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

package/docs/obsidian.md

@@ -72,13 +72,18 @@ A focus keeps the full vault on disk and filters the native Graph view. The
 query is
 
 ```
-path:"<note path>" OR path:"<note path>" ...
+path:/^<note path>$/ OR path:/^<note path>$/ ...
 ```
 
-in the order of the selected set (canonical-id order). Inside the quoted term
-a backslash and a double quote are escaped with a backslash; nothing else is
-changed, so a path that itself contains search operators (`tag:`, `-`, `OR`,
-parentheses) stays text. Paths are NFC-normalized before they are quoted. A
+in the order of the selected set (canonical-id order). Each term is a regular
+expression anchored at both ends, so it matches exactly one note: a plain
+`path:` term matches any path that contains it, and with titles as names one
+note's path can lie inside another's. In the term every regular-expression
+character and the `/` delimiter is escaped with a backslash, and a space and
+a double quote are written as `\x20` and `\x22`, so a path that itself
+contains search operators (`tag:`, `-`, `OR`, parentheses) stays text. Paths
+are NFC-normalized first. A persisted focus of the earlier query version
+(`obsidian-graph-search-paths/v1`, quoted substring terms) is still read. A
 path that carries a control character, a C1 control, or the U+2028 or U+2029
 line separator cannot be a search term and refuses with
 `focus-path-unrepresentable`; so does an absolute path, a backslash path or a
@@ -256,7 +261,7 @@ nothing under `scripts/obsidian/` ships.
 | --- | --- |
 | `@mnstry/atelier/obsidian` | `src/runtime/obsidian/index.mjs`: enablement, machine settings, engine, service lifecycle, production seams, app qualification |
 | `@mnstry/atelier/obsidian/contracts` | `src/projection/obsidian/contracts.mjs`: contract validation, `selectScope`, note paths |
