---
phase: 05-hardening-and-docs
plan: "02"
type: execute
wave: 2
depends_on:
  - "05-01"
files_modified:
  - MAINTAINER.md
autonomous: true
requirements:
  - DOCS-01

must_haves:
  truths:
    - "A contributor following only MAINTAINER.md can install Rust, clone the repo, and build the extension without external research"
    - "A contributor following only MAINTAINER.md can run all tests (unit, SQL logic, DuckLake/Iceberg) without external research"
    - "A contributor following only MAINTAINER.md can load the built extension in a DuckDB Python shell and execute a semantic query"
    - "A contributor following only MAINTAINER.md can update the DuckDB version pin and verify the build still works"
    - "A contributor following only MAINTAINER.md can run the fuzzer locally and interpret results"
    - "A contributor following only MAINTAINER.md can understand the publishing process for the community extension registry"
    - "The architecture overview maps every src/ file to its conceptual role"
    - "Worked examples cover adding a new DDL function and adding a new metric type"
  artifacts:
    - path: "MAINTAINER.md"
      provides: "Complete maintainer documentation covering all required sections"
      contains: "Architecture Overview"
      min_lines: 200
  key_links:
    - from: "MAINTAINER.md"
      to: "Justfile"
      via: "References just commands for all build/test/fuzz workflows"
      pattern: "just"
    - from: "MAINTAINER.md"
      to: "Cargo.toml"
      via: "References feature flags and dependencies"
      pattern: "features"
    - from: "MAINTAINER.md"
      to: "fuzz/"
      via: "Documents fuzzer setup, running, corpus management"
      pattern: "cargo fuzz"
---

<objective>
Write MAINTAINER.md covering the complete developer lifecycle: environment setup, build, test, LOAD, version pin update, fuzzing, and community extension publishing. Includes architecture overview and worked examples.

Purpose: Satisfy DOCS-01 -- a contributor can set up, build, test, load, fuzz, and publish the extension without asking for help.
Output: MAINTAINER.md at project root.
</objective>

<execution_context>
@/Users/paul/.claude/get-shit-done/workflows/execute-plan.md
@/Users/paul/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/05-hardening-and-docs/05-CONTEXT.md
@.planning/phases/05-hardening-and-docs/05-RESEARCH.md
@.planning/phases/05-hardening-and-docs/05-01-SUMMARY.md
@Cargo.toml
@Justfile
@src/lib.rs
@src/model.rs
@src/expand.rs
@src/catalog.rs
@.github/workflows/NightlyFuzz.yml
@.github/workflows/DuckDBVersionMonitor.yml
@.github/workflows/PullRequestCI.yml
@.github/workflows/MainDistributionPipeline.yml
@.github/workflows/CodeQuality.yml
</context>

<tasks>

<task type="auto">
  <name>Task 1: Write MAINTAINER.md with all required sections, architecture overview, and worked examples</name>
  <files>
    MAINTAINER.md
  </files>
  <action>
Create `MAINTAINER.md` at the project root. The primary reader is a Python expert who knows the semantic views domain but is new to Rust and DuckDB extension development. Use brief inline Rust concept explanations with Python analogies where they first appear. Explain the "why" behind troubleshooting fixes, not just the commands.

**Required sections (all equally detailed):**

1. **Prerequisites** -- What to install before anything else:
   - `rustup` (analogous to `pyenv` -- manages Rust toolchain versions)
   - Stable Rust toolchain via `rustup install stable`
   - `just` command runner (analogous to `make` but simpler -- `cargo install just` or `brew install just`)
   - Python 3 (for SQLLogicTest runner and DuckLake setup -- user likely already has this)
   - Git (with submodules support)

2. **Quick Start** -- Minimal steps to go from clone to working extension:
   - `git clone --recurse-submodules`
   - `just setup` (installs dev tools, configures DuckDB test runner)
   - `just build` (builds debug extension)
   - `just test-rust` (runs unit tests)
   - `just test-sql` (runs SQL logic tests via DuckDB)

