@medicine-wheel/app 0.5.2 → 0.5.4

package/ALPHA.md

@@ -0,0 +1,59 @@
+# This suite is experimental alpha
+
+**Read this before depending on anything here.**
+
+The Medicine Wheel Developer Suite is under active development and is published
+in the open so the work can be examined, discussed, and improved. It is not
+finished software. Publishing early is deliberate — but so is telling you what
+you are installing.
+
+## What that means concretely
+
+- **APIs change between patch versions.** All packages move in lockstep, so a
+  bump you would normally read as "nothing changed for me" may still change
+  what you depend on. Pin exact versions.
+- **Packages appear, and their boundaries move.** Three packages were added in
+  `0.5.3`. Where a responsibility lives is still being decided.
+- **Some packages are intentionally small first cuts.** They express an
+  intention with a working minimum rather than a finished surface. Their
+  READMEs say so where it applies.
+- **Storage shapes are still settling.** Records written by one version may
+  need repair by a later one. Do not treat any store here as an archive of
+  record yet.
+- **Test coverage is real but uneven.** 210 tests pass at `0.5.3`; that is a
+  floor, not a claim of completeness.
+
+## What it does *not* mean
+
+It does not mean the work is careless. Defects found are fixed and written
+down, specifications are versioned alongside the code in `rispecs/`, and
+sessions are chronicled. The alpha label is about **stability of contract**,
+not about standard of care.
+
+## Cultural material
+
+Parts of this suite encode Indigenous relational research methodology —
+Four Directions structure, ceremony protocol, OCAP® compliance surfaces,
+relational accountability. That material is included because the software is
+*for* that way of working, not as decoration.
+
+If you are building on those parts, please read them as an invitation to work
+relationally rather than as a finished implementation of anyone's protocol.
+Where a design question is properly a knowledge holder's decision rather than
+an engineer's, the specs try to say so. Where we have got that wrong, telling
+us is a contribution.
+
+## If you are evaluating this
+
+The most useful things to read first:
+
+- `rispecs/` — the specifications, versioned with the code
+- `README.md` — what the suite is
+- Open issues — where the known edges are, stated plainly
+
+Feedback is genuinely wanted at this stage, including "this boundary is wrong"
+and "this should not be software".
+
+## License
+
+MIT — see `LICENSE`.

package/README.md

@@ -2,6 +2,12 @@
 
 > A first experimental TypeScript framework for relational healing, ceremonial inquiry, and Indigenous-aligned software development — grounded in the Four Directions, Wilson's three R's (Respect, Reciprocity, Responsibility), and OCAP® data sovereignty principles.
 
+> [!WARNING]
+> **Experimental alpha.** APIs change between patch versions, packages appear and
+> their boundaries move, and storage shapes are still settling. Published in the
+> open so the work can be examined and improved — pin exact versions, and read
+> [ALPHA.md](./ALPHA.md) before depending on any of it.
+
 ## NEWS
 
 * Full postgres (neon) data provider !
