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

package/docs/{local-services.md → reference/local-services.md}

@@ -203,8 +203,19 @@ the child it created. If that proof never arrives it stops only that child, by
 its process handle, and reports the private operational log,
 `state/service/service.log`.
 
-A tick is largely synchronous, so a healthy service in a long tick may not
-answer health within the deadline. That is `busy`, not `occupied`: it is
+Stretches of a tick are synchronous (walking the directories, reading the
+HTML sources and the sidecars of PDF and Word documents, resolving links and
+assembling the canonical graph, building the whole graph of a project bound to
+a personal workspace, capturing the source snapshot, the
+publisher's restart recovery, its exchange probe, writing the journal, the
+look again at displaced files), so a healthy service in a long one may not
+answer health within the deadline; observing the vault and source files before
+a view is prepared, reading the Markdown sources into the canonical graph,
+preparing
+and publishing a view, and reading it back after a commit yield between files
+and between publication units, and health is answered meanwhile. A service
+that does not answer in time is `busy`, not
+`occupied`: it is
 never adopted, never stopped and never started over, and a `start` whose own
 child went straight into a long first tick reports it as started and busy
 instead of ending it. The command line of another process is read from
@@ -268,7 +279,35 @@ A tick that fails for a reason nobody typed (a full disk, a crash inside a
 step) does not end the service. Its error code is kept in
 `state/service/last-error.json`, its message only in the private log; the
 delay before the next attempt doubles up to a ceiling, and the next tick
-proceeds.
+proceeds. It starts as the first tick of the service does, loading the project
+again and looking at every view, so nothing the failed tick saw and did not
+act on is lost. A tick whose engine lock could not be given back at its end
+(its released ticket could not be written) fails too: its error is recorded
+and the loop backs off, and its work was already recorded before the release.
+The lock stays this service's, and the next tick gives it back before it takes
+it again, instead of finding its own ticket and answering `busy` until the
+service is started again.
+
+A view refused for a file-system error does not fail the tick. Examples are
+a vault folder that could not be allocated or placed (`vault-location-unusable`),
+a configuration file that could not be read again during the tick, a source
+removed while it was read (both `mixed-read`) and candidates that could not be
+staged (`staging-failed`). The view's freshness names only the refusal, so the
+service writes a `view-refused` line to its private log for each such view
+whose refusal carries a file-system error's code, at most 64 a tick: the view,
+the refusal's code and the error's code (`EACCES`, `EIO`, `ENOENT`, `ENOSPC`).
+Only codes shaped as a file-system error's are written, never a message. A view
+the next tick names for the same reason is not written again, so a folder that
+stays unwritable (tried at every tick) is written once. It is written again when
+its reason changes, or after a tick that failed or did not name it: a tick that
+did not refuse it, refused it for no file-system error, had named 64 other
+views first, or was refused as a whole. When removing the staged candidates
+afterwards fails too, the line also names that error's code as `cleanupCause`,
+and a line is written for that alone when the refusal names no error of its
+own. That failure does not replace the refusal. What could not be removed
+stays where it was: in `staging/`, or at its exchange path under `recovery/`
+once the publication's journal is written. The restart recovery of the next
+publication removes the latter.
 
 ### Cases that need a person
 
