setup

name	setup
description	Bootstrap the html-showcase pipeline into the current repo. Copies build-nav.py, check-orphan-pages.py, and site.sh into <repo>/scripts/,
allowed-tools	Read, Bash, AskUserQuestion
argument-hint	[--site <name>] [--force] [--repo <path>]
disable-model-invocation	false

Prerequisite — cc-plugin-root. This skill resolves its scripts with cc-plugin-root <plugin> (the CLAUDE_PLUGIN_ROOT placeholder is not a shell variable and expands to empty). If the command is missing, run /itp:setup (its first step installs it), or link it directly:

mkdir -p ~/.local/bin && ln -sfn \
  ~/.claude/plugins/marketplaces/cc-skills/scripts/cc-plugin-root ~/.local/bin/cc-plugin-root

/html-showcase:setup — install the pipeline into a repo

Self-Evolving Skill: If a step here is wrong or a workaround was needed, fix this file immediately, don't defer. Only update for real, reproducible issues.

What this skill does

This skill is a thin orchestrator around scripts/install.sh, the shipped one-shot bootstrap. It:

1. Runs a preflight check (no writes) to see what's already installed
2. Reports the diff between the canonical pipeline and the current repo
3. Asks the user whether to proceed (unless they passed --yes)
4. Runs the install with the same flags the user requested

After running, the target repo has:

<repo>/
├── scripts/
│   ├── build-nav.py             ◄── universal sitemap + auto-nav builder
│   ├── check-orphan-pages.py    ◄── pure-stdlib orphan detector
│   └── site.sh                  ◄── nav + validate + push wrapper
├── .gitignore                   ◄── now includes **/.published.json
└── (optional) <site>/           ◄── seeded with index.html, overrides.css, lychee.toml

install.sh itself is not copied into the target repo — it stays in the plugin and is the canonical install entry point.

When this skill fires

• The user types /html-showcase:setup (with or without flags).
• The user asks to "install the showcase scripts", "bootstrap a sitemap-organized site", "set up html-showcase in this repo".
• The user wants to publish a static HTML site to bigblack via Tailscale and is starting from a fresh repo.

It does not fire for:

• Authoring a new page (that's /html-showcase:page-template)
• Editing the kernel CSS (no setup needed; just edit assets/showcase.css)

How to invoke (the model's procedure)

The skill follows the four-phase setup pattern used by other cc-skills plugins (/itp:setup, /itp-hooks:setup, /asciinema-tools:setup).

Phase 1 — Preflight

Resolve the install script and run --check to see what's missing without writing anything.

ROOT="$(cc-plugin-root html-showcase)"
INSTALL="$ROOT/skills/page-template/scripts/install.sh"

bash "$INSTALL" --check

Exit codes:

• 0 — everything already installed; report success and stop.
• 10 — at least one item missing or out-of-date; proceed to phase 2.
• non-zero (other) — script error; report and stop.

Phase 2 — Present findings + gate

Show the user what's missing (the ✗ lines from the preflight output), then ask via AskUserQuestion:

"Install the html-showcase pipeline into this repo? This copies 3 scripts into <repo>/scripts/ and adds one line to .gitignore. Idempotent and safe to re-run."

Options:

• Yes — proceed with install
• Yes, with starter site — also seed <repo>/contractor-site/ (or another name) with index.html, overrides.css, lychee.toml
• No — abort

If the user passed --yes (or equivalent), skip the gate.

Phase 3 — Install (only if approved)

# Plain install
bash "$INSTALL"

# With starter site
bash "$INSTALL" --site "${SITE_NAME:-contractor-site}"

# Force overwrite (only if the user explicitly asks)
bash "$INSTALL" --force

Phase 4 — Verify + summarize

Re-run bash "$INSTALL" --check and confirm exit code 0. Print a short next-steps summary:

✓ Pipeline installed. Next steps:

  1. Author HTML files in <site-dir>/ and any <site-dir>/<section-slug>/
     (each subdir of the site root with *.html becomes a "section").

  2. Build the sitemap + auto-nav rail:
       scripts/site.sh nav <site-dir>

  3. Validate (lychee + orphan-page check):
       scripts/site.sh check <site-dir>

  4. (Optional) Publish to bigblack via Tailscale:
       scripts/site.sh push <site-dir>

For authoring guidance:  /html-showcase:page-template
For the architecture:    plugins/html-showcase/CLAUDE.md

Dependencies the user needs

Confirmed by the --check output:

• python3 ≥ 3.10 (preinstalled on macOS, but verify with command -v python3)
• lychee (only for site.sh check / push) — brew install lychee
• rsync, ssh, git — preinstalled on macOS

If lychee is missing, the install still succeeds (it's only used at validation time). The model should mention it in the next-steps summary so the user installs it before running scripts/site.sh check.

Hard rules

• Never run install without preflight. The preflight is what makes the skill non-destructive.
• Always gate destructive operations on AskUserQuestion unless the user passed --yes. The skill's contract is "I won't surprise you."
• Pass through --repo <path> when the user names a different target. Default is git rev-parse --show-toplevel || pwd, which is usually right.
• Don't re-implement the install logic in the skill. All file copying lives in install.sh. The skill is an orchestrator, not a re-implementation.

Post-Execution Reflection

0. Locate yourself. This SKILL.md lives at plugins/html-showcase/skills/setup/SKILL.md.
1. What failed? If install.sh --check reported wrong state, fix the script. If a phase missed a user expectation, fix this SKILL.md.
2. What worked? Promote any successful patterns into references/ or back into the skill body.
3. What drifted? Keep this skill's command list and the install.sh --help output aligned.
4. Log it. Add a short note to the plugin's CLAUDE.md if you changed an invariant.

Do NOT defer. The next invocation inherits whatever you leave behind.