@mnstry/atelier 0.2.0-alpha.1 → 0.2.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.2.0-alpha.3
+
+Documentation and metadata release. No contract changes and no runtime
+behaviour changes: documents valid against `0.2.0-alpha.0` remain valid.
+
+- **The package's promises are now under a gate.** The checkable claims,
+  the will-not-do list, the conformance/admission separation, and the
+  audience/visibility rule live canonically in `docs/blocks/`, the README
+  embeds them verbatim between markers, and a test fails when they drift.
+  Promises converge by machinery; framing diverges by audience.
+- **The README is restructured as a depth ramp** — category and trust
+  posture first, the working loop with its visible result second, the
+  checkable claims third, boundaries fourth, architecture fifth, reference
+  last — and a new "Where the Atelier stops" section states the boundary
+  with MNSTRY's managed platform as a literal table.
+- **Overbroad claims are corrected.** "Trustworthy enough for whatever you
+  govern with it" is gone from the README and `docs/design.md` — controls
+  shaped for one demanding case do not establish adequacy everywhere; the
+  agent-runtime passage now states the narrow, testable control rather
+  than a general safety claim; "does not contact external services" now
+  carries its documented `gh` exception inline; contract and test counts
+  are stated by command, not by number; the contributions text now matches
+  `CONTRIBUTING.md`'s outside-PRs-not-open-yet posture; and
+  `docs/continuity.md` speaks of npm publication in the present tense.
+- **`npx` examples use the collision-free `mnstry-atelier` form.** The
+  unscoped npm name `atelier` belongs to an unrelated third-party package,
+  so a bare `npx atelier` outside an installed workspace runs someone
+  else's code. Every `npx` example on every surface now uses the branded
+  binary, `atelier` remains the documented command inside installed
+  workspaces, and `docs/install.md` no longer calls `mnstry-atelier` a
+  legacy alias — it is the safe form.
+- **npm metadata describes the package from the outside.** A concrete
+  description, registry keywords, and a homepage that resolves to the
+  published documentation page.
+
+## 0.2.0-alpha.2
+
+Documentation and release-lane release. No contract changes and no runtime
+behaviour changes: documents valid against `0.2.0-alpha.0` remain valid.
+
+- **The README is rebuilt around the system rather than its first
+  application.** New `docs/design.md` states the design in five movements —
+  a repository with an ontology, rules that refuse, collaboration as governed
+  disclosure, a local runtime for humans and for agents, and a platform for
+  your own tool — each ending with the command that proves it. Methodology
+  authoring is stated as the first application, not the ceiling.
+- **Publishing is automated on tag push** via npm trusted publishing (OIDC),
+  so releases carry a provenance attestation and no registry token is stored
+  anywhere. Two fail-closed guards: the tagged commit must be an ancestor of
+  `main`, and the tag must equal `package.json`'s version.
+- **The disclosure scanner no longer flags the OIDC permission key.**
+  `id-token` is a GitHub Actions permission, not a credential; the exemption
+  is the literal `id-` prefix only, and every other compound still matches.
+- **`0.2.0` was published in error and unpublished the same day.** A
+  `npm version patch` against an alpha resolves the prerelease to `0.2.0`
+  rather than advancing it, and `git push --follow-tags` delivered the tag
+  even though branch protection rejected the commit, so a release published
+  from a commit that never landed on `main`. That number is permanently
+  retired on npm. The ancestry guard above exists so this cannot recur.
+
 ## 0.2.0-alpha.1
 
 First release published to the npm registry, under `@mnstry/atelier` with

package/README.md

@@ -1,35 +1,106 @@
 # MNSTRY Atelier
 
-A methodology that creates real transformation cannot scale through static
-content, generic AI, or manual labor. The Atelier is a local-first toolkit for
-authoring that body of work as structured documents machines can validate —
-in plain files, on your machine, under your control.
-
-It is built for methodology holders and the studios that serve them: you
-author primitives, sources, and offers in your own repositories; the Atelier
-builds a knowledge graph over them, projects a local review surface, checks
-readiness against published protocols, and validates exports against public
-contracts. The MNSTRY runtime remains the authority for identity, consent,
-visibility, provisioning, bookings, commerce, sessions, audit, and
-client-grade sharing — using it is optional, and everything here works
-without it.
+**The Atelier makes a repository mean something.** It is a local governance
+toolkit for file-based bodies of work — a Node CLI and library with no
+service, no account, and no telemetry. Git is the database. The ontology is
+the schema. The validators are the constraints. The runtime is local.
+
+An ordinary file gains a small structured header: what this is, who it is
+for, what it relates to. That is the entire enrollment. From those
+declarations the Atelier builds a knowledge graph over your work, generates
+a review page you read in a browser on loopback, checks the work against
+published readiness protocols, and rejects what must never happen — a
+public export that quietly references a private source.
+
+MNSTRY publishes it under Apache-2.0 and authors its own workspaces with
+it. Everything here runs without ever talking to a MNSTRY runtime, so it
+can govern a methodology, a research corpus, an editorial pipeline, or any
+body of work that must outlive the tools that touch it. Every promise on
+this page ends in a command you can run.
 
