Add project bible rules and update README

- rules/patterns/go-project-bible/contract.md: required files, ADL format,
  runtime-flows rules, what not to duplicate, how to keep current
- README.md: rewritten to reflect actual repo purpose and structure

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

rules/patterns/go-project-bible/contract.md

@@ -0,0 +1,110 @@
+# Contract: Project Bible (bible-local/)
+
+## Purpose
+
+`bible-local/` is the single source of truth for everything **specific to this project**:
+data model, API surface, business rules, architectural decisions.
+
+Shared engineering rules (CSV, logging, DB, tables, etc.) live in the `bible/` submodule.
+Do not duplicate them in `bible-local/`.
+
+## Required Files
+
+Every project bible must have these files:
+
+```
+bible-local/
+  README.md              — index: what files exist and what each covers
+  architecture/
+    system-overview.md   — what the product does, active scope, non-goals
+    data-model.md        — domain entities, DB tables, naming conventions
+    api-surface.md       — all HTTP endpoints with methods and response shape
+    runtime-flows.md     — key mutation flows, invariants, critical rules
+  decisions/
+    README.md            — ADL format explanation
+    YYYY-MM-DD-topic.md  — one file per architectural decision
+```
+
+Optional (add when relevant):
+```
+  architecture/
+    ui-information-architecture.md  — page structure, navigation, UI invariants
+  docs/
+    INTEGRATION_GUIDE.md            — external system integration (formats, protocols)
+```
+
+## system-overview.md Rules
+
+- List what is **in scope** and what is **explicitly out of scope**.
+- Out of scope section prevents scope creep — update it when you reject a feature.
+- Include tech stack and local run command.
+
+## data-model.md Rules
+
+- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
+- List all DB tables with one-line description of each.
+- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
+- Migration policy: how migrations are numbered and applied.
+
+## api-surface.md Rules
+
+- Every endpoint: method, path, brief description, key response fields.
+- Group by domain area (Registry, Ingest, Timeline, etc.).
+- Note any endpoints that are UI-only routes vs JSON API.
+- Document pagination, filtering params where non-obvious.
+
+## runtime-flows.md Rules
+
+This is the most important file. Document flows that are **easy to break**:
+
+- Mutation paths (what happens step by step when user does X)
+- Event/time source priority rules
+- Deduplication logic
+- Cross-entity side effects (e.g. removing a component affects asset status)
+- Anything that caused a bug or regression — add a "DO NOT reintroduce" note
+
+Format each flow as a numbered list of steps, not prose.
+
+## Architectural Decision Log (ADL)
+
+Write a decision entry when:
+- You choose between two non-obvious approaches
+- You intentionally reject a feature or pattern
+- A bug caused a rule change (e.g. cursor safety)
+- You freeze or deprecate something
+
+**Format:**
+
+```markdown
+# Decision: <short title>
+
+**Date:** YYYY-MM-DD
+**Status:** active | superseded by YYYY-MM-DD-topic.md
+
+## Context
+What situation made this decision necessary.
+
+## Decision
+What was decided, stated clearly.
+
+## Consequences
+What this means going forward. What is now forbidden or required.
+```
+
+- One decision per file, named `YYYY-MM-DD-short-topic.md`.
+- When a decision is superseded, add `superseded by` to the old file's status — do not delete it.
+- Record the decision **in the same commit** as the code that implements it.
+
+## What NOT to Put in bible-local/
+
+- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/`
+- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder
+- Duplicate of what is already in code (don't restate what the code clearly shows)
+- Speculative future architecture — document what exists, not what might exist
+
+## Keeping the Bible Current
+
+- Update `bible-local/` in the **same commit** as the code change it describes.
+- If you change a flow, update `runtime-flows.md` in the same PR.
+- If a section becomes outdated, fix or delete it — stale docs are worse than no docs.
+- Bible files are in **English only**.