Skip to content

docs: Overhaul the docs so new users do not get lost #1937

Closed
7 of 7 issues completed
Closed

Description

@huang195

Problem

A new user gets lost after the README. We audited all 67 docs outside docs/superpowers/ (about 25,000 lines) and their link graph, at main 02e489e.

  1. Two steps of the new-user journey are missing. No doc says what you should see after agentop observe. No doc in docs/ or the README shows how to read the screen. The screen mock-up is at line 989 of a 2,180-line file (cmd/agentop/README.md), and the keys start at line 1558.
  2. The CLI and the README disagree.
    • Setup ends with agentop exec -- <cmd>, not agentop configure claude-code enable.
    • install.sh --help says that the session store is memory-only.
    • The usage text leaves out pi.
  3. The docs a new user opens first are written for someone else.
    • The agentop README opens with the Kubernetes view.
    • bob.md starts with JSON byte-splicing.
    • codex.md never says "now run codex".
    • laptop-service.md starts with supervisor internals.
  4. There is no troubleshooting page. All the fixes are ### sections under "Three ways to turn it off".
  5. Plugin docs do not say where a plugin applies. The plugin tutorial produces a plugin that does not register, because it has no build-tag step.
  6. Kubernetes users have no journey. The opt-in label is never named, and there is no troubleshooting section.
  7. There are two install guides. The external one (rossoctl.dev laptop quickstart) is stale in five places:
    • configure bobshell
    • NONESSENTIAL_TRAFFIC
    • no Pi
    • Codex and OpenCode as "exec only"
    • the old Bob keychain text

Goal

A new user follows one path and never opens a reference doc to finish a step:

README.md            install, 3 commands → "Next: Getting started"
  docs/getting-started.md   install → connect → check → read the screen → next steps → undo
  docs/using-agentop.md     the screen, panes, top keys, every command in one table
  docs/troubleshooting.md   doctor first, then one heading per symptom
  docs/agents/<agent>.md    Use it → What you see → Known issues → How it works (for developers)
docs/README.md        three paths: New here · Daily use · Reference

Reference docs stay complete, but they move below the new-user path. docs/ stays flat, because released binaries print five doc paths. A link checker keeps every link and anchor valid during the moves.

Sub-issues (one PR each, at most 2,000 lines)

Run each one with /sdd-fast <number>. Order:

  1. docs: Add the new-user path: getting started, troubleshooting and a link checker #1938 New-user path: the link checker, getting-started, troubleshooting, configuration, the docs index, the CLI text fixes and the stale facts. This one goes first.
  2. docs: Add an agentop user guide and reorder the agentop reference #1939 agentop user guide: using-agentop.md, the reference reorder, and docs for cost and pipeline get. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938.
  3. docs: Put "Use it" first in the Claude Code, Codex and any-agent guides #1940 Agent guides, part 1: claude-code, codex, any-agent. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938.
  4. docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941 Agent guides, part 2: opencode, bob, pi, and moving their sections out of the agentop README. After docs: Add an agentop user guide and reorder the agentop reference #1939.
  5. docs: Reorder laptop-service.md for daily use #1942 laptop-service.md reorder. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938.
  6. docs: Show where each plugin applies and fix the plugin tutorial #1943 Plugin docs: the "Where" column, the laptop first screen, one owner per plugin, and the tutorial build-tag step. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938.
  7. docs: Add the Kubernetes journey and clean up the contributor docs #1944 Kubernetes journey, architecture cleanup, CONTRIBUTING, orphans and the export-doc merge. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938.

After #1938 merges, #1939, #1940, #1942, #1943 and #1944 can run at the same time. #1941 waits for #1939.

Rules for every PR in this overhaul

These rules are the same in every sub-issue of the docs overhaul, so each sub-issue is complete without the others.

  1. Language. Write in ASD-STE100 Simplified Technical English, in the prose mode:
    • one idea per sentence, at most 25 words
    • active voice
    • no semicolons
    • no phrasal verbs
    • no marketing adjectives
  2. Naming. Use Cortex for the product and its binaries. Use AuthBridge only for a frozen artifact name: an image, the authbridge-proxy container, a ConfigMap, a header, an env var, or the mode field. The full table is in the root CLAUDE.md, section "Naming".
  3. Move, do not copy. When a section moves to a new file:
    • Delete it from the old file.
    • Update every inbound link and anchor. Use grep -rn '<file>#<anchor>' --include='*.md' --include='*.go' --include='*.sh' . to find them.
    • In the old place, leave at most one line that points to the new place.
  4. Keep these paths valid. Released binaries and install.sh print them to users:
    • docs/pricing.md (cmd/agentop/cmd_config_migrate_pricing.go, cmd/agentop/cmd_service.go, cmd/cortex/local.go)
    • docs/praxis-policy.md and its anchor #move-from-the-cpex-plugin (cmd/agentop/cmd_update.go, cmd/agentop/setup_step_binaries.go, cmd/cortex/praxis.go, scripts/install.sh)
    • docs/session-export.md (cmd/agentop/cmd_export.go)
    • docs/laptop-local-model.md, as a full GitHub URL (cmd/agentop/cmd_server.go)
    • docs/laptop-service.md (code comments in cmd/agentop/cmd_service.go and cmd/agentop/cmd_claudecode.go. They name sections by title. If a section title changes or the section moves, update the comment.)
  5. New-user pages are complete. A reader of README.md, docs/getting-started.md, docs/using-agentop.md or docs/troubleshooting.md must finish each step without opening a reference doc. Links to reference docs are for "more detail" only.
  6. Facts come from the code. When a doc states a command, flag, key, port, count or file path, check it in the code on main before you write it. When the code and a doc disagree, change the doc to match the code.
  7. Do not state counts that drift. Do not write "all sixteen plugins" or "seven keys". Link to the list instead, or show the list.
  8. Size. One PR, at most 2,000 diff lines (git diff --stat main). Moved text counts twice.
  9. Gate. Run these before you push:
    • python3 scripts/dev/check-doc-links.py. The first sub-issue adds this script. Until it merges, use the reference implementation in that sub-issue.
    • pre-commit run --files <changed files>
    • When Go files change: go vet ./... and gofmt -l . in each module you touched. For cmd/agentop, also run scripts/dev/go-test-shards.sh -short cmd/agentop.
    • Add any new word that the spellcheck job rejects to the word list that .github/spellcheck/.spellcheck.yml names.
  10. PR title. Use docs: <Subject starting with uppercase>. End the PR body with Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com>. Sign off every commit (git commit -s).
  11. No cost-reduction pitch for new users. A new user is not interested in it. Tool pruning comes back later, together with the context-guru integration. In README.md, docs/getting-started.md, docs/using-agentop.md, docs/troubleshooting.md, the "New here" part of docs/README.md, install.sh help and setup output, the first paragraph and "Use it" of each agent guide, and the first screen of docs/plugin-catalog.md:
    • do not mention cost reduction, token savings or "cut the waste"
    • do not mention agentop tools scan, --write, or turning on tool-prune
    • showing what an agent spends (tokens, cost) is fine: that is observation, not reduction
    • reference docs (laptop-token-savings.md, tool-prune-plugin.md, the agentop reference, "How it works" sections) keep their content without changes

For a human after review

  • The external laptop quickstart. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938 merges, make the rossoctl.dev laptop page (docs/get-started/laptop.md in the site source) a short page that points to this repo's README.md and docs/getting-started.md. Or bring it up to date. This change is in another repository. Draft it, and get the site owners' OK before you post.
  • The README comment. The README's HTML comment says the install command is duplicated on the website. Keep that comment until the website change lands.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationepicLarge multi-workstream initiatives

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions