System Map — the "tell them everything" dashboard

Why this matters

Born 2026-09-01 from the sleeper-mode production-readiness directive. The user said: "we've got built-in workflows, in-house skills, agents, orchestrator, everything — explain to them how it operates and improves any model that uses it." The system map IS that explanation, live. Every status is read from a real source — not a claim, not a checkbox, a live read. The walkthrough step 5 (aide-onboarding-walkthrough §5) is the first-run instance; this skill is the always-on panel.

The 8 subsystem cards (the spec)

Each card is a <system-map-card> component. Pure read: on mount, on interval (30s), and on focus, the card calls the corresponding route and renders status + last-updated + doctrine link + journal link. No state mutation, no caching, no optimistic updates. Cards:

1. In-house model — GET /api/models/status — North-Mini-Code-1.0
   • Live: status = ready / loading / error / not_loaded + model_id + port + memory_used_mb
   • Source: models/manifest.json (10 model entries, in-house flag)
   • Doctrine: aide-cipher-house-model
   • Journal: .aide/logs/arch-out.log (last 50 lines, scrollable)
2. 3 Workbenches — GET /api/workbenches — sovereign-coder/pipeline/architect
   • Live: per-workbench status = installed / available / disabled + plugins_count + skills_count + mcp_count
   • Source: workbenches/sovereign-{coder,pipeline,architect}.json (3 bundles, pluggable, per-bundle governance)
   • Doctrine: aide-bundle workflow
   • Journal: aide-bundle install <id> log
3. 197 Skills — GET /api/skills/count + per-skill status
   • Live: total + per-skill loaded / unloaded (lazy activation per aide-skill-curation)
   • Source: skills/packs/ directory (verified 2026-09-01: 197 packs)
   • Doctrine: aide-skill-curation (when to load what)
   • Journal: per-skill last_used_at (from DNA-helix X1 spine)
4. Agent loop — GET /api/agent/status
   • Live: status = online / offline / degraded + active_sessions + last_action_at + model_in_use
   • Source: node/src/services/agent-loop.mjs (the orchestrator)
   • Doctrine: aide-orchestrator-awareness + aide-offline-agent-loop
   • Journal: .aide/logs/agent-events.jsonl
5. Micro-Experts — GET /api/experts/list
   • Live: per-expert name + role + domain + holdout_agreement + manifest_sha + status = loaded / frozen / training
   • Source: harness/micro-experts.mjs + .aide/experts/ manifests (3 trained: task-router @ 0.978, diff-risk-gate @ 1.00, request-intent-classifier @ 1.00, per aide-micro-expert-collective FIRST-TRAIN RECIPE)
   • Doctrine: aide-micro-expert-collective (the collective, the FIRST-TRAIN RECIPE, the holdout-agreement floor)
   • Journal: node scripts/experts-battery.mjs last-run log
6. DNA-Helix memory — GET /api/memory/status
   • Live: X1 spine events + X2 joins + X3 retention + total_entries + oldest + newest
   • Source: harness/memory-spine.mjs + helix-join.mjs + helix-retention.mjs (commits 448b888)
   • Doctrine: aide-helix-memory (X1+X2+X3, the 3-strand helix)
   • Journal: .aide/memory/helix.jsonl
7. Veritas + Selfheal — GET /api/veritas/status + GET /api/selfheal/status
   • Live: credo version + 5 oaths status + last_evidence_scan + selfheal status = green / yellow / red + last_repair_at
   • Source: harness/veritas.mjs + scripts/selfheal.mjs (commit 54af97b)
   • Doctrine: aide-veritas-layer + aide-credo-guardrail + aide-cipher-self-healing-sop
   • Journal: .aide/logs/selfheal.log
8. BYOK + Desktop control — GET /api/byok/status + GET /api/desktop/status
   • Live: per-provider connected / invalid_key / unreachable / not_configured (no key material, only booleans per aide-cloud-handoff H2) + desktop status = enabled / disabled + active_grants
   • Source: aide-cloud-handoff H1+H2 (8 BYOK routes + 4 provider routes) + aide-p6-desktop-control Stage A bounded grants
   • Doctrine: aide-cloud-handoff + aide-provider-connect + aide-p6-desktop-control
   • Journal: egress-journal.jsonl (journaled egress, never the key)

