octwin-cli 0.8.17 → 0.9.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut th
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-21
+
+### Changed
+- **`octwin automation` reads your RULES — what you wrote — not job rows.** BREAKING for scripts: the list
+  is each rule of the project in the platform's own words (the sentence the console's Outbound → Automatic
+  tab shows), on or paused, its week (sent / not delivered / failed / skipped) and its next time, under the
+  week's numbers and what needs a look; `--json` is `{ summary, rules }`. New: `coming` (every time still to
+  come), `happened` (every fire, its final word, why a message did not go) and `why <id>` (one line's steps
+  and the words sent — what a scripted test asserts a fire with). `pause` / `resume` / `run` take a rule key;
+  the key of the older job in your own `automation.yaml` finds the rule it runs as (`src/lib/rules.ts`). It
+  listed job rows until now — since the platform ran every pack's automation as rules, those were only its
+  own two sweeps, so nothing you declared showed in the terminal. `campaigns` and `send` are unchanged.
+  Upgrade before the platform retires the jobs routes: an older CLI's `octwin automation` will answer 404.
+
+### Fixed
+- **`octwin records` lists a project's handoffs and cases even when the pack declares no types of its
+  own.** The catalog now carries the platform's entities with a `listed` flag per entity; the command
+  lists the listed ones (a missing flag, from an older server, reads as listed), so it neither prints
+  every unused platform type nor says "no record types" over a project full of handoffs.
+
 ## [0.8.17] - 2026-10-12
 
 ### Added

package/README.md

@@ -89,7 +89,7 @@ refused by name rather than leaving stdout empty.
 | `octwin analytics` | Stage-by-stage conversion for **any** entity declared with a `pipeline:` (`--overview` / `--milestones` / `--trends` / `--cost`; `--stage <id>` lists the records currently at a stage). Needs `records:read`. Page `--stage` with `octwin analytics <entity> --stage <id> --limit n --offset n`. |
 | `octwin catalog` | Commerce products with price / availability / stock, plus the WhatsApp catalog binding. `--readiness` runs the Meta Graph checklist. Needs `catalog:read` + the `catalog` plan feature. Page with `octwin catalog --limit n --offset n`. |
 | `octwin scheduling` | The scheduling engine's state, or `--slots <resourceRecordId>` for the slots one bookable resource actually computes — how you verify the availability rules `deploy --seed` created. Needs `scheduling:read`. `octwin scheduling --slots <resourceRecordId> --from YYYY-MM-DD --days n` reads one resource's computed slots. |
-| `octwin automation` | The jobs your pack's automation declaration produced — status, interval and each one's **last result** (matched / acted / errors) — under a health line counted in SQL. `campaigns` lists the campaigns. Jobs are derived from declarations, so there is no `create`. Needs `automation:read`. `octwin automation campaigns` (or `--campaigns`) lists campaigns; page with `octwin automation --limit n --offset n`. |
+| `octwin automation` | Your pack's **rules**, each in the platform's own words — on or paused, its week (sent / not delivered / failed / skipped) and its next time — under the week's numbers and what needs a look. `coming [--range today\|tomorrow\|week\|all] [--entity e] [--q text] [--cursor c]` lists every time still to come, `happened [--chip all\|not_delivered\|failed\|skipped\|moves\|tasks] [--period 7d\|30d] [--q text] [--cursor c]` every fire with its final word and why a message did not go, `why <id> [--kind timer\|fire\|queued]` one line's steps and the words sent. An older `segment` / `stale_records` / `sla_sweep` job or `on:` hook is listed as the rule it runs as. `campaigns` (or `--campaigns`) lists the campaigns, paged with `--limit n --offset n`. Needs `automation:read`. |
 | `octwin integrations` | What the pack **declares** beside what is actually **configured**, and it flags the gap: a connection declared and never configured is the commonest reason an integration silently never fires, and neither list alone shows it. `preflight <key>` diagnoses without calling out (`integrations:read`); `deliveries [id]` is the outbound log; `events` is what arrived inbound. Needs `integrations:read`. `octwin integrations deliveries --status s --operation id --limit n --offset n` is the outbound delivery log. |
 | `octwin journeys` | The customer journeys your pack declares, measured: `--funnel` (default) · `--overview` · `--goals` · `--trends` · `--cost` · `--definition` (what was declared, works with no traffic), plus `--stage <id>` for the runs sitting at a stage now. Same flag grammar as `octwin analytics` — a journey funnel and an entity funnel are the same question about different subjects. Needs `journeys:read`. Page `--stage` with `octwin journeys <id> --stage <stageId> --limit n --offset n`. |
 | `octwin performance` | The project's business indicators — value produced, conversion, duration — each with its delta against the previous window and a `why` naming the declaration it came from. `--detail` adds the breakdown. Needs `records:read`, **not** a `performance:*` scope (there is none). `octwin performance --range <days>` sets the window and `octwin performance --channel <whatsapp|web>` narrows every figure to one channel — the console's two controls. |
@@ -119,7 +119,7 @@ lists the verbs and their exact flags.
 | `octwin catalog` | `availability <sku> --to "in stock"` · `stock <sku> [--set-on-hand n]` |
 | `octwin scheduling` | `rules --resource <id>` · `rule add --resource <id> --dow 1 --start 09:00 --end 17:00 [--slot-minutes 30] [--capacity 1]` · `rule rm <ruleId>` · `exception add --resource <id> --date YYYY-MM-DD --kind closed\|extra [--start --end]` · `exception rm <id>` |
 | `octwin agents` | `set <ref> [--model m] [--enabled true\|false] [--overlay "…"\|none] [--enable-tool t] [--disable-tool t]` |
