@mnstry/atelier 0.2.0-alpha.14 → 0.2.0-alpha.16

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

@@ -4,7 +4,7 @@ This document describes the selection binding, the apply policy setup, the
 conflict-state view and the acceptance receipt validator under
 `src/projection/obsidian/selection-ui/`. It states what each one does on this
 machine and what it does not. The contract itself is in
-[obsidian-contract.md](obsidian-contract.md).
+[obsidian-contract.md](../reference/obsidian-contract.md).
 
 Nothing in this module starts the app, runs `obsidian-cli`, publishes a vault
 or writes a source file. The test suite installs a spawn guard that throws if
@@ -273,7 +273,7 @@ path. The package root (`@mnstry/atelier`) exports nothing of the projection.
 Names ending `ForOracleTests` are mutation controls for the test suite, not a
 supported API. The whole surface is alpha and may change between prereleases.
 What the tarball must and must not carry, and the package proof, are in
-[release-engineering.md](release-engineering.md#obsidian-package-contents).
+[release-engineering.md](../maintainers/release-engineering.md#obsidian-package-contents).
 
 ## First vault: what to expect
 
@@ -564,7 +564,7 @@ its own storage and asks again the next time until the vault is trusted or
 restricted mode is switched on for good in its settings. Turning the plugin
 off in a vault, or uninstalling it there, is respected from then on;
 `atelier obsidian plugin on --scope ID` brings it back. What the plugin does
-and never does is in [obsidian-plugin.md](obsidian-plugin.md).
+and never does is in [obsidian-plugin.md](../reference/obsidian-plugin.md).
 
 `open` and `status` answer with a freshness state, not a promise. `current`
 means the vault is the present generation, verified by read-back, and the app
@@ -689,7 +689,7 @@ exactly because the folder is listed.
   Obsidian does not have to be quit.
 - **Obsidian is not running.** The view is published on the path with no app,
   as before. `open` then adds the vault to the app's settings file (see
-  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list) for
+  [Obsidian's vault list](../reference/obsidian-contract.md#obsidians-vault-list) for
   exactly when and how that one file is written, marked to reopen) and starts
   Obsidian plainly, with no link: an Obsidian started with a link opens only
   that vault and drops the reopen flag of every other one, so your other
@@ -825,7 +825,7 @@ names the folder meanwhile, a settings file with other bytes is already
 there, or an interrupted run left a replacement or a removal. `open` may then
 add and open the vault before it is complete, and the app publishes the rest.
 Anything that would replace or remove a file waits for the app. See "First publication into a vault no Obsidian lists" in
-[obsidian-contract.md](obsidian-contract.md). The plugin's entry written this
+[obsidian-contract.md](../reference/obsidian-contract.md). The plugin's entry written this
 way counts as offered until the plugin says hello from the vault.
 
 The publisher still writes into a vault only when it can coordinate with every
@@ -971,9 +971,12 @@ confirmed there (see "A confirmed selection", below).
   (`personal-views-exceed-settings-limit`), within the Obsidian settings
   contract. The preferred view, when it names a saved one, is the default. No
   generation file is written. `view add` refuses `views-from-personal-overlay`;
-  `audience set`, `audience clear` and `location set` refuse
-  `personal-binding-decision-unavailable`. Each refuses before anything is
-  resolved or written.
+  `audience set me` records owner-only visibility in the machine settings, and
+  `audience clear` withholds every audience. Custom audience lists refuse
+  `personal-binding-owner-only`; `location set` still refuses
+  `personal-binding-decision-unavailable`. Refused operations do not change
+  audience, view or location settings. Following a selection may still keep
+  machine-private continuity evidence before the setting operation refuses.
 - **Preferences and coverage.** `preferences` are returned read only. A theme
   is reported and never written: `appearance.json` stays the person's.
   `coverage` is passed through untouched. No Obsidian code reads it: it states
@@ -1024,28 +1027,52 @@ unit and loader is what it was.
   a confirmed generation. `status`, `open` and `service start` load the
   selection and refuse with its code; the service's freshness shows every view
   `stale` with it, and its status document has it as the last tick's reason.
-  `selection-history-shortened` comes only from a process that read the
-  history longer, which is the running service: a command of the command line
-  reads the history in a process of its own, as it then stands, so `status`
-  reports the selection a cut history ends with while the service refuses it.
+  The command and service read the same machine-private continuity state, so a
+  restart or a separate command does not accept a shortened history. An invalid
+  checkpoint refuses `invalid-selection-continuity`; a checkpoint that cannot be
+  kept refuses `selection-continuity-unavailable`. No project is returned in either case.
   A confirmed selection is reported by `status` (`selection`: the generation
   and the number of its record).
-- **The service starts whatever the selection.** A bound project's folder is
-  its private home, so the home alone locates the workspace
-  (`locatePersonalHome`): the service resolves its workspace from that at once
-  and starts, and its engine awaits the loader at each tick. Started by a login
-  item, the service asks the home, not the loader, for its workspace and log.
-  `service status` and `stop`, the ticks `open` asks for, `service unit
-  --remove` and `uninstall` locate the service the same way. When no project
-  loaded (a restart while nothing is confirmed), the engine locates the
-  workspace too, so each view published before says why nothing is published
-  now instead of keeping the previous run's `current`. A service given a loader
-  that answers a promise and no locator is still refused at start with
+- **The service starts from an initialized home whatever the selection.** A bound
+  project's folder is its private home. The home must contain its caller-authored
+  `atelier.personal.json`, even when its enrollment is explicitly empty and no
+  generation is confirmed. A bare directory or a missing/unreadable manifest
+  refuses before startup; the locator cannot infer that no repositories were
+  enrolled from missing evidence. This tightens the former lower-level API
+  behavior that could start from a bare home. The locator reads the home and the
+  current manifest's repository roots for exclusion, without composing or
+  selecting a generation. A data root
+  inside a declared repository is refused before private state is created or a
+  login item is removed for a restart, including when nothing is confirmed.
+  The service resolves its workspace from that at once and starts, and its
+  engine awaits the loader at each tick. `atelier obsidian --personal-home`
+  does this for a bound home. A
+  program that runs the service itself (`runMaintenanceService` from
+  `@mnstry/atelier/obsidian`) gives it the same through `locateProject`, a
+  synchronous function that answers, without loading anything, a project whose
+  `configDir` is the folder the workspace is resolved from. The workspace is
+  then resolved from that answer alone: a data root named only in the loaded
+  project's local overlay, and not in the answer, is not seen, so the service's
+  state can lie under another data root than the loaded project's. Name the data
+  root through the `dataRoot` option or the workspace pointer instead, which
+  both see. Started by a login item, the service asks the home, not the loader,
+  for its workspace and log. `service status` and `stop`, the ticks `open` asks
+  for, `service unit --remove` and `uninstall` locate the service the same way.
+  When no project loaded (a restart while nothing is confirmed), the engine
+  locates the workspace too, so each view published before says why nothing is
+  published now instead of keeping the previous run's `current`. A service given
+  a loader that answers a promise and no locator is still refused at start with
   `service-loader-not-synchronous`, and so is one whose locator answers a
   promise; a located value that names no folder refuses
   `service-locator-invalid`. The workspace pointer is under the home, so a home
   that is gone when the service starts leaves it no workspace to find
   (`service-workspace-not-prepared`).
+- **Cleanup with nothing confirmed.** `service unit --remove` and `uninstall`
+  locate the existing protected workspace without a generation, and remember
+  the machine's login-item decision as `off` there. They do not change the
+  audience or confirm anything. Uninstall reports the actual kept workspace
+  pointer under the personal home, and leaves its bytes, private state,
+  generations and selection history in place.
 - **Following the history.** A loaded project is pinned to the record it was
   loaded under, and the engine observes that record and the place of the next
   one as configuration. A confirmation is therefore loaded at the next tick. A
@@ -1062,7 +1089,7 @@ unit and loader is what it was.
   another), whether or not the
   record's generation could be used, and whichever part of the service read
   it. A history that ends earlier refuses `selection-history-shortened` at a
