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

package/docs/knowledge-health/devday/participant-response.md

@@ -0,0 +1,22 @@
+# Participant response and separate Review
+
+This public workshop uses the existing local Knowledge editor and ordinary coauthor drafts. Its author label is locally asserted. Saved drafts and proposal retention do not establish native finding disposition, authentication, semantic support, release readiness or human acceptance.
+
+1. Start Workshop against the current `workshop-readiness` finding. Open its captured evidence, source declaration, anchor and finding fingerprints.
+2. Record your original words, then save and continue. The consumer preserves lossless wording within 512 UTF-8 bytes. Original words cannot be replaced through Propose.
+3. Record a separate optional interpretation, then save and continue. Leaving it blank records an explicitly empty interpretation. Proposed interpretation requires Confirm or Keep original wording before saving.
+4. Choose Note, Perspective, Disagreement or Pause, then save and continue. Perspective retains the existing `perspective-only` value. Pause is a response choice; the session Pause control remains a separate navigation action.
+5. Read the original contribution and choice event IDs, descriptor/event-history readback and immutable saved-value readback. A save request ID identifies the save receipt and differs from the original answer ID. An unsaved choice remains unconfirmed.
+6. Review displays the current `[]` declaration and proposed `["devday:workshop"]` declaration. Return removes the preview and makes no request. Selecting the draft starts a separate linked Review session. Record selected draft, save it, continue, then reload or reopen the same session from history before preparing the handoff.
+7. The copy-only source-owner handoff retains original words, optional interpretation, four-choice meaning, original contribution/choice IDs, contributor session, selected save receipt, source/anchor/read set and all six finding fingerprints. Foundation owns durable proposal retention and original-identity lookup in its existing sidecar/proposals implementation. That owner work remains prospective until applied and qualified.
+8. The source owner checks the bound source digest and exact before/after UTF-8 declaration, edits the exact declaration through the ordinary repository route, reads it back, refreshes expected evidence and reruns the same assessment/question. Keep the earlier finding, contribution and selected draft as history. Automated Obsidian/frontmatter apply remains separate and keeps its refusals.
+
+## Recovery and storage meaning
+
+Retry first looks up the original request. Observed returns the retained result; not-found permits the same complete event intent to retry; unknown keeps the original intent without appending. A Review start is looked up as `kg-<original request UUID>`, independently of its contributor session ID. No successor UUID is generated during retry. Missing descriptors, ledger custody or immutable values remain unknown/unavailable.
+
+The existing draft engine requires nonempty text. This consumer stores optional interpretation as the inert JSON text `{ "text": "..." }`, including the empty string. The editor and history decode it for display. Its save receipt's value digest binds the encoded text; it does not claim to bind the decoded string. Existing draft schema, event ledger, save/recovery rules and values directory remain authoritative.
+
+`readSavedFields` reads the existing verified event chain and existing immutable values under the existing operation lock. It refuses redirected, missing or changed values and never reconstructs them. Reopen requires both owning readbacks to agree. Earlier descriptors without the participant profile marker retain their legacy revision history; new sessions use four responses and a separate Review.
+
+Source-only authored cases accompany this change. No tests, browser journey, installed package, retention readback, source edit or release was executed by this supplier attempt.

package/docs/knowledge-health/devday/public-default.md

