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

package/contracts/public-api-baseline.json

@@ -0,0 +1,57 @@
+{
+  "schema": "mnstry.atelier-public-api-baseline@v1",
+  "baselineTag": "v0.2.0-alpha.4",
+  "baselineCommit": "6fed5b9e1077b361e26b2b581ea67a55e7634963",
+  "baselineVersion": "0.2.0-alpha.4",
+  "publishedRegistryArtifact": {
+    "package": "@mnstry/atelier",
+    "version": "0.2.0-alpha.4",
+    "shasum": "9f67f5b7fabc748ec235bbe85587a71b5ad639c8",
+    "integrity": "sha512-mt2vWnFZtBAc8C+bzjcgrIPYRGgVOhFHm4SPDrnXvWgcdDY/G2aUY5KP6YPmjkRCMvewGMsH7Wg+8i63f1/onQ==",
+    "sha256": "a032971977d9fbd3b7adc94f204739d4202b1754d72a77cbc79f4c473850e531",
+    "entryCount": 265,
+    "verifiedAt": "2026-08-25"
+  },
+  "requiredSubpaths": [
+    ".",
+    "./cli",
+    "./project",
+    "./graph",
+    "./projection",
+    "./readiness",
+    "./readiness-protocols",
+    "./server",
+    "./harness",
+    "./support",
+    "./egress",
+    "./boundary",
+    "./upgrade",
+    "./attestation",
+    "./extension-packs",
+    "./analysis/adapter",
+    "./export-contract",
+    "./dry-run",
+    "./contracts/atelier-export.v1.schema.json",
+    "./fixtures/atelier-export/sample-studio-offer.v1.json"
+  ],
+  "requiredModuleExports": {
+    ".": ["ALLOWED_RUNTIME_TARGETS", "ATELIER_LOCK_SCHEMA", "ATELIER_MIGRATION_SCHEMA", "ATELIER_READINESS_SCHEMA", "BASE_MIGRATIONS", "BOUNDARY_POLICY_SCHEMA", "LOCAL_AUDIENCES", "MNSTRY_READINESS_PACK_SCHEMA", "OBJECT_CLASSES", "PROJECT_CONFIG_SCHEMA", "READINESS_PROTOCOL_IDS", "READINESS_PROTOCOL_SLUGS", "RUNTIME_OWNERS", "RUNTIME_VISIBILITIES", "analysisAdapterDryRun", "applyUpgrade", "buildAtelierLock", "buildGraph", "buildProjectProjection", "buildReadiness", "buildSupportBundlePreview", "bundledMnstryReadinessPackV1", "bundledReadinessPack", "bundledReadinessProtocols", "checkAtelierLock", "checkBoundaryPolicy", "checkForbiddenEgress", "contextEnvelope", "createAtelierSidecarServer", "createPromoteEvent", "getBundledReadinessProtocol", "installBoundaryHooks", "loadAtelierLock", "loadBoundaryPolicy", "planUpgrade", "protocolById", "resolveProjectConfig", "validateAtelierExportContract", "validateAtelierExportDryRun", "validateAtelierExportDryRunFile", "validateBoundaryPolicy", "validateJsonSchema", "validateMigrationRecord", "validateProjectConfigDoc", "validateSchemaShape", "validateSupportBundlePayload", "writeAtelierLock"],
+    "./cli": ["DEFAULT_BRAND", "buildCommandHelpText", "buildHelpText", "buildVersionText", "commandMap", "runCli"],
+    "./project": ["EXTERNAL_REPO_KIND", "LOCAL_OVERLAY_ENV", "LOCAL_OVERLAY_FILES", "LOCAL_OVERLAY_SCHEMA", "LOCAL_STATE_DIR", "PROJECT_CONFIG_ARG_PREFIX", "PROJECT_CONFIG_ENV", "PROJECT_CONFIG_SCHEMA", "SUPPORTED_IDENTITY_PROVIDERS", "asObject", "commandProject", "ensureLocalState", "firstString", "gitRemoteUrl", "isExternalRepo", "loadRepoAccess", "localOverlayCandidatePaths", "localStateRoot", "parseArgs", "parseRepoPathOverrides", "projectConfigArg", "readJson", "readLocalOverlay", "readProjectConfig", "remoteHost", "resolvePathValue", "resolveProjectConfig", "stripProjectConfigArgs", "validateProjectConfigDoc", "writeJson"],
+    "./graph": ["VALID_AUDIENCES", "VALID_RELATIONS", "buildGraph", "ignoredSidecarWarnings", "parseFrontmatterYaml", "runGraphCommand"],
+    "./projection": ["buildProjectProjection", "runProjectCommand"],
+    "./readiness": ["ATELIER_READINESS_SCHEMA", "buildReadiness", "runReadinessCommand", "stableReadinessForCheck", "summarizeGraph", "summarizeProjection"],
+    "./readiness-protocols": ["MNSTRY_READINESS_PACK_SCHEMA", "READINESS_PROTOCOL_IDS", "READINESS_PROTOCOL_SCHEMA", "READINESS_PROTOCOL_SLUGS", "READINESS_RUN_SCHEMA", "bundledMnstryReadinessPackV1", "bundledReadinessPack", "bundledReadinessProtocols", "getBundledReadinessProtocol", "protocolById"],
+    "./server": ["ATELIER_CAPABILITIES_SCHEMA", "ATELIER_CONTEXT_SCHEMA", "ATELIER_DOCTOR_SCHEMA", "ATELIER_PRESENCE_SCHEMA", "ATELIER_RESOLVE_SCHEMA", "ATELIER_SESSION_AUTH_SCHEMA", "createAtelierSidecarServer"],
+    "./harness": ["contextEnvelope", "runContextCommand"],
+    "./support": ["BANNED_KEY_PATTERNS", "BANNED_VALUE_PATTERNS", "DEFAULT_SUPPORT_FIELDS", "SUPPORT_BUNDLE_PREVIEW_SCHEMA", "buildSupportBundlePreview", "parseSupportBundleArgs", "readSupportBundleJson", "runSupportCommand", "supportBundlePreview", "validateSupportBundlePayload", "writeOrPrintSupportBundle"],
+    "./egress": ["DEFAULT_EGRESS_SCAN_PATHS", "LOCAL_COMPUTED_ALLOW_MARKER", "TEST_FIXTURE_ALLOW_MARKER", "checkForbiddenEgress", "discoverForbiddenEgressScanFiles", "forbiddenEgressFindingsForText"],
+    "./boundary": ["BOUNDARY_POLICY_SCHEMA", "DEFAULT_FORBIDDEN_PATHS", "LEGACY_PROMOTE_EVENT_SCHEMAS", "PRIVATE_AUDIENCES", "PROMOTE_EVENT_SCHEMA", "SEMANTIC_INITIALIZATION_DEFAULTS", "VALID_AUDIENCES", "VALID_AUTOCOMMIT", "VALID_BOUNDARY_MODES", "VALID_REPO_KINDS", "auditContentRules", "checkBoundaryPolicy", "checkPushContent", "createPromoteEvent", "diffFileSections", "installBoundaryHooks", "loadBoundaryPolicy", "projectBoundaryPolicyPath", "projectGovernanceLedgerPath", "resolveCurrentActor", "runBoundaryAuditCommand", "runBoundaryCheckCommand", "runBoundaryInstallHooksCommand", "runBoundaryPushCheckCommand", "runPromoteCommand", "semanticChangesInFile", "semanticFieldOnLine", "stagedPathsForProject", "validateBoundaryPolicy"],
+    "./upgrade": ["ATELIER_LOCK_SCHEMA", "ATELIER_MIGRATION_SCHEMA", "BASE_MIGRATIONS", "LOCK_FILE", "MIGRATION_CLASSES", "applyMigration", "applyUpgrade", "buildAtelierLock", "checkAtelierLock", "loadAtelierLock", "lockPathForProject", "planUpgrade", "runLockCommand", "runUpgradeCommand", "validateMigrationRecord", "writeAtelierLock"],
+    "./attestation": ["KEY_ENV_VAR", "LOCAL_KEY_FILE", "canonicalize", "generateKeyPair", "loadSigningKey", "payloadHashOf", "safeLabel", "signAttestation", "signDocument", "signingInput", "verifyAttestation", "verifyDocument", "verifyPayloadBinding"],
+    "./extension-packs": ["ATELIER_EXT_NAMESPACE", "EXTENSION_PACK_SCHEMA", "PROTOCOL_POSTURE_POINTS", "RESERVED_NAMESPACE", "RESERVED_NAMESPACE_PATTERN", "computePackDigest", "createProtocolRegistry", "loadExtensionPacks"],
+    "./analysis/adapter": ["analysisAdapterDryRun", "runAnalysisAdapterCommand"],
+    "./export-contract": ["ALLOWED_RUNTIME_TARGETS", "LOCAL_AUDIENCES", "OBJECT_CLASSES", "RUNTIME_OWNERS", "RUNTIME_VISIBILITIES", "validateAtelierExportContract", "validateJsonSchema", "validateSchemaShape"],
+    "./dry-run": ["main", "validateAtelierExportDryRun", "validateAtelierExportDryRunFile"]
+  }
+}

package/docs/assurance-controls.md

@@ -0,0 +1,39 @@
+# 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 | `test/boundary-content-rules.test.mjs` | 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` | egress tests, marker-inventory test, and egress case in `assurance:mutation-smoke` | Data-only files are not interpreted; reviewed `gh` subprocess fallbacks are documented exceptions |
+| 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 |
+| 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

@@ -32,3 +32,18 @@ The default package posture is no telemetry, no external network egress, no
 runtime mutation, no browser apply endpoint, and no model-assisted analysis execution.
 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.

package/docs/blocks/claims.md

@@ -3,16 +3,22 @@ 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
+the package. The exceptions are explicit: `boundary check` may invoke `gh api
+user` after no declared actor matches an explicit `--actor`,
+`MNSTRY_ATELIER_ACTOR`, `GITHUB_ACTOR`, or a configured Git email; repository
+identity checks may invoke `gh api repos/...` to resolve a canonical GitHub
+identity. Those authenticated requests use your own `gh` credentials. A
+recognized explicit actor prevents the boundary actor fallback; recorded
+repository identities let identity checks keep working when the provider is
+unavailable. 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:
+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 two reviewed `gh` paths above are therefore
+documented exceptions rather than scanner detections:
 
 ```bash
 npm run egress:check

package/docs/design.md

@@ -12,12 +12,16 @@ proves it — because a design document that cannot be checked is marketing.
 
 ## 1. A repository with an ontology
 
-A small structured header turns a file into a node: front matter on
+A small structured header turns a file into a governed node: front matter on
 Markdown, or a `.kg.json` sidecar beside any other format — JSON, YAML,
 CSV, media, anything — which the kit enrolls without ever parsing the
 foreign format. The header declares identity (`kg.id`), type, status,
 audience, and relations to other nodes.
 
+Markdown without a `kg` block is still counted by the canonical graph engine,
+but only as private `unclassified` material with a diagnostic. Once a `kg`
+block is present, partial or malformed declarations are blocking errors.
+
 The graph builder compiles the repository into a knowledge graph,
 deterministically: same tree in, same graph out, and `--check` mode fails
 when a generated graph has drifted from its sources. There is no import
@@ -92,14 +96,16 @@ atelier lock check --project ./atelier.project.json
 The same governed workspace projects two ways.
 
 For humans: a generated review surface, served by a sidecar that binds to
-loopback only. The served pages carry a policy that authorizes no external
-origin, and the only network client in the package refuses non-loopback
-URLs.
+loopback only. It requires a generated publication manifest and serves only
+enrolled safe static files after realpath validation. The served pages carry a
+policy that authorizes no external origin, and the only network client in the
+package refuses non-loopback URLs.
 
 For agents: session-bound context and capability envelopes that hand an
 agent harness a governed view of the workspace — what exists, what it may
-look at, what it may propose. Proposals are recorded as metadata; there
-are no browser apply endpoints and no write authority to grant. Context
+look at, what it may propose. Proposals are recorded as typed copy-only
+metadata; capability declarations expose no apply endpoint, source write,
+execution, or Git authority. Context
 without authority. Neutral Claude and Codex skill wrappers ship in the
 package, so a harness can do readiness review work against the workspace
 without a single line of custom glue.

package/docs/install.md

@@ -30,19 +30,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.3
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
 ```
 
 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.3"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.3"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the
@@ -57,6 +57,24 @@ The workspace `atelier.lock.json` should record the resolved version or Git
 SHA from the install. Treat the tag or version as the friendly handle and the
 SHA as the review authority.
 
+### Adapter runners must bind package identity
+
+An early downstream adapter exposed a subtle failure mode worth making a
+general rule: a wrapper that scans arbitrary sibling checkouts and accepts the
+first matching binary can validate against an archived tree while appearing
+current. Adapter and distribution runners must therefore:
+
+1. declare one exact `@mnstry/atelier` version in their package manifest;
+2. prefer the installed `node_modules/@mnstry/atelier` package over incidental
+   sibling checkouts;
+3. accept an explicit local checkout only when its package name and version
+   match the declared dependency;
+4. run `atelier --version` and `atelier lock check` as part of adapter proof;
+5. fail closed when the declared version, resolved package, and lock disagree.
+
+This rule binds which Atelier implementation ran. It does not make generated
+output authoritative or grant runtime mutation.
+
 Use one private domain repository per user:
 
 ```text
@@ -103,7 +121,11 @@ atelier init --template shared-project --target ./project-alpha --actor tenant-u
 
 `--actor` rewrites the copied boundary policy actor entry and binds it to the
 local Git email when available. Use `--github-login` or `--git-email` to set
-those values explicitly during onboarding.
+those values explicitly during onboarding. At check time, a declared actor is
+resolved in this order: recognized `--actor`/`MNSTRY_ATELIER_ACTOR`/
+`GITHUB_ACTOR`, configured Git email, then a reviewed `gh api user` fallback.
+An explicit value that is not declared in the policy does not authenticate an
+actor and therefore does not suppress later resolution attempts.
 
 Then update:
 

package/docs/knowledge-graph.md

@@ -7,16 +7,20 @@ projection readiness.
 
 ## Source Rules
 
-- Markdown documents use front matter.
+- Markdown documents may use front matter. A document with no `kg` block is
+  represented as `unclassified`, assigned the fail-closed `private` audience,
+  and reported diagnostically rather than silently treated as governed.
 - Non-Markdown sources use adjacent `.kg.json` sidecars.
-- `kg.id` is required and stable.
-- `kg.audience` is required.
+- Once a Markdown `kg` block exists, `kg.id` and `kg.audience` are required;
+  empty, partial, and malformed declarations are blocking errors.
 - `kg.visibility` is invalid in local source metadata.
 - Declared relations emit semantic edges.
 
 ## Source formats
 
-The graph is sidecar-first: Markdown front matter is the only inline metadata
+The graph has one canonical classification engine in
+`src/graph/knowledge-graph.mjs`; the older `graph.mjs` surface is a compatibility
+adapter over it, not a second classifier. Markdown front matter is the only inline metadata
 format the kit reads, and every other file becomes a first-class node through
 an adjacent `<file>.kg.json` sidecar
 (`contracts/knowledge-source-sidecar.v1.schema.json`). This is how any format

package/docs/local-services.md

@@ -0,0 +1,101 @@
+# Managed local services
+
+Atelier-backed repositories sometimes need a local authoring, review, or
+preview service that writes repository-owned state. The service may be
+specialized; its lifecycle and data-boundary behavior should not be improvised.
+
+This contract applies to consumer services other than `atelier dev`. It does
+not change the Atelier sidecar's own lifecycle.
+
+## Atelier sidecar reference boundary
+
+The built-in `atelier dev` sidecar is the reference for its request and
+publication boundary, not for the managed lifecycle below. It binds only to a
+literal loopback host and refuses startup without a valid generated
+`atelier.manifest.json`. Static reads are limited to manifest-enrolled,
+supported file types after realpath containment; hidden, state, secret-shaped,
+symlinked, unknown, and unenrolled paths are denied. API reads require a trusted
+loopback host and `Sec-Fetch-Site: same-origin` or `none`; `same-site` and
+cross-site requests are refused. Mutations additionally require an
+allowed method, exact expected origin, and the session nonce. Its collaboration
+records are copy-only proposals, not an apply channel.
+
+## Kit and adapter boundary
+
+The portable Atelier layer owns these invariants:
+
+- bind to loopback only;
+- expose explicit `start`, `status`, and `stop` operations;
+- detach only when the user asked for a service that survives an agent command;
+- identify the running process with both a random runtime identifier and its
+  process ID;
+- refuse to adopt, overwrite, or stop a process whose identity cannot be
+  proven;
+- keep runtime records, logs, drafts, and recovery copies in ignored local
+  storage with owner-only permissions;
+- make writes atomic and keep a failed queued write from poisoning later saves;
+- keep unsaved browser work available when the service disappears;
+- provide an explicit snapshot export and a retry path;
+- use no telemetry, remote dependency, or external send path.
+
+The consuming repository owns its service name, port, executable, state schema,
+content, command names, and user-facing recovery copy. None of those adapter
+details belong in the public Atelier kit.
+
+## Lifecycle contract
+
+### Start
+
+1. Resolve an explicit loopback port and ignored runtime directory.
+2. Probe the service health endpoint.
+3. If a managed instance answers with the recorded runtime identifier and PID,
+   report it as already running.
+4. If anything else owns the port, refuse to take it over.
+5. Generate a fresh runtime identifier, start the child without a shell, write
+   a mode-0600 runtime record, and wait for health to echo both identifiers.
+6. If health never proves ownership, stop only the child just created and
+   report the ignored operational log.
+
+### Status
+
+Status is healthy only when the runtime record, health response, runtime
+identifier, PID, service identity, and loopback address agree. A responding
+port without that proof is occupied, not adopted.
+
+### Stop
+
+Stop only the PID whose health response matches the recorded runtime identifier
+and PID. Refuse on disagreement. After a clean stop, remove only the generated
+runtime record. Never kill by port, process name, or broad pattern.
+
+Managed start survives a terminal or agent command. It does not imply operating
+system startup. Installing an OS-level service is a separate system change and
+requires explicit user authorization.
+
+## Authoring-state contract
+
+- The canonical template may be tracked; the live draft must be ignored unless
+  a reviewed workflow explicitly promotes a sanitized artifact.
+- Live state and runtime metadata use owner-only permissions.
+- Browser autosave is a recovery layer, not a substitute for the canonical
+  local file.
+- A lost server must produce a persistent, actionable message naming the exact
+  restart command, the retained browser state, the snapshot option, and Retry.
+- Conflict responses remain fail-closed. Do not silently overwrite a newer
+  file or reconcile divergent tabs automatically.
+
+## Required evidence
+
+A consumer implementation is not complete until tests prove:
+
+1. start is idempotent and survives the launching command;
+2. status refuses an unowned listener;
+3. stop is bound to runtime identifier and PID;
+4. a stopped server leaves the exact in-browser draft intact;
+5. restart plus Retry persists that draft;
+6. a refused filesystem write does not break later valid saves;
+7. private state and runtime files are ignored and owner-readable only; and
+8. a fresh checkout can discover the commands through its agent instructions.
+
+Use synthetic fixtures for public Atelier tests. Tenant-specific proof remains
+in the tenant repository.

package/docs/release-engineering.md

@@ -10,16 +10,23 @@ a location, never the matched content.
 ### release:audit
 
 `npm run release:audit` (`scripts/check-release-tarball.mjs`) audits the exact
-tarball `npm pack` would publish:
+tarball `npm pack` would publish. `npm run release:candidate` packs once and
+passes the same archive and expected SHA-256 through this audit and both
+consumer smokes:
 
 - Package metadata: name, license, exposed CLI bins, and a mandatory `files`
   allowlist in `package.json`.
 - Tarball allowlist: every packed path must match a known-good pattern; any
-  unexpected file fails the audit.
+  unexpected file fails the audit. The extracted archive inventory must match
+  the `npm pack --json` inventory exactly.
 - Content scan: every packed file is scanned against committed structural
   patterns (absolute user paths, machine-local temp paths, agent-local state
   paths, key material, secret-like assignments) and against the maintainer-held
   denylist described below.
+- Egress scan: the canonical egress control receives the exact `npm pack`
+  inventory and inspects every packed executable or markup file, including a
+  test-shaped path if one is ever admitted to the artifact. Packed test-fixture
+  suppression markers are refused; reviewed local-computed markers are counted.
 - Version drift: `CHANGELOG.md` must contain a `## <version>` heading and
   `README.md` must mention the version. The expected version and tarball name
   are derived from `package.json`, never hardcoded.
@@ -27,6 +34,15 @@ tarball `npm pack` would publish:
 Exit codes: `0` clean, `1` findings, `2` configuration error (for example an
 unavailable denylist without explicit acknowledgment).
 
+`release:candidate` additionally requires a clean tree, records the candidate
+commit and tarball digest, and refuses a version already bound to a different
+tagged commit. It is a release-evidence command, not a publication command.
+When `ATELIER_RELEASE_OUTPUT_DIR` is set, it atomically retains the verified
+tarball, npm-pack metadata, and a machine-readable receipt. The trusted
+publishing workflow runs `prepublishOnly` explicitly with that output directory,
+re-verifies the retained digest, and publishes the retained tarball path rather
+than repacking the source checkout.
+
 ### repo:check
 
 `npm run repo:check` (`scripts/check-repo-disclosure.mjs`) sweeps the whole
@@ -43,6 +59,27 @@ Git-tracked tree, not just the tarball:
 Exit codes match `release:audit`: `0` clean, `1` findings, `2` configuration or
 usage error.
 
+### disclosure check
+
+`atelier disclosure check` is the portable consumer-facing content gate. It
+scans every tracked text file by default or the exact staged index with
+`--staged`, never follows tracked symlinks, and reports labels plus locations
+without echoing matched content. `--untrusted` suppresses finding details.
+
+The command loads private patterns from `ATELIER_DENYLIST_JSON`, an explicit
+`--denylist` path, or ignored
+`.atelier-local/disclosure-denylist.json`. A repository-local denylist is
+refused if it is tracked or not covered by `.gitignore`. Missing private
+patterns are a configuration failure unless `--structural-only` explicitly
+acknowledges the reduced verdict. Public text-only packaging can also use
+`--fail-on-binary`; Atelier's own tarball audit separately refuses packed
+binary files.
+
+The public Atelier repository keeps the stronger `repo:check` identity and
+commit-message controls. The portable command exists so consumer repositories
+can enforce the same public/private content boundary without inheriting
+MNSTRY-specific commit identities.
+
 ### Commit-identity gate
 
 Part of `repo:check --commits`. Commit authors must match a hardcoded
@@ -65,6 +102,17 @@ changelog and the migration registry honest about breaking changes:
 - Every registered migration record is re-validated against the migration
   record contract.
 
+### public-api:compat
+
+`npm run public-api:compat` compares every package subpath and named JavaScript
+export published by `v0.2.0-alpha.4` with the current package. Removing one
+fails closed. It also rejects modified source that retains the already-tagged
+baseline version, independently of the release-candidate check. The baseline
+records and verifies its tag commit and the public npm artifact identity; the
+published archive was independently checked to contain all 20 subpaths and 212
+named exports. This is runtime JavaScript shape continuity, not a promise about
+function signatures, types, or behavior.
+
 ### egress:check
 
 `npm run egress:check` (`atelier egress check`) scans package runtime paths for
@@ -75,8 +123,22 @@ paths; this gate is the mechanical check behind that claim.
 
 `npm run consumer:smoke` (`scripts/consumer-smoke.mjs`) packs the real tarball,
 installs it offline into a throwaway consumer project with lifecycle scripts
-disabled, and imports the public API to validate a sample export. It proves the
-tarball is installable and functional exactly as a consumer receives it.
+disabled and without copying the publisher's `overrides`, checks the installed
+dependency tree, imports every declared JavaScript export, parses every
+declared JSON export, and validates a sample export through both API and CLI.
+It proves the tarball is installable and functional exactly as a bare consumer
+receives it from disk. The offline smoke deliberately warms the locked registry
+dependency closure first; it does not prove that a not-yet-published version
+resolves from a cold or live registry.
+
+### assurance:mutation-smoke
+
+`npm run assurance:mutation-smoke` runs local, synthetic negative controls for
+the boundary, graph, packed and direct egress, sidecar, and distribution
+families. Every fixture introduces one named failure and must be refused by the
+terminal CLI or release command where one exists. This is part of
+`prepublishOnly`; a control that stops detecting its failure mode blocks the
+release even if positive-path tests remain green.
 
 ### Egress-marker inventory
 
@@ -105,7 +167,7 @@ maintainer-reviewed before entering the list.
 Four jobs run on pushes to `main` and on pull requests, and all four are
 required status checks:
 
-- `test`: syntax check (`node --check`, not a type system), the full test suite, contract checks, `egress:check`, and
+- `test`: syntax check (`node --check`, not a type system), the full test suite (including isolated consumer disclosure-command proofs), contract checks, `egress:check`, `assurance:mutation-smoke`, and
   `migrations:check`. This job sets `ATELIER_ALLOW_MISSING_DENYLIST=1` scoped
   to the job only — denylist assertions belong to the secret lane.
 - `consumer-smoke`: warms the npm cache with `npm ci` (the offline tarball
@@ -127,11 +189,14 @@ the only safe block.
 
 To clear a fork pull request, a maintainer verifies the head SHA and dispatches
 the `fork-sweep` workflow with the pull-request number and that SHA. The
-workflow runs the trusted scanner from `main` against the fork's tree checked
-out as data — it never installs or executes anything from the untrusted tree —
-re-verifies that the head SHA has not moved, and posts a `secret-sweep` check
-run on the SHA. The newest check run with that name supersedes the earlier
-failure for branch protection.
+workflow pins the trusted scanner checkout to the protected default branch and
+runs it against the fork checked out as data — it never installs or executes
+anything from the untrusted tree. It requires an open PR whose base repository
+and branch are the protected default, pins the base and head SHAs from GitHub,
+scans the complete bounded base-to-head object range while waiving only
+repository-specific commit identity, re-verifies that the head SHA has not
+moved, and posts a `secret-sweep` check run on the SHA. The newest check run
+with that name supersedes the earlier failure for branch protection.
 
 `release:audit` never runs against untrusted code (`npm pack` executes
 lifecycle scripts); it re-runs on the push build of the merge commit. No

package/docs/repo-boundary-guard.md

@@ -170,12 +170,22 @@ machine for weeks.
 - `pre-push` runs `atelier boundary push-check` — git writes the ref updates to
   the hook's stdin, and only that range is judged. A brand-new branch is diffed
   against the empty tree, so nothing slips through unscanned.
-- `atelier boundary audit` scans the whole tree and **reports without blocking**,
-  listing both matches and declared exceptions with their reasons.
+- `atelier boundary audit` scans the current working tree by default and
+  **reports without blocking**, listing matches, incomplete-read diagnostics,
+  and declared exceptions with their reasons. Use `--head` for a committed
+  snapshot. The output names its source so a dirty tree cannot be mistaken for
+  `HEAD` evidence.
 
 If the guard cannot work out which repo it is running in, it fails closed. A
 guard that silently judges nothing is worse than one that stops you.
 
+Path scopes are segment-aware globs: `*` does not cross `/`, `**` does, and
+patterns are matched against normalized repository-relative paths. Explicitly
+declaring `contentRules: []` is invalid; omit the field to receive defaults.
+Git diff output and binary reads have per-file and aggregate budgets. A failed,
+truncated, oversized, or unparsable evidence read produces a blocking
+completeness diagnostic rather than a partial clean verdict.
+
 ### Declaring an exception
 
 Exceptions live in the boundary policy, not in the guard script. A repo-specific

package/docs/upgrade.md

@@ -5,6 +5,38 @@ 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.5
+
+This release hardens public/private boundary enforcement, local serving,
+collaboration-ledger integrity, disclosure review, and release provenance.
+Documents valid against `0.2.0-alpha.0` remain contract-compatible, but some
+previously tolerated unsafe or ambiguous states now fail closed.
+
+- Projects using `atelier dev` must provide a generated
+  `atelier.manifest.json`; only enrolled, safe, realpath-validated static files
+  are served, and the sidecar accepts loopback traffic only.
+- Empty or malformed content-rule policies, incomplete Git reads, corrupt or
+  oversized collaboration ledgers, and unsafe manifest entries are now
+  blocking errors with typed CLI diagnostics.
+- Run `atelier disclosure check` before sharing tracked or staged content. A
+  private denylist is required by default and must remain outside the public
+  repository.
+- Release candidates are packed once, SHA-256-bound, and the exact audited
+  tarball is the artifact sent through npm trusted publishing.
+
+Re-run the boundary, disclosure, graph, readiness, and lock checks below after
+updating. If `atelier dev` previously served files without a manifest, generate
+and review the manifest before restarting it.
+
+## 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
@@ -85,7 +117,7 @@ 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.3
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -93,7 +125,7 @@ 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.3"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.5"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/fixtures/projects/sample-workspace/content/source.html.kg.json

@@ -1,5 +1,6 @@
 {
-  "assetFilename": "source.html",
+  "schema": "mnstry.source-sidecar@v1",
+  "asset": "source.html",
   "title": "Sample Source",
   "summary": "Neutral non-Markdown source with durable sidecar identity.",
   "tags": [
@@ -8,6 +9,8 @@
   "kg": {
     "id": "sample-workspace:source-html",
     "type": "source",
+    "domain": "sample",
+    "lifecycle": "source",
     "status": "active",
     "audience": "private",
     "relations": {}