@veleads/gtm 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to `@veleads/gtm`. Each entry is tagged: **no action**, **op
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-24
+- **migration** "Clients" are now **projects**: one private repo = one project.
+  `client.yaml` → `project.yaml`, `CLIENT.md` → `PROJECT.md`, `client_id` → `project_id` in every YAML
+  file (all kinds now version 2), `owners.client_approver` → `owners.approver`, project status
+  `churned` → `closed`. `gtm migrate` (run by `gtm upgrade`) renames the files and keys in place,
+  keeping comments; existing ICP/copy approvals stay valid. New repos are named `gtm-project-<slug>`.
+- **action** Approvals are recorded as name and role, e.g. `--by "Maria Chen (VP Marketing)"`.
+- **action** Project repos no longer require pnpm. New repos default to npm (no `packageManager` pin),
+  and every command is `npx gtm <command>`. CI and `gtm upgrade` use whichever package manager the
+  repo's committed lockfile belongs to (npm, pnpm or yarn). Existing repos: copy the CI workflows from
+  `.gtm/templates/repo/github/workflows/` after upgrading.
+
+## [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 projects with one standard,
+agent-agnostic process. Each project 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+. npm is enough; pnpm or yarn work too (the repo follows whichever lockfile you commit).
+
+```bash
+npx @veleads/gtm init acme --name "Acme Corp"
+cd gtm-project-acme
+npm install
+npx gtm status
+npx 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 project 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` |
+| `PROJECT.md` | project-specific rules that add to the process | yes |
+| `project.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 (**sign-off**) → TAM → enrich → qualify → copy (**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 project repo as `npx gtm <command>` (whichever package manager installed it). `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 project 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 project repo, **read `AGENTS.md` first** and follow it; then `PROJECT.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
+
+Project repos pin an exact version. New releases arrive as a pull request from the repo's weekly
+`gtm-upgrade` workflow, or via `npx gtm upgrade`. Breaking YAML changes ship with automatic
+migrations; see [CHANGELOG.md](https://github.com/Veleads/gtm-core/blob/main/CHANGELOG.md).