36fad7d130
Combines lane-go's typed omni search, launch-time model overrides, TUI artifacts view, run-state websocket push, and the "reflect the change where it belongs" committer rule with the Templates gallery, chat/omni-search and other reviewed work already on main. The 12 files both sides touched keep both intents composed rather than dropping either side: the omni search keeps the typed search contract (CLI `pipelines search` and the TUI popup with type badges and marked snippets) alongside the run-list quick filter; cli.md and ui-ux-review.md document both the search rework and the artifacts view; orchestration.md, harnesses.md and operations.md keep the model-override and reflect-where-it-belongs guidance; and the protocol/CLI/server/TUI code keeps the new search, run-event, override and artifacts paths alongside the existing run, title and help surfaces. Checks before committing: - go build ./... -- pass - go vet ./... -- pass - go test -count=1 ./internal/... ./cmd/... -- all pass Doc check before committing: nothing needs updating. The lane's own docs and references (docs/cli.md, docs/ui-ux-review.md, and the orchestration, harnesses and operations skill references) already carry the new features. format.md and the packaged templates already describe the line-oriented result format and the human decision stage from the earlier lane-go merge. The root README already describes the omni search popup. Model overrides, the search command, run events and the artifacts view are runtime/CLI/TUI surfaces that cli.md documents; no template, README or topic-doc edit is required by this merge.
114 lines
9.0 KiB
Markdown
114 lines
9.0 KiB
Markdown
# UI/UX review
|
||
|
||
An independent reviewer rendered every screen family at 120×36, 80×24 and
|
||
40×16, alongside light/dark ANSI previews. This was an executed screen/render
|
||
review, not a real-user usability or screen-reader study. Real-terminal contrast
|
||
and external editor/OpenCode behavior were not assessed by that review.
|
||
|
||
## Design decisions
|
||
|
||
- **Results before machinery.** Home starts with recent outcomes and reported
|
||
results. Statistics come afterward; addresses and notification setup live in Status.
|
||
- **Two Run focus targets.** Tab and Shift+Tab alternate Details ↔ Graph. Recorded
|
||
visits are a compact selector inside Details, not a third focusable pane.
|
||
- **Readable reports.** Results use prose, Markdown, lists and labelled nested
|
||
values instead of raw transport objects. The stored output is unchanged.
|
||
- **Progressive disclosure.** Progress, task input, evidence and execution metadata
|
||
are secondary. A stage's reported result is not independently verified success.
|
||
- **Full-size graphs.** Keep the existing boxes/arrows, centering, dim pending
|
||
routes and panning. Collapse an unusably small inactive run-graph preview rather
|
||
than drawing severed box tops. A focused graph remains reachable on narrow screens.
|
||
- **Contextual controls.** Forms and overlays replace background-page hints.
|
||
Safety warnings wrap and scroll while confirmation/cancellation remain pinned.
|
||
|
||
## Feedback by screen
|
||
|
||
| Screen | Reviewer feedback | Response / remaining work |
|
||
| --- | --- | --- |
|
||
| Home | Usage and infrastructure outrank results; narrow columns clip reports. | Results first, wider result column, wrapped previews, statistics last, continuation indicator. |
|
||
| Home empty/loading | Missing statistics look like permanent loading. | No placeholder usage spinner; empty and initial data-loading states are distinct. |
|
||
| Pipeline overview | Graph is good; identity and metadata compete with useful content. | Keep the graph. Further compacting the toolbar on small screens remains worthwhile. |
|
||
| Pipeline stage | Five prose columns resemble a spreadsheet. | Full-width stacked fields; capabilities before long instructions; configuration disclosure. |
|
||
| Runs list | Footer advertises stage/graph controls that do not apply. | List-specific search/select/open/back controls. |
|
||
| Run overview | Stage sidebar takes too much space and adds a third focus target. | Remove sidebar focus and resizing; compact visit selector and full-width Details. |
|
||
| Run stage/visit | Summary repeats output; long evidence crowds the result. | Render the result once; collapse secondary sections; preserve each recorded visit. |
|
||
| Run graph | Inactive previews sever boxes; narrow focused Graph can disappear. | Collapse unusable previews; allocate the viewport to the focused full-size canvas. |
|
||
| Templates | Definition source dominates purpose and expected result. | Error/loading states corrected. A purpose-first catalog overview remains a follow-up. |
|
||
| Drafts | Paths and publication metadata dominate the draft's purpose. | Preserve current draft retention/validation. Moving metadata behind disclosure remains a follow-up. |
|
||
| Status | Narrow cards hide addresses; scrolling does not reveal them. | Wrap card contents and scroll the actual service-card canvas. |
|
||
| Task form | Tool lists consume prompt space; wrong footer. | Larger task area, compact scope summary, correct submit/cancel controls. |
|
||
| CLI pipeline picker | Background Home controls remain visible. | Picker-specific filter/select/cancel controls. |
|
||
| Search | "Omnisearch" promises broader scope than pipeline search. | Home `/` opens an omni popup that searches pipelines, versions, runs, steps/visits, artifact names and stage input/output/evidence text, with typed badges, a non-colour marked snippet for text matches, and Enter-to-open navigation. The run-list `/` filter remains a separate, pipeline-scoped quick filter. The same broad cross-kind search is available server-side as `pipelines search QUERY [--type KIND]`, documented in [CLI and agent authoring](cli.md#search). |
|
||
| Commands | No descriptions or indication of hidden entries. | Selected-command explanation and visible range/count. |
|
||
| Versions | Selected/latest markers truncate on narrow screens. | Correct view-version footer; further metadata prioritization remains a follow-up. |
|
||
| Naming/publication | Naming inherits publication shortcuts. | Input-specific name-saving/retention footer. |
|
||
| Start/retry/cancel | Narrow safety warnings are clipped. | Wrapped, independently scrollable disclosures with pinned controls. |
|
||
| Editor picker/checking | Unlabelled filter and color-only selection; wrong pending footer. | Labelled filter, textual selection marker, appropriate pending-state footer. |
|
||
| Logs | Long failure messages are horizontally inaccessible. | Left/right panning; vertical unread tracking is retained. |
|
||
| Failure/debug | Generic mutation warning does not explain Debug. | Explain pinned definition/evidence, retained draft scope and separation from retry. |
|
||
|
||
The second executed review confirmed the improved Home and 80-column run report
|
||
hierarchy. It identified four remaining narrow-layout issues, addressed afterward:
|
||
short-screen Details now uses compact headers to expose the actual result;
|
||
pipeline stage focus collapses its inactive graph preview; draft-delete uses the
|
||
same wrapped/scrollable safety dialog; and narrow overlay footers keep Escape
|
||
instructions visible. Dedicated regressions exercise each of these behaviors.
|
||
|
||
## Navigation
|
||
|
||
Run opens in Details. `n`/`p` selects recorded visits from either pane, including
|
||
repeated stages; `0` returns to the overview. `j`/`k` scrolls Details or pans Graph,
|
||
depending on focus. `h`/`l` and arrow keys pan a focused graph; in Details,
|
||
left/right selects the previous/next visit. `c` centers the focused graph.
|
||
`o`, `s`, `i`, `t`, `m` disclose result, progress, input, evidence and execution details.
|
||
`A` opens the run's artifacts view: recorded files grouped by stage and visit, with
|
||
name, content type and human size in aligned columns, an `[img]` marker for images,
|
||
the URL per entry, and `Enter`/`o` to open or `y` to copy the selected entry.
|
||
|
||
Home still advertises only `/` search and `:` commands. `q` never exits the client;
|
||
use `:quit`. Consequential actions still require explicit confirmation.
|
||
|
||
## Regression coverage
|
||
|
||
`internal/tui/ux_regression_test.go` covers the two-target focus cycle at all three
|
||
sizes, visible narrow graph focus, readable nested reports without altering data,
|
||
reachable safety warnings, contextual footers, terminal errors and narrow Status
|
||
scrolling. Existing graph, repeated-visit, permission, draft and confirmation tests
|
||
remain applicable. Compiled CLI/TUI PTY integration additionally exercises the
|
||
actual two-target Tab cycle and editor/publication/debug/retry flows with mocked
|
||
OpenCode; it does not verify real-provider inference or terminal-specific contrast.
|
||
|
||
## Earlier review record: October 8, 2026
|
||
|
||
The retained review below predates this redesign. Its findings and verification
|
||
are historical, not a claim that the current screens have no remaining UX issues.
|
||
|
||
> Five independent read-only reviewer sessions inspected executed `Model.View`
|
||
> renders of Home, pipeline details, selected/focused/scrolled stages, native
|
||
> delivery, and run inspection at 80/120/160 columns. Fixes were applied between
|
||
> rounds. Snapshot review does not establish color accessibility or phone delivery.
|
||
|
||
| Earlier round | Findings and changes |
|
||
| --- | --- |
|
||
| 1 | Added stage row ranges, horizontal graph overflow arrows/pan hint, and full-height column separators. |
|
||
| 2 | Balanced graph/detail space; expanded focused details; added textual focus/selection and complete selected-run headings; made title truncation explicit. |
|
||
| 3 | Exposed tools/notify in narrow configuration columns; preserved run statuses separately from shortened names; corrected run page size. |
|
||
| 4 | Made pinned field headings follow the actual scrolled group; exposed page-scroll keys; preserved HTTP/HTTPS in compact endpoint text. |
|
||
| 5 | No material remaining usability findings in those reviewed renders. |
|
||
|
||
That iteration added wrapping `n`/`p` pipeline-stage selection and placed the ntfy
|
||
URL/topic in the global header. This redesign supersedes that header placement
|
||
and the multi-column stage layout; it preserves pipeline-stage selection.
|
||
|
||
The earlier record reports race tests, vet, builds, and actual PTY inspection of
|
||
the historical **anime episodes today v1** pipeline (pipeline **8**, no schedule).
|
||
Its complete model/web/phone execution was **not tested**. It used dated web
|
||
evidence → verify/enrich → Markdown report → native ntfy attachment through the
|
||
system connection; the LiveChart schedule was fetched during that investigation.
|
||
Removing its bundled starter does not remove its published history. Current
|
||
snapshot fixtures use the generic `examples/three-stage.md` starter.
|
||
|
||
`PIPELINES_UX_SNAPSHOT_DIR=<directory> go test ./internal/tui -run
|
||
TestUIUXReviewSnapshots -count=1` regenerates the existing snapshots without server
|
||
mutations. Review artifacts remain in the session's approved temporary directory.
|