@veleads/gtm 0.2.0 → 0.3.0

package/dist/cli.js

@@ -40,28 +40,32 @@ var Approval = z.object({
 );
 var FieldSources = z.record(z.string(), z.string().min(1));
 
-// ../schemas/src/client.ts
+// ../schemas/src/project.ts
 import { z as z2 } from "zod";
 
 // ../schemas/src/versions.ts
 var FILE_VERSIONS = {
-  client: 1,
-  icp: 1,
-  signals: 1,
-  "campaign-config": 1
+  project: 2,
+  icp: 2,
+  signals: 2,
+  "campaign-config": 2
 };
+var FILE_RENAMES = [
+  { from: "client.yaml", to: "project.yaml", since: "0.3.0" },
+  { from: "CLIENT.md", to: "PROJECT.md", since: "0.3.0" }
+];
 
-// ../schemas/src/client.ts
-var ClientFile = z2.object({
-  version: z2.literal(FILE_VERSIONS.client),
-  client_id: Slug,
+// ../schemas/src/project.ts
+var ProjectFile = z2.object({
+  version: z2.literal(FILE_VERSIONS.project),
+  project_id: Slug,
   name: z2.string().min(1),
-  status: z2.enum(["onboarding", "active", "paused", "churned"]),
+  status: z2.enum(["onboarding", "active", "paused", "closed"]),
   started_at: IsoDate,
   owners: z2.object({
     gtm_engineer: z2.string().min(1),
     sdrs: z2.array(z2.string().min(1)),
-    client_approver: z2.string().min(1).describe("Client-side person who signs off ICP and copy")
+    approver: z2.string().min(1).describe("Person who signs off ICP and copy for this project")
   }),
   regions: z2.array(z2.string().min(2)).min(1).describe("Target regions, e.g. EU, UK, US"),
   features: z2.record(z2.string(), z2.boolean()).default({}).describe("Opt-in core features, see FEATURES")
@@ -94,7 +98,7 @@ var IcpPersona = z3.object({
 });
 var IcpFile = z3.object({
   version: z3.literal(FILE_VERSIONS.icp),
-  client_id: Slug,
+  project_id: Slug,
   approval: Approval,
   segments: z3.array(IcpSegment).min(1),
   personas: z3.array(IcpPersona).min(1),
@@ -124,7 +128,7 @@ var SignalDefinition = z4.object({
 });
 var SignalsFile = z4.object({
   version: z4.literal(FILE_VERSIONS.signals),
-  client_id: Slug,
+  project_id: Slug,
   signals: z4.array(SignalDefinition).min(1)
 }).superRefine((f, ctx) => {
   const keys = f.signals.map((s) => s.key);
@@ -185,7 +189,7 @@ var Compliance = z5.object({
 });
 var CampaignConfig = z5.object({
   version: z5.literal(FILE_VERSIONS["campaign-config"]),
-  client_id: Slug,
+  project_id: Slug,
   campaign_id: Slug,
   owner: z5.string().min(1),
   stage: Stage.describe("The stage currently being worked on"),
@@ -208,7 +212,7 @@ var CampaignConfig = z5.object({
 // ../schemas/src/account.ts
 import { z as z6 } from "zod";
 var Account = z6.object({
-  client_id: Slug,
+  project_id: Slug,
   tam_id: Slug,
   domain: Domain,
   name: z6.string().min(1),
@@ -225,7 +229,7 @@ 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({
-  client_id: Slug,
+  project_id: Slug,
   account_domain: Domain,
   first_name: z7.string().min(1),
   last_name: z7.string().min(1),
@@ -242,7 +246,7 @@ var Contact = z7.object({
 // ../schemas/src/signal.ts
 import { z as z8 } from "zod";
 var SignalEvent = z8.object({
-  client_id: Slug,
+  project_id: Slug,
   signal_key: Slug,
   account_domain: Domain,
   contact_linkedin_url: z8.string().url().nullable(),
@@ -255,7 +259,7 @@ var SignalEvent = z8.object({
 // ../schemas/src/lead.ts
 import { z as z9 } from "zod";
 var Lead = z9.object({
-  client_id: Slug,
+  project_id: Slug,
   campaign_id: Slug,
   run_id: z9.uuid(),
   email: z9.email(),
@@ -282,7 +286,27 @@ var FEATURES = {
 };
 
 // ../schemas/src/migrations.ts
-var MIGRATIONS = [];
+import { isMap, isScalar } from "yaml";
+function renameKey(doc, path, from, to) {
+  const node = path.length ? doc.getIn(path, true) : doc.contents;
+  if (!isMap(node)) return;
+  const pair = node.items.find((p) => (isScalar(p.key) ? p.key.value : p.key) === from);
+  if (!pair) return;
+  if (isScalar(pair.key)) pair.key.value = to;
+  else pair.key = to;
+}
+var renameClientId = (doc) => renameKey(doc, [], "client_id", "project_id");
+var MIGRATIONS = [
+  // 0.3.0: "clients" became "projects" (one private repo per project).
+  { kind: "project", from: 1, description: "client_id \u2192 project_id, owners.client_approver \u2192 owners.approver, status churned \u2192 closed", up(doc) {
+    renameClientId(doc);
+    renameKey(doc, ["owners"], "client_approver", "approver");
+    if (doc.get("status") === "churned") doc.set("status", "closed");
+  } },
+  { kind: "icp", from: 1, description: "client_id \u2192 project_id", up: renameClientId },
+  { kind: "signals", from: 1, description: "client_id \u2192 project_id", up: renameClientId },
+  { kind: "campaign-config", from: 1, description: "client_id \u2192 project_id", up: renameClientId }
+];
 function migrateDocument(kind, doc, migrations = MIGRATIONS, target = FILE_VERSIONS[kind]) {
   const raw = doc.get("version");
   const from = typeof raw === "number" ? raw : Number(raw);
@@ -321,11 +345,11 @@ function copyContentHash(markdown) {
 
 // src/commands/approve.ts
 var USAGE = `Usage:
-  gtm approve icp --by "<Name (side)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]
-  gtm approve copy <campaign> --by "<Name (side)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]`;
+  gtm approve icp --by "<Name (role)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]
+  gtm approve copy <campaign> --by "<Name (role)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]`;
 function load(file) {
   if (!existsSync(file)) {
-    console.error(`${file} not found: run this from the root of a client repo`);
+    console.error(`${file} not found: run this from the root of a project repo`);
     return null;
   }
   const doc = parseDocument(readFileSync(file, "utf8"));
@@ -361,7 +385,7 @@ function runApprove(root2, args2, opts) {
   }
   const by = opts.by?.trim();
   if (!by) {
-    console.error('--by is required: the human who approved, e.g. --by "Maria Chen (client)"');
+    console.error('--by is required: the human who approved, e.g. --by "Maria Chen (VP Marketing)"');
     return false;
   }
   const date = opts.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
@@ -502,7 +526,7 @@ import { dirname as dirname3, join as join5 } from "path";
 var SHIPPED_DIRS = ["skills", "templates", "providers", "schemas"];
 function agentsMd() {
   const header = `<!-- GENERATED by \`gtm sync\` from ${PACKAGE_NAME} v${GTM_VERSION}. Do not edit: it is overwritten on upgrade.
-     Client-specific rules go in CLIENT.md. Process changes go to the Veleads/gtm-core repo. -->
+     Project-specific rules go in PROJECT.md. Process changes go to the Veleads/gtm-core repo. -->
 
 `;
   return header + readFileSync4(join5(KIT_DIR, "AGENTS.md"), "utf8").replaceAll("{{GTM_VERSION}}", GTM_VERSION);
@@ -545,7 +569,7 @@ function runSync(root2, opts = {}) {
       console.log(`in sync with ${PACKAGE_NAME} v${GTM_VERSION}`);
       return true;
     }
-    console.log(`out of sync with ${PACKAGE_NAME} v${GTM_VERSION} (run \`pnpm gtm sync\`; never edit .gtm/ or AGENTS.md by hand):`);
+    console.log(`out of sync with ${PACKAGE_NAME} v${GTM_VERSION} (run \`npx gtm sync\`; never edit .gtm/ or AGENTS.md by hand):`);
     for (const d of diffs) console.log(`  ${d}`);
     return false;
   }
@@ -562,18 +586,18 @@ function runSync(root2, opts = {}) {
 // src/commands/init.ts
 function runInit(slug, opts) {
   if (!slug || !Slug.safeParse(slug).success || !opts.name) {
-    console.error('Usage: gtm init <client-slug> --name "<Client Name>" [--dir <path>]   (slug: lowercase, digits, hyphens)');
+    console.error('Usage: gtm init <project-slug> --name "<Project Name>" [--dir <path>]   (slug: lowercase, digits, hyphens)');
     return false;
   }
-  const root2 = resolve(opts.cwd, opts.dir ?? `gtm-client-${slug}`);
+  const root2 = resolve(opts.cwd, opts.dir ?? `gtm-project-${slug}`);
   if (existsSync4(root2) && readdirSync2(root2).length > 0) {
     console.error(`${root2} exists and is not empty`);
     return false;
   }
-  const vars = { CLIENT_ID: slug, CLIENT_NAME: opts.name, TODAY: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10), GTM_VERSION };
+  const vars = { PROJECT_ID: slug, PROJECT_NAME: opts.name, TODAY: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10), GTM_VERSION };
   const tpl = join6(KIT_DIR, "templates");
   copyTemplate(join6(tpl, "repo"), root2, vars);
-  copyTemplate(join6(tpl, "client"), root2, vars, { rename: (rel) => rel === "client.yaml" ? rel : join6("context", rel) });
+  copyTemplate(join6(tpl, "project"), root2, vars, { rename: (rel) => rel === "project.yaml" ? rel : join6("context", rel) });
   for (const d of ["campaigns", "tam"]) {
     mkdirSync3(join6(root2, d), { recursive: true });
     writeFileSync4(join6(root2, d, ".gitkeep"), "");
@@ -584,9 +608,9 @@ function runInit(slug, opts) {
 Created ${root2} (core v${GTM_VERSION})${git.status === 0 ? " with git initialised" : ""}.
 
 Next:
-  1. Create a PRIVATE GitHub repo for it (e.g. <your-org>/gtm-client-${slug}) and push this folder.
-     Client repos hold client context: never make them public.
-  2. pnpm install && pnpm gtm validate     (TODO warnings remain until intake is done)
+  1. Create a PRIVATE GitHub repo for it (e.g. <your-org>/gtm-project-${slug}) and push this folder.
+     Project repos hold project context: never make them public.
+  2. npm install && npx gtm validate     (or pnpm/yarn; TODO warnings remain until intake is done)
   3. Open the repo in Claude Code or Codex and start with stage 00-intake.`);
   return true;
 }
@@ -602,22 +626,39 @@ Per AGENTS.md this is a mandatory stop: do not improvise the job with ad-hoc scr
 }
 
 // src/commands/migrate.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5, renameSync, writeFileSync as writeFileSync5 } from "fs";
 import { join as join7, relative as relative2 } from "path";
 import { parseDocument as parseDocument2 } from "yaml";
-function clientYamlFiles(root2) {
+function projectYamlFiles(root2) {
   const files = [
-    { kind: "client", file: join7(root2, "client.yaml") },
+    { kind: "project", file: join7(root2, "project.yaml") },
     { kind: "icp", file: join7(root2, "context", "icp.yaml") },
     { kind: "signals", file: join7(root2, "context", "signals.yaml") },
     ...subdirs(join7(root2, "campaigns")).map((c) => ({ kind: "campaign-config", file: join7(root2, "campaigns", c, "config.yaml") }))
   ];
   return files.filter((f) => existsSync5(f.file));
 }
+function pendingRenames(root2) {
+  return FILE_RENAMES.filter((r) => existsSync5(join7(root2, r.from)) && !existsSync5(join7(root2, r.to)));
+}
 function runMigrate(root2, opts = {}) {
   let ok = true;
   let changed = 0;
-  for (const { kind, file } of clientYamlFiles(root2)) {
+  for (const { from, to } of pendingRenames(root2)) {
+    changed++;
+    console.log(`  ${opts.dryRun ? "would rename" : "renamed"} ${from} \u2192 ${to}`);
+    if (opts.dryRun) continue;
+    renameSync(join7(root2, from), join7(root2, to));
+    if (to.endsWith(".md")) {
+      const p = join7(root2, to);
+      writeFileSync5(p, readFileSync5(p, "utf8").replace(new RegExp(`^# ${from.replace(".", "\\.")}`, "m"), `# ${to}`));
+    }
+  }
+  if (opts.dryRun && changed) {
+    console.log("(dry run: YAML migrations are listed after the renames are applied)");
+    return ok;
+  }
+  for (const { kind, file } of projectYamlFiles(root2)) {
     const rel = relative2(root2, file);
     const doc = parseDocument2(readFileSync5(file, "utf8"));
     if (doc.errors.length) {
@@ -634,7 +675,7 @@ function runMigrate(root2, opts = {}) {
       for (const a of res.applied) console.log(`  ${opts.dryRun ? "would apply" : "applied"} ${rel}: ${a}`);
       if (pinned) {
         doc.setIn(["approval", "content_hash"], icpContentHash(doc.toJS()));
-        console.log(`  re-pinned ICP approval hash in ${rel} (core migration, content approved by the client)`);
+        console.log(`  re-pinned ICP approval hash in ${rel} (core migration, content approved by the project approver)`);
       }
       if (!opts.dryRun) writeFileSync5(file, doc.toString({ flowCollectionPadding: false, lineWidth: 0 }));
     } catch (e) {
@@ -655,9 +696,9 @@ function runNewCampaign(root2, campaign) {
     console.error("Usage: gtm new-campaign <campaign-slug>");
     return false;
   }
-  const clientFile = join8(root2, "client.yaml");
-  if (!existsSync6(clientFile)) {
-    console.error("client.yaml not found: run this from the root of a client repo");
+  const projectFile = join8(root2, "project.yaml");
+  if (!existsSync6(projectFile)) {
+    console.error("project.yaml not found: run this from the root of a project repo");
     return false;
   }
   const dest = join8(root2, "campaigns", campaign);
@@ -665,8 +706,8 @@ function runNewCampaign(root2, campaign) {
     console.error(`campaigns/${campaign} already exists`);
     return false;
   }
-  const clientId = parse(readFileSync6(clientFile, "utf8"))?.client_id ?? "TODO";
-  copyTemplate(join8(KIT_DIR, "templates", "campaign"), dest, { CLIENT_ID: clientId, CAMPAIGN_ID: campaign, OWNER: process.env.GTM_USER ?? "TODO" });
+  const projectId = parse(readFileSync6(projectFile, "utf8"))?.project_id ?? "TODO";
+  copyTemplate(join8(KIT_DIR, "templates", "campaign"), dest, { PROJECT_ID: projectId, CAMPAIGN_ID: campaign, OWNER: process.env.GTM_USER ?? "TODO" });
   mkdirSync4(join8(dest, "runs"), { recursive: true });
   writeFileSync6(join8(dest, "runs", ".gitkeep"), "");
   console.log(`Created campaigns/${campaign}. Branch: git switch -c campaign/${campaign}`);
@@ -688,9 +729,9 @@ function campaignStages(root2) {
   return subdirs(join9(root2, "campaigns")).map((id) => ({ id, stage: readYaml(join9(root2, "campaigns", id, "config.yaml"))?.stage ?? "?" }));
 }
 function runStatus(root2) {
-  const client = readYaml(join9(root2, "client.yaml"));
+  const project = readYaml(join9(root2, "project.yaml"));
   const icp = readYaml(join9(root2, "context", "icp.yaml"));
-  console.log(`${client?.name ?? "?"} (${client?.client_id ?? "?"}) \xB7 status ${client?.status ?? "?"} \xB7 core v${GTM_VERSION}`);
+  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(join9(root2, "campaigns")).map((id) => {
@@ -700,7 +741,7 @@ function runStatus(root2) {
     return [id, cfg.stage ?? "?", cfg.gates?.copy?.status ?? "?", cfg.gates?.launch?.status ?? "?", cfg.owner ?? "?", last];
   });
   if (!rows.length) {
-    console.log("no campaigns yet: pnpm gtm new-campaign <campaign-slug>");
+    console.log("no campaigns yet: npx gtm new-campaign <campaign-slug>");
     return true;
   }
   const header = ["campaign", "stage", "copy gate", "launch gate", "owner", "latest run log"];
@@ -766,8 +807,8 @@ function loadVersioned(r, file, kind, schema) {
   }
   const expected = FILE_VERSIONS[kind];
   if (raw?.version !== expected) {
-    if (typeof raw?.version === "number" && raw.version < expected) r.err(file, `is version ${raw.version}, core v${GTM_VERSION} expects ${expected}: run \`pnpm gtm migrate\``);
-    else if (typeof raw?.version === "number") r.err(file, `is version ${raw.version}, newer than core v${GTM_VERSION} (${expected}): run \`pnpm gtm upgrade\``);
+    if (typeof raw?.version === "number" && raw.version < expected) r.err(file, `is version ${raw.version}, core v${GTM_VERSION} expects ${expected}: run \`npx gtm migrate\``);
+    else if (typeof raw?.version === "number") r.err(file, `is version ${raw.version}, newer than core v${GTM_VERSION} (${expected}): run \`npx gtm upgrade\``);
     else r.err(file, `missing "version: ${expected}"`);
     return null;
   }
@@ -784,14 +825,14 @@ function checkCoreSync(r, root2) {
   if (!/^\d+\.\d+\.\d+/.test(pinned)) r.err(join10(root2, "package.json"), `${PACKAGE_NAME} must be pinned exactly (got "${pinned}")`);
   const versionFile = join10(root2, ".gtm", "VERSION");
   const synced = existsSync8(versionFile) ? readFileSync8(versionFile, "utf8").trim() : null;
-  if (synced !== GTM_VERSION) r.err(versionFile, `is ${synced ?? "missing"}, installed core is ${GTM_VERSION}: run \`pnpm gtm sync\``);
-  if (!existsSync8(join10(root2, "AGENTS.md"))) r.err(join10(root2, "AGENTS.md"), "missing: run `pnpm gtm sync`");
+  if (synced !== GTM_VERSION) r.err(versionFile, `is ${synced ?? "missing"}, installed core is ${GTM_VERSION}: run \`npx gtm sync\``);
+  if (!existsSync8(join10(root2, "AGENTS.md"))) r.err(join10(root2, "AGENTS.md"), "missing: run `npx gtm sync`");
 }
 function checkNoLeadData(r, root2) {
   for (const rel of walk(root2, SKIP_DIRS)) {
     const file = join10(root2, rel);
     if (DATA_FILES.test(rel)) {
-      r.err(file, "data files are not allowed in a client repo (lead data belongs in Postgres)");
+      r.err(file, "data files are not allowed in a project repo (lead data belongs in Postgres)");
       continue;
     }
     if (!/\.(md|ya?ml|txt)$/i.test(rel) || rel === "pnpm-lock.yaml") continue;
@@ -811,14 +852,14 @@ function checkPinnedApproval(r, contentFile, approval, current, what, approveCmd
   r.err(contentFile, `${what} changed after approval (approved ${pinned}, now ${current}). Re-present it to the approver and record it with \`${approveCmd} --by "<name>"\`, or revert the change`);
   return false;
 }
-function validateCampaign(r, root2, clientId, campaign, icp, signals, icpApproved) {
+function validateCampaign(r, root2, projectId, campaign, icp, signals, icpApproved) {
   const dir = join10(root2, "campaigns", campaign);
   console.log(`campaign ${campaign}`);
   for (const f of REQUIRED_CAMPAIGN) if (!existsSync8(join10(dir, f))) r.err(join10(dir, f), "missing");
   const cfgFile = join10(dir, "config.yaml");
   const cfg = loadVersioned(r, cfgFile, "campaign-config", CampaignConfig);
   if (cfg) {
-    if (cfg.client_id !== clientId) r.err(cfgFile, `client_id "${cfg.client_id}" does not match client.yaml "${clientId}"`);
+    if (cfg.project_id !== projectId) r.err(cfgFile, `project_id "${cfg.project_id}" does not match project.yaml "${projectId}"`);
     if (cfg.campaign_id !== campaign) r.err(cfgFile, `campaign_id "${cfg.campaign_id}" does not match folder "${campaign}"`);
     if (icp) {
       const segs = new Set(icp.segments.map((s) => s.id));
@@ -841,7 +882,7 @@ function validateCampaign(r, root2, clientId, campaign, icp, signals, icpApprove
       r.err(cfgFile, `stage is "${cfg.stage}" but the ICP gate (context/icp.yaml approval) is not approved, or the ICP changed since approval`);
     }
     const copyFile = join10(dir, "copy.md");
-    const copyApproved = existsSync8(copyFile) ? checkPinnedApproval(r, copyFile, cfg.gates.copy, copyContentHash(readFileSync8(copyFile, "utf8")), "copy", `pnpm gtm approve copy ${campaign}`) : false;
+    const copyApproved = existsSync8(copyFile) ? checkPinnedApproval(r, copyFile, cfg.gates.copy, copyContentHash(readFileSync8(copyFile, "utf8")), "copy", `npx gtm approve copy ${campaign}`) : false;
     if (stageIndex(cfg.stage) > stageIndex("copy") && !copyApproved) {
       r.err(cfgFile, `stage is "${cfg.stage}" but gates.copy is not approved, or copy.md changed since approval`);
     }
@@ -866,22 +907,23 @@ function runValidate(root2, onlyCampaign) {
   const r = new Report(root2);
   console.log(`validating ${root2} against core v${GTM_VERSION}`);
   checkCoreSync(r, root2);
-  const meta = loadVersioned(r, join10(root2, "client.yaml"), "client", ClientFile);
-  const clientId = meta?.client_id ?? "";
+  for (const { from, to } of pendingRenames(root2)) r.err(join10(root2, from), `renamed to ${to} in core 0.3.0: run \`npx gtm migrate\``);
+  const meta = loadVersioned(r, join10(root2, "project.yaml"), "project", ProjectFile);
+  const projectId = meta?.project_id ?? "";
   if (meta) {
     for (const key of Object.keys(meta.features)) {
-      if (!FEATURES[key]) r.err(join10(root2, "client.yaml"), `unknown feature "${key}" (known: ${Object.keys(FEATURES).join(", ") || "none"})`);
+      if (!FEATURES[key]) r.err(join10(root2, "project.yaml"), `unknown feature "${key}" (known: ${Object.keys(FEATURES).join(", ") || "none"})`);
     }
   }
-  if (!existsSync8(join10(root2, "CLIENT.md"))) r.warn(join10(root2, "CLIENT.md"), "missing (client-specific rules for agents)");
+  if (!existsSync8(join10(root2, "PROJECT.md"))) r.warn(join10(root2, "PROJECT.md"), "missing (project-specific rules for agents)");
   for (const f of REQUIRED_CONTEXT) if (!existsSync8(join10(root2, "context", f))) r.err(join10(root2, "context", f), "missing");
   const icpFile = join10(root2, "context", "icp.yaml");
   const sigFile = join10(root2, "context", "signals.yaml");
   const icp = existsSync8(icpFile) ? loadVersioned(r, icpFile, "icp", IcpFile) : null;
   const signals = existsSync8(sigFile) ? loadVersioned(r, sigFile, "signals", SignalsFile) : null;
-  if (meta && icp && icp.client_id !== clientId) r.err(icpFile, `client_id "${icp.client_id}" does not match client.yaml "${clientId}"`);
-  if (meta && signals && signals.client_id !== clientId) r.err(sigFile, `client_id "${signals.client_id}" does not match client.yaml "${clientId}"`);
-  const icpApproved = icp ? checkPinnedApproval(r, icpFile, icp.approval, icpContentHash(parse3(readFileSync8(icpFile, "utf8"))), "ICP", "pnpm gtm approve icp") : false;
+  if (meta && icp && icp.project_id !== projectId) r.err(icpFile, `project_id "${icp.project_id}" does not match project.yaml "${projectId}"`);
+  if (meta && signals && signals.project_id !== projectId) r.err(sigFile, `project_id "${signals.project_id}" does not match project.yaml "${projectId}"`);
+  const icpApproved = icp ? checkPinnedApproval(r, icpFile, icp.approval, icpContentHash(parse3(readFileSync8(icpFile, "utf8"))), "ICP", "npx gtm approve icp") : false;
   checkNoLeadData(r, root2);
   const campaigns = onlyCampaign ? [onlyCampaign] : subdirs(join10(root2, "campaigns"));
   for (const c of campaigns) {
@@ -889,24 +931,31 @@ function runValidate(root2, onlyCampaign) {
       r.err(join10(root2, "campaigns", c), "campaign folder not found");
       continue;
     }
-    validateCampaign(r, root2, clientId, c, icp, signals, icpApproved);
+    validateCampaign(r, root2, projectId, c, icp, signals, icpApproved);
   }
   r.summary();
   return r.errors === 0;
 }
 
 // src/commands/upgrade.ts
-function pm(root2, args2) {
-  const onPath = spawnSync2("pnpm", ["--version"], { stdio: "ignore" }).status === 0;
-  const pinned = JSON.parse(readFileSync9(join11(root2, "package.json"), "utf8")).packageManager ?? "pnpm@10";
-  const [cmd, pre] = onPath ? ["pnpm", []] : ["npx", ["-y", pinned]];
-  return spawnSync2(cmd, [...pre, ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
+function detectPackageManager(root2) {
+  if (existsSync9(join11(root2, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync9(join11(root2, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+function installExact(root2, pm, spec) {
+  const onPath = (bin) => spawnSync2(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 spawnSync2(cmd, args2, { cwd: root2, stdio: "inherit" }).status ?? 1;
+}
+function gtm(root2, args2) {
+  return spawnSync2("npx", ["gtm", ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
 }
 var FROZEN_STAGES = ["qa", "launch"];
 function runUpgrade(root2, opts) {
   const before = pinnedVersion(root2);
   if (!before) {
-    console.error(`package.json does not depend on ${PACKAGE_NAME}: is this a client repo?`);
+    console.error(`package.json does not depend on ${PACKAGE_NAME}: is this a project repo?`);
     return false;
   }
   const frozen = campaignStages(root2).filter((c) => FROZEN_STAGES.includes(c.stage));
@@ -921,11 +970,12 @@ function runUpgrade(root2, opts) {
     return false;
   }
   const target = opts.version ?? "latest";
-  console.log(`Upgrading ${PACKAGE_NAME} ${before} \u2192 ${target}`);
-  if (pm(root2, ["add", "-D", "--save-exact", `${PACKAGE_NAME}@${target}`]) !== 0) return false;
-  if (pm(root2, ["exec", "gtm", "sync"]) !== 0) return false;
-  if (pm(root2, ["exec", "gtm", "migrate"]) !== 0) return false;
-  const valid = pm(root2, ["exec", "gtm", "validate"]) === 0;
+  const pm = detectPackageManager(root2);
+  console.log(`Upgrading ${PACKAGE_NAME} ${before} \u2192 ${target} (with ${pm})`);
+  if (installExact(root2, pm, `${PACKAGE_NAME}@${target}`) !== 0) return false;
+  if (gtm(root2, ["sync"]) !== 0) return false;
+  if (gtm(root2, ["migrate"]) !== 0) return false;
+  const valid = gtm(root2, ["validate"]) === 0;
   const after = pinnedVersion(root2) ?? target;
   const changelog = join11(root2, "node_modules", ...PACKAGE_NAME.split("/"), "CHANGELOG.md");
   if (existsSync9(changelog)) {
@@ -939,21 +989,134 @@ ${notes || "(no changelog entries)"}
   return valid;
 }
 
+// src/help.ts
+var COMMANDS = {
+  init: {
+    usage: 'gtm init <project-slug> --name "<Project Name>" [--dir <path>]',
+    summary: "scaffold a new project repo",
+    details: [
+      "Creates a complete project repo: project.yaml, context/ templates, campaigns/, tam/, PROJECT.md,",
+      "CI workflows, .gtm/ (core kit) and AGENTS.md, pinned to this CLI's version, then runs git init.",
+      "Push the result to a PRIVATE repo: it will hold project context."
+    ],
+    writes: "A new folder (default ./gtm-project-<slug>). Refuses if it exists and is not empty.",
+    examples: ['npx @veleads/gtm init acme --name "Acme Corp"', 'npx @veleads/gtm init acme --name "Acme Corp" --dir ./projects/acme']
+  },
+  "new-campaign": {
+    usage: "gtm new-campaign <campaign-slug>",
+    summary: "scaffold campaigns/<slug>/",
+    details: ["Copies the campaign template (brief.md, config.yaml, copy.md, runs/). Owner comes from GTM_USER."],
+    writes: "campaigns/<slug>/ (refuses if it exists).",
+    examples: ["git switch -c campaign/q1-uk-cfo && npx gtm new-campaign q1-uk-cfo"]
+  },
+  validate: {
+    usage: "gtm validate [campaign]",
+    summary: "check repo against schemas, gates, data rules",
+    details: [
+      "Checks project.yaml, context/ and campaigns against the schemas; segment/persona/signal references;",
+      "gate order (no stage past an unapproved or changed ICP/copy approval); required files; run-log names;",
+      "no lead data (blocks data files, warns on email addresses); .gtm/ matches the installed core.",
+      "Exit code 1 if there is any error; warnings never fail."
+    ],
+    writes: "Nothing (read-only).",
+    examples: ["npx gtm validate", "npx gtm validate q1-uk-cfo"]
+  },
+  status: {
+    usage: "gtm status",
+    summary: "campaigns, stages, gates",
+    details: ["One screen: project, core version, ICP gate, and per campaign the stage, copy/launch gates, owner and latest run log."],
+    writes: "Nothing (read-only).",
+    examples: ["npx gtm status"]
+  },
+  approve: {
+    usage: 'gtm approve icp --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]\ngtm approve copy <campaign> --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]',
+    summary: "record a sign-off and pin a hash of the approved content",
+    details: [
+      "Run ONLY after the named human explicitly approved in this session (AGENTS.md section 4).",
+      "Pins a content hash: if context/icp.yaml or the campaign's copy.md changes afterwards,",
+      "`gtm validate` fails until it is re-approved. Refuses if the file would not validate.",
+      "The launch gate is recorded by hand in config.yaml (its content is the lead set)."
+    ],
+    writes: "context/icp.yaml \u2192 approval (icp), or campaigns/<campaign>/config.yaml \u2192 gates.copy (copy).",
+    examples: ['npx gtm approve icp --by "Maria Chen (VP Marketing)" --notes "Segments A+B, personas CFO+AP"', 'npx gtm approve copy q1-uk-cfo --by "Maria Chen (VP Marketing)"']
+  },
+  sync: {
+    usage: "gtm sync [--check]",
+    summary: "copy core kit into .gtm/ + AGENTS.md",
+    details: [
+      "Makes .gtm/ (skills, templates, schemas, provider docs) and AGENTS.md match the installed core.",
+      "--check only compares and exits 1 if they differ (CI uses this; never edit .gtm/ by hand)."
+    ],
+    writes: ".gtm/ (replaced entirely) and AGENTS.md; creates CLAUDE.md if missing. With --check: nothing.",
+    examples: ["npx gtm sync", "npx gtm sync --check"]
+  },
+  migrate: {
+    usage: "gtm migrate [--dry-run]",
+    summary: "upgrade YAML files to current schema versions",
+    details: ["Applies core schema migrations to project.yaml, context/*.yaml and campaigns/*/config.yaml, keeping comments."],
+    writes: "Those YAML files, only if a migration applies. With --dry-run: nothing.",
+    examples: ["npx gtm migrate --dry-run", "npx gtm migrate"]
+  },
+  upgrade: {
+    usage: "gtm upgrade [version] [--force]",
+    summary: "install newer core, sync, migrate, validate",
+    details: [
+      "Installs @veleads/gtm@<version|latest> pinned exactly, then sync, migrate and validate, and prints the changelog.",
+      "Refuses while a campaign is in qa or launch, or with uncommitted changes (--force overrides; ask a GTM engineer)."
+    ],
+    writes: "package.json, lockfile, node_modules, .gtm/, AGENTS.md and migrated YAML files.",
+    examples: ["npx gtm upgrade", "npx gtm upgrade 0.3.0"]
+  },
+  job: {
+    usage: "gtm job <name> <campaign>",
+    summary: "run a pipeline job (Phase 2)",
+    details: [
+      "Planned: tam, enrich, suppression:import, signals, qualify, qa, push, activate, results, status.",
+      "Not available yet: it exits 1. Per AGENTS.md this is a stop; do not improvise jobs with ad-hoc scripts."
+    ],
+    writes: "Nothing yet.",
+    examples: ["npx gtm job tam q1-uk-cfo"]
+  }
+};
+function generalHelp(version) {
+  const width = Math.max(...Object.keys(COMMANDS).map((c) => c.length));
+  const lines = Object.entries(COMMANDS).map(([name, c]) => `  ${name.padEnd(width)}  ${c.summary}`);
+  return `gtm v${version}: CLI for gtm-brain project repos (@veleads/gtm)
+
+Usage: gtm <command> [options]      (inside a project repo: npx gtm <command>)
+
+Commands:
+${lines.join("\n")}
+
+Run \`gtm <command> --help\` for usage, what it writes, and examples.
+
+Global options:
+  --root <dir>     repo root (default: current directory)
+  -h, --help       show help (with a command: that command's help; nothing is run)
+  -v, --version    print the version
+
+Exit codes: 0 success, 1 failure or validation errors.
+
+For coding agents: inside a project repo, read AGENTS.md first and follow it. Read-only commands
+(validate, status, sync --check, migrate --dry-run) are always safe to run.`;
+}
+function commandHelp(name) {
+  const c = COMMANDS[name];
+  if (!c) return null;
+  return `gtm ${name}: ${c.summary}
+
+Usage:
+${c.usage.split("\n").map((u) => `  ${u}`).join("\n")}
+
+${c.details.map((d) => `  ${d}`).join("\n")}
+
+Writes: ${c.writes}
+
+Examples:
+${c.examples.map((e) => `  ${e}`).join("\n")}`;
+}
+
 // src/cli.ts
-var HELP = `gtm v${GTM_VERSION}: gtm-brain core CLI (run inside a client repo)
-
-  gtm init <client-slug> --name "<Name>" [--dir <path>]   scaffold a new client repo
-  gtm new-campaign <campaign-slug>                        scaffold campaigns/<slug>/
-  gtm validate [campaign]                                 check repo against schemas, gates, data rules
-  gtm status                                              campaigns, stages, gates
-  gtm approve icp --by "<Name (side)>" [--notes ..] [--date YYYY-MM-DD]
-  gtm approve copy <campaign> --by "<Name (side)>" [..]   record a sign-off and pin a hash of the approved content
-  gtm sync [--check]                                      copy core kit into .gtm/ + AGENTS.md
-  gtm migrate [--dry-run]                                 upgrade YAML files to current schema versions
-  gtm upgrade [version] [--force]                         install newer core, sync, migrate, validate
-  gtm job <name> <campaign>                               run a pipeline job (Phase 2)
-
-Global: --root <dir>  repo root (default: current directory)`;
 var { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
@@ -973,11 +1136,27 @@ var { values, positionals } = parseArgs({
 var [command, ...args] = positionals;
 var cwd = process.cwd();
 var root = resolve2(cwd, values.root ?? ".");
+function help(name) {
+  if (!name) {
+    console.log(generalHelp(GTM_VERSION));
+    return true;
+  }
+  const text = commandHelp(name);
+  if (!text) {
+    console.error(`Unknown command "${name}"
+
+${generalHelp(GTM_VERSION)}`);
+    return false;
+  }
+  console.log(text);
+  return true;
+}
 function run() {
   if (values.version) {
     console.log(GTM_VERSION);
     return true;
   }
+  if (values.help) return help(command === "help" ? args[0] : command);
   switch (command) {
     case "init":
       return runInit(args[0], { name: values.name, dir: values.dir, cwd });
@@ -998,13 +1177,13 @@ function run() {
     case "job":
       return runJob(args[0]);
     case void 0:
+      return help(void 0);
     case "help":
-      console.log(HELP);
-      return true;
+      return help(args[0]);
     default:
       console.error(`Unknown command "${command}"
 
-${HELP}`);
+${generalHelp(GTM_VERSION)}`);
       return false;
   }
 }