@mnstry/atelier 0.2.0-alpha.1

package/docs/install.md

@@ -0,0 +1,140 @@
+# Install
+
+Repo Boundary Guard V1 is a local-first pattern for Atelier workspaces. It
+keeps private domain source in user-owned Git repositories and keeps shared
+project work in shared project repositories.
+
+## Posture
+
+- No telemetry.
+- No cloud service is required by Atelier.
+- No MNSTRY runtime mutation.
+- No direct browser writes or apply endpoints.
+- No GitHub provisioning from this package.
+
+Git repository access is the hard read boundary for source files. Local
+`kg.audience` labels guide projection and review, but they do not hide files
+from anyone who can read the repository.
+
+Use `atelier` as the primary CLI command in copied workspaces. The older
+`mnstry-atelier` binary is a legacy alias for compatibility.
+
+## Install Shape
+
+The registry is the distribution channel of record, as `docs/continuity.md`
+commits:
+
+```bash
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.1
+```
+
+Installing from the matching Git tag resolves to the same reviewed commit:
+
+```bash
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
+```
+
+Or over SSH:
+
+```bash
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
+```
+
+Keep the `@mnstry/` scope. The unscoped name `atelier` on npm belongs to an
+unrelated third-party package, so a bare `npx atelier` runs someone else's code.
+
+Do not install from `v0.2.0-alpha.0`. That tag is the **contract epoch
+marker** — `contracts/compat-baseline.json` pins the compatibility gate to it,
+so it stays where it is permanently. It predates the current tree and carries
+`publishConfig.access: "restricted"`.
+
+The workspace `atelier.lock.json` should record the resolved version or Git
+SHA from the install. Treat the tag or version as the friendly handle and the
+SHA as the review authority.
+
+Use one private domain repository per user:
+
+```text
+github.com/<org>/<github-login>-private-domain
+```
+
+Use shared project repositories for project work that the team can read:
+
+```text
+github.com/<org>/project-<project-slug>
+github.com/<org>/project-shared-library
+```
+
+The repository names above are examples. Create and permission repositories in
+GitHub or your internal Git host before pointing Atelier at them.
+
+## Tenant Workspace Example
+
+Default placeholder shape:
+
+- Actor id: `tenant-user`
+- GitHub login placeholder: `TENANT_GITHUB_LOGIN_PLACEHOLDER`
+- Private domain repo: `github.com/<org>/tenant-private-domain`
+- Shared project repo: `github.com/<org>/project-alpha`
+
+`TENANT_GITHUB_LOGIN_PLACEHOLDER` is not a real account. Set real identity
+values only inside the copied private workspace or through initializer flags.
+The example repositories are placeholders, not repositories created by this
+package release.
+
+## Local Setup
+
+Copy one of the starter templates:
+
+- `templates/private-domain-workspace/` for one user's private domain repo.
+- `templates/shared-project-workspace/` for shared project repositories.
+
+Prefer the CLI initializer when possible:
+
+```bash
+atelier init --template private-domain --target ./tenant-private-domain --actor tenant-user
+atelier init --template shared-project --target ./project-alpha --actor tenant-user
+```
+
+`--actor` rewrites the copied boundary policy actor entry and binds it to the
+local Git email when available. Use `--github-login` or `--git-email` to set
+those values explicitly during onboarding.
+
+Then update:
+
+- `atelier.project.json` repo paths.
+- `repo-access.v1.json` read boundaries.
+- `atelier.lock.json` with `atelier lock write` after choosing the exact Atelier package source.
+- README placeholders for project names and Git remotes.
+
+Keep project configuration tracked and local overlay state ignored. Track
+`atelier.project.json`, `repo-access.v1.json`, `boundary-policy.v1.json`,
+`atelier.lock.json`, and source documents. Do not track `atelier.local.json`,
+`atelier.workspace.local.json`, `.atelier-local/`, proposals/current/presence/
+nonce/grants/audit/session/support state, prompts, transcripts, support
+bundles, or generated projections.
+
+Run local-only checks from the copied workspace:
+
+```bash
+atelier graph --project ./atelier.project.json
+atelier project --project ./atelier.project.json
+atelier readiness --project ./atelier.project.json
+atelier readiness journey --project ./atelier.project.json
+atelier readiness run mnstry.readiness:identity-map --project ./atelier.project.json
+atelier readiness packet --project ./atelier.project.json
+atelier readiness export --dry-run --project ./atelier.project.json
+```
+
+These commands read local files and write generated local outputs only.
+
+## Upgrade Path
+
+The starter commands create `atelier.lock.json` inside the copied workspace so
+the installed Atelier package source, version, contracts, and migration state
+are reviewable. Refresh it from inside the copied workspace after choosing a
+registry or Git tag install. Local tarballs remain release-audit and
+smoke-test tools; they are not the default install path.
+
+See `docs/tenant-readiness.md` for the readiness review format and
+`docs/upgrade.md` for the full upgrade flow and boundary review checklist.

