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

package/docs/assurance-controls.md

@@ -0,0 +1,49 @@
+# Assurance controls and evidence map
+
+This ledger maps public trust claims to the control that enforces them, the
+test that challenges the control, and the limit that remains. It describes the
+source tree; a release decision must additionally record the exact candidate
+commit and packed-tarball digest.
+
+| Claim | Enforcing control | Defensive evidence | Stated limit |
+| --- | --- | --- | --- |
+| Boundary rules cannot silently switch themselves off | `src/boundary/policy.mjs`, `src/boundary/content-rules.mjs`, and generated Git hooks | `boundary:test`; boundary case in `assurance:mutation-smoke` | Repository access remains the source read boundary; an audience label is not encryption |
+| A clean boundary verdict uses complete evidence | Typed Git reads with diff and binary budgets; incomplete reads become blocking diagnostics; Sync requires the enrolled root to be scanned, uses its digest-bound Git for actor and staged evidence, and disables network actor fallback | `test/boundary-content-rules.test.mjs`; Sync boundary-scope, pinned-Git, and no-network actor refusal cases | Budgets intentionally refuse evidence too large to inspect rather than claiming it is clean |
+| Graph classification has one meaning | `src/graph/knowledge-graph.mjs` is canonical; `src/graph/graph.mjs` adapts its result | `graph:test`; graph case in `assurance:mutation-smoke` | Unclassified Markdown is retained as private diagnostic material, not admitted as governed content |
+| The package has no undisclosed runtime egress path | Canonical forbidden-egress scanner plus exact packed-file inventory in `release:audit`; Atelier Sync confines network Git to bounded fetch and an exact-plan, non-force push | egress tests, marker-inventory test, runtime fetch/push refusal tests, and egress case in `assurance:mutation-smoke` | Data-only files are not interpreted; reviewed `gh` actor resolution and explicitly enrolled Git fetch/push are documented subprocess exceptions. Optional host-bound vault SDK and transport I/O is outside the lexical scanner model; trusted provider configuration, denial probes and hosted qualification are separate controls. |
+| User-confirmed repository writes match what was reviewed | Content-bound, expiring plan identifiers; fresh complete observations; exact staged and written-tree blob/mode manifests; post-hook tree, single-parent, and message verification with compare-and-swap rollback; refusal of prior unpublished commits; and an exact verified-object push after HEAD/target revalidation with tag following and recursive submodule publication disabled | `sync:test` plan, expiry, hook/index, late-HEAD, ahead-branch, remote-ref, remote-drift, and evidence-failure cases | Ordinary Git hooks may run, but a hook cannot substitute a different commit object for publication |
+| Resident Sync state cannot escape or grow without bound | Contained private directories, no-follow/identity-checked leaves, a 4,096-entry observation ceiling, bounded state projection, nonce-bound locks with aged abandoned-claim recovery, lock-directory identity validation and an ambiguous live-PID maximum age, consumed plans under age/file/byte ceilings, and corruption-recovering hash-chained traces with per-event/resident ceilings | `sync:test` observation/state ceilings, redirected-state/lock, plan lifecycle, concurrent enrollment/recovery, corruption, and trace ceilings | Machine-local state is diagnostic convenience; Git and readable repository files remain authoritative |
+| Local review serves only generated publication output | Loopback-only bind, required `atelier.manifest.json`, realpath containment, enrolled safe types, POSIX no-follow plus cross-platform leaf type/identity validation for local state, and host/fetch-site/origin/method/nonce checks | `server:security:test`; sidecar case in `assurance:mutation-smoke` | The sidecar is a local review tool, not user authentication or runtime authorization |
+| Collaboration cannot become a hidden apply path | Proposal authority is capability-derived; records are typed; POSIX ledger and snapshot leaves are no-follow, while every platform rejects redirected leaves and validates opened file identity when available; ledger reads are bounded, one-pass for lists, and corrupt tails fail closed | `collaboration:test` and ledger ceiling/performance tests | Collaboration remains copy-only proposal metadata; snapshots are rebuildable projections and Git review owns source changes |
+| The Obsidian maintenance service is reachable from this machine only, and only by its owner | Bind and client are restricted to the literal `127.0.0.1` or `::1`; `Host` must be the exact bound authority; cross-site `Origin` and `Sec-Fetch-Site` are refused; four fixed operations with exact paths and methods; status, tick and stop need a per-runtime random bearer kept only in the mode-0600 record; payloads are bounded and name their runtime; health carries no path or title | `test/obsidian-maintenance.test.mjs` listener, disclosure and unauthorised-request cases, each with a deliberately broken listener that must fail | A local process running as the same user can read the record; the bearer is ownership proof between local processes, not user authentication |
+| A maintenance service is stopped or reported as running only when it is proven to be this workspace's own | Record and health must agree on service name, workspace, runtime identifier, PID, executable digest and loopback address; anything else on the port is `occupied`; a reused PID is never signalled; a malformed or foreign record refuses; `start` stops only the child it created, by handle | Unowned and silent listener, wrong-identity, PID-reuse, stale-record, malformed-record, idempotent and concurrent start, and launcher-survival cases, with mutation controls | Status probes have a deadline: a service busy in a long synchronous tick can be reported `occupied` until it answers |
+| Maintenance never sweeps recovery or staging, and one workspace has one ticking engine | The service deletes only its generated record; the engine and the publisher own every other write; a hard kill is settled by the publisher's journaled restart recovery; each tick holds a private per-workspace lock taken from a holder only with proof of abandonment | Directory-listing oracles across start, ticks, stop, hard kill and stale record; hard kill between exchange and manifest commit; lock exclusion and takeover cases; each with a mutation control | A live lock holder that recorded no health address needs a person; a tick that outlasts the shutdown grace period ends with the process and is settled on the next start |
+| Source application policy is re-read before every automatic apply | The engine authorizes from disk immediately before each dispatch; manual mode never reaches the apply operation; the service keeps this on every tick; the apply operation reads the installed policy again at its decision and immediately before the write, recomputes its digest and evaluates its selector over the current canonical graph; `policy install` verifies that digest and names the expected one; whether this machine may see the object is asked before anything else, so an absent and a withheld object get one answer | Revocation, manual-mode and apply-unavailable cases in `test/obsidian-maintenance.test.mjs`; policy, refusal-table and late-revocation cases in `test/obsidian-edits.test.mjs`, each with a deliberately broken rule that must fail | A policy is private configuration of one machine; whoever can write that private state can install one |
+| Applying an edit to a source file cannot lose another program's bytes | One operation for a person and for a policy: exact identity, path and digest checks at commit; the write is an atomic exchange, never a check followed by a rename; displaced bytes that are not the base are exchanged back and retained; the old source stays as a backup that is looked at again for late writers; write-ahead record and intent before the exchange; restart recovery decides from digests only, and so does an exchange that reports a failure; generated regions never reach a source: the tail is intact, or removed with the end of the authored text proven, and anything else refuses; every git directory is refused, nested, respelled or relocated; the hold on an edited note lifts only on a read of the note at that moment; no git command that writes | `test/obsidian-edits.test.mjs`: end to end through the real engine, a refusal table with a whole-project byte and `git status` oracle, a real second process writing in three styles and four timings with both outcomes asserted, a crash at every durable step, a disclosure walk, a generated tail cut at every byte offset from both sides and a fuzz over the whole note; every oracle has a mutation control | macOS arm64 on APFS only; refuses where no atomic exchange exists; the source becomes a new file (permission bits kept, hard links refused); a late writer's bytes are retained and surfaced, never merged; a hard link made after the path check is not detected; a fragment of generated text shorter than eight bytes left inside an edited body cannot be told from typing |
+| A structural edit made in a vault becomes one copy-only proposal and never a source change | The proposal adapter routes by whole identity to the existing store of the enrolled repository or refuses typed and writes nothing; it records the operation in private immutable state first, looks in the persisted store for its operation identity before creating, under a private per-repository lock taken over only with proof; it preflights the ledger limits, defers `ledger-full`, refuses `proposal-too-large` and `ledger-corrupt`, bounds batches and retries, and never compacts; a proposal holds codes, offsets and digests and no note text; acceptance is shown and never acted on | `test/obsidian-proposals.test.mjs`: routing table with a whole-project byte and `git status` oracle, identity survival against the real store, a crash at every step, two real processes, generated ledgers at 256 KiB, 16 MiB and 10,000 events and an invalid line, a no-busy-loop count of store reads, a disclosure walk; engine cases in `test/obsidian-maintenance.test.mjs`; every oracle has a mutation control | In manual mode an operation exists only after apply has looked at the edit; a refused or exhausted operation waits for a person; the store directory lives in the repository and must be git-ignored; two workspaces that enrol one repository create one proposal each |
+| Opening a view reports `current` only for the exact, verified, present generation and a qualified app | `open` needs a tick of the proven service after the request, a persisted `current`, an independent read-back of the trusted pointer and every note, and an app at or above the minimum version that answers for that vault; every other outcome is typed, distinct and exits non-zero; the app and the operating system are reached only through injected seams, and the production ones only behind `--adapter=obsidian-cli` | `test/obsidian-open.test.mjs`: outcome table, read-back, app-floor, busy and read-only cases, each with a deliberately broken rule that must fail; a spawn guard and a production-seam import check | The production probe and launcher are not exercised against a real app here; `indexing` relies on an undocumented readiness field until acceptance qualifies it |
+| Operating-system startup is never installed implicitly | `buildStartupAdapter` is pure text generation; Windows refuses typed; the service refuses `--startup` without a consent that covers startup | Builder purity oracle (no filesystem, process or home-directory access; no machine path beyond its inputs) and startup-consent refusal | Generated units have not been qualified against real launchd or systemd hosts |
+| Expected operator failures are actionable without leaking internals | Typed project/JSON diagnostics and the CLI execution wrapper | `test/cli-brand.test.mjs` | Unexpected stacks require the operator to opt in with `ATELIER_DEBUG=1` |
+| Published APIs do not disappear silently | Tag-derived subpath and named-export baseline plus version/tag identity refusal | `public-api:compat`; `test/public-api-compat.test.mjs` | Additive API checks do not decide whether a new version number is appropriate |
+| The published artifact is the artifact tested | `release:candidate` packs once, binds SHA-256, sends that exact archive through allowlist/content audit, bare-consumer install, all-export import, and branded distribution smoke, then the trusted-publishing workflow retains and publishes that same tarball path | `release:audit`, `consumer:smoke`, `distribution:smoke`, `assurance:mutation-smoke`, `publish-workflow.test.mjs` | Passing gates does not publish, deploy, or constitute an external reviewer’s approval |
+
+The release-blocking command is `npm run prepublishOnly`. It includes positive
+regression suites and deliberately broken local fixtures. The latter prove
+that boundary, graph, egress, sidecar, and distribution controls still refuse
+their named failure modes; they do not exercise a live abuse path.
+
+## Exact-candidate evidence
+
+At candidate cut, retain all of the following together:
+
+1. the Git commit SHA and a clean working-tree check;
+2. the `npm pack --json` inventory and tarball SHA-256;
+3. outputs from syntax, contracts, public-API compatibility, migrations, repository disclosure,
+   release audit, full tests, mutation smoke, bare consumer, and distribution
+   smoke;
+4. a defensive review tied to that same commit and digest; and
+5. explicit human decisions for versioning, publication, deployment, or any
+   external communication.
+
+Evidence for a different commit or a dirty tree is not evidence for the
+candidate.

