Add turn-based intent demo

Author: rivendale

README.md

@@ -17,15 +17,17 @@ Managing Partner / CTO and a Certified Financial Planner professional.
 - Protocol Wealth GitHub: https://github.com/Protocol-Wealth
 - Nick Rygiel GitHub: https://github.com/rivendale
 
-## Related Protocol Wealth Open Source Projects
+## Related Open Source Projects
 
-These repositories are companion references and implementation inspiration. The
-`pwcli-core` specification remains neutral and reusable outside Protocol Wealth.
+These Protocol Wealth and maintainer repositories are companion references and
+implementation inspiration. The `pwcli-core` specification remains neutral and
+reusable outside Protocol Wealth.
 
 - `nexus-core`: https://github.com/Protocol-Wealth/nexus-core
 - `pwos-core`: https://github.com/Protocol-Wealth/pwos-core
 - `pwplan-core`: https://github.com/Protocol-Wealth/pwplan-core
 - `pw-learnai`: https://github.com/Protocol-Wealth/pw-learnai
+- `iocalc-agent-env`: https://github.com/rivendale/iocalc-agent-env
 
 ## Core Idea
 
@@ -98,6 +100,8 @@ Read these files in order:
 4. [docs/standards-map.md](docs/standards-map.md) for standards selection.
 5. [docs/context-packs.md](docs/context-packs.md) for context-pack structure.
 6. [docs/validation.md](docs/validation.md) for local and CI validation.
+7. [examples/turn-based-game/README.md](examples/turn-based-game/README.md) for a runnable browser demo.
+8. [docs/human-ux-guide.md](docs/human-ux-guide.md) for progressive disclosure patterns.
 
 ## Validation
 
@@ -110,6 +114,10 @@ npm run validate
 The same command runs in GitHub Actions on pull requests and pushes to `main`
 using Node 22 and Node 24.
 
+## Runnable Demo
+
+Open [examples/turn-based-game/index.html](examples/turn-based-game/index.html) in a browser for a no-build demo of command input, intent telemetry, registered primitive hydration, approval, deterministic execution, and return-focus ledger output.
+
 ## Example Query
 
 Illustrative synthetic example only; not tax, accounting, investment, or financial advice.

SPEC.md

@@ -101,9 +101,10 @@ They are not generated by the model at runtime. Each primitive should declare:
 - side-effect level;
 - approval requirement;
 - source/provenance requirements;
-- supported input and output modes.
+- supported input and output modes;
+- optional preview, cost, risk, empty/loading/error, primary action, and undo metadata.
 
-See [schemas/primitive.schema.json](schemas/primitive.schema.json).
+See [schemas/primitive.schema.json](schemas/primitive.schema.json) and [docs/human-ux-guide.md](docs/human-ux-guide.md).
 
 ## 7. Context Packs
 

docs/companion-projects.md

@@ -1,8 +1,8 @@
 # Companion Projects
 
 `pwcli-core` is a neutral public specification. The repositories below are
-related Protocol Wealth open-source projects that may provide implementation
-ideas, examples, or future integration references.
+related Protocol Wealth or maintainer open-source projects that may provide
+implementation ideas, examples, or future integration references.
 
 Maintainer context:
 
@@ -18,6 +18,7 @@ Maintainer context:
 | pwos-core | https://github.com/Protocol-Wealth/pwos-core | Potential reference for operating-system style control-plane patterns. |
 | pwplan-core | https://github.com/Protocol-Wealth/pwplan-core | Potential reference for planning workflows and structured decision records. |
 | pw-learnai | https://github.com/Protocol-Wealth/pw-learnai | Potential reference for education, AI literacy, and learning workflows. |
+| iocalc-agent-env | https://github.com/rivendale/iocalc-agent-env | Public Apache-2.0 reference for game-agent environment experiments and agent-facing simulation context. |
 
 ## Boundary
 

docs/human-ux-guide.md

