@mnstry/atelier 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/coauthor-session.md

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

package/docs/connected-composition.md

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

package/docs/decisions.md

@@ -0,0 +1,167 @@
+# Typed decision proposals
+
+The optional `@mnstry/atelier/decisions` API validates finite questions and
+their proposed answers. It performs no provider calls, credential lookup,
+source mutation, or acceptance. A consuming host supplies the provider and
+independently checks authorization before disclosure or use.
+
+For a development pilot, pin the reviewed source commit or its verified
+tarball. Check that the installed package exports `./decisions`; an older
+published alpha may not contain this API. A source merge does not publish a
+new registry version.
+
+This API is suitable for a small, explicit choice, an ordered score, or a
+Boolean probability. It does not extract missing evidence or generate prose.
+The fixtures describe an invented reading room; their answers and usage are
+synthetic examples, not model evaluation results.
+
+```js
+import {
+  decisionRequestDigest,
+  validateDecisionRequest,
+  validateDecisionResult,
+} from '@mnstry/atelier/decisions'
+
+const requestCheck = validateDecisionRequest(request)
+if (!requestCheck.ok) throw new Error('Invalid decision request')
+const digest = decisionRequestDigest(request)
+
+// The host obtains a result under its own provider and disclosure policy.
+const resultCheck = validateDecisionResult(request, result)
+if (!resultCheck.ok) throw new Error('Invalid decision result')
+```
+
+The adjacent TypeScript declarations export `DecisionRequest`,
+`DecisionQuestion`, `DecisionResult`, `DecisionAnswer`, `DecisionScope`,
+`DecisionUsage`, and `DecisionValidation`, including the individual question
+and answer variants. Runtime validation remains required for external data.
+
+For hosts that need only question and answer validation, use
+`validateDecisionAnswers(questions, answers)`. It checks bounded plain JSON,
+question structure, exact answer keys and types, probability distributions,
+and score expectations. It accepts no state, computes no hash, performs no
+provider execution, and writes nothing. The host supplies its own transient
+request binding and enforces its privacy policy.
+
+```js
+import { validateDecisionAnswers } from '@mnstry/atelier/decisions'
+
+const answerCheck = validateDecisionAnswers(questions, answers)
+if (!answerCheck.ok) throw new Error('Invalid decision answers')
+```
+
+This separate API checks evidence reference syntax, uniqueness and bounds,
+but cannot establish membership in a source snapshot that it has not received.
+The request and result validators still enforce that membership. A successful
+answer check establishes neither authorization nor semantic correctness.
+
+## Requests
+
+`atelier-decision-request@v1` records a request ID, task, rubric version,
+host-reported scope, state, evidence references, and questions. The
+`scope.workspaceId` and `scope.authorizationRef` fields bind the assessment to
+the host's reported snapshot. They do not authenticate a caller, prove
+consent, or grant access. The host must revalidate current permissions and
+revocation before sending data or acting on a cached result.
+
+Each question includes instructions and at least one `evidenceIds` entry
+referring to the request's evidence. Evidence identities are unique; their
+`sourceRef` strings are opaque references preserved for the host. Validation
+does not fetch them or prove that the state faithfully represents a source.
+
+| Question | Criteria | Answer |
+| --- | --- | --- |
+| `choice` | A map of 2–64 option IDs to descriptions | A selected option, complete probability map, and provider confidence statistic |
+| `score` | An ordered list of 2–10 descriptions | A zero-index weighted expectation, complete probability list, and provider confidence statistic |
+| `boolean` | Explicit `true` and `false` descriptions | A probability between zero and one |
+
+Identifiers are 1–128 ASCII characters, beginning with a letter or digit and
+continuing with letters, digits, `.`, `_`, `:`, or `-`. The names `__proto__`,
+`constructor`, and `prototype` are refused as object keys and identifiers.
+State and descriptions support Unicode; validation does not normalize text.
+
+Requests are limited to 64 questions, 256 evidence entries, 32,000 state
+characters, 4,000 instruction characters per question, 2,000 characters per
+criterion, and 2,048 characters per source reference. String limits count
+Unicode code points. Empty state is allowed so the host can record an
+insufficient-evidence abstention; instructions and descriptions must contain
+non-whitespace text.
+
+## Results and integrity
+
+`atelier-decision-result@v1` copies the request ID, task, rubric version and
+scope, and carries `requestDigest`, provider ID, concrete model name,
+elapsed milliseconds, and usage. Token counts are nonnegative safe integers;
+`usage: null` records unavailable usage without treating it as zero.
+
+`authority` is always `proposal-only`. `mode` is `shadow` or `advisory`;
+neither value grants execution authority. An `assessed` result contains
+exactly the requested answer keys and types. An `abstained` result contains
+an empty answer map and one explicit reason: `insufficient-evidence`,
+`ambiguous`, `no-match`, `budget-exhausted`, `provider-unavailable`, `timeout`,
+`invalid-response`, or `unauthorized`.
+
+The validator checks that distributions sum to one within `1e-6`, a chosen
+option has maximum probability, and a score equals its zero-index weighted
+expectation within `1e-6`. Tied maximum choices are valid. Boolean answers
+have no confidence field. Confidence is a provider statistic, not measured
+semantic correctness; a structurally valid high-confidence answer can still
+be wrong. The host owns evaluation data, calibrated thresholds, escalation,
+and fallback behavior. The host must also compare the recorded model with
+its requested concrete model pin; the request contract does not prescribe a
+provider or model.
+
+`decisionRequestDigest` returns lowercase SHA-256 over canonical JSON with
+object keys recursively sorted in JavaScript string order. Array order and
+exact Unicode content are retained. It includes the full request, scope,
+evidence, rubric, and optional extensions. Reordering object insertion does
+not change the digest; changing any represented value does. This is local
+integrity evidence, not a signature or proof of provenance. Invalid requests
+throw a generic `TypeError`; validators return `{ ok, errors }` without
+echoing source text, unknown field names, or provider response content.
+
+Content hashes can themselves be sensitive. A host whose policy forbids
+hashing a passage must use its own transient request binding instead of this
+digest-bearing envelope. It can reuse the question and answer types without
+calling `decisionRequestDigest` or retaining a full request. The public
+contract does not override the host's privacy policy.
+
+## Closed fields and extensions
+
+The standalone JSON Schemas are
+`atelier-decision-request.v1.schema.json` and
+`atelier-decision-result.v1.schema.json`. They validate static shape. Use the
+JavaScript validator as well for request binding, evidence relationships,
+distribution semantics, and bounded in-process JSON.
+
+As with other Atelier contracts, the roots allow optional
+`contractVersion: "1.0.0"`, and closed objects allow an optional object-valued
+`ext`. Unknown first-class fields are refused. Namespaced extension members
+are inert metadata: consumers must ignore unrecognized members and must
+never derive authority from them. Dynamic question, choice and answer maps
+contain only their declared entries; they have no reserved metadata entry.
+
+Both requests and results, including extensions, are limited to 16,777,216
+canonical JSON bytes, 100,000 values, and 32 levels of nesting below the root.
+Cycles, symbols, sparse arrays, accessors, non-finite numbers, undefined
+values and custom prototypes are refused. Plain objects with a null
+prototype are accepted. No input is mutated.
+
+## Host integration
+
+1. Build bounded questions from already authorized evidence. Preserve all
+   source passages and coverage independently of a proposed prioritization.
+2. Validate the request, then check the host's current consent, destination,
+   concrete model pin, input limit, evaluation budget and timeout policy.
+3. Call a provider through the host adapter. Keep credentials, private
+   criteria, raw responses and provider execution outside the public kit.
+4. Normalize and validate the result against the exact request. Retain full
+   distributions and unknown usage; represent failures as explicit
+   abstentions without accepting partial answer sets.
+5. Compare shadow results with an independently labeled evaluation set.
+   Enable an advisory consumer only after task-specific acceptance. Keep the
+   host's existing behavior as the fallback and recheck authorization on
+   cache access.
+
+This module does not change the existing analysis adapter's default-disabled
+execution policy or accept a model proposal as an authored fact.

