jsfe 1.14.2 → 1.15.1

package/README.md

@@ -14,7 +14,7 @@ npm i jsfe
 - **[README.md](README.md)** - Technical API reference (this document)
 - **[Flow author reference](docs/copilot-reference.md)** - the authoritative engine and JSON authoring specification for flow authors and AI flow generators (shipped in the package; the Flow Designer's CoPilot reads it from the published version, so change it with the engine)
 - **[Development candidate acceptance](docs/development-release.md)** - reproducible package and cross-repository verification
-- **[System Flows](docs/system-flows.md)** and **[Shopify Flows](docs/shopify-flows.md)** - the bundled flow and tool libraries in `flows/`, step by step
+- **[System Flows](docs/flows/system/README.md)** and **[Shopify Flows](docs/flows/shopify/README.md)** - the bundled flow and tool libraries in `flows/`: a page and a chart per flow, generated from the JSON (`node scripts/flow-docs.mjs`), plus the conventions the system flows share
 
 *For detailed tutorials, step-by-step examples, and comprehensive workflow patterns, see the **[User Guide](user-guide.md)**.*
 
@@ -334,7 +334,7 @@ const body = buildAiRequest(
   `toParameterRequest` / `fromParameterAnswers` (its enum and boolean parameters),
   `freeTextParameters`, `mergeTextParameters`, `INTENT_YES_THRESHOLD`: these map the structured
   intent-detection request to TypeSafe System One and back. The host sends the requests.
-  - Stage 1 asks one yes/no probability per flow and picks the highest if it reaches
+  - (The single-call mapping; two-stage detection uses `buildFlowStage`, below.) Stage 1 asks one yes/no probability per flow and picks the highest if it reaches
     `INTENT_YES_THRESHOLD` (0.5), else `"None"`. Stage 2, for the chosen flow only, asks one per enum
     value and one per boolean parameter. Below the threshold a parameter is omitted (the flow asks for
     it), never set to `false`.
@@ -354,7 +354,10 @@ The host runs either, or both as a hedge, and replies with the canonical JSON: `
 stage 1, `{ "parameters": { … } }` for stage 2. `jsfe/host` exports `buildFlowStage`, `buildParameterStage`
 and the decoders (`decodeFlowLlm`, `decodeFlowSystemOne`, `decodeParametersLlm`, `decodeParametersSystemOne`,
 `isNearMiss`), so a host never interprets an answer itself. Only primaries are ever activated by detection;
-a stage-2 failure starts the flow without its parameters (it asks for them). The default, `'single-call'`,
+a stage-2 failure starts the flow without its parameters (it asks for them). Stage 1's System One request
+is one `choice` over the primaries (`route`) and one `noul` (`any`): does the message start any of them; the
+routed flow starts when `any` reaches 0.5, else `"None"`. Both executors are told that a question starts a flow
+only when it asks for the flow's action, never because it mentions its subject. The default, `'single-call'`,
 is the original single call.
 
 **The reply ranker (contextual DISPATCH, `onResponse: "continue"`):** when a flow's question gets a reply its

package/dist/docs/flow-docs.d.ts

@@ -0,0 +1,13 @@
+export function generateFlowDocs({ sets, root, check, hostRun, log }: {
+    sets: any;
+    root: any;
+    check?: boolean | undefined;
+    hostRun?: {} | undefined;
+    log?: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    } | undefined;
+}): {
+    failed: number;
+};
+//# sourceMappingURL=flow-docs.d.ts.map

package/dist/docs/flow-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-docs.d.ts","sourceRoot":"","sources":["../../src/docs/flow-docs.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;EAqRC"}

package/dist/docs/flow-docs.js

@@ -0,0 +1,523 @@
+/**
+ * Flow docs: one Markdown page per flow (its facts: parameters, calls, tools, callers; and a Mermaid chart of each
+ * declaration: provider, form or compiled form inputs, performer, step list) and a README per set (its call graph and flow
+ * tables), written from the flow JSON itself so a chart can never disagree with a flow. Only the text between
+ * <!-- generated:start --> and <!-- generated:end --> is rewritten; anything else in a page is written by hand and kept.
+ *
+ *   generateFlowDocs({ sets, root, check, hostRun, log }) → { failed }
+ *     sets     [{ key, title, flows, tools, source, how?, skeleton? }]: each set's pages go to <root>/<key>/; pages link
+ *              across sets. skeleton: an entry point's page gets a "What it does" section to write by hand.
+ *     check    write nothing; count a stale page, a page with no flow (orphan) or a broken link as a failure.
+ *     hostRun  { flowId: 'who runs it' } for flows the host starts by id, outside any flow.
+ * A wrapper whose wrapped flow is an entry point inherits that role (the sets are composed that way).
+ * Node only (fs).
+ */
+import fs from 'fs';
+import path from 'path';
+export function generateFlowDocs({ sets, root, check = false, hostRun = {}, log = console.log }) {
+    const SETS = sets;
+    // Which set holds a flow id; a page links to a flow in its own set, or in another set's folder.
+    const setOf = new Map(), flowOf = new Map();
+    for (const s of SETS) {
+        for (const f of s.flows) {
+            if (!setOf.has(f.id)) {
+                setOf.set(f.id, s.key);
+                flowOf.set(f.id, f);
+            }
+            else { /* the first set that defines it */ }
+        }
+    }
+    const known = (id) => setOf.has(id);
+    for (const s of SETS) {
+        for (const f of s.flows) {
+            const w = typeof f.wraps === 'string' ? flowOf.get(f.wraps) : null;
+            if (w && w !== f && w.primary && f.primary === undefined) {
+                f.primary = true;
+                f.inherited = f.wraps;
+            }
+            else { /* own role */ }
+        }
+    }
+    const START = '<!-- generated:start -->', END = '<!-- generated:end -->';
+    // The set whose page is being written: links are relative to its folder.
+    let current = SETS[0] ? SETS[0].key : '';
+    const href = (id) => (setOf.get(id) === current ? `${id}.md` : `../${setOf.get(id)}/${id}.md`);
+    const link = (id) => (known(id) ? `[${id}](${href(id)})${setOf.get(id) === current ? '' : ' (' + setOf.get(id) + ')'}` : id);
+    const esc = (s) => String(s).replace(/"/g, '#quot;').replace(/[\r\n]+/g, ' ').replace(/[<>]/g, (c) => (c === '<' ? '#lt;' : '#gt;')).replace(/[{}]/g, (c) => (c === '{' ? '#123;' : '#125;')).replace(/\|/g, '#124;').replace(/`/g, "'");
+    const cut = (s, n) => { const t = String(s).replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+    const cond = (k) => cut(k.replace(/^condition:\s*/, ''), 70);
+    const safe = (s) => String(s).replace(/[^A-Za-z0-9]+/g, '_');
+    function walk(o, fn) { if (Array.isArray(o)) {
+        o.forEach((x) => walk(x, fn));
+    }
+    else if (o && typeof o === 'object') {
+        fn(o);
+        Object.values(o).forEach((v) => walk(v, fn));
+    }
+    else { /* scalar */ } }
+    const CALL_TYPES = new Set(['call', 'replace', 'reboot']);
+    // Keys of a declaration that name a flow by id: a provider's gate, source and menu flows, a performer's flow, prepare
+    // and present, a form input's sub-form, a call's flow, a wrapper's wrapped flow.
+    const FLOW_KEYS = { flow: 'declared', prepare: 'prepare', present: 'present', form: 'sub-form', wraps: 'wraps' };
+    // A flow is reached by a FLOW step, by a declaration key that names it, by its id passed as a FLOW step's parameter (a
+    // hook run by the flow it is passed to), or by its id written in a SET expression (a default target).
+    function callsOf(flow) {
+        const flows = new Map(), tools = new Set(), add = (id, how) => flows.set(id, (flows.get(id) || new Set()).add(how));
+        const { functions, provides, ...rest } = flow;
+        // A provider's gate and source are called; a menu choice's flow replaces the provider.
+        if (provides) {
+            if (provides.gate && provides.gate.flow) {
+                add(provides.gate.flow, 'call');
+            }
+            else { /* ungated */ }
+            if (provides.source && provides.source.flow) {
+                add(provides.source.flow, 'call');
+            }
+            else { /* no source */ }
+            for (const ch of (provides.menu && provides.menu.choices) || []) {
+                if (ch.flow) {
+                    add(ch.flow, 'replace');
+                }
+                else { /* answers in place */ }
+            }
+        }
+        else { /* not a provider */ }
+        if (typeof flow.wraps === 'string') {
+            add(flow.wraps, 'wraps');
+        }
+        else { /* not a wrapper */ }
+        walk(rest, (s) => {
+            if (s.type === 'FLOW' && typeof s.value === 'string') {
+                add(s.value, s.callType || 'call');
+                for (const [k, v] of Object.entries(s.parameters || {})) {
+                    if (typeof v === 'string' && v !== s.value && known(v)) {
+                        add(v, `${k} of ${s.value}`);
+                    }
+                    else { /* not a flow name */ }
+                }
+            }
+            else if (s.type === 'SET' && typeof s.value === 'string') {
+                for (const m of s.value.matchAll(/'([a-z0-9]+(?:-[a-z0-9]+)+)'/g)) {
+                    if (known(m[1]) && m[1] !== flow.id) {
+                        add(m[1], 'by name');
+                    }
+                    else { /* not a flow id */ }
+                }
+            }
+            else if (!s.type) {
+                for (const [k, how] of Object.entries(FLOW_KEYS)) {
+                    if (typeof s[k] === 'string' && known(s[k])) {
+                        add(s[k], how === 'declared' ? 'call' : how);
+                    }
+                    else { /* not a flow reference */ }
+                }
+            }
+            else { /* not a flow reference */ }
+            // Any other key whose value is a flow id names that flow (a form's or input's validator, an input's after hook,
+            // a confirmation's on_declined).
+            for (const [k, v] of Object.entries(s)) {
+                if (typeof v === 'string' && v !== flow.id && known(v) && !(k in FLOW_KEYS) && !(s.type === 'FLOW' && k === 'value')) {
+                    add(v, k);
+                }
+                else { /* not a flow id */ }
+            }
+            if (s.type === 'CALL-TOOL' && s.tool) {
+                tools.add(s.tool);
+            }
+            else if (!s.type && typeof s.tool === 'string' && s.action) {
+                tools.add(s.tool);
+            }
+            else { /* not a tool */ }
+        });
+        // The engine compiles a form's declined steps into its companion flow <id>-declined.
+        if (flow.form && Array.isArray(flow.form.declined) && flow.form.declined.length && known(flow.id + '-declined')) {
+            add(flow.id + '-declined', 'declined');
+        }
+        else { /* no companion */ }
+        // A function body names a flow by its quoted id (a proposal's on_declined, a default target).
+        for (const body of Object.values(functions || {})) {
+            for (const m of [].concat(body.body || body).join('\n').matchAll(/'([a-z0-9]+(?:-[a-z0-9]+)+)'/g)) {
+                if (known(m[1]) && m[1] !== flow.id) {
+                    add(m[1], 'by name');
+                }
+                else { /* not a flow id */ }
+            }
+        }
+        return { flows, tools };
+    }
+    const callers = new Map();
+    for (const f of SETS.flatMap((s) => s.flows)) {
+        for (const [target, hows] of callsOf(f).flows) {
+            const m = callers.get(target) || new Map();
+            for (const h of hows) {
+                m.set(f.id, (m.get(f.id) || new Set()).add(h));
+            }
+            callers.set(target, m);
+        }
+    }
+    function kindOf(flow) {
+        const k = [];
+        if (flow.provides) {
+            k.push('provider');
+        }
+        else { /* none */ }
+        if (flow.form || (flow.metadata && flow.metadata.formProtocol)) {
+            k.push('form');
+        }
+        else { /* none */ }
+        if (flow.performs) {
+            k.push('performer');
+        }
+        else { /* none */ }
+        if (flow.call) {
+            k.push('call');
+        }
+        else { /* none */ }
+        if (flow.wraps) {
+            k.push('wrapper');
+        }
+        else { /* none */ }
+        if (flow.steps && flow.steps.length) {
+            k.push('steps');
+        }
+        else { /* none */ }
+        if (flow.functions && !k.length) {
+            k.push('function library');
+        }
+        else { /* none */ }
+        if (flow.data && !k.length) {
+            k.push('data');
+        }
+        else { /* none */ }
+        return k;
+    }
+    // A step as a node label; terminal = control leaves this flow there.
+    function describe(s) {
+        const t = s.type;
+        if (t === 'SET') {
+            return { label: 'set ' + s.variable, kind: 'set' };
+        }
+        if (t === 'SAY') {
+            return { label: 'say: ' + cut(s.value || '', 60), kind: 'say' };
+        }
+        if (t === 'SAY-GET') {
+            return { label: 'ask: ' + cut(s.value || '', 60), kind: 'ask' };
+        }
+        if (t === 'CALL-TOOL') {
+            return { label: 'tool: ' + s.tool, kind: 'tool' };
+        }
+        if (t === 'FLOW') {
+            const ct = s.callType || 'call';
+            const q = s.value === 'ask-choice' && s.parameters && typeof s.parameters.question === 'string' ? ' ' + cut(s.parameters.question.replace(/^\{\{(.*)\}\}$/, '$1'), 50) : '';
+            return { label: (ct === 'call' ? 'call ' : ct + ' → ') + s.value + q, kind: ct === 'call' ? 'call' : 'exit' };
+        }
+        if (t === 'END') {
+            return { label: 'end (back to caller)', kind: 'exit' };
+        }
+        if (t === 'RETURN') {
+            return { label: 'return to host / AI', kind: 'exit' };
+        }
+        if (t === 'DISPATCH') {
+            return { label: 'dispatch: intent detection', kind: 'exit' };
+        }
+        return { label: t, kind: 'other' };
+    }
+    // One chart builder for every shape: nodes and edges, with the open ends ("pending") joined to whatever comes next.
+    function builder() {
+        const lines = ['flowchart TD', '   START(("start"))'];
+        let pending = [['START', null]], seq = 0;
+        const id = (p) => `${p}${seq++}`;
+        const node = (nid, d) => {
+            const shape = d.kind === 'exit' ? [`(["`, `"])`] : d.kind === 'tool' ? [`[/"`, `"/]`] : d.kind === 'call' ? [`[["`, `"]]`] : d.kind === 'input' ? [`[/"`, `"\\]`] : d.kind === 'decision' ? [`{"`, `"}`] : [`["`, `"]`];
+            lines.push(`   ${nid}${shape[0]}${esc(d.label)}${shape[1]}`);
+            const cls = { exit: 'endstep', tool: 'toolstep', call: 'flowstep', input: 'inputstep' }[d.kind];
+            if (cls) {
+                lines.push(`   class ${nid} ${cls}`);
+            }
+            else { /* plain */ }
+        };
+        const join = (nid) => { for (const [from, label] of pending.splice(0)) {
+            lines.push(label ? `   ${from} -- "${esc(label)}" --> ${nid}` : `   ${from} --> ${nid}`);
+        } };
+        // Chain one plain node after the open ends.
+        const then = (d) => { const nid = id('n'); node(nid, d); join(nid); if (d.kind !== 'exit') {
+            pending.push([nid, null]);
+        }
+        else { /* leaves */ } return nid; };
+        // A fan: one decision, one labelled branch per entry, each branch's end left open (or closed when it leaves).
+        const fan = (label, branches) => {
+            const did = id('d');
+            node(did, { label, kind: 'decision' });
+            join(did);
+            for (const [edge, d] of branches) {
+                const bid = id('b');
+                node(bid, d);
+                lines.push(`   ${did} -- "${esc(edge)}" --> ${bid}`);
+                if (d.kind !== 'exit') {
+                    pending.push([bid, null]);
+                }
+                else { /* leaves */ }
+            }
+        };
+        // A step list: consecutive SETs collapse into one node; a CASE is a diamond with one edge per branch.
+        const steps = (list) => {
+            const groups = [];
+            for (const s of list || []) {
+                const last = groups[groups.length - 1];
+                if (s.type === 'SET' && last && last.set) {
+                    last.vars.push(s.variable);
+                }
+                else if (s.type === 'SET') {
+                    groups.push({ set: true, vars: [s.variable] });
+                }
+                else {
+                    groups.push({ step: s });
+                }
+            }
+            const onFail = (nid, s) => {
+                if (s.type !== 'CALL-TOOL' || !s.onFail) {
+                    return;
+                }
+                else { /* a failure path */ }
+                const fid = nid + 'f', d = describe(s.onFail);
+                node(fid, d);
+                lines.push(`   ${nid} -- "fails" --> ${fid}`);
+                if (d.kind !== 'exit') {
+                    pending.push([fid, null]);
+                }
+                else { /* leaves the flow */ }
+            };
+            for (const g of groups) {
+                if (g.set) {
+                    then({ label: 'set ' + cut([...new Set(g.vars)].filter((v) => v !== 'noop').join(', ') || 'noop', 70), kind: 'set' });
+                    continue;
+                }
+                else { /* a step */ }
+                const s = g.step;
+                if (s.type === 'CASE') {
+                    const cid = id('c');
+                    lines.push(`   ${cid}{"case"}`);
+                    join(cid);
+                    Object.entries(s.branches || {}).forEach(([k, b]) => {
+                        const edge = k === 'default' ? 'else' : cond(k);
+                        const noop = b.type === 'SET' && /^noop/.test(b.variable || '');
+                        if (noop) {
+                            pending.push([cid, edge]);
+                            return;
+                        }
+                        else { /* a real branch */ }
+                        const bid = id('b'), d = describe(b);
+                        node(bid, d);
+                        lines.push(`   ${cid} -- "${esc(edge)}" --> ${bid}`);
+                        if (d.kind !== 'exit') {
+                            pending.push([bid, null]);
+                        }
+                        else { /* leaves the flow */ }
+                        onFail(bid, b);
+                    });
+                }
+                else {
+                    const nid = then(describe(s));
+                    onFail(nid, s);
+                }
+            }
+        };
+        const done = () => {
+            if (pending.length) {
+                lines.push('   DONE(["end (back to caller)"])', '   class DONE endstep');
+                join('DONE');
+            }
+            else { /* every path leaves explicitly */ }
+            lines.push('   classDef endstep fill:#eef,stroke:#669', '   classDef toolstep fill:#efe,stroke:#696', '   classDef flowstep fill:#fef6e0,stroke:#b80', '   classDef inputstep fill:#f3eefc,stroke:#75a');
+            return '```mermaid\n' + lines.join('\n') + '\n```';
+        };
+        return { then, fan, steps, done };
+    }
+    function providerChart(p) {
+        const c = builder();
+        if (p.gate && p.gate.flow) {
+            c.then({ label: `gate: call ${p.gate.flow} unless ${(p.gate.verified || []).join(' and ')}`, kind: 'call' });
+        }
+        else { /* ungated */ }
+        if (p.source && p.source.flow) {
+            c.then({ label: `source: call ${p.source.flow} → ${p.source.result || ''}${p.source.refresh ? ' (' + p.source.refresh + ')' : ''}`, kind: 'call' });
+        }
+        else { /* no source */ }
+        const facts = (p.facts || []).map((f) => f.key);
+        c.then({ label: `say facts: ${cut(facts.join(', '), 80)}${p.default ? ' (default ' + p.default + ')' : ''}`, kind: 'say' });
+        if (p.menu && (p.menu.choices || []).length) {
+            c.fan('menu', [...p.menu.choices.map((ch) => [cut((ch.phrases || []).slice(0, 3).join(' / ') || ch.key, 40), { label: `${ch.key} → ${ch.flow || ''}`, kind: ch.flow ? 'exit' : 'say' }]),
+                ...(p.menu.done ? [[cut((p.menu.done.phrases || []).slice(0, 3).join(' / '), 40), { label: 'done', kind: 'exit' }]] : [])]);
+        }
+        else { /* no menu */ }
+        return c.done();
+    }
+    function formChart(fm) {
+        const c = builder();
+        if (fm.before && fm.before.length) {
+            c.steps(fm.before);
+        }
+        else { /* nothing before */ }
+        for (const i of fm.inputs || []) {
+            const extra = [i.when ? 'when ' + cut(i.when, 40) : '', i.form ? 'form ' + i.form : '', i.profile && i.profile.kind ? i.profile.kind : ''].filter(Boolean).join(' · ');
+            c.then({ label: `${i.name}${i.label ? ' (' + i.label + ')' : ''}${extra ? ': ' + extra : ''}`, kind: 'input' });
+        }
+        if (fm.confirm) {
+            c.then({ label: 'confirm', kind: 'decision' });
+        }
+        else { /* no confirmation */ }
+        if (fm.after && fm.after.length) {
+            c.steps(fm.after);
+        }
+        else { /* nothing after */ }
+        return c.done();
+    }
+    function performsChart(flow) {
+        const c = builder();
+        if (flow.prepare) {
+            c.then({ label: 'prepare: call ' + flow.prepare, kind: 'call' });
+        }
+        else { /* none */ }
+        if (flow.present) {
+            c.then({ label: 'present: call ' + flow.present, kind: 'call' });
+        }
+        else { /* none */ }
+        c.fan('action', flow.performs.map((a) => [cut(a.when || a.action, 50), { label: `${a.action} (${a.effect}${a.confirm ? ', confirmed' : ''}): ${a.flow ? 'flow ' + a.flow : ''}${a.tool ? ' tool ' + a.tool : ''}`, kind: a.tool ? 'tool' : 'call' }]));
+        if (flow.project && flow.project.length) {
+            c.steps(flow.project);
+        }
+        else { /* no projection */ }
+        return c.done();
+    }
+    function stepsChart(list) { const c = builder(); c.steps(list); return c.done(); }
+    function facts(flow) {
+        const { flows, tools } = callsOf(flow);
+        const params = (flow.parameters || []).map((p) => `\`${p.name}\`${p.enum ? ' (' + p.enum.join(' / ') + ')' : ''}: ${p.description || ''}`);
+        const out = [
+            `**${flow.name || flow.id}** · \`${flow.id}\`${flow.version ? ' · version ' + flow.version : ''}${flow.primary ? ' · **entry point** (intent detection can start it' + (flow.inherited ? '; primary inherited from ' + flow.inherited : '') + ')' : ' · worker (called by other flows)'} · ${kindOf(flow).join(' + ')}${flow.scope ? ' · ' + flow.scope + ' scope' : ''}`,
+            '',
+            `> ${flow.description || ''}`,
+            '',
+            `- **Parameters:** ${params.length ? '\n  - ' + params.join('\n  - ') : 'none'}`,
+            `- **Calls:** ${flows.size ? [...flows].map(([id, cts]) => `${link(id)} (${[...cts].join(', ')})`).join(', ') : 'no other flow'}`,
+            `- **Tools:** ${tools.size ? [...tools].map((t) => '`' + t + '`').join(', ') : 'none'}`,
+            `- **Called by:** ${[...(flow.primary ? ['intent detection'] : []), ...(hostRun[flow.id] ? [hostRun[flow.id]] : []), ...[...(callers.get(flow.id) || new Map())].map(([id, hows]) => link(id) + ([...hows].some((h) => !CALL_TYPES.has(h)) ? ` (${[...hows].filter((h) => !CALL_TYPES.has(h)).join(', ')})` : ''))].join(', ') || 'nothing (unreachable)'}`,
+        ];
+        if (flow.functions) {
+            out.push(`- **Functions:** ${Object.keys(flow.functions).map((n) => '`' + n + '`').join(', ')}`);
+        }
+        else { /* none */ }
+        if (flow.provides) {
+            out.push('', '### Provider', '', ...(flow.provides.facts || []).map((f) => `- fact \`${f.key}\`: ${f.description || ''}${f.path ? ' (from `' + f.path + '`)' : ''}`), '', providerChart(flow.provides));
+        }
+        else { /* not a provider */ }
+        if (flow.form) {
+            out.push('', '### Form', '', formChart(flow.form));
+        }
+        else { /* not a form */ }
+        // A form the jsfe SDK compiled (the system set) carries its inputs as a variable; its steps are the engine's run-form loop.
+        const compiled = flow.metadata && flow.metadata.formProtocol && flow.variables && flow.variables.inputs && Array.isArray(flow.variables.inputs.value) ? flow.variables.inputs.value : null;
+        if (!flow.form && compiled && compiled.length) {
+            out.push('', '### Form inputs', '', formChart({ inputs: compiled }));
+        }
+        else { /* not a compiled form */ }
+        if (flow.performs) {
+            out.push('', '### Performs', '', ...flow.performs.map((a) => `- \`${a.action}\` (${a.effect}): ${a.reconcile && a.reconcile.policy ? cut(a.reconcile.policy, 300) : ''}`), '', performsChart(flow));
+        }
+        else { /* not a performer */ }
+        if (flow.call) {
+            out.push('', '### Call', '', `Runs ${link(flow.call.flow)} with its parameters.`);
+        }
+        else { /* not a call */ }
+        if (flow.wraps) {
+            out.push('', '### Wraps', '', `Runs ${link(flow.wraps)} with this set's wording.`);
+        }
+        else { /* not a wrapper */ }
+        if (flow.steps && flow.steps.length) {
+            out.push('', '### Steps', '', stepsChart(flow.steps));
+        }
+        else { /* no steps */ }
+        return out.join('\n');
+    }
+    function upsert(file, title, generated, skeleton) {
+        const block = `${START}\n${generated}\n${END}`;
+        const old = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+        const next = old && old.includes(START) && old.includes(END)
+            ? old.slice(0, old.indexOf(START)) + block + old.slice(old.indexOf(END) + END.length)
+            : `# ${title}\n\n${block}\n${skeleton ? '\n' + skeleton : ''}`;
+        if (next === old) {
+            return false;
+        }
+        else if (check) {
+            log(`STALE  ${path.relative(root, file)}`);
+            return true;
+        }
+        else {
+            fs.writeFileSync(file, next);
+            return true;
+        }
+    }
+    let failed = 0;
+    for (const set of SETS) {
+        current = set.key;
+        const dir = path.join(root, set.key), ids = new Set(set.flows.map((f) => f.id));
+        fs.mkdirSync(dir, { recursive: true });
+        let changed = 0;
+        // ai-ar-ql's entry points carry a written part; elsewhere a flow's generated facts are its documentation.
+        const SKELETON = '## What it does\n\n_To be written._\n';
+        for (const f of set.flows) {
+            if (upsert(path.join(dir, f.id + '.md'), f.name || f.id, facts(f), set.skeleton && f.primary ? SKELETON : '')) {
+                changed++;
+            }
+            else { /* unchanged */ }
+        }
+        const entries = set.flows.filter((f) => f.primary), workers = set.flows.filter((f) => !f.primary);
+        // The README's graph shows what intent detection can start and the flows each entry point reaches directly.
+        const graph = ['flowchart LR'];
+        for (const f of entries) {
+            graph.push(`   ${safe(f.id)}(["${esc(f.name || f.id)} · ${f.id}"])`);
+            for (const [t, hows] of callsOf(f).flows) {
+                const target = ids.has(t) ? `${safe(t)}["${esc(t)}"]` : `x_${safe(t)}[("${esc(t)} (${setOf.get(t) || 'not in this checkout'})")]`;
+                graph.push(`   ${safe(f.id)} ${[...hows].some((h) => CALL_TYPES.has(h)) ? '-->' : '-.->'} ${target}`);
+            }
+        }
+        const table = (list) => ['| flow | kind | what it is |', '|---|---|---|', ...list.map((f) => `| [${f.id}](${f.id}.md) | ${kindOf(f).join(' + ')} | ${cut(f.description || '', 140).replace(/\|/g, '/')} |`)].join('\n');
+        const index = [`${set.flows.length} flows (${entries.length} entry points), ${set.tools.length} tools. The graph shows each entry point and the flows it reaches directly; a dotted arrow is a flow named rather than called (a hook, a prepare or present step, a default target). Each flow page charts its declarations: a provider (gate, source, facts, menu), a form (inputs in order, then its after steps), a performer (prepare, present, action) and any step list.`, '', '```mermaid', graph.join('\n'), '```', '', '## Entry points', '', entries.length ? table(entries) : 'None: intent detection starts no flow of this set directly.', '', '## Workers', '', table(workers)].join('\n');
+        const others = SETS.filter((s) => s !== set);
+        const readme = `## How to read these docs\n\nEach flow page has a generated part (facts and charts, rewritten from ${set.source})${set.skeleton ? ' and, for entry points, a written part' : ''}.${set.how ? ' ' + set.how : ''}${others.length ? ' The other sets: ' + others.map((s) => `[${s.key}](../${s.key}/README.md)`).join(', ') + '.' : ''}\n`;
+        if (upsert(path.join(dir, 'README.md'), set.title, index, readme)) {
+            changed++;
+        }
+        else { /* unchanged */ }
+        // A page whose flow is gone (renamed, deleted) is wrong about the flow set: it must go too.
+        const orphans = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'README.md' && !ids.has(f.slice(0, -3)));
+        for (const o of orphans) {
+            log(`ORPHAN ${set.key}/${o}: no ${set.key} flow '${o.slice(0, -3)}'`);
+        }
+        if (check) {
+            log(changed || orphans.length ? `${path.relative(process.cwd(), dir) || set.key}: ${changed} stale, ${orphans.length} orphan: run the generator` : `${path.relative(process.cwd(), dir) || set.key}: ${set.flows.length} flow docs + README current`);
+        }
+        else {
+            log(`${path.relative(process.cwd(), dir) || set.key}: ${set.flows.length} flow docs + README, ${changed} written${orphans.length ? `; ${orphans.length} orphan page(s) to delete` : ''}`);
+        }
+        failed += check ? changed + orphans.length : orphans.length;
+    }
+    // Links are checked once every set's pages exist: a page links into the other sets' folders.
+    for (const set of SETS) {
+        const dir = path.join(root, set.key);
+        const broken = [];
+        for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+            for (const m of fs.readFileSync(path.join(dir, f), 'utf8').matchAll(/\]\(((?:\.\.\/[a-z0-9-]+\/)?[a-z0-9:-]+\.md)(?:#[^)]*)?\)/gi)) {
+                if (!fs.existsSync(path.join(dir, m[1]))) {
+                    broken.push(`${set.key}/${f} → ${m[1]}`);
+                }
+                else { /* exists */ }
+            }
+        }
+        for (const b of broken) {
+            log(`BROKEN ${b}`);
+        }
+        failed += broken.length;
+    }
+    return { failed };
+}

package/dist/forms/flows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/forms/flows.js"],"names":[],"mappings":"AA6HA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4DC;AACD;;;GAGG;AACH;;;;;;EAGC;AAueD,wHAAwH;AACxH,wEAaC;AACD,4FAA4F;AAC5F;;;EAYC;AACD,sGAAsG;AACtG;;;EAOC;AAnqBM,6CAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA41B9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOG"}
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/forms/flows.js"],"names":[],"mappings":"AAqIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4DC;AACD;;;GAGG;AACH;;;;;;EAGC;AAueD,wHAAwH;AACxH,wEAaC;AACD,4FAA4F;AAC5F;;;EAYC;AACD,sGAAsG;AACtG;;;EAOC;AA3qBM,6CAAuG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAo2B9G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAOG"}

package/dist/forms/flows.js

@@ -40,6 +40,13 @@ const optionalIncomplete = (id, condition, form, reason) => WHEN(id, `(${conditi
 export const textValue = (text) => (String(text).includes('{{') ? String(text) : JSON.stringify(String(text)));
 // Keys for a numbered menu: 1..9 without 8, the language key (owner rule 2026-10-19).
 const KEYS_JS = "(function (n) { var k = []; for (var i = 1; k.length < n && i <= 9; i++) { if (i !== 8) { k.push(String(i)); } } return k; })";
+// Month names a card expiration may be said with (English, Spanish), longest first so 'sept' is not read as 'sep'.
+const MONTH_NAMES = [['september', 9], ['septiembre', 9], ['setiembre', 9], ['february', 2], ['febrero', 2], ['november', 11], ['noviembre', 11],
+    ['december', 12], ['diciembre', 12], ['january', 1], ['octubre', 10], ['october', 10], ['august', 8], ['agosto', 8], ['enero', 1], ['marzo', 3],
+    ['march', 3], ['abril', 4], ['april', 4], ['junio', 6], ['julio', 7], ['mayo', 5], ['june', 6], ['july', 7], ['sept', 9], ['jan', 1], ['ene', 1],
+    ['feb', 2], ['mar', 3], ['apr', 4], ['abr', 4], ['may', 5], ['jun', 6], ['jul', 7], ['aug', 8], ['ago', 8], ['sep', 9], ['oct', 10], ['nov', 11],
+    ['dec', 12], ['dic', 12]];
+const MONTH_RE = MONTH_NAMES.map(([n]) => n).join('|');
 // ── field presets (decision 2A): ONE library, read only by collect-input ─────────────────────────────────────────
 // A form uses a preset by name ({ name, field }); keys it gives override the preset's (e.g. a tenant's account pattern).
 export const FIELD_PRESETS = {
@@ -75,8 +82,9 @@ export const FIELD_PRESETS = {
         retry: 'Please say or enter the full card number.', retry_es: 'Por favor diga o ingrese el número completo de su tarjeta.',
         retry_text: 'Please type the full card number.', retry_text_es: 'Por favor escriba el número completo de su tarjeta.' },
     card_expiration: { label: 'expiration date', label_es: 'fecha de vencimiento',
-        // MM0YY: a zero said between month and year ("020 28", prod 2026-10-25 14:10, was taken for the billing ZIP)
-        profile: { kind: 'pattern', regex: '\\b(0?[1-9]|1[0-2])\\s*(?:/|-|\\s|de)?\\s*(?:20)?(\\d{2})\\b|\\b0[1-9]0\\s+(?:20)?\\d{2}\\b' }, digits: { min: 3, max: 6 },
+        // MM0YY: a zero said between month and year ("020 28", prod 2026-10-25 14:10, was taken for the billing ZIP).
+        // Up to two words between month and year ("el mes 06 año 31", prod 2026-10-28 21:54, was asked again); a month by name.
+        profile: { kind: 'pattern', regex: `\\b(0?[1-9]|1[0-2]|${MONTH_RE})\\.?(?:\\s*(?:/|-|del?|año|ano|year|of)(?=[\\s\\d])){0,2}\\s*(?:20)?(\\d{2})\\b|\\b0[1-9]0\\s+(?:20)?\\d{2}\\b` }, digits: { min: 3, max: 6 },
         validator: 'validate-card-expiration',
         question: 'What is the expiration date, month and year?', question_es: '¿Cuál es la fecha de vencimiento, mes y año?',
         retry: 'Please say or enter the expiration as four digits, month then year, like 0 9 2 8.', retry_es: 'Por favor diga o ingrese el vencimiento en cuatro dígitos, mes y año, por ejemplo 0 9 2 8.',
@@ -635,9 +643,9 @@ const validators = [
         parameters: [{ name: 'input', type: 'string', description: 'input name' }, { name: 'value', type: 'string', description: 'the reading' }],
         steps: [SIDE('vcn_check', "(cargo.inputCheck = validateCardNumber(value) ? { ok: true, value: String(value).replace(/\\D/g, '') } : { ok: false, message: \"That card number doesn't look right.\", message_es: 'Ese número de tarjeta no parece correcto.' }, true)")] },
     { id: 'validate-card-expiration', name: 'ValidateCardExpiration', version: '1.0.0', scope: 'isolated',
-        description: 'Validator: month and year, a real month, not expired (validateExpiration). Normalizes to MMYY. Params: input, value.',
+        description: 'Validator: month (a number or its English or Spanish name) and year, a real month, not expired (validateExpiration). Normalizes to MMYY. Params: input, value.',
         parameters: [{ name: 'input', type: 'string', description: 'input name' }, { name: 'value', type: 'string', description: 'the reading' }],
-        steps: [SIDE('vce_check', "(function (v) { var m = /^(0?[1-9]|1[0-2])\\D*(?:20)?(\\d{2})$/.exec(String(v).replace(/\\s+/g, '').replace(/de/gi, '')) || /^(\\d{2})(\\d{2})$/.exec(String(v).replace(/\\D/g, '')) || /^(0[1-9])0(\\d{2})$/.exec(String(v).replace(/\\D/g, '')); var mm = m ? ('0' + m[1]).slice(-2) : ''; var yy = m ? m[2] : ''; cargo.inputCheck = m && validateExpiration(mm, yy) ? { ok: true, value: mm + yy } : { ok: false, message: \"That expiration date doesn't look right.\", message_es: 'Esa fecha de vencimiento no parece correcta.' }; return true; })(value)")] },
+        steps: [SIDE('vce_check', "(function (v) { var names = " + JSON.stringify(MONTH_NAMES.map(([n]) => n)) + "; var nums = " + JSON.stringify(MONTH_NAMES.map(([, k]) => k)) + "; var w = new RegExp('\\\\b(' + names.join('|') + ')\\\\b', 'i').exec(String(v)); if (w) { v = String(v).replace(w[0], ' ' + nums[names.indexOf(w[1].toLowerCase())] + ' '); } var m = /^(0?[1-9]|1[0-2])\\D*(?:20)?(\\d{2})$/.exec(String(v).replace(/\\s+/g, '').replace(/de/gi, '')) || /^(\\d{2})(\\d{2})$/.exec(String(v).replace(/\\D/g, '')) || /^(0[1-9])0(\\d{2})$/.exec(String(v).replace(/\\D/g, '')); var mm = m ? ('0' + m[1]).slice(-2) : ''; var yy = m ? m[2] : ''; cargo.inputCheck = m && validateExpiration(mm, yy) ? { ok: true, value: mm + yy } : { ok: false, message: \"That expiration date doesn't look right.\", message_es: 'Esa fecha de vencimiento no parece correcta.' }; return true; })(value)")] },
     { id: 'validate-card-cvv', name: 'ValidateCardCvv', version: '1.0.0', scope: 'isolated',
         description: 'Validator: the security code has the length of its card brand, 4 digits for American Express (34, 37) and 3 for every other brand; with no card number yet, 3 or 4. Params: input, value, values.',
         parameters: [{ name: 'input', type: 'string', description: 'input name' }, { name: 'value', type: 'string', description: 'the reading' }, { name: 'values', type: 'object', description: "the form's values, for the card number" }],

package/dist/helpers/answer.d.ts

@@ -31,7 +31,7 @@ export function isAmountAnswer(input: any): boolean;
  * answer was taken, so "pagar cuenta 50, ciento treinta y cuatro…" paid $50, "$10 con 18 centavos" paid $10.00 and an
  * offer read back with "terminada en 2 4 8 6" paid $2. Numbers that name an account, card, code or ZIP, and digits spoken
  * one by one, are not amounts; two different remaining numbers are ambiguous unless exactly one is marked as money ($,
- * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50. Amounts said only in words are NaN (not parsed yet).
+ * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50, "157 95" is $157.95. Amounts said only in words are NaN (not parsed yet).
  */
 export function amountInAnswer(input: any): number;
 /** Internal numeric evidence shared by the opt-in money reader; legacy results stay unchanged. */

package/dist/helpers/answer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/helpers/answer.js"],"names":[],"mappings":"AAsNA;;;GAGG;AACH,wEAkBC;AAED;;;;GAIG;AACH,mDAIC;AAED,+HAA+H;AAC/H,oDAIC;AAcD,2GAA2G;AAC3G,uDAGC;AAOD;;;;;GAKG;AACH,+DAUC;AAKD;;;;GAIG;AACH,oDAEC;AAiBD;;;;;;GAMG;AACH,mDAAmF;AAEnF,kGAAkG;AAClG;;;EAmCC;AAUD;;;;;;;;;GASG;AACH,6EA4GC;;;;;;;;AAncD,qCAKwE"}
+{"version":3,"file":"answer.d.ts","sourceRoot":"","sources":["../../src/helpers/answer.js"],"names":[],"mappings":"AAsNA;;;GAGG;AACH,wEAkBC;AAED;;;;GAIG;AACH,mDAIC;AAED,+HAA+H;AAC/H,oDAIC;AAcD,2GAA2G;AAC3G,uDAGC;AAOD;;;;;GAKG;AACH,+DAUC;AAKD;;;;GAIG;AACH,oDAEC;AAqBD;;;;;;GAMG;AACH,mDAAmF;AAEnF,kGAAkG;AAClG;;;EAoCC;AAUD;;;;;;;;;GASG;AACH,6EA4GC;;;;;;;;AAxcD,qCAKwE"}

package/dist/helpers/answer.js

@@ -330,12 +330,16 @@ const DOLLARS_AND_CENTS = /(\d+)\s*(?:dollars?|d[oó]lar(?:es)?|bucks?)?\s*(?:an
 // cents is allowed ("171 con un 06").
 const CENTS_JOINERS = ['con', 'and']; // 'and' too (owner 2026-10-18: "87 and 21" = $87.21)
 const DOLLARS_JOINED_CENTS = /(\$\s*)?(\d+)(\s*(?:dollars?|d[oó]lar(?:es)?|bucks?))?\s*(and|con|y)\s*(?:un\s+)?(\d{1,2})\b(?!\s*\d)/gi;
+// Dollars and two cent digits said with no word between them, as speech-to-text writes "ciento cincuenta y siete noventa y
+// cinco": "157 95", "$157 95", "1 50" (owner 2026-10-29; prod 10-28 callers re-asked). Never after a decimal or before more
+// digits, and never two-digit dollars: "95 52" is four digits, a card's last four read in pairs.
+const DOLLARS_SPACE_CENTS = /(?<![\d.,])(\$\s*)?(\d|\d{3,})\s+(\d{2})(?![\d.,]|\s*(?:dollars?|d[oó]lar(?:es)?|bucks?|cents?|centavos?)\b)/gi;
 /**
  * The amount an answer names, or NaN when it names none or is ambiguous. Prod replay 2026-10-14: the first number in the
  * answer was taken, so "pagar cuenta 50, ciento treinta y cuatro…" paid $50, "$10 con 18 centavos" paid $10.00 and an
  * offer read back with "terminada en 2 4 8 6" paid $2. Numbers that name an account, card, code or ZIP, and digits spoken
  * one by one, are not amounts; two different remaining numbers are ambiguous unless exactly one is marked as money ($,
- * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50. Amounts said only in words are NaN (not parsed yet).
+ * dollars, cents or decimals). "50 cents" alone is $0.50; "82 dollars and 50" and "82 con 50" are $82.50, "157 95" is $157.95. Amounts said only in words are NaN (not parsed yet).
  */
 export function amountInAnswer(input) { return numericAmountReading(input).value; }
 /** Internal numeric evidence shared by the opt-in money reader; legacy results stay unchanged. */
@@ -358,7 +362,8 @@ export function numericAmountReading(input) {
     else {
         // no dollars-and-cents phrase
     }
-    t = t.replace(IDENTIFIER_NUMBER, ' ').replace(SPELLED_DIGITS, ' ').replace(DOLLARS_JOINED_CENTS, (m, sign, d, word, joiner, c) => (sign || word || (CENTS_JOINERS.includes(joiner.toLowerCase()) && c.length === 2) ? ` $${d}.${c.padStart(2, '0')} ` : m));
+    t = t.replace(IDENTIFIER_NUMBER, ' ').replace(SPELLED_DIGITS, ' ').replace(DOLLARS_JOINED_CENTS, (m, sign, d, word, joiner, c) => (sign || word || (CENTS_JOINERS.includes(joiner.toLowerCase()) && c.length === 2) ? ` $${d}.${c.padStart(2, '0')} ` : m))
+        .replace(DOLLARS_SPACE_CENTS, (m, sign, d, c) => ` $${d}.${c} `);
     const found = [...t.matchAll(/(\$\s*)?(\d+(?:\.\d{1,2})?)(\s*(?:dollars?|d[oó]lar(?:es)?|bucks?|cents?|centavos?)\b)?/gi)]
         .map((m) => ({ v: parseFloat(m[2]), marked: !!(m[1] || m[3] || m[2].includes('.')), cents: !m[1] && /cent/i.test(m[3] || '') }));
     const values = [...new Set(found.map((f) => f.v))];

package/dist/helpers/money.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/helpers/money.js"],"names":[],"mappings":"AAIA,gHAAgH;AAChH,wDAGC;AAiBD;8FAC8F;AAC9F,oEAIC;AACD,+FAA+F;AAC/F,0DAEC;AACD;oGACoG;AACpG,4DAGC;AAWD;;;GAGG;AACH,+DAYC;AACD,4FAA4F;AAC5F,iEAAsG"}
+{"version":3,"file":"money.d.ts","sourceRoot":"","sources":["../../src/helpers/money.js"],"names":[],"mappings":"AAIA,gHAAgH;AAChH,wDAGC;AAkBD;8FAC8F;AAC9F,oEAIC;AACD,+FAA+F;AAC/F,0DAEC;AACD;oGACoG;AACpG,4DAGC;AAWD;;;GAGG;AACH,+DAYC;AACD,4FAA4F;AAC5F,iEAAsG"}

package/dist/helpers/money.js

@@ -8,8 +8,9 @@ export function validateMoneyOptions(options) {
     return options;
 }
 // This is an input grammar, not a conversation classifier. Anything outside one complete
-// monetary answer belongs to DISPATCH, including refusals, corrections with context and reports.
-const NUMERIC_MONEY = /^(?:\$\s*)?(?:\d{1,3}(?:[,.]\d{3})+|\d+)(?:[.,]\d{1,2})?(?:\s*(?:dollars?|d[oó]lar(?:es)?|bucks?))?(?:\s*(?:and|con|y)\s*(?:un\s*)?\d{1,2}(?:\s*(?:cents?|centavos?))?)?$|^\d{1,2}\s*(?:cents?|centavos?)$/i;
+// monetary answer belongs to DISPATCH, including refusals, corrections with context and reports. "157 95" is dollars and
+// cents said with no word between them (owner 2026-10-29); "95 52" is not (a card's last four read in pairs).
+const NUMERIC_MONEY = /^(?:\$\s*)?(?:\d{1,3}(?:[,.]\d{3})+|\d+)(?:[.,]\d{1,2})?(?:\s*(?:dollars?|d[oó]lar(?:es)?|bucks?))?(?:\s*(?:and|con|y)\s*(?:un\s*)?\d{1,2}(?:\s*(?:cents?|centavos?))?)?$|^\d{1,2}\s*(?:cents?|centavos?)$|^(?:\$\s*)?(?:\d|\d{3,})\s+\d{2}$/i;
 const PAYMENT_PREFIX = /^(?:(?:i (?:want to|would like to|can|am able to|will) |i['’]d like to )?pay|(?:quiero |quisiera |puedo |s[ií] puedo |voy a )?(?:pagar|abonar)|(?:no,?\s+)?make it)\s*(?=\$|\d|[a-záéíóúüñ])/i;
 const ACCOUNT_PREFIX = /^(?:(?:sub[ -]?account|subcuenta|cuenta)\s+\d{1,8}\s*,\s*)/i;
 const DIGIT_WORD = '(?:zero|one|two|three|four|five|six|seven|eight|nine|cero|uno|dos|tres|cuatro|cinco|seis|siete|ocho|nueve)';

package/dist/host/intent-stages.d.ts

@@ -23,8 +23,6 @@
 import type { FlowParameterDefinition } from '../index.js';
 /** A noul at or above this is a yes. */
 export declare const STAGE_YES_THRESHOLD = 0.5;
-/** Stage 1, System One: two top flows that together reach this pick the higher one (prod 10-17). */
-export declare const STAGE_PAIR_SUM = 0.7;
 export interface StageTurn {
     role: 'user' | 'assistant';
     content: string;
@@ -52,9 +50,9 @@ export interface StageSystemOne<I> {
     questions: Record<string, unknown>;
     index: I[];
 }
+/** Stage 1, System One: `route` is the choice among the flows, `any` whether the message starts one at all. */
 export interface FlowQuestionRef {
-    id: string;
-    flow: number;
+    id: 'route' | 'any';
 }
 export type ParameterQuestionRef = {
     id: string;
@@ -99,26 +97,34 @@ export type StageSystemOneAnswers = Record<string, {
 } | undefined> | undefined;
 /** The flow's own parameters, never asked of the user. */
 export declare const isInternalParameter: (p: StageParameter | FlowParameterDefinition) => boolean;
-/** Stage 1's instructions for both executors. `flows` are the primaries offered. */
+/**
+ * Stage 1's instructions for both executors. `flows` are the primaries offered.
+ *
+ * System One gets ONE request with two questions over the same list: `route`, a `choice` among the flows (each
+ * option's criterion is its description, so every flow is weighed against the others), and `any`, a `noul`
+ * asking whether the message starts any of them. TypeSafe documents that a "none of the above" option may not
+ * work well and advises the companion noul.
+ */
 export declare function buildFlowStage(input: string, conversation: StageTurn[], flows: StageFlow[]): FlowStageRequest;
 /** A text model's stage-1 answer as the canonical reply; throws when it names no offered flow. */
 export declare function decodeFlowLlm(text: string, stage: FlowStageRequest): {
     flowName: string;
 };
 /**
- * System One's stage-1 answers as the canonical reply, with the top three scores (for logs and a host's hedge
- * policy) and `pair` when two close candidates picked the higher. Throws if any question is unanswered.
+ * System One's stage-1 answers as the canonical reply. `any` at or above the threshold starts the flow `route`
+ * chose; below it, "None". `scores` are the top three flows by the chance that each is the one started,
+ * any × its route probability (for logs and the host's near-miss hedge); `any` is logged with them. Throws when
+ * either answer is missing or names no offered flow.
  */
-export declare function decodeFlowSystemOne(answers: StageSystemOneAnswers, stage: FlowStageRequest, { threshold, pairSum }?: {
+export declare function decodeFlowSystemOne(answers: StageSystemOneAnswers, stage: FlowStageRequest, { threshold }?: {
     threshold?: number | undefined;
-    pairSum?: number | undefined;
 }): {
     flowName: string;
     scores: {
         name: string;
         p: number;
     }[];
-    pair: boolean;
+    any: number;
 };
 /**
  * A System One "None" that is a near miss: the chance that at least one of its two top flows applies,

package/dist/host/intent-stages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-stages.d.ts","sourceRoot":"","sources":["../../src/host/intent-stages.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"intent-stages.d.ts","sourceRoot":"","sources":["../../src/host/intent-stages.ts"],"names":[],"mappings":"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"}

package/dist/host/intent-stages.js

@@ -22,11 +22,11 @@
  */
 /** A noul at or above this is a yes. */
 export const STAGE_YES_THRESHOLD = 0.5;
-/** Stage 1, System One: two top flows that together reach this pick the higher one (prod 10-17). */
-export const STAGE_PAIR_SUM = 0.7;
 // ── the rules: written once, rendered for both executors ─────────────────────────────────────────────
 const FLOW_TRUE = "The latest message, read with the conversation, is what the workflow's description says should start it: the user asks for its action or information, or raises the problem it exists to handle. Also when it accepts the assistant's offer in the conversation to start or resume it (assistant: \"Shall I try the payment again?\" → user: \"yes\").";
 const FLOW_FALSE = "It only shares a topic with the workflow, is not what the workflow's description covers, or is a greeting, an acknowledgement or a fragment that asks for nothing.";
+/** A question usually asks for information the assistant gives itself; it is weighed before it is taken as a trigger. */
+const QUESTION_RULE = "A question usually asks for information the assistant can give itself. Consider it carefully: it starts a workflow only when it asks for that workflow's action or raises the problem it exists to handle, never because it mentions the workflow's subject (\"can I pay with this card at a store?\" asks how the card is used, not to make a payment).";
 const PARAMETER_RULES = [
     'Give a value only when the user gave it, in the latest message or earlier in the conversation. Never guess.',
     "Write it as the parameter's rule says; otherwise the value alone, in the user's words (never the whole sentence around it).",
@@ -49,33 +49,45 @@ const stateOf = (conversation, input, instructions) => ({
 });
 const jsonTail = (schema) => `\n\n<json-schema>\n${JSON.stringify(schema)}\n</json-schema>\n\nRespond ONLY with valid JSON matching the schema. No other text.`;
 // ── stage 1 ───────────────────────────────────────────────────────────────────────────────────────────
-/** Stage 1's instructions for both executors. `flows` are the primaries offered. */
+/**
+ * Stage 1's instructions for both executors. `flows` are the primaries offered.
+ *
+ * System One gets ONE request with two questions over the same list: `route`, a `choice` among the flows (each
+ * option's criterion is its description, so every flow is weighed against the others), and `any`, a `noul`
+ * asking whether the message starts any of them. TypeSafe documents that a "none of the above" option may not
+ * work well and advises the companion noul.
+ */
 export function buildFlowStage(input, conversation, flows) {
     const names = flows.map(f => f.name);
     const schema = {
         type: 'object', additionalProperties: false, required: ['flowName'],
         properties: { flowName: { type: 'string', enum: [...names, 'None'] } },
     };
+    const list = flows.map(f => `- ${f.name}: ${f.description}`);
     const system = [
         'Decide which workflow, if any, the latest message starts.',
         `A workflow is chosen when: ${FLOW_TRUE}`,
         `"None" when: ${FLOW_FALSE}`,
+        QUESTION_RULE,
         'Answer with the exact workflow name, or "None".',
         '',
         '<workflows>',
-        ...flows.map(f => `- ${f.name}: ${f.description}`),
+        ...list,
         '</workflows>',
     ].join('\n') + jsonTail(schema);
-    const questions = {};
-    const index = [];
-    flows.forEach((f, i) => {
-        const id = `f${i}`;
-        questions[id] = {
-            type: 'noul', criteria: { true: FLOW_TRUE, false: FLOW_FALSE },
-            instructions: { flow: { name: f.name, description: f.description }, question: 'Should the latest message start the workflow in `flow`?' },
-        };
-        index.push({ id, flow: i });
-    });
+    const workflows = Object.fromEntries(flows.map(f => [f.name, f.description]));
+    const questions = {
+        any: {
+            type: 'noul',
+            criteria: { true: `${FLOW_TRUE} The workflow is one of \`workflows\`.`, false: `${FLOW_FALSE} ${QUESTION_RULE}` },
+            instructions: { workflows, question: 'Should the latest message start one of the workflows in `workflows`?' },
+        },
+    };
+    questions.route = {
+        type: 'choice', criteria: workflows,
+        instructions: 'Which workflow does the latest message, read with the conversation, come closest to starting?',
+    };
+    const index = [{ id: 'any' }, { id: 'route' }];
     return {
         task: 'detect_flow', stage: 1, input, conversation, flows,
         llm: { system, user: conversationText(conversation, input), schema },
@@ -97,23 +109,27 @@ export function decodeFlowLlm(text, stage) {
     }
 }
 /**
- * System One's stage-1 answers as the canonical reply, with the top three scores (for logs and a host's hedge
- * policy) and `pair` when two close candidates picked the higher. Throws if any question is unanswered.
+ * System One's stage-1 answers as the canonical reply. `any` at or above the threshold starts the flow `route`
+ * chose; below it, "None". `scores` are the top three flows by the chance that each is the one started,
+ * any × its route probability (for logs and the host's near-miss hedge); `any` is logged with them. Throws when
+ * either answer is missing or names no offered flow.
  */
