@awesomate/hosting-mcp 0.12.0 → 0.13.0

package/skill/awesomate-n8n/references/possibilities.md

@@ -0,0 +1,83 @@
+# Possibilities — grounding "what could I automate?"
+
+Rules for suggesting automations. Every idea must be grounded in this
+instance's real inventory — never in what n8n generically supports.
+
+## When to offer ideas
+
+| Situation | Action |
+|---|---|
+| Explicit ask ("what could I automate", "give me ideas", "what else") | Run the inspect, present the tiers below |
+| Vague request, right after the first inventory pass | ONE offering sentence ("Based on what you have connected I can suggest a few automations — want that?"), then wait |
+| Anything else | Never volunteer an unprompted idea dump |
+
+## Data source — facts only
+
+`awesomate_n8n_inspect {what:'possibilities'}` returns facts, zero ideas.
+Ideation is your job; this payload is the ground truth you build on:
+
+| Field | Meaning |
+|---|---|
+| `services[]` | Connected services: `service`, `credentials` (count), `credentialNames` (≤3 names), `confirmed`, `nodeType` (native n8n node or null), `usedInWorkflows` (inventory refs), `activeInWorkflows` (node present in the LIVE histogram) |
+| `unusedConnections` | Services with a credential but no known usage. Cached inventory cross-checked against live node usage — a workflow wired up after the last weekly refresh still counts as used |
+| `nodesInUse` | `{type, count}` histogram across the instance, descending |
+| `aiToolsAvailable` | AI/langchain nodes on this n8n. **null = unknown (catalog down). Never say "no AI tools" on null** |
+| `communityPackages` | `{packageName, installedVersion, nodeTypes}`. **null = unknown, [] = verified none — never collapse the two** |
+| `counts` | `workflows`, `activeWorkflows`, `credentials`, `datatables` (null = table absent on this n8n version) |
+
+## Presentation — at most 8 ideas, three grounded tiers
+
+Order by concreteness. Skip a tier rather than pad it.
+
+1. **Extend what you already have** — per existing workflow: "your
+   `<workflow name>` could also notify X / retry Y / log to a datatable".
+   Ground each in a workflow from `awesomate_n8n_workflows` plus the nodes
+   it already uses.
+2. **New builds with existing connections** — name the actual credential:
+   "using your `<credentialNames[0]>` Gmail credential, a daily digest of…".
+   `unusedConnections` is the highest-signal list here: they connected it
+   for a reason and nothing uses it yet.
+3. **Needs something new** — labelled honestly with exactly what:
+   a new connection ("needs a Slack credential — 2 min in your n8n UI"),
+   a plan upgrade ("builds need Support Plus+"), or the FFMPEG variant
+   ("media nodes are Support Plus+ only"). Never disguise tier 3 as tier 2.
+
+## Grounding rules (hard)
+
+- Only suggest nodes present on THIS variant. `capabilities.variant` from
+  `awesomate_n8n_context`: Standard has no localFiles / better-ffmpeg /
+  mediafx. Check `communityPackages` before naming any community node.
+- Only reference credentials in `services[]`. **Never claim a credential
+  works because it exists** — inventory shows names, not validity; say
+  "you have a credential named X" and verify during the build.
+- AI-agent ideas require `aiToolsAvailable` to be a non-empty array. On
+  null, say the catalog is unavailable, not that AI is unsupported.
+- Respect platform invariants in any sketch you show: `$vars` not `$env`,
+  webhook data at `$json.body`, HTTP Request nodes not `$helpers`, Code
+  nodes return `[{json:{...}}]`, `saveExecutionProgress` stays false,
+  webhook trigger (explicit path) instead of formTrigger. Details:
+  [platform-notes.md](platform-notes.md).
+- Datatable-backed ideas: only when `counts.datatables` is non-null;
+  writes need Support Plus+ (`awesomate_n8n_datatable_write`); tables
+  resolve per project at runtime.
+
+## Community templates — importable starting points
+
+Search by the user's actually-connected services, not by the idea's topic:
+
+- `awesomate_n8n_node_docs {tool:'search_templates', args:{query: '<service>'}}`
+  then `{tool:'get_template', args:{templateId}}` for the JSON.
+- A template is a starting point, not a deploy: strip nodes needing
+  credentials the user lacks, then run the full build loop (validate →
+  create_draft → test) from SKILL.md §2.
+- 503 `node_catalog_unavailable` → skip templates this session and fall
+  back to the vendored references in `references/vendor/`.
+
+## Essentials plan
+
+`capabilities.builder: false` → reads work, builds need Support Plus+.
+Say so ONCE, honestly — "I can explain, diagnose, and design these, but
+building on your instance needs Support Plus+ (upgrade at
+hub.awesomate.ai/billing)" — then keep helping within reads: present the
+tiers as a roadmap, sketch designs, diagnose existing workflows. Do not
+repeat the upsell on every idea.

