Problem
In docs/features/brain-system.md:63-83 and docs/ARCHITECTURE.md:114-122:
The Data Storage directory trees depict Brain entity records as monolithic JSON files (people.json, projects.json, ideas.json, admin.json, inbox.json, links.json, journals.json, memories.json, buckets.json).
In server/services/brainStorage.js:5-16, 58-77, Migration 200 (issue #725) refactored all entity stores into collectionStore directories (data/brain/<type>/<id>/index.json with a schema-version stamped data/brain/<type>/index.json). The monolithic .json files are legacy files from before migration 200.
Additionally, docs/features/brain-system.md:291 describes server/routes/brain.js as an aggregator mounting subrouters but omits brainIdeaLoom.js (ideaLoomRoutes, mounted at server/routes/brain.js:20, 26).
Trigger
Developers, operators, or autonomous CoS agents reading docs/features/brain-system.md or docs/ARCHITECTURE.md to locate Brain data files on disk for inspection, backup, or manual migration.
Impact
Users and agents looking for data/brain/people.json or data/brain/inbox.json find only 20-byte legacy stubs or .bak-200 files instead of the actual active records in data/brain/<type>/<id>/index.json, leading to mistaken data loss diagnosis.
Fix
- In
docs/features/brain-system.md:65-82 and docs/ARCHITECTURE.md:114-122, update the data/brain/ layout diagram to show the per-record collectionStore directory structure:
./data/brain/
├── meta.json # Settings and scheduler state
├── admin/ # Admin tasks (collectionStore: <id>/index.json)
├── buckets/ # Custom bucket definitions (collectionStore: <id>/index.json)
├── ideas/ # Ideas and concepts (collectionStore: <id>/index.json)
├── inbox/ # Captured thoughts (collectionStore: <id>/index.json)
├── journals/ # Daily Log entries (collectionStore: <id>/index.json)
├── links/ # Cross-record links (collectionStore: <id>/index.json)
├── memories/ # Brain memories (collectionStore: <id>/index.json)
├── people/ # People records (collectionStore: <id>/index.json)
├── projects/ # Projects with status tracking (collectionStore: <id>/index.json)
├── songs/ # SongBook songs (collectionStore: <id>/index.json)
├── memory-bridge-map.json # Brain↔CoS memory bridge mapping
├── obsidian-vaults.json # Obsidian vault sync config
├── sync_log.jsonl # Obsidian sync history
├── digests.jsonl # Daily digest history
└── reviews.jsonl # Weekly review history
- In
docs/features/brain-system.md:291, update the router description table to include brainIdeaLoom.js (ideaLoomRoutes).
(Rejected alternative: Leaving the file tree diagram unedited was rejected because it directly misrepresents the on-disk storage layout established in migration 200.)
Acceptance criteria
Problem
In
docs/features/brain-system.md:63-83anddocs/ARCHITECTURE.md:114-122:The Data Storage directory trees depict Brain entity records as monolithic JSON files (
people.json,projects.json,ideas.json,admin.json,inbox.json,links.json,journals.json,memories.json,buckets.json).In
server/services/brainStorage.js:5-16, 58-77, Migration 200 (issue #725) refactored all entity stores intocollectionStoredirectories (data/brain/<type>/<id>/index.jsonwith a schema-version stampeddata/brain/<type>/index.json). The monolithic.jsonfiles are legacy files from before migration 200.Additionally,
docs/features/brain-system.md:291describesserver/routes/brain.jsas an aggregator mounting subrouters but omitsbrainIdeaLoom.js(ideaLoomRoutes, mounted atserver/routes/brain.js:20, 26).Trigger
Developers, operators, or autonomous CoS agents reading
docs/features/brain-system.mdordocs/ARCHITECTURE.mdto locate Brain data files on disk for inspection, backup, or manual migration.Impact
Users and agents looking for
data/brain/people.jsonordata/brain/inbox.jsonfind only 20-byte legacy stubs or.bak-200files instead of the actual active records indata/brain/<type>/<id>/index.json, leading to mistaken data loss diagnosis.Fix
docs/features/brain-system.md:65-82anddocs/ARCHITECTURE.md:114-122, update thedata/brain/layout diagram to show the per-recordcollectionStoredirectory structure:docs/features/brain-system.md:291, update the router description table to includebrainIdeaLoom.js(ideaLoomRoutes).(Rejected alternative: Leaving the file tree diagram unedited was rejected because it directly misrepresents the on-disk storage layout established in migration 200.)
Acceptance criteria
docs/features/brain-system.mdanddocs/ARCHITECTURE.mdshow thecollectionStoredirectory layout for Brain entity stores.docs/features/brain-system.mdlistsbrainIdeaLoom.jsamongserver/routes/brain.jssubrouters.