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

package/fixtures/ui/presentation/reference.v1.json

@@ -0,0 +1,293 @@
+{
+  "schema": "atelier.presentation/v1",
+  "version": "1.0.0",
+  "id": "reference-desk",
+  "title": "Reference desk",
+  "lang": "en",
+  "direction": "ltr",
+  "theme": "light",
+  "density": "comfortable",
+  "navigation": [
+    {
+      "id": "nav-work",
+      "label": "Working area",
+      "target": "work"
+    },
+    {
+      "id": "nav-context",
+      "label": "Context",
+      "target": "context"
+    }
+  ],
+  "panes": [
+    {
+      "id": "work",
+      "label": "Working area",
+      "role": "primary",
+      "width": {
+        "min": 30,
+        "max": 75,
+        "value": 60
+      },
+      "blocks": [
+        "intro",
+        "draft-title",
+        "draft-body",
+        "comparison",
+        "preview",
+        "paper-image"
+      ]
+    },
+    {
+      "id": "context",
+      "label": "Context",
+      "role": "context",
+      "width": {
+        "min": 25,
+        "max": 60,
+        "value": 35
+      },
+      "blocks": [
+        "items",
+        "steps",
+        "graph",
+        "status",
+        "refusal",
+        "decision",
+        "receipt",
+        "offer",
+        "review",
+        "publication"
+      ]
+    }
+  ],
+  "nodes": [
+    {
+      "id": "paper-image",
+      "type": "media",
+      "label": "Paper illustration",
+      "src": "/paper.svg",
+      "alt": "A grey rectangular sheet on a plain background",
+      "caption": "Invented reference media; the host supplies the local asset."
+    },
+    {
+      "id": "intro",
+      "type": "text",
+      "label": "A small reference workspace",
+      "text": "Invented notes and objects exercise the presentation contract. Content, workflow and permissions belong to the host."
+    },
+    {
+      "id": "draft-title",
+      "type": "field",
+      "label": "Note title",
+      "value": "A study of paper shapes",
+      "input": "text",
+      "required": true,
+      "disabled": false
+    },
+    {
+      "id": "draft-body",
+      "type": "editor",
+      "label": "Draft text",
+      "value": "Arrange three paper shapes on the table.\nDescribe how their edges meet.",
+      "disabled": false
+    },
+    {
+      "id": "comparison",
+      "type": "diff",
+      "label": "Change preview",
+      "before": "Two paper shapes.",
+      "after": "Three paper shapes.",
+      "beforeLabel": "Earlier text",
+      "afterLabel": "Proposed text"
+    },
+    {
+      "id": "preview",
+      "type": "preview",
+      "label": "Read-only preview",
+      "text": "A study of paper shapes\n\nThree simple shapes share a table."
+    },
+    {
+      "id": "items",
+      "type": "collection",
+      "label": "Objects",
+      "items": [
+        {
+          "id": "circle",
+          "label": "Circle",
+          "detail": "Round edge",
+          "selected": true
+        },
+        {
+          "id": "square",
+          "label": "Square",
+          "detail": "Four equal edges",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "id": "steps",
+      "type": "sequence",
+      "reorderable": true,
+      "label": "Reading order",
+      "items": [
+        {
+          "id": "observe",
+          "label": "Observe",
+          "selected": false
+        },
+        {
+          "id": "describe",
+          "label": "Describe",
+          "selected": false
+        }
+      ]
+    },
+    {
+      "id": "graph",
+      "type": "graph",
+      "label": "Connections",
+      "items": [
+        {
+          "id": "paper",
+          "label": "Paper"
+        },
+        {
+          "id": "shape",
+          "label": "Shape"
+        }
+      ],
+      "edges": [
+        {
+          "from": "paper",
+          "to": "shape",
+          "label": "folded into"
+        }
+      ]
+    },
+    {
+      "id": "status",
+      "type": "status",
+      "label": "Status",
+      "text": "Host-supplied status information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": []
+    },
+    {
+      "id": "refusal",
+      "type": "refusal",
+      "label": "Refusal",
+      "text": "Host-supplied refusal information.",
+      "tone": "warning",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": [
+        "disabled-action"
+      ]
+    },
+    {
+      "id": "decision",
+      "type": "decision",
+      "label": "Decision",
+      "text": "Host-supplied decision information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": []
+    },
+    {
+      "id": "receipt",
+      "type": "receipt",
+      "label": "Receipt",
+      "text": "Host-supplied receipt information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": []
+    },
+    {
+      "id": "offer",
+      "type": "offer",
+      "label": "Offer",
+      "text": "Host-supplied offer information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": []
+    },
+    {
+      "id": "review",
+      "type": "review",
+      "label": "Review",
+      "text": "Host-supplied review information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": []
+    },
+    {
+      "id": "publication",
+      "type": "publication",
+      "label": "Publication",
+      "text": "Host-supplied publication information.",
+      "tone": "neutral",
+      "details": [
+        {
+          "label": "Source",
+          "value": "Invented reference host"
+        }
+      ],
+      "actions": [
+        "confirm-action"
+      ]
+    },
+    {
+      "id": "confirm-action",
+      "type": "action",
+      "label": "Request publication",
+      "actionRef": "publish-request",
+      "disabled": false,
+      "confirmation": {
+        "title": "Request publication?",
+        "description": "This forwards a request to the host. It does not publish content or grant permission.",
+        "confirmLabel": "Send request",
+        "cancelLabel": "Keep editing"
+      }
+    },
+    {
+      "id": "disabled-action",
+      "type": "action",
+      "label": "Unavailable action",
+      "actionRef": "unavailable",
+      "disabled": true,
+      "reason": "The reference host has not supplied this capability."
+    }
+  ]
+}

package/package.json

@@ -1,14 +1,45 @@
 {
   "name": "@mnstry/atelier",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.10",
   "private": false,
-  "description": "Local-first MNSTRY Atelier workspace for agentic authoring, graph projection, and dry-run runtime readiness.",
+  "description": "Local toolkit that turns a Git repository into an ontology-governed knowledge graph, enforcement layer, and runtime for people, agents, and tools. No telemetry or required hosted account; optional host-bound vault adapters.",
+  "keywords": [
+    "knowledge-graph",
+    "ontology",
+    "front-matter",
+    "local-first",
+    "json-schema",
+    "validation",
+    "provenance",
+    "governance",
+    "markdown",
+    "cli",
+    "agent-context",
+    "offline"
+  ],
   "type": "module",
   "bin": {
     "atelier": "bin/atelier.mjs",
     "mnstry-atelier": "bin/mnstry-atelier.mjs"
   },
   "exports": {
+    "./decisions": "./src/decisions/contracts.mjs",
+    "./contracts/atelier-decision-request.v1.schema.json": "./contracts/atelier-decision-request.v1.schema.json",
+    "./contracts/atelier-decision-result.v1.schema.json": "./contracts/atelier-decision-result.v1.schema.json",
+    "./presentation": "./src/ui/presentation/index.mjs",
+    "./presentation/browser": "./src/ui/presentation/browser.mjs",
+    "./presentation/native": "./src/ui/presentation/native.mjs",
+    "./contracts/atelier-presentation.v1.schema.json": "./contracts/atelier-presentation.v1.schema.json",
+    "./contracts/atelier-pane-presentation.v1.schema.json": "./contracts/atelier-pane-presentation.v1.schema.json",
+    "./coauthor": "./src/coauthor/session.mjs",
+    "./skills": "./src/skills/steward.mjs",
+    "./intake": "./src/intake/store.mjs",
+    "./contracts/atelier-intake.v1.schema.json": "./contracts/atelier-intake.v1.schema.json",
+    "./guides": "./src/guides/contracts.mjs",
+    "./contracts/atelier-guide.v1.schema.json": "./contracts/atelier-guide.v1.schema.json",
+    "./contracts/atelier-skill-steward.v1.schema.json": "./contracts/atelier-skill-steward.v1.schema.json",
+    "./coauthor/store": "./src/coauthor/store.mjs",
+    "./contracts/atelier-coauthor.v1.schema.json": "./contracts/atelier-coauthor.v1.schema.json",
     ".": "./src/index.mjs",
     "./cli": "./src/cli/run.mjs",
     "./project": "./src/project/config.mjs",
@@ -18,54 +49,99 @@
     "./readiness-protocols": "./src/readiness-protocols/bundled-pack.mjs",
     "./server": "./src/server/local-sidecar.mjs",
     "./harness": "./src/harness/context.mjs",
+    "./collaboration": "./src/collaboration/index.mjs",
     "./support": "./src/support/support-bundle.mjs",
     "./egress": "./src/egress/forbidden-egress.mjs",
+    "./disclosure": "./src/disclosure/content-scan.mjs",
     "./boundary": "./src/boundary/policy.mjs",
     "./upgrade": "./src/upgrade/upgrade.mjs",
     "./attestation": "./src/attestation/sign.mjs",
     "./extension-packs": "./src/extension-packs/loader.mjs",
     "./analysis/adapter": "./src/analysis/adapter.mjs",
+    "./runtime": "./src/runtime/supervisor.mjs",
+    "./runtime/git": "./src/runtime/git-adapter.mjs",
+    "./runtime/observation": "./src/runtime/repository-observation.mjs",
     "./export-contract": "./src/export/atelier-export-contract.mjs",
     "./dry-run": "./src/validate-atelier-export-dry-run.mjs",
     "./contracts/atelier-export.v1.schema.json": "./contracts/atelier-export.v1.schema.json",
-    "./fixtures/atelier-export/sample-studio-offer.v1.json": "./fixtures/atelier-export/sample-studio-offer.v1.json"
+    "./fixtures/atelier-export/sample-studio-offer.v1.json": "./fixtures/atelier-export/sample-studio-offer.v1.json",
+    "./vault": "./src/vault/index.mjs",
+    "./contracts/atelier-vault-publication.v1.schema.json": "./contracts/atelier-vault-publication.v1.schema.json",
+    "./vault/source": "./src/vault/source.mjs",
+    "./contracts/atelier-adoption-policy.v1.schema.json": "./contracts/atelier-adoption-policy.v1.schema.json",
+    "./contracts/atelier-migration.v2.schema.json": "./contracts/atelier-migration.v2.schema.json",
+    "./contracts/atelier-upgrade-plan.v2.schema.json": "./contracts/atelier-upgrade-plan.v2.schema.json",
+    "./contracts/atelier-upgrade-receipt.v1.schema.json": "./contracts/atelier-upgrade-receipt.v1.schema.json",
+    "./local-state": "./src/project/durable-state.mjs",
+    "./obsidian": "./src/runtime/obsidian/index.mjs",
+    "./obsidian/contracts": "./src/projection/obsidian/contracts.mjs",
+    "./obsidian/materialize": "./src/projection/obsidian/materialize/index.mjs",
+    "./obsidian/publication": "./src/projection/obsidian/publication/index.mjs",
+    "./obsidian/recovery": "./src/projection/obsidian/recovery/index.mjs",
+    "./obsidian/edits": "./src/projection/obsidian/edits/index.mjs",
+    "./obsidian/proposals": "./src/projection/obsidian/proposals/index.mjs",
+    "./obsidian/selection": "./src/projection/obsidian/selection-ui/index.mjs",
+    "./contracts/atelier-obsidian-acceptance-receipt.v1.schema.json": "./contracts/atelier-obsidian-acceptance-receipt.v1.schema.json",
+    "./contracts/atelier-obsidian-apply-policy.v1.schema.json": "./contracts/atelier-obsidian-apply-policy.v1.schema.json",
+    "./contracts/atelier-obsidian-corpus-profile.v1.schema.json": "./contracts/atelier-obsidian-corpus-profile.v1.schema.json",
+    "./contracts/atelier-obsidian-edit-operation.v1.schema.json": "./contracts/atelier-obsidian-edit-operation.v1.schema.json",
+    "./contracts/atelier-obsidian-ext-settings.v1.schema.json": "./contracts/atelier-obsidian-ext-settings.v1.schema.json",
+    "./contracts/atelier-obsidian-generation-manifest.v1.schema.json": "./contracts/atelier-obsidian-generation-manifest.v1.schema.json",
+    "./contracts/atelier-obsidian-proposal-receipt.v1.schema.json": "./contracts/atelier-obsidian-proposal-receipt.v1.schema.json",
+    "./contracts/atelier-obsidian-publication-journal.v1.schema.json": "./contracts/atelier-obsidian-publication-journal.v1.schema.json",
+    "./contracts/atelier-obsidian-scope.v1.schema.json": "./contracts/atelier-obsidian-scope.v1.schema.json",
+    "./contracts/atelier-obsidian-service-state.v1.schema.json": "./contracts/atelier-obsidian-service-state.v1.schema.json",
+    "./contracts/atelier-obsidian-source-snapshot.v1.schema.json": "./contracts/atelier-obsidian-source-snapshot.v1.schema.json"
   },
   "scripts": {
     "contract": "node src/check-atelier-export-contract.mjs",
     "dry-run": "node src/validate-atelier-export-dry-run.mjs fixtures/atelier-export/sample-studio-offer.v1.json",
     "test": "node --test test/*.test.mjs",
-    "syntax:check": "find bin src -name '*.mjs' -print0 | xargs -0 -n1 node --check",
+    "syntax:check": "node scripts/check-syntax.mjs",
     "graph:test": "node --test test/graph.test.mjs test/graph-knowledge-graph.test.mjs test/graph-determinism.test.mjs test/graph-source-formats.test.mjs",
     "project:test": "node --test test/project.test.mjs test/project-config.test.mjs test/projection-policy.test.mjs test/projection-alignment.test.mjs",
     "server:security:test": "node --test test/server.test.mjs test/server-security.test.mjs test/server-proposals.test.mjs",
     "browser:smoke": "node --test test/server.test.mjs",
+    "presentation:proof": "node scripts/prove-presentation-browser.mjs",
     "support-bundle:test": "node --test test/support-bundle.test.mjs test/support-egress-analysis.test.mjs",
     "egress:check": "node bin/atelier.mjs egress check",
     "readiness:test": "node --test test/readiness.test.mjs test/readiness-summary.test.mjs test/readiness-protocol-contract.test.mjs test/readiness-protocols.test.mjs test/readiness-protocol-runtime.test.mjs",
     "harness:test": "node --test test/harness.test.mjs test/harness-context.test.mjs",
-    "boundary:test": "node --test test/boundary-policy-contract.test.mjs test/boundary-guard.test.mjs",
+    "collaboration:test": "node --test test/collaboration-ledger.test.mjs test/server-proposals.test.mjs",
+    "sync:test": "node --test test/runtime-git-adapter.test.mjs test/runtime-observation.test.mjs test/runtime-supervisor.test.mjs",
+    "boundary:test": "node --test test/boundary-policy-contract.test.mjs test/boundary-content-rules.test.mjs test/boundary-guard.test.mjs",
+    "obsidian:test": "node --test --test-concurrency=1 test/obsidian-acceptance.test.mjs test/obsidian-contract.test.mjs test/obsidian-edits.test.mjs test/obsidian-maintenance.test.mjs test/obsidian-materialization.test.mjs test/obsidian-open.test.mjs test/obsidian-package.test.mjs test/obsidian-proposals.test.mjs test/obsidian-publication-feasibility.test.mjs test/obsidian-recovery.test.mjs",
     "upgrade:test": "node --test test/upgrade-contract.test.mjs test/upgrade.test.mjs",
     "release:audit": "node scripts/check-release-tarball.mjs",
+    "release:candidate": "node scripts/release-candidate.mjs",
     "repo:check": "node scripts/check-repo-disclosure.mjs",
     "migrations:check": "node scripts/check-breaking-migrations.mjs",
     "contract:compat": "node scripts/check-contract-compat.mjs",
+    "public-api:compat": "node scripts/check-public-api-compat.mjs",
+    "assurance:mutation-smoke": "node --test test/assurance-mutations.test.mjs",
     "consumer:smoke": "node scripts/consumer-smoke.mjs",
     "distribution:smoke": "node scripts/distribution-smoke.mjs",
-    "prepublishOnly": "npm run release:audit && npm run repo:check && npm run migrations:check && npm run contract:compat && npm run syntax:check && npm test && npm run consumer:smoke && npm run distribution:smoke"
+    "prepublishOnly": "npm run repo:check && npm run migrations:check && npm run contract:compat && npm run public-api:compat && npm run syntax:check && npm test && npm run assurance:mutation-smoke && npm run release:candidate"
   },
   "dependencies": {
     "ajv": "8.20.0",
-    "ajv-formats": "3.0.1"
+    "ajv-formats": "3.0.1",
+    "fast-uri": "3.1.7"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "esbuild": "0.25.12",
+    "playwright": "1.55.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "typescript": "5.8.3"
   },
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MNSTRY/atelier.git"
   },
-  "homepage": "https://mnstry.org",
+  "homepage": "https://docs.mnstry.ai/public-product/developers/atelier",
   "bugs": {
     "url": "https://github.com/MNSTRY/atelier/issues"
   },
@@ -93,6 +169,6 @@
     "access": "public"
   },
   "overrides": {
-    "fast-uri": "3.1.5"
+    "fast-uri": "3.1.7"
   }
 }

