claude-code-kanban 7.5.0 → 7.6.1

package/plugin/plugins/claude-code-kanban/hooks/show.ts

@@ -0,0 +1,120 @@
+import type { EngineInterface, Register } from 'claude-code'
+import { cckRoot } from './context'
+
+export const TOOL = 'mcp__claude-code-kanban__show'
+export const SKILL_LINE = /^\s*-\s*claude-code-kanban:show(?=:|\s*$)/
+
+type ShowInput = { title: string; key?: string; kind?: 'markdown' | 'html'; file?: string }
+type Shown = { title: string; key?: string | null; index: number; count: number; path?: string | null }
+
+export function boardPort(cckUrl: string) {
+  return /^[a-z]+:\/\/[^/]*:(\d+)(?:\/|$)/i.exec(cckUrl)?.[1]
+}
+
+export function shownText({ title, key, index, count, path }: Shown, claim = false) {
+  const at = `"${title}" (${key ? `${key}, ` : ''}${index}/${count})`
+  return claim ? `Card ${at} is ready. Write it to ${path}; the card refreshes on each save.` : `Shown ${at}`
+}
+
+export function dropSkillLine(listing: string) {
+  return listing
+    .split('\n')
+    .filter(l => !SKILL_LINE.test(l))
+    .join('\n')
+}
+
+let cck: Promise<string> | undefined
+
+function cckDir($: EngineInterface) {
+  cck ??= Promise.all([$.env.get('CLAUDE_CONFIG_DIR'), $.env.get('HOME'), $.env.get('USERPROFILE')]).then(
+    ([configDir, home, userProfile]) => cckRoot(configDir, home, userProfile),
+  )
+  return cck
+}
+
+let target: Promise<{ url: string; terminalId: string } | undefined> | undefined
+
+// Both vars come from ptyEnv, so only a session started in cck's embedded terminal has them.
+function terminal($: EngineInterface) {
+  target ??= Promise.all([$.env.get('CCK_URL'), $.env.get('CCK_TERMINAL_ID')]).then(([url, terminalId]) =>
+    url && terminalId ? { url: url.replace(/\/+$/, ''), terminalId } : undefined,
+  )
+  return target
+}
+
+// Read on every post, the way cli.js reads it for dispatch: a restarted board writes a new token.
+async function terminalToken($: EngineInterface, url: string) {
+  const port = boardPort(url)
+  if (!port) return undefined
+  try {
+    const { token } = JSON.parse(await $.fs.read(`${await cckDir($)}/terminal-tokens/${port}.json`))
+    return typeof token === 'string' && token ? token : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function errorText(status: number, text: string) {
+  try {
+    const { error } = JSON.parse(text)
+    if (typeof error === 'string' && error) return error
+  } catch {}
+  return `cck answered HTTP ${status}`
+}
+
+async function post($: EngineInterface, input: ShowInput) {
+  const t = await terminal($)
+  if (!t) return { deny: 'The overlay needs a Claude Code session started in the cck terminal.' }
+  const token = await terminalToken($, t.url)
+  if (!token) return { deny: `No terminal token for the cck server at ${t.url}. It must run with the terminal enabled.` }
+  const { title, key, kind, file } = input
+  const body = JSON.stringify({ sessionId: await $.session.id(), title, key, kind, file })
+  let res: Awaited<ReturnType<EngineInterface['http']['fetch']>>
+  try {
+    res = await $.http.fetch(`${t.url}/api/terminals/${encodeURIComponent(t.terminalId)}/show`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-terminal-token': token },
+      body,
+    })
+  } catch (err) {
+    return { deny: `Cannot reach cck at ${t.url}: ${err instanceof Error ? err.message : String(err)}` }
+  }
+  if (!res.ok) return { deny: errorText(res.status, res.text) }
+  return { result: shownText(JSON.parse(res.text) as Shown, file == null) }
+}
+
+// A -p run is detached from the terminal, so only an interactive session gets the tool.
+export const register: Register = on => {
+  on('session.start', { isInteractive: true }, async ($, e, next) => {
+    if (await terminal($)) {
+      await $.tool.register({
+        name: 'show',
+        description:
+          'Show a card in the cck overlay above this terminal. Post one when the user asks you to show, draw or visualize something, or when your answer is a comparison of 4 or more rows, a flow, or numbers over time. Pick the form that makes the point best: a table, chart, diagram, mockup, small widget or a mix. Give each card a key that names what it shows (for example latency-chart), and post again with that key to update the card in place instead of adding a new one. Without file, the tool answers with a path: write the card there with Write, and change it with Edit; the card refreshes on each save. Pass file to show a file that already exists. To explain code with a call stack or a tree, load the claude-code-kanban:show skill first for the notation. The user sees the rendered card and knows you do not; in your reply, say what the card shows, and take the render as given.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            title: { type: 'string', description: 'Card title' },
+            kind: {
+              type: 'string',
+              enum: ['markdown', 'html'],
+              description:
+                'markdown (default): mermaid, diff and code fences render. html: a body fragment; load the claude-code-kanban:show skill first for the HTML contract',
+            },
+            file: { type: 'string', description: 'Absolute path of an existing markdown, HTML, image or text file' },
+            key: { type: 'string', description: 'Card name: the same key replaces the card in place and keeps its file' },
+          },
+          required: ['title'],
+        },
+      })
+    }
+    return next(e)
+  })
+
+  on('tool.call', { tool: TOOL }, async ($, e) => post($, e as unknown as ShowInput))
+
+  on('prompt.attachment', { type: 'skill_listing' }, async ($, e, next) => {
+    if (await terminal($)) return next(e)
+    return next({ ...e, text: dropSkillLine(e.text) })
+  })
+}