@@ -25,8 +31,17 @@ medicine-wheel-ontology-core          ← Foundation (types, schemas, RDF vocabu
     ├── medicine-wheel-ui-components        ← React components
     ├── medicine-wheel-data-store           ← Shared Redis data access
     └── medicine-wheel-session-reader       ← Session event data reader
+
+@medicine-wheel/creative-orientation      ← The question asked before the work
+    ├── @medicine-wheel/creative-problem-solving ← Signpost — re-exports the above
+    ├── @medicine-wheel/gap-analysis        ← The fire path
+    └── @medicine-wheel/brainstorming       ← Idea → design, through human gates
 ```
 
+> **Is there a prior state you are restoring?** Named one — this is a fire, and
+> gap analysis is the right instrument. Named none — you are creating, and
+> structural tension is. `mw orient "<outcome>"` asks it from the command line.
+
 ## Methodology: RISE Framework
 
 This project utilizes the **RISE** methodology:
@@ -129,6 +144,30 @@ Session event reader — JSONL parsing, session summaries, analytics extraction,
 - **Version:** 0.2.0
 - **Dependencies:** None (Node.js built-ins only)
 
+### [@medicine-wheel/creative-orientation](src/creative-orientation)
+The orientation question, asked before the work: *is there a prior state you are restoring?* Yes — this is a fire, route to gap analysis. No — you are creating, route to structural tension. Reads the claim the caller supplies; advises where phrasing and situation disagree, and never refuses.
+
+- **Version:** 0.5.3
+- **Dependencies:** None (Node.js built-ins only)
+
+### [@medicine-wheel/creative-problem-solving](src/creative-problem-solving)
+Signpost package — re-exports `@medicine-wheel/creative-orientation` and adds `THE_QUESTION`. Holds no logic of its own. It exists because "creative problem solving" is the name people look for, and a signpost carrying the traveller's name is how they find the door.
+
+- **Version:** 0.5.3
+- **Dependencies:** `@medicine-wheel/creative-orientation`
+
+### [@medicine-wheel/gap-analysis](src/gap-analysis)
+Problem-solving built properly for when something worked and stopped — evidenced baseline, observation, difference, verifiable elimination steps. Root cause, incidents, regressions, troubleshooting. The baseline requirement is what separates a fire from a creating act.
+
+- **Version:** 0.5.3
+- **Dependencies:** `@medicine-wheel/creative-orientation`
+
+### [@medicine-wheel/brainstorming](src/brainstorming)
+Idea into committed design through approval gates a human holds — `explore → clarify → approaches → design → spec → review → plan`. Every outcome it emits, including its own multiple-choice questions, passes the orientation question before it is spoken.
+
+- **Version:** 0.5.3
+- **Dependencies:** `@medicine-wheel/creative-orientation`
+
 ## Specifications
 
 RISE framework specifications for all 15 packages are in [`rispecs/`](rispecs/). Start with [`medicine-wheel.spec.md`](rispecs/medicine-wheel.spec.md) for the system overview.

package/app/api/narrative/beats/route.ts

@@ -15,7 +15,7 @@ export async function POST(request: Request) {
     // Pass the caller's id and timestamp through when supplied. A client that
     // authored a beat holds its id and will look it up again — minting a fresh
     // one here hands back a beat the caller can never find.
-    const beat = createBeat({
+    const { beat, warnings } = createBeat({
       id: body.id,
       timestamp: body.timestamp,
       direction: body.direction,
@@ -31,8 +31,15 @@ export async function POST(request: Request) {
       sub_beats: body.sub_beats,
       origin: body.origin,
     });
-    return NextResponse.json(beat, { status: 201 });
+    // Warnings ride on the created beat rather than replacing it, so clients
+    // that read the beat back by id keep working while advisory findings stop
+    // being computed-and-discarded.
+    return NextResponse.json(warnings.length ? { ...beat, warnings } : beat, { status: 201 });
   } catch (error: any) {
-    return NextResponse.json({ error: error.message }, { status: 500 });
+    // An invalid draft is the caller's error, not the server's. Reporting it
+    // as a 500 would read as "we broke" when the truth is "this beat does not
+    // satisfy the wheel's laws and was not stored".
+    const invalid = /^Invalid beat draft/.test(error?.message ?? '');
+    return NextResponse.json({ error: error.message }, { status: invalid ? 400 : 500 });
   }
 }

package/app/narrative/beats/page.tsx

@@ -25,23 +25,32 @@ export default function BeatsPage() {
   async function addBeat(e: FormEvent<HTMLFormElement>) {
     e.preventDefault();
     const form = new FormData(e.currentTarget);
+    // The act is never sent: it is derived from the direction by the engine.
+    // Offering it as a form field is how a west beat came to be stored in act 1.
     const body = {
       direction: form.get("direction") as string,
       title: form.get("title") as string,
       description: form.get("description") as string,
       prose: form.get("prose") as string || undefined,
-      act: parseInt(form.get("act") as string) || 1,
       learnings: (form.get("learnings") as string).split(",").map((s) => s.trim()).filter(Boolean),
       ceremonies: [],
       relations_honored: [],
     };
     const res = await fetch("/api/narrative/beats", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
     if (res.ok) {
-      toast.success("Beat added");
+      const created = await res.json();
+      if (Array.isArray(created?.warnings) && created.warnings.length) {
+        toast.warning(`Beat added — ${created.warnings.join(" · ")}`);
+      } else {
+        toast.success("Beat added");
+      }
       setShowForm(false);
       const data = await fetch("/api/narrative/beats").then((r) => r.json());
       setBeats(Array.isArray(data) ? data : []);
-    } else { toast.error("Could not save the beat — check the form and try again"); }
+    } else {
+      const err = await res.json().catch(() => null);
+      toast.error(err?.error ?? "Could not save the beat — check the form and try again");
+    }
   }
 
   // Direction summary
@@ -87,9 +96,7 @@ export default function BeatsPage() {
           </select>
           <textarea name="description" placeholder="Description" rows={2} required className="px-3 py-2 rounded-md border bg-background text-sm sm:col-span-2" />
           <textarea name="prose" placeholder="Prose (optional)" rows={2} className="px-3 py-2 rounded-md border bg-background text-sm" />
-          <select name="act" className="px-3 py-2 rounded-md border bg-background text-sm">
-            <option value="1">Act 1 (East)</option><option value="2">Act 2 (South)</option><option value="3">Act 3 (West)</option><option value="4">Act 4 (North)</option>
-          </select>
+          <p className="px-3 py-2 text-xs text-muted-foreground self-center">Act is derived from the direction — east 1, south 2, west 3, north 4.</p>
           <input name="learnings" placeholder="Learnings (comma-separated)" className="px-3 py-2 rounded-md border bg-background text-sm sm:col-span-2" />
           <button type="submit" className="px-4 py-2 rounded-md bg-primary text-primary-foreground text-sm hover:opacity-90">Add beat</button>
         </form>

package/dist/cli/beats-register.js

@@ -0,0 +1,199 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actForDirection = void 0;
+exports.resolveBeatsFile = resolveBeatsFile;
+exports.registerEpisodeBeats = registerEpisodeBeats;
+exports.describeArc = describeArc;
+/**
+ * mw beat register — an episode's authored beats into the wheel.
+ *
+ * This is the path that was missing. `mkepisode --register` registers the
+ * episode; nothing registered the beats an episode carries, so they sat in a
+ * YAML file as a design artifact and never became records.
+ *
+ * It goes **through** `@medicine-wheel/narrative-engine` rather than posting
+ * JSON at the REST surface. That distinction is the whole point: the first
+ * time these beats were registered it was by a script that POSTed directly,
+ * which meant `validateBeatDraft` never ran and nothing confirmed they were
+ * legal. Registering by hand around the door is the same defect the door
+ * exists to prevent.
+ *
+ * Reads `<episode>/beats/beats.yaml`:
+ *
+ *   cycle_id: cycle-...          # null means unbound; the cycle is created if named
+ *   cycle_question: >-           # used only when the cycle must be created
+ *   beats:
+ *     - id, direction, title, description, prose?, learnings[], relations_honored[], origin
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const narrative_engine_1 = require("@medicine-wheel/narrative-engine");
+Object.defineProperty(exports, "actForDirection", { enumerable: true, get: function () { return narrative_engine_1.actForDirection; } });
+/** Minimal YAML reader for the beats file — avoids a dependency for one shape. */
+function readBeatsFile(file) {
+    // js-yaml ships with the app; require lazily so the CLI stays usable without it.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const yaml = require('js-yaml');
+    const parsed = yaml.load(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`${file} did not parse to an object`);
+    }
+    const { cycle_id = null, cycle_question, beats } = parsed;
+    if (!Array.isArray(beats))
+        throw new Error(`${file} has no 'beats' array`);
+    return { cycle_id, cycle_question, beats };
+}
+function resolveBeatsFile(episodeDir) {
+    const candidates = [
+        path.join(episodeDir, 'beats', 'beats.yaml'),
+        path.join(episodeDir, 'beats.yaml'),
+    ];
+    const found = candidates.find(c => fs.existsSync(c));
+    if (!found) {
+        throw new Error(`No beats file found. Looked for:\n  ${candidates.join('\n  ')}`);
+    }
+    return found;
+}
+async function get(url) {
+    const res = await fetch(url, { signal: AbortSignal.timeout(15000) });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status} GET ${url}`);
+    return res.json();
+}
+async function post(url, body) {
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(20000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        // A 400 is the wheel refusing an illegal beat. Surface its reason rather
+        // than a status code — the caller needs to know which law it broke.
+        let detail = text;
+        try {
+            detail = JSON.parse(text).error ?? text;
+        }
+        catch { /* keep raw */ }
+        throw new Error(`HTTP ${res.status}: ${detail}`);
+    }
+    return JSON.parse(text);
+}
+async function registerEpisodeBeats(episodeDir, options) {
+    const file = resolveBeatsFile(episodeDir);
+    const doc = readBeatsFile(file);
+    const outcome = {
+        registered: [], skipped: [], rejected: [],
+        cycleId: doc.cycle_id, cycleCreated: false,
+    };
+    // Build every draft through the door first. Nothing is written until all of
+    // them are legal — a half-registered arc is worse than none, because the
+    // cycle then reports a story that stops mid-sentence.
+    const drafts = [];
+    for (const raw of doc.beats) {
+        const draft = {
+            id: raw.id,
+            direction: raw.direction,
+            title: (raw.title ?? '').trim(),
+            description: (raw.description ?? '').trim(),
+            prose: raw.prose ? String(raw.prose).trim() : undefined,
+            learnings: raw.learnings ?? [],
+            ceremonies: raw.ceremonies ?? [],
+            relations_honored: raw.relations_honored ?? [],
+            cycle_id: doc.cycle_id ?? undefined,
+            parent_beat_id: raw.parent_beat_id,
+            origin: raw.origin ?? {
+                producer: 'chronicle-episode',
+                source_ref: path.basename(episodeDir),
+                method: 'authored',
+            },
+        };
+        const check = (0, narrative_engine_1.validateBeatDraft)(draft);
+        if (!check.valid) {
+            outcome.rejected.push({
+                id: raw.id ?? '(no id)',
+                violations: check.violations.filter(v => v.severity === 'error').map(v => `${v.field}: ${v.message}`),
+            });
+            continue;
+        }
+        // Prove it can be authored before anything is sent.
+        (0, narrative_engine_1.createBeat)(draft);
+        drafts.push(draft);
+    }
+    if (outcome.rejected.length > 0 || options.dryRun)
+        return outcome;
+    // Ensure the cycle exists before binding to it, so no beat is written naming
+    // a cycle that is not there.
+    if (doc.cycle_id) {
+        const cycles = await get(`${options.apiUrl}/api/narrative/cycles`);
+        if (!cycles.some(c => c.id === doc.cycle_id)) {
+            await post(`${options.apiUrl}/api/narrative/cycles`, {
+                id: doc.cycle_id,
+                research_question: doc.cycle_question ?? `Episode ${path.basename(episodeDir)}`,
+                current_direction: 'east',
+            });
+            outcome.cycleCreated = true;
+        }
+    }
+    const existing = await get(`${options.apiUrl}/api/narrative/beats`);
+    const known = new Set(existing.map(b => b.id));
+    for (const draft of drafts) {
+        if (draft.id && known.has(draft.id)) {
+            outcome.skipped.push({ id: draft.id, reason: 'already registered' });
+            continue;
+        }
+        const got = await post(`${options.apiUrl}/api/narrative/beats`, draft);
+        if (got.id !== draft.id) {
+            throw new Error(`The wheel returned id ${got.id} for a beat sent as ${draft.id}. ` +
+                'Registration stopped — an id that does not survive the round trip cannot be looked up again.');
+        }
+        outcome.registered.push(got.id);
+    }
+    return outcome;
+}
+/** Human-readable summary of what an arc now holds. */
+function describeArc(beats) {
+    const order = { east: 1, south: 2, west: 3, north: 4 };
+    const lines = beats
+        .slice()
+        .sort((a, b) => (a.act - b.act) || String(a.timestamp).localeCompare(String(b.timestamp)))
+        .map(b => `  act ${b.act}  ${String(b.direction).padEnd(6)} ${b.title}`);
+    const walked = [...new Set(beats.map(b => b.direction))].sort((a, b) => order[a] - order[b]);
+    lines.push('');
+    lines.push(`  directions walked: ${walked.join(' → ')}${walked.length === 4 ? '  (complete arc)' : ''}`);
+    return lines;
+}

