Repository navigation
Description
Part 1 of the docs overhaul (parent: #1937). Do this one first. The other sub-issues use the link checker and the pages that this one adds.
Problem
A new laptop user has a good README, but nothing tells them what to do after agentop observe. Four things are missing:
- No "check it works" step. No doc in the repo says what the first row in
agentop observelooks like. - No page shows how to read the screen. The screen mock-up is at line 989 of
cmd/agentop/README.md, and the key table starts at line 1558. - No troubleshooting page. Every fix is an
###section under "Three ways to turn it off" indocs/laptop-service.md. In the outline, those sections look like ways to turn Cortex off. - The CLI and the README disagree.
- The last message of setup tells a user without
--claude-codeto runagentop exec -- <cmd>, notagentop configure claude-code enable(cmd/agentop/cmd_setup.go, theui.Next("Open a new terminal, then:", ...)call). - For a
--claude-codeuser, it prints bareagentop, which is deprecated (cmd/agentop/main.go). The README saysagentop observe. scripts/install.sh --helpsays "The session store is memory-only". This is false on a laptop: history is kept in~/.cortex/sessions.
- The last message of setup tells a user without
docs/README.md is also hard to scan:
- Its "Getting started" table mixes first-day tasks with praxis policy enforcement and offline export analysis.
- It holds the full configuration-reference table.
- It has a typo: "group sessions into sessions".
Tasks
1. Add the link checker: scripts/dev/check-doc-links.py
It uses the Python standard library only, and it exits 1 when it finds a problem. It must check:
- every relative Markdown link
](path)and](path#anchor)in every*.mdfile, except underdocs/superpowers/and anytestdata/directory - that the path is a file or a directory
- that each
#anchoron a.mdtarget matches a heading slug, using GitHub's rules:- lowercase
- remove HTML tags
- remove every character that is not a word character,
-or a space - change each space to
- - give the second identical slug
-1, the third-2, and so on - also accept
<a name=...>and<a id=...> - ignore headings inside fenced code blocks
- that each path and anchor in the "Keep these paths valid" list below still exists, as a hard-coded list. A comment names the Go or shell file that prints each one.
Add a local pre-commit hook in .pre-commit-config.yaml that runs it on \.md$ changes (pass_filenames: false).
Add --selftest. It builds a temporary tree with one good link, one missing file, one missing anchor and one duplicate heading, and it asserts the result for each.
Reference implementation. It passes on main at 02e489e with no findings. Extend it with the file check, the hard-coded list and --selftest:
import os, re, sys
root = sys.argv[1]
def slugs(path):
s, seen, fence = set(), {}, False
for line in open(path):
if line.lstrip().startswith('```'): fence = not fence; continue
if fence: continue
m = re.match(r'#{1,6}\s+(.*)', line)
if not m: continue
t = re.sub(r'<[^>]+>', '', m.group(1).strip()).lower()
t = re.sub(r'[^\w\- ]', '', t).replace(' ', '-')
n = seen.get(t, 0); seen[t] = n + 1
s.add(t if n == 0 else f'{t}-{n}')
for a in re.findall(r'<a (?:name|id)="([^"]+)"', open(path).read()): s.add(a)
return s
cache = {}
for d, _, fs in os.walk(root):
if 'superpowers' in d or 'testdata' in d: continue
for f in fs:
if not f.endswith('.md') or f == 'CLAUDE.md': continue
p = os.path.join(d, f)
for m in re.findall(r'\]\(([^)\s]+)\)', open(p).read()):
if m.startswith(('http', 'mailto')) or '#' not in m: continue
path, a = m.split('#', 1)
t = os.path.normpath(os.path.join(d, path)) if path else p
if not t.endswith('.md') or not os.path.exists(t): continue
if t not in cache: cache[t] = slugs(t)
if a not in cache[t]: print(os.path.relpath(p, root), '->', m)Default root to the repository root (the parent of scripts/), so python3 scripts/dev/check-doc-links.py works with no argument. Skip .claude/ and node_modules/.
2. Add docs/getting-started.md (about 150 lines)
This is the page the README sends a new user to after the install. Keep this order and these headings:
- Install. The one-liner from the README. Say what setup asks, and that it asks once.
- Connect your agent. A table with one row per agent: the
agentop configure <agent> enablecommand, the command to start the agent, and whether a running agent must restart. Get the facts from eachdocs/agents/<agent>.md, section "Enable and revert" or equal. Useagentop exec -- <command>for any other agent. - Check that it works.
- Run
agentop observeand send one prompt. - Say what a new row shows: the agent, the model, tokens and cost.
- Use the columns that
cmd/agentop/README.mdlists under "Panes" → Sessions. - When no row appears, run
agentop doctor, then readdocs/troubleshooting.md.
- Run
- Read the screen.
- The Sessions screen mock-up from
cmd/agentop/README.md(the fenced block of the band, table and footer, near the CTX text). - One line for each column.
- A table of the 10 keys a new user needs:
↑/↓,Enter,Esc,/,?,$,u,T,A,q. - Check each key in
cmd/agentop/README.md→ "Keybindings" and in the code undercmd/agentop/tui/. - End with: press
?for every key.
- The Sessions screen mock-up from
- Next steps. One line and one command each, with a link for more detail:
- add history from before Cortex (
agentop import --dry-run) - switch model server (
agentop server, linklaptop-local-model.md) - see cost (
agentop cost --window month --by agent)
- add history from before Cortex (
- Undo it.
agentop configure <agent> disable, then restart the agent.agentop uninstall, and--purgeto also delete~/.cortex. Linklaptop-service.md#remove-it.
3. Add docs/troubleshooting.md
Start with one section: "Run agentop doctor first". It checks the install and prints the fix for each problem.
Then move these sections from docs/laptop-service.md, as ## headings in this order. Keep each heading's text the same, so the existing anchors stay valid:
- Install:
- "
agentop: command not found" - "Restricted environments (sandboxes, no launchd session)"
- "
- My agent does not show in agentop:
- "Why traffic disappears from
agentop" - "Everything shows as
tunneland no plugin ever runs" - "Developer tooling is not intercepted at all"
- "Go tools on macOS are passed through unread"
- "Why traffic disappears from
- Errors:
- "
502 Cortex proxy is not serving" - "A request gets
421 Misdirected Request" - "Failing closed"
- "
Use ## group headings for the three groups. End with "Problems with one agent": one link per agent to docs/agents/<agent>.md#known-issues, or to the equal section where a guide has no "Known issues".
Update every link to the moved anchors. Today these files link to them: docs/agents/claude-code.md, docs/agents/opencode.md, and comments in cmd/agentop/cmd_claudecode.go. Use grep to find the complete list.
4. Add docs/configuration.md
Move the section "Configuration reference" from docs/README.md without changes, together with the two paragraphs below its table. Fix the links in it for the new location.
5. Rewrite docs/README.md
Use three paths, in this order:
- New here. Getting started, your agent's guide (one link per agent), Using agentop, Troubleshooting.
- Daily use.
- local models and servers
- script plugins
- remote machine
- importing history
- pricing and cost
- running the service (
laptop-service.md) - praxis policy
- exporting sessions
- Reference. Four groups:
- Kubernetes:
kubernetes.md,architecture.md,cmd/README.md, the demos - Plugins: the catalog, then the author docs in this order:
plugin-tutorial.md,plugin-reference.md,script-plugin.md. Then the per-plugin list, which must includescript. - Configuration (
configuration.md), the session API, the proxy contract - Contributor and integrator contracts:
idp-plugin-contract.md,lineage-wire-contract.md
- Kubernetes:
Keep "In this directory". Remove "group sessions into sessions". Each table row is one short line.
6. Update README.md
- After the Quick start commands, add one line: Next: Getting started. It shows what you should see, how to read the screen, and how to undo it.
- In "Learn more", put "Getting started", "Using agentop" and "Troubleshooting" first. Then "All docs".
- Remove the "full install guide" link to rossoctl.dev. That page is stale (see the parent issue). The README is the one full guide.
docs/using-agentop.mdis added by sub-issue docs: Add an agentop user guide and reorder the agentop reference #1939. Until it exists, linkcmd/agentop/README.md#paneswith the text "Using agentop".
6a. Remove the cost-reduction pitch from README.md
Rule 11 has the details.
- Change the tagline "Watch every model call, tool call and dollar your agent spends, live — then cut the waste." Keep the first part, and remove "then cut the waste".
- Remove the section "Trim 4–20% off Claude Code's prompts" and its
agentop tools scan --writecommand. - Remove "token savings" from the "Guides:" line.
- Keep "Read-only until you turn on pruning, server routing or an enforcing script". It is a fact about data, not a pitch.
docs/README.md: put the token-savings row under "Reference" → Plugins, not under "New here" or "Daily use".
7. Fix the CLI text
cmd/agentop/cmd_setup.go, the last message of setup:- Without
--claude-code: printagentop configure claude-code enablewith the commentconnect your agent (or opencode, codex, bob, pi). Then printagentop observewith the commentwatch your agent traffic live. - With
--claude-code: printagentop observe, not bareagentop. - Update the tests that assert this output. Find them with
grep -rn 'send an agent through Cortex\|watch your agent traffic live' cmd/agentop.
- Without
scripts/install.shusage():- Remove the block "After installing, to cut Claude Code's token cost:", the
agentop tools scan --writeline and "Then watch the $ saved on every prompt…". Keep one line:Then watch your agent live: agentop observe. - Check the setup output (
cmd/agentop/cmd_setup.goand the setup steps) for the same pitch, and remove it. - Change bare
agentoptoagentop observe. - Replace the two lines "The session store is memory-only…" and
cortex-session-dump --out ./cortex-dumpwith:History is kept in ~/.cortex/sessions. agentop import adds sessions from before Cortex. - Check that
install.shinstallscortex-session-dumptoday. If it does, keep the tool and only change the help text.
- Remove the block "After installing, to cut Claude Code's token cost:", the
cmd/agentop/main.gousage text: theconfigure <agent>line listsclaude-code, bob, codex, opencode. Addpi, becausecmd_configure.godispatches it.
8. Fix stale facts in the new-user path
docs/agents/claude-code.md:- "Seven keys" (two places) disagrees with the table and with "six keys" (two places). Count the keys that
cmd/agentop/cmd_claudecode.gowrites, and use the code's number everywhere. - Do the same check for "six keys" in
docs/laptop-service.md.
- "Seven keys" (two places) disagrees with the table and with "six keys" (two places). Count the keys that
docs/agents/bob.md: remove the two references toconfigure bobshell. That command was removed. The shell half is now part ofagentop configure bob.docs/laptop-service.md:- "Bob … our internal coding agent (not the
bobdemo user)": describe IBM Bob as the README does. - "run
agentopwith no arguments": change it toagentop observe.
- "Bob … our internal coding agent (not the
docs/laptop-token-savings.md: "runagentop" →agentop observe.docs/laptop-service.md→ "Remove it": it lists the agents thatagentop uninstallunroutes. Check the list against the uninstall code incmd/agentop, which includes Codex and Pi, and fix the list.
Acceptance
python3 scripts/dev/check-doc-links.pyand--selftestpass. The pre-commit hook runs it.docs/laptop-service.mdno longer has the moved sections. Each section appears once, indocs/troubleshooting.md.- A reader can follow
README.md→docs/getting-started.mdfrom install to undo and open no other file. agentop setupwithout--claude-codeends withconfigure … enableandagentop observe.- The
cmd/agentoptests pass with-short.
Out of scope
- Reordering the rest of
laptop-service.md(sub-issue docs: Reorder laptop-service.md for daily use #1942). - Splitting
cmd/agentop/README.md(sub-issue docs: Add an agentop user guide and reorder the agentop reference #1939). - The agent-guide template (sub-issues docs: Put "Use it" first in the Claude Code, Codex and any-agent guides #1940 and docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941).
For a human after review
None.
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
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
docs: Add a getting-started page
docs: Remove the token-saving pitch from the new-user path
Merge pull request #1947 from huang195/docs/new-user-path-1938-followup
docs: Reorder laptop-service.md for daily use
huang195 commentedon Nov 18, 2026
Done in #1945 and #1947. The acceptance items pass on main: the link checker and its --selftest pass, the pre-commit hook runs it, the moved sections are only in docs/troubleshooting.md, and setup ends with configure … enable and agentop observe.