3. **Architecture Overview** -- Map source tree to concepts:
   - Use the tree format from 05-RESEARCH.md Pattern 7 (MAINTAINER.md Source Tree Overview Pattern)
   - Brief description of each file/directory's role
   - Explain the data flow: JSON definition -> model.rs -> catalog.rs -> expand.rs -> SQL string -> DuckDB execution
   - Explain the feature flag split: `default` (bundled, for tests) vs `extension` (loadable, for DuckDB)
   - Mention the sidecar persistence pattern (write to file from invoke, read on next load)

4. **Building** -- How to build:
   - `just build` for debug, `just build-release` for release
   - Explain `Cargo.toml` (analogous to `pyproject.toml`) and `Makefile` roles
   - Explain `crate-type = ["cdylib", "lib"]` -- cdylib produces the .duckdb_extension shared library, lib enables tests and fuzzing
   - Explain the Makefile delegates to cargo with `--no-default-features --features extension`
   - Common build errors and their fixes (missing submodules, wrong Rust version)

5. **Testing** -- All test types:
   - `just test-rust` -- Rust unit tests (runs with bundled DuckDB, no extension loading)
   - `just test-sql` -- SQL logic tests (builds extension, loads it in DuckDB, runs test/sql/*.test files)
   - `just test-iceberg` -- DuckLake/Iceberg integration test (requires `just setup-ducklake` first)
   - `just test-all` -- Runs all three
   - `just coverage` -- Coverage report (80% threshold)
   - `just lint` -- Formatting, clippy, cargo-deny
   - Explain the difference between `cargo test` (bundled DuckDB, no LOAD) and `just test-sql` (real LOAD, catches ABI issues)

6. **Loading the Extension** -- How to use the built extension:
   - Python context (primary): `import duckdb; con = duckdb.connect(); con.install_extension('build/debug/semantic_views.duckdb_extension', force_install=True); con.load_extension('semantic_views')`
   - Show a complete worked example: define a semantic view, query it, explain it
   - Note the build/debug vs build/release paths

7. **Updating the DuckDB Version Pin** -- Just the steps:
   - Where the version is pinned: `Cargo.toml` (duckdb and libduckdb-sys version), `Makefile` (TARGET_DUCKDB_VERSION), CI workflow files (duckdb_version)
   - Steps: update all four locations, run `just build && just test-all`, commit
   - Note: the DuckDBVersionMonitor workflow automates detection of new versions

8. **Fuzzing** -- How to run and manage fuzz targets:
   - What fuzzing is (1-2 sentence analogy: "like Python's hypothesis but for binary data -- generates random inputs to find crashes")
   - Install nightly toolchain: `rustup install nightly`
   - Install cargo-fuzz: `cargo install cargo-fuzz`
   - `just fuzz` to run default target, `just fuzz target=fuzz_sql_expand` for specific target
   - `just fuzz-all` for all targets
   - `cargo fuzz list` to see available targets
   - Describe the three targets and what each covers
   - Corpus management: `just fuzz-cmin` to minimize, corpus lives in `fuzz/corpus/` (committed to repo)
   - Interpreting crashes: artifacts in `fuzz/artifacts/`, reproduce with `cargo fuzz run <target> <artifact-path>`
   - Nightly CI: runs automatically, opens GitHub issue on crash, submits corpus update PRs

9. **Publishing to Community Extension Registry** -- The process:
   - Reference `description.yml` format from 05-RESEARCH.md Pattern 7
   - Explain: fork `duckdb/community-extensions`, add `description.yml` for `semantic_views`, submit PR
   - List the required fields and what they map to in this project
   - Note excluded platforms and required toolchains
   - Note this is a one-time setup; subsequent versions update the `ref` field

10. **Worked Examples** -- Common extension tasks:
    - **Adding a new DDL function** (e.g., a hypothetical `rename_semantic_view`):
      - Create src/ddl/rename.rs with VScalar implementation
      - Register in src/lib.rs entrypoint
      - Add `#[cfg(feature = "extension")]` gate
      - Add SQL logic test in test/sql/
      - Update list in MAINTAINER.md architecture section
    - **Adding a new metric type** (e.g., a hypothetical `window` metric type):
      - Update src/model.rs with new field or variant
      - Update src/expand.rs SQL generation logic
      - Add unit tests in expand.rs
      - Add proptest property if applicable
      - Update fuzz seed corpus if the JSON schema changes

11. **Troubleshooting** -- Common errors and fixes:
    - "Symbol not found" / ABI mismatch when LOADing -- version pin mismatch between Cargo.toml and DuckDB binary
    - "cargo test" passes but "just test-sql" fails -- the bundled feature masks LOAD issues; always run SQL logic tests
    - Clippy pedantic lint failures -- explain priority = -1 pattern and how to add `#[allow(...)]` for legitimate cases
    - Linker errors with "loadable-extension" -- explain the feature flag split and why `cargo test` must use default features
    - Fuzz target won't compile -- needs nightly toolchain, check `rustup show` for active toolchain

12. **CI Workflows** -- Brief description of each:
    - PullRequestCI.yml -- Fast check on PRs (Linux x86_64 only)
    - MainDistributionPipeline.yml -- Full 5-platform build on main/release pushes
    - CodeQuality.yml -- Formatting, linting, coverage
    - DuckDBVersionMonitor.yml -- Weekly check for new DuckDB releases
    - NightlyFuzz.yml -- Daily fuzzing with crash reporting

**Tone guidelines (from CONTEXT.md):**
- Rust concept explanations feel like footnotes, not lectures
- One-liner Python analogies where possible (e.g., "Cargo.toml is Rust's pyproject.toml")
- Explain "why" behind troubleshooting fixes
- This is the SINGLE doc a contributor needs -- no "see also" chains for essential workflows
- DuckDB install context: user uses DuckDB through Python (`pip install duckdb`)
  </action>
  <verify>
    <automated>test -f /Users/paul/Documents/Dev/Personal/duckdb-semantic-views/MAINTAINER.md && wc -l /Users/paul/Documents/Dev/Personal/duckdb-semantic-views/MAINTAINER.md | awk '{if ($1 >= 200) print "PASS: "$1" lines"; else print "FAIL: only "$1" lines"}'</automated>
    <manual>Read through MAINTAINER.md and verify: (1) a Python expert could follow it without Rust knowledge, (2) all 12 sections are present and equally detailed, (3) architecture overview maps every src/ file, (4) two worked examples are included, (5) no "see also" chains to external docs for essential workflows</manual>
    <sampling_rate>run after this task commits, before next task begins</sampling_rate>
  </verify>
  <done>
    - MAINTAINER.md exists at project root with 200+ lines
    - All 12 sections present: Prerequisites, Quick Start, Architecture, Building, Testing, Loading, Version Pin Update, Fuzzing, Publishing, Worked Examples, Troubleshooting, CI Workflows
    - Rust concepts explained with Python analogies
    - Architecture overview maps every file in src/ to its role
    - Two worked examples: adding a DDL function, adding a metric type
    - Troubleshooting covers the 5 most common errors
    - A Python expert new to Rust could follow the doc without external research
    - DOCS-01 requirement is satisfied
  </done>
</task>

</tasks>

<verification>
1. MAINTAINER.md exists and is comprehensive (200+ lines)
2. All required sections are present and equally detailed
3. Architecture overview matches actual source tree
4. Worked examples reference real files and patterns
5. Fuzzing section references actual fuzz targets and Justfile recipes from Plan 05-01
6. No broken references to files or commands that don't exist
</verification>

<success_criteria>
- A contributor with Python expertise and no Rust experience can follow MAINTAINER.md to: set up dev environment, build the extension, run all tests, load in DuckDB Python shell, update version pin, run fuzzer, and understand the publishing process
- DOCS-01 requirement is fully satisfied
</success_criteria>

<output>
After completion, create `.planning/phases/05-hardening-and-docs/05-02-SUMMARY.md`
</output>
