Add two-stage charged-crystal demo and original art set.

tasks/plan.md

@@ -0,0 +1,122 @@
+# Implementation Plan: Magic Factory Demo
+
+## Overview
+
+Build a small but presentable 2.5D factory game demo in Godot. The player will place belts, machines, mana pipes, and a configurable bridge arm to complete a two-stage magical production chain. The demo uses a coherent CC0 asset pack from the beginning, while all gameplay state remains independent from scene nodes so large-factory performance work is not blocked by the presentation layer.
+
+## Demo promise
+
+The first public-facing slice starts on a small floating factory site and ends when the player continuously produces charged crystals. It must feel like a game rather than an engineering benchmark: it has a title screen, readable construction controls, visible production, machine status feedback, a short objective sequence, sound-ready hooks, and a clear completion state.
+
+## Architecture decisions
+
+- Godot 4.7.1 stable, standard Windows build, with GDScript for the first playable slice.
+- 3D world with an orthographic camera and fixed grid: 2.5D presentation without 2D simulation assumptions leaking into rendering.
+- Simulation advances on a fixed integer tick and is stored in plain data keyed by integer IDs. Scene nodes mirror state; they are not authoritative gameplay objects.
+- Machines do not poll every rendered frame. They wake for exact state-changing events such as input arrival, output space, recipe completion, and mana-network changes.
+- The first logistics route is belt-to-machine. Bridge arms belong to machines and select explicit belt endpoints; there is no independent inserter entity layer.
+- Kenney Factory Kit 3.0 is the initial visual base. Its source archive, CC0 license, URL, version, and acquisition date stay in the repository.
+- Performance tooling is a developer-only mode inside the demo, not the user-facing premise.
+
+## Dependency graph
+
+```text
+Godot project + licensed asset pack
+             |
+             v
+2.5D world + camera + grid
+             |
+             v
+fixed-tick world data + commands
+             |
+      +------+------+
+      |             |
+      v             v
+belt transport   build controls
+      |             |
+      +------+------+
+             v
+machine production
+             |
+      +------+------+
+      |             |
+      v             v
+mana network    bridge arm
+      |             |
+      +------+------+
+             v
+objective flow + polish
+             |
+             v
+stress scene + release check
+```
+
+## Task list
+
+### Phase 1: Playable foundation
+
+- [x] Task 1: Register tools and third-party assets
+- [x] Task 2: Create a launchable 2.5D world
+- [x] Task 3: Add grid construction controls
+- [x] Task 4: Run one belt-to-machine production chain
+
+### Checkpoint: First playable loop
+
+- [x] Project opens without import errors in Godot 4.7.1
+- [x] Player can place a belt and machine with mouse controls
+- [x] A visible item travels into a machine and becomes a visible output item
+- [x] Simulation outcome is independent from render frame rate
+
+### Phase 2: Distinctive game systems
+
+- [x] Task 5: Add mana supply and pipe connectivity
+- [x] Task 6: Add configurable bridge arms
+- [x] Task 7: Add status inspection and objective guidance
+- [x] Task 8: Add a second recipe and demo completion state
+
+### Checkpoint: Demo identity
+
+- [x] Player can diagnose every stopped machine from the UI
+- [x] Bridge arms can cross several belt lanes without becoming standalone ticking entities
+- [x] Mana shortage visibly stops and later resumes production
+- [x] The first complete production chain can be built from a fresh game
+
+### Phase 3: Presentation and scale guardrails
+
+- [ ] Task 9: Add menu, save snapshot, audio hooks, and visual polish
+- [ ] Task 10: Add deterministic stress generation and metrics
+- [ ] Task 11: Package a Windows demo build
+
+### Checkpoint: Demo ready
+
+- [x] Fresh player can reach continuous charged-crystal production
+- [ ] CC0 assets have traceable license records
+- [ ] Fixed-seed automated runs produce identical state hashes
+- [ ] Stress mode reports simulation and rendering costs separately
+- [ ] Windows build launches on a clean path outside the editor
+
+## Explicitly deferred
+
+- Combat, enemies, character control, story campaign, research tree, procedural world generation, multiplayer, mod loading, pressure-based fluid simulation, final commissioned art, and a native C++ simulation extension.
+- C++ is reconsidered only after the representative stress workload identifies a measured hot path that the data layout and scheduler cannot solve in GDScript.
+
+## Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---:|---|
+| Free assets make the game look generically industrial | High | Use one coherent pack, recolor materials, and add a small original mana/rune visual layer before adding more packs. |
+| Scene-node architecture grows with factory size | High | Keep authoritative simulation in arrays/dictionaries and render only visible state. |
+| Bridge-arm setup is tedious | High | Validate source/destination selection in the first production chain and add strong previews and error feedback. |
+| Mana pipe rules become a second fluid simulator | Medium | Demo supports capacity and connectivity, but no pressure, temperature, or free-form fluid physics. |
+| Early polish hides an unscalable core | High | Ship a stress generator and deterministic counters before expanding the recipe catalog. |
+
+## Open decisions with safe defaults
+
+- Reference hardware: use the current development PC until a minimum target specification is chosen.
+- Art direction: Kenney industrial forms with dark stone, brass, cyan mana, and violet high-tier energy.
+- Input: mouse and keyboard first; controller support deferred.
+- Distribution: Windows desktop first.
+
+## Post-demo progression
+
+The research tree remains outside the Tasks 1–11 demo scope, but its current full-game design is specified in `docs/tech-tree-v0.2.md`. Data and implementation work is dependency-ordered in `tasks/tech-tree-plan-v0.2.md` and `tasks/tech-tree-todo-v0.2.md`; it starts only after the demo-ready checkpoint unless the project scope is explicitly changed.

tasks/recipe-editor-plan.md

