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

package/docs/obsidian.md

@@ -282,18 +282,30 @@ 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`
+1. Declare a view in the project configuration:
+   `atelier obsidian view add everything --all`. It adds a view of every note
+   the machine may show to `atelier.project.json`, shows the change as a diff
+   and how many notes the view would show, and makes it the default view. You
+   commit the file; Atelier commits nothing. See
+   [Adding a view](#adding-a-view). The member it writes,
+   `ext["mnstry.atelier.obsidian"]`, is an `atelier-obsidian-ext-settings/v1`
    document: `enabled: true`, `scopes` (each with a `scopeId`, a `mode` of
    `full`, `scoped` or `focus`, a `selector`, and for an expansion an explicit
-   `depth` and `maxNodes`), and optionally `defaultScopeId`. A project without
-   this member is `disabled (not-configured)` and nothing is published.
-   `atelier obsidian scope list` shows what was declared.
+   `depth` and `maxNodes`), and optionally `defaultScopeId`. It can also be
+   written by hand. A project without this member is
+   `disabled (not-configured)` and nothing is published.
+   `atelier obsidian view list` (or `scope list`) shows what was declared.
 2. Set the private machine settings. They live outside every repository and
    are never committed:
-   - `atelier obsidian audience set A,B` names the audiences this machine lets
-     into a view. No audience is admitted by default, so a view is empty until
-     one is set; `audience clear` empties it again.
+   - `atelier obsidian audience set me` lets "only you" into a view: every
+     audience of a note but `sensitive`, and the notes that carry no
+     classification, which only a vault that is yours alone shows.
+     `audience set A,B` names the audiences instead, and never shows notes
+     without a classification; `sensitive` is added by name
+     (`audience set me,sensitive`, which is such a list). No audience is
+     admitted by default, so a view is empty until one is set;
+     `audience clear` empties it again. See
+     [Notes without a classification](#notes-without-a-classification).
    - `atelier obsidian mode set manual` keeps every queued edit waiting for a
      person. `mode set automatic` is refused until an active automatic policy
      is installed.
@@ -302,11 +314,14 @@ Obsidian.
      unchanged; `policy revoke` returns the mode to `manual` and stops every
      later apply.
 3. Open a view:
-   `atelier obsidian open --scope ID --consent-actor ID --adapter=obsidian-cli`.
+   `atelier obsidian open --scope 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
+   `--adapter=obsidian-cli` is needed the first time; the workspace remembers
+   it, and later runs need no flag. The first open of a workspace records who
+   allowed the maintenance service to run: for a person at a terminal, the
+   account's name; for a program, `--consent-actor ID`, which it must pass.
+   Later opens reconnect and need neither. `atelier obsidian settings` shows
+   what was remembered and how to change it. `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
@@ -315,26 +330,227 @@ Obsidian.
    [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.
+`atelier obsidian service start [--consent-actor ID] [--adapter=obsidian-cli]`,
+`service status` and `service stop`; `service unit --print` prints the login
+item that `service unit --install` would write, and installs nothing (see
+[Start at login](#start-at-login)). The flags are needed only until the
+workspace remembers them, as for `open`.
+
+### Adding a view
+
+```sh
+atelier obsidian view add ID (--all | --folder PATH [--folder PATH ...] [--repo R] | --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]
+```
+
+- `--all` is a view of every note (`full`). `--folder` takes the notes under a
+  folder of a repository, written from the repository's root (`docs/notes`),
+  and can be given as often as needed; `--repo R` names the repository when
+  the project has more than one. `--tag T` takes the notes with a tag. Each of
+  these is a `scoped` view, and `--expand DEPTH:MAX` adds the notes they link
+  to, following links up to DEPTH steps and adding at most MAX notes.
+- The first view declared is the default; `--default` makes a later one the
+  default.
+- Before writing, the command counts the notes the view would show on this
+  machine, as the machine decided who may see (as "only you", with the notes
+  without a classification it shows, while nobody decided), and names how
+  many of the notes it selects are withheld: those without a classification
+  (a `kg` block) that the decision does not show, and those whose audience is
+  not admitted. A view that would show no note is refused with
+  `view-would-be-empty` and the counts; `--allow-empty` declares it anyway.
+  When the machine admits no audience at all (`audience clear`), the refusal
+  says so and names `atelier obsidian audience set me`.
+- While nobody decided who may see, the maintenance service publishes no
+  note, whatever the counts say: the next step `view add` names is then
+  `atelier obsidian audience set me`, before `atelier obsidian open` (`next`
+  under `--json`, in order).
+- A person at a terminal sees the change and the counts and is asked
+  `Write this change? [Y/n]`; `--yes` answers beforehand, and no answer within
+  10 minutes writes nothing (`unanswered`). For anyone else the command is the
+  consent: the change is made, and printed (`diff` under `--json`).
+- The file is rewritten only when it is in the form Atelier writes JSON in
+  (two-space indentation, LF or CRLF line ends, with or without a final one),
+  so the change is the new view and nothing else. A file in another form is
+  refused with `project-config-format-unknown`, and the member to add by hand
+  is in the refusal's `detail`. The file is replaced atomically, keeps its
+  mode, and only while it holds the bytes the change was made from
+  (`project-config-changed` otherwise). A link is not followed
+  (`project-file-not-regular`).
+- The workspace pointer is only ever written into an ignored `.atelier-local/`.
+  When that folder is not ignored, the same change adds `.atelier-local/` to
+  the project's `.gitignore`, and shows it.
+- A name that is taken is refused with `view-exists`. Removing a view is done
+  by hand for now.
+- The contract's `type` selector matches a note's file type (`markdown`,
+  `html`), not its `kg.type`, so `view add` does not offer it; a view by
+  `kg.type` needs a contract change.
+
+### Notes without a classification
+
+A note whose front matter carries no `kg` block (or that has no front matter)
+is unclassified: the knowledge graph gives it the `private` audience, and by
+default no view shows it. A vault that is only yours shows it: the audience
+decision `only-you` with `unclassified: shown`, which `audience set me`
+records. A list of audiences never shows one, even a list that names every
+audience "only you" stands for, so a vault for anyone else can never carry
+them.
+
+A note whose labels cannot be known is never shown, in any vault: front matter
+Atelier cannot read (a block scalar such as `description: |`, a value wrapped
+onto a second line), front matter that is not plain `key: value` lines at its
+top level (a quoted key such as `"kg":`, a one-line flow or JSON mapping, a
+complex key), or any top-level `kg` key that is not a block. Such a note may
+say `sensitive`, which "only you" leaves out. Only a note with no front
+matter, or with front matter of plain top-level keys at the start of the line,
+none of which is `kg`, counts as one without a classification. A plain key is
+written with ASCII letters, digits, `_` and `-`, starting with a letter or
+`_`: a note whose front matter uses a key with a space (`due date:`), other
+letters (`título:`), a dot or a leading digit, or a quoted key, stays withheld
+even when it holds nothing sensitive. Give it a `kg` block to show it.
+
+In an "only you" vault such a note is shown only when its bytes read as a note
+the way the emitter reads every note, so one file that cannot be published
+(front matter that opens and never closes, closes at once, or carries a
+trailing space on its first line; bytes that are not UTF-8) never stops the
+vault: it stays withheld, as does a file that cannot be read. A shown note is
+part of the view in every respect: links to it are links inside the view,
+generated text may name it, the selection operation resolves it, and an edit
+to it is applied to its source like any other.
+
+A decision recorded before this release, "only you" with those notes
+withheld, keeps them withheld until `audience set me` is run again. Changing
+the decision rebuilds every view at the next tick (the eligibility revision
+changes).
+
+### What this machine remembers
+
+A workspace's machine settings (`atelier-obsidian-machine-settings/v2`, owner
+only, under the private data root, never in a repository) hold what a person
+decided once, so no later run asks again or has to be told again. Each
+decision is null until it is made, and otherwise records what was decided,
+when, by whom when that is known (an actor identifier), and how: answered at
+a terminal (`question`), given on the command line (`command`), taken as the
+defaults (`defaults`), or carried over from an earlier release (`v1`).
+
+| Decision | Holds | Made today by |
+| --- | --- | --- |
+| `audience` | `only-you` or `custom`, and whether notes that carry no classification are `shown` or `withheld`. Only `only-you` may show them; a list of audiences always withholds them. The admitted list stays in `audienceAllow`, the engine's audience input | `audience set me` (only you, shown) or `audience set A,B` / `audience clear` (withheld) |
+| `location` | the absolute folder that holds this workspace's vaults | `location set DIR` |
+| `loginItem` | `on` or `off` | `service unit --install` (on); `service unit --remove` and `uninstall` (off) |
+| `adapter` | `obsidian-cli` | `--adapter=obsidian-cli` given to `open`, `service start` or `service unit --install` |
+
+Who allowed the maintenance service is not a second copy here: it stays the
+consent the service reads from its own settings. `atelier obsidian settings`
+shows all of it, and how each answer is changed.
+
+Releases up to 0.2.0-alpha.12 wrote `atelier-obsidian-machine-settings/v1`.
+Such a file is read as the v2 document it stands for, an audience list set
+with it becoming that person's decision, and stays v1 on disk until the next
+write, which writes v2. A release that knows only v1 refuses a v2 file as
+`invalid-machine-settings`: after an upgrade, a maintenance service that
+still runs the earlier release fails its ticks until it is replaced, which
+`atelier obsidian open` and `atelier obsidian service start` do.
+
+### Start at login
+
+Without a login item the vault is complete after a restart, but nothing keeps
+it fresh until the next `open`. A login item starts the maintenance service
+when you log in:
+
+```sh
+atelier obsidian service unit --install [--consent-actor ID] [--adapter=obsidian-cli]
+atelier obsidian service unit --print    # what --install writes; writes nothing
+atelier obsidian service unit --remove
+atelier obsidian uninstall
+```
+
+- On macOS it is a launchd agent,
+  `~/Library/LaunchAgents/ai.mnstry.atelier.<project>.<workspace-id>.plist`.
+  macOS says "Background Items Added" and lists it as "node" under System
+  Settings → General → Login Items & Extensions, because there is no app to
+  name it after. Switched off there, it stays off: `status` reports
+  `installed, switched off in System Settings`, and `open` starts the service
+  for that session only.
+- On Linux it is a systemd user unit,
+  `~/.config/systemd/user/atelier-obsidian-<workspace-id>.service`
+  (`$XDG_CONFIG_HOME` when set), enabled with `systemctl --user`. Disabled
+  with `systemctl --user disable`, it stays disabled: `status` reports
+  `installed, disabled`, and `open` starts the service for that session
+  only. Where no user instance of systemd answers (WSL, a container), the
+  answer is `login-item-unavailable` and nothing is left behind.
+- Windows is not offered (`startup-platform-unqualified`), as publication
+  itself is refused there.
+
+It runs the package installed in the project
+(`<project>/node_modules/@mnstry/atelier/…`, named by that path, so the next
+start runs whatever release the project has installed then), with the Node
+that installed it and the search path you had, in the root folder. It names
+the data folder and the workspace it was installed for, so it finds them at
+login whatever variables your shell set. Run from
+`npx` in a project that has no package installed, it refuses with
+`login-item-needs-installed-package`: install `@mnstry/atelier` in the project
+first. Installing records that you allowed the service to run at login (the
+consent then covers startup): `--consent-actor ID` names who allows it; for a
+person at a terminal, the actor already recorded for this workspace, or else
+the account's name. A program that passes no `--consent-actor` for a
+workspace whose consent covers the service alone is refused
+(`startup-consent-required`). The answer is remembered as the `loginItem`
+decision. `--remove` takes the consent back to the service alone, removes the
+item, and starts the service again for this session only, as a process of its
+own (with the adapter given or remembered; otherwise the next `open` starts
+it). Each workspace has its own login item, port, log and consent, and
+projects may pin different releases; `launchctl list | grep ai.mnstry.atelier`
+lists every one on a Mac.
+
+Once a login item is installed, the service is started through it: `service
+start`, `open` and the replacement of an outdated service ask launchd or
+systemd to start it, never start a second one beside it, and accept only the
+service that proves itself with the installed entry. When the unit differs from
+what would be written now (the Node it names was removed, say), the next start
+writes it again and says `login item refreshed`. A refusal of the service at
+login (another service already runs, or the consent does not cover startup)
+ends the process cleanly, so it is not retried every minute, and `status` says
+`the login item did not start the service: <code>` with the next step. A crash
+is restarted after a minute.
+
+`uninstall` removes the login item and stops the service. It keeps the vaults,
+the private state, the project file and Obsidian's vault list as they are, and
+prints where each is: every vault under the data root and every folder
+allocated to a view where the workspace decided its vaults live, a view no
+longer declared included. It does not start the service again.
 
 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 earlier release. One the login item started notices it: after each tick
+it compares the package on disk (read through the path the item names, so a
+re-pointed link or a `file:` install counts) with the release it started
+with, and when they differ it exits after that tick with code 75, and its
+service manager starts the new release within a minute. Otherwise `open` and
+`service start` replace 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, they stop it as `service stop` would and start the installed release under
+the consent already recorded (through the login item when there is one), and
+say `service: restarted (outdated)`. The installed release is read from the
+package of the entry that would be started, so with a login item it is the
+project's own package. 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`, and `service
+start` answers that it runs, with `release: later`; run `atelier obsidian
+service stop`, then open again, or open with the later release. A service that
+does not answer health in time, in a stretch of a tick that does not yield, is
+not stopped (`open` answers `busy`), and a listener that does not prove itself
+this workspace's service is never touched. While a view is being prepared and
+published the service does answer: `open` asks it for a tick that starts after
+the one in flight and waits for that tick, two minutes at most unless
+`atelier obsidian open --wait-ms MS` sets another bound, before it reports the
+view as it is (one that read `current` is reported `updating`, with the reason
+`tick-still-running`, while that tick has not ended); and `service stop` is
+accepted and ends the
+service after the tick in flight or after its shutdown grace, whichever comes
+first. A publication cut short that way is settled by the publisher's restart
+recovery at the next one.
 
 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
