Update Help Docs

Update Sculptor Help Docs

⚠️ Deprecated / optional — the help docs are no longer actively maintained. Refreshing docs/help/ is not a required release step and is no longer part of the promote-release follow-up. This skill still works if you deliberately want to update a specific page, but treat any run as optional — don't run it just because a release went out.

Note: docs live in this repo at docs/help/. The Sculptor help docs live here, alongside the code. This skill edits the markdown and images under docs/help/ in the current checkout.

Publishing: /sculptor:help fetches the docs live from imbue-ai/sculptor on GitHub, so edits you make here go live to users once they land on main there. Editing docs/help/ in a local checkout does not by itself change what /sculptor:help returns.

This skill updates the docs under docs/help/ so their prose and screenshots match the current Sculptor app. The docs are served live to /sculptor:help, so accuracy matters: a wrong button name or a stale screenshot ends up in users' answers.

Inputs

• Required: Sculptor version. Format is <major>.<minor>, e.g. 0.27. The skill expects you to already be on release/sculptor-v<version>.0 in the current checkout. It does not change branches for you — if you're on the wrong branch, it stops and tells you. The help docs live at docs/help/ and the images at docs/help/images/. All paths in this document — both the docs and source-path references (sculptor/frontend/src/..., sculptor/sculptor/web/skills.py, etc.) — resolve against the current working directory, which must be the Sculptor checkout on the release branch.

What you do NOT do

• Never commit, branch, or push. This workflow produces an uncommitted diff; the user handles git from there. Confirm this boundary up front if the user hints at automation.
• Never read the large PNG screenshots directly from your own context. Always delegate "describe this image" to a subagent — a dozen 2× screenshots will blow out your context window fast.
• Do not annotate screenshots. No highlight boxes, no arrows, no spotlight/dim effects, no text labels. Use cropping to direct the reader's eye — see Phase 5.
• Do not pause to confirm scope mid-run. Invoking this skill runs the full workflow. Only stop if genuinely blocked (server refuses to start, a destructive action would overwrite user work). "This would take a while" is not a blocker.

No phase is optional

Phases 1–6 run on every invocation, in order, with no shortcuts.

• A phase's output may be empty (no drift in Phase 2, zero reshoots in Phase 4, zero annotations in Phase 5). That is a valid result of running the phase — it is not a license to skip it.
• Every phase has an end-of-phase gate. You may not advance to the next phase until its gate passes.
• If you find yourself thinking "nothing changed so I can skip ahead", re-read this section. The check step of each phase is what decides "nothing changed"; you do not decide that on vibes.
• Hedging words (optional, if needed, when appropriate) do not appear in this skill's phase descriptions. If you think you see one, re-read the containing sentence — it is almost certainly scoped to a sub-choice inside the phase, not to whether the phase itself runs.

Preconditions

Before starting, verify every item below. If any fails, stop and tell the user what needs to change — do not proceed, do not switch branches for them.

1. Current branch matches the version input. Run git rev-parse --abbrev-ref HEAD; it must equal release/sculptor-v<version>.0 (e.g. version 0.27 → branch release/sculptor-v0.27.0). If it doesn't match, tell the user they need to check out that branch first and re-invoke. Don't attempt the checkout yourself — they may have in-flight work on the current branch.
2. Record the commit SHA for the Phase 6 report: git rev-parse HEAD. Keep it in conversation state.
3. The working tree is clean enough to review. Check git status for docs/help/ — the user should be able to tell your changes apart from theirs. If docs/help/ already has uncommitted changes, ask before proceeding.
4. uv, python3, and Pillow (PIL) are available (Pillow is used by the processing script and by the cropping step). The image-processing script is bundled with this skill at .claude/skills/update-help-docs/scripts/process-screenshots.py — it lives in the skill, not under docs/help/.
5. The /auto-qa-changes skill is available. Read that skill before starting — Phase 4 launches its harness every run (to drive the per-image audit, even when no reshoot turns out to be needed), so you need the server lifecycle, port handling, and API details that this skill does not duplicate.

A note on the branch-match rule: if the user just cut a new release, their local branch list may not have release/sculptor-v<version>.0 yet. Suggest git fetch --all --tags && git checkout release/sculptor-v<version>.0 in that case.

Content guidance

The docs are read by external customers running the installed Sculptor app. Three rules shape what belongs in the prose; apply them both in Phase 2 (what to flag as wrong) and Phase 3 (what to write). Violations of any rule are a WRONG verdict even if the underlying claim is technically accurate.

1. Use only words the user sees in the UI. If a concept exists in the code but has no visible name in the app, don't name it in the docs — describe the user-visible behavior instead.

   Example: the frontend splits slash-picker entries across common/builtinSkills.ts and common/pseudoSkills.ts, but the / picker renders them identically. Docs should say "built-in commands" (or just list them); never "pseudo-skills".

2. Experimental and off-by-default features live on a dedicated page, not scattered through the main docs. If a feature requires a settings toggle, feature flag, or env var to turn on, most users will never encounter it. It belongs under a separate "Experimental features" page (create one if none exists yet); do not sprinkle it through Workspaces / Agents / Interface / Code Review / etc. A reader of a main page should come away understanding only the default-on behavior.

   Example: in-place workspaces are off by default. They don't belong in the main Workspaces page. If a main page mentions them, that's a WRONG verdict in Phase 2 — the fix is to move the content to the Experimental page (or trim it), not to refine the wording in place.

3. No dev-build references. Customers install a packaged app. Don't mention uv run, just start, .dev0 version suffixes, cloning the Sculptor repo, running from source, or anything else that only applies to people developing Sculptor. Any existing dev-flow reference in the docs is a WRONG verdict.

Phase 1: Survey the help docs

Read every doc-page markdown file under docs/help/ in full, plus the index at docs/help/README.md. At the time of writing the pages are getting_started.md, workspaces.md, chat.md, terminal.md, agents.md, changes.md, pull_requests.md, slash_commands.md, command_palette.md, settings.md, and experimental/container_backend.md — but do not hard-code this list. Glob docs/help/**/*.md and read what is actually there.

While reading, build a list of every factual claim that needs verification. These typically fall into buckets:

• Named UI elements — button labels, panel names, tab names, dialog titles
• Paths on disk — ~/.sculptor/workspaces/..., clone vs in-place layout
• Flows — the step ordering of "create workspace", "review changes", "add a repo"
• Keyboard shortcuts — the cmd+… table
• Slash commands — the list of built-ins and what each does
• Image references — ![alt](images/<name>.png) lines (paths are relative to docs/help/)

Also list docs/help/images/. The repo stores only the final padded versions of each image (1200×800 sage-green-padded PNGs) — there is no separate raw/processed split. Note which images are referenced from markdown and which are orphaned.

Phase 2: Audit text against the Sculptor source

Dispatch parallel Explore subagents, each owning one or two doc files, to verify the claims you listed in Phase 1. Each subagent should:

• Receive the doc content (or file path) and a list of specific claims to verify
• Return a claim-by-claim verdict: VERIFIED / WRONG / PARTIAL / MISLEADING, with the file:line in the Sculptor source that proves it

Parallelism matters: one subagent per 1–2 doc files keeps the main context small and the turnaround fast. Do not do the verification yourself in the main thread.

Where truth lives (starting points, not exhaustive)

Sculptor source conventionally lives under sculptor/. Start from these anchors; let the code tell you the rest.

• Frontend UI: sculptor/frontend/src/
  • Chat: pages/workspace/components/ChatInput.tsx, pages/workspace/components/chat-alpha/TurnFooter.tsx
  • Workspace chrome: pages/workspace/WorkspaceLayoutShell.tsx, pages/workspace/WorkspaceHeader.tsx, components/nav/WorkspaceSidebar.tsx
  • Panels: components/sections/registry/panelRegistry.ts (panel names, icons, default sections), the panel components under pages/workspace/panels/ (ActionsPanel.tsx, ChangesPanel.tsx, TerminalPanelView.tsx, useTerminal.ts, …), components/actions/ActionDialog.tsx
  • Slash commands (source of truth): common/builtinSkills.ts, common/pseudoSkills.ts + the matcher in ChatInput.tsx
  • Keybindings: common/keybindings/definitions.ts
  • Settings: pages/settings/SettingsPage.tsx and subsections
  • Panel tabs / section chrome test IDs: components/sections/SectionHeader.tsx, components/sections/AddPanelDropdown.tsx
• Backend / paths: sculptor/sculptor/utils/build.py (workspace layout), sculptor/sculptor/services/workspace_service/environment_manager/environments/clone_strategy.py, sculptor/sculptor/services/workspace_service/environment_manager/environments/local_terminal_manager.py
• Electron main: main.ts (container-backend URL regex, window config)
• Test IDs: sculptor/sculptor/constants.py — the ElementIDs StrEnum

Produce an audit table

For each doc file, produce a compact table: Claim | Status | Source — this is the input to Phase 3. Keep it in conversation state (no need to write to disk). Do not start editing until the table for every file is complete.

What each verdict means — no "close enough"

For text:

• VERIFIED — no text change.
• WRONG / MISLEADING — rewrite to match source.
• PARTIAL — rewrite. PARTIAL is not "close enough"; /sculptor:help ingests these docs verbatim, so partial is wrong.

For images associated with the claim (by being inside the same doc section): any verdict other than VERIFIED marks the image for reshoot in Phase 4. "The image still looks plausible" does not override this — if the claim needed a rewrite, the illustrating image needs a reshoot.

Add/update/remove decisions

• Remove when the feature no longer exists in the code (e.g., a hover tooltip replaced by a slash command). Delete the prose and rm docs/help/images/<name>.png.
• Update when the concept still exists but the name/wording/path is stale. Prefer the exact string from the source.
• Add when a shipped concept is absent from the docs and a user would plausibly ask /sculptor:help about it.

End-of-phase gate (Phase 2)

Before advancing to Phase 3, confirm:

• Every doc file under docs/help/**/*.md (plus the index at docs/help/README.md) has an audit table.
• Every PARTIAL/WRONG/MISLEADING row names the source file:line that proves the verdict.
• Every non-VERIFIED row has an entry on the Phase 4 reshoot candidate list (unless the doc section has no image).

Phase 3: Rewrite the markdown

Edit each doc in place (prefer Edit for surgical changes; use Write for rewrites). Style rules observed in the existing docs:

• Second person, short sentences, no emojis
• Button/command names in **bold**, file paths and code in backticks
• H1 per page, --- separators between sections
• Image reference sits immediately above the section it illustrates, using ![alt](images/<name>.png) (paths are relative to docs/help/; the repo stores only the final padded image at docs/help/images/<name>.png)
• Written for two audiences simultaneously: a human customer, and the /sculptor:help skill that ingests the markdown and answers questions from it — so keep claims literal and verifiable

When the top-level structure changes (a page added or removed), also update docs/help/README.md (the index / table of contents, with a one-line description per page).

Phase 4: Recapture screenshots

Phase 4 always runs. It answers "which images need to be reshot?" — not "should I run this phase?". If the answer is zero, Phase 4 still runs through its preflight (launch harness, seed curated demo, audit each image against its spec) and produces an empty reshoot list.

The reshoot list is deterministic. An image goes on it if ANY of these are true:

• Its claim had a PARTIAL / WRONG / MISLEADING verdict in Phase 2.
• The doc section that references it had text rewritten in Phase 3.
• Its Phase 4.4 spec audit (a subagent-read of the current processed image against the spec below) returns anything other than a clean YES.

"The image still looks plausible" is not a keep reason. "The image would be extra work to reshoot" is not a keep reason.

4.1 Known gotchas (read first — these have bitten previous runs)