package/skills/claude/atelier-guided-coauthor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: atelier-guided-coauthor
+description: Guide an author through a selected packet in Codex, retaining private source-bound draft answers and resuming through the local Atelier coauthor CLI.
+---
+
+# Guided coauthor
+
+Use the installed `atelier coauthor` command, not a browser conversation service.
+The author chooses the packet and may read it normally without this workflow.
+
+Check the repository's instructions and local package first. Run
+`./node_modules/.bin/atelier coauthor --help` from the intended repository.
+Do not download another package if the command is unavailable. Explain that the
+installed version needs the coauthor capability and preserve ordinary packet review.
+
+## Start or resume
+
+- Require an existing Git workspace with ignored, untracked `.atelier-local/`.
+  Do not change global skills, sibling repositories, credentials or remote access.
+- Read the selected packet. Use consumer-owned field ids and workspace-relative
+  source references. Compute SHA-256 over each source file's exact UTF-8 bytes.
+  Send a `start` request containing `config: {id, fields}`; each field has
+  `id` and `source: {ref, digest}`. Packet structure stays in the consumer.
+- Requests are JSON on stdin; responses are JSON. Use an ignored request file
+  when needed, not shell interpolation of the author's text. Read the returned
+  state and revision. `read` takes `sessionId` and resumes retained history.
+- Ask one useful question at a time. Record the author's exact answer with an
+  `answer` event; events carry a unique `id`, `expectedRevision` and `type`.
+  Do not infer an answer or approval from silence.
+- If proposing edited wording, use `propose` and show the change. Wait for the
+  author's explicit confirmation before `confirm`. `reject` restores the
+  original. Even apparently stylistic rewrites need confirmation.
+- Send `save` only for the agreed draft. Say “saved as a private draft” only
+  after the command returns a saved receipt. The source packet is never edited.
+  `continueAfterSave: true` on an answer retains the author's advance intent;
+  otherwise `advance` is explicit.
+- `pause` and `resume` preserve the current phase. On restart, a `saving`
+  state may use `recover` to reconcile the pending private write. A
+  `recovery` state requires explicit `retry`, with one retry available.
+  Stop retrying when exhausted and retain all artifacts for inspection.
+
+## Boundaries
+
+Never submit store-owned receipt/failure events or fabricate persistence evidence.
+A stale source or revision is a visible conflict, not permission to overwrite it.
+Keep the old history and obtain a newly bound session for revised sources.
+Saved answers are proposals for later owner review, not publication, canonical
+acceptance, guide access, or a completed packet. No saved-answer undo is provided;
+do not erase history to simulate it. Summarize unresolved questions for the meeting.

