Skip to content

docs: Put "Use it" first in the OpenCode, Bob and Pi guides #1941

Open

Description

@huang195

Part 4 of the docs overhaul (parent: #1937). Start after sub-issue #1939 merges. This sub-issue moves sections out of cmd/agentop/README.md, and sub-issue #1939 reorders that file.

Problem

  • docs/agents/bob.md (297 lines) starts with the JSON key shape and byte-splicing. The commands come at about line 28. The step that bites users most is about line 83: restart the editor from the Dock. Bob's real configure docs live in cmd/agentop/README.md:
    • "Typing bob instead of agentop exec -- bob (the shell half of agentop configure bob)"
    • "Routing the IBM Bob editor through Cortex (agentop configure bob)"
    • together about 315 lines
    • bob.md sends the reader there for "the conventions"
  • docs/agents/opencode.md (394 lines) never says "start opencode". Lines 22–68 are internals. cmd/agentop/README.md → "Routing OpenCode through Cortex (agentop configure opencode)" covers the same ground a second time.
  • docs/agents/pi.md (162 lines) is the best of the six guides, but "Verified depth" is in the middle. cmd/agentop/README.md → "Routing Pi through Cortex (agentop configure pi)" covers it a second time.

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/bob.md, docs/agents/opencode.md and docs/agents/pi.md.
  2. Move the per-agent configure sections out of cmd/agentop/README.md:
    • The Bob shell section and the Bob editor section, with all their H3 subsections ("Which file it writes", "Symlinks", "What status does and does not know", "Trusting Cortex's CA without the keychain (macOS)", "What it knows, and what it does not"), go into bob.md → "How it works". Keep the heading texts.
    • Merge the OpenCode section into opencode.md. Remove each fact that opencode.md already states. Move only what is new.
    • Merge the Pi section into pi.md in the same way.
    • In cmd/agentop/README.md, replace each moved section with one line under "Per-agent configure": agentop configure <agent>, and a link to docs/agents/<agent>.md.
    • Update every inbound link. For example, docs/agents/bob.md links #routing-the-ibm-bob-editor-through-cortex-agentop-configure-bob. Use grep and the link checker.
  3. bob.md "Use it": agentop configure bob enable covers both the editor and the bob shell command. Then quit the editor and start it again from the Dock, or the equal step on Linux. Then open a new terminal for bob. Check every fact in the configure bob code in cmd/agentop.
  4. opencode.md "Use it": start opencode, and say what to restart when it runs as a service. Take this from its existing service-model text.
  5. pi.md:

Acceptance

Out of scope

claude-code, codex and any-agent (sub-issue #1940).

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