package/docs/exact-upgrades.md

@@ -0,0 +1,159 @@
+# Local exact-plan upgrades
+
+The explicit `atelier upgrade plan/apply/status/recover` commands prepare a
+local candidate from an already installed Atelier executor. They preserve an
+adopter's source branch and configuration, show the exact changes, and retain
+local evidence of what was selected and what Git actually committed.
+
+Execution in this first slice requires Linux or macOS with working directory
+fsync. Other hosts, including native Windows, refuse before transaction state
+creation; existing Atelier commands remain available. The platform refusal is
+tested separately from the POSIX execution scenarios.
+
+This first slice supports **one configuration repository in a linked Git
+worktree**, with its project config and workspace at the root. Its single
+managed repo must point to `.`. It refreshes the lock, graph, HTML projection,
+manifest and readiness output. Generated paths must be distinct paths within
+`atelier-output/`. Distribution branding is retained. External packs, local
+overlays, private readiness runs, submodules, sparse checkouts, attribute/filter
+transformations and runtime/alignment participants are refused. These limits
+are explicit eligibility checks, not assurances about unsupported setups.
+
+There is no package installation, network discovery, hook replacement, runtime
+activation, or automatic policy mode. Existing legacy `upgrade --apply` remains
+a separate workflow; it does not acquire these transaction guarantees.
+
+## Enroll and prepare
+
+Create a dedicated candidate worktree using your usual Git workflow, then add
+and commit `atelier.adoption-policy.json` there:
+
+```json
+{
+  "schema": "mnstry.atelier-adoption-policy@v1",
+  "enabled": true,
+  "mode": "manual-exact-plan",
+  "maxAgeSeconds": 86400,
+  "recoveryCoverage": "local-only",
+  "allowedEffects": ["lock-and-projections", "git-commit"]
+}
+```
+
+Ignore `.atelier-local/` and keep every file beneath it untracked. Start with a
+clean index and worktree. From the candidate worktree:
+
+```sh
+atelier upgrade plan --save --project ./atelier.project.json
+```
+
+The result names a private saved plan and its `sha256:` confirmation digest.
+Inspect its `writes`: concrete paths, ownership, old/new byte digests and modes,
+and the proposed bytes in base64. `readSet` inventories the entire enrolled
+repository except Git administration and private local state. The plan also
+binds the repository identity, HEAD, branch, policy, Git executable,
+configuration, Git auxiliary ignore/attribute files, hook directory and files, executor and imported dependency bytes,
+and a fixed expiry. Default lifetime is 24 hours; policy may shorten it.
+The Git fingerprint covers the transaction's selected executable. Legacy
+builders also invoke Git from `PATH`; use the same executable there when
+setting `ATELIER_GIT_PATH`. Cross-host output ordering is not guaranteed.
+Executor checkout metadata may affect generated lock provenance; the saved
+plan binds the resulting bytes rather than promising identical regeneration.
+
+Inherited `GIT_*` overrides such as an IDE's `GIT_ASKPASS` are refused (apart
+from the documented prompt, pager and optional-lock controls). Prepare from
+an environment without those overrides. Repository, global and system Git
+attribute files must be absent or empty for this slice.
+
+Generation uses an isolated private preparation directory and the existing
+builders. Only five registered output paths can be written, and a complete
+before/after inventory checks that boundary. The executor then saves those
+bytes; application does not recalculate or silently replace the selected plan.
+This is a bounded trusted executor, not a sandbox for arbitrary migration code.
+The generated readiness JSON retains absolute local graph and projection paths,
+which may include the account name. Inspect those committed bytes before sharing
+the candidate branch; generating a candidate does not authorize publication.
+
+## Apply the reviewed bytes
+
+Use `atelier upgrade explain --plan SAVED_PLAN_PATH --format markdown` to read
+the verified plan's effects, expiry and consent limits. The default JSON format
+contains the same report. Explanation is read-only and never grants approval.
+See [guided upgrades](guided-upgrades.md) for the owner-agent workflow.
+
+Use the returned path and digest literally:
+
+```sh
+atelier upgrade apply --plan SAVED_PLAN_PATH --confirm sha256:REVIEWED_DIGEST --project ./atelier.project.json
+```
+
+The digest selects content; it is not an authenticated human signature. Host
+permissions must establish any stronger authority. The command takes an
+exclusive local writer lease, checks current bindings before mutation and at
+safe boundaries, records original bytes and write intents, writes only expected
+preimages, stages only the frozen paths, and runs the existing commit hooks.
+No commit uses `--no-verify`. Hook execution is existing adopter code with its
+normal host privileges, not a new sandbox or a promise of no hook side effects.
+Relevant hook changes invalidate the plan; files or executables that hooks
+consult outside their directory are not transitively fingerprinted.
+Git commit has a 30-second execution budget. A timeout is conservatively
+`recovery-required`, since a hook may already have acted; this budget is not
+a guarantee that all hook descendants terminate within 30 seconds.
+
+A successful Git exit is insufficient: the commit's parent, tree and message,
+staged blobs, branch and worktree must match. A refused commit retains its index
+and worktree as `commit-refused`. Unexpected changes become `recovery-required`.
+Neither case causes an automatic retry, reset, hook bypass or success claim.
+Every accepted attempt consumes the plan, including an interrupted attempt.
+
+## Status and recovery evidence
+
+```sh
+atelier upgrade status --operation OPERATION_ID --project ./atelier.project.json
+atelier upgrade recover --operation OPERATION_ID --dry-run --project ./atelier.project.json
+```
+
+The operation ID is the hexadecimal part of the plan digest. Events live in
+`.atelier-local/upgrades/operations/OPERATION_ID/events/`, with original bytes in
+`backups/`. Events are exclusive, fsynced publications with sequence numbers,
+previous-event digests and verified rereads. Missing, truncated or altered events
+refuse success. This is local integrity evidence; a host owner who can replace
+all records can rewrite a chain. It is not externally authenticated provenance.
+
+Only a verified terminal receipt asserts completion. The v1 lock retains prior
+migration history, template lineage and successful-upgrade metadata. Its success
+fields deliberately lag the new receipt; the command never writes the hash of
+an uncreated commit into that commit. No automatic metadata refresh is shipped.
+
+An interruption after Git commits but before the terminal event remains
+`recovery-required`, even when the commit exists. Recovery dry-run reports
+current HEAD/index evidence, safely restorable bytes and conflicts. Subsequent
+user edits and any moved HEAD prevent automatic restoration. This release offers
+**no recovery mutation**: restoring files or reverting a commit requires a
+separately reviewed operation with current authority. It never resets history.
+
+A crash may leave the writer lease in place. Inspect its owner and verify that
+process has stopped before separately handling the stale lease; elapsed time
+alone never releases it. Status and recovery inspection remain available.
+A crash during preparation can also leave a `prepare-*` scratch directory
+under `.atelier-local/upgrades/`. Further preparation and application refuse
+with a stale-preparation diagnostic. Verify the writer has stopped and inspect
+the directory before separately removing only that abandoned scratch directory.
+The command does not delete it automatically or remove plans, receipts or backups.
+
+Evidence has no automatic deletion. Inventory limits (4,096 files, 64 MiB) and a
+32 MiB retained-state admission threshold and 8 MiB saved-plan limit bound this small-workspace slice.
+Exhaustion refuses another operation; export and verify evidence before any
+separate retention maintenance. Ignored state is not backed up or inherited by
+another clone. Enrollment explicitly acknowledges local-only recovery.
+
+## Provenance and acceptance boundaries
+
+The plan pins installed executor and dependency bytes. It does not authenticate
+an upstream publisher or verify a newly downloaded release. Release discovery,
+authenticated artifact intake, dependency installation, multi-repository
+transactions and standing automatic consent remain separate future work.
+
+A completed transaction means a prepared local candidate commit. It does not
+mean a merged upstream change, CI acceptance, adoption in another workspace,
+published package or activated service. Use the adopter's normal review and
+landing process to accept the candidate.