-## Status
+```bash
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.3
+npx mnstry-atelier init --fixture=sample-workspace --target ./sample
+npx mnstry-atelier graph --project ./sample/atelier.project.json
+```
 
-- Version: `0.2.0-alpha.1`
-- Stability: alpha — contracts are under a compatibility gate from the
-  `v0.2.0-alpha.0` epoch tag onward; everything else may still move
-- Runtime: Node.js `>=22.18.0 <23`
-- Dependencies: ajv, ajv-formats (JSON Schema validation); nothing else at
-  runtime
-- Distribution: `@mnstry/atelier@0.2.0-alpha.1` on npm, published from the
-  `v0.2.0-alpha.1` tag. The older `v0.2.0-alpha.0` tag is the contract
-  epoch marker, not an install target — it predates the current tree.
-- Telemetry: none. Network egress: none, with one documented exception —
-  see "Nothing leaves your machine" below.
+`npx` here runs the binary already installed in `./node_modules/.bin` —
+always install first. Keep the `@mnstry/` scope: the unscoped npm name
+`atelier` belongs to an unrelated third-party package, so a bare
+`npx atelier` outside an installed workspace runs someone else's code.
+The branded `npx mnstry-atelier` form never collides with it; inside an
+installed workspace the shorter `atelier` command is also available, and
+that is the form npm scripts and the command reference below use.
+
+## What authoring looks like
+
+Here is a complete, working source document — fictional, like every
+fixture in this package:
+
+```markdown
+---
+title: "Grounding practice"
+summary: "The opening practice every offer in this catalog builds on."
+kg:
+  id: "my-studio:grounding-practice"
+  type: "document"
+  status: "active"
+  audience: "team"
+  relations:
+    supports: "my-studio:flagship-offer"
+---
+
+# Grounding practice
+
+The practice itself, in your words, in your file, in your repository.
+```
+
+That header is the entire enrollment. The graph builder reads front matter
+like this, and `.kg.json` sidecars for files that are not Markdown — JSON,
+YAML, CSV, media, anything — without ever parsing the foreign format. Your
+documents stay in your repositories, in formats you chose, readable
+without this tool. From there the working loop is four commands:
+
+```bash
+npx mnstry-atelier graph --project ./sample/atelier.project.json      # build the knowledge graph
+npx mnstry-atelier project --project ./sample/atelier.project.json    # generate the local review page
+npx mnstry-atelier readiness --project ./sample/atelier.project.json  # check against published protocols
+npx mnstry-atelier dry-run ./atelier-export.json                      # validate against the public contracts
+```
+
+After those four commands you have a generated graph, a browsable review
+page under your project's output directory, a readiness summary, and a
+dry-run report — all of them files in your repository, all of them
+diffable. `npx mnstry-atelier dev` serves the review page on loopback.
+
+<!-- atelier:block:audience-visibility:start -->
+The `audience` field in the header is the load-bearing word. It declares who
+a source is written for — `public`, `team`, `operator`, `staff`, `private`,
+or `sensitive` — and the machinery downstream refuses to let material travel
+further than its audience allows. Runtime and export `visibility` is a
+separate vocabulary (`private`, `shared`, `platform`, `public`) describing
+runtime exposure, and the validators reject every crossing between the two.
+Above all: a public export that references a source whose audience is not
+public is refused. That check is fixture-pinned and mutation-tested —
+deleting its enforcement fails tests, not documentation.
+<!-- atelier:block:audience-visibility:end -->
+
+The same machinery is a library:
+
+```js
+import { validateAtelierExportDryRun } from '@mnstry/atelier'
+
+const report = validateAtelierExportDryRun(exportDocument)
+console.log(report.accepted, report.importable, report.errors)
+```
+
+Real projects start from the `private-domain`, `shared-project`, or
+`distribution` templates instead of the sample fixture —
+[`docs/install.md`](docs/install.md) is the full install guide.
 
 ## Claims you can check
 
+<!-- atelier:block:claims:start -->
 This package makes three promises. None of them asks for your trust — each
 one names the command that proves it.
 
@@ -75,143 +146,152 @@ atelier dry-run ./atelier-export.json
 `docs/continuity.md` records the distribution commitments behind these
 claims, including the perpetual Apache-2.0 grant on every tagged release you
 receive.
+<!-- atelier:block:claims:end -->
 
