---
name: story
description: Tell a repository's artifact-backed story, answer a question with a dated chapter, or refresh stale story pages.
---

# Repository story

Produce cited HTML stories from MyFlow artifacts. The CLI extracts facts, validates page sources, and renders pages; you write only the narrative. Read [page-source.md](references/page-source.md) and the [authoring checklist](references/authoring-checklist.md) before writing, then read the shipped lens specifications in `lenses/`. For an external theme, see [styling.md](references/styling.md).

1. Run `node ../myflow/scripts/resolve-repository-map.mjs discover --cwd <git-root>` from this skill's directory. Read the selected map. Derive `<repository-dir>` as the parent of `workstreamRoot` and `<store-root>` as the ancestor of its `repositories/` directory. If `storeMode` is `checkout`, stop: stories require the home store. Identify the repository's `<identity>` relative to `<store-root>/repositories/`.
2. Run `node ../myflow/scripts/cli.mjs artifacts pull --cwd <git-root>`. Then run `node scripts/story.mjs facts --repository-dir <repository-dir>` and `node scripts/story.mjs status --repository-dir <repository-dir> --store-root <store-root>`. Re-read facts each run; do not save facts as an artifact. Pull before writing so chapters from other machines are present. Pull restores missing files but does not overwrite local files.
3. Read the cited artifacts from the facts, not only the summaries. Read each shipped lens spec from `lenses/`, then any `<repository-dir>/story/lenses/*.md`: the repository version replaces a shipped lens of the same name and new names add panels. Keep artifact links relative to the resulting output page. Check existing chapters and sources in `story/src/` before continuing.
4. On a first run, use the facts' proposed eras as a starting point; split or rename by theme if the record supports it. Write a main source with one distinct panel per lens, a workstream source for every workstream, and a dated chapter source per era. Seed the chapters before assembling the main page so its ledger includes them.
5. When asked a question, normally write one new chapter that builds on earlier chapters, then rewrite the main source to include it. Chapters normally stay stable, including those from older workstreams, but a deliberate revision or supersession is allowed when the record changes. Ordinary assembly is write-once: follow the checked revision procedure in [page-source.md](references/page-source.md), never silently overwrite a chapter. Rewrite each stale workstream or main page source reported by `status`; do not rewrite unchanged chapters.
6. Assemble each page with `node scripts/story.mjs assemble --src <source-file> --repository-dir <repository-dir> --store-root <store-root>` (chapters first, main last). The command copies each source into `story/src/`. Then run `node scripts/story.mjs index --store-root <store-root>` and rerun `status` until it reports no stale pages. Follow the authoring checklist's local link, report-link, date-map, tab and reader checks before delivery; leave unavailable reader checks pending.
7. Before sync, compare local existing chapter pairs with remote versions and reconcile stale local copies: pull restores missing files but never overwrites local edits, and existing-file sync is last-push-wins. Sync with `node ../myflow/scripts/cli.mjs artifacts sync --cwd <git-root> --path repositories/<identity>/story --path repositories/index.html`. Inspect the JSON receipt; a failed sync is not a successful delivery. Whole-story sync refuses remote chapters missing locally; pull and reconcile rather than bypassing the guard. For intentional exact-path removal, follow [page-source.md](references/page-source.md): sync the updated main HTML/source and `story/state.json`, the deleted chapter HTML/source paths, and all changed inbound HTML pages and their sources in the same path-scoped invocation; verify the remote links and ledger together.

## Narrative rules

- Cite every factual claim with a relative link to at least one synced Markdown artifact under the narrated repository; raw observations, JSONL and store configuration are not narrative citations. If only a journal supports an exact claim, narrow the prose to what a Markdown record actually supports; each narrative section needs a citation. Cite both sides when the record disagrees. Never resolve a conflict silently.
- Compare every summary count you quote against the facts and cite both sides of a mismatch. Prefer journal and frontmatter tiers over prose, and retain the source's uncertainty. An open choice is not a reversal until the record shows one.
- Write in plain, global English. Distinguish evidence, interpretation, and missing evidence. Feedback ratings are context, not a verdict; show them beside stage attempts, returns, corrections, Verify outcomes, and gaps in the Friction lens.
- Keep narrative within the page-source schema and allowed tags. Never insert external resources or styling into a page source. Story pages quote artifacts into the same private remote as the underlying record; review sensitive detail before syncing.