Repository navigation
Open
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
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 inSSL_CERT_FILE. It never says "now runcodex". 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
- Apply the template to
docs/agents/claude-code.md,docs/agents/codex.mdanddocs/agents/any-agent.md. claude-code.md:- "Use it" must hold the restart rule:
claude --resumepicks the conversation back up. - "Known issues" must hold the CA trust-failure symptom (today in "CA trust").
- Move "What
enablewrites", "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#panesfor pruning: linkdocs/using-agentop.mdif it exists. If it does not exist yet, keep the link.
- "Use it" must hold the restart rule:
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 whereverconfigure codexlives. - "Check" uses
agentop observe, notproxy.log. - Move the
SSL_CERT_FILEreasoning, the state record, the updater pid identity and "Verified depth" to "How it works".
- "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
any-agent.md:- "Use it" =
agentop exec -- <command>, plus what to do when the agent ignoresHTTPS_PROXY. Take that text from the existing guide. - Move the design reasoning to "How it works", and remove the changelog wording.
- "Use it" =
- Duplicates.
- The CA "extends or replaces" explanation exists in
claude-code.md,any-agent.mdandlaptop-service.md. Keep it once, inany-agent.md→ "How it works". Link it fromclaude-code.md. Do not editlaptop-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.mdunder "Remove it" (the H4 "Ifagentopis already gone"). Keep the Claude Code steps inclaude-code.md. Do not editlaptop-service.md: sub-issue docs: Reorder laptop-service.md for daily use #1942 replaces its copy with a link.
- The CA "extends or replaces" explanation exists in
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
- opencode, bob and pi (sub-issue docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941).
- Any change to the CLI.
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).
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Type
Projects
- StatusShow more project fieldsNew/ToDo
Activity