# CLI views implementation plan (stages 1 and 2)

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Terminal output drawn as magit-style screens (header block, body, counted sections, action legend), with every unmigrated list restyled through the same row renderer.

**Architecture:** A declarative `screen` value built by a command at a terminal and drawn by one renderer in `internal/control/screen.go`. The row layout reuses `table`'s width logic; `table` itself drops its header row and cyan. `emitView` and `emitPageView` route `--json` and piped output to the existing code unchanged. The CLI tells the server which repository it inferred (`here=` in `--term`) so legend commands can omit it.

**Tech Stack:** Go, the `internal/control` registry, `internal/termtext` for markup, `git` via `internal/gitutil`.

**Spec:** `docs/specs/2026-10-01-cli-views-design.md`

**Issues:** #316 (tracking), #317 (stage 1), #318 (stage 2), #319 (stage 3)

## Global Constraints

- Piped output and `--json` are byte-identical before and after every task.
- All rendering is server-side in `internal/control`; `cmd/gitbay` only adds `here=` to `--term`.
- Colour is never the only signal; `stripSGR` of a colour render equals the colourless render.
- Colours: blue (`\x1b[34m`) for section headings and legend commands; yellow for what waits on the viewer; green/red/none for state. Refs are dim, never cyan.
- Glyphs: `✓` passed/ok, `✗` failed/blocked, `◐` running/pending, `●` waiting on you, `○` closed/draft.
- Commit messages end with `Ref #N` / `Closes #N` for the stage issue. No attribution lines.
- Locally: `go build ./...`, `go vet ./...`, `go test ./internal/control/ ./internal/gitutil/ ./cmd/gitbay/`. The e2e suite runs in CI.
- Commits are signed (the repository requires it); MRs merge with `--strategy ff`.

## Corrections to the spec found while planning

These are applied to the spec in the same commit as this plan:

1. There is no `browse` command. The legend never offers one; the header's
   first field links to the page (OSC 8) where the terminal shows links,
   and a `URL:` field carries it otherwise.
2. `mr rebase`, `mr checkout` and `repo clone` are CLI-local (`cmd/gitbay/local.go`),
   not registry commands. The legend may name them; the resolve test
   accepts them from a fixed list.
3. The server cannot see the client's working directory. The CLI sends
   `here=<owner/name>` in `--term` when it is inside a clone it can infer;
   legend commands drop an argument equal to it.
4. Actions carry no label: the legend prints group names and commands.
5. A table that has not migrated keeps its dim header row when it has a
   number or size column (`admin runners`, `admin stats`): without a
   header those columns are unreadable. Every other table drops it.
6. `mr show` commits carry no signature glyph: `CommitOut` has no
   signature state, and verifying each commit on every show is not worth
   the cost. `repo log` already shows it.
7. Discussion rows carry their full body beneath them. A show screen that
   printed only first lines would lose what `issue show` prints today.

## File structure

| File | Responsibility |
|---|---|
| `internal/control/screen.go` (new) | `screen`, `field`, `section`, `row`, `action`; `render`; legend layout; `cmdline` |
| `internal/control/screen_test.go` (new) | renderer goldens, legend layout, `checkActions` helper |
| `internal/control/plain_test.go` (new) | `pinPlain` golden helper for piped output |
| `internal/control/testdata/plain/*.txt` (new) | pinned piped output per migrated command |
| `internal/control/table.go` | new cell kinds, header rule, dim refs, `lines()` split from `flush()` |
| `internal/control/term.go` | `sgrBlue`, `glyph()`, `Term.Here` |
| `internal/control/view.go` | ref painted dim in `title` |
| `internal/control/control.go` | `emitView` |
| `internal/control/cursor.go` | `emitPageView`, `nextArgv`, restyled next-page line |
| `internal/gitutil/numstat.go` (new) | `DiffNumstat` |
| `internal/control/mr.go`, `issue.go`, `repo.go`, `build.go`, `dashboard.go` | screen builders and `emitView` calls |
| `cmd/gitbay/ssh.go` | `here=` |
| `.gitbay/wiki/Users.org` | "Output rules" rewritten |
| `CHANGELOG.org` | unreleased entries |

---

## Stage 1 (one MR, Ref #317)

### Task 1: Palette, glyph cells, dim refs

**Files:**
- Modify: `internal/control/term.go` (const block at line 53, add `glyph`)
- Modify: `internal/control/table.go` (cell kinds, constructors, `joinRow`, `fit`)
- Modify: `internal/control/view.go:99,106`
- Test: `internal/control/term_test.go`, `internal/control/table_test.go`

**Interfaces:**
- Produces: `sgrBlue`; `glyph(state string) (g, sgr string)`; `kindGlyph`, `kindMeta`; `cGlyph(state string) cell`; `cYou() cell`; `cMeta(parts ...string) cell`.

- [ ] **Step 1: Write failing tests**

Append to `internal/control/term_test.go`:

```go
func TestGlyph(t *testing.T) {
	for _, c := range []struct{ state, g, sgr string }{
		{"success", "✓", sgrGreen},
		{"approved", "✓", sgrGreen},
		{"merged", "✓", ""},
		{"failure", "✗", sgrRed},
		{"changes requested", "✗", sgrRed},
		{"signed_key_revoked", "✗", sgrRed},
		{"running", "◐", ""},
		{"pending", "◐", ""},
		{"closed", "○", ""},
		{"draft", "○", ""},
		{"open", "", ""},
		{"", "", ""},
	} {
		g, sgr := glyph(c.state)
		if g != c.g || sgr != c.sgr {
			t.Errorf("glyph(%q) = %q %q, want %q %q", c.state, g, sgr, c.g, c.sgr)
		}
	}
}
```

Append to `internal/control/table_test.go`:

```go
func TestRefsDimNotCyan(t *testing.T) {
	var b strings.Builder
	tb := (&Ctx{Term: Term{Cols: 80, Color: true}}).table(&b, "#", "TITLE")
	tb.row(cRef("#12"), cFlex("Android app"))
	tb.flush()
	if strings.Contains(b.String(), sgrCyan) {
		t.Errorf("ref painted cyan: %q", b.String())
	}
	if !strings.Contains(b.String(), sgrDim+"#12"+sgrReset) {
		t.Errorf("ref not dim: %q", b.String())
	}
}

func TestGlyphAndMetaCells(t *testing.T) {
	var b strings.Builder
	tb := (&Ctx{Term: Term{Cols: 80, Color: true}}).table(&b)
	tb.row(cRef("1779"), cGlyph("failure"), cFlex("test"), cMeta("gitbay", "2h"))
	tb.row(cRef("1780"), cYou(), cFlex("review"), cMeta("", "3h"))
	tb.flush()
	out := b.String()
	for _, want := range []string{sgrRed + "✗" + sgrReset, sgrYellow + "●" + sgrReset, sgrDim + "gitbay · 2h" + sgrReset, sgrDim + "3h" + sgrReset} {
		if !strings.Contains(out, want) {
			t.Errorf("missing %q in %q", want, out)
		}
	}
}
```

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/control/ -run 'TestGlyph|TestRefsDimNotCyan|TestGlyphAndMetaCells'`
Expected: build failure, `undefined: glyph`, `undefined: cGlyph`.

- [ ] **Step 3: Implement**

In `term.go`, add `sgrBlue = "\x1b[34m"` to the const block after `sgrYellow`, and after `stateColor`:

```go
// glyph is the mark a screen puts first in a row or field for a state
// word, and its colour: ✓ passed, ✗ failed or blocked, ◐ still going,
// ○ closed or draft. A state with no mark ("open") returns "".
func glyph(state string) (g, sgr string) {
	switch state {
	case "merged":
		return "✓", ""
	case "success", "ok", "approved", "verified", "passed":
		return "✓", sgrGreen
	case "failure", "failed", "error", "changes requested",
		"bad_signature", "signed_email_mismatch", "signed_key_expired", "signed_key_revoked":
		return "✗", sgrRed
	case "pending", "running", "queued":
		return "◐", ""
	case "closed", "draft", "canceled", "cancelled", "skipped":
		return "○", ""
	}
	return "", ""
}
```

In `table.go`, extend the kind list and constructors:

```go
const (
	kindText cellKind = iota
	kindFlex
	kindRef
	kindState
	kindAge
	kindNum
	kindSize
	kindSwatch
	kindGlyph
	kindMeta
)
```

```go
// cGlyph is a state's mark, coloured for the state.
func cGlyph(state string) cell {
	g, sgr := glyph(state)
	return cell{kind: kindGlyph, s: g, sgr: sgr}
}

// cYou is the mark for a row that waits on the viewer.
func cYou() cell { return cell{kind: kindGlyph, s: "●", sgr: sgrYellow} }

// cMeta is a row's trailing facts, dim and joined by " · ". Empty parts
// are skipped.
func cMeta(parts ...string) cell {
	var keep []string
	for _, p := range parts {
		if p != "" {
			keep = append(keep, p)
		}
	}
	return cell{kind: kindMeta, s: strings.Join(keep, " · ")}
}
```

In `joinRow`, replace the `kindRef` case and add two cases:

```go
			case kindRef:
				s = t.term.link(r[i].url, t.term.paint(sgrDim, s))
			case kindGlyph:
				s = t.term.paint(r[i].sgr, s)
			case kindMeta:
				s = t.term.paint(sgrDim, s)
```

In `fit`, let metadata shrink with text:

```go
	for i := len(kinds) - 1; i >= 0; i-- {
		if kinds[i] == kindText || kinds[i] == kindMeta {
			shrink(i)
		}
	}
```

In `view.go`, lines 99 and 106, replace `sgrCyan` with `sgrDim`.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/`
Expected: the three new tests pass. Any existing test asserting `sgrCyan` on a ref (search: `grep -n sgrCyan internal/control/*_test.go`) is updated to `sgrDim` in this step; diff and tree tests that expect cyan hunk headers and directory names stay as they are.

- [ ] **Step 5: Commit**

```bash
git add internal/control/term.go internal/control/table.go internal/control/view.go internal/control/*_test.go
git commit -m "control: glyph and meta cells, refs dim

Ref #317"
```

### Task 2: Header rows only where columns need naming

**Files:**
- Modify: `internal/control/table.go` (`flush`, new `numeric`, new `lines`)
- Test: `internal/control/table_test.go`

**Interfaces:**
- Produces: `func (t *table) lines() []string` (terminal rows, padded and painted, header omitted); `flush` keeps its signature.

- [ ] **Step 1: Write failing tests**

```go
func TestTableDropsHeaderWithoutNumbers(t *testing.T) {
	var b strings.Builder
	tb := (&Ctx{Term: Term{Cols: 80}}).table(&b, "#", "STATE", "TITLE")
	tb.row(cRef("#12"), cState("open"), cFlex("Android app"))
	tb.flush()
	if got, want := b.String(), "#12  open  Android app\n"; got != want {
		t.Errorf("got %q, want %q", got, want)
	}
}

func TestTableKeepsHeaderForNumbers(t *testing.T) {
	var b strings.Builder
	tb := (&Ctx{Term: Term{Cols: 80}}).table(&b, "RUNNER", "PENDING")
	tb.row(cText("bay1"), cNum(3))
	tb.flush()
	if !strings.HasPrefix(b.String(), "RUNNER  PENDING\n") {
		t.Errorf("header missing: %q", b.String())
	}
}

func TestTableLines(t *testing.T) {
	tb := (&Ctx{Term: Term{Cols: 80}}).table(io.Discard)
	tb.row(cRef("!1"), cFlex("one"))
	tb.row(cRef("!22"), cFlex("two"))
	got := tb.lines()
	want := []string{"!1   one", "!22  two"}
	if !slices.Equal(got, want) {
		t.Errorf("got %q, want %q", got, want)
	}
}
```