package/plugin/plugins/claude-code-kanban/skills/dispatch/SKILL.md

@@ -22,6 +22,8 @@ End every spec with the reply line, because you usually need the result to conti
 When you are done, or cannot finish, send the result to <your peer name> with the SendMessage tool, then stop.
 ```
 
+A resumed session gets a new peer name, and the reply line still names the old one. After this session resumes, send each worker in `dispatch list` your new name with `SendMessage`.
+
 `--handoff` is a skill argument that drops the reply line: the session owns the task, and the user follows it on the board. Keep it out of the `dispatch start` command.
 
 ## Track on the board (optional)

package/plugin/plugins/claude-code-kanban/skills/kanban/SKILL.md

@@ -28,6 +28,8 @@ This session id is `${CLAUDE_SESSION_ID}`. `--session` defaults to it through `$
 
 With no argument, run nothing on the board: show the user the table above.
 
+An argument with no command name works on this session and its files. `open` and `preview` both mean `doc preview`, and with no target they mean the file this conversation is about. `open` focuses a session only as `session open`.
+
 ## Keep the board still
 
 The user works in other windows while you run, so pick the quiet command. `doc link` and `pane add` add an entry the user opens when ready. `doc preview` is the one command that opens a modal on the user's screen: use it when the user asks to see something now.

