feat: the sources corpus, the first build-loop steps, a release gate for non-plugin repositories and the plain-language install

.abcd/config/artefact.json

@@ -0,0 +1,5 @@
+{
+  "kind": "plugin",
+  "lockstep": [],
+  "site": false
+}

.abcd/config/reading-presets.json

@@ -60,10 +60,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1270000,
-        "measured_tokens_est": 1249424,
-        "measured_bytes": 4810285,
-        "measured_at": "f0746858220e04d862e00ff431dfec361756d52b"
+        "tokens_est": 1280000,
+        "measured_tokens_est": 1260415,
+        "measured_bytes": 4852600,
+        "measured_at": "3bc0c2f208aff2acb91cd4383a62fe2bea58ebf7"
       }
     },
     "entailment": {
@@ -133,9 +133,9 @@
       ],
       "window": {
         "tokens_est": 380000,
-        "measured_tokens_est": 367204,
-        "measured_bytes": 1413738,
-        "measured_at": "f0746858220e04d862e00ff431dfec361756d52b"
+        "measured_tokens_est": 375787,
+        "measured_bytes": 1446780,
+        "measured_at": "3bc0c2f208aff2acb91cd4383a62fe2bea58ebf7"
       }
     },
     "comparative": {
@@ -216,10 +216,10 @@
         "test"
       ],
       "window": {
-        "tokens_est": 1280000,
-        "measured_tokens_est": 1258460,
-        "measured_bytes": 4845073,
-        "measured_at": "f0746858220e04d862e00ff431dfec361756d52b"
+        "tokens_est": 1290000,
+        "measured_tokens_est": 1269451,
+        "measured_bytes": 4887388,
+        "measured_at": "3bc0c2f208aff2acb91cd4383a62fe2bea58ebf7"
       }
     }
   }

.abcd/development/brief/04-surfaces/01-ahoy.md

@@ -177,9 +177,10 @@ user-scope directory for machine-local state.
                                  that write holds .config.json.lock beside it
   memory/                        user-scope memory (personal, cross-project — a later
                                  phase; the shipped store is repo-scope .abcd/memory/)
-  sources/                       the local sources corpus /abcd:ingest and /abcd:consult
-                                 read. abcd NEVER creates it: absent means both verbs
-                                 say so and stop
+  sources/                       the local sources corpus the source verb maintains and
+                                 /abcd:ingest and /abcd:consult read. Created only by
+                                 its explicit init: absent means every other verb and
+                                 both commands say so and stop
   load-limits                    the load check's per-machine limits (stray-minutes,
                                  extreme-load), read-only; abcd never creates it
                                  (itd-2609231434459890)
@@ -379,13 +380,31 @@ about, one question per category present, never one per item.
 | `category` | Examples | Apply behaviour |
 |---|---|---|
 | `safe-autocreate` | the repo skeleton, history-store directories, the name-guard artefacts | applied once the category is approved, no per-item prompt; create-if-absent, never overwriting |
-| `config-change` | visibility, oracle adapter, the `PATH` entry, the git-identity pin | transparent confirm; skip-if-set with a "current value" notice |
+| `config-change` | visibility, oracle adapter, the `PATH` entry, the git-identity pin, the artefact kind | transparent confirm; skip-if-set with a "current value" notice |
 | `plugin-owned` | the marker block (itd-3); hook-manifest verification | silent overwrite on marker drift; a non-resolvable diagnostic for a malformed or missing manifest, and for a conventions file whose block would land inside a fence or HTML comment nothing closes (`marker.unplaceable`) |
 | `dependency` | the opt-in scanners | one category-level approval covering them; abcd never auto-executes a package manager, and the user runs the commands |
 | `status-line` | the offer of abcd's status line in the host harness | an advisory offer asked after its own question, written only on an answered consent; never under the approve-everything flag, and reported as optional work it skipped |
 | `oracle-routing` | the offer of abcd's proposed model-tier routing table (itd-2609170822093401): the machine's `~/.abcd/oracle-routing.json`, then, as a separate question, the repository's `.abcd/config/oracle-routing.json` | the proposal rendered as a table (agent, tier, fan-out) and each file written only on its own answered consent, the machine one owner-only; never under the approve-everything flag, and reported as optional work it skipped; a decline records nothing, so the next install offers again; uninstall leaves both files |
 | `user-state` | the registry entry, re-founding, stale or duplicate entries | guided; never auto-edit user-scope state, report extras read-only |
 
+**The artefact kind is a gap until it is declared** (itd-2609150819432059). A
+managed repository with no `.abcd/config/artefact.json` raises a required,
+resolvable `artefact.missing` gap, because the launch verbs choose what to
+preview, check and scaffold by the kind declared there and refuse to guess it.
+The apply pass writes the file once config changes are approved: a repository
+carrying `.claude-plugin/plugin.json` takes `kind: plugin` without a question,
+so the shipped shape adopts silently; any other is asked its kind, last of all
+the install's questions. An unanswered prompt takes `application`, the kind that
+assumes least about the build. An unattended install is not asked, and an
+answer naming none of `plugin`, `binary` and `application` is not refused: both
+declare `application` with a note saying what was heard, as the house-style
+question does, because withholding the declaration would leave every launch verb
+refusing the repository. The file is validated by
+the one reader the launch verbs share, before it is written and whenever it is
+read, so a declaration that is present and refused raises a non-resolvable
+`artefact.invalid` diagnostic instead: it is the user's file, and the install
+never overwrites it.
+
 **The questions come in a fixed order**, and the order is a contract rather than
 a presentation choice: answers are positional, so without it the Nth piped
 answer approves a different category on every run — a wrong answer that exits 0
@@ -400,6 +419,28 @@ agent drives the git-identity pin, the one approval no flag covers. Off a
 terminal each answer is echoed to the diagnostic stream, so a piped run leaves a
 transcript rather than a column of questions with no visible reply.
 
+**Every value question carries its own explanation** (iss-163). A question that
+picks one of several values (the repo visibility, the docs target, the oracle
+backend, the deep-scan toggle, the house-style question and each status-line
+element) is rendered with core's canonical help above it: what is being
+decided, then what each answer means, including what it asks of the person in
+keys, tools or cost. The oracle question defines an oracle before asking for
+one, and says plainly that every answer but host-delegated is recorded without
+changing how reviews run, because no other adapter ships. The words live in core, so every
+front door shows the same explanation and none invents its own; the question
+line itself is unchanged, so a piped answer stream lines up with it.
+
+**The result explains itself to the person who ran it** (iss-164). Beside the
+exact record (every write, change, note, declined category, outstanding step and
+optional step left undone), the install returns a one-sentence headline for its
+status and a plain-language summary: one item per kind of write, per declined
+category, for the required work still outstanding, and per optional step left
+undone, each saying what it is, why it matters and what, if anything, to do, and
+naming the paths or identifiers it explains. The words are core's, written for
+the product thinker and the technical facilitator rather than abcd's
+implementers, with no raw environment names; the text render leads with them and
+prints the exact record after as detail.
+
 Answers that run out read as end-of-file, and end-of-file declines every confirm
 and takes the default for every prompt, so an unattended run adopts nothing it
 was not told to adopt. The cost is that a stdin held open and silent makes a
@@ -453,9 +494,11 @@ hook as a running one.
 
 Two writes deserve their own note. The visibility step rewrites the ignore block
 under the config-change approval already given, with no confirmation of its own;
-its one extra line is a post-hoc note when a public fence had to be narrowed,
+its receipt adds a post-hoc note when a public fence had to be narrowed,
 because an ignore rule cannot untrack committed records, so the reader learns
-from the receipt that the committed record tiers stay published (iss-255). And a
+from the receipt that the committed record tiers stay published (iss-255). Like
+every install write, a block it could not write (a symlinked `.gitignore`, say)
+is a note naming the file and the reason, never a silent omission. And a
 remote URL recorded in the registry carries no credential: it is scrubbed where
 the identity is derived, scrubbed again as the index is *loaded* so every
 rewrite drops a credential from every entry rather than only the one being

.abcd/development/brief/04-surfaces/04-launch.md

@@ -14,12 +14,43 @@ And it never ships the design record: the payload is default-deny with the whole
 
 The preview always exits 0, because a preview never blocks, and its one write is
 its pre-flight report in the gitignored local tier. Bare `abcd launch` refuses
-with a hint to ask for it. A repository with no launch payload
-(`.abcd/config/launch-payload.json`) has nothing to preview, and the preview
-says so and names the release path it does have: the scaffolded release
+with a hint to ask for it. A repository that declares `kind: plugin` with no
+launch payload (`.abcd/config/launch-payload.json`) has nothing to preview, and
+the preview says so and names the release path a repository that ships no plugin
+has: declaring its kind as `binary` or `application`, the scaffolded release
 workflows, the dated CHANGELOG heading the cut writes, and the auto-release
 workflow that tags it.
 
