@veleads/gtm 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@veleads/gtm`. Each entry is tagged: **no action**, **op
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-24
+- **opt-in** `gtm stack up | down [--wipe] | status`: each project repo runs its own stack (Postgres +
+  hatchet-lite + gtm worker) on Docker, as compose project `gtm-<project_id>` with its own volumes. The
+  worker is the image `ghcr.io/veleads/gtm-worker:<version>` matching the pinned core; it applies
+  database migrations when it starts. Connection settings go to `~/.gtm/stacks/<project_id>.env`
+  (used by `gtm job`), provider keys to `~/.gtm/stacks/<project_id>.secrets.env`; nothing is written
+  into the repo. Ports are configurable (`GTM_PG_PORT`, `GTM_HATCHET_UI_PORT`, `GTM_HATCHET_GRPC_PORT`)
+  and bound to localhost only. Releases now also publish the worker image. The gtm-core development
+  stack (`pnpm stack:up` + `pnpm worker`) still works as a fallback for `gtm job`.
+- **action** One database per project: each project repo runs its own stack (Postgres + Hatchet +
+  workers) and core holds no project state. Rows no longer carry `project_id`; unique keys are now
+  per database (`accounts` on `tam_id` + `domain`, `contacts` on `linkedin_url`, …). A new
+  single-row `project` table binds the database to one `project_id` on the first job, and workers
+  refuse jobs for any other project. The `account`, `contact`, `lead` and `signal` schemas drop
+  `project_id`; `project.yaml` and job payloads keep it. DB migration
+  `20261025000000_database_per_project` binds an existing single-project database automatically and
+  **refuses to run on a database that holds more than one project**: give each project its own
+  database (copy its rows, filtered by `project_id`) before upgrading. Point each project's
+  `DATABASE_URL` at its own database.
+
 ## [0.6.0] - 2026-10-24
 - **no action** Layered ICP: `context/icp.yaml` can have an optional `core.firmographics` that every
   segment shares; segments then hold only what differs, and a segment field **replaces** the same core

package/dist/cli.js

@@ -280,7 +280,6 @@ var CampaignConfig = z5.object({
 // ../schemas/src/account.ts
 import { z as z6 } from "zod";
 var Account = z6.object({
-  project_id: Slug,
   tam_id: Slug,
   domain: Domain,
   name: z6.string().min(1),
@@ -297,7 +296,6 @@ var Account = z6.object({
 import { z as z7 } from "zod";
 var EmailStatus = z7.enum(["valid", "catch_all", "invalid", "unknown", "not_found"]);
 var Contact = z7.object({
-  project_id: Slug,
   account_domain: Domain,
   first_name: z7.string().min(1),
   last_name: z7.string().min(1),
@@ -314,7 +312,6 @@ var Contact = z7.object({
 // ../schemas/src/signal.ts
 import { z as z8 } from "zod";
 var SignalEvent = z8.object({
-  project_id: Slug,
   signal_key: Slug,
   account_domain: Domain,
   contact_linkedin_url: z8.string().url().nullable(),
@@ -327,7 +324,6 @@ var SignalEvent = z8.object({
 // ../schemas/src/lead.ts
 import { z as z9 } from "zod";
 var Lead = z9.object({
-  project_id: Slug,
   campaign_id: Slug,
   run_id: z9.uuid(),
   email: z9.email(),
@@ -467,9 +463,9 @@ function githubToken() {
 }
 var login = (handle) => handle.replace(/^@/, "").toLowerCase();
 var GitHubError = class extends Error {
-  constructor(status, message) {
+  constructor(status2, message) {
     super(message);
-    this.status = status;
+    this.status = status2;
     this.name = "GitHubError";
   }
   status;
@@ -1299,15 +1295,62 @@ import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
 import { homedir } from "os";
 import { join as join9 } from "path";
 var STACK_ENV_FILE = process.env.GTM_STACK_ENV ?? join9(homedir(), ".gtm", "stack.env");
-function loadStackEnv(file = STACK_ENV_FILE) {
-  if (!existsSync7(file)) return false;
+var STACKS_DIR = process.env.GTM_STACKS_DIR ?? join9(homedir(), ".gtm", "stacks");
+var projectStackEnvFile = (projectId) => join9(STACKS_DIR, `${projectId}.env`);
+var projectSecretsFile = (projectId) => join9(STACKS_DIR, `${projectId}.secrets.env`);
+function readEnvFile(file) {
+  const out = {};
+  if (!existsSync7(file)) return out;
   for (const line of readFileSync8(file, "utf8").split("\n")) {
     const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
-    if (m && process.env[m[1]] === void 0) process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+    if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "");
   }
+  return out;
+}
+function loadStackEnv(file = STACK_ENV_FILE) {
+  if (!existsSync7(file)) return false;
+  for (const [k, v] of Object.entries(readEnvFile(file))) if (process.env[k] === void 0) process.env[k] = v;
   return true;
 }
 
+// ../core/src/local-stack.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitFor(what, check, seconds = 120) {
+  for (let i = 0; i < seconds; i++) {
+    if (await check()) return;
+    await sleep(1e3);
+  }
+  throw new Error(`timed out waiting for ${what}`);
+}
+async function hatchetReady(url) {
+  try {
+    return (await fetch(`${url}/api/ready`)).ok;
+  } catch {
+    return false;
+  }
+}
+async function createHatchetToken(exec, name) {
+  let tenant = "";
+  await waitFor("hatchet tenant", () => {
+    try {
+      tenant = exec("postgres", ["psql", "-U", "gtm", "-d", "hatchet", "-tAc", `select id from "Tenant" where slug = 'default'`]);
+    } catch {
+      tenant = "";
+    }
+    return /^[0-9a-f-]{36}$/.test(tenant);
+  });
+  let token = "";
+  await waitFor("hatchet token", () => {
+    try {
+      token = exec("hatchet-lite", ["/hatchet-admin", "token", "create", "--config", "/config", "--tenant-id", tenant, "--name", name]).split("\n").at(-1).trim();
+    } catch {
+      token = "";
+    }
+    return /^eyJ[\w-]+\.[\w-]+\.[\w-]+$/.test(token);
+  }, 60);
+  return token;
+}
+
 // ../core/src/adapters/mock-account-source.ts
 import { createHash as createHash3 } from "crypto";
 
@@ -1644,9 +1687,10 @@ async function runJob(root2, args2) {
     console.error(input);
     return false;
   }
+  loadStackEnv(projectStackEnvFile(input.ctx.project_id));
   loadStackEnv();
   if (!process.env.HATCHET_CLIENT_TOKEN) {
-    console.error(`No Hatchet connection. Local: run \`pnpm stack:up\` and \`pnpm worker\` in gtm-core (writes ${STACK_ENV_FILE}). Deployed: set HATCHET_CLIENT_TOKEN.`);
+    console.error(`No Hatchet connection. Run \`npx gtm stack up\` in this project repo (writes ${projectStackEnvFile(input.ctx.project_id)}). Deployed: set HATCHET_CLIENT_TOKEN.`);
     return false;
   }
   const { HatchetClient } = await import("@hatchet-dev/typescript-sdk/v1");