-## Quickstart
-
-```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.1
-
-npx atelier init --fixture=sample-workspace --target ./sample
-npx atelier graph --project ./sample/atelier.project.json
-npx atelier project --project ./sample/atelier.project.json
-npx atelier readiness --project ./sample/atelier.project.json
-MNSTRY_ATELIER_ACTOR=owner npx atelier boundary check --project ./sample/atelier.project.json
-npx atelier dev --project ./sample/atelier.project.json
-```
-
-`npx` here runs the binary already installed in `./node_modules/.bin`. Always
-install first, and keep the `@mnstry/` scope — the unscoped name `atelier`
-belongs to an unrelated third-party package.
-
-`init` scaffolds a fictional sample workspace, `graph` builds the knowledge
-graph from front matter and sidecars, `project` generates the local review
-surface, `dev` serves it on loopback only. From there:
-
-```js
-import { validateAtelierExportDryRun } from '@mnstry/atelier'
-
-const report = validateAtelierExportDryRun(exportDocument)
-console.log(report.accepted, report.importable, report.errors)
-```
-
-Real projects start from the `private-domain`, `shared-project`, or
-`distribution` templates instead of the sample fixture.
-
-## What this package does
-
-- Initializes neutral local Atelier projects.
-- Builds a front-matter and sidecar-led knowledge graph; a `.kg.json` sidecar
-  enrolls any file — Markdown, JSON, YAML, CSV, media — without the kit ever
-  parsing the foreign format.
-- Generates and serves a local GUI projection over a loopback-only sidecar.
-- Produces agent-harness context and capability envelopes, and ships neutral
-  Codex and Claude skill wrappers for readiness review work.
-- Records proposal metadata without browser apply/write endpoints.
-- Enforces the local source `audience` and runtime `visibility` boundary, and
-  rejects unresolved, disguised, or non-public-projectable source references.
-- Enforces Repo Boundary Guard V1 for private domain and shared project
-  repos: strict policies fail closed when private or sensitive source is
-  placed in a shared repo, when protected local files are staged, or when
-  private-domain material appears in shared work without a `git.promote`
-  disclosure record.
-- Validates `atelier-export@v1` JSON against the published schema and
-  produces deterministic dry-run reports with `accepted`, `importable`, and
-  `worstOperationStatus`.
-- Ships the bundled `mnstry-readiness-pack@v1` with twelve claim-first
-  readiness protocols, extensible through validated extension packs.
-- Writes and checks `atelier.lock.json`, and applies branch-based,
-  review-first upgrades that refuse dirty repos and never silently overwrite
-  authored content.
-- Checks first-party source, templates, and examples for forbidden
-  non-localhost egress — a fail-closed discipline gate over this repo's own
-  code, not a runtime sandbox.
-
-## What this package does not do
+## What it will not do
 
+<!-- atelier:block:will-not-do:start -->
 - It does not write to a MNSTRY runtime database.
 - It does not import, provision, publish, or send anything.
-- It does not contact external services.
+- Except for the documented `gh` actor-resolution fallback, it initiates no
+  external network requests.
 - It does not execute model-assisted analysis or any model provider.
 - It does not include client project content.
 
 These limits are the design. An authoring tool for private material earns
 trust by what it refuses to be able to do.
