Repository navigation
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
Part 2 of the docs overhaul (parent: #1937). Start after sub-issue #1938 merges. This sub-issue uses its link checker and docs/getting-started.md.
Problem
cmd/agentop/README.md has 2,180 lines, and it is the only description of the agentop screen. A new laptop user cannot use it:
- It opens with the Kubernetes view. Line 3 says agentop inspects "AuthBridge's in-memory session store", "typically reached via
kubectl port-forward". "Run" saysobserve"discovers AuthBridge agents in your currentkubectlcontext". It then describes the Namespaces pane first. A laptop user never sees that pane, and a local Cortex wins by default (see "Choosing between a cluster and a local Cortex"). - The screen is in the middle of the file.
- "Install" has no curl one-liner.
- "Panes" starts at about line 843 (39% into the file).
- The Sessions mock-up is at about line 989.
- "Keybindings" is at about line 1558: about 60 rows with no short list.
- Before all of these come Bob shell setup, script plugins and server routing.
- Commands have no doc.
costandpipeline gethave no section anywhere.tools,pricing,export,setup,uninstall,doctorandserviceare documented only in other files, and this README does not link to them.
- Some facts are wrong.
- The Catalog pane entry says it opens with
P. The key help saysC("WasPuntil…"). - The pane list says "the other four" and leaves out the Agents pane (
A). Agents is described only inside "Keybindings". - "configures the editor above": the editor section is below.
- The Sessions text tells the reader to press
Esc"back to the Pods pane" to reset CTX. That is true only in a cluster.
- The Catalog pane entry says it opens with
Tasks
1. Add docs/using-agentop.md (about 250 lines)
This is the user guide. Keep this order:
- Open it.
agentop observe. On a laptop it connects to the local Cortex. Link the cluster choice (--kubernetes) in the reference. - The screen.
- Move the Sessions screen mock-up here from
cmd/agentop/README.md. - One line for each column: what it shows and its unit. Include SERVER, CTX and the
(*)import marker. If SAVED~ is shown by default, describe it in one neutral line (what it counts), with no pitch. - Shorten the band text (LAST 1H, TODAY, 7 DAYS, MONTH) to one line for each period.
- Leave the long column details, such as the CTX derivation, in the reference.
- Move the Sessions screen mock-up here from
- Panes. One line each: what it shows and the key that opens it.
- Sessions, Events, Detail, Timeline, Usage, Agents, Pipeline, Plugin detail, Catalog, Key help
- Namespaces, marked "cluster only"
- Check each key in the code under
cmd/agentop/tui/.
- Keys.
- A table of the 10–15 keys that a daily user needs, taken from "Keybindings":
↑↓,Enter,Esc,/,?,$,u,T,A,S,p,q, and any key the code marks as global. - Then: press
?for the full list. - Link the full table in the reference.
- A table of the 10–15 keys that a daily user needs, taken from "Keybindings":
- Everyday commands. A table, one row per top-level subcommand in
cmd/agentop/main.go: the command, one line on what it does, one example, and a link.- Rows: observe, setup, doctor, update, uninstall, service, configure, exec, server, script, pipeline, pricing, cost, export, import.
- Leave out
tools(rule 11). The reference keeps it. - Leave out
experimentaland the deprecated aliasclaude-code. - Links:
laptop-service.mdfor setup, doctor, service and uninstall.pricing.mdfor pricing.session-export.mdfor export. A section in the reference for the others.
2. Reorder cmd/agentop/README.md into a reference
- New intro (lines 1–8). "Reference for
agentop. For a first tour, readdocs/using-agentop.md." It works with the local Cortex on a laptop, and with an AuthBridge sidecar in a cluster. - "Install". Put the curl one-liner first, then the release download, then
go build. - "Run". Laptop first. Move the cluster text (port-forward, Namespaces first, kubectl discovery) under "Choosing between a cluster and a local Cortex (
--kubernetes)". - New order of the H2 sections:
- Install
- Updating
- Run, with its subsections
- Panes
- Keybindings
- Settings
- Where a session opens
- Commands. Keep each existing command section, and make each one an H3 under this heading:
- configure status
- exec
- server
- import
- script
- cost (new)
- pipeline get (new)
- Editing the pipeline
- Plugin dependencies
- Per-agent configure. Leave the existing Bob, OpenCode and Pi sections here without changes. Sub-issue docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941 moves them.
- Trust model
- Internals: How a timeline is fetched, Architecture, and the CTX derivation subsection (move it out of Sessions)
- Keep heading texts the same wherever you can, so anchors stay valid. Many docs link
#importing-agent-history-agentop-import,#choosing-an-inference-server-agentop-server,#local-model-servers,#panesand#naming-sessions-from-claude-code---skip-claude-metadata. The link checker finds all of them.
3. Write the two missing command sections
agentop cost. Read the code (grep -rln 'func.*[Cc]ost' cmd/agentop/*.go, andagentop cost --helpfrom a build). Give every flag with one line each, plus three examples: this month by agent, today by model, and a JSON output if the command has one. Linkdocs/pricing.mdfor how cost is computed.agentop pipeline get. What it prints and when to use it: to see the pipeline that runs, because the config file alone does not show the defaults. Check against the code.
4. Fix the wrong facts
- Catalog key: write what the code binds.
- The pane list: include Agents, and fix the count, or remove the count.
- "the editor above" → below (or remove it, if the order changes).
- The CTX reset with
Escto Pods: mark it cluster-only, or give the laptop way.
5. Link from the new-user path
README.md"Learn more" anddocs/README.md"New here": linkdocs/using-agentop.md. Sub-issue docs: Add the new-user path: getting started, troubleshooting and a link checker #1938 usedcmd/agentop/README.md#panesuntil this page exists.docs/getting-started.md"Read the screen": add "More: Using agentop".
Acceptance
docs/using-agentop.mdexists. A reader can read the Sessions screen and use the top keys without openingcmd/agentop/README.md.- Every top-level subcommand in
cmd/agentop/main.go, exceptexperimental,claude-codeandtools, has a row indocs/using-agentop.mdand a doc that it links to. - The Sessions mock-up exists once, in
docs/using-agentop.md. - The link checker passes.
Out of scope
- Moving the Bob, OpenCode and Pi configure sections (sub-issue docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941).
- Any change to agentop's behavior. The only code changes allowed are in the usage text, and only where it is wrong.
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
documentationImprovements or additions to documentationImprovements or additions to documentation
Type
Projects
- StatusShow more project fieldsDone
Activity
docs: Add the plan for the agentop user guide (#1939)
docs: Move the agentop README sections into reference order
docs: Add the agentop user guide