@phenomenalorg/mcp 0.2.0 → 0.4.0

package/README.md

@@ -67,15 +67,16 @@ Point it somewhere else with a URL:
 ## Command line
 
 ```
-npx @phenomenalorg/mcp [<url>] [--url <url>] [--logout] [--version] [--help]
+npx @phenomenalorg/mcp [<url>] [--url <url>] [--skill [dir]] [--logout] [--version] [--help]
 ```
 
-| Flag        | What it does                                                          |
-| ----------- | --------------------------------------------------------------------- |
-| `--url`     | The Phenomenal MCP endpoint. Default `https://api.phenomenal.org/mcp` |
-| `--logout`  | Forget the saved sign-in for that server and exit                     |
-| `--version` | Print the version and exit                                            |
-| `--help`    | Print usage and exit                                                  |
+| Flag            | What it does                                                          |
+| --------------- | --------------------------------------------------------------------- |
+| `--url`         | The Phenomenal MCP endpoint. Default `https://api.phenomenal.org/mcp` |
+| `--skill [dir]` | Install the Phenomenal agent skill (see below)                        |
+| `--logout`      | Forget the saved sign-in for that server and exit                     |
+| `--version`     | Print the version and exit                                            |
+| `--help`        | Print usage and exit                                                  |
 
 Sign out of one server:
 
