@rubar/lavish-publish-cf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Kettles
+
+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/README.md

@@ -0,0 +1,83 @@
+# lavish-publish-cf
+
+Self-host a Cloudflare Worker that publishes themed HTML pages on your own domain — plus the Claude Code skill that drives it.
+
+![Brief in, themed Cloudflare-hosted page out](explainer-image.png)
+
+API-compatible with [htmlship.com](https://htmlship.com) (same shape, same CLI verbs), but runs on **your** Cloudflare account with **your** KV. No third party in the loop, no monthly fee, no vendor lock-in.
+
+```
+lavish-publish-cf/
+├── worker/   ← Cloudflare Worker (src/index.ts) + Node CLI (cli/index.js)
+└── skill/    ← /publish Claude Code skill
+```
+
+## What you get
+
+- A **Worker** (`worker/`) that accepts `POST /api/v1/pages` and serves the resulting page at `/v/<slug>` under a strict CSP (`script-src 'none'`).
+- A zero-dep **CLI** (`worker/cli/index.js`, installs as `publish-cf`) that handles publish, update, delete, list-mine, plus per-page inline comments.
+- An inline **comment** UI on `/v/<slug>` — viewers select text and leave anchored comments; the owner addresses them and runs `publish-cf comments resolve <slug> <id>`.
+- A **Claude Code skill** (`skill/`) that goes from "a markdown brief" / "a description" / "an existing HTML file" to a themed, published page in one command. Picks a theme from [`lavish-themes`](https://github.com/natekettles/lavish-themes), inlines the styling, calls the CLI, reports the URL.
+
+## Install
+
+**Just the CLI** (talks to a worker you've already deployed, or any compatible API):
+
+```sh
+npm install -g @rubar/lavish-publish-cf
+publish-cf config set --api-base https://your-worker.workers.dev
+publish-cf --help
+```
+
+Or use it without install: `npx @rubar/lavish-publish-cf publish my-page.html`.
+
+**Full self-host** (deploy your own Worker + KV):
+
+```sh
+git clone https://github.com/natekettles/lavish-publish-cf.git
+cd lavish-publish-cf
+./scripts/install.sh
+```
+
+The installer walks through:
+
+1. `npm install` at the repo root (Wrangler + nothing else)
+2. `npx wrangler login` (interactive — opens browser)
+3. `npx wrangler kv namespace create PAGES` and patches `worker/wrangler.toml`
+4. `npm run deploy` — your worker goes live on `*.workers.dev`
+5. `npm install -g .` so `publish-cf` is on your PATH
+6. Optional: symlink `skill/` into `~/.claude/skills/publish` so Claude Code can find it
+
+Steps that need your input pause and ask. Steps that don't, run. Re-running is safe — every step detects "already done" and skips.
+
+After install, see [`worker/README.md`](worker/README.md) for the full Worker + CLI reference.
+
+## How the pieces talk to each other
+
+```
+You ──/publish brief.md──▶ Claude Code
+                              │
+                              │  reads ~/.lavish-themes/tier{1,2}/<slug>.html
+                              │  (from lavish-themes)
+                              ▼
+                          themed HTML
+                              │
+                              │  publish-cf publish report.html …
+                              ▼
+                          your Worker (workers.dev or custom domain)
+                              │
+                              │  KV: PAGES namespace
+                              ▼
+                          https://<your-worker>/v/<slug>
+```
+
+The skill assumes `~/.lavish-themes` exists (the install location used by [`lavish-themes`](https://github.com/natekettles/lavish-themes)). If you skip themes installation, the skill will still work for HTML you supply pre-styled — it just can't pick a theme for you.
+
+## Related projects
+
+- [`lavish-axi`](https://github.com/kunchenguid/lavish-axi) — local editor and review surface. `/publish loc <source>` (handled by the same skill in `skill/`) saves to `.lavish/` and opens with `lavish-axi` instead of publishing.
+- [`@rubar/lavish-themes`](https://www.npmjs.com/package/@rubar/lavish-themes) — the six theme shells the skill picks from. `npm i -g @rubar/lavish-themes` to get the `lavish-themes` CLI (`list`, `path <slug>`, `copy <slug> [dest]`).
+
+## Licence
+
+MIT — see [`LICENSE`](LICENSE).

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@rubar/lavish-publish-cf",
+  "version": "0.1.0",
+  "description": "CLI for the lavish-publish-cf Cloudflare Worker — publish themed HTML pages with inline comments to your own worker.",
+  "bin": {
+    "publish-cf": "worker/cli/index.js",
+    "lavish-publish-cf": "worker/cli/index.js"
+  },
+  "files": [
+    "worker/cli",
+    "worker/src",
+    "worker/wrangler.toml",
+    "worker/tsconfig.json",
+    "worker/README.md",
+    "worker/CLAUDE.md",
+    "scripts",
+    "skill",
+    "README.md",
+    "LICENSE",
+    "explainer-image.png"
+  ],
+  "scripts": {
+    "dev": "wrangler dev --config worker/wrangler.toml",
+    "deploy": "wrangler deploy --config worker/wrangler.toml",
+    "tail": "wrangler tail --config worker/wrangler.toml",
+    "types": "wrangler types --config worker/wrangler.toml"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260101.0",
+    "typescript": "^5.6.0",
+    "wrangler": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natekettles/lavish-publish-cf.git"
+  },
+  "homepage": "https://github.com/natekettles/lavish-publish-cf#readme",
+  "bugs": {
+    "url": "https://github.com/natekettles/lavish-publish-cf/issues"
+  },
+  "keywords": [
+    "cloudflare",
+    "cloudflare-workers",
+    "publish",
+    "html",
+    "static-site",
+    "lavish",
+    "htmlship"
+  ],
+  "author": "Nathan Kettles",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# install.sh — set up the lavish-publish-cf worker + CLI + Claude Code skills.
+#
+# Idempotent. Each step detects "already done" and skips. Safe to re-run.
+#
+# Steps:
+#   1. cd worker && npm install
+#   2. npx wrangler login (only if not already logged in)
+#   3. Create the PAGES KV namespace and patch wrangler.toml
+#   4. npx wrangler deploy
+#   5. npm install -g . (puts `publish-cf` on your PATH)
+#   6. Optionally symlink skill/ into ~/.claude/skills/publish
+#
+# Env overrides:
+#   LAVISH_PUBLISH_CF_DIR  — repo location (default: $(dirname $(dirname $(realpath $0))))
+#   SKIP_GLOBAL_CLI=1      — skip step 5 (the global npm install)
+#   SKIP_SKILLS=1          — skip step 6 (the Claude Code skill symlinks)
+
+set -euo pipefail
+
+REPO_DIR="${LAVISH_PUBLISH_CF_DIR:-$(cd "$(dirname "$0")/.." && pwd)}"
+WORKER_DIR="$REPO_DIR/worker"
+SKILL_DIR="$REPO_DIR/skill"
+SKILLS_HOME="$HOME/.claude/skills"
+
+# package.json moved to repo root in v0.1.0 — wrangler runs against worker/wrangler.toml.
+PKG_DIR="$REPO_DIR"
+
+bold() { printf "\033[1m%s\033[0m\n" "$*"; }
+dim()  { printf "\033[2m%s\033[0m\n" "$*"; }
+warn() { printf "\033[33m%s\033[0m\n" "$*"; }
+ok()   { printf "\033[32m✓\033[0m %s\n" "$*"; }
+err()  { printf "\033[31m✗\033[0m %s\n" "$*" >&2; }
+
+ask() {
+  local prompt="$1" default="${2:-Y}" reply
+  read -r -p "$prompt " reply
+  reply="${reply:-$default}"
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+require() {
+  command -v "$1" >/dev/null 2>&1 || { err "Missing dependency: $1"; exit 1; }
+}
+
+bold "lavish-publish-cf installer"
+echo "Repo: $REPO_DIR"
+echo
+
+require node
+require npm
+require git
+
+# ---- step 1: install worker deps -------------------------------------------
+bold "Step 1: install worker dependencies"
+cd "$PKG_DIR"
+if [[ -d node_modules && -f node_modules/.package-lock.json ]]; then
+  ok "node_modules already in place — skipping"
+else
+  npm install
+  ok "Installed"
+fi
+echo
+
+# ---- step 2: wrangler login -------------------------------------------------
+bold "Step 2: authenticate with Cloudflare"
+if npx --no-install wrangler whoami >/dev/null 2>&1; then
+  ok "Already logged in: $(npx --no-install wrangler whoami 2>/dev/null | tail -1)"
+else
+  warn "Wrangler needs to authenticate. A browser window will open."
+  if ask "Run \`npx wrangler login\` now? [Y/n]"; then
+    npx wrangler login
+  else
+    warn "Skipped login. Re-run this script after you've authenticated."
+    exit 1
+  fi
+fi
+echo
+
+# ---- step 3: create KV namespace + patch wrangler.toml ----------------------
+bold "Step 3: create the PAGES KV namespace"
+WRANGLER_TOML="$WORKER_DIR/wrangler.toml"
+if grep -q 'REPLACE_WITH_KV_NAMESPACE_ID' "$WRANGLER_TOML"; then
+  dim "Creating namespace…"
+  ns_output="$(npx wrangler kv namespace create PAGES 2>&1)"
+  ns_id="$(printf "%s" "$ns_output" | grep -oE 'id = "[a-f0-9]+"' | head -1 | sed -E 's/id = "([a-f0-9]+)"/\1/')"
+  if [[ -z "$ns_id" ]]; then
+    err "Could not parse KV namespace id from wrangler output:"
+    printf "%s\n" "$ns_output" >&2
+    exit 1
+  fi
+  # macOS sed needs the empty -i argument
+  if [[ "$(uname)" == "Darwin" ]]; then
+    sed -i '' "s/REPLACE_WITH_KV_NAMESPACE_ID/$ns_id/" "$WRANGLER_TOML"
+  else
+    sed -i "s/REPLACE_WITH_KV_NAMESPACE_ID/$ns_id/" "$WRANGLER_TOML"
+  fi
+  ok "Namespace $ns_id wired into wrangler.toml"
+else
+  ok "wrangler.toml already has a KV namespace id — skipping"
+fi
+echo
+
+# ---- step 4: deploy ---------------------------------------------------------
+bold "Step 4: deploy the worker"
+cd "$PKG_DIR"
+if ask "Run \`npx wrangler deploy --config worker/wrangler.toml\` now? [Y/n]"; then
+  npx wrangler deploy --config worker/wrangler.toml
+  ok "Deployed"
+else
+  warn "Skipped deploy. Run \`cd $PKG_DIR && npm run deploy\` when ready."
+fi
+echo
+
+# ---- step 5: global CLI install --------------------------------------------
+if [[ "${SKIP_GLOBAL_CLI:-0}" != "1" ]]; then
+  bold "Step 5: install the publish-cf CLI globally"
+  if command -v publish-cf >/dev/null 2>&1; then
+    ok "publish-cf already on PATH ($(command -v publish-cf))"
+  elif ask "Run \`npm install -g .\` from $PKG_DIR? [Y/n]"; then
+    cd "$PKG_DIR"
+    npm install -g .
+    ok "publish-cf installed globally"
+  else
+    dim "Skipped. You can call it directly: node $WORKER_DIR/cli/index.js …"
+  fi
+  echo
+fi
+
+# ---- step 6: skill symlink --------------------------------------------------
+if [[ "${SKIP_SKILLS:-0}" != "1" ]]; then
+  bold "Step 6: register the /publish Claude Code skill"
+  if [[ -d "$SKILLS_HOME" ]]; then
+    link="$SKILLS_HOME/publish"
+    if [[ -L "$link" ]]; then
+      current="$(readlink "$link")"
+      if [[ "$current" == "$SKILL_DIR" ]]; then
+        ok "$link → $SKILL_DIR (already correct)"
+      else
+        warn "$link points elsewhere ($current). Re-pointing."
+        ln -sfn "$SKILL_DIR" "$link"
+        ok "$link → $SKILL_DIR (updated)"
+      fi
+    elif [[ -e "$link" ]]; then
+      warn "$link exists and is not a symlink. Skipping — move it manually to register the skill."
+    elif ask "Symlink $link → $SKILL_DIR? [Y/n]"; then
+      ln -s "$SKILL_DIR" "$link"
+      ok "$link → $SKILL_DIR"
+    else
+      dim "Skipped skill registration."
+    fi
+  else
+    dim "~/.claude/skills not found — install Claude Code first if you want skill discovery."
+  fi
+  echo
+fi
+
+# ---- next steps -------------------------------------------------------------
+bold "What's next"
+echo "  publish-cf --help                  CLI reference"
+echo "  /publish cf <source>               via Claude Code, after symlinking the skill"
+echo "  /publish loc <source>              same skill, local-only with lavish-axi"
+echo
+bold "Related projects"
+echo "  lavish-themes  https://github.com/natekettles/lavish-themes  (themes/ library)"
+echo "  lavish-axi     https://github.com/kunchenguid/lavish-axi     (local editor)"
+echo
+ok "Install complete."

package/skill/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: publish
+description: "Generate a styled HTML page from a description, file path, or URL and either open it locally in `lavish-axi` for review or publish it to a self-hosted Cloudflare worker. Use whenever the user asks for a lavish page, styled brief, runbook, mock, prototype, report, manifesto, or any HTML artifact they want to view or share. Default theme is light — never dark unless the prompt explicitly says so. Also handles `/publish list` to manage existing CF pages."
+argument-hint: "[cf|loc] <source-path | url | description> | list"
+user-invocable: true
+---
+
+# publish
+
+One skill, two modes:
+
+- **Local** (`/publish loc <source>` or `/publish <source>` when local-ish keywords are present) — generate the HTML, save under `.lavish/`, and open it in `lavish-axi` for review. No Cloudflare involved.
+- **CF** (`/publish cf <source>`) — same generate-and-save, then publish to the self-hosted Cloudflare worker. See `references/cloudflare.md`.
+
+Pairs with `/address-comments <slug>` for the reviewer-feedback loop on CF-published pages.
+
+If the argument is exactly `list` (or `manage` / `pages`), jump to `references/manage.md`.
+
+## Mode resolution
+
+Read the first positional token of the argument:
+
+- `loc` / `local` → **local** mode. Strip the token; treat the remainder as the source.
+- `cf` / `cloudflare` / `publish` → **CF** mode. Strip the token.
+- `list` / `manage` / `pages` → load `references/manage.md` and follow it.
+
+If no mode token is present, scan the rest of the prompt for keywords (case-insensitive):
+
+- "publish to cloudflare", "ship", "deploy", "share publicly" → CF.
+- "view locally", "open in lavish", "preview", "review locally" → local.
+
+If neither token nor keyword resolves the mode, fire `AskUserQuestion` **once** with destination as the question (Local recommended; CF as the alternative). Do **not** default silently — the whole point of asking once is to avoid accidental publishing.
+
+## Inputs
+
+The argument (after stripping the mode token) is required and can be:
+
+| Form                  | Example                            | Treatment                                              |
+| --------------------- | ---------------------------------- | ------------------------------------------------------ |
+| Existing file path    | `/path/to/brief.md`                | Read it. Use as the source.                            |
+| HTTP(S) URL           | `https://example.com/article`      | Fetch via WebFetch; on error fall back to `/crawl4ai`. |
+| Prose / "describe it" | `a 1-page brief comparing X and Y` | Generate content from scratch from the description.    |
+
+If invoked with no argument at all, prompt with `AskUserQuestion` for a source — do not start generating from an empty prompt.
+
+## Check for a project DESIGN.md (before picking a theme)
+
+Walk up from `cwd` (bounded by the repo root — stop at `.git`) looking for `DESIGN.md`, `design.md`, or `Design.md`. If one exists, the project's design system is the source of truth — load `references/design-md.md` and follow it. An explicit theme slug in the prompt still overrides DESIGN.md.
+
+## Theme inference (aggressive — ask only as a last resort)
+
+If the prompt names a theme slug verbatim (`latex`, `terminal`, `water`, `swiss`, `handwritten`, `zine`), use it. Skip the rest of this section.
+
+Otherwise, match the prompt against this table and pick silently:
+
+| Prompt signal                                                            | Theme           |
+| ------------------------------------------------------------------------ | --------------- |
+| "runbook", "postmortem", "RFC", CLI/terminal-flavored                    | **terminal**    |
+| "brief", "strategy", "decision", "memo", decisive product/strategy prose | **swiss**       |
+| "research", "paper", "abstract", citations, academic                     | **latex**       |
+| "manifesto", "launch", "announcement", marketing-loud                    | **zine**        |
+| "letter", "note", "personal", "journal", handwritten feel                | **handwritten** |
+| Generic / neutral / no signal but theme is fine                          | **water**       |
+
+If the prompt gives **zero** signal AND there is no DESIGN.md, fire `AskUserQuestion` once with three bucket options:
+
+- **Recommended: Editorial** — serif and typographic (maps to `swiss`; `latex` for research-feeling pieces).
+- **Utility** — neutral or technical (maps to `water`; `terminal` for runbooks/CLI).
+- **Expressive** — unconventional (maps to `zine`; `handwritten` for personal notes).
+
+All three buckets resolve to **light themes** by default. The user can override by typing a theme slug as `Other`.
+
+## Build the page
+
+1. Read the matching shell at `~/.lavish-themes/tier{1,2}/<slug>.html` (Tier 1: latex, terminal, water. Tier 2: swiss, handwritten, zine). The themes library installs there via [lavish-themes](https://github.com/natekettles/lavish-themes); if it is missing, point the user at that repo's `scripts/install.sh`.
+2. Replace the body content with the user's actual content, **keeping theme-specific markup conventions intact**.
+3. Overwrite every placeholder string (title, masthead, sample copy).
+
+For the per-theme markup rules and the placeholder-replacement checklist, load `references/themes.md` once before authoring.
+
+## Save the file
+
+- If `cwd/.lavish/` exists or `cwd` is writable, save to `<cwd>/.lavish/<kebab-slug>.html`. Create `.lavish/` if missing.
+- Otherwise, save to `~/.lavish/throwaway/<YYYY-MM-DD>-<kebab-slug>.html` (create the dir if needed).
+- `kebab-slug` derived from the page title — short, lowercase, alphanumeric + hyphens. Match the input file's basename when there is one.
+
+## Local mode — open in lavish-axi
+
+```bash
+lavish-axi <path>
+```
+
+That's it. The CLI starts (or reuses) the local server and opens the browser at the right session URL. Per global CLAUDE.md, observe the rendered page before reporting done — confirm it loaded, confirm the theme is light, confirm the content replaced cleanly. No Cloudflare, no public URL.
+
+Reply to the user with:
+
+- Local file path
+- Theme used
+- Any design decision worth review (one-liner, optional)
+
+## CF mode — publish to Cloudflare
+
+Before publishing, load `references/cloudflare.md`. It covers:
+
+- Opt-in keyword/flag triggers for password, comments, and expiry (all off by default)
+- `publish-cf publish` command + flag mapping
+- Post-publish report shape
+- CSP / self-containment rules
+- "When the deploy is stale" recovery
+
+After publishing, run `open <url>` and reply with the tight summary described in the reference.
+
+## Trigger phrases
+
+Match on:
+
+- "publish this as a lavish page", "make a lavish page", "ship this as a styled page"
+- "deploy this brief", "share this as a published page"
+- "view this locally", "preview this in lavish", "open this in the lavish editor"
+- "/publish list", "manage my published pages", "list my pages"
+
+## What NOT to do
+
+- Do **not** spawn a subagent for any flow in this skill. `AskUserQuestion` renders in the main thread; subagents can't reach the user.
+- Do **not** publish to CF without an explicit `cf` token or a CF keyword (or a user pick in the destination question). The default route is local.
+- Do **not** publish before opening the file locally to verify it renders.
+- Do **not** use markdown tables in the user-facing reply (the CLI doesn't render them). For long structured output use a `.lavish/` HTML file and `lavish-axi <file>` per global CLAUDE.md.
+- Do **not** improvise a custom palette. Use the chosen theme shell as-is and only swap content. DESIGN.md is the one sanctioned override; see `references/design-md.md`.

package/skill/references/cloudflare.md

@@ -0,0 +1,99 @@
+# Cloudflare publish reference
+
+Load when running the `cf` mode of `/publish`. Covers opt-in flags, the publish command, the post-publish report, CSP rules, and recovery when the deployed worker is stale.
+
+## Defaults (CF mode)
+
+Unless the user opts in (see triggers below):
+
+- **Comments: off** — page serves directly under strict CSP, no sidebar.
+- **Password: off** — anyone with the URL can view.
+- **Expiry: none** — page stays up until deleted.
+
+## Opt-in triggers in the prompt
+
+Detect any of the following (case-insensitive). Strip matched tokens from the source string before treating the remainder as the source-path / URL / description.
+
+| Dimension | Keyword triggers                                                    | Inline flag form                                                 | Effect                                                                                                                  |
+| --------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Password  | "with password", "add password", "password on", "enable password"   | `password=<value>` / `--password <value>`                        | Turns password on. Keyword with no value → generate one and share back. Inline value → use it; **do not** echo it back. |
+| Comments  | "with comments", "allow comments", "enable comments", "comments on" | `comments=on`                                                    | Turns comments on.                                                                                                      |
+| Expiry    | n/a (too ambiguous in natural language)                             | `expires=<value>` (`1d` / `7d` / `30d` / `none`, or raw minutes) | Sets expiry.                                                                                                            |
+
+## Generating passwords
+
+When the user opted in by keyword (no value supplied), generate one with:
+
+```bash
+openssl rand -base64 12 | tr -d '=+/' | cut -c1-12
+```
+
+Pass it via `--password`. Then **share it back in the final reply** — the user has no other way to recover it.
+
+The "never echo a user-supplied password" rule applies only when the user typed the password into their prompt. Generated passwords must be shared, otherwise they are useless.
+
+## Publish command
+
+```bash
+publish-cf publish <path> [--password "..."] [--expires-in <minutes>] [--no-comments]
+```
+
+Flag mapping from the resolved opt-in state:
+
+- **Password opted in** (keyword or inline value) → `--password "<value>"`. If opted in by keyword only, generate the value first.
+- **Comments not opted in** (the default) → always pass `--no-comments`. Comments opted in → omit the flag.
+- **Expiry**: `1d` → `--expires-in 1440`; `7d` → `--expires-in 10080`; `30d` → `--expires-in 43200`; none → omit the flag.
+
+After publish:
+
+- The URL prints to stdout and auto-copies to clipboard.
+- The `owner_key` and `source_path` are written to `~/.publish-cloudflare/keys.json` automatically — `/address-comments` reads `source_path` later to find the local file.
+
+## Open and report
+
+```bash
+open <url>
+```
+
+Per global CLAUDE.md, observe the page in the browser before reporting done.
+
+Reply to the user with a tight summary:
+
+- The URL (one line, no fluff)
+- Slug
+- Password (if set) — quote it so the user can copy it (only when generated by us)
+- Expiry (if set) — human-readable
+- Comments — on/off
+- Local file path
+- _Optional one-liner if you'd like to call out a design decision worth review._
+
+## Self-containment / CSP rules
+
+The artifact is served under a strict CSP:
+
+- `script-src 'none'` — inline `<script>` and external CDN scripts will not execute.
+- `style-src 'self' 'unsafe-inline' https:` — inline CSS is fine, HTTPS CDN stylesheets are fine, relative paths are not.
+
+Practical rules:
+
+- Inline all CSS, or load it via `<link>` to a public HTTPS CDN. Both work.
+- Don't reference local images or relative paths — they won't resolve on the worker.
+- Every Tier 1 / Tier 2 theme shell already satisfies this.
+
+If the artifact relies on JS to function (a chart library, an interactive widget), warn the user before publishing — it will render as a static skeleton, not as the live version.
+
+## When the deploy is stale
+
+If `publish-cf publish` returns a 404 on the comments endpoint after publish, the worker is older than the comments feature:
+
+```bash
+cd ~/.lavish-publish-cf/worker && npx wrangler deploy
+```
+
+Then retry.
+
+## Related references
+
+- `references/manage.md` — list/manage existing CF pages.
+- `references/themes.md` — placeholder-replacement checklist (CSP requires sample copy be purged).
+- `references/design-md.md` — when a project's DESIGN.md drives styling instead of a theme shell.

package/skill/references/design-md.md

@@ -0,0 +1,56 @@
+# DESIGN.md handling
+
+Load when a project DESIGN.md was found during the walk-up step in `SKILL.md`. The project's design system wins over the six Lavish theme shells — its tokens, fonts, colors, and components are the source of truth.
+
+## Walk-up algorithm
+
+From `cwd`, walk **upward** looking for any of:
+
+- `DESIGN.md`
+- `design.md`
+- `Design.md`
+
+Stop at the first hit. Bound the search by the nearest `.git` directory — don't escape the repo. `lavish-axi` and `lavish-axi design` both surface this path; you can also `grep` for it directly.
+
+## Override hierarchy
+
+```
+explicit theme slug in user prompt   →  use that slug, ignore DESIGN.md
+DESIGN.md exists                      →  build from DESIGN.md, skip the theme picker
+neither                               →  fall through to theme inference in SKILL.md
+```
+
+If the user explicitly names one of the six theme slugs (`latex`, `terminal`, `water`, `swiss`, `handwritten`, `zine`) in their original prompt, that overrides DESIGN.md — proceed with the named template.
+
+## When DESIGN.md is present and not overridden
+
+Surface DESIGN.md as the recommended option in the style question instead of the Editorial/Utility/Expressive buckets:
+
+```
+header: "Style"
+- label: "Recommended: Use <repo>'s DESIGN.md"
+  description: "Build the page from the project's design system. Tokens, fonts, and components come from DESIGN.md."
+- label: "Editorial"
+  description: "Serif and typographic Lavish theme. LaTeX or Swiss depending on content."
+- label: "Utility"
+  description: "Neutral or technical Lavish theme. Water or Terminal depending on content."
+- label: "Expressive"
+  description: "Unconventional Lavish theme. Handwritten or Zine depending on content."
+multiSelect: false
+```
+
+If the prompt provided **no theme signal at all**, you can skip this question and proceed directly with DESIGN.md — the walk-up itself is a strong signal that the user wants project-system styling.
+
+## "Build from DESIGN.md" semantics
+
+If the user picks the DESIGN.md option (or it's used by default per above), skip the template-shell flow entirely. Build the page directly from the project's design system:
+
+- Copy its tokens, components, and markup conventions.
+- Inline the relevant CSS or load the project's stylesheet via HTTPS CDN (subject to the same CSP constraints described in `references/cloudflare.md` if publishing).
+- Keep `<meta name="lavish-design" content="off">` in the head so DaisyUI isn't injected on top.
+
+Read DESIGN.md once at the start of authoring. Treat it as opinionated and prescriptive — don't mix Lavish theme conventions in.
+
+## Local vs CF mode interaction
+
+The DESIGN.md path works identically in both `loc` and `cf` modes. In CF mode, the CSP constraints in `references/cloudflare.md` still apply — inline the CSS or use an HTTPS CDN, never relative paths.