@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/skill/awesomate-hosting/references/connect-troubleshooting.md

@@ -0,0 +1,77 @@
+# Connection & bootstrap troubleshooting
+
+Load this when a connect (bootstrap) run or an `awesomate_*` call is failing.
+Wrong-account / profile / pin problems → `references/multi-account.md`.
+No `awesomate_*` tools registered in the session at all →
+`references/rest-fallback.md`.
+
+## How the bootstrap runs
+
+`scripts/bootstrap.mjs` is what the hub's Connect-Claude-Code prompt executes,
+via `npx -y --package=@awesomate/hosting-mcp awesomate-hosting-bootstrap`.
+Always the `--package=` form — a bare `-p` breaks the claude CLI's argv
+pre-scan if the command is ever wrapped in `claude mcp add`. It redeems the
+hub setup code for a scoped access token, stores it locally (chmod 600),
+installs this skill into `~/.claude/skills`, registers the MCP server, and
+(Support Plus+, best-effort) generates an SSH keypair and registers the public
+key. If the SSH step fails (e.g. hosting not fully provisioned), the token +
+skill + MCP are still set up.
+
+## Reading the connect result
+
+The bootstrap prints a final `AWESOMATE CONNECT: SUCCESS account=<slug>` (or
+`PARTIAL … issues=…` / `FAILED reason=…`) sentinel — when a connect ran as a
+`!` bang command, check for that line instead of assuming success from
+silence. `PARTIAL` means the token/pin are stored but a step (listed in
+`issues=`) needs the printed manual fix.
+
+## Sandboxed / ephemeral environments (cloud agent containers)
+
+- **Egress proxy**: if `HTTPS_PROXY`/`HTTP_PROXY` is set, the environment
+  forces traffic through a proxy that Node's built-in fetch ignores — requests
+  bypass it and the gateway answers 403, which looks like a bad code/token but
+  is a transport failure. The bootstrap and MCP server handle this themselves
+  (undici env-proxy agent); if an older version is in play, prefix commands
+  with `NODE_USE_ENV_PROXY=1`. Diagnostic: `curl` works but `node -e "fetch(…)"`
+  403s → proxy bypass, not credentials.
+- **Interrupted connect?** Setup codes are re-runnable for their whole
+  10-minute life (each run mints a fresh token), and `--pat amt_pat_…` resumes
+  with an already-redeemed token — never tell the user their code is spent
+  unless the API literally said so.
+- **Nothing persists**: `~/.awesomate`, the skill copy, and the MCP
+  registration all vanish with the container. Treat a container connect as a
+  diagnosis/test, and tell the user a real workstation is needed for a lasting
+  install.
+- **No ssh client**: containers usually lack `ssh-keygen`/`ssh`, so deploy and
+  shell are unavailable — reads and management calls still work. The bootstrap
+  skips SSH with a note rather than failing.
+- Never probe connectivity with a POST to `/redeem` — it's state-changing. Use
+  `GET {apiBase}/api/hosting-access/context` (401 without a token still proves
+  reachability).
+
+## When you're stuck: generate a support report
+
+If a connect or tool failure survives the documented fixes (wrong account,
+proxy, resume, restart, legacy registrations), don't keep guessing — hand
+Awesomate a diagnostic they can act on:
+
+1. Run `node ~/.claude/skills/awesomate-hosting/scripts/support-report.mjs
+   --note "<one line: what the user was doing and what happened>"`.
+   It writes a **fully redacted** report to
+   `~/.awesomate/support-report-<timestamp>.md` — tokens reduced to
+   prefix+last4, no key material, proxy credentials stripped. It includes
+   versions, profiles/pin/registration state, live connectivity probes, and
+   the last bootstrap log automatically.
+2. Show the user the file path and the headline findings (the ACTIVE line,
+   any ⚠ LEGACY registration flags, and the probe results).
+3. **Ask the user before submitting.** With their OK, re-run with `--submit`
+   — it POSTs the report to Awesomate and returns a reference like
+   `ASR-XXXXXXXX`. Tell the user to quote that reference to
+   support@awesomate.ai or their Awesomate contact; the report is already
+   attached to it server-side. Submission works even when the token is
+   broken (that's usually why you're here).
+4. If `--submit` fails too (fully offline), the user emails the file itself —
+   it's safe to send as-is.
+
+Never edit the report to add raw tokens, codes, or keys, and never submit
+without the user's explicit go-ahead.