@@ -84,6 +85,29 @@ npx @phenomenalorg/mcp --logout
 npx @phenomenalorg/mcp --logout --url https://api.ph-dev.org/mcp
 ```
 
+## The agent skill
+
+Connecting gives your assistant the tools. The **skill** gives it the working
+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.
+
+```bash
+npx @phenomenalorg/mcp --skill .claude/skills   # install it into a project
+npx @phenomenalorg/mcp --skill                  # install into ./.claude/skills if it
+                                                # exists, else print SKILL.md
+```
+
+`--skill <dir>` writes a `phenomenal/` folder into the directory you name:
+`SKILL.md` plus `references/` — the full tool catalog, the `run_mutation` long
+tail, and how to read the GraphQL schema. An existing install is replaced; the
+skill is generated from the server's own tool registry, so there is nothing in
+it worth keeping across an update.
+
+For a client with no skills feature, point it at
+<https://phenomenal.org/agents> instead — the same briefing, plus the install
+recipes, as one plain-text page it can fetch.
+
 ## Where your sign-in is kept
 
 `~/.phenomenal/mcp/<server>.json`, one file per server, written `0600` inside a

package/dist/cli.d.ts

@@ -5,13 +5,18 @@ export interface CliOptions {
     logout: boolean;
     version: boolean;
     help: boolean;
+    /** `--skill` was given, with or without a directory. */
+    skill: boolean;
+    /** The directory named after `--skill`, or `null` for "decide for me". */
+    skillDir: string | null;
 }
 export declare class CliUsageError extends Error {
 }
 /**
- * `--url <u>`, `--url=<u>` or a bare positional URL; `--logout`, `--version`,
- * `--help`. Anything else is a usage error rather than a silently ignored
- * flag — an MCP client config typo should say so, not connect somewhere else.
+ * `--url <u>`, `--url=<u>` or a bare positional URL; `--skill [dir]`,
+ * `--logout`, `--version`, `--help`. Anything else is a usage error rather than
+ * a silently ignored flag — an MCP client config typo should say so, not
+ * connect somewhere else.
  */
 export declare function parseArgs(argv: readonly string[]): CliOptions;
 export declare function usage(version: string): string;

package/dist/cli.js

@@ -9,14 +9,16 @@ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/
 import { ensureAuthorized } from './auth.js';
 import { startBridge } from './bridge.js';
 import { clearSession, storePath } from './store.js';
+import { defaultInstallDir, installSkill, readSkillMarkdown } from './skill.js';
 import { readPackageVersion } from './version.js';
 export const DEFAULT_SERVER_URL = 'https://api.phenomenal.org/mcp';
 export class CliUsageError extends Error {
 }
 /**
- * `--url <u>`, `--url=<u>` or a bare positional URL; `--logout`, `--version`,
- * `--help`. Anything else is a usage error rather than a silently ignored
- * flag — an MCP client config typo should say so, not connect somewhere else.
+ * `--url <u>`, `--url=<u>` or a bare positional URL; `--skill [dir]`,
+ * `--logout`, `--version`, `--help`. Anything else is a usage error rather than
+ * a silently ignored flag — an MCP client config typo should say so, not
+ * connect somewhere else.
  */
 export function parseArgs(argv) {
     const options = {
@@ -24,6 +26,8 @@ export function parseArgs(argv) {
         logout: false,
         version: false,
         help: false,
+        skill: false,
+        skillDir: null,
     };
     let urlSeen = false;
     for (let i = 0; i < argv.length; i += 1) {
@@ -45,6 +49,24 @@ export function parseArgs(argv) {
             urlSeen = true;
             i += 1;
         }
+        else if (arg === '--skill') {
+            options.skill = true;
+            /**
+             * The directory is OPTIONAL, so the value is only consumed when the next
+             * argument is not itself a flag. `--skill --url x` has to keep meaning
+             * what it says; swallowing `--url` as a directory would install the skill
+             * into a folder called `--url` and then connect to the default server.
+             */
+            const value = argv[i + 1];
+            if (value !== undefined && !value.startsWith('-')) {
+                options.skillDir = value;
+                i += 1;
+            }
+        }
+        else if (arg.startsWith('--skill=')) {
+            options.skill = true;
+            options.skillDir = arg.slice('--skill='.length) || null;
+        }
         else if (arg.startsWith('--url=')) {
             options.url = validUrl(arg.slice('--url='.length));
             urlSeen = true;
@@ -77,10 +99,13 @@ export function usage(version) {
         `phenomenal-mcp ${version} — connect an MCP client to Phenomenal over stdio.`,
         '',
         'Usage:',
-        '  npx @phenomenalorg/mcp [<url>] [--url <url>] [--logout] [--version]',
+        '  npx @phenomenalorg/mcp [<url>] [--url <url>] [--skill [dir]] [--logout]',
         '',
         'Options:',
         `  --url <url>   The Phenomenal MCP endpoint (default ${DEFAULT_SERVER_URL})`,
+        '  --skill [dir] Install the Phenomenal skill into dir/phenomenal/. With no',
+        '                dir it installs into .claude/skills/ when that folder is',
+        '                already here, and prints SKILL.md to stdout otherwise.',
         '  --logout      Forget the saved sign-in for that server and exit',
         '  --version     Print the version and exit',
         '  --help        Print this and exit',
@@ -113,6 +138,9 @@ export async function run(argv, io = defaultIo) {
         io.out(version);
         return 0;
     }
+    if (options.skill) {
+        return installOrPrintSkill(options, io);
+    }
     if (options.logout) {
         const had = clearSession(options.url);
         io.err(had
@@ -130,6 +158,26 @@ export async function run(argv, io = defaultIo) {
     await handle.done;
     return 0;
 }
+/**
+ * `--skill`, in one place: install when a directory is known, print otherwise.
+ *
+ * The rule is "do the obvious thing and say what you did". A named directory is
+ * an explicit ask. An unnamed one installs only into a `.claude/skills/` that
+ * ALREADY exists — standing in a project that reads skills is itself the ask —
+ * and otherwise falls back to stdout, which writes nothing anywhere. Every
+ * branch reports its outcome on stderr, so nobody has to guess which one ran.
+ */
+function installOrPrintSkill(options, io) {
+    const target = options.skillDir ?? defaultInstallDir(process.cwd());
+    if (!target) {
+        io.out(readSkillMarkdown());
+        io.err('Printed the Phenomenal skill. Pass a directory to install it: --skill <dir>');
+        return 0;
+    }
+    const written = installSkill(target);
+    io.err(`Installed the Phenomenal skill into ${written}.`);
+    return 0;
+}
 // `import.meta.url` is the built dist/cli.js when npm runs the bin; the guard
 // keeps `run` importable from tests without starting a session.
 const invokedDirectly = process.argv[1] !== undefined && import.meta.url.endsWith('/cli.js');

package/dist/skill.d.ts

@@ -0,0 +1,21 @@
+/** The skill package inside this npm package. `dist/cli.js` → `../skill/`. */
+export declare function skillSourceDir(): string;
+/**
+ * The conventional skills directory of the project you are standing in.
+ *
+ * Only when it ALREADY exists. Creating `.claude/skills/` in whatever directory
+ * a person happened to be in would be a command that reshapes a project as a
+ * side effect of asking to read something.
+ */
+export declare function defaultInstallDir(cwd: string): string | null;
+/** `SKILL.md`, for printing. */
+export declare function readSkillMarkdown(): string;
+/**
+ * Copy the whole `phenomenal/` folder into a skills directory.
+ *
+ * The folder is named for the skill, not for the package, because that is what
+ * an Agent Skills client keys on. An existing install is overwritten: the skill
+ * is generated, so the copy on disk has no edits worth keeping, and a command
+ * that refused would leave people on a stale skill with no obvious way forward.
+ */
+export declare function installSkill(targetDir: string): string;

package/dist/skill.js

@@ -0,0 +1,45 @@
+/**
+ * `--skill`: hand the Phenomenal Agent Skill to a client that reads skills.
+ *
+ * The skill is generated from the server's own tool registry and copied into
+ * this package at build time (`scripts/copy-skill.mjs`), so what a customer
+ * installs on their laptop is the same text the server would have told the
+ * model — and nothing here reads the source repo at run time, because on a
+ * customer's machine there is no source repo.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The skill package inside this npm package. `dist/cli.js` → `../skill/`. */
+export function skillSourceDir() {
+    return fileURLToPath(new URL('../skill/', import.meta.url));
+}
+/**
+ * The conventional skills directory of the project you are standing in.
+ *
+ * Only when it ALREADY exists. Creating `.claude/skills/` in whatever directory
+ * a person happened to be in would be a command that reshapes a project as a
+ * side effect of asking to read something.
+ */
+export function defaultInstallDir(cwd) {
+    const candidate = join(cwd, '.claude', 'skills');
+    return existsSync(candidate) ? candidate : null;
+}
+/** `SKILL.md`, for printing. */
+export function readSkillMarkdown() {
+    return readFileSync(join(skillSourceDir(), 'SKILL.md'), 'utf8');
+}
+/**
+ * Copy the whole `phenomenal/` folder into a skills directory.
+ *
+ * The folder is named for the skill, not for the package, because that is what
+ * an Agent Skills client keys on. An existing install is overwritten: the skill
+ * is generated, so the copy on disk has no edits worth keeping, and a command
+ * that refused would leave people on a stale skill with no obvious way forward.
+ */
+export function installSkill(targetDir) {
+    const destination = resolve(targetDir, 'phenomenal');
+    mkdirSync(destination, { recursive: true });
+    cpSync(skillSourceDir(), destination, { recursive: true });
+    return destination;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenomenalorg/mcp",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -25,6 +25,7 @@
   },
   "files": [
     "dist",
+    "skill",
     "README.md"
   ],
   "exports": {
@@ -34,7 +35,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "build": "node scripts/copy-skill.mjs && tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
     "test": "pnpm run build && vitest run"
   },
@@ -43,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

@@ -0,0 +1,56 @@
+---
+name: phenomenal
+description: Use when the user wants to manage a PTO, school or club in Phenomenal — the public site and its pages, members and invites, events and tickets, announcements and email, forms, store and ticket orders, tasks, or asking what the organization already knows. Requires the Phenomenal MCP server to be connected.
+---
+
+# Phenomenal
+
+<!-- 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 `fef338e5`._
+
+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.
+
+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.
+
+Publish a page: list_pages → get_page → draft_page → update_page_draft (saved privately) → preview publish_page → ask → publish_page with confirm: true.
+
+For other work: list_mutations → describe_mutation → run_mutation. Read arguments; never guess. query_graphql is read-only.
+
+## 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.
+
+New event for my organization (call list_my_orgs first): . Ask for missing dates, location and ticket details. list_events → create_event → update_event for event details only. For tickets: list_mutations({ area: "events" }) → describe_mutation({ name: "createTicketType" }) → run_mutation with its exact input schema. For ticket changes, describe_mutation({ name: "updateTicketType" }) first. Leave the event unpublished; preview set_event_published and ask before confirming.
+
+Membership review for my organization (call list_my_orgs first): list_members (follow cursors) → list_groups → list_group_members. Report pending or suspended members and officer roles. Recommend changes but make none; keep names and addresses in your answer to me.
+
+Month-end money for my organization (call list_my_orgs first): payout_status → list_orders. Report holds, failures, possible refunds and available funds. Propose refund_ticket_order, cancel_order or start_payout only when needed; each needs its own preview and yes. Move no money yet.
+
+## References
+
+Read one of these when you need the detail, not before:
+
+- `references/tools.md` — every tool, its arguments, and whether it needs `confirm`.
+- `references/mutations.md` — the `run_mutation` long tail, by area.
+- `references/schema.md` — `query_graphql` and `get_schema`, and the limits they enforce.
+- `references/starting-doc.md` — this briefing plus the install recipes, as published online.
+
+Online: https://phenomenal.org/agents (and `https://phenomenal.org/agents/tools`, `/mutations`, `/schema`).
+
+## When this file and the server disagree
+
+This file is a copy. It ships separately from the server and can lag it.
+
+Read `phenomenal://instructions` and compare its `Tool surface fingerprint` with the fingerprint above. A different value means this copy is out of date: use the live instructions, schemas and confirmation requirements. If the resource has no fingerprint (an older server), freshness is unknown; inspect live tools and describe mutations before acting. This fingerprint is a compatibility hint, not an integrity check, and is not compared with the product version.
+
+`initialize` reports the live server's version as `serverInfo.version`, and `tools/list` reports exactly which tools it has — **those are the authority.** If a tool named here is missing from the live list, or the server offers one this file does not name, go by the live list and say plainly that your copy of the guide is out of date. Do not guess an argument, and do not invent a tool because this file mentions it.