@@ -0,0 +1,107 @@
+# Use the public workshop profile
+
+Use the exact package version and integrity supplied by the release owner. This
+profile is a source contribution until it is admitted, released and rehearsed.
+
+In an empty consumer directory, install that version and create a new workshop:
+
+```sh
+npm install --save-exact "@mnstry/atelier@$ATELIER_DEVDAY_VERSION"
+```
+
+```js
+import { initializeKnowledgeHealthWorkshop } from '@mnstry/atelier/knowledge-health'
+initializeKnowledgeHealthWorkshop('./workshop')
+```
+
+Build its graph and projection, then start the existing loopback host:
+
+```sh
+npx --no-install atelier graph --project ./workshop/atelier.project.json
+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 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/devday/quickstart.md

@@ -0,0 +1,18 @@
+# Start with the pinned public package
+
+This quickstart covers the published baseline, 0.2.0-alpha.12. It gives a public invented graph example and existing coauthor capabilities. The full Knowledge Health guided journey is a release-owner join; it is not present in this baseline installation.
+
+Use Node 22.18.0 for the tested rehearsal. Create a new empty directory and install the exact version:
+
+    npm install --save-exact @mnstry/atelier@0.2.0-alpha.12
+    ./node_modules/.bin/atelier --version
+    ./node_modules/.bin/atelier init --template sample-workspace --target example
+    cd example
+    ../node_modules/.bin/atelier graph
+    ../node_modules/.bin/atelier project
+
+The graph and projection describe the installed invented example. Read its source documents alongside the result. A structural check does not decide whether a real relationship is meaningful or accepted by its owner.
+
+These commands use the installed bin. They do not download a moving latest version or require a publisher checkout. The tested docs inside the installation include README.md, docs/knowledge-graph.md and docs/coauthor-session.md. The exported API families include @mnstry/atelier/graph, @mnstry/atelier/project and @mnstry/atelier/coauthor. Use only the actual version's declared exports.
+
+For the Dev Day release, the facilitator must first receive and rehearse its exact version, normal example entry, guided authoring entry and owning correction route. Replace the pinned version only after that receiving. Do not substitute an unreleased source template or a private editor for an installed capability. Keep the tested package integrity and the separate tarball/registry reports with the handover.

package/docs/knowledge-health/devday/support.md

@@ -0,0 +1,22 @@
+# Support and recovery
+
+| Surface | Evidence | Limit |
+| --- | --- | --- |
+| macOS, Node 22.18.0 | Clean public baseline registry and tarball consumer reports | Full Dev Day candidate remains pending receiving |
+| Node 24.13.1–24.x | Package declares support | No run in this packet |
+| Linux | Package may run there | No platform qualification in this packet |
+| Windows | No consumer run here | This proof harness refuses Windows execution until separately qualified |
+| Guided Knowledge Health UI | Existing native suppliers have separate proof | Not installed by the public baseline |
+| Human understanding/usefulness | Predeclared participant protocol | Actual event observations remain open |
+
+If installation fails, keep the exact version, registry integrity, Node/npm version and error. Do not add publisher overrides or switch to latest to hide the error. Retry a network fetch only after identifying the network failure; a save/application retry follows its own operation lookup and fencing contract.
+
+If a command or example is missing, check the installed package's bin, exports and files. In the observed baseline, normal init refused knowledge-workspace and listed private-domain, shared-project, sample-workspace, distribution and external-project. Use the tested sample-workspace baseline only for its supported graph exercise. The full guided example requires the new release owner's receiving.
+
+If source or repository identity changed, stop the affected write. Preserve the original finding/source/field/revision, exact words and pending intent. Refresh through the supported binding/assessment route and distinguish historical context from the current source. The tested baseline coauthor CLI refused stale revision and source drift while retaining its saved state.
+
+If save/application is unknown, preserve the original ID and complete record and use its authoritative lookup/readback. A missing reply is not proof that nothing happened. Resend only identical intent after the owning contract's authoritative absence/fence and explicit retry decision. Do not reset or compact the ledger as a recovery shortcut.
+
+For withdrawal, close the current component and disable unavailable typed controls. Preserve the ledger. Use only an owner-qualified previous reader; an older typed reader may refuse newer events even while ordinary operations work. Re-enter the qualified current reader for complete historical context. This packet does not operate a participant's retained private state or install a rollback.
+
+Provide support with the pinned package/candidate, failed step, expected/observed behavior, original IDs, checked readback, public example source digests and scoped cleanup. Exclude tokens, private documents and unrelated histories. Preserve the original failure and its correction rather than replacing it with a later pass.

package/docs/knowledge-health/exercise.md

@@ -0,0 +1,17 @@
+# Follow one finding
+
+Allow about 20 minutes. You can stop at any step, disagree with the proposed relationship, or keep a perspective without applying a revision.
+
+1. **Read the two sources.** Open the checklist and workshop proposal in the supported guided host. Notice the empty supporting declaration in the checklist. In the graph, find both source identities and the missing declared relationship. The graph is a view of the sources.
+2. **Inspect the finding and evidence.** Read the question and the exact `[]` declaration. Open the check's evidence details. Confirm this is the current checklist and saved passage. A missing declaration does not mean the workshop is unsafe or that the relationship must be added.
+3. **Add your words.** In the existing passage contribution input, write one sentence about what you understand or question. For example: “The checklist may support the workshop, but it should not approve it.” This is an invitation; use your own words. The current native note limit is 512 UTF-8 bytes, so some characters use more than one byte.
+4. **Keep interpretation separate.** Read the proposed interpretation, if one is offered. It must be separately labeled and leave your original words intact. You may correct it or leave it empty. Nothing in this exercise requires a model call.
+5. **Choose how to keep it.** Explicitly choose Note, Perspective, Disagreement or Pause, then save your words and choice. Read the retained words and separate interpretation. Until both native readbacks are verified, a choice can remain unconfirmed even when the words are saved. You may return to writing without continuing.
+6. **Preview a revision.** If you want to explore the example proposal, open the existing Review. Compare `[]` with `["devday:workshop"]`. The proposed change adds only the supporting declaration; it does not approve the workshop. Select it only if you choose. Back to writing leaves it unapplied.
+7. **Apply to the working draft and reopen.** Use the existing selected-application action. Wait for verified readback, then reopen the saved draft. Check that your selected declaration is there. The original authored source still contains `[]` until its owner changes it.
+8. **Let the source owner act.** On this disposable copy, the facilitator may designate you as its source owner. Review and apply the exact declaration through the normal repository editing route, then read the file back. Ownership of this example gives no permission to write another repository. If you are not its owner, keep the draft as a proposal.
+9. **Check the new evidence.** Refresh the source's expected-evidence hash through the owning route and rerun the same question evaluation and relationship check. Compare old and new source evidence. The supported structural gap should disappear; the words, old finding and chosen perspective remain history. Meaning and your agreement remain open to you.
+
+Finish with one sentence: what did the check help you see, and what did you still have to decide? No automatic walkthrough can answer that on your behalf.
+
+If the host lacks one of these steps, use [support and recovery](support.md) and record that exact missing step. Do not replace it with an invented command or an unrelated source.

package/docs/knowledge-health/facilitator.md

@@ -0,0 +1,20 @@
+# Facilitator run sheet
+
+Use the exact supported release and one new disposable workshop copy per participant. The kit's target session is Thursday 8 October 2026; rehearse the installed version on Wednesday 7 October. Those dates do not prove publication or participant acceptance.
+
+Before the session, obtain the release owner's verified version and guided entry. Install that exact version using the package's tested quickstart, check its documented Node/Git/browser prerequisites, and rehearse the whole [exercise](exercise.md) from a clean copy without private paths, developer imports or environment overrides. Do not start until the public launch, copy/open, contribution, interpretation, Review, source-owner correction, readback/reopen and reassessment steps are available. Keep any genuine missing step visible.
+
+| Time | Invitation | Observe without answering for the participant |
+| --- | --- | --- |
+| 0–3 minutes | “Read these two sources. What do you think their connection is?” | Can they distinguish source words from graph projection? |
+| 3–6 | “What exactly does this finding show?” | Do they find the `[]` evidence and understand the limited relationship check? |
+| 6–11 | “Add your own words. How would you like them understood?” | Original words, separate interpretation, an explicit choice, and optionality. |
+| 11–15 | “Would you keep the proposed declaration change?” | Preview before effect, ability to disagree or return, selected draft readback. |
+| 15–20 | “What has changed after the source owner acts and the check runs again?” | Source versus draft, reopened text, current evidence and remaining judgment. |
+| 20–25 | “What was useful, confusing or missing?” | Record the participant's actual words and any unanswered question. |
+
+Offer the participant the source-owner role only for their own disposable copy. Explain what the ordinary source write will change before granting that role. Keep source ownership and participant judgment distinct even when one person performs both.
+
+For a recovery exercise, use the host's documented disposable failure rehearsal. If it has no supported rehearsal, discuss the visible unconfirmed state without disconnecting an unknown service. A pending choice is checked under its original identity; it is not submitted as a new note. Do not run a provider to fill a gap, alter a participant's words, or reset the example's history.
+
+Observe keyboard access and the [checklist](support.md). If a step fails, preserve the words and exact pending intent, record the visible state and reproduction steps, then use the normal support route. Finishing a scripted exercise is not evidence that the participant found it useful.

package/docs/knowledge-health/quickstart.md

@@ -0,0 +1,94 @@
+# Follow the workshop finding
+
+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.
+
+## Install the verified version
+
+The facilitator supplies the exact rehearsed version and package integrity.
+Create an empty consumer directory, then use that version:
+
+```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);
+```
+
+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 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:
+
+```sh
+npx --no-install atelier graph --project ./workshop/atelier.project.json
+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.

