@awesomate/hosting-mcp 0.27.0 → 0.30.0

package/dist/index.js

@@ -40263,6 +40263,12 @@ async function knowledgeSources(config3, args) {
       if (!args.sourceId || !Array.isArray(args.tags)) return { error: "invalid_request", note: "tag needs sourceId and tags (the full replacement list of free-form tags; collections are unaffected)" };
       return await hubPatch(config3, `/api/knowledge/sources/${encodeURIComponent(args.sourceId)}`, { tags: args.tags });
     }
+    if (args.action === "rename") {
+      if (!args.sourceId || typeof args.title !== "string" || !args.title.trim()) {
+        return { error: "invalid_request", note: "rename needs sourceId and a non-empty title" };
+      }
+      return await hubPatch(config3, `/api/knowledge/sources/${encodeURIComponent(args.sourceId)}`, { title: args.title.trim() });
+    }
     if (args.action === "set_visibility") {
       const ids = args.sourceIds?.length ? args.sourceIds : args.sourceId ? [args.sourceId] : [];
       if (!ids.length || !args.visibility) return { error: "invalid_request", note: "set_visibility needs sourceId (or sourceIds) and visibility" };
@@ -40968,6 +40974,12 @@ var TITLES = {
   awesomate_app_get: "Get app details",
   awesomate_app_scaffold: "Get app scaffold guide",
   awesomate_app_deploy_info: "Get app deploy briefing",
+  awesomate_app_update: "Link repo to app",
+  awesomate_app_repo_check: "Report repo check",
+  awesomate_app_deploy_event: "Record deploy outcome",
+  awesomate_app_migration_plan: "Get migration checklist",
+  awesomate_app_capacity: "Check hosting capacity",
+  awesomate_app_domain_attach: "Attach hostname to app",
   awesomate_app_health: "Check app health",
   awesomate_app_run_state: "Start or stop an app environment",
   awesomate_app_set_env: "Set app secret",
@@ -41687,7 +41699,7 @@ server.registerTool(
   "awesomate_app_get",
   {
     annotations: annotate("awesomate_app_get", READ_ONLY),
-    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).",
+    description: "Get one app plus its environments (subdomains, ports, db engine/name, deploy + health state) and any hostnames of the user's own attached to them. 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 }) => {
@@ -41724,12 +41736,15 @@ server.registerTool(
   "awesomate_app_scaffold",
   {
     annotations: annotate("awesomate_app_scaffold", READ_ONLY),
-    description: "Fetch the app's starter files (its template rendered against the live app metadata \u2014 subdomains, control-plane URL, repo \u2014 with placeholders already substituted). Call after awesomate_app_create reaches status=active: write each returned file into a fresh local project folder at its relative path, then run npm install (Node apps) and follow the bundled CLAUDE.md. This is how the starter code gets onto the user's machine \u2014 don't reconstruct templates by hand.",
-    inputSchema: { appId: external_exports.number().int().positive().describe("The app id from awesomate_app_create / _list") }
+    description: "Fetch the app's starter files (its template rendered against the live app metadata \u2014 subdomains, control-plane URL, repo \u2014 with placeholders already substituted). Call after awesomate_app_create reaches status=active: write each returned file into a fresh local project folder at its relative path, then run npm install (Node apps) and follow the bundled CLAUDE.md. This is how the starter code gets onto the user's machine \u2014 don't reconstruct templates by hand. mode 'adopt' is for a repo that ALREADY exists (Replit, Lovable, anything): it returns only the plumbing (.github/workflows/deploy.yml, .awesomate.json with the deploy contract, scripts/security-check.mjs, scripts/awesomate-migrate.mjs, AWESOMATE.md) to write into that repo without touching its code. Run awesomate_app_repo_check first so the deploy block is pre-filled from the check.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id from awesomate_app_create / _list"),
+      mode: external_exports.enum(["full", "adopt"]).default("full").describe("'full' = the whole starter for a new app; 'adopt' = plumbing only for an existing repo")
+    }
   },
-  async ({ appId }) => {
+  async ({ appId, mode }) => {
     try {
-      return textResult(await hubGet(requireConfig(), `/api/my-apps/apps/${appId}/scaffold`));
+      return textResult(await hubGet(requireConfig(), `/api/my-apps/apps/${appId}/scaffold${mode === "adopt" ? "?mode=adopt" : ""}`));
     } catch (err) {
       return errorResult(err);
     }
@@ -41739,7 +41754,7 @@ server.registerTool(
   "awesomate_app_deploy_info",
   {
     annotations: annotate("awesomate_app_deploy_info", READ_ONLY),
-    description: "READ-ONLY deploy briefing \u2014 this never deploys anything (deploys happen via git push). Reports how to deploy an app, its per-env targets, last-deploy/health state, and how to promote (dev\u2192staging\u2192main) or roll back (git revert + push). Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions \u2192 cPanel). Use the awesomate-github skill to wire push-to-deploy the first time.",
+    description: "READ-ONLY deploy briefing \u2014 this never deploys anything (deploys happen via git push). Reports how to deploy an app, its per-env targets, last-deploy/health state, whether a deploy key is registered, and how to promote (dev\u2192staging\u2192main) or roll back (git revert + push). Node apps deploy via git push (dev/staging/main \u2192 GitHub Actions builds on its runner \u2192 artefacts shipped to cPanel; nothing builds on the account). First-time wiring is awesomate-github/scripts/deploy-key.mjs <appId>, no ticket needed. For an existing repo being moved from Replit or Lovable, start with awesomate_app_migration_plan.",
     inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
   },
   async ({ appId }) => {
@@ -41750,6 +41765,130 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_app_update",
+  {
+    annotations: annotate("awesomate_app_update", MUTATING),
+    description: "Link an app to the GitHub repo it deploys from and record where the code came from. Call it as soon as the repo is known (owner/repo) for an app being moved from Replit, Lovable or any existing codebase; deploy-key.mjs also calls it for you when it sets the repo secrets. autoTickets:false turns off the hub's automatic support tickets for this app (they are on by default and open a Desk ticket when a rule fires: a committed secret, a blocker reported three times, a deploy failing three times in a day).",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      githubRepo: external_exports.string().min(3).max(255).optional().describe("'owner/repo' (a github.com URL is accepted and trimmed)"),
+      sourcePlatform: external_exports.enum(["scaffold", "replit", "lovable", "other"]).optional().describe("Where the code came from"),
+      deployKeyFingerprint: external_exports.string().min(1).max(128).optional().describe("Set by deploy-key.mjs; the fingerprint of the per-app deploy key"),
+      readyPath: external_exports.string().regex(/^\/[A-Za-z0-9_\-./]{0,120}$/).optional().describe("Readiness route the health checks probe, default /api/ready"),
+      autoTickets: external_exports.boolean().optional().describe("Whether the hub may open support tickets about this app automatically (default true)")
+    }
+  },
+  async ({ appId, ...body }) => {
+    try {
+      return textResult(await hubPatch(requireConfig(), `/api/my-apps/apps/${appId}`, body));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_repo_check",
+  {
+    annotations: annotate("awesomate_app_repo_check", MUTATING),
+    description: "Report the JSON produced by `node ~/.claude/skills/awesomate-app-builder/scripts/migrate-check.mjs [--fix]` for the repo this app deploys from. The hub stores it, updates the migration plan (repo_checked becomes done when no blockers remain), pre-fills the deploy block that awesomate_app_scaffold mode 'adopt' returns, and applies its ticket rules: a committed secret opens a Desk ticket at once; the same blocker reported three times opens one; otherwise nothing is sent. Fix blockers in the code, re-run the script, report again. Never paste source code into this call; the report carries rule ids, file paths and one-line details only.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      report: external_exports.object({
+        version: external_exports.number().optional(),
+        platform: external_exports.string().optional(),
+        findings: external_exports.array(external_exports.object({ id: external_exports.string(), severity: external_exports.enum(["info", "warn", "blocker"]), title: external_exports.string().optional(), detail: external_exports.string().optional(), file: external_exports.string().optional(), fix: external_exports.string().optional() })).max(200),
+        detected: external_exports.record(external_exports.unknown()).optional(),
+        deploy: external_exports.record(external_exports.unknown()).optional()
+      }).passthrough().describe("The script output, passed through unchanged")
+    }
+  },
+  async ({ appId, report }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/repo-check`, { report }));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_deploy_event",
+  {
+    annotations: annotate("awesomate_app_deploy_event", MUTATING),
+    description: "Record the outcome of a deploy to one environment, after `gh run watch` finishes or the manual artefact deploy exits. Pass outcome 'failure' with the failing step name (from gh run view --log-failed) or 'success' with the commit sha. The hub updates the plan and, after three failures on one env inside a day, opens a support ticket itself and tells you so; do not push again blindly and do not raise the ticket yourself.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      env: external_exports.enum(["dev", "staging", "prod"]).describe("Which environment the deploy targeted"),
+      outcome: external_exports.enum(["success", "failure"]),
+      source: external_exports.enum(["workflow", "healthcheck", "manual"]).default("workflow").describe("'workflow' = GitHub Actions, 'manual' = deploy-artifacts.sh"),
+      step: external_exports.string().max(64).optional().describe('Failing workflow step, e.g. "Readiness check"'),
+      sha: external_exports.string().regex(/^[0-9a-f]{40}$/i).optional().describe("Full commit sha that was deployed"),
+      runUrl: external_exports.string().url().max(512).optional().describe("GitHub Actions run URL"),
+      detail: external_exports.string().max(500).optional().describe("One line on what failed; no logs, no secrets")
+    }
+  },
+  async ({ appId, ...body }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/deploy-events`, body));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_migration_plan",
+  {
+    annotations: annotate("awesomate_app_migration_plan", READ_ONLY),
+    description: "The hub-computed checklist for getting an existing app (Replit, Lovable, any repo) running on Awesomate: ordered steps, each done / todo / blocked / not_applicable / unavailable, with the exact tool or script that completes it, and any support ticket the hub has already opened about it. Call it at the start of a migration session and after each step; follow `next`. The capacity step reads the account's real limits (awesomate_app_capacity) and the hostname step attaches the user's own subdomain (awesomate_app_domain_attach).",
+    inputSchema: { appId: external_exports.number().int().positive().describe("The app id") }
+  },
+  async ({ appId }) => {
+    try {
+      return textResult(await hubGet(requireConfig(), `/api/my-apps/apps/${appId}/migration-plan`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_capacity",
+  {
+    annotations: annotate("awesomate_app_capacity", MUTATING),
+    description: "Will this app fit on the user's hosting account? Reads the account's live limits and last-day peaks (memory ceiling shared by every environment and the website, task limit where a Node process costs about 11, disk, database sizes, any install or build running on the account, pm2 restart loops) and returns a verdict: ok, warn, blocked or unknown, with reasons and headroom. Call it before the first deploy and again before prod. With fix:true it raises the account's task and memory limits to the platform floors (raise-only, never lowers) when that is what blocks; anything left after that is for Awesomate and the hub opens a support ticket itself and shows it here; do not raise one yourself. Runs a few seconds of server reads; do not poll it.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      fix: external_exports.boolean().default(false).describe("Raise the account floors if that is what blocks (Support Plus and above)")
+    }
+  },
+  async ({ appId, fix }) => {
+    try {
+      const cfg = requireConfig();
+      return textResult(fix ? await hubPost(cfg, `/api/my-apps/apps/${appId}/capacity/fix`, {}) : await hubGet(cfg, `/api/my-apps/apps/${appId}/capacity`));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "awesomate_app_domain_attach",
+  {
+    annotations: annotate("awesomate_app_domain_attach", MUTATING),
+    description: "Put the user's own hostname on an app environment (default prod), so the switch from their old platform is a DNS change. The hostname must be a SUBDOMAIN of a domain already on their hosting account (app.theirdomain.com); the apex and www stay with whatever serves them today, usually their website. Creates the cPanel subdomain and the reverse proxy for that environment, queues the certificate, and returns the exact DNS record to set plus whether it already points at Awesomate. Calling it again for a hostname already attached is a cheap DNS re-check (no reconfiguration, no Apache reload); pass reattach:true only to rewrite the plumbing. awesomate_app_get also re-checks DNS for attached hostnames. Node apps only; a domain not yet on the account needs awesomate_domain_add first. A 503 hostname_attach_disabled means Awesomate has not switched this on yet: tell the user, keep prod on its Awesomate address, do not retry.",
+    inputSchema: {
+      appId: external_exports.number().int().positive().describe("The app id"),
+      hostname: external_exports.string().min(4).max(253).describe("e.g. app.careconnect-ai.com.au"),
+      env: external_exports.enum(["dev", "staging", "prod"]).default("prod"),
+      reattach: external_exports.boolean().default(false).describe("Rewrite the subdomain plumbing even though the hostname is already attached")
+    }
+  },
+  async ({ appId, ...body }) => {
+    try {
+      return textResult(await hubPost(requireConfig(), `/api/my-apps/apps/${appId}/domains`, body));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 server.registerTool(
   "awesomate_app_set_env",
   {
@@ -41893,9 +42032,9 @@ server.registerTool(
   "awesomate_knowledge_sources",
   {
     annotations: annotate("awesomate_knowledge_sources", MUTATING),
-    description: "The knowledge base's content sources \u2014 the LIBRARY. action 'search' {q?, kind?, visibility?, tags?, collectionIds?, cursor?, limit?} \u2014 find sources by title/tag substring and metadata filters (instant, free; for CONTENT search use awesomate_knowledge_search); each row carries visibility (private|internal|public \u2014 who may retrieve it, ENFORCED), tags and collections. 'tag' {sourceId, tags} \u2014 REPLACE a source's free-form tags. 'set_visibility' {sourceId|sourceIds, visibility, confirm?} \u2014 change who may retrieve the source(s); 'public' is irreversible once fetched, so it needs the user's explicit agreement and their account slug as confirm. 'move' {sourceId|sourceIds, collectionIds?, removeCollectionIds?} \u2014 add to / remove from collections. 'sync_rules' / 'sync_rule_create' {pathPrefix, includeGlobs?, visibility?, tags?, collectionIds?, onFileRemoved?} / 'sync_rule_delete' {ruleId} / 'sync_run' / 'sync_state' \u2014 keep a folder of the account's File Manager (their n8n file system: public/, private/, temp/) synced into the knowledge base, so files their workflows write become searchable; a public rule needs confirm. 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources, failed_jobs_7d}: use THIS to say what the knowledge base contains, and if failed_jobs_7d > 0 say so \u2014 those ingests are missing from every other count. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}, optionally with visibility (default private), tags and collectionIds; ALWAYS get explicit approval first (ingest costs money and counts against quota), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
+    description: "The knowledge base's content sources \u2014 the LIBRARY. action 'search' {q?, kind?, visibility?, tags?, collectionIds?, cursor?, limit?} \u2014 find sources by title/tag substring and metadata filters (instant, free; for CONTENT search use awesomate_knowledge_search); each row carries visibility (private|internal|public \u2014 who may retrieve it, ENFORCED), tags and collections. 'tag' {sourceId, tags} \u2014 REPLACE a source's free-form tags. 'rename' {sourceId, title} \u2014 set the source's display TITLE, which is what every citation shows. An UPLOADED file is titled from its FILENAME slugified into title case (Nasa Coverage \u2026 Reagan S Address), because there is nowhere to put a title at ingest; this is the only way to fix it. Rename AFTER the ingest job succeeds. 'set_visibility' {sourceId|sourceIds, visibility, confirm?} \u2014 change who may retrieve the source(s); 'public' is irreversible once fetched, so it needs the user's explicit agreement and their account slug as confirm. 'move' {sourceId|sourceIds, collectionIds?, removeCollectionIds?} \u2014 add to / remove from collections. 'sync_rules' / 'sync_rule_create' {pathPrefix, includeGlobs?, visibility?, tags?, collectionIds?, onFileRemoved?} / 'sync_rule_delete' {ruleId} / 'sync_run' / 'sync_state' \u2014 keep a folder of the account's File Manager (their n8n file system: public/, private/, temp/) synced into the knowledge base, so files their workflows write become searchable; a public rule needs confirm. 'list' \u2014 ONE page of sources, most recently ingested first (default 50, max 200 via limit): read `page.has_more`/`next_cursor` and pass cursor to continue \u2014 a page is never the whole library. 'summary' \u2014 exact whole-library counts {total, by_kind, chunks, indexed_chunks, failed_sources, failed_jobs_7d}: use THIS to say what the knowledge base contains, and if failed_jobs_7d > 0 say so \u2014 those ingests are missing from every other count. 'jobs' \u2014 ingest job statuses (optional status filter: queued|running|succeeded|failed). 'add' \u2014 ingest a public page {url} or a whole site {sitemap, since?}, optionally with visibility (default private), tags and collectionIds; ALWAYS get explicit approval first (ingest costs money and counts against quota), for a local FILE on the user's machine use awesomate_knowledge_upload instead (it streams the file from disk; this tool takes URLs only). A pack_required response means the allowance is exhausted: NOTHING was purchased \u2014 present the pack price (1 credit = $100) and let the user buy from the hub if they want it. 'remove' {sourceId} \u2014 deletes the source AND its indexed content; explicit approval required.",
     inputSchema: {
-      action: external_exports.enum(["list", "summary", "add", "remove", "jobs", "search", "tag", "set_visibility", "move", "sync_rules", "sync_rule_create", "sync_rule_delete", "sync_run", "sync_state"]),
+      action: external_exports.enum(["list", "summary", "add", "remove", "jobs", "search", "tag", "rename", "set_visibility", "move", "sync_rules", "sync_rule_create", "sync_rule_delete", "sync_run", "sync_state"]),
       pathPrefix: external_exports.string().max(512).optional().describe("sync_rule_create: a File Manager folder to keep synced, e.g. 'public/reports'"),
       includeGlobs: external_exports.array(external_exports.string().max(120)).max(20).optional().describe("sync_rule_create: only files matching these globs (relative to the folder), e.g. ['**/*.pdf']"),
       onFileRemoved: external_exports.enum(["keep", "demote_to_private", "delete"]).optional().describe("sync_rule_create: what happens to the knowledge source when the file is removed (default demote_to_private for internal/public rules, keep for private)"),
@@ -41904,6 +42043,7 @@ server.registerTool(
       kind: external_exports.string().max(32).optional().describe("search: source kind filter (web, document, video, audio, image, book, dataset)"),
       visibility: external_exports.enum(["private", "internal", "public"]).optional().describe("add: the audience the new source is cleared for (default private); set_visibility: the level to apply; search: filter"),
       tags: external_exports.array(external_exports.string().max(64)).max(64).optional().describe("add: free-form tags; tag: the REPLACEMENT list; search: filter (AND)"),
+      title: external_exports.string().min(1).max(300).optional().describe("rename: the source's display title, shown in every citation"),
       collectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("add: put the source in these collections; move: add to; search: filter"),
       removeCollectionIds: external_exports.array(external_exports.string().max(64)).max(16).optional().describe("move: remove from these collections"),
       sourceIds: external_exports.array(external_exports.string().max(300)).max(200).optional().describe("set_visibility/move: several sources at once"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.27.0",
+  "version": "0.30.0",
   "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",

package/skill/CHANGELOG.json

@@ -1,5 +1,31 @@
 {
   "versions": [
+    {
+      "version": "0.30.0",
+      "highlights": [
+        "Put your own hostname on your app: awesomate_app_domain_attach sets up app.yourdomain.com on production, queues the certificate and tells you the exact DNS record to create, so moving from Replit or Lovable ends in a DNS change rather than a new address",
+        "The migration checklist now carries the hostname and DNS steps through to done"
+      ]
+    },
+    {
+      "version": "0.29.0",
+      "highlights": [
+        "Ask Claude whether your app will fit before you deploy: awesomate_app_capacity reads your hosting account's real memory and process limits, last-day peaks, disk and database sizes, and says ok, warn or blocked with the reasons",
+        "When the account's limits are the problem, fix:true raises them to the platform floors on the spot; anything that still blocks becomes a support ticket Awesomate opens for you",
+        "Your production app is now probed every five minutes; if it stops answering for a quarter of an hour after having been healthy, Awesomate is told and a ticket appears in your plan",
+        "Every account that hosts an app is swept nightly so an old process limit cannot sit unnoticed"
+      ]
+    },
+    {
+      "version": "0.28.0",
+      "highlights": [
+        "Moving an app from Replit or Lovable is now a guided checklist: awesomate_app_migration_plan tells Claude exactly what is done, what is next and which tool finishes it, and no support ticket is needed to connect deploys",
+        "Push-to-deploy is set up from your own machine: deploy-key.mjs makes a key just for your app, authorises it on your hosting account and sets the three repo secrets",
+        "A pre-deploy repo check catches the Replit lockfile that points at a private mirror, the Neon-only database driver, a hardcoded port and a missing readiness route before anything reaches the server",
+        "The deploy now builds on GitHub and ships only the built files; nothing builds on your hosting account, which is what made deploys die with Killed",
+        "If the check finds a committed secret or a deploy keeps failing, Awesomate opens a support ticket for you and the plan shows the link"
+      ]
+    },
     {
       "version": "0.20.7",
       "highlights": [

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

@@ -58,8 +58,8 @@ decision brain. The short version, matched to what they say:
     single subdomain — there's no dev copy to review on, so every change is
     live the moment it's published.
   - **No deploy workflow.** The static template is just the page files, so
-    pushing to GitHub does not publish it (see the awesomate-github skill's
-    §2 — deploy wiring needs Awesomate support).
+    pushing to GitHub does not publish it; the files are copied to the site's
+    document root over the account SSH (awesomate-hosting `ssh-connect.sh`).
 
   If the page needs a webhook URL, a secret, or a place to test before it
   goes live, it's a **Node app**. Say that in one line and move on.
@@ -182,6 +182,47 @@ When the need is "remember/track a list an automation uses" rather than an
 app with a UI, an n8n data table (awesomate-n8n skill) beats building an app
 — no hosting slot, no deploy, queryable from workflows directly.
 
+## 2b. Bringing an existing app (Replit, Lovable, any repo)
+
+Many users arrive with a working app and their code already on GitHub. Do
+not rebuild it. Read [references/migrate-from-replit.md](references/migrate-from-replit.md)
+and let the hub drive: **`awesomate_app_migration_plan` returns the ordered
+checklist for that app with each step done / todo / blocked and the tool or
+script that finishes it. Call it first, follow `next`, call it again after
+every step.** The short shape:
+
+1. `awesomate_app_create` (Node, Postgres) if the app does not exist yet.
+2. `awesomate_app_update` with the `owner/repo` and `sourcePlatform`.
+3. `node ~/.claude/skills/awesomate-app-builder/scripts/migrate-check.mjs --fix`
+   in the clone, then `awesomate_app_repo_check` with its JSON. Fix blockers
+   in the code, re-run, re-report until none remain.
+4. `awesomate_app_scaffold` with `mode: 'adopt'`: write the returned plumbing
+   into the repo (workflow, `.awesomate.json`, security gate, migrate runner,
+   `AWESOMATE.md`). Touch nothing else.
+5. `node ~/.claude/skills/awesomate-github/scripts/deploy-key.mjs <appId>`.
+6. `awesomate_app_set_env` for each secret per environment.
+6b. `awesomate_app_capacity` before the first deploy: it reads the account's
+   real memory and task limits and last-day peaks. `blocked` with an
+   auto-fixable reason → call again with `fix: true`; anything left is for
+   Awesomate and the hub has already opened the ticket.
+7. Push `dev`, `gh run watch`, `awesomate_app_health`, then
+   `awesomate_app_deploy_event` with the outcome.
+8. Data into staging, rehearse, then prod. Stop idle environments after.
+9. `awesomate_app_domain_attach` puts their own subdomain on prod and returns
+   the DNS record; the cutover is that DNS change.
+
+**Never build on the hosting account** (no `npm ci` without `--omit=dev`, no
+`npm run build`, no `vite build` over SSH). It shares one memory ceiling with
+the user's other environments and website, and a build there dies with
+"Killed". GitHub Actions builds; `awesomate-hosting/scripts/deploy-artifacts.sh`
+is the manual fallback and builds on the user's machine.
+
+**Never raise a support ticket for these problems yourself.** When the repo
+check finds a committed secret, a blocker is reported three times, or a
+deploy fails three times in a day, the hub opens the ticket and the plan
+shows its link. Say "Awesomate has been notified and will pick this up" and
+keep going on what you can fix.
+
 ## 3. Hard rules
 
 - Non-technical user: explain in plain words, one or two short questions at a
@@ -201,5 +242,8 @@ app with a UI, an n8n data table (awesomate-n8n skill) beats building an app
   The honest options are an upgrade or asking support (awesomate-support
   skill) to remove an app.
 - Never invent that a capability exists — read `awesomate_app_context` first.
+- Never build on the hosting account, and never raise a support ticket for a
+  repo or deploy problem yourself: the hub does both the building (via
+  GitHub Actions) and the ticketing (via its rules). See §2b.
 - Never print a secret or commit a `.env` (the credentials + github skills
   enforce this).

package/skill/awesomate-app-builder/references/migrate-from-replit.md

@@ -0,0 +1,105 @@
+# Moving an app from Replit (or Lovable) to Awesomate hosting
+
+The user has a working app somewhere else and their code on their own GitHub.
+The job is to make it run on their Awesomate account in three environments,
+move the data, and switch their address, without anyone at Awesomate doing a
+step by hand. **The hub tells you what is left**: call
+`awesomate_app_migration_plan` at the start of every session and after every
+step; it returns ordered steps with `done` / `todo` / `blocked` and the tool
+or script that completes each one. Follow it rather than this page from
+memory.
+
+## Rules that do not bend
+
+- **Never build on the hosting account.** No `npm ci` (without `--omit=dev`),
+  no `npm run build`, no `vite build` over SSH. The account has one memory
+  ceiling shared by every environment and the user's website; a build there
+  is killed mid-run with no useful error. GitHub Actions builds and ships
+  artefacts; `awesomate-hosting/scripts/deploy-artifacts.sh` is the manual
+  fallback and builds on the user's machine.
+- **Never raise a support ticket for these problems yourself.** The hub opens
+  one when a rule fires (a secret in the repo, a blocker reported three times,
+  a deploy that fails three times in a day) and the plan shows its link. Tell
+  the user "Awesomate has been notified and will pick this up" and keep going
+  on what you can fix.
+- **Dev first, then staging with real data, then prod.** Never push `main`
+  before the staging rehearsal passes.
+
+## The sequence (what the plan will walk you through)
+
+1. **Provision the app** if it does not exist: `awesomate_app_create` with
+   `kind: 'node'`, template `node-crud-postgres` (Postgres), name from the
+   user. Three environments with their own database and `.env` appear.
+2. **Link the repo**: `awesomate_app_update { githubRepo: 'owner/repo',
+   sourcePlatform: 'replit' }`.
+3. **Check the repo**: run
+   `node ~/.claude/skills/awesomate-app-builder/scripts/migrate-check.mjs --fix`
+   in the clone, then post the JSON with `awesomate_app_repo_check`. Fix
+   every `blocker` in the code, re-run, re-post. The common Replit ones:
+   - `lockfile_private_registry`: the lockfile resolves packages from
+     Replit's mirror. `--fix` regenerates it; commit the result. This is why
+     `npm ci` hangs for 14 minutes and dies with an empty log.
+   - `neon_serverless_driver`: `@neondatabase/serverless` only talks to
+     Neon. Switch to `pg` with `drizzle-orm/node-postgres`.
+   - `ready_route_missing`: add `/api/ready` (200 only when `select 1`
+     succeeds, else 503). Snippet in the repo's `AWESOMATE.md` after step 4.
+   - `port_hardcoded`: `app.listen(Number(process.env.PORT))`.
+   - `drizzle_no_generated_sql` (warn): add `drizzle-kit generate` to the
+     build, commit `drizzle/`, use the shipped migrate runner. Never `push`.
+   - `replit_dev_deps`, `replit_env_reads`, `replit_auth` (warn): remove
+     the `@replit/*` plugins, `REPL_ID` reads, and replace Replit Auth.
+4. **Add the plumbing**: `awesomate_app_scaffold { appId, mode: 'adopt' }`
+   returns only `.github/workflows/deploy.yml`, `.awesomate.json`,
+   `scripts/security-check.mjs`, `scripts/awesomate-migrate.mjs` and
+   `AWESOMATE.md`. Write them into the repo; touch nothing else. Then edit
+   the `deploy` block in `.awesomate.json` to match what the check script
+   suggested under `deploy` (artifacts, migrate).
+5. **Deploy key**: `node ~/.claude/skills/awesomate-github/scripts/deploy-key.mjs <appId>`
+   in the repo. It mints a key for this app, authorises it on the user's
+   account, sets the three repo secrets, and records the repo on the hub.
+6. **Secrets**: `awesomate_app_set_env` per key per environment. `PORT` and
+   `DATABASE_URL` are already there. Replit Secrets map one to one; ask the
+   user for values through the awesomate-credentials skill, never in chat.
+6b. **Capacity**: `awesomate_app_capacity` before the first deploy and again
+   before prod. It reports the account's memory ceiling (shared by every
+   environment and the website), the task limit (a Node process costs about
+   11), last-day peaks and faults, disk and database sizes, and whether a
+   build is running on the account. `blocked` on `nproc_below_floor` or
+   `pmem_below_floor` → call again with `fix: true`. Faults, low disk or a
+   restart loop are for Awesomate: the hub opens the ticket; tell the user.
+7. **Dev**: create and push `dev`; `gh run watch`; `awesomate_app_health`.
+   Report the outcome with `awesomate_app_deploy_event` (success or failure,
+   with the failing step) so the plan and the stuck-deploy rule see it.
+8. **Data into staging**: on the user's machine,
+   `pg_dump --no-owner --no-acl "<old DATABASE_URL>" | gzip > dump.sql.gz`,
+   then over their jailed SSH (`awesomate-hosting/scripts/ssh-connect.sh`):
+   `gunzip -c dump.sql.gz | ssh ... 'set -a; . ~/apps/<slug>-staging/.env; psql "$DATABASE_URL"'`.
+   Push `staging`, exercise the real flows on the staging URL.
+9. **Prod**: freeze writes on the old platform, repeat the dump into the
+   prod database, merge `staging` to `main`, check `/api/ready` and the key
+   flows.
+10. **Address**: `awesomate_app_domain_attach { appId, hostname:
+    'app.theirdomain.com' }`. The hostname must be a subdomain of a domain
+    already on the account (their website's domain usually is); the apex and
+    `www` stay with the website. It returns the CNAME to set and whether DNS
+    already points at us; call it again after they change DNS. Lower the TTL
+    before the cutover, then: freeze writes on the old platform, final data
+    import, switch the record, check `/api/ready` on the new hostname.
+11. **Cleanup**: `awesomate_app_run_state` stopped for dev and staging;
+    remove Replit-only files; keep the old platform read-only for a week.
+
+## Lovable
+
+A Lovable app is a Vite React SPA on Supabase. Supabase stays where it is.
+The app is `kind: 'static'` here; the build output is the site. The check
+script recognises it and stops after the platform section; the static path
+does not need the deploy key or the workflow. Full support is a later release.
+
+## What you cannot do
+
+- You cannot put the apex or `www` of their domain on the app; a subdomain
+  only (design decision D3). If they insist on the apex, that is a support
+  conversation, not a tool call.
+- You cannot open a Desk ticket for platform problems; the hub does.
+- You cannot lower an account limit or raise it above the platform floors;
+  `awesomate_app_capacity fix:true` is raise-only up to the floors.

package/skill/awesomate-app-builder/scripts/migrate-check.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Pre-deploy check for a repo that was NOT scaffolded by Awesomate (Replit,
+ * Lovable, anything). Zero dependencies. Prints a JSON report Claude posts
+ * to the hub with awesomate_app_repo_check, which stores it, updates the
+ * migration plan, and may open a support ticket for blockers.
+ *
+ *   node migrate-check.mjs [<repo-dir>] [--fix]
+ *
+ * --fix applies the one repair that is purely mechanical: regenerating a
+ * lockfile that points at a private registry. Everything else is reported
+ * with the fix spelled out so Claude can do it in the code.
+ *
+ * Exit code is always 0. Severity: blocker (the deploy will fail or must not
+ * happen), warn (will bite later), info (worth knowing).
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const args = process.argv.slice(2);
+const fix = args.includes('--fix');
+const dir = resolve(args.find((a) => !a.startsWith('--')) ?? '.');
+
+const findings = [];
+let deploy = null;
+const detected = { node: null, packageManager: 'npm', build: null, start: null, scripts: {}, deps: {}, devDeps: {}, ready_path: '/api/ready', hasReadyRoute: false, drizzle: false, drizzleSql: false, migrationsDir: null, usesPortEnv: false, usesDatabaseUrl: false, replit: {}, websockets: false, largeDirs: [], sourceFiles: 0 };
+const add = (id, severity, title, extra = {}) => findings.push({ id, severity, title, ...extra });
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+const pkg = readJson(join(dir, 'package.json'));
+if (!pkg) {
+  add('no_package_json', 'blocker', 'No package.json at the repo root', { fix: 'Point me at the folder that holds package.json, or this is not a Node app.' });
+  finish('unknown');
+}
+
+detected.scripts = pkg.scripts ?? {};
+detected.deps = pkg.dependencies ?? {};
+detected.devDeps = pkg.devDependencies ?? {};
+detected.build = detected.scripts.build ?? null;
+detected.start = detected.scripts.start ?? null;
+detected.node = pkg.engines?.node ?? null;
+
+// --- platform --------------------------------------------------------------
+const hasReplitFiles = existsSync(join(dir, '.replit')) || existsSync(join(dir, 'replit.nix'));
+const replitDeps = Object.keys({ ...detected.deps, ...detected.devDeps }).filter((d) => d.startsWith('@replit/'));
+const lovable = existsSync(join(dir, 'supabase')) || Object.keys(detected.deps).some((d) => d.startsWith('@supabase/')) && existsSync(join(dir, 'vite.config.ts')) && !detected.deps.express;
+const platform = hasReplitFiles || replitDeps.length ? 'replit' : lovable ? 'lovable' : existsSync(join(dir, '.awesomate.json')) ? 'scaffold' : 'unknown';
+detected.replit = { files: hasReplitFiles, deps: replitDeps };
+
+// --- source scan -------------------------------------------------------------
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', 'attached_assets', 'scripts']);
+const SRC_RE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const files = [];
+(function walk(d, depth) {
+  if (depth > 8) return;
+  for (const e of readdirSync(d, { withFileTypes: true })) {
+    if (SKIP.has(e.name)) continue;
+    const p = join(d, e.name);
+    if (e.isDirectory()) walk(p, depth + 1);
+    else if (SRC_RE.test(e.name)) files.push(p);
+  }
+})(dir, 0);
+detected.sourceFiles = files.length;
+
+const SECRET_RE = /(sk-[A-Za-z0-9]{16,}|sk_live_[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-----|postgres(ql)?:\/\/[^:\s]+:[^@\s]+@)/;
+let readyFound = false, portEnv = false, portHardcoded = null, dbUrl = false, neon = false, replEnv = [], replitAuth = false, ws = false, evalUse = false;
+for (const f of files) {
+  let text;
+  try { if (statSync(f).size > 1_000_000) continue; text = readFileSync(f, 'utf8'); } catch { continue; }
+  const rel = relative(dir, f);
+  if (SECRET_RE.test(text) && !/\.example\./.test(rel)) add('secret_in_source', 'blocker', 'Something shaped like a secret is committed', { file: rel, fix: 'Rotate it with the provider, remove it from the code, store it with awesomate_app_set_env.' });
+  if (/['"`]\/api\/ready['"`]/.test(text)) readyFound = true;
+  if (/process\.env\.PORT/.test(text)) portEnv = true;
+  const listen = text.match(/\.listen\(\s*(\d{4,5})\s*[,)]/);
+  if (listen && !/process\.env\.PORT/.test(text)) portHardcoded = { file: rel, port: listen[1] };
+  if (/process\.env\.DATABASE_URL/.test(text)) dbUrl = true;
+  if (/@neondatabase\/serverless|drizzle-orm\/neon-/.test(text)) neon = true;
+  for (const v of ['REPL_ID', 'REPLIT_DOMAINS', 'REPLIT_DEV_DOMAIN', 'REPL_SLUG', 'REPL_OWNER']) if (text.includes(v) && !replEnv.includes(v)) replEnv.push(v);
+  if (/replit\.com\/oidc|ISSUER_URL.*replit|openid-client/.test(text) && /REPL/.test(text)) replitAuth = true;
+  if (/from ['"](ws|socket\.io)['"]|require\(['"](ws|socket\.io)['"]\)|new WebSocketServer/.test(text)) ws = true;
+  if (/\beval\(|new Function\(/.test(text)) evalUse = true;
+}
+detected.hasReadyRoute = readyFound;
+detected.usesPortEnv = portEnv;
+detected.usesDatabaseUrl = dbUrl;
+detected.websockets = ws;
+
+// --- tracked .env ------------------------------------------------------------
+try {
+  const tracked = execSync('git ls-files .env */.env', { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+  if (tracked) add('tracked_env_file', 'blocker', 'A .env file is tracked by git', { file: tracked.split('\n')[0], fix: 'git rm --cached it, add .env to .gitignore, rotate anything in it.' });
+} catch { /* not a git repo */ }
+
+// --- lockfile ----------------------------------------------------------------
+const lockPath = join(dir, 'package-lock.json');
+if (!existsSync(lockPath)) {
+  const alt = ['yarn.lock', 'pnpm-lock.yaml', 'bun.lockb'].find((f) => existsSync(join(dir, f)));
+  if (alt) detected.packageManager = alt.split('.')[0].replace('lockb', 'bun');
+  add('no_npm_lockfile', 'blocker', alt ? `Uses ${alt}; the deploy runs npm ci` : 'No package-lock.json', { fix: 'Run npm install --package-lock-only to create package-lock.json (keep the other lockfile if you like).' });
+} else {
+  const lock = readJson(lockPath);
+  const hosts = new Set();
+  const walkPkgs = (pkgs) => { for (const [, v] of Object.entries(pkgs ?? {})) { if (v?.resolved) { try { hosts.add(new URL(v.resolved).host); } catch { /* ignore */ } } } };
+  walkPkgs(lock?.packages); walkPkgs(lock?.dependencies);
+  const foreign = [...hosts].filter((h) => h !== 'registry.npmjs.org' && h !== 'github.com' && h !== 'codeload.github.com');
+  if (foreign.length) {
+    if (fix) {
+      try {
+        execSync('npm install --package-lock-only --ignore-scripts --registry https://registry.npmjs.org', { cwd: dir, stdio: 'pipe' });
+        add('lockfile_private_registry', 'info', `Lockfile pointed at ${foreign.join(', ')}; regenerated against the public registry`, { fix: 'Commit the new package-lock.json.' });
+      } catch (err) {
+        add('lockfile_private_registry', 'blocker', `Lockfile resolves packages from ${foreign.join(', ')} and regeneration failed`, { detail: String(err.message).slice(0, 300), fix: 'rm package-lock.json && npm install --package-lock-only --registry https://registry.npmjs.org' });
+      }
+    } else {
+      add('lockfile_private_registry', 'blocker', `Lockfile resolves packages from ${foreign.join(', ')}, unreachable from Awesomate and from GitHub Actions`, { fix: 'node migrate-check.mjs --fix (regenerates the lockfile against registry.npmjs.org), then commit it.' });
+    }
+  }
+}
+
+// --- app contract --------------------------------------------------------------
+if (!detected.build) add('no_build_script', 'blocker', 'package.json has no "build" script', { fix: 'Add one that produces the artefacts (for example vite build && esbuild server/index.ts --bundle --platform=node --format=esm --outdir=dist).' });
+if (!readyFound) add('ready_route_missing', 'blocker', 'No /api/ready route', { fix: 'Add a route that returns 200 only when the database answers (see AWESOMATE.md). The deploy and health checks probe it.' });
+if (portHardcoded) add('port_hardcoded', 'blocker', `Server listens on a fixed port ${portHardcoded.port}`, { file: portHardcoded.file, fix: 'Use Number(process.env.PORT); the account assigns one port per environment.' });
+else if (!portEnv) add('port_env_unknown', 'warn', 'Could not confirm the server reads process.env.PORT', { fix: 'Make sure app.listen uses process.env.PORT.' });
+if (!dbUrl && (detected.deps.pg || detected.deps['drizzle-orm'] || detected.deps['@neondatabase/serverless'])) add('database_url_unused', 'warn', 'A database driver is present but DATABASE_URL is not read', { fix: 'Connect with process.env.DATABASE_URL; provisioning writes it per environment.' });
+if (neon || detected.deps['@neondatabase/serverless']) add('neon_serverless_driver', 'blocker', 'Uses the Neon serverless driver, which only speaks to Neon over HTTP/WebSocket', { fix: "Switch to 'pg' with drizzle-orm/node-postgres (npm i pg && npm rm @neondatabase/serverless ws)." });
+
+const drizzleCfg = ['drizzle.config.ts', 'drizzle.config.js', 'drizzle.config.mjs'].find((f) => existsSync(join(dir, f)));
+if (drizzleCfg) {
+  detected.drizzle = true;
+  detected.drizzleSql = existsSync(join(dir, 'drizzle', 'meta', '_journal.json'));
+  if (!detected.drizzleSql) add('drizzle_no_generated_sql', 'warn', 'Drizzle is configured but no generated SQL is committed; drizzle-kit push cannot reach the account database', { fix: 'Add "drizzle-kit generate" to the build script, commit drizzle/, add "drizzle" to deploy.artifacts and set deploy.migrate to "node --env-file=.env scripts/awesomate-migrate.mjs".' });
+} else if (existsSync(join(dir, 'migrations'))) {
+  detected.migrationsDir = 'migrations';
+}
+
+if (replitDeps.length) add('replit_dev_deps', 'warn', `Replit-only packages present: ${replitDeps.join(', ')}`, { fix: 'Remove them from package.json and vite.config.ts; they do nothing outside Replit.' });
+if (hasReplitFiles) add('replit_config_files', 'info', '.replit / replit.nix present', { fix: 'Harmless; delete when the move is done.' });
+if (replEnv.length) add('replit_env_reads', 'warn', `Code reads Replit-only variables: ${replEnv.join(', ')}`, { fix: 'Replace with your own configuration or remove; they are unset on Awesomate.' });
+if (replitAuth) add('replit_auth', 'warn', 'Replit Auth (OIDC against replit.com) is used for sign-in', { fix: 'It stops working off Replit. Replace with your own auth (session + password, or another OIDC provider).' });
+if (ws) add('websockets_proxy', 'info', 'WebSockets are used', { fix: 'Nothing to do: the reverse proxy forwards the Upgrade handshake on every environment address and attached hostname.' });
+if (evalUse) add('dynamic_code_eval', 'warn', 'eval() or new Function() in source', { fix: 'The prod security gate blocks these; replace before merging to main.' });
+if (detected.node && !/(^|[^0-9])22([^0-9]|$)|>=\s*(1[8-9]|2[0-2])/.test(String(detected.node))) add('node_engine_mismatch', 'warn', `engines.node is "${detected.node}"; Awesomate runs Node 22`, { fix: 'Test on Node 22 locally; update engines.' });
+if (pkg.scripts?.start && /NODE_ENV=/.test(pkg.scripts.start)) add('start_sets_node_env', 'info', 'start script sets NODE_ENV inline', { fix: 'Not needed: the account .env sets NODE_ENV per environment. deploy.start is the entry file, e.g. dist/index.js.' });
+if (existsSync(join(dir, 'main.py'))) add('python_file_present', 'info', 'main.py present', { fix: 'Only Node runs on the account; delete it if it is a leftover.' });
+
+for (const name of readdirSync(dir, { withFileTypes: true })) {
+  if (!name.isDirectory() || SKIP.has(name.name) && name.name !== 'attached_assets') continue;
+  let size = 0, count = 0;
+  (function du(p, depth) { if (depth > 6) return; for (const e of readdirSync(p, { withFileTypes: true })) { const q = join(p, e.name); if (e.isDirectory()) du(q, depth + 1); else { count += 1; try { size += statSync(q).size; } catch { /* ignore */ } } } })(join(dir, name.name), 0);
+  if (size > 50 * 1024 * 1024) { detected.largeDirs.push({ dir: name.name, mb: Math.round(size / 1048576), files: count }); add('large_assets_dir', 'warn', `${name.name}/ is ${Math.round(size / 1048576)} MB (${count} files)`, { fix: 'Do not ship it through the deploy; serve static assets from public_html or object storage and keep the repo small.' }); }
+}
+
+// --- suggested deploy contract ---------------------------------------------------
+const artifacts = ['dist', 'package.json', 'package-lock.json'];
+if (detected.drizzle) artifacts.splice(1, 0, 'drizzle');
+else if (detected.migrationsDir) artifacts.splice(1, 0, 'migrations');
+deploy = {
+  node: 22,
+  build: detected.drizzle && !/drizzle-kit generate/.test(detected.build ?? '') ? 'npx drizzle-kit generate && npm run build' : 'npm run build',
+  artifacts,
+  install: 'npm ci --omit=dev',
+  migrate: detected.drizzle ? 'node --env-file=.env scripts/awesomate-migrate.mjs' : detected.migrationsDir ? 'node --env-file=.env scripts/awesomate-migrate.mjs migrations' : null,
+  start: 'dist/index.js',
+  ready_path: '/api/ready',
+};
+
+finish(platform);
+
+function finish(plat) {
+  const blockers = findings.filter((f) => f.severity === 'blocker').length;
+  const report = { version: 1, platform: plat, findings, detected, deploy, summary: { blockers, warnings: findings.filter((f) => f.severity === 'warn').length, fixApplied: fix } };
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(0);
+}

package/skill/awesomate-github/SKILL.md

@@ -59,29 +59,44 @@ git checkout -b dev
 git push -u origin dev
 ```
 
-## 2. Push-to-deploy (for apps built with awesomate-app-builder)
-
-Node apps from the app builder ship with a GitHub Actions workflow that
-deploys on a push to `dev` / `staging` / `main` (dev → dev, main → prod).
-Once the branches exist, explain it as *"save your work = it goes live"* —
-don't lecture on branches.
-
-**But you cannot finish the wiring yourself, and you should say so.** That
-workflow needs `SSH_HOST`, `SSH_USER` and `SSH_PRIVATE_KEY` as repo secrets,
-and **no client-reachable tool or route returns those values** — they're
-admin-only. `github-setup.mjs --deploy-secrets` only copies them from your
-environment, so with nothing there it prints `skip deploy secret …` and the
-first deploy run goes red. So:
-
-1. Set up the repo, the branches and the commits (§1) — all of that works.
-2. Tell the user plainly: *"your code is backed up on GitHub; the automatic
-   deploy still needs Awesomate to connect it — I'll raise that for you."*
-   Raise it via the **awesomate-support** skill.
-3. **Do not loop on the failing pipeline.** Re-running it, rewriting the
-   workflow, or pushing again won't produce the missing secrets.
-
-Static sites have no deploy workflow at all — the template is just the page
-files — so pushing does not publish them either; same handoff.
+## 2. Push-to-deploy (Node apps on Awesomate)
+
+Node apps deploy on a push to `dev` / `staging` / `main` (dev → dev, main →
+prod). GitHub Actions builds on its own runner and ships only the built
+files to the account; **nothing builds on the hosting account**, and neither
+should you over SSH. Once wired, explain it as *"save your work = it goes
+live"*; don't lecture on branches.
+
+**Wiring it is one command, run from the repo folder, and needs no ticket:**
+
+```
+node ~/.claude/skills/awesomate-github/scripts/deploy-key.mjs <appId>
+```
+
+It generates a key **for this app only**, authorises it on the user's own
+hosting account through the hub (Support Plus and above), sets
+`SSH_PRIVATE_KEY`, `SSH_HOST` and `SSH_USER` on the repo with `gh secret set`,
+shreds the private key locally, and tells the hub which repo the app deploys
+from. Re-running it is safe; `--rotate` replaces the key. `<appId>` comes from
+`awesomate_app_list` / `awesomate_app_get`.
+
+The repo also needs the Awesomate plumbing: a scaffolded app already has it;
+an existing repo (Replit, Lovable, anything) gets it from
+`awesomate_app_scaffold` with `mode: 'adopt'` after the repo check. The full
+order for an existing repo lives in the app-builder skill's
+`references/migrate-from-replit.md`, and `awesomate_app_migration_plan` tells
+you which step is next.
+
+**When a deploy run goes red**, read the failing step (`gh run view
+--log-failed`), report it with `awesomate_app_deploy_event`, fix the cause,
+and push again. Three failures on one environment inside a day make the hub
+open a support ticket itself and show it in the plan; tell the user
+"Awesomate has been notified" and keep working. Do not raise that ticket
+yourself and do not loop on pushes.
+
+Static sites have no deploy workflow at all: the template is just the page
+files, so pushing does not publish them. They are copied to the site's
+document root over the account SSH (awesomate-hosting `ssh-connect.sh`).
 
 ## 3. Everyday use (plain language)
 
@@ -107,13 +122,13 @@ control — they should never have to think about it:
   aren't backed up anywhere — want me to set that up? Takes a minute."*
   `env_file_tracked` is urgent: untrack it, .gitignore it, and route the
   secrets through awesomate-credentials.
-  **`last_deploy_failed` that never clears is usually the unwired deploy
-  secrets (§2), not a bug you can fix.** Check whether `SSH_HOST` /
-  `SSH_USER` / `SSH_PRIVATE_KEY` are set on the repo (`gh secret list`)
-  before touching anything: if they're missing, stop, tell the user the
-  deploy connection is pending with Awesomate, and raise it via the
-  awesomate-support skill. Don't retry the run, and don't start editing the
-  workflow file.
+  **`last_deploy_failed`:** first check the three deploy secrets exist
+  (`gh secret list`). If they are missing, run `deploy-key.mjs <appId>` (§2);
+  that is the fix, not a ticket. If they exist, read the failing step with
+  `gh run view --log-failed`, report it with `awesomate_app_deploy_event`,
+  fix the cause and push once. A "Killed" or exit 137 inside a step that runs
+  on the account means memory: the build must move to the runner (it does by
+  default; check `.awesomate.json` deploy.build is not being run over SSH).
 - **Auto-checkpoint.** After every meaningful working change (feature works,
   bug fixed, content updated), commit with a plain-English message — don't
   wait for "save my work", and never ask them to write a message. Push at

package/skill/awesomate-github/scripts/deploy-key.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Wire push-to-deploy for an Awesomate app from the client's own machine.
+ *
+ *   node deploy-key.mjs <appId> [--path <repo-dir>] [--rotate]
+ *
+ * 1. Generates a fresh ed25519 keypair for THIS app (never the machine key).
+ * 2. Registers the public half on the hosting account through the hub
+ *    (POST /api/hosting-access/ssh-keys, Support Plus and above).
+ * 3. Sets SSH_PRIVATE_KEY, SSH_HOST and SSH_USER as GitHub Actions secrets on
+ *    the repo in <repo-dir> (gh CLI, already authenticated).
+ * 4. Shreds the private key locally and tells the hub which repo and key
+ *    fingerprint the app now uses (PATCH /api/my-apps/apps/<id>).
+ *
+ * Idempotent: if the repo already has the three secrets and --rotate is not
+ * given, it only refreshes the hub's record. --rotate mints a new key AND
+ * revokes the previous one from the hosting account, so a leaked key stops
+ * working. Prints names and fingerprints, never key material.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir, homedir } from 'node:os';
+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 appId = Number(positional[0]);
+const pathIdx = args.indexOf('--path');
+const cwd = pathIdx >= 0 && args[pathIdx + 1] ? args[pathIdx + 1] : process.cwd();
+const rotate = flags.has('--rotate');
+
+if (!Number.isInteger(appId) || appId <= 0) {
+  console.error('usage: node deploy-key.mjs <appId> [--path <repo-dir>] [--rotate]');
+  console.error('appId: the number from awesomate_app_list / awesomate_app_get');
+  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);
+}
+
+// --- account: API base, token and SSH block from the hosting skill's resolver --
+const resolver = join(homedir(), '.claude', 'skills', 'awesomate-hosting', 'scripts', 'resolve-account.mjs');
+if (!existsSync(resolver)) {
+  die('The awesomate-hosting skill is not installed on this machine. Connect Claude Code from hub.awesomate.ai/sites first.');
+}
+const resolved = spawnSync('node', [resolver, '--api', '--ssh'], { encoding: 'utf8' });
+if (resolved.status !== 0) {
+  die((resolved.stderr || resolved.stdout || '').trim() || 'Could not resolve the connected Awesomate account.');
+}
+const kv = {};
+for (const part of resolved.stdout.trim().split(';')) {
+  const m = part.trim().match(/^([A-Z]+)='(.*)'$/);
+  if (m) kv[m[1]] = m[2];
+}
+const { ACCT, API, PAT, H: sshHost, U: sshUser } = kv;
+if (!API || !PAT) die('No access token found for this account. Reconnect from hub.awesomate.ai/sites.');
+if (!sshHost || !sshUser) die('This plan has no shell access (Support Plus and above), so a deploy key cannot be authorised.');
+console.log(`→ account: ${ACCT}  hosting user: ${sshUser}@${sshHost}`);
+
+async function hub(method, path, body) {
+  const res = await fetch(`${API}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${PAT}`, 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await res.text();
+  let json = {};
+  try { json = text ? JSON.parse(text) : {}; } catch { json = { raw: text.slice(0, 200) }; }
+  if (!res.ok) {
+    const msg = json.message || json.error || `${res.status}`;
+    throw new Error(`${method} ${path} → ${res.status}: ${msg}`);
+  }
+  return json;
+}
+
+// --- repo ------------------------------------------------------------------
+if (run('gh', ['--version']).status !== 0) die("GitHub CLI 'gh' is not installed (macOS: brew install gh).");
+if (run('gh', ['auth', 'status']).status !== 0) die('Not connected to GitHub. Run: gh auth login');
+const repoView = run('gh', ['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner']);
+if (repoView.status !== 0) die(`No GitHub repo in ${cwd}. Run github-setup.mjs first.`);
+const repo = repoView.stdout.trim();
+console.log(`→ repo: ${repo}`);
+
+const existing = run('gh', ['secret', 'list', '--json', 'name', '-q', '.[].name']).stdout.split(/\r?\n/).filter(Boolean);
+const haveAll = ['SSH_PRIVATE_KEY', 'SSH_HOST', 'SSH_USER'].every((n) => existing.includes(n));
+
+let previousFingerprint = null;
+try {
+  const current = await hub('GET', `/api/my-apps/apps/${appId}`);
+  previousFingerprint = current?.app?.deploy_key_fingerprint ?? null;
+} catch { /* the hub record is optional here */ }
+
+let fingerprint = null;
+if (haveAll && !rotate) {
+  console.log('• deploy secrets already present on the repo (pass --rotate to replace the key)');
+} else {
+  // --- key ----------------------------------------------------------------
+  const dir = mkdtempSync(join(tmpdir(), 'awm-deploy-key-'));
+  const keyPath = join(dir, 'key');
+  try {
+    const gen = spawnSync('ssh-keygen', ['-t', 'ed25519', '-N', '', '-C', `awesomate-deploy:${ACCT}:app${appId}`, '-f', keyPath], { encoding: 'utf8' });
+    if (gen.status !== 0) die(`ssh-keygen failed: ${(gen.stderr || '').trim()}`);
+    const publicKey = readFileSync(`${keyPath}.pub`, 'utf8').trim();
+
+    const reg = await hub('POST', '/api/hosting-access/ssh-keys', {
+      publicKey,
+      label: `deploy:app${appId} (${repo})`,
+    });
+    fingerprint = reg.fingerprint ?? null;
+    const host = reg.sshHost || sshHost;
+    const user = reg.sshUser || sshUser;
+    console.log(`• deploy key authorised on ${user}@${host}${fingerprint ? ` (${fingerprint})` : ''}`);
+
+    const priv = readFileSync(keyPath, 'utf8');
+    for (const [name, value] of [['SSH_PRIVATE_KEY', priv], ['SSH_HOST', host], ['SSH_USER', user]]) {
+      const set = run('gh', ['secret', 'set', name], { input: value });
+      if (set.status !== 0) die(`gh secret set ${name} failed: ${(set.stderr || '').trim()}`);
+      console.log(`• set repo secret ${name}`);
+    }
+  } finally {
+    // Overwrite before unlinking so the private half does not linger in tmp.
+    try { if (existsSync(keyPath)) writeFileSync(keyPath, '\0'.repeat(4096)); } catch { /* best effort */ }
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// --- revoke the previous key on rotate --------------------------------------
+if (rotate && fingerprint && previousFingerprint && previousFingerprint !== fingerprint) {
+  try {
+    const list = await hub('GET', '/api/hosting-access/ssh-keys');
+    const old = (list?.keys ?? []).find((k) => k.fingerprint === previousFingerprint);
+    if (old) {
+      await hub('DELETE', `/api/hosting-access/ssh-keys/${old.id}`);
+      console.log(`• revoked the previous deploy key (${previousFingerprint})`);
+    } else {
+      console.log(`• previous key ${previousFingerprint} is not in the hub registry; revoke it from hub.awesomate.ai/settings?tab=access if it still exists`);
+    }
+  } catch (err) {
+    console.log(`• could not revoke the previous key (${err.message}); revoke it from hub.awesomate.ai/settings?tab=access`);
+  }
+}
+
+// --- tell the hub -----------------------------------------------------------
+const patch = { githubRepo: repo };
+if (fingerprint) patch.deployKeyFingerprint = fingerprint;
+try {
+  await hub('PATCH', `/api/my-apps/apps/${appId}`, patch);
+  console.log(`• hub updated: app ${appId} deploys from ${repo}`);
+} catch (err) {
+  console.log(`• could not update the hub record (${err.message}); the secrets are set, so deploys will work. Ask Claude to run awesomate_app_update.`);
+}
+
+console.log('\n✓ Push-to-deploy is wired. Push the dev branch to deploy dev; gh run watch to follow.');

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

@@ -2,15 +2,15 @@
 /**
  * Zero-knowledge GitHub scaffolder. Idempotent — safe to re-run.
  *
- *   node github-setup.mjs <repo-name> [--public] [--path <dir>] [--deploy-secrets]
+ *   node github-setup.mjs <repo-name> [--public] [--path <dir>]
  *
  * 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.
+ * `gh repo create --source=. --push` (private by default; personal accounts OK).
  *
- * 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.
+ * Deploy secrets are NOT handled here: run deploy-key.mjs <appId> afterwards,
+ * which mints a per-app key and sets SSH_HOST/SSH_USER/SSH_PRIVATE_KEY itself.
+ * Prints only non-sensitive output.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -24,10 +24,9 @@ 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('usage: node github-setup.mjs <repo-name> [--public] [--path <dir>]');
   console.error('repo-name: letters/digits/._- , starts alphanumeric');
   process.exit(2);
 }
@@ -111,19 +110,6 @@ if (already.status === 0) {
   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-hosting/SKILL.md

@@ -362,6 +362,11 @@ skill drive the Git workflow; this skill just deploys the result.
   setup (Support Plus+). Invocation + failure modes:
   `references/connect-troubleshooting.md`.
 - `ssh-connect.sh` — open a jailed SSH session (or run one remote command).
+- `deploy-artifacts.sh <dev|staging|prod>` — manual deploy of a Node app when
+  GitHub Actions is not available: builds on THIS machine from the repo's
+  `.awesomate.json` contract, ships only the artefacts over the jailed SSH,
+  installs, migrates, restarts, probes readiness. It refuses to run on the
+  hosting account itself: nothing builds there, ever.
 - `wp.sh` — run a WP-CLI command against a live site over that SSH.
 - `deploy.sh` — snapshot-first Studio→live deploy (files, optional DB).
 - `pull-live.sh` — clone a live site down to a local folder (read-only on live).

package/skill/awesomate-hosting/scripts/deploy-artifacts.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Manual deploy of an Awesomate Node app WITHOUT GitHub Actions: build here,
+# ship only the artefacts, install and restart on the account. Reads the same
+# .awesomate.json "deploy" contract the workflow uses.
+#
+#   deploy-artifacts.sh <dev|staging|prod> [--path <repo-dir>] [--skip-build]
+#
+# It refuses to run on the hosting account itself: the account shares one
+# memory ceiling across every environment and the website, and a build there
+# is how deploys die with "Killed".
+set -euo pipefail
+
+ENV_NAME="${1:-}"; shift || true
+DIR="$(pwd)"; SKIP_BUILD=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path) DIR="$2"; shift 2 ;;
+    --skip-build) SKIP_BUILD=1; shift ;;
+    *) echo "unknown option $1" >&2; exit 2 ;;
+  esac
+done
+case "$ENV_NAME" in dev|staging|prod) ;; *) echo "usage: deploy-artifacts.sh <dev|staging|prod> [--path <repo-dir>] [--skip-build]" >&2; exit 2 ;; esac
+cd "$DIR"
+[ -f .awesomate.json ] || { echo "✗ .awesomate.json not found in $DIR (awesomate_app_scaffold mode adopt writes it)" >&2; exit 1; }
+command -v jq >/dev/null || { echo "✗ jq is required (macOS: brew install jq)" >&2; exit 1; }
+
+if [[ "$(hostname -f 2>/dev/null || hostname)" == *awesomate.io* ]] || [[ "$HOME" == /home/* && -d /usr/local/cpanel ]]; then
+  echo "✗ This looks like the hosting account. Never build on the account: run this from your own machine." >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! CREDS_EVAL="$(node "$SCRIPT_DIR/resolve-account.mjs" --ssh)"; then exit 1; fi
+eval "$CREDS_EVAL"
+echo "→ account: $ACCT  ($U@$H)"
+
+APP_SLUG="$(jq -r '.app_slug // empty' .awesomate.json)"; [ -n "$APP_SLUG" ] || { echo "✗ .awesomate.json has no app_slug" >&2; exit 1; }
+ENV_URL="$(jq -r --arg e "$ENV_NAME" '.environments[$e].url // empty' .awesomate.json)"
+BUILD_CMD="$(jq -r '.deploy.build // "npm run build"' .awesomate.json)"
+INSTALL_CMD="$(jq -r '.deploy.install // "npm ci --omit=dev"' .awesomate.json)"
+MIGRATE_CMD="$(jq -r '.deploy.migrate // empty' .awesomate.json)"
+START_SCRIPT="$(jq -r '.deploy.start // "dist/index.js"' .awesomate.json)"
+READY_PATH="$(jq -r '.deploy.ready_path // "/api/ready"' .awesomate.json)"
+ARTIFACTS="$(jq -r '(.deploy.artifacts // ["dist","package.json","package-lock.json"]) | join(" ")' .awesomate.json)"
+REMOTE_DIR="/home/$U/apps/${APP_SLUG}-${ENV_NAME}"
+NAME="${APP_SLUG}-${ENV_NAME}"
+SSH=(ssh -i "$K" -p "$P" -o StrictHostKeyChecking=accept-new "$U@$H")
+
+if [ "$ENV_NAME" = "prod" ]; then
+  read -r -p "This deploys to PRODUCTION ($ENV_URL). Type the app slug to continue: " confirm
+  [ "$confirm" = "$APP_SLUG" ] || { echo "aborted"; exit 1; }
+fi
+
+if [ "$SKIP_BUILD" = 0 ]; then
+  echo "→ building locally: $BUILD_CMD"
+  npm ci
+  bash -eo pipefail -c "$BUILD_CMD"
+  case " $ARTIFACTS " in *" node_modules "*) npm prune --omit=dev ;; esac
+fi
+for a in $ARTIFACTS; do [ -e "$a" ] || { echo "✗ artefact '$a' does not exist after the build" >&2; exit 1; }; done
+
+echo "→ shipping $ARTIFACTS to $REMOTE_DIR"
+"${SSH[@]}" "mkdir -p '$REMOTE_DIR'"
+# shellcheck disable=SC2086
+tar czf - $ARTIFACTS | "${SSH[@]}" bash -lc "set -eo pipefail; cd '$REMOTE_DIR' && tar xzf - && export PATH=\"\$HOME/.npm-global/bin:/opt/cpanel/ea-nodejs22/bin:\$PATH\" && if [ -n '$INSTALL_CMD' ]; then $INSTALL_CMD; fi"
+if [ -n "$MIGRATE_CMD" ]; then
+  echo "→ migrating: $MIGRATE_CMD"
+  "${SSH[@]}" bash -lc "set -eo pipefail; cd '$REMOTE_DIR' && export PATH=\"\$HOME/.npm-global/bin:/opt/cpanel/ea-nodejs22/bin:\$PATH\" && $MIGRATE_CMD"
+fi
+echo "→ restarting $NAME"
+"${SSH[@]}" bash -lc "cd '$REMOTE_DIR' && (~/.npm-global/bin/pm2 restart $NAME --update-env || ~/.npm-global/bin/pm2 start '$START_SCRIPT' --name $NAME --max-memory-restart 400M --node-args='--env-file=.env') && ~/.npm-global/bin/pm2 save"
+
+echo "→ readiness: ${ENV_URL}${READY_PATH}"
+for i in 1 2 3 4 5 6; do
+  sleep 5
+  code="$(curl -s -o /dev/null -w '%{http_code}' "${ENV_URL}${READY_PATH}" || true)"
+  if [ "$code" = "200" ]; then echo "✓ $ENV_NAME is ready at $ENV_URL"; exit 0; fi
+  echo "  attempt $i: HTTP $code"
+done
+echo "✗ readiness failed. 503: process not listening or database unreachable; 404: no ${READY_PATH} route." >&2
+exit 1