source: .forge/dashboard/README.md · generated — edit the markdown, not this file

Tracker dashboard

A self-contained, double-clickable HTML view of .forge/tracker.yaml. Its data files (tracker.js, signals.js, metrics.js, usage.js) and the reference graph are generated and gitignored — ./forge-start.sh builds them once in a fresh clone, the hooks below keep them current, and the hosted copy on Cloudflare Pages is built by .claude/lib/pages-build.sh (this folder is the Pages build output directory; the doc site lands in docs/ beside it). Reads from sibling files (tracker.js, signals.js, optionally metrics.js / usage.js) that mirror project state as window.TRACKER / window.SIGNALS / window.METRICS / window.USAGE. No web server, no build step. _headers is Cloudflare Pages configuration, not a page asset: it marks the generated data files Cache-Control: no-cache, so a fresh deploy is visible on the next load instead of after the edge’s week-long default TTL.

How the hosted copy gets its data. The Pages project deploys this repo without a build command (its settings are not ours to change), so it serves only what is committed — and on main the data files are gitignored. The Publish dashboard workflow (.github/workflows/publish-dashboard.yml) is the build step Pages does not run: on every push to main it runs pages-build.sh, commits the generated files on top of main and force-pushes the result to the live branch, which Cloudflare deploys at https://live.forge-et-harness.pages.dev/. _redirects on main forwards the production URL there, so https://forge-et-harness.pages.dev/ keeps working; the workflow drops that file on live itself so the live site cannot redirect to itself. live is a generated artifact — nothing merges into it and nobody commits to it. A consequence worth knowing: every other branch’s preview deployment carries the redirect too, so a PR preview of index.html changes is not viewable; check those locally.

Files

File Contents Source Refresh
index.html Main dashboard — hero, KPI strip, setup gates, tabbed delivery phases, conditional team table, conditional release/UAT section, conditional wave drumbeat, signals tiles, conditional delivery-metrics section, conditional usage line, recent activity rail. hand-edited n/a
usage.html Per-phase / per-day / per-developer / per-model token-usage breakdown. Linked from the index Usage section when local usage data exists. hand-edited n/a
tracker.js window.TRACKER = JSON mirror of tracker.yaml. .forge/tracker.yaml (via yq) regen-tracker-dashboard.sh hook
signals.js window.SIGNALS = precomputed inputs for the S6 (lessons) signal tile: the weekly cadence, the total, and how many lessons are in each sync status. The other tiles are computed in the browser from window.TRACKER. .forge/lessons.md regen-tracker-dashboard.sh hook
metrics.js window.METRICS = aggregate delivery-metrics / estimation signals. .forge/metrics/*.jsonl regen-metrics-dashboard.sh hook
usage.js window.USAGE = aggregated token-usage data for this project. Gitignored (per-developer-per-machine). ~/.claude/forge-usage.jsonl (filtered by current project) regen-usage-dashboard.sh hook

View

Double-click index.html. It opens in your default browser via file://. All four data files are loaded via regular <script> tags (no fetch(), which is blocked under file://). Missing data files are handled gracefully: tracker absent → full-page fallback; signals absent → the Lessons tile (S6) reads as a placeholder; metrics absent or empty → Delivery Metrics doesn’t render; usage absent → the Usage section doesn’t render at all.

A worktree’s copy, in the Claude Code app’s browser pane. The pane’s dashboard entry in .claude/launch.json serves the main checkout’s dashboard. To check a change made in a worktree, add a temporary entry that runs .claude/lib/serve-static.js <port> ../worktrees/<name>/forge-et-harness/.forge/dashboard (a relative path), copy the gitignored data files (tracker.js, signals.js, metrics.js, usage.js) into that worktree’s .forge/dashboard/, compare the two side by side, then stop both servers and remove the temporary entry. A dashboard change is checked in a browser, not only by a Node script.

Refresh

Automatic. Three hooks keep the data files in sync:

  • .claude/hooks/regen-tracker-dashboard.sh — on PostToolUse, regenerates tracker.js when .forge/tracker.yaml is edited and signals.js when .forge/lessons.md is edited; on Stop, regenerates both at the end of every turn, which catches writes no Edit/Write hook sees (a worktree session, a Bash write).
  • .claude/hooks/regen-metrics-dashboard.sh — on PostToolUse, regenerates metrics.js from .forge/metrics/*.jsonl after tracker edits or metrics-ledger edits. Empty ledgers produce window.METRICS.empty = true, so the section hides.
  • .claude/hooks/regen-usage-dashboard.sh — regenerates usage.js on every Claude Code Stop event in this project.

After Claude edits any of those source files, just refresh the browser tab.

Manual fallback for tracker.js (e.g., after a hand-edit outside Claude):

cd .forge/dashboard
{ printf 'window.TRACKER = '; yq -o=json . ../tracker.yaml; printf ';\n'; } > tracker.js

yq is already required by the harness gate-state hooks — install with brew install yq (macOS) if needed. Without yq the hook fails open with a one-line stderr note; tracker.js will go stale until you install it or run the manual command.

The dashboard never edits tracker.yaml, spec/plan files, or lessons.md — it’s a read-only view.

What the dashboard shows

Formats

Every date leads with its weekday and reads day, month, year — Thu 17 Sep 2026; Thu 17 Sep where space is tight (the drumbeat bars stack weekday, day and month); a due date reads Fri 20 Nov; the usage page reads Sun 2026·10·11. Relative times are spelt out (9 days ago, 7 hours ago), and counts are plain numbers, never zero-padded. A field holding N/A shows as a dash, the same as an empty one, except in an Owner column, where “N/A” marks a dropped feature or slice or a won’t-fix bug, which nobody will own, and a dash marks work nobody has picked up yet. Hovering a dropped feature or slice row, or its drawer (“Dropped by”), and a won’t-fix bug’s drawer (“Decided by”), names who decided (decided_by). No row is faded: a dropped feature or slice and a won’t-fix bug show their state through the status chip and the “N/A” owner, in normal text, as a done one does.

Hero

The project name is the header’s; the page heading repeats it for screen readers only. Only when there is no phase row to carry it does the hero show a one-line status string answering “where are things?” (derived from setup.* + delivery.current_phase + delivery.phases: a setup stage before Gate 3, “Phase N sealed · Phase N+1 not yet opened” between phases, “All phases sealed” at the end). While a phase row is shown, its heading carries “Phase N · title” and the done count instead. The hero no longer has a second line: the accepted risks and spikes are listed under the Setup gates, blocked features are named in the phase row’s In progress tile, and the update time is the header’s badge: the newest last_updated on any tracker entry, since the tracker has no top-level timestamp.

At-a-glance

Once delivery phases exist, the top of the page reads the whole project; one row per phase (items 3 and 4) follows the Setup section, just above Delivery, in phase order. Every row has the same heading — a caret, “Phase N · title” (with the status for a phase not in progress, and ✓ on a sealed one), the meta line and, for the active phase, the pace line — and clicking the heading folds or opens the tiles and progress bar under it. On every load the phase in scope (item 3) starts open and every other phase starts folded, so when Phase 2 opens, its row opens and Phase 1’s folds, with no change to the page:

  1. Whole project — Setup gates, Total features (split by phase, “N in Phase 1 · M in Phase 2”), Done (with the percentage and the shipped and dropped split) and Remaining (with its percentage: everything not done or dropped, in progress included, split by phase — so Done + Remaining = Total, and their percentages add up to 100%; a feature with no known phase is named as such rather than left out).
  2. The project-wide overall progress bar. The tiles’ percentages are features closed (shipped or dropped) over all features; the progress bars also weigh open bugs. A bar’s headline is features closed ÷ (all features + the open bugs), each open bug (open or in progress) counted as a share of a feature by severity — high 0.5, medium 0.25, low 0.1 (BUG_WEIGHT in index.html). A fixed or won’t-fix bug is not counted, because fixing it finished work its feature had already claimed. So open bugs hold a bar below the Done tile, fixing them moves it up, and a phase’s bar reads 100% only when every feature is closed and none of its bugs is open — the phase-seal condition. Work in flight extends the fill in a lighter shade: a feature sized by stage (FEATURE_PHASE_WEIGHT), a bug in progress at half its share. The line under the bar reads “N of M done · K in progress · B open bugs (I in progress) · Phase 1 x% · Phase 2 y%” (the phase figures weighed the same way). The weights and the sum are not on the page: hovering anywhere on the block — its heading, percentage, bar or the line under it — shows them, with their numbers, and hovering a “Phase N x%” figure shows that phase’s own sum. Before any feature exists, the bar shows the setup gates’ progress instead, and hovering it says how that is worked out.
  3. The phase row that starts open — the active phase, or between phases the next one to open, so Phase 2’s row opens by itself. A current_phase left pointing at a sealed phase is treated as no active phase. Its heading is “Phase N · title”; under it, the due_date, the done count with its percentage and the unresolved bugs scheduled for the phase (bugs[].delivery_phase, open or in progress — the phase cannot seal until each is fixed, closed as won’t-fix or moved). For the active phase a pace line follows: working days left to the due date (today included), the features per working day needed to close the rest (features not shipped and not dropped), and the rate so far — shipped features per working day from started through yesterday. Dropped features are not counted in the rate: they are not delivery, and a drop is recorded in the phase where it was decided, so counting them would raise the active phase’s rate with every later-phase drop. The ✓ on pace / ⚠ behind pace verdict appears only once 15 working days have passed (PACE_MIN_DAYS), because early features are mostly foundations and sizes differ, so a short run predicts little; before that the line shows the numbers alone. A working day is a weekday that is not on the team’s holiday list, delivery.holidays in tracker.yaml. With no list, every weekday counts. Hovering over the line shows how each figure is worked out, with the numbers that went into it: features left, working days left and the due date; features shipped, working days elapsed and the start date; the dropped features left out; when the verdict appears; and the holiday list used. Then four tiles: Features (paused noted — dropped ones are shown under Done), Done, In progress (features in spec, workitem-decompose, plan, dev or review, and which of them are blocked) and Backlog (how many are ready to start — every dependency shipped — and how many are waiting). Done, In progress and Backlog each show their share of the phase’s features, so they add up to 100% (paused features aside). Done is rounded on its own, matching the phase heading; In progress and Backlog split the rest of 100 by largest remainder, so separate rounding cannot make the row read 99% or 101%. The project row’s Remaining is worked out the same way against Done. With paused features in the phase, each share is rounded on its own. Up to three blocked or ready features are named in the tile; the tooltip always lists them all. Every tile whose figure is worked out says how on hover: Done (its share, shipped and dropped) and Remaining on both rows, In progress (the blocked features) and Backlog (the ready and claimed ones). A phase card’s hover covers its mini bar and its count alike.
  4. The phase progress bar — the same bar over the phase’s own features and the bugs scheduled for it (bugs[].delivery_phase): with no open bug its headline equals the phase’s Done tile, and the line under it reads “N of M done · K in progress · B open bugs (I in progress)”. Every phase row has its own, folded with the row when the row is folded. The Delivery section’s phase cards show the same figure, with the feature count and the open bugs: “50/73 · 66% · 17 open bugs”.

Blocked means started work waiting on a blocked_by dependency that is not yet at ship or done, other than the feature’s own sub-features: a parent delivered through its parts (F38 through F38-a … F38-h) is progressing, not blocked. A backlog feature whose dependency has not shipped is waiting its turn in the build order, so it is counted as waiting, not blocked. A dependency chip’s hover text uses the same words: “Waits on F1-b” on a backlog feature, “Blocked by F1-b” on started work.

Before phases exist, or once every phase is sealed, only one row is shown: Setup gates, Total features, Done, In progress and Not started (backlog and paused features — the started ones are in In progress), with the progress bar below it. A dropped feature counts as done — it is an exit state, the same as a dropped foundation slice (.claude/rules/tracker.md: a phase seals when every feature is done or dropped). So Done is ship + done + dropped, the phase tabs’ N/M uses the same count, and the progress bars give a dropped feature full weight. The Done tile’s sub-line counts shipped and dropped separately, so a dropped feature is never read as built; its row stays in its phase’s list with a DROPPED badge and a full meter in the done colour (tooltip “dropped”). Every value comes from tracker.yaml alone, so the strip renders whether or not local usage data exists.

Setup

A four-dot row (PRD → Architecture → Foundation → Decomposition; “Arch” and “Decomp” at phone widths) with labels and gate-pass dates. Foundation slices collapse behind a disclosure headed “Foundation slices · N” (N is every slice, dropped ones included). The list is built from the Delivery feature list’s rows, at the same full width: Slice (“FS-1 · title”), Status, Owner (the slice’s assignee, under the same name as the feature and bug lists’ owner column), a Progress meter filled by status as a feature’s is by stage (not started as backlog, in progress as development), Updated, and a caret that opens the slice’s drawer — status, owner, spec and plan paths, started and updated dates, who dropped it (decided_by), and its notes. Below 1080px a row wraps onto two lines, as a feature row does. When all four gates pass and foundation is done, the section collapses to a one-line ✓ Setup complete · sealed <date> summary under the dot row; the line is a disclosure holding one block per gate (owner, status, date, notes, risks and spikes, and Foundation’s slice list, each folded), so the phase row below sits near the top of the page.

Delivery

Two render modes, decided by delivery.phases.length:

  • Phased mode (delivery.phases non-empty): tabbed phase strip. Each tab shows “Phase N”, the status pill, title, mini progress bar, done/total count, the bar’s percentage (open bugs weighed, as above), the phase’s open bugs and the due date. Click a tab to view its detail panel. Every load opens the tab of the phase in scope (the phase row that is open above); the tab clicked is not remembered, so a reload returns to the current phase. Every panel — locked, in-progress or complete — shows the same feature rows: title, status badge (the stage written out: development, in review, shipped, decomposing), owner (a dash for a backlog feature, whose owner is not shown until work starts or it is claimed with /et-claim, or when none is set), active blockers, a progress meter weighted by phase, and last-updated. Rows sort by feature id unless a column is sorted (Column sorting, below), and a click opens the feature’s detail drawer. Data drift (a complete phase missing sealed, or a feature whose delivery_phase doesn’t match any phase id) surfaces inline with a ⚠ on the affected tab/row.
  • Flat mode (delivery.phases: []): one-row-per-feature list grouped by sub-status, sorted by last_updated. No phase scaffolding. Used by small projects that opt out of phases (under ~10 features).

Column sorting. The feature list, the open and closed bug lists (Signals), the foundation slice list and the Team table sort by any column: each column name is a button. Every list is always sorted by one column. Each page load starts every list on its first column: the feature list by Feature, ascending, in every phase panel; the open and closed bug lists by Bug, descending; the foundation slices by Slice, ascending; and the Team table by Team member, ascending. Clicking the sorted column reverses it; clicking another column sorts by it, ascending (smallest, oldest or A first). An arrow shows on the sorted column only, with its direction; under the pointer or keyboard focus, another column shows a faint ▲, the ascending sort a click gives. Status and severity sort by meaning, not alphabetically: a feature by its stage (backlog → … → done, then dropped and paused), a slice from not started to dropped, a bug from high to low severity and from to do to won’t fix. Ids sort naturally (F2 before F10), Updated by time, and Blocked by by the number of active blockers. Empty values go last in both directions, and rows with equal values keep the order the page built. Every phase panel shares one feature sort, so a click on any panel’s column sorts all of them; the open bug list sorts within each phase group, a feature’s detail drawer moves with its row, and the Team table’s summary rows stay at its foot. Nothing is stored: a sort chosen by clicking lasts until the page reloads, which starts every list on its first column again. Where the column names are hidden (the feature list below 1080px, the bug lists on a phone), the lists keep their current sort and cannot be re-sorted until the screen is wider.

Status chips. Every status on the page — feature and slice rows and drawers, phase tabs, gates, risks and spikes, waves, the release and its UAT cycles — is the same chip: an icon, the written label, and a tone that follows how far along the item is (queued, shaping, building, review, shipped, done, paused, dropped, plus attention and alert for risks and failures). The tone list and what each status maps to are in index.html, beside the .st-chip CSS and the chip() helper; a new status value needs a row in the matching map there, or it renders as a neutral chip with its raw text.

Team (conditional)

One row per team member named in an owner field or a foundation slice’s assignee, laid out like a ledger: currently working on (their features in progress, then their bugs in progress, one per line with its stage as text — F5-c · development, BUG-086 · in progress; the stage drops to its own line at phone widths, and at 480px and below the list moves under the name), then three counts at the right edge — foundation slices done (slices assigned to them at done; dropped slices are not counted), features done (features they own at ship or done) and bugs fixed (bugs they own at fixed). Every column takes an equal share of the width, except at 360px and below, where the name column is wider. The counts are right-aligned, headers included, so units sit under units. Rows follow the Delivery list’s feature rows — dashed hairlines between them and the same hover tint — while names stay in the body typeface. Above the total row, a Dropped or won’t fix row counts the dropped slices and features and the bugs closed as won’t fix, and a No owner recorded row (shown only when needed) counts finished work with no owner, so the totals always match the closed counts elsewhere on the page (the Done tiles; the slices closed while Foundation runs, and the “Foundation slices · N” count once it is sealed). A team member is shown by full_name from delivery.team in tracker.yaml (keyed by the first name the fields carry), or as written when not listed there. Names sort alphabetically unless another column is sorted (Column sorting). A feature counts once, for its tracker owner, even when others helped. Hidden when no slice, feature or bug has one — browser-computed from window.TRACKER.

There is no “Attention” section — paused / blocked / drift surface inline on the feature rows they describe. Accepted risks live in project-prd.md; scoped spikes live in design/architecture.md.

Release / UAT (conditional)

The release lifecycle, rendered from window.TRACKER.releases (one entry per phase’s UAT round) and window.TRACKER.uat_issues — both ride the existing regen-tracker-dashboard.sh mirror, so no new generation hook. Placed after Delivery, before Signals (it is the stage after a phase’s delivery). Populated interactively by the /forge-release command (or by hand). It shows one block per release, newest first, each with the UAT issues whose release_id names it (an issue naming no release is counted under the newest), and the section header names the newest release that is neither signed off nor live. Each block shows:

  • the release id, lifecycle status, scoped delivery phases, and the sign-off / go-live date once reached;
  • a six-step lifecycle track (build-complete → regression → uat → stabilize → signed-off → live) with the current step highlighted;
  • the cycle list (RC-n regression / UC-n UAT), each with a flow pass-count (e.g. 7 of 10 flows passed) and status;
  • a callout for any blocking UAT issues gating sign-off;
  • a UAT-issue triage breakdown (total · defects · change-requests · queries · open).

The entire section hides when releases is empty ([]) — exactly like the Usage section’s empty state, so existing projects render unchanged (NFR-1). Detailed per-cycle plans/reports and per-flow evidence live under .forge/release/<id>/; the tracker (and this section) hold only the compact summary + links.

Wave Drumbeat (conditional)

A cross-feature wave-cadence view, rendered from each feature’s waves[] in window.TRACKER. It appears (after Release / UAT, before Signals) only when at least one feature is decomposed into waves; otherwise it stays hidden. It shows:

  • in the section heading, the count of merged waves and of waves with an open PR, plus the median days from one wave’s merge to the next wave’s merge in the same feature, over the last 30 days;
  • a bar chart of waves merged per day over the last 14 days;
  • Merged today — each wave merged today, with its feature and the repos its work items touched;
  • Live waves — every wave at pr-open (shown “PR open”) or in-progress, with its status, the waves it waits on, and its repos. With github_org set in tracker.yaml, each repo links to a GitHub PR search for that wave.

Signals (the new section)

Leading-indicator tiles that surface harness-effectiveness over time; the section heading counts them. Each tile is a single number + sub-label; no bordered cards.

ID Question Source
S1 Phase throughput How many features are done (shipped or dropped) in the current phase, and how many are in progress? tracker.yaml features grouped by delivery_phase + sub-status
S2 Phase pace Are we on pace, given how long previous phases took? delivery.phases[].started + sealed (median of completed phases)
S3 Lead time How long does a feature take, end to end? Feature started → last_updated for phase: ship or done; the median, the time 3 in 4 features finish within (75th percentile), and the last-4-week trend
S4 Rework Are we redoing earlier passes over shipped features? Count of features with a non-empty follow_up_of — browser-computed from window.TRACKER (NOT signals.js)
S5 Paused or dropped What share of decomposed features stopped before shipping? “N of M”: features with phase: paused or dropped, of the features started; the sub-line splits paused and dropped
S6 Lessons Is the team still in heavy learning mode, or has the workflow stabilized? The headline is the total number of ## L-NNN lessons in .forge/lessons.md, beside a sparkline of the weekly count over the last 4 weeks — a lesson counts in a week by a dated ### YYYY-MM-DD — title heading, or a ## L-NNN — title heading’s body **Date:** line. The sub-line splits that total by status, one per line, each lesson in exactly one: awaiting upstream sync (**Sync target:** upstream, **Synced:** _pending_), synced upstream (upstream, **Synced:** names a forge-harness commit), project-only (**Sync target:** project-only), withdrawn (**Synced:** says withdrawn; the target no longer matters), and invalid (anything else — fix the entry to the format in .claude/rules/tracker.md § Lessons Entry Format). A status shows only when at least one lesson has it (all precomputed into signals.js)
S7 Open bugs How many post-ship defects are open, where, and are fewer being found over time? The headline is the count of tracker.yaml bugs[] with status open/in-progress, beside a sparkline of bugs found per week over the last 4 weeks (bugs[].found_date, in the same Monday-start UTC weeks as S6; falling is good). The sub-line gives the open bugs’ severities, the number of features or foundation slices they affect, the total filed, and the fixed and won’t-fix counts — browser-computed from window.TRACKER

Below the tiles, four collapsed lists give the detail, each shown only when it has entries: open bugs by scheduled-fix phase, highest id first (the phase line is left out when every open bug is scheduled for the current phase), and closed bugs (fixed and won’t-fix, highest id first) — each sortable by column (Column sorting, above) and laid out as one table per list under a row of column names, so the id, severity, title, feature, owner and status columns line up across every row; the feature column is the feature or slice the bug was filed against (affects), the owner column is the bug’s owner (who is fixing or fixed it, a dash while nobody has picked it up, “N/A” on a won’t-fix), the status column is a chip in the page’s status tones (to do, in progress, fixed or won’t fix). Each row ends in a caret and, as a feature row does, opens a drawer: status, severity, owner, who decided a won’t-fix (decided_by), the phase the fix is scheduled for, what it affects, when and in what it was found (found_date, found_in), what it breaks (spec_ref), the fix PR (fix_pr, each <repo>#<n> in it a link to that pull request in the tracker’s github_org), the write-up (the bug’s .forge/bugs.md section, or its doc), and its notes. The drawer moves with its row when the list is sorted. On a narrow screen the column names are hidden, the feature, owner and status move to a line under the title, and the caret stays beside the title. Rows in all four lists look like the Delivery feature rows: the same 8px row spacing, 12.5px text, dashed hairline between rows and hover tint. Bugs carry a severity but no priority: delivery_phase says when the fix is due. Then rework features with the features they rework, and dropped features — each with its title, its phase and its tracker notes, which record why it was dropped.

Reading the signals. These establish a baseline and surface direction — they do not (and cannot, in v1) prove the harness improved productivity. A non-harness comparison point doesn’t exist inside this dashboard. Lessons added per week (the bars on the Lessons tile) dropping over time is good (stabilization). Rework rate dropping is good; rising can be either thrashing (bad) or higher-quality specs catching more issues earlier (good) — needs human read of which. Bugs found per week (the bars on the Open bugs tile) dropping is good too, but a spike can mean a new kind of testing started (the first real Entra sign-ins produced one), not that quality fell. Phase pace is wall-clock, not effort.

Pricing never appears in the Signals section. Pricing is a local-data feature (depends on per-developer usage.jsonl), and the rest of the dashboard renders correctly without it — see Usage below.

Delivery Metrics (conditional)

Delivery Metrics is the estimation-baseline layer, rendered from window.METRICS which is generated from .forge/metrics/*.jsonl ledgers. It appears after Signals and before Usage only when at least one metrics row exists. It shows three grouped panels plus a baseline-volume footnote:

  • Cycle time — median feature cycle (feature_started → feature_done), spec authoring (feature_started → spec_approved), wave-1 cycle (spec_approved → wave-1 merged, decomp + first build), and later-wave cycle (prev-wave merged → this-wave merged, build only). Splitting wave-1 from later waves shows how much faster waves run once the spec is paid for.
  • Throughput — features/day and waves/day over a rolling window (default 14 days; override with FORGE_METRICS_WINDOW_DAYS).
  • Complexity signals — median workitems per feature and median agent runs.
  • Baseline volume (footnote) — completed features, merged waves, agent runs (with repair/retry count), and snapshot count: the denominators behind the medians.

These are labelled as baselines / estimate signals, not predictions or commitments. The source ledgers are append-only, role/project-level facts and are safe to commit; future token-joined *.local.jsonl variants stay gitignored.

Usage (conditional)

A one-line current-week summary — tokens this week · est. cost · link to usage.html — that renders only when window.USAGE has at least one row scoped to the current project. When local usage data is absent, the entire Usage section is hidden; no empty card, no placeholder, no “0 tokens” line. The full per-phase / per-day / per-developer / per-model breakdown lives in usage.html (the link target), which reuses the same usage.js data and rate table.

Pricing appears only in the Usage section and usage.html. Currency values do not appear in the hero, KPI strip, signals, or activity rail (FR-11 invariant — grep the rendered DOM for $ and you’ll see this).

Recent activity

The 5 most recent events derived from tracker timestamps (phase sealing/opening, feature last-updated transitions, gate runs). Listed newest-first with relative timestamps.

Privacy

usage.js and the underlying .forge/usage.jsonl are gitignored — they contain user_email values from git config user.email and are per-developer-per-machine local state. The three base .forge/metrics/*.jsonl ledgers carry role/project-level delivery facts and are committed. Future token-joined metrics variants (*.local.jsonl) are gitignored.

tracker.js, signals.js and metrics.js are gitignored too, but for a different reason: they are generated mirrors of committed sources (tracker.yaml, lessons.md, the metrics ledgers), and committing them would make every branch that regenerated them conflict (.forge/lessons.md L-049).

A team-wide usage rollup across developers (a shared data store) is not part of v1.

Updating Anthropic API rates

When Anthropic changes API prices, edit the RATES block in two places, identically, and set RATES_VERIFIED_DATE in usage.html (the only file that has it) to the day you checked:

  1. The inline script in index.html (used by the Usage one-line summary).
  2. The inline script in usage.html (used by the cost card + by-model breakdown).

Existing rows in ~/.claude/forge-usage.jsonl need no migration — cost is computed at render time, not at capture time. The dashboards apply the new rates to all history on the next refresh.

Customising

Templates ship generic. To rebrand for your project, edit index.html:

  • The Forge mark (inline SVG in the header)
  • Colors (CSS custom properties in the :root block at the top)
  • Section titles (“Setup”, “Delivery”, “Signals”, etc.)

tracker.js, signals.js, metrics.js and usage.js are generated — do not hand-edit.

Generated from .forge/dashboard/README.md by .claude/lib/render-docs-html.js. Markdown is canonical.