publish

--delivery-mode takes path or subdomain. Omitted, the skill sends no X-Delivery-Mode header and the server chooses. It applies to fresh publications with new-v1 routing metadata.

Promotion serves from a brewpage.app address with stricter HTML limits (scripts, cookies, embeds). Dedicated subdomain gives its own origin with fewer limits: choose it if Promotion breaks your HTML. The response decides the effective mode, and the server may return an existing publication: share the returned link exactly, trailing slash included. New password-protected links stay clean (never append ?p=).

Good to know

• Eligible, unprotected HTML, sites and files in public can appear in the gallery and be indexed; everything else is noindex. Eligibility does not guarantee ranking.
• Headless runs use the defaults: suggested private namespace, no password.
• A rejected upload prints FAILED: publish rejected (HTTP <status>: <message>) with the server’s reason. After a successful OK line, lines starting with NOTICE: say what the server skipped or adjusted.
• Limits behind the headline numbers: a ZIP expands to at most 40 MB, paths stop at 380 characters (900 bytes) and names at 200 bytes. The skill’s own read-only limits command prints the current values.
• Do not publish .env files or secrets: pages are reachable by anyone with the link, and content expires after the TTL.

Arguments. --ttl N (default 15), --entry <filename>, optional --delivery-mode path|subdomain (other values are rejected before upload). A prompt with no path and no inline text asks once what to publish.

Detect. For a path, brewpage-run.sh probe '<path>' prints TYPE:, the absolute PATH: and size stats. Types are classified SITE, MARKDOWN, FILE, JSON, HTML in that order.

Namespace. Options: public, a suggested slug (3-16 chars named after the content, such as api-docs; never random), or custom. Skip or no answer means the suggested private slug.

Password. Option 2 takes an absolute path to an existing file with at least four characters. Option 1, 3 or no answer ignores every password file, stale ones included. The helper copies the bytes into private header files: never shell literals, curl arguments or chat output; control characters stop the upload.

Publish. Every slot is re-validated by the script (ns, days, entry, delivery_mode, password_file); an invalid value is re-asked, never cleaned up. Commands over 8,000 characters are refused, so long text goes through stage: chunks of up to 6,000 characters, then publish --run <id>. cleanup --run <id> drops a staged but unpublished run.

Result. The script prints one decisive line: OK <url> (sites add | Files: N), CONFIRM: ... (exit 2, nothing uploaded; after you confirm, the same command reruns with --confirmed) or FAILED: ... (response body withheld, since it may hold a token). On OK the skill shows Published: <url> (sites: Published site: <url>). The run directory is removed on every exit.

One script, one rule. Every shell step is bash ${CLAUDE_SKILL_DIR}/scripts/brewpage-run.sh <probe|stage|publish|cleanup> ... with single-quoted values. The single allowed-tools rule matches that exact shape, so nothing prompts, headless included. A quoted script path, cd prefix, && chain or $(...) falls back to the normal permission prompt.

Owner token. Captured inside the script and written to history; the model sees only OK, CONFIRM or FAILED lines.

Run isolation. A private brewpage.XXXXXX directory (mode 700) under $TMPDIR, else /tmp, outside .claude/; only the script creates and removes it, so no Write grant is needed.

History file. <project-root>/.claude/brewpage-history.md, mode 600, git-ignored. Root resolution: CLAUDE_PROJECT_DIR, Git, an upward .git/.claude search (a profile .claude is skipped), or the current directory. Existing rows are never rewritten.

| Date | URL | Owner Token | TTL | Type | Owner API | Identity |
|------|-----|-------------|-----|------|-----------|----------|

Use the stored Owner API (ownerLink), never a hostname split into namespace and ID. OWNER_API is that URL and TOKEN the stored owner token.

curl -s -X DELETE "$OWNER_API" -H "X-Owner-Token: TOKEN"
curl -s -X PUT "$OWNER_API" -H "X-Owner-Token: TOKEN" -F "archive=@/absolute/path/to/new-bundle.zip"

PUT replaces a site’s file set and keeps the host and the delivery mode; do not send X-Delivery-Mode on it.

Only new public non-sites can switch hosting: GET /api/{type}/{ns}/{id}/hosting returns the version, then PATCH it with X-Owner-Token and {"deliveryMode":"subdomain","expectedVersion":1}. Use the version from GET. Issued URLs become safe redirects.

Passwords and revocation cannot recall downloaded or cached copies.

A directory is packed by scripts/publish.mjs pack --dir <dir> --out <archive.zip>: stale target removed, zip status checked, result verified with unzip -t and a non-zero size; any failure deletes the archive before curl runs.

The pack is an allowlist: only web-asset extensions (.html .css .js .json .svg .png .woff2 .pdf .md and similar) go in. System files (.DS_Store, __MACOSX/, Thumbs.db, desktop.ini) are dropped and listed under SKIPPED, never flagged and never counted toward the server’s file limit. Hidden files and folders (.env, .git/) are dropped too, except the root .well-known/, which ships with its files, extension-less ones included (such as apple-app-site-association); node_modules/ and symlinks are dropped as well. A supplied .zip is inspected, never rewritten: system entries are left alone (the server drops them), hidden entries are flagged, and an entry matching .env, id_rsa, secret, credential, password, token, .pem, .key, .p12, .crt or .map blocks the upload until you confirm.

Tests: bash brewdoc/skills/publish/tests/run.sh (no network, no real upload; they do not prove server rollout).