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

package/docs/learning.md

@@ -0,0 +1,215 @@
+# Learning from corrections and outcomes
+
+The learning module records feedback in context, preserves proposals and human
+decisions, and supplies explicitly activated lessons to a named harness. It is
+an experimental local source capability. It requires consumer integration and
+does not establish availability in a published package or installed desktop.
+
+A person defines the task and scope, an agent can propose a lesson, and the
+person reviews its wording and consequences. Evidence can be represented before
+acceptance. Only accepted, activated content is eligible for task context.
+
+## Records and authority
+
+Four kinds of records describe the main path:
+
+1. An **observation** preserves feedback or a tool outcome, its interpretation,
+   provenance reference, project and activity. Source digests are assertions
+   supplied by the caller; the store never follows a source reference. A null
+   digest explicitly represents unavailable original-byte verification.
+2. A **lesson proposal** names evidence observations, purpose, principle,
+   exceptions and a complete proposed artifact. Artifacts can be instructions,
+   skills, principles or descriptions of checks. Check artifacts are inert;
+   this module does not turn prose into executable validators.
+3. A **decision** accepts, rejects or defers one exact proposal digest. The
+   digest binds its artifact, scope and cited observation digests. Editing any
+   of them requires a new proposal and decision.
+4. An **activation** binds that decision and artifact to one harness. It makes
+   content eligible for subsequent context requests; it neither installs files
+   nor grants permissions. Withdrawal is a new record, preserving history.
+
+The local CLI accepts an explicit actor assertion. It does not authenticate
+people. A network or multi-user host must resolve actors from its own trusted
+session and enforce access, capture consent and action capabilities before
+calling the library. A field that says `human` is not authentication.
+
+Scope always names an exact project. An activity can be an explicitly reviewed
+`*`; context requests always name a concrete activity. There is no global
+workspace-to-workspace inheritance. Only a local human actor may decide,
+activate or withdraw. Capture and proposal creation never confer those powers.
+
+Two active artifacts with the same kind and name and different content are
+withheld when their scopes overlap the requested activity. The context result
+explains the conflict. This deterministic slot check does not establish that
+differently named lessons are semantically compatible.
+
+## CLI workflow
+
+Run inside the intended Git workspace with `.atelier-local/` ignored and
+untracked. The existing `atelier setup` command can prepare local state for an
+adopted project. Every command reads a JSON object from stdin, up to 256 KiB,
+and prints JSON. Keep request and export files private.
+
+For `capture`, `propose`, `decide`, `activate` and `withdraw`, the envelope is:
+
+```json
+{
+  "workspaceId": "sample-workspace",
+  "actor": { "id": "local-owner", "kind": "human" },
+  "requestId": "capture-one",
+  "expectedRevision": 0,
+  "input": {
+    "id": "observation-one",
+    "signal": "user-correction",
+    "text": "Put shortages first in the inventory summary.",
+    "interpretation": "explicit",
+    "scope": { "project": "sample-project", "activity": "inventory-summary" },
+    "source": { "ref": "manual-user-entry", "digest": null }
+  }
+}
+```
+
+Pass this to `atelier learn capture`. Use the returned revision for the next
+write and a new request identifier. Retrying identical request bytes and actor
+returns the original receipt. Reusing an identifier for changed content refuses.
+A stale revision requires reloading and reviewing the current state.
+
+The subsequent command inputs are:
+
+| Command | Input |
+| --- | --- |
+| `propose` | `id`, `title`, `principle`, `rationale`, `exceptions`, `evidenceIds`, `scope`, `artifact: {kind, name, content}`; optional `supersedes` |
+| `decide` | `lessonId`, returned `lessonDigest`, `verdict: accepted/rejected/deferred`, `reason` |
+| `activate` | New activation `id`, `lessonId`, `lessonDigest`, returned `decisionId`, `harnessId` |
+| `withdraw` | `activationId`, `reason` |
+
+For a proposal, an example complete artifact is:
+
+```json
+{
+  "kind": "instruction",
+  "name": "inventory-summary",
+  "content": "For inventory summaries, list shortages before storage locations."
+}
+```
+
+An exception such as “A location audit can lead with storage locations” stays
+beside the artifact in selected context. Skill artifacts contain the complete
+reviewed text; rendering never asks a model to add unreviewed steps.
+
+Read commands take `{"workspaceId":"sample-workspace"}`:
+
+- `atelier learn list` returns current records and activation states.
+- `atelier learn graph` returns a private graph with typed evidence, proposal,
+  decision, activation and withdrawal nodes and their relationships.
+- `atelier learn plan` groups pending evidence by exact scope and suggests a
+  processing route. Counts are not independent corroboration or promotion rules.
+- `atelier learn export` returns a digest-bound private history archive. There
+  is no automatic send path, canonical graph enrollment or trusted import.
+
+`render` and `context` also require a `query`. A render query is
+`{"lessonId":"lesson-one","lessonDigest":"<digest returned by propose>"}`.
+A context query is:
+
+```json
+{
+  "workspaceId": "sample-workspace",
+  "query": {
+    "scope": { "project": "sample-project", "activity": "inventory-summary" },
+    "harnessId": "sample-harness"
+  }
+}
+```
+
+Pass it to `atelier learn context` at each new task boundary. The response
+includes applicable artifacts, source provenance and exceptions. Proposed,
+rejected, deferred, withdrawn and superseded material is not active guidance.
+The harness remains responsible for instruction hierarchy and actual tool
+permission enforcement. Withdrawing a lesson affects future context selection;
+it cannot erase content a running model already received.
+
+An application outcome can be captured with `lessonId` to link subsequent
+feedback back to the lesson. Revision uses a new proposal with `supersedes`.
+The replacement must retain the exact scope and artifact slot. Acceptance alone
+does not replace active content; activating the accepted replacement retires the
+previous activation in that harness atomically. Changing an active lesson's
+decision requires withdrawing its active bindings first.
+
+## Persistence and recovery
+
+Private state lives under `.atelier-local/learning`. Immutable events retain a
+content digest, previous digest, request, actor assertion and resulting record.
+Existing private-state helpers provide containment, no-follow regular-file
+checks, exclusive writer ownership and non-overwriting durable publication.
+On POSIX, directories and event files use restrictive `0700` and `0600` modes.
+Windows uses account ACLs; POSIX mode bits do not establish Windows access
+control. The hosting account or application must protect workspace access.
+Ignored Git state prevents accidental enrollment, not access by other local
+users.
+Replay verifies the chain and transitions; projections are rebuilt from it.
+
+There are explicit input, event-count and journal-byte ceilings. Unknown files,
+missing events, broken chains and corrupt records refuse. Pending staging files
+are not committed events. A lost reply after a durable write can be reconciled
+by retrying exactly the same request. No automatic compaction or destructive
+history repair occurs. Export before capacity maintenance; do not truncate
+history to make an error disappear.
+
+Admission reserves one event and the maximum valid event size for every active
+binding that would remain after the write. Ordinary writes also preserve a
+minimum maintenance margin. This can refuse a new activation before the journal
+is full, ensuring every existing activation retains room for withdrawal.
+Withdrawal consumes its own reservation while preserving the others. This is a
+journal-capacity guarantee; filesystem failure or lost disk space can still
+prevent a durable write.
+
+Digests prove internal consistency against the retained bytes, not that an
+authorized person authored them. An owner with filesystem write access can
+replace local state. Multi-user trust and signed admission require independent
+host authority. Retention or deletion of source material must also account for
+private learning text and exports; a source reference is not a deletion policy.
+
+## Optional assistance and compatibility
+
+`@mnstry/atelier/learning/assistance` provides mechanical work planning, exact
+bounded evidence batches and a proposal-only adapter driver. The host supplies
+the selected adapter, its qualification evidence, authorization for the exact
+payload and adapter version, and durable budget reservation and settlement.
+The driver makes at most one adapter call for an admitted attempt. Unknown
+completion is retained as unknown; there is no fallback or automatic retry.
+Invalid responses still settle their returned attempt. Unknown usage remains
+unknown. Cancellation, time limits, provider credentials and budget persistence
+belong to the injected host. Tests qualify the adapter contract with synthetic
+implementations; they do not qualify any real model.
+
+Returned drafts still need ordinary `propose`, human decision and activation.
+No expensive model pass is required for capture, integrity checks, grouping,
+context selection, rendering, export or withdrawal. Stronger reasoning can be
+reserved for exceptions and conflicting interpretations.
+
+`@mnstry/atelier/learning/adapters` converts an existing skill-observation
+receipt into a tool-attributed observation. The original feedback words remain
+explicitly unavailable. A legacy lesson can become a fresh proposal with
+caller-selected local evidence and scope; old acceptance and activation never
+transfer. The existing `atelier feedback` support-report command and
+proposal-only `atelier-claim@v1` contract keep their original meaning.
+
+## Public foundation and hosts
+
+The open-source package owns the portable records, validation, local store,
+CLI, evidence graph, context selection, inert rendering and conformance cases.
+Campaigns may stay in their own workspaces; selected references do not change
+their writer ownership. Private evidence projections stay outside committed
+canonical graphs unless an owner explicitly authors an appropriate source.
+
+A desktop or other host owns integrated capture, authenticating its caller,
+background jobs, provider access, budgets, review controls and actual harness
+integration. Private feedback, preferences, methods and authored skills remain
+in their owning workspace. A commercial host should consume these contracts
+without making basic local learning or export depend on an account.
+
+Run `node --test test/learning-*.test.mjs` on the supported Node version for
+the local acceptance cases. They cover terminal capture through withdrawal
+across process restarts, concurrent/stale writes, source and decision binding,
+conflicts, supersession, retention of history, adapter budgets and refusal paths.
+Installed desktop behavior and real-model quality require their own evidence.