Files to touch (when wiring)

File	Change
common/contracts/system-map.ts	NEW: zod schemas for SystemMapSnapshot (the 8-card state) + SubsystemStatus (live/offline/N/A + last_updated + doctrine_url + journal_url). All .strict().
node/src/services/system-map.mjs	NEW: createSystemMapService({workspace, fetchImpl}) — getSnapshot() calls the 9 routes in parallel (8 cards + veritas sub-route), returns the snapshot. No caching. No mutation. 5s per-route timeout.
node/src/routes/system-map.ts	NEW: GET /api/system-map/snapshot — returns the snapshot.
node/src/openapi.ts	EXTEND: register routesForSystemMap(systemMapService).
common/openapi.json	REGENERATE.
browser/src/cockpit/system-map/SystemMap.tsx	NEW: the 8-card grid + the live poll (30s interval) + the focus-refresh + the doctrine/journal links.
browser/src/cockpit/system-map/cards/*.tsx	NEW: 8 card components, one per subsystem.
browser/src/cockpit/system-map/index.ts	NEW: exports.
tests/arch/system-map-doctrine.test.ts	NEW: parses this skill + asserts the 8 card names + the 9 routes + the contract schemas.

Threat matrix

Threat	Likelihood	Blast radius	Mitigation	Detection test
Card blocks on a hung route	medium (9 routes in parallel, one hang = whole panel frozen)	system map looks broken	per-route 5s timeout via AbortController; one hung card = that card shows "degraded" + the other 7 render normally	mock a hanging route, assert 5s timeout fires + the other 7 are fine
System map leaks a BYOK key	low (routes are doc-shaped)	credential leak	the snapshot shape explicitly excludes key material; veritas secret-scan in CI; the route contract is the 8-card shape, nothing more	the snapshot never contains a key string; test asserts shape only
Stale snapshot (route returns cached data)	low (we never cache)	user sees old data	no caching by design; 30s poll + focus-refresh + manual "refresh" button	mock a route that returns stale data, assert the UI surfaces the timestamp
A subsystem card crashes the whole panel	low (1 of 8 cards)	whole panel fails to render	error boundary per card; crashed card shows "error: " + a "retry" button; the other 7 keep working	throw inside a card, assert the other 7 still render
The snapshot route becomes a DoS vector	low (no auth on local socket)	the daemon stalls	per-IP rate limit on /api/system-map/snapshot (1 req/s per workspace, drop excess with 429); 5s per-route timeout caps blast radius	hit the route 100x in 1s, assert at most 1 success + the rest 429
Doctrine link is broken (skill deleted)	low (stable)	404 in the UI	the link is aide-<name>; the route resolves to /skills/packs/<name>/SKILL.md; missing file = 404 with a "skill removed in this build" inline message	delete a skill, assert the card surfaces the message gracefully
The 30s poll drains the battery on a laptop	medium (always-on)	battery drain	poll only when the panel is visible (IntersectionObserver); stop on tab blur; resume on focus	mock a 30s tick while the panel is hidden, assert no request fired
A subsystem has no route yet (e.g. a new skill ships without wiring)	medium (rolling releases)	card shows "no data"	the card is graceful: shows "— (not yet wired in this build)" + the doctrine link	add a card that references a nonexistent route, assert the graceful fallback

Dependencies

Upstream skills (must be loaded first):

• aide-ide-research R1+R2 (load before any AIDE feature)
• aide-vscode-parity-roadmap per-phase skill spec
• aide-onboarding-walkthrough (sister skill, walkthrough step 5 IS the system map)
• aide-cipher-house-model (card 1)
• aide-skill-curation (card 3)
• aide-orchestrator-awareness + aide-offline-agent-loop (card 4)
• aide-micro-expert-collective (card 5, FIRST-TRAIN RECIPE)
• aide-helix-memory (card 6)
• aide-veritas-layer + aide-credo-guardrail (card 7)
• aide-cloud-handoff + aide-provider-connect + aide-p6-desktop-control (card 8)

Repo primitives:

• common/contracts/*.ts (zod-strict pattern)
• node/src/services/*.mjs (service factory pattern)
• node/src/routes/*.ts (route registry)
• node/src/openapi.ts (buildRoutes, single-source-of-truth hoist)
• browser/src/cockpit/*.tsx (component tree)

Pitfalls (Windows + this repo)

• Snapshot parallelism: Promise.all with AbortController per route is the only safe pattern; sequential calls blow the 5s budget on a slow disk
• Never cache: the user reads the system map to know "what is LIVE right now"; any cache makes the answer a lie
• The 8 cards are READ-ONLY: this skill must NEVER write to any .aide/ file; that would conflate the read surface with the write surface (the walkthrough IS the write surface for state)
• The 8 routes already exist for some cards (models, workbenches, experts, byok, desktop, agent, memory, veritas); the system-map service is a FAN-OUT layer, not a re-implementation
• Doctrineless cards: a card that references a skill that does not exist must surface a graceful "skill removed in this build" message, NOT a 500
• The journal link points to the LAST log file, not a live tail; the user opens it in a separate panel; do not iframe it (the iframe trick breaks back-pressure)
• 30s poll vs requestAnimationFrame: never use rAF for the poll (battery); use setInterval gated by IntersectionObserver + document.visibilityState
• The 8 cards are independent: a card's failure MUST NOT take down the panel; the error boundary is per-card

Gates (verification battery)

1. node --check browser/src/cockpit/system-map/*.tsx exit 0
2. node --test tests/arch/system-map-doctrine.test.ts PASS — asserts: (a) this skill file has 8 card names; (b) the SystemMapSnapshot zod schema is strict; (c) the 9 source routes exist (the 8 + veritas sub-route); (d) the snapshot shape never includes a key-shaped string
3. node --test tests/arch/system-map-resilience.test.ts PASS — asserts: (a) one hung card does not block the other 7; (b) a thrown error in a card shows the graceful error state; (c) the 30s poll stops when the panel is hidden
4. npm run contracts is a no-op (openapi.json regenerates byte-identical)
5. scripts/egress-audit.mjs PASS (no provider host in browser/dist)
6. Manual: open the cockpit, navigate to the system map panel, verify all 8 cards render with live status, verify the 30s poll updates a card after a manual change (e.g. start/stop the in-house model), verify the panel survives a thrown error in one card, verify battery drain is bounded (use a profiler)

Rollout (2 PRs)

PR A — Contracts + service + route + tests (smaller, runtime-only)

• common/contracts/system-map.ts (zod schemas)
• node/src/services/system-map.mjs (fan-out, parallel fetch, 5s timeouts)
• node/src/routes/system-map.ts (GET /api/system-map/snapshot)
• node/src/openapi.ts (register)
• common/openapi.json (regenerate)
• 2 arch tests (doctrine parse + resilience)
• Commit: feat(system-map): fan-out service + snapshot route (PR A of aide-system-map)

PR B — Cockpit panel + manual smoke

• browser/src/cockpit/system-map/ (the 8 card components + the grid + the 30s poll)
• Add a top-level cockpit route: /system-map
• Link from the walkthrough step 5 + from the cockpit header
• Manual smoke on a real workspace
• Commit: feat(cockpit): system map panel (PR B of aide-system-map)

References

• aide-ide-research (R1+R2: load before any AIDE feature, 3 sources per claim)
• aide-vscode-parity-roadmap (per-phase skill spec)
• aide-onboarding-walkthrough (sister skill, walkthrough step 5)
• aide-cipher-house-model (card 1)
• aide-skill-curation (card 3)
• aide-orchestrator-awareness + aide-offline-agent-loop (card 4)
• aide-micro-expert-collective (card 5, FIRST-TRAIN RECIPE)
• aide-helix-memory (card 6)
• aide-veritas-layer + aide-credo-guardrail (card 7)
• aide-cloud-handoff + aide-provider-connect + aide-p6-desktop-control (card 8)
• aide-master-roadmap (the no-phone-home law, audit line 73)
• docs/AUDIT-2026-08-31.md PART 6 (the 10-feature advantage, audit line 165-167: "Telegram + desktop control + bounded sandbox" + "Micro-Expert Collective" + "Veritas evidence gates" are the 3 of the 10 that the system map shows live)
• E:/pip_temp/competitor-onboarding-byok.md (the 7-source gap analysis that motivated this skill)