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

Interface specification: six workspaces, twenty-seven interface items, styling and keys

Browse Source
This commit is contained in:
Sam
2026-11-10 13:04:05 +11:00
parent ae7fc00e5b
commit b44bf73713
10 changed files with 980 additions and 140 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
.pi/memory-vault/packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec.md Normal file
View File

@@ -0,0 +1,93 @@
---
type: context
id: context.paperclip-harness.docs-ui-layout-md-interface-spec
title: docs/UI-LAYOUT.md interface spec
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/context
- paperclip-harness
- ui-layout
- spec
- docs
---
# docs/UI-LAYOUT.md interface spec
New spec at /home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md (9942 bytes) written this turn. Structure:
1. Opens with the only four questions the UI may answer: what is the state of the work, what is happening now, what needs me, what do I do about it.
2. Fact-ownership table pinning each shown fact to one source (see the paperclip-harness context note for the full mapping).
3. Per-pane tables: what each pane must show and which keys it may use. TUIOS keeps `h j k l z n`; bare Esc stays free.
4. Three candidate layouts (A one-page-per-view, B cockpit tree+thread, C cockpit with diff) plus a width-driven recommendation: C at 150+ columns, B at 110–149, A at 80–109, 'too small' screen below 80x24.
Open decisions recorded in the doc/conversation: (1) diff as its own pane vs bottom half of the log; (2) whether tree selection drives other panes by writing `watching = AUD-163` into `.harness/harness.toml` (panes watch the file) vs direct pane messages; (3) whether the four screens stay four workspaces or collapse to two.
## Detailed context from completed turn
That notification is the failed Explore agent finishing late — the one that returned nothing because `claude-haiku-4.5` 404s. Nothing new in it; I did that reading myself.
Meanwhile I did what you asked next: the interface spec and the mockups.
## `docs/UI-LAYOUT.md`
It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:
| shown | read from | never |
|---|---|---|
| tasks, status, assignee | company issue list | a folder name |
| blockers | `issues/{id}/diagnostics/blockers`, per task | the list |
| thread | `issues/{id}/comments` | a copy |
| run state | `issues/{id}/runs` | a log we write |
| cost | `issues/{id}/cost-summary` | our arithmetic |
| what changed | `git` in the task's worktree | a stored diff |
| folder, machine, session, watched task | `.harness/harness.toml` | Paperclip |
Then a table per pane: what it must show and which keys it may use, with `h j k l z n` reserved for TUIOS and a bare Esc free.
## Three layouts, live in your session
They are running now on workspaces 6, 7, 8 (`mock-A`, `mock-B`, `mock-C`), and as images:
```
/tmp/mockups/A.png /tmp/mockups/B.png /tmp/mockups/C.png
```
- **A — one page each.** What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
- **B — cockpit: tree beside conversation.** Tree 34% left, thread and reply box right, `⤷` markers under each task showing what it waits on. Log and diff one workspace away.
- **C — cockpit with the change visible.** Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.
Recommendation in the doc: **C, falling back to B, falling back to A, chosen by the pane's actual width** — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.
## Two decisions I need from you
1. **Is the diff its own pane, or the bottom half of the log?** A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
2. **Does the tree drive the other panes?** My proposal: `enter` on a task writes `watching = AUD-163` into the project's `harness.toml` and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.
Also still open from earlier: whether the four screens stay four workspaces or become two.
Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.
## Evidence
- Confidence: 85%
- Reason: Key deliverable and its design decisions, reusable by future work on the UI.; enriched with final-answer detail because persistence should be reusable
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

53
.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md Normal file
View File

@@ -0,0 +1,53 @@
---
type: context
id: context.paperclip-harness.paperclip-harness
title: paperclip-harness
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/context
- paperclip-harness
- tuios
- tml
- architecture
- ui-layout
---
# paperclip-harness
Repo root: /home/sam/paseo/projects/paperclip-harness (pack label 'paperclip-harness'), running inside a TUIOS session ('tuios coding harness' / π window) so windows/workspaces are addressable by name or index.
Top-level contents: AGENTS.md, bin/, CHECKLIST.md, docs/, HANDOVER.md, README.md, tui/, plus the workspace layout (shell, tree, reply, log, new, and mock-A/mock-B/mock-C mockups).
Architecture/config rules discovered:
- Rendering: TML documents (root `<tml version="1" title="...">`, optional first-child `<state>{JSON}</state>`), rendered by tuios in a popup or pane using the user's theme. Rules documented in the repo: roles not hex colours (fg, dim, mute, accent, success, warning, error, info, series1–6; hex refused); bindings read state (`{state.passed}`, `{pct(...)}`) with no loops/assignment; data attributes take state paths without braces (`rows="state.services"`); actions `set/toggle/emit/close/copy/pane(...)`; limits 256 KiB from a pane, 5,000 nodes, depth 32, state 1 MiB, patch 64 KiB, 8 open surfaces per pane. Expressions have no object literals, so action params live in state (e.g. state.run = {"window":"build","text":"make\n"}).
- Data ownership (from the new spec): tasks/status/assignee from the company issue list (never a folder name); blockers from `issues/{id}/diagnostics/blockers` per task; thread from `issues/{id}/comments`; run state from `issues/{id}/runs`; cost from `issues/{id}/cost-summary` (never our arithmetic); what-changed from `git` in the task's worktree (never a stored diff); folder/machine/session/watched task from `.harness/harness.toml` (never Paperclip).
- Key ownership in panes: `h j k l z n` are reserved for TUIOS; a bare Esc must stay free.
Known environment caveats: some sessions have no display, so screenshots fail with 'no window found' and clipboard writes report 'no clipboard' but the file is saved; windows in this harness are 88x26 by default.
Related: the Explore subagent configured with `claude-haiku-4.5` 404s and returns nothing — do that reading directly.
## Evidence
- Confidence: 85%
- Reason: Durable repo overview and rendering/config conventions evidenced across the turn.
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

