@timqi/pier 0.1.0 → 0.1.2

package/docs/deploy.md

@@ -1,15 +1,7 @@
 # Running Pier as a service (Linux, systemd)
 
-Pier is one Node process that binds the loopback. Running it in a terminal
-(`pier serve`) is a complete installation — nothing below is required to *use* Pier. What systemd
-adds is the thing a terminal cannot: scheduled tasks fire and IM channels stay
-connected while nobody is logged in.
-
-That is also why this document is Linux-only. A laptop closes its lid; the
-machine you want always-on is a server, and on that machine systemd is already
-there.
-
-## The short version
+`pier serve` in a terminal is a complete installation; systemd keeps tasks
+firing and channels connected while nobody is logged in. Linux only.
 
 ```sh
 npm install -g @timqi/pier
@@ -17,225 +9,97 @@ pier service install
 journalctl --user -u pier -e     # the password, printed once
 ```
 
-That writes the unit below, enables linger, and starts the service. The rest of
-this page is what it wrote and why — read it before widening the bind, and when
-you want the unit to say something different.
+That writes the units, enables linger, and starts the service. `systemctl
+--user cat pier` shows the units with their per-line comments; this page is
+what they do not say.
 
 ## Prerequisites
 
 - Node 24 or newer (`node:sqlite` is used unflagged).
-- A user-writable global npm prefix. The updater runs as you, so an initial
-  install that needed `sudo npm install -g` cannot later update itself.
-- The `sqlite3` CLI is optional, for the off-machine backup and password steps
-  below. Pier itself and its automatic update backup do not need it.
-- Pier installed globally: `npm install -g @timqi/pier`. The unit runs that
-  installed entry point, so a deploy is `pier update`. A checkout
-  (`git clone` + `npm ci && npm run build`) is the *develop* path; point the
-  unit's `ExecStart` at its `dist/main.js` if you run one as the service, and
-  update it with the "From a checkout" steps under Updating.
+- A user-writable global npm prefix: the updater runs as you.
+- `sqlite3` CLI: optional, for the off-machine backup and password steps below.
+- Pier installed globally. A checkout (`git clone` + `npm ci && npm run build`)
+  is the *develop* path; point the unit's `ExecStart` at its `dist/main.js` if
+  you run one as the service, and update it with the checkout steps under
+  Updating.
 
 ## The unit
 
-A **user** unit, not a system one: Pier runs as you, reads your Pi
-configuration, and drives sessions in your own directories. Running it as root
-or as a dedicated system user means an agent that cannot touch the files you
-wanted it to work on.
-
-`~/.config/systemd/user/pier.service` — what `pier service install` generates,
-with your absolute Node and package paths filled in:
-
-```ini
-[Unit]
-Description=Pier — agent workspace
-Documentation=https://github.com/timqi/pier
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=%h
-# Absolute paths on purpose: systemd starts with a minimal PATH, so a node
-# installed by nvm/fnm/asdf is not on it — the installer fills in the node
-# that installed Pier and the globally installed entry point.
-ExecStart="/absolute/path/to/node" "/absolute/npm/prefix/lib/node_modules/@timqi/pier/dist/main.js"
-# Inherited by every command a turn runs: on systemd's bare PATH an agent asked
-# to run npm or node would be told they do not exist. The installer records the
-# PATH of the shell that ran it — that shell is your login one — with the node
-# above first and the standard directories as a floor. Installed a new tool
-# since? Re-run install --force, or add your own drop-in.
-Environment="PATH=/absolute/path/to/node/bin:/your/shell/PATH:/usr/local/bin:/usr/bin:/bin"
-# Loopback by default. Put a reverse proxy in front before widening this —
-# whoever reaches this port can drive an agent that runs a shell.
-Environment="HOST=127.0.0.1"
-Environment="PORT=3141"
-Restart=always
-RestartSec=2
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=pier
-
-[Install]
-WantedBy=default.target
-```
-
-`--pier-home` adds a quoted `PIER_HOME` environment line. Paths with spaces and
-literal systemd `%` specifiers are escaped. `pier service install` also writes an
-updater unit containing the exact npm executable currently on `PATH`. Re-run with
-`--force` after changing service settings or the Node/npm installation; it
-rewrites both units and restarts the running service. The limits drop-in remains
-operator-owned and is never overwritten.
-
-Enable it, and tell logind to keep your user manager alive after you log out —
-without lingering, every scheduled task stops when your SSH session ends:
-
-```sh
-loginctl enable-linger "$USER"
-systemctl --user daemon-reload
-systemctl --user enable --now pier
-```
+A **user** unit. `~/.config/systemd/user/pier.service` records the absolute
+node and entry point, the installing shell's `PATH`, and a loopback bind;
+`--pier-home` adds `PIER_HOME`. `pier service install --force` rewrites both
+units and restarts (after a new tool, or a moved Node); the limits drop-in is
+never overwritten. Linger is enabled by the installer.
 
 ## Memory limits
 