@@ -1655,7 +1699,7 @@ async function runJob(root2, args2) {
     throw new Error("runs on the gtm worker");
   } });
   console.log(`\u2022 running tam for ${input.segments.length} segment(s) via ${input.source} (budget $${input.budget_usd})`);
-  const hint = setTimeout(() => console.log("  \u2026 still waiting. Is the worker running? (`pnpm worker` in gtm-core)"), 2e4);
+  const hint = setTimeout(() => console.log("  \u2026 still waiting. Is the worker running? (`npx gtm stack status`)"), 2e4);
   try {
     const output = await tam.run(input);
     printTam(TamJobResult.parse(output), campaign);
@@ -1695,30 +1739,136 @@ function runNewCampaign(root2, campaign) {
   return true;
 }
 
-// src/commands/status.ts
-import { existsSync as existsSync12, readdirSync as readdirSync3, readFileSync as readFileSync13 } from "fs";
+// src/commands/stack.ts
+import { spawnSync as spawnSync4 } from "child_process";
+import { chmodSync, existsSync as existsSync12, mkdirSync as mkdirSync4, readFileSync as readFileSync13, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
 import { join as join14 } from "path";
 import { parse as parse8 } from "yaml";
+var WORKER_IMAGE = "ghcr.io/veleads/gtm-worker";
+var PORTS = { GTM_PG_PORT: 5432, GTM_HATCHET_UI_PORT: 8888, GTM_HATCHET_GRPC_PORT: 7077 };
+function stackSettings(projectId, env = process.env) {
+  const envFile = projectStackEnvFile(projectId);
+  const saved = readEnvFile(envFile);
+  const ports = Object.fromEntries(
+    Object.keys(PORTS).map((k) => [k, Number(env[k] ?? saved[k] ?? PORTS[k])])
+  );
+  for (const [k, v] of Object.entries(ports)) if (!Number.isInteger(v) || v < 1 || v > 65535) throw new Error(`${k} must be a port number, got "${v}"`);
+  return {
+    projectId,
+    composeProject: `gtm-${projectId}`,
+    composeFile: join14(KIT_DIR, "stack", "docker-compose.yml"),
+    envFile,
+    secretsFile: projectSecretsFile(projectId),
+    workerImage: env.GTM_WORKER_IMAGE ?? `${WORKER_IMAGE}:${GTM_VERSION}`,
+    ports
+  };
+}
+function composeEnv(s, token = "") {
+  return {
+    ...Object.fromEntries(Object.entries(s.ports).map(([k, v]) => [k, String(v)])),
+    GTM_WORKER_IMAGE: s.workerImage,
+    GTM_SECRETS_FILE: s.secretsFile,
+    HATCHET_CLIENT_TOKEN: token
+  };
+}
+function stackEnvText(s, token) {
+  return [
+    `# Written by \`gtm stack up\` for project ${s.projectId}. Local stack only; never commit.`,
+    `DATABASE_URL=postgresql://gtm:gtm@localhost:${s.ports.GTM_PG_PORT}/gtm`,
+    `HATCHET_CLIENT_TOKEN=${token}`,
+    "HATCHET_CLIENT_TLS_STRATEGY=none",
+    ...Object.entries(s.ports).map(([k, v]) => `${k}=${v}`),
+    ""
+  ].join("\n");
+}
+function compose(s, args2, opts = {}) {
+  const res = spawnSync4("docker", ["compose", "-f", s.composeFile, "-p", s.composeProject, ...args2], {
+    env: { ...process.env, ...composeEnv(s, opts.token) },
+    encoding: "utf8",
+    stdio: opts.quiet ? "pipe" : ["ignore", "inherit", "inherit"]
+  });
+  if (res.error) throw new Error(`docker is not available (${res.error.message}). Install Docker Desktop or Docker Engine first.`);
+  if (res.status !== 0) throw new Error(`docker compose ${args2.join(" ")} failed${opts.quiet ? `: ${res.stderr || res.stdout}` : ""}`);
+  return (res.stdout ?? "").trim();
+}
+async function up(s) {
+  const ui = `http://localhost:${s.ports.GTM_HATCHET_UI_PORT}`;
+  console.log(`\u2022 starting postgres + hatchet-lite (${s.composeProject})`);
+  compose(s, ["up", "-d", "--wait", "postgres"]);
+  compose(s, ["up", "-d", "hatchet-lite"]);
+  await waitFor("hatchet-lite", () => hatchetReady(ui));
+  console.log("\u2022 creating a Hatchet API token");
+  const token = await createHatchetToken((service, args2) => compose(s, ["exec", "-T", service, ...args2], { quiet: true }), `gtm-${s.projectId}-${Date.now()}`);
+  mkdirSync4(STACKS_DIR, { recursive: true, mode: 448 });
+  writeFileSync6(s.envFile, stackEnvText(s, token));
+  chmodSync(s.envFile, 384);
+  console.log(`\u2022 starting the worker (${s.workerImage})`);
+  compose(s, ["up", "-d", "worker"], { token });
+  console.log(`
+Stack for ${s.projectId} is up.
+  Hatchet UI   ${ui}   (local login admin@example.com / Admin123!!)
+  Postgres     postgresql://gtm:gtm@localhost:${s.ports.GTM_PG_PORT}/gtm   (this project's database)
+  Settings     ${s.envFile}   (used by \`npx gtm job\`)
+  Secrets      ${s.secretsFile}   (provider API keys for the worker; ${existsSync12(s.secretsFile) ? "found" : "not created yet"})
+Next: \`npx gtm job tam <campaign>\`.`);
+}
+function down(s, wipe) {
+  compose(s, ["down", ...wipe ? ["-v"] : []]);
+  if (wipe) rmSync2(s.envFile, { force: true });
+  console.log(wipe ? `Stack stopped; this project's database, Hatchet state and ${s.envFile} are deleted (secrets file kept).` : "Stack stopped; data kept (`npx gtm stack up` to resume).");
+}
+async function status(s) {
+  compose(s, ["ps"]);
+  const ready = await hatchetReady(`http://localhost:${s.ports.GTM_HATCHET_UI_PORT}`);
+  console.log(`hatchet: ${ready ? "ready" : "not ready"} \xB7 settings: ${existsSync12(s.envFile) ? s.envFile : "missing (run `npx gtm stack up`)"} \xB7 worker image: ${s.workerImage}`);
+}
+async function runStack(root2, args2, opts = {}) {
+  const [action] = args2;
+  if (!action || !["up", "down", "status"].includes(action)) {
+    console.error("Usage: gtm stack up | down [--wipe] | status");
+    return false;
+  }
+  if (!existsSync12(join14(root2, "project.yaml"))) {
+    console.error("project.yaml not found: run gtm stack inside a project repo.");
+    return false;
+  }
+  try {
+    const project = ProjectFile.parse(parse8(readFileSync13(join14(root2, "project.yaml"), "utf8")));
+    const s = stackSettings(project.project_id);
+    if (action === "up") await up(s);
+    else if (action === "down") down(s, Boolean(opts.wipe));
+    else await status(s);
+    return true;
+  } catch (e) {
+    console.error(`gtm stack ${action}: ${e.message}`);
+    return false;
+  }
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync13, readdirSync as readdirSync3, readFileSync as readFileSync14 } from "fs";
+import { join as join15 } from "path";
+import { parse as parse9 } from "yaml";
 function readYaml2(file) {
   try {
-    return parse8(readFileSync13(file, "utf8"));
+    return parse9(readFileSync14(file, "utf8"));
   } catch {
     return null;
   }
 }
 function campaignStages(root2) {
-  return subdirs(join14(root2, "campaigns")).map((id) => ({ id, stage: readYaml2(join14(root2, "campaigns", id, "config.yaml"))?.stage ?? "?" }));
+  return subdirs(join15(root2, "campaigns")).map((id) => ({ id, stage: readYaml2(join15(root2, "campaigns", id, "config.yaml"))?.stage ?? "?" }));
 }
 function runStatus(root2) {
-  const project = readYaml2(join14(root2, "project.yaml"));
-  const icp = readYaml2(join14(root2, "context", "icp.yaml"));
+  const project = readYaml2(join15(root2, "project.yaml"));
+  const icp = readYaml2(join15(root2, "context", "icp.yaml"));
   console.log(`${project?.name ?? "?"} (${project?.project_id ?? "?"}) \xB7 status ${project?.status ?? "?"} \xB7 core v${GTM_VERSION}`);
   console.log(`ICP gate: ${icp?.approval?.status ?? "?"}${icp?.approval?.approved_by ? ` by ${icp.approval.approved_by} on ${icp.approval.approved_at}` : ""}
 `);
-  const rows = subdirs(join14(root2, "campaigns")).map((id) => {
-    const cfg = readYaml2(join14(root2, "campaigns", id, "config.yaml")) ?? {};
-    const runsDir = join14(root2, "campaigns", id, "runs");
-    const last = existsSync12(runsDir) ? readdirSync3(runsDir).filter((f) => f.endsWith(".md")).sort().at(-1) ?? "-" : "-";
+  const rows = subdirs(join15(root2, "campaigns")).map((id) => {
+    const cfg = readYaml2(join15(root2, "campaigns", id, "config.yaml")) ?? {};
+    const runsDir = join15(root2, "campaigns", id, "runs");
+    const last = existsSync13(runsDir) ? readdirSync3(runsDir).filter((f) => f.endsWith(".md")).sort().at(-1) ?? "-" : "-";
     return [id, cfg.stage ?? "?", cfg.gates?.copy?.status ?? "?", cfg.gates?.launch?.status ?? "?", cfg.owner ?? "?", last];
   });
   if (!rows.length) {
@@ -1735,9 +1885,9 @@ function runStatus(root2) {
 }
 
 // src/commands/upgrade.ts
-import { spawnSync as spawnSync4 } from "child_process";
-import { existsSync as existsSync13, readFileSync as readFileSync14 } from "fs";
-import { join as join15 } from "path";
+import { spawnSync as spawnSync5 } from "child_process";
+import { existsSync as existsSync14, readFileSync as readFileSync15 } from "fs";
+import { join as join16 } from "path";
 
 // src/changelog.ts
 function compareVersions(a, b) {
@@ -1756,17 +1906,17 @@ function changelogBetween(text, from, to) {
 
 // src/commands/upgrade.ts
 function detectPackageManager(root2) {
-  if (existsSync13(join15(root2, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync13(join15(root2, "yarn.lock"))) return "yarn";
+  if (existsSync14(join16(root2, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync14(join16(root2, "yarn.lock"))) return "yarn";
   return "npm";
 }
 function installExact(root2, pm, spec) {
-  const onPath = (bin) => spawnSync4(bin, ["--version"], { stdio: "ignore" }).status === 0;
+  const onPath = (bin) => spawnSync5(bin, ["--version"], { stdio: "ignore" }).status === 0;
   const [cmd, args2] = pm === "npm" ? ["npm", ["install", "--save-dev", "--save-exact", spec]] : pm === "pnpm" ? onPath("pnpm") ? ["pnpm", ["add", "-D", "--save-exact", spec]] : ["npx", ["-y", "pnpm@10", "add", "-D", "--save-exact", spec]] : onPath("yarn") ? ["yarn", ["add", "-D", "--exact", spec]] : ["npx", ["-y", "yarn@1", "add", "-D", "--exact", spec]];
-  return spawnSync4(cmd, args2, { cwd: root2, stdio: "inherit" }).status ?? 1;
+  return spawnSync5(cmd, args2, { cwd: root2, stdio: "inherit" }).status ?? 1;
 }
 function gtm(root2, args2) {
-  return spawnSync4("npx", ["gtm", ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
+  return spawnSync5("npx", ["gtm", ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
 }
 var FROZEN_STAGES = ["qa", "launch"];
 function runUpgrade(root2, opts) {
@@ -1781,7 +1931,7 @@ function runUpgrade(root2, opts) {
     console.error("Finish the launch first, or re-run with --force if a GTM engineer approved it.");
     return false;
   }
-  const dirty = spawnSync4("git", ["status", "--porcelain"], { cwd: root2, encoding: "utf8" });
+  const dirty = spawnSync5("git", ["status", "--porcelain"], { cwd: root2, encoding: "utf8" });
   if (dirty.status === 0 && dirty.stdout.trim() && !opts.force) {
     console.error("Refusing to upgrade with uncommitted changes. Commit or stash first (or --force).");
     return false;
@@ -1794,9 +1944,9 @@ function runUpgrade(root2, opts) {
   if (gtm(root2, ["migrate"]) !== 0) return false;
   const valid = gtm(root2, ["validate"]) === 0;
   const after = pinnedVersion(root2) ?? target;
-  const changelog = join15(root2, "node_modules", ...PACKAGE_NAME.split("/"), "CHANGELOG.md");
-  if (existsSync13(changelog)) {
-    const notes = changelogBetween(readFileSync14(changelog, "utf8"), before, after);
+  const changelog = join16(root2, "node_modules", ...PACKAGE_NAME.split("/"), "CHANGELOG.md");
+  if (existsSync14(changelog)) {
+    const notes = changelogBetween(readFileSync15(changelog, "utf8"), before, after);
     console.log(`
 === Changes ${before} \u2192 ${after} ===
 ${notes || "(no changelog entries)"}
@@ -1935,11 +2085,24 @@ var COMMANDS = {
       "tam: builds the TAM for the campaign's segments into the database (needs an approved ICP and",
       "config.yaml \u2192 tam.source; mock-accounts for a local proof) and prints the funnel, cost and run_id.",
       "Validates first, sends the resolved config to the workers via Hatchet, and waits for the result.",
-      "Local: `pnpm stack:up` + `pnpm worker` in gtm-core (settings in ~/.gtm/stack.env).",
+      "Needs this project's stack: `npx gtm stack up` (settings in ~/.gtm/stacks/<project_id>.env).",
       "Planned (exit 1, a stop per AGENTS.md): enrich, suppression:import, signals, qualify, qa, push, activate, results."
     ],
     writes: "Rows in Postgres (runs, accounts, costs). No repo files: copy the printed run-log row into the run log.",
     examples: ["npx gtm job tam q1-uk-cfo"]
+  },
+  stack: {
+    usage: "gtm stack up\ngtm stack down [--wipe]\ngtm stack status",
+    summary: "run this project's own stack (Postgres + Hatchet + worker) on Docker",
+    details: [
+      "One stack per project (compose project gtm-<project_id>, its own volumes and database). The worker image",
+      "matches the core version this repo pins and applies database migrations when it starts. Needs Docker.",
+      "Ports: GTM_PG_PORT (5432), GTM_HATCHET_UI_PORT (8888), GTM_HATCHET_GRPC_PORT (7077); set them to run two stacks at once.",
+      "Provider API keys for the worker: ~/.gtm/stacks/<project_id>.secrets.env (never in the repo).",
+      "down keeps the data; down --wipe deletes this project's database and Hatchet state (ask the human first)."
+    ],
+    writes: "Docker containers and volumes, and ~/.gtm/stacks/<project_id>.env. No repo files.",
+    examples: ["npx gtm stack up", "npx gtm stack status", "GTM_PG_PORT=5433 npx gtm stack up"]
   }
 };
 function generalHelp(version) {
@@ -1997,6 +2160,7 @@ var { values, positionals } = parseArgs({
     check: { type: "boolean" },
     "dry-run": { type: "boolean" },
     force: { type: "boolean" },
+    wipe: { type: "boolean" },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" }
   }
@@ -2050,6 +2214,8 @@ async function run() {
       return runUpgrade(root, { version: args[0], force: values.force });
     case "job":
       return runJob(root, args);
+    case "stack":
+      return runStack(root, args, { wipe: values.wipe });
     case void 0:
       return help(void 0);
     case "help":

package/kit/AGENTS.md

@@ -26,8 +26,8 @@ Three layers, never mixed:
 | Layer | Where | Holds | Never holds |
 |---|---|---|---|
 | **Brain** | git (this repo) | context, configs, copy, run logs, aggregate reports | PII, lead lists, exports, secrets |
-| **Execution** | central workers (deployed from gtm-core, run on Hatchet) | TAM build, enrichment waterfall, verification, scoring, signals, sender push | business decisions |
-| **Data** | central Postgres | accounts, contacts, enrichments, signals, suppression, campaign leads, events, runs, costs | anything not scoped by `project_id` + `run_id` |
+| **Execution** | this project's workers (gtm-core code, run on Hatchet) | TAM build, enrichment waterfall, verification, scoring, signals, sender push | business decisions |
+| **Data** | this project's own Postgres (one database per project) | accounts, contacts, enrichments, signals, suppression, campaign leads, events, runs, costs | another project's data; rows without a `run_id` |
 
 **The agent orchestrates; code does bulk work.** The agent picks the playbook, edits config, runs a
 `npx gtm job` command, reads the aggregate output, QAs a small sample, and writes the run log. The
@@ -129,6 +129,7 @@ Rules, no exceptions:
 - Bounce rate > 3% or spam complaints in results: recommend pausing; the human decides.
 - Anything that would contact a real person outside a launch that passed all three gates.
 - You are about to edit `AGENTS.md` or anything in `.gtm/`.
+- You are about to run `npx gtm stack down --wipe`: it deletes this project's database. Only on the human's request.
 
 ## 5. Data rules
 
@@ -140,10 +141,13 @@ Rules, no exceptions:
 3. QA sample review happens in the DB console or terminal output. Do not paste sampled rows into files
    or PR descriptions; summarize ("19/20 correct persona").
 4. **Secrets** live only in `.env` (git-ignored) or the secret manager. Never print, echo, commit or
-   paste keys. Provider API keys never live in a project repo: they are on the central workers.
-5. Every DB row carries `project_id`, `campaign_id`, `run_id` and timestamps. Every job prints its `run_id`.
+   paste keys. Provider API keys never live in a project repo: they are on this project's workers (local stack:
+   `~/.gtm/stacks/<project_id>.secrets.env`, written by the human).
+5. Every DB row carries `campaign_id`, `run_id` and timestamps (the database itself is the project scope).
+   Every job prints its `run_id`.
 6. Every lead field records its source (`field_sources`) so GDPR "where did you get my data?" can be answered.
-7. This project\x27s data is never mixed with another project\x27s: jobs are scoped by `project_id`.
+7. This project's data is never mixed with another project's: it has its own database, bound to this
+   `project_id` on the first job, and jobs for another project are refused.
 
 ## 6. Team and concurrency rules
 
@@ -178,6 +182,8 @@ Run from the repo root. If you cannot run shell commands, give the exact command
 | `npx gtm sync [--check]` | re-copy core kit into `.gtm/` and `AGENTS.md` | available |
 | `npx gtm migrate [--dry-run]` | rewrite YAML files to the installed core's schema versions | available |
 | `npx gtm upgrade [version]` | install a newer core, sync, migrate, validate, show changelog | available |
+| `npx gtm stack up` / `npx gtm stack status` | start / check this project's own stack (Postgres + Hatchet + worker at this core version) on Docker; jobs need it | available |
+| `npx gtm stack down [--wipe]` | stop the stack, data kept; `--wipe` deletes this project's database (only when the human asks) | available |
 | `npx gtm job tam <campaign>` | build TAM into `accounts` (via the workers), print funnel counts, cost, run_id and a run-log row | available |
 | `npx gtm job enrich <campaign>` | find people + email waterfall + verification, cost-capped | planned |
 | `npx gtm job suppression:import <campaign> <file>` | load suppression lists (file stays outside git) | planned |
@@ -203,7 +209,8 @@ Every job prints a `run_id`, counts and cost. Copy those into the run log.
 
 - **New project:** create an empty **private** repo (e.g. `<org>/gtm-project-<slug>`), clone it, and in
   that folder run `npx @veleads/gtm init . --name "<Name>"` (or `init <slug>` to create a new folder).
-  Commit, push, then stage `00-intake` begins.
+  Commit, push, then stage `00-intake` begins. Before the first job (stage 2), start the project's stack
+  with `npx gtm stack up` (needs Docker).
 - **New campaign:** from up-to-date `main`: `git switch -c campaign/<slug>`,
   `npx gtm new-campaign <slug>`, fill `brief.md`, set `stage`, follow the routing table.
 - **New SDR:** read this file and `PROJECT.md`, run `npx gtm status`, then section 2 with a GTM engineer watching.
@@ -214,7 +221,7 @@ Every job prints a `run_id`, counts and cost. Copy those into the run log.
   The PR contains the new `.gtm/`, `AGENTS.md`, lockfile, and any YAML migrations. Read the changelog
   in the PR body: entries marked **migration** or **action** need a human look.
 - Upgrades are refused while a campaign is in `qa` or `launch`. Live campaigns (`results`) keep running
-  on the central workers across upgrades; nothing changes for them mid-flight.
+  on this project's workers across upgrades; nothing changes for them mid-flight.
 - New opt-in capabilities appear as `features` in `project.yaml`; they are off until you enable them.
 - If `validate` says "run `npx gtm sync`" or "`migrate`", the repo and the installed core disagree:
   run the command, review the diff, commit it on its own branch.

package/kit/schemas/account.schema.json

@@ -2,10 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "project_id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9-]*$"
-    },
     "tam_id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$"
@@ -90,7 +86,6 @@
     }
   },
   "required": [
-    "project_id",
     "tam_id",
     "domain",
     "name",

package/kit/schemas/contact.schema.json

@@ -2,10 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "project_id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9-]*$"
-    },
     "account_domain": {
       "type": "string",
       "pattern": "^(?!-)[a-z0-9-]+(\\.[a-z0-9-]+)+$"
@@ -91,7 +87,6 @@
     }
   },
   "required": [
-    "project_id",
     "account_domain",
     "first_name",
     "last_name",

package/kit/schemas/lead.schema.json

@@ -2,10 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "project_id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9-]*$"
-    },
     "campaign_id": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$"
@@ -114,7 +110,6 @@
     }
   },
   "required": [
-    "project_id",
     "campaign_id",
     "run_id",
     "email",

package/kit/schemas/signal.schema.json

@@ -2,10 +2,6 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "project_id": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9-]*$"
-    },
     "signal_key": {
       "type": "string",
       "pattern": "^[a-z0-9][a-z0-9-]*$"
@@ -53,7 +49,6 @@
     }
   },
   "required": [
-    "project_id",
     "signal_key",
     "account_domain",
     "contact_linkedin_url",

package/kit/skills/02-tam/SKILL.md

@@ -22,8 +22,9 @@ Know how big the market is, and whether the ICP filters are right, before spendi
 4. Trigger the job: `npx gtm job tam <campaign>`. It validates, sends segment filters and exclusions
    from `icp.yaml` to the workers, which page accounts through the adapter, upsert them into
    `accounts` (re-runs update, never duplicate) and print counts per segment plus a run-log row.
-   **You do not page through accounts yourself.** If it says there is no Hatchet connection or keeps
-   waiting for a worker, stop and tell the human (AGENTS.md section 4).
+   **You do not page through accounts yourself.** If it says there is no Hatchet connection, run
+   `npx gtm stack up` once (needs Docker). If that fails, or the job keeps waiting for a worker
+   (`npx gtm stack status`), stop and tell the human (AGENTS.md section 4).
 5. Funnel counts per segment (printed by the job):
    - **TAM**: accounts matching filters.
    - **Reachable**: accounts where at least one target persona can be found (from the job's
@@ -36,7 +37,7 @@ Know how big the market is, and whether the ICP filters are right, before spendi
 8. Write `tam/<tam_id>.md` from `.gtm/templates/outputs/tam-summary.md` and the run log.
 
 ## Outputs
-- Rows in `accounts` (Postgres), tagged `project_id`, `tam_id`, `run_id`.
+- Rows in `accounts` (this project's Postgres), tagged `tam_id`, `segment_id`, `run_id`.
 - `tam/<tam_id>.md` with funnel table and sanity check. Run log.
 
 ## Checklist

package/kit/stack/docker-compose.yml

@@ -0,0 +1,66 @@
+# One project's stack: Postgres (this project's data + Hatchet's state), hatchet-lite (job engine) and
+# the gtm worker at the core version this project repo pins. Driven by `npx gtm stack up|down|status`,
+# which sets the compose project name (gtm-<project_id>), the ports and the worker image.
+# Data stays in this project's Docker volumes; nothing here is written into the repo.
+services:
+  postgres:
+    image: postgres:16.10
+    command: postgres -c max_connections=200
+    environment:
+      POSTGRES_USER: gtm
+      POSTGRES_PASSWORD: gtm
+      POSTGRES_DB: gtm
+    # Local only: reachable from this machine (QA samples in a DB console), not from the network.
+    ports: ["127.0.0.1:${GTM_PG_PORT:-5432}:5432"]
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./init:/docker-entrypoint-initdb.d:ro
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U gtm -d gtm"]
+      interval: 2s
+      timeout: 5s
+      retries: 30
+
+  hatchet-lite:
+    image: ghcr.io/hatchet-dev/hatchet/hatchet-lite:v0.110.5
+    depends_on:
+      postgres:
+        condition: service_healthy
+    ports:
+      - "127.0.0.1:${GTM_HATCHET_UI_PORT:-8888}:8888"
+      - "127.0.0.1:${GTM_HATCHET_GRPC_PORT:-7077}:7077"
+    environment:
+      DATABASE_URL: postgresql://gtm:gtm@postgres:5432/hatchet?sslmode=disable
+      SERVER_AUTH_COOKIE_DOMAIN: localhost
+      SERVER_AUTH_COOKIE_INSECURE: "t"
+      SERVER_GRPC_BIND_ADDRESS: 0.0.0.0
+      SERVER_GRPC_INSECURE: "t"
+      SERVER_GRPC_BROADCAST_ADDRESS: localhost:${GTM_HATCHET_GRPC_PORT:-7077}
+      SERVER_GRPC_PORT: "7077"
+      SERVER_URL: http://localhost:${GTM_HATCHET_UI_PORT:-8888}
+      SERVER_AUTH_SET_EMAIL_VERIFIED: "t"
+      SERVER_INTERNAL_CLIENT_INTERNAL_GRPC_BROADCAST_ADDRESS: localhost:7077
+    volumes:
+      - hatchet_config:/config
+
+  worker:
+    image: ${GTM_WORKER_IMAGE:-ghcr.io/veleads/gtm-worker:latest}
+    depends_on:
+      postgres:
+        condition: service_healthy
+      hatchet-lite:
+        condition: service_started
+    restart: unless-stopped
+    environment:
+      DATABASE_URL: postgresql://gtm:gtm@postgres:5432/gtm
+      HATCHET_CLIENT_TOKEN: ${HATCHET_CLIENT_TOKEN:-}
+      HATCHET_CLIENT_HOST_PORT: hatchet-lite:7077
+      HATCHET_CLIENT_TLS_STRATEGY: none
+    # Provider API keys: ~/.gtm/stacks/<project_id>.secrets.env, outside the repo. Optional.
+    env_file:
+      - path: ${GTM_SECRETS_FILE:-/dev/null}
+        required: false
+
+volumes:
+  pgdata:
+  hatchet_config:

package/kit/stack/init/01-hatchet-db.sql

@@ -0,0 +1,2 @@
+-- hatchet-lite keeps its own state in a separate database on the same Postgres instance.
+CREATE DATABASE hatchet;

package/kit/templates/repo/README.md

@@ -10,6 +10,7 @@ npm install          # or: pnpm install / yarn install
 cp .env.example .env
 npx gtm status
 npx gtm validate
+npx gtm stack up     # this project's own stack (needs Docker); jobs run on it
 ```
 
 ## What lives where

package/kit/templates/repo/env.example

@@ -1,5 +1,5 @@
-# Copy to .env (never commit). Provider API keys do NOT belong here: they live on the central worker.
+# Copy to .env (never commit). Provider API keys do NOT belong here: they go to this project's worker
+# (local stack: ~/.gtm/stacks/<project_id>.secrets.env). `npx gtm stack up` writes the connection
+# settings to ~/.gtm/stacks/<project_id>.env; set HATCHET_CLIENT_TOKEN here only for a hosted stack.
 GTM_USER=jdoe
-# Phase 2: trigger jobs on the shared Hatchet, read-only DB access for QA samples
 HATCHET_CLIENT_TOKEN=
-DATABASE_URL_READONLY=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veleads/gtm",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "gtm-brain core: process kit (AGENTS.md, skills, templates, schemas) and the gtm CLI for client repos",
   "keywords": [
     "gtm",
@@ -39,8 +39,8 @@
   },
   "devDependencies": {
     "tsup": "^8.5.0",
-    "@gtm/schemas": "0.0.0",
-    "@gtm/core": "0.0.0"
+    "@gtm/core": "0.0.0",
+    "@gtm/schemas": "0.0.0"
   },
   "homepage": "https://github.com/Veleads/gtm-core#readme",
   "bugs": {