-  load and at a recheck, and nothing is loaded from it while it is shorter; at
+  load and at a recheck until a fresh confirmation accepts it; at
   the read made when a tick stops a view, the view says `mixed-read` at that
   tick and the code at the next. A project already loaded is loaded again at
   the next tick once any part of the service has read the history ending at a
@@ -1078,18 +1105,26 @@ unit and loader is what it was.
   noted. The views say why (`open` and
   `status --json` name the ways out), and the vault keeps what it last
   published.
-- **What ends that refusal.** The removed records put back; a history as long
-  again, since a record in a place already read, with other content, is read
-  as a confirmation (after a cut of one record the person's next confirmation
-  is followed; after a cut of several, one confirmation is not enough); or a
-  start of the service. The number is kept in the process only, so a service
-  started after the cut cannot tell a cut history from one never longer: it
-  reads the history as it then stands and follows what it ends with,
-  publishing it if its generation still holds. Every start counts, the
-  person's own and one at login, after an upgrade or after a failure. Stopping
-  and starting the service is therefore how a person accepts a shorter
-  history, and a start nobody chose accepts it too. Nothing here keeps the
-  number across a start.
+- **What ends that refusal.** Put the removed records back, or explicitly confirm
+  the currently eligible generation through `selectPersonalGeneration` again.
+  That existing confirmation operation is the accepting act; no new command is
+  needed. One fresh confirmation accepts a shorter history even when its record
+  number remains below the highest ever observed. Its unique confirmation
+  identity distinguishes it from a previously observed record restored to the
+  same position. Replaying a previously observed prefix refuses, including after
+  a shorter history was accepted. Composition still decides whether the chosen
+  generation is eligible.
+- **Continuity across starts.** The highest observed number, accepted head and
+  previously observed record digests live in
+  `state/maintenance/selection-continuity.json` under the existing private
+  workspace. Reads validate its closed schema, workspace and personal-home
+  identities; changed writes are serialized through the existing private-state
+  lock, owner-only and atomic. State is bounded at 1 MiB and 8,192 observed record
+  identities; exhausting the identity budget refuses `selection-continuity-capacity`.
+  First use initializes from the current valid history, including historical v1
+  records without a confirmation identity. Retain this private state: deleting
+  all of it removes the evidence that distinguishes prior observation from a first
+  installation. Damaged existing state is never treated as a new installation.
 - **What the history is checked for besides.** At every full reconciliation the
   history is read again, so a record before the last that no longer links, or
   a confirmation that landed before the engine first looked at the record,