package/docs/local-services.md

@@ -145,8 +145,9 @@ explicit consent that names its actor.
 | --- | --- | --- | --- |
 | Health | `GET /health` | none | service name, workspace identity, runtime identifier, PID, loopback host and port, executable digest, start time, status |
 | Status | `GET /status` | bearer | the health fields, loop state, last tick, last error code, and per-view freshness with held notes counted, not named |
-| Tick now | `POST /tick` | bearer | the state of the tick that ran |
+| Tick now | `POST /tick` | bearer | the state of the tick that ran. The body may also name one view (`scopeId`, a contract identifier), which that tick prepares and publishes once more, asking the app again |
 | Stop | `POST /stop` | bearer | an acknowledgement naming the runtime and PID, then the service ends |
+| Plugin challenge, hello, lease, release, status | `POST /plugin/challenge`, `/plugin/hello`, `/plugin/lease`, `/plugin/release`, `/plugin/status` | a handshake over one vault's key, which never crosses the wire | Atelier's Obsidian plugin inside that vault: presence and read-only status of that one view ([obsidian-plugin.md](obsidian-plugin.md)) |
 
 Health carries no path, no note title, no source name and no withheld
 identity. There is no other operation: no file serving, no command, no
@@ -159,13 +160,29 @@ The listener refuses a request before looking its operation up when:
   also refuses a name that resolves to loopback;
 - `Sec-Fetch-Site` is present and is neither `none` nor `same-origin`, or
   `Origin` is present and is not the listener itself;
