dzql 0.4.3 → 0.4.5

package/README.md

@@ -7,7 +7,7 @@ PostgreSQL-powered framework with automatic CRUD operations, live query subscrip
 - **[Documentation Hub](docs/)** - Complete documentation index
 - **[Getting Started Tutorial](docs/getting-started/tutorial.md)** - Complete tutorial with working todo app
 - **[API Reference](docs/reference/api.md)** - Complete API documentation
-- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents (NEW in v0.2.0)
+- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents
 - **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
 - **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
@@ -32,7 +32,7 @@ await ws.connect();
 const user = await ws.api.save.users({ name: 'Alice' });
 const results = await ws.api.search.users({ filters: { name: 'alice' } });
 
-// NEW in v0.2.0: Live query subscriptions
+// Live query subscriptions
 const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
   { venue_id: 123 },
   (updated) => console.log('Venue changed!', updated)
@@ -59,17 +59,20 @@ See **[Compiler Documentation](docs/compiler/)** for complete usage guide, codin
 ## Testing
 
 ```bash
-# Start test database
-cd tests/test-utils && docker compose up -d
+# From repository root - start test database
+docker compose up -d
+
+# Initialize test database
+bun run test:init
 
 # Run tests
 bun test
 
 # Stop database
-cd tests/test-utils && docker compose down
+docker compose down
 ```
 
-All tests use `bun:test` framework with automatic database setup/teardown. See **[tests/test-utils/README.md](tests/test-utils/README.md)** for details.
+All tests use `bun:test` framework. See **[tests/README.md](../../tests/README.md)** for details.
 
 ## License
 

package/docs/README.md

@@ -7,6 +7,7 @@ Complete documentation for the DZQL PostgreSQL-powered framework.
 New to DZQL? Start here:
 
 - **[Tutorial](getting-started/tutorial.md)** - Complete step-by-step guide with a working todo app
+- **[Interpreter vs Compiler](guides/interpreter-vs-compiler.md)** - Understand the two execution modes
 - **[Subscriptions Quick Start](getting-started/subscriptions-quick-start.md)** - Get real-time subscriptions working in 5 minutes
 
 ## 📖 Guides
@@ -14,6 +15,9 @@ New to DZQL? Start here:
 Feature-specific guides and how-tos:
 
 - **[Live Query Subscriptions](guides/subscriptions.md)** - Real-time denormalized documents
+- **[Many-to-Many Relationships](guides/many-to-many.md)** - Junction table management
+- **[Field Defaults](guides/field-defaults.md)** - Auto-populate fields on create
+- **[Custom Functions](guides/custom-functions.md)** - Extend with PostgreSQL or Bun functions
 - **[Client Stores](guides/client-stores.md)** - Pinia store patterns for Vue.js
 
 ## 📘 Reference
@@ -29,7 +33,7 @@ Complete API documentation:
 - [Quickstart](compiler/QUICKSTART.md) - Get started with the DZQL compiler
 - [Advanced Filters](compiler/ADVANCED_FILTERS.md) - Complex search operators
 - [Coding Standards](compiler/CODING_STANDARDS.md) - Best practices for DZQL code
-- [Comparison](compiler/COMPARISON.md) - DZQL vs other approaches
+- [Comparison](compiler/COMPARISON.md) - Runtime vs compiled side-by-side
 
 ## 🤖 For AI Assistants
 
