From d586012f20afdd4f77f1835450c908f031445133 Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Wed, 23 Sep 2026 09:11:18 -0700 Subject: [PATCH 1/4] docs: update weekly product documentation for September 23 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Source of truth: live Notion SOP https://www.notion.so/3b3b9d5bf616810dbacaca7dd2305259 Window: GitHub merged:>=2026-09-16, through this run on 2026-09-23. gh returned 103 PRs (limit 1000, avoiding the SOP example’s 50-PR truncation). Workspace baseline: 2158895228. Prior session stopped at a usage limit; the checkout was clean. ## Changes - Pages, CLI, and MCP: public sharing, workspace menus, origin labels, pagination, first-publish opening, version previews, mobile comments, and link handling: #7570, #7658, #7726, #7472, #7532, #7718. Files: pages.mdx; cli/cli-reference.mdx; mcp-server.mdx. - iPhone launch, requirements, setup, host states, and Pro checklist: #7703, #7686, #7697, #7661, #7642, #7494. Files: install.mdx; faq.mdx; overview.mdx; remote-access.mdx. - Editor save conflicts and Markdown link actions: #7711, #7621. Files: editor.mdx. - Terminal locations, copying, and ended-session recovery: #7712, #7709, #7618. Files: terminal-integration.mdx. - Model catalog, embedded sign-in, and leaderboard history: #7741, #7740, #7651. Files: agent-integration.mdx; usage.mdx; cli/cli-reference.mdx. - Repository picker, cloud working branches and attachments, mobile sessions, sidebar naming and ordering: #7694, #7620, #7622, #7633, #7604, #7650, #7575. Files: first-workspace.mdx; workspaces.mdx. - Slack plugin tools and gated thread follow-ups, queuing, mute and stop controls: #7583, #7585, #7586, #7588, #7592, #7594. Files: use-with-slack.mdx. - New CLI transcript, environment, and page deletion commands; connected-service plugins and MCP CLI migration: #7602, #7317. Files: cli/cli-reference.mdx; skills.mdx. - Startup recovery and pre-account workspace migration: #7764, #7649. Files: troubleshooting.mdx. Current source wins over PR descriptions: page ordering is newest-created first, search includes description, default CLI output remains a bare array, and the leaderboard automatically backfills since launch (there is no history-range picker). Slack thread commands and Mobile settings retain their availability qualifications. No assumption that every merged fix is already in the latest download. ## Deliberately skipped - [#7765](https://github.com/superset-sh/superset/pull/7765) fix(host-service): report GitHub being unreachable as unavailable, not a 500: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7756](https://github.com/superset-sh/superset/pull/7756) fix(pages): restore page.list's bare-array contract for released clients: Restores compatibility for released clients; checked the current listPaginated implementation when documenting #7726. - [#7749](https://github.com/superset-sh/superset/pull/7749) fix(build): build every dist-types a filtered mobile typecheck needs: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7748](https://github.com/superset-sh/superset/pull/7748) feat(mobile): refresh the App Store listing and load review creds from .env: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7747](https://github.com/superset-sh/superset/pull/7747) feat(mobile): ask for a rating on returning Home after real use: App Store rating timing needs no setup or reference instructions. - [#7746](https://github.com/superset-sh/superset/pull/7746) feat(mobile): start Sentry natively so launch crashes carry native context: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7744](https://github.com/superset-sh/superset/pull/7744) fix(email): make the welcome email unsubscribable via a Resend automation: Welcome email unsubscribe delivery is not a product workflow needing docs. - [#7734](https://github.com/superset-sh/superset/pull/7734) fix(desktop): restore locale provider test mocks: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7733](https://github.com/superset-sh/superset/pull/7733) fix(marketing): hide leaderboard vertical guide lines: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7732](https://github.com/superset-sh/superset/pull/7732) chore(desktop): bump version to 1.30.2: Version bump only. - [#7723](https://github.com/superset-sh/superset/pull/7723) fix(desktop): preserve sidebar order and missing group members: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7717](https://github.com/superset-sh/superset/pull/7717) fix(desktop): keep terminal links within URL boundaries: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7715](https://github.com/superset-sh/superset/pull/7715) fix(ci): unblock CLI publishing and retry macOS installs: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7714](https://github.com/superset-sh/superset/pull/7714) fix(desktop): prevent tab close clicks from starting a drag: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7710](https://github.com/superset-sh/superset/pull/7710) feat(marketing): add Vladimir mobile testimonial and rank quotes: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7704](https://github.com/superset-sh/superset/pull/7704) feat(marketing): add App Store icon to footer: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7701](https://github.com/superset-sh/superset/pull/7701) chore(desktop): bump version to 1.30.1: Version bump only. - [#7700](https://github.com/superset-sh/superset/pull/7700) fix(marketing): refine hero copy and demo details: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7698](https://github.com/superset-sh/superset/pull/7698) feat(marketing): replace mobile feature cards with customer testimonials: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7696](https://github.com/superset-sh/superset/pull/7696) fix: write managed configs and workspace files through symlinks: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7695](https://github.com/superset-sh/superset/pull/7695) fix(marketing): isolate and scale the mobile phone demo: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7691](https://github.com/superset-sh/superset/pull/7691) fix(terminal): preserve agent paste mode across host restarts: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7690](https://github.com/superset-sh/superset/pull/7690) feat(marketing): showcase mobile workflows and simplify the homepage: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7689](https://github.com/superset-sh/superset/pull/7689) chore(mobile): bump version to 1.1.1 for TestFlight: Version bump only. - [#7688](https://github.com/superset-sh/superset/pull/7688) fix(desktop): resolve dev Dock names across workspace path aliases: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7685](https://github.com/superset-sh/superset/pull/7685) docs(marketing): add September 20 weekly changelog: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7684](https://github.com/superset-sh/superset/pull/7684) docs(skills): share mobile demo recording and film tooling: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7683](https://github.com/superset-sh/superset/pull/7683) fix(ui): truncate the page title instead of running it under the header actions: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7680](https://github.com/superset-sh/superset/pull/7680) fix(host-service): treat a socket torn down mid-request as the cloud being unreachable: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7678](https://github.com/superset-sh/superset/pull/7678) fix(desktop): keep markdown link and image attributes as strings so a paste can't stop the editor saving: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7676](https://github.com/superset-sh/superset/pull/7676) docs(db): migration safety checklist and deploy workflow pitfalls from the 17 September outage: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7675](https://github.com/superset-sh/superset/pull/7675) fix(integrations): backfill existing connections into the table #7317 reads: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7672](https://github.com/superset-sh/superset/pull/7672) fix(ci): a failed production migration can no longer pass as a success: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7671](https://github.com/superset-sh/superset/pull/7671) fix(db,ci): make migration 0119 online-safe and bound production migrations: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7670](https://github.com/superset-sh/superset/pull/7670) fix(desktop): send text to running terminals as a bracketed paste, not raw keystrokes: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7669](https://github.com/superset-sh/superset/pull/7669) feat(skills): audit page usage in the 10x skill: Existing skills page already describes the 10x audit; page-usage audit is an internal skill refinement. - [#7668](https://github.com/superset-sh/superset/pull/7668) fix(mobile): scroll-to-bottom button drives Claude Code's fullscreen view: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7666](https://github.com/superset-sh/superset/pull/7666) fix(host-service): treat a gh that cannot start as no token: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7665](https://github.com/superset-sh/superset/pull/7665) chore(desktop): bump version to 1.30.0: Version bump only. - [#7664](https://github.com/superset-sh/superset/pull/7664) refactor(marketing): share the store badges with the mobile launch post: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7662](https://github.com/superset-sh/superset/pull/7662) chore(mobile): simulator verification skill, stand-in host, and host-state flows: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7659](https://github.com/superset-sh/superset/pull/7659) fix(host-service): stop the Linux file watcher from taking the host down, and make superset start recover: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7655](https://github.com/superset-sh/superset/pull/7655) feat(marketing): add /mobile landing page behind the mobile-launch flag: Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7647](https://github.com/superset-sh/superset/pull/7647) fix(agent-setup): restore Codex working status: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7644](https://github.com/superset-sh/superset/pull/7644) fix(desktop): refresh commits after external changes: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7643](https://github.com/superset-sh/superset/pull/7643) fix(mobile): a long press lifts the whole session tab, not its text: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7641](https://github.com/superset-sh/superset/pull/7641) fix(desktop): harden renderer error boundaries and recovery: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7639](https://github.com/superset-sh/superset/pull/7639) fix(desktop): keep the editor selection valid when external content replaces the document: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7638](https://github.com/superset-sh/superset/pull/7638) fix(desktop): stop the file tree throwing when a lookup walks through a file: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7636](https://github.com/superset-sh/superset/pull/7636) fix(host-service): classify an index its storage cannot deliver as environmental: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7615](https://github.com/superset-sh/superset/pull/7615) fix(cli-framework,i18n): `bun run dev` runs the CLI instead of dying: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7613](https://github.com/superset-sh/superset/pull/7613) fix(host-service): a terminal in a cloud workspace knows it is in one: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7611](https://github.com/superset-sh/superset/pull/7611) feat(marketing): Superset Mobile launch post (hidden until launch): Marketing/store copy, layout, or launch assets; no separate product-doc change. The released iPhone workflow is covered by #7686 and #7703. - [#7608](https://github.com/superset-sh/superset/pull/7608) fix(sandbox): the release probe checks the display from inside the box: Internal build, tests, migration, developer tooling, or recovery plumbing; no new user-facing instructions. - [#7606](https://github.com/superset-sh/superset/pull/7606) fix(relay): tolerate slow connections with coordinated deadlines: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7605](https://github.com/superset-sh/superset/pull/7605) fix(desktop): drop duplicate create-workspace submits while one is in flight: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7603](https://github.com/superset-sh/superset/pull/7603) fix(desktop): preserve translation context for route errors: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7601](https://github.com/superset-sh/superset/pull/7601) feat(mobile): let the workspace list scroll under a transparent header: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7598](https://github.com/superset-sh/superset/pull/7598) fix(desktop): keep viewport emulation on a crashed browser pane from crashing the app: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7597](https://github.com/superset-sh/superset/pull/7597) fix(host-service): pin git's diff prefixes so the Changes pane can parse every patch: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7593](https://github.com/superset-sh/superset/pull/7593) fix(api): post the Slack agent's reply after its run budget is spent: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7587](https://github.com/superset-sh/superset/pull/7587) fix(desktop): keep new sidebar group orders on the integer lane: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7582](https://github.com/superset-sh/superset/pull/7582) fix(api): bound every Slack agent call by the run budget: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7581](https://github.com/superset-sh/superset/pull/7581) feat(api): Slack agent foundation — shared handler, execution guard, thread window, model and output fixes: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. - [#7573](https://github.com/superset-sh/superset/pull/7573) feat(pages): publish without a workspace: Standalone publishing is already documented in pages.mdx; preserved that guidance and included its contract in the new CLI/MCP reference. - [#7255](https://github.com/superset-sh/superset/pull/7255) fix(host-service): preserve consumed Claude prompts in handoffs: Reliability or visual fix restores expected behavior; no new workflow or necessary workaround to document. ## Validation - bun install: passed; no tracked dependency changes. - bun run lint:fix: passed, no code fixes. - bun run lint: passed. - bun run --cwd apps/docs typecheck: passed. - Vale on all 16 changed docs: zero errors and warnings. Small pre-existing prose violations in touched pages were corrected to satisfy the SOP. - git diff --check: passed. Only apps/docs/content/docs/ and the required append-only root TODO log are included. No push or PR. 37 PRs drove changes; 66 were deliberately skipped as separate documentation work. --- TODO.md | 6 + apps/docs/content/docs/agent-integration.mdx | 5 + apps/docs/content/docs/cli/cli-reference.mdx | 172 +++++++++++++++++- apps/docs/content/docs/editor.mdx | 14 ++ apps/docs/content/docs/faq.mdx | 6 +- apps/docs/content/docs/first-workspace.mdx | 2 +- apps/docs/content/docs/install.mdx | 8 + apps/docs/content/docs/mcp-server.mdx | 18 +- apps/docs/content/docs/overview.mdx | 2 +- apps/docs/content/docs/pages.mdx | 26 ++- apps/docs/content/docs/remote-access.mdx | 14 +- apps/docs/content/docs/skills.mdx | 15 +- .../content/docs/terminal-integration.mdx | 6 +- apps/docs/content/docs/troubleshooting.mdx | 8 +- apps/docs/content/docs/usage.mdx | 16 +- apps/docs/content/docs/use-with-slack.mdx | 14 ++ apps/docs/content/docs/workspaces.mdx | 13 +- 17 files changed, 316 insertions(+), 29 deletions(-) create mode 100644 TODO.md diff --git a/TODO.md b/TODO.md new file mode 100644 index 00000000000..37acb79943c --- /dev/null +++ b/TODO.md @@ -0,0 +1,6 @@ +# 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. diff --git a/apps/docs/content/docs/agent-integration.mdx b/apps/docs/content/docs/agent-integration.mdx index d9c367a473d..18564b42855 100644 --- a/apps/docs/content/docs/agent-integration.mdx +++ b/apps/docs/content/docs/agent-integration.mdx @@ -40,6 +40,11 @@ Superset includes a built-in chat panel for AI interactions without leaving the - Chat session titles are generated automatically from the conversation - Use the thinking level control to set reasoning effort: **Off**, **Low**, **Medium**, **High**, or **Max** +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. In the Codex +workspace launcher, Sol supports reasoning effort through **Ultra**, and Luna +through **Max**. [Usage](/usage) tracks estimated token costs for these models. + ## Agent Settings Go to **Settings → Agents** to customize launch behavior for each built-in agent. diff --git a/apps/docs/content/docs/cli/cli-reference.mdx b/apps/docs/content/docs/cli/cli-reference.mdx index 58ea493aba1..be8879d327d 100644 --- a/apps/docs/content/docs/cli/cli-reference.mdx +++ b/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… ``` + + +", required: true, description: "Workspace ID." }, + { flag: "--terminal ", required: true, description: "Terminal ID, returned as sessionId by agents create." }, + { flag: "--host ", 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 --terminal +``` + + +The transcript object in JSON mode, or its text in human-readable mode. + + + #### 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. - --- @@ -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. + + +--- + +### pages + +Publish and manage [Pages](/pages) in the active organization. + +", description: "Scope to a workspace. Defaults to SUPERSET_WORKSPACE_ID; pass an empty string for the whole organization." }, + { flag: "--search , -q ", description: "Search titles, slugs, and descriptions." }, + { flag: "--limit ", description: "Fetch one batch of 1–200 pages." }, + { flag: "--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 '' --json +``` + + +", description: "Page title; defaults to the file or directory name." }, + { flag: "--description ", description: "Short description." }, + { flag: "--label , -l ", description: "What changed in this version." }, + { flag: "--visibility ", description: "just_me, org, or everyone. New pages default to org." }, + { flag: "--page ", description: "Add a version to this existing page." }, + { flag: "--workspace ", 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 --label "Addressed feedback" +``` + + +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. + + + + +Delete a page and every version. Interactive terminals ask for confirmation +unless `--yes` is passed; non-interactive input does not prompt. + + +--- + +### environments + + +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 +``` + + +--- + +### mcp + +Use tools from connected plugins. This is separate from the +[Superset MCP server](/mcp-server), which exposes Superset itself to agents. + +", 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. + + +", 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":""}' +``` --- diff --git a/apps/docs/content/docs/editor.mdx b/apps/docs/content/docs/editor.mdx index 62c53958317..5f448fce66f 100644 --- a/apps/docs/content/docs/editor.mdx +++ b/apps/docs/content/docs/editor.mdx @@ -30,6 +30,20 @@ Ways in: For longer editing sessions, **⌘O** opens the workspace in your IDE ([IDE Integration](/use-with-ide)). +## Save and Review External Changes + +Use **Save** or **⌘S** to write your edits. If an agent or script changes the file while you have unsaved edits, the editor keeps your buffer and shows an external-change banner. Click **Compare** to review the disk and local versions side by side. Saving a conflicted file opens the same review. + +- **Keep editing** preserves your unsaved edits without writing to disk. +- **Reload from disk** replaces your buffer with the disk version. It is unavailable if the file cannot be read. +- **Overwrite file** replaces the disk version with your edits. + +The editor does not autosave or merge simultaneous edits. + +## Markdown Links + +Web links in Markdown previews follow **Settings → Links**. By default, Shift-click opens a new tab, Cmd/Ctrl-click opens a split browser pane, and Cmd/Ctrl+Shift-click opens the system browser. A plain click keeps you editing. + ## Cross-Workspace Search The search bar can search across all open workspaces, not just the active one, useful when you're running parallel workstreams and can't remember which branch has the thing. diff --git a/apps/docs/content/docs/faq.mdx b/apps/docs/content/docs/faq.mdx index 8b9db956560..e7057de4bc2 100644 --- a/apps/docs/content/docs/faq.mdx +++ b/apps/docs/content/docs/faq.mdx @@ -6,10 +6,10 @@ description: Frequently asked questions ## Platforms **What platforms are supported?** -macOS (Apple Silicon and Intel) is the supported target. A Linux x64 AppImage ships with each release but is experimental and untested. Windows is planned with no date. The CLI additionally supports Linux x64 and arm64. +macOS (Apple Silicon and Intel) is the supported target. A Linux x64 AppImage ships with each release but is experimental and untested. Windows is planned with no date. The CLI also supports Linux x64 and arm64. **Is there a mobile app or web dashboard?** -A mobile app is in progress, no date yet. There's no supported web dashboard today. +[Superset for iPhone](https://apps.apple.com/app/id6788926383) is available for iOS 26 or later with Superset Pro and a computer with Remote Access enabled. See [setup](/remote-access#connect-from-an-iphone). Android is not available yet. There's no supported web dashboard today. **Does it work with GitLab or self-hosted remotes?** GitHub is fully supported via the `gh` CLI. Repos with other remotes work locally, but cross-machine project identity is currently tied to GitHub, so the same project can show up twice across devices. @@ -68,7 +68,7 @@ Yes. Terminals are backed by a background daemon, so running processes and scrol ## Remote and Automations **Why does my host show offline when the machine is up?** -"Online" means connected to the Superset relay, not "the process is running." Remote access via relay is **off by default**; enable it under **Settings → Security** (or run `superset start --daemon` on CLI hosts). See [Remote Access](/remote-access). The local CLI works regardless of relay state. +"Online" means connected to the Superset relay, not "the process is running." Remote access via relay is **off by default**; enable it under **Settings → Remote Access** (or run `superset start --daemon` on CLI hosts). See [Remote Access](/remote-access). The local CLI works regardless of relay state. **Can I open a remote host's ports on my Mac?** Not yet; the ports panel shows ports on the host machine. Workaround: `ssh -L 3000:localhost:3000 user@host` or a tailnet. diff --git a/apps/docs/content/docs/first-workspace.mdx b/apps/docs/content/docs/first-workspace.mdx index 08ebf19057e..dac88a54346 100644 --- a/apps/docs/content/docs/first-workspace.mdx +++ b/apps/docs/content/docs/first-workspace.mdx @@ -7,7 +7,7 @@ This is the most important page in the docs. In about ten minutes you'll add a r ## 1. Add a Repository -Add your repo from a local folder or Git URL. Requires GitHub auth (`gh auth status`). +Add your repo from a local folder or clone a remote repository. In the clone dialog, search the GitHub repositories available to the selected host's GitHub CLI login, then pick one to fill in the URL and project name. You can also paste a Git URL manually. Check GitHub access with `gh auth status` on that host. ![Add Repository](/images/add-repo.png) diff --git a/apps/docs/content/docs/install.mdx b/apps/docs/content/docs/install.mdx index fd66108c57c..e57a6be3d03 100644 --- a/apps/docs/content/docs/install.mdx +++ b/apps/docs/content/docs/install.mdx @@ -26,6 +26,14 @@ Onboarding checks your prerequisites with live detection: install or sign in to Using Bedrock, Vertex, OpenRouter, or another provider? See [Providers](/providers). +Paid organizations also get a **Get the best out of Pro** sidebar checklist for Remote Access, mobile, and automations. Reopen it from **Help → Get the best out of Pro** if you dismissed it. + +## iPhone + +[Download Superset for iPhone](https://apps.apple.com/app/id6788926383) to continue your agents from your phone. You need **iOS 26 or later**, **Superset Pro**, and a connected computer with **Remote Access enabled**. Sign in with the same Superset account and organization you use on desktop. + +Follow [iPhone setup](/remote-access#connect-from-an-iphone) to connect your computer. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). + ## Staying Updated Superset checks for updates automatically. New releases ship daily; the [changelog](https://superset.sh/changelog) rounds up each week's highlights. diff --git a/apps/docs/content/docs/mcp-server.mdx b/apps/docs/content/docs/mcp-server.mdx index ffebd1cf39c..4b541a6d7ea 100644 --- a/apps/docs/content/docs/mcp-server.mdx +++ b/apps/docs/content/docs/mcp-server.mdx @@ -332,15 +332,27 @@ API keys grant full access to your organization. Keep them secret and never comm | Tool | Description | |------|-------------| -| `pages_list` | List published pages in the organization (optionally scoped to one workspace) | +| `pages_list` | Search and paginate pages, optionally scoped to one workspace | | `pages_get` | Get one page's metadata by id or slug (title, visibility, URL, served version) | | `pages_versions` | List a page's version history, newest first | | `pages_pull` | Get a download URL for a page's HTML, plus that version's metadata | -| `pages_publish` | Publish an HTML document (passed inline, not as a path) and get its public URL | +| `pages_publish` | Publish an HTML document (passed inline, not as a path) and get its shareable URL | | `pages_comments_list` | List comment threads on a page, with replies and resolved state | | `pages_comments_reply` | Post a reply into a comment thread | | `pages_comments_resolve` | Mark a comment thread resolved, or reopen it | +`pages_list` returns `{ items, nextCursor }`, ordered newest-created first. +Pass `search` to match title, slug, or description, `limit` for 1–200 rows +(default 50), and the returned `nextCursor` as `cursor` to continue. Keep +fetching until `nextCursor` is null. `scope` accepts `all` (default), `team` +for shared pages, or `mine` for your private pages. + +`pages_publish` accepts `visibility: "just_me"`, `"org"` (the default for new +pages), or `"everyone"` for anonymous read-only access. Pass `workspaceId` and +`entryPath` together to link the page to a workspace. Both are optional; +outside a workspace, save the returned `id` and pass it as `pageId` when +publishing updates. Otherwise each publish creates a separate page. + ### Automations | Tool | Description | @@ -386,7 +398,7 @@ Once connected, you can ask your AI agent to: - "Create a task for fixing the login bug" - "List all my assigned tasks" - "Create a workspace for the auth feature on my MacBook" -- "Schedule a daily automation that triages new Linear issues at 9am" +- "Schedule a daily automation that triages new Linear issues at 9 a.m." - "Pause the nightly cleanup automation" - "Show me the last 10 runs of my Linear triage automation" - "Answer the two threads handed to me on the launch-plan page" diff --git a/apps/docs/content/docs/overview.mdx b/apps/docs/content/docs/overview.mdx index 4efe221a853..b80110c1daf 100644 --- a/apps/docs/content/docs/overview.mdx +++ b/apps/docs/content/docs/overview.mdx @@ -3,7 +3,7 @@ title: What is Superset? description: The 60-second version --- -Superset is a source-available platform for running AI coding agents in parallel, licensed under the Elastic License 2.0. It's available as a desktop IDE, a command-line interface, and an MCP server. +Superset is a source-available platform for running AI coding agents in parallel, licensed under the Elastic License 2.0. It's available as a desktop IDE, an [iPhone app](/install#iphone), a command-line interface, and an MCP server. The core move: every task gets its own **workspace**, an isolated git worktree on its own branch. Agents work in workspaces, so three agents (or ten) can run at once without touching each other's changes or your `main`. You review each result in a built-in diff viewer and integrate through ordinary branches and PRs. diff --git a/apps/docs/content/docs/pages.mdx b/apps/docs/content/docs/pages.mdx index f33b5d3e918..dbd475e6434 100644 --- a/apps/docs/content/docs/pages.mdx +++ b/apps/docs/content/docs/pages.mdx @@ -43,12 +43,34 @@ To publish from the CLI, keep the source inside your workspace and run: superset pages publish design.html --title "Onboarding design" --label "First draft" ``` -The command returns a shareable URL. New pages are visible to your organization by default. For a private draft, add `--visibility just_me` when you first publish. +The command returns a shareable URL. On the first publish from a workspace, it also attempts to open the page according to **Settings → Links → Pages**. Republishing does not reopen it. Automatic opening is skipped over SSH, in cloud sandboxes, and when publishing without a workspace. + +## Find Workspace Pages + +Open the Pages menu beside **Run**, above **Files / Changes / Review**. It lists pages published from the workspace, your pinned pages, and **All pages**. Choose **New page**, enter a request, and pick an agent to create it. A blue **New** indicator marks a fresh publish until you close the menu. + +The main Pages list shows linked workspace names so you can see where a page came from. + +Web links inside a workspace Page follow **Settings → Links** and open outside the Page pane. If no plain-click action is set, a plain click opens a browser pane. Links in standalone Pages in the desktop app open in the system browser. + +## Share a Page + +Use **Share** to choose who can open the page: + +- **Only you**: a private draft. +- **Anyone in your organization**: members of your organization. This is the default for new pages. +- **Anyone with the link**: anyone can read it without signing in. Public access does not grant comment or edit permissions, or access to the rest of the version history. + +**Shared version** controls whether the link follows the latest publish or stays on a specific version. Anonymous readers can access only that shared version. + +For a new page, the CLI accepts `--visibility just_me`, `--visibility org`, or `--visibility everyone`. Republishing preserves visibility unless you explicitly change it. Shared links include the page thumbnail in link previews. ## Send Feedback Directly to an Agent Open the page, enter comment mode, and click an element to pin feedback to it. The agent receives the comment along with context identifying the element, so teammates can point to exactly what they want changed. +On iPhone, the comments sheet keeps replies inline. Tap **Reply** to target a thread, or clear the reply target to leave a page-level comment. Resolved threads appear under the resolved-comments disclosure. + Publishing from an agent's Superset terminal automatically sets that session to watch the page for new comments. In the workspace page pane, use the agent menu in the page header to see which agent is watching, select another running agent, or choose **Stop watching**. Keep the host and agent session running for automatic feedback delivery. If the menu says **Nothing is watching this page**, select a running agent. New comments are delivered when the agent is available to handle them. @@ -73,7 +95,7 @@ superset pages publish design.html --page --label "Updated onboarding Publishing from outside a workspace works too, but there's no path for a later publish to resolve against: every run creates a separate page unless you pass `--page`. The publish tells you when that happened and prints the command to reuse. -Republishing preserves the page's visibility. You can also inspect version history or retrieve a published version: +Use the page title menu to preview earlier versions read-only, rename the page, or refresh it. You can also inspect version history or retrieve a published version: ```bash superset pages versions diff --git a/apps/docs/content/docs/remote-access.mdx b/apps/docs/content/docs/remote-access.mdx index f5fb7c75d10..d15911f9d58 100644 --- a/apps/docs/content/docs/remote-access.mdx +++ b/apps/docs/content/docs/remote-access.mdx @@ -63,6 +63,16 @@ superset hosts list --org superset status --org ``` +## Connect from an iPhone + +Install [Superset for iPhone](https://apps.apple.com/app/id6788926383). Mobile requires **iOS 26 or later** and **Superset Pro**. + +1. On your computer, enable **Allow remote access to this device via relay** in **Settings → Remote Access**. You can also use the inline toggle in **Settings → Mobile** when that tab is available. Both toggles control the same setting. +2. On your phone, sign in with the same Superset account and select the same organization. The QR code in desktop Mobile settings opens the App Store; it does not sign you in. +3. Select your computer and open a workspace to continue its terminal sessions, send prompts, review diffs, or merge PRs. Keep the computer awake, online, and running Superset. + +A computer that has never connected shows **One step left** with Remote Access instructions. A previously connected computer shows its last-seen time when offline. **Can’t check** means presence could not be loaded; use **Try again**. See [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect). + ## Grant teammates access When a host first comes online, the user who started it is the only one with access. Other members of your organization won't see it in their workspaces list until you add them. @@ -90,11 +100,11 @@ Only ports that the workspace started are forwarded. Other services on the host If a local process already uses the port, the row shows **local port busy** and offers two actions: stop the local process (only when a Superset workspace started it) or **Use another port**, which maps the remote port to a free local port and shows the mapping, for example `3000 → localhost:54321`. -The remote server sees each forwarded connection as coming from its own loopback address — there is no real client IP. Only TCP is carried; anything UDP (WebRTC media, mDNS) does not ride the forward. +The remote server sees each forwarded connection as coming from its own loopback address; there is no real client IP. Only TCP is carried; anything UDP (WebRTC media, mDNS) does not ride the forward. Forwarding needs a host on the current relay running host-service 1.26 or newer. For a host you reach some other way, [forward a port yourself](/ports#forward-a-port-yourself) with SSH or Tailscale. -Forwarded traffic passes through the Superset relay, like terminal traffic does. A browser talking to a forwarded dev server sends whatever it normally would — cookies, auth headers, query strings — so treat a forwarded port like the remote service it reaches, not like localhost. +Forwarded traffic passes through the Superset relay, like terminal traffic does. A browser talking to a forwarded dev server sends whatever it normally would (cookies, auth headers, query strings), so treat a forwarded port like the remote service it reaches, not like localhost. ## Turning access off diff --git a/apps/docs/content/docs/skills.mdx b/apps/docs/content/docs/skills.mdx index a1816da2e6a..61de62e74f5 100644 --- a/apps/docs/content/docs/skills.mdx +++ b/apps/docs/content/docs/skills.mdx @@ -31,8 +31,8 @@ Or, in Claude Code, via the plugin marketplace: | `superset:orchestrate` | Turns the agent you're talking to into a coordinator of parallel agents; see [Agent Orchestration](/orchestration) | | `superset:automate` | Turns a recurring chore into a scheduled [automation](/automations) and reviews its first run with you | | `superset:page` | Builds and publishes shareable [Pages](/pages), then updates them in response to pinned team comments | -| `superset:browser` | Drives a workspace's [in-app browser](/browser) panes — open, navigate, screenshot, eval, read console, and raw CDP for click/type automation — and routes to [Browser Use 3.0](/browser#browser-use-30) for browsers the panes can't reach | -| `superset:computer` | Drives [native desktop apps](/computer) through an accessibility-first driver (Cua Driver by default) — inspect windows, click, type, use menus, and verify results with background interaction when the platform supports it | +| `superset:browser` | Drives a workspace's [in-app browser](/browser) panes: open, navigate, screenshot, eval, read console, and raw CDP for click/type automation, and routes to [Browser Use 3.0](/browser#browser-use-30) for browsers the panes can't reach | +| `superset:computer` | Drives [native desktop apps](/computer) through an accessibility-first driver (Cua Driver by default): inspect windows, click, type, use menus, and verify results with background interaction when the platform supports it | | `superset:standup` | Sweeps your workspaces, tasks, and agent terminals into a digest: what needs you, what's in flight, what's blocked | | `superset:doctor` | Diagnoses Superset problems (expired auth, offline hosts, stale versions) and fixes them one step at a time | | `superset:feedback` | Files a bug report or feature request: privately to the Superset team (from your account, so we can reply) or as a public GitHub issue | @@ -51,6 +51,17 @@ You usually don't invoke them; agents pick the right skill from context: To invoke one explicitly: `/superset:feedback` in Claude Code, or `/superset/feedback` in the in-app chat. Other agents that read skills (Codex, Kimi, Vibe, Grok) see the same skills with a `superset-` prefix. +## Connected Service Plugins + +The plugin catalog includes Notion, Slack, and Gmail. Install a plugin from +**Plugins**, then connect the account it needs. Connections are separate from +installation: installed skills alone do not authorize access to a service. +If a connection expires, reconnect it when prompted. + +Agents call connected tools through Superset's credential proxy. The service +credential stays on the server; it is not written into local agent config. +You can inspect and call the same tools with [`superset mcp`](/cli/cli-reference#mcp). + ## How They're Delivered At launch, the desktop app writes managed copies into the standard discovery locations: `~/.claude/skills/superset/` (loaded by Claude Code as a plugin, hence the `superset:` namespace), `~/.agents/skills/`, and `~/.agents/commands/`. diff --git a/apps/docs/content/docs/terminal-integration.mdx b/apps/docs/content/docs/terminal-integration.mdx index 619b0f5e670..9dd55f25a48 100644 --- a/apps/docs/content/docs/terminal-integration.mdx +++ b/apps/docs/content/docs/terminal-integration.mdx @@ -24,6 +24,8 @@ Sessions survive app restarts: - Output history preserved - Scrollback maintained +If a terminal has ended, choose **New shell** to start a fresh session in the same pane. Recent output from the previous session stays visible. For agent recovery, see [Resume Interrupted Sessions](/agent-integration#resume-interrupted-sessions). + ## Pane Rename Double-click a pane title to rename it. @@ -41,11 +43,13 @@ Right-click in the terminal for quick actions: - **Mark as Unread** - Show the unread indicator again - Split, Clear, Move to Tab, Close +Normal multiline copying trims trailing ASCII row padding while preserving indentation, tabs, Unicode whitespace, and blank lines. Single-line and rectangular selections keep their selected text. + ## Cmd/Ctrl-Click Links Hold `Cmd` (macOS) or `Ctrl` and click links in terminal output: - URLs open in browser -- File paths open in the built-in file viewer by default +- File paths open in the built-in file viewer by default. A location such as `src/index.ts:240:7` jumps to line 240, column 7. - Change file-path behavior in **Settings → Terminal** ## Environment Variables diff --git a/apps/docs/content/docs/troubleshooting.mdx b/apps/docs/content/docs/troubleshooting.mdx index 4c48803201a..7c35dc0b234 100644 --- a/apps/docs/content/docs/troubleshooting.mdx +++ b/apps/docs/content/docs/troubleshooting.mdx @@ -13,6 +13,12 @@ Almost always a context mix-up, not data loss. Check, in order: Your worktrees are still on disk at `~/.superset/worktrees/` either way; Superset only deletes them when you delete a workspace. +If you created your account after using v1, update Superset and relaunch it. Current versions import pre-account workspaces that older v2 releases could miss. + +## App Starts Without a Window + +If the startup error names a corrupt `tanstack-db.sqlite`, the app can fail before its automatic updater starts. The fix removes this unused database from startup. Install a release containing the fix manually from [superset.sh/download](https://superset.sh/download); if no newer release is available, [contact support](/community) with the startup error. + ## Update Button Does Nothing If the app quits and reopens on the same version, the updater hit a known race (fixed in recent releases). Download a fresh copy from [superset.sh/download](https://superset.sh/download) once; updates work normally after that. @@ -62,7 +68,7 @@ Superset detects installed agents automatically, but each agent can be enabled o The host machine must be online and registered with the relay. -**Fix:** on the host, confirm the toggle in **Settings → Security** is on (desktop) or that `superset start --daemon` is running (CLI). See [Remote Access](/remote-access). +**Fix:** on the host, confirm the toggle in **Settings → Remote Access** is on (desktop) or that `superset start --daemon` is running (CLI). See [Remote Access](/remote-access). ## Automation Run Failed While the Device Was Offline diff --git a/apps/docs/content/docs/usage.mdx b/apps/docs/content/docs/usage.mdx index 9589dbcb515..c1093e4e42c 100644 --- a/apps/docs/content/docs/usage.mdx +++ b/apps/docs/content/docs/usage.mdx @@ -21,13 +21,13 @@ Run different agents on different subscriptions from one machine: ![Two Claude Code accounts with quota meters, one marked as the default](/images/usage-accounts.png) -- **Add account** creates a second profile: pick a profile name, then run the shown sign-in command (e.g. `CLAUDE_CONFIG_DIR="$HOME/.claude-work" claude auth login`) in any terminal on this host. The dialog detects the sign-in automatically. -- **Make default** picks which account new agent launches use — when a provider has several accounts, the cards read as a radio group with the default checked. Switching reaches terminals you already have open too: a running agent keeps its account until you relaunch it. -- Your setup comes along: skills, plugins, MCP servers, and settings are shared across accounts, and for Claude Code there's one conversation history — `--resume` shows the same sessions whichever account is active. -- Logins, credentials, and account identity stay per account. The **…** menu on a card offers **Switch sign-in…** (re-login that profile to a different account) and, for secondary profiles, **Remove…** — which deletes that profile and its credentials, never your shared setup or history. The system-default login can't be removed. +- **Add account** creates a second profile. Pick a profile name and billing type, then complete Claude Code or Codex sign-in in the terminal inside the dialog. Click a login URL to open your system browser. Superset detects a successful sign-in automatically. For a remote host, copy the shown command and run it in a terminal on that host. +- **Make default** picks which account new agent launches use. When a provider has several accounts, the cards read as a radio group with the default checked. Switching reaches terminals you already have open too: a running agent keeps its account until you relaunch it. +- Your setup comes along: skills, plugins, MCP servers, and settings are shared across accounts, and for Claude Code there's one conversation history: `--resume` shows the same sessions whichever account is active. +- Logins, credentials, and account identity stay per account. The **…** menu on a card offers **Switch sign-in…** (re-login that profile to a different account) and, for secondary profiles, **Remove…**, which deletes that profile and its credentials, never your shared setup or history. The system-default login can't be removed. - If a sign-in expires, the card shows the exact login command to run, with click-to-copy. -Under the hood, a profile is just a config dir the CLI is pointed at (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`). Superset's agent wrappers re-resolve the current default every time the agent starts in a Superset terminal — so switching works for agents you launch by hand too, and a value you export yourself always wins. +Under the hood, a profile is just a config dir the CLI is pointed at (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`). Superset's agent wrappers re-resolve the current default every time the agent starts in a Superset terminal, so switching works for agents you launch by hand too, and a value you export yourself always wins. ## Token Costs @@ -38,6 +38,12 @@ Below the meters, the **Token usage** chart estimates spend from the agents' loc - **Model** table and **Workspace** bars break spend down; click a row for a per-model or per-workspace drilldown, or **All N →** for every workspace and project - Workspace drilldowns list the top sessions by cost; click one to copy its session ID for `claude --resume` +## Leaderboard History + +Joining or rejoining the leaderboard publishes available local usage history +since its July 29, 2026 launch. Leaving deletes your published history. +Rejoining can restore it from session logs still on your machine. + ## Machine Resources The **Machine resources** section is a live view (every 2 seconds) of local CPU and memory: Superset's own usage, the system RAM split, and a process table covering the app and every workspace, grouped by project down to individual terminal panes. Click a workspace or session row to jump to it. diff --git a/apps/docs/content/docs/use-with-slack.mdx b/apps/docs/content/docs/use-with-slack.mdx index 3e912adf73a..7a5af6b1c22 100644 --- a/apps/docs/content/docs/use-with-slack.mdx +++ b/apps/docs/content/docs/use-with-slack.mdx @@ -21,6 +21,20 @@ description: Mention @superset in Slack to file tasks or dispatch coding agents 2. Click **Connect** to install the Superset Slack app (OAuth) 3. Mention `@superset` in any channel, or DM the bot, and describe what you want done +## Connected Plugins + +The Slack agent can use a linked user's connected Linear and GitHub plugins to read issues and repositories, file or update issues, comment, and open pull requests. It uses a limited tool set; plugin tools cannot delete resources, merge pull requests, or perform bulk writes. If a requested plugin is not connected, the reply offers a **Connect** button. + +## Thread Follow-ups + +These controls are available when thread follow-ups are enabled for your Slack team: + +- Once the agent has replied in a thread, follow-up replies reach it without another mention. Replies sent while it is working are queued for the next turn. +- Send `!mute` to require mentions in that thread again, or `!unmute` to resume automatic follow-ups. Direct mentions still work in a muted thread. +- Send `!stop` or `!cancel` in the thread or DM to end the running Slack turn. Work already completed remains in the reply's Changes footer. This does not undo actions or stop coding agents already launched in workspaces. + +Without thread follow-ups enabled, continue to mention `@superset` for each channel request. + ## Good First Prompts ```text diff --git a/apps/docs/content/docs/workspaces.mdx b/apps/docs/content/docs/workspaces.mdx index 9fe7d412df4..693cb7ee01f 100644 --- a/apps/docs/content/docs/workspaces.mdx +++ b/apps/docs/content/docs/workspaces.mdx @@ -5,7 +5,7 @@ description: Isolated environments for each git branch ## Core Concept -Each workspace = one git branch. Workspaces are isolated git worktrees with their own directory, terminal, and ports. The exception: [sessions](#sessions), which get a managed scratch folder instead of a branch. +Each workspace = one git branch. Local project workspaces are isolated git worktrees with their own directory, terminal, and ports. Cloud workspaces use a separate clone. The exception: [sessions](#sessions), which get a managed scratch folder instead of a branch. @@ -27,6 +27,12 @@ Each workspace gets: - Own terminal sessions - Workspace-scoped port detection and controls +New local worktrees use `//` directories. Existing worktrees keep their paths. + +### Cloud Workspaces + +When cloud workspaces are available to your account, the selected branch is the base for a new `superset/-` working branch. Multi-repository workspaces create the same working branch name in each repository, from that repository's base. You can attach images to the initial prompt; the agent receives them when the workspace starts. + ## Import Worktrees If you have existing git worktrees on disk, use the **Import** tab in the New Workspace modal to bring them into Superset. Click **Import all** to bulk-import all discovered worktrees at once. @@ -46,6 +52,8 @@ either `--project ` or `--session`; omitting both is an error: superset workspaces create --session --local --agent claude --prompt "…" ``` +On iPhone, choose **No project** in the composer's project picker, or tap **+** beside **No project** on Home. Sending your prompt creates a session on the selected online host. + Automations can run in session mode too; see [Automations](/automations). ## Pin Workspaces @@ -55,6 +63,9 @@ Keep active workspaces at the top of the sidebar: - Right-click a workspace and choose **Pin to Sidebar** (or **Unpin**) - Drag into the **Pinned** section to pin, drag within it to reorder, drag out to unpin - Sessions work the same way +- Pinned project workspaces show a project-name prefix, such as `project/workspace` + +If sorting or filtering prevents a sidebar drag, the notice offers an action to restore manual ordering or clear filters. ## List and Board Views From fa27633693dcc335901eeb7db31aa38a4949694f Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Wed, 23 Sep 2026 09:28:30 -0700 Subject: [PATCH 2/4] docs: correct stale claims and consolidate weekly updates Replace outdated remote-port and privacy claims, correct the 90-day leaderboard backfill cap and link settings location, and describe credential use and comment-watch registration accurately. Consolidate iPhone requirements and troubleshooting, trim repeated Pages prose, and keep launch effort details in the CLI reference. Remove the #7764 startup entry because it does not identify a fixed release and its upgrade instructions are too vague. This supersedes that item in the original PR audit. Validate with docs typecheck, lint:fix, lint, Vale (zero errors or warnings), and git diff --check. --- TODO.md | 4 ++++ apps/docs/content/docs/agent-integration.mdx | 9 +++++---- apps/docs/content/docs/browser.mdx | 18 +++++++++--------- apps/docs/content/docs/faq.mdx | 6 +++--- apps/docs/content/docs/install.mdx | 2 +- apps/docs/content/docs/pages.mdx | 10 +++------- apps/docs/content/docs/remote-access.mdx | 4 ++-- .../docs/content/docs/terminal-integration.mdx | 4 ++-- apps/docs/content/docs/troubleshooting.mdx | 14 ++++++++------ apps/docs/content/docs/usage.mdx | 7 ++++--- apps/docs/content/docs/workspaces.mdx | 6 +++--- 11 files changed, 44 insertions(+), 40 deletions(-) diff --git a/TODO.md b/TODO.md index 37acb79943c..9c5c5481987 100644 --- a/TODO.md +++ b/TODO.md @@ -4,3 +4,7 @@ - [ ] 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. diff --git a/apps/docs/content/docs/agent-integration.mdx b/apps/docs/content/docs/agent-integration.mdx index 18564b42855..60a0e7c9b95 100644 --- a/apps/docs/content/docs/agent-integration.mdx +++ b/apps/docs/content/docs/agent-integration.mdx @@ -38,12 +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. In the Codex -workspace launcher, Sol supports reasoning effort through **Ultra**, and Luna -through **Max**. [Usage](/usage) tracks estimated token costs for these models. +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 diff --git a/apps/docs/content/docs/browser.mdx b/apps/docs/content/docs/browser.mdx index 36962153b78..a15beb0b638 100644 --- a/apps/docs/content/docs/browser.mdx +++ b/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 --pane --out shot.png superset browser console --workspace --pane ``` -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 - 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. -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. diff --git a/apps/docs/content/docs/faq.mdx b/apps/docs/content/docs/faq.mdx index e7057de4bc2..18569ed01e4 100644 --- a/apps/docs/content/docs/faq.mdx +++ b/apps/docs/content/docs/faq.mdx @@ -9,7 +9,7 @@ description: Frequently asked questions macOS (Apple Silicon and Intel) is the supported target. A Linux x64 AppImage ships with each release but is experimental and untested. Windows is planned with no date. The CLI also supports Linux x64 and arm64. **Is there a mobile app or web dashboard?** -[Superset for iPhone](https://apps.apple.com/app/id6788926383) is available for iOS 26 or later with Superset Pro and a computer with Remote Access enabled. See [setup](/remote-access#connect-from-an-iphone). Android is not available yet. There's no supported web dashboard today. +Yes, [Superset for iPhone](/install#iphone) is available. Android is not available yet. There's no supported web dashboard today. **Does it work with GitLab or self-hosted remotes?** GitHub is fully supported via the `gh` CLI. Repos with other remotes work locally, but cross-machine project identity is currently tied to GitHub, so the same project can show up twice across devices. @@ -71,7 +71,7 @@ Yes. Terminals are backed by a background daemon, so running processes and scrol "Online" means connected to the Superset relay, not "the process is running." Remote access via relay is **off by default**; enable it under **Settings → Remote Access** (or run `superset start --daemon` on CLI hosts). See [Remote Access](/remote-access). The local CLI works regardless of relay state. **Can I open a remote host's ports on my Mac?** -Not yet; the ports panel shows ports on the host machine. Workaround: `ssh -L 3000:localhost:3000 user@host` or a tailnet. +Yes. The desktop app forwards detected ports for the selected remote workspace to your machine. If a local port is busy, choose **Use another port**. See [Remote Access](/remote-access#ports-on-a-remote-host) for requirements. **Why did my automation run fail while my machine was asleep?** Runs fail when the target device isn't relay-connected at fire time. Use **Retry all** once it's back. See [Troubleshooting](/troubleshooting#automation-run-failed-while-the-device-was-offline). @@ -79,7 +79,7 @@ Runs fail when the target device isn't relay-connected at fire time. Use **Retry ## Privacy **Does my code leave my machine?** -No. Superset is local-first: repos, worktrees, terminal output, and agent sessions stay on your machine. Cloud sync covers account and organization metadata only. Remote access traffic is routed through the relay only when you explicitly enable it. +Local workspace files live on their host machine. Enabling Remote Access sends workspace traffic through the relay; cloud workspaces run your code in the cloud, and publishing a Page uploads its content. Agents also send prompts and context to the model providers you configure. **Does it modify git config?** No. Superset uses standard git commands. diff --git a/apps/docs/content/docs/install.mdx b/apps/docs/content/docs/install.mdx index e57a6be3d03..45f2426b208 100644 --- a/apps/docs/content/docs/install.mdx +++ b/apps/docs/content/docs/install.mdx @@ -30,7 +30,7 @@ Paid organizations also get a **Get the best out of Pro** sidebar checklist for ## iPhone -[Download Superset for iPhone](https://apps.apple.com/app/id6788926383) to continue your agents from your phone. You need **iOS 26 or later**, **Superset Pro**, and a connected computer with **Remote Access enabled**. Sign in with the same Superset account and organization you use on desktop. +[Download Superset for iPhone](https://apps.apple.com/app/id6788926383) to continue your agents from your phone. You need **iOS 26 or later**, **Superset Pro**, and a connected computer with **Remote Access enabled**. Follow [iPhone setup](/remote-access#connect-from-an-iphone) to connect your computer. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android). diff --git a/apps/docs/content/docs/pages.mdx b/apps/docs/content/docs/pages.mdx index dbd475e6434..baa8321ef49 100644 --- a/apps/docs/content/docs/pages.mdx +++ b/apps/docs/content/docs/pages.mdx @@ -5,8 +5,6 @@ description: Share agent-created designs and reports with your team, and turn co Superset Pages gives your agents a way to present designs, reports, and analysis to your team. Teammates comment directly on the page, and an agent picks up the feedback, makes changes, and publishes an updated version. -Your teammates can talk directly to your agent. You no longer have to copy feedback from a review into an agent session and carry the result back. - ![A Superset Page presenting a cloud signup design review, with a comment pinned to the headline](/images/pages-design-review.png) ## The Design Loop @@ -16,8 +14,6 @@ Your teammates can talk directly to your agent. You no longer have to copy feedb 3. **Comment.** Teammates pin feedback to the part of the page they want to discuss. 4. **Iterate.** The agent watching the page receives new comments, updates the source, republishes, and replies to the threads it addressed. -This is how we use Pages internally at Superset: someone creates a design doc, presents it to the team, and the doc evolves as teammates leave feedback. The discussion and the agent's updates stay together on the page. - ## Create Your First Page Open the **Pages** tab and click **Create with AI**. Superset starts an agent session that asks what you want to create, helps build the page, and publishes a link for your team. The help icon beside the **Pages** title opens this guide. @@ -37,13 +33,13 @@ Turn your findings into a report and publish it as a Page for the team. The Superset plugin includes a [Pages skill](/skills) that guides agents through building, publishing, and updating pages. A page can be a self-contained HTML file or a directory with an `index.html` and supporting assets. -To publish from the CLI, keep the source inside your workspace and run: +To publish from the CLI, run: ```bash superset pages publish design.html --title "Onboarding design" --label "First draft" ``` -The command returns a shareable URL. On the first publish from a workspace, it also attempts to open the page according to **Settings → Links → Pages**. Republishing does not reopen it. Automatic opening is skipped over SSH, in cloud sandboxes, and when publishing without a workspace. +The command returns a shareable URL. The first publish from a local desktop workspace asks the desktop to open it according to **Settings → Links → Pages**; later versions do not reopen. See the [CLI reference](/cli/cli-reference#pages) for options and opening limitations. ## Find Workspace Pages @@ -71,7 +67,7 @@ Open the page, enter comment mode, and click an element to pin feedback to it. T On iPhone, the comments sheet keeps replies inline. Tap **Reply** to target a thread, or clear the reply target to leave a page-level comment. Resolved threads appear under the resolved-comments disclosure. -Publishing from an agent's Superset terminal automatically sets that session to watch the page for new comments. In the workspace page pane, use the agent menu in the page header to see which agent is watching, select another running agent, or choose **Stop watching**. +Publishing from an agent's Superset terminal attempts to register that session for new comments. Check the command's watch status; a failed registration does not fail the publish. In the workspace page pane, use the agent menu in the page header to see which agent is watching, select another running agent, or choose **Stop watching**. Keep the host and agent session running for automatic feedback delivery. If the menu says **Nothing is watching this page**, select a running agent. New comments are delivered when the agent is available to handle them. diff --git a/apps/docs/content/docs/remote-access.mdx b/apps/docs/content/docs/remote-access.mdx index d15911f9d58..b0c3e4abbf9 100644 --- a/apps/docs/content/docs/remote-access.mdx +++ b/apps/docs/content/docs/remote-access.mdx @@ -65,13 +65,13 @@ superset status --org ## Connect from an iPhone -Install [Superset for iPhone](https://apps.apple.com/app/id6788926383). Mobile requires **iOS 26 or later** and **Superset Pro**. +Install [Superset for iPhone](/install#iphone) and check its requirements before connecting. 1. On your computer, enable **Allow remote access to this device via relay** in **Settings → Remote Access**. You can also use the inline toggle in **Settings → Mobile** when that tab is available. Both toggles control the same setting. 2. On your phone, sign in with the same Superset account and select the same organization. The QR code in desktop Mobile settings opens the App Store; it does not sign you in. 3. Select your computer and open a workspace to continue its terminal sessions, send prompts, review diffs, or merge PRs. Keep the computer awake, online, and running Superset. -A computer that has never connected shows **One step left** with Remote Access instructions. A previously connected computer shows its last-seen time when offline. **Can’t check** means presence could not be loaded; use **Try again**. See [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect). +If your computer does not appear online, see [Remote Host Won’t Connect](/troubleshooting#remote-host-wont-connect). ## Grant teammates access diff --git a/apps/docs/content/docs/terminal-integration.mdx b/apps/docs/content/docs/terminal-integration.mdx index 9dd55f25a48..51883bc00f3 100644 --- a/apps/docs/content/docs/terminal-integration.mdx +++ b/apps/docs/content/docs/terminal-integration.mdx @@ -43,14 +43,14 @@ Right-click in the terminal for quick actions: - **Mark as Unread** - Show the unread indicator again - Split, Clear, Move to Tab, Close -Normal multiline copying trims trailing ASCII row padding while preserving indentation, tabs, Unicode whitespace, and blank lines. Single-line and rectangular selections keep their selected text. +Multiline copying removes trailing space padding while preserving indentation and blank lines. Single-line and rectangular selections keep their selected text. ## Cmd/Ctrl-Click Links Hold `Cmd` (macOS) or `Ctrl` and click links in terminal output: - URLs open in browser - File paths open in the built-in file viewer by default. A location such as `src/index.ts:240:7` jumps to line 240, column 7. -- Change file-path behavior in **Settings → Terminal** +- Configure link actions and modifier keys in **Settings → Links** ## Environment Variables diff --git a/apps/docs/content/docs/troubleshooting.mdx b/apps/docs/content/docs/troubleshooting.mdx index 7c35dc0b234..65fb34efe80 100644 --- a/apps/docs/content/docs/troubleshooting.mdx +++ b/apps/docs/content/docs/troubleshooting.mdx @@ -15,10 +15,6 @@ Your worktrees are still on disk at `~/.superset/worktrees/` either way; Superse If you created your account after using v1, update Superset and relaunch it. Current versions import pre-account workspaces that older v2 releases could miss. -## App Starts Without a Window - -If the startup error names a corrupt `tanstack-db.sqlite`, the app can fail before its automatic updater starts. The fix removes this unused database from startup. Install a release containing the fix manually from [superset.sh/download](https://superset.sh/download); if no newer release is available, [contact support](/community) with the startup error. - ## Update Button Does Nothing If the app quits and reopens on the same version, the updater hit a known race (fixed in recent releases). Download a fresh copy from [superset.sh/download](https://superset.sh/download) once; updates work normally after that. @@ -66,9 +62,15 @@ Superset detects installed agents automatically, but each agent can be enabled o ## Remote Host Won't Connect -The host machine must be online and registered with the relay. +The host machine must be awake, online, and connected to the relay. On the host, enable **Settings → Remote Access → Allow remote access to this device via relay** (desktop), or run `superset start --daemon` (CLI). + +On iPhone: + +- **One step left** means the computer has never connected. Follow the Remote Access setup steps on that computer. +- **Offline** with a last-seen time means it connected before. Check that it is awake, online, and running Superset, then retry. +- **Can’t check** means Superset could not load connection status. Use **Try again**; this message does not establish that the computer is offline. -**Fix:** on the host, confirm the toggle in **Settings → Remote Access** is on (desktop) or that `superset start --daemon` is running (CLI). See [Remote Access](/remote-access). +See [Remote Access](/remote-access) for setup. ## Automation Run Failed While the Device Was Offline diff --git a/apps/docs/content/docs/usage.mdx b/apps/docs/content/docs/usage.mdx index c1093e4e42c..d722664ebc4 100644 --- a/apps/docs/content/docs/usage.mdx +++ b/apps/docs/content/docs/usage.mdx @@ -13,7 +13,7 @@ The **Usage** page (gauge icon in the sidebar) tracks what your agents consume o The top of **Token usage** shows official subscription quota for every Claude Code and Codex login on this host, refreshed every 5 minutes (use the refresh button to force it). Each account card shows the email, plan, and one meter per quota window, e.g. **Session (5h)** and **Weekly** for Claude, with the fill percentage and time until reset. -Quota comes from the providers' own usage endpoints using your existing sign-ins; Superset never handles credentials. Some plans (org-managed, education) don't expose limits. +Superset reads quota from the providers' usage endpoints using the agent credentials stored on your host. Some plans (org-managed, education) don't expose limits. ## Multiple Accounts @@ -41,8 +41,9 @@ Below the meters, the **Token usage** chart estimates spend from the agents' loc ## Leaderboard History Joining or rejoining the leaderboard publishes available local usage history -since its July 29, 2026 launch. Leaving deletes your published history. -Rejoining can restore it from session logs still on your machine. +from the last 90 days, starting no earlier than July 29, 2026. Leaving deletes +your published history. Rejoining restores only the history within that window +that is still available in your local session logs. ## Machine Resources diff --git a/apps/docs/content/docs/workspaces.mdx b/apps/docs/content/docs/workspaces.mdx index 693cb7ee01f..208b393ae6f 100644 --- a/apps/docs/content/docs/workspaces.mdx +++ b/apps/docs/content/docs/workspaces.mdx @@ -5,7 +5,7 @@ description: Isolated environments for each git branch ## Core Concept -Each workspace = one git branch. Local project workspaces are isolated git worktrees with their own directory, terminal, and ports. Cloud workspaces use a separate clone. The exception: [sessions](#sessions), which get a managed scratch folder instead of a branch. +A workspace gives a task its own directory, terminals, and ports. Local project workspaces use isolated git worktrees; cloud workspaces use separate clones. [Sessions](#sessions) use a managed scratch folder without requiring a project. @@ -21,7 +21,7 @@ In the prompt-first workspace flow, **Link pull request** lets you search by tit If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise Superset generates a name from your prompt. Per-project **Naming instructions** (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/". -Each workspace gets: +Each new branch-based workspace gets: - Own git branch - Own working directory - Own terminal sessions @@ -31,7 +31,7 @@ New local worktrees use `//` directories. ### Cloud Workspaces -When cloud workspaces are available to your account, the selected branch is the base for a new `superset/-` working branch. Multi-repository workspaces create the same working branch name in each repository, from that repository's base. You can attach images to the initial prompt; the agent receives them when the workspace starts. +When cloud workspaces are available to your account, Superset creates a new working branch from the selected base. For multiple repositories, it uses the same working branch name in each. Attach images to the initial prompt to give the agent visual context when it starts. ## Import Worktrees From 68fb55c6ca06271823c77cc5f2dc711238919470 Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Wed, 23 Sep 2026 10:41:30 -0700 Subject: [PATCH 3/4] docs: trim repeated explanations across user guides --- TODO.md | 4 ++++ apps/docs/content/docs/agent-status.mdx | 8 ++----- apps/docs/content/docs/editor.mdx | 8 +++---- apps/docs/content/docs/first-workspace.mdx | 16 +++++-------- apps/docs/content/docs/orchestration.mdx | 16 +++---------- apps/docs/content/docs/ports.mdx | 26 +++++----------------- apps/docs/content/docs/pull-requests.mdx | 12 +++++----- apps/docs/content/docs/tasks.mdx | 10 ++++----- 8 files changed, 33 insertions(+), 67 deletions(-) diff --git a/TODO.md b/TODO.md index 9c5c5481987..03075a136a7 100644 --- a/TODO.md +++ b/TODO.md @@ -8,3 +8,7 @@ ## 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. diff --git a/apps/docs/content/docs/agent-status.mdx b/apps/docs/content/docs/agent-status.mdx index fff493cc839..499d5cda2e9 100644 --- a/apps/docs/content/docs/agent-status.mdx +++ b/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. diff --git a/apps/docs/content/docs/editor.mdx b/apps/docs/content/docs/editor.mdx index 5f448fce66f..c483971ad01 100644 --- a/apps/docs/content/docs/editor.mdx +++ b/apps/docs/content/docs/editor.mdx @@ -3,7 +3,7 @@ title: Editor & Files description: File explorer, built-in editor, and cross-workspace search --- -You don't have to leave Superset to look at or fix a file. Each workspace has a file tree, a fast built-in editor, and search that spans workspaces. +Each workspace has a file tree, a built-in editor, and search across workspaces. ## File Explorer @@ -19,8 +19,6 @@ Browse and manage your workspace's files from the sidebar: ## Built-in Editor -The editor is CodeMirror-based: small, fast to load, and light on memory, built for quick fixes between agent runs, not to replace your IDE. - ![The built-in editor](/images/codemirror.png) Ways in: @@ -46,7 +44,7 @@ Web links in Markdown previews follow **Settings → Links**. By default, Shift- ## Cross-Workspace Search -The search bar can search across all open workspaces, not just the active one, useful when you're running parallel workstreams and can't remember which branch has the thing. +The search bar searches across all open workspaces. ![Cross-workspace search](/images/search-bar.png) @@ -61,4 +59,4 @@ Images open fitted to the pane, with standard viewer navigation: ## Tabs, Splits, and Panes -The whole workspace shell is composable: **Tab → Split → Pane** with drag-and-drop everywhere. Drop a pane onto the tab strip to spawn a new tab; mix terminals, files, diffs, and browser panes in one layout. The browser pane keeps its state when you switch workspaces. +Drop a pane onto the tab strip to create a new tab; mix terminals, files, diffs, and browser panes in one layout. The browser pane keeps its state when you switch workspaces. diff --git a/apps/docs/content/docs/first-workspace.mdx b/apps/docs/content/docs/first-workspace.mdx index dac88a54346..e406dc6dc00 100644 --- a/apps/docs/content/docs/first-workspace.mdx +++ b/apps/docs/content/docs/first-workspace.mdx @@ -3,7 +3,7 @@ title: Your First Parallel Session description: Go from install to three agents working in parallel, then ship the best result --- -This is the most important page in the docs. In about ten minutes you'll add a repo, put three agents to work on isolated branches, and merge the winner. +In about ten minutes you'll add a repo, put three agents to work on isolated branches, and merge the winner. ## 1. Add a Repository @@ -13,9 +13,9 @@ Add your repo from a local folder or clone a remote repository. In the clone dia ## 2. Create a Workspace with a Prompt -Press **⌘N**. Each workspace is an isolated git worktree on its own branch: no stashing, no `git checkout` whiplash, and nothing an agent does here touches your other work. +Press **⌘N** to create an isolated git worktree on its own branch. -In the prompt-first flow, describe the task, pick an agent, and create. The agent starts working on your prompt immediately. (The **Auto-run command** toggle lives on the tasks surfaces; see [Agent Integration](/agent-integration).) +In the prompt-first flow, describe the task, pick an agent, and create. The agent starts working on your prompt immediately. A good first prompt if your repo needs dependencies or env files: @@ -30,15 +30,13 @@ Future workspaces will then install dependencies and copy env files automaticall ## 3. Fan Out to Three Agents -Now the part worktrees make possible. Press **⌘N** twice more and give each workspace the same prompt with a different agent, say Claude Code, Codex, and Amp: +Press **⌘N** twice more and give each workspace the same prompt with a different agent, say Claude Code, Codex, and Amp: ```text Find a small bug in this repo and fix it. Explain the bug and the fix in your final message. ``` -Each agent works on its own branch, in its own directory, with its own terminal. They can't step on each other, and none of them touch `main`. - ## 4. Watch Them Work - The sidebar shows each workspace's status at a glance @@ -63,13 +61,11 @@ If a losing attempt had one good idea, select those lines in its diff and copy t ## 7. Clean Up -Delete the other workspaces. [Lifecycle teardown scripts](/setup-teardown-scripts) run automatically, and the worktrees are removed. Deleting a workspace after merging is the normal rhythm, not an edge case. +Delete the other workspaces. [Lifecycle teardown scripts](/setup-teardown-scripts) run automatically, and the worktrees are removed. ## You Now Know the Core Loop -Delegate in workspaces, review in diffs, integrate through branches and PRs. Everything else in Superset builds on this loop. - -Named workflows to try next: +Try these workflows next: } title="Race Agents on One Task" href="/recipes/race-agents"> diff --git a/apps/docs/content/docs/orchestration.mdx b/apps/docs/content/docs/orchestration.mdx index 0a1dee97272..aa4c7babc4b 100644 --- a/apps/docs/content/docs/orchestration.mdx +++ b/apps/docs/content/docs/orchestration.mdx @@ -4,10 +4,10 @@ description: Turn the agent you're already talking to into a coordinator of othe --- - the fan-out is mechanical: many similar slices, clear acceptance criteria, and results a coordinator can verify against tests. For work you want to review step by step, use the manual recipes above. + the fan-out is mechanical: many similar slices, clear acceptance criteria, and results a coordinator can verify against tests. For work you want to review step by step, use the [parallel workstreams recipe](/recipes/parallel-workstreams). -The `superset:orchestrate` skill lets one agent coordinate many. Ask the agent you're already talking to for parallel work, and it runs the whole job through the Superset CLI: an isolated workspace per worker, an agent launched in each, follow-ups sent over their terminals, results collected at the end. +The `superset:orchestrate` skill lets one agent coordinate workers in separate workspaces through the Superset CLI. ![Agents working in parallel workspaces](/images/agents-race.png) @@ -15,17 +15,7 @@ The coordinator can be Claude Code or Codex; the workers can be any mix of agent ## Install -The desktop app [ships this skill automatically](/skills), so if you use Superset, your agents already have it. For standalone agents: - -```bash -npx skills add superset-sh/skills -``` - -Claude Code users can also install via the plugin marketplace: - -```text -/plugin marketplace add superset-sh/superset -``` +The desktop app includes this skill. For standalone agents, see [Skills installation](/skills#installation). ## What to Ask For diff --git a/apps/docs/content/docs/ports.mdx b/apps/docs/content/docs/ports.mdx index 09055ebb3d9..3da8faf40de 100644 --- a/apps/docs/content/docs/ports.mdx +++ b/apps/docs/content/docs/ports.mdx @@ -19,13 +19,7 @@ Superset does not assign per-workspace port ranges. It discovers listening ports ## Port Labels -Add friendly names to automatically detected ports with a workspace -configuration file. Useful for: - -- Providing meaningful labels for your team -- Making common dev-server ports easier to scan in the UI - -Create `.superset/ports.json` in your repository: +Label detected ports by creating `.superset/ports.json` in your repository: ```json { @@ -42,19 +36,15 @@ Create `.superset/ports.json` in your repository: - `label` - Display text shown in tooltip **Behavior:** -- Dynamic port discovery is still authoritative -- `ports.json` only labels ports that Superset already detects as listening +- Labels apply only to ports detected as listening - Ports without a matching label still appear -- Label entries for ports that are not currently listening are ignored - Each workspace reads labels from its own worktree's file - Changes are detected automatically - Ports can be opened at `localhost:PORT` from the browser action (remote workspace ports are [forwarded to your machine](#remote-access) first) **Error Handling:** -If `ports.json` is malformed: -- Labels from that file are ignored until fixed -- Detected ports still appear without those labels +If `ports.json` is malformed, detected ports still appear without labels until you fix the file. **Tips:** - Commit `.superset/ports.json` to share port labels with your team @@ -62,11 +52,7 @@ If `ports.json` is malformed: ## Remote Access -When a workspace lives on a [remote host](/remote-access), the sidebar lists ports listening **on that host**. When you select a remote workspace, the desktop app forwards each of its ports to the same port number on your machine, so `localhost:PORT` reaches the host. Only ports that the workspace started are forwarded. When you select another workspace, the forwards move to that workspace. - -If a local process already uses the port, the row shows **local port busy**. Stop the local process from the row (when a Superset workspace started it), or pick **Use another port** to map the remote port to a free local port. The row then shows the mapping, for example `3000 → localhost:54321`. - -Forwarding needs a host on the current relay running host-service 1.26 or newer. For other hosts, forward the port yourself. +The desktop app forwards detected ports from the selected remote workspace to your machine. If a local port is busy, choose **Use another port** from its row. See [remote port forwarding](/remote-access#ports-on-a-remote-host) for requirements and behavior, or forward a port yourself below. ### Forward a port yourself @@ -86,6 +72,4 @@ Both work for servers that only listen on loopback. If the server binds `0.0.0.0 ## Discovery and Updates -Port discovery runs in each host server, not in the desktop renderer. The host server watches terminal process trees, scans for listening ports, resolves any matching port label, and publishes `port:changed` events when ports appear or disappear. - -The desktop sidebar keeps one ports query per online host. It patches that cached host snapshot from port events, batching bursts so updates stay responsive without refetching every time a port changes. A slower fallback refetch still runs so the UI recovers if an event is missed during reconnect. +The port list updates as workspace processes start and stop listening. diff --git a/apps/docs/content/docs/pull-requests.mdx b/apps/docs/content/docs/pull-requests.mdx index 7bde5209aa1..3b661ca4d45 100644 --- a/apps/docs/content/docs/pull-requests.mdx +++ b/apps/docs/content/docs/pull-requests.mdx @@ -3,7 +3,7 @@ title: Pull Requests description: Review, check, and merge PRs from your projects without leaving the app --- -The **Pull requests** view brings the PRs from your projects' GitHub repositories into Superset, so the loop of reviewing, fixing, and merging agent work never leaves the app. It's a destination in the dashboard sidebar with a resizable split view: the PR list on the left, and a full detail view — rendered description, CI checks, and the complete diff — on the right. +Open **Pull requests** in the dashboard sidebar to review PRs from your projects' GitHub repositories. The resizable split view shows the PR list on the left and the selected PR's description, checks, and diff on the right. ![The Pull requests split view: filterable list on the left, detail with rendered markdown on the right](/images/pull-requests-view.png) @@ -14,7 +14,7 @@ The list shows every PR from the repositories behind your projects. Each row car - **State tabs**: **All**, **Open**, or **Merged** - **Repository**: multi-select across your projects' repos - **Author**: filter to a specific GitHub author -- **Reviews**: review-status filter — *No reviews*, *Review required*, *Approved review*, *Changes requested*, *Reviewed by you*, *Not reviewed by you*, *Awaiting review from you*, or *Awaiting review from you or your team* +- **Reviews**: review-status filter: *No reviews*, *Review required*, *Approved review*, *Changes requested*, *Reviewed by you*, *Not reviewed by you*, *Awaiting review from you*, or *Awaiting review from you or your team* - **Search**: find PRs by title or number Filters persist, so the view comes back the way you left it. Active filters show a count badge next to the search box. @@ -25,7 +25,7 @@ Selecting a PR opens it in the right pane, with **Summary** and **Code** tabs. T ### Summary -The PR description renders as full markdown — headings, lists, code spans, and links. Alongside it: +The Summary tab shows the PR description alongside: - **Checks**: every CI check with its status and a link to the run on GitHub. The header summarizes the state at a glance ("All 12 passed"). Cancelled checks count as failures, not successes. - Review status and reviewers for the PR @@ -41,13 +41,11 @@ The **Code** tab is a complete diff viewer: a file tree with per-file added/dele ### Comment Straight to an Agent -Select lines in the Code tab and write a comment — then send it to an agent instead of (or as well as) leaving it on GitHub. The comment goes out with the file, line range, and side baked in: +Select lines in the Code tab and send a comment to an agent, optionally posting it on GitHub too. The agent receives the file, line range, and diff side: - If a workspace is already linked to the PR, send it to one of its **running agent terminals**, or start a **new agent session** there - If no workspace exists yet, Superset **creates a PR-checkout workspace** and launches the agent with your comment as its first prompt -That turns "this function should handle the empty case" from a review comment into a running fix. - ## Actions From the detail header: @@ -63,4 +61,4 @@ Merging, closing, and commenting act on the real PR through your GitHub connecti ## Where PRs Come From -PRs sync from the GitHub repositories of your connected projects; connect GitHub under project settings and the list stays fresh automatically. PR-based workspaces also surface review status and checks on their sidebar entries — see [PR Status](/workspaces#pr-status) — and the [PR feedback recipe](/recipes/pr-feedback) shows the full loop of turning review comments into agent runs. +Connect GitHub under project settings to sync PRs. Linked workspaces also show [PR status](/workspaces#pr-status) in the sidebar. For a review workflow, see the [PR feedback recipe](/recipes/pr-feedback). diff --git a/apps/docs/content/docs/tasks.mdx b/apps/docs/content/docs/tasks.mdx index f998a39dc28..4842244e04a 100644 --- a/apps/docs/content/docs/tasks.mdx +++ b/apps/docs/content/docs/tasks.mdx @@ -3,7 +3,7 @@ title: Tasks description: Track work items and delegate them to agents without leaving the app --- -The **Tasks** view brings your issue tracker into Superset, so delegating a task to an agent doesn't start with a copy-paste from Linear or GitHub. It's a destination in the dashboard sidebar with independent filters that are restored when you come back. Pull requests have their own view — see [Pull Requests](/pull-requests). +Open **Tasks** in the dashboard sidebar to browse issues and delegate them to agents. Filters persist between visits. [Pull Requests](/pull-requests) has a separate view. ![The Tasks view on the GitHub issues source, with per-row Add to workspace actions](/images/task-list.png) @@ -22,19 +22,19 @@ The Linear source lists issues from the whole connected workspace; filter by pro - **Filters** for project, task state, and assignee; empty filters mean everything - **Semantic search**: find tasks by meaning, not just keywords - **Multi-select**: check several tasks and act on them together -- **Create tasks** from the desktop with the **New task** modal — title, description, status, priority, and assignee +- **Create tasks** from the desktop with the **New task** modal: title, description, status, priority, and assignee ![Creating a task from the desktop](/images/create-task.png) -Opening a task shows its full detail: an editable title, description, activity, and a properties sidebar for status, priority, and assignee — plus quick actions without switching to Linear. +Opening a task shows its full detail: an editable title, description, activity, and a properties sidebar for status, priority, and assignee. ## From Task to Workspace -The point of having tasks in Superset is delegation. Launch an agent from a task and the task's content becomes the agent's prompt: +Launch an agent from a task and the task's content becomes the agent's prompt: - **Run in workspace** on a task (or a multi-selection of tasks) picks a project and an agent, then creates a workspace per task with the agent already working - The **Auto-run command** toggle controls whether each agent starts immediately or stages the command for review - The **Task Prompt Template** (per agent, under **Settings → Agents**) controls how a task is turned into the agent's prompt - On the GitHub issues source, **Add to workspace** does the same for a single issue -When the agents finish, their branches come back as PRs — review and merge them from [Pull Requests](/pull-requests). +After creating a PR, review and merge it from [Pull Requests](/pull-requests). From c91e8d82a87871bc34c3eb9e7377571599c3cee0 Mon Sep 17 00:00:00 2001 From: Kiet Ho Date: Wed, 23 Sep 2026 10:57:54 -0700 Subject: [PATCH 4/4] docs: clarify iPhone cloud workspace requirements --- apps/docs/content/docs/install.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/content/docs/install.mdx b/apps/docs/content/docs/install.mdx index 45f2426b208..5d8bb65d954 100644 --- a/apps/docs/content/docs/install.mdx +++ b/apps/docs/content/docs/install.mdx @@ -30,7 +30,7 @@ Paid organizations also get a **Get the best out of Pro** sidebar checklist for ## iPhone -[Download Superset for iPhone](https://apps.apple.com/app/id6788926383) to continue your agents from your phone. You need **iOS 26 or later**, **Superset Pro**, and a connected computer with **Remote Access enabled**. +[Download Superset for iPhone](https://apps.apple.com/app/id6788926383) to continue your agents from your phone. You need **iOS 26 or later** and **Superset Pro**. Enable **Remote Access** to reach agents on your computer. If cloud workspaces are enabled for your account, you can use them without a connected computer. Follow [iPhone setup](/remote-access#connect-from-an-iphone) to connect your computer. Android is not available yet; join the [Android waitlist](https://superset.sh/mobile#android).