@@ -1098,7 +1133,8 @@ unit and loader is what it was.
   refuses `mixed-read` at its next wait, before its generation commits (one
   already committed stays), so do the views after it, and the next tick
   publishes under the new record. While the last load was refused, every tick
-  loads again: with nothing confirmed only the history is read, and with a
+  loads again: with nothing confirmed the manifest, history and private continuity
+  state are read without composition, and with a
   confirmed generation that no longer holds, one composition runs in a worker
   per tick.
 - **A narrowing.** When the newly confirmed generation drops a source (a
@@ -1110,10 +1146,14 @@ unit and loader is what it was.
   published (`held-for-your-edit`, `publication-withheld-for-your-edit`): the
   note is neither removed nor overwritten. A note edited during the
   publication itself stays in the vault (`retained-edit`).
-- **Who may see.** The binding never decides it. It stays this machine's
-  audience setting, none by default, and `audience set` still refuses for a
-  bound project: until an audience is allowed some other way, a bound vault
-  shows no note. Deciding who may see a bound vault is not built.
+- **Who may see.** The existing machine audience setting owns this decision.
+  For a personal binding, an undecided empty audience initializes to `only-you`
+  with notes without a classification shown, recorded with `defaults` provenance.
+  Existing explicit `only-you` lists and unclassified choices retain their exact
+  meaning. An explicit `audience clear` stays empty across ticks and restarts.
+  A nonempty custom setting refuses `personal-binding-owner-only` until
+  `audience set me` or `audience clear` is recorded. Nothing is written into a
+  generation or the personal overlay.
 - **Reading the history on the service's event loop.** The head is one
   directory listing and one bounded read per record. A record that is not a
   regular file (a FIFO, a device) refuses `selection-history-corrupt` without
@@ -1121,6 +1161,9 @@ unit and loader is what it was.
   project (its permissions changed, not removed) fails the tick when the
   engine observes its files, as an unreadable configuration file does: nothing
   is published, and the service reports the failed tick.
+  After a worker composes a generation, the caller still reads generation
+  files, resolves the generation's project configuration and assembles the
+  bound project on its own thread. Composition itself remains in the worker.
 
 Measured once on 2,156 notes in three repositories, with 50 annotations and five
 saved views (six views in all). The production contributions were loaded, as
@@ -1179,7 +1222,7 @@ logged, and what carries no code is a crash.
 A service bound through `--personal-home` is given a locator as well, and starts
 from it (see "A confirmed selection"). The plugin's status read allows for such
 a loader without waiting for it (see "The channel" in
-[obsidian-plugin.md](obsidian-plugin.md)).
+[obsidian-plugin.md](../reference/obsidian-plugin.md)).
 
 **Since that measurement.** The engine prepares each view cooperatively and
 the publisher yields between complete units, so the service answers health and
