diff --git a/.changeset/easy-experts-peel.md b/.changeset/easy-experts-peel.md
new file mode 100644
index 00000000..026547ad
--- /dev/null
+++ b/.changeset/easy-experts-peel.md
@@ -0,0 +1,5 @@
+---
+"@upstash/box": patch
+---
+
+Include TypeScript source and documentation in the npm package.
diff --git a/.gitignore b/.gitignore
index 0bfe72f7..1a694c00 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,3 +44,6 @@ temp/
 
 # pnpm's local content-addressable store, when one is configured in-repo
 .pnpm-store/
+
+# Documentation fetched during packing
+/packages/sdk/docs/
diff --git a/packages/sdk/.prettierignore b/packages/sdk/.prettierignore
index 4d6880d3..a519164c 100644
--- a/packages/sdk/.prettierignore
+++ b/packages/sdk/.prettierignore
@@ -1,2 +1,3 @@
 dist
 examples
+docs/
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 06ba61f4..b3e19ec0 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -26,6 +26,10 @@ console.log(run.result);
 await box.delete();
 ```
 
+## Docs
+
+The npm package includes TypeScript source in `node_modules/@upstash/box/src/` and documentation in `node_modules/@upstash/box/docs/`. Start with `src/index.ts` to explore the source.
+
 ## Authentication
 
 Pass `apiKey` in the config or set the `UPSTASH_BOX_API_KEY` environment variable.
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 4391a9c2..d8725bc8 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -25,7 +25,8 @@
     "format:check": "prettier --check .",
     "lint": "prettier --check . --write",
     "ci:lint": "prettier --check .",
-    "prepublishOnly": "node scripts/gen-version.mjs && npm run build"
+    "prepublishOnly": "node scripts/gen-version.mjs && npm run build",
+    "prepack": "giget gh:upstash/docs/box docs --force-clean 1>&2"
   },
   "keywords": [
     "upstash",
@@ -43,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^20.10.0",
     "@types/ws": "^8.18.1",
+    "giget": "3.3.1",
     "prettier": "^3.8.1",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
@@ -51,7 +53,15 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "docs",
+    "!src/**/*.test.*",
+    "!src/**/*.test-d.*",
+    "!src/**/*.spec.*",
+    "!src/**/test-utils.*",
+    "!src/**/__tests__/**",
+    "!src/**/__snapshots__/**"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -63,5 +73,8 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
+  },
+  "directories": {
+    "doc": "./docs"
   }
 }
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 7109a249..d5397ea2 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -374,6 +374,8 @@ export class Run<T = string> {
 
   /**
    * Cancel a running execution.
+   *
+   * @see node_modules/@upstash/box/docs/overall/shell.mdx
    */
   async cancel(): Promise<void> {
     this._abortController?.abort();
@@ -385,6 +387,8 @@ export class Run<T = string> {
 
   /**
    * Retrieve logs for this run.
+   *
+   * @see node_modules/@upstash/box/docs/overall/shell.mdx
    */
   async logs(): Promise<RunLog[]> {
     const allLogs = await this._box.logs();
@@ -481,6 +485,8 @@ export class StreamRun<T = string, C = Chunk> extends Run<T> implements AsyncIte
  * `box.browser.listTabs()`, or `box.browser.getTab(id)`. All page operations
  * run against this specific tab. `screenshot`/`extract`/`observe`/`act`/`run`
  * all work headless, without a visible screen.
+ *
+ * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
  */
 export class Tab {
   /** CDP target id of this tab. */
@@ -499,7 +505,11 @@ export class Tab {
     this.title = init.title;
   }
 
-  /** Navigate this tab to a URL and return the page content. */
+  /**
+   * Navigate this tab to a URL and return the page content.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
+   */
   goto(url: string): Promise<BrowserContent> {
     return this.box._request<BrowserContent>("POST", `/v2/box/${this.box.id}/browser/goto`, {
       body: { url, tab: this.id },
@@ -507,7 +517,11 @@ export class Tab {
     });
   }
 
-  /** Read this tab's current title, URL, text, and links. */
+  /**
+   * Read this tab's current title, URL, text, and links.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/reading-pages.mdx
+   */
   content(): Promise<BrowserContent> {
     return this.box._request<BrowserContent>(
       "GET",
@@ -516,7 +530,11 @@ export class Tab {
     );
   }
 
-  /** Capture this tab as PNG bytes, or as a base64 string when requested. */
+  /**
+   * Capture this tab as PNG bytes, or as a base64 string when requested.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/reading-pages.mdx
+   */
   screenshot(options: BrowserScreenshotOptions & { type: "base64" }): Promise<string>;
   screenshot(options?: BrowserScreenshotOptions & { type?: "png" }): Promise<Uint8Array>;
   screenshot(options: BrowserScreenshotOptions): Promise<Uint8Array | string>;
@@ -536,7 +554,11 @@ export class Tab {
     return resp.data;
   }
 
-  /** Extract schema-validated structured data from this tab (metered). */
+  /**
+   * Extract schema-validated structured data from this tab (metered).
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/reading-pages.mdx
+   */
   async extract<T>(
     instruction: string,
     schema: BrowserExtractSchema<T>,
@@ -561,7 +583,11 @@ export class Tab {
     return schema.parse(resp.data);
   }
 
-  /** List actionable page elements matching an instruction (metered). */
+  /**
+   * List actionable page elements matching an instruction (metered).
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/ai-actions.mdx
+   */
   async observe(
     instruction: string,
     options?: BrowserExtractOptions,
@@ -577,9 +603,17 @@ export class Tab {
     return { elements: resp.elements ?? [] };
   }
 
-  /** Resolve and execute one natural-language action on this tab (metered). */
+  /**
+   * Resolve and execute one natural-language action on this tab (metered).
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/ai-actions.mdx
+   */
   async act(instruction: string, options?: BrowserExtractOptions): Promise<BrowserActResult>;
-  /** Replay a pre-resolved `observe()` action with no LLM call and no key (`model` ignored). */
+  /**
+   * Replay a pre-resolved `observe()` action with no LLM call and no key (`model` ignored).
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/ai-actions.mdx
+   */
   async act(action: BrowserAction): Promise<BrowserActResult>;
   async act(
     instructionOrAction: string | BrowserAction,
@@ -623,17 +657,26 @@ export class Tab {
    * Live-view URL for this tab (authenticated via a token in the URL). Open it
    * directly or embed it in an iframe — the page renders the tab live via CDP
    * screencast. View-only: frames flow out, no input goes in.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/live-view.mdx
    */
   liveViewUrl(): Promise<string> {
     return this.box._browserLiveViewUrl(this.id);
   }
 
-  /** Close this tab. */
+  /**
+   * Close this tab.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
+   */
   async close(): Promise<void> {
     await this.box._request("DELETE", `/v2/box/${this.box.id}/browser/tabs/${this.id}`);
   }
 }
 
+/**
+ * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
+ */
 export class Box<TProvider = unknown> {
   readonly id: string;
 
@@ -643,43 +686,91 @@ export class Box<TProvider = unknown> {
   /** Whether this box is configured as keep-alive. */
   readonly keepAlive: boolean;
 
-  /** Current network access policy for this box. */
+  /**
+   * Current network access policy for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/network-policy.mdx
+   */
   get networkPolicy(): NetworkPolicy {
     return this._networkPolicy;
   }
 
-  /** Agent operations namespace */
+  /**
+   * Agent operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/agent.mdx
+   */
   readonly agent: {
+    /**
+     * @see node_modules/@upstash/box/docs/overall/agent.mdx
+     */
     run<T>(
       options: RunOptions<T, TProvider> & {
         responseSchema: RunOptions<T, TProvider>["responseSchema"];
       },
     ): Promise<Run<T>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/agent.mdx
+     */
     run(options: RunOptions<undefined, TProvider>): Promise<Run<string>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/agent.mdx
+     */
     stream(options: StreamOptions<TProvider>): Promise<StreamRun<string, Chunk>>;
   };
 
-  /** File operations namespace */
+  /**
+   * File operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/files.mdx
+   */
   readonly files: {
     /**
      * Read a file. Passing `length` reads a bounded byte range starting at
      * `offset` (default 0) instead of the whole file; the server rejects a
      * `length` above 8 MiB.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     read: (
       path: string,
       options?: { encoding?: "base64"; offset?: number; length?: number },
     ) => Promise<string>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     write: (options: { path: string; content: string; encoding?: "base64" }) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     list: (path?: string) => Promise<FileEntry[]>;
-    /** Return filesystem metadata for a path. `follow` dereferences a final symlink (default: lstat). */
+    /**
+     * Return filesystem metadata for a path. `follow` dereferences a final symlink (default: lstat).
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     stat: (path: string, options?: { follow?: boolean }) => Promise<FileStat>;
-    /** Create a directory. `parents` mirrors `mkdir -p`. */
+    /**
+     * Create a directory. `parents` mirrors `mkdir -p`.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     mkdir: (path: string, options?: { parents?: boolean }) => Promise<void>;
-    /** Move/rename a path. */
+    /**
+     * Move/rename a path.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     rename: (from: string, to: string) => Promise<void>;
-    /** Remove a path. `recursive` is required to remove a directory. */
+    /**
+     * Remove a path. `recursive` is required to remove a directory.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     remove: (path: string, options?: { recursive?: boolean }) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     upload: (files: UploadFileEntry[]) => Promise<void>;
     /**
      * Download files from the box to the local filesystem.
@@ -695,47 +786,129 @@ export class Box<TProvider = unknown> {
      * // Download the entire workspace
      * await box.files.download();
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     download: (options?: { folder?: string }) => Promise<void>;
   };
 
-  /** Execution namespace — shell commands and inline code */
+  /**
+   * Execution namespace — shell commands and inline code
+   *
+   * @see node_modules/@upstash/box/docs/overall/shell.mdx
+   */
   readonly exec: {
+    /**
+     * @see node_modules/@upstash/box/docs/overall/shell.mdx
+     */
     command: (command: string) => Promise<Run<string>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/shell.mdx
+     */
     code: (options: CodeExecutionOptions) => Promise<Run<string>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
+     */
     stream: (command: string) => Promise<StreamRun<string, ExecStreamChunk>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
+     */
     streamCode: (options: CodeExecutionOptions) => Promise<StreamRun<string, ExecStreamChunk>>;
     /**
      * Open a live, interactive command session over a WebSocket: stdin,
      * streamed stdout/stderr, resize, and signals. Node-only. See
      * {@link ExecSessionOptions}.
+     *
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
      */
     session: (options: ExecSessionOptions) => Promise<ExecSessionHandle>;
   };
 
-  /** Schedule operations namespace */
+  /**
+   * Schedule operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+   */
   readonly schedule: {
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     exec: (options: ExecScheduleOptions) => Promise<Schedule>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     agent: (options: AgentScheduleOptions<TProvider>) => Promise<Schedule>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     list: () => Promise<Schedule[]>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     get: (id: string) => Promise<Schedule>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     update: (id: string, options: UpdateScheduleOptions<TProvider>) => Promise<Schedule>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     pause: (id: string) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     resume: (id: string) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+     */
     delete: (id: string) => Promise<void>;
   };
 
-  /** Git operations namespace */
+  /**
+   * Git operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/git.mdx
+   */
   readonly git: {
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     clone: (options: GitCloneOptions) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     diff: () => Promise<string>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     status: () => Promise<string>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     commit: (options: GitCommitOptions) => Promise<GitCommitResult>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     updateConfig: (options: GitConfigUpdateOptions) => Promise<GitConfig>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     push: (options?: { branch?: string }) => Promise<void>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     createPR: (options: GitPROptions) => Promise<PullRequest>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     createIssue: (options: GitIssueOptions) => Promise<Issue>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     exec: (options: GitExecOptions) => Promise<GitExecResult>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/git.mdx
+     */
     checkout: (options: GitCheckoutOptions) => Promise<void>;
   };
 
@@ -765,34 +938,74 @@ export class Box<TProvider = unknown> {
    * tabs. All page operations (`goto`, `content`, `screenshot`, `extract`,
    * `observe`, `act`, `run`, `close`) live on the {@link Tab} handle returned
    * here.
+   *
+   * @see node_modules/@upstash/box/docs/overall/browser/overview.mdx
    */
   readonly browser: {
     tab: {
-      /** Open a tab, navigate it, and wait for the requested lifecycle state. */
+      /**
+       * Open a tab, navigate it, and wait for the requested lifecycle state.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
+       */
       create: (url: string, options?: BrowserTabCreateOptions) => Promise<Tab>;
     };
-    /** List the box's open tabs as handles. */
+    /**
+     * List the box's open tabs as handles.
+     *
+     * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
+     */
     listTabs: () => Promise<Tab[]>;
-    /** Address an existing tab by its CDP target id — no network call. */
+    /**
+     * Address an existing tab by its CDP target id — no network call.
+     *
+     * @see node_modules/@upstash/box/docs/overall/browser/tabs.mdx
+     */
     getTab: (id: string) => Tab;
-    /** Return an authenticated CDP WebSocket URL for Playwright, Puppeteer, or Stagehand. */
+    /**
+     * Return an authenticated CDP WebSocket URL for Playwright, Puppeteer, or Stagehand.
+     *
+     * @see node_modules/@upstash/box/docs/overall/browser/connect.mdx
+     */
     cdpUrl: () => Promise<string>;
     /**
      * Session recordings — capture the browser (all tabs, follows the
      * foreground) to a replayable HLS video with run/tab-switch chapters.
      * Recordings auto-stop after `maxDurationSeconds` (max 10 minutes) or
      * after 3 minutes of no on-screen activity.
+     *
+     * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
      */
     recordings: {
-      /** Start capturing. One active recording per box. */
+      /**
+       * Start capturing. One active recording per box.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
+       */
       start: (options?: BrowserRecordingOptions) => Promise<BrowserRecordingHandle>;
-      /** Stop the active recording and return its metadata. */
+      /**
+       * Stop the active recording and return its metadata.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
+       */
       stop: () => Promise<BrowserRecording>;
-      /** List this box's recordings, newest first. */
+      /**
+       * List this box's recordings, newest first.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
+       */
       list: () => Promise<BrowserRecording[]>;
-      /** Fetch one recording's metadata. */
+      /**
+       * Fetch one recording's metadata.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
+       */
       get: (recordingId: string) => Promise<BrowserRecording>;
-      /** Download a recording's video (MP4, or MPEG-TS for pre-MP4 recordings) to a local file; returns the path written. */
+      /**
+       * Download a recording's video (MP4, or MPEG-TS for pre-MP4 recordings) to a local file; returns the path written.
+       *
+       * @see node_modules/@upstash/box/docs/overall/browser/recordings.mdx
+       */
       download: (recordingId: string, options?: { path?: string }) => Promise<string>;
     };
   };
@@ -965,6 +1178,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Create a new sandboxed box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   static async create<TProvider = unknown>(config?: BoxConfig): Promise<Box<TProvider>> {
     const apiKey = config?.apiKey ?? process.env.UPSTASH_BOX_API_KEY;
@@ -1053,6 +1268,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * List all boxes for the authenticated user.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   static async list(options?: ListOptions): Promise<BoxData[]> {
     const apiKey = options?.apiKey ?? process.env.UPSTASH_BOX_API_KEY;
@@ -1162,6 +1379,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Get an existing box by ID
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   static async get<TProvider = unknown>(
     boxId: string,
@@ -1202,6 +1421,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Get an existing box by name
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   static getByName = Box.get;
 
@@ -2470,6 +2691,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Get the current box status.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async getStatus(): Promise<{ status: string }> {
     return this._request<{ status: string }>("GET", `/v2/box/${this.id}/status`);
@@ -2490,6 +2713,8 @@ export class Box<TProvider = unknown> {
    * Update the custom harness configured for this box.
    *
    * The box must have been created with `agent.harness: Agent.Custom`.
+   *
+   * @see node_modules/@upstash/box/docs/overall/custom-agent.mdx
    */
   async configureCustomHarness(customHarness: CustomHarnessConfig): Promise<void> {
     if (this._agent !== Agent.Custom) {
@@ -2503,6 +2728,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Update the network access policy for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/network-policy.mdx
    */
   async updateNetworkPolicy(policy: NetworkPolicy): Promise<void> {
     await this._request("PUT", `/v2/box/${this.id}/config/network-policy`, {
@@ -2513,6 +2740,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Read the current init command.
+   *
+   * @see node_modules/@upstash/box/docs/overall/keep-alive.mdx
    */
   async getInitCommand(): Promise<string> {
     const data = await this._request<{ init_command?: string }>(
@@ -2525,6 +2754,8 @@ export class Box<TProvider = unknown> {
   /**
    * Set or replace the init command. On a paused box the change is stored and
    * applied on the next resume.
+   *
+   * @see node_modules/@upstash/box/docs/overall/keep-alive.mdx
    */
   async setInitCommand(initCommand: string): Promise<void> {
     if (!initCommand) {
@@ -2537,6 +2768,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Delete the init command.
+   *
+   * @see node_modules/@upstash/box/docs/overall/keep-alive.mdx
    */
   async deleteInitCommand(): Promise<void> {
     await this._request("DELETE", `/v2/box/${this.id}/startup`);
@@ -2544,6 +2777,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Pause the box (release compute, preserve state).
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async pause(): Promise<void> {
     if (this.keepAlive) {
@@ -2554,6 +2789,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Resume a paused box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async resume(): Promise<void> {
     await this._request("POST", `/v2/box/${this.id}/resume`);
@@ -2561,6 +2798,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Delete this box permanently.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async delete(): Promise<void> {
     await this._request("DELETE", `/v2/box/${this.id}`);
@@ -2569,6 +2808,8 @@ export class Box<TProvider = unknown> {
   /**
    * Save workspace state as a snapshot for later restore.
    * Creates the snapshot asynchronously and polls until ready.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async snapshot(options: { name: string }): Promise<Snapshot> {
     const data = await this._request<Snapshot>("POST", `/v2/box/${this.id}/snapshots`, {
@@ -2600,6 +2841,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * List all snapshots for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async listSnapshots(): Promise<Snapshot[]> {
     const data = await this._request<{ snapshots: Snapshot[] }>(
@@ -2611,6 +2854,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Delete a snapshot.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async deleteSnapshot(snapshotId: string): Promise<void> {
     await this._request("DELETE", `/v2/box/${this.id}/snapshots/${snapshotId}`);
@@ -2618,6 +2863,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Create a new box from a saved snapshot.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   static async fromSnapshot<TProvider = unknown>(
     snapshotId: string,
@@ -2700,6 +2947,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * Get structured logs for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async logs(options?: { offset?: number; limit?: number }): Promise<LogEntry[]> {
     const params = new URLSearchParams();
@@ -2712,6 +2961,8 @@ export class Box<TProvider = unknown> {
 
   /**
    * List all runs for this box, newest first.
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   async listRuns(): Promise<BoxRunData[]> {
     const data = await this._request<{ runs: BoxRunData[] }>("GET", `/v2/box/${this.id}/runs`);
@@ -3200,6 +3451,8 @@ export class Box<TProvider = unknown> {
   /**
    * Expose a port on a public URL. A request to the URL resumes the box if it
    * is paused and is held until the port is listening.
+   *
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
    */
   async getPublicURL(
     port: number,
@@ -3214,6 +3467,9 @@ export class Box<TProvider = unknown> {
     });
   }
 
+  /**
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
+   */
   async listPublicURLs(): Promise<{ publicURLs: PublicURLListItem[] }> {
     const data = await this._request<{ previews: PublicURLListItem[] }>(
       "GET",
@@ -3222,11 +3478,18 @@ export class Box<TProvider = unknown> {
     return { publicURLs: data.previews };
   }
 
+  /**
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
+   */
   async deletePublicURL(port: number): Promise<void> {
     await this._request("DELETE", `/v2/box/${this.id}/preview/${port}`);
   }
 
-  /** @deprecated Use `getPublicURL` instead. */
+  /**
+   * @deprecated Use `getPublicURL` instead.
+   *
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
+   */
   async getPreviewUrl(
     port: number,
     options?: { bearerToken?: boolean; basicAuth?: boolean },
@@ -3234,13 +3497,21 @@ export class Box<TProvider = unknown> {
     return this.getPublicURL(port, options);
   }
 
-  /** @deprecated Use `listPublicURLs` instead. */
+  /**
+   * @deprecated Use `listPublicURLs` instead.
+   *
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
+   */
   async listPreviews(): Promise<{ previews: PublicURLListItem[] }> {
     const data = await this.listPublicURLs();
     return { previews: data.publicURLs };
   }
 
-  /** @deprecated Use `deletePublicURL` instead. */
+  /**
+   * @deprecated Use `deletePublicURL` instead.
+   *
+   * @see node_modules/@upstash/box/docs/overall/preview.mdx
+   */
   async deletePreview(port: number): Promise<void> {
     await this.deletePublicURL(port);
   }
@@ -3262,6 +3533,8 @@ export class Box<TProvider = unknown> {
  * console.log(run.result); // "hello"
  * await box.delete();
  * ```
