Narraitor repo orientation
1. Purpose
Get a cold session productive in minutes: where things live, which commands exist, which docs are canonical, and which claims to distrust. This is the map, not the manual — deeper rules live in the sibling skills.
2. When to use
- First substantive action in a fresh session or after a long gap.
- Any "where is / where do I look" question about this repo.
- Before citing a doc's claim about structure, tooling, or design-system canon.
3. When not to use
- You already know the target file — go read it.
- Authoring new components/stores/routes → use
narraitor-architecture (conventions) and narraitor-architecture-contract (invariants).
- Debugging a concrete failure →
narraitor-debugging-playbook.
4. Inputs required
None. Repo checkout on develop (run git fetch && git status first — never orient against a stale checkout).
5. Procedure
- Read
CLAUDE.md (repo root) — the operating manual. Then this map.
- Locate by concern:
| Concern |
Look here first |
| App data / state |
src/state/ — one Zustand store per domain; persistence seam src/state/persistence.ts (IndexedDB db narraitor-state) |
| Cross-store cascades |
src/lib/state/storePubSub.ts + src/state/storeEventWiring.ts |
| AI generation |
src/lib/ai/ — model strings in src/lib/ai/config.ts; client fetch seam src/lib/ai/aiFetch.ts; server key resolution src/lib/ai/resolveApiKey.ts |
| Prompt templates |
src/lib/promptTemplates/ (registry: narrativeTemplateManager.ts); context/token budget in src/lib/promptContext/ |
| Server endpoints |
src/app/api/**/route.ts (19 routes: narrative/, generate-, ai/, inventory/) |
| Client→API seam |
src/lib/api/ — components call these services, never raw fetch (dependency-cruiser enforces) |
| UI components |
src/components/<Domain>/ with co-located .css; stories centralized in src/stories/ |
| Theming / tokens |
src/lib/theme/themes/{_shared-tokens,ds3}.css; ThemeProvider.tsx; localStorage narraitor-color-scheme (light/dark only — ADR-013 deleted DS1/DS2 and the narraitor-theme key with them) |
| Pages |
src/app/ (App Router); dev harnesses under src/app/dev/* (knip-exempt, not production canon) |
| Unit tests |
co-located src/**/__tests__ + src/**/*.test.*; config jest.config.cjs |
| Visual/e2e tests |
tests/visual/**/*.spec.ts; baselines *-chromium-darwin.png; config playwright.config.ts |
| CI gates |
.github/workflows/ci.yml (+ playwright-tutorials.yml, codeql.yml) |
| Scripts/tools |
scripts/ — check package.json before assuming a script is wired |
- Command quick-reference (details + failure modes:
narraitor-build-test-env):
npm run dev (3000 main / derived port in worktrees) · npm run storybook (6006) · quality gate = npm test + npm run type-check + npm run lint + npm run lint:css.
- Docs of record:
public_docs/ (ADR-001…012 under public_docs/architecture/, roadmap at public_docs/development/mvp-roadmap.md), README.md, DESIGN.md, .github/ templates.
- Check the do-not-trust list (below) before acting on any doc claim.
6. Evidence required
Before repeating any structural claim (path, script, route, store field): confirm it with ls/glob/grep in the current tree. Docs and memories describe the past; the tree is the present.
7. Output artifact
An oriented session. If asked to summarize, produce a short "where I'll look and why" note with verified paths — not a re-dump of this map.
8. Common traps
- Do NOT trust blindly:
docs/ (gitignored planning vault; all point-in-time plans now under docs/plans/archive/, several completed/superseded); DESIGN.md's type-scale numbers, which are still DS1-era — the doc flags them inline and #1543 tracks the rewrite; ADR-007 and ADR-011 (historical by design — both correctly marked superseded, read them as history not guidance); and narraitor-architecture/narraitor-pattern-alignment-skill, which still carry shadcn-era mentions. Those describe the origin of the src/components/ui/ primitives, never a license to add cva/cn()/Tailwind — where they conflict with narraitor-architecture-contract, the contract wins.
- Cleared by the 2026-07-28 doc-rot sweep, don't re-flag:
ai-systems.md's gemini-2.0-flash (now points at config.ts), style-port's dead design-tokens.css path (now themes/), and the /dev/design-system* references in DESIGN.md / public_docs/design-system/README.md (present but correctly marked retired).
- Bad behavior this prevents: a session reads
DESIGN.md, navigates to /dev/design-system, finds nothing, and "helpfully" rebuilds a living style guide that was deliberately deleted.
- Port 3000 may be held by an orphan
next dev or another project — lsof -nP -iTCP:3000 -sTCP:LISTEN before blaming code.
src/app/dev/* harnesses are development sandboxes: patterns there are NOT production conventions.- No Tailwind. Plain CSS + design tokens (
var(--token)) + clsx. Any utility-class or cn() suggestion is a regression.
9. Related skills
narraitor-build-test-env (run/verify commands) · narraitor-architecture-contract (invariants) · narraitor-domain-reference (applied domain knowledge) · narraitor-failure-archaeology (settled battles) · existing narraitor-architecture (authoring conventions).
10. Provenance and maintenance
Re-verify volatile claims with:
ls src/state src/lib/ai src/lib/api src/lib/theme/themes && find src/app/api -name route.ts | wc -l (expect ~20 routes)grep -n "gemini-" src/lib/ai/config.ts (current model strings)git log --oneline -5 (has the world moved since this map?)
Last generated: 2026-07-04 (develop @ 4bec88e6)
Known uncertainty:
- Route count and
/dev/* harness list drift as features land; counts here are a snapshot.
docs/ vault contents were sampled, not exhaustively read.
1---2name: narraitor-repo-orientation3description: Fast orientation map for a zero-context session in the Narraitor repo. Use FIRST when starting work here, when asked "where does X live", "how is this repo organized", "what's the stack", "where do I look for the stores / AI code / themes / tests", or to check WHICH docs are trustworthy before acting on one. (Asking WHY something is built this way -> narraitor-failure-archaeology; fixing or correcting a stale doc -> narraitor-docs-and-writing; "where do prompts live" -> narraitor-prompt-template-governance.)4---56# Narraitor repo orientation78## 1. Purpose9Get a cold session productive in minutes: where things live, which commands exist, which docs are canonical, and which claims to distrust. This is the map, not the manual — deeper rules live in the sibling skills.1011## 2. When to use12- First substantive action in a fresh session or after a long gap.13- Any "where is / where do I look" question about this repo.14- Before citing a doc's claim about structure, tooling, or design-system canon.1516## 3. When not to use17- You already know the target file — go read it.18- Authoring new components/stores/routes → use `narraitor-architecture` (conventions) and `narraitor-architecture-contract` (invariants).19- Debugging a concrete failure → `narraitor-debugging-playbook`.2021## 4. Inputs required22None. Repo checkout on `develop` (run `git fetch && git status` first — never orient against a stale checkout).2324## 5. Procedure25261. Read `CLAUDE.md` (repo root) — the operating manual. Then this map.272. Locate by concern:2829| Concern | Look here first |30|---|---|31| App data / state | `src/state/` — one Zustand store per domain; persistence seam `src/state/persistence.ts` (IndexedDB db `narraitor-state`) |32| Cross-store cascades | `src/lib/state/storePubSub.ts` + `src/state/storeEventWiring.ts` |33| AI generation | `src/lib/ai/` — model strings in `src/lib/ai/config.ts`; client fetch seam `src/lib/ai/aiFetch.ts`; server key resolution `src/lib/ai/resolveApiKey.ts` |34| Prompt templates | `src/lib/promptTemplates/` (registry: `narrativeTemplateManager.ts`); context/token budget in `src/lib/promptContext/` |35| Server endpoints | `src/app/api/**/route.ts` (19 routes: narrative/*, generate-*, ai/*, inventory/*) |36| Client→API seam | `src/lib/api/` — components call these services, never raw fetch (dependency-cruiser enforces) |37| UI components | `src/components/<Domain>/` with co-located `.css`; stories centralized in `src/stories/` |38| Theming / tokens | `src/lib/theme/themes/{_shared-tokens,ds3}.css`; `ThemeProvider.tsx`; localStorage `narraitor-color-scheme` (light/dark only — ADR-013 deleted DS1/DS2 and the `narraitor-theme` key with them) |39| Pages | `src/app/` (App Router); dev harnesses under `src/app/dev/*` (knip-exempt, not production canon) |40| Unit tests | co-located `src/**/__tests__` + `src/**/*.test.*`; config `jest.config.cjs` |41| Visual/e2e tests | `tests/visual/**/*.spec.ts`; baselines `*-chromium-darwin.png`; config `playwright.config.ts` |42| CI gates | `.github/workflows/ci.yml` (+ `playwright-tutorials.yml`, `codeql.yml`) |43| Scripts/tools | `scripts/` — check package.json before assuming a script is wired |44453. Command quick-reference (details + failure modes: `narraitor-build-test-env`):46 `npm run dev` (3000 main / derived port in worktrees) · `npm run storybook` (6006) · quality gate = `npm test` + `npm run type-check` + `npm run lint` + `npm run lint:css`.474. Docs of record: `public_docs/` (ADR-001…012 under `public_docs/architecture/`, roadmap at `public_docs/development/mvp-roadmap.md`), `README.md`, `DESIGN.md`, `.github/` templates.485. Check the do-not-trust list (below) before acting on any doc claim.4950## 6. Evidence required51Before repeating any structural claim (path, script, route, store field): confirm it with `ls`/glob/grep in the current tree. Docs and memories describe the past; the tree is the present.5253## 7. Output artifact54An oriented session. If asked to summarize, produce a short "where I'll look and why" note with verified paths — not a re-dump of this map.5556## 8. Common traps57- **Do NOT trust blindly:** `docs/` (gitignored planning vault; all point-in-time plans now under `docs/plans/archive/`, several completed/superseded); `DESIGN.md`'s type-scale numbers, which are still DS1-era — the doc flags them inline and #1543 tracks the rewrite; ADR-007 and ADR-011 (historical by design — both correctly marked superseded, read them as history not guidance); and `narraitor-architecture`/`narraitor-pattern-alignment-skill`, which still carry shadcn-era mentions. Those describe the *origin* of the `src/components/ui/` primitives, never a license to add `cva`/`cn()`/Tailwind — where they conflict with `narraitor-architecture-contract`, the contract wins.58 - Cleared by the 2026-07-28 doc-rot sweep, don't re-flag: `ai-systems.md`'s `gemini-2.0-flash` (now points at `config.ts`), `style-port`'s dead `design-tokens.css` path (now `themes/`), and the `/dev/design-system*` references in `DESIGN.md` / `public_docs/design-system/README.md` (present but correctly marked retired).59- Bad behavior this prevents: a session reads `DESIGN.md`, navigates to `/dev/design-system`, finds nothing, and "helpfully" rebuilds a living style guide that was deliberately deleted.60- Port 3000 may be held by an orphan `next dev` or another project — `lsof -nP -iTCP:3000 -sTCP:LISTEN` before blaming code.61- `src/app/dev/*` harnesses are development sandboxes: patterns there are NOT production conventions.62- No Tailwind. Plain CSS + design tokens (`var(--token)`) + `clsx`. Any utility-class or `cn()` suggestion is a regression.6364## 9. Related skills65`narraitor-build-test-env` (run/verify commands) · `narraitor-architecture-contract` (invariants) · `narraitor-domain-reference` (applied domain knowledge) · `narraitor-failure-archaeology` (settled battles) · existing `narraitor-architecture` (authoring conventions).6667## 10. Provenance and maintenance6869Re-verify volatile claims with:70- `ls src/state src/lib/ai src/lib/api src/lib/theme/themes && find src/app/api -name route.ts | wc -l` (expect ~20 routes)71- `grep -n "gemini-" src/lib/ai/config.ts` (current model strings)72- `git log --oneline -5` (has the world moved since this map?)7374Last generated: 2026-07-04 (develop @ 4bec88e6)75Known uncertainty:76- Route count and `/dev/*` harness list drift as features land; counts here are a snapshot.77- `docs/` vault contents were sampled, not exhaustively read.
jerseycheese