-export function decodeFlowSystemOne(answers, stage, { threshold = STAGE_YES_THRESHOLD, pairSum = STAGE_PAIR_SUM } = {}) {
-    const p = answered(answers, stage.systemOne.index);
-    const ranked = stage.systemOne.index.map(q => ({ name: stage.flows[q.flow].name, p: p.get(q.id) })).sort((a, b) => b.p - a.p);
+export function decodeFlowSystemOne(answers, stage, { threshold = STAGE_YES_THRESHOLD } = {}) {
+    const any = Number(answers?.any?.noul);
+    if (!Number.isFinite(any))
+        throw new Error('System One: question any unanswered');
+    const names = stage.flows.map(f => f.name);
+    const route = answers?.route;
+    const raw = route?.probabilities;
+    if (!raw || typeof raw !== 'object')
+        throw new Error('System One: question route unanswered');
+    if (!names.includes(String(route?.choice)))
+        throw new Error(`System One: route chose "${String(route?.choice).slice(0, 60)}", not an offered workflow`);
+    const probabilities = Object.fromEntries(names.map(n => [n, Number(raw[n]) || 0]));
+    const ranked = names.map(n => ({ name: n, p: any * probabilities[n] })).sort((a, b) => b.p - a.p);
     const scores = ranked.slice(0, 3);
-    const [a, b] = ranked;
-    if (a && a.p >= threshold) {
-        return { flowName: a.name, scores, pair: false };
-    }
-    else if (a && b && a.p + b.p >= pairSum) {
-        return { flowName: a.name, scores, pair: true };
-    }
-    else {
-        return { flowName: 'None', scores, pair: false };
-    }
+    const flowName = any >= threshold && ranked[0] ? ranked[0].name : 'None';
+    return { flowName, scores, any };
 }
 /**
  * A System One "None" that is a near miss: the chance that at least one of its two top flows applies,

package/dist/runtime-identity.js

@@ -1 +1 @@
-export const JSFE_RUNTIME_FINGERPRINT = "sha256:9fca8fe719c5610d1260ece2cc393107d549667095f71bcaa62427a894f0ba7b";
+export const JSFE_RUNTIME_FINGERPRINT = "sha256:07545e99b09fda4ba770a9732d47399cee27e0ec746b824efa9e3f4124e74bb6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsfe",
-  "version": "1.14.2",
+  "version": "1.15.1",
   "description": "TypeScript workflow engine for conversational/automation apps: multi-flow orchestration, interrupt/resume, stack-based control, robust errors, and flexible tool/REST integration.",
   "license": "MIT",
   "author": "Ron Pinkas",
@@ -27,6 +27,10 @@
       "types": "./dist/helpers/index.d.ts",
       "import": "./dist/helpers/index.js"
     },
+    "./docs": {
+      "types": "./dist/docs/flow-docs.d.ts",
+      "import": "./dist/docs/flow-docs.js"
+    },
     "./forms": {
       "types": "./dist/forms/index.d.ts",
       "import": "./dist/forms/index.js"