-Worth setting: an agent runs whatever a turn decided to run, so the failure to
-plan for is a build or a test suite eating the machine, not Pier itself
-leaking. A cgroup limit turns "the box OOMs and sshd dies with it" into "the
-heaviest process inside this unit is killed".
-
-User units can do this without root as long as the memory controller is
-delegated to your user manager, which it is by default on current systemd:
+Requires the memory controller delegated to your user manager (default on
+current systemd):
 
 ```sh
 systemctl show "user@$(id -u).service" -p DelegateControllers
 # DelegateControllers=cpu memory pids   ← memory listed means these work
 ```
 
-`~/.config/systemd/user/pier.service.d/limits.conf` — a drop-in, so the unit
-above stays about what Pier is and this file is about what it may consume:
-
-The limit is on the **whole unit**: `node`, every Pi subagent, and every
-command a turn ran, added together — plus the page cache those processes
-touched, which is why the soft ceiling should be the one that bites. So size it
-as a share of the machine, not as "how much should Pier need". Percentages are
-relative to installed physical memory, which also keeps this file portable:
-
-```ini
-[Service]
-# Soft ceiling: past this the kernel reclaims hard and lets the unit crawl
-# instead of killing anything. This is the one that should bite first.
-MemoryHigh=60%
-# Hard ceiling: the kernel OOM-kills *inside this cgroup*. The number exists to
-# protect everything outside it — the OS, sshd, your other services — so what
-# it should leave behind is a few GB for them, not a small share for Pier.
-MemoryMax=75%
-# Swapping an agent is worse than failing it — the machine stops responding
-# long before the limit is reached.
-MemorySwapMax=0
-# A runaway command an agent ran can fork as well as allocate.
-TasksMax=512
-# The unit's own processes are the preferred victims if the *machine* still
-# runs out, e.g. before these limits are tuned. Works with no cgroup limit at
-# all, which makes it the cheapest half of this file.
-OOMScoreAdjust=200
-# A child being OOM-killed must not take the service with it: the turn that
-# ran it fails, Pier keeps serving. (Delegated units default to this; set
-# explicitly because the default depends on system configuration.)
-OOMPolicy=continue
-```
-
-On a dedicated 4–8 GB VPS those percentages land around 2.5–6 GB, which is
-roughly what one agent doing ordinary work needs. On a big shared box, prefer
-absolute values sized to what you are willing to lose to a runaway build —
-`MemoryHigh=8G` / `MemoryMax=12G` on 32 GB, say — because 75% of a large
-machine is no longer a meaningful ceiling.
-
-Pick the numbers by measuring, not by guessing — Pier idles in the hundreds of
-MB, and what varies is what the agent runs:
+The installer writes `~/.config/systemd/user/pier.service.d/limits.conf` once
+(`MemoryHigh=60%`, `MemoryMax=75%`, no swap, `TasksMax=512`, `OOMPolicy=continue`,
+each line commented). The limit covers the **whole unit** — `node`, Pi
+subagents, every command a turn ran, their page cache. Dedicated 4–8 GB VPS:
+the defaults land around 2.5–6 GB. Big shared box: absolute values
+(`MemoryHigh=8G` / `MemoryMax=12G` on 32 GB). Pier idles in the hundreds of MB:
 
 ```sh
 systemctl --user show pier -p MemoryCurrent -p MemoryPeak
 systemd-cgtop --depth=3 "user.slice/user-$(id -u).slice"
 ```
 
-A limit that fires during ordinary work is worse than none: the turn dies with
-a signal and the cause is a kernel message nobody reads. Set it to protect the
-machine, then raise it the first time it kills something legitimate.
-
 ## Logs
 
-Pier writes to stdout and stderr and to nothing else — no log file, no
-rotation, no log configuration. Under the unit above that *is* the log:
-journald stamps the time, keeps the history and rotates it, which is why
-nothing in Pier reimplements any of that.
+stdout and stderr only; journald stamps, keeps and rotates.
 
 ```sh
 journalctl --user -u pier -f            # follow
 journalctl --user -u pier -p warning    # only what went wrong
 journalctl --user -u pier --since -1h | grep 'tasks:'   # one area
+journalctl --user -u pier | grep 'client:'              # browser-side errors
 ```
 
 Every line is `area: message` — `core`, `agent`, `tasks`, `slack`, `telegram`,
 `lark`, `channels`, `slack.tool`, `auth`, `boards`, `client`, `db`, `drain`,
-`secrets`, `settings`, `credentials`, `update`, `tools`, `push`,
-`web`, `web.providers`, `pier` — so an area is a grep
-and a level is a `-p`. The level reaches journald as a syslog priority prefix, which Pier
-emits only when systemd says the output is a journal (`$JOURNAL_STREAM`); run
-in a terminal, the same lines carry a timestamp and a level word instead.
-
-What is logged by default: process start and shutdown, sessions opening,
-conversation → session routing, every turn ending, every task run queued and
-settled, callback and message delivery failures with their retries, adapters
-starting (and failing to start or stop), dropped inbound messages, failed
-logins, and any request that threw. A watch probe that matched nothing is the
-one routine event kept at `debug` — it fires on every interval.
-
-`client:` is the browser's half, posted back by the workbench (`ui/report.ts`)
-and written into this same stream: script errors, unhandled rejections and a
-dead SSE stream, each with the view and the user agent. It comes from signed-in
-tabs only — the route sits behind the password like the rest of `/api`, so
-nobody who cannot already reach Pier can write into this journal. The person sees the
-same sentence in the chat pane, so "I clicked and nothing happened" has a line
-on both ends:
-
-```sh
-journalctl --user -u pier | grep 'client:'
-```
+`secrets`, `settings`, `credentials`, `update`, `tools`, `push`, `web`,
+`web.providers`, `pier`. Level: a syslog priority prefix under
+`$JOURNAL_STREAM`, a level word in a terminal. `client:` is posted back by
+signed-in workbench tabs (`ui/report.ts`): script errors, unhandled rejections,
+a dead SSE stream, with view and user agent.
 
 ```sh
 systemctl --user set-environment PIER_LOG=debug   # + per-message tracing
 systemctl --user restart pier
 ```
 
-`PIER_LOG` takes `debug`, `info` (default), `warn`, `error` or `silent`. Prefer
-turning `debug` on for a session and back off: it logs one line per inbound
-message and per tool call.
+`PIER_LOG`: `debug`, `info` (default), `warn`, `error`, `silent`. `debug` logs
+one line per inbound message and per tool call.
 
 ## First login
 
-Pier generates a password on an empty database and prints it once, so the
-journal is where you read it:
+A password is generated on an empty database and printed once:
 
 ```sh
 journalctl --user -u pier | grep -A2 'no password'
 ```
 
-Only its scrypt hash is stored. If you lose it, drop the row and restart — a
-new password is generated and printed:
+Only its scrypt hash is stored. Lost it? Drop the row and restart:
 
 ```sh
 sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'
 pier restart
 ```
 
-Changing the password signs out every browser: the session rows behind the
-cookies are deleted. So does the recovery above — a new password does not leave
-the old one's browsers signed in. To end one browser without changing the
-password, use Settings → Instance → Signed-in devices. A session that is not
-used expires 7 days after its last request. However a session ends — signed
-out, expired, password changed, password recovered — its push subscription is
-deleted with it, so that browser stops being notified as well.
-
-The upgrade that introduced these rows signs everyone out once: a cookie issued
-before it names no row. Have the password to hand.
+- Changing or recovering the password signs out every browser.
+- One browser: Settings → Instance → Signed-in devices.
+- A browser session expires 7 days after its last request, and 90 days after
+  it signed in however often it is used.
+- However a session ends, its push subscription goes with it.
 
 ## Restarting and reloading
 
@@ -245,34 +109,26 @@ pier reload           # apply channel config and recycle idle sessions in place
 pier tools sync       # install/update the managed CLI tools
 ```
 
-Both commands signal the installed systemd service; they are not foreground
-process controls. `pier restart` refuses new messages and root Task runs, waits
-up to five minutes for active work, then exits for `Restart=always` to start the
-next process. At the deadline it records every aborted IM turn first, and the
-next process posts that note after its adapter starts. Cleanup after the deadline
-has one shared 10-second bound regardless of how many sessions are stuck.
-
-`pier tools sync` converges the command-line tools switched on in Console →
-Settings — they install into `~/.pier/tools/bin`, which the service puts first
-on the PATH every session and task inherits. Normally a switch runs
-it for you as a task; typing it is for a machine that was offline when one was
-flipped. One sync runs at a time per machine: an overlapping one waits for the
-lock (and converges on the switches as they stand when its turn comes) instead
-of racing the other's installs.
-
-`pier reload` does not stop active work. It reloads Slack and Telegram adapters
-and immediately evicts idle sessions nobody is watching, so their next message
-opens with current agent files and configuration. Streaming sessions and
-sessions held by an open workbench stay attached until their normal eviction.
-
-Console → Settings → Instance → **Reload** is the same thing from a browser, and
-needs no shell on the box. It also takes the session open in the tab that asked
-(only a turn in flight is exempt) and answers with how many were recycled and
-how many are still mid-turn — the second number is the only reason a change can
-still fail to show up.
-
-An ordinary `systemctl --user restart pier` and `pier update` remain fast,
-hard-stop paths. Let active work finish first when using either one.
+All three signal the installed service.
+
+- `pier restart`: refuses new messages and root Task runs, waits up to five
+  minutes, exits for `Restart=always`; aborted IM turns at the deadline are
+  recorded and posted by the next process; post-deadline cleanup has one shared
+  10-second bound.
+- `pier reload`: reloads channel adapters, evicts idle unwatched sessions;
+  streaming or watched sessions, and sessions still holding queued messages,
+  stay until normal eviction. Console → Settings → Instance → **Reload** is
+  the same, also takes the asking tab's session (unless mid-turn or holding a
+  queue), and answers `recycled` / `busy`.
+- `pier tools sync`: converges the tools switched on in Console → Settings into
+  `~/.pier/tools/bin` (first on every session's PATH); one sync at a time per
+  machine.
+- `systemctl --user restart pier` and `pier update` are hard stops.
+- One Pier per `$PIER_HOME`: a start whose directory another live Pier holds
+  logs `another Pier (pid N) owns …` and exits before opening the database. Kept
+  under `Restart=always` on purpose — the service takes the directory back by
+  itself once the other process (usually a hand-typed `pier serve`) is gone, at
+  one refused start every `RestartSec=2` until then.
 
 ## Updating
 
@@ -281,12 +137,10 @@ pier update           # installs the latest release, then hard-stops/restarts Pi
 pier update --check   # only says whether one exists
 ```
 
-The workbench footer says the same thing without being asked: the server asks
-`registry.npmjs.org` at boot and at most every 30 minutes after that, and the
-version turns into `v0.0.1 → 0.0.2` when there is something newer. A failed
-check is silent by design — an offline box is not a broken one.
+The footer asks `registry.npmjs.org` at boot and at most every 30 minutes and
+shows `v0.0.1 → 0.0.2` when newer exists; a failed check is silent.
 
-From a checkout instead, stop and back up before replacing the build:
+From a checkout:
 
 ```sh
 systemctl --user stop pier
@@ -297,54 +151,27 @@ npm ci && npm run build
 systemctl --user start pier
 ```
 
-For a service install, `pier update` hard-stops Pier; it does not use the
-graceful `pier restart` path. The Console's **Update now** and the automatic
-path do: both drain (new work refused, running turns finished, the rest
-ledgered for the next boot to report) before the updater unit is started.
-
-Either way the updater snapshots the database to
-`~/.pier/db/backups/pier.db.release-<version>.bak` before npm touches the
-package — `<version>` being the Pier that is being replaced, i.e. the release to
-reinstall if that copy is ever restored. This happens for every release,
-including releases with no schema change.
-
-Both of those steps run while Pier is still serving: the snapshot is taken
-through a read-only connection, so it is consistent on a live database, and npm
-writes into the global prefix rather than into the running process. Only the
-stop and the start that follow them are downtime — a second or two instead of
-the ten to twenty an install takes. A backup or install that fails therefore
-never stops anything; the failure is in the updater's journal and the running
-Pier keeps serving the version it already loaded. (For those seconds the live
-process is running code whose files on disk have already been replaced: a
-browser left open on the old page can see a lazily loaded asset 404 until it
-reloads. On the drained paths nothing else is running by then; `pier update`
-does not drain, which is the same reason to let active work finish first.)
-
-### Automatic updates
-
-Off by default. Switched on from the version panel, it checks every 15 minutes
-and hands over only when all three hold: the switch is on, a newer release
-exists, and the instance is idle (nothing streaming, no task run in flight).
-systemd only — without the unit there is nothing to hand the install to.
+`pier update` hard-stops; the Console's **Update now** and the automatic path
+drain first (new work refused, running turns finished, the rest ledgered for
+the next boot). Either way the updater snapshots
+`~/.pier/db/backups/pier.db.release-<version>.bak` (`<version>` = the Pier being
+replaced) before npm runs, every release. Only stop and start are downtime; a
+failed backup or install stops nothing (`journalctl --user -u pier-update`).
 
-The unit records **absolute** paths to the node and npm that installed Pier,
-because systemd's PATH has neither. That pins it to one directory of one version
-manager: with fnm or nvm, `fnm uninstall v24` deletes the Node that `ExecStart`
-names while the running process survives (Linux keeps a deleted binary mapped).
-Pier checks those paths at boot and before every handover, and reports it in the
-journal and in the version panel rather than letting the next restart fail:
+**Automatic updates**: off by default; switched on from the version panel;
+checks every 15 minutes; hands over only when the switch is on, a newer release
+exists, and the instance is idle (nothing streaming, no task run in flight).
+systemd only.
 
-```
-pier service install --force    # re-records the current node and npm
-```
+**Node paths**: `fnm uninstall v24` (or nvm) deletes the Node `ExecStart`
+names while the process survives; Pier checks at boot and before every handover
+and reports in the journal and the version panel. Fix: `pier service install
+--force`.
 
