@miadi/ncp-story-studio 0.8.0 → 0.8.1

package/README.md

@@ -5,14 +5,16 @@ zero-dependency validator, a reader that accepts the NCP dialects that actually
 story-lattice layout with a React renderer, story-project storage over JSON files or Neon Postgres,
 the agent link protocol, and the canonical terminology as data.
 
-Phase plan, sources of truth, and what is deliberately not built yet: [`PHASES.md`](./PHASES.md).
+In the Miadi stack, this is one of two narrative models. The Narrative Context Protocol (NCP)
+describes a story the way Dramatica does: throughlines, players, storypoints and storybeats.
+Miadi's story studio opens NCP story projects, draws them as a line of beats, and lets agents
+read and link into them. The other model is `@miadi/wampum-narrative-engine`, a peer rather than
+a view of this one, and `@miadi/ncp-wampum-bridge` carries a story between the two.
 
 ## Install
 
 ```bash
-pnpm add @miadi/ncp-story-studio
-# in this workspace
-pnpm -w add @miadi/ncp-story-studio@workspace:* --filter <consumer>
+npm i @miadi/ncp-story-studio
 ```
 
 `react` and `@neondatabase/serverless` are optional peer dependencies: they are needed only by
@@ -147,7 +149,7 @@ Cards clamp their summary and illustration to three lines, so the canvas is 480p
 import { JsonStoryStore } from '@miadi/ncp-story-studio/store/json'
 import { NeonStoryStore } from '@miadi/ncp-story-studio/store/neon'
 
-const store = new JsonStoryStore({ root: '/srv/miadi/ncp-story-projects' })
+const store = new JsonStoryStore({ root: './ncp-story-projects' })
 await store.init()
 const project = await store.get('catalyst-of-change')
 await store.save({ ...project, document }, { expected_updated_at: project.updated_at })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/ncp-story-studio",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Narrative Context Protocol story studio as consumable modules: canonical NCP types and a zero-dependency validator, a headless story-lattice layout with a React renderer, story-project storage providers (JSON files and Neon Postgres), the agent link protocol, and the terminology and example data behind the teaching surface.",
   "license": "MIT",
   "author": "Miadi",
