Skip to content

Commit 3c744ed

Browse files
MustafaNazeerMustafaNazeer
authored
phase 0: brainstorm, plan, scaffold, and audit (#3)
* phase 0 brainstorm: resolve hosting decisions, cascade to specs and briefs The four open questions in the technical design's section 13 are now resolved on 2026-05-09: * Hosting domain: meridian-demo.pages.dev (Cloudflare default). * Backend host: Fly.io free tier with auto-stop on idle and auto-start on first request, not a VPS plus systemd. * Demo symbol set: AAPL, SPY, NVDA, TSLA, GOOG. * Audit log on the live demo: WebSocket-only, in-memory ring buffer, not persisted to disk. Section 13 of the design spec now records these as resolved decisions. The Phase 9 frontend gains an explicit cold-start "engine warming up" state for the Fly auto-wake window (5 to 15 seconds). Phase 10 moves from VPS plus systemd to Fly Dockerfile plus fly.toml; the window-cost estimate drops from 85 percent to 75 percent accordingly. The CLI meridian-replay --audit flag is unaffected, since that flag is for offline diffing against the Python reference, not for the live demo. Cascading edits propagate the new stack through SPEC.md, STATUS.md, README.md, GETTING-STARTED.md, the design spec sections 2.3, 3, 5.3, 5.5, 9, 11, and 13, and the briefs for the PM (00), Engine Developer (03), Security Engineer (08), DevOps Engineer (09), Performance Engineer (12), and Observability Engineer (14). STATUS.md flips Phase 0 to in_progress as part of opening the phase. * phase 0: write rolling implementation plan at docs/plan.md The plan is the PM session's per-phase source of truth, complementing STATUS.md (which is the simpler "which phase is next" pointer). Each phase block covers: goal, status, window cost, inputs, outputs, dispatch order, high-level tasks, exit criteria, and risks. Phase 0 is fully detailed because it is in flight; Phases 1 through 11 are at medium grain and will be expanded with bite-sized-step companion plans under docs/superpowers/plans/ when each phase opens. Decisions and constraints from the 2026-05-09 brainstorm and the design spec section 13 are reflected throughout: meridian-demo.pages.dev, Fly.io free tier with cold-start UX requirement, five-symbol demo (AAPL, SPY, NVDA, TSLA, GOOG), in-memory WebSocket-only audit log on the live demo, Phase 10 window cost reduced to ~75 percent. The plan also lists the 10 matching invariants in Phase 3 verbatim so the property test suite has a single source of truth, and codifies the cross-cutting testing, performance, security, documentation, and concurrency disciplines that span phases. * phase 0 dispatch: specialist outputs plus React 19 / Fly-serves reconciliation The four parallel Phase 0 specialists have returned and their outputs land here in one consolidated commit. UI/UX Designer (05): * docs/design/tokens.md (every visual token from canonical.html, with an embedded Tailwind config block ready to drop into frontend/tailwind.config.ts). * docs/design/wireframes.md (per-component layouts, data-component names, micro-interactions, connection state visual treatments). Security Engineer (08): * docs/security/threat-model.md (STRIDE on four surfaces: WebSocket endpoint, static-file serving, replay tape, build pipeline). * docs/security/checklist.md (per-phase hardening checklist; Phase 10 Fly hardening items expanded). * docs/security/secrets.md (FLY_API_TOKEN, CLOUDFLARE_API_TOKEN, fly secrets set, rotation procedures). * Three [citation needed] markers in the threat model are deferred to the Citation and Fact Auditor dispatch. DevOps Engineer (09): * CMakeLists.txt root plus apps/{bench,replay,server}/CMakeLists.txt stubs plus tests/CMakeLists.txt. cmake -B build -S . -G Ninja configures cleanly. * .github/workflows/ci.yml with engine matrix (clang plus gcc) and a frontend job. Caches keyed on toolchain plus pnpm-lock.yaml. * frontend/ Vite scaffold via pnpm create vite, Tailwind 3.4, with the embedded config from tokens.md applied verbatim to frontend/tailwind.config.ts. * .gitignore extended for .cache/, pnpm-lock.yaml.bak, and frontend/.env*. * docs/setup-guide.md section 12.1 documents the manual GitHub branch-protection toggle. Documentation Engineer (15): * README.md rewritten as a Phase 0 stub with every metric and URL labeled "target" or "v1 will". * docs/architecture.md as a 15-minute orientation for a developer new to the codebase. * docs/setup-guide.md skeleton (DevOps fills it across phases). * docs/adr/0001-cpp20-library-plus-drivers.md (status Accepted, dated 2026-05-09). PM reconciliation in this commit: * React 18 became React 19 throughout (SPEC.md, README.md, design spec sections 3 and 5.5, docs/plan.md, docs/architecture.md, agents/04-frontend-developer.md). DevOps's pnpm create vite defaulted to React 19; we accept that rather than downgrade. Vega's frontend stays on React 18; matching majors across the constellation is a non-goal. * Design spec section 5.4 corrected: meridian-server serves WSS /ws plus /healthz plus /metrics, NOT GET / for the static React app. Cloudflare Pages owns the SPA per the section 13 resolution. The Security Engineer flagged this ambiguity and the PM resolved it. docs/architecture.md updated to match. The Citation and Fact Auditor dispatches next; that pass resolves the three [citation needed] markers and audits README.md, docs/architecture.md, the ADR, the threat model, the design spec, and this plan. * phase 0 audit: resolve auditor findings F1 through F4 and land the audit report The Citation and Fact Auditor's Phase 0 pass at docs/audits/citation-audit-2026-05-09.md found 53 verified, 2 unverified, and 2 wrong claims across the Phase 0 documentation surface. The auditor resolved the three [citation needed] markers in docs/security/threat-model.md in place (uWebSockets advisory history, Fly.io free-tier wake latency, Cloudflare Pages _headers mechanism) by replacing each with a footnoted citation naming the verifying source and the 2026-05-09 verification date. This commit lands four PM follow-ups that the auditor flagged as Phase 0 close blockers: F1: Property-test case-count divergence. SPEC.md and design spec section 8.2 previously said "at least 1000 generated cases per CI run", while docs/plan.md and design spec section 2.3 said "10,000 generated sequences each". The two numbers serve different purposes; the docs now state both: at least 1000 cases per invariant per CI run as the continuous regression discipline, and a one-time 10,000-sequence validation pass with zero failures as the Phase 3 acceptance criterion (per section 2.3 success criteria). F2: SPEC.md "Project summary" previously asserted "the headline 6.2M events per second number is defensible in isolation" as fact. No benchmark has run; the number was aspirational. Reframed: "the headline 6M events per second target will be defensible in isolation once measured in Phase 5." ADR 0001 quotes SPEC.md verbatim and is updated to match. F3: GoogleTest is pinned by tag v1.15.2 in CMakeLists.txt, while threat-model.md and checklist.md required pinning by SHA, not tag. The auditor's recommendation: pin by commit SHA or by an immutable upstream release tag (release tags only; branch tags like main, master, HEAD remain forbidden because they retarget). Both the threat-model entry and the Phase 10 hardening checklist item now reflect this. F4: Design spec section 10 repo layout previously named the frontend directory web/. CLAUDE.md, docs/plan.md, the actual scaffold, and every other doc use frontend/. Section 10 now matches; component list updated to match the wireframes (Header, Hero, Ladder, DepthChart, Tape, PerfPanel, Footer, EngineWarmingUp). With these fixes landed and the audit report committed, the Phase 0 documentation surface is clean of unverified or wrong claims. * phase 0: status board updated to reflect closeout state STATUS.md "Last updated" advances and Resume notes section now describes the four-commit branch state (1ad71f3, 8862eab, 23ed376, 60a9e89), the next concrete task (user authorizes push, PM runs the standard push protocol against the first CI run), and the deferred branch-protection toggle on main. docs/plan.md Phase 0 task list is updated to mark items 4 through 6 as done with the produced commits cited; item 7 (the merge gate) remains pending until the user signals push. The phase status itself stays at in_progress until the PR merges, per the PM brief's definition of done. The check-in protocol runs in the chat alongside this commit; the user's continue / pause / stop answer is captured in Resume notes when received.
1 parent b7012e0 commit 3c744ed

50 files changed

Lines changed: 6038 additions & 102 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
push:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ci-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
engine:
15+
name: engine (${{ matrix.toolchain }})
16+
runs-on: ubuntu-24.04
17+
strategy:
18+
fail-fast: false
19+
matrix:
20+
toolchain: [clang, gcc]
21+
include:
22+
- toolchain: clang
23+
cc: clang
24+
cxx: clang++
25+
apt_packages: clang
26+
- toolchain: gcc
27+
cc: gcc
28+
cxx: g++
29+
apt_packages: gcc g++
30+
env:
31+
CC: ${{ matrix.cc }}
32+
CXX: ${{ matrix.cxx }}
33+
CMAKE_GENERATOR: Ninja
34+
steps:
35+
- name: Checkout
36+
uses: actions/checkout@v4
37+
38+
- name: Install build tools
39+
run: |
40+
sudo apt-get update
41+
sudo apt-get install -y --no-install-recommends \
42+
cmake \
43+
ninja-build \
44+
${{ matrix.apt_packages }}
45+
46+
- name: Compute source hash for cache key
47+
id: srchash
48+
run: |
49+
HASH=$(find . -type f \
50+
\( -name 'CMakeLists.txt' -o -name '*.cmake' -o -name '*.cpp' -o -name '*.h' -o -name '*.hpp' \) \
51+
-not -path './build/*' \
52+
-not -path './frontend/*' \
53+
-not -path './.git/*' \
54+
-print0 | sort -z | xargs -0 sha256sum | sha256sum | cut -d' ' -f1)
55+
echo "hash=${HASH}" >> "$GITHUB_OUTPUT"
56+
57+
- name: Cache CMake build directory
58+
uses: actions/cache@v4
59+
with:
60+
path: build
61+
key: cmake-${{ matrix.toolchain }}-${{ runner.os }}-${{ steps.srchash.outputs.hash }}
62+
restore-keys: |
63+
cmake-${{ matrix.toolchain }}-${{ runner.os }}-
64+
65+
- name: Configure
66+
run: cmake -B build -S . -G Ninja
67+
68+
- name: Build
69+
run: cmake --build build
70+
71+
- name: Test
72+
run: ctest --test-dir build --output-on-failure
73+
74+
frontend:
75+
name: frontend
76+
runs-on: ubuntu-24.04
77+
defaults:
78+
run:
79+
working-directory: frontend
80+
steps:
81+
- name: Checkout
82+
uses: actions/checkout@v4
83+
84+
- name: Setup Node.js
85+
uses: actions/setup-node@v4
86+
with:
87+
node-version: '22'
88+
89+
- name: Enable pnpm via corepack
90+
run: corepack enable
91+
92+
- name: Resolve pnpm store path
93+
id: pnpm-store
94+
run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
95+
96+
- name: Cache pnpm store
97+
uses: actions/cache@v4
98+
with:
99+
path: ${{ steps.pnpm-store.outputs.path }}
100+
key: pnpm-${{ runner.os }}-${{ hashFiles('frontend/pnpm-lock.yaml') }}
101+
restore-keys: |
102+
pnpm-${{ runner.os }}-
103+
104+
- name: Install dependencies
105+
run: pnpm install --frozen-lockfile
106+
107+
- name: Build
108+
run: pnpm build
109+
110+
- name: Test
111+
run: |
112+
if pnpm run --silent | grep -qE '^\s*test\s*$'; then
113+
pnpm test --run
114+
else
115+
echo "No 'test' script defined in package.json yet; skipping. Vitest is wired in Phase 9."
116+
fi

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ CTestTestfile.cmake
2828
Testing/
2929
_deps/
3030
Makefile
31+
.cache/
3132

3233
# Profile-guided optimization
3334
*.profraw
@@ -52,6 +53,12 @@ dist/
5253
.vite/
5354
*.tsbuildinfo
5455
.eslintcache
56+
pnpm-lock.yaml.bak
57+
frontend/.env
58+
frontend/.env.local
59+
frontend/.env.*.local
60+
frontend/.env.development
61+
frontend/.env.production
5562

5663
# IDE
5764
.vscode/

‎CMakeLists.txt‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
cmake_minimum_required(VERSION 3.25)
2+
3+
project(meridian
4+
VERSION 0.1.0
5+
DESCRIPTION "Meridian: price-time priority limit order book and matching engine"
6+
LANGUAGES CXX
7+
)
8+
9+
set(CMAKE_CXX_STANDARD 20)
10+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
11+
set(CMAKE_CXX_EXTENSIONS OFF)
12+
13+
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
14+
15+
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
16+
set(CMAKE_BUILD_TYPE Release CACHE STRING "Default build type" FORCE)
17+
set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
18+
Debug Release RelWithDebInfo MinSizeRel)
19+
endif()
20+
21+
option(MERIDIAN_BUILD_TESTS "Build the Meridian test suite" ON)
22+
option(MERIDIAN_BUILD_BENCH "Build meridian-bench" ON)
23+
option(MERIDIAN_BUILD_REPLAY "Build meridian-replay" ON)
24+
option(MERIDIAN_BUILD_SERVER "Build meridian-server" ON)
25+
26+
include(FetchContent)
27+
28+
# GoogleTest is pulled in early so dependent targets across phases can use it.
29+
# Locked to v1.15.2 (released 2024-07-31). Update only with explicit DevOps and Code Reviewer sign-off.
30+
FetchContent_Declare(
31+
googletest
32+
GIT_REPOSITORY https://github.com/google/googletest.git
33+
GIT_TAG v1.15.2
34+
GIT_SHALLOW TRUE
35+
)
36+
set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
37+
38+
if(MERIDIAN_BUILD_TESTS)
39+
FetchContent_MakeAvailable(googletest)
40+
enable_testing()
41+
include(GoogleTest)
42+
endif()
43+
44+
# libmeridian.a (Phase 1): the engine library lives under src/ and include/meridian/.
45+
# add_subdirectory(src) is intentionally commented out until Phase 1 lands the first sources.
46+
# add_subdirectory(src)
47+
48+
# Driver binaries (apps/). Each subdirectory's CMakeLists.txt is a stub today; the
49+
# add_subdirectory lines are intentionally commented out until each binary's main.cpp lands
50+
# in the phase noted next to it. When the sources land, the dispatched agent uncomments
51+
# the matching line.
52+
#
53+
# apps/bench: Phase 5 (Performance Engineer)
54+
# apps/replay: Phase 6 (Engine Developer)
55+
# apps/server: Phase 8 (Engine Developer)
56+
#
57+
# add_subdirectory(apps/bench)
58+
# add_subdirectory(apps/replay)
59+
# add_subdirectory(apps/server)
60+
61+
# Tests (Phase 1 onward). The tests/ subdirectory's CMakeLists.txt is a stub today;
62+
# the add_subdirectory line is commented out until QA Engineer lands the first test source.
63+
#
64+
# if(MERIDIAN_BUILD_TESTS)
65+
# add_subdirectory(tests)
66+
# endif()