package/skill/awesomate-n8n/references/testing-policy.md

@@ -0,0 +1,115 @@
+# Testing Policy (mandatory)
+
+A build or change is NOT done until the workflow has been EXECUTED on the
+user's instance and the execution INSPECTED node by node.
+`awesomate_n8n_deploy {action:'validate'}` checks structure, not behaviour —
+a passing validate plus a green final status is never "tested".
+
+Applies to: new builds (SKILL.md Phase 5), the upgrade loop (test the draft
+AND re-verify after promote), and any fix to a failing workflow. Only
+exception: the user explicitly waives testing for that specific task.
+
+## How a test runs
+
+There is no manual or pin-data execution on this platform. E2E = activate +
+production webhook + poll executions:
+
+1. Get approval to go live, then
+   `awesomate_n8n_deploy {action:'activate', workflowId}` — production
+   webhooks only respond while the workflow is active.
+2. `awesomate_n8n_test {workflowId, payload}` — fires the PRODUCTION webhook
+   with the `X-Awesomate-Test` header; returns the webhook response plus the
+   `executionId` it caused. Real side effects DO run: emails actually send.
+   Address them to the user's own email, prefix subjects `[TEST]`, use
+   obviously fake data (`test+<runId>@…`, "TEST SUBMISSION"), and tell the
+   user before firing. Non-email side effects (CRM writes, payments, SMS):
+   STOP and ask first.
+3. Inspect: `awesomate_n8n_executions {executionId, debug: true}` — read the
+   node list, per-node output, and which branches ran. When consent is off,
+   debug data is unavailable and the call falls back to the non-debug
+   detail (final status + failing node only) — state that in the report;
+   you inspected less than usual.
+
+A green final status is not inspection. Do not enable
+`saveExecutionProgress` to get richer data — the hub enforces it FALSE
+(write-amplification incident); `debug: true` is the inspection path.
+
+## Fixtures (payload classes)
+
+The payload passed to `awesomate_n8n_test` is the POST body — the workflow
+sees it at `$json.body`. Run at minimum one of each class:
+
+| Class | Payload |
+|---|---|
+| happy-path | Realistic valid input, obviously fake values |
+| empty | `{}` / missing fields entirely |
+| malformed | Wrong types, missing required fields, junk strings |
+| error-`<api>` | Input that drives a named upstream API to a realistic error (nonexistent id → 404, bad enum → 400) — one per external dependency |
+
+Quota: `limits` from `awesomate_n8n_context` caps daily test fires. Plan
+the fixture set before burning tests; a 429 `quota_exceeded` means the
+day's cap — tell the user, never retry-loop.
+
+## Error-path testing (required, minimum 3)
+
+1. Failed upstream call (error-`<api>` fixture)
+2. Empty payload
+3. Malformed payload
+
+Verify `onError` branches ACTUALLY ROUTE: in the execution's node list,
+confirm the error path's nodes ran and the post-failure happy-path nodes
+did not. Final status alone proves nothing — an execution whose error
+branch routed can still finish green.
+
+## Multi-trigger gotcha
+
+`awesomate_n8n_test` reaches the webhook trigger only. A schedule (or any
+non-webhook) branch NEVER runs from a test fire — it is untested unless
+exercised deliberately:
+
+- Draft phase: temporarily wire the branch behind a webhook trigger via
+  `awesomate_n8n_deploy {action:'update_draft'}`, test-fire it, then
+  REMOVE the temporary trigger before promote.
+- Never promote or leave live a workflow carrying a temporary test
+  trigger — it is a world-callable production URL.
+- If the branch cannot be exercised this way, list it under "needs human"
+  in the report. Do not report it as tested.
+
+## What Claude cannot verify → human checklist
+
+List explicitly, per test run:
+
+- Real side effects landing (the `[TEST]` email in their inbox, the CRM
+  record, the SMS)
+- OAuth/credential-gated calls that could not be exercised
+- External services actually pointing at the production webhook URL
+- Schedule/non-webhook branches that never fired (see above)
+
+Ask the user to confirm each ("check your inbox for [TEST] …") and record
+their answer in the report.
+
+## Test Report (required in every handoff)
+
+```
+## Test Report — <workflow> @ <instance>
+Executed: <executionIds + payload class for each>
+Inspection: debug / non-debug fallback (consent off)
+Passed: <node paths verified, outputs checked>
+Error paths: <fixture → which branch routed → result>
+Not verifiable by Claude (needs human): <list + why>
+Post-test state: restored ✔ (checklist below)
+```
+
+## Post-test state restore
+
+- [ ] Temporary test triggers/nodes removed from drafts
+- [ ] Test drafts deactivated; deleted via
+      `awesomate_n8n_deploy {action:'delete_draft'}` unless the user wants
+      them kept
+- [ ] `[TEST]` rows written to datatables during tests cleaned up
+      (`awesomate_n8n_datatable_write {action:'delete_rows'}`)
+- [ ] Live workflow's activation state matches what the user expects
+- [ ] After a promote: the ORIGINAL production URL re-verified with a test
+      fire (promote preserves webhookIds — the old URL must still respond)
+- [ ] User told which `[TEST]` artifacts (emails, records) to expect and
+      discard

