state-hub/dashboard/src/index.md

---
title: Overview
---

```js
const API = "http://127.0.0.1:8000";
const POLL = 15_000;
```

```js
// Live polling — yields {data, ok, ts} every POLL ms
const summaryState = (async function*() {
  while (true) {
    let data, ok = false;
    try {
      const r = await fetch(`${API}/state/summary`);
      ok = r.ok;
      data = ok ? await r.json() : {error: `HTTP ${r.status}`};
    } catch (e) {
      data = {error: "API unreachable"};
    }
    yield {data, ok, ts: new Date()};
    await new Promise(res => setTimeout(res, POLL));
  }
})();
```

```js
const summary  = summaryState.data  ?? {};
const _ok      = summaryState.ok    ?? false;
const _ts      = summaryState.ts;
const totals   = summary.totals     ?? {};
const ws       = totals.workstreams ?? {};
const tasks    = totals.tasks       ?? {};
const decisions = totals.decisions  ?? {};
```

```js
// Registered projects — milestone events tagged with registration
const regsState = (async function*() {
  while (true) {
    let rows = [];
    try {
      const r = await fetch(`${API}/progress/?event_type=milestone&limit=500`);
      if (r.ok) {
        const all = await r.json();
        rows = all.filter(e => e.summary?.startsWith("Project registered with State Hub:"));
      }
    } catch {}
    yield rows;
    await new Promise(res => setTimeout(res, POLL));
  }
})();
```

# Custodian State Hub

```js
display(html`<div class="live-bar">
  <span style="color:${_ok ? 'var(--theme-foreground-focus)' : 'red'}">●</span>
  ${_ok
    ? `Live · updated ${_ts?.toLocaleTimeString()}`
    : `<span style="color:red">Offline — run: <code>cd ~/the-custodian/state-hub && make api</code></span>`}
</div>`);
```

```js
if (summary.error) display(html`<div class="warning">⚠️ ${summary.error}</div>`);
```

## Status

```js
display(html`<div class="grid grid-cols-4" style="gap:1rem;margin-bottom:1.5rem">
  <div class="card">
    <h3>Active Workstreams</h3>
    <p class="big-num">${ws.active ?? 0}</p>
    <small>${ws.blocked ?? 0} blocked</small>
  </div>
  <div class="card ${(decisions.open + decisions.escalated) > 0 ? 'warn' : ''}">
    <h3>Blocking Decisions</h3>
    <p class="big-num">${(decisions.open ?? 0) + (decisions.escalated ?? 0)}</p>
    <small>${decisions.escalated ?? 0} escalated</small>
  </div>
  <div class="card ${(tasks.blocked ?? 0) > 0 ? 'warn' : ''}">
    <h3>Blocked Tasks</h3>
    <p class="big-num">${tasks.blocked ?? 0}</p>
    <small>of ${tasks.total ?? 0} total</small>
  </div>
  <div class="card">
    <h3>Events Today</h3>
    <p class="big-num">${(summary.recent_progress ?? []).filter(e =>
      e.created_at?.startsWith(new Date().toISOString().slice(0,10))).length}</p>
    <small>last 20 shown below</small>
  </div>
</div>`);
```

## Registered Projects

```js
const regs = regsState ?? [];
if (regs.length === 0) {
  display(html`<p style="color:gray">No projects registered yet. Run <code>custodian register-project</code> inside a repo.</p>`);
} else {
  display(Inputs.table(regs.map(e => ({
    Project:    e.detail?.project_path?.split("/").at(-1) ?? "—",
    Domain:     e.detail?.domain ?? "—",
    Path:       e.detail?.project_path ?? "—",
    Registered: new Date(e.created_at).toLocaleString(),
  })), {maxWidth: 900}));
}
```

## Open Workstreams by Domain

```js
import * as Plot from "npm:@observablehq/plot";

const topicById = Object.fromEntries((summary.topics ?? []).map(t => [t.id, t.domain]));

const openWs = (summary.open_workstreams ?? []).map(w => ({
  title: w.title,
  domain: topicById[w.topic_id] ?? "unknown",
  done:        w.tasks_done        ?? 0,
  in_progress: w.tasks_in_progress ?? 0,
  blocked:     w.tasks_blocked     ?? 0,
  todo:        w.tasks_todo        ?? 0,
  total:       w.tasks_total       ?? 0,
})).sort((a, b) => a.domain.localeCompare(b.domain) || a.title.localeCompare(b.title));

const statusOrder = ["done", "in progress", "blocked", "todo"];
const statusColors = ["#4caf50", "steelblue", "#ff7043", "#e0e0e0"];

const taskRows = openWs.flatMap(w => [
  {label: w.title, domain: w.domain, status: "done",        count: w.done},
  {label: w.title, domain: w.domain, status: "in progress", count: w.in_progress},
  {label: w.title, domain: w.domain, status: "blocked",     count: w.blocked},
  {label: w.title, domain: w.domain, status: "todo",        count: w.todo},
]).filter(d => d.count > 0);

// y-axis shows domain (only for the first workstream in each domain group)
const yLabels = {};
const _seenDomains = new Set();
for (const w of openWs) {
  yLabels[w.title] = _seenDomains.has(w.domain) ? "" : w.domain;
  _seenDomains.add(w.domain);
}

if (openWs.length === 0) {
  display(html`<p style="color:gray">No open workstreams.</p>`);
} else {
  display(Plot.plot({
    y: {label: null, tickSize: 0, domain: openWs.map(w => w.title), tickFormat: t => yLabels[t] ?? ""},
    x: {label: "Tasks", grid: true},
    color: {domain: statusOrder, range: statusColors, legend: true},
    marks: [
      Plot.barX(taskRows, {y: "label", x: "count", fill: "status", tip: true}),
      // Workstream title inside the bar
      Plot.text(openWs.filter(w => w.total > 0), {
        y: "title", x: 0, dx: 6,
        text: d => d.title.length > 36 ? d.title.slice(0, 34) + "…" : d.title,
        textAnchor: "start", fontSize: 10, fill: "#333",
      }),
      Plot.text(openWs.filter(w => w.total === 0), {
        y: "title", x: 0, dx: 6,
        text: d => `${d.title.length > 24 ? d.title.slice(0, 22) + "…" : d.title} — no tasks yet`,
        textAnchor: "start", fontSize: 10, fill: "#aaa",
      }),
      // "done / total" label after the bar
      Plot.text(openWs.filter(w => w.total > 0), {
        y: "title", x: "total",
        text: d => ` ${d.done}/${d.total}`,
        dx: 4, textAnchor: "start", fontSize: 11, fill: "gray",
      }),
      Plot.ruleX([0]),
    ],
    marginLeft: 160,
    marginRight: 70,
    height: Math.max(80, openWs.length * 44 + 50),
    width: 700,
  }));
}
```

```js
// Registered domains with no workstreams yet — show a getting-started hint
const regs = regsState ?? [];
const registeredDomains = new Set(regs.map(e => e.detail?.domain).filter(Boolean));
const emptyRegistered = (summary.topics ?? []).filter(t =>
  registeredDomains.has(t.domain) && (t.workstreams ?? []).length === 0
);

if (emptyRegistered.length > 0) {
  display(html`<div class="hint-box">
    <strong>💡 Getting started</strong>
    <p>These registered projects have no workstreams yet:</p>
    <ul>${emptyRegistered.map(t => html`<li>
      <strong>${t.domain}</strong> — open repo in Claude Code and say <em>"Hi!"</em> to kick off first session, or run <code>custodian create-workstream --domain ${t.domain} --title "My first workstream"</code> manually
    </li>`)}</ul>
  </div>`);
}
```

## Blocking Decisions

```js
const blocking = summary.blocking_decisions ?? [];
if (blocking.length === 0) {
  display(html`<p style="color:green">✓ No blocking decisions.</p>`);
} else {
  for (const d of blocking) {
    const card = html`<div class="dec-card ${d.escalation_note ? 'dec-escalated' : ''}">
      <div class="dec-header">
        <span class="dec-title">${d.title}</span>
        <span class="dec-meta">
          ${d.escalation_note ? html`<span class="dec-warn-badge">⚠ escalated</span>` : ""}
          ${d.deadline ? html`<span>Due ${new Date(d.deadline).toLocaleDateString()}</span>` : ""}
        </span>
      </div>
      ${d.description ? html`<p class="dec-desc">${d.description}</p>` : ""}
      ${d.rationale   ? html`<p class="dec-context"><strong>Context:</strong> ${d.rationale}</p>` : ""}
      ${d.escalation_note ? html`<p class="dec-context dec-warn-text">${d.escalation_note}</p>` : ""}
      <details class="dec-resolve">
        <summary>Resolve this decision →</summary>
        <div class="dec-resolve-inner">
          <label>Your decision &amp; rationale</label>
          <textarea class="r-text" rows="4" placeholder="State the chosen option and your reasoning…"></textarea>
          <label>Decided by</label>
          <input class="r-by" type="text" value="Bernd">
          <div class="dec-resolve-actions">
            <button class="r-submit">Record &amp; close</button>
            <span class="r-msg"></span>
          </div>
        </div>
      </details>
    </div>`;

    const btn  = card.querySelector(".r-submit");
    const msg  = card.querySelector(".r-msg");
    const det  = card.querySelector(".dec-resolve");

    btn.addEventListener("click", async () => {
      const rationale  = card.querySelector(".r-text").value.trim();
      const decidedBy  = card.querySelector(".r-by").value.trim() || "Bernd";
      if (!rationale) { msg.textContent = "⚠ Please enter a rationale."; return; }
      btn.disabled = true; btn.textContent = "Saving…";
      try {
        const r = await fetch(`${API}/decisions/${d.id}/resolve`, {
          method: "POST",
          headers: {"Content-Type": "application/json"},
          body: JSON.stringify({rationale, decided_by: decidedBy}),
        });
        if (r.ok) {
          det.open = false;
          det.querySelector("summary").textContent = "✓ Resolved — DECISIONS.md written, updates in next poll";
          det.querySelector("summary").style.color = "green";
          card.style.opacity = "0.55";
        } else {
          const err = await r.json().catch(() => ({}));
          msg.textContent = `Error ${r.status}: ${err.detail ?? "unknown"}`;
          btn.disabled = false; btn.textContent = "Record & close";
        }
      } catch (e) {
        msg.textContent = `Network error: ${e.message}`;
        btn.disabled = false; btn.textContent = "Record & close";
      }
    });

    display(card);
  }
}
```

## Decisions Due Within 7 Days

```js
const in7 = new Date(Date.now() + 7*24*60*60*1000);
const due = (summary.blocking_decisions ?? []).filter(d => d.deadline && new Date(d.deadline) <= in7);
if (due.length === 0) {
  display(html`<p>No decisions due in next 7 days.</p>`);
} else {
  display(Inputs.table(due.map(d => ({
    Title:    d.title,
    Deadline: new Date(d.deadline).toLocaleString(),
    Status:   d.status,
  }))));
}
```

## Recent Activity

```js
display(Inputs.table((summary.recent_progress ?? []).map(e => ({
  Time:    new Date(e.created_at).toLocaleString(),
  Type:    e.event_type,
  Author:  e.author ?? "—",
  Summary: e.summary,
})), {maxWidth: 900}));
```

<style>
.live-bar { font-size: 0.8rem; color: gray; text-align: right; margin-bottom: 0.5rem; }
.card { background: var(--theme-background-alt); border-radius: 8px; padding: 1rem; }
.card.warn { border: 2px solid orange; }
.big-num { font-size: 2.5rem; font-weight: bold; margin: 0.25rem 0; }
.warning { background: #fff3cd; border: 1px solid #ffc107; border-radius: 4px; padding: 0.75rem; }
.hint-box { background: var(--theme-background-alt); border-left: 3px solid steelblue; border-radius: 4px; padding: 0.75rem 1rem; margin-top: 0.75rem; font-size: 0.9rem; }
.hint-box code { background: var(--theme-background); padding: 0.15rem 0.4rem; border-radius: 3px; font-size: 0.85rem; }
.dec-card { background: var(--theme-background-alt); border-radius: 8px; padding: 1rem 1.25rem; margin-bottom: 1rem; border-left: 4px solid steelblue; }
.dec-card.dec-escalated { border-left-color: orange; }
.dec-header { display: flex; align-items: baseline; gap: 0.75rem; flex-wrap: wrap; margin-bottom: 0.5rem; }
.dec-title { font-weight: 600; font-size: 1rem; }
.dec-meta { font-size: 0.8rem; color: gray; display: flex; gap: 0.5rem; align-items: center; }
.dec-warn-badge { background: orange; color: white; border-radius: 3px; padding: 0.1rem 0.35rem; font-size: 0.75rem; }
.dec-desc { font-size: 0.9rem; margin: 0.4rem 0 0.25rem; white-space: pre-wrap; line-height: 1.5; }
.dec-context { font-size: 0.85rem; color: gray; margin: 0.25rem 0; }
.dec-warn-text { color: #b45309; }
.dec-resolve { margin-top: 0.75rem; }
.dec-resolve summary { cursor: pointer; font-size: 0.85rem; color: steelblue; user-select: none; }
.dec-resolve-inner { display: flex; flex-direction: column; gap: 0.4rem; margin-top: 0.6rem; }
.dec-resolve-inner label { font-size: 0.8rem; font-weight: 600; color: gray; }
.dec-resolve-inner textarea { width: 100%; box-sizing: border-box; padding: 0.4rem; border-radius: 4px; border: 1px solid var(--theme-foreground-faint); background: var(--theme-background); font-family: inherit; font-size: 0.875rem; resize: vertical; }
.dec-resolve-inner input[type=text] { width: 220px; padding: 0.3rem 0.5rem; border-radius: 4px; border: 1px solid var(--theme-foreground-faint); background: var(--theme-background); font-family: inherit; font-size: 0.875rem; }
.dec-resolve-actions { display: flex; align-items: center; gap: 0.75rem; margin-top: 0.25rem; }
.dec-resolve-actions button { padding: 0.35rem 0.9rem; border-radius: 4px; border: none; background: steelblue; color: white; cursor: pointer; font-size: 0.875rem; }
.dec-resolve-actions button:disabled { opacity: 0.5; cursor: default; }
.r-msg { font-size: 0.8rem; color: #b45309; }
</style>