docs: write the operator and authority documentation

[pashifika]

Summary

This pull request writes the repository's operator and authority documentation: CLAUDE.md becomes the authority for repository guidance, CONTRIBUTING.md is added for credentialed procedures only, and README.md is rewritten through the readme-creator skill. No code changes.

The gates these documents exist to explain are already live, and nothing in the repository stated them. This change addresses the following:

• .github/rulesets/main.json has been enforcing since a3acc2b — no direct or force push to main, a pull request with resolved threads, merge commits only, one strict status check named ci — and no file told a contributor or an agent that any of it was true.
• The standing prohibitions existed only as code comments, so each one was a rule with no reason attached and nothing to stop the next contributor from deleting it.
• There was no CONTRIBUTING.md at all, so the release path lived only in release.yml.
• README.md had accumulated from two changes' feature notes rather than being written for a reader arriving cold, and three of its documented facts turned out to be wrong.

Two prohibitions changed, not just moved

Two entries in the prohibition list were rewritten because their previous wording did not do the work it claimed.

• The AGENTS.md / RULES.md entry now states that it scopes to an operator's OMP agent directory at runtime and explicitly not to this repository's own root files. Without that sentence the rule appears to forbid the very file it is written in, and the resolution a reader invents may be to delete the rule. The mechanism is named: each is single-slot, so writing one replaces the operator's instructions rather than adding to them.
• The .omp/ entry admits no loophole. The previous text — never delete a directory this package or its verification did not create — permitted deleting one the verification did create, which is exactly how the operator's project-local config.yml and skills root were lost while cleaning up a plugin root under <project>/.omp/plugins/. The replacement forbids deleting .omp/ at either location, states that a verification step materializing it changes nothing, and requires cleanup to remove named paths one by one rather than a containing directory. It also records why the loss was silent: a global ignore excludes /.omp/, so git status never reports it missing. The incident is recorded next to the rule.

Three documented facts were wrong

Running every documented command against the package as built produced three corrections, all recorded in rasen/changes/operator-documentation/evidence/.

• The marketplace source format was wrong. omp plugin marketplace add github:pashifika/omp-codebase-memory is rejected with Unrecognized source format; the accepted form is owner/repo, which is what the sibling omp-toolgate README already documents.
• The marketplace install cannot resolve yet. .omp-plugin/marketplace.json names source.ref: "v0.1.0" and no tag exists, so the command fails with Remote branch v0.1.0 not found. The catalog is deliberately not repointed at main, because version-gate in release.yml requires catalog_ref == TAG. The README states the limitation instead.
• watcher_enabled was documented as a measured CBM default and no such key exists. CBM 0.10.8 exposes six config keys, watcher_enabled is not among them, and it is not a field in index_status output either. The change's delta spec has been corrected in the planning repository and now forbids documenting a key CBM does not expose. The README documents auto_index (false), auto_index_limit (50000), and auto_watch (true).

A fourth stale claim was removed rather than corrected: the README said CBM's installer configures 44 client surfaces, and 0.10.8 reports 43. A count that moves each release is drift with no operator value.

The declared license and the LICENSE file disagreed

LICENSE held the unmodified Apache License 2.0 template while package.json, .omp-plugin/marketplace.json, and README.md all declared MIT. Two contradictory statements of the distribution terms is a defect rather than a style question, and this pull request is the one that would have shipped MIT. See LICENSE as an operator-facing claim.

MIT is the side kept, for three reasons. Three metadata fields already said so; both sibling repositories in this account carry the identical 1066-byte MIT text; and the Apache file's own appendix still read Copyright [yyyy] [name of copyright owner], so it was never customized — a boilerplate drop, not a decision. No release has been tagged, so nothing was ever distributed under the conflicting pair. LICENSE is now byte-identical to omp-toolgate's.

README workflow and section shape

README.md went through every phase of the readme-creator skill. The skill's classification table has no row that fits this package — no bin, no main/exports, "private": true, omp.extensions present, and a skills/ directory that is harvested output rather than the product. The literal first-matching row is "skill bundle", which would have produced a one-command Quick Start and a skills table describing neither the executable lifecycle nor the MCP wiring. Classified as a CLI tool instead, by how operators actually consume it, with the harvested context surfaces folded into one extra section. The section order follows the sibling omp-toolgate README. Badges are omitted because nothing here is published to a registry.

