@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/docs/knowledge-health/quickstart.md

@@ -1,62 +1,29 @@
-# Follow the workshop finding
+# Use the public workshop profile
 
-This is the primary entry for the composed workshop. The release owner must
-first bind and verify its exact package version, exports, template and guided
-host. The functions below are implemented in the source proposal. They are
-absent from the published `0.2.0-alpha.12` baseline.
+Use a pinned package version that includes this profile and verify its integrity.
+Rehearse that exact installation and receiving browser before a participant
+session. Git must be on PATH; the installed package's engine range governs Node.
 
-## Install the verified version
-
-The facilitator supplies the exact rehearsed version and package integrity.
-Create an empty consumer directory, then use that version:
+In an empty consumer directory, install that version and create a new workshop:
 
 ```sh
-: "${ATELIER_DEVDAY_VERSION:?Set the exact version supplied by the release owner}"
 npm install --save-exact "@mnstry/atelier@$ATELIER_DEVDAY_VERSION"
 ```
 
-Initialize the package's shipped workshop fixture through its normal export:
-
 ```js
 import { initializeKnowledgeHealthWorkshop, assessKnowledgeHealthWorkshop }
-  from '@mnstry/atelier/knowledge-health';
-
-const workspaceRoot = initializeKnowledgeHealthWorkshop('./workshop');
-const before = assessKnowledgeHealthWorkshop({ workspaceRoot });
-console.log(before.assessment, before.retrievalEvaluation);
+  from '@mnstry/atelier/knowledge-health'
+const workspaceRoot = initializeKnowledgeHealthWorkshop('./workshop')
+const before = assessKnowledgeHealthWorkshop({ workspaceRoot })
+console.log(before.assessment, before.retrievalEvaluation)
 ```
 
-An existing destination is refused. The example has two public invented
-sources, `devday:checklist` and `devday:workshop`, and the planned relationship
-`checklist-workshop`. The separate [pilot example](assessment/quickstart.md)
-uses `demo:checklist` and `checklist-pilot`.
-
-## Contribute and follow the owning correction
-
-Use the release's verified existing guided host to follow the
-[workshop exercise](exercise.md). Keep your words and the separate
-interpretation, choose how to retain them, and verify both native readbacks.
-The [API guide](api.md) explains the existing adapter/caller join. The host
-keeps the original choice ID and full finding reference during recovery.
-
-Preview the example declaration before applying it to a working draft. Save
-and reopen that draft through its owning route. Its source remains unchanged
-until the disposable source owner edits the exact declaration and reads it
-back. Rerun `assessKnowledgeHealthWorkshop` against the current source and its
-actual binding/revisions.
-
-Read both outputs. The relationship check may clear while
-`retrievalEvaluation` still lists `devday:checklist` as stale. Keep the frozen
-expected evidence and earlier contribution context. The source owner explicitly
-refreshes the relevant expected-evidence hash, then reruns the same assessment
-and question evaluation. An empty stale list does not establish semantic or
-human acceptance.
-
-## Open the existing host
+The initializer refuses an existing destination. This workshop uses
+`devday:checklist` and `checklist-workshop`; the separate
+[assessment exercise](assessment/quickstart.md) uses `demo:checklist` and
+`checklist-pilot`. The assessment helper writes no source or expected evidence.
 
-The inspected Foundation source supports this launch sequence after graph and
-projection output have been built with the same project. Run it from the
-consumer that contains the exact installed version:
+Build its graph and projection, then start the existing loopback host:
 
 ```sh
 npx --no-install atelier graph --project ./workshop/atelier.project.json
@@ -64,31 +31,86 @@ npx --no-install atelier build --project ./workshop/atelier.project.json
 npx --no-install atelier server --knowledge --project ./workshop/atelier.project.json --port=0
 ```
 
