---
phase: 36-registry-publishing-maintainer-docs
plan: 02
type: execute
wave: 1
depends_on: []
files_modified:
  - MAINTAINER.md
  - examples/snowflake_parity.py
autonomous: true
requirements:
  - MAINT-01
  - MAINT-02
  - MAINT-03

must_haves:
  truths:
    - "MAINTAINER.md documents multi-version branching strategy (main vs duckdb/1.4.x)"
    - "MAINTAINER.md documents CE registry update process for new releases"
    - "MAINTAINER.md documents how to bump DuckDB version on both branches"
    - "MAINTAINER.md uses anentropic GitHub org everywhere (no paul-rl references)"
    - "MAINTAINER.md worked examples use native DDL syntax (no function-based DDL)"
    - "examples/snowflake_parity.py demonstrates v0.5.4 features"
  artifacts:
    - path: "MAINTAINER.md"
      provides: "Complete maintainer documentation"
      contains: "Multi-Version Branching Strategy"
    - path: "examples/snowflake_parity.py"
      provides: "v0.5.4 milestone example"
      contains: "UNIQUE"
  key_links:
    - from: "MAINTAINER.md"
      to: "description.yml"
      via: "CE publishing section references description.yml workflow"
      pattern: "description.yml"
    - from: "examples/snowflake_parity.py"
      to: "build/debug/semantic_views.duckdb_extension"
      via: "LOAD extension path"
      pattern: "semantic_views.duckdb_extension"
---

<objective>
Update MAINTAINER.md with targeted edits (multi-branch strategy, CE update process, DuckDB version bump, native DDL examples, correct GitHub username) and create the end-of-milestone Python example.

Purpose: MAINTAINER.md is the canonical contributor guide -- it must reflect the current state of the project (native DDL, dual-branch workflow, CE publishing). The Python example documents v0.5.4 features for users.
Output: Updated MAINTAINER.md, new examples/snowflake_parity.py
</objective>

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

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/36-registry-publishing-maintainer-docs/36-CONTEXT.md
@.planning/phases/36-registry-publishing-maintainer-docs/36-RESEARCH.md

<interfaces>
<!-- Existing example patterns from examples/ directory -->

From examples/basic_ddl_and_query.py (pattern to follow):
```python
#!/usr/bin/env python3
# /// script
# dependencies = ["duckdb==1.5.0"]
# requires-python = ">=3.10"
# ///
import duckdb
con = duckdb.connect(config={"allow_unsigned_extensions": "true"})
con.execute("LOAD 'build/debug/semantic_views.duckdb_extension'")
```

From examples/advanced_features.py (section header pattern):
```python
# ============================================================
# Section N: Title -- Description
# ============================================================
print("\n=== Section N: Title -- Description ===")
```
</interfaces>
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update MAINTAINER.md with targeted edits</name>
  <files>MAINTAINER.md</files>
  <read_first>
    - MAINTAINER.md (full file -- understand existing structure before making targeted edits)
    - .github/workflows/Build.yml (reference for multi-version CI documentation, lines 1-40)
    - .github/workflows/DuckDBVersionMonitor.yml (reference for version bump documentation, first 50 lines)
    - .duckdb-version (current version pin value)
    - .planning/phases/36-registry-publishing-maintainer-docs/36-RESEARCH.md (section update plan and content templates)
  </read_first>
  <action>
    Make targeted surgical edits to MAINTAINER.md per D-09. Preserve all sections not listed below.

    **Edit 1 (D-01): Fix GitHub username in Quick Start (line 41)**
    Change: `git clone --recurse-submodules https://github.com/paul-rl/duckdb-semantic-views.git`
    To: `git clone --recurse-submodules https://github.com/anentropic/duckdb-semantic-views.git`

    **Edit 2 (D-12): Replace "Complete Worked Example" (lines 237-288) with native DDL**
    Replace the entire `define_semantic_view()` / `semantic_query()` example with native DDL using `CREATE SEMANTIC VIEW` and `semantic_view()`. Use the content from RESEARCH.md "MAINTAINER.md Worked Example (Native DDL)" section. Include `install_extension` / `load_extension` pattern (not the `LOAD` string path pattern -- MAINTAINER.md is for contributors who build locally). The example should show:
    - CREATE TABLE with sample data
    - CREATE SEMANTIC VIEW with TABLES, DIMENSIONS, METRICS
    - semantic_view() query
    - explain_semantic_view() for introspection
    - SHOW SEMANTIC VIEWS
    - DESCRIBE SEMANTIC VIEW
    - DROP SEMANTIC VIEW

    **Edit 3 (D-10, MAINT-01): Add "Multi-Version Branching Strategy" section**
    Insert a new section after "Updating the DuckDB Version Pin" (after line 335) and before "Fuzzing". Content:

    ```markdown
    ## Multi-Version Branching Strategy

    The extension supports two DuckDB version tracks via separate branches:

    | Branch | DuckDB Version | Purpose | Version Format |
    |--------|---------------|---------|----------------|
    | `main` | Latest (currently 1.5.x) | Primary development, CE registry `ref` | `0.5.4` |
    | `duckdb/1.4.x` | 1.4.x (Andium LTS) | LTS compatibility | `0.5.4+duckdb1.4` |

    ### Development Workflow

    1. **New features**: Develop on milestone branches (e.g., `milestone/v0.5.4`), squash-merge to `main`
    2. **Cherry-pick to LTS**: After main is stable, cherry-pick relevant commits to `duckdb/1.4.x`
    3. **Version bumps**: Each branch tracks its own DuckDB version in `.duckdb-version`

    ### Syncing Changes Between Branches

    ```bash
    # Cherry-pick a commit from main to LTS
    git checkout duckdb/1.4.x
    git cherry-pick <commit-sha>
    # Resolve any DuckDB API differences (e.g., parser_extension_compat.hpp)
    just test-all
    ```

    ### CI Coverage

    Both branches run the full Build.yml pipeline on push. The DuckDB Version Monitor
    checks for new releases of both the latest and LTS version lines (weekly, Monday 09:00 UTC).
    ```

    **Edit 4 (D-13, MAINT-03): Extend "Updating the DuckDB Version Pin" to cover both branches**
    Add a subsection at the end of the existing "Updating the DuckDB Version Pin" section (before the new Multi-Version section). Content:

    ```markdown
    ### Bumping DuckDB on the LTS Branch

    The `duckdb/1.4.x` branch follows the same process but targets LTS releases:

    1. Check out the LTS branch: `git checkout duckdb/1.4.x`
    2. Update `.duckdb-version` to the new LTS version (e.g., `v1.4.5`)
    3. Update `Cargo.toml`: `duckdb = { version = "=1.4.5", ... }` and `libduckdb-sys = "=1.4.5"`
    4. Update Python PEP 723 headers and CI workflow files (same sed/search as main)
    5. Run `just build && just test-all`
    6. The Cargo.toml `version` field on LTS uses build metadata: `0.5.4+duckdb1.4`

    The DuckDB Version Monitor has separate jobs for latest (`check-latest`) and LTS (`check-lts`)
    that automate this process on their respective branches.
    ```

    **Edit 5 (D-11, MAINT-02): Rewrite "Publishing to Community Extension Registry" (lines 430-481)**
    Replace the entire section with updated content including:
    - Reference to `description.yml` at repo root (per D-08)
    - Correct GitHub org `anentropic` (per D-01)
    - Native DDL hello_world (per D-02)
    - Step-by-step CE update process for new releases
    - Field reference table (keep but update)

    New content for the section:

    ```markdown
    ## Publishing to Community Extension Registry

    The extension is published to the [DuckDB Community Extension Registry](https://duckdb.org/community_extensions/development).

    ### description.yml

    The registry descriptor lives at `description.yml` in the repo root. It specifies the extension
    metadata, build configuration, and hello_world example that appears on the CE page.

    Key fields:
    | Field | Value | Notes |
    |-------|-------|-------|
    | `name` | `semantic_views` | Must match the LOAD name |
    | `language` / `build` | `Rust` / `cargo` | CE pipeline runs `cargo build` |
    | `license` | `MIT` | Must match LICENSE file |
    | `excluded_platforms` | semicolon-separated | Platforms we cannot support (WASM, musl, mingw, etc.) |
    | `requires_toolchains` | `rust;python3` | Build-time dependencies for CE CI |
    | `ref` | 40-char commit SHA | Points to main branch commit to build from |

    ### Submitting a New Release

    1. Complete the milestone on the milestone branch
    2. Squash-merge to `main` and tag the release (e.g., `v0.5.4`)
    3. Copy the merge commit SHA: `git rev-parse HEAD` (on main)
    4. Update `description.yml`: set `ref` to the new SHA, update `version`
    5. Fork [duckdb/community-extensions](https://github.com/duckdb/community-extensions) (or update existing fork)
    6. Copy `description.yml` to `extensions/semantic_views/description.yml` in the fork
    7. Submit a PR to `duckdb/community-extensions`
    8. Wait for the CE build pipeline to pass (builds across all non-excluded platforms)
    9. After merge, the extension is installable via:
       ```sql
       INSTALL semantic_views FROM community;
       LOAD semantic_views;
       ```

    ### Adding LTS Support

    To publish builds for DuckDB 1.4.x (Andium LTS), add the `andium` field to `description.yml`:
    ```yaml
    repo:
      github: anentropic/duckdb-semantic-views
      ref: <main-branch-sha>
      andium: <duckdb-1.4.x-branch-sha>
    ```
    The CE pipeline will build from `andium` SHA against DuckDB 1.4.x.
    ```

    **Edit 6: Update "Worked Examples" section header area (lines 483+)**
    The "Adding a New DDL Function" and "Adding a New Metric Type" examples use old function-based DDL patterns (`define_semantic_view`, `semantic_query`, `list_semantic_views`, `drop_semantic_view`). Per D-12, update these to use native DDL syntax:
    - Replace `define_semantic_view('name', '...')` references with `CREATE SEMANTIC VIEW name AS ...`
    - Replace `semantic_query(...)` with `semantic_view(...)` table function
    - Replace `list_semantic_views()` with `SHOW SEMANTIC VIEWS`
    - Replace `drop_semantic_view('name')` with `DROP SEMANTIC VIEW name`
    - Replace `rename_semantic_view('old', 'new')` with `ALTER SEMANTIC VIEW old RENAME TO new`
    - Update the SQL logic test example in the "Adding a New DDL Function" section to use native DDL
    - Keep the Rust code patterns as-is (they show VScalar implementation which is still valid for reference, though note in a comment that DDL is now handled via parser hooks, not scalar functions)

    **Verification after all edits:**
    - Search the entire file for `paul-rl` -- must find zero matches
    - Search for `define_semantic_view` in code examples -- must find zero matches (ok in prose explaining history)
    - Search for `semantic_query` in code examples -- must find zero matches
    - Confirm "Multi-Version Branching Strategy" section exists
    - Confirm "Bumping DuckDB on the LTS Branch" subsection exists
    - Confirm "Submitting a New Release" subsection exists
  </action>
  <verify>
    <automated>grep -c 'paul-rl' MAINTAINER.md | grep -q '^0$' && grep -q 'Multi-Version Branching Strategy' MAINTAINER.md && grep -q 'Submitting a New Release' MAINTAINER.md && grep -q 'Bumping DuckDB on the LTS Branch' MAINTAINER.md && grep -q 'anentropic/duckdb-semantic-views' MAINTAINER.md && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - Zero occurrences of `paul-rl` in MAINTAINER.md
    - Section "Multi-Version Branching Strategy" exists with branch table (MAINT-01)
    - Subsection "Submitting a New Release" exists with 9-step process (MAINT-02)
    - Subsection "Bumping DuckDB on the LTS Branch" exists (MAINT-03)
    - Quick Start clone URL uses `anentropic/duckdb-semantic-views`
    - Worked example uses `CREATE SEMANTIC VIEW` (not `define_semantic_view`)
    - Worked example uses `semantic_view()` (not `semantic_query()`)
    - Worked example uses `SHOW SEMANTIC VIEWS` (not `list_semantic_views()`)
    - CE publishing section references `description.yml` at repo root
  </acceptance_criteria>
  <done>MAINTAINER.md has multi-branch docs (MAINT-01), CE update process (MAINT-02), DuckDB version bump for both branches (MAINT-03), correct GitHub org, and native DDL examples</done>
</task>

<task type="auto">
  <name>Task 2: Create examples/snowflake_parity.py</name>
  <files>examples/snowflake_parity.py</files>
  <read_first>
    - examples/basic_ddl_and_query.py (pattern: PEP 723 header, LOAD path, section structure)
    - examples/advanced_features.py (pattern: section headers with print, multiple demos)
  </read_first>
  <action>
    Per D-14: Create `examples/snowflake_parity.py` demonstrating v0.5.4 features.

    Use the same pattern as existing examples:
    - PEP 723 header with `duckdb==1.5.0` dependency
    - `uv run examples/snowflake_parity.py` in docstring
    - `allow_unsigned_extensions` config
    - `LOAD 'build/debug/semantic_views.duckdb_extension'`
    - Section headers with `=== ... ===` print format

    The example must demonstrate these v0.5.4 features:

    **Section 1: UNIQUE constraints and cardinality inference**
    - Create tables with both PRIMARY KEY and UNIQUE constraints
    - Show that RELATIONSHIPS infer cardinality from constraints (no explicit MANY TO ONE keywords)
    - Query that works because cardinality is correctly inferred

    **Section 2: ALTER SEMANTIC VIEW RENAME TO**
    - Create a semantic view, rename it, query under new name
    - Show ALTER SEMANTIC VIEW IF EXISTS on non-existent view (silent no-op)

    **Section 3: SHOW SEMANTIC commands with filtering**
    - SHOW SEMANTIC VIEWS (list all)
    - SHOW SEMANTIC DIMENSIONS IN view_name
    - SHOW SEMANTIC METRICS IN view_name
    - SHOW SEMANTIC DIMENSIONS LIKE '%pattern%'
    - SHOW SEMANTIC METRICS STARTS WITH 'prefix'
    - SHOW SEMANTIC FACTS IN view_name (requires FACTS clause in the view)
    - SHOW SEMANTIC DIMENSIONS LIMIT 2

    **Section 4: SHOW SEMANTIC DIMENSIONS FOR METRIC (fan-trap-aware)**
    - Create a view with fan trap potential
    - SHOW SEMANTIC DIMENSIONS IN view FOR METRIC metric_name
    - Show that fan-trap-unsafe dimensions are filtered out

    Data setup:
    - Use a simple e-commerce schema (customers, orders, line_items)
    - customers: id (PK), name, email
    - orders: id (PK), customer_id (FK->customers), region
    - line_items: id (PK), order_id (FK->orders), amount, category
    - Add UNIQUE on customers(email) to demonstrate UNIQUE constraint support
    - Use FACTS for a computed expression to enable SHOW SEMANTIC FACTS demo

    Keep the example self-contained and runnable with `uv run examples/snowflake_parity.py` after `just build`.
  </action>
  <verify>
    <automated>test -f examples/snowflake_parity.py && grep -q 'UNIQUE' examples/snowflake_parity.py && grep -q 'ALTER SEMANTIC VIEW' examples/snowflake_parity.py && grep -q 'SHOW SEMANTIC' examples/snowflake_parity.py && grep -q 'LIKE' examples/snowflake_parity.py && grep -q 'STARTS WITH' examples/snowflake_parity.py && grep -q 'LIMIT' examples/snowflake_parity.py && echo "PASS" || echo "FAIL"</automated>
  </verify>
  <acceptance_criteria>
    - File exists at `examples/snowflake_parity.py`
    - Has PEP 723 header with `duckdb==1.5.0`
    - Has docstring with `uv run examples/snowflake_parity.py`
    - Demonstrates UNIQUE constraints in TABLES clause
    - Demonstrates cardinality inference (no explicit MANY TO ONE)
    - Demonstrates ALTER SEMANTIC VIEW RENAME TO
    - Demonstrates SHOW SEMANTIC DIMENSIONS/METRICS/FACTS with LIKE, STARTS WITH, LIMIT
    - Demonstrates SHOW SEMANTIC DIMENSIONS FOR METRIC
    - Contains FACTS clause to enable SHOW SEMANTIC FACTS
    - Uses section header pattern matching existing examples
  </acceptance_criteria>
  <done>examples/snowflake_parity.py exists, demonstrates all v0.5.4 features (UNIQUE, cardinality inference, ALTER RENAME, SHOW commands with LIKE/STARTS WITH/LIMIT, FOR METRIC), runnable after `just build`</done>
</task>

</tasks>

<verification>
- `grep -c 'paul-rl' MAINTAINER.md` returns 0
- `grep -q 'Multi-Version Branching Strategy' MAINTAINER.md` succeeds
- `grep -q 'UNIQUE' examples/snowflake_parity.py` succeeds
- `just test-all` passes (MAINTAINER.md and example changes should not break tests)
</verification>

<success_criteria>
- MAINTAINER.md documents multi-branch strategy, CE update process, DuckDB version bump
- MAINTAINER.md uses `anentropic` everywhere, native DDL in all examples
- examples/snowflake_parity.py demonstrates v0.5.4 features
- All tests pass
</success_criteria>

<output>
After completion, create `.planning/phases/36-registry-publishing-maintainer-docs/36-02-SUMMARY.md`
</output>
