Consolidate engine docs and naming

README.md

@@ -14,16 +14,19 @@ npm run build
 npm run dev
 ```
 
-The web app starts on `http://localhost:3000` when launched through `src/index.ts` or `dist/index.js`. The lower-level server module defaults to `3001` when started directly. Set `PORT` to choose a port; the server will try the next few ports if the requested one is already in use.
+`npm run dev` and `npm run start` use `DEFAULT_GAME_ENGINE` from `.env` to choose the active engine. Supported values are `ink`, `yaml`, and `zcode`. The engine-specific scripts remain available when you want to bypass the default.
+
+Set `PORT` to choose a port; the server will try the next few ports if the requested one is already in use. Current engine defaults are YAML `3001`, Z-code `3002`, and Ink `3003` before port fallback.
 
 ## Commands
 
 ```powershell
 npm run dev       # Start the web UI through ts-node/nodemon
+npm run start     # Build/run the configured default engine from dist/
 npm run dev:ink   # Start the Ink engine server, watch ink source, compile on restart
 npm run dev:yaml  # Start the YAML engine server
-npm run dev:zork  # Start the Z-code/Zork engine server
-npm run start     # Run the compiled web server from dist/
+npm run dev:zcode # Start the Z-code engine server
+npm run start:ink # Build and run the compiled Ink engine server
 npm run build     # Compile TypeScript
 npm run test      # Run Jest tests
 npm run lint      # Run ESLint on src/
@@ -31,13 +34,14 @@ npm run start:cli # Run the CLI interface
 npm run dev:cli   # Run the CLI interface through ts-node/nodemon
 ```
 
-Each game engine also has an inspect command for debugger work: `npm run dev:ink:inspect`, `npm run dev:yaml:inspect`, and `npm run dev:zork:inspect`.
+Each game engine also has `:debug` and `:inspect` variants. `:debug` enables engine-specific diagnostic logging. `:inspect` starts Node with the inspector and currently also enables that engine's debug flag, so it is the combined debug-plus-inspector mode.
 
 ## Configuration
 
 Environment variables are loaded from `.env`.
 
 - `PORT`: preferred web server port.
+- `DEFAULT_GAME_ENGINE`: engine used by `npm run dev` and `npm run start`; one of `ink`, `yaml`, or `zcode`.
 - `DEFAULT_WORLD_FILE`: YAML world file to load. Defaults to `./data/worlds/example_world.yml`.
 - `OPENROUTER_API_KEY`: API key for LLM command interpretation.
 - `OPENROUTER_MODEL`: OpenRouter model name.
@@ -57,7 +61,7 @@ The placeholder server API supports:
 - `getSaveGames()`
 - `isGameRunning()`
 
-Save slots are positive integers. In the current placeholder implementation, save availability is per socket session and is lost on reload. Loading a save starts the demo content like `newGame()`.
+Save slots are positive integers. Save behavior is engine-specific: the Ink client/server path persists Ink state, client history, choices, media state, and playback position for browser save/load; YAML and Z-code persistence still need regression testing and cleanup.
 
 ## Web Client
 
@@ -97,7 +101,7 @@ The train stops at Eibenreith.
 
 Glossary markup is a normal story tag scoped to the paragraph/block it is attached to. The UI finds every matching visible instance of the term in that right-page block and adds a hover/focus note. The tag itself is not displayed, is not sent to TTS, and is ignored by choices and command history. Avoid raw Ink control characters in the explanation; `|`, `{`, and `}` must be escaped in Ink as `\|`, `\{`, and `\}` if they are needed literally.
 
-Canonical block/media/control tags use Ink-style `#` syntax. In Ink these are real Ink tags. In YAML and Zork narrative output, leading `#...` lines are parsed by the server into the same structured `StoryTag` objects before reaching the client. The browser only consumes structured `TurnResult` objects.
+Canonical block/media/control tags use Ink-style `#` syntax. In Ink these are real Ink tags. In YAML and Z-code narrative output, leading `#...` lines are parsed by the server into the same structured `StoryTag` objects before reaching the client. The browser only consumes structured `TurnResult` objects.
 
 Tag format:
 
@@ -173,6 +177,10 @@ Game-state and player-message tags:
 
 `#score[...]` marks an intended ending and opens a localized ending popup when the turn reaches `inputMode: end`. `#error[...]` marks an unrecoverable ending and opens an error popup. If an Ink story runs out of content without an explicit `#score[...]` or `#error[...]`, the Ink engine emits an `#error[...]` tag. `#achievement[...]` and `#alert[...]` open localized queued popups while the game continues.
 
+## Architecture Documentation
+
+`SPECIFICATION.md` is the canonical architecture and implementation specification. `TODO.md` is the canonical progress and remaining-work list. The former loose Ink and Z-code inclusion notes have been folded into those two files.
+
 ## Assets
 
 - `public/sounds/`: sound effects referenced by `#sfx[file]` tags.
@@ -215,7 +223,7 @@ The right page history is line-addressed rather than natively scrolled. The page
 
 ### 2026-05-14
 
-- Consolidated usage, markup, and architecture documentation into `README.md` and `CLIENT_TODO.md`.
+- Consolidated usage, markup, and architecture documentation into `README.md` and `TODO.md`.
 - Added no-cache static serving and module URL cache busting so browser reloads pick up JS changes reliably during development.
 - Fixed module loader dependency ordering so modules are initialized only after their declared dependencies are ready.
 - Added the placeholder game API for `newGame`, `loadGame`, `saveGame`, `hasSaveGame`, `getSaveGames`, and `isGameRunning`.