package/docs/knowledge-graph.md

@@ -0,0 +1,140 @@
+# MNSTRY Atelier Knowledge Graph
+
+The Atelier knowledge graph is a local, Git-backed operating model for project
+source material. It is not a taxonomy and it is not runtime retrieval. It is a
+durable model of source nodes, evidence, relationships, diagnostics, and
+projection readiness.
+
+## Source Rules
+
+- Markdown documents use front matter.
+- Non-Markdown sources use adjacent `.kg.json` sidecars.
+- `kg.id` is required and stable.
+- `kg.audience` is required.
+- `kg.visibility` is invalid in local source metadata.
+- Declared relations emit semantic edges.
+
+## Source formats
+
+The graph is sidecar-first: Markdown front matter is the only inline metadata
+format the kit reads, and every other file becomes a first-class node through
+an adjacent `<file>.kg.json` sidecar
+(`contracts/knowledge-source-sidecar.v1.schema.json`). This is how any format
+— json, yaml, csv, images, arbitrary binaries — joins the census without
+atelier ever parsing the foreign format itself.
+
+Two census rules follow:
+
+- Document extensions (`.md`, `.html`, `.pdf`, `.docx`) are always sources.
+  Non-Markdown documents *demand* a sidecar and fail closed without one.
+- Any other file *opts in* by carrying a sidecar. Without one it is simply not
+  knowledge-graph material — no error, no node. A sidecar whose adjacent asset
+  is missing is still an orphan error either way.
+
+A sidecar that Git ignores cannot enroll a file. Membership asks whether the
+sidecar is *visible* in tracked state, not whether it exists on this disk: an
+untracked, ignored `<file>.kg.json` is machine-local, so obeying one mints a
+node — with whatever audience it declares, up to `public` — that appears in no
+tracked file and on no other machine. The refusal runs both ways: an ignored
+sidecar enrolls nothing and describes nothing, so a document-extension asset
+whose only sidecar is ignored still fails closed with the ordinary
+missing-sidecar error, which is the verdict a clean checkout reaches anyway.
+Refused sidecars are named — a warning, `ignored-sidecar`, on `buildGraph`'s
+`ignoredSidecarWarnings(project)` and on the workspace builder's
+`ignoredSidecars`, printed by `atelier graph` — because dropping them silently
+is what let the injection through. They are reported *beside* the graph and
+never inside it: `buildGraph`'s return value is written verbatim as the
+artifact, and a machine-local observation there would churn committed bytes
+per machine, which is the failure the ignore filter exists to prevent.
+
+The sidecar branch is binary-safe by construction: the asset's bytes are never
+read. Identity, audience, and relations all come from the sidecar, so
+audience-based projection filtering, disclosure diagnostics, and the repo
+boundary guard treat a sidecar-described binary exactly like a Markdown
+document.
+
+Why the kit does not parse yaml (or csv, or anything else): the zero-dependency
+trust posture. Node ships no yaml parser, and pulling one in — or hand-rolling
+parsers for every format an adopter might commit — widens exactly the supply
+chain and attack surface the kit exists to keep auditable. Declared metadata in
+a schema-checked JSON sidecar is the trust boundary. Richer format adapters
+that derive metadata from asset contents belong to extension packs
+(`atelier-extension-pack.v1`), not the kit core.
+
+## Census Rules
+
+Graph and projection walks skip git-ignored paths. A committed artifact must
+describe the repository, not one machine's working tree — if `.mnstry-local/`,
+support bundles, editor scratch, or OS junk enter the census, every machine
+produces different bytes for the same commit and multi-machine workspaces
+rebase-conflict on every sync.
+
+The check is one batched `git ls-files --others --ignored --exclude-standard
+--directory` per repository root, not a per-file `git check-ignore`, which is
+too slow to survive contact with a real workspace.
+
+Repository *discovery* is deliberately not filtered this way: a git folder that
+appears in the workspace is an explicit decision for the operator to make (see
+the `external` repo kind), not something to drop silently.
+
+Determinism is a tested contract. `test/graph-determinism.test.mjs` builds
+twice, plants git-ignored junk between builds, and fails if any committed
+artifact changes a byte. It also asserts the planted paths really are ignored,
+so a dropped `.gitignore` pattern fails loudly rather than passing while the
+churn quietly returns.
+
+### Open decision: one writer
+
+Determinism guards the trigger, not the underlying shape. Committing generated
+artifacts and rebuilding them on every machine on every tick is inherently
+collision-prone: any nondeterminism that slips back in — a new census input, a
+Node version difference, a timestamp — reproduces the churn, and a machine that
+cannot fast-forward keeps publishing its own build, which is self-sustaining.
+
+The durable fixes are one-writer postures: generate in CI only, or stop
+committing projections and build them on demand. This is not yet decided. When
+the kit formalizes projection workflows for multi-machine adopters, one of those
+should become the documented default, with committed artifacts treated as the
+single-machine special case.
+
+## Projection Rules
+
+The graph feeds local views, readiness reports, and dry-run exports. A local
+projection may hide or emphasize material for a stakeholder, but it does not
+enforce object-level permissions. If enforcement is required, the project must
+use Git repo access locally or MNSTRY runtime permissions after import.
+
+## Collaboration Rules
+
+Git authorship is the primary local attribution signal. Actor and harness
+annotations are advisory context. Sensitive semantic fields should fail closed
+without an explicit review marker, while ordinary authored files can use normal
+Git merge/review workflows.
+
+## File Classification
+
+Every file the kit ships or generates belongs to one of three classes, declared
+once in the kit manifest's `fileClasses` and resolved through
+`classifyPath(path, { repoRole })`:
+
+| Class | Meaning | Safe automated handling |
+|---|---|---|
+| `source` | canonical, human or agent authored | never discard; conflicts need a human |
+| `generated-projection` | rebuilt deterministically every tick | discard and regenerate freely |
+| `distributed-runtime-copy` | canonical in ONE repo role, copied into consumers by runtime sync | rederivable in consumers, canonical where it is owned |
+
+A `distributed-runtime-copy` **must** declare `canonicalRepoRole`. This is the
+part that cannot be skipped: name-matching alone cannot tell the repo that owns
+a file from the repos that merely receive it. A self-repair loop that treats a
+runtime copy as authored work wedges the consumer in permanent rebase conflict;
+a sync loop that folds it into a plain "generated" list silently destroys
+canonical edits in the repo where it is source. The same path therefore resolves
+to `source` in its canonical role and `distributed-runtime-copy` everywhere else.
+
+Unclassified paths default to `source`, the fail-closed answer — never discarded.
+Later entries win, as in `.gitignore`, so an adopter can narrow a kit default by
+appending a more specific pattern.
+
+Adapters must not maintain shadow lists. `test/file-class.test.mjs` asserts the
+kit itself keeps no second copy: the graph walker's skip list is derived from the
+declaration, and the glob dialect lives in one module.