@@ -1258,7 +1301,7 @@ personal home they compose in a worker, as the engine's loads do, and the read
 starts each one on the loop by reading the selection history. A load that holds the loop
 for a second or more is logged (`status-project-loaded`), and so is a load at
 every request that names the files it started over (see "What the service
-shows of these loads" in [obsidian-plugin.md](obsidian-plugin.md)).
+shows of these loads" in [obsidian-plugin.md](../reference/obsidian-plugin.md)).
 
 What the waits cost. The waits of observation and routing are taken at
 every boundary between two edits or two operations and before each
@@ -1302,7 +1345,7 @@ test reported as a pass.
   is admitted although the protocol depends on the view's undocumented
   `lastSavedData` field, and the protocol cases have not been re-run on any
   later release. See the "App capability floor" row of
-  [obsidian-contract.md](obsidian-contract.md). An app that was not running
+  [obsidian-contract.md](../reference/obsidian-contract.md). An app that was not running
   when an adapter was qualified had no version to check, and neither had an
   app that was not found. Such an answer is never reused, and the adapter
   built on it does not coordinate with any app it then finds running, and
@@ -1342,6 +1385,50 @@ test reported as a pass.
   first allocation or when a vault is made again. Every other check runs
   again at both, and a vault made again, or published into, through a link on
   the way is refused (`vault-allocation-moved`).
+- Private state after a wait: that the private state is outside every
+  repository the workspace declares now is proven when a project loads, around
+  each engine phase, inside the engine and selection locks, and after each wait
+  the publisher makes for the app, its list of vaults, its comparison of kept
+  notes or its quiet period. "Declares now" differs by binding. For a project
+  bound to a personal home, each proof reads the home's manifest again, so a
+  repository enrolled while a tick waits is seen at the next proof. For an
+  ordinary project, each proof uses the repositories of the project as it was
+  last loaded. A change to its configuration or overlay that declares a
+  repository enclosing the data root is not seen until the project is loaded
+  again, and the writes of the tick in flight (preserved edits, pending edits
+  and freshness, say) can land under it meanwhile. The proof is not made again
+  at every write, and it is not made at all for writes made outside the
+  engine's phases and the publisher. Those are:
+  - the built-in proposal store's writes for pending edits to shared notes
+    (kept bytes, arbitration records and its queue) while it works through
+    several of them;
+  - everything the service process itself keeps: its log, service settings,
+    runtime record (with its bearer), service-start lock, startup record,
+    error record and login-item record, including those written after it waits
+    for a free port, for its server to listen or for the service manager, and
+    those a login item's start writes in the workspace the unit names when the
+    project's loader fails;
+  - the plugin channel's bearer and the plugin choices it records, including a
+    first-use bearer minted while a view is prepared and the confirmation
+    written when a plugin session opens;
+  - lock cleanup when a proof fails: any private lock that is held, or whose
+    ticket was just published, when its proof refuses is still released or
+    withdrawn, so that ownership is never left behind. This covers the engine
+    lock (a release record, or the withdrawal of a ticket published before
+    the last check of its acquisition), the selection continuity lock and the
+    publication locks, including a release retried at the next acquisition.
+    Lock cleanup and removing staged candidates are the only changes the
+    engine and the publisher make after one of their proofs refuses.
+
+  Each of these writers keeps its file inside the workspace's private state,
+  but none checks the roots declared now. A manifest that comes to enclose the
+  data root, or that cannot be read, while the service runs can therefore
+  receive these writes. A refusal of the private state's own location
+  (`managed-root-unproven`) stops the whole tick, whichever view it is found
+  in: no later view is prepared, given a store or published, and no view is
+  reported current after it. A view whose own vault is in a bad place is still
+  refused alone. A single check of the declared
+  roots at every private-state write is planned as a separate change.
 - Replacing a vault during a publication: the allocated folder is checked
   before the vault lock is taken and again once its folder is made, after the
   app is asked about the vault, before each note and before the generation is
@@ -1366,7 +1453,7 @@ test reported as a pass.
   `~/.config/obsidian`) on Linux. It is written only while the process table
   shows, positively, that no Obsidian runs, only when Obsidian created it
   before, and with a backup beside it; see
-  [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list). A
+  [Obsidian's vault list](../reference/obsidian-contract.md#obsidians-vault-list). A
   Flatpak or snap build keeps its list inside its sandbox and never reads that
   file. Which build is in use is read from which vault list was written last
   (every build rewrites its own when a vault window opens or closes), and only
@@ -1421,7 +1508,7 @@ test reported as a pass.
   - The command-line tool (`obsidian-cli`) is a client of the app and is not
     counted. An app packaged under another executable name, an app on
     another machine and an app that starts after a reading are not seen; see
-    "The path with no app" in [obsidian-contract.md](obsidian-contract.md).
+    "The path with no app" in [obsidian-contract.md](../reference/obsidian-contract.md).
 - The app-free path is live: before 0.2.0-alpha.10 the probe always found
   Atelier's own service, so publication never took the path with no app.
   From 0.2.0-alpha.10 it does, whenever the process table shows, positively,
@@ -1451,7 +1538,7 @@ test reported as a pass.
   back and a deleted folder is not made again until the person turns it on
   in Obsidian's settings or runs
   `atelier obsidian plugin on --scope ID`. Plugin files are never removed from
-  a vault. See [obsidian-plugin.md](obsidian-plugin.md).
+  a vault. See [obsidian-plugin.md](../reference/obsidian-plugin.md).
 - Login items: the tests run the launchd and systemd managers' own code
   against stand-ins that answer as launchctl and systemctl do, and never
   against a real session. What `launchctl print-disabled` says for an item

package/docs/guides/ontology-guide.md

@@ -0,0 +1,111 @@
+# Source-bound ontology guidance
+
+The experimental internal ontology guide prepares a private proposal for the
+existing knowledge workspace. It starts with a decision and preserves concept
+identity, exact source passages, directed relationship meaning and uncertainty.
+It does not edit a plan or source, confirm a participant answer, accept a mapping,
+or execute a decision.
+
+This module is not a supported package export or a new browser route. Existing
+knowledge-plan v1 files, the five knowledge views, sessions and package interfaces
+are unchanged. Maintainers can inspect its behavior with:
+
+```sh
+node --test test/ontology-guide.test.mjs
+```
+
+## One guided loop
+
+Choose a question in the current plan, then answer seven prompts:
+
+1. What decision will this help?
+2. What is the thing you are naming?
+3. How would you recognize the same thing next week?
+4. What close example should stay separate?
+5. Which source supports it?
+6. What does the relationship mean in each direction?
+7. What would change your mind?
+
+For an existing corpus, select bounded permitted evidence through the current
+knowledge context. For a blank workspace, retain its enrolled source directory
+and begin with a permitted observation/interview note or an explicit unknown.
+A synthetic practice observation remains labelled synthetic. An absent or broken
+enrollment is a source configuration error; it cannot establish an abstention.
+Both routes lead to source-owner review and a proposed next decision or test.
+Observed outcomes belong in Learn after they exist.
+
+The seven prompts map to the four existing Model fields: `concept`, `identity`,
+`relation` and `test`. A host should use the existing session answer/propose,
+confirmation and private-save operations. The guide returns wording; it does not
+send those operations. A saved draft remains a proposal. Agent-written wording
+still requires the existing explicit participant confirmation before saving.
+
+## Identity, evidence and limits
+
+Choose concepts by their existing IDs. Definitions, stable identity rules and
+`concept:` tags remain in the v1 plan. Examples, near misses, distinction
+rationale and disconfirming observations stay in private proposal metadata;
+they do not widen the closed plan schema. Identical definitions or identity
+rules require an explanation of how the concepts differ. Similar labels or
+aliases never establish identity. This small check cannot detect every semantic
+ambiguity; a reviewer still judges the proposed definitions and examples.
+
+The guide reads context through the existing local knowledge workspace. Evidence
+must match a unique selected source ID, its current full-file digest, a valid
+line range and its exact text. The handoff retains repo/path, digest, locator
+and passage, including qualifications. A source or plan change requires a new
+binding; earlier evidence and drafts remain historical. This is local-operator
+source binding, not a recipient permission check or hosted access decision.
+
+Explain each required relation using its existing forward predicate and both
+endpoint concepts. A reverse reading helps a person understand the original
+relation; it creates no inverse assertion. Evidence retrieval cannot establish a
+business claim, certainty or semantic truth.
+
+A proposed answer can say `supported` or `abstain`. These are the participant's
+proposed labels. `ready-for-human-review` checks draft completeness and source
+binding only. It does not certify that the answer is supported. Require stated
+scope and uncertainty, alternative explanations, and what could change the
+answer. Missing evidence suggests narrowing the claim or abstaining. Omitted
+sources remain explicit in the handoff; an abstention with omissions is marked
+`unverified-omissions`, so it cannot imply corpus-wide absence of evidence.
+
+## Review handoff
+
+The internal `createOntologyGuide()` adapter reads an already-loaded local
+workspace and a current question ID:
+
+- `prompts(workspace, questionId, entry)` returns ordered guidance for `corpus`
+  or `blank` entry and the existing view/Model field for each step.
+- `inspect(workspace, questionId, draft)` returns field-specific next actions,
+  verified source passages and retained retrieval limitations.
+- `prepareReview(workspace, questionId, draft, {basePlanText, planRef})` returns
+  an input body for the existing copy-only proposal store, or diagnostics.
+
+`draft` retains the workspace snapshot, raw base-plan SHA-256, entry route,
+decision, exact concept IDs with examples/counterexamples and identity basis,
+required relation readings, selected evidence pins, proposed answer/limits and
+disconfirming observation. An optional `proposedPlan` must still validate as v1.
+The source owner reviews changes before any canonical admission.
+
+The handoff binds exact raw plan bytes, retains complete before/proposed text
+and structural changes, and uses `proposal.copy-only` with `directWrite: false`
+and no apply endpoint. Oversize handoffs refuse with a request to narrow the
+change, before the existing store can truncate them. The guide never calls the
+store or persists a second draft ledger. A host explicitly supplies the body to
+the existing proposal workflow after reviewing the private audience.
+
+Review and source edit remain separate. The source owner inspects the exact diff,
+checks identity and passage meaning, applies an admitted change using the normal
+Git path, reruns knowledge check/evaluate, then starts a newly bound session.
+No source pin is replaced automatically to clear a failed check.
+
+Cross-repository concept mappings remain proposals preserving both source
+identities. Conversion to an edge-governance record requires the allocated
+stable repository/source descriptor, exact current source revisions and raw
+byte locators, plus the receiving review policy. This internal guide does not
+invent those values, emit accepted equivalence or activate a semantic edge.
+
+The synthetic tests exercise software behavior on the invented equipment library.
+They do not demonstrate a cold participant's comprehension, answer correctness,
+host ACL behavior or a completed human corpus/blank-start drill.

package/docs/{personal-workspace.md → guides/personal-workspace.md}

@@ -117,7 +117,9 @@ remove only their own temporary files. Every failure is a
   that `readPersonalSelection` returns, so a choice shown against an older history
   does not apply. Selections are append-only, numbered, hash-chained records under
   `selections/`, each written completely before it is published, so a crash leaves
-  only a temporary file. Concurrent selections refuse `selection-concurrent`. An
+  only a temporary file. New records include a unique confirmation identity: confirming the
+  same generation against the same predecessor again produces a distinct record. Existing
+  v1 records without this identity remain readable. Concurrent selections refuse `selection-concurrent`. An
   ineligible generation refuses with its composition code, such as
   `stale-generation`.
 - `readPersonalSelection({ personalHome })` returns the current selection and
@@ -128,9 +130,10 @@ remove only their own temporary files. Every failure is a
   rewriting, any trailing run of records (up to the whole history) yields another
   valid chain; it changes the returned `head`, so a host that needs to detect it
   keeps the head it last observed and compares it. The Obsidian maintenance
-  service keeps the highest record number it has read a history ending at, for
-  as long as it runs and no longer, and refuses a history that ends earlier
-  (see [obsidian.md](obsidian.md)).
+  service persists the highest observed record number, accepted head and observed
+  record identities in its machine-private continuity state. A restart keeps that
+  evidence. A shorter history refuses until the removed records return or the person
+  makes one fresh confirmation (see [obsidian.md](obsidian.md)).
 - `readPersonalSelectionHead({ personalHome })` returns `{ selected, sequence,
   head }` from the history alone, with `sequence` 0 while nothing is selected.
   It composes nothing, so it does not say whether the selection is still

package/docs/{research-starter.md → guides/research-starter.md}

@@ -108,7 +108,7 @@ demonstrate framing, research return, uncertainty, review and graph proposals.
 local ingestion, persistent Knowledge records, retrieval and graph projection.
 The tests are synthetic conformance evidence, not real research validation.
 
-When useful practice emerges, use [Practical Judgment](practical-judgment.md):
+When useful practice emerges, use [Phronesis — practical judgment](../reference/phronesis.md):
 retain its reason, cases and exceptions, then adopt it into the appropriate
 instruction, capability or implementation through that destination's owner.
 Ordinary research does not require a new skill, ADR or personal tracking.

package/docs/{tenant-readiness.md → guides/tenant-readiness.md}

@@ -19,6 +19,38 @@ write through a browser view.
    commerce, sessions, audit, and client-grade sharing as MNSTRY runtime
    authority.
 
+## Select the Readiness Pack
+
+Projects include the bundled MNSTRY readiness pack by default. To use only
+declared custom protocols, set this in the tracked `atelier.project.json`,
+preserving the project's other settings:
+
+```json
+{
+  "ext": {
+    "mnstry.atelier": {
+      "readiness": { "includeBundled": false }
+    }
+  }
+}
+```
+
+An absent setting or explicit `true` keeps the existing bundled protocols and
+twelve-dimension tenant journey. Local preferences cannot re-enable a bundle
+that the tracked project deselects.
+
+After reviewing a selection change, update the existing lock explicitly:
+
+```bash
+atelier lock write --project ./atelier.project.json
+atelier lock check --project ./atelier.project.json
+```
+
+The lock records the selected packs while preserving its template and migration
+history. A lock that still pins the deselected bundle fails `lock check` and
+`upgrade --dry-run`. To select the bundle again, set `includeBundled` to `true`
+and write the lock after review.
+
 ## Local Review Pass
 
 Run checks from the copied workspace:
@@ -36,6 +68,13 @@ Use `--check` modes where available when validating committed generated output.
 If a command is unavailable in an older workspace, report the exact command and
 stderr instead of substituting a new protocol.
 
+With the bundle deselected, the graph, project projection and generic readiness
+checks remain available. The projection and readiness output omit the MNSTRY
+tenant journey; they do not create a replacement journey or packet. Selected
+custom protocols use the existing [extension-pack workflow](extensions.md#readiness-extension-packs).
+`readiness journey`, `readiness packet` and `readiness export --dry-run` refuse
+with `readiness-pack-disabled`, including when custom packs are selected.
+
 ## Claim-First Output
 
 Readiness summaries should lead with claims, then evidence:

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

@@ -9,6 +9,37 @@ workspace between Atelier package releases. The flow is local-only: it does not
 provision repositories, contact a Git host, mutate the MNSTRY runtime, or write
 through a browser view.
 
+## Upgrading to 0.2.0-alpha.16
+
+This release renames two graph workspace names; nothing else changes and no
+stored record changes format.
+
+- The room `constellation` is now `map`, and the middle recipe and theme layer
+  `coach` is now `distribution`. Use `room: 'map'`,
+  `composeRecipes({ distribution })`, `planMap`, `createMap`, and the shell
+  handle's `map` and `backToMap`. Provenance now reads `setBy: 'distribution'`;
+  code that compared `setBy` values with `'coach'` must compare with
+  `'distribution'`.
+- The alpha.15 names still work in this release and are removed in the next:
+  `room: 'constellation'`, `composeRecipes({ coach })` (do not pass both),
+  `planConstellation`, `createConstellation`, `constellation`,
+  `backToConstellation` and the `.constellation` class. Styles that target
+  `.atelier-gw .constellation` should move to `.atelier-gw .map`.
+
+## Upgrading to 0.2.0-alpha.15
+
+This release adds the graph workspace (`@mnstry/atelier/graph-workspace` and
+`@mnstry/atelier/graph-workspace/browser`) and the graph view, access and
+source-contribution modules. Existing consumers do not need to change. No schema
+or stored record format changes, with one effect on Knowledge Health:
+
+- Knowledge Health regenerates its rule identity for the knowledge-graph file:
+  the `check` each assessment carries names a new `version` and `sourceTree`.
+  The rule it applies is unchanged. A workshop contribution started on
+  0.2.0-alpha.14, completed or not, cannot start Review on this release
+  (`finding changed; refresh before selecting a new draft`); start Review
+  before upgrading, or record a new contribution.
+
 ## Upgrading to 0.2.0-alpha.14
 
 `atelier upgrade closure --npm-root ABSOLUTE_NPM_ROOT` plans a check of a staged
@@ -64,7 +95,7 @@ version in a disposable workspace before client use.
 
 ## Upgrading to 0.2.0-alpha.13
 
-The public [Knowledge Health workshop](knowledge-health/devday/public-default.md)
+The public [Knowledge Health workshop](../knowledge-health/quickstart.md)
 uses an invented local workspace. Participants can retain their original words,
 a separate interpretation and a `note`, `perspective-only`, `disagreement` or
 `pause` response. Review is a separate optional session. A selected draft can
@@ -75,7 +106,7 @@ then reads it back and reassesses. The browser host grants no source-apply route
 
 `atelier knowledge semantic` exposes the existing semantic runner's eleven
 operations through JSON stdin. It retains the runner's refusal codes and saved
-failure details. The [semantic operation contract](semantic-operation.md)
+failure details. The [semantic operation contract](../reference/semantic-operation.md)
 remains authoritative; this release adds no schema or package export.
 
 Existing source and local history remain owned by their original repositories.
@@ -96,13 +127,13 @@ The next release adds the responsibility workflows, source-current ingestion,
 Trackables, governed instruction adoption and local template profiles. Template
 adoption uses the existing exact-plan transaction engine with explicit v2 policy
 and v3 plans; existing policies are never converted automatically. See
-[template profiles](template-profile.md) and [template adoption](template-upgrades.md).
+[template profiles](../reference/template-profile.md) and [template adoption](template-upgrades.md).
 Optional advisory decisions require no provider installation or activation.
 
 New Trackable journals retain resolved calendar occurrences and byte-bound state.
 Legacy v1 journals remain available as chain-verified exports when state replay
 cannot be established. Preserve historical records and use the documented
-[Trackables](trackables.md) host limits before adopting a new profile.
+[Trackables](../reference/trackables.md) host limits before adopting a new profile.
 Regenerate local graph/projection artifacts through the ordinary upgrade process
 and qualify each consuming host independently. A package update supplies no
 publication permission or runtime activation.
@@ -165,7 +196,7 @@ The link resolver that produces `links_to` edges changed in five classes
 the repository root, malformed percent-encoding, and workspace-only wikilink
 and cross-repository edges). Regenerate committed graph artifacts after
 upgrading and review the difference; the classes are listed in the changelog
-and in [obsidian-contract.md](obsidian-contract.md).
+and in [obsidian-contract.md](../reference/obsidian-contract.md).
 
 ## Upgrading to 0.2.0-alpha.7
 
@@ -264,7 +295,7 @@ compensating for that.
 This release breaks the export vocabulary. The runtime owner names are now
 the vendor-neutral domain terms `identity`, `catalog`, `commitments`,
 `events`, `projection`, `consent`, `messaging`, `providers`, and `audit`
-(defined in `docs/ontology.md`), and documents written against
+(defined in `docs/reference/ontology.md`), and documents written against
 `v0.1.0-alpha.2` do not validate here. Regenerate exports and projections rather than hand-editing
 them, and update any consumer that pins an owner name. `CHANGELOG.md` lists
 every breaking change in this release, including the contract-stability epoch
@@ -276,7 +307,7 @@ current corpus against the validators of the baseline recorded in
 a tag sets `baselineTag` to that tag in the release commit, so the following
 development cycle is checked against the released validators. Until the first
 post-epoch tag is cut the baseline is null and the gate is inert by design.
-See `docs/contract-stability.md`.
+See `docs/reference/contract-stability.md`.
 
 ## Before You Upgrade
 
@@ -378,8 +409,8 @@ and dependency trees; two observed byte inventories must agree and match the com
 checkout does not authenticate an upstream publisher.
 
 Review snapshots and decisions are separate from historical v1 locks. See
-[pack lifecycle](extension-pack-lifecycle.md) and
-[inspection portability](review-portability.md) before replacing packs or moving
+[pack lifecycle](../reference/extension-pack-lifecycle.md) and
+[inspection portability](../reference/review-portability.md) before replacing packs or moving
 state. Updating a package or a digest never silently renews old approval.
 
 ## Exact local candidate transactions