Files

tegwick d7c4bd5802 feat(onboarding): redesign repo integration journey

custodian_cli.py:
- register-project now writes CLAUDE.custodian.md (suggestion) instead
  of overwriting CLAUDE.md; includes preamble with integration instructions
- registers repo via POST /repos/
- creates a "Repo Integration: {slug}" workstream in the domain's topic
  with 4 onboarding tasks (integrate CLAUDE.md, first workplan, SBOM,
  EPs/TDs); checks for existing workstream to be idempotent
- fixes {REPO_SLUG} template substitution (previously missing)

dashboard:
- repos.md: fetches workstreams; detects active repo-integration-* slugs;
  adds "Integrating" KPI card; shows ⚙ integrating badge per repo in
  coverage map and table; replaces "How to Ingest a Repo" with
  "Onboard a New Repo" 4-step panel with doc help button
- docs/repo-integration.md (new): full collaboration model doc — custodian
  as coach, repo agent as executor; journey, generated tasks, first session
  protocol, ongoing relationship
- docs/repos.md: links to new repo-integration doc; updates "What is a
  managed repo?" section; adds onboarding quick reference
- docs/reference.md: fix latent build error — code examples were in ```js
  fences (executed by OF); changed to ```javascript (display only)
- observablehq.config.js: adds "Repo Integration" to Reference nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-02 08:42:30 +01:00

3.2 KiB

Raw Blame History

title

title
Reference & Context Help — Reference

Reference & Context Help

The Reference section is a collection of in-depth documentation pages explaining the data model, design conventions, and mechanics of each dashboard view. Reference pages are readable as standalone articles and also surfaced inline via the ? context-help button on dashboard pages.

The ? context-help button

Every dashboard page exposes one or more ? buttons — small circular controls that open the relevant reference page in an overlay without leaving the current view.

Where ? buttons appear

Location	Opens
Page h1 heading	Reference page for that dashboard view
KPI sidebar cards	Reference page for the specific metric shown
Live indicator	Live Data — poll interval, offline recovery

How to use it

Hover over the element — the ? button fades in at the top-right corner.
Click ? — the reference page opens in a modal overlay.
Read the docs, then dismiss with ✕ close, Esc, or by clicking the backdrop.

The overlay does not interrupt the live data polling loop — the dashboard continues refreshing in the background while the overlay is open.

Overlay behaviour

Detail	Value
Size	`min(780px, 92vw)` wide · `82vh` tall
Content	Observable Framework page rendered in an `<iframe>`
Dismiss	✕ button · Esc key · click outside the box
Animation	Fade-in backdrop + slide-up box (150 ms)
Stacking	`z-index: 9000` — always above dashboard content

Only one overlay can be open at a time. Opening a second ? replaces the first automatically.

Adding ? help to a new page

The helper is exported from src/components/doc-overlay.js:

import {withDocHelp} from "./components/doc-overlay.js";

On a page h1:

const _h1 = document.querySelector("#observablehq-main h1");
if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/my-page"); }

On a sidebar card or other element (must have position: relative):

const _card = html`<div class="kpi-infobox" style="position:relative">…</div>`;
withDocHelp(_card, "/docs/my-page");

withDocHelp(element, docPath) mutates the element in place and returns it, so it can be chained directly before display() or injectTocTop().

Writing a reference page

Reference pages live in state-hub/dashboard/src/docs/ and follow a consistent structure:

---
title: Topic — Reference
---

# Topic — Reference

One-sentence purpose statement.

---

## Section 1
…

## Section 2
…

---

*Footer note (optional — e.g. governance constraint, append-only policy).*

Conventions:

Title frontmatter: "Topic — Reference" (em dash, not hyphen)
Sections separated by --- horizontal rules
Tables preferred over prose lists for structured data
Code blocks for MCP tool calls and REST examples
No live data fetching — reference pages are static

After writing the page, register it in two places:

observablehq.config.js — add to the Reference pages array (alphabetical)
src/reference.md — add a row to the dashboard-pages table

3.2 KiB Raw Blame History