chore: obsidian docs

feat(ui): add bug reporting integrations
docs: implementation plan for bug reporting
2026-05-17 23:35:13 -05:00 · 2026-05-17 23:34:17 -05:00 · 2026-05-17 23:02:46 -05:00 · 2026-05-17 22:57:34 -05:00 · 2026-05-13 17:59:13 -05:00 · 2026-05-12 20:52:35 -05:00
90 changed files with 6111 additions and 745 deletions
@@ -22,11 +22,49 @@ npm run dev       # local dev server
 npm run build     # type-check + production build
 ```

+## Make Your Own Game
+
+Halfstreet is currently meant to be forked as a complete Astro app, not consumed
+as a separate engine package. To make a new story, replace the markdown vault in
+`src/world/` and keep the TypeScript runtime in place.
+
+Start with:
+
+- `src/world/game.md` for the title, starting room, starting inventory, ending
+  priority, opening art, help text, and end text.
+- `src/world/parser.md` for command vocabulary and aliases.
+- `src/world/rooms/`, `src/world/items/`, `src/world/encounters/`, and
+  `src/world/endings/` for story content.
+- `src/world/mechanics/` and `src/world/actions/` for configurable rules and
+  interactions.
+- `src/world/ui.md` for page metadata, footer links, and UI feature switches.
+- `src/world/templates/` for starter files.
+
+Run `npm test` after changing world files. The loader validates wikilinks,
+required sections, frontmatter shape, and references between rooms, items,
+encounters, endings, mechanics, and actions.
+
+## Releases
+
+The footer build number comes from Woodpecker's pipeline number and increments on each CI build.
+The package version is an intentional release label.
+
+Use one of these from a clean worktree when you are ready to cut a release:
+
+```sh
+npm run release:patch  # fixes, typo corrections, small polish
+npm run release:minor  # meaningful playable additions or mechanics
+npm run release:major  # disruptive changes after 1.0.0
+git push --follow-tags
+```
+
+Each release script updates `package.json` and `package-lock.json`, creates a release commit, and tags it.
+
 ## Layout

 - `src/engine/` — parser, dispatcher, encounter logic
 - `src/ui/` — terminal renderer, theme, chips
- `src/world/` — markdown content (rooms, items, encounters, endings)
+- `src/world/` — Obsidian-friendly authoring vault
 - `src/pages/index.astro` — entry page

 ## Design docs
@@ -0,0 +1,653 @@
+# Bug Reporting Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a "Report a Bug" footer link that opens the Bugpin screenshot widget (forwards to GitHub Issues), plus auto error capture via Bugsink (Sentry-compatible) on every page.
+
+**Architecture:** Two independent flows. Bugpin = user-initiated, lazy-loaded `<script>` widget from `bugpin.half.st`, triggered by a footer `<button>`. Bugsink = background, `@sentry/browser` SDK initialised on page load against a DSN at `bugsink.half.st`. Both credentials are public project tokens and live in `src/world/ui.md`. Both flows are no-ops when not configured.
+
+**Tech Stack:** Astro 6, TypeScript, Zod 4, Vitest 4 (node env, no jsdom), `@sentry/browser` (new dep), Bugpin widget script.
+
+**Spec:** `docs/superpowers/specs/2026-05-17-bug-reporting-design.md`
+
+---
+
+## File map
+
+- `src/world/schema.ts` — **modify**: extend `uiFrontmatterSchema` with optional `bugReport` block.
+- `src/world/schema.test.ts` — **modify**: add accept/reject cases for `bugReport`.
+- `src/world/types.ts` — **modify**: extend `UiConfig` to expose `bugReport`.
+- `src/world/ui.md` — **modify**: add `bugReport` frontmatter.
+- `src/ui/error-tracking.ts` — **create**: reads body data attrs, calls `Sentry.init`. No-op when DSN missing.
+- `src/ui/bug-report.ts` — **create**: wires footer button click to lazy-load Bugpin widget, then call `BugPin.open()`. No-op when config missing.
+- `src/pages/index.astro` — **modify**: render the footer button conditionally, attach data attrs to `<body>`, import the two new modules.
+- `package.json` / `package-lock.json` — **modify**: add `@sentry/browser`.
+- `src/world/TODOs.md:45` — **modify**: rewrite to reflect actual approach.
+
+No DOM tests for the two new UI modules: the project's Vitest config runs in node with no jsdom. Coverage for those modules is `astro check` (type safety) + a manual smoke step at the end of the plan. Schema changes get full unit test coverage via the existing test file.
+
+---
+
+## Task 1: Extend `uiFrontmatterSchema` with `bugReport` (TDD)
+
+**Files:**
+- Modify: `src/world/schema.ts`
+- Modify: `src/world/schema.test.ts`
+
+- [ ] **Step 1: Add the failing tests**
+
+Append these inside the existing `describe('uiFrontmatterSchema', ...)` block in `src/world/schema.test.ts` (just before the closing `})` on line 120):
+
+```ts
+  it('accepts a bugReport block with bugpin and bugsink subconfigs', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: {
+        copyright: '© 2026 Ethan J Lewis',
+        links: [],
+      },
+      bugReport: {
+        enabled: true,
+        label: 'Report a Bug',
+        bugpin: {
+          serverUrl: 'https://bugpin.half.st',
+          apiKey: 'proj_07df4bf91f12445b8ef8c723e865ed7b',
+        },
+        bugsink: {
+          enabled: true,
+          dsn: 'https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1',
+        },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('accepts ui config with no bugReport block at all', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects a bugpin block with a non-url serverUrl', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+      bugReport: {
+        enabled: true,
+        bugpin: { serverUrl: 'not-a-url', apiKey: 'proj_x' },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
+  })
+
+  it('rejects a bugsink block with a non-url dsn', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+      bugReport: {
+        enabled: true,
+        bugsink: { dsn: 'whatever' },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
+  })
+```
+
+- [ ] **Step 2: Run tests, confirm they fail**
+
+```
+npm test -- src/world/schema.test.ts
+```
+
+Expected: the four new tests fail because `bugReport` is currently unknown (zod by default strips extras, so the "accepts" cases probably pass — but the "rejects" cases will fail because zod will accept anything for unknown fields). Either way, confirm the test runner reports at least the two "rejects" cases as failing.
+
+- [ ] **Step 3: Add the schema fields**
+
+In `src/world/schema.ts`, find `uiFrontmatterSchema` (starts at line 48). Add a `bugReport` field at the end of the object (after `features`, before the closing `})`). Final block:
+
+```ts
+export const uiFrontmatterSchema = z.object({
+  pageTitle: z.string().trim().min(1),
+  description: z.string().trim().min(1),
+  robots: z.string().trim().min(1).default('noindex'),
+  themeColor: z.string().trim().min(1).default('#1a0d00'),
+  footer: z.object({
+    copyright: z.string().trim().min(1),
+    copyrightHref: z.url().optional(),
+    buildLabel: z.string().trim().min(1).default('Build #'),
+    showBuild: z.boolean().default(true),
+    links: z.array(z.object({
+      label: z.string().trim().min(1),
+      href: z.url(),
+    })).default([]),
+  }),
+  features: z.object({
+    chips: z.boolean().default(true),
+    lightMeter: z.boolean().default(true),
+    typedEffect: z.boolean().default(true),
+    roomScroll: z.boolean().default(true),
+  }).default({
+    chips: true,
+    lightMeter: true,
+    typedEffect: true,
+    roomScroll: true,
+  }),
+  bugReport: z.object({
+    enabled: z.boolean().default(false),
+    label: z.string().trim().min(1).default('Report a Bug'),
+    bugpin: z.object({
+      serverUrl: z.url(),
+      apiKey: z.string().trim().min(1),
+    }).optional(),
+    bugsink: z.object({
+      enabled: z.boolean().default(true),
+      dsn: z.url(),
+    }).optional(),
+  }).optional(),
+})
+```
+
+- [ ] **Step 4: Run tests, confirm pass**
+
+```
+npm test -- src/world/schema.test.ts
+```
+
+Expected: all `uiFrontmatterSchema` tests pass (the original two + the four new ones).
+
+- [ ] **Step 5: Commit**
+
+```
+git add src/world/schema.ts src/world/schema.test.ts
+git commit -m "feat(world): add bugReport block to ui schema"
+```
+
+---
+
+## Task 2: Surface `bugReport` on the `UiConfig` type
+
+**Files:**
+- Modify: `src/world/types.ts:64-85`
+
+- [ ] **Step 1: Extend the interface**
+
+In `src/world/types.ts`, replace the existing `UiConfig` interface (currently lines 64–85) with:
+
+```ts
+export interface UiConfig {
+  pageTitle: string
+  description: string
+  robots: string
+  themeColor: string
+  footer: {
+    copyright: string
+    copyrightHref?: string
+    buildLabel: string
+    showBuild: boolean
+    links: Array<{
+      label: string
+      href: string
+    }>
+  }
+  features: {
+    chips: boolean
+    lightMeter: boolean
+    typedEffect: boolean
+    roomScroll: boolean
+  }
+  bugReport?: {
+    enabled: boolean
+    label: string
+    bugpin?: {
+      serverUrl: string
+      apiKey: string
+    }
+    bugsink?: {
+      enabled: boolean
+      dsn: string
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Verify type check passes**
+
+```
+npx astro check
+```
+
+Expected: 0 errors, 0 warnings (or at least no new errors introduced by this change).
+
+- [ ] **Step 3: Commit**
+
+```
+git add src/world/types.ts
+git commit -m "feat(world): expose bugReport on UiConfig"
+```
+
+---
+
+## Task 3: Add real config to `ui.md`
+
+**Files:**
+- Modify: `src/world/ui.md`
+
+- [ ] **Step 1: Edit frontmatter**
+
+Insert this block in `src/world/ui.md` between the `features:` block and the closing `---`, so the frontmatter ends like:
+
+```yaml
+features:
+  chips: true
+  lightMeter: true
+  typedEffect: true
+  roomScroll: true
+bugReport:
+  enabled: true
+  label: "Report a Bug"
+  bugpin:
+    serverUrl: "https://bugpin.half.st"
+    apiKey: "proj_07df4bf91f12445b8ef8c723e865ed7b"
+  bugsink:
+    enabled: true
+    dsn: "https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1"
+---
+```
+
+- [ ] **Step 2: Verify the world loads**
+
+```
+npm test -- src/world/buildWorld.test.ts
+npm test -- src/world/loader.test.ts
+```
+
+Expected: all tests pass — the new frontmatter is valid.
+
+- [ ] **Step 3: Commit**
+
+```
+git add src/world/ui.md
+git commit -m "feat(world): wire bugpin + bugsink credentials in ui.md"
+```
+
+---
+
+## Task 4: Install `@sentry/browser`
+
+**Files:**
+- Modify: `package.json`, `package-lock.json`
+
+- [ ] **Step 1: Install**
+
+```
+npm install @sentry/browser
+```
+
+Expected: a single new dependency added under `"dependencies"` in `package.json`; lockfile updates.
+
+- [ ] **Step 2: Verify**
+
+```
+node -e "require('@sentry/browser')"
+```
+
+Expected: no output and exit code 0.
+
+- [ ] **Step 3: Commit**
+
+```
+git add package.json package-lock.json
+git commit -m "chore: add @sentry/browser for bugsink integration"
+```
+
+---
+
+## Task 5: Create the Bugsink init module
+
+**Files:**
+- Create: `src/ui/error-tracking.ts`
+
+No unit test — Vitest runs in node with no jsdom, and this module only does work in a browser. Coverage is `astro check` (types) + the manual smoke at the end.
+
+- [ ] **Step 1: Write the module**
+
+```ts
+// src/ui/error-tracking.ts
+import * as Sentry from '@sentry/browser'
+
+const dsn = document.body?.dataset.bugsinkDsn ?? ''
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    tracesSampleRate: 0,
+    replaysSessionSampleRate: 0,
+    replaysOnErrorSampleRate: 0,
+    integrations: [],
+  })
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+```
+npx astro check
+```
+
+Expected: 0 new errors.
+
+- [ ] **Step 3: Commit**
+
+```
+git add src/ui/error-tracking.ts
+git commit -m "feat(ui): initialise sentry browser sdk against bugsink dsn"
+```
+
+---
+
+## Task 6: Create the Bugpin trigger module
+
+**Files:**
+- Create: `src/ui/bug-report.ts`
+
+Module reads config from the footer button's `data-*` attributes, lazy-loads the Bugpin widget on first click, then calls `BugPin.open()`. Subsequent clicks just call `open()` again.
+
+- [ ] **Step 1: Write the module**
+
+```ts
+// src/ui/bug-report.ts
+
+interface BugPinAPI {
+  open: () => void
+  close: () => void
+}
+
+declare global {
+  interface Window {
+    BugPin?: BugPinAPI
+  }
+}
+
+const button = document.querySelector<HTMLButtonElement>('[data-bug-report-trigger]')
+
+if (button) {
+  const serverUrl = button.dataset.bugpinServer
+  const apiKey = button.dataset.bugpinKey
+
+  if (serverUrl && apiKey) {
+    let loadPromise: Promise<void> | null = null
+
+    const ensureLoaded = (): Promise<void> => {
+      if (window.BugPin) return Promise.resolve()
+      if (loadPromise) return loadPromise
+
+      loadPromise = new Promise<void>((resolve, reject) => {
+        const script = document.createElement('script')
+        script.src = `${serverUrl.replace(/\/$/, '')}/widget.js`
+        script.async = true
+        script.dataset.apiKey = apiKey
+        script.addEventListener('load', () => resolve())
+        script.addEventListener('error', () => {
+          loadPromise = null
+          reject(new Error(`Failed to load Bugpin widget from ${script.src}`))
+        })
+        document.head.appendChild(script)
+      })
+
+      return loadPromise
+    }
+
+    button.addEventListener('click', async (event) => {
+      event.preventDefault()
+      button.disabled = true
+      try {
+        await ensureLoaded()
+        window.BugPin?.open()
+      } catch (err) {
+        console.error('[bug-report]', err)
+      } finally {
+        button.disabled = false
+      }
+    })
+  }
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+```
+npx astro check
+```
+
+Expected: 0 new errors.
+
+- [ ] **Step 3: Commit**
+
+```
+git add src/ui/bug-report.ts
+git commit -m "feat(ui): lazy-load bugpin widget on footer click"
+```
+
+---
+
+## Task 7: Wire footer button and module imports in `index.astro`
+
+**Files:**
+- Modify: `src/pages/index.astro`
+
+- [ ] **Step 1: Add config bindings to the frontmatter script**
+
+In the `---` block at the top of `src/pages/index.astro`, after `const remainingFooterLinks = footerLinks.slice(1)`, add:
+
+```ts
+const bugReport = ui?.bugReport
+const bugpinConfig = bugReport?.enabled ? bugReport.bugpin : undefined
+const bugsinkDsn =
+  bugReport?.enabled && bugReport.bugsink?.enabled ? bugReport.bugsink.dsn : ''
+```
+
+- [ ] **Step 2: Add the `data-bugsink-dsn` attribute to `<body>`**
+
+Replace the existing `<body>` opening tag with:
+
+```astro
+<body data-bugsink-dsn={bugsinkDsn}>
+```
+
+- [ ] **Step 3: Add the footer button**
+
+In the `<footer class="mystery-footer">` block (currently lines 89–109), append this AFTER the existing `{remainingFooterLinks.map(...)}` block, before the closing `</footer>`:
+
+```astro
+{bugpinConfig && (
+  <>
+    <span aria-hidden="true">|</span>
+    <button
+      type="button"
+      class="mystery-footer-bug-report"
+      data-bug-report-trigger
+      data-bugpin-server={bugpinConfig.serverUrl}
+      data-bugpin-key={bugpinConfig.apiKey}
+    >{bugReport?.label ?? 'Report a Bug'}</button>
+  </>
+)}
+```
+
+- [ ] **Step 4: Import the two new modules**
+
+Replace the existing module-import script block (currently lines 130–133):
+
+```astro
+<script>
+  import '../ui/terminal.ts'
+  import '../ui/theme.ts'
+</script>
+```
+
+with:
+
+```astro
+<script>
+  import '../ui/terminal.ts'
+  import '../ui/theme.ts'
+  import '../ui/error-tracking.ts'
+  import '../ui/bug-report.ts'
+</script>
+```
+
+- [ ] **Step 5: Add CSS so the button matches the surrounding links**
+
+Open `src/ui/crt.css` and grep for `.mystery-footer` to find the existing footer styles. Add a rule that makes the button look identical to the footer anchors. Append this block at the end of the existing `.mystery-footer` rules (search for `.mystery-footer a` and add directly after that selector's rule):
+
+```css
+.mystery-footer-bug-report {
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  color: inherit;
+  text-decoration: underline;
+  cursor: pointer;
+}
+.mystery-footer-bug-report:hover,
+.mystery-footer-bug-report:focus-visible {
+  text-decoration: none;
+}
+.mystery-footer-bug-report:disabled {
+  opacity: 0.5;
+  cursor: progress;
+}
+```
+
+If `.mystery-footer a` styles its anchors differently (e.g. specific color, no underline by default), match those properties instead. Look at the actual `a` rule and copy its `color`/`text-decoration` declarations into `.mystery-footer-bug-report` so the two render visually identically.
+
+- [ ] **Step 6: Run the full type check and build**
+
+```
+npx astro check
+npm run build
+```
+
+Expected: 0 errors, build succeeds.
+
+- [ ] **Step 7: Commit**
+
+```
+git add src/pages/index.astro src/ui/crt.css
+git commit -m "feat(ui): add Report a Bug footer button and wire bug tracking modules"
+```
+
+---
+
+## Task 8: Update TODOs
+
+**Files:**
+- Modify: `src/world/TODOs.md:45`
+
+- [ ] **Step 1: Rewrite the TODO line**
+
+Replace line 45 of `src/world/TODOs.md`:
+
+```
+- [ ] Set up BugPin as a self-hosted visual bug reporter for the site, then have incoming reports create markdown files under `src/world/bugs/` via a webhook or API bridge so bugs can be tracked in git alongside the game content. Include screenshot/annotation metadata in the markdown and decide whether these bug docs stay outside the world loader or get their own loader later.
+```
+
+with:
+
+```
+- [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st → forwards to GitHub Issues). Add Bugsink (@sentry/browser → bugsink.half.st) for automatic JS error capture. Mark complete after manual verification: a test report appears in the Bugpin portal AND a GitHub issue is created AND a thrown error appears in the Bugsink portal.
+```
+
+- [ ] **Step 2: Commit**
+
+```
+git add src/world/TODOs.md
+git commit -m "docs: rewrite TODO 45 to reflect Bugpin/Bugsink approach"
+```
+
+---
+
+## Task 9: Manual smoke test
+
+**Pre-req:** the Bugpin GitHub integration must be configured server-side before user reports will create issues. See spec §5. Steps below test the widget plumbing regardless.
+
+- [ ] **Step 1: Start dev server**
+
+```
+npm run dev
+```
+
+Open the URL it prints (default `http://localhost:4321`).
+
+- [ ] **Step 2: Verify the footer button renders**
+
+In the rendered footer at the bottom of the page, confirm "Report a Bug" appears after "Source Code", styled like the surrounding links.
+
+- [ ] **Step 3: Verify the widget lazy-loads**
+
+Open DevTools → Network. Filter for `widget.js`. Confirm NO request to `bugpin.half.st/widget.js` on cold page load.
+
+Click "Report a Bug". Confirm:
+- A single GET to `https://bugpin.half.st/widget.js` (status 200).
+- The Bugpin dialog opens.
+- Take a screenshot, write "smoke test" in the note, submit.
+- The dialog closes / shows a success state.
+
+Re-click "Report a Bug". Confirm NO second `widget.js` request — only the dialog re-opens.
+
+- [ ] **Step 4: Verify Bugpin received the report**
+
+Open `https://bugpin.half.st/portal`. Confirm the "smoke test" report appears with the screenshot attached.
+
+If the GitHub integration is configured: confirm a matching issue appears in the halfstreet GitHub repo.
+
+- [ ] **Step 5: Verify Bugsink captures an uncaught error**
+
+In the dev server's running page, open DevTools console and run:
+
+```js
+setTimeout(() => { throw new Error('bugsink smoke test') }, 0)
+```
+
+Open `https://bugsink.half.st`. Confirm a "bugsink smoke test" event appears within ~30 seconds.
+
+- [ ] **Step 6: Verify the launcher styling is acceptable**
+
+After step 3, the Bugpin widget's built-in floating launcher may now also be visible on the page. If its presence is visually objectionable, add a CSS rule to `src/ui/crt.css` targeting the Bugpin host element (inspect the DOM to find the selector — Bugpin uses Shadow DOM with a custom-element host like `<bugpin-widget>` or similar). Example:
+
+```css
+bugpin-widget,
+[data-bugpin-launcher] {
+  display: none !important;
+}
+```
+
+If this turns out to be needed, commit the CSS as `style(ui): hide bugpin built-in launcher (we have our own trigger)`. If the launcher's appearance is fine as-is, skip this step.
+
+- [ ] **Step 7: Mark TODO #45 complete**
+
+Once steps 1–5 all pass, edit `src/world/TODOs.md` line 45, change `- [ ]` to `- [x]`, and commit:
+
+```
+git add src/world/TODOs.md
+git commit -m "chore: mark TODO 45 complete"
+```
+
+---
+
+## Done criteria
+
+All of the following are true:
+
+- `npm test` passes.
+- `npx astro check` reports 0 errors.
+- `npm run build` succeeds.
+- Manual smoke (Task 9 steps 1–5) all pass.
+- TODO #45 is `[x]`.
@@ -0,0 +1,152 @@
+# Bug reporting: Bugpin (user) + Bugsink (auto)
+
+**Status:** Approved design, ready for implementation plan.
+**Date:** 2026-05-17
+
+## Goal
+
+Let visitors report bugs in the Halfstreet site with a screenshot, and capture uncaught JavaScript errors automatically. Reports should flow to systems already running on the `half.st` host so there is no new infrastructure to manage.
+
+## Two distinct flows
+
+| | Bugpin | Bugsink |
+|---|---|---|
+| Trigger | Visitor clicks "Report a Bug" in footer | Uncaught JS error |
+| Capture | Screenshot, annotations, free-text note, console/network metadata | Stack trace, breadcrumbs |
+| Destination | Bugpin portal → auto-creates a GitHub Issue in the halfstreet repo | Bugsink portal only |
+| Library | `bugpin.half.st/widget.js` (lazy-loaded on click) | `@sentry/browser` npm package (loads on every page) |
+
+The two are intentionally separate. Bugpin owns user-facing reports; Bugsink owns automatic exception capture. Sentry's user-feedback widget is **not** used — that would overlap Bugpin and muddle the responsibilities.
+
+## Components
+
+### 1. Footer link
+
+`src/pages/index.astro`
+
+Add "Report a Bug" to the footer chain after the existing links. Render as a `<button>` styled to match the surrounding `<a>` elements so it can dispatch JS without a hash-link navigation.
+
+Final order:
+`© 2026 Ethan J Lewis | GNU 3.0 | Build #<n> | Source Code | Report a Bug`
+
+The button only renders when `world.ui.bugReport?.enabled` is true and a Bugpin server URL is configured. If either is missing, the button is omitted (local dev stays clean).
+
+### 2. Config
+
+`src/world/ui.md` — add a `bugReport` frontmatter block:
+
+```yaml
+bugReport:
+  enabled: true
+  label: "Report a Bug"
+  bugpin:
+    serverUrl: "https://bugpin.half.st"
+    apiKey: "proj_07df4bf91f12445b8ef8c723e865ed7b"
+  bugsink:
+    enabled: true
+    dsn: "https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1"
+```
+
+The Bugpin project API key and the Bugsink DSN are both designed to ship to clients (they are public credentials that authenticate the project, not the operator), so checking them into the repo is acceptable.
+
+`src/world/schema.ts` — extend `uiFrontmatterSchema` with an optional `bugReport` object:
+
+```ts
+bugReport: z.object({
+  enabled: z.boolean().default(false),
+  label: z.string().trim().min(1).default('Report a Bug'),
+  bugpin: z.object({
+    serverUrl: z.url(),
+    apiKey: z.string().trim().min(1),
+  }).optional(),
+  bugsink: z.object({
+    enabled: z.boolean().default(true),
+    dsn: z.url(),
+  }).optional(),
+}).optional(),
+```
+
+`src/world/types.ts` — extend `UiConfig` with the matching TypeScript shape.
+
+### 3. Bugpin lazy loader
+
+New module: `src/ui/bug-report.ts`
+
+Responsibilities:
+- Read Bugpin config from a `data-*` attribute on the footer button (so the module stays free of Astro imports).
+- On first click, inject `<script src="${serverUrl}/widget.js" data-api-key="${apiKey}" async>` into `<head>`. Hide Bugpin's built-in floating button using whatever option the widget exposes (likely `data-hidden="true"` or a CSS rule scoped via the widget's Shadow DOM hook — confirm against the install guide during implementation).
+- Once the script resolves, call `window.BugPin.open()`.
+- Cache the loaded state on a module-level flag; subsequent clicks just call `open()` again.
+- If the script fails to load (offline, server down), log to the console and surface a minimal inline message ("Couldn't open bug reporter — try refreshing"). Do not break the page.
+
+Wire-up in `src/pages/index.astro`:
+- The footer button gets `data-bug-report-trigger`, `data-bugpin-server`, `data-bugpin-key` attributes.
+- A new `<script>` block imports `../ui/bug-report.ts` alongside the existing terminal/theme imports.
+
+The lazy-load is deliberate: ~150 KB of widget code stays off the cold load for visitors who never click.
+
+### 4. Bugsink init
+
+New module: `src/ui/error-tracking.ts`
+
+Responsibilities:
+- Add `@sentry/browser` as a dependency.
+- Read the DSN from a `data-bugsink-dsn` attribute set on `<body>` (or a meta tag) so the module is server-render-agnostic.
+- On import, call:
+  ```ts
+  Sentry.init({
+    dsn,
+    tracesSampleRate: 0,
+    replaysSessionSampleRate: 0,
+    replaysOnErrorSampleRate: 0,
+    integrations: [],
+  })
+  ```
+- If `dsn` is missing or `bugsink.enabled` is false, no-op.
+
+Error-capture only — no performance tracing, no session replay. Keeps the bundle small and avoids accidentally shipping a replay tool we didn't design for.
+
+Wire-up in `src/pages/index.astro`:
+- A new `<script>` block imports `../ui/error-tracking.ts` near the existing imports.
+
+### 5. Bugpin GitHub wiring
+
+Out of scope for the code change, but recorded here so it isn't lost during implementation:
+
+1. In the halfstreet GitHub repo, create a classic personal access token (or fine-grained equivalent) with `repo` scope.
+2. In Bugpin admin (https://bugpin.half.st/portal): Projects → halfstreet → Integrations → GitHub. Paste the token, select the halfstreet repo, set default labels (e.g., `bug`, `user-report`).
+3. Verify by submitting a test report from the footer link and confirming an issue appears in GitHub.
+
+## Out of scope
+
+- **Markdown files under `src/world/bugs/`.** Original TODO #45 proposed this; explicitly dropped — Bugpin's portal + GitHub Issues replace that storage path.
+- **Gitea mirroring.** Bugpin does not natively support Gitea. Deferred until there's clear value in a Bugpin → Gitea bridge. The front-end design does not preclude this; it would be a server-side addition on the Bugpin host.
+- **Sentry user-feedback widget.** Bugpin owns user reports; Bugsink stays auto-only.
+- **PII redaction policy.** Bugpin's widget includes a built-in blur tool; Bugsink only captures stack traces, not request bodies. No additional scrubbing layer.
+
+## Risks / things to verify during implementation
+
+- **Bugpin "hide default button" mechanism.** Docs mention a floating launcher; the exact opt-out attribute needs to be confirmed against the install guide or the widget source. If no opt-out exists, fall back to CSS that hides the widget's launcher selector inside its Shadow DOM root (or wrap with a custom-element rule).
+- **Bugsink Sentry SDK compatibility.** Bugsink claims Sentry-SDK compatibility but tested feature surface varies. Verify with `@sentry/browser` v9 (current stable as of 2026-05) — if a specific minor version is needed, pin it.
+- **Cold-start cost.** Bugsink adds ~30–40 KB gzipped to the page. Acceptable for an authored, low-traffic site; flag if budget gets tight.
+
+## TODOs.md update
+
+Replace line 45 with:
+
+```
+- [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st → forwards to GitHub Issues). Add Bugsink (@sentry/browser → bugsink.half.st) for automatic JS error capture.
+```
+
+Mark complete once the implementation lands and a test report has appeared in both Bugpin's portal and GitHub.
+
+## Files touched (preview)
+
+- `src/world/ui.md` — add `bugReport` block.
+- `src/world/schema.ts` — extend `uiFrontmatterSchema`.
+- `src/world/types.ts` — extend `UiConfig`.
+- `src/pages/index.astro` — render the button conditionally, wire data attributes, import the two new UI modules.
+- `src/ui/bug-report.ts` — **new**, lazy loads the Bugpin widget on click.
+- `src/ui/error-tracking.ts` — **new**, initializes Sentry SDK against Bugsink DSN.
+- `package.json` / `package-lock.json` — add `@sentry/browser`.
+- `src/world/TODOs.md` — rewrite line 45.
@@ -1,14 +1,15 @@
 {
  "name": "halfstreet",
-  "version": "0.0.1",
+  "version": "0.1.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "halfstreet",
-      "version": "0.0.1",
+      "version": "0.1.0",
      "license": "GPL-3.0-or-later",
      "dependencies": {
+        "@sentry/browser": "^10.53.1",
        "astro": "^6.1.9",
        "yaml": "^2.8.4",
        "zod": "^4.4.3"
@@ -1766,6 +1767,81 @@
        "win32"
      ]
    },
+    "node_modules/@sentry-internal/browser-utils": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/browser-utils/-/browser-utils-10.53.1.tgz",
+      "integrity": "sha512-X4d6y8sBMjmNhcDW4eMBU3ASsNIMz8dqaFkhyIMN/dkYr/yZKnbRZPaVuVUGvHKjnlficPpIH0/HK9KBjrYxPw==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/core": "10.53.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/feedback": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/feedback/-/feedback-10.53.1.tgz",
+      "integrity": "sha512-vVpTI/aEYN5d9IgZeYJWMqVaN0+iFgidSrYNAsZTh1US5sJUzF/wrl+68KdpmCtFROrN3jiAn1oPSwL5CKvEJA==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry/core": "10.53.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/replay": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/replay/-/replay-10.53.1.tgz",
+      "integrity": "sha512-wZNzTBYkgGUPWMuUQv7L64+OJmoCnz7GQNiTrTFK6EVAjJXFBCSsPp/nhif0bLhbk8+0g4xz633uOhpXuQbFdw==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/browser-utils": "10.53.1",
+        "@sentry/core": "10.53.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry-internal/replay-canvas": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry-internal/replay-canvas/-/replay-canvas-10.53.1.tgz",
+      "integrity": "sha512-aueLaf/2prExwA76BGU5/bOXCKWqtt6jQXWA6WJQNrmKpPEtZJB4ypnpsou0McXQCF8tur2Y8U0TEkwQP13yJQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/replay": "10.53.1",
+        "@sentry/core": "10.53.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry/browser": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry/browser/-/browser-10.53.1.tgz",
+      "integrity": "sha512-zXF373hzUOGzUOrqd8xb1U3LQi5uYC3mwv+z5OMKUUinQlu30tTWBs7ypy6YTchtix9QlYaHWlayUF8vBZ5UjA==",
+      "license": "MIT",
+      "dependencies": {
+        "@sentry-internal/browser-utils": "10.53.1",
+        "@sentry-internal/feedback": "10.53.1",
+        "@sentry-internal/replay": "10.53.1",
+        "@sentry-internal/replay-canvas": "10.53.1",
+        "@sentry/core": "10.53.1"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@sentry/core": {
+      "version": "10.53.1",
+      "resolved": "https://registry.npmjs.org/@sentry/core/-/core-10.53.1.tgz",
+      "integrity": "sha512-XG4ezlkyuAPjBC5+9kXC94rXXuqYTw9NRhfaDHssbTFaGnqBR8vQX2UUgZfY7ucbeelRDGfBu1sywoU+mB04uA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/@shikijs/core": {
      "version": "4.0.2",
      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.0.2.tgz",
@@ -1,7 +1,7 @@
 {
  "name": "halfstreet",
  "type": "module",
-  "version": "0.0.1",
+  "version": "0.1.0",
  "license": "GPL-3.0-or-later",
  "engines": {
    "node": ">=22.12.0"
@@ -11,10 +11,14 @@
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro",
+    "release:patch": "npm version patch -m \"chore(release): %s\"",
+    "release:minor": "npm version minor -m \"chore(release): %s\"",
+    "release:major": "npm version major -m \"chore(release): %s\"",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "dependencies": {
+    "@sentry/browser": "^10.53.1",
    "astro": "^6.1.9",
    "yaml": "^2.8.4",
    "zod": "^4.4.3"
@@ -326,6 +326,79 @@ describe('light status', () => {
      maxTurns: 6,
    })
  })
+
+  it('uses the configured light meter length and state keys', () => {
+    const lightWorld: World = {
+      ...world,
+      mechanics: {
+        light: {
+          enabled: true,
+          handler: 'light',
+          maxTurns: 3,
+          burnOn: ['wait'],
+          stateKeys: { lit: 'isLit', burn: 'fuel' },
+          ui: { meter: true, icon: 'candle' },
+        },
+      },
+      items: {
+        ...world.items,
+        torch: {
+          id: 'torch',
+          names: ['torch', 'lamp'],
+          short: 'an oil lamp',
+          long: 'An iron oil lamp, unlit.',
+          initialState: { isLit: false },
+          takeable: true,
+          lightable: true,
+        },
+      },
+    }
+    const state: GameState = {
+      ...initialStateFor(lightWorld),
+      inventory: [{ id: 'torch', state: { isLit: true, fuel: 2 } }],
+    }
+
+    expect(getLightStatus(state, lightWorld)).toEqual({
+      itemId: 'torch',
+      lit: true,
+      turnsLeft: 2,
+      maxTurns: 3,
+    })
+  })
+
+  it('hides the meter when the light mechanic is disabled', () => {
+    const lightWorld: World = {
+      ...world,
+      mechanics: {
+        light: {
+          enabled: false,
+          handler: 'light',
+          maxTurns: 6,
+          burnOn: ['move', 'wait'],
+          stateKeys: { lit: 'lit', burn: 'burn' },
+          ui: { meter: true, icon: 'candle' },
+        },
+      },
+      items: {
+        ...world.items,
+        torch: {
+          id: 'torch',
+          names: ['torch', 'lamp'],
+          short: 'an oil lamp',
+          long: 'An iron oil lamp, unlit.',
+          initialState: { lit: false },
+          takeable: true,
+          lightable: true,
+        },
+      },
+    }
+    const state: GameState = {
+      ...initialStateFor(lightWorld),
+      inventory: [{ id: 'torch', state: { lit: true, burn: 6 } }],
+    }
+
+    expect(getLightStatus(state, lightWorld)).toBeNull()
+  })
 })

 describe('ambiguous → disambiguation flow', () => {
@@ -501,22 +574,32 @@ describe('light/extinguish verbs (implicit lighter)', () => {
    expect(texts).toContain('The book is empty.')
  })

-  it('burns two segments on wait and extinguishes on the third wait', () => {
+  it('burns one segment on each wait and extinguishes when the last segment expires', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 6 } }] }

    const first = dispatch(state, { kind: 'verb-only', verb: 'wait' }, world)
-    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(4)
+    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(5)
    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(true)

    const second = dispatch(first.state, { kind: 'verb-only', verb: 'wait' }, world)
-    expect(second.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(2)
+    expect(second.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(4)

    const third = dispatch(second.state, { kind: 'verb-only', verb: 'wait' }, world)
-    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(0)
-    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(false)
-    expect(third.appended.map((l) => l.text)).toContain('The flame dies.')
+    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
+
+    const fourth = dispatch(third.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(fourth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(2)
+
+    const fifth = dispatch(fourth.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(fifth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(1)
+    expect(fifth.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(true)
+
+    const sixth = dispatch(fifth.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(sixth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(0)
+    expect(sixth.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(false)
+    expect(sixth.appended.map((l) => l.text)).toContain('The flame dies.')
  })

  it('burns one segment on movement', () => {
@@ -543,6 +626,100 @@ describe('light/extinguish verbs (implicit lighter)', () => {
    expect(result.state.location).toBe('r2')
  })

+  it('uses configured maxTurns when lighting and burning down', () => {
+    const baseWorld = w()
+    const world: World = {
+      ...baseWorld,
+      mechanics: {
+        light: {
+          enabled: true,
+          handler: 'light',
+          maxTurns: 3,
+          burnOn: ['wait'],
+          stateKeys: { lit: 'lit', burn: 'burn' },
+          ui: { meter: true, icon: 'candle' },
+          messages: { flameDies: 'The configured light dies.' },
+        },
+      },
+      items: {
+        ...baseWorld.items,
+        lamp: {
+          id: 'lamp',
+          names: ['lamp'],
+          short: 'an oil lamp',
+          long: '.',
+          initialState: { lit: false },
+          takeable: true,
+          lightable: true,
+          litText: 'The wick catches.',
+        },
+      },
+    }
+    let state = initialStateFor(world)
+    state = { ...state, inventory: [
+      { id: 'lamp', state: { lit: false } },
+      { id: 'matches', state: { uses: 2 } },
+    ] }
+
+    const lit = dispatch(state, { kind: 'verb-target', verb: 'light', target: { canonical: 'lamp', raw: 'lamp' } }, world)
+    expect(lit.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
+
+    const first = dispatch(lit.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(2)
+    const second = dispatch(first.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(second.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(1)
+    const third = dispatch(second.state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(false)
+    expect(third.appended.map((l) => l.text)).toContain('The configured light dies.')
+  })
+
+  it('does not burn down on movement when move is not configured', () => {
+    const world: World = {
+      ...w(),
+      mechanics: {
+        light: {
+          enabled: true,
+          handler: 'light',
+          maxTurns: 3,
+          burnOn: ['wait'],
+          stateKeys: { lit: 'lit', burn: 'burn' },
+          ui: { meter: true, icon: 'candle' },
+        },
+      },
+      rooms: {
+        r: { id: 'r', title: '[ R ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: { n: 'r2' }, items: [] },
+        r2: { id: 'r2', title: '[ R2 ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] },
+      },
+    }
+    let state = initialStateFor(world)
+    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 3 } }] }
+
+    const result = dispatch(state, { kind: 'go', direction: 'n' }, world)
+    expect(result.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
+  })
+
+  it('disabling the light mechanic removes burn-down behavior', () => {
+    const world: World = {
+      ...w(),
+      mechanics: {
+        light: {
+          enabled: false,
+          handler: 'light',
+          maxTurns: 6,
+          burnOn: ['move', 'wait'],
+          stateKeys: { lit: 'lit', burn: 'burn' },
+          ui: { meter: true, icon: 'candle' },
+        },
+      },
+    }
+    let state = initialStateFor(world)
+    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 1 } }] }
+
+    const result = dispatch(state, { kind: 'verb-only', verb: 'wait' }, world)
+    expect(result.state.inventory.find((i) => i.id === 'lamp')?.state).toEqual({ lit: true, burn: 1 })
+    expect(result.appended.map((l) => l.text)).not.toContain('The flame dies.')
+  })
+
  it('extinguishes a lit lamp', () => {
    const world = w()
    let state = initialStateFor(world)
@@ -623,6 +800,21 @@ describe('use verb routing', () => {
        letter: { id: 'letter', names: ['letter'], short: 'a letter', long: '.', initialState: {}, takeable: true, readable: true, readableText: 'Read me.' },
        'broken-cigarette': { id: 'broken-cigarette', names: ['cigarette', 'broken cigarette'], short: 'a broken cigarette', long: '.', initialState: { lit: false }, takeable: true, lightable: true, litText: 'The end glows once, then steadies. The smoke is bitter.' },
      },
+      actions: {
+        'burn-letter': {
+          id: 'burn-letter',
+          verbs: ['use'],
+          requires: { allVisibleOrHeld: ['letter', 'matches'] },
+          consumes: { inventory: ['letter'] },
+          decrements: { item: 'matches', stateKey: 'uses' },
+          setsFlags: { letterBurned: true },
+          messages: {
+            success: 'The letter catches at one corner. In a few breaths it is ash.',
+            spent: 'The matchbook is empty.',
+            missingRequired: "You don't see the letter here.",
+          },
+        },
+      },
      encounters: {},
      endings: { true: { whenFlags: { _never: true }, narration: '' }, wrong: { whenFlags: { _never: true }, narration: '' }, bad: { whenFlags: { _never: true }, narration: '' } },
    }
@@ -685,6 +877,77 @@ describe('use verb routing', () => {
  })
 })

+describe('handler-backed drink action', () => {
+  function w(): World {
+    return {
+      startingRoom: 'r',
+      startingInventory: ['whiskey'],
+      rooms: {
+        r: { id: 'r', title: '[ R ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] },
+        'drunk-start': { id: 'drunk-start', title: '[ Drunk Start ]', descriptions: { firstVisit: 'The hall tips.', revisit: 'The hall tips again.', examined: '.' }, exits: { n: 'drunk-next' }, items: [] },
+        'drunk-next': { id: 'drunk-next', title: '[ Drunk Next ]', descriptions: { firstVisit: 'The room doubles.', revisit: 'The room doubles again.', examined: '.' }, exits: { s: 'drunk-start' }, items: [] },
+        vestibule: { id: 'vestibule', title: '[ Vestibule ]', descriptions: { firstVisit: '.', revisit: 'You wake somewhere else.', examined: '.' }, exits: {}, items: [] },
+        pantry: { id: 'pantry', title: '[ Pantry ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: ['whiskey'] },
+      },
+      items: {
+        whiskey: { id: 'whiskey', names: ['whiskey'], short: 'a bottle of whiskey', long: '.', initialState: {}, takeable: true },
+      },
+      actions: {
+        'drink-whiskey': {
+          id: 'drink-whiskey',
+          verbs: ['drink'],
+          handler: 'drunk-transition',
+          requires: { allHeld: ['whiskey'] },
+          consumes: { inventory: ['whiskey'] },
+          drunkTransition: {
+            destinationRoom: 'drunk-start',
+            maxMoves: 2,
+            wakeRoom: 'vestibule',
+            resetRoom: 'pantry',
+          },
+          messages: {
+            success: 'Custom drink text.',
+            missingRequired: 'Hold it first.',
+            tooManyMovesPassOut: 'Custom pass out.',
+            reset: 'Custom reset.',
+          },
+        },
+      },
+      encounters: {},
+      endings: { true: { whenFlags: { _never: true }, narration: '' }, wrong: { whenFlags: { _never: true }, narration: '' }, bad: { whenFlags: { _never: true }, narration: '' } },
+    }
+  }
+
+  it('uses markdown action config for destination, move cap, wake room, and reset room', () => {
+    const world = w()
+    let state = initialStateFor(world)
+    let result = dispatch(state, { kind: 'verb-target', verb: 'drink', target: { canonical: 'whiskey', raw: 'whiskey' } }, world)
+
+    expect(result.state.location).toBe('drunk-start')
+    expect(result.state.inventory.find((i) => i.id === 'whiskey')).toBeUndefined()
+    expect(result.appended.map((l) => l.text)).toContain('Custom drink text.')
+
+    state = {
+      ...result.state,
+      roomState: {
+        ...result.state.roomState,
+        pantry: { takenItems: ['whiskey'], droppedItems: ['whiskey'] },
+      },
+    }
+    result = dispatch(state, { kind: 'go', direction: 'n' }, world)
+    expect(result.state.location).toBe('drunk-next')
+    expect(result.state.flags['drunkMoves']).toBe(1)
+
+    result = dispatch(result.state, { kind: 'go', direction: 's' }, world)
+    expect(result.state.location).toBe('vestibule')
+    expect(result.state.flags['drunk']).toBe(false)
+    expect(result.state.roomState['pantry']?.['takenItems']).toEqual([])
+    expect(result.state.roomState['pantry']?.['droppedItems']).toEqual([])
+    expect(result.appended.map((l) => l.text)).toContain('Custom pass out.')
+    expect(result.appended.map((l) => l.text)).toContain('Custom reset.')
+  })
+})
+
 describe('ending detection', () => {
  function makeWorld(): World {
    return {
@@ -1,9 +1,47 @@
-import type { World } from '../world/types'
-import type { GameState, ParsedCommand, DispatchResult, ItemInstance, TranscriptLine } from './types'
-import { SCHEMA_VERSION, TRANSCRIPT_CAP } from './types'
+import { DEFAULT_WORLD_MESSAGES, type DeclarativeAction, type LightMechanicMessageKey, type World, type WorldMessageKey } from '../world/types'
+import type { GameState, ParsedCommand, DispatchResult, ItemInstance, TranscriptLine, ResolveLevel } from './types'
+import { SCHEMA_VERSION, TRANSCRIPT_CAP, RESOLVE_LEVELS } from './types'
 import { applyVerbToEncounter, maybeTriggerEncounter } from './encounters'

-export const LIGHT_TURNS_MAX = 6
+type ActiveLightMechanic = NonNullable<NonNullable<World['mechanics']>['light']>
+type ActiveResolveMechanic = NonNullable<NonNullable<World['mechanics']>['resolve']>
+
+const DEFAULT_LIGHT_MECHANIC: ActiveLightMechanic = {
+  enabled: true,
+  handler: 'light',
+  maxTurns: 6,
+  burnOn: ['move', 'wait'],
+  stateKeys: { lit: 'lit', burn: 'burn' },
+  ui: { meter: true, icon: 'candle' },
+  messages: {},
+}
+const DEFAULT_RESOLVE_MECHANIC: ActiveResolveMechanic = {
+  enabled: true,
+  handler: 'resolve',
+  ladder: RESOLVE_LEVELS,
+  wrongVerbCost: 1,
+  safeRooms: { recoverySteps: 1 },
+  failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
+}
+const DEFAULT_DRUNK_ACTION: DeclarativeAction = {
+  id: 'drink-whiskey',
+  verbs: ['drink'],
+  handler: 'drunk-transition',
+  requires: { allHeld: ['whiskey'] },
+  consumes: { inventory: ['whiskey'] },
+  drunkTransition: {
+    destinationRoom: 'drunk-hall',
+    maxMoves: 20,
+    wakeRoom: 'foyer',
+    resetRoom: 'kitchen',
+  },
+  messages: {
+    success: 'You drink from the bottle. It tastes of smoke, sugar, and rainwater left too long in a pipe.',
+    secretFoundPassOut: 'The faceless man steps backward into the dark. The floor rises under you, or you fall toward it.',
+    tooManyMovesPassOut: 'The rooms keep turning until they become one room. Then even that room is gone.',
+    reset: 'The bottle is not with you. Somewhere in the kitchen, it is half full again.',
+  },
+}

 export interface LightStatus {
  itemId: string
@@ -12,13 +50,34 @@ export interface LightStatus {
  maxTurns: number
 }

-const HALFSTREET_ASCII = String.raw`
- _   _       _  __     ____  _                 _
-| | | | __ _| |/ _|   / ___|| |_ _ __ ___  ___| |_
-| |_| |/ _\` | | |_    \___ \| __| '__/ _ \/ _ \ __|
-|  _  | (_| | |  _|    ___) | |_| | |  __/  __/ |_
-|_| |_|\__,_|_|_|     |____/ \__|_|  \___|\___|\__|
-`.trim()
+function message(world: World, key: WorldMessageKey): string {
+  return world.messages?.[key] ?? DEFAULT_WORLD_MESSAGES[key]
+}
+
+function lightMechanic(world: World): ActiveLightMechanic {
+  return world.mechanics?.light ?? DEFAULT_LIGHT_MECHANIC
+}
+
+function resolveMechanic(world: World): ActiveResolveMechanic {
+  return world.mechanics?.resolve ?? DEFAULT_RESOLVE_MECHANIC
+}
+
+function drunkAction(world: World): DeclarativeAction {
+  return Object.values(world.actions ?? {}).find((action) => action.handler === 'drunk-transition') ?? DEFAULT_DRUNK_ACTION
+}
+
+function recoverResolve(level: ResolveLevel, world: World): ResolveLevel {
+  const mechanic = resolveMechanic(world)
+  if (!mechanic.enabled || mechanic.safeRooms.recoverySteps === 0) return level
+  const idx = mechanic.ladder.indexOf(level)
+  if (idx <= 0) return level
+  return mechanic.ladder[Math.max(0, idx - mechanic.safeRooms.recoverySteps)] ?? level
+}
+
+function lightMessage(world: World, key: LightMechanicMessageKey, fallback: WorldMessageKey): string {
+  const mechanic = lightMechanic(world)
+  return mechanic?.messages?.[key] ?? message(world, fallback)
+}

 export function initialStateFor(world: World): GameState {
  const startingRoom = world.rooms[world.startingRoom]
@@ -31,13 +90,14 @@ export function initialStateFor(world: World): GameState {
  })

  const opening: TranscriptLine[] = [
-    { kind: 'system', text: HALFSTREET_ASCII },
+    ...(world.game?.openingArt ? [{ kind: 'system' as const, text: world.game.openingArt }] : []),
    { kind: 'system', text: startingRoom.title },
    { kind: 'narration', text: startingRoom.descriptions.firstVisit },
  ]

  return {
    schemaVersion: SCHEMA_VERSION,
+    transcriptCap: world.game?.transcriptCap,
    location: world.startingRoom,
    inventory,
    roomState: { [world.startingRoom]: { visited: true } },
@@ -53,17 +113,20 @@ export function initialStateFor(world: World): GameState {
 }

 export function getLightStatus(state: GameState, world: World): LightStatus | null {
+  const mechanic = lightMechanic(world)
+  if (!mechanic?.enabled || mechanic.ui?.meter === false) return null
+
  let fallback: LightStatus | null = null
  for (const inst of state.inventory) {
    const def = world.items[inst.id]
    if (!def?.lightable) continue
-    const lit = inst.state['lit'] === true
-    const turnsLeft = lit ? getLightTurnsLeft(inst) : 0
+    const lit = inst.state[mechanic.stateKeys.lit] === true
+    const turnsLeft = lit ? getLightTurnsLeft(inst, world) : 0
    const status = {
      itemId: inst.id,
      lit,
      turnsLeft,
-      maxTurns: LIGHT_TURNS_MAX,
+      maxTurns: mechanic.maxTurns,
    }
    if (lit) return status
    fallback = fallback ?? status
@@ -73,7 +136,8 @@ export function getLightStatus(state: GameState, world: World): LightStatus | nu

 function append(state: GameState, lines: TranscriptLine[]): GameState {
  const transcript = [...state.transcript, ...lines]
-  return { ...state, transcript: transcript.slice(-TRANSCRIPT_CAP) }
+  const cap = state.transcriptCap ?? TRANSCRIPT_CAP
+  return { ...state, transcript: transcript.slice(-cap) }
 }

 export function getItemsInRoom(state: GameState, world: World, roomId: string): string[] {
@@ -93,12 +157,12 @@ function setRoomFlag(state: GameState, roomId: string, key: string, value: strin
  }
 }

-const ENDING_PRIORITY: ('true' | 'wrong' | 'bad')[] = ['true', 'wrong', 'bad']
-
 function evaluateEndings(state: GameState, world: World): GameState | null {
  if (state.endedWith) return null
-  for (const id of ENDING_PRIORITY) {
+  const priority = world.endingPriority ?? Object.keys(world.endings)
+  for (const id of priority) {
    const ending = world.endings[id]
+    if (!ending) continue
    const flags = ending.whenFlags
    let allMatch = true
    for (const [k, v] of Object.entries(flags)) {
@@ -115,6 +179,7 @@ function evaluateEndings(state: GameState, world: World): GameState | null {
 }

 function withEndingCheck(result: DispatchResult, world: World): DispatchResult {
+  result = maybeResolveDrunkState(result, world)
  const updated = evaluateEndings(result.state, world)
  if (!updated) return result
  const endingLine: TranscriptLine = updated.transcript[updated.transcript.length - 1]!
@@ -142,11 +207,11 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,
  if (command.kind === 'confirmation') {
    const pending = state.pendingConfirmation
    if (!pending) {
-      return narrate(state, [{ kind: 'narration', text: 'Nothing to confirm.' }])
+      return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-confirm') }])
    }
    const cleared: GameState = { ...state, pendingConfirmation: null }
    if (!command.confirmed) {
-      return narrate(cleared, [{ kind: 'narration', text: 'Cancelled.' }])
+      return narrate(cleared, [{ kind: 'narration', text: message(world, 'cancelled') }])
    }
    return dispatch(cleared, pending.command, world, true)
  }
@@ -157,7 +222,7 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,

  // Once the game has ended, only restart/undo (handled by the UI) can clear state.
  if (state.endedWith) {
-    return narrate(state, [{ kind: 'narration', text: 'The story has ended. Type `restart` or `undo`.' }])
+    return narrate(state, [{ kind: 'narration', text: world.game?.endedText ?? 'The story has ended. Type `restart` or `undo`.' }])
  }

  if (!confirmed && isCriticalCommand(command)) {
@@ -170,7 +235,7 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,
  if (command.kind === 'disambiguation') {
    const pending = state.pendingDisambiguation
    if (!pending) {
-      return narrate(state, [{ kind: 'narration', text: 'Nothing to choose between.' }])
+      return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-choose') }])
    }
    const cleared: GameState = { ...state, pendingDisambiguation: null }
    return dispatch(
@@ -183,9 +248,9 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,

  if (command.kind === 'unknown') {
    const text =
-      command.reason === 'unknown-verb' ? 'You consider the words, but they don\'t fit this place.'
-      : command.reason === 'unknown-noun' ? 'You don\'t see anything like that here.'
-      : 'You hesitate.'
+      command.reason === 'unknown-verb' ? message(world, 'unknown-verb')
+      : command.reason === 'unknown-noun' ? message(world, 'unknown-noun')
+      : message(world, 'malformed')
    return narrate(state, [{ kind: 'narration', text }])
  }

@@ -219,7 +284,7 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,
    if (command.verb === 'look') return withEndingCheck(handleLook(state, world), world)
    if (command.verb === 'inventory') return withEndingCheck(handleInventory(state, world), world)
    if (command.verb === 'wait') return withEndingCheck(handleWait(state, world), world)
-    if (command.verb === 'listen') return withEndingCheck(narrate(state, [{ kind: 'narration', text: 'You listen. The house listens back.' }]), world)
+    if (command.verb === 'listen') return withEndingCheck(narrate(state, [{ kind: 'narration', text: message(world, 'listen') }]), world)
  }

  if (command.kind === 'verb-target') {
@@ -233,14 +298,15 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,
    if (command.verb === 'drop') return withEndingCheck(handleDrop(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'examine' || command.verb === 'look') return withEndingCheck(handleExamine(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'read') return withEndingCheck(handleRead(stateWithNoun, command.target.canonical, world), world)
+    if (command.verb === 'drink') return withEndingCheck(handleDrink(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'light') return withEndingCheck(handleLight(stateWithNoun, command.target.canonical, null, world), world)
    if (command.verb === 'extinguish') return withEndingCheck(handleExtinguish(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'use') {
      const target = world.items[command.target.canonical]
      if (target?.lighter && !target.lightable) {
-        return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: 'Use match with what?' }]), world)
+        return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-lighter-with-what') }]), world)
      }
-      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: "You can't think how to use that here." }]), world)
+      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-unknown') }]), world)
    }
    return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: `You're not sure how to ${command.verb} that.` }]), world)
  }
@@ -256,16 +322,16 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World,
      return withEndingCheck(handleLight(stateWithNoun, command.target.canonical, command.indirect.canonical, world), world)
    }
    if (command.verb === 'use') {
-      const burnResult = handleBurnLetter(stateWithNoun, command.target.canonical, command.indirect.canonical, world)
-      if (burnResult) return withEndingCheck(burnResult, world)
+      const actionResult = handleDeclarativeAction(stateWithNoun, command, world)
+      if (actionResult) return withEndingCheck(actionResult, world)
      const lightResult = handleUseAsLight(stateWithNoun, command.target.canonical, command.indirect.canonical, world)
      if (lightResult) return withEndingCheck(lightResult, world)
-      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: "You can't think how to use that here." }]), world)
+      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-unknown') }]), world)
    }
    return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: `You're not sure how to ${command.verb} that.` }]), world)
  }

-  return narrate(state, [{ kind: 'narration', text: 'Nothing happens.' }])
+  return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
 }

 function narrate(state: GameState, lines: TranscriptLine[]): DispatchResult {
@@ -287,11 +353,11 @@ function handleMeta(state: GameState, verb: 'restart' | 'undo' | 'hint' | 'save'

 function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd', world: World): DispatchResult {
  const room = world.rooms[state.location]
-  if (!room) return narrate(state, [{ kind: 'narration', text: 'You are nowhere.' }])
+  if (!room) return narrate(state, [{ kind: 'narration', text: message(world, 'nowhere') }])

  const dest = room.exits[direction]
  if (!dest) {
-    return narrate(state, [{ kind: 'narration', text: 'You can\'t go that way.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'no-exit') }])
  }

  const lock = room.lockedExits?.[direction]
@@ -303,7 +369,7 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  }

  const destRoom = world.rooms[dest]
-  if (!destRoom) return narrate(state, [{ kind: 'narration', text: 'The way ahead is unfinished.' }])
+  if (!destRoom) return narrate(state, [{ kind: 'narration', text: message(world, 'unfinished-exit') }])

  const visited = !!state.roomState[dest]?.['visited']
  const description = visited ? destRoom.descriptions.revisit : destRoom.descriptions.firstVisit
@@ -312,12 +378,10 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  next = setRoomFlag(next, dest, 'visited', true)

  if (destRoom.safe) {
-    const ladder = ['steady', 'shaken', 'reeling', 'returning'] as const
-    const idx = ladder.indexOf(state.resolveLevel)
-    if (idx > 0) next = { ...next, resolveLevel: ladder[idx - 1]! }
+    next = { ...next, resolveLevel: recoverResolve(state.resolveLevel, world) }
  }

-  const lightTick = advanceLightState(next, 1, world)
+  const lightTick = advanceLightState(next, 'move', world)
  next = lightTick.state

  const arrivalLines: TranscriptLine[] = [
@@ -325,7 +389,13 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
    { kind: 'narration', text: description },
    ...lightTick.lines,
  ]
-  const result = narrate(next, arrivalLines)
+  let result = narrate(next, arrivalLines)
+
+  if (state.flags['drunk'] === true && dest.startsWith('drunk-')) {
+    const moved = advanceDrunkTurns(result.state, world)
+    if (moved.appended.length > 0) return { state: moved.state, appended: [...arrivalLines, ...moved.appended] }
+    result = { state: moved.state, appended: arrivalLines }
+  }

  // Trigger any encounter waiting in this room.
  const triggered = maybeTriggerEncounter(result.state, world)
@@ -335,17 +405,115 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  return result
 }

+function handleDrink(state: GameState, itemId: string, world: World): DispatchResult {
+  const action = drunkAction(world)
+  const targetItems = new Set([
+    ...(action.requires?.allHeld ?? []),
+    ...(action.requires?.allVisibleOrHeld ?? []),
+    ...(action.consumes?.inventory ?? []),
+  ])
+  if (!action.verbs.includes('drink') || !targetItems.has(itemId)) {
+    return narrate(state, [{ kind: 'narration', text: message(world, 'cannot-drink') }])
+  }
+  const requiredHeld = action.requires?.allHeld ?? [...targetItems]
+  const held = requiredHeld.every((requiredId) => state.inventory.some((i) => i.id === requiredId))
+  if (!held) {
+    return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'need-carrying') }])
+  }
+  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
+  const consumed = new Set(action.consumes?.inventory ?? [itemId])
+  const dest = world.rooms[config.destinationRoom]
+  const next: GameState = {
+    ...state,
+    location: config.destinationRoom,
+    inventory: state.inventory.filter((i) => !consumed.has(i.id)),
+    flags: { ...state.flags, drunk: true, drunkMoves: 0, drunkSecretFound: false },
+  }
+  const visited = !!next.roomState[config.destinationRoom]?.['visited']
+  const withVisit = setRoomFlag(next, config.destinationRoom, 'visited', true)
+  const lines: TranscriptLine[] = [
+    { kind: 'narration', text: action.messages.success },
+  ]
+  if (dest) {
+    lines.push(
+      { kind: 'system', text: dest.title },
+      { kind: 'narration', text: visited ? dest.descriptions.revisit : dest.descriptions.firstVisit },
+    )
+  }
+  return narrate(withVisit, lines)
+}
+
+function maybeResolveDrunkState(result: DispatchResult, world: World): DispatchResult {
+  if (result.state.flags['drunk'] !== true) return result
+  if (result.state.flags['drunkSecretFound'] === true) {
+    const action = drunkAction(world)
+    const passed = passOutFromDrunk(
+      result.state,
+      world,
+      action.messages.secretFoundPassOut ?? DEFAULT_DRUNK_ACTION.messages.secretFoundPassOut!,
+    )
+    return { state: passed.state, appended: [...result.appended, ...passed.appended] }
+  }
+  return result
+}
+
+function advanceDrunkTurns(state: GameState, world: World): DispatchResult {
+  const action = drunkAction(world)
+  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
+  const current = typeof state.flags['drunkMoves'] === 'number' ? state.flags['drunkMoves'] : 0
+  const moves = current + 1
+  const next = { ...state, flags: { ...state.flags, drunkMoves: moves } }
+  if (moves < config.maxMoves) return { state: next, appended: [] }
+  return passOutFromDrunk(
+    next,
+    world,
+    action.messages.tooManyMovesPassOut ?? DEFAULT_DRUNK_ACTION.messages.tooManyMovesPassOut!,
+  )
+}
+
+function passOutFromDrunk(state: GameState, world: World, preface: string): DispatchResult {
+  const action = drunkAction(world)
+  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
+  const resetItem = action.consumes?.inventory?.[0] ?? 'whiskey'
+  const wakeRoom = world.rooms[config.wakeRoom]
+  const resetRoomState = state.roomState[config.resetRoom] ?? {}
+  const resetTaken = ((resetRoomState['takenItems'] ?? []) as string[]).filter((id) => id !== resetItem)
+  const resetDropped = ((resetRoomState['droppedItems'] ?? []) as string[]).filter((id) => id !== resetItem)
+  const next: GameState = {
+    ...state,
+    location: config.wakeRoom,
+    inventory: state.inventory.filter((i) => i.id !== resetItem),
+    flags: { ...state.flags, drunk: false, drunkMoves: 0, drunkSecretFound: false },
+    roomState: {
+      ...state.roomState,
+      [config.resetRoom]: {
+        ...resetRoomState,
+        takenItems: resetTaken,
+        droppedItems: resetDropped,
+      },
+      [config.wakeRoom]: { ...(state.roomState[config.wakeRoom] ?? {}), visited: true },
+    },
+  }
+  const lines: TranscriptLine[] = [
+    { kind: 'narration', text: preface },
+    { kind: 'system', text: wakeRoom?.title ?? `[ ${config.wakeRoom} ]` },
+    { kind: 'narration', text: wakeRoom?.descriptions.revisit ?? `You wake in ${config.wakeRoom}.` },
+    { kind: 'narration', text: action.messages.reset ?? DEFAULT_DRUNK_ACTION.messages.reset! },
+  ]
+  return narrate(next, lines)
+}
+
 function handleWait(state: GameState, world: World): DispatchResult {
-  const lightTick = advanceLightState(state, 2, world)
+  const lightTick = advanceLightState(state, 'wait', world)
  return narrate(lightTick.state, [
-    { kind: 'narration', text: 'Time passes.' },
+    { kind: 'narration', text: message(world, 'time-passes') },
    ...lightTick.lines,
  ])
 }

 function handleLook(state: GameState, world: World): DispatchResult {
  const room = world.rooms[state.location]
-  if (!room) return narrate(state, [{ kind: 'narration', text: 'You see nothing.' }])
+  if (!room) return narrate(state, [{ kind: 'narration', text: message(world, 'see-nothing') }])
  const items = getItemsInRoom(state, world, state.location)
  const itemNarration = describeRoomItems(items.map((id) => world.items[id]?.short ?? id))
  return narrate(state, [
@@ -374,30 +542,31 @@ function joinList(values: string[]): string {

 function handleInventory(state: GameState, world: World): DispatchResult {
  if (state.inventory.length === 0) {
-    return narrate(state, [{ kind: 'narration', text: 'You are empty-handed.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'inventory-empty') }])
  }
  const lines = state.inventory.map((inst) => {
    const item = world.items[inst.id]
-    const litSuffix = inst.state['lit'] === true ? ' (lit)' : ''
+    const mechanic = lightMechanic(world)
+    const litSuffix = mechanic?.enabled && inst.state[mechanic.stateKeys.lit] === true ? ' (lit)' : ''
    return `  ${item?.short ?? inst.id}${litSuffix}`
  })
  return narrate(state, [
-    { kind: 'narration', text: 'You are carrying:' },
+    { kind: 'narration', text: message(world, 'inventory-heading') },
    { kind: 'narration', text: lines.join('\n') },
  ])
 }

 function handleTake(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: 'You don\'t see that here.' }])
-  if (!item.takeable) return narrate(state, [{ kind: 'narration', text: 'You can\'t take that.' }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-here') }])
+  if (!item.takeable) return narrate(state, [{ kind: 'narration', text: message(world, 'cannot-take') }])

  const itemsHere = getItemsInRoom(state, world, state.location)
  if (!itemsHere.includes(itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You don\'t see that here.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-here') }])
  }
  if (state.inventory.find((i) => i.id === itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You already have it.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'already-have') }])
  }

  const wasInRoomBase = (world.rooms[state.location]?.items ?? []).includes(itemId)
@@ -412,17 +581,18 @@ function handleTake(state: GameState, itemId: string, world: World): DispatchRes
    const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
    next = setRoomFlag(next, state.location, 'droppedItems', dropped.filter((id) => id !== itemId))
  }
-  return narrate(next, [{ kind: 'narration', text: 'Taken.' }])
+  return narrate(next, [{ kind: 'narration', text: message(world, 'taken') }])
 }

-function handleDrop(state: GameState, itemId: string, _world: World): DispatchResult {
+function handleDrop(state: GameState, itemId: string, world: World): DispatchResult {
  if (!state.inventory.find((i) => i.id === itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You don\'t have that.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-have') }])
  }
-  const itemDef = _world.items[itemId]
+  const itemDef = world.items[itemId]
  const itemInst = state.inventory.find((i) => i.id === itemId) ?? null
-  if (itemDef?.lightable && itemInst?.state['lit'] === true) {
-    return narrate(state, [{ kind: 'narration', text: "Extinguish it first." }])
+  const mechanic = lightMechanic(world)
+  if (mechanic?.enabled && itemDef?.lightable && itemInst?.state[mechanic.stateKeys.lit] === true) {
+    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'dropLit', 'drop-lit') }])
  }
  let next: GameState = {
    ...state,
@@ -430,17 +600,17 @@ function handleDrop(state: GameState, itemId: string, _world: World): DispatchRe
  }
  const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
  next = setRoomFlag(next, state.location, 'droppedItems', [...dropped, itemId])
-  return narrate(next, [{ kind: 'narration', text: 'Dropped.' }])
+  return narrate(next, [{ kind: 'narration', text: message(world, 'dropped') }])
 }

 function handleExamine(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: 'You don\'t see anything like that.' }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  const inventoryInst = state.inventory.find((i) => i.id === itemId) ?? null
  const visible =
    inventoryInst ||
    getItemsInRoom(state, world, state.location).includes(itemId)
-  if (!visible) return narrate(state, [{ kind: 'narration', text: 'You don\'t see anything like that.' }])
+  if (!visible) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  return narrate(state, [{ kind: 'narration', text: describeItem(itemId, item.long, inventoryInst) }])
 }

@@ -459,46 +629,49 @@ function spellSmallCount(value: number): string {

 function handleRead(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  const visible =
    state.inventory.find((i) => i.id === itemId) ||
    getItemsInRoom(state, world, state.location).includes(itemId)
-  if (!visible) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!visible) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  if (!item.readable || !item.readableText) {
-    return narrate(state, [{ kind: 'narration', text: "There's nothing to read on it." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-read') }])
  }
  return narrate(state, [{ kind: 'narration', text: item.readableText }])
 }

 function handleLight(state: GameState, targetId: string, instrumentId: string | null, world: World): DispatchResult {
+  const mechanic = lightMechanic(world)
+  if (!mechanic?.enabled) return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
+
  const target = world.items[targetId]
-  if (!target) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
-  if (target.lighter && !target.lightable) return narrate(state, [{ kind: 'narration', text: 'Use match with what?' }])
-  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: "You can't light that." }])
+  if (!target) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
+  if (target.lighter && !target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'useLighterWithWhat', 'use-lighter-with-what') }])
+  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'cannotLight', 'cannot-light') }])
  const targetInst = state.inventory.find((i) => i.id === targetId) ?? null
  const visibleInRoom = getItemsInRoom(state, world, state.location).includes(targetId)
  if (!targetInst && !visibleInRoom) {
-    return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  }
  // The 'lit' state lives on the inventory instance for inventory items, or
  // (eventually) on roomState for items left in a room. For now we only
  // support lighting items the player is carrying.
  if (!targetInst) {
-    return narrate(state, [{ kind: 'narration', text: "You'd have to be carrying it." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'need-carrying') }])
  }
