hatchkit 0.1.2 → 0.1.3

package/dist/index.js

@@ -2,14 +2,14 @@
 import { join, resolve } from "node:path";
 import { confirm } from "@inquirer/prompts";
 import chalk from "chalk";
-import { ensureCoolify, ensureDns, ensureGitHub, ensureGlitchtip, ensureGpuProvider, ensureHetzner, ensureOpenpanel, ensureResend, ensureS3, getConfig, getConfigPath, getMlServices, isFirstRun, resetConfig, runOnboarding, } from "./config.js";
+import { ensureCoolify, ensureGitHub, ensureHetzner, ensureS3, getConfig, getConfigPath, getMlServices, isFirstRun, reconfigureProvider, resetConfig, runOnboarding, } from "./config.js";
 import { runCoolifySetup } from "./deploy/coolify.js";
 import { setupGitHub } from "./deploy/github.js";
 import { deployMlServices } from "./deploy/gpu.js";
 import { pushProjectKeyToCoolify, showProjectKey } from "./deploy/keys.js";
 import { runTerraform } from "./deploy/terraform.js";
 import { collectProjectConfig } from "./prompts.js";
-import { runProvision } from "./provision/index.js";
+import { runProvision, runUnprovision } from "./provision/index.js";
 import { scaffoldApp } from "./scaffold/app.js";
 import { scaffoldInfra } from "./scaffold/infra.js";
 import { mlEnvVarName, printMlSummary, resolveMlServices } from "./scaffold/ml-client.js";
@@ -35,10 +35,15 @@ async function main() {
         console.log(getCliVersion());
         return;
     }
