Skip to content

docs: Show where each plugin applies and fix the plugin tutorial #1943

Closed

Description

@huang195

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.md does not say where a plugin applies.
    • Its table has no laptop/Kubernetes column. Only script says "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".
    • script is 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.
  • 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 in core/plugins/opa/README.md (604 lines).
    • docs/cpex-plugin.md (533 lines) and core/plugins/cpex/README.md (651 lines) both hold deployment, build tag, hooks, config and decisions.
    • The allowed_audiences and placeholder_mode sections of jwt-validation live in docs/plugin-reference.md, not in docs/jwt-validation-plugin.md.
  • The tutorial produces a plugin that does not register.
    • docs/plugin-tutorial.md never mentions the build tag include_plugin_<name>, the file core/plugins/all/plugins_<name>.go or scripts/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 in core/plugins/all/.
  • Author docs have no order. docs/README.md lists the reference before the tutorial. The tutorial and the reference never link script-plugin.md, and script-plugin.md does not link them back.
  • Counts are wrong.
    • core/plugins/README.md says "All seventeen", and its table has 17 rows. It leaves out script and token-exchange-aiac. core/plugins/all/ has 19 plugins_*.go files.
    • Its local and full profile lines disagree with scripts/profile-tags/profiles.go. That file says local is the three parsers, tool-prune and script, and full is "all sixteen".
    • docs/architecture.md says the full profile has "all fourteen".
  • AuthBridge is used as the product name in:
    • plugin-catalog.md
    • plugin-tutorial.md ("authbridge plugin")
    • litellm-budget-track-plugin.md
    • session-budget-plugin.md
    • token-broker-plugin.md
    • sparc-plugin.md
    • tool-prune-plugin.md
    • cpex-plugin.md
    • core/plugins/opa/README.md
  • History is mixed into reference text.
    • litellm-budget-track-plugin.md calls itself a "Design document", and it has "Future Work" and "Rates and ordering (changed)".
    • static-inject-plugin.md ends with migration notes ("Now 403", MOCA AB2 smoke).
    • inference-parser-plugin.md explains 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.go writes, and from the profile that the release tarball is built with in scripts/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 default pipeline:, 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.
  • 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 agentop command turns on is Laptop or Both.
    • The PR body lists the source for each row.
  • Sort the table and the sections alphabetically.
  • cpex entry: the laptop cpex build is removed. Link praxis-policy.md for 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.md is the operator page: what it does, when to use it, the config table, and where it runs.
    • core/plugins/opa/README.md keeps policy authoring: decision paths, the input document, example policies and the bundle layout. Replace its config table with a link.
  • cpex.
    • docs/cpex-plugin.md is the operator page: deployment, config, decisions and denials.
    • core/plugins/cpex/README.md keeps 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_audiences and placeholder_mode sections from docs/plugin-reference.md into docs/jwt-validation-plugin.md. Leave one link line.
  • Keep every docs/<name>-plugin.md file, 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:
    1. Create core/plugins/all/plugins_<name>.go with //go:build include_plugin_<name> and the blank import.
    2. Add the plugin to the membership map in scripts/profile-tags/profiles.go.
    3. Build with the tag.
  • 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 cortex with 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, read script-plugin.md.
  • script-plugin.md: link the tutorial where it says that Go plugins are for anything permanent.
  • Link core/plugins/README.md from the tutorial, for the package list.

4. Counts and lists

  • core/plugins/README.md: add the script and token-exchange-aiac rows. Replace "All seventeen" and the profile lines with a link to scripts/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/2177 with gh issue view. Fix the link if the issue lives in rossoctl/cortex.
  • static-inject-plugin.md and inference-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.md which 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

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