Final cleanup pass for Brainy 8.0. Catches three categories of debt:
A. STEP-7 FOLLOW-THROUGH (rebuild-path collapse)
Step 7's bisect-reset (debugging a flaky test) lost the in-source edits
to three rebuild paths even though the commit message claimed they
shipped. Re-applied now:
- src/utils/metadataIndex.ts — collapsed the `isLocalStorage` /
cloud-pagination branching. Local-load-all-at-once is the only path
in 8.0. Removed ~150 LOC of paginated-cloud branching for both nouns
and verbs, plus the safety counters (`consecutiveEmptyBatches`,
`MAX_ITERATIONS`, etc.).
- src/hnsw/hnswIndex.ts — same simplification for HNSW rebuild. The
paginated cloud path is gone; HNSW now loads all nodes at once.
Removed ~85 LOC.
- src/graph/graphAdjacencyIndex.ts — same simplification for graph
adjacency rebuild. Removed ~50 LOC.
The collapse is safe because cloud adapters were deleted in step 7;
`storageType === 'OPFSStorage'` (and similar) can never match now.
B. CLOUD-ONLY DOCS DELETED
- docs/operations/cost-optimization-aws-s3.md
- docs/operations/cost-optimization-azure.md
- docs/operations/cost-optimization-cloudflare-r2.md
- docs/operations/cost-optimization-gcs.md
- docs/operations/cloud-run-filestore-guide.md
(docs/deployment/* contained no cloud-specific files that needed deletion.)
C. STORAGE-ADAPTERS GUIDE REWRITTEN FOR 8.0
docs/guides/storage-adapters.md → fresh content reflecting the 8.0
reality:
- Two adapters: FileSystemStorage + MemoryStorage. Quick-start matrix.
- Cloud backup section explains the operator-tooling pattern (gsutil /
aws s3 / rclone / azcopy) with the exact commands consumers will run.
- "Why no cloud adapters in 8.0?" section documents the four reasons
per BR-BRAINY-80-STORAGE-SIMPLIFY.
- Migration recipe for 7.x cloud-adapter consumers: mount local disk →
filesystem storage → operator backup cron.
Updated frontmatter description so soulcraft.com/docs renders the
correct preview.
NOT IN THIS COMMIT (deliberate, lower-priority)
- src/storage/cacheManager.ts still references StorageType.S3 /
REMOTE_API / OPFS as dead branches (23 sites). The branches are never
reached in 8.0, but cleaning them would cascade through 5 consumers.
Defer to a follow-up if the dead code surfaces as a real maintenance
issue.
- src/config/storageAutoConfig.ts keeps its StorageType enum + autodetect
for 7.x compat surface. Same reason: rewriting cascades through
zeroConfig, extensibleConfig, sharedConfigManager. Defer.
- docs/MIGRATION-V3-TO-V4.md and docs/DEVELOPER_LEARNING_PATH.md still
reference cloud adapters as historical artefacts. That's accurate —
they describe how things used to be. Left as-is.
- @deprecated audit in src/ (10 files) deferred — audit each individually
in a future polish pass.
VERIFICATION
- npx tsc --noEmit: clean
- npm test: 1408 / 1409 (same pre-existing race-condition outstanding from
step 7; no regressions from this cleanup)
Add YAML frontmatter (slug, public, category, template, order) to 8
existing docs and 2 new getting-started guides (installation, quick-start).
Include docs/**/*.md in npm package files so the portal sync-docs script
can read them from node_modules after publish.
Update CLAUDE.md with docs pipeline trigger phrases and release checklist.
- Switch vitest pool from threads to forks for process isolation
- Disable v8 coverage by default (causes vitest worker RPC timeout)
- Increase hookTimeout 30s to 60s for MetadataIndexManager init under load
- Reduce O(1) space test entity count, replace brittle timing assertions
- Add docs/guides/storage-adapters.md with verified batch config values