@@ -377,13 +593,79 @@ proposals list` and `proposals show OPERATION` read them, and nothing applies
 one. A body edit to a note whose source uses CRLF line endings is also a
 proposal, never an apply, because the app normalizes line endings on save.
 
-The vault itself lives under the private data root, outside every repository:
-`~/Library/Application Support/Atelier` on macOS, `$XDG_DATA_HOME/atelier`
-(else `~/.local/share/atelier`) on Linux and `%LOCALAPPDATA%\Atelier` on
-Windows, under `obsidian/<workspace-id>/`. `--data-root DIR` names another
-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).
+Atelier's private state lives under the private data root, outside every
+repository: `~/Library/Application Support/Atelier` on macOS,
+`$XDG_DATA_HOME/atelier` (else `~/.local/share/atelier`) on Linux and
+`%LOCALAPPDATA%\Atelier` on Windows, under `obsidian/<workspace-id>/`.
+`--data-root DIR` names another 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).
+
+Where the vaults are is decided per workspace. Until a person decides it, a
+view's vault is under the data root too, in `vaults/<view>`, as in every
+earlier release. `atelier obsidian location set DIR` decides a visible folder
+instead (`~/Atelier`, say). Each view that has not been published yet is then
+given its own folder there at its first publication, named
+`<project> (<view>)`: `~/Atelier/harbor-notes (everything)`. That name is also
+the vault's name in Obsidian's vault switcher, so it is readable and unique
+across projects and views. The first name that is free is taken, with a number
+inside the parentheses when needed (`harbor-notes (everything 2)`): free means
+nothing on the disk has it, and no vault Obsidian lists has it in any letter
+case. The folder is created private to this user (mode 0700), and so is `DIR`
+when Atelier creates it; a missing folder on the way to `DIR` is made as any
+other folder is. The allocation is recorded in the workspace's private
+state (`state/allocations/<view>.json`) and is never recomputed: renaming the
+project or deciding another folder later moves no vault, and a vault published
+before under the data root stays there. `location show` says where each
+view's vault is, or will be, or why its record cannot be read.
+
+Atelier publishes only into the folder it made. The allocation records the
+folder's real path, device and inode, and the maintenance service checks them
+at every tick, as the publisher does before it writes anything and again
+before each note and before its commit (see Known limits). Another folder
+put where the one made was (moved in, or a link) is not published into
+(`vault-allocation-replaced`), nor is the same folder reached through a link
+put on the way since, into a vault the app lists, say
+(`vault-allocation-moved`). A folder that has gone is made again at the next
+tick, only where its recorded real path leads and only where a location would
+be accepted (not inside a repository, the private state, a vault Atelier
+publishes or one the app lists, and on the data root's volume). A vault
+removed, moved or replaced while it is being published stops that publication
+(`vault-allocation-missing`, `vault-allocation-replaced`, or
+`vault-root-moved` for a vault under the data root). Once the folder is put
+back, or made again, the running service publishes into it again at its next
+tick; no restart is needed. One case waits for the next change at the view's
+sources: a folder made again after a publication that stopped just before its
+commit. That generation is finished by restart recovery, its notes went with
+the folder that went away, and the view reads `vault-note-missing` until then. A
+view that was published and whose vault Atelier cannot find is refused
+(`vault-allocation-lost`) rather than published again into a new, empty vault
+under the data root: its record was lost, or, for a view that never had a
+record (published under the data root), its `vaults/<view>` folder was
+removed. Restore the record from a backup if its vault was allocated
+elsewhere; otherwise make the folder `vaults/<view>` under the data root, and
+the view is published there at the next change at its sources. `status` and
+`open` name that next step for this code, and for `vault-allocation-moved`,
+`vault-allocation-replaced` and `vault-allocation-missing`.
+
+`DIR` is refused inside an enrolled repository or the project, inside a vault
+Atelier publishes, inside a folder Obsidian lists as a vault, and on another
+volume than the data root (a note is published by an atomic exchange, which
+cannot cross volumes). A folder a sync client keeps in step (iCloud Drive, a
+cloud storage provider, Dropbox, OneDrive, Google Drive, or a Desktop or
+Documents folder iCloud syncs) is refused unless `--allow-synced-location` is
+given: another machine's Obsidian could hold a vault there unseen. A folder
+macOS protects (Desktop, Documents, Downloads) is accepted with a warning,
+because macOS asks before Obsidian or the maintenance service may read it.
+`~/` is read against the account's home folder, which a shell does not do
+after `--x=`. Each check compares the folder as written and as its real path,
+in any letter case, so a link into a listed or synced vault is refused as
+that vault is. Obsidian's vault list is read through the app when it runs and
+answers, and otherwise from its settings file, never written. When the list
+cannot be read, `location set` says so and accepts the folder, and the
+maintenance service allocates no vault there until it can read the list
+(the view is `stale`, `app-vault-list-unreadable`, and is tried again at
+the next tick).
 
 ### What `open` does in each state of Obsidian
 
@@ -415,28 +697,97 @@ exactly because the folder is listed.
   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
+  operating system. A vault Obsidian already lists but had closed is not
+  reopened by a plain start, so if Obsidian refuses that link just after it
+  started, `open` hands it the link once more, again through that tool and
+  never through the operating system, before it gives up. 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.
+  In the same write, `open` turns Obsidian's command line on (`cli: true`)
+  when it is off: publishing into a vault Obsidian holds needs it until
+  Atelier's plugin takes over that part, and it is off in a new installation.
+  The answer says what was written and where the backup of the file as it
+  was is kept.
+- **Obsidian is installed and never started** (no `obsidian.json` yet). When
+  the process table says, positively, that no Obsidian runs, `open` creates
+  the file, with this vault flagged open and the command line on, and starts
+  Obsidian plainly; Obsidian opens the vault. Nothing else is in the file,
+  and the settings folder is created private to you when it does not exist
+  yet. The file is created exclusively: if Obsidian writes its own first,
+  that one is kept and `open` says so. While an Obsidian may run, nothing is
+  created (`app-may-be-running`).
 - **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
+  above. For a vault it does not list yet, see "Restart, only when you ask"
+  below; without that, `open` answers `app-version-unsupported` with reason
+  `no-vault-open` and names `--restart-obsidian`.
+- **Obsidian runs with its command line 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.
+  is not enabled", only a link reaches it, and its settings belong to the
+  running app, which keeps the switch in memory and would write it back. See
+  "Restart, only when you ask" below; without that, `open` adds and launches
+  nothing, and answers `app-cli-unavailable` with reason `cli-turned-off`,
+  naming `--restart-obsidian` and where to turn the switch on yourself:
+  Settings > General > Advanced > Command line interface.
+
+**Restart, only when you ask.** In the two states where Obsidian runs but
+`open` cannot reach it (its command line off, or no vault open and the view's
+vault not in its list), `atelier obsidian open --restart-obsidian` lets `open`
+restart Obsidian once:
+
+1. Before anything is sent, it checks, reading only, that the write the
+   restart is for can succeed: the view's vault folder exists, Obsidian's
+   settings file can be read and is yours, is no link and has no second
+   name, is not a Flatpak or snap build's, is not too large to take the
+   vault, and lists no vault at a folder above the view's. An Obsidian that
+   has shown only its starter window has written no settings file yet; then
+   the folder it goes in must be yours (or be missing inside a folder of
+   yours), and the file is created after the quit, as for an Obsidian that
+   never started. Otherwise `open` answers that refusal and leaves Obsidian
+   running. Right before the first signal, once the process below is proven,
+   it keeps a copy of the settings file beside it
+   (`obsidian.json.atelier-backup-<time>`), which this run's write does not
+   prune, and the answer names it; a copy that cannot be kept sends nothing.
+2. It sends SIGTERM to Obsidian's main process, and to nothing else. That
+   process is found in the process table and must be the only Obsidian main
+   process there, one of yours, named by the app bundle's path, with every
+   other Obsidian process its child; it is read again just before the signal
+   and must be the same process, yours, under the same parent. Anything else
+   (two Obsidians, another user's, a helper of another process, a table that
+   cannot be read) is answered `app-main-process-unproven`, with the reason in
+   `restart.detail`, and nothing is sent.
+3. Obsidian handles that SIGTERM as a quit: it closes every window, keeping
+   the vaults it had open flagged to reopen, and its helper processes end. On
+   macOS its main process can then stay, with no window. Electron handles
+   only the first SIGTERM as a quit: a second one ends the process at once,
+   without its quit handlers. `open` sends that second SIGTERM only when the
+   same process has shown no window and no helper at every reading for at
+   least 5 seconds (a margin, not a proof that it has nothing left to save). There
+   is never a third signal, and never a stronger one: an Obsidian that is not
+   gone within 30 seconds is answered `launch-failed` with reason
+   `app-did-not-quit`, and nothing is written. The answer says how many
+   signals were delivered.
+4. It adds the vault to Obsidian's settings and turns the command line on, in
+   the one write described above.
+5. It starts Obsidian plainly, and the vaults it had open come back, with this
+   one beside them. If the vault could not be added after all, Obsidian is
+   still started again, as it was.
+
+The answer says that Obsidian was restarted, which process was signalled,
+how, and what was written. The flag is never implied by any other flag or
+answer; every other operation refuses it. The restart is qualified on macOS
+only (on Linux a quit Obsidian is started with a link, which would drop the
+other vaults' reopen flags): elsewhere `open` answers
+`restart-platform-unqualified`.
+
+Two limits. `open` asks nothing at a terminal yet: the restart needs the flag
+there too, until the first-run command asks "Obsidian must restart once to add
+this vault … Restart now?" in that state. And if `open` itself is interrupted
+(Ctrl-C, or its process ended) after Obsidian quit and before it was started
+again, Obsidian stays quit: start it yourself, and it reopens its vaults; run
+`open` again to add the view's vault.
 
 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
@@ -464,6 +815,19 @@ 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.
 
+A view's first publication into the folder allocated for it is the one
+exception to the rule below. While no list the app keeps names that folder, a
+folder above it or one inside it, the vault is filled even while Obsidian
+runs, by creating files only. When that run completes, `open` adds the vault
+to Obsidian and opens it after the commit. A run that stops partway commits
+nothing and falls back to the coordinated path. That happens when the list
+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
+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
 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
@@ -500,6 +864,419 @@ 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.
 
+## Personal workspaces
+
+A personal workspace (see [personal-workspace.md](personal-workspace.md)) is
+projected through one route, `bindPersonalWorkspace({ personalHome,
+generationId })` in `src/projection/obsidian/personal-workspace.mjs`. Both
+arguments are explicit; neither is discovered from the environment or the
+working directory. A loader uses `loadBoundProject` with the same arguments,
+or `loadBoundProjectOffThread`, which composes in a worker thread; the engine
+awaits its loader. The command, the service and the login item bind a personal
+home through `--personal-home`, which follows the generation the person
+confirmed there (see "A confirmed selection", below).
+
+- **One graph.** The binding is attached to the generation's resolved
+  `atelier.project.json` under one symbol key. When a project carries it, the
+  pipeline's `buildGraph` builds the canonical graph with the caller's file
+  cache and composition's own rule that no private note is a link target, then
+  applies eligibility as for any project. The engine, view counts, source apply,
+  the proposal adapter and the selection operation all build through it, so they
+  read one graph. A plain build of the generation's configuration would differ:
+  there, a shared note's link can name a private note.
+- **Only a confirmed graph is used.** A graph is returned only under a validity
+  key that `composePersonalWorkspace` confirmed. The key names:
+  - the authored manifest and overlay, as regular files of at most 1 MiB;
+  - every file of the generation, as regular files of at most 8 MiB (the
+    personal-workspace module's own limits);
+  - the private home's own state, any `.git` above it, and a `.git` in its
+    `generations` folder;
+  - each enrolled root's link status and its Git configuration (its remote and
+    its helpers), through a `gitdir:` file and its common directory where `.git`
+    is a file;
+  - the user's Git configuration (`~/.gitconfig` and the XDG one), through a
+    link, and any ambient Git variable;
+  - a digest of the graph's facts: nodes, edges, embeds, assets, resolved links
+    and every finding.
+
+  The inputs are read before the composition runs. A key is confirmed only when
+  the composition then accepted the inputs and composed a graph with exactly
+  those facts, so every graph used is one the composition built too. A single
+  change that lands while it runs is either seen by it or leaves the key behind;
+  a change and its exact undo during one composition is caught at the next full
+  reconciliation. Binding confirms the first key. An authored or generation
+  file the key reads is opened without following a link and without waiting on
+  it. A FIFO, a device or a link refuses at once, with the composition's code
+  (`generation-corrupt`, `malformed-input`). A Git configuration file is read
+  through a link, as Git reads it, but never waited on.
+
+  When a build finds its key unconfirmed, a caller that builds once composes in
+  its own thread. The engine, and the proposal adapter it runs, compose in a
+  worker, off the event loop, then build again. The adapter builds only when it
+  looks at a newly observed edit, as for any project. On a tick whose graph is
+  pending (`personal-validation-pending`), it records nothing for the edits it
+  reached and reports `observed.deferred`. It offers those edits, and every
+  earlier refusal, again next tick, and leaves a due proposal operation as it
+  is, without spending one of its attempts. While shared sources change before
+  every tick, every tick is pending: the edit is deferred again, with one full
+  build per tick, until a tick with no change. A worker that does not answer
+  within two minutes is let go of and refuses `personal-composition-unavailable`,
+  so the tick does not wait. A worker blocked in a system call (a FIFO opened for
+  reading) cannot be stopped until that call returns. Until then it keeps the
+  process from exiting, and each such expiry leaves one thread behind: a service
+  stopped in that state needs a kill. A graph that still differs refuses
+  `personal-graph-unconfirmed`.
+- **A copy is refused.** The settings member names the bound generation. A copy
+  of a bound project that lost the binding (a structured clone, a JSON round
+  trip) refuses `personal-binding-lost`, and is never built as an ordinary
+  project.
+- **Validity.** Composition decides whether the generation may be used, at bind
+  time and at every build. Its refusals keep their codes (`stale-generation`,
+  `generation-missing`, `generation-corrupt`, `generation-relocated`,
+  `retained-removed-reference`, `not-private-location`, `root-symlinked`,
+  `ambient-git-environment`, `future-schema`, `ambiguous-binding` and the rest).
+  `bindPersonalWorkspace` throws them as `PersonalWorkspaceRefusal`.
+  `loadBoundProject` and every build refuse with the same code as a maintenance
+  refusal, so the engine and every command report it typed, and no view stays
+  current. Nothing is published, and no vault, manifest, journal or private home
+  byte is written. A refusal the projection adds (`personal-view-id-reserved`,
+  `personal-views-exceed-settings-limit`) is a maintenance refusal from the
+  start.
+- **Staleness is noticed at the next tick.** The engine observes the person's
+  `atelier.personal.json` and `atelier.overlay.json` and the bound generation's
+  `generation.json` as configuration. A change to any of them prepares every
+  view again on the next tick, unasked, and a generation that no longer holds
+  is refused there. Every full reconciliation composes a bound workspace again,
+  in a worker, whatever else it prepares. A cause the key does not name is
+  therefore refused within the reconciliation interval (five minutes by
+  default). Those causes are:
+  - the system Git configuration, and files a Git configuration includes
+    (`include.path`, `config.worktree`);
+  - an enrolled repository's work tree or top level changing;
+  - a change of the authored inputs and its exact undo during one composition;
+  - a shared note replaced by a link;
+  - an untracked note becoming ignored.
+
+  The views are prepared again only when that composition refuses or confirms a
+  different key: an unchanged workspace is not rebuilt, republished or locked.
+  After a refusal the engine
+  loads the project again at the next tick, so a loader that binds the next
+  generation is followed. The generation's record and the settings member both
+  name the generation, so a rebound generation invalidates every view even when
+  its configuration file is byte-identical.
+- **Views.** The overlay's saved views become scopes in memory: each is a
+  scoped view of the repositories it names, and `everything` is a full view of
+  the composed graph. A saved view named `everything` is refused. More than 255
+  saved views, or a view of more than 256 repositories, is refused at bind
+  (`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.
+- **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
+  what is not enforced, and is never permission.
+- **Workspace identity.** The bound project's folder is the private home, so
+  the workspace pointer is `<personal home>/.atelier-local/obsidian.json`. A
+  generation is a closed, verified inventory, and an extra file there would
+  invalidate it. This is provisional until the per-person projection
+  configuration exists.
+- **Edits.** A vault edit to a private note is never applied. Source apply
+  refuses it with `personal-overlay-proposals-only`. The proposal adapter does
+  not observe, record or propose it either: it answers
+  `personal-overlay-not-proposed`. Nothing is written into a generation, and
+  the view stays
+  `held-for-your-edit` until the edit is undone. Turning such an edit into a
+  change of the person's overlay is not built.
+- **Reserved settings key.** The settings member
+  `ext["mnstry.atelier.personal-workspace"]` is reserved: the binding writes it
+  in memory. A project configuration that declares it itself is refused at
+  every build (`personal-binding-lost`, naming the key).
+
+### A confirmed selection
+
+`--personal-home DIR`, given instead of `--project` to `atelier obsidian`, to
+the service entry and in a login item's unit, binds the personal home DIR
+(`src/runtime/obsidian/personal-selection.mjs`). Without it, every argument,
+unit and loader is what it was.
+
+- **What is loaded.** The generation the person last confirmed with
+  `selectPersonalGeneration` (see [personal-workspace.md](personal-workspace.md)),
+  and nothing else. The loader reads the head of the selection history from
+  the history alone (`readPersonalSelectionHead`), loads the generation it
+  names through the route above (in a worker for the service, in the
+  command's thread for a command), then reads the head again. A head that
+  moved meanwhile refuses `personal-selection-changed`. Nothing here confirms
+  a selection or chooses one for the person.
+- **Nothing confirmed publishes nothing.** No record refuses
+  `nothing-selected`; a confirmed generation whose inputs were edited and not
+  confirmed again refuses `stale-generation`; a history whose hash chain does
+  not hold refuses `selection-history-corrupt`; a history that ends at an
+  earlier record than the running service has read refuses
+  `selection-history-shortened`; a home whose history cannot be read refuses
+  `personal-home-unavailable`, and a home that is gone or not
+  private refuses with the module's own code (`root-missing`,
+  `not-private-location`, `root-symlinked`). Every other refusal of the
+  composition keeps its code. Nothing falls back to another generation or to
+  the project without a binding. The vault keeps what it last published from
+  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.
+  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
+  `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`).
+- **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
+  history cut short is seen at the next tick too, and a running service does
+  not follow it back. Selections are only ever appended, so a history that
+  ends at an earlier record than the service has read it ending at was cut by
+  something other than a confirmation, and following it back could publish
+  what nobody confirmed after the records removed: cut after a restore nobody
+  confirmed, it would publish that restore. The service notes the highest
+  record number at every read of the history's end (a load's first read, its
+  read once the generation is loaded, the recheck at a full reconciliation,
+  and a read made when a tick stops a view as `mixed-read` because the tick's
+  settings changed or could not be read, once for views stopped one after
+  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
+  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
+  later record than the one the project was loaded under, so a confirmation
+  read elsewhere in the service and removed before the engine looked refuses at
+  that tick; otherwise a project already loaded is held to this at its next
+  recheck, at the latest the next full reconciliation, and until then it
+  publishes nothing new under another record, and a change at its sources
+  brings the recheck forward. A record added and removed between two of those
+  reads was never read, and does not count: while a load of its own is under
+  way, the plugin's status read compares the files that decide its views and
+  reads no history, so a record it sees then only as a changed file is not
+  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 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,
+  refuses with its code within the reconciliation interval. A confirmation
+  during a tick changes an observed file: the view being prepared or published
+  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
+  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
+  repository withdrawn, a view narrowed), each view follows the publisher's
+  rule for notes that leave a view; this binding adds no rule. At the view's
+  next publication a generated note of the dropped source leaves the vault and
+  its bytes are moved to private recovery. A note the person edited, once the
+  engine has queued the edit, holds the whole view at the generation it last
+  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.
+- **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
+  being waited on. A home that becomes unreadable while the engine holds a
+  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.
+
+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
+the service loads them, so the proposal adapter was registered. The host's load
+average was near 35, slower than an idle one, so read the times as upper
+bounds. "Main-thread compositions" counts the Git probe a composition makes on
+the event loop's thread.
+
+| Step | Wall time | Longest event-loop block | Main-thread compositions |
+| --- | --- | --- | --- |
+| Load, composed in a worker (`loadBoundProjectOffThread`) | 3.8 s | 0.03 s | none |
+| Load in the calling thread (`loadBoundProject`) | 3.5 s | 3.5 s | one |
+| One build without a file cache (a caller that builds once) | 1.4 s | 1.3 s | none |
+| First tick: load, build, and first publication of six vaults | 582 s | 574 s | none |
+| Tick with every view prepared again | 4.5 s | 4.5 s | none |
+| Idle tick | 0.25 s | 0.23 s | none |
+| Tick with a vault edit and a graph change: the adapter defers, the engine confirms in a worker | 12.4 s | 2.8 s | none |
+| Next tick: the adapter observes that edit (one build) | 2.1 s | 2.0 s | none |
+| Full-reconciliation tick, the edit still open | 5.0 s | 1.0 s | none |
+
+**What is met.** No composition runs on the engine's event loop, the proposal
+adapter's included. The load, a confirmation after a change, and the
+composition at every full reconciliation run in a worker; the tick does not
+wait on one that misses its deadline. An unchanged workspace is not prepared
+again. While an edit stays open and shared sources are quiet, the adapter
+builds nothing more; under continuous change it builds once per tick until a
+quiet tick.
+
+**What a service binding needed.** The first publication blocked the event
+loop far longer than the service's five-second health probe: about ten minutes
+here. That is the
+publication path every project takes, not this route: an ordinary project of
+450 notes, measured the same way, blocked as long as a bound one. Preparing six
+views again blocked 4.5 s, under the probe. The proposal adapter's build of a
+newly observed edit, without the engine's file cache, blocked 2.0 s, at a
+two-second target, as for an ordinary project. A service binding needed the
+first publication to yield to the event loop, which it now does (see "Since
+that measurement"), and a start that does not wait for its loader. The service
+resolves its workspace from the project its loader answers when it starts, and refuses a loader that answers a promise or any
+other thenable, such as `loadBoundProjectOffThread`, with
+`service-loader-not-synchronous`, before it reads anything from it, listens or
+records anything; a promise it was handed is let go, and its refusal, if it
+is refused, does not go unhandled. Started by a login item (`--startup`), the
+service asks its loader (or, under `--personal-home`, its locator) once for both
+the lookup of its workspace and its own start. One that answers a promise there
+is never handed to the workspace resolution: a promise whose `constructor`
+reads as this realm's `Promise` is let go without calling a `then` of its
+own, any other thenable (as a rule another realm's promise or a subclass's)
+is adopted once (its `then` is called once in all), the refusal is recorded
+in the workspace the unit names, when that exists, and the process ends with
+0, so the service manager does not start it again at once. One that throws
+there, whatever it throws (`undefined` too, a value with no prototype, or one
+whose `code` cannot be read), or answers a project whose `then` cannot be
+read, ends the start as a failure of the loader does anywhere else: it is
+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)).
+
+**Since that measurement.** The engine prepares each view cooperatively and
+the publisher yields between complete units, so the service answers health and
+status while notes are emitted, staged and published. The first-tick figures
+in the table are from before that change and have not been taken again on that
+corpus. Building the canonical graph gives the event loop a turn between the
+Markdown sources it reads, hashes and parses (the census): a first tick reads
+every source, and on a heavily loaded host the build of one view of 10,000
+invented notes held the listener for 8 s in one stretch. The other sources
+(HTML files and the sidecars of PDF and Word documents) are read without a turn
+between them, and a project bound to a personal workspace is built by its own
+route in one stretch. Walking the directories, resolving the links and
+assembling the graph still run through.
+So do capturing the source snapshot, the publisher's restart recovery,
+validating a prepared view and planning its units, the exchange probe, writing
+and syncing the journal before the candidates move, and the look again at
+displaced files after the units (`recheckDisplacedFiles`).
+The read-back after a commit waits between
+notes: on a loaded host it took 16.8 s for one view of 10,000 invented notes
+and held the listener for all of it, and now a request is answered between two
+notes. Nothing is checked at those waits, since the generation is committed. A
+note edited in the vault while the read-back is under way is read as edited
+when the walk has not reached it, and is seen by the next tick when it has, as
+an edit made just after a read-back is. A stop whose grace runs out while a
+read-back waits ends the process after the commit and before the view is
+recorded as current, as a crash there does: the next start's first tick reads
+the committed generation back. Before a view is prepared, a tick looks at
+every view's notes and then at the sources, and both walks wait between files.
+They matter after a publication, when the watcher has named the notes it
+wrote, and at every full reconciliation, when every note and every source is
+hashed: on one view of 10,000 invented notes on a loaded host such a tick held
+the listener for 5.5 s when the walks ran through. Nothing is checked at their
+waits and nothing is written. Within Atelier only the engine commits a
+manifest or writes the pending edits, under the lock the tick holds, so the
+pending edits are read, compared and written in one stretch after the walk
+over the vault, and the bytes an edit keeps are read there. A file changed
+after its turn in a walk is seen by the next tick, by its stat hint or the
+watcher (one that keeps its size and times and draws no event, at the latest
+by the next full reconciliation), as one changed just after a walk that ran
+through is; when the tick builds the graph, the look again at the sources
+after the build refuses such a change as `mixed-read`. A source this tick
+observed, removed before the build read it (or its folder), is refused the
+same way. So is a selected source removed before a view's preparation, or the
+look again before its commit, read it: that view is refused, and the tick goes
+on to its other views. Either way the next tick reads everything again; a path
+that can never be read still fails the tick. A note gone from a
+vault, a source that changed, or a configuration file that changed is a change
+once: a tick that sees it and then fails without a typed reason (a file it
+cannot read, a disk that is full, a project loader that fails) has recorded it
+without acting on it. The next tick therefore starts as the first tick of a
+process does: it loads the project again and looks at every view, so a view
+whose note is missing reads `vault-note-missing` instead of staying `current`,
+and a changed source or view is published.
+The comparison of kept notes with their candidates reads asynchronously,
+sixteen at a time, and does not hold the listener. Observing pending edits
+and routing proposals wait between two edits and between two operations, so
+a burst of edits does not hold the listener for its whole length. One edit,
+or one operation, is still one stretch. The first edit an observation looks
+at that the object store does not hold yet builds the canonical graph in its
+stretch, and the first operation routed builds it again while the lock of
+its repository is held. An edit whose published note
+is not retained has its whole view prepared again in its stretch: once for a
+view and generation in an observation when the preparation succeeds, and for
+every such edit when it fails. A stop whose grace runs out while proposals
+are routed can end the process between two operations of a repository with
+that repository's proposal lock still held, as a crash can. A service in one
+of those stretches does not answer until it ends, and is `busy` if that
+outlasts the probe. A request can
+hold the listener too: the plugin's status read loads the project on the event
+loop at its first requests after the service starts (until two loads agree),
+when a configuration file changed, every two and a half minutes, again two to
+thirty seconds after a load that failed, and at every request while one of
+those files vouches for nothing or while its loads never agree. For a project
+named by `--project` none of those loads is taken off the loop. For a bound
+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)).
+
+What the waits cost. The waits of observation and routing are taken at
+every boundary between two edits or two operations and before each
+repository, whatever time was spent; while routing describes its operations
+a wait comes after about 8 ms of work or 32 units. Nothing is checked around
+any of them. In preparation and publication a wait
+comes after about 8 ms of work or 32 units,
+whichever is first, and around each one the engine checks that the tick's
+settings still hold: it reads and hashes every configuration file it observes
+(the project configuration, the repository access file, local overlays and,
+for a bound personal workspace, its inputs), reads and validates the machine
+settings, and asks the eligibility revision. Measured on six configuration
+files, that check took about 0.2 ms, twice per wait; a first publication of
+200 invented notes waited 463 times, so roughly 0.2 s of a 64 s tick, on a
+host with a load average above 200 (indicative only). The selected sources
+cost one stat call each after the preparation and one before the commit; a
+note reused from the preparation cache is still not read.
+
 ## Known limits
 
 These are the limits known at this release. None is hidden behind a skipped
