Consolidate project documentation

README.md

@@ -1,5 +1,14 @@
 # Reanimator Core
 
-Architecture documentation was moved to the Project Bible:
+Project documentation is split into two sources:
 
-- `bible/README.md`
+- `bible/` - shared engineering rules and cross-project patterns
+- `bible-local/` - this project's current architecture, contracts, and decisions
+
+Read order for contributors and agents:
+
+1. `bible/README.md`
+2. `bible-local/README.md`
+3. `bible-local/architecture/system-overview.md`
+
+Operational status notes and implementation scratchpads are intentionally not kept as long-lived top-level documentation.

bible-local/README.md

@@ -17,5 +17,6 @@ The Bible is the single source of truth for this project's architecture.
 - `architecture/runtime-flows.md` - ingest, timeline, status, and failure invariants.
 - `architecture/ui-information-architecture.md` - required UI structure and semantics.
 - `architecture/data-model.md` - domain language, core tables, and migration boundaries.
-- `docs/` - migrated operational and implementation documentation (formerly `/docs`).
+- `docs/README.md` - index of active project documents outside the architecture set.
+- `docs/hardware-ingest-contract.md` - external JSON integration contract.
 - `decisions/README.md` - how to capture new and updated architecture decisions.

bible-local/decisions/2026-03-01-mysql-tx-cursor-safety.md

@@ -14,6 +14,6 @@
 - Consequences:
   - Recompute/rebuild code paths must be audited and kept cursor-safe.
   - Future projection rebuild and repair flows must follow two-phase read/write design by default.
-  - Runtime invariant documented in `bible/architecture/runtime-flows.md`.
+  - Runtime invariant documented in `bible-local/architecture/runtime-flows.md`.
 - Supersedes:
   - None.

bible-local/decisions/2026-03-15-documentation-consolidation.md

@@ -0,0 +1,21 @@
+# 2026-03-15 - Consolidate Canonical Project Documentation
+
+- Date:
+  - `2026-03-15`
+- Decision:
+  - Keep canonical project documentation only in `bible-local/architecture/`, `bible-local/docs/hardware-ingest-contract.md`, and short index/reference files.
+  - Remove stale progress trackers, migration status snapshots, and one-off implementation plans from `bible-local/docs/`.
+- Context:
+  - The repository accumulated multiple historical status files that no longer matched the current codebase or active architecture.
+  - Several documents duplicated the same ingest and migration story with conflicting claims.
+  - Documentation governance already requires removal of obsolete guidance in the same change.
+- Consequences:
+  - Contributors must update the architecture files or the external ingest contract instead of reviving ad-hoc status documents.
+  - Compatibility references may remain as short pointers, but not as duplicated source-of-truth documents.
+  - Root documentation now points directly to `bible/` and `bible-local/`.
+- Supersedes:
+  - `bible-local/docs/TODO.md`
+  - `bible-local/docs/IMPLEMENTATION_STATUS.md`
+  - `bible-local/docs/STRING_ID_MIGRATION_STATUS.md`
+  - `bible-local/docs/FINAL_STATUS.md`
+  - `bible-local/docs/plan/Plan #1.md`

bible-local/decisions/README.md

@@ -7,6 +7,7 @@ Use this directory to capture architecture decisions and significant updates.
 - Every architecture decision must be recorded in the Bible.
 - If a decision replaces an older one, update the older document in the same change.
 - Keep entries short, explicit, and linked to the affected architecture files.
+- Use `bible-local/architecture/...` and `bible-local/docs/...` paths when referencing affected documents.
 
 ## Minimal Entry Template
 

bible-local/docs/README.md

@@ -0,0 +1,13 @@
+# Project Docs Index
+
+This directory keeps active non-architecture documents for Reanimator Core.
+
+## Active Documents
+
+- `hardware-ingest-contract.md` - external-facing JSON hardware ingest contract for integrators.
+
+## Removed Document Types
+
+The project does not keep long-lived progress trackers, implementation status snapshots, or one-off task plans as canonical documentation.
+
+When such notes are no longer needed to operate the system, delete them instead of updating them indefinitely.

bible-local/docs/hardware-ingest-contract.md

@@ -33,7 +33,7 @@ language: ru
 1. **Snapshot** — JSON описывает состояние сервера на момент сбора. Может включать историю изменений статуса компонентов.
 2. **Идемпотентность** — повторная отправка идентичного payload не создаёт дублей (дедупликация по хешу).
 3. **Частичность** — можно передавать только те секции, данные по которым доступны. Пустой массив и отсутствие секции эквивалентны.
-4. **Толерантность к лишним полям** — неизвестные поля JSON молча игнорируются, ошибки не возникает.
+4. **Строгая схема** — endpoint использует строгий JSON-декодер; неизвестные поля приводят к `400 Bad Request`.
 5. **Event-driven** — импорт создаёт события в timeline (LOG_COLLECTED, INSTALLED, REMOVED, FIRMWARE_CHANGED и др.).
 
 ---
@@ -102,6 +102,7 @@ GET /ingest/hardware/jobs/{job_id}
 Частые причины `400`:
 - Неверный формат `collected_at` (требуется RFC3339).
 - Пустой `hardware.board.serial_number`.
+- Наличие неизвестного JSON-поля на любом уровне.
 - Тело запроса превышает допустимый размер.
 
 ---

bible-local/governance/documentation-policy.md

@@ -8,14 +8,15 @@ This policy defines how architectural knowledge is captured and maintained.
 
 - Record every architecture decision in the Bible before or together with implementation.
 - Use English for all architecture documentation.
+- External integration handoff documents may use the consumer language when needed, but they must be explicitly marked as external-facing.
 - Keep only current architecture in active sections.
 - When a solution is replaced, update or remove obsolete guidance in the same change.
-- Keep architecture details centralized in `bible/`; other top-level docs should only reference it.
+- Keep shared rules in `bible/` and project-specific architecture in `bible-local/`; other top-level docs should only reference them.
 
 ## Change Workflow
 
-1. Update the relevant file(s) in `bible/architecture/`.
+1. Update the relevant file(s) in `bible-local/architecture/` or `bible-local/docs/`.
-2. If behavior changed, add or update a decision note in `bible/decisions/`.
+2. If behavior changed or documentation policy changed, add or update a decision note in `bible-local/decisions/`.
 3. Remove duplicated or outdated statements from non-Bible docs.
 4. Validate consistency against code paths in `internal/api`, `internal/ingest`, and `internal/repository`.
 

internal/api/ui_ingest.tmpl

@@ -54,7 +54,7 @@
           <textarea class="input" id="hardware" name="payload" rows="10">{{.HardwarePayload}}</textarea>
         </div>
         <div class="field">
-          <label for="hardwareFile">Upload JSON snapshot(s) (per INTEGRATION_GUIDE.md)</label>
+          <label for="hardwareFile">Upload JSON snapshot(s) (per hardware-ingest-contract.md)</label>
           <input class="input" id="hardwareFile" type="file" accept="application/json,.json" multiple data-hardware-files="1" />
         </div>
         <div class="field" data-hardware-progress-wrap hidden>

releases/v0.1.0/RELEASE_NOTES.md

@@ -1,5 +1,7 @@
 # Release v0.1.0
 
+Historical note: this file is a point-in-time release snapshot, not the current architecture reference.
+
 Date: 2026-02-15
 Tag: v0.1.0
 Previous tag: none (initial tagged release)