-Open the printed loopback URL ending in `/knowledge`. Port zero asks the host
-for an available port. The server refuses a missing projection output or
-`atelier.manifest.json`; its source diagnostic names graph and build as the
-prerequisites. These commands are supported by the inspected source. Their
-execution against the workshop and the actual released package remains to be
-qualified by its owners.
-
-The current `/knowledge` source hosts Knowledge sessions and an answer field.
-Foundation must still bind the workshop assessment and existing native
-adapter/caller/R5 contribution, disposition and selected-draft ports to that
-host. Merely opening it does not supply those joins. The existing
-`knowledge-workspace` template contains a different equipment-loan example;
-it must not be mistaken for the shipped workshop fixture initialized above.
-Keep the exact words, separate interpretation, original choice ID and pending
-record through recovery. Retention and selected-draft application use the
-existing owning write boundary and independent readback.
-
-The owning release must qualify the launch sequence, declared exports, actual
-native input and lifecycle before participants use this exercise. Runtime
-controls require their existing licensed host allocation; private source
-snapshots, bundles and local state are excluded from the npm payload.
-
-For preparation and recovery, see [support](support.md),
-[facilitator guidance](facilitator.md) and the
-[Assessment API details](assessment/api.md). The
-[Proof baseline guide](devday/quickstart.md) remains historical alpha12 guidance.
-Independent Proof owns its candidate-specific successor and the actual
-keyboard, focus, undo, input-method, recovery and participant observations.
+Open the printed URL at `/knowledge`. The Workshop profile appears when the
+current invented checklist has the actionable missing supporting relationship.
+Read the finding and both sources before responding.
+
+## Retain your response
+
+1. Record your original words and save the private draft.
+2. Record a separate interpretation. **Propose revised wording** shows the
+   confirmation step; confirm or keep the original wording, then save.
+3. Enter one exact choice yourself: `note`, `perspective-only`, `disagreement`
+   or `pause`. Save it. These responses retain different meanings, and a
+   proposed choice is refused.
+
+**Review** is a separate, optional action. It becomes available after all three
+fields are saved and read back. It opens a second session with one field:
+enter `["devday:workshop"]` there and save it to select the draft declaration.
+See [participant response](participant-response.md).
+
+The **Pause** control pauses the session and retains its existing state. A
+saved `pause` choice records your response without selecting a source edit.
+
+The same native text field stays available while a request is pending. Later
+wording and composition remain unsaved until you record them. Export the
+snapshot before closing the tab when wording or a request remains unresolved.
+Closed-tab browser recovery, native undo and keyboard behavior still require
+qualification in the receiving browser.
+
+If a reply is lost, **Retry exact request** first looks up its original ID in
+durable history. A known retained event is read back without another append.
+An unknown outcome retains the request for inspection. A source change leaves
+earlier history readable and refuses new writes to the old session.
+
+## Review a source-owner handoff
+
+After the selected draft is saved in the Review session, **Prepare
+source-owner handoff** reads both sessions back from durable storage and
+retains one copy-only proposal in the existing local proposal store. The
+proposal holds the original words, interpretation, choice, selected
+declaration, six finding reference fields, source, anchor, read set and the
+saved draft receipts, unshortened. The response names the proposal ID. Read the
+proposal back at `/api/proposals/<id>` or on the `/proposals` page.
+
+Repeating the request looks up the original saved receipt before anything is
+appended. The same handoff returns the same proposal. A different value under
+the same receipt is refused. If the source has changed since, a proposal that
+was already retained is still read back, and nothing new is retained. A
+missing or altered saved draft, or a handoff too large to keep whole, is
+refused. An unreadable proposal ledger is reported as unknown: inspect it, then
+repeat the same request. A retained proposal has status `proposed`. It is not a
+review decision and it applies no source change.
+
+The normal Knowledge host has no source-apply endpoint. A source owner may
+review and edit the exact declaration using normal repository editing, then
+read it back and reassess:
+
+```js
+import { createPublicWorkshopComposition } from '@mnstry/atelier/knowledge-health'
+const workshop = createPublicWorkshopComposition({ workspaceRoot: './workshop' })
+console.log(workshop.inspect())
+console.log(workshop.read(savedSessionId))
+```
+
+Keep the frozen expected evidence. A cleared relationship finding can still
+leave `devday:checklist` stale in question evaluation. Refreshing expected
+evidence is a separate explicit source-owner action. Neither result establishes
+semantic support, readiness or human acceptance.
+
+## API and authority
+
+`createPublicWorkshopComposition` delegates `start`, `event`, `lookup`, `read`,
+`recover` and `list` to the existing Knowledge sessions and durable coauthor
+store. `profile()` provides current evidence and the start snapshot;
+`prepareHandoff(sessionId)` prepares the copy-only handoff after durable readback.
+Use the existing session request shapes. The author is locally asserted.
+
+This profile saves ordinary public coauthor drafts. Its context retains the
+six finding fields; it does not issue a native typed finding-disposition receipt.
+It adds no source writer, ledger, canonical model, editor or server.
+
+The public Obsidian source-apply primitive is available under
+`@mnstry/atelier/obsidian/edits`. It requires its admitted workspace, vault,
+generation, policy and authored-body lens. Its compatibility with this workshop
+frontmatter remains an owner binding gap; these controls must remain enforced.

