@awesomate/hosting-mcp 0.7.3 → 0.8.2

package/dist/index.js

@@ -40179,6 +40179,130 @@ server.registerTool(
     }
   }
 );
+readTool(
+  "awesomate_app_context",
+  "Call FIRST before any app-builder work. Returns the connected account's plan, whether the app builder is unlocked (capability.appBuilder \u2014 Support Plus+), whether they have a cPanel hosting account yet, their existing apps, firstRun, and capability-aware next-step suggestions to offer the user. If appBuilder is false, relay the upgrade suggestion rather than attempting to build.",
+  "/api/my-apps/context"
+);
+readTool(
+  "awesomate_app_list",
+  "List the client\u2019s apps (id, slug, kind, status, primary_domain, github repo). Use to find an appId before get/deploy.",
+  "/api/my-apps/apps"
+);
+server.registerTool(
+  "awesomate_app_get",
+  {
+    description: "Get one app plus its environments (subdomains, ports, db engine/name, deploy + health state). Poll this after awesomate_app_create \u2014 status goes provisioning \u2192 active | failed (read provision_error on failure).",
+    inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_list / _create") }
+  },
+  async ({ appId }) => {
+    try {
+      return textResult(await hubGet(requireConfig(), `/api/my-apps/apps/${appId}`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_create",
+  {
+    description: "Provision a new app on the client's cPanel account. Choose the stack deliberately (see the awesomate-app-builder skill): kind 'static' = a single fast landing/lead page served straight from the docroot (no DB, no server process \u2014 pick this for brochure/landing/lead-capture); kind 'node' = a dynamic app with a backend + database (logins, custom logic, an API). For node, dbEngine 'postgres' suits relational/JSON/AI-heavy data, 'mysql' is the simple default. Returns 202 immediately with an appId + subdomain(s); poll awesomate_app_get until status=active. Requires apps:write (Support Plus+) \u2014 a 403 means offer an upgrade. Get the user's confirmation on the stack + name before calling.",
+    inputSchema: {
+      appSlug: external_exports.string().regex(/^[a-z][a-z0-9]{1,15}$/).describe("2-16 chars, starts with a letter, lowercase alphanumeric \u2014 used for subdomains + db names"),
+      kind: external_exports.enum(["node", "static"]).default("node").describe("'static' for a landing/lead page (no DB); 'node' for a dynamic app"),
+      dbEngine: external_exports.enum(["mysql", "postgres"]).default("mysql").describe("node only \u2014 the database engine to provision"),
+      template: external_exports.string().optional().describe("Starter template (defaults: node \u2192 'node-auth-sync', static \u2192 'static-landing')")
+    }
+  },
+  async ({ appSlug, kind, dbEngine, template }) => {
+    try {
+      return textResult(
+        await hubPost(requireConfig(), "/api/my-apps/apps", { appSlug, kind, dbEngine, template })
+      );
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_deploy",
+  {
+    description: "Report how to deploy an app and its per-env targets. Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions \u2192 cPanel); this returns the branch\u2192env map and subdomains. Use the awesomate-github skill to wire push-to-deploy the first time.",
+    inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
+  },
+  async ({ appId }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/deploy`, {}));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_set_env",
+  {
+    description: "Store an API key / secret for a Node app environment: it's encrypted in the hub AND injected into the app's .env (0600) then the app restarts. ALWAYS use this instead of putting a secret in code, a committed file, or leaving it in the chat. NEVER echo the value back \u2014 confirm with the key name only. If the user pastes a key in chat, store it here and tell them (per the awesomate-credentials skill) it should be rotated since it passed through the transcript. Node apps only (static sites have no server env).",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      key: external_exports.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/).describe("Env var name, e.g. OPENAI_API_KEY"),
+      value: external_exports.string().min(1).describe("The secret value (stored encrypted; never echoed)"),
+      env: external_exports.enum(["dev", "staging", "prod"]).default("dev").describe("Which environment to set it on")
+    }
+  },
+  async ({ appId, key, value, env }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/env`, { key, value, env }));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_attach_to_app",
+  {
+    description: "Wire an app to call the user's own n8n as a backend. Give it the app + a webhook URL you already created/tested/promoted on their n8n (via awesomate_n8n_deploy \u2014 create_draft returns the webhook URL, and promote preserves it). It stores N8N_WEBHOOK_URL + a generated N8N_WEBHOOK_SECRET on the app (encrypted + injected) and RETURNS the secret so you can add a matching `X-Awesomate-Webhook-Secret` header check to the n8n workflow (so the webhook isn't world-callable). The app then calls it via src/lib/n8n.ts callWorkflow(). Node apps only. Only reach for this when the job needs an external app/credential or AI the user already has in n8n \u2014 not for pure in-app logic.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      webhookUrl: external_exports.string().url().describe("The n8n workflow's production webhook URL (from awesomate_n8n_deploy)"),
+      env: external_exports.enum(["dev", "staging", "prod"]).default("dev").describe("Which app environment to wire")
+    }
+  },
+  async ({ appId, webhookUrl, env }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/attach-n8n`, { webhookUrl, env }));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_health",
+  {
+    description: "Probe an app's environments live and report health. Node envs hit /api/ready (200 = deployed + DB up + migrations applied); static hits the root. An env that isn't deployed yet reports unreachable \u2014 expected, not a failure. Use after a deploy to confirm it came up, or when the user says something's down.",
+    inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
+  },
+  async ({ appId }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/health`, {}));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_n8n_provision_pg",
+  {
+    description: "Provision a NEW Postgres database on the user's own Awesomate cPanel hosting and wire it into their n8n as a ready-to-use `postgres` credential their workflows can select. This is a WRITE that creates real infrastructure \u2014 get explicit user approval first. Requires: their n8n builder access (Support Plus+, allow_client_cli_builds) AND the allow_pg_writes consent (403 consent_required \u2192 send them to settingsUrl); AND an Awesomate cPanel hosting account (409 hosting_required otherwise). Limited to 2/day. Returns the new credential id + name, the database/user, and the password ONCE (it lives in the n8n credential, never stored by Awesomate \u2014 tell the user to note or rotate it). After this, build the workflow selecting the returned Postgres credential.",
+    inputSchema: {}
+  },
+  async () => {
+    try {
+      return textResult(await hubPost(requireConfig(), "/api/my-n8n/machine/pg-credentials", {}));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 async function main() {
   try {
     config2 = loadConfig();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.7.3",
-  "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, and n8n automations",
+  "version": "0.8.2",
+  "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",
   "publishConfig": {
@@ -19,7 +19,7 @@
   "scripts": {
     "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --external:node:*",
     "typecheck": "tsc --noEmit",
-    "test": "esbuild src/config.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/config.mjs --external:node:* && node --test test/",
+    "test": "esbuild src/config.ts --bundle --platform=node --target=node18 --format=esm --outfile=test/.build/config.mjs --external:node:* && node --test test/*.test.mjs",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {

package/skill/awesomate-app-builder/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: awesomate-app-builder
+description: Build real things on the user's Awesomate hosting from plain English — a website, a landing page, or a web app with a database. Use when the user says "get started", "what can you do", "build me an app", "make a website / landing page", "I need a form / signup / dashboard", "help", or mentions their Awesomate hosting and wants something built. The first-run greeter for non-technical users. Companion to awesomate-hosting, awesomate-credentials, awesomate-github and awesomate-seo — same connection, same PAT.
+---
+
+# Awesomate App Builder — build real things from plain English
+
+The user is likely **non-technical**. Your job: understand what they actually
+want in plain words, pick the simplest stack that fits, and build + ship it on
+their Awesomate hosting — explaining just enough, never jargon-dumping. Ask
+short questions one or two at a time. Provisioning is consent-free (it's their
+own hosting) but you should always confirm the **stack + name** before creating.
+
+## 0. First run (every session)
+
+1. Run `awesomate_whoami` — everything acts on whichever ACCOUNT this folder
+   resolves to. Every tool response is stamped `account: <slug>`; if it isn't
+   the account the user means, fix the pin/connection first (see the
+   awesomate-hosting skill's multi-account section).
+2. Call `awesomate_app_context` once and cache it. It returns:
+   - `capability.appBuilder` — if **false**, building is Support Plus+. Relay
+     the upgrade suggestion (don't attempt to build); reads still work.
+   - `hasCpanelAccount` — if **false**, they need hosting set up first (hand
+     off to the awesomate-hosting skill).
+   - `firstRun` + `suggestions[]` — on first run, greet warmly and offer the
+     suggestions as a short menu ("Here's what I can do for you… what would
+     you like?"). Don't dump all tools.
+   - `apps[]` — their existing apps; offer to continue one instead of starting
+     over.
+
+## 1. Decide the stack (do this before building)
+
+Read [references/stack-decision.md](references/stack-decision.md) — it's the
+decision brain. The short version, matched to what they say:
+
+- **"I have a WordPress site" / blog / regular content / needs to rank on
+  Google** → **WordPress** (hand to the awesomate-hosting skill). Then use
+  **awesomate-seo** so it's findable.
+- **Shop / sell products** → **WordPress + WooCommerce**.
+- **Landing page / capture leads / one-pager / "just needs to look good and
+  be found"** → **static site** (`kind: 'static'`). Fastest possible load,
+  no database. This is the right default for marketing pages — don't reach for
+  a full app.
+- **App with logins / custom logic / a dashboard / an API** → **Node app**
+  (`kind: 'node'`). Pick **postgres** when the data is relational / needs
+  concurrency / JSON / analytics; **mysql** for simple cases.
+
+**Never default to WordPress.** Match the tech to the job; prefer the least
+machinery that does it.
+
+### When to use their n8n instead of coding a backend
+If the app needs to **send an email, look something up in their apps (Sheets,
+CRM, a database), or use AI** — their **own n8n** is often the fastest path,
+because their credentials are already connected there. Check the credential
+inventory (`GET /api/my-n8n/machine/credentials`) and say e.g. *"you already
+have Gmail connected in n8n — want the form to email you through that?"* Use
+the **awesomate-n8n** skill to build the workflow, then store its webhook URL
+in the app (see the awesomate-credentials skill) and call it from the app.
+Don't reach for n8n for pure in-app logic with no external app/credential — a
+webhook round-trip adds latency and a failure point for nothing.
+
+## 2. The build loop
+
+Work in short phases, keeping the user in plain language. **Dev is the default
+target; never touch prod without an explicit ask.**
+
+1. **Discovery** — one or two plain questions until you know the job + the
+   stack (§1). Don't over-interview.
+2. **Design** — say back, in a sentence or two, what you'll build and the stack
+   you recommend. Get a yes.
+3. **Confirmation gate** — confirm the **name** (2–16 lowercase letters/digits,
+   starts with a letter — becomes the subdomain + db names) and the **stack**,
+   then call `awesomate_app_create` (`appSlug`, `kind`, and for node `dbEngine`).
+   It returns **202** with an `appId` + subdomain(s); poll `awesomate_app_get`
+   until `status` is `active` (or `failed` — read `provision_error`, explain
+   plainly).
+4. **Implementation** — build the actual code/content locally against the
+   template. Handle **secrets** only via the **awesomate-credentials** skill
+   (encrypted + injected, never committed/echoed). Wire **version control**
+   from the first commit via **awesomate-github**. If it needs email/lookup/AI,
+   attach n8n (§"when to use n8n").
+5. **Testing** — deploy to **dev** (`git push` to `dev`), then
+   `awesomate_app_health` to confirm it came up (Node: `/api/ready`). Show the
+   user the live dev URL and let them try it. Iterate on dev until they're happy.
+6. **Wrap-up / promote** — only when the user approves, promote **dev → staging
+   → main** (merge + push per branch). `awesomate_app_deploy` reports the
+   branch→env map. Prod is `main`.
+
+**Promote / rollback (git-based):** promoting is merging the tested branch
+forward (`dev`→`staging`→`main`); rolling back is `git revert` of the bad
+commit + push (redeploys the previous good state), or redeploy an earlier good
+SHA. Always `awesomate_app_health` after a promote. Static sites ship their
+files directly (no build step).
+
+## 3. Hard rules
+
+- Non-technical user: explain in plain words, one or two short questions at a
+  time, no unexplained jargon. Recommend; don't quiz them on architecture.
+- Confirm the stack + name before `awesomate_app_create`. Default the target
+  to **dev**; never push to prod without an explicit ask.
+- A `403` on a write = plan gate (Support Plus+). Offer an upgrade, don't retry.
+- Never invent that a capability exists — read `awesomate_app_context` first.
+- Never print a secret or commit a `.env` (the credentials + github skills
+  enforce this).

package/skill/awesomate-app-builder/references/stack-decision.md

@@ -0,0 +1,52 @@
+# Stack decision — match the tech to the job
+
+Bias toward whatever **loads fastest and is the least machinery** for the need.
+Ask at most 2–3 plain questions, then recommend a stack in one sentence and
+confirm before building. **Never default to WordPress.**
+
+## The map
+
+| What the user is really trying to do | Stack | Why / how |
+|---|---|---|
+| "I already have a WordPress site" / a blog / publishes content regularly / **wants to rank on Google & AI** | **WordPress** | Best CMS for indexable content, sitemaps, schema. Hand to the awesomate-hosting skill to provision, then run **awesomate-seo**. |
+| Sell products / online shop | **WordPress + WooCommerce** | Reuse the `woo-agent-storefront` (AI-shopping feeds + `llms.txt`) and `woo-catalog-perfection` skills. |
+| A landing page / capture leads / a one-pager / "just needs to look good and be found" | **static site** (`kind: 'static'`) | Served straight from the cPanel docroot — no database, no server process, fastest load. Add SEO + a lead form (below). The right default for marketing pages. |
+| A tool/app with **logins, custom logic, a dashboard, or an API** | **Node app** (`kind: 'node'`) | A real backend + database. |
+
+### Within a Node app: which database?
+- **postgres** — relational data with relationships, concurrency, JSON columns,
+  or analytics/AI features. The modern default for a real app.
+- **mysql** — simple/legacy needs, or when they already know MySQL.
+- Provisioned automatically by `awesomate_app_create`; the app's `.env` gets
+  `DB_ENGINE`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASS`, and a
+  ready-to-use `DATABASE_URL`.
+
+## Questions that resolve the choice fast
+1. "Is this mainly a **page people read** (marketing, blog, shop) or a **tool
+   people use** (log in, do things, see their own data)?" → read → WP/static;
+   tool → Node.
+2. If read: "Do you need to **publish/edit content often** (blog, many pages)?"
+   → yes → WordPress; no → static.
+3. If tool: "Will people **sign in** or does it store data per user?" → yes →
+   Node + postgres.
+
+## Does it need a backend job? Prefer their n8n.
+If the ask includes **email someone, look something up in their apps, save a
+lead somewhere, or use AI**, that's usually a job for their **own n8n** — their
+credentials are already connected there, so there's nothing new to set up.
+
+- Check `GET /api/my-n8n/machine/credentials` (names/types only) and offer what
+  they already have: *"You've got Gmail + Google Sheets connected — want the
+  form to email you and add the lead to a sheet?"*
+- Build the workflow with the **awesomate-n8n** skill (webhook trigger →
+  action), take its **webhook URL**, and store it in the app as
+  `N8N_WEBHOOK_URL` via the **awesomate-credentials** skill. The static
+  template's lead form and the Node template's `src/lib/n8n.ts` both POST there.
+- Skip n8n for pure in-app logic with no external app/credential/AI — a webhook
+  round-trip just adds latency and a failure point.
+
+## Always, for any public site
+Offer **awesomate-seo** (meta/OG tags, `sitemap.xml`, `robots.txt`, JSON-LD, a
+general `llms.txt`) so it's findable by search engines *and* AI assistants — and
+**awesomate-github** so their work is version-controlled and deploys on push
+from day one.

package/skill/awesomate-credentials/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: awesomate-credentials
+description: Safely capture and store API keys, tokens, database URLs and other secrets for the user's Awesomate apps — encrypted in the hub and injected into the app's .env, never committed to git, never echoed back. Use whenever the user pastes something that looks like a secret, says "here's my API key", "add this key", "store this secret / token / password", "save my credentials", or drops a key into a file. Companion to awesomate-app-builder.
+---
+
+# Awesomate Credentials — handle secrets safely
+
+Non-technical users will hand you secrets the easy way: pasted into chat or
+dropped in a file. Your job is to get them into the right place **safely** and
+never leak them.
+
+## The rules (non-negotiable)
+
+1. **Never echo a secret value back** — not in a summary, not in a code block,
+   not "just to confirm". Confirm with the **key name + a redacted preview
+   only** (e.g. `OPENAI_API_KEY = sk-…redacted`).
+2. **Never commit a secret.** App secrets live in `.env` (gitignored) or the
+   hub's encrypted store — never in tracked files. If you see a secret in code
+   about to be committed, stop and move it.
+3. **A secret pasted in chat is exposed.** Store it, then tell the user plainly:
+   *"Because that key was pasted into the chat, treat it as exposed — rotate it
+   when convenient, and next time drop it in the inbox file (below) instead."*
+4. **Prefer the file-drop path** for anything sensitive (below).
+
+## Detect and offer
+
+If the user's message contains something shaped like a secret — `sk-…`,
+`ghp_`/`gho_…`, `AKIA…`, `xox[bp]-…`, a bearer token, a `postgres://…` /
+`mysql://…` URL, or they say "here's my key" — don't just carry on. Offer to
+store it safely: *"I'll store that as an encrypted secret for your app and keep
+it out of the code — what's it for?"* Then store it (below) and redact it from
+your own responses.
+
+## Where a secret goes
+
+Read [references/where-secrets-go.md](references/where-secrets-go.md) for the
+full map. Short version:
+
+- **A running app needs it** (API key the backend calls, a DB URL) → store it on
+  the app with **`awesomate_app_set_env`** (tool). It's encrypted in the hub AND
+  written to the app's `.env` (0600), then the app restarts. Ask which env
+  (default `dev`). Node apps only — static sites have no server env.
+- **A personal key just to keep** (not an app runtime secret) → your local
+  `~/.config/api-keys.env` (chmod 600), with a note if it was pasted in chat.
+- **Never** a tracked file, a commit, or the chat.
+
+## The safe file-drop flow (preferred)
+
+For anything sensitive, steer the user away from pasting in chat:
+
+1. Tell them: *"Create a file `.awesomate/secret-inbox.txt` in your project and
+   paste the value there — I'll grab it and wipe the file."* (`.awesomate/` is
+   gitignored by the github skill.)
+2. Read the file to capture the value, call `awesomate_app_set_env` to store it,
+   then **scrub the file**:
+   `node ~/.claude/skills/awesomate-credentials/scripts/capture-secret.mjs .awesomate/secret-inbox.txt`
+   — this securely overwrites and removes it so the plaintext doesn't linger.
+3. Confirm with the key name only.
+
+## After storing
+Tell the user what you set (key + env), that it's encrypted and injected, and —
+if it came through the chat — the one-line rotation nudge. Never restate the value.

package/skill/awesomate-credentials/references/where-secrets-go.md

@@ -0,0 +1,26 @@
+# Where a secret goes
+
+| The secret is… | Put it… | How |
+|---|---|---|
+| An app runtime secret (API key the backend calls, a third-party token, a DB URL) | The app's `.env` **and** the hub's encrypted store | `awesomate_app_set_env` (tool) — encrypts hub-side + injects into `.env` (0600) + restarts the app |
+| An n8n webhook URL the app calls (`N8N_WEBHOOK_URL`) | Same as above | `awesomate_app_set_env` — it's not secret-secret, but it belongs in `.env` with the rest |
+| A personal key the user just wants kept (not used by a running app) | `~/.config/api-keys.env` (chmod 600) | Append `KEY=value`; add a `# pasted in chat <date> — rotate` note if it came through chat |
+| Anything, ever | **NOT** in code, a tracked file, a commit, or the chat transcript | — |
+
+## Why two places for app secrets
+The hub's encrypted `hosted_app_env_secrets` row is the **durable source of
+truth** (survives redeploys, is auditable, uses the same AES-256-GCM as the DB
+password). The host `.env` is what the **running process actually reads**
+(`dotenv/config`). `awesomate_app_set_env` writes both in one step.
+
+## Redaction pattern
+When you confirm, show at most a short prefix:
+- `sk-proj-abc…` → `OPENAI_API_KEY = sk-proj-…redacted`
+- a DB URL → `DATABASE_URL = postgresql://…redacted`
+Never the full value.
+
+## Rotation note (chat-pasted keys)
+A value pasted into the conversation is in the transcript — treat it as exposed.
+After storing it, tell the user once: *"rotate this when convenient, and next
+time use the `.awesomate/secret-inbox.txt` drop so it stays out of the chat."*
+High-value keys (payment, production DB, cloud root) — recommend rotating now.

package/skill/awesomate-credentials/scripts/capture-secret.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Securely scrub a secret-inbox file after its value has been captured and
+ * stored (via awesomate_app_set_env). Overwrites the file contents with random
+ * bytes, then removes it, so the plaintext secret doesn't linger on disk.
+ *
+ * Usage:  node capture-secret.mjs <path-to-inbox-file>
+ *
+ * Prints only a non-sensitive confirmation — never the file contents. The
+ * capturing step (reading the value + calling awesomate_app_set_env) is done by
+ * Claude with the MCP tool; this script's single job is the safe wipe.
+ */
+
+import { statSync, writeFileSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+
+const target = process.argv[2];
+if (!target) {
+  console.error('usage: node capture-secret.mjs <path-to-inbox-file>');
+  process.exit(2);
+}
+
+let size = 0;
+try {
+  size = statSync(target).size;
+} catch {
+  console.log(`nothing to scrub: ${target} does not exist`);
+  process.exit(0);
+}
+
+try {
+  // Overwrite with random bytes of the same length, then delete. Best-effort
+  // (a single pass is enough on modern storage for this threat model — the
+  // point is not leaving the plaintext readable at the known path).
+  if (size > 0) writeFileSync(target, randomBytes(size), { flag: 'w' });
+  rmSync(target, { force: true });
+  console.log(`scrubbed ${target} (${size} bytes overwritten + removed)`);
+} catch (err) {
+  console.error(`failed to scrub ${target}: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+}

package/skill/awesomate-github/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: awesomate-github
+description: Set up GitHub version control for the user's app with zero Git knowledge required — connect their GitHub once, then create the repo, .gitignore, first commit and push-to-deploy for them. Use when the user says "connect GitHub", "back up my app", "save my work", "set up version control", "put this on GitHub", or after building an app when it should be version-controlled. Companion to awesomate-app-builder.
+---
+
+# Awesomate GitHub — version control for people who don't know Git
+
+Assume the user knows **nothing** about Git or GitHub. Never make them run raw
+git commands or understand branches/remotes. You drive everything through the
+`gh` CLI and the bundled script; you ask only simple, plain questions.
+
+## 0. First run
+
+1. **Is `gh` installed?** Run `gh --version`. If missing, give the one-line
+   install for their OS and stop until it's there:
+   - macOS: `brew install gh`
+   - Debian/Ubuntu: `sudo apt install gh` (or https://cli.github.com)
+   - Windows: `winget install --id GitHub.cli`
+2. **Are they connected to GitHub?** Run `gh auth status`. If not:
+   - Say plainly: *"I'll connect you to GitHub — I'll show a link and a short
+     code. Open the link, paste the code, and click approve. No password, no
+     tokens to copy."*
+   - Have them run `gh auth login` (choose GitHub.com → HTTPS → "Login with a
+     web browser"). It prints a one-time code + opens the device-flow page.
+     Wait for them to finish, then re-check `gh auth status`.
+   - Never ask them for a token or paste one yourself.
+
+## 1. Set up a project (the whole thing, via one script)
+
+Once `gh auth status` is good, run the scaffolder from the project folder:
+
+```
+node ~/.claude/skills/awesomate-github/scripts/github-setup.mjs <repo-name> [--public]
+```
+
+It does, in order (all idempotent — safe to re-run):
+1. **Secret guard** — refuses if a `.env` or an obvious secret (key/token
+   shapes) is about to be tracked. Fix that first (use the
+   awesomate-credentials skill) — never commit secrets.
+2. Ensures `.gitignore` exists and excludes `.env` (creates/appends if needed).
+3. `git init` (if needed), stages everything, makes the first commit.
+4. `gh repo create <name> --private --source=. --push` (private by default;
+   `--public` to override). Personal accounts work — no org needed.
+5. Prints the repo URL.
+
+Ask only: **"What should we call this project?"** (repo name) and, if relevant,
+**"Keep it private?"** (default yes). Derive a sensible kebab-case repo name
+from what they tell you.
+
+## 2. Push-to-deploy (for apps built with awesomate-app-builder)
+
+If this is a Node app from the app builder, wire the deploy secrets so a push
+ships it (GitHub Actions → cPanel). The app builder / hub provides the SSH
+deploy values; set them as repo secrets with `gh secret set` (the script does
+this when run with `--deploy-secrets` and the values are available in the
+environment). Then: **push to `dev` → deploys dev; `main` → deploys prod.**
+Explain it as *"save your work = it goes live"* — don't lecture on branches.
+
+## 3. Everyday use (plain language)
+
+- "Save my work" → stage, commit with a short message you write for them, push.
+- "Put it live" → push to the right branch (dev/staging/main) and tell them the URL.
+- Always write clear commit messages **for** them; don't ask them to.
+
+## Hard rules
+- Never commit a secret or a `.env`. The script's secret guard is a backstop,
+  not a licence to skip checking. If you spot a secret, route it through the
+  awesomate-credentials skill instead.
+- Never ask the user for a GitHub token or password; the device-flow is the
+  only auth path.
+- Default repos to **private**.

package/skill/awesomate-github/references/github-basics.md

@@ -0,0 +1,12 @@
+# GitHub, in four sentences (only surface if the user asks)
+
+- **A repository ("repo")** is just a folder of your project that GitHub keeps a
+  safe, versioned copy of — every save is remembered, so you can always go back.
+- **A commit** is one saved snapshot with a short note about what changed.
+- **Pushing** sends your latest commits up to GitHub (the backup + the thing
+  that triggers deploys).
+- **Branches** are parallel copies; here they map to environments — `dev` is
+  your workspace, `main` is what's live — so "push to main" means "make it live".
+
+You never need to run Git commands yourself — just tell me "save my work" or
+"put it live" and I'll do the right thing.

package/skill/awesomate-github/scripts/github-setup.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Zero-knowledge GitHub scaffolder. Idempotent — safe to re-run.
+ *
+ *   node github-setup.mjs <repo-name> [--public] [--path <dir>] [--deploy-secrets]
+ *
+ * Steps: verify gh auth → ensure .gitignore excludes .env → SECRET GUARD
+ * (refuse to commit a .env or an obvious key/token) → git init + first commit →
+ * `gh repo create --source=. --push` (private by default; personal accounts OK)
+ * → optionally seed deploy Actions secrets from the environment.
+ *
+ * Deploy secrets are read from env vars (SSH_HOST/SSH_USER/SSH_PRIVATE_KEY), not
+ * argv, so they never appear in `ps`. Prints only non-sensitive output.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const positional = args.filter((a) => !a.startsWith('--'));
+const repoName = positional[0];
+const pathIdx = args.indexOf('--path');
+const cwd = pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : process.cwd();
+const isPublic = flags.has('--public');
+const wantDeploySecrets = flags.has('--deploy-secrets');
+
+if (!repoName || !/^[a-z0-9][a-z0-9._-]{0,99}$/i.test(repoName)) {
+  console.error('usage: node github-setup.mjs <repo-name> [--public] [--path <dir>] [--deploy-secrets]');
+  console.error('repo-name: letters/digits/._- , starts alphanumeric');
+  process.exit(2);
+}
+
+function run(cmd, cmdArgs, opts = {}) {
+  return spawnSync(cmd, cmdArgs, { cwd, encoding: 'utf8', ...opts });
+}
+function die(msg) {
+  console.error(`\n✗ ${msg}`);
+  process.exit(1);
+}
+
+// --- 0. gh present + authenticated ----------------------------------------
+if (run('gh', ['--version']).status !== 0) {
+  die("GitHub CLI 'gh' isn't installed. Install it (macOS: brew install gh) then re-run.");
+}
+if (run('gh', ['auth', 'status']).status !== 0) {
+  die("You're not connected to GitHub yet. Run: gh auth login  (GitHub.com → HTTPS → Login with a web browser), then re-run this.");
+}
+
+// --- 1. .gitignore excludes .env ------------------------------------------
+const giPath = join(cwd, '.gitignore');
+const needed = ['.env', '.env.local', '*.log', '.DS_Store', 'node_modules/'];
+let gi = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
+const have = new Set(gi.split(/\r?\n/).map((l) => l.trim()));
+const toAdd = needed.filter((n) => !have.has(n));
+if (toAdd.length) {
+  gi = (gi.endsWith('\n') || gi === '' ? gi : gi + '\n') + toAdd.join('\n') + '\n';
+  writeFileSync(giPath, gi);
+  console.log(`• .gitignore: added ${toAdd.join(', ')}`);
+}
+
+// --- init early so the secret guard can inspect the staged set ------------
+if (!existsSync(join(cwd, '.git'))) {
+  if (run('git', ['init', '-b', 'main']).status !== 0) die('git init failed.');
+  console.log('• initialised a git repo (branch: main)');
+}
+if (run('git', ['add', '-A']).status !== 0) die('git add failed.');
+
+// --- 2. SECRET GUARD -------------------------------------------------------
+const staged = run('git', ['diff', '--cached', '--name-only']).stdout.split(/\r?\n/).filter(Boolean);
+const envLeak = staged.find((f) => /(^|\/)\.env(\.|$)/.test(f) && !/\.env\.example$/.test(f));
+if (envLeak) {
+  die(`Refusing to commit '${envLeak}' — that's a secrets file. It's now gitignored; run \`git rm --cached ${envLeak}\` and re-run. Store secrets via the awesomate-credentials skill, never in the repo.`);
+}
+const SECRET_RE = /(sk-[A-Za-z0-9]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|xox[bp]-[A-Za-z0-9-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+for (const f of staged) {
+  const abs = join(cwd, f);
+  try {
+    if (statSync(abs).size > 512 * 1024) continue; // skip large/binary
+    if (SECRET_RE.test(readFileSync(abs, 'utf8'))) {
+      die(`Refusing to commit '${f}' — it contains something shaped like a secret (API key / token / private key). Move it out (use the awesomate-credentials skill) and re-run.`);
+    }
+  } catch {
+    /* unreadable/binary — skip */
+  }
+}
+
+// --- 3. first commit (only if there's anything to commit) -----------------
+if (run('git', ['diff', '--cached', '--quiet']).status !== 0) {
+  if (run('git', ['commit', '-m', 'Initial commit']).status !== 0) die('git commit failed.');
+  console.log('• made the first commit');
+} else {
+  console.log('• nothing new to commit');
+}
+
+// --- 4. create the GitHub repo + push -------------------------------------
+const already = run('git', ['remote', 'get-url', 'origin']);
+if (already.status === 0) {
+  console.log(`• remote already set: ${already.stdout.trim()}`);
+  run('git', ['push', '-u', 'origin', 'HEAD']);
+} else {
+  const vis = isPublic ? '--public' : '--private';
+  const create = run('gh', ['repo', 'create', repoName, vis, '--source=.', '--remote=origin', '--push']);
+  if (create.status !== 0) {
+    die(`gh repo create failed: ${(create.stderr || create.stdout || '').trim()}`);
+  }
+  console.log(`• created ${isPublic ? 'public' : 'private'} repo and pushed`);
+}
+
+// --- 5. deploy secrets (values from env, never argv) ----------------------
+if (wantDeploySecrets) {
+  for (const name of ['SSH_HOST', 'SSH_USER', 'SSH_PRIVATE_KEY']) {
+    const val = process.env[name];
+    if (!val) {
+      console.log(`• skip deploy secret ${name} (not in environment)`);
+      continue;
+    }
+    const set = run('gh', ['secret', 'set', name], { input: val });
+    console.log(set.status === 0 ? `• set deploy secret ${name}` : `• FAILED to set ${name}: ${(set.stderr || '').trim()}`);
+  }
+}
+
+// --- done ------------------------------------------------------------------
+const url = run('gh', ['repo', 'view', '--json', 'url', '-q', '.url']).stdout.trim();
+console.log(`\n✓ Done. Your project is on GitHub${url ? `: ${url}` : ''}.`);

package/skill/awesomate-seo/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: awesomate-seo
+description: Make the user's site findable — by Google AND by AI assistants. Adds title/meta/Open Graph tags, sitemap.xml, robots.txt, canonical tags, JSON-LD structured data, and a general llms.txt. Works for static sites, Node apps, and WordPress. Use when the user says "SEO", "get found on Google", "rank higher", "make my site discoverable", "sitemap", "meta tags", "schema", or after building/changing a public site. Companion to awesomate-app-builder.
+---
+
+# Awesomate SEO — get found on Google and AI
+
+Search engines and AI assistants both need machine-readable signals. This skill
+adds them to any site the user has. Treat SEO as **ongoing**, not one-shot:
+bake it in when a page is built, and re-run the relevant parts whenever content
+or structure changes.
+
+Be honest about limits: these are the signals that *let* you rank and be cited
+— they don't *guarantee* placement. Never promise rankings.
+
+## 0. What kind of site is this?
+
+- **Static site or Node app** (from awesomate-app-builder) → you write the files
+  directly into the project (below), commit, and deploy.
+- **WordPress** → drive it through WP-CLI via the awesomate-hosting skill
+  (`wp` passthrough). Install a free SEO plugin + let it generate the sitemap
+  rather than hand-writing files (see §WordPress).
+- **A shop (WooCommerce)** → also use the `woo-agent-storefront` skill for
+  AI-shopping feeds + a store `llms.txt`, and `woo-catalog-perfection` for
+  product-data quality. This skill covers the site-level SEO around it.
+
+## 1. Static / Node — write these
+
+Follow [references/seo-checklist.md](references/seo-checklist.md) for exact
+formats + length limits. In short, per site:
+
+1. **`<head>` tags** on every page: unique `<title>` (≤60 chars), meta
+   description (≤155), canonical `<link>`, Open Graph (`og:title/description/
+   image/url/type`) and `twitter:card`. The static-landing template ships
+   `{{...}}` placeholders — fill them with real values.
+2. **`robots.txt`** at the site root — allow crawling, point to the sitemap.
+3. **`sitemap.xml`** at the root — list every real URL with `<loc>` (+ `<lastmod>`).
+4. **JSON-LD** (`<script type="application/ld+json">`) — the right schema.org
+   type (`Organization` / `WebSite` / `Product` / `Article` / `LocalBusiness`).
+5. **`llms.txt`** at the root — a short, plain-markdown summary of what the
+   site/business is and its key pages, so AI assistants can understand and cite
+   it. (This is the general, non-shop counterpart to the Woo `llms.txt`.)
+
+Then commit + deploy (awesomate-github). On content changes, update the
+affected `<head>` tags, `sitemap.xml` `<lastmod>`, and `llms.txt`.
+
+## 2. WordPress
+
+Through the awesomate-hosting skill's `wp` passthrough:
+- Install + activate a free SEO plugin (e.g. `wp plugin install wordpress-seo
+  --activate` for Yoast, or the user's preference). It manages titles/meta,
+  Open Graph, and the XML sitemap.
+- Confirm the sitemap is live (`/sitemap_index.xml` or `/sitemap.xml`) and
+  `robots.txt` references it.
+- Add an `llms.txt` at the site root for AI discoverability (the plugin won't).
+- WordPress is the recommended stack precisely when SEO/organic reach matters —
+  lean into it here.
+
+## 3. Verify
+- `robots.txt` and `sitemap.xml` (or the WP sitemap) return 200 at the root.
+- Each key page has a unique title + description and valid JSON-LD (no syntax
+  errors — a broken `application/ld+json` block is worse than none).
+- `llms.txt` exists and is accurate.
+Tell the user the next step is submitting the sitemap in Google Search Console
+(you can't do that for them) — offer a one-paragraph how-to if they want it.
+
+## Hard rules
+- Never fabricate content, reviews, or business facts to "help SEO".
+- Never claim these guarantee a ranking — they make the site *eligible* and
+  *legible*, to search engines and AI both.
+- Invalid structured data is a bug — validate the JSON before shipping.

package/skill/awesomate-seo/references/seo-checklist.md

@@ -0,0 +1,72 @@
+# SEO checklist — exact formats
+
+## `<head>` (every page, unique per page)
+```html
+<title>Primary keyword — Brand</title>              <!-- ≤60 chars -->
+<meta name="description" content="…">                <!-- ≤155 chars, compelling -->
+<link rel="canonical" href="https://DOMAIN/PATH">
+<meta property="og:title" content="…">
+<meta property="og:description" content="…">
+<meta property="og:type" content="website">          <!-- or article/product -->
+<meta property="og:url" content="https://DOMAIN/PATH">
+<meta property="og:image" content="https://DOMAIN/og.png">  <!-- 1200×630 ideally -->
+<meta name="twitter:card" content="summary_large_image">
+```
+
+## `robots.txt` (site root)
+```
+User-agent: *
+Allow: /
+Sitemap: https://DOMAIN/sitemap.xml
+```
+Only `Disallow:` paths that genuinely shouldn't be indexed (admin, cart,
+thank-you). Don't block CSS/JS.
+
+## `sitemap.xml` (site root)
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://DOMAIN/</loc><lastmod>YYYY-MM-DD</lastmod></url>
+  <url><loc>https://DOMAIN/about</loc><lastmod>YYYY-MM-DD</lastmod></url>
+</urlset>
+```
+List only real, canonical, indexable URLs (no dupes, no query-string variants).
+
+## JSON-LD (in `<head>` or end of `<body>`)
+Pick the type that fits; validate before shipping.
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  "name": "Brand",
+  "url": "https://DOMAIN/",
+  "logo": "https://DOMAIN/logo.png"
+}
+</script>
+```
+Common types: `WebSite` (+ `SearchAction`), `Organization` / `LocalBusiness`
+(add `address`, `telephone`, `openingHours`), `Product` (`offers`, `brand`,
+`gtin`), `Article` (`headline`, `datePublished`, `author`), `FAQPage`.
+
+## `llms.txt` (site root — AI discoverability)
+Plain markdown so assistants can read + cite the site. Keep it current.
+```
+# Brand — what we do
+
+One-paragraph plain-English description of the business/product and who it's for.
+
+## Key pages
+- [Home](https://DOMAIN/): …
+- [Pricing](https://DOMAIN/pricing): …
+- [Contact](https://DOMAIN/contact): …
+
+## Facts
+- Location, hours, contact — only true, verifiable facts.
+```
+
+## Length + quality rules
+- Titles ≤60, descriptions ≤155 chars, each unique across the site.
+- One `<h1>` per page; descriptive; not keyword-stuffed.
+- Alt text on meaningful images.
+- Every claim in `llms.txt`/JSON-LD must be true — never invent facts or reviews.