94
.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md Normal file
View File

@@ -0,0 +1,94 @@
---
type: context
id: context.paperclip-harness.tmp
title: tmp
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/context
- autolearn
- rich-discovery
- repo/tmp
---
# tmp
## Rich discovery update (2026-11-10 01:47:01)
That notification is the failed Explore agent finishing late — the one that returned nothing because `claude-haiku-4.5` 404s. Nothing new in it; I did that reading myself.
Meanwhile I did what you asked next: the interface spec and the mockups.
## `docs/UI-LAYOUT.md`
It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:
| shown | read from | never |
|---|---|---|
| tasks, status, assignee | company issue list | a folder name |
| blockers | `issues/{id}/diagnostics/blockers`, per task | the list |
| thread | `issues/{id}/comments` | a copy |
| run state | `issues/{id}/runs` | a log we write |
| cost | `issues/{id}/cost-summary` | our arithmetic |
| what changed | `git` in the task's worktree | a stored diff |
| folder, machine, session, watched task | `.harness/harness.toml` | Paperclip |
Then a table per pane: what it must show and which keys it may use, with `h j k l z n` reserved for TUIOS and a bare Esc free.
## Three layouts, live in your session
They are running now on workspaces 6, 7, 8 (`mock-A`, `mock-B`, `mock-C`), and as images:
```
/tmp/mockups/A.png /tmp/mockups/B.png /tmp/mockups/C.png
```
- **A — one page each.** What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
- **B — cockpit: tree beside conversation.** Tree 34% left, thread and reply box right, `⤷` markers under each task showing what it waits on. Log and diff one workspace away.
- **C — cockpit with the change visible.** Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.
Recommendation in the doc: **C, falling back to B, falling back to A, chosen by the pane's actual width** — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.
## Two decisions I need from you
1. **Is the diff its own pane, or the bottom half of the log?** A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
2. **Does the tree drive the other panes?** My proposal: `enter` on a task writes `watching = AUD-163` into the project's `harness.toml` and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.
Also still open from earlier: whether the four screens stay four workspaces or become two.
Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.
## Source paths observed
- `tmp/pi-subagents-1000/home-sam-paseo-projects-paperclip-harness/01a1c288-74f9-75ae-ba9a-a501d66bc3b5/tasks/87e640dd-8043-41e.output`
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
- `tmp/mockups/A.txt`
- `tmp/mockups/B.txt`
- `tmp/mockups/C.txt`
- `tmp/mockups/A.png`
- `tmp/mockups/B.png`
- `tmp/mockups/C.png`
## Evidence
- Confidence: 84%
- Reason: Update component/repository context with detailed discovered structure and configuration
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

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

@@ -0,0 +1,90 @@
---
type: action
id: action.paperclip-harness.wrote-docs-ui-layout-md-and-three-live-layout-mockups
title: Wrote docs/UI-LAYOUT.md and three live layout mockups
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/action
- ui-layout
- deliverable
- mockups
- commit
---
# Wrote docs/UI-LAYOUT.md and three live layout mockups
Completed work this turn:
- Deliverable: /home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md (9942 bytes) — four allowed user questions, fact-ownership table, per-pane show/keys spec, three layouts, width-driven recommendation.
- Artifacts: three mockups run live as TUIOS workspaces 6/7/8 (mock-A, mock-B, mock-C) and captured as /tmp/mockups/{A,B,C}.txt and .png.
- Validation: text renderings measured (A 16x81, B 20x82, C 15x82) and inspected; each workspace confirmed at 88x26 via tuios list-workspaces. Committed as ae7fc00 ('Interface spec: what each page must show, the source of every fact, and three layouts').
- Follow-up: awaiting user choice of layout and answers on diff-pane placement, tree-driven pane hand-off, and workspace count; build starts with the width-driven chooser.
## Detailed deliverable from completed turn
That notification is the failed Explore agent finishing late — the one that returned nothing because `claude-haiku-4.5` 404s. Nothing new in it; I did that reading myself.
Meanwhile I did what you asked next: the interface spec and the mockups.
## `docs/UI-LAYOUT.md`
It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:
| shown | read from | never |
|---|---|---|
| tasks, status, assignee | company issue list | a folder name |
| blockers | `issues/{id}/diagnostics/blockers`, per task | the list |
| thread | `issues/{id}/comments` | a copy |
| run state | `issues/{id}/runs` | a log we write |
| cost | `issues/{id}/cost-summary` | our arithmetic |
| what changed | `git` in the task's worktree | a stored diff |
| folder, machine, session, watched task | `.harness/harness.toml` | Paperclip |
Then a table per pane: what it must show and which keys it may use, with `h j k l z n` reserved for TUIOS and a bare Esc free.
## Three layouts, live in your session
They are running now on workspaces 6, 7, 8 (`mock-A`, `mock-B`, `mock-C`), and as images:
```
/tmp/mockups/A.png /tmp/mockups/B.png /tmp/mockups/C.png
```
- **A — one page each.** What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
- **B — cockpit: tree beside conversation.** Tree 34% left, thread and reply box right, `⤷` markers under each task showing what it waits on. Log and diff one workspace away.
- **C — cockpit with the change visible.** Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.
Recommendation in the doc: **C, falling back to B, falling back to A, chosen by the pane's actual width** — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.
## Two decisions I need from you
1. **Is the diff its own pane, or the bottom half of the log?** A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
2. **Does the tree drive the other panes?** My proposal: `enter` on a task writes `watching = AUD-163` into the project's `harness.toml` and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.
Also still open from earlier: whether the four screens stay four workspaces or become two.
Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.
## Evidence
- Confidence: 85%
- Reason: Concrete deliverable, artifacts, commit, and follow-up context.; enriched with final-answer detail because persistence should be reusable
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

