GTM OS 0.2.5 release notes

CLI: @gtmos/cli 0.2.5. Images: ghcr.io/ay-automate/gtmos-{api,worker,mcp,console}:0.2.5 (also tagged stable), plus pgvector/pgvector:pg16.

0.2.5 is the largest release since 0.1.0. Your engines learn from outcomes, every factual claim in outbound content is checked against proof you approved, setup is a guided wizard, and a self-hosted instance is closed to the network by default. It follows release 0.2.2 and CLI 0.2.4.

Breaking change for self-hosters: ports are local-only by default

The console (3000), API (3001) and MCP (3004) ports now bind to 127.0.0.1. An existing deployment becomes local-only on its next gtm up or gtm upgrade.

If anyone reaches your server by IP address or hostname (a teammate's browser, a webhook, an MCP client on another machine), that stops working until you choose one of two things:

Put a reverse proxy with HTTPS on the same host in front of the three ports. This is the safer option, and the user guide has a Caddy example and the checks to run.
Or open the ports on purpose: set GTMOS_BIND_ADDRESS=0.0.0.0 in .env and run gtm up again (or run gtm up --bind 0.0.0.0).

gtm up prints a warning when it finds an existing deployment, and writes the setting into your .env so the choice is explicit from then on. The value is kept across later runs. If you only use GTM OS on one machine, nothing changes for you.

Product rules that hold for everything below: nothing sends, writes to a CRM, spends money, merges or publishes without a different person's approval. Agents propose and never approve. Dry Mode holds everywhere. Numbers are real, or they are a dash with a reason.

What is new

Setup and first wins

Setup wizard. A guided setup in the console (nine steps on six screens) and the same steps for your agent over MCP. It turns your answers, website, connected data and documents into the definitions your engines run on, shows the evidence behind every suggested value, and never invents one. It ends with a build, a short brief of your operating system, and Launch.
First-win checklist. Eight milestones computed from real facts in your workspace, not from clicks: instance ready, first real data source connected, first sync finished, first definition signed by a person, first Dry Mode draft, accounts with fit scores, a second person approving an action, and the first live message. A card on Home and on Setup shows what is done and what to do next.
Operator nudges (opt-in). Owners and admins get an in-app nudge when something needs them. Email is opt-in per person, every email carries an unsubscribe link, and nobody gets more than one a week. If email is not configured on your instance, the nudge says so plainly.
gtm doctor checks your harness. gtm init records which CLI, skills release and operation list it generated your files from. gtm doctor compares that with what is running and tells you to run gtm init --refresh when your project files are stale.

Trust and safety

Proof library. Settings > Proof library holds case studies, metrics, testimonials and logos, each with a permission (public, anonymized, internal only) and an optional expiry. Claims are extracted from documents you upload and kept only when the quote is verbatim in the source. A second person activates them. Customer phrases are mined from your text and approved one by one.
Claims gate. Every factual claim in outbound content (statistics, results, named customers, outcomes with no number) is checked against active proof when an action is proposed and again right before it runs. It covers outreach on every channel, SEO publishes and meeting invites. You set the policy in Settings, and acknowledging a claim is recorded.
Dry Mode per engine. Besides the organization-wide switch, each engine has its own Dry or Live mode in Settings > Safety. The stricter of the two applies. Going live is an owner or admin action, confirmed and audited.
Closed by default. Ports are local-only (above), GTMOS_LIVE must be set explicitly in production, instance keys are shared with organizations only for providers you list, members cannot commit CSV imports or bulk edits unless an owner allows it, and private records are actually private.

Engines (eight in the console)

Score, Outreach, Performance Ads, SEO & GEO, Enrichment, Merges, Plays and Routing.

Outcome learning. Scoring records each verdict, measures what happened afterwards (a positive reply, a meeting, an opportunity, a won deal), computes lift per criterion and proposes a new scoring model that a second person approves. The Score page shows what it learned. Reps can flag a score from the lead queue. Outreach shows what is working once a group has at least 30 sends.
Score. Signals fade by family, intent is weighted by who it comes from, hard disqualifiers, negative reply and bounce behavior, a neutral ICP default, and committee coverage. The next rescan re-scores accounts once. Preview it first.
Outreach. Multi-step sequences with waits in days or business days counted in the recipient's timezone, send windows, templates or briefs, weighted A/B variants and exits on reply, unsubscribe, bounce, a meeting or a stage change. Funding, hiring and intent signals can enroll one person per signal into an approved sequence with a daily cap. Personalization is tiered (1:1, 1:few, 1:many) and grounded in your proof library. Reply next steps are proposals, never automatic. Delivery reports from Gmail and Outlook are applied as bounces and never read as replies.
LinkedIn. Steps send through Unipile on the same approval path as email, with seat caps and an accept-wait step. It needs a real Unipile account and your explicit acceptance of the risk.
Performance Ads. Pacing and a nightly allocator steer toward a target you set. The allocator only proposes. MER, aMER, ACoS and CAC payback tiles, and a table of platform numbers against real ones.
Enrichment. Every written value carries when it was verified, a freshness window and a confidence. Stale values are re-checked, a newer value can replace an existing one only through an approval with undo, and a monthly spend cap spends on your best accounts first.
Routing. Capacity caps per type, weights, out-of-office, stickiness, and lead-to-account matching (only an exact domain match attaches on its own).
Merges. The duplicate scan follows your signed identity rule. Conflicts are decided per field and listed on the approval. Unmerge is safe.
Plays. Engines > Plays > Results shows runs, outcomes, credited revenue and spend per play. Nine plays ship in the blueprints: speed to lead, meeting prep, meeting follow-up, stage-stuck nudge, closed-lost win-back, renewal runway, champion change, content refresh and enrich on create.
SEO & GEO. Topic clusters, briefs and drafts with a quality gate. Publish to Webflow through Composio, to WordPress.com as drafts only, or through a signed webhook (also the route for self-hosted WordPress). The published body is the approved draft, bound to its hash.
Attribution. Position-based and per-channel models next to the equal split, chosen in Settings > Money > Attribution. Until you choose, your numbers stay on the equal split. Visits from AI assistants are credited to SEO & GEO.

Agents, skills and MCP

Sixteen organization agents in six packs (CRM, revenue, data, growth, ops, core), installed when a pack is enabled, with the same governance as any agent. Packs and blueprints can ship agent triggers (schedule, event or manual).
107 skills and 11 role subagents (gtm-operator, revops-analyst, deal-reviewer, sales-researcher, content-strategist, seo-refresher, customer-success-manager, competitive-analyst, ads-analyst, data-steward, eval-reviewer). gtm init installs them, checked against a manifest, with a bundled offline copy. Your edits to installed skills are kept when you refresh.
Console and MCP parity. An owner's or admin's agent key can do what that person can do in the console, scoped and audited. Agents never approve, execute, sign, give OAuth consent or switch Dry Mode.

Console

Connections page. Brand logos, search (press /), and three sort orders: relevance to your setup (default), A to Z, and connected first. Each integration shows Native or Via Composio, a Needed strip, and honest statuses.
Definitions and environments. The Go live card signs and promotes everything together. Applying in dev now says "Not applied (dev)" instead of "executed".
Plain words. Monitors, Audit log, Mission Control, Cost, Environments and app lists no longer show internal keys. Decided approvals show their final state, and the Focus Queue lists only approvals still waiting on a person.
Engine app updates. Settings > Packages has an owner-run card for engine app updates. An upgrade changes no installed engine app by itself.

Fixes from customer feedback

Contact import. A company column now links each contact to an account, matching by website first and then by name. Rows with no match, and rows that match more than one account, are listed so you can fix them. The import never creates accounts. Yes/no and number cells are accepted. Large imports no longer hit the 30 second limit.
Enrichment. Lookups run with your workspace key, with the instance key only as a fallback. When a provider is down, enrichment moves on to the next one instead of stopping.
Self-host ports. See the breaking change at the top.

Upgrade

An upgrade never touches, removes or loses your data. Every change in this release only adds. The updater refuses any release that does not, and there is no override.

Upgrade the CLI first. The CLI renders the compose file your instance runs on, so it must be at least as new as the release.
```
npm i -g @gtmos/cli@latest
```
See what is available. This changes nothing.
```
gtm upgrade --check
```
Rehearse, then upgrade. Run from your instance folder, or pass --dir <path>.
```
gtm upgrade --channel stable --dry-run
gtm upgrade --channel stable --yes
```
A plain gtm upgrade never moves an install that is pinned to a version. To move a pinned install, choose the target on purpose with --channel stable or --to 0.2.5.
Refresh your project files. In each project folder, run gtm init --refresh to take the new skills and subagents. Files you edited are kept.

What the upgrade does: it checks the signed release list, pulls the new images, checks that nothing destructive is pending, stops the services, takes and verifies a backup, rehearses the migration on a copy of your data, migrates, restarts and verifies. If a step fails, it rolls back by swapping the images back. Your data is never restored over your live database. Restoring a backup is a manual last resort, and you rename the live database first.

Before you start, know these:

Keep GTMOS_MASTER_KEY somewhere safe, apart from your backups. Backups do not contain it.
GTMOS_LIVE must be true or false in production, or the services refuse to start. The upgrade writes false into an older .env, which is how it already behaved.
Instance keys are shared with organizations only for providers in GTMOS_PLATFORM_CREDENTIAL_PROVIDERS. The upgrade keeps the providers you already use.
The first rescan after the upgrade can move account scores once. Run the rescan preview before it.
Visits from Copilot, Claude and other AI assistants move from "Website (other)" to SEO & GEO credit.
New workspaces start with the signal verification gate on Strict.

Check it worked

gtm doctor shows the sources you expect as live, and its Harness section has no stale line.
GET /health reports 0.2.5 on the API, worker, MCP server and console.
The upgrade reported that verification passed, and a snapshot exists in your backups folder.
Row counts of your main tables match the numbers you noted before.
The rescan preview looks reasonable.
Dry Mode check: propose one send to an internal address and confirm a different person has to approve it.
Settings > Proof library: add one proof and check that the claims check passes and blocks as expected.
gtm init --refresh in a project, then confirm .claude/agents holds the 11 subagents.

The full walkthrough, including rollback, is in the user guide.

Known limitations and what is not in this release

Not built yet:

Create in CRM. There is no gated "create a record in the CRM" action. CRM writes stay update-only, and high-risk Composio writes need per-record approval.
Custom field display and filters. "Show in tables" and "Allow filtering" are stored, but the Companies list has no such columns or filters yet. Record filters over the API and MCP do work.
Company context for AI steps. Only brand voice, proof and customer phrases reach drafts. The rest of your company context does not yet.
Connectors without a native card. Instantly, lemlist, Smartlead, Gong, Mixpanel and Amplitude. Use Composio.
Deferred. New engines (ABM, sales intelligence, lifecycle, reporting). Ads creative loop, audience sync and offline conversions. Routing SLAs and escalation. Merge batches and learning from rulings. An enrichment catalog with triggers for job changes. Play holdouts and a larger play library. GEO gap fixes and a link graph. More vendor skill packs. Engine-dependent agents and per-agent evaluation sets.

Works, with a caveat:

Signal scan quality. Web search results are not yet checked as being about the account. Set up a news binding for better results, or switch the scan off.

Rough edges:

The Records and Model pages still show ontology keys and type names, because they are model-builder pages.
A few small icon buttons are under 28 px at phone width.

Needs a live check with real accounts

The code is tested against contracts and a live database, but these need a real account. Treat them as unverified until you have checked them:

Unipile: a LinkedIn message, a connection request and the accept wait.
Webflow and WordPress.com: CMS publishing through Composio, and self-hosted WordPress through the signed webhook.
Gmail: a real bounce report arriving in a connected mailbox.
Resend: send, bounce and complaint events.
Salesforce: the native adapter is not verified against a real organization. Use the Composio path.

Docs

Quickstart and how-to: https://ay-automate.github.io/gtmos-releases/user-guide.html
Architecture, engines and security: https://ay-automate.github.io/gtmos-releases/product-documentation.html
Video series: https://ay-automate.github.io/gtmos-releases/videos/index.html
Earlier release, kept for history: 0.2.2