Skip to content

docs: Put "Use it" first in the Claude Code, Codex and any-agent guides #1940

Open

Description

@huang195

Part 3 of the docs overhaul (parent: #1937). Start after sub-issue #1938 merges. This sub-issue uses its link checker and docs/troubleshooting.md. It can run at the same time as sub-issues #1939, #1942, #1943 and #1944.

Problem

The agent guides are the second page a new user opens. Most of them start with internals:

  • docs/agents/claude-code.md (297 lines). The commands come first, which is good. Then lines 20–56 explain the state file. The restart rule and the trust-failure symptom are in the middle. Subagent headers, router behavior and "Verified depth" are mixed in. It says "Seven keys" in two places, but its table and two other places say six (sub-issue docs: Add the new-user path: getting started, troubleshooting and a link checker #1938 fixes the number).
  • docs/agents/codex.md (555 lines). It starts with dotenv details, then a long passage on why the CA goes in SSL_CERT_FILE. It never says "now run codex". The daemon restart is the main thing that bites a user, and it is at about line 91. The only way given to check that it works is ~/.cortex/proxy.log.
  • docs/agents/any-agent.md (111 lines). The usage is at lines 19–23. The rest is design reasoning and changelog wording ("as of the same change").

The agent-guide template

Every docs/agents/<agent>.md uses these H2 sections, in this order:

# <Agent name>

<One paragraph, at most 4 sentences: what Cortex does for this agent, and how well
it is supported.>

## Use it
1. Enable: `agentop configure <agent> enable` (or `agentop exec -- <cmd>`).
2. Start the agent: the exact command, and whether a running agent or a background
   daemon must restart. Say how to restart it.
3. Check: run `agentop observe`, send one prompt, and see a row for <agent>.
   `agentop configure <agent> status` shows what is set.
4. Undo: `agentop configure <agent> disable`, then the same restart rule.

## What you see
<What agentop shows for this agent: grouping, subagents, cost, what is missing.>

## Switching inference servers   (only if the agent supports it)
## Import history                 (only if `agentop import` supports it)

## Known issues
<Symptom → fix. Link docs/troubleshooting.md for problems shared by all agents.>

## How it works (for developers)
<Everything else, moved down without changes: what `enable` writes, the state
record, undoing by hand, CA trust details, URL matching, "Verified depth".>

Rules for the template:

  • The "Use it" section is at most 25 lines. The reader can follow it alone.
  • Do not delete detail. Move it to "How it works (for developers)" as H3 sections, and keep the heading texts so anchors stay valid.
  • Remove changelog wording, such as "as of the same change", "previously" and "earlier versions". Say what is true now. Remove a fact only when it is no longer true.

Tasks

  1. Apply the template to docs/agents/claude-code.md, docs/agents/codex.md and docs/agents/any-agent.md.
  2. claude-code.md:
    • "Use it" must hold the restart rule: claude --resume picks the conversation back up.
    • "Known issues" must hold the CA trust-failure symptom (today in "CA trust").
    • Move "What enable writes", "The record", "Undoing it by hand", subagent headers, the router behavior and "Verified depth" to "How it works".
    • The link to cmd/agentop/README.md#panes for pruning: link docs/using-agentop.md if it exists. If it does not exist yet, keep the link.
  3. codex.md:
    • "Use it" must say how to start Codex, and how to restart its daemon or updater. Today this is in the section near line 91. Check the facts in cmd/agentop/cmd_codex*.go, or wherever configure codex lives.
    • "Check" uses agentop observe, not proxy.log.
    • Move the SSL_CERT_FILE reasoning, the state record, the updater pid identity and "Verified depth" to "How it works".
  4. any-agent.md:
    • "Use it" = agentop exec -- <command>, plus what to do when the agent ignores HTTPS_PROXY. Take that text from the existing guide.
    • Move the design reasoning to "How it works", and remove the changelog wording.
  5. Duplicates.
    • The CA "extends or replaces" explanation exists in claude-code.md, any-agent.md and laptop-service.md. Keep it once, in any-agent.md → "How it works". Link it from claude-code.md. Do not edit laptop-service.md: sub-issue docs: Reorder laptop-service.md for daily use #1942 replaces its copy with a link.
    • "Undoing it by hand" for Claude Code also exists in laptop-service.md under "Remove it" (the H4 "If agentop is already gone"). Keep the Claude Code steps in claude-code.md. Do not edit laptop-service.md: sub-issue docs: Reorder laptop-service.md for daily use #1942 replaces its copy with a link.

Acceptance

  • Each of the three files starts with the one paragraph and "Use it". "Use it" is at most 25 lines.
  • No fact is lost. Check this with a word diff of the old and new text. Every removed line moved, or it is no longer true. The PR body lists each line that is no longer true.
  • 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).

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