+ *
+ * @see node_modules/@upstash/box/docs/overall/ephemeral-box.mdx
  */
 export class EphemeralBox {
   readonly id: string;
@@ -3269,7 +3542,11 @@ export class EphemeralBox {
   /** Unix timestamp (seconds) when this box will be auto-deleted. */
   readonly expiresAt: number;
 
-  /** File operations namespace */
+  /**
+   * File operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/files.mdx
+   */
   readonly files: {
     /**
      * Read a file from the box. Passing `length` reads a bounded byte range
@@ -3282,6 +3559,8 @@ export class EphemeralBox {
      * const b64 = await box.files.read("image.png", { encoding: "base64" });
      * const head = await box.files.read("big.log", { length: 64 * 1024 });
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     read: (
       path: string,
@@ -3294,6 +3573,8 @@ export class EphemeralBox {
      * ```ts
      * await box.files.write({ path: "hello.txt", content: "Hello!" });
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     write: (options: { path: string; content: string; encoding?: "base64" }) => Promise<void>;
     /**
@@ -3303,15 +3584,33 @@ export class EphemeralBox {
      * ```ts
      * const files = await box.files.list("src");
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     list: (path?: string) => Promise<FileEntry[]>;
-    /** Return filesystem metadata for a path. `follow` dereferences a final symlink (default: lstat). */
+    /**
+     * Return filesystem metadata for a path. `follow` dereferences a final symlink (default: lstat).
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     stat: (path: string, options?: { follow?: boolean }) => Promise<FileStat>;
-    /** Create a directory. `parents` mirrors `mkdir -p`. */
+    /**
+     * Create a directory. `parents` mirrors `mkdir -p`.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     mkdir: (path: string, options?: { parents?: boolean }) => Promise<void>;
-    /** Move/rename a path. */
+    /**
+     * Move/rename a path.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     rename: (from: string, to: string) => Promise<void>;
-    /** Remove a path. `recursive` is required to remove a directory. */
+    /**
+     * Remove a path. `recursive` is required to remove a directory.
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
+     */
     remove: (path: string, options?: { recursive?: boolean }) => Promise<void>;
     /**
      * Upload local files to the box.
@@ -3320,6 +3619,8 @@ export class EphemeralBox {
      * ```ts
      * await box.files.upload([{ path: "./local.txt", destination: "remote.txt" }]);
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     upload: (files: UploadFileEntry[]) => Promise<void>;
     /**
@@ -3329,25 +3630,49 @@ export class EphemeralBox {
      * ```ts
      * await box.files.download({ folder: "src" });
      * ```
+     *
+     * @see node_modules/@upstash/box/docs/overall/files.mdx
      */
     download: (options?: { folder?: string }) => Promise<void>;
   };
 
-  /** Execution namespace — shell commands and inline code */
+  /**
+   * Execution namespace — shell commands and inline code
+   *
+   * @see node_modules/@upstash/box/docs/overall/shell.mdx
+   */
   readonly exec: {
+    /**
+     * @see node_modules/@upstash/box/docs/overall/shell.mdx
+     */
     command: (command: string) => Promise<Run<string>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/shell.mdx
+     */
     code: (options: CodeExecutionOptions) => Promise<Run<string>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
+     */
     stream: (command: string) => Promise<StreamRun<string, ExecStreamChunk>>;
+    /**
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
+     */
     streamCode: (options: CodeExecutionOptions) => Promise<StreamRun<string, ExecStreamChunk>>;
     /**
      * Open a live, interactive command session over a WebSocket: stdin,
      * streamed stdout/stderr, resize, and signals. Node-only. See
      * {@link ExecSessionOptions}.
+     *
+     * @see node_modules/@upstash/box/docs/overall/live-sessions.mdx
      */
     session: (options: ExecSessionOptions) => Promise<ExecSessionHandle>;
   };
 
-  /** Schedule operations namespace */
+  /**
+   * Schedule operations namespace
+   *
+   * @see node_modules/@upstash/box/docs/overall/schedules.mdx
+   */
   readonly schedule: Box["schedule"];
 
   private _box: Box;
@@ -3366,7 +3691,11 @@ export class EphemeralBox {
    * The current working directory tracked in the SDK.
    * Every new session starts at `/workspace/home`.
    */
-  /** Current network access policy for this box. */
+  /**
+   * Current network access policy for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/network-policy.mdx
+   */
   get networkPolicy(): NetworkPolicy {
     return this._box.networkPolicy;
   }
@@ -3388,6 +3717,8 @@ export class EphemeralBox {
 
   /**
    * Get the current box status.
+   *
+   * @see node_modules/@upstash/box/docs/overall/ephemeral-box.mdx
    */
   async getStatus(): Promise<{ status: string }> {
     return this._box.getStatus();
@@ -3395,6 +3726,8 @@ export class EphemeralBox {
 
   /**
    * Delete this ephemeral box before its TTL expires.
+   *
+   * @see node_modules/@upstash/box/docs/overall/ephemeral-box.mdx
    */
   async delete(): Promise<void> {
     return this._box.delete();
@@ -3403,6 +3736,8 @@ export class EphemeralBox {
   /**
    * Save workspace state as a snapshot for later restore.
    * Creates the snapshot asynchronously and polls until ready.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async snapshot(options: { name: string }): Promise<Snapshot> {
     return this._box.snapshot(options);
@@ -3410,6 +3745,8 @@ export class EphemeralBox {
 
   /**
    * List all snapshots for this box.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async listSnapshots(): Promise<Snapshot[]> {
     return this._box.listSnapshots();
@@ -3417,6 +3754,8 @@ export class EphemeralBox {
 
   /**
    * Delete a snapshot.
+   *
+   * @see node_modules/@upstash/box/docs/overall/snapshots.mdx
    */
   async deleteSnapshot(snapshotId: string): Promise<void> {
     return this._box.deleteSnapshot(snapshotId);
@@ -3439,6 +3778,8 @@ export class EphemeralBox {
    * // Default runtime and max TTL
    * const box = await EphemeralBox.create();
    * ```
+   *
+   * @see node_modules/@upstash/box/docs/overall/ephemeral-box.mdx
    */
   static async create(config?: EphemeralBoxConfig): Promise<EphemeralBox> {
     const apiKey = config?.apiKey ?? process.env.UPSTASH_BOX_API_KEY;
@@ -3500,6 +3841,8 @@ export class EphemeralBox {
    * ```ts
    * const box = await EphemeralBox.fromSnapshot("snap-abc123", { ttl: 3600 });
    * ```
+   *
+   * @see node_modules/@upstash/box/docs/overall/ephemeral-box.mdx
    */
   static async fromSnapshot(
     snapshotId: string,
@@ -3559,6 +3902,8 @@ export class EphemeralBox {
 
   /**
    * Get an existing ephemeral box by name
+   *
+   * @see node_modules/@upstash/box/docs/overall/how-it-works.mdx
    */
   static getByName = Box.get;
 
diff --git a/packages/sdk/src/custom-harness.ts b/packages/sdk/src/custom-harness.ts
index 3c545539..aea6b976 100644
--- a/packages/sdk/src/custom-harness.ts
+++ b/packages/sdk/src/custom-harness.ts
@@ -110,6 +110,8 @@ function createEmitter(write: (chunk: string) => void): CustomHarnessEmitter {
  *   return { output, inputTokens: prompt.split(/\s+/).length, outputTokens: output.split(/\s+/).length };
  * });
  * ```
+ *
+ * @see node_modules/@upstash/box/docs/overall/custom-agent.mdx
  */
 export async function runCustomHarness(
   handler: CustomHarnessHandler,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 95035490..0e40deb6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -114,6 +114,9 @@ importers:
       '@types/ws':
         specifier: ^8.18.1
         version: 8.18.1
+      giget:
+        specifier: 3.3.1
+        version: 3.3.1
       prettier:
         specifier: ^3.8.1
         version: 3.8.1
@@ -1092,6 +1095,10 @@ packages:
   get-tsconfig@4.13.6:
     resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
 
+  giget@3.3.1:
+    resolution: {integrity: sha512-r+mvuDjrjMpsdw46Kmeydb8bdHm7wOKw8wNBtTndkjbPjgAp5oUJUxRE76wZFknxIPokfWvep2qSXK37aXE6zg==}
+    hasBin: true
+
   glob-parent@5.1.2:
     resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
     engines: {node: '>= 6'}
@@ -2700,6 +2707,8 @@ snapshots:
     dependencies:
       resolve-pkg-maps: 1.0.0
 
+  giget@3.3.1: {}
+
   glob-parent@5.1.2:
     dependencies:
       is-glob: 4.0.3