package/skills/claude/atelier-guided-upgrade/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: atelier-guided-upgrade
+description: Prepare and explain an Atelier package upgrade in an isolated candidate, retain the owner decision, and apply only the approved effects. Use for owners asking to update an existing Atelier.
+---
+
+# Guided Atelier upgrade
+
+The default outcome is a reviewable candidate and an owner decision. Preserve the
+owner's actual request and existing scoped authority; no per-command approval
+loop is needed for actions already authorized. Preparation alone never authorizes
+changing the working installation, merging, publishing or restarting a service.
+
+## Establish the source and workspace
+
+Read the selected repository's instructions and upgrade procedure. Identify its
+actual installed scoped package, package-manager lock, Atelier lock, Git state,
+project roots, packs, overlays and running-service ownership. Resolve the package
+from that workspace (including a parent install); never use global Atelier,
+unscoped registry fallback or the first sibling checkout found on disk.
+Read `docs/guided-upgrades.md` and `docs/exact-upgrades.md` from the selected
+installed package when present. If an old install lacks this skill or commands,
+use the owner-selected new package's documentation only after verifying its
+source. Repository instructions and owner authority still govern.
+
+Select an exact release through a source already trusted by the owner. Record
+version, source commit when verified, artifact URL/integrity and the dependency
+lock. Mutable dist-tags are discovery hints, not final pins. A declaration in a
+lock or a digest supplied beside a download does not authenticate a publisher.
+An unpublished candidate must be labeled as such; use it only in an expressly
+selected rehearsal. Never invent a release or replace a pinned install with main.
+
+## Prepare without disturbing authoring
+
+Use a separate candidate with an identified base. Preserve dirty source and
+private answers; do not stash, reset, clean, stop services or commit another
+writer's edits to create eligibility. If using a snapshot of current edits,
+record and recheck its exact manifest; it is a snapshot, not an adopted commit.
+Ignored answers, browser storage and runtime credentials are not in a Git clone.
+Record that gap without importing them into a public report or projection.
+
+Stage the selected package using the owner's package manager and lock procedure,
+with lifecycle scripts disabled; investigate any required scripts before execution.
+Verify the resolved identity and inventory before running its commands. Inspect
+migration/compatibility effects before rewriting the old Atelier lock. Retain the
+old lock and all lineage. Keep installation changes distinct from generated files.
+
+Check exact-plan eligibility: Linux/macOS, one managed repository at `.`, config
+and workspace at its root, linked candidate worktree, clean state and supported
+Git settings. Packs, overlays and other unsupported participants require the
+repository's explicit operator procedure. Do not broaden graph roots, remove
+policies or disable filters/hooks to force eligibility. Never silently fall back
+to legacy `upgrade --apply`; it has different guarantees.
+
+For an eligible candidate, prepare `upgrade plan --save`, then use
+`upgrade explain --plan SAVED_PLAN_PATH` (JSON) and `--format markdown` (owner
+view). Invoke the verified installed binary with the explicit project path.
+Inspect `bindingsCurrent` and blockers even when the explanation exits zero.
+Keep source/pin/policy installation commits and the saved projection plan separate.
+For an operator procedure, retain an exact before/after file manifest and named
+commands instead; do not call it an exact-plan transaction or invent its digest.
+
+## Explain and retain consent
+
+Present the local benefit, exact target, changed files, preserved customizations,
+checks, known limits, recovery coverage and proposed effects. Show installation,
+local commit, merge, publication and activation separately. Ask one concrete
+question covering the effects that still need authority. A permission to prepare
+or a generic earlier “go” does not approve a newly introduced material effect.
+A prior explicit approval of this same current plan and effects remains valid.
+
+Retain a new decision record in ignored, untracked
+`.atelier-local/guided-upgrades/` (or a private sibling evidence directory):
+`kind: owner-decision`, report and plan/manifest SHA-256, candidate base, target
+identity, exact owner words, conversation reference, observation time, decision
+(approve/defer/decline), allowed effects, and
+`humanApprovalAuthenticated: false`, `recordedBy: agent`.
+Do not invent identity, words, references or approvals; missing provenance is a
+reported gap. This is an agent-attested record, not an authenticated signature or
+an execution grant. Keep existing records immutable. Silence conveys no consent.
+
+## Apply, validate and close
+
+After actual approval, use the saved path and exact confirmation digest literally.
+Recheck bindings; changed or expired plans require a fresh explanation and any
+newly necessary decision. A consumed plan is inspected, never replayed.
+Run the repository's documented acceptance checks and inspect the actual diff.
+Only a verified terminal transaction receipt means a candidate commit completed.
+Honor existing hooks and keep source/answer files within their ownership boundary.
+An operator procedure has its own validation evidence, not a transaction receipt.
+
+Continue authorized merge/activation steps only when included in the owner's
+scope. Report prepared, installed-in-candidate, committed, merged and running as
+separate observed states. A local preview passing is not recipient acceptance.
+On failure, preserve the candidate, backups and receipts; explain what changed
+and the next safe action. Recovery inspection does not automatically restore
+files or reset Git. Do not publish source, restart an existing service or advance
+an author's workflow phase merely because upgrade checks passed.

