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

package/docs/guides/co-authoring.md

@@ -0,0 +1,113 @@
+# Co-authoring with agents
+
+A body of work is authored together, in the structure of the work itself
+rather than in a document tool or an email thread. People read and question
+the pages. Agents draft from the graph and the questions. Where the checks
+run in the commit path, every change, by a person or an agent, passes the
+same checks, and that is what makes the agentic
+process (an agent acting inside a governed workflow) reliable.
+
+This page describes the loop, the record it leaves, and what has to be in
+place for it to hold. The files are yours. The package supplies the graph,
+the checks and the collaboration records. The harness supplies the agent.
+Nothing here changes what the package will and will not do to a source:
+README section 4, "The local runtime serves people and agents", states that,
+and the will-not-do block states the rest.
+
+## The loop
+
+Three actors take part: a person, an agent running in the harness, and the
+package. In this loop the package records, checks and refuses; the edit and
+the commit are the agent's or the person's.
+
+1. **A person asks on the page.** A reader selects the sentence they mean on
+   the projected page and leaves a question, a correction or a discussion. The
+   review surface (the package's optional `atelier dev --review`, or a
+   consumer adapter built on the collaboration ledger) records the note and
+   pins it to that passage and to the digest of that revision of the source.
+2. **An agent drafts from the graph.** In the harness it reads the open
+   questions on the file, follows the graph to every file declared to depend
+   on it, and edits those files in the working tree. Where they are wired in,
+   the graph check and the boundary guard run against its work as they would
+   against anyone's.
+3. **A person decides, and the change lands.** The person reviews the draft
+   and, where the workflow records decisions, records one with its rationale
+   through the consumer adapter or the team's workflow. The optional review
+   workspace records decisions on review-run claims, not decisions about a draft
+   change. The package does not require or check a decision before a commit. The
+   person or the agent commits the change through the boundary guard, and the
+   graph and the pages built from it follow on their next build.
+
+The next question starts from the updated source.
+
+## Provenance is built in
+
+The review store pins notes and reading positions to a document's digest and
+the passage they address, and binds decisions to the evidence they judged.
+A contribution made against a stale version is refused. A later decision
+supersedes an earlier one, and the history keeps both. Each record carries the
+name its author gives, which the package records as locally asserted, not
+authenticated. `docs/guides/local-review.md` describes the store and its refusals. When the source changes, earlier notes stay pinned to
+the wording they addressed, so "what has been questioned about this passage"
+is a lookup, not a memory.
+
+A change by an agent passes the same checks as a change by a person: the graph
+check and the boundary guard, where they are wired in. A team that wants every
+change to carry a recorded decision adds that rule to its own workflow; the
+package does not enforce it.
+
+## Giving an agent a job
+
+This section describes the system (the package with a harness and connected
+tools), not the package alone.
+
+You define the outcome and constraints. An agent uses the relevant files,
+works through the task with connected tools and returns work to review.
+Approved changes become part of the shared record for the next task. The
+agent's instructions (its skill and the harness's permissions, not a package
+gate) specify which records it may use, what it may change and when approval
+is required.
+
+The team defines a goal and reviews a proposed plan before the agent starts,
+then reviews the outputs and approves consequential actions. Accepted changes
+update the shared knowledge, so the next task starts from the latest agreed
+material rather than from a fresh briefing.
+
+What has to be connected: the agent, access to the relevant files, and
+whatever other tools the chosen workflow uses,
+plus agreed review responsibilities and action permissions. The package
+organizes source material and review contributions; agent execution and
+external delivery are integrations you configure in the harness.
+
+## What the loop rests on
+
+- **A harness with the skills installed.** `atelier skills sync` installs the
+  package's skill files into the workspace from a digest-confirmed plan (by
+  default from the package's `skills/codex` into `.agents/skills`; `--source`
+  and `--target` change that). Whether a harness discovers and follows them
+  is the harness's matter. See `docs/guides/skill-steward.md`.
+- **Gates in the commit path.** The boundary guard hooks
+  (`atelier boundary install-hooks`) and the graph check in CI. The sentence
+  "every change passes the same checks" is true where the checks run on every
+  commit.
+- **A contribution surface.** The package's loopback projection carries the
+  page and its passages. Its optional review workspace (`atelier dev --review`,
+  described in `docs/guides/local-review.md`) records passage notes and decisions
+  on review-run claims. A consumer adapter built on the collaboration ledger
+  or the team's workflow records decisions about a draft change;
+  `docs/reference/coauthor-session.md` describes the experimental portable
+  session reducer. These records do not apply a source change; the agent in
+  the harness does, and the checks run against it.
+- **Examples with expected results.** By convention, each round of authoring
+  adds reviewed examples with expected results beside the rules they test. The
+  package keeps them and their links in the graph; it does not run them. An
+  agent in the harness runs them against its drafts, and because they stay in
+  the record, a later draft can be checked against the same cases.
+
+## What the package does not do here
+
+It does not draft. It does not apply a proposal to a source. It does not
+grant an agent write access. It does not decide. It records the question,
+checks the change, and records a decision when one is given, and it refuses
+a contribution made against a stale version. The rest is the harness's work
+and the people's.

