brewpage-mcp 1.21.0 → 1.23.0

package/README.md

@@ -38,7 +38,7 @@ Claude Code: `claude mcp add --transport http brewpage --scope user https://brew
 For clients that only start local servers; the same tools as the server URL.
 
 ```bash
-npx -y brewpage-mcp@1.21.0
+npx -y brewpage-mcp@1.23.0
 ```
 
 Requires Node.js 20 or newer. This starts the stdio server for an MCP client.
@@ -63,7 +63,7 @@ Local fallback (stdio, needs Node.js; the same tools): add to `~/Library/Applica
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.21.0"]
+      "args": ["-y", "brewpage-mcp@1.23.0"]
     }
   }
 }
@@ -86,7 +86,7 @@ Custom servers follow your ChatGPT plan and workspace settings.
 The remote command above is the default. Local fallback: register a project-scoped stdio server:
 
 ```bash
-claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.21.0
+claude mcp add --transport stdio --scope project brewpage -- npx -y brewpage-mcp@1.23.0
 ```
 
 This writes `.mcp.json` in the project root. Use `--scope user` for user-scoped registration. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
@@ -110,7 +110,7 @@ Local fallback (stdio, needs Node.js; the same tools): open **Settings > MCP** a
   "mcpServers": {
     "brewpage": {
       "command": "npx",
-      "args": ["-y", "brewpage-mcp@1.21.0"]
+      "args": ["-y", "brewpage-mcp@1.23.0"]
     }
   }
 }
@@ -124,7 +124,7 @@ Open the Cline MCP settings panel and add:
 {
   "brewpage": {
     "command": "npx",
-    "args": ["-y", "brewpage-mcp@1.21.0"]
+    "args": ["-y", "brewpage-mcp@1.23.0"]
   }
 }
 ```
@@ -156,21 +156,21 @@ Thirty-two tools are available. Creation returns an owner token; keep it to modi
 | `bind_token` | Add an owner token to your profile (admin token) |
 | `mint_token` | Mint a profile token, shown once (admin token) |
 | `set_domain` | Connect a domain you own to an HTML page or site; returns the DNS records to create |
-| `list_domains` | List the profile's custom domains with status and DNS records (admin token) |
-| `check_domain` | Check a custom domain's DNS now; status `pending_dns` -> `verifying` -> `active` |
+| `list_domains` | Read one custom domain's status and DNS records without a check, or list the profile's custom domains (admin token) |
+| `check_domain` | Run a DNS check once the records exist; status `pending_dns` -> `verifying` -> `active` |
 | `remove_domain` | Remove a custom domain and free its slot; the BrewPage link keeps working |
 | `get_page_data` | Read what visitors saved on your page: the settings and usage, or one list's entries |
 | `set_page_data` | Write author entries (for example today's menu) without republishing the page |
 | `configure_page_data` | Change who can read a list and its limits; only what you name changes |
 | `delete_page_data` | Delete entries by id, or every entry in a time range |
-| `get_guide` | Read the short Page data guide before writing a page that saves data |
+| `get_guide` | Read a short guide: Page data before writing a page that saves data, or the custom-domain steps |
 | `search_gallery` | Browse public content or list owned resources |
 | `get_stats` | Read platform-wide statistics |
 | `get_limits` | Read the current upload limits (`GET /api/limits`) |
 
 All five publish tools accept optional `deliveryMode: "path" | "subdomain"`, sent only as `X-Delivery-Mode`; authored JSON and multipart bodies keep their existing format. Visibility and password protection are separate choices. Omitted namespace is private (a generated `priv-<random>` namespace): unlisted and not indexed; anyone with the link can still open it. `public` lists HTML, sites and files in the gallery and sitemap, so Google, Bing and AI search can find and index them; public pages are served on the brewpage.app domain for the strongest reach (a site always gets its own subdomain). Never put secrets in a public publication. Password-protected publications, JSON and KV are never listed.
 
-The MCP server wraps a subset of the backend-generated public [REST contract](../openapi/openapi.json). TTL inputs take days or a string such as `2w`/`36h` (default 15); the server rounds to whole days and clamps to 1–30 (owner-specific caps and eligible automatic extensions can differ). Use returned `expiresAt`. Every tolerated-input adjustment (TTL clamp, format alias, skipped site member, normalised namespace) comes back in the response `notices` array and is printed as `Notice (code): message`; `secret-detected` prints as `WARNING (code): message`: relay it to the user. A live BrewPage token or manage link in public content (`credential-published`) prints first as `SECURITY ALERT (credential-published): …`: tell the user to remove and reset it; that result is hidden from the gallery, so it prints no `VISIBILITY` line. A minted `manageUrl` prints as `MANAGE LINK (private): …`: give it to the user privately, never publish it. A listed public result prints `VISIBILITY: public, listed. Hide: set_visibility listed=false`. `get_page` reads stored rendered HTML or format-specific code/text from the API; it does not call the owner-only original-source endpoint or a browser viewer. `publish_file` uploads from a source URL and does not expose password or TTL inputs.
+The MCP server wraps a subset of the backend-generated public [REST contract](../openapi/openapi.json). TTL inputs are days: up to 30 days without an account, up to 90 with a free profile (an owner token held in the profile); a default applies when omitted; whole days such as `15`, `15d` or `15 days`. Use returned `expiresAt`. Every tolerated-input adjustment (format alias, skipped site member, normalised namespace) comes back in the response `notices` array and is printed as `Notice (code): message`; `secret-detected` prints as `WARNING (code): message`: relay it to the user. A live BrewPage token or manage link in public content (`credential-published`) prints first as `SECURITY ALERT (credential-published): …`: tell the user to remove and reset it; that result is hidden from the gallery, so it prints no `VISIBILITY` line. A minted `manageUrl` prints as `MANAGE LINK (private): …`: give it to the user privately, never publish it. A listed public result prints `VISIBILITY: public, listed. Hide: set_visibility listed=false`. `get_page` reads stored rendered HTML or format-specific code/text from the API; it does not call the owner-only original-source endpoint or a browser viewer. `publish_file` uploads from a source URL and does not expose password or TTL inputs.
 
 For a fresh publication, sites and HTML pages of format `HTML` outside `public` (including the generated unlisted namespace) always use Dedicated subdomain (`subdomain`); omit `deliveryMode` there. An explicit `path` there is not rejected: the publication is created on its subdomain and the result reports `deliveryModeMatched: false`, `deliveryModeReason: "policy:subdomain-required"` and a `Delivery notice:` line. Everything else in any namespace (Markdown, code/text, files, JSON, KV, public HTML) defaults to Promotion (`path`) and may choose Dedicated subdomain, including password-protected content. Promotion uses a BrewPage path with stricter active-document restrictions. Each NEW site gets one publication-specific host for its complete bundle, preserving relative/root-relative paths; missing assets return 404, with no SPA fallback. Third-party widgets may still need provider configuration.
 
@@ -198,7 +198,7 @@ update_hosting(type="html", namespace="public", id="aBcDeFgHiJ", ownerToken="tok
 
 Publish HTML, Markdown, code or JSON content to BrewPage; with `format` omitted the server detects it. Returns a public URL and owner token. Markdown raw HTML is rendered through an allowlist: scripts, styles, event handlers, forms, frames/embeds and `meta`/`base`/`link` are removed; links allow `http`, `https`, `mailto`, `tel` and relative URLs, images also `data:`; a lone unknown tag such as `<author>` shows as text.
 
-Parameters: `content` (string), `format` (optional; omit to let the server detect HTML, Markdown, code or JSON; `html` keeps code/JSON as HTML; also `markdown`/`md` or a code language), `namespace` (optional -- **omit for private, unlisted content**; `public` lists the page in the gallery and sitemap for Google, Bing and AI search, served on the brewpage.app domain; never put secrets there), `password` (optional), `ttlDays` (days or a string such as `2w`; default 15; the server clamps to 1--30, up to 90 with an owner token in a profile), `filename` (optional, used as title fallback), `showTopBar` (optional boolean -- adds a toolbar with filename, Download button, and theme toggle), `deliveryMode` (optional), `domain` (optional; a domain you own to connect to an HTML-format page, see Custom domains), `state` (optional; lets an HTML page save what its visitors enter, see Page data).
+Parameters: `content` (string), `format` (optional; omit to let the server detect HTML, Markdown, code or JSON; `html` keeps code/JSON as HTML; also `markdown`/`md` or a code language), `namespace` (optional -- **omit for private, unlisted content**; `public` lists the page in the gallery and sitemap for Google, Bing and AI search, served on the brewpage.app domain; never put secrets there), `password` (optional), `ttlDays` (days: up to 30 without an account, up to 90 with a free profile; a default applies when omitted), `filename` (optional, used as title fallback), `showTopBar` (optional boolean -- adds a toolbar with filename, Download button, and theme toggle), `deliveryMode` (optional), `domain` (optional; a domain you own to connect to an HTML-format page, see Custom domains), `state` (optional; lets an HTML page save what its visitors enter, see Page data).
 
 The result includes `deliveryModeReason` and a `Delivery notice:` line when the server returns them (see above).
 
@@ -276,7 +276,7 @@ Publish a single-page or multi-file HTML site. Pass `entryContent` for a single
 
 Limits (current values from `get_limits`): a request is at most 25 MiB; a site at most 200 files, 5 MiB per file and 20 MiB in total; each path at most 380 characters. System files such as `.DS_Store` and `__MACOSX/` are skipped and never count; files with an unsupported extension or a too-long path are skipped and reported in notices. Entry: `entry`, else root `index.html`, else the shallowest HTML file. A site limit hit answers 400 with a message naming the limit, as does a PDF/Office file that is unreadable or password-protected; 413 means the request is over 25 MiB, has too many files and form fields, or a file name/path is too long; 422 means no servable file is left; 503 means busy: retry after `Retry-After` seconds (failed publish tools print it).
 
-Parameters: exactly one of `entryContent` (string) or non-empty `files` (array of `{path, content}`), `entry` (optional entry file path, default `index.html`), `namespace` (optional -- omit for private, unlisted content; `public` lists the site in the gallery and sitemap for Google, Bing and AI search; a site always gets its own subdomain), `password` (optional), `ttlDays` (days or a string such as `2w`; default 15; the server clamps to 1--30, up to 90 with an owner token in a profile), `ownerToken` (optional, groups site under an existing owner), `deliveryMode` (optional; fresh sites require `subdomain`), `domain` (optional; a domain you own to connect to the site, see Custom domains), `state` (optional; lets the site save what its visitors enter, see Page data).
+Parameters: exactly one of `entryContent` (string) or non-empty `files` (array of `{path, content}`), `entry` (optional entry file path, default `index.html`), `namespace` (optional -- omit for private, unlisted content; `public` lists the site in the gallery and sitemap for Google, Bing and AI search; a site always gets its own subdomain), `password` (optional), `ttlDays` (days: up to 30 without an account, up to 90 with a free profile; a default applies when omitted), `ownerToken` (optional, groups site under an existing owner), `deliveryMode` (optional; fresh sites require `subdomain`), `domain` (optional; a domain you own to connect to the site, see Custom domains), `state` (optional; lets the site save what its visitors enter, see Page data).
 
 Example prompt:
 
@@ -306,7 +306,7 @@ republish_site(namespace="public", id="aBcDeFgHiJ", ownerToken="tok_...", files=
 
 Publish a JSON document to BrewPage. Returns a public URL and owner token. The body may be passed as a JSON string or as a structured object.
 
-Parameters: `json` (string, object, or array), `namespace` (optional -- omit for private content; `public` is the shared public namespace; JSON is never listed or indexed, anyone with the link can open it), `password` (optional), `ttlDays` (days or a string such as `2w`; default 15; the server clamps to 1--30, up to 90 with an owner token in a profile), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
+Parameters: `json` (string, object, or array), `namespace` (optional -- omit for private content; `public` is the shared public namespace; JSON is never listed or indexed, anyone with the link can open it), `password` (optional), `ttlDays` (days: up to 30 without an account, up to 90 with a free profile; a default applies when omitted), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
 
 Example prompt:
 
@@ -356,7 +356,7 @@ update_json(namespace="public", id="aBcDeFgHiJ", json={"mode": "dark", "version"
 
 Create a new KV (key/value) entry. Returns a public URL and owner token. The KV entry is addressed by `(namespace, id, key)`; this tool creates the entry and emits the generated `id` along with the owner token.
 
-Parameters: `key` (string), `value` (string), `namespace` (optional -- omit for private content; `public` is the shared public namespace; KV is never listed or indexed, anyone with the link can open it), `password` (optional), `ttlDays` (days or a string such as `2w`; default 15; the server clamps to 1--30, up to 90 with an owner token in a profile), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
+Parameters: `key` (string), `value` (string), `namespace` (optional -- omit for private content; `public` is the shared public namespace; KV is never listed or indexed, anyone with the link can open it), `password` (optional), `ttlDays` (days: up to 30 without an account, up to 90 with a free profile; a default applies when omitted), `tags` (optional `string[]`), `ownerToken` (optional existing owner), `deliveryMode` (optional).
 
 Example prompt:
 
@@ -510,37 +510,48 @@ Parameters: `label` (optional), `scope` (`publish` default | `admin`), `expiresI
 
 ### Custom domains
 