package/docs/ontology.md

@@ -0,0 +1,206 @@
+# Atelier export ontology
+
+The public vocabulary of the `atelier-export@v1` contract: the nine runtime
+owner terms, the object classes and export collections they govern, the six
+runtime targets an export may address, and the boundary between local
+`audience` and runtime `visibility`. Everything on this page is defined by
+the published schemas and the dry-run validator that ship in this package.
+
+## MNSTRY's format, offered openly
+
+The Atelier export format is MNSTRY's format, offered openly. Conformance is
+public and offline: the contracts, fixtures, and dry-run validator are all in
+this package, and anyone can check a document against them without a MNSTRY
+account, a network connection, or MNSTRY's involvement. Admission is a
+separate and narrower decision: MNSTRY's private validator only ever decides
+admission into a MNSTRY runtime. It never redefines conformance, and a
+document it declines can still be fully conformant. Nothing in this
+vocabulary requires MNSTRY approval to use.
+
+## How ownership is declared
+
+An export document declares, in `importPlan.runtimeOwners`, which runtime
+owner governs each object class it ships. An owner is an area of runtime
+authority — a named accountability for a category of governed records — not a
+module, a table, or a service. The owner enum is closed:
+
+`identity`, `catalog`, `commitments`, `events`, `projection`, `consent`,
+`messaging`, `providers`, `audit`
+
+Ownership assignments are made per document and reviewed at admission. The
+mapping from export collections to runtime targets, by contrast, is fixed by
+the contract and is not negotiable per document.
+
+Two namespace notes, because the same words appear at different levels:
+
+- The owner `consent` and the object class `consent_boundary` are different
+  namespaces. The class names a kind of exported object; the owner names the
+  runtime authority that governs objects of that kind.
+- The owner `projection` and the local generated projection are different
+  things. The local projection is a development preview of source material on
+  your machine; the owner term names the runtime authority over what is
+  actually shown to people.
+
+## The six runtime targets
+
+Every export collection maps to exactly one runtime target. Any declared
+target field anywhere in a document (`runtimeObject`, `targetObject`,
+`targetClass`, and their snake_case forms) must name one of these six values;
+anything else is a semantic-profile violation.
+
+| Runtime target | Meaning | Export collections |
+| --- | --- | --- |
+| `content.material` | Readable and renderable content | `offers`, `surfaces`, `sdui` |
+| `core.artifact` | Reviewable records and documents | `consentBoundaries`, `staffPrep`, `providerEgress` |
+| `core.trackable` | Measurable signals over time | `trackables` |
+| `scheduling.commitment` | Commitment paths and scheduled steps | `commitmentPaths` |
+| `space.space` | Spaces where activity happens | `spaces` |
+| `space.provision` | Provisioning of a space or provider capacity | (declared directly by readiness mappings) |
+
+The same mapping applies to import object classes: `offer`, `public_surface`,
+`surface`, and `sdui_block` target `content.material`; `commitment_path`
+targets `scheduling.commitment`; `space` targets `space.space`; `trackable`
+targets `core.trackable`; and `consent_boundary`, `staff_prep`, and
+`provider_egress` target `core.artifact`.
+
+## Audience and visibility
+
+These are two different vocabularies and the contract keeps them apart.
+
+**Audience** is local readership: `public`, `team`, `operator`, `staff`,
+`private`, `sensitive`. It classifies who source material is written for and
+whether it is eligible for projection. It is not a security boundary —
+repository access is the read boundary, and an audience label does not hide a
+file from anyone who can read the repository. Provenance source nodes carry
+`audience` and never `visibility`.
+
+**Visibility** is runtime authority: `private`, `shared`, `platform`,
+`public`. It is a security boundary on governed runtime objects, and the
+runtime default is private. Export objects carry `visibility` and never a
+local audience value.
+
+The validator enforces the separation in both directions: a local audience
+value appearing in a `visibility` field is rejected, a `visibility` key on a
+source node is rejected, and any object with public visibility must resolve
+its source references exclusively to public-audience source nodes.
+
+## The nine owner terms
+
+Each section gives the term's definition, what it governs in an export
+document, and what admission review checks for material assigned to it. The
+"governs" lists describe the characteristic assignments made by the bundled
+readiness protocols and the sample fixtures; a document may propose others,
+and the proposal is what admission review reviews.
+
+### identity
+
+Runtime authority over who someone is: accounts, actors, roles, and the link
+between locally described actors and governed identity records.
+
+Governs: no export collection creates identity records. Identity-owned
+material arrives as review artifacts (`staffPrep` entries targeting
+`core.artifact`) that describe actors and their roles.
+
+Admission review checks: every actor description carries source evidence and
+a declared owner; role claims trace to sources; nothing in the document
+creates or mutates an identity record.
+
+### catalog
+
+Runtime authority over what is offered: offers, their components, and their
+pricing.
+
+Governs: `offer` objects (the `offers` collection, targeting
+`content.material`).
+
+Admission review checks: pricing uses ISO-4217 currency codes and integer
+minor-unit amounts; every offer component carries an approval status; a
+public offer resolves only public-audience sources.
+
+### commitments
+
+Runtime authority over what participants commit to: commitment paths and the
+scheduled steps inside them.
+
+Governs: `commitment_path` objects (the `commitmentPaths` collection,
+targeting `scheduling.commitment`).
+
+Admission review checks: the plan is dry-run only — no scheduling writes;
+every step is present as reviewable material rather than an instruction to
+execute.
+
+### events
+
+Runtime authority over what happened: measurable signals recorded over time.
+
+Governs: `trackable` objects (the `trackables` collection, targeting
+`core.trackable`).
+
+Admission review checks: every trackable declares a runtime owner and a
+proposed runtime visibility; no local audience value leaks into a visibility
+field.
+
+### projection
+
+Runtime authority over what is shown: surfaces, generated display blocks, and
+the presented shape of spaces.
+
+Governs: `public_surface`, `surface`, and `sdui_block` objects (the
+`surfaces` and `sdui` collections, targeting `content.material`), and
+presentation-side `space` material.
+
+Admission review checks: public surfaces resolve exclusively to
+public-audience source nodes; the visibility gate defaults to private with a
+public-only source policy; an export from a dirty working tree must declare
+`forced: true` and carry a non-empty taint list.
+
+### consent
+
+Runtime authority over what has been agreed to: consent boundaries and their
+exceptions.
+
+Governs: `consent_boundary` objects (the `consentBoundaries` collection,
+targeting `core.artifact`).
+
+Admission review checks: boundaries default to private visibility; every
+exception is visible to audit; consent material fails closed — missing or
+ambiguous consent evidence blocks rather than warns.
+
+### messaging
+
+Runtime authority over what is sent to people: outbound messages and
+notifications.
+
+Governs: no bundled export collection maps to messaging. The term exists in
+the owner enum so a document can propose messaging ownership for review — for
+example, a journey handoff that would eventually notify a participant.
+Nothing in this format sends anything.
+
+Admission review checks: messaging-owned material is proposal-only; the
+document demonstrates that no send occurs locally and that any eventual send
+would be governed at the runtime.
+
+### providers
+
+Runtime authority over external service relationships: provider egress and
+the provisioning behind spaces.
+
+Governs: `provider_egress` objects (the `providerEgress` collection,
+targeting `core.artifact`) and provisioning review material targeting
+`space.provision`.
+
+Admission review checks: egress is declared, never performed; each declared
+provider crossing names its provider class and is individually reviewable.
+
+### audit
+
+Runtime authority over the record of decisions: evidence, review trails, and
+the trackables that prove a review happened.
+
+Governs: review artifacts (`staffPrep` entries targeting `core.artifact`) and
+review-trail trackables (the `trackables` collection, targeting
+`core.trackable`).
+
+Admission review checks: decisions leave a trail; evidence references resolve
+to provenance source nodes or to export objects that themselves carry
+provenance; nothing is silently dropped.