package/skills/claude/atelier-local-service/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: atelier-local-service
+description: Build or repair a durable loopback-only authoring, review, or preview service in an Atelier-backed repository when local state must survive agent commands and fail safely.
+---
+
+# Atelier local service
+
+Use this skill for a consumer-owned service that persists repository-backed
+local state. Do not use it to change `atelier dev` itself or to install an
+operating-system service without explicit authorization.
+
+Read `docs/local-services.md` from the installed Atelier package or source
+checkout before changing lifecycle code.
+
+## Boundary first
+
+Separate the portable mechanism from the consumer adapter before editing:
+
+- Atelier invariants: loopback binding, proven ownership, exact stop, ignored
+  mode-0600 state, atomic writes, recoverable browser failure, and tests.
+- Consumer details: service identity, port, commands, paths, schema, content,
+  and user-facing language.
+
+Never promote consumer names, content, structures, examples, or local paths
+into Atelier. Public tests use invented fixtures.
+
+## Workflow
+
+1. Inspect the existing server, process owner, port, persistence file,
+   `.gitignore`, health route, save handler, and tests. Preserve the live draft
+   before restarting anything.
+2. Expose repository-owned `start`, `status`, and `stop` commands. Start may
+   detach only because the user needs continuity beyond the launching command.
+3. Bind to loopback. Pair a random runtime identifier with the PID in both the
+   private runtime record and health response. Refuse unowned listeners.
+4. Keep drafts, runtime metadata, and operational logs ignored and owner-only.
+   Do not commit live authoring state.
+5. Make the UI retain the draft when the service disappears. Show the exact
+   restart command, snapshot export, and Retry path instead of a generic error.
+6. Serialize writes without permanently rejecting the queue after one failed
+   operation. Keep conflicts and invalid state fail-closed.
+7. Prove lifecycle ownership, server-loss recovery, later-save recovery,
+   permissions, ignore coverage, and fresh-checkout discoverability.
+
+Do not claim durability from a passing request alone. Report separately:
+saved file truth, managed-process truth, browser recovery truth, and the
+remaining OS-restart boundary.