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

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## 0.2.0-alpha.5
+
+- Harden boundary enforcement so path globs use segment-aware matching, an
+  explicitly empty or malformed content-rule policy is invalid, staged and
+  pushed binary evidence is scanned within bounded budgets, incomplete Git
+  reads fail closed, linked worktrees install hooks in the correct Git common
+  directory, and `boundary audit` defaults to the current working tree with an
+  explicit `--head` snapshot mode.
+- Consolidate graph classification in one canonical engine. Markdown without a
+  `kg` block is now represented as `unclassified` with a private audience and
+  diagnostics; empty, partial, or malformed declarations remain blocking.
+  Generated projection directories remain derived from the file-class manifest
+  so graph validation and generated-only upgrade recovery cannot drift apart.
+- Bind release egress verification to the exact `npm pack` inventory, including
+  test-shaped paths that are actually published, and make the legacy egress
+  checker a thin delegate to the canonical scanner. Packed fixture-suppression
+  markers are refused and reviewed local-computed suppressions are counted.
+- Harden `atelier dev` so it binds only to loopback, requires a generated
+  `atelier.manifest.json`, serves only enrolled safe static files after
+  realpath validation, and applies host, fetch-site, origin, method, and nonce
+  checks to the relevant read and mutation routes.
+- Make collaboration records fail closed with typed corrupt-record results,
+  bounded ledger reads, POSIX no-follow and cross-platform state-leaf identity
+  validation, content-bound event identifiers, write locking, explicit
+  compaction, and one-pass proposal-list materialization. Compatibility
+  snapshots are best-effort projections of committed events rather than a
+  second authority. Proposal authority now follows declared capabilities and
+  apply endpoints rather than action-like words, and the never-released
+  provider-analysis experiment was removed before it became part of a
+  published API.
+- Render expected project and JSON failures as typed, actionable CLI messages
+  without stacks by default; set `ATELIER_DEBUG=1` to include diagnostic stacks.
+- Strengthen release proof with negative-control mutations and a bare consumer
+  that installs without publisher overrides, validates its dependency tree,
+  and imports every declared package export. A candidate is packed once, bound
+  by SHA-256, and passed unchanged through tarball audit, consumer, and branded
+  distribution gates. The trusted-publishing workflow publishes that same
+  retained, audited tarball rather than repacking the source directory.
+- Pin every JavaScript subpath and named export from `v0.2.0-alpha.4` in a
+  registry-verified compatibility baseline with immutable tag-commit and
+  public-artifact provenance. Release tooling refuses removals, provenance
+  drift, and binding modified source to an already-tagged package version.
+- Add a portable `atelier disclosure check` command that scans tracked or
+  staged consumer content, requires private denylist coverage by default, and
+  refuses tracked repository-local denylist files. Portable and repository
+  sweeps now detect the full bounded family of private-key headers and refuse
+  binary or invalid-UTF-8 evidence instead of omitting it. Fork sweeps require
+  the trusted denylist secret and cannot fall back to the untrusted checkout.
+  Repository release sweeps also inspect every bounded blob introduced by the
+  commit range, so content added and deleted before the final tree cannot
+  become public history unseen.
+- Add public agent instructions and mirrored skills for extracting reusable
+  mechanisms from private implementations without carrying tenant material
+  into Atelier, plus a managed local-service contract for durable loopback
+  authoring and review tools.
+- Document the client-zero adapter rule that exact package identity, installed
+  dependency resolution, CLI version, and `atelier.lock.json` must agree. This
+  prevents a stale sibling checkout from satisfying a current adapter proof.
+- Declare the audited `fast-uri` pin as a direct runtime dependency so packed
+  offline consumer installs resolve the same dependency closure as the source
+  checkout.
+
 ## 0.2.0-alpha.4
 
 Presentation release. No contract changes and no runtime behaviour changes:

package/README.md

@@ -48,7 +48,7 @@ governed projections
 You can see the complete loop in a disposable sample workspace:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.4
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
 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
@@ -146,6 +146,20 @@ 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.
 
+Repositories that may contribute to a public or shared surface can add a
+private, ignored disclosure denylist and scan either the tracked tree or the
+exact staged index:
+
+```bash
+npx mnstry-atelier disclosure check --staged
+```
+
+The built-in structural pass catches machine-local paths, key material, and
+secret-shaped assignments. A client-aware verdict additionally requires the
+private denylist; the command fails closed when it is absent unless
+`--structural-only` is chosen explicitly. Denylist patterns and matched text
+never belong in the shared repository.
+
 ### 3. Collaboration becomes governed disclosure
 
 Collaboration is not equivalent to giving every participant every file. The
@@ -163,6 +177,11 @@ boundary; it does not silently make access decisions on your behalf.
 graph. The library exposes the same project, graph, validation, and projection
 primitives to code.
 
+Consumer-owned authoring or review services that need a separate durable
+lifecycle follow [the managed local-service contract](./docs/local-services.md).
+That contract standardizes process ownership, private local state, and browser
+recovery without putting a tenant's service details into Atelier.
+
 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
@@ -234,16 +253,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
@@ -316,7 +341,7 @@ Node.js `>=22.18.0 <23` is required. Pin the prerelease while the package
 remains in alpha:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.4
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.5
 ```
 
 Then choose the path that matches what you are building:
@@ -328,11 +353,12 @@ Then choose the path that matches what you are building:
 - [Distribution contracts](./docs/distributions.md)
 - [Conformance and attestation](./docs/attestation.md)
 - [Continuity commitments](./docs/continuity.md)
+- [Assurance controls and evidence map](./docs/assurance-controls.md)
 - [Upgrade notes](./docs/upgrade.md)
 
 ## Status and command reference
 
-Current package: `@mnstry/atelier@0.2.0-alpha.4`.
+Current package: `@mnstry/atelier@0.2.0-alpha.5`.
 
 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.

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.4
+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.4"
+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.4"
+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.