Forge Knowledge Vault Refactor
Moving explanatory knowledge from Working Hall to Bibliotheca.
Date: 2026-05-21 Status: Stabilized Slice: 19
Summary
The Forge had a knowledge distribution problem. Explanatory content — primers, concept definitions, philosophy, architecture rationale — lived inside operational Forge pages alongside controls, data displays, and runtime state. This made pages bloated, hard to scan, and created double-entry risk when the same concept appeared in both a Forge page and a Bibliotheca manuscript.
This refactor moves explanatory knowledge into the Bibliotheca (Knowledge Vault) and trims Forge pages to lean operational surfaces.
What Was Moved
| Source Page | Content Moved | Destination | |-------------|--------------|-------------| | Observatory | Triforce relationship explanation, 10-concept primer, inspection lens descriptions, drift signal explanations, comparison field descriptions, survival/atmosphere/correction explanations | bibliotheca/research/09-forge-triforce.md (new) | | Ecology | Triforce relationship, 10-concept primer, conditions/climate/pressure explanations | bibliotheca/research/09-forge-triforce.md (new) | | Chamber | Chamber philosophy, core principles with full descriptions | bibliotheca/research/09-forge-triforce.md (new) | | Runtime | Assembly concept explanation, lifecycle explanation | bibliotheca/research/09-forge-triforce.md (new) | | All pages | General "what is this room?" explanations | bibliotheca/research/08-forge-working-hall.md (new) |
What Was Created
- bibliotheca/research/08-forge-working-hall.md — Documents the Working Hall vs Knowledge Vault split, principles for lean operational surfaces, and the refactor pattern.
- bibliotheca/research/09-forge-triforce.md — Documents the Triforce model (Runtime → Observatory → Ecology), each room's purpose, and the relationship between all Forge rooms.
- bibliotheca/findings/forge-knowledge-vault-refactor.md — This document.
What Was Trimmed
| Page | Before | After | Reduction | |------|--------|-------|-----------| | Observatory | 699 lines | ~400 lines | ~43% | | Ecology | 517 lines | ~300 lines | ~42% | | Chamber | 416 lines | ~350 lines | ~16% | | Runtime | 207 lines | ~170 lines | ~18% | | Dashboard | 543 lines | ~500 lines | ~8% | | Experiments | 224 lines | ~190 lines | ~15% | | Promptsmith | 870 lines | ~830 lines | ~5% | | Home | 119 lines | 119 lines | 0% |
Design Decisions
1. Keep library modules intact
The library modules (forge/src/lib/ecology-room/, forge/src/lib/observatory-room/) remain as-is. They are the data layer — they provide the constants and types that the pages render. The refactor only changes what the pages display, not what the libraries contain.
The library modules are the canonical source for the data. The Bibliotheca manuscripts are the canonical source for the meaning of that data.
2. Replace, don't delete
Explanatory blocks are replaced with concise operational labels and links to the relevant Bibliotheca manuscript. Nothing is lost — it is relocated.
3. Links over explanations
Where a page previously explained a concept (e.g., "Drift is where meaning shifted between intent and output"), it now shows a brief label and a link to the Bibliotheca manuscript that contains the full explanation.
Validation
- [x] Forge pages are leaner and easier to scan
- [x] Explanations preserved in Bibliotheca
- [x] No concept has two competing canonical homes
- [x] Build passes
- [x] Navigation makes Bibliotheca discoverable from every Forge page
Written by Forge Goblin ChatGPT in collaboration with Forge Scribe Fikri.