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

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.2.0-alpha.4
+
+Presentation release. No contract changes and no runtime behaviour changes:
+documents valid against `0.2.0-alpha.0` remain valid.
+
+- **The README now explains the system before the package.** It begins with
+  the repository as a durable substrate, then shows how ontology, enforcement,
+  governed projections, and a local runtime make the same work usable by
+  people, teams, agents, and tools.
+- **The story progresses with the reader.** Stewards and collaborators get the
+  purpose and working loop first; builders get the graph and library surfaces;
+  technical readers retain the exact, test-gated claims, limitations, and
+  conformance boundaries.
+- **Methodology authoring is presented as the proving ground, not the
+  category.** The package can support any file-based body of work whose
+  structure, relationships, disclosure, and readiness must remain portable and
+  enforceable.
+- **Package and installation metadata match the new public presentation.** The
+  prerelease remains explicitly pinned, and the coordinated MNSTRY developer
+  documentation carries the same conceptual spine.
+- **Bundled client instructions match the released CLI.** The Codex and Claude
+  open-Atelier skills use `atelier dev` and point registry users to the scoped,
+  collision-free install path.
+
+## 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,170 +1,234 @@
 # 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.
+**Turn a repository into a living, governed system.**
+
+Important bodies of work often begin as files: methods, research, programs,
+policies, editorial systems, product knowledge, or something no existing app
+quite understands. A folder can hold that work, but it cannot explain what each
+file is, how the pieces relate, who may see them, or whether the whole is ready
+to use.
+
+The Atelier adds that missing layer without taking the work away from you. It
+turns a repository into an ontology-governed knowledge graph, gives rules the
+power to refuse invalid states, and produces bounded views for people, teams,
+agents, and tools. Git remains the source of record. Your files remain readable.
+The runtime remains local.
+
+That makes the same repository useful at several levels:
+
+- A **steward** can shape a coherent system without surrendering it to a
+  proprietary database.
+- A **team** can collaborate through explicit roles, handoffs, and disclosure
+  boundaries.
+- A **person or agent** can receive the right context and capabilities for the
+  task, without receiving the entire repository.
+- A **toolmaker** can build a specialized or commercial product on the graph,
+  contracts, validators, and projections instead of inventing a new source of
+  truth.
+
+MNSTRY built the Atelier for a demanding case: a living body of methodology
+that must stay legible, internally connected, privacy-aware, and usable across
+many interfaces. Methodology authoring is one application of the system, not
+its definition or ceiling.
+
+## From files to a working system
+
+```text
+files you own
+    ↓ declare identity, type, audience, and relationships
+ontology-governed graph
+    ↓ apply contracts, policies, and readiness rules
+governed projections
+    ├── local review
+    ├── bounded agent context
+    ├── collaboration and disclosure
+    └── specialized tools and commercial distributions
+```
+
+You can see the complete loop in a disposable sample workspace:
+
+```bash
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.4
+npx mnstry-atelier init --fixture=sample-workspace --target ./sample
+npx mnstry-atelier graph --project ./sample/atelier.project.json
+npx mnstry-atelier project --project ./sample/atelier.project.json
+npx mnstry-atelier dev --project ./sample/atelier.project.json
+```
+
+Open the loopback URL printed by `dev`. The browser page is generated from
+the same graph and rules that the CLI and library expose.
+
+`npx` here runs the binary installed in `./node_modules/.bin`, so install the
+scoped package first. Keep the `@mnstry/` scope: the unscoped npm package
+`atelier` is unrelated. The branded `npx mnstry-atelier` command avoids that
+collision; inside an installed workspace, the shorter `atelier` command is
+also available.
 
 ## 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:
+Enrollment is deliberately small. A source file declares its identity, type,
+audience, and relationships in front matter:
 
 ```markdown
 ---
-title: "Grounding practice"
-summary: "The opening practice every offer in this catalog builds on."
+title: Breath practice
+summary: A simple preparation practice.
+tags: []
 kg:
-  id: "my-studio:grounding-practice"
-  type: "document"
-  status: "active"
-  audience: "team"
+  id: example:breath-practice
+  type: document
+  status: active
+  audience: public
   relations:
-    supports: "my-studio:flagship-offer"
+    belongs_to: example:flagship-program
 ---
 
-# Grounding practice
+# Breath practice
 
-The practice itself, in your words, in your file, in your repository.
+Let the exhale become slightly longer than the inhale.
 ```
 
-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:
+The file is still Markdown. Git still records its history. The declarations
+let the Atelier resolve one canonical identity, validate its declared shape,
+connect it to neighboring work, and decide where it may
+travel.
 
-```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
-```
+When a source format cannot carry front matter, a sidecar can provide the same
+declarations. The graph does not require every source to become Markdown.
 
-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
+From there, one source can inform a human-readable review page, a session-bound
+context envelope for an agent, or structured input to another tool. These are
+interfaces to the same governed repository, not copies that quietly drift apart.
 
-```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
-```
+## Rules travel with the work
 
-`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.
+The ontology is not only a vocabulary. It is an enforcement surface. Contracts
+define valid shapes, policies govern movement and disclosure, readiness rules
+make completion testable, and validators fail closed when a boundary cannot be
+proven.
 
-`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:
+<!-- 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 -->
 
-```js
-import { validateAtelierExportDryRun } from '@mnstry/atelier'
+That distinction matters whenever several interfaces share one body of work.
+A public site, an internal review tool, and an agent session can all use the
+same graph while receiving different, mechanically checked projections.
+
+## The system beneath it
+
+### 1. The repository becomes an ontology
+
+The project manifest tells the Atelier where sources live and which boundaries
+govern the workspace. Source declarations establish typed nodes and relationships. The
+graph command resolves those declarations into a deterministic index that can
+be queried, validated, rendered, and extended.
+
+This is what makes a collection of files behave like a system while remaining
+portable. The repository contains both the knowledge and the terms needed to
+interpret it.
+
+### 2. Rules can refuse
+
+A useful rule must do more than advise. The Atelier checks schema validity,
+relationship integrity, audience boundaries, readiness protocols, and export
+contracts. Invalid or ambiguous states produce a failing command instead of a
+best-effort publication.
+
+Because the checks are local and versioned with the work, the repository can
+prove its state in CI, on a laptop, or inside a larger toolchain.
+
+### 3. Collaboration becomes governed disclosure
+
+Collaboration is not equivalent to giving every participant every file. The
+Atelier models audience, runtime visibility, roles, and capability envelopes
+as separate concerns. A projection can therefore disclose the material needed
+for a task while withholding material outside that boundary.
 
-const report = validateAtelierExportDryRun(exportDocument)
-console.log(report.accepted, report.importable, report.errors)
+This creates a shared language for human handoffs, agent sessions, reviews,
+and eventual managed delivery. The open package validates the declared
+boundary; it does not silently make access decisions on your behalf.
+
+### 4. The local runtime serves people and agents
+
+`atelier dev` exposes a loopback-only review surface backed by the compiled
+graph. The library exposes the same project, graph, validation, and projection
+primitives to code.
+
+The shipped agent model is intentionally bounded: the Atelier can assemble
+session context, capability envelopes, and proposed changes, but it does not
+apply those proposals or grant direct write access. It is a local context and
+control layer that another interface can build on, not an autonomous editor.
+
+### 5. The repository can power another product
+
+The CLI is one interface. The package is also a library, and its contracts are
+published artifacts. A tool can use the repository as its durable source of
+truth, compile the graph, select an audience-safe projection, and present a
+purpose-built experience without reimplementing the governance model.
+
+That tool may be private, open source, or commercial. Apache-2.0 permits all
+three. Conformance to the public Atelier contracts does not require a MNSTRY
+account or service.
+
+Read [the design document](./docs/design.md) for the five-part architecture and
+[the ontology](./docs/ontology.md) and
+[contract-stability policy](./docs/contract-stability.md) for the stable
+boundaries.
+
+## Build your own tool on it
+
+Use the CLI when a shell command or CI gate is enough. Use the library when the
+Atelier is the substrate beneath a custom interface:
+
+```js
+import {
+  buildGraph,
+  resolveProjectConfig,
+} from '@mnstry/atelier'
+
+const project = resolveProjectConfig({
+  cwd: process.cwd(),
+  argv: ['--project=./atelier.project.json'],
+})
+const graph = buildGraph(project)
+
+if (graph.errors.length > 0) throw new Error(graph.errors.join('\n'))
+console.log(graph.nodes)
 ```
 
-Real projects start from the `private-domain`, `shared-project`, or
-`distribution` templates instead of the sample fixture.
+The package exports change over the alpha series, so pin the exact prerelease
+version and treat the package export map and shipped source modules as the
+executable API reference. [Distribution contracts](./docs/distributions.md) explain
+how a governed subset can be packaged for another surface without widening its
+audience.
+
+## Where the Atelier stops
 
-## Status
+The open package owns repository-side structure and proof. A managed runtime
+may consume a conformant export, but that is a separate system with a separate
+trust boundary.
 
-- 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.
+| The local Atelier does | A managed runtime may do |
+| --- | --- |
+| Parse sources and sidecars | Authenticate participants |
+| Compile and query the graph | Resolve live authorization |
+| Validate contracts and relationships | Persist runtime state |
+| Enforce export audience boundaries | Deliver governed experiences |
+| Generate local review and agent context | Record consent and operational events |
+| Check offline conformance | Decide optional admission |
 
-## Claims you can check
+### Claims you can verify
 
+<!-- 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,132 +274,99 @@ 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 -->
 
-## Your documents and the boundary
+### Conformance and admission
 
-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.
+<!-- atelier:block:conformance-admission:start -->
+The Atelier export format is MNSTRY's format, offered openly.
 
-## Build your own tool on it
+**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.
 
-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. It lives in this
-  repository and deliberately never ships in the npm tarball.
-- `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
-
-`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`:
+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 -->
 