-| `octwin automation` | `run <jobId>` · `pause\|resume <jobId>` · `send <campaignId>` — the id may be the declaration **key** the list prints; the CLI resolves it to the uuid the route wants |
+| `octwin automation` | `pause\|resume <ruleKey>` · `run <ruleKey>` (a rule on a timetable, now) · `send <campaignId>` — a rule key is what the list prints; the key of the older job in your own `automation.yaml` finds the rule it runs as |
 | `octwin integrations` | `test <key>` (a live call to the connection's `health:` operation) · `retry\|cancel\|send-now <deliveryId>` |
 
 `--set k=v` coerces JSON scalars (`--set rating=4.5` sends a number); `--fields-json` takes anything
@@ -155,7 +155,7 @@ octwin orders                                 # then: octwin orders <reference_i
 octwin analytics                              # then: octwin analytics <entity> [--stage <id>]
 octwin catalog                                # products + stock + the WhatsApp binding
 octwin scheduling --slots <resourceRecordId>  # the slots your availability rules compute
-octwin automation                             # did your declared jobs run, and what did they touch
+octwin automation                             # your rules in words; then: coming · happened · why <id>
 octwin integrations                           # declared vs configured — the silent-never-fires check
 octwin journeys                               # then: octwin journeys <id> [--overview|--goals|--cost]
 octwin performance                            # value, conversion and duration, each with its `why`

package/dist/cli.js

@@ -28,7 +28,7 @@
  *   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion, any pipelined entity
  *   octwin catalog [--readiness]     # commerce products + stock + the WhatsApp catalog binding (catalog:read)
  *   octwin scheduling [--slots <resourceRecordId>]  # engine state / computed slots (scheduling:read)
- *   octwin automation [campaigns]    # the jobs your declarations produced + health + last result (automation:read)
+ *   octwin automation [coming|happened|why <id>|campaigns]  # the project's rules in words, what is coming up, what happened (automation:read)
  *   octwin integrations [deliveries|events|preflight|test …]  # declared vs configured, and the delivery log (integrations:read)
  *   octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition]  # declared journeys, measured (journeys:read)
  *   octwin performance [--detail]    # the project's business indicators (records:read — there is no performance scope)
@@ -85,6 +85,7 @@ import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 import { BASE_FILE, deployBaseOf, hashBundle, planPull, readBase, writeBase } from './lib/base.js';
 import { formatChecksRefusal } from './lib/refusal.js';
 import { readPage, morePageHint } from './lib/page.js';
+import { phraseText, resolveRuleKey, shortTime } from './lib/rules.js';
 import { chatLabel, answersTheTurn } from './lib/chat-line.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
 import { buildSymbols, linkExplainers, renderSymbolsMarkdown } from './lib/kb-symbols.js';