-Show one HTML page (format html, no password) or one site on a domain you own, such as `www.example.com` or `example.com`. Free, 5 per profile. The owner token must be in a free BrewPage profile: sign in at https://account.brewpage.app and add the token there, or with `bind_token`. The BrewPage link keeps working.
+Show one HTML page (format html, no password) or one site on a domain you own, such as `www.example.com` or `example.com`. Free, up to 5 per profile. A profile token works at once; an owner token must first be added to a free BrewPage profile: sign in at https://account.brewpage.app/tokens, press Add existing token and paste it (or `bind_token` with an admin profile token). Any registrar or DNS host works; if you are buying a domain, Cloudflare and Porkbun are the quickest to set up. The BrewPage link keeps working.
 
-How it goes: `set_domain` returns the DNS records, the domain owner creates exactly those records at their DNS provider, then `check_domain` reports the status: `pending_dns` (records not seen yet), `verifying` (DNS found, HTTPS being issued), `active` (live). HTTPS is issued automatically. The records come from the result, never from memory: a subdomain takes a TXT record at `_brewpage.<host>` plus a CNAME to `domains.brewpage.app`; a root domain takes the TXT record plus the A record shown, or the optional ALIAS row.
+How it goes:
 
-`publish_html` and `publish_site` accept an optional `domain` to connect it while publishing. The publication is always created; the result prints a `CUSTOM DOMAIN` block with the records, or says the domain was not set next to the notice that explains why.
+1. `set_domain` returns the DNS records. They come from the result, never from memory: a subdomain takes a TXT record at `_brewpage.<host>` plus a CNAME to `domains.brewpage.app`; a root domain takes the TXT record plus the A record shown, or the optional ALIAS row.
+2. The domain owner creates exactly those records at their DNS provider: MX (mail) records stay, an A, AAAA or CNAME record at the same name is replaced, and at Cloudflare Proxy status is set to DNS only.
+3. After the records exist, `check_domain` once.
+4. `list_domains` with the same `type`, `namespace` and `id` reads the status without a new check until it is `active`. BrewPage checks on its own (the first full check about 15 minutes after adding); the domain is usually live within 30 minutes and HTTPS is issued automatically. Another `check_domain` is needed only after a DNS change.
+
+Statuses: `pending_dns` (records not seen yet), `verifying` (DNS found, HTTPS being issued), `active` (live), `lost` (the records broke after going live; the domain is still served until `graceEndsAt`: restore the records and check again). The `Problem:` line of a result names what blocks progress and its fix; a refusal names its next step. The same steps are in `get_guide(topic="custom-domain")` for the assistant.
+
+`publish_html` and `publish_site` accept an optional `domain` to connect it while publishing. The publication is always created; the result prints a `CUSTOM DOMAIN` block with the records, or says the domain was not set, with the next step, below the notice that explains why.
 
 ### `set_domain`
 
 Connect a domain to an HTML page or site (`PUT /api/publications/{html|site}/{ns}/{id}/domain`). A hostname already in the profile moves to this publication. A page on a BrewPage path address moves to its own subdomain, and its BrewPage link keeps working.
 