Add `"io"` and `"slices"` to the test file's imports if missing.

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/control/ -run 'TestTableDropsHeader|TestTableKeepsHeader|TestTableLines'`
Expected: FAIL (header printed; `lines` undefined).

- [ ] **Step 3: Implement**

Replace `flush` with:

```go
func (t *table) flush() {
	if t.term.Cols == 0 || len(t.rows) == 0 {
		return
	}
	var b strings.Builder
	for _, l := range t.lines() {
		b.WriteString(l + "\n")
	}
	io.WriteString(t.w, b.String())
}

// numeric reports whether a column holds numbers or sizes, which need a
// header to say what they count.
func (t *table) numeric() bool {
	for _, r := range t.rows {
		for _, c := range r {
			if c.kind == kindNum || c.kind == kindSize {
				return true
			}
		}
	}
	return false
}

// lines lays the rows out at the terminal width: a dim header first
// only when a column is a number, then each row padded and painted.
func (t *table) lines() []string {
	if !t.numeric() {
		t.header = nil
	}
	t.dropEmpty()
	n := len(t.header)
	for _, r := range t.rows {
		n = max(n, len(r))
	}
	widths := make([]int, n)
	for i, h := range t.header {
		widths[i] = cells(h)
	}
	for _, r := range t.rows {
		for i := 0; i < len(r); i++ {
			widths[i] = max(widths[i], cells(r[i].s))
		}
	}
	t.capSparse(widths)
	t.fit(widths)

	var out []string
	line := make([]string, n)
	if len(t.header) > 0 {
		for i := range line {
			line[i] = ""
			if i < len(t.header) {
				line[i] = clip(t.header[i], widths[i])
			}
		}
		out = append(out, t.term.paint(sgrDim, strings.TrimRight(t.join(line, widths), " ")))
	}
	for _, r := range t.rows {
		for i := 0; i < n; i++ {
			s := ""
			if i < len(r) {
				s = clip(r[i].s, widths[i])
			}
			line[i] = s
		}
		out = append(out, strings.TrimRight(t.joinRow(r, line, widths), " "))
	}
	return out
}
```

Update the comment above `type table struct` to say the header is written only when a column is numeric.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/`
Expected: new tests pass. Existing terminal tests that expected a header line on a table without numbers fail; update each expected string to drop its first line (the header). Do not change any plain-output expectation.

- [ ] **Step 5: Commit**

```bash
git add internal/control/table.go internal/control/*_test.go
git commit -m "control: tables name their columns only when they hold numbers

Ref #317"
```

### Task 3: The screen model and renderer

**Files:**
- Create: `internal/control/screen.go`
- Create: `internal/control/screen_test.go`

**Interfaces:**
- Consumes: `table.lines()`, `cGlyph`, `cMeta`, `cYou`, `sgrBlue` (tasks 1–2).
- Produces:

```go
type screen struct {
	fields   []field
	body     string
	format   string
	sections []section
	actions  []action
}
type field struct {
	label string
	value []cell
}
type section struct {
	title string
	n     int
	rows  []row
	more  []string
	empty bool
}
type row struct {
	cells  []cell
	body   string
	format string
}
type action struct {
	group string
	argv  []string
}
func (c *Ctx) render(w io.Writer, s screen)
func rowOf(cs ...cell) row // a row with no body
```

- [ ] **Step 1: Write failing tests**

`internal/control/screen_test.go`:

```go
package control

import (
	"strings"
	"testing"
	"time"
)

func screenCtx(cols int, color bool) *Ctx {
	return &Ctx{Term: Term{Cols: cols, Color: color}}
}

func renderString(c *Ctx, s screen) string {
	var b strings.Builder
	c.render(&b, s)
	return b.String()
}

func sampleScreen() screen {
	return screen{
		fields: []field{
			{"Merge", []cell{cRef("!552"), cText("wire $PAGER through long views")}},
			{"State", []cell{cState("open"), cMeta("cli-pager → main", "cmc")}},
			{"Checks", []cell{cGlyph("running"), cText("1 running")}},
		},
		body:   "Pages long views.",
		format: "markdown",
		sections: []section{
			{title: "Commits", n: 2, rows: []row{
				rowOf(cRef("8f3a1c2"), cFlex("cli: page long output")),
				rowOf(cRef("2b77e90"), cFlex("control: mark views")),
			}},
			{title: "Discussion", n: 0, empty: true},
			{title: "Hidden", n: 0},
		},
	}
}

func TestRenderPlainLayout(t *testing.T) {
	got := renderString(screenCtx(80, false), sampleScreen())
	want := `Merge:   !552  wire $PAGER through long views
State:   open  cli-pager → main · cmc
Checks:  ◐  1 running

Pages long views.

Commits (2)
8f3a1c2  cli: page long output
2b77e90  control: mark views

Discussion (0)
`
	if got != want {
		t.Errorf("got:\n%s\nwant:\n%s", got, want)
	}
}

func TestRenderColourIsOnlyPaint(t *testing.T) {
	for _, cols := range []int{80, 120} {
		plain := renderString(screenCtx(cols, false), sampleScreen())
		colour := renderString(screenCtx(cols, true), sampleScreen())
		if stripSGR(colour) != plain {
			t.Errorf("cols %d: colour render differs beyond SGR:\n%s\n---\n%s", cols, stripSGR(colour), plain)
		}
		if !strings.Contains(colour, sgrBold+sgrBlue+"Commits (2)"+sgrReset) {
			t.Errorf("cols %d: heading not bold blue: %q", cols, colour)
		}
		if !strings.Contains(colour, sgrDim+"Merge:"+sgrReset) {
			t.Errorf("cols %d: label not dim: %q", cols, colour)
		}
	}
}

func TestRenderMoreLine(t *testing.T) {
	s := screen{sections: []section{{title: "Builds", n: 14, more: []string{"build", "list", "krz/gitbay"},
		rows: []row{rowOf(cRef("1779"), cFlex("test"))}}}}
	got := renderString(screenCtx(80, false), s)
	if !strings.HasSuffix(got, "1779  test\n+13 more  gitbay build list krz/gitbay\n") {
		t.Errorf("got %q", got)
	}
}

func TestRenderRowBody(t *testing.T) {
	s := screen{sections: []section{{title: "Discussion", n: 1, rows: []row{
		{cells: []cell{cText("cmc"), cMeta("2h")}, body: "Looks good.", format: "markdown"},
	}}}}
	got := renderString(screenCtx(80, false), s)
	want := "Discussion (1)\ncmc  2h\n  Looks good.\n"
	if got != want {
		t.Errorf("got %q, want %q", got, want)
	}
}

func TestRenderFieldWraps(t *testing.T) {
	long := strings.Repeat("word ", 20)
	s := screen{fields: []field{{"Merge", []cell{cRef("!1"), cText(strings.TrimSpace(long))}}}}
	for _, l := range strings.Split(strings.TrimRight(renderString(screenCtx(40, false), s), "\n"), "\n") {
		if cells(l) > 40 {
			t.Errorf("line wider than 40: %q", l)
		}
	}
}

func init() { termNow = func() time.Time { return time.Date(2026, 10, 1, 12, 0, 0, 0, time.UTC) } }
```

If `termNow` is already pinned by another test file's `init`, drop the `init` here.

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/control/ -run 'TestRender'`
Expected: build failure, `undefined: screen`.

- [ ] **Step 3: Implement `internal/control/screen.go`**

```go
package control

import (
	"fmt"
	"io"
	"strings"

	"gitbay.org/krz/gitbay/internal/termtext"
)

// screen is a show or a list as a terminal draws it: a header block of
// labelled fields, a body, counted sections, and the commands that
// apply. Commands build one only at a terminal; plain and --json output
// never reach it.
type screen struct {
	fields   []field
	body     string // markup source
	format   string // the body's markup format
	sections []section
	actions  []action
}

// field is one header line: a label and the cells after it.
type field struct {
	label string
	value []cell
}

// section is a titled run of rows. n is the total, shown as "(n)"; when
// it is more than the rows shown, more is the command for the rest. An
// empty section is left out unless empty says to draw "(0)".
type section struct {
	title string
	n     int
	rows  []row
	more  []string
	empty bool
}

// row is a section row, and optionally the markup that follows it (a
// comment's body).
type row struct {
	cells  []cell
	body   string
	format string
}

func rowOf(cs ...cell) row { return row{cells: cs} }

// action is one command in the legend, under its group's name. argv is
// the command as typed after "gitbay".
type action struct {
	group string
	argv  []string
}

// render draws s: the parts in order, one blank line between parts and
// between sections.
func (c *Ctx) render(w io.Writer, s screen) {
	var blocks []string
	if b := c.renderFields(s.fields); b != "" {
		blocks = append(blocks, b)
	}
	if b := c.renderBody(s.body, s.format, ""); b != "" {
		blocks = append(blocks, b)
	}
	for _, sec := range s.sections {
		if b := c.renderSection(sec); b != "" {
			blocks = append(blocks, b)
		}
	}
	if b := c.renderLegend(s.actions); b != "" {
		blocks = append(blocks, b)
	}
	io.WriteString(w, strings.Join(blocks, "\n"))
}

// renderFields aligns labels on the widest, dim, with a colon. Every
// cell but the last is painted as a table paints it; the last wraps to
// the width, continuation lines under its first column.
func (c *Ctx) renderFields(fs []field) string {
	t := c.Term
	wide := 0
	for _, f := range fs {
		if len(f.value) > 0 {
			wide = max(wide, cells(f.label)+1)
		}
	}
	var b strings.Builder
	for _, f := range fs {
		if len(f.value) == 0 {
			continue
		}
		prefix := t.paint(sgrDim, f.label+":") + strings.Repeat(" ", wide-cells(f.label)-1+2)
		col := wide + 2
		head := ""
		for _, cl := range f.value[:len(f.value)-1] {
			s := c.cellText(cl)
			if s == "" {
				continue
			}
			head += c.paintCell(cl, s) + "  "
			col += cells(s) + 2
		}
		last := f.value[len(f.value)-1]
		lines := termtext.Wrap(c.cellText(last), max(8, t.Cols-col))
		indent := strings.Repeat(" ", col)
		for i, l := range lines {
			p := indent
			if i == 0 {
				p = prefix + head
			}
			b.WriteString(strings.TrimRight(p+c.paintCell(last, l), " ") + "\n")
		}
	}
	return b.String()
}

// cellText is a cell's terminal text: made safe, ages relative, sizes
// humanized, as table.row prepares it.
func (c *Ctx) cellText(cl cell) string {
	s := termSafe(cl.s)
	switch cl.kind {
	case kindAge:
		return relAge(s, termNow())
	case kindSize:
		var n int64
		if _, err := fmt.Sscan(s, &n); err == nil {
			return humanBytes(n)
		}
	}
	return s
}

// paintCell paints text s as its cell's kind paints at a terminal.
func (c *Ctx) paintCell(cl cell, s string) string {
	t := c.Term
	switch cl.kind {
	case kindState:
		return t.paintState(s)
	case kindRef:
		return t.link(cl.url, t.paint(sgrDim, s))
	case kindMeta:
		return t.paint(sgrDim, s)
	case kindSwatch:
		return t.swatch(s)
	}
	return t.paint(cl.sgr, s)
}

// renderBody renders markup to the width, each line prefixed by indent.
func (c *Ctx) renderBody(src, format, indent string) string {
	if strings.TrimSpace(src) == "" {
		return ""
	}
	opts := termtext.Options{Width: max(0, c.Term.Cols-len(indent)), Color: c.Term.Color, Base: c.Cfg.Server.SiteURL}
	var b strings.Builder
	for _, l := range strings.Split(strings.TrimRight(termtext.Render(termSafe(src), format, opts), "\n"), "\n") {
		if l == "" {
			b.WriteString("\n")
			continue
		}
		b.WriteString(indent + l + "\n")
	}
	return b.String()
}

