Maintainer.

# Standard release cycle (most days):
cd /Users/zy/dev/dashbook
# make changes …
pnpm check                    # expect 0 errors
pnpm dev                      # http://localhost:5173 — smoke-check visually
# update PLAN.md §9 with a Done row for what you just did
git add -A
git commit -m "EN-XX: <one-line scope>"   # uses the team's commit convention
git push                      # → Vercel auto-deploys; ~60s to live

# After the deploy, open https://dashbook.vercel.app to verify

# 1. Create the typed spec
src/lib/specs/components/<slug>.ts
# Use an existing one as a template — e.g. button.ts has the full shape.

# 2. Register it in the index
src/lib/specs/components/index.ts        # alphabetical
src/lib/content/components.ts            # sidebar + search

# 3. Create the docs page
src/routes/components/<slug>/+page.svelte
# Use ComponentLayout. Reference button/+page.svelte as the template.

# 4. (Optional) Add to nav if it's a featured component
src/lib/content/nav.ts

# 5. Verify
pnpm check                               # spec type-checks
pnpm dev                                 # visit /components/<slug>

# 1. Add the content entry
src/lib/content/patterns.ts
# Fields: slug, name, description, category, uses, optional draft flag.
# Categories: Shells · Data · Forms · Confirmation · States · Layout · Architecture.

# 2. Create the page
src/routes/patterns/<slug>/+page.svelte
# Use PatternLayout. Best templates:
#   - transaction-list/+page.svelte   (data recipe)
#   - empty-zero-state/+page.svelte   (simple state)
#   - url-state-dialog/+page.svelte   (architecture w/ live demo)

# 3. Update nav
src/lib/content/nav.ts                   # add child under Patterns

# 4. Verify
pnpm check
pnpm dev                                 # visit /patterns/<slug>

# Append a new variant to src/lib/chrome/card-sources.ts:

export const cardVariants: CardVariant[] = [
  { id: 'jade', label: 'Jade', /* … */ },
  {
    id: 'cobalt',                        // kebab-case; ends up in URLs + MCP tool args
    label: 'Cobalt',
    description: '…',
    status: 'production' | 'draft',
    usedForBins: ['12345'],              // which BINs ship this variant
    bg: '#354CEF',
    gradient: { /* … */ },
    wordmarkFg: '#FFFFFF',
    appIcon: { bg: '#354CEF', glyph: '#FFFFFF', radius: 0.2 }
  }
];

# No other code changes needed — generators are variant-agnostic.
# Verify in /brand/card configurator and via:
#   curl http://localhost:5173/api/card/<id>/preview

# Tokens are defined in two places that must stay in sync:

# 1. src/app.css           — the runtime CSS vars (--bg, --primary, etc.)
# 2. src/lib/tokens.ts     — typed exports for MCP/JSON API/spec consumers

# Update both. Then:
pnpm check
pnpm dev
# visit /foundations/color to confirm the token surfaces with the new value
# visit /foundations/typography or /spacing as relevant

# Four independent versioned things:

# Dashbook portal (this repo)
package.json   "version": "x.y.z"
# Bump on release-worthy changes. Currently 1.0.0 (first declared-stable release).

# Claude plugin manifest (Channel B — see §8)
claude-plugin/.claude-plugin/plugin.json   "version": "x.y.z"
.claude-plugin/marketplace.json   plugins[].version   "x.y.z"
# Bump BOTH together on skill/command/MCP-server-entry changes — the admin
# card reads marketplace.json, not plugin.json. Currently 0.3.0.

# @dashfi/mcp-server (the npm CLI proxy)
packages/mcp-server/package.json   "version": "x.y.z"
# Bump on additive features (new tools, new resources) or breaking changes
# (tool signature changes). Currently 0.3.0.

# @dashfi/svelte (the lib, in core monorepo)
core/libs/svelte-components/lib/package.json   "version": "x.y.z"
# Currently 0.0.1 (never bumped). On the next coordinated release, bump to
# 0.1.0 (additive features) or 1.0.0 (declared stable). NOT in this repo —
# that lives in core. Sync via the migration branch.

# TWO UPDATE CHANNELS — they propagate very differently. The common trap is
# assuming an edited skill reaches everyone instantly. It doesn't; the MCP
# tools the skill talks about do.

# ── Channel A: MCP tools + JSON API + /llms.txt  (AUTOMATIC) ──
# Anything the deploy serves: /mcp tools, /api/* JSON, /llms.txt, all src/.
#   Merge to main → Vercel auto-deploys → live for ALL clients (Claude Code
#   plugin, claude.ai Connector, Desktop) on their next call.
#   No version bump, no admin action, no re-install.

# ── Channel B: skill prose + slash commands  (ORG-WIDE, needs a step) ──
# Ships INSIDE the plugin, pulled from the trlmkb/dashbook GitHub repo.
#   1. Edit claude-plugin/ — SKILL.md, commands/*.md.
#   2. Bump claude-plugin/.claude-plugin/plugin.json "version".  ← the signal; don't skip.
#   3. Merge to main on trlmkb/dashbook.
#   4. claude.ai admin → Plugins (Cowork) re-pulls from GitHub automatically —
#      there is NO manual sync button. The command list refreshes on the next
#      pull; the plugin CARD (name, description, version shown in admin) is keyed
#      to the "version" field in .claude-plugin/marketplace.json (the root
#      marketplace manifest — NOT claude-plugin/.claude-plugin/plugin.json), so
#      bump BOTH versions or the card shows stale metadata. To force a refresh:
#      remove + re-add the org marketplace in admin.
#   5. Members get it on their NEXT Claude Code session. No per-user install.

# Connector (claude.ai web users)
#   admin → Organization settings → Connectors → Add → Custom → Web
#   URL: https://dashbook.vercel.app/mcp
#   Gets Channel A (MCP tools) automatically. Does NOT get Channel B —
#   slash commands are a Claude Code convenience; web users invoke the tools
#   directly or via the skill.

# VERIFY
#   Channel A:  curl https://dashbook.vercel.app/api/marketing/patterns.json   (instant after deploy)
#   Channel B:  fresh Claude Code session → new /dashbook-* commands appear,
#               skill shows the bumped version.

# When someone files a bug or sends feedback:

# 1. Reproduce in your own session (fresh Claude Code, dashbook plugin installed).
# 2. If repro fails: likely client-side. Ask reporter for:
#       - /plugin list output
#       - /mcp connection status
#       - Time of failure (we can correlate to Vercel logs)
#       - Whether fresh install or existing
# 3. If repro succeeds: that's a real bug.
#       - File GH issue: trlmkb/dashbook/issues
#       - Fix forward, ship in next release
#       - Add to PLAN.md §9 Done with what changed + why

# Past examples in .knowledge/:
#   2FA-page wordmark bug    →  cross-namespace fix (0319f50)
#   MCP tool surface zero results  →  P0 investigation (still pending)
#   Docs SPA WebFetch invisible  →  /api/components.json + JSON API