-  if (targetInst.state['lit'] === true) {
-    return narrate(state, [{ kind: 'narration', text: "It's already lit." }])
+  if (targetInst.state[mechanic.stateKeys.lit] === true) {
+    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'alreadyLit', 'already-lit') }])
  }

  // Pick an instrument. If explicit, validate it; if implicit, find any.
  let lighterInst = null as typeof state.inventory[number] | null
  if (instrumentId) {
    lighterInst = state.inventory.find((i) => i.id === instrumentId) ?? null
-    if (!lighterInst) return narrate(state, [{ kind: 'narration', text: "You don't have that." }])
+    if (!lighterInst) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-have') }])
    const lighterDef = world.items[instrumentId]
-    if (!lighterDef?.lighter) return narrate(state, [{ kind: 'narration', text: "That isn't going to help." }])
+    if (!lighterDef?.lighter) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'notHelpful', 'not-helpful') }])
    if (typeof lighterInst.state['uses'] === 'number' && lighterInst.state['uses'] <= 0) {
-      return narrate(state, [{ kind: 'narration', text: "It is spent." }])
+      return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'spent', 'spent') }])
    }
  } else {
    for (const inst of state.inventory) {
@@ -509,7 +682,7 @@ function handleLight(state: GameState, targetId: string, instrumentId: string |
      break
    }
    if (!lighterInst) {
-      return narrate(state, [{ kind: 'narration', text: 'You have nothing to light it with.' }])
+      return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'noLighter', 'no-lighter') }])
    }
  }