-Parameters: `type` (`html` | `site`), `namespace`, `id`, `hostname` (e.g. `www.example.com` or `example.com`), `ownerToken` (optional; the publication's owner token added to a profile, or a profile token).
+Parameters: `type` (`html` | `site`), `namespace`, `id`, `hostname` (a bare hostname such as `www.example.com` or `example.com`, no scheme or path), `ownerToken` (optional; a profile token, or the publication's owner token added to a profile).
 
 ```
 set_domain(type="html", namespace="public", id="aBcDeFgHiJ", hostname="www.example.com")
 ```
 
-Output: `Custom domain connected.`, then `Domain:`, `Status:`, `Problem:` (what is still missing), `Serving:`, `Shows:`, the `records[]` rows verbatim as JSON (`type`, `name`, `host`, `value`, `state`) and the next step. `host` is the name DNS panels ask for.
+Output: `Custom domain added. It is not live until the DNS records below exist.`, then `Domain:`, `Status:`, `Problem:` (what is still missing, with the fix), `Serving:`, `Shows:`, the `records[]` rows verbatim as JSON (`type`, `name`, `host`, `value`, `state`) and the next step. `host` is the name DNS panels ask for.
 
 ---
 
 ### `list_domains`
 
-List the custom domains of a profile (`GET /api/domains`): how many are used and allowed, and for each one its status, DNS records and the publication it shows.
+Read custom domains without running a DNS check. With `type`, `namespace` and `id` (`GET /api/publications/{html|site}/{ns}/{id}/domain`; a profile token or an owner token added to the profile) or with `hostname` (`GET /api/domains/{hostname}`; admin profile token): the status, problem, DNS records and next step of that one custom domain. Without an address (`GET /api/domains`; admin profile token): every custom domain of the profile, plus how many are used and allowed.
+
+Parameters: optional `type` + `namespace` + `id`, or `hostname`; `ownerToken` (optional, default `BREWPAGE_OWNER_TOKEN`, local server only).
 
-Parameters: `ownerToken` (admin token of the profile; optional, default `BREWPAGE_OWNER_TOKEN`, local server only).
+```
+list_domains(type="html", namespace="public", id="aBcDeFgHiJ")
+```
 
 ---
 
 ### `check_domain`
 
-Check DNS now and return the updated status and records. By publication: `type`, `namespace`, `id` with an owner token in the profile (`POST /api/publications/{html|site}/{ns}/{id}/domain/check`). By hostname: `hostname` with an admin token of the profile (`POST /api/domains/{hostname}/check`). Checks are spaced: a repeat too soon answers 429 and the result prints `Retry-After`.
+Run a DNS check now and return the updated status and records. One check after the records exist is enough: BrewPage keeps checking on its own, and `list_domains` reads the status without a check. By publication: `type`, `namespace`, `id` with a profile token or an owner token added to the profile (`POST /api/publications/{html|site}/{ns}/{id}/domain/check`). By hostname: `hostname` with an admin profile token (`POST /api/domains/{hostname}/check`). A repeat within seconds answers 429 and the result prints `Retry-After`.
 
 Parameters: either `type` + `namespace` + `id`, or `hostname`; `ownerToken` (optional).
 
@@ -584,9 +595,9 @@ The four page-data tools below take `namespace` + `id` + `ownerToken`, or `manag
 
 ### `get_guide`
 
-Read a short reference text. Topic `page-data`: how a page saves what visitors enter, with the script calls and the `state` settings. Meant to be read before writing such a page. No API call.
+Read a short reference text. Topic `page-data`: how a page saves what visitors enter, with the script calls, the `state` settings, the owner view and how to try the page locally before publishing. Meant to be read before writing such a page. Topic `custom-domain`: the steps that put a page or site on a domain you own, with the statuses and the fix for each problem. No API call.
 
-Parameters: `topic` (`page-data`).
+Parameters: `topic` (`page-data` | `custom-domain`).
 
 ---
 
@@ -693,7 +704,8 @@ get_limits()
 | "List my published pages" / "What did I publish?" | `search_gallery` | Set `mine=true` + `ownerToken` |
 | "Browse the public BrewPage gallery" | `search_gallery` | Optional `q`, `sort=date\|views` |
 | "Put this page on my own domain" | `set_domain` | Owner token in a free profile; returns the DNS records to create |
-| "I added the DNS records, is my domain live?" | `check_domain` | Status `pending_dns` -> `verifying` -> `active` |
+| "I added the DNS records" | `check_domain` | Once; status `pending_dns` -> `verifying` -> `active` |
+| "Is my domain live yet?" | `list_domains` | With `type`, `namespace`, `id`: reads the status without a new check |
 | "Which domains do I have?" | `list_domains` | Admin token of the profile |
 | "Disconnect my domain" | `remove_domain` | The BrewPage link keeps working |
 | "Make a page with a guestbook / form / poll that saves answers" | `get_guide`, then `publish_html` | Publish with `state`; give the user the page link and the management link |
@@ -757,6 +769,14 @@ Every publish response includes an **owner token** -- the only credential that a
 
 ## Changelog
 
+## 1.23.0 -- 2026-11-14
+
+- Page data guide (`get_guide` topic `page-data`) regenerated from BrewPage's new Browser SDK text: build, try locally, publish. It adds the local preview (a page opened from disk or localhost keeps entries in that browser and sends nothing: `s.local`, `?bp-local=owner`, `?bp-local=off`; the same file works unchanged once published with `state`) and the owner view (`s.role`, `s.onRole`, `list({all: true})`, `removeById`, error `not_owner`). Custom domains: 400 `DOMAIN_NOT_REGISTERED` and the notice `domain-not-registered` name the next step (buy the domain from a registrar first, or check its spelling); the `NOT_ELIGIBLE` reasons `EXPIRED` and `MODE` name the server's next step; the `DOMAIN_TAKEN` and `CHECK_PAUSED` problem texts follow the site. `ttlDays` states the contract. Thirty-two tools. Contract 2.36.0. `User-Agent: brewpage-mcp/1.23.0`.
+
+## 1.22.0 -- 2026-11-12
+
+- Custom domains: the texts now lead to a connected domain. A refusal names its next step (an owner token in no profile: sign in at https://account.brewpage.app/tokens, press Add existing token, paste it, repeat); results give the DNS records step (mail records stay, a same-name A, AAAA or CNAME is replaced, Cloudflare Proxy status DNS only), one `check_domain`, then status reads until `active`; the `Problem:` line names the fix; status `lost` is described. `list_domains` takes an optional `type` + `namespace` + `id` or `hostname` and reads that one custom domain without a DNS check; without them it lists the profile as before. `get_guide` adds the topic `custom-domain`. Thirty-two tools. Contract 2.28.0. `User-Agent: brewpage-mcp/1.22.0`.
+
 ## 1.21.0 -- 2026-11-12
 
 - Remote mode only: optional `GET /metrics` with usage counts for the operator (calls per tool, Claude, ChatGPT or other clients, distinct clients per day), served only to the addresses in `BREWPAGE_METRICS_CIDRS`. No addresses, arguments or content are kept or shown. Tools, inputs and stdio are unchanged: thirty-two tools, contract 2.27.0. `User-Agent: brewpage-mcp/1.21.0`.

package/dist/guides/custom-domain.d.ts

@@ -0,0 +1,4 @@
+/** Custom-domain statuses: the "Statuses (`status`):" table under "## Custom Domains" of llms-full.txt. */
+export declare const DOMAIN_STATUSES: Record<string, string>;
+/** Custom-domain problems and fixes: the "Problems (`problem`) and the fix:" table of the same section; rows with a <placeholder> key left out. */
+export declare const DOMAIN_PROBLEMS: Record<string, string>;

package/dist/guides/custom-domain.js

@@ -0,0 +1,26 @@
+// Generated by scripts/sync-guide.mjs from brewpage-app frontend/src (llms-full.txt); do not hand-edit.
+/** Custom-domain statuses: the "Statuses (`status`):" table under "## Custom Domains" of llms-full.txt. */
+export const DOMAIN_STATUSES = {
+    "pending_dns": "DNS records not seen yet: create them; `problem` names the missing one",
+    "verifying": "DNS records found, HTTPS being issued: wait",
+    "active": "live at `url` (`serving: true`)",
+    "lost": "DNS records broke after going live; still served until `graceEndsAt`: restore them, then check",
+};
+/** Custom-domain problems and fixes: the "Problems (`problem`) and the fix:" table of the same section; rows with a <placeholder> key left out. */
+export const DOMAIN_PROBLEMS = {
+    "DOMAIN_NOT_REGISTERED": "the domain does not exist yet: register it with a domain registrar, then create the records",
+    "TXT_MISSING": "create the TXT record of `records[]`",
+    "TXT_WRONG": "a `bp-verify=` TXT record has another value: replace it with the one in `records[]`",
+    "ROUTING_MISSING": "create the CNAME record (apex: the A or ALIAS record)",
+    "ROUTING_WRONG": "the name points elsewhere: replace its A or CNAME record (Cloudflare: DNS only)",
+    "FOREIGN_AAAA": "delete the AAAA record listed in `records[]`",
+    "CAA_BLOCKS": "add the CAA record listed in `records[]`",
+    "DOMAIN_TAKEN": "this hostname is not available: use another hostname or write to info@brewpage.app",
+    "QUEUE_FULL": "DNS records are right, verification waits its turn: nothing to do",
+    "CERT_PENDING": "HTTPS certificate on its way: nothing to do",
+    "CERT_FAILED": "the certificate could not be issued: check the DNS records, then check again",
+    "DNS_LOST": "DNS records stayed broken past `graceEndsAt`, so the domain was disconnected: restore them, then check again",
+    "CHECK_PAUSED": "automatic checks paused, records not right a week after adding: fix DNS, then check again (resumes them)",
+    "RESOLVER_UNAVAILABLE": "DNS did not answer: retried automatically",
+    "PUBLICATION_GONE": "the publication is gone: connect the custom domain to another one",
+};

package/dist/guides/page-data.d.ts

@@ -1,4 +1,4 @@
 /** Page data cheat-sheet: the text block under "## Page data" -> "### Browser SDK" of llms-full.txt. */
 export declare const PAGE_DATA_GUIDE: string;
-/** Page script call shapes: the "bp.state() -> s|null" line of llms.txt. */
+/** Page script call shapes: the "bp.state() -> s|null" line of llms-full.txt. */
 export declare const PAGE_DATA_CALLS = "bp.state() -> s|null (guard it); c=s.col(\"name\"); c.set(key,value) c.get(key) c.remove(key) c.add(value) c.list({order,limit}) c.stats({countBy})";

package/dist/guides/page-data.js

@@ -1,53 +1,48 @@
-// Generated by scripts/sync-guide.mjs from brewpage-app frontend/src (llms-full.txt, llms.txt); do not hand-edit.
+// Generated by scripts/sync-guide.mjs from brewpage-app frontend/src (llms-full.txt); do not hand-edit.
 /** Page data cheat-sheet: the text block under "## Page data" -> "### Browser SDK" of llms-full.txt. */
 export const PAGE_DATA_GUIDE = [
-    "BrewPage page data (the `state` API): a published page saves data on BrewPage. No keys, no backend.",
-    "1) Publish with a \"state\" field (POST /api/html JSON body; multipart field \"state\" on /api/sites):",
-    "   {\"content\":\"<!doctype html>...\",\"state\":{\"collections\":{",
-    "     \"saves\":{\"mode\":\"private\"},",
-    "     \"votes\":{\"mode\":\"private\",\"choices\":{\"choice\":[\"a\",\"b\",\"c\"]}},",
-    "     \"guestbook\":{\"mode\":\"shared\",\"maxDocsPerVisitor\":5},",
-    "     \"scores\":{\"mode\":\"shared\",\"index\":\"score\",\"maxDocsPerVisitor\":1},",
-    "     \"menu\":{\"mode\":\"shared\",\"write\":\"author\"}}}}",
-    "   The page gets its own address https://<label>.brewpage.app. Saving needs a declared \"state\" and that address (or its custom domain).",
-    "   Raw-HTML publishes cannot carry state: use the JSON body, or PATCH /api/{ns}/{id}/state afterwards.",
-    "2) Include before your code (absolute URL, classic script, no async, no import):",
-    "   <script src=\"https://brewpage.app/js/state.js\"></script>",
-    "3) Use, inside an async function (top-level return/await break a classic script):",
-    "   async function start() {",
-    "     const s = await bp.state();             // null if unavailable; reason in bp.state.reason + console",
-    "     if (!s) return showNote(\"Saving is not available on this page right now.\"); // always guard; the page keeps working",
-    "     const saves = s.col(\"saves\");",
-    "     await saves.set(\"slot1\", {level: 3});   // own doc; key A-Za-z0-9_.- (not starting with _), <=128",
-    "     const game = await saves.get(\"slot1\");  // value or null",
-    "     await saves.remove(\"slot1\");            // true if it existed",
-    "     await s.col(\"guestbook\").add({text: input.value}); // random key",
-    "     const docs = await s.col(\"guestbook\").list({order: \"-createdAt\", limit: 20}); // array; docs.next = cursor or null",
-    "     for (const d of docs) { const li = document.createElement(\"li\"); li.append(bp.text(d.value.text)); ul.append(li); }",
-    "     await s.col(\"scores\").list({order: \"-index\", limit: 10});",
-    "     await s.col(\"votes\").stats({countBy: \"choice\"}); // {count, by: {a, b, c, other}}",
-    "     await s.col(\"menu\").get(\"today\");       // write:\"author\" docs: visitors read",
-    "   }",
-    "   start();",
-    "   bp.storage.ready.then(() => bp.storage.setItem(\"k\", \"v\")); // localStorage-like, synced, one doc; works where s is null",
-    "Modes: private (own docs only; default) | shared (all read, own write) | shared + write:\"author\" (author writes via API/MCP).",
-    "Collection names: a-z, 0-9, _ and -, start with a letter, <=32 chars, <=32 collections.",
-    "One thing per visitor (vote, RSVP, best score): use a fixed key such as \"me\".",
-    "Writes run in call order; save on change or submit, not on every keystroke.",
-    "Errors reject with e.code (e.message explains): rate_limited (e.retryAfter), quota, too_large, value_refused, mode_forbidden,",
-    "  challenge_cancelled, challenge_failed, challenge_unavailable, not_found, invalid_argument, network, unavailable, error.",
-    "BrewPage may ask a visitor for a quick human check before saving; the SDK shows it and retries.",
-    "  If your page sets a Content-Security-Policy, allow https://challenges.cloudflare.com (script-src, frame-src).",
-    "Limits: 16 KiB per doc (maxDocBytes up to 64 KiB); per visitor 20 docs, 32 KiB, 30 writes/min; list <= 100; data lives as long as the page.",
-    "Identity: one cookie per visitor per page; another browser or cleared cookies = new visitor.",
-    "bp.state() is null: without \"state\", on brewpage.app/... path addresses (needs_subdomain; unavailable in the brewpage.app viewer),",
-    "  in frames on other sites (embedded), with cookies off and outside BrewPage (file://, localhost, chat previews).",
-    "  Test the published link.",
-    "Privacy: the author reads all visitors' data (Data tab, API). Tell visitors: \"What you enter is saved on BrewPage and can be read by this page's author.\"",
+    "BrewPage Page data (API word `state`): a published page saves what visitors enter. No backend, no key in page code; not KV/JSON (your own data).",
+    "1) Build. Before your code (absolute URL, classic script, no async/import): <script src=\"https://brewpage.app/js/state.js\"></script>",
+    "bp.state() -> s|null (guard it); c=s.col(\"name\"); c.set(key,value) c.get(key) c.remove(key) c.add(value) c.list({order,limit}) c.stats({countBy})",
+    "  async function start() { // no top-level await/return",
+    "    const s = await bp.state(); // null -> reason in bp.state.reason, console",
+    "    if (!s) return showNote(\"Saving is not available on this page right now.\"); // always guard",
+    "    const book = s.col(\"guestbook\");",
+    "    await book.add({text: input.value}); // random key",
+    "    const docs = await book.list({order: \"-createdAt\", limit: 20}); // [{key, id, value, mine, createdAt}], .next|null -> list({cursor})",
+    "    for (const d of docs) ul.append(bp.text(d.value.text));",
+    "    const v = s.col(\"votes\");",
+    "    await v.set(\"me\", {choice: \"a\"}); // key A-Za-z0-9_.-, no leading _, <=128; \"me\" = one per visitor",
+    "    await v.get(\"me\"); // value or null; remove(key) -> true if it existed",
+    "    await v.stats({countBy: \"choice\"}); // {count, by: {a, b, other}}",
+    "  }",
+    "  start();",
+    "  bp.storage.ready.then(() => bp.storage.setItem(\"k\", \"v\")); // localStorage-like, synced; works where s is null",
+    "2) state (in the publish body, not the page): {} = all lists private (visitor sees own entries). Name a list to change its rule:",
+    "  {\"collections\":{\"guestbook\":{\"mode\":\"shared\",\"maxDocsPerVisitor\":5}}} = all read, each writes own",
+    "  \"scores\":{\"mode\":\"shared\",\"index\":\"score\",\"maxDocsPerVisitor\":1} -> list({order: \"-index\"})",
+    "  \"votes\":{\"choices\":{\"choice\":[\"a\",\"b\"]}} -> stats, other values count as other",
+    "  \"menu\":{\"mode\":\"shared\",\"write\":\"author\"} = visitors read, author writes (Owner API, MCP)",
+    "  List names a-z0-9_- (letter first, <=32 chars), <=32 lists. A private list never turns shared: new name.",
+    "3) Owner view: s.role is \"owner\" where the page shows its owner gear, else \"visitor\"; s.onRole(fn(role)) runs now and on change.",
+    "  Owner: c.list({all: true}) = all entries + d.visitor label (paged like list); c.removeById(entry.id). No secrets in page.",
+    "4) Test locally: open from disk or http(s)://localhost, 127.0.0.1, [::1], *.localhost: bp.state() = local preview, s.local === true,",
+    "  console \"[BrewPage] Local preview\". Kept in this browser, nothing sent; clear: localStorage.removeItem(\"__bp_state_local\").",
+    "  One visitor; checks and limits as published, e.status 0. Not applied: state rules, rate limits, human check, cookies.",
+    "  ?bp-local=owner = owner view, ?bp-local=off = off. Same file works unchanged once published with state.",
+    "5) Publish: POST https://brewpage.app/api/html, Content-Type: application/json, body {\"content\":\"<html>...\",\"state\":{...}}; sites: multipart field \"state\".",
+    "  Raw HTML body cannot carry state (or PATCH /api/{ns}/{id}/state later). Own address https://<label>.brewpage.app (or custom domain).",
+    "  Give the user the page link (`link`) and the management link (`manageUrl`, private; Data tab shows entries).",
+    "  On the published link: one save works and shows in the Data tab; each list behaves as declared.",
+    "6) Errors: e.code: rate_limited (e.retryAfter), quota, too_large, value_refused, mode_forbidden, not_owner, challenge_cancelled,",
+    "  challenge_failed, challenge_unavailable, not_found, invalid_argument, network, unavailable, error.",
+    "  Own CSP: allow https://challenges.cloudflare.com (script-src, frame-src).",
+    "7) Limits: 16 KiB per entry; per visitor 20 entries, 32 KiB, 30 writes/min; list <= 100.",
+    "  Visitor = one cookie per browser per page. Save on change or submit.",
+    "  null: no \"state\", brewpage.app/... paths (needs_subdomain), frames on other sites (embedded), cookies off, chat previews.",
+    "8) Tell visitors: \"What you enter is saved on BrewPage and can be read by this page's author.\"",
     "  Shared lists: \"Your message is public: everyone who opens this page can read it.\"",
-    "Never collect passwords, card numbers or other credentials. Entries are text and numbers.",
-    "Author API (owner token or management key): GET/PATCH /api/{ns}/{id}/state, GET /api/{ns}/{id}/state/{col}?format=csv.",
-    "After publishing, give the user the page link and the management link (private); its Data tab shows the entries.",
+    "  Never collect passwords, card numbers or other credentials. Render entries as text (bp.text), never innerHTML.",
 ].join("\n") + "\n";
-/** Page script call shapes: the "bp.state() -> s|null" line of llms.txt. */
+/** Page script call shapes: the "bp.state() -> s|null" line of llms-full.txt. */
 export const PAGE_DATA_CALLS = "bp.state() -> s|null (guard it); c=s.col(\"name\"); c.set(key,value) c.get(key) c.remove(key) c.add(value) c.list({order,limit}) c.stats({countBy})";

package/dist/tools.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/server";
 export declare const DEFAULT_BASE_URL = "https://brewpage.app";
-export declare const USER_AGENT = "brewpage-mcp/1.21.0";
+export declare const USER_AGENT = "brewpage-mcp/1.23.0";
 export declare const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export declare const SERVER_INSTRUCTIONS: string;

package/dist/tools.js

@@ -1,8 +1,9 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
+import { DOMAIN_PROBLEMS, DOMAIN_STATUSES } from "./guides/custom-domain.js";
 import { PAGE_DATA_CALLS, PAGE_DATA_GUIDE } from "./guides/page-data.js";
 export const DEFAULT_BASE_URL = "https://brewpage.app";
-export const USER_AGENT = "brewpage-mcp/1.21.0";
+export const USER_AGENT = "brewpage-mcp/1.23.0";
 export const OWNER_TOKEN_ENV = "BREWPAGE_OWNER_TOKEN";
 /** Server instructions of the handshake: one paragraph per line; the first stands alone within 512 chars. */
 export const SERVER_INSTRUCTIONS = [
@@ -10,6 +11,7 @@ export const SERVER_INSTRUCTIONS = [
     "After publishing, give the user the page link and the management link from the result. Say that the management link is private: whoever has it can edit or delete the page, and its Data tab shows what visitors saved.",
     "KV and JSON tools hold your own data. Page data holds what a page's visitors save: get_page_data reads it, set_page_data writes author entries, configure_page_data changes who can read a list, delete_page_data moderates. In a later chat these four take the management link as manageUrl.",
     "HTML pages and sites show a small BrewPage badge; page code must not hide or alter it. A profile can turn it off on up to 5 pages (set_badge).",
+    "A custom domain, only when the user asks for their own domain: set_domain, the user creates the returned DNS records at their DNS provider, check_domain once, then list_domains reads the status until it is active. Steps and fixes: get_guide topic custom-domain.",
 ].join("\n");
 const READ_ONLY = { readOnlyHint: true };
 const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true };
@@ -198,32 +200,67 @@ function configuredListLine(name, named, before, after) {
     return after.mode === "shared" ? `${name} - ${listRuleText(after)} (was private)`
         : `${name} - ${listRuleText(after)} (was shared; it cannot become shared again while it holds visitors' entries)`;
 }
-const DOMAIN_PROFILE_TEXT = "Works when the owner token is in a free BrewPage profile (sign-in at https://account.brewpage.app); free, 5 domains per profile.";
-const DOMAIN_ADDRESS_TEXT = "Addressed by publication (type, namespace, id; an owner token in the profile) or by hostname (an admin token of the profile).";
-const DOMAIN_OWNER_TOKEN = `Owner token in a BrewPage profile: the publication's own token added to the profile, or a profile token. Default: ${ENV_DEFAULT}.`;
-const DOMAIN_EITHER_TOKEN = `By publication: an owner token in the profile. By hostname: an admin token of the profile. Default: ${ENV_DEFAULT}.`;
-const DOMAIN_ADDRESS_ERROR = "Provide either `hostname` (admin token of the profile) or `type`, `namespace` and `id` (an owner token in the profile).";
-const DOMAIN_ARGUMENT = "Optional domain the user owns (www.example.com or example.com) to connect to the new publication. " +
-    "Works when the owner token is in a free BrewPage profile, without a password. The publication is always created; " +
-    "the result lists the DNS records for the domain owner to create, or says why the domain was not set.";
-/** Plain words for `DomainItem.problem`; other codes print bare. */
-const DOMAIN_PROBLEMS = {
-    TXT_MISSING: "the TXT record is not visible yet",
-    TXT_WRONG: "the TXT record has another value",
-    ROUTING_MISSING: "the CNAME or A record is not visible yet",
-    ROUTING_WRONG: "the CNAME or A record points elsewhere",
-    FOREIGN_AAAA: "an AAAA record points elsewhere: delete it",
-    CAA_BLOCKS: "a CAA record stops the HTTPS certificate: add the CAA record listed",
-    DOMAIN_TAKEN: "this hostname is not available",
-    QUEUE_FULL: "DNS is right; the next step is queued and retried automatically",
-    CERT_PENDING: "the HTTPS certificate is on its way",
-    CERT_FAILED: "the HTTPS certificate was not issued: check DNS, then check again",
-    DNS_LOST: "the records stayed broken: restore them, then check again",
-    CHECK_PAUSED: "automatic checks are paused; a check resumes them",
-    RESOLVER_UNAVAILABLE: "DNS did not answer; retried automatically",
-    PUBLICATION_GONE: "the publication is gone: set the domain on another one",
+const DOMAIN_TOKENS_PAGE = "https://account.brewpage.app/tokens";
+const DOMAIN_PROFILE_TEXT = `Free with a BrewPage profile, up to 5 custom domains: a profile token works at once, an owner token after it is added to a profile (sign-in at ${DOMAIN_TOKENS_PAGE}, "Add existing token").`;
+const DOMAIN_PROVIDER_TEXT = "Any registrar or DNS host works; if the user is buying a domain, Cloudflare and Porkbun are the quickest to set up.";
+const DOMAIN_ADDRESS_TEXT = "Addressed by publication (type, namespace, id; a profile token or an owner token added to the profile) or by hostname (an admin profile token).";
+const DOMAIN_OWNER_TOKEN = `A profile token, or the publication's owner token added to a BrewPage profile. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_EITHER_TOKEN = `By publication: a profile token or an owner token added to the profile. By hostname: an admin profile token. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_LIST_TOKEN = `Whole list or by hostname: an admin profile token. By publication: a profile token or an owner token added to the profile. Default: ${ENV_DEFAULT}.`;
+const DOMAIN_ADDRESS_ERROR = "Provide either `hostname` (an admin profile token) or `type`, `namespace` and `id` (a profile token or an owner token added to the profile).";
+const DOMAIN_HOSTNAME = "Custom domain as a bare hostname, e.g. www.example.com; instead of type, namespace and id";
+const DOMAIN_ARGUMENT = "Optional custom domain for the new publication: a bare hostname the user owns (www.example.com or example.com, no scheme or path). " +
+    "Needs a profile token or an owner token added to a free BrewPage profile, and no password. The publication is always created; " +
+    "the result lists the DNS records for the domain owner to create, or says why the custom domain was not set.";
+/** Status sentence of the check_domain description; names every key of DOMAIN_STATUSES. */
+const DOMAIN_STATUS_TEXT = "Status: pending_dns (DNS records not seen yet), verifying (DNS records found, HTTPS being issued), active (live), " +
+    "lost (DNS records broke after going live; still served until `graceEndsAt`; restored records and one more check bring it back). `problem` names the fix.";
+/** Next step per `reason` of 409 NOT_ELIGIBLE and per `NOT_ELIGIBLE_<reason>` problem. */
+const DOMAIN_REASONS = {
+    OWNERSHIP: `add its owner token to the profile (bind_token with an admin profile token, or "Add existing token" at ${DOMAIN_TOKENS_PAGE})`,
+    OLD: "it is an old publication: publish it again and connect the custom domain to the new one",
+    RETIRED: "its address was retired: connect the custom domain to a live publication",
+    TYPE: "only HTML pages and sites can",
+    FORMAT: "the page is not format html: publish it as format html",
+    PASSWORD: "remove the password (management link, or POST /api/{html|sites}/{ns}/{id}/password {\"password\":null})",
+    EXPIRED: "it has expired: extend it, or connect the custom domain to another publication",
+    MODE: "it is not on its own subdomain: set the domain on it again (set_domain with the same hostname), which moves it to its own subdomain",
 };
-const DOMAIN_NEXT_CREATE = "Next: ask the user to add exactly these records at their DNS provider and change nothing else (keep MX/email records); `host` is the name DNS panels ask for. Then call check_domain. BrewPage also checks on its own and issues HTTPS automatically.";
+const DOMAIN_READ_STATUS = "read the status with list_domains (same type, namespace and id, or hostname)";
+const DOMAIN_NEXT_CREATE = "Next: give the user exactly these DNS records to create at their DNS provider (`host` is the name DNS panels ask for). " +
+    "MX/mail records stay; an A, AAAA or CNAME record at the same name is replaced. When the user says the records exist, call check_domain once, then " +
+    DOMAIN_READ_STATUS + " until it is active: BrewPage checks on its own (first full check about 15 minutes after adding), " +
+    "usually live within 30 minutes, HTTPS is automatic. Call check_domain again only after a DNS change.";
+const DOMAIN_NEXT_VERIFYING = "Next: DNS records are found and HTTPS is being issued. To follow it, " + DOMAIN_READ_STATUS +
+    " until it is active; call check_domain again only if the Problem line says so or DNS changed.";
+const DOMAIN_NEXT_LOST = "Next: DNS records broke after going live. Ask the user to restore exactly these DNS records at their DNS provider, then call check_domain once.";
+const DOMAIN_SUSPENDED_TEXT = "BrewPage suspended this custom domain: the user writes to info@brewpage.app; repeating a call does not help.";
+/** Custom-domain guide: the flow in tool words, then the status and problem tables generated from llms-full.txt. */
+const CUSTOM_DOMAIN_GUIDE = [
+    "BrewPage custom domain: a hostname the user owns (example.com, docs.example.com) shows one HTML page of format html or one site, without a password. Only when the user asks for their own domain.",
+    `Who: ${DOMAIN_PROFILE_TEXT}`,
+    "  403 DOMAIN_NEEDS_ACCOUNT = the owner token is in no profile: give the user the owner token (it is theirs) to add there, then repeat the call. With an admin profile token bind_token adds it instead.",
+    `Domain: ${DOMAIN_PROVIDER_TEXT}`,
+    "Steps:",
+    "1) set_domain (type, namespace, id, hostname), or `domain` on publish_html / publish_site. The hostname is bare: www.example.com or example.com, no scheme or path.",
+    "2) Give the user exactly the DNS records of the result to create at their DNS provider (`host` is the name DNS panels ask for); never values from memory.",
+    "   MX/mail records stay; an A, AAAA or CNAME record at the same name is replaced. At Cloudflare set Proxy status to DNS only.",
+    "3) When the user says the records exist: check_domain once.",
+    "4) Read the status with list_domains (type, namespace, id) until it is active. BrewPage checks on its own (first full check about 15 minutes after adding);",
+    "   usually live within 30 minutes, HTTPS is issued automatically. check_domain again only after a DNS change; on 429 wait Retry-After and read instead.",
+    "Statuses (`Status:` line of a result):",
+    ...Object.entries(DOMAIN_STATUSES).map(([status, text]) => `  ${status} - ${text}`),
+    "Problems (`Problem:` line) and the fix:",
+    ...Object.entries(DOMAIN_PROBLEMS).map(([problem, fix]) => `  ${problem} - ${fix}`),
+    "  NOT_ELIGIBLE_<reason> - the publication cannot take a custom domain now; the line names the fix",
+    "A refusal names its next step. The BrewPage link keeps working throughout. set_domain with the same hostname on another publication of the profile moves it; remove_domain removes it.",
+].join("\n") + "\n";
+/** `Problem:` value: the code plus its fix (generated table, or the reason of a `NOT_ELIGIBLE_<reason>` code); other codes print bare. */
+function domainProblemText(problem) {
+    const reason = problem.startsWith("NOT_ELIGIBLE_") ? DOMAIN_REASONS[problem.slice("NOT_ELIGIBLE_".length)] : undefined;
+    const fix = reason ? `the publication cannot take a custom domain now: ${reason}` : DOMAIN_PROBLEMS[problem];
+    return fix ? `${problem} (${fix})` : problem;
+}
 /** One custom domain (`DomainItem`): status, `records[]` verbatim and the next step. */
 function domainLines(item) {
     const { hostname, displayHostname, problem, url } = item;
@@ -233,7 +270,7 @@ function domainLines(item) {
         `Status: ${item.status}`,
     ];
     if (typeof problem === "string" && problem)
-        lines.push(`Problem: ${problem}${DOMAIN_PROBLEMS[problem] ? ` (${DOMAIN_PROBLEMS[problem]})` : ""}`);
+        lines.push(`Problem: ${domainProblemText(problem)}`);
     lines.push(`Serving: ${item.serving === true}`);
     if (item.suspended === true)
         lines.push(`suspended: true`);
@@ -247,7 +284,7 @@ function domainLines(item) {
         lines.push(`The publication moved to its own BrewPage subdomain (a custom domain needs it); its BrewPage link keeps working.`);
     if (typeof item.detached === "string" && item.detached)
         lines.push(`Earlier domain ${item.detached} stays in the profile, not attached.`);
-    for (const [field, label] of [["checkedAt", "Checked"], ["nextCheckAt", "Next automatic check"], ["graceEndsAt", "Shown until"]]) {
+    for (const [field, label] of [["checkedAt", "Checked"], ["nextCheckAt", "Next automatic check"], ["graceEndsAt", "Served until (graceEndsAt)"]]) {
         if (typeof item[field] === "string")
             lines.push(`${label}: ${item[field]}`);
     }
@@ -259,44 +296,88 @@ function domainLines(item) {
     if (item.provider === "cloudflare")
         lines.push(`Cloudflare: Proxy status "DNS only" on the CNAME or A record.`);
     if (item.suspended === true)
-        return lines;
+        return [...lines, DOMAIN_SUSPENDED_TEXT];
+    if (problem === "DOMAIN_NOT_REGISTERED")
+        lines.push(DOMAIN_PROVIDER_TEXT);
+    // The DNS provider is unknown until a check names it, so the Cloudflare rule travels with the step.
     if (item.status === "pending_dns")
-        lines.push(DOMAIN_NEXT_CREATE);
+        lines.push(DOMAIN_NEXT_CREATE + (typeof item.provider === "string" && item.provider ? "" : " At Cloudflare set Proxy status to DNS only."));
     if (item.status === "verifying")
-        lines.push(`Next: DNS is found and HTTPS is being issued. Call check_domain again shortly.`);
+        lines.push(DOMAIN_NEXT_VERIFYING);
     if (item.status === "active")
-        lines.push(`Live: the domain shows the publication over HTTPS. The BrewPage link keeps working.`);
+        lines.push(`Live: the custom domain shows the publication over HTTPS. The BrewPage link keeps working.`);
     if (item.status === "lost")
-        lines.push(`Next: DNS changed after going live. Ask the user to restore exactly these records at their DNS provider, then call check_domain.`);
+        lines.push(DOMAIN_NEXT_LOST);
     return lines;
 }
-/** Create with `domain`: the returned `customDomain`, else a line saying it was not set (the reason is a `domain-*` notice). */
-function publishDomainLines(data, requested) {
+/** 403 `DOMAIN_NEEDS_ACCOUNT` and its create notice: the profile step in the user's hands, then `then`. */
+function domainNeedsProfile(fromEnv, then) {
+    return `The owner token is in no BrewPage profile. Give the user the owner token (it is theirs${fromEnv ? `; it is the ${OWNER_TOKEN_ENV} value in this server's settings` : ""}) ` +
+        `and ask them to sign in at ${DOMAIN_TOKENS_PAGE} (free), press "Add existing token" and paste it; then ${then}. With an admin profile token bind_token adds it instead.`;
+}
+const DOMAIN_LIMIT_NEXT = "remove_domain frees one; a hostname already in the profile moves here with set_domain.";
+/** 400 `DOMAIN_NOT_REGISTERED` and its create notice; the caller appends the call to make next. */
+const DOMAIN_NOT_REGISTERED_NEXT = "The domain is not registered yet: ask the user to buy it from a domain registrar first (BrewPage does not sell domains), or check its spelling;";
+/** 409 `DOMAIN_PROFILE_AMBIGUOUS` and its create notice; `then` = the call to make with the profile token. */
+function domainAmbiguous(then) {
+    return `The token is in several profiles: ${then} with a profile token of the profile that should hold the custom domain (minted at ${DOMAIN_TOKENS_PAGE}).`;
+}
+/** Next step per `domain-*` notice of a create; other codes point at the notice text. */
+function publishDomainNext(code, fromEnv) {
+    if (code === "domain-needs-account")
+        return ` ${domainNeedsProfile(fromEnv, "call set_domain for this publication")}`;
+    if (code === "domain-limit-reached")
+        return ` Next: ${DOMAIN_LIMIT_NEXT}`;
+    if (code === "domain-profile-ambiguous")
+        return ` ${domainAmbiguous("call set_domain")}`;
+    if (code === "domain-not-eligible" || code === "domain-invalid")
+        return " The domain notice above says what to fix; then set_domain connects it.";
+    if (code === "domain-not-registered")
+        return ` ${DOMAIN_NOT_REGISTERED_NEXT} then set_domain connects it.`;
+    if (code === "domain-account-restricted")
+        return " The domain notice above says why.";
+    return " The domain notice above says why. set_domain connects it later.";
+}
+/** Create with `domain`: the returned `customDomain`, else a line saying it was not set plus the next step of its `domain-*` notice. */
+function publishDomainLines(data, requested, fromEnv = false) {
     const item = data.customDomain;
     if (item && typeof item === "object")
         return [``, `CUSTOM DOMAIN`, ...domainLines(item)];
     if (!requested)
         return [];
-    const reason = notices(data).some((n) => n.code.startsWith("domain-")) ? " The domain notice above says why." : "";
-    return [``, `CUSTOM DOMAIN: ${requested} was not set; the publication is live at its BrewPage link.${reason} set_domain connects it later.`];
+    const notice = notices(data).find((n) => n.code.startsWith("domain-"));
+    return [``, `CUSTOM DOMAIN: ${requested} was not set; the publication is live at its BrewPage link.` +
+            (notice ? publishDomainNext(notice.code, fromEnv) : " set_domain connects it later.")];
 }
-/** Next step after a custom-domain refusal; other codes keep the server answer alone. */
-function domainHints(data, byHostname) {
-    const { code, limit, used } = (data ?? {});
-    if (code === "DOMAIN_NEEDS_ACCOUNT") {
-        return ["Custom domains need a free BrewPage account: sign in at https://account.brewpage.app and add this token to your profile (bind_token), then retry."];
+/** Next step after a custom-domain refusal; `address` = how the call named the domain. Other codes keep the server answer alone. */
+function domainHints(data, address, fromEnv = false) {
+    const { code, limit, used, reason } = (data ?? {});
+    switch (code) {
+        case "DOMAIN_NEEDS_ACCOUNT": return [domainNeedsProfile(fromEnv, "repeat this call")];
+        case "DOMAIN_LIMIT": return typeof limit === "number" && limit > 0
+            ? [`The profile uses ${typeof used === "number" ? used : limit} of ${limit} custom domains: ${DOMAIN_LIMIT_NEXT}`] : [];
+        case "ADMIN_TOKEN_REQUIRED": return ["This call needs an admin profile token." + (address === "publication" ? ""
+                : " With a publish-scope profile token or an owner token added to the profile, pass type, namespace and id" + (address === "hostname" ? " instead of hostname." : "."))];
+        case "DOMAIN_CHECK_TOO_SOON": return [`Checked a moment ago: do not call check_domain again now. BrewPage keeps checking on its own; after Retry-After ${DOMAIN_READ_STATUS}.`];
+        case "DOMAIN_NOT_FOUND": return ["No custom domain there: list_domains shows the profile's custom domains; set_domain connects one."];
+        case "INVALID_HOSTNAME": return ["Pass one bare hostname such as www.example.com or example.com (no scheme, path or port); the message says what to fix."];
+        case "DOMAIN_NOT_ALLOWED": return ["brewpage.app addresses and some domains cannot be used: ask the user for a domain they own."];
+        case "DOMAIN_NOT_REGISTERED": return [`${DOMAIN_NOT_REGISTERED_NEXT} then repeat this call.`];
+        case "NOT_ELIGIBLE": return typeof reason === "string" && DOMAIN_REASONS[reason] ? [`This publication cannot take a custom domain: ${DOMAIN_REASONS[reason]}.`] : [];
+        case "DOMAIN_PROFILE_AMBIGUOUS": return [domainAmbiguous("repeat")];
+        case "OWNER_TOKEN_REVOKED":
+        case "OWNER_TOKEN_EXPIRED":
+            return [`The token ${code === "OWNER_TOKEN_REVOKED" ? "was revoked" : "expired"}: repeat with another profile token or the publication's owner token.`];
+        case "ACCOUNT_RESTRICTED":
+        case "ACCOUNT_BLOCKED":
+            return [`This profile cannot add custom domains${code === "ACCOUNT_RESTRICTED" ? " now" : ""}: tell the user; repeating the call does not help.`];
+        case "DOMAIN_SUSPENDED": return [DOMAIN_SUSPENDED_TEXT];
+        case "PUBLICATION_UNAVAILABLE": return ["The publication is missing or expired (outside public a wrong token answers the same): check type, namespace, id and the token."];
+        case "FEATURE_DISABLED":
+        case "DOMAIN_INTAKE_PAUSED":
+        case "HOSTING_CREATION_PAUSED": return ["Temporary: tell the user and try again later."];
+        default: return [];
     }
-    if (code === "DOMAIN_LIMIT" && typeof limit === "number" && limit > 0) {
-        return [`The profile uses ${typeof used === "number" ? used : limit} of ${limit} custom domains: remove_domain frees one; a hostname already in the profile moves here with set_domain.`];
-    }
-    if (code === "ADMIN_TOKEN_REQUIRED") {
-        return ["Custom domains need an admin token from a free BrewPage profile." + (byHostname ? " With an owner token of the publication, pass type, namespace and id instead of hostname." : "")];
-    }
-    if (code === "DOMAIN_CHECK_TOO_SOON")
-        return ["Checked a moment ago: wait, then call check_domain again."];
-    if (code === "DOMAIN_NOT_FOUND")
-        return ["No custom domain there: list_domains shows the profile's domains; set_domain connects one."];
-    return [];
 }
 /** `/api/<segments>` with each segment encoded; empty, `.` and `..` refused (URL parsing would resolve them away). */
 export function apiPath(...segments) {
@@ -415,8 +496,8 @@ const SITE_NAMESPACE_DESCRIPTION = PUBLIC_NAMESPACE_LEAD + "A site always gets i
 /** `namespace` for publish_json and publish_kv: data is never listed. */
 const DATA_NAMESPACE_DESCRIPTION = "Omit (default): private. namespace=public: the shared public namespace. JSON and KV are never listed in the gallery " +
     "or indexed, in any namespace; anyone who has the link can open it. " + NAMESPACE_FORMAT;
-const TTL_SCHEMA = z.union([z.number().positive(), z.string().min(1).max(32)]).optional().describe("Requested TTL: days as a number, or a string such as '2w', '36h' or '1 month' (default 15 days). " +
-    "The server rounds to whole days and clamps to the allowed range (1-30; up to 90 with an owner token in a profile), reporting each adjustment in notices; the returned expiresAt is the actual expiry.");
+const TTL_SCHEMA = z.union([z.number().positive(), z.string().min(1).max(32)]).optional().describe("TTL in days: up to 30 days without an account, up to 90 with a free profile (pass an ownerToken held in the profile); " +
+    "a default applies when omitted. Accepts whole days: 15, '15d', '15 days'. The returned expiresAt is the actual expiry.");
 const DELIVERY_MODE_SCHEMA = z.enum(["path", "subdomain"]).optional().describe("Optional delivery choice for a fresh publication, independent of password/namespace. " +
     "Fresh sites and HTML-format pages outside public (including the default unlisted namespace) always use subdomain; an explicit path there still publishes, on subdomain, with a delivery notice. " +
     "Everything else in any namespace (Markdown, code/text, files, JSON, KV, public HTML) defaults to path (Promotion); public HTML may automatically choose subdomain for browser features. " +
@@ -518,7 +599,7 @@ export function createServer(options = {}) {
     const apiFetch = options.fetch ?? fetch;
     const server = new McpServer({
         name: "brewpage-mcp",
-        version: "1.21.0",
+        version: "1.23.0",
     }, { instructions: SERVER_INSTRUCTIONS });
     /** Caller argument first, then the configured default; `fromEnv` marks the configured one. */
     function ownerTokenFor(argument) {
@@ -584,7 +665,7 @@ export function createServer(options = {}) {
             lines.push(`Expires: ${data.expiresAt}`);
         lines.push(...hostingResponseLines(data));
         lines.push(...pageDataPublishLines(data, sentState));
-        lines.push(...publishDomainLines(data, requestedDomain));
+        lines.push(...publishDomainLines(data, requestedDomain, sentOwnerToken !== undefined && sentOwnerToken === defaultOwnerToken));
         lines.push(...ownerTokenLines(data, "update or delete this resource later", sentOwnerToken));
         lines.push(...ownerLinkLines(data));
         const ns = (data.namespace ?? effectiveNamespace) || "";
@@ -599,7 +680,7 @@ export function createServer(options = {}) {
             "Format order: `format`, then a known filename extension, else the server detects it. Returns its primary share link and owner token. Optional password, TTL, filename, top toolbar (showTopBar). " +
             "A `public` page without deliveryMode may get its own subdomain if it needs browser features a BrewPage link lacks; " +
             "the result then has deliveryModeReason and a delivery notice. Markdown raw HTML is allowlisted: scripts, styles, event handlers, forms, embeds removed. " +
-            "Optional `domain` connects a domain the user owns to an HTML-format page. " +
+            "Optional `domain` connects a custom domain the user owns to an HTML-format page. " +
             MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
         inputSchema: {
             content: z.string().describe("HTML, Markdown, code or JSON to publish"),
@@ -863,7 +944,7 @@ export function createServer(options = {}) {
         ...toolMeta("Publish site", ADDITIVE),
         description: "Publish an HTML site to BrewPage. " + PUBLIC_HINT + "Single-page: `entryContent`. Multi-page: `files` (`{path, content}` array). Optional `entry` overrides `index.html`. Returns its primary share link and owner token. " +
             "Static only: HTML, CSS, JS (incl. built React/Vue bundles) run in the browser; server code (PHP etc.) never runs. " + SITE_LIMITS_TEXT +
-            " Optional `domain` connects a domain the user owns. " + MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
+            " Optional `domain` connects a custom domain the user owns. " + MANAGE_URL_TEXT + " " + SECRETS + " " + BADGE_TEXT + " " + PUBLISH_STATE_TEXT,
         inputSchema: {
             deliveryMode: DELIVERY_MODE_SCHEMA,
             entryContent: z
@@ -969,7 +1050,7 @@ export function createServer(options = {}) {
             lines.push(`Expires: ${site.expiresAt}`);
         lines.push(...hostingResponseLines(site));
         lines.push(...pageDataPublishLines(site, sentState?.value));
-        lines.push(...publishDomainLines(site, domain || undefined));
+        lines.push(...publishDomainLines(site, domain || undefined, owner !== undefined && owner === defaultOwnerToken));
         lines.push(...ownerTokenLines(site, "view info or delete this site", owner));
         lines.push(...ownerLinkLines(site));
         const ns = (site.namespace || effectiveNamespace) || "";
@@ -1636,15 +1717,18 @@ export function createServer(options = {}) {
     }
     server.registerTool("set_domain", {
         ...toolMeta("Connect custom domain", ADDITIVE),
-        description: "Connect a domain the user owns (www.example.com or example.com) to one HTML page or site. " + DOMAIN_PROFILE_TEXT +
-            " Returns the DNS records for the domain owner to create at their DNS provider: TXT for ownership plus CNAME, or A/ALIAS for a root domain. " +
-            "A DNS check after that moves the status pending_dns -> verifying -> active; HTTPS is issued automatically. " +
-            "HTML pages of format html and sites, without a password. A hostname already in the profile moves to this publication. The BrewPage link keeps working.",
+        description: "Connect a custom domain (a hostname the user owns) to one HTML page of format html or one site, without a password. " + DOMAIN_PROFILE_TEXT +
+            " Returns the DNS records for the domain owner to create at their DNS provider exactly as returned: MX/mail records stay, " +
+            "an A, AAAA or CNAME record at the same name is replaced, at Cloudflare Proxy status is DNS only. " +
+            "One DNS check after the records exist is enough: BrewPage keeps checking on its own (first full check about 15 minutes after adding); " +
+            "usually live within 30 minutes, HTTPS is automatic. Status: pending_dns -> verifying -> active (lost when the DNS records break later); `problem` names the fix. " +
+            "A hostname already in the profile moves to this publication; the BrewPage link keeps working. " + DOMAIN_PROVIDER_TEXT +
+            " Steps and fixes: guide topic `custom-domain`.",
         inputSchema: {
             type: z.enum(["html", "site"]).describe("Publication type"),
             namespace: z.string().describe("Publication namespace"),
             id: z.string().describe("Publication ID"),
-            hostname: z.string().describe("Domain or subdomain the user owns, e.g. www.example.com or example.com"),
+            hostname: z.string().describe("Bare hostname the user owns: www.example.com or example.com, no scheme or path"),
             ownerToken: z.string().optional().describe(DOMAIN_OWNER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1654,23 +1738,40 @@ export function createServer(options = {}) {
         const path = apiPath("publications", type, namespace, id, "domain");
         const { ok, status, data, headers: answerHeaders } = await apiRequest("PUT", path, { hostname }, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("set domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, false));
-        const lead = status === 201 ? "Custom domain connected." : "Custom domain set: it was already in the profile (moved here or unchanged).";
+            return ownerFailure("set domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, "publication", auth.fromEnv));
+        const lead = status === 201 ? "Custom domain added. It is not live until the DNS records below exist."
+            : "Custom domain set: it was already in the profile (moved here or unchanged).";
         return textResult([lead, ``, ...domainLines(data)].join("\n"));
     });
     server.registerTool("list_domains", {
         ...toolMeta("List custom domains", READ_ONLY),
-        description: "List the custom domains of a BrewPage profile: status, DNS records and the publication each one shows, plus how many the profile holds and may hold. Needs an admin token of the profile.",
+        description: "Read custom domains without running a DNS check: status, `problem`, DNS records and the publication shown. " +
+            "No address: every custom domain of the profile plus how many it holds and may hold. With type, namespace and id, or with hostname: that one custom domain.",
         inputSchema: {
-            ownerToken: z.string().optional().describe(`Admin token of the profile. Default: ${ENV_DEFAULT}.`),
+            type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
+            namespace: z.string().optional().describe("Publication namespace"),
+            id: z.string().optional().describe("Publication ID"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
+            ownerToken: z.string().optional().describe(DOMAIN_LIST_TOKEN),
         },
-    }, async ({ ownerToken }) => {
+    }, async ({ type, namespace, id, hostname, ownerToken }) => {
         const auth = ownerTokenFor(ownerToken);
         if (!auth.token)
             return textResult(NO_OWNER_TOKEN, true);
+        // An empty string reads as an omitted argument: the list stays reachable for a client that fills every field.
+        const [kind, ns, row, host] = [type, namespace, id, hostname].map((part) => part || undefined);
+        if ([kind, ns, row, host].some((part) => part !== undefined)) {
+            const path = domainPath(kind, ns, row, host);
+            if (path === null)
+                return textResult(DOMAIN_ADDRESS_ERROR, true);
+            const { ok, status, data, headers: answerHeaders } = await apiRequest("GET", path, undefined, { "X-Owner-Token": auth.token });
+            if (!ok)
+                return ownerFailure("read domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, host !== undefined ? "hostname" : "publication", auth.fromEnv));
+            return textResult(domainLines(data).join("\n"));
+        }
         const { ok, status, data, headers: answerHeaders } = await apiRequest("GET", "/api/domains", undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("list domains", status, data, auth.fromEnv, answerHeaders, domainHints(data, false));
+            return ownerFailure("list domains", status, data, auth.fromEnv, answerHeaders, domainHints(data, "list", auth.fromEnv));
         const list = data;
         const items = Array.isArray(list.items) ? list.items : [];
         const lines = [`Custom domains: ${list.used} of ${list.limit} used`];
@@ -1682,14 +1783,15 @@ export function createServer(options = {}) {
     });
     server.registerTool("check_domain", {
         ...toolMeta("Check custom domain DNS", ADDITIVE),
-        description: "Check the DNS of a custom domain now and return its status and records. Status: pending_dns (records not seen yet), " +
-            "verifying (DNS found, HTTPS being issued), active (live). " + DOMAIN_ADDRESS_TEXT +
-            " Checks are spaced: a repeat too soon answers 429 with Retry-After.",
+        description: "Run a DNS check of a custom domain now and return its status, `problem` and DNS records. " +
+            "One check after the DNS records exist is enough: BrewPage keeps checking on its own (`nextCheckAt`) and reading the status needs no check; " +
+            "another check fits only after a DNS change. " + DOMAIN_STATUS_TEXT + " " + DOMAIN_ADDRESS_TEXT +
+            " A repeat within seconds answers 429 with Retry-After.",
         inputSchema: {
             type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
             namespace: z.string().optional().describe("Publication namespace"),
             id: z.string().optional().describe("Publication ID"),
-            hostname: z.string().optional().describe("Custom domain, e.g. www.example.com; instead of type, namespace and id"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
             ownerToken: z.string().optional().describe(DOMAIN_EITHER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1701,18 +1803,18 @@ export function createServer(options = {}) {
             return textResult(DOMAIN_ADDRESS_ERROR, true);
         const { ok, status, data, headers: answerHeaders } = await apiRequest("POST", path, undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("check domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined));
+            return ownerFailure("check domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined ? "hostname" : "publication", auth.fromEnv));
         return textResult([`DNS checked.`, ``, ...domainLines(data)].join("\n"));
     });
     server.registerTool("remove_domain", {
         ...toolMeta("Remove custom domain", DESTRUCTIVE),
         description: "Remove a custom domain from the profile: it stops showing the publication and its slot is free at once. The BrewPage link keeps working. " +
-            DOMAIN_ADDRESS_TEXT + " DNS records at the provider stay until the domain owner deletes them.",
+            DOMAIN_ADDRESS_TEXT + " DNS records at the DNS provider stay until the domain owner deletes them.",
         inputSchema: {
             type: z.enum(["html", "site"]).optional().describe("Publication type; with namespace and id, instead of hostname"),
             namespace: z.string().optional().describe("Publication namespace"),
             id: z.string().optional().describe("Publication ID"),
-            hostname: z.string().optional().describe("Custom domain, e.g. www.example.com; instead of type, namespace and id"),
+            hostname: z.string().optional().describe(DOMAIN_HOSTNAME),
             ownerToken: z.string().optional().describe(DOMAIN_EITHER_TOKEN),
         },
     }, async ({ type, namespace, id, hostname, ownerToken }) => {
@@ -1724,7 +1826,7 @@ export function createServer(options = {}) {
             return textResult(DOMAIN_ADDRESS_ERROR, true);
         const { ok, status, data, headers: answerHeaders } = await apiRequest("DELETE", path, undefined, { "X-Owner-Token": auth.token });
         if (!ok)
-            return ownerFailure("remove domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined));
+            return ownerFailure("remove domain", status, data, auth.fromEnv, answerHeaders, domainHints(data, hostname !== undefined ? "hostname" : "publication", auth.fromEnv));
         const what = hostname !== undefined ? `Custom domain removed: ${hostname}` : `No custom domain on ${type} ${namespace}/${id} now`;
         return textResult(`${what} · slot free · BrewPage link unchanged\nIts DNS records can be deleted at the DNS provider.`);
     });
@@ -1933,10 +2035,11 @@ export function createServer(options = {}) {
         ...toolMeta("Read BrewPage guide", READ_ONLY),
         description: "Short reference texts for building on BrewPage. Topic `page-data`: how a published page saves what visitors enter " +
             "(forms, guestbook, votes, leaderboard, game progress) with the script `https://brewpage.app/js/state.js` and the `state` config; " +
-            "meant to be read before writing such a page.",
+            "meant to be read before writing such a page. Topic `custom-domain`: the steps that put a page or site on a domain the user owns " +
+            "(profile, DNS records, one check, statuses, problems and fixes).",
         inputSchema: {
-            topic: z.enum(["page-data"]).describe("Guide topic"),
+            topic: z.enum(["page-data", "custom-domain"]).describe("Guide topic"),
         },
-    }, async () => textResult(PAGE_DATA_GUIDE + PAGE_DATA_GUIDE_TAIL));
+    }, async ({ topic }) => textResult(topic === "custom-domain" ? CUSTOM_DOMAIN_GUIDE : PAGE_DATA_GUIDE + PAGE_DATA_GUIDE_TAIL));
     return server;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brewpage-mcp",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "mcpName": "io.github.kochetkov-ma/brewpage-mcp",
   "description": "MCP server for BrewPage — publish and manage HTML, sites, KV, JSON and files from AI assistants",
   "type": "module",