Repository navigation
Closed
7 / 77 of 7 issues completedClosed
7 / 77 of 7 issues completed
Copy link
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationepicLarge multi-workstream initiativesLarge multi-workstream initiatives
Description
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.
- Two steps of the new-user journey are missing. No doc says what you should see after
agentop observe. No doc indocs/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. - The CLI and the README disagree.
- Setup ends with
agentop exec -- <cmd>, notagentop configure claude-code enable. install.sh --helpsays that the session store is memory-only.- The usage text leaves out
pi.
- Setup ends with
- The docs a new user opens first are written for someone else.
- The agentop README opens with the Kubernetes view.
bob.mdstarts with JSON byte-splicing.codex.mdnever says "now runcodex".laptop-service.mdstarts with supervisor internals.
- There is no troubleshooting page. All the fixes are
###sections under "Three ways to turn it off". - 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.
- Kubernetes users have no journey. The opt-in label is never named, and there is no troubleshooting section.
- There are two install guides. The external one (rossoctl.dev laptop quickstart) is stale in five places:
configure bobshellNONESSENTIAL_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:
- 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.
- docs: Add an agentop user guide and reorder the agentop reference #1939 agentop user guide:
using-agentop.md, the reference reorder, and docs forcostandpipeline get. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938. - 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.
- 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.
- docs: Reorder laptop-service.md for daily use #1942
laptop-service.mdreorder. After docs: Add the new-user path: getting started, troubleshooting and a link checker #1938. - 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.
- 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.
- 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
- Naming. Use Cortex for the product and its binaries. Use AuthBridge only for a frozen artifact name: an image, the
authbridge-proxycontainer, a ConfigMap, a header, an env var, or the mode field. The full table is in the rootCLAUDE.md, section "Naming". - 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.
- Keep these paths valid. Released binaries and
install.shprint 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.mdand 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 incmd/agentop/cmd_service.goandcmd/agentop/cmd_claudecode.go. They name sections by title. If a section title changes or the section moves, update the comment.)
- New-user pages are complete. A reader of
README.md,docs/getting-started.md,docs/using-agentop.mdordocs/troubleshooting.mdmust finish each step without opening a reference doc. Links to reference docs are for "more detail" only. - Facts come from the code. When a doc states a command, flag, key, port, count or file path, check it in the code on
mainbefore you write it. When the code and a doc disagree, change the doc to match the code. - Do not state counts that drift. Do not write "all sixteen plugins" or "seven keys". Link to the list instead, or show the list.
- Size. One PR, at most 2,000 diff lines (
git diff --stat main). Moved text counts twice. - 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 ./...andgofmt -l .in each module you touched. Forcmd/agentop, also runscripts/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.ymlnames.
- PR title. Use
docs: <Subject starting with uppercase>. End the PR body withAssisted-By: Claude (Anthropic AI) <noreply@anthropic.com>. Sign off every commit (git commit -s). - 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 ofdocs/README.md,install.shhelp and setup output, the first paragraph and "Use it" of each agent guide, and the first screen ofdocs/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.mdin the site source) a short page that points to this repo'sREADME.mdanddocs/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 documentationImprovements or additions to documentationepicLarge multi-workstream initiativesLarge multi-workstream initiatives
Type
Projects
- StatusShow more project fieldsDone
Activity