-    console.log(chalk.bold(`\n  hatchkit v${getCliVersion()}\n`));
-    // Global --help without a subcommand prints the top-level help.
-    if (command === "--help" || command === "-h") {
-        printHelp();
+    const isJson = args.includes("--json");
+    // Suppress the banner for machine-readable output so stdout is pure JSON.
+    if (!isJson) {
+        console.log(chalk.bold(`\n  hatchkit v${getCliVersion()}\n`));
+    }
+    // Global --help / help subcommand (with optional topic).
+    if (command === "--help" || command === "-h" || command === "help") {
+        const topic = command === "help" ? args[1] : undefined;
+        printHelp(topic);
         return;
     }
     switch (command) {
@@ -53,12 +58,46 @@ async function main() {
                 return printHelp("config");
             await handleConfig();
             break;
+        case "status": {
+            if (args.includes("--help"))
+                return printHelp("status");
+            const { collectStatus, renderStatusHuman } = await import("./status.js");
+            const s = collectStatus();
+            if (isJson) {
+                console.log(JSON.stringify(s, null, 2));
+            }
+            else {
+                console.log(renderStatusHuman(s));
+            }
+            break;
+        }
+        case "explain": {
+            if (args.includes("--help"))
+                return printHelp("explain");
+            const { renderExplain } = await import("./explain.js");
+            console.log(renderExplain({ json: isJson }));
+            break;
+        }
+        case "completion": {
+            if (args.includes("--help"))
+                return printHelp("completion");
+            const { renderCompletion } = await import("./completion.js");
+            const shell = (args[1] ?? "").toLowerCase();
+            if (shell !== "zsh" && shell !== "bash" && shell !== "fish") {
+                console.log("Usage: hatchkit completion <zsh|bash|fish>");
+                process.exit(1);
+            }
+            console.log(renderCompletion(shell));
+            break;
+        }
         case "create":
-        case undefined:
             if (args.includes("--help"))
                 return printHelp("create");
             await handleCreate();
             break;
+        case undefined:
+            await handleNoArgs();
+            break;
         case "update":
             if (args.includes("--help"))
                 return printHelp("update");
@@ -74,10 +113,72 @@ async function main() {
                 return printHelp("add");
             await handleAdd();
             break;
+        case "remove":
+            if (args.includes("--help"))
+                return printHelp("remove");
+            await handleRemove();
+            break;
+        case "rename-domain": {
+            if (args.includes("--help"))
+                return printHelp("rename-domain");
+            const { runRenameDomainCli } = await import("./deploy/rename-domain.js");
+            await runRenameDomainCli(args.slice(1), MONOREPO_ROOT);
+            break;
+        }
+        case "doctor": {
+            if (args.includes("--help"))
+                return printHelp("doctor");
+            const { runDoctor } = await import("./doctor.js");
+            await runDoctor({ json: isJson });
+            break;
+        }
+        case "dns": {
+            if (args.includes("--help"))
+                return printHelp("dns");
+            await handleDns();
+            break;
+        }
+        case "gh-pages":
+        case "pages": {
+            if (args.includes("--help"))
+                return printHelp("gh-pages");
+            if (command === "pages") {
+                console.log(chalk.yellow("  Note: `hatchkit pages` has been renamed to `hatchkit gh-pages`."));
+            }
+            const { runPagesSetup } = await import("./deploy/pages.js");
+            await runPagesSetup(resolve("."));
+            break;
+        }
         default:
             printHelp();
     }
 }
+/** No-args: show the status-aware menu. If stdin is a TTY, also offer
+ *  to kick off the most likely next step (setup or create). Agents
+ *  running non-interactively just get the menu + exit 0. */
+async function handleNoArgs() {
+    const { collectStatus, renderMenu } = await import("./status.js");
+    const s = collectStatus();
+    console.log(renderMenu(s));
+    if (!process.stdin.isTTY)
+        return;
+    const hasCore = s.providers.find((p) => p.key === "coolify")?.configured &&
+        s.providers.find((p) => p.key === "hetzner")?.configured &&
+        s.providers.find((p) => p.key === "dns")?.configured &&
+        s.providers.find((p) => p.key === "github")?.configured;
+    if (!hasCore) {
+        const ok = await confirm({ message: "Run `hatchkit setup` now?", default: true });
+        if (ok)
+            await runOnboarding();
+        return;
+    }
+    const ok = await confirm({
+        message: "Scaffold a new project now (`hatchkit create`)?",
+        default: true,
+    });
+    if (ok)
+        await handleCreate();
+}
 async function handleKeys() {
     const sub = args[1];
     const projectName = args[2];
@@ -85,9 +186,10 @@ async function handleKeys() {
         console.log("Usage: hatchkit keys <show|push> <project-name>");
         process.exit(1);
     }
+    const isJson = args.includes("--json");
     switch (sub) {
         case "show":
-            await showProjectKey(projectName);
+            await showProjectKey(projectName, { json: isJson });
             break;
         case "push":
             await pushProjectKeyToCoolify(projectName);
@@ -142,7 +244,126 @@ async function handleAdd() {
         }
         services = requested;
     }
-    await runProvision({ baseName, services });
+    // Flag parsing:
+    //   --no-write                      → never write; print a cache summary only
+    //   --enable-dev-obs                → also populate .env.development with GlitchTip/OpenPanel creds
+    //   --surfaces=<shared|separate|server-only|client-only>
+    //   --server-dir <path>             → absolute or project-relative env dir for the server
+    //   --client-dir <path>             → same for the client
+    //   (no surface flags)              → prompt interactively
+    const noWrite = args.includes("--no-write");
+    const enableDevObs = args.includes("--enable-dev-obs");
+    const surfaceFlag = args.find((a) => a.startsWith("--surfaces="))?.slice("--surfaces=".length);
+    const serverDirIdx = args.indexOf("--server-dir");
+    const clientDirIdx = args.indexOf("--client-dir");
+    const serverDirFlag = serverDirIdx >= 0 ? args[serverDirIdx + 1] : undefined;
+    const clientDirFlag = clientDirIdx >= 0 ? args[clientDirIdx + 1] : undefined;
+    const { resolve: resolvePath } = await import("node:path");
+    const validSurfaceModes = ["shared", "separate", "server-only", "client-only"];
+    let surfaces = undefined;
+    if (noWrite) {
+        surfaces = false;
+    }
+    else if (surfaceFlag || serverDirFlag || clientDirFlag) {
+        // Non-interactive surface config: require every field we need.
+        if (!surfaceFlag || !validSurfaceModes.includes(surfaceFlag)) {
+            console.log(chalk.red(`  --surfaces=<mode> is required when --server-dir/--client-dir is passed.\n  Valid: ${validSurfaceModes.join(", ")}`));
+            process.exit(1);
+        }
+        const mode = surfaceFlag;
+        const needsServer = mode === "shared" || mode === "separate" || mode === "server-only";
+        const needsClient = mode === "shared" || mode === "separate" || mode === "client-only";
+        if (needsServer && !serverDirFlag) {
+            console.log(chalk.red("  --server-dir <path> is required for this --surfaces mode."));
+            process.exit(1);
+        }
+        if (needsClient && !clientDirFlag) {
+            console.log(chalk.red("  --client-dir <path> is required for this --surfaces mode."));
+            process.exit(1);
+        }
+        surfaces = {
+            mode,
+            serverEnvDir: needsServer ? resolvePath(serverDirFlag) : undefined,
+            clientEnvDir: needsClient ? resolvePath(clientDirFlag) : undefined,
+        };
+    }
+    await runProvision({ baseName, services, surfaces, enableDevObs });
+}
+async function handleRemove() {
+    // Mirrors handleAdd: `hatchkit remove [<name>] [<services>] [--dry-run] [--yes]`
+    //   hatchkit remove                             (fully interactive)
+    //   hatchkit remove raptor-runner               (prompts for services)
+    //   hatchkit remove raptor-runner all
+    //   hatchkit remove raptor-runner glitchtip,resend
+    //   hatchkit remove raptor-runner all --yes     (skip confirmation)
+    const positional = args.slice(1).filter((a) => !a.startsWith("--"));
+    const dryRun = args.includes("--dry-run");
+    const skipConfirm = args.includes("--yes") || args.includes("-y");
+    let baseName = positional[0];
+    const rawService = positional[1];
+    const allServices = ["glitchtip", "openpanel", "resend"];
+    if (!baseName) {
+        const { input } = await import("@inquirer/prompts");
+        const { validateProjectName } = await import("./utils/validate.js");
+        baseName = await input({
+            message: "Project name to remove (e.g. raptor-runner):",
+            validate: validateProjectName,
+        });
+    }
+    let services;
+    if (!rawService) {
+        const { checkbox } = await import("@inquirer/prompts");
+        services = await checkbox({
+            message: "Which services to remove (-dev AND -prod clients each)?",
+            choices: [
+                { name: "GlitchTip (deletes the project)", value: "glitchtip", checked: true },
+                { name: "OpenPanel (deletes the project)", value: "openpanel", checked: true },
+                { name: "Resend (deletes the API key)", value: "resend", checked: true },
+            ],
+            required: true,
+        });
+    }
+    else if (rawService === "all") {
+        services = allServices;
+    }
+    else {
+        const requested = rawService.split(",").map((s) => s.trim().toLowerCase());
+        const invalid = requested.filter((s) => !allServices.includes(s));
+        if (invalid.length > 0) {
+            console.log(chalk.red(`  Unknown service(s): ${invalid.join(", ")}`));
+            console.log(chalk.dim(`  Valid: ${allServices.join(", ")}, or 'all'`));
+            process.exit(1);
+        }
+        services = requested;
+    }
+    // Confirmation — deletion is permanent upstream. Skip on --yes or --dry-run.
+    if (!skipConfirm && !dryRun) {
+        const { confirm } = await import("@inquirer/prompts");
+        const ok = await confirm({
+            message: `Delete -dev and -prod clients of "${baseName}" from ${services.join(", ")}? This can't be undone.`,
+            default: false,
+        });
+        if (!ok) {
+            console.log(chalk.dim("  Cancelled."));
+            return;
+        }
+    }
+    await runUnprovision({ baseName, services, dryRun });
+}
+async function handleDns() {
+    const sub = args[1];
+    switch (sub) {
+        case "link-to-cloudflare": {
+            const rest = args.slice(2);
+            const dryRun = rest.includes("--dry-run");
+            const domains = rest.filter((a) => !a.startsWith("--"));
+            const { runDnsLinkToCloudflare } = await import("./dns.js");
+            await runDnsLinkToCloudflare({ domains, dryRun });
+            break;
+        }
+        default:
+            printHelp("dns");
+    }
 }
 // ---------------------------------------------------------------------------
 // Commands
@@ -373,22 +594,12 @@ async function handleConfig() {
             const isGpuPlatform = (p) => gpuPlatforms.includes(p);
             switch (provider) {
                 case "coolify":
-                    await ensureCoolify();
-                    break;
                 case "hetzner":
-                    await ensureHetzner();
-                    break;
                 case "dns":
-                    await ensureDns();
-                    break;
                 case "glitchtip":
-                    await ensureGlitchtip();
-                    break;
                 case "openpanel":
-                    await ensureOpenpanel();
-                    break;
                 case "resend":
-                    await ensureResend();
+                    await reconfigureProvider(provider);
                     break;
                 case "s3": {
                     const { select } = await import("@inquirer/prompts");
@@ -400,7 +611,7 @@ async function handleConfig() {
                             { name: "R2", value: "r2" },
                         ],
                     });
-                    await ensureS3(p);
+                    await reconfigureProvider(`s3.${p}`);
                     break;
                 }
                 default:
@@ -409,7 +620,7 @@ async function handleConfig() {
                         console.log(chalk.dim("  Valid: coolify, hetzner, dns, s3, modal, runpod, hf, replicate, glitchtip, openpanel, resend"));
                         return;
                     }
-                    await ensureGpuProvider(provider);
+                    await reconfigureProvider(`gpu.${provider}`);
             }
             break;
         }
