Skip to content

docs: Add an agentop user guide and reorder the agentop reference #1939

Closed

Description

@huang195

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" says observe "discovers AuthBridge agents in your current kubectl context". 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.
    • cost and pipeline get have no section anywhere.
    • tools, pricing, export, setup, uninstall, doctor and service are 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 says C ("Was P until…").
    • 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.

Tasks

1. Add docs/using-agentop.md (about 250 lines)

This is the user guide. Keep this order:

  1. Open it. agentop observe. On a laptop it connects to the local Cortex. Link the cluster choice (--kubernetes) in the reference.
  2. 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.
  3. 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/.
  4. 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.
  5. 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 experimental and the deprecated alias claude-code.
    • Links: laptop-service.md for setup, doctor, service and uninstall. pricing.md for pricing. session-export.md for 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, read docs/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:
    1. Install
    2. Updating
    3. Run, with its subsections
    4. Panes
    5. Keybindings
    6. Settings
    7. Where a session opens
    8. 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
    9. 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.
    10. Trust model
    11. 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, #panes and #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, and agentop cost --help from 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. Link docs/pricing.md for 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 Esc to Pods: mark it cluster-only, or give the laptop way.

5. Link from the new-user path

Acceptance

  • docs/using-agentop.md exists. A reader can read the Sessions screen and use the top keys without opening cmd/agentop/README.md.
  • Every top-level subcommand in cmd/agentop/main.go, except experimental, claude-code and tools, has a row in docs/using-agentop.md and a doc that it links to.
  • The Sessions mock-up exists once, in docs/using-agentop.md.
  • The link checker passes.

Out of scope

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.

  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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions