Skip to content

docs: Reorder laptop-service.md for daily use #1942

Closed

Description

@huang195

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 -9 demonstration, 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: and tls_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:

  1. Intro: the agentop service command block, and the agentop doctor and agentop uninstall paragraph. Then the warning: never use kill or pkill. Keep only the first sentence of its reason here.

  2. "Is it working?"

  3. "Start and stop"

  4. "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.

  5. "Remove it": promote it from ### to ##, with its H4 subsections promoted one level. The anchor #remove-it does not change.

  6. "Re-running the installer is safe". A code comment in cmd/agentop/cmd_service.go names this section by title, so keep the title.

  7. "Automatic updates"

  8. "Linux: staying up after you log out"

  9. 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.

  10. A new H2, "Configuration". It holds "The memory: configuration" and "The tls_bridge: configuration" as H3.

  11. A new H2, "How it works". It holds:

    • "The supervisor" (new H3). Move the kill -9 demonstration, the macOS two-process text and the praxis three-process text from the intro.
    • "How traffic is grouped into sessions"
    • "The cpex build"

2. Replace the duplicates with links

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

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