-A newer Pier brings its own schema up on the next start: the migrations run in
-one transaction before the port opens, and the version they leave behind is
-stamped in the database. It also snapshots the immediately preceding schema to
-`~/.pier/db/backups/pier.db.v<N>.bak` (`N` = the schema it was at). **Upgrades
-only.** Start an older Pier on a database a newer one has migrated and it
-refuses to run rather than write tables it does not understand — the way back
-down is either a release backup or that schema snapshot:
+**Schema**: a newer Pier migrates on start, in one transaction before the port
+opens, after snapshotting to `~/.pier/db/backups/pier.db.v<N>.bak` (`N` = the
+schema it was at). Upgrades only: an older Pier refuses a newer database. Way
+back:
 
 ```sh
 systemctl --user stop pier
@@ -354,86 +181,44 @@ cp backups/pier.db.release-0.0.4.bak pier.db    # the version in the name
 # then reinstall that Pier release: npm install -g @timqi/pier@0.0.4
 ```
 
-Every copy lives in `~/.pier/db/backups/`, written under a temporary name and
-renamed into place, so a `.bak` name only ever refers to a finished copy. The
-three newest of **each kind** are kept — three release backups and three schema
-snapshots, counted separately so a run of releases cannot evict the copies taken
-before a migration. Backing up twice at the same version replaces that version's
-copy. Each is a full copy of the database, one directory below it, and therefore
-protects against a bad upgrade, not against a lost disk — an off-machine copy is
-still yours to take.
-
-### Can it update itself?
-
-Yes, with one caveat that decides the shape: **the updater must not be a child
-of the service it restarts.** `systemctl --user restart pier` kills everything
-in `pier.service`'s cgroup, so an update script spawned by Pier dies halfway
-through — sometimes after unpacking and before restarting, which is the one
-outcome worse than not updating.
-
-So installation writes a second unit and `pier update` starts it after recording
-the running service's effective `PIER_HOME` in a runtime drop-in. That includes
-an operator environment override, so the updater cannot back up one database and
-migrate another. `~/.config/systemd/user/pier-update.service`:
-
-```ini
-[Unit]
-Description=Update Pier to the latest published version
-
-[Service]
-Type=oneshot
-# npm's dependencies run postinstall scripts as `sh -c node …`, which needs a
-# node on PATH — the absolute one below only answers npm's own shebang. Same
-# recorded PATH as pier.service, and recorded rather than sourced from a login
-# shell at run time: a dotfile must not get to decide which node npm uses.
-Environment="PATH=/path/to/node/bin:/your/shell/PATH:/usr/local/bin:/usr/bin:/bin"
-ExecStart=/path/to/node /path/to/pier/dist/cli.js backup
-ExecStart=/path/to/node /recorded/path/to/npm install -g @timqi/pier@latest
-# Last: everything above it runs with Pier still up, so the stop is the downtime.
-ExecStart=systemctl --user stop pier.service
-ExecStopPost=systemctl --user start pier.service
-```
-
-`pier update` triggers that unit with a call that survives Pier's restart because
-the work happens in a different cgroup. Starting the unit directly is unsupported:
-the command first records the effective database home used by the running service.
+Copies are written under a temporary name and renamed into place; the three
+newest of **each kind** (release, schema) are kept; a second backup at the same
+version replaces it. They protect against a bad upgrade, not a lost disk.
 
-Deliberately **not** a `systemd.timer`. An unattended update is a machine that
-rewrites its own code from the network while holding your API keys, and its hard
-stop interrupts whatever session was mid-turn. Pier notices a newer release
-and says so in the workbench footer; starting the update stays a decision someone
-makes. The updater's `ExecStopPost` is what brings the service back: after a
-successful stop, and — as a no-op, since nothing was stopped — after a backup or
-install that failed.
+**The updater unit** `pier-update.service` (backup, `npm install -g`, stop,
+`ExecStopPost` start) runs outside `pier.service`'s cgroup, which a restart
+kills. `pier update` records the service's effective `PIER_HOME` in a runtime
+drop-in, then starts it; starting the unit directly is unsupported. No
+`systemd.timer`: only Pier starts an update, so it can drain first.
 
 ## Remote access
 
-The unit binds the loopback, and that is the intended posture. To reach it from
-elsewhere, pick a tunnel rather than a wider bind:
-
-- `ssh -L 3141:localhost:3141 server` — nothing to configure, nothing exposed.
-- Tailscale, or Cloudflare Tunnel — no open port, and TLS terminates outside.
-- A reverse proxy (Caddy, nginx) if you want a real hostname. Terminate TLS
-  there, preserve the external `Host` (or pass `X-Forwarded-Host`), and pass
-  `X-Forwarded-For`; Pier uses the external host for write-origin checks and
-  counts login failures per forwarded client. Its session cookie is marked
-  `Secure` when a loopback proxy reports `X-Forwarded-Proto: https` (the header
-  is ignored from anywhere else, where it is a header the client wrote).
+Loopback bind; reach it over a tunnel, not a wider bind:
+
+- `ssh -L 3141:localhost:3141 server`
+- Tailscale, or Cloudflare Tunnel — no open port, TLS terminates outside.
+- A reverse proxy (Caddy, nginx): terminate TLS there, preserve the external
+  `Host` (or pass `X-Forwarded-Host`), and **set** `X-Forwarded-For` to the
+  client — nginx `proxy_set_header X-Forwarded-For $remote_addr;`, Caddy by
+  default. Pier reads the rightmost hop, so appending the peer is safe too
+  (`$proxy_add_x_forwarded_for`); the unsafe case is a proxy that passes the
+  client's own header through without adding a hop of its own, which lets the
+  client name its throttle bucket.
+  Pier uses the external host for write-origin checks and counts login
+  failures per forwarded client. The cookie is `Secure` when a loopback proxy
+  reports `X-Forwarded-Proto: https` (ignored from anywhere else).
+- `ssh -L` sends no such header, so every client through the tunnel shares one
+  throttle bucket.
 
 ## Backups
 
-Three paths hold everything: `~/.pier/db/pier.db` (tasks, channels, the chat →
-session map, workbench state, settings, the password hash, and the sealed
-provider credentials and channel tokens), `~/.pier/master.key` (the key that
-seals them — without it the database's sealed values are unreadable), and
-`~/.pier/boards/`. `~/.pier/db/backups/` holds the automatic pre-update and
-pre-migration copies, named for the release or schema they came from.
-For off-machine backups, use `sqlite3 ... "VACUUM INTO '…'"` rather than `cp`,
-which under WAL can miss the most recent commits. Pi's own session history lives
-under `~/.pier/pi` (Pier sets `PI_CODING_AGENT_DIR` there unless the environment
-already names another directory).
-
-Inbound chat attachments (photos, uploads from any surface) accumulate under
-`~/.pier/inbox/<channel>/` and are never deleted by Pier — a transcript may
-reference them indefinitely. Prune old files by hand (or a cron) when disk
-matters; a pruned file degrades to a broken attachment link, nothing else.
+- `~/.pier/db/pier.db` — tasks, channels, chat → session map, workbench state,
+  settings, password hash, sealed credentials and tokens. Off-machine: `sqlite3
+  ... "VACUUM INTO '…'"`, not `cp` (WAL can miss the latest commits).
+- `~/.pier/master.key` — seals the database's credentials.
+- `~/.pier/boards/`.
+- `~/.pier/db/backups/` — the automatic pre-update and pre-migration copies.
+- `~/.pier/pi` — Pi's session history (unless `PI_CODING_AGENT_DIR` names
+  another directory).
+- `~/.pier/inbox/<channel>/` — inbound chat attachments, never deleted by
+  Pier; prune by hand (a pruned file becomes a broken attachment link).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
   "license": "AGPL-3.0-only",
   "repository": "github:timqi/pier",