curate: the structural upkeep cycle

When to use it

• After a burst of edits, or on a schedule: settle the curation debt across reachability, backlog, completeness, and hygiene before it compounds.
• When orient reports validate errors or lint findings; curate is the verb that acts on them.
• Not when the content stopped being true. Curation is structural upkeep of the bundle as it stands; content that no longer matches reality is maintain's job.

What the agent does

1. Locate the bundle. The directory you named, else a .okf/ directory, else a root index.md whose frontmatter carries okf_version. If the okf CLI is missing, the agent stops and follows doctor first; nothing below works without it.
2. Measure. Three deterministic reads: okf validate --json, okf lint --json, and okf loose --json.
3. Interpret through the three lenses, kept separate. Conformance errors (section 9) are the only hard failures and get fixed first, always. Lint findings are advisory curation debt, ranked by how much each hurts a reader navigating the graph, not by raw count. Loose files can be legitimate terminal leaves, so each one gets judged before it gets linked anywhere. The curation model describes the categories lint reports across.
4. Propose, then apply. The agent lists the fixes worth making in order: must-fix errors first, then the debt worth settling, then the judgment calls. It applies the ones you confirm, or all the obvious ones when you asked it to just clean up.
5. Re-measure. validate and lint run again, and the report is the before and the after in two lines.

The measuring is entirely the CLI's; the ranking, the loose-file judgment, and the call on which debt is worth settling stay with the agent. In Claude Code with the plugin, a smaller version of this cycle also runs automatically after every edit inside a bundle.

Try it

In Claude Code with the okf plugin, run /okf:gem curate, or ask the skill in plain words:

Run a curation pass over docs/: fix any conformance errors and settle whatever curation debt is worth it.

Pitfalls

• Curate is structural; maintain is semantic. When curation surfaces a concept that parses fine but no longer matches reality, that is a maintain job, and the agent switches verbs for those concepts instead of patching them structurally.
• Do not chase zeros. Lint is advisory by design. Driving every count to zero can make a bundle worse: forced links on terminal leaves, deleted tags instead of a curated vocabulary. Rank by reader pain, fix what earns it.
• Loose is a review list, not a to-do list. A backlog item or a leaf reached only through its index can be loose by design, and that is not a defect.
• Errors always come first. Section 9 conformance failures are the only findings that block everything else; no amount of tidy tagging matters while validate is red.