docs: update product guides and trim redundant instructions

TODO.md

@@ -0,0 +1,14 @@
+# TODO
+
+## 2026-09-23 09:11 — Weekly docs update
+
+- [ ] Review the committed docs/update-2026-09-23 branch; the commit message contains the PR-by-PR audit.
+- [ ] Restore or update the automation’s missing .github/prompts/update-docs.md pointer to the live Notion SOP.
+
+## 2026-09-23 09:28 — Weekly docs update
+
+- [ ] Review the follow-up correctness and trimming commit, including the remote-port and privacy FAQ corrections.
+
+## 2026-09-23 10:41 — Weekly docs update
+
+- [ ] Review the broader trimming pass across onboarding, orchestration, ports, editor, agent status, tasks, and PR guides.

apps/docs/content/docs/agent-integration.mdx

@@ -38,7 +38,13 @@ Superset includes a built-in chat panel for AI interactions without leaving the
 
 - Use the model picker to choose supported models and connect providers
 - Chat session titles are generated automatically from the conversation
-- Use the thinking level control to set reasoning effort: **Off**, **Low**, **Medium**, **High**, or **Max**
+- Use the thinking level control to adjust reasoning effort for the selected model
+
+## Models and Reasoning Effort
+
+The model pickers include **GPT-6 Sol** and **GPT-6 Luna** for Codex and
+Superset Chat, and **Opus 5.5** for Claude Code and Superset Chat. Available
+reasoning levels depend on the agent and model; see the [launch options](/cli/cli-reference#agent-effort-levels).
 
 ## Agent Settings
 

apps/docs/content/docs/agent-status.mdx

@@ -3,11 +3,9 @@ title: Agent Status & Notifications
 description: How Superset knows what your agents are doing, and how it tells you
 ---
 
-Running many agents only works if you can tell who needs you.
-
 ## The Activity Strip
 
-Each workspace in the sidebar shows a compact activity strip with what's actually happening:
+Each workspace in the sidebar shows an activity strip:
 
 - **Running agents and open ports** appear inline on the workspace item
 - **Running and PR state persist across restarts**
@@ -30,10 +28,8 @@ The hooks no-op outside Superset terminals (they check for a Superset-supplied e
 
 ## Dock Badge
 
-The macOS dock icon shows a badge for workspaces with unread activity or that need your attention, so you can step away and still know when an agent wants you.
+The macOS dock icon shows a badge for workspaces with unread activity or that need your attention.
 
 ![Dock icon showing an attention badge](/images/dock-badge.png)
 
 macOS only shows dock badges when Superset has notification permission. If you don't see badges, check **System Settings → Notifications → Superset**.
-
-The intended rhythm: fan work out, leave the app in the background, and come back on notification or dock badge rather than watching terminals.

apps/docs/content/docs/browser.mdx

@@ -46,11 +46,11 @@ Click **Design** in the browser toolbar to arm an element picker inside the page
 
 When Superset detects a port in use (e.g. `localhost:3000`), clicking its external link icon opens it in an in-app browser tab instead of the system browser.
 
-For workspaces on a [remote host](/remote-access), ports listen on that host and aren't forwarded locally; see [forward a port yourself](/ports#forward-a-port-yourself).
+For workspaces on a [remote host](/remote-access), the desktop app forwards detected ports while that workspace is selected. See [Remote Access](/remote-access#ports-on-a-remote-host) for requirements and port conflicts.
 
 ## Drive it from the CLI and agents
 
-Browser panes can be driven programmatically with the [`superset browser`](/cli/cli-reference#browser) commands, so an agent can open a page, read it, screenshot it, and interact with it — in the same pane you're watching.
+Browser panes can be driven programmatically with the [`superset browser`](/cli/cli-reference#browser) commands, so an agent can open a page, read it, screenshot it, and interact with it in the same pane you're watching.
 
 ```bash
 # Open a page and get its pane id back
@@ -62,31 +62,31 @@ superset browser screenshot --workspace <id> --pane <paneId> --out shot.png
 superset browser console --workspace <id> --pane <paneId>
 ```
 
-For full interaction — clicking, typing, scrolling, form flows — `superset browser cdp` prints a raw [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) WebSocket endpoint you can point a browser-use / Playwright-class client at. The endpoint drives only that pane's page (never the Superset app itself), and pane operations are scoped to their workspace.
+For full interaction (clicking, typing, scrolling, form flows), `superset browser cdp` prints a raw [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) WebSocket endpoint you can point a browser-use / Playwright-class client at. The endpoint drives only that pane's page (never the Superset app itself), and pane operations are scoped to their workspace.
 
-Agents pick this up automatically through the [`superset:browser` skill](/skills). A pane runs against the browser's real, logged-in session — agents are instructed to treat it accordingly and to confirm before consequential actions.
+Agents pick this up automatically through the [`superset:browser` skill](/skills). A pane runs against the browser's real, logged-in session; agents are instructed to treat it accordingly and to confirm before consequential actions.
 
 ## Pane or standalone browser?
 
-The `superset:browser` skill is engine-generic with the in-app pane as the default: when a page is (or can be) open in a workspace pane — previewing a dev server, verifying UI you're watching, clicking through a flow — agents use the `superset browser` commands above.
+The `superset:browser` skill is engine-generic with the in-app pane as the default: when a page is (or can be) open in a workspace pane (previewing a dev server, verifying UI you're watching, clicking through a flow), agents use the `superset browser` commands above.
 
 Some targets are out of the panes' reach: a real Chrome window outside Superset, a host running without the desktop app attached, or work that needs an isolated or cloud browser. For those, the skill routes to [Browser Use 3.0](https://docs.browser-use.com/open-source/browser-use-cli) as a second engine.
 
 ### Browser Use 3.0
 
 <Callout type="info" title="Optional third-party software">
-	Browser Use is built by [Browser Use](https://browser-use.com), not by Superset, and nothing in Superset requires it — the in-app pane engine works with no extra install. Only add it if you want standalone automation, and note that attaching it to your running Chrome hands agents your signed-in sessions.
+	Browser Use is built by [Browser Use](https://browser-use.com), not by Superset, and nothing in Superset requires it; the in-app pane engine works with no extra install. Only add it if you want standalone automation, and note that attaching it to your running Chrome hands agents your signed-in sessions.
 </Callout>
 
-Browser Use 3.0 is a CLI that lets agents execute Python against a browser over the Chrome DevTools Protocol. It isn't bundled with Superset — agents check for it and ask before installing. To install it yourself (requires [uv](https://docs.astral.sh/uv/)) so the `browser-use` command lands on your `PATH`:
+Browser Use 3.0 is a CLI that lets agents execute Python against a browser over the Chrome DevTools Protocol. It isn't bundled with Superset; agents check for it and ask before installing. To install it yourself (requires [uv](https://docs.astral.sh/uv/)) so the `browser-use` command lands on your `PATH`:
 
 ```bash
 uv tool install browser-use
 browser-use --help
 ```
 
-You can also run it ephemerally with `uvx --from 'browser-use[cli]' browser-use …`, but that doesn't add `browser-use` to your `PATH` — each call needs the full `uvx --from` prefix.
+You can also run it ephemerally with `uvx --from 'browser-use[cli]' browser-use …`, but that doesn't add `browser-use` to your `PATH`; each call needs the full `uvx --from` prefix.
 
-By default it attaches to your running Chrome — your real, signed-in profile — so the skill requires your explicit consent before taking that path; otherwise agents use a scratch browser or a Browser Use cloud browser (which bills until stopped, so they ask first and stop it after). `browser-use --doctor` diagnoses connection problems, and `browser-use skill` prints the engine's own usage reference.
+By default it attaches to your running Chrome (your real, signed-in profile), so the skill requires your explicit consent before taking that path; otherwise agents use a scratch browser or a Browser Use cloud browser (which bills until stopped, so they ask first and stop it after). `browser-use --doctor` diagnoses connection problems, and `browser-use skill` prints the engine's own usage reference.
 
 Browser Use can also drive an in-app pane: point it at the pane's endpoint from `superset browser cdp` (as `BU_CDP_WS`) and the pane presents itself as a single page target. For panes the `superset browser` verbs are the simpler default, but this lets Browser Use's harness reach the same pane when you want it.

apps/docs/content/docs/cli/cli-reference.mdx

@@ -845,7 +845,7 @@ superset workspaces get --field branch   # inside a workspace
 	output="Workspace"
 >
 Update a workspace on its host (default: this machine). `--tag` replaces the
-whole tag set — tagging is how workspaces group into sidebar folders, so
+whole tag set: tagging is how workspaces group into sidebar folders, so
 retagging moves the workspace between folders.
 
 ```bash
@@ -982,13 +982,38 @@ superset agents create --workspace ws_… --agent codex --prompt "Review this di
 superset agents create --workspace ws_… --agent claude --resume-session 0b7c…
 ```
 
+</Command>
+
+<Command
+	name="superset agents read"
+	options={[
+		{ flag: "--workspace <id>", required: true, description: "Workspace ID." },
+		{ flag: "--terminal <id>", required: true, description: "Terminal ID, returned as sessionId by agents create." },
+		{ flag: "--host <id>", description: "Target host. Mutually exclusive with --local." },
+		{ flag: "--local", description: "Read from this machine." },
+	]}
+>
+Read the agent's saved transcript, beyond the visible screen returned by
+`terminals read`. Without `--host` or `--local`, the target defaults to cloud
+when your account has cloud workspaces, otherwise this machine. The command
+fails if Superset cannot read a transcript for that terminal.
+
+```bash
+superset agents read --local --workspace <workspace-id> --terminal <terminal-id>
+```
+
+<CommandReturns>
+The transcript object in JSON mode, or its text in human-readable mode.
+</CommandReturns>
+</Command>
+
 #### Agent models
 
 Model is an explicit override for one launch. If you omit `--model`, Superset
 passes no model flag and the agent uses its own configured default. Ids match
 the desktop model picker: Claude takes a family alias (`fable`, `opus`,
 `sonnet`, `haiku`) that tracks the newest release, or a pinned id such as
-`claude-opus-4-8`. The host rejects an unknown id before launching the agent,
+`claude-opus-5-5`. Codex includes `gpt-6-sol` and `gpt-6-luna`. The host rejects an unknown id before launching the agent,
 and the error names every id that agent accepts. Agents without a model
 picker, including Superset chat, reject an explicit model override.
 
@@ -1002,14 +1027,15 @@ The host rejects unsupported values before launching the agent.
 | --- | --- |
 | Claude | `low`, `medium`, `high`, `xhigh`, `max` |
 | Amp | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
-| Codex | `low`, `medium`, `high`, `xhigh` |
+| Codex | `low`, `medium`, `high`, `xhigh`; `max` and `ultra` depend on the selected model |
 | Mastracode | `off`, `low`, `medium`, `high`, `xhigh` |
 | Pi | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
 | Copilot | `low`, `medium`, `high`, `xhigh` |
 
+GPT-6 Sol supports `max` and `ultra`; GPT-6 Luna supports `max`.
+
 Other agents, including Superset chat, currently use their own default and
 reject an explicit effort override.
-</Command>
 
 ---
 
@@ -1110,7 +1136,7 @@ screenshot, read console, evaluate JavaScript, and get a raw Chrome DevTools
 Protocol endpoint for click/type/scroll automation. Every operation runs in the
 pane the user sees, against the browser's real session. Browser panes live in
 the desktop app, so a standalone host with no desktop attached has no panes and
-these commands error. A `paneId` is scoped to its workspace — pass the same
+these commands error. A `paneId` is scoped to its workspace; pass the same
 `--workspace` it was opened under. See the [`browser` skill](/skills) for the
 agent-facing protocol.
 
@@ -1185,7 +1211,7 @@ Capture a PNG screenshot of the pane's page.
 	]}
 	output={`{ result: unknown }`}
 >
-Evaluate JavaScript in the page and return the result — the ergonomic path for
+Evaluate JavaScript in the page and return the result for
 reading or nudging the DOM.
 
 ```bash
@@ -1218,7 +1244,139 @@ Read the pane's captured console output.
 >
 Print a raw Chrome DevTools Protocol WebSocket endpoint for the pane, for
 browser-use / Playwright-class tools (mouse, keyboard, scroll, DOM, network).
-The URL embeds an auth token — treat it as a secret.
+The URL embeds an auth token; treat it as a secret.
+</Command>
+
+---
+
+### pages
+
+Publish and manage [Pages](/pages) in the active organization.
+
+<Command
+	name="superset pages list"
+	options={[
+		{ flag: "--workspace <name|id>", description: "Scope to a workspace. Defaults to SUPERSET_WORKSPACE_ID; pass an empty string for the whole organization." },
+		{ flag: "--search <text>, -q <text>", description: "Search titles, slugs, and descriptions." },
+		{ flag: "--limit <n>", description: "Fetch one batch of 1–200 pages." },
+		{ flag: "--cursor <cursor>", description: "Continue from the previous nextCursor." },
+	]}
+>
+Without `--limit` or `--cursor`, fetches all matching pages and returns a plain
+array. Either pagination flag selects one batch and returns
+`{ items, nextCursor }`; `nextCursor` is null at the end. A cursor without a
+limit uses 50 rows per batch. Pages are ordered newest-created first.
+`--quiet` prints page IDs in either mode. Linked workspaces appear in the
+WORKSPACE column and in each row's `workspaceLinks`.
+
+```bash
+superset pages list --workspace '' --search onboarding --json
+superset pages list --workspace '' --limit 20 --json
+superset pages list --workspace '' --limit 20 --cursor '<nextCursor>' --json
+```
+</Command>
+
+<Command
+	name="superset pages publish <path>"
+	args={[
+		{ name: "path", required: true, description: "HTML file, or directory containing index.html and its assets." },
+	]}
+	options={[
+		{ flag: "--title <text>", description: "Page title; defaults to the file or directory name." },
+		{ flag: "--description <text>", description: "Short description." },
+		{ flag: "--label <text>, -l <text>", description: "What changed in this version." },
+		{ flag: "--visibility <value>", description: "just_me, org, or everyone. New pages default to org." },
+		{ flag: "--page <id>", description: "Add a version to this existing page." },
+		{ flag: "--workspace <name|id>", description: "Workspace link; defaults to SUPERSET_WORKSPACE_ID. Optional." },
+		{ flag: "--no-watch", description: "Do not register this terminal to receive new page comments." },
+	]}
+>
+Publishing the same entry path from the same workspace adds a version to the
+existing page. Without a workspace, keep the returned ID and pass `--page` on
+later publishes to avoid creating another page. Existing visibility is
+preserved unless explicitly supplied.
+
+The first version published from a workspace attempts to open in the desktop,
+following **Settings → Links → Pages**. This is skipped over SSH or in a cloud
+sandbox. An opening failure does not fail the publish; the result includes an
+`openNote`. Later versions do not reopen.
+
+```bash
+superset pages publish report.html --title "Weekly report" --visibility everyone
+superset pages publish report.html --page <page-id> --label "Addressed feedback"
+```
+
+<CommandReturns>
+Page metadata including `id`, `title`, `version`, and `url`, plus `unanchored`,
+`watching`, and asset upload/reuse counts. Unlinked publishes include a
+`republish` command; watch and opening notes appear when applicable.
+</CommandReturns>
+</Command>
+
+<Command
+	name="superset pages delete <page>"
+	args={[
+		{ name: "page", required: true, description: "Page ID or slug." },
+	]}
+	options={[
+		{ flag: "--yes", description: "Skip the interactive confirmation." },
+	]}
+	output="{ id: string }"
+>
+Delete a page and every version. Interactive terminals ask for confirmation
+unless `--yes` is passed; non-interactive input does not prompt.
+</Command>
+
+---
+
+### environments
+
+<Command name="superset environments list">
+List the active organization's cloud environments, including their IDs, names,
+and repositories. Human-readable output marks unusable environments. JSON
+returns the environment array, including entries that cannot start a workspace.
+
+```bash
+superset environments list --json
+```
+</Command>
+
+---
+
+### mcp
+
+Use tools from connected plugins. This is separate from the
+[Superset MCP server](/mcp-server), which exposes Superset itself to agents.
+
+<Command
+	name="superset mcp tools"
+	options={[
+		{ flag: "--plugin <name>", required: true, description: "Plugin name from superset plugins list." },
+	]}
+	output="Array<{ plugin: string; tool: string; description: string }>"
+>
+List the tools a connected plugin exposes. Use the returned names and
+descriptions before calling a tool.
+</Command>
+
+<Command
+	name="superset mcp call-tool <tool> [arguments]"
+	args={[
+		{ name: "tool", required: true, description: "Tool name from mcp tools." },
+		{ name: "arguments", description: "JSON arguments; defaults to {}. Pass - to read stdin." },
+	]}
+	options={[
+		{ flag: "--plugin <name>", required: true, description: "Connected plugin name." },
+	]}
+>
+Call a plugin tool and return its MCP result, including the content array.
+Credentials are attached by Superset's API. `--connection` and `--plugin-id`
+are deprecated aliases for `--plugin`; they take a plugin name, not a connection ID.
+
+```bash
+superset mcp tools --plugin notion
+superset mcp call-tool notion-fetch --plugin notion '{"id":"<page-id>"}'
+```
 </Command>
 
 ---