@mnstry/atelier 0.2.0-alpha.14 → 0.2.0-alpha.16

package/contracts/public-api-baseline.json

@@ -32,26 +32,305 @@
     "./export-contract",
     "./dry-run",
     "./contracts/atelier-export.v1.schema.json",
-    "./fixtures/atelier-export/sample-studio-offer.v1.json"
+    "./fixtures/atelier-export/sample-studio-offer.v1.json",
+    "./extensions",
+    "./extensions/client",
+    "./extensions/server",
+    "./extensions/postgres",
+    "./contracts/atelier-extension-manifest.v1.schema.json",
+    "./extensions/drizzle",
+    "./extensions/prisma"
   ],
   "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"]
+    ".": [
+      "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"
+    ],
+    "./extensions": [
+      "ExtensionError",
+      "canonicalJson",
+      "exact",
+      "parseInstallationBinding",
+      "parseManifest",
+      "parseOperationReceipt",
+      "text",
+      "parseProviderOperationProof"
+    ],
+    "./extensions/client": [
+      "createExtensionAdminClient",
+      "createExtensionClient",
+      "createHttpHostTransport"
+    ],
+    "./extensions/server": [
+      "assertVerifiedScope",
+      "createExtensionHandler",
+      "createRootAdmissionConsumer",
+      "defineAction",
+      "defineExtension",
+      "digest",
+      "releaseDigest"
+    ],
+    "./extensions/postgres": [
+      "lookupPostgresOperation",
+      "oncePostgresOperation",
+      "postgresHealth",
+      "withPostgresScope"
+    ],
+    "./extensions/drizzle": [
+      "drizzleHealth",
+      "lookupDrizzleOperation",
+      "onceDrizzleOperation",
+      "withDrizzleScope"
+    ],
+    "./extensions/prisma": [
+      "lookupPrismaOperation",
+      "oncePrismaOperation",
+      "prismaHealth",
+      "withPrismaScope"
+    ]
   }
 }

package/docs/README.md

