docs: restructure the site — Agents & IDE chapters, Installation, audit gap fixes, Quick start consolidation - #115
Merged
Conversation
Closes #114. Supported IDEs are now visible the moment the docs open: a top-level "IDE integration" sidebar section (right after Getting started) with two mirrored pages, and the landing paragraph links both. ide/vscode.md consolidates what was scattered across cli.md one-liners and initialization notes: the reopen-in-container flow, the customizations.vscode block, the per-stack extension table, and a pointer to the existing hardening page. ide/jetbrains.md documents the path that three merged PRs left invisible: the Gateway flow and customizations.jetbrains block (#77), the per-stack Marketplace plugins with the Ultimate-gating caveats from stack_jetbrains_plugin (#79), the security-relevant `overrideCommand: false` with an explicit do-not-remove warning (#78), the extra DAC_OVERRIDE/CHOWN/FOWNER capabilities, and the `.idea` read-only mount toggle. Strict Sphinx build (-W): clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Both IDE paths now keep their security material on their own page — the JetBrains page already carries overrideCommand/capabilities, so a separate "Hardening the VS Code setup" page under Architecture & security was the odd one out. Content moved verbatim as a "Security hardening" section (headings demoted one level); the two same-page pointers replace the old cross-page links, generated-files.md retargets its deep link, and the sidebar section becomes plain "Architecture". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Per #114 direction: supported agents deserve a top-level section, not paragraphs buried in Getting started. New sidebar chapter "Agents" (between Getting started and IDE integration) with five pages, and the landing paragraph links all four agent names. - agents/claude.md — authentication (moved from secrets.md), host paths (moved from the mounts section), RTK hook, and the claude-yolo alias (verified against agents.bash). - agents/cursor.md — auth + cursor.cli configuration (from secrets.md), host paths and workspace isolation, host-side RTK hook. - agents/codex.md / agents/copilot.md — their full onboarding sections, which had ended up mis-nested under the RTK heading in the README migration. - agents/rtk.md — what RTK is and the opt-out, plus a per-agent setup table linking into the agent pages. initialization.md keeps the init-level material (stacks, mount mechanics and the SANDCAT_* flag table, caches, gitignore) and points at the Agents chapter; secrets.md keeps the generic substitution mechanics; the cli.md deep link retargets. Strict Sphinx build (-W): clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Basic Auth (secrets.md): documents the #85 mechanism that had no docs presence — git base64-encodes username:password, so a placeholder returned by a credential helper never appears in plain text; the addon decodes the Basic blob, substitutes, and re-encodes, gated by the same host allowlist as plain-text substitution. Includes the on-prem GitLab walkthrough (the exact scenario from issue #56) with pointers to upstream_ca_bundles and extra_hosts. Agent container hardening (architecture/overview.md): consolidates the security posture that #90 and #103 introduced but never documented — no-new-privileges, the removed vscode sudo grant (root phase runs in the entrypoint, drops via gosu), no NET_ADMIN despite the shared netns, the public/private volume split, and the read-only .devcontainer overlay; notes the JetBrains capability additions and links the IDE-side boundary. Strict Sphinx build (-W): clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
details move to Configuration Getting started now holds a single page. The quick start's steps absorb the best of the pages they duplicated: step 2 merges the initialization intro (prompt-driven init, skip-flags examples, agent list linking the Agents chapter, stacks list linking the new Configuration pages); step 4 merges Starting the sandbox wholesale (run/--build, claude-yolo, attach semantics, IDE mode). Step 1 gains a pointer to the detailed install options. The detailed install page moves to a top-level "Installation" menu entry just before Configuration. The remaining Initializing-the-sandbox sections become Configuration pages: stacks (devbox), volume-mounts (with the SANDCAT_* flag table), caches, gitignore; the Agent-specific-setup pointer section is dropped (the Agents chapter is in the menu). initialization.md and running.md are gone; every inbound link retargeted (agents, ide, architecture, generated-files, cli reference, cross-page anchors that used to be same-page). Strict Sphinx build (-W): clean. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The caption-less toctree visually merged with the IDE integration group in the RTD theme; a captioned single-page section reads as a proper top-level entry, consistent with the neighbouring groups. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A one-page group under its own caption was redundant; as the first, caption-less toctree the page stands alone at the top of the sidebar. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
shejnowicz
changed the title
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.
Closes #114.
Started as the IDE-integration chapter from the docs-coverage audit and grew — with the maintainer's direction — into a restructuring of the whole site. Commit-by-commit:
ide/vscode.md,ide/jetbrains.md) — top-level sidebar section; the JetBrains page documents what fix(cli): emit customizations.jetbrains when --ide jetbrains #77/fix(cli): set overrideCommand:false so app-init.sh runs in JetBrains #78/feat(cli): install JetBrains stack plugins via customizations.jetbrains #79 left invisible: the Gateway flow,customizations.jetbrains, per-stack Marketplace plugins with Ultimate-gating caveats, a do-not-remove warning foroverrideCommand: false(skippingapp-init.shbypasses the sandbox's TLS/policy wiring), and the extra capabilities.ide/vscode.md— both IDE paths now keep security material on their own page; the sidebar section becomes plain "Architecture".agents/{claude,cursor,codex,copilot,rtk}.md) — per-agent authentication, host paths/mounts, RTK hooks and aliases, moved out of Getting started and secrets.md; agent names on the landing page link here. Codex/Copilot onboarding un-nested from under the RTK heading where the README migration had left it.secrets.mdgains Basic Auth (git credentials): the Add basic auth handling for claude #85 decode→substitute→re-encode mechanism with an on-prem GitLab walkthrough (the issue-Not working git access to gitlab server #56 scenario);architecture/overview.mdgains Agent container hardening: no-new-privileges (Run the agent container with no_new_privs set #90), the removed sudo grant (security(image): remove vscode passwordless-sudo grant #103), no NET_ADMIN in the shared netns, the volume split, the read-only.devcontaineroverlay.SANDCAT_*flag table, caches, gitignore). All 14 inbound links retargeted.Final sidebar:
Quick start · Agents · IDE integration · Installation · Configuration · Architecture · Reference · Operations · Project.Verification
-W --keep-going) clean after every step — it caught and gated all 14 dangling cross-references during the restructure.stack_extension()/stack_jetbrains_plugin(),claude-yoloalias vsagents.bash, Basic Auth mechanics vsmitmproxy_addon_common.py, hardening claims vsDockerfile.app/compose-agent.yml.Preview for reviewers
Until the project is imported on readthedocs.org (which will give every docs PR an automatic preview link in the checks), render this PR locally:
🤖 Generated with Claude Code