start getting some docs together

README.md

···
-# Slices Social - A social app for sharing/creating AT Protocol Appviews
+# Slices
 
-Slices Social is an AT Protocol appview that allows users to create and share
-slices (appviews).
+An open-source platform for building AT Protocol appviews with custom data
+schemas, automatic SDK generation, and built-in sync capabilities.
 
-## Architecture
+## Overview
 
-- **API** (`/api`) - Rust backend with AT Protocol integration, PostgreSQL
-  database, and dynamic XRPC handlers
-- **Frontend** (`/frontend`) - Deno server-side rendered application with OAuth
-  authentication
+Slices enables developers to create "slices" - custom appviews within the AT
+Protocol ecosystem. Each slice can define its own lexicons (schemas), sync data
+from other AT Protocol services, and automatically generate type-safe SDKs.
+Think of it as your own customizable view into the AT Protocol network.
 
-## ✅ Completed Features
+### Key Features
 
-### Core Infrastructure
+- **Custom Lexicons**: Define your own data schemas using AT Protocol lexicons
+- **Automatic SDK Generation**: Get type-safe TypeScript clients generated from
+  your lexicons
+- **Data Synchronization**: Import and index data from Bluesky and other AT
+  Protocol services
+- **OAuth Integration**: Built-in AT Protocol authentication
+- **Multi-tenant Architecture**: Each slice operates independently with its own
+  data validated against its lexicons
+- **Dynamic API Endpoints**: CRUD operations automatically created for each
+  lexicon record type (collection)
 
-- [x] AT Protocol OAuth integration with AIP server
-- [x] PostgreSQL database with slice-aware queries
-- [x] Docker containerization with Nix flakes
-- [x] Production deployment pipeline
+## Documentation
 
-### Slice Management
+- [Introduction](./docs/intro.md) - What is Slices and why use it
+- [Getting Started](./docs/getting-started.md) - Set up your first slice
+- [Core Concepts](./docs/concepts.md) - Understand slices, lexicons, and
+  collections
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+- [SDK Usage](./docs/sdk-usage.md) - Using generated TypeScript clients
 
-- [x] Create and manage slice records
-- [x] Define custom lexicons for slices (appviews)
-- [x] Slice-specific data filtering
-- [x] Slice statistics (records, collections, actors)
+## Quick Start
 
-### Data Synchronization
+### Prerequisites
 
-- [x] Bulk sync from AT Protocol repositories based on domain specific lexicons
-- [x] Collection-specific sync with repo filtering
-- [x] Indexing of records into local database
-- [x] Slice-aware record filtering during sync
+- Docker and Docker Compose
+- PostgreSQL
+- Rust (for API development)
+- Deno (for frontend)
 
-### TypeScript Client Generation
+### Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://tangled.sh/justslices.net/core
+cd core
+```
+
+2. Set up environment variables:
 
-- [x] Dynamic TypeScript client generation from lexicons
-- [x] Nested collection structure (e.g.,
-      `client.social.slices.slice.listRecords()`)
-- [x] CRUD operations (create, read, update, delete)
-- [x] OAuth client with PKCE authentication flow
-- [x] Slice-aware collection operations
-- [x] Optional authentication for read-only operations (e.g., listRecords,
-      getRecord)
+Create `.env` files in both `/api` and `/frontend` directories (see
+[Getting Started](./docs/getting-started.md) for details).
+
+3. Start the services:
 
-### Frontend
+```bash
+# Start the API
+cd api
+cargo run
 
-- [x] Server-side rendered pages with HTMX
-- [x] User authentication and session management
-- [x] Slice overview with index statistics
-- [x] Records browser with collection/author filtering
-- [x] Sync interface with collection prefilling from lexicons
-- [x] Settings page to edit profile
-- [x] Encrypted cookie-based sessions
+# In another terminal, start the frontend
+cd frontend
+deno task dev
+```
 
-### API Endpoints
+4. Visit `http://localhost:8000` to access the web interface.
 
-- [x] `/xrpc/social.slices.slice.sync` - Bulk synchronization
-- [x] `/xrpc/social.slices.slice.stats` - Slice statistics
-- [x] `/xrpc/social.slices.slice.records` - Slice records with filtering
-- [x] `/xrpc/social.slices.slice.codegen` - Client code generation (currently
-      TypeScript only, but designed for extensibility)
-- [x] Dynamic collection XRPC endpoints (`*.list`, `*.get`, `*.create`, etc.)
-- [x] OAuth endpoints for authentication flow
+## Project Structure
 
-## 🚧 In Progress/Next Up
+### API (`/api`)
 
