@miadi/inquiry-weave 0.8.0 → 0.8.1

package/README.md

@@ -1,350 +1,208 @@
 # @miadi/inquiry-weave
 
-Relate and sync three identities of one inquiry — and never write the inquiry itself.
+`inquiry-weave` keeps three identities in relation:
 
-```
-        ┌────────────────────────────┐   inquire (vessel + issue)   ┌──────────────────────┐
-        │  Inquiry artefact          │ ◄─────────────────────────── │  Chronicle episode   │
-        │  $MIADI_INQUIRY_ROOT/<dir> │                              │  <chronicle>/<date>- │
-        │  (IAIP tree —              │ ───────────────────────────► │  episode-NNN-<slug>/ │
-        │   system-of-record)        │   promote / sync (mirror)    │    inquiry/<dir>/    │
-        └─────────────┬──────────────┘                              └──────────┬───────────┘
-                      │                                                        │
-                      │            ┌────────────────────────┐                  │
-                      └──────────► │  GitHub issue          │ ◄────────────────┘
-                        .weave.yaml│  owner/repo#N          │ inquiry/weave.yaml
-                                   └────────────────────────┘
-```
-
-## The three identities (worked example: ep126 / #245)
-
-| Identity | Example |
-|---|---|
-| Inquiry artefact | `/src/IAIP/prototypes/artefacts/ep126-mila-ai-event-260715-b08218a8-…` |
-| GitHub issue | `miadisabelle/Etuaptmumk-RSM#245` |
-| Chronicle episode | `…/miadi-chronicle/2026-07-13-episode-126-mila-ai-indigenous-gathering/` |
-
-This package generalizes the manual prior art (`<episode>/inquiry/_sync.sh`, a one-way tar
-copy) into a repeatable workflow: `relate`, `promote`, `inquire`, `sync`, `status`.
+- an inquiry artefact in the IAIP artefact shelf;
+- its GitHub issue;
+- the Chronicle episode that carries it.
 
-## The mystery boundary
+It creates issues with the portable `gh` CLI, records both shores of the
+relation, syncs the artefact into the episode, and registers the weave. It does
+not depend on private host scripts or private cache folders.
 
-**The package never generates inquiry content.** Creating an inquiry's substance — the
-question, the search, the listening — is human work and stays that way. `inquire` creates
-only the *vessel*: a named empty directory, its GitHub issue, and the relation metadata.
-This boundary is enforced by an executable test (the vessel must contain relation
-metadata only).
+## Install
 
-## CLI
-
-```
-inquiry-weave relate   --artefact <name|path> --episode <num|name|path> [--issue owner/repo#N]
-inquiry-weave promote  --artefact <name|path> (--episode <ref> | --new-episode <slug> [--title <t>])
-inquiry-weave inquire  --episode <ref> --slug <slug> [--title <t>] [--repo owner/repo] [--no-issue]
-inquiry-weave sync     (--artefact <ref> [--episode <ref>] | --episode <ref> [--all])
-inquiry-weave status   (--episode <ref> | --artefact <ref>) [--json]
-inquiry-weave register (--episode <ref> | --artefact <ref>) [--dry-run]
-inquiry-weave lineage  --from <ref> --to <ref> --relation <text> [--kind …] [--reverse]
-inquiry-weave catalog  [--chronicle-root <dir>] [--series <name>] [--json]
-inquiry-weave stories  [--stories-root <dir>] [--json]
-```
-
-Global flags: `--inquiry-root`, `--chronicle-root`, `--stories-root`, `--repo`, `--mw-url`,
-`--dry-run`, `--json`.
-Exit codes: `0` ok, `1` operational error, `2` usage/resolution error (ambiguous episode
-numbers list their candidates — duplicates exist in the wild).
-
-`--dry-run` is **global**: every mutating command (`relate`, `promote`, `inquire`, `sync`,
-`register`) previews its plan and returns exit 0 without writing to the IAIP tree,
-the chronicle, GitHub, or medicine-wheel. The projected plan matches the live output
-apart from its prefix (`would <verb>:` on relation lines, `dry-run:` on sync lines), and
-— like a live run — a standalone `sync` still refuses an artefact that is not related to
-the episode. Fixed in v0.4.1 — prior to v0.4.1, `inquire`/`relate`/`promote` mutated real
-state during a dry run. v0.4.2 restores the not-related guard on `sync --dry-run` (only
-`promote` previews an as-yet-unpersisted relation).
-
-## The two catalogs
-
-`catalog` and `stories` expose the package's two read-models — the same manifests
-`app/chronicle` renders — so a person can ask what exists without reading TypeScript.
-Both are read-only: they walk a root and print, and write nothing anywhere.
-
-```
-$ inquiry-weave stories
-stories: /home/mia/Documents/Twine/Stories
-  14 on the shelf · 4 episode(s) indexed · 4 carrying no episode number
- 131 html      Episode 131 _ Every Device_ One Song.html
-  44 directory Episode-044-Decompose-and-Begin-Again
-  -- html      the-room-lent-it-ears.html
-  …
-  episodes: 40(1) 44(2) 131(3) 311(4)
+```bash
+npm install -g @miadi/inquiry-weave passages
+gh auth status
 ```
 
-The `--` rows are the finding, not noise: `linkStoryForms` attaches a story to an episode
-by the number parsed from its name, so a story carrying none is reachable from no episode
-room. The count is printed on its own line for exactly that reason.
-
-`catalog` prints the chronicle the same way — episode number, `yaml` (structured) or
-`name` (the older `script.md` era), folder, title — followed by the manifest's diagnostics
-(`episode-number-collision`, `unsafe-artifact-path`, …) as `note:` lines.
-
-**Ownership.** `@miadi/episodic-memory-schema` declares the chronicle→book edge
-(`StoryManifestEntry`, `linkStoryForms`, `EpisodeManifestEntry.stories`); this package
-*enumerates* it (`buildStoryLibraryCatalog`) and relates it. It never authors a story —
-deriving a book from a vessel belongs to `packages/passages`.
+`passages` owns canonical episode birth through `mkepisode`. `inquiry-weave`
+owns issue/artefact/episode relation and offers a compatibility episode
+scaffold for combined one-command inquiry flows.
 
 ## Environment
 
-| Variable | Fallback chain | Default |
-|---|---|---|
-| `MIADI_INQUIRY_ROOT` | → `INQUIRY_ROOT` | `/src/IAIP/prototypes/artefacts` |
-| `MIADI_CHRONICLE_ROOT` | — | `/srv/miadi/episodes/miadi-chronicle` |
-| `MIADI_STORIES_ROOT` | — | `/home/mia/Documents/Twine/Stories` |
-| `MIADI_INQUIRY_REPO` | — | `miadisabelle/Etuaptmumk-RSM` |
-| `INQUIRY_WEAVE_ISSUE_LIB` | → `/a/src/scripts/fn_github_issue.sh` → `/src/scripts/fn_github_issue.sh` | — |
-| `MW_API_URL` | — | `http://127.0.0.1:8040` |
-
-## Metadata contract
-
-`weave.yaml` / `.weave.yaml` — written and owned by this package — is the authoritative
-record of the relation. Sync state lives episode-side only, so the artefact-side file can
-be mirrored verbatim without a self-invalidating hash loop.
-
-**Episode side, `<episode>/inquiry/weave.yaml`:**
-
-```yaml
-weave: 1
-episode:
-  number: 126
-  slug: mila-ai-indigenous-gathering
-  path: 2026-07-13-episode-126-mila-ai-indigenous-gathering
-inquiries:
-  - artefact: ep126-mila-ai-event-260715-b08218a8-0441-4596-a16e-47483d3ab57c
-    issue: miadisabelle/Etuaptmumk-RSM#245
-    issue_url: https://github.com/miadisabelle/Etuaptmumk-RSM/issues/245
-    related_at: 2026-07-15T00:00:00.000Z
-    last_sync:
-      at: 2026-07-15T00:00:00.000Z
-      tree_sha256: <sha256 of the sorted relpath:filehash:size manifest>
-      file_count: 4
-      bytes_total: 341001
-```
-
-**Artefact side, `<artefact>/.weave.yaml`:**
-
-```yaml
-weave: 1
-artefact: ep126-mila-ai-event-260715-b08218a8-0441-4596-a16e-47483d3ab57c
-issue: miadisabelle/Etuaptmumk-RSM#245
-issue_url: https://github.com/miadisabelle/Etuaptmumk-RSM/issues/245
-episodes:
-  - path: 2026-07-13-episode-126-mila-ai-indigenous-gathering
-    number: 126
-    related_at: 2026-07-15T00:00:00.000Z
+```bash
+export MIADI_CHRONICLE_ROOT=/srv/miadi/episodes/miadi-chronicle
+export MIADI_INQUIRY_DIR=/a/src/IAIP/prototypes/artefacts
+export MIADI_INQUIRY_GITHUB_REPO=miadisabelle/Etuaptmumk-RSM
+export MW_API_URL="${MW_API_URL:-${MIADI_CHRONICLE_MW_URL:-http://127.0.0.1:8040}}"
 ```
 
-`relate` also appends the ep090-style back-link into the artefact's `AGENTS.md`
-(episode path + `related issue owner/repo#N`) — append-if-missing, never overwriting.
-
-### `.hch/` is legacy input — and an open decision
-
-`.hch/` (the issue-harness cache written by `fn_github_issue.sh` and its predecessors) is
-read **best-effort, once**, to seed `.weave.yaml` when relating a pre-existing artefact.
-Tolerated shapes: the correct `issue_<N>.env`, the V2-era bug shape (literal `issue_.env`
-with no `issue_url`), and the newest `issue_add__*.json` as fallback. This package never
-writes `.hch`.
-
-**Open decision (deliberately not settled in v0):** does `.hch` get (a) formalized as a
-shared contract across tools, (b) kept as `fn_github_issue.sh`'s private cache and mapped
-into `.weave.yaml` at relate time — v0's de-facto behavior — or (c) retired? v0 is
-compatible with all three outcomes.
+| Flag | Environment |
+| --- | --- |
+| `--chronicle-root` | `MIADI_CHRONICLE_ROOT` |
+| `--inquiry-root` | `MIADI_INQUIRY_DIR` |
+| `--repo` | `MIADI_INQUIRY_GITHUB_REPO` |
+| `--mw-url` | `MW_API_URL` |
+| `--stories-root` | `MIADI_STORIES_ROOT` |
 
