@signaliz/cli 1.0.3 → 1.0.5

package/README.md

@@ -34,6 +34,19 @@ move plus exact commands for five plain workflows:
 - Improve results from learning: `signaliz improve <campaign_id>`.
 - Prove Ops delivery: `signaliz prove`.
 
+## Concepts
+
+Signaliz is the GTM brain over your stack. Six nouns explain the rest:
+
+- Op - one executable unit of work, created from a goal or plan. You run it, poll it, and retrieve results.
+- Routine - an Op on a schedule. Each scheduled execution is a Tick, and each Tick produces items you can inspect.
+- Sink - a delivery destination such as webhook, CSV, Slack, Sheets, Airbyte, or Nango.
+- Kernel - your workspace's persistent GTM state: campaigns, memory, connections, provider routes, and readiness gates.
+- Brain - the learning layer over the Kernel. It extracts campaign patterns, calibrates deliverability, and seeds safer defaults.
+- Campaign - a governed outbound object built from Kernel state and Brain learning. A Campaign Build is one execution that produces rows and artifacts.
+
+Use Campaign Builder when you need a list now. Use the GTM Kernel when the campaign should persist, route through specific providers, and improve from feedback. Use Ops when the job is prompt-first or recurring, such as monitors, alerts, and ad-hoc pulls.
+
 ## Install
 
 ```bash
@@ -42,50 +55,41 @@ npm install -g @signaliz/cli
 
 ## Quick Start
 
+The golden path, in order. Each step shows the canonical command surface; compatibility aliases still work, but the README keeps one path visible.
+
 ```bash
 # 1. Authenticate
 signaliz auth login
 
-# 2. Get the recommended next safest move
+# 2. Orient. This is read-only and prints one next safest move.
 signaliz start
-signaliz build "Build a campaign for industrial maintenance buyers" --target-count 50
-signaliz connect
-signaliz audit
-signaliz prove
 
-# 3. Check workspace/API health and discover GTM tools
-signaliz health
-signaliz gtm context
-signaliz gtm bootstrap --include-samples
-signaliz gtm plan "Build 100 verified VP Sales leads at B2B SaaS companies" --target-count 100 --json > plan.json
-signaliz gtm commit-plan --plan-file plan.json
-signaliz gtm commit-plan --plan-file plan.json --write --confirm
-signaliz gtm prepare-build <campaign_id> --build-input --json > build-args.json
-signaliz campaign build --input-file build-args.json
-signaliz discover --query "build a campaign with webhook delivery" --category ops
+# 3. Plan something. Pick the surface that matches the job.
+signaliz campaign build --prompt "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --dry-run
+signaliz gtm plan "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --json > plan.json
+signaliz ops plan "Build 100 verified VP Sales leads at B2B SaaS companies"
 
-# 4. Plan and create a prompt-first Op
-signaliz /plan "Build 100 verified VP Sales leads at B2B SaaS companies"
-signaliz quickstart company_research
-signaliz /goal "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
+# 4. Launch only after review.
+signaliz campaign build --prompt "VP Sales at B2B SaaS, 50-500 employees" --target-count 100 --confirm-spend --wait
+signaliz gtm commit-plan --plan-file plan.json --confirm
+signaliz ops create "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
+signaliz ops run <op_id>
 
-# 5. Run, poll, and retrieve results
-signaliz run <op_id>
-signaliz status <op_id>
-signaliz results <op_id> --limit 100 --json
+# 5. Check status and pull results.
+signaliz campaign status <campaign_build_id>
+signaliz campaign rows <campaign_build_id> --limit 100
+signaliz ops status <op_id>
+signaliz ops results <op_id> --limit 100 --json
 
-# 6. Debug async execution and queue health
-signaliz ops run-status <trigger_run_id>
-signaliz queue --summary
-signaliz debug <op_id>
-signaliz watch <trigger_run_id>
-signaliz tail <trigger_run_id>
-signaliz doctor
-signaliz readiness
-signaliz dashboard summary
-signaliz ops dashboard summary
+# 6. Debug async execution when something stalls.
+signaliz ops run-status <trigger_run_id> --watch
+signaliz ops queue --summary
+signaliz ops logs <trigger_run_id>
+signaliz ops doctor
 ```
 
+Two gates protect you. `--confirm-spend` approves spendful launches and delivery risk after reviewing an estimate. `--confirm` writes Kernel or provider-route state after a dry-run. Read-only planning and dry-runs do not spend credits or mutate state.
+
 ## Authentication
 
 ```bash
@@ -188,6 +192,8 @@ signaliz email find --company-domain stripe.com --full-name "Jane Smith"
 
 ## GTM Kernel
 
+Use this path when the campaign should become durable workspace state. The plan is read-only, `commit-plan` dry-runs first, and writes require `--confirm`.
+
 ```bash
 # Inspect the workspace Kernel context available to agents
 signaliz gtm context
@@ -207,7 +213,7 @@ signaliz gtm plan "Find CTOs at fintech startups in NYC" \
 # Save the JSON plan, then dry-run a reviewed campaign-object commit
 signaliz gtm plan "Find CTOs at fintech startups in NYC" --target-count 100 --json > plan.json
 signaliz gtm commit-plan --plan-file plan.json
-signaliz gtm commit-plan --plan-file plan.json --write --confirm
+signaliz gtm commit-plan --plan-file plan.json --confirm
 
 # List and inspect first-class GTM campaigns
 signaliz gtm campaigns --status active
@@ -235,19 +241,12 @@ signaliz gtm activate-route --campaign-id <campaign_id> \
 
 # Derive exact dry-run build input from the committed GTM campaign object
 signaliz gtm prepare-build <campaign_id> --build-input --json > build-args.json
-signaliz campaign build --input-file build-args.json
-
-# Reproduce the full first-run proof path as one local receipt
-node scripts/gtm-kernel-first-run-proof.mjs \
-  --brief "Find CTOs at fintech startups in NYC" \
-  --confirm-draft-write \
-  --out-dir /tmp/gtm-kernel-first-run-proof
+signaliz campaign build --input-file build-args.json --confirm-spend
 
 # Write route changes only after reviewing the dry-run
 signaliz gtm activate-route --campaign-id <campaign_id> \
   --provider-id instantly \
   --layer sender \
-  --write \
   --confirm
 
 # Prepare feedback ingress with feedback-triggered Brain learning
@@ -369,14 +368,12 @@ email verification primitive.
 ## Ops Execution And Observability
 
 Prompt-first Ops stay simple for beginners, but the CLI exposes production
-inspection paths for operators debugging asynchronous workflows.
+inspection paths for operators debugging asynchronous workflows. The canonical
+surface is `signaliz ops ...`; shortcut aliases remain available for existing
+scripts but are not needed for new work.
 
 ```bash
 # Natural-language planning and creation
-signaliz /plan "Monitor these accounts daily and alert Slack on funding signals"
-signaliz /goal "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
-signaliz plan "Monitor these accounts daily and alert Slack on funding signals"
-signaliz goal "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
 signaliz ops plan "Monitor these accounts daily and alert Slack on funding signals"
 signaliz ops quickstart company_research
 signaliz ops create "Build 100 verified VP Sales leads at B2B SaaS companies" --confirm-spend
@@ -386,53 +383,45 @@ signaliz ops run <op_id>
 signaliz ops status <op_id>
 signaliz ops results <op_id> --limit 100 --json
 signaliz ops results <op_id> --include-failed-runs --json
-signaliz run <op_id>
-signaliz status <op_id>
-signaliz results <op_id> --limit 100 --json
 
 # Save repeatable local Ops command recipes
-signaliz saved save daily-goal -- /goal "Build 100 verified VP Sales leads" --target-count 100
+signaliz ops saved save daily-goal -- create "Build 100 verified VP Sales leads" --target-count 100
 signaliz ops saved save daily-monitor -- plan "Monitor key accounts daily" --cadence daily --destinations slack,csv
-signaliz saved list
-signaliz saved run daily-monitor --json
-signaliz saved delete daily-monitor
+signaliz ops saved list
+signaliz ops saved run daily-monitor --json
+signaliz ops saved delete daily-monitor
 
 # Inspect Trigger.dev execution state
 signaliz ops run-status <trigger_run_id>
 signaliz ops run-status <trigger_run_id> --watch --interval-ms 5000 --max-polls 60
-signaliz watch <trigger_run_id>
 signaliz ops run-status --run-ids run_a,run_b --json
 
 # Inspect async queue depth, provider pressure, and individual jobs
 signaliz ops queue
 signaliz ops queue --summary
-signaliz queue --summary
 signaliz ops queue --job-id <api_request_queue_id>
 signaliz ops queue --idempotency-key <key>
 
 # Stream live run logs
 signaliz ops logs <trigger_run_id>
-signaliz tail <trigger_run_id>
 signaliz ops logs <trigger_run_id> --since <event_id> --filter error
 
 # Replay a failed execution from a captured checkpoint
 signaliz ops replay <execution_event_id>
-signaliz replay <execution_event_id>
 
 # Approve or reject pending Ops approval tokens
-signaliz approve <approval_token_id> --decision approved
-signaliz approve --token-ids token_a,token_b --decision rejected --notes "Needs review"
+signaliz ops approve <approval_token_id> --decision approved
+signaliz ops approve --token-ids token_a,token_b --decision rejected --notes "Needs review"
 
 # Inspect and manually run routines
-signaliz routines --status active
-signaliz routine <routine_id>
-signaliz routine <routine_id> run --force
-signaliz routine <routine_id> ticks --limit 20
-signaliz routine <routine_id> items --state failed --json
+signaliz ops routines --status active
+signaliz ops routine <routine_id>
+signaliz ops routine <routine_id> run --force
+signaliz ops routine <routine_id> ticks --limit 20
+signaliz ops routine <routine_id> items --state failed --json
 
 # Pull operator telemetry from the Ops dashboard API
 signaliz ops dashboard summary
-signaliz dashboard summary
 signaliz ops dashboard functions --time-range-days 7 --json
 signaliz ops dashboard recent --limit 25
 signaliz ops dashboard timeseries --granularity hour --json
@@ -453,11 +442,10 @@ signaliz tools --json
 signaliz discover --query "verify emails" --json
 signaliz lead status <job_id> --json
 signaliz email verify jane@example.com --json
-signaliz queue --summary --json
+signaliz ops queue --summary --json
 signaliz ops run-status <trigger_run_id> --json
-signaliz replay <execution_event_id> --json
+signaliz ops replay <execution_event_id> --json
 signaliz ops dashboard summary --json
-signaliz dashboard summary --json
 ```
 
 When `campaign build --wait --json` is used, the CLI emits one valid JSON
@@ -473,5 +461,4 @@ document with both `initial` and `final` states.
 
 ## Config File
 
-The CLI stores configuration in `~/.signaliz/config.json` (mode 0600). The file contains your API key and optional workspace context created by `signaliz auth workspace set`. `SIGNALIZ_API_KEY` and `SIGNALIZ_WORKSPACE_ID` override saved config values for one-off execution.
-The CLI stores configuration in `~/.signaliz/config.json` (mode 0600). The file contains your API key, optional workspace settings, and local saved Ops command recipes created by `signaliz ops saved save`.
+The CLI stores configuration in `~/.signaliz/config.json` (mode 0600). The file contains your API key, optional workspace context created by `signaliz auth workspace set`, and local saved Ops command recipes created by `signaliz ops saved save`. `SIGNALIZ_API_KEY` and `SIGNALIZ_WORKSPACE_ID` override saved config values for one-off execution.