Curation write-back

kcap curate apply writes the guidelines promoted for a repo into that repo’s CLAUDE.md / AGENTS.md, inside a managed block. It’s the file-based counterpart to session-start injection: instead of guidance appearing in the agent’s context automatically, it lives in your instruction files, in version control, visible in code review.

Write-back vs. injection

The curation pipeline lets you promote a fact-cluster to either of two independent targets, each putting guidance in front of the agent a different way:

Injection — automatic and ephemeral. Top clusters are fed into the agent’s context at the start of every session; nothing touches disk. (See Evaluations.)
Write-back (claude_md) — explicit and durable. kcap curate apply edits CLAUDE.md / AGENTS.md so the guidance survives outside Capacitor, ships in the repo, and shows up in git history.

Use either, both, or neither per cluster. This page is about write-back.

Prerequisites

Run it inside the git repo you want to update — the repo is inferred from your working directory and its git remote, so there are no scope flags.
At least one cluster must have been promoted with the CLAUDE.md target for that repo. Clusters promoted only for injection aren’t written.

Usage

kcap curate apply            # show the diff, then confirm (Apply? [y/N])
kcap curate apply --dry-run  # print the planned changes and exit, writing nothing
kcap curate apply --yes      # apply without the prompt (CI / scripting); -y for short

apply previews exactly what it will change and waits for confirmation, so the default run is safe to try.

The managed block

Guidelines are written into a single block bounded by HTML-comment markers:

<!-- kcap:curated:start -->
## Curated guidelines

_Managed by `kcap curate apply` — do not edit; changes are overwritten._

- <guideline text>
<!-- kcap:curated:end -->

Everything outside the markers is left untouched. Re-running reconciles the block against the currently-promoted set: guidelines are added, updated, or removed, and if nothing is promoted any more the block is deleted. Because the block is regenerated each time, don’t hand-edit inside the markers — put your own guidance above or below them.

Which files it writes

kcap curate apply targets the instruction files at the repo root:

Both exist → both CLAUDE.md and AGENTS.md are updated.
One exists → that file is updated.
Neither exists → AGENTS.md is created (the cross-harness default).

Safe to re-run

Applying is idempotent — run it as often as you like. It fails closed: if the managed block in a file has been hand-mangled (a missing or duplicated marker), the command aborts with a message to fix that file by hand rather than guessing. Nothing else in the file is rewritten.

Facts & curation — how clusters are promoted (and the CLAUDE.md target this command reads).
Evaluations — where the findings that become clusters come from.
Commands — the CLI reference.