Drive Dashtxtastic from any folder on your laptop with a Claude Code skill. Author markdown in your editor, type /dashtxtastic in Claude Code, and the skill picks the render mode, creates the project, uploads the file, and returns the preview URL. Re-running it against the same folder updates the existing dashboard instead of creating duplicates.

Prerequisites

• A paid Dashtxtastic subscription. The Developer API is included with Pro and Pro + AI. Free callers receive 402 Payment Required.
• An API key minted at /settings/developer. The plaintext is shown once; copy it to a password manager.
• Claude Code installed and signed in.

Install the skill

Drop two files into your Claude Code skills folder.

On macOS:

mkdir -p ~/.claude/skills/dashtxtastic

On Linux:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/claude/skills/dashtxtastic"

Inside that folder, create SKILL.md with the body from the reference SKILL.md section below, and projects.json with this empty registry:

{
  "_schema": "Dashtxtastic source-path -> project map.",
  "_recovery": "Rebuild by GET /api/v1/projects?pageSize=100 and parsing the 'source:' line from each description.",
  "entries": {}
}

The slash command /dashtxtastic becomes available the next time Claude Code starts. The folder name is the command name.

Set environment variables

Export both in the shell you launch Claude Code from. Add them to ~/.zshrc or ~/.bashrc so they survive new sessions.

export DTX_API_KEY="dtx_..."                       # required, paid-tier bearer token
export DTX_BASE_URL="https://dashtxtastic.com"     # optional, defaults to this

The skill refuses to run if DTX_API_KEY is not set. It never prompts for the key inline and never echoes the key in shell commands.

What the skill does

Five steps per invocation. The user sees one or two questions and a final URL; the rest is automated.

1. Refresh render modes. GET /api/v1/render-modes to pull the live authoringPrompt for every mode.
2. Pick a mode. Match the user's content shape to a mode (table below). Propose the choice with a one-line justification.
3. Create or reuse the project. A local JSON registry maps source folders to projects so a re-run updates instead of duplicating.
4. Author the markdown. Write a single main.md that follows the chosen mode's authoringPrompt exactly.
5. Publish. PUT /api/v1/projects/{id}/files/main.md. The render is inline; the response carries the preview URL.

Dashtxtastic does not have a dedicated process-flow mode. For flow diagrams or parallel-paths layouts, the skill maps to project_hub and re-shapes the content into themed track lists, with confirmation before authoring.

Update vs create

Re-running the skill against a source path already in the registry updates the existing dashboard. You do not need to remember project IDs. The skill records the source-folder to project mapping in ~/.claude/skills/dashtxtastic/projects.json after every successful create. Every POST /projects also writes a source: <abs-path> breadcrumb into the project description, so a lost registry can be rebuilt by listing projects and parsing descriptions.

User: /dashtxtastic update the AI Innovations hub with the latest priorities
Skill: looks up /Users/you/Projects/ai-innovations in the registry
Skill: finds id 46cfb347-... renderMode project_hub
Skill: re-authors main.md and PUTs to /api/v1/projects/46cfb347.../files/main.md
Skill: refreshes lastPublishedUtc, returns the same /view URL

If the registry file is ever lost, rebuild it in one shot:

curl -sS -H "Authorization: Bearer $DTX_API_KEY" \
  "$DTX_BASE_URL/api/v1/projects?pageSize=100" \
  | jq -r '.data.items[] | .description, .id, .renderMode, .name'

Parse each description for the first source: line, rebuild the JSON, drop it back at ~/.claude/skills/dashtxtastic/projects.json.

Per-mode authoring tips