package/docs/release-engineering.md

@@ -0,0 +1,151 @@
+# Release engineering
+
+This document describes the enforcement surface for the Atelier package: the
+release gates, the CI lanes, the fork policy, and the version-bump surface.
+Every gate named here fails closed and reports findings as a generic label plus
+a location, never the matched content.
+
+## Gates
+
+### release:audit
+
+`npm run release:audit` (`scripts/check-release-tarball.mjs`) audits the exact
+tarball `npm pack` would publish:
+
+- Package metadata: name, license, exposed CLI bins, and a mandatory `files`
+  allowlist in `package.json`.
+- Tarball allowlist: every packed path must match a known-good pattern; any
+  unexpected file fails the audit.
+- Content scan: every packed file is scanned against committed structural
+  patterns (absolute user paths, machine-local temp paths, agent-local state
+  paths, key material, secret-like assignments) and against the maintainer-held
+  denylist described below.
+- Version drift: `CHANGELOG.md` must contain a `## <version>` heading and
+  `README.md` must mention the version. The expected version and tarball name
+  are derived from `package.json`, never hardcoded.
+
+Exit codes: `0` clean, `1` findings, `2` configuration error (for example an
+unavailable denylist without explicit acknowledgment).
+
+### repo:check
+
+`npm run repo:check` (`scripts/check-repo-disclosure.mjs`) sweeps the whole
+Git-tracked tree, not just the tarball:
+
+- Default mode scans every tracked text file line-by-line with the structural
+  patterns and the denylist.
+- `--staged` scans staged changes only, for local pre-commit use.
+- `--structural-only` is the intentional no-denylist lane used by CI jobs that
+  run without secrets.
+- `--commits <none|range|all>` adds the commit-identity gate and scans commit
+  messages in the selected range with the same patterns.
+
+Exit codes match `release:audit`: `0` clean, `1` findings, `2` configuration or
+usage error.
+
+### Commit-identity gate
+
+Part of `repo:check --commits`. Commit authors must match a hardcoded
+maintainer allowlist; committers additionally allow GitHub's merge identity,
+which GitHub-UI merges reintroduce. The allowlist is committed and reviewable
+in the script — it is not a secret.
+
+### migrations:check
+
+`npm run migrations:check` (`scripts/check-breaking-migrations.mjs`) keeps the
+changelog and the migration registry honest about breaking changes:
+
+- Every `**Breaking:**` changelog entry must match exactly one entry in
+  `scripts/breaking-changes.map.json`, and every map entry must match exactly
+  one changelog entry (no stale exemptions).
+- Map entries with a migration disposition must name an active breaking
+  migration in the registry, and every active breaking migration must be
+  referenced by the map.
+- Exempt entries require a non-empty reason and a date.
+- Every registered migration record is re-validated against the migration
+  record contract.
+
+### egress:check
+
+`npm run egress:check` (`atelier egress check`) scans package runtime paths for
+forbidden non-localhost egress. The package claims no network egress in runtime
+paths; this gate is the mechanical check behind that claim.
+
+### consumer:smoke
+
+`npm run consumer:smoke` (`scripts/consumer-smoke.mjs`) packs the real tarball,
+installs it offline into a throwaway consumer project with lifecycle scripts
+disabled, and imports the public API to validate a sample export. It proves the
+tarball is installable and functional exactly as a consumer receives it.
+
+### Egress-marker inventory
+
+The local-computed egress allow marker disables unresolved-target egress
+detection for a small window around each use, so its spread is pinned:
+`test/egress-marker-inventory.test.mjs` asserts the exact files and occurrence
+counts where the marker may appear. Widening that inventory is a reviewed
+decision, not a mechanical edit.
+
+## Denylist mechanism
+
+Beyond the committed structural patterns, content scans apply a maintainer-held
+pattern list supplied via the `ATELIER_RELEASE_DENYLIST` CI secret or a local
+gitignored file (`release-denylist.local.json`); the `ATELIER_DENYLIST_JSON`
+environment variable takes precedence over the file. Every audit fails closed
+when the list is absent; setting `ATELIER_ALLOW_MISSING_DENYLIST=1` explicitly
+acknowledges a structural-only run.
+
+Findings are reported as label plus location, never content — neither the
+pattern source nor the matched text is printed, and a pattern compile error
+prints the label only. Labels are themselves kept generic and are
+maintainer-reviewed before entering the list.
+
+## CI lanes
+
+Four jobs run on pushes to `main` and on pull requests, and all four are
+required status checks:
+
+- `test`: syntax check (`node --check`, not a type system), the full test suite, contract checks, `egress:check`, and
+  `migrations:check`. This job sets `ATELIER_ALLOW_MISSING_DENYLIST=1` scoped
+  to the job only — denylist assertions belong to the secret lane.
+- `consumer-smoke`: warms the npm cache with `npm ci` (the offline tarball
+  install needs the registry dependencies cached), then runs
+  `npm run consumer:smoke`.
+- `structural-sweep`: runs `repo:check --structural-only` with the
+  commit-identity gate over the pull-request range; on push builds the
+  `ATELIER_COMMIT_SCAN` repository variable selects the commit scan depth. No
+  secrets are required, so this lane runs for fork pull requests.
+- `secret-sweep`: the only lane with access to the denylist. It runs the full
+  `repo:check` (with the configured commit scan) and `release:audit`.
+
+## Fork policy
+
+Fork pull requests never receive repository secrets, so `secret-sweep` cannot
+pass in place. The job fails explicitly rather than skipping — GitHub treats a
+skipped job as satisfying a required status check, so an explicit failure is
+the only safe block.
+
+To clear a fork pull request, a maintainer verifies the head SHA and dispatches
+the `fork-sweep` workflow with the pull-request number and that SHA. The
+workflow runs the trusted scanner from `main` against the fork's tree checked
+out as data — it never installs or executes anything from the untrusted tree —
+re-verifies that the head SHA has not moved, and posts a `secret-sweep` check
+run on the SHA. The newest check run with that name supersedes the earlier
+failure for branch protection.
+
+`release:audit` never runs against untrusted code (`npm pack` executes
+lifecycle scripts); it re-runs on the push build of the merge commit. No
+workflow uses `pull_request_target`.
+
+## Version-bump surface
+
+A version bump touches exactly:
+
+- `package.json` (`version`)
+- `CHANGELOG.md` (a `## <version>` heading)
+- the pinned install tags in `README.md`, `docs/install.md`,
+  and `docs/upgrade.md`
+
+The release scripts derive the expected version and tarball name from
+`package.json`, so they are not part of the bump surface, and `release:audit`
+fails when the changelog heading or the README mention lags the bump.