the-custodian/workplans/CUST-WP-0030-dashboard-entity-list-ux.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CUST-WP-0030	workplan	Dashboard Entity List UX	custodian	the-custodian	done	custodian	custodian	2026-03-29	2026-03-29	9d8e1c33-2067-4593-a5d8-d28dda3b1d21

Dashboard Entity List UX

Goal

Make every entity table in the dashboard navigable and self-documenting. Two new UI primitives:

1. REF cell — running row number (1-based); click copies a deep-link (<origin>/data/<recordtype>/<id>) to the clipboard; double-click opens the link in a new tab.
2. Name cell — second column, titled after the record type; shows the entity name truncated at 80 chars with full-name tooltip on hover.

Support these cells with a landing page (/data/[type]/[id]) that renders a key-value view of every field in the record, each key decorated with a <help-tip> (one-sentence description + link to the relevant help-doc section).

Pilot all three features on the Token Cost page, then extend to other entity tables in later workplans.

Background

Current entity tables show only IDs (often truncated UUIDs) with no way to navigate to a record detail view or discover what a field means. For a person reviewing agent activity the tables are hard to parse. Providing a running reference number, an entity name column, and a click-through detail page substantially lowers the cognitive load.

The <help-tip> custom element already exists in src/components/help-tip.js and is used on several pages — the field-help registry will reuse it as the rendering layer.

Implementation Plan

The pilot targets the Token Cost page. Observable Framework supports parameterised pages via [param].md file naming. The API already exposes GET /token-events/?task_id=… and GET /token-events/summary/; a per-record GET endpoint is needed before the landing page can work.

Component layer

• src/components/ref-cell.js — exports refCell(index, type, id) that returns an HTMLElement with click/dblclick handlers.
• src/components/field-help.js — exports FIELD_HELP map and fieldRow(key, value) helper that wraps the key in <help-tip>.

API layer

• GET /token-events/{event_id} — returns TokenEventRead for a single event; needed by the landing page data loader.

Dashboard pages

• src/data/token-events/[id].json.py — data loader that calls the new single-event endpoint; returns JSON for the landing page.
• src/data/token-events/[id].md — landing page: key-value table, each row built with fieldRow().
• src/token-cost.md — updated: REF column (refCell) and Name column added to By Repo, By Workplan, and Top Tasks tables.

Tasks

id: T01
title: "REF cell component"
status: done
priority: high
description: >
  Create src/components/ref-cell.js.
  Export refCell(index, recordType, id) → HTMLElement.
  - Displays 1-based index as monospace text, cursor:pointer.
  - Single click: copies `${location.origin}/data/${recordType}/${id}` to
    clipboard; briefly flashes "Copied!" as a transient tooltip using the
    existing help-tip positioning pattern.
  - Double click: window.open(deeplink, '_blank').
  - No external dependencies; plain DOM.
state_hub_task_id: "8ee527cf-436b-4bab-bdb8-406314a38d99"

id: T02
title: "GET /token-events/{event_id} endpoint"
status: done
priority: high
description: >
  Add GET /token-events/{event_id} to api/routers/token_events.py.
  Returns TokenEventRead (already defined in schemas/token_event.py).
  404 if not found.
  No migration needed.
  Add a test in tests/test_token_events.py: get by id → 200, unknown id → 404.
state_hub_task_id: "02c27d25-d744-4da0-9bcb-b40ada54d5a5"

id: T03
title: "Field-help registry"
status: done
priority: medium
description: >
  Create src/components/field-help.js.
  Export FIELD_HELP: a plain object keyed by field name.
  Each entry: { label, description, doc } — matches help-tip attributes.
  Cover at minimum all TokenEventRead fields:
    id, tokens_in, tokens_out, tokens_total, task_id, workstream_id,
    repo_id, session_id, model, agent, ref_type, ref_id, note, created_at.
  Export fieldRow(key, value) → HTMLElement (<tr>) that wraps key in a
  <help-tip> (or plain <td> if key is not in FIELD_HELP) and value in a
  second <td>.
  Import HelpTip from ./help-tip.js to ensure the custom element is
  registered.
state_hub_task_id: "7721d884-bd70-459f-b36d-450d69aac549"