package/dist/cli/mw.js

@@ -46,6 +46,8 @@ const child_process_1 = require("child_process");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const skills_1 = require("./skills");
+const beats_register_1 = require("./beats-register");
+const orientation_1 = require("./orientation");
 // ── Config ────────────────────────────────────────────────────────
 const MW_API_URL = process.env.MW_API_URL ?? 'http://localhost:8040';
 const MW_FORMAT = process.env.MW_FORMAT ?? 'pretty';
@@ -212,6 +214,20 @@ function cmdHelp() {
     console.log(`
 ${C.bold}🌿 mw — Medicine Wheel CLI${C.reset}
 
+  ORIENTATION
+    mw orient "<outcome>"                  Which orientation does this call for?
+      [--restores "<prior state>"]         A prior state you are returning to
+      [--evidence "<when it existed>"]     When that state was actually true
+
+    Ask before problem-solving, debugging, fixing, troubleshooting, root-cause
+    or creative-problem-solving work. It reads the claim you supply:
+
+      --restores named  → a fire; gap analysis is the right instrument
+      --restores absent → you are creating; structural tension is
+
+    Urgency is not evidence — under pressure every situation feels like a fire.
+    It reports and offers a restatement; it never refuses.
+
   CEREMONY LIFECYCLE
     mw ceremony open <intention>           Open ceremony (starts in East)
     mw ceremony close <id> [summary]       Close ceremony
@@ -235,6 +251,8 @@ ${C.bold}🌿 mw — Medicine Wheel CLI${C.reset}
 
   NARRATIVE
     mw beat create <dir> <title> <desc>    Create narrative beat
+    mw beat register <episode-dir>         Register authored beats via the door
+    mw beat register <episode-dir> --dry-run   Check legality, write nothing
     mw beat list [--direction east]        List beats
     mw arc <cycle_id>                      Get narrative arc
 
@@ -525,9 +543,49 @@ async function cmdNode(positional, flags) {
     }
 }
 // ── Beat ──────────────────────────────────────────────────────────
-async function cmdBeat(positional) {
+async function cmdBeat(positional, flags = {}) {
     const sub = positional[0] ?? 'list';
     switch (sub) {
+        case 'register': {
+            const dir = positional[1];
+            if (!dir) {
+                console.error('Usage: mw beat register <episode-dir> [--dry-run]');
+                console.error('  Registers an episode\'s authored beats through the authoring door.');
+                process.exit(2);
+            }
+            try {
+                const out = await (0, beats_register_1.registerEpisodeBeats)(dir, {
+                    apiUrl: MW_API_URL,
+                    dryRun: flags['dry-run'] === true,
+                });
+                if (out.rejected.length > 0) {
+                    console.error(`${C.south}${out.rejected.length} beat(s) rejected — nothing was written${C.reset}`);
+                    for (const r of out.rejected) {
+                        console.error(`  ${r.id}`);
+                        for (const v of r.violations)
+                            console.error(`    ${v}`);
+                    }
+                    process.exit(1);
+                }
+                if (flags['dry-run'] === true) {
+                    console.log(`${C.green}dry run — all beats are legal, nothing written${C.reset}`);
+                    break;
+                }
+                if (out.cycleCreated)
+                    console.log(`${C.dim}cycle created:${C.reset} ${out.cycleId}`);
+                console.log(`${C.green}registered ${out.registered.length}${C.reset}${out.skipped.length ? `  ${C.dim}(${out.skipped.length} already present)${C.reset}` : ''}`);
+                const all = (await api('GET', '/api/narrative/beats'));
+                const scoped = out.cycleId ? all.filter(b => b.cycle_id === out.cycleId) : all;
+                console.log('');
+                for (const line of (0, beats_register_1.describeArc)(scoped))
+                    console.log(line);
+            }
+            catch (err) {
+                console.error(`${C.south}${err.message}${C.reset}`);
+                process.exit(1);
+            }
+            break;
+        }
         case 'create':
             mcpCall('create_narrative_beat', {
                 direction: positional[1] ?? '',
@@ -714,7 +772,7 @@ async function main() {
             break;
         case 'beat':
         case 'b':
-            await cmdBeat(rest);
+            await cmdBeat(rest, flags);
             break;
         case 'edge':
         case 'e':
@@ -746,6 +804,10 @@ async function main() {
         case 'arc':
             mcpCall('get_narrative_arc', { cycle_id: rest[0] ?? '' });
             break;
+        case 'orient':
+        case 'orientation':
+            (0, orientation_1.cmdOrient)(rest, flags);
+            break;
         default:
             console.error(`${C.south}Unknown command: ${cmd}${C.reset}`);
             console.error("Run 'mw help' for usage.");

package/dist/cli/orientation.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmdOrient = cmdOrient;
+/**
+ * mw orient — which orientation does this situation call for?
+ *
+ * The operator surface for `@medicine-wheel/creative-orientation`. The package
+ * shipped at 0.5.3 with no way to run it, which made it a library nobody could
+ * reach — a spec with a package.json.
+ *
+ *   mw orient "catch cross-service contract breaks"
+ *   mw orient "the image matches the packages" --restores "true through 0.5.0" --evidence "tagged 2026-07-17"
+ *
+ * It never refuses. It reports, and where the phrasing and the situation
+ * disagree it says so and offers a restatement.
+ */
+const creative_orientation_1 = require("@medicine-wheel/creative-orientation");
+const C = {
+    east: '\x1b[33m', south: '\x1b[31m', west: '\x1b[34m',
+    green: '\x1b[32m', dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m',
+};
+function cmdOrient(positional, flags) {
+    const outcome = positional.join(' ').trim();
+    if (!outcome) {
+        console.error('Usage: mw orient "<the outcome you want>" [--restores "<prior state>"] [--evidence "<when it existed>"]');
+        console.error('');
+        console.error('  Names which orientation the situation calls for.');
+        console.error('  --restores  a prior state you are returning to. Its presence is what');
+        console.error('              separates a repair from a creating act.');
+        process.exit(2);
+    }
+    const restores = typeof flags.restores === 'string' ? flags.restores : null;
+    const evidence = typeof flags.evidence === 'string' ? flags.evidence : undefined;
+    const claim = { outcome, restores, evidence };
+    const reading = (0, creative_orientation_1.readOrientation)(claim);
+    const tint = reading.orientation === 'advancing' ? C.east : C.west;
+    console.log('');
+    console.log(`${C.bold}${tint}${reading.orientation}${C.reset}  →  route: ${C.bold}${reading.route}${C.reset}`);
+    console.log('');
+    console.log(`${C.dim}outcome:${C.reset} ${outcome}`);
+    if (restores)
+        console.log(`${C.dim}restores:${C.reset} ${restores}${evidence ? ` ${C.dim}(${evidence})${C.reset}` : ''}`);
+    console.log('');
+    console.log(`${C.dim}signals${C.reset}`);
+    for (const s of reading.signals) {
+        const mark = s.suggests === 'advancing' ? `${C.east}↑${C.reset}` : `${C.west}↻${C.reset}`;
+        console.log(`  ${mark} ${C.dim}[${s.kind}]${C.reset} ${s.detail}`);
+    }
+    if ((0, creative_orientation_1.worthSaying)(reading)) {
+        console.log('');
+        console.log(`${C.south}${C.bold}advice${C.reset}`);
+        console.log(`  ${reading.advice}`);
+        if (reading.suggestedOutcome) {
+            console.log('');
+            console.log(`${C.green}suggested restatement${C.reset}`);
+            console.log(`  ${reading.suggestedOutcome}`);
+        }
+    }
+    else {
+        console.log('');
+        console.log(`${C.green}the phrasing and the situation agree — nothing to say${C.reset}`);
+    }
+    console.log('');
+}

package/lib/store.ts

@@ -22,7 +22,7 @@ import type {
   MedicineWheelCycle,
 } from '@/lib/types';
 
-import { actForDirection } from '@medicine-wheel/narrative-engine';
+import { createBeat as authorBeat, validateBeatDraft, type BeatDraft } from '@medicine-wheel/narrative-engine';
 import { extractBeats } from './beat-response';
 import { extractCycles, normalizeMedicineWheelCycle } from './cycle-response';
 import { getJsonlStore } from './jsonl-store';
@@ -138,32 +138,73 @@ export function getBeatsByDirection(direction: string): NarrativeBeat[] {
 // `act` is optional because it is derived from `direction`, not supplied.
 // Requiring it invited callers to pass a constant, which is how a west beat
 // came to be recorded in act 1.
+/**
+ * Create a beat through the authoring door.
+ *
+ * This delegates to `@medicine-wheel/narrative-engine` rather than assembling
+ * the record itself. It did assemble it, and that made the REST surface a
+ * second minting site: a beat posted over HTTP was never checked by
+ * `validateBeatDraft`, so the door only governed callers who happened to come
+ * through MCP. Five beats were registered that way before this was noticed —
+ * they were valid, but nothing had confirmed it.
+ *
+ * Throws on an invalid draft. The route turns that into a 400, which is the
+ * honest answer: a beat that fails the wheel's laws should not be stored and
+ * then reported as created.
+ */
 export function createBeat(
   data: Omit<NarrativeBeat, 'id' | 'timestamp' | 'act'> & { id?: string; timestamp?: string; act?: number },
-): NarrativeBeat {
-  const id = data.id || crypto.randomUUID();
-  const beat: NarrativeBeat = {
-    id,
+): { beat: NarrativeBeat; warnings: string[] } {
+  // A POST carrying an existing id is an update. Its provenance was stamped at
+  // creation; re-stamping `origin` on every touch would rewrite who authored
+  // the beat — the record must keep its first producer unless the caller
+  // states a new one deliberately.
+  const existing = data.id ? (store.getBeat(data.id) as any) : undefined;
+
+  const draft: BeatDraft = {
     direction: data.direction,
     title: data.title,
     description: data.description,
     prose: data.prose,
     ceremonies: data.ceremonies ?? [],
     learnings: data.learnings ?? [],
-    timestamp: data.timestamp || new Date().toISOString(),
-    // Derive the act from the direction rather than defaulting to 1. A west
-    // beat posted without an act was being recorded as an opening moment,
-    // which places it wrongly on the wheel for every reader downstream.
-    act: data.act ?? actForDirection(data.direction),
     relations_honored: data.relations_honored ?? [],
+    act: data.act,
+    id: data.id ?? crypto.randomUUID(),
+    timestamp: data.timestamp,
+    cycle_id: data.cycle_id,
+    parent_beat_id: data.parent_beat_id,
+    origin: data.origin ?? existing?.origin ?? { producer: 'rest' },
   };
-  if (data.cycle_id !== undefined) beat.cycle_id = data.cycle_id;
-  if (data.parent_beat_id !== undefined) beat.parent_beat_id = data.parent_beat_id;
+
+  // `strictAct` turns an act that contradicts the direction into an error
+  // instead of a stored contradiction. The act is derived, never chosen; a
+  // caller supplying the natural act is fine, a caller supplying any other is
+  // told so rather than silently recorded.
+  const beat = authorBeat(draft, { strictAct: true });
+
+  // The door computes warnings on every draft; discarding them made the
+  // advisory half of validation invisible on the paths people actually use.
+  const warnings = validateBeatDraft(draft)
+    .violations.filter(v => v.severity === 'warning')
+    .map(v => `${v.field}: ${v.message}`);
+
   if (data.sub_beats !== undefined) beat.sub_beats = data.sub_beats;
-  if (data.origin !== undefined) beat.origin = data.origin;
 
   store.createBeat(beat as any);
 
+  // Reciprocate the child side of any sub_beats named on this beat. A parent
+  // listing children that do not point back is the same one-sided relation the
+  // cycle and parent bindings below exist to prevent.
+  if (beat.sub_beats?.length) {
+    for (const childId of beat.sub_beats) {
+      const child = store.getBeat(childId) as any;
+      if (child && child.parent_beat_id !== beat.id) {
+        store.createBeat({ ...child, parent_beat_id: beat.id });
+      }
+    }
+  }
+
   // Bind the cycle side of the relation. A beat naming a cycle that does not
   // list it back is invisible to every arc reader that starts from the cycle.
   if (beat.cycle_id) {
@@ -181,7 +222,7 @@ export function createBeat(
     }
   }
 
-  return beat;
+  return { beat, warnings };
 }
 
 // ── Cycles ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -20,34 +20,40 @@
     "Dockerfile",
     "docker-entrypoint.sh",
     "docker-build-push.sh",
-    "README.md"
+    "README.md",
+    "ALPHA.md"
   ],
+  "//workspaces": "TOPOLOGICAL ORDER — do not alphabetize. `npm run <script> --workspaces` executes in THIS array's order, not in dependency order: a package listed before a package it imports builds first and fails TS2307 on any tree without a stale dist/. Roots first (ontology-core, creative-orientation, session-reader), then their dependents, mcp last. A new package goes after everything it imports.",
   "workspaces": [
+    "src/ontology-core",
+    "src/creative-orientation",
+    "src/session-reader",
     "src/ceremony-protocol",
-    "src/community-review",
-    "src/consent-lifecycle",
+    "src/storage-provider",
     "src/data-store",
     "src/data-store-postgres",
-    "src/fire-keeper",
     "src/graph-viz",
     "src/importance-unit",
-    "src/narrative-cluster",
     "src/narrative-engine",
-    "src/ontology-core",
+    "src/narrative-cluster",
     "src/perception-layer",
     "src/prompt-decomposition",
     "src/relational-index",
     "src/relational-query",
-    "src/session-reader",
-    "src/storage-provider",
+    "src/ui-components",
+    "src/brainstorming",
+    "src/gap-analysis",
+    "src/creative-problem-solving",
+    "src/community-review",
+    "src/consent-lifecycle",
+    "src/fire-keeper",
+    "src/transformation-tracker",
     "src/ceremonial-diary",
     "src/github-ceremony",
-    "src/transformation-tracker",
-    "src/ui-components",
     "mcp"
   ],
   "scripts": {
-    "build:packages": "npm run build -w src/ontology-core && npm run build --workspaces --if-present",
+    "build:packages": "npm run build -w src/ontology-core -w src/creative-orientation && npm run build --workspaces --if-present",
     "build:cli": "tsc -p tsconfig.cli.json && node -e \"for (const f of ['dist/cli/mw.js','dist/cli/mwsrv.js']) { try { require('fs').chmodSync(f, 0o755); } catch (e) { console.warn('[cli] chmod skipped (non-fatal):', e.message); } }\"",
     "clean:packages": "npm run clean --workspaces --if-present",
     "prebuild": "npm run build:packages",
@@ -78,31 +84,32 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.5.2",
-    "@medicine-wheel/ceremony-protocol": "^0.5.2",
-    "@medicine-wheel/community-review": "^0.5.2",
-    "@medicine-wheel/consent-lifecycle": "^0.5.2",
-    "@medicine-wheel/data-store": "^0.5.2",
-    "@medicine-wheel/data-store-postgres": "^0.5.2",
-    "@medicine-wheel/fire-keeper": "^0.5.2",
-    "@medicine-wheel/github-ceremony": "^0.5.2",
-    "@medicine-wheel/graph-viz": "^0.5.2",
-    "@medicine-wheel/importance-unit": "^0.5.2",
-    "@medicine-wheel/mcp": "^4.5.2",
-    "@medicine-wheel/narrative-cluster": "^0.5.2",
-    "@medicine-wheel/narrative-engine": "^0.5.2",
-    "@medicine-wheel/ontology-core": "^0.5.2",
-    "@medicine-wheel/perception-layer": "^0.5.2",
-    "@medicine-wheel/prompt-decomposition": "^0.5.2",
-    "@medicine-wheel/relational-index": "^0.5.2",
-    "@medicine-wheel/relational-query": "^0.5.2",
-    "@medicine-wheel/session-reader": "^0.5.2",
-    "@medicine-wheel/storage-provider": "^0.5.2",
-    "@medicine-wheel/transformation-tracker": "^0.5.2",
-    "@medicine-wheel/ui-components": "^0.5.2",
+    "@medicine-wheel/ceremonial-diary": "^0.5.4",
+    "@medicine-wheel/ceremony-protocol": "^0.5.4",
+    "@medicine-wheel/community-review": "^0.5.4",
+    "@medicine-wheel/consent-lifecycle": "^0.5.4",
+    "@medicine-wheel/data-store": "^0.5.4",
+    "@medicine-wheel/data-store-postgres": "^0.5.4",
+    "@medicine-wheel/fire-keeper": "^0.5.4",
+    "@medicine-wheel/github-ceremony": "^0.5.4",
+    "@medicine-wheel/graph-viz": "^0.5.4",
+    "@medicine-wheel/importance-unit": "^0.5.4",
+    "@medicine-wheel/mcp": "^4.5.4",
+    "@medicine-wheel/narrative-cluster": "^0.5.4",
+    "@medicine-wheel/narrative-engine": "^0.5.4",
+    "@medicine-wheel/ontology-core": "^0.5.4",
+    "@medicine-wheel/perception-layer": "^0.5.4",
+    "@medicine-wheel/prompt-decomposition": "^0.5.4",
+    "@medicine-wheel/relational-index": "^0.5.4",
+    "@medicine-wheel/relational-query": "^0.5.4",
+    "@medicine-wheel/session-reader": "^0.5.4",
+    "@medicine-wheel/storage-provider": "^0.5.4",
+    "@medicine-wheel/transformation-tracker": "^0.5.4",
+    "@medicine-wheel/ui-components": "^0.5.4",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",
+    "js-yaml": "^4.3.0",
     "lucide-react": "^0.475.0",
     "next": "^15.3.0",
     "next-themes": "^0.4.6",
@@ -115,6 +122,7 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
@@ -122,5 +130,9 @@
     "tailwindcss": "^4.1.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/medicine-wheel.git"
   }
 }