package/skill/references/mutations.md

@@ -0,0 +1,247 @@
+# Phenomenal actions (the `run_mutation` long tail)
+
+<!-- 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 `fef338e5`._
+
+The curated tools in `references/tools.md` cover the work an officer does most days. Everything else Phenomenal can do is reachable by name:
+
+1. `list_mutations({ area, search })` — the index, filtered.
+2. `describe_mutation(name)` — the exact arguments, as a JSON Schema. **Read this; do not guess an argument name.**
+3. `run_mutation(name, input, confirm?)` — run it.
+
+Prefer a curated tool when one covers what you need: it is one call instead of three, and it resolves names for you.
+
+**(confirm)** marks an action that sends mail, moves money, publishes something publicly, deletes something, changes who can do what, or changes the organization's web address. Those change nothing until a person has said yes in words. Every action is subject to your role in the organization regardless; the confirm gate is about being asked, not about being allowed.
+
+Areas: account, brand, broadcasts, connections, domains, drive, email-preferences, events, forms, groups, knowledge, looks, media, meetings, members, money, orders, organization, pages, store, tasks, tickets.
+
+## account
+
+- `updateMyProfile` — Change your own name and preferred language.
+
+## brand
+
+- `activateBrandKit` **(confirm)** — Make a saved brand kit the organization's live one.
+- `createBrandKit` — Save a new brand kit for the organization.
+- `generateBrandKit` — Generate a brand kit from the school's existing website or logo.
+- `readSiteContent` — Read an existing website's pages so a brand kit or starter content can be built from them.
+- `updateBrandKit` — Replace a saved brand kit.
+
+## broadcasts
+
+- `createBroadcastDraft` — Prefer the `draft_broadcast` tool. Create an unsent email draft for the organization, with its audience.
+- `retryFailedDeliveries` **(confirm)** — Re-send a broadcast to the recipients whose delivery failed.
+- `sendBroadcast` **(confirm)** — Prefer the `send_broadcast` tool. Send a broadcast to its audience.
+- `sendBroadcastTest` **(confirm)** — Prefer the `send_broadcast_test` tool. Send one test copy of a broadcast to a single address.
+- `translateBroadcast` — Fill in a broadcast's missing translations for the organization's languages.
+- `updateBroadcastDraft` — Prefer the `draft_broadcast` tool. Replace an unsent broadcast draft, including its audience.
+
+## connections
+
+- `revokeAgentGrant` **(confirm)** — Disconnect an AI assistant this person connected to Phenomenal — possibly the one you are running in, which would end this conversation.
+
+## domains
+
+- `addDomain` **(confirm)** — Register a school-owned domain name for the organization and return the DNS records to publish.
+- `claimSubdomain` **(confirm)** — Claim a phenomenal.org web address for the organization.
+- `disableDomainSending` **(confirm)** — Stop sending email from a custom domain.
+- `refreshDomainSending` **(confirm)** — Re-check the DNS records for sending email from a custom domain and update its status.
+- `releaseSubdomain` **(confirm)** — Give up the organization's phenomenal.org web address.
+- `removeDomain` **(confirm)** — Remove a custom domain from the organization.
+- `startDomainSending` **(confirm)** — Start sending organization email from a custom domain and return the DKIM records to publish.
+- `verifyDomain` **(confirm)** — Advance a custom domain through verification — first ownership, then DNS.
+
+## drive
+
+- `disconnectGoogleDrive` — Disconnect the organization's Google Drive.
+- `exportDriveCsv` — Export a Google Drive spreadsheet as CSV text for import.
+- `importDriveFiles` — Import chosen Google Drive files into the knowledge base at a classification and scope.
+- `importDriveFolder` — Import a whole Google Drive folder into the knowledge base, optionally including subfolders.
+
+## email-preferences
+
+- `setMyEmailStream` — Change your own subscription to one of an organization's email streams.
+- `setMyPreferredLanguage` — Set the language you want Phenomenal to write to you in.
+- `unsubscribeMeFromOrg` — Unsubscribe yourself from all of an organization's email.
+
+## events
+
+- `createEvent` — Prefer the `create_event` tool. Create an event.
+- `createTicketType` — Add a ticket type (price, capacity) to an event.
+- `deleteEvent` **(confirm)** — Delete an event and its ticket types.
+- `deleteTicketType` **(confirm)** — Delete a ticket type from an event.
+- `setEventPublished` **(confirm)** — Prefer the `set_event_published` tool. Publish or unpublish an event.
+- `setEventVisibility` **(confirm)** — Set who can see an event — everyone, members, or one group.
+- `translateEvent` — Fill in an event's missing translations for the organization's languages.
+- `updateEvent` — Prefer the `update_event` tool. Change an event — time, place, description, page content.
+- `updateTicketType` — Change a ticket type's name, price, capacity or availability.
+
+## forms
+
+- `createForm` — Create a form (sign-ups, RSVPs, volunteer slots) as a draft.
+- `deleteForm` **(confirm)** — Delete a form.
+- `publishForm` **(confirm)** — Publish a form so people can fill it in.
+- `renameForm` — Change a form's title.
+- `setFormSubmissionStatus` — Mark a form submission new, in review, or handled.
+- `unpublishForm` **(confirm)** — Take a form off the site.
+- `updateFormDraft` — Replace a form draft.
+
+## groups
+
+- `createGroup` — Create a group — a class, a committee, a team.
+- `createGroupPage` — Create a group's own landing page.
+- `deleteGroup` **(confirm)** — Delete a group.
+- `joinGroup` — Join an open group yourself.
+- `leaveGroup` — Leave a group yourself.
+- `removeGroupMembership` **(confirm)** — Take a member out of one group.
+- `setGroupJoinPolicy` **(confirm)** — Set whether people can join a group themselves or only an admin can add them.
+- `setGroupMembership` **(confirm)** — Put a member in a group with a relation, or change the relation they are in it with.
+- `setGroupMemberStatus` **(confirm)** — Mark a member active or inactive in one group.
+- `setGroupMemberTitle` — Set a member's display title in one group (Teacher, Room Parent).
+- `setGroupParent` — Move a group underneath another group, or to the top level.
+- `translateGroup` — Fill in a group's missing name translations.
+- `updateGroup` — Change a group's name or description.
+
+## knowledge
+
+- `addDocument` — Add a document to the organization's knowledge base so the assistant can answer from it.
+- `askOrg` — Prefer the `ask_org` tool. Ask a question and get an answer drawn from the organization's own documents, with citations.
+- `deleteDocument` **(confirm)** — Delete a document from the organization's knowledge base.
+- `importUploadedDocument` — Import a document from pasted text into the knowledge base.
+- `learnAgain` — Re-index one knowledge source so the assistant picks up its current contents.
+- `reclassifyDocument` **(confirm)** — Change who a knowledge document can be shown to.
+- `relearnKnowledge` — Bring a retired knowledge source back into the assistant's answers.
+- `unlearnKnowledge` **(confirm)** — Retire a knowledge source from the assistant's answers, with a reason.
+- `updateDocument` — Change a knowledge document's title, kind or body.
+
+## looks
+
+- `deleteLook` **(confirm)** — Delete a saved visual preset.
+- `setSurfaceLook` — Apply a saved visual preset to a page, event, form or broadcast.
+- `suggestLook` — Suggest a visual preset for an occasion.
+- `upsertLook` — Create or replace a saved visual preset.
+
+## media
+
+- `deleteAsset` **(confirm)** — Delete an uploaded photo or file.
+- `discardEditedImage` — Throw away an AI image edit that was never kept.
+- `editAsset` — Edit a photo with AI from a plain-language instruction.
+- `generateLibraryImage` — Generate a new image for the organization's media library from an instruction.
+- `keepEditedImage` — Save an AI image edit into the organization's media library as a new asset.
+- `keepLibraryImage` — Save a generated image into the organization's media library.
+- `learnAsset` — Index a file's contents so the assistant can answer from it.
+- `redescribeAsset` — Regenerate a file's AI description and alt text.
+- `setAssetAudience` **(confirm)** — Change who can see an uploaded file — the public, or members only.
+- `updateAsset` — Change an uploaded file's title, alt text, classification or scope.
+
+## meetings
+
+- `addAgendaItem` — Add an item to a meeting's agenda.
+- `adjournMeeting` **(confirm)** — End a live meeting.
+- `appendTranscript` — Append transcript segments to a live meeting's record.
+- `approveItemMinutes` **(confirm)** — Approve the minutes text for one agenda item.
+- `cancelPrompt` — Discard a live vote without recording it.
+- `closePrompt` **(confirm)** — Close a live vote and record its result in the meeting's minutes and ledger.
+- `compileMinutesDraft` — Compile and AI-clean an adjourned meeting's minutes into the working draft.
+- `createMeeting` — Create a meeting, optionally scheduled.
+- `draftItemMinutes` — Suggest minutes text for one agenda item from the transcript.
+- `generateItemMinutes` — Auto-draft and save an agenda item's minutes from the transcript and its recorded motions, marking the item done.
+- `openPrompt` — Open a live vote in a meeting with its question and options.
+- `publishMinutes` **(confirm)** — Publish an adjourned meeting's minutes as a page and email every active member their action items.
+- `raiseQuestion` — Raise a question to the floor of a live meeting so the chair sees it.
+- `recordMotion` **(confirm)** — Record a motion in the minutes of a live meeting, with who moved and seconded it.
+- `removeAgendaItem` **(confirm)** — Delete an agenda item and renumber the rest of the meeting's agenda.
+- `reorderAgendaItems` — Set the order of a meeting's agenda items by listing their ids in the order you want.
+- `resolveQuestion` — Mark a question raised to the floor answered or dismissed.
+- `respondToPrompt` **(confirm)** — Cast your own vote in a live meeting prompt.
+- `saveMinutesDraft` — Save the Secretary's edited minutes draft.
+- `setActiveItem` — Make an agenda item the one the live meeting is on.
+- `setAttendance` — Record whether a member is present at a meeting.
+- `startMeeting` **(confirm)** — Start a meeting.
+- `suggestPoll` — Suggest a poll question and options from the recent meeting transcript.
+- `suggestPollOptions` — Suggest options for a poll question from the recent transcript.
+- `suggestTasks` — Suggest follow-up tasks for an agenda item.
+- `translateMeeting` — Fill in a meeting title's missing translations.
+- `triageWindow` — Classify a window of live meeting transcript into suggested governance decisions.
+- `updateAgendaItem` — Change an agenda item's title, kind or detail.
+- `updateMeeting` — Change a meeting's title or scheduled time.
+
+## members
+
+- `acceptInvite` — Accept an invitation to join an organization using the token from the invite link.
+- `assignMemberRole` **(confirm)** — Give a member an additional named role (Treasurer, Room Parent).
+- `confirmMemberImport` **(confirm)** — Commit a member import that `previewMemberImport` has already checked.
+- `createInvite` **(confirm)** — Prefer the `invite_member` tool. Invite someone to the organization by email at a chosen role.
+- `previewMemberImport` — Check a CSV of members and report what would happen, without writing anything.
+- `removeMember` **(confirm)** — Prefer the `remove_member` tool. Remove someone from the organization entirely.
+- `revokeInvite` **(confirm)** — Cancel a pending invitation.
+- `setMemberRole` **(confirm)** — Prefer the `set_member_role` tool. Change a member's role in the organization.
+- `setMemberStatus` **(confirm)** — Suspend or reactivate a member.
+- `unassignMemberRole` **(confirm)** — Take a named role away from a member.
+
+## money
+
+- `startPayout` **(confirm)** — Prefer the `start_payout` tool. Pay the available Stripe balance out to the organization's bank account.
+- `startStripeOnboarding` **(confirm)** — Begin Stripe onboarding for the organization and return the link to finish it.
+
+## orders
+
+- `cancelOrder` **(confirm)** — Prefer the `cancel_order` tool. Cancel a store order and, when asked, refund the buyer.
+- `retryOrder` **(confirm)** — Retry fulfillment for a store order that failed.
+
+## organization
+
+- `createOrg` — Create a new organization with you as its owner.
+- `setOrgDefaultLanguage` **(confirm)** — Set the organization's default site language.
+- `setOrgJoinPolicy` **(confirm)** — Set whether people can request to join the organization themselves.
+- `setOrgLanguages` **(confirm)** — Set which languages the site is offered in, as a comma-separated list.
+- `suggestOrgTheme` — Suggest theme colors and fonts from a description.
+- `updateOrg` **(confirm)** — Change the organization's name, contact email, postal address or home page.
+- `updateOrgChrome` — Replace the site's header and footer content.
+- `updateOrgDesignSystem` — Replace the organization's design system.
+- `updateOrgNav` — Replace the site navigation.
+- `updateOrgTheme` — Change the organization's colors, fonts and logo.
+
+## pages
+
+- `createGroupSubpage` — Create a page underneath a group's landing page.
+- `createPage` — Create a new, empty page.
+- `deletePage` **(confirm)** — Delete a page, published or not.
+- `draftPageBlocks` — Prefer the `draft_page` tool. Draft page content from a plain-language instruction and return the blocks.
+- `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.
+- `renamePage` — Change a page's title, optionally for one language only.
+- `rewriteBlockText` — Rewrite one content block's text from a plain-language instruction.
+- `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.
+- `setPageVisibility` **(confirm)** — Set who can see a page — everyone, members, or one group.
+- `translateDocument` — Translate a document's text into the organization's languages.
+- `translatePage` — Fill in a page's missing translations, for one block or the whole page.
+- `unpublishPage` **(confirm)** — Prefer the `unpublish_page` tool. Take a page off the live site.
+- `updatePageDraft` — Prefer the `update_page_draft` tool. Replace a page draft with new blocks.
+
+## store
+
+- `createOrgProduct` — Add a product to the store from a catalog blank at a retail price.
+- `deleteOrgProduct` **(confirm)** — Remove a product from the store.
+- `deleteProductGroup` **(confirm)** — Delete a product group and leave its individual products in place.
+- `setOrgProductEnabled` **(confirm)** — Show or hide a store product.
+- `updateOrgProduct` — Change a store product's title or retail price.
+- `upsertProductGroup` — Create or replace a product group and its variants.
+
+## tasks
+
+- `createTask` — Prefer the `create_task` tool. Create a follow-up task, optionally assigned to a member and tied to a meeting.
+- `setTaskStatus` — Prefer the `set_task_status` tool. Mark a task open or done.
+
+## tickets
+
+- `checkInTicket` — Check a ticket in at the door by its code.
+- `compTickets` **(confirm)** — Issue free tickets to someone for an event.
+- `refundTicketOrder` **(confirm)** — Prefer the `refund_ticket_order` tool. Refund a ticket order in full and void its tickets.
+- `undoCheckIn` — Undo a ticket check-in at the door.

