Skip to content

docs: Add the Kubernetes journey and clean up the contributor docs #1944

Closed

Description

@huang195

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, function InjectAuthBridge) does this:
    • It injects the sidecar only into a workload with the label rossoctl.io/type set to agent, or to tool when the injectTools feature gate is on.
    • The label rossoctl.io/inject: disabled opts 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 annotation rossoctl.io/authbridge-mode, then the cluster default proxy-sidecar (docs/architecture.md, "Deployment modes").
  • Verify. The verify steps are spread across four places:
    • CONTRIBUTING.md (verify-spire-keycloak.sh)
    • docs/session-api.md (a port-forward recipe that kubernetes.md does 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". lite is 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 cortex and cortex-envoy.
    • It links the root CLAUDE.md for hot-reload. That file holds agent notes, not user docs.
  • docs/framework-architecture.md says "AuthBridge's plugin pipeline". core/llmclient/README.md says "authbridge plugins".
  • deploy/proxy-init/README.md calls 15123 and 15124 "AuthBridge's" listeners. In redirect mode they are Envoy's (cmd/README.md, ports).
  • docs/idp-plugin-contract.md line 3 has the internal ticket id "RHAIENG-5681".
  • deploy/sparc-service/README.md says "AuthBridge's Go sparc plugin". The plugin is Cortex's.
  • SECURITY.md lists "Helm lint" as a pre-commit hook. .pre-commit-config.yaml has 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.md and core/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.md sends 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:

  1. 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 in architecture.md, and link this table instead.
  2. Deploy an agent. The cortex-demos weather agent.
  3. Opt a workload in. Write this section in kubernetes.md with the facts above.
    • Check each fact again in rossoctl/operator on main (clone it, or use gh api). Name the file and function in a comment in the doc source.
    • Give a minimal Deployment label example.
  4. Verify.
    • kubectl get pod shows the authbridge-proxy container.
    • kubectl logs <pod> -c authbridge-proxy.
    • The session-API port-forward recipe from session-api.md (link it).
    • :9093/reload/status from framework-architecture.md (link it).
    • Check the container name against the operator's AuthBridgeProxyContainerName.
  5. 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).
  6. 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#troubleshooting for 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.md keeps 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.md with docs/framework-architecture.md#9-config-hot-reload.
  • core/README.md and docs/framework-architecture.md: replace each link to CLAUDE.md with the user doc that covers the topic. Keep a link only where no user doc covers it.
  • Naming fixes:
    • framework-architecture.md and core/llmclient/README.md: the product and the pipeline are Cortex's.
    • deploy/proxy-init/README.md ports: 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.md and kubernetes.md link deploy/lineage-attach/README.md.
  • CONTRIBUTING.md (dev loop) and docs/praxis-policy.md link praxis/README.md.

4. CONTRIBUTING.md

  • First section: "Build, test, lint, run". Put each command in a code block:

    • make agentop
    • make cortex
    • make 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/agentop
    • go test -race ./... per module, with GOWORK=off
    • go vet ./...
    • gofmt -l .. Always give it a path.
    • pre-commit install --hook-type pre-commit --hook-type commit-msg
    • the praxis cargo fmt, clippy and test commands from praxis/README.md

    Check each command against the Makefile and 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.md into docs/session-export.md. Keep that path: cmd/agentop/cmd_export.go prints 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 put session-dump.md under "Reference" → Kubernetes.

Acceptance

  • A new Kubernetes user can go from prerequisites to a verified sidecar using the kubernetes.md table and its links.
  • The opt-in label and the opt-out label are named, and the code was checked.
  • CONTRIBUTING.md starts with build, test and lint commands, and each one runs.
  • docs/session-export-guide.md no longer exists. Each command and flag is described once, in docs/session-export.md.
  • No .md file outside docs/superpowers/ is unlinked. The exceptions are the three core/ signposts and docs/proposals/.
  • The link checker passes.

Out of scope

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.

  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