@@ -520,37 +731,199 @@ function printHelp(topic) {
 
   ${chalk.bold("Removal is not supported.")} Removing features could delete
     user code — remove manually + edit the manifest.
+`);
+        return;
+    }
+    if (topic === "gh-pages") {
+        console.log(`
+  ${chalk.bold("hatchkit gh-pages")} — wire GitHub Pages for the current repo
+
+  ${chalk.bold("Usage:")}
+    cd <project-dir> && hatchkit gh-pages
+
+  ${chalk.bold("What it does:")}
+    1. Reads the repo via \`gh repo view\` (must be a GitHub repo you own).
+    2. Scans the repo root + ${chalk.dim("docs/ site/ www/ web/")} for candidate sites:
+         - ${chalk.cyan("jekyll")}      (Gemfile + _config.yml)
+         - ${chalk.cyan("node-build")}  (package.json with a \`build\` script)
+         - ${chalk.cyan("static")}      (index.html)
+       If multiple sites are found, prompts you to pick. If none are
+       found, prompts for kind + location manually.
+    3. Enables Pages via the GitHub API with ${chalk.dim("build_type=workflow")}.
+    4. Writes ${chalk.cyan(".github/workflows/gh-pages.yml")} tailored to the site kind.
+       Refuses to overwrite any existing Pages workflow in the repo.
+    5. Optionally registers a custom domain + wires DNS:
+         - Cloudflare: auto-configured via API (uses your stored token)
+         - INWX / manual: prints the records you need to add
+       Also writes a ${chalk.cyan("CNAME")} file into the published folder (or
+       ${chalk.dim("public/")} for build-step projects).
+
+  ${chalk.bold("After running:")}
+    git add -A && git commit -m "ci: deploy to GitHub Pages" && git push
+
+  ${chalk.bold("Notes:")}
+    - Private repos need a paid GitHub plan for Pages. Free-tier repos
+      must be made public first.
+    - For ${chalk.dim("node-build")} sites, confirm the detected publish dir matches what
+      your build tool actually outputs (Vite → dist, CRA → build, etc).
+    - Monorepos / hybrids: if both the root and ${chalk.dim("docs/")} have sites, you'll
+      be prompted to pick one. Run the command twice if you want both.
+`);
+        return;
+    }
+    if (topic === "dns") {
+        console.log(`
+  ${chalk.bold("hatchkit dns")} — DNS reconciliation helpers
+
+  ${chalk.bold("Subcommands:")}
+    link-to-cloudflare [domain...]
+        For each Cloudflare zone, push its nameservers to INWX as the
+        registrar delegation. Use after importing zones into Cloudflare
+        when you don't want to click through INWX per-domain.
+
+        No args  → processes every zone the token can see.
+        Args     → space-separated domain names, filters to those.
+        ${chalk.dim("--dry-run")}     → print-only, no API calls.
+        ${chalk.dim("INWX_SANDBOX=1")} → use the OTE sandbox instead of production.
+
+  ${chalk.bold("Prerequisites:")}
+    Run ${chalk.cyan("hatchkit config add dns")} and choose Cloudflare, then answer
+    ${chalk.cyan("yes")} to "Is INWX your domain registrar?" when prompted.
+`);
+        return;
+    }
+    if (topic === "doctor") {
+        console.log(`
+  ${chalk.bold("hatchkit doctor")} — verify every configured provider
+
+  Runs a read-only API call against each provider whose credentials are
+  stored (Coolify /version, Hetzner /servers, Cloudflare /tokens/verify,
+  Resend /domains, …). Reports ok / fail / not-configured per provider
+  and exits non-zero if any check fails. Safe to run repeatedly.
 `);
         return;
     }
     if (topic === "add") {
         console.log(`
-  ${chalk.bold("hatchkit add")} — create per-service clients for an existing project
+  ${chalk.bold("hatchkit add")} — provision per-project clients and write env files
 
   ${chalk.bold("Usage:")}
-    hatchkit add [<project-name>] [<services>]
+    hatchkit add [<project-name>] [<services>] [flags]
+
+  ${chalk.bold("What it does:")}
+    · GlitchTip / OpenPanel: ${chalk.bold("one project per product")}, events tagged by
+      \`environment\` so dev / staging / prod share the same dashboard.
+      Written to ${chalk.cyan(".env.production")} only — dev noise pollutes real metrics.
+      Pass ${chalk.cyan("--enable-dev-obs")} to populate ${chalk.cyan(".env.development")} too.
+    · Resend: separate ${chalk.cyan("-dev")} and ${chalk.cyan("-prod")} API keys (audience
+      safety). Written to the server's dev + prod env respectively.
+    · ${chalk.cyan(".env.production")} is dotenvx-encrypted — commit-safe.
+      ${chalk.cyan(".env.development")} is plaintext — gitignored, not encrypted.
+    · A 0600 cache of every value is saved under
+      ${chalk.dim("<config-dir>/provisioned/<project>.*.env")} for recoverability.
+      ${chalk.dim("Secret values never hit stdout.")}
+
+  ${chalk.bold("Surfaces:")}
+    hatchkit asks which surfaces your project has. Options:
+      · ${chalk.cyan("shared")}       — server + client, one obs project (recommended)
+      · ${chalk.cyan("server-only")}  — no browser bundle (API, CLI, worker)
+      · ${chalk.cyan("client-only")}  — static site / SPA with no backend
+      · ${chalk.cyan("separate")}     — server + client, one obs project per surface
+
+    Env for each surface is written to its own directory (e.g.
+    ${chalk.dim("packages/server/.env.production")}, ${chalk.dim("packages/client/.env.production")}).
+
+  ${chalk.bold("Services:")}
+    glitchtip   GLITCHTIP_DSN (server) / PUBLIC_GLITCHTIP_DSN (client)
+    openpanel   OPENPANEL_* (server) / PUBLIC_OPENPANEL_* (client)
+    resend      RESEND_API_KEY (server only)
+
+  ${chalk.bold("Flags:")}
+    --enable-dev-obs            Also populate .env.development with obs creds.
+    --no-write                  Skip writing; save 0600 cache only.
+    --surfaces=<mode>           shared | server-only | client-only | separate
+    --server-dir <path>         Server env directory (skips prompt when set).
+    --client-dir <path>         Client env directory (skips prompt when set).
 
-  Both args are optional — anything missing is prompted for, including a
-  multi-select of which services to run. ${chalk.dim("(<services> is 'all', a single")}
-  ${chalk.dim("service, or a comma-separated list.)")}
+  ${chalk.bold("Examples:")}
+    hatchkit add
+    hatchkit add raptor-runner
+    hatchkit add raptor-runner all --enable-dev-obs
+    hatchkit add raptor-runner glitchtip,resend --no-write
+    hatchkit add raptor-runner all --surfaces=shared \\
+        --server-dir ./raptor-runner/packages/server \\
+        --client-dir ./raptor-runner/packages/client
+`);
+        return;
+    }
+    if (topic === "remove") {
+        console.log(`
+  ${chalk.bold("hatchkit remove")} — inverse of ${chalk.cyan("add")}: tear down per-project clients
+
+  ${chalk.bold("Usage:")}
+    hatchkit remove [<project-name>] [<services>] [--dry-run] [--yes]
+
+  Both positional args are optional — anything missing is prompted for.
+  ${chalk.dim("(<services> is 'all', a single service, or a comma-separated list.)")}
 
   ${chalk.bold("What it does:")}
-    For every selected service, creates two clients:
+    For every selected service, deletes both clients:
       - ${chalk.cyan("<project-name>-dev")}
       - ${chalk.cyan("<project-name>-prod")}
-    …and prints an env block for each, plus saves it under
+    Also removes the local env cache at
     ${chalk.dim("<config-dir>/provisioned/<project-name>.{dev,prod}.env")}.
 
+    Re-runs are idempotent — missing upstream resources log
+    ${chalk.dim("already gone")} and keep going.
+
   ${chalk.bold("Services:")}
-    glitchtip   Creates a GlitchTip project, returns GLITCHTIP_DSN
-    openpanel   Creates an OpenPanel client, returns OPENPANEL_CLIENT_ID/_SECRET
-    resend      Creates a restricted Resend API key, returns RESEND_API_KEY
+    glitchtip   Deletes the GlitchTip project
+    openpanel   Deletes the OpenPanel project (and clears cached creds)
+    resend      Finds API keys by name and deletes them
+
+  ${chalk.bold("Options:")}
+    --dry-run   Print what would be deleted; hit no APIs, remove no files.
+    --yes, -y   Skip the interactive confirmation prompt.
 
   ${chalk.bold("Examples:")}
-    hatchkit add
-    hatchkit add raptor-runner
-    hatchkit add raptor-runner all
-    hatchkit add raptor-runner glitchtip,resend
+    hatchkit remove raptor-runner all
+    hatchkit remove raptor-runner glitchtip,resend --dry-run
+    hatchkit remove raptor-runner all --yes
+`);
+        return;
+    }
+    if (topic === "rename-domain") {
+        console.log(`
+  ${chalk.bold("hatchkit rename-domain")} — move a project to a new domain
+
+  ${chalk.bold("Usage:")}
+    cd <project-dir> && hatchkit rename-domain --to <new-domain>
+    hatchkit rename-domain --dir <project-dir> --to <new-domain> --dry-run
+
+  ${chalk.bold("What it rewrites:")}
+    ${chalk.cyan(".hatchkit.json")}                                (manifest domain)
+    ${chalk.cyan("infra/terraform/stacks/<stack>/<name>.tfvars")}  (domain + subdomain keys)
+    ${chalk.cyan("infra/stacks/<name>.env")}                       (APP_DOMAIN +
+                                                     any line that mentions the
+                                                     old full domain; skips
+                                                     COOLIFY_URL)
+
+  ${chalk.bold("What it does NOT touch (you run these manually):")}
+    - ${chalk.dim("terraform apply")} — review the plan before destroying old records.
+    - Coolify app FQDN + redeploy — UI or API. New TLS cert: 1-3 min.
+    - ${chalk.dim("hatchkit dns link-to-cloudflare")} if NS flip is needed.
+    - OAuth redirect URIs, Stripe webhooks, app-code references.
+
+  ${chalk.bold("Options:")}
+    --to <domain>   Target domain (prompted if omitted).
+    --dir <path>    Project dir (defaults to cwd).
+    --dry-run       Show the plan; don't write.
+    --yes, -y       Skip the confirmation prompt.
+
+  ${chalk.bold("Example:")}
+    cd ~/src/my-project
+    hatchkit rename-domain --to my-project.com --dry-run
+    hatchkit rename-domain --to my-project.com
 `);
         return;
     }
