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

package/docs/install.md

@@ -34,19 +34,19 @@ The registry is the distribution channel of record, as `docs/continuity.md`
 commits:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.13
 ```
 
 Installing from the matching Git tag resolves to the same reviewed commit:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.13"
 ```
 
 Or over SSH:
 
 ```bash
-npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
+npm install --save-dev "git+ssh://git@github.com/MNSTRY/atelier.git#v0.2.0-alpha.13"
 ```
 
 Keep the `@mnstry/` scope — see the command-form note above for why the
@@ -165,6 +165,9 @@ Generate `graph` and `project` output before starting the preview. Existing laun
 configs are not rewritten by these template changes. Append server arguments
 following a `--` separator after the configured Node arguments. The host process
 lifecycle still needs qualification before relying on preview restarts.
+A repository that tracks `.html`, `.pdf` or `.docx` files needs a sidecar for
+each before its first graph; see
+[documents in an adopted repository](#documents-in-an-adopted-repository).
 
 Upgrade planning and application use the same optional `gh api user` fallback
 as ordinary boundary checks. Supply a valid explicit selector or mapped identity
@@ -202,6 +205,80 @@ atelier readiness export --dry-run --project ./atelier.project.json
 
 These commands read local files and write generated local outputs only.
 
+### Documents in an adopted repository
+
+The knowledge graph reads every `.md`, `.html`, `.pdf` and `.docx` file that
+Git does not ignore. Markdown carries its own metadata. Each of the other
+three needs an adjacent `<file>.kg.json` sidecar, and `atelier graph` fails
+until every one has one. A vault with a PDF attachment, a static website or a
+folder of documents therefore fails its first graph after `adopt`.
+
+`atelier enroll documents` writes the missing sidecars:
+
+```bash
+atelier enroll documents --dry-run   # list what would be written
+atelier enroll documents             # write them
+atelier graph
+```
+
+Each sidecar is the smallest classification that lets the graph pass: the
+document's title (an HTML page's `atelier:title` or `<title>`, otherwise its
+file name), an empty summary and tag list, no relations, the domain,
+lifecycle and status the graph already infers from the path, the id
+`<repo>:asset:<path>`, and the audience `private`. Two paths that fold to the
+same id, such as `About Us.html` and `about-us.html`, each get a short digest
+of their exact path. Enrollment never changes a sidecar that exists, including
+one Git ignores or a link with the sidecar's name, and never changes a
+source. It reads only what the graph reads (for HTML, the page's title), so
+it honors the scope below and Git's ignore rules.
+
+`--audience` chooses another audience. The repository's boundary policy must
+allow it: a shared repository forbids `private`, so it needs, for example,
+`--audience team`. A policy in `legacy-warning` mode only warns. Review the
+sidecars, then commit them with the sources.
+
+`atelier adopt --enroll-documents [--audience AUDIENCE]` adopts and enrolls
+in one step. The audience is checked against the policy before adoption writes
+anything.
+
+### Scoping what the graph reads
+
+Decision (2026-09-25): a project-level scope for tracked paths belongs in
+`atelier.project.json`, and it already has a place there: `setup.include`
+and `setup.exclude`, which `adopt --include` and `adopt --exclude` record.
+
+- Git's ignore rules cannot leave out a tracked file, and should not be asked
+  to: ignoring a committed build folder would hide it from Git as well.
+- The scope must be tracked. The graph is committed, so it has to come out the
+  same on every machine; that is why Git-ignored paths are skipped. A scope in
+  `atelier.local.json` or `.atelier-local/` would make it differ per machine.
+- The v1 project config contract already declares both fields, one path each.
+  Adoption wrote them and the `monorepo` profile requires `--include`, but
+  until this release nothing read them. Giving them their meaning does not
+  widen the contract. A new field, or a list, would widen a closed object,
+  which [contract stability](contract-stability.md) makes a new major version.
+
+Each value is a path pattern relative to the folder that holds
+`atelier.project.json`, in the dialect the boundary policy's `forbiddenPaths`
+uses: `*` stays within one folder name, `**` crosses folders, case does not
+matter, and a pattern without a slash matches a name at any depth (`_site`
+leaves out every folder named `_site`). A path is outside the graph when it
+or a folder above it matches `exclude`, or, when `include` is set, when
+neither it nor a folder above it matches `include`. `exclude` wins. A sidecar
+follows its source. A path outside the graph is treated exactly like a
+Git-ignored one: no node, no sidecar demand, no orphan-sidecar error, and it
+cannot be a link target or an embedded asset.
+
+```json
+{ "setup": { "profile": "single-repo", "exclude": "_site" } }
+```
+
+Use `exclude` for tracked material that is not a source, such as a built
+site. Use `atelier enroll documents` for documents that are sources. Each
+field holds one pattern in v1; if one is not enough, open an issue, since a
+list is a contract change. A project that already sets either field now gets
+a graph over that scope: run `atelier graph` and commit the result.
+
 ## Upgrade path
 
 The starter commands create `atelier.lock.json` inside the copied workspace so

package/docs/intake-and-guides.md

@@ -30,6 +30,11 @@ structure, missing-asset evidence, and format-specific completeness checks.
 Do not flatten a conversation export merely to satisfy a text-output API.
 Packet authoring can proceed before corpus ingestion.
 
+The [progressive ingestion proposal](progressive-ingestion.md) describes a
+possible coverage, routing and incremental-processing layer over this store.
+It is a design proposal; those orchestration capabilities are not supplied by
+the current intake API.
+
 ## Guides and private implementations
 
 `@mnstry/atelier/guides` and the guide schema define portable offers, inert

package/docs/integration-contract-decisions.md

@@ -1,5 +1,25 @@
 # Integration contract decisions
 
+## Responsibility architecture
+
+The [responsibility architecture](architecture.md) is the canonical naming and
+composition model. Keep existing source/API identifiers as compatibility
+surfaces. Responsibilities, roles, methods, resources, records and hosts have
+distinct kinds and typed relationships. This decision adopts the architecture
+direction; it does not declare every consumer implemented or qualified.
+
+Use additive contracts for architecture bindings, practical cases, native ADR
+snapshots and instruction adoption. Existing learning, intake, knowledge and
+capability stores retain their domain ownership. Native ADR identity and
+approvals remain with the repository that issued them. An imported decision
+never becomes a new local approval automatically.
+
+Preview and runtime must map authored fields to the same relevant domain rules.
+Unsupported required behavior is a visible resolution failure. Installation,
+actual loading, operation execution, durable readback and behavior assessment
+remain separate evidence. Reconsider this architecture if a proposed workflow
+requires a competing domain writer or an unrelated mandatory stage.
+
 <!-- mnstry-review-workflow: atelier-integration-implementation-r1 gate: implementation-readiness stage: closing -->
 
 These decisions implement the first local integration cut. They do not satisfy
@@ -12,8 +32,10 @@ independent review, publication or human acceptance.
 | Claim decision | Separate immutable decision aggregate and contract | Never insert new event types into legacy proposal aggregates. Stable request identity and expected version are mandatory. |
 | Document response | Separate passage-bound record | A question/correction is not a semantic claim or agreement. |
 | Owner handoff | Derived proposed change | No canonical apply or publication authority; cross-repository Git disclosure is a distinct event. |
-| Inspection bundle | Separate inert artifact; reuse disclosure/JCS | No active-state overwrite, execution, secret transfer or approval import. |
-| Pack compatibility | New versioned lifecycle declaration | Legacy packs remain inspectable; closed v1 contracts are not silently widened. |
+| Inspection bundle | Separate inert artifact; reuse disclosure/JCS ([inspection-bundle.mjs](../src/collaboration/inspection-bundle.mjs); [prepareInspectionBundle](../src/collaboration/inspection-bundle.mjs#L37-L105)) | No active-state overwrite, execution, secret transfer or approval import ([prohibitedKeys](../src/collaboration/inspection-bundle.mjs#L16-L36), [inspectBundle](../src/collaboration/inspection-bundle.mjs#L106-L197), [read and write paths](../src/collaboration/inspection-bundle.mjs#L198-L223)). |
+| Pack compatibility | New versioned lifecycle declaration ([lifecycle.mjs](../src/extension-packs/lifecycle.mjs); [inspectPackLifecycle](../src/extension-packs/lifecycle.mjs#L14-L121)) | Legacy packs remain inspectable; closed v1 contracts are not silently widened ([legacy packs inspectable; closed declaration and entries](../src/extension-packs/lifecycle.mjs#L14-L121), [rootVersion](../src/extension-packs/lifecycle.mjs#L7-L12)). |
+
+<!-- Whole-file citations here rely on decision-practice definition revision three, which drafts on added as well as modified or removed lines. Uncited: Package provenance, Evidence snapshot, Claim decision and Document response await symbol-level citation support in the decision-practice consumer. -->
 
 Reuse existing private-file, ledger, origin/nonce, JSON validation and
 attestation primitives where applicable. Decisions retain complete history;

package/docs/interaction-and-reflection.md

@@ -0,0 +1,72 @@
+# Interaction and Reflection
+
+Companion supplies the qualities and behavior of an interaction. Witness offers
+revisable reflection on a person, work, an interface or a system. Coaching is an
+optional mode tied to a chosen intention. One host owns the conversation floor,
+effects and delivery; neither role creates a second conversation or personal
+profile store.
+
+The portable `@mnstry/atelier/reflection` API validates attributed observations
+and assessments, qualifies exact evidence revisions, and prepares reflective
+acts. An observation reports what a source says; an assessment interprets it.
+Qualification checks provenance references, scope, purpose, withdrawal and
+assistance. It does not determine semantic truth, psychological state or learning.
+A system-friction assessment cannot become a claim of personal incapacity.
+Independent-capacity claims require independent evidence about the same person,
+and still remain attributed judgments with uncertainty and limits.
+
+Correcting or withdrawing an observation changes its reference. Dependent
+assessments and queued acts then become unavailable until deliberately revised.
+Several assessors may disagree. The caller retains their histories and owns
+correction, withdrawal, export and retention. This module does not silently
+persist a personal model, enable monitoring, erase source records or publish them.
+
+## Typed acts and interaction policy
+
+An act has an origin, purpose, scope, semantic meaning, wording, dependencies,
+mode and expiry. Ask, explain, reflect, propose, challenge, acknowledge and repair
+remain separate from delivery. A change in meaning or wording produces a changed
+act digest and requires a new delivery identity rather than replaying an old ID.
+
+Policy expresses Reflection/coaching availability, challenge, initiative,
+pacing and communication criteria. The selector enforces scope, current evidence,
+expiry, floor, pause and enabled modes. Clarity, warmth, candor, attribution,
+uncertainty and repair are surfaced evaluation criteria. Their presence does not
+prove that generated language exhibits them; representative human assessment is
+still required. Ordinary work and Companion acts function with Reflection off.
+
+`selectInteractionAct` returns selected, deferred or declined with reasons.
+Selection grants no effect authority. Orientation pins for chosen intentions
+and preferences come from their native owner; a name match cannot join contexts.
+An empty current context supports ordinary conversation without tracking.
+
+## Host delivery contract
+
+`createInteractionController({authorityId, host})` requires one host with:
+
+| Method | Responsibility |
+| --- | --- |
+| `current()` | Return current policy, scoped observations/assessments/orientations, interaction state and time |
+| `authorize(exactAct)` | Apply the existing host effect authority to the exact act digest, scope and purpose |
+| `reserve(delivery)` | Durably reserve an idempotency key and serialize access to the conversation floor; return `created` |
+| `send(delivery)` | Emit the exact text, observe interruption, and retain actual partial/full native delivery state |
+| `read(key)` | Read the native reservation/delivery receipt, including key, authority, act digest, status and delivered text |
+| `interrupt(request)` | Stop/reconcile the native effect and retain actual partial delivery |
+
+Reservations must be durable and exclusive across controllers and processes.
+The host rechecks its own live scope, authority and floor at emission and serializes
+competing deliveries. The controller's pre-send recheck is additional protection,
+not a replacement for atomic host admission. No raw network sender is included.
+
+Receipt statuses are reserved, begun, completed, interrupted, failed and unknown.
+A new controller reads an existing reservation instead of emitting again. Unknown
+or interrupted output requires native reconciliation; automatic retries cannot
+duplicate guidance. Readback must match the exact act and actual text prefix.
+Completed delivery requires the complete text, and proves neither understanding
+nor improvement. Repair is a separately selected act with its own identity.
+
+The reference tests use a file-backed host to exercise actual partial output,
+interruption, repair, controller restart, changed evidence and a lost response.
+This qualifies orchestration against that test adapter. Production conversation
+hosts, voice output, persistent personal tracking and human communication quality
+need their own adoption and acceptance evidence.

package/docs/knowledge-graph.md

@@ -5,6 +5,11 @@ source material. It is not a taxonomy and it is not runtime retrieval. It is a
 durable model of source nodes, evidence, relationships, diagnostics, and
 projection readiness.
 
+For setting up useful domain concepts and testing whether the graph helps answer
+work questions, follow [knowledge setup](knowledge-setup.md). It builds on this
+canonical source graph and keeps domain concepts, source types, semantic
+acceptance, and runtime authority distinct.
+
 ## Source Rules
 
 - Markdown documents may use front matter. A document with no `kg` block is
@@ -77,6 +82,21 @@ The check is one batched `git ls-files --others --ignored --exclude-standard
 --directory` per repository root, not a per-file `git check-ignore`, which is
 too slow to survive contact with a real workspace.
 
+The project can also scope the census from its tracked config:
+`setup.include` and `setup.exclude` in `atelier.project.json` are path
+patterns relative to the config's folder, and a path outside that scope is
+treated exactly like a Git-ignored one (no node, no sidecar demand, no orphan
+error, no link or embed target). A sidecar follows its source. The scope is
+tracked for the same reason ignored paths are skipped: every machine must walk
+the same files. The rules and the decision behind them are in
+[install](install.md#scoping-what-the-graph-reads).
+
+`atelier enroll documents` writes the sidecar the census demands of every
+non-Markdown document that has none, as the smallest classification that
+lets the graph pass (audience `private` unless `--audience` says otherwise and
+the boundary policy allows it). It reads the same census as `atelier graph`,
+never changes an existing sidecar, and never changes a source.
+
 Repository *discovery* is deliberately not filtered this way: a git folder that
 appears in the workspace is an explicit decision for the operator to make (see
 the `external` repo kind), not something to drop silently.

package/docs/knowledge-health/api.md

@@ -0,0 +1,30 @@
+# Additive integration reference
+
+The [additive module sources](../../src/knowledge/participatory/index.mjs) accept the host's already received APIs. They create no editor, store, parser, accepted ontology or application route. The owning package must bind its supported public export before offering these functions to installed callers. This reference supplies no unsupported deep-import instruction.
+
+```js
+// Host composition after native/public receiving; the release owns the import.
+const guided = createGuidedContribution({
+  adapter: existingSourceBoundContributionAdapter,
+  caller: existingNativeKnowledgeHealthCaller,
+  same: existingCanonicalEquality,
+});
+const prepared = guided.prepareChoice({
+  joined: freshValidatedFindingJoin,
+  editorState: currentNativeEditorState,
+  contributionId: hostContributionId,
+  choiceId: hostChoiceId,
+  originalWords: exactParticipantWords,
+  interpretation: separateProposedInterpretation,
+  outcome: explicitParticipantOutcome,
+  participantChoice: actualParticipantChoice,
+});
+```
+
+The result is `chosen-not-retained`. The native caller's `retainDisposition` performs the existing two append steps and independent readbacks. Bind its `writeContribution`, `readContribution`, `writeDisposition` and `lookupDisposition` to the current native actor/source boundary. `checkDisposition` resolves an unknown result by lookup; `retryDisposition` requires an explicit retry with the same full record after checked absence. The adapter verifies source, saved passage and field; the owning host still checks currency and permission at effects.
+
+`exampleRevision({joined,contribution,proposalId,changeId,decisionId})` creates only the invented workshop's proposed supporting-array change. It refuses another source, field or directed relationship. The output contains a native proposal and `selected-not-applied` intent. Receive the actual contribution/proposal, show the native preview, and obtain the participant's explicit selection before native `recordDecision` and draft `apply-selection`. Preparing an example proposal does not authorize either write. Native provenance rules still govern assistant responses; this proposal is labeled `invented-example-proposal`.
+
+`guidanceFor(stage)` supplies concise copy and an existing-host navigation intent. `createGuidanceCue({React,Button})` renders that cue with the existing Runtime Button. It creates no input or editor. The host selects the cue from its validated state and decides whether a corresponding action is available; the cue grants no effect permission. Keep one stable cue ID, the existing editor key and the normal return-focus path. `onAction` requests navigation/check intent only; pending save has no action. Do not infer successful retention, source application or reassessment by advancing a step number.
+
+For another repository, bind its real declared sources and supported check, field, saved occurrence, actor/store/head and normal source-writer route. Reassess after any source or evidence change. An unresolved mapping remains unsupported; do not match titles, translate old ranges, infer an ownership grant or reuse the workshop change generator on real material.

package/docs/knowledge-health/assessment/api.md

@@ -0,0 +1,96 @@
+# Assessment API and existing commands
+
+The additive `@mnstry/atelier/knowledge-health` export joins existing checker,
+graph, parser and bounded context implementations. It adds no graph rule,
+canonical model, editor/store, provider dispatch or root CLI.
+
+```js
+import { resolveProjectConfig } from '@mnstry/atelier/project'
+import { assessKnowledgeHealth } from '@mnstry/atelier/knowledge-health'
+const project = resolveProjectConfig({
+  cwd: workspace, argv: ['--project', projectConfig], writeLocalState: false,
+})
+const result = assessKnowledgeHealth({
+  project, planPath: 'knowledge-plan.json',
+  relationId: 'checklist-pilot', questionId: 'readiness',
+  sourceRevisions, binding, currentSourceBytes,
+})
+```
+
+Those workspace/binding variables are caller inputs. The installed public
+`initializeKnowledgeHealthExample` / `assessKnowledgeHealthExample` helpers
+provide a complete invented invocation. The [example implementation](../../../src/knowledge-health/example.mjs)
+shows its data binding; callers import the supported public entry above.
+
+`sourceRevisions` is an explicit `[{repo,path,revision}]` entry for every censused
+source. A binding contains:
+
+```json
+{
+  "source":{"id":"demo:checklist","repo":"records","path":"checklist.md","sha256":"CURRENT_SHA256","revision":"OWNER_REVISION"},
+  "field":{"id":"kg.relations.supports","pointer":"/kg/relations/supports","format":"markdown-inline-array","start":0,"end":2,"quote":"[]"},
+  "authoring":{"storeId":"EXISTING_STORE","sourceId":"demo:checklist","artifactId":"EXISTING_ARTIFACT","fieldId":"kg.relations.supports","actorBindingId":"EXISTING_ACTOR_BINDING"}
+}
+```
+
+The offsets above are placeholders. Supply exact half-open UTF-8 offsets in
+current source bytes, the owner's revision and existing authoring identity. The
+parser probe proves the range addresses that declaration rather than matching
+prose or another field. Only typed inline Markdown relation arrays are supported.
+Wrong quotes, source pins, missing IDs, prose or unsupported profiles refuse.
+Resolve project config again after it changes. Config/access/plan changes during
+a read refuse. Effective resolved repository bindings join the scope digest.
+The plan ceiling is 65,536 bytes; project/access ceilings are 1 MiB each.
+
+| Result field | Meaning |
+| --- | --- |
+| `assessment` | Original native report/diagnostics/context, exact source/rule/read-set/declaration evidence, selected findings, coverage/currency and refusals. |
+| `retrievalEvaluation` | Native graph-versus-lexical evaluation against frozen explicit expectations. Expected IDs never enter retrieval. |
+| `context` | Existing-output projection with observations/denominators, provenance and explicit semantic/repository unknowns. It is not an accepted canonical. |
+
+Complete current evidence produces native `needs-attention` or
+`structurally-valid`. Omissions produce `partial` with no actionable edit target;
+binding/evidence refusals produce `uncertain`; native invalid plan/graph produces
+`invalid`. Both native invalid-report shapes remain original. None establishes
+source rights, meaning, source application, human acceptance or repository use.
+
+`createAssessmentProjector` is also available for qualified injected callers. It
+requires original checker commit/tree/blob/source/schema/graph identities, raw
+plan bytes, exact read-set/scope, native graph/context and the same owner binding.
+Optional native evaluation makes stale expected pins a refusal for an
+evaluation-dependent task. The workspace join reports structural reassessment
+and frozen evaluation separately, preserving both facts after a correction.
+
+`knowledgeHealthContext({assessment,graph,planBytes,agentSuggestions,
+repositoryEvidence})` verifies exact native graph and raw plan digests. Suggestions
+require bounded nonempty text, selected-source citations and provenance
+`{actorId,method,version,recordId,planSha256,readSetSha256}`. They remain supplied,
+unreviewed and semantically unknown; no provider runs. Repository evidence remains
+caller-supplied/unverified and never infers declared/adopted/consumed/executed.
+
+Graph digests include native location-dependent options. Relocation changes that
+digest; source/read-set/field pins remain independently visible. Repeating the
+same bounded workspace inputs is deterministic. Changed source/scope/rules
+invalidate comparison identity; a package version alone cannot pin rules.
+
+Existing corresponding-source commands are:
+
+```sh
+atelier knowledge check --project ./kh-example/atelier.project.json --plan knowledge-plan.json
+atelier knowledge context --project ./kh-example/atelier.project.json --plan knowledge-plan.json --question "What supports pilot readiness?" --mode graph
+atelier knowledge evaluate --project ./kh-example/atelier.project.json --plan knowledge-plan.json
+atelier graph --project ./kh-example/atelier.project.json
+atelier graph --check --project ./kh-example/atelier.project.json
+```
+
+`graph` writes a generated artifact; `--check` tests its exact freshness. The
+legacy artifact keeps declared edges; the canonical API exposes ordinary links
+and their origin too. Neither ordinary links nor reverse edges satisfy this rule.
+`knowledge check` exits nonzero for invalid inputs/graph; `ok:true` may coexist
+with warnings. Set CI warning policy explicitly. `knowledge evaluate` exits
+nonzero for missing/stale graph-mode expected evidence. Omitted evidence can
+yield `abstain-unverified`, not a verified answer.
+
+There is no `atelier knowledge-health` command here. Use the public API and
+[capability map](capabilities.md), which distinguishes inspected source commands
+from executed supplier tests and published baseline availability.

package/docs/knowledge-health/assessment/capabilities.md

@@ -0,0 +1,40 @@
+# Capability map and retained tooling needs
+
+`KNOWLEDGE_HEALTH_CAPABILITIES` from the public assessment entry contains exact
+source commit/tree/blob/file references, baseline availability, verification
+scope and smallest receiving corrections. It is an inventory projection, not
+release certification or semantic/human acceptance.
+
+| Need | Actual existing surface | Evidence and limit |
+| --- | --- | --- |
+| Graph structure | `./graph`: `buildCanonicalGraph`, `createGraphFileCache`; `graph` / `graph --check` | Native API used in this receiving rehearsal; public alpha.12 includes canonical graph. Legacy generated artifact has declared edges only. |
+| Typed relation | Internal `inspectKnowledgePlan`; current `knowledge check` | Actual existing checker used; alpha.12 lacks knowledge-plan modules. Additive API joins it without rewriting rules. |
+| Agent-readable evidence | Internal `createKnowledgeContext`; current `knowledge context --mode graph|lexical` | Native function used. Source bytes/digests, census, omissions and resource limits retained; no provider execution or recipient-sharing authority. |
+| Task evidence/abstention | Internal `evaluateKnowledgeQuestions`; current `knowledge evaluate` | Native function used. Expected pins stay outside retrieval. It does not judge answer meaning or unseen/human value. |
+| Ingestion evaluation | Current `./ingestion/evaluation`: `evaluateIngestionTrial`, `ingestionEvaluationDigest` | Actual evaluator used on invented calibration. Exact multiset scoring and null costs; no held-out/semantic pass. Alpha.12 lacks this module. |
+| Local extraction/proposals | Current `./ingestion`: `createIngestionStore`; `ingest plan/run/status/query`; current `./knowledge` contribution/context helpers | Static inspection. Bounded local text/CSV/JSON and lexical evidence; no semantic acceptance or raw graph enrollment. |
+| Semantic lifecycle | Internal `createSemanticOperation`, dependency witnesses and reconsideration | Static only, not a public knowledge export here. Owner-bound recorded callbacks remain proposal-only; acceptance pending. |
+| Repository freshness | `./runtime/observation`: `observeRepository`, `validateRepositoryObservation`; owning `sync status` / `sync trace` | Public baseline file/export verified, current source inspected. Git/runtime observation cannot prove adoption/consumption/execution, causal lineage or remote freshness. |
+| Repository handoff | Current `./harnesses`: `inspectHarness`, `createHarnessHandoff`, `verifyHarnessHandoff`, `reconcileKnowledge`; `harness inspect/verify` | Static only. Complete ledgers and explicit dependency snapshots; actual adopter/execution evidence separate. |
+| Readiness/freshness | `./readiness`: `buildReadiness`; `readiness --check`, `generated check` | Public baseline verified, source inspected. Existing artifact/schema/freshness checks do not establish source meaning or human value. |
+| Authoring/hosts | `./coauthor`: `createSession`, `transition`, `replaySession`; existing store/presentation/runtime/Obsidian; current knowledge dashboard/session and sidecar | Static only in this supplier. Mounted editor/store owns apply/save; native and participant proof separate. |
+| Normal initialization | Current `atelier init --template knowledge-workspace --target ./workspace` and its shipped template | Source dispatch inspected; public alpha.12 lacks this dispatch/template. Test both from the exact official new archive and published version. The explicit fixture helper is not that test. |
+
+Keep S2–S5 tooling work visible:
+
+- **S2:** qualifiers, contradiction/identity, optional bounded agent cost/value,
+  private perspectives and scoped learning. Reuse native semantic/contribution,
+  evaluation and learning primitives; human source-supported trials remain open.
+- **S3:** declared/adopted/consumed/executed traces, drift, partial refresh,
+  withdrawal/recovery. Join actual observation/runtime/harness evidence. This
+  context defaults all four use stages to unobserved.
+- **S4:** other hosts/media/domains, keyboard/IME/zoom/text scaling, accessible
+  graph alternatives and purposeful scale. Existing source-format,
+  presentation/runtime and budgets are starting points; installed measurements
+  remain host-specific. This proof is Node22/macOS only.
+- **S5:** ownership, documentation, rollback/recovery, maintenance and complete
+  programme closure. A public kit is an input to those journeys, not their proof.
+
+Preserve source evidence, structure, interpretations, proposals, owner decisions
+and execution as distinct records. Reuse existing canonicals and one editor/store
+write boundary. No replacement graph, health score or canonical registry is added.

package/docs/knowledge-health/assessment/evaluation.md

@@ -0,0 +1,27 @@
+# Recorded calibration and broader evaluation
+
+This public invented recorded trial uses the existing ingestion evaluator. It
+runs no processor, provider or held-out bank:
+
+```sh
+node --input-type=module -e "import {evaluateKnowledgeHealthCalibration as evaluate} from '@mnstry/atelier/knowledge-health'; console.log(JSON.stringify(evaluate(), null, 2))"
+```
+
+The [suite](../../../fixtures/knowledge-health/calibration-suite.json) expects one
+evidence item; the [trial](../../../fixtures/knowledge-health/calibration-trial.json)
+returns it twice. Native scoring reports one matched and one unexpected item.
+Cost remains null, human verdict unassessed, semantic qualification not-assessed.
+Calibration-only cases cannot pass held-out qualification.
+
+For a recorded evaluation, use the existing `./ingestion/evaluation` exports. Pin
+suite/processor/configuration/sources; retain exact evidence locators/text,
+outcome, attempts, measured latency/cost and any human-assessment provenance.
+Unknown measurements stay unknown. This evaluates extraction evidence, not
+semantic support or authenticated human judgment.
+
+`knowledge evaluate` separately compares graph versus lexical retrieval using
+the typed plan's frozen expectations. Measure actual answer support, qualifiers,
+contradiction/identity and correction effort through an authorized semantic/human
+trial. Supplied agent suggestions can retain exact citations/provenance but
+cannot accept canonical truth. See [capabilities](capabilities.md) for the broader
+repository/host/maintenance work.

package/docs/knowledge-health/assessment/facilitator.md

@@ -0,0 +1,30 @@
+# Assessment exercise run sheet
+
+Before the session, pin the published version and rehearse [quickstart](quickstart.md)
+in a fresh npm consumer. Verify the export and fixture/docs inventory in that
+exact artifact. Declared Node ranges exceed this supplier's Node22/macOS proof;
+test the intended host, Git and editor. Record npm integrity/readback and installed
+journey evidence separately from a local archive check.
+
+1. Let the participant read both sources and describe the useful decision and
+   remaining qualifications.
+2. Run assessment and navigate native message, exact declaration and selected
+   source evidence. Explain task scope and direction.
+3. Invite their own words, interpretation, disagreement, perspective-only or
+   pause. Keep these separate from source truth.
+4. Preview the one-field revision; let the participant choose whether to apply
+   it through the owning editor. Save and reopen.
+5. Rerun; compare finding/pins and unchanged caveats. Inspect stale frozen
+   expectations as an independent evaluation fact.
+6. Record actual understanding, usefulness, confusion and correction effort.
+   Automated tests cannot establish these human outcomes.
+
+Predict and test a reverse edge, ordinary link, baseline restoration or bounded
+source omission. No model execution is needed. Use existing host contribution
+and save routes for a guided editor; verify original words, preview/refusal/pause,
+apply/readback/reopen/reassessment in that actual mounted host before claiming
+support. This kit supplies assessment/evidence, not host acceptance.
+
+Retain participant consent/audience boundaries, baseline/result identities and
+feedback. [Evaluation](evaluation.md) and [capabilities](capabilities.md) preserve
+semantic, actual repository, cross-host/accessibility/scale and maintenance gaps.

package/docs/knowledge-health/assessment/quickstart.md

@@ -0,0 +1,61 @@
+# Source-bound Knowledge Health exercise
+
+Use a local Git workspace and a pinned Atelier release that includes
+`@mnstry/atelier/knowledge-health`. Atelier declares Node
+`>=22.18.0 <23 || >=24.13.1 <25`; this supplier rehearsal used Node22.18 on
+macOS. Git must be on PATH. The invented public exercise needs no model account.
+
+Replace `VERSION_FROM_FACILITATOR` with the exact workshop release version:
+
+```sh
+npm install --save-exact @mnstry/atelier@VERSION_FROM_FACILITATOR
+node --input-type=module -e "import('@mnstry/atelier/knowledge-health').then(m => console.log(typeof m.assessKnowledgeHealth))"
+```
+
+The import should print `function`. Public alpha.12 does not include this export,
+knowledge-plan/context modules or the normal `knowledge-workspace` initializer.
+See [troubleshooting](troubleshooting.md) if your installed version lacks them.
+
+Create a new disposable directory; the helper refuses an existing directory:
+
+```sh
+node --input-type=module -e "import {initializeKnowledgeHealthExample as init} from '@mnstry/atelier/knowledge-health'; init('./kh-example')"
+node --input-type=module -e "import {assessKnowledgeHealthExample as assess} from '@mnstry/atelier/knowledge-health'; console.log(JSON.stringify(assess('./kh-example'), null, 2))" > before.json
+```
+
+Open `kh-example/records/checklist.md` in your editor. Its typed declaration is
+`supports: []`. The report says `checklist-pilot` has no declared edge in the
+required direction. Inspect the exact source digest/content revision, declaration
+quote and UTF-8 byte range in the finding, the native report in
+`assessment.original.report`, and selected source text in
+`assessment.original.context.sources`.
+
+The source says the pilot has not been approved and no allocation decision is
+recorded. Record your own words and interpretation separately. You may disagree,
+leave a perspective without revising, or pause. The structural report does not
+decide what the source means or require a write.
+
+If you choose the supplied correction, compare your file with the installed
+`fixtures/knowledge-health/corrected/checklist.md`. It changes only the declaration
+to `supports: ["demo:pilot"]`. Apply that change through your existing editor,
+save and reopen the local file. Preserve the body and its qualifications. The
+assessment API itself writes no source.
+
+```sh
+node --input-type=module -e "import {assessKnowledgeHealthExample as assess} from '@mnstry/atelier/knowledge-health'; console.log(JSON.stringify(assess('./kh-example'), null, 2))" > after.json
+```
+
+The current structural report should be `structurally-valid` with zero selected
+findings and one matching declared edge. Its source/read-set/comparison pins
+change; the earlier report remains your baseline. Compare the
+[expected summary](../../../fixtures/knowledge-health/expected-summary.json).
+
+`retrievalEvaluation` still reports the changed checklist as stale against frozen
+baseline expectations. Review and explicitly update an evaluation baseline when
+appropriate; never silently replace expected pins to make it pass. Approval,
+funding, semantic support, adoption and participant usefulness remain unknown.
+
+Use [the API guide](api.md) for an existing source. Example `content-sha256:`
+revisions and invented actor/store labels are fixture evidence, not authenticated
+identity, durable store heads or write authority. The explicit fixture helper
+does not prove normal package `init` or the actual guided editor/save journey.

package/docs/knowledge-health/assessment/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting and recovery
+
+| Observation | Next action |
+| --- | --- |
+| Export/knowledge command missing | Check the exact installed version/export map. Alpha.12 lacks the new seam. Use the facilitator's pinned release, never a private checkout import. |
+| Example directory exists | Choose a new directory; retain earlier source/reports. |
+| Git unavailable | Install Git normally, then initialize a new disposable example. |
+| Rule identity drift | Retain the result and reinstall the exact pinned audited version. Source owner regenerates identity for changed candidates. |
+| Config/scope changed | Resolve current project/repository bindings again; rerun without concurrent config/access/plan edits. |
+| Stale binding/quote | Reopen through the owner, read actual durable head/bytes and rebuild the exact binding. A digest grants no write permission. |
+| Unsupported profile | Use a typed inline relation declaration for this rule. Keep prose interpretation separate; do not invent its relation. |
+| Partial evidence | Inspect omissions/denominators and current availability/scope/resource bounds. Partial context cannot prove absence or semantic failure. |
+| Cleared structure, stale evaluation | Review frozen expectations separately; explicitly authorize a new baseline if needed. |
+| Generated graph stale | Run existing `graph`, then `graph --check` for the same disposable project. This refreshes a projection, not declarations. |
+| Repository use unknown | Use owning observation/runtime/harness records; a local Git head or copied package does not prove adoption/execution. |
+
+Undo the invented correction through your editor by restoring `supports: []`,
+save/reopen and rerun. Keep earlier reports. The finding should return with
+current pins. No automatic source retry/rollback occurs in this API.
+
+An actual host preview/save/recovery failure stays with its existing owning
+operation/head/readback route. Preserve ambiguous-save uncertainty. Native
+undo/IME/focus, installed recovery and participant acceptance remain separate.

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

@@ -0,0 +1,16 @@
+# Atelier Dev Day run sheet
+
+Rehearsal target: Wednesday 7 October 2026. In-person use: Thursday 8 October 2026, Asia/Makassar. This is a planned protocol; no participant result has been observed here.
+
+Before the event, rehearse the exact published version on a clean consumer. Record package version, integrity, tested Mac/Node, normal installed entry, public example and owning source route. Bring the pinned release and verified quickstart. A local tarball run and registry installation are separate records. If the full guided journey is unavailable, disclose that limit and use only the supported baseline exercise; do not present it as the complete delivery.
+
+Allow roughly 25–35 minutes for the exercise, adapting to the participant. Explain that their words, disagreement and decision to pause remain theirs. Ask whether they want their feedback recorded, use a participant code rather than a name, and preserve exact words only within the agreed note custody. They may decline or stop at any point.
+
+1. Ask what the participant currently thinks the source relationship means. Record their explanation and confidence before showing the finding. Ask what evidence would change their view.
+2. Open the installed public example through its normal entry. Let them locate the source passage and supporting evidence. Ask them to explain the finding in their own words, including what the tool cannot establish.
+3. Invite a contribution relevant to the example. Preserve their exact original words. Let them inspect any proposed interpretation and choose agreement, disagreement, perspective-only or pause. Do not reinterpret a pause as acceptance.
+4. Let them inspect the proposed revision and preview. Ask what will change, who owns the write, and what should remain unchanged. Apply only through the example's existing owning route after their explicit choice. Saving words and applying a source correction are different actions.
+5. Verify the exact accepted readback, reopen through the normal entry, and rerun the affected check. Let the participant explain what changed and what remains uncertain. Preserve a historical finding/context rather than relabeling it current.
+6. Ask what was difficult, whether the contribution felt meaningful, and whether the result was useful. Record an exact quotation if they agreed, elapsed time and assistance used. Separate their judgment from facilitator interpretation and automated results.
+
+If a write is uncertain, preserve the original operation ID and full intent. Use the existing original-ID lookup/readback before any admitted identical retry. Keep the interface in an unconfirmed/checking state until readback resolves it. Do not create a new operation ID, erase history or show Saved early. If the owning route cannot resolve it, stop the write step and retain the trace for support.