package/docs/knowledge-health/readme.md

@@ -1,15 +1,23 @@
 # A workshop checklist
 
-Start with the [composed workshop quickstart](quickstart.md). It binds this
-fixture to the received generic assessment; its target release and native host
-still require the release owner’s qualified receiving.
+Start with the [public workshop quickstart](quickstart.md). It uses
+the existing Knowledge host, ordinary private drafts and a copy-only
+source-owner handoff. Choose a pinned package version that includes this profile
+and rehearse that exact installation before a participant session.
 
 Try one small Knowledge Health journey with two invented sources: a checklist and a proposed community workshop. The plan expects the checklist to support consideration of the workshop. Its declaration currently contains `supports: []`.
 
 The check can show this missing relationship. It cannot decide whether the workshop is ready or whether that relationship is useful. You bring that judgment.
 
-Use the [guided exercise](exercise.md), the [support and recovery notes](support.md), or the [facilitator run sheet](facilitator.md). All material is public and invented. Work on your own disposable copy of [the example](../../fixtures/knowledge-health/workshop/README.md).
+Use the [participant response guide](participant-response.md) or the
+[facilitator run sheet](facilitator.md). All material is public and invented.
+Work on your own disposable copy of
+[the example](../../fixtures/knowledge-health/workshop/README.md).
 
-This guidance supplier does not install a host or launch a separate editor. **The package's guided-example entry and exact release version still need to be bound by its release owner.** No launch command is documented here until that installed entry is verified. An existing Workbench host can receive this material and the additive cues through its own source owner. If your installed version has no guided-example entry, the files remain readable example material; ask for the supported version rather than using private developer paths.
+The separate [assessment exercise](assessment/quickstart.md) uses an editor and
+the assessment API with the `demo:checklist` and `checklist-pilot` example.
+The workshop uses `devday:checklist` and `checklist-workshop`; its drafts do not
+issue native typed finding-disposition receipts or apply canonical source edits.
+Installed-host behavior and participant usefulness require their own evidence.
 
 The [integration reference](api.md) explains the additive modules. The native editor, saved versions, authoring records and source-owner correction route remain authoritative. The cues never dispatch an assistant or apply a change.

package/docs/maintainers/describing-the-atelier.md

@@ -0,0 +1,173 @@
+# Describing the Atelier
+
+Copy about a governance tool is itself a claim. `docs/reference/design.md` says a design
+document that cannot be checked is marketing, and the same holds for a README
+sentence, a distribution's landing page or a partner's brief. This page carries
+the judgment behind the wording. The promises themselves live in
+`docs/blocks/` and are embedded verbatim under `test/normative-blocks.test.mjs`;
+this page says how to write around them without overclaiming.
+
+It binds anyone writing about the Atelier in this repository, in a
+distribution built on it, or in materials that name it.
+
+## Two readers, one rule
+
+Two people read about the Atelier. An operator installs `@mnstry/atelier`,
+governs a body of work on their own local computer or virtual machine, and runs
+whatever systems they run. A team on a managed runtime works the same
+repository from a harness that also reaches that runtime, and cares about what
+it retains.
+
+The rule for choosing words: **package copy describes the package; system copy
+describes the system.** The package is the repository, the graph, the
+contracts, the gates, the projection, the skills and the sync. The system is
+the package plus the harness plus a runtime plus connected tools. A sentence
+that needs a runtime to be true is system copy. A sentence about the package
+is true for both readers and is written once. This repository's own pages are
+package copy.
+
+## Agents live in the harness
+
+The agent is never in the package. The harness (Claude Code, Codex or another
+coding harness) supplies the agent that edits authored files. The package
+supplies context, checks and collaboration records. What the package will and
+will not do over the network and to a runtime is stated in the README's
+will-not-do and claims blocks; what it does to a source is stated in README
+section 4, "The local runtime serves people and agents". Embed or point to
+those; do not restate them, because a looser restatement of a boundary is the
+failure the public-source rules single out.
+
+Two sentences about agents are both true and must not be confused. About the
+workflow: where the checks run in the commit path, every change, by a person
+or an agent in the harness, passes the same checks, and that is what makes an agentic process (one where an agent acts inside a
+governed workflow) reliable. Do not describe that workflow as agents only
+proposing while an owner types the edit; that is neither the design nor the
+practice. About the package: its collaboration surface assembles context and
+proposals and applies none of them, and the README says so. Do not describe
+the package as an editor, autonomous or otherwise.
+
+## Skills guide, gates enforce
+
+Skills carry the workflows an agent runs: opening a source, guiding an
+authoring session, running a readiness review, keeping the public boundary.
+They are delivered from the package as an audited set of skill files,
+installed into a workspace by a plan whose content digest is confirmed before
+it applies, and pinned by a lock, so the installed skill files are known and
+reviewable. Whether a given harness discovers and follows them is separate
+evidence. Enforcement never rests in a skill. Where they are wired into the
+commit path or CI, the gates run whether or not an agent followed its
+instructions, and they fail closed: the graph check (`atelier graph --check`),
+the boundary guard (`atelier boundary check`, installed as Git hooks by
+`atelier boundary install-hooks`) and the export validator (`atelier dry-run`).
+A Git hook runs only where it is installed
+and can be skipped with `git commit --no-verify`; run the same commands in CI
+where that matters.
+
+Never write that a skill "bounds", "limits" or "prevents" an agent. A skill
+is guidance a model may or may not follow. A gate runs regardless. List gates
+by the commands that run them.
+
+## Artifacts are governed, not frozen
+
+Generated artifacts (projected pages, documents built from the graph, a site
+built from the same sources) are governed, not forbidden from being touched.
+Each carries its source and revision, and a freshness check flags one that has
+drifted. Do not write "never hand-edited" or "always generated". Write what
+the machinery does: it knows where an artifact came from and says when it no
+longer matches.
+
+## Three proofs
+
+Three different things get called "validated". Keep them apart.
+
+- **Conformance.** The export dry-run validator proves an artifact is in the
+  published format and every reference resolves to a declared source; the
+  README's audience-visibility block states what it refuses across audience
+  and visibility. It does not
+  prove that referenced content is packaged, and it does not prove that every
+  necessary rule was written down. `atelier dry-run <artifact>`
+  reports `accepted`, and separately whether the artifact is `importable`.
+- **Coverage.** The readiness protocols check a supplied answers file
+  against each protocol's required inputs and list the ones missing; an
+  answer being present is not evidence that it is right. `atelier readiness
+  run PROTOCOL_ID --answers FILE` is that input-completeness check, and its
+  runs are not evidence-bound. For a run bound to its sources, `atelier review
+  run PROTOCOL_ID --answers FILE` records that source-bound run. Accepting one
+  of its claims in the review workspace checks source linkage. Linked bytes
+  establish what was read, not whether they logically support the proposed claim
+  (`docs/guides/local-review.md`). The responsible people review coverage; an issuer can record its admission
+  decision in an attestation bound to the canonical form of the document it
+  judged (`docs/reference/attestation.md`).
+- **Behavior.** Representative inputs and expected results beside each rule,
+  run by whatever executes the rule, show that the documented rules do what
+  the record says. The package keeps the cases and links them to their rules
+  in the graph; it does not run them, so name the runner when you cite this
+  proof.
+
+Completeness is coverage plus behavior. No sentence lets one proof stand for
+another. "Passes the validator" never means "enough to rebuild from".
+
+## What a universal may claim
+
+Keep a universal only when a mechanism establishes it. "The same files always
+produce the same graph" stands because determinism is a tested contract
+(`test/graph-determinism.test.mjs`). Replace the rest with the step that makes
+the claim true.
+
+| Instead of | Write |
+| --- | --- |
+| on the intranet the moment it has a header | give a file a header and the next build puts it on the intranet |
+| an immutable record | a revision-pinned record that keeps the original contribution beside every later decision |
+| a correction made once reaches every artifact | a correction made once reaches every artifact on its next build |
+| every file a change affects | every file declared to depend on it |
+| the improvement arrives the day it ships | the capability is adopted against the same source and tests: edit the skill, run the checks, keep what passes |
+| copying the folder is the backup | a copy of the folder is a copy of the whole record |
+
+## One factual standard
+
+The machinery settles what a sentence may claim it guarantees. An issuer's
+approval settles what that issuer commits to and how it frames an offer. When
+both meet in one sentence, the commitment reads as a commitment and the
+guarantee as a guarantee, and the reader can tell which is which. A sentence
+that was approved for one document is not thereby true in the next one.
+
+## The graph is where the work improves
+
+The knowledge graph is an index of what depends on what. It is also the basis
+for iterative authoring. By convention each round adds reviewed examples with
+expected results, linked to the rules they test. An agent in the harness can
+run them against its drafts, revise its work and its instructions where they
+fail, and run them again; the package keeps the cases and their links, not the
+runner. Say so when describing the graph; an index alone undersells it.
+
+## Extensions, stated as possibility
+
+A website or another tool built on the same graph carries its source and
+revision, and can keep its own records in the graph with the decisions made
+about them. In package copy
+this is what the graph makes possible for an operator's own agents to build,
+never a feature list of the package.
+
+## Wording
+
+- "Your local computer or virtual machine", never "this computer".
+- American spelling throughout, as the README uses: "artifact", "license", "behavior".
+- The public category noun is "local governance toolkit for file-based bodies
+  of work".
+- Counts are stated by the command that lists them, not by number.
+- No speed or ease claims. Show the command.
+- Promise, egress, conformance and admission language embeds the block in
+  `docs/blocks/`; it is never paraphrased.
+- "AI" is a category, not an actor. Name the model, the agent, the harness or
+  the system that does the thing.
+- "Agentic" is defined where it first appears on a page.
+- No client is named and no client's structure is reused. Examples are
+  synthetic and are validated against the exact release they ship with.
+- Sentence case. Short declaratives.
+
+## Where this came from
+
+These rulings were made while writing about the Atelier and checked by
+independent review against the implementation. They are kept here so the next
+writer starts from the judgment, not from the wording that happened to
+survive.

