Repository navigation
Closed
Labels
documentationImprovements or additions to documentationImprovements or additions to documentation
Description
Part 6 of the docs overhaul (parent: #1937). Start after sub-issue #1938 merges. This sub-issue uses its link checker. It touches only plugin docs, so it can run at the same time as sub-issues #1939, #1940, #1942 and #1944.
Problem
A laptop user who wants to turn on one feature cannot find it. A new plugin author follows a tutorial that does not work.
docs/plugin-catalog.mddoes not say where a plugin applies.- Its table has no laptop/Kubernetes column. Only
scriptsays "Laptop only". - Its first screen is the build-tag and "Production ready?" preamble.
- "Default config?" describes only the Kubernetes default AuthBridge pipeline. It does not show the laptop default.
- The file has no YAML example (zero code blocks).
- Its first sentence calls them "AuthBridge pipeline plugins".
scriptis out of alphabetical order.- The cpex entry does not say that the laptop cpex build is removed, and it does not link
praxis-policy.md. - "Cost records" and "
pricing:" are two "Moved" stub sections.
- Its table has no laptop/Kubernetes column. Only
- The catalog and seven plugin docs hold the same text word for word. The seven are a2a-parser, context-guru, inference-parser, jwt-validation, lineage-telemetry, mcp-parser and token-exchange. The two copies will drift.
- Some plugins have two docs and no clear owner.
docs/opa-plugin.md(12 lines) repeats the config table incore/plugins/opa/README.md(604 lines).docs/cpex-plugin.md(533 lines) andcore/plugins/cpex/README.md(651 lines) both hold deployment, build tag, hooks, config and decisions.- The
allowed_audiencesandplaceholder_modesections of jwt-validation live indocs/plugin-reference.md, not indocs/jwt-validation-plugin.md.
- The tutorial produces a plugin that does not register.
docs/plugin-tutorial.mdnever mentions the build taginclude_plugin_<name>, the filecore/plugins/all/plugins_<name>.goorscripts/profile-tags.- A build without the tag registers no plugin, and the config is rejected.
- Step 6 shows
cmd/cortex/plugins_extra.go. The real imports live incore/plugins/all/.
- Author docs have no order.
docs/README.mdlists the reference before the tutorial. The tutorial and the reference never linkscript-plugin.md, andscript-plugin.mddoes not link them back. - Counts are wrong.
core/plugins/README.mdsays "All seventeen", and its table has 17 rows. It leaves outscriptandtoken-exchange-aiac.core/plugins/all/has 19plugins_*.gofiles.- Its
localandfullprofile lines disagree withscripts/profile-tags/profiles.go. That file says local is the three parsers, tool-prune and script, and full is "all sixteen". docs/architecture.mdsays the full profile has "all fourteen".
- AuthBridge is used as the product name in:
plugin-catalog.mdplugin-tutorial.md("authbridge plugin")litellm-budget-track-plugin.mdsession-budget-plugin.mdtoken-broker-plugin.mdsparc-plugin.mdtool-prune-plugin.mdcpex-plugin.mdcore/plugins/opa/README.md
- History is mixed into reference text.
litellm-budget-track-plugin.mdcalls itself a "Design document", and it has "Future Work" and "Rates and ordering (changed)".static-inject-plugin.mdends with migration notes ("Now 403", MOCA AB2 smoke).inference-parser-plugin.mdexplains what happened "previously".
Tasks
1. docs/plugin-catalog.md
- First screen: "Plugins on a laptop".
- Say which plugins a local install runs by default. Get this from the default config that
cmd/cortex/local.gowrites, and from the profile that the release tarball is built with inscripts/profile-tags/profiles.go. - Say how to turn a plugin on, with script and inference-router (through
agentop server) as the examples. Do not present tool-prune as a cost lever (rule 11). - Give one YAML block that a laptop user can copy into
~/.cortex/config.yaml: the real defaultpipeline:, with no change. - Check the YAML: load it with a local build (
cortex --config <file>, or the config validation the binary runs at boot). Say in the PR body how you checked it.
- Say which plugins a local install runs by default. Get this from the default config that
- Table: add a "Where" column with the value Laptop, Kubernetes or Both.
- A plugin that needs cluster services is Kubernetes. Examples: SPIFFE, Keycloak,
/shared/client-id.txt, an in-cluster bundle server. - A plugin that the laptop default config or an
agentopcommand turns on is Laptop or Both. - The PR body lists the source for each row.
- A plugin that needs cluster services is Kubernetes. Examples: SPIFFE, Keycloak,
- Sort the table and the sections alphabetically.
- cpex entry: the laptop cpex build is removed. Link
praxis-policy.mdfor laptop policy. - Remove the copied paragraphs. For each plugin, the catalog keeps a summary of at most two lines and a link. The full text lives in the plugin doc.
- Replace the two "Moved" stub sections with one link line each, in a "See also" list.
- First sentence: "Cortex pipeline plugins".
2. One owner for each plugin's content
- opa.
docs/opa-plugin.mdis the operator page: what it does, when to use it, the config table, and where it runs.core/plugins/opa/README.mdkeeps policy authoring: decision paths, the input document, example policies and the bundle layout. Replace its config table with a link.
- cpex.
docs/cpex-plugin.mdis the operator page: deployment, config, decisions and denials.core/plugins/cpex/README.mdkeeps the internals: hooks and FFI. Replace its deployment notes with a link.- Move each duplicate fact once. Do not delete a fact that only one of the two files holds.
- jwt-validation. Move the
allowed_audiencesandplaceholder_modesections fromdocs/plugin-reference.mdintodocs/jwt-validation-plugin.md. Leave one link line. - Keep every
docs/<name>-plugin.mdfile, even the short ones. The catalog links one file per plugin.
3. docs/plugin-tutorial.md
- Add the build-tag step after the step that writes the plugin:
- Create
core/plugins/all/plugins_<name>.gowith//go:build include_plugin_<name>and the blank import. - Add the plugin to the membership map in
scripts/profile-tags/profiles.go. - Build with the tag.
- Create
- Copy the exact form from an existing file, for example
core/plugins/all/plugins_toolprune.go. - Fix Step 6 (
cmd/cortex/plugins_extra.go) to match. - Test the tutorial. In a scratch branch, follow every step as written, build
cortexwith the tag, and load the tutorial's YAML. The plugin must register, and the config must load. Do not commit the tutorial plugin. Say in the PR body what you ran. - At the top, say which doc to read when: the tutorial first, then
plugin-reference.md. For a quick plugin with no Go, readscript-plugin.md. script-plugin.md: link the tutorial where it says that Go plugins are for anything permanent.- Link
core/plugins/README.mdfrom the tutorial, for the package list.
4. Counts and lists
core/plugins/README.md: add thescriptandtoken-exchange-aiacrows. Replace "All seventeen" and the profile lines with a link toscripts/profile-tags/profiles.go. Do not write a count.
5. Naming and history
- Replace AuthBridge where it names the product or the pipeline. Keep it where it names an artifact:
- the image
- the container
- a ConfigMap
- a header
- the OPA policy package
authbridge.inbound.request, which is a wire name - a file name, such as
spend-authbridge.json
litellm-budget-track-plugin.md:- Remove "Design document", or say what the doc is now.
- Move "Future Work" and the "(changed)" history to a short "History" section at the end, or delete text that is no longer true.
- Check its link to
github.com/rossoctl/rossoctl/issues/2177withgh issue view. Fix the link if the issue lives inrossoctl/cortex.
static-inject-plugin.mdandinference-parser-plugin.md: give the present behavior only. Remove the migration and "previously" notes.
Acceptance
- A laptop user sees on the first screen of
plugin-catalog.mdwhich plugins run, which to turn on, and a YAML block that loads. - Every catalog row has "Where".
- No paragraph exists in both the catalog and a plugin doc.
- A plugin built by following the tutorial registers.
- The link checker passes.
Out of scope
docs/architecture.mdandlineage-telemetry-plugin.md's link todeploy/lineage-attach(sub-issue docs: Add the Kubernetes journey and clean up the contributor docs #1944 owns them).
Any change to plugin code.
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
documentationImprovements or additions to documentationImprovements or additions to documentation
Type
Projects
- StatusShow more project fieldsDone
Activity
docs: Add the plan for the plugin docs overhaul (#1943)
docs: Tighten the plugin docs plan (#1943)
docs: Show where each plugin applies in the catalog