-| `@mnstry/atelier/obsidian/materialize` | `prepareView`, settings, path registry |
+| `@mnstry/atelier/obsidian/materialize` | `prepareView`, settings (including the plugin's files and entry), path registry |
 | `@mnstry/atelier/obsidian/publication` | `publishView`, editor adapters, the exchange |
 | `@mnstry/atelier/obsidian/recovery` | recovery store, journals, late-writer recheck |
 | `@mnstry/atelier/obsidian/edits` | edit observation, arbitration, apply policy, source apply |
@@ -272,9 +277,10 @@ What the tarball must and must not carry, and the package proof, are in
 
 ## First vault: what to expect
 
-This is the path an adopter walks on one machine, in the order the command
-requires it. Every operation and flag below is the shipped `atelier obsidian`
-usage text; `atelier obsidian --help` prints it.
+This is the path an adopter walks on one machine. Every operation and flag
+below is the shipped `atelier obsidian` usage text; `atelier obsidian --help`
+prints it. There are three steps, and none of them is done by hand in
+Obsidian.
 
 1. Enable the projection in the project configuration. The member
    `ext["mnstry.atelier.obsidian"]` is an `atelier-obsidian-ext-settings/v1`
@@ -295,15 +301,54 @@ usage text; `atelier obsidian --help` prints it.
      has to carry; `policy install FILE` installs it and leaves the mode
      unchanged; `policy revoke` returns the mode to `manual` and stops every
      later apply.
-3. Start the maintenance service:
-   `atelier obsidian service start --consent-actor ID --adapter=obsidian-cli`.
-   Reaching the installed app is never a default, so `--adapter=obsidian-cli`
-   is required, and the consent actor records who allowed the service to run.
-   `service status` and `service stop` manage it; `service unit --print
-   --adapter=obsidian-cli` prints a startup unit and installs nothing.
-4. Open a view: `atelier obsidian open --scope ID --adapter=obsidian-cli`.
-   The command starts or reconnects maintenance, verifies the vault by reading
-   it back, and asks the app (version 1.13.7 or later) to open it.
+3. Open a view:
+   `atelier obsidian open --scope ID --consent-actor ID --adapter=obsidian-cli`.
+   That's it. Reaching the installed app is never a default, so
+   `--adapter=obsidian-cli` is required, and the first open of a workspace
+   records who allowed the maintenance service to run (`--consent-actor`;
+   later opens reconnect to it and need no consent). `open` starts or
+   reconnects maintenance and asks it for a tick, makes Obsidian (version
+   1.13.7 or later) know the view's vault as one of its vaults, opens it,
+   publishes the view, verifies the vault by reading it back, and waits until
+   the app answers for exactly that vault. It does this in whatever state
+   Obsidian is in; see
+   [What `open` does in each state of Obsidian](#what-open-does-in-each-state-of-obsidian).
+
+The maintenance service can also be managed on its own:
+`atelier obsidian service start --consent-actor ID --adapter=obsidian-cli`,
+`service status` and `service stop`; `service unit --print
+--adapter=obsidian-cli` prints a startup unit and installs nothing.
+
+After an upgrade of Atelier, a maintenance service started earlier still runs
+the earlier release. `open` replaces it: when the service of this workspace
+proves itself Atelier's own but runs an earlier release than the installed one
+(its record names the release it runs: the package version and a digest of
+its modules; an earlier version, the same version with other modules, or no
+release named), or refuses a tick that names a view as releases up to
+0.2.0-alpha.11 do,
+`open` stops it as `service stop` would and starts the installed release under
+the consent already recorded, and says `service: restarted (outdated)`. A
+service of a later release is never replaced by an earlier one, so two
+installations used on one workspace (a global and a project-local one, say)
+do not replace each other's service on every open: `open` answers
+`service-unavailable` / `service-other-release`; run `atelier obsidian service
+stop`, then open again, or open with the later release. A service in a long
+tick is not stopped (`open` answers `busy`), and a listener that does not
+prove itself this workspace's service is never touched.
+
+The first time Obsidian opens a view's vault it asks "Do you trust the author
+of this vault?", because every vault Atelier publishes carries Atelier's own
+plugin. "Trust author and enable plugins" turns it on: a status bar item then
+says whether the view is current, updating, held for an edit you made, stale,
+or whether the maintenance service does not answer, and "Atelier: show status"
+says why. "Browse vault in Restricted Mode" keeps every community plugin off
+in that vault, and nothing else changes: maintenance, `open` and `status` work
+without the plugin, as they always did. Obsidian keeps the answer per vault in
+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).
 
 `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
@@ -315,7 +360,9 @@ and the view is not republished over it. The remaining outcomes (`indexing`,
 `publisher-conflict`, `app-missing`, `app-version-unsupported`,
 `app-cli-unavailable`, `launch-failed`, `service-unavailable`, `busy`,
 `disabled`) each name what to do next, and exit code 3 says the answer is not
-success.
+success. Both also report Atelier's plugin for each view, under `plugin`:
+present while it holds the vault open in the app, with the app and plugin
+versions, or not present with the reason.
 
 Edits made in the vault are preserved before anything is republished. A body
 replacement is held as a pending edit; under manual mode it reaches its source
@@ -338,17 +385,120 @@ absolute directory. Private state inside an enrolled repository is refused.
 Publication is proven on macOS arm64 only and is refused on Windows; see
 [Known limits](#known-limits).
 
-### First publication while Obsidian is running
-
-The publisher writes into a vault only when it can coordinate with every
-Obsidian that might have it open. An Obsidian that is running without this
-vault open cannot be coordinated with, so the first publication of a view is
-refused as `publisher-conflict` with reason `editor-uncoordinated`, and
-nothing is written. Quit Obsidian: the service then publishes the view
-directly, and `atelier obsidian open --scope ID --adapter=obsidian-cli` starts
-Obsidian on it. An Obsidian with no vault open at all answers its command line
-with "Vault not found." for every command, its version included; that is
-reported as reason `no-vault-open`, and the same remedy applies.
+### What `open` does in each state of Obsidian
+
+Obsidian opens a vault from a link only when the folder is in its own vault
+list, the `vaults` of `obsidian.json` in its user-data directory. `open` puts
+the view's vault there first, and never asks a person to open a folder by
+hand. It then names the vault by its id (`obsidian://open?vault=<id>`), never
+by path where the id reaches it first: a path is matched against the list by
+string prefix, so a link for a note under `/A/strategy-lab` can open the
+listed vault `/A/strategy`. When another vault's folder is named like the id,
+or the id is unusual, the vault's own path is used, which the app matches
+exactly because the folder is listed.
+
+- **Obsidian runs and answers its command line (any vault is open).** `open`
+  reads the app's vault list through its command line. A vault the app does
+  not list is added and opened in a new window through the app itself (it
+  writes its own settings), and read back from its list. `open`
+  then waits, bounded, until the app answers for exactly this vault, and asks
+  maintenance for the view again: the publication runs through the app, which
+  now holds the vault, with every editor check of the publication protocol.
+  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
+  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
+  vaults would not come back the next time you start it. Started plainly, it
+  reopens every vault it had open, this one included, and once its command
+  line answers (the app itself, not the tool's "unable to find Obsidian")
+  `open` hands it the vault's link through that tool, never through the
+  operating system. On Linux a plain start is not
+  qualified yet, and Obsidian is started with the link (the other vaults'
+  reopen marks are lost there; a known limit).
+  An Obsidian that never ran on this account has no settings file yet, and
+  `open` does not create one: start Obsidian once, then open again.
+- **Obsidian runs with no vault open.** Its command line then answers every
+  command with "Vault not found.", so nothing can be asked of it, and its
+  settings file belongs to the running app, so it is only read. A vault the
+  app already lists is opened by path and published through the app as
+  above. A vault it does not list yet is answered as outcome
+  `app-version-unsupported` with reason `no-vault-open`: open any vault in
+  Obsidian, or quit it, and open again. This is the one state of a running
+  Obsidian that `open` cannot get through alone.
+- **Obsidian's command line is turned off** (the default of a new
+  installation). It then answers every command with "Command line interface
+  is not enabled", and only a link reaches it. With Obsidian running, `open`
+  adds and launches nothing. With Obsidian quit, `open` adds the vault to its
+  settings and starts it, and Obsidian opens the vault. Either way `open` then
+  answers `app-cli-unavailable` with reason `cli-turned-off` and says where to
+  turn it on: Settings > General > Advanced > Command line interface.
+  Publishing into a vault Obsidian holds needs it until Atelier's plugin takes
+  over that part.
+
+Only `open` adds a vault to Obsidian: the maintenance service never does, so
+it never opens a window nobody asked for. A declared view that was never
+opened is published while Obsidian is quit, and `open --scope ID` adds it.
+
+In no state does `open` add a view's vault inside a folder Obsidian already
+lists as a vault (your home folder, say): that vault would show the view's
+notes too, and a command-line call run in the view's folder would reach it.
+`open` answers `launch-failed` with reason `vault-inside-another-vault`:
+remove that vault from Obsidian's vault list, or keep Atelier's data root
+outside that folder. A view's vault that Obsidian lists already, below such a
+vault, is reached by its id instead (see "Which window answers" in
+[Known limits](#known-limits)).
+
+Obsidian can list one folder more than once, under another letter case or
+through a link, and then open it in one window per entry. Each of those
+windows holds the view's vault, and a publication coordinates with one window
+only, so none is made: the view reports `publisher-conflict` with reason
+`vault-open-in-several-windows`, and `open` answers the same, names the
+entries (`open in Obsidian as: …`; `duplicates` in JSON) and launches nothing.
+Remove the extra entries from Obsidian's vault list and open again. Closing
+the extra windows is not enough: Obsidian keeps the last window it closed
+marked open, so two entries can stay marked open with one window showing, and
+the view stays refused until the list names the folder once.
+While one entry of the folder has a window, `open` reaches only that one and
+never opens another entry of the same folder beside it.
+
+The publisher still writes into a vault only when it can coordinate with every
+Obsidian that may hold it, or when the process table shows, positively, that
+none runs. Otherwise it stops, and the view reports `publisher-conflict` with
+reason `editor-uncoordinated`. That reason has several causes, and the report
+does not say which: Obsidian runs without this vault open, or with it open but
+its command line did not answer; the process table could not be read, or on
+Linux shows an app that runs on a system Electron, which may be Obsidian; the
+app's version was not checked when the publication began; or an app started
+while the view was being published with the app closed. `status` gives
+`atelier obsidian open` as the next step (it adds the vault to Obsidian and
+publishes through it), or quitting Obsidian (on Linux, also any app that runs
+on a system Electron). When `open` itself already did that and the
+publication still stopped, it says to quit Obsidian and open again.
+
+The tick `open` asks for prepares and publishes its view once more, whatever
+state the view is in. A view whose last publication did not settle (refused,
+stale or still updating) is also tried again without waiting for a change: as
+soon as the app looks different (it quit or started, or opened or closed a
+vault in its list), and otherwise after a delay that starts at 30 seconds and
+doubles per attempt, up to the full reconciliation every five minutes. What
+the app looks like is read from the process table and the app's vault list
+alone: maintenance runs nothing in Obsidian to find out, and asks it for its
+version only when a view is about to be published, without blocking.
+
+While Atelier's plugin holds the view's vault open in the app and the command
+line gives no version (as it answers while a vault is still loading), the
+version the plugin reports stands in (reason `plugin-reported`); a version the
+command line gives always decides, and while the process table shows no app
+running, a plugin's report counts for nothing. `open` then asks the command
+line nothing: a vault the app's settings file lists is opened by path, and one
+it does not show is answered as `app-cli-unavailable` with reason
+`vault-open-cli-silent` (the app has the vault open; make sure its
+command-line interface is turned on). So is a listed vault the command line
+does not answer for once it is opened, while only the plugin reports the
+version: `open` says so at once instead of waiting for the app.
 
 ## Known limits
 
@@ -375,7 +525,22 @@ 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).
+  [obsidian-contract.md](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
+  asks it nothing. That publication stops as `publisher-conflict` with reason
+  `editor-uncoordinated`, and the next publication asks again and reads the
+  version. A view that stopped is tried again on the next tick `open` asks
+  for, as soon as the app looks different, and otherwise after a delay that
+  starts at 30 seconds and doubles, up to the full reconciliation every five
+  minutes. A tick `open` asks for never reuses a remembered app answer.
+- Install location (macOS): the app is found only at
+  `/Applications/Obsidian.app`, and its command-line tool only inside it. An
+  Obsidian installed elsewhere, or a renamed bundle, is `app-missing`.
+  Nothing is published through it, publication waits while it runs (the
+  process probe still sees it), and `open` answers `app-missing` and cannot
+  start it. With it quit, the view is published on the path with no app.
 - No vault open: while Obsidian runs with no vault open, its command-line tool
   answers every command, `version` included, with `Vault not found.`. The
   version floor cannot be checked then, so the app does not qualify:
@@ -383,23 +548,87 @@ test reported as a pass.
   published through the app. `status` (under `service.app`) and `open` say what
   to do: open any vault in Obsidian, or quit Obsidian. With the app quit,
   maintenance publishes on its own path again; with a vault open, it reads
-  the version again on a later tick. `open` launches nothing while the app
-  runs with no vault open, and after its own launch it waits, bounded, while
-  the app is still opening the vault.
-- Detecting the app: the process table is read with `ps -A -o comm=`, and the
-  app is recognised by the executable a process runs, never by its arguments,
-  so a path argument that contains an `obsidian` directory (the maintenance
-  service itself, anything under the private data root) is not the app. On
-  macOS the executable `Obsidian` and the bundle's `Obsidian Helper`
-  processes count, in any directory. On Linux a process named `obsidian`
-  counts, which covers the .deb, snap, AppImage and Flatpak builds. A
-  distribution that runs the app under a system Electron shows only
-  `electron`: the table is then `unknown`, which is treated as a running app,
-  so publication through the app-free path waits until no such process runs.
-  The command-line tool (`obsidian-cli`) is a client of the app and is not
-  counted. A process renamed by its packager, 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 version again on a later tick. While the app runs with no vault open,
+  `open` has it open a vault only when its list already knows that vault,
+  by path; one it does not know cannot be added then (see below). After its
+  own launch `open` waits, bounded, while the app is still opening the vault;
+  an app whose vault window is still loading answers a command with `Error:
+  Command "…" not found`, which is read as not up yet, never as a version.
+- Obsidian's settings file: `open` adds a view's vault to the app's own list,
+  `obsidian.json` in its user-data directory: `~/Library/Application
+  Support/obsidian` on macOS and `$XDG_CONFIG_HOME/obsidian` (else
+  `~/.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
+  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
+  when no build wrote one from its installation; for a Flatpak or snap build
+  the file is then neither read nor written: `open` answers
+  `obsidian-sandboxed` and says to start Obsidian with any vault open, then
+  open again, and adds the vault through the app. On Windows no location is
+  known, and `open` adds the vault through the app in the same way.
+- Recent items: adding a vault through the running app is Obsidian's own
+  "open folder as vault", which also puts the vault's folder in the operating
+  system's recently used documents (Recent Items on macOS).
+- Which window answers: Obsidian answers a command-line call that names a
+  vault (`vault=<id>` first) in that vault's window; any other call in the
+  window of the first vault in its list whose folder is the tool's working
+  directory or contains it, and otherwise in the vault window that had focus
+  last. A vault that takes a call is opened when it is closed. Calls about a
+  vault therefore name its id; only when that id would name another vault
+  first (one whose folder has the id as its name) do they run inside its
+  folder instead, and not at all when a vault listed before it at a folder
+  above it (your home folder, say) would take them there. The vault root is
+  taken in the spelling the file system stores, so a data root given in
+  another letter case on macOS changes nothing. Publication calls do this
+  only while the app's list shows the view's vault open, and run in a
+  directory that is no vault otherwise. So maintenance never reopens a vault
+  window you closed while Obsidian keeps running, and never reaches another
+  vault: publication then stops as `publisher-conflict` until `atelier
+  obsidian open` opens the vault again or Obsidian quits.
+- Detecting the app: the process table is read with `ps -A -o comm=`
+  (`pid=,comm=` on Linux), and the app is recognised by the executable a
+  process runs, never by its arguments, so a path argument that contains an
+  `obsidian` directory (the maintenance service itself, anything under the
+  private data root) is not the app. A `ps` that has not answered within five
+  seconds is killed and the reading is `unknown`, which is treated as a
+  running app.
+  - macOS: the executable `Obsidian` and the bundle's `Obsidian Helper`
+    processes count, in any directory. An app started through a differently
+    named link shows that name for its main process; its `Obsidian Helper`
+    processes still count.
+  - Linux: a process named `obsidian` counts, which covers the .deb, snap,
+    AppImage and Flatpak builds. Linux names a process after the path it was
+    started through, so for a name that is not recognised the probe reads
+    the executable `/proc/<pid>/exe` resolves to: an app started through a
+    link or launcher named `obs`, or a child started through
+    `/proc/self/exe` whose executable is readable, still counts. A process
+    whose executable this user may not read (another user's, or one of this
+    user's that hides it from tracing, such as ssh-agent) or that exited
+    meanwhile is judged by its name alone. Any other read failure, or a
+    table in which no executable resolves at all, is `unknown`. A
+    distribution that runs the app under a system Electron shows only
+    `electron`: the table is then `unknown`, so publication through the
+    app-free path waits until no such process runs.
+  - 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 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,
+  that no Obsidian runs. It applies only then. The table is read at path
+  selection, again immediately before the first note, and again whenever two
+  seconds have passed. An app that starts between two readings is not seen
+  for at most two seconds plus one note's publication, and in that window a
+  note is exchanged with no editor check. Bytes on disk stay protected by the
+  on-disk comparison and the exchange. An unsaved buffer in the newly started
+  app does not: the app applies its own external-modification merge, which
+  can drop overlapping edits. Once a reading shows an app, every remaining
+  note refuses. To avoid the window, do not start Obsidian while a view is
+  being published with the app closed.
 - CRLF sources: the editor normalizes line endings when it saves, so a body
   edit made in the vault to a note whose source uses CRLF is more than a body
   replacement to the edit lens. It is preserved and becomes a proposal; it is
@@ -408,6 +637,15 @@ test reported as a pass.
 - An edit the byte lens cannot turn into source bytes (a new or changed link
   to another note of the vault, an edited front matter) becomes a copy-only
   proposal. No operation applies one.
+- Atelier's plugin (phase 1) reports presence and status and decides
+  nothing: publication still coordinates with the app through its
+  command-line tool, which must be enabled, and the plugin only supplies the
+  app version where that tool gives none. A person who turns the plugin off
+  in a vault, or uninstalls it there, is followed: its entry is not added
+  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).
 - Acceptance: a schema-valid receipt closes no gate, the package proof closes
   no gate, and no adopter acceptance is recorded in this repository.
 
@@ -421,3 +659,9 @@ The test suite proves each oracle can fail:
 - `createReceiptValidatorForOracleTests` accepts a rule table with one rule
   switched off; every negative case that depends on that rule then passes,
   and even that closes nothing.
+- `openScopeForOracleTests` with an `OPENING_PRIMITIVES.keptByApp` that
+  never holds: an open with Obsidian running without the vault reports the
+  publisher conflict it could have cleared, and the first-open oracle fails.
+- `createMaintenanceEngineForOracleTests` with an
+  `ENGINE_PRIMITIVES.isRetryDue` that never holds: a refused view waits for
+  the full reconciliation, and the retry oracle fails.

package/docs/release-engineering.md

@@ -63,7 +63,13 @@ Shipped, and required by the audit:
 - Every `contracts/atelier-obsidian-<name>.v<n>.schema.json` present in the
   source tree (lowercase name, versioned). Each must be packed and exported
   under its own path, and the audit fails if it finds none.
-- `docs/obsidian.md` and `docs/obsidian-contract.md`.
+- `docs/obsidian.md`, `docs/obsidian-contract.md` and `docs/obsidian-plugin.md`.
+- Atelier's own Obsidian plugin, which every managed vault receives:
+  `plugins/obsidian/manifest.json`, `main.js` and `styles.css`, the only files
+  admitted under `plugins/`, with its channel
+  (`src/projection/obsidian/plugin-bridge/index.mjs`) and the service's half
+  (`src/runtime/obsidian/plugin-channel.mjs`). `main.js` is scanned for egress
+  like every packed script.
 - `fixtures/obsidian/**`: small synthetic text only. Every packed fixture, in
   any subtree and spelling under `fixtures/`, is at most 262,144 bytes. The
   acceptance receipts under `fixtures/obsidian/acceptance/receipts/` are

package/docs/upgrade.md

@@ -9,6 +9,35 @@ 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.12
+
+This release makes the first open of an Obsidian view automatic and ships
+Atelier's own plugin. `open` adds the view's vault to Obsidian itself, whether
+Obsidian is running or not, and publishes without quitting it; a closed
+Obsidian is started so your other vaults reopen. Vaults are laid out
+readably: folders mirror your repository and file names are note titles,
+with identity kept in a properties block; a vault published by an earlier
+release is laid out again once, keeping held edits. Each managed vault gets
+the Atelier plugin (one trust prompt per vault) with a status bar. A
+maintenance service of an earlier release is replaced by `open` under the
+consent already recorded. No project or machine setting needs to change.
+Machine settings stay v1; generation manifests move to v2 (below).
+
+Node.js 24 (24.13.1 or later) is now supported alongside Node.js 22, and
+both write byte-identical graph files, so people on either can share a
+repository. `atelier dev` on a port that is already taken now says
+`port-in-use` and names `--port=<free port>`; before, it printed an internal
+error. A script that read that failure's exit code sees 2 instead of 1.
+
+## Upgrading to 0.2.0-alpha.11
+
+This release tightens the Obsidian projection's app checks after independent
+review of 0.2.0-alpha.10: Atelier never coordinates with an Obsidian whose version it
+has not checked, the advice for a refused publication is true for every cause
+and appears in `status` as well as `open`, Linux resolves an app started
+through a differently named launcher, and the process check has a timeout.
+No project or machine setting needs to change.
+
 ## Upgrading to 0.2.0-alpha.10
 
 This release fixes the first activation of the Obsidian projection. In
@@ -154,7 +183,7 @@ See `docs/contract-stability.md`.
 ## Before You Upgrade
 
 - Start from a clean Git status in the copied workspace.
-- Confirm Node.js matches the package range: `>=22.18.0 <23`.
+- Confirm Node.js matches the package range: `>=22.18.0 <23 || >=24.13.1 <25`.
 - Keep this package root and copied starter workspaces separate.
 - Keep upgrade diffs generic: placeholders only, no project-specific private
   material, transcripts, support bundles, local absolute paths, local agent
@@ -176,7 +205,7 @@ For registry installs, pin the exact version and record the resolved version
 in the lockfile:
 
 ```bash
-npm install --save-dev @mnstry/atelier@0.2.0-alpha.10
+npm install --save-dev @mnstry/atelier@0.2.0-alpha.12
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 
@@ -184,7 +213,7 @@ For Git installs, pin the release tag rather than a branch, so the lock file
 records exactly what was reviewed:
 
 ```bash
-npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.10"
+npm install --save-dev "git+https://github.com/MNSTRY/atelier.git#v0.2.0-alpha.12"
 npx mnstry-atelier lock write --project ./atelier.project.json
 ```
 

package/fixtures/obsidian/contracts/generation-manifest-v2/invalid/case-only-collision.v2.json

@@ -0,0 +1,160 @@
+{
+  "schema": "atelier-obsidian-generation-manifest/v2",
+  "layoutVersion": 2,
+  "generationId": "gen-0001",
+  "scopeId": "scope-topic",
+  "snapshotId": "snap-0001",
+  "notes": [
+    {
+      "repoId": "north",
+      "nodeId": "a",
+      "title": "Shared concept",
+      "path": "north/topics/Shared concept.md",
+      "noteDigest": "sha256:5555555555555555555555555555555555555555555555555555555555555555",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 120
+        },
+        "identity": {
+          "start": 40,
+          "end": 116
+        },
+        "body": {
+          "start": 120,
+          "end": 280
+        },
+        "generated": [
+          {
+            "kind": "relations",
+            "range": {
+              "start": 280,
+              "end": 340
+            }
+          }
+        ]
+      }
+    },
+    {
+      "repoId": "north",
+      "nodeId": "d",
+      "title": "Shared concept",
+      "path": "north/topics/shared CONCEPT.md",
+      "noteDigest": "sha256:6666666666666666666666666666666666666666666666666666666666666666",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 40
+        },
+        "body": {
+          "start": 40,
+          "end": 200
+        },
+        "generated": [
+          {
+            "kind": "relations",
+            "range": {
+              "start": 200,
+              "end": 260
+            }
+          },
+          {
+            "kind": "identity",
+            "range": {
+              "start": 260,
+              "end": 340
+            }
+          }
+        ],
+        "identity": {
+          "start": 260,
+          "end": 340
+        }
+      }
+    },
+    {
+      "repoId": "north",
+      "nodeId": "e",
+      "title": "Diagram",
+      "path": "north/figures/diagram.svg.md",
+      "noteDigest": "sha256:8888888888888888888888888888888888888888888888888888888888888888",
+      "regions": {
+        "frontmatter": {
+          "start": 0,
+          "end": 80
+        },
+        "identity": {
+          "start": 0,
+          "end": 80
+        },
+        "body": {
+          "start": 240,
+          "end": 240
+        },
+        "generated": [
+          {
+            "kind": "representation",
+            "range": {
+              "start": 80,
+              "end": 240
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "links": [
+    {
+      "edgeId": "e4",
+      "sourceNodeId": "d",
+      "targetNodeId": "a",
+      "type": "links_to",
+      "origin": "markdown",
+      "targetState": "in-scope",
+      "inversions": [
+        {
+          "source": {
+            "start": 12,
+            "end": 30
+          },
+          "note": {
+            "start": 52,
+            "end": 96
+          }
+        }
+      ]
+    },
+    {
+      "edgeId": "e5",
+      "sourceNodeId": "a",
+      "targetNodeId": "d",
+      "type": "supersedes",
+      "origin": "declared",
+      "targetState": "in-scope"
+    },
+    {
+      "edgeId": "e1",
+      "sourceNodeId": "a",
+      "targetNodeId": "b",
+      "type": "related",
+      "origin": "declared",
+      "targetState": "outside-selection"
+    }
+  ],
+  "attachments": [
+    {
+      "path": "north/figures/diagram.svg",
+      "digest": "sha256:7777777777777777777777777777777777777777777777777777777777777777",
+      "byteLength": 900
+    }
+  ],
+  "completeness": {
+    "status": "complete",
+    "expectedNotes": 3,
+    "writtenNotes": 3
+  },
+  "freshness": {
+    "status": "current",
+    "checkedAt": "2026-01-05T10:00:05Z"
+  }
+}