Move engineering docs to spec/, resync with the implementation, and group the tree

.github/workflows/ci.yml

@@ -116,7 +116,7 @@ jobs:
           python3 scripts/verify_benchmark_report.py kernel.json --kind kernel-native
           python3 scripts/verify_benchmark_report.py transport.json --kind transport-loopback
           python3 scripts/check_regressions.py --scatter scatter.json --kernel kernel.json \
-            --transport transport.json --emit-md docs/engineering/benchmark_metrics.md
+            --transport transport.json --emit-md spec/benchmarks/metrics.md
 
       - name: Upload regression benchmark report
         if: always()
@@ -125,7 +125,7 @@ jobs:
           name: regression-benchmark-report
           if-no-files-found: warn
           path: |
-            docs/engineering/benchmark_metrics.md
+            spec/benchmarks/metrics.md
             scatter.json
             kernel.json
             transport.json
@@ -254,7 +254,7 @@ jobs:
       - name: Python 3.11 tests (native core)
         run: .venv/bin/python -m pytest -q
 
-  # Cross-library scatter benchmark incl. time-to-first-render (docs/engineering/benchmark.md).
+  # Cross-library scatter benchmark incl. time-to-first-render (spec/benchmarks/results.md).
   # Each isolated group uses the same deterministic input sizes and runs in
   # parallel. The report job below merges the partial results.
   benchmark_vs:

.github/workflows/release.yml

@@ -123,7 +123,7 @@ jobs:
 
   # Pyodide / Emscripten WASM wheel for in-browser CPython. Pyodide's platform
   # ABI is compiler-sensitive, so keep Rust, Emscripten, the wheel tag, and the
-  # runtime probe pinned as one tested set (see docs/engineering/production-readiness.md).
+  # runtime probe pinned as one tested set (see spec/process/production-readiness.md).
   wasm:
     name: Wheel Pyodide (runtime verified)
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -20,5 +20,4 @@ repos:
         language: system
         types: [text]
         files: ^docs/
-        exclude: ^docs/engineering/
         require_serial: true

CHANGELOG.md

@@ -119,7 +119,7 @@ in the README).
   values.
 - `xy.pyplot`: a matplotlib-flavored shim over the composition
   API (`import xy.pyplot as plt`). Corpus-defined compatibility —
-  see `docs/engineering/matplotlib-compat.md`; fully contained in
+  see `spec/matplotlib/compat.md`; fully contained in
   `python/xy/pyplot/` with boundary guardrails.
 - **Statistical and density chart breadth.** Added first-class `errorbar`/
   `error_band`, `box`, `violin`, `ecdf`, `hexbin`, and `contour` marks plus
@@ -299,7 +299,7 @@ in the README).
   as a ~58 KB, resolution-independent SVG); covers every chart kind including
   density/heatmap rasters, and the full mark styling surface (gradients,
   dashes, symbols, rounded bars, smooth curves as exact cubic Béziers).
-- **Mark-level styling** (both APIs; `docs/engineering/styling.md#styling-the-marks`):
+- **Mark-level styling** (both APIs; `spec/api/styling.md#styling-the-marks`):
   - `fill="linear-gradient(...)"` on `area`/`bar`/`column`/`histogram` — real
     CSS gradient syntax (2–8 stops, `%` positions, `currentColor` = the mark's
     own resolved color, hue-preserving fades to `transparent`); mark-space by
@@ -362,7 +362,7 @@ in the README).
   Linux glibc **and** musl/Alpine (x86-64, aarch64, armv7), macOS (x86-64,
   Apple Silicon), and Windows (x86, x64, arm64). An experimental
   Pyodide/Emscripten WASM wheel is built but does not yet load in-browser