@@ -447,7 +486,7 @@ error, 3 the operation ran and its answer is not success.
 | `status` | enablement, machine settings, what was decided, proven service state, per-view freshness with its diagnostics (a code, the rule and the in-view note concerned, never a value; see [the Obsidian contract](obsidian-contract.md#notes-that-were-laid-out-anyway)), whether an apply operation exists | nothing |
 | `settings` | what this machine remembers for the workspace (who may see, where vaults live, start at login, the adapter), who allowed the service, and how each answer is changed | nothing |
 | `scope list`, `scope show ID` (also `view list`, `view show ID`) | the declared views | nothing |
-| `view add ID (--all \| --folder PATH [--folder PATH ...] [--repo R] \| --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]` | adds a view to the project configuration, after showing the change and how many notes the view would show; refuses a view that would show no note unless `--allow-empty` (see [Adding a view](obsidian.md#adding-a-view)) | `atelier.project.json`, and `.gitignore` when `.atelier-local/` is not ignored. Never committed |
+| `view add ID (--all \| --folder PATH [--folder PATH ...] [--repo R] \| --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]` | adds a view to the project configuration, after showing the change and how many notes the view would show; refuses a view that would show no note unless `--allow-empty` (see [Adding a view](../guides/obsidian.md#adding-a-view)) | `atelier.project.json`, and `.gitignore` when `.atelier-local/` is not ignored. Never committed |
 | `audience show`, `audience set me\|A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. `me` is only you: every audience but `sensitive`, which is added by name. The answer is remembered as the person's decision. A change invalidates every view at the next tick | private machine settings |
 | `location show`, `location set DIR [--allow-synced-location]` | where this workspace's vaults live; each view not published yet gets `<project> (<view>)` there at its first publication, and a vault published already stays where it is | private machine settings |
 | `mode show`, `mode set manual\|automatic` | `automatic` refuses without an installed, matching, active automatic policy | private machine settings |

package/docs/{obsidian-contract.md → reference/obsidian-contract.md}

@@ -5,7 +5,7 @@ feasibility track. It states what is proven, on what, and what is not. Nothing
 here enables a feature. The publisher under
 `src/projection/obsidian/publication/` is called by the maintenance service
 (`atelier obsidian service start`) and so by `atelier obsidian open`; see
-[obsidian.md](obsidian.md).
+[obsidian.md](../guides/obsidian.md).
 
 ## Registered shapes
 
@@ -665,6 +665,29 @@ again, so bytes that drift under an unchanged pinned digest are not seen by
 describes, and the next observation by digest sees the drift. A note whose pin
 changed is read and verified against the pin as always.
 
+The maintenance engine prepares a view cooperatively (the
+`prepareViewCooperatively` production seam): it waits between notes so that
+the service keeps answering. The bound above holds there too. After a
+cooperative preparation, and again while the publisher holds its locks,
+before the journal entry that says the publication settled and before the
+commit, the engine checks every selected source as observation does: a source
+that still has the stat hint it was indexed with is taken as unchanged and is
+not opened, and one whose hint moved is read and must still be the pinned
+bytes. A source that changed during the tick, or was removed, refuses the
+generation as `mixed-read`: its manifest is not committed, at that tick or by the restart
+recovery of a later one, and the next tick observes in full and prepares the
+view again. The same waits check that the configuration files, the machine
+settings and the eligibility revision are still the ones the tick read. A
+configuration file that cannot be read at such a check (no permission, an I/O
+error) refuses the view as `mixed-read` too, and the tick goes on to its
+other views.
+
+Called on its own, a cooperative preparation reads every selected source
+against its pin once more before it returns, a reused note's included, unless
+its caller says it checks them itself (`scheduling.recheckSources: false`, as
+the engine does). A preparation refused or cancelled on the way leaves the
+preparation cache as it was.
+
 The engine holds one graph file cache and one preparation cache per scope for
 its lifetime and hands them through the `createGraphCache` and
 `createPreparationCache` production seams; a test replaces either with
@@ -845,7 +868,7 @@ written meanwhile.
 
 macOS (Darwin 25, arm64) with Obsidian 1.13.7 (installer 1.12.7), CLI enabled,
 no community plugin. Sixteen interleavings, 25 rounds for each racing case, in
-four complete clean runs of the prototype in `experiments/obsidian-publication/`
+four complete clean runs of the historical publication feasibility prototype
 at commits `34f5fab` and `c5142e7`. The receipts record those same trees under their
 pre-sign-off identities `5930f85` and `93303ff`; the branch was rewritten only to add
 sign-off trailers, with identical content. Receipt SHA-256 digests:
@@ -857,11 +880,13 @@ sign-off trailers, with identical content. Receipt SHA-256 digests:
 
 A fifth run aborted because the harness could not open a note after the
 second-window case; no bytes were involved. The receipts are maintainer-held
-and are not part of this repository.
+and are not part of this repository. Current desktop qualification uses
+`scripts/obsidian/desktop-receipts.mjs`. These historical receipts do not qualify
+a later candidate or a different host.
 
 Every vault Atelier publishes now carries Atelier's own plugin
 ([obsidian-plugin.md](obsidian-plugin.md)), so a trusted vault runs one
-community plugin. In phase 1 it registers no editor extension, no vault event
+community plugin. The current plugin registers no editor extension, no vault event
 handler and nothing that writes; it only talks to the maintenance service over
 loopback. The protocol cases above have not been re-run with it loaded; that
 run is gate G20, before the plugin carries any part of publication.

package/docs/{obsidian-plugin.md → reference/obsidian-plugin.md}

@@ -5,11 +5,11 @@ finds or installs it: the maintenance service puts it into the vault with the
 notes, and Obsidian asks once per vault whether to trust the vault's plugins.
 Until the person says yes, and whenever the plugin is absent, turned off or
 running in an app that is too old, everything works as it did before through
-the command-line path described in [obsidian.md](obsidian.md).
+the command-line path described in [obsidian.md](../guides/obsidian.md).
 
-This is phase 1: the plugin is present, reports status and holds a channel to
-the service. It decides nothing and writes nothing. Phase 2, planned at the
-end of this document, moves the in-app part of publication into it.
+The plugin reports status and holds a channel to the service. It decides
+nothing and writes nothing. Publication uses the existing command-line or
+app-free path; the plugin does not perform its critical section.
 
 The source is `plugins/obsidian/` in the package: `manifest.json`, `main.js`
 and `styles.css`, plain JavaScript with no build step. The channel it speaks
@@ -32,7 +32,24 @@ is `src/projection/obsidian/plugin-bridge/channel.mjs`; the service's half is
   a window with the view, its state and the reason in words, the committed and
   the prepared generation, when freshness was last checked, the held, retained
   and pending edits, the service address and state, and the plugin and app
-  versions.
+  versions. While the service is unreachable, current generations, check time
+  and edit counts are unknown. After a connection refusal or timeout on the
+  same channel, the window also shows the last authenticated state, reason,
+  generation and check under "Last observed" labels. Those rows are historical
+  and never establish current freshness, service health or permission.
+  History stays only in memory. It is cleared on a channel change, missing or
+  unsupported setup, authentication refusal, an untrusted answer, a missing or
+  malformed view, a report for another scope, a disabled view or unload.
+  A connection reset or any other failure outside connection refusal and
+  timeout also clears it. Without a prior usable report, "Last observed
+  status" says "not available". After startup admits the channel, a republish
+  that names a different channel (host, port, scope or key) resets the display
+  to `connecting` before its next answer; this reset does not repeat an
+  unchanged notice or lose the transition back to current. A republish of the
+  same channel keeps the display and history, and unusable data shows
+  `not set up`.
+  Republish keeps an unsupported-app or unavailable-Node setup label and its
+  channel closed. Plugin 1.1.2 adds this status continuity.
 - A notice appears when the view moves into a state that needs a person (held,
   stale, service unreachable, app too old) and when it is current again.
   `updating` is not announced: it is what every change looks like.
@@ -336,6 +353,124 @@ the vault's key without sending it, and the service proves it first
 | `POST /plugin/release` | `sessionId`, `counter`, `mac` | sealed: whether the session was released |
 | `POST /plugin/status` | `sessionId`, `counter`, `mac` | sealed: the view's state, reason, verification, committed and prepared generation, held notes (counted, not named), retained edits, open pending edits, and the service's own state |
 
+A status answer carries the view and its pending edits only while the project
+allows that view at the moment of the request, not as of the last tick
+(`src/runtime/obsidian/view-permission.mjs`): its Obsidian settings are
+enabled and declare the view, and its workspace pointer still names the
+workspace this service runs for, with its private state where the service
+keeps it. Otherwise the answer is still sealed and still carries the service's
+own state, but `view` and `pendingEdits` are `null`, which the plugin already
+reads as nothing known about the view. That covers a view turned off or taken
+out of the settings before the next tick, and the freshness a later tick
+writes for it, which keeps its generations and counts. It also covers anything
+that cannot be established: settings that refuse, a project that does not
+load, a pointer that cannot be read. The plugin then shows `Atelier: stale`
+with the reason "no freshness recorded", keeps its session and asks again at
+its next round; it is not told why, and it remembers nothing of the view to
+show later.
+
+Loading the project runs Git in child processes, which would otherwise happen
+every two seconds for every open vault, so the project is kept:
+
+- **What decides it.** The files the engine observes as configuration,
+  compared at every request by a digest of what they hold, never by their
+  times. Each file holds where it really is and the bytes there: its path
+  resolved as the system resolves it when the loader opens it (`realpath(3)`,
+  through a link anywhere on the way, a `..` after a link included), so a
+  configuration kept in a dotfiles repository and linked into the project is
+  kept like any other, and a link pointed elsewhere, the file's own or one to
+  a folder above it, is a change even where every byte is the same. A folder
+  in a file's place, a link that leads nowhere or to a folder, and a file
+  that cannot be read vouch for nothing: then nothing is kept, and the
+  project is loaded at every request. Where the system resolves no path for a
+  regular file that is there and is not a link (some volumes on Windows
+  answer `EISDIR`; a C library that needs `/proc` and has none), the file is
+  compared by its own path as given and its bytes, so the project is still
+  kept; a link above such a file, pointed elsewhere, is not seen there. A
+  link the system does not resolve vouches for nothing. The pointer and the
+  place of the private state are read at every request.
+- **When it is kept.** Two loads in a row, each started after those files
+  were read and found to hold the same, must return the same project as far
+  as the decision reads one: the views it enables, where its pointer is, the
+  data root its local overlay prefers and the roots it protects. A field that
+  differs from load to load, such as a time or a personal-workspace binding
+  kept under a symbol key, does not keep a project from being kept. One
+  load is not enough: a file changed and changed back while it ran leaves the
+  same bytes around a project read from other ones. So three loads keep the
+  project when the service has just started, and two after a change.
+- **For how long.** A kept project is loaded again once it is two and a half
+  minutes old, and is never used once it is five, the interval of the
+  engine's full reconciliation. Whatever no file here names (an overlay named
+  by `MNSTRY_ATELIER_LOCAL_CONFIG` that did not exist at the last load, for
+  instance) is seen by then.
+- **A loader that answers a promise** is never waited for, because the plugin
+  gives a request a second and a half. Its view is told nothing until two of
+  its loads have agreed; one load runs at a time, and a kept project goes on
+  deciding, within its time, while it is loaded again. A load that has not
+  answered within two and a half minutes is given up and its later answer
+  ignored, whether a request or that answer is the first to come after the
+  deadline. A service bound to a personal home (`--personal-home`) has such a
+  loader: it starts from the home alone, and its plugins are told about a view
+  once two of the loads that compose the confirmed generation have agreed. A
+  service given only a loader that answers a promise still refuses to start
+  (see "Personal workspaces" in [obsidian.md](../guides/obsidian.md)).
+- **A load that fails** (it throws, it is refused, it is given up, or a file
+  vouches for nothing under a loader that answers a promise) ends whatever
+  was kept, and is asked for again after two seconds, then four, up to
+  thirty, while the files hold the same. A change to them is tried at once,
+  with two exceptions. Until a load has answered and named the files, a
+  corrected configuration waits for the next try. And while one of the files
+  vouches for nothing there is no digest to change, so after a load that
+  failed then (one that answers a promise, or one that answers at once and
+  threw) a change to another file waits for the next try as well.
+- **What the service shows of these loads.** Its status document counts
+  them (`statusLoads`: `answered`, `failed`, `givenUp`, `slow`, `notKept` and
+  `longestMs`). Its log gets a `status-project-loaded` line, with the
+  milliseconds, the outcome, flags and counts and never a path, only for a
+  load somebody has to see, each kind on its own row, written when the row is
+  1, 2, 4, 8 and so on long (from 2 for loads after which nothing is kept):
+  - a load that failed or was given up;
+  - a load that answered at once and took a second or more (`slow`). A second
+    is most of the second and a half the plugin gives a request, spent on the
+    listener's own event loop; a load that answers a promise holds nothing;
+  - a load after which nothing is kept although it named the files it
+    started over (`notKept`, from the second in a row, with `vouched` false
+    while a file vouches for nothing): a load at every request. A load that
+    named other files than it started over (the first, which started over
+    none, or the one after a change that names other files, such as a new
+    confirmed selection) neither counts nor ends that row, so loads that
+    each name other files than the one before are never counted. A start and
+    a change each have one load that names the files it started over and has
+    nothing to agree with yet, so neither writes such a line; each is
+    counted, so a healthy service shows one `notKept` at its start and one
+    after each change. A change that lands while a load reads the files,
+    names the same files, and changes the views or what the workspace is
+    resolved from, makes that load keep nothing as well, and so writes one
+    line and counts two. Any other change that lands then counts one, as a
+    change does, and writes nothing.
+
+  A row of failures goes on through loads that answer between them, and ends
+  at the first load that answers a minute or more after its last failure; a
+  line is written then (`afterFailures`). That line comes with the first load
+  after the minute, which under a kept project is the next reload, two and a
+  half minutes after the load that kept it, and none comes if no load
+  follows. A row of slow
+  loads ends the same way, at a load that answers in time a minute or more
+  after the last slow one. So, while loads come less than a minute apart (a
+  load at every request, or the retries after a failure), a loader that
+  fails, or is slow, every other load or every third keeps one row, written
+  less and less often, instead of a line per load. While a project is kept it
+  is loaded again every two and a half minutes, so there a row of failures
+  ends at the next reload that answers: a loader that answers at least one
+  reload between two failures writes each failure and the load that ends its
+  row, as before, and one that fails at every reload and answers only at its
+  retry keeps one row. Each slow load is written there, as before. A row
+  of loads after which nothing is kept ends at the next load that keeps the
+  project and named the files it started over. A healthy service writes none
+  of these lines. The log is cut over only when it is opened, so a line per
+  load, every two seconds while a file vouches for nothing, would have grown
+  it without bound.
+
 Refusals, before anything else is looked at: `Host` other than the listener's
 literal loopback authority, a cross-site `Origin` or `Sec-Fetch-Site`, a path
 other than one of the nine exactly (a query included), or another method (the
@@ -414,7 +549,11 @@ is authenticated, so they only ever decide what is shown.
   directory changed) and one HMAC per vault; at most four handshakes wait per
   view, and recorded challenges can keep them filled for at most about
   thirty seconds after a restart, since a challenge is answered only within
-  thirty seconds of the time it names.
+  thirty seconds of the time it names. A status request of a session costs a
+  read of the project's configuration files and of its workspace pointer; the
+  project itself is loaded again when one of those files changed, every two
+  and a half minutes, or at every request while one of them vouches for
+  nothing (see "The channel").
 - Egress. `plugins/` is in the egress scan, which fails a request whose target
   is not a literal loopback address, and the release audit requires the three
   plugin files in the package and scans them in the tarball.
@@ -488,6 +627,72 @@ note open in the editor.
 
 ## Evidence
 
+- `test/obsidian-plugin-status-continuity.test.mjs` exercises transient history
+  and the shipped request flow through a finite, socket-free `http.request`
+  stand-in. Canonical channel computations seal the invented replies. It
+  checks refused and timed-out lease/status requests, rejected leases followed
+  by interrupted handshakes, listener proof and answer authentication,
+  republished data, notice deduplication and recovery, and late answers after
+  a channel change or unload. It opens no service or app and writes no plugin
+  data. These tests complement the real-listener and real-app checks below.
+- `test/obsidian-view-permission.test.mjs` asks whether the project allows a
+  view the way the service asks before a status answer, over real project
+  files, the real loader and the real workspace resolution, with no listener,
+  with time a number the test moves: every way a view or its
+  workspace is withdrawn and given back; the workspace's identity compared as
+  well as its place; two loads per change however often a view is asked
+  about; a change that keeps a file's size and modification time; a change
+  that lands during a load; a file the project comes to name; a configuration
+  file that is a link, retargeted, or a link to a link; a folder, a link that
+  leads nowhere and a link to a folder in a file's place; a kept project's
+  time; a loader that fails, with its backoff; and a loader that answers a
+  promise: one load at a time, a change undone and done again while it runs,
+  through a link, a load that never answers, one whose answer comes after its
+  deadline before any request, and one refused again and again; a link whose
+  target has a `..` after a link, and a link to a folder above a file pointed
+  at a byte-for-byte copy; two loads that differ in a time and a symbol-keyed
+  binding, or in a protected root; how long each load took and how it ended;
+  and the service refusing to start on a loader that answers a promise, a
+  refused promise or a thenable. Mutations of the module (a link that vouches
+  for nothing, a project kept from one load whose files are read again when
+  it answers, no deadline, no backoff, no identity check, the files not taken
+  from the load, no time limit, a late answer taken, JavaScript's realpath, no
+  real path for a regular file, the whole project compared, no protected
+  roots compared) and a service that does not refuse each fail at least one
+  of them. It also covers: a late refusal after the deadline; which loads the
+  log report writes (a row of failures or of slow loads kept through loads in
+  time between them until a minute without one, so a loader that fails every
+  other or every third load writes one row; loads after which nothing is
+  kept, from the second in a row, and loads that named other files, which
+  neither count nor end that row) and that a line holds no path; a load at
+  every request written while a file vouches for nothing and while loads
+  never agree, and none at a change that names other files; each input of the
+  workspace resolution (pointer folder, data-root preference, protected
+  repositories) keeping two loads apart; a system that resolves no path, for
+  a regular file and for a link; and, through the test service entry in a
+  child process, a start under `--startup` on a promise, a refused promise,
+  a thenable (its `then` called once) and a refused promise with a `then` of
+  its own that throws (never called), which asks the loader once, records the
+  refusal and ends with 0; and one on a loader that throws `undefined`, a
+  value with no prototype or one whose `code` cannot be read, or answers a
+  project whose `then` cannot be read, which logs `untyped-error` with the
+  text of what was thrown (its message, or the value itself, `undefined` for
+  `undefined`, and `unprintable` when it cannot be made text) and ends
+  with 1. `test/obsidian-personal-selection.test.mjs` covers a locator that
+  answers a thenable (its `then` called once) or throws `undefined`. Ten more
+  mutations (the loader asked twice at such a start, its
+  promise not let go, every load or every failure written, no fallback for a
+  regular file or one for a link too, a late refusal not given up, and each
+  of the three inputs dropped) each fail at least one case, and so do a row
+  of failures or of slow loads ended at any load in time, a load after which
+  nothing is kept written from the first in a row, the first load counted
+  among those, a kept project that does not end that row, a load that named
+  other files counted or ending it, and the files taken as vouching when they
+  did not.
+  `test/obsidian-personal-workspace.test.mjs` keeps a bound personal
+  workspace from the loader that composes in a worker: its views once two
+  compositions agree, nothing while its generation is refused, and the next
+  generation's views once that is bound.
 - `test/obsidian-plugin.test.mjs` runs the shipped `main.js` in a stand-in app
   against a real listener on an ephemeral loopback port: parity of the
   plugin's constants and of every proof and MAC with the channel contract (a
@@ -517,7 +722,13 @@ note open in the editor.
   drift left for the person asked about once),
   and an upgrade; the service publishing the plugin and the plugin it
   published holding the view; qualification from a plugin report, with one
-  launch or two; and `status` and `open` reporting it. A spawn guard refuses
+  launch or two; `status` and `open` reporting it; a view the project turns
+  off or no longer declares, told nothing of what the service stored about
+  it, before the next tick and after it, and told as before once it is
+  allowed again; a project whose pointer is pointed at another workspace,
+  told nothing until it names this one again; and a loader that answers a
+  promise, never waited for, with the plugin keeping its session meanwhile.
+  A spawn guard refuses
   any child of the suite that could reach an Obsidian with the developer's
   own `HOME`.
 - The same file has three real-app tests, skipped unless
@@ -556,64 +767,3 @@ note open in the editor.
   storage. Writing the profile's local storage would mean editing a LevelDB
   database behind the app's back, and calling `app.plugins.setEnable(true)`
   would skip the prompt altogether.
-
-## Phase 2 plan
-
-Phase 2 moves the in-app critical section of publication into the plugin, and
-closes gates G20 and G21 of the initiative. Nothing below is implemented.
-
-1. Commands. The channel gains the publication protocol's three operations,
-   `inspect`, `publish` (`replace` and `remove`) and `collect`, with the
-   payloads the command-line path validates today (`validatePayload`), and a
-   protocol variant, `obsidian-plugin-critical-section/v1`, recorded in every
-   journal it writes. The service stays the only client that starts work; the
-   plugin fetches work with a bounded long poll (`POST /plugin/work`) and
-   answers with `POST /plugin/result`, both sealed under the session's key
-   like every command of phase 1, so the plugin never listens on a port and
-   takes work only from a service that proved it holds the vault's key.
-   At most one operation per vault is in flight, every operation has an
-   identity, a lost answer is recovered with `collect`, and a publish is never
-   sent twice.
-2. The critical section. The plugin runs the same synchronous body the
-   command-line path sends through `eval` (`criticalSection` in
-   `bridge-script.mjs`), shipped in `main.js` rather than sent: refuse on a
-   dirty or differing editor in any window, refuse on changed bytes on disk,
-   exchange atomically, update open editors in one transaction of minimal
-   hunks and record `lastSavedData`, record the outcome, reply at once. The
-   late-writer re-check and the manifest commit stay in the publisher.
-3. Path selection. With a live lease from a plugin whose protocol matches, the
-   publisher uses the plugin channel; otherwise the command-line path, and
-   with no app running, the app-free path, exactly as today. A refusal is
-   never relaxed by switching paths.
-4. Live edit preservation. The plugin forwards the vault's `modify` events and
-   the editor's dirty state for Atelier's notes to the service as they happen,
-   so an edit is preserved in recovery before any maintenance tick looks for
-   it. The service still decides what an edit is.
-5. G20. The complete G00 interleaving suite (sixteen interleavings, racing
-   cases repeated) and the G04 production-publisher suite run in plugin mode
-   on a real isolated app, unchanged, with zero lost bytes. A case that passes
-   on the command-line path and fails in plugin mode fails the gate; the suite
-   is not narrowed.
-6. G21. Apply and Discard in the status window for held edits, forwarded to
-   the service's existing apply operation, which decides; then the procedure
-   AP-08: enable, disable, uninstall and an app below the floor on one vault
-   with pending edits and recovery bytes, comparing manifests, path
-   allocations, pending edits and recovery digests with the command-line path
-   after each step.
-
-Open questions for phase 2: when, if ever, plugin files are removed from a
-vault; and how an upgraded service answers an older `main.js` that the app
-keeps running until it reloads the plugin (the hello carries the plugin
-version and the protocol for that).
-
-### Deviations from the track plan
-
-The obsidian-plugin track planned an optional enhanced mode. The owner's
-decision of 2026-09-24 made the plugin the primary in-app half, shipped in
-every managed vault, with the command-line path as the fallback. Phase 1 here
-therefore builds the plugin, its delivery and a presence and status channel
-before the publication commands the plan's first phase describes; the parity
-held today is between the plugin's constants and the channel contract, and the
-refusal parity with the command-line path belongs to phase 2, when the plugin
-carries publication commands. Fixtures are generated in temporary directories
-rather than kept under `fixtures/obsidian/plugin/`.

package/docs/{practical-judgment.md → reference/phronesis.md}

@@ -1,15 +1,24 @@
-# Practical Judgment and practice adoption
+# Phronesis — practical judgment
 
-Practical Judgment supports deciding what matters and what is fitting in a
+Phronesis supports deciding what matters and what is fitting in a
 particular situation. It also supports cultivation: contrasting cases, warranted
 exceptions, questions, distinct voices and reflection on consequences. A useful
 deliberation can remain open or produce an action without producing a rule.
 
+Phronesis is a responsibility; the [Knowledge Graph](knowledge-graph.md) is a
+shared representation. Knowledge Stewardship remains the broader responsibility
+for knowledge inclusion and applicability. Phronesis draws on the shared graph
+and contributes cases, decisions and learning through existing Knowledge records,
+review and activation. It introduces no new store or canonical authority and
+does not supply automatic wisdom or a universal score.
+
 `@mnstry/atelier/judgment` validates portable cases and native architecture
 decision snapshots. `inspectPracticalCase` preserves purpose, values, evidence,
 alternatives, dissent, cultivation exercises and reconsideration conditions.
 It does not score wisdom. The invented workshop fixtures demonstrate an open
 deliberation and a decision whose implementation is still planned.
+The API and the `atelier-practical-judgment` skill identity retain their existing
+names and compatibility obligations.
 
 ## Architecture decisions
 
@@ -31,7 +40,7 @@ review and dependency reconsideration. Do not change an old record in place.
 
 ## From feedback to intrinsic practice
 
-The [learning lifecycle](learning.md) captures an observation, proposes a scoped
+The [learning lifecycle](../guides/learning.md) captures an observation, proposes a scoped
 lesson, records an exact decision, then activates the accepted version for a
 named harness. `capabilityEventToLearningInput` bridges version-bound capability
 metadata into that lifecycle. It retains the reported cause, binding, release,

package/docs/reference/portability.md

@@ -0,0 +1,92 @@
+# Portability: what a record holds and what the checks prove
+
+An Atelier workspace is meant to be enough for another team to build from,
+without rediscovering the work it describes. This page says what a complete
+record holds, what each check proves about it, and where the line between the
+record and a running product falls. `docs/reference/continuity.md` covers the
+package's own continuity commitments; this page covers yours.
+
+## What a complete record holds
+
+| What the record must hold | What another team needs from it |
+| --- | --- |
+| Rules and calculations | The rules the product applies, their inputs, how each result is computed and interpreted, exceptions and versions. |
+| Agent behavior | Instructions, tone, context requirements, permitted actions and example exchanges. |
+| Product and interface | Screens and flows, state changes, saved results, access rules, and what one person or a group can do. |
+| Content and brand | Copy, published material, design references and assets, with ownership or license terms. |
+| Business workflows | Processes, responsibilities, handoffs and approval rules. |
+| Data and connections | Your systems' data formats, identifiers, relationships and export instructions, plus the service interfaces and dependencies a replacement would reconnect. |
+| Tests and decisions | Representative inputs and expected results, quality criteria, accepted decisions and relevant revision history. |
+
+**Every custom rule has a retained explanation.** If a rule determines a
+result, a reply, access or a next step, its meaning belongs in the authored
+record, including when software executes it.
+
+## How the record is checked
+
+In three parts. The first two are package commands; the third is not.
+
+The export validator checks conformance: the record is in the published
+format and every reference resolves to a declared source. What it refuses
+across a source's `audience` and an export's `visibility` is stated in the
+README's audience-visibility block.
+
+```bash
+atelier dry-run ./atelier-export.json
+```
+
+The report says `accepted`, and separately whether the artifact is
+`importable`. The validator resolves references to declared provenance
+entries, not to packaged content, so it proves the artifact's shape and its
+references, not that everything necessary was written down.
+
+The readiness protocols check coverage inputs: a supplied answers file is
+checked against each protocol's required inputs, and the missing ones are
+listed. An answer being present is not evidence that it is right.
+
+```bash
+atelier readiness run PROTOCOL_ID --answers answers.json --project ./atelier.project.json
+```
+
+That run is an input-completeness check and is not evidence-bound. For a run
+bound to its sources, `atelier review run PROTOCOL_ID --answers answers.json`
+records that source-bound run. Accepting one of its claims in the review
+workspace checks source linkage. A linked source establishes which
+bytes were read, not whether they logically support the proposed claim
+(`docs/guides/local-review.md`). The responsible people review coverage; an
+issuer can record its admission decision in an attestation bound to the canonical form of the document it
+judged (`docs/reference/attestation.md`).
+
+The record also carries its own tests. A complete record gives every
+documented rule representative inputs and expected results beside it. The
+package keeps these cases and links them to their rules; it does not run them.
+Whatever executes the rules runs them, so name that runner when you cite this
+check.
+
+Together the three show what has been delivered and what remains unresolved,
+in the record rather than in someone's memory. A rebuild also needs the authored
+rules, their representative tests, the data exports, the dependencies and the
+operating instructions, reviewed together against the agreed scope. No
+validator can supply that review.
+
+## The dividing line
+
+If it describes how the work is done, it is a file in the Atelier. If it
+records what happened to a particular person, or has to be enforced at the
+moment of use, it lives in a product runtime. A folder of files cannot
+decide, while two people are in a session, which of them may see what;
+cannot hold a payment; and cannot be the consistent, recoverable record when
+several parties write at once.
+
+The Atelier holds how the work is done and the documentation of your systems'
+data: formats, identifiers, relationships and export instructions. Records
+about particular people live in the systems you run. What the package will
+and will not do toward any runtime is stated once, in the README's
+will-not-do block; this page adds nothing to it.
+
+## Copying the record
+
+The repository is the store, Git is the history, and a copy of the folder is a
+copy of the whole record. A copied folder carries the record and its history,
+not remote data or assets stored elsewhere; the data-and-connections row above
+is where those are described so a replacement knows where to look.

package/docs/{portable-presentation.md → reference/portable-presentation.md}

@@ -2,8 +2,8 @@
 
 Status: opt-in implementation candidate, not a published or adopted interface.
 Contract discussion: [issue 39](https://github.com/MNSTRY/atelier/issues/39).
-Current corrections and remaining adoption conditions:
-[review disposition](presentation-review-disposition.md).
+Current compatibility and adoption conditions are in
+[consumer boundaries](presentation-consumer-boundaries.md).
 
 ## Placement and authority
 

package/docs/{presentation-consumer-boundaries.md → reference/presentation-consumer-boundaries.md}

@@ -44,6 +44,11 @@ font loads; no-JavaScript readability and absence of motion are the baseline.
 5. Obtain the separate source, CI, maintainer and deployment authorities. The
    reference consumer neither allocates a product path nor activates a site.
 
+Synthetic composition events and browser/React fixtures do not establish real
+OS input, screen-reader behavior or native performance. Verify pending/busy
+announcements with actual assistive technology and profile the receiving native
+host before changing its confirmation guards.
+
 ## CI integration handoff
 
 The existing workflow does not yet execute either browser proof. A maintainer

package/docs/{project-options.md → reference/project-options.md}

@@ -31,6 +31,23 @@ Resolution may create ignored `.atelier-local/` directories; this diagnostic is
 not a promise of a write-free invocation. The ordinary config report retains
 its existing shape and local config path.
 
+## Bundled readiness selection
+
+The tracked `atelier.project.json` may set
+`ext["mnstry.atelier"].readiness.includeBundled` to `false` to deselect the bundled
+MNSTRY readiness pack. An absent setting or explicit `true` preserves the
+existing default. `readiness` must be an object and `includeBundled` a boolean;
+invalid values fail with `readiness-selection-invalid`. This is a project
+setting, not a CLI flag or local preference.
+
+Project-aware protocol listing and runs then use only selected custom packs;
+generic graph, projection and readiness checks remain available without the
+MNSTRY tenant journey. A bare protocol listing without a project selection
+retains its standalone bundled list. Review selection changes and run
+`atelier lock write --project ./atelier.project.json`; see
+[readiness pack selection](../guides/tenant-readiness.md#select-the-readiness-pack)
+for lock checks and commands that require the bundle.
+
 ## Command inventory
 
 | Family | Project handling | Other effects |