From b44bf73713440ee2c6a699e7c2d46d28feeda755 Mon Sep 17 00:00:00 2001 From: Sam Date: Tue, 10 Nov 2026 13:04:05 +1100 Subject: [PATCH] Interface specification: six workspaces, twenty-seven interface items, styling and keys --- .../docs-ui-layout-md-interface-spec.md | 93 ++++ .../20-context/paperclip-harness.md | 53 ++ .../packs/paperclip-harness/20-context/tmp.md | 94 ++++ ...layout-md-and-three-live-layout-mockups.md | 90 ++++ ...ve-layout-selection-by-pane-width-c-b-a.md | 47 ++ ...measured-widths-and-screenshot-workflow.md | 46 ++ ...ry-structure-and-configuration-patterns.md | 94 ++++ .../rich-discovery-tmp-2026-11-10-01-47-01.md | 97 ++++ ...erface-spec-and-mockup-session-snapshot.md | 46 ++ docs/UI-LAYOUT.md | 460 ++++++++++++------ 10 files changed, 980 insertions(+), 140 deletions(-) create mode 100644 .pi/memory-vault/packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/20-context/tmp.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01.md create mode 100644 .pi/memory-vault/packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot.md diff --git a/.pi/memory-vault/packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec.md b/.pi/memory-vault/packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec.md new file mode 100644 index 0000000..bd4cb9b --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/20-context/docs-ui-layout-md-interface-spec.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md b/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md new file mode 100644 index 0000000..e6016aa --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/20-context/paperclip-harness.md @@ -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 ``, optional first-child `{JSON}`), 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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md b/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md new file mode 100644 index 0000000..27ad639 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/20-context/tmp.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md b/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md new file mode 100644 index 0000000..9e2a2af --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/40-actions/2026-11-10-wrote-docs-ui-layout-md-and-three-live-layout-mockups.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a.md b/.pi/memory-vault/packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a.md new file mode 100644 index 0000000..e96bd5e --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/50-decisions/responsive-layout-selection-by-pane-width-c-b-a.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow.md b/.pi/memory-vault/packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow.md new file mode 100644 index 0000000..56f8411 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/60-observations/mockup-layouts-a-b-c-measured-widths-and-screenshot-workflow.md @@ -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 '; 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 ''`; 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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md b/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md new file mode 100644 index 0000000..52d94a7 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/60-observations/tmp-repository-structure-and-configuration-patterns.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01.md b/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01.md new file mode 100644 index 0000000..26a4179 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/80-sessions/rich-discovery-tmp-2026-11-10-01-47-01.md @@ -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 + +- 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]] diff --git a/.pi/memory-vault/packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot.md b/.pi/memory-vault/packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot.md new file mode 100644 index 0000000..d102d37 --- /dev/null +++ b/.pi/memory-vault/packs/paperclip-harness/80-sessions/ui-interface-spec-and-mockup-session-snapshot.md @@ -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 + +- 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]] diff --git a/docs/UI-LAYOUT.md b/docs/UI-LAYOUT.md index 538ed93..6efda56 100644 --- a/docs/UI-LAYOUT.md +++ b/docs/UI-LAYOUT.md @@ -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 -what each page must show, where every fact comes from, what the keys are, and then three -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. +Written 2026-11-10. This replaces the earlier layout note: it is now the one document that +says what the interface contains. Layout comes after this, and is chosen from it. -## 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 | -| blockers ("blocked by AUD-163") | `GET /api/issues/{id}/diagnostics/blockers`, per task | the list endpoint — it carries no blockers | -| thread | `GET /api/issues/{id}/comments` | a copy we keep | -| run state, start and end | `GET /api/issues/{id}/runs` | a log file we write | -| cost | `GET /api/issues/{id}/cost-summary` | our own arithmetic | -| what changed | `git` in `currentExecutionWorkspace.cwd` | a diff we store | -| which folder, machine, session | `/.harness/harness.toml` | Paperclip (it does not know) | -| which task a viewer is on | the same file, `watching` | a hidden second copy | +| **Board** | what is the state of the work, and what needs me | Task tree · Task summary · Needs you | +| **Work** | what is happening now, and what changed | Run log · Diff · Worktree facts | +| **Conversation** | what has been said, and what do I say back | Thread · Composer · Task header | +| **Author** | what am I asking for, and how will it be judged | Task form · Guidance · Preview | +| **Project** | which folder, which machine, what limits, what cost | Project facts · Costs · Settings | +| **Repair** | is the layout sound, and what went wrong | Layout map · Health · Log | -The rule that follows: **the interface is allowed to be wrong for one refresh, and is -never allowed to be right for the wrong reason.** Every screen shows the time of its last -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 **shell** workspace stays as it is: one pane with a prompt in the project folder, for +the moments when the person needs a shell and should not have to leave. --- -# 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 -phone-sized terminal. Worst for watching two things at once, because switching costs a -keystroke and hides the tree. +### Navigation and framing -``` -┌ task tree ── workspace 2 of 5 ────────────────────────────────────────────────┐ -│ spike-2026-11-10 · read 11:42:07 · 6 tasks │ -│ │ -│ 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 -``` +**1. Workspace strip.** A one-line strip at the top of every panel showing which +workspace this is and how many there are, with the current one marked. Implemented in +Lipgloss; TUIOS switches workspaces, so this is a position indicator, not a control. +Empty state: never empty. Failed state: never applicable. -## 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 -and diff live one workspace away, because during a conversation the change matters less -than what the agent said. +**3. Footer key hints.** The keys that work right now, in this panel, in this state. Uses +the `help` component with `key.Binding`, so a key that does not apply is not shown. +Never shows a key that would do nothing. -``` -┌ tree 34% ─────────────────┐┌ reply ────────────────────────────────────────────┐ -│ spike-2026-11-10 ││ AUD-165 in_progress · Builder │ -│ 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 -``` +**4. Notice line.** One line for the result of an action, such as "sent", "created +AUD-166", or the exact error text. Disappears when the next action starts. Uses Lipgloss +only; the text is always the server's own words, never a paraphrase. -## 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, -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. +### Lists and rows -``` -┌ tree 28% ──────────┐┌ reply 72% ──────────────────────────────────────────────┐ -│ TODO (2) ││ AUD-165 in_progress · Builder read 11:42:07 │ -│ ▸ AUD-166 cost ││ agent 11:38 Workspace Ready — branch AUD-165-… │ -│ AUD-167 docs ││ you 11:40 Please also guard against HOME being unset.│ -│ ⤷ AUD-166 ││ agent 11:41 Done — guard added, tests pass. │ -│ IN PROGRESS (1) ││ ┌─────────────────────────────────────────────────────┐ │ -│ AUD-165 probe ││ │ > _ │ │ -│ BLOCKED (1) ││ └─────────────────────────────────────────────────────┘ │ -│ AUD-162 tree │├─ diff ──────────────────────────────────────────────────┤ -│ ⤷ AUD-161 ││ cleanup.sh · branch AUD-165-… · 1 commit · +4 −0 │ -│ DONE (2) ││ @@ -1,2 +1,3 @@ │ -│ AUD-163 NOTES.md ││ -rm -rf "$HOME/tmp" || true │ -│ ││ +[ -n "$HOME" ] && rm -rf -- "$HOME/tmp" || true │ -│ ↑↓ · a · enter ││ ↑↓ scroll · r re-read │ -└────────────────────┘└────────────────────────────────────────────────────────┘ -``` +**6. Task row.** One line per task: selection cursor, identifier, status, assignee, title, +and a blocker badge when something blocks it. The `list` component with a custom +delegate, so filtering and scrolling come for free. + +**7. Group header.** A heading with a count, such as "Blocked (2)". Not selectable. +Implemented in the list delegate. + +**8. Status pill.** The task's state as a short word with a distinct style per state, and +a different shape as well as colour so it survives a monochrome terminal and colour +blindness. + +**9. Assignee chip.** The agent's name, or a dash. Uses the agent name from Paperclip, +never an identifier fragment. + +**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 -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. +| Panel | Shows | Reads from | +|---|---|---| +| 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. -- 110–149 columns: B, with the diff one workspace away. -- 80–109 columns: A, one page each. -- Below 80×24: the "too small" screen with the numbers, on every page. +- **A panel never invents a fact.** If Paperclip does not have it, the panel says it does + not have it. +- **A panel shows when it last read.** So a wrong panel is visibly stale rather than + 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.