-  (`docs/engineering/production-readiness.md` documents the exact linker failure and fix
+  (`spec/process/production-readiness.md` documents the exact linker failure and fix
   direction).
 - Release workflow `workflow_dispatch` dry-run mode: builds and verifies the
   full artifact matrix without publishing to PyPI (default for manual runs).

CLAUDE.md

@@ -1,9 +1,16 @@
 # xy / xy
 
 A high-performance charting engine. The authoritative design is
-`docs/engineering/design-dossier.md` — **read the relevant § before changing behavior**;
+`spec/design-dossier.md` — **read the relevant § before changing behavior**;
 code comments cite dossier sections (e.g. §16 = deep-zoom re-centering).
 
+The entire `spec/` directory is the source of truth for intended behavior,
+architecture, compatibility, benchmarks, release readiness, and contributor
+contracts. Keep it current with every relevant code, configuration, build, and
+release change. A change is incomplete while its affected specification is
+missing, stale, or inconsistent with the implementation; resolve discrepancies
+instead of treating the implementation alone as authoritative.
+
 ## Layout
 
 - `src/` — Rust core, **minimal external crates** (C ABI; one cdylib per
@@ -31,9 +38,9 @@ code comments cite dossier sections (e.g. §16 = deep-zoom re-centering).
 - `python/xy/pyplot/` — the matplotlib shim, fully contained
   (one-way dependency onto the public composition API; guardrails in
   `tests/pyplot/test_boundaries.py`). Corpus-defined compatibility:
-  `tests/pyplot/corpus/` + `docs/engineering/matplotlib-compat.md`.
+  `tests/pyplot/corpus/` + `spec/matplotlib/compat.md`.
 - `python/reflex-xy/` — the Reflex adapter, a separate distributable
-  package (`reflex_xy`; design: `docs/engineering/design/reflex-integration.md`). Chart
+  package (`reflex_xy`; design: `spec/design/reflex-integration.md`). Chart
   data rides the app's own websocket as a second socket.io namespace;
   figures live in a per-process registry rebuilt from Reflex state on miss.
   Depends on `xy` + `reflex`; `xy` itself must never import

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 The full contributor guide — PR checklist, local gate commands, and the
 chart-type contribution walkthrough — lives at
-[`docs/engineering/contributing.md`](docs/engineering/contributing.md).
+[`spec/process/contributing.md`](spec/process/contributing.md).
 
 Quick start:
 
@@ -26,6 +26,6 @@ python -c "import xy.kernels as k; print(k.BACKEND)"
 `BACKEND` is always `native`; an unavailable native core raises `ImportError`
 with remediation instead of silently degrading.
 
-Design questions are settled by [`docs/engineering/design-dossier.md`](docs/engineering/design-dossier.md)
+Design questions are settled by [`spec/design-dossier.md`](spec/design-dossier.md)
 — code comments cite its §-numbers. Read the relevant section before changing
 behavior, and don't regress the invariants listed in `CLAUDE.md`.

README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-  <img src="docs/engineering/assets/launch-benchmark-comparison.svg" alt="Grouped horizontal bar-chart comparison of xy, Matplotlib, and Plotly cold-render times at 10 million points; xy has the lowest measured time in all three output modes in this recorded run." width="1200">
+  <img src="spec/assets/launch-benchmark-comparison.svg" alt="Grouped horizontal bar-chart comparison of xy, Matplotlib, and Plotly cold-render times at 10 million points; xy has the lowest measured time in all three output modes in this recorded run." width="1200">
 </p>
 
 xy is an experimental Python charting library for large, interactive datasets.
@@ -73,7 +73,7 @@ The same chart can be exported without changing how it is built.
 xy currently includes line, scatter, area, histogram, bar and column, heatmap,
 error bar and band, box, violin, ECDF, hexbin, contour, step, stairs, stem,
 triangle mesh, and faceted charts. See the
-[copyable examples](docs/engineering/api-examples.md) for the complete surface.
+[copyable examples](spec/api/api-examples.md) for the complete surface.
 
 ### Coming from matplotlib
 
@@ -91,7 +91,7 @@ plt.show()
 ```
 
 The shim intentionally covers common plotting workflows rather than every
-matplotlib feature. See the [compatibility guide](docs/engineering/matplotlib-compat.md).
+matplotlib feature. See the [compatibility guide](spec/matplotlib/compat.md).
 
 ## Benchmarks
 
@@ -163,7 +163,7 @@ hover and selection can still return original rows.
 For benchmark methodology and measured results, see the
 [benchmark runbook](benchmarks/README.md) and the committed
 [launch report](benchmarks/launch_baselines/xy-0.1.0/macos-arm64-m5-pro/report.md).
-For the full design, see the [design dossier](docs/engineering/design-dossier.md).
+For the full design, see the [design dossier](spec/design-dossier.md).
 
 ## Stable vs. Experimental
 
@@ -202,12 +202,12 @@ needed for browser behavior.
 
 Engineering references:
 
-- [API examples](docs/engineering/api-examples.md)
-- [Styling](docs/engineering/styling.md)
+- [API examples](spec/api/api-examples.md)
+- [Styling](spec/api/styling.md)
 - [Benchmarks](benchmarks/README.md)
-- [Matplotlib compatibility](docs/engineering/matplotlib-compat.md)
-- [Architecture and design](docs/engineering/design-dossier.md)
-- [Production readiness](docs/engineering/production-readiness.md)
+- [Matplotlib compatibility](spec/matplotlib/compat.md)
+- [Architecture and design](spec/design-dossier.md)
+- [Production readiness](spec/process/production-readiness.md)
 - [Security](SECURITY.md)
 - [Changelog](CHANGELOG.md)
 

SECURITY.md

@@ -33,4 +33,4 @@ metadata is rejected.
   default; `sandbox=False` is an explicit caller opt-out for trusted HTML.
 - The native core is a local in-process C-ABI library; it processes only data
   already in the caller's process and performs no I/O or network access.
-- The audit trail lives in `docs/engineering/security-audit-2026-07-06.md`.
+- The audit trail lives in `spec/process/security-audit-2026-07-06.md`.

docs/api-reference/contributing.md

@@ -8,7 +8,8 @@ description: Set up XY development, run the right gates, and prepare a focused c
 XY welcomes focused bug fixes, documentation improvements, tests, and chart
 surface work. The canonical contributor guide is
 [CONTRIBUTING.md](https://github.com/reflex-dev/xy/blob/main/CONTRIBUTING.md);
-the engineering version contains the complete release and browser checklists.
+the internal [contributor specification](https://github.com/reflex-dev/xy/blob/main/spec/process/contributing.md)
+contains the complete release and browser checklists.
 
 ## Local Setup
 

docs/app/AGENTS.md

@@ -72,7 +72,7 @@ xy_docs/                 # App entry point and XY-specific site composition
 scripts/                 # Post-build sitemap, Markdown, and HTML validators
 tests/                   # Docs, links, live-preview, and integration tests
 ../                      # Public Markdown sources
-../engineering/          # Internal project docs; never published
+../../spec/              # Internal project docs; never published
 ```
 
 ## Commands

docs/app/README.md

@@ -30,7 +30,7 @@ development.
 
 Public pages live in the parent `docs/` directory. Page routes and sidebar
 order are declared centrally in `xy_docs/config.py`; do not add ordering
-frontmatter to individual Markdown files. The `docs/engineering/` tree is
+frontmatter to individual Markdown files. The `spec/` tree is
 internal project documentation and is intentionally excluded from the public
 site.
 

docs/app/xy_docs/config.py

@@ -199,7 +199,6 @@
     exclude=(
         "app/**",
         "assets/**",
-        "engineering/**",
         "styling/chrome-slots.md",
         "styling/component-variations.md",
         "styling/mark-styles.md",