paperclip-harness/docs/outline/03-code-map.md

Code map

The binary

tui/ builds one binary. main.go reads the flags and starts one screen.

File	Does
main.go	flags, palette, which screen to start
model.go	the task tree screen and the shared row loader
board.go	Board: tasks, chosen task, needs you
work.go	Work: runs, change, facts, review, log, merge
agents.go	Agents: roster, runs, log, settings, skills, extensions
reply.go	Reply: thread and reply box
newtask.go	New task: the form, guidance, preview
project.go	Project: overview, facts, costs, settings, projects
repair.go	Repair: health, layout, log, cleanup
frame.go	the panel frame, tabs, hints, overlays, wrapping
theme.go	the palette and the icon set
toolpane.go	opening a tool as a pane, and finding the current workspace
picker.go	skills and extensions for one agent
rebuild.go	detached rebuild, merge and review, and their logs

tui/paperclip/client.go is the whole API client. It holds no state.

The commands

File	Does
bin/office	adopt a folder, create its session, build its panes
bin/board	build or repair the panes, by name, in order
bin/merge	rebase, check, review, merge, re-check, roll back on failure
bin/review	the review alone
bin/triage	ask Mouse-1 one four-option question
bin/project-reset	close panes, remove worktrees and branches, keep the folder
bin/shell-banner	the box printed at the top of Shell
bin/lib/tuios.py	sessions, workspaces, panes: claim by name, never by number
bin/lib/harness.py	API, git, ocr, and the tool-path fix
bin/lib/project.py	the project file and the registry

The rules the code keeps

• No network or git call inside an update or view function. They run in commands.
• No hardcoded sizes. The size comes from the terminal on every refresh.
• One click-zone manager, created once, wrapping the whole view.
• Every panel line is exactly the width asked for. tui/frame_test.go fails if it is not.