@brass-lantern/mcp 0.0.1-stage → 2.3.0

package/dist/docs/pages/guide/building-worlds/two-rooms.md

@@ -0,0 +1,339 @@
+# A two-room game
+
+This page builds the smallest complete game, [`packages/engine/src/worlds/examples/two-rooms.ts`](https://github.com/mrballistic/brass-lantern/blob/main/packages/engine/src/worlds/examples/two-rooms.ts), from nothing. You’re home after a long time away; the door is locked, and you left the key somewhere obvious. [A test](https://github.com/mrballistic/brass-lantern/blob/main/packages/engine/tests/worlds/examples/two-rooms.test.ts) plays it to the end.
+
+The whole game is one file, `two-rooms.ts`, holding one object. Its outline:
+
+```ts
+import type { World } from '@brass-lantern/engine';
+
+export const twoRooms: World = {
+  // Two rooms: startRoom and rooms
+  // Things: items
+  // What happens: npcs, dialogue, flagLabels, events and endings
+};
+```
+
+Each section below shows one part of that object, in order; put them inside the braces one after another and you have the file. It’s also [shown whole](#the-whole-file) at the end. The game ships with the engine, so you can play it straight away without typing any of it: `import { twoRooms } from '@brass-lantern/engine/worlds'`.
+
+## Two rooms
+
+```ts
+  startRoom: 'porch',
+  rooms: {
+    porch: {
+      name: 'Front Porch',
+      description: 'A creaky porch in front of an old house. A doormat lies at your feet.',
+      exits: {
+        north: { to: 'hall', door: 'front_door' },
+        in: { to: 'hall', door: 'front_door' },
+      },
+      listExits: ['north'],
+      items: ['doormat'],
+      npcs: [],
+      onEnter: [],
+      scenery: ['front_door'],
+    },
+    hall: {
+      name: 'Hall',
+      description: 'A dusty hall that smells of old books. The front door is south.',
+      exits: {
+        south: { to: 'porch', door: 'front_door' },
+        out: { to: 'porch', door: 'front_door' },
+      },
+      listExits: ['south'],
+      items: ['side_table'],
+      npcs: [],
+      onEnter: [],
+      scenery: ['front_door'],
+    },
+  },
+```
+
+- **`startRoom`** is where a new game begins.
+- **`exits`** map what the player types to where it goes. A plain string (`north: 'hall'`) is enough for an open way through; here each exit is an object naming a **`door`**, an item that has to be open before anyone passes. Several labels for the same way (`north`, `in`) are normal.
+- **`listExits`** is what the exit line shows. Without it, every label is listed.
+- **`scenery`** lists items that are present without being *in* the room: the door belongs to both rooms, so both name it, and it’s never listed or taken.
+- **`items`**, **`npcs`** and **`onEnter`** are required on every room, even when empty.
+
+## Things
+
+```ts
+  items: {
+    doormat: {
+      name: 'doormat',
+      aliases: ['mat'],
+      description: 'WELCOME, it says, unconvincingly.',
+      portable: false,
+      refusal: 'It’s nailed down. Somebody really wanted you welcome.',
+      tags: [],
+      scenery: true,
+      instead: { examine: [{ if: '!flag:found_key', then: 'find_key' }] },
+    },
+    key: { name: 'brass key', aliases: ['key'], description: 'Small, brass, a little green.', portable: true, tags: [] },
+    front_door: {
+      name: 'front door',
+      aliases: ['door'],
+      description: 'Solid oak, painted red a long time ago.',
+      portable: false,
+      tags: [],
+      door: true,
+      container: { openable: true, locked: true, key: 'key' },
+    },
+    side_table: {
+      name: 'side table',
+      aliases: ['table'],
+      description: 'A spindly side table.',
+      portable: false,
+      tags: [],
+      scenery: true,
+      surface: true,
+      contains: ['letter'],
+    },
+    letter: {
+      name: 'letter',
+      aliases: ['envelope', 'note'],
+      description: 'An envelope with your name on it, in your own handwriting.',
+      portable: true,
+      tags: [],
+      instead: { read: [{ then: 'read_letter' }] },
+    },
+  },
+```
+
+- **Every item has a `name`** (shown to players), a **`description`** (EXAMINE), says whether it’s **`portable`**, and has **`tags`** (labels for your own rules; `[]` is fine). **`aliases`** are other words for it. The world’s `items` is required too.
+- **`scenery: true`** on an item keeps it out of the room’s list of things (the description already mentions the mat). It’s still in the room’s `items`, so it can be examined. **`refusal`** is what TAKE says to something that isn’t portable.
+- **The door** is an item with `door: true` and a `container` block: it can be opened, it starts locked, and the `key` item unlocks it. UNLOCK DOOR WITH KEY and OPEN DOOR work with no rules at all.
+- **The mat hides the key.** An **`instead`** rule replaces what a verb normally does. A rule is `{ if, then }`: `if` is a [condition](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#conditions) (`!flag:found_key`, “the flag `found_key` isn’t set”), and `then` names an event to run. EXAMINE MAT runs the `find_key` event the first time; once `found_key` is set the rule’s `if` fails and EXAMINE prints the description as usual.
+- **The key starts nowhere.** It isn’t in any room’s `items`, so it’s offstage until an event moves it.
+- **The side table is a `surface`**: what’s on it is always visible and in reach, which is where the hall’s “Sitting on the side table is:” comes from. `contains` puts the letter there at the start.
+- **The letter ends the game** with an `instead` rule on READ.
+
+## What happens
+
+```ts
+  npcs: {},
+  dialogue: {},
+  flagLabels: {},
+  events: {
+    intro: ['You’re back at the old house at last. You’re sure you left the key somewhere obvious.'],
+    find_key: ['You lift a corner of the mat. Underneath: a brass key.', { set: 'found_key' }, { move: 'key', to: 'porch' }],
+    read_letter: ['“Dear me,” it begins. “If you’re reading this, you remembered the mat. Welcome home.”', { end: 'home' }],
+  },
+  endings: {
+    home: { lines: ['✨ You’re home.'], footer: ['Type RESTART to play again.'] },
+  },
+```
+
+- **`events`** are named lists of steps. A string prints; an object is an [effect](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#events-and-effects). `find_key` prints a line, sets a flag and moves the key onto the porch.
+- **`intro`** plays when a new game starts.
+- **`end`** plays one of the world’s **`endings`**: its lines, then the footer, and the game is over. A line starting with an emoji (✨) is shown as an event; [How lines are styled](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#how-lines-are-styled) has the rules.
+- **`npcs`, `dialogue` and `flagLabels`** are required. This game has no people, and its flags are set by effects rather than [bracket lines](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#bracket-lines-the-older-form), so they’re empty.
+
+## The whole file
+
+The three parts, assembled. The sections above leave out only what goes around them: the import, a comment, and `export const twoRooms: World = {` with its closing `};`. (The file in the repo also has `// #region` comments marking the three parts for this page. They change nothing, and they’re left out here.)
+
+**two-rooms.ts**
+```ts
+import type { World } from '@brass-lantern/engine';
+
+/**
+ * The smallest complete game: two rooms, a locked door, a hidden key and a
+ * way to win. Built step by step in docs/guide/building-worlds/two-rooms.md;
+ * tests/worlds/examples/two-rooms.test.ts plays it.
+ */
+export const twoRooms: World = {
+  startRoom: 'porch',
+  rooms: {
+    porch: {
+      name: 'Front Porch',
+      description: 'A creaky porch in front of an old house. A doormat lies at your feet.',
+      exits: {
+        north: { to: 'hall', door: 'front_door' },
+        in: { to: 'hall', door: 'front_door' },
+      },
+      listExits: ['north'],
+      items: ['doormat'],
+      npcs: [],
+      onEnter: [],
+      scenery: ['front_door'],
+    },
+    hall: {
+      name: 'Hall',
+      description: 'A dusty hall that smells of old books. The front door is south.',
+      exits: {
+        south: { to: 'porch', door: 'front_door' },
+        out: { to: 'porch', door: 'front_door' },
+      },
+      listExits: ['south'],
+      items: ['side_table'],
+      npcs: [],
+      onEnter: [],
+      scenery: ['front_door'],
+    },
+  },
+
+  items: {
+    doormat: {
+      name: 'doormat',
+      aliases: ['mat'],
+      description: 'WELCOME, it says, unconvincingly.',
+      portable: false,
+      refusal: 'It’s nailed down. Somebody really wanted you welcome.',
+      tags: [],
+      scenery: true,
+      instead: { examine: [{ if: '!flag:found_key', then: 'find_key' }] },
+    },
+    key: { name: 'brass key', aliases: ['key'], description: 'Small, brass, a little green.', portable: true, tags: [] },
+    front_door: {
+      name: 'front door',
+      aliases: ['door'],
+      description: 'Solid oak, painted red a long time ago.',
+      portable: false,
+      tags: [],
+      door: true,
+      container: { openable: true, locked: true, key: 'key' },
+    },
+    side_table: {
+      name: 'side table',
+      aliases: ['table'],
+      description: 'A spindly side table.',
+      portable: false,
+      tags: [],
+      scenery: true,
+      surface: true,
+      contains: ['letter'],
+    },
+    letter: {
+      name: 'letter',
+      aliases: ['envelope', 'note'],
+      description: 'An envelope with your name on it, in your own handwriting.',
+      portable: true,
+      tags: [],
+      instead: { read: [{ then: 'read_letter' }] },
+    },
+  },
+
+  npcs: {},
+  dialogue: {},
+  flagLabels: {},
+  events: {
+    intro: ['You’re back at the old house at last. You’re sure you left the key somewhere obvious.'],
+    find_key: ['You lift a corner of the mat. Underneath: a brass key.', { set: 'found_key' }, { move: 'key', to: 'porch' }],
+    read_letter: ['“Dear me,” it begins. “If you’re reading this, you remembered the mat. Welcome home.”', { end: 'home' }],
+  },
+  endings: {
+    home: { lines: ['✨ You’re home.'], footer: ['Type RESTART to play again.'] },
+  },
+};
+```
+
+## Play it
+
+You need Node 24 or later. In a new folder:
+
+```bash
+npm init -y
+npm pkg set type=module
+npm i @brass-lantern/engine
+```
+
+Save the file above as `two-rooms.ts`, and this beside it as `play.ts`:
+
+```ts
+import { createGame } from '@brass-lantern/engine';
+import { twoRooms } from './two-rooms.ts';
+
+const game = createGame(twoRooms);
+console.log(game.opening.join('\n'));
+for (const command of ['north', 'examine mat', 'take key', 'unlock door with key', 'open door', 'north', 'take letter', 'read letter']) {
+  console.log(`> ${command}`);
+  console.log(game.send(command).lines.join('\n'));
+}
+```
+
+```bash
+node play.ts
+```
+
+Node 24 and later run TypeScript files as they are, no compiler needed (`npx tsx play.ts` works too). `createGame` runs a world with no browser: `game.opening` is what the game says before the first command, and `game.send(line)` takes whatever a player would type and answers with its `lines`. No server or API key is needed. To skip the typing, import the shipped copy instead: `import { twoRooms } from '@brass-lantern/engine/worlds'`.
+
+It prints this, word for word (the test checks the same transcript):
+
+```
+You’re back at the old house at last. You’re sure you left the key somewhere obvious.
+📍 Front Porch
+A creaky porch in front of an old house. A doormat lies at your feet.
+Exits: north.
+> north
+The front door is closed.
+> examine mat
+You lift a corner of the mat. Underneath: a brass key.
+> take key
+Taken: brass key.
+> unlock door with key
+Unlocked.
+> open door
+Opened.
+> north
+📍 Hall
+A dusty hall that smells of old books. The front door is south.
+Sitting on the side table is:
+  A letter
+Exits: south.
+> take letter
+Taken: letter.
+> read letter
+“Dear me,” it begins. “If you’re reading this, you remembered the mat. Welcome home.”
+✨ You’re home.
+Type RESTART to play again.
+```
+
+**In the browser**, the same world plays in the terminal from `@brass-lantern/vue`: a styled window, like an old CRT screen, with the typing prompt, saves and the rest of what a player sees. The shortest way there is a new [Vite](https://vite.dev) app:
+
+```bash
+npm create vite@latest my-game -- --template vanilla-ts
+cd my-game
+npm i @brass-lantern/engine @brass-lantern/vue vue pinia
+```
+
+The template already has an `index.html` with `<div id="app">` that loads `src/main.ts`. Copy `two-rooms.ts` into `src/`, then replace everything in `src/main.ts` with:
+
+```ts
+import { mountGame } from '@brass-lantern/vue';
+import '@brass-lantern/vue/style.css';
+import './style.css';
+import { twoRooms } from './two-rooms.ts';
+
+mountGame('#app', {
+  cartridges: [{ kind: 'world', id: 'two-rooms', title: 'TWO ROOMS', world: twoRooms }],
+  storagePrefix: 'two-rooms',
+});
+```
+
+and everything in `src/style.css` with:
+
+```css
+html, body, #app { height: 100%; margin: 0; overflow: hidden; }
+```
+
+```bash
+npm run dev
+```
+
+Open the address it prints and the game boots. What the options mean:
+
+- **`cartridges`** are the games on offer. A cartridge with `kind: 'world'` is a world like this one; `id` names it (in its saves, for one), and `title` is what the menu shows. With one cartridge there’s no menu: the terminal boots straight into it.
+- **`storagePrefix`** names everything the game keeps in the browser (saves, the player’s theme), so two games on one site don’t share saves.
+- **The game fills `#app`**, which is why `style.css` gives it the whole window.
+
+Vite tells TypeScript what a `.css` import is (the template’s `vite/client` types), and it accepts the `.ts` ending on `./two-rooms.ts`, as Node does. Outside Vite, [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#put-a-game-on-a-page) says what to declare for the stylesheet, and covers themes and the rest of the options.
+
+Players won’t type exactly the commands above. “Look under the mat” or “use the key on the door” aren’t commands the engine can act on by itself, so with the [intent server](https://mrballistic.github.io/brass-lantern/guide/intent-server) running they can be mapped onto EXAMINE MAT and UNLOCK DOOR WITH KEY. Without it (as with `createGame`, which never uses it) the player gets a nudge to rephrase.
+
+## Where next
+
+- Give the game a person to talk to, hints and a score: [Snack Attack](https://mrballistic.github.io/brass-lantern/guide/your-first-world) shows all three.
+- Make the hall dark until you find a lamp: [darkness](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#darkness-and-death).
+- Every field, with its default: the [world schema](https://mrballistic.github.io/brass-lantern/reference/world-schema).

package/dist/docs/pages/guide/coding-agents.md

@@ -0,0 +1,120 @@
+# Coding agents
+
+Two ways to give a coding agent (Claude Code, Cursor, Codex and the like) what it needs to build a Brass Lantern world: the docs as one file, and a local MCP server that can also audit and play the world it writes.
+
+## The docs as one file
+
+The site publishes its documentation as markdown, built from the same pages you are reading.
+
+- [llms.txt](https://mrballistic.github.io/brass-lantern/llms.txt) is the index: a one-line summary and a link to every page. Each page also has a `.md` copy beside it (add `.md` to its address). Use this when the agent should fetch only the pages it needs.
+- [llms-full.txt](https://mrballistic.github.io/brass-lantern/llms-full.txt) is every page in one file, with the example worlds’ code inlined. Use this when the agent can take it all in one read: it then has the schema, the conditions, the effects and the recipes together.
+
+## The MCP server
+
+`@brass-lantern/mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io) server. It lets an agent close the loop on a world it is writing: **write** the world file, **audit** it, **play** a few commands to see how it actually reads, **fix** what turned up, and repeat. It also serves this version’s docs, so the agent reads the schema that matches the engine.
+
+### Install
+
+In Claude Code:
+
+```bash
+claude mcp add brass-lantern -- npx -y @brass-lantern/mcp
+```
+
+For any client that takes JSON config:
+
+```json
+{
+  "mcpServers": {
+    "brass-lantern": {
+      "command": "npx",
+      "args": ["-y", "@brass-lantern/mcp"]
+    }
+  }
+}
+```
+
+Node 24 or later. World paths in tool calls are relative to the directory the client starts the server in (normally your project), or absolute. Worlds must be inside that directory or one you allow with `--root <dir>`, which you can repeat and which is relative to the same directory:
+
+```bash
+claude mcp add brass-lantern -- npx -y @brass-lantern/mcp --root ../shared-worlds
+```
+
+### The tools
+
+**`audit_world`** checks a world file the way the engine’s `auditWorld` does: exits that go nowhere, conditions that don’t parse, effects naming things that don’t exist, unmapped flag labels and more.
+
+Inputs: `path` (a `.ts`, `.mts`, `.js` or `.mjs` module) and optionally `export` (which export is the world; by default the default export, else the only world-shaped one).
+
+```json
+{ "path": "src/worlds/office.ts" }
+```
+
+```text
+World: default in /project/src/worlds/office.ts
+Engine: @brass-lantern/engine 2.3.0 (the project’s)
+Size: 1 room, 0 items, 0 characters, 0 events
+
+1 problem:
+- room hall: exit north goes nowhere (“nowhere”)
+```
+
+**`play`** starts a fresh game and types each command as a player would, with no LLM. It is stateless: every call begins at the start, and the game is seeded (default seed 1, or pass `seed`) so a run repeats exactly. To continue a session, send the whole command list again. At most 500 commands run per call, and a transcript over 2,000 lines keeps its opening and its last 200 lines, with a note where the middle was cut. The game stops when it ends.
+
+Inputs: `path`, optionally `export`, `commands` (the lines to type, in order) and optionally `seed`.
+
+```json
+{ "path": "src/worlds/office.ts", "commands": ["open drawer", "take key", "north"] }
+```
+
+````text
+World: default in /project/src/worlds/office.ts
+Engine: @brass-lantern/engine 2.3.0 (the project’s)
+Seed: 1
+
+…the opening…
+> open drawer
+You open the drawer. Inside is a brass key.
+> take key
+Taken.
+> pull the lever with feeling
+[not understood by the parser: “pull the lever with feeling”. With the intent server running, an LLM would get a chance to read it.]
+…
+
+Final state:
+```json
+{
+  "room": "Lobby (lobby)",
+  "inventory": ["brass key"],
+  "flags": [],
+  "score": 0,
+  "moves": 2,
+  "gameOver": false
+}
+````
+
+The “not understood by the parser” note marks input the regex parser can’t read. A real player with the [intent server](./intent-server) would have it sent to the LLM; here nothing is, so treat the note as “this phrasing needs a verb, an alias or a rule” rather than as a bug. The final state includes `score`, from the engine’s `currentScore`. Notes (such as “Game over after 3 of 5 commands.”) come in a blank-line-separated block just before “Final state:”. Two things depend on the engine in use: a project engine older than 2.3.0 has no `currentScore`, so `score` comes from the world’s `score` variable, or is `null` if the world keeps none; and an engine without the parser helpers skips the “not understood” note. Neither is a fault in the world.
+
+**`docs`** serves the documentation bundled with the server. With no arguments it returns the index of pages; with `page` (such as `reference/world-schema`) one page’s markdown; with `query` (such as `timers fuses`) the best-matching sections. If you give both, `page` wins.
+
+```json
+{ "query": "timers fuses" }
+```
+
+```text
+…the best-matching sections, each with its page path…
+```
+
+### Which engine
+
+The server audits and plays a world with the engine the world’s own project uses, so a project on 2.2 is checked by 2.2’s rules. It looks for `@brass-lantern/engine` from the world file. If the project has none, the server uses the engine bundled with it, and the reply says “bundled with the MCP server” without further comment. If the project’s engine is found but can’t be used (it can’t be resolved or fails to import, or lacks `createGame` or `auditWorld`), the server falls back to the bundled one and adds a note saying why. Every reply states the engine version and whose it is, so you always know what you were checked against.
+
+A world file is re-read on every call, so an edit shows on the next one. That covers `.ts` and `.mts` worlds and the project files they import (loaded with no module cache), and `.mjs` and `.js` worlds along with the project files they import. Packages a world imports stay cached and are not reloaded.
+
+### Safety and limits
+
+The server **runs the world module it is pointed at**, with your permissions, the same way your test runner runs your tests. Point it at code you trust. It speaks only over local stdio and makes no network calls of its own. A world file is only loaded when it is inside the directory the server started in or one you passed with `--root`, compared after resolving symlinks; anything else is refused with a message naming `--root`. That check confines which world file is loaded, not what the module then imports or does: any module inside an allowed directory can be run. It is not a sandbox.
+
+A world’s console output (`console.log`, `dir`, `table` and the rest) goes to stderr, so it can’t break the protocol.
+
+Two limits to know: a world whose script loops forever hangs the server until the client restarts it, and a world that calls `process.exit()` ends the server the same way. There is no per-call timeout yet.

package/dist/docs/pages/guide/deploying.md

@@ -0,0 +1,56 @@
+# Deploying
+
+A Brass Lantern game is a static site, plus the intent server if you want loose phrasing understood. If you use the packages in your own app ([Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library)), deploy your app the way you already do and mount `intentRoute` in your backend; this page is about the repo’s demo site and server.
+
+## Static only
+
+`npm run build` writes `apps/site/dist/`, which any static host can serve: GitHub Pages, Netlify, an S3 bucket, a web server. Without an intent server the game still plays on the regex parser alone; players just get a “didn’t understand” reply where the server would have helped.
+
+To serve from a subpath, set the base at build time:
+
+```bash
+VITE_BASE=/my-game/ npm run build
+```
+
+That’s how the [demo](https://mrballistic.github.io/brass-lantern/demo/) is published: `.github/workflows/pages.yml` builds these docs and the demo together and deploys them to GitHub Pages on every push to `main`.
+
+## With the intent server
+
+The SPA calls `/api/parse-intent` on its own origin, so serve both from one host and proxy `/api/` to the server:
+
+```apache
+# Apache (mod_proxy, mod_proxy_http)
+DocumentRoot /var/www/my-game
+<Directory /var/www/my-game>
+    FallbackResource /index.html
+</Directory>
+ProxyPass        /api/  http://127.0.0.1:3001/api/
+ProxyPassReverse /api/  http://127.0.0.1:3001/api/
+```
+
+```nginx
+# nginx
+root /var/www/my-game;
+location / { try_files $uri /index.html; }
+location /api/ { proxy_pass http://127.0.0.1:3001; }
+```
+
+Build and run the server:
+
+```bash
+npm ci && npm run build -w @brass-lantern/server
+GEMINI_KEY=… NODE_ENV=production node packages/server/dist/index.js
+```
+
+**Install the dev dependencies**
+The repo’s server imports `express`, which this repo keeps as a dev dependency (the published package treats it as an optional peer). Don’t install with `npm ci --omit=dev` before running `node packages/server/dist/index.js`: the server won’t start. Install everything, or write your own small app around `intentRoute` and install `express` yourself.
+
+In production, use a process manager (systemd, pm2, a container) and keep the key in an environment file only that service can read. The server drains in-flight requests on SIGTERM, so rolling restarts don’t drop players’ commands.
+
+## Suggestions from running one
+
+- **Cache hashed assets forever and `index.html` never**, and upload the assets before `index.html`. Then a deploy never serves a page whose scripts haven’t arrived yet.
+- **Deploy as a user that can only write the site**, not an admin. A CI deploy key is as powerful as the account it logs into.
+- **Pin your CI actions to commit SHAs**, and keep deploy secrets in a deployment environment that only release tags can use.
+- **Check that the key never reaches the bundle.** A CI step that greps `dist/` for `AIza` fails the build if it ever does.
+- **Analytics (the demo site):** set `VITE_GA_MEASUREMENT_ID` at build time to turn on its GA4 reporting. The consent banner appears only then. In your own app, analytics are whatever you wire to `GameOptions.analytics`.

package/dist/docs/pages/guide/getting-started.md

@@ -0,0 +1,72 @@
+# Getting started
+
+Brass Lantern is a small engine for classic parser text adventures (*go north*, *take lamp*, *give the mug to Gary*) that runs in the browser inside a CRT terminal. You write a game as data; the engine runs it.
+
+It also plays **Z-machine story files**, the format Infocom’s games shipped in, in the same terminal.
+
+It comes with five cartridges: **Snack Attack**, a three-room world that exists to show the engine off, **Zork I, II and III**, and **Zork I rebuilt natively** on the engine. [Play them](https://mrballistic.github.io/brass-lantern/demo/), then come back. For a full-length game built on the engine, try [Office Space: The Text Adventure](https://initech.mrballistic.com).
+
+## Use it in your app
+
+Brass Lantern is on npm as three library packages (the engine, a Vue terminal and an optional intent server) plus an MCP server for coding agents. [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library) covers installing them, mounting a game, themes, running headless in Node and wiring the intent server.
+
+```bash
+npm i @brass-lantern/engine @brass-lantern/vue vue pinia
+```
+
+## Run the demo from the repo
+
+You need Node 24 or later.
+
+```bash
+git clone https://github.com/mrballistic/brass-lantern.git
+cd brass-lantern
+npm install
+npm run dev        # http://localhost:5173
+```
+
+The terminal boots to the cartridge menu; type `1` for Snack Attack, `2`–`4` for Zork I–III, or `5` for the native Zork I. All are fully playable offline: the regex parser handles every command the engine knows, and Zork has its own parser. Loose phrasing (“make that thing stop beeping”) needs the optional [intent server](https://mrballistic.github.io/brass-lantern/guide/intent-server).
+
+## What’s in the box
+
+```
+packages/
+  engine/          @brass-lantern/engine: the engine, the regex parser, fuzzy matching,
+                   line styling, createGame, auditWorld, the story-file runtime
+                   (zmachine/), and the bundled worlds (worlds/)
+  vue/             @brass-lantern/vue: the terminal, the boot sequence, the game stores,
+                   themes, mountGame, and the CRT stylesheet
+  server/          @brass-lantern/server: the intent server (parseIntent, intentRoute),
+                   plus the small Express app the repo runs (src/index.ts)
+apps/
+  site/            the demo: app.config.ts lists the cartridges, main.ts mounts the game,
+                   apps/site/public/stories/ holds the Zork trilogy and its licenses
+docs/              this site (npm run docs:dev)
+scripts/           the consumer smoke test, the glkapi vendoring
+```
+
+Each package has its own tests; `packages/engine/src/types/world.ts` is the world schema, with a comment on every field.
+
+## Make it yours
+
+In your own app, the cartridges are just the `cartridges` you pass to `mountGame` ([Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library)). In the repo, everything that makes the demo *a particular game collection* is in `apps/site/src/app.config.ts`:
+
+```ts
+export const cartridges: Cartridge[] = [
+  { kind: 'world', id: 'snack-attack', title: 'SNACK ATTACK', world: tutorial },
+  { kind: 'zcode', id: 'zork1', title: 'ZORK I', story: 'stories/zork1.z3', format: 'Z-machine v3' },
+  { kind: 'zcode', id: 'zork2', title: 'ZORK II', story: 'stories/zork2.z3', format: 'Z-machine v3' },
+  { kind: 'zcode', id: 'zork3', title: 'ZORK III', story: 'stories/zork3.z3', format: 'Z-machine v3' },
+  { kind: 'world', id: 'zork1-native', title: 'ZORK I · NATIVE', world: zork1 },
+];
+export const appName = 'BRASS LANTERN';
+export const storagePrefix = 'brass-lantern';
+```
+
+Add your own world as a cartridge (and remove the others if you like: with one cartridge there’s no menu). [Building worlds](https://mrballistic.github.io/brass-lantern/guide/building-worlds/) walks through writing one, from two rooms up; [Playing story files](https://mrballistic.github.io/brass-lantern/guide/z-machine) covers Z-machine cartridges.
+
+## For coding agents
+
+The docs also come as plain markdown for agents and LLM tools. [llms.txt](https://mrballistic.github.io/brass-lantern/llms.txt) indexes every page, each page has a `.md` copy beside it, and [llms-full.txt](https://mrballistic.github.io/brass-lantern/llms-full.txt) is all of it in one file, with the example worlds’ code inlined. Point an agent at llms-full.txt and it has the schema, the conditions, the effects and the recipes in one read. There is also a local MCP server that lets an agent audit and play the world it is writing; [Coding agents](https://mrballistic.github.io/brass-lantern/guide/coding-agents) covers both.
+
+Working on Brass Lantern itself? [CONTRIBUTING.md](https://github.com/mrballistic/brass-lantern/blob/main/CONTRIBUTING.md) has the checks to run before a pull request.