package/docs/{release-engineering.md → maintainers/release-engineering.md}

@@ -63,7 +63,7 @@ Shipped, and required by the audit:
 - Every `contracts/atelier-obsidian-<name>.v<n>.schema.json` present in the
   source tree (lowercase name, versioned). Each must be packed and exported
   under its own path, and the audit fails if it finds none.
-- `docs/obsidian.md`, `docs/obsidian-contract.md` and `docs/obsidian-plugin.md`.
+- `docs/guides/obsidian.md`, `docs/reference/obsidian-contract.md` and `docs/reference/obsidian-plugin.md`.
 - Atelier's own Obsidian plugin, which every managed vault receives:
   `plugins/obsidian/manifest.json`, `main.js` and `styles.css`, the only files
   admitted under `plugins/`, with its channel
@@ -257,7 +257,8 @@ offline-only hosts keep the behaviour above:
    online install.
 
 Failures print as `[code] message` with a `Next:` step. The pure classifiers
-are in `scripts/consumer-closure-diagnostics.mjs`:
+are in `src/upgrade/closure-diagnostics.mjs`; the consumer smoke and tests
+import that canonical module directly:
 
 - `consumer-closure-incomplete`: an offline install or reinstall hit
   `ENOTCACHED`, or the captured lockfile has a registry entry missing
@@ -353,8 +354,8 @@ A version bump touches exactly:
 
 - `package.json` (`version`)
 - `CHANGELOG.md` (a `## <version>` heading)
-- the pinned install tags in `README.md`, `docs/install.md`,
-  and `docs/upgrade.md`
+- the pinned install tags in `README.md`, `docs/start/install.md`,
+  and `docs/guides/upgrade.md`
 - `compatibleRootVersions` in
   `templates/external-project-workspace/pack-lifecycle.json`, so the shipped
   starter's pack is qualified for the released root version (the

package/docs/{announcements.md → reference/announcements.md}

@@ -40,7 +40,7 @@ never re-signs.
 The signature covers the UTF-8 encoding of the RFC 8785 (JCS)
 canonicalization of the document with its `signature` member set to null —
 the same normative rule the attestation flow uses (see
-`docs/attestation.md`). The shared implementation is
+`docs/reference/attestation.md`). The shared implementation is
 `signDocument`/`verifyDocument` in `src/attestation/sign.mjs`.
 
 ## Verifying announcements

package/docs/{architecture.md → reference/architecture.md}

