Repository navigation
Description
Part 5 of the docs overhaul (parent: #1937). Start after sub-issue #1938 merges. Sub-issue #1938 moves the troubleshooting sections out of docs/laptop-service.md. This sub-issue reorders what is left.
Problem
docs/laptop-service.md ("Running Cortex: start, stop, and remove it") is linked from the README and from every agent guide. It is in the wrong order for a user:
- The first screen shows the service commands, which is good. Then it shows a
kill -9demonstration, then the supervisor internals for macOS, then praxis-mode process details. - Internals and storage sections come before the daily ones:
- update provenance
- the cpex build
- session grouping
- cost and session storage
- plugin state
memory:andtls_bridge:
- "Is it working?" (about line 775), "Start and stop" and "Remove it" are near the end.
- "Remove it" is an
###under "Three ways to turn it off". The section has only two of the three ways in it.
Tasks
1. Reorder docs/laptop-service.md
Use this H2 order. Keep each heading's text, so its anchor stays valid, unless a change below says otherwise:
-
Intro: the
agentop servicecommand block, and theagentop doctorandagentop uninstallparagraph. Then the warning: never usekillorpkill. Keep only the first sentence of its reason here. -
"Is it working?"
-
"Start and stop"
-
"Three ways to turn it off": "Pause it" and "Unwire Claude Code". Name the third way, removing Cortex, in one sentence with a link to the next section. Or rename the section to match what it holds. If you rename it, update the inbound links.
-
"Remove it": promote it from
###to##, with its H4 subsections promoted one level. The anchor#remove-itdoes not change. -
"Re-running the installer is safe". A code comment in
cmd/agentop/cmd_service.gonames this section by title, so keep the title. -
"Automatic updates"
-
"Linux: staying up after you log out"
-
A new H2, "Where your data lives". It holds these sections, demoted to H3, with their headings unchanged:
- "Cost history is written to
~/.cortex/cost" - "Session history is kept in
~/.cortex/sessions" (with "Importing history from before Cortex" and "Clearing it" as H4) - "Plugin state is kept in
~/.cortex/plugin-state.json"
The anchors do not change when a heading level changes. Check with the link checker.
- "Cost history is written to
-
A new H2, "Configuration". It holds "The
memory:configuration" and "Thetls_bridge:configuration" as H3. -
A new H2, "How it works". It holds:
- "The supervisor" (new H3). Move the
kill -9demonstration, the macOS two-process text and the praxis three-process text from the intro. - "How traffic is grouped into sessions"
- "The cpex build"
- "The supervisor" (new H3). Move the
2. Replace the duplicates with links
- The CA "extends or replaces" text: link
docs/agents/any-agent.md, and keep it in one place only. - The Claude Code undo-by-hand steps: link
docs/agents/claude-code.md. - This sub-issue owns
laptop-service.md. Sub-issue docs: Put "Use it" first in the Claude Code, Codex and any-agent guides #1940 does not edit it.
3. Pointer at the top
Under the H1, add one line: "New to Cortex? Start with Getting started. For problems, see Troubleshooting."
Acceptance
- The H2 order is as above. Every section that existed before still exists once.
- The anchors in the "Keep these paths valid" list, and every anchor that other docs link, still resolve. The link checker shows this.
- No text is lost (word diff). The PR body lists any sentence that you changed, and why.
Out of scope
- The troubleshooting sections (sub-issue docs: Add the new-user path: getting started, troubleshooting and a link checker #1938 moved them).
docs/session-export*.mdanddocs/session-dump.md(sub-issue docs: Add the Kubernetes journey and clean up the contributor docs #1944).
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
Type
Projects
- StatusShow more project fieldsDone
Activity
docs: Add the plan to reorder laptop-service.md (#1942)
docs: Fix the claude-code.md link in the #1942 plan
docs: Reorder laptop-service.md for daily use