1. Headless xterm renders blank. xterm.js uses @xterm/addon-webgl which produces a transparent canvas under headless Chromium. The manual-test harness must launch Chromium with --disable-webgl --disable-webgl2 so xterm falls back to the canvas renderer. If the terminal screenshot is empty or garbled, check sculptor/sculptor/testing/manual_test_harness.py for those flags. Headed mode does NOT fix this on macOS.
2. Default viewport is too small for docs. The harness defaults to 1400×900. For docs screenshots, launch the server with --viewport-width 1920 --viewport-height 1200 — fixed-px UI chrome looks proportional rather than chunky.
3. Don't background the server with run_in_background. The tool timeout kills it. Use nohup … & with a pidfile, per the /auto-qa-changes skill.
4. Onboarding modal blocks the home page on a fresh instance. Dismiss it via its ONBOARDING_* testids before trying to reach workspaces.
5. The default demo repo is unusable. The harness default manual_test_repo / testing branch produces a workspace banner reading manual_test_repo › testing and file names like performance-log.txt and stuff.txt. That makes Sculptor look like internal tooling in every docs screenshot. Section 4.3 is mandatory, not a fallback.
6. Never inspect PNGs from the main thread. Every "does this screenshot show what I want?" check goes through a subagent: "Describe /path/to/0012_get.png, focusing on whether the Actions panel is open on the right edge and whether the Add Action dialog is visible."
7. The slash-command picker shows the local user's installed skills and commands. Sculptor scans ~/.claude/skills/ and ~/.claude/commands/ on every picker open (see discover_skills in sculptor/sculptor/web/skills.py) — so whatever the person running the harness has installed leaks into the docs screenshot. If any image in the reshoot list shows the / picker open, rename both dirs out of the way and relaunch the harness before capturing:

   mv ~/.claude/skills ~/.claude/skills.docs-hidden 2>/dev/null || true
   mv ~/.claude/commands ~/.claude/commands.docs-hidden 2>/dev/null || true
   # … relaunch harness, capture slash picker, shut harness down …
   mv ~/.claude/skills.docs-hidden ~/.claude/skills 2>/dev/null || true
   mv ~/.claude/commands.docs-hidden ~/.claude/commands 2>/dev/null || true

   The clean picker should show exactly: six built-ins (/batch, /clear, /context, /copy, /loop, /simplify) plus the four stock sculptor:* plugin skills (fix-bug, help, sculpt-cli, setup-repo). discover_skills also scans the repo's .claude/skills and .claude/commands, but because 4.3 mandates --project-path /tmp/sculptor-demo/widget-store (no .claude/ dir), the repo scan is a no-op — if the demo path ever changes, re-check this. Plugin skills live under the Sculptor install and stay visible. Verify before cropping: dispatch a subagent to read the raw source and confirm no row shows a "Custom" badge and no row has a name outside that set. If any Custom row is visible, the rename didn't take effect — reshoot, don't crop around it. Always restore both dirs before shutting down, even on error paths.

4.2 Launch the harness

Use the /auto-qa-changes skill for the actual launch — this skill does not re-document the server lifecycle. At minimum you need:

export SCREENSHOTS_DIR="$PWD/attachments/screenshots"   # or any writable dir
mkdir -p "$SCREENSHOTS_DIR"
SCULPTOR_MANUAL_TEST_HIDE_FAKE_MODELS=1 \
nohup uv run --project sculptor python -m sculptor.testing.manual_test_server \
  --screenshots-dir "$SCREENSHOTS_DIR" \
  --viewport-width 1920 --viewport-height 1200 \
  > /tmp/manual-test-server.log 2>&1 &
echo $! > /tmp/manual-test-server.pid

The SCULPTOR_MANUAL_TEST_HIDE_FAKE_MODELS=1 env var hides the "Fake Claude" and "Fake Claude 2" test-only models from the model picker. The harness normally turns on integration-testing mode (which shows them) so live tests can exercise them; for docs screenshots we want the production model list. This env var is read by manual_test_harness.py and flips TESTING__INTEGRATION_ENABLED=false only for this run — it does not affect regular integration tests.

Poll the log for the MANUAL_TEST_CONTROL_PORT= line to find the port. Hit /status until the server is ready. Dismiss onboarding as the first interaction.

4.3 Seed a curated demo — required, every run

The harness default (manual_test_repo / testing branch) is never acceptable in docs screenshots. Always seed a curated repo before launching the harness. This is not a fallback step — it runs unconditionally.

Create /tmp/sculptor-demo/widget-store/ as a recognizable TypeScript e-commerce sample:

• Real-looking package.json (name widget-store, a handful of deps), README.md, src/ with a few .ts files (e.g. products.ts, cart.ts, checkout.ts), tests/ with one test.
• git init, initial commit on main. The banner will show widget-store › <branch> — check it before you start capturing.

Launch the harness with --project-path /tmp/sculptor-demo/widget-store. Create the workspace with a meaningful name (e.g. add-search-bar, wire-up-checkout) — not default, not test, not <feature>-module.

Drive the demo so that the following UI states all exist simultaneously — any of them may be needed by images in Phase 4.4 (which derives what to shoot from the current docs, not a hardcoded list here):

• Visible in-progress todos in the Agent tasks panel (mid-run captures need the agent still thinking).
• A diff with at least 2 files changed.
• Terminal pane populated with real output — usually a git log or a test run.
• A second agent in the same workspace (spawn it before the first agent finishes so both tabs are visible).

Verify each before proceeding: banner shows widget-store, workspace name is meaningful, agent has in-progress todos, diff has ≥2 files, terminal has output, two agent tabs present. If any are missing, fix the setup — do not proceed to 4.5.

4.4 Audit each image and build the reshoot list

There is no hardcoded canonical image list in this skill — features come and go, and any list here would rot. The docs repo is the source of truth for which images currently exist; the markdown section that references each image is its spec.

For every image in docs/help/images/:

1. Find the markdown reference. Which doc file + section links images/<name>.png? If nothing references it, the image is orphaned — flag it for the Phase 6 report, don't silently delete.
2. Use the section's prose as the image's spec. The prose describes what the image must show; don't look elsewhere.
3. Decide the outcome using Phase 2's verdict on that section:
   • Feature removed (Phase 3 deleted the section): rm docs/help/images/<name>.png. No reshoot.
   • Section rewritten (PARTIAL / WRONG / MISLEADING in Phase 2): add to reshoot list. The new prose is the new spec.
   • Section VERIFIED (prose unchanged in Phase 3): dispatch a per-image subagent to check the image still matches the prose against the current release. If drift without text change, add to reshoot list. Otherwise, no reshoot.

Spec-audit prompt for VERIFIED sections (run per image):

Read the section in docs/help/<doc-file> that references images/<name>.png, then look at the image at docs/help/images/<name>.png. Against the current app at release <version>, does the image still accurately depict what the prose describes? Answer YES or NO plus one sentence. If NO, name what's different.

Then check for coverage gaps. Walk Phase 2's audit table for user-facing features in the release branch that are NOT covered by any existing doc section. For each such feature that rises to "most customers would ask /sculptor:help about this," surface a proposal in the Phase 6 report — do not create new doc pages or images inline. Each proposal includes:

• Proposed image name
• Target doc file and section placement
• One-sentence description of what the image would show
• Why it warrants its own image vs. being covered by an existing section

Adding a new page or image is a scope change; let the user decide and re-run the skill (or hand-edit) to add them. Document the gap in the report, not in the diff.

Special case for the slash-commands image (if one exists in the docs): gotcha #7 applies — the ~/.claude/skills and ~/.claude/commands dirs must be renamed out of the way before the capture so the user's personal skills don't leak into the picker. The picker should show only the built-ins from common/builtinSkills.ts + common/pseudoSkills.ts and the stock sculptor:* plugin skills (audit-table can confirm the exact set for the release).

Final reshoot list for this run:

• Every image whose section was rewritten in Phase 3.
• Every VERIFIED image whose spec-audit subagent returned NO.
• Nothing else — proposed new images live in the report, not the diff.