@@ -63,9 +63,7 @@
   "files": [
     "dist",
     "assets",
-    "rispecs",
     "README.md",
-    "PHASES.md",
     "LICENSE"
   ],
   "repository": {

package/PHASES.md

@@ -1,299 +0,0 @@
-# @miadi/ncp-story-studio — Phase Plan
-
-**Written:** 2026-09-12 · steered by Guillaume's annotations on the capability survey.
-**Reads with:** `AGENTS.md` (direction, version table stale — read manifests), `STATUS.md`,
-`rispecs/`, and `/a/src/Miadi-18/rispecs/wampum-narrative-engine/` (later phases).
-**Origin issue:** `jgwill/Miadi#361`. Wampum lanes: `#437` foundations, `#438` NCP bridge,
-`#439` package surface.
-
-## Sources of truth
-
-| what | where |
-|---|---|
-| Canonical NCP schema | `/workspace/repos/avadisabelle/holisticagnostic-narrative-context-protocol/schema/ncp-schema.json` |
-| Prototype experience to rebuild | `/workspace/repos/miadisabelle/a1f8409e-1a36-495e-9ac2-84f617e6447c-ncp-story-studio-251125` |
-| Governance research | that repo's `foundations/{decolonization-protocol-extensions,oral-tradition-storywork,linguistic-relativity-indigenous-epistemology}/` |
-| Wampum specs | `rispecs/wampum-narrative-engine/` in this checkout |
-| Consumption target | `app/ncp` in this checkout — **planned, not yet created** |
-
-`app/ncp` is where the published packages are consumed to rebuild the prototype experience
-inside Miadi, with the seed projects (Catalyst of Changes and the other four narratives)
-observable there. It is a target, not a stale reference.
-
-## Status — 2026-09-19 (phone round, from a real phone — 0.7.3 to 0.7.6)
-
-Reported from an iPhone: sweep the scrubber to the end and back, and the page died. Reproduced in
-WebKit (the engine of every iOS browser) with Playwright's iPhone profile: the studio rewrote the
-URL on every beat crossed, and WebKit throws a `SecurityError` past 100 `replaceState` calls in 10
-seconds. The app now writes the URL once the reader rests. In the package, for the phone's memory:
-
-- **The graph draws the window around the view, not the whole line** (`visibleNodeRange`): a dozen
-  cards, rings and stems instead of ninety, however long the story. The canvas keeps its full width,
-  so scrolling, snapping and focus-following are unchanged.
-- **A focused beat stays drawn, and the first screen is drawn before hydration** (0.7.4, from a
-  WebKit review); a follow longer than six beats cuts instead of gliding, and the follow
-  runs before paint so a cut never shows an empty frame (0.7.5, 0.7.6): arrow keys kept working past the window's edge only while the focused beat
-  stayed mounted, and a link to beat 40 painted an empty line until the page hydrated.
-- **No full-length SVG blur.** The line's glow was an `feGaussianBlur` over a 32,000px path — at
-  a phone's 3x density a buffer 97,000 pixels wide. It is now a faint wide stroke under the thin one.
-
-## Status — 2026-09-19 (phone round, second pass — 0.7.0 to 0.7.2)
-
-Two independent reviews read the first pass: a code review (9 findings) and a phone UX walk at
-360, 390, 430, 768 and landscape (20 findings, one blocking). What the package took from them:
-
-- **The line and the scrubber cannot disagree.** `centerBeatId` separates where the reader is from
-  the beat they chose; a relaid line (cards ↔ compact) is put back on its beat.
-- **A swipe is reported where it comes to rest**, not beat by beat as it passes; the scroll the
-  graph makes itself is never reported. The scrubber reads the beat from where the thumb lifts.
-- **Fine mode and go-to-number** on the scrubber: ninety beats across a phone is four pixels a
-  beat; a resting thumb gets twelve, and the counter takes "60".
-- **Cards open their beat**; rings are thicker and more opaque; nothing in the graph is under
-  10px; the scrubber has a visible keyboard focus ring.
-- **`ValidationIssue.elementIds`**: a sequence clash names its beats, once per clash.
-- **A crossing costs two beats, not ninety** (0.7.2): beat marks are memoised behind one stable
-  click handler, so the scrubber no longer drags a full re-render of the line behind the thumb.
-  Fine mode reads the pause from event timestamps (0.7.1): a timer fired mid-slide on a busy page.
-- Held for Guillaume: a tone palette where each axis owns a hue family. Three axes currently share
-  purples (opinion, power, transcendence), which a phone cannot tell apart; the prototype's
-  palette is kept until that is decided.
-
-## Status — 2026-09-19 (phone round)
-
-The studio was built at a desk and read on a phone. On a 390px screen the nine tabs wrapped into
-three rows and scrolled away with the page, the save sat at the top of a 32,000px beat list, the
-edit buttons appeared only on hover — which a touch screen never does — and a vertical swipe that
-started on the graph could not scroll the page past it. What changed (0.6.0, and `app/ncp`):
-
-- **`<BeatScrubber>`** — one tick per beat, coloured by tone, signposts tallest. A thumb runs along
-  ninety beats in one stroke; the graph or the list follows it. It rides in the studio's sticky bar
-  in both the graph and the beats view.
-- **The graph on touch is a carousel.** `snap` settles one beat at the centre; `followFocus` scrolls
-  a linked beat into view (before, `?view=graph&beat=x` opened on beat 1); `onCenteredBeatChange`
-  lets the host know where the reader is. Vertical swipes pass through to the page.
-- **Shorter cards, shorter canvas.** Cards clamp to three lines; the canvas drops from 720 to 480.
-- **In the app:** a bottom bar on phones (overview · graph · beats · ask · more), a views sheet and
-  the chat as sheets over the shared `DragSheet` (jgwill/Miadi#381), a sticky status bar with the
-  save, beats that filter by words and appreciation and fold into an outline, card actions shown on
-  touch, 16px fields so iOS does not zoom into every edit, and whole-card links on the project list.
-
-## Status — 2026-09-19 (navigation round)
-
-Four things a reader asked for after using it:
-
-- **The line is navigable.** Drag the empty space to pan; arrow keys scroll it, shift for a longer
-  step, Home and End for the ends. A press that starts on a beat still opens that beat.
-- **Compact says something.** It was circles; now each mark carries its narrative function, its
-  summary and its three tone letters, so a ninety-beat story is readable at a glance.
-- **Cards are the default at every length** — the card is what makes a beat readable, and the line
-  is now navigable, so length is no longer a reason to hide them. Compact is one click away.
-- **Every view is reachable without dragging.** The tab bar wraps; `terminology` was hidden behind a
-  sideways scroll.
-- **Validation reads as three things**: what to fix, what the story extends (declared, not drift),
-  and what is worth knowing — each group counted once with its places behind a disclosure, instead
-  of sixty-three identical lines.
-
-## Status — 2026-09-15 (interface round)
-
-The surface was refined against the prototype it is modelled on, which had a visual language the
-rebuild had not carried across:
-
-- **The graph draws cards again.** A node is a numbered mark with three tone rings that turn slowly;
-  above the line its card carries the appreciation, the perspective, the summary and the
-  illustration; below it a panel names each tone axis with its colour. The headless layout is
-  unchanged — this is presentation over the same geometry — so a server still draws the same SVG.
-- **Beats are a timeline, not a list.** A gradient spine with the sequence circles sitting on it and
-  the cards alternating left and right, each card carrying its tone triad as A/S/T chips. Editing
-  opens in place and closes back into the same shape.
-- **Every element view is a card** in the prototype's shapes: perspectives with a point-of-view
-  badge, players with an avatar and their visual and audio lines, storypoints with an appreciation
-  eyebrow and a function chip, dynamics with their vector.
-- **One room, one light.** `app/ncp` uses the prototype's slate ground with indigo, purple and pink
-  accents rather than the portal's neutral tokens — the studio is its own room, and the rest of the
-  portal keeps its own.
-- **The view is in the URL.** `?view=graph&beat=<id>` — a link can point at a story's graph, or at
-  one beat inside it, and a reload lands where it left.
-- **The tab bar counts.** Each view says how much it holds.
-
-## Status — 2026-09-12 (second round)
-
-A third review — a parity audit against the prototype — returned 14 gaps. What closed:
-
-- **The six teaching stories are back.** Catalyst of Change, Echoes of the Past, Tushell and the
-  Orchestra of Agents, The Keeper Chronicles, The Bridge Walker, The Archive Keeper — every beat
-  toned. Catalyst is assembled from its source document plus the enrichment table the prototype
-  kept separately, so it arrives with its 90 toned beats, 23 moments and 5 overviews (the
-  prototype's own adapter dropped 22 of those moments).
-- **The agent reads the whole story.** The digest threshold was 60k, and the seed story is ~80k, so
-  the studio's own narrative reached the model as an index. Default is 400k now.
-- **A story can be read**: beat storytelling and illustration without opening an editor, tone names
-  beside the colours, storypoint and player storytelling rendered, perspective references named.
-- **The graph says what its colours mean** — a legend, and every node describes itself in words.
-- **Terminology is a place**: `/ncp/terminology`, all 255 terms by section plus the legacy table.
-- **The chat is a chat**: a welcome, a thinking indicator, auto-scroll, and a drawer on a phone.
-- **A story can bring its own reading positions** — the persona registry is open, so the prototype's
-  guest voices (a wise owl, a data dolphin) can be registered without changing this package.
-
-Both of those are now closed. A story's guest voices reach the prompt: asking *Tushell and the
-Orchestra of Agents* about its first beat answers as 🧠 Mia · 🌸 Miette · 🎨 Ava8 · 🌊 Tushell ·
-🦉 Wise Owl, and the Keeper Chronicles answer with 🌀 Miawapaskone and 🪶 Grandmother Yazhi. And the
-studio answers for real by default — `NCP_AGENT_DISABLED=1` is the off switch, not an on switch.
-A live call still needs the writer credential, because the port is publicly reachable and a model
-call costs money; a browser without it gets the prompt instead of an error.
-
-## Status — 2026-09-12
-
-Phase 1 and Phase 2 are **built and running**: `@miadi/ncp-story-studio` 0.1.0 with 86 tests, and
-`app/ncp` consuming it on port 3335. What landed, and what each phase still holds, is below; the
-module surface is in `README.md`.
-
-Verified end to end on 2026-09-12: the four bundled examples seeded into a JSON store, the studio
-rendering graph and beat editor, an edit saved from the browser through a server action to
-`story.ncp.json` on disk, a conditional `PUT` accepted and a stale one refused with 409, an
-unauthenticated write refused with 401.
-
-Two adversarial reviews ran against this work — one on the package, one on `app/ncp`. They
-returned 18 and 14 findings. All are fixed; the package half carries a regression test per finding
-(`test/review-findings.test.mjs`), and the surface half was re-verified by request:
-
-```bash
-# a server action without the credential is refused, and with it is allowed
-curl -X POST /api/ncp/session -H "Authorization: Bearer $MIADI_API_TOKEN_WRITER" -c jar.txt
-# a story that arrived invalid stays editable; an edit that adds an error does not
-curl -X PUT /api/ncp/projects/shawshank-redemption ...   # 200, preexisting_errors: 19
-# a server action and a REST PUT racing on the same version: one wins, one conflicts
-```
-
-## Phase 1 — vocabulary and data · **built**
-
-Goal: one NCP type surface everyone can produce compatible data against, and a viewer in
-`app/ncp` reading real stories.
-
-- **S1 `/schema`** — TypeScript types, a zero-dependency validator (Zod was dropped: a published
-  package should not pin a validation library on its consumers), the canonical JSON Schema as an
-  asset, and fixtures, from the
-  canonical schema (29 appreciations, 148/144 narrative functions, 9 dynamics × 16 vectors,
-  3-axis tones, 6 audience POVs, `moments.fabric`). Prototype-only fields
-  (`custom_appreciation`, `custom_narrative_function`, `Player.motivations`,
-  `Perspective.throughline`) become **declared extensions**; `pov` renames to
-  `author_structural_pov`. No Wampum fields in the model at this phase.
-- **S2 `/graph`** — the story lattice as a real component package (headless layout + React
-  renderer), consumed by `app/ncp`, not copied into it.
-- **S9 examples + terminology** — the 5 canonical examples, the 5 prototype narratives, and
-  `docs/terminology/` as data behind a browser view. Teaching surface is first-class, not a
-  by-product.
-- **`app/ncp` v1** — project list, story viewer, graph view, reading from the store provider.
-
-## Phase 2 — editing and story projects · **built**
-
-- **S3 `/editor`** — CRUD for beats / players / storypoints, drag-reorder, dynamic perspectives,
-  live validation with structural-tension alerts. **Two storage providers behind one
-  interface: JSON files and Neon (Postgres).** Story projects are managed, not held in a tab.
-- **S4 `/agents`** — the `[[Beat|Player|Perspective|Point:ID|Label]]` link protocol as its own
-  parser module, and a provider-neutral model adapter (the prototype hard-codes one vendor and
-  one model string). Personas: 🧠 Mia structural, 🌸 Miette narrative, 🎨 Ava8 musical.
-- **S12 chronicle ↔ story** — import episode material into a story, and surface a story inside
-  an episode. Both directions, reusing `@miadi/inquiry-weave` and the chronicle readers in
-  `app/chronicle/lib/`.
-- **S10 import / export** — NCP JSON in and out, then reuse what Miadi already publishes:
-  `@miadi/voice` for spoken readings, the Twine promotion path for a readable book,
-  `@miadi/musical-composition-to-episode` for composition links.
-
-### What Phase 1 and 2 taught, and what changed because of it
-
-- **Three dialects, not one.** The canonical schema, the subtxt exports, and the Catalyst design
-  file disagree about shape *and* vocabulary. One reader now recognizes each and reports every
-  adaptation, which is what lets all four examples open in the same studio.
-- **The canonical `required` lists name every field.** No shipped example satisfies them, so the
-  studio validates what a studio needs by default and enforces the schema's own lists on request.
-- **Beat `sequence` numbers a series, not a narrative.** Signposts 1-4 and progressions 1-16 are
-  separate runs inside one throughline; uniqueness is checked per series.
-- **An adversarial review found 18 defects** in the first cut, the worst of which deleted a store
-  root. Every one is fixed with a named regression test in `test/review-findings.test.mjs`.
-
-## Phase 3 — relational and symphonic readings
-
-- **S11 Ava8 × NCP** — Ava8 is a musical orchestra agent, not a name collision. Relate story
-  `moments` to musical structure and explore symphonic capability inside a story. RISE specs
-  drafted during Phase 1–2 so this phase has ground to stand on.
-- **S5 Wampum** — specs first (`rispecs/wampum-narrative-engine/` already holds the belt model,
-  the `project`/`read` bridge with its `crossing_report`, and the four-layer perspective
-  prompt). First concrete artifact: **Catalyst of Changes rendered in belt form**, to look at
-  and reflect on, before any schema support lands.
-- **S6 governance** — the ground is now local and pinned. The three research packets were carried
-  into `foundations/` on 2026-09-20 from `avadisabelle/holisticagnostic-narrative-context-protocol`
-  at `0ce09365` (an unmerged branch — see each packet's `carried-from.yaml`), and the five layers
-  are specified one folder each in `rispecs/governance/`: transmission conditions, relational
-  provenance, linguistic frame, performativity, semantic access control. Nothing is implemented,
-  deliberately — only the layers a later phase proves it needs, and the refusal gate the Wampum
-  perspective layer already requires.
-
-## Phase 4 — narrative workflow runtime
-
-**S7** — goals, candidate trajectories, state versions, budgets, termination authority. The
-spec needs revision before it is built; it is not Phase 1 material.
-
-## Phase 5 — three universes
-
-**S8** — Engineer / Ceremony / Story validators returning evidence rather than a score.
-Deliberately last: elements of the model resemble it already, and introducing it early would
-confuse the vocabulary. It gets integrated where it belongs, not early.
-
-## The spec lane that runs through every phase
-
-Specifications advance even where implementation does not.
-
-- `rispecs/governance/<layer>/` — one folder per layer: transmission conditions, relational
-  provenance, linguistic frame, performativity, semantic access control. Each states who the
-  teller and receiver requirements are, what the layer means, and how it sits in the model.
-  Kept alive as later phases reveal what governance actually has to do. If a phase needs part
-  of it early, that part gets analysed and implemented then — not pre-built.
-- Wampum specs and the Ava8 × NCP spec, written ahead of their phase for the same reason.
-
-## Consumption inside `app/`
-
-- **C1** — publish order: schema, then the graph component, then editor, then agents. Headless
-  first: validators and layout carry no React so route handlers can use them; the React
-  renderer ships behind a subpath export (`@miadi/attention-ui` is the local precedent).
-- **C2** — `workspace:*` in the root `package.json` while exports move; published semver once
-  they settle. Every manifest change updates `pnpm-lock.yaml` with scoped install/build/test.
-- **C3** — surface: `app/ncp` (projects), `app/ncp/studio/[storyId]` (the studio),
-  `app/api/ncp/*` (validate, stories, later projections). Pattern to copy:
-  `app/chronicle/lib/*.ts` and `app/chronicle/[episode]/page.tsx` importing
-  `@miadi/episodic-memory-schema`, `@miadi/inquiry-weave`, `@miadi/tide` server-side.
-- **C4** — validation runs server-side, where its record can be persisted.
-- **C5** — storage provider chosen by environment: JSON files under a stories root, or Neon.
-  Browser storage only for per-viewer conveniences.
-- **C6** — `app/live-story-monitor` and `app/narrative-lattice` become consumers of these
-  packages. Today `app/narrative-lattice/page.tsx` runs on fixtures from
-  `@/types/live-story-monitor-data`; they need feeding from the same schema and provider.
-- **C7** — port 3335 is the single surface: dev mode while building, prod rebuild when
-  shipping, and state what is shipping from an untracked tree before rebuilding.
-
-## What this gives Concordia
-
-- **K1** — an authorship record a rights or ethics review can read: state version, agent and
-  role, model, prompt, schema version, approvals, rejected alternatives.
-- **K2** — per-field artifacts for the faculty alignment open as `jgwill/Miadi#611`–`#614`.
-- **K3** — the Martin Lefebvre report in this folder is a literature anchor for the
-  narrative-theory framing. Cite from it; do not specify from it.
-- **K4** — a seminar-ready teaching surface: terminology browser and worked example stories,
-  with governance handling stated in the data rather than promised in prose.
-
-## Risks that set the order
-
-- **R2** — schema divergence between the prototype types and the canonical schema. Freeze S1
-  before porting any UI.
-- **R3** — the schema repo is not vendored here (its only submodule is `llms`). Pin it or copy
-  the schema with a version stamp, or the enums drift silently.
-- **R1** — cultural protocol. Deferring Wampum out of Phase 1 removes this from the critical
-  path. When it returns: public seed belts only, no community-specific readings without
-  consent, and the refusal gate exists before any generated reading ships.
-
-## Stale claims in `AGENTS.md` (do not carry forward)
-
-- The version table. Real versions today: `@miadi/episodic-memory-schema` 0.10.0, `@miadi/tide`
-  0.4.0, `@miadi/tide-contract` 0.3.0, `@miadi/hooks-core` 0.5.0, `@miadi/a2a-contracts` 0.1.1.
-  Read the manifests, per the `miadi-package-truth` skill.
-- `pnpm add @miadi/ncp-story-studio` — no manifest, nothing published yet.
-- `@miadi/three-universe-processor` appears in issue prose only; no such package exists.

package/rispecs/README.rise.md

@@ -1,5 +0,0 @@
-# RISE README: @miadi/ncp-story-studio
-
-NCP story studio for story studio workflows for narrative continuity and production planning.
-
-Read `./RISPEC.md`, check `../package.json`, and use the narrowest package needed. Indexed from root `llms.txt` and `llms-full.txt`.

package/rispecs/RISPEC.md

@@ -1,9 +0,0 @@
-# RISPEC: @miadi/ncp-story-studio
-
-RISE = Reverse-engineer, Intent-extract, Specify, Export.
-
-Purpose: story studio workflows for narrative continuity and production planning.
-Install: `pnpm add @miadi/ncp-story-studio` or workspace `pnpm -w add @miadi/ncp-story-studio@workspace:* --filter <consumer-package>`.
-Contract: public exports, schemas, CLI flags, or adapter payloads owned by this package.
-Authority: `package.json`, source exports, tests, and release metadata remain truth.
-Handoff: verify exports, examples, test evidence, and publish/stub/deprecated status.