wellwelwel/lagune / .claude/skills/dashboard
dashboard
VerifiedAuthoritative reference for the Lagune dashboard, a live view of a project's .lagune/ chain with a locked-down local action surface. Use before changing anything under src/dashboard/ or src/types/dashboard/.
Lagune dashboard
A live view of a project's .lagune/ chain: charter, findings, hardening, verification, and the catalog of specializations. It parses the real memory artifacts, tracking map, and project catalog on every request and pushes a browser reload whenever anything under .lagune/ changes. It has no notion of installation: it shows whatever artifacts .lagune/ holds, with an empty state while there are none, and reads nothing the skills CLI writes. Viewing is read-only. The one write path is the Settings action surface, which records the project's categories and what its hooks leave out, in-process behind the guards described under Actions.
Authored in strict TypeScript with Node APIs. It ships as a self-contained static client plus a zero-dependency server, both bundled into lib/ at build time. src/ is never published.
The product mission and workflow philosophy live in CLAUDE.md. The code conventions live in the engineering skill, the architecture decisions in the architecture skill, the design-engineering principles in the ui skill, and how to verify rendered output in the cdp skill.
Consistency
The client follows one visual system. Same-styled elements never carry their own local variants, and when two of them disagree on a value, standardize on the smallest one already in use. New kinds of visual consistency belong here as subsections, never as new top-level sections.
Spacing
- One card inset: content inside any surface card sits
p-4.5(18px) from every edge, all four sides. The metric cards, finding cards, charter cards, rail blocks, and detail cards all share it. - List cards put every padding on the row: the container is only
overflow-hidden rounded-lg bg-surface shadow-card, with no padding of its own. Each row ownspx-4.5 py-3, and the first and last rows close the card edge withfirst:pt-4.5andlast:pb-4.5, all fromROW_EDGES(in the findings table, the header is the first row:pt-4.5 pb-3). This keeps row hover and dividers spanning the full card width, and keeps every spacing readable on the element itself. Never assemble an inset from a parent padding plus a child padding: a hidden contribution on the parent is exactly the inconsistency this rule exists to prevent. - Fixed rhythm: rows use
py-3withgap-3, card grids usegap-4, sections end withmb-6, and section heads sitmb-3above their content.
Tiles and icons
Icon tiles in rows are size-8.5 with text-[1.05rem] glyphs, circular arrow affordances are size-8.5 rounded-full text-[0.95rem], and large tiles are size-11 rounded-md text-[1.25rem].
Typography
Micro labels (uppercase group titles, table headers, card labels) come from MICRO_LABEL in client/utils/tailwind-classes.ts, badges from BADGE, group heads from GROUP_HEAD, and hover labels from TOOLTIP, shown by the nearest group/tip ancestor. Reuse the token instead of retyping a near-copy. Card titles are text-[0.9rem] font-bold tracking-[-0.01em], with extrabold reserved for page and section headings.
Run
End users run it against their own project, with no install:
npx lagune dashboard
That serves the built client and opens the browser on the workspace's .lagune/.
Local development in this repo:
npm run dashboard:dev # Vite dev server with HMR, proxying data to the node server
npm run dashboard:build # build the client into lib/dashboard
npm run typecheck
The server prints its URL. By default it binds port 0, so the OS hands back a free port that never conflicts (set PORT to pin one, where it climbs on conflict). In npm run dashboard:dev, the browser opens on the Vite URL: client edits hot-swap modules in place (state survives), while the node server, pinned on port 3001 behind Vite's proxy, keeps watching .lagune/ and reloads the page on any edit there. Nothing is written to disk in dev, Vite serves the client from memory.
How it fits together
- Server (
server/): anode:httpserver.start.tsis the reusable entry: it resolves the paths, listens (port0by default, climbing only whenPORTpins a busy one), opens the browser, and stays up untilSIGINT. ThedashboardCLI command and the dev entry (tools/dashboard-serve.ts) both call it.data/parses the Markdown memories,tracking.json, the project's categories and its own specializations (.lagune/configs.jsonand.lagune/catalog/) into one typedDashboardDataobject, served atGET /api/data. Understanding markdown is deliberately not our code: themarkdown/module asksmdast-util-from-markdown(micromark, the same CommonMark engine behind the website's Docusaurus, bundled at build time so the published package still needs zero runtime installs) which lines are code and which spans are HTML comments. Code of any kind (fenced, indented, diffs, mermaid diagrams) is never structure, and comments are stripped before any parsing without ever touching code or inline code. Only the domain mapping is manual: which heading opens a section, which- **Field:**line is a field, what goes where. An h1 ends any section, and h4 to h6 stay inside the block they annotate, out of the extracted prose. Field lines are read by a staged grammar (fieldValue) whose canonical shape is the template's and whose fallbacks absorb common LLM punctuation drift: any list marker (-,*,+), optional bold (**or__), case-insensitive field name, then a required separator (colon canonically, em or en dash, or a spaced hyphen). The separator is what keeps prose from matching, and the value is never rewritten. Never hand-roll markdown lexing here (fence pairing, comment masking): extend the mapping over the tree instead.live-reload.tswatches.lagune/, streaming a reload overGET /events(SSE).static-files.tsserves the built client, guarded against path traversal.- The server reads
.lagune/from the invoking working directory and the client from the packaged location, never fromsrc/. - Actions (
actions.ts,guards.ts,session.ts): the Settings route records the project's categories throughPOST /api/actions/categories, by the same rules asaddandremove, and thecheckersblock throughPOST /api/actions/checkers, by the same rules the hooks read it with, both in-process via the engine's own modules. Every change must preserve these invariants:- No shell, eval, or subprocess, ever. Nothing from a request reaches one. Each action writes only its own field of
.lagune/configs.json, never an arbitrary path or content. - Fail-closed payloads. Dispatch is a code-defined
Mapkeyed by pathname, never a lookup on a request value. Any key beyond the action's declared fields is rejected (so__proto__,constructor,prototypenever pass). Names pass only by exact membership against the engine's own categories, checkers, and settings, paths and patterns only through the engine's own pattern reader, and every other value by plain types (no regex), all rebuilt into a fresh object, never spread or merged. Acheckersblock the hooks already refuse is never replaced: it is fixed in the file, never overwritten from the browser. Hostfirst, every route. A request must carry a loopbackHost(or a dev host fromtools/dashboard-serve.ts), checked before anything else, so a rebound domain reaches nothing.- Cross-origin locked out.
GET /api/session,GET /api/data, and every action reject aSec-Fetch-Sitethat is present and notsame-origin, so a cross-origin page is never handed the token or data (page script cannot forge that header). No response carries a CORS header andOPTIONSis never answered, so preflights fail closed. - Token. A 256-bit value regenerated per start, written to a
0600file in the OS temp dir (session-<pid>.token) so it is never world-readable at rest. Actions additionally require it inx-lagune-token(compared withtimingSafeEqual) and an exact loopback or devOrigin. - Bounded input, serialized writes. Bodies are
application/json, ≤16KB,JSON.parsed, and cut off by a 5s read timeout so a slow-loris body cannot pin the single-flight lock. One action runs at a time (409 when busy). - Hardened responses. Every response sends
nosniff, and HTML addsframe-ancestors 'none'andx-frame-options: DENYagainst clickjacking. Errors are generic to the browser, detailed only in the terminal with newlines neutralized. The one engine message the browser shows is the refusal of acheckersblock, so Settings can say what the hooks stop on. Success needs no refetch: the.lagune/write triggers the SSE reload. - Residual. The boundary is loopback plus token, not UID isolation: on loopback TCP another local process can still reach the surface. The dashboard targets a single-user workstation. Closing this would need a Unix-domain socket (
0600), deferred until a multi-user need is real.
- No shell, eval, or subprocess, ever. Nothing from a request reaches one. Each action writes only its own field of
- Client (
client/): a Preact single-page app.components/androutes/are Preact components;main.tsxowns the render root andapp.tsxthe routing, with signals for state, search, filters, and theme. A route with several parts keeps them under acomponents/<route>/folder (seecomponents/settings/). Blocks that display artifact prose render throughcomponents/admonition.tsx, the dashboard's equivalent of the website's docs admonitions:note,info,tip,warning, anddanger. Each kind sets one accent (--adm) and theadmonitionutility instyles/index.cssderives every internal color from it (surface, border, heading, body, inline code, text selection), the same mechanism as the website'sdocs.css. Reuse it, picking the kind by what the text means, instead of hand-tinting a card.styles/is a token-driven design system (light and dark), imported bymain.tsxand bundled by the Tailwind Vite plugin. Typography matches the website's docs and loads from Google Fonts inindex.html(nothing shipped in the package). The layout must stay responsive down to a minimum resolution of 1024x768px.- Below 1280px, prefer vertical alignments and single-column layouts. At 1280px and above, prefer grid layouts and horizontal alignments.
- Shared (
shared/): runtime metadata both sides import (specialization labels, descriptions, and category badges, the agent themes of the prompt previews, severity ordering). It derives from the core's own data, never duplicates it: the categories come fromsrc/categories/categories.tsand the specialization-to-category mapping fromsrc/catalog/builtin.ts. Those core modules, and everything here, stay import-safe for the browser (pure data, type-only imports): the website imports them through its bridge, so a label, a logo, or a theme is written once for both surfaces. The hooks' rules (src/core/checker-rules.ts) stay import-safe the same way, so the Settings route reads a pattern and resolves each hook's settings exactly as the engine does, never through a copy. - Types: the shared data contract and the server/client-internal types live in
src/types/dashboard/, the single source of truth both sides import. - Build (
src/dashboard/vite.config.ts): Vite with@preact/preset-viteand@tailwindcss/vite, entered throughclient/index.html, always emitting tolib/dashboardwith hashed bundle names.client/public/assets/(icons and images, referenced as/assets/...) is copied verbatim. It is the single home of every logo, and the website serves it as well. There is no dev output directory,vite devserves everything from memory.
Security context
Read all, one at a time, with node lib/bin/index.js read catalog <name> from the repository root after a build: javascript, network, http-request, access-control, crypto, interpreter, path, browser, and regex.
Routes
#/ overview · #/findings and #/findings/:id · #/sidequests · #/charter · #/catalog · #/history · #/settings (?tab=hooks opens the hooks).
Add ?theme=dark to the URL to force a theme.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |