feat(setup): give instructions and skills one compact line each

[dizys]

Last of four stacked PRs reworking the setup console's UX. Based on #44.

Instructions & skills (formerly Context) had the densest rows in the console. Each skill took about 100px: a badge, two lines of description, a metadata line, a labelled Visibility select, and Edit and View buttons. Fifteen skills ran to some 3,000px on a phone. Each agent's instructions had a Shared / Separate / None switch that needed a paragraph underneath to explain it.

Screenshots

Same sample data before and after (scripts/fixtures/console), light theme; desktop at 1280 px, phone at 390 px. Click an image for full size.

Before	After
Instructions: one page holding instructions and every skill becomes two tabs. Each agent’s Shared / Separate / None switch is a choice that explains itself.
Skills: one line per skill, with the agent picker and the actions in the list’s toolbar.
New page

Before	After	Before	After
On a phone: the whole page before (skills start below the fold), and the Skills tab after.		Instructions tab, after.

The README's picture is rebuilt from the new console too:

Two tabs, each at its own address

Instructions and Skills are tabs under the page header: #instructions and #instructions/skills, so either can be linked or bookmarked. Arrow keys move between them, as in any tab list. Skills are only scanned when their tab is open.

Instructions

• Shared instructions: the AGENTS.md row says how big it is and which agents read it ("1 kB · read by Claude Code and Codex"), or "Not written yet". Its action is Write until it exists, then Edit. Delete is in its menu.

• What each agent reads: one choice per agent, worded so it explains itself:

  • Shared AGENTS.md (marked write it first while the shared file doesn't exist)
  • Its own CLAUDE.md / Its own AGENTS.md
  • No instructions

  Leaving a file of its own, or reading nothing, still asks first. A cancelled or failed change shows the choice in effect again. Under the name, the row only adds what the choice doesn't say: its own file's path, or that the shared file isn't written yet.

• The editors say what they edit and who reads it ("Claude Code's CLAUDE.md · Only Claude Code reads this file"; "Shared AGENTS.md · Read by Claude Code and Codex").

Skills

• One line per skill. A skill icon, the name and a one-line description (two on a phone) (the whole description shows on hover), and one control:

  • Codex: a switch.
  • Claude Code and OpenCode: their own visibility or permission menu.
  • Other agents: what's known (Unverified).

  Pressing the name opens the skill as before, with its Markdown, location, Edit and Remove.

• Agent picks whose skills are shown. Refresh, Install from source and Add skill sit beside it in the list's toolbar. Skill rows have no menus, so their controls line up with the toolbar's buttons.

• What a setting means for that agent ("Each setting is this agent's own user policy…") is said once under the list, not above every list.

• About 60px per skill, down from about 100px.

README and guide pictures

• scripts/readme-media.js rebuilds docs/media/setup-{light,dark}.png (Overview on a desktop and Agents on a phone, mid-setup) and docs/media/ports-panel.png from the console itself, with sample data. These pictures were still of the old design.
• The sample data and routing it shares with console-screens.js move to scripts/lib/console-fixtures.cjs. CONTRIBUTING says when to run it.

Also

• Small selects (tc-select--sm) match the small buttons beside them, and keep 16px text on a phone so iOS doesn't zoom in.
• A row can show an icon (row.icon) in place of a monogram; AGENTS.md uses a file icon.
• scripts/console-screens.js also photographs the Skills tab.
• The context guide describes the new controls.

Test plan

• node --test tests/*.test.mjs: 602 pass (updated: what each agent reads, who reads the shared file, Write vs Edit)
• Context audit, updated for the choice menus: cancelled and failed changes show the choice in effect; an unreadable file offers no editor
• Skills audit, updated for the switches and compact rows: no optimistic state; a late result never lands on another agent's list; policies have no repeated badge
• scripts/readme-media.js regenerated the README's two pictures and the Ports guide's from the console
• scripts/ui-audit.js: no findings at 360, 390, 820, 1100 and 1440 px, and embedded at 390 and 1198
• Storage, auto-update, form-drafts and row audits pass
• CI: lint, versions, and the browser and core images built and smoke-tested on amd64 and arm64

Stack: #42 Foundations → #43 Structure → #44 Overview → #45 Instructions & skills

🤖 Generated with Claude Code