+**Every verb runs against a declared artefact kind** (itd-2609150819432059). A
+managed repository says once what it ships, in `.abcd/config/artefact.json`:
+`kind` is `plugin`, `binary` or `application`, `lockstep` names the JSON files a
+non-plugin kind holds in lockstep with its version-location primary, and `site`
+reserves the release-rendered site's opt-in, read and not yet acted on.
+`binary` and `application` behave identically in every verb; the verify job's Go
+leg keys on `go.mod`, never on the kind. One
+reader in `internal/core/launch` validates the file for every launch verb and for
+`ahoy`, whose `artefact.missing` gap writes it — kind `plugin` without a question
+for a repository carrying a plugin manifest, otherwise the kind the operator
+answers. An unknown kind or a malformed declaration — an unknown or repeated key, or a
+lockstep entry key in another case, among them — refuses every verb before
+anything is written, naming the kind and the accepted set. The preview and the
+scaffold choose what to read and write by the kind, so they refuse a repository
+that has declared none, naming the file and the kinds and never a missing-file
+error; the cut, the archive render and the receipts check read an absent
+declaration as the plugin shape they have always assumed. The gate's inputs — the ledger, the anchor tag,
+the version location — are kind-independent, so the cut's derivation, its
+findings gate and the deferral read run unchanged for every kind; only the reads
+that bind a run to a plugin follow the kind. For a kind other than `plugin` the
+preview scans the tree the release tag would archive (`git archive`'s view of
+`HEAD`, `export-ignore` honoured, links excluded) minus the record namespace,
+denied by the same rule a plugin payload is held to, unless it declares an
+include set; the report names which tree it scanned. Its lockstep check reads
+the primary and every declared file, reads no plugin manifest, and refuses a
+declared file it cannot read. The rows that judge a plugin payload — the
+installability smoke and its deep tier, hook compliance, the parity diff — report
+`not_armed` and name the kind. For a kind that ships no plugin payload, the cut
+refuses to stage one and the archive render refuses outright.
+
 > **Phase ownership** ([adr-33](../../decisions/adrs/0033-launch-phase-ownership-tiered.md)): the curated-release cut — packaging with `.abcd/**` excluded plus the secret/PII scan — ships in [Phase 1](../../roadmap/phases/phase-1-ahoy.md). The pre-flight gate suite (itd-65) and the payload parity diff with the deep installability smoke (itd-66) run on the preview and on the cut's render path; the remaining release automation is separately scheduled (itd-70 retention, itd-72 publishing); itd-73 derived versioning ships with the release cut.
 
 ## Sub-verbs
@@ -118,9 +149,25 @@ version flag at all: the version is derived, never authored
 ([adr-31](../../decisions/adrs/0031-derived-versioning-from-intents.md)).
 
 **The scaffold writes the release machinery into a managed repo that lacks
-it**: the two release workflows, the adr-37 release runbook and a reviews-charter
-check, wired to the repo's own default branch and Go version and to the check
-names its own pull-request CI reports, token-scoped and injection-safe. The check
+it**, shaped by the declared artefact kind and refused without one. A plugin
+receives the two release workflows, the adr-37 release runbook and a
+reviews-charter check. Any other kind receives the gate as a workflow of its own,
+`abcd-release-gate.yml`, rendered from the same template, which is only ever
+called — never triggered by a tag push, so it cannot race a tag-driven workflow
+the repository already runs — plus the runbook and the charter check, a
+`CHANGELOG.md` holding only the empty `[Unreleased]` anchor when it has none (an
+existing changelog is never opened), and `auto-release.yml` calling the gate
+unless a release workflow of its own is in charge. That workflow is left
+byte-for-byte; the report names it as left alone and prints the job to add to it
+so it calls the gate before its build step, with `publish: false` so the gate
+verifies and tags only. Every scaffolded file is drift-checked the same way. A
+managed repository's workflow carries gate plumbing and a **named empty build
+job**: abcd does not guess how a repository builds (iss-2608270559310755), so the
+job holds one step to fill and names `dist/` as its output, and the publish job
+attaches whatever is left there. The verify job's Go leg renders only for a
+repository with a `go.mod`. Every file is wired to the repo's own default branch
+and Go version and to the check names its own pull-request CI reports,
+token-scoped and injection-safe. The check
 names are read from the repo's pull-request and merge-queue workflows — a name
 only a run knows (a matrix job, an expression-named job, a reusable-workflow
 call) is omitted rather than guessed, and every name is held to an injection-safe
@@ -134,12 +181,13 @@ are regenerated from, proved byte-exact by a test, so a scaffolded repo and this
 one cannot drift. The scaffolded workflow carries a **rehearsal** that arms the
 full gate against a simulated changelog roll and publishes nothing, so a green
 rehearsal is the runbook's precondition for a first real release. A bare repo
-with no semantic detector degrades cleanly to the deterministic gates and a
-generic build.
+with no semantic detector degrades cleanly to the deterministic gates and the
+empty build job.
 
 It is idempotent and fail-safe: a re-run on current machinery is a no-op
 (exit 0), a hand-edited file is refused (exit 1) rather than clobbered unless
-the caller confirms, and a structural fault exits 2.
+the caller confirms, and a structural fault, a missing declaration or an unknown
+kind exits 2 with nothing written.
 
 **The preview is spelled `dry-run`, and it is a flag, not a sub-verb.** The
 binary registers no `dry-run` subcommand under launch, and `commands/launch.md`

.abcd/development/brief/04-surfaces/08-abcd.md

@@ -86,8 +86,9 @@ here too.
 Binary-backed `/abcd:` verbs route through the transport-agnostic core (the CLI
 is the front door today; an MCP server follows later, per
 [adr-23](../../decisions/adrs/0023-transport-agnostic-core.md)). Not every verb
-does: `consult` and `ingest` run entirely as host-side markdown over the
-sources corpus and never invoke the binary. `prepare-this-repo` is the mixed
+does: `consult` and `ingest` run as host-side markdown over the sources corpus,
+and reach the binary only through the `source` verb, which makes every write to
+the corpus. `prepare-this-repo` is the mixed
 case: its audit half runs `abcd lint`, and its adoption half is binary-backed
 too and writes — the identity verb's initialiser records the repo's identity
 block and registers the surfaces held to it, and the ahoy installer lays the hooks, the