@veleads/gtm 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to `@veleads/gtm`. Each entry is tagged: **no action**, **op
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-10-24
+- **no action** The npm package now has a README (what it is, quick start, commands, guidance for
+  coding agents).
+- **no action** `gtm <command> --help` and `gtm help <command>` print that command's usage, what it
+  writes, and examples, without running it. Previously `--help` after a command ran the command.
+
 ## [0.2.0] - 2026-10-24
 - **action** ICP approvals are now pinned to the approved content. New `gtm approve icp --by "<name>"`
   records the sign-off with a `content_hash`; `gtm validate` fails if `context/icp.yaml` changes after

package/README.md

@@ -0,0 +1,72 @@
+# @veleads/gtm
+
+CLI and process kit for **gtm-brain**: run outbound for many clients with one standard,
+agent-agnostic process. Each client gets its own **private** git repo; this package scaffolds it,
+keeps its playbooks in sync with the core, validates it, and upgrades it safely.
+
+Works with Claude Code, Codex, or any coding agent that can read files and run shell commands.
+Source: [Veleads/gtm-core](https://github.com/Veleads/gtm-core) · MIT
+
+## Quick start
+
+Requires Node.js 22+ and pnpm (`corepack enable`, or use `npx pnpm@10`).
+
+```bash
+npx @veleads/gtm init acme --name "Acme Corp"
+cd gtm-client-acme
+pnpm install
+pnpm gtm status
+pnpm gtm validate
+```
+
+Push the new folder to a **private** repository, then open it in your coding agent. The generated
+`AGENTS.md` tells the agent how to work in the repo, starting at stage `00-intake`.
+
+## What you get in a client repo
+
+| Path | What | Edit? |
+|---|---|---|
+| `AGENTS.md` | operator manual: session start, 9-stage routing, hard stops, data rules | no, generated by `gtm sync` |
+| `.gtm/` | stage playbooks (Agent Skills), templates, JSON schemas, provider docs | no, generated by `gtm sync` |
+| `CLIENT.md` | client-specific rules that add to the process | yes |
+| `client.yaml`, `context/` | owners, ICP (md + yaml), signals, personas, offer, proof, voice | yes |
+| `campaigns/<id>/` | brief, config, copy, QA report, run logs | yes |
+
+Stages: intake → ICP (**client sign-off**) → TAM → enrich → qualify → copy (**client sign-off**) →
+QA → launch (**go/no-go**) → results. ICP and copy approvals are pinned to the approved content:
+editing either afterwards makes `gtm validate` fail until it's re-approved.
+
+## Commands
+
+Run inside a client repo as `pnpm gtm <command>`. `gtm <command> --help` shows usage, **what the
+command writes**, and examples, without running it.
+
+| Command | What it does | Writes |
+|---|---|---|
+| `init <slug> --name "<Name>"` | scaffold a new client repo | new folder |
+| `new-campaign <slug>` | scaffold `campaigns/<slug>/` | that folder |
+| `validate [campaign]` | schemas, gates, cross-references, no lead data, core sync | nothing |
+| `status` | campaigns, stages, gates | nothing |
+| `approve icp --by "<name>"` | record ICP sign-off, pin its hash | `context/icp.yaml` |
+| `approve copy <campaign> --by "<name>"` | record copy sign-off, pin its hash | campaign `config.yaml` |
+| `sync [--check]` | copy the core kit into `.gtm/` + `AGENTS.md` | `.gtm/`, `AGENTS.md` (nothing with `--check`) |
+| `migrate [--dry-run]` | move YAML files to the current schema versions | YAML files |
+| `upgrade [version]` | install a newer core, sync, migrate, validate, show changelog | deps, `.gtm/`, YAML |
+| `job <name> <campaign>` | pipeline jobs (TAM, enrich, …) | planned, not available yet |
+
+Exit codes: `0` success, `1` failure or validation errors.
+
+## For coding agents
+
+- Inside a client repo, **read `AGENTS.md` first** and follow it; then `CLIENT.md`.
+- Read-only commands are always safe: `validate`, `status`, `sync --check`, `migrate --dry-run`,
+  and any `--help`.
+- Never edit `AGENTS.md` or `.gtm/`. Never run `gtm approve` unless a named human explicitly approved
+  in the session.
+- `gtm job` is not available yet: stop and tell the human rather than improvising with scripts.
+
+## Upgrades
+
+Client repos pin an exact version. New releases arrive as a pull request from the repo's weekly
+`gtm-upgrade` workflow, or via `pnpm gtm upgrade`. Breaking YAML changes ship with automatic
+migrations; see [CHANGELOG.md](https://github.com/Veleads/gtm-core/blob/main/CHANGELOG.md).

package/dist/cli.js

@@ -939,21 +939,134 @@ ${notes || "(no changelog entries)"}
   return valid;
 }
 
+// src/help.ts
+var COMMANDS = {
+  init: {
+    usage: 'gtm init <client-slug> --name "<Client Name>" [--dir <path>]',
+    summary: "scaffold a new client repo",
+    details: [
+      "Creates a complete client repo: client.yaml, context/ templates, campaigns/, tam/, CLIENT.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 client context."
+    ],
+    writes: "A new folder (default ./gtm-client-<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 ./clients/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 && pnpm gtm new-campaign q1-uk-cfo"]
+  },
+  validate: {
+    usage: "gtm validate [campaign]",
+    summary: "check repo against schemas, gates, data rules",
+    details: [
+      "Checks client.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: ["pnpm gtm validate", "pnpm gtm validate q1-uk-cfo"]
+  },
+  status: {
+    usage: "gtm status",
+    summary: "campaigns, stages, gates",
+    details: ["One screen: client, core version, ICP gate, and per campaign the stage, copy/launch gates, owner and latest run log."],
+    writes: "Nothing (read-only).",
+    examples: ["pnpm gtm status"]
+  },
+  approve: {
+    usage: 'gtm approve icp --by "<Name (side)>" [--notes ".."] [--date YYYY-MM-DD]\ngtm approve copy <campaign> --by "<Name (side)>" [--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: ['pnpm gtm approve icp --by "Maria Chen (client)" --notes "Segments A+B, personas CFO+AP"', 'pnpm gtm approve copy q1-uk-cfo --by "Maria Chen (client)"']
+  },
+  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: ["pnpm gtm sync", "pnpm gtm sync --check"]
+  },
+  migrate: {
+    usage: "gtm migrate [--dry-run]",
+    summary: "upgrade YAML files to current schema versions",
+    details: ["Applies core schema migrations to client.yaml, context/*.yaml and campaigns/*/config.yaml, keeping comments."],
+    writes: "Those YAML files, only if a migration applies. With --dry-run: nothing.",
+    examples: ["pnpm gtm migrate --dry-run", "pnpm 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: ["pnpm gtm upgrade", "pnpm 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: ["pnpm 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 client repos (@veleads/gtm)
+
+Usage: gtm <command> [options]      (inside a client repo: pnpm 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 client 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 +1086,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 +1127,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;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veleads/gtm",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "gtm-brain core: process kit (AGENTS.md, skills, templates, schemas) and the gtm CLI for client repos",
   "keywords": [
     "gtm",