docs: reorg sidebar, merge install+overview, add CLI section, rewrite MCP for v2#3926
Merged
saddlepaddle merged 2 commits intomainfrom May 1, 2026
Merged
docs: reorg sidebar, merge install+overview, add CLI section, rewrite MCP for v2#3926saddlepaddle merged 2 commits intomainfrom
saddlepaddle merged 2 commits intomainfrom
Conversation
…write MCP for v2 Single-tree docs sidebar (drops the per-product switcher in favor of one flat sidebar with section dividers). CLI is now a top-level section between Core Features and Guides — three pages (Getting Started, CLI Reference, Host Server, Env Vars). The MCP page is rewritten for v2. User-facing changes: - New Overview page (merge of installation.mdx + overview.mdx) modeled on opencode's intro+install+orientation flow. Single curl install + Homebrew tap; from-source instructions dropped. - New CLI section in the docs sidebar (no more product switcher / hidden dropdown). CLI Getting Started, CLI Reference, Host Server (new), and Env Vars sit alongside the desktop docs. - New `cli/host-server.mdx` getting-started for setting up a host server on a CLI-only or headless machine: prerequisites (git, gh, GH_TOKEN/GITHUB_TOKEN for sandboxes), agent CLI install table, authenticate, start, create a project, create a workspace, lifecycle. - "Host service" → "Host server" everywhere user-facing (folks recognize "server" more readily than "service"). Code internals are unchanged. - Beta callouts on /cli/getting-started and /cli/cli-reference. The MCP page replaces its old beta callout with a v2 framing note that points v1 users at the deprecated endpoint. - MCP page rewritten for v2: capabilities table reflects the actual v2 surface (tasks, workspaces, automations, projects, hosts), tool list uses the new underscore-prefixed names (`tasks_create`, `automations_set_prompt`, etc.), and example usage features automations. - Sidebar restyle: search above, Overview/CLI/etc. as section dividers, no product switcher. - `cli/projects create` and MCP `projects_create` documented (host service already supports both modes via `project.create`; CLI/MCP wrappers to follow in a separate PR). Env vars page adds GH_TOKEN/GITHUB_TOKEN for headless gh auth.
Greptile SummaryDocs-only reorganization: drops the per-product sidebar switcher in favour of a single flat sidebar, merges Confidence Score: 5/5Safe to merge — no code changes outside the docs app, all findings are P2. All changes are documentation and a small sidebar component refactor. No logic bugs found. The only finding is a minor discrepancy between the PR test plan (Amp tab is last) and the actual tab order in mcp.mdx, which is a P2 style/consistency note and does not block merge. apps/docs/content/docs/mcp.mdx — verify intended tab ordering matches the test plan.
|
| Filename | Overview |
|---|---|
| apps/docs/src/app/(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsx | Removes per-product switcher logic; replaces with recursive visit() that flattens the full page tree into a single sections array. Logic is correct given the updated meta.json structure. |
| apps/docs/src/app/(docs)/components/Sidebar/Sidebar.tsx | Drops product menu state, associated keyboard handler, and useEffect that reset open-sections on product change. Correctly simplified now that sections is a static module-level constant. |
| apps/docs/content/docs/mcp.mdx | URL updated from v1 to v2 across all config blocks; capabilities and tool list rewritten for v2. Amp CLI tab remains first in the CLI Options Tabs component, contrary to the test plan's note that it should be last. |
| apps/docs/content/docs/cli/host-server.mdx | New page covering prerequisites, auth, start/stop lifecycle, project and workspace creation on a headless machine. Content is accurate and well-structured. |
| apps/docs/content/docs/cli/meta.json | Removes root:true and section separators; CLI is now a regular folder referenced from the top-level meta.json. host-server added to pages list. |
| apps/docs/content/docs/meta.json | Removes installation entry; adds CLI section separator and four CLI page references after mcp. |
| apps/docs/content/docs/overview.mdx | Merges old installation.mdx content into overview; adds video, requirements, install button, and What's next link list. Clean consolidation. |
| apps/docs/content/docs/cli/cli-reference.mdx | host service → host server throughout; projects create command fully documented; quoted CLI error message preserving old wording is intentional (reflects actual binary output). |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[source.pageTree.children] --> B[parseSectionsFromSeparators]
B --> C{visit each node}
C -->|separator node| D[Create new SidebarSection\nparse icon + title]
C -->|page node| E[Append to currentSection.items]
C -->|folder node| F[Recurse into children]
F --> C
D --> G[sections array]
E --> G
G --> H[Sidebar.tsx renders sections]
H --> I[Flat single-sidebar UI\nno product switcher]
Prompt To Fix All With AI
Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 1
apps/docs/content/docs/mcp.mdx:28
**Amp tab order contradicts test plan**
The test plan states "Amp tab is last," but `Amp CLI` is the first entry in the `items` array here (and again at line 84 for the Manual Configuration tabs). If the intent is to move Amp to the end, the arrays need to be reordered; otherwise the test plan note should be removed to avoid confusion during review.
```suggestion
<Tabs items={["Claude Code", "Codex", "Gemini CLI", "Open Code", "Amp CLI"]}>
```
Reviews (1): Last reviewed commit: "docs: reorg sidebar, merge installation+..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| @@ -24,22 +28,22 @@ Superset provides an [MCP (Model Context Protocol)](https://modelcontextprotocol | |||
| <Tabs items={["Amp CLI", "Claude Code", "Codex", "Gemini CLI", "Open Code"]}> | |||
There was a problem hiding this comment.
The test plan states "Amp tab is last," but Amp CLI is the first entry in the items array here (and again at line 84 for the Manual Configuration tabs). If the intent is to move Amp to the end, the arrays need to be reordered; otherwise the test plan note should be removed to avoid confusion during review.
Suggested change
| <Tabs items={["Amp CLI", "Claude Code", "Codex", "Gemini CLI", "Open Code"]}> | |
| <Tabs items={["Claude Code", "Codex", "Gemini CLI", "Open Code", "Amp CLI"]}> |
Prompt To Fix With AI
This is a comment left during a code review.
Path: apps/docs/content/docs/mcp.mdx
Line: 28
Comment:
**Amp tab order contradicts test plan**
The test plan states "Amp tab is last," but `Amp CLI` is the first entry in the `items` array here (and again at line 84 for the Manual Configuration tabs). If the intent is to move Amp to the end, the arrays need to be reordered; otherwise the test plan note should be removed to avoid confusion during review.
```suggestion
<Tabs items={["Claude Code", "Codex", "Gemini CLI", "Open Code", "Amp CLI"]}>
```
How can I resolve this? If you propose a fix, please make it concise.
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughAdds Terminal CLI docs (including a Host Server page), introduces Changes
Sequence Diagram(s)sequenceDiagram
participant CLI as "CLI"
participant Host as "Host Server"
participant Git as "Git / GH"
participant Cloud as "Cloud Project DB"
CLI->>Host: POST /projects/create (name, --url|--path, --host?)
alt clone mode (--url)
Host->>Git: git clone --url into host filesystem
Git-->>Host: repoPath
else import mode (--path)
Host->>Host: validate local repo path
end
Host->>Cloud: create cloud project record (project metadata)
Cloud-->>Host: { projectId, mainWorkspaceId? }
Host-->>CLI: JSON { projectId, repoPath, mainWorkspaceId }
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 6/8 reviews remaining, refill in 14 minutes and 43 seconds.Comment |
Contributor
🧹 Preview Cleanup CompleteThe following preview resources have been cleaned up:
Thank you for your contribution! 🎉 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
apps/docs/src/app/(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsx (1)
42-54:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPrevent page leakage when a separator label is malformed.
At Line 42, when a
separatorfails regex parsing,currentSectionkeeps its old value, so laterpagenodes can be attached to the wrong section.Proposed fix
const visit = (node: PageTreeNode) => { if (node.type === "separator") { + currentSection = null; const name = String(node.name ?? ""); const match = name.match(/^(\w+)\s+(.+)$/); if (match) { const [, iconName, title] = match; currentSection = { title, Icon: iconMap[iconName] || Rocket, items: [], }; sections.push(currentSection); }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/docs/src/app/`(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsx around lines 42 - 54, When handling a separator node in SidebarContent.tsx, a failed regex parse leaves the previous currentSection in place causing subsequent page nodes to be appended to the wrong section; update the separator branch in the block that checks node.type === "separator" so that when match is falsy you explicitly set currentSection = undefined (and do not push a section) to prevent leaking pages into the prior section (symbols: node.type, currentSection, match, sections, iconMap, Rocket).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/docs/content/docs/cli/cli-reference.mdx`:
- Around line 430-433: Update the error example string to use the consistent
“host server” terminology: find the example that currently reads "Host service
for this machine isn't running. Run: superset start." and change it to "Host
server for this machine isn't running. Run: superset start." (ensure you update
only the displayed message in apps/docs/content/docs/cli/cli-reference.mdx so
the rest of the text/behavior remains unchanged).
- Around line 363-391: Add an explicit availability caveat under the Command
block for name="superset projects create" stating that the CLI wrapper or
hosting integration is not yet generally available (GA) and that the command may
not be available or may require a specific wrapper version; update the prose
immediately after the description (near the "Register a project on a host."
paragraph) to include a short note about the pending wrapper shipping and any
workaround (e.g., use local host only or specific version) so readers are aware
of possible command/tooling mismatches.
In `@apps/docs/content/docs/overview.mdx`:
- Line 6: Change the lead sentence "Superset is an open source AI coding
platform." to use the hyphenated compound adjective "open-source" so it reads
"Superset is an open-source AI coding platform." Update the string in the
overview lead (the lead sentence in the overview.mdx content) accordingly to
maintain correct grammar and consistent docs style.
---
Outside diff comments:
In
`@apps/docs/src/app/`(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsx:
- Around line 42-54: When handling a separator node in SidebarContent.tsx, a
failed regex parse leaves the previous currentSection in place causing
subsequent page nodes to be appended to the wrong section; update the separator
branch in the block that checks node.type === "separator" so that when match is
falsy you explicitly set currentSection = undefined (and do not push a section)
to prevent leaking pages into the prior section (symbols: node.type,
currentSection, match, sections, iconMap, Rocket).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 86e2e01f-7b19-436b-ab15-4fa21d965fc5
📒 Files selected for processing (13)
apps/docs/content/docs/cli/cli-reference.mdxapps/docs/content/docs/cli/env-vars.mdxapps/docs/content/docs/cli/getting-started.mdxapps/docs/content/docs/cli/host-server.mdxapps/docs/content/docs/cli/meta.jsonapps/docs/content/docs/installation.mdxapps/docs/content/docs/mcp.mdxapps/docs/content/docs/meta.jsonapps/docs/content/docs/overview.mdxapps/docs/content/docs/ports.mdxapps/docs/src/app/(docs)/components/Sidebar/Sidebar.tsxapps/docs/src/app/(docs)/components/Sidebar/components/SidebarContent/SidebarContent.tsxapps/docs/src/app/(docs)/components/Sidebar/components/SidebarContent/index.ts
💤 Files with no reviewable changes (1)
- apps/docs/content/docs/installation.mdx
Comment on lines
+363
to
+391
| <Command | ||
| name="superset projects create" | ||
| options={[ | ||
| { flag: "--name <name>", required: true, description: "Display name for the project." }, | ||
| { flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." }, | ||
| { flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." }, | ||
| { flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." }, | ||
| { flag: "--host <id>", description: "Target host. Defaults to the local machine." }, | ||
| ]} | ||
| output={`{ | ||
| projectId: string; | ||
| repoPath: string; | ||
| mainWorkspaceId: string | null; | ||
| }`} | ||
| > | ||
| Register a project on a host. Two modes: | ||
|
|
||
| - **Clone** — pass `--url` and `--parent-dir`. The host clones the repo | ||
| into `<parent-dir>/<derived-name>/`. | ||
| - **Import** — pass `--path` to register a repo that already exists on disk. | ||
|
|
||
| Either way, the cloud project row is created and the host's main workspace | ||
| is ensured. | ||
|
|
||
| ```bash | ||
| superset projects create --name "my-app" --url https://github.com/org/my-app.git --parent-dir ~/code | ||
| superset projects create --name "my-app" --path ~/code/my-app | ||
| ``` | ||
| </Command> |
Contributor
There was a problem hiding this comment.
Add an explicit availability caveat for projects create.
This section reads as fully GA, but the PR notes wrapper shipping is still pending. Without a note, users can hit command/tooling mismatch immediately.
Proposed doc tweak
<Command
name="superset projects create"
@@
>
+<Callout type="warn">
+`superset projects create` may not be available in older CLI builds yet.
+If you don't see this command, upgrade to the latest CLI release.
+</Callout>
+
Register a project on a host. Two modes:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| <Command | |
| name="superset projects create" | |
| options={[ | |
| { flag: "--name <name>", required: true, description: "Display name for the project." }, | |
| { flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." }, | |
| { flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." }, | |
| { flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." }, | |
| { flag: "--host <id>", description: "Target host. Defaults to the local machine." }, | |
| ]} | |
| output={`{ | |
| projectId: string; | |
| repoPath: string; | |
| mainWorkspaceId: string | null; | |
| }`} | |
| > | |
| Register a project on a host. Two modes: | |
| - **Clone** — pass `--url` and `--parent-dir`. The host clones the repo | |
| into `<parent-dir>/<derived-name>/`. | |
| - **Import** — pass `--path` to register a repo that already exists on disk. | |
| Either way, the cloud project row is created and the host's main workspace | |
| is ensured. | |
| ```bash | |
| superset projects create --name "my-app" --url https://github.com/org/my-app.git --parent-dir ~/code | |
| superset projects create --name "my-app" --path ~/code/my-app | |
| ``` | |
| </Command> | |
| <Command | |
| name="superset projects create" | |
| options={[ | |
| { flag: "--name <name>", required: true, description: "Display name for the project." }, | |
| { flag: "--url <url>", description: "Clone from a Git URL. Mutually exclusive with `--path`." }, | |
| { flag: "--parent-dir <path>", description: "Where to clone into. Required with `--url`." }, | |
| { flag: "--path <path>", description: "Import an existing local repo. Mutually exclusive with `--url`." }, | |
| { flag: "--host <id>", description: "Target host. Defaults to the local machine." }, | |
| ]} | |
| output={`{ | |
| projectId: string; | |
| repoPath: string; | |
| mainWorkspaceId: string | null; | |
| }`} | |
| > | |
| <Callout type="warn"> | |
| `superset projects create` may not be available in older CLI builds yet. | |
| If you don't see this command, upgrade to the latest CLI release. | |
| </Callout> | |
| Register a project on a host. Two modes: | |
| - **Clone** — pass `--url` and `--parent-dir`. The host clones the repo | |
| into `<parent-dir>/<derived-name>/`. | |
| - **Import** — pass `--path` to register a repo that already exists on disk. | |
| Either way, the cloud project row is created and the host's main workspace | |
| is ensured. | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/content/docs/cli/cli-reference.mdx` around lines 363 - 391, Add an
explicit availability caveat under the Command block for name="superset projects
create" stating that the CLI wrapper or hosting integration is not yet generally
available (GA) and that the command may not be available or may require a
specific wrapper version; update the prose immediately after the description
(near the "Register a project on a host." paragraph) to include a short note
about the pending wrapper shipping and any workaround (e.g., use local host only
or specific version) so readers are aware of possible command/tooling
mismatches.
Comment on lines
430
to
433
| If the resolved host is the local machine but the host server isn't | ||
| responding, the CLI errors with | ||
| `Host service for this machine isn't running. Run: superset start.` | ||
| rather than silently falling through to the cloud. |
Contributor
There was a problem hiding this comment.
Use consistent “host server” terminology in the error example.
Line 432 still says “Host service…”, which conflicts with the renamed terminology in this same section.
Proposed wording update
-`Host service for this machine isn't running. Run: superset start.`
+`Host server for this machine isn't running. Run: superset start.`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| If the resolved host is the local machine but the host server isn't | |
| responding, the CLI errors with | |
| `Host service for this machine isn't running. Run: superset start.` | |
| rather than silently falling through to the cloud. | |
| If the resolved host is the local machine but the host server isn't | |
| responding, the CLI errors with | |
| `Host server for this machine isn't running. Run: superset start.` | |
| rather than silently falling through to the cloud. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/content/docs/cli/cli-reference.mdx` around lines 430 - 433, Update
the error example string to use the consistent “host server” terminology: find
the example that currently reads "Host service for this machine isn't running.
Run: superset start." and change it to "Host server for this machine isn't
running. Run: superset start." (ensure you update only the displayed message in
apps/docs/content/docs/cli/cli-reference.mdx so the rest of the text/behavior
remains unchanged).
| --- | ||
|
|
||
| ## What is Superset? | ||
| Superset is an open source AI coding platform. It's available as a desktop IDE, a command-line interface, or an MCP server. |
Contributor
There was a problem hiding this comment.
Hyphenate the compound adjective in the lead sentence.
Use “open-source” before the noun phrase for correct grammar and cleaner docs copy.
✏️ Suggested edit
-Superset is an open source AI coding platform. It's available as a desktop IDE, a command-line interface, or an MCP server.
+Superset is an open-source AI coding platform. It's available as a desktop IDE, a command-line interface, or an MCP server.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Superset is an open source AI coding platform. It's available as a desktop IDE, a command-line interface, or an MCP server. | |
| Superset is an open-source AI coding platform. It's available as a desktop IDE, a command-line interface, or an MCP server. |
🧰 Tools
🪛 LanguageTool
[grammar] ~6-~6: Use a hyphen to join words.
Context: ... with Superset. --- Superset is an open source AI coding platform. It's availabl...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/docs/content/docs/overview.mdx` at line 6, Change the lead sentence
"Superset is an open source AI coding platform." to use the hyphenated compound
adjective "open-source" so it reads "Superset is an open-source AI coding
platform." Update the string in the overview lead (the lead sentence in the
overview.mdx content) accordingly to maintain correct grammar and consistent
docs style.
…quote - mcp.mdx: move Amp CLI to last position in both Setup tab lists (matches what the PR description claimed; greptile flagged the contradiction) - cli-reference.mdx: paraphrase the local-host error sentence instead of quoting an exact string with stale "Host service" wording (the CLI binary still emits the old phrasing; quoting a renamed version would be inaccurate)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs reorg pass. No code changes outside the docs app.
Sidebar
Pages
installation.mdxandoverview.mdx. Modeled on opencode's intro→install→orientation flow. Single `curl | sh` (auto-detects platform) + Homebrew tap. From-source instructions dropped.Drift to flag
The Overview docs `projects create` for both CLI and MCP, but the CLI/MCP wrappers don't ship yet. Host service has the underlying `project.create` (clone + importLocal modes). The wrapper code lands in a follow-up PR — at that point this docs PR will already match. Acceptable to merge first or hold; either way the doc/code drift window is narrow.
Test plan
Summary by CodeRabbit
New Features
superset projects createCLI command (clone vs import modes, optional host target, JSON output).Documentation
Refactor