// renderSection is the heading, the rows laid out as one table with no
// header, each row's body indented beneath it, and the "+n more" line.
func (c *Ctx) renderSection(s section) string {
	if len(s.rows) == 0 && !s.empty {
		return ""
	}
	var b strings.Builder
	b.WriteString(c.Term.paint(sgrBold+sgrBlue, fmt.Sprintf("%s (%d)", s.title, s.n)) + "\n")
	tb := &table{term: c.Term, w: io.Discard}
	for _, r := range s.rows {
		tb.row(append([]cell(nil), r.cells...)...)
	}
	if len(s.rows) > 0 {
		tb.header = nil
		for i, l := range tb.lines() {
			b.WriteString(l + "\n")
			b.WriteString(c.renderBody(s.rows[i].body, s.rows[i].format, "  "))
		}
	}
	if rest := s.n - len(s.rows); rest > 0 && len(s.more) > 0 {
		b.WriteString(c.Term.paint(sgrDim, fmt.Sprintf("+%d more  %s", rest, c.cmdline(s.more))) + "\n")
	}
	return b.String()
}
```

`renderLegend` and `cmdline` come in task 4; add stubs now so the package builds:

```go
func (c *Ctx) renderLegend(as []action) string { return "" }

func (c *Ctx) cmdline(argv []string) string { return "gitbay " + strings.Join(argv, " ") }
```

Check the module path in `go.mod` and use it in the `termtext` import.

`tb.lines()` relies on task 2's rule that a table with no numeric column has no header; a section whose rows carry `cNum` would otherwise print the header slice, which is nil here, so `tb.header = nil` before `lines()` keeps sections header-less in every case.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestRender'`
Expected: PASS. If `TestRenderPlainLayout` differs only in the field padding, the rule is: label, colon, then spaces to `wide+2` columns (`wide` = longest label + 1).

- [ ] **Step 5: Commit**

```bash
git add internal/control/screen.go internal/control/screen_test.go
git commit -m "control: screen model and renderer

Ref #317"
```

### Task 4: Legend, `cmdline`, and `here=`

**Files:**
- Modify: `internal/control/screen.go` (replace the two stubs)
- Modify: `internal/control/term.go` (`Term.Here`, `ParseTerm`)
- Test: `internal/control/screen_test.go`, `internal/control/term_test.go`

**Interfaces:**
- Produces: `Term.Here string`; `func (c *Ctx) cmdline(argv []string) string`; `func (c *Ctx) renderLegend(as []action) string`.

- [ ] **Step 1: Write failing tests**

In `term_test.go`, add cases to `TestParseTerm`'s table (match its existing struct shape):

```go
		{"120,color,here=krz/gitbay", Term{Cols: 120, Color: true, Here: "krz/gitbay"}},
		{"120,here=", Term{Cols: 120}},
```

In `screen_test.go`:

```go
func TestCmdlineDropsHere(t *testing.T) {
	c := screenCtx(80, false)
	c.Term.Here = "krz/gitbay"
	if got, want := c.cmdline([]string{"mr", "diff", "krz/gitbay", "552"}), "gitbay mr diff 552"; got != want {
		t.Errorf("got %q, want %q", got, want)
	}
	if got, want := c.cmdline([]string{"issue", "show", "krz/hutch", "3"}), "gitbay issue show krz/hutch 3"; got != want {
		t.Errorf("got %q, want %q", got, want)
	}
	if got, want := c.cmdline([]string{"issue", "list", "--label", "needs review"}), "gitbay issue list --label 'needs review'"; got != want {
		t.Errorf("got %q, want %q", got, want)
	}
}

func legendSample() []action {
	return []action{
		{"Unblock", []string{"mr", "rebase", "552"}},
		{"Review", []string{"mr", "review", "krz/gitbay", "552", "--approve"}},
		{"Review", []string{"mr", "comment", "krz/gitbay", "552"}},
		{"Read", []string{"mr", "diff", "krz/gitbay", "552"}},
	}
}

func TestLegendColumns(t *testing.T) {
	c := screenCtx(120, false)
	c.Term.Here = "krz/gitbay"
	got := c.renderLegend(legendSample())
	want := strings.Repeat("─", 120) + "\n" +
		"Unblock               Review                        Read\n" +
		"gitbay mr rebase 552  gitbay mr review 552 --approve  gitbay mr diff 552\n" +
		"                      gitbay mr comment 552\n"
	if got != want {
		t.Errorf("got:\n%s\nwant:\n%s", got, want)
	}
}

func TestLegendStacksWhenNarrow(t *testing.T) {
	c := screenCtx(60, false)
	c.Term.Here = "krz/gitbay"
	got := c.renderLegend(legendSample())
	want := strings.Repeat("─", 60) + "\n" +
		"Unblock\ngitbay mr rebase 552\n" +
		"Review\ngitbay mr review 552 --approve\ngitbay mr comment 552\n" +
		"Read\ngitbay mr diff 552\n"
	if got != want {
		t.Errorf("got:\n%s\nwant:\n%s", got, want)
	}
}

func TestLegendColour(t *testing.T) {
	c := screenCtx(120, true)
	got := c.renderLegend(legendSample())
	if !strings.Contains(got, sgrBlue+"gitbay mr rebase 552"+sgrReset) || !strings.Contains(got, sgrBold+"Unblock"+sgrReset) {
		t.Errorf("legend paint: %q", got)
	}
	if stripSGR(got) != screenCtx(120, false).renderLegend(legendSample()) {
		t.Error("colour legend differs beyond SGR")
	}
}
```

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/control/ -run 'TestParseTerm|TestCmdline|TestLegend'`
Expected: FAIL (`Here` unknown field; stub output).

- [ ] **Step 3: Implement**

In `term.go`, add to `Term`:

```go
	// Here is the repository the CLI inferred from the clone it runs in,
	// so a suggested command can leave it out.
	Here string
```

and in `ParseTerm`'s loop, before `switch opt`:

```go
		if v, ok := strings.CutPrefix(opt, "here="); ok {
			t.Here = v
			continue
		}
```

In `screen.go`, replace the stubs:

```go
// cmdline is argv as the viewer would type it: "gitbay", the words
// shell-quoted, and the repository the CLI inferred left out.
func (c *Ctx) cmdline(argv []string) string {
	words := []string{"gitbay"}
	for _, a := range argv {
		if c.Term.Here != "" && a == c.Term.Here {
			continue
		}
		words = append(words, shellWord(a))
	}
	return strings.Join(words, " ")
}

// renderLegend is a rule, then the action groups in the order they first
// appear, each a bold name over its commands in blue. Groups sit side by
// side, three to a band, when the terminal is 80 wide or more and the
// band fits; otherwise they stack.
func (c *Ctx) renderLegend(as []action) string {
	if len(as) == 0 {
		return ""
	}
	t := c.Term
	type group struct {
		name string
		cmds []string
	}
	var groups []*group
	byName := map[string]*group{}
	for _, a := range as {
		g := byName[a.group]
		if g == nil {
			g = &group{name: a.group}
			byName[a.group] = g
			groups = append(groups, g)
		}
		g.cmds = append(g.cmds, c.cmdline(a.argv))
	}
	var b strings.Builder
	b.WriteString(t.paint(sgrDim, strings.Repeat("─", t.Cols)) + "\n")
	for start := 0; start < len(groups); start += 3 {
		band := groups[start:min(start+3, len(groups))]
		widths := make([]int, len(band))
		total, height := 0, 0
		for i, g := range band {
			widths[i] = cells(g.name)
			for _, cmd := range g.cmds {
				widths[i] = max(widths[i], cells(cmd))
			}
			total += widths[i]
			height = max(height, len(g.cmds))
		}
		total += 2 * (len(band) - 1)
		if t.Cols < 80 || total > t.Cols {
			for _, g := range band {
				b.WriteString(t.paint(sgrBold, g.name) + "\n")
				for _, cmd := range g.cmds {
					b.WriteString(t.paint(sgrBlue, cmd) + "\n")
				}
			}
			continue
		}
		for line := -1; line < height; line++ {
			var l strings.Builder
			for i, g := range band {
				s, paint := "", sgrBlue
				if line < 0 {
					s, paint = g.name, sgrBold
				} else if line < len(g.cmds) {
					s = g.cmds[line]
				}
				if i < len(band)-1 {
					l.WriteString(t.paint(paint, s) + strings.Repeat(" ", widths[i]-cells(s)+2))
				} else {
					l.WriteString(t.paint(paint, s))
				}
			}
			b.WriteString(strings.TrimRight(l.String(), " ") + "\n")
		}
	}
	return b.String()
}
```

`shellWord` already exists (used by `emitPage`); if it is in `cmd/gitbay` rather than `internal/control`, find it with `grep -rn 'func shellWord' internal/` and use that one.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/control/screen.go internal/control/term.go internal/control/*_test.go
git commit -m "control: action legend; here= names the inferred repository

Ref #317"
```

### Task 5: `emitView`, `emitPageView`, the next-page line

**Files:**
- Modify: `internal/control/control.go` (after `emit`)
- Modify: `internal/control/cursor.go` (`emitPage`)
- Test: `internal/control/screen_test.go`, `internal/control/cursor_test.go:84`

**Interfaces:**
- Consumes: `render`, `cmdline` (tasks 3–4).
- Produces:

```go
func (c *Ctx) emitView(data any, plain func(w io.Writer), build func() screen) int
func (c *Ctx) emitPageView(p page, items any, next string, plain func(w io.Writer), build func() screen) int
func (c *Ctx) nextArgv(next string) []string
```

- [ ] **Step 1: Write failing tests**

```go
func TestEmitViewRoutes(t *testing.T) {
	built := false
	build := func() screen { built = true; return screen{fields: []field{{"Repo", []cell{cText("a/b")}}}} }
	plain := func(w io.Writer) { io.WriteString(w, "plain\n") }

	var out bytes.Buffer
	c := &Ctx{Stdout: &out, Stderr: io.Discard}
	c.emitView(map[string]string{"k": "v"}, plain, build)
	if out.String() != "plain\n" || built {
		t.Errorf("piped: %q built=%v", out.String(), built)
	}

	out.Reset()
	c = &Ctx{Stdout: &out, Stderr: io.Discard, JSON: true, Term: Term{Cols: 80}}
	c.emitView(map[string]string{"k": "v"}, plain, build)
	if !strings.Contains(out.String(), `"k":"v"`) || built {
		t.Errorf("json: %q built=%v", out.String(), built)
	}

	out.Reset()
	c = &Ctx{Stdout: &out, Stderr: io.Discard, Term: Term{Cols: 80}}
	c.emitView(map[string]string{"k": "v"}, plain, build)
	if out.String() != "Repo:  a/b\n" || !built {
		t.Errorf("terminal: %q built=%v", out.String(), built)
	}
}
```

Add `bytes` and `io` imports to `screen_test.go`.

In `cursor_test.go`, change the expectation at line 84 to the new stderr line:

```go
	want := "Next page  gitbay build list " + repo.Path() + " --limit 2 --cursor "
```

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/control/ -run 'TestEmitViewRoutes|TestCursor'`
Expected: FAIL (`emitView` undefined; old `more:` text).

- [ ] **Step 3: Implement**

In `control.go`, after `emit`:

```go
// emitView is emit for a command with a terminal screen: --json and
// piped output are emit's, and at a terminal build's screen is drawn
// in place of plain.
func (c *Ctx) emitView(data any, plain func(w io.Writer), build func() screen) int {
	if c.Term.Cols == 0 || c.JSON {
		return c.emit(data, plain)
	}
	return c.emit(data, func(w io.Writer) { c.render(w, build()) })
}
```

In `cursor.go`, extract the argv the old `more:` line built:

```go
// nextArgv is the command that fetches the page after this one: this
// command's argv with its cursor replaced.
func (c *Ctx) nextArgv(next string) []string {
	argv := strings.Fields(joinPath(c.Cmd.Path))
	for i := 0; i < len(c.Argv); i++ {
		if c.Argv[i] == "--cursor" {
			i++
			continue
		}
		argv = append(argv, c.Argv[i])
	}
	return append(argv, "--cursor", next)
}
```

and replace the terminal branch of `emitPage`'s closure (from `var again []string` to the `Fprintf`) with:

```go
		fmt.Fprintln(c.Stderr, c.Term.paint(sgrBold, "Next page")+"  "+c.Term.paint(sgrBlue, c.cmdline(c.nextArgv(next))))
