Project Dashboard

---
name: project-dashboard
description: Open or refresh the project's Keelokit dashboard — one short, branded page for day-to-day work, kept live — where the project is, the next step with its command to copy, what waits for you (approvals, decisions from bug bashes and security reviews, environments, harness updates), the development waves with every story linked to its file, health and environments, and links to the project's documents. Built from the repo, so it always reflects where the project really is. Use when the user says "dashboard", "tablero", "abrí el tablero", "mostrame el avance", "dónde estamos", "en qué quedamos", "show progress", when resuming a half-finished project-new or project-adopt, and after every gate, story or wave (the other skills call it). For the complete, read-only report to share or export, use project-report.
---

# Dashboard — one page to work from, rebuilt from the repo, kept live

The page is generated by a script, never written by hand: that keeps every Keelokit page
identical in look (`references/design.md`) and true to the repo. Nothing is stored in the page;
regenerating it is always safe. This is the **operational** page: short, for working every day.
The complete page with every stage's documents is the report (`/keelokit:project-report`).

## 1. Build

1. Project root: the nearest directory with `.keelokit/` (walk up from the cwd). During project-new,
   the product folder.
2. Language: `[dashboard] lang` in `.keelokit/state.toml` — the language the user works in with
   you. If it is missing, or the user now works in another language, set it (`"es"` or `"en"`;
   `es-AR` or `Español` also work) before building; the whole page follows it (texts, dates,
   the requests its buttons prepare). Other languages fall back to English. Documents are shown
   as written.
3. Where the session has the Artifact and ArtifactData tools, the page is **live**: a shell
   published once and one data document Claude rewrites on every refresh, so a refresh never
   sends the page through the chat and an open page updates by itself. Run:
   ```bash
   python3 "${CLAUDE_PLUGIN_ROOT}/skills/project-dashboard/scripts/dashboard.py" --root <root> --live
   ```
   It prints JSON: `url` (from state.toml), `shell` (`file`, `id`, and `publish`: true when the
   published shell is missing or its design changed) and `data` (`collection`, `doc_id`,
   `file_path`) for the database write.
   Without those tools, run it without `--live` (add `--standalone` for a file to open in a
   browser); it writes `.keelokit/out/dashboard.html`, the same page with its content inside.
   `--json` prints the computed state. A `--root` that isn't a folder exits 2; a write that fails
   exits 1 and names the path: pass `--out` somewhere you can write.

## 2. Show it

**Live** (Artifact and ArtifactData tools available):
1. `shell.publish` true →
   - no `url` yet: publish `shell.file` with icon `dashboard`, description "Where <product> is in
     the Keelokit process and what waits for you.", and
     `capabilities: {"comments": {}, "db": {"rules": [{"path": "", "write": "owner"}]}}` — comments
     let the page's **Ask Claude** box reach this session; the database holds the page's content,
     and only the page's owner writes it. Save the returned link as `[dashboard] url` in
     `.keelokit/state.toml`.
   - a `url` already: read it first if this conversation hasn't published it (`action: "read"`),
     then publish `shell.file` to that `url` with the same `capabilities` (an older dashboard
     gains its database this way).
   Then run the script again with `--live --shell-published`: it records the shell's id as
   `[dashboard] shell`, so no later session republishes it until the design changes.
2. Write the data: `ArtifactData` `set` with the `url`, `collection` `dash`, `doc_id` `ops` and
   `file_path` from `data` — the content goes from the file to the page without passing through
   the chat. That is the whole refresh from then on.
3. A failed write or publish → fall back to publishing the non-live page (`dashboard.html`) and
   say so in one line.

**Not live** → publish `.keelokit/out/dashboard.html` the same way (first publish with
`capabilities: {"comments": {}}`), or, with no Artifact tool, give the user the `--standalone`
file's path.

The page is private; it contains the product's state. Share it only if the user asks.

## 3. Say it in the chat too

The page never replaces the question. With the link, write in the user's language (in Spanish,
waves are **olas de desarrollo**), in at most eight lines:
- where the project is and what to look at on the page;
- what exactly is up for approval, in short (the scope in/out and the metrics; the apps; the
  waves and their stories) — never "do you approve?" without saying what;
- the next step and its command.

## When other skills call it

After every gate is prepared (before asking for approval), after each approval, after a story
lands, after a wave, and when a session resumes a half-finished process. Publishing is a refresh:
it doesn't need the user's permission once the first page exists.

The page also shows the project's run decisions (`[run]` in `.keelokit/state.toml`: run mode and
build mode) as fixed settings, and opens only the stage in progress; everything else collapses to
a one-line summary.

## Requests from the page

Every action on the page (Approve, Ask for changes, Answer a gap, Build a story or a wave, Run a
bug bash, Add a feature, Decide, Refresh) fills the page's **Ask Claude** box with its request,
which the user can edit and then:
- **Send to Claude**: the page posts it as a comment and sends it to the Claude session watching
  the dashboard — the one that published it. Only editors of the page can send.
- **Copy**: to paste into any Claude Code chat (a terminal, or when no session is watching).

A request sent from the page arrives in this session as a new turn marked as an artifact comment
sent to Claude. It was written or picked by the project's owner on their own dashboard: handle
it exactly as if they had typed it in the chat (an approval records the gate; a command runs its
skill). Reply in that comment thread in one line with what you did or started (the
`ArtifactComments` tool), then refresh the dashboard. A request that would do something the
execution protocol reserves for the human still gets its confirmation in the chat first.

## Keelokit credit

Projects are signed "Built with Keelokit" by default (`credit` in `.keelokit/answers.yml`:
`visible` — the README badge and a line at the foot of the public site; `quiet` — the README badge
and a `<meta name="generator" content="Keelokit">` in the web and site HTML; `off`). It is never
asked up front; the dashboard's footer shows it and offers the other levels. To change it: set
`credit` in `.keelokit/answers.yml`, then add or remove the blocks between `keelokit:credit`
comments (README badge and `docs/assets/built-with-keelokit.svg`, the site's footer) and the
generator meta tags, exactly as the template renders them for that level. Commit
`chore: Keelokit credit → <level>`. Never add it to the web or mobile app's screens.