DashClaw

---
source-of-truth: false
owner: maintainers
last-verified: 2026-08-03
doc-type: handoff
---

# DashClaw (v2 Governance Runtime)

DashClaw is AI agent decision infrastructure: a focused control plane for policy enforcement, decision recording, assumption tracking, and risk signals.

## Commands

```bash
npm run dev          # local dev server (port 3000)
npm run lint         # eslint
npm run typecheck    # tsc --noEmit — required for any changed .ts file, even outside app/
npm test             # vitest; one file: npm test -- <file> (full suite before push: npx vitest run)
npm run build        # next build — required for any change under app/**
npm run db:migrate   # apply pending schema to local DB (auto-loads .env.local; idempotent)
```

All other scripts stay in `package.json`; add one here only when the agent keeps needing it.

## Verify before you commit

CLAUDE.md is advisory; CI is not. A push is its own step - run these and READ the output first:

- `npm run lint`
- `npx vitest run` - the **full** suite (targeted runs miss regressions in unrelated files). Tests run on **node** by default; only `.jsx`/`.tsx` tests and the files listed in `DOM_TESTS` in `vitest.config.js` get jsdom (that split took the suite from 511s to 161s). A new test that needs `window`/`document` goes in that list or carries `// @vitest-environment jsdom`; the tell is `document is not defined`.
- `npx next build` - required for any change under `app/**`
- For any changed `.ts` file (even outside `app/`), run `npm run typecheck` before pushing - vitest transpiles without type-checking and will pass; the build runs `tsc` and will not.
- **Entry-path drills (v8.3, `scripts/drills/README.md`)**: a release touching `cli/**`, `scripts/setup.mjs`, or the `up` path runs `npm run drill:fresh-windows` (and/or `drill:fresh-linux`) first; one touching hosted mint/export/import runs `npm run drill:hosted`. A drill failure is a broken ship - fix on the spot, log it in the maintainer log. These test the DISTRIBUTION path on factory-fresh machines; CI's `up-smoke.yml` (from-source, dev-imaged runners) does not cover that class.

CI also gates `openapi:check`, `api:inventory:check`, `route-sql:check`, and `version:check`. The pre-commit hook lints staged JS/TS, typechecks when a staged file is `.ts`/`.tsx`, and regenerates the doc/contract/bundle artifacts for you (see "Generated artifacts").

Session discipline (from usage-log audit, 2026-08-03):

- **State a stop condition before any search or edit loop** (max iterations or a concrete success check). When it's hit, stop and re-plan instead of grinding the same Bash/Edit/Read cycle.
- **Model routing:** short, mechanical tasks (lookups, doc tweaks, single-file edits) belong on a cheap model (Haiku/Sonnet); reserve Opus/Fable for architecture, debugging, and security reasoning.

## Gotchas (what you can't infer from the code)

- **After pulling changes that touch `schema/schema.js` or `drizzle/*.sql`, run `npm run db:migrate`.** Otherwise your local DB stays on the old schema while middleware/routes expect new columns; the auth lookup fails and **every authenticated request answers 503 `SCHEMA_NOT_INITIALIZED` naming the migrate fix** (before v4.61.0 this surfaced as a misleading 401 "Invalid or missing API key"). One-command fix.
- **No direct SQL in route files.** `app/api/**/route.js` must go through repositories (`app/lib/repositories/*.repository.js`); `npm run route-sql:check` blocks any increase in per-file direct SQL. Repositories are exempt.
- **`.gitattributes` drifts silently.** living-merge install + CRLF normalization leave `.gitattributes` modified-but-unstaged, which silently blocks `git pull --rebase`, `git push`, and worktree ops. Before those, run `git status` and either `git add .gitattributes && git commit` or `git checkout -- .gitattributes` if the diff is LF/whitespace-only. Starting a session with `M .gitattributes` is the norm here, not an anomaly.
- **Documented counts derive themselves — don't hand-edit them.** Cited counts (route totals, MCP tool/resource, SDK method, guard policy, shield) are written from source-of-truth by `scripts/check-doc-counts.mjs`, not maintained by hand. Pre-commit runs `--write --staged-only`, which rewrites those numbers in files **already staged** and re-stages them; a drift in an unstaged file is reported instead, so it can never sweep unrelated edits into your commit. Run `npm run doc:counts:fix` to derive them everywhere, `npm run doc:counts` to just look. CI's `--strict` run stays authoritative. Two things stay manual on purpose: MCP tool **enumerations** (the group taxonomy is editorial) and `last-verified` **date stamps** (auto-advancing one would assert a human verified something they did not).

## Governance boundary

DashClaw is a **minimal governance runtime, not an agent platform**. We do not give agents tools to achieve goals (Calendar, Messaging, CRM); we provide the infrastructure to **govern** those goals.

- **Core runtime**: `app/api/` (governance routes).

## Where to look first

Read these for depth instead of duplicating them here:

- `PROJECT_DETAILS.md` - canonical system map and boundary rules.
- `QUICK-START.md` - the 8-minute "first governed action" path.
- `docs/architecture/runtime-api.md` - the 4-step governance loop.
- `sdk/README.md` - Node SDK surface and error handling.

## Essential surfaces

- `/approvals` - THE hero surface: the live stream of what your agent just tried and the items waiting on your one-click approval.
- `/decisions` - causal-chain ledger of every governed action.
- `/setup` - readiness verification and instance health.
- `/connect` - onboarding to the first governed action.

## Tech stack

- Node 20+, Next.js 16 (App Router), Postgres (Neon recommended).
- Versions live in their manifests (`package.json`, `sdk/package.json`, `sdk-python/pyproject.toml`, `plugins/dashclaw/.claude-plugin/plugin.json`) and are injected into UI strings via `next.config.js`. **Never hardcode a version number in this file** - `npm run version:check` fails the build if you do. The platform and both SDKs (`package.json`, `sdk/package.json`, `sdk-python/pyproject.toml`) share **one version** - bump them together with `npm run version:set <x.y.z>`, enforced by `npm run version:sync:check` (the `plugin.json` bundle keeps its own version). A DEPRECATED `dashclaw/legacy` SDK subpath exists for older integrations (removed in v5.0.0; see `docs/sdk-parity.md`).

## Definition of done includes a human-visible, human-OPERABLE surface

The full contract is **`HUMAN-EXPERIENCE.md`** at the repo root (adopted 2026-07-02
by Wes's direction) — read it before designing any feature. The classic agent failure
mode in this repo: build the schema + route + repository + tests for a feature and
never give a **human** a way to see or use it — the feature ships and silently
disappears, or ships with a terminal command where a button belongs. Before calling
any feature done, answer four questions in writing (spec, plan, or ship summary):

1. **Where does a human SEE it?** Name the page and the click path from an existing
   surface (nav, sidebar, an existing detail view). A deep URL nobody links to is not
   a surface.
2. **Is it discoverable?** The path must start somewhere humans already are. If the
   feature only enriches an API response, the consuming page must render the new data.
3. **Is every human step a CLICK?** Wherever the human's role is judgment (review,
   approve, ratify, tune, dismiss), it's a button/toggle/form in the product — never
   "copy this command," "open GitHub," or "run this script." Zero-terminal test:
   walk the human's entire role for the feature; terminal commands + GitHub visits
   required must be zero.
4. **Was it verified rendered?** Drive the actual page (frontend-verify skill /
   headless browser) and confirm the new element appears and its controls work — API
   tests and unit tests prove the data exists, not that anyone can see or use it.

API/SDK-only features are allowed, but that is an **explicit stated decision** in the
spec ("no UI surface because X"), never a default you fall into. The `dashclaw-ship`
skill enforces this as a UI-discoverability gate at ship time; this rule exists so the
surface is *designed in* at build time, not bolted on at the gate. The marketing site
is updated with new features **in the same ship** (`HUMAN-EXPERIENCE.md` clause 4).

## Generated artifacts - never edit by hand

`public/downloads/*.zip` bundles and the `plugins/dashclaw/` skill/hook mirrors are produced by `npm run bundles:refresh` (`scripts/refresh-bundles.mjs`), which mirrors the hand-authored `public/downloads/dashclaw-governance/` skill and canonical `hooks/` scripts into `plugins/dashclaw/` and rebuilds the three download zips. The pre-commit hook runs it automatically when staged changes touch `hooks/`, `plugins/dashclaw/`, or `public/downloads/dashclaw-governance/`, and stages the result. **Editing the mirrors/zips by hand is pointless - the next refresh overwrites it.** Regenerate instead.

## Design changes

Before any UI, copy, or visual change, **read `.impeccable.md` at the repo root** - the canonical design context (users, brand, aesthetic, 4 anti-references, 7 tiebreaker principles). **Never hardcode hex values**; use the CSS tokens in `app/globals.css` and the Tailwind theme. A `UserPromptSubmit` hook (`.claude/hooks/impeccable-reminder.py`) nudges you when design keywords appear, but the rule holds either way.

## Lessons from agent-log review (2026-06-05)

DashClaw-specific gaps surfaced from my agent history (most generic rules are already enforced above or by the `.claude/hooks` guards):

- **Model/provider drift, not just version drift.** When supported models change, update `app/lib/providers/providerRegistry.ts` (and the model-strategy catalogs) and run `npm run pricing:refresh` — never hardcode model ids or prices. Verify current ids (Context7/web) before wiring them; "Opus 4.6 is out" / "Unknown model: gpt-5.3-codex" has bitten me repeatedly. Latest Opus is 4.8 (2026-06).
- **Don't cosmetically rename `.jsx`↔`.js`** (e.g. keep `app/connect/page.jsx`). It churns diffs for zero behavior change.
- **DashClaw MCP server needs only `DASHCLAW_URL` + `DASHCLAW_API_KEY`** (optionally `DASHCLAW_AGENT_ID`). `org_id` is **not** required for MCP — don't add it.
- **Maintain plugin parity across runtimes.** When you add a capability to the Claude Code plugin, mirror it for Codex and **Hermes** (`plugins/`); those parity gaps have been flagged.
- **On PR/spec reviews, trust only what you read** — don't pass an implementer's or sub-agent's "it works" through; re-verify against the actual code/tests.
- **Token/cache discipline — the whales live here.** This repo is where my biggest context burns happen (multi-hundred-turn Opus sessions at >300K context/turn). The global CLAUDE.md "Token & cache discipline" applies; in this repo especially: explore via **GitNexus queries + sub-agents** instead of broad file reads, `/clear` between unrelated tasks, route reviews/exploration to Sonnet/Haiku, and keep build/test logs out of the thread (read only the failures).

<!-- gitnexus:start -->
# GitNexus — Code Intelligence

This project is indexed by GitNexus as **DashClaw** (32131 symbols, 63068 relationships, 786 execution flows).

> Index stale? Run `node .gitnexus/run.cjs analyze --index-only` from the project root — it auto-selects an available runner. No `.gitnexus/run.cjs` yet? Bootstrap with `npx`, `bunx`, or `pnpm dlx` — e.g. `bunx gitnexus@latest analyze` (npm 11 npx crash; #1939).

## Always Do

- **MUST run impact before editing.** Use `impact({target: "symbolName", direction: "upstream"})` or `node .gitnexus/run.cjs impact "symbolName" --direction upstream --repo .`; report callers, processes, and risk. Never substitute grep for graph analysis.
- **MUST analyze graph changes before committing.** Use `detect_changes({scope: "all"})` (MCP) or `node .gitnexus/run.cjs detect-changes --scope all --repo .` (CLI fallback). `partial: true` or `truncated: true` is not a clean check — a zero means unseen, not unaffected; re-run it. For regression review: `detect_changes({scope: "compare", base_ref: "main"})` or `node .gitnexus/run.cjs detect-changes --scope compare --base-ref "main" --repo .`.
- MUST warn on HIGH/CRITICAL `risk` pre-edit; never use `riskSharedAxes` to waive a HIGH/CRITICAL `risk` warning. Compare File/symbol: MCP File omits axes; Graph-RAG expands File.
- **MUST treat `risk: UNKNOWN` as unresolved, not as low.** An empty caller set is not evidence the symbol is unused — it can also mean the callers are not resolvable by the index (plain-object property access, dynamic dispatch, cross-language calls). `impact` pairs `UNKNOWN` with a `riskNote` saying so. Confirm with a text search before treating the symbol as safe to change or delete; do not proceed on the strength of a zero.
- **MUST use `query({search_query: "concept"})` for concepts/flows, `context({name: "symbolName"})` for a named symbol, or `impact` for blast radius, on read-only callers, dependencies, imports, or execution flow.** Graph first; text search only for empty/`UNKNOWN`/literals.
- For security review, `explain({target: "fileOrSymbol"})` lists taint findings (source→sink flows; needs `analyze --pdg`).

## Never Do

- NEVER edit a function, class, or method before MCP/CLI impact analysis.
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis, and never read `UNKNOWN` as an all-clear — it means the walk could not answer, which is the one verdict that requires confirming by other means.
- NEVER rename symbols with find-and-replace — use `rename` which understands the call graph.
- NEVER commit before MCP/CLI graph change analysis.

## Resources

| Resource | Use for |
| --- | --- |
| `gitnexus://repo/DashClaw/context` | Codebase overview, check index freshness |
| `gitnexus://repo/DashClaw/clusters` | All functional areas |
| `gitnexus://repo/DashClaw/processes` | All execution flows |
| `gitnexus://repo/DashClaw/process/{name}` | Step-by-step execution trace |

## CLI

| Task | Read this skill file |
| --- | --- |
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus-exploring/SKILL.md` |
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus-impact-analysis/SKILL.md` |
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus-debugging/SKILL.md` |
| Rename / extract / split / refactor | `.claude/skills/gitnexus-refactoring/SKILL.md` |
| Tools, resources, schema reference | `.claude/skills/gitnexus-guide/SKILL.md` |
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus-cli/SKILL.md` |

<!-- gitnexus:end -->

## Environment

- Required env vars: `DATABASE_URL`, `DASHCLAW_API_KEY`, `ENCRYPTION_KEY`, `NEXTAUTH_URL`, `NEXTAUTH_SECRET` — see `.env.example` for placeholders. Never read or move real values from `.env`/`.env.local`.

@.claude/costclaw.md