package/docs/extension-pack-lifecycle.md

@@ -0,0 +1,33 @@
+# Pack compatibility for evidence-bound review
+
+The closed v1 pack format remains unchanged. An adapter can declare a separate
+`atelier-pack-lifecycle@v1` file through
+`ext["mnstry.atelier"].extensionPackLifecycle`. Each entry binds the pack ID,
+version and content digest to `compatibleRootVersions`, an explicit finite set
+of approved root versions. This conservative compatibility range does not infer
+SemVer compatibility or silently approve a future root version.
+
+`atelier review packs` reports admission. `--migration-plan` returns a dry-run
+report referencing the existing extension-pack upgrade registry and its checks.
+A declaration can name an available registry `migrationId`; unknown migrations
+fail qualification. Pack loading never executes extension code or installs
+packages. An owner reviews replacement term/protocol meaning, retains prior
+content, updates declarations and locks, and uses the existing upgrade workflow.
+The plan itself writes nothing. A fresh run is required after a change.
+
+| Root/pack state | Historical inspection | New evidence-bound run |
+| --- | --- | --- |
+| Current root explicitly approved; exact active pack | Pinned snapshot | Admitted |
+| Exact deprecated pack, root approved | Pinned snapshot; replacement shown | Admitted with deprecated status |
+| Retired, wrong digest/version or unapproved root | Pinned snapshot | Refused |
+| Legacy pack without lifecycle declaration | Existing readers remain usable | Unqualified; refused |
+| No custom packs | Bundled snapshot | Admitted |
+| Old root predating this feature | Its legacy readers only | No new review protocol supplied by that root |
+
+A snapshot contains the actual protocol and source identity used originally.
+Historical inspection does not load today's replacement as yesterday's method.
+Migration IDs describe reviewed owner operations, not autonomous reinterpretation
+or approval. For rollback restore the previous package, pack declarations and
+lock; retain the evidence and contribution ledgers. Existing legacy readiness
+execution remains compatible and does not acquire exact-review qualification
+merely because it can still read the pack.

