@f-o-h/cli 0.1.5 → 0.1.6

package/README.md

@@ -9,6 +9,17 @@ Current published baseline: `@f-o-h/cli@0.1.5`
 This mirror is a generated release artifact. The private product monorepo is not
 published here, and no open-source license is granted unless stated separately.
 
+Package-local examples and schemas ship with the npm artifact:
+
+- `examples/scenario-suite.viewing.yml`
+- `examples/proof-report.example.json`
+- `examples/transcript-export.example.json`
+- `examples/improvement-packet.example.json`
+- `schemas/cli-envelope.schema.json`
+- `schemas/scenario-suite.schema.json`
+- `schemas/transcript-export.schema.json`
+- `schemas/improvement-packet.schema.json`
+
 ## Install
 
 ```bash
@@ -50,6 +61,9 @@ foh org list --json
 foh org use --org <org-id> --json
 foh setup --org <org-id> --agent-template <template-id> --agent-name "Demo Agent" --json
 foh prove --agent <agent-id> --json --out foh-proof.json
+foh test run --suite ./suite.yml --agent <agent-id> --json --out foh-test-report.json
+foh agent replay --file ./transcript-export.json --json
+foh bug improve --from-file foh-proof.json --out foh-improvement.json --json
 ```
 
 `auth signup --web` opens the console signup page when possible and always
@@ -59,9 +73,85 @@ returned short-lived token. Credential auth remains available as fallback.
 
 `foh prove` produces a compact signed proof report across auth, org context,
 agent validation, contact phone readiness, voice provider health, widget
-channel/embed readiness, widget smoke, and simulation certification. Use
-`--strict` in automation when holds should fail the command, and
+channel/embed readiness, widget smoke, and simulation certification. It is
+read-only by default; pass `--mutation-mode ensure` or `--repair` only when you
+explicitly want proof to ensure missing widget state. Use `--strict` in
+automation when holds should fail the command, and `--mission voice` or
 `--require-phone` when a voice/contact number is mandatory for the demo.
 
 The CLI defaults to the production API at `https://api.frontofhouse.okii.uk`.
+
+## Local Scenario Suites
+
+`foh test run --suite <file>` runs deterministic widget-runtime checks for a
+specific agent. The suite format supports reply text checks plus structured
+runtime assertions for trace/correlation IDs, action or terminal state, latency,
+variables, tool calls, escalation/handoff, lead capture, and exact response
+field paths.
+
+```yaml
+agent: agent_123
+scenarios:
+  - id: viewing
+    turns:
+      - user: Can I book a viewing this week?
+        expect:
+          contains: viewing
+          trace_present: true
+          correlation_present: true
+          action: text
+          latency_ms:
+            max: 3000
+```
+
+Use transcript fixtures when turning real user conversations into regression
+tests:
+
+```yaml
+agent: agent_123
+scenarios:
+  - id: replay-viewing
+    fixture_transcript: ./fixtures/viewing-transcript.json
+```
+
+## Transcript Export
+
+Use hydrated transcript export to turn real behavior into replay/debug artifacts:
+
+```bash
+foh transcripts export \
+  --agent <agent-id> \
+  --hydrate \
+  --include-traces \
+  --format json \
+  --out foh-transcripts.json \
+  --json
+```
+
+Exports redact obvious emails, phone numbers, and secret-like tokens by default.
+Each exported conversation includes a `replay_command` and `test_fixture` seed
+so operators or AI agents can move from observed failure to replay or scenario
+regression without opening the console.
+
+Replay a local export without API access:
+
+```bash
+foh agent replay --file foh-transcripts.json --json
+```
+
+## Improvement Packets
+
+Use `foh bug improve` when a setup, proof, replay, knowledge, runtime, or
+live-proof failure should become actionable backlog/test/config/docs work:
+
+```bash
+foh bug improve \
+  --from-file test-results/proof-or-replay-failure.json \
+  --out test-results/improvement-packet.json \
+  --json
+```
+
+The command emits a redacted `foh_improvement_packet.v1` with stable IDs,
+reason code, promotion decision, evidence summary, and deterministic next
+commands.