From 4e7fb433f0af752cf1ce236f7f8755cbfea0c12b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 1 Jun 2026 01:52:57 +0000
Subject: [PATCH 1/2] docs: update root README + constitution principle X for
 README sync (closes #10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The root README documented only `init` while 002/003 shipped `add`,
`verify`, `search`, and `index`. Rewrite it to cover the full command
surface (the consumer init→search→add→verify workflow plus the
origin-side index generator), refresh the exit-code table with the now-
live code 2 (verification failure), and align wording with the
consolidated skillrig skill.

Add constitution Principle X (User-Facing Documentation Co-Evolution):
the root README MUST be updated in the same branch as any command-surface
or user-facing behavior change, and a lagging README is a blocking review
finding — the standing obligation that prevents a repeat of this gap.
Bump constitution 2.1.1 → 2.2.0 and record it in the Sync Impact Report.
---
 .specledger/memory/constitution.md |  32 +++++-
 README.md                          | 157 +++++++++++++++++++++++++----
 2 files changed, 170 insertions(+), 19 deletions(-)

diff --git a/.specledger/memory/constitution.md b/.specledger/memory/constitution.md
index ee82bf3..65f1eb1 100644
--- a/.specledger/memory/constitution.md
+++ b/.specledger/memory/constitution.md
@@ -1,5 +1,15 @@
 <!--
   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) — the root README MUST be updated
+        in the same branch whenever the command surface or user-facing behavior changes;
+        the README is the entry-point doc and a stale one is a defect (002/003 shipped
+        new commands — add/verify/search/index — without updating it: the gap this closes).
+    Amended section:
+      - Development Workflow — added a bullet binding the root README sync to every CLI 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 +173,23 @@ 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
+The root **`README.md`** 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 stay
+in sync with the shipped behavior. Whenever a feature branch changes the **command
+surface** (adds/removes/renames a command or flag) or any **user-facing behavior**
+(exit-code meanings, origin-resolution rules, output contract, configuration file
+shape), that branch MUST update `README.md` in the **same branch** as the code. A
+README that documents only a subset of the implemented commands is a **defect**, not
+a backlog item — the same standard this constitution applies to the design docs
+(`cli.md`) and the consolidated skill (Principle IX). Reviews MUST treat an
+out-of-date README as a blocking finding.
+
+This principle is corrective: features 002 and 003 added `add`, `verify`, `search`,
+and `index` while the README still described only `init` (issue #10). The remedy is
+not a one-time cleanup but a standing obligation — every CLI change ships its README
+update, just as it ships its skill update.
+
 ## Architecture & CLI Design
 
 The detailed CLI architecture and command-pattern rules live in the git-tracked
@@ -212,6 +239,9 @@ 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.
+- The root `README.md` MUST be updated in the same branch whenever the command
+  surface or user-facing behavior changes (Principle X) — a README that lags the
+  implemented commands is a blocking review finding.
 - Every CLI change ships a skill update with verified trigger coverage (Principle IX).
 
 ## Agent Preferences
@@ -234,4 +264,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
diff --git a/README.md b/README.md
index f78f1ac..1de3fcb 100644
--- a/README.md
+++ b/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
 

From f73c4f09577f81f2b152eccb1b349f1de4c6b844 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 1 Jun 2026 07:17:20 +0000
Subject: [PATCH 2/2] docs: reword constitution Principle X per PR #12 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reframe Principle X as task-creation (a README-update task is created when
feature work changes CLI behavior) rather than a 'blocking defect', and
explicitly position it as an extension of the existing co-evolution
discipline (IX skill sync + the docs/design sync rule) — which named neither
the root README — instead of a standalone new rule. Update the Sync Impact
Report and the Development Workflow bullet to match.
---
 .specledger/memory/constitution.md | 52 +++++++++++++++++-------------
 1 file changed, 29 insertions(+), 23 deletions(-)

diff --git a/.specledger/memory/constitution.md b/.specledger/memory/constitution.md
index 65f1eb1..6623ff2 100644
--- a/.specledger/memory/constitution.md
+++ b/.specledger/memory/constitution.md
@@ -2,12 +2,15 @@
   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) — the root README MUST be updated
-        in the same branch whenever the command surface or user-facing behavior changes;
-        the README is the entry-point doc and a stale one is a defect (002/003 shipped
-        new commands — add/verify/search/index — without updating it: the gap this closes).
+      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 sync to every CLI change.
+      - 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)
@@ -174,21 +177,23 @@ architecture §2b). A skill that ships with a vague description is the same defe
 skillrig polices in others.
 
 ### X. User-Facing Documentation Co-Evolution
-The root **`README.md`** 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 stay
-in sync with the shipped behavior. Whenever a feature branch changes the **command
-surface** (adds/removes/renames a command or flag) or any **user-facing behavior**
-(exit-code meanings, origin-resolution rules, output contract, configuration file
-shape), that branch MUST update `README.md` in the **same branch** as the code. A
-README that documents only a subset of the implemented commands is a **defect**, not
-a backlog item — the same standard this constitution applies to the design docs
-(`cli.md`) and the consolidated skill (Principle IX). Reviews MUST treat an
-out-of-date README as a blocking finding.
-
-This principle is corrective: features 002 and 003 added `add`, `verify`, `search`,
-and `index` while the README still described only `init` (issue #10). The remedy is
-not a one-time cleanup but a standing obligation — every CLI change ships its README
-update, just as it ships its skill update.
+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
 
@@ -239,9 +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.
-- The root `README.md` MUST be updated in the same branch whenever the command
-  surface or user-facing behavior changes (Principle X) — a README that lags the
-  implemented commands is a blocking review finding.
+- 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