@@ -0,0 +1,64 @@
+# Implementation Plan: Planner Recipe Workbench
+
+## Overview
+
+Build a local, planner-facing recipe workbench whose JSON book becomes the shared authority for item, machine, and recipe balance. It must make the dependency tree understandable, allow safe edits without touching code, report broken references and loops immediately, and save recoverable revisions back into the project.
+
+## Architecture decisions
+
+- `data/recipe-book.json` is the editable authority; the browser interface does not hide a second copy.
+- The editor is dependency-free HTML/CSS/JavaScript so the planner can launch it with one Windows shortcut.
+- A localhost-only helper saves to the fixed data path and creates a timestamped backup before replacement.
+- Import/export remains available when the helper is not running.
+- The graph is generated from item-to-recipe and recipe-to-item references; positions are presentation state, not balance data.
+- All mutations pass through one command history so undo/redo, validation, autosave draft, and dirty-state reporting stay consistent.
+
+## Task list
+
+### Phase 1: Authority data
+
+- [x] Define the recipe-book schema
+- [x] Seed a complete first-warp recipe path and representative postgame exchanges
+- [x] Add structural and balance validation rules
+
+### Checkpoint: Data
+
+- [x] Every recipe input/output references an existing item
+- [x] Every recipe machine, biome, stage, and unlock technology is known
+- [x] First-warp production has a traceable upstream route
+
+### Phase 2: Planner interface
+
+- [x] Add searchable item/recipe/machine navigation
+- [x] Add focus and full-tree graph views with pan, zoom, and selection
+- [x] Add editable inspector forms and repeatable input/output rows
+- [x] Add route summaries and issue navigation
+
+### Checkpoint: Editing
+
+- [x] Changing an amount updates the tree and balance summary immediately
+- [x] Adding or deleting a reference cannot fail silently
+- [x] Undo/redo restores complete book states
+
+### Phase 3: Persistence and handoff
+
+- [x] Add one-click Windows launcher and local save endpoint
+- [x] Create backups on every direct save
+- [x] Add JSON import/export and draft recovery
+- [x] Document the planner workflow
+
+### Checkpoint: Complete
+
+- [x] Browser interaction and visual layout verified at desktop and narrow widths
+- [x] Direct save followed by reload returns identical data
+- [x] Automated tests cover schema, references, cycles, and critical first-warp ingredients
+
+## Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---:|---|
+| Large global graph becomes unreadable | High | Default to selected-node neighborhood; keep full tree as an explicit mode |
+| Planner accidentally breaks runtime IDs | High | Warn before ID rename, update references automatically, and validate before save |
+| Browser storage is mistaken for a real save | High | Persistent dirty indicator; direct save or exported file is the only committed state |
+| Random recipes cannot fit ordinary amount fields | High | Outputs support amount, min/max, chance, and weight in one schema |
+| Tool data diverges from the game | High | Runtime integration must consume the same JSON or generated resources from it |

tasks/recipe-editor-todo.md

@@ -0,0 +1,11 @@
+# Planner Recipe Workbench Tasks
+
+- [x] RE1: Define `recipe-book.json` and its schema.
+- [x] RE2: Seed mainline magical-law recipes through first warp.
+- [x] RE3: Implement searchable catalogs and graph navigation.
+- [x] RE4: Implement item, recipe, and machine inspectors.
+- [x] RE5: Implement validation, issue navigation, and dependency-cycle detection.
+- [x] RE6: Implement undo, redo, draft recovery, import, export, and direct save.
+- [x] RE7: Add a localhost-only launcher with save backups.
+- [x] RE8: Verify browser layout, interactions, and save round-trip.
+- [ ] RE9: Connect Godot runtime import after the simulation content model is implemented.

tasks/tech-tree-plan-v0.2.md

@@ -0,0 +1,104 @@
+# Implementation Plan: Magical-Law Progression v0.2
+
+## Overview
+
+Implement the progression in `docs/tech-tree-v0.2.md` as a sequence of playable magical-law experiments. The highest-risk mechanic—the portal's bounded random matter exchange—is prototyped before large content production. Once that proves fun, each ecology zone adds one distinct simulation law and one automated proof loop, culminating in a player-built dimensional gate and post-victory entropy economy.
+
+## Architecture decisions
+
+- Existing belts, mana pipes, bridge endpoints, fixed ticks, and event wakeups remain the physical substrate.
+- A biome law changes simulation through explicit data/state contracts; it cannot reach into arbitrary scene nodes.
+- Probability uses deterministic seeded result bags over mass batches. Saves preserve the active bag and seed so reload cannot reroll outputs.
+- Failure states are recoverable resources or paused machines on standard difficulty, never silent deletion.
+- Research proofs are produced by satisfying observable state sequences, not by renaming ordinary assembly recipes.
+- Boundary crossings are explicit logistics nodes. The visible map stays continuous while the transport graph remains partitioned.
+- First warp is deterministic once its conditions are met. Random exchange begins immediately after victory.
+
+## Dependency graph
+
+```text
+M1 portal fun prototype ------+
+                              |
+M2 biome-law contract --------+----> M3 catalog + validator ----> M4 proof runtime/UI/save
+                                                                  |
+                                                                  v
+M5 runic opening -> M6 life/death -> M7 ember -> M8 mirror -> M9 first warp
+                                                                    |
+                                                                    v
+                                                         M10 postgame portal loop
+                                                                    |
+                                                                    v
+                                                           M11 pacing proof
+```
+
+## Task list
+
+### Phase 1: Prove the risky fun
+
+- [ ] M1: Prototype bounded random exchange, sorting, entropy, and recovery
+- [ ] M2: Define biome-law and boundary-crossing contracts
+- [ ] M3: Load and validate the 80-node v0.2 catalog
+- [ ] M4: Implement experiment-driven research proofs, UI, and saving
+
+### Checkpoint: Core hypothesis
+
+- [ ] A ten-minute portal toy creates at least two meaningful strategies: stable targeting and high-entropy throughput
+- [ ] Reloading cannot reroll a result bag
+- [ ] Each planned ecology law has an isolated state model and a recoverable failure path
+- [ ] Mainline graph is acyclic and contains all five magical verbs
+
+### Phase 2: Playable ecology progression
+
+- [ ] M5: Deliver the old-kingdom runic opening
+- [ ] M6: Deliver forest and undead zones in either order
+- [ ] M7: Deliver the life/death merge and ember-state loop
+- [ ] M8: Deliver mirror folding, visible probability, and identity anchoring
+
+### Checkpoint: Magic identity
+
+- [ ] A stripped-art test can distinguish all four external zones by rules alone
+- [ ] A starting-zone blueprint cannot run unchanged in another zone
+- [ ] Every proof line can be automated and exposes a precise stop reason
+- [ ] Life and death routes remain order-independent and converge without duplicate blockers
+
+### Phase 3: Victory and continuation
+
+- [ ] M9: Deliver the twelve-segment gate, synchronized ritual, and first-warp achievements
+- [ ] M10: Turn the opened gate into the postgame matter-exchange and paradox-research loop
+
+### Checkpoint: Complete loop
+
+- [ ] Completing G09 alone does not win; the walker construct must actually cross the aperture
+- [ ] First warp has no random failure
+- [ ] Continuing after victory immediately exposes useful portal production
+- [ ] Portal exchange reduces one resource pressure while measurably increasing sorting, buffering, entropy, or mana work
+
+### Phase 4: Timing proof
+
+- [ ] M11: Instrument and tune the expert and normal routes
+
+### Checkpoint: Release candidate
+
+- [ ] Expert-route P50 ≤ 7:15 and P90 ≤ 8:00
+- [ ] Experienced first-play P50 is 18–21 hours and P75 ≤ 24:00
+- [ ] The expert route still demonstrates growth, decay, three-state conversion, echo separation, and four-anchor synchronization
+
+## Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---:|---|
+| Random exchange feels punitive or unplannable | Critical | Prototype first; use bounded bags, visible ranges, bias controls, and recyclable outcomes |
+| Ecology laws become four unrelated minigames | High | Keep common item tags, mana frequencies, proof records, and boundary-node interfaces |
+| Magical layouts become tedious pattern copying | High | Ship fixed 3×3/5×5 templates with snapping and previews |
+| Portal becomes strictly better than gathering | High | Cap early usable mass at 90% and exact targeting at 65%; charge entropy and catalysts |
+| Eight-hour play skips the interesting systems | Critical | Validate the mandatory closure and time the five explicit mechanic demonstrations |
+| Region effects cause per-cell/per-frame cost | High | Recompute zone membership on construction and wake entities only when law state changes |
+
+## Explicitly deferred
+
+- Full combat and tower-defense balance
+- Procedurally generated infinite biome types
+- Multiple full-sized playable dimensions
+- Freehand rune drawing
+- Irreversible corruption or permanent random destruction on standard difficulty
+