id: T04
title: "Token-event landing page"
status: done
priority: medium
description: >
  Create two files:
  1. src/data/token-events/[id].json.py — data loader.
     Reads `id` from argv[1]; calls GET /token-events/{id};
     exits 1 if 404 so Observable renders an error page.
  2. src/data/token-events/[id].md — landing page.
     Imports fieldRow from components/field-help.js.
     Fetches FileAttachment("token-events/{id}.json").json().
     Renders an HTML <table> with one row per field using fieldRow().
     Title: "Token Event · {id.slice(0,8)}…".
     Back link: "<a href='/token-cost'>← Token Cost</a>".
state_hub_task_id: "dc63746d-74b3-434a-925c-1cead480198f"

id: T05
title: "Apply REF and Name columns to Token Cost page"
status: done
priority: high
description: >
  Update src/token-cost.md.
  Import refCell from ./components/ref-cell.js.
  For each of the three entity tables (By Repo, By Workplan, Top Tasks):
  - Prepend a "REF" column using refCell(i+1, recordType, row.id).
    Record types: "repos" for By Repo (using repo_id), "workstreams" for
    By Workplan (using scope_id), "token-events" for Top Tasks (using
    task_id — note: links to the task landing page, not a token event page,
    until T04 is done; use recordType "tasks").
  - Add a Name column as the second data column:
    - By Repo: repo_slug (no truncation needed, slugs are short)
    - By Workplan: scope_id displayed as first 8 chars + "…" (unchanged)
      → replace with workstream title if available; for now show scope_id
      truncated to 36 chars with full UUID tooltip.
    - Top Tasks: task_id truncated to 80 chars with full-id tooltip.
  Keep all existing columns unchanged.
state_hub_task_id: "3225cc6c-2574-41e9-b8fd-e5e703a9dd7c"

id: T07
title: "Repo filter dropdown on Token Cost page"
status: done
priority: high
description: >
  Add a "Filter by repo" select element directly below the Token Cost page
  heading (above all three tables). Populate options from the already-fetched
  /repos/ data (plus an "All repos" default at the top). When a repo is selected,
  re-render all three tables (By Repo, By Workplan, Top Tasks) showing only rows
  whose data is attributed to that repo. The individual-events data (fetched for
  wsMap/taskMap) is already keyed by repo_id on each event — use that to filter
  By Workplan and Top Tasks rows client-side. By Repo always shows at most the
  selected repo (one row). If "All repos" is selected, all rows are shown as
  before. Implement filtering as a reactive variable that triggers table redraws.
state_hub_task_id: "c01cead4-ff9c-4533-b3d8-9f7554387771"

id: T08
title: "Sort order dropdown on Token Cost page"
status: done
priority: high
description: >
  Add a "Sort by" select element immediately to the right of the repo filter
  dropdown. Options (in display order):
    "Tokens Total" (default — current server-side order)
    "Tokens In"
    "Tokens Out"
    "Event Count"
    "Most Recent"
  Implement as a client-side sort applied after filtering and before slicing for
  max-results. For the first four options sort descending by the named field.
  For "Most Recent", sort each table's rows by the most recent created_at among
  the individual token events belonging to that row's group (repo/workstream/task).
  Derive a lastEventAt lookup map from the already-fetched /token-events/ data;
  rows with no events sort last. The sort applies uniformly to all three tables.
state_hub_task_id: "84183245-5016-4d87-ad6a-9cd5f6873245"

id: T09
title: "Max results dropdown on Token Cost page"
status: done
priority: medium
description: >
  Add a "Show" select element immediately to the right of the sort dropdown.
  Options: 10, 20, 50, 100, 500. Default: 20.
  After filtering and sorting each table's data array, slice to at most N rows
  before rendering. Display the total available count beneath or beside each
  table when the table is truncated (e.g. "Showing 20 of 47"). The limit applies
  independently per table (each table may have different totals). No API change
  needed — client-side slice of the already-fetched arrays.
state_hub_task_id: "3ef43135-fb65-4cca-b8c3-4c7eeb52107c"

id: T06
title: "Consistency gate and docs update"
status: done
priority: low
description: >
  1. Run `cd state-hub && make test` — all token_events tests must pass.
  2. Run `make fix-consistency REPO=the-custodian`.
  3. Add a one-paragraph entry to src/docs/reference.md describing the
     /data/<type>/<id> URL scheme and the REF column convention.
state_hub_task_id: "107cb5bb-ff0c-4c97-af04-2cdeff11f0b2"

Amendments & Improvements

Post-completion fixes and enhancements discovered during manual testing.

A01 — amendment — Deep-link URL prefix wrong

ref-cell.js generated deep-links as <origin>/data/<type>/<id> but Observable Framework serves pages at /<type>/<id> (the src/data/ directory is for data loaders, not pages). Fixed by removing the /data/ prefix from the deepLink construction in ref-cell.js. The T01 description was also inaccurate in stating the /data/ path.

A02 — amendment — FileAttachment rejects template literals

T04 used FileAttachment(`../data/token-events/${eventId}.json`) in the landing page. Observable Framework requires FileAttachment to be called with a single literal string (it processes them statically at compile time). This caused a SyntaxError that also aborted the cell defining eventId, cascading into a RuntimeError: wsId is not defined on the next cell. Fixed by replacing all FileAttachment calls in landing pages with direct fetch(${API}/...) calls.

A03 — amendment — Workstream and repo landing pages missing

T04 only created a token-event landing page. The By Workplan and By Repo tables also had REF links (to /workstreams/<id> and /repos/<slug>), both returning 404. Added:

• src/workstreams/[id].md — fetches GET /workstreams/{id}
• src/repos/[slug].md — fetches GET /repos/{slug}/
• Corresponding unused data loaders left in src/data/ for reference.

A04 — amendment — Repos router uses slug, not UUID

T05 passed repo_id (UUID) to refCell for the By Repo table, but the repos API uses slug-based routing (GET /repos/{slug}/). Passing a UUID returned 404. Fixed by passing repo_slug to refCell so the deep-link resolves correctly.

A05 — amendment — Top Tasks refCell used wrong record type

T05 specified "token-events" as the record type for Top Tasks, but the column contains task_id (a task UUID, not a token-event UUID), so the landing page returned "Token event not found". Fixed by:

• Changing record type to "tasks" in the refCell call.
• Creating src/tasks/[id].md (fetches GET /tasks/{task_id}).

I02 — improvement — Entity FK fields on detail pages link to their targets

On every detail page (token-event, task, workstream, repo), fields that hold a foreign-key UUID (task_id, workstream_id, repo_id) now render as clickable links with an async-loaded bubble-help showing the entity title.

Implementation:

• GET /repos/by-id/{repo_id} added to api/routers/repos.py — UUID lookup needed because the existing repos router uses slug routing.
• FIELD_LINKS registry added to src/components/field-help.js mapping each FK field to {apiUrl, getUrl, getTitle} resolution rules. getUrl receives (id, data) so slug-routed entities can derive their page URL from the fetched entity (e.g. repo_id → /repos/{data.slug}).
• _linkCell(key, id) helper added: renders a short-UUID link immediately, then fetches the entity asynchronously and wraps the anchor in a <help-tip label="{title}" description="{type} · {full-uuid}"> once the data arrives.
• fieldRow updated to dispatch to _linkCell whenever the field key is in FIELD_LINKS and the value is non-null.

I05 — improvement — Max results dropdown

A "Show" select (10 / 20 / 50 / 100 / 500, default 20) sits to the right of the sort dropdown. After filtering and sorting, each table is sliced to at most N rows. A "Showing M of N" note appears below any truncated table.

I04 — improvement — Sort order dropdown

A "Sort by" select sits to the right of the repo filter. Options: Tokens Total (default), Tokens In, Tokens Out, Event Count, Most Recent. Sorting is applied client-side after filtering and before the max-results slice. "Most Recent" sorts by the maximum created_at among the events in each group, derived from the already-fetched individual events data.

I03 — improvement — Repo filter dropdown

A "Filter by repo" select appears directly below the Token Cost heading. Options come from the already-fetched /repos/ list plus "All repos" at the top. Selecting a repo filters all three tables client-side to show only rows attributable to that repo. No API change needed.

I01 — improvement — Workstream and task Name columns show titles

T05 originally showed truncated UUIDs in the Workstream and Task name columns (the summary data carries only IDs, not titles). Improved by fetching /workstreams/ and /tasks/ in parallel with the token-event poll and building lookup maps (wsMap, taskMap). The Name column now displays workstream.title and task.title (truncated to 80 chars) with the full UUID as tooltip.