@@ -7,7 +7,7 @@ contracts, governance, graph and local runtime support eight responsibilities.
 | --- | --- | --- |
 | Inquiry | Investigate uncertainty and assess evidence | Discovery and Research Harnesses; `inquiry` |
 | Knowledge Stewardship | Curate, govern, connect and operationalize knowledge | `harness knowledge`, `ingest`, intake, graph and context; [evidence navigation](evidence-navigation.md), composed by Discovery and Research |
-| Practical Judgment | Discern fitting action, cultivate practice and learn from consequences | `learn`, practical cases, decision adapters, `practice` |
+| [Phronesis — practical judgment](phronesis.md) | Discern fitting action, cultivate practice and learn from consequences | `learn`, practical cases, decision adapters, `practice` |
 | Creation and Delivery | Design, implement, verify and deliver changes | `harness build` |
 | Capability Stewardship | Qualify, package, adopt, exercise and evolve reusable abilities | `capability`, Skill Steward and `skills` |
 | Reflection | Form revisable assessments of the person, work, interaction and system | Witness role; qualified assessments and reflective acts |
@@ -19,8 +19,8 @@ into work. A **role** describes participation. A **capability** specifies a
 supported outcome; a **resource** realizes it. A **method** is an optional way of
 working. A **record** retains domain meaning. A **host** executes through its
 actual bindings. A role does not acquire a new store or permission merely by
-being named. Coaching is one reflective method. Phronesis remains the foundation
-of Practical Judgment, including purposes, particulars, taste and exceptions.
+being named. Coaching is one reflective method. Phronesis attends to purposes,
+particulars, taste and warranted exceptions.
 
 Skill Steward is a specialized role within Capability Stewardship. Its existing
 catalog and bindings remain authoritative for managed skills. Knowledge
@@ -28,6 +28,13 @@ Stewardship owns knowledge inclusion and applicability. Neither owns another
 repository's adoption decision. Fabric can implement Coordination; the local
 contracts do not require a Fabric service or account.
 
+Knowledge Stewardship remains the broader responsibility. The Knowledge Graph
+is the shared representation of sources, evidence and relationships used across
+responsibilities. Phronesis draws on it and contributes cases, decisions and
+learning through the existing Knowledge writer, review and activation routes.
+This introduces no new store or canonical authority and does not automate wisdom
+or assign it a universal score.
+
 Creation and Delivery also owns the kit's user-facing failure contract: one
 diagnostic shape, a registry of stable codes, and one exit-code convention for
 every command. Other responsibilities raise typed diagnostics through that
@@ -82,8 +89,27 @@ host adoption is not established by this catalog. A catalog entry is not an exec
 semantic registry. Host adapters must map these contracts to existing domain
 operations rather than create competing writers.
 
-See [Practical Judgment](practical-judgment.md), [research starter](research-starter.md)
-and [integration decisions](integration-contract-decisions.md).
+Native ADR identity and approval remain with the issuing repository. Importing
+a decision does not create a new local approval.
+
+See [Phronesis](phronesis.md) and the
+[research starter](../guides/research-starter.md).
 
 See [Trackables](trackables.md), [Interaction and Reflection](interaction-and-reflection.md)
 and [Coordination](coordination.md) for supported profiles, native bindings and limits.
+
+## Maintained implementation decisions
+
+These current implementation decisions remain within this responsibility
+architecture. Source citations identify the controls that must be reconsidered
+when their implementation changes; they confer no new approval or execution
+authority.
+
+<!-- atelier:maintained-implementation-decisions:start -->
+
+| Artifact | Decision | Compatibility and authority |
+| --- | --- | --- |
+| Inspection bundle | Keep the [inspection bundle](../../src/collaboration/inspection-bundle.mjs) inert and attributed; reuse disclosure and JCS primitives. | Importing must not overwrite active state, transfer execution or secret authority, or create current local approval. |
+| Pack compatibility | Use the [versioned pack lifecycle](../../src/extension-packs/lifecycle.mjs) declaration. | Existing packs remain inspectable; closed versioned contracts must not be silently widened. |
+
+<!-- atelier:maintained-implementation-decisions:end -->

package/docs/{atelier-runtime.md → reference/atelier-runtime.md}