47
.pi/memory-vault/packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a.md Normal file
View File

@@ -0,0 +1,47 @@
---
type: decision
id: decision.paperclip-harness.responsive-layout-selection-by-pane-width-c-b-a
title: Responsive layout selection by pane width (C→B→A)
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/decision
- ui-layout
- responsive
- decision
- paperclip-harness
---
# Responsive layout selection by pane width (C→B→A)
Decision: pick the UI layout from the pane's actual width rather than fixing one. Order: layout C (cockpit with visible diff) at 150+ columns, layout B (tree beside thread) at 110–149, layout A (one page per view) at 80–109, and a dedicated 'too small' screen below 80x24.
Context: three layouts were mocked up (A one-page, B cockpit, C cockpit-with-diff). C gives a claim and the code behind it in one glance but needs width; below ~120 columns the diff half is unreadable. A works at 80 columns but costs a keystroke to see the tree while replying.
Rationale: give the person as much as the terminal can carry, never a layout pretending to have room it does not. Consequence: first build step is the width-driven chooser.
Open caveats: diff as separate pane vs bottom of log (C depends on diff sharing a page with reply); whether tree selection writes `watching` into harness.toml to drive other panes vs direct messaging; four workspaces vs two.
## Evidence
- Confidence: 85%
- Reason: Explicit architectural choice with rationale, consequences, alternatives, and open caveats.
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

46
.pi/memory-vault/packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow.md Normal file
View File

@@ -0,0 +1,46 @@
---
type: observation
id: observation.paperclip-harness.mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow
title: Mockup layouts A/B/C measured widths and screenshot workflow
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/observation
- tuios
- mockups
- screenshots
- caveats
---
# Mockup layouts A/B/C measured widths and screenshot workflow
Three layout mockups were rendered as text and images:
- /tmp/mockups/A.txt (16 lines, 81 wide), B.txt (20 lines, 82 wide), C.txt (15 lines, 82 wide); images A.png 145K, B.png 171K, C.png 160K (mode 600).
- They also run live as TUIOS workspaces 6/7/8 named mock-A/mock-B/mock-C (each 88x26 alongside shell, tree, reply, log, new).
- C's diff half is unreadable below ~120 columns per the doc, which is why the width-driven fallback exists.
Screenshot/clipboard caveats in this harness: 'tuios screenshot' with a wrong window name fails with 'no window found matching ...', listing available windows (Yazi panes and π windows) and offering 'tuios list-windows -s <session>'; repeated clipboard writes in a display-less session print 'This session has no display, so it has no clipboard' yet still save the file. 'tuios list-workspaces' output format: ` ws <n> '<name>'`; a sizing pass showed all 8 workspaces at 88x26.
## Evidence
- Confidence: 80%
- Reason: Concrete environment and artifact facts useful for future UI work and debugging.
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

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

@@ -0,0 +1,94 @@
---
type: observation
id: observation.paperclip-harness.tmp-repository-structure-and-configuration-patterns
title: tmp repository structure and configuration patterns
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/observation
- autolearn
- rich-discovery
- repo/tmp
---
# tmp repository structure and configuration patterns
## Structural/configuration observations (2026-11-10 01:47:01)
That notification is the failed Explore agent finishing late — the one that returned nothing because `claude-haiku-4.5` 404s. Nothing new in it; I did that reading myself.
Meanwhile I did what you asked next: the interface spec and the mockups.
## `docs/UI-LAYOUT.md`
It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:
| shown | read from | never |
|---|---|---|
| tasks, status, assignee | company issue list | a folder name |
| blockers | `issues/{id}/diagnostics/blockers`, per task | the list |
| thread | `issues/{id}/comments` | a copy |
| run state | `issues/{id}/runs` | a log we write |
| cost | `issues/{id}/cost-summary` | our arithmetic |
| what changed | `git` in the task's worktree | a stored diff |
| folder, machine, session, watched task | `.harness/harness.toml` | Paperclip |
Then a table per pane: what it must show and which keys it may use, with `h j k l z n` reserved for TUIOS and a bare Esc free.
## Three layouts, live in your session
They are running now on workspaces 6, 7, 8 (`mock-A`, `mock-B`, `mock-C`), and as images:
```
/tmp/mockups/A.png /tmp/mockups/B.png /tmp/mockups/C.png
```
- **A — one page each.** What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
- **B — cockpit: tree beside conversation.** Tree 34% left, thread and reply box right, `⤷` markers under each task showing what it waits on. Log and diff one workspace away.
- **C — cockpit with the change visible.** Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.
Recommendation in the doc: **C, falling back to B, falling back to A, chosen by the pane's actual width** — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.
## Two decisions I need from you
1. **Is the diff its own pane, or the bottom half of the log?** A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
2. **Does the tree drive the other panes?** My proposal: `enter` on a task writes `watching = AUD-163` into the project's `harness.toml` and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.
Also still open from earlier: whether the four screens stay four workspaces or become two.
Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.
## Source paths observed
- `tmp/pi-subagents-1000/home-sam-paseo-projects-paperclip-harness/01a1c288-74f9-75ae-ba9a-a501d66bc3b5/tasks/87e640dd-8043-41e.output`
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
- `tmp/mockups/A.txt`
- `tmp/mockups/B.txt`
- `tmp/mockups/C.txt`
- `tmp/mockups/A.png`
- `tmp/mockups/B.png`
- `tmp/mockups/C.png`
## Evidence
- Confidence: 82%
- Reason: Captured factual repo structure/configuration patterns from rich discovery
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

97
.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01.md Normal file
View File