What the review cycle changed

Three review rounds followed the first draft, and each found the same species of defect — an unmeasured inference about how OMP discovers a marketplace install — twice inside the correction to the previous one.

1. The README said a marketplace install does not deliver the rulebook rule, because the marketplace provider "contributes skills and agents but is not a rules provider". Both halves are false at the pinned OMP version: discovery/claude-plugins.ts:637 registers a Rule provider whose loadRules reads <root>/rules, and it registers no agents provider at all. That claim was not this change's invention — it is an accepted requirement at rasen/specs/durable-context/spec.md:89, with a scenario obliging the README to assert it, so correcting the README alone would have put it in conflict with an accepted spec.
2. The replacement rationale said both routes are discovered over one plugin-root list. Also an inference, also false: the routes run in two disjoint lanes, and omp-extension-roots.ts:361-379 drops any root whose realpath appears in the marketplace set so one plugin is not listed twice. Surface parity is real, but it comes from each lane registering the same providers.
3. The corrected rationale then stretched that lane argument over the MCP entry and the augmentation, which no provider lane serves. Their parity holds by a third mechanism — config.plugins[<package>], written identically by both install paths — and now carries its own citation.

The requirement that came out of round 1 is what caught rounds 2 and 3: an install-route difference is documented only where a measurement supports it, and unmeasured sameness fails that gate as surely as unmeasured difference.

Verification also found that the proposal declared two new capabilities while only one had a delta spec. rasen validate reported the change valid regardless, because it checks artifact presence rather than capability coverage — so twenty-one of the forty-six tasks would have left no accepted requirement behind on archive.

The change therefore carries four delta specs: two added (repository-conventions, operator-documentation) and two modifying accepted capabilities (durable-context, context-harvest).

Key files changed

The three documents, and what each now owns, plus the license correction.

File	Purpose
CLAUDE.md	The authority. Scope, layout, git workflow with branch naming and the merge-only reason, the CI contract, where a new test belongs, and the prohibition list with each entry's mechanism. AGENTS.md remains a tracked symlink to it
CONTRIBUTING.md	New. Only what needs maintainer credentials: the release path in order, and the ruleset import. Links the authority for every rule, and records that no DCO is required
README.md	Rewritten. Install routes with the marketplace route's one real limit, the /cbm surface, why indexing is the agent's work, configuration including the measured CBM defaults, the system-first policy with its cache-root reason, the graph-context surfaces, a refusals section, and the CBM version the shipped artifacts derive from
LICENSE	Replaced. The Apache 2.0 template gives way to the MIT text every manifest already declared

Test plan

• bun run typecheck — clean
• bun run test:unit — 409 pass, 0 fail
• bun run test:packaging — 10 pass, 0 fail
• Every documented command run against the package as built, each install under a mktemp -d HOME: git-spec install, the [] feature-declining install, omp plugin features --enable/--disable, omp plugin uninstall, omp plugin marketplace add + omp plugin discover, and omp plugin link .
• Every workflow claim checked against .github/rulesets/main.json and tags.json, and every documented path against the code that derives it in src/paths.ts
• CBM defaults checked against codebase-memory-mcp config --help and config list at 0.10.8
• AGENTS.md verified as a symlink in a fresh clone: mode 120000, blob is the target path, both names byte-identical
• An OMP session started at the repository root reports the authority text from its project context
• readme-creator quality checklist scored 27/27 applicable items, render check clean
• A read-only agent with no prior context answered installation, purpose, non-goals, and the branch rule from the three documents alone, and found no contradiction between them
• Every license claim agrees: package.json, .omp-plugin/marketplace.json, README.md, and LICENSE all say MIT, and LICENSE is byte-identical to the sibling repositories' text
• CI ci gate green on every pushed head, most recently 03a364d
• Three review rounds by fresh role-isolated reviewers, all 34 findings resolved, none declined — REVIEW CYCLE VERDICT: CLEAN. The one self-authored fix in the cycle was checked by a separate read-only worker rather than self-certified

🤖 Generated with omp