@@ -0,0 +1,65 @@
+# Human UX Guide
+
+`pwcli-core` treats conversational UI as a focus-preserving control plane, not a
+license to hide consequential state changes behind fluent text. The user should
+see what the system inferred, what panel or route will hydrate, what costs or
+risks matter, and what will happen after approval.
+
+## Progressive Disclosure
+
+Use three practical disclosure modes.
+
+### Basic
+
+Basic mode favors speed for low-risk or reversible work. It should still leave a
+clear receipt after execution.
+
+- read-only summaries can run directly;
+- reversible idempotent mutations may use one-click confirmation;
+- show concise source references and fallback routes after completion.
+
+### Intermediate
+
+Intermediate mode is the default for mixed human and AI workflows. It should
+show an intent receipt before consequential work.
+
+- display intent, confidence, side-effect level, and candidate primitive;
+- show cost fields, risk labels, and likely output;
+- require explicit approval for state changes;
+- return focus with a deterministic ledger event and a separate interpretation.
+
+### Advanced
+
+Advanced mode favors auditability and operator control. It should expose
+structured payloads and provenance.
+
+- show the full intent telemetry payload;
+- show source records separately from AI interpretations;
+- expose fallback route and execution target metadata;
+- require approval for irreversible or externally visible actions;
+- keep replay and rollback policy visible.
+
+## Primitive UX Fields
+
+Registered primitives can include optional `ux` metadata in
+`schemas/primitive.schema.json`. These fields do not execute behavior; they give
+the host application predictable labels and empty/loading/error states.
+
+Recommended fields:
+
+- `primaryAction` for the approval button label;
+- `previewFields` for deterministic values to show before execution;
+- `riskLabels` for warnings, counterplay, privacy, or compliance notes;
+- `costFields` for energy, money, time, quota, or approval costs;
+- `emptyState`, `loadingState`, and `errorState` for bounded UI copy;
+- `undoPolicy` for rollback expectations.
+
+## Assertion Separation
+
+Never mix factual ledger state with model interpretation. A preview panel may
+show both, but it should label them separately:
+
+- deterministic source or event ledger: what the state engine knows;
+- advisor interpretation: what a model or heuristic inferred.
+
+The deterministic ledger remains the source of truth.

docs/validation.md

@@ -25,6 +25,7 @@ The GitHub Actions workflow runs the same command on pull requests and pushes to
   `humanReviewRequired`.
 - Every `context-pack/*.md` file has YAML frontmatter matching the repository's
   context-pack convention.
+- Example-local `.schema.json` files parse, and fixture JSON files declare a resolvable `schemaRef`, `name`, `summary`, and `example`; core fixtures receive lightweight shape checks.
 - Markdown local links resolve.
 - Public metadata markers are present in root docs.
 - Text files are ASCII-only, use LF line endings, avoid trailing whitespace, and

examples/turn-based-game/README.md

@@ -0,0 +1,37 @@
+# Turn-Based Game Intent Demo
+
+Synthetic runnable example for the `pwcli-core` dual-engine pattern. It is a
+small browser-only demo: no build step, no backend, no model calls, and no
+external dependencies.
+
+Open `index.html` in a modern browser.
+
+## What It Demonstrates
+
+1. Human command text is lossy.
+2. The parser compiles it into an intent telemetry object.
+3. The app selects a registered primitive from a static registry.
+4. The preview panel shows cost, risk, fallback route, and source references.
+5. A state-changing action pauses at an approval gate.
+6. The deterministic engine writes a ledger event.
+7. Advisor interpretation is displayed separately from deterministic state.
+
+The example uses turn-based game language because games make irreversible
+commits, costs, and preview UX easy to see. The same pattern applies to
+archives, finance workbenches, household workflows, care portals, and other
+high-integrity apps.
+
+## Files
+
+- `index.html` - static page shell.
+- `styles.css` - small local visual layer.
+- `demo.js` - deterministic parser, primitive registry, state machine, and ledger.
+- `fixtures/` - JSON fixtures for intent, primitive, source, provenance, and result.
+- `schemas/` - example-local schema for the result ledger fixture.
+
+## Safety Boundary
+
+This demo does not let AI generate UI or mutate state. The parser is a tiny
+keyword heuristic so the state machine is easy to inspect. A real implementation
+can swap in a model parser, BAML-style parser, MCP tool, or typed API as long as
+the output is validated before it reaches the deterministic engine.