```

Then add:

```go
// emitPageView is emitPage for a list with a terminal screen.
func (c *Ctx) emitPageView(p page, items any, next string, plain func(w io.Writer), build func() screen) int {
	if c.Term.Cols == 0 || c.JSON {
		return c.emitPage(p, items, next, plain)
	}
	return c.emitPage(p, items, next, func(w io.Writer) { c.render(w, build()) })
}
```

`cmdline` shell-quotes each word, so the old `shellWord` loop in `emitPage` is no longer used there; remove it if nothing else in the function uses it.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/control/control.go internal/control/cursor.go internal/control/*_test.go
git commit -m "control: emitView and emitPageView; next page as a legend line

Ref #317"
```

### Task 6: The CLI sends `here=`

**Files:**
- Modify: `cmd/gitbay/ssh.go` (`termValue` signature and `runSSHPaged`)
- Test: `cmd/gitbay/term_test.go`

**Interfaces:**
- Produces: `func termValue(isTerminal bool, cols int, here string, env func(string) string) string`.

- [ ] **Step 1: Write failing test**

Add to `cmd/gitbay/term_test.go`:

```go
func TestTermValueHere(t *testing.T) {
	env := func(string) string { return "" }
	if got, want := termValue(true, 100, "krz/gitbay", env), "100,color,here=krz/gitbay"; got != want {
		t.Errorf("got %q, want %q", got, want)
	}
	if got := termValue(true, 100, "", env); strings.Contains(got, "here=") {
		t.Errorf("here= without a repository: %q", got)
	}
	if got := termValue(false, 100, "krz/gitbay", env); got != "" {
		t.Errorf("piped: %q", got)
	}
}
```

Update the existing `termValue(c.tty, c.cols, env(c.env))` call in `term_test.go:40` to `termValue(c.tty, c.cols, "", env(c.env))`.

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./cmd/gitbay/ -run TestTermValue`
Expected: build failure (too many arguments).

- [ ] **Step 3: Implement**

Change `termValue` to take `here` and append it last:

```go
func termValue(isTerminal bool, cols int, here string, env func(string) string) string {
	// ... existing body up to the links check unchanged ...
	if linksWanted(env) {
		v += ",links"
	}
	if here != "" {
		v += ",here=" + here
	}
	return v
}
```

Keep the `GITBAY_TERM=basic` early return as it is: an instance that old ignores `here=` anyway, and `basic` promises only width and colour. Add one sentence to the function's comment: "here is the repository inferred from the clone, for suggested commands to leave out."

In `runSSHPaged`, pass `t.repo`:

```go
	if v := termValue(isTTY, cols, t.repo, os.Getenv); v != "" && !slices.Contains(serverArgv, "--json") {
```

- [ ] **Step 4: Run tests**

Run: `go test ./cmd/gitbay/`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add cmd/gitbay/ssh.go cmd/gitbay/term_test.go
git commit -m "cli: send the inferred repository as here= in --term

Ref #317"
```

### Task 7: Test helpers for migrations — `checkActions` and `pinPlain`

**Files:**
- Modify: `internal/control/screen_test.go`
- Create: `internal/control/plain_test.go`

**Interfaces:**
- Produces (test-only): `func checkActions(t *testing.T, s screen)`; `func pinPlain(t *testing.T, name, got string)`; flag `-update-plain`.

- [ ] **Step 1: Write the helpers and their own tests**

Append to `screen_test.go`:

```go
// cliLocal are commands cmd/gitbay runs itself; the registry does not
// know them, but a legend may suggest them.
var cliLocal = map[string]bool{"mr rebase": true, "mr checkout": true, "repo clone": true}

// errorer is the part of *testing.T checkActions uses, so its own test
// can pass a recorder.
type errorer interface {
	Helper()
	Errorf(format string, args ...any)
}

type recorder struct{ failed bool }

func (r *recorder) Helper()                {}
func (r *recorder) Errorf(string, ...any) { r.failed = true }

// checkActions fails t for any legend or "more" command that the
// registry would not dispatch, or whose flags it would refuse.
func checkActions(t errorer, s screen) {
	t.Helper()
	var all [][]string
	for _, a := range s.actions {
		all = append(all, a.argv)
	}
	for _, sec := range s.sections {
		if len(sec.more) > 0 {
			all = append(all, sec.more)
		}
	}
	for _, argv := range all {
		if len(argv) >= 2 && cliLocal[argv[0]+" "+argv[1]] {
			continue
		}
		cmd, rest, ok := Lookup(argv)
		if !ok {
			t.Errorf("no command for %q", argv)
			continue
		}
		if err := checkFlags(cmd, rest); err != nil {
			t.Errorf("%q: %v", argv, err)
		}
	}
}

func TestCheckActionsCatchesTypos(t *testing.T) {
	r := &recorder{}
	checkActions(r, screen{actions: []action{{"Read", []string{"mr", "dif", "a/b", "1"}}}})
	if !r.failed {
		t.Error("a misspelled command passed")
	}
	r = &recorder{}
	checkActions(r, screen{actions: []action{{"Read", []string{"mr", "diff", "a/b", "1", "--bogus"}}}})
	if !r.failed {
		t.Error("an unknown flag passed")
	}
	r = &recorder{}
	checkActions(r, screen{actions: []action{{"Unblock", []string{"mr", "rebase", "1"}}}})
	if r.failed {
		t.Error("a CLI-local command failed")
	}
}
```

`checkFlags` reads the command's declared flags (`Command.Flags`, each with
`Name` and `Arg`; `Arg` empty for a switch), so no store is involved. Add it
to `screen_test.go`:

```go
// checkFlags refuses a flag the command does not declare, and a value
// flag with nothing after it. Words that are not flags are positionals.
func checkFlags(cmd Command, rest []string) error {
	takes := map[string]bool{}
	for _, f := range cmd.Flags {
		takes[f.Name] = f.Arg != ""
	}
	for i := 0; i < len(rest); i++ {
		a := rest[i]
		if !strings.HasPrefix(a, "--") {
			continue
		}
		name, _, inline := strings.Cut(a, "=")
		value, ok := takes[name]
		if !ok {
			return fmt.Errorf("%s does not take %s", joinPath(cmd.Path), name)
		}
		if value && !inline {
			if i+1 >= len(rest) {
				return fmt.Errorf("%s needs a value", name)
			}
			i++
		}
	}
	return nil
}
```

If a command in a legend declares no `Flags` but accepts some (an older
registration), add its `Flags` to the registration rather than loosening
the check; `TestCommandsDeclareFlags` or its equivalent may already
enforce this (`grep -n 'Flags' internal/control/help_test.go`).

Create `internal/control/plain_test.go`:

```go
package control

import (
	"flag"
	"os"
	"path/filepath"
	"regexp"
	"testing"
)

var updatePlain = flag.Bool("update-plain", false, "rewrite testdata/plain from the current output")

var plainStamp = regexp.MustCompile(`\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(:\d{2})?(Z| UTC)?`)

// pinPlain compares a command's piped output with the copy taken before
// its terminal screen was rewritten. Timestamps are masked; the fixture
// clock is the store's.
func pinPlain(t *testing.T, name, got string) {
	t.Helper()
	got = plainStamp.ReplaceAllString(got, "<time>")
	path := filepath.Join("testdata", "plain", name+".txt")
	if *updatePlain {
		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
			t.Fatal(err)
		}
		if err := os.WriteFile(path, []byte(got), 0o644); err != nil {
			t.Fatal(err)
		}
		return
	}
	want, err := os.ReadFile(path)
	if err != nil {
		t.Fatalf("%v: capture it with -update-plain before changing the command", err)
	}
	if got != string(want) {
		t.Errorf("piped output changed:\n--- want\n%s--- got\n%s", want, got)
	}
}
```

- [ ] **Step 2: Run**

Run: `go test ./internal/control/ -run 'TestCheckActions'`
Expected: PASS.

- [ ] **Step 3: Commit**

```bash
git add internal/control/screen_test.go internal/control/plain_test.go
git commit -m "control: test helpers for screen migrations

Ref #317"
```

### Task 8: Docs, changelog, MR

**Files:**
- Modify: `.gitbay/wiki/Users.org` ("Output rules" section)
- Modify: `CHANGELOG.org` (unreleased section at the top; create one headed `* Unreleased` if the top entry is a released version)

- [ ] **Step 1: Rewrite "Output rules"**

Replace the section's terminal-output rules with: the four parts of a screen and their order; the label/heading/row rules; the colour table; the glyph table; that a table names its columns only when one holds numbers; the legend and `here=`; that piped and `--json` output are unaffected. Keep the existing piped-output and exit-code rules as they are.

- [ ] **Step 2: Changelog entry**

```org
- Terminal output is drawn as screens (#317): lists drop
  their header row unless a column is a number, refs are dim rather than
  cyan, and state shows as a leading glyph where a screen has one. The
  next page is a =Next page= line with the command. The CLI sends the
  repository it inferred as =here== in =--term=, so suggested commands
  leave it out; an older instance ignores it. Piped and =--json= output
  are unchanged.
```

- [ ] **Step 3: Verify and push**

Run: `go build ./... && go vet ./... && go test ./internal/control/ ./cmd/gitbay/`
Expected: all PASS.

```bash
git add .gitbay/wiki/Users.org CHANGELOG.org
git commit -m "docs: screen output rules

Ref #317"
git push -u origin cli-views-1
gitbay mr create --source cli-views-1 --target main --title "control: screen renderer (stage 1 of CLI views)"
```

CI runs the e2e suite. `e2e/term_test.go` and any e2e test that matches a terminal header row or cyan may need its expectation updated; fix on the branch, amend, force-push.

---

## Stage 2a: show screens (one MR, Ref #318)

Each migration follows the same order: pin the piped output on the
unchanged code, write the screen test, write the builder, switch the
command to `emitView`, confirm the pin still matches.

### Task 9: `gitutil.DiffNumstat`

**Files:**
- Create: `internal/gitutil/numstat.go`
- Test: `internal/gitutil/numstat_test.go`

**Interfaces:**
- Produces:

```go
type NumStat struct {
	Path    string
	Added   int // -1 for a binary file
	Deleted int // -1 for a binary file
	Status  string // "A", "M", "D", "R"
}
func DiffNumstat(dir, base, head string) ([]NumStat, error)
```

- [ ] **Step 1: Write failing test**

Use the package's existing test-repository helper (`grep -n 'func.*testRepo\|func initRepo' internal/gitutil/*_test.go`) to make a repo with a base commit, then a commit that modifies one file (+2 −1), adds one, and adds a binary file. Assert:

```go
	want := []NumStat{
		{Path: "a.txt", Added: 2, Deleted: 1, Status: "M"},
		{Path: "bin.dat", Added: -1, Deleted: -1, Status: "A"},
		{Path: "new.txt", Added: 1, Deleted: 0, Status: "A"},
	}
```

- [ ] **Step 2: Run to confirm failure**

Run: `go test ./internal/gitutil/ -run TestDiffNumstat`
Expected: `undefined: DiffNumstat`.

- [ ] **Step 3: Implement**

