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

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,25 +330,216 @@ 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
+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 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
@@ -377,13 +583,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 +687,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 +805,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 +854,174 @@ 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. No command or service binds one yet: that waits for the selection seam that
+keeps one projection configuration per person.
+
+- **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).
+
+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 remains before a service or `open` binds a personal workspace of this
+size.** The first publication blocks 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 needs the
+first publication to yield to the event loop (or run off it), or a corpus small
+enough to stay within the probe.
+
 ## Known limits
 
 These are the limits known at this release. None is hidden behind a skipped
@@ -554,6 +1076,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 +1197,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.