docs(constitution): add Principle X on README co-evolution

.specledger/memory/constitution.md

@@ -1,5 +1,18 @@
 <!--
   Sync Impact Report
+  Version change: 2.1.1 → 2.2.0 (amendment — 2026-06-01, resolves issue #10)
+    Added principle:
+      X. User-Facing Documentation Co-Evolution (new) — when feature work changes CLI
+        behavior, a task MUST be created to update the root README so it never lags the
+        command surface. Explicitly framed as an extension of the existing co-evolution
+        discipline (IX skill sync + the docs/design sync rule), which named neither the
+        root README — the gap that let 002/003 ship add/verify/search/index while the
+        README still described only init (issue #10).
+    Amended section:
+      - Development Workflow — added a bullet binding the root README update task to every
+        CLI behavior change.
+    No other principle changes.
+  ---
   Version change: 2.1.0 → 2.1.1 (terminology patch — 2026-05-31, resolves issue #7)
     - §III ground-truth: "skills/*/skill.toml walk" → "skills/*/SKILL.md frontmatter walk
       (skillrig index)"; mise `[[requires]]` → `metadata.x-skillrig.requires` (manifest moved
@@ -163,6 +176,25 @@ to fight (it is the rationale behind the origin's `lint` conformance gate, cli.m
 architecture §2b). A skill that ships with a vague description is the same defect
 skillrig polices in others.
 
+### X. User-Facing Documentation Co-Evolution
+Whenever a user story / feature work changes the behavior of the CLI, a task MUST
+be created to update the root **`README.md`**. The README is the project's
+entry-point document — the first thing a human or agent reads to learn what the CLI
+does and how to use it — so it must not lag the shipped command surface
+(adds/removes/renames of a command or flag) or user-facing behavior (exit-code
+meanings, origin-resolution rules, output contract, configuration file shape).
+
+This is the same co-evolution discipline the constitution already applies
+elsewhere, extended to the README — it is **not** a new kind of rule:
+- Principle IX requires every CLI change to ship a matching **skill** update.
+- The *Architecture & CLI Design* and *Development Workflow* sections require the
+  `docs/design/` contract (notably `cli.md`) to be kept in sync in the same branch.
+
+None of those named the **root README**, which is exactly how features 002 and 003
+shipped `add`, `verify`, `search`, and `index` while the README still described only
+`init` (issue #10). Principle X closes that specific gap: the README's update task
+travels with the feature, the same way the skill and design-doc updates do.
+
 ## Architecture & CLI Design
 
 The detailed CLI architecture and command-pattern rules live in the git-tracked
@@ -212,6 +244,10 @@ implementation details evolve and live with the test code.
   [pattern-gate checklist](../../docs/design/checklist-template.md).
 - Design docs in `docs/design/` MUST be kept in sync with implementation changes;
   CLI behavior changes update `cli.md` in the same branch.
+- When a user story / feature changes CLI behavior, a task to update the root
+  `README.md` MUST be created so the README never lags the command surface
+  (Principle X) — the same co-evolution discipline as the skill (IX) and the
+  `docs/design/` contract above.
 - Every CLI change ships a skill update with verified trigger coverage (Principle IX).
 
 ## Agent Preferences
@@ -234,4 +270,4 @@ be justified against Principles VI, VII, and VIII. The binding CLI design contra
 is [docs/design/cli.md](../../docs/design/cli.md); changes to CLI behavior must
 remain consistent with it.
 
-**Version**: 2.1.1 | **Ratified**: 2026-05-24 | **Last Amended**: 2026-05-31
+**Version**: 2.2.0 | **Ratified**: 2026-05-24 | **Last Amended**: 2026-06-01

README.md

@@ -1,23 +1,52 @@
 # skillrig
 
-`skillrig` is a CLI for pointing a repository (or your per-user default) at an
-**origin** — the `OWNER/REPO` that hosts your team's agent skills — and resolving
-which origin is active for any working directory. An origin reference is
-`OWNER/REPO[@REF]`; the optional `@REF` tracks a specific branch.
+`skillrig` is a single, generic, **consume-only** CLI for pointing a repository
+(or your per-user default) at an **origin** — the `OWNER/REPO` that hosts your
+team's agent skills — and managing the skills you vendor from it. The same binary
+serves humans, agents, and CI. There is no `publish` and no write credential in
+the binary: GitHub is the authority plane ("publishing" a skill is a PR to the
+origin).
 
-> NOTE: a skillrig **origin** is a GitHub repository with a determined structure, use the template repository provided to create your own origin.
+An origin reference is `OWNER/REPO[@REF]`; the optional `@REF` tracks a specific
+branch.
+
+> NOTE: a skillrig **origin** is a GitHub repository with a determined structure;
+> use the template repository provided to create your own origin.
 
 ## Install
 
-Requires Go 1.24+ and `git` on your `PATH` (used for an offline repo-root lookup).
+Requires Go 1.24+ and `git` on your `PATH` (used for offline repo-root lookups,
+tree-SHA recomputation, and fetching skills over git).
 
 ```sh
 go build -o skillrig .
 ```
 
-## Usage
+## The workflow
 
-### Bind a repo to an origin
+Most consumers follow one path — bind an origin once, then discover, vendor, and
+verify skills:
+
+```sh
+skillrig init --origin my-org/my-skills      # 1. bind this repo to an origin
+skillrig search terraform                     # 2. discover what the origin offers
+skillrig add terraform-plan-review            # 3. vendor a skill into .agents/skills/
+skillrig verify                               # 4. prove vendored skills are unchanged
+```
+
+Origin **maintainers** also run `skillrig index` inside the origin repo to
+regenerate the catalog that `search` reads (see [`index`](#index)).
+
+Every command resolves the active origin the same way (see
+[Origin resolution precedence](#origin-resolution-precedence)), accepts `--json`
+for a complete machine-readable result, and accepts `--verbose` to surface the
+raw cause behind any summary or error.
+
+## Commands
+
+### `init`
+
+Bind a repository (or your global default) to an origin.
 
 ```sh
 # Run from anywhere in the repo; the config lands at the git repository root.
@@ -37,23 +66,109 @@ skillrig init --origin my-org/my-skills@staging
 The optional `@REF` is validated for shape only (offline) — it is not checked
 against the remote.
 
-### Set a personal default
-
 ```sh
-# Used when a repo has no origin of its own.
+# Set a personal default, used when a repo has no origin of its own.
 skillrig init --origin my-org/my-skills --global
+
+# Never prompt; fail fast if --origin is missing (safe for CI/agents).
+skillrig init --origin my-org/my-skills --non-interactive
 ```
 
-Writes `$XDG_CONFIG_HOME/skillrig/config.toml` (or `~/.config/skillrig/config.toml`).
+`--global` writes `$XDG_CONFIG_HOME/skillrig/config.toml` (or
+`~/.config/skillrig/config.toml`).
+
+### `search`
 
-### Scripts and agents
+Discover the skills your configured origin publishes by reading its catalog
+(`index.json`). Read-only; needs a resolvable origin but no git working tree. A
+free-text `QUERY` is a case-insensitive token-AND substring over
+name + description + topics (a skill matches only if **every** term is present),
+and `--topic` adds an exact-string AND filter. An empty result is success
+(exit 0).
 
 ```sh
-# Never prompt; fail fast if --origin is missing (safe for CI/agents).
-skillrig init --origin my-org/my-skills --non-interactive
+# List every skill the origin publishes.
+skillrig search
+
+# Free-text query (token-AND over name + description + topics).
+skillrig search terraform plan
 
-# Machine-readable result.
-skillrig init --origin my-org/my-skills --json
+# Filter by topic (repeatable; AND across topics).
+skillrig search --topic aws --topic terraform
+```
+
+### `add`
+
+Vendor a named skill from the configured origin into the canonical
+`.agents/skills/<skill>/`, recording its identity (version, commit, tree-SHA,
+path) in `.skillrig/skills-lock.json`. `add` copies the skill byte-identically,
+injecting nothing. It is idempotent on identical content and refuses to overwrite
+a vendored skill whose on-disk content diverges from the lock unless you pass
+`--force`. Requires a git repository; commit the result, then run `skillrig
+verify`.
+
+The acquisition form is chosen automatically and reported in the result:
+
+- **Local** — the configured origin is checked out at `<repo-root>/OWNER/REPO`;
+  `add` reads that checkout (no network). Keep the checkout out of your index
+  (e.g. `echo 'my-org/' >> .git/info/exclude`).
+- **Remote** — no local checkout exists; `add` fetches the skill subtree over git
+  from the origin, using a GitHub token from `GH_TOKEN` / `GITHUB_TOKEN` /
+  `gh auth token` when one is available (public origins need none).
+
+```sh
+# Vendor a skill from your configured origin.
+skillrig add terraform-plan-review
+
+# Pin an immutable version (a bare semver expands via the origin's tag scheme;
+# anything else is a literal git tag or commit SHA).
+skillrig add terraform-plan-review --pin v1.4.0
+
+# Preview what would be vendored, writing nothing.
+skillrig add terraform-plan-review --dry-run
+
+# Overwrite a locally-diverged copy with the origin's content.
+skillrig add terraform-plan-review --force
+```
+
+### `verify`
+
+Check **this** repository's vendored skills (`.agents/skills`) against the
+committed lock (`.skillrig/skills-lock.json`) — label-honesty (git tree-SHA) plus
+orphan/completeness — offline, deterministic, and read-only (it recomputes
+tree-SHAs and writes nothing). It needs no origin and no network, which makes it a
+load-bearing CI gate.
+
+```sh
+# Verify this repo's vendored skills match their recorded versions (CI gate).
+skillrig verify
+
+# Machine-readable per-skill verdicts for an agent / jq.
+skillrig verify --json
+```
+
+`verify` exits `0` when everything matches, `2` on any verification failure
+(mismatch / orphan / missing / dirty), and `1` on a usage problem (e.g. a
+malformed lock or not a git repo).
+
+### `index`
+
+**Origin-maintainer command.** Run inside the origin repo (locally or in CI on
+merge) to regenerate the origin's machine-readable catalog (`index.json`) by
+walking its skills directory and parsing each skill's `SKILL.md` frontmatter —
+the same parser `add` and `verify` use. It is a single-tip, full regeneration:
+the catalog is overwritten wholesale, sorted by name with a stable key order, so
+regenerating over an unchanged skill set is byte-identical.
+
+```sh
+# Regenerate index.json at the origin repo root.
+skillrig index
+
+# Write the catalog to an explicit path.
+skillrig index --out catalog/index.json
+
+# Machine-readable summary of what was generated.
+skillrig index --json
 ```
 
 ## Origin resolution precedence
@@ -78,12 +193,18 @@ SKILLRIG_ORIGIN  >  project .skillrig/config.toml (nearest ancestor)  >  global
 
 ## Exit codes
 
+Exit codes are part of the contract — scripts and agents branch on them, so their
+meanings are fixed:
+
 | Code | Meaning |
 |------|---------|
 | `0`  | Success (including an idempotent no-op) |
 | `1`  | Usage or configuration error (bad flags, invalid origin, no origin configured) |
+| `2`  | Verification failure (`verify` found a mismatch / orphan / missing / dirty skill) |
+
+Code `3` (prerequisite) is reserved for a future command.
 
-Codes `2` (verification) and `3` (prerequisite) are reserved for later commands.
+Errors go to **stderr**; data goes to **stdout**.
 
 ## Configuration file