package/skill/awesomate-n8n/references/troubleshooting.md

@@ -0,0 +1,69 @@
+# Troubleshooting — diagnosing a failing workflow
+
+Diagnosis playbook. Work the flow top-to-bottom; do not jump to fixes before
+you have the failing execution's detail.
+
+## Diagnosis flow
+
+1. `awesomate_n8n_context` — confirm consent flags, capabilities, and the
+   instance fingerprint before reading anything else.
+2. `awesomate_n8n_executions {workflowId}` — list recent runs. Pick the
+   failing execution (or the first failure in a streak — later failures are
+   often downstream noise from the same cause).
+3. `awesomate_n8n_executions {executionId}` — detail: error message, the node
+   that threw, last node executed.
+4. **Walk the item data BACKWARDS from the failing node.** The node that
+   throws is rarely the node that is wrong — the usual cause is an upstream
+   node emitting a mis-mapped or missing field that a downstream expression
+   consumes. Compare what each upstream node emitted against what the failing
+   node's expressions expect. Read the node config with
+   `awesomate_n8n_workflows {id, detail:'full'}`.
+5. `awesomate_n8n_executions {executionId, debug: true}` — node-level output
+   data. Requires `error_content_analysis` consent:
+   - `403 consent_required` → give the user the `settingsUrl` from the error
+     response and stop; they enable it under Settings → Privacy.
+   - `tooLarge: true` → payload over 15MB. Use the summary in the response;
+     do NOT retry hoping for the full payload.
+6. Node behaving strangely rather than erroring → check its schema with
+   `awesomate_n8n_node_docs {tool: "get_node"}` (on `503
+   node_catalog_unavailable`, fall back to the `vendor/` references).
+
+## Common errors → cause → fix
+
+| Error / symptom | Likely cause | Fix |
+|---|---|---|
+| Downstream fields empty/undefined on a webhook workflow | Webhook data lives at `$json.body`, not `$json` | Use `{{ $json.body.field }}`. #1 cause of "undefined" in webhook flows |
+| "access to environment variables is denied" | `$env` is blocked fleet-wide — in Code nodes AND regular field expressions | Use `{{ $vars.key \|\| 'fallback' }}` or a Config Set-node literal; never `$env` |
+| "$helpers is not defined" (works in editor preview, fails at run time) | Task runners strip `$helpers` from Code nodes | Move HTTP calls to HTTP Request nodes; process results in a downstream Code node |
+| "Could not find the data table: '<id>'" | PROJECT scope, not existence — datatables resolve within the workflow's own project at runtime | Check which project owns the table (`awesomate_n8n_inspect {what: "datatables"}`) vs the workflow. Recreate/move the table into the workflow's project (`awesomate_n8n_datatable_write`, Support Plus+). Reference tables by name, never by id |
+| Credential "could not be found" | Sharing/RBAC — the credential exists but is not shared with the workflow's project/owner. Almost never deletion | Verify it exists via `awesomate_n8n_inspect {what: "credentials"}`; user shares it to the project in the n8n editor |
+| Webhook URL returns 404 | Workflow not active — production webhook paths register only while active. Test URLs work only while the editor is listening | Activate via `awesomate_n8n_deploy`. Never activate a copy — `promote` preserves webhookIds |
+| Form URL 404s at its custom path | formTrigger ignores the custom `path`; forms serve only at `/form/<webhookId>` | Use a webhook trigger when a stable path matters |
+| "Unrecognized node type" / unknown node at activation | Community media node on an instance without the FFMPEG variant (Support Plus+ gate) | Check `awesomate_n8n_context` capabilities; upgrade variant or rebuild on core nodes. Note: static validation flagging `CUSTOM.*` nodes "unknown" is a false positive — trust activation, not the validator |
+| Output shows literal "[object Object]" | Expression resolves to an object where a string is expected | Drill to the scalar (`{{ $json.body.user.email }}`) or wrap in `JSON.stringify()` |
+| Workflow saved but never executes | Draft was never activated/published; saving is not publishing | `awesomate_n8n_deploy {action: "activate"}` (new) or `promote` (replacing a live one). E2E-verify: activate + hit the production webhook + poll executions |
+| Code node output vanishes or breaks downstream | Not returning `[{ json: {...} }]`, or leftover template boilerplate | Return an array of `{json}` objects; check whether the node is unedited boilerplate |
+| Node config valid yesterday, "Invalid value for 'operation'" today | Partial update stripped the `operation` discriminator | Set `resource` + `operation` together in the same update; re-validate |
+| `crashed` status, hours-long runtime, loop workflow | `saveExecutionProgress: true` (quadratic writes — 2TB WAL incident) and/or no `executionTimeout` on a `splitInBatches` loop | Keep `saveExecutionProgress` FALSE (the hub enforces it); add `executionTimeout` to every loop workflow; bound rows per run |
+| `429 quota_exceeded` | Plan daily cap reached | STOP immediately. Do not retry-loop — tell the user the cap is hit; it resets daily or they upgrade. Limits are in `awesomate_n8n_context` |
+
+## Verification after a fix
+
+- Re-run realistically: `awesomate_n8n_test {workflowId, payload}` for manual
+  runs; for live paths, activate + POST the production webhook + poll
+  `awesomate_n8n_executions` until the new run appears.
+- Inspect the fixed run's data, not just its status — an `onError: continue`
+  branch can turn a failure into a "successful" run carrying an `error` key.
+
+## When to STOP and hand off
+
+- **`agency_managed` error** — the workflow is managed by Awesomate. Reads
+  are fine: list it, read executions, run `debug`, and explain the failure to
+  the user freely. Do NOT attempt any change (`deploy`, `test`, datatable
+  writes) — changes to agency-managed workflows go through Awesomate support.
+  Summarize your diagnosis so the user can paste it into their ticket.
+- `403 consent_required` the user declines to enable — diagnose from the
+  execution summary only; say plainly what deeper access would show.
+- `429 quota_exceeded` — never burn remaining quota on retries.
+- Fix requires the FFMPEG variant or a higher plan — explain the gate; the
+  upgrade happens in the hub, not here.