@@ -57,4 +57,4 @@ The local Git supervisor is a separate mechanical authority surface. It may
 create a repository commit only from an unchanged, bounded plan after the user
 repeats its exact operation id. That repository write is not a MNSTRY runtime
 mutation and does not grant proposal apply authority to the browser sidecar.
-See [Atelier Sync: Deliverable Zero](./atelier-sync.md).
+See [Atelier Sync: headless repository supervision](../guides/atelier-sync.md).

package/docs/{connected-composition.md → reference/connected-composition.md}

@@ -6,12 +6,10 @@ host. Existing package exports and contracts remain unchanged.
 
 ## Bounded implementation
 
-Owned additions: `src/composition/`, `src/access/`, `src/preview/`,
+The source is `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.
+`scripts/prove-connected-composition.mjs`. Its local proof does not establish
+adoption or CI qualification of a receiving host.
 
 The public root supplies placement validation, an opt-in trusted-host enforcement
 helper and a two-origin preview channel. A private host supplies identity,
@@ -25,7 +23,7 @@ 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
+## Supported controls
 
 1. Closed, byte/depth/count-bounded JSON parsing, placement and action schemas;
    exact source-byte and immutable definition/renderer digests.
@@ -52,11 +50,10 @@ 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
+## Protocol and limits
 
-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.
+The wire uses `proposal-v1` discriminators and a closed action validator.
+The implementation profile is `connected-composition/experimental-v1`.
 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.

package/docs/{coordination.md → reference/coordination.md}

@@ -37,7 +37,7 @@ projection can waive a Build blocker.
 | Dependencies/handoffs | Reuse Harness verification; add cross-repository dependency/cycle views | Trusted snapshot acquisition and receiving receipt verification |
 | Directives/dispositions | Add scoped versioned observations and distinct stages | Sending, receiving, wakeups and authenticated acknowledgements |
 | Delivery/gates | Reuse Build candidate, attempt, decision and gate records | Commands, CI, review and deployment |
-| ADRs | Practical Judgment native-byte adapter and decision record | Repository numbering, authority and acceptance |
+| ADRs | [Phronesis — practical judgment](phronesis.md) native-byte adapter and decision record | Repository numbering, authority and acceptance |
 | Practice/context | Learning lifecycle and scoped instruction adoption | Host context admission and observed behavior |
 | Ingestion/knowledge | One Intake source lineage, bounded ingestion, Knowledge review and context | Source rights, domain meaning and external processing |
 | Capability adoption | Capability releases, independent repository plans, Skill Steward and feedback bridge | Publisher trust, host loading and native use |

package/docs/{decisions.md → reference/decisions.md}

@@ -173,7 +173,7 @@ The core package has no Jev dependency or credential requirement. Its ingestion,
 inquiry, knowledge and learning workflows remain available without a provider.
 The public decision contract alone does not install or qualify an adapter.
 
-Use [Capability Stewardship](capability-stewardship.md) to inventory a provider
+Use [Capability Stewardship](../guides/capability-stewardship.md) to inventory a provider
 capability's procedures, required tools, effects, exact release and repository
 adoption. A skill bundle can describe how to use an adapter; installing that
 bundle neither configures credentials nor enables provider execution. Record
@@ -184,9 +184,9 @@ timeouts, budgets and revocation. No repository's adoption enables another's.
 Harnesses consume validated advice through their existing owners. Ingestion may
 use a qualified prioritization while retaining every selected source and coverage
 gap. Research preserves citations and contradictory evidence. Knowledge admission
-and [practical judgment](practical-judgment.md) retain their review and adoption
+and [Phronesis — practical judgment](phronesis.md) retain their review and adoption
 steps; a provider result cannot write graph facts, accept a lesson, or install
-instructions. The [learning lifecycle](learning.md) can retain permitted outcome
+instructions. The [learning lifecycle](../guides/learning.md) can retain permitted outcome
 evidence for reconsideration without creating a second knowledge store.
 
 With no binding, use the existing local or manual workflow. A requested provider

package/docs/{design.md → reference/design.md}

@@ -163,5 +163,5 @@ its own ontology, protocols, and boundary policies.
 
 The claims behind this page are stated precisely, with their known limits,
 in the README's "Claims you can check" — each with the command that proves
-it. `docs/continuity.md` records the distribution commitments, including
+it. `docs/reference/continuity.md` records the distribution commitments, including
 the perpetual Apache-2.0 grant on every tagged release you receive.