tasks/tech-tree-plan.md

@@ -0,0 +1,114 @@
+# Implementation Plan: Full Technology Progression (superseded)
+
+> Superseded by `tasks/tech-tree-plan-v0.2.md`. Retained only as a record of the rejected factory-reskin direction.
+
+## Overview
+
+Turn the design in `docs/tech-tree-v0.1.md` into a data-driven research and progression system after the current demo loop is stable. The implementation proceeds in playable vertical slices: first load and validate the catalog, then make each era playable from mining through research unlock, and finally add the heart-furnace victory loop and pacing telemetry. This is post-demo scope and does not change the completion bar for Tasks 1–11 in `tasks/plan.md`.
+
+## Architecture decisions
+
+- The CSV is a design interchange file, not runtime authority. Runtime content should use a typed Godot `Resource` or equivalent structured data generated from the same identifiers.
+- Technologies, recipes, buildings, UI labels, save data, and achievements reference stable IDs; display names remain localizable data.
+- Research is fixed-tick and event-driven like the current machine simulation. A lab wakes on input, queue, completion, or unlock changes rather than polling independently each frame.
+- Unlock evaluation lives in the simulation layer. UI only displays state and submits commands.
+- Every era is delivered as a complete loop: resource access → processing → research material → gate technology → visible objective.
+- The 8/24-hour targets are verified by route simulation and instrumented playtests, not inferred from green unit tests.
+
+## Dependency graph
+
+```text
+TT1 catalog contract
+        |
+        +----> TT2 graph/cost validator
+        |
+        v
+TT3 research runtime ----> TT4 UI + save
+        |
+        v
+TT5 T0/T1 slice -> TT6 T2 slice -> TT7 T3 slice -> TT8 T4 slice -> TT9 T5 + victory
+                                                              |              |
+                                                              +------>-------+
+                                                                     v
+                                                          TT10 optional/postgame
+                                                                     |
+                                                                     v
+                                                          TT11 telemetry/tuning
+```
+
+## Task list
+
+### Phase 1: Data and rules
+
+- [ ] TT1: Define stable technology, recipe, building, and unlock IDs
+- [ ] TT2: Add dependency validation and route-cost simulation
+- [ ] TT3: Implement fixed-tick research runtime
+- [ ] TT4: Add research UI, queue commands, and save state
+
+### Checkpoint: Research foundation
+
+- [ ] The full catalog loads with no duplicate, missing, cyclic, or role-invalid dependency
+- [ ] A headless test researches a node by consuming exact item counts
+- [ ] Save/load preserves completed and partial research exactly
+
+### Phase 2: Early playable progression
+
+- [ ] TT5: Deliver T0/T1 from repair milestones to automated cyan tablets
+- [ ] TT6: Deliver T2 mana-logistics and ether-fluid introduction
+
+### Checkpoint: Early game
+
+- [ ] A fresh run reaches crimson-tablet production without debug spawning
+- [ ] Existing belt, mana-pipe, and bridge-arm behavior remains deterministic
+- [ ] Every stopped lab or production machine exposes a readable reason
+
+### Phase 3: Midgame scale
+
+- [ ] TT7: Deliver T3 alchemy, precision construction, and leyline survey
+- [ ] TT8: Deliver T4 cross-island shipping, phase metallurgy, and emerald tablets
+
+### Checkpoint: Midgame
+
+- [ ] At least one required resource must arrive from another island
+- [ ] Violet and emerald recipes exercise the intended multi-stage chains
+- [ ] A reference factory meets the normal and expert tablet-rate targets
+
+### Phase 4: Endgame and continuation
+
+- [ ] TT9: Deliver T5 source extraction, heart furnace, timed ignition, and achievements
+- [ ] TT10: Add comfort, warding, and repeatable postgame branches
+
+### Checkpoint: Complete progression
+
+- [ ] Mainline can finish without researching any O-role node
+- [ ] Completing G13 alone cannot trigger victory
+- [ ] First stable ignition records one authoritative completion time and unlocks postgame research
+
+### Phase 5: Pacing proof
+
+- [ ] TT11: Add route telemetry, benchmark saves, and 8/24-hour balance gates
+
+### Checkpoint: Release candidate
+
+- [ ] Expert-route P50 is at most 7:15 and P90 at most 8:00
+- [ ] Experienced first-play P50 is 18–21 hours and P75 at most 24:00
+- [ ] No mainline wait exceeds five minutes when the era reference factory meets target throughput
+
+## Risks and mitigations
+
+| Risk | Impact | Mitigation |
+|---|---:|---|
+| Sixty-two technologies create content before the core is fun | High | Implement by era and stop at every checkpoint for a complete playable test |
+| Research logic duplicates recipe/building unlock rules | High | One ID-based unlock service is authoritative for simulation, UI, and saving |
+| Random map distance determines achievement validity | High | Clamp required-resource distance and ship fixed benchmark seeds |
+| Optional automation becomes secretly mandatory for 24 hours | High | Maintain a no-comfort-tech reference route and compare it with the recommended route |
+| Speedrun balance removes normal-player breathing room | High | Tune guidance and convenience separately from mainline material cost |
+| High-tier factories overload scene nodes | High | Preserve data-oriented simulation, sleeping machines, and batched visible rendering |
+
+## Open decisions with safe defaults
+
+- Hostile enemies: default to environmental hazards and optional warding until combat receives its own approved design.
+- Campaign map: use a bounded handcrafted resource topology for balance tests; procedural variants must satisfy the same distance envelope.
+- Localization names: treat names in v0.1 as Chinese working names while IDs remain stable.
+- Achievement clock: count simulation time only, excluding pause/load/non-interactive cutscenes.
+- Existing demo: keep its all-tools-available showcase mode even after campaign unlock rules exist.

