---
phase: 22-documentation
plan: 01
type: execute
wave: 1
depends_on: []
files_modified: [README.md]
autonomous: true
requirements: [DOC-01]

must_haves:
  truths:
    - "README shows native DDL syntax (CREATE SEMANTIC VIEW) as the primary interface"
    - "All 7 DDL verbs appear with examples: CREATE, CREATE OR REPLACE, CREATE IF NOT EXISTS, DROP, DROP IF EXISTS, DESCRIBE, SHOW"
    - "A lifecycle worked example demonstrates create -> query -> describe -> drop"
    - "Version string is updated from v0.4.0 to v0.5.0"
    - "Function-based syntax is retained as a documented alternative"
  artifacts:
    - path: "README.md"
      provides: "DDL syntax reference with worked examples"
      contains: "CREATE SEMANTIC VIEW"
  key_links:
    - from: "README.md DDL examples"
      to: "test/sql/phase20_extended_ddl.test"
      via: "syntax consistency"
      pattern: "CREATE SEMANTIC VIEW|DROP SEMANTIC VIEW|DESCRIBE SEMANTIC VIEW|SHOW SEMANTIC VIEWS"
---

<objective>
Update the README to replace function-based syntax examples with native DDL syntax and add a DDL reference section covering all 7 DDL verbs with a lifecycle worked example.

Purpose: Users can learn the full DDL syntax from the README without reading source code (DOC-01).
Output: Updated README.md with native DDL as the primary interface, matching the current tone and detail level.
</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/22-documentation/22-RESEARCH.md

@README.md
@test/sql/phase20_extended_ddl.test
@test/sql/phase16_parser.test
</context>

<tasks>

<task type="auto">
  <name>Task 1: Rewrite README with native DDL syntax</name>
  <files>README.md</files>
  <action>
Rewrite README.md following these specific changes. Use the existing tone (short headings, one explanatory sentence + code block, realistic table/column names like `orders`). Do NOT over-document -- match the current level of detail.

**Version update (line 7):**
Change `v0.4.0` to `v0.5.0` (matches Cargo.toml).

**Sections to keep unchanged:**
- Title + intro paragraph (lines 1-5, but update version on line 7)
- "How it works" section (lines 9-17)
- "Loading" section (lines 19-30)
- "Querying" section (lines 98-128) -- query interface is unchanged
- "Building" section (lines 155-168)
- "License" section (lines 170-173)

**Section "Creating a semantic view" (lines 32-96) -- REPLACE with "Defining a semantic view":**
Replace the `create_semantic_view()` function examples with native `CREATE SEMANTIC VIEW` DDL syntax. Keep both single-table and multi-table examples, using the same `orders` / `customers` data the current README uses.

Single-table example:
```sql
CREATE SEMANTIC VIEW orders (
    tables := [{'alias': 'o', 'table': 'orders'}],
    dimensions := [
        {'name': 'region', 'expr': 'region', 'source_table': 'o'},
        {'name': 'category', 'expr': 'category', 'source_table': 'o'},
        {'name': 'order_month', 'expr': "date_trunc('month', created_at)", 'source_table': 'o'}
    ],
    metrics := [
        {'name': 'revenue', 'expr': 'sum(amount)', 'source_table': 'o'},
        {'name': 'order_count', 'expr': 'count(*)', 'source_table': 'o'}
    ]
);
```

Multi-table example (with relationships):
```sql
CREATE SEMANTIC VIEW order_analytics (
    tables := [
        {'alias': 'o', 'table': 'orders'},
        {'alias': 'c', 'table': 'customers'}
    ],
    relationships := [
        {'from_table': 'o', 'to_table': 'c',
         'join_columns': [{'from': 'customer_id', 'to': 'id'}]}
    ],
    dimensions := [
        {'name': 'region', 'expr': 'region', 'source_table': 'o'},
        {'name': 'customer_tier', 'expr': 'tier', 'source_table': 'c'}
    ],
    metrics := [
        {'name': 'revenue', 'expr': 'sum(amount)', 'source_table': 'o'}
    ]
);
```

Keep the note: "Only the tables needed for your requested dimensions/metrics get joined."

**Section "Other DDL functions" (lines 144-153) -- REPLACE with "DDL reference":**
Add one-liner description + code block for each of these DDL verbs:
- `CREATE OR REPLACE SEMANTIC VIEW name (...)` -- overwrites an existing view
- `CREATE SEMANTIC VIEW IF NOT EXISTS name (...)` -- no-op if already exists
- `DROP SEMANTIC VIEW name` -- removes a view
- `DROP SEMANTIC VIEW IF EXISTS name` -- no-op if not found
- `DESCRIBE SEMANTIC VIEW name` -- shows view metadata (dimensions, metrics, etc.)
- `SHOW SEMANTIC VIEWS` -- lists all defined semantic views

Keep the style brief -- one sentence + one code block per verb. Do NOT add column descriptions or formal output tables.