-
-## Your documents and the boundary
-
-What you author is yours. Documents live in your repositories, in formats you
-chose, readable without this tool. The one vocabulary the contracts enforce:
-`audience` describes local source readership (`public`, `team`, `operator`,
-`staff`, `private`, `sensitive`); runtime/export `visibility` describes
-runtime exposure and accepts only `private`, `shared`, `platform`, or
-`public`. A public export referencing a source whose audience is not public
-is refused — that check is fixture-pinned and mutation-tested.
-
-## Build a branded distribution
-
-The Atelier is designed to be white-labeled. A distribution wraps the CLI
-under its own name, contributes a validated extension pack (branded
-protocols, terms, templates), and themes the projection — while the root
-contracts, guards, and conformance stay canonical underneath. Start by
-copying the worked example:
+<!-- atelier:block:will-not-do:end -->
+
+## Conformance is public, admission is separate
+
+<!-- atelier:block:conformance-admission:start -->
+The Atelier export format is MNSTRY's format, offered openly.
+
+**Anyone can check a document against the published contracts, forever,
+offline.** The contracts, fixtures, and dry-run validator all ship in the
+package, so conformance needs no account, no network, and no MNSTRY
+involvement.
+
+Admission is a narrower, opt-in decision: whether a MNSTRY governed runtime
+accepts a document for delivery to the people it serves. That is what
+admission buys — delivery through a runtime that enforces consent and
+visibility at serve time — and it takes the form of a signed MNSTRY
+attestation against criteria this package publishes (`docs/attestation.md`).
+The criteria are public, the checker is private, and the rejection message
+is part of the contract. You can build on the Atelier without ever talking
+to MNSTRY, and a document MNSTRY declines can still be fully conformant.
+<!-- atelier:block:conformance-admission:end -->
+
+## Where the Atelier stops
+
+The Atelier is a complete, standalone tool; nothing on the right side of
+this table is required to use it. MNSTRY's managed platform begins where
+local preparation ends:
+
+| The Atelier, today                    | The MNSTRY managed platform        |
+| ------------------------------------- | ---------------------------------- |
+| Local files and Git authority         | Runtime authority                  |
+| Knowledge graph and review projection | Governed delivery                  |
+| Readiness checks and proposed claims  | Runtime consent and identity       |
+| Offline conformance                   | Signed admission                   |
+| Proposal-only harness access          | Tenant applications and operations |
+
+## The system
+
+The full design lives in [`docs/design.md`](docs/design.md) — five
+movements, each grounded in shipped machinery, each ending with the command
+that proves it. In brief:
+
+**A repository with an ontology.** Front matter — or a `.kg.json` sidecar
+beside any format the kit never parses — declares a file's identity, type,
+audience, and relations. A node's `kg.id` names its canonical: the stable
+source-of-truth version of a thing that people, tools, and agents can refer
+to without losing meaning. The graph builder compiles the repository into a
+deterministic knowledge graph. No import step, no database: the repository
+is the store, and Git is the history, the review process, and the read
+boundary.
+
+**Rules that refuse.** JSON Schema contracts under a compatibility epoch
+define the vocabulary, and fail-closed validators enforce it — including
+the audience/visibility refusal above. Schema widening outside `ext`
+containers is refused by a schema-vs-schema differ, breaking changes
+require a new contract version with a recorded migration, and twelve
+claim-first readiness protocols check a workspace against published
+criteria to produce proposed claims, never runtime mutations.
+
+**Collaboration as governed disclosure.** Repositories have enforced roles:
+private-domain repos hold one person's source material, shared-project
+repos hold what a team may read, and the boundary guard fails closed when
+material crosses without a record. Crossing the boundary requires a
+recorded `git.promote` disclosure event — disclosure is a commit, not an
+accident. Change to the machinery itself is governed the same way: the
+lockfile records exactly what a workspace runs, and upgrades are
+branch-based, review-first, and refuse dirty repositories.
+
+**A local runtime for humans and for agents.** `atelier project` renders a
+projection — a contextual view of the same governed workspace. Humans get a
+generated review page over a loopback-only sidecar; agent harnesses get
+session-bound context and capability envelopes, with a place to record
+proposals and no apply endpoints. That is a narrow, testable control — a
+bounded view, and no write authority to grant — not a general claim that an
+agent is safe around private material. Neutral Claude and Codex skill
+wrappers ship in the package.
+
+**A platform for your own tool.** A distribution wraps the CLI under its
+own name, contributes a validated extension pack, and themes the
+projection, while the root contracts, guards, and conformance stay
+canonical underneath.
+
+It exists because some bodies of work are too important to live inside
+someone else's platform. MNSTRY built the Atelier to carry its own most
+demanding case — private transformational work, where a leaked document is
+a betrayal — and that case shaped the defaults: fail-closed boundaries, no
+telemetry, no send path, agents without authority, disclosure as a recorded
+event. Other domains reuse the mechanics and define their own ontology,
+protocols, and boundary policies. Methodology authoring is the first
+application, not the ceiling.
+
+## Build your own tool on it
+
+The Atelier is designed to be built on, under your name — including
+commercially. A distribution wraps the CLI under its own command,
+contributes a validated extension pack (branded protocols, terms,
+templates), and themes the projection, while the root contracts, guards,
+and conformance stay canonical underneath. Apache-2.0 makes commercial use
+a right, not a favor; the trademark policy keeps the name ours and the
+code yours. Start by copying the worked example:
 
 - `examples/loomworks-studio` — a complete fictional distribution: branded
-  bin, extension pack, themed workspace template.
-- `docs/distributions.md` — the contract a distribution must honor.
+  bin, extension pack, themed workspace template. It lives in this
+  repository and deliberately never ships in the npm tarball.
+- [`docs/distributions.md`](docs/distributions.md) — the contract a
+  distribution must honor.
 - `TRADEMARKS.md` — naming rules; Apache-2.0 grants code rights, not brand
-  rights. Every distribution carries "powered by MNSTRY Atelier" attribution,
-  checked by `atelier distribution check`.
-
-## The MNSTRY relationship
-
-The Atelier is the front porch, not the house. Conformance — is this document
-valid against the published contracts? — is public, offline, and free,
-forever. Admission — will MNSTRY's governed runtime accept it for delivery to
-clients? — is a separate, opt-in step: a signed attestation issued by MNSTRY
-against criteria this package publishes (`docs/attestation.md`). You can
-build on the Atelier without ever talking to MNSTRY. If you want your work to
-run on MNSTRY runtimes, the path is admission, and the rejection message is
-part of the contract.
-
-## Feedback and announcements
-
-Both channels respect consent by construction. `atelier feedback` writes a
-scanned, redaction-checked report to a local file — there is no send path;
-you choose whether and where to share it. `announcements list` verifies
-project-shipped announcements against a committed public key — pull-only,
-nothing phones home to ask.
-
-## Running the test suite from a fresh clone
+  rights. Every distribution carries "powered by MNSTRY Atelier"
+  attribution, checked by `atelier distribution check`.
 