@@ -518,64 +691,105 @@ function handleLight(state: GameState, targetId: string, instrumentId: string |
  const lighterUsesField = typeof lighterInst.state['uses'] === 'number' ? lighterInst.state['uses'] : null
  const newLighterUses = lighterUsesField === null ? null : lighterUsesField - 1
  const newInventory = state.inventory.map((i) => {
-    if (i.id === targetInst.id) return { ...i, state: { ...i.state, lit: true, burn: LIGHT_TURNS_MAX } }
+    if (i.id === targetInst.id) return { ...i, state: { ...i.state, [mechanic.stateKeys.lit]: true, [mechanic.stateKeys.burn]: mechanic.maxTurns } }
    if (i.id === lighterInst!.id && newLighterUses !== null) return { ...i, state: { ...i.state, uses: newLighterUses } }
    return i
  })
-  const lines: TranscriptLine[] = [{ kind: 'narration', text: target.litText ?? 'It catches.' }]
+  const lines: TranscriptLine[] = [{ kind: 'narration', text: target.litText ?? lightMessage(world, 'flameCatches', 'flame-catches') }]
  if (newLighterUses === 0) {
-    lines.push({ kind: 'narration', text: lighterDef.lighterEmptyText ?? 'It is spent.' })
+    lines.push({ kind: 'narration', text: lighterDef.lighterEmptyText ?? lightMessage(world, 'spent', 'spent') })
  }
  return narrate({ ...state, inventory: newInventory }, lines)
 }

-function handleBurnLetter(state: GameState, firstId: string, secondId: string, world: World): DispatchResult | null {
-  const ids = [firstId, secondId]
-  if (!ids.includes('letter') || !ids.includes('matches')) return null
+function handleDeclarativeAction(
+  state: GameState,
+  command: Extract<ParsedCommand, { kind: 'verb-target-prep' }>,
+  world: World,
+): DispatchResult | null {
+  const action = findDeclarativeAction(command, world)
+  if (!action) return null

-  const matches = state.inventory.find((i) => i.id === 'matches')
-  if (!matches) return narrate(state, [{ kind: 'narration', text: "You don't have a match." }])
-  if (typeof matches.state['uses'] === 'number' && matches.state['uses'] <= 0) {
-    return narrate(state, [{ kind: 'narration', text: 'The matchbook is empty.' }])
+  for (const itemId of action.requires?.allVisibleOrHeld ?? []) {
+    if (!isVisibleOrHeld(state, world, itemId)) {
+      return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-see-anything') }])
+    }
+  }
+  for (const itemId of action.requires?.allHeld ?? []) {
+    if (!state.inventory.some((i) => i.id === itemId)) {
+      return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-have') }])
+    }
  }

-  const letterHeld = state.inventory.some((i) => i.id === 'letter')
-  const letterInRoom = getItemsInRoom(state, world, state.location).includes('letter')
-  if (!letterHeld && !letterInRoom) {
-    return narrate(state, [{ kind: 'narration', text: "You don't see the letter here." }])
+  const decrement = action.decrements
+  const decremented = decrement ? state.inventory.find((i) => i.id === decrement.item) : null
+  if (decrement && !decremented) {
+    return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-have') }])
+  }
+  const decrementStateValue = decrement ? decremented?.state[decrement.stateKey] : null
+  const decrementedValue: number | null = typeof decrementStateValue === 'number' ? decrementStateValue : null
+  if (decrementedValue !== null && decrementedValue <= 0) {
+    return narrate(state, [{ kind: 'narration', text: action.messages.spent ?? message(world, 'spent') }])
  }

-  const newMatchesUses = typeof matches.state['uses'] === 'number' ? matches.state['uses'] - 1 : null
+  const consumed = new Set(action.consumes?.inventory ?? [])
  let next: GameState = {
    ...state,
    inventory: state.inventory
-      .filter((i) => i.id !== 'letter')
-      .map((i) => i.id === 'matches' && newMatchesUses !== null ? { ...i, state: { ...i.state, uses: newMatchesUses } } : i),
-    flags: { ...state.flags, letterBurned: true },
+      .filter((i) => !consumed.has(i.id))
+      .map((i) =>
+        decrement && i.id === decrement.item && decrementedValue !== null
+          ? { ...i, state: { ...i.state, [decrement.stateKey]: decrementedValue - 1 } }
+          : i,
+      ),
+    flags: { ...state.flags, ...(action.setsFlags ?? {}) },
  }

-  if (letterInRoom) {
-    const baseItems = world.rooms[state.location]?.items ?? []
-    const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
-    if (baseItems.includes('letter')) {
-      const taken = (next.roomState[state.location]?.['takenItems'] ?? []) as string[]
-      next = setRoomFlag(next, state.location, 'takenItems', [...new Set([...taken, 'letter'])])
-    }
-    if (dropped.includes('letter')) {
-      next = setRoomFlag(next, state.location, 'droppedItems', dropped.filter((id) => id !== 'letter'))
-    }
+  for (const itemId of consumed) {
+    next = removeVisibleRoomItem(next, world, itemId)
  }

-  const lines: TranscriptLine[] = [
-    { kind: 'narration', text: 'The letter catches at one corner. In a few breaths it is ash.' },
-  ]
-  if (newMatchesUses === 0) {
-    lines.push({ kind: 'narration', text: world.items['matches']?.lighterEmptyText ?? 'The matchbook is empty.' })
+  const lines: TranscriptLine[] = [{ kind: 'narration', text: action.messages.success }]
+  if (decrementedValue === 1 && action.messages.spent) {
+    lines.push({ kind: 'narration', text: action.messages.spent })
  }
  return narrate(next, lines)
 }

+function findDeclarativeAction(
+  command: Extract<ParsedCommand, { kind: 'verb-target-prep' }>,
+  world: World,
+): DeclarativeAction | null {
+  const commandItems = new Set([command.target.canonical, command.indirect.canonical])
+  for (const action of Object.values(world.actions ?? {})) {
+    if (!action.verbs.includes(command.verb)) continue
+    const required = [...(action.requires?.allVisibleOrHeld ?? []), ...(action.requires?.allHeld ?? [])]
+    if (required.length > 0 && required.every((itemId) => commandItems.has(itemId))) return action
+  }
+  return null
+}
+
+function isVisibleOrHeld(state: GameState, world: World, itemId: string): boolean {
+  return state.inventory.some((i) => i.id === itemId) || getItemsInRoom(state, world, state.location).includes(itemId)
+}
+
+function removeVisibleRoomItem(state: GameState, world: World, itemId: string): GameState {
+  if (!getItemsInRoom(state, world, state.location).includes(itemId)) return state
+  const baseItems = world.rooms[state.location]?.items ?? []
+  let next = state
+  if (baseItems.includes(itemId)) {
+    const taken = (next.roomState[state.location]?.['takenItems'] ?? []) as string[]
+    next = setRoomFlag(next, state.location, 'takenItems', [...new Set([...taken, itemId])])
+  }
+  const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
+  if (dropped.includes(itemId)) {
+    next = setRoomFlag(next, state.location, 'droppedItems', dropped.filter((id) => id !== itemId))
+  }
+  return next
+}
+
 function handleUseAsLight(state: GameState, firstId: string, secondId: string, world: World): DispatchResult | null {
+  if (!lightMechanic(world)?.enabled) return null
  const first = world.items[firstId]
  const second = world.items[secondId]
  if (first?.lighter && second?.lightable) return handleLight(state, secondId, firstId, world)
@@ -584,45 +798,50 @@ function handleUseAsLight(state: GameState, firstId: string, secondId: string, w
 }

 function handleExtinguish(state: GameState, targetId: string, world: World): DispatchResult {
+  const mechanic = lightMechanic(world)
+  if (!mechanic?.enabled) return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
+
  const target = world.items[targetId]
-  if (!target) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
-  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: "You can't extinguish that." }])
+  if (!target) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
+  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'cannotExtinguish', 'cannot-extinguish') }])
  const targetInst = state.inventory.find((i) => i.id === targetId)
-  if (!targetInst) return narrate(state, [{ kind: 'narration', text: "You'd have to be carrying it." }])
-  if (targetInst.state['lit'] !== true) {
-    return narrate(state, [{ kind: 'narration', text: "It isn't lit." }])
+  if (!targetInst) return narrate(state, [{ kind: 'narration', text: message(world, 'need-carrying') }])
+  if (targetInst.state[mechanic.stateKeys.lit] !== true) {
+    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'notLit', 'not-lit') }])
  }
  const newInventory = state.inventory.map((i) =>
-    i.id === targetId ? { ...i, state: { ...i.state, lit: false, burn: 0 } } : i,
+    i.id === targetId ? { ...i, state: { ...i.state, [mechanic.stateKeys.lit]: false, [mechanic.stateKeys.burn]: 0 } } : i,
  )
-  return narrate({ ...state, inventory: newInventory }, [{ kind: 'narration', text: target.extinguishedText ?? 'The flame dies.' }])
+  return narrate({ ...state, inventory: newInventory }, [{ kind: 'narration', text: target.extinguishedText ?? lightMessage(world, 'flameDies', 'flame-dies') }])
 }

-function advanceLightState(state: GameState, cost: number, world: World): { state: GameState; lines: TranscriptLine[] } {
-  if (cost <= 0) return { state, lines: [] }
+function advanceLightState(state: GameState, trigger: 'move' | 'wait', world: World): { state: GameState; lines: TranscriptLine[] } {
+  const mechanic = lightMechanic(world)
+  if (!mechanic?.enabled || !mechanic.burnOn.includes(trigger)) return { state, lines: [] }

  let changed = false
  const lines: TranscriptLine[] = []
  const inventory = state.inventory.map((inst) => {
    const def = world.items[inst.id]
-    if (!def?.lightable || inst.state['lit'] !== true) return inst
+    if (!def?.lightable || inst.state[mechanic.stateKeys.lit] !== true) return inst

-    const turnsLeft = getLightTurnsLeft(inst)
-    const nextTurns = Math.max(0, turnsLeft - cost)
+    const turnsLeft = getLightTurnsLeft(inst, world)
+    const nextTurns = Math.max(0, turnsLeft - 1)
    changed = true

    if (nextTurns === 0) {
-      lines.push({ kind: 'narration', text: def.extinguishedText ?? 'The flame dies.' })
-      return { ...inst, state: { ...inst.state, lit: false, burn: 0 } }
+      lines.push({ kind: 'narration', text: def.extinguishedText ?? lightMessage(world, 'flameDies', 'flame-dies') })
+      return { ...inst, state: { ...inst.state, [mechanic.stateKeys.lit]: false, [mechanic.stateKeys.burn]: 0 } }
    }
-    return { ...inst, state: { ...inst.state, burn: nextTurns } }
+    return { ...inst, state: { ...inst.state, [mechanic.stateKeys.burn]: nextTurns } }
  })

  return changed ? { state: { ...state, inventory }, lines } : { state, lines }
 }

-function getLightTurnsLeft(inst: ItemInstance): number {
-  const turns = inst.state['burn']
+function getLightTurnsLeft(inst: ItemInstance, world: World): number {
+  const mechanic = lightMechanic(world)
+  const turns = inst.state[mechanic.stateKeys.burn]
  if (typeof turns === 'number') return Math.max(0, turns)
-  return inst.state['lit'] === true ? LIGHT_TURNS_MAX : 0
+  return inst.state[mechanic.stateKeys.lit] === true ? mechanic.maxTurns : 0
 }
@@ -92,6 +92,23 @@ const world: World = {
  },
 }

+function withResolveMechanic(overrides: Partial<NonNullable<NonNullable<World['mechanics']>['resolve']>>): World {
+  return {
+    ...world,
+    mechanics: {
+      resolve: {
+        enabled: true,
+        handler: 'resolve',
+        ladder: ['steady', 'shaken', 'reeling', 'returning'],
+        wrongVerbCost: 1,
+        safeRooms: { recoverySteps: 1 },
+        failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
+        ...overrides,
+      },
+    },
+  }
+}
+
 describe('encounters — phase advancement', () => {
  it('triggers an encounter on entering its room', () => {
    let s = initialStateFor(world)
@@ -157,6 +174,34 @@ describe('encounters — phase advancement', () => {
    expect(s.resolveLevel).toBe('steady')
  })

+  it('uses markdown resolve config for wrong-verb cost', () => {
+    const configured = withResolveMechanic({ wrongVerbCost: 2 })
+    let s = initialStateFor(configured)
+    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
+    const r = dispatch(s, { kind: 'verb-target', verb: 'push', target: { canonical: 'revenant', raw: 'revenant' } }, configured)
+    expect(r.state.resolveLevel).toBe('reeling')
+  })
+
+  it('uses markdown resolve config for safe-room recovery', () => {
+    const configured = withResolveMechanic({ safeRooms: { recoverySteps: 2 } })
+    let s = initialStateFor(configured)
+    s = { ...s, resolveLevel: 'reeling' }
+    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
+    s = dispatch(s, { kind: 'go', direction: 's' }, configured).state
+    expect(s.resolveLevel).toBe('steady')
+  })
+
+  it('uses markdown resolve config for post-retreat level', () => {
+    const configured = withResolveMechanic({ failure: { retreatAt: 'returning', afterRetreat: 'reeling' } })
+    let s = initialStateFor(configured)
+    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
+    s = { ...s, resolveLevel: 'returning' }
+    s = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, configured).state
+    const r = dispatch(s, { kind: 'confirmation', confirmed: true }, configured)
+    expect(r.state.location).toBe('foyer')
+    expect(r.state.resolveLevel).toBe('reeling')
+  })
+
  it('allows a required item to be the direct target in a target-preposition encounter command', () => {
    let s = initialStateFor(world)
    s = {
@@ -2,6 +2,17 @@ import type { World } from '../world/types'
 import type { GameState, ParsedCommand, DispatchResult, TranscriptLine, ResolveLevel } from './types'
 import { TRANSCRIPT_CAP, RESOLVE_LEVELS } from './types'

+type ActiveResolveMechanic = NonNullable<NonNullable<World['mechanics']>['resolve']>
+
+const DEFAULT_RESOLVE_MECHANIC: ActiveResolveMechanic = {
+  enabled: true,
+  handler: 'resolve',
+  ladder: RESOLVE_LEVELS,
+  wrongVerbCost: 1,
+  safeRooms: { recoverySteps: 1 },
+  failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
+}
+
 function append(state: GameState, lines: TranscriptLine[]): GameState {
  const transcript = [...state.transcript, ...lines]
  return { ...state, transcript: transcript.slice(-TRANSCRIPT_CAP) }
@@ -38,11 +49,26 @@ export function maybeTriggerEncounter(state: GameState, world: World): DispatchR
  return narrate(next, [{ kind: 'narration', text: phase.description }])
 }

-function bumpResolve(level: ResolveLevel, cost: 0 | 1 | 2 | undefined): ResolveLevel {
-  if (!cost) return level
-  const idx = RESOLVE_LEVELS.indexOf(level)
-  const newIdx = Math.min(RESOLVE_LEVELS.length - 1, idx + cost)
-  return RESOLVE_LEVELS[newIdx]!
+function resolveMechanic(world: World): ActiveResolveMechanic {
+  return world.mechanics?.resolve ?? DEFAULT_RESOLVE_MECHANIC
+}
+
+function bumpResolve(level: ResolveLevel, cost: 0 | 1 | 2 | undefined, world: World): ResolveLevel {
+  const mechanic = resolveMechanic(world)
+  if (!mechanic.enabled || !cost) return level
+  const idx = mechanic.ladder.indexOf(level)
+  if (idx < 0) return level
+  const newIdx = Math.min(mechanic.ladder.length - 1, idx + cost)
+  return mechanic.ladder[newIdx]!
+}
+
+function shouldRetreat(level: ResolveLevel, cost: 0 | 1 | 2 | undefined, world: World): boolean {
+  const mechanic = resolveMechanic(world)
+  return mechanic.enabled && !!cost && level === mechanic.failure.retreatAt
+}
+
+function afterRetreatResolve(world: World): ResolveLevel {
+  return resolveMechanic(world).failure.afterRetreat
 }

 export interface EncounterResolution {
@@ -103,12 +129,13 @@ export function applyVerbToEncounter(
  if (!transition) {
    // Wrong verb — apply default narration and resolve cost.
    if (!verb || (targetId !== null && targetId !== encId)) return null  // verb is unrelated to this encounter
-    const newResolve = bumpResolve(state.resolveLevel, 1)
-    if (state.resolveLevel === 'returning') {
+    const wrongVerbCost = resolveMechanic(world).wrongVerbCost
+    const newResolve = bumpResolve(state.resolveLevel, wrongVerbCost, world)
+    if (shouldRetreat(state.resolveLevel, wrongVerbCost, world)) {
      // Retreat.
      const retreat = def.onFailed
      if (retreat) {
-        const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: 'shaken' }
+        const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: afterRetreatResolve(world) }
        const dest = world.rooms[retreat.retreatTo]
        const lines: TranscriptLine[] = [
          { kind: 'narration', text: retreat.narration },
@@ -125,10 +152,10 @@ export function applyVerbToEncounter(
  }

  // Right verb — but if it has a resolve cost and player is already at 'returning', retreat.
-  if (transition.resolveCost && transition.resolveCost > 0 && state.resolveLevel === 'returning') {
+  if (shouldRetreat(state.resolveLevel, transition.resolveCost, world)) {
    const retreat = def.onFailed
    if (retreat) {
-      const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: 'shaken' }
+      const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: afterRetreatResolve(world) }
      const dest = world.rooms[retreat.retreatTo]
      const lines: TranscriptLine[] = [
        { kind: 'narration', text: transition.narration },
@@ -142,13 +169,14 @@ export function applyVerbToEncounter(
  // Right verb — narrate and transition.
  let next: GameState = { ...state }
  if (transition.resolveCost) {
-    next = { ...next, resolveLevel: bumpResolve(next.resolveLevel, transition.resolveCost) }
+    next = { ...next, resolveLevel: bumpResolve(next.resolveLevel, transition.resolveCost, world) }
  }

  if (transition.to === 'resolved') {
    const newEncState = { ...next.encounterState }
    delete newEncState[encId]
    let resolvedFlags = { ...next.flags, [`${encId}.resolved`]: true }
+    if (transition.setFlags) resolvedFlags = { ...resolvedFlags, ...transition.setFlags }
    if (def.onResolved?.setFlags) resolvedFlags = { ...resolvedFlags, ...def.onResolved.setFlags }
    next = { ...next, encounterState: newEncState, flags: resolvedFlags }
  } else if (transition.to === 'failed') {
@@ -157,7 +185,7 @@ export function applyVerbToEncounter(
      const dest = world.rooms[retreat.retreatTo]
      const newEncState = { ...next.encounterState }
      delete newEncState[encId]
-      next = { ...next, location: retreat.retreatTo, encounterState: newEncState, resolveLevel: 'shaken' }
+      next = { ...next, location: retreat.retreatTo, encounterState: newEncState, resolveLevel: afterRetreatResolve(world) }
      const lines: TranscriptLine[] = [
        { kind: 'narration', text: transition.narration },
        { kind: 'narration', text: retreat.narration },
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { parse } from './parser'
-import type { ParserContext } from './parser'
+import type { ParserContext, ParserVocabulary } from './parser'

 const emptyCtx: ParserContext = {
  knownItems: [],
@@ -92,6 +92,45 @@ describe('parser — unknown input', () => {
 })

 describe('parser — verb + target', () => {
+  it('uses vocabulary supplied by world markdown', () => {
+    const vocabulary: ParserVocabulary = {
+      directions: {
+        n: ['n', 'northward'],
+        s: ['s'],
+        e: ['e'],
+        w: ['w'],
+        u: ['u'],
+        d: ['d'],
+      },
+      prepositions: ['beside'],
+      stopWords: ['the'],
+      noTargetVerbs: ['look'],
+      metaVerbs: ['restart'],
+      verbs: {
+        go: ['go'],
+        look: ['look', 'observe'],
+        take: ['take hold of'],
+      },
+    }
+    const ctx: ParserContext = {
+      knownItems: ['lamp'],
+      knownEncounters: [],
+      visibleNouns: [{ id: 'lamp', aliases: ['lamp'] }],
+      inventoryItemIds: [],
+      lastNoun: null,
+      awaitingDisambiguation: null,
+      vocabulary,
+    }
+    expect(parse('observe', ctx)).toEqual({ kind: 'verb-only', verb: 'look' })
+    expect(parse('northward', ctx)).toEqual({ kind: 'go', direction: 'n' })
+    expect(parse('go northward', ctx)).toEqual({ kind: 'go', direction: 'n' })
+    expect(parse('take hold of the lamp', ctx)).toEqual({
+      kind: 'verb-target',
+      verb: 'take',
+      target: { canonical: 'lamp', raw: 'lamp' },
+    })
+  })
+
  it('recognizes slice-two encounter verbs', () => {
    const ctx: ParserContext = {
      knownItems: [],
@@ -1,5 +1,14 @@
 import type { ParsedCommand, NounRef, Verb, MetaVerb, Direction, PendingDisambiguation } from './types'

+export interface ParserVocabulary {
+  directions: Record<Direction, string[]>
+  prepositions: string[]
+  stopWords: string[]
+  noTargetVerbs: Verb[]
+  metaVerbs: MetaVerb[]
+  verbs: Partial<Record<Verb, string[]>>
+}
+
 export interface ParserContext {
  /** All item ids that exist in the world (for noun matching). */
  knownItems: string[]
@@ -11,63 +20,115 @@ export interface ParserContext {
  inventoryItemIds: string[]
  lastNoun: NounRef | null
  awaitingDisambiguation: PendingDisambiguation | null
+  vocabulary?: ParserVocabulary
 }

-/** Verb synonym table: each entry maps an alias to the canonical Verb. */
-const VERB_SYNONYMS: Record<string, Verb> = {
-  // movement
-  go: 'go', walk: 'go', move: 'go',
-  // perception
-  look: 'look', l: 'look',
-  examine: 'examine', x: 'examine', inspect: 'examine',
-  // inventory
-  inventory: 'inventory', inv: 'inventory', i: 'inventory',
-  // manipulation
-  take: 'take', get: 'take', grab: 'take', 'pick up': 'take',
-  drop: 'drop', put: 'drop', leave: 'drop',
-  use: 'use', combine: 'use',
-  open: 'open', close: 'close',
-  read: 'read', light: 'light', extinguish: 'extinguish', douse: 'extinguish',
-  attack: 'attack', kill: 'attack', fight: 'attack', strike: 'attack',
-  hold: 'hold', show: 'hold',
-  push: 'push', press: 'push',
-  pull: 'pull',
-  cut: 'cut', trim: 'cut',
-  play: 'play',
-  listen: 'listen',
-  pour: 'pour',
-  uncover: 'open',
-  wait: 'wait', z: 'wait',
+export const SUPPORTED_VERBS: Verb[] = [
+  'go',
+  'look',
+  'examine',
+  'take',
+  'drop',
+  'use',
+  'open',
+  'close',
+  'read',
+  'light',
+  'extinguish',
+  'attack',
+  'inventory',
+  'wait',
+  'hold',
+  'push',
+  'pull',
+  'cut',
+  'play',
+  'listen',
+  'pour',
+  'drink',
+]
+
+export const SUPPORTED_META_VERBS: MetaVerb[] = ['restart', 'undo', 'hint', 'save', 'quit', 'theme']
+
+export const DEFAULT_PARSER_VOCABULARY: ParserVocabulary = {
+  directions: {
+    n: ['n', 'north'],
+    s: ['s', 'south'],
+    e: ['e', 'east'],
+    w: ['w', 'west'],
+    u: ['u', 'up'],
+    d: ['d', 'down'],
+  },
+  prepositions: ['with', 'on', 'in', 'to'],
+  stopWords: ['at', 'the', 'a', 'an'],
+  noTargetVerbs: ['look', 'inventory', 'wait', 'listen'],
+  metaVerbs: ['restart', 'undo', 'hint', 'save', 'quit', 'theme'],
+  verbs: {
+    go: ['go', 'walk', 'move'],
+    look: ['look', 'l'],
+    examine: ['examine', 'x', 'inspect'],
+    inventory: ['inventory', 'inv', 'i'],
+    take: ['take', 'get', 'grab', 'pick up'],
+    drop: ['drop', 'put', 'leave'],
+    use: ['use', 'combine'],
+    open: ['open', 'uncover'],
+    close: ['close'],
+    drink: ['drink', 'sip'],
+    read: ['read'],
+    light: ['light'],
+    extinguish: ['extinguish', 'douse'],
+    attack: ['attack', 'kill', 'fight', 'strike'],
+    hold: ['hold', 'show'],
+    push: ['push', 'press'],
+    pull: ['pull'],
+    cut: ['cut', 'trim'],
+    play: ['play'],
+    listen: ['listen'],
+    pour: ['pour'],
+    wait: ['wait', 'z'],
+  },
 }

-const DIRECTION_WORDS: Record<string, Direction> = {
-  n: 'n', north: 'n',
-  s: 's', south: 's',
-  e: 'e', east: 'e',
-  w: 'w', west: 'w',
-  u: 'u', up: 'u',
-  d: 'd', down: 'd',
+interface CompiledVocabulary {
+  directionWords: Record<string, Direction>
+  metaVerbs: Record<string, MetaVerb>
+  verbSynonyms: Record<string, Verb>
+  multiWordVerbs: string[]
+  noTargetVerbs: Set<string>
+  stopWords: Set<string>
+  prepositions: Set<string>
 }

-const META_VERBS: Record<string, MetaVerb> = {
-  restart: 'restart',
-  undo: 'undo',
-  hint: 'hint',
-  save: 'save',
-  quit: 'quit',
-  theme: 'theme',
+function normalizeAlias(value: string): string {
+  return value.trim().toLowerCase().replace(/\s+/g, ' ')
 }

-/** Verbs that legally take no target. */
-const VERB_ONLY_VERBS = new Set<string>(['look', 'inventory', 'wait', 'listen'])
+function compileVocabulary(vocabulary: ParserVocabulary): CompiledVocabulary {
+  const directionWords: Record<string, Direction> = {}
+  for (const [direction, aliases] of Object.entries(vocabulary.directions) as [Direction, string[]][]) {
+    for (const alias of aliases) directionWords[normalizeAlias(alias)] = direction
+  }

-/** Two-word verb prefixes (e.g. "pick up X"). */
-const TWO_WORD_VERBS = ['pick up']
+  const metaVerbs: Record<string, MetaVerb> = {}
+  for (const verb of vocabulary.metaVerbs) metaVerbs[normalizeAlias(verb)] = verb

-/** Leading stop-words stripped from the noun phrase before matching. */
-const STOP_WORDS = new Set(['at', 'the', 'a', 'an'])
+  const verbSynonyms: Record<string, Verb> = {}
+  for (const [verb, aliases] of Object.entries(vocabulary.verbs) as [Verb, string[]][]) {
+    for (const alias of aliases) verbSynonyms[normalizeAlias(alias)] = verb
+  }

-const PREPOSITIONS = new Set(['with', 'on', 'in', 'to'])
+  return {
+    directionWords,
+    metaVerbs,
+    verbSynonyms,
+    multiWordVerbs: Object.keys(verbSynonyms)
+      .filter((alias) => alias.includes(' '))
+      .sort((a, b) => b.split(' ').length - a.split(' ').length),
+    noTargetVerbs: new Set(vocabulary.noTargetVerbs),
+    stopWords: new Set(vocabulary.stopWords.map(normalizeAlias)),
+    prepositions: new Set(vocabulary.prepositions.map(normalizeAlias)),
+  }
+}

 function resolveNoun(rawTokens: string[], ctx: ParserContext): { id: string; alias: string } | null {
  const phrase = rawTokens.join(' ')
@@ -89,19 +150,19 @@ function tokenize(input: string): string[] {
  return input.trim().toLowerCase().split(/\s+/).filter(Boolean)
 }

-function matchTwoWordVerb(tokens: string[]): { verb: Verb; rest: string[] } | null {
-  if (tokens.length < 2) return null
-  const head = tokens.slice(0, 2).join(' ')
-  for (const phrase of TWO_WORD_VERBS) {
-    if (phrase === head) {
-      const verb = VERB_SYNONYMS[phrase]
-      if (verb) return { verb, rest: tokens.slice(2) }
+function matchMultiWordVerb(tokens: string[], vocabulary: CompiledVocabulary): { verb: Verb; rest: string[] } | null {
+  for (const phrase of vocabulary.multiWordVerbs) {
+    const phraseTokens = phrase.split(' ')
+    if (tokens.length >= phraseTokens.length && tokens.slice(0, phraseTokens.length).join(' ') === phrase) {
+      const verb = vocabulary.verbSynonyms[phrase]
+      if (verb) return { verb, rest: tokens.slice(phraseTokens.length) }
    }
  }
  return null
 }

 export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
+  const vocabulary = compileVocabulary(ctx.vocabulary ?? DEFAULT_PARSER_VOCABULARY)
  const trimmed = rawInput.trim()
  if (!trimmed) return { kind: 'unknown', raw: '', reason: 'malformed' }

@@ -116,19 +177,14 @@ export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
  }

  // Meta-commands take precedence (single-word).
-  if (META_VERBS[head] && tokens.length === 1) {
-    return { kind: 'meta', verb: META_VERBS[head]! }
+  if (vocabulary.metaVerbs[head] && tokens.length === 1) {
+    return { kind: 'meta', verb: vocabulary.metaVerbs[head]! }
  }

  // Direction shortcuts: "n", "north", "go n", "go north".
-  if (DIRECTION_WORDS[head] && tokens.length === 1) {
-    return { kind: 'go', direction: DIRECTION_WORDS[head]! }
+  if (vocabulary.directionWords[head] && tokens.length === 1) {
+    return { kind: 'go', direction: vocabulary.directionWords[head]! }
  }
-  if (head === 'go' && tokens.length === 2) {
-    const dir = DIRECTION_WORDS[tokens[1]!]
-    if (dir) return { kind: 'go', direction: dir }
-  }
-
  // Disambiguation reply: a single-word answer matching one of the candidates.
  // Must be checked before verb resolution so "brass" / "iron" etc. are caught.
  if (ctx.awaitingDisambiguation && tokens.length === 1) {
@@ -143,15 +199,15 @@ export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
    }
  }

-  // Two-word verb (e.g. "pick up X").
-  const twoWord = matchTwoWordVerb(tokens)
+  // Multi-word verb aliases (e.g. "pick up X").
+  const twoWord = matchMultiWordVerb(tokens, vocabulary)
  let verb: Verb | undefined
  let rest: string[]
  if (twoWord) {
    verb = twoWord.verb
    rest = twoWord.rest
  } else {
-    verb = VERB_SYNONYMS[head]
+    verb = vocabulary.verbSynonyms[head]
    rest = tokens.slice(1)
  }

@@ -159,26 +215,31 @@ export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
    return { kind: 'unknown', raw: trimmed, reason: 'unknown-verb' }
  }

+  if (verb === 'go' && rest.length === 1) {
+    const dir = vocabulary.directionWords[rest[0]!]
+    if (dir) return { kind: 'go', direction: dir }
+  }
+
  // Strip leading stop-words from the noun phrase (e.g. "at", "the", "a", "an").
-  while (rest.length > 0 && STOP_WORDS.has(rest[0]!)) {
+  while (rest.length > 0 && vocabulary.stopWords.has(rest[0]!)) {
    rest = rest.slice(1)
  }

  if (rest.length === 0) {
-    if (VERB_ONLY_VERBS.has(verb)) {
+    if (vocabulary.noTargetVerbs.has(verb)) {
      return { kind: 'verb-only', verb: verb as 'look' | 'inventory' | 'wait' | 'listen' }
    }
    return { kind: 'unknown', raw: trimmed, reason: 'malformed' }
  }

  // Detect a preposition splitting target | indirect.
-  const prepIdx = rest.findIndex((tok) => PREPOSITIONS.has(tok))
+  const prepIdx = rest.findIndex((tok) => vocabulary.prepositions.has(tok))
  if (prepIdx > 0 && prepIdx < rest.length - 1) {
    const targetTokens = rest.slice(0, prepIdx)
    const prep = rest[prepIdx]!
    let indirectTokens = rest.slice(prepIdx + 1)
    // Strip stop-words at the head of the indirect phrase too ("on the table").
-    while (indirectTokens.length > 0 && STOP_WORDS.has(indirectTokens[0]!)) {
+    while (indirectTokens.length > 0 && vocabulary.stopWords.has(indirectTokens[0]!)) {
      indirectTokens = indirectTokens.slice(1)
    }
    if (indirectTokens.length > 0) {
@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { parse } from './parser'
 import type { ParserContext } from './parser'
-import { dispatch, initialStateFor } from './dispatcher'
+import { dispatch, getItemsInRoom, initialStateFor } from './dispatcher'
 import { world } from '../world'
 import type { GameState } from './types'

@@ -30,6 +30,7 @@ function ctxFor(state: GameState): ParserContext {
    inventoryItemIds: state.inventory.map((i) => i.id),
    lastNoun: state.lastNoun,
    awaitingDisambiguation: state.pendingDisambiguation,
+    vocabulary: world.parser,
  }
 }

@@ -223,4 +224,116 @@ describe('playthrough — sample world', () => {
      'family-register',
    ]))
  })
+
+  it('plays through the conditional rain-room branch', () => {
+    const state = play([
+      'n',                 // gate → foyer
+      'n',                 // foyer → hallway
+      'u',                 // hallway → parlor
+      'u',                 // parlor → upper stair
+      'wait',
+      'd',                 // upper stair → parlor
+      's',                 // parlor → wrong hallway
+      'wait',
+      'n',                 // wrong hallway → rain room
+      'look basin',
+    ])
+
+    expect(state.flags['distant-steps.resolved']).toBe(true)
+    expect(state.flags['rainwater-basin.resolved']).toBe(true)
+    expect(state.flags['rainRoomEntered']).toBe(true)
+    expect(state.endedWith).toBe('replacement')
+  })
+
+  it('reaches the expanded true ending through the vault choice', () => {
+    const state = play([
+      'n',                 // gate → foyer
+      'n',                 // foyer → hallway
+      'n',                 // hallway → dining-room
+      'close curtains',
+      'n',                 // dining-room → conservatory
+      'take shears',
+      'cut vines with shears',
+      's',                 // conservatory → dining-room
+      'w',                 // dining-room → hallway
+      'd',                 // hallway → music-room
+      'play note',
+      'n',                 // music-room → servants-passage
+      'wait',
+      'e',                 // servants-passage → laundry
+      'wait',
+      'take damp sheet',
+      'w',                 // laundry → servants-passage
+      's',                 // servants-passage → music-room
+      'u',                 // music-room → hallway
+      'n',                 // hallway → dining-room
+      'e',                 // dining-room → kitchen
+      'e',                 // kitchen → back-door
+      'e',                 // back-door → garden
+      'wait',
+      'n',                 // garden → well
+      'd',                 // well → well-shaft
+      'wait',
+      'd',                 // well-shaft → tunnel
+      'n',                 // tunnel → ossuary
+      'take ring',
+      'leave ring',
+      'e',                 // ossuary → flooded-passage
+      'use water with sheet',
+      'n',                 // flooded-passage → root-chamber
+      'listen',
+      'e',                 // root-chamber → burial-gallery
+      'examine portraits',
+      'take register',
+      'e',                 // burial-gallery → antechamber
+      'e',                 // antechamber → vault
+      'n',                 // vault → chapel
+      'take vial',
+      'pour vial on basilisk',
+      's',                 // chapel → vault
+      'read register',
+    ])
+
+    expect(state.flags['basiliskSpared']).toBe(true)
+    expect(state.flags['nameSpoken']).toBe(true)
+    expect(state.endedWith).toBe('true')
+  })
+
+  it('passes out after wandering the drunk rooms too long', () => {
+    const state = play([
+      'n',                 // gate → foyer
+      'n',                 // foyer → hallway
+      'n',                 // hallway → dining-room
+      'e',                 // dining-room → kitchen
+      'take whiskey',
+      'drink whiskey',
+      'e', 'w', 'e', 'w', 'e',
+      'w', 'e', 'w', 'e', 'w',
+      'e', 'w', 'e', 'w', 'e',
+      'w', 'e', 'w', 'e', 'w',
+    ])
+
+    expect(state.location).toBe('foyer')
+    expect(state.flags['drunk']).toBe(false)
+    expect(state.flags['drunkMoves']).toBe(0)
+    expect(getItemsInRoom(state, world, 'kitchen')).toContain('whiskey')
+  })
+
+  it('finds the faceless man in the drunk rooms and wakes in the foyer', () => {
+    const state = play([
+      'n',                 // gate → foyer
+      'n',                 // foyer → hallway
+      'n',                 // hallway → dining-room
+      'e',                 // dining-room → kitchen
+      'take whiskey',
+      'drink whiskey',
+      'u',                 // drunk hall → drunk landing
+      'listen',
+    ])
+
+    expect(state.location).toBe('foyer')
+    expect(state.flags['facelessManMet']).toBe(true)
+    expect(state.flags['houseDebtNamed']).toBe(true)
+    expect(state.flags['drunk']).toBe(false)
+  })
 })
@@ -9,7 +9,7 @@ export type Direction = 'n' | 's' | 'e' | 'w' | 'u' | 'd'
 export type Verb =
  | 'go' | 'look' | 'examine' | 'take' | 'drop' | 'use' | 'open' | 'close'
  | 'read' | 'light' | 'extinguish' | 'attack' | 'inventory' | 'wait'
-  | 'hold' | 'push' | 'pull' | 'cut' | 'play' | 'listen' | 'pour'
+  | 'hold' | 'push' | 'pull' | 'cut' | 'play' | 'listen' | 'pour' | 'drink'

 export type MetaVerb = 'restart' | 'undo' | 'hint' | 'save' | 'quit' | 'theme'

@@ -40,6 +40,7 @@ export interface ItemInstance {
 }

 export type EncounterPhase = string  // phase names are encounter-specific
+export type EndingId = string

 export interface TranscriptLine {
  kind: 'narration' | 'player' | 'system' | 'ending'
@@ -59,6 +60,7 @@ export interface PendingConfirmation {

 export interface GameState {
  schemaVersion: number
+  transcriptCap?: number
  location: RoomId
  inventory: ItemInstance[]
  /** Per-room state: visited, items dropped, descriptive flags. */
@@ -77,7 +79,7 @@ export interface GameState {
  /** Capped at 200 entries; older entries are dropped on append. */
  transcript: TranscriptLine[]
  /** Set true when the player has reached an ending. UI shows ending screen. */
-  endedWith: 'true' | 'wrong' | 'bad' | null
+  endedWith: EndingId | null
 }

 export interface DispatchResult {
@@ -1,22 +1,33 @@
 ---
 import '../ui/crt.css'
+import { world } from '../world'
+
+const buildNumber = process.env.CI_PIPELINE_NUMBER ?? 'local'
+const ui = world.ui
+const footerLinks = ui?.footer.links ?? []
+const firstFooterLink = footerLinks[0]
+const remainingFooterLinks = footerLinks.slice(1)
+const bugReport = ui?.bugReport
+const bugpinConfig = bugReport?.enabled ? bugReport.bugpin : undefined
+const bugsinkDsn =
+  bugReport?.enabled && bugReport.bugsink?.enabled ? bugReport.bugsink.dsn : ''
 ---

 <html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-    <title>Halfstreet — Ethan J Lewis</title>
-    <meta name="description" content="A gothic mystery." />
-    <meta name="robots" content="noindex" />
+    <title>{ui?.pageTitle ?? `${world.game?.title ?? 'Halfstreet'} - Ethan J Lewis`}</title>
+    <meta name="description" content={ui?.description ?? world.game?.description ?? 'A gothic mystery.'} />
+    <meta name="robots" content={ui?.robots ?? 'noindex'} />
    <link rel="icon" href="/favicon.ico" sizes="any" />
    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
    <link rel="icon" href="/favicon-96x96.png" type="image/png" sizes="96x96" />
    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
    <link rel="manifest" href="/site.webmanifest" />
-    <meta name="theme-color" content="#1a0d00" />
+    <meta name="theme-color" content={ui?.themeColor ?? '#1a0d00'} />
  </head>
-  <body>
+  <body data-bugsink-dsn={bugsinkDsn}>
    <div class="mystery-root" data-mystery-root>
      <div class="mystery-bezel">
        <div class="mystery-options" data-mystery-options>
@@ -50,16 +61,20 @@ import '../ui/crt.css'
            </div>
            <div class="mystery-options-group" aria-label="Game">
              <div class="mystery-options-label">Game</div>
+              {ui?.features.chips !== false && (
+                <>
                  <button type="button" data-chips-choice="on" aria-pressed="true">Chips On</button>
                  <button type="button" data-chips-choice="off" aria-pressed="false">Chips Off</button>
+                </>
+              )}
              <button type="button" data-restart-choice>Restart</button>
            </div>
          </div>
        </div>
        <div class="mystery-transcript" data-mystery-transcript aria-live="polite" aria-atomic="false"></div>
        <div class="mystery-controls">
-          <div class="mystery-chips" data-mystery-chips></div>
-          <div class="mystery-light-meter" data-mystery-light-meter aria-hidden="true"></div>
+          {ui?.features.chips !== false && <div class="mystery-chips" data-mystery-chips></div>}
+          {ui?.features.lightMeter !== false && <div class="mystery-light-meter" data-mystery-light-meter aria-hidden="true"></div>}
        </div>
        <div class="mystery-input-row">
          <input
@@ -76,11 +91,39 @@ import '../ui/crt.css'
        </div>
      </div>
      <footer class="mystery-footer">
-        © 2026 <a href="https://ethanjlewis.com">Ethan J Lewis</a>
+        {ui?.footer.copyrightHref ? <a href={ui.footer.copyrightHref}>{ui.footer.copyright}</a> : <span>{ui?.footer.copyright ?? '© 2026 Ethan J Lewis'}</span>}
+        {firstFooterLink && (
+          <>
            <span aria-hidden="true">|</span>
-        <a href="https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE">GNU 3.0</a>
+            <a href={firstFooterLink.href}>{firstFooterLink.label}</a>
+          </>
+        )}
+        {ui?.footer.showBuild !== false && (
+          <>
            <span aria-hidden="true">|</span>
-        <a href="https://half.st/ejlewis/halfstreet">Source Code</a>
+            <span>{ui?.footer.buildLabel ?? 'Build #'}{buildNumber}</span>
+          </>
+        )}
+        {remainingFooterLinks.map((link) => (
+          <>
+            <span aria-hidden="true">|</span>
+            <a href={link.href}>{link.label}</a>
+          </>
+        ))}
+        {bugpinConfig && (
+          <>
+            <span aria-hidden="true">|</span>
+            <button
+              type="button"
+              class="mystery-footer-bug-report"
+              data-bug-report-trigger
+              data-bugpin-server={bugpinConfig.serverUrl}
+              data-bugpin-key={bugpinConfig.apiKey}
+              aria-describedby="bug-report-status"
+            >{bugReport?.label ?? 'Report a Bug'}</button>
+            <span id="bug-report-status" class="mystery-footer-status" aria-live="polite"></span>
+          </>
+        )}
      </footer>
    </div>
    <script>
@@ -105,6 +148,8 @@ import '../ui/crt.css'
    <script>
      import '../ui/terminal.ts'
      import '../ui/theme.ts'
+      import '../ui/error-tracking.ts'
+      import '../ui/bug-report.ts'
    </script>
  </body>
 </html>
@@ -0,0 +1,126 @@
+interface BugPinAPI {
+  init: (config: { apiKey: string, serverUrl: string }) => Promise<void> | void
+  open: () => void
+  close: () => void
+}
+
+declare global {
+  interface Window {
+    BugPin?: BugPinAPI
+  }
+}
+
+const launcherSelector = [
+  '.fixed.bottom-5.right-5',
+  '.fixed.bottom-5.left-5',
+  '.fixed.top-5.right-5',
+  '.fixed.top-5.left-5',
+].join(',')
+const button = document.querySelector<HTMLButtonElement>('[data-bug-report-trigger]')
+let loadPromise: Promise<void> | null = null
+let initialized = false
+let launcherObserver: MutationObserver | null = null
+
+function setStatus(message: string): void {
+  const targetId = button?.getAttribute('aria-describedby')
+  const target = targetId ? document.getElementById(targetId) : null
+  if (target) target.textContent = message
+}
+
+function buildWidgetSrc(serverUrl: string): string {
+  return `${serverUrl.replace(/\/$/, '')}/widget.js`
+}
+
+function loadWidget(serverUrl: string): Promise<void> {
+  if (window.BugPin) return Promise.resolve()
+  if (loadPromise) return loadPromise
+
+  loadPromise = new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = buildWidgetSrc(serverUrl)
+    script.async = true
+    script.addEventListener('load', () => resolve())
+    script.addEventListener('error', () => {
+      loadPromise = null
+      reject(new Error(`Failed to load BugPin widget from ${script.src}`))
+    })
+    document.head.appendChild(script)
+  })
+
+  return loadPromise
+}
+
+function hideBugPinLauncher(): void {
+  const host = document.getElementById('bugpin-widget')
+  const root = host?.shadowRoot
+  if (!root) return
+
+  for (const launcher of root.querySelectorAll<HTMLElement>(launcherSelector)) {
+    launcher.hidden = true
+    launcher.style.display = 'none'
+    launcher.setAttribute('aria-hidden', 'true')
+  }
+}
+
+function watchBugPinLauncher(): void {
+  const host = document.getElementById('bugpin-widget')
+  const root = host?.shadowRoot
+  if (!root || launcherObserver) return
+
+  hideBugPinLauncher()
+  launcherObserver = new MutationObserver(() => hideBugPinLauncher())
+  launcherObserver.observe(root, { childList: true, subtree: true })
+}
+
+function waitForBugPinEffects(): Promise<void> {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => setTimeout(resolve, 0))
+  })
+}
+
+async function openBugReport(serverUrl: string, apiKey: string): Promise<void> {
+  await loadWidget(serverUrl)
+
+  if (!window.BugPin) {
+    throw new Error('BugPin widget loaded, but window.BugPin is unavailable')
+  }
+
+  if (!initialized) {
+    await window.BugPin.init({ apiKey, serverUrl })
+    initialized = true
+    watchBugPinLauncher()
+    await waitForBugPinEffects()
+  }
+
+  hideBugPinLauncher()
+  window.BugPin.open()
+  hideBugPinLauncher()
+}
+
+if (button) {
+  const serverUrl = button.dataset.bugpinServer
+  const apiKey = button.dataset.bugpinKey
+
+  if (serverUrl && apiKey) {
+    button.addEventListener('click', async (event) => {
+      event.preventDefault()
+      setStatus('')
+      button.disabled = true
+
+      try {
+        await openBugReport(serverUrl, apiKey)
+      } catch (err) {
+        console.error('[bug-report]', err)
+        setStatus("Couldn't open bug reporter - try refreshing.")
+      } finally {
+        button.disabled = false
+      }
+    })
+  }
+}
+
+if (window.BugPin) {
+  requestAnimationFrame(() => watchBugPinLauncher())
+}
+
+export {}
@@ -89,11 +89,35 @@ body {
  text-align: center;
 }

-.mystery-footer a {
+.mystery-footer a,
+.mystery-footer-bug-report {
  color: var(--m-fg);
  text-decoration: none;
 }

+.mystery-footer-bug-report {
+  background: none;
+  border: none;
+  padding: 0;
+  margin: 0;
+  font: inherit;
+  cursor: pointer;
+}
+
+.mystery-footer-bug-report:hover,
+.mystery-footer-bug-report:focus-visible {
+  text-decoration: underline;
+}
+
+.mystery-footer-bug-report:disabled {
+  cursor: progress;
+  opacity: 0.55;
+}
+
+.mystery-footer-status {
+  color: var(--m-fg);
+}
+
 .mystery-footer span {
  margin: 0 0.5ch;
 }
@@ -115,6 +139,35 @@ body {
  z-index: 1;
 }

+.mystery-bezel::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  z-index: 2;
+  opacity: 0;
+}
+
+:root[data-mystery-drunk] .mystery-bezel::after {
+  background:
+    linear-gradient(
+      93deg,
+      transparent 0 48%,
+      color-mix(in srgb, var(--m-fg) 12%, transparent) 49% 50%,
+      transparent 51% 100%
+    ),
+    repeating-linear-gradient(
+      to bottom,
+      transparent 0 9px,
+      color-mix(in srgb, var(--m-fg) 8%, transparent) 9px 10px,
+      transparent 10px 23px
+    );
+  mix-blend-mode: screen;
+  opacity: 0.32;
+  transform: translateX(0.32ch) skewX(-1.4deg);
+  animation: mystery-drunk-screen 5.8s ease-in-out infinite;
+}
+
 .mystery-options {
  position: absolute;
  top: 8px;
@@ -308,6 +361,30 @@ body {
  margin: 0.25em 0;
 }

+:root[data-mystery-drunk] .mystery-transcript {
+  filter: blur(0.35px) contrast(1.05);
+  text-shadow:
+    0.055em 0.02em currentColor,
+    -0.075em -0.015em color-mix(in srgb, var(--m-fg) 50%, transparent),
+    0.14em 0 color-mix(in srgb, var(--m-accent-2) 26%, transparent),
+    0 0 4px currentColor;
+  animation: mystery-drunk-copy 6.4s ease-in-out infinite;
+}
+
+:root[data-mystery-drunk] .mystery-transcript .player,
+:root[data-mystery-drunk] .mystery-transcript .system,
+:root[data-mystery-drunk] .mystery-transcript .narration {
+  transform: translateX(0.12ch) skewX(-1.2deg);
+}
+
+:root[data-mystery-drunk] .mystery-transcript > div:nth-child(2n) {
+  transform: translateX(-0.18ch) skewX(0.8deg);
+}
+
+:root[data-mystery-drunk] .mystery-transcript > div:nth-child(3n) {
+  transform: translateX(0.28ch) skewX(-1.4deg);
+}
+
 .mystery-input-row {
  display: flex;
  align-items: center;
@@ -370,6 +447,26 @@ body {
  animation: mystery-cursor-blink 1.05s steps(1, end) infinite;
 }

+:root[data-mystery-drunk] .mystery-input-row {
+  filter: blur(0.2px);
+  transform: translateX(0.2ch);
+  text-shadow:
+    0.12em 0 currentColor,
+    -0.16em 0 color-mix(in srgb, var(--m-accent-2) 42%, transparent),
+    0 0 5px currentColor;
+}
+
+:root[data-mystery-drunk] .mystery-input-row::before {
+  content: '>>';
+  letter-spacing: -0.4ch;
+}
+
+:root[data-mystery-drunk] .mystery-input-display::after {
+  text-shadow:
+    0.22em 0 currentColor,
+    -0.18em 0 color-mix(in srgb, var(--m-fg) 50%, transparent);
+}
+
 :root[data-mystery-input-focused] .mystery-input-display::after {
  animation: mystery-cursor-blink 1.05s steps(1, end) infinite;
 }
@@ -379,6 +476,31 @@ body {
  50%, 100% { opacity: 0; }
 }

+@keyframes mystery-drunk-copy {
+  0%, 18%, 100% {
+    filter: blur(0.2px) contrast(1.03);
+    transform: translate(0, 0) skewX(0);
+  }
+  36% {
+    filter: blur(0.8px) contrast(1.08);
+    transform: translate(0.12ch, -0.04em) skewX(-0.25deg);
+  }
+  58% {
+    filter: blur(0.3px) contrast(1.04);
+    transform: translate(-0.06ch, 0.02em) skewX(0.08deg);
+  }
+  76% {
+    filter: blur(0.65px) contrast(1.07);
+    transform: translate(-0.18ch, 0.05em) skewX(0.32deg);
+  }
+}
+
+@keyframes mystery-drunk-screen {
+  0%, 100% { transform: translateX(0.32ch) skewX(-1.4deg); }
+  45% { transform: translateX(-0.22ch) skewX(1.1deg); }
+  72% { transform: translateX(0.5ch) skewX(-0.6deg); }
+}
+
 .mystery-controls {
  display: flex;
  align-items: flex-start;
@@ -479,6 +601,17 @@ body {
  cursor: not-allowed;
 }

+:root[data-mystery-drunk] .mystery-chip {
+  transform: rotate(-0.6deg);
+  text-shadow:
+    0.1em 0 currentColor,
+    -0.1em 0 color-mix(in srgb, var(--m-fg) 35%, transparent);
+}
+
+:root[data-mystery-drunk] .mystery-chip:nth-child(2n) {
+  transform: translateY(1px) rotate(0.8deg);
+}
+
 .mystery-transcript .ending {
  margin-top: 2em;
  margin-bottom: 1em;
@@ -0,0 +1,12 @@
+import * as Sentry from '@sentry/browser'
+
+const dsn = document.body?.dataset.bugsinkDsn ?? ''
+
+if (dsn) {
+  Sentry.init({
+    dsn,
+    tracesSampleRate: 0,
+    replaysSessionSampleRate: 0,
+    replaysOnErrorSampleRate: 0,
+  })
+}
@@ -1,8 +1,9 @@
 import { parse } from '../engine/parser'
 import type { ParserContext } from '../engine/parser'
-import { dispatch, initialStateFor, getItemsInRoom, getLightStatus, LIGHT_TURNS_MAX } from '../engine/dispatcher'
+import { dispatch, initialStateFor, getItemsInRoom, getLightStatus } from '../engine/dispatcher'
 import { saveState, loadState, clearSave } from '../engine/save'
 import { world } from '../world'
+import { DEFAULT_WORLD_MESSAGES, type WorldMessageKey } from '../world/types'
 import type { GameState, TranscriptLine } from '../engine/types'
 import { TRANSCRIPT_CAP } from '../engine/types'
 import { computeChips } from './chips'
@@ -14,24 +15,17 @@ const inputEl = document.querySelector<HTMLInputElement>('[data-mystery-input]')
 const inputDisplayEl = document.querySelector<HTMLSpanElement>('[data-mystery-input-display]')
 const lightMeterEl = document.querySelector<HTMLDivElement>('[data-mystery-light-meter]')

-const HELP_TEXT = `You arrive at the address, but you do not remember what has happened. The road behind you is gone...
+const HELP_TEXT = world.game?.helpText ?? `This is a text adventure. Type short commands to act.`
+const UI_FEATURES = world.ui?.features ?? {
+  chips: true,
+  lightMeter: true,
+  typedEffect: true,
+  roomScroll: true,
+}

-This is a text adventure. Type short commands to act in the house.
-
-Common commands:
-look                    describe the room again
-n, s, e, w, u, d        move by direction
-take lamp               pick something up
-examine letter          inspect something nearby or held
-read letter             read a readable object
-inventory               see what you carry
-light lamp with matches use one thing with another
-wait                    let the room continue
-undo                    step back once
-restart                 begin again
-theme                   change the terminal colors
-
-Most commands are verb first, then the thing: examine gate, take lamp, use key on door.`
+function message(key: WorldMessageKey): string {
+  return world.messages?.[key] ?? DEFAULT_WORLD_MESSAGES[key]
+}

 if (!transcriptEl || !inputEl || !inputDisplayEl) {
  console.error('[halfstreet] terminal mount points missing')
@@ -53,6 +47,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
  const ROOM_SCROLL_MS = 180

  const syncLightMeter = (): void => {
+    if (!UI_FEATURES.lightMeter) return
    if (!lightMeterEl) return
    const status = getLightStatus(state, world)
    lightMeterEl.hidden = !status
@@ -75,8 +70,8 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {

    const leds = document.createElement('div')
    leds.className = 'mystery-light-leds'
-    const turnsLeft = Math.max(0, Math.min(LIGHT_TURNS_MAX, status.turnsLeft))
-    for (let i = 0; i < LIGHT_TURNS_MAX; i++) {
+    const turnsLeft = Math.max(0, Math.min(status.maxTurns, status.turnsLeft))
+    for (let i = 0; i < status.maxTurns; i++) {
      const segment = document.createElement('span')
      segment.className = 'mystery-light-segment'
      const lit = i < turnsLeft
@@ -98,6 +93,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
  }

  function refreshChips(): void {
+    if (!UI_FEATURES.chips) return
    renderChips(computeChips(state, world), (command) => {
      clearIdleHint()
      inputEl!.value = command
@@ -119,6 +115,10 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
    inputEl!.classList.toggle('ended', state.endedWith !== null)
  }

+  const syncDrunkEffect = (): void => {
+    document.documentElement.toggleAttribute('data-mystery-drunk', state.flags['drunk'] === true)
+  }
+
  const syncCommandLine = (): void => {
    const visibleText = inputEl.value || inputEl.placeholder
    inputDisplayEl.textContent = visibleText
@@ -156,6 +156,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      inventoryItemIds: s.inventory.map((i) => i.id),
      lastNoun: s.lastNoun,
      awaitingDisambiguation: s.pendingDisambiguation,
+      vocabulary: world.parser,
    }
  }

@@ -270,7 +271,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
  }

  const renderAll = (lines: TranscriptLine[], options: { animate?: boolean; scroll?: boolean } = {}): void => {
-    const animate = options.animate ?? true
+    const animate = (options.animate ?? true) && UI_FEATURES.typedEffect
    const shouldScroll = options.scroll ?? true
    const generation = renderGeneration
    renderQueue = renderQueue.then(() => renderLines(lines, animate, shouldScroll, generation)).catch((err) => {
@@ -369,12 +370,14 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
    refreshChips()
    syncLightMeter()
    syncEndedUI()
+    syncDrunkEffect()
  }

  renderAll(state.transcript, { animate: false })
  refreshChips()
  syncLightMeter()
  syncEndedUI()
+  syncDrunkEffect()
  syncCommandLine()
  scheduleIdleHint()

@@ -437,8 +440,9 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
        refreshChips()
        syncLightMeter()
        syncEndedUI()
+        syncDrunkEffect()
      } else {
-        appendLines([{ kind: 'system', text: 'There is no further back.' }], { scroll: false })
+        appendLines([{ kind: 'system', text: message('no-undo') }], { scroll: false })
      }
      return
    }
@@ -456,7 +460,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      const previousLocation = state.location
      const result = dispatch(state, command, world)
      state = result.state
-      const shouldScrollToRoom = command.kind === 'go' && state.location !== previousLocation
+      const shouldScrollToRoom = UI_FEATURES.roomScroll && command.kind === 'go' && state.location !== previousLocation
      renderAll(result.appended, { scroll: shouldScrollToRoom })  // dispatch already pushed these into state.transcript
      saveState(state)
      if (raw.trim().toLowerCase() === 'theme') {
@@ -465,6 +469,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      refreshChips()
      syncLightMeter()
      syncEndedUI()
+      syncDrunkEffect()
    } catch (err) {
      console.error('[halfstreet] dispatch error', err)
      appendLines([{ kind: 'system', text: '[ The terminal hums and resets. ]' }], { scroll: false })
@@ -4,7 +4,7 @@
  "showTags": false,
  "showAttachments": false,
  "hideUnresolved": false,
-  "showOrphans": true,
+  "showOrphans": false,
  "collapse-color-groups": false,
  "colorGroups": [
    {
@@ -37,9 +37,9 @@
    }
  ],
  "collapse-display": false,
-  "showArrow": false,
-  "textFadeMultiplier": 0,
-  "nodeSizeMultiplier": 1.82265625,
+  "showArrow": true,
+  "textFadeMultiplier": -3,
+  "nodeSizeMultiplier": 2.2138427734375,
  "lineSizeMultiplier": 5,
  "collapse-forces": false,
  "centerStrength": 0.518713248970312,
@@ -0,0 +1,11 @@
+{
+  "markdown:add-metadata-property": [],
+  "editor:toggle-source": [
+    {
+      "modifiers": [
+        "Mod"
+      ],
+      "key": ";"
+    }
+  ]
+}
@@ -0,0 +1,6 @@
+---
+short:
+readable:
+takeable:
+names:
+---
@@ -17,6 +17,7 @@ views:
      - exitW
      - exitU
      - exitD
+      - items
  - type: cards
    name: Items
    filters:
@@ -29,3 +30,11 @@ views:
      - takeable
      - names
      - formula.Room
+  - type: cards
+    name: Items By Room
+    filters:
+      and:
+        - file.inFolder("items")
+    order:
+      - file.name
+      - formula.Room
@@ -41,8 +41,9 @@
 - [ ] FEATURE: Add a Safe to somewhere that it makes sense (the bedroom?) We can add a safe-cracking mini-game. The safe contains a single bullet, which can be used with the revolver. 
 - [ ] FEATURE: Add item Revolver, which can be used to kill the thing at the end. It comes with no bullets, so players need to defeat the safe-cracking minjgame. Place the revolver somewhere it takes the player some effort to find. 
 - [ ] Feature: A faceless voice that speaks in a whisper in the smoking room, which demands whiskey and dispenses riddles if the player finds a bottle of whiskey (but hasn't drunk it yet). The riddles are randomly chosen from a list of 25 difficult riddles (source them). If the riddle is answered correctly there needs to be some reward and maybe a major plot point is revealed. 
- [ ] Add item Whiskey bottle, half full of something smoky. In the kitchen. Drinking it gets the player drunk, which causes them to unlock the drunk rooms, which are a series of rooms where they can go many directions, but somehow end up in seemingly back in the same spot. They are essentially a maze of doors and hallways, ladders and levels. There should be boundaries established though, it shouldn't be endless. After 20 or so moves the player passes out and wakes up back in the foyer, with the whiskey bottle returned to the kitchen, somehow still half full. Add a random encounter in the dark rooms, a creaking floorboard helps you find a secret door that opens with a faceless man inside who gives you major plot info. After this encounter you pass out and wake up in the lobby as before.
- [ ] Set up BugPin as a self-hosted visual bug reporter for the site, then have incoming reports create markdown files under `src/world/bugs/` via a webhook or API bridge so bugs can be tracked in git alongside the game content. Include screenshot/annotation metadata in the markdown and decide whether these bug docs stay outside the world loader or get their own loader later.
+- [x] Add item Whiskey bottle, half full of something smoky. In the kitchen. Drinking it gets the player drunk, which causes them to unlock the drunk rooms, which are a series of rooms where they can go many directions, but somehow end up in seemingly back in the same spot. They are essentially a maze of doors and hallways, ladders and levels. There should be boundaries established though, it shouldn't be endless. After 20 or so moves the player passes out and wakes up back in the foyer, with the whiskey bottle returned to the kitchen, somehow still half full. Add a random encounter in the dark rooms, a creaking floorboard helps you find a secret door that opens with a faceless man inside who gives you major plot info. After this encounter you pass out and wake up in the lobby as before. When the player is "drunk" the text on the terminal should appear blurry, like the user has double vision. 
+- [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st -> forwards to GitHub Issues). Add Bugsink (@sentry/browser -> bugsink.half.st) for automatic JS error capture. Mark complete after manual verification: a test report appears in the Bugpin portal AND a GitHub issue is created AND a thrown error appears in the Bugsink portal.
 - [ ] BUG: It says the door closes behind you when you enter the lobby, but you can still exit S to the gate.
 - [x] FEATURE: Add a short "typed" effect to the text. Make it look like it's being typed out, if that makes sense, one character at a time. The effect should be brief. 
 - [x] FEATURE: Whenever you change rooms, scroll the text so the name of the room you're in is at the top. Users can scroll up to see the history. This should be an effect where the old text slides up to make room for the new text, and this should happen before the "typed" effect.
+- [ ] Open-source authoring architecture: follow [[open-source-authoring-roadmap]] to move as much story, parser, mechanic, action, and UI configuration as practical into markdown under `src/world` so authors can control it from Obsidian.
@@ -0,0 +1,27 @@
+---
+id: burn-letter
+verbs: [use]
+requires:
+  allVisibleOrHeld:
+    - "[[letter]]"
+    - "[[matches]]"
+consumes:
+  inventory:
+    - "[[letter]]"
+decrements:
+  item: "[[matches]]"
+  stateKey: uses
+setsFlags:
+  letterBurned: true
+---
+
+# Burn Letter
+
+## success
+The letter catches at one corner. In a few breaths it is ash.
+
+## spent
+The matchbook is empty.
+
+## missingRequired
+You don't see the letter here.
@@ -0,0 +1,33 @@
+---
+id: drink-whiskey
+verbs: [drink]
+handler: drunk-transition
+requires:
+  allHeld:
+    - "[[whiskey]]"
+consumes:
+  inventory:
+    - "[[whiskey]]"
+drunkTransition:
+  destinationRoom: "[[drunk-hall]]"
+  maxMoves: 20
+  wakeRoom: "[[foyer]]"
+  resetRoom: "[[kitchen]]"
+---
+
+# Drink Whiskey
+
+## success
+You drink from the bottle. It tastes of smoke, sugar, and rainwater left too long in a pipe.
+
+## missingRequired
+You'd have to be carrying it.
+
+## secretFoundPassOut
+The faceless man steps backward into the dark. The floor rises under you, or you fall toward it.
+
+## tooManyMovesPassOut
+The rooms keep turning until they become one room. Then even that room is gone.
+
+## reset
+The bottle is not with you. Somewhere in the kitchen, it is half full again.
@@ -0,0 +1,155 @@
+# Authoring Halfstreet
+
+Halfstreet is authored from this `src/world` vault. The TypeScript runtime loads and validates the markdown; ordinary story changes should start here.
+
+Use wikilinks for references when you can. The loader accepts `[[foyer]]` and stores it as `foyer`, so Obsidian links stay useful without changing runtime ids.
+
+## Forking The Game
+
+The current open-source shape is a forkable Astro app. Keep `src/engine`, `src/ui`, and `src/pages` in place, then replace the markdown in this vault with your own rooms, items, encounters, endings, mechanics, actions, parser vocabulary, and UI labels.
+
+For a new game, update these files first:
+
+- `game.md`: title, starting room, starting inventory, ending priority, opening art, help text, and end text.
+- `parser.md`: direction words, verb aliases, prepositions, stop words, no-target verbs, and meta verbs.
+- `ui.md`: page title, meta description, footer labels and links, build label, and UI feature switches.
+- `templates/`: copy these starter files when adding new world content.
+
+After edits, run `npm test` from the repo root. Validation errors are meant to point back to the markdown field or section that needs fixing.
+
+## Rooms
+
+Room files live in `rooms/`. Every room needs frontmatter plus three prose sections:
+
+- `## first-visit`
+- `## revisit`
+- `## examined`
+
+Set unused exits to `null`. Set exits to `[[room-id]]` when they lead somewhere. Put item ids in `items`, and set `encounter` when a room starts an encounter.
+
+```yaml
+id: sample-room
+title: "[ Sample Room ]"
+exitN: "[[other-room]]"
+exitS: null
+exitE: null
+exitW: null
+exitU: null
+exitD: null
+items:
+  - "[[sample-key]]"
+encounter: null
+safe: true
+```
+
+Locked exits use a matching `exitXRequires` and `exitXLockedText` pair. The requirement must be an item id or a known flag.
+
+```yaml
+exitN: "[[locked-room]]"
+exitNRequires: sample-key
+exitNLockedText: The door will not move.
+```
+
+## Items
+
+Item files live in `items/`. The prose before the first `##` header is the long description shown by `examine`.
+
+Use `readable: true` only when the item has a `## read` section. Use `lightable: true` for items that can be lit, and `lighter: true` for items that can light other items.
+
+```yaml
+id: sample-key
+names: ["key", "sample key"]
+short: "a sample key"
+takeable: true
+initialState: {}
+```
+
+Allowed optional item sections are:
+
+- `## read`
+- `## lit`
+- `## extinguished`
+- `## lighter-empty`
+
+## Encounters
+
+Encounter files live in `encounters/`. Encounters are state machines: `initialPhase` points to a phase, each phase points to a description section, and each transition points to a narration section.
+
+```yaml
+id: sample-encounter
+startsIn: "[[sample-room]]"
+initialPhase: waiting
+aliases: [figure, shape]
+defaultWrongVerbNarration: wrong-verb
+phases:
+  waiting:
+    description: waiting
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: waited
+        to: resolved
+```
+
+Use `onResolved.setFlags` for flags that endings or locked exits can read. Use `requires.item` on a transition when the player must hold a specific item.
+
+## Endings
+
+Ending files live in `endings/`. `whenFlags` controls when an ending is available, and the markdown body is the ending narration.
+
+Quote ids that look like booleans:
+
+```yaml
+id: "true"
+whenFlags:
+  familySecretKnown: true
+```
+
+Bare `id: true` is parsed as a boolean by YAML before the loader sees it.
+
+## Mechanics
+
+Mechanic files live in `mechanics/`. They configure named TypeScript handlers without moving the algorithms into markdown.
+
+`mechanics/light.md` controls the light timer, burn triggers, state keys, meter setting, and fallback light prose. `mechanics/resolve.md` controls resolve levels, wrong-verb cost, safe-room recovery, and retreat behavior.
+
+Keep `handler` set to the supported handler name. Set `enabled: false` to disable a mechanic cleanly.
+
+## Actions
+
+Action files live in `actions/`. Simple actions can require visible or held items, consume inventory, decrement item state, set flags, and narrate success.
+
+```yaml
+id: sample-action
+verbs: [use]
+requires:
+  allVisibleOrHeld:
+    - "[[sample-key]]"
+setsFlags:
+  sampleActionDone: true
+```
+
+Every default action needs `## success`. Handler-backed actions may require extra sections. For example, the `drunk-transition` handler requires `## success`, `## secretFoundPassOut`, `## tooManyMovesPassOut`, and `## reset`.
+
+## Game, Parser, Messages, And UI
+
+- `game.md` controls the title, description, starting room, starting inventory, ending priority, transcript cap, opening art, help text, and ended text.
+- `parser.md` controls directions, verb aliases, prepositions, stop words, no-target verbs, and meta verbs.
+- `messages.md` controls common system prose.
+- `ui.md` controls page metadata, footer labels and links, build label visibility, and UI feature toggles.
+
+## Common Validation Errors
+
+`missing required section "## first-visit"`: add the exact section header to the room file. Section names must use only letters, digits, hyphens, and underscores.
+
+`## read section is required when readable: true`: either add `## read` to the item or remove `readable: true`.
+
+`frontmatter references missing section`: an encounter phase, transition, or failure references a prose key that does not exist. Add the section or fix the key.
+
+`exitNRequires is set but exitNLockedText is missing`: locked exits need both the requirement and locked narration fields.
+
+`references unknown item` or `references unknown room`: check the wikilink/id spelling and make sure the referenced file exists in the matching folder.
+
+`endingPriority references "true" but endings/true.md is missing`: quote boolean-like ids in YAML and make sure the ending file exists.
+
+`unknown message section` or `unknown item section`: the loader only accepts known section keys. Rename the header to one of the allowed keys for that file type.
@@ -1,7 +1,83 @@
 import { describe, it, expect } from 'vitest'
-import { world } from './index'
+import { assembleWorld, world } from './index'
+import type { GameManifest, Item, Room, World } from './types'
+
+const manifest: GameManifest = {
+  id: 'test',
+  title: 'Test',
+  description: 'A tiny test world.',
+  startingRoom: 'foyer',
+  startingInventory: ['letter'],
+  endingPriority: ['true'],
+}
+
+const rooms: Record<string, Room> = {
+  foyer: {
+    id: 'foyer',
+    title: '[ Foyer ]',
+    descriptions: {
+      firstVisit: 'You are here.',
+      revisit: 'Still here.',
+      examined: 'A foyer.',
+    },
+    exits: {},
+    items: [],
+  },
+}
+
+const items: Record<string, Item> = {
+  letter: {
+    id: 'letter',
+    names: ['letter'],
+    short: 'a letter',
+    long: 'A folded letter.',
+    initialState: {},
+    takeable: true,
+  },
+}
+
+const endings: World['endings'] = {
+  true: { whenFlags: {}, narration: 'The end.' },
+}
+
+function build(overrides: Partial<Parameters<typeof assembleWorld>[0]> = {}) {
+  return assembleWorld({
+    game: manifest,
+    rooms,
+    items,
+    endings,
+    encounters: {},
+    encounterDocs: [],
+    ...overrides,
+  })
+}

 describe('assembled world', () => {
+  it('assembles a minimal manifest-backed world', () => {
+    const result = build()
+    expect(result.startingRoom).toBe('foyer')
+    expect(result.startingInventory).toEqual(['letter'])
+    expect(result.endingPriority).toEqual(['true'])
+  })
+
+  it('rejects a game manifest with an unknown starting room', () => {
+    expect(() => build({
+      game: { ...manifest, startingRoom: 'missing-room' },
+    })).toThrow(/startingRoom references "missing-room"/)
+  })
+
+  it('rejects a game manifest with an unknown starting inventory item', () => {
+    expect(() => build({
+      game: { ...manifest, startingInventory: ['missing-item'] },
+    })).toThrow(/startingInventory references unknown item "missing-item"/)
+  })
+
+  it('rejects a game manifest with an unknown ending priority entry', () => {
+    expect(() => build({
+      game: { ...manifest, endingPriority: ['missing-ending'] },
+    })).toThrow(/endingPriority references "missing-ending"/)
+  })
+
  it('contains the authored opening and main-floor rooms', () => {
    expect(Object.keys(world.rooms)).toEqual(expect.arrayContaining([
      'outside-gate',
@@ -88,16 +164,356 @@ describe('assembled world', () => {
  })

  it('startingRoom is a known room', () => {
+    expect(world.game?.startingRoom).toBe(world.startingRoom)
    expect(world.rooms[world.startingRoom]).toBeDefined()
  })

  it('startingInventory items are known', () => {
+    expect(world.game?.startingInventory).toEqual(world.startingInventory)
    for (const itemId of world.startingInventory) {
      expect(world.items[itemId]).toBeDefined()
    }
  })

+  it('game manifest text is loaded from markdown', () => {
+    expect(world.game?.title).toBe('Halfstreet')
+    expect(world.game?.openingArt).toContain('____')
+    expect(world.game?.helpText).toContain('This is a text adventure.')
+    expect(world.game?.endedText).toContain('The story has ended.')
+  })
+
+  it('parser vocabulary is loaded from markdown', () => {
+    expect(world.parser?.verbs.take).toContain('pick up')
+    expect(world.parser?.verbs.open).toContain('uncover')
+    expect(world.parser?.directions.n).toContain('north')
+  })
+
+  it('UI config is loaded from markdown', () => {
+    expect(world.ui?.pageTitle).toBe('Halfstreet - Ethan J Lewis')
+    expect(world.ui?.footer.links.map((link) => link.label)).toEqual(['GNU 3.0', 'Source Code'])
+    expect(world.ui?.footer.showBuild).toBe(true)
+    expect(world.ui?.features.typedEffect).toBe(true)
+  })
+
+  it('system messages are loaded from markdown', () => {
+    expect(world.messages?.['unknown-verb']).toContain("don't fit this place")
+    expect(world.messages?.taken).toBe('Taken.')
+  })
+
+  it('light mechanic config is loaded from markdown', () => {
+    expect(world.mechanics?.light?.enabled).toBe(true)
+    expect(world.mechanics?.light?.maxTurns).toBe(6)
+    expect(world.mechanics?.light?.burnOn).toEqual(['move', 'wait'])
+    expect(world.mechanics?.light?.messages?.flameDies).toBe('The flame dies.')
+  })
+
+  it('resolve mechanic config is loaded from markdown', () => {
+    expect(world.mechanics?.resolve?.enabled).toBe(true)
+    expect(world.mechanics?.resolve?.ladder).toEqual(['steady', 'shaken', 'reeling', 'returning'])
+    expect(world.mechanics?.resolve?.safeRooms.recoverySteps).toBe(1)
+    expect(world.mechanics?.resolve?.failure.afterRetreat).toBe('shaken')
+  })
+
+  it('declarative actions are loaded from markdown', () => {
+    expect(world.actions?.['burn-letter']?.verbs).toEqual(['use'])
+    expect(world.actions?.['burn-letter']?.requires?.allVisibleOrHeld).toEqual(['letter', 'matches'])
+    expect(world.actions?.['burn-letter']?.messages.success).toContain('ash')
+  })
+
+  it('handler-backed actions are loaded from markdown', () => {
+    expect(world.actions?.['drink-whiskey']?.verbs).toEqual(['drink'])
+    expect(world.actions?.['drink-whiskey']?.handler).toBe('drunk-transition')
+    expect(world.actions?.['drink-whiskey']?.requires?.allHeld).toEqual(['whiskey'])
+    expect(world.actions?.['drink-whiskey']?.drunkTransition).toEqual({
+      destinationRoom: 'drunk-hall',
+      maxMoves: 20,
+      wakeRoom: 'foyer',
+      resetRoom: 'kitchen',
+    })
+  })
+
+  it('loads a markdown-owned encounter phase machine', () => {
+    expect(world.encounters.rat).toMatchObject({
+      id: 'rat',
+      startsIn: 'cellar-stair',
+      initialPhase: 'lurking',
+      onResolved: { setFlags: { ratGone: true } },
+      defaultWrongVerbNarration: 'The rat watches.',
+    })
+    const lurking = world.encounters.rat?.phases.lurking
+    expect(lurking).toBeDefined()
+    expect(lurking?.transitions).toEqual([
+      {
+        verb: 'attack',
+        target: 'rat',
+        chipLabel: 'ATTACK RAT',
+        chipCommand: 'attack rat',
+        narration: 'You stamp. The rat squeals and is gone into the dark.',
+        to: 'resolved',
+      },
+      {
+        verb: 'wait',
+        chipLabel: 'WAIT',
+        narration: 'The rat does not move. Neither do you.',
+        to: 'lurking',
+      },
+    ])
+  })
+
+  it('loads the first migrated encounter batch from markdown', () => {
+    expect(world.encounters['window-guest']).toMatchObject({
+      aliases: ['guest', 'window guest', 'curtains', 'curtain', 'window'],
+      onResolved: { setFlags: { curtainsClosed: true } },
+      onFailed: { retreatTo: 'hallway' },
+    })
+    expect(world.encounters['covered-cage']).toMatchObject({
+      aliases: ['covered cage', 'cage', 'birdcage', 'cloth'],
+      onResolved: { setFlags: { cageUncovered: true } },
+      onFailed: { retreatTo: 'hallway' },
+    })
+    expect(world.encounters['piano-echo']).toMatchObject({
+      aliases: ['piano echo', 'piano', 'note', 'key'],
+      onResolved: { setFlags: { musicSolved: true } },
+      onFailed: { retreatTo: 'hallway' },
+    })
+    expect(world.encounters['window-guest']?.phases['standing-outside']?.transitions[0]?.chipCommand).toBe('close curtains')
+    expect(world.encounters['covered-cage']?.phases.rustling?.transitions[0]?.chipCommand).toBe('uncover cage')
+    expect(world.encounters['piano-echo']?.phases.listening?.transitions[0]?.chipCommand).toBe('play note')
+  })
+
+  it('loads the wait-resolved encounter batch from markdown', () => {
+    expect(world.encounters['breathing-wall']).toMatchObject({
+      aliases: ['breathing wall', 'wall', 'walls', 'breathing'],
+      onResolved: { setFlags: { breathingWallPassed: true } },
+      onFailed: { retreatTo: 'music-room' },
+    })
+    expect(world.encounters['linen-shape']).toMatchObject({
+      aliases: ['linen shape', 'shape', 'sheet', 'sheets', 'linen'],
+      onResolved: { setFlags: { linenShapeEmpty: true } },
+      onFailed: { retreatTo: 'servants-passage' },
+    })
+    expect(world.encounters['stair-sleeper']).toMatchObject({
+      aliases: ['stair sleeper', 'sleeper', 'figure', 'person', 'body'],
+      onResolved: { setFlags: { hallwayShifted: true } },
+      onFailed: { retreatTo: 'parlor' },
+    })
+    expect(world.encounters['breathing-wall']?.phases.audible?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
+    expect(world.encounters['linen-shape']?.phases.hanging?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
+    expect(world.encounters['stair-sleeper']?.phases.seated?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
+  })
+
+  it('loads the item-gated encounter batch from markdown', () => {
+    expect(world.encounters['ivy-figure']).toMatchObject({
+      aliases: ['ivy figure', 'figure', 'ivy', 'vines', 'vine'],
+      onResolved: { setFlags: { conservatoryVinesCut: true } },
+      onFailed: { retreatTo: 'dining-room' },
+    })
+    expect(world.encounters['child-beneath-well']).toMatchObject({
+      aliases: ['child', 'well child', 'child beneath well', 'barefoot child'],
+      onResolved: { setFlags: { childPassedWell: true } },
+      onFailed: { retreatTo: 'well' },
+    })
+    expect(world.encounters['bone-keeper']).toMatchObject({
+      aliases: ['bone keeper', 'keeper', 'hands', 'bones', 'ribs'],
+      onResolved: { setFlags: { burialRingPlaced: true } },
+      onFailed: { retreatTo: 'tunnel' },
+    })
+
+    expect(world.encounters['ivy-figure']?.phases.hidden?.transitions).toEqual([
+      expect.objectContaining({ verb: 'cut', requires: { item: 'pruning-shears' }, chipCommand: 'cut vines' }),
+      expect.objectContaining({ verb: 'use', requires: { item: 'pruning-shears' }, chipCommand: 'use vines with shears' }),
+    ])
+    expect(world.encounters['child-beneath-well']?.phases.climbing?.transitions).toEqual([
+      expect.objectContaining({ verb: 'hold', requires: { item: 'toy-dog' }, setFlags: { woofReturned: true }, chipCommand: 'hold dog' }),
+      expect.objectContaining({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' }),
+    ])
+    expect(world.encounters['bone-keeper']?.phases.arranging?.transitions[0]).toMatchObject({
+      verb: 'drop',
+      target: 'burial-ring',
+      requires: { item: 'burial-ring' },
+      chipCommand: 'leave ring',
+    })
+  })
+
+  it('loads the garden and lower-passage encounter batch from markdown', () => {
+    expect(world.encounters['garden-procession']).toMatchObject({
+      aliases: ['garden procession', 'procession', 'lanterns', 'lantern', 'lights', 'hedge'],
+      onResolved: { setFlags: { gardenQuiet: true } },
+      onFailed: { retreatTo: 'back-door' },
+    })
+    expect(world.encounters.reflection).toMatchObject({
+      aliases: ['reflection', 'water', 'black water', 'face', 'reflected figure'],
+      onResolved: { setFlags: { reflectionObscured: true } },
+      onFailed: { retreatTo: 'ossuary' },
+    })
+    expect(world.encounters['root-movement']).toMatchObject({
+      aliases: ['root movement', 'roots', 'root', 'opening'],
+      onResolved: { setFlags: { rootsListenedTo: true } },
+      onFailed: { retreatTo: 'flooded-passage' },
+    })
+
+    expect(world.encounters['garden-procession']?.phases.passing?.transitions[0]).toMatchObject({
+      verb: 'wait',
+      chipLabel: 'WAIT',
+      to: 'resolved',
+    })
+    expect(world.encounters.reflection?.phases.following?.transitions[0]).toMatchObject({
+      verb: 'use',
+      target: 'reflection',
+      requires: { item: 'damp-sheet' },
+      chipCommand: 'use water with sheet',
+    })
+    expect(world.encounters['root-movement']?.phases.shifting?.transitions[0]).toMatchObject({
+      verb: 'listen',
+      chipCommand: 'listen',
+      to: 'resolved',
+    })
+  })
+
+  it('loads the final encounter batch from markdown', () => {
+    expect(world.encounters['portrait-woman']).toMatchObject({
+      aliases: ['portrait woman', 'woman', 'portrait', 'portraits', 'veil', 'funeral veil'],
+      onResolved: { setFlags: { familyResemblanceSeen: true } },
+      onFailed: { retreatTo: 'root-chamber' },
+    })
+    expect(world.encounters.basilisk).toMatchObject({
+      aliases: ['basilisk', 'creature', 'eye', 'altar', 'coil'],
+      onResolved: { setFlags: { basiliskSpared: true } },
+      onFailed: { retreatTo: 'vault' },
+    })
+    expect(world.encounters['vault-memory']).toMatchObject({
+      aliases: ['vault memory', 'memory', 'bed', 'photograph', 'photo', 'thing', 'buried thing'],
+    })
+    expect(world.encounters['creaking-floorboard']).toMatchObject({
+      aliases: ['creaking floorboard', 'floorboard', 'board', 'creak', 'secret door', 'faceless man', 'man', 'voice'],
+    })
+    expect(world.encounters['distant-steps']).toMatchObject({
+      aliases: ['distant steps', 'steps', 'footsteps', 'hallway'],
+      onResolved: { setFlags: { distantStepsPassed: true } },
+      onFailed: { retreatTo: 'parlor' },
+    })
+    expect(world.encounters['rainwater-basin']).toMatchObject({
+      aliases: ['rainwater basin', 'basin', 'water', 'rainwater', 'reflection'],
+      onResolved: { setFlags: { rainRoomEntered: true, houseAcceptedYou: true } },
+      onFailed: { retreatTo: 'wrong-hallway' },
+    })
+
+    expect(world.encounters['portrait-woman']?.phases.watching?.transitions[0]).toMatchObject({
+      verb: 'examine',
+      chipCommand: 'examine portraits',
+    })
+    expect(world.encounters.basilisk?.phases.sleeping?.transitions).toEqual([
+      expect.objectContaining({ verb: 'pour', requires: { item: 'silver-vial' }, chipCommand: 'pour vial on basilisk' }),
+      expect.objectContaining({ verb: 'use', requires: { item: 'silver-vial' }, chipCommand: 'use basilisk with vial' }),
+    ])
+    expect(world.encounters['vault-memory']?.phases.buried?.transitions).toEqual([
+      expect.objectContaining({ verb: 'read', requires: { item: 'family-register' }, setFlags: { nameSpoken: true } }),
+      expect.objectContaining({ verb: 'take', setFlags: { tookPhotograph: true } }),
+      expect.objectContaining({ verb: 'attack', setFlags: { disturbedVault: true } }),
+    ])
+    expect(world.encounters['creaking-floorboard']?.phases.creaking?.transitions).toEqual([
+      expect.objectContaining({ verb: 'listen', setFlags: { drunkSecretFound: true, facelessManMet: true, houseDebtNamed: true } }),
+      expect.objectContaining({ verb: 'open', setFlags: { drunkSecretFound: true, facelessManMet: true, houseDebtNamed: true } }),
+    ])
+    expect(world.encounters['distant-steps']?.phases.approaching?.transitions[0]).toMatchObject({
+      verb: 'wait',
+      to: 'resolved',
+    })
+    expect(world.encounters['rainwater-basin']?.phases.reflecting?.transitions).toEqual([
+      expect.objectContaining({ verb: 'look', chipCommand: 'look basin' }),
+      expect.objectContaining({ verb: 'examine', chipCommand: 'examine basin' }),
+    ])
+  })
+
+  it('rejects duplicate handler-backed action owners', () => {
+    expect(() => build({
+      actions: {
+        first: {
+          id: 'first',
+          verbs: ['drink'],
+          handler: 'drunk-transition',
+          requires: { allHeld: ['letter'] },
+          drunkTransition: {
+            destinationRoom: 'foyer',
+            maxMoves: 1,
+            wakeRoom: 'foyer',
+            resetRoom: 'foyer',
+          },
+          messages: {
+            success: 'ok',
+            secretFoundPassOut: 'secret',
+            tooManyMovesPassOut: 'moves',
+            reset: 'reset',
+          },
+        },
+        second: {
+          id: 'second',
+          verbs: ['drink'],
+          handler: 'drunk-transition',
+          requires: { allHeld: ['letter'] },
+          drunkTransition: {
+            destinationRoom: 'foyer',
+            maxMoves: 1,
+            wakeRoom: 'foyer',
+            resetRoom: 'foyer',
+          },
+          messages: {
+            success: 'ok',
+            secretFoundPassOut: 'secret',
+            tooManyMovesPassOut: 'moves',
+            reset: 'reset',
+          },
+        },
+      },
+    })).toThrow(/handler "drunk-transition" is already used by actions\/first\.md/)
+  })
+
+  it('reports the action field that references an unknown item', () => {
+    expect(() => build({
+      actions: {
+        burn: {
+          id: 'burn',
+          verbs: ['use'],
+          requires: { allVisibleOrHeld: ['letter', 'missing-match'] },
+          messages: { success: 'ok' },
+        },
+      },
+    })).toThrow(/actions\/burn\.md: requires\.allVisibleOrHeld references unknown item "missing-match"/)
+  })
+
+  it('reports the drunk transition field that references an unknown room', () => {
+    expect(() => build({
+      actions: {
+        drink: {
+          id: 'drink',
+          verbs: ['drink'],
+          handler: 'drunk-transition',
+          requires: { allHeld: ['letter'] },
+          drunkTransition: {
+            destinationRoom: 'missing-room',
+            maxMoves: 1,
+            wakeRoom: 'foyer',
+            resetRoom: 'foyer',
+          },
+          messages: {
+            success: 'ok',
+            secretFoundPassOut: 'secret',
+            tooManyMovesPassOut: 'moves',
+            reset: 'reset',
+          },
+        },
+      },
+    })).toThrow(/actions\/drink\.md: drunkTransition\.destinationRoom references unknown room "missing-room"/)
+  })
+
+  it('ending priority references loaded endings', () => {
+    expect(world.endingPriority).toEqual(world.game?.endingPriority)
+    for (const endingId of world.endingPriority ?? []) {
+      expect(world.endings[endingId], endingId).toBeDefined()
+    }
+  })
+
  it('endings have non-empty narration where the original did', () => {
-    expect(world.endings.true.narration.length).toBeGreaterThan(0)
+    expect(world.endings['true']?.narration.length).toBeGreaterThan(0)
  })
 })
@@ -1,389 +0,0 @@
-import type { EncounterDef } from './types'
-import { narration } from './loader'
-
-export const encounters: Record<string, EncounterDef> = {
-  rat: {
-    id: 'rat',
-    startsIn: 'cellar-stair',
-    initialPhase: 'lurking',
-    phases: {
-      lurking: {
-        description: narration('rat', 'lurking'),
-        transitions: [
-          {
-            verb: 'attack',
-            target: 'rat',
-            chipLabel: 'ATTACK RAT',
-            chipCommand: 'attack rat',
-            narration: narration('rat', 'attack-rat-resolved'),
-            to: 'resolved',
-          },
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('rat', 'wait-stays'),
-            to: 'lurking',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { ratGone: true } },
-    defaultWrongVerbNarration: 'The rat watches.',
-  },
-  'window-guest': {
-    id: 'window-guest',
-    aliases: ['guest', 'window guest', 'curtains', 'curtain', 'window'],
-    startsIn: 'dining-room',
-    initialPhase: 'standing-outside',
-    phases: {
-      'standing-outside': {
-        description: narration('window-guest', 'standing-outside'),
-        transitions: [
-          {
-            verb: 'close',
-            target: 'window-guest',
-            chipLabel: 'CLOSE CURTAINS',
-            chipCommand: 'close curtains',
-            narration: narration('window-guest', 'close-window-guest-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { curtainsClosed: true } },
-    onFailed: { narration: narration('window-guest', 'failed'), retreatTo: 'hallway' },
-    defaultWrongVerbNarration: narration('window-guest', 'wrong-verb'),
-  },
-  'ivy-figure': {
-    id: 'ivy-figure',
-    aliases: ['ivy figure', 'figure', 'ivy', 'vines', 'vine'],
-    startsIn: 'conservatory',
-    initialPhase: 'hidden',
-    phases: {
-      hidden: {
-        description: narration('ivy-figure', 'hidden'),
-        transitions: [
-          {
-            verb: 'cut',
-            target: 'ivy-figure',
-            chipLabel: 'CUT VINES',
-            chipCommand: 'cut vines',
-            requires: { item: 'pruning-shears' },
-            narration: narration('ivy-figure', 'cut-ivy-figure-resolved'),
-            to: 'resolved',
-          },
-          {
-            verb: 'use',
-            target: 'ivy-figure',
-            chipLabel: 'USE SHEARS',
-            chipCommand: 'use vines with shears',
-            requires: { item: 'pruning-shears' },
-            narration: narration('ivy-figure', 'cut-ivy-figure-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { conservatoryVinesCut: true } },
-    onFailed: { narration: narration('ivy-figure', 'failed'), retreatTo: 'dining-room' },
-    defaultWrongVerbNarration: narration('ivy-figure', 'wrong-verb'),
-  },
-  'covered-cage': {
-    id: 'covered-cage',
-    aliases: ['covered cage', 'cage', 'birdcage', 'cloth'],
-    startsIn: 'smoking-room',
-    initialPhase: 'rustling',
-    phases: {
-      rustling: {
-        description: narration('covered-cage', 'rustling'),
-        transitions: [
-          {
-            verb: 'open',
-            target: 'covered-cage',
-            chipLabel: 'UNCOVER CAGE',
-            chipCommand: 'uncover cage',
-            narration: narration('covered-cage', 'open-covered-cage-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { cageUncovered: true } },
-    onFailed: { narration: narration('covered-cage', 'failed'), retreatTo: 'hallway' },
-    defaultWrongVerbNarration: narration('covered-cage', 'wrong-verb'),
-  },
-  'piano-echo': {
-    id: 'piano-echo',
-    aliases: ['piano echo', 'piano', 'note', 'key'],
-    startsIn: 'music-room',
-    initialPhase: 'listening',
-    phases: {
-      listening: {
-        description: narration('piano-echo', 'listening'),
-        transitions: [
-          {
-            verb: 'play',
-            target: 'piano-echo',
-            chipLabel: 'PLAY NOTE',
-            chipCommand: 'play note',
-            narration: narration('piano-echo', 'play-piano-echo-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { musicSolved: true } },
-    onFailed: { narration: narration('piano-echo', 'failed'), retreatTo: 'hallway' },
-    defaultWrongVerbNarration: narration('piano-echo', 'wrong-verb'),
-  },
-  'breathing-wall': {
-    id: 'breathing-wall',
-    aliases: ['breathing wall', 'wall', 'walls', 'breathing'],
-    startsIn: 'servants-passage',
-    initialPhase: 'audible',
-    phases: {
-      audible: {
-        description: narration('breathing-wall', 'audible'),
-        transitions: [
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('breathing-wall', 'wait-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { breathingWallPassed: true } },
-    onFailed: { narration: narration('breathing-wall', 'failed'), retreatTo: 'music-room' },
-    defaultWrongVerbNarration: narration('breathing-wall', 'wrong-verb'),
-  },
-  'linen-shape': {
-    id: 'linen-shape',
-    aliases: ['linen shape', 'shape', 'sheet', 'sheets', 'linen'],
-    startsIn: 'laundry',
-    initialPhase: 'hanging',
-    phases: {
-      hanging: {
-        description: narration('linen-shape', 'hanging'),
-        transitions: [
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('linen-shape', 'wait-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { linenShapeEmpty: true } },
-    onFailed: { narration: narration('linen-shape', 'failed'), retreatTo: 'servants-passage' },
-    defaultWrongVerbNarration: narration('linen-shape', 'wrong-verb'),
-  },
-  'stair-sleeper': {
-    id: 'stair-sleeper',
-    aliases: ['stair sleeper', 'sleeper', 'figure', 'person', 'body'],
-    startsIn: 'stair-up',
-    initialPhase: 'seated',
-    phases: {
-      seated: {
-        description: narration('stair-sleeper', 'seated'),
-        transitions: [
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('stair-sleeper', 'wait-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { hallwayShifted: true } },
-    onFailed: { narration: narration('stair-sleeper', 'failed'), retreatTo: 'parlor' },
-    defaultWrongVerbNarration: narration('stair-sleeper', 'wrong-verb'),
-  },
-  'garden-procession': {
-    id: 'garden-procession',
-    aliases: ['garden procession', 'procession', 'lanterns', 'lantern', 'lights', 'hedge'],
-    startsIn: 'garden',
-    initialPhase: 'passing',
-    phases: {
-      passing: {
-        description: narration('garden-procession', 'passing'),
-        transitions: [
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('garden-procession', 'wait-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { gardenQuiet: true } },
-    onFailed: { narration: narration('garden-procession', 'failed'), retreatTo: 'back-door' },
-    defaultWrongVerbNarration: narration('garden-procession', 'wrong-verb'),
-  },
-  'child-beneath-well': {
-    id: 'child-beneath-well',
-    aliases: ['child', 'well child', 'child beneath well', 'barefoot child'],
-    startsIn: 'well-shaft',
-    initialPhase: 'climbing',
-    phases: {
-      climbing: {
-        description: narration('child-beneath-well', 'climbing'),
-        transitions: [
-          {
-            verb: 'hold',
-            target: 'toy-dog',
-            chipLabel: 'SHOW DOG',
-            chipCommand: 'hold dog',
-            requires: { item: 'toy-dog' },
-            narration: narration('child-beneath-well', 'hold-toy-dog-resolved'),
-            to: 'resolved',
-          },
-          {
-            verb: 'wait',
-            chipLabel: 'WAIT',
-            narration: narration('child-beneath-well', 'wait-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { childPassedWell: true } },
-    onFailed: { narration: narration('child-beneath-well', 'failed'), retreatTo: 'well' },
-    defaultWrongVerbNarration: narration('child-beneath-well', 'wrong-verb'),
-  },
-  'bone-keeper': {
-    id: 'bone-keeper',
-    aliases: ['bone keeper', 'keeper', 'hands', 'bones', 'ribs'],
-    startsIn: 'ossuary',
-    initialPhase: 'arranging',
-    phases: {
-      arranging: {
-        description: narration('bone-keeper', 'arranging'),
-        transitions: [
-          {
-            verb: 'drop',
-            target: 'burial-ring',
-            chipLabel: 'LEAVE RING',
-            chipCommand: 'leave ring',
-            requires: { item: 'burial-ring' },
-            narration: narration('bone-keeper', 'leave-burial-ring-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { burialRingPlaced: true } },
-    onFailed: { narration: narration('bone-keeper', 'failed'), retreatTo: 'tunnel' },
-    defaultWrongVerbNarration: narration('bone-keeper', 'wrong-verb'),
-  },
-  reflection: {
-    id: 'reflection',
-    aliases: ['reflection', 'water', 'black water', 'face', 'reflected figure'],
-    startsIn: 'flooded-passage',
-    initialPhase: 'following',
-    phases: {
-      following: {
-        description: narration('reflection', 'following'),
-        transitions: [
-          {
-            verb: 'use',
-            target: 'reflection',
-            chipLabel: 'USE SHEET',
-            chipCommand: 'use water with sheet',
-            requires: { item: 'damp-sheet' },
-            narration: narration('reflection', 'obscure-water-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { reflectionObscured: true } },
-    onFailed: { narration: narration('reflection', 'failed'), retreatTo: 'ossuary' },
-    defaultWrongVerbNarration: narration('reflection', 'wrong-verb'),
-  },
-  'root-movement': {
-    id: 'root-movement',
-    aliases: ['root movement', 'roots', 'root', 'opening'],
-    startsIn: 'root-chamber',
-    initialPhase: 'shifting',
-    phases: {
-      shifting: {
-        description: narration('root-movement', 'shifting'),
-        transitions: [
-          {
-            verb: 'listen',
-            chipLabel: 'LISTEN',
-            chipCommand: 'listen',
-            narration: narration('root-movement', 'listen-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { rootsListenedTo: true } },
-    onFailed: { narration: narration('root-movement', 'failed'), retreatTo: 'flooded-passage' },
-    defaultWrongVerbNarration: narration('root-movement', 'wrong-verb'),
-  },
-  'portrait-woman': {
-    id: 'portrait-woman',
-    aliases: ['portrait woman', 'woman', 'portrait', 'portraits', 'veil', 'funeral veil'],
-    startsIn: 'burial-gallery',
-    initialPhase: 'watching',
-    phases: {
-      watching: {
-        description: narration('portrait-woman', 'watching'),
-        transitions: [
-          {
-            verb: 'examine',
-            target: 'portrait-woman',
-            chipLabel: 'EXAMINE PORTRAITS',
-            chipCommand: 'examine portraits',
-            narration: narration('portrait-woman', 'examine-portraits-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { familyResemblanceSeen: true } },
-    onFailed: { narration: narration('portrait-woman', 'failed'), retreatTo: 'root-chamber' },
-    defaultWrongVerbNarration: narration('portrait-woman', 'wrong-verb'),
-  },
-  basilisk: {
-    id: 'basilisk',
-    aliases: ['basilisk', 'creature', 'eye', 'altar', 'coil'],
-    startsIn: 'chapel',
-    initialPhase: 'sleeping',
-    phases: {
-      sleeping: {
-        description: narration('basilisk', 'sleeping'),
-        transitions: [
-          {
-            verb: 'pour',
-            target: 'silver-vial',
-            chipLabel: 'POUR VIAL',
-            chipCommand: 'pour vial on basilisk',
-            requires: { item: 'silver-vial' },
-            narration: narration('basilisk', 'pour-vial-resolved'),
-            to: 'resolved',
-          },
-          {
-            verb: 'use',
-            target: 'basilisk',
-            chipLabel: 'USE VIAL',
-            chipCommand: 'use basilisk with vial',
-            requires: { item: 'silver-vial' },
-            narration: narration('basilisk', 'pour-vial-resolved'),
-            to: 'resolved',
-          },
-        ],
-      },
-    },
-    onResolved: { setFlags: { basiliskSpared: true } },
-    onFailed: { narration: narration('basilisk', 'failed'), retreatTo: 'vault' },
-    defaultWrongVerbNarration: narration('basilisk', 'wrong-verb'),
-  },
-}
@@ -2,6 +2,34 @@
 id: basilisk
 startsIn: "[[chapel]]"
 initialPhase: sleeping
+aliases: [basilisk, creature, eye, altar, coil]
+onResolved:
+  setFlags:
+    basiliskSpared: true
+onFailed:
+  narration: failed
+  retreatTo: "[[vault]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  sleeping:
+    description: sleeping
+    transitions:
+      - verb: pour
+        target: silver-vial
+        chipLabel: POUR VIAL
+        chipCommand: pour vial on basilisk
+        requires:
+          item: "[[silver-vial]]"
+        narration: pour-vial-resolved
+        to: resolved
+      - verb: use
+        target: basilisk
+        chipLabel: USE VIAL
+        chipCommand: use basilisk with vial
+        requires:
+          item: "[[silver-vial]]"
+        narration: pour-vial-resolved
+        to: resolved
 ---

 ## sleeping
@@ -2,6 +2,26 @@
 id: bone-keeper
 startsIn: "[[ossuary]]"
 initialPhase: arranging
+aliases: [bone keeper, keeper, hands, bones, ribs]
+onResolved:
+  setFlags:
+    burialRingPlaced: true
+onFailed:
+  narration: failed
+  retreatTo: "[[tunnel]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  arranging:
+    description: arranging
+    transitions:
+      - verb: drop
+        target: "[[burial-ring]]"
+        chipLabel: LEAVE RING
+        chipCommand: leave ring
+        requires:
+          item: "[[burial-ring]]"
+        narration: leave-burial-ring-resolved
+        to: resolved
 ---

 ## arranging
@@ -2,6 +2,22 @@
 id: breathing-wall
 startsIn: "[[servants-passage]]"
 initialPhase: audible
+aliases: [breathing wall, wall, walls, breathing]
+onResolved:
+  setFlags:
+    breathingWallPassed: true
+onFailed:
+  narration: failed
+  retreatTo: "[[music-room]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  audible:
+    description: audible
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
 ---

 ## audible
@@ -2,6 +2,32 @@
 id: child-beneath-well
 startsIn: "[[well-shaft]]"
 initialPhase: climbing
+aliases: [child, well child, child beneath well, barefoot child]
+onResolved:
+  setFlags:
+    childPassedWell: true
+onFailed:
+  narration: failed
+  retreatTo: "[[well]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  climbing:
+    description: climbing
+    transitions:
+      - verb: hold
+        target: "[[toy-dog]]"
+        chipLabel: SHOW DOG
+        chipCommand: hold dog
+        requires:
+          item: "[[toy-dog]]"
+        narration: hold-toy-dog-resolved
+        setFlags:
+          woofReturned: true
+        to: resolved
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
 ---

 ## climbing
@@ -2,6 +2,24 @@
 id: covered-cage
 startsIn: "[[smoking-room]]"
 initialPhase: rustling
+aliases: [covered cage, cage, birdcage, cloth]
+onResolved:
+  setFlags:
+    cageUncovered: true
+onFailed:
+  narration: failed
+  retreatTo: "[[hallway]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  rustling:
+    description: rustling
+    transitions:
+      - verb: open
+        target: covered-cage
+        chipLabel: UNCOVER CAGE
+        chipCommand: uncover cage
+        narration: open-covered-cage-resolved
+        to: resolved
 ---

 ## rustling
@@ -0,0 +1,45 @@
+---
+id: creaking-floorboard
+startsIn: "[[drunk-landing]]"
+initialPhase: creaking
+aliases: [creaking floorboard, floorboard, board, creak, secret door, faceless man, man, voice]
+defaultWrongVerbNarration: wrong-verb
+phases:
+  creaking:
+    description: creaking
+    transitions:
+      - verb: listen
+        chipLabel: LISTEN
+        chipCommand: listen
+        narration: listen-resolved
+        setFlags:
+          drunkSecretFound: true
+          facelessManMet: true
+          houseDebtNamed: true
+        to: resolved
+      - verb: open
+        target: creaking-floorboard
+        chipLabel: OPEN BOARD
+        chipCommand: open floorboard
+        narration: listen-resolved
+        setFlags:
+          drunkSecretFound: true
+          facelessManMet: true
+          houseDebtNamed: true
+        to: resolved
+---
+
+## creaking
+One floorboard creaks after you have stopped moving.
+
+It creaks again, softer, from under the wrong foot.
+
+## listen-resolved
+You listen.
+
+The board lifts by itself. Beneath it is a narrow door, and behind the door a man without a face sits with his hands folded.
+
+"Halfstreet keeps what is owed," he whispers. "It does not know the difference between a debt and a child."
+
+## wrong-verb
+The floorboard waits until you breathe, then creaks beneath that too.
@@ -0,0 +1,37 @@
+---
+id: distant-steps
+startsIn: "[[wrong-hallway]]"
+initialPhase: approaching
+aliases: [distant steps, steps, footsteps, hallway]
+onResolved:
+  setFlags:
+    distantStepsPassed: true
+onFailed:
+  narration: failed
+  retreatTo: "[[parlor]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  approaching:
+    description: approaching
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
+---
+
+## approaching
+The footsteps come closer without growing louder.
+
+They stop whenever you move.
+
+## wait-resolved
+You stand still.
+
+The steps pass through you with the cold, careful pressure of someone carrying a tray through a dark room. When they are gone, the hallway is shorter by one door.
+
+## wrong-verb
+The hallway lengthens. The footsteps begin again from farther away.
+
+## failed
+You turn back too quickly and find the parlor waiting with all its chairs facing you.
@@ -2,6 +2,22 @@
 id: garden-procession
 startsIn: "[[garden]]"
 initialPhase: passing
+aliases: [garden procession, procession, lanterns, lantern, lights, hedge]
+onResolved:
+  setFlags:
+    gardenQuiet: true
+onFailed:
+  narration: failed
+  retreatTo: "[[back-door]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  passing:
+    description: passing
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
 ---

 ## passing
@@ -2,6 +2,34 @@
 id: ivy-figure
 startsIn: "[[conservatory]]"
 initialPhase: hidden
+aliases: [ivy figure, figure, ivy, vines, vine]
+onResolved:
+  setFlags:
+    conservatoryVinesCut: true
+onFailed:
+  narration: failed
+  retreatTo: "[[dining-room]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  hidden:
+    description: hidden
+    transitions:
+      - verb: cut
+        target: ivy-figure
+        chipLabel: CUT VINES
+        chipCommand: cut vines
+        requires:
+          item: "[[pruning-shears]]"
+        narration: cut-ivy-figure-resolved
+        to: resolved
+      - verb: use
+        target: ivy-figure
+        chipLabel: USE SHEARS
+        chipCommand: use vines with shears
+        requires:
+          item: "[[pruning-shears]]"
+        narration: cut-ivy-figure-resolved
+        to: resolved
 ---

 ## hidden
@@ -2,6 +2,22 @@
 id: linen-shape
 startsIn: "[[laundry]]"
 initialPhase: hanging
+aliases: [linen shape, shape, sheet, sheets, linen]
+onResolved:
+  setFlags:
+    linenShapeEmpty: true
+onFailed:
+  narration: failed
+  retreatTo: "[[servants-passage]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  hanging:
+    description: hanging
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
 ---

 ## hanging
@@ -2,6 +2,24 @@
 id: piano-echo
 startsIn: "[[music-room]]"
 initialPhase: listening
+aliases: [piano echo, piano, note, key]
+onResolved:
+  setFlags:
+    musicSolved: true
+onFailed:
+  narration: failed
+  retreatTo: "[[hallway]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  listening:
+    description: listening
+    transitions:
+      - verb: play
+        target: piano-echo
+        chipLabel: PLAY NOTE
+        chipCommand: play note
+        narration: play-piano-echo-resolved
+        to: resolved
 ---

 ## listening
@@ -2,6 +2,24 @@
 id: portrait-woman
 startsIn: "[[burial-gallery]]"
 initialPhase: watching
+aliases: [portrait woman, woman, portrait, portraits, veil, funeral veil]
+onResolved:
+  setFlags:
+    familyResemblanceSeen: true
+onFailed:
+  narration: failed
+  retreatTo: "[[root-chamber]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  watching:
+    description: watching
+    transitions:
+      - verb: examine
+        target: portrait-woman
+        chipLabel: EXAMINE PORTRAITS
+        chipCommand: examine portraits
+        narration: examine-portraits-resolved
+        to: resolved
 ---

 ## watching
@@ -0,0 +1,46 @@
+---
+id: rainwater-basin
+startsIn: "[[rain-room]]"
+initialPhase: reflecting
+aliases: [rainwater basin, basin, water, rainwater, reflection]
+onResolved:
+  setFlags:
+    rainRoomEntered: true
+    houseAcceptedYou: true
+onFailed:
+  narration: failed
+  retreatTo: "[[wrong-hallway]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  reflecting:
+    description: reflecting
+    transitions:
+      - verb: look
+        target: rainwater-basin
+        chipLabel: LOOK BASIN
+        chipCommand: look basin
+        narration: look-resolved
+        to: resolved
+      - verb: examine
+        target: rainwater-basin
+        chipLabel: EXAMINE BASIN
+        chipCommand: examine basin
+        narration: look-resolved
+        to: resolved
+---
+
+## reflecting
+The basin shows no ceiling. It shows a hallway instead, and in that hallway a lamp going out.
+
+## look-resolved
+You look into the rainwater.
+
+Rooms gather there one beneath another: nursery, chapel, vault, gate. For a moment they fit together correctly. Then your reflection enters them from the wrong side, and every door in the image opens inward.
+
+When you look up, the room has learned you.
+
+## wrong-verb
+Rain touches your hands, though you are not beneath it.
+
+## failed
+The rain rises without filling the basin. You step back into the wrong hallway before it reaches your mouth.
@@ -2,8 +2,25 @@
 id: rat
 startsIn: "[[cellar-stair]]"
 initialPhase: lurking
+onResolved:
+  setFlags:
+    ratGone: true
+defaultWrongVerbNarration: wrong-verb
+phases:
+  lurking:
+    description: lurking
+    transitions:
+      - verb: attack
+        target: rat
+        chipLabel: ATTACK RAT
+        chipCommand: attack rat
+        narration: attack-rat-resolved
+        to: resolved
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-stays
+        to: lurking
 ---
-![[Pasted image 20260509213136.png]]
 ## lurking
 A heavy rat watches you from the third step. Its eyes catch the light.

@@ -12,3 +29,6 @@ You stamp. The rat squeals and is gone into the dark.

 ## wait-stays
 The rat does not move. Neither do you.
+
+## wrong-verb
+The rat watches.
@@ -2,6 +2,26 @@
 id: reflection
 startsIn: "[[flooded-passage]]"
 initialPhase: following
+aliases: [reflection, water, black water, face, reflected figure]
+onResolved:
+  setFlags:
+    reflectionObscured: true
+onFailed:
+  narration: failed
+  retreatTo: "[[ossuary]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  following:
+    description: following
+    transitions:
+      - verb: use
+        target: reflection
+        chipLabel: USE SHEET
+        chipCommand: use water with sheet
+        requires:
+          item: "[[damp-sheet]]"
+        narration: obscure-water-resolved
+        to: resolved
 ---

 ## following
@@ -2,6 +2,23 @@
 id: root-movement
 startsIn: "[[root-chamber]]"
 initialPhase: shifting
+aliases: [root movement, roots, root, opening]
+onResolved:
+  setFlags:
+    rootsListenedTo: true
+onFailed:
+  narration: failed
+  retreatTo: "[[flooded-passage]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  shifting:
+    description: shifting
+    transitions:
+      - verb: listen
+        chipLabel: LISTEN
+        chipCommand: listen
+        narration: listen-resolved
+        to: resolved
 ---

 ## shifting
@@ -2,6 +2,22 @@
 id: stair-sleeper
 startsIn: "[[stair-up]]"
 initialPhase: seated
+aliases: [stair sleeper, sleeper, figure, person, body]
+onResolved:
+  setFlags:
+    hallwayShifted: true
+onFailed:
+  narration: failed
+  retreatTo: "[[parlor]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  seated:
+    description: seated
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-resolved
+        to: resolved
 ---

 ## seated
@@ -0,0 +1,60 @@
+---
+id: vault-memory
+startsIn: "[[vault]]"
+initialPhase: buried
+aliases: [vault memory, memory, bed, photograph, photo, thing, buried thing]
+defaultWrongVerbNarration: wrong-verb
+phases:
+  buried:
+    description: buried
+    transitions:
+      - verb: read
+        target: family-register
+        chipLabel: READ REGISTER
+        chipCommand: read register
+        requires:
+          item: "[[family-register]]"
+        narration: read-register-resolved
+        setFlags:
+          nameSpoken: true
+        to: resolved
+      - verb: take
+        target: vault-memory
+        chipLabel: TAKE PHOTO
+        chipCommand: take photograph
+        narration: take-photograph-resolved
+        setFlags:
+          tookPhotograph: true
+        to: resolved
+      - verb: attack
+        target: vault-memory
+        chipLabel: ATTACK BED
+        chipCommand: attack bed
+        narration: attack-bed-resolved
+        setFlags:
+          disturbedVault: true
+        to: resolved
+---
+
+## buried
+The bed waits in the center of the vault. The photograph lies face down on the coverlet.
+
+The family register feels heavier here, as if all its missing pages have returned at once.
+
+## read-register-resolved
+You read the name from the register.
+
+The letters are difficult only until you say them. Then they seem to have been waiting in your mouth since the gate.
+
+## take-photograph-resolved
+You take the photograph.
+
+It is dry and light and terribly easy to lift.
+
+## attack-bed-resolved
+You strike the little bed.
+
+The sound is small. The house hears it anyway.
+
+## wrong-verb
+The photograph remains face down. The bedclothes do not stir.
@@ -2,6 +2,24 @@
 id: window-guest
 startsIn: "[[dining-room]]"
 initialPhase: standing-outside
+aliases: [guest, window guest, curtains, curtain, window]
+onResolved:
+  setFlags:
+    curtainsClosed: true
+onFailed:
+  narration: failed
+  retreatTo: "[[hallway]]"
+defaultWrongVerbNarration: wrong-verb
+phases:
+  standing-outside:
+    description: standing-outside
+    transitions:
+      - verb: close
+        target: window-guest
+        chipLabel: CLOSE CURTAINS
+        chipCommand: close curtains
+        narration: close-window-guest-resolved
+        to: resolved
 ---

 ## standing-outside
@@ -1,6 +1,13 @@
 ---
 id: bad
 whenFlags:
-  _never: true
+  tookPhotograph: true
 ---

+You take the photograph.
+
+The child in it is you.
+
+Behind you, on the stairs, someone has come up to meet you.
+
+You do not go down again.
@@ -0,0 +1,17 @@
+---
+id: mercy
+whenFlags:
+  nameSpoken: true
+  woofReturned: true
+  basiliskSpared: true
+  burialRingPlaced: true
+  familyResemblanceSeen: true
+---
+
+You remain in the vault until the lamp goes out.
+
+The house is quiet.
+
+Somewhere above, floorboards settle one final time.
+
+By morning, Halfstreet contains one fewer restless thing.
@@ -0,0 +1,15 @@
+---
+id: replacement
+whenFlags:
+  houseAcceptedYou: true
+  rainRoomEntered: true
+  hallwayShifted: true
+---
+
+You open the front door.
+
+Someone is standing at the gate outside.
+
+They look tired. Rain-darkened. Lost.
+
+After a moment, you understand they have arrived for you.
@@ -1,7 +1,18 @@
 ---
 id: true
 whenFlags:
-  ratGone: true
+  nameSpoken: true
+  basiliskSpared: true
+  burialRingPlaced: true
+  familyResemblanceSeen: true
 ---

-You stand at the top of the stair. The thing below has settled. The door behind you opens, and outside, finally, is morning.
+You stand in the vault. What is buried at Halfstreet is buried because it was loved, and grieved, and finally let go.
+
+You set the lamp beside it.
+
+You speak the name aloud.
+
+The house settles around you like a long exhalation.
+
+Outside, the road exists again.
@@ -1,6 +1,15 @@
 ---
 id: wrong
 whenFlags:
-  _never: true
+  disturbedVault: true
 ---

+You disturb what should have remained untouched.
+
+The house rearranges itself around your leaving.
+
+Corridors repeat.
+
+Doors return you to themselves.
+
+The hallway grows longer.
@@ -0,0 +1,47 @@
+---
+id: halfstreet
+title: Halfstreet
+description: A gothic mystery.
+startingRoom: "[[outside-gate]]"
+startingInventory:
+  - "[[letter]]"
+  - "[[matches]]"
+  - "[[broken-cigarette]]"
+endingPriority:
+  - mercy
+  - "true"
+  - replacement
+  - bad
+  - wrong
+transcriptCap: 200
+---
+
+## opening-art
+ _   _       _  __     ____  _                 _
+| | | | __ _| |/ _|   / ___|| |_ _ __ ___  ___| |_
+| |_| |/ _` | | |_    \___ \| __| '__/ _ \/ _ \ __|
+|  _  | (_| | |  _|    ___) | |_| | |  __/  __/ |_
+|_| |_|\__,_|_|_|     |____/ \__|_|  \___|\___|\__|
+
+## help
+You arrive at the address, but you do not remember what has happened. The road behind you is gone...
+
+This is a text adventure. Type short commands to act in the house.
+
+Common commands:
+look                    describe the room again
+n, s, e, w, u, d        move by direction
+take lamp               pick something up
+examine letter          inspect something nearby or held
+read letter             read a readable object
+inventory               see what you carry
+light lamp with matches use one thing with another
+wait                    let the room continue
+undo                    step back once
+restart                 begin again
+theme                   change the terminal colors
+
+Most commands are verb first, then the thing: examine gate, take lamp, use key on door.
+
+## ended
+The story has ended. Type `restart` or `undo`.
@@ -1,15 +1,37 @@
-import type { World, Room, Item } from './types'
+import type { World, Room, Item, GameManifest, EncounterDef } from './types'
 import {
+  parseAction,
+  parseGame,
+  parseLightMechanic,
+  parseMessages,
+  parseParser,
+  parseUi,
+  parseResolveMechanic,
  parseRoom,
  parseItem,
  parseEnding,
  parseEncounterNarration,
+  type ParsedEncounterNarration,
 } from './loader'
-// Importing loader (above) triggers auto-registration of encounter narrations.
-// ESM evaluates dependencies first, so by the time encounters.ts is evaluated below,
-// narration() can resolve all keys.
-import { encounters } from './encounters'

+const gameFiles = import.meta.glob<string>('./game.md', {
+  eager: true, query: '?raw', import: 'default',
+})
+const parserFiles = import.meta.glob<string>('./parser.md', {
+  eager: true, query: '?raw', import: 'default',
+})
+const uiFiles = import.meta.glob<string>('./ui.md', {
+  eager: true, query: '?raw', import: 'default',
+})
+const messageFiles = import.meta.glob<string>('./messages.md', {
+  eager: true, query: '?raw', import: 'default',
+})
+const mechanicFiles = import.meta.glob<string>('./mechanics/*.md', {
+  eager: true, query: '?raw', import: 'default',
+})
+const actionFiles = import.meta.glob<string>('./actions/*.md', {
+  eager: true, query: '?raw', import: 'default',
+})
 const roomFiles = import.meta.glob<string>('./rooms/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
@@ -23,11 +45,48 @@ const encounterFiles = import.meta.glob<string>('./encounters/*.md', {
  eager: true, query: '?raw', import: 'default',
 })

-// Re-parse encounter docs here so we can validate startsIn / initialPhase against encounters.ts.
-// (The loader already auto-registered narrations from these same files at module init.)
 const encounterDocs = Object.entries(encounterFiles).map(([path, raw]) =>
  parseEncounterNarration(raw, path),
 )
+const markdownEncounters: Record<string, EncounterDef> = {}
+for (const doc of encounterDocs) {
+  if (!doc.encounter) {
+    throw new Error(`encounters/${doc.id}.md is missing phases frontmatter`)
+  }
+  if (markdownEncounters[doc.id]) throw new Error(`encounters/${doc.id}.md: duplicate markdown encounter id "${doc.id}"`)
+  markdownEncounters[doc.id] = doc.encounter
+}
+const encounters: Record<string, EncounterDef> = markdownEncounters
+
+const gameEntry = Object.entries(gameFiles)[0]
+if (!gameEntry) {
+  throw new Error('world/game.md is missing')
+}
+const game = parseGame(gameEntry[1], gameEntry[0])
+const parserEntry = Object.entries(parserFiles)[0]
+if (!parserEntry) {
+  throw new Error('world/parser.md is missing')
+}
+const parser = parseParser(parserEntry[1], parserEntry[0])
+const uiEntry = Object.entries(uiFiles)[0]
+const ui = uiEntry ? parseUi(uiEntry[1], uiEntry[0]) : undefined
+const messageEntry = Object.entries(messageFiles)[0]
+const messages = messageEntry ? parseMessages(messageEntry[1], messageEntry[0]) : undefined
+const mechanics: World['mechanics'] = {}
+for (const [path, raw] of Object.entries(mechanicFiles)) {
+  if (path.endsWith('/light.md')) {
+    mechanics.light = parseLightMechanic(raw, path)
+  } else if (path.endsWith('/resolve.md')) {
+    mechanics.resolve = parseResolveMechanic(raw, path)
+  }
+}
+
+const actions: NonNullable<World['actions']> = {}
+for (const [path, raw] of Object.entries(actionFiles)) {
+  const action = parseAction(raw, path)
+  if (actions[action.id]) throw new Error(`${path}: duplicate action id "${action.id}"`)
+  actions[action.id] = action
+}

 // Build rooms map.
 const rooms: Record<string, Room> = {}
@@ -46,37 +105,65 @@ for (const [path, raw] of Object.entries(itemFiles)) {
 }

 // Build endings.
-const endings: World['endings'] = {
-  true: { whenFlags: {}, narration: '' },
-  wrong: { whenFlags: {}, narration: '' },
-  bad: { whenFlags: {}, narration: '' },
-}
+const endings: World['endings'] = {}
 const seenEndings = new Set<string>()
 for (const [path, raw] of Object.entries(endingFiles)) {
  const { id, ending } = parseEnding(raw, path)
+  if (seenEndings.has(id)) throw new Error(`${path}: duplicate ending id "${id}"`)
  endings[id] = ending
  seenEndings.add(id)
 }
-const requiredEndings = ['true', 'wrong', 'bad'] as const
-for (const id of requiredEndings) {
-  if (!seenEndings.has(id)) {
-    throw new Error(`endings/${id}.md is missing — every ending id must have a markdown file.`)
-  }
+
+interface AssembleWorldInput {
+  game: GameManifest
+  ui?: World['ui']
+  parser?: World['parser']
+  messages?: World['messages']
+  mechanics?: World['mechanics']
+  actions?: World['actions']
+  rooms: Record<string, Room>
+  items: Record<string, Item>
+  endings: World['endings']
+  encounters: Record<string, EncounterDef>
+  encounterDocs: ParsedEncounterNarration[]
 }

-// Cross-reference validation.
-// Build set of all known flag names from encounter setFlags and ending whenFlags.
-const knownFlags = new Set<string>()
-for (const enc of Object.values(encounters)) {
+export function assembleWorld({
+  game,
+  ui,
+  parser,
+  messages,
+  mechanics,
+  actions,
+  rooms,
+  items,
+  endings,
+  encounters,
+  encounterDocs,
+}: AssembleWorldInput): World {
+  // Build set of all known flag names from encounter setFlags and ending whenFlags.
+  const knownFlags = new Set<string>()
+  for (const enc of Object.values(encounters)) {
    if (enc.onResolved?.setFlags) {
      for (const flagName of Object.keys(enc.onResolved.setFlags)) knownFlags.add(flagName)
    }
-}
-for (const ending of Object.values(endings)) {
+  }
+  for (const action of Object.values(actions ?? {})) {
+    if (action.setsFlags) {
+      for (const flagName of Object.keys(action.setsFlags)) knownFlags.add(flagName)
+    }
+  }
+  for (const ending of Object.values(endings)) {
    for (const flagName of Object.keys(ending.whenFlags)) knownFlags.add(flagName)
-}
+  }

-for (const room of Object.values(rooms)) {
+  for (const id of game.endingPriority) {
+    if (!endings[id]) {
+      throw new Error(`game.md: endingPriority references "${id}" but endings/${id}.md is missing.`)
+    }
+  }
+
+  for (const room of Object.values(rooms)) {
    for (const [dir, dest] of Object.entries(room.exits)) {
      if (!rooms[dest!]) {
        throw new Error(`rooms/${room.id}.md: exit${dir.toUpperCase()} references "${dest}" but no such room exists.`)
@@ -104,27 +191,93 @@ for (const room of Object.values(rooms)) {
        }
      }
    }
-}
+  }

-// Validate encounter narration registry: every encounter in TS has a markdown doc.
-for (const enc of Object.values(encounters)) {
+  if (!rooms[game.startingRoom]) {
+    throw new Error(`game.md: startingRoom references "${game.startingRoom}" but no such room exists.`)
+  }
+  for (const itemId of game.startingInventory) {
+    if (!items[itemId]) {
+      throw new Error(`game.md: startingInventory references unknown item "${itemId}"`)
+    }
+  }
+
+  const actionHandlers = new Map<string, string>()
+  for (const action of Object.values(actions ?? {})) {
+    if (action.handler) {
+      const previous = actionHandlers.get(action.handler)
+      if (previous) {
+        throw new Error(
+          `actions/${action.id}.md: handler "${action.handler}" is already used by actions/${previous}.md. ` +
+          'Only one action may own a handler-backed behavior.',
+        )
+      }
+      actionHandlers.set(action.handler, action.id)
+    }
+
+    const referencedItems: Array<[string, string]> = [
+      ...(action.requires?.allHeld ?? []).map((id): [string, string] => ['requires.allHeld', id]),
+      ...(action.requires?.allVisibleOrHeld ?? []).map((id): [string, string] => ['requires.allVisibleOrHeld', id]),
+      ...(action.consumes?.inventory ?? []).map((id): [string, string] => ['consumes.inventory', id]),
+      ...(action.decrements ? [['decrements.item', action.decrements.item] as [string, string]] : []),
+    ]
+    for (const [field, itemId] of referencedItems) {
+      if (!items[itemId]) {
+        throw new Error(`actions/${action.id}.md: ${field} references unknown item "${itemId}"`)
+      }
+    }
+    if (action.handler === 'drunk-transition') {
+      const config = action.drunkTransition
+      if (!config) {
+        throw new Error(`actions/${action.id}.md uses drunk-transition but is missing drunkTransition config`)
+      }
+      for (const [key, roomId] of Object.entries({
+        destinationRoom: config.destinationRoom,
+        wakeRoom: config.wakeRoom,
+        resetRoom: config.resetRoom,
+      })) {
+        if (!rooms[roomId]) {
+          throw new Error(`actions/${action.id}.md: drunkTransition.${key} references unknown room "${roomId}"`)
+        }
+      }
+    }
+  }
+
+  // Validate encounter narration registry: every encounter has a markdown doc.
+  for (const enc of Object.values(encounters)) {
    const doc = encounterDocs.find(d => d.id === enc.id)
    if (!doc) {
      throw new Error(`encounters/${enc.id}.md: missing narration markdown for encounter "${enc.id}"`)
    }
-  if (doc.startsIn !== enc.startsIn) {
-    throw new Error(`encounters/${enc.id}.md: startsIn "${doc.startsIn}" does not match encounters.ts "${enc.startsIn}"`)
  }
-  if (doc.initialPhase !== enc.initialPhase) {
-    throw new Error(`encounters/${enc.id}.md: initialPhase "${doc.initialPhase}" does not match encounters.ts "${enc.initialPhase}"`)
-  }
-}

-export const world: World = {
-  startingRoom: 'outside-gate',
-  startingInventory: ['letter', 'matches', 'broken-cigarette'],
+  return {
+    game,
+    ui,
+    parser,
+    messages,
+    mechanics,
+    actions,
+    startingRoom: game.startingRoom,
+    startingInventory: game.startingInventory,
+    endingPriority: game.endingPriority,
    rooms,
    items,
    encounters,
    endings,
+  }
 }
+
+export const world: World = assembleWorld({
+  game,
+  ui,
+  parser,
+  messages,
+  mechanics,
+  actions,
+  rooms,
+  items,
+  encounters,
+  endings,
+  encounterDocs,
+})
@@ -0,0 +1,9 @@
+---
+id: altar-stone
+names: ["altar", "altar stone", "cracked altar", "altar-stone"]
+short: "a cracked altar stone"
+takeable: false
+initialState: {}
+---
+
+The altar has split across the center. The crack is narrow enough to hide a thread and deep enough to swallow light.
@@ -0,0 +1,9 @@
+---
+id: portrait-frame
+names: ["frame", "portrait frame", "shattered frame", "portrait-frame"]
+short: "a shattered portrait frame"
+takeable: false
+initialState: {}
+---
+
+The backing has warped away from the frame. Someone wrote beneath it, then scratched the writing into harmless lines.
@@ -0,0 +1,11 @@
+---
+id: rainwater-basin
+names: ["basin", "rainwater basin", "rainwater", "water", "rainwater-basin"]
+short: "a rainwater basin"
+takeable: false
+initialState: {}
+---
+
+The basin is cut directly into the floor. Rain strikes its surface without making rings.
+
+If you lean near it, the water shows rooms you have already left.
@@ -0,0 +1,11 @@
+---
+id: rusted-key
+names: ["key", "rusted key", "rusted-key"]
+short: "a rusted key"
+takeable: true
+initialState: {}
+---
+
+The key is furred with rust except where fingers have worried the bow clean. Its teeth are thin, almost eaten through.
+
+It smells faintly of rain.
@@ -1,5 +1,330 @@
 import { describe, it, expect, beforeEach } from 'vitest'
-import { parseRoom, parseItem, parseEnding, parseEncounterNarration, narration, registerEncounterNarrations, _resetEncounterNarrationRegistry } from './loader'
+import {
+  parseGame,
+  parseAction,
+  parseLightMechanic,
+  parseResolveMechanic,
+  parseMessages,
+  parseParser,
+  parseUi,
+  parseRoom,
+  parseItem,
+  parseEnding,
+  parseEncounterNarration,
+  narration,
+  registerEncounterNarrations,
+  _resetEncounterNarrationRegistry,
+} from './loader'
+
+const GAME_MD = `---
+id: halfstreet
+title: Halfstreet
+description: A gothic mystery.
+startingRoom: "[[outside-gate]]"
+startingInventory:
+  - "[[letter]]"
+endingPriority:
+  - "true"
+  - wrong
+transcriptCap: 200
+---
+
+## opening-art
+HALFSTREET
+
+## help
+Help text.
+
+## ended
+The story has ended.
+`
+
+describe('parseGame', () => {
+  it('parses manifest frontmatter and sections', () => {
+    const game = parseGame(GAME_MD, 'game.md')
+    expect(game).toEqual({
+      id: 'halfstreet',
+      title: 'Halfstreet',
+      description: 'A gothic mystery.',
+      startingRoom: 'outside-gate',
+      startingInventory: ['letter'],
+      endingPriority: ['true', 'wrong'],
+      transcriptCap: 200,
+      openingArt: 'HALFSTREET',
+      helpText: 'Help text.',
+      endedText: 'The story has ended.',
+    })
+  })
+
+  it('throws when a required section is missing', () => {
+    const incomplete = GAME_MD.replace('## help\nHelp text.\n\n', '')
+    expect(() => parseGame(incomplete, 'game.md')).toThrow(/missing required section.*help/i)
+  })
+})
+
+const PARSER_MD = `---
+directions:
+  n: [n, north]
+  s: [s, south]
+  e: [e, east]
+  w: [w, west]
+  u: [u, up]
+  d: [d, down]
+prepositions: [with, on]
+stopWords: [the]
+noTargetVerbs: [look]
+metaVerbs: [restart]
+verbs:
+  go: [go]
+  look: [look, observe]
+  take: [take, pick up]
+---
+
+# Parser Vocabulary
+`
+
+describe('parseParser', () => {
+  it('parses parser vocabulary frontmatter', () => {
+    const parser = parseParser(PARSER_MD, 'parser.md')
+    expect(parser.verbs.look).toEqual(['look', 'observe'])
+    expect(parser.verbs.take).toContain('pick up')
+    expect(parser.directions.n).toEqual(['n', 'north'])
+    expect(parser.noTargetVerbs).toEqual(['look'])
+  })
+
+  it('rejects unsupported verb keys', () => {
+    const invalid = PARSER_MD.replace('  take: [take, pick up]', '  dance: [dance]')
+    expect(() => parseParser(invalid, 'parser.md')).toThrow()
+  })
+})
+
+const UI_MD = `---
+pageTitle: Halfstreet - Ethan J Lewis
+description: A gothic mystery.
+robots: noindex
+themeColor: "#1a0d00"
+footer:
+  copyright: "© 2026 Ethan J Lewis"
+  copyrightHref: https://ethanjlewis.com
+  buildLabel: "Build #"
+  showBuild: true
+  links:
+    - label: GNU 3.0
+      href: https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE
+    - label: Source Code
+      href: https://half.st/ejlewis/halfstreet
+features:
+  chips: true
+  lightMeter: true
+  typedEffect: true
+  roomScroll: true
+---
+
+# UI
+`
+
+describe('parseUi', () => {
+  it('parses site metadata, footer config, and feature toggles', () => {
+    const ui = parseUi(UI_MD, 'ui.md')
+    expect(ui.pageTitle).toBe('Halfstreet - Ethan J Lewis')
+    expect(ui.footer.buildLabel).toBe('Build #')
+    expect(ui.footer.links.map((link) => link.label)).toEqual(['GNU 3.0', 'Source Code'])
+    expect(ui.features).toEqual({
+      chips: true,
+      lightMeter: true,
+      typedEffect: true,
+      roomScroll: true,
+    })
+  })
+})
+
+const LIGHT_MECHANIC_MD = `---
+enabled: true
+handler: light
+maxTurns: 3
+burnOn: [wait]
+stateKeys:
+  lit: isLit
+  burn: fuel
+ui:
+  meter: true
+  icon: candle
+---
+
+## noLighter
+No flame.
+
+## flameDies
+Dark again.
+`
+
+describe('parseLightMechanic', () => {
+  it('parses configurable light mechanic frontmatter and messages', () => {
+    const light = parseLightMechanic(LIGHT_MECHANIC_MD, 'mechanics/light.md')
+    expect(light.enabled).toBe(true)
+    expect(light.maxTurns).toBe(3)
+    expect(light.burnOn).toEqual(['wait'])
+    expect(light.stateKeys).toEqual({ lit: 'isLit', burn: 'fuel' })
+    expect(light.messages?.noLighter).toBe('No flame.')
+    expect(light.messages?.flameDies).toBe('Dark again.')
+  })
+
+  it('rejects unknown light message sections', () => {
+    const invalid = `${LIGHT_MECHANIC_MD}
+## typo
+No.
+`
+    expect(() => parseLightMechanic(invalid, 'mechanics/light.md')).toThrow(/unknown light mechanic section "## typo"/)
+  })
+})
+
+const RESOLVE_MECHANIC_MD = `---
+enabled: true
+handler: resolve
+ladder: [steady, shaken, reeling, returning]
+wrongVerbCost: 2
+safeRooms:
+  recoverySteps: 2
+failure:
+  retreatAt: returning
+  afterRetreat: reeling
+---
+
+# Resolve
+`
+
+describe('parseResolveMechanic', () => {
+  it('parses configurable resolve mechanic frontmatter', () => {
+    const resolve = parseResolveMechanic(RESOLVE_MECHANIC_MD, 'mechanics/resolve.md')
+    expect(resolve.enabled).toBe(true)
+    expect(resolve.ladder).toEqual(['steady', 'shaken', 'reeling', 'returning'])
+    expect(resolve.wrongVerbCost).toBe(2)
+    expect(resolve.safeRooms.recoverySteps).toBe(2)
+    expect(resolve.failure.afterRetreat).toBe('reeling')
+  })
+
+  it('rejects failure levels outside the ladder', () => {
+    const invalid = RESOLVE_MECHANIC_MD.replace('ladder: [steady, shaken, reeling, returning]', 'ladder: [steady, shaken]')
+    expect(() => parseResolveMechanic(invalid, 'mechanics/resolve.md')).toThrow(/failure\.retreatAt must be present in ladder/)
+  })
+})
+
+const ACTION_MD = `---
+id: burn-letter
+verbs: [use]
+requires:
+  allVisibleOrHeld:
+    - "[[letter]]"
+    - "[[matches]]"
+consumes:
+  inventory:
+    - "[[letter]]"
+decrements:
+  item: "[[matches]]"
+  stateKey: uses
+setsFlags:
+  letterBurned: true
+---
+
+## success
+The letter catches at one corner. In a few breaths it is ash.
+
+## spent
+The matchbook is empty.
+`
+
+const HANDLER_ACTION_MD = `---
+id: drink-whiskey
+verbs: [drink]
+handler: drunk-transition
+requires:
+  allHeld:
+    - "[[whiskey]]"
+consumes:
+  inventory:
+    - "[[whiskey]]"
+drunkTransition:
+  destinationRoom: "[[drunk-hall]]"
+  maxMoves: 20
+  wakeRoom: "[[foyer]]"
+  resetRoom: "[[kitchen]]"
+---
+
+## success
+You drink from the bottle.
+
+## secretFoundPassOut
+The faceless man steps backward.
+
+## tooManyMovesPassOut
+The rooms keep turning.
+
+## reset
+The bottle is not with you.
+`
+
+describe('parseAction', () => {
+  it('parses a declarative action with wikilinks and sections', () => {
+    const action = parseAction(ACTION_MD, 'actions/burn-letter.md')
+    expect(action.id).toBe('burn-letter')
+    expect(action.verbs).toEqual(['use'])
+    expect(action.requires?.allVisibleOrHeld).toEqual(['letter', 'matches'])
+    expect(action.consumes?.inventory).toEqual(['letter'])
+    expect(action.decrements).toEqual({ item: 'matches', stateKey: 'uses' })
+    expect(action.setsFlags).toEqual({ letterBurned: true })
+    expect(action.messages.success).toContain('ash')
+  })
+
+  it('parses a handler-backed drunk transition action', () => {
+    const action = parseAction(HANDLER_ACTION_MD, 'actions/drink-whiskey.md')
+    expect(action.id).toBe('drink-whiskey')
+    expect(action.handler).toBe('drunk-transition')
+    expect(action.requires?.allHeld).toEqual(['whiskey'])
+    expect(action.consumes?.inventory).toEqual(['whiskey'])
+    expect(action.drunkTransition).toEqual({
+      destinationRoom: 'drunk-hall',
+      maxMoves: 20,
+      wakeRoom: 'foyer',
+      resetRoom: 'kitchen',
+    })
+    expect(action.messages.tooManyMovesPassOut).toContain('turning')
+  })
+
+  it('requires a success section', () => {
+    const invalid = ACTION_MD.replace(/## success[\s\S]*?## spent/, '## spent')
+    expect(() => parseAction(invalid, 'actions/burn-letter.md')).toThrow(/missing required section "## success"/)
+  })
+
+  it('requires handler-specific sections for drunk transition actions', () => {
+    const invalid = HANDLER_ACTION_MD.replace(/## tooManyMovesPassOut[\s\S]*?## reset/, '## reset')
+    expect(() => parseAction(invalid, 'actions/drink-whiskey.md')).toThrow(
+      /missing required section "## tooManyMovesPassOut" for handler "drunk-transition"/,
+    )
+  })
+})
+
+const MESSAGES_MD = `## unknown-verb
+No.
+
+## inventory-empty
+Nothing held.
+`
+
+describe('parseMessages', () => {
+  it('parses keyed message sections', () => {
+    expect(parseMessages(MESSAGES_MD, 'messages.md')).toEqual({
+      'unknown-verb': 'No.',
+      'inventory-empty': 'Nothing held.',
+    })
+  })
+
+  it('rejects unknown message keys', () => {
+    const invalid = `## typo-key
+No.
+`
+    expect(() => parseMessages(invalid, 'messages.md')).toThrow(/unknown message section "## typo-key"/)
+  })
+})

 const FOYER_MD = `---
 id: foyer
@@ -251,6 +576,24 @@ const RAT_MD = `---
 id: rat
 startsIn: "[[cellar-stair]]"
 initialPhase: lurking
+onResolved:
+  setFlags:
+    ratGone: true
+defaultWrongVerbNarration: wrong-verb
+phases:
+  lurking:
+    description: lurking
+    transitions:
+      - verb: attack
+        target: rat
+        chipLabel: ATTACK RAT
+        chipCommand: attack rat
+        narration: attack-resolved
+        to: resolved
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-stays
+        to: lurking
 ---

 ## lurking
@@ -261,6 +604,9 @@ You stamp. The rat squeals and is gone into the dark.

 ## wait-stays
 The rat does not move. Neither do you.
+
+## wrong-verb
+The rat watches.
 `

 describe('parseEncounterNarration', () => {
@@ -273,7 +619,41 @@ describe('parseEncounterNarration', () => {
      lurking: 'A heavy rat watches you from the third step. Its eyes catch the light.',
      'attack-resolved': 'You stamp. The rat squeals and is gone into the dark.',
      'wait-stays': 'The rat does not move. Neither do you.',
+      'wrong-verb': 'The rat watches.',
    })
+    expect(doc.encounter).toMatchObject({
+      id: 'rat',
+      startsIn: 'cellar-stair',
+      initialPhase: 'lurking',
+      onResolved: { setFlags: { ratGone: true } },
+      defaultWrongVerbNarration: 'The rat watches.',
+    })
+    const lurking = doc.encounter?.phases.lurking
+    expect(lurking).toBeDefined()
+    expect(lurking?.description).toContain('heavy rat')
+    expect(lurking?.transitions).toEqual([
+      {
+        verb: 'attack',
+        target: 'rat',
+        chipLabel: 'ATTACK RAT',
+        chipCommand: 'attack rat',
+        narration: 'You stamp. The rat squeals and is gone into the dark.',
+        to: 'resolved',
+      },
+      {
+        verb: 'wait',
+        chipLabel: 'WAIT',
+        narration: 'The rat does not move. Neither do you.',
+        to: 'lurking',
+      },
+    ])
+  })
+
+  it('throws when encounter frontmatter points at a missing prose section', () => {
+    const invalid = RAT_MD.replace('narration: attack-resolved', 'narration: missing-key')
+    expect(() => parseEncounterNarration(invalid, 'encounters/rat.md')).toThrow(
+      /frontmatter references missing section "## missing-key"/,
+    )
  })

  it('throws when no sections are present', () => {
@@ -18,9 +18,20 @@ function matter(raw: string): ParsedFile {
  const data = (parsed && typeof parsed === 'object' ? parsed : {}) as Record<string, unknown>
  return { data, content }
 }
-import type { Room, RoomDescriptions, Item } from './types'
+import { DEFAULT_WORLD_MESSAGES, type DeclarativeAction, type EncounterDef, type Room, type RoomDescriptions, type Item, type WorldMessages } from './types'
 import type { Direction } from '../engine/types'
-import { roomFrontmatterSchema, itemFrontmatterSchema, endingFrontmatterSchema, encounterFrontmatterSchema } from './schema'
+import {
+  gameFrontmatterSchema,
+  actionFrontmatterSchema,
+  lightMechanicFrontmatterSchema,
+  parserFrontmatterSchema,
+  resolveMechanicFrontmatterSchema,
+  roomFrontmatterSchema,
+  itemFrontmatterSchema,
+  endingFrontmatterSchema,
+  encounterFrontmatterSchema,
+  uiFrontmatterSchema,
+} from './schema'

 const WIKILINK = /^\[\[([^\]|]+)(?:\|[^\]]*)?\]\]$/

@@ -78,6 +89,139 @@ const DIR_KEYS: Record<Direction, { exit: string; requires: string; locked: stri

 const REQUIRED_ROOM_SECTIONS = ['first-visit', 'revisit', 'examined'] as const

+const REQUIRED_GAME_SECTIONS = ['opening-art', 'help', 'ended'] as const
+
+export function parseGame(raw: string, sourcePath: string) {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  const fm = gameFrontmatterSchema.parse(frontmatter)
+  const sections = splitSections(parsed.content)
+  for (const key of REQUIRED_GAME_SECTIONS) {
+    if (!(key in sections)) {
+      throw new Error(`${sourcePath}: missing required section "## ${key}"`)
+    }
+  }
+
+  return {
+    id: fm.id,
+    title: fm.title,
+    description: fm.description,
+    startingRoom: fm.startingRoom,
+    startingInventory: fm.startingInventory,
+    endingPriority: fm.endingPriority,
+    transcriptCap: fm.transcriptCap,
+    openingArt: sections['opening-art']!,
+    helpText: sections['help']!,
+    endedText: sections['ended']!,
+  }
+}
+
+export function parseParser(raw: string, _sourcePath: string) {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  return parserFrontmatterSchema.parse(frontmatter)
+}
+
+export function parseUi(raw: string, _sourcePath: string) {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  return uiFrontmatterSchema.parse(frontmatter)
+}
+
+export function parseMessages(raw: string, sourcePath: string): WorldMessages {
+  const parsed = matter(raw)
+  const sections = splitSections(parsed.content)
+  const allowed = Object.keys(DEFAULT_WORLD_MESSAGES)
+  for (const key of Object.keys(sections)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`${sourcePath}: unknown message section "## ${key}". Allowed: ${allowed.join(', ')}`)
+    }
+  }
+  return sections as WorldMessages
+}
+
+const LIGHT_MESSAGE_KEYS = [
+  'useLighterWithWhat',
+  'cannotLight',
+  'alreadyLit',
+  'notHelpful',
+  'spent',
+  'noLighter',
+  'cannotExtinguish',
+  'notLit',
+  'dropLit',
+  'flameCatches',
+  'flameDies',
+] as const
+
+export function parseLightMechanic(raw: string, sourcePath: string) {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  const fm = lightMechanicFrontmatterSchema.parse(frontmatter)
+  const sections = splitSections(parsed.content)
+  for (const key of Object.keys(sections)) {
+    if (!LIGHT_MESSAGE_KEYS.includes(key as typeof LIGHT_MESSAGE_KEYS[number])) {
+      throw new Error(`${sourcePath}: unknown light mechanic section "## ${key}". Allowed: ${LIGHT_MESSAGE_KEYS.join(', ')}`)
+    }
+  }
+
+  return {
+    ...fm,
+    messages: sections,
+  }
+}
+
+export function parseResolveMechanic(raw: string, _sourcePath: string) {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  return resolveMechanicFrontmatterSchema.parse(frontmatter)
+}
+
+const ACTION_SECTION_KEYS = ['success', 'spent', 'missingRequired', 'secretFoundPassOut', 'tooManyMovesPassOut', 'reset'] as const
+type ActionSectionKey = typeof ACTION_SECTION_KEYS[number]
+const ACTION_REQUIRED_SECTIONS: Record<NonNullable<DeclarativeAction['handler']> | 'default', ActionSectionKey[]> = {
+  default: ['success'],
+  'drunk-transition': ['success', 'secretFoundPassOut', 'tooManyMovesPassOut', 'reset'],
+}
+
+export function parseAction(raw: string, sourcePath: string): DeclarativeAction {
+  const parsed = matter(raw)
+  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
+  const fm = actionFrontmatterSchema.parse(frontmatter)
+  const sections = splitSections(parsed.content)
+  for (const key of Object.keys(sections)) {
+    if (!ACTION_SECTION_KEYS.includes(key as ActionSectionKey)) {
+      throw new Error(`${sourcePath}: unknown action section "## ${key}". Allowed: ${ACTION_SECTION_KEYS.join(', ')}`)
+    }
+  }
+  const requiredSections = ACTION_REQUIRED_SECTIONS[fm.handler ?? 'default']
+  for (const key of requiredSections) {
+    if (!sections[key]) {
+      const scope = fm.handler ? ` for handler "${fm.handler}"` : ''
+      throw new Error(`${sourcePath}: missing required section "## ${key}"${scope}`)
+    }
+  }
+
+  return {
+    id: fm.id,
+    verbs: fm.verbs,
+    handler: fm.handler,
+    requires: fm.requires,
+    consumes: fm.consumes,
+    decrements: fm.decrements,
+    setsFlags: fm.setsFlags,
+    drunkTransition: fm.drunkTransition,
+    messages: {
+      success: sections.success!,
+      spent: sections.spent,
+      missingRequired: sections.missingRequired,
+      secretFoundPassOut: sections.secretFoundPassOut,
+      tooManyMovesPassOut: sections.tooManyMovesPassOut,
+      reset: sections.reset,
+    },
+  }
+}
+
 export function parseRoom(raw: string, sourcePath: string): Room {
  const parsed = matter(raw)
  const frontmatter = stripWikilink(parsed.data) as Record<string, unknown>
@@ -179,7 +323,7 @@ export function parseItem(raw: string, sourcePath: string): Item {
 }

 export interface ParsedEnding {
-  id: 'true' | 'wrong' | 'bad'
+  id: string
  ending: { whenFlags: Record<string, string | boolean | number | string[]>; narration: string }
 }

@@ -199,6 +343,7 @@ export interface ParsedEncounterNarration {
  startsIn: string
  initialPhase: string
  narrations: Record<string, string>
+  encounter?: EncounterDef
 }

 export function parseEncounterNarration(raw: string, sourcePath: string): ParsedEncounterNarration {
@@ -209,14 +354,67 @@ export function parseEncounterNarration(raw: string, sourcePath: string): Parsed
  if (Object.keys(narrations).length === 0) {
    throw new Error(`${sourcePath}: no narration sections found`)
  }
+  const encounter = fm.phases
+    ? buildEncounterFromMarkdown(fm, narrations, sourcePath)
+    : undefined
+
  return {
    id: fm.id,
    startsIn: fm.startsIn,
    initialPhase: fm.initialPhase,
    narrations,
+    encounter,
  }
 }

+function proseSection(sections: Record<string, string>, key: string, sourcePath: string): string {
+  const text = sections[key]
+  if (text === undefined) {
+    const available = Object.keys(sections).join(', ') || '(none)'
+    throw new Error(`${sourcePath}: frontmatter references missing section "## ${key}". Available: ${available}`)
+  }
+  return text
+}
+
+function buildEncounterFromMarkdown(
+  fm: ReturnType<typeof encounterFrontmatterSchema.parse>,
+  sections: Record<string, string>,
+  sourcePath: string,
+): EncounterDef {
+  const phases: EncounterDef['phases'] = {}
+  for (const [phaseId, phase] of Object.entries(fm.phases ?? {})) {
+    phases[phaseId] = {
+      description: proseSection(sections, phase.description, sourcePath),
+      transitions: phase.transitions.map((transition) => ({
+        ...transition,
+        narration: proseSection(sections, transition.narration, sourcePath),
+      })),
+    }
+  }
+  if (!phases[fm.initialPhase]) {
+    throw new Error(`${sourcePath}: initialPhase "${fm.initialPhase}" is not defined in phases`)
+  }
+
+  const encounter: EncounterDef = {
+    id: fm.id,
+    startsIn: fm.startsIn,
+    initialPhase: fm.initialPhase,
+    phases,
+  }
+  if (fm.aliases) encounter.aliases = fm.aliases
+  if (fm.onResolved) encounter.onResolved = fm.onResolved
+  if (fm.onFailed) {
+    encounter.onFailed = {
+      narration: proseSection(sections, fm.onFailed.narration, sourcePath),
+      retreatTo: fm.onFailed.retreatTo,
+    }
+  }
+  if (fm.defaultWrongVerbNarration) {
+    encounter.defaultWrongVerbNarration = proseSection(sections, fm.defaultWrongVerbNarration, sourcePath)
+  }
+  return encounter
+}
+
 const encounterNarrationRegistry = new Map<string, Map<string, string>>()

 export function registerEncounterNarrations(docs: ParsedEncounterNarration[]): void {
@@ -246,9 +444,8 @@ export function narration(encounterId: string, key: string): string {
 }

 // Auto-register encounter narrations from co-located markdown files at module init.
-// This populates the registry BEFORE encounters.ts is evaluated (ESM evaluates dependencies first),
-// so encounters.ts can call narration() at top level without explicit ordering.
-// While src/mystery/world/encounters/ does not yet exist (Task 8 creates it), this is a no-op.
+// This keeps the narration() helper available for tests and any remaining
+// TypeScript escape hatches that need to reference encounter prose by key.
 const _encounterFiles = import.meta.glob<string>('./encounters/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
@@ -0,0 +1,51 @@
+---
+enabled: true
+handler: light
+maxTurns: 6
+burnOn:
+  - move
+  - wait
+stateKeys:
+  lit: lit
+  burn: burn
+ui:
+  meter: true
+  icon: candle
+---
+
+# Light
+
+The light mechanic controls lightable inventory items, the burn timer, and the terminal meter.
+
+## useLighterWithWhat
+Use match with what?
+
+## cannotLight
+You can't light that.
+
+## alreadyLit
+It's already lit.
+
+## notHelpful
+That isn't going to help.
+
+## spent
+It is spent.
+
+## noLighter
+You have nothing to light it with.
+
+## cannotExtinguish
+You can't extinguish that.
+
+## notLit
+It isn't lit.
+
+## dropLit
+Extinguish it first.
+
+## flameCatches
+It catches.
+
+## flameDies
+The flame dies.
@@ -0,0 +1,19 @@
+---
+enabled: true
+handler: resolve
+ladder:
+  - steady
+  - shaken
+  - reeling
+  - returning
+wrongVerbCost: 1
+safeRooms:
+  recoverySteps: 1
+failure:
+  retreatAt: returning
+  afterRetreat: shaken
+---
+
+# Resolve
+
+The resolve mechanic controls how encounters wear down the player, how safe rooms restore resolve, and which resolve level the player has after an encounter forces a retreat.
@@ -0,0 +1,113 @@
+## unknown-verb
+You consider the words, but they don't fit this place.
+
+## unknown-noun
+You don't see anything like that here.
+
+## malformed
+You hesitate.
+
+## nothing-to-confirm
+Nothing to confirm.
+
+## cancelled
+Cancelled.
+
+## nothing-to-choose
+Nothing to choose between.
+
+## no-undo
+There is no further back.
+
+## use-lighter-with-what
+Use match with what?
+
+## use-unknown
+You can't think how to use that here.
+
+## nothing-happens
+Nothing happens.
+
+## nowhere
+You are nowhere.
+
+## no-exit
+You can't go that way.
+
+## unfinished-exit
+The way ahead is unfinished.
+
+## cannot-drink
+You can't drink that.
+
+## need-carrying
+You'd have to be carrying it.
+
+## time-passes
+Time passes.
+
+## listen
+You listen. The house listens back.
+
+## see-nothing
+You see nothing.
+
+## inventory-empty
+You are empty-handed.
+
+## inventory-heading
+You are carrying:
+
+## dont-see-here
+You don't see that here.
+
+## cannot-take
+You can't take that.
+
+## already-have
+You already have it.
+
+## taken
+Taken.
+
+## dont-have
+You don't have that.
+
+## drop-lit
+Extinguish it first.
+
+## dropped
+Dropped.
+
+## dont-see-anything
+You don't see anything like that.
+
+## nothing-to-read
+There's nothing to read on it.
+
+## cannot-light
+You can't light that.
+
+## already-lit
+It's already lit.
+
+## not-helpful
+That isn't going to help.
+
+## spent
+It is spent.
+
+## no-lighter
+You have nothing to light it with.
+
+## cannot-extinguish
+You can't extinguish that.
+
+## not-lit
+It isn't lit.
+
+## flame-catches
+It catches.
+
+## flame-dies
+The flame dies.
@@ -0,0 +1,467 @@
+# Open-Source Authoring Roadmap
+
+Goal: make Halfstreet usable as a small text-adventure toolkit, where a new author can create or fork a story mostly by editing markdown inside this `src/world` Obsidian vault.
+
+Bias: if a setting, rule, phrase, object, or workflow can reasonably live in markdown frontmatter or markdown sections, put it there. TypeScript should remain the runtime, validator, and escape hatch for genuinely executable behavior.
+
+## Principles
+
+- Keep `src/world` as the authoring surface. Authors should not need to hunt through `src/engine`, `src/ui`, or `src/pages` for ordinary story changes.
+- Prefer markdown files with frontmatter over TypeScript config when the data is declarative.
+- Preserve Obsidian-friendly wikilinks for references between rooms, items, encounters, endings, mechanics, and author notes.
+- Separate generic engine behavior from Halfstreet-specific story behavior.
+- Keep validation strict. Markdown should be friendly to write, but mistakes should fail loudly during dev and CI.
+- Make every new abstraction prove itself against the current Halfstreet content before calling it reusable.
+
+## Target Vault Shape
+
+This is the rough destination, not a required first commit:
+
+```text
+src/world/
+  game.md
+  parser.md
+  ui.md
+  mechanics/
+    light.md
+    resolve.md
+    drunk.md
+    inventory.md
+  actions/
+    burn-letter.md
+    drink-whiskey.md
+  rooms/
+  items/
+  encounters/
+  endings/
+  bugs/
+  authoring.md
+  open-source-authoring-roadmap.md
+```
+
+`game.md` should become the primary manifest: title, description, starting room, starting inventory, ending priority, enabled mechanics, default UI labels, and other story-level settings.
+
+`parser.md` should hold author-controlled vocabulary: verbs, aliases, prepositions, direction words, meta commands, and no-target verbs.
+
+`mechanics/*.md` should describe optional rule modules in markdown. Some mechanics can be fully declarative; others can bind to a named TypeScript handler while keeping all author-facing knobs and prose in markdown.
+
+`actions/*.md` should replace one-off hardcoded interactions where possible, especially story-specific combinations like burning the letter or drinking whiskey.
+
+## Phase 1: Manifest in Markdown
+
+Move story-level constants out of TypeScript and into `src/world/game.md`.
+
+Candidate frontmatter:
+
+```yaml
+id: halfstreet
+title: Half Street
+description: A gothic mystery.
+startingRoom: "[[outside-gate]]"
+startingInventory:
+  - "[[letter]]"
+  - "[[matches]]"
+  - "[[broken-cigarette]]"
+endingPriority:
+  - mercy
+  - "true"
+  - replacement
+  - bad
+  - wrong
+transcriptCap: 200
+```
+
+Candidate sections:
+
+```md
+## opening-art
+...
+
+## help
+...
+
+## ended
+The story has ended. Type `restart` or `undo`.
+```
+
+Implementation notes:
+
+- Add a `parseGame` loader path beside `parseRoom`, `parseItem`, `parseEnding`, and `parseEncounterNarration`.
+- Update `World` to include manifest data instead of hardcoding `startingRoom`, `startingInventory`, required endings, ending priority, ASCII art, and help copy in engine/UI files.
+- Keep validation in `src/world/index.ts`: starting room must exist, starting inventory must reference real items, ending priority must reference loaded endings.
+- Treat this as the first reusable boundary. A fork should be able to change the starting room and opening text without touching TypeScript.
+
+Acceptance criteria:
+
+- `src/world/index.ts` no longer hardcodes `outside-gate`, starting items, or ending priority.
+- Opening ASCII/help text can be edited in Obsidian.
+- Existing Halfstreet tests and build still pass.
+
+## Phase 2: Parser Vocabulary in Markdown
+
+Move parser vocabulary into `src/world/parser.md`.
+
+Candidate frontmatter:
+
+```yaml
+directions:
+  n: [n, north]
+  s: [s, south]
+  e: [e, east]
+  w: [w, west]
+  u: [u, up]
+  d: [d, down]
+prepositions: [with, on, in, to]
+stopWords: [at, the, a, an]
+noTargetVerbs: [look, inventory, wait, listen]
+metaVerbs: [restart, undo, hint, save, quit, theme]
+verbs:
+  go: [go, walk, move]
+  look: [look, l]
+  examine: [examine, x, inspect]
+  take: [take, get, grab, pick up]
+  drop: [drop, put, leave]
+  use: [use, combine]
+  open: [open, uncover]
+  close: [close]
+  drink: [drink, sip]
+  read: [read]
+  light: [light]
+  extinguish: [extinguish, douse]
+  attack: [attack, kill, fight, strike]
+  hold: [hold, show]
+  push: [push, press]
+  pull: [pull]
+  cut: [cut, trim]
+  play: [play]
+  listen: [listen]
+  pour: [pour]
+  wait: [wait, z]
+```
+
+Implementation notes:
+
+- Keep the parser code generic: it should consume a parsed vocabulary object rather than owning Halfstreet's vocabulary.
+- Allow multi-word verb aliases from markdown, not a separate hardcoded `TWO_WORD_VERBS` list.
+- Validate that every verb key maps to an engine-supported verb or a registered custom action.
+- Keep parser behavior deterministic and testable with a small synthetic vocabulary fixture.
+
+Acceptance criteria:
+
+- A new verb alias can be added by editing `parser.md`.
+- Parser tests cover markdown-loaded vocabulary.
+- Existing Halfstreet commands continue to parse.
+
+## Phase 3: Text and System Messages in Markdown
+
+Move generic narration strings that authors may want to tune into markdown.
+
+Candidate file: `src/world/messages.md`
+
+Candidate sections:
+
+```md
+## unknown-verb
+You consider the words, but they don't fit this place.
+
+## unknown-noun
+You don't see anything like that here.
+
+## malformed
+You hesitate.
+
+## nothing-to-confirm
+Nothing to confirm.
+
+## cancelled
+Cancelled.
+
+## inventory-empty
+You are empty-handed.
+
+## taken
+Taken.
+
+## dropped
+Dropped.
+```
+
+Implementation notes:
+
+- Add a small message lookup helper with fallback defaults.
+- Use message keys from dispatcher and UI instead of inline strings.
+- Keep heavily stateful narration in mechanics/actions, not in one giant message file.
+
+Acceptance criteria:
+
+- Common parser/dispatcher responses are author-editable in Obsidian.
+- Missing message keys fail validation or fall back predictably.
+
+## Phase 4: Mechanics as Markdown-Configured Modules
+
+Move optional, reusable systems into `src/world/mechanics/*.md`.
+
+Start with mechanics that already exist:
+
+- `light.md`: burn duration, burn trigger policy, item state keys, meter visibility, extinguish behavior, author-facing prose keys.
+- `resolve.md`: resolve ladder, safe-room recovery, failure behavior.
+- `drunk.md`: special room prefix, max moves, pass-out room, item reset behavior, visual effect flag.
+- `inventory.md`: carry limits later, drop policy, lit-drop restrictions.
+
+Candidate `light.md` frontmatter:
+
+```yaml
+enabled: true
+handler: light
+maxTurns: 6
+burnOn:
+  - move
+  - wait
+stateKeys:
+  lit: lit
+  burn: burn
+ui:
+  meter: true
+  icon: candle
+messages:
+  noLighter: You have nothing to light it with.
+  alreadyLit: It's already lit.
+  notLit: It isn't lit.
+  dropLit: Extinguish it first.
+```
+
+Implementation notes:
+
+- TypeScript still owns the actual light algorithm, but markdown owns the knobs and prose.
+- `World` should expose enabled mechanics as parsed data.
+- Dispatcher should call enabled mechanic handlers through a small registry rather than direct Halfstreet-specific functions.
+- Do not overgeneralize on the first pass. Convert one mechanic, keep tests green, then repeat.
+
+Acceptance criteria:
+
+- The light timer can be changed from markdown.
+- Disabling a mechanic in markdown removes its behavior cleanly.
+- Existing light UI still works from parsed mechanic data.
+
+## Phase 5: Declarative Actions
+
+Move one-off item interactions into `src/world/actions/*.md` where possible.
+
+Candidate `burn-letter.md`:
+
+```yaml
+id: burn-letter
+verbs: [use, light]
+requires:
+  allVisibleOrHeld:
+    - "[[letter]]"
+    - "[[matches]]"
+consumes:
+  inventory:
+    - "[[letter]]"
+decrements:
+  item: "[[matches]]"
+  stateKey: uses
+setsFlags:
+  letterBurned: true
+```
+
+```md
+## success
+The letter catches at one corner. In a few breaths it is ash.
+
+## spent
+The matchbook is empty.
+```
+
+Candidate `drink-whiskey.md` may need a `handler: drunk-transition` escape hatch because it changes room, removes and resets an item, and starts a timed mode. That is acceptable: markdown should still own the item ids, destination room, max moves, and prose.
+
+Implementation notes:
+
+- Support a small declarative action grammar first: required items, consumed items, state decrement, flags, room transition, success narration.
+- Add `handler` as an explicit escape hatch for complex behavior.
+- Validate all referenced items, rooms, flags, and section keys.
+
+Acceptance criteria:
+
+- Burning the letter no longer lives as hardcoded ids in the dispatcher.
+- At least one complex action remains supported through a named handler with markdown-owned config.
+
+## Phase 6: Encounters Fully in Markdown
+
+Current state: implemented. Encounter phase machines and prose now live together in `src/world/encounters/*.md`.
+
+Destination: encounter phase machines live in `src/world/encounters/*.md`.
+
+Candidate frontmatter:
+
+```yaml
+id: rat
+startsIn: "[[cellar-stair]]"
+initialPhase: lurking
+aliases: [rat]
+onResolved:
+  setFlags:
+    ratGone: true
+defaultWrongVerbNarration: wrong-verb
+phases:
+  lurking:
+    description: lurking
+    transitions:
+      - verb: attack
+        target: rat
+        chipLabel: ATTACK RAT
+        chipCommand: attack rat
+        narration: attack-rat-resolved
+        to: resolved
+      - verb: wait
+        chipLabel: WAIT
+        narration: wait-stays
+        to: lurking
+```
+
+Sections remain the prose:
+
+```md
+## lurking
+...
+
+## attack-rat-resolved
+...
+
+## wait-stays
+...
+
+## wrong-verb
+...
+```
+
+Implementation notes:
+
+- Replace `encounters.ts` with parsed encounter definitions from markdown.
+- Validate every `description`, `narration`, and `defaultWrongVerbNarration` key points to a real section.
+- Keep support for custom handler hooks later if needed, but do not start there.
+
+Acceptance criteria:
+
+- Adding a simple encounter requires one markdown file only.
+- No duplicated `startsIn` / `initialPhase` values between markdown and TypeScript.
+- Encounter transition chips still compute correctly.
+
+## Phase 7: UI Configuration in Markdown
+
+Move author-facing UI labels, themes, footer links, title metadata, and feature toggles into `src/world/ui.md`.
+
+Candidate frontmatter:
+
+```yaml
+pageTitle: Halfstreet - Ethan J Lewis
+description: A gothic mystery.
+robots: noindex
+themeColor: "#1a0d00"
+footer:
+  copyright: "2026 Ethan J Lewis"
+  links:
+    - label: GNU 3.0
+      href: https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE
+    - label: Source Code
+      href: https://half.st/ejlewis/halfstreet
+features:
+  chips: true
+  lightMeter: true
+  typedEffect: true
+  roomScroll: true
+```
+
+Implementation notes:
+
+- Keep layout and styling in Astro/CSS.
+- Let markdown control labels, metadata, and feature switches.
+- Avoid making authors edit `src/pages/index.astro` for ordinary title/footer/help changes.
+
+Acceptance criteria:
+
+- Site metadata and footer links are editable from `src/world/ui.md`.
+- Feature toggles are validated and reflected in the UI.
+
+## Phase 8: Authoring Docs and Starter Template
+
+Add docs that live where authors work.
+
+Files:
+
+- `src/world/authoring.md`: how to create rooms, items, encounters, endings, mechanics, and actions.
+- `src/world/templates/room.md`
+- `src/world/templates/item.md`
+- `src/world/templates/encounter.md`
+- `src/world/templates/action.md`
+- `src/world/templates/game.md`
+
+Implementation notes:
+
+- Keep docs short and example-heavy.
+- Include "common validation errors" with exact fixes.
+- Add a tiny sample adventure later if the repo is meant to be a toolkit, not only a Halfstreet fork.
+
+Acceptance criteria:
+
+- A new author can add a room, item, simple encounter, and ending by following files inside the Obsidian vault.
+- Templates use wikilinks and valid frontmatter.
+
+## Phase 9: Package Boundary
+
+Once the markdown-driven pieces are stable, decide whether to keep this as a forkable app or extract a package.
+
+Forkable app path:
+
+- Keep everything in one Astro repo.
+- Document "replace `src/world` to make your own game."
+- Lowest maintenance burden.
+
+Package path:
+
+- Extract generic engine/loader/parser into a package, with Halfstreet as an example app.
+- Better for reuse, but increases release and compatibility work.
+
+Recommendation: stay forkable first. Do not package until at least two different worlds can run through the same engine without code edits.
+
+## Suggested Implementation Order
+
+1. Add `game.md` manifest and parse it.
+2. Move opening/help/ending priority/start state into manifest-backed world data.
+3. Add `parser.md` and make parser consume loaded vocabulary.
+4. Add `messages.md` for common system responses.
+5. Convert the light mechanic to markdown-configured runtime behavior.
+6. Convert `burn-letter` into a declarative action.
+7. Convert encounter state machines into markdown.
+8. Add `ui.md` for metadata, footer, and UI feature toggles.
+9. Add authoring docs and templates.
+10. Reassess package extraction after a second sample world exists.
+
+## Current Status
+
+- Phase 1 is implemented: `game.md` controls the manifest, starting room, starting inventory, ending priority, transcript cap, opening art, help text, and ended text.
+- Phase 2 is implemented: `parser.md` controls command vocabulary, direction aliases, prepositions, stop words, no-target verbs, and meta verbs.
+- Phase 3 is implemented: `messages.md` controls common parser, dispatcher, and UI system responses with TypeScript defaults as fallback.
+- Phase 4 is implemented for the first reusable mechanics: `mechanics/light.md` controls the light mechanic's enabled state, burn triggers, burn duration, state keys, meter toggle, and light prose fallbacks; `mechanics/resolve.md` controls the resolve ladder, safe-room recovery, wrong-verb cost, and retreat behavior.
+- Phase 5 has its first two action patterns implemented: `actions/burn-letter.md` defines a simple declarative interaction, and `actions/drink-whiskey.md` defines a complex `drunk-transition` handler-backed action with markdown-owned item ids, destination room, move cap, reset room, wake room, and prose.
+- Phase 5 validation is hardened: handler-backed actions require their handler-specific prose sections, unsupported handler config is rejected, duplicate handler ownership fails during world assembly, and missing room/item references report the exact action field authors need to fix.
+- Phase 6 started with an incremental migration: encounter markdown gained full phase machine support when `phases:` is present, and `rat` became the first fully markdown-owned encounter.
+- Phase 6 now has its first simple batch migrated: `window-guest`, `covered-cage`, and `piano-echo` are markdown-owned, including aliases, resolved/failed effects, wrong-verb text, transition chips, and transition commands.
+- Phase 6 also has the wait-resolved batch migrated: `breathing-wall`, `linen-shape`, and `stair-sleeper` are markdown-owned, including aliases, resolved/failed effects, wrong-verb text, and wait transition chips.
+- Phase 6 now has an item-gated batch migrated: `ivy-figure`, `child-beneath-well`, and `bone-keeper` are markdown-owned, including required inventory items, repeated narration keys, transition-level flags, alternate fallback transitions, and resolved/failed effects.
+- Phase 6 now has a garden/lower-passage batch migrated: `garden-procession`, `reflection`, and `root-movement` are markdown-owned, including wait, item-gated, and listen transitions plus resolved/failed effects.
+- Phase 6 is implemented: the final legacy batch (`portrait-woman`, `basilisk`, `vault-memory`, `creaking-floorboard`, `distant-steps`, and `rainwater-basin`) is markdown-owned, `encounters.ts` has been removed, and world assembly now requires every encounter markdown file to define `phases:`.
+- Phase 7 is implemented: `ui.md` controls page title, meta description, robots, theme color, footer copyright/link/build labels, and feature toggles for chips, the light meter, typed text, and room-title scrolling.
+- Phase 8 is implemented: `authoring.md` explains the markdown authoring workflow, common validation errors, and current room/item/encounter/ending/mechanic/action surfaces; `templates/` includes starter room, item, encounter, action, and game files.
+- Phase 9 is resolved for now in favor of the forkable app path: README and vault-local authoring docs tell authors to replace `src/world` while keeping the Astro app and TypeScript runtime intact. Package extraction is deferred until a second sample world proves the boundary.
+
+## Near-Term Slice
+
+The next concrete slice should stay on open-source polish without extracting a package:
+
+- Add a short root-level contribution guide if outside authors are expected to send changes.
+- Decide whether to include a tiny second sample world fixture to test the forkable boundary.
+- Keep package extraction deferred until that sample world can run without Halfstreet-specific code edits.
+
+This keeps the toolkit roadmap focused on a low-maintenance open-source shape before adding package complexity.
@@ -0,0 +1,40 @@
+---
+directions:
+  n: [n, north]
+  s: [s, south]
+  e: [e, east]
+  w: [w, west]
+  u: [u, up]
+  d: [d, down]
+prepositions: [with, on, in, to]
+stopWords: [at, the, a, an]
+noTargetVerbs: [look, inventory, wait, listen]
+metaVerbs: [restart, undo, hint, save, quit, theme]
+verbs:
+  go: [go, walk, move]
+  look: [look, l]
+  examine: [examine, x, inspect]
+  inventory: [inventory, inv, i]
+  take: [take, get, grab, pick up]
+  drop: [drop, put, leave]
+  use: [use, combine]
+  open: [open, uncover]
+  close: [close]
+  drink: [drink, sip]
+  read: [read]
+  light: [light]
+  extinguish: [extinguish, douse]
+  attack: [attack, kill, fight, strike]
+  hold: [hold, show]
+  push: [push, press]
+  pull: [pull]
+  cut: [cut, trim]
+  play: [play]
+  listen: [listen]
+  pour: [pour]
+  wait: [wait, z]
+---
+
+# Parser Vocabulary
+
+Edit the frontmatter above to tune the commands Halfstreet accepts.
@@ -2,7 +2,9 @@
 id: bedroom
 title: "[ Bedroom ]"
 exitN: null
-exitS: null
+exitS: "[[returned-nursery]]"
+exitSRequires: woofReturned
+exitSLockedText: "The south wall holds only wallpaper, faded to the color of old linen."
 exitE: "[[nursery]]"
 exitW: null
 exitU: "[[attic]]"
@@ -9,6 +9,7 @@ exitU: null
 exitD: null
 items:
  - "[[family-register]]"
+  - "[[portrait-frame]]"
 encounter: "[[portrait-woman]]"
 ---

@@ -7,7 +7,7 @@ exitE: null
 exitW: null
 exitU: null
 exitD: null
-items: ["silver-vial"]
+items: ["silver-vial", "altar-stone"]
 encounter: "[[basilisk]]"
 safe: false
 ---
@@ -0,0 +1,23 @@
+---
+id: drunk-cellar
+title: "[ Cellar ]"
+exitN: "[[drunk-stairs]]"
+exitS: "[[drunk-hall]]"
+exitE: "[[drunk-door-loop]]"
+exitW: null
+exitU: "[[drunk-kitchen]]"
+exitD: "[[drunk-cellar]]"
+items: []
+encounter: null
+---
+
+## first-visit
+The cellar smells of earth, bottles, and hair singed by a candle.
+
+The ceiling is too low until you stoop, then too high. Shelves line the walls with jars that hold only dark.
+
+## revisit
+The cellar keeps its dark in jars.
+
+## examined
+The floor slopes toward a drain that is not at the lowest point. The jars have labels, but the ink runs away from your eyes.
@@ -0,0 +1,23 @@
+---
+id: drunk-door-loop
+title: "[ Door ]"
+exitN: "[[drunk-hall]]"
+exitS: "[[drunk-kitchen]]"
+exitE: "[[drunk-stairs]]"
+exitW: "[[drunk-landing]]"
+exitU: null
+exitD: null
+items: []
+encounter: null
+---
+
+## first-visit
+A door stands alone in a room too narrow to contain it.
+
+It is open. It is closed. Both facts are true enough to make your stomach turn.
+
+## revisit
+The door returns you to itself by another route.
+
+## examined
+The hinges are on both sides. The keyhole shows a dim hall, then the back of your own head, then nothing.
@@ -0,0 +1,23 @@
+---
+id: drunk-hall
+title: "[ Hallway ]"
+exitN: "[[drunk-door-loop]]"
+exitS: "[[drunk-stairs]]"
+exitE: "[[drunk-kitchen]]"
+exitW: "[[drunk-hall]]"
+exitU: "[[drunk-landing]]"
+exitD: "[[drunk-cellar]]"
+items: []
+encounter: null
+---
+
+## first-visit
+The hallway receives you sideways.
+
+There are too many doors, and each one has the familiar brass knob from somewhere else in the house. The carpet rises and falls as if the boards beneath it are breathing through cloth.
+
+## revisit
+The hallway is still here, or here again.
+
+## examined
+The walls lean without falling. North is ahead until you look at it. South is behind you unless it is upstairs. Every direction seems possible in the way a bad idea seems possible.
@@ -0,0 +1,23 @@
+---
+id: drunk-kitchen
+title: "[ Kitchen ]"
+exitN: "[[drunk-landing]]"
+exitS: "[[drunk-door-loop]]"
+exitE: "[[drunk-hall]]"
+exitW: "[[drunk-cellar]]"
+exitU: null
+exitD: "[[drunk-stairs]]"
+items: []
+encounter: null
+---
+
+## first-visit
+The kitchen has no stove. It has three sinks, all running.
+
+Steam gathers near the ceiling and lowers itself in slow sheets. Something knocks once from inside a cupboard, politely.
+
+## revisit
+The kitchen pours water into itself.
+
+## examined
+Pots hang where windows should be. The counter is wet. A corkscrew turns in a small circle by itself and leaves no mark on the wood.
@@ -0,0 +1,23 @@
+---
+id: drunk-landing
+title: "[ Landing ]"
+exitN: "[[drunk-cellar]]"
+exitS: "[[drunk-hall]]"
+exitE: "[[drunk-kitchen]]"
+exitW: "[[drunk-stairs]]"
+exitU: "[[drunk-door-loop]]"
+exitD: "[[drunk-hall]]"
+items: []
+encounter: "[[creaking-floorboard]]"
+---
+
+## first-visit
+The landing hangs in the dark without a staircase touching it.
+
+A floorboard complains under your weight, then answers from several feet away.
+
+## revisit
+The landing waits for the sound of your next step.
+
+## examined
+There is a narrow seam between two boards. Cold air moves through it in small spoken breaths.
@@ -0,0 +1,23 @@
+---
+id: drunk-stairs
+title: "[ Stairs ]"
+exitN: "[[drunk-hall]]"
+exitS: "[[drunk-cellar]]"
+exitE: null
+exitW: "[[drunk-door-loop]]"
+exitU: "[[drunk-landing]]"
+exitD: "[[drunk-hall]]"
+items: []
+encounter: null
+---
+
+## first-visit
+The stairs climb and descend with the same steps.
+
+The rail is cold on one side and warm on the other. Halfway along, a landing passes you without stopping.
+
+## revisit
+The stairs remember your feet badly.
+
+## examined
+Each tread is worn in the center. Some are worn on the underside too. The banister has been gripped hard enough to smooth the varnish away.
@@ -2,7 +2,9 @@
 id: parlor
 title: "[ Parlor ]"
 exitN: "[[study]]"
-exitS: null
+exitS: "[[wrong-hallway]]"
+exitSRequires: hallwayShifted
+exitSLockedText: "The chairs face that wall with great expectation, but the room has not yet made a door there."
 exitE: null
 exitW: null
 exitU: "[[stair-up]]"
@@ -0,0 +1,27 @@
+---
+id: rain-room
+title: "[ Rain Room ]"
+exitN: null
+exitS: "[[wrong-hallway]]"
+exitE: null
+exitW: null
+exitU: null
+exitD: null
+items:
+  - "[[rusted-key]]"
+  - "[[rainwater-basin]]"
+encounter: "[[rainwater-basin]]"
+---
+
+## first-visit
+Rain falls steadily inside the room and nowhere else.
+
+It drops from a ceiling without clouds and gathers in a basin set into the floor. The walls are papered like a bedroom, tiled like a kitchen, then papered again.
+
+Something small and iron glints near the basin's rim.
+
+## revisit
+The rain room keeps raining.
+
+## examined
+Water threads down the walls without staining them. The basin catches every drop and never fills. The south door opens back into the hallway that should not be here.
@@ -0,0 +1,26 @@
+---
+id: returned-nursery
+title: "[ Nursery ]"
+exitN: null
+exitS: null
+exitE: null
+exitW: "[[bedroom]]"
+exitU: null
+exitD: null
+items: []
+encounter: null
+safe: true
+---
+
+## first-visit
+The toys are no longer arranged.
+
+They lie where a child might have dropped them: horse on its side, blocks scattered under the bed, a wooden soldier face down near the door.
+
+The room is less careful now. Less awake.
+
+## revisit
+The nursery remains untidied.
+
+## examined
+The circle on the floor has opened. Dust fills the places where the toys once sat, pale as old chalk. On the shelf, the bolted music box is closed, and for once it does not seem to be listening.
@@ -8,7 +8,7 @@ exitW: "[[chamber]]"
 exitU: null
 exitD: null
 items: []
-encounter: null
+encounter: "[[vault-memory]]"
 safe: true
 ---

@@ -0,0 +1,27 @@
+---
+id: wrong-hallway
+title: "[ Hallway ]"
+exitN: "[[rain-room]]"
+exitNRequires: distantStepsPassed
+exitNLockedText: "The hallway lengthens ahead of you. Something is still walking there."
+exitS: "[[parlor]]"
+exitE: null
+exitW: null
+exitU: null
+exitD: null
+items: []
+encounter: "[[distant-steps]]"
+---
+
+## first-visit
+The hallway is longer now.
+
+The wallpaper repeats in small mistakes: vine, gate, hand, vine, gate, hand. Doors stand where no doors stood before, but each knob turns into the same cold brass.
+
+Footsteps approach from the far end.
+
+## revisit
+The wrong hallway has kept its length for you.
+
+## examined
+The boards bend slightly under your weight, though the footsteps ahead do not touch them. A rain-smell waits north, thin and steady.
@@ -1,5 +1,261 @@
 import { describe, it, expect } from 'vitest'
-import { roomFrontmatterSchema, itemFrontmatterSchema, endingFrontmatterSchema, encounterFrontmatterSchema } from './schema'
+import {
+  gameFrontmatterSchema,
+  actionFrontmatterSchema,
+  lightMechanicFrontmatterSchema,
+  parserFrontmatterSchema,
+  uiFrontmatterSchema,
+  roomFrontmatterSchema,
+  itemFrontmatterSchema,
+  endingFrontmatterSchema,
+  encounterFrontmatterSchema,
+} from './schema'
+
+describe('gameFrontmatterSchema', () => {
+  it('accepts a markdown game manifest', () => {
+    const data = {
+      id: 'halfstreet',
+      title: 'Halfstreet',
+      description: 'A gothic mystery.',
+      startingRoom: 'outside-gate',
+      startingInventory: ['letter', 'matches'],
+      endingPriority: ['true', 'wrong'],
+      transcriptCap: 200,
+    }
+    expect(() => gameFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects an empty ending priority', () => {
+    const data = {
+      id: 'halfstreet',
+      title: 'Halfstreet',
+      description: 'A gothic mystery.',
+      startingRoom: 'outside-gate',
+      startingInventory: [],
+      endingPriority: [],
+    }
+    expect(() => gameFrontmatterSchema.parse(data)).toThrow()
+  })
+})
+
+describe('parserFrontmatterSchema', () => {
+  it('accepts markdown parser vocabulary', () => {
+    const data = {
+      directions: {
+        n: ['n', 'north'],
+        s: ['s', 'south'],
+        e: ['e', 'east'],
+        w: ['w', 'west'],
+        u: ['u', 'up'],
+        d: ['d', 'down'],
+      },
+      prepositions: ['with', 'on', 'in', 'to'],
+      stopWords: ['at', 'the', 'a', 'an'],
+      noTargetVerbs: ['look', 'inventory', 'wait', 'listen'],
+      metaVerbs: ['restart', 'undo', 'theme'],
+      verbs: {
+        go: ['go', 'walk'],
+        look: ['look', 'observe'],
+        take: ['take', 'pick up'],
+      },
+    }
+    expect(() => parserFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects unsupported verb keys', () => {
+    const data = {
+      directions: {
+        n: ['n'],
+        s: ['s'],
+        e: ['e'],
+        w: ['w'],
+        u: ['u'],
+        d: ['d'],
+      },
+      prepositions: ['with'],
+      verbs: { dance: ['dance'] },
+    }
+    expect(() => parserFrontmatterSchema.parse(data)).toThrow()
+  })
+})
+
+describe('uiFrontmatterSchema', () => {
+  it('accepts markdown UI config', () => {
+    const data = {
+      pageTitle: 'Halfstreet - Ethan J Lewis',
+      description: 'A gothic mystery.',
+      robots: 'noindex',
+      themeColor: '#1a0d00',
+      footer: {
+        copyright: '© 2026 Ethan J Lewis',
+        copyrightHref: 'https://ethanjlewis.com',
+        buildLabel: 'Build #',
+        showBuild: true,
+        links: [
+          { label: 'GNU 3.0', href: 'https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE' },
+          { label: 'Source Code', href: 'https://half.st/ejlewis/halfstreet' },
+        ],
+      },
+      features: {
+        chips: true,
+        lightMeter: true,
+        typedEffect: true,
+        roomScroll: true,
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects invalid footer links', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: {
+        copyright: '© 2026 Ethan J Lewis',
+        links: [{ label: 'Source Code', href: '/relative' }],
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
+  })
+
+  it('accepts a bugReport block with bugpin and bugsink subconfigs', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: {
+        copyright: '© 2026 Ethan J Lewis',
+        links: [],
+      },
+      bugReport: {
+        enabled: true,
+        label: 'Report a Bug',
+        bugpin: {
+          serverUrl: 'https://bugpin.half.st',
+          apiKey: 'proj_07df4bf91f12445b8ef8c723e865ed7b',
+        },
+        bugsink: {
+          enabled: true,
+          dsn: 'https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1',
+        },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('accepts ui config with no bugReport block at all', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects a bugpin block with a non-url serverUrl', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+      bugReport: {
+        enabled: true,
+        bugpin: { serverUrl: 'not-a-url', apiKey: 'proj_x' },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
+  })
+
+  it('rejects a bugsink block with a non-url dsn', () => {
+    const data = {
+      pageTitle: 'Halfstreet',
+      description: 'A gothic mystery.',
+      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
+      bugReport: {
+        enabled: true,
+        bugsink: { dsn: 'whatever' },
+      },
+    }
+    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
+  })
+})
+
+describe('lightMechanicFrontmatterSchema', () => {
+  it('accepts markdown light mechanic config', () => {
+    const data = {
+      enabled: true,
+      handler: 'light',
+      maxTurns: 4,
+      burnOn: ['move', 'wait'],
+      stateKeys: { lit: 'lit', burn: 'burn' },
+      ui: { meter: true, icon: 'candle' },
+    }
+    expect(() => lightMechanicFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('rejects unknown burn triggers', () => {
+    const data = {
+      enabled: true,
+      handler: 'light',
+      maxTurns: 4,
+      burnOn: ['look'],
+    }
+    expect(() => lightMechanicFrontmatterSchema.parse(data)).toThrow()
+  })
+})
+
+describe('actionFrontmatterSchema', () => {
+  it('accepts a declarative action', () => {
+    const data = {
+      id: 'burn-letter',
+      verbs: ['use'],
+      requires: { allVisibleOrHeld: ['letter', 'matches'] },
+      consumes: { inventory: ['letter'] },
+      decrements: { item: 'matches', stateKey: 'uses' },
+      setsFlags: { letterBurned: true },
+    }
+    expect(() => actionFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('accepts a handler-backed drunk transition action', () => {
+    const data = {
+      id: 'drink-whiskey',
+      verbs: ['drink'],
+      handler: 'drunk-transition',
+      requires: { allHeld: ['whiskey'] },
+      consumes: { inventory: ['whiskey'] },
+      drunkTransition: {
+        destinationRoom: 'drunk-hall',
+        maxMoves: 20,
+        wakeRoom: 'foyer',
+        resetRoom: 'kitchen',
+      },
+    }
+    expect(() => actionFrontmatterSchema.parse(data)).not.toThrow()
+  })
+
+  it('requires drunk transition config for handler-backed drunk actions', () => {
+    const data = { id: 'drink-whiskey', verbs: ['drink'], handler: 'drunk-transition' }
+    expect(() => actionFrontmatterSchema.parse(data)).toThrow(/drunkTransition is required/)
+  })
+
+  it('rejects drunk transition config without the matching handler', () => {
+    const data = {
+      id: 'drink-whiskey',
+      verbs: ['drink'],
+      drunkTransition: {
+        destinationRoom: 'drunk-hall',
+        maxMoves: 20,
+        wakeRoom: 'foyer',
+        resetRoom: 'kitchen',
+      },
+    }
+    expect(() => actionFrontmatterSchema.parse(data)).toThrow(/only supported when handler is drunk-transition/)
+  })
+
+  it('rejects unsupported action verbs', () => {
+    const data = { id: 'dance-letter', verbs: ['dance'] }
+    expect(() => actionFrontmatterSchema.parse(data)).toThrow()
+  })
+})

 describe('roomFrontmatterSchema', () => {
  it('accepts a fully populated room', () => {
@@ -67,9 +323,9 @@ describe('endingFrontmatterSchema', () => {
    expect(() => endingFrontmatterSchema.parse(data)).not.toThrow()
  })

-  it('rejects unknown ending id', () => {
-    const data = { id: 'mercy', whenFlags: {} }
-    expect(() => endingFrontmatterSchema.parse(data)).toThrow()
+  it('accepts custom ending ids', () => {
+    const data = { id: 'secret', whenFlags: {} }
+    expect(() => endingFrontmatterSchema.parse(data)).not.toThrow()
  })
 })

@@ -78,6 +334,32 @@ describe('encounterFrontmatterSchema', () => {
    const data = { id: 'rat', startsIn: 'cellar-stair', initialPhase: 'lurking' }
    expect(() => encounterFrontmatterSchema.parse(data)).not.toThrow()
  })
+
+  it('accepts markdown-owned encounter phases', () => {
+    const data = {
+      id: 'rat',
+      startsIn: 'cellar-stair',
+      initialPhase: 'lurking',
+      onResolved: { setFlags: { ratGone: true } },
+      defaultWrongVerbNarration: 'wrong-verb',
+      phases: {
+        lurking: {
+          description: 'lurking',
+          transitions: [
+            {
+              verb: 'attack',
+              target: 'rat',
+              chipLabel: 'ATTACK RAT',
+              chipCommand: 'attack rat',
+              narration: 'attack-rat-resolved',
+              to: 'resolved',
+            },
+          ],
+        },
+      },
+    }
+    expect(() => encounterFrontmatterSchema.parse(data)).not.toThrow()
+  })
 })

 describe('itemFrontmatterSchema — bible additions', () => {
@@ -1,7 +1,190 @@
 import { z } from 'zod'
+import { SUPPORTED_META_VERBS, SUPPORTED_VERBS } from '../engine/parser'
+import { RESOLVE_LEVELS } from '../engine/types'

 const stateValueSchema = z.union([z.string(), z.boolean(), z.number(), z.array(z.string())])
 const stateRecordSchema = z.record(z.string(), stateValueSchema)
+const directionSchema = z.enum(['n', 's', 'e', 'w', 'u', 'd'])
+const verbSchema = z.enum(SUPPORTED_VERBS)
+const metaVerbSchema = z.enum(SUPPORTED_META_VERBS)
+const aliasListSchema = z.array(z.string().trim().min(1)).min(1)
+const lightBurnTriggerSchema = z.enum(['move', 'wait'])
+const resolveLevelSchema = z.enum(RESOLVE_LEVELS)
+const resolveCostSchema = z.union([z.literal(0), z.literal(1), z.literal(2)])
+
+export const gameFrontmatterSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  startingRoom: z.string().min(1),
+  startingInventory: z.array(z.string().min(1)).default([]),
+  endingPriority: z.array(z.string().min(1)).min(1),
+  transcriptCap: z.number().int().positive().optional(),
+})
+
+export type GameFrontmatter = z.infer<typeof gameFrontmatterSchema>
+
+export const parserFrontmatterSchema = z.object({
+  directions: z.record(directionSchema, aliasListSchema),
+  prepositions: aliasListSchema,
+  stopWords: z.array(z.string().trim().min(1)).default([]),
+  noTargetVerbs: z.array(verbSchema).default([]),
+  metaVerbs: z.array(metaVerbSchema).default([]),
+  verbs: z.partialRecord(verbSchema, aliasListSchema),
+}).superRefine((value, ctx) => {
+  for (const direction of directionSchema.options) {
+    if (!value.directions[direction]?.length) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['directions', direction],
+        message: `directions.${direction} must define at least one alias`,
+      })
+    }
+  }
+})
+
+export type ParserFrontmatter = z.infer<typeof parserFrontmatterSchema>
+
+export const uiFrontmatterSchema = z.object({
+  pageTitle: z.string().trim().min(1),
+  description: z.string().trim().min(1),
+  robots: z.string().trim().min(1).default('noindex'),
+  themeColor: z.string().trim().min(1).default('#1a0d00'),
+  footer: z.object({
+    copyright: z.string().trim().min(1),
+    copyrightHref: z.url().optional(),
+    buildLabel: z.string().trim().min(1).default('Build #'),
+    showBuild: z.boolean().default(true),
+    links: z.array(z.object({
+      label: z.string().trim().min(1),
+      href: z.url(),
+    })).default([]),
+  }),
+  features: z.object({
+    chips: z.boolean().default(true),
+    lightMeter: z.boolean().default(true),
+    typedEffect: z.boolean().default(true),
+    roomScroll: z.boolean().default(true),
+  }).default({
+    chips: true,
+    lightMeter: true,
+    typedEffect: true,
+    roomScroll: true,
+  }),
+  bugReport: z.object({
+    enabled: z.boolean().default(false),
+    label: z.string().trim().min(1).default('Report a Bug'),
+    bugpin: z.object({
+      serverUrl: z.url(),
+      apiKey: z.string().trim().min(1),
+    }).optional(),
+    bugsink: z.object({
+      enabled: z.boolean().default(true),
+      dsn: z.url(),
+    }).optional(),
+  }).optional(),
+})
+
+export type UiFrontmatter = z.infer<typeof uiFrontmatterSchema>
+
+export const lightMechanicFrontmatterSchema = z.object({
+  enabled: z.boolean().default(true),
+  handler: z.literal('light').default('light'),
+  maxTurns: z.number().int().positive().default(6),
+  burnOn: z.array(lightBurnTriggerSchema).default(['move', 'wait']),
+  stateKeys: z.object({
+    lit: z.string().trim().min(1).default('lit'),
+    burn: z.string().trim().min(1).default('burn'),
+  }).default({ lit: 'lit', burn: 'burn' }),
+  ui: z.object({
+    meter: z.boolean().default(true),
+    icon: z.string().trim().min(1).default('candle'),
+  }).default({ meter: true, icon: 'candle' }),
+})
+
+export type LightMechanicFrontmatter = z.infer<typeof lightMechanicFrontmatterSchema>
+
+export const resolveMechanicFrontmatterSchema = z.object({
+  enabled: z.boolean().default(true),
+  handler: z.literal('resolve').default('resolve'),
+  ladder: z.array(resolveLevelSchema).min(1).default([...RESOLVE_LEVELS]),
+  wrongVerbCost: resolveCostSchema.default(1),
+  safeRooms: z.object({
+    recoverySteps: z.number().int().nonnegative().default(1),
+  }).default({ recoverySteps: 1 }),
+  failure: z.object({
+    retreatAt: resolveLevelSchema.default('returning'),
+    afterRetreat: resolveLevelSchema.default('shaken'),
+  }).default({ retreatAt: 'returning', afterRetreat: 'shaken' }),
+}).superRefine((value, ctx) => {
+  const seen = new Set(value.ladder)
+  if (seen.size !== value.ladder.length) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['ladder'],
+      message: 'ladder entries must be unique',
+    })
+  }
+  if (!seen.has(value.failure.retreatAt)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['failure', 'retreatAt'],
+      message: 'failure.retreatAt must be present in ladder',
+    })
+  }
+  if (!seen.has(value.failure.afterRetreat)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['failure', 'afterRetreat'],
+      message: 'failure.afterRetreat must be present in ladder',
+    })
+  }
+})
+
+export type ResolveMechanicFrontmatter = z.infer<typeof resolveMechanicFrontmatterSchema>
+
+const actionHandlerSchema = z.enum(['drunk-transition'])
+
+export const actionFrontmatterSchema = z.object({
+  id: z.string().min(1),
+  verbs: z.array(verbSchema).min(1),
+  handler: actionHandlerSchema.optional(),
+  requires: z.object({
+    allHeld: z.array(z.string().min(1)).min(1).optional(),
+    allVisibleOrHeld: z.array(z.string().min(1)).min(1).optional(),
+  }).optional(),
+  consumes: z.object({
+    inventory: z.array(z.string().min(1)).default([]),
+  }).optional(),
+  decrements: z.object({
+    item: z.string().min(1),
+    stateKey: z.string().min(1),
+  }).optional(),
+  setsFlags: stateRecordSchema.optional(),
+  drunkTransition: z.object({
+    destinationRoom: z.string().min(1),
+    maxMoves: z.number().int().positive(),
+    wakeRoom: z.string().min(1),
+    resetRoom: z.string().min(1),
+  }).optional(),
+}).superRefine((value, ctx) => {
+  if (value.handler === 'drunk-transition' && !value.drunkTransition) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['drunkTransition'],
+      message: 'drunkTransition is required when handler is drunk-transition',
+    })
+  }
+  if (value.handler !== 'drunk-transition' && value.drunkTransition) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['drunkTransition'],
+      message: 'drunkTransition is only supported when handler is drunk-transition',
+    })
+  }
+})
+
+export type ActionFrontmatter = z.infer<typeof actionFrontmatterSchema>

 export const roomFrontmatterSchema = z.object({
  id: z.string().min(1),
@@ -46,7 +229,7 @@ export const itemFrontmatterSchema = z.object({
 export type ItemFrontmatter = z.infer<typeof itemFrontmatterSchema>

 export const endingFrontmatterSchema = z.object({
-  id: z.enum(['true', 'wrong', 'bad']),
+  id: z.string().min(1),
  whenFlags: stateRecordSchema.default({}),
 })

@@ -56,6 +239,36 @@ export const encounterFrontmatterSchema = z.object({
  id: z.string().min(1),
  startsIn: z.string().min(1),
  initialPhase: z.string().min(1),
+  aliases: z.array(z.string().min(1)).optional(),
+  onResolved: z.object({
+    setFlags: z.record(z.string(), z.union([z.string(), z.boolean(), z.number()])).optional(),
+    unlockExits: z.array(z.object({
+      room: z.string().min(1),
+      direction: directionSchema,
+    })).optional(),
+  }).optional(),
+  onFailed: z.object({
+    narration: z.string().min(1),
+    retreatTo: z.string().min(1),
+  }).optional(),
+  defaultWrongVerbNarration: z.string().min(1).optional(),
+  phases: z.record(z.string().min(1), z.object({
+    description: z.string().min(1),
+    transitions: z.array(z.object({
+      verb: verbSchema,
+      target: z.string().min(1).optional(),
+      chipLabel: z.string().min(1).optional(),
+      chipCommand: z.string().min(1).optional(),
+      requires: z.object({
+        item: z.string().min(1),
+        state: z.record(z.string(), z.union([z.string(), z.boolean(), z.number()])).optional(),
+      }).optional(),
+      to: z.string().min(1),
+      narration: z.string().min(1),
+      resolveCost: resolveCostSchema.optional(),
+      setFlags: z.record(z.string(), z.union([z.string(), z.boolean(), z.number()])).optional(),
+    })).default([]),
+  })).optional(),
 })

 export type EncounterFrontmatter = z.infer<typeof encounterFrontmatterSchema>
@@ -0,0 +1,15 @@
+---
+id: sample-action
+verbs: [use]
+requires:
+  allVisibleOrHeld:
+    - "[[sample-item]]"
+setsFlags:
+  sampleActionDone: true
+---
+
+## success
+The action succeeds.
+
+## missingRequired
+You do not see what you need.
@@ -0,0 +1,28 @@
+---
+id: sample-encounter
+startsIn: "[[sample-room]]"
+initialPhase: waiting
+aliases: [figure]
+onResolved:
+  setFlags:
+    sampleEncounterResolved: true
+defaultWrongVerbNarration: wrong-verb
+phases:
+  waiting:
+    description: waiting
+    transitions:
+      - verb: wait
+        chipLabel: WAIT
+        chipCommand: wait
+        narration: waited
+        to: resolved
+---
+
+## waiting
+The figure waits.
+
+## waited
+You wait. The figure is gone.
+
+## wrong-verb
+That does not change what waits here.
@@ -0,0 +1,29 @@
+---
+id: sample-game
+title: Sample Game
+description: A small text adventure.
+startingRoom: "[[sample-room]]"
+startingInventory: []
+endingPriority:
+  - sample-ending
+transcriptCap: 200
+---
+
+## opening-art
+SAMPLE GAME
+
+## help
+Type short commands to act in the world.
+
+Common commands:
+look
+n, s, e, w, u, d
+take item
+examine item
+inventory
+wait
+undo
+restart
+
+## ended
+The story has ended. Type `restart` or `undo`.
@@ -0,0 +1,9 @@
+---
+id: sample-item
+names: ["sample item", "item"]
+short: "a sample item"
+takeable: true
+initialState: {}
+---
+
+Describe the item when the player examines it.
@@ -0,0 +1,22 @@
+---
+id: sample-room
+title: "[ Sample Room ]"
+exitN: null
+exitS: null
+exitE: null
+exitW: null
+exitU: null
+exitD: null
+items: []
+encounter: null
+safe: false
+---
+
+## first-visit
+Describe what the player notices the first time they enter.
+
+## revisit
+Describe the room after it has already been seen.
+
+## examined
+Describe closer inspection of the room.
@@ -1,7 +1,181 @@
 // World data type definitions. World modules export plain data conforming to
 // these shapes; the engine reads but never mutates them.

-import type { RoomId, ItemId, EncounterId, Direction, Verb, EncounterPhase } from '../engine/types'
+import type { RoomId, ItemId, EncounterId, Direction, Verb, EncounterPhase, ResolveLevel } from '../engine/types'
+import type { ParserVocabulary } from '../engine/parser'
+
+export const DEFAULT_WORLD_MESSAGES = {
+  'unknown-verb': "You consider the words, but they don't fit this place.",
+  'unknown-noun': "You don't see anything like that here.",
+  malformed: 'You hesitate.',
+  'nothing-to-confirm': 'Nothing to confirm.',
+  cancelled: 'Cancelled.',
+  'nothing-to-choose': 'Nothing to choose between.',
+  'no-undo': 'There is no further back.',
+  'use-lighter-with-what': 'Use match with what?',
+  'use-unknown': "You can't think how to use that here.",
+  'nothing-happens': 'Nothing happens.',
+  nowhere: 'You are nowhere.',
+  'no-exit': "You can't go that way.",
+  'unfinished-exit': 'The way ahead is unfinished.',
+  'cannot-drink': "You can't drink that.",
+  'need-carrying': "You'd have to be carrying it.",
+  'time-passes': 'Time passes.',
+  listen: 'You listen. The house listens back.',
+  'see-nothing': 'You see nothing.',
+  'inventory-empty': 'You are empty-handed.',
+  'inventory-heading': 'You are carrying:',
+  'dont-see-here': "You don't see that here.",
+  'cannot-take': "You can't take that.",
+  'already-have': 'You already have it.',
+  taken: 'Taken.',
+  'dont-have': "You don't have that.",
+  'drop-lit': 'Extinguish it first.',
+  dropped: 'Dropped.',
+  'dont-see-anything': "You don't see anything like that.",
+  'nothing-to-read': "There's nothing to read on it.",
+  'cannot-light': "You can't light that.",
+  'already-lit': "It's already lit.",
+  'not-helpful': "That isn't going to help.",
+  spent: 'It is spent.',
+  'no-lighter': 'You have nothing to light it with.',
+  'cannot-extinguish': "You can't extinguish that.",
+  'not-lit': "It isn't lit.",
+  'flame-catches': 'It catches.',
+  'flame-dies': 'The flame dies.',
+} as const
+
+export type WorldMessageKey = keyof typeof DEFAULT_WORLD_MESSAGES
+export type WorldMessages = Partial<Record<WorldMessageKey, string>>
+
+export interface GameManifest {
+  id: string
+  title: string
+  description: string
+  startingRoom: RoomId
+  startingInventory: ItemId[]
+  endingPriority: string[]
+  transcriptCap?: number
+  openingArt?: string
+  helpText?: string
+  endedText?: string
+}
+
+export interface UiConfig {
+  pageTitle: string
+  description: string
+  robots: string
+  themeColor: string
+  footer: {
+    copyright: string
+    copyrightHref?: string
+    buildLabel: string
+    showBuild: boolean
+    links: Array<{
+      label: string
+      href: string
+    }>
+  }
+  features: {
+    chips: boolean
+    lightMeter: boolean
+    typedEffect: boolean
+    roomScroll: boolean
+  }
+  bugReport?: {
+    enabled: boolean
+    label: string
+    bugpin?: {
+      serverUrl: string
+      apiKey: string
+    }
+    bugsink?: {
+      enabled: boolean
+      dsn: string
+    }
+  }
+}
+
+export type LightBurnTrigger = 'move' | 'wait'
+export type LightMechanicMessageKey =
+  | 'useLighterWithWhat'
+  | 'cannotLight'
+  | 'alreadyLit'
+  | 'notHelpful'
+  | 'spent'
+  | 'noLighter'
+  | 'cannotExtinguish'
+  | 'notLit'
+  | 'dropLit'
+  | 'flameCatches'
+  | 'flameDies'
+
+export interface LightMechanicConfig {
+  enabled: boolean
+  handler: 'light'
+  maxTurns: number
+  burnOn: LightBurnTrigger[]
+  stateKeys: {
+    lit: string
+    burn: string
+  }
+  ui?: {
+    meter?: boolean
+    icon?: string
+  }
+  messages?: Partial<Record<LightMechanicMessageKey, string>>
+}
+
+export interface ResolveMechanicConfig {
+  enabled: boolean
+  handler: 'resolve'
+  ladder: ResolveLevel[]
+  wrongVerbCost: 0 | 1 | 2
+  safeRooms: {
+    recoverySteps: number
+  }
+  failure: {
+    retreatAt: ResolveLevel
+    afterRetreat: ResolveLevel
+  }
+}
+
+export interface WorldMechanics {
+  light?: LightMechanicConfig
+  resolve?: ResolveMechanicConfig
+}
+
+export interface DeclarativeAction {
+  id: string
+  verbs: Verb[]
+  handler?: 'drunk-transition'
+  requires?: {
+    allHeld?: ItemId[]
+    allVisibleOrHeld?: ItemId[]
+  }
+  consumes?: {
+    inventory?: ItemId[]
+  }
+  decrements?: {
+    item: ItemId
+    stateKey: string
+  }
+  setsFlags?: Record<string, string | boolean | number | string[]>
+  drunkTransition?: {
+    destinationRoom: RoomId
+    maxMoves: number
+    wakeRoom: RoomId
+    resetRoom: RoomId
+  }
+  messages: {
+    success: string
+    spent?: string
+    missingRequired?: string
+    secretFoundPassOut?: string
+    tooManyMovesPassOut?: string
+    reset?: string
+  }
+}

 export interface RoomDescriptions {
  /** Shown the first time the player enters this room. */
@@ -80,6 +254,8 @@ export interface EncounterTransition {
  narration: string
  /** Resolve cost for the player on this transition (0–2). */
  resolveCost?: 0 | 1 | 2
+  /** Optional transition-specific story flags. */
+  setFlags?: Record<string, string | boolean | number>
 }

 export interface EncounterDef {
@@ -98,15 +274,18 @@ export interface EncounterDef {
 }

 export interface World {
+  game?: GameManifest
+  ui?: UiConfig
+  parser?: ParserVocabulary
+  messages?: WorldMessages
+  mechanics?: WorldMechanics
+  actions?: Record<string, DeclarativeAction>
  startingRoom: RoomId
  startingInventory: ItemId[]
+  endingPriority?: string[]
  rooms: Record<RoomId, Room>
  items: Record<ItemId, Item>
  encounters: Record<EncounterId, EncounterDef>
  /** Story flag definitions and the endings they unlock. */
-  endings: {
-    true: { whenFlags: Record<string, string | boolean | number | string[]>; narration: string }
-    wrong: { whenFlags: Record<string, string | boolean | number | string[]>; narration: string }
-    bad: { whenFlags: Record<string, string | boolean | number | string[]>; narration: string }
-  }
+  endings: Record<string, { whenFlags: Record<string, string | boolean | number | string[]>; narration: string }>
 }
@@ -0,0 +1,34 @@
+---
+pageTitle: Halfstreet - Ethan J Lewis
+description: A gothic mystery.
+robots: noindex
+themeColor: "#1a0d00"
+footer:
+  copyright: "© 2026 Ethan J Lewis"
+  copyrightHref: https://ethanjlewis.com
+  buildLabel: "Build #"
+  showBuild: true
+  links:
+    - label: GNU 3.0
+      href: https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE
+    - label: Source Code
+      href: https://half.st/ejlewis/halfstreet
+features:
+  chips: true
+  lightMeter: true
+  typedEffect: true
+  roomScroll: true
+bugReport:
+  enabled: true
+  label: "Report a Bug"
+  bugpin:
+    serverUrl: "https://bugpin.half.st"
+    apiKey: "proj_07df4bf91f12445b8ef8c723e865ed7b"
+  bugsink:
+    enabled: true
+    dsn: "https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1"
+---
+
+# UI
+
+This file controls site metadata, footer links, and runtime UI feature switches.
Author	SHA1	Message	Date
ejlewis	89bb69bcfa	chore: obsidian docs ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-17 23:35:13 -05:00
ejlewis	18aa517319	feat(ui): add bug reporting integrations	2026-05-17 23:34:17 -05:00
ejlewis	a51bb6f86f	docs: implementation plan for bug reporting Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-17 23:02:46 -05:00
ejlewis	4f6460297f	docs: design for Bugpin + Bugsink bug reporting Footer link triggers Bugpin's screenshot widget (lazy-loaded) which forwards to GitHub Issues. Bugsink captures uncaught JS errors via the Sentry SDK. Both servers live on the half.st host. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-17 22:57:34 -05:00
ejlewis	03482693ea	Open source markdown authoring workflow ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-13 17:59:13 -05:00
ejlewis	7b1b5d0f6c	chore: add build number and release scripts ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-12 20:52:35 -05:00
ejlewis	e7b74c827a	fix(engine): burn lamp one segment per wait	2026-05-12 20:31:50 -05:00
ejlewis	52fb869976	feat(mystery): add altered rooms and drunk sequence	2026-05-12 20:22:20 -05:00