tasks/tech-tree-todo-v0.2.md

@@ -0,0 +1,298 @@
+# Magical-Law Progression Tasks v0.2
+
+## M1: Prototype portal matter exchange
+
+**Description:** Build a headless and minimal visual toy where 100 mass units form a seeded result bag, outputs arrive in shuffled order, anchors bias the distribution, and throughput raises entropy.
+
+**Acceptance criteria:**
+
+- [ ] The UI shows expected output ranges before a batch starts.
+- [ ] Stable, anchored, and high-entropy modes create different useful tradeoffs.
+- [ ] Every residue/anomaly has a recovery route; no required item relies on a sub-5% roll.
+
+**Verification:**
+
+- [ ] Same seed/input/calibration produces the same bag and state hash.
+- [ ] Save/load mid-bag preserves remaining outputs and cannot reroll.
+- [ ] One million simulated batches stay inside configured mass and probability bounds.
+
+**Dependencies:** None
+
+**Files likely touched:**
+
+- `src/simulation/result_bag.gd`
+- `src/simulation/portal_exchange.gd`
+- `tests/portal_exchange_smoke.gd`
+- `scenes/labs/portal_exchange_lab.tscn`
+
+**Estimated scope:** Medium
+
+## M2: Define biome laws and boundaries
+
+**Description:** Add data contracts for zone membership, boundary nodes, law state, failure/recovery, and law-specific machine modifiers without coupling them to rendered terrain.
+
+**Acceptance criteria:**
+
+- [ ] Forest balance, undead decay, ember temperature, mirror entropy, and rift instability use the same lifecycle interface.
+- [ ] Boundary crossings are explicit graph edges that can be opened and closed deterministically.
+- [ ] Existing entities outside a special zone retain current behavior.
+
+**Verification:**
+
+- [ ] Unit fixtures enter/leave each law and report exact state changes.
+- [ ] Closing a crossing never deletes in-flight inventory.
+- [ ] Sleeping entities do not wake every tick only because they occupy a special zone.
+
+**Dependencies:** None
+
+**Files likely touched:**
+
+- `src/simulation/biome_law.gd`
+- `src/simulation/biome_registry.gd`
+- `src/simulation/boundary_network.gd`
+- `tests/biome_law_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M3: Encode and validate the v0.2 progression
+
+**Description:** Turn `docs/tech-tree-nodes-v0.2.csv` into typed runtime data and validate prerequisites, roles, proof types, boundary unlocks, experiment requirements, and recovery paths.
+
+**Acceptance criteria:**
+
+- [ ] All 80 records load under stable IDs.
+- [ ] M nodes never depend on C/POST/INFINITE nodes.
+- [ ] Mainline totals equal K 10,780; L 9,580; D 9,580; E 8,150; S 6,200.
+
+**Verification:**
+
+- [ ] Invalid fixtures cover duplicate IDs, missing prerequisites, cycles, invalid proof types, and missing recovery.
+- [ ] The computed G09 closure contains inscription, life, death, element, dimension, and portal tags.
+- [ ] Existing simulation smoke tests remain green.
+
+**Dependencies:** M2
+
+**Files likely touched:**
+
+- `src/data/technology_definition.gd`
+- `src/data/technology_catalog.gd`
+- `src/data/technology_catalog.tres`
+- `tests/technology_catalog_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M4: Implement experiment-driven research
+
+**Description:** Consume physical proof items only after their experiment state sequence has completed, then support queues, parallel archives, progress inspection, and exact save/load.
+
+**Acceptance criteria:**
+
+- [ ] Each proof records which law experiment validated it.
+- [ ] Archives consume exact proof sets and never duplicate the final unit under parallel completion.
+- [ ] UI explains whether the bottleneck is proof validity, input, archive capacity, or prerequisite state.
+
+**Verification:**
+
+- [ ] Disconnect/reconnect preserves partial experiment and research progress.
+- [ ] Save/load fingerprints match uninterrupted execution.
+- [ ] Invalid hand-spawned blanks cannot satisfy a proof requirement.
+
+**Dependencies:** M3
+
+**Files likely touched:**
+
+- `src/simulation/research_system.gd`
+- `src/simulation/proof_experiment.gd`
+- `src/ui/research_screen.gd`
+- `tests/research_proof_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M5: Deliver the runic opening
+
+**Description:** Map the current prototype into B00–K11, then add ordered inscription, mana-frequency splitting, rune adjacency, clay constructs, and boundary surveying.
+
+**Acceptance criteria:**
+
+- [ ] A fresh run produces K automatically and discovers both external-zone crossings.
+- [ ] A wrong inscription order returns a reusable blank with a readable diagnosis.
+- [ ] Rune templates change at least one recipe and one efficiency property.
+
+**Verification:**
+
+- [ ] Automated flow reaches K11 without debug items.
+- [ ] Existing belt/mana/bridge deterministic tests pass.
+- [ ] A stripped-art test distinguishes ordinary routing from ordered inscription.
+
+**Dependencies:** M4
+
+**Files likely touched:**
+
+- `src/data/era_runic_content.tres`
+- `src/simulation/rune_array.gd`
+- `src/simulation/objective_system.gd`
+- `tests/era_runic_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M6: Deliver forest and undead zones
+
+**Description:** Implement regenerative growth/ecology balance and timed decay/memory recovery as two order-independent vertical slices with their own crossings and proof lines.
+
+**Acceptance criteria:**
+
+- [ ] Either zone can be completed first from the same K11 save.
+- [ ] Overharvest produces recoverable blight; mist decay produces recoverable bone dust.
+- [ ] L and D proofs are continuously automatable through their actual law loops.
+
+**Verification:**
+
+- [ ] Life-first and death-first runs both reach L08+D08 with matching mainline totals.
+- [ ] Ecology and identity conservation tests pass under backpressure.
+- [ ] Starting-zone blueprints visibly fail until adapted to each local law.
+
+**Dependencies:** M5
+
+**Files likely touched:**
+
+- `src/data/era_life_death_content.tres`
+- `src/simulation/growth_cycle.gd`
+- `src/simulation/decay_identity.gd`
+- `tests/era_life_death_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M7: Deliver ember-state production
+
+**Description:** Merge the two anchor laws, open a protected ember crossing, and automate temperature/state cycling through E08.
+
+**Acceptance criteria:**
+
+- [ ] Heat can accelerate production but unsafe heat only pauses and yields recoverable slag.
+- [ ] One medium completes cold, molten, and charged states to produce E.
+- [ ] Dragon glass requires the state loop rather than a conventional one-step furnace recipe.
+
+**Verification:**
+
+- [ ] Automated mandatory flow reaches E08 without optional fire spirits.
+- [ ] Energy and material conservation hold across state transitions.
+- [ ] Cooling loss and reheating wake only affected networks.
+
+**Dependencies:** M6
+
+**Files likely touched:**
+
+- `src/data/era_ember_content.tres`
+- `src/simulation/thermal_network.gd`
+- `src/simulation/item_state.gd`
+- `tests/era_ember_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M8: Deliver mirror folding and identity
+
+**Description:** Add paired spatial endpoints, echo sampling, bounded probabilistic duplication, shadow-matter separation, and identity anchoring through S08.
+
+**Acceptance criteria:**
+
+- [ ] Unnamed paths loop or misroute predictably; named endpoint pairs are deterministic.
+- [ ] Probability UI shows batch ranges before S05-dependent processes start.
+- [ ] Real and echo items can be sorted and both have useful recovery recipes.
+
+**Verification:**
+
+- [ ] Automated flow reaches S08 without optional mirror multiplication.
+- [ ] Seeded result bags reproduce exactly across frame rates and reloads.
+- [ ] No mainline item depends on a rare random output.
+
+**Dependencies:** M1, M7
+
+**Files likely touched:**
+
+- `src/data/era_mirror_content.tres`
+- `src/simulation/fold_network.gd`
+- `src/simulation/item_identity.gd`
+- `tests/era_mirror_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M9: Deliver the first-warp victory
+
+**Description:** Build the rift site, twelve ring stones, four anchors, beat-synchronized material batches, four-frequency power window, entropy safety, walker construct, and both time achievements.
+
+**Acceptance criteria:**
+
+- [ ] Researching G09 cannot win the game by itself.
+- [ ] First warp succeeds deterministically once all displayed ritual conditions hold.
+- [ ] The achievement timestamp is the simulation frame on which the walker crosses.
+
+**Verification:**
+
+- [ ] Boundary tests cover 07:59:59/08:00:00 and 23:59:59/24:00:00.
+- [ ] Save/load during ring construction, batch ritual, power window, and crossing preserves exact state.
+- [ ] A full mainline test contains all five law demonstrations and no C dependency.
+
+**Dependencies:** M8
+
+**Files likely touched:**
+
+- `src/data/era_portal_content.tres`
+- `src/simulation/grand_ritual.gd`
+- `src/simulation/achievement_clock.gd`
+- `tests/first_warp_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M10: Deliver the postgame portal economy
+
+**Description:** Connect the proven exchange toy to the opened campaign gate, add paradox proofs, ecological tuning, destinations, causal locks, relics, exact targeting, multiple gates, and repeatable research.
+
+**Acceptance criteria:**
+
+- [ ] Basic random exchange is usable immediately after victory.
+- [ ] The player can trade gathering pressure for sorting/entropy work but cannot outperform local basic-resource loops in every dimension.
+- [ ] Entropy bands create recoverable opportunities rather than arbitrary destruction.
+
+**Verification:**
+
+- [ ] Reference factories demonstrate unfocused, ecological, and true-name strategies.
+- [ ] Every X/I node calculates deterministic cost and survives save migration.
+- [ ] A portal-only economy cannot remain self-sustaining without external mana/catalyst input.
+
+**Dependencies:** M9
+
+**Files likely touched:**
+
+- `src/data/postgame_portal_content.tres`
+- `src/simulation/portal_exchange.gd`
+- `src/simulation/paradox_research.gd`
+- `tests/postgame_portal_smoke.gd`
+
+**Estimated scope:** Medium
+
+## M11: Prove 8/24-hour pacing and magical identity
+
+**Description:** Record progression and law-specific failure metrics, run structured expert and first-play tests, and tune without removing the mandatory magical demonstrations.
+
+**Acceptance criteria:**
+
+- [ ] Telemetry records first proof, zone entry, anchor, gate stage, failure/recovery, and warp timestamps.
+- [ ] Target percentiles meet 8/24 hours on standard topology seeds.
+- [ ] At least 80% of testers can explain why one machine stopped in each ecology zone.
+
+**Verification:**
+
+- [ ] Report includes at least three rehearsed expert runs and eight experienced first-play runs.
+- [ ] Cost simulator matches actual consumed proofs and final inventories.
+- [ ] Stripped-art test distinguishes every ecology zone by rules alone.
+
+**Dependencies:** M9, M10
+
+**Files likely touched:**
+
+- `src/telemetry/progression_metrics.gd`
+- `tools/progression_report.gd`
+- `tests/progression_benchmark_smoke.gd`
+- `artifacts/progression-benchmark-v0.2.md`
+
+**Estimated scope:** Medium