‎GETTING-STARTED.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Before any code is written, post a short orientation message to the user that na
2525
* Which agents you plan to dispatch in parallel.
2626
* The first concrete artifact you will produce (the implementation plan in `docs/plan.md`).
2727

28-
Wait for the user to ack before proceeding. The user may have new context (a chosen domain name, VPS provider preference, etc.).
28+
Wait for the user to ack before proceeding. The user may have new context (a Fly.io app name preference, a region preference, etc.; the four open questions originally in design spec section 13 were resolved on 2026-05-09 during Phase 0 bootstrap and are no longer open).
2929

3030
### Step 3: brainstorm and plan
3131

‎README.md‎

Lines changed: 52 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,84 +2,101 @@
22

33
A price-time priority limit order book and matching engine in C++20, with a live web visualization.
44

5-
> **Status**: under construction. Project scaffolded 2026-05-09; build begins at Phase 1. The headline benchmark numbers and live demo URL below are **target values for v1**, not measured yet. This README will be rewritten by the Documentation Engineer in Phase 11 with real numbers and a real demo link.
5+
> **Status**: under construction. Project scaffolded 2026-05-09; Phase 0 foundations in progress, with the engine's first line of code landing in Phase 1. Every concrete metric and URL on this page is labeled "target" or "v1 will" until measured or deployed. The Documentation Engineer rewrites this README in Phase 11 with real numbers and a real demo link.
66
77
## What this is
88