package/skill/references/schema.md

@@ -0,0 +1,38 @@
+# Reading Phenomenal's schema
+
+<!-- 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 `fef338e5`._
+
+Two tools answer questions no curated tool anticipated.
+
+## `get_schema(typeName?)`
+
+Returns the named GraphQL type plus one level of the types it references. With no argument it returns the whole schema, which is large — name a type when you can.
+
+The same text is also a resource: `phenomenal://schema.graphql`. Reading a resource costs no tool call, so prefer it when your client supports resources.
+
+## `query_graphql(query, variables?)`
+
+Runs a **read-only** GraphQL query against the same schema, as you, in your own transaction. Use it for a shape no tool returns — a count across events, a field a list tool omits, one page's blocks alongside its status.
+
+It is not a way around anything. It executes through exactly the path `/graphql` serves, with your role and the same row-level rules, so a query for something you may not read comes back refused, not empty-and-silent.
+
+### What it will refuse
+
+- **Anything that is not a query.** A mutation, a subscription, or a document with several operations and no `operationName`. Mutations go through `run_mutation`.
+- **Introspection.** `__schema` and `__type` are blocked, because `get_schema` and the `phenomenal://schema.graphql` resource are the cheaper, complete answer.
+- **Depth over 8.** Nested selections deeper than that are rejected before they run.
+- **More than 30 aliases** in one document.
+- **A cost over 1000.** Cost weights list fields' children, so a wide selection under several lists trips it. Ask for the fields you need.
+
+A refused query says which limit it hit. Narrow the selection rather than retrying it unchanged.
+
+## Working with it
+
+1. `get_schema("Query")` to see what can be asked for.
+2. `get_schema("Event")` (or whichever type) for its fields.
+3. `query_graphql` with a small selection, then widen if you need to.
+
+Most queries take an `orgId`. It comes from `list_my_orgs`, like everywhere else — never invent one.