-- [ ] Connect to Jetstream
-- [ ] Add search and filtering functionality to records browser, and generated
-      client
-- [ ] Support more complex lexicon types (e.g., unions, arrays, refs)
-- [ ] Lexicon validation
-- [ ] Lexicon verification
-- [ ] SDK examples and tutorials, implement Statusphere Slice
-- [ ] Pagination for large record sets, maybe even a table view would be cool
-- [ ] Slice timeline and user profile pages
-- [ ] Display xprc docs for dynamic endpoints (looking at
-      [Scalar](https://github.com/scalar/scalar))
+The backend is built in Rust and serves as the core AT Protocol integration
+layer. It provides:
 
-## ❌ The Future
+- **AT Protocol XRPC Handlers**: Dynamic endpoints for slice-specific
+  collections with full CRUD operations
+- **Sync Engine**: Bulk synchronization from AT Protocol repositories
+- **Jetstream Integration**: Real-time data streaming from AT Protocol firehose
+- **Database Layer**: PostgreSQL integration with slice-aware queries
+- **SDK Generation**: Automatically generates type-safe TypeScript clients and
+  OpenAPI specifications
+- **OAuth Integration**: Handles AT Protocol OAuth flows and token management
 
-- [ ] Integrated labeler service for basic moderation
-- [ ] Auto view hydration strategies, maybe configureable in the UI
-- [ ] Add pre-defined lexicons straight from Lexicon Community or other sources
-- [ ] Support more languages for client code generation (e.g., Python,
-      Flutter/Dart, Swift)
-- [ ] Integrate/interop with various Microcosm services
-- [ ] Cli tool for codegen and other utilities
-- [ ] Background job processing queue for syncs
-- [ ] Rate limiting and API quotas
-- [ ] API docs
-- [ ] Appview bug tracking, waitlists, feature flags, analytics, etc.
-- [ ] Fork a slice!
-- [ ] Strategies for managing/migrating lexicon changes over time
+### Frontend (`/frontend`)
 
-## 🛠️ Development
+A server-side rendered web application built with Deno that provides:
 
-### Prerequisites
+- **User Interface**: Web-based slice management, records browsing, and sync
+  controls
+- **Authentication**: OAuth integration with session management
+- **Server-Side Rendering**: HTMX-powered interactive UI with minimal
+  client-side JavaScript
+- **Generated Client Integration**: Uses auto-generated TypeScript clients for
+  API communication
 
-- Nix with flakes enabled (not required, used for deployment)
-- Docker
-- PostgreSQL
+## Development
 
-### Getting Started
+### Running Tests
 
 ```bash
-# Start API development
+# API tests
 cd api
-cargo run
+cargo test
 
-# Start frontend development
+# Frontend tests
 cd frontend
-deno task dev
+deno test
 ```
 
-### Useful Scripts
+### Database Migrations
 
-- `api/scripts/test_sync.sh` - Test local sync endpoint (pre-seed all slices
-  from the atmosphere)
-- `frontend/scripts/register-oauth-client.sh` - Register OAuth client with AIP
+```bash
+cd api
+sqlx migrate run
+
+# If you modify database queries, update the query cache
+cargo sqlx prepare
+```
+
+### Building for Production
+
+```bash
+# Build the API
+cd api
+cargo build --release
+```
+
+## Contributing
 
-## 🚀 Deployment
+### How to Contribute
 
-The service is deployed using Nix-built Docker containers with:
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
-- Fly.io for hosting (move to Upscale?)
-- PostgreSQL for data storage
-- Environment-based configuration
+### Development Guidelines
 
-## 📝 Environment Variables
+- Follow Rust conventions for API code
+- Use Deno formatting for TypeScript/JavaScript
+- Write tests for new features following existing patterns
+- Update documentation as needed
+- Keep commits focused and descriptive
 
-### API
+### Areas for Contribution
 
-- `DATABASE_URL` - PostgreSQL connection string
-- `AUTH_BASE_URL` - AIP OAuth service URL
-- `PORT` - Server port (default: 3000)
+- Lexicon validation and verification
+- UI/UX improvements
+- Documentation and examples
+- Bug fixes and performance improvements
 
-### Frontend
+## Deployment
 
-- `OAUTH_CLIENT_ID` - OAuth application client ID
-- `OAUTH_CLIENT_SECRET` - OAuth application client secret
-- `OAUTH_REDIRECT_URI` - OAuth callback URL
-- `OAUTH_AIP_BASE_URL` - AIP OAuth service URL
-- `SESSION_ENCRYPTION_KEY` - Session cookie encryption key
-- `API_URL` - Backend API base URL
-- `SLICE_URI` - Filters collection based queries by slice
+The service can be deployed using Docker containers. We provide:
+
+- Docker Compose configuration for local development
+- Nix flakes for reproducible builds
+- Fly.io configuration for cloud deployment
+
+See the [deployment guide](./docs/deployment.md) for detailed instructions.
+
+## Environment Variables
+
+### API Configuration
+
+| Variable        | Description                  | Required |
+| --------------- | ---------------------------- | -------- |
+| `DATABASE_URL`  | PostgreSQL connection string | Yes      |
+| `AUTH_BASE_URL` | AIP OAuth service URL        | Yes      |
+| `PORT`          | Server port (default: 3000)  | No       |
+
+### Frontend Configuration
+
+| Variable              | Description                     | Required |
+| --------------------- | ------------------------------- | -------- |
+| `OAUTH_CLIENT_ID`     | OAuth application client ID     | Yes      |
+| `OAUTH_CLIENT_SECRET` | OAuth application client secret | Yes      |
+| `OAUTH_REDIRECT_URI`  | OAuth callback URL              | Yes      |
+| `OAUTH_AIP_BASE_URL`  | AIP OAuth service URL           | Yes      |
+| `API_URL`             | Backend API base URL            | Yes      |
+| `SLICE_URI`           | Default slice URI for queries   | Yes      |
+
+## Roadmap
+
+### In Progress
+
+- Documentation
+- Frontend UX improvements/social features
+- Support more search and filtering params in collection xrpx handlers and SDK
+- Surface jetstream and sync logs in the UI
+- Improve sync and jetstream reliability
+- Monitor api container performance and resource usage
+
+### Planned Features
+
+- Labeler service integration
+- CLI tool
+- API rate limiting
+- Enhanced lexicon management UI
+- Lexicon discovery and sharing
+
+## Community
+
+- **Bluesky**: [@justslices.net](https://bsky.app/profile/justslices.net)
+- **Discord**: [Join our server](https://discord.gg/your-invite)
+
+## Support
+
+- [Documentation](./docs/)
+- [Discord Community](https://discord.gg/your-invite)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+for details.
+
+## Acknowledgments
+
+- Built on the [AT Protocol](https://atproto.com)
+- Inspired by the AT Protocol community
+- Thanks to all contributors
+
+## Status
+
+This project is in active development. APIs may change as we approach v1.0.
+
+---
+
+Made with love for the AT Protocol ecosystem ❤️

api/README.md

···
-# Slice - AT Protocol Indexer
-
-A Rust-based AT Protocol indexer service with HTMX web interface for syncing and viewing AT Protocol records.
-
-## Features
-
-- 📚 **Bulk Collection Sync**: Efficiently sync entire AT Protocol collections
-- 🔄 **Smart Discovery**: Automatically find repositories with target collections
-- 🌐 **Web Interface**: HTMX-powered UI for easy bulk operations
-- 🚀 **XRPC API**: Native AT Protocol XRPC endpoints
-- 🗄️ **PostgreSQL Storage**: Efficient JSONB storage with smart indexing
-
-## Quick Start
-
-### Prerequisites
-
-- Rust 1.70+
-- PostgreSQL 12+
-
-### Setup
-
-1. **Clone and setup**:
-   ```bash
-   git clone <repo>
-   cd slice
-   ```
-
-2. **Database setup**:
-   ```bash
-   createdb slice
-   export DATABASE_URL="postgresql://localhost/slice"
-   ```
-
-3. **Run the server**:
-   ```bash
-   cargo run
-   ```
-
-4. **Open web interface**: http://127.0.0.1:3000
-
-## Usage
-
-### Web Interface
-
-- **Home**: Overview and quick links
-- **Records**: Browse indexed records by collection
-- **Sync**: Manually sync individual records
-
-### API Endpoints
-
-- `GET /xrpc/social.slices.records.list?collection=app.bsky.feed.post` - List records
-- `POST /xrpc/social.slices.collections.bulkSync` - Bulk sync collections
-
-### Example: Bulk Sync Collections
-
-```bash
-curl -X POST "http://127.0.0.1:3000/xrpc/social.slices.collections.bulkSync" \
-  -H "Content-Type: application/json" \
-  -d '{"collections": ["app.bsky.feed.post", "app.bsky.actor.profile"]}'
-```
-
-### Popular Collections to Sync
-
-```
-app.bsky.feed.post        # Bluesky posts
-app.bsky.actor.profile    # User profiles  
-app.bsky.feed.like        # Likes
-app.bsky.feed.repost      # Reposts
-app.bsky.graph.follow     # Follows
-```
-
-## Architecture
-
-Built following the [AT Protocol Indexer Specification](docs/atproto_indexer_spec.md):
-
-- **Single Table Design**: All records in one `record` table with JSONB for flexibility
-- **Smart Syncing**: Hybrid approach supporting both individual record fetch and bulk operations
-- **Future CAR Support**: Architecture ready for CAR file import for efficient bulk syncing
-
-## Development
-
-```bash
-# Run with auto-reload
-cargo watch -x run
-
-# Run tests
-cargo test
-
-# Check code
-cargo clippy
-```

api/docs/atproto_indexer_spec.md

···
-# AT Protocol Indexing Service - Technical Specification
-
-## Project Overview
-
-Build a high-performance, scalable indexing service for AT Protocol that
-automatically generates typed APIs for any lexicon, with intelligent data
-fetching strategies and real-time synchronization.
-
-### Core Goals
-
-- **Universal Lexicon Support**: Automatically handle any AT Protocol lexicon
-  without manual configuration
-- **Multi-Language Client Generation**: Generate typed API clients for
-  TypeScript, Rust, Python, Go, etc.
-- **High Performance**: Handle millions of records efficiently with smart
-  caching and batching
-- **Real-time Sync**: Support both bulk imports and live firehose updates
-- **Developer Experience**: Hasura-style auto-generated APIs with full type
-  safety
-
-## Architecture Overview
-
-### Data Storage Strategy
-
-**Primary Database: PostgreSQL**
-
-- Single source of truth for all indexed records
-- Single table approach for maximum flexibility across arbitrary lexicons
-- JSONB for complete record storage and sophisticated querying
-- Optional partitioning by collection for very high volume deployments
-
-```sql
--- Single table for all AT Protocol records
-CREATE TABLE IF NOT EXISTS "record" (
-    "uri" TEXT PRIMARY KEY NOT NULL,
-    "cid" TEXT NOT NULL,
-    "did" TEXT NOT NULL,
-    "collection" TEXT NOT NULL,
-    "json" JSONB NOT NULL, -- Use JSONB for performance and querying
-    "indexedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
-);
-
--- Essential indexes for performance
-CREATE INDEX IF NOT EXISTS idx_record_collection ON "record"("collection");
-CREATE INDEX IF NOT EXISTS idx_record_did ON "record"("did");
-CREATE INDEX IF NOT EXISTS idx_record_indexed_at ON "record"("indexedAt");
-CREATE INDEX IF NOT EXISTS idx_record_json_gin ON "record" USING GIN("json");
-
--- Collection-specific indexes for common queries
-CREATE INDEX IF NOT EXISTS idx_record_collection_did ON "record"("collection", "did");
-CREATE INDEX IF NOT EXISTS idx_record_cid ON "record"("cid");
-```
-
-**Caching Strategy**
-
-- **Redis**: Hot data caching, query result caching, rate limiting
-- **Application-level**: Compiled lexicon handlers, parsed schemas
-- **CDN**: Public API endpoints with appropriate cache headers
-
-**PostgreSQL JSONB Advantages**
-
-- **GIN indexes**: Fast querying on JSON content with `@>`, `?`, `?&`, `?|`
-  operators
-- **JSON operators**: Rich querying with `->`, `->>`, `#>`, `#>>` for nested
-  access
-- **JSON path queries**: Complex nested field access and filtering
-- **Performance**: JSONB stored in optimized binary format for fast access
-- **Flexibility**: Handle arbitrary lexicon schemas without schema migrations
-
-### Search Implementation
-
-**Hybrid Approach**:
-
-- **PostgreSQL**: Primary queries, exact matches, admin operations, complex
-  joins
-- **Optional Search Engine**: User-facing search, fuzzy matching, aggregations,
-  analytics
-
-**Search Engine Options**:
-
-- **Typesense**: Easy setup, good performance for smaller deployments
-- **Meilisearch**: Excellent for instant search experiences
-- **Elasticsearch/OpenSearch**: Full-featured for large-scale deployments
-
-## Record Fetching Strategies
-
-### Decision Matrix
-
-| Scenario             | Strategy                | Reasoning                                    |
-| -------------------- | ----------------------- | -------------------------------------------- |
-| Initial sync         | CAR file download       | Most efficient for bulk data                 |
-| Real-time updates    | Firehose stream         | Live updates as they happen                  |
-| Catch-up sync (<24h) | List + individual fetch | Good for small gaps                          |
-| Catch-up sync (>24h) | CAR file re-download    | More efficient than many individual requests |
-| Single record update | Individual fetch        | Targeted and fast                            |
-
-### Implementation Strategy
-
-```rust
-async fn smart_sync(&self, did: &str) -> Result<()> {
-    let last_sync = self.get_last_sync_time(did).await?;
-    
-    match last_sync {
-        None => self.sync_repo_car(did).await?, // Initial: CAR file
-        Some(last) if Utc::now() - last > Duration::hours(24) => {
-            self.sync_repo_car(did).await? // Full resync: CAR file
-        }
-        Some(last) => {
-            self.incremental_sync(did, last).await? // Incremental: List + fetch
-        }
-    }
-    
-    Ok(())
-}
-```
-
-## Dynamic Lexicon System
-
-### Why Single Table Works Better for AT Protocol
-
-**Lexicon characteristics that favor single table:**
-
-- **Runtime schema definition**: Lexicons can be arbitrary and defined by any
-  developer
-- **Shared metadata**: All records have common fields (CID, timestamp, author,
-  etc.)
-- **Flexible querying**: Query across different record types seamlessly
-- **Unknown schema count**: Could have hundreds of different lexicons
-
-### Unified Query Interface
-
-**Cross-lexicon querying capabilities:**
-
-```sql
--- Posts with specific hashtags
-SELECT * FROM "record" 
-WHERE "collection" = 'app.bsky.feed.post' 
-AND "json"->>'text' ILIKE '%#atproto%';
-
--- All records by author across all lexicons
-SELECT "collection", COUNT(*) FROM "record" 
-WHERE "did" = 'did:plc:example' 
-GROUP BY "collection";
-
--- Cross-lexicon search for any record with text content
-SELECT * FROM "record" 
-WHERE "json" ? 'text' 
-AND "json"->>'text' ILIKE '%search term%';
-
--- Recent records across all collections
-SELECT "uri", "collection", "json"->>'$type' as record_type, "indexedAt"
-FROM "record" 
-WHERE "indexedAt" > NOW() - INTERVAL '24 hours'
-ORDER BY "indexedAt" DESC;
-```
-
-### Schema Management
-
-**Components**:
-
-1. **Lexicon Registry**: Parse and store lexicon definitions for validation
-2. **Indexer Lexicons**: Define the indexer's own XRPC procedures with proper
-   lexicons
-3. **Validation Layer**: Ensure records conform to their lexicon schemas
-4. **XRPC Server**: Serve both indexed AT Protocol data and indexer's own
-   procedures
-5. **Type Generator**: Generate typed interfaces for all lexicons (AT Protocol +
-   indexer)
-
-### Dynamic Index Creation
-
-```sql
--- Add lexicon-specific indexes as needed for performance
-CREATE INDEX IF NOT EXISTS idx_posts_text ON "record" USING GIN(("json"->'text')) 
-WHERE "collection" = 'app.bsky.feed.post';
-
-CREATE INDEX IF NOT EXISTS idx_profiles_handle ON "record"(("json"->>'handle')) 
-WHERE "collection" = 'app.bsky.actor.profile';
-
--- For very high volume, consider partitioning by collection
-CREATE TABLE "record_posts" PARTITION OF "record" 
-FOR VALUES IN ('app.bsky.feed.post');
-
--- Composite indexes for common query patterns
-CREATE INDEX IF NOT EXISTS idx_record_collection_created_at ON "record"("collection", ("json"->>'createdAt'))
-WHERE "json" ? 'createdAt';
-```
-
-### Implementation Strategy
-
-```rust
-async fn register_lexicon(lexicon: LexiconDoc) -> Result<()> {
-    // 1. Store lexicon definition for validation
-    self.store_lexicon_schema(lexicon).await?;
-    
-    // 2. Create collection-specific indexes if needed
-    self.create_performance_indexes(&lexicon.id).await?;
-    
-    // 3. Register XRPC handlers for core AT Protocol lexicons
-    if lexicon.id.starts_with("com.atproto.") {
-        self.register_atproto_handlers(&lexicon.id).await?;
-    }
-    
-    // 4. Generate TypeScript types for all lexicons (AT Protocol + indexer)
-    self.generate_client_types(&lexicon.id).await?;
-    
-    Ok(())
-}
-
-async fn initialize_indexer_lexicons(&self) -> Result<()> {
-    // Define and register the indexer's own XRPC procedures
-    let indexer_lexicons = vec![
-        self.create_list_records_lexicon(),
-        self.create_search_records_lexicon(),
-        self.create_get_record_lexicon(),
-        // ... other indexer procedures
-    ];
-    
-    for lexicon in indexer_lexicons {
-        self.register_indexer_procedure(lexicon).await?;
-    }
-    
-    Ok(())
-}
-```
-
-### Record Validation
-
-**Validation Layer**: Ensure data integrity with lexicon schema validation
-
-```rust
-async fn insert_record(&self, record: ATProtoRecord) -> Result<()> {
-    // 1. Validate against lexicon schema
-    let lexicon = self.get_lexicon_schema(&record.collection).await?;
-    self.validate_record_against_schema(&record.json, &lexicon)?;
-    
-    // 2. Insert with proper indexing
-    sqlx::query!(
-        r#"INSERT INTO "record" ("uri", "cid", "did", "collection", "json", "indexedAt")
-           VALUES ($1, $2, $3, $4, $5, $6)
-           ON CONFLICT ("uri")
-           DO UPDATE SET 
-               "cid" = EXCLUDED."cid", 
-               "json" = EXCLUDED."json",
-               "indexedAt" = EXCLUDED."indexedAt""#,
-        record.uri,
-        record.cid,
-        record.did,
-        record.collection,
-        record.json,
-        record.indexed_at
-    ).execute(&self.db).await?;
-    
-    Ok(())
-}
-
-// Batch processing for CAR file imports
-async fn batch_insert_records(&self, records: &[ATProtoRecord]) -> Result<()> {
-    let mut tx = self.db.begin().await?;
-    
-    for record in records {
-        sqlx::query!(
-            r#"INSERT INTO "record" ("uri", "cid", "did", "collection", "json", "indexedAt")
-               VALUES ($1, $2, $3, $4, $5, $6)
-               ON CONFLICT ("uri")
-               DO UPDATE SET 
-                   "cid" = EXCLUDED."cid", 
-                   "json" = EXCLUDED."json",
-                   "indexedAt" = EXCLUDED."indexedAt""#,
-            record.uri,
-            record.cid,
-            record.did,
-            record.collection,
-            record.json,
-            record.indexed_at
-        ).execute(&mut *tx).await?;
-    }
-    
-    tx.commit().await?;
-    Ok(())
-}
-```
-
-### API Generation Strategy
-
-**XRPC Endpoints** with proper lexicon definitions:
-
-```
-GET    /xrpc/social.slices.records.list          # List records for collection
-GET    /xrpc/social.slices.records.get           # Get specific record  
-POST   /xrpc/social.slices.records.create        # Create record
-POST   /xrpc/social.slices.records.update        # Update record
-POST   /xrpc/social.slices.records.delete        # Delete record
-
-# Advanced query procedures
-GET    /xrpc/social.slices.records.search        # Full-text search on record content
-GET    /xrpc/social.slices.records.filter        # JSON field filtering
-GET    /xrpc/social.slices.author.listRecords    # All records by author (cross-collection)
-GET    /xrpc/social.slices.search.global         # Global search across all collections
-```
-
-**Lexicon Definitions** for indexer procedures:
-
-```json
-{
-  "lexicon": 1,
-  "id": "social.slices.records.list",
-  "defs": {
-    "main": {
-      "type": "query",
-      "description": "List records for a specific collection",
-      "parameters": {
-        "collection": {
-          "type": "string",
-          "description": "Collection/lexicon ID (e.g. app.bsky.feed.post)",
-          "required": true
-        },
-        "author": {
-          "type": "string",
-          "description": "Filter by author DID"
-        },
-        "limit": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 100,
-          "default": 25
-        },
-        "cursor": {
-          "type": "string",
-          "description": "Pagination cursor"
-        }
-      },
-      "output": {
-        "encoding": "application/json",
-        "schema": {
-          "type": "object",
-          "required": ["records"],
-          "properties": {
-            "records": {
-              "type": "array",
-              "items": { "$ref": "#/defs/indexedRecord" }
-            },
-            "cursor": { "type": "string" }
-          }
-        }
-      }
-    },
-    "indexedRecord": {
-      "type": "object",
-      "required": ["uri", "cid", "value", "indexedAt"],
-      "properties": {
-        "uri": { "type": "string", "format": "at-uri" },
-        "cid": { "type": "string" },
-        "value": { "type": "unknown" },
-        "indexedAt": { "type": "string", "format": "datetime" },
-        "collection": { "type": "string" },
-        "rkey": { "type": "string" },
-        "authorDid": { "type": "string", "format": "did" }
-      }
-    }
-  }
-}
-```
-
-**Benefits of XRPC + Lexicons**:
-
-- **Native AT Protocol**: Indexer becomes a proper AT Protocol service
-- **Discoverable APIs**: Lexicons can be fetched and introspected
-- **Type Generation**: Same code generation works for indexer APIs
-- **Consistent**: Uses established AT Protocol patterns
-- **Composable**: Can be mixed with other AT Protocol services
-
-**XRPC Implementation Examples**:
-
-```rust
-// XRPC query handler for listing records
-async fn handle_list_records(&self, params: ListRecordsParams) -> Result<ListRecordsOutput> {
-    let records = sqlx::query!(
-        r#"SELECT "uri", "cid", "did", "collection", "json", "indexedAt" 
-           FROM "record" 
-           WHERE "collection" = $1 
-           AND ($2::text IS NULL OR "did" = $2)
-           ORDER BY "indexedAt" DESC 
-           LIMIT $3"#,
-        params.collection,
-        params.author,
-        params.limit.unwrap_or(25) as i32
-    ).fetch_all(&self.db).await?;
-    
-    let indexed_records: Vec<IndexedRecord> = records.into_iter().map(|row| {
-        IndexedRecord {
-            uri: row.uri,
-            cid: row.cid,
-            did: row.did,
-            collection: row.collection,
-            value: serde_json::from_str(&row.json.to_string()).unwrap_or_default(),
-            indexed_at: row.indexedAt.to_rfc3339(),
-        }
-    }).collect();
-    
-    Ok(ListRecordsOutput {
-        records: indexed_records,
-        cursor: self.generate_cursor(&records).await?,
-    })
-}
-
-// XRPC search handler with JSONB queries  
-async fn handle_search_records(&self, params: SearchParams) -> Result<SearchOutput> {
-    let records = sqlx::query!(
-        r#"SELECT "uri", "cid", "did", "collection", "json", "indexedAt"
-           FROM "record" 
-           WHERE ($1::text IS NULL OR "collection" = $1)
-           AND "json"->>'text' ILIKE $2
-           ORDER BY "indexedAt" DESC 
-           LIMIT $3"#,
-        params.collection,
-        format!("%{}%", params.query),
-        params.limit.unwrap_or(25) as i32
-    ).fetch_all(&self.db).await?;
-    
-    Ok(SearchOutput { 
-        records: records.into_iter().map(|row| IndexedRecord {
-            uri: row.uri,
-            cid: row.cid,
-            did: row.did,
-            collection: row.collection,
-            value: serde_json::from_str(&row.json.to_string()).unwrap_or_default(),
-            indexed_at: row.indexedAt.to_rfc3339(),
-        }).collect()
-    })
-}
-```
-
-## Multi-Language Client Generation
-
-### Initial Target: TypeScript
-
-**Primary focus**: Generate fully typed TypeScript clients for web applications
-and Node.js services
-
-- **Type Safety**: Complete interfaces for all request/response objects
-- **Auto-completion**: Full IDE support with generated types
-- **Runtime Validation**: Optional runtime type checking
-- **Documentation**: Auto-generated JSDoc comments from lexicon descriptions
-
-### Future Language Support
-
-**Planned targets** for multi-language expansion:
-
-- **Rust**: High-performance services, CLI tools
-- **Python**: Data analysis, ML workflows, web backends
-- **Go**: Microservices, system tools
-
-### Code Generation Pipeline
-
-**Extensible architecture** designed for multiple languages:
-
-```rust
-trait CodeGenerator {
-    fn generate_client(&self, lexicons: &[LexiconDoc]) -> Result<String>;
-    fn generate_types(&self, lexicon: &LexiconDoc) -> Result<String>;
-    fn generate_method(&self, nsid: &str, def: &LexiconDef) -> Result<String>;
-}
-
-// Initial implementation: TypeScript
-impl CodeGenerator for TypeScriptGenerator {
-    fn generate_client(&self, lexicons: &[LexiconDoc]) -> Result<String> {
-        // Generate TypeScript client with full type safety
-    }
-}
-
-// Future implementations:
-// impl CodeGenerator for RustGenerator { /* ... */ }
-// impl CodeGenerator for PythonGenerator { /* ... */ }
-// impl CodeGenerator for GoGenerator { /* ... */ }
-```
-
-### TypeScript Client Generation
-
-**Type-Safe Generic XRPC Client with Auto-Discovery:**
-
-```typescript
-// Registry of all known collections -> their record types
-interface CollectionRecordMap {
-  // Core AT Protocol (always included)
-  "app.bsky.feed.post": PostRecord;
-  "app.bsky.actor.profile": ProfileRecord;
-  "app.bsky.feed.like": LikeRecord;
-
-  // Dynamically discovered custom lexicons
-  "recipes.cooking-app.com": RecipeRecord;
-  "tasks.productivity-tool.io": TaskRecord;
-  "photos.gallery-app.net": PhotoRecord;
-  "someRecord.something-cool.indexer.com": SomeCustomRecord;
-}
-
-// Generic input/output types with conditional typing
-interface CreateRecordInput<T extends keyof CollectionRecordMap> {
-  collection: T;
-  repo: string; // The DID that will become the 'did' field
-  rkey?: string; // Used to construct the URI
-  record: CollectionRecordMap[T]; // Type depends on collection!
-}
-
-interface ListRecordsParams<T extends keyof CollectionRecordMap> {
-  collection: T;
-  author?: string;
-  limit?: number;
-  cursor?: string;
-}
-
-interface ListRecordsOutput<T extends keyof CollectionRecordMap> {
-  records: Array<{
-    uri: string;
-    cid: string;
-    did: string; // Author DID
-    collection: T;
-    value: CollectionRecordMap[T]; // Typed based on collection (parsed from json field)
-    indexedAt: string;
-  }>;
-  cursor?: string;
-}
-
-// Generated client class with conditional types
-export class ATProtoIndexerClient {
-  private client: AxiosInstance;
-
-  constructor(baseURL: string, accessToken?: string) {
-    this.client = axios.create({
-      baseURL,
-      headers: accessToken ? { Authorization: `Bearer ${accessToken}` } : {},
-    });
-  }
-
-  // Generic method - fully typed based on collection parameter
-  async createRecord<T extends keyof CollectionRecordMap>(
-    input: CreateRecordInput<T>,
-  ): Promise<CreateRecordOutput>;
-
-  // Fallback for unknown collections
-  async createRecord(input: {
-    collection: string;
-    repo: string;
-    rkey?: string;
-    record: unknown;
-  }): Promise<CreateRecordOutput>;
-
-  // Implementation handles both cases
-  async createRecord(input: any): Promise<CreateRecordOutput> {
-    const response = await this.client.post(
-      "/xrpc/social.slices.records.create",
-      input,
-    );
-    return response.data;
-  }
-
-  // Generic typed list method
-  async listRecords<T extends keyof CollectionRecordMap>(
-    params: ListRecordsParams<T>,
-  ): Promise<ListRecordsOutput<T>>;
-
-  // Fallback for unknown collections
-  async listRecords(params: {
-    collection: string;
-    author?: string;
-    limit?: number;
-    cursor?: string;
-  }): Promise<ListRecordsOutput<string>>;
-
-  async listRecords(params: any): Promise<any> {
-    const response = await this.client.get("/xrpc/social.slices.records.list", {
-      params,
-    });
-    return response.data;
-  }
-
-  // Convenience methods for popular collections
-  async createPost(
-    input: Omit<CreateRecordInput<"app.bsky.feed.post">, "collection">,
-  ) {
-    return this.createRecord({ ...input, collection: "app.bsky.feed.post" });
-  }
-
-  async listPosts(
-    params: Omit<ListRecordsParams<"app.bsky.feed.post">, "collection">,
-  ) {
-    return this.listRecords({ ...params, collection: "app.bsky.feed.post" });
-  }
-
-  // Auto-generated convenience methods for custom lexicons
-  async createRecipe(
-    input: Omit<CreateRecordInput<"recipes.cooking-app.com">, "collection">,
-  ) {
-    return this.createRecord({
-      ...input,
-      collection: "recipes.cooking-app.com",
-    });
-  }
-
-  async searchRecords(params: SearchRecordsParams): Promise<SearchOutput> {
-    const response = await this.client.get("/xrpc/social.slices.records.search", {
-      params,
-    });
-    return response.data;
-  }
-}
-```
-
-**Usage Examples with Full Type Safety:**
-
-```typescript
-const indexer = new ATProtoIndexerClient("https://indexer.example.com");
-
-// ✅ Fully typed for known collections
-await indexer.createPost({
-  repo: "did:plc:user123",
-  record: {
-    $type: "app.bsky.feed.post",
-    text: "Hello!",
-    createdAt: new Date().toISOString(),
-    // TypeScript knows this must be a PostRecord
-  },
-});
-
-// ✅ Custom lexicon with full typing
-await indexer.createRecord({
-  collection: "recipes.cooking-app.com",
-  repo: "did:plc:chef456",
-  record: {
-    $type: "recipes.cooking-app.com",
-    title: "Pizza",
-    ingredients: ["dough", "sauce", "cheese"],
-    difficulty: "easy",
-    // TypeScript enforces RecipeRecord structure
-  },
-});
-
-// ✅ Query with same type safety - returns typed results
-const posts = await indexer.listPosts({
-  author: "did:plc:user123",
-  limit: 50,
-});
-// posts.records[0].value is typed as PostRecord!
-
-// ✅ Unknown collection - falls back gracefully
-await indexer.createRecord({
-  collection: "new-app.startup.xyz",
-  repo: "did:plc:user789",
-  record: {
-    customField: "value", // No type checking, but still works
-  },
-});
-```
-
-**Auto-Discovery Implementation:**
-
-```rust
-// Indexer discovers and registers custom lexicons dynamically
-impl ATProtoIndexer {
-    async fn discover_lexicons(&self) -> Result<Vec<LexiconDoc>> {
-        let mut lexicons = Vec::new();
-        
-        // Core AT Protocol lexicons
-        lexicons.extend(self.load_core_lexicons().await?);
-        
-        // Custom lexicons from indexed records
-        let custom_collections = sqlx::query!(
-            r#"SELECT DISTINCT "collection" FROM "record" 
-               WHERE "collection" NOT LIKE 'app.bsky.%' 
-               AND "collection" NOT LIKE 'com.atproto.%'"#
-        ).fetch_all(&self.db).await?;
-        
-        for row in custom_collections {
-            if let Ok(lexicon) = self.fetch_lexicon_definition(&row.collection).await {
-                lexicons.push(lexicon);
-            }
-        }
-        
-        Ok(lexicons)
-    }
-    
-    async fn fetch_lexicon_definition(&self, nsid: &str) -> Result<LexiconDoc> {
-        // Fetch from domain's well-known endpoint
-        let domain = nsid.split('.').last().unwrap_or("");
-        let lexicon_url = format!("https://{}/.well-known/atproto/lexicon/{}", domain, nsid);
-        
-        let response = self.client.get(&lexicon_url).send().await?;
-        let lexicon: LexiconDoc = response.json().await?;
-        Ok(lexicon)
-    }
-    
-    async fn regenerate_typescript_client(&self) -> Result<()> {
-        let all_lexicons = self.discover_lexicons().await?;
-        let typescript_code = self.typescript_generator.generate_client(&all_lexicons)?;
-        
-        // Write to file or serve via API endpoint
-        self.write_client_code("typescript", &typescript_code).await?;
-        Ok(())
-    }
-    
-    // Get statistics about indexed collections
-    async fn get_collection_stats(&self) -> Result<Vec<CollectionStats>> {
-        let stats = sqlx::query!(
-            r#"SELECT "collection", 
-                      COUNT(*) as record_count,
-                      COUNT(DISTINCT "did") as unique_authors,
-                      MIN("indexedAt") as first_indexed,
-                      MAX("indexedAt") as last_indexed
-               FROM "record" 
-               GROUP BY "collection" 
-               ORDER BY record_count DESC"#
-        ).fetch_all(&self.db).await?;
-        
-        Ok(stats.into_iter().map(|row| CollectionStats {
-            collection: row.collection,
-            record_count: row.record_count.unwrap_or(0) as u64,
-            unique_authors: row.unique_authors.unwrap_or(0) as u64,
-            first_indexed: row.first_indexed,
-            last_indexed: row.last_indexed,
-        }).collect())
-    }
-}
-```
-
-**Lexicon Discovery Protocol:**
-
-```json
-// GET https://cooking-app.com/.well-known/atproto/lexicon/recipes.cooking-app.com
-{
-  "lexicon": 1,
-  "id": "recipes.cooking-app.com",
-  "description": "Recipe sharing lexicon",
-  "defs": {
-    "main": {
-      "type": "record",
-      "record": {
-        "type": "object",
-        "required": ["$type", "title", "ingredients"],
-        "properties": {
-          "$type": { "const": "recipes.cooking-app.com" },
-          "title": { "type": "string" },
-          "ingredients": { "type": "array", "items": { "type": "string" } },
-          "cookingTime": { "type": "integer" },
-          "difficulty": { "type": "string", "enum": ["easy", "medium", "hard"] }
-        }
-      }
-    }
-  }
-}
-```
-
-**Generated CLI with Discovery:**
-
-```bash
-# Generate TypeScript client with auto-discovered lexicons
-npx atproto-codegen typescript \
-  --discover \
-  --output ./src/generated/indexer-client.ts \
-  --endpoint https://your-indexer.com
-
-# Or specify additional custom lexicons
-npx atproto-codegen typescript \
-  --lexicons recipes.cooking-app.com,tasks.productivity-tool.io \
-  --output ./src/generated/indexer-client.ts \
-  --endpoint https://your-indexer.com
-```
-
-## Implementation Technology Stack
-
-### Backend: Rust
-
-**Rationale**:
-
-- Zero-copy parsing of CAR files and CBOR data
-- Memory safety for long-running indexing processes
-- High-performance concurrent processing
-- Strong type system prevents runtime errors
-- Excellent async ecosystem (Tokio)
-
-### Client Generation: TypeScript (Initial Target)
-
-**Rationale**:
-
-- **Primary ecosystem**: Most AT Protocol developers use JavaScript/TypeScript
-- **Immediate value**: Web apps and Node.js services are common use cases
-- **Type safety**: Excellent TypeScript support for generated interfaces
-- **Developer experience**: Full IDE support with auto-completion
-- **Ecosystem compatibility**: Works with React, Next.js, Express, etc.
-
-### Key Dependencies
-
-```toml
-[dependencies]
-tokio = { version = "1.0", features = ["full"] }
-sqlx = { version = "0.7", features = ["postgres", "chrono", "serde_json"] }
-serde = { version = "1.0", features = ["derive"] }
-reqwest = { version = "0.11", features = ["json", "stream"] }
-libipld = { version = "0.16", features = ["dag-cbor", "car"] }
-tokio-tungstenite = "0.20" # WebSocket for firehose
-redis = { version = "0.23", features = ["tokio-comp"] }
-tracing = "0.1"
-
-# Code generation dependencies
-handlebars = "4.0" # Template engine for TypeScript generation
-```
-
-## Performance Optimizations
-
-### Concurrent Processing
-
-- **Bounded concurrency**: Limit simultaneous CAR file processing
-- **Streaming**: Process large CAR files without loading entirely into memory
-- **Batching**: Group database operations for better throughput
-- **Connection pooling**: Efficient database connection management
-
-### Rate Limiting
-
-```rust
-// Token bucket implementation for API rate limiting
-struct RateLimiter {
-    tokens: Arc<Mutex<f64>>,
-    max_tokens: f64,
-    refill_rate: f64, // tokens per second
-}
-```
-
-### Memory Management
-
-- **Streaming CAR processing**: Avoid loading entire repos into memory
-- **LRU caches**: Intelligent caching of frequently accessed data
-- **Pagination**: Cursor-based pagination for large result sets
-
-## Real-Time Synchronization
-
-### Firehose Integration
-
-```rust
-async fn start_firehose_listener(&self) -> Result<()> {
-    let (ws_stream, _) = connect_async(
-        "wss://bsky.network/xrpc/com.atproto.sync.subscribeRepos"
-    ).await?;
-    
-    // Process commits in real-time
-    while let Some(msg) = read.next().await {
-        if let Ok(commit) = self.parse_commit(&msg) {
-            self.process_commit(commit).await?;
-        }
-    }
-    
-    Ok(())
-}
-```
-
-### Sync Strategies
-
-1. **Initial Bootstrap**: Download existing data via CAR files
-2. **Real-time Updates**: Process firehose stream for live changes
-3. **Periodic Reconciliation**: Compare local state with remote to catch missed
-   updates
-4. **Backfill**: Handle gaps in data due to downtime
-
-## API Design
-
-### Core Principles
-
-- **RESTful**: Follow REST conventions where applicable
-- **Lexicon-Agnostic**: Work with any current or future AT Protocol lexicon
-- **Type-Safe**: Generate strongly typed clients
-- **Cacheable**: Design for HTTP caching and CDN distribution
-- **Paginated**: Support cursor-based pagination for large datasets
-
-### Authentication
-
-- **Optional**: Support authenticated requests for private data
-- **Bearer tokens**: Standard AT Protocol authentication
-- **Rate limiting**: Per-user and global rate limits
-
-### Response Format
-
-```json
-{
-  "data": [...],
-  "cursor": "next_page_token",
-  "count": 42,
-  "total": 1337
-}
-```
-
-## Risk Mitigation
-
-### Data Consistency
-
-- **Idempotent operations**: Safe to retry any indexing operation
-- **Checksum validation**: Verify CAR file integrity
-- **Reconciliation**: Periodic comparison with authoritative sources
-
-### Scalability
-
-- **Horizontal scaling**: Design for multiple indexer instances
-- **Database sharding**: Partition by lexicon type or DID prefix
-- **Caching layers**: Multiple levels of caching for performance
-
-### Operational
-
-- **Circuit breakers**: Prevent cascade failures
-- **Graceful degradation**: Continue operating with reduced functionality
-- **Monitoring**: Comprehensive observability for quick issue detection

docs/api-reference.md

···
+# API Reference
+
+Complete reference for Slices API endpoints.
+
+## Base URL
+
+```
+https://your-api-domain.com/xrpc/
+```
+
+## Authentication
+
+Most write operations require OAuth 2.0 authentication. Include the access token in the Authorization header:
+
+```
+Authorization: Bearer YOUR_ACCESS_TOKEN
+```
+
+Read operations typically work without authentication.
+
+## Core Endpoints
+
+### Slice Management
+
+#### `social.slices.slice.listRecords`
+
+List all slices.
+
+**Method**: GET
+
+**Parameters**:
+- `limit` (number, optional): Maximum records to return (default: 50)
+- `cursor` (string, optional): Pagination cursor
+- `sort` (string, optional): Sort field and order (e.g., `createdAt:desc`)
+- `author` (string, optional): Filter by author DID
+- `authors` (string[], optional): Filter by multiple author DIDs
+
+**Response**:
+```json
+{
+  "records": [
+    {
+      "uri": "at://did:plc:abc/social.slices.slice/xyz",
+      "cid": "bafyrei...",
+      "did": "did:plc:abc",
+      "collection": "social.slices.slice",
+      "value": {
+        "name": "My Slice",
+        "domain": "com.example",
+        "createdAt": "2024-01-01T00:00:00Z"
+      },
+      "indexedAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "cursor": "next-page-cursor"
+}
+```
+
+#### `social.slices.slice.getRecord`
+
+Get a specific slice by URI.
+
+**Method**: GET
+
+**Parameters**:
+- `uri` (string, required): AT Protocol URI of the slice
+
+**Response**: Single record object (same structure as listRecords item)
+
+#### `social.slices.slice.createRecord`
+
+Create a new slice.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "record": {
+    "$type": "social.slices.slice",
+    "name": "My New Slice",
+    "domain": "com.example",
+    "createdAt": "2024-01-01T00:00:00Z"
+  },
+  "rkey": "optional-record-key"
+}
+```
+
+**Response**:
+```json
+{
+  "uri": "at://did:plc:abc/social.slices.slice/xyz",
+  "cid": "bafyrei..."
+}
+```
+
+### Slice Operations
+
+#### `social.slices.slice.stats`
+
+Get statistics for a slice.
+
+**Method**: POST
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri"
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "collections": ["com.example.post", "app.bsky.actor.profile"],
+  "collectionStats": [
+    {
+      "collection": "com.example.post",
+      "recordCount": 150,
+      "uniqueActors": 10
+    }
+  ],
+  "totalLexicons": 5,
+  "totalRecords": 500,
+  "totalActors": 25,
+  "message": "Statistics retrieved successfully"
+}
+```
+
+#### `social.slices.slice.records`
+
+Browse records in a slice.
+
+**Method**: POST
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "collection": "com.example.post",
+  "repo": "did:plc:optional-filter",
+  "limit": 20,
+  "cursor": "pagination-cursor"
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "records": [
+    {
+      "uri": "at://did:plc:abc/com.example.post/xyz",
+      "cid": "bafyrei...",
+      "did": "did:plc:abc",
+      "collection": "com.example.post",
+      "value": { /* record data */ },
+      "indexedAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "cursor": "next-page-cursor"
+}
+```
+
+#### `social.slices.slice.syncUserCollections`
+
+Synchronously sync collections for the authenticated user.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "timeoutSeconds": 30
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "reposProcessed": 1,
+  "recordsSynced": 45,
+  "timedOut": false,
+  "message": "Sync completed successfully"
+}
+```
+
+#### `social.slices.slice.startSync`
+
+Start an asynchronous bulk sync job.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "collections": ["com.example.post"],
+  "externalCollections": ["app.bsky.actor.profile"],
+  "repos": ["did:plc:abc", "did:plc:xyz"],
+  "limitPerRepo": 100
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "jobId": "job-uuid",
+  "message": "Sync job started"
+}
+```
+
+#### `social.slices.slice.codegen`
+
+Generate TypeScript client code.
+
+**Method**: POST
+
+**Body**:
+```json
+{
+  "target": "typescript",
+  "slice": "at://your-slice-uri"
+}
+```
+
+**Response**:
+```json
+{
+  "success": true,
+  "generatedCode": "// Generated TypeScript client code..."
+}
+```
+
+## Dynamic Collection Endpoints
+
+For each collection in your slice, the following endpoints are automatically generated:
+
+### `[collection].listRecords`
+
+List records in a collection.
+
+**Method**: GET
+
+**Parameters**:
+- `slice` (string, required): Slice URI
+- `limit` (number, optional): Maximum records (default: 50)
+- `cursor` (string, optional): Pagination cursor
+- `sort` (string, optional): Sort specification
+- `author` (string, optional): Filter by author DID
+- `authors` (string[], optional): Filter by multiple DIDs
+
+### `[collection].getRecord`
+
+Get a single record.
+
+**Method**: GET
+
+**Parameters**:
+- `slice` (string, required): Slice URI
+- `uri` (string, required): Record URI
+
+### `[collection].searchRecords`
+
+Search within a collection.
+
+**Method**: GET
+
+**Parameters**:
+- `slice` (string, required): Slice URI
+- `query` (string, required): Search query
+- `field` (string, optional): Specific field to search
+- `limit` (number, optional): Maximum results
+- `cursor` (string, optional): Pagination cursor
+- `sort` (string, optional): Sort specification
+
+### `[collection].createRecord`
+
+Create a new record.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "record": {
+    "$type": "collection.name",
+    /* record fields */
+  },
+  "rkey": "optional-key"
+}
+```
+
+### `[collection].updateRecord`
+
+Update an existing record.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "rkey": "record-key",
+  "record": {
+    "$type": "collection.name",
+    /* updated fields */
+  }
+}
+```
+
+### `[collection].deleteRecord`
+
+Delete a record.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "rkey": "record-key"
+}
+```
+
+## Lexicon Management
+
+### `social.slices.lexicon.listRecords`
+
+List lexicons in a slice.
+
+**Method**: GET
+
+**Parameters**: Same as collection.listRecords
+
+### `social.slices.lexicon.createRecord`
+
+Add a lexicon to a slice.
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Body**:
+```json
+{
+  "slice": "at://your-slice-uri",
+  "record": {
+    "$type": "social.slices.lexicon",
+    "nsid": "com.example.post",
+    "definitions": "{\"lexicon\": 1, ...}",
+    "createdAt": "2024-01-01T00:00:00Z",
+    "slice": "at://your-slice-uri"
+  }
+}
+```
+
+## Actor Management
+
+### `social.slices.slice.getActors`
+
+Get actors (users) in a slice.
+
+**Method**: GET
+
+**Parameters**:
+- `slice` (string, required): Slice URI
+- `search` (string, optional): Search query
+- `dids` (string[], optional): Filter by DIDs
+- `limit` (number, optional): Maximum results
+- `cursor` (string, optional): Pagination cursor
+
+**Response**:
+```json
+{
+  "actors": [
+    {
+      "did": "did:plc:abc",
+      "handle": "user.bsky.social",
+      "sliceUri": "at://slice-uri",
+      "indexedAt": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "cursor": "next-page"
+}
+```
+
+## Blob Upload
+
+### `com.atproto.repo.uploadBlob`
+
+Upload a blob (image, file).
+
+**Method**: POST
+
+**Authentication**: Required
+
+**Headers**:
+- `Content-Type`: MIME type of the blob
+
+**Body**: Raw binary data
+
+**Response**:
+```json
+{
+  "blob": {
+    "$type": "blob",
+    "ref": { "$link": "bafkrei..." },
+    "mimeType": "image/jpeg",
+    "size": 127198
+  }
+}
+```
+
+## Error Responses
+
+All endpoints may return error responses:
+
+```json
+{
+  "error": "InvalidRequest",
+  "message": "Detailed error message"
+}
+```
+
+Common HTTP status codes:
+- `200`: Success
+- `400`: Bad request
+- `401`: Authentication required
+- `403`: Forbidden
+- `404`: Not found
+- `500`: Internal server error
+
+## Pagination
+
+List endpoints support cursor-based pagination:
+
+1. Make initial request without cursor
+2. Use returned cursor for next page
+3. Continue until no cursor returned
+
+Example:
+```javascript
+let cursor = undefined;
+do {
+  const response = await fetch(`/xrpc/collection.listRecords?cursor=${cursor}`);
+  const data = await response.json();
+  // Process records
+  cursor = data.cursor;
+} while (cursor);
+```
+
+## Sorting
+
+Sort parameter format: `field:order` or `field1:order1,field2:order2`
+
+Examples:
+- `createdAt:desc` - Newest first
+- `name:asc` - Alphabetical
+- `createdAt:desc,name:asc` - Newest first, then alphabetical
+
+## Next Steps
+
+- [SDK Usage](./sdk-usage.md) - Using generated TypeScript clients
+- [Getting Started](./getting-started.md) - Build your first application
+- [Concepts](./concepts.md) - Understand the architecture

docs/concepts.md

···
+# Core Concepts
+
+Understanding these core concepts will help you effectively use Slices.
+
+## Slices
+
+A slice is an independent appview within the AT Protocol ecosystem. Think of it
+as your own data universe with custom schemas and records.
+
+### Key Properties
+
+- **URI**: Unique AT Protocol URI (e.g.,
+  `at://did:plc:abc123/social.slices.slice/3xyz`)
+- **Name**: Human-readable identifier
+- **Domain**: Namespace for lexicons (e.g., `com.example`, `social.grain`)
+- **Creation Date**: When the slice was created
+
+### Slice Isolation
+
+Each slice maintains complete data isolation:
+
+- Records are filtered by slice URI in all queries
+- Sync operations respect slice boundaries
+- Statistics are calculated per-slice
+- Users can have different data in different slices
+
+## Lexicons
+
+Lexicons are JSON schemas that define record types in AT Protocol. They specify
+the structure, validation rules, and metadata for records.
+
+### Lexicon Structure
+
+```json
+{
+  "lexicon": 1,
+  "id": "com.example.blogPost",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "A blog post record",
+      "record": {
+        "type": "object",
+        "properties": {
+          "title": { "type": "string" },
+          "content": { "type": "string" },
+          "publishedAt": { "type": "string", "format": "datetime" }
+        },
+        "required": ["title", "content"]
+      }
+    }
+  }
+}
+```
+
+### Supported Types
+
+- **Primitives**: string, number, integer, boolean
+- **Complex**: object, array, union, ref
+- **Special**: blob (for media), cid-link, at-uri
+- **Formats**: datetime, at-identifier, did, handle
+
+### Lexicon Namespacing
+
+Lexicons follow reverse domain naming:
+
+- `com.example.post` - A post in the example.com namespace
+- `social.slices.slice` - Core slice record type
+- `app.bsky.actor.profile` - Bluesky profile (external)
+
+## Collections
+
+Collections are groups of records with the same lexicon type. They map directly
+to XRPC endpoints.
+
+### Primary Collections
+
+Collections that match your slice's domain namespace. For example, if your slice
+domain is `com.example`, then `com.example.post` would be a primary collection.
+
+### External Collections
+
+Collections from other namespaces that you've synced into your slice. For
+example:
+
+- Bluesky profiles (`app.bsky.actor.profile`)
+- Bluesky posts (`app.bsky.feed.post`)
+- Collections from other slices
+
+### Collection Operations
+
+Both primary and external collections support the same operations:
+
+- `*.listRecords` - List with pagination and filtering
+- `*.getRecord` - Get single record by URI
+- `*.createRecord` - Create new record
+- `*.updateRecord` - Update existing record
+- `*.deleteRecord` - Remove record
+- `*.searchRecords` - Search within collection
+
+The key difference is conceptual: primary collections are "native" to your
+slice's domain, while external collections are imported from other namespaces.
+
+## Records
+
+Records are individual data items stored in collections.
+
+### Record Properties
+
+- **URI**: Unique AT Protocol URI
+- **CID**: Content identifier (hash)
+- **DID**: Owner's decentralized identifier
+- **Collection**: Lexicon type
+- **Value**: Actual record data
+- **IndexedAt**: When record was indexed
+
+### Record Keys (rkeys)
+
+Records use keys for identification:
+
+- **Self**: Special key for singleton records (e.g., profiles)
+- **TID**: Timestamp-based identifiers
+- **Custom**: User-defined keys
+
+### Record Lifecycle
+
+1. **Creation**: Via API or sync
+2. **Indexing**: Stored in PostgreSQL
+3. **Updates**: New versions with new CIDs
+4. **Deletion**: Soft or hard delete
+
+## Sync Engine
+
+The sync engine imports AT Protocol data into your slice using multiple
+strategies for optimal performance and reliability.
+
+### Sync Types
+
+**Bulk Sync**: One-time import of historical data
+
+- Specify collections to sync
+- Filter by repositories (DIDs)
+- Set limits per repository
+- Uses optimized bulk database operations
+
+**User Sync**: Sync data for authenticated user
+
+- Automatic on login
+- Timeout protection (30 seconds default)
+- External collection discovery
+- Synchronous operation for immediate feedback
+
+**Jetstream Sync**: Real-time updates via WebSocket
+
+- Subscribe to AT Protocol firehose
+- Filter relevant events by slice collections
+- Automatic record updates and deletions
+- Built-in reconnection with exponential backoff
+
+### Sync Process
+
+1. **Discovery**: Find available records via AT Protocol relay
+2. **Filtering**: Apply slice and collection filters
+3. **Validation**: Check lexicon compliance against slice schemas
+4. **Storage**: Index in database using bulk operations
+5. **Deduplication**: Skip existing records (by CID comparison)
+
+### Performance Optimizations
+
+**CID-Based Deduplication**
+
+- Compare Content Identifiers (CIDs) before processing
+- Skip records that haven't changed since last sync
+- Reduces unnecessary database operations and validation overhead
+
+**Actor Caching**
+
+- Pre-load actor lookup cache to avoid database hits during Jetstream processing
+- Cache (DID, slice_uri) mappings for external collection filtering
+- Periodic cache refresh every 5 minutes
+
+### Jetstream Reliability
+
+**Automatic Recovery**
+
+- Infinite retry loop with exponential backoff (5 seconds → 5 minutes max)
+- Fresh consumer instance creation on each retry
+- Database connectivity monitoring and recovery
+- Connection status tracking via atomic flags
+
+**Error Handling**
+
+- Graceful degradation when database connections fail
+- Validation fallback with fresh lexicon loading from database
+- Separate error handling for primary vs external collections
+
+**Configuration Reloading**
+
+- Automatic slice configuration refresh every 5 minutes
+- Dynamic collection filtering based on slice lexicons
+- Actor cache updates to reflect new slice membership
+
+## XRPC Handlers
+
+XRPC (Cross-Protocol Remote Procedure Call) handlers provide the API layer.
+
+### Dynamic Handlers
+
+Automatically generated from lexicons:
+
+- No manual endpoint creation
+- Type-safe request/response
+- Automatic validation
+- OAuth integration
+
+### Core Handlers
+
+Built-in endpoints for slice management:
+
+- `social.slices.slice.stats` - Slice statistics
+- `social.slices.slice.records` - Browse records
+- `social.slices.slice.codegen` - Generate SDKs
+- `social.slices.slice.sync` - Trigger sync
+
+### Handler Authentication
+
+- **Read Operations**: Optional auth (public by default)
+- **Write Operations**: Require OAuth tokens
+- **Admin Operations**: Require slice ownership
+
+## Generated SDKs
+
+Type-safe client libraries generated from lexicons.
+
+### SDK Features
+
+- **Type Safety**: Full TypeScript types
+- **Nested Structure**: Matches lexicon namespacing
+- **OAuth Integration**: Automatic token handling
+- **Error Handling**: Retry logic and graceful failures
+
+### SDK Generation Process
+
+1. Parse slice lexicons
+2. Generate TypeScript interfaces
+3. Create client classes
+4. Add utility functions
+5. Format and validate
+
+### Using Generated SDKs
+
+```typescript
+// Initialize client
+const client = new AtProtoClient(apiUrl, sliceUri, oauthClient);
+
+// Use nested structure matching lexicons
+await client.com.example.post.listRecords();
+await client.social.slices.slice.stats();
+await client.app.bsky.actor.profile.getRecord({ uri });
+```
+
+## Authentication
+
+OAuth 2.0 with PKCE for secure authentication.
+
+### OAuth Flow
+
+1. **Authorization**: Redirect to AT Protocol provider
+2. **Callback**: Exchange code for tokens
+3. **Token Storage**: Secure client-side storage
+4. **Refresh**: Automatic token renewal
+
+### Session Management
+
+- Encrypted cookies for web sessions
+- Token refresh before expiration
+- Graceful degradation for read-only access
+
+## Blob Handling
+
+Media files use blob references with CDN URLs.
+
+### Blob Structure
+
+```json
+{
+  "$type": "blob",
+  "ref": { "$link": "bafkreig5bcb..." },
+  "mimeType": "image/jpeg",
+  "size": 127198
+}
+```
+
+### CDN URL Generation
+
+Convert blob references to CDN URLs using Bluesky's CDN:
+
+```typescript
+recordBlobToCdnUrl(record, blobRef, "avatar");
+// -> https://cdn.bsky.app/img/avatar/plain/did:plc:abc/bafkrei...@jpeg
+```
+
+### Bluesky CDN Presets
+
+- `avatar` - Profile pictures
+- `banner` - Cover images
+- `feed_thumbnail` - Small previews
+- `feed_fullsize` - Full resolution
+
+## Next Steps
+
+- [API Reference](./api-reference.md) - Detailed endpoint documentation
+- [SDK Usage](./sdk-usage.md) - Advanced client patterns
+- [Getting Started](./getting-started.md) - Build your first slice

docs/deployment.md

···
+# Deployment Guide
+
+Documentation for deploying Slices to production is coming soon.
+
+## Basic Requirements
+
+- [AIP server](https://github.com/graze-social/aip) running and accessible
+- Registered OAuth client with AIP
+- PostgreSQL database
+
+## Environment Setup
+
+See the [environment variables](../README.md#environment-variables) section in the README for required configuration.
+
+## Docker
+
+Docker images can be built using the provided Dockerfile in each directory.
+
+## More Information
+
+For now, refer to:
+- [Getting Started](./getting-started.md) for local setup
+- [README](../README.md) for environment configuration

docs/getting-started.md

···
+# Getting Started with Slices
+
+This guide will help you set up Slices and create your first slice.
+
+## Prerequisites
+
+- Docker and Docker Compose
+- PostgreSQL (or use Docker)
+- Deno (for frontend)
+- Rust and Cargo (for API development)
+- An AT Protocol account (for OAuth)
+
+## Initial Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/your-org/slice
+cd slice
+```
+
+### 2. Set Up the Database
+
+Start PostgreSQL using Docker:
+
+```bash
+docker-compose up -d postgres
+```
+
+Or use an existing PostgreSQL instance and create a database:
+
+```sql
+CREATE DATABASE slices;
+```
+
+### 3. Configure Environment Variables
+
+Create `.env` files for both API and frontend:
+
+**API (`/api/.env`)**:
+```bash
+DATABASE_URL=postgres://user:password@localhost:5432/slices
+AUTH_BASE_URL=https://aip.your-domain.com
+PORT=3000
+```
+
+**Frontend (`/frontend/.env`)**:
+```bash
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+OAUTH_REDIRECT_URI=http://localhost:8000/oauth/callback
+OAUTH_AIP_BASE_URL=https://aip.your-domain.com
+SESSION_ENCRYPTION_KEY=your-32-char-key
+API_URL=http://localhost:3000
+SLICE_URI=at://did:plc:your-did/social.slices.slice/your-slice-id
+DATABASE_URL=slices.db
+```
+
+### 4. Register OAuth Client
+
+Register your application with the AIP server:
+
+```bash
+cd frontend
+./scripts/register-oauth-client.sh
+```
+
+Save the client ID and secret to your `.env` file.
+
+### 5. Start the Services
+
+Start the API server:
+```bash
+cd api
+cargo run
+```
+
+Start the frontend:
+```bash
+cd frontend
+deno task dev
+```
+
+Visit `http://localhost:8000` to access the web interface.
+
+## Creating Your First Slice
+
+### 1. Log In
+
+Click "Login" and authenticate with your AT Protocol account.
+
+### 2. Create a Slice
+
+Click "Create Slice" and provide:
+- **Name**: A friendly name for your slice
+- **Domain**: Your namespace (e.g., `com.example`)
+
+### 3. Define a Lexicon
+
+Navigate to your slice and go to the Lexicon tab. Create a lexicon for your first record type:
+
+```json
+{
+  "lexicon": 1,
+  "id": "com.example.post",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "A blog post",
+      "record": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Post title"
+          },
+          "content": {
+            "type": "string",
+            "description": "Post content"
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Creation timestamp"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Post tags"
+          }
+        },
+        "required": ["title", "content", "createdAt"]
+      }
+    }
+  }
+}
+```
+
+### 4. Generate TypeScript Client
+
+Navigate to the Code Generation tab and click "Generate TypeScript Client". This creates a type-safe client library for your slice.
+
+### 5. Use the Generated Client
+
+In your application:
+
+```typescript
+import { AtProtoClient } from "./generated-client.ts";
+
+const client = new AtProtoClient(
+  'http://localhost:3000',
+  'at://did:plc:your-did/social.slices.slice/your-slice-id'
+);
+
+// List posts
+const posts = await client.com.example.post.listRecords();
+
+// Create a post
+const newPost = await client.com.example.post.createRecord({
+  title: "My First Post",
+  content: "Hello from Slices!",
+  createdAt: new Date().toISOString(),
+  tags: ["introduction", "slices"]
+});
+
+// Get a specific post
+const post = await client.com.example.post.getRecord({
+  uri: newPost.uri
+});
+```
+
+## Syncing External Data
+
+To import data from other AT Protocol repositories:
+
+### 1. Navigate to Sync
+
+Go to your slice and click the Sync tab.
+
+### 2. Configure Sync
+
+Choose collections to sync:
+- **Primary Collections**: Your slice's lexicons
+- **External Collections**: Bluesky or other AT Protocol collections
+
+### 3. Start Sync
+
+Specify repositories (DIDs) to sync from, or leave empty to sync all available data.
+
+### 4. Monitor Progress
+
+The sync will run in the background. Check the status in the UI or via API.
+
+## Next Steps
+
+- [Core Concepts](./concepts.md) - Understand slices, lexicons, and collections
+- [API Reference](./api-reference.md) - Explore available endpoints
+- [SDK Usage](./sdk-usage.md) - Advanced SDK patterns
+- [Examples](./examples/) - Sample applications
+
+## Troubleshooting
+
+### Database Connection Issues
+- Verify PostgreSQL is running: `docker ps`
+- Check DATABASE_URL format
+- Ensure database exists
+
+### OAuth Errors
+- Verify client ID and secret
+- Check redirect URI matches configuration
+- Ensure AIP server is accessible
+
+### Sync Not Working
+- Check user has necessary permissions
+- Verify lexicons are valid
+- Check API server logs for errors
+
+### Generated Client Issues
+- Regenerate client after lexicon changes
+- Ensure API server is running
+- Check for TypeScript compilation errors

docs/intro.md

···
+# Introduction to Slices
+
+Slices is an AT Protocol appview platform that enables developers to create
+custom data slices (appviews) with their own lexicons, sync AT Protocol data,
+and generate type-safe SDKs.
+
+## What is a Slice?
+
+A slice is a custom appview within the AT Protocol ecosystem. Each slice:
+
+- Has its own domain namespace (e.g., `social.grain`, `xyz.statusphere`)
+- Defines custom lexicons (schemas) for record types
+- Can sync both internal and external AT Protocol collections
+- Provides automatically generated type-safe SDKs
+
+## Why Slices?
+
+Building AT Protocol applications typically requires:
+
+- Setting up infrastructure to index and query AT Protocol data
+- Managing OAuth authentication flows
+- Implementing XRPC handlers for CRUD operations
+- Creating client libraries for frontend integration
+
+Slices provides all of this infrastructure out of the box, letting you focus on
+your application logic.
+
+## Key Features
+
+### Dynamic API Generation
+
+Define a lexicon, and Slices automatically creates REST endpoints for:
+
+- Listing records with filtering and sorting
+- Getting individual records by URI
+- Creating new records with OAuth authentication
+- Updating existing records
+- Deleting records
+- Searching within collections
+
+### Data Synchronization
+
+Sync AT Protocol data into your slice:
+
+- Import external collections (e.g., Bluesky profiles, posts)
+- Filter data by repository or collection
+- Maintain slice-specific data isolation
+- Real-time sync via Jetstream (coming soon)
+
+### Type-Safe SDK Generation
+
+Automatically generate TypeScript clients with:
+
+- Full type safety for all record types
+- OAuth authentication integration
+- Nested API structure matching your lexicons
+- Blob/CDN URL utilities for media handling
+
+### Multi-Tenant Architecture
+
+Each slice operates independently:
+
+- Isolated data storage
+- Custom lexicon definitions
+- Separate sync configurations
+- Per-slice statistics and analytics
+
+## Use Cases
+
+- **Custom Social Apps**: Build specialized social networks with custom record
+  types
+- **Data Aggregators**: Collect and organize AT Protocol data for analysis
+- **Specialized Feeds**: Create curated views of AT Protocol content
+- **Research Tools**: Index and query specific subsets of AT Protocol data
+- **Creative Applications**: Blogs, galleries, portfolios built on AT Protocol
+
+## Architecture Overview
+
+Slices consists of two main components:
+
+- **API Server** (Rust): Handles AT Protocol integration, database operations,
+  and API endpoints
+- **Frontend** (Deno): Provides web UI for slice management and user
+  authentication
+
+Both components work together to provide a complete AT Protocol appview
+platform. The API server can also be run standalone as a headless service and
+interactive with via it's XRPC apis.
+
+## Next Steps
+
+- [Getting Started](./getting-started.md) - Set up your first slice
+- [Core Concepts](./concepts.md) - Understand the key concepts
+- [API Reference](./api-reference.md) - Explore the API endpoints
+- [SDK Usage](./sdk-usage.md) - Learn to use generated clients

docs/sdk-usage.md

···
+# SDK Usage Guide
+
+This guide covers how to use the generated TypeScript SDK for your slice.
+
+## Installation
+
+After generating your TypeScript client, you can use it directly in your project:
+
+```typescript
+import { AtProtoClient } from "./generated-client.ts";
+import { OAuthClient } from "@slices/oauth";
+```
+
+## Basic Setup
+
+### Without Authentication (Read-Only)
+
+```typescript
+const client = new AtProtoClient(
+  'https://api.your-domain.com',
+  'at://did:plc:abc/social.slices.slice/your-slice-id'
+);
+
+// Read operations work without auth
+const records = await client.com.example.post.listRecords();
+```
+
+### With Authentication (Full Access)
+
+```typescript
+import { OAuthClient } from "@slices/oauth";
+
+// Set up OAuth client
+const oauthClient = new OAuthClient({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  authBaseUrl: 'https://aip.your-domain.com',
+  redirectUri: 'https://your-app.com/oauth/callback',
+  scopes: ['atproto:atproto', 'atproto:transition:generic']
+});
+
+// Initialize API client with OAuth
+const client = new AtProtoClient(
+  'https://api.your-domain.com',
+  'at://did:plc:abc/social.slices.slice/your-slice-id',
+  oauthClient
+);
+```
+
+## CRUD Operations
+
+### Listing Records
+
+```typescript
+// List all records
+const posts = await client.com.example.post.listRecords();
+
+// With pagination
+const page1 = await client.com.example.post.listRecords({ limit: 20 });
+const page2 = await client.com.example.post.listRecords({ 
+  limit: 20, 
+  cursor: page1.cursor 
+});
+
+// With filtering
+const userPosts = await client.com.example.post.listRecords({
+  author: 'did:plc:user123'
+});
+
+// With sorting
+const recentPosts = await client.com.example.post.listRecords({
+  sort: 'createdAt:desc'
+});
+
+// Multiple sort fields
+const sortedPosts = await client.com.example.post.listRecords({
+  sort: 'createdAt:desc,title:asc'
+});
+```
+
+### Getting a Single Record
+
+```typescript
+const post = await client.com.example.post.getRecord({
+  uri: 'at://did:plc:abc/com.example.post/3xyz'
+});
+
+console.log(post.value.title);
+console.log(post.value.content);
+```
+
+### Creating Records
+
+```typescript
+// Create with auto-generated key
+const newPost = await client.com.example.post.createRecord({
+  title: "My New Post",
+  content: "This is the content",
+  createdAt: new Date().toISOString(),
+  tags: ["typescript", "atproto"]
+});
+
+console.log(`Created: ${newPost.uri}`);
+
+// Create with custom key
+const customPost = await client.com.example.post.createRecord(
+  {
+    title: "Custom Key Post",
+    content: "Using a custom record key",
+    createdAt: new Date().toISOString()
+  },
+  true // useSelfRkey for singleton records like profiles
+);
+```
+
+### Updating Records
+
+```typescript
+// Get the record key from the URI
+const uri = 'at://did:plc:abc/com.example.post/3xyz';
+const rkey = uri.split('/').pop(); // '3xyz'
+
+const updated = await client.com.example.post.updateRecord(
+  rkey,
+  {
+    title: "Updated Title",
+    content: "Updated content",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  }
+);
+
+console.log(`Updated: ${updated.cid}`);
+```
+
+### Deleting Records
+
+```typescript
+const rkey = '3xyz';
+await client.com.example.post.deleteRecord(rkey);
+```
+
+### Searching Records
+
+```typescript
+// Basic search
+const results = await client.com.example.post.searchRecords({
+  query: "typescript"
+});
+
+// Search specific field
+const titleResults = await client.com.example.post.searchRecords({
+  query: "guide",
+  field: "title"
+});
+
+// Search with pagination
+const searchPage = await client.com.example.post.searchRecords({
+  query: "tutorial",
+  limit: 10,
+  cursor: previousCursor
+});
+```
+
+## Working with External Collections
+
+Access synced external collections like Bluesky profiles:
+
+```typescript
+// List Bluesky profiles in your slice
+const profiles = await client.app.bsky.actor.profile.listRecords();
+
+// Get a specific profile
+const profile = await client.app.bsky.actor.profile.getRecord({
+  uri: 'at://did:plc:user/app.bsky.actor.profile/self'
+});
+
+// Access profile data
+console.log(profile.value.displayName);
+console.log(profile.value.description);
+```
+
+## Blob Handling
+
+### Uploading Blobs
+
+```typescript
+// Read file as ArrayBuffer
+const file = await Deno.readFile('./image.jpg');
+
+// Upload blob
+const blobResponse = await client.uploadBlob({
+  data: file,
+  mimeType: 'image/jpeg'
+});
+
+// Use blob in a record
+const postWithImage = await client.com.example.post.createRecord({
+  title: "Post with Image",
+  content: "Check out this image!",
+  image: blobResponse.blob,
+  createdAt: new Date().toISOString()
+});
+```
+
+### Converting Blobs to CDN URLs
+
+```typescript
+import { recordBlobToCdnUrl } from "./generated-client.ts";
+
+// Get a record with a blob
+const profile = await client.app.bsky.actor.profile.getRecord({
+  uri: 'at://did:plc:user/app.bsky.actor.profile/self'
+});
+
+// Convert avatar blob to CDN URL
+if (profile.value.avatar) {
+  const avatarUrl = recordBlobToCdnUrl(
+    profile,
+    profile.value.avatar,
+    'avatar' // Size preset
+  );
+  console.log(`Avatar URL: ${avatarUrl}`);
+}
+
+// Available presets:
+// - 'avatar': Small square images
+// - 'banner': Wide header images
+// - 'feed_thumbnail': Small feed previews
+// - 'feed_fullsize': Full resolution images
+```
+
+## Slice Operations
+
+### Get Slice Statistics
+
+```typescript
+const stats = await client.social.slices.slice.stats({
+  slice: 'at://your-slice-uri'
+});
+
+console.log(`Total records: ${stats.totalRecords}`);
+console.log(`Total actors: ${stats.totalActors}`);
+
+stats.collectionStats.forEach(stat => {
+  console.log(`${stat.collection}: ${stat.recordCount} records`);
+});
+```
+
+### Browse Slice Records
+
+```typescript
+const records = await client.social.slices.slice.records({
+  slice: 'at://your-slice-uri',
+  collection: 'com.example.post',
+  limit: 50
+});
+
+records.records.forEach(record => {
+  console.log(`${record.uri}: ${JSON.stringify(record.value)}`);
+});
+```
+
+### Sync User Collections
+
+```typescript
+// Sync current user's data (requires auth)
+const syncResult = await client.social.slices.slice.syncUserCollections({
+  timeoutSeconds: 30
+});
+
+console.log(`Synced ${syncResult.recordsSynced} records`);
+```
+
+## Error Handling
+
+```typescript
+try {
+  const post = await client.com.example.post.getRecord({
+    uri: 'at://invalid-uri'
+  });
+} catch (error) {
+  if (error.message.includes('404')) {
+    console.log('Record not found');
+  } else if (error.message.includes('401')) {
+    console.log('Authentication required');
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## OAuth Authentication Flow
+
+### 1. Initialize OAuth
+
+```typescript
+const oauthClient = new OAuthClient({
+  clientId: process.env.OAUTH_CLIENT_ID,
+  clientSecret: process.env.OAUTH_CLIENT_SECRET,
+  authBaseUrl: process.env.OAUTH_AIP_BASE_URL,
+  redirectUri: 'https://your-app.com/oauth/callback'
+});
+```
+
+### 2. Start Authorization
+
+```typescript
+const authResult = await oauthClient.authorize({
+  loginHint: 'user.bsky.social'
+});
+
+// Redirect user to authorization URL
+window.location.href = authResult.authorizationUrl;
+```
+
+### 3. Handle Callback
+
+```typescript
+// In your callback handler
+const urlParams = new URLSearchParams(window.location.search);
+const code = urlParams.get('code');
+const state = urlParams.get('state');
+
+await oauthClient.handleCallback({ code, state });
+```
+
+### 4. Use Authenticated Client
+
+```typescript
+const client = new AtProtoClient(apiUrl, sliceUri, oauthClient);
+
+// OAuth tokens are automatically managed
+const profile = await client.social.slices.actor.profile.createRecord({
+  displayName: "New User",
+  description: "My profile"
+}, true); // useSelfRkey for profile
+```
+
+## Type Safety
+
+The generated SDK provides full TypeScript type safety:
+
+```typescript
+// TypeScript knows the shape of your records
+const post = await client.com.example.post.getRecord({ uri });
+
+// Type error: property 'unknownField' does not exist
+// post.value.unknownField
+
+// Autocomplete works for all fields
+post.value.title;      // string
+post.value.tags;       // string[]
+post.value.createdAt;  // string
+
+// Creating records is type-checked
+await client.com.example.post.createRecord({
+  title: "Valid",
+  content: "Also valid",
+  createdAt: new Date().toISOString(),
+  // Type error: 'invalidField' is not assignable
+  // invalidField: "This will error"
+});
+```
+
+## Advanced Patterns
+
+### Batch Operations
+
+```typescript
+// Process records in batches
+async function* getAllRecords() {
+  let cursor: string | undefined;
+  
+  do {
+    const batch = await client.com.example.post.listRecords({
+      limit: 100,
+      cursor
+    });
+    
+    yield* batch.records;
+    cursor = batch.cursor;
+  } while (cursor);
+}
+
+// Use the generator
+for await (const record of getAllRecords()) {
+  console.log(record.value.title);
+}
+```
+
+
+## Next Steps
+
+- [API Reference](./api-reference.md) - Complete endpoint documentation
+- [Concepts](./concepts.md) - Understand the architecture
+- [Getting Started](./getting-started.md) - Initial setup guide