-## IAIP is the external system-of-record
+`MIADI_INQUIRY_ROOT`, `INQUIRY_ROOT`, and `MIADI_INQUIRY_REPO` remain fallback
+aliases for older environments.
 
-The inquiry root lives in the IAIP tree (a checkout of `miadisabelle/Etuaptmumk-RSM`).
-Sync is one-way (artefact → episode): the episode copy is a snapshot, deletions
-propagate, and local edits to the copy are flagged as `episode-copy-diverged` before
-being overwritten.
+## Create an issue and weave the current folder
 
-**Deployment API evaluation note:** the deployment evaluated for this exposed only
-`/api/articles` and `/api/articles/seed` (which read `prototypes/artefacts` markdown into
-Redis) — there is no inquiry CRUD. It is a documented future interface; **v0 has no
-dependency on it**, so no host is named here: the URL belongs to a deployment, not to the
-package, and hard-coding one into a published README ships someone's infrastructure to
-everybody who installs it. Set `INQUIRY_WEAVE_API_URL` if a future version needs it.
+From an existing inquiry artefact:
 
-**Deferred decision, explicitly named:** absorbing IAIP into Miadi packages is out of
-scope and not planned here.
+```bash
+cd "$MIADI_INQUIRY_DIR/ep133-honcho-eval"
 
-## GitHub issues via fn_github_issue.sh
+inquiry-weave inquire \
+  --artefact . \
+  --episode 133 \
+  --title "Honcho evaluation inquiry"
+```
 