• infographic_before_after uses Dashtxtastic-flavored markdown: [[chip]] bullets and **Lead.** body footer takeaways.
• infographic_stages expects bold key/value meta lines (**Window:**, **Author:**, **Status:**), 3 to 5 **Label.** body guiding-constraint bullets, one ## Phase N: Name (window) per phase, and a ## Metrics and targets table. Appendices are optional; omit them if the doc has none.
• project_hub wants 3 featured H3 cards plus a trailing ### Why this matters, then up to 4 themed track groups. Each track bullet is [Name](sibling.md), owner Name. Headline. for same-project links; use [Name](/view/<other-project-guid>) for cross-project links to other Dashtxtastic dashboards. Featured card bodies must be one or more short paragraphs separated by blank lines: bullet lists inside a featured H3 are stripped (the card renders with the title only), and markdown two-space line breaks inside a single paragraph are collapsed. For a multi-beat narrative inside one card, split each beat into its own paragraph with a bolded cue lead, e.g. **Where we are.** ... then blank line then **What we are missing.** .... Prefix a track bullet with a status marker to color-code it and draw a legend band at the foot of the hub: [at-risk] (amber), [blocked] (red), [decision] (purple), [new] (blue); no marker means on track (green).
• list_dashboard renders a reference-document layout: navy header band, uppercase navy H2 section titles, navy-headered tables with alternating rows. Bold identifier-shaped tokens (no whitespace, like admin-config or CityOfMargate) are auto-styled as monospace blue label badges; multi-word bolds stay as ordinary bold.
• Sibling links use relative paths in every render mode, not just project_hub. Inside any uploaded file, write [label](sibling.md) or [label](subdir/sibling.md) to link to another file in the same project. The renderer rewrites the .md to the published .html and keeps the click inside the preview iframe. Do not write [label](https://dashtxtastic.com/view/<projectId>/sibling.md) for same-project links; full URLs are only correct for cross-project links or off-platform documents.

Failure modes

The skill quotes the message field on any 4xx or 5xx response so you see the renderer's actual complaint.

Reference SKILL.md

Copy the body below into ~/.claude/skills/dashtxtastic/SKILL.md. Authoring rules come from GET /api/v1/render-modes at run time; the live response overrides anything pinned here.

---
name: dashtxtastic
description: "Publish single-page HTML dashboards via the Dashtxtastic API (https://dashtxtastic.com). Picks a render mode (prose, tile / list dashboard, before/after infographic, stages roadmap, or project hub), authors markdown to that mode's spec, uploads it, and returns the rendered preview URL. Use when the user asks for a one-page visual, project overview, before/after comparison, multi-phase roadmap, status hub, or any shareable dashboard sourced from markdown."
---

# Dashtxtastic Skill

Publish a single-page HTML dashboard by driving the Dashtxtastic Developer API. Author markdown that conforms to the chosen render mode's `authoringPrompt` and let the hosted renderer produce the self-contained HTML. The skill covers every render mode the API exposes, not just infographics.

## When to activate

- "Make me an infographic / one-pager / dashboard for X"
- "Visual representation of X, current and future state"
- "One-page summary of X"
- "Roadmap / phase plan for X"
- "Project hub / status hub / track aggregator for X"
- Anytime the user asks for a shareable single-page render of a markdown source

## When NOT to activate

For routine prose docs with lots of headings and narrative paragraphs (priority briefs, weekly retros, meeting agendas, plain status reports), a generic markdown-to-HTML converter is a better fit. Rule of thumb: 4+ headings of prose → use a generic pipeline. 4-10 distinct visual zones (cards, comparison panels, status pills, color-coded bands, phase columns) → this skill.

## Prerequisites (one-time)

The skill expects two environment variables:

```bash
# Required: bearer token minted at https://dashtxtastic.com/settings/developer
export DTX_API_KEY="dtx_..."

# Optional: defaults to https://dashtxtastic.com if unset
export DTX_BASE_URL="https://dashtxtastic.com"
```

If `DTX_API_KEY` is not exported in the shell, stop and tell the user to add it to `~/.zshrc` before continuing. Do not hard-code the key in any command or commit it anywhere.

The Developer API is paid-tier. A 402 response means the subscription has lapsed; surface that to the user verbatim.

## Source-path registry

`~/.claude/skills/dashtxtastic/projects.json` is the source-of-truth map between a source folder on disk and the Dashtxtastic project it publishes to. Read it before every `POST`, write it after every successful `POST` or `PUT`.

Schema (current entries shown in the file itself):

```json
{
  "entries": {
    "<absolute-source-path>": {
      "id": "<project guid>",
      "name": "<dashboard name>",
      "renderMode": "<mode id>",
      "sourceFile": "<filename uploaded as main.md>",
      "lastPublishedUtc": "<ISO 8601>"
    }
  }
}
```

Rules:

1. Before `POST /projects`, look up the source path. If found, skip the `POST` and go straight to `PUT /files/{sourceFile}` against the existing `id`. This makes "update the X dashboard" idempotent across sessions.
2. On every `POST` set the project `description` to a string whose first line is `source: <absolute-source-path>`. That single breadcrumb lets the registry be rebuilt by listing projects and parsing descriptions if the local file is ever lost.
3. After every successful `POST` write a new entry; after every successful `PUT` refresh `lastPublishedUtc`.
4. On registry miss when the user clearly means an existing dashboard, recover by `GET /api/v1/projects?q=<name>` and re-hydrate before creating a duplicate. Never silently create a second project with the same source path.

Sample read / write (jq-friendly):

```bash
REG=~/.claude/skills/dashtxtastic/projects.json
SRC="/absolute/path/to/source/folder"
jq --arg k "$SRC" '.entries[$k] // empty' "$REG"   # read
jq --arg k "$SRC" --argjson v '{...}' '.entries[$k] = $v' "$REG" > "$REG.tmp" && mv "$REG.tmp" "$REG"
```

## Workflow

### 1. Refresh the render-mode catalog

Always start with a live `GET /api/v1/render-modes` so the `authoringPrompt` text the skill follows is current. The renderer is the source of truth; the inline cheat-sheet below is for orientation only.

```bash
curl -sS -H "Authorization: Bearer $DTX_API_KEY" \
  "${DTX_BASE_URL:-https://dashtxtastic.com}/api/v1/render-modes"
```

Read the `data.modes[].authoringPrompt` for the mode you intend to use, top to bottom, before writing any markdown. Rules in those prompts override anything below if they disagree.

### 2. Pick a render mode

| User's content shape | Render mode `id` |
|---|---|
| Current state vs future state, transformation, migration, before/after | `infographic_before_after` |
| Multi-phase roadmap, sprint plan, sequenced initiative with metrics matrix | `infographic_stages` |
| Process flow, parallel paths, track aggregator across themes, "hub" of links | `project_hub` |
| Plain prose with sections | `prose` (rare for this skill; usually a generic pipeline is better) |
| Card grid where each section is a tile | `tile_dashboard` |
| Section-by-section bullet lists | `list_dashboard` |

Important: Dashtxtastic does not have a Pattern-A "process flow" infographic mode. When the user asks for a flow diagram or parallel-paths layout, map it to `project_hub` and re-shape the content into themed track lists (one H3 theme grouping per parallel path, bullets for the steps). Confirm the re-shape with the user before authoring.

Propose the chosen mode to the user in one line with a justification, then wait for confirmation before proceeding to step 3.

### 3. Create or reuse the project

First check the registry. If the absolute source path is already in `~/.claude/skills/dashtxtastic/projects.json`, skip this step and reuse the existing `id` in step 5 (update path, not create path).

For a new project:

```bash
curl -sS -X POST -H "Authorization: Bearer $DTX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<short name>",
    "renderMode": "<chosen-id>",
    "description": "source: <absolute source path>\n<optional one-line summary>"
  }' \
  "${DTX_BASE_URL:-https://dashtxtastic.com}/api/v1/projects"
```

Capture `data.id` from the 201 response and write the new entry to the registry. The `source:` line in the description is the recovery breadcrumb described in the Source-path registry section above.

### 4. Author the markdown

Write a single `main.md` file that follows the chosen mode's `authoringPrompt` exactly. The Dashtxtastic renderer is strict: missing sections, wrong heading levels, or the wrong number of sub-sections will produce broken output, not a friendly error.

Spec highlights per mode (read the live `authoringPrompt` for the full version):

- **`infographic_before_after`** — `# Title` + italic subtitle paragraph. `## Pillars` with exactly 4 `### Pillar` sub-sections (each a paragraph plus 2-3 bullets). `## Why this matters` paragraph. `## Current state` with a baseline-date subtitle paragraph and 8-10 bullets of the form `- [[chip]] **lead** body`. `## Future state` mirrors current state. `## Phase legend`, `## Key takeaways` (bullets with `**Lead.** body`), `## Important notes`.
- **`infographic_stages`** — `# Title` + subtitle. Three `**Window:** ...`, `**Author:** ...`, `**Status:** ...` lines. `## Guiding constraints` (3-5 `**Label.** body` bullets). One `## Phase N: Name (window)` per phase, each with `**Goal:** ...`, `### Work items` table `| ID | Item | Owner | Source |`, `### Exit criteria` bullets, `### Dependencies` bullets. `## Metrics and targets` table. `## Out of scope`, `## Risks`, `## Open questions`. Two appendices: `## Appendix A: Backend coverage tiering` and `## Appendix B: Seed retroactive tests`.
- **`project_hub`** — `# Title` + italic subtitle. `## Featured this cycle` with 3 `### Feature` H3s plus a trailing `### Why this matters`. **Card body rules (observed 2026-05-19):**
  - **Bullet lists in a card body are silently dropped** — only the H3 title renders. Do not use `-` or `*` bullets inside featured H3s.
  - **Multiple short paragraphs in a card body DO render**, even though the spec says "one short paragraph". Separate paragraphs with blank lines. Markdown two-space line breaks (`  \n`) inside a paragraph also get collapsed back to a single line, so use blank-line paragraph breaks instead.
  - For multi-beat narratives (e.g., "where we are / what we are missing / how we close / where we want to get to"), give each beat its own paragraph with a bolded cue lead: `**Where we are.** ...\n\n**What we are missing.** ...\n\n**How we close the gap.** ...\n\n**Where we want to get to.** ...`. This stacks the cues on their own lines and gives a presenter a natural pause point between beats.
  
  `## Tracks by theme` with up to 4 `### Theme` H3s, each containing bullets of the form `- [Track Name](sibling.md), owner Name. Headline.` (use `[Track](/view/<other-project-guid>)` for cross-project links). `## Owner workload matrix`, `## Key takeaways`, `## Notes and sources`.
  - **Track status markers and legend (confirmed 2026-05-21).** Prefix a track bullet with a status marker to color-code it; the renderer draws a legend band at the foot of the hub. The full marker set and color mapping:
    - (no marker) — `On track`, green. This is the default.
    - `[at-risk]` — `At risk`, yellow/amber.
    - `[blocked]` — `Blocked`, red.
    - `[decision]` — `Decision pending`, purple.
    - `[new]` — `New this cycle`, blue.
    Form is `- [blocked] [Track Name](sibling.md), owner Name. Headline.` (marker, then the linked title). Keep any inline `**Blocked**`/`**At risk**` status text in the headline if the source uses it; the marker drives the color, the bold text reads in plain Markdown viewers.

Content gathering:

1. Read the project's `README.md` and primary planning doc (roadmap, plan, scoping).
2. Pull baselines and final targets verbatim from any metrics table.
3. Use named owners only if they appear in the source. Never invent owners.
4. Convert relative dates ("end of Q3") to absolute ("2026-08-03") when the source allows it.

Style rules enforced by the renderer and by user preference:

- **No em-dashes anywhere.** Use commas, periods, parentheses, or semicolons. The user has corrected this many times.
- **No emojis in body content.** Use plain text or rely on the renderer's built-in glyphs.
- **No rendered HTML.** Only `.md` files are accepted by the API. The HTML is the output, never an input.
- **Sibling links use relative paths, never full Dashtxtastic URLs.** Inside any uploaded file, link to another file in the same project as `[label](sibling.md)` or `[label](subdir/sibling.md)`. The renderer resolves these to the published view automatically, and the same source works in any local Markdown viewer (VS Code, GitHub). Do NOT write `[label](https://dashtxtastic.com/view/<project-id>/sibling.md)` — it is verbose, brittle if the project ID changes, and the user has called this out. Full Dashtxtastic URLs are only correct when (a) linking to a *different* project (`[Other Project](/view/<other-project-guid>)`) or (b) the link lives outside the published markdown (e.g., a meeting agenda on disk pointing at the published dashboard root, where no relative path exists).

### 5. Upload the file (renders inline)

`PUT` writes the source, renders, and publishes in a single call:

```bash
curl -sS -X PUT -H "Authorization: Bearer $DTX_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @/tmp/<project-slug>.md \
  "${DTX_BASE_URL:-https://dashtxtastic.com}/api/v1/projects/<id>/files/main.md"
```

Path rules: lowercase ASCII, ends in `.md`, no `..`, no leading slash, under 1 MiB.

**renderMode is per-file, not per-project.** The project carries a default renderMode that new files inherit, but each file can override it. To set a sibling file's renderMode on upload, append `?renderMode=<mode>` as a query parameter on the `PUT`:

```bash
# Upload a prose sibling under a project_hub project
curl -sS -X PUT -H "Authorization: Bearer $DTX_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @/tmp/next.md \
  "${DTX_BASE_URL:-https://dashtxtastic.com}/api/v1/projects/<id>/files/next.md?renderMode=prose"
```

This is undocumented in the OpenAPI spec but works. Use it to attach pages with different shapes (e.g., a `project_hub` main with `prose` or `tile_dashboard` siblings the hub links to via `[Sibling](sibling.md)`). Project-level `PATCH /projects/{id}` with `{"renderMode": "..."}` only changes the project default for future files; existing files keep their per-file value.

The response body's `data` carries the new version and a preview / SAS URL. Surface that URL to the user in the next message, and refresh `lastPublishedUtc` for this source path in the registry.

### 6. Report back to the user

Tell the user:

1. The mode that was chosen and a one-line reason.
2. The Dashtxtastic project URL.
3. Three concrete tweaks they can ask for next (e.g., swap a metric chip, re-shape a bullet, change which file is `main`).

**URL formats (two different routes, do not mix them up):**

- **Hub / project home (main.md):** `https://dashtxtastic.com/view/<id>` with NO filename suffix. The hub renders `main.md` by default; appending `/main.md` is wrong.
- **Sibling file (anything not `main.md`):** `https://dashtxtastic.com/p/<id>/<filename>.html`. Note the **two differences from the API path**: the route prefix is `/p/` (not `/view/`), and the extension is `.html` (not `.md`). The API `PUT` target uses `/view/<id>/files/<name>.md` because that is the upload path, but the human-facing share URL is `/p/<id>/<name>.html`. This is the published, rendered view.

So when sharing a freshly uploaded sibling, build the URL as `/p/<id>/<name>.html`, never as `/view/<id>/<name>.md`. Cross-project links inside markdown still use the `[label](/view/<other-guid>)` form (those resolve to the other project's hub).

Open the URL with `open <url>` only if the user asks for it. Do not auto-open; the preview is gated by their session cookie in the browser.

## Error handling

| HTTP | Meaning | What to do |
|---|---|---|
| 401 | API key missing, malformed, or revoked | Ask the user to re-mint at `/settings/developer` |
| 402 | Subscription dropped to free | Surface verbatim; suggest re-upgrading |
| 412 | Tried to delete the main or last file | Promote a sibling via `POST /files/set-main` first |
| 413 | Markdown body > 1 MiB | Split the content across multiple files; set `main` accordingly |
| 422 | Validation error (renderer rejected the markdown shape) | Re-read the relevant `authoringPrompt` and fix the structure |
| 429 | Rate limit (60 reads / 30 writes per minute per key) | Wait one minute; do not retry in a tight loop |

All `4xx`/`5xx` responses use `{ "status": "error", "error": "<code>", "message": "..." }`. Quote the `message` to the user when reporting failure.

## Anti-patterns

- Hand-crafting standalone HTML, inline CSS, or local SVG. The renderer owns layout; markdown is the only input.
- Calling `POST /projects` before confirming the render mode with the user.
- Uploading rendered HTML, images, or non-markdown files (the API rejects every extension except `.md`).
- Inventing baseline or target metrics that are not in the source docs.
- Polling rapidly after `PUT`. The render is inline; the response already carries the URL.
- Em-dashes anywhere in the markdown content. Strip them from quotes too.
- Hard-coding the API key in the markdown, in commands you echo back, in a commit, or in a screenshot. Use `$DTX_API_KEY` only.

## Reference

- API base: `https://dashtxtastic.com/api/v1`
- OpenAPI: `https://dashtxtastic.com/api/openapi/v1.json`
- Developer docs: `https://dashtxtastic.com/api/docs/index.html`
- Settings (mint keys): `https://dashtxtastic.com/settings/developer`

Authoring rules come exclusively from `GET /api/v1/render-modes` at run time. Do not read local Dashtxtastic source, CSS, or Razor templates to decide markdown structure; the API is the only source of truth.