colliery-io
diff --git a/‎.github/workflows/docs.yml‎
Lines changed: 20 additions & 32 deletions b/‎.github/workflows/docs.yml‎
Lines changed: 20 additions & 32 deletions
diff --git a/‎.metis/strategies/NULL/initiatives/GQLITE-I-0022/initiative.md‎
Lines changed: 87 additions & 37 deletions b/‎.metis/strategies/NULL/initiatives/GQLITE-I-0022/initiative.md‎
Lines changed: 87 additions & 37 deletions
diff --git a/‎.metis/strategies/NULL/initiatives/GQLITE-I-0022/tasks/GQLITE-T-0078.md‎
Lines changed: 141 additions & 0 deletions b/‎.metis/strategies/NULL/initiatives/GQLITE-I-0022/tasks/GQLITE-T-0078.md‎
Lines changed: 141 additions & 0 deletions
@@ -2,11 +2,7 @@ name: Documentation
 
 on:
   push:
-    branches: [main]
     tags: ['v*']
-  pull_request:
-    branches: [main]
-    paths: ['docs/**']
 
 permissions:
   contents: read
@@ -34,21 +30,14 @@ jobs:
       - name: Get version info
         id: version
         run: |
-          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
-            VERSION="${GITHUB_REF#refs/tags/}"
-            echo "version=$VERSION" >> $GITHUB_OUTPUT
-            echo "is_main=false" >> $GITHUB_OUTPUT
-          else
-            echo "version=latest" >> $GITHUB_OUTPUT
-            echo "is_main=true" >> $GITHUB_OUTPUT
-          fi
+          VERSION="${GITHUB_REF#refs/tags/}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Build current docs
         working-directory: docs
         run: mdbook build
 
       - name: Fetch existing docs (for versioning)
-        if: github.event_name == 'push'
         run: |
           mkdir -p _site
           # Try to fetch existing gh-pages content
@@ -58,30 +47,32 @@ jobs:
           fi
 
       - name: Organize versioned docs
-        if: github.event_name == 'push'
         run: |
           VERSION="${{ steps.version.outputs.version }}"
 
-          # For main branch, always update /latest/
-          # For tags, create versioned directory
+          # Create versioned directory
           rm -rf _site/$VERSION
           mkdir -p _site/$VERSION
           cp -r docs/book/* _site/$VERSION/
 
-          # Generate versions.json only from main (tags just add their directory)
-          if [[ "${{ steps.version.outputs.is_main }}" == "true" ]]; then
-            cd _site
-            {
-              echo "["
-              echo "  \"latest\""
-              for v in $(ls -d v[0-9]* 2>/dev/null | sort -Vr | head -10); do
-                echo "  ,\"$v\""
-              done
-              echo "]"
-            } > versions.json
+          # Update latest to point to this version
+          rm -rf _site/latest
+          mkdir -p _site/latest
+          cp -r docs/book/* _site/latest/
+
+          # Update versions.json
+          cd _site
+          {
+            echo "["
+            echo "  \"latest\""
+            for v in $(ls -d v[0-9]* 2>/dev/null | sort -Vr | head -10); do
+              echo "  ,\"$v\""
+            done
+            echo "]"
+          } > versions.json
 
-            # Create index redirect to latest
-            cat > index.html << 'EOF'
+          # Create index redirect to latest
+          cat > index.html << 'EOF'
           <!DOCTYPE html>
           <html>
           <head>
@@ -93,16 +84,13 @@ jobs:
           </body>
           </html>
           EOF
-          fi
 
       - name: Upload artifact
-        if: github.event_name == 'push'
         uses: actions/upload-pages-artifact@v3
         with:
           path: _site
 
   deploy:
-    if: github.event_name == 'push'
     needs: build
     runs-on: ubuntu-latest
     environment:
 
@@ -4,14 +4,14 @@ level: initiative
 title: "Multi-Graph Support via GraphManager and ATTACH"
 short_code: "GQLITE-I-0022"
 created_at: 2025-12-25T20:16:11.339561+00:00
-updated_at: 2025-12-25T20:16:11.339561+00:00
+updated_at: 2026-01-04T14:34:29.624102+00:00
 parent: GQLITE-V-0001
 blocked_by: []
 archived: false
 
 tags:
   - "#initiative"
-  - "#phase/discovery"
+  - "#phase/completed"
 
 
 exit_criteria_met: false
@@ -68,29 +68,23 @@ Key insight: If you frequently query across "separate" graphs, they're arguably
 
 ## Use Cases
 
-### Use Case 1: Multi-Tenant SaaS
-- **Actor**: SaaS platform developer
-- **Scenario**: Each customer gets isolated graph; platform manages lifecycle
-- **Example**: `gm.create("tenant_acme")`, `gm.drop("tenant_acme")`
-- **Outcome**: Complete data isolation, easy onboarding/offboarding
-
-### Use Case 2: Test/Production Separation
-- **Actor**: Developer
-- **Scenario**: Separate graphs for testing without affecting production
-- **Example**: `gm.open("prod")` vs `gm.open("test")`
-- **Outcome**: Safe testing environment
-
-### Use Case 3: Graph Versioning
+### Use Case 1: Graph Versioning
 - **Actor**: Data engineer
-- **Scenario**: Maintain versioned snapshots during migration
-- **Example**: `gm.create("graph_v2")`, migrate, then `gm.drop("graph_v1")`
-- **Outcome**: Safe rollback capability
-
-### Use Case 4: Cross-Graph Analytics
-- **Actor**: Analyst
-- **Scenario**: Correlate entities across domain graphs by shared identifier
-- **Example**: Find users in social graph who purchased in products graph
-- **Outcome**: Ad-hoc cross-domain queries without merging graphs
+- **Scenario**: Maintain versioned snapshots during schema migration or data transformation
+- **Example**: `gm.create("graph_v2")`, migrate data, validate, then `gm.drop("graph_v1")`
+- **Outcome**: Safe rollback capability, ability to compare before/after states
+
+### Use Case 2: Cross-Graph Analytics
+- **Actor**: Analyst or application developer
+- **Scenario**: Correlate entities across separate domain graphs by shared identifier
+- **Example**: Join a knowledge graph with an activity graph via shared entity IDs
+- **Outcome**: Ad-hoc cross-domain queries without merging conceptually separate graphs
+
+### Use Case 3: Domain Isolation in Monolith Applications
+- **Actor**: Application developer
+- **Scenario**: Single application manages multiple independent graph datasets (e.g., a note-taking app with separate graphs per workspace/project)
+- **Example**: `gm.open_or_create("project_alpha")`, `gm.open_or_create("project_beta")`
+- **Outcome**: Clean separation of unrelated data within one application
 
 ## Architecture **[CONDITIONAL: Technically Complex Initiative]**
 
@@ -246,22 +240,78 @@ Each graph is a separate `.db` file; use ATTACH for cross-graph.
 
 ## Implementation Plan
 
-### Phase 1: GraphManager in Bindings
-- Add `GraphManager` to Python bindings (`manager.py`)
-- Add `GraphManager` to Rust bindings (`manager.rs`)
-- Raw SQL cross-graph via ATTACH (no Cypher changes yet)
-- Tests for file management and ATTACH queries
+### Phase 1: C Extension - FROM Clause Support
+
+**Parser Changes (`cypher_gram.y`, `cypher_scanner.l`):**
+- Add `FROM` token handling in MATCH context (distinguish from LOAD CSV FROM)
+- Grammar rule: `match_clause : MATCH pattern_list FROM identifier ...`
+- Store graph name in `cypher_match` AST node
+
+**AST Changes (`cypher_ast.h`, `cypher_ast.c`):**
+- Add `from_graph` field to `cypher_match` struct
+- Update AST construction/destruction functions
+- Add accessor: `cypher_match_get_from_graph()`
+
+**Transform Layer (`transform_match.c`):**
+- When `from_graph` is set, prefix all table references with graph name
+- Example: `nodes` → `{graph_name}.nodes`, `edges` → `{graph_name}.edges`
+- No connection management - just string prefixing in generated SQL
+
+**Testing:**
+- Unit tests for parser accepting/rejecting FROM syntax
+- Transform tests verifying correct table prefixing
+- Ensure backward compatibility (queries without FROM unchanged)
+
+### Phase 2: Binding Layer - GraphManager
 
-### Phase 2: Cypher FROM Clause
-- Add `FROM` token handling in parser (avoid conflict with LOAD CSV FROM)
-- Extend `cypher_match` AST with `from_graph` field
-- Transform layer prefixes table names when `from_graph` set
-- Executor manages coordinator connection with ATTACH
+**Python (`graphqlite/manager.py`):**
+```python
+class GraphManager:
+    def __init__(self, base_path: str)
+    def list(self) -> list[str]
+    def create(self, name: str) -> Graph
+    def open(self, name: str) -> Graph
+    def open_or_create(self, name: str) -> Graph
+    def drop(self, name: str) -> None
+    def query_cross(self, cypher: str, graphs: list[str]) -> Result
+```
+- `query_cross` handles ATTACH to coordinator connection
+- Connection pooling for open graphs
+- Context manager support (`with graphs(...) as gm`)
+
+**Rust (`src/manager.rs`):**
+```rust
+pub struct GraphManager { ... }
+impl GraphManager {
+    pub fn new(base_path: impl AsRef<Path>) -> Result<Self>
+    pub fn list(&self) -> Result<Vec<String>>
+    pub fn create(&mut self, name: &str) -> Result<Graph>
+    pub fn open(&mut self, name: &str) -> Result<Graph>
+    pub fn open_or_create(&mut self, name: &str) -> Result<Graph>
+    pub fn drop(&mut self, name: &str) -> Result<()>
+    pub fn query_cross(&self, cypher: &str, graphs: &[&str]) -> Result<QueryResult>
+}
+```
+
+**ATTACH Coordination:**
+- Maintain a "coordinator" in-memory connection for cross-graph queries
+- Dynamically ATTACH requested graphs before executing
+- DETACH after query completes (or pool attached state)
+
+**Testing:**
+- File creation/deletion
+- Connection lifecycle
+- Cross-graph queries via ATTACH
+- Error handling (missing graphs, permission errors)
 
 ### Phase 3: Documentation & Examples
-- Update README with multi-graph examples
-- Add examples/multi_graph/ tutorials
-- Document cross-graph query patterns and when to use them
+
+- Update README with multi-graph section
+- Add `examples/multi_graph/` with:
+  - Graph versioning workflow
+  - Cross-graph analytics example
+- Document when to use multi-graph vs single graph with better modeling
+- API reference for GraphManager in both Python and Rust docs
 
 ### Design Decisions
 
 
@@ -0,0 +1,141 @@
+---
+id: add-from-token-and-grammar-rule-to
+level: task
+title: "Add FROM token and grammar rule to parser"
+short_code: "GQLITE-T-0078"
+created_at: 2026-01-03T15:38:26.838253+00:00
+updated_at: 2026-01-03T15:55:03.253784+00:00
+parent: GQLITE-I-0022
+blocked_by: []
+archived: false
+
+tags:
+  - "#task"
+  - "#phase/completed"
+
+
+exit_criteria_met: false
+strategy_id: NULL
+initiative_id: GQLITE-I-0022
+---
+
+# Add FROM token and grammar rule to parser
+
+*This template includes sections for various types of tasks. Delete sections that don't apply to your specific use case.*
+
+## Parent Initiative **[CONDITIONAL: Assigned Task]**
+
+[[GQLITE-I-0022]]
+
+## Objective **[REQUIRED]**
+
+{Clear statement of what this task accomplishes}
+
+## Backlog Item Details **[CONDITIONAL: Backlog Item]**
+
+{Delete this section when task is assigned to an initiative}
+
+### Type
+- [ ] Bug - Production issue that needs fixing
+- [ ] Feature - New functionality or enhancement  
+- [ ] Tech Debt - Code improvement or refactoring
+- [ ] Chore - Maintenance or setup work
+
+### Priority
+- [ ] P0 - Critical (blocks users/revenue)
+- [ ] P1 - High (important for user experience)
+- [ ] P2 - Medium (nice to have)
+- [ ] P3 - Low (when time permits)
+
+### Impact Assessment **[CONDITIONAL: Bug]**
+- **Affected Users**: {Number/percentage of users affected}
+- **Reproduction Steps**: 
+  1. {Step 1}
+  2. {Step 2}
+  3. {Step 3}
+- **Expected vs Actual**: {What should happen vs what happens}
+
+### Business Justification **[CONDITIONAL: Feature]**
+- **User Value**: {Why users need this}
+- **Business Value**: {Impact on metrics/revenue}
+- **Effort Estimate**: {Rough size - S/M/L/XL}
+
+### Technical Debt Impact **[CONDITIONAL: Tech Debt]**
+- **Current Problems**: {What's difficult/slow/buggy now}
+- **Benefits of Fixing**: {What improves after refactoring}
+- **Risk Assessment**: {Risks of not addressing this}
+
+## Acceptance Criteria
+
+## Acceptance Criteria
+
+## Acceptance Criteria **[REQUIRED]**
+
+- [ ] {Specific, testable requirement 1}
+- [ ] {Specific, testable requirement 2}
+- [ ] {Specific, testable requirement 3}
+
+## Test Cases **[CONDITIONAL: Testing Task]**
+
+{Delete unless this is a testing task}
+
+### Test Case 1: {Test Case Name}
+- **Test ID**: TC-001
+- **Preconditions**: {What must be true before testing}
+- **Steps**: 
+  1. {Step 1}
+  2. {Step 2}
+  3. {Step 3}
+- **Expected Results**: {What should happen}
+- **Actual Results**: {To be filled during execution}
+- **Status**: {Pass/Fail/Blocked}
+
+### Test Case 2: {Test Case Name}
+- **Test ID**: TC-002
+- **Preconditions**: {What must be true before testing}
+- **Steps**: 
+  1. {Step 1}
+  2. {Step 2}
+- **Expected Results**: {What should happen}
+- **Actual Results**: {To be filled during execution}
+- **Status**: {Pass/Fail/Blocked}
+
+## Documentation Sections **[CONDITIONAL: Documentation Task]**
+
+{Delete unless this is a documentation task}
+
+### User Guide Content
+- **Feature Description**: {What this feature does and why it's useful}
+- **Prerequisites**: {What users need before using this feature}
+- **Step-by-Step Instructions**:
+  1. {Step 1 with screenshots/examples}
+  2. {Step 2 with screenshots/examples}
+  3. {Step 3 with screenshots/examples}
+
+### Troubleshooting Guide
+- **Common Issue 1**: {Problem description and solution}
+- **Common Issue 2**: {Problem description and solution}
+- **Error Messages**: {List of error messages and what they mean}
+
+### API Documentation **[CONDITIONAL: API Documentation]**
+- **Endpoint**: {API endpoint description}
+- **Parameters**: {Required and optional parameters}
+- **Example Request**: {Code example}
+- **Example Response**: {Expected response format}
+
+## Implementation Notes **[CONDITIONAL: Technical Task]**
+
+{Keep for technical tasks, delete for non-technical. Technical details, approach, or important considerations}
+
+### Technical Approach
+{How this will be implemented}
+
+### Dependencies
+{Other tasks or systems this depends on}
+
+### Risk Considerations
+{Technical risks and mitigation strategies}
+
+## Status Updates **[REQUIRED]**
+
+*To be added during implementation*