```go
package gitutil

import (
	"fmt"
	"os/exec"
	"strconv"
	"strings"

	"gitbay.org/krz/gitbay/internal/toolpath"
)

// NumStat is one file's line counts between two commits. A binary file
// counts -1 each way.
type NumStat struct {
	Path    string
	Added   int
	Deleted int
	Status  string
}

// DiffNumstat lists the files changed from base to head, sorted by path,
// with line counts and A/M/D/R status. Renames are detected.
func DiffNumstat(dir, base, head string) ([]NumStat, error) {
	run := func(args ...string) (string, error) {
		cmd := exec.Command(toolpath.Look("git"), append([]string{"-C", dir}, args...)...)
		out, err := cmd.Output()
		if err != nil {
			return "", fmt.Errorf("git %s: %w", args[0], err)
		}
		return string(out), nil
	}
	num, err := run("diff", "--numstat", "-z", "-M", "--end-of-options", base, head)
	if err != nil {
		return nil, err
	}
	names, err := run("diff", "--name-status", "-z", "-M", "--end-of-options", base, head)
	if err != nil {
		return nil, err
	}
	status := map[string]string{}
	f := strings.Split(strings.TrimSuffix(names, "\x00"), "\x00")
	for i := 0; i < len(f); {
		s := f[i]
		if strings.HasPrefix(s, "R") || strings.HasPrefix(s, "C") {
			if i+2 < len(f) {
				status[f[i+2]] = s[:1]
			}
			i += 3
			continue
		}
		if i+1 < len(f) {
			status[f[i+1]] = s[:1]
		}
		i += 2
	}
	var out []NumStat
	recs := strings.Split(strings.TrimSuffix(num, "\x00"), "\x00")
	for i := 0; i < len(recs); i++ {
		parts := strings.SplitN(recs[i], "\t", 3)
		if len(parts) != 3 {
			continue
		}
		path := parts[2]
		if path == "" && i+2 < len(recs) { // rename: "a\td\t" then old, new
			path = recs[i+2]
			i += 2
		}
		ns := NumStat{Path: path, Added: -1, Deleted: -1, Status: status[path]}
		if parts[0] != "-" {
			ns.Added, _ = strconv.Atoi(parts[0])
			ns.Deleted, _ = strconv.Atoi(parts[1])
		}
		out = append(out, ns)
	}
	return out, nil
}
```

Check the `toolpath` import path against `merge.go`'s imports and match it.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/gitutil/ -run TestDiffNumstat`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/gitutil/numstat.go internal/gitutil/numstat_test.go
git commit -m "gitutil: DiffNumstat

Ref #318"
```

### Task 10: `mr show` screen

**Files:**
- Modify: `internal/control/mr.go` (`runMRShow` at line 739; new `mrShowScreen`)
- Test: `internal/control/mrscreen_test.go` (new), `internal/control/testdata/plain/mr-show.txt` (new)

**Interfaces:**
- Consumes: `screen` types, `emitView`, `cGlyph`, `cYou`, `cMeta`, `checksMark` (`marks.go:15`), `gitutil.DiffNumstat`.
- Produces: `func mrShowScreen(c *Ctx, repo store.Repo, d MRShow, files []gitutil.NumStat) screen`.

- [ ] **Step 1: Pin the piped output on unchanged code**

`internal/control/mrscreen_test.go`:

```go
package control

import (
	"testing"

	"gitbay.org/krz/gitbay/internal/gitutil"
	"gitbay.org/krz/gitbay/internal/protocol"
)

func TestMRShowPlainPinned(t *testing.T) {
	st, repo, owner := twoMRTestRepo(t)
	c, out, errOut := mrTestCtx(st, owner)
	if code := Dispatch(c, []string{"mr", "show", repo.Path(), "1"}); code != protocol.ExitOK {
		t.Fatalf("exit %d: %s", code, errOut)
	}
	pinPlain(t, "mr-show", out.String())
}
```

Run: `go test ./internal/control/ -run TestMRShowPlainPinned -update-plain`
then `go test ./internal/control/ -run TestMRShowPlainPinned`
Expected: PASS both times; `testdata/plain/mr-show.txt` exists.

- [ ] **Step 2: Write the failing screen tests**

```go
func mrShowFixture() MRShow {
	d := MRShow{mrOut: mrOut{Number: 552, Title: "wire $PAGER through long views", State: "open",
		Author: "cmc", Source: "cli-pager", TargetRef: "main", Body: "Pages long views.", BodyFormat: "markdown",
		CreatedAt: "2026-10-01T11:40:00Z"}}
	d.Commits = []CommitOut{{"8f3a1c2aaaaaaaa", "cli: page long output"}, {"2b77e90bbbbbbbb", "control: mark views"}}
	d.Checks = []CheckOut{{Context: "test", State: "pending"}, {Context: "build", State: "success"}}
	d.Gates = &GatesOut{ApprovalsRequired: 1, FastForward: false, Unmet: []string{"needs 1 approval", "behind main"}}
	return d
}

func actionArgvs(s screen, group string) [][]string {
	var out [][]string
	for _, a := range s.actions {
		if a.group == group {
			out = append(out, a.argv)
		}
	}
	return out
}

func TestMRShowScreenBehind(t *testing.T) {
	c := screenCtx(100, false)
	repo := store.Repo{OwnerName: "krz", Name: "gitbay", DefaultBranch: "main"}
	s := mrShowScreen(c, repo, mrShowFixture(), []gitutil.NumStat{{Path: "cmd/gitbay/ssh.go", Added: 41, Deleted: 6, Status: "M"}})
	if got := actionArgvs(s, "Unblock"); len(got) != 1 || got[0][1] != "rebase" {
		t.Errorf("Unblock = %q, want mr rebase", got)
	}
	if got := actionArgvs(s, "Merge"); len(got) != 0 {
		t.Errorf("Merge offered with unmet gates: %q", got)
	}
	titles := map[string]int{}
	for _, sec := range s.sections {
		titles[sec.title] = sec.n
	}
	if titles["Commits"] != 2 || titles["Files"] != 1 {
		t.Errorf("sections = %v", titles)
	}
	checkActions(t, s)
}

func TestMRShowScreenReady(t *testing.T) {
	c := screenCtx(100, false)
	d := mrShowFixture()
	d.Gates = &GatesOut{FastForward: true}
	repo := store.Repo{OwnerName: "krz", Name: "gitbay", DefaultBranch: "main"}
	s := mrShowScreen(c, repo, d, nil)
	if len(actionArgvs(s, "Unblock")) != 0 {
		t.Error("Unblock offered when nothing blocks")
	}
	if got := actionArgvs(s, "Merge"); len(got) != 1 || got[0][1] != "merge" {
		t.Errorf("Merge = %q", got)
	}
	checkActions(t, s)
}

func TestMRShowScreenClosedOffersNoWrites(t *testing.T) {
	c := screenCtx(100, false)
	d := mrShowFixture()
	d.State, d.Gates = "merged", nil
	s := mrShowScreen(c, store.Repo{OwnerName: "krz", Name: "gitbay"}, d, nil)
	for _, a := range s.actions {
		if a.group != "Read" {
			t.Errorf("merged MR offers %q", a.argv)
		}
	}
}
```

Add `store` to the imports.

Run: `go test ./internal/control/ -run TestMRShowScreen`
Expected: `undefined: mrShowScreen`.

- [ ] **Step 3: Implement `mrShowScreen`**

Add to `mr.go` after `runMRShow`:

```go
// mrShowScreen is mr show at a terminal: where the merge request stands,
// its description, its commits, files and discussion, and what can be
// done about it now.
func mrShowScreen(c *Ctx, repo store.Repo, d MRShow, files []gitutil.NumStat) screen {
	n := strconv.FormatInt(d.Number, 10)
	path := repo.Path()
	state := d.State
	if d.Draft {
		state = "draft"
	}
	s := screen{body: d.Body, format: d.BodyFormat}

	s.fields = append(s.fields,
		field{"Merge", []cell{cLink("!"+n, c.siteURL(path, "mrs", n)), cText(d.Title)}},
		field{"State", []cell{cState(state), cMeta(d.Source+" → "+d.TargetRef, d.Author, relAge(d.CreatedAt, termNow()))}},
	)
	if len(d.Checks) > 0 {
		var sts []store.CommitStatus
		for _, x := range d.Checks {
			sts = append(sts, store.CommitStatus{Context: x.Context, State: x.State})
		}
		m := checksMark(sts)
		s.fields = append(s.fields, field{"Checks", []cell{m}})
	}
	open := d.State == "open" || d.State == "source_gone"
	behind := false
	if g := d.Gates; g != nil && open {
		var parts []string
		for _, u := range g.Unmet {
			parts = append(parts, "✗ "+u)
		}
		behind = !g.FastForward
		if len(parts) == 0 {
			s.fields = append(s.fields, field{"Gates", []cell{cMark("✓ ready to merge", sgrGreen)}})
		} else {
			s.fields = append(s.fields, field{"Gates", []cell{cMark(strings.Join(parts, " · "), sgrRed)}})
		}
	}
	if len(d.ReviewRequests) > 0 {
		v := cText("requested of " + strings.Join(d.ReviewRequests, ", "))
		if slices.Contains(d.ReviewRequests, c.User.Username) {
			v.sgr = sgrYellow
		}
		s.fields = append(s.fields, field{"Review", []cell{v}})
	}
	if d.Milestone != "" {
		s.fields = append(s.fields, field{"Milestone", []cell{cText(d.Milestone)}})
	}
	if len(d.Labels) > 0 {
		s.fields = append(s.fields, field{"Labels", []cell{cText(strings.Join(d.Labels, ", "))}})
	}
	if !c.Term.Links {
		s.fields = append(s.fields, field{"URL", []cell{cText(c.siteURL(path, "mrs", n))}})
	}

	commits := section{title: "Commits", n: len(d.Commits)}
	for _, cm := range d.Commits {
		commits.rows = append(commits.rows, rowOf(cRef(fmt.Sprintf("%.7s", cm.SHA)), cFlex(cm.Subject)))
	}
	add, del := 0, 0
	filesSec := section{n: len(files)}
	for _, f := range files {
		counts := "binary"
		if f.Added >= 0 {
			add, del = add+f.Added, del+f.Deleted
			counts = fmt.Sprintf("+%d −%d", f.Added, f.Deleted)
		}
		filesSec.rows = append(filesSec.rows, rowOf(cRef(f.Status), cFlex(f.Path), cMeta(counts)))
	}
	filesSec.title = fmt.Sprintf("Files  +%d −%d", add, del)
	if len(files) == 0 {
		filesSec.title = "Files"
	}
	disc := section{title: "Discussion", empty: true}
	for _, cm := range d.Comments {
		if cm.Kind == "system" {
			continue
		}
		disc.n++
		disc.rows = append(disc.rows, row{cells: []cell{cText(cm.Author), cMeta(relAge(cm.CreatedAt, termNow()))}, body: cm.Body, format: cm.BodyFormat})
	}
	s.sections = []section{commits, filesSec, disc}

	if open {
		if behind {
			s.actions = append(s.actions, action{"Unblock", []string{"mr", "rebase", n}})
		}
		s.actions = append(s.actions,
			action{"Review", []string{"mr", "review", path, n, "--approve"}},
			action{"Review", []string{"mr", "comment", path, n}},
		)
		if d.Gates != nil && len(d.Gates.Unmet) == 0 {
			s.actions = append(s.actions, action{"Merge", []string{"mr", "merge", path, n}})
		}
	}
	s.actions = append(s.actions, action{"Read", []string{"mr", "diff", path, n}})
	return s
}
```

Notes for the implementer:
- `mr rebase` is CLI-local and infers the repository from the clone, so it takes only the number.
- The "Files" title carries the totals as the spec's `Files (n) +a −d`; `renderSection` prints `title (n)`, so title `Files  +86 −12` with `n: 4` renders as `Files  +86 −12 (4)`. If that reads badly in the golden, add an optional `note string` to `section` drawn dim after the count, and use it here instead. Decide when you see the render; keep the test on `n`.

In `runMRShow`, compute files only at a terminal and switch to `emitView`:

```go
	var files []gitutil.NumStat
	if c.Term.Cols > 0 && !c.JSON && base != "" {
		files, _ = gitutil.DiffNumstat(dir, base, mrHeadRef(mr.Number))
	}
	return c.emitView(d, func(w io.Writer) {
		// existing plain closure, unchanged
	}, func() screen { return mrShowScreen(c, repo, d, files) })
```

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestMRShow'`
Expected: all PASS, including `TestMRShowPlainPinned` against the pin taken in step 1.

- [ ] **Step 5: Look at it**