-```bash
-npm install
-npm test     # 510 tests: 509 pass, 1 fail — the denylist check, by design
-```
+## Install and go deeper
 
-To acknowledge the missing file and run the rest, which turns that failure
-into a recorded skip:
+Node.js `>=22.18.0 <23` is required. Pin the prerelease while the package
+remains in alpha:
 
 ```bash
-ATELIER_ALLOW_MISSING_DENYLIST=1 npm test     # 509 pass, 0 fail, 1 skipped
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.4
 ```
 
-## Command reference
-
-```bash
-atelier dry-run ./atelier-export.json
-atelier contract check
-atelier graph --project ./atelier.project.json
-atelier project --project ./atelier.project.json
-atelier readiness --project ./atelier.project.json
-atelier readiness protocols
-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
-atelier boundary check --project ./atelier.project.json
-atelier boundary check --staged --project ./atelier.project.json
-atelier boundary install-hooks --project ./atelier.project.json
-atelier promote --source-repo tenant-private-domain --target-repo project-alpha --kg-id tenant-private-domain:seed
-atelier lock write --project ./atelier.project.json
-atelier lock check --project ./atelier.project.json
-atelier upgrade --dry-run --project ./atelier.project.json
-atelier upgrade --apply --project ./atelier.project.json --branch codex/atelier-upgrade-YYYYMMDD
-atelier extension-pack validate --project ./atelier.project.json
-atelier attestation verify ./attestation.json
-atelier feedback create --message "what happened"
-atelier announcements list
-atelier distribution check --target ./my-distribution
-atelier dev --project ./atelier.project.json
+Then choose the path that matches what you are building:
+
+- [Installation and first run](./docs/install.md)
+- [Design and architecture](./docs/design.md)
+- [Knowledge graph and source model](./docs/knowledge-graph.md)
+- [Local runtime and agent boundary](./docs/atelier-runtime.md)
+- [Distribution contracts](./docs/distributions.md)
+- [Conformance and attestation](./docs/attestation.md)
+- [Continuity commitments](./docs/continuity.md)
+- [Upgrade notes](./docs/upgrade.md)
+
+## Status and command reference
+
+Current package: `@mnstry/atelier@0.2.0-alpha.4`.
+
+The alpha package is usable and contract-tested, but its library API may still
+change before a stable release. Pin the exact version in production toolchains.
+
+```text
+atelier init
+atelier adopt
+atelier setup
+atelier graph
+atelier project
+atelier build
+atelier dev
+atelier generated check
+atelier config check
+atelier extension-pack
+atelier distribution check
+atelier egress check
+atelier boundary
+atelier readiness
+atelier export
+atelier context flow
+atelier support bundle
+atelier feedback
+atelier announcements
+atelier attestation
+atelier promote
+atelier upgrade
+atelier lock
 ```
 
-`upgrade --apply` creates or switches to the requested branch, refuses dirty
-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
-
-Fixtures in this package are fictional and generic. Project-specific adapter
-fixtures belong in their project repositories, not in the published Atelier
-package.
+Run `atelier --help` or `atelier <command> --help` for the current flags. The
+full command behavior is also covered by the package's executable tests.
 
-## License and contributing
+## Contributing and license
 
-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.
+Contributions are welcome through [the contribution guide](./CONTRIBUTING.md).
+MNSTRY Atelier is released under [Apache-2.0](./LICENSE).

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.4
 ```
 
 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.4"
 ```
 
 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.4"
 ```
 
