@signaliz/cli 1.0.2 → 1.0.4

package/README.md

@@ -11,6 +11,42 @@ Fresh enrichment throughput now allows Free 60/min, Builder 300/min, Team
 600/min, Agency 1,000/min, and Pay-As-You-Go 1,000/min, with a 5,000/hour
 workspace safety cap.
 
+## Where To Start
+
+If you are not sure whether to use the UI, CLI, Codex, MCP, or SDK, start here:
+
+```bash
+signaliz start
+```
+
+Signaliz is the GTM brain over any stack. Use CLI, MCP, Codex, or SDK when an
+agent needs to build, audit, route, or debug work. Use the UI as the human
+cockpit to inspect state, connect tools, approve gated actions, and monitor
+results.
+
+`signaliz start` is read-only. It checks workspace health, credits, Ops proof,
+Kernel readiness, and provider-route blockers, then recommends one next safest
+move plus exact commands for five plain workflows:
+
+- Build a campaign plan: `signaliz build "campaign brief"`.
+- Connect tools and provider routes: `signaliz connect`.
+- Audit previous campaigns: `signaliz audit`.
+- 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
@@ -19,36 +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. Check workspace/API health and discover GTM tools
-signaliz health
-signaliz discover --query "build a campaign with webhook delivery" --category ops
+# 2. Orient. This is read-only and prints one next safest move.
+signaliz start
+
+# 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"
 
-# 3. 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>
 
-# 4. 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
 
-# 5. 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
@@ -149,6 +190,71 @@ signaliz email status <job_id>
 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
+signaliz gtm context --no-memory --limit 5 --json
+
+# Check Kernel, Brain, feedback, memory, and connection readiness gates
+signaliz gtm bootstrap
+signaliz gtm bootstrap --campaign-id <campaign_id> --include-samples --json
+
+# Compose a read-only campaign build plan before creating, routing, or spending
+signaliz gtm plan "Find CTOs at fintech startups in NYC" \
+  --target-count 100 \
+  --layers icp,lead_generation,email_verification,sender,feedback \
+  --preferred-providers instantly \
+  --include-planned
+
+# 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 --confirm
+
+# List and inspect first-class GTM campaigns
+signaliz gtm campaigns --status active
+signaliz gtm campaign <campaign_id> --log-limit 20 --memory-limit 20
+
+# Search ranked GTM memory instead of dumping raw history
+signaliz gtm memory "positive replies from technical founders" \
+  --outcome-type positive_reply \
+  --limit 10
+
+# Plan Brain learning in dry-run mode
+signaliz gtm learning <campaign_id> --include-network --write-mode dry_run
+signaliz gtm learning-run <campaign_id> \
+  --phases workspace_pattern_extraction,failure_pattern_detection,defaults_seed,delivery_risk \
+  --write-mode dry_run
+signaliz gtm calibrate <campaign_id> --min-sample-size 10
+
+# Inspect and repair provider readiness without leaving the CLI
+signaliz gtm execution <campaign_id>
+signaliz gtm integrations --campaign-id <campaign_id> --include-planned
+signaliz gtm route-preview --campaign-id <campaign_id> --layer sender
+signaliz gtm activate-route --campaign-id <campaign_id> \
+  --provider-id instantly \
+  --layer sender
+
+# 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 --confirm-spend
+
+# Write route changes only after reviewing the dry-run
+signaliz gtm activate-route --campaign-id <campaign_id> \
+  --provider-id instantly \
+  --layer sender \
+  --confirm
+
+# Prepare feedback ingress with feedback-triggered Brain learning
+signaliz gtm feedback-webhook --provider instantly \
+  --campaign-id <campaign_id> \
+  --write-mode dry_run
+```
+
 ## Campaign Builder
 
 ### Build a campaign
@@ -262,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
@@ -279,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
@@ -346,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
@@ -366,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.