@@ -0,0 +1,97 @@
---
type: session
id: session.paperclip-harness.rich-discovery-tmp-2026-11-10-01-47-01
title: Rich discovery: tmp 2026-11-10 01:47:01
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/session
- autolearn
- rich-discovery
- repo/tmp
---
# Rich discovery: tmp 2026-11-10 01:47:01
Sanitized rich discovery snapshot captured automatically from the completed turn.
## Source paths observed
- `tmp/pi-subagents-1000/home-sam-paseo-projects-paperclip-harness/01a1c288-74f9-75ae-ba9a-a501d66bc3b5/tasks/87e640dd-8043-41e.output`
- `home/sam/paseo/projects/paperclip-harness/docs/UI-LAYOUT.md`
- `tmp/mockups/A.txt`
- `tmp/mockups/B.txt`
- `tmp/mockups/C.txt`
- `tmp/mockups/A.png`
- `tmp/mockups/B.png`
- `tmp/mockups/C.png`
## Final answer snapshot
That notification is the failed Explore agent finishing late — the one that returned nothing because `claude-haiku-4.5` 404s. Nothing new in it; I did that reading myself.
Meanwhile I did what you asked next: the interface spec and the mockups.
## `docs/UI-LAYOUT.md`
It opens with the only four questions the interface is allowed to answer — what is the state of the work, what is happening now, what needs me, what do I do about it — then a table pinning every fact to its one owner:
| shown | read from | never |
|---|---|---|
| tasks, status, assignee | company issue list | a folder name |
| blockers | `issues/{id}/diagnostics/blockers`, per task | the list |
| thread | `issues/{id}/comments` | a copy |
| run state | `issues/{id}/runs` | a log we write |
| cost | `issues/{id}/cost-summary` | our arithmetic |
| what changed | `git` in the task's worktree | a stored diff |
| folder, machine, session, watched task | `.harness/harness.toml` | Paperclip |
Then a table per pane: what it must show and which keys it may use, with `h j k l z n` reserved for TUIOS and a bare Esc free.
## Three layouts, live in your session
They are running now on workspaces 6, 7, 8 (`mock-A`, `mock-B`, `mock-C`), and as images:
```
/tmp/mockups/A.png /tmp/mockups/B.png /tmp/mockups/C.png
```
- **A — one page each.** What exists today. Whole width per page, works at 80 columns. Costs a keystroke to look at the tree while replying.
- **B — cockpit: tree beside conversation.** Tree 34% left, thread and reply box right, `⤷` markers under each task showing what it waits on. Log and diff one workspace away.
- **C — cockpit with the change visible.** Tree 28%, thread top right, diff bottom right — a claim and the code behind it in one glance. Needs width; below ~120 columns the diff half is unreadable.
Recommendation in the doc: **C, falling back to B, falling back to A, chosen by the pane's actual width** — 150+, 110–149, 80–109, and the "too small" screen below 80×24. The person gets as much as the terminal can carry, never a layout pretending to have room it does not.
## Two decisions I need from you
1. **Is the diff its own pane, or the bottom half of the log?** A separate pane never squeezes the log for a long diff, but costs a workspace. C only works if the diff can share a page with the reply.
2. **Does the tree drive the other panes?** My proposal: `enter` on a task writes `watching = AUD-163` into the project's `harness.toml` and asks TUIOS to switch to the reply page; the reply, log and diff panes watch that file and reload when it changes. One fact, one owner, no message bus — but it means a file is the hand-off, so say if you would rather each pane be told directly.
Also still open from earlier: whether the four screens stay four workspaces or become two.
Say which layout you want, and I will build it — starting with the width-driven choice, since that is what makes it survive being used in a small pane.
## 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-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

46
.pi/memory-vault/packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot.md Normal file
View File

@@ -0,0 +1,46 @@
---
type: session
id: session.paperclip-harness.ui-interface-spec-and-mockup-session-snapshot
title: UI interface spec and mockup session snapshot
status: active
source_of_truth: false
freshness: current
last_reviewed: 2026-11-10
tags:
- pack/paperclip-harness
- agent-memory/session
- session
- paperclip-harness
- ui-layout
- tuios
---
# UI interface spec and mockup session snapshot
Rich discovery/planning session for paperclip-harness UI:
- Read TML surface rules (roles not hex, state bindings, action set, size limits 256 KiB/5,000 nodes/depth 32/1 MiB state/64 KiB patch/8 surfaces per pane).
- Authored docs/UI-LAYOUT.md tying every displayed fact to one owner (issue list, blockers, comments, runs, cost-summary, git worktree, .harness/harness.toml).
- Built and verified three layouts A/B/C as text, PNG, and live TUIOS workspaces mock-A/B/C at 88x26; recommended width-driven C→B→A with a sub-80x24 'too small' screen.
- Environment notes: display-less sessions block screenshots and clipboard; Explore subagent on claude-haiku-4.5 404s.
- Outstanding: user must pick layout and resolve diff-pane placement, harness.toml watch-file hand-off, and 4-vs-2 workspaces.
## Evidence
- Confidence: 80%
- Reason: Sanitized snapshot of a rich discovery/planning turn with durable details.
## Related
- [[packs/paperclip-harness/00-system/pi-agent/memory-manifest|Memory Manifest]]
## Related learned memories <!-- same-turn-2026-11-10 01:47:01 -->
- context: [[packs/paperclip-harness/20-context/paperclip-harness|paperclip-harness]]
- context: [[packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec|docs/UI-LAYOUT.md interface spec]]
- observation: [[packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow|Mockup layouts A/B/C measured widths and screenshot workflow]]
- decision: [[packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a|Responsive layout selection by pane width (C→B→A)]]
- action: [[packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups|Wrote docs/UI-LAYOUT.md and three live layout mockups]]
- session: [[packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot|UI interface spec and mockup session snapshot]]
- session: [[packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01|Rich discovery: tmp 2026-11-10 01:47:01]]
- context: [[packs/paperclip-harness/20-context/tmp|tmp]]
- observation: [[packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns|tmp repository structure and configuration patterns]]