package/docs/atelier-runtime.md

@@ -14,6 +14,8 @@ The package owns reusable mechanics:
 - proposal-only collaboration metadata;
 - support-bundle dry runs with no send path;
 - export dry-run validation for `atelier-export@v1`.
+- explicit single-repository enrollment and full-state Git observation;
+- fast-forward-only reconciliation and two-phase user-confirmed commits.
 
 Project adapters own project facts: repo roster, source roots, read-boundary
 config, extension packs, brand language, and generated project outputs.
@@ -28,7 +30,31 @@ runtime authority.
 
 ## Safety Posture
 
-The default package posture is no telemetry, no external network egress, no
-runtime mutation, no browser apply endpoint, and no model-assisted analysis execution.
+The default package posture is no telemetry, no MNSTRY runtime mutation, no
+browser apply endpoint, and no model-assisted analysis execution. Conformance
+is offline. The only documented subprocess network paths are the bounded `gh`
+actor-resolution fallback and explicitly enrolled Atelier Sync Git fetch and
+user-confirmed non-force push operations.
 Provider analysis output may only enter as proposed `atelier-claim@v1` records
 until explicitly reviewed by the project owner.
+
+`atelier dev` is narrower than a general static server. It refuses non-loopback
+bind hosts, requires a generated `atelier.manifest.json`, and publishes only
+manifest-enrolled HTML, script, style, and image files that remain inside the
+workspace after realpath resolution. Hidden paths, local state, secret-shaped
+names, symlinks, unknown file types, and unenrolled files are unavailable.
+Reads validate the loopback host and fetch metadata; mutations additionally
+require an allowed method, exact same origin, and the session nonce.
+
+Collaboration endpoints are copy-only: they create or review proposal records;
+they do not apply source changes. Authority is derived from declared
+capabilities and apply endpoints, never inferred from action-like prose. A
+partially corrupt ledger returns typed incomplete evidence and blocks a clean
+claim. Ledger reads and records are bounded, appends are locked, and retention
+changes happen only through explicit compaction.
+
+The local Git supervisor is a separate mechanical authority surface. It may
+create a repository commit only from an unchanged, bounded plan after the user
+repeats its exact operation id. That repository write is not a MNSTRY runtime
+mutation and does not grant proposal apply authority to the browser sidecar.
+See [Atelier Sync: Deliverable Zero](./atelier-sync.md).

package/docs/atelier-sync.md

@@ -0,0 +1,172 @@
+# Atelier Sync: Deliverable Zero
+
+Atelier Sync is the collaborator-facing name for the resident repository
+supervisor. Deliverable Zero is deliberately headless: it proves the Git,
+filesystem, state-machine, recovery, and user-authority boundaries before a
+tray shell or installer is allowed to make the product feel finished.
+
+This is repository mechanics, not MNSTRY runtime authority. A Git commit
+changes the enrolled repository. It does not mutate MNSTRY identity, consent,
+visibility, provisioning, commerce, sessions, audit, or any other managed
+runtime object.
+
+## Authority contract
+
+- Enrollment names exactly one repository. Atelier never scans a home folder.
+- One resolved absolute system Git executable, version, and executable digest
+  owns Git semantics for the enrollment. Every inherited `GIT_*` variable is
+  stripped from supervised Git calls before Atelier adds its small fixed
+  safety environment. Custom SSH transport belongs in the user's SSH config;
+  credentials continue through ordinary Git credential helpers. Git `2.40.0`
+  or newer is required so global and system attribute provenance is observable.
+- Every cycle observes the full repository. There is no watcher correctness
+  dependency in Deliverable Zero.
+- Fetch and fast-forward-only reconciliation are mechanical operations.
+- Commit creation is a two-phase, user-confirmed operation. Planning records
+  the head, branch, complete status digest, exact file paths, commit message,
+  reviewed blob/mode manifest, diff summary, and exact optional upstream push
+  identity. The push identity digest covers the single resolved, normalized,
+  credential-free execution destination; persisted display evidence likewise
+  strips authentication material, query strings, and fragments. Multiple push
+  URLs and `url.*.insteadOf`/`pushInsteadOf` rewrites are refused as ambiguous.
+  Every authoritative field is bound into the operation id.
+  Execution requires that exact id and refuses if the plan, repository,
+  staged bytes/modes, written tree, commit parent/message, or publish target
+  changed. A publish plan is refused while any earlier local commit remains
+  unpublished, and publication names the exact verified commit object rather
+  than a movable `HEAD` ref. Plans expire after 24 hours, are consumed by a
+  definitive execution attempt, and are held under resident file/count
+  ceilings. Expired, malformed, or oversized retained plan files are removed
+  under the repository lock before those ceilings are enforced; redirected
+  plan state remains a hard refusal.
+- A commit plan cannot absorb pre-existing staged work. It stages only literal,
+  explicitly reviewed paths.
+- Configured Atelier boundary policy is checked against the staged change set
+  before commit creation using the enrolled Git executable. When the enrolled project
+  operates a private-domain repository with a declared owner, actor verification is blocking even in
+  legacy-warning mode. The Sync path disables the boundary command's optional
+  network `gh api user` fallback and fails closed when local actor evidence is
+  insufficient. Commit history is provenance, not current-user identity, and
+  is not accepted as actor evidence on this path. Shared-only checks skip derived actor lookup, including ambient platform
+  identities. Invalid explicit selectors are still refused. Ownership is scoped
+  to configured repository names; it does not authenticate repository identity. Ordinary Git hooks still run; the resulting commit tree,
+  single parent, and message must equal the reviewed authority or the local
+  commit is rolled back and publication is refused.
+- Push is present only when the reviewed plan requested it, the branch had no
+  prior unpublished commits, and HEAD still names the exact verified commit.
+  Atelier re-resolves the single push URL immediately before publication and
+  pushes the exact commit object directly to that reviewed destination. Push is
+  never forced, never follows tags, and never recursively publishes submodule
+  refs. When fetch and push resolve to the same credential-free identity,
+  Atelier refreshes the exact remote-tracking branch and re-observes before it
+  reports `committed-and-published`. A distinct configured push URL is honored,
+  but remains an explicit attention state because it cannot prove the fetch
+  upstream synchronized. A failed push or post-push tracking refresh preserves
+  the local commit, creates one stable attention state, and returns a non-zero
+  command exit.
+- Semantic conflict resolution, merge commits, rebase, reset, force push,
+  browser apply, broad path scans, telemetry, and hidden upload are absent.
+
+## Repository completeness
+
+`atelier sync status` emits a supervisor envelope whose `state.observation`
+contains the current `atelier-repository-observation@v1` document. That
+observation cannot report `complete: true` when any of these are unresolved:
+
+- lexically identifiable provider-managed, UNC/network, WSL-cross-boundary, or
+  unclassified external filesystem roots (mapped-drive classification remains
+  an operating-system integration concern for the signed beta);
+- an unsupported Git engine or bare repository;
+- sparse checkout, partial clone, or shallow repository state;
+- tracked paths carrying `assume-unchanged` or `skip-worktree` index flags;
+- missing or unhealthy submodules;
+- required Git LFS content without a working LFS integration, including LFS
+  semantics declared by tracked or untracked worktree attributes, repository
+  info attributes, and default global or system attributes;
+- an unclassified custom clean, smudge, or process filter;
+- a configured `core.hooksPath` whose executable behavior is outside the
+  reviewed repository contract;
+- a remote URL whose authentication shape cannot be classified;
+- multiple push destinations or any configured Git URL rewrite rule;
+- any required Git evidence read that fails, times out, exceeds its budget, or
+  cannot be parsed.
+- a change set above the 4,096-entry resident observation ceiling; or
+- a `core.attributesFile` outside the repository-owned/tracked attributes
+  boundary whose filter semantics have not been classified.
+
+HTTPS through Git Credential Manager, SSH through the user's existing SSH
+configuration, and local test remotes are classified explicitly. Atelier does
+not collect or store provider credentials.
+
+## Local operation state
+
+Ignored `.atelier-local/runtime/` contains:
+
+- `enrollment.json` — exact repository and Git engine;
+- `state.json` — a bounded projection of healthy, attention, or paused state;
+- `control.json` — user pause/freeze state;
+- `plans/` — expiring, consumed reviewed commit plans under count/byte ceilings;
+- `operations.ndjson` — sequence- and hash-chained resident trace with explicit
+  hash-bound checkpoints before its byte or record ceiling, with a fresh
+  digest-linked generation after a torn or corrupt chain; and
+- an atomic per-repository operation lock.
+
+Every directory component is containment-checked and every state leaf is
+opened without following redirects where the platform supports it, with leaf
+type and identity checks on every platform. Stale-lock recovery uses an
+exclusive recovery claim, ages out an abandoned recovery claim after the owner
+grace interval, identity-checks the lock directory before and after quarantine,
+and quarantines only the claimed stale directory; it never recursively deletes
+a newly acquired lock. A live PID without durable process identity cannot wedge
+the repository forever: its owner record becomes recoverable after the 24-hour
+maximum operation age. Enrollment takes the same lock as every other
+authoritative state mutation.
+
+Deleting this directory removes convenience and diagnostics. It cannot change
+repository meaning. Git plus readable files remain authoritative.
+
+## Engineering commands
+
+```bash
+atelier sync enroll --repo /absolute/path/to/repository
+atelier sync status --repo /absolute/path/to/repository
+atelier sync reconcile --repo /absolute/path/to/repository
+atelier sync run --repo /absolute/path/to/repository --once
+
+atelier sync plan \
+  --repo /absolute/path/to/repository \
+  --path docs/decision.md \
+  --message "docs: record decision" \
+  --publish
+
+# Repeat the exact operation id printed by plan:
+atelier sync commit \
+  --repo /absolute/path/to/repository \
+  --operation operation-... \
+  --confirm operation-...
+```
+
+`status`, `audit`, `reconcile`, `run --once`, and `commit` return a non-zero
+process exit when their result is not healthy, so automation cannot treat a
+paused state, attention state, or failed publication as success merely because
+JSON was emitted.
+
+The future native shell may label the final two commands **Commit & sync**.
+It must not bypass either phase.
+
+The repeated operation id is a visible user-intent confirmation gate, not an
+authorization secret. Local software able to read and modify the repository is
+inside the same operating-system trust domain; the control prevents implicit
+or stale execution, not a hostile process with the user's filesystem access.
+
+## Evidence boundary
+
+Deliverable Zero proves the headless supervisor contract on Linux and macOS,
+with Windows CI covering the portable observation, state, and direct-process
+contract. POSIX executable-wrapper substitution is explicitly skipped on
+Windows; native Windows wrapper-injection proof, signed installation,
+background launch at user login, Windows Home/Pro device behavior, macOS
+notarization, and a nontechnical-user workflow belong to the signed
+collaborator beta. Repositories without an initial commit are not supported by
+this deliverable. A Git executable upgrade changes enrolled identity and
+requires re-enrollment.

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,61 @@
+This package makes three promises. None of them asks for your trust — each
+one names the command that proves it.
+
+**There is no silent egress; every network path is named.** There is no
+telemetry, update check, crash reporting, or model provider path in the package.
+The optional vault API adds explicit host-bound artifact uploads and reads; it
+is never activated by local authoring commands. Its injected storage, database
+and identity SDKs may use the network and require separate hosted qualification. The exceptions are explicit: `boundary check` and
+`upgrade` (including `--dry-run` and `--apply`) may invoke `gh api user` only when
+an operated private-domain repository needs owner attribution, no explicit selector or `GITHUB_ACTOR` was supplied, and no
+configured Git email maps to an actor. Shared-only boundary checks skip derived
+identity lookup. Invalid explicit selectors are refused without fallback;
+platform logins must uniquely match declared login mappings. Repository identity
+checks may invoke `gh api repos/...` to resolve a canonical GitHub identity.
+Those authenticated requests use your own `gh` credentials. Recorded repository
+identities let identity checks keep working when the provider is unavailable.
+See `docs/install.md` for the full attribution precedence and mode semantics.
+Explicitly enrolled Atelier Sync may also run bounded Git fetches
+for observation/reconciliation and one non-force push only when the exact
+reviewed commit plan requested and confirmed it, no earlier local commit is
+waiting to be published, and HEAD still names the verified commit object. Sync
+never uses the network actor fallback, follows tags, or recursively publishes
+submodule refs. The local authoring HTTP client
+refuses non-loopback URLs, the served pages authorize no external origin, and
+release audit scans every executable or markup file in the exact `npm pack`
+inventory for egress primitives. The standalone gate also scans executable and
+markup files under `src/`, `bin/`, `scripts/`, `templates/`, `examples/`, and
+`skills/`. Two limits worth stating plainly: the egress control does not
+interpret data-only `.json` or `.md` files, and it does not model
+`child_process`; the reviewed `gh` and enrolled Git paths above are documented
+subprocess exceptions rather than scanner detections:
+
+```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,18 @@
+- It does not write to a MNSTRY runtime database.
+- It does not import, provision, publish, or send project content to a MNSTRY
+  managed runtime.
+- Conformance remains offline. Local CLI network access is limited to the documented
+  `gh` actor-resolution fallback and explicitly enrolled Atelier Sync Git
+  operations: bounded fetch for observation/reconciliation, and non-force push
+  only when the exact reviewed commit plan requested and confirmed it, no
+  earlier local commit remains unpublished, and HEAD still names the verified
+  commit object; Sync does not use network actor fallback, follow tags, or
+  recursively publish submodule refs.
+- Optional vault adapters use explicitly injected host SDKs and transports. The
+  host owns their network access, authentication and infrastructure; importing
+  the kit does not create a service or make a network request.
+- 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/coauthor-session.md

@@ -0,0 +1,57 @@
+# Experimental portable coauthor session
+
+Tracked by issue #33. The experimental reducer is exported at
+`@mnstry/atelier/coauthor`; the private draft adapter at `@mnstry/atelier/coauthor/store`.
+The `atelier coauthor start|read|event|recover` CLI consumes one JSON request on
+stdin. Run it from the intended Git workspace; `.atelier-local/` must be ignored
+and untracked. The shipped `atelier-guided-coauthor` skill guides harness use.
+This local candidate has not been published or accepted by a real author.
+
+The harness supplies a session id and an ordered list of consumer-owned field
+ids, each bound to an immutable source reference and SHA-256 digest. The pure
+reducer accepts revision-bound events and returns a new state plus effects.
+It does not access files, render a browser, contact a model or authorize writes.
+
+An answer remains in history. Every proposed wording change requires explicit
+confirmation before saving. Answer-and-continue intent survives confirmation;
+advance occurs only after a matching receipt. Pause retains the current phase.
+Rejection restores the original answer. Undo of an already saved value is not
+implemented: consumers must not advertise it or delete history to simulate it.
+
+## Adapter obligations
+
+- Keep reducer state inside the trusted adapter; untrusted callers submit
+  intents, never snapshots or save receipts. Rehydrate from validated events
+  with `replaySession`, using the original immutable configuration.
+- Authenticate and authorize actors outside this module. Session identifiers
+  and matching digests are correlation data, not proof of identity or authority.
+- Persist accepted events through the existing consumer ledger. This module's
+  in-memory history is a replay projection, not a second durable database.
+- Before executing `write-field`, verify source identity and containment and
+  apply the consumer's compare-and-swap write policy. Key execution by session
+  id plus request id. Retry uses the same key; duplicate delivery must not
+  perform another write. Reconcile a pending write after a restart rather than
+  blindly replaying historical effects.
+- Emit a receipt only after durable persistence and readback of the exact
+  target field's UTF-8 value. The receipt binds session, request, field, source
+  reference, source digest and value digest. A digest match alone does not
+  establish that these adapter duties occurred.
+- A failure remains visible. One explicit retry is allowed; subsequent failures
+  require adapter reconciliation. A valid late receipt can resolve recovery.
+- Persist the accepted receipt event before showing saved state. This module
+  grants no canonical publication, release, remote execution or guide access.
+
+The supplied store reuses the collaboration ledger implementation, in a separate
+coauthor stream that is never mixed into legacy proposal aggregates. It verifies
+contiguous versions and previous-event identity; compaction that drops history
+is refused. It writes immutable private draft values, then replays a readback-bound
+receipt before showing saved state. It never edits selected source files.
+Workspace-local Git checks are the only subprocess use; no network is added.
+Operation locks serialize this adapter's writers. A leftover lock requires
+operator inspection, never automatic removal of an unknown writer's lock.
+
+`start` takes `{config: {id, fields}}`; `read` and `recover` take `{sessionId}`;
+`event` takes `{sessionId, event}`. A receipt or failure event submitted through
+the CLI is refused. Source changes block new writes, not reading old history.
+Configuration and saved drafts have the additive `atelier-coauthor.v1` schema;
+source path containment and duplicate fields are checked by the adapter as well.

package/docs/connected-composition.md

@@ -0,0 +1,75 @@
+# Connected composition: synthetic foundation
+
+Status: experimental, opt-in source prototype. Not an accepted public API,
+production auth integration, published release, or certification of a private
+host. Existing package exports and contracts remain unchanged.
+
+## Bounded implementation
+
+Owned additions: `src/composition/`, `src/access/`, `src/preview/`,
+`examples/connected-composition/`, `test/connected-composition*.test.mjs`, and
+`scripts/prove-connected-composition.mjs`. This document records the reservation.
+No existing sidecar, vault, coauthor, presentation, keyboard or business module
+is changed. The prototype starts from the frozen presentation supplier and is a
+separate candidate; its local proof cannot satisfy that supplier's CI gate.
+
+The public root supplies placement validation, an opt-in trusted-host enforcement
+helper and a two-origin preview channel. A private host supplies identity,
+membership, delegation, policy, registry/source resolution, services, result
+filtering and audit storage. Auth adapters can differ without changing placements.
+White-label and self-provisioned hosts remain possible; no hosting infrastructure
+or tenant provisioning is implemented here.
+
+The example uses two invented auth adapters and an in-memory collection service.
+It is intentionally not an auth provider. Only preview-plane synthetic reads and
+an explicitly enabled reversible sandbox action are supported. No production
+plane, live network transport, credential, payment or irreversible action exists.
+
+## Implementation sequence and acceptance
+
+1. Closed, byte/depth/count-bounded JSON parsing, placement and action schemas;
+   exact source-byte and immutable definition/renderer digests.
+2. Trusted channel authentication, complete decision binding, agent attenuation,
+   fail-closed revalidation before service and before output; bounded projection.
+3. Independent fake service authorization, expected-version/idempotency behavior,
+   with accurate uncertainty rather than invented rollback after an effect.
+4. Exact-origin/source/nonce MessageChannel handshake and generation/source/sequence
+   guards; old mounts and pending responses cleared on change or logout.
+5. An Astro page retaining useful static content without JavaScript or an account;
+   isolated dynamic preview, ordinary native controls, narrow responsive layout.
+6. Focused control tests, three desktop browser engines, source-edit/build/refresh,
+   fake adapter switch/logout, scoped agent refusal and no secret projection.
+
+The browser receives proposals and filtered results, never a trusted session,
+decision or service port. This separation protects against an untrusted preview,
+not a malicious host constructor. A real service must independently authorize
+and atomically own effect/version/idempotency receipts. Types and callback names
+are not security boundaries. A compromised private service or dishonest projector
+is outside this root helper's assurance.
+
+No general source writer is added. The browser does not get filesystem tools.
+The proof harness edits only its disposable authored fixture and rebuilds it.
+Existing coauthor draft persistence and canonical source promotion stay owned by
+their existing workflows. There is no duplicate placement database.
+
+## Proposal alignment
+
+The wire retains the `proposal-v1` discriminators from the reviewed placement
+proposal, with an executable closed action validator added. The implementation
+is `connected-composition/experimental-v1`, not a proposal acceptance event.
+An action's full request digest is additionally bound to authorization, so an
+identifier cannot silently stand for a changed payload. The projector returns
+only filtered data; the root constructs all public state metadata itself.
+Audit intake uses `pending` and output settlement uses `prepared`, not
+`delivered`: returning a prepared result is not a browser delivery acknowledgement.
+Preview lifecycle generations are mount-local and never serialize host session
+generation or identity. Real hosts must map invalidation into channel disposal.
+The first resolver intentionally admits exactly one data binding and a web
+projection. Multi-resource composition, other host projections and a published
+package export require their own accepted contracts; parsing their proposed
+shape alone is not runtime admission.
+
+Missing completion gates: owner validation of real host adapters and source
+promotion integration, service-specific transaction/reconciliation proof,
+assistive-technology and actual native/device tests, private adopter acceptance,
+maintainer integration and recognized CI. None is implied by this prototype.

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