package/docs/{distributions.md → guides/distributions.md}

@@ -39,7 +39,7 @@ changes what a root command means is a fork, not a distribution.
 Distributions must carry MNSTRY attribution. The normative wording of this
 requirement lives in `TRADEMARKS.md` under "Required attribution" — this
 document deliberately does not restate it, so the two cannot drift. See also
-`docs/attestation.md` for how admission decisions are recorded.
+`docs/reference/attestation.md` for how admission decisions are recorded.
 
 Three related obligations live alongside it:
 
@@ -149,8 +149,10 @@ Workspace projections read
 }
 ```
 
-The "MNSTRY Tenant Readiness" section heading in the rendered projection stays
-as is: it names the bundled MNSTRY pack.
+When the bundled readiness pack is selected, the rendered projection keeps the
+"MNSTRY Tenant Readiness" heading: it names that pack. An explicit
+`readiness.includeBundled: false` in the project's `ext["mnstry.atelier"]` omits
+the section; absent or `true` retains the existing default.
 
 ### 5. Add an extension pack
 
@@ -165,10 +167,13 @@ The manifest carries the advisory attribution key:
 }
 ```
 
-Extension protocols load alongside the bundled twelve; they never replace
-them. Note that pack contributions to the tenant readiness packet ride in an
-unschema'd runtime document (`mnstry.tenant-readiness-packet@v1`) whose shape
-is pinned by tests, not by the versioned contracts the compat gate checks.
+Extension protocols load alongside the bundled twelve by default. A project
+can [deselect the bundle](tenant-readiness.md#select-the-readiness-pack) and use
+only its selected custom protocols; this does not create a replacement tenant
+journey or packet. When the bundle is selected, pack contributions to the tenant
+readiness packet ride in an unschema'd runtime document
+(`mnstry.tenant-readiness-packet@v1`) whose shape is pinned by tests, not by the
+versioned contracts the compat gate checks.
 
 Declared pack paths resolve from the directory holding `atelier.project.json`
 and may not contain `..` segments, so the pack directory has to sit inside the
@@ -216,5 +221,5 @@ a stylistic preference.
 
 A distribution changes branding, not authority. Admission of any payload into
 a MNSTRY destination is decided and recorded exactly as for the root package —
-see `docs/attestation.md` for the admission model and how attestations record
+see `docs/reference/attestation.md` for the admission model and how attestations record
 those decisions.

package/docs/guides/extensions.md

@@ -0,0 +1,189 @@
+# Custom database extensions
+
+Use `atelier extension init --directory ./custom-extension --id sample.counter`
+to generate a TypeScript Postgres backend. The destination must not exist.
+The command writes files only. It creates no database, starts no process and
+grants no access. Apply the emitted migration to a customer-owned PostgreSQL 17
+database with a separate migration role; keep the application login restricted.
+
+The generated backend is a host adapter. Its host supplies the database client,
+verified root public keys, pinned installation/release and an admission origin.
+The server authenticates a short-lived invocation and obtains durable root
+admission before creating its in-process effect scope. The Postgres helper
+keeps a native transaction API and atomically commits custom writes with their
+operation receipts. Credentials and application data stay in the customer backend.
+
+Import portable wire types from `@mnstry/atelier/extensions`, member/admin clients
+from `/extensions/client`, and backend helpers from `/extensions/server` and
+`/extensions/postgres`. Browser clients never import database drivers or server keys.
+The Postgres driver is installed in the generated project, not in Atelier.
+
+Studio installation and member permission are separate. An authenticated host
+owns membership, consent and product access. The manifest declares requested
+capabilities; it grants none. Root-bound results use a separate authorized action.
+The generated `atelier.extension-pack.json` reuses Atelier's canonical pack identity,
+loader and lock adoption. Its namespaced `runtimeManifest` field pins this component's
+manifest file and release digest. The runtime manifest describes the backend protocol;
+it does not create another pack identity. Declare the emitted pack in your existing
+project and adopt it with the normal validation/lock workflow. Pack loading remains
+non-executing and grants no backend or root authority. Standalone hosts can consume
+the portable SDK without an Atelier project.
+
+Use `extension validate --directory ...` to check source/schema/release digests.
+After reviewing an edit, use `extension seal --directory ...` to update them.
+A valid seal identifies bytes; it proves neither publisher trust nor deployment.
+Keep the package lockfile after installation. Lost write replies require explicit
+lookup/recovery; neither client silently retries or refreshes a generation.
+
+Scaffold profiles include postgres-sql, drizzle-db-first, drizzle-code-first,
+prisma-7-postgres and convex-native. Drizzle retains its native query builder and transaction API;
+Prisma retains its native generated client and pg adapter. Convex uses the native
+starter described below. Prisma 8 remains an unqualified separate experiment. Scaffolding, synthetic
+protocol tests, real provider tests, actual supported hosts, public release and
+customer acceptance carry separate evidence. Private runtime bindings are not
+distributed in this package.
+
+The runtime parser is required after JSON Schema validation: it enforces unique IDs and cross-references, recovery scope/effect, current-schema readability, Unicode and total JSON bounds. Native Postgres operation results are capped at 60 KiB inside the transaction, leaving room for the original-operation recovery proof within the 64 KiB action output bound. Every failure after successful admission remains an uncertain operation; inspect its durable receipt before deciding what to do next.
+
+The candidate SDK version 0.2.0-alpha.15 is unpublished. Before its release,
+pack the reviewed Atelier checkout with `npm pack --ignore-scripts` and install
+the resulting local tarball in the generated project with
+`npm install /absolute/path/to/mnstry-atelier-0.2.0-alpha.15.tgz`. Then run
+`npm run typecheck` and reseal the reviewed project. Do not expect the unpublished
+version to install from the public registry. String length limits use Unicode
+code points, matching JSON Schema; ill-formed surrogate sequences remain refused.
+
+The source seal covers package.json, tsconfig.json, src/, present npm lockfiles,
+and present Drizzle/Prisma configuration and Prisma schema files. Installing or
+changing a lockfile requires an explicit reseal. It does not cover an arbitrary
+external host or deployed image. Schema bytes cover schemas/ and migrations/.
+Each source file is limited to 1 MiB; each canonical digest map is limited to
+128 KiB. Deterministic invalid pack state refuses before rewriting the manifest.
+The manifest and pack remain separate files: an interruption between their writes
+is detected as stale by validation and requires an explicit reseal.
+
+Choose a profile with `atelier extension init --profile drizzle-db-first` (or
+`drizzle-code-first`, `prisma-7-postgres`). DB-first uses native `drizzle-kit pull`
+restricted to extension_data, then normalizes the generated local relation import
+for Node ESM. Review and retain the generated schema before resealing. Code-first
+uses native generation: review and apply its SQL before the explicit forced-RLS
+governance migration. Export the schema declaration so generation creates it.
+Prisma 7 uses native client generation and the explicit application DSN supplied
+by the customer host; the reviewed SQL still installs RLS. Generator output is
+a proposed source change, never permission to mutate a shared or Root database.
+Optional provider dependencies are installed in the generated app, never Atelier.
+
+Custom native configuration, schema and migration locations must be listed in the
+generated package.json `files` array as literal project-relative files or directories.
+This reuses the project's native package input list; it adds no second project catalog
+and never executes a TypeScript config during sealing. The list itself is sealed.
+Conventional generated paths and present npm locks are included automatically.
+Globs, parent paths, dependency directories, hidden paths except Git ignore/attribute files, and self-referential
+manifest/pack inputs refuse. The seal identifies these declared inputs; it does not
+claim an arbitrary external host, build artifact or dependency outside the project.
+
+Prisma interactive transactions use a 12-second transaction timeout and a 10-second
+SQL statement timeout. A manifest may allow up to 30 seconds, but the native
+transaction can roll back sooner and the handler then reports operation unknown.
+
+
+After reviewing and sealing a project, `atelier extension bundle --directory
+./custom-extension --json` writes its registration bundle to stdout. It contains
+the pinned manifest, exact schema strings and migration hashes. It uses the same
+file checks as sealing and refuses stale inputs. It creates no account, database,
+process or installation and applies no migration.
+
+Pass this bundle to `createExtensionAdminClient(transport).registerRelease(bundle)`
+through the consuming host's authenticated transport, then configure the returned
+release using the existing connection and lifecycle methods. The receiving host
+must independently verify every release and file digest and apply its publisher
+policy. A registration receipt is separate from health, enablement and consent.
+An older host without registration refuses with `unavailable`; clients do not
+silently enable or repeat the operation.
+
+A generic counter response is custom application data. A host's result-recording
+contract can require a different schema and narrower bounds. Author that result
+explicitly, update its action output schema, review and reseal it, and request the
+host's separate permission before recording it. Declaring a root-write permission
+alone does not make an arbitrary action result compatible.
+
+## Native Convex starter
+
+Use `atelier extension init --profile convex-native --directory ./custom-extension`
+for a TypeScript project pinned to Convex 1.46.0. This optional adapter uses native
+Convex schema/functions, indexes and OCC transactions. It installs no SQL driver
+and adds no Convex dependency to Atelier itself. Import native backend helpers
+from `@mnstry/atelier/extensions/convex`; browser clients use the same portable
+`/extensions/client` interface as the SQL profiles.
+
+The HTTP action verifies the original Root delegation and consumes admission
+once. It then passes that token and the canonical payload to an **internal
+mutation**, which verifies them again. A serialized scope or an `admitted`
+boolean is not authority. Native writes and the indexed operation result commit
+in one mutation. Output validators refuse invalid values and preserve canonical
+result bytes, so response and durable lookup cannot diverge. Root callbacks and provider commits remain separate. A lost
+reply requires a new admitted lookup operation, without repeating the write.
+No ordinary public mutation/query exposes the generated member tables. `GET /health`
+reports only the immutable release/schema health envelope after native index checks.
+
+The customer owns its Convex project and deployment. Set the public verification
+keys, issuer, exact invocation audience, opaque installation reference and Root
+admission origin in that deployment. Keep admin keys and member identities out
+of the browser and runtime request. HTTPS is required by default. The explicit
+local test option additionally requires both provider deployment URLs to be
+literal loopback addresses; Convex can set `NODE_ENV` to production even locally.
+
+The versioned native schema is `migrations/001-schema.ts`; `convex/schema.ts`
+re-exports it. The existing schema digest binds those migration bytes. Native
+source and generated code are sealed as bundle inputs. Generate provider code,
+strictly typecheck, seal, validate and export the bundle; validate again after
+deployment. Any changed generated input requires resealing and requalification.
+Atelier's CLI performs no provider login, process startup or deployment.
+
+The sample supports scoped set/get/export/delete and durable lookup. Deletion
+atomically clears live sample rows and older operation results for up to 500
+operations; larger histories refuse and need an explicit paginated erasure design.
+Backups remain subject to the operator's retention policy. In-flight admitted
+mutations may finish after disable. Public reactive feeds, revocation on feed
+reconnect, schema backfills, portability and complete host/privacy acceptance
+remain unqualified. The native starter's provider proof does not enable a
+receiving host's Convex profile or establish a complete customer journey.
+
+## Readiness extension packs
+
+Local readiness protocols use the existing extension-pack declarations in
+`atelier.project.json`. They are separate from database runtime adapters. A
+project can select custom protocols without the bundled MNSTRY readiness pack:
+
+```json
+{
+  "ext": {
+    "mnstry.atelier": {
+      "readiness": { "includeBundled": false },
+      "extensionPacks": [
+        {
+          "id": "sample.readiness",
+          "version": "v1",
+          "path": "packs/sample-pack.v1.json",
+          "enabled": true
+        }
+      ]
+    }
+  }
+}
+```
+
+Review the pack, then run `atelier extension-pack validate` and
+`atelier lock write`, both with `--project ./atelier.project.json`.
+Use `atelier readiness protocols --project ./atelier.project.json` to list the
+selected protocols, then pass a full namespaced ID to `atelier readiness run`
+or `atelier review run` with the same project. Evidence-bound review still
+requires the existing [pack compatibility declaration](../reference/extension-pack-lifecycle.md).
+Existing answer, proposal and evidence rules continue to apply.
+
+Omitting `readiness.includeBundled` or setting it to `true` keeps custom
+protocols alongside the bundle. With `false`, bundled IDs and aliases are
+unavailable to project runs. A standalone `readiness protocols` invocation
+without a project selection still lists the bundle. Generic graph, project and
+readiness checks remain available; the MNSTRY journey, packet and readiness
+export commands refuse. See [pack selection and lock transitions](tenant-readiness.md#select-the-readiness-pack).

package/docs/guides/graph-refresh.md

@@ -0,0 +1,152 @@
+# Graph projection refresh
+
+This is an experimental host integration module in `src/graph-refresh/`. It is
+not enabled by `atelier dev --knowledge`, and has no published package export.
+It adds no listener, daemon, graph database, identity or grant authority. A host
+attaches its start and stop to the existing sidecar lifecycle. The first proof
+uses invented graph-view fixtures; authenticated host receiving is separate.
+
+The Git source, canonical graph builder and knowledge plan still own source
+identity and semantics. Refresh consumes complete authorized projections. It
+does not extract a second graph, accept a relation, change a plan or apply a
+proposal. The existing graph file cache supplies incremental source reuse.
+
+## Lifecycle ports
+
+`createGraphRefresh` takes these host functions:
+
+| Port | Contract |
+| --- | --- |
+| `build({generation,binding,signal})` | Return one complete authorized graph-view projection. Compute in isolation, honor cancellation, and bound execution. Do not write a current output from inside the builder. |
+| `validate(projection)` | Return exactly `true` only for a supported, complete projection with a verified digest. Use the projection owner's validator. It may be asynchronous. |
+| `revalidate(binding,projection)` | Return exactly `true` only while this host-issued binding and every requested historical or current projection are still readable. `projection` is null before the build. Errors and other values refuse. It may be asynchronous. |
+| `stage({projection,generation,signal})` | Optional preparation of a complete host output, isolated from readers. Return `{commit,discard}`. It may be asynchronous. The default uses only the controller's in-memory pointer. |
+| `commit()` | Synchronously and atomically replace the host's current output. Never queue an asynchronous current write. A promise result is unsupported and refuses controller publication. |
+| `discard()` | Idempotently remove only this uncommitted staging output. It may be asynchronous. Failure retains cleanup custody even after supersession, access loss or stop. |
+| `clear()` | Synchronously clear host reader caches, inspectors, selections, search results and renderer resources. A failure or promise result blocks accepting a replacement binding. |
+| `onCleanup(outcome)` | Optional trusted host notification `{cleanupId,state,code}` for resolved or failed staging cleanup. It carries no source, path, binding or raw exception and is never a reader event. |
+
+`setAccess({key,expiresAtMs,...privateHostState})` accepts a trusted host binding.
+The key binds principal, exact authorized repositories, grant revision and
+expiry, policy and request filter. This is a cache and lifecycle key, not proof
+of a grant. Keep any instance-issued capability object in private host state;
+do not clone that capability or reconstruct it from browser JSON. Each access
+replacement first purges prior history, projection and selection. A host access
+adapter must revalidate the actual capability, not just compare the key.
+
+`start()` starts a pending build only when a binding is present. `invalidate()`
+immediately marks an existing view stale, aborts a superseded build and requests
+a replacement. Bursts share a fixed coalescing window, default 40 ms. Only one
+build and staging operation runs at a time. An abort-ignoring builder must
+settle before its successor can compute; its late result cannot publish.
+
+Every awaited build, validation, access check and staging step is followed by a
+generation fence. A final current access check and fence precede synchronous
+commit and pointer replacement without an intervening await. Partial builds,
+failed saves and obsolete generations never become the controller's current
+view. A conforming staging adapter is required for equivalent disk behavior.
+
+Cleanup custody is separate from publication and reader eligibility.
+`cleanupStatus()` returns sanitized host-only records with a `cleanupId` and
+`cleaning` or `failed` state. A failed discard retains its transaction handle;
+new builds and staging stop until the host resolves it with
+`await retryCleanup(cleanupId)`. Concurrent retries share the complete operation
+and its result, including a rejection. A failed attempt requires a separate host
+call to retry; a waiting caller never starts another attempt automatically.
+Success releases the handle and requests a fresh build if the host is running
+with current access. Rejection remains retained and notifies the host again.
+This bounds unresolved custody to one transaction without a retry daemon.
+
+The host must consume these operational outcomes and keep the controller until
+cleanup is resolved. Never serialize cleanup records into a reader response.
+Grant loss still purges private reader state immediately; resource custody does
+not authorize any old view delivery. `stop()` retains unresolved cleanup, and
+`await flush()` settles an already in-flight operation even after stop. Process
+restart recovery belongs to the staging adapter's existing resource journal;
+this controller does not add a persistent store or trust a saved projection.
+
+`read(digest?)` revalidates before returning a detached copy. A previous view is
+returned with `stale:true` after a source edit or failure, and `historical:true`
+when it is no longer the published snapshot. History is in memory, bounded to
+three previous digests by default, and available only under the same still-valid
+binding. A missing digest returns no projection. It does not fall back to a
+different snapshot. Restart requires fresh host access and a successful rebuild;
+there is no automatic trust of saved projections.
+
+`select(ref,digest)` accepts a current qualified `{repoId,localId}` only against
+the exact published digest. `compare(beforeDigest,afterDigest)` revalidates both
+retained snapshots and fences access changes before returning their comparison.
+
+## Revocation and UI receiving
+
+On a grant or policy notification the host first retires its access capability,
+then calls `invalidateAccess()`. This synchronously aborts work and drops the
+current projection, all history, selection and host caches. Expiry and a refused
+read or build check do the same. They cannot wait for a replacement build. Each
+read still checks access, covering a missed notification before another delivery.
+The controller cannot detect remote revocation without its host's notification
+or revalidation; this module does not establish an authenticated access host.
+
+Subscribe with `subscribe(listener)` and dispose with its returned unsubscribe
+function. Events contain only `{type,phase,generation,stale,failure}`. On `clear`,
+the UI must immediately dispose its graph, inspector, selection, query caches
+and pending render work, including all WebGL resources that retain private
+labels or topology. A previous browser copy cannot be recalled by clearing the
+controller alone. Conforming hosts must connect this event and `clear` to their
+own state and verify the visible result. Do not keep the old graph on screen
+while fetching a narrower replacement. Old refs and diagnostics are absent
+from clear events. A listener failure does not prevent other listeners running.
+
+| Phase | Meaning |
+| --- | --- |
+| `stopped` | No delivery; snapshots and selections cleared. |
+| `denied` | No current host binding or access refused/expired; no delivery. |
+| `pending` | Authorized first build requested. |
+| `building` | Build or staging in progress; an existing view is explicitly stale. |
+| `stale` | Source change invalidated the published generation. |
+| `current` | Latest complete generation passed validation and access checks. |
+| `failed` | Build, save or staging cleanup failed. An authorized old view may remain stale. |
+| `unsupported` | Host validator refused the projection. An authorized old view may remain stale. |
+
+Failures expose generic codes, never arbitrary build exceptions or source paths.
+The host can keep source-level details in an independently authorized diagnostic
+channel. `flush()` awaits pending work for a drill or on-demand build; it is not
+a background completion promise. `stop()` purges immediately and fences late
+results. The host must also await its own resource cleanup where required.
+
+## Local watcher binding
+
+`createLocalGraphRefresh({roots,...ports})` reuses Atelier's existing filesystem
+watcher factory. Roots are trusted host inputs for the exact current permitted
+repository set. It does not discover, clone or authorize repositories. Start it
+with the existing sidecar, and call `stop()` from that sidecar's close path.
+On a replacement access decision, pass the new permitted roots explicitly as
+`setAccess(binding,roots)`. Old watchers close on clear; delayed events from a
+retired watcher cannot invalidate the replacement reader's projection.
+
+Watch events are hints. A periodic rebuild, default every 30 seconds, reconciles
+dropped events using the canonical builder and file cache. It does not interrupt
+an in-flight build. `status().watchState` is `watching`, `unavailable` or `stopped`;
+failure to watch remains visible while periodic reconciliation can continue.
+Neither watcher nor reconciliation timer keeps a second process alive.
+
+## Snapshot comparison
+
+`compareGraphSnapshots(before,after)` is a pure derived comparison. Trusted callers
+must revalidate both snapshots first; controller `compare` performs that check.
+The pure function refuses incompatible schemas, different access contexts or
+filters, duplicate qualified refs and dangling references. It does not turn
+matching access metadata into authentication.
+
+Nodes compare by qualified ref, sources by repository and path with all exact
+pins retained, edges by edge id, and questions by question id. A rename does not
+merge identities. Assertions sharing a semantic triple retain separate edge ids.
+Changed bytes, revision, locator, edge support or question state are included.
+Possible question impact conservatively follows permitted edges in either
+direction within the supplied slice. It is explicitly possible impact, not
+proof of a semantic dependency or completeness outside that slice. No model,
+provider, source write or accepted history mutation occurs.
+
+Run `node --test test/graph-refresh-*.test.mjs` for the synthetic lifecycle,
+comparison and real local file-edit/restart drills. These checks do not qualify
+the held sidecar integration, a real recipient access host, or a browser renderer.

package/docs/guides/graph-workspace.md

@@ -0,0 +1,64 @@
+# Graph workspace
+
+A graph workspace lets a person explore a whole knowledge graph, then shape its concepts one step at a time. It is built in three layers, and the last one belongs to the owner:
+
+1. **Atelier** ships primitives and defaults: the read model, scale and layout helpers, label placement, recipes, themes, authoring and the browser rooms.
+2. **A coach** builds tooling for a cohort from those pieces: their own recipes, a theme, perhaps a different shell around the same rooms.
+3. **The owner** shapes their own system from everything they receive: hiding what they do not use, renaming, adding their own recipes and appearance.
+
+Nothing in a layer is hard-coded into the one below it. Recipes and themes are data that compose by name, and every resolved recipe field records which layer set it.
+
+## One graph, three rooms
+
+- **Constellation.** Every readable record, alive on a night-sky canvas (the default), with soft glows for the owner's folders and folder names at a distance. Names fade in by importance as you zoom in and never overlap each other or the controls. Hovering lights a neighbourhood; clicking selects without moving the map. "Let it move" turns on live physics.
+- **Workbench.** A sparse set of rich cards (incoming on the left, outgoing on the right) beside a focused authoring sheet. One subject at a time, one step at a time, with deferral and structural guidance. Drafts belong to one workspace identity (and reader scope, where the host has one), so two workspaces never see each other's drafts. Without an identity they live in this tab only. With `profile.id` or `draftIdentity` they persist in this browser, and with a host storage port they persist there. The interface says which.
+- **Review.** Before and proposed, the state of the evidence, and that a person decides. Nothing is sent.
+
+A work **recipe** picks the room, the lens and the single primary action. Lenses (`question`, `concept`, `zone`) belong to the constellation, subjects (`record`, `concept`, `relation`) to the workbench, and the review room takes neither. The primary action is one of `search`, `open-evidence`, `next-step`, `walk`, `review` or `pick`, and only one the recipe's room can carry out (`primaryActionsFor`). Combinations the shell cannot honour are refused when recipes are composed, and recipes the workspace cannot run (a relation recipe with no relations, say) are not offered. Defaults: *Explore*, *Answer a question*, *Refine a concept*, *Inspect a record*. A command bar (⌘K or `/`) replaces persistent navigation. Text view lists every record, and without WebGL every task remains available through Text view and the workbench.
+
+## Honesty rules the primitives keep
+
+- Zones come only from the owner's folder structure. No computed clusters are drawn.
+- A record belongs to a concept only when the record carries the concept's tag itself. Text matches are offered as suggestions labelled "not members".
+- Edge direction is preserved. Edges fall into three classes: written links, folder containment and declared relations. Only declared relations are drawn with arrows and emphasis.
+- Links to records outside the readable set are counted, never drawn.
+- "Ready for human review" means complete and grounded in readable records. It is not a verdict on truth.
+
+## Scale
+
+`planConstellation()` decides whether to draw every record or to show zones. The default budget is 12,000 records or 60,000 links. Above it, `aggregateZones()` gives counts by zone and directed bundles between zones, and `zoneSlice()` opens one zone at a time. Every link touching the zone is accounted for exactly once (drawn, omitted inside the zone, to another zone, or omitted to another zone), and plan concepts list only the kept records that declare them, with the rest counted. Aggregating 30,000 records is part of the test suite. On a laptop GPU the constellation holds 60 fps at 5,000 records, with labels and zone glows.
+
+## Build a workspace
+
+```js
+import Graph from 'graphology'
+import Sigma from 'sigma'
+import { EdgeArrowProgram } from 'sigma/rendering'
+import forceAtlas2 from 'graphology-layout-forceatlas2'
+import FA2Layout from 'graphology-layout-forceatlas2/worker'
+import { buildWorkspaceModel, layoutWorkspace, composeRecipes, composeTheme, DEFAULT_THEME } from '@mnstry/atelier/graph-workspace'
+import { mountGraphWorkspace } from '@mnstry/atelier/graph-workspace/browser'
+
+// graph: an Atelier knowledge graph the host has already limited to this reader.
+const model = buildWorkspaceModel({ graph, plan, zoneRule: { prefix: 'notes/', depth: 1 } })
+layoutWorkspace(model, { Graph, forceAtlas2 })            // or store positions at build time
+
+const recipes = composeRecipes({ coach: coachRecipes, owner: ownerRecipes }).recipes
+const theme = composeTheme(DEFAULT_THEME, coachTheme, ownerTheme) // every layer is checked; one bad layer refuses the theme
+
+mountGraphWorkspace(element, { model, recipes, theme, deps: { Sigma, Graph, EdgeArrowProgram, FA2Layout },
+  profile: { id: 'workspace-id', name: 'My notebook', vocabulary: { record: 'note', records: 'notes', zone: 'folder' } },
+  // Optional: persist drafts to the host instead of this browser.
+  // storage: hostDraftPort, draftIdentity: { workspace: 'workspace-id', reader: readerScope },
+})
+```
+
+Atelier does not depend on `sigma` or `graphology`; the host injects them. Pin sigma 3 and graphology 0.25 or later in the consuming application.
+
+## Keeping a shareable layer clean
+
+A coach or owner who builds on private workspaces can check that nothing from them reaches a shareable layer. `fingerprintsFrom()` derives distinctive strings from a private graph and plan (record ids, paths, long titles, summary openings, plan wording and names). `scanForFingerprints()` reports where any of them appears in shareable text, naming the file and a masked sample only.
+
+## What this does not do
+
+It does not authenticate a reader, grant access, read source bodies, save to a source or apply a plan change. Drafts that outlive the browser, and proposals, need a host storage port bound to the coauthor ledger, and the host's ontology guide remains the authority on guidance. See the [reference](../reference/graph-workspace.md) for every export.

package/docs/{ingestion.md → guides/ingestion.md}

@@ -1,12 +1,14 @@
 # Progressive local ingestion
 
-Status: experimental source implementation, not yet a released package feature.
+Status: experimental. Shipped since 0.2.0-alpha.13 as the `atelier ingest`
+command and the `@mnstry/atelier/ingestion` export.
 The local runner preserves explicitly selected files and makes bounded text
 search useful before semantic interpretation. It composes the existing
-[immutable intake](intake-and-guides.md) with a resumable plan. It never enrolls
+[immutable intake](../reference/intake-and-guides.md) with a resumable plan. It never enrolls
 raw captures into the canonical graph or treats extracted text as accepted
-knowledge. The [architecture proposal](progressive-ingestion.md) describes the
-larger destination; this page describes the implemented subset.
+knowledge. Host integrations use the existing [semantic proposal processor](../reference/semantic-ingestion.md),
+[semantic operation](../reference/semantic-operation.md) and [optional suppliers](../reference/optional-ingestion.md)
+under their documented profiles and limits.
 
 ## Start with a purpose and selected sources
 
@@ -16,8 +18,7 @@ traversal, symlinks and implicit external reads are refused. The local CLI is
 for a trusted workspace owner. Its workspace identifier is a binding against
 accidental cross-workspace reuse, not an authenticated identity or tenant ACL.
 
-The following examples assume the development checkout or a future package
-version containing this command. Released alpha.7 does not contain it.
+The following examples need 0.2.0-alpha.13 or later.
 
 ```sh
 atelier ingest plan <<'JSON'
@@ -169,13 +170,13 @@ verification and correction effort. Compare cost per useful accepted result,
 with quality floors and rare exceptions preserved. Keep private examples and
 methods in their owning workspace.
 
-## Remaining product work
+## Host responsibilities and limits
 
-The public foundation still needs qualified semantic adapters, focused
-synthesis and graph decision integration, richer document/media processors,
-connector census and permission-change handling, and representative pilots.
-The proprietary runtime adds native scheduling, installed processors,
-provider credentials/budgets, progress and source review, cancellation,
-notifications and scoped harness delivery. The public reference path remains
-usable without that runtime. Neither private material nor private methodology
-belongs in public fixtures or distributed proprietary prompts.
+The local runner supplies no richer document/media processors, connector census,
+permission-change orchestration or provider execution. Semantic processing and
+graph decisions use separate APIs and require qualified host integration.
+Native scheduling, installed processors, provider credentials/budgets, progress
+and source review, cancellation, notifications and scoped harness delivery belong
+to the host. The public reference path remains usable without a proprietary
+runtime. Neither private material nor private methodology belongs in public
+fixtures or distributed proprietary prompts.

package/docs/{inquiry-harnesses.md → guides/inquiry-harnesses.md}

@@ -1,8 +1,7 @@
 # Discovery Harness and Research Harness
 
-Status: implemented locally for the next release. The published alpha.7 package
-does not expose `inquiry`. Use `node bin/atelier.mjs inquiry help` from this
-source checkout, or `atelier inquiry help` from a package built from it.
+Status: shipped since 0.2.0-alpha.13. Run `atelier inquiry help` for the
+commands.
 
 Discovery frames questions, compares explanations and prepares decisions.
 Research gathers and checks evidence and returns a portable bundle. People set