package/plugin/plugins/claude-code-kanban/skills/show/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: show
+description: Show card guide for the cck overlay. Use before a show call that posts HTML (a chart, mockup or diagram), a mermaid diagram, or explains code (a call stack or tree).
+argument-hint: '[explain|diagram|chart|mockup] [what to show]'
+---
+
+# Show cards
+
+The `mcp__claude-code-kanban__show` tool exists only in a Claude Code session started in cck's terminal. Without it, tell the user that and stop.
+
+An argument names a card kind from [Card kinds](#card-kinds) and what to show: read that kind's guide and post the card. With no kind, pick the one that makes the point best; with no topic, show the subject of this conversation.
+
+## HTML contract
+
+This applies to the `.html` file that a `kind: "html"` post names.
+
+- Write a body fragment: no `<!doctype>`, `<html>`, `<head>` or `<body>`. The overlay wraps it in a sandboxed document. `<style>` and `<script>` work; the script has no access to the page around it.
+- The card is about 360 to 640 px wide and sizes its height to the content. Keep the content in normal flow, without `position: fixed` or `100vh`.
+- One chart or diagram per card, under an `<h2>` that says what to see. Keep it flat: solid fills and 1 px lines.
+- Open links with `<a href="https://...">`; the overlay opens them in a new browser tab.
+- Take every color and font from these variables, so the card follows the user's light or dark theme:
+
+| Variable | Use |
+|---|---|
+| `--color-bg`, `--color-bg-subtle` | Page and panel background |
+| `--color-text`, `--color-text-muted` | Body text, secondary text |
+| `--color-border` | Lines, box outlines |
+| `--color-accent` | The one thing to look at |
+| `--color-info`, `--color-success`, `--color-warning`, `--color-danger` | Status |
+| `--color-series-1` … `--color-series-8` | Chart series, in order |
+| `--color-ramp-1` … `--color-ramp-5` | One-hue magnitude, least to most |
+| `--font-sans`, `--font-mono` | Fonts |
+
+## Card kinds
+
+Any HTML that helps the user see the point is a good card: a comparison table, a checklist, a before and after, a diff, a small interactive widget, a mix of these. The HTML contract above is all it needs. Four kinds have their own guide; read it before you write that kind:
+
+- Chart, stat tile or meter: [references/chart.md](references/chart.md)
+- Mockup of a screen, dialog or form: [references/mockup.md](references/mockup.md)
+- Diagram in SVG of a system, flow, states or layers: [references/diagram.md](references/diagram.md)
+- Explain code (call stack, pseudocode, component or file tree, or a diff of one), in markdown: [references/explain.md](references/explain.md)
+
+## Mermaid
+
+The card is narrow. Use `flowchart TD`, short node labels and `subgraph` blocks, and split a big system map into several cards.

package/plugin/plugins/claude-code-kanban/skills/show/references/NOTICE.md

@@ -0,0 +1,27 @@
+# Notice
+
+`diagram.md` and the files in `diagram/` are adapted from the diagram-design skill (https://github.com/cathrynlavery/diagram-design), under the MIT License:
+
+```text
+MIT License
+
+Copyright (c) 2025 Cathryn Lavery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/plugin/plugins/claude-code-kanban/skills/show/references/chart.md

@@ -0,0 +1,58 @@
+# Chart card
+
+A chart in an HTML card. The card's CSP allows inline script only, so no chart library loads: draw bars with CSS or SVG, and lines with SVG.
+
+## Choose the form before the colors
+
+The data's job picks the form, and often the right form is not a chart.
+
+| The data is | Post | Not |
+|---|---|---|
+| One current value, maybe with its change | A stat tile | A bar chart with one bar |
+| 2 to 4 headline numbers | A row of stat tiles | A grouped bar chart |
+| One ratio against a limit | A meter: a track with a fill | A pie with 2 slices |
+
+When it is a chart, the reader's job picks the type:
+
+| The reader must | Type | Color |
+|---|---|---|
+| Compare sizes | Horizontal bars, sorted | One color, `--color-series-1` |
+| See a trend over time | A line; an area for one series | One color |
+| Tell series apart | Grouped or stacked bars, several lines | Series tokens in order |
+| See that one item stands out | Bars or lines with one in `--color-accent`, the rest in `--color-border` | Accent and gray |
+| See above or below a baseline | Bars that grow both ways from a zero line | `--color-success` and `--color-danger` only when up is good |
+| See a magnitude across a grid | A heatmap | The ramp |
+| See part of a whole | One stacked bar; at most 6 parts | Series tokens |
+
+Horizontal bars suit the card best: long labels fit at the left and the bars use the width. Close values go in bars, because a pie hides small differences. One y-axis per chart: for two scales, post two charts or index both series to 100.
+
+## Series
+
+- Use the series tokens in order: the order keeps neighbors apart for color-blind readers.
+- 1 to 3 series: color with direct labels is enough.
+- 4 to 6: a legend, and label the lines at their ends.
+- 7 or 8: the most the tokens allow. Past that, fold the smallest into "Other" or post a table. Never make up a ninth color.
+- A series keeps its color when you filter or sort: color follows the item, not its rank.
+- The ramp is for ordered values. Groups with no order (teams, endpoints) take series colors.
+- Labels and values use `--color-text` or `--color-text-muted`; a small swatch or line key beside the text carries the series color.
+
+## Marks
+
+- Bars at most 24 px thick, with a 2 px gap between neighbors, rounded 4 px at the value end and square at the baseline. All bars grow from one baseline.
+- Lines 2 px, round joins. End dots at least 8 px wide.
+- An area fill is the series color at about 10% opacity.
+- Gridlines and axes are solid 1 px `--color-border`, never dashed. Fewer is better: direct labels first, gridlines next.
+- Separate touching marks with a gap in the background color, not with a stroke.
+
+## Labels
+
+- The `<h2>` says what to see ("p95 latency doubled after the deploy"), not what is plotted.
+- Label the few values that matter: the last point, the extreme, the item the card is about. Put the value at the bar end or the line end.
+- Round axis ticks (0, 1,000, 2,000) and use thousands separators.
+- A label that does not fit inside a bar goes outside its end. Never clip it.
+- Stat tile: a short label in sentence case, the value in sans, semibold, compact (`12.9K`, `$4.2M`), and an optional change against a named period (`+8% vs last week`), green or red only by whether up is good.
+- `font-variant-numeric: tabular-nums` only for numbers in a column; a large single value uses normal figures.
+
+## Fit the card
+
+Size bars in `%`, or give SVG a `viewBox` and `width:100%`, so the chart scales with the card.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/architecture.md

@@ -0,0 +1,18 @@
+# Architecture
+
+For components and how they connect: a system overview, an integration map, trust zones.
+
+- Group by tier, top to bottom: clients, services, stores.
+- A zone (tier, network, trust boundary) is a rect with `rx` 8, `--color-bg-subtle` fill and a `--color-border` hairline, drawn first. Its name is a small mono label in its top left corner with 16 units of space above the first node. At most 3 zones; a dashed outline marks a trust boundary.
+- 1 or 2 focal nodes: the main entry point or the main store.
+- A two-bend path from (x1,y1) down to (x2,y2), with `m` halfway down:
+
+```svg
+<path class="edge" d="M x1,y1 V m-8 Q x1,m x1+8,m H x2-8 Q x2,m x2,m+8 V y2" marker-end="url(#d1-arrow)"/>
+```
+
+  Flip the signs for the other directions. A line between nodes on one axis is a straight `V` or `H`.
+- A vertical connection leaves the bottom edge and enters the top edge, not the sides.
+- Where two lines must cross, the less important one hops over with a small arc: `H cx-8 a 8,8 0 0,1 16,0 H x2`.
+- A call to an outside API may use `--color-info` for its line, when the diagram mixes internal and external calls.
+- No two-headed arrows when one direction is the obvious one.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/er.md

@@ -0,0 +1,10 @@
+# ER
+
+For a data model: tables, API resources, domain entities. A model with plain relationships is cheaper as a mermaid `erDiagram`; draw SVG when you need to group entities or mark the central one.
+
+- At most 6 entities on a card; 2 columns of entities, relations between them.
+- An entity is a box in two parts: a header with its name in sans on `--color-bg-subtle`, and a body with one field per line in mono. Mark the key `#id`, a foreign key `→ user_id`. Show only the fields the point needs.
+- Boxes take the height of their fields; do not pad them to match.
+- Relations are lines with the cardinality near each end in mono, 8 to 12 units off the box: `1`, `N`, `0..1`, `1..*`. Use one notation for both ends.
+- An optional verb (`owns`, `belongs to`) sits on the middle of the line on a mask.
+- Accent on the aggregate root or the entity the card is about.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/flow.md

@@ -0,0 +1,13 @@
+# Flow
+
+For decision logic, triage, routing: "if this, then that".
+
+- Node shapes:
+  - start and end: a pill, `rx` 16
+  - step: a rect, `rx` 6
+  - decision: a diamond with at most 3 exits; more exits means nested decisions
+  - merge: a filled dot, `r` 4, where branches meet again
+- Label every edge out of a decision (`yes`, `no`, `timeout`). By habit "yes" goes down and "no" goes right, but the label is what counts.
+- Accent goes on the happy path or on the one decision that matters most, not on every decision.
+- A long chain of steps is a numbered list.
+- On a narrow card keep side branches one column wide and return them to the main column.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/layers.md

@@ -0,0 +1,10 @@
+# Layers
+
+For stacked levels: a tech stack, a cascade, a memory hierarchy, a context hierarchy. This is the type that suits the card best: it is tall by nature.
+
+- 3 to 6 full-width bands of the same height (48 to 64 units), stacked with no gap and split by hairlines.
+- Each band, left to right: an index tag in mono (`L3`, `APP`), the layer name in sans, a short note in muted mono at the right edge. On a 360 px card drop the note into a second line under the name.
+- Fill: all `--color-bg` with hairlines, or alternate `--color-bg` and `--color-bg-subtle`. Pick one.
+- Show direction once, outside the stack: a small arrow with a mono label (`requests ↓`).
+- Accent on one layer: the bottleneck or the one under discussion.
+- If the levels are not a hierarchy, it is an architecture or a swimlane.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/sequence.md

@@ -0,0 +1,19 @@
+# Sequence
+
+For requests and replies between actors over time: an API call path, an auth flow, an incident replay.
+
+- Actors are boxes in one row at the top; at most 4 on a card (about 100 units apart in a 440 viewBox). A fifth actor makes the labels too small.
+- Lifelines: dashed vertical lines in `--color-text-muted` under each actor. Time runs down.
+- Messages are horizontal arrows, labeled above the line:
+
+| Kind | Line | Head |
+|---|---|---|
+| Call | solid, muted | filled |
+| Return | dashed, muted | filled |
+| Async, fire and forget | dashed, muted | open (a `polyline`, no fill) |
+| The one result that matters | solid, accent | filled, accent |
+
+- A self-call is a short U loop on the same lifeline, label on its right.
+- An activation bar (8 units wide, `--color-bg-subtle`, hairline) shows who holds control, only when that matters.
+- A branch goes in one frame: a rect over the lifelines it spans, with a tab at its top left (`ALT`, `OPT`, `LOOP`) in mono and the guard (`[token valid]`) under it. `ALT` splits its regions with a dashed line. At most one frame, no nesting.
+- At most 12 messages. Past that, post the overview and put the detail on a second card.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/state.md

@@ -0,0 +1,12 @@
+# State
+
+For finite states: order status, connection lifecycle, job status, a wizard.
+
+- States are rects with `rx` 8, name in sans.
+- Start: a filled dot, `r` 6. End: a ring, `r` 8, around a filled dot, `r` 5.
+- Every transition has a label in mono: `event [guard] / action`, each part only when it says something.
+- A self-transition loops over the top of its state.
+- Run top to bottom; reorder states before you let transitions cross.
+- A transition from every state (timeout, cancel) is one note under the diagram, `* → Failed on timeout`, not an arrow from each state.
+- Accent on the state the reader should notice, usually the failure state or the done state.
+- More transitions than twice the states means two machines: post two cards.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/swimlane.md

@@ -0,0 +1,10 @@
+# Swimlane
+
+For a process that passes between people, teams or systems.
+
+- On a card, lanes are columns, one per actor, at most 4, with time running down. Rows of lanes run sideways and do not fit.
+- Each lane has a mono label at its top. Hairlines split the lanes.
+- A step is a rect in the lane of the actor that does it, never across two lanes.
+- Handoffs (lines that cross a lane border) are the edges that matter. Accent the one that adds the most delay or coupling.
+- A lane with one step is fine; do not pad lanes to match.
+- Order the steps so the flow goes mostly down; a line that zigzags between lanes means the order is wrong.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/timeline.md

@@ -0,0 +1,9 @@
+# Timeline
+
+For events in time: releases, milestones, an incident, a roadmap.
+
+- On a card the axis runs down: a hairline at the left, dates in mono to its left, events to its right. A horizontal axis fits only 4 or 5 short events.
+- An event is a filled dot, `r` 4, on the axis, with its label beside it. A milestone is an accent dot, `r` 6, with a bold label.
+- Space events by real time. If one stretch is crowded and another empty, break the axis with a visible gap mark rather than fake even spacing.
+- Name the unit of the axis (days, sprints, versions).
+- An incident timeline can color its dots by status (`--color-danger` for the outage start, `--color-success` for the recovery), and nothing else.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram/tree.md

@@ -0,0 +1,10 @@
+# Tree
+
+For parent and children: a dependency tree, a taxonomy, a breakdown, an ownership chart.
+
+- Root at the top. At most 4 levels and 4 children per level on a card; past that, split it, or turn the tree on its side as an indented list with elbow lines on the left, which fits a narrow card well.
+- Nodes are rects with `rx` 6, 32 to 48 units tall, at most two widths.
+- Lines are elbows: a short drop from the parent, a horizontal bus over the children, a short drop into each child's top edge. Hairline, muted.
+- A leaf can have a thinner stroke, or let its position say it.
+- Accent on one node: the root or one key leaf, not both.
+- No level skipped: a parent links only to its own children.

package/plugin/plugins/claude-code-kanban/skills/show/references/diagram.md

@@ -0,0 +1,87 @@
+# Diagram card
+
+An SVG diagram in an HTML card, for a picture that mermaid lays out badly: layers, zones, lanes, a timeline, or one node that must stand out. For a plain flowchart, sequence or ER sketch, a mermaid block in a markdown card is cheaper; use this only when layout or emphasis carries the meaning.
+
+## Decide first
+
+- Would a table or three sentences say the same? Then write those.
+- Pick one type from the table, then read its file before you draw.
+- Delete before you add. Every node is a distinct idea: two nodes that always travel together are one. Every line carries information: if the layout already shows the link, drop the line.
+- More than 9 nodes is two cards: an overview and a detail.
+
+| Showing | Type | File |
+|---|---|---|
+| Decision logic with branches | Flow | `diagram/flow.md` |
+| Messages between actors over time | Sequence | `diagram/sequence.md` |
+| States and the events that move between them | State | `diagram/state.md` |
+| Stacked levels of abstraction | Layers | `diagram/layers.md` |
+| Components, connections, trust zones | Architecture | `diagram/architecture.md` |
+| Parent and children | Tree | `diagram/tree.md` |
+| A process with handoffs between teams | Swimlane | `diagram/swimlane.md` |
+| Events in time | Timeline | `diagram/timeline.md` |
+| Entities, fields, relationships | ER | `diagram/er.md` |
+
+Bars, lines, scatter and Gantt are charts: read `chart.md`.
+
+## Fit the card
+
+Content wider than the card scrolls sideways, which reads badly; content taller than the card scrolls down, which reads fine.
+
+- Draw for a narrow card: viewBox width 400 to 480, top to bottom. A wide left-to-right map turns its 12 px labels into 8 px at the default size.
+- Scale with the card: `<svg viewBox="0 0 440 H" style="width:100%;max-width:660px;height:auto">`. Never a fixed `width`.
+- Text at least 12 viewBox units, so it stays readable at 360 px.
+- The title goes in the `<h2>` above the SVG, not inside it.
+
+## Colors
+
+Presentation attributes do not take `var()`, so color the SVG through classes in a `<style>` block. Then the diagram follows the user's theme switch with no script.
+
+| Role | Token |
+|---|---|
+| Canvas, node mask | `--color-bg` |
+| Container, zone fill | `--color-bg-subtle` |
+| Node name, main stroke | `--color-text` |
+| Sublabel, default arrow, lifeline | `--color-text-muted` |
+| Hairline, zone outline | `--color-border` |
+| Focal node or path, 1 or 2 per diagram | `--color-accent` |
+| Status meaning only | `--color-info`, `--color-success`, `--color-warning`, `--color-danger` |
+
+Make tints with `color-mix(in srgb, var(--color-accent) 12%, var(--color-bg))`, not opacity, so lines behind a node do not show through.
+
+```html
+<style>
+  .d text { font: 12px var(--font-sans); fill: var(--color-text); }
+  .d .sub { font: 12px var(--font-mono); fill: var(--color-text-muted); }
+  .d .node { fill: var(--color-bg); stroke: var(--color-text); stroke-width: 1; }
+  .d .store { fill: var(--color-bg-subtle); stroke: var(--color-text-muted); }
+  .d .focal { fill: color-mix(in srgb, var(--color-accent) 12%, var(--color-bg)); stroke: var(--color-accent); }
+  .d .edge { fill: none; stroke: var(--color-text-muted); stroke-width: 1.2; }
+  .d .edge.hot { stroke: var(--color-accent); }
+  .d .dash { stroke-dasharray: 4 3; }
+  .d .head { fill: var(--color-text-muted); }
+  .d .label-mask { fill: var(--color-bg); }
+</style>
+<svg class="d" viewBox="0 0 440 300" style="width:100%;max-width:660px;height:auto" role="img" aria-labelledby="d1-t">
+  <title id="d1-t">Order service writes to the queue</title>
+  <defs>
+    <marker id="d1-arrow" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
+      <polygon class="head" points="0 0, 8 3, 0 6" />
+    </marker>
+  </defs>
+  <!-- edges first, then nodes -->
+</svg>
+```
+
+Give each marker and title an id with a per-card prefix (`d1-`), so two SVGs in one card do not clash.
+
+## Shapes and lines
+
+- Node: `rx` 6, name in `--font-sans`, a technical sublabel (port, path, type) in `--font-mono`. Names in mono read as noise.
+- Node kinds by fill and stroke, not by color: plain step `.node`, store `.store`, external a thin stroke, optional or async a dashed stroke, focal `.focal`.
+- Lines go straight or bend at right angles with a rounded corner (radius 8), also between nodes that are not on one axis.
+- Draw edges before nodes, so nodes cover the line ends.
+- An edge label sits horizontal on an opaque `.label-mask` rect, 6 to 10 units off its line, at most 14 characters.
+- Each line has its own path and attach point, 12 units from the next.
+- Corner radius at most 8.
+- A legend, when the diagram needs one, is a row below the diagram, not inside it.
+- Coordinates and sizes on a 4-unit grid keep the spacing even.

package/plugin/plugins/claude-code-kanban/skills/show/references/explain.md

@@ -0,0 +1,98 @@
+# Explain card
+
+A markdown card that shows how code works: what calls what, what a function decides, where things live, or what a change moves. Post `kind: "markdown"`; the board renders the fences below.
+
+## Make one point
+
+Each card makes one point about the code under discussion. Write the point as a sentence or two, then the view that proves it. Pick the smallest view that makes the point clear; add a second view to the card only when it shows what the first cannot.
+
+| Showing | View | Fence |
+|---|---|---|
+| Runtime flow: who calls whom | Call stack | `callstack` |
+| What a function decides | Pseudocode | `text` |
+| UI structure, state and module boundaries | Component tree | `tsx` |
+| Which file owns what | File tree | `text` |
+| Messages between parts over time | Sequence | `mermaid` |
+| What a change adds, removes or moves | A diff of the view above | see [Diff](#diff) |
+
+Keep only the calls, files, props and states the point needs, with real names from the code. Give the card a `key` that names the topic; post a follow-up view, such as the diff after the fix, with the same key so it replaces the card.
+
+## Call stack
+
+The board draws the tree lines, links, focus and folds from this notation:
+
+```callstack
+ handleCheckout                  src/routes/checkout.ts:24
+   validateCart                  throws on an empty cart
+   placeOrder *                  src/orders/place.ts:40
+     chargeCard                  src/payments/charge.ts:31
+       ~ 2 SDK frames
+         PaymentsClient.charge   node_modules/pay-sdk/client.js:112
+         HttpClient.request      node_modules/pay-sdk/http.js:58
++    sendReceipt                 src/email/receipt.ts:9
+-    logOrder                    src/orders/log.ts:5
+ onPaymentWebhook                src/routes/webhooks.ts:58
+   markOrderPaid                 src/orders/status.ts:22
+```
+
+- The fence tag is `callstack`.
+- Caller on top. Indent each callee 2 spaces under its caller; the board turns the spaces into tree lines. Several roots are fine.
+- One frame per line: the function or method name as one identifier, spelled as in the code.
+- The note goes after 2 or more spaces: a `path:line` relative to the project root, which the board links, or a few words. Line the notes up in one column.
+- A `*` after the name, with one space, marks the frame to look at. One per stack.
+- `+` or `-` in the first column marks a frame the change adds or removes. In a stack with any `+` or `-`, every other line starts with one space.
+
+### Folds
+
+A `~ N <what> frames` line stands for frames the reader can skip, such as framework, library or runtime code. It sits where those frames sit: under the frame that calls them, or at the top for framework callers above a handler.
+
+- With frames indented under it, the line is a fold: the board shows it closed, and the reader clicks it to open.
+- A fold that holds the `*` frame or a `+` or `-` frame starts open, so the point stays on screen.
+- Folds nest: library frames that call runtime frames get a `~` each.
+- With nothing under it, the line is a note that frames were left out. Write the frames out only when the reader may need them.
+
+## Pseudocode
+
+```text
+placeOrder(cart)
+  if any item is out of stock
+    return "sold out"
+  charge the card
+  if the charge fails
+    release the stock
+  send the receipt
+```
+
+## Component tree
+
+```tsx
+<CheckoutPage>             (src/routes/checkout.tsx)
+  useCart()
+  <OrderSummary>
+    <PayButton>            (packages/ui)
+```
+
+## File tree
+
+The one view drawn with box characters:
+
+```text
+src/
+├── routes/       # HTTP handlers
+├── orders/       # owns order state
+└── payments/     # talks to the card provider
+```
+
+## Diff
+
+Draw a change in the shape of the view it changes: a component tree diff for a component change, a file tree diff for a move. Mark each line with `+`, `-` or a space in the first column. A call stack takes the marks inside its `callstack` fence; every other view goes in a `diff` fence:
+
+```diff
+ <CheckoutPage>
+   useCart()
+   <OrderSummary>
++    <PromoCodeInput />
+     <PayButton>
+```
+
+Show the whole block without marks when most of it is new, or when a diff would hide the order or the owner of each part.

package/plugin/plugins/claude-code-kanban/skills/show/references/mockup.md

@@ -0,0 +1,30 @@
+# Mockup card
+
+A wireframe in an HTML card: a screen, a dialog, a form or a component, to agree on layout and wording before code.
+
+## Content
+
+- Real labels and real copy from the task: "Delete 3 sessions?", not "Lorem ipsum" or "Button".
+- Plain boxes in place of logos, brand names and product chrome. A gray block (`--color-bg-subtle`) with a mono caption stands in for an image, chart or map.
+- One screen or one state per card. For a flow, post one card per step under one `key` prefix, or show 2 or 3 states side by side when they fit.
+- Mark open questions with numbered callouts: a small circle in `--color-accent` with a number, and the notes as a list under the sketch.
+
+## Building blocks
+
+The card already styles `button`, `button.primary`, `input`, `select`, `textarea`, `table` and headings from the tokens. Use them as they are.
+
+```html
+<style>
+  .m { border: 1px solid var(--color-border); border-radius: 8px; overflow: hidden; }
+  .m-bar { display: flex; gap: 8px; align-items: center; padding: 8px 12px; background: var(--color-bg-subtle); border-bottom: 1px solid var(--color-border); }
+  .m-body { padding: 12px; display: grid; gap: 8px; }
+  .m-img { background: var(--color-bg-subtle); border: 1px dashed var(--color-border); border-radius: 6px; min-height: 64px; display: grid; place-items: center; font: 11px var(--font-mono); color: var(--color-text-muted); }
+  .m-note { display: inline-grid; place-items: center; width: 18px; height: 18px; border-radius: 50%; background: var(--color-accent); color: #fff; font: 600 11px var(--font-sans); }
+</style>
+```
+
+## Fit the card
+
+- A sketch narrower than the card sits centered (`margin-inline: auto`).
+- A phone screen fits at real size, about 360 px. A desktop screen does not: sketch the part under discussion (one panel, the toolbar, the dialog), not the whole window.
+- Scripts may toggle a state (open a menu, switch a tab) to show the interaction. Keep it to a few lines; the card has no storage and no network.