-`npm test` includes one fail-closed check that expects a private denylist
-file (`release-denylist.local.json`, gitignored) used by MNSTRY's release
-lane. On a fresh clone that file is absent, so the check **fails** — it never
-passes silently on missing protection. Expect this, after `npm install`:
-
-```bash
-npm install
-npm test     # 509 tests: 508 pass, 1 fail — the denylist check, by design
-```
-
-To acknowledge the missing file and run the rest, which turns that failure
-into a recorded skip:
+## Status
 
-```bash
-ATELIER_ALLOW_MISSING_DENYLIST=1 npm test     # 508 pass, 0 fail, 1 skipped
-```
+- Version: `0.2.0-alpha.3`
+- Stability: alpha — contracts are under a compatibility gate from the
+  `v0.2.0-alpha.0` epoch tag onward; everything else may still move
+- Runtime: Node.js `>=22.18.0 <23`
+- Dependencies: ajv, ajv-formats (JSON Schema validation); nothing else at
+  runtime
+- Distribution: `@mnstry/atelier@0.2.0-alpha.3` on npm, published from the
+  `v0.2.0-alpha.3` tag. The `v0.2.0-alpha.0` tag is the contract epoch
+  marker, not an install target — it predates the current tree. The version
+  `0.2.0` was published in error and unpublished the same day; that number
+  is permanently retired on npm and will never be reused.
+- Telemetry: none. Network egress: none, with one documented exception —
+  see "Claims you can check" above.
 
 ## Command reference
 
