git:20261013.f825a3a to git:20261013.40cfc47

---

name: publish

user-invocable: true

argument-hint: "[prompt] <text|file_path|directory_path|zip_path> [--ttl N] [--entry filename] [--delivery-mode path|subdomain]"

model: haiku

---

# brewdoc:publish

Publishes HTML/Markdown, JSON, files and multi-file sites to **brewpage.app** (free, no sign-up) and returns the URL.

## Prompt contract

`$ARGUMENTS` is one free-form RU/EN prompt; the content (text, file/dir/zip path) and the flags `--ttl N`,

`--entry <filename>`, `--delivery-mode path|subdomain` may sit anywhere in it.

1. Mode: the content type of what is published — detected in Step 2, scored by the keyword table there.

2. Scope: a sentence naming a file/dir resolves to that file/dir (e.g. "publish my report.md" ->

`content_arg = report.md`, resolved against cwd). Never guess, never silently fall back to an empty

3. Ask: a sentence with no path and no inline text/JSON has nothing to publish -> ONE `AskUserQuestion`

asking what to publish. Namespace and password -> the two dedicated `AskUserQuestion` calls in Steps

Print once, before the first tool action, including filesystem probes and questions (labels literal,

values in the conversation language). Use `unresolved` for type/namespace/password until determined;

report resolved stats in Step 3.

```

PLAN — brewdoc:publish

INPUT: <arguments verbatim, or "(empty)">

MODE: <detected type — SITE|MARKDOWN|FILE|JSON|HTML> — <matched extension/shape | prose-resolved path>

SCOPE: namespace=<ns>; ttl=<days>; password=<set|none>; delivery-mode=<server-default|path|subdomain>

DO: <2-5 imperative bullets>

RESULT: <published URL>

```

## Workflow

### Step 1: Parse Arguments

Extract from the prompt:

- `--ttl N` → TTL in days (default: `15`)

- `--entry <filename>` → entry file for SITE uploads (default: auto-detect)

- `--delivery-mode path|subdomain` → optional creation header; omitted = server default; reject other values before upload

- Remaining text → `content_arg`, per Prompt contract rules 2-3

### Step 2: Detect Content Type

### Step 3: Show Pre-Publish Stats

For HTML/MARKDOWN/JSON/FILE:

```

Content: <type description> · <size> · <api endpoint>

TTL: <N> days

```

```

Content: site · <N> files · <total_size> · POST /api/sites

Entry: <entry_file>

TTL: <N> days

```

These are source-tree estimates: report the ARCHIVE MANIFEST that Step 6 prints before upload; its

`ENTRY:` line is the entry `scripts/publish.mjs` resolved in the built archive.

### Step 4: Ask Namespace

Use **AskUserQuestion**:

```

Namespace controls discovery and appears in publication addresses on brewpage.app.

By default publishing is PRIVATE (unlisted): not in the public gallery and not indexed by search engines. The link is not secret, though — anyone who has it can open it (use a password to restrict access).

Choose `public` for eligible gallery discovery. Eligible public HTML, sites and files may permit indexing on either address; unlisted, protected or otherwise ineligible native responses retain `noindex, nofollow`. Indexing is not guaranteed.

Options:

1) public — eligible gallery discovery; eligible publications may permit indexing

2) {suggested slug} — private, link-only (default)

3) Enter custom namespace

4) Skip → use suggested slug (private)

Reply with a number or your custom namespace (1-32 lowercase letters, digits or hyphens).

```

Suggested slug: 3-16 chars of `a-z0-9-` named after the content (`api-docs`, `report-q2`,

`pricing`, `user-config`), else the project or directory name; never random strings or truncated filenames.

### Step 5: Ask Password

Use **AskUserQuestion**:

```

Password protection (if set, page is hidden from gallery):

Options:

1) No password (default)

2) Use an existing local password file (min 4 characters)

3) Skip → no password

Reply with a number and, for option 2, the absolute local file path. Do not paste password contents.

```

### Step 6: Publish and Save Token (secure)

Delivery mode: NEW sites and non-public namespaces require Dedicated subdomain (`subdomain`; explicit `path` is

rejected); NEW public non-sites default to Promotion (`path`) and may select `subdomain`, password-protected

included. Send it only as `X-Delivery-Mode`, never in authored JSON, text or multipart fields. A deduplicated

OLD or NEW winner may differ: keep its identity, cohort, mode and exact `link`. Missing/null OLD routing

metadata means Existing link; never infer mode from its address.

| `{ns}` | `^[a-z0-9-]{1,32}$` | `bp_validate` |

```bash

```

```bash

```

```bash

```

```bash

```

```bash

```

### Step 7: Output Result

```

Published: {url from bash output}

Owner token saved to <project-root>/.claude/brewpage-history.md (mode 600, git-ignored)

```

```

Published site: {url from bash output}

Entry: {entry_file} | Files: {count}

Owner token saved to <project-root>/.claude/brewpage-history.md (mode 600, git-ignored)

Share the server URL exactly as printed, including any trailing slash.

```

For a private (non-`public`) namespace, append one short line after the link (skip if the reply must stay brief): *Unlisted link — anyone who has it can open it, but it's not in the gallery or search. Want it discoverable? Publish to `public`.*

```

Publish failed: {the FAILED line, verbatim}

```

## Notes

- **`format` is a query param**: `/api/html` reads only `?format=` from the URL; a body `format` key is ignored and the default `html` stores markdown as raw text.

- History: `<project-root>/.claude/brewpage-history.md` (root: `CLAUDE_PROJECT_DIR` → git toplevel → upward `.git`/`.claude` walk (a `.claude` in HOME or in the profile parent, the dir whose `.claude` IS the active config dir, is skipped; a `.git` there still counts) → `PWD`, via `scripts/brewpage-lib.sh`), mode `600`, added to the project `.gitignore`. Its header holds the **delete** command for the owner token.

- History TTL = requested days; stored `createdAt`/`expiresAt` are authoritative: a deduplicated winner keeps its original expiry, and ordinary PUT/update does not renew it.

- Owner API calls use the returned `ownerLink` and stored identity metadata, never a NEW root hostname parsed for namespace/ID; OLD rows without metadata keep their existing API identifiers.

- **Update a site**: `PUT` the new bundle to its apex owner API with `X-Owner-Token`; it replaces the file set and keeps the host. No `X-Delivery-Mode` on ordinary PUT/update.

- Hosting change, NEW public non-sites only (OLD, sites and non-public identities have no mode choice): owner-only `PATCH /api/{type}/{ns}/{id}/hosting` with `{"deliveryMode":"subdomain","expectedVersion":1}` from current identity metadata; then use the returned URL/version.

- NEW password-protected links stay clean: never generate or append `?p=`. API password requests use `X-Password`; OLD password behavior is unchanged.

- **SITE bundles are allowlisted**: `pack` drops dot-entries (`.env`, `.git/`, `.DS_Store`), `node_modules/`, symlinks and unknown types, and verifies the archive (`unzip -t`, name set) before `curl`, else deletes it and exits 1. `inspect` never rewrites a supplied ZIP; it exits 2 when anything unexpected or sensitive is inside.

- Keep `.link` exact (NEW subdomain roots keep `/`, OLD links their form); never reconstruct a host from IDs. Verify NEW native sites at the exact URL and asset paths in a browser; OLD sites may redirect via a landing page: check in a browser or fetch the explicit entry asset.