sam/paperclip-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Sam
2026-11-12 12:10:57 +11:00
parent 7b2cccf2ff
commit a129c4e0c3
9 changed files with 616 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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]]

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

@@ -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]]

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

@@ -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]]

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

@@ -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]]

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

@@ -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]]

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

@@ -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]]

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

@@ -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]]

26
bin/office
View File

@@ -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)

8
docs/STARTUP.md
View File

@@ -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.