-- the path is not one of the four, exactly and without a query, or the method
+- the path is not one of the nine, exactly and without a query, or the method
   is not that path's method.
 
 Status, tick and stop additionally refuse without the bearer of the running
 runtime. A `POST` payload is a JSON object of at most 1 KiB that names the
 runtime identifier it is meant for, so a request aimed at an earlier runtime on
-the same port does nothing.
+the same port does nothing (409, `request-names-another-runtime`). A tick may
+also name one view by its `scopeId`, which must be a contract identifier as
+the scope contract defines it (400, `request-invalid`); any other member, and a
+`scopeId` on a stop, is refused (400, `request-member-unknown`). A refused
+request runs nothing.
+
+The plugin commands carry no credential in a header, and refuse one. The key
+of a vault the workspace maintains is random per view and kept owner-only in
+private state and in that vault's plugin data file; it never crosses the
+wire. The service answers a challenge only for a key it holds, with a proof
+over its own exact address, before the plugin sends anything that names the
+vault; the plugin then proves the same key, and every later command and answer
+is sealed with a key for that session, with a counter that only goes up. What
+a session grants is the plugin commands for that one view and nothing else:
+the runtime bearer is not accepted there, and a vault's key is not accepted by
+status, tick or stop. A plugin payload is a JSON object of at most 1 KiB with
+exactly the fields of its command.
 
 ### Status values and refusal cases
 
