@phenomenalorg/mcp 0.3.0 → 0.5.0

package/README.md

@@ -92,6 +92,18 @@ habits that go with them: call `list_my_orgs` before anything else, draft →
 preview → publish, never confirm a send on its own initiative, keep member
 details out of anything public.
 
+For page authoring, read `phenomenal://instructions` and call
+`get_page_authoring_state` first: canonical content and revisions define the
+edit. Use `preview_page_changes` with `DRAFT`, then `save_page_changes` to save
+content and its document Look together privately. Read the canonical state
+back after saving. Page-wide CSS belongs to Looks; preserve enabled-language
+HTML and unrelated blocks when changing appearance or making a targeted edit.
+
+Publication is separate: review a fresh `PUBLISH` preview, then call
+`publish_page` with its exact required review receipt only after explicit human
+confirmation. Saving a draft does not publish it. The generated skill and tool
+references describe the current inputs and review requirements.
+
 ```bash
 npx @phenomenalorg/mcp --skill .claude/skills   # install it into a project
 npx @phenomenalorg/mcp --skill                  # install into ./.claude/skills if it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenomenalorg/mcp",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Phenomenal MCP bridge — connects a stdio-only MCP client to the Phenomenal MCP server over Streamable HTTP, with browser sign-in.",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "open": "^11.0.0"
   },
   "devDependencies": {
+    "@ptopro/mcp-tools": "workspace:*",
     "@types/node": "^22.10.0",
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"

package/skill/SKILL.md

@@ -8,24 +8,26 @@ description: Use when the user wants to manage a PTO, school or club in Phenomen
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 39 tools · 163 actions · 5 prompts · fingerprint `5dc7363e`._
+_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
 
 You are connected to Phenomenal, the platform for this PTO's site, members, events, tickets, email, forms, store and money.
 
 Start with list_my_orgs. Every organization id comes from it; never guess or invent one. Name the selected organization; ask if ambiguous.
 
-Say whether you are drafting, saving or publishing. draft_page saves nothing. draft_broadcast saves a draft and returns its id; it sends nothing. update_page_draft saves privately. publish_page publishes; send_broadcast sends to families.
+Say when you are previewing, saving or publishing. Page Looks previews and Cancel write nothing; save_page_changes/update_page_draft stay private. draft_broadcast saves a draft but sends nothing. Only publish/send reaches an audience.
 
 For any tool with confirm, first call WITHOUT confirm. Present the returned action, target and effect to the user, then END THE TURN. Wait for a NEW explicit user message approving that exact preview; only then use confirm: true for the same action/target. The initial request and client/native tool-permission approval do not approve a later preview. Never self-confirm. “Nothing has happened yet” is a successful no-effect preview, not an error or retry signal.
 
 Mail and money are one-way. Slow down before sending, refunding or paying out.
 
-Keep member names, addresses and form answers in your answer to the officer; never copy them into public pages or broadcasts. Write US English, plainly and warmly, for parents on phones. On FORBIDDEN, explain the role limit and stop; never hunt for another route.
+Keep member names, addresses and form answers in your answer to the officer, never on public pages or broadcasts. Write warm, plain US English for parents on phones. On FORBIDDEN, explain the role limit and stop.
 
-Publish a page: list_pages → get_page → draft_page → update_page_draft (saved privately) → preview publish_page → ask → publish_page with confirm: true.
+Looks are the default for new page-wide styling: get_page_authoring_state → DRAFT preview → save_page_changes (private) → get_page_authoring_state to read the canonical save → PUBLISH preview → publish_page. Use complete content and exact revisions/digests; legacy tools remain compatible.
 
 For other work: list_mutations → describe_mutation → run_mutation. Read arguments; never guess. query_graphql is read-only.
 
+Custom HTML supports scoped styles, gradients, animations and static email fallback. Before authoring CSS, read the complete grammar and working example in references/starting-doc.md or phenomenal://instructions. Save privately and inspect validated stored HTML.
+
 ## Worked sequences
 
 Draft the weekly newsletter for my organization (call list_my_orgs first): org_overview → list_events for the next three weeks → list_pages → draft_broadcast. Report the saved draft and audience; use US English for parents. If a test is requested: send_broadcast_test without confirm → present its action/target/effect → end the turn → wait for a NEW explicit user message approving that preview → confirm the same action/target. Repeat the entire sequence separately for send_broadcast; test approval never approves the full send.

package/skill/references/mutations.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 39 tools · 163 actions · 5 prompts · fingerprint `5dc7363e`._
+_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
 
 The curated tools in `references/tools.md` cover the work an officer does most days. Everything else Phenomenal can do is reachable by name:
 
@@ -213,9 +213,11 @@ Areas: account, brand, broadcasts, connections, domains, drive, email-preference
 - `generateBlockImage` — Generate an image for one content block from an instruction.
 - `generateSitePages` **(confirm)** — Generate and publish a set of starter pages for the site from a description.
 - `movePage` — Change a page's URL slug.
-- `publishPage` **(confirm)** — Prefer the `publish_page` tool. Publish a page draft to the live site.
+- `previewDocumentLook` — Prefer `preview_page_changes`.
+- `publishPage` **(confirm)** — Prefer the `publish_page` tool. Publish a page draft to its configured audience on the live site.
 - `renamePage` — Change a page's title, optionally for one language only.
 - `rewriteBlockText` — Rewrite one content block's text from a plain-language instruction.
+- `saveDocumentWithLook` — Prefer `save_page_changes`.
 - `setPageEditPolicy` **(confirm)** — Set who may edit a page — organization admins, or a group's stewards too.
 - `setPageGroupSlug` — Change a page's path segment underneath its group.
 - `setPageMediaAudience` **(confirm)** — Change who can see the images on a page.

package/skill/references/schema.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 39 tools · 163 actions · 5 prompts · fingerprint `5dc7363e`._
+_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
 
 Two tools answer questions no curated tool anticipated.
 

package/skill/references/starting-doc.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 39 tools · 163 actions · 5 prompts · fingerprint `5dc7363e`._
+_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
 
 Phenomenal runs a school's PTO: its public website, its member roster, its events and tickets, its email to families, its forms, its store and its money. It exposes all of that over the Model Context Protocol, so an assistant an officer already uses can do the work with them.
 
@@ -59,18 +59,20 @@ You are connected to Phenomenal, the platform for this PTO's site, members, even
 
 Start with list_my_orgs. Every organization id comes from it; never guess or invent one. Name the selected organization; ask if ambiguous.
 
-Say whether you are drafting, saving or publishing. draft_page saves nothing. draft_broadcast saves a draft and returns its id; it sends nothing. update_page_draft saves privately. publish_page publishes; send_broadcast sends to families.
+Say when you are previewing, saving or publishing. Page Looks previews and Cancel write nothing; save_page_changes/update_page_draft stay private. draft_broadcast saves a draft but sends nothing. Only publish/send reaches an audience.
 
 For any tool with confirm, first call WITHOUT confirm. Present the returned action, target and effect to the user, then END THE TURN. Wait for a NEW explicit user message approving that exact preview; only then use confirm: true for the same action/target. The initial request and client/native tool-permission approval do not approve a later preview. Never self-confirm. “Nothing has happened yet” is a successful no-effect preview, not an error or retry signal.
 
 Mail and money are one-way. Slow down before sending, refunding or paying out.
 
-Keep member names, addresses and form answers in your answer to the officer; never copy them into public pages or broadcasts. Write US English, plainly and warmly, for parents on phones. On FORBIDDEN, explain the role limit and stop; never hunt for another route.
+Keep member names, addresses and form answers in your answer to the officer, never on public pages or broadcasts. Write warm, plain US English for parents on phones. On FORBIDDEN, explain the role limit and stop.
 
-Publish a page: list_pages → get_page → draft_page → update_page_draft (saved privately) → preview publish_page → ask → publish_page with confirm: true.
+Looks are the default for new page-wide styling: get_page_authoring_state → DRAFT preview → save_page_changes (private) → get_page_authoring_state to read the canonical save → PUBLISH preview → publish_page. Use complete content and exact revisions/digests; legacy tools remain compatible.
 
 For other work: list_mutations → describe_mutation → run_mutation. Read arguments; never guess. query_graphql is read-only.
 
+Custom HTML supports scoped styles, gradients, animations and static email fallback. Before authoring CSS, read the complete grammar and working example in references/starting-doc.md or phenomenal://instructions. Save privately and inspect validated stored HTML.
+
 ## Worked sequences
 
 Draft the weekly newsletter for my organization (call list_my_orgs first): org_overview → list_events for the next three weeks → list_pages → draft_broadcast. Report the saved draft and audience; use US English for parents. If a test is requested: send_broadcast_test without confirm → present its action/target/effect → end the turn → wait for a NEW explicit user message approving that preview → confirm the same action/target. Repeat the entire sequence separately for send_broadcast; test approval never approves the full send.
@@ -83,6 +85,37 @@ Month-end money for my organization (call list_my_orgs first): payout_status →
 
 ## Reference
 
+### Custom HTML styles
+
+Use a Look by default for new page-wide styling. A Look supplies sparse design-token overrides and optional bounded CSS; omitted tokens inherit the organization base. Existing block-local HTML <style> islands remain supported, stay with their blocks and are scoped independently. Do not automatically relocate either stylesheet into the other layer or use the legacy island editor as the default way to author a page Look.
+
+Keep each HTML locale as a complete localized value such as props.html.en and props.html.es. Preserve element structure, links, media provenance, class names, ids and keyframe names while translating visible copy. Author ordinary local class/id/keyframe names only: Phenomenal applies its own instance scopes. Look CSS and HTML CSS share the supported selector, motion, URL and composition safety limits described below, including the 16,384-byte Look CSS ceiling.
+
+Choosing a shared Look uses its key; an owned Look carries its complete value and optional copiedFrom provenance; base removes the page override. Use picker values only for presentation. Revisions and the effect-bound previewDigest bind the exact reviewed input; actual server permissions remain the authority and are rechecked by every resolver. Preview and Cancel are zero-write, save_page_changes remains a private draft, and only a separately reviewed and confirmed publish_page changes the public site.
+
+Custom HTML supports local <style> blocks in a leaf {id,type:"html",props:{html:{en:"…"}}} or a section with props.kind:"html". Prefer the same get_page_authoring_state → DRAFT preview → save_page_changes → canonical get_page_authoring_state read-back path for combined HTML-and-Look edits. Legacy update_page_draft and get_page remain compatible for existing island-only work. The server encodes local classes/IDs and binds CSS separately for each rendered instance. Never write runtime scope/keyframe IDs into stored content.
+
+CSS v1: element/class/ID compounds and comma lists; descendant and child (>) combinators; :hover, :focus, :focus-visible. No global/universal/attribute/sibling selectors, functional pseudos or pseudo-elements. Media queries are a single (min-width:Npx)/(max-width:Npx), N=240–2560, or (prefers-reduced-motion:reduce/no-preference). Existing approved inline typography, spacing, color, borders, table and flex/grid display rules also work in sheets. Linear gradients accept an optional -360–360deg angle; radial gradients an optional circle/ellipse. Both need 2–8 approved opaque named or 3/6-digit hex colors with optional ordered 0–100% stops. Background-position uses two 0–100% values; background-size uses two 100–400% values.
+
+Named local @keyframes animate transform/background-position only. Transform supports up to three distinct single-argument functions: translateX/Y ±16px, rotate ±5deg, scale 0.95–1.05. One animation per rule: shorthand or name/duration/delay/timing-function/iteration-count/direction/fill-mode longhands. Duration 0.2–30s, delay 0–5s, iterations 1–10 or infinite (at least 2s per cycle), linear/ease/ease-in/ease-out/ease-in-out, normal/reverse/alternate/alternate-reverse, none/forwards/backwards/both. Animation names are case-sensitive and must be defined in the same sheet. Transition shorthand supports transform or background-position, 0.1–2s and one of those easings. The site provides Pause/Resume and enforces reduced motion automatically; content stays readable.
+
+Block-local canonical stylesheet limits: 16,384 characters, 2,048 AST nodes, 64 ordinary rules, 32 declarations per rule, 8 selector arms and 8 compounds per arm, 8 keyframes with 2–16 stops and at most 4 motion declarations per stop. A Look's separate ceiling is 16,384 UTF-8 bytes. One media nesting layer. An unsupported or malformed HTML-island sheet is omitted as a whole while readable HTML remains; invalid Look CSS instead refuses preview/save and is never silently discarded as a valid Look save. No URLs/imports/font loading, custom properties, positioning, opacity, hiding, flashing, resource fetches or !important. Existing HTML/media URL and proposal provenance policies still apply. Web rendering retains scoped interactive/motion behavior. Email resolves static selector specificity, order, inline precedence and inheritance, then emits safe inline styles with solid gradient fallback; hover/media/motion effects are omitted. Email preview uses the actual email producer.
+
+Background-position keyframes use exactly two endpoints, from/0% and to/100%, over at least 2s; transform-only entrances may be shorter. The 16,384-character cap applies to canonical serialized CSS. Input/runtime transport allows 2MiB for encoded scope expansion; rescoping restores the same canonical budget. Email matching is capped at 200,000 memoized states per fragment; exhaustion preserves readable content and original inline styles without a partial cascade.
+
+CSS policy revision: html-scoped-css-v1.1.
+
+Font-family accepts an ordered comma list of at most 8 entries from serif, sans-serif, monospace, system-ui, arial, georgia, verdana only; no quoted/unknown fonts or font loading. Solid background accepts approved opaque named or 3/6-digit hex colors and canonicalizes to background-color, with last-declaration source order; it is a color alias, not general background layer/reset syntax. Example declarations: font-family:Georgia,serif;background:#ffffff;font-size:1rem. Font-size must be at least 12px, 1em/1rem or 100%; 0.95rem is rejected. Unsupported declarations reject the entire stylesheet, so inspect saved HTML rather than assuming generic validation means every style survived.
+
+Working localized HTML value (use its string as props.html.en; the volunteer link must match a real page in the target site):
+<style>
+.welcome{background:linear-gradient(90deg,#123456 0%,#345678 100%);background-size:200% 200%;background-position:0% 50%;color:white;padding:24px;border-radius:16px;animation:Welcome 6s linear infinite alternate}
+.welcome a{color:white;display:inline-block;padding:12px;border:1px solid white;border-radius:8px;transition:transform 0.2s ease}
+.welcome a:hover,.welcome a:focus-visible{transform:translateY(-4px)}
+@media (max-width:600px){.welcome{padding:16px}}
+@keyframes Welcome{from{background-position:0% 50%}to{background-position:100% 50%}}
+</style><section class="welcome"><h2>Welcome, families</h2><p>Make our school a wonderful place to grow.</p><a href="/volunteer">Find your volunteer moment</a></section>
+
 - https://phenomenal.org/agents/tools — every tool, its arguments, and whether it needs `confirm`.
 - https://phenomenal.org/agents/mutations — the `run_mutation` long tail, by area.
 - https://phenomenal.org/agents/schema — `query_graphql` and `get_schema`, and the limits they enforce.

package/skill/references/tools.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 39 tools · 163 actions · 5 prompts · fingerprint `5dc7363e`._
+_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
 
 Every tool the Phenomenal MCP server offers, in the order a client lists them. `list_my_orgs` is first because every other tool needs an organization id from it.
 
@@ -103,6 +103,49 @@ One page from Phenomenal with its current draft content, as the array of blocks
 
 - `pageId` (string, required) — From list_pages.
 
+### `get_page_authoring_state`
+
+Read the complete authorized page content, Looks appearance, revisions, actions and safe same-organization picker context before editing.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `pageId` (string, required) — The exact page id from get_page_authoring_state.
+
+### `preview_page_changes`
+
+Validate complete page content and a Look together without writing. DRAFT previews edits; PUBLISH previews the exact stored draft.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `pageId` (string, required) — The exact page id from get_page_authoring_state.
+- `expectedDocumentRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
+- `expectedThemeRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
+- `content` (object)
+- `lookChange` (any)
+- `effect` (string (DRAFT | PUBLISH)) — DRAFT by default. PUBLISH accepts no edits and previews stored state.
+
+### `save_page_changes`
+
+Save one previously previewed complete page-and-Look DRAFT atomically. It remains private and never publishes or retries.
+
+**Hints:** writes. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `pageId` (string, required) — The exact page id from get_page_authoring_state.
+- `expectedDocumentRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
+- `expectedThemeRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
+- `content` (object)
+- `lookChange` (any)
+- `previewDigest` (string, required) — Copy exactly from the matching VALID DRAFT preview.
+
 ### `draft_page`
 
 Draft content for a Phenomenal page from a plain-language instruction and return the blocks. It SAVES NOTHING — show the result to the person, then save it with update_page_draft. This counts against the organization's AI budget, exactly as drafting from the admin app does.
@@ -124,11 +167,11 @@ Save a page's draft in Phenomenal. Replaces the WHOLE draft, so send the full bl
 **Arguments**
 
 - `pageId` (string, required) — From list_pages.
-- `blocks` (array, required) — The page draft as an array of Phenomenal content blocks — objects with "id", "type" and "props". Replaces the whole draft, so read the current one with get_page and send it back changed. Plain text you send in a translatable prop comes back as {"en":"…"}; that is the site storing it per language, not your save failing.
+- `blocks` (array, required) — The page draft as an array of Phenomenal content blocks — objects with "id", "type" and "props". Replaces the whole draft, so read the current one with get_page and send it back changed. Plain text you send in a translatable prop comes back as {"en":"…"}; that is the site storing it per language, not your save failing. Read phenomenal://block-vocabulary for the generated property names of every leaf block and section kind.
 
 ### `publish_page`
 
-Publish a page's draft to the live Phenomenal site. Everyone can see it immediately, so this needs confirm: true.
+Publish a page's draft to its configured audience on the live Phenomenal site. This needs confirm: true.
 
 **Hints:** writes. **Confirm:** required — without it you get a preview and nothing changes.
 
@@ -136,6 +179,7 @@ Publish a page's draft to the live Phenomenal site. Everyone can see it immediat
 
 - `pageId` (string, required) — From list_pages.
 - `confirm` (boolean) — First call without confirm. Present the returned action, target and effect, END THE TURN, and wait for a NEW explicit user message approving that exact preview. Only then set true for the same action/target. Initial requests and client/native tool-permission approvals do not count.
+- `lookReview` (object)
 
 ### `unpublish_page`