docs: add README, contributing guide, and validation CI

The repository had no entry point. README covers the architecture, the
latency budget, the documentation map, and — prominently — that nothing
here has been compiled, simulated, or run on hardware, so no reader
mistakes design targets for measurements.

CI gates on structural defects only. Broken links are reported but not
blocking, since manual tiers 10 and 11 are knowingly incomplete; adding
--ignore-category keeps that distinction explicit rather than lowering
the bar globally. Verilator lint reports without gating until the tree
is clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: mcelikx

.github/workflows/validate.yml

@@ -0,0 +1,72 @@
+name: Validate
+
+# Structural validation of the repository. This does NOT prove the design is
+# correct or fast — that needs simulation against the golden model and a
+# post-route timing report, neither of which runs here.
+#
+# It proves the tree is internally consistent: every module the top level
+# instantiates exists, the RTL obeys the coding rules in CLAUDE.md, and
+# cross-references resolve.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Repository consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Broken links are ignored as a build gate because manual tiers 10 and 11
+      # are knowingly incomplete — the count is reported below so the gap stays
+      # visible rather than being silently tolerated.
+      - name: Validate structure
+        run: |
+          python3 scripts/validate.py \
+            --quiet \
+            --html docs/validation-report.html \
+            --ignore-category broken-link
+
+      - name: Report metrics
+        if: always()
+        run: |
+          python3 scripts/validate.py 2>/dev/null \
+            | python3 scripts/ci_summary.py >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: validation-report
+          path: docs/validation-report.html
+          retention-days: 30
+
+  lint:
+    name: RTL lint
+    runs-on: ubuntu-latest
+    # Verilator is not yet clean across the tree — this reports rather than
+    # gates. Flip continue-on-error off once `scripts/lint.sh` passes.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Verilator
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y verilator
+          verilator --version
+
+      - name: Lint
+        run: ./scripts/lint.sh

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+This is a real-money trading system. The bar is higher than for most codebases, and the
+reasons are in [`CLAUDE.md`](CLAUDE.md) §5 and §6. Read those first.
+
+---
+
+## Before you write RTL
+
+1. **Read the governing manual.** Every block has one; it is named in the module header.
+   The manuals encode the constraints that make the design correct *and* fast. Skipping
+   them produces code that synthesizes, misses timing, and blows the latency budget.
+2. **State the latency budget** in nanoseconds and cycles, in the module header. A block
+   without a budget is not reviewable.
+3. **State the resource budget** — LUT/FF/BRAM/URAM/DSP — in the same header.
+
+## Coding standard
+
+Full detail in [`manuals/00-foundations/03-hdl-and-rtl-coding.md`](manuals/00-foundations/03-hdl-and-rtl-coding.md).
+
+- Synthesizable **SystemVerilog IEEE 1800-2017**. `logic` only, never `reg`/`wire`.
+- `always_ff` / `always_comb` only. Never bare `always`. `<=` in ff, `=` in comb.
+- **No latches.** Default assignments open every `always_comb`; every `case` has a `default`.
+- Synchronous active-high `rst`. Reset control state only, never datapath registers.
+- Registered outputs by default; exceptions justified in a comment.
+- All literals sized (`8'd5`), all parameters typed (`parameter int unsigned`).
+- Named generate blocks. One module per file, filename == module name.
+- `` `default_nettype none `` at the top, `` `default_nettype wire `` at the bottom.
+- SVA assertions inside `` `ifndef SYNTHESIS `` on every stream interface and invariant.
+- **No division, no modulo, no floating point.**
+
+CDC uses only the sanctioned primitives in [`rtl/common/`](rtl/common/). Hand-rolling a
+synchronizer is a review failure, not a style disagreement — the failure mode is a design
+that works for months and then corrupts one order.
+
+## Before you open a PR
+
+```bash
+python3 scripts/validate.py --ignore-category broken-link   # must exit 0
+./scripts/lint.sh                                            # Verilator, -Wall clean
+make -C scripts sim                                          # testbenches pass
+```
+
+- **Every fast-path module needs a testbench.** No exceptions.
+- Do not report "done" until place-and-route timing closes.
+- Quote **WNS/TNS and utilization verbatim from the report**. Never estimate them.
+- If a latency number was simulated, say "simulated". If measured on hardware, say
+  "measured, N=…". These are not interchangeable and conflating them wastes everyone's time.
+
+## Suppressing a validator rule
+
+Rules can be suppressed, but never silently:
+
+```systemverilog
+localparam real CLKFB_MULT_F = 12.500;  // validate: allow real — vendor MMCM declares it real
+```
+
+The justification is mandatory. A suppression without one is itself reported.
+
+---
+
+## 🔒 Changes that need extra care
+
+These have a blast radius beyond the file you are editing.
+
+| Change | Requirement |
+|---|---|
+| **Risk limits, order sizing, kill switch** | Separate commit, separate review, separate audit entry. **Never bundled with other work.** |
+| **`rtl/pkg/trading_pkg.sv`** | System-wide contract. Say so explicitly and update the latency budget in the same commit. |
+| **`rtl/fpga_top.sv`** | Holds the master latency budget. Any added cycle must be justified in the PR. |
+| **ITCH/OUCH field offsets** | Must be verified against the current spec PDF and the verification recorded. A wrong offset produces a decoder that corrupts *some* messages silently. |
+| **Anything touching a live venue** | Never. Simulated and UAT endpoints only, until conformance certification is complete. |
+
+## What must never be optimized away
+
+The risk gate, the kill switch, gap detection, and the error counters. Removing a check to
+save a cycle converts a latency problem into a solvency problem.
+
+## Never commit
+
+Venue credentials, comp IDs, session IDs, MPIDs, production IP addresses, or recorded
+exchange market data. `.gitignore` covers the common cases; it is not a substitute for
+looking at your diff.
+
+---
+
+## Commit messages
+
+Conventional-Commit prefixes (`feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`,
+`build:`), imperative mood, subject ≤ 72 chars. The body explains **why**, not a file-by-file
+recap — and in this codebase the *why* is usually a failure mode being prevented. Say what
+it is.