@@ -559,30 +932,88 @@ function printHelp(topic) {
   ${chalk.bold("hatchkit config")} — manage provider credentials
 
   ${chalk.bold("Subcommands:")}
-    config              Show status of every configured provider
+    config              Show status of every configured provider (alias: \`status\`)
     config add <p>      Configure a provider
-                        (coolify, hetzner, dns, s3, modal, runpod, hf, replicate)
+                        (coolify, hetzner, dns, s3, modal, runpod, hf, replicate,
+                         glitchtip, openpanel, resend)
     config reset        Clear ALL CLI config (providers, tokens, ML registry, ports)
+`);
+        return;
+    }
+    if (topic === "status") {
+        console.log(`
+  ${chalk.bold("hatchkit status")} — show provider status + next-step hint
+
+  ${chalk.bold("Usage:")}
+    hatchkit status [--json]
+
+  ${chalk.bold("Output:")}
+    Human: ✓/· per provider, next-best-step, config path.
+    JSON:  full StatusSnapshot — stable shape for agents / scripts.
+`);
+        return;
+    }
+    if (topic === "explain") {
+        console.log(`
+  ${chalk.bold("hatchkit explain")} — one-page mental model of the CLI
+
+  ${chalk.bold("Usage:")}
+    hatchkit explain [--json]
+
+  Dumps a plain-text (or JSON) description of concepts, commands, and
+  the canonical workflow. Useful for humans with zero context and for
+  agents that need to "grok" hatchkit before driving it.
+`);
+        return;
+    }
+    if (topic === "completion") {
+        console.log(`
+  ${chalk.bold("hatchkit completion")} — print a shell-completion script
+
+  ${chalk.bold("Usage:")}
+    hatchkit completion <zsh|bash|fish>
+
+  Pipe into your shell config, e.g.:
+    hatchkit completion zsh  > ~/.zsh/completions/_hatchkit
+    hatchkit completion bash > /usr/local/etc/bash_completion.d/hatchkit
+    hatchkit completion fish > ~/.config/fish/completions/hatchkit.fish
 `);
         return;
     }
     console.log(`
   ${chalk.bold("Usage:")} hatchkit <command> [options]
 
-  ${chalk.bold("Commands:")}
-    create          Scaffold a new project (default)
-    add             Create GlitchTip / OpenPanel / Resend clients for an existing project
+  ${chalk.bold("Getting started:")}
+    setup           One-time onboarding — wires up all credentials (alias: init)
+    status          Show what's configured and what's next
+    doctor          Health-check every provider with contextual fix hints
+    explain         One-page mental model of the CLI
+
+  ${chalk.bold("Projects:")}
+    create          Scaffold a new project (interactive)
     update          Add features to an already-scaffolded project (run in project dir)
+    add             Create GlitchTip / OpenPanel / Resend clients for an existing project
+    remove          Delete the -dev/-prod clients created by 'add' (inverse of add)
+    rename-domain   Move a scaffolded project to a new domain (rewrites tfvars/env/manifest)
+    gh-pages        Wire GitHub Pages for the current repo (static / Vite / Jekyll — with DNS)
+    dns             DNS reconciliation helpers (link-to-cloudflare, …)
     keys show <p>   Print the dotenvx private key for a project
     keys push <p>   Push the key onto the project's Coolify app
-    setup           Run first-time setup / onboarding (alias: init)
-    config          Show provider status
-    config add <p>  Configure a provider (coolify, hetzner, dns, s3, modal, etc.)
+
+  ${chalk.bold("Config:")}
+    config          Show provider status (same as \`status\`)
+    config add <p>  Configure a provider (coolify, hetzner, dns, s3, modal, …)
     config reset    Clear ALL CLI config (providers, tokens, ML registry, ports)
 
+  ${chalk.bold("For agents / scripts:")}
+    status --json   StatusSnapshot as JSON
+    doctor --json   Per-provider health with fix hints as JSON
+    completion <shell>  Print a zsh/bash/fish completion script
+
   ${chalk.bold("Options:")}
     --version, -v   Print the CLI version
     --help, -h      Show this help message (pass to a subcommand for detail)
+    --json          Machine-readable output (status, doctor, explain)
     --dry-run       (with \`create\`) show what would change without writing
     --yes, -y       (with \`create\`) skip prompts, use defaults / --config values
     --config <path> (with \`create\`) load JSON overrides for ProjectConfig fields
@@ -592,8 +1023,8 @@ function printHelp(topic) {
 
   ${chalk.bold("Environment:")}
     HATCHKIT_CONF_DIR   Override the config/ports-registry location
-                          (advanced — useful for isolated per-workspace state
-                          or automated testing).
+
+  ${chalk.dim("Run `hatchkit help <command>` for per-command detail.")}
 `);
 }
 // ---------------------------------------------------------------------------