docs: add per-module .claude/CLAUDE.md and redirect AGENTS.md (#1466)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

core/wren-core-base/.claude/CLAUDE.md

@@ -0,0 +1,37 @@
+# wren-core-base
+
+Shared Rust crate with manifest types used by both wren-core and wren-core-py. Defines the MDL (Modeling Definition Language) data model.
+
+## Key Types (`src/mdl/`)
+
+- `manifest.rs` — `Manifest`, `Model`, `Column`, `Metric`, `Relationship`, `View`, `RowLevelAccessControl`, `ColumnLevelAccessControl`
+- `builder.rs` — Fluent `ManifestBuilder` API for constructing manifests in tests and tools
+
+## Features
+
+| Feature | Description |
+|---|---|
+| `default` | No optional features |
+| `python-binding` | Enables PyO3 derive macros via `wren-manifest-macro` for auto-generating Pydantic-compatible Python classes |
+
+## Dependencies
+
+- `wren-manifest-macro` (path: `manifest-macro/`) — Proc macro crate for auto-generating Python bindings
+- `sqlparser` — SQL type parsing
+- `pyo3` (optional) — Python FFI
+
+## Dev Commands
+
+```bash
+cargo check                    # Compile check
+cargo test                     # Run tests
+cargo fmt                      # Format
+cargo clippy -- -D warnings    # Lint
+taplo fmt                      # Format Cargo.toml
+```
+
+## Conventions
+
+- Any change to manifest types affects both Rust (wren-core) and Python (wren-core-py) consumers
+- When adding fields, ensure `serde` defaults are set for backward compatibility
+- The `python-binding` feature must remain optional — wren-core does not need it

core/wren-core-base/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+All module instructions live in `.claude/CLAUDE.md`. Please refer to that file for build commands, architecture, and conventions.

core/wren-core-py/.claude/CLAUDE.md

@@ -0,0 +1,44 @@
+# wren-core-py
+
+PyO3 bindings exposing wren-core to Python. Built with Maturin. This is the bridge between the Rust semantic engine and the Python ibis-server.
+
+## Key Source Files (`src/`)
+
+- `lib.rs` — PyO3 module entry point
+- `context.rs` — Python-facing session context wrapping wren-core
+- `manifest.rs` — Python manifest types (auto-generated via `wren-manifest-macro`)
+- `validation.rs` — Query validation exposed to Python
+- `extractor.rs` — MDL extraction utilities
+- `remote_functions.rs` — Remote function registration
+- `errors.rs` — Error type conversions (Rust -> Python exceptions)
+
+## Dev Commands
+
+```bash
+just install     # Poetry install
+just develop     # Build dev wheel with maturin (for local testing)
+just build       # Build release wheel
+just test-rs     # Rust tests only (cargo test --no-default-features)
+just test-py     # Python tests only (pytest)
+just test        # Both Rust and Python tests
+just format      # cargo fmt + ruff format + ruff check --fix + taplo fmt
+```
+
+## Dependencies
+
+- **wren-core** (path: `../wren-core/core`) — The Rust semantic engine
+- **wren-core-base** (path: `../wren-core-base`, feature: `python-binding`) — Shared manifest types with PyO3 support
+- **PyO3** with `abi3-py311` — Stable ABI targeting Python 3.11+
+- **Maturin** — Build backend for Rust-Python packages
+
+## Build Notes
+
+- Uses PyO3 stable ABI (`abi3-py311`), so one wheel works across Python 3.11+
+- The `extension-module` feature is the default and required for building as a Python extension
+- For `--no-default-features` (used in `test-rs`), PyO3 extension module linking is disabled so pure Rust tests can run
+
+## Conventions
+
+- Format Rust with `cargo fmt`, Python with `ruff`
+- CI runs on `wren-core-py/**` or `wren-core/**` changes
+- Changes to wren-core-base manifest types may require updating Python-side tests here

core/wren-core-py/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+All module instructions live in `.claude/CLAUDE.md`. Please refer to that file for build commands, architecture, and conventions.

core/wren-core/.claude/CLAUDE.md

@@ -0,0 +1,53 @@
+# wren-core
+
+Rust semantic engine for Wren Engine. Handles MDL analysis, query planning, logical plan optimization, and SQL generation via Apache DataFusion (Canner fork).
+
+## Workspace Layout
+
+Cargo workspace with four crates:
+
+| Crate | Purpose |
+|---|---|
+| `core/` | Main library — MDL processing, analyzer rules, optimizer passes, SQL generation |
+| `sqllogictest/` | SQL end-to-end tests using `.slt` files |
+| `benchmarks/` | Performance benchmarks |
+| `wren-example/` | Usage examples |
+
+## Key Source Directories (`core/src/`)
+
+- `mdl/` — Core MDL processing: `WrenMDL` (manifest + symbol table), `AnalyzedWrenMDL` (with lineage), function definitions (scalar/aggregate/window per dialect), type planning
+- `logical_plan/analyze/` — DataFusion analyzer rules: `ModelAnalyzeRule` (TableScan -> ModelPlanNode), scope tracking, access control (RLAC/CLAC), view expansion, relationship chain resolution
+- `logical_plan/optimize/` — Optimization passes: type coercion, timestamp simplification
+- `sql/` — SQL parsing and analysis
+
+## Dev Commands
+
+```bash
+cargo check --all-targets                               # Compile check
+RUST_MIN_STACK=8388608 cargo test --lib --tests --bins  # Run tests
+cargo fmt --all                                         # Format
+cargo clippy --all-targets --all-features -- -D warnings  # Lint
+taplo fmt                                               # Format Cargo.toml files
+```
+
+## Testing
+
+- Most unit tests are in `core/src/mdl/mod.rs`
+- SQL end-to-end tests use sqllogictest files in `sqllogictest/test_files/`
+- Snapshot testing with `insta` — run `cargo insta review` to approve changes
+
+## Dependencies
+
+- **DataFusion fork**: `https://github.com/Canner/datafusion.git` branch `canner/v49.0.1`
+- **wren-core-base**: Shared manifest types from `../wren-core-base`
+
+## Known Limitations
+
+**ModelAnalyzeRule — correlated subquery column resolution**: The `ModelAnalyzeRule` cannot resolve outer column references inside correlated subqueries. It only sees the subquery's own table scope. This affects TPCH Q2, Q4, Q15, Q17, Q20, Q21, Q22.
+
+## Conventions
+
+- Format with `cargo fmt`, lint with `clippy -D warnings`
+- TOML formatting with `taplo`
+- Snapshot tests use `insta`
+- CI runs on `wren-core/**` changes

core/wren-core/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+All module instructions live in `.claude/CLAUDE.md`. Please refer to that file for build commands, architecture, and conventions.