package/docs/knowledge-health/readme.md

@@ -0,0 +1,15 @@
+# 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.
+
+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).
+
+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 [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/knowledge-health/support.md

@@ -0,0 +1,34 @@
+# Support and recovery
+
+| Capability | What this supplier establishes | What the installed release must establish |
+| --- | --- | --- |
+| Workshop source and check | Native graph, plan, context and question evaluation on these exact invented sources | Installed assessment entry, evidence read-set and current source binding |
+| Original words and choices | Actual native full-reference disposition APIs retain all four choices and separate interpretation in a disposable ledger | Actor/source/head checks at the host boundary and participant-visible controls |
+| Draft preview/application | Actual native selected decision, preview, apply, save and reopen in disposable state | Installed Review/focus/undo flow and current effect permissions |
+| Source change/reassessment | Owned disposable source edit, exact readback and same-rule reassessment | The real owning repository edit route and fresh expected evidence |
+| Recovery | Original-ID native lookup after a withheld response, with no second write | Installed pending-intent/scratch recovery across browser and service restart |
+| Accessibility | Cue structure, received Button role/focus and synthesized Enter/Space activation, disabled refusal and editor preservation in DOM qualification | Real keyboard navigation/focus return, screen reader, zoom, IME and browser checks |
+
+Qualification uses Node 22.18.0. The installed package's declared engine range governs other versions. A local same-machine authoring host supplies its own actor binding and owning routes; this supplier does not add hosted authentication or grant access to another repository. Use only public invented material in the example copy. No hosted account or provider call is needed for this guided supplier's supported case.
+
+| Visible state | Keep | Next step |
+| --- | --- | --- |
+| No applicable finding | Your writing and any plain note | Select supported example material or ask which input is supported. |
+| Saving/checking | Original operation and newer words | Wait; verify the exact saved revision. Do not start another write. |
+| Words saved, choice unconfirmed | Original contribution and complete choice record | Check original choice. Lookup reads only. |
+| Lookup proves choice absent | The same choice ID and identical complete record | Explicitly retry only if the host offers its fenced original-choice action. |
+| Source/head changed | Human words, old source reference and history | Read current source/head; choose whether to attach a fresh contribution. |
+| Draft saved, source unchanged | Selected draft and proposal | Ask its actual source owner to review the change. |
+| Source applied, old expected evidence | Source readback and old result | Refresh expected evidence through the owner and reassess; keep both results. |
+
+Never solve an unknown save by deleting history, changing the operation ID, dispatching an assistant, or restarting someone else's editor. If lookup is unavailable, remain unconfirmed and preserve the intent.
+
+Use this checklist during the installed rehearsal:
+
+- Tab/Shift-Tab reaches evidence, contribution input, choice controls, Review and return controls in an understandable order; focus is visible and no trap occurs.
+- Enter/Space activates each button once. A disabled control cannot write. Choice labels expose the chosen state and a choice is not preselected as human consent.
+- The source evidence and proposed interpretation have readable labels. Status changes are announced without moving focus or replacing the editor.
+- Escape/return uses the host's normal path back to the original editor and caret. Native undo/redo, selection and composing text remain intact.
+- Save during a later edit acknowledges only the saved revision; the newer text remains visible and unsaved. Unknown choice/application exposes a read-only check before retry.
+- Reopen/reload/service restart recovers exact words, interpretation, choice and pending identity. An old note is labeled historical after source/head changes.
+- Zoom, narrow layout and screen-reader reading retain the evidence/choice distinction. Test the release's actual supported browser and IME; DOM observations alone do not establish these.

package/docs/knowledge-setup.md

@@ -0,0 +1,248 @@
+# Set up a graph that earns its context
+
+Start with useful work: a question someone needs to answer, the decision it
+changes, and the evidence that would make the answer trustworthy. Let people
+plan and validate; let agents do bounded retrieval, comparison, and drafting.
+Expand the ontology when another real task exposes a missing distinction.
+
+## Try the complete local path
+
+```sh
+atelier init --template knowledge-workspace --target ./equipment-notes
+cd equipment-notes
+git init
+atelier knowledge check
+atelier knowledge context --question "Can the blue telescope be loaned this week?"
+atelier knowledge evaluate
+```
+
+The starter is an independently invented equipment library. Its private source
+graph has an equipment record, an inspection, and a qualified repair forecast.
+The inspection says the item has **not** passed; the replacement **may** arrive.
+The useful answer is to obtain the cap and a completed inspection before a
+loan decision. The CLI selects the supporting evidence; a person or agent must
+still read it and substantiate the answer.
+
+`check`, `context`, and `evaluate` read current source without changing it.
+They use the canonical graph builder, not a saved graph that may be stale.
+They make no provider calls. They are local operator tools: output may contain
+private source text, paths, and diagnostics. Repository access remains the read
+boundary. These commands do not implement recipient authorization or sharing.
+
+## Adapt it to work you actually do
+
+1. Name the work and its steward in `knowledge-plan.json`. Pick three to five
+   ordinary questions with decisions or actions at stake. Include a question
+   whose correct response is that the sources do not establish an answer.
+2. Record permission to process the selected sources, who reviews meaning,
+   how corrections and withdrawals are handled, and who can approve expression
+   for a recipient and purpose. These are declared responsibilities; the plan
+   does not authenticate an approver or enforce consent.
+3. Choose the smallest concepts those questions need. For each, write a
+   definition, a stable identity rule, and one `concept:...` tag. Similar
+   display names are not sufficient grounds to merge records.
+4. Declare the useful relationships, their direction, and what they mean.
+   Attach them to source records using the existing native predicates.
+   Run `knowledge check` to find unused concepts, unknown tags, empty concept
+   populations, and absent directed edges. Coverage reports both total records
+   and context-eligible records; archived, unclassified, and non-Markdown
+   records cannot satisfy retrieval coverage. Duplicate mappings of a predicate
+   and concept pair are refused; use assertion records for distinct meanings.
+5. Keep a small permitted slice of originals. Use Markdown front matter or
+   adjacent sidecars as described in [the source graph](knowledge-graph.md).
+   Use `atelier adopt` for an existing workspace; do not initialize over it.
+   Copy and adapt the starter plan, then use `--plan FILE` if it lives elsewhere.
+6. Compare retrieval on the questions before adding a model, vector index, or
+   engine. Pin the expected source ids and SHA-256 digests in each question.
+   Inspect missing evidence and relationships; repair the ontology or source
+   descriptions only when the failure warrants it.
+7. Have a person and an agent unfamiliar with the fixture attempt new questions.
+   Record supported answers, appropriate abstention, corrections, time,
+   measured model usage, and the work that resulted. A known test case stays
+   a regression case after a fix; it is no longer unseen evaluation.
+
+For a real workspace, replace every fictional record, role, and case. In the
+starter, roles are examples and source rights are assumed only for its invented
+content. Add repository boundary policies and hooks through the existing
+[boundary workflow](repo-boundary-guard.md) when collaborating across trust domains.
+Use actual access controls at the consuming host.
+
+## Domain ontology and source graph are different layers
+
+`kg.type` describes source records: document, evidence, artifact, decision, and
+the other native types. The plan's concepts describe what those records are
+about. A `concept:equipment` tag does not create a new native node type, schema,
+or accepted business entity. Do not put arbitrary domain verbs in
+`kg.relations`; the native vocabulary remains closed.
+
+Use a separate evidence-bearing assertion record when meaning needs more than
+a native edge: who asserted what, the passage and revision, subject, optional
+object, polarity, possibility or obligation, scope, time, and review status.
+Do not invent an object for a unary statement, turn a future possibility into
+a positive fact, or erase qualifications to make an edge fit. A native
+`related` link is useful navigation; it does not carry the lost meaning.
+Keep richer domain schemas in a consumer or extension pack until repeated
+independent needs justify a portable contract.
+
+Source occurrence, entity identity, assertion, proposed decision, accepted
+decision, action, observation, and reviewed lesson have different lifecycles.
+A graph edge proves neither semantic truth nor execution permission. Record
+counterevidence, corrections, and the conditions where a lesson should not be
+reused. Later reuse should help an actual new task; retention alone is not use.
+
+## Bounded context and honest accounting
+
+`context --mode lexical` ranks active, classified Markdown by matches in titles,
+summaries, and tags, breaking equal scores by record ID. `--mode graph` takes
+one hop from the top `maxDocuments` lexical seeds. It visits each seed followed
+by at most one unseen declared neighbor before the next seed. Further neighbors
+take turns across the original seeds only after every seed has been considered.
+With two document slots and multiple seeds, the lexical seeds go first because
+two seeds and a neighbor cannot all fit. Each seed's neighbors are ordered by
+their own lexical score, then record ID. Only the original seed set expands.
+Document and byte limits can still omit seeds or part of a neighborhood; check
+the reported omissions. It does not infer edges, search every body,
+perform semantic extraction, or rank by expected answers. Word forms and
+synonyms can be missed; improve descriptions or evaluate another retrieval
+method against the same cases before widening the pipeline.
+
+The JSON packet carries complete source text, source digests, file and line
+locations, selection reasons, and the declared edges between selected records.
+It retains direction and multiple predicates. Text is explicitly data, never
+an instruction channel. Current census digests must match the read source;
+changed, redirected, oversized, or unreadable sources are omitted visibly.
+`omissions` names up to 20 record IDs and reasons within the packet byte cap:
+`document-limit`, `packet-budget`, `source-over-budget`, `changed-since-census`,
+`redirected`, `decode`, or `unreadable`. Invalid paths, repository escapes, and
+unsupported source kinds also have distinct refusal reasons. Exception text
+and absolute paths are not included. `coverage.omissionsUnlisted` counts any
+additional details that could not fit; `unreadable` counts read and decode
+failures only. Inspect these details in Deepen, Apply, Learn, or evaluation output.
+Non-Markdown and unclassified records stay in graph diagnostics but are not
+context text. No parser is silently invented for a PDF or binary.
+
+`planSha256` hashes the exact raw bytes read from the plan file, including
+formatting; the CLI, dashboard, and session use the same binding.
+`censusSha256` hashes compact JSON containing the canonical nodes, edges, and
+the sorted Markdown census inventory of file keys and raw-byte digests. A
+body-only change to an unselected Markdown source changes this digest after a
+new census. Non-Markdown records contribute their node metadata, not a digest
+of their PDF, HTML, or DOCX body bytes.
+Each source's `sha256` hashes its raw file bytes. Line locations count actual
+LF or CRLF lines; a final newline does not create an extra line.
+
+`budget.maxContextBytes` caps the **whole compact JSON response**, including its
+metadata. `--max-bytes` may lower it. `maxDocuments` bounds the selected source
+count, and `maxSourceBytes` bounds each selected file read. A source that cannot
+fit is omitted whole, preserving qualifications rather than clipping them.
+Any omission warrants inspecting coverage. No match means `needs-evidence`,
+not a claim that the real-world fact does not exist. When search misses a
+qualification that a source owner has selected, a trusted host can read the
+complete cited unit exactly from an ingestion plan that includes the source
+with a completed attempt; see
+[read a complete selected citation](evidence-navigation.md#read-a-complete-selected-citation).
+The line locations in this packet are not ingestion `line` locators: ingestion
+also splits on a lone CR and removes a leading BOM (U+FEFF). Map them
+explicitly; a wrong mapping fails safe, because the hash check withholds the
+selection.
+
+The graph builder still censuses the configured workspace before selection.
+This byte cap is not a corpus processing or wall-time limit. Use the project's
+existing include/exclude scope for large collections.
+
+Payload bytes are measured exactly. `estimatedTokens` is only
+`ceil(UTF-8 bytes / 4)`; it is not a tokenizer count or a safe model token limit,
+particularly across languages. Actual tokens, provider cost, and human
+correction time remain unknown until measured. Count initial ingestion,
+retries, review, retrieved context, output, and amortized reuse. Never add
+cached input to a provider's inclusive input count twice.
+
+## What evaluation proves
+
+`evaluate` runs lexical and graph modes with identical questions and budgets.
+Expected ids and digests are used only **after** retrieval. It reports evidence
+recall, missing sources, stale expected revisions, missing directed relations,
+payload bytes, and omissions. It exits 1 when graph mode misses an expected
+case or the case pins are stale. An abstention case requires no matching
+candidates and no omissions. Matching evidence that was omitted yields
+`abstain-unverified`, fails the case, and keeps the dashboard in Deepen.
+Evaluation includes candidate counts and the bounded omission details; it
+checks retrieval behavior, not a model's ability to abstain.
+
+The example deliberately shows that adding necessary evidence can **increase**
+context size. A smaller packet with a missing decisive qualification is not
+an improvement. Compare the least expensive approach that meets the quality
+floor, then measure whether it helps actual work. This tool cannot establish
+answer correctness, consent, ontology quality, causal benefit, operational
+acceptance, or token savings from a passing structural check.
+
+## Growing from a supported result
+
+Keep the source-to-answer trace usable first. Add richer extraction only for
+demonstrated missing meaning; keep proposals reviewable. Add incremental
+processing when repeated parsing dominates measured cost, with exact source
+revision and ontology-version invalidation. Add another engine when it improves
+the same reserved cases enough to justify its full cost and correction burden.
+Add recipient expression only with separate permission checks and a bounded
+serializer. Existing review, coauthoring, intake, and optional decision APIs
+remain separate capabilities with their own contracts.
+
+For sustained value, link the reviewed decision to the actual action, observed
+consequence, and a later appropriate use or non-use. Evaluate usefulness and
+care alongside costs; no count of nodes, edges, or retrieved tokens substitutes
+for that evidence.
+
+## Guided dashboards and coauthoring
+
+Use `atelier dev --knowledge` after graph/build to work through Onboard, Model,
+Deepen, Apply, and Learn. The browser and `knowledge session` CLI share
+source-bound private drafts, confirmation, and recovery. See
+[knowledge workspaces](knowledge-workspace.md) for the complete flow and limits.
+
+## Recording a host's semantic extraction
+
+`atelier knowledge semantic` records an extraction that your own tool or model
+ran, so a receiver can review it against the exact source. Atelier never runs
+the extraction. The runner, its request shapes and the receiver journey are
+described in [semantic operation](semantic-operation.md); this section covers
+the command.
+
+- Run it in the Git workspace where `atelier ingest` planned and ran the
+  sources. Each call reads one JSON object from stdin, at most 256 KiB:
+  `{"workspaceId": "...", "run": "<knowledge domain run>", "request": {...}}`.
+- Operations: `begin`, `status`, `reconcile`, `complete`, `proposals`,
+  `contribution` (prepareContribution), `relation` (prepareRelation), `record`,
+  `cascade`, `context` and `project`.
+- `request` holds exactly the operation's fields. Optional fields are `limit`
+  for `proposals`, and `supersedes` with `revisionReason` for `contribution`.
+  Every field has a declared kind: text, an object, an array, an integer
+  `limit`, `kind` as one of `entity`, `assertion` or `unknown`, and
+  `supersedes` or `revisionReason` also as `null`. Any other field, a missing
+  or null required one, or a value of the wrong kind refuses as
+  `SEMANTIC_OPERATION_INVALID` and writes nothing. Formats such as timestamps
+  and digests are checked by the runner, which may already have captured raw
+  output by then. The command closes every request; the internal library
+  closes only `begin` and some nested values, so library callers do not get
+  this check.
+- Success prints the operation's JSON result. A failure prints
+  `{"ok": false, "code": "SEMANTIC_...", "error": "..."}` on stderr and exits 1:
+  - the operation's own refusals keep their `SEMANTIC_*` code;
+  - when the runner attached a saved ledger write or captured raw output to the
+    failure, it carries `recorded` or `captured` with a `nextAction`, under the
+    runner's own code, or `SEMANTIC_OPERATION_INTERRUPTED` when the error had
+    none. Reopen the same operation rather than running the extraction again.
+    A few runner paths can still fail without attaching that detail;
+  - Atelier's other refusals, such as an invalid digest or a directory that is
+    not the Git workspace, are coded `SEMANTIC_OPERATION_REFUSED`.
+
+  A failure whose text could reveal host detail and that saved nothing is
+  reported by the command runner instead, without host detail: as
+  `[internal-error]`, or as `[code] message` for Atelier's lowercase codes.
+- Receiver records submitted through `record` are the caller's assertions:
+  Atelier checks their consistency but does not authenticate who made them.
+- Raw output travels inside the 256 KiB request as UTF-8 text, so larger raw
+  output cannot be recorded through the command yet.
+- Known limits from the runner's review stay: contradictory host declarations
+  across the ledger and intake can lead to two executions, found afterwards,
+  and a detected contradiction cannot yet be resolved. Neither is hidden by the
+  command.