@@ -554,6 +1331,35 @@ test reported as a pass.
   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.
+- Vault location: consent to a folder a sync client keeps in step
+  (`--allow-synced-location`) is given when `location set` decides the folder,
+  and is not recorded, so the maintenance service does not check for sync
+  clients again. The decision keeps the folder as it was written, so at a
+  view's first allocation a folder on the way that has since become a link
+  into a synced folder is followed, and its vault is allocated there without
+  being asked; a folder that becomes synced without any link (iCloud's
+  "Desktop & Documents Folders" turned on, say) is not refused either, at the
+  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`).
+- 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
+  committed. A program of the same account that puts a link in its place
+  between one check and what follows it can still have that go through the
+  link: one note's writes (the folders on its way and the note), or the vault
+  lock's folder (made there, or made private if it was there already) and, in
+  a folder that already holds one (another Atelier vault), a lock ticket and
+  its release flag. For a note replaced or removed while the app holds the
+  vault, the app is asked about that note between the check and the write, so
+  that window lasts a round trip to the app. The next check refuses the
+  publication, and it is never reported current.
+- Vault identity: an allocated folder is known by its real path, device and
+  inode. On Linux a folder made at the same path after the allocated one was
+  removed can be given the same inode number (ext4 reuses a freed one), and is
+  then taken for the one made; macOS (APFS) did not reuse one in 200 tries.
+  Such a folder is published into only at the recorded real path, and the
+  plugin's bearer only when this account owns it.
 - 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
@@ -646,6 +1452,17 @@ test reported as a pass.
   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).
+- 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
+  switched off in System Settings, and the exit statuses read from
+  `launchctl` and `systemctl`, are the documented ones and are not yet
+  confirmed on a host. A unit whose program cannot be loaded at all (the
+  project's package was removed) is restarted by its manager once a minute,
+  and each attempt adds a few lines to `state/service/login-item.log`, which
+  nothing bounds: `service unit --remove` or `uninstall` ends it. An upgrade
+  in the moment between a service's start and the first reading of its release
+  is not noticed until the next change.
 - Acceptance: a schema-valid receipt closes no gate, the package proof closes
   no gate, and no adopter acceptance is recorded in this repository.
 
@@ -665,3 +1482,8 @@ The test suite proves each oracle can fail:
 - `createMaintenanceEngineForOracleTests` with an
   `ENGINE_PRIMITIVES.isRetryDue` that never holds: a refused view waits for
   the full reconciliation, and the retry oracle fails.
+- `createMaintenanceEngineForOracleTests` with
+  `ENGINE_PRIMITIVES.rechecksEveryViewAfterFailure` false: a note removed, a
+  source changed or a view added in a tick that then fails without a typed
+  reason is lost, the view stays `current` with the note gone or the old
+  content, the new view is never published, and the oracle fails.