Build and run against a scratch instance or production read-only:

```bash
go build -o /tmp/gitbay ./cmd/gitbay && /tmp/gitbay mr show krz/gitbay 551
```

The server renders, so this shows the new screen only after deploy; until then, render from a test: add a temporary `t.Log(renderString(c, s))` in `TestMRShowScreenBehind`, run with `-v`, read it, remove the log.

- [ ] **Step 6: Commit**

```bash
git add internal/control/mr.go internal/control/mrscreen_test.go internal/control/testdata/plain/mr-show.txt
git commit -m "control: mr show as a screen

Ref #318"
```

### Task 11: `issue show` screen

**Files:**
- Modify: `internal/control/issue.go` (`runIssueShow` at line 381; new `issueShowScreen`)
- Test: `internal/control/issuescreen_test.go` (new), `testdata/plain/issue-show.txt`

**Interfaces:**
- Produces: `func issueShowScreen(c *Ctx, repo store.Repo, d IssueShow, canWrite bool) screen`.

- [ ] **Step 1: Pin piped output**

```go
func TestIssueShowPlainPinned(t *testing.T) {
	st, repo, uid := newQueueTestRepo(t)
	owner := store.User{ID: uid, Username: "alice"}
	id, err := st.CreateIssue(repo.ID, uid, "Android app", "An app.", "markdown")
	if err != nil {
		t.Fatal(err)
	}
	if err := st.AddIssueComment(id, uid, "Started.", "markdown"); err != nil {
		t.Fatal(err)
	}
	c, out, errOut := mrTestCtx(st, owner)
	if code := Dispatch(c, []string{"issue", "show", repo.Path(), "1"}); code != protocol.ExitOK {
		t.Fatalf("exit %d: %s", code, errOut)
	}
	pinPlain(t, "issue-show", out.String())
}
```

Run with `-update-plain`, then without. Expected: PASS.

- [ ] **Step 2: Failing screen tests**

```go
func issueFixture() IssueShow {
	return IssueShow{issueOut: issueOut{Number: 12, Title: "Android app", State: "open", Author: "cmc",
		Labels: []string{"mobile"}, Assignees: []string{"alice"}, Body: "An app.", BodyFormat: "markdown",
		CreatedAt: "2026-08-21T10:00:00Z"},
		Comments: []commentOut{{ID: 1, Author: "cmc", Body: "Started.", BodyFormat: "markdown", CreatedAt: "2026-09-01T10:00:00Z", Kind: "comment"},
			{ID: 2, Author: "cmc", Body: "labelled mobile", CreatedAt: "2026-09-01T10:00:00Z", Kind: "system"}}}
}

func TestIssueShowScreen(t *testing.T) {
	c := screenCtx(100, false)
	c.User = store.User{Username: "alice"}
	repo := store.Repo{OwnerName: "krz", Name: "gitbay"}
	s := issueShowScreen(c, repo, issueFixture(), true)
	if len(s.sections) != 1 || s.sections[0].title != "Discussion" || s.sections[0].n != 1 {
		t.Errorf("sections = %+v", s.sections)
	}
	var verbs []string
	for _, a := range s.actions {
		verbs = append(verbs, a.argv[1])
	}
	if !slices.Equal(verbs, []string{"comment", "assign", "label", "close"}) {
		t.Errorf("actions = %q", verbs)
	}
	checkActions(t, s)
}

func TestIssueShowScreenReaderOnlyComments(t *testing.T) {
	c := screenCtx(100, false)
	c.User = store.User{Username: "bob"}
	s := issueShowScreen(c, store.Repo{OwnerName: "krz", Name: "gitbay"}, issueFixture(), false)
	if len(s.actions) != 1 || s.actions[0].argv[1] != "comment" {
		t.Errorf("reader actions = %+v", s.actions)
	}
}
```

Expected on run: `undefined: issueShowScreen`.

- [ ] **Step 3: Implement**

```go
// issueShowScreen is issue show at a terminal. canWrite is write access
// or authorship: what lets the viewer close, assign and label.
func issueShowScreen(c *Ctx, repo store.Repo, d IssueShow, canWrite bool) screen {
	n := strconv.FormatInt(d.Number, 10)
	path := repo.Path()
	s := screen{body: d.Body, format: d.BodyFormat}
	s.fields = append(s.fields,
		field{"Issue", []cell{cLink("#"+n, c.siteURL(path, "issues", n)), cText(d.Title)}},
		field{"State", []cell{cState(d.State), cMeta(d.Author, relAge(d.CreatedAt, termNow()))}},
	)
	if len(d.Labels) > 0 {
		s.fields = append(s.fields, field{"Labels", []cell{cText(strings.Join(d.Labels, ", "))}})
	}
	if len(d.Assignees) > 0 {
		v := cText(strings.Join(d.Assignees, ", "))
		if slices.Contains(d.Assignees, c.User.Username) {
			v.sgr = sgrYellow
		}
		s.fields = append(s.fields, field{"Assignee", []cell{v}})
	}
	if d.Milestone != "" {
		s.fields = append(s.fields, field{"Milestone", []cell{cText(d.Milestone)}})
	}
	if !c.Term.Links {
		s.fields = append(s.fields, field{"URL", []cell{cText(c.siteURL(path, "issues", n))}})
	}
	disc := section{title: "Discussion", empty: true}
	for _, cm := range d.Comments {
		if cm.Kind == "system" {
			continue
		}
		disc.n++
		disc.rows = append(disc.rows, row{cells: []cell{cText(cm.Author), cMeta(relAge(cm.CreatedAt, termNow()))}, body: cm.Body, format: cm.BodyFormat})
	}
	s.sections = []section{disc}

	s.actions = append(s.actions, action{"Discuss", []string{"issue", "comment", path, n}})
	if canWrite {
		s.actions = append(s.actions,
			action{"Triage", []string{"issue", "assign", path, n, "--add", c.User.Username}},
			action{"Triage", []string{"issue", "label", path, n, "--add", "<label>"}},
		)
		verb := "close"
		if d.State == "closed" {
			verb = "reopen"
		}
		s.actions = append(s.actions, action{"State", []string{"issue", verb, path, n}})
	}
	return s
}
```

Check `issue assign` and `issue label` flags with `ssh git@gitbay.org help issue assign` and `help issue label`; adjust the argv to the real flags. A literal `<label>` placeholder in a suggested command is acceptable in the legend (it is what the user fills in) but `checkActions` will parse it as a value; that is fine.

In `runIssueShow`, compute `canWrite` with the same rule `setIssueState` uses (author, or `policy.CanWrite` on the access role) only at a terminal, and switch to `emitView(d, plain, func() screen { return issueShowScreen(c, repo, d, canWrite) })`.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestIssueShow'`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/control/issue.go internal/control/issuescreen_test.go internal/control/testdata/plain/issue-show.txt
git commit -m "control: issue show as a screen

Ref #318"
```

### Task 12: `repo show` screen

**Files:**
- Modify: `internal/control/repo.go` (`runRepoShow` at line 376, `repoGlance`, new `repoShowScreen`)
- Test: `internal/control/reposcreen_test.go` (new), `testdata/plain/repo-show.txt`

**Interfaces:**
- Produces: `func repoShowScreen(c *Ctx, d repoShowOut, g repoGlance, mrs []store.MR, issues []store.Issue, commits []CommitOut) screen`. Hoist the local `type out struct` in `runRepoShow` to package level as `repoShowOut` (and `mirrorOut` as `repoMirrorOut`) so the builder can take it; the JSON tags do not change.

- [ ] **Step 1: Pin piped output**

```go
func TestRepoShowPlainPinned(t *testing.T) {
	st, repo, uid := newQueueTestRepo(t)
	c, out, errOut := mrTestCtx(st, store.User{ID: uid, Username: "alice"})
	if code := Dispatch(c, []string{"repo", "show", repo.Path()}); code != protocol.ExitOK {
		t.Fatalf("exit %d: %s", code, errOut)
	}
	pinPlain(t, "repo-show", out.String())
}
```

Run with `-update-plain`, then without. Expected: PASS. Then hoist the types; run again; still PASS.

- [ ] **Step 2: Failing screen test**

```go
func TestRepoShowScreen(t *testing.T) {
	c := screenCtx(100, false)
	d := repoShowOut{Path: "krz/gitbay", Description: "A CLI-first git forge.", Visibility: "public", DefaultBranch: "main",
		Topics: []string{"cli", "forge"}}
	g := repoGlance{clone: "ssh://git@gitbay.org/krz/gitbay.git", release: "v1.41.0, 2h ago", checks: "✓ 2/2 on main"}
	mrs := []store.MR{{Number: 552, Title: "wire $PAGER", UpdatedAt: "2026-10-01T11:40:00Z"}}
	s := repoShowScreen(c, d, g, mrs, nil, []CommitOut{{"a136534ff9", "changelog: v1.41.0"}})
	got := map[string]int{}
	for _, sec := range s.sections {
		got[sec.title] = sec.n
	}
	if got["Open merge requests"] != 1 || got["Recent commits"] != 1 {
		t.Errorf("sections = %v", got)
	}
	if _, ok := got["Open issues"]; ok && got["Open issues"] == 0 && len(s.sections) == 3 {
		// an empty section with no rows is not drawn; it may be present in the model
	}
	checkActions(t, s)
}
```

Expected on run: `undefined: repoShowScreen`.

- [ ] **Step 3: Implement**

`repoAtAGlance` keeps its fields; add the counts as ints (`issues, mrs int`) beside the strings so sections can carry totals, and fill them from `c.Store.OpenCounts`.

```go
// repoShowScreen is repo show at a terminal: how to clone it, where the
// default branch stands, what is open, and the latest commits.
func repoShowScreen(c *Ctx, d repoShowOut, g repoGlance, mrs []store.MR, issues []store.Issue, commits []CommitOut) screen {
	s := screen{body: d.Description, format: "text"}
	name := []cell{cLink(d.Path, c.siteURL(d.Path)), cState(d.Visibility)}
	if d.Archived {
		name = append(name, cState("archived"))
	}
	s.fields = append(s.fields, field{"Repo", name}, field{"Clone", []cell{cText(g.clone)}})
	head := []cell{cText(d.DefaultBranch)}
	if g.checks != "" {
		head = append(head, cText(strings.TrimSuffix(g.checks, " on "+d.DefaultBranch)))
	}
	s.fields = append(s.fields, field{"Head", head})
	if g.release != "" {
		s.fields = append(s.fields, field{"Release", []cell{cText(g.release)}})
	}
	if len(d.Topics) > 0 {
		s.fields = append(s.fields, field{"Topics", []cell{cText(strings.Join(d.Topics, ", "))}})
	}
	if d.ForkOf != "" {
		s.fields = append(s.fields, field{"Fork of", []cell{cRef(d.ForkOf)}})
	}
	for _, m := range d.Mirrors {
		if m.LastError != "" {
			s.fields = append(s.fields, field{"Mirror", []cell{cGlyph("failed"), cText(m.Direction + " " + m.URL + ": " + m.LastError)}})
		}
	}
	if !c.Term.Links {
		s.fields = append(s.fields, field{"URL", []cell{cText(c.siteURL(d.Path))}})
	}

	ms := section{title: "Open merge requests", n: g.mrsN, more: []string{"mr", "list", d.Path}}
	for _, m := range mrs {
		ms.rows = append(ms.rows, rowOf(cRef(fmt.Sprintf("!%d", m.Number)), cFlex(m.Title), cAge(m.UpdatedAt)))
	}
	is := section{title: "Open issues", n: g.issuesN, more: []string{"issue", "list", d.Path}}
	for _, i := range issues {
		is.rows = append(is.rows, rowOf(cRef(fmt.Sprintf("#%d", i.Number)), cFlex(i.Title), cAge(i.UpdatedAt)))
	}
	cs := section{title: "Recent commits", n: len(commits), more: []string{"repo", "log", d.Path}}
	for _, cm := range commits {
		cs.rows = append(cs.rows, rowOf(cRef(fmt.Sprintf("%.7s", cm.SHA)), cFlex(cm.Subject)))
	}
	s.sections = []section{ms, is, cs}
	s.actions = []action{
		{"Contribute", []string{"mr", "create", d.Path}},
		{"Contribute", []string{"issue", "create", d.Path}},
		{"Read", []string{"repo", "log", d.Path}},
	}
	return s
}
```

`Recent commits` sets `more`, but `n == len(rows)` so no "+n more" line prints; that is intended. In `runRepoShow`, at a terminal only, read up to 5 open MRs (`c.Store.QueryMRs` or the function `runMRList` uses, with `State: "open", Limit: 5`), up to 5 open issues (`c.Store.QueryIssues(repo.ID, store.IssueFilter{State: "open", Limit: 5})`), and 5 commits (the helper `repo log` uses; `grep -n 'func runRepoLog' internal/control/*.go` and reuse what it calls). Then `emitView(d, plain, func() screen { return repoShowScreen(c, d, glance, mrs, issues, commits) })`. The plain closure keeps only its `else` branch: delete the `c.Term.Cols > 0` branch inside it, since a terminal no longer reaches it.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestRepoShow'`
Expected: PASS, pin unchanged.

- [ ] **Step 5: Commit**

```bash
git add internal/control/repo.go internal/control/reposcreen_test.go internal/control/testdata/plain/repo-show.txt
git commit -m "control: repo show as a screen

Ref #318"
```

### Task 13: `build show` screen

**Files:**
- Modify: `internal/control/build.go` (`runBuildShow` at line 240, new `buildShowScreen`)
- Test: `internal/control/buildscreen_test.go` (new), `testdata/plain/build-show.txt`

**Interfaces:**
- Produces: `func buildShowScreen(c *Ctx, repo store.Repo, d BuildOut, mr *store.MR) screen`.

- [ ] **Step 1: Pin piped output**

```go
func TestBuildShowPlainPinned(t *testing.T) {
	st, repo, uid := newQueueTestRepo(t)
	id, err := st.CreateBuild(repo.ID, "test", "a136534ff9a136534ff9a136534ff9a136534ff9", "main", `["go vet ./...","go test ./..."]`, "", "", true)
	if err != nil {
		t.Fatal(err)
	}
	if err := st.FinishBuild(id, "success"); err != nil {
		t.Fatal(err)
	}
	c, out, errOut := mrTestCtx(st, store.User{ID: uid, Username: "alice"})
	if code := Dispatch(c, []string{"build", "show", repo.Path(), "1"}); code != protocol.ExitOK {
		t.Fatalf("exit %d: %s", code, errOut)
	}
	pinPlain(t, "build-show", out.String())
}
```

If the build number is not 1, read it back with the store's build-by-id accessor and pass that number. Run with `-update-plain`, then without.

- [ ] **Step 2: Failing screen test**

```go
func TestBuildShowScreenFailed(t *testing.T) {
	c := screenCtx(100, false)
	d := BuildOut{Number: 83, Job: "daily-pull", Status: "failure", SHA: "355b04066b", Ref: "main",
		Steps: []string{"setup", "pull", "publish"}, FailedStep: 2, FailedReason: "exit 1", DurationS: 74}
	s := buildShowScreen(c, store.Repo{OwnerName: "krz", Name: "omaha-metro-blotter"}, d, nil)
	steps := s.sections[0]
	if steps.title != "Steps" || steps.n != 3 {
		t.Fatalf("steps = %+v", steps)
	}
	if g := steps.rows[1].cells[0]; g.s != "✗" {
		t.Errorf("failed step glyph = %q", g.s)
	}
	if g := steps.rows[2].cells[0]; g.s != "" {
		t.Errorf("step after the failure = %q, want no glyph", g.s)
	}
	if len(s.actions) != 1 || s.actions[0].argv[1] != "log" {
		t.Errorf("actions = %+v", s.actions)
	}
	checkActions(t, s)
}
```

Expected on run: `undefined: buildShowScreen`.

- [ ] **Step 3: Implement**

```go
// buildShowScreen is build show at a terminal: the build's outcome, what
// it ran on, each step's outcome, and the command for its log.
func buildShowScreen(c *Ctx, repo store.Repo, d BuildOut, mr *store.MR) screen {
	n := strconv.FormatInt(d.Number, 10)
	path := repo.Path()
	var s screen
	s.fields = append(s.fields,
		field{"Build", []cell{cLink(n, c.siteURL(path, "builds", n)), cText(d.Job)}},
		field{"State", []cell{cGlyph(d.Status), cState(d.Status)}},
		field{"Commit", []cell{cRef(fmt.Sprintf("%.10s", d.SHA)), cText(d.Subject)}},
		field{"Ref", []cell{cText(d.Ref)}},
	)
	if mr != nil {
		s.fields = append(s.fields, field{"MR", []cell{cRef(fmt.Sprintf("!%d", mr.Number)), cText(mr.Title)}})
	}
	if d.DurationS > 0 {
		s.fields = append(s.fields, field{"Duration", []cell{cText(c.Term.dur(d.DurationS))}})
	}
	if !c.Term.Links {
		s.fields = append(s.fields, field{"URL", []cell{cText(c.siteURL(path, "builds", n))}})
	}
	steps := section{title: "Steps", n: len(d.Steps)}
	for i, step := range d.Steps {
		line, _, _ := strings.Cut(step, "\n")
		state := stepState(d.Status, d.FailedStep, i+1)
		meta := ""
		if i+1 == d.FailedStep {
			meta = d.FailedReason
		}
		steps.rows = append(steps.rows, rowOf(cGlyph(state), cFlex(line), cMeta(meta)))
	}
	s.sections = []section{steps}
	s.actions = []action{{"Read", []string{"build", "log", path, n}}}
	return s
}
```

Check what `stepState` returns for steps after a failure (the comment says they "never ran"); if it returns a word `glyph` maps to `○` ("skipped"), change the test's third assertion to `○`. In `runBuildShow`, move the `OpenMRBySource` lookup out of the plain closure into a terminal-only block before `emitView`, and drop the plain closure's `c.Term.Cols > 0` code (the `mr`/`logCmd` fields and the steps table), which only a terminal reached.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestBuildShow'`
Expected: PASS, pin unchanged.

- [ ] **Step 5: Commit, verify, MR**

```bash
git add internal/control/build.go internal/control/buildscreen_test.go internal/control/testdata/plain/build-show.txt
git commit -m "control: build show as a screen

Ref #318"
go build ./... && go vet ./... && go test ./internal/control/ ./internal/gitutil/
git push -u origin cli-views-2a
gitbay mr create --source cli-views-2a --target main --title "control: show screens (stage 2a of CLI views)"
```

Add a CHANGELOG line under the unreleased section naming the four screens before pushing.

---

## Stage 2b: lists and dashboard (one MR, Ref #318)

### Task 14: `mr list`, `issue list`, `build list` screens

**Files:**
- Modify: `internal/control/mr.go` (`mrListTerm` at line 711 and its caller), `issue.go` (`runIssueList` terminal branch), `build.go` (`runBuildList`)
- Test: `internal/control/listscreen_test.go` (new), `testdata/plain/{mr,issue,build}-list.txt`

**Interfaces:**
- Produces:

```go
func mrListScreen(c *Ctx, repo store.Repo, state string, mrs []store.MR, ds []mrOut, checks, review map[int64]cell) screen
func issueListScreen(c *Ctx, repo store.Repo, state string, issues []store.Issue, ds []issueOut, comments map[int64]int, labels, assignees map[int64][]string) screen
func buildListScreen(c *Ctx, repo store.Repo, ds []BuildOut) screen
```

- [ ] **Step 1: Pin piped output for all three**

```go
func TestListsPlainPinned(t *testing.T) {
	st, repo, owner := twoMRTestRepo(t)
	if _, err := st.CreateIssue(repo.ID, owner.ID, "Android app", "", "markdown"); err != nil {
		t.Fatal(err)
	}
	if _, err := st.CreateBuild(repo.ID, "test", "abc111", "main", `["go test ./..."]`, "", "", true); err != nil {
		t.Fatal(err)
	}
	for name, argv := range map[string][]string{
		"mr-list":    {"mr", "list", repo.Path()},
		"issue-list": {"issue", "list", repo.Path()},
		"build-list": {"build", "list", repo.Path()},
	} {
		c, out, errOut := mrTestCtx(st, owner)
		if code := Dispatch(c, argv); code != protocol.ExitOK {
			t.Fatalf("%s: exit %d: %s", name, code, errOut)
		}
		pinPlain(t, name, out.String())
	}
}
```

Run with `-update-plain`, then without.

- [ ] **Step 2: Failing screen tests**

```go
func TestMRListScreen(t *testing.T) {
	c := screenCtx(100, false)
	c.User = store.User{Username: "alice"}
	repo := store.Repo{OwnerName: "krz", Name: "gitbay", DefaultBranch: "main"}
	mrs := []store.MR{{ID: 1, Number: 552, UpdatedAt: "2026-10-01T11:40:00Z"}}
	ds := []mrOut{{Number: 552, Title: "wire $PAGER", State: "open", Source: "cli-pager", TargetRef: "main"}}
	checks := map[int64]cell{1: cMark("✓ 2/2", sgrGreen)}
	review := map[int64]cell{1: cMark("review requested", sgrYellow)}
	s := mrListScreen(c, repo, "open", mrs, ds, checks, review)
	if len(s.sections) != 1 || s.sections[0].title != "Open merge requests" || s.sections[0].n != 1 {
		t.Fatalf("sections = %+v", s.sections)
	}
	if g := s.sections[0].rows[0].cells[1]; g.s != "●" {
		t.Errorf("review requested of the viewer should lead with ●, got %q", g.s)
	}
	var verbs []string
	for _, a := range s.actions {
		verbs = append(verbs, strings.Join(a.argv[:2], " "))
	}
	if !slices.Equal(verbs, []string{"mr create", "mr list"}) {
		t.Errorf("actions = %q", verbs)
	}
	checkActions(t, s)
}
```

Write the equivalent `TestIssueListScreen` (assigned to the viewer leads with `●`; title `Open issues`; actions `issue create`, `issue list --state closed`) and `TestBuildListScreen` (glyph from status; title `Builds`; no state filter action).

Expected on run: undefined builders.

- [ ] **Step 3: Implement**

```go
// mrListScreen is mr list at a terminal: one section of merge requests,
// each led by ● when it waits on the viewer or its checks' mark, then
// title, branch, review and age.
func mrListScreen(c *Ctx, repo store.Repo, state string, mrs []store.MR, ds []mrOut, checks, review map[int64]cell) screen {
	title := map[string]string{"open": "Open merge requests", "closed": "Closed merge requests", "merged": "Merged merge requests", "all": "Merge requests"}[state]
	sec := section{title: title, n: len(ds)}
	for i, d := range ds {
		m := mrs[i]
		lead := checks[m.ID]
		lead.kind = kindGlyph
		lead.s, _, _ = strings.Cut(lead.s, " ")
		if r := review[m.ID]; r.sgr == sgrYellow {
			lead = cYou()
		}
		branch := d.Source
		if d.TargetRef != repo.DefaultBranch {
			branch += " → " + d.TargetRef
		}
		ref := cLink(fmt.Sprintf("!%d", d.Number), c.siteURL(repo.Path(), "mrs", strconv.FormatInt(d.Number, 10)))
		sec.rows = append(sec.rows, rowOf(ref, lead, cFlex(d.Title), cMeta(branch, review[m.ID].s, relAge(m.UpdatedAt, termNow()))))
	}
	s := screen{sections: []section{sec}}
	s.actions = append(s.actions, action{"New", []string{"mr", "create", repo.Path()}})
	other := "all"
	if state == "all" {
		other = "open"
	}
	s.actions = append(s.actions, action{"Filter", []string{"mr", "list", repo.Path(), "--state", other}})
	return s
}
```

`issueListScreen` follows the same shape: lead `cYou()` when `assigneesMark` would colour the viewer yellow, otherwise `cGlyph(d.State)`; text the title; meta labels, assignees, comment count (`"3 comments"`), age. `buildListScreen`: lead `cGlyph(d.Status)`, ref the number, text `job  ref`, meta subject and age; one action, `Read: build show <path> <latest number>` when the list is non-empty.

Callers: replace each terminal branch with `emitPageView(p, ds, next, plain, func() screen { ... })`, keeping the plain closures byte-for-byte. `mrListTerm` is deleted once nothing calls it. An empty list at a terminal still prints "nothing to list" to stderr (that is `emit`'s), so the builders never see zero rows from a real call.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestListsPlainPinned|TestMRListScreen|TestIssueListScreen|TestBuildListScreen'`
Expected: PASS.

- [ ] **Step 5: Commit**

```bash
git add internal/control/mr.go internal/control/issue.go internal/control/build.go internal/control/listscreen_test.go internal/control/testdata/plain/
git commit -m "control: mr, issue and build lists as screens

Ref #318"
```

### Task 15: `dashboard` screen

**Files:**
- Modify: `internal/control/dashboard.go` (`runDashboard` from line 140; delete `needsYou` once unused)
- Test: `internal/control/dashscreen_test.go` (new), `testdata/plain/dashboard.txt`

**Interfaces:**
- Produces: `func dashboardScreen(c *Ctx, d DashboardOut, lines []FeedLine) screen`. Check the element type `FeedLines` returns (`grep -n 'func FeedLines' internal/control/feedline.go`) and use it.

- [ ] **Step 1: Pin piped output**

```go
func TestDashboardPlainPinned(t *testing.T) {
	st, _, owner := twoMRTestRepo(t)
	c, out, errOut := mrTestCtx(st, owner)
	if code := Dispatch(c, []string{"dashboard"}); code != protocol.ExitOK {
		t.Fatalf("exit %d: %s", code, errOut)
	}
	pinPlain(t, "dashboard", out.String())
}
```

Run with `-update-plain`, then without.

- [ ] **Step 2: Failing screen tests**

```go
func dashFixture() DashboardOut {
	return DashboardOut{
		Assigned: []DashboardItem{{Repo: "krz/skunky-art", Number: 33, Title: "LibRedirect listing", Author: "cmc"}},
		MRs:      []DashboardItem{{Repo: "krz/gitbay", Number: 552, Title: "wire $PAGER", Author: "cmc"}},
		Builds: []DashboardBuild{
			{Repo: "krz/omaha-metro-blotter", Number: 83, Job: "daily-pull", Status: "failure", Ref: "main", CreatedAt: "2026-09-30T12:00:00Z"},
			{Repo: "krz/gitbay", Number: 1779, Job: "test", Status: "success", Ref: "main", CreatedAt: "2026-10-01T10:00:00Z"},
			{Repo: "krz/gitbay", Number: 1778, Job: "build", Status: "success", Ref: "main", CreatedAt: "2026-10-01T10:00:00Z"},
		},
		Server: &ServerOut{Commit: "135f300"},
	}
}

func TestDashboardScreen(t *testing.T) {
	c := screenCtx(110, false)
	c.User = store.User{Username: "cmc", IsAdmin: true}
	s := dashboardScreen(c, dashFixture(), nil)
	var titles []string
	for _, sec := range s.sections {
		if len(sec.rows) > 0 {
			titles = append(titles, sec.title)
		}
	}
	want := []string{"Assigned issues", "Open merge requests", "Failed builds"}
	if !slices.Equal(titles, want) {
		t.Errorf("sections = %q, want %q", titles, want)
	}
	for _, f := range s.fields {
		if f.label == "Server" || f.label == "Queues" {
			t.Errorf("admin block %q on the dashboard screen", f.label)
		}
	}
	var first []string
	for _, a := range s.actions {
		first = append(first, strings.Join(a.argv, " "))
	}
	if !slices.Contains(first, "issue show krz/skunky-art 33") || !slices.Contains(first, "build log krz/omaha-metro-blotter 83") {
		t.Errorf("actions = %q", first)
	}
	if !slices.Contains(first, "admin stats") {
		t.Errorf("admin missing admin stats: %q", first)
	}
	checkActions(t, s)
}

func TestDashboardScreenPassingBuildsCollapse(t *testing.T) {
	c := screenCtx(110, false)
	d := dashFixture()
	d.Builds = d.Builds[1:]
	s := dashboardScreen(c, d, nil)
	for _, sec := range s.sections {
		if sec.title == "Failed builds" && len(sec.rows) > 0 {
			t.Error("failed builds section with no failures")
		}
	}
	if !strings.Contains(renderString(c, s), "2 builds passed") {
		t.Errorf("no passing-build summary:\n%s", renderString(c, s))
	}
}
```

Expected on run: `undefined: dashboardScreen`.

- [ ] **Step 3: Implement**

```go
// dashboardScreen is dashboard at a terminal: what waits on the viewer
// first, then their open merge requests, failed builds, a few lines of
// activity and the pinned repositories. The operator's queues are
// admin stats'; a mirror or queue failure shows as one header line.
func dashboardScreen(c *Ctx, d DashboardOut, lines []FeedLine) screen {
	var s screen
	s.fields = append(s.fields, field{"User", []cell{cText(c.User.Username)}}, field{"Instance", []cell{cText(c.Cfg.SiteHost())}})
	if q := d.Queues; q != nil {
		if bad := q.Webhooks.Failed + q.Mail.Failed + q.Push.Failed + q.Mirrors.Errors + q.Deps.Errors; bad > 0 {
			s.fields = append(s.fields, field{"Problems", []cell{cGlyph("failed"), cText(fmt.Sprintf("%d failing in the background", bad))}})
		}
	}
	if d.Unread > 0 {
		s.fields = append(s.fields, field{"Inbox", []cell{cYou(), cText(fmt.Sprintf("%d unread", d.Unread))}})
	}

	item := func(it DashboardItem, marker, page string, you bool) row {
		lead := cell{kind: kindGlyph}
		if you {
			lead = cYou()
		}
		ref := cLink(fmt.Sprintf("%s%s%d", it.Repo, marker, it.Number), c.siteURL(it.Repo, page, strconv.FormatInt(it.Number, 10)))
		return rowOf(ref, lead, cFlex(it.Title), cMeta(it.Author))
	}
	reviews := section{title: "Review requested", n: len(d.Reviews)}
	for _, it := range d.Reviews {
		reviews.rows = append(reviews.rows, item(it, "!", "mrs", true))
	}
	assigned := section{title: "Assigned issues", n: len(d.Assigned)}
	for _, it := range d.Assigned {
		assigned.rows = append(assigned.rows, item(it, "#", "issues", true))
	}
	mrs := section{title: "Open merge requests", n: len(d.MRs)}
	for _, it := range d.MRs {
		mrs.rows = append(mrs.rows, item(it, "!", "mrs", false))
	}

	failed := section{title: "Failed builds"}
	passed := 0
	seen := map[string]bool{}
	var firstFailed *DashboardBuild
	for i, b := range d.Builds {
		key := b.Repo + "\x00" + b.Job + "\x00" + b.Ref
		if seen[key] {
			continue
		}
		seen[key] = true
		switch b.Status {
		case "success":
			passed++
		case "failure", "failed", "error":
			failed.n++
			failed.rows = append(failed.rows, rowOf(cLink(strconv.FormatInt(b.Number, 10), c.siteURL(b.Repo, "builds", strconv.FormatInt(b.Number, 10))),
				cGlyph(b.Status), cFlex(b.Job+"  "+b.Ref), cMeta(b.Repo, relAge(b.CreatedAt, termNow()))))
			if firstFailed == nil {
				firstFailed = &d.Builds[i]
			}
		}
	}

	activity := section{title: "Recent activity", n: len(lines), more: []string{"feed"}}
	for _, l := range lines[:min(len(lines), 5)] {
		activity.rows = append(activity.rows, rowOf(l.termCells(c)...))
	}
	if passed > 0 {
		activity.rows = append(activity.rows, rowOf(cMeta(fmt.Sprintf("%d builds passed", passed))))
	}

	pinned := section{title: "Pinned", n: len(d.Pinned)}
	if len(d.Pinned) > 0 {
		var paths []string
		for _, p := range d.Pinned {
			paths = append(paths, p.Path)
		}
		pinned.rows = []row{rowOf(cMeta(strings.Join(paths, "  ")))}
	}
	s.sections = []section{reviews, assigned, mrs, failed, activity, pinned}

	if len(d.Reviews) > 0 {
		it := d.Reviews[0]
		s.actions = append(s.actions, action{"Next", []string{"mr", "show", it.Repo, strconv.FormatInt(it.Number, 10)}})
	}
	if len(d.Assigned) > 0 {
		it := d.Assigned[0]
		s.actions = append(s.actions, action{"Next", []string{"issue", "show", it.Repo, strconv.FormatInt(it.Number, 10)}})
	}
	if firstFailed != nil {
		s.actions = append(s.actions, action{"Next", []string{"build", "log", firstFailed.Repo, strconv.FormatInt(firstFailed.Number, 10)}})
	}
	s.actions = append(s.actions, action{"More", []string{"feed"}})
	if c.User.IsAdmin {
		s.actions = append(s.actions, action{"Instance", []string{"admin", "stats"}})
	}
	return s
}
```

Notes:
- `l.termCells(c)` is the feed's existing terminal row; check its column order and, if it leads with an age, keep it — activity rows are the one place time leads.
- With no feed lines but passing builds, the section has `n: 0` and one row, so it renders as `Recent activity (0)` above the summary. If that reads wrong, title the summary row's section `Builds` instead. Decide on the rendered output.
- Saved query sections (`d.Queries`) become one section each, titled with the query name and `n: q.Count`, rows as `item` without a lead, `more: []string{"query", "show", q.Name}` (check the real subcommand with `ssh git@gitbay.org help query`). Insert them after `mrs`.
- `Cfg.SiteHost()` exists (`repo.go` uses it).

In `runDashboard`, compute `lines := FeedLines(events)` before emitting (it is computed inside the closure today), and switch to `c.emitView(d, plain, func() screen { return dashboardScreen(c, d, lines) })`. In the plain closure, delete every `c.Term.Cols > 0` branch (the `needsYou` line, the terminal activity rows, the empty-section skip) so the closure is the plain path only; the pin from step 1 proves it unchanged. Delete `needsYou` if nothing else calls it, and its test.

- [ ] **Step 4: Run tests**

Run: `go test ./internal/control/ -run 'TestDashboard'`
Expected: PASS, pin unchanged.

- [ ] **Step 5: Verify, commit, MR**

```bash
go build ./... && go vet ./... && go test ./internal/control/ ./internal/gitutil/ ./cmd/gitbay/
git add internal/control/dashboard.go internal/control/dashscreen_test.go internal/control/testdata/plain/dashboard.txt CHANGELOG.org
git commit -m "control: dashboard as a screen

Ref #318"
git push -u origin cli-views-2b
gitbay mr create --source cli-views-2b --target main --title "control: list and dashboard screens (stage 2b of CLI views)"
```

---

## Stage 3

Written as its own plan after stage 2b merges, from the `screen` API as it
stands then. Its scope: every remaining `c.table` and `c.view` caller
(start with `profile`, `release`, `milestone`, `org`, `label`), the header
lines of `mr diff`, `repo diff`, `repo commit` and `build log`, and removing
`view`'s terminal branches.

## Self-review notes

- Spec coverage: visual rules → tasks 1–4; model and `emitView` → 3, 5;
  `here=` → 4, 6; paging → 5; resolve test → 7; plain pinning → 7 and the
  first step of 10–15; screens → 10–15; wiki → 8; stage 3 deferred to its
  own plan, as the spec's stages allow.
- Two places in tasks 10 and 15 are marked "decide on the rendered output"
  (the Files count, the activity count). They are presentation choices with
  both options spelled out, not missing work.