+Commands below use the `atelier` form, which is what an installed
+workspace sees; from outside a workspace, invoke the same commands as
+`npx mnstry-atelier`.
+
 ```bash
 atelier dry-run ./atelier-export.json
 atelier contract check
@@ -243,20 +323,26 @@ atelier dev --project ./atelier.project.json
 authored repos, preserves unrelated user hooks through composed hook files,
 runs only registered migrations, refreshes generated projections, and leaves
 a Git commit for review. It will not weaken boundary policy, introduce
-telemetry, enable non-localhost egress, run model-assisted analysis, or write/import/apply
-runtime state.
-
-## Sample fixtures
+telemetry, enable non-loopback egress, run model-assisted analysis, or
+write, import, or apply runtime state.
 
-Fixtures in this package are fictional and generic. Project-specific adapter
-fixtures belong in their project repositories, not in the published Atelier
-package.
+`feedback create` writes a scanned, redaction-checked report to a local
+file — there is no send path; you choose whether and where to share it.
+`announcements list` verifies project-shipped announcements against a
+committed public key — pull-only, nothing phones home to ask
+([`docs/announcements.md`](docs/announcements.md)).
 
 ## License and contributing
 
 Apache-2.0. See `LICENSE`, `NOTICE` (attribution obligations that survive
 forks), `TRADEMARKS.md` (naming), and `docs/continuity.md` (distribution
-continuity commitments). Contributions are accepted under inbound-equals-
-outbound Apache-2.0 with a DCO sign-off — `CONTRIBUTING.md` is the working
-agreement, including how to contribute without exposing client material or
-your own private methodology.
+continuity commitments).
+
+Issues and questions are welcome. Outside pull requests are not open yet —
+a required CI check currently asserts maintainer commit identity — and
+`CONTRIBUTING.md` states that posture plainly, along with the
+inbound-equals-outbound Apache-2.0 terms and DCO sign-off that will govern
+contributions when they open. One expectation worth knowing before you run
+the suite: `npm test` from a fresh clone fails exactly one check by
+design — a release-lane protection whose private file is absent — and
+`CONTRIBUTING.md` explains the acknowledged-skip form.

package/docs/blocks/audience-visibility.md

@@ -0,0 +1,9 @@
+The `audience` field in the header is the load-bearing word. It declares who
+a source is written for — `public`, `team`, `operator`, `staff`, `private`,
+or `sensitive` — and the machinery downstream refuses to let material travel
+further than its audience allows. Runtime and export `visibility` is a
+separate vocabulary (`private`, `shared`, `platform`, `public`) describing
+runtime exposure, and the validators reject every crossing between the two.
+Above all: a public export that references a source whose audience is not
+public is refused. That check is fixture-pinned and mutation-tested —
+deleting its enforcement fails tests, not documentation.

package/docs/blocks/claims.md

@@ -0,0 +1,45 @@
+This package makes three promises. None of them asks for your trust — each
+one names the command that proves it.
+
+**Nothing leaves your machine, with one exception you can see.** There is no
+telemetry, no update check, no crash reporting, and no send path anywhere in
+the package. The exception: when no actor is configured, `boundary check` and
+`doctor` fall back to the `gh` CLI to resolve your GitHub login, which is an
+authenticated request to GitHub made with your own credentials. Set
+`MNSTRY_ATELIER_ACTOR` and that path is never taken. The only network client
+refuses non-loopback URLs, the served pages carry a policy that authorizes no
+external origin, and a fail-closed gate scans the executable and markup files
+under `src/`, `bin/`, `scripts/`, and `examples/` for egress primitives. Two
+limits worth stating plainly: the gate does not read the `.json` and `.md`
+files under `templates/` and `skills/`, and it does not model
+`child_process`, which is why the `gh` fallback above does not trip it:
+
+```bash
+npm run egress:check
+```
+
+**Compatibility is checked by machinery, not memory.** Documents valid
+against the `v0.2.0-alpha.0` contracts stay valid: every change is checked
+against the baseline tag's validators, and schema widening outside `ext`
+containers is refused by a schema-vs-schema differ. Breaking changes require
+a new contract version and a recorded migration. Known limit: the differ
+compares schemas structurally and does not resolve `$ref` pointers, so a
+`$ref` retargeted at a looser definition is not caught by this gate — the
+fixture tests catch that for contracts with negative fixtures, and closing
+the gap in the differ is tracked work:
+
+```bash
+npm run contract:compat
+```
+
+**Conformance works offline, forever.** Validating a document against the
+published contracts needs this package and nothing else — no account, no
+service, no network:
+
+```bash
+atelier dry-run ./atelier-export.json
+```
+
+`docs/continuity.md` records the distribution commitments behind these
+claims, including the perpetual Apache-2.0 grant on every tagged release you
+receive.

package/docs/blocks/conformance-admission.md

@@ -0,0 +1,15 @@
+The Atelier export format is MNSTRY's format, offered openly.
+
+**Anyone can check a document against the published contracts, forever,
+offline.** The contracts, fixtures, and dry-run validator all ship in the
+package, so conformance needs no account, no network, and no MNSTRY
+involvement.
+
+Admission is a narrower, opt-in decision: whether a MNSTRY governed runtime
+accepts a document for delivery to the people it serves. That is what
+admission buys — delivery through a runtime that enforces consent and
+visibility at serve time — and it takes the form of a signed MNSTRY
+attestation against criteria this package publishes (`docs/attestation.md`).
+The criteria are public, the checker is private, and the rejection message
+is part of the contract. You can build on the Atelier without ever talking
+to MNSTRY, and a document MNSTRY declines can still be fully conformant.

package/docs/blocks/will-not-do.md

@@ -0,0 +1,9 @@
+- It does not write to a MNSTRY runtime database.
+- It does not import, provision, publish, or send anything.
+- Except for the documented `gh` actor-resolution fallback, it initiates no
+  external network requests.
+- It does not execute model-assisted analysis or any model provider.
+- It does not include client project content.
+
+These limits are the design. An authoring tool for private material earns
+trust by what it refuses to be able to do.

package/docs/continuity.md

@@ -21,10 +21,9 @@ NOTICE attribution obligation and the trademark limits in `TRADEMARKS.md`).
    tag you fetched, with full Apache-2.0 rights over it. MNSTRY will not ask
    for deletion of received tagged source and has no license mechanism to do
    so.
-2. **npm publication at public release.** When the package's public flip
-   happens, tagged releases will be published to the npm registry under
-   `@mnstry/atelier` with public access, making the registry — not repository
-   permission — the distribution channel of record.
+2. **npm publication.** Tagged releases are published to the npm registry
+   under `@mnstry/atelier` with public access, making the registry — not
+   repository permission — the distribution channel of record.
 3. **Contract compatibility by machinery.** From tag `v0.2.0-alpha.0`
    onward, the published contracts are under a compatibility gate
    (`npm run contract:compat`): documents valid against the baseline tag must

package/docs/design.md

@@ -0,0 +1,161 @@
+# The design
+
+The Atelier makes a repository mean something. Files declare what they are,
+who they are for, and how they relate — and machinery enforces it.
+
+**Git is the database. The ontology is the schema. The validators are the
+constraints. The runtime is local.**
+
+This page states the design in five movements. Each one is a general
+primitive, grounded in a shipped mechanism, ending with the command that
+proves it — because a design document that cannot be checked is marketing.
+
+## 1. A repository with an ontology
+
+A small structured header turns a file into a node: front matter on
+Markdown, or a `.kg.json` sidecar beside any other format — JSON, YAML,
+CSV, media, anything — which the kit enrolls without ever parsing the
+foreign format. The header declares identity (`kg.id`), type, status,
+audience, and relations to other nodes.
+
+The graph builder compiles the repository into a knowledge graph,
+deterministically: same tree in, same graph out, and `--check` mode fails
+when a generated graph has drifted from its sources. There is no import
+step, no database, and no export lock-in. The repository is the store. Git
+is the history, the review process, and the read boundary you already
+trust — an audience label guides projection, but repository access is what
+actually hides a file.
+
+```bash
+atelier graph --project ./atelier.project.json
+atelier graph --check --project ./atelier.project.json
+```
+
+## 2. Rules that refuse
+
+The ontology is not documentation. It is the enforcement mechanism.
+
+The JSON Schema contracts under `contracts/` define the vocabulary —
+exports, project configuration, boundary policy, sidecars, locks,
+migrations, readiness, attestation — and fail-closed validators enforce
+it. The load-bearing
+separation is `audience` versus `visibility`: audience is local readership
+(`public`, `team`, `operator`, `staff`, `private`, `sensitive`), visibility
+is runtime authority (`private`, `shared`, `platform`, `public`), and the
+validators reject every crossing — a local audience word in a visibility
+field, a `visibility` key on a source node, and above all a public export
+that resolves any source reference to a non-public source. That last check
+is fixture-pinned and mutation-tested: deleting its enforcement makes tests
+fail, not documentation drift.
+
+The contracts sit under a stability epoch. Every change is checked against
+the baseline tag's validators, schema widening outside namespaced `ext`
+containers is refused by a schema-vs-schema differ, and a breaking change
+requires a new contract version with a recorded migration. Twelve bundled
+claim-first readiness protocols check a workspace against published
+criteria and produce proposed claims — never runtime mutations.
+
+```bash
+atelier dry-run ./atelier-export.json
+atelier contract check
+npm run contract:compat
+```
+
+## 3. Collaboration as governed disclosure
+
+Repositories have roles. A private-domain repo holds one person's source
+material; a shared-project repo holds what a team may read. The boundary
+guard enforces the difference and fails closed: private or sensitive
+source placed in a shared repo blocks, protected local files staged for
+commit block, and private-domain material appearing in shared work without
+a recorded disclosure blocks.
+
+Crossing the boundary is an event with a record: `atelier promote` writes a
+`git.promote` disclosure event, reviewable like any other commit.
+Disclosure is a commit, not an accident.
+
+Change to the machinery itself is governed the same way. The workspace
+lockfile records exactly which package version, contracts, extension
+packs, and migrations a workspace runs; upgrades are branch-based,
+review-first, refuse dirty repos, and never silently overwrite authored
+content.
+
+```bash
+atelier boundary check --project ./atelier.project.json
+atelier boundary check --staged --project ./atelier.project.json
+atelier promote --source-repo <private-repo> --target-repo <shared-repo> --kg-id <node>
+atelier lock check --project ./atelier.project.json
+```
+
+## 4. A local runtime for humans and for agents
+
+The same governed workspace projects two ways.
+
+For humans: a generated review surface, served by a sidecar that binds to
+loopback only. The served pages carry a policy that authorizes no external
+origin, and the only network client in the package refuses non-loopback
+URLs.
+
+For agents: session-bound context and capability envelopes that hand an
+agent harness a governed view of the workspace — what exists, what it may
+look at, what it may propose. Proposals are recorded as metadata; there
+are no browser apply endpoints and no write authority to grant. Context
+without authority. Neutral Claude and Codex skill wrappers ship in the
+package, so a harness can do readiness review work against the workspace
+without a single line of custom glue.
+
+This is a deliberately narrow answer to a broad question. It does not make
+an agent safe around private material in general; it makes one surface
+checkable: within the Atelier sidecar, a harness receives session-bound
+context and can record proposals, and there is no apply endpoint and no
+write authority to grant. A bounded view, with writing made impossible —
+a testable control, not a trust exercise.
+
+```bash
+atelier dev --project ./atelier.project.json
+atelier context flow --project ./atelier.project.json
+```
+
+## 5. A platform for your own tool
+
+The Atelier is designed to be built on, under your name, including
+commercially.
+
+A distribution wraps the CLI under its own command, contributes a
+validated extension pack — branded protocols, terms, templates — and
+themes the projection, while the root contracts, guards, and conformance
+stay canonical underneath. The repository carries a complete fictional
+reference distribution (`examples/loomworks-studio`) small enough to read
+in one sitting: a wrapper bin, a pack, a themed workspace.
+
+Apache-2.0 makes commercial use a right, not a favor. The trademark policy
+keeps the name ours and the code yours: every distribution carries
+"powered by MNSTRY Atelier" attribution, and the check is a command, not a
+request. The contribution terms are inbound-equals-outbound with a DCO
+sign-off and no CLA — nobody, including MNSTRY, holds rights over a
+contribution that the contributor does not also hold. Outside pull
+requests are not open yet; `CONTRIBUTING.md` states the posture and the
+terms that will govern them when they open.
+
+```bash
+atelier distribution check --target ./my-distribution
+atelier extension-pack validate --project ./atelier.project.json
+```
+
+## The first application
+
+Methodology authoring is the Atelier's first application, not its ceiling.
+MNSTRY built this to carry its own most demanding case: private
+transformational work, where a leaked document is not a bug but a
+betrayal. That case set the bar — fail-closed boundaries, no telemetry, no
+send path, agents without authority, disclosure as a recorded event.
+
+That case shaped the defaults. Other bodies of work — a research corpus, a
+client practice, an editorial pipeline, anything that must outlive the
+tools that touch it — reuse the mechanics, and each defines and validates
+its own ontology, protocols, and boundary policies.
+
+The claims behind this page are stated precisely, with their known limits,
+in the README's "Claims you can check" — each with the command that proves
+it. `docs/continuity.md` records the distribution commitments, including
+the perpetual Apache-2.0 grant on every tagged release you receive.

package/docs/install.md

@@ -1,8 +1,9 @@
 # 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.
+This is the install guide for Atelier workspaces. The workspace pattern it
+installs — Repo Boundary Guard V1 — keeps private domain source in
+user-owned Git repositories and keeps shared project work in shared project
+repositories.
 
 ## Posture
 
@@ -16,32 +17,36 @@ 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.
+Two command forms ship, and each has a place. Inside an installed
+workspace, use `atelier` — it resolves from `node_modules/.bin`, so npm
+scripts and workspace shells get the real binary. From outside a
+workspace, always use the branded `npx mnstry-atelier` form: the unscoped
+npm name `atelier` belongs to an unrelated third-party package, so a bare
+`npx atelier` outside a workspace runs someone else's code.
 
-## Install Shape
+## 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
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.3
 ```
 
 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"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.3"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.3"
 ```
 
-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.
+Keep the `@mnstry/` scope — see the command-form note above for why the
+unscoped name is dangerous.
 
 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,
@@ -68,7 +73,7 @@ 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
+## Tenant workspace example
 
 Default placeholder shape:
 
@@ -82,7 +87,7 @@ 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
+## Local setup
 
 Copy one of the starter templates:
 
@@ -128,7 +133,7 @@ atelier readiness export --dry-run --project ./atelier.project.json
 
 These commands read local files and write generated local outputs only.
 
-## Upgrade Path
+## Upgrade path
 
 The starter commands create `atelier.lock.json` inside the copied workspace so
 the installed Atelier package source, version, contracts, and migration state

package/docs/upgrade.md

@@ -5,6 +5,29 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.3
+
+No contract changes and no runtime behaviour changes: documents valid against
+`0.2.0-alpha.0` remain valid, and `npm run contract:compat` is clean against
+the same epoch baseline. Upgrading is a dependency bump.
+
+One thing worth knowing, because it changes what you type. Outside an
+installed workspace, use `npx mnstry-atelier` rather than `npx atelier`: the
+unscoped npm name `atelier` belongs to an unrelated third-party package, so a
+bare `npx atelier` there runs someone else's code. Inside an installed
+workspace both names resolve from `node_modules/.bin`, so npm scripts and
+workspace shells need no change.
+
+## Upgrading to 0.2.0-alpha.2
+
+No contract changes and no runtime behaviour changes: documents valid against
+`0.2.0-alpha.0` remain valid, and `npm run contract:compat` is clean against
+the same epoch baseline. Upgrading is a dependency bump.
+
+Note on version numbering: `0.2.0` was published in error and unpublished the
+same day. If a lockfile anywhere pins `0.2.0`, repin it to `0.2.0-alpha.2` —
+that number is permanently retired on npm and will not resolve.
+
 ## Upgrading to 0.2.0-alpha.1
 
 No contract changes and no authored-content changes: documents valid against
@@ -12,7 +35,7 @@ No contract changes and no authored-content changes: documents valid against
 the same epoch baseline. Upgrading is a dependency bump.
 
 Two things worth knowing. The package is now on the npm registry, so the
-install command changes from a Git reference to `@mnstry/atelier@0.2.0-alpha.1`
+install command changes from a Git reference to `@mnstry/atelier@0.2.0-alpha.2`
 — keep the `@mnstry/` scope, since the unscoped name belongs to an unrelated
 package. And a local sidecar that previously exited on a malformed request now
 answers it, so anything that supervised `atelier dev` through restarts can stop
@@ -62,16 +85,16 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.1
-npx atelier lock write --project ./atelier.project.json
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.3
+npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
 For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.1"
-npx atelier lock write --project ./atelier.project.json
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.3"
+npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
 Before accepting upstream changes, run the non-mutating upgrade planner:

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.3",
   "private": false,
-  "description": "Local-first MNSTRY Atelier workspace for agentic authoring, graph projection, and dry-run runtime readiness.",
+  "description": "Local CLI that compiles a Git repository into a validated knowledge graph — front-matter ontology, fail-closed audience boundaries, offline contract conformance. No telemetry, no service, no account.",
+  "keywords": [
+    "knowledge-graph",
+    "ontology",
+    "front-matter",
+    "local-first",
+    "json-schema",
+    "validation",
+    "provenance",
+    "governance",
+    "markdown",
+    "cli",
+    "agent-context",
+    "offline"
+  ],
   "type": "module",
   "bin": {
     "atelier": "bin/atelier.mjs",
@@ -65,7 +79,7 @@
     "type": "git",
     "url": "git+https://github.com/MNSTRY/atelier.git"
   },
-  "homepage": "https://mnstry.org",
+  "homepage": "https://docs.mnstry.ai/public-product/developers/atelier",
   "bugs": {
     "url": "https://github.com/MNSTRY/atelier/issues"
   },