package/docs/guided-upgrades.md

@@ -0,0 +1,99 @@
+# Upgrade with your agent
+
+Ask your agent to prepare an upgrade using the bundled
+`atelier-guided-upgrade` skill. It is available in both packaged skill surfaces.
+For an older installation, the operator first selects and verifies the new
+package. Reading its skill is not permission to install or execute it in your
+working Atelier.
+
+> Prepare an Atelier upgrade in an isolated candidate. Preserve my authored
+> work, local customizations and existing approvals. Identify an exact trusted
+> release, explain its effect here and run the appropriate checks. Show me what
+> is ready and ask before applying changes to my working installation, merging
+> or restarting services. Report unsupported configurations explicitly.
+
+## What the owner reviews
+
+The agent prepares a short explanation with inspectable evidence:
+
+| Item | Required information |
+| --- | --- |
+| Source | Old and selected package identities, source commit when verified, artifact integrity, dependency lock and trust source. |
+| Local impact | Benefit, actual changed paths, preserved customizations, migrations and unsupported participants. |
+| Validation | Exact candidate tested, commands, results, skipped coverage and remaining acceptance checks. |
+| Consent | The specific installation, commit, merge or activation effects requested; prior applicable authority and any new decision. |
+| Recovery | What remains untouched, retained backups and conflicts; whether restoration is manual. |
+| Outcome | Prepared, installed in candidate, committed, merged, running and owner-accepted are distinct states. |
+
+Do not attach private authored content to an upstream issue or public release.
+Even generated readiness output can contain account paths. Retain full evidence
+privately and publish only an explicitly approved summary.
+
+## Exact-plan explanation
+
+After selecting/installing the executor in an eligible candidate, follow
+[exact upgrades](exact-upgrades.md) for enrollment and preparation. Use the
+verified installed binary (these examples assume a root-local npm install):
+
+```sh
+./node_modules/.bin/atelier upgrade plan --save --project ./atelier.project.json
+./node_modules/.bin/atelier upgrade explain --plan SAVED_PLAN_PATH --project ./atelier.project.json
+./node_modules/.bin/atelier upgrade explain --plan SAVED_PLAN_PATH --format markdown --project ./atelier.project.json
+```
+
+Both explanations derive from the same verified saved plan. They expose paths,
+before/after hashes, executor evidence, expiry and consent limits, without
+printing the proposed base64 contents. Inspect the saved bytes separately.
+The command is read-only: it neither records consent nor regenerates output.
+JSON `bindingsCurrent: false` and `blockers` identify observed staleness even
+when explanation succeeds. `bindingsCurrent: true` is not a reservation or a
+complete application admission; apply performs its full checks again.
+
+The owner's decision must bind the displayed plan and effects. An agent records
+the exact words and conversation reference privately with the report digest,
+candidate, target and decision. Use `humanApprovalAuthenticated: false` and
+`recordedBy: agent`; the record is an attestation of the conversation, not a
+cryptographic human signature. Hashes identify content and detect changes. A
+trusted host/harness must enforce any stronger approval boundary. Merely
+writing an approval-looking JSON file grants no authority.
+
+## Existing workspaces outside the first slice
+
+A managed subdirectory, multiple repositories, external packs, overlays or an
+unsupported host require a separate operator procedure. Keep those boundaries;
+changing a graph root to `.` can expose previously excluded material. Never
+remove a guard to make the exact planner accept a workspace.
+
+Use the consuming repository's documented procedure, retaining the old source
+and lock history, an exact dependency pin and a before/after manifest. Label the
+result as an operator-prepared candidate. The exact transaction receipt and its
+guarantees do not apply. If no procedure exists, prepare a migration proposal and
+stop before application. The legacy flag-based apply command is not an automatic
+substitute for the saved-plan workflow.
+
+An isolated snapshot may preserve active local edits for a rehearsal, provided
+its manifest is stable and the original remains untouched. It does not settle
+ownership of those edits or include ignored answer history. Reconcile with the
+active writer before eventual adoption. Test reopening/resuming owned state at
+the actual recipient before claiming owner acceptance.
+
+## Release and pilot checklist
+
+Maintainers retain a release candidate with `ATELIER_RELEASE_OUTPUT_DIR` and
+`npm run prepublishOnly`: one archive is audited and exercised by installed
+consumer and distribution smokes. This proves the candidate artifact, not that
+it was published or that an adopter trusts its publisher. Include the candidate
+commit/tree, artifact digest, release notes, supported runtimes, migration limits
+and original review qualifications in the release handoff.
+
+The publishing workflow rebuilds and verifies its own retained artifact after
+the release commit lands. Its published integrity is the consumer's installation
+reference; do not substitute a different local tarball's digest. Publication
+uses a separately authorized version tag. An alpha version in source is not
+evidence that npm already contains it.
+
+Pilot one explicitly selected workspace: inspect, prepare separately, explain,
+record a real decision, apply the authorized effects, verify and confirm the
+owner can continue their work. Candidate tests alone do not complete that last
+step. Background discovery, unattended installation and automatic recovery are
+not provided by this workflow.