# jouleclaw-stack — starter cascades

This directory exists because the five-lens wave-7/8 cross-talk audit
(Phillip / Rafie / Bloom / Hyper-Agent / Priscilla) independently
flagged the same on-ramp gap: **a multi-crate workspace, one end-to-end
example**. Small runnable cascades give a new operator a working
starting point per use case.

Each example is self-contained and runs with:

```
cargo run -p jouleclaw-stack --example <name>
```

| Example | What it shows | Audit lens |
|---|---|---|
| `minimal_cache_only` | The smallest cascade walk; L0 cache vs L3 echo. | Phillip — text-is-state |
| `rag_with_retrieval` | Retrieve → enrich → rerank → read over a seeded index. | Bloom — verifiable zone |
| `comprehend_demo` | `Stack::comprehend` — L0–L2 only, with intent tagging. | Priscilla — *understand before you generate* |
| `agent_with_skill_induction` | Register a skill, watch a query class resolve at L0.5. | Phillip — agent-ready APIs |
| `save_memory_and_promote` | Manual `save_memory` + auto-learned `NotifyPromotedFact` events. | Hyper-Agent — three modes of memory |
| `ledger_breakdown` | A workload, a ledger, a `CostSummary` rendered with intent shares. | Rafie — breakdown at the top |
| `full_cascade_with_triangle` | Cascade walk + triangle (elicitor → cone → conservation → oracle) + JCR-1 receipt — in one run. | The consolidated end-to-end stake. |
| `openpay_per_joule_billing` | Cross-standard composition: JouleClaw → JCR-1 → OpenPay. Pay-per-joule pitch made real, three artifacts emitted. | Open-standards quartet — composing at the wire layer, not the crate-graph layer. |

## Doctrine in one line

*"Inference is the last resort, not the entry point."* — SPEC §1.1

Read the `comprehend_demo` example first if you want to feel why that
sentence is the project's centre of gravity.