office: usage text, no session before the project is known good; commands on PATH

.pi/memory-vault/packs/paperclip-harness/20-context/home.md

@@ -898,3 +898,100 @@ Committed as `9631cdd` and pushed.
 - session: [[packs/paperclip-harness/80-sessions/paperclip-tuios-sessions-across-hosts-initextra-initcontent-|Paperclip/TUIOS sessions across hosts, initExtra→initContent fix, and dry-runs]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-11-23-32-18|Rich discovery: home 2026-11-11 23:32:18]]
 - context: [[packs/paperclip-harness/20-context/home|home]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+## Rich discovery update (2026-11-12 00:35:25)
+
+You are right that I was inconsistent. Here is the exact state, then the simple rule for `office`.
+
+## What is applied, precisely
+
+| | `/etc/nixos` changed? | Evaluates to pi | Running pi | Needs |
+|---|---|---|---|---|
+| **`.13`** | **yes, now**: lock bumped to 2026-11-07, `initExtra` → `initContent` | **1.5.0** | 0.82.1 | one `sudo nixos-rebuild switch` |
+| **`.27`** | **yes, now**: same two edits | 1.5.0 | 0.82.1 | a fix first — see below |
+| **`.51`** | no | 0.87.1 | 0.87.1 | the same two edits, then rebuild |
+
+Earlier I said "applied" when I had only tested a copy in `/tmp`. That was wrong wording on my part: nothing had been written to `/etc/nixos`. It has been now, on `.13` and `.27`, and `.13`'s dry-run build passes with 465 derivations to build and 5.5 GiB to fetch.
+
+On `.13`, the rebuild is:
+
+```sh
+sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop
+```
+
+**`.27` cannot be rebuilt yet.** Its evaluation fails in home-manager's fontconfig code:
+
+```
+… while evaluating the option `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings':
+error: … head values (attrsets.nix:1711)
+```
+
+That is home-manager 2026-11-10 disagreeing with something in `.27`'s font configuration, not the Pi change. The smaller next attempt is to bump **nixpkgs only** on `.27` and leave home-manager where it is — I would try that before touching fonts.
+
+`.51` would need the same two edits to reach 1.5.0. Say whether you want `.51` aligned in the same pass, or left at 0.87.1 until `.13` is proven.
+
+## Your notes, adopted — and the commands simplified
+
+I read `docs/STARTUP-COMMANDS.md`. Four things from it are now in our `bin/office`:
+
+- **A host name → address table** (`nixos-desktop`/`.13` → `192.168.20.13`, and so on), because the old version broke on names ssh could not resolve.
+- **A check whether the named host is this machine**, before any ssh. I hit exactly that trap tonight: `office --remote 192.168.20.13` from `.13` tried to log in to itself.
+- **An ssh probe** (`ssh -o BatchMode=yes <addr> true`) before doing anything remote, so a missing key says so instead of half-working.
+- **`bin/board --reset`** — closes every pane, waits until the session is empty, clears the workspace names, then builds. `--replace` alone can run out of workspace slots on a half-built session.
+
+One thing is *simpler* than the old design: it needed `tuios new --host …` plus `office … --host …`, because `office` could not create a session. Ours can, through the daemon's own verb. So it is one command.
+
+## The rule, in one table
+
+| Situation | Command |
+|---|---|
+| folder on this machine, shell on this machine | `bin/office <folder> --project "<Name>"` |
+| folder Paperclip has not seen yet | `bin/office <folder> --new "<Name>"` |
+| folder on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
+| repair / rebuild | `bin/board`, `bin/board --replace`, `bin/board --reset` |
+| start again from nothing | `bin/project-reset <folder>` |
+
+And the rule that removes the confusion: **the folder and the session live on the same machine.** If you are typing inside the session, on the machine that owns the folder, it is just `bin/office <folder>`. `--host` is only for the case where those two differ.
+
+Written into `docs/STARTUP.md`, committed as `7b2cccf` and pushed.
+
+## Your `email_agent` case, concretely
+
+The folder is on `.13`, the Paperclip project is **Email Agent** (`local_path`, so no worktree policy), and the session must live on `.13`. From `.27`:
+
+```sh
+bin/office /home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent
+```
+
+That runs the work on `.13` over ssh, creates the session there, and builds eight panes. Then `tuios attach --host nixos-desktop email-agent`. No program can move your client, so that last step is always yours.
+
+## Source paths observed
+
+- `gitea.lab.audasmedia.com.au/sam/paperclip-harness.git`
+- `NixOS/nixpkgs/0954f7ee2f6bb3dc7d4e3d0d8bcb8fd4bde4cfc5`
+- `NixOS/nixpkgs/f4a03c008967841f2a0b3cb7c436fc6fc31671f6`
+- `home/sam/.config/fontconfig/conf.d/10-hm-fonts.conf`
+- `fontconfig/conf.d/10-hm-fonts.conf`
+- `etc/nixos/hosts/sam-4screen-desktop/configuration.nix`
+- `etc/nixos/hosts/sam-thinkpad/configuration.nix`
+- `home/sam/paseo/projects/email_agent`
+
+## Evidence
+
+- Confidence: 84%
+- Reason: Update component/repository context with detailed discovered structure and configuration
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md

@@ -1016,3 +1016,101 @@ Say go on 1 and I will run the project-docs pass before anything else.
 - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-headroom-integration-machine-drift-cancel-|paperclip-harness: headroom integration, machine drift, cancel feature, office workflow]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-itself-2026-11-11-08-00-32|Rich discovery: itself 2026-11-11 08:00:32]]
 - context: [[packs/paperclip-harness/20-context/tmp|itself]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+Repo/config root is /etc/nixos (NixOS flake, home-manager). Hosts live under /etc/nixos/hosts/<host>/configuration.nix and shared home config in /etc/nixos/home.nix; flake.lock pins nixpkgs.
+
+Hosts and addresses: nixos-desktop/.13 -> 192.168.20.13, .27, .51 (ssh access by IP; names may not resolve).
+
+Pi CLI (the 'pi' tool) exists in three versions across the fleet: .13 and .27 evaluate to 1.5.0 after edits, .51 currently at 0.87.1. Running binaries were 0.82.1 on .13/.27 before rebuild.
+
+Fonts are declared per-host in configuration.nix (nerd-fonts.symbols-only, font-awesome, nerd-fonts.jetbrains-mono) plus home-manager fontconfig (see hosts/sam-4screen-desktop/configuration.nix lines ~398-446 and hosts/sam-thinkpad/configuration.nix ~199-202).
+
+Office workflow docs are in /etc/nixos/docs/: STARTUP-COMMANDS.md (existing notes) and STARTUP.md (new simplified rule, committed as 7b2cccf). Helper scripts: bin/office, bin/board, bin/project-reset.
+
+Key rule documented: the folder and the session must live on the same machine. On the owning machine run `bin/office <folder>`; use `--host <host>` only when the folder and session machine differ.
+
+## Detailed context from completed turn
+
+You are right that I was inconsistent. Here is the exact state, then the simple rule for `office`.
+
+## What is applied, precisely
+
+| | `/etc/nixos` changed? | Evaluates to pi | Running pi | Needs |
+|---|---|---|---|---|
+| **`.13`** | **yes, now**: lock bumped to 2026-11-07, `initExtra` → `initContent` | **1.5.0** | 0.82.1 | one `sudo nixos-rebuild switch` |
+| **`.27`** | **yes, now**: same two edits | 1.5.0 | 0.82.1 | a fix first — see below |
+| **`.51`** | no | 0.87.1 | 0.87.1 | the same two edits, then rebuild |
+
+Earlier I said "applied" when I had only tested a copy in `/tmp`. That was wrong wording on my part: nothing had been written to `/etc/nixos`. It has been now, on `.13` and `.27`, and `.13`'s dry-run build passes with 465 derivations to build and 5.5 GiB to fetch.
+
+On `.13`, the rebuild is:
+
+```sh
+sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop
+```
+
+**`.27` cannot be rebuilt yet.** Its evaluation fails in home-manager's fontconfig code:
+
+```
+… while evaluating the option `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings':
+error: … head values (attrsets.nix:1711)
+```
+
+That is home-manager 2026-11-10 disagreeing with something in `.27`'s font configuration, not the Pi change. The smaller next attempt is to bump **nixpkgs only** on `.27` and leave home-manager where it is — I would try that before touching fonts.
+
+`.51` would need the same two edits to reach 1.5.0. Say whether you want `.51` aligned in the same pass, or left at 0.87.1 until `.13` is proven.
+
+## Your notes, adopted — and the commands simplified
+
+I read `docs/STARTUP-COMMANDS.md`. Four things from it are now in our `bin/office`:
+
+- **A host name → address table** (`nixos-desktop`/`.13` → `192.168.20.13`, and so on), because the old version broke on names ssh could not resolve.
+- **A check whether the named host is this machine**, before any ssh. I hit exactly that trap tonight: `office --remote 192.168.20.13` from `.13` tried to log in to itself.
+- **An ssh probe** (`ssh -o BatchMode=yes <addr> true`) before doing anything remote, so a missing key says so instead of half-working.
+- **`bin/board --reset`** — closes every pane, waits until the session is empty, clears the workspace names, then builds. `--replace` alone can run out of workspace slots on a half-built session.
+
+One thing is *simpler* than the old design: it needed `tuios new --host …` plus `office … --host …`, because `office` could not create a session. Ours can, through the daemon's own verb. So it is one command.
+
+## The rule, in one table
+
+| Situation | Command |
+|---|---|
+| folder on this machine, shell on this machine | `bin/office <folder> --project "<Name>"` |
+| folder Paperclip has not seen yet | `bin/office <folder> --new "<Name>"` |
+| folder on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
+| repair / rebuild | `bin/board`, `bin/board --replace`, `bin/board --reset` |
+| start again from nothing | `bin/project-reset <folder>` |
+
+And the rule that removes the confusion: **the folder and the session live on the same machine.** If you are typing inside the session, on the machine that owns the folder, it is just `bin/office <folder>`. `--host` is only for the case where those two differ.
+
+Written into `docs/STARTUP.md`, committed as `7b2cccf` and pushed.
+
+## Your `email_agent` case, concretely
+
+The folder is on `.13`, the Paperclip project is **Email Agent** (`local_path`, so no worktree policy), and the session must live on `.13`. From `.27`:
+
+```sh
+bin/office /home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent
+```
+
+That runs the work on `.13` over ssh, creates the session there, and builds eight panes. Then `tuios attach --host nixos-desktop email-agent`. No program can move your client, so that last step is always yours.
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Concrete repo layout, host map, version state and script names from the turn.; enriched with final-answer detail because persistence should be reusable
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md

@@ -1068,3 +1068,33 @@ Committed as `9631cdd` and pushed.
 - session: [[packs/paperclip-harness/80-sessions/paperclip-tuios-sessions-across-hosts-initextra-initcontent-|Paperclip/TUIOS sessions across hosts, initExtra→initContent fix, and dry-runs]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-11-23-32-18|Rich discovery: home 2026-11-11 23:32:18]]
 - context: [[packs/paperclip-harness/20-context/home|home]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+Deliverable: updated /etc/nixos on .13 and .27 (flake.lock bumped to nixpkgs 2026-11-07; Pi home.nix option initExtra -> initContent), simplified `bin/office` and `bin/board` per docs/STARTUP-COMMANDS.md, and rewrote the rule into docs/STARTUP.md (committed 7b2cccf, pushed).
+
+bin/office improvements adopted: hostname->address table (nixos-desktop/.13 -> 192.168.20.13), local-host detection before any ssh, `ssh -o BatchMode=yes <addr> true` probe, and it can create sessions itself via `tuios new` (one command instead of two).
+
+bin/board gains `--reset`: close every pane, wait until session empty, clear workspace names, then rebuild (avoids running out of workspace slots on a half-built session).
+
+Validation: .13 dry-build passes (465 derivations, 5.5 GiB). .27 blocked by fontconfig eval error. .51 untouched.
+
+Follow-ups: run switch on .13; fix .27 (nixpkgs-only bump first); decide whether to align .51.
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Concrete completed work, commit id, validation and open follow-ups.
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li.md

@@ -433,3 +433,33 @@ Say go on 1 and I will run the project-docs pass before anything else.
 - action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Paperclip Harness: docs published to Outline, Obsidian note updated, repo pushed]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-link-2026-11-11-21-45-49|Rich discovery: link. 2026-11-11 21:45:49]]
 - context: [[packs/paperclip-harness/20-context/home|link.]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+Decision: `bin/office <folder>` is the default when the folder and the session are on the same machine, including when you are typing inside the session on that machine. `--host <host>` is used only when the folder lives on a different machine than where the session must run.
+
+Context: previous docs required `tuios new --host …` plus `office … --host …`, because `office` could not create a session; that plus ssh name resolution and self-ssh traps caused confusion.
+
+Rationale: our `bin/office` can now create sessions through the daemon's own verb, so one command suffices; a host name -> address table plus a BatchMode ssh probe and a 'is this me' check removes the common failure modes.
+
+Consequences: command table — local folder: `bin/office <folder> --project "<Name>"`; unseen folder: `--new "<Name>"`; remote folder: add `--host nixos-desktop`; repair: `bin/board` / `--replace` / `--reset`; full reset: `bin/project-reset <folder>`. Attaching is always a manual final step (`tuios attach --host <host> <session>`).
+
+Caveat: when done from .27 against an .13 folder, use `--host nixos-desktop --session <name>`, e.g. `/home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent` (local_path project, no worktree policy).
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Explicit convention with rationale, alternatives and command table.
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md

@@ -4302,3 +4302,118 @@ Committed as `9631cdd` and pushed.
 - session: [[packs/paperclip-harness/80-sessions/paperclip-tuios-sessions-across-hosts-initextra-initcontent-|Paperclip/TUIOS sessions across hosts, initExtra→initContent fix, and dry-runs]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-11-23-32-18|Rich discovery: home 2026-11-11 23:32:18]]
 - context: [[packs/paperclip-harness/20-context/home|home]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+As of this turn:
+
+- .13 (/etc/nixos changed): lock bumped to nixpkgs 2026-11-07 (from 2026-07-29), Pi initExtra -> initContent. Evaluates to pi 1.5.0; running 0.82.1. Dry-run build passes: 465 derivations to build, 1666 paths fetched (~5.5 GiB download, 17.8 GiB unpacked). Needs `sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop`.
+- .27: same two edits applied, but evaluation fails in home-manager fontconfig: `head values` at nixpkgs lib/attrsets.nix:1711 while evaluating `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings` / `10-hm-fonts.conf`. Suspected home-manager 2026-11-10 incompatibility; recommended next attempt is bumping nixpkgs only, leaving home-manager pinned, before touching font config.
+- .51: unchanged, pi 0.87.1 both evaluated and running; would need the same two edits to reach 1.5.0.
+
+Also emitted: deprecation warnings that xorg package set is deprecated and xorg.libXtst/libxshmfence renamed to libxtst/libxshmfence.
+
+## Evidence
+
+- Confidence: 85%
+- Reason: Factual state and a specific reproducible evaluation error, useful for future work.
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+## Structural/configuration observations (2026-11-12 00:35:25)
+
+You are right that I was inconsistent. Here is the exact state, then the simple rule for `office`.
+
+## What is applied, precisely
+
+| | `/etc/nixos` changed? | Evaluates to pi | Running pi | Needs |
+|---|---|---|---|---|
+| **`.13`** | **yes, now**: lock bumped to 2026-11-07, `initExtra` → `initContent` | **1.5.0** | 0.82.1 | one `sudo nixos-rebuild switch` |
+| **`.27`** | **yes, now**: same two edits | 1.5.0 | 0.82.1 | a fix first — see below |
+| **`.51`** | no | 0.87.1 | 0.87.1 | the same two edits, then rebuild |
+
+Earlier I said "applied" when I had only tested a copy in `/tmp`. That was wrong wording on my part: nothing had been written to `/etc/nixos`. It has been now, on `.13` and `.27`, and `.13`'s dry-run build passes with 465 derivations to build and 5.5 GiB to fetch.
+
+On `.13`, the rebuild is:
+
+```sh
+sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop
+```
+
+**`.27` cannot be rebuilt yet.** Its evaluation fails in home-manager's fontconfig code:
+
+```
+… while evaluating the option `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings':
+error: … head values (attrsets.nix:1711)
+```
+
+That is home-manager 2026-11-10 disagreeing with something in `.27`'s font configuration, not the Pi change. The smaller next attempt is to bump **nixpkgs only** on `.27` and leave home-manager where it is — I would try that before touching fonts.
+
+`.51` would need the same two edits to reach 1.5.0. Say whether you want `.51` aligned in the same pass, or left at 0.87.1 until `.13` is proven.
+
+## Your notes, adopted — and the commands simplified
+
+I read `docs/STARTUP-COMMANDS.md`. Four things from it are now in our `bin/office`:
+
+- **A host name → address table** (`nixos-desktop`/`.13` → `192.168.20.13`, and so on), because the old version broke on names ssh could not resolve.
+- **A check whether the named host is this machine**, before any ssh. I hit exactly that trap tonight: `office --remote 192.168.20.13` from `.13` tried to log in to itself.
+- **An ssh probe** (`ssh -o BatchMode=yes <addr> true`) before doing anything remote, so a missing key says so instead of half-working.
+- **`bin/board --reset`** — closes every pane, waits until the session is empty, clears the workspace names, then builds. `--replace` alone can run out of workspace slots on a half-built session.
+
+One thing is *simpler* than the old design: it needed `tuios new --host …` plus `office … --host …`, because `office` could not create a session. Ours can, through the daemon's own verb. So it is one command.
+
+## The rule, in one table
+
+| Situation | Command |
+|---|---|
+| folder on this machine, shell on this machine | `bin/office <folder> --project "<Name>"` |
+| folder Paperclip has not seen yet | `bin/office <folder> --new "<Name>"` |
+| folder on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
+| repair / rebuild | `bin/board`, `bin/board --replace`, `bin/board --reset` |
+| start again from nothing | `bin/project-reset <folder>` |
+
+And the rule that removes the confusion: **the folder and the session live on the same machine.** If you are typing inside the session, on the machine that owns the folder, it is just `bin/office <folder>`. `--host` is only for the case where those two differ.
+
+Written into `docs/STARTUP.md`, committed as `7b2cccf` and pushed.
+
+## Your `email_agent` case, concretely
+
+The folder is on `.13`, the Paperclip project is **Email Agent** (`local_path`, so no worktree policy), and the session must live on `.13`. From `.27`:
+
+```sh
+bin/office /home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent
+```
+
+That runs the work on `.13` over ssh, creates the session there, and builds eight panes. Then `tuios attach --host nixos-desktop email-agent`. No program can move your client, so that last step is always yours.
+
+## Source paths observed
+
+- `gitea.lab.audasmedia.com.au/sam/paperclip-harness.git`
+- `NixOS/nixpkgs/0954f7ee2f6bb3dc7d4e3d0d8bcb8fd4bde4cfc5`
+- `NixOS/nixpkgs/f4a03c008967841f2a0b3cb7c436fc6fc31671f6`
+- `home/sam/.config/fontconfig/conf.d/10-hm-fonts.conf`
+- `fontconfig/conf.d/10-hm-fonts.conf`
+- `etc/nixos/hosts/sam-4screen-desktop/configuration.nix`
+- `etc/nixos/hosts/sam-thinkpad/configuration.nix`
+- `home/sam/paseo/projects/email_agent`
+
+## Evidence
+
+- Confidence: 82%
+- Reason: Captured factual repo structure/configuration patterns from rich discovery
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/70-runbooks/tmp-deployment-operations.md

@@ -1335,3 +1335,104 @@ Caveat: `bin/office` dry runs create the TUIOS session and need manual kill (see
 - session: [[packs/paperclip-harness/80-sessions/paperclip-harness-new-existing-dry-runs-clean-test-plan-pi-v|paperclip-harness: --new/--existing dry runs, clean test plan, Pi version dry-run on .13/.27]]
 - session: [[packs/paperclip-harness/80-sessions/rich-discovery-root-2026-11-11-22-37-01|Rich discovery: root 2026-11-11 22:37:01]]
 - context: [[packs/paperclip-harness/20-context/paperclip-harness|root]]
+
+
+---
+
+## Update (2026-11-12 00:35:25)
+
+Trigger: applying config changes in /etc/nixos, or the .27 fontconfig evaluation failure.
+
+Prerequisites: ssh access by IP (BatchMode probe `ssh -o BatchMode=yes <addr> true`), sudo on target host.
+
+Steps (on .13, known good):
+1. Dry run to see scope: `sudo nixos-rebuild dry-build --flake /etc/nixos#nixos-desktop` (expected ~465 derivations / 5.5 GiB).
+2. Apply: `sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop`.
+3. Verify: check `pi --version` (evaluated vs running) after switch.
+
+Fix path for .27 (fontconfig eval error at `… fonts.fontconfig.configFile.fonts.settings`): bump nixpkgs only in flake.lock, keep home-manager pinned, re-evaluate; do NOT change font config first. If it still fails, inspect home-manager fontconfig settings against newer nixpkgs attrsets (nixpkgs lib/attrsets.nix head).
+
+Rollback: revert flake.lock and the initContent/initExtra edits in /etc/nixos (git tracked), then rebuild. Safe edits: home.nix Pi option name, flake.lock. Dangerous: font package removal, home-manager version bumps without testing.
+
+Troubleshooting: 'already applied' claims must be verified — only edits in /etc/nixos count; /tmp copies are not applied.
+
+## Detailed procedure from completed turn
+
+You are right that I was inconsistent. Here is the exact state, then the simple rule for `office`.
+
+## What is applied, precisely
+
+| | `/etc/nixos` changed? | Evaluates to pi | Running pi | Needs |
+|---|---|---|---|---|
+| **`.13`** | **yes, now**: lock bumped to 2026-11-07, `initExtra` → `initContent` | **1.5.0** | 0.82.1 | one `sudo nixos-rebuild switch` |
+| **`.27`** | **yes, now**: same two edits | 1.5.0 | 0.82.1 | a fix first — see below |
+| **`.51`** | no | 0.87.1 | 0.87.1 | the same two edits, then rebuild |
+
+Earlier I said "applied" when I had only tested a copy in `/tmp`. That was wrong wording on my part: nothing had been written to `/etc/nixos`. It has been now, on `.13` and `.27`, and `.13`'s dry-run build passes with 465 derivations to build and 5.5 GiB to fetch.
+
+On `.13`, the rebuild is:
+
+```sh
+sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop
+```
+
+**`.27` cannot be rebuilt yet.** Its evaluation fails in home-manager's fontconfig code:
+
+```
+… while evaluating the option `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings':
+error: … head values (attrsets.nix:1711)
+```
+
+That is home-manager 2026-11-10 disagreeing with something in `.27`'s font configuration, not the Pi change. The smaller next attempt is to bump **nixpkgs only** on `.27` and leave home-manager where it is — I would try that before touching fonts.
+
+`.51` would need the same two edits to reach 1.5.0. Say whether you want `.51` aligned in the same pass, or left at 0.87.1 until `.13` is proven.
+
+## Your notes, adopted — and the commands simplified
+
+I read `docs/STARTUP-COMMANDS.md`. Four things from it are now in our `bin/office`:
+
+- **A host name → address table** (`nixos-desktop`/`.13` → `192.168.20.13`, and so on), because the old version broke on names ssh could not resolve.
+- **A check whether the named host is this machine**, before any ssh. I hit exactly that trap tonight: `office --remote 192.168.20.13` from `.13` tried to log in to itself.
+- **An ssh probe** (`ssh -o BatchMode=yes <addr> true`) before doing anything remote, so a missing key says so instead of half-working.
+- **`bin/board --reset`** — closes every pane, waits until the session is empty, clears the workspace names, then builds. `--replace` alone can run out of workspace slots on a half-built session.
+
+One thing is *simpler* than the old design: it needed `tuios new --host …` plus `office … --host …`, because `office` could not create a session. Ours can, through the daemon's own verb. So it is one command.
+
+## The rule, in one table
+
+| Situation | Command |
+|---|---|
+| folder on this machine, shell on this machine | `bin/office <folder> --project "<Name>"` |
+| folder Paperclip has not seen yet | `bin/office <folder> --new "<Name>"` |
+| folder on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
+| repair / rebuild | `bin/board`, `bin/board --replace`, `bin/board --reset` |
+| start again from nothing | `bin/project-reset <folder>` |
+
+And the rule that removes the confusion: **the folder and the session live on the same machine.** If you are typing inside the session, on the machine that owns the folder, it is just `bin/office <folder>`. `--host` is only for the case where those two differ.
+
+Written into `docs/STARTUP.md`, committed as `7b2cccf` and pushed.
+
+## Your `email_agent` case, concretely
+
+The folder is on `.13`, the Paperclip project is **Email Agent** (`local_path`, so no worktree policy), and the session must live on `.13`. From `.27`:
+
+```sh
+bin/office /home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent
+```
+
+That runs the work on `.13` over ssh, creates the session there, and builds eight panes. Then `tuios attach --host nixos-desktop email-agent`. No program can move your client, so that last step is always yours.
+
+## Evidence
+
+- Confidence: 80%
+- Reason: Repeatable procedure with commands, failure handling and a validation caveat.; enriched with final-answer detail because persistence should be reusable
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25.md

@@ -0,0 +1,116 @@
+---
+type: session
+id: session.paperclip-harness.rich-discovery-home-2026-11-12-00-35-25
+title: Rich discovery: home 2026-11-12 00:35:25
+status: active
+source_of_truth: false
+freshness: current
+last_reviewed: 2026-11-12
+tags:
+  - pack/paperclip-harness
+  - agent-memory/session
+  - autolearn
+  - rich-discovery
+  - repo/home
+---
+
+# Rich discovery: home 2026-11-12 00:35:25
+
+Sanitized rich discovery snapshot captured automatically from the completed turn.
+
+
+## Source paths observed
+
+- `gitea.lab.audasmedia.com.au/sam/paperclip-harness.git`
+- `NixOS/nixpkgs/0954f7ee2f6bb3dc7d4e3d0d8bcb8fd4bde4cfc5`
+- `NixOS/nixpkgs/f4a03c008967841f2a0b3cb7c436fc6fc31671f6`
+- `home/sam/.config/fontconfig/conf.d/10-hm-fonts.conf`
+- `fontconfig/conf.d/10-hm-fonts.conf`
+- `etc/nixos/hosts/sam-4screen-desktop/configuration.nix`
+- `etc/nixos/hosts/sam-thinkpad/configuration.nix`
+- `home/sam/paseo/projects/email_agent`
+
+## Final answer snapshot
+
+You are right that I was inconsistent. Here is the exact state, then the simple rule for `office`.
+
+## What is applied, precisely
+
+| | `/etc/nixos` changed? | Evaluates to pi | Running pi | Needs |
+|---|---|---|---|---|
+| **`.13`** | **yes, now**: lock bumped to 2026-11-07, `initExtra` → `initContent` | **1.5.0** | 0.82.1 | one `sudo nixos-rebuild switch` |
+| **`.27`** | **yes, now**: same two edits | 1.5.0 | 0.82.1 | a fix first — see below |
+| **`.51`** | no | 0.87.1 | 0.87.1 | the same two edits, then rebuild |
+
+Earlier I said "applied" when I had only tested a copy in `/tmp`. That was wrong wording on my part: nothing had been written to `/etc/nixos`. It has been now, on `.13` and `.27`, and `.13`'s dry-run build passes with 465 derivations to build and 5.5 GiB to fetch.
+
+On `.13`, the rebuild is:
+
+```sh
+sudo nixos-rebuild switch --flake /etc/nixos#nixos-desktop
+```
+
+**`.27` cannot be rebuilt yet.** Its evaluation fails in home-manager's fontconfig code:
+
+```
+… while evaluating the option `home-manager.users.sam.fonts.fontconfig.configFile.fonts.settings':
+error: … head values (attrsets.nix:1711)
+```
+
+That is home-manager 2026-11-10 disagreeing with something in `.27`'s font configuration, not the Pi change. The smaller next attempt is to bump **nixpkgs only** on `.27` and leave home-manager where it is — I would try that before touching fonts.
+
+`.51` would need the same two edits to reach 1.5.0. Say whether you want `.51` aligned in the same pass, or left at 0.87.1 until `.13` is proven.
+
+## Your notes, adopted — and the commands simplified
+
+I read `docs/STARTUP-COMMANDS.md`. Four things from it are now in our `bin/office`:
+
+- **A host name → address table** (`nixos-desktop`/`.13` → `192.168.20.13`, and so on), because the old version broke on names ssh could not resolve.
+- **A check whether the named host is this machine**, before any ssh. I hit exactly that trap tonight: `office --remote 192.168.20.13` from `.13` tried to log in to itself.
+- **An ssh probe** (`ssh -o BatchMode=yes <addr> true`) before doing anything remote, so a missing key says so instead of half-working.
+- **`bin/board --reset`** — closes every pane, waits until the session is empty, clears the workspace names, then builds. `--replace` alone can run out of workspace slots on a half-built session.
+
+One thing is *simpler* than the old design: it needed `tuios new --host …` plus `office … --host …`, because `office` could not create a session. Ours can, through the daemon's own verb. So it is one command.
+
+## The rule, in one table
+
+| Situation | Command |
+|---|---|
+| folder on this machine, shell on this machine | `bin/office <folder> --project "<Name>"` |
+| folder Paperclip has not seen yet | `bin/office <folder> --new "<Name>"` |
+| folder on another machine | `bin/office <folder> --project "<Name>" --host nixos-desktop` |
+| repair / rebuild | `bin/board`, `bin/board --replace`, `bin/board --reset` |
+| start again from nothing | `bin/project-reset <folder>` |
+
+And the rule that removes the confusion: **the folder and the session live on the same machine.** If you are typing inside the session, on the machine that owns the folder, it is just `bin/office <folder>`. `--host` is only for the case where those two differ.
+
+Written into `docs/STARTUP.md`, committed as `7b2cccf` and pushed.
+
+## Your `email_agent` case, concretely
+
+The folder is on `.13`, the Paperclip project is **Email Agent** (`local_path`, so no worktree policy), and the session must live on `.13`. From `.27`:
+
+```sh
+bin/office /home/sam/paseo/projects/email_agent --project "Email Agent" --host nixos-desktop --session email-agent
+```
+
+That runs the work on `.13` over ssh, creates the session there, and builds eight panes. Then `tuios attach --host nixos-desktop email-agent`. No program can move your client, so that last step is always yours.
+
+## Evidence
+
+- Confidence: 86%
+- Reason: Preserve full sanitized discovery detail from a rich investigation turn
+
+## Related
+
+- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
+
+## Related learned memories <!-- same-turn-2026-11-12 00:35:25 -->
+
+- context: [[packs/paperclip-harness/20-context/tmp|NixOS /etc/nixos flake: hosts, Pi CLI versions, office workflow]]
+- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|NixOS fleet: Pi CLI version state and .27 fontconfig evaluation failure]]
+- runbook: [[packs/paperclip-harness/70-runbooks/tmp-deployment-operations|Rebuild/switch a NixOS host and fix home-manager fontconfig eval error]]
+- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Pi 1.5.0 edits in /etc/nixos, simplified office/board scripts, docs/STARTUP.md]]
+- decision: [[packs/paperclip-harness/50-decisions/paperclip-harness-ui-six-workspaces-spec-first-four-panel-li|Convention: folder and session must live on the same machine; --host only when they differ]]
+- session: [[packs/paperclip-harness/80-sessions/rich-discovery-home-2026-11-12-00-35-25|Rich discovery: home 2026-11-12 00:35:25]]
+- context: [[packs/paperclip-harness/20-context/home|home]]