@@ -178,8 +195,9 @@ the same port does nothing.
 | `stale-record` | the recorded address is closed and the recorded PID is gone | starts; the new service replaces the record once it listens | refuses; nothing is proven to stop |
 | `pid-not-ours` | the recorded address is closed and a process has the recorded PID (the number was reused, or a process outlived its listener) | starts; that PID is never signalled | refuses; that PID is never signalled |
 
-`start` is serialized per workspace, spawns the service without a shell, and
-detaches it only when asked for a service that survives the launching command.
+`start` is serialized per workspace, spawns the service without a shell, in
+the root directory rather than the one the command runs in, and detaches it
+only when asked for a service that survives the launching command.
 It waits for health to echo the runtime identifier it generated and the PID of
 the child it created. If that proof never arrives it stops only that child, by
 its process handle, and reports the private operational log,
@@ -198,6 +216,39 @@ to end and removes only the generated record. It never looks a process up by
 port, name or pattern. Ending a proven runtime that ignores the request is
 opt-in and is proven again immediately before the signal.
 
+A runtime of an earlier release is replaced by a command that asks for a tick
+with the start options of the installed entry (`requestServiceTick({ service
+})`; `open` does). Every runtime records at its start the release it runs
+(`executable.ext.release` in its record): the package version and a digest of
+every runtime module it ships (`src/` and `contracts/`, by path and content),
+and of the plugin it publishes into every vault (`plugins/`; none where a
+package has no such folder).
+A runtime of an earlier release proves itself `healthy` but records an earlier
+version than this package's, this version with an entry module or modules of
+other content, or no release at all (releases up to the one that began
+recording it); or it refuses a tick that names a view, as releases up to
+0.2.0-alpha.11 do (their `POST` payload has exactly one member). Versions are
+ordered as semantic versions, a prerelease below its release
+(`0.2.0-alpha.11` < `0.2.0-alpha.12` < `0.2.0`; `releaseStanding` in
+`lifecycle.mjs`). It is stopped as `stop` stops it and the installed entry is
+started, detached, under the consent already recorded; the answer carries
+`restarted: "outdated"`, and `open` shows `service: restarted (outdated)`. A
+runtime that records a later version, or another version that cannot be
+ordered against the installed one, is never
+replaced by this release, nor asked for the tick: the answer is
+`service-other-release` (`open`: `service-unavailable`, with the next step
+`atelier obsidian service stop`, then open again). So two installations used
+on one workspace, a global and a project-local one for example, do not replace
+each other's runtime on every open; within one version, other content is
+replaced. The same version string is compared by content even when it cannot
+be ordered (a fork's `dev`, say), so the runtime `open` just started is always
+this release and "service stop, then open" cannot loop. A listener of now refuses a tick only when it names another runtime,
+which happens when a concurrent command replaced the runtime between the check
+and the request: the record is read again, the runtime that took its place is
+asked, and nothing is restarted. A `busy` runtime is not stopped, and anything
+that is not a proven runtime of this workspace is never stopped. Without the
+start options the runtime is only reported (`service-outdated`).
+
 The service itself refuses to start beside a runtime of the same workspace
 that proves itself, and ends cleanly when its record no longer names it. Two
 engines can never tick one workspace together: each tick holds a private
@@ -231,15 +282,153 @@ proceeds.
   accepts a connection and does not answer in time proves nothing.
   `inspectPrivateGenerationLock` reports the holder without changing anything.
 
-### Operating-system startup
+### Operating-system startup: the login item
 
 `buildStartupAdapter` returns the text of a launchd user agent (macOS) or a
 systemd user unit (Linux) from the values it is given. It writes no file,
 installs nothing, runs no service manager and looks nothing up on the machine.
 Windows startup has not been qualified and refuses with
-`startup-platform-unqualified`. Installing a unit is a separate system change
-that needs explicit user authorization; the service refuses to run with
-`--startup` unless the recorded consent covers startup.
+`startup-platform-unqualified`. The unit runs the service entry with
+`--startup` in the root directory, with the search path it is given, and is
+restarted after a crash or a non-zero exit but never after a clean one:
+
+| Key | launchd | systemd |
+| --- | --- | --- |
+| Program | `ProgramArguments`: Node, the entry, `--startup`, `--project`, `--data-root`, `--workspace-id`, `--adapter` | `ExecStart`, the same words |
+| Search path | `EnvironmentVariables` `PATH` | `Environment="PATH=…"` |
+| Directory | `WorkingDirectory` `/` | `WorkingDirectory=/` |
+| Start | `RunAtLoad` | `WantedBy=default.target` |
+| Restart | `KeepAlive` `SuccessfulExit` false, `ThrottleInterval` 60 | `Restart=on-failure`, `RestartSec=60`, `RestartPreventExitStatus=2` |
+| Stop | `ExitTimeOut` 60 (a tick in flight gets 30 s) | `TimeoutStopSec=60` |
+| Process type | `Standard`: the service's budgets were measured without background I/O throttling | – |
+| Output | `StandardOutPath`, `StandardErrorPath`: `state/service/login-item.log` | `StandardOutput`, `StandardError`: `append:` the same file |
+
+Installing one is an explicit request (`service unit --install`), never a
+side effect (`src/runtime/obsidian/login-item.mjs`):
+
+1. The entry is the one of the package installed for the project, found as
+   Node finds a package from the project's folder and named by that path,
+   not its real path, so an upgrade or a re-pointed link is what the next
+   start runs. Without one, the command's own package is used unless it lies
+   in a package runner's cache (npx, pnpm dlx, bunx) or a temporary folder:
+   `login-item-needs-installed-package`. Node is named by its real path, so a
+   version manager's per-shell link is never named. The search path keeps
+   absolute entries once, and none in a temporary folder. The unit always
+   names the data root the workspace was resolved under (the flag, the
+   pointer, the overlay's preference or the platform default, such as
+   `$XDG_DATA_HOME/atelier`) and the workspace identity, because the
+   manager's environment carries only the search path: the service at login
+   finds the same workspace, and, when the project no longer leads to it (it
+   moved, or its pointer is gone), records its refusal in the workspace the
+   unit names, if that exists.
+2. The consent is recorded before the unit is loaded, because the manager
+   starts the service as soon as it loads it: `--consent-actor ID`; for a
+   person at a terminal, the actor already recorded for the workspace or else
+   the account's name (asking for the login item there is that person's
+   consent); or a recorded consent that already covers startup. Otherwise
+   `startup-consent-required`. Its coverage becomes `service-and-startup`.
+   A proven service of an earlier release than the entry the unit will run
+   is stopped then, as `service stop` stops it, so the unit's own start at
+   load runs that entry instead of refusing beside the earlier one; if the
+   manager then refuses the unit, the entry is started as a child for this
+   session.
+3. The injected service manager (`service-managers.mjs`) writes the unit
+   atomically with mode 0644 and loads it. launchd: bootout of a loaded job
+   (it keeps the definition it was loaded with), a bounded wait until launchd
+   lets it go, then `bootstrap gui/<uid>`. systemd: `daemon-reload`, `enable`.
+   A unit file written where none was is removed again when the manager
+   does not take it, since launchd loads every property list in
+   `~/Library/LaunchAgents` at login.
+   A manager that refuses the unit takes the consent back to the one recorded
+   before; when none was, the consent just recorded stays for the actor, but
+   covers the service alone.
+4. `state/service/login-item.json` (`atelier-obsidian-login-item/v1`) records
+   the label, allocated once and kept, the unit file, the digest of its text,
+   the program and the search path. The answer is remembered as the
+   `loginItem` decision of the machine settings (`on`), by the actor named or
+   the person at the terminal; `--adapter=obsidian-cli`, when given, is
+   remembered as for `service start`.
+
+The production manager (`service-manager-production.mjs`) is the only code
+that runs `launchctl` or `systemctl` or writes into `~/Library/LaunchAgents`
+or the user's systemd folder. It is imported only by the command entry, and
+refuses under the Node test runner (`real-login-item-under-test`) and when
+HOME is not the account's own home directory (`login-item-home-mismatch`):
+a unit is registered in the account's real session whatever HOME says, so a
+private HOME never installs one.
+
+Once installed, `startService` starts the service through the manager
+(`launchctl kickstart -p`, `systemctl --user start`) instead of spawning a
+child, so two starts never compete, and accepts the runtime that proves itself
+with a record naming the digest of the entry the unit runs; the runtime
+identifier is the service's own there. As for a child, it waits for that
+runtime to be healthy and answers `busy` only when the wait is over and the
+runtime is still in its first tick. A listener that has not written its
+record yet is waited for as that service, never adopted. On the way, a unit
+whose text differs from what would be written now, keeping the recorded
+search path, is written and loaded again (`loginItem: { refreshed: true }`).
+The manager is asked first whether the person switched the item off (System
+Settings on macOS, `systemctl --user disable` on Linux); one that is off is
+neither written again, reloaded, enabled nor started through the manager
+(`login-item-switched-off`). A unit that is switched off, whose file is gone,
+or that the manager does not have loaded (no user systemd), is not forced: a
+child is started for that command only, and the answer says why (`loginItem:
+{ via: 'child', reason }`). `requestServiceTick` replaces an outdated service the same way,
+and so does `startService` with `replaceOutdated` (`service start`): a proven
+runtime of an earlier release is stopped through its own listener, under the
+start lock, and the installed entry started in its place
+(`replaced: 'outdated'`); one of a later release is left running and
+answered as `release: 'later'`.
+
+Which release is installed is read from the entry that would be started
+(`runtimeRelease`): the digest of that entry, and `readReleaseIdentity({
+root })` of the package that entry's path names (its root is the folder above
+`src/runtime/obsidian/service-main.mjs`, read without resolving links), read
+now and never cached. With a login item that is the project's own package,
+whatever package the command runs from, and a re-pointed link or a `file:`
+install is read where it leads now. An entry that is not a package's service
+entry (a test entry) is measured against this package's own release,
+`releaseIdentity()`, the cached form a service records when it starts. Both
+cover the package version and every file under `src/`, `contracts/` and
+`plugins/`; a package without `plugins/` reads as one with an empty one.
+
+Under `--startup` the service:
+
+- writes its log into its own bounded `service.log`, as under `start`; the
+  unit's output file receives only what happens before that log is open;
+- exits 0 on a refusal as well (another runtime of this workspace answers, no
+  consent that covers startup, an occupied port, arguments it cannot use), so
+  its manager does not start it again every minute, and records how the start
+  ended in `state/service/last-startup.json`
+  (`atelier-obsidian-last-startup/v1`: `at`, `outcome` `started` or
+  `refused`, `code`); `status` reports a refusal while the service is not
+  running. A refusal here is any error that carries a code, Node's system
+  errors included (`EACCES`, `EADDRNOTAVAIL` or `EMFILE` from listening,
+  `EPERM` where macOS privacy settings deny a folder): those, too, wait for
+  the next login or `open` instead of a restart every minute. Only an error
+  without a code exits 1 and is restarted;
+- records the path it was started by beside its real path
+  (`executable.ext.invokedAs`), so the busy proof reads a process table that
+  names the entry through a link;
+- after every tick, compares the release on disk, read through the path it
+  was started by, with the one it started with (`readReleaseIdentity`: the
+  package version and a digest of every file under `src/`, `contracts/` and
+  `plugins/`). The files' status is
+  compared first and the digest computed only when that differs; a package
+  that cannot be read is not a change yet. When they differ, the service
+  finishes the tick, removes its record and exits 75, which its manager
+  restarts on the new release.
+
+`service unit --remove` lowers the consent to the service alone first, so a
+unit a failed removal left behind could only refuse, then unloads it (launchd
+`bootout`, systemd `disable --now`, which stop a service it runs) and deletes
+the file and the record, and remembers `off`. It then starts the service again
+at once as a detached child for this session, under the consent now recorded,
+when the adapter is given or remembered; otherwise the next `open` starts it.
+`uninstall` removes the login item and stops the proven service, remembers
+`off`, starts nothing, and keeps the vaults, the private state, the project
+file and Obsidian's vault list. Removing Obsidian's vault entries is not part
+of it.
 
 The service entry refuses to run without an explicitly selected editor
 adapter. Public Atelier tests start only a test entry whose adapter reports
@@ -247,45 +436,72 @@ that no app runs, in temporary directories, on ephemeral loopback ports.
 
 ### The `obsidian` command
 
-`atelier obsidian <operation>` is the noninteractive surface over all of the
-above. With `--json` it prints exactly one JSON document, for a refusal too.
+`atelier obsidian <operation>` is the command-line surface over all of the
+above. Every input is an argument. With `--json` it prints exactly one JSON
+document, for a refusal too.
 Exit codes: 0 done, 1 an error nobody typed, 2 a typed refusal or a usage
 error, 3 the operation ran and its answer is not success.
 
 | Operation | What it does | Writes |
 | --- | --- | --- |
-| `status` | enablement, machine settings, proven service state, per-view freshness, whether an apply operation exists | nothing |
-| `scope list`, `scope show ID` | the declared views | nothing |
-| `audience show`, `audience set A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. A change invalidates every view at the next tick | private machine settings |
+| `status` | enablement, machine settings, what was decided, proven service state, per-view freshness with its diagnostics (a code, the rule and the in-view note concerned, never a value; see [the Obsidian contract](obsidian-contract.md#notes-that-were-laid-out-anyway)), whether an apply operation exists | nothing |
+| `settings` | what this machine remembers for the workspace (who may see, where vaults live, start at login, the adapter), who allowed the service, and how each answer is changed | nothing |
+| `scope list`, `scope show ID` (also `view list`, `view show ID`) | the declared views | nothing |
+| `view add ID (--all \| --folder PATH [--folder PATH ...] [--repo R] \| --tag T) [--expand DEPTH:MAX] [--default] [--allow-empty] [--yes]` | adds a view to the project configuration, after showing the change and how many notes the view would show; refuses a view that would show no note unless `--allow-empty` (see [Adding a view](obsidian.md#adding-a-view)) | `atelier.project.json`, and `.gitignore` when `.atelier-local/` is not ignored. Never committed |
+| `audience show`, `audience set me\|A,B`, `audience clear` | the audiences this machine lets into a view; none by default, which publishes an empty view. `me` is only you: every audience but `sensitive`, which is added by name. The answer is remembered as the person's decision. A change invalidates every view at the next tick | private machine settings |
+| `location show`, `location set DIR [--allow-synced-location]` | where this workspace's vaults live; each view not published yet gets `<project> (<view>)` there at its first publication, and a vault published already stays where it is | private machine settings |
 | `mode show`, `mode set manual\|automatic` | `automatic` refuses without an installed, matching, active automatic policy | private machine settings |
 | `policy show`, `policy install FILE`, `policy revoke` | `install` validates against the apply-policy contract and stores the policy owner-only beside the machine settings, never in a project, a repository or a note. `revoke` marks the stored policy revoked, which the engine reads before its very next dispatch, and returns the mode to manual | private machine settings |
-| `service start`, `service status`, `service stop` | `startService`, `serviceStatus`, `stopService`. The first start needs `--consent-actor ID` | what the lifecycle writes |
-| `service unit --print` | the text `buildStartupAdapter` returns. Installing a unit is not offered | nothing |
-| `open [--scope ID]` | starts or reconnects the owned service, asks it for a tick, reads the view back, qualifies the installed app, has the vault opened | what the service writes |
+| `service start`, `service status`, `service stop` | `startService`, `serviceStatus`, `stopService`. The first start records who allowed it: `--consent-actor ID`, or for a person at a terminal the account's name. `service start` replaces a proven service of an earlier release (`replaced: 'outdated'`) and never one of a later release (`release: 'later'`); with a login item it starts the service through it | what the lifecycle writes |
+| `service unit --print` | the text `service unit --install` would write now | nothing |
+| `service unit --install` | installs the login item and starts the service through it (see above). macOS and Linux | the service settings (consent), the unit file, `login-item.json`, the `loginItem` decision |
+| `service unit --remove` | lowers the consent to the service alone, unloads and deletes the unit, and starts the service again as a detached child for this session | the service settings, the unit file, `login-item.json`, the `loginItem` decision |
+| `uninstall` | removes the login item, stops the proven service, and prints where the vaults, the private state, the project file and Obsidian's vault list are; each is kept, and nothing is started again | the login item's files, the `loginItem` decision |
+| `open [--scope ID]` | starts or reconnects the owned service, asks it for a tick, reads the view back, qualifies the installed app, makes the app know the vault (through the app while it runs; in its settings while none runs), has the vault opened, and asks again for a view the app kept from publication | what the service writes; the app's vault list (see [Obsidian's vault list](obsidian-contract.md#obsidians-vault-list)) |
 
 Reaching the installed app or the operating system is never a default.
 `open`, `service start` and `service unit` refuse with
-`app-adapter-not-selected` unless `--adapter=obsidian-cli` is given, the same
-explicit rule the service entry has, and the modules that talk to an app are
-loaded only after that check. Tests pass their own seams and a guard in the
+`app-adapter-not-selected` unless `--adapter=obsidian-cli` is given, or was
+given once before to `open` or `service start` of this workspace, which
+remembers it (`selectAdapter`); `service unit --install` refuses the same way.
+The service entry keeps its own explicit rule. The modules that talk to an app
+are loaded only after that selection. A remembered adapter is used only by the
+real command-line entry and never under the Node test runner
+(`remembered-adapter-under-test`). A service manager is the caller's
+(`serviceManager`, or `seams.serviceManager`), or, for the real command-line
+entry only, the production one. Tests pass their own seams and a guard in the
 test file throws if anything tries to start the app, its command-line tool, an
-operating-system opener or a service manager.
+operating-system opener or a service manager, touches the account's real
+LaunchAgents or systemd folder, or starts the `obsidian` command's `open` or
+`service` outside the test runner's context with an environment that leads to
+the developer's app.
+
+A person at a terminal is asked one thing, by `view add` only: whether to
+write the change it shows to a file they commit. `--yes` answers beforehand,
+and a question gets no answer after 10 minutes, which writes nothing. The
+first start of the maintenance service records the account's name as the
+actor that allowed it when no `--consent-actor` is given. A person is at a
+terminal when standard input and output are both terminals and neither
+`--json`, `--no-input`, a `CI` environment nor `ATELIER_NONINTERACTIVE=1`
+says otherwise (`isInteractive`); under the test runner the process's own
+terminal is never looked at. A recorded consent is never replaced by a derived
+one.
 
 `open` answers one typed outcome, each with a one-line explanation and a next
 step. Only `current` is success:
 
 | Outcome | Meaning |
 | --- | --- |
-| `current` | the proven service ticked after the request; the view's persisted freshness is `current`; read back independently, the trusted generation is the prepared one and every note has the bytes it was published with; the app meets the minimum version, was asked to open this vault, answers for exactly this vault and has finished reading it |
+| `current` | the proven service ticked after the request; the view's persisted freshness is `current`; read back independently, the trusted generation is the prepared one and every note has the bytes it was published with; the app meets the minimum version, knows this vault as one of its vaults, was asked to open it, answers for exactly this vault and has finished reading it |
 | `updating` | a publication is under way, a tick outlasted the wait, or a note differs from the trusted generation and has not been looked at yet |
 | `held-for-your-edit` | an edited note is preserved and held |
 | `stale-readable` | a last good vault exists and reads back, but is not proven to be the present generation |
-| `not-prepared` | no generation of this view has been published |
+| `not-prepared` | no generation of this view can be read back: none was published yet, or its vault cannot be found or used (the reason says which) |
 | `publisher-conflict` | another publisher or an uncoordinated editor holds the vault |
-| `app-missing`, `app-cli-unavailable`, `app-version-unsupported` | no installation; no command-line capability; below the minimum version, or a version that cannot be read (reason `no-vault-open` when the app runs with no vault open and its command line answers nothing else) |
-| `launch-failed` | the operating system refused, or the app never answered for this vault |
+| `app-missing`, `app-cli-unavailable`, `app-version-unsupported` | no installation; no command-line capability, or the command line turned off in Obsidian (`cli-turned-off`); below the minimum version, or a version that cannot be read (reason `no-vault-open` when the app runs with no vault open and its command line answers nothing else) |
+| `launch-failed` | the vault could not be added to the app's list (a typed reason names why), the operating system refused, or the app never answered for this vault |
 | `indexing` | the app answers for this vault and has not finished reading it |
-| `service-unavailable` | the service could not be started or is not provably ours (`occupied`, no consent yet, a start that never proved ownership) |
+| `service-unavailable` | the service could not be started or is not provably ours (`occupied`, no consent yet, a start that never proved ownership), or it runs a later release than this command (`service-other-release`) |
 | `busy` | the service is ours and in a long tick |
 | `disabled` | the integration is off or not declared |