tasks/tech-tree-todo.md

@@ -0,0 +1,300 @@
+# Full Technology Progression Tasks (superseded)
+
+> Superseded by `tasks/tech-tree-todo-v0.2.md`. Retained only as a record of the rejected factory-reskin direction.
+
+## TT1: Define the progression data contract
+
+**Description:** Create stable IDs and typed records for technologies, research costs, prerequisites, recipes, buildings, unlocks, and postgame formulas. Import the v0.1 catalog without putting unlock conditions in UI code.
+
+**Acceptance criteria:**
+
+- [ ] Every row in `docs/tech-tree-nodes-v0.1.csv` maps to one runtime record.
+- [ ] Display names can change without changing save-compatible IDs.
+- [ ] Mainline, comfort, optional, and postgame roles are explicit data.
+
+**Verification:**
+
+- [ ] Headless catalog-load test reports 76 records.
+- [ ] Unknown pack, technology, recipe, or unlock IDs fail with an actionable message.
+- [ ] Existing simulation smoke tests still pass.
+
+**Dependencies:** None
+
+**Files likely touched:**
+
+- `src/data/technology_definition.gd`
+- `src/data/technology_catalog.gd`
+- `src/data/technology_catalog.tres`
+- `tests/technology_catalog_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT2: Validate the graph and simulate route costs
+
+**Description:** Add tooling that validates the dependency DAG and computes a selected route's tablet totals, lab-seconds, earliest unlocks, and final heart-furnace materials.
+
+**Acceptance criteria:**
+
+- [ ] Validator rejects duplicates, missing prerequisites, cycles, and any M node that transitively depends on O.
+- [ ] Mainline totals equal Q 11,220; A 10,920; R 9,990; V 8,400; G 5,300.
+- [ ] Simulator can compare mainline, recommended-normal, and custom routes.
+
+**Verification:**
+
+- [ ] Fixture tests cover each invalid-graph class.
+- [ ] Golden output records per-era cost and theoretical lab bottlenecks.
+- [ ] CI exits nonzero if catalog validation fails.
+
+**Dependencies:** TT1
+
+**Files likely touched:**
+
+- `src/data/technology_graph.gd`
+- `tools/progression_calculator.gd`
+- `tests/technology_graph_smoke.gd`
+- `tests/fixtures/technology_graphs.tres`
+
+**Estimated scope:** Medium
+
+## TT3: Implement the fixed-tick research runtime
+
+**Description:** Add research queues, lab input consumption, partial progress, completion events, and unlock commands while preserving the simulation's event-driven scheduling.
+
+**Acceptance criteria:**
+
+- [ ] Labs consume one exact tablet set per completed unit and never duplicate or lose items.
+- [ ] Loss of an input pauses exact progress and input restoration wakes the lab.
+- [ ] Completing a technology emits one idempotent unlock event.
+
+**Verification:**
+
+- [ ] Fixed-seed runs produce identical research fingerprints.
+- [ ] Disconnect/reconnect tests preserve partial unit progress exactly.
+- [ ] Parallel labs complete the same technology without over-consuming the final unit.
+
+**Dependencies:** TT1, TT2
+
+**Files likely touched:**
+
+- `src/simulation/research_system.gd`
+- `src/simulation/world_simulation.gd`
+- `tests/research_simulation_smoke.gd`
+- `tests/simulation_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT4: Add research UI and persistence
+
+**Description:** Let players inspect the graph, understand missing prerequisites and materials, manage the queue, and resume exact progress after save/load.
+
+**Acceptance criteria:**
+
+- [ ] Locked, available, queued, active, and complete states are visually distinct.
+- [ ] Selecting a node shows prerequisites, exact cost, unlocks, and current bottleneck.
+- [ ] Save/load preserves completion, queue order, invested tablets, timer, and achievement eligibility.
+
+**Verification:**
+
+- [ ] UI only submits research commands and never grants unlocks directly.
+- [ ] Save-then-run and uninterrupted-run fingerprints match.
+- [ ] Keyboard/mouse navigation works at 1280×720 and 1920×1080.
+
+**Dependencies:** TT3
+
+**Files likely touched:**
+
+- `src/ui/research_screen.gd`
+- `scenes/ui/research_screen.tscn`
+- `src/persistence/world_snapshot.gd`
+- `tests/research_save_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT5: Deliver the T0/T1 vertical slice
+
+**Description:** Build the campaign opening from repair milestones through automated mining, refinement, bridge arms, and continuous cyan-tablet production.
+
+**Acceptance criteria:**
+
+- [ ] A fresh player can reach C11 using only produced resources and objective guidance.
+- [ ] Existing demo entities map to progression IDs without changing their deterministic behavior.
+- [ ] Cyan production at 15/min is achievable with a clearly readable small factory.
+
+**Verification:**
+
+- [ ] Fresh-start headless scenario completes all six milestones and C11.
+- [ ] Manual walkthrough needs no developer controls or hidden starter stock.
+- [ ] Regression suite for belts, mana, and bridge endpoints passes.
+
+**Dependencies:** TT4
+
+**Files likely touched:**
+
+- `src/data/era_t0_t1_content.tres`
+- `src/simulation/objective_system.gd`
+- `src/main.gd`
+- `tests/era_t1_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT6: Deliver the T2 mana-logistics slice
+
+**Description:** Add second-tier belts and bridge arms, mana stabilization, spirit-sand glasswork, ether-fluid handling, and the crimson-tablet gate.
+
+**Acceptance criteria:**
+
+- [ ] The first fluid recipe requires pumps and storage but has no unrecoverable deadlock.
+- [ ] Disconnecting mana or fluid produces a precise stop reason and resumes safely.
+- [ ] The reference build sustains 15 crimson tablets per minute.
+
+**Verification:**
+
+- [ ] Automated flow covers A01 through A12 from a T1-complete save.
+- [ ] Fluid and mana conservation tests pass under backpressure.
+- [ ] Bridge II range and filters match catalog data.
+
+**Dependencies:** TT5
+
+**Files likely touched:**
+
+- `src/data/era_t2_content.tres`
+- `src/simulation/fluid_network.gd`
+- `src/simulation/world_simulation.gd`
+- `tests/era_t2_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT7: Deliver the T3 alchemy slice
+
+**Description:** Add elemental separation, alchemical synthesis, thermal mana, precision construction, leyline survey, and violet-tablet production.
+
+**Acceptance criteria:**
+
+- [ ] R13 can be reached without any C or O technology.
+- [ ] Byproducts back up visibly and can be routed or voided through an explicit recipe.
+- [ ] The reference build sustains 20 violet tablets per minute for normal pacing.
+
+**Verification:**
+
+- [ ] Automated flow covers the mandatory T3 route from a T2-complete save.
+- [ ] Conservation and deterministic allocation tests include solid, fluid, and mana networks.
+- [ ] Optional construction golems do not appear in the mandatory dependency closure.
+
+**Dependencies:** TT6
+
+**Files likely touched:**
+
+- `src/data/era_t3_content.tres`
+- `src/simulation/recipe_system.gd`
+- `src/simulation/resource_survey.gd`
+- `tests/era_t3_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT8: Deliver the T4 cross-island slice
+
+**Description:** Add bounded floating-island expansion, bulk shipping, deep leyline mining, phase metallurgy, spirit processors, and emerald-tablet production.
+
+**Acceptance criteria:**
+
+- [ ] A mandatory late resource is obtained from another island and moved by an automated route.
+- [ ] Required-resource distances stay inside the achievement-safe generation envelope.
+- [ ] The reference build sustains 20 emerald tablets per minute for normal pacing.
+
+**Verification:**
+
+- [ ] Fixed benchmark seeds expose all critical resources in allowed distance bands.
+- [ ] Cross-island transport preserves item counts across save/load.
+- [ ] Automated flow reaches V13 without comfort or warding nodes.
+
+**Dependencies:** TT7
+
+**Files likely touched:**
+
+- `src/data/era_t4_content.tres`
+- `src/simulation/island_logistics.gd`
+- `src/world/resource_topology.gd`
+- `tests/era_t4_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT9: Deliver T5 and the heart-furnace victory loop
+
+**Description:** Add source extraction, perpetual mana, warp logistics, heart components, furnace assembly, 300-second ignition, authoritative victory timing, and both limit achievements.
+
+**Acceptance criteria:**
+
+- [ ] G13 unlocks the ignition process but does not itself win the game.
+- [ ] The furnace consumes exact structure and component totals and pauses safely on mana loss.
+- [ ] Completion at 8 hours grants both achievements; completion after 8 but by 24 grants only the 24-hour achievement.
+
+**Verification:**
+
+- [ ] Accelerated deterministic test runs the entire final sequence without debug item injection.
+- [ ] Boundary tests cover 07:59:59, 08:00:00, 23:59:59, and 24:00:00.
+- [ ] Save/load during component assembly and ignition preserves exact progress and clock state.
+
+**Dependencies:** TT8
+
+**Files likely touched:**
+
+- `src/data/era_t5_content.tres`
+- `src/simulation/victory_system.gd`
+- `src/simulation/achievement_clock.gd`
+- `tests/victory_flow_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT10: Add optional and postgame branches
+
+**Description:** Implement comfort automation, modules, construction/logistics golems, warding, sky tablets, and seven repeatable technology lines without altering the mainline closure.
+
+**Acceptance criteria:**
+
+- [ ] Every C technology has a measurable convenience or payback claim.
+- [ ] Standard campaign can finish with every O technology locked.
+- [ ] Repeatable costs follow catalog formulas and cannot overflow save or UI values.
+
+**Verification:**
+
+- [ ] Dependency validator still reports no M-to-O path.
+- [ ] Mainline route totals remain unchanged after optional content loads.
+- [ ] Repeatable levels 1, 10, and 50 calculate deterministically.
+
+**Dependencies:** TT9
+
+**Files likely touched:**
+
+- `src/data/optional_technology_content.tres`
+- `src/data/postgame_technology_content.tres`
+- `src/simulation/research_system.gd`
+- `tests/postgame_research_smoke.gd`
+
+**Estimated scope:** Medium
+
+## TT11: Prove and tune 8/24-hour pacing
+
+**Description:** Instrument progression timestamps and bottlenecks, create reference saves/routes, run structured expert and normal playtests, then tune against percentile targets.
+
+**Acceptance criteria:**
+
+- [ ] Telemetry records every metric listed in the design without collecting personal data.
+- [ ] Expert P50/P90 and normal P50/P75 meet the agreed limits on standard maps.
+- [ ] Each tuning change names the observed bottleneck and preserves route identity.
+
+**Verification:**
+
+- [ ] Benchmark report compares at least three expert runs and eight first-play runs.
+- [ ] Automated route simulation agrees with catalog costs and benchmark save inventories.
+- [ ] Final release checklist contains no unexplained wait above five minutes.
+
+**Dependencies:** TT9, TT10
+
+**Files likely touched:**
+
+- `src/telemetry/progression_metrics.gd`
+- `tools/progression_report.gd`
+- `tests/progression_benchmark_smoke.gd`
+- `artifacts/progression-benchmark.md`
+
+**Estimated scope:** Medium

tasks/todo.md

@@ -0,0 +1,193 @@
+# Magic Factory Demo Tasks
+
+## Task 1: Register tools and third-party assets
+
+**Description:** Add the portable Godot version record, import Kenney Factory Kit 3.0, and preserve provenance so every external file remains auditable and replaceable.
+
+**Acceptance criteria:**
+- [x] Godot 4.7.1 can run from a workspace-local tool directory.
+- [x] Factory Kit source archive and extracted game-ready models are separated.
+- [x] Author, source URL, version, license, and acquisition date are documented.
+
+**Verification:**
+- [x] Godot reports version 4.7.1 stable.
+- [x] Asset archive contains its original CC0 license.
+- [x] No unlicensed third-party file is present.
+
+**Dependencies:** None
+
+**Estimated scope:** Medium
+
+## Task 2: Create a launchable 2.5D world
+
+**Description:** Build the project shell, orthographic camera, lit ground, environment, and a minimal HUD using the imported visual language.
+
+**Acceptance criteria:**
+- [x] Project starts directly into a readable isometric-like factory site.
+- [x] Camera pans and zooms within bounded limits.
+- [x] Resolution changes do not break the HUD.
+
+**Verification:**
+- [x] Headless project import completes without script errors.
+- [x] Graphical capture confirms camera composition and HUD layout.
+
+**Dependencies:** Task 1
+
+**Estimated scope:** Medium
+
+## Task 3: Add grid construction controls
+
+**Description:** Let the player choose a building type, preview its footprint, place it on the grid, rotate it, and remove it.
+
+**Acceptance criteria:**
+- [x] Valid and invalid placement previews are visibly different.
+- [x] Occupied cells cannot overlap.
+- [x] Rotation and removal update both world data and visuals.
+
+**Verification:**
+- [x] Automated grid occupancy and removal checks pass.
+- [x] Full player-flow smoke test builds the required routes through the construction API.
+
+**Dependencies:** Task 2
+
+**Estimated scope:** Medium
+
+## Task 4: Run one belt-to-machine production chain
+
+**Description:** Implement a source, straight and corner belts, one processing machine, and a sink so an item visibly becomes another item.
+
+**Acceptance criteria:**
+- [x] Items advance on fixed simulation ticks and render smoothly between them.
+- [x] Machine consumes the correct input and emits exactly one configured output.
+- [x] Backpressure stops the machine without losing or duplicating items.
+
+**Verification:**
+- [x] Identical fixed-tick runs produce matching counts and state fingerprints.
+- [x] Player-flow test remains correct after build, rejected overlap, removal, and replacement.
+
+**Dependencies:** Task 3
+
+**Estimated scope:** Medium
+
+## Task 5: Add mana supply and pipe connectivity
+
+**Description:** Add mana sources, pipes, and capacity-limited consumers; network topology is recalculated only when construction changes it.
+
+**Acceptance criteria:**
+- [x] Connected powered machines run and disconnected machines stop.
+- [x] Shared demand above source capacity produces deterministic allocation.
+- [x] Reconnecting a pipe wakes affected machines immediately.
+
+**Verification:**
+- [x] Connectivity and deterministic allocation tests pass.
+- [x] Disconnect/reconnect regression preserves unfinished recipe time exactly.
+
+**Dependencies:** Task 4
+
+**Estimated scope:** Medium
+
+## Task 6: Add configurable bridge arms
+
+**Description:** Bind an overhead arm to a machine and let the player select explicit pickup and drop cells across multiple belt lanes.
+
+**Acceptance criteria:**
+- [x] Endpoint preview clearly shows valid and invalid target cells.
+- [x] The arm transfers through the owning machine without an independent polling loop.
+- [x] Removing an endpoint leaves the machine safely waiting for a valid belt.
+
+**Verification:**
+- [x] Transfer count remains deterministic under input and output blockage.
+- [x] Full player-flow test binds explicit pickup and drop cells across a broken belt route.
+
+**Dependencies:** Task 4
+
+**Estimated scope:** Medium
+
+## Task 7: Add status inspection and objective guidance
+
+**Description:** Add a selection panel, machine stop reasons, throughput counters, construction hints, and a short objective sequence.
+
+**Acceptance criteria:**
+- [x] Selected machines expose recipe, progress, inventory, mana, and stop reason.
+- [x] Objectives lead from first belt placement to first processed item.
+- [x] UI never becomes authoritative simulation state.
+
+**Verification:**
+- [x] Every machine state maps to a readable UI message.
+- [x] Fresh-start walkthrough can be completed without debug controls.
+
+**Dependencies:** Tasks 5 and 6
+
+**Estimated scope:** Medium
+
+## Task 8: Add a second recipe and demo completion state
+
+**Description:** Extend the chain to raw crystal, refined crystal, and charged crystal, then detect sustained final output as completion.
+
+**Acceptance criteria:**
+- [x] Two machine stages can operate continuously with belt backpressure.
+- [x] Increasing a real bottleneck increases measured final throughput.
+- [x] Completion is based on sustained production, not one debug-spawned item.
+
+**Verification:**
+- [x] End-to-end count conservation test passes.
+- [x] Fresh-game manual completion path succeeds.
+
+**Dependencies:** Task 7
+
+**Estimated scope:** Medium
+
+## Task 9: Add demo presentation and snapshot saving
+
+**Description:** Add title/pause screens, coherent materials and mana effects, audio hooks, and one-slot world snapshot persistence.
+
+**Acceptance criteria:**
+- [ ] New game, continue, pause, restart, and quit flows work.
+- [ ] Snapshot restores construction, transport, production, and objectives.
+- [ ] Industrial assets read as magical machinery through a unified material pass.
+
+**Verification:**
+- [ ] Save-then-run and run-from-save produce matching state hashes.
+- [ ] Manual UI flow works at 1080p and a smaller window.
+
+**Dependencies:** Task 8
+
+**Estimated scope:** Medium
+
+## Task 10: Add deterministic stress generation and metrics
+
+**Description:** Add a developer-only scene that generates representative active, blocked, and offscreen factories and reports separate simulation/render costs.
+
+**Acceptance criteria:**
+- [ ] Presets create 1k visible, 10k active, and 100k blocked entity workloads.
+- [ ] Metrics show tick time, frame time, active/sleeping machines, and transported items.
+- [ ] Blocked-machine per-tick cost does not grow linearly with their count.
+
+**Verification:**
+- [ ] Fixed presets produce repeatable state hashes and entity counts.
+- [ ] A saved benchmark report identifies the first measured bottleneck.
+
+**Dependencies:** Task 8
+
+**Estimated scope:** Medium
+
+## Task 11: Package a Windows demo build
+
+**Description:** Configure export settings, build the playable Windows package, and verify it outside the editor.
+
+**Acceptance criteria:**
+- [ ] Export contains required assets and third-party notices.
+- [ ] Demo starts without the editor or workspace-local source tree.
+- [ ] Release README explains controls and current scope.
+
+**Verification:**
+- [ ] Clean-path smoke test reaches the first playable objective.
+- [ ] Packaged file list contains no source archives or development-only tools.
+
+**Dependencies:** Tasks 9 and 10
+
+**Estimated scope:** Medium
+
+## Post-demo progression work
+
+The 8/24-hour full technology progression is intentionally tracked separately in `tasks/tech-tree-plan-v0.2.md` and `tasks/tech-tree-todo-v0.2.md`. It does not add hidden completion requirements to the current demo tasks.