package/skill/references/starting-doc.md

@@ -0,0 +1,92 @@
+# Phenomenal for agents
+
+<!-- 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 `fef338e5`._
+
+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.
+
+**If you are an assistant reading this on someone's behalf:** connect with one of the recipes below, then follow the guidance in "How to work in Phenomenal" further down. It combines the standing instructions and workflows from the live registry.
+
+## Connect
+
+The server is at `https://api.phenomenal.org/mcp`. Signing in happens in a browser: the person picks which organizations the connection may act for, and the connection can never do more than their own role allows.
+
+**Claude Code**
+
+```
+claude mcp add --transport http phenomenal https://api.phenomenal.org/mcp
+```
+
+**Codex CLI**
+
+Run the add command first. If it opens sign-in, finish in the browser. If it hangs after saying the server was added, press Ctrl+C; the configuration is already saved. Then run the login command separately to finish or retry sign-in.
+
+```
+codex mcp add phenomenal --url https://api.phenomenal.org/mcp
+```
+
+```
+codex mcp login phenomenal
+```
+
+**Claude Desktop**
+
+Settings → Connectors → Add custom connector, then paste `https://api.phenomenal.org/mcp`.
+
+**Anything that only speaks stdio**
+
+```
+npx @phenomenalorg/mcp
+```
+
+Node 20 or newer.
+
+## Install the skill package
+
+A client that reads [Agent Skills](https://code.claude.com/docs/en/skills) can hold the briefing below as a file, so it loads only when it is needed:
+
+```
+npx @phenomenalorg/mcp --skill <dir>
+```
+
+That writes a `phenomenal/` folder — `SKILL.md` plus its reference sheets — into the directory you name. With no directory it installs into `.claude/skills/` when that folder is already there, and prints `SKILL.md` to stdout when it is not.
+
+## How to work in Phenomenal
+
+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.
+
+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.
+
+Publish a page: list_pages → get_page → draft_page → update_page_draft (saved privately) → preview publish_page → ask → publish_page with confirm: true.
+
+For other work: list_mutations → describe_mutation → run_mutation. Read arguments; never guess. query_graphql is read-only.
+
+## 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.
+
+New event for my organization (call list_my_orgs first): . Ask for missing dates, location and ticket details. list_events → create_event → update_event for event details only. For tickets: list_mutations({ area: "events" }) → describe_mutation({ name: "createTicketType" }) → run_mutation with its exact input schema. For ticket changes, describe_mutation({ name: "updateTicketType" }) first. Leave the event unpublished; preview set_event_published and ask before confirming.
+
+Membership review for my organization (call list_my_orgs first): list_members (follow cursors) → list_groups → list_group_members. Report pending or suspended members and officer roles. Recommend changes but make none; keep names and addresses in your answer to me.
+
+Month-end money for my organization (call list_my_orgs first): payout_status → list_orders. Report holds, failures, possible refunds and available funds. Propose refund_ticket_order, cancel_order or start_payout only when needed; each needs its own preview and yes. Move no money yet.
+
+## Reference
+
+- 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.
+
+## When this page and the server disagree
+
+This page is a copy of the server's own registry, published from it. Read `phenomenal://instructions` and compare its `Tool surface fingerprint` with the fingerprint above. If they differ, say this guide is out of date and use live instructions, schemas and confirmation requirements. If the resource has no fingerprint, freshness is unknown. Do not compare this fingerprint with the product version. `initialize` reports the live server's version as `serverInfo.version`, and `tools/list` reports exactly which tools it has — **those are the authority.** If a tool named here is missing from the live list, go by the live list and say plainly that the published guide is out of date.

package/skill/references/tools.md

@@ -0,0 +1,512 @@
+# Phenomenal tools
+
+<!-- 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 `fef338e5`._
+
+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.
+
+**Confirm** means the tool changes nothing until a person has said yes in words and you pass `confirm: true`. Called without it, the tool returns a preview of what would happen. See `SKILL.md`.
+
+**Hints** are the MCP annotations a client shows before it calls: _read-only_ (no write of any kind), _writes_, _destructive_ (it can destroy something a person would miss), _idempotent_ (calling twice is the same as once). They are hints, not a fence — what you are allowed to do is decided by your role in the organization.
+
+### `list_my_orgs`
+
+List the organizations you can act for in Phenomenal, with your role in each. Call this first: every other tool needs an organization id from this list.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- none
+
+### `org_overview`
+
+A one-call summary of an organization in Phenomenal: its name and web address, how many members it has, its most recent pages, events, groups and broadcasts, and where its money stands. Sections your role cannot read are listed under "unavailable" rather than left out.
+
+**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.
+
+### `list_members`
+
+The people in a Phenomenal organization, with each person's role and status. Use the membershipId from here for set_member_role and remove_member — never a user id.
+
+**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.
+- `status` (string (active | pending | suspended)) — Only members in this state. Leave it out for everyone.
+- `limit` (integer) — How many to return (1–200, default 50).
+- `cursor` (string) — The nextCursor from a previous call.
+
+### `invite_member`
+
+Invite someone to a Phenomenal organization by email at a chosen role. An invitation email goes out immediately, so this needs confirm: true. You cannot invite at a role above your own.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `email` (string, required) — The invitee’s email address.
+- `role` (string (owner | admin | editor | member), required) — The role they join at. Most people are "member"; officers are "admin".
+- `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.
+
+### `set_member_role`
+
+Change a member's role in a Phenomenal organization. This changes what they can do, so it needs confirm: true. You cannot grant a role above your own, only an owner may change an owner, and the last active owner cannot be demoted.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `membershipId` (string, required) — From list_members — not a user id.
+- `role` (string (owner | admin | editor | member), required) — The role to move them to.
+- `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.
+
+### `remove_member`
+
+Remove someone from a Phenomenal organization entirely. They lose access immediately, so this needs confirm: true. Suspending them instead keeps the record — ask the person which they meant.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `membershipId` (string, required) — From list_members — not a user id.
+- `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.
+
+### `list_pages`
+
+The pages on a Phenomenal organization's site, with each page's slug and whether it is published. Use the id from here with get_page, update_page_draft and publish_page.
+
+**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.
+- `status` (string (draft | published | published_changes)) — Only pages in this state. "published_changes" means it is live but the draft has moved on.
+
+### `get_page`
+
+One page from Phenomenal with its current draft content, as the array of blocks you would edit. Read this before changing anything: update_page_draft replaces the whole draft.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `pageId` (string, required) — From list_pages.
+
+### `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.
+
+**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 page being drafted, from list_pages.
+- `instruction` (string, required) — What the page should say, in plain language — "a fall festival page with the date, the volunteer sign-up and a photo".
+
+### `update_page_draft`
+
+Save a page's draft in Phenomenal. Replaces the WHOLE draft, so send the full block array — read the current one with get_page first. The live page does not change until publish_page.
+
+**Hints:** writes, idempotent. **Confirm:** not required.
+
+**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. 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.
+
+**Hints:** writes. **Confirm:** required — without it you get a preview and nothing changes.
+
+**Arguments**
+
+- `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.
+
+### `unpublish_page`
+
+Take a page off the live Phenomenal site. The draft is kept, but every link anyone has shared to it stops working — so this needs confirm: true.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**Arguments**
+
+- `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.
+
+### `list_events`
+
+The events on a Phenomenal organization's calendar, soonest first, with whether each one is published.
+
+**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.
+- `from` (string) — Only events starting on or after this date (YYYY-MM-DD).
+- `to` (string) — Only events starting on or before this date (YYYY-MM-DD).
+
+### `create_event`
+
+Create an event in Phenomenal. It starts UNPUBLISHED — nobody outside the organization sees it until set_event_published.
+
+**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.
+- `title` (string, required) — What the event is called.
+- `startsAt` (string, required) — When it starts, as an ISO 8601 date-time — "2026-10-17T18:00:00Z".
+- `endsAt` (string) — When it ends, ISO 8601. Optional.
+- `location` (string) — Where it is. Optional.
+- `description` (string) — A short description for the page. Optional.
+- `slug` (string) — The URL segment. Optional — one is derived from the title.
+
+### `update_event`
+
+Change an event in Phenomenal — its title, time, place or description. Only the fields you pass are changed. If the event is already published, the site changes at once.
+
+**Hints:** writes, 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.
+- `eventId` (string, required) — From list_events.
+- `title` (string) — A new title.
+- `startsAt` (string) — A new start, ISO 8601.
+- `endsAt` (string) — A new end, ISO 8601.
+- `location` (string) — A new location.
+- `description` (string) — A new description.
+
+### `set_event_published`
+
+Publish or unpublish an event in Phenomenal. Publishing puts it in front of everyone, so this needs confirm: true.
+
+**Hints:** writes. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `eventId` (string, required) — From list_events.
+- `published` (boolean, required) — true to publish, false to take it down.
+- `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.
+
+### `list_groups`
+
+The groups in a Phenomenal organization — classes, committees, teams — with how people get into each one. Use the groupId from here with list_group_members, and when addressing a broadcast.
+
+**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.
+
+### `list_group_members`
+
+Who is in one Phenomenal group, with each person's relation to it (member, steward) and whether they are still active.
+
+**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.
+- `groupId` (string, required) — From list_groups.
+- `status` (string (active | inactive)) — Only people in this state. Default is active only.
+
+### `list_broadcasts`
+
+The email broadcasts of a Phenomenal organization — drafts and sent ones — with how many people each reached.
+
+**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.
+- `status` (string) — Only broadcasts in this state, e.g. "draft" or "sent".
+
+### `draft_broadcast`
+
+Write an email broadcast draft for a Phenomenal organization and choose who it would go to. SENDS NOTHING — it creates a draft and tells you how many people it would reach.
+
+**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.
+- `subject` (string, required) — The subject line families will see.
+- `body` (string, required) — The message, in Markdown. Write it the way a parent would want to read it — short, warm, and clear about dates and what to do.
+- `audience` (object) — Who it goes to. Leave it out entirely to address every member of the organization.
+- `replyTo` (string) — Where replies go. Optional — the organization's contact address is used otherwise.
+
+### `send_broadcast_test`
+
+Send ONE test copy of a Phenomenal broadcast to a single address, so a person can read it before it goes out. This is still real email to a real inbox, so it needs confirm: true.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `broadcastId` (string, required) — From list_broadcasts or draft_broadcast.
+- `toEmail` (string, required) — The single address to send the test to.
+- `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.
+
+### `send_broadcast`
+
+Send a Phenomenal broadcast to its whole audience. Real email leaves immediately and CANNOT be recalled, so this needs confirm: true — and the person, not you, decides.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `broadcastId` (string, required) — From list_broadcasts or draft_broadcast.
+- `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.
+
+### `list_orders`
+
+Store orders in a Phenomenal organization, newest first, with each buyer and what they paid. Orders needing attention have onHold set or a status of fulfillment_failed.
+
+**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.
+- `status` (string (pending | paid | submitted | shipped | delivered | fulfillment_failed | canceled | refunded)) — Only orders in this state.
+- `limit` (integer) — How many to return (1–100, default 25).
+- `cursor` (string) — The nextCursor from a previous call.
+
+### `cancel_order`
+
+Cancel a store order in Phenomenal and refund the buyer. Money moves and the buyer is emailed, so this needs confirm: true. The reason is shown to the buyer.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `orderId` (string, required) — From list_orders.
+- `reason` (string, required) — Why it is being canceled, in a sentence the buyer will read (3–500 characters).
+- `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.
+
+### `refund_ticket_order`
+
+Refund an event ticket purchase in Phenomenal in full and void its tickets. Money moves and the buyer is emailed, so this needs confirm: true. Ticket purchases are separate from store orders — this is the ticket one.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `purchaseId` (string, required) — The ticket order id.
+- `eventId` (string) — The event the purchase belongs to, from list_events. Optional, and worth passing: with it the preview can name the buyer and the amount.
+- `reason` (string) — Why it is being refunded, in a sentence the buyer will read.
+- `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.
+
+### `payout_status`
+
+Where a Phenomenal organization's money stands: what is available to pay out, what is still settling, and the recent payouts.
+
+**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.
+
+### `start_payout`
+
+Pay a Phenomenal organization's available Stripe balance out to its bank account. Money leaves, so this needs confirm: true.
+
+**Hints:** destructive. **Confirm:** required — without it you get a preview and nothing changes.
+
+**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.
+- `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.
+
+### `list_tasks`
+
+The follow-up tasks in a Phenomenal organization — who owes what, and by when.
+
+**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.
+- `status` (string (open | done)) — Only tasks in this state.
+
+### `create_task`
+
+Create a follow-up task in Phenomenal, optionally assigned to a member and due on a date.
+
+**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.
+- `title` (string, required) — What needs doing, in a short sentence.
+- `dueDate` (string) — When it is due (YYYY-MM-DD). Optional.
+- `assigneeMembershipId` (string) — Who owes it, from list_members. Optional.
+
+### `set_task_status`
+
+Mark a Phenomenal task open or done. Closing one is how a meeting’s follow-ups stop showing on the assignee’s list.
+
+**Hints:** writes, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `taskId` (string, required) — From list_tasks.
+- `status` (string (open | done), required) — The state to move it to.
+
+### `list_forms`
+
+The forms in a Phenomenal organization — sign-ups, RSVPs, volunteer slots — with how many submissions each has.
+
+**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.
+
+### `form_submissions`
+
+The answers people have submitted to a Phenomenal form, newest first. These carry family names and email addresses — keep them inside your answer to the officer and do not repeat them elsewhere.
+
+**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.
+- `formId` (string) — From list_forms. Leave it out for every form.
+- `status` (string) — Only submissions in this state, e.g. "new".
+- `limit` (integer) — How many to return (1–100, default 25).
+- `cursor` (string) — The nextCursor from a previous call.
+
+### `find_media`
+
+Find photos and files in a Phenomenal organization's media library by what is in them. Returns the STORED PATH of each file, which is what page blocks and events refer to — not a public link, and not something to paste into a message.
+
+**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.
+- `query` (string, required) — What you are looking for — "fall festival pumpkins", "school logo".
+- `kind` (string) — Narrow to one kind, e.g. "image" or "document".
+- `limit` (integer) — How many to return (1–50, default 20).
+
+### `ask_org`
+
+Ask a question and get an answer drawn from a Phenomenal organization's own documents and knowledge, with citations. Use this before guessing at anything about how a particular school does things.
+
+**Hints:** read-only. **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.
+- `question` (string, required) — The question, in plain language.
+
+### `list_mutations`
+
+Every action Phenomenal can take that the curated tools do not already cover, as a short index. Filter by area or search by word, then read one with describe_mutation and run it with run_mutation. Reach for a curated tool first when one fits — they are shorter and they resolve names for you.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `area` (string (account | brand | broadcasts | connections | domains | drive | email-preferences | events | forms | groups | knowledge | looks | media | meetings | members | money | orders | organization | pages | store | tasks | tickets)) — Only actions in this part of Phenomenal.
+- `search` (string) — Only actions whose name or summary contains this word.
+
+### `describe_mutation`
+
+What one Phenomenal action does and exactly what arguments it takes, as a JSON Schema. Read this before run_mutation — do not guess an argument name.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `name` (string, required) — From list_mutations.
+
+### `run_mutation`
+
+Run any Phenomenal action by name, with the arguments describe_mutation lists. Actions that send mail, move money, publish, delete, change permissions or change addressing show a preview and change nothing until confirm: true. Prefer a curated tool when one covers what you need.
+
+**Hints:** writes. **Confirm:** required — without it you get a preview and nothing changes.
+
+**Arguments**
+
+- `name` (string, required) — The action name, from list_mutations.
+- `input` (object) — The arguments, exactly as describe_mutation names them. Most take an orgId from list_my_orgs.
+- `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.
+
+### `query_graphql`
+
+Read anything in Phenomenal with a GraphQL query. Read-only: only `query` operations are accepted, one per call. Use get_schema first to see the fields, and prefer a curated tool when one already answers the question.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `query` (string, required) — One GraphQL query operation. Most reads start from org(id: $orgId) — pass the id as a variable.
+- `variables` (object) — Values for the query’s variables.
+
+### `get_schema`
+
+Phenomenal's GraphQL schema. Give a type name to see that type and the types its fields mention; give none for the list of type names. Use this before writing a query_graphql query.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `typeName` (string) — A type name — "Org", "Page", "Event". Leave it out to list every type.
+
+## Workflows
+
+### weekly_newsletter
+
+Draft this week’s newsletter from what is actually happening, and stop before sending.
+
+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.
+
+### new_event
+
+Set up an event and its tickets, and leave it unpublished.
+
+New event for my organization (call list_my_orgs first): . Ask for missing dates, location and ticket details. list_events → create_event → update_event for event details only. For tickets: list_mutations({ area: "events" }) → describe_mutation({ name: "createTicketType" }) → run_mutation with its exact input schema. For ticket changes, describe_mutation({ name: "updateTicketType" }) first. Leave the event unpublished; preview set_event_published and ask before confirming.
+
+### membership_review
+
+Review the roster: who is waiting, who holds what, and what looks wrong.
+
+Membership review for my organization (call list_my_orgs first): list_members (follow cursors) → list_groups → list_group_members. Report pending or suspended members and officer roles. Recommend changes but make none; keep names and addresses in your answer to me.
+
+### site_health
+
+Check the public site for stale, missing and unpublished things.
+
+Check the health of my organization (call list_my_orgs first)'s Phenomenal site.
+
+Call org_overview, list_pages and list_events. Tell me: pages that are drafts and probably should not be, pages published a long time ago whose content sounds out of date, events in the past that are still on the calendar, and whether the web address and custom domain are set up.
+
+Give me a short list in priority order. Change nothing.
+
+### month_end_money
+
+Close out the month: orders needing attention, refunds outstanding, what can be paid out.
+
+Month-end money for my organization (call list_my_orgs first): payout_status → list_orders. Report holds, failures, possible refunds and available funds. Propose refund_ticket_order, cancel_order or start_payout only when needed; each needs its own preview and yes. Move no money yet.