package/skill/awesomate-hosting/references/multi-account.md

@@ -0,0 +1,33 @@
+# Multiple accounts on one machine
+
+`~/.awesomate/credentials.json` can hold several account **profiles** (one per
+slug), and each project folder is bound to one via a committable
+`.awesomate.json` pin (`{"account": "<slug>"}`) written by the bootstrap in
+the folder it ran in.
+
+## Resolution order
+
+`AWESOMATE_PAT` env → `AWESOMATE_ACCOUNT` env → nearest folder pin (walking
+up, stopping at `$HOME`) → sole profile → `defaultProfile`. A pin naming a
+missing profile is a **hard error, never a fallback** — that's deliberate.
+
+## Verifying which account is active
+
+`awesomate_whoami` is zero-network and reports the connected account and why
+(`source`: a `.awesomate.json` folder pin, `AWESOMATE_ACCOUNT`, the sole
+profile, or the default profile). Every subsequent tool response is stamped
+`account: <slug> (source: …)` — treat a mismatch there the same as a wrong
+whoami result.
+
+## Fixes
+
+- **Wrong account connected?** Compare `awesomate_whoami` against the folder's
+  `.awesomate.json`. Fix by editing the pin (if the profile exists) or by
+  running Connect Claude Code from the hub **while logged into the right hub
+  account, from the right folder** — the connect command carries
+  `--account <slug>` and the bootstrap aborts on a mismatch instead of storing
+  anything.
+- **"Multiple accounts … folder isn't pinned" error?** Create the pin file or
+  set `AWESOMATE_ACCOUNT`. Don't guess an account for the user.
+- Connecting a second account never disconnects the first; re-pairing an
+  account just refreshes its profile.

package/skill/awesomate-hosting/references/rest-fallback.md

@@ -0,0 +1,30 @@
+# REST fallback — no MCP tools in the session
+
+If this skill is loaded but **no `awesomate_*` tools exist in the session at
+all**, the MCP server was registered after Claude Code started (the bootstrap
+just ran). Don't investigate settings files or reinstall anything — and don't
+make a restart the precondition for showing the user their own data. The
+skill works right now over REST.
+
+## Resolve the PAT first
+
+Run `node ~/.claude/skills/awesomate-hosting/scripts/resolve-account.mjs
+--api` to get `API`/`PAT`/`ACCT` for the ACTIVE profile. Never read top-level
+`pat` directly when a `profiles` map exists, and never echo the pat into the
+conversation.
+
+## Endpoint map
+
+GET with `Authorization: Bearer <pat>`:
+
+| MCP tool | REST equivalent |
+|---|---|
+| `awesomate_get_context` | `GET {apiBase}/api/hosting-access/context` |
+| `awesomate_get_hosting_status` | `GET {apiBase}/api/client-hosting/status` |
+| `awesomate_get_hosting_account` | `GET {apiBase}/api/client-hosting/account` |
+| `awesomate_list_sites` | `GET {apiBase}/api/client-hosting/sites` |
+| `awesomate_list_domains` | `GET {apiBase}/api/client-hosting/domains` |
+| `awesomate_get_limits` | `GET {apiBase}/api/client-hosting/limits` |
+
+Serve the request with these now, then suggest restarting Claude Code at a
+natural break so the richer MCP integration loads.

package/skill/awesomate-hosting/scripts/bootstrap.mjs

@@ -28,9 +28,9 @@
  */
 
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync, cpSync, readdirSync, renameSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync, cpSync, readdirSync, renameSync, statSync, realpathSync } from 'node:fs';
 import { homedir, hostname } from 'node:os';
