Repository navigation
Description
Part 7 of the docs overhaul (parent: #1937). Start after sub-issue #1938 merges. This sub-issue uses its link checker and the new docs/README.md layout. It can run at the same time as sub-issues #1939, #1940, #1942 and #1943.
Problem
Kubernetes users have no journey
docs/kubernetes.md (62 lines) is the right entry point, but it does not cover the steps:
- Opt in. It says a workload "opts in with a label", but it never names the label. The operator code (
rossoctl/operator,operator/internal/webhook/injector/pod_mutator.go, functionInjectAuthBridge) does this:- It injects the sidecar only into a workload with the label
rossoctl.io/typeset toagent, or totoolwhen theinjectToolsfeature gate is on. - The label
rossoctl.io/inject: disabledopts a workload out. - A global feature gate can turn off all injection.
- The mode comes from
AgentRuntime.Spec.AuthBridgeMode, then the namespace ConfigMap, then the deprecated annotationrossoctl.io/authbridge-mode, then the cluster defaultproxy-sidecar(docs/architecture.md, "Deployment modes").
- It injects the sidecar only into a workload with the label
- Verify. The verify steps are spread across four places:
CONTRIBUTING.md(verify-spire-keycloak.sh)docs/session-api.md(a port-forward recipe thatkubernetes.mddoes not link)docs/framework-architecture.md(hot-reload status on:9093)- the external quickstart (
kubectl get deployments)
- Troubleshoot. No Kubernetes troubleshooting doc exists. The only one is in
deploy/lineage-attach/README.md, and no doc links it. - A wrong fact. It lists the modes as "proxy-sidecar, envoy-sidecar, lite".
liteis a build profile, not a mode (docs/architecture.md).
Architecture and reference docs repeat each other and use stale names
docs/architecture.md:- Its H1 is "# Cortex", and it calls the product "token management for Kubernetes". It does not say it is the sidecar architecture.
- Its image and mode tables repeat
cmd/README.md. - Its "Prerequisites" repeats
kubernetes.md. - Its "Component Documentation" list repeats
cmd/README.md.
cmd/README.md:- Its title is "AuthBridge Binaries", and it says "Two authbridge binaries". The binaries are
cortexandcortex-envoy. - It links the root
CLAUDE.mdfor hot-reload. That file holds agent notes, not user docs.
- Its title is "AuthBridge Binaries", and it says "Two authbridge binaries". The binaries are
docs/framework-architecture.mdsays "AuthBridge's plugin pipeline".core/llmclient/README.mdsays "authbridge plugins".deploy/proxy-init/README.mdcalls15123and15124"AuthBridge's" listeners. In redirect mode they are Envoy's (cmd/README.md, ports).docs/idp-plugin-contract.mdline 3 has the internal ticket id "RHAIENG-5681".deploy/sparc-service/README.mdsays "AuthBridge's Go sparc plugin". The plugin is Cortex's.SECURITY.mdlists "Helm lint" as a pre-commit hook..pre-commit-config.yamlhas no Helm hook, because the charts moved to the operator.
Files that no doc links
deploy/lineage-attach/{README,RECIPE,DESIGN}.md: a good set, with expected output for each step and a troubleshooting section.praxis/README.md: the Rust dev loop.core/pipeline/README.mdandcore/plugins/README.md: code-adjacent signposts, which can stay as they are.docs/proposals/*.md: records with correct status lines, reached through the directory link. Keep them.
New contributors do not find the dev loop
CONTRIBUTING.mdsends the reader to the rossoctl contribution guide before any local content.- Its first code block builds the proxy-init Docker image, which is a Kubernetes artifact.
- The laptop dev loop (
make agentop,make cortex,make dev-install) is in prose. - The test commands are only under "Code Style". No lint command is stated. The Rust loop is only in
praxis/README.md. - Its own Kubernetes dev-loop text says that one step does nothing without an image override that no longer exists.
The export docs repeat each other
docs/session-export.md (162 lines, the reference) and docs/session-export-guide.md (596 lines, the walk-through) repeat the commands and the agentop export flags. docs/session-dump.md says in its own banner that a laptop does not need it, but docs/README.md lists it under "Getting started".
Tasks
1. Make docs/kubernetes.md the journey
Add a table with one row per step: prerequisites, install, deploy, opt in, verify, configure plugins, troubleshoot. Each row says the step and links to the page that does it:
- Prerequisites and install the platform. The rossoctl quickstart (
https://www.rossoctl.dev/docs/get-started/kubernetes/) and the full install reference (rossoctl/rossoctl,docs/operate/install-kubernetes.md). Remove the copy of the prerequisites inarchitecture.md, and link this table instead. - Deploy an agent. The cortex-demos weather agent.
- Opt a workload in. Write this section in
kubernetes.mdwith the facts above.- Check each fact again in
rossoctl/operatoronmain(clone it, or usegh api). Name the file and function in a comment in the doc source. - Give a minimal Deployment label example.
- Check each fact again in
- Verify.
kubectl get podshows theauthbridge-proxycontainer.kubectl logs <pod> -c authbridge-proxy.- The session-API port-forward recipe from
session-api.md(link it). :9093/reload/statusfromframework-architecture.md(link it).- Check the container name against the operator's
AuthBridgeProxyContainerName.
- Configure plugins. The ConfigMap and its shape (
framework-architecture.md), hot-reload (§9), and the catalog's "Where" column (sub-issue docs: Show where each plugin applies and fix the plugin tutorial #1943). - Troubleshoot. A short "Troubleshooting" section in
kubernetes.md:- a pod with no sidecar: the label is missing or the gate is off
- a refused reload
- a link to
deploy/lineage-attach/README.md#troubleshootingfor lineage - a link to the external rossoctl troubleshooting page, if one exists (check with
curl -sI)
Remove "lite" from the mode list.
2. Architecture and reference cleanup
docs/architecture.md:- Change the H1 to "Cortex in Kubernetes: sidecar architecture", and add one sentence on who the page is for.
- Replace the image and mode tables and "Component Documentation" with links to
cmd/README.md.cmd/README.mdkeeps the tables. - Replace "all fourteen" (the full profile) with a link to
scripts/profile-tags/profiles.go. Do not write a count.
cmd/README.md:- Change the title to "Cortex binaries", and fix the first sentence.
- Replace the link to
CLAUDE.mdwithdocs/framework-architecture.md#9-config-hot-reload.
core/README.mdanddocs/framework-architecture.md: replace each link toCLAUDE.mdwith the user doc that covers the topic. Keep a link only where no user doc covers it.- Naming fixes:
framework-architecture.mdandcore/llmclient/README.md: the product and the pipeline are Cortex's.deploy/proxy-init/README.mdports: Envoy's in redirect mode.deploy/sparc-service/README.md: the plugin is Cortex's.
docs/idp-plugin-contract.md: remove the internal ticket id.SECURITY.md: make the pre-commit hook list match.pre-commit-config.yaml.
3. Link the orphans
docs/lineage-telemetry-plugin.mdandkubernetes.mdlinkdeploy/lineage-attach/README.md.CONTRIBUTING.md(dev loop) anddocs/praxis-policy.mdlinkpraxis/README.md.
4. CONTRIBUTING.md
-
First section: "Build, test, lint, run". Put each command in a code block:
make agentopmake cortexmake dev-install. Add a warning: it restarts the one shared local proxy and cuts every attached session.scripts/dev/go-test-shards.sh -short cmd/agentopgo test -race ./...per module, withGOWORK=offgo vet ./...gofmt -l .. Always give it a path.pre-commit install --hook-type pre-commit --hook-type commit-msg- the praxis
cargo fmt,clippyandtestcommands frompraxis/README.md
Check each command against the
Makefileand the CI workflows. -
Move the rossoctl contribution-guide link below this section.
-
Move the proxy-init image build into the Kubernetes section.
-
Kubernetes dev loop. Say at the top of the section what works today and what does not, in plain words. Take the facts from its existing text. Do not invent a fix.
5. Merge the export docs
- Merge
docs/session-export-guide.mdintodocs/session-export.md. Keep that path:cmd/agentop/cmd_export.goprints it.- Order: the guide's steps first, then the analysis and "the traps", then the cluster and scripting sections, then the field reference ("the record", reading rules, selection, flags, what it does not carry, truncation).
- Remove the second copy of the commands and the flags.
- Delete
docs/session-export-guide.md, and update every link to it. docs/README.md: put the export doc under "Daily use", and putsession-dump.mdunder "Reference" → Kubernetes.
Acceptance
- A new Kubernetes user can go from prerequisites to a verified sidecar using the
kubernetes.mdtable and its links. - The opt-in label and the opt-out label are named, and the code was checked.
CONTRIBUTING.mdstarts with build, test and lint commands, and each one runs.docs/session-export-guide.mdno longer exists. Each command and flag is described once, indocs/session-export.md.- No
.mdfile outsidedocs/superpowers/is unlinked. The exceptions are the threecore/signposts anddocs/proposals/. - The link checker passes.
Out of scope
docs/plugin-tutorial.mdand everydocs/*-plugin.mdexceptlineage-telemetry-plugin.md(sub-issue docs: Show where each plugin applies and fix the plugin tutorial #1943 owns them).- Fixing the Kubernetes dev loop itself.
- Changes in other repositories.
For a human after review
- If the external rossoctl Kubernetes quickstart is stale (it is labeled v0.8 but runs
git checkout v0.7.0), report it to the rossoctl site owners.
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 for the Kubernetes journey and docs cleanup
docs: Review the plan for #1944
docs: Fix names and duplicate tables in the reference docs