460
docs/UI-LAYOUT.md
View File

@@ -1,168 +1,348 @@
# What the interface must show, and three layouts to choose from # The interface: what we need, how it is grouped, and how it is drawn
Written 2026-11-10. This is the design document the screens are built against. It says Written 2026-11-10. This replaces the earlier layout note: it is now the one document that
what each page must show, where every fact comes from, what the keys are, and then three says what the interface contains. Layout comes after this, and is chosen from it.
layouts at three different shapes. Nothing here is decoration: each line exists because a
person needs it to make a decision or to know what is happening.
## The four questions the interface answers Plain English throughout. No invented shorthand. If a word here is not obvious, it is
defined in "Words we use".
1. **What is the state of the work?** todo, in progress, blocked, done — for one project. ---
2. **What is happening right now?** the run, what the agent changed, what it cost.
3. **What needs me?** blocked tasks, a merge that was refused, a task waiting for a person.
4. **What do I do about it?** reply, unblock, assign, create, merge.
Anything that does not answer one of those four is not on a screen. ## Words we use
## Where each fact comes from - **Workspace** — one page in TUIOS. The person switches between workspaces.
- **Panel** — one pane inside a workspace. Each panel is a program, or one area of one
program, that holds one kind of content.
- **View** — a way of looking at a panel, for example "the task tree" or "the diff". A
panel can hold several views and show one at a time.
- **Focus** — which panel receives the keys. Exactly one panel has focus at a time, and
the person can always see which one.
- **Fact** — a piece of truth with exactly one owner. Tasks, blockers, comments, runs,
costs and worktrees belong to Paperclip.
One owner per fact. The middle column is the only place the interface may read it. A workspace holds at most **four** panels. More than four cannot be read at a glance on
one screen, so a fifth thing to look at becomes a view inside a panel, or a new workspace.
| What is shown | Read from | Never | ---
## How things are grouped
The grouping is by what the person is doing, not by which system the data came from. There
are four things a person does with this factory:
1. **Decide and direct.** What is the state of the work, what is blocked, what is waiting
on me, what do I do next.
2. **Watch.** What is an agent doing right now, what has it changed, what has it cost.
3. **Talk.** Answer an agent, correct it mid-task, unblock a task with words.
4. **Author and govern.** Write a new task or plan, set the verify command, watch the
budget, repair the layout when TUIOS loses it.
That gives six workspaces. They are deliberately fewer than the number of things we could
show, because a person who cannot find the screen they need has gained nothing from more
screens.
| Workspace | The question it answers | Panels (maximum four) |
|---|---|---| |---|---|---|
| task list, status, title, assignee | `GET /api/companies/{id}/issues` | a local cache or folder name | | **Board** | what is the state of the work, and what needs me | Task tree · Task summary · Needs you |
| blockers ("blocked by AUD-163") | `GET /api/issues/{id}/diagnostics/blockers`, per task | the list endpoint — it carries no blockers | | **Work** | what is happening now, and what changed | Run log · Diff · Worktree facts |
| thread | `GET /api/issues/{id}/comments` | a copy we keep | | **Conversation** | what has been said, and what do I say back | Thread · Composer · Task header |
| run state, start and end | `GET /api/issues/{id}/runs` | a log file we write | | **Author** | what am I asking for, and how will it be judged | Task form · Guidance · Preview |
| cost | `GET /api/issues/{id}/cost-summary` | our own arithmetic | | **Project** | which folder, which machine, what limits, what cost | Project facts · Costs · Settings |
| what changed | `git` in `currentExecutionWorkspace.cwd` | a diff we store | | **Repair** | is the layout sound, and what went wrong | Layout map · Health · Log |
| which folder, machine, session | `<project>/.harness/harness.toml` | Paperclip (it does not know) |
| which task a viewer is on | the same file, `watching` | a hidden second copy |
The rule that follows: **the interface is allowed to be wrong for one refresh, and is The **shell** workspace stays as it is: one pane with a prompt in the project folder, for
never allowed to be right for the wrong reason.** Every screen shows the time of its last the moments when the person needs a shell and should not have to leave.
read, so a stale screen says it is stale.
## Pages and panes
A **page** is a workspace. A **pane** is one program in it. TUIOS keeps part of the
keyboard, so no screen may use `h j k l z n` for its own actions, and a bare Esc must be
free to close a box.
| Page | Pane | Must show | Keys |
|---|---|---|---|
| shell | shell | a prompt in the project folder | — |
| tree | task tree | groups todo / in progress / blocked / done; identifier, status, assignee, title, blocker; a count per group | ↑↓ Tab Shift-Tab move · `a` assign to Builder · `enter` open this task in reply and log · `r` re-read · `q` quit |
| reply | conversation | the thread with author and time; a box to type in; the status that will be sent with the reply | `tab` focus the box · `enter` send · `s` cycle status · `esc` leave the box · `r` re-read |
| log | run log | run state, start and end, then activity events, newest last | `↑↓` scroll · `g`/`G` top/bottom · `r` re-read · `q` quit |
| diff | change | worktree path and branch; commits on the branch; changed files with counts; the diff itself | `↑↓` scroll · `r` re-read |
| new | new task form | title, what it must do, must finish first, proves it is done, assign | `tab`/`↑↓` next field · `enter` next, and create on the last · `esc` cancel |
Two decisions to settle with you, because they change the shape:
- **Is the diff its own pane or the bottom half of the log?** Its own pane is honest (a
long diff never squeezes the log) and costs a workspace. One pane split in two is
tighter and hides the diff while the log scrolls.
- **Does the tree drive the other panes?** My proposal: pressing `enter` on a task writes
`watching = AUD-163` into the project's `harness.toml` and asks TUIOS to show the reply
page. The reply, log and diff panes watch that file and reload when it changes. One
fact, one owner, no message bus.
## What must never happen
- A pane that lies: showing a task as in progress after the run ended.
- A key that does nothing visible, or two keys that do the same thing differently.
- A layout that breaks below some size instead of saying "too small".
- A second copy of anything Paperclip owns, on disk or in memory across refreshes.
- An action with no visible result: every write must show what came back, or the error.
--- ---
# The layouts ## The user interface items
## A — one page each (what exists today, and the safe default) These are the pieces the panels are made from. Each one says what it is for, which
Charmbracelet component implements it, and what it must show in its empty, loading and
failed states. The list is deliberately finite: if an item is not here, a panel does not
invent it.
Every page is its own workspace, one pane, the whole width. Best at 80 columns and on a ### Navigation and framing
phone-sized terminal. Worst for watching two things at once, because switching costs a
keystroke and hides the tree.
``` **1. Workspace strip.** A one-line strip at the top of every panel showing which
┌ task tree ── workspace 2 of 5 ────────────────────────────────────────────────┐ workspace this is and how many there are, with the current one marked. Implemented in
│ spike-2026-11-10 · read 11:42:07 · 6 tasks │ Lipgloss; TUIOS switches workspaces, so this is a position indicator, not a control.
│ │ Empty state: never empty. Failed state: never applicable.
│ TODO (2) │
│ ▸ AUD-166 todo — Add the weekly cost report │
│ AUD-167 todo — Document the merge gate [AUD-166 todo] │
│ IN PROGRESS (1) │
│ AUD-165 in_progress Builder Review gate probe │
│ BLOCKED (1) │
│ AUD-162 blocked — Tree render check [AUD-161 todo] │
│ DONE (2) │
│ AUD-163 done Builder Write NOTES.md │
│ │
│ ↑↓ move · a assign · enter open · r re-read · q quit │
└──────────────────────────────────────────────────────────────────────────────┘
1 shell 2 tree* 3 reply 4 log 5 diff 6 new
```
## B — cockpit: tree and conversation side by side **2. Panel frame.** A border with a title and a focus marker. Rounded border when the
panel has focus, plain border when it does not, plus the word `focus` in the title so the
difference does not depend on colour. Implemented with Lipgloss borders. Every panel has
one, and the frame is what the "too small" message replaces.
One workspace holds the work; the tree stays visible while you read and reply. The log **3. Footer key hints.** The keys that work right now, in this panel, in this state. Uses
and diff live one workspace away, because during a conversation the change matters less the `help` component with `key.Binding`, so a key that does not apply is not shown.
than what the agent said. Never shows a key that would do nothing.
``` **4. Notice line.** One line for the result of an action, such as "sent", "created
┌ tree 34% ─────────────────┐┌ reply ────────────────────────────────────────────┐ AUD-166", or the exact error text. Disappears when the next action starts. Uses Lipgloss
│ spike-2026-11-10 ││ AUD-165 in_progress · Builder │ only; the text is always the server's own words, never a paraphrase.
│ read 11:42:07 ││ │
│ ││ agent 11:38 │
│ TODO (2) ││ Workspace Ready — branch AUD-165-… │
│ ▸ AUD-166 Add weekly cost ││ │
│ AUD-167 Document merge ││ you 11:40 │
│ ⤷ waits on AUD-166 ││ Please also guard against HOME being unset. │
│ IN PROGRESS (1) ││ │
│ AUD-165 Review probe ││ agent 11:41 │
│ BLOCKED (1) ││ Done — guard added, tests pass. │
│ AUD-162 Tree render ││ │
│ ⤷ waits on AUD-161 ││ │
│ DONE (2) ││ │
│ AUD-163 NOTES.md ││ ┌───────────────────────────────────────────────┐ │
│ AUD-164 List lines ││ │ > _ │ │
│ ││ └───────────────────────────────────────────────┘ │
│ ↑↓ move · a assign ││ status → in_progress · s status · enter send │
└───────────────────────────┘└───────────────────────────────────────────────────┘
tab focus · esc leave box · r re-read
```
## C — cockpit with the change always visible **5. Stale marker.** The time of the last successful read, shown in the panel title. The
purpose is honesty: a panel that has not read recently says so instead of looking current.
Tree on the left, conversation top right, diff bottom right. The most information at once, ### Lists and rows
and the only layout where a person can see a claim and the code that backs it at the same
time. It needs width: below about 120 columns the diff half is unreadable and the layout
must fall back to B or A.
``` **6. Task row.** One line per task: selection cursor, identifier, status, assignee, title,
┌ tree 28% ──────────┐┌ reply 72% ──────────────────────────────────────────────┐ and a blocker badge when something blocks it. The `list` component with a custom
│ TODO (2) ││ AUD-165 in_progress · Builder read 11:42:07 │ delegate, so filtering and scrolling come for free.
│ ▸ AUD-166 cost ││ agent 11:38 Workspace Ready — branch AUD-165-… │
│ AUD-167 docs ││ you 11:40 Please also guard against HOME being unset.│ **7. Group header.** A heading with a count, such as "Blocked (2)". Not selectable.
│ ⤷ AUD-166 ││ agent 11:41 Done — guard added, tests pass. │ Implemented in the list delegate.
│ IN PROGRESS (1) ││ ┌─────────────────────────────────────────────────────┐ │
│ AUD-165 probe ││ │ > _ │ │ **8. Status pill.** The task's state as a short word with a distinct style per state, and
│ BLOCKED (1) ││ └─────────────────────────────────────────────────────┘ │ a different shape as well as colour so it survives a monochrome terminal and colour
│ AUD-162 tree │├─ diff ──────────────────────────────────────────────────┤ blindness.
│ ⤷ AUD-161 ││ cleanup.sh · branch AUD-165-… · 1 commit · +4 −0 │
│ DONE (2) ││ @@ -1,2 +1,3 @@ │ **9. Assignee chip.** The agent's name, or a dash. Uses the agent name from Paperclip,
│ AUD-163 NOTES.md ││ -rm -rf "$HOME/tmp" || true │ never an identifier fragment.
│ ││ +[ -n "$HOME" ] && rm -rf -- "$HOME/tmp" || true │
│ ↑↓ · a · enter ││ ↑↓ scroll · r re-read │ **10. Blocker badge.** `waits on AUD-163` on the row, read per task from the blocker
└────────────────────┘└────────────────────────────────────────────────────────┘ diagnosis. When the blocker is finished the badge says `ready`, because a task that is
``` ready but still marked blocked is the most confusing state we have.
**11. Needs-you card.** One card per decision waiting on a person: a refused merge, a
task waiting for an answer, a task whose blocker finished while it was still marked
blocked. Each card says what happened, what is expected, and the one key that acts on it.
Implemented as `list` items with a different delegate.
**12. Table.** For figures that must be compared: per-task cost, per-run duration,
per-file change counts. Uses the `table` component with fixed column widths taken from the
panel width, never from a constant.
### Reading long content
**13. Thread message.** Author, time, and the body with paragraph breaks and code blocks
preserved. Bodies are wrapped to the panel, never truncated with an ellipsis in the middle
of a sentence. Scrolls inside a `viewport`.
**14. Composer.** A multi-line text area for the reply, growing with the text up to a
third of the panel, then scrolling. Uses `textarea`. Enter sends and needs to be stated in
the footer, because a text area normally treats Enter as a new line.
**15. Diff view.** File headers, hunks, and line numbers, with additions and deletions
distinguished by a leading character as well as colour. Scrolls inside a `viewport`.
Very large diffs are capped with an explicit line saying how many lines were left out, and
a key that shows everything.
**16. Run timeline.** One row per run: state, what woke it, start and end, duration, cost,
and a link to the agent's final message. Uses `table` or a list delegate.
**17. Worktree facts.** The folder, the branch, the base it was cut from, and the
delivery state. Small, monospaced, never wrapped.
### Input and forms
**18. Form field.** A label, an optional "(required)", a hint line under it, and the value.
Single-line fields use `textinput`; the description uses `textarea`. Tab moves forward,
Shift-Tab moves back, Enter on the last field submits.
**19. Validation message.** Directly under the field that is wrong, in the field's own
words, and the submit key stays available so the person can correct and try again.
**20. Result receipt.** After a write: the identifier that was created or the state that
was set, with the server's response behind it. A failure shows the server's message
verbatim, because paraphrasing an error we do not understand is how an afternoon is lost.
**21. Confirmation prompt.** For anything destructive: the exact thing being removed, and
the word that must be typed to continue. Uses `textinput` with no suggestions.
### Status and feedback
**22. Spinner with a verb.** While a read or a write is in flight: what is happening, not
just that something is. Uses `spinner`.
**23. Progress bar.** Only for things with a known count, such as "3 of 7 tasks read".
Uses `progress`. Never used as decoration, and never used to fake a duration.
**24. Health row.** One line per check in the Repair workspace: name, pass, fail or not
run, and the reason. Three states, never two, because "not run" is not "pass".
**25. Empty state.** Every panel says why it is empty: "no tasks in this project", "this
task has never run", "no worktree, so nothing to compare". An empty panel with no words is
a bug.
**26. Error state.** The failed thing, the exact message, and the one action that is still
possible, such as retry or open the Repair workspace.
### Icons
**27. Glyphs.** A small set used consistently: running, waiting, blocked, done, failed,
unread. Taken from the glyph set TUIOS reports, with an ASCII fallback, and never the only
carrier of meaning. Checked with `tuios list-glyphs` before use, not assumed.
--- ---
# Recommendation ## What each panel shows, and where the facts come from
**C, falling back to B, falling back to A**, chosen by the width the pane actually has, not | Panel | Shows | Reads from |
by a setting. The person gets the most information their terminal can carry, and never a |---|---|---|
layout that pretends to have room it does not. | Task tree | groups, rows, badges | company issue list, then the blocker diagnosis per task |
| Task summary | status, assignee, priority, blockers, verify command, cost, last run | single task read, blocker diagnosis, cost summary |
| Needs you | decisions and waits | task states, merge refusals, pending answers already on the task |
| Run log | run timeline and activity | runs, activity |
| Diff | changed files and the change | `git` in the task's own worktree |
| Worktree facts | folder, branch, base, delivery state | the task's current execution workspace |
| Thread | messages | comments |
| Composer | the text being written, the status to send | the person, then a comment or a status change |
| Task header | identifier, title, status, assignee | single task read |
| Task form | the fields being written | the person, then a created task |
| Guidance | what a good task needs, and the project's verify command | the project's `.harness` file |
| Preview | the description as the agent will receive it | the form, not the server |
| Project facts | folder, machine, session, project identifier | the project's `.harness` file |
| Costs | spend by task and by agent | cost summary per task, agent budget |
| Settings | verify command, budget, watched task | the `.harness` file, then Paperclip for what it owns |
| Layout map | workspaces and panels as they actually exist | TUIOS |
| Health | checks and their outcome | the checks themselves |
| Log | what the repair did | the repair's own output |
Concretely: Two rules follow and are not negotiable:
- 150 columns and wider: C. Tree 28%, right split 55/45 between reply and diff. - **A panel never invents a fact.** If Paperclip does not have it, the panel says it does
- 110–149 columns: B, with the diff one workspace away. not have it.
- 80–109 columns: A, one page each. - **A panel shows when it last read.** So a wrong panel is visibly stale rather than
- Below 80×24: the "too small" screen with the numbers, on every page. quietly wrong.
Two things to settle before building: whether the tree drives the other panes through ---
`harness.toml`, and whether the four screens stay four workspaces or become two.
## How it is drawn
**One theme, semantic roles.** Colours are named by role (text, muted, accent, success,
warning, error, and a surface colour), and panels ask for the role, never for a hex value.
A dark and a light variant exist from the start.
**Focus is unmistakable.** The focused panel gets a rounded border, a bright border colour,
and the word `focus` in its title. Two of those three do not depend on colour.
**Density.** One cell of horizontal padding inside a frame, one blank line between
sections, no blank line between rows. Rows are single lines except thread messages, which
are the only content that gets paragraph space.
**Alignment.** Identifiers, statuses, assignee names and numbers are aligned into columns
whose widths are computed from the content in view, capped at a share of the panel width.
Never a hardcoded column width.
**Truncation.** A truncated title ends in an ellipsis and the full text is available with a
key that opens a detail view. Nothing important is truncated silently.
**No decoration that carries no meaning.** No gradients, no box-drawing around every row,
no colour that does not correspond to a state.
**Motion.** Only two things animate: the spinner while something is in flight, and the
selection cursor as it moves. Nothing else moves on its own.
**The Charmbracelet pieces we use:** `list` for rows and decisions, `table` for figures,
`viewport` for anything scrollable, `textarea` for the composer, `textinput` for fields
with one line, `help` and `key` for the footer, `spinner` and `progress` for feedback.
Tabs are not a component in this collection, so a view switcher inside a panel is built
from Lipgloss and the `help` component, and is styled like the rest of the interface.
---
## Keys
TUIOS keeps `h`, `j`, `k`, `l`, `z` and `n` in window management mode, so no panel may use
them. A bare Esc must stay free, because it closes a box.
| Where | Key | Does |
|---|---|---|
| Any panel | Tab, Shift-Tab | move focus to the next or previous panel |
| Any panel | ? | show the keys for this panel |
| Any panel | r | read again from Paperclip |
| Any panel | q | leave this panel's program, returning the pane to its shell |
| Any panel | Esc | close the open overlay or leave the composer, never quit |
| Task tree | Up, Down | move the selection |
| Task tree | Enter | open this task in the Conversation and Work workspaces |
| Task tree | a | assign to the configured agent |
| Task tree | Space | expand or collapse a group |
| Thread | Up, Down, Page Up, Page Down | scroll |
| Composer | Enter | send |
| Composer | Shift-Enter | new line |
| Composer | s | choose the status to send with the reply |
| Diff | Up, Down, Page Up, Page Down | scroll |
| Diff | f | show the whole file, not the capped view |
| Forms | Tab, Shift-Tab | next or previous field |
| Forms | Enter | next field, and submit on the last one |
| Destructive | typed word | confirm |
No key means two things in two panels. Where a panel needs a key that is taken, it uses a
different one rather than overloading.
---
## Size, and what happens when there is not enough
Every panel declares a smallest useful size. When a panel is smaller than that, it draws
its own short message with the size it has and the size it needs, and nothing else. The
program never draws a broken layout and never invents a scrollbar to hide the problem.
| Panel | Smallest useful size |
|---|---|
| Task tree | 30 columns by 10 rows |
| Task summary | 30 by 8 |
| Needs you | 30 by 6 |
| Run log | 40 by 10 |
| Diff | 40 by 12 |
| Worktree facts | 30 by 6 |
| Thread | 40 by 12 |
| Composer | 40 by 4 |
| Task form | 50 by 14 |
| Guidance | 30 by 6 |
| Preview | 40 by 10 |
| Project facts, Costs, Settings | 40 by 8 |
| Layout map, Health, Log | 40 by 8 |
The workspace itself needs 80 columns by 24 rows. Below that, the whole workspace shows one
message naming the size it has and the size it needs.
---
## Layout, once the panels are settled
The panels above do not fit in one workspace, and should not. Layout is chosen by the
width of the terminal, so the person gets as much as their screen can carry and never a
layout pretending to have room it does not.
- **150 columns and wider:** Board shows tree and summary side by side with Needs you under
the tree. Work shows run log and diff side by side. Conversation shows thread above
composer with the task header above both.
- **110 to 149 columns:** two panels per workspace at most; the third becomes a view
switched with a tab inside the panel that shares its kind of content.
- **80 to 109 columns:** one panel per workspace at full width, in the order Board, Work,
Conversation, Author.
- **Below 80 by 24:** one message, nothing else.
The exact three candidate arrangements are drawn in the earlier note and are still valid
for the wide case; what changes here is that the panels themselves are now defined, so the
layout is a matter of which panels share a workspace rather than what a panel contains.
---
## What is not in this version, deliberately
- No chat with an agent as a separate thing: the Conversation workspace is the chat.
- No plan editor: a plan is a task's description, and the Author workspace writes it.
- No second task board: TUIOS has one, Paperclip has one, and this interface is the one
that knows about blockers and worktrees.
- No settings for colours: one theme, two variants, no per-panel colour choices.
- No dashboards of figures with nothing to act on: every number sits next to the thing it
describes.
---
## Decisions needed before building
1. **Does the tree drive the other workspaces?** Proposal: pressing Enter writes the chosen
task's identifier into the project's `.harness/harness.toml` as `watching`, and asks
TUIOS to show the Conversation workspace. The other panels watch that file and reload
when it changes. One fact, one owner, no message bus, and it survives a restart.
2. **Six workspaces, or fewer?** The proposal is six. Fewer means more switching inside a
panel, which costs a key and hides state.
3. **Which glyph set?** Depends on the font in the terminal; must be checked with
`tuios list-glyphs` on the machine the person actually uses.
4. **Is the diff a panel or a view inside the Work workspace?** A panel never squeezes the
run log; a view keeps the workspace count down.