9-
The venue half of a two-project quant systems narrative on the resume. [Vega](https://github.com/MustafaNazeer/Vega) prices instruments. Meridian is the place those instruments would trade.
9+
Meridian is the venue half of a two-project quant systems narrative on the resume. [Vega](https://github.com/MustafaNazeer/Vega) prices instruments. Meridian is the place those instruments would trade.
1010

11-
The engine implements strict price-time priority (FIFO within each price level) and supports five order types: limit, market, immediate-or-cancel (IOC), post-only, and fill-or-kill (FOK), plus cancel-by-id. It is multi-instrument: one matching thread handles many symbols via a symbol-keyed dispatch. The single-thread matching loop is the headline performance number.
11+
The engine implements strict price-time priority (FIFO within each price level) and supports five order types: limit, market, immediate or cancel (IOC), post-only, and fill or kill (FOK), plus cancel by id. It is multi-instrument: one matching thread handles many symbols via a symbol keyed dispatch. Top of book is published to readers (the sampler thread, the WebSocket server) through a seqlock protected snapshot, so the matching loop never blocks on I/O. The single threaded matching loop is the headline performance number.
1212

13-
## Targets (v1)
13+
## v1 targets
1414

15-
* **Throughput**: 6M+ events per second, single-threaded.
16-
* **Latency**: p50 ≤ 500 ns, p99 ≤ 2 μs, p99.9 ≤ 5 μs per event.
17-
* **Correctness**: 10 matching invariants verified by `rapidcheck` property-based tests, ≥1000 generated cases per CI run.
18-
* **Replay**: NASDAQ ITCH 5.0 binary tapes, parsed and replayed against the engine.
19-
* **Live demo**: 30 Hz web visualization with the engine running in real time, decoupled from the matching loop via sequence-locked snapshots.
15+
Every number in this section is a **target, not yet measured**. Real numbers replace these in Phase 11 once `meridian-bench` runs on the user's desktop with the final binary.
16+
17+
* **Throughput target**: 6M events per second, single threaded.
18+
* **Latency target**: p50 under 500 ns, p99 under 2 us, p99.9 under 5 us per event.
19+
* **Correctness target**: 10 matching invariants verified by `rapidcheck` property based tests, at least 1000 generated cases per CI run, with the C++ engine's audit log diffed byte for byte against a Python reference implementation under `tests/reference/`.
20+
* **Replay target**: NASDAQ ITCH 5.0 binary tapes, parsed and replayed against the engine.
21+
* **Live demo target**: 30 Hz web visualization with the engine running in real time, decoupled from the matching loop via the seqlock protected snapshot.
2022

2123
## How it ships
2224

2325
Three thin driver binaries link against `libmeridian.a`:
2426

2527
| Binary | Purpose | Networking |
2628
|---|---|---|
27-
| `meridian-bench` | Pure throughput and latency benchmark. The 6M events per second number comes from this binary. | None. |
28-
| `meridian-replay` | CLI: replays an ITCH tape, streams JSON Lines (fills, cancels, top-of-book) to stdout. | None. |
29-
| `meridian-server` | Live demo: replayer + matching loop + uWebSockets at the same time. | uWebSockets. |
29+
| `meridian-bench` | Pure throughput and latency benchmark. The headline events per second target comes from this binary. | None. |
30+
| `meridian-replay` | CLI: replays an ITCH tape, streams JSON Lines (fills, cancels, top of book) to stdout. | None. |
31+
| `meridian-server` | Live demo: replayer plus matching loop plus 30 Hz sampler plus uWebSockets. | uWebSockets only. |
3032

31-
The library and the bench binary contain zero networking code, so the headline number is defensible.
33+
The library and the bench binary contain zero networking code, so the headline number is defensible in isolation.
3234

3335
## Tech stack
3436

3537
| Layer | Choice |
3638
|---|---|
3739
| Engine language | C++20 (clang 19+ primary, gcc 14+ secondary) |
3840
| Build | CMake 3.25+ with Ninja |
39-
| Tests | GoogleTest plus rapidcheck (property-based) |
40-
| Benchmark | Google Benchmark plus a hand-rolled latency harness |
41-
| WebSocket | uWebSockets v20+ |
42-
| ITCH parser | Hand-rolled (single-header) |
43-
| Frontend | React 18 plus Vite plus TypeScript plus Tailwind |
41+
| Tests | GoogleTest plus rapidcheck (property based) |
42+
| Benchmark | Google Benchmark plus a hand rolled HDR histogram latency harness |
43+
| WebSocket library | uWebSockets v20+ |
44+
| ITCH parser | Hand rolled, single header |
45+
| Logging | spdlog, level filtered out of the release hot path |
46+
| JSON | simdjson (parse), glaze (serialize) |
47+
| Reference implementation | Python 3.11 plus pytest under `tests/reference/` |
48+
| Frontend framework | React 19 plus Vite plus TypeScript |
49+
| Frontend styling | Tailwind CSS |
50+
| State management (frontend) | Zustand |
51+
| Charts | Hand rolled SVG (no chart library) |
4452
| Frontend host | Cloudflare Pages |
45-
| Backend host | Hetzner CX22 VPS or Fly.io |
53+
| Backend host | Fly.io machine (free tier, Dockerfile plus `fly.toml`, auto stop on idle, auto start on first request) |
54+
| Package manager (frontend) | pnpm |
4655
| CI/CD | GitHub Actions |
4756
| License | MIT |
4857

4958
## Visual design
5059

51-
The live demo's visual identity is the **Twilight** theme: deep indigo `#0E1126` background, gold `#D4A24C` accent, muted teal `#4FA89E` for bid, faded coral `#C5765B` for ask, off-white `#EFE9DC` ink, Newsreader italic for editorial display, Inter for UI body, JetBrains Mono with `tabular-nums` for all numerics. The canonical design HTML at [`docs/design/canonical.html`](docs/design/canonical.html) is the visual ground truth.
60+
The live demo's visual identity is the **Twilight** theme: deep indigo `#0E1126` background, gold `#D4A24C` accent, muted teal `#4FA89E` for bid, faded coral `#C5765B` for ask, off-white `#EFE9DC` ink. Display type is Newsreader italic, body type is Inter, all numerics are JetBrains Mono with `font-variant-numeric: tabular-nums`. The canonical design HTML at [`docs/design/canonical.html`](docs/design/canonical.html) is the visual ground truth; the React implementation under `frontend/` mirrors its tokens, anatomy, and personality.
61+
62+
Twilight was chosen on 2026-05-09 from a field of five candidate directions. The four rejected directions (Bourse, Terminal, Eikon, Onyx) live under [`design-mockups/themes/`](design-mockups/themes/) for design archaeology. The contrast between Vega's "Oxblood" theme (warm dark reds) and Meridian's "Twilight" theme (cool indigos with gold) is intentional so the two projects read as a constellation rather than two clones of the same template.
63+
64+
## Live demo
65+
66+
v1 will deploy the frontend to **`meridian-demo.pages.dev`** (Cloudflare Pages default subdomain; no custom domain for v1) and the engine to a Fly.io machine reachable at `wss://<fly-app>.fly.dev/ws`. The Fly app name and region are picked at Phase 10. Neither URL is live yet; this section will link to a working demo once Phase 10 ships.
5267

53-
Twilight was chosen on 2026-05-09 from a field of five candidate directions. The four rejected directions (Bourse, Terminal, Eikon, Onyx) live under [`design-mockups/themes/`](design-mockups/themes/) for design archaeology.
68+
The Fly machine auto stops when idle and auto starts on the first request, so the first WebSocket connection after a quiet period takes roughly 5 to 15 seconds while Fly wakes the machine. The Phase 9 frontend renders an explicit "engine warming up" state during this window rather than appearing broken.
69+
70+
## Status
71+
72+
Phased build, 12 phases (0 through 11). Phase 0 (foundations) is in progress as of 2026-05-09. The single source of truth for which phase is current is [`STATUS.md`](STATUS.md); the per phase implementation plan is [`docs/plan.md`](docs/plan.md).
5473

5574
## Entry points
5675

5776
* [`SPEC.md`](SPEC.md): the full project spec, agent roster, and 12 phase build plan.
5877
* [`CLAUDE.md`](CLAUDE.md): the auto loaded brief for any Claude Code session opened in this directory.
5978
* [`STATUS.md`](STATUS.md): single source of truth for which phase is in flight.
60-
* [`GETTING-STARTED.md`](GETTING-STARTED.md): the first-session walkthrough.
79+
* [`GETTING-STARTED.md`](GETTING-STARTED.md): the first session walkthrough.
6180
* [`docs/superpowers/specs/2026-05-09-meridian-design.md`](docs/superpowers/specs/2026-05-09-meridian-design.md): the deep technical design (the engineering contract).
6281
* [`docs/plan.md`](docs/plan.md): the per phase implementation plan, written by the Project Manager in Phase 0.
63-
64-
## Live demo
65-
66-
(Will be updated to the live URL after Phase 10 deployment ships.)
82+
* [`docs/architecture.md`](docs/architecture.md): a 15 minute orientation for a developer new to the codebase.
83+
* [`agents/`](agents/): 18 specialist agent briefs (00 PM plus 17 specialists).
6784

6885
## Repository layout
6986

7087
See `CLAUDE.md` for the canonical directory tree. Headline:
7188

7289
```
73-
include/meridian/ public library headers
74-
src/ libmeridian.a implementation
75-
apps/{bench,replay,server}/ three driver binaries
76-
tests/ unit, property, integration tests
77-
bench/ CI benchmark baseline JSON
78-
frontend/ React app for the live demo
79-
docs/ specs, design, security, perf, risk, ADRs
80-
agents/ 18 specialist briefs
90+
include/meridian/ public library headers
91+
src/ libmeridian.a implementation
92+
apps/{bench,replay,server}/ three driver binaries
93+
tests/ unit, property, integration, concurrency, reference
94+
bench/ CI benchmark baseline JSON
95+
frontend/ React app for the live demo
96+
docs/ specs, design, security, perf, risk, ADRs, audits
97+
agents/ 18 specialist briefs
8198
```
8299

83100
## License
84101

85-
MIT. See [`LICENSE`](LICENSE) once it lands in Phase 0.
102+
MIT. The `LICENSE` file lands in Phase 0 as part of the DevOps Engineer's repo bootstrap.

0 commit comments

Comments
 (0)