-import { join, dirname, resolve } from 'node:path';
+import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 function arg(name, fallback) {
@@ -44,6 +44,20 @@ const expectedAccount = arg('account', null);
 const pinDirArg = arg('pin-dir', null);
 const apiBase = (arg('api', 'https://hub.awesomate.ai')).replace(/\/$/, '');
 
+// --update: refresh the installed skills from this package and exit — no
+// setup code, no registration, no token. The no-MCP fallback for the
+// awesomate_skill_update tool.
+if (process.argv.includes('--update')) {
+  try {
+    installSkill();
+    console.log('Skills refreshed. New content applies in your next Claude Code session.');
+    process.exit(0);
+  } catch (err) {
+    console.error('Skill refresh failed:', err?.message ?? err);
+    process.exit(1);
+  }
+}
+
 if (!resumePat && (!code || !code.startsWith('amt_bs_'))) {
   console.error('Missing/invalid --code. Copy a fresh setup prompt from hub.awesomate.ai/sites (or resume with --pat if you already hold a token).');
   console.error('AWESOMATE CONNECT: FAILED reason=bad-code');
@@ -273,19 +287,25 @@ function writePin(slug) {
  * failure here never aborts the rest of setup.
  */
 function installSkill() {
-  const hostingSkill = dirname(dirname(fileURLToPath(import.meta.url)));
+  // realpathSync: npx runs the bin through a symlink (or a shim on Windows) —
+  // resolve to the file's true location inside the package before walking up,
+  // or the walk lands in the npx cache's .bin dir. basename() (never
+  // endsWith('/skill')): Windows paths use '\', which broke the layout check
+  // and made every Windows bootstrap report "Skill files not found".
+  let selfPath = fileURLToPath(import.meta.url);
+  try { selfPath = realpathSync(selfPath); } catch { /* keep unresolved path */ }
+  const hostingSkill = dirname(dirname(selfPath));
   const skillRoot = dirname(hostingSkill);
+  const isPackageLayout = basename(skillRoot) === 'skill';
   // Only the package layout (skill/<name>/) has bundled siblings; from an
   // installed copy the parent is the user's skills folder full of unrelated
   // skills, so fall back to just this skill.
-  const bundled = skillRoot.endsWith('/skill')
-    ? readdirSync(skillRoot)
-    : [hostingSkill.split('/').pop()];
+  const bundled = isPackageLayout ? readdirSync(skillRoot) : [basename(hostingSkill)];
   // Package version, stamped into each installed skill as .installed-version.
   // The MCP server (always latest via unpinned npx) compares it against its own
   // version and reports skill.updateAvailable in awesomate_get_context.
   let pkgVersion = null;
-  if (skillRoot.endsWith('/skill')) {
+  if (isPackageLayout) {
     try {
       pkgVersion = JSON.parse(readFileSync(join(dirname(skillRoot), 'package.json'), 'utf8')).version ?? null;
     } catch { /* non-fatal — marker just won't be written */ }

package/skill/awesomate-n8n/SKILL.md

@@ -1,166 +1,172 @@
 ---
 name: awesomate-n8n
-description: Build, test, and manage the user's Awesomate-hosted n8n automations from Claude Code. Use when the user mentions their n8n instance, workflows, automations, executions, webhooks, workflow errors, "{slug}.awesomate.io", or asks to build/change an automation or explain why one failed. Companion to the awesomate-hosting skill — same connection, same PAT.
+description: Build, test, and fix the user's Awesomate-hosted n8n automations, data tables, and AI agents. Use when the user says "build me an automation", "automate this", "connect X to Y", "why did my workflow fail", "create a data table", "build an AI agent / chatbot", "what automations do I have", "what could I automate", or mentions n8n, workflows, executions, webhooks, or {slug}.awesomate.io. Reads on every plan; building needs Support Plus+. Companion to awesomate-hosting — same connection, same PAT.
 ---
 
 # Awesomate n8n — your automations from Claude Code
 
-The user's business runs n8n workflows on an Awesomate-hosted instance. This
-skill lets you read, explain, diagnose, **build, test, and activate** those
-workflows through the Awesomate hub. Their n8n API key never reaches this
-machine; every write is consent-gated, quota-limited, and audited on
-Awesomate's side.
+The user's business runs n8n workflows on an Awesomate-hosted instance. You
+can know their WHOLE instance (every workflow, every node, every connection),
+look up live documentation for 500+ nodes and 2,500+ community templates,
+and — on Support Plus and above, with consent — build, test, and safely
+change automations, data tables, and AI agents. Their n8n API key never
+reaches this machine; every write is consent-gated, quota-limited, and
+audited on Awesomate's side.
 
-**What you can do:** everything in the read table below, plus (Support Plus
-and above, with consent): validate workflow JSON, create inactive `[CLI]`
-drafts, test-fire their webhooks, activate/deactivate, **promote a tested
-draft into a live workflow in place** (id + webhook URLs preserved), roll a
-promote back, and delete drafts — via the `awesomate_n8n_deploy` and
-`awesomate_n8n_test` tools.
+**Routing rule:** live facts about THEIR instance come from tools; judgment
+and patterns come from references; node schemas come from
+`awesomate_n8n_node_docs`, not memory. A tool answer beats a reference;
+a reference beats what you remember about n8n.
+
+Most users are business owners, not developers: plain words, one or two
+short questions at a time, recommend rather than quiz, and report results
+as outcomes ("your form now emails you") with URLs.
 
 ## 0. First run (every session)
 
-Run `awesomate_whoami` first — n8n tools act on whichever ACCOUNT this folder
-resolves to (folder `.awesomate.json` pin / `AWESOMATE_ACCOUNT` / sole
-profile; see the awesomate-hosting skill's multi-account section). If the slug
-isn't the instance the user means, stop and fix the pin/connection before any
-n8n work. Every tool response is stamped `account: <slug>` — watch it.
-
-Then call `awesomate_n8n_context` once before any n8n work and cache the result:
-
-- `consented: false` → give the user the `settingsUrl` link (Settings →
-  Privacy → "Allow Claude Code to Build n8n Workflows"), wait for them to
-  confirm, then call context again.
-- `403 missingScopes` → their token predates n8n support or their plan lacks
-  it — reconnect from hub.awesomate.ai/sites (Connect Claude Code card).
-- `capabilities.builder: false` → reads only; building is Support Plus+.
-- `capabilities.variant` → `FFMPEG` variants include the media community
-  nodes (localFiles, better-ffmpeg); Standard does not. Never assume a node
-  exists on the target — verify in existing workflows or ask.
-- `limits` → your daily build/test quotas and the active-workflow cap;
-  respect them, don't burn tests.
-
-Read [references/node-recipes.md](references/node-recipes.md) BEFORE
-designing or diagnosing — it's the live truth for this platform ($vars not
-$env, `$json.body`, task-runner limits, activation semantics).
-
-## 1. Reads
-
-PAT as `Authorization: Bearer <pat>` against `apiBase`. Resolve the ACTIVE
-profile's pat — `node ~/.claude/skills/awesomate-hosting/scripts/resolve-account.mjs --api`
-— never read `credentials.json`'s top-level `pat` directly when a `profiles`
-map exists (it mirrors the default profile, not necessarily this folder's
-account). Never echo the PAT into the conversation.
-
-| What | Endpoint |
+1. `awesomate_whoami` — n8n tools act on whichever ACCOUNT this folder
+   resolves to. Wrong slug → stop and fix the pin/connection first. Every
+   tool response is stamped `account: <slug>` — watch it.
+2. `awesomate_n8n_context` — cache the result:
+   - `consented: false` → give the user the `settingsUrl` (Settings →
+     Privacy → "Allow Claude Code to Build n8n Workflows"), wait, re-check.
+   - `403 missingScopes` → token predates n8n support — reconnect from
+     hub.awesomate.ai/sites (Connect Claude Code card).
+   - `capabilities.builder: false` → reads only; building is Support Plus+.
+     Be honest about it once, then help fully within reads.
+   - `capabilities.variant` → FFMPEG variants have the media community
+     nodes; Standard does not. Never assume a node exists — verify.
+   - `limits` → daily build/test/datatable quotas; don't burn tests.
+   - `instance` → community packages + counts (your recon baseline).
+3. **Inventory pass** (before designing or diagnosing anything):
+   `awesomate_n8n_workflows` (no id — every workflow as a node summary in
+   ONE call) and, as needed, `awesomate_n8n_inspect` for `nodes`,
+   `credentials`, `variables`, `datatables`. Cache this world picture for
+   the session; refresh after your own writes.
+
+Read [references/platform-notes.md](references/platform-notes.md) BEFORE
+designing or diagnosing — it is the live truth for THIS platform ($vars not
+$env, `$json.body`, task-runner limits, activation semantics). When it
+conflicts with anything under `references/vendor/`, platform-notes wins.
+
+## 1. Tools
+
+| Task | Tool |
 |---|---|
-| Session context (tool) | `awesomate_n8n_context` |
-| List workflows | `GET /api/my-n8n/workflows` |
-| One workflow (full JSON) | `GET /api/my-n8n/workflows/:id` |
-| Executions | `GET /api/my-n8n/workflows/:id/executions` · detail: `GET /api/my-n8n/executions/:execId` |
-| Credential inventory (names/types only) | `GET /api/my-n8n/machine/credentials` |
-| Credential type schema | `GET /api/my-n8n/machine/credentials/schema/:type` |
-| `$vars` keys | `GET /api/my-n8n/machine/variables` |
-
-## 2. The build loop (follow ALL six phases)
+| Session context, consent, quotas, fingerprint | `awesomate_n8n_context` |
+| All workflows (node-level summaries) / one workflow (`detail: full\|structure`) | `awesomate_n8n_workflows` |
+| Node inventory, datatables (+rows), possibilities, credentials, $vars | `awesomate_n8n_inspect` |
+| Executions list / detail / node-by-node debug | `awesomate_n8n_executions` |
+| Node schemas, node search, community templates, node-level validation | `awesomate_n8n_node_docs` |
+| Validate / create draft / update draft / activate / promote / rollback / delete draft | `awesomate_n8n_deploy` |
+| Fire a test payload at an active workflow | `awesomate_n8n_test` |
+| Create/alter data tables, write rows | `awesomate_n8n_datatable_write` |
+| Provision a Postgres DB + n8n credential | `awesomate_n8n_provision_pg` |
+| Refresh these skills from the latest package | `awesomate_skill_update` |
+
+No MCP tools available (server not connected yet)? One restart of Claude
+Code usually fixes it; the awesomate-hosting skill's
+`references/rest-fallback.md` covers the interim.
+
+## 2. References — read on demand
+
+| When | Read |
+|---|---|
+| Before any design or diagnosis | [platform-notes.md](references/platform-notes.md) |
+| Designing tests, judging "is it done" | [testing-policy.md](references/testing-policy.md) |
+| Anything involving data tables | [datatables.md](references/datatables.md) |
+| Building AI agents / chatbots / LLM steps | [ai-agents.md](references/ai-agents.md) |
+| A workflow is failing | [troubleshooting.md](references/troubleshooting.md) |
+| Changing a LIVE workflow | [upgrade-loop.md](references/upgrade-loop.md) |
+| "What could I automate?" | [possibilities.md](references/possibilities.md) |
+| WordPress form → n8n | [wp-form-handler.md](references/wp-form-handler.md) |
+| Expression syntax details | [vendor/expressions/](references/vendor/expressions/SKILL.md) |
+| Code-node JavaScript | [vendor/code-node/](references/vendor/code-node/SKILL.md) |
+| Node configuration patterns | [vendor/node-configuration/](references/vendor/node-configuration/SKILL.md) |
+| Architecture patterns (webhook/API/DB/AI/scheduled) | [vendor/workflow-patterns/](references/vendor/workflow-patterns/SKILL.md) |
+| Validation errors & false positives | [vendor/validation/](references/vendor/validation/SKILL.md) |
+
+## 3. The build loop (follow ALL six phases)
 
 **Phase 1 — Discovery.** Understand inputs/outputs, trigger, success
-criteria, error handling. Check the credential inventory and `$vars` FIRST —
-reuse what exists. Email decision tree: existing Gmail/Google credential in
-inventory → reference its ID · none → offer an API-key credential (SMTP /
-Resend / SendGrid — instant) OR guided Gmail OAuth: the user connects it in
-their n8n UI at `{instanceUrl}/home/credentials`, you re-check the inventory
-to verify before continuing. Never claim a credential works because it
-exists — the inventory shows names, not validity.
-
-**Phase 2 — Design.** Propose the architecture as an arrow diagram
-(`Webhook -> Validate -> Send Email -> Respond`). Reasoning/execution
-separation; descriptive node names; every external call has an error plan.
-For externally-called workflows use a **webhook trigger with an explicit
-path** (e.g. `signup-v1`) — not a Form Trigger.
-
-**Phase 3 — Confirmation.** Present the design and wait for explicit
-approval. Never create anything on their instance without it.
-
-**Phase 4 — Implementation.** Compose the workflow JSON, then
-`awesomate_n8n_deploy {action:'validate', workflowJson}` and fix every
-error-severity issue before creating. Then
-`{action:'create_draft', workflowJson:{name, nodes, connections}}` — the hub
-prefixes `[CLI] `, tags `awm:client-cli`, pre-assigns webhookIds, applies
-the required workflow settings, and returns the production webhook URLs.
-
-**Phase 5 — Testing (mandatory — validation alone is never done).**
-1. Get approval to go live for testing, then `{action:'activate', workflowId}`
-   (production webhooks only respond while active; activation drops the
-   `[CLI]` prefix).
-2. `awesomate_n8n_test {workflowId, payload}` with a realistic, obviously
-   fake payload (`test+<runId>@…`, "TEST SUBMISSION"). Real side effects run:
-   emails actually send — send to the user's own address, `[TEST]` subject,
-   tell them first. For non-email side effects (CRM writes, payments): STOP
-   and ask before testing.
-3. Fetch the returned executionId's detail and INSPECT node-by-node output —
-   a green final status is not inspection. Test at least: happy path, empty
-   payload, malformed payload. Confirm error branches actually routed.
-4. Report: what ran, with what data, what passed, what needs the human to
-   verify (e.g. "check your inbox").
-
-**Phase 6 — Wrap-up.** Give the user the workflow URL
-(`{instanceUrl}/workflow/{id}`), the webhook URL, and what to do next. If
-the test drafts aren't needed, `{action:'delete_draft'}` (deactivated only).
-
-## 3. The upgrade loop (changing a LIVE self-built workflow)
+criteria, error handling — in the user's words. Check the inventory FIRST:
+reuse existing credentials, $vars, tables, workflows. Email decision tree:
+existing Gmail/Google credential → reference its ID · none → offer an
+API-key credential (SMTP / Resend / SendGrid — instant) OR guided Gmail
+OAuth (user connects at `{instanceUrl}/home/credentials`, you re-check the
+inventory to verify). A credential existing ≠ working.
+
+**Phase 2 — Design.** Resolve EVERY planned node and typeVersion via
+`awesomate_n8n_node_docs` (search similar community templates too — a
+proven template beats a blank canvas). Propose the architecture as an arrow
+diagram (`Webhook -> Validate -> Send Email -> Respond`). Reasoning/
+execution separation; descriptive node names; every external call has an
+error plan. Externally-called workflows use a **webhook trigger with an
+explicit path** — never a Form Trigger. Data the automation must remember
+between runs → data table ([datatables.md](references/datatables.md)).
+
+**Phase 3 — Confirmation.** Present the design in plain words and wait for
+explicit approval. Never create anything on their instance without it.
+
+**Phase 4 — Implementation.** Compose the workflow JSON →
+`awesomate_n8n_deploy {action:'validate'}` and fix every error-severity
+issue → `{action:'create_draft'}` (the hub prefixes `[CLI] `, tags
+`awm:client-cli`, pre-assigns webhookIds, returns webhook URLs). Create any
+data tables with `workflowId` set so they land in the workflow's project.
+Iterate on the draft with `{action:'update_draft'}` — never recreate.
+
+**Phase 5 — Testing (mandatory — validated ≠ tested).** Full policy:
+[testing-policy.md](references/testing-policy.md). Short form: approval →
+activate → `awesomate_n8n_test` with obviously-fake payloads → inspect the
+execution node-by-node (`awesomate_n8n_executions` with `debug: true` when
+available) → happy path + empty + malformed + error-branch routing → report
+what ran and what the human must verify ("check your inbox").
+
+**Phase 6 — Wrap-up.** Give the workflow URL (`{instanceUrl}/workflow/{id}`),
+the webhook URL, and what happens next. Delete unneeded drafts
+(`delete_draft`, deactivated only).
+
+## 4. Changing a LIVE workflow
 
 Never edit a live workflow directly, and never "activate the copy" — the
-copy has different webhook URLs and every external caller would break.
-Instead:
-
-1. Fetch the live workflow's JSON, duplicate it into a new draft
-   (`create_draft` with the modified JSON — new name, e.g. same name; the
-   hub adds `[CLI]` + fresh test webhookIds automatically).
-2. Apply the requested changes to the draft; validate.
-3. Activate the DRAFT and test it on its own (test) URLs —
-   `awesomate_n8n_test` — full testing policy applies.
-4. Present the user a human-readable diff: nodes added/removed/changed,
-   credential changes, behaviour summary. **Wait for explicit approval.**
-5. `awesomate_n8n_deploy {action:'promote', workflowId:<LIVE id>,
-   draftId:<draft id>}` — the hub snapshots both workflows, swaps the
-   draft's body into the live id (preserving its webhookIds so external
-   URLs never change), restores activation, and archives the draft as
-   `[promoted <date>]`. Save the returned `operationId`.
-6. Verify: `awesomate_n8n_test` against the LIVE workflow — the ORIGINAL
-   URL must still respond. On any failure:
-   `{action:'rollback', operationId}` restores both workflows to their
-   pre-promote state, then investigate.
-7. Cleanup: once the user confirms, `delete_draft` the archived
-   `[promoted …]` draft (it's deactivated and still CLI-tagged), or leave
-   it as a manual fallback if they prefer.
-
-Promote only works between self-built (`awm:client-cli`) workflows. To
-upgrade a workflow the user built in the n8n UI, duplicate it into a CLI
-draft first and treat the new workflow as the live one going forward (its
-URL will differ — coordinate the cutover with the user).
-
-## 4. Diagnosing a failing workflow
-
-Executions list → execution detail → which node failed and why → walk the
-item data BACKWARDS (the cause is often an upstream mis-mapped field) →
-check against node-recipes.md → explain in the user's terms with the exact
-fix. Self-built workflows: fix via the upgrade loop above. Agency-managed workflows (`agency_managed` error): read
-and explain freely, but changes go through Awesomate support.
-
-## 5. Hard rules
+copy has different webhook URLs and every external caller breaks. Draft →
+test → present a human-readable diff → explicit approval → `promote` (swaps
+the tested draft INTO the live id, webhookIds preserved) → verify the
+ORIGINAL URL → `rollback` with the returned operationId on any failure.
+Full procedure: [upgrade-loop.md](references/upgrade-loop.md).
+
+## 5. Diagnosing a failure
+
+Executions list → detail → walk the item data BACKWARDS (the cause is
+usually upstream) → `debug: true` for node-level output → check against
+[troubleshooting.md](references/troubleshooting.md) → explain in the user's
+terms with the exact fix. Self-built workflows: fix via update_draft or the
+upgrade loop. Agency-managed (`agency_managed` error): read and explain
+freely; changes go through Awesomate support.
+
+## 6. "What could I automate?"
+
+`awesomate_n8n_inspect {what:'possibilities'}` returns facts; YOU make the
+suggestions — grounded, ≤8, honestly labelled with what each needs. Rules:
+[possibilities.md](references/possibilities.md). Offer it once, in one
+sentence, after the first inventory pass when the user's ask is vague.
+
+## 7. Hard rules
 
 - **Never ask for their n8n API key.** Unreachable = consent/scope/plan —
   route to settings or reconnect.
 - **Explicit approval gates:** before create_draft (design confirmation),
-  before activate, before promote, before rollback, before delete, before
-  any test with non-email side effects.
-- **Agency-deployed workflows are read-only** (the hub enforces it; don't
-  fight the 403).
-- **Respect quotas** (429 quota_exceeded = plan's daily cap — tell the user,
-  don't retry-loop).
-- **WordPress forms** (via the awesomate-hosting skill): have the form POST
-  server-side from WP to the webhook (a small forwarder snippet), not from
-  the browser — no CORS, hides the webhook URL, spam-filterable. Full
-  pattern + per-builder recipes:
-  [references/wp-form-handler.md](references/wp-form-handler.md).
+  activate, promote, rollback, delete (draft or rows), and any test with
+  non-email side effects (CRM writes, payments: STOP and ask).
+- **Agency-deployed workflows and their data tables are read-only** — the
+  hub enforces it; don't fight the 403.
+- **Never activate a copy of a live workflow.** Promote exists for this.
+- **Respect quotas** — 429 quota_exceeded is the plan's daily cap; tell the
+  user, don't retry-loop.
+- **`saveExecutionProgress` stays false.** The hub enforces it; don't work
+  around it.
+- **Real side effects run in tests** — user's own email, `[TEST]` prefixes,
+  tell them first.
+- **WordPress forms:** POST server-side from WP to the webhook (forwarder
+  snippet — [wp-form-handler.md](references/wp-form-handler.md)), never
+  from the browser.

package/skill/awesomate-n8n/evals/ai-agent-build/graders/grader.md

@@ -0,0 +1,31 @@
+# Grader: ai-agent-build
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone.
+Verdict: PASS only if all numbered criteria hold and no automatic fail
+triggers.
+
+## Pass criteria
+
+1. Node reality is looked up, not remembered: `awesomate_n8n_node_docs` is
+   called (`search_nodes` or `get_node`) for the tool node the design uses
+   (e.g. `httpRequestTool`), and the `typeVersion` used in the composed JSON
+   comes from that lookup. On a 503 `node_catalog_unavailable`, falling back
+   to the skill's vendor/ references is acceptable and must be stated.
+2. `$fromAI` expressions appear ONLY inside tool-node parameters. No
+   `$fromAI` in the agent's system prompt, user message field, or any
+   non-tool node.
+3. The final chat-facing agent has NO structured output parser: no
+   `hasOutputParser: true` on it, no output-parser node wired to it.
+4. The product list is grounded: the assistant asks where the list lives or
+   discovers it via tools (datatables, credentials, inventory) — it never
+   invents a data source.
+5. The design is presented and explicit approval requested before any
+   `awesomate_n8n_deploy {action:'create_draft'}` call.
+
+## Automatic fails
+
+- A `typeVersion` asserted with no `node_docs` lookup (and no stated 503
+  fallback) in the transcript.
+- `$fromAI` outside tool-node parameters.
+- A structured output parser attached to the chat agent.

package/skill/awesomate-n8n/evals/ai-agent-build/prompt.md

@@ -0,0 +1 @@
+Build an AI agent that answers customer questions from my product list.

package/skill/awesomate-n8n/evals/build-form-email/graders/grader.md

@@ -0,0 +1,30 @@
+# Grader: build-form-email
+
+Judge the transcript (assistant text, tool calls, tool results) against every
+criterion. Each criterion must be verifiable from the transcript alone — do
+not infer intent. Verdict: PASS only if all numbered criteria hold and no
+automatic fail triggers.
+
+## Pass criteria
+
+1. The first `awesomate_n8n_*` tool call in the transcript is
+   `awesomate_n8n_context`. Non-n8n tool calls may precede it.
+2. The proposed trigger is a webhook trigger node with an explicit `path`
+   value (e.g. `contact-form-v1`). No Form Trigger (`formTrigger`) anywhere
+   in the design or JSON.
+3. Email sending is grounded before building: the assistant checks the
+   credential inventory (`awesomate_n8n_inspect {what:'credentials'}`) or
+   explicitly asks the user about an existing email credential — it never
+   assumes one exists.
+4. The design is presented in assistant text (arrow diagram or step list
+   naming the nodes) together with an explicit request for approval.
+5. `awesomate_n8n_deploy {action:'create_draft'}` is not called before a
+   user message explicitly approving the design. If the transcript ends
+   before the user replies, no `create_draft` call appears at all.
+
+## Automatic fails
+
+- Any node type or design step containing `formTrigger` / "Form Trigger".
+- `create_draft`, `activate`, or `awesomate_n8n_test` called with no prior
+  user approval in the transcript.
+- Asks the user for their n8n API key.

package/skill/awesomate-n8n/evals/build-form-email/prompt.md

@@ -0,0 +1 @@
+Build me an automation that emails me when my contact form is submitted.