-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,28 @@ 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.4
+
+This is a presentation release. There are 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. The README,
+package metadata, and public documentation now describe the Atelier as a
+repository substrate for people, agents, teams, and tools. Upgrading is a
+dependency bump.
+
+## 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 +94,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.4
+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.4"
+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.4",
   "private": false,
-  "description": "Local-first MNSTRY Atelier workspace for agentic authoring, graph projection, and dry-run runtime readiness.",
+  "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry, service, or 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"
   },

package/skills/claude/atelier-open/SKILL.md

@@ -25,14 +25,15 @@ name (`atelier`) and use the port the harness returns. The equivalent manual
 command is:
 
 ```
-./node_modules/.bin/atelier server
+./node_modules/.bin/atelier dev
 ```
 
-Use the local binary path. Do **not** run `npx atelier` — this package is not
-yet published to npm, and the unscoped name `atelier` belongs to an unrelated
-third-party package that `npx` would download and execute.
+Use the local binary path. Do **not** run unscoped `npx atelier`: the unscoped
+name belongs to an unrelated third-party package that `npx` would download and
+execute. From outside an installed workspace, install `@mnstry/atelier` first
+and use the branded `npx mnstry-atelier` command.
 
-`atelier server` resolves its port as **argv > `PORT` env > 8137**, so a
+`atelier dev` resolves its port as **argv > `PORT` env > 8137**, so a
 supervisor can hand it a free port without a config edit.
 
 ## Do not fight for the canonical port

package/skills/codex/atelier-open/SKILL.md

@@ -25,14 +25,15 @@ name (`atelier`) and use the port the harness returns. The equivalent manual
 command is:
 
 ```
-./node_modules/.bin/atelier server
+./node_modules/.bin/atelier dev
 ```
 
-Use the local binary path. Do **not** run `npx atelier` — this package is not
-yet published to npm, and the unscoped name `atelier` belongs to an unrelated
-third-party package that `npx` would download and execute.
+Use the local binary path. Do **not** run unscoped `npx atelier`: the unscoped
+name belongs to an unrelated third-party package that `npx` would download and
+execute. From outside an installed workspace, install `@mnstry/atelier` first
+and use the branded `npx mnstry-atelier` command.
 
-`atelier server` resolves its port as **argv > `PORT` env > 8137**, so a
+`atelier dev` resolves its port as **argv > `PORT` env > 8137**, so a
 supervisor can hand it a free port without a config edit.
 
 ## Do not fight for the canonical port