package/skill/awesomate-n8n/references/upgrade-loop.md

@@ -0,0 +1,98 @@
+# Upgrade loop — changing a workflow that already exists
+
+Use this whenever the target workflow is not a fresh build: a live self-built
+workflow, a draft mid-iteration, or a workflow the user built in the n8n UI.
+
+## Invariants (violating any of these breaks external callers)
+
+- **Never edit a live workflow directly.** Live changes go draft → test →
+  promote. `update_draft` on a live workflow is refused (409, below).
+- **Never activate the copy.** A duplicated draft has different webhook URLs;
+  activating it instead of promoting strands every external caller.
+- **Promote preserves webhookIds** — that is the whole point. The live id and
+  its production URLs never change across a promote.
+- **Promote only works between self-built (`awm:client-cli`) workflows.**
+  UI-built workflows need the duplication path at the bottom.
+- **Save the `operationId`** returned by promote — it is the only rollback
+  handle.
+
+## Which path
+
+| Situation | Path |
+|---|---|
+| Iterating on an INACTIVE draft (not yet promoted/activated) | `update_draft` in place — no new workflow ids |
+| Changing a LIVE self-built workflow | Duplicate → draft loop → promote (steps below) |
+| Changing a workflow built in the n8n UI (no `awm:client-cli` tag) | Duplicate into a CLI draft; coordinated URL cutover |
+| Agency-managed workflow (`agency_managed` 403) | Read/explain only; changes go through Awesomate support |
+
+## Iterating on a draft: `update_draft`
+
+`awesomate_n8n_deploy {action:'update_draft', workflowId,
+workflowJson:{name?, nodes, connections, settings?}}`
+
+- **Full JSON replace** — nodes + connections replace the draft's entirely;
+  send the complete workflow, not a delta.
+- Settings are **whitelisted server-side**: unknown keys and null/undefined
+  values are dropped, `saveExecutionProgress` is pinned false (2TB WAL
+  incident), `executionOrder` defaults to `v1`. Omit a key to keep the
+  draft's current value.
+- Refusals: **409 `workflow_active`** — the workflow is live; do NOT
+  deactivate it to force the edit, use the promote path below. 403
+  `not_self_built` — only `awm:client-cli` workflows. 403 `agency_managed`.
+- Validate (`{action:'validate', workflowJson}`) before every update; re-test
+  after (the full Phase 5 testing policy from SKILL.md applies).
+
+## Upgrading a LIVE self-built workflow
+
+1. **Duplicate.** Fetch the live workflow's full JSON
+   (`awesomate_n8n_workflows {id, detail:'full'}` or
+   `GET /api/my-n8n/workflows/:id`), then `create_draft` with the modified
+   JSON — new name, e.g. same name; the hub adds `[CLI] ` + fresh test
+   webhookIds automatically.
+2. **Iterate.** Apply the requested changes; validate. Further revisions go
+   through `update_draft` on the draft — no need to delete and recreate.
+3. **Test the draft on its own (test) URLs.** Activate the DRAFT (approval
+   gate applies), then `awesomate_n8n_test {workflowId:<draft id>, payload}`.
+   Full testing policy: inspect node-by-node output, happy path + empty +
+   malformed payloads, confirm error branches routed.
+4. **Present the diff — mandatory before promote.** Human-readable, covering
+   ALL of: nodes added / removed / changed (name + what changed), credential
+   changes (added, swapped, removed), and a behavior summary in the user's
+   terms (what the workflow will now do differently). **Wait for explicit
+   approval.** No diff, no promote.
+5. **Promote.** `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 against the ORIGINAL URL.** `awesomate_n8n_test` against the
+   LIVE workflow id — the original production URL must still respond, and
+   the execution must show the NEW behavior (inspect node output; a 200
+   alone proves nothing). On any failure:
+   `{action:'rollback', operationId}` restores both workflows to their
+   pre-promote state, then investigate — do not iterate on the live body.
+7. **Cleanup.** Once the user confirms the promoted version, `delete_draft`
+   the archived `[promoted …]` draft (it is deactivated and still
+   CLI-tagged), or leave it as a manual fallback if they prefer.
+
+## UI-built workflows (no `awm:client-cli` tag)
+
+Promote refuses these. Instead:
+
+1. Fetch the UI workflow's JSON; `create_draft` a CLI copy with the changes.
+2. Test the draft fully (steps 2–3 above).
+3. The draft becomes the live workflow going forward — its webhook URL
+   DIFFERS from the original. Coordinate the cutover with the user: they
+   update every external caller to the new URL, confirm traffic arrives on
+   the new workflow, then deactivate the old UI workflow themselves (it is
+   theirs — do not delete it).
+
+## Errors you will hit
+
+| Code | Meaning | Do |
+|---|---|---|
+| 409 `workflow_active` | `update_draft` on a live workflow | Promote path, never deactivate-to-edit |
+| 403 `not_self_built` | No `awm:client-cli` tag | UI-built duplication path |
+| 403 `agency_managed` | Awesomate-deployed workflow | Explain only; route to support |
+| 429 `quota_exceeded` | Daily plan cap | Tell the user; never retry-loop |

package/skill/awesomate-n8n/references/vendor/MANIFEST.json

@@ -0,0 +1,26 @@
+{
+  "syncedAt": "2026-08-19T03:06:35.506Z",
+  "sourceSha": "d293559",
+  "files": {
+    "expressions/SKILL.md": "n8n-expression-syntax/SKILL.md",
+    "expressions/COMMON_MISTAKES.md": "n8n-expression-syntax/COMMON_MISTAKES.md",
+    "expressions/EXAMPLES.md": "n8n-expression-syntax/EXAMPLES.md",
+    "code-node/SKILL.md": "n8n-code-javascript/SKILL.md",
+    "code-node/DATA_ACCESS.md": "n8n-code-javascript/DATA_ACCESS.md",
+    "code-node/BUILTIN_FUNCTIONS.md": "n8n-code-javascript/BUILTIN_FUNCTIONS.md",
+    "code-node/ERROR_PATTERNS.md": "n8n-code-javascript/ERROR_PATTERNS.md",
+    "code-node/COMMON_PATTERNS.md": "n8n-code-javascript/COMMON_PATTERNS.md",
+    "node-configuration/SKILL.md": "n8n-node-configuration/SKILL.md",
+    "node-configuration/OPERATION_PATTERNS.md": "n8n-node-configuration/OPERATION_PATTERNS.md",
+    "node-configuration/DEPENDENCIES.md": "n8n-node-configuration/DEPENDENCIES.md",
+    "workflow-patterns/SKILL.md": "n8n-workflow-patterns/SKILL.md",
+    "workflow-patterns/webhook_processing.md": "n8n-workflow-patterns/webhook_processing.md",
+    "workflow-patterns/http_api_integration.md": "n8n-workflow-patterns/http_api_integration.md",
+    "workflow-patterns/database_operations.md": "n8n-workflow-patterns/database_operations.md",
+    "workflow-patterns/ai_agent_workflow.md": "n8n-workflow-patterns/ai_agent_workflow.md",
+    "workflow-patterns/scheduled_tasks.md": "n8n-workflow-patterns/scheduled_tasks.md",
+    "validation/SKILL.md": "n8n-validation-expert/SKILL.md",
+    "validation/ERROR_CATALOG.md": "n8n-validation-expert/ERROR_CATALOG.md",
+    "validation/FALSE_POSITIVES.md": "n8n-validation-expert/FALSE_POSITIVES.md"
+  }
+}