**NEW section "Lifecycle example" -- add AFTER "DDL reference":**
A single continuous SQL block showing the full lifecycle using the `orders` view:
1. CREATE the semantic view
2. Query it with `semantic_view()`
3. DESCRIBE it
4. SHOW SEMANTIC VIEWS
5. DROP it

Use realistic data (the `orders` table already used in other examples). Keep the CREATE compact (fewer dimensions/metrics than the full example above).

**Section "Explain" (lines 130-142) -- KEEP as-is:**
`explain_semantic_view()` remains function-based (no DDL equivalent exists). Keep this section unchanged.

**NEW section "Function syntax" -- add AFTER "Explain" (or after lifecycle):**
Brief 3-4 line note that function-based DDL (`create_semantic_view()`, `drop_semantic_view()`, etc.) still works as an alternative. One sentence + a brief list of function names. Do NOT repeat full examples -- just reference that the functions exist for backward compatibility.

**Final structure should be approximately:**
1. Title + intro (version updated)
2. How it works (unchanged)
3. Loading (unchanged)
4. Defining a semantic view (rewritten with DDL)
5. Querying (unchanged)
6. DDL reference (new -- all verbs)
7. Lifecycle example (new -- worked example)
8. Explain (unchanged)
9. Function syntax (new -- brief alternative note)
10. Building (unchanged)
11. License (unchanged)

**IMPORTANT constraints:**
- README should stay under ~200 lines total (current is 173)
- Copy struct field names exactly from test files: `alias`, `table`, `name`, `expr`, `source_table`, `from_table`, `to_table`, `join_columns`, `from`, `to`
- All DDL examples must end with semicolons
- Do NOT add BNF grammar, formal syntax diagrams, or API tables
- Do NOT add the `CREATE TABLE orders (...)` setup SQL in the main example (current README omits it from the multi-table example; include it only once if at all, like the current README does)
  </action>
  <verify>
    <automated>grep -c "CREATE SEMANTIC VIEW\|DROP SEMANTIC VIEW\|DESCRIBE SEMANTIC VIEW\|SHOW SEMANTIC VIEWS\|CREATE OR REPLACE\|IF NOT EXISTS\|IF EXISTS" README.md</automated>
  </verify>
  <done>README.md contains native DDL syntax as primary interface, all 7 DDL verbs have examples, lifecycle worked example present, version updated to v0.5.0, function syntax noted as alternative, total length under 200 lines</done>
</task>

<task type="auto">
  <name>Task 2: Validate README accuracy and test suite</name>
  <files>README.md</files>
  <action>
Validate the updated README for accuracy and consistency:

1. **Run `just test-all`** to confirm no regressions (this is a doc-only change so all tests must still pass).

2. **Cross-check every SQL code block in the README** against the test files:
   - Every `CREATE SEMANTIC VIEW` example must match struct field patterns from `test/sql/phase20_extended_ddl.test` and `test/sql/phase16_parser.test`
   - Verify struct field names are correct: `alias`, `table`, `name`, `expr`, `source_table`, `from_table`, `to_table`, `join_columns`, `from`, `to`
   - Verify all DDL examples end with semicolons

3. **Verify completeness checklist:**
   - [ ] Version string is `v0.5.0` (not `v0.4.0`)
   - [ ] No remaining `SELECT * FROM create_semantic_view(` in the main flow (function syntax should only appear in the "Function syntax" alternative section, if at all)
   - [ ] All 7 DDL verbs present: CREATE, CREATE OR REPLACE, CREATE IF NOT EXISTS, DROP, DROP IF EXISTS, DESCRIBE, SHOW
   - [ ] Lifecycle example covers: create, query, describe, show, drop
   - [ ] `explain_semantic_view()` still documented as function-based
   - [ ] Querying section unchanged (uses `semantic_view()` function)
   - [ ] Total README length under 200 lines

4. **Fix any issues found** in the cross-check.
  </action>
  <verify>
    <automated>cd /Users/paul/Documents/Dev/Personal/duckdb-semantic-views && just test-all</automated>
  </verify>
  <done>All tests pass, every SQL code block in README matches test file patterns, all 7 DDL verbs present, no stale v0.4.0 references, no stale function syntax in main flow</done>
</task>

</tasks>

<verification>
1. `just test-all` passes (no regressions from documentation-only change)
2. All 7 DDL verbs appear in README with examples
3. At least one lifecycle example (create, query, describe, drop)
4. Version string updated to v0.5.0
5. No stale `create_semantic_view()` calls in the main documentation flow
6. README total length under 200 lines
</verification>

<success_criteria>
- DOC-01 satisfied: README includes DDL syntax reference with worked examples
- A user reading only the README can learn all 7 DDL verbs without reading source code
- The README matches the tone and detail level of the current version (no over-documentation)
- `just test-all` green
</success_criteria>

<output>
After completion, create `.planning/phases/22-documentation/22-01-SUMMARY.md`
</output>