-`inquire` delegates issue creation to the sourced `issue_add` function of
-`fn_github_issue.sh` (a `gh` CLI wrapper), invoked with cwd = the artefact directory and
-an explicit `owner/repo`. The created identity is parsed from stdout (`* owner/repo#N`)
-and recorded straight into `.weave.yaml`. Issue title convention: the artefact's absolute
-path (as with #245). `--no-issue` skips creation.
+This creates the issue in `MIADI_INQUIRY_GITHUB_REPO`, writes its identity to
+`.weave.yaml`, writes the matching relation to
+`<episode>/inquiry/weave.yaml`, and adds the episode backlink to `AGENTS.md`.
+Before those writes, an unprefixed folder is renamed to
+`ep<episode-number>-<existing-folder-name>`. The prefix is mandatory once the
+episode identity is known; a destination collision stops the command.
+By default, the artefact's Markdown, text, YAML, and JSON documents become the
+issue body. Generated weave metadata, `AGENTS.md`, hidden directories, and
+binary files are excluded. Use `--body <text>` or `--body-file <path>` to
+override that derived body.
 
-## Medicine-wheel registration & forgewright visibility
+## Create a new inquiry vessel and issue
 
-`inquiry-weave register` (v0.2) projects each woven relation into medicine-wheel:
-`POST {MW_API_URL}/api/inquiry-weaves`, upsert key
-`inquiry-weave:<episode.path>:<artefact.id>`. Registration moves metadata only —
-weave files on disk stay authoritative; an unreachable medicine-wheel reports and
-exits `1` without touching them. Forgewright renders the registered weaves in its
-episode views. The contract lives in the RISE specs:
+```bash
+inquiry-weave inquire \
+  --slug honcho-eval \
+  --episode 133 \
+  --title "Honcho evaluation inquiry"
+```
 
-- `rispecs/medicine-wheel-registration.spec.md` (this package)
-- `medicine-wheel:rispecs/inquiry-weave-registration.spec.md`
-- `forgewright:rispecs/09-inquiry-weave-visibility.spec.md` (branch `4-plan-episode-visibility`)
+The new directory is named `ep<NNN>-<slug>-<YYMMDD>-<uuid>` beneath
+`MIADI_INQUIRY_DIR`. It begins with relation metadata only; inquiry content is
+written afterward by the people and practices conducting the inquiry.
 
-### Episode nodes — cards visible at birth (v0.3)
+## Create the issue and a new episode together
 
-The Chronicle UI hangs perspectives off **episode cards**; cards come from
-`/api/nodes` artifact references (`miadi.artifact-ref.v1`, kind
-`chronicle_episode`). `registerEpisodeNode(mwUrl, input)` registers that card:
-it preflights `GET /api/nodes/chronicle:<episode-dir-name>` (an existing card is
-`already-registered` success, never overwritten — medicine-wheel's POST upserts)
-and otherwise POSTs the ep137-proven record. Failure is fail-open: the outcome
-is `{ state: "registered" | "already-registered" | "pending", node_id, error? }`
-and the function never throws, so vessel creation can never fail because of
-registration (jgwill/Miadi#490).
+Use an existing artefact:
 
-## Kinship with @miadi/passages
+```bash
+inquiry-weave inquire \
+  --artefact . \
+  --new-episode honcho-eval-adequate-memories \
+  --title "Honcho evaluation inquiry"
+```
 
-Episode *creation* as a first-class command (`mkepisode -n 133 -t <slug> -g "<goal>"`)
-likely belongs to `packages/passages` ("Narrative Formulations for the Miadi Chronicle").
-This package keeps its `--new-episode` scaffolding inside one exported function
-(`scaffoldEpisode`) so passages can own creation later, and inquiry-weave consumes any
-pre-existing episode regardless of its creator.
+Or create the artefact vessel, issue, episode, and weave in one command:
 
-## Chronicle repo rule
+```bash
+inquiry-weave inquire \
+  --slug honcho-eval \
+  --new-episode honcho-eval-adequate-memories \
+  --title "Honcho evaluation inquiry"
+```
 
-All work in `miadi-chronicle/` is committed directly to `main` (per its `AGENTS.md`) —
-this package writes there only when you run it, and never commits anything itself.
+Both combined forms also sync the artefact snapshot into the new episode. When
+`MW_API_URL` (or `--mw-url`) is present, the command registers the episode card
+and writes its `.mw-registration.json` receipt in the same run.
 
-## Development
+The combined form uses inquiry-weave's compatibility scaffold. For a fully
+governed episode with an explicit goal and references, create it first with
+`mkepisode`, then use `inquire --episode`:
 
-```
-pnpm --filter @miadi/inquiry-weave build
-pnpm --filter @miadi/inquiry-weave test
+```bash
+mkepisode \
+  -n 133 \
+  -t "honcho eval adequate memories" \
+  -g "Establish adequate memories for the honcho evaluation." \
+  -r "jgwill/Miadi#133"
 ```
 
-Tests are fixture-based (`node --test` in temp roots), with no network and no real `gh`
-calls (`INQUIRY_WEAVE_ISSUE_LIB` injects a fake issue lib).
-
----
-🌸: A loom, not a pen — the weave holds artefact, issue, and episode in relation so none
-drifts from the others, while the question itself stays yours to ask.
-
-## `resolve` — one chronicle reference, answered
+## Weave an issue that already exists
 
 ```bash
-inquiry-weave resolve "miadi-chronicle:311/services-inventory"
+inquiry-weave relate \
+  --artefact "$MIADI_INQUIRY_DIR/ep133-honcho-eval" \
+  --episode 133 \
+  --issue jgwill/Miadi#133
 ```
 
-```
-écoute factorisation logiciels — the relational software factory
-  [room·local] [room·tailnet] [room·public] [wheel·captures]
-  [wheel·graph] [wheel·node] [wheel·relations] [file·inventory]
-  <miadi-chronicle:311/services-inventory>
-  episode 311 · 2026-08-05-episode-311-coute-… · matched by number
-  path: /srv/miadi/episodes/…/services-inventory.json
-  modality: relational
-```
+To weave the artefact and its already-recorded issue into a newly scaffolded
+episode:
 
-Turns a `miadi-chronicle:` reference into every door it opens. Contract:
-`rispecs/miadi-chronicle-dsl/SPEC.md` (v1.1) and `SPEC-TERMINAL.md` (v1.2);
-grounding in `foundations/resource-addressing-and-terminal-hypermedia/`.
+```bash
+inquiry-weave promote \
+  --artefact "$MIADI_INQUIRY_DIR/ep133-honcho-eval" \
+  --new-episode honcho-eval-adequate-memories
+```
 
-Each bracket is its own OSC 8 hyperlink, and the canonical reference stays
-visible beside them — the OSC 8 specification says a hyperlink "should not be
-the only means of figuring out the target", and there is no way to detect
-whether a terminal supports them. `--raw` drops the escape for clean capture.
+## Sync, inspect, and register
 
-**The reference is host-free.** `miadi-chronicle:311` is the name; a base is
-chosen at render time. That is ARK's Name Mapping Authority rule — the
-resolver's hostport is identity-inert — and it is why the same reference reads
-correctly from this host, the tailnet, or the public front.
+```bash
+inquiry-weave sync --episode 133 --all
+inquiry-weave status --episode 133
+inquiry-weave register --episode 133
+```
+
+Sync is one-way from the IAIP artefact to the episode snapshot. The source
+artefact remains authoritative. Registration projects relation metadata to the
+Chronicle medicine wheel; it does not move inquiry content.
+
+`--dry-run` previews mutating commands without filesystem, GitHub, or
+medicine-wheel writes. `--no-issue` creates or relates the artefact without
+opening GitHub.
+
+## Command surface
+
+```text
+inquiry-weave inquire  (--episode <ref> | --new-episode <slug>)
+                       (--artefact <path> | --slug <new-artefact-slug>)
+                       [--title <text>] [--body <text> | --body-file <path>]
+                       [--repo owner/repo] [--no-issue]
+inquiry-weave relate   --artefact <path> --episode <ref> [--issue owner/repo#N]
+inquiry-weave promote  --artefact <path> (--episode <ref> | --new-episode <slug>)
+inquiry-weave sync     (--artefact <path> [--episode <ref>] | --episode <ref> --all)
+inquiry-weave status   (--episode <ref> | --artefact <path>) [--json]
+inquiry-weave register (--episode <ref> | --artefact <path>) [--dry-run]
+inquiry-weave lineage  --from <ref> --to <ref> --relation <sentence>
+                       [--kind continues-from|relates-to] [--reverse]
+inquiry-weave catalog  [--series <name>] [--json]
+inquiry-weave stories  [--stories-root <dir>] [--json]
+inquiry-weave resolve  <miadi-chronicle:...> [--verify] [--json]
+```
 
-| flag | does |
-| --- | --- |
-| `--json` | the full result: `canonical`, `resolution`, `artifact`, `destinations[]`, `open`, `shareable`, `path`, `modality` |
-| `--base local\|internal\|public` | lead with one door. Reorders; never removes one |
-| `--local` | lead with the file on this disk |
-| `--verify` | ask the wheel whether the episode is really on it |
-| `--raw` | no escape sequences |
+Exit codes are `0` success, `1` operational failure, and `2` usage or identity
+resolution failure.
 
-**`--verify` exists because a 200 proves nothing.** The wheel's `/graph`,
-`/nodes` and `/relations` pages are client-routed, and so is forgewright's
-chronicle view: both return 200 for an episode name that does not exist
-(measured `?episode=9999-99-99-episode-000-nope` → 200). Only
-`GET /api/nodes/<id>` discriminates, and that is what `--verify` asks.
+## Relation records
 
-**Two answers, never collapsed.** `open` is where a human click should land —
-the episode room. `path` is the bytes on this host. An earlier draft returned
-only the file, and clicking it opened a text editor on raw JSON: local-first is
-about data ownership and availability, not about presentation.
+The artefact owns `.weave.yaml`; the episode owns `inquiry/weave.yaml`, which
+also records sync hashes and counts. These files are authoritative. The
+medicine wheel is their registered projection.
 
-### Forms
+## Episode lineage
 
+```bash
+inquiry-weave lineage \
+  --from 132 \
+  --to 133 \
+  --kind relates-to \
+  --relation "The evaluation carries the prior memory contract into practice." \
+  --reverse \
+  --dry-run
 ```
-miadi-chronicle:092/126?view=wheel#scene=river   # canonical, rootless
-miadi-chronicle://092/126                        # accepted forever, normalized away
-```
-
-`//` is RFC 3986 §3.2's authority marker, so a conformant parser reads the
-first path segment as a host — `new URL("miadi-chronicle://126")` yields host
-`"126"` and an **empty path**. Producers emit rootless; parsers accept both.
-
-### Artifact segments
 
-`services-inventory` · `state-machine` · `captures` · `recordings` · `inquiry`
-· `plans`. The last four are served by the medicine wheel and are keyed by
-`episode_path` — the **full folder name**. The episode number is not a key
-there: `?episode_number=320` returns 0 records for an episode whose
-`?episode_path=<folder>` returns 1.
+Drop `--dry-run` to write both shores. The relation sentence must read
+truthfully from both episode rooms.
 
-### Fragments
-
-`#state=` and `#event=` are spellable; `#transition=`, `#parameter=`,
-`#action=` and `#source=` are not. State names are unique tree-wide (SMDF's
-V002) so they survive structural motion; transitions are addressed positionally
-and a sibling insert silently retargets the reference. Name-keyed fragments are
-durable against structural motion and **fragile against rename** — see
-`SPEC-TERMINAL.md` §4.3a.
-
-## `terminal install` — clickable references in Terminator
+## Development
 
 ```bash
-inquiry-weave terminal install --enable
+pnpm --filter @miadi/inquiry-weave build
+pnpm --filter @miadi/inquiry-weave test
 ```
 
-Writes three files and one config line, each printed:
+Tests use temporary roots and a fake `gh` executable. They make no network or
+real GitHub calls.
 
-| path | is |
-| --- | --- |
-| `~/.config/terminator/plugins/miadi_chronicle_url_handler.py` | the URL handler |
-| `~/.config/environment.d/50-miadi-chronicle.conf` | systemd user environment |
-| `~/bin/miadi-chronicle-open` | the resolver wrapper a click runs |
-| `enabled_plugins` in the Terminator config | only with `--enable`, after a backup |
-
-Then restart Terminator and **Ctrl+click** a `miadi-chronicle:` reference
-anywhere in its output. Plain click needs `link_single_click = True`.
-
-`--force` overwrites, `--dry-run` previews, `terminal uninstall` reverses it,
-`terminal show` prints the paths. Running install twice is safe.
-
-**Why a plugin when OSC 8 exists.** Terminator has two click paths: an OSC 8
-hyperlink calls `open_url(prepare=False)` and goes straight to `xdg-open`,
-while a regex match calls `prepare=True` — the only path that consults
-`url_handler` plugins. So the plugin covers what OSC 8 structurally cannot: a
-bare `miadi-chronicle:311` in output that knows nothing about miadi — a git
-log, a grep hit, an agent's raw text.
-
-**Why the environment drop-in.** A GUI process inherits nothing from your
-shell, so `MIADI_URL_BASE`, `MW_API_URL` and `MIADI_CHRONICLE_ROOT` are absent
-at click time and every click falls back to localhost. `environment.d` is the
-OS's own answer — read by systemd's user-environment generator at session
-start, so every GUI process in the session inherits it. Takes effect at the
-next login; the wrapper carries the same values as a fallback until then.
-Test with `env -i`, which is the real click condition. See `jgwill/Miadi#620`.
+---
+
+🌸 `passages` opens the governed episode vessel. `inquiry-weave` ties the
+living inquiry, its issue, and that episode together without pretending they
+are the same thing.

package/dist/artefact.d.ts

@@ -11,6 +11,14 @@ export interface ArtefactIdentity {
 }
 export declare class ArtefactResolutionError extends Error {
 }
+export interface PrefixArtefactResult {
+    artefact: ArtefactIdentity;
+    renamedFrom?: string;
+}
+/** Give a prepared artefact its episode identity before issue/weave writes. */
+export declare function ensureEpisodePrefix(artefact: ArtefactIdentity, episodeNumber: number, options?: {
+    dryRun?: boolean;
+}): Promise<PrefixArtefactResult>;
 export declare function resolveArtefact(inquiryRoot: string, ref: string): ArtefactIdentity;
 export interface ArtefactNameParts {
     episodeNumber: number;

package/dist/artefact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artefact.d.ts","sourceRoot":"","sources":["../src/artefact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,qBAAa,uBAAwB,SAAQ,KAAK;CAAG;AAErD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAclF;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAIlE;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,OAAO,CAAC,CAUlB"}
+{"version":3,"file":"artefact.d.ts","sourceRoot":"","sources":["../src/artefact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,qBAAa,uBAAwB,SAAQ,KAAK;CAAG;AAErD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,+EAA+E;AAC/E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,gBAAgB,EAC1B,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAc/B;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAclF;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAIlE;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/artefact.js

@@ -5,12 +5,28 @@
  * directory and nothing else. The inquiry's substance is written by humans
  * (and their chosen ceremonies), never by this package.
  */
-import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, rename } from "node:fs/promises";
 import { existsSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { basename, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 export class ArtefactResolutionError extends Error {
 }
+/** Give a prepared artefact its episode identity before issue/weave writes. */
+export async function ensureEpisodePrefix(artefact, episodeNumber, options = {}) {
+    if (/^ep\d+-/.test(artefact.name))
+        return { artefact };
+    const targetName = `ep${episodeNumber}-${artefact.name}`;
+    const targetDir = join(dirname(artefact.dir), targetName);
+    if (existsSync(targetDir)) {
+        throw new ArtefactResolutionError(`cannot prefix artefact: destination already exists: ${targetDir}`);
+    }
+    if (!options.dryRun)
+        await rename(artefact.dir, targetDir);
+    return {
+        artefact: { name: targetName, dir: targetDir },
+        renamedFrom: artefact.dir,
+    };
+}
 export function resolveArtefact(inquiryRoot, ref) {
     const trimmed = ref.trim().replace(/\/+$/, "");
     const candidates = [

package/dist/artefact.js.map

@@ -1 +1 @@
-{"version":3,"file":"artefact.js","sourceRoot":"","sources":["../src/artefact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"artefact.js","sourceRoot":"","sources":["../src/artefact.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAOxE,MAAM,OAAO,uBAAwB,SAAQ,KAAK;CAAG;AAOrD,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAA0B,EAC1B,aAAqB,EACrB,UAAgC,EAAE;IAElC,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;IACtD,MAAM,UAAU,GAAG,KAAK,aAAa,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAA;IACxD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,CAAA;IACzD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,uBAAuB,CAC/B,uDAAuD,SAAS,EAAE,CACnE,CAAA;IACH,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IAC1D,OAAO;QACL,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE;QAC9C,WAAW,EAAE,QAAQ,CAAC,GAAG;KAC1B,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAmB,EAAE,GAAW;IAC9D,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG;QACjB,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC;QAC1B,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;KACjD,CAAA;IACD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,SAAS,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;YAC/D,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAA;QACtD,CAAC;IACH,CAAC;IACD,MAAM,IAAI,uBAAuB,CAC/B,uBAAuB,GAAG,kBAAkB,WAAW,iBAAiB,CACzE,CAAA;AACH,CAAC;AASD,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAA;IACrC,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;IAChE,OAAO,KAAK,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,IAAI,IAAI,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,EAAE,CAAA;AACzF,CAAC;AAMD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAmB,EACnB,IAAY,EACZ,UAAiC,EAAE;IAEnC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;IACnC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;IACtB,CAAC;IACD,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,uBAAuB,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAA;IAChF,CAAC;IACD,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACrC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAA;AACtB,CAAC;AAOD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAmB,EACnB,KAAoB;IAEpB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;IAC/C,IAAI,QAAQ,GAAG,EAAE,CAAA;IACjB,IAAI,UAAU,CAAC,QAAQ,CAAC;QAAE,QAAQ,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;IACrE,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC;QAAE,OAAO,KAAK,CAAA;IACzD,MAAM,KAAK,GAAG,CAAC,KAAK,KAAK,CAAC,cAAc,IAAI,CAAC,CAAA;IAC7C,IAAI,KAAK,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;IAC3D,MAAM,SAAS,GAAG,QAAQ,KAAK,EAAE,IAAI,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IACxE,MAAM,UAAU,CAAC,QAAQ,EAAE,GAAG,SAAS,GAAG,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC7F,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,OAAO,EAGL,gBAAgB,EAIjB,MAAM,cAAc,CAAA;AAkCrB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;IACzC,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CAC1C;AAED,MAAM,WAAW,aAAc,SAAQ,OAAO,CAAC,UAAU,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AA24BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEzF;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAaH,OAAO,EAGL,gBAAgB,EAIjB,MAAM,cAAc,CAAA;AAuCrB,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;IACzC,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;CAC1C;AAED,MAAM,WAAW,aAAc,SAAQ,OAAO,CAAC,UAAU,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAg/BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkEzF;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}