bin/office

@@ -236,8 +236,26 @@ def run_on_remote(host, folder, opts):
     return 0
 
 
+USAGE = """office — open a folder as a project
+
+  office <folder> --project "<Name>"        adopt a project Paperclip already has
+  office <folder> --new "<Name>"            create the Paperclip project too
+  office <folder> --project "<Name>" --host nixos-desktop    the folder is on that machine
+  office <folder> --dry                     say what would happen, write nothing
+
+The folder and the session live on the same machine. If you are typing inside the
+session, on the machine that owns the folder, it is just: office <folder>.
+"""
+
+
 def main():
-    opts = parse(sys.argv[1:])
+    argv = sys.argv[1:]
+    if not argv or "-h" in argv or "--help" in argv:
+        h.say(USAGE.strip())
+        return 0
+    opts = parse(argv)
+    if opts["folder"] in ("", "."):
+        raise h.Refused(2, "give the folder: office <folder> --project \"<Name>\"  (office --help)")
     folder = os.path.abspath(os.path.expanduser(opts["folder"]))
     if not os.path.isdir(folder):
         raise h.Refused(2, "no folder at %s" % folder)
@@ -277,9 +295,6 @@ def main():
         h.say("dry run: nothing was written")
         return 0
 
-    if not opts["no_switch"]:
-        ensure_session(session, folder)
-
     if opts["host"] and opts["host"] not in (pj.this_machine(), pj.this_machine().split(".")[0]):
         # Only a note, because the panes are built by the machine that owns them.
         h.say("host: %s (build the pages there)" % host)
@@ -323,6 +338,9 @@ def main():
     pj.save(folder, cfg)
     h.say("wrote   %s" % pj.path(folder))
 
+    if not opts["no_switch"]:
+        ensure_session(session, folder)
+
     pj.register(cfg, proj["name"])
     h.say("recorded in %s" % pj.REGISTRY)
 

docs/STARTUP.md

@@ -1,4 +1,10 @@
-# Starting a project: the three commands and the rule
+# Starting a project: the commands and the rule
+
+These commands are on your `PATH` as `office`, `board`, `merge`, `review`, `triage` and
+`project-reset`. Each is a two-line wrapper in `~/.local/bin` that runs the real script in this
+repository — a wrapper, not a symlink, because a symlinked script resolves its own directory to
+`~/.local/bin` and then cannot find its siblings. The previous project's wrappers were moved to
+`~/.local/bin/.old-harness/`, not deleted.
 
 Replaces the previous project's four commands. There are three now, and one rule that removes
 most of the confusion.