@@ -0,0 +1,90 @@
+# Atelier documentation
+
+Choose a starting path, then use the task guides and references for the installed version.
+The [responsibility architecture](reference/architecture.md) and versioned contracts remain the existing authorities.
+
+## Start here
+
+- [Start Atelier independently](start/independent-start.md)
+- [Install](start/install.md)
+- [Set up a graph that earns its context](start/knowledge-setup.md)
+- [Start a research workspace](start/research-starter-quickstart.md)
+
+## Task guides
+
+- [Atelier Sync: headless repository supervision](guides/atelier-sync.md)
+- [Capability stewardship](guides/capability-stewardship.md)
+- [Co-authoring with agents](guides/co-authoring.md)
+- [Distributions](guides/distributions.md)
+- [Local exact-plan upgrades](guides/exact-upgrades.md)
+- [Custom database extensions](guides/extensions.md)
+- [Upgrade with your agent](guides/guided-upgrades.md)
+- [Progressive local ingestion](guides/ingestion.md)
+- [Discovery Harness and Research Harness](guides/inquiry-harnesses.md)
+- [Knowledge workspaces and guided coauthoring](guides/knowledge-workspace.md)
+- [Knowledge development and the learning cycle](guides/learning-harnesses.md)
+- [Learning from corrections and outcomes](guides/learning.md)
+- [Local source review](guides/local-review.md)
+- [Obsidian projection: selection, apply policy and acceptance receipts](guides/obsidian.md)
+- [Personal workspace composition](guides/personal-workspace.md)
+- [Research starter](guides/research-starter.md)
+- [Skill stewardship](guides/skill-steward.md)
+- [Local template adoption](guides/template-upgrades.md)
+- [Tenant Readiness Guide](guides/tenant-readiness.md)
+- [Upgrade Guide](guides/upgrade.md)
+
+## Architecture and API reference
+
+- [Announcements](reference/announcements.md)
+- [Responsibilities, workflows and runtime bindings](reference/architecture.md)
+- [MNSTRY Atelier Runtime](reference/atelier-runtime.md)
+- [Attestation](reference/attestation.md)
+- [Experimental portable coauthor session](reference/coauthor-session.md)
+- [Connected composition: synthetic foundation](reference/connected-composition.md)
+- [Distribution continuity commitment](reference/continuity.md)
+- [Contract stability](reference/contract-stability.md)
+- [Portable Coordination and native authority](reference/coordination.md)
+- [Decision practices](reference/decision-practices.md)
+- [Typed decision proposals](reference/decisions.md)
+- [The design](reference/design.md)
+- [Evidence navigation](reference/evidence-navigation.md)
+- [Pack compatibility for evidence-bound review](reference/extension-pack-lifecycle.md)
+- [Immutable intake and guide integration](reference/intake-and-guides.md)
+- [Interaction and Reflection](reference/interaction-and-reflection.md)
+- [MNSTRY Atelier Knowledge Graph](reference/knowledge-graph.md)
+- [Managed local services](reference/local-services.md)
+- [Durable local state](reference/local-state.md)
+- [Obsidian projection contract](reference/obsidian-contract.md)
+- [Atelier's Obsidian plugin](reference/obsidian-plugin.md)
+- [Atelier export ontology](reference/ontology.md)
+- [Optional ingestion suppliers](reference/optional-ingestion.md)
+- [Portability: what a record holds and what the checks prove](reference/portability.md)
+- [Portable presentation v1](reference/portable-presentation.md)
+- [Phronesis — practical judgment](reference/phronesis.md)
+- [Presentation and public-page consumers](reference/presentation-consumer-boundaries.md)
+- [Project option and command inventory](reference/project-command-inventory.md)
+- [Project location and repository overrides](reference/project-options.md)
+- [Repo Boundary Guard V1](reference/repo-boundary-guard.md)
+- [Review state and portable inspection](reference/review-portability.md)
+- [Vanilla semantic proposal processor](reference/semantic-ingestion.md)
+- [Semantic operation: internal vanilla profile](reference/semantic-operation.md)
+- [Portable template profiles](reference/template-profile.md)
+- [Trackables: one definition, one domain writer](reference/trackables.md)
+- [Portable private artifact vaults (experimental)](reference/vault-service.md)
+
+## Maintainer controls
+
+- [Assurance controls and evidence map](maintainers/assurance-controls.md)
+- [Describing the Atelier](maintainers/describing-the-atelier.md)
+- [Release engineering](maintainers/release-engineering.md)
+
+## Knowledge Health
+
+- [Collection overview](knowledge-health/readme.md)
+- [Public workshop](knowledge-health/quickstart.md)
+- [Participant response and recovery](knowledge-health/participant-response.md)
+- [Facilitator guide](knowledge-health/facilitator.md)
+- [Assessment example](knowledge-health/assessment/quickstart.md)
+- [Participatory host API](knowledge-health/api.md)
+
+The [claim blocks](blocks/) supply the canonical promise text embedded in the package README.

package/docs/blocks/claims.md

@@ -14,7 +14,7 @@ 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.
+See `docs/start/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
@@ -69,6 +69,6 @@ service, no network:
 atelier dry-run ./atelier-export.json
 ```
 
-`docs/continuity.md` records the distribution commitments behind these
+`docs/reference/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

@@ -9,7 +9,7 @@ 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`).
+attestation against criteria this package publishes (`docs/reference/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/{atelier-sync.md → guides/atelier-sync.md}

@@ -1,9 +1,14 @@
-# Atelier Sync: Deliverable Zero
+# Atelier Sync: headless repository supervision
 
-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.
+Atelier Sync is the optional headless repository supervisor in the public
+Atelier toolkit. Its CLI and runtime APIs cover Git, filesystem, state-machine,
+recovery and user-authority boundaries. Use the [independent local start](../start/independent-start.md)
+for authoring without enabling supervision.
+
+The public toolkit includes no desktop utility, tray shell or native installer.
+MNSTRY's desktop utility is a separate proprietary consumer. Generic startup,
+editor and native-presentation bindings remain optional public tooling; a host
+owns its installation, background lifecycle and user interface.
 
 This is repository mechanics, not MNSTRY runtime authority. A Git commit
 changes the enrolled repository. It does not mutate MNSTRY identity, consent,
@@ -20,7 +25,7 @@ runtime object.
   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.
+  dependency.
 - 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,
@@ -74,8 +79,8 @@ 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);
+  unclassified external filesystem roots (mapped-drive classification requires
+  a qualified operating-system host integration);
 - 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;
@@ -151,8 +156,8 @@ 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.
+A consuming host may present the final two commands as **Commit & sync**.
+It must preserve both phases and their exact confirmation boundary.
 
 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
@@ -161,12 +166,13 @@ 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,
+The headless supervisor contract has automated coverage 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
+notarization and a nontechnical-user workflow require separate evidence from
+the consuming host. These tests establish no installed desktop qualification.
+Repositories without an initial commit are unsupported by this supervisor.
+A Git executable upgrade changes enrolled identity and
 requires re-enrollment.

package/docs/guides/co-authoring.md

@@ -0,0 +1,113 @@
+# Co-authoring with agents
+
+A body of work is authored together, in the structure of the work itself
+rather than in a document tool or an email thread. People read and question
+the pages. Agents draft from the graph and the questions. Where the checks
+run in the commit path, every change, by a person or an agent, passes the
+same checks, and that is what makes the agentic
+process (an agent acting inside a governed workflow) reliable.
+
+This page describes the loop, the record it leaves, and what has to be in
+place for it to hold. The files are yours. The package supplies the graph,
+the checks and the collaboration records. The harness supplies the agent.
+Nothing here changes what the package will and will not do to a source:
+README section 4, "The local runtime serves people and agents", states that,
+and the will-not-do block states the rest.
+
+## The loop
+
+Three actors take part: a person, an agent running in the harness, and the
+package. In this loop the package records, checks and refuses; the edit and
+the commit are the agent's or the person's.
+
+1. **A person asks on the page.** A reader selects the sentence they mean on
+   the projected page and leaves a question, a correction or a discussion. The
+   review surface (the package's optional `atelier dev --review`, or a
+   consumer adapter built on the collaboration ledger) records the note and
+   pins it to that passage and to the digest of that revision of the source.
+2. **An agent drafts from the graph.** In the harness it reads the open
+   questions on the file, follows the graph to every file declared to depend
+   on it, and edits those files in the working tree. Where they are wired in,
+   the graph check and the boundary guard run against its work as they would
+   against anyone's.
+3. **A person decides, and the change lands.** The person reviews the draft
+   and, where the workflow records decisions, records one with its rationale
+   through the consumer adapter or the team's workflow. The optional review
+   workspace records decisions on review-run claims, not decisions about a draft
+   change. The package does not require or check a decision before a commit. The
+   person or the agent commits the change through the boundary guard, and the
+   graph and the pages built from it follow on their next build.
+
+The next question starts from the updated source.
+
+## Provenance is built in
+
+The review store pins notes and reading positions to a document's digest and
+the passage they address, and binds decisions to the evidence they judged.
+A contribution made against a stale version is refused. A later decision
+supersedes an earlier one, and the history keeps both. Each record carries the
+name its author gives, which the package records as locally asserted, not
+authenticated. `docs/guides/local-review.md` describes the store and its refusals. When the source changes, earlier notes stay pinned to
+the wording they addressed, so "what has been questioned about this passage"
+is a lookup, not a memory.
+
+A change by an agent passes the same checks as a change by a person: the graph
+check and the boundary guard, where they are wired in. A team that wants every
+change to carry a recorded decision adds that rule to its own workflow; the
+package does not enforce it.
+
+## Giving an agent a job
+
+This section describes the system (the package with a harness and connected
+tools), not the package alone.
+
+You define the outcome and constraints. An agent uses the relevant files,
+works through the task with connected tools and returns work to review.
+Approved changes become part of the shared record for the next task. The
+agent's instructions (its skill and the harness's permissions, not a package
+gate) specify which records it may use, what it may change and when approval
+is required.
+
+The team defines a goal and reviews a proposed plan before the agent starts,
+then reviews the outputs and approves consequential actions. Accepted changes
+update the shared knowledge, so the next task starts from the latest agreed
+material rather than from a fresh briefing.
+
+What has to be connected: the agent, access to the relevant files, and
+whatever other tools the chosen workflow uses,
+plus agreed review responsibilities and action permissions. The package
+organizes source material and review contributions; agent execution and
+external delivery are integrations you configure in the harness.
+
+## What the loop rests on
+
+- **A harness with the skills installed.** `atelier skills sync` installs the
+  package's skill files into the workspace from a digest-confirmed plan (by
+  default from the package's `skills/codex` into `.agents/skills`; `--source`
+  and `--target` change that). Whether a harness discovers and follows them
+  is the harness's matter. See `docs/guides/skill-steward.md`.
+- **Gates in the commit path.** The boundary guard hooks
+  (`atelier boundary install-hooks`) and the graph check in CI. The sentence
+  "every change passes the same checks" is true where the checks run on every
+  commit.
+- **A contribution surface.** The package's loopback projection carries the
+  page and its passages. Its optional review workspace (`atelier dev --review`,
+  described in `docs/guides/local-review.md`) records passage notes and decisions
+  on review-run claims. A consumer adapter built on the collaboration ledger
+  or the team's workflow records decisions about a draft change;
+  `docs/reference/coauthor-session.md` describes the experimental portable
+  session reducer. These records do not apply a source change; the agent in
+  the harness does, and the checks run against it.
+- **Examples with expected results.** By convention, each round of authoring
+  adds reviewed examples with expected results beside the rules they test. The
+  package keeps them and their links in the graph; it does not run them. An
+  agent in the harness runs them against its drafts, and because they stay in
+  the record, a later draft can be checked against the same cases.
+
+## What the package does not do here
+
+It does not draft. It does not apply a proposal to a source. It does not
+grant an agent write access. It does not decide. It records the question,
+checks the change, and records a decision when one is given, and it refuses
+a contribution made against a stale version. The rest is the harness's work
+and the people's.