@@ -40,28 +44,6 @@ Complete API documentation:
 - [npm Package](https://www.npmjs.com/package/dzql)
 - [GitHub Repository](https://github.com/blueshed/dzql)
 - [Issue Tracker](https://github.com/blueshed/dzql/issues)
-- [Changelog](../../../CHANGELOG.md)
-- [Contributing](../../../CONTRIBUTING.md)
-
-## 🏗️ Architecture
-
-Looking for architecture and design docs? See the [repository docs](../../../docs/):
-
-- [Permissions System](../../../docs/architecture/PERMISSIONS.md)
-- [Project Roadmap](../../../docs/architecture/ROADMAP.md)
-- [Subscription Architecture](../../../docs/architecture/SUBSCRIPTIONS_STRATEGY.md)
-
-## 🧪 Development
-
-Contributing to DZQL? See development documentation:
-
-- [TDD Workflow](../../../docs/development/TDD_WORKFLOW.md)
-- [WebSocket Testing](../../../docs/development/WEBSOCKET_TESTING.md)
-- [Claude Web Setup](../../../docs/development/CLAUDE-WEB.md)
-
-## 📦 Package Contents
-
-This documentation is published with the npm package. For repository-wide documentation (contributors, development workflow, architecture), see [`/docs/`](../../../docs/) in the repository root.
 
 ## Need Help?
 

package/docs/compiler/README.md

@@ -6,17 +6,11 @@ The DZQL Compiler transforms declarative entity definitions into optimized Postg
 
 - **[Quickstart Guide](QUICKSTART.md)** - Get started with the compiler in 5 minutes
 
-## Guides
+## Reference
 
 - **[Advanced Filters](ADVANCED_FILTERS.md)** - Complex search operators and patterns
 - **[Coding Standards](CODING_STANDARDS.md)** - Best practices for DZQL code
-
-## Reference
-
-- **[Comparison](COMPARISON.md)** - How DZQL compares to other approaches
-- **[Session Summary](SESSION_SUMMARY.md)** - Development session documentation
-- **[Summary](SUMMARY.md)** - Compiler overview and architecture
-- **[Overnight Build](OVERNIGHT_BUILD.md)** - Batch compilation process
+- **[Comparison](COMPARISON.md)** - Runtime vs compiled side-by-side
 
 ## Using the Compiler
 

package/docs/examples/README.md

@@ -0,0 +1,38 @@
+# DZQL Examples
+
+SQL examples demonstrating DZQL entity registration patterns.
+
+## Files
+
+### blog.sql
+A complete blog application with:
+- Multiple entities (users, posts, comments, tags)
+- Many-to-many relationships (posts ↔ tags)
+- Soft delete
+- FK includes
+- Permission paths
+- Notification paths
+
+### venue-detail-simple.sql
+Basic subscribable definition for venue data.
+
+### venue-detail-subscribable.sql
+Full subscribable with relations and permission paths. Demonstrates:
+- Root entity with FK includes
+- Child entity filtering
+- Permission path syntax
+
+## Usage
+
+These files are meant to be run after DZQL core migrations. See the [Tutorial](../getting-started/tutorial.md) for complete setup instructions.
+
+```bash
+# After setting up your database with DZQL migrations
+psql $DATABASE_URL < examples/blog.sql
+```
+
+## See Also
+
+- [API Reference](../reference/api.md) - Entity registration parameters
+- [Many-to-Many Guide](../guides/many-to-many.md) - M2M configuration
+- [Subscriptions Guide](../guides/subscriptions.md) - Subscribable patterns

package/docs/examples/blog.sql

@@ -0,0 +1,160 @@
+-- ============================================================================
+-- Blog Application Example
+-- ============================================================================
+--
+-- This example demonstrates:
+--   - Multiple related entities (users, posts, comments, tags)
+--   - Many-to-many relationships (posts <-> tags via post_tags junction)
+--   - Soft delete (posts.deleted_at)
+--   - FK includes (dereferencing author, post)
+--   - Permission paths (author can edit/delete own content)
+--   - Notification paths (notify post author when comments added)
+--
+-- To use this example:
+--   1. Create tables first (see CREATE TABLE statements below)
+--   2. Run the dzql.register_entity() calls to enable CRUD operations
+--   3. Use the generated API: save_posts, get_posts, search_posts, etc.
+--
+-- For a complete working example with Docker, tests, and frontend:
+--   See packages/blog/ in the DZQL repository
+--
+-- ============================================================================
+
+-- Create tables
+CREATE TABLE IF NOT EXISTS users (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(255) NOT NULL,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id SERIAL PRIMARY KEY,
+  title VARCHAR(500) NOT NULL,
+  content TEXT NOT NULL,
+  summary TEXT,
+  author_id INT REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW(),
+  deleted_at TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS comments (
+  id SERIAL PRIMARY KEY,
+  content TEXT NOT NULL,
+  post_id INT REFERENCES posts(id),
+  author_id INT REFERENCES users(id),
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Tags table for categorizing posts
+CREATE TABLE IF NOT EXISTS tags (
+  id SERIAL PRIMARY KEY,
+  name VARCHAR(50) UNIQUE NOT NULL,
+  color VARCHAR(7) DEFAULT '#3788d8'
+);
+
+-- Junction table for post-tag many-to-many relationship
+CREATE TABLE IF NOT EXISTS post_tags (
+  post_id INT NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
+  tag_id INT NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+  PRIMARY KEY (post_id, tag_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_post_tags_post_id ON post_tags(post_id);
+CREATE INDEX IF NOT EXISTS idx_post_tags_tag_id ON post_tags(tag_id);
+
+-- ============================================================================
+-- DZQL Entity Registrations
+-- ============================================================================
+
+-- Users entity - blog authors
+select dzql.register_entity(
+  'users',
+  'name',
+  array['name', 'email'],
+  '{}',  -- no FK includes
+  false, -- hard delete
+  '{}',  -- no reverse FK
+  '{}',  -- no notifications
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view users
+    'create', array[]::text[],         -- Anyone can register
+    'update', array['@id'],            -- Only update own profile
+    'delete', array['@id']             -- Only delete own account
+  )
+);
+
+-- Register tags entity first
+select dzql.register_entity(
+  'tags',
+  'name',
+  array['name'],
+  '{}',  -- no FK includes
+  false, -- hard delete
+  '{}',  -- no temporal
+  '{}',  -- no notifications
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view tags
+    'create', array[]::text[],         -- Anyone can create tags
+    'update', array[]::text[],         -- Anyone can update tags
+    'delete', array[]::text[]          -- Anyone can delete tags
+  )
+);
+
+-- Posts entity - blog posts with M2M tags
+select dzql.register_entity(
+  'posts',
+  'title',
+  array['title', 'content', 'summary'],
+  jsonb_build_object(
+    'author', 'users'  -- FK to users
+  ),
+  true,  -- soft delete (deleted_at)
+  '{}',  -- no temporal
+  '{}',  -- no notification paths
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view posts
+    'create', array[]::text[],         -- Anyone can create posts
+    'update', array['@author_id'],     -- Only author can update
+    'delete', array['@author_id']      -- Only author can delete
+  ),
+  jsonb_build_object(
+    'many_to_many', jsonb_build_object(
+      'tags', jsonb_build_object(
+        'junction_table', 'post_tags',
+        'local_key', 'post_id',
+        'foreign_key', 'tag_id',
+        'target_entity', 'tags',
+        'id_field', 'tag_ids',
+        'expand', true  -- Include full tag objects in response
+      )
+    )
+  )  -- graph_rules with M2M
+);
+
+-- Comments entity - blog comments
+select dzql.register_entity(
+  'comments',
+  'content',
+  array['content'],
+  jsonb_build_object(
+    'post', 'posts',
+    'author', 'users'
+  ),
+  false, -- hard delete
+  '{}',  -- no reverse FK
+  jsonb_build_object(
+    'post_author', array['@post_id->posts.author_id'],
+    'commenters', array['@post_id']
+  ),
+  jsonb_build_object(
+    'view', array[]::text[],           -- Anyone can view comments
+    'create', array[]::text[],         -- Anyone can comment
+    'update', array['@author_id'],     -- Only author can update
+    'delete', array[
+      '@author_id',                    -- Author can delete
+      '@post_id->posts.author_id'      -- Post author can delete
+    ]
+  )
+);

package/docs/examples/venue-detail-simple.sql

@@ -0,0 +1,8 @@
+-- Simplified test subscribable for initial testing
+SELECT dzql.register_subscribable(
+  'venue_detail',
+  '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',
+  '{"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}}'::jsonb
+);

package/docs/examples/venue-detail-subscribable.sql

@@ -0,0 +1,45 @@
+-- Example: Venue Detail Subscribable
+-- This subscribable builds a denormalized document containing:
+-- - The venue record
+-- - The organization (FK expanded)
+-- - All sites belonging to the venue
+-- - All packages with their allocations
+
+SELECT dzql.register_subscribable(
+  'venue_detail',
+
+  -- Permission: who can subscribe?
+  -- Users who act_for the venue's organization (active roles only)
+  jsonb_build_object(
+    'subscribe', ARRAY['@org_id->acts_for[org_id=$]{active}.user_id']
+  ),
+
+  -- Parameters: subscription key
+  jsonb_build_object(
+    'venue_id', 'int'
+  ),
+
+  -- Root entity
+  'venues',
+
+  -- Relations to include in document
+  jsonb_build_object(
+    -- FK expansion: organisation
+    'org', 'organisations',
+
+    -- Child collection: sites
+    'sites', jsonb_build_object(
+      'entity', 'sites',
+      'filter', 'venue_id=$venue_id'
+    ),
+
+    -- Child collection: packages with nested allocations
+    'packages', jsonb_build_object(
+      'entity', 'packages',
+      'filter', 'venue_id=$venue_id',
+      'include', jsonb_build_object(
+        'allocations', 'allocations'
+      )
+    )
+  )
+);

package/docs/for-ai/claude-guide.md

@@ -2,6 +2,38 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Quick Reference Card
+
+```
+DZQL QUICK REFERENCE
+====================
+
+5 Operations:     get, save, delete, lookup, search
+2 Modes:          Interpreter (runtime) | Compiler (static SQL)
+Client API:       ws.api.{operation}.{entity}(params)
+Server API:       db.api.{operation}.{entity}(params, userId)
+
+Entity Registration:
+  dzql.register_entity(
+    table_name,           -- 'todos'
+    label_field,          -- 'title' (for lookups)
+    searchable_fields,    -- ARRAY['title', 'description']
+    fk_includes,          -- '{"org": "organisations"}'
+    soft_delete,          -- false
+    temporal_fields,      -- '{}'
+    notification_paths,   -- '{"ownership": ["@org_id->acts_for..."]}'
+    permission_paths,     -- '{"view": [], "create": [...]}'
+    graph_rules,          -- '{"on_create": {...}, "many_to_many": {...}}'
+    field_defaults        -- '{"owner_id": "@user_id"}'
+  )
+
+M2M id_field naming:  tag_ids (singular + _ids), NOT tags_ids
+Permission [] = public, omitted = denied
+Path syntax: @field->table[filter]{temporal}.target_field
+
+Compile: dzql compile entities.sql -o compiled/
+```
+
 ## Project Overview
 
 DZQL is a PostgreSQL-powered framework that eliminates CRUD boilerplate by providing automatic database operations, real-time WebSocket synchronization, and graph-based relationship management. The core concept: register an entity in PostgreSQL and instantly get 5 standard operations (get, save, delete, lookup, search) plus real-time notifications with zero code.

package/docs/guides/interpreter-vs-compiler.md

@@ -0,0 +1,237 @@
+# Interpreter vs Compiler Mode
+
+DZQL offers two execution modes for your entities. Understanding when to use each is fundamental to getting the best out of the framework.
+
+## Quick Summary
+
+| Aspect | Interpreter | Compiler |
+|--------|-------------|----------|
+| **Setup** | Register entity, use immediately | Register entity, compile, deploy SQL |
+| **Performance** | ~8-12ms per operation | ~2-4ms per operation |
+| **Debugging** | Opaque (dynamic SQL) | Transparent (static SQL) |
+| **Best For** | Development, prototyping | Production, performance-critical |
+
+## How It Works
+
+### Interpreter Mode (Runtime)
+
+Entity configuration is stored as JSON in `dzql.entities` table and parsed at runtime:
+
+```
+Client Request → generic_exec() → Parse JSON config → Build SQL → Execute
+```
+
+**Characteristics:**
+- Zero build step - changes take effect immediately
+- JSON config parsed on every request
+- Dynamic SQL generated at runtime
+- Generic query plans (harder to optimize)
+
+**Usage:**
+```sql
+-- Register entity
+SELECT dzql.register_entity('todos', 'title', ARRAY['title'], ...);
+
+-- Use immediately via generic executor
+SELECT dzql.generic_exec('save', 'todos', '{"title": "Buy milk"}'::jsonb, 1);
+```
+
+### Compiler Mode (Static)
+
+Entity configuration is compiled into dedicated PostgreSQL functions:
+
+```
+Entity Definition → dzql compile → Static SQL Functions → Deploy → Execute
+```
+
+**Characteristics:**
+- Build step required
+- No JSON parsing at runtime
+- Static SQL with specific query plans
+- PostgreSQL can optimize and cache plans
+
+**Usage:**
+```bash
+# Compile entities to SQL
+dzql compile entities.sql -o compiled/
+
+# Deploy to database
+psql < compiled/entities.sql
+```
+
+```sql
+-- Use compiled functions directly
+SELECT save_todos('{"title": "Buy milk"}'::jsonb, 1);
+```
+
+## The Server Automatically Chooses
+
+The DZQL server (`db.js`) automatically tries compiled functions first:
+
+```javascript
+// In callDZQLOperation()
+try {
+  // Try compiled function: save_todos()
+  const result = await sql.unsafe(`SELECT save_todos($1, $2)`, [data, userId]);
+  return result[0].result;
+} catch (error) {
+  // If compiled function doesn't exist, fall back to interpreter
+  if (error.message.includes('save_todos') && error.code === '42883') {
+    return await sql`SELECT dzql.generic_exec('save', 'todos', ${data}, ${userId})`;
+  }
+  throw error;
+}
+```
+
+This means you can:
+1. Start with interpreter mode during development
+2. Compile and deploy when ready for production
+3. Mix and match - some entities compiled, others interpreted
+
+## Performance Comparison
+
+### Interpreter (Runtime Parsing)
+
+```sql
+SELECT dzql.generic_exec('save', 'venues', '{"name": "MSG"}'::jsonb, 42);
+```
+
+**Execution steps:**
+1. Fetch entity config from `dzql.entities` (table lookup)
+2. Parse `permission_paths` JSONB
+3. Build permission query dynamically
+4. Parse `graph_rules` JSONB
+5. Execute rules via dynamic SQL
+6. Parse `notification_paths` JSONB
+7. Resolve paths dynamically
+8. Execute the actual save
+
+**Cost:** ~8-12ms, 3-5 JSONB parses, unpredictable query plans
+
+### Compiler (Pre-built Functions)
+
+```sql
+SELECT save_venues('{"name": "MSG"}'::jsonb, 42);
+```
+
+**Execution steps:**
+1. Call `can_update_venues()` - pre-compiled permission check
+2. Execute INSERT/UPDATE - direct SQL
+3. Call `graph_venues_on_create()` - pre-compiled graph rules
+4. Call `resolve_notification_paths_venues()` - pre-compiled
+5. Done
+
+**Cost:** ~2-4ms, 0 JSONB parses, optimized query plans
+
+## When to Use Each
+
+### Use Interpreter When:
+- Rapid prototyping and development
+- Schema changes frequently
+- Learning DZQL concepts
+- Small applications with low traffic
+- Need maximum flexibility
+
+### Use Compiler When:
+- Production deployments
+- Performance is critical
+- Need predictable query performance
+- Want reviewable/auditable SQL
+- Large teams (generated SQL is easy to review)
+- Complex permission or graph rules
+
+### Recommended Workflow:
+1. **Development:** Use interpreter for fast iteration
+2. **Staging:** Compile and test performance
+3. **Production:** Deploy compiled functions
+
+## Compiling Entities
+
+### Via CLI
+
+```bash
+# Single file
+dzql compile database/entities.sql -o compiled/
+
+# Multiple files
+dzql compile database/*.sql -o compiled/
+```
+
+### Programmatically
+
+```javascript
+import { DZQLCompiler } from 'dzql/compiler';
+
+const compiler = new DZQLCompiler();
+const result = compiler.compileFromSQL(sqlContent);
+
+console.log(result.sql);  // Generated PostgreSQL functions
+```
+
+### What Gets Generated
+
+For each entity, the compiler generates:
+
+| Function | Purpose |
+|----------|---------|
+| `get_{entity}(id, user_id)` | Retrieve single record |
+| `save_{entity}(data, user_id)` | Create or update |
+| `delete_{entity}(id, user_id)` | Delete record |
+| `lookup_{entity}(term, user_id)` | Autocomplete search |
+| `search_{entity}(filters, user_id)` | Paginated search |
+| `can_view_{entity}(user_id, record)` | Permission check |
+| `can_create_{entity}(user_id, record)` | Permission check |
+| `can_update_{entity}(user_id, record)` | Permission check |
+| `can_delete_{entity}(user_id, record)` | Permission check |
+
+## Debugging
+
+### Interpreter Mode
+
+Debugging is harder because SQL is generated dynamically:
+
+```sql
+-- You see this
+EXPLAIN ANALYZE SELECT dzql.generic_exec('save', 'venues', '...');
+
+-- But the actual query is hidden inside
+```
+
+### Compiler Mode
+
+Standard PostgreSQL tools work:
+
+```sql
+-- See the actual function
+\sf save_venues
+
+-- Analyze performance
+EXPLAIN ANALYZE SELECT save_venues('{"name": "MSG"}'::jsonb, 42);
+
+-- Check slow queries
+SELECT * FROM pg_stat_statements WHERE query LIKE '%save_venues%';
+```
+
+## Feature Parity
+
+Both modes support the same features:
+
+| Feature | Interpreter | Compiler |
+|---------|-------------|----------|
+| CRUD operations | ✅ | ✅ |
+| Permission paths | ✅ | ✅ |
+| Graph rules | ✅ | ✅ |
+| Notification paths | ✅ | ✅ |
+| FK includes | ✅ | ✅ |
+| Many-to-many | ✅ | ✅ |
+| Field defaults | ✅ | ✅ |
+| Soft delete | ✅ | ✅ |
+| Temporal fields | ✅ | ✅ |
+
+The difference is purely in execution speed and debuggability, not functionality.
+
+## See Also
+
+- [Compiler Quickstart](../compiler/QUICKSTART.md) - Get started with compilation
+- [Compiler Comparison](../compiler/COMPARISON.md) - Detailed side-by-side analysis
+- [API Reference](../reference/api.md) - The 5 operations

package/docs/guides/many-to-many.md

@@ -161,6 +161,23 @@ SELECT dzql.register_entity(
 | `id_field` | Yes | Field name for ID array in API | `"tag_ids"` |
 | `expand` | No | Include full objects (default: false) | `false` or `true` |
 
+### Naming Convention for `id_field`
+
+**Important:** The `id_field` should use the **singular** form of the target entity, not plural:
+
+| Target Entity | Correct `id_field` | Wrong |
+|---------------|-------------------|-------|
+| `tags` | `tag_ids` | `tags_ids` |
+| `roles` | `role_ids` | `roles_ids` |
+| `categories` | `category_ids` | `categories_ids` |
+| `users` | `user_ids` | `users_ids` |
+
+This convention matches common ORM patterns and is more readable:
+- `tag_ids: [1, 2, 3]` reads as "tag IDs"
+- `tags_ids: [1, 2, 3]` reads awkwardly as "tags IDs"
+
+Using the wrong naming will cause the M2M sync to fail because the generated code looks for a field name that doesn't match what clients send.
+
 ### The `expand` Flag
 
 Controls whether full related objects are included in responses:

package/docs/guides/subscriptions.md

@@ -28,7 +28,7 @@ Live Query Subscriptions (Pattern 1 from vision.md) enable clients to subscribe
 Create a SQL file with your subscribable definition:
 
 ```sql
--- examples/subscribables/venue_detail.sql
+-- examples/venue-detail-subscribable.sql
 SELECT dzql.register_subscribable(
   'venue_detail',
   '{"subscribe": ["@org_id->acts_for[org_id=$]{active}.user_id"]}'::jsonb,
@@ -56,7 +56,7 @@ SELECT dzql.register_subscribable(
 ```bash
 # Compile subscribable to SQL functions
 bun packages/dzql/src/compiler/cli/compile-subscribable.js \
-  examples/subscribables/venue_detail.sql \
+  examples/venue-detail-subscribable.sql \
   > /tmp/venue_detail.sql
 
 # Deploy to database