@@ -240,9 +241,9 @@ const VERB_REQUIREMENTS = {
     // which does NOT confer this — that 403 is otherwise baffling.
     'projects create': { scope: 'projects:write' },
     'projects rm': { scope: 'projects:write' },
-    // Jobs are declaration-derived, so there is no `create` — only acting on one.
-    // `campaigns` is absent on purpose: it is a READ sharing the verb slot, and an
-    // entry here would print "needs automation:write" on a read failure.
+    // Rules are declared, so there is no `create` — only acting on one (or a campaign).
+    // `coming` / `happened` / `why` / `campaigns` are absent on purpose: they are READS sharing
+    // the verb slot, and an entry here would print "needs automation:write" on a read failure.
     'automation run': { scope: 'automation:write' },
     'automation pause': { scope: 'automation:write' },
     'automation resume': { scope: 'automation:write' },
@@ -2763,12 +2764,16 @@ async function cmdRecords(flags) {
                 out.print('No AI Agent is loaded in this project.');
                 return;
             }
-            if (json?.has_xrm === false) {
-                // No record TYPES of its own — but the platform's own records (an order, a case) still read by name.
+            // The LISTED types, as the console's switcher shows them: the catalog carries every platform
+            // entity for lookups by name. A server older than the `listed` field sent declared types only,
+            // so a missing one reads as listed.
+            const ents = (json?.entities ?? []).filter(e => e.listed !== false);
+            if (json?.has_xrm === false && ents.length === 0) {
+                // No record TYPES of its own and no platform records yet — the platform's (an order, a case)
+                // still read by name.
                 out.print('This pack declares no record types of its own. Platform records still read by name: octwin records order | product | case | …');
                 return;
             }
-            const ents = (json?.entities ?? []);
             if (ents.length === 0) {
                 out.print('No entities visible — mint a token with the `records:read` scope to inspect data.');
                 return;
@@ -4927,49 +4932,51 @@ async function cmdScheduling(flags) {
     out.print(`  upcoming slots: ${json?.upcoming_slots ?? 0}   booked seats: ${json?.booked_seats ?? 0}`);
     out.print('\nSlots for one resource:  octwin scheduling --slots <resourceRecordId>   (ids: octwin records <entity>)');
 }
-// ── automation: declaration-derived jobs + campaigns ─────────────────────────
+// ── automation: the project's rules + campaigns ──────────────────────────────
 /**
- * Verbs that mean "act on a job", not "an id".
+ * Verbs of `octwin automation` — a view (`coming`, `happened`, `why`, `campaigns`) or an act (`run`, `pause`,
+ * `resume`, `send`) — not a rule key.
  *
- * `pause` / `resume` rather than a literal `status active|paused`: the route body
- * takes the status, but the RBAC layer it calls checks the ACTION
- * (`assertMay(…, action: 'pause' | 'resume')`), and `VERB_REQUIREMENTS` is keyed
- * per verb — so one verb per intent makes both the permission hint and the 403
- * say the right thing.
+ * Until 0.9.0 the command read JOB ROWS (`…/automation/jobs`). Since the platform's migration 126 those are only its
+ * own two sweeps: a pack's `rules:` — and its older `segment` / `stale_records` / `sla_sweep` jobs and `on:` hooks,
+ * which run as compiled rules — were invisible in the terminal. It reads the rules routes the console's Outbound →
+ * Automatic tab reads now, so the words are the server's.
  */
-const AUTOMATION_VERBS = new Set(['run', 'pause', 'resume', 'campaigns', 'send']);
+const AUTOMATION_VERBS = new Set(['coming', 'happened', 'why', 'run', 'pause', 'resume', 'campaigns', 'send']);
+const AUTOMATION_WRITES = new Set(['run', 'pause', 'resume', 'send']);
 /**
- * Turn whatever the author typed into the UUID the route demands.
- *
- * (`UUID_RE` is the one already declared for `--media`, deliberately reused rather
- * than a second copy of the same pattern.)
- *
- * The write routes take a UUID path param and reject anything else with a bare
- * *"Malformed identifier in the URL — expected a UUID"* 400. But the thing an author
- * has in front of them is the declaration KEY (`cart_recovery_nudge`) — that is what
- * the list prints, and it is the name in their own YAML. Measured: passing the key
- * 400s on all three write verbs.
- *
- * So the key is resolved here, against the list route, rather than documented as a
- * gotcha. A UUID passes straight through, and an unknown key fails naming the keys
- * that DO exist — which is the answer to the question the author is actually asking.
+ * Turn the campaign an author typed into the UUID the send route demands — the id `octwin automation campaigns`
+ * prints, or the campaign's key. An unknown one fails naming those that exist.
  */
-async function resolveAutomationId(kind, typed, base, t) {
+async function resolveCampaignId(typed, t) {
     if (UUID_RE.test(typed))
         return typed;
-    const { status, json } = await apiGet(`${base}/${kind}`, t);
-    if (status !== 200) {
-        die(`could not resolve '${typed}' — reading ${kind} failed (HTTP ${status})${errDetail(json)}`);
-    }
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const { status, json } = await apiGet(`${base}/campaigns`, t);
+    if (status !== 200)
+        die(`could not resolve '${typed}' — reading campaigns failed (HTTP ${status})${errDetail(json)}`);
     const rows = readPage(json).rows;
     const hit = rows.find(r => r.key === typed || r.id === typed);
     if (hit?.id)
         return hit.id;
     const keys = rows.map(r => r.key ?? r.id).filter(Boolean);
-    die(`no ${kind === 'jobs' ? 'job' : 'campaign'} '${typed}' in this project.`
-        + (keys.length ? ` Available: ${keys.join(', ')}` : ` This project declares none.`));
+    die(`no campaign '${typed}' in this project.` + (keys.length ? ` Available: ${keys.join(', ')}` : ' This project has none.'));
 }
-/** `pause`/`resume`/`run`/`send` — the writes behind `octwin automation`. */
+/** The rule an author typed, against the project's rules (`resolveRuleKey`) — or the command dies naming them. */
+async function resolveRule(typed, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const { status, json } = await apiGet(`${base}/rules`, t);
+    if (status !== 200)
+        die(`could not resolve '${typed}' — reading the rules failed (HTTP ${status})${errDetail(json)}`);
+    const keys = (json?.rules ?? []).map(r => r.key).filter((k) => typeof k === 'string');
+    const r = resolveRuleKey(typed, keys);
+    if ('error' in r)
+        die(r.error);
+    return r.key;
+}
+/** `pause` / `resume` / `run` a rule, `send` a campaign — the writes behind `octwin automation`. */
 async function cmdAutomationWrite(flags) {
     const t = resolveTarget(flags);
     const { url } = t;
@@ -4977,75 +4984,64 @@ async function cmdAutomationWrite(flags) {
     const verb = flags._[0];
     const typed = flags._[1];
     const asJson = flags.json === true;
-    if (!typed)
-        die(`usage: octwin automation ${verb} <${verb === 'send' ? 'campaignId' : 'jobId'}>   (ids: octwin automation${verb === 'send' ? ' campaigns' : ''})`);
-    const id = await resolveAutomationId(verb === 'send' ? 'campaigns' : 'jobs', typed, base, t);
-    if (verb === 'pause' || verb === 'resume') {
-        const { status, json } = await apiSend('PATCH', `${base}/jobs/${encodeURIComponent(id)}/status`, { status: verb === 'pause' ? 'paused' : 'active' }, t);
-        if (status === 404)
-            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
-        // RBAC re-checks the ACTION on the job, so a 403 here can be a grant gap
-        // rather than a missing scope — same caveat as a record write.
-        if (status !== 200)
-            writeFail(`${verb} job '${typed}'`, status, json, url, true);
-        if (asJson) {
-            out.result(json);
-            return;
-        }
-        const j = json?.job ?? {};
-        out.print(`✓ job '${j.key ?? typed}' is now ${j.status}`);
-        if (j.next_run_at)
-            out.print(`  next run: ${j.next_run_at}`);
-        return;
-    }
-    if (verb === 'run') {
+    if (verb === 'send') {
+        if (!typed)
+            die('usage: octwin automation send <campaignId>   (ids: octwin automation campaigns)');
+        const id = await resolveCampaignId(typed, t);
         if (!asJson)
-            out.print(`→ Running job '${typed}' in ${targetLabel(t)} …`);
-        const { status, json } = await apiSend('POST', `${base}/jobs/${encodeURIComponent(id)}/run`, undefined, t);
+            out.print(`→ Sending campaign '${typed}' in ${targetLabel(t)} …`);
+        const { status, json } = await apiSend('POST', `${base}/campaigns/${encodeURIComponent(id)}/send`, undefined, t);
         if (status === 404)
-            die(`job '${typed}' not found in ${targetLabel(t)} (ids: octwin automation)`);
+            die(`campaign '${typed}' not found in ${targetLabel(t)} (ids: octwin automation campaigns)`);
         if (status !== 200)
-            writeFail(`run job '${typed}'`, status, json, url, true);
+            writeFail(`send campaign '${typed}'`, status, json, url, true);
         if (asJson) {
             out.result(json);
             return;
         }
         const r = json?.result ?? {};
-        out.print(`✓ ran '${typed}': matched ${r.matched ?? 0}, acted ${r.acted ?? 0}, errors ${r.errors ?? 0}`);
-        // `acted < matched` is the route's own definition of a PARTIAL run, so say so
-        // rather than leaving three numbers for the author to compare.
-        if ((r.errors ?? 0) > 0)
-            out.print('  ⚠ some rows errored — see the job\'s last_result in `octwin automation`');
-        else if ((r.acted ?? 0) < (r.matched ?? 0))
-            out.print('  partial: matched rows were skipped (cooldown, or already acted on)');
+        const already = Number(r.already_queued ?? 0);
+        out.print(`✓ campaign '${typed}': matched ${r.matched ?? 0}, enqueued ${r.enqueued ?? 0}${already ? `, ${already} already had it` : ''}  [${r.stage ?? '?'}]`);
+        // A campaign that stopped half-way is FINISHED by the same command: it queues only the contacts
+        // with no delivery yet, so `already` is the earlier send's work, not a skip.
+        if (already)
+            out.print('  finished an earlier send — each contact gets this campaign once');
+        if ((r.enqueued ?? 0) + already < (r.matched ?? 0))
+            out.print('  partial: some matched records were not enqueued (records sharing a contact, or a record with none)');
+        out.print('  enqueued ≠ delivered — watch the sends land with `octwin automation happened`');
         return;
     }
-    // send — one campaign
-    if (!asJson)
-        out.print(`→ Sending campaign '${typed}' in ${targetLabel(t)} …`);
-    const { status, json } = await apiSend('POST', `${base}/campaigns/${encodeURIComponent(id)}/send`, undefined, t);
+    if (!typed)
+        die(`usage: octwin automation ${verb} <ruleKey>   (keys: octwin automation)`);
+    const key = await resolveRule(typed, t);
+    const path = `${base}/rules/${encodeURIComponent(key)}/${verb}`;
+    if (!asJson && verb === 'run')
+        out.print(`→ Running rule '${key}' in ${targetLabel(t)} …`);
+    const { status, json } = await apiSend('POST', path, undefined, t);
     if (status === 404)
-        die(`campaign '${typed}' not found in ${targetLabel(t)} (ids: octwin automation campaigns)`);
+        die(`rule '${key}' not found in ${targetLabel(t)} (keys: octwin automation)`);
+    // RBAC re-checks the ACTION on `automation.rule`, so a 403 can be a grant gap rather than a missing scope; a 409
+    // is the rule saying why not (only a rule on a timetable can be run now) — the server's words.
     if (status !== 200)
-        writeFail(`send campaign '${typed}'`, status, json, url, true);
+        writeFail(`${verb} rule '${key}'`, status, json, url, true);
     if (asJson) {
         out.result(json);
         return;
     }
-    const r = json?.result ?? {};
-    const already = Number(r.already_queued ?? 0);
-    out.print(`✓ campaign '${typed}': matched ${r.matched ?? 0}, enqueued ${r.enqueued ?? 0}${already ? `, ${already} already had it` : ''}  [${r.stage ?? '?'}]`);
-    // A campaign that stopped half-way is FINISHED by the same command: it queues only the contacts
-    // with no delivery yet, so `already` is the earlier send's work, not a skip.
-    if (already)
-        out.print('  finished an earlier send — each contact gets this campaign once');
-    if ((r.enqueued ?? 0) + already < (r.matched ?? 0))
-        out.print('  partial: some matched records were not enqueued (records sharing a contact, or a record with none)');
-    out.print('  enqueued ≠ delivered — watch the sends land with `octwin logs`');
+    if (verb === 'run') {
+        out.print(`✓ '${key}' runs now — it reaches ${json?.reaches ?? 0} record(s); next time after this run: ${shortTime(json?.next)}`);
+        out.print('  see what it did: octwin automation happened');
+    }
+    else if (verb === 'pause') {
+        out.print(`✓ '${key}' is paused — its times still arm, and nothing runs (nothing is caught up when it resumes)`);
+    }
+    else {
+        out.print(json?.resumed === false ? `  '${key}' was not paused` : `✓ '${key}' runs again`);
+    }
 }
 /**
- * A campaign's delivery progress — the per-status counts of the reminders it queued. Not sent yet
- * (a draft) is all zeros, and reads as a dash rather than "sent 0".
+ * A campaign's delivery progress — the per-status counts of its deliveries. Not sent yet (a draft) is all zeros, and
+ * reads as a dash rather than "sent 0".
  */
 function campaignProgressLine(p) {
     const n = (k) => Number(p?.[k] ?? 0);
@@ -5053,27 +5049,147 @@ function campaignProgressLine(p) {
         return '—'.padEnd(28);
     return `sent ${n('sent')} · failed ${n('failed')} · pending ${n('pending')}${n('cancelled') ? ` · cancelled ${n('cancelled')}` : ''}`.padEnd(28);
 }
+/** A line's record and customer, as one tail — `· Booking #7 · Sara`. */
+function lineTail(l) {
+    const rec = l?.record ? ` · ${l.record.noun ?? l.record.entity ?? 'record'} #${l.record.number ?? '?'}` : '';
+    const who = l?.contact ? ` · ${l.contact.name ?? 'customer'}` : '';
+    return `${rec}${who}`;
+}
+/** A query string of the values that are set — `range=week&q=cairo`. Each caller names the flags it passes. */
+function setQs(values) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(values))
+        if (typeof v === 'string')
+            p.set(k, v);
+    return p.toString();
+}
+/** `octwin automation coming` — every time still to come: a rule's, or a flow's own message (a send). */
+async function automationComing(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    if (!asJson)
+        out.print(`→ Reading what is coming up in ${targetLabel(t)} …`);
+    const qs = setQs({ range: flags.range, entity: flags.entity, q: flags.q, cursor: flags.cursor });
+    const { status, json } = await apiGet(`${base}/upcoming?${qs || 'range=week'}`, t);
+    if (status !== 200)
+        die(`could not read what is coming up (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+    if (asJson) {
+        out.result(json);
+        return;
+    }
+    const lines = (json?.lines ?? []);
+    out.print(`Coming up in ${targetLabel(t)} (${typeof flags.range === 'string' ? flags.range : 'week'}): ${json?.total ?? lines.length}`);
+    if (lines.length === 0)
+        out.print('  (nothing — a rule\'s time arms when its record is made or changed)');
+    for (const l of lines) {
+        const mark = l.skipped ? '  [skipped]' : l.paused ? '  [paused]' : '';
+        out.print(`  ${shortTime(l.at)}  ${phraseText(l.headline)}${lineTail(l)}${mark}  ${l.kind === 'queued' ? 'message' : 'timer'} ${l.id}`);
+    }
+    if (json?.next)
+        out.print(`\nMore: octwin automation coming --cursor ${json.next}`);
+    if (lines.length)
+        out.print('Why one goes, and what it will say:  octwin automation why <id>');
+}
+/** `octwin automation happened` — every fire of the period: its final word, and why a message did not go. */
+async function automationHappened(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    if (!asJson)
+        out.print(`→ Reading what happened in ${targetLabel(t)} …`);
+    const qs = setQs({ chip: flags.chip, period: flags.period, q: flags.q, cursor: flags.cursor });
+    const { status, json } = await apiGet(`${base}/history?${qs || 'period=7d'}`, t);
+    if (status !== 200)
+        die(`could not read what happened (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+    if (asJson) {
+        out.result(json);
+        return;
+    }
+    const lines = (json?.lines ?? []);
+    const c = json?.counts ?? {};
+    out.print(`Happened in ${targetLabel(t)} (${typeof flags.period === 'string' ? flags.period : '7d'}): ${json?.total ?? lines.length}`
+        + `  —  ${c.not_delivered ?? 0} not delivered, ${c.failed ?? 0} failed, ${c.skipped ?? 0} skipped`);
+    if (lines.length === 0)
+        out.print('  (nothing yet)');
+    for (const l of lines) {
+        const why = l.code || l.reason ? `  (${l.code ?? l.reason})` : '';
+        out.print(`  ${shortTime(l.at)}  ${String(l.outcome ?? '—').padEnd(13)} ${phraseText(l.headline)}${lineTail(l)}${why}  ${l.id}`);
+    }
+    if (json?.next)
+        out.print(`\nMore: octwin automation happened --cursor ${json.next}`);
+    if (lines.length)
+        out.print('Each step and the words sent:  octwin automation why <id>');
+}
 /**
- * `octwin automation [--campaigns] [--json]` — the jobs a pack's declarations
- * produced, with their last result, plus the health counts.
+ * `octwin automation why <id>` — one line's *Why?*, as the console's drawer: the rule in words, each step with its
+ * outcome, the words the customer reads. The line's kind picks the route (`--kind timer|fire|queued`); without it
+ * each is asked in turn — a coming time, a fire, a send.
+ */
+async function automationWhy(flags, t) {
+    const { url } = t;
+    const base = `${url}/api/self/p/automation`;
+    const asJson = flags.json === true;
+    const id = flags._[1];
+    if (!id)
+        die('usage: octwin automation why <id> [--kind timer|fire|queued]   (ids: octwin automation coming | happened)');
+    const kinds = typeof flags.kind === 'string' ? [flags.kind] : ['timer', 'fire', 'queued'];
+    for (const kind of kinds) {
+        if (!['timer', 'fire', 'queued'].includes(kind))
+            die(`--kind is timer, fire or queued (got '${kind}')`);
+        const { status, json } = await apiGet(`${base}/why/${kind}/${encodeURIComponent(id)}`, t);
+        if (status === 404)
+            continue;
+        if (status !== 200)
+            die(`could not read why (HTTP ${status})${errDetail(json)}${authFailureDetail(status, t.url)}`);
+        if (asJson) {
+            out.result(json);
+            return;
+        }
+        const v = json ?? {};
+        out.print(`${phraseText(v.line?.headline)}${lineTail(v.line)}  — ${shortTime(v.line?.at)}`);
+        if (v.rule)
+            out.print(`  rule ${v.rule.key}: ${phraseText(v.rule.sentence)}`);
+        if (v.line?.outcome)
+            out.print(`  outcome: ${v.line.outcome}${v.line.code ? ` (${v.line.code})` : ''}${v.line.reason ? ` — ${v.line.reason}` : ''}`);
+        for (const check of (v.checks ?? []))
+            out.print(`  checked again before it acts: ${phraseText(check)}`);
+        if (v.words?.text)
+            out.print(`  the customer reads${v.words.tag ? ` (${v.words.tag})` : ''}: ${v.words.text}`);
+        for (const s of (v.steps ?? [])) {
+            const send = s.send ? ` · ${s.send.status}${s.send.reason ? ` (${s.send.reason})` : ''}` : '';
+            out.print(`  step ${s.verb}: ${s.skipped ? `held back (${s.skipped})` : s.state}${send}${s.detail ? ` — ${s.detail}` : ''}`);
+        }
+        if (v.queued)
+            out.print(`  a flow's own message: ${v.queued.status}${v.queued.error ? ` — ${v.queued.error}` : ''}`);
+        return;
+    }
+    die(`nothing under '${id}' in ${targetLabel(t)} — a coming time may have just happened, and a fire is kept 30 days`);
+}
+/**
+ * `octwin automation [--json]` — the project's rules, each in the server's words, under the week's numbers.
  *
- * Needs `automation:read`. The job list is CAPPED server-side and the counts are
- * computed in SQL, so the header numbers come from `/health` rather than from
- * filtering the page — past the cap a client-side count would depend on the cap
- * instead of the data.
+ * Needs `automation:read`. The words are the console's (`rules/describe.ts` writes each rule as a sentence), so the
+ * terminal says what the Automatic tab says.
  */
 async function cmdAutomation(flags) {
-    if (typeof flags._[0] === 'string' && AUTOMATION_VERBS.has(flags._[0])) {
-        // `campaigns` is a READ that shares the verb slot with the writes.
-        if (flags._[0] !== 'campaigns')
-            return cmdAutomationWrite(flags);
+    const verb = typeof flags._[0] === 'string' ? flags._[0] : null;
+    if (verb && AUTOMATION_WRITES.has(verb))
+        return cmdAutomationWrite(flags);
+    if (verb && !AUTOMATION_VERBS.has(verb)) {
+        die(`unknown automation verb '${verb}' — octwin automation [coming | happened | why <id> | campaigns | run|pause|resume <ruleKey> | send <campaignId>]`);
     }
     const t = resolveTarget(flags);
     const { url } = t;
     const base = `${url}/api/self/p/automation`;
     const asJson = flags.json === true;
-    const campaigns = flags._[0] === 'campaigns' || flags.campaigns === true;
-    if (campaigns) {
+    if (verb === 'coming')
+        return automationComing(flags, t);
+    if (verb === 'happened')
+        return automationHappened(flags, t);
+    if (verb === 'why')
+        return automationWhy(flags, t);
+    if (verb === 'campaigns' || flags.campaigns === true) {
         if (!asJson)
             out.print(`→ Reading campaigns from ${targetLabel(t)} …`);
         const { status, json } = await apiGet(`${base}/campaigns?${pagingQs(flags)}`, t);
@@ -5100,40 +5216,37 @@ async function cmdAutomation(flags) {
         return;
     }
     if (!asJson)
-        out.print(`→ Reading automation jobs from ${targetLabel(t)} …`);
-    const [jobs, health] = await Promise.all([
-        apiGet(`${base}/jobs`, t),
-        apiGet(`${base}/health`, t),
-    ]);
-    if (jobs.status !== 200)
-        die(`could not read automation jobs (HTTP ${jobs.status})${errDetail(jobs.json)}${authFailureDetail(jobs.status, url)}`);
+        out.print(`→ Reading the rules of ${targetLabel(t)} …`);
+    const [rules, summary] = await Promise.all([apiGet(`${base}/rules`, t), apiGet(`${base}/summary`, t)]);
+    if (rules.status !== 200)
+        die(`could not read the rules (HTTP ${rules.status})${errDetail(rules.json)}${authFailureDetail(rules.status, url)}`);
+    const s = summary.status === 200 ? summary.json : null;
     if (asJson) {
-        out.result({ jobs: jobs.json, health: health.json });
+        out.result({ summary: s, rules: rules.json?.rules ?? [] });
         return;
     }
-    const page = readPage(jobs.json);
-    const h = health.status === 200 ? (health.json ?? {}) : {};
-    out.print(`Automation in ${targetLabel(t)}: ${h.total ?? page.rows.length} job(s)`
-        + `  —  ${h.active ?? '?'} active, ${h.paused ?? '?'} paused, ${h.failing ?? '?'} failing, ${h.never_checked ?? '?'} never checked`);
-    if (page.rows.length === 0) {
-        out.print('  (none — jobs are DERIVED from the pack\'s automation declaration, not created here.');
-        out.print('   No `automation.yaml` block → no jobs. `octwin deploy` installs them.)');
-        return;
+    const list = (rules.json?.rules ?? []);
+    const w = s?.week ?? {};
+    out.print(`Automation in ${targetLabel(t)}: ${list.length} rule(s)`
+        + (s ? `  —  this week ${w.sent ?? 0} sent, ${w.notDelivered ?? 0} not delivered, ${w.failed ?? 0} failed, ${s.counts?.upcoming ?? 0} coming up` : ''));
+    for (const n of (s?.needsLook ?? [])) {
+        out.print(`  ⚠ ${n.rule?.key ?? '?'}: ${n.kind === 'paused' ? 'paused' : n.kind === 'not_delivered' ? `${n.n} not delivered${n.codes?.length ? ` (${n.codes.join(', ')})` : ''}` : `${n.n} failed`}`);
     }
-    for (const j of page.rows) {
-        const r = j.last_result ?? {};
-        // A job runs only when its look finds work, so "not run yet" is normal; "never checked" is the dead one.
-        const ran = (j.last_run_at ? `last run ${j.last_run_at}` : 'not run yet')
-            + (j.last_checked_at ? `, checked ${j.last_checked_at}` : ', never checked');
-        const result = j.last_result
-            ? `  matched ${r.matched ?? 0}/acted ${r.acted ?? 0}${(r.errors ?? 0) > 0 ? `/ERRORS ${r.errors}` : ''}`
-            : '';
-        out.print(`  ${String(j.key ?? j.id).padEnd(26)} ${String(j.status).padEnd(7)} ${j.kind}/${j.entity ?? '—'}`
-            + `  every ${j.interval_seconds}s  ${ran}${result}`);
+    if (list.length === 0) {
+        out.print('  (none — a pack writes rules in automation.yaml `rules:`; `octwin deploy` installs them)');
+        return;
     }
-    out.print('\nRun one now:  octwin automation run <jobId>     (jobId = the `key` above, or its uuid)');
-    out.print('Pause/resume: octwin automation pause|resume <jobId>');
-    out.print('Campaigns:    octwin automation campaigns');
+    for (const r of list) {
+        const wk = r.week ?? {};
+        out.print(`  ${String(r.key)}  [${r.paused ? 'paused' : 'on'}]  next ${shortTime(r.next)}`
+            + `  ·  week ${wk.total ?? 0}: ${wk.sent ?? 0} sent, ${wk.notDelivered ?? 0} not delivered, ${wk.failed ?? 0} failed, ${wk.skipped ?? 0} skipped`);
+        out.print(`      ${phraseText(r.sentence)}`);
+    }
+    out.print('\nComing up:     octwin automation coming [--range today|tomorrow|week|all]');
+    out.print('Happened:      octwin automation happened [--chip not_delivered|failed|skipped|moves|tasks] [--period 7d|30d]');
+    out.print('Why one line:  octwin automation why <id>');
+    out.print('Act:           octwin automation pause|resume|run <ruleKey>   (needs automation:write)');
+    out.print('Campaigns:     octwin automation campaigns');
 }
 // ── integrations: declared connections, their credentials, and the delivery log ──
 /** Verbs that act on a connection or a delivery, rather than naming one. */
@@ -5952,7 +6065,7 @@ function help() {
   octwin analytics [entity] [--funnel|--overview|--milestones|--trends|--cost] [--stage <id>]  # stage conversion for any pipelined entity
   octwin catalog [--readiness] [--json]                  # commerce products + stock + the WhatsApp catalog binding
   octwin scheduling [--slots <resourceRecordId>] [--from YYYY-MM-DD] [--days n]  # engine state / computed slots
-  octwin automation [campaigns] [--json]                 # the jobs your declarations produced + health, last result each
+  octwin automation [coming|happened|why <id>|campaigns] [--json]   # the rules in words; coming up; happened, and why
   octwin integrations [--json]                           # declared connections BESIDE what is configured (the silent-never-fires check)
   octwin integrations deliveries [<id>] | events         # the outbound delivery log / inbound events
   octwin journeys [journeyId] [--funnel|--overview|--goals|--trends|--cost|--definition] [--stage <id>]
@@ -5975,7 +6088,7 @@ Writes — exercise the state your pack creates (each needs the matching :write
   octwin catalog availability <sku> --to "in stock" | stock <sku> [--set-on-hand n]
   octwin scheduling rules --resource <id> | rule add|rm | exception add|rm
   octwin agents  set <packId::agentId> [--model m] [--enable-tool t] [--disable-tool t]
-  octwin automation run <jobId> | pause <jobId> | resume <jobId> | send <campaignId>
+  octwin automation pause|resume|run <ruleKey> | send <campaignId>
   octwin integrations test <key>                         # a LIVE call to the connection's health: operation
   octwin integrations retry|cancel|send-now <deliveryId>
   (octwin integrations preflight <key> needs only integrations:read — it makes no call)
@@ -6260,24 +6373,35 @@ octwin projects rm <slug> [--yes]
 
   --dow is 0-6, 0 = Sunday. \`rules\` is how you find an id to remove, and
   \`--slots\` is how you check what a rule actually produces.`,
-    automation: `octwin automation [campaigns | --campaigns] [--limit n] [--offset n] [--json]
-  No args = every job the pack's automation declaration produced, with its status,
-  interval and LAST RESULT (matched / acted / errors), under a health line whose
-  counts come from SQL rather than from filtering the page — the job list is capped
-  server-side, so a client-side count would depend on the cap. Needs automation:read.
-
-  Jobs are DERIVED from declarations. There is no \`create\`: no automation block in
-  the pack means no jobs, and \`octwin deploy\` is what installs them.
-
-  WRITES (automation:write):
-    octwin automation run <jobId>          # run once, now — prints matched/acted/errors
-    octwin automation pause|resume <jobId>
-    octwin automation send <campaignId>    # enqueue a campaign; enqueued != delivered
-
-  <jobId> is the \`key\` the list shows (its uuid works too). The routes themselves
-  accept only a uuid — the CLI resolves the key for you, and names the keys that do
-  exist when it cannot. A 403 on a write can be an RBAC grant gap rather than a
-  missing scope: the action is re-checked against the job.`,
+    automation: `octwin automation [coming | happened | why <id> | campaigns | --campaigns] [--json]
+  No args = every RULE of the project — each in the platform's own words (the
+  sentence the console's Outbound → Automatic tab shows), on or paused, its week
+  (sent / not delivered / failed / skipped) and its next time — under the week's
+  numbers and what needs a look. Needs automation:read.
+
+  A pack writes rules in automation.yaml \`rules:\`; its older \`segment\` /
+  \`stale_records\` / \`sla_sweep\` jobs and xrm \`on:\` hooks run as rules too,
+  listed under the key they compile to (\`segment:<job key>\`).
+
+  READ:
+    octwin automation coming   [--range today|tomorrow|week|all] [--entity e] [--q text] [--cursor c]
+                               # every time still to come — a rule's, or a flow's own message
+    octwin automation happened [--chip all|not_delivered|failed|skipped|moves|tasks] [--period 7d|30d] [--cursor c]
+                               # every fire: its final word, and why a message did not go
+    octwin automation why <id> [--kind timer|fire|queued]
+                               # one line: the rule in words, each step, the words sent
+    octwin automation campaigns [--limit n] [--offset n]
+
+  WRITES (automation:write):
+    octwin automation pause|resume <ruleKey>   # paused: its times arm, nothing runs, nothing caught up
+    octwin automation run <ruleKey>            # a rule on a timetable, now
+    octwin automation send <campaignId>        # enqueue a campaign; enqueued != delivered
+
+  <ruleKey> is the key the list prints; the key of the older job in your own
+  automation.yaml finds the rule it runs as. A 403 on a write can be an RBAC grant
+  gap rather than a missing scope: the action is re-checked on automation.rule.
+  (Until 0.9.0 this command listed job rows — since the platform ran every pack's
+  automation as rules, those were only its own two sweeps.)`,
     integrations: `octwin integrations [--json]
   What the pack DECLARES beside what is actually CONFIGURED, in one view — because a
   connection that is declared and never configured is the commonest reason an
@@ -6410,7 +6534,7 @@ export const COMMANDS = {
     analytics: { run: cmdAnalytics, json: 'document', flags: ['funnel', 'overview', 'milestones', 'trends', 'cost', 'stage', 'limit', 'offset'] },
     catalog: { run: cmdCatalog, json: 'document', flags: ['limit', 'offset', 'readiness', 'set-on-hand', 'to'] },
     scheduling: { run: cmdScheduling, json: 'document', flags: ['capacity', 'date', 'days', 'dow', 'end', 'from', 'kind', 'resource', 'slot-minutes', 'slots', 'start'] },
-    automation: { run: cmdAutomation, json: 'document', flags: ['campaigns', 'limit', 'offset'] },
+    automation: { run: cmdAutomation, json: 'document', flags: ['campaigns', 'chip', 'cursor', 'entity', 'kind', 'limit', 'offset', 'period', 'q', 'range'] },
     integrations: { run: cmdIntegrations, json: 'document', flags: ['limit', 'offset', 'operation', 'status'] },
     journeys: { run: cmdJourneys, json: 'document', flags: ['funnel', 'overview', 'goals', 'trends', 'cost', 'definition', 'stage', 'limit', 'offset'] },
     performance: { run: cmdPerformance, json: 'document', flags: ['detail', 'range', 'channel'] },

package/dist/lib/rules.js

@@ -0,0 +1,36 @@
+/**
+ * What `octwin automation` needs to speak RULES — the project's rules as the platform's Automatic tab reads them
+ * (`/api/self/p/automation/…`). Pure, so the two decisions it makes are tested on their own:
+ *
+ * - **which rule an author means** (`resolveRuleKey`) — the key `octwin automation` prints, or the key of the older
+ *   `automation.yaml` job it was compiled from: a `segment` job `cart_nudge` runs as the rule `segment:cart_nudge`,
+ *   and the job key is what the author has in their own YAML;
+ * - **the server's words** (`phraseText`) — a rule's sentence and a line's headline arrive as `Phrase`s (text, a
+ *   strong part, a quote with named slots), the same the console draws; the terminal prints them flat.
+ */
+/** A sentence of `Phrase`s as one line of text — a quote in quotes, a slot as `{name}`. */
+export function phraseText(phrases) {
+    return (phrases ?? []).map(p => p.text ?? p.strong
+        ?? (p.quote ? `"${p.quote.map(q => q.text ?? `{${q.slot ?? ''}}`).join('')}"` : '')).join('');
+}
+/**
+ * The rule an author typed: its key exactly, else the one rule whose key ends in `:<typed>` (an older job's key, or a
+ * hook's moment). Two such rules, or none, is an answer that names what does exist.
+ */
+export function resolveRuleKey(typed, keys) {
+    if (keys.includes(typed))
+        return { key: typed };
+    const hits = keys.filter(k => k.endsWith(`:${typed}`));
+    if (hits.length === 1)
+        return { key: hits[0] };
+    if (hits.length > 1)
+        return { error: `'${typed}' could be ${hits.length} rules — ${hits.join(', ')}. Use the full key.` };
+    return { error: `no rule '${typed}' in this project.` + (keys.length ? ` Rules: ${keys.join(', ')}` : ' It runs none.') };
+}
+/** A time as the terminal shows it — `2026-10-22 09:00Z`; a missing one is a dash. */
+export function shortTime(iso) {
+    if (!iso)
+        return '—';
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? iso : `${d.toISOString().slice(0, 16).replace('T', ' ')}Z`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.17",
+  "version": "0.9.0",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {

package/templates/starter/automation.yaml

@@ -0,0 +1,10 @@
+# What the pack does by itself — rules: WHEN something changes (`on:`) or a time arrives (`at:`), FOR a
+# record, DO actions. Guide: `craft-automation`; every change, time and action: `rules-guide`.
+rules:
+  # The journey's goal, reached by the RECORD — so a request an operator creates counts too, not
+  # only chat ones. Guide: `craft-measure`.
+  - key: request_made
+    for: request
+    on: created
+    do:
+      - track: { journey: request, goal_reached: requested }

package/templates/starter/xrm.yaml

@@ -16,11 +16,7 @@ entities:
     pipeline:
       stages:   [new, scheduled, done, cancelled]
       terminal: [done, cancelled]
-    # The journey's goal, reached by the RECORD — so a request an operator creates counts too, not
-    # only chat ones. Guide: `craft-measure`.
-    on:
-      create:
-        - track: { journey: request, goal_reached: requested }
+    # What happens by itself when a request is made, moves or goes quiet is a rule — `automation.yaml`.
 
 # Rows every new project starts with (`octwin deploy --seed`) — a customer may see them.
 demo: