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

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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

package/README.md

@@ -1,33 +1,41 @@
 # MNSTRY Atelier
 
-**Author your methodology once, in files you own, in a form machines can
-validate and runtimes can honor.**
-
-A methodology that creates real transformation cannot scale through static
-content, generic AI, or manual labor. Scaling it means giving it a form
-machines can carry — and most tools do that by taking the work into their
-platform, their format, their database, where it stops being fully yours.
-The Atelier answers the same problem the other way around.
-
-The Atelier is a local-first toolkit for authoring a body of work as
-structured documents machines can validate — plain files, in your own Git
-repositories, on your machine, under your control. You author primitives,
-sources, and offers; the Atelier builds a knowledge graph over them,
-projects a local review surface, checks readiness against published
-protocols, and validates exports against public contracts. There is no
-telemetry and no send path, and the commands that prove the package's
-promises are further down this page.
-
-It is built for methodology holders and the studios that serve them. The
-MNSTRY runtime — the governed platform for identity, consent, visibility,
-provisioning, bookings, commerce, sessions, audit, and client-grade
-sharing — is a separate, optional destination. The Atelier is the front
-porch, not the house: everything here works without ever talking to MNSTRY.
+**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.
+
+```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
+```
+
+`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
 
-A source document is a plain file with a small structured header. This is a
-complete, working example — fictional, like every fixture in this package:
+Here is a complete, working source document — fictional, like every
+fixture in this package:
 
 ```markdown
 ---
@@ -49,93 +57,35 @@ 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. From
-there the working loop is four commands:
+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
-atelier graph --project ./atelier.project.json      # build the knowledge graph
-atelier project --project ./atelier.project.json    # generate the local review surface
-atelier readiness --project ./atelier.project.json  # check against published protocols
-atelier dry-run ./atelier-export.json               # validate against the public contracts
+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
 ```
 
-Each one reads local files and writes local files. The `audience` field in
-the header is the load-bearing word: it declares who a source is written
-for (`public`, `team`, `operator`, `staff`, `private`, `sensitive`), and
-the machinery downstream refuses to let material travel further than its
-audience allows. A public export that references a non-public source is
-rejected — that check is fixture-pinned and mutation-tested.
-
-## The system
-
-Git is the database. The ontology is the schema. The validators are the
-constraints. The runtime is local. The design is five movements, each
-grounded in shipped machinery — [docs/design.md](docs/design.md) states
-them in full, ending each one with the command that proves it:
-
-**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. 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.** Eighteen contracts under a compatibility epoch
-define the vocabulary; fail-closed validators enforce it. A public export
-that references a non-public source is rejected — fixture-pinned and
-mutation-tested — and dry-run reports are deterministic: `accepted`,
-`importable`, `worstOperationStatus`. Twelve bundled claim-first readiness
-protocols check the work against published criteria and produce proposed
-claims, never runtime mutations.
-
-**Collaboration as governed disclosure.** Private-domain and shared-project
-repos have enforced roles: the boundary guard fails closed when private or
-sensitive material lands in shared space, when protected local files are
-staged, or when private-domain material appears in shared work without 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 repos.
-
-**A local runtime for humans and for agents.** The workspace projects two
-ways: a generated review surface over a loopback-only sidecar for humans,
-and session-bound context and capability envelopes for agent harnesses — a
-governed view with proposals recorded as metadata and no apply endpoints.
-Context without authority. Neutral Claude and Codex skill wrappers ship in
-the package.
-
-**A platform for your own tool.** A distribution wraps the CLI under your
-own name, contributes a validated extension pack, and themes the
-projection, while the root contracts, guards, and conformance stay
-canonical underneath — commercially if you want. See "Build your own tool
-on it" below.
-
-Methodology authoring is the first application, not the ceiling. MNSTRY
-built the Atelier to carry its own most demanding case — private
-transformational work, where a leaked document is a betrayal — and a
-system trustworthy enough for that is trustworthy enough for whatever you
-govern with it.
-
-## Quickstart
-
-```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.2
-
-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:
+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'
@@ -145,26 +95,12 @@ 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.
-
-## Status
-
-- Version: `0.2.0-alpha.2`
-- 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.2` on npm, published from the
-  `v0.2.0-alpha.2` 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 "Nothing leaves your machine" below.
+`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.
 
@@ -210,27 +146,110 @@ 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 -->
 
-## What this package will 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.
+<!-- 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.
 
-## Your documents and the 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.
 
-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.
+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
 
@@ -245,52 +264,34 @@ code yours. Start by copying the worked example:
 - `examples/loomworks-studio` — a complete fictional distribution: branded
   bin, extension pack, themed workspace template. It lives in this
   repository and deliberately never ships in the npm tarball.
-- `docs/distributions.md` — the contract a distribution must honor.
+- [`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 export format is MNSTRY's format, offered openly. 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`). The criteria are public; the checker is private;
-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.
-
-## 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     # 510 tests: 509 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     # 509 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
@@ -322,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

@@ -35,9 +35,10 @@ atelier graph --check --project ./atelier.project.json
 
 The ontology is not documentation. It is the enforcement mechanism.
 
-Eighteen JSON Schema contracts define the vocabulary — exports, project
-configuration, boundary policy, sidecars, locks, migrations, readiness,
-attestation — and fail-closed validators enforce it. The load-bearing
+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
@@ -103,9 +104,12 @@ 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 the honest answer to the question every team has right now: how do
-you put an agent inside private material safely? Not by trusting the
-agent — by projecting a bounded view and making writing impossible.
+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
@@ -127,9 +131,11 @@ 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. Contributions run inbound-equals-outbound with a DCO sign-off and
-no CLA — nobody, including MNSTRY, holds rights over your contribution
-that you do not also hold.
+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
@@ -144,9 +150,10 @@ 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.
 
-A system trustworthy enough for that is trustworthy enough for whatever
-you govern with it: a research corpus, a client practice, an editorial
-pipeline, a body of work that must outlive the tools that touch it.
+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

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.2
+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.2"
+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.2"
+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,19 @@ 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
@@ -72,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.2
-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.2"
-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.2",
+  "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"
   },