AI Operations Dashboard — User Guide

A complete walkthrough of how to use the dashboard, change what it shows, feed it your own data, add new panels, refresh it, and deploy it. Start here and read top to bottom the first time. Everything else in `help/` (rendered in-app at /help) is a deeper reference.

> Quick start (v0.2): New here? Don't read this top-to-bottom yet — run the wizard first. > > ``bash > npm install > npm run setup # ← interactive wizard, ~5 min, generates your config + AI agent files > npm run dev > ` > > The wizard walks you through product naming, theme pick, panel selection, data file seeding, and (optional) AI-agent integration. When it's done you'll have a working dashboard wired to YOUR data — no manual ai-ops-dashboard.config.ts` edits needed. > > For the full mental model + every escape hatch, read HANDBOOK.md (the canonical "how AI Operations Dashboard thinks" doc). This file is the day-2 reference once you're past setup.

Table of contents

1. What you're looking at
2. The five-minute setup
3. Daily use
4. Branding the dashboard
5. Picking panels
6. Feeding it your data
7. Adding a custom panel
8. Refreshing the data
9. Deploying
10. Common edits cheatsheet
11. Troubleshooting
12. Custom tabs (v0.4)

1. What you're looking at

When you open the dashboard you see four layers stacked top to bottom:

┌──────────────────────────────────────────────────────────┐
│  Banner          ← optional, full-width status strip     │
├──────────────────────────────────────────────────────────┤
│  Header          ← product title + tagline + tab strip   │
├──────────────────────────────────────────────────────────┤
│  Hero stats      ← five stat cards summarizing key data  │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  Active panel    ← whatever tab is selected              │
│                                                          │
└──────────────────────────────────────────────────────────┘

Banner — by default, the AI spend watchdog. Green at $0 today, yellow under $10, red above. You can remove it or replace it with your own.

Header — your product name, tagline, last-data-updated timestamp, and the tab strip. Each tab is a panel.

Hero stats — every panel can contribute up to two hero stats. The first five collected fill the strip. Always visible regardless of which tab is active.

Active panel — the content for whichever tab the user clicked. The default tab is set in ai-ops-dashboard.config.ts.

The page auto-refreshes every 120 seconds by default (set by refreshSeconds in the config). Hit Cmd-R for instant.

2. The five-minute setup

git clone <your-ai-ops-dashboard-folder> my-dashboard
cd my-dashboard
npm install                    # 19 seconds, 370 packages
npm run dev                    # http://localhost:3000

You'll see a working dashboard rendered against the sample data in data/, docs/operator-log.md, plans/execution-status.md, and knowledge/postmortems/. Nothing about this first render is real — it's all placeholder content shipped with the package so you can see what each panel looks like before you wire your own data.

Now do three things in order:

a. Edit your product name. Open `ai-ops-dashboard.config.ts` and change product.title, product.tagline, product.eyebrow. Save. The dashboard re-renders.

b. Pick a theme. Same file, change theme: "dark" to "warm" or "paper". Save. The colors flip.

c. Wipe the sample data. Open data/pending.json and replace its contents with your own items (schema in section 6 below). Repeat for docs/operator-log.md. Now it's *your* dashboard.

That's enough to feel like it's yours. Everything below is for going deeper.

3. Daily use

AI Operations Dashboard is designed to be read every morning and updated as you ship. There's a small set of files you edit by hand and a small set of files that update themselves.

Files you edit by hand:

| File | When | What | |---|---|---| | data/pending.json | Adding/closing work items | The "what's next" queue | | docs/operator-log.md | After every substantive work session | A timestamped entry — what you shipped, why, what's next | | knowledge/postmortems/<date>-<slug>.md | When something breaks | Root cause + fix + prevention | | plans/execution-status.md | When sprint state changes | Current sprint, sub-task ledger, decisions |

Files that update themselves:

| File | Refreshed by | When | |---|---|---| | data/recent-commits.json | npm run data:freeze-commits | Pre-push git hook, or any time you run it | | data/usage.json | npm run data:aggregate-usage | Daily cron, or any time data/usage-log.jsonl grows | | data/scheduled-jobs.json | You — but rarely changes | When you add/remove a recurring job |

The intended rhythm is: read the dashboard in the morning, edit the by-hand files as you work, push at the end of the day, let the pre-push hook regenerate recent-commits.json. The dashboard reflects everything next time you open it.

4. Branding the dashboard

Open `ai-ops-dashboard.config.ts`. The product block is your branding:

product: {
  title: "Acme AI · Ops",         // the big header
  tagline: "Live spend, work-in-flight, incidents.",
  description: "...",              // <meta description>
  eyebrow: "Internal",             // small uppercase label above the title
},

Picking a theme. Three themes ship in app/globals.css:

• dark — default. Deep navy, indigo accent. Best for AI / dev tools.
• warm — cream background, brown accent. Best for content / publication brands.
• paper — white background, blue accent. Best for traditional dashboards / status pages.

To roll your own theme, copy a [data-theme="..."] block in app/globals.css, rename it, change the CSS variables, then set theme: "yours" in the config. The variables drive every color in the dashboard.

Hiding "Powered by AI Operations Dashboard". In the config:

branding: { showPoweredBy: false },

Allowed under the Pro and Agency license tiers — see LICENSE.

5. Picking panels

The panels array in ai-ops-dashboard.config.ts controls which tabs render and in what order:

import { panel as overview } from "@/components/panels/overview-panel"
import { panel as activity } from "@/components/panels/activity-panel"
import { panel as pending } from "@/components/panels/pending-panel"
import { panel as usage } from "@/components/panels/usage-panel"
// ... import the ones you want

export const config = {
  // ...
  panels: [overview, activity, pending, usage],
}

To remove a panel — delete the import + the entry from the array. Don't delete the panel file unless you're certain you won't use it again.

To reorder tabs — just rearrange the array. The first panel is the default tab unless you set defaultTab explicitly.

The 12 built-in panels:

| Panel | What it reads | What it shows | |---|---|---| | overview-panel | Synthesizes data from the others | Top priorities + last log + recent commits + AI spend | | plan-panel | plans/execution-status.md | Roadmap, sub-task ledger, decision log | | sprints-panel | plans/execution-status.md | Sprint-progress board | | activity-panel | data/recent-commits.json | 90-day commit heat map + chronological commit list | | pending-panel | data/pending.json | Open work items, priority-sorted, with step lists | | log-panel | docs/operator-log.md | Operator log, newest first | | postmortems-panel | knowledge/postmortems/*.md | Severity-tinted incident cards + prevention summary | | usage-panel | data/usage.json | AI spend rolled up by day, month, quarter, model | | scheduled-panel | data/scheduled-jobs.json | Recurring job catalogue (tab label: "Scheduled Jobs") | | repos-panel | data/connected-repos.json + data/connected-repos-signals.json | One card per connected repo with its aggregated signals | | docs-panel | every markdown file in your operator docs/ (operator-log.md excluded) | In-app viewer for your own operator docs (the dashboard's product guides live at /help) | | skills-panel | filesystem scan of ~/.claude (Claude Code only) | Inventory of every plugin / skill / MCP server / agent |

Don't see a panel you want? Look at the `templates/` folder — nine pre-built configs show different combinations. Or write your own (section 7).

6. Feeding it your data

Every panel reads from flat files in your repo. No database. No API keys. The files are checked into git so the dashboard works on any machine with a clone.

data/pending.json

The work queue. Each item:

{
  "id": "wire-stripe",
  "title": "Wire up Stripe for paid tier",
  "why": "Free users have nowhere to convert. Launch blocker.",
  "priority": "high",
  "doer": "you",
  "ref": "app/api/checkout/",
  "dateAdded": "2026-05-15",
  "steps": [
    "Create Stripe account in test mode",
    "Add STRIPE_SECRET_KEY to .env",
    "Build /api/checkout/session route"
  ],
  "tags": ["billing", "launch-blocker"]
}

Required: title. Everything else is optional. priority is "high" | "medium" | "low". Items auto-sort by priority then dateAdded.

docs/operator-log.md

A markdown log. Newest entry on top. Each entry follows this shape:

## 2026-05-21 09:30 — Shipped the pending → done flow

**Why:** Items piling up in pending was driving a "what did I close this week" question I couldn't answer.

**What shipped:** Click-to-close on pending items, moves them to docs/operator-log.md with a generated entry.

**Tags:** ux, queue

**Next:** Bulk close action.

The log panel parses the four **Why:** / **What shipped:** / **Tags:** / **Next:** fields. Tags split on commas or middle-dots.

knowledge/postmortems/

One markdown file per incident. Naming convention: YYYY-MM-DD-slug.md. Frontmatter sets title, date, severity (p0 / p1 / p2 / p3). Body has free-form ## What happened, ## Root cause, ## Fix, ## Prevention sections. The panel auto-extracts the summary + prevention bullets.

plans/execution-status.md

Markdown file with three tables: sprint progress, sub-task ledger, decision log. Plus three header fields at the top:

**Last update:** 2026-05-21 09:30 PDT
**Current state:** v0.2 in flight
**Next sub-task on resume:** S2.4 — wire Stripe checkout

The plan panel parses the tables and renders them with status chips (✅ shipped, 🟡 queued, etc.).

data/usage.json

AI spend rollup. Built automatically by npm run data:aggregate-usage from the per-call log at data/usage-log.jsonl. You don't edit this by hand — your code writes one JSONL line per API call, the aggregator rolls it up.

Per-call log line shape:

{"at":"2026-05-21T10:23:00.000Z","model":"claude-opus-4-7","tokensIn":1240,"tokensOut":340,"cost":0.0289,"label":"freeze-commits"}

data/scheduled-jobs.json

Catalogue of recurring jobs. Edit by hand when you add a cron, a GitHub Action, or a git hook.

data/recent-commits.json

90 days of git history. Refreshed by npm run data:freeze-commits (or the pre-push hook). Never edited by hand. Committed to the repo because the production build can't always run git log.

data/connected-repos.json *(v0.3)*

Registry of every external repo wired to this dashboard via the ai-ops-dashboard CLI. One row per repo: id, name, path, linkedAt, lastReportedAt, writeCount, emitSignals, writeTokenFingerprint. Updated by npx ai-ops-dashboard init, npx ai-ops-dashboard link, and every subsequent CLI write. Read by the Repos panel + the multi-repo Activity aggregator. Edit by hand only to revoke a write token (clear writeTokenFingerprint) or change an emitSignals allowlist.

6.5. The ai-ops-dashboard CLI *(v0.3)*

AI Operations Dashboard v0.3 ships a thin CLI (cli/ai-ops-dashboard.mjs, exposed as the ai-ops-dashboard bin) so any repo on your machine can push signals into a single shared dashboard without you opening the dashboard repo in your editor. The CLI does atomic JSON writes, fingerprint-checks every write against a per-repo token, and works equally well from a human shell or a Claude Code session.

One-time per repo:

cd ~/code/their-saas
npx ai-ops-dashboard init --dashboard /Users/you/ai-ops-dashboard

That creates .ai-ops-dashboard-client/ in the current directory (config, AGENTS.md, README, gitignore), appends the repo to the dashboard's data/connected-repos.json, and issues a write token. Idempotent — re-running refreshes display name and emit-signals without resetting the write count.

Daily writes from inside any connected repo:

# Append an entry to the dashboard's operator log
npx ai-ops-dashboard log "Shipped pricing-v2 to Stripe" --tags pricing,launch

# Add a pending item
npx ai-ops-dashboard pending add "Wire abandoned-cart email" --priority high --doer you

# Close a pending item (also writes a closure entry to the log)
npx ai-ops-dashboard pending close abandoned-cart-email

# Write a new postmortem
npx ai-ops-dashboard postmortem "Stripe webhook outage 2026-06-02" \
  --severity high --tags payments,outage

# Show dashboard status (last write, dashboard path, permissions)
npx ai-ops-dashboard status

# Re-fingerprint write tokens after editing connected-repos.json by hand
npx ai-ops-dashboard refresh

Wiring repos from the wizard. Setup step 7 (/setup/connect in the browser, or the new step in npm run setup) accepts absolute repo paths and shells out to ai-ops-dashboard init for each one in a single batch. Useful when onboarding 3+ repos at once.

For Claude Code sessions. .ai-ops-dashboard-client/AGENTS.md is the contract Claude reads on every session start — it tells the agent which dashboard files are source-of-truth and which CLI commands are safe to run without re-prompting. The dashboard's manifest in .ai-ops-dashboard/manifest.json lists every recipe path the connected repo may write to.

Full SOP — token rotation, schema, troubleshooting, multi-machine setups: help/connecting-repos.md.

7. Adding a custom panel

This is what makes AI Operations Dashboard extensible. A panel is a single TypeScript file in components/panels/. Scaffold one:

npm run new:panel -- metrics

That creates components/panels/metrics-panel.tsx with a starter template. Open it and you'll see four sections to fill in:

export const panel: PanelDefinition<MetricsData> = {
  id: "metrics",
  label: "Metrics",
  hint: "Tooltip text shown on tab hover.",

  // 1. Declare what data files you read.
  //    Used by the docs page + dev-mode file watcher.
  sources: [
    { path: "data/metrics.json", kind: "file", purpose: "Source of truth" },
  ],

  // 2. Load your data. Runs server-side, once per page render.
  //    Use readJson / readMarkdown / walkMarkdown / readGitLog / fetchJson.
  async loader(ctx) {
    const file = path.join(ctx.projectRoot, "data", "metrics.json")
    return readJson<MetricsData>(file, { items: [] })
  },

  // 3. (Optional) Contribute hero stats. Each panel can add up to 2.
  heroStats(data) {
    return [{ label: "Metrics", value: data.items.length }]
  },

  // 4. Render. Receives the data your loader returned.
  Component({ data }) {
    return <div className="data-card">...</div>
  },
}

Then register it in ai-ops-dashboard.config.ts:

import { panel as metrics } from "@/components/panels/metrics-panel"

// ...
panels: [overview, activity, metrics, pending],

Save. Visit /?tab=metrics. Done.

Available data-source adapters (import from @/lib/data-sources):

• readJson<T>(path, fallback) — typed JSON parse with safe fallback
• readMarkdown(path, projectRoot) — single .md file with frontmatter
• walkMarkdown(dir, projectRoot, opts) — recursive folder walk
• readGitLog(opts) — frozen-snapshot first, git log fallback
• fetchJson<T>(url, fallback) — REST endpoint with in-memory cache

Error handling. If your loader throws, the panel renders a small error card with the message. Other panels are unaffected. You don't need try/catch inside loaders.

Empty states. If your loader returns null, undefined, or an empty array, AI Operations Dashboard renders a generic "no data" card listing the panel's declared sources. You can supply a custom Empty component on the panel definition.

Full reference: help/panels.md.

8. Refreshing the data

There are four ways the dashboard gets fresh data, in increasing order of automation:

a. Manual refresh — edit the markdown/JSON file, reload the browser. Always works. Best for pending.json, operator-log.md, postmortems.

b. Auto-refresh on page — by default the page reloads every 120 seconds via <meta http-equiv="refresh">. Tune via refreshSeconds in the config; set to 0 to disable.

c. Build-time regeneration — npm run data:build runs all generator scripts (freeze-commits, aggregate-usage). Wired into npm run build, so every deploy ships fresh data. Run it manually any time:

npm run data:build

d. Pre-push git hook — recommended. Regenerates data/recent-commits.json before every push. Setup:

# Add to .git/hooks/pre-push (make executable)
#!/usr/bin/env bash
npm run data:freeze-commits
git add data/recent-commits.json
git commit -m "[freeze] data/recent-commits.json refresh" --no-verify 2>/dev/null || true

Why the manual hook? Because on Vercel and other deploy platforms the build container ships a shallow git clone, so the production build can't reliably regenerate git history. The pre-push hook ensures the committed snapshot is always fresh.

Watch mode for dev: in a second terminal alongside npm run dev:

npm run data:watch

This auto-runs aggregate-usage whenever data/usage-log.jsonl grows. Useful when actively shipping AI calls.

9. Deploying

AI Operations Dashboard supports three deploy modes. Pick one with the AI_OPS_DASHBOARD_MODE env var.

Mode: `vercel` (default)

vercel deploy --prod

Or push to a connected GitHub repo. Vercel auto-detects Next.js, runs npm run build, deploys. SSR on every request. Use Vercel preview protection to put it behind auth.

Mode: `static` — *v0.2 roadmap.* Today the page uses URL search params for tab routing + live filesystem reads, both of which preclude Next.js static export. The v0.2 release will add per-tab pre-rendering via generateStaticParams so you can deploy as plain HTML to S3, GitHub Pages, Netlify, or file://. Until then, use Vercel mode (their free tier covers most indie projects).

Mode: `node`

AI_OPS_DASHBOARD_MODE=node npm run build
npm start

Runs as a Node server. Allows future SSE / WebSocket live updates (roadmap v0.2). Today behaves the same as Vercel mode but on your own infrastructure.

Docker — sample Dockerfile in help/deployment.md.

Auth — three patterns documented:

• Vercel preview protection (built-in on the platform)
• Cloudflare Access in front of any deployment
• Basic-auth middleware in middleware.ts (snippet in deployment doc)

Full deployment matrix: help/deployment.md.

10. Common edits cheatsheet

| I want to… | Edit this file | |---|---| | Change the dashboard title | ai-ops-dashboard.config.ts → product.title | | Switch themes | ai-ops-dashboard.config.ts → theme | | Remove a tab | ai-ops-dashboard.config.ts → delete the import + array entry | | Add a tab | Write the panel, then add to the array in ai-ops-dashboard.config.ts | | Change which tab loads by default | ai-ops-dashboard.config.ts → defaultTab | | Disable auto-refresh | ai-ops-dashboard.config.ts → refreshSeconds: 0 | | Hide the AI spend banner | ai-ops-dashboard.config.ts → delete banner: spendBanner | | Hide "Powered by AI Operations Dashboard" | ai-ops-dashboard.config.ts → branding: { showPoweredBy: false } (paid tier) | | Add a new work item | Append to data/pending.json | | Log today's work | Append to docs/operator-log.md | | Record an incident | New file in knowledge/postmortems/ | | Update the sprint state | plans/execution-status.md | | Tune the AI spend thresholds | data/usage.json → thresholds.dailyYellow / dailyRed | | Add a custom color | New [data-theme="..."] block in app/globals.css | | Change the footer attribution text | components/dashboard/footer.tsx |

11. Troubleshooting

The dashboard is blank / 500 error. Check the terminal running npm run dev. One of your data files is probably malformed JSON. Run node -e "JSON.parse(require('fs').readFileSync('data/pending.json','utf-8'))" to find which one.

A panel says "Panel error". The panel's loader threw. The error message is in the card. Most common cause: a data file's shape doesn't match what the panel expects. The page itself still renders — other panels are unaffected.

Activity tab is empty on Vercel but full locally. Vercel's shallow clone doesn't ship git history. Run npm run data:freeze-commits locally and commit the resulting data/recent-commits.json. Set up the pre-push hook (section 8) so you don't forget.

Tab strip wraps to multiple lines. You have too many panels for your viewport. Either drop a panel from the config or shorten panel label fields (3-5 chars works fine — "Plan" not "Master Plan").

Spend banner stuck at $0. Your data/usage.json was never aggregated. Run npm run data:aggregate-usage. If data/usage-log.jsonl is also empty, you haven't instrumented any AI calls yet — there's nothing to roll up.

"Cannot find module '@/...'." Run npm install, then make sure your editor uses the project's tsconfig.json (VS Code prompts to do this automatically when you open the folder).

Refresh interval too aggressive / not aggressive enough. Edit refreshSeconds in the config. Anything below 30 starts feeling jumpy. Anything above 600 starts feeling stale.

Want to deploy without the "Powered by AI Operations Dashboard" line. Upgrade to a Pro tier license and set branding.showPoweredBy: false. See LICENSE.

More questions? help/faq.md has 14 more.

12. Custom tabs

v0.4 added a first-class way to scaffold your own tabs without writing a panel component by hand. Pick one of five archetypes that match the shape of your data, run a single command (or click through the visual wizard), and the dashboard wires the rest.

The five archetypes

| Archetype | Shape | Pick when | |---|---|---| | list | Flat array of records | You want a backlog, watchlist, follow-ups queue, reading list — anything you add, edit, close | | timeline | Append-only journal, newest on top | Decision logs, narrative changelogs, retros — anything you only append to | | metrics | Daily key/value rollup | Health scores, single-number KPIs, gauge dashboards | | folder | Markdown directory + frontmatter | Postmortem-style folders, runbooks, playbooks | | rest | HTTP fetch + cache (with TTL) | Live third-party data — Vercel status, GitHub stars, anything behind an HTTP JSON endpoint |

Each archetype owns a loader, a default Component, a JSON schema, and a CLI verb set. You can override the Component later if you want a custom layout — the archetype keeps the data shape stable.

The add-tab wizard

Visit `/admin/add-tab` when the dev server is running. The wizard walks through: archetype → slug → label → fields → AI allow-list → review. On commit it writes the panel component, appends an import to ai-ops-dashboard.config.ts, registers the entry in .ai-ops-dashboard/manifest.json -> customPanels[], and seeds an empty data file.

The CLI

Same flow, no browser:

# Scaffold (interactive — prompts for fields + allow-list)
npx ai-ops-dashboard panel add --slug followups --label "Followups" --archetype list

# Scaffold (non-interactive — pass the spec)
npx ai-ops-dashboard panel add \
  --slug decisions \
  --label "Decisions" \
  --archetype timeline \
  --fields note:string:required,owner:string

# Write to a custom panel via the generic dispatcher
npx ai-ops-dashboard followups add --title "Email about pricing" --priority medium
npx ai-ops-dashboard followups close <id>
npx ai-ops-dashboard decisions append --note "Picked Postgres over SQLite"
npx ai-ops-dashboard health record --date 2026-06-02 --score 87
npx ai-ops-dashboard runbooks new --slug deploy-rollback
npx ai-ops-dashboard vercel-status refresh

The dispatcher looks the slug up in .ai-ops-dashboard/manifest.json -> customPanels[], finds the archetype, validates the verb against aiAllowedTasks, and delegates to the right handler. If a verb isn't in the allow-list, the CLI refuses — edit the manifest to grant it.

Full archetype reference + field schemas: help/custom-tabs.md.

Skills inventory (Claude Code only)

A read-only tab that scans ~/.claude/skills, ~/.claude/agents, ~/.claude/plugins, and your declared MCP servers. Opt in by flipping ai.includeSkillsInventory: true in ai-ops-dashboard.config.ts. Includes a Review mode that exports the inventory (or a multi-selected subset) to:

• JSON — ~/Downloads/ai-ops-dashboard-skills-inventory-<timestamp>.json
• Markdown — ~/Downloads/ai-ops-dashboard-skills-inventory-<timestamp>.md

Use it to mirror your Claude setup on a new machine, audit what's installed before a cleanup, or hand the manifest to another Claude Code session to bootstrap an identical environment. The panel never writes back to ~/.claude/* — deletions are operator-driven, never agent-initiated.

What to read next

• help/configuration.md — full schema reference for every config field
• help/panels.md — deep dive on the panel API, all 12 built-ins, custom panel patterns
• help/custom-tabs.md — every archetype + field schema + CLI dispatcher reference (v0.4)
• help/deployment.md — every deploy target with step-by-step instructions
• help/upgrading.md — semver discipline + migration policy
• templates/ — nine drop-in starter kits (ai-founder, indie-saas-founder, content-creator, consulting-agency, oss-maintainer, personal-os, ecommerce-operator, research-lab, blank-slate). Pick one in the wizard or copy by hand.