docs and more docs

README.md

···
 # Slices
 
-An open-source platform for building AT Protocol appviews with custom data
+An open-source platform for building AT Protocol AppViews with custom data
 schemas, automatic SDK generation, and built-in sync capabilities.
 
+⚠️ **Alpha Release** Version 0.x - This project is in active development
+approaching stability. Core features are implemented and functional, though APIs
+may undergo refinements. Suitable for early adoption and development use.
+Production deployment is possible with thorough testing for your specific use
+case.
+
 ## Overview
 
 Slices enables developers to create "slices" - custom appviews within the AT
···
 - **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)
+- **Dynamic API Endpoints**: CRUD operations with SQL-like queries automatically
+  created for each lexicon record type (collection)
 
 ## Documentation
 
···
 - [API Reference](./docs/api-reference.md) - Complete API documentation
 - [SDK Usage](./docs/sdk-usage.md) - Using generated TypeScript clients
 
-## Quick Start
+## Development Quick Start
 
 ### Prerequisites
 
···
 1. Clone the repository:
 
 ```bash
-git clone https://tangled.sh/justslices.net/core
+git clone https://tangled.sh/slices.network/slices
 cd core
 ```
 
 2. Set up environment variables:
 
-Create `.env` files in both `/api` and `/frontend` directories (see
-[Getting Started](./docs/getting-started.md) for details).
+Create `.env` files in both `/api` and `/frontend` directories (see environment
+variables section below).
+
+3. Start the required infrastructure services:
+
+> **Note**: This section is a work in progress. Currently using Cloudflare
+> tunnels, but support for alternative solutions like ngrok or Tailscale would
+> be welcome contributions.
+
+```bash
+# Start PostgreSQL, AIP OAuth service, Cloudflare tunnel, and Redis
+CLOUDFLARE_TUNNEL_TOKEN=<your-token> AIP_EXTERNAL_BASE=<your-tunnel-url> docker compose up -d
+```
 
-3. Start the services:
+You'll need to provide:
+
+- `CLOUDFLARE_TUNNEL_TOKEN`: Your Cloudflare tunnel token for secure access
+- `AIP_EXTERNAL_BASE`: The external URL for the AIP OAuth service (e.g.,
+  `https://tunnel.example.com`)
+
+4. Start the application services:
 
 ```bash
 # Start the API
···
 deno task dev
 ```
 
-4. Visit `http://localhost:8000` to access the web interface.
+5. Visit `http://localhost:8080` to access the web interface.
 
 ## Project Structure
 
···
 
 - **AT Protocol XRPC Handlers**: Dynamic endpoints for slice-specific
   collections with full CRUD operations
+- **Lexicon Validation**: Validates all records against defined lexicon schemas
 - **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
 
 ### Frontend (`/frontend`)
···
 
 ### 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       |
+| Variable                               | Description                                                    | Required | Default                               |
+| -------------------------------------- | -------------------------------------------------------------- | -------- | ------------------------------------- |
+| `DATABASE_URL`                         | PostgreSQL connection string                                   | Yes      | -                                     |
+| `AUTH_BASE_URL`                        | Authentication service base URL                                | No       | `http://localhost:8081`               |
+| `PORT`                                 | Server port                                                    | No       | `3000`                                |
+| `PROCESS_TYPE`                         | Process type: `all` (HTTP + Jetstream), `app`, or `worker`     | No       | `all`                                 |
+| `RELAY_ENDPOINT`                       | AT Protocol relay endpoint for backfill                        | No       | `https://relay1.us-west.bsky.network` |
+| `JETSTREAM_HOSTNAME`                   | AT Protocol Jetstream hostname                                 | No       | -                                     |
+| `SYSTEM_SLICE_URI`                     | System slice URI                                               | No       | Default slice URI                     |
+| `DEFAULT_MAX_SYNC_REPOS`               | Maximum repositories per sync operation                        | No       | `5000`                                |
+| `REDIS_URL`                            | Redis connection URL (optional, falls back to in-memory cache) | No       | -                                     |
+| `REDIS_TTL_SECONDS`                    | Redis cache TTL in seconds                                     | No       | `3600`                                |
+| `JETSTREAM_CURSOR_WRITE_INTERVAL_SECS` | Interval for writing Jetstream cursor position                 | No       | `30`                                  |
+| `RUST_LOG`                             | Rust logging level                                             | No       | `debug`                               |
 
 ### 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      |
+| Variable              | Description                                   | Required | Default     |
+| --------------------- | --------------------------------------------- | -------- | ----------- |
+| `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      | -           |
+| `ADMIN_DID`           | Admin DID for privileged operations           | No       | -           |
+| `DATABASE_URL`        | SQLite database path (frontend session store) | No       | `slices.db` |
 
 ## Roadmap
 
···
 - 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
+- SDK error handling improvements (i.e. fuzzy search, date ranges, geo?? etc)
+- Improve sync and jetstream performace, logging, error handling, and
+  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
+- More cli templates (React, Expo, Astro, etc) and examples
 
 ## Community
 
-- **Bluesky**: [@justslices.net](https://bsky.app/profile/justslices.net)
-- **Discord**: [Join our server](https://discord.gg/your-invite)
+- **Bluesky**: [@slices.network](https://bsky.app/profile/slices.network)
+- **Discord**: [Join our server](https://discord.gg/NqSd3eW8S8)
 
 ## Support
 
 - [Documentation](./docs/)
-- [Discord Community](https://discord.gg/your-invite)
+- [Discord Community](https://discord.gg/NqSd3eW8S8)
 
 ## License
 
···
 
 - 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.
+- Thanks to all contributors and early adopters
 
 ---
 

docs/api-reference.md

···
 # API Reference
 
-Complete reference for Slices API endpoints.
-
 ## Base URL
 
-```bash
+```
 https://api.slices.network/xrpc/
 ```
 
-## Authentication
-
-Most write operations require OAuth 2.0 authentication. Include the access token
-in the Authorization header:
-
+For local development:
 ```
-Authorization: Bearer YOUR_ACCESS_TOKEN
+http://localhost:3000/xrpc/
 ```
 
-Read operations typically work without authentication.
-
-## Dynamic Collection Endpoints
-
-For each collection in your slice, the following endpoints are automatically
-generated:
-
-### `[collection].getRecords`
-
-Get records in a collection.
-
-**Method**: GET
-
-**Parameters**:
-
-- `slice` (string, required): Slice URI
-- `limit` (number, optional): Maximum records (default: 50)
-- `cursor` (string, optional): Pagination cursor
-- `where` (object, optional): Filter conditions using field-specific queries
-- `sortBy` (array, optional): Sort specification with field and direction
-  objects
-
-### `[collection].getRecord`
-
-Get a single record.
-
-**Method**: GET
+## Authentication
 
-**Parameters**:
+Write operations require OAuth 2.0 authentication with a Bearer token:
 
-- `slice` (string, required): Slice URI
-- `uri` (string, required): Record URI
-
-### `[collection].countRecords`
-
-Count records in a collection.
-
-**Method**: GET
-
-**Parameters**:
-
-- `slice` (string, required): Slice URI
-- `where` (object, optional): Filter conditions using field-specific queries
-- Other filter parameters (no limit/cursor)
-
-**Response**:
-
-```json Code
-{
-  "count": 150
-}
 ```
-
-### `[collection].createRecord`
-
-Create a new record.
-
-**Method**: POST
-
-**Authentication**: Required
-
-**Body**:
-
-```json Code
-{
-  "slice": "at://your-slice-uri",
-  "record": {
-    "$type": "com.recordcollector.album",
-    "title": "Superunknown",
-    "artist": "Soundgarden",
-    "releaseDate": "1994-03-08",
-    "condition": "Near Mint",
-    "genre": ["grunge", "alternative metal"]
-  },
-  "rkey": "3jklmno456"
-}
+Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-### `[collection].updateRecord`
-
-Update an existing record.
-
-**Method**: POST
-
-**Authentication**: Required
-
-**Body**:
-
-```json Code
-{
-  "slice": "at://your-slice-uri",
-  "rkey": "3xyz789abc",
-  "record": {
-    "$type": "com.recordcollector.album",
-    "title": "Dirt",
-    "artist": "Alice in Chains",
-    "releaseDate": "1992-09-29",
-    "condition": "Very Good Plus",
-    "notes": "Minor sleeve wear, vinyl plays perfectly"
-  }
-}
-```
+Read operations are public by default.
 
-### `[collection].deleteRecord`
+## Collection Endpoints
 
-Delete a record.
+For each collection in your slice (e.g., `com.recordcollector.album`), the following endpoints are automatically generated:
 
-**Method**: POST
+# **{collection}.getRecords**
 
-**Authentication**: Required
+> List records with filtering, sorting, and pagination.
 
-**Body**:
+**Method:** `POST`
+**Endpoint:** `/xrpc/{collection}.getRecords`
+**Example:** `/xrpc/com.recordcollector.album.getRecords`
 
-```json Code
+**Request Body:**
+```json
 {
-  "rkey": "3abc123xyz"
+  "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+  "limit": 20,
+  "cursor": "optional-pagination-cursor",
+  "where": {
+    "genre": { "contains": "grunge" },
+    "condition": { "in": ["Mint", "Near Mint"] }
+  },
+  "sortBy": [
+    { "field": "releaseDate", "direction": "desc" }
+  ]
 }
 ```
 
-## Core Endpoints
-
-### Slice Management
+**Parameters:**
+- `slice` (string, required): The slice URI to query
+- `limit` (number, optional): Maximum records to return (default: 50, max: 100)
+- `cursor` (string, optional): Pagination cursor from previous response
+- `where` (object, optional): Filter conditions. Field filters support operators: `eq`, `contains`, `in`. Special field `json` searches across all fields
+- `sortBy` (array, optional): Sort specification. Each item has `field` and `direction` ("asc" or "desc")
 
-### `network.slices.slice.getRecords`
-
-Get all slices.
-
-**Method**: GET
-
-**Parameters**:
-
-- `limit` (number, optional): Maximum records to return (default: 50)
-- `cursor` (string, optional): Pagination cursor
-- `where` (object, optional): Filter conditions using field-specific queries
-- `sortBy` (array, optional): Sort specification with field and direction
-  objects
-
-**Response**:
-
-```json Code
+**Response:**
+```json
 {
   "records": [
     {
-      "uri": "at://did:plc:abc/network.slices.slice/xyz",
-      "cid": "bafyrei...",
-      "did": "did:plc:abc",
-      "collection": "network.slices.slice",
+      "uri": "at://did:plc:user123/com.recordcollector.album/3l2w4x5y6z",
+      "cid": "bafyreigbtj4x7ip5legnfznufuopl4sg4knzc2cof6duas4b3q2fy6swua",
+      "did": "did:plc:user123",
+      "collection": "com.recordcollector.album",
       "value": {
-        "name": "My Slice",
-        "domain": "com.example",
-        "createdAt": "2024-01-01T00:00:00Z"
+        "$type": "com.recordcollector.album",
+        "title": "Nevermind",
+        "artist": "Nirvana",
+        "releaseDate": "1991-09-24T00:00:00.000Z",
+        "genre": ["grunge", "alternative rock"],
+        "condition": "Near Mint",
+        "notes": "Original pressing, includes poster"
       },
-      "indexedAt": "2024-01-01T00:00:00Z"
+      "indexedAt": "2024-03-15T10:30:15.123Z"
     }
   ],
-  "cursor": "next-page-cursor"
+  "cursor": "next-page-cursor-xyz789"
 }
 ```
 
-### `network.slices.slice.getRecord`
-
-Get a specific slice by URI.
+# **{collection}.getRecord**
 
-**Method**: GET
-
-**Parameters**:
-
-- `uri` (string, required): AT Protocol URI of the slice
-
-**Response**: Single record object (same structure as getRecords item)
-
-### `network.slices.slice.createRecord`
-
-Create a new slice.
-
-**Method**: POST
+> Get a single record by URI.
 
-**Authentication**: Required
+**Method:** `GET`
+**Endpoint:** `/xrpc/{collection}.getRecord`
+**Example:** `/xrpc/com.recordcollector.album.getRecord`
 
-**Body**:
+**Query Parameters:**
+- `slice` (string, required): The slice URI
+- `uri` (string, required): The AT Protocol URI of the record
 
-```json Code
-{
-  "slice": "at://your-slice-uri",
-  "record": {
-    "$type": "network.slices.slice",
-    "name": "My New Slice",
-    "domain": "com.example",
-    "createdAt": "2024-01-01T00:00:00Z"
-  },
-  "rkey": "optional-record-key"
-}
+**Example Request:**
+```
+GET /xrpc/com.recordcollector.album.getRecord?slice=at://did:plc:abc123/network.slices.slice/xyz789&uri=at://did:plc:user123/com.recordcollector.album/3l2w4x5y6z
 ```
 
-**Response**:
-
-```json Code
+**Response:**
+```json
 {
-  "uri": "at://did:plc:abc/network.slices.slice/xyz",
-  "cid": "bafyrei..."
+  "uri": "at://did:plc:user123/com.recordcollector.album/3l2w4x5y6z",
+  "cid": "bafyreigbtj4x7ip5legnfznufuopl4sg4knzc2cof6duas4b3q2fy6swua",
+  "did": "did:plc:user123",
+  "collection": "com.recordcollector.album",
+  "value": {
+    "$type": "com.recordcollector.album",
+    "title": "Nevermind",
+    "artist": "Nirvana",
+    "releaseDate": "1991-09-24T00:00:00.000Z",
+    "genre": ["grunge", "alternative rock"],
+    "condition": "Near Mint",
+    "notes": "Original pressing, includes poster"
+  },
+  "indexedAt": "2024-03-15T10:30:15.123Z"
 }
 ```
 
-### Slice Operations
+# **{collection}.countRecords**
 
-### `network.slices.slice.stats`
+> Count records matching filter criteria.
 
-Get statistics for a slice.
+**Method:** `POST`
+**Endpoint:** `/xrpc/{collection}.countRecords`
+**Example:** `/xrpc/com.recordcollector.album.countRecords`
 
-**Method**: POST
-
-**Body**:
-
-```json Code
+**Request Body:**
+```json
 {
-  "slice": "at://your-slice-uri"
+  "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+  "where": {
+    "condition": { "in": ["Mint", "Near Mint"] },
+    "genre": { "contains": "grunge" }
+  }
 }
 ```
 
-**Response**:
-
-```json Code
+**Response:**
+```json
 {
   "success": true,
-  "collections": ["com.recordcollector.album", "com.recordcollector.review"],
-  "collectionStats": [
-    {
-      "collection": "com.recordcollector.album",
-      "recordCount": 427,
-      "uniqueActors": 23
-    }
-  ],
-  "totalLexicons": 5,
-  "totalRecords": 500,
-  "totalActors": 25,
-  "message": "Statistics retrieved successfully"
+  "count": 42,
+  "message": "Count retrieved successfully"
 }
 ```
 
-### `network.slices.slice.listSliceRecords`
+# **{collection}.createRecord**
 
-List records across multiple collections in a slice.
+> Create a new record.
 
-**Method**: POST
-
-**Body**:
+**Method:** `POST`
+**Endpoint:** `/xrpc/{collection}.createRecord`
+**Example:** `/xrpc/com.recordcollector.album.createRecord`
+**Authentication:** Required
 
-```json Code
+**Request Body:**
+```json
 {
-  "slice": "at://your-slice-uri",
-  "collections": ["com.recordcollector.album", "com.recordcollector.review"],
-  "authors": ["did:plc:optional-filter"],
-  "limit": 20,
-  "cursor": "pagination-cursor"
+  "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+  "rkey": "optional-custom-key",
+  "record": {
+    "$type": "com.recordcollector.album",
+    "title": "In Utero",
+    "artist": "Nirvana",
+    "releaseDate": "1993-09-21T00:00:00.000Z",
+    "genre": ["grunge", "alternative rock"],
+    "condition": "Very Good Plus",
+    "notes": "Some light wear on sleeve"
+  }
 }
 ```
 
-**Response**:
+**Parameters:**
+- `slice` (string, required): The slice URI
+- `rkey` (string, optional): Custom record key (auto-generated if omitted)
+- `record` (object, required): The record data matching your lexicon schema
 
-```json Code
+**Response:**
+```json
 {
-  "success": true,
-  "records": [
-    {
-      "uri": "at://did:plc:abc/com.recordcollector.album/xyz",
-      "cid": "bafyrei...",
-      "did": "did:plc:abc",
-      "collection": "com.recordcollector.album",
-      "value": {/* record data */},
-      "indexedAt": "2024-01-01T00:00:00Z"
-    }
-  ],
-  "cursor": "next-page-cursor"
+  "uri": "at://did:plc:user123/com.recordcollector.album/3abc456def",
+  "cid": "bafyreihj7x5legnfznufuopl4sg4knzc2cof6duas4b3q2fy6swua"
 }
 ```
 
-### `network.slices.slice.searchSliceRecords`
-
-Search records across multiple collections in a slice by content.
+# **{collection}.updateRecord**
 
-**Method**: POST
+> Update an existing record.
 
-**Body**:
+**Method:** `POST`
+**Endpoint:** `/xrpc/{collection}.updateRecord`
+**Example:** `/xrpc/com.recordcollector.album.updateRecord`
+**Authentication:** Required
 
-```json Code
+**Request Body:**
+```json
 {
-  "slice": "at://your-slice-uri",
-  "collections": ["com.recordcollector.album", "com.recordcollector.review"],
-  "search": "search term",
-  "authors": ["did:plc:optional-filter"],
-  "limit": 20,
-  "cursor": "pagination-cursor"
+  "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+  "rkey": "3abc456def",
+  "record": {
+    "$type": "com.recordcollector.album",
+    "title": "In Utero",
+    "artist": "Nirvana",
+    "releaseDate": "1993-09-21T00:00:00.000Z",
+    "genre": ["grunge", "alternative rock", "noise rock"],
+    "condition": "Very Good",
+    "notes": "Updated: slight ring wear visible, plays perfectly"
+  }
 }
 ```
 
-**Response**:
+**Parameters:**
+- `slice` (string, required): The slice URI
+- `rkey` (string, required): The record key to update
+- `record` (object, required): The complete updated record data
 
-```json Code
+**Response:**
+```json
 {
-  "success": true,
-  "records": [
-    {
-      "uri": "at://did:plc:abc/com.recordcollector.album/xyz",
-      "cid": "bafyrei...",
-      "did": "did:plc:abc",
-      "collection": "com.recordcollector.album",
-      "value": {/* record data */},
-      "indexedAt": "2024-01-01T00:00:00Z"
-    }
-  ],
-  "cursor": "next-page-cursor"
+  "uri": "at://did:plc:user123/com.recordcollector.album/3abc456def",
+  "cid": "bafyreiabc123legnfznufuopl4sg4knzc2cof6duas4b3q2fy6swua"
 }
 ```
 
-### `network.slices.slice.syncUserCollections`
+# **{collection}.deleteRecord**
 
-Synchronously sync collections for the authenticated user.
+> Delete a record.
 
-**Method**: POST
-
-**Authentication**: Required
-
-**Body**:
+**Method:** `POST`
+**Endpoint:** `/xrpc/{collection}.deleteRecord`
+**Example:** `/xrpc/com.recordcollector.album.deleteRecord`
+**Authentication:** Required
 
-```json Code
+**Request Body:**
+```json
 {
-  "slice": "at://your-slice-uri",
-  "timeoutSeconds": 30
+  "rkey": "3abc456def"
 }
 ```
 
-**Response**:
-
-```json Code
-{
-  "success": true,
-  "reposProcessed": 1,
-  "recordsSynced": 45,
-  "timedOut": false,
-  "message": "Sync completed successfully"
-}
+**Response:**
+```json
+{}
 ```
 
-### `network.slices.slice.startSync`
+## Filtering
 
-Start an asynchronous bulk sync job.
+The `where` parameter supports powerful filtering:
 
-**Method**: POST
+### Filter Operators
 
-**Authentication**: Required
-
-**Body**:
-
-```json Code
-{
-  "slice": "at://your-slice-uri",
-  "collections": ["com.recordcollector.album"],
-  "externalCollections": ["app.bsky.actor.profile"],
-  "repos": ["did:plc:abc", "did:plc:xyz"],
-  "limitPerRepo": 100
-}
+- **`eq`**: Exact match
+```json
+{ "condition": { "eq": "Mint" } }
 ```
 
-**Response**:
+- **`contains`**: Partial text match (case-insensitive)
+```json
+{ "artist": { "contains": "pearl jam" } }
+```
 
-```json Code
-{
-  "success": true,
-  "jobId": "job-uuid",
-  "message": "Sync job started"
-}
+- **`in`**: Match any value in array
+```json
+{ "condition": { "in": ["Mint", "Near Mint", "Very Good Plus"] } }
 ```
 
-### `network.slices.slice.codegen`
+### Special Fields
 
-Generate TypeScript client code.
-
-**Method**: POST
-
-**Body**:
-
-```json Code
-{
-  "target": "typescript",
-  "slice": "at://your-slice-uri"
-}
+- **`json`**: Search across all fields
+```json
+{ "json": { "contains": "nirvana" } }
 ```
 
-**Response**:
-
-```json Code
+- **System fields**: Filter by record metadata
+```json
 {
-  "success": true,
-  "generatedCode": "// Generated TypeScript client code..."
+  "did": { "eq": "did:plc:user123" },
+  "collection": { "eq": "com.recordcollector.album" },
+  "indexedAt": { "contains": "2024-03" }
 }
 ```
 
-## Lexicon Management
+### Complex Filtering Examples
 
-### `network.slices.lexicon.getRecords`
-
-Get lexicons in a slice.
-
-**Method**: GET
-
-**Parameters**: Same as collection.getRecords
-
-### `network.slices.lexicon.countRecords`
-
-Count lexicons in a slice.
-
-**Method**: GET
-
-**Parameters**: Same as collection.getRecords (except limit and cursor)
-
-**Response**:
-
-```json Code
+**Multiple conditions (AND logic):**
+```json
 {
-  "count": 10
+  "where": {
+    "genre": { "contains": "grunge" },
+    "condition": { "in": ["Mint", "Near Mint"] },
+    "releaseDate": { "contains": "1991" }
+  }
 }
 ```
 
-### `network.slices.lexicon.createRecord`
-
-Add a lexicon to a slice.
-
-**Method**: POST
-
-**Authentication**: Required
-
-**Body**:
-
-```json Code
+**Array field filtering:**
+```json
 {
-  "slice": "at://your-slice-uri",
-  "record": {
-    "$type": "network.slices.lexicon",
-    "nsid": "com.recordcollector.album",
-    "definitions": "{\"lexicon\": 1, ...}",
-    "createdAt": "2024-01-01T00:00:00Z",
-    "slice": "at://your-slice-uri"
+  "where": {
+    "genre": { "contains": "alternative" }
   }
 }
 ```
 
-## Actor Management
-
-### `network.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
+## Sorting
 
-**Response**:
+Sort results using the `sortBy` parameter:
 
-```json Code
+```json
 {
-  "actors": [
-    {
-      "did": "did:plc:abc",
-      "handle": "user.bsky.social",
-      "sliceUri": "at://slice-uri",
-      "indexedAt": "2024-01-01T00:00:00Z"
-    }
-  ],
-  "cursor": "next-page"
+  "sortBy": [
+    { "field": "releaseDate", "direction": "desc" },
+    { "field": "artist", "direction": "asc" }
+  ]
 }
 ```
 
-## Blob Upload
+**Common sort patterns:**
+- Newest releases first: `[{ "field": "releaseDate", "direction": "desc" }]`
+- Alphabetical by artist: `[{ "field": "artist", "direction": "asc" }]`
+- By condition (best first): `[{ "field": "condition", "direction": "asc" }]`
+- Recently indexed: `[{ "field": "indexedAt", "direction": "desc" }]`
 
-### `com.atproto.repo.uploadBlob`
+## Pagination
 
-Upload a blob (image, file).
+Use cursor-based pagination for large result sets:
 
-**Method**: POST
+```javascript
+// First request
+const page1 = await fetch('/xrpc/com.recordcollector.album.getRecords', {
+  method: 'POST',
+  body: JSON.stringify({
+    slice: 'at://your-slice-uri',
+    limit: 20
+  })
+});
 
-**Authentication**: Required
-
-**Headers**:
-
-- `Content-Type`: MIME type of the blob
-
-**Body**: Raw binary data
-
-**Response**:
-
-```json Code
-{
-  "blob": {
-    "$type": "blob",
-    "ref": { "$link": "bafkrei..." },
-    "mimeType": "image/jpeg",
-    "size": 127198
-  }
-}
+// Next page using cursor
+const page2 = await fetch('/xrpc/com.recordcollector.album.getRecords', {
+  method: 'POST',
+  body: JSON.stringify({
+    slice: 'at://your-slice-uri',
+    limit: 20,
+    cursor: page1.cursor
+  })
+});
 ```
 
 ## Error Responses
 
-All endpoints may return error responses:
+All endpoints return consistent error format:
 
-```json Code
+```json
 {
   "error": "InvalidRequest",
-  "message": "Detailed error message"
+  "message": "Missing required parameter: slice"
 }
 ```
 
-Common HTTP status codes:
-
+**Common HTTP Status Codes:**
 - `200`: Success
-- `400`: Bad request
-- `401`: Authentication required
-- `403`: Forbidden
-- `404`: Not found
+- `400`: Bad request (invalid parameters)
+- `401`: Unauthorized (missing/invalid auth token)
+- `403`: Forbidden (insufficient permissions)
+- `404`: Not found (record/collection doesn't exist)
 - `500`: Internal server error
 
-## Pagination
+## OpenAPI Specification
 
-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
+Get the OpenAPI spec for your slice:
 
-Example:
+**Method:** `GET`
+**Endpoint:** `/xrpc/network.slices.slice.openapi`
 
-```javascript
-let cursor = undefined;
-do {
-  const response = await fetch(`/xrpc/collection.getRecords?cursor=${cursor}`);
-  const data = await response.json();
-  // Process records
-  cursor = data.cursor;
-} while (cursor);
-```
+**Query Parameters:**
+- `slice` (string, required): The slice URI
 
-## Filtering
+**Response:** OpenAPI 3.0 specification with all available endpoints
 
-List endpoints support filtering using the `where` parameter with field-specific
-query operators:
+## Example: Record Collector Application
 
-### Filter Operators
+Here's a complete example using the record collector lexicon:
 
-- `eq`: Exact match
-- `contains`: Partial text match (case-insensitive)
-- `in`: Match any value in array
-
-### Examples
-
-**Exact match filtering:**
-
-```json Code
+### Lexicon Definition
+```json
 {
-  "where": {
-    "artist": { "eq": "Nirvana" },
-    "condition": { "eq": "Mint" }
+  "lexicon": 1,
+  "id": "com.recordcollector.album",
+  "defs": {
+    "main": {
+      "type": "record",
+      "record": {
+        "type": "object",
+        "required": ["title", "artist", "releaseDate"],
+        "properties": {
+          "title": { "type": "string", "description": "Album title" },
+          "artist": { "type": "string", "description": "Artist or band name" },
+          "releaseDate": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Original release date"
+          },
+          "genre": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Music genres"
+          },
+          "condition": {
+            "type": "string",
+            "description": "Vinyl condition (Mint, Near Mint, etc.)"
+          },
+          "notes": {
+            "type": "string",
+            "description": "Collector notes"
+          }
+        }
+      }
+    }
   }
 }
 ```
 
-**Text search filtering:**
-
-```json Code
-{
-  "where": {
-    "title": { "contains": "nevermind" },
-    "genre": { "contains": "grunge" }
-  }
-}
+### List Albums by Genre
+```bash
+curl -X POST "https://api.slices.network/xrpc/com.recordcollector.album.getRecords" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+    "where": { "genre": { "contains": "grunge" } },
+    "sortBy": [{ "field": "releaseDate", "direction": "desc" }],
+    "limit": 10
+  }'
 ```
 
-**Array filtering:**
-
-```json Code
-{
-  "where": {
-    "condition": { "in": ["Mint", "Near Mint", "Very Good Plus"] },
-    "artist": { "in": ["Nirvana", "Pearl Jam", "Soundgarden"] }
-  }
-}
+### Add New Album to Collection
+```bash
+curl -X POST "https://api.slices.network/xrpc/com.recordcollector.album.createRecord" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+    "record": {
+      "$type": "com.recordcollector.album",
+      "title": "Superunknown",
+      "artist": "Soundgarden",
+      "releaseDate": "1994-03-08T00:00:00.000Z",
+      "genre": ["grunge", "alternative metal"],
+      "condition": "Near Mint",
+      "notes": "Limited edition orange vinyl"
+    }
+  }'
 ```
 
-**Global search across all fields:**
-
-```json Code
-{
-  "where": {
-    "json": { "contains": "grunge" }
-  }
-}
+### Search Collection by Condition
+```bash
+curl -X POST "https://api.slices.network/xrpc/com.recordcollector.album.getRecords" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+    "where": {
+      "condition": { "in": ["Mint", "Near Mint"] },
+      "releaseDate": { "contains": "199" }
+    },
+    "sortBy": [{ "field": "artist", "direction": "asc" }]
+  }'
 ```
 
-## Sorting
+### Count Albums in Collection
+```bash
+curl -X POST "https://api.slices.network/xrpc/com.recordcollector.album.countRecords" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+    "where": { "condition": { "eq": "Mint" } }
+  }'
+```
 
-Sort parameter uses an array format with field and direction:
-
-```json Code
-{
-  "sortBy": [
-    { "field": "releaseDate", "direction": "desc" },
-    { "field": "title", "direction": "asc" }
-  ]
-}
+### Update Album Condition
+```bash
+curl -X POST "https://api.slices.network/xrpc/com.recordcollector.album.updateRecord" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "slice": "at://did:plc:abc123/network.slices.slice/xyz789",
+    "rkey": "3abc456def",
+    "record": {
+      "$type": "com.recordcollector.album",
+      "title": "Ten",
+      "artist": "Pearl Jam",
+      "releaseDate": "1991-08-27T00:00:00.000Z",
+      "genre": ["grunge", "alternative rock"],
+      "condition": "Very Good",
+      "notes": "Updated after closer inspection - slight scuffs on Side B"
+    }
+  }'
 ```
 
-Examples:
-
-- `[{ "field": "releaseDate", "direction": "desc" }]` - Newest releases first
-- `[{ "field": "artist", "direction": "asc" }]` - Alphabetical by artist
-- `[{ "field": "releaseDate", "direction": "desc" }, { "field": "title", "direction": "asc" }]` -
-  Newest first, then alphabetical by title
-
 ## 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
+- [Concepts](./concepts.md) - Understand the architecture

docs/concepts.md

···
 # Core Concepts
 
-Understanding these core concepts will help you effectively use Slices.
+Slices is built on four fundamental concepts that work together to create a
+powerful AT Protocol development platform.
+
+```
+Slices → Lexicons → Sync → APIs
+(Container) → (Schema) → (Data) → (Access)
+```
+
+## **Slices**: Your Data Universe
+
+### What is a Slice?
+
+A slice is your own independent data space within the AT Protocol network. Think
+of it as a database with built-in APIs, authentication, and real-time sync, all
+isolated from other slices.
 
-## Slices
+### Why Slices Matter
+
+In the AT Protocol ecosystem, data lives on Personal Data Servers (PDS)
+scattered across the network. Slices acts as an **AppView** that:
+
+- Aggregates data from across the network
+- Applies your custom schemas
+- Provides instant APIs for your data
+- Maintains complete data isolation
+
+### Creating Your Slice
+
+When you create a slice for `com.recordcollector`:
+
+```
+Slice Name: My Vinyl Collection
+Domain: com.recordcollector
+URI: at://did:plc:abc123/network.slices.slice/xyz789
+```
 
-A slice is an independent appview within the AT Protocol ecosystem. Think of it
-as your own data universe with custom schemas and records.
+This slice becomes the container for all your vinyl collection data, completely
+isolated from other slices.
 
 ### Key Properties
 
-- **URI**: Unique AT Protocol URI (e.g.,
-  `at://did:plc:abc123/network.slices.slice/3xyz`)
-- **Name**: Human-readable identifier
-- **Domain**: Namespace for lexicons (e.g., `com.example`, `social.grain`)
-- **Creation Date**: When the slice was created
+- **URI**: Unique AT Protocol identifier
+- **Domain**: Your namespace (e.g., `com.recordcollector`)
+- **Isolation**: Complete data separation between slices
+- **Multi-tenancy**: Multiple users can have data in the same slice
 
-### Slice Isolation
+### Example: Record Collector Slice
 
-Each slice maintains complete data isolation:
+```json
+{
+  "uri": "at://did:plc:abc123/network.slices.slice/xyz789",
+  "name": "Vinyl Collection Manager",
+  "domain": "com.recordcollector",
+  "createdAt": "2024-01-15T10:00:00Z"
+}
+```
 
-- 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**: Data Schemas
 
-## Lexicons
+### What are Lexicons?
 
-Lexicons are JSON schemas that define record types in AT Protocol. They specify
-the structure, validation rules, and metadata for records.
+Lexicons are JSON schemas that define the structure of your data in AT Protocol.
+They're like database tables with built-in validation. In Slices, these lexicons
+automatically generate APIs for you.
 
-### Lexicon Structure
+### Defining Your Data
 
-```json Code
+For a record collector app, you might define an album lexicon:
+
+```json
 {
   "lexicon": 1,
   "id": "com.recordcollector.album",
   "defs": {
     "main": {
       "type": "record",
-      "description": "A vinyl album record",
+      "description": "A vinyl album in the collection",
       "record": {
         "type": "object",
+        "required": ["title", "artist", "releaseDate"],
         "properties": {
-          "title": { "type": "string" },
-          "artist": { "type": "string" },
-          "releaseDate": { "type": "string", "format": "datetime" },
-          "condition": { "type": "string" }
-        },
-        "required": ["title", "artist"]
+          "title": {
+            "type": "string",
+            "description": "Album title"
+          },
+          "artist": {
+            "type": "string",
+            "description": "Artist or band name"
+          },
+          "releaseDate": {
+            "type": "string",
+            "format": "datetime",
+            "description": "Original release date"
+          },
+          "genre": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Musical genres"
+          },
+          "condition": {
+            "type": "string",
+            "enum": [
+              "Mint",
+              "Near Mint",
+              "Very Good Plus",
+              "Very Good",
+              "Good",
+              "Fair",
+              "Poor"
+            ],
+            "description": "Vinyl condition grading"
+          },
+          "notes": {
+            "type": "string",
+            "maxLength": 1000,
+            "description": "Collector's notes"
+          }
+        }
       }
     }
   }
 }
 ```
 
-### Supported Types
+### Primary vs External Lexicons
 
-- **Primitives**: string, number, integer, boolean
-- **Complex**: object, array, union, ref
-- **Special**: blob (for media), cid-link, at-uri
-- **Formats**: datetime, at-identifier, did, handle
+**Primary Lexicons**: Match your slice domain:
 
-### Lexicon Namespacing
+- `com.recordcollector.album`
+- `com.recordcollector.review`
+- `com.recordcollector.wishlist`
 
-Lexicons follow reverse domain naming:
+**External Lexicons**: From other namespaces:
 
-- `com.recordcollector.album` - An album in the recordcollector.com namespace
-- `com.recordcollector.review` - A vinyl review record
-- `network.slices.slice` - Core slice record type
-- `app.bsky.actor.profile` - Bluesky profile (external)
+- `app.bsky.actor.profile` (Bluesky profiles)
+- `sh.tangled.repo` (Tangled Repo)
+- `social.grain.photo` (Grain Photos)
+- `com.cassettecollector.tape` (Cassette Collector)
 
-## Collections
+### Automatic API Generation
 
-Collections are groups of records with the same lexicon type. They map directly
-to XRPC endpoints.
+Each lexicon with `type: "record"` automatically creates endpoints. Record types
+are the only lexicons that generate CRUD APIs:
 
-### Primary Collections
+```
+com.recordcollector.album (type: "record") →
+  /xrpc/com.recordcollector.album.getRecords
+  /xrpc/com.recordcollector.album.createRecord
+  /xrpc/com.recordcollector.album.updateRecord
+  /xrpc/com.recordcollector.album.deleteRecord
+```
 
-Collections that match your slice's domain namespace. For example, if your slice
-domain is `com.recordcollector`, then `com.recordcollector.album` would be a
-primary collection.
+Note: Other lexicon types (like `query`, `procedure`, or `subscription`) serve
+different purposes and don't create these standard CRUD endpoints.
 
-### External Collections
+## **Sync**: Data Flow
 
-Collections from other namespaces that you've synced into your slice. For
-example:
+### How Data Enters Your Slice
 
-- Bluesky profiles (`app.bsky.actor.profile`)
-- Bluesky posts (`app.bsky.feed.post`)
-- Collections from other slices
+The sync engine manages how data flows into your slice from the AT Protocol
+network.
 
-### Collection Operations
+### Three Sync Strategies
 
-Both primary and external collections support the same operations:
+#### 1. Bulk Sync: Historical Import
 
-- `*.getRecords` - Get records with pagination, filtering, and search
-- `*.getRecord` - Get single record by URI
-- `*.createRecord` - Create new record
-- `*.updateRecord` - Update existing record
-- `*.deleteRecord` - Remove record
-- `*.countRecords` - Count records with filtering
+Perfect for initial data loading or periodic updates. When you're first starting
+out, you might only be syncing your own records from your PDS. But as more
+people adopt your app and write records to their own PDSs, you can sync from
+their repositories too, growing your network.
 
-The key difference is conceptual: primary collections are "native" to your
-slice's domain, while external collections are imported from other namespaces.
+Specify:
 
-## Records
+- Collections to sync (e.g., `com.recordcollector.album`)
+- External collections (e.g., `app.bsky.actor.profile` for user profiles)
+- Specific repositories (DIDs) to import from
 
-Records are individual data items stored in collections.
+#### 2. User Sync: On-Demand
 
-### Record Properties
+Automatically syncs when users log in. This is primarily for discovering and
+syncing external collections. When a new user authenticates for the first time,
+they become an actor in your slice, allowing you to discover what external
+collections they have (like Bluesky profiles or posts) and sync that data from
+their PDS.
 
-- **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
+#### 3. Jetstream: Real-Time Updates
 
-### Record Keys (rkeys)
+Connects to the AT Protocol firehose for live updates. This tracks create,
+update, and delete events as they happen across the network.
 
-Records use keys for identification:
+```
+Firehose Event → Filter by Collection → Validate → Store in Slice
+```
 
-- **Self**: Special key for singleton records (e.g., profiles)
-- **TID**: Timestamp-based identifiers
-- **Custom**: User-defined keys
+### Syncing External Data
 
-### Record Lifecycle
+Import Bluesky profiles to show who owns each album and their Bluesky avatar.
+You can sync external collections like `app.bsky.actor.profile` to enrich your
+slice with user information from the broader AT Protocol network.
 
-1. **Creation**: Via API or sync
-2. **Indexing**: Stored in PostgreSQL
-3. **Updates**: New versions with new CIDs
-4. **Deletion**: Soft or hard delete
+### Performance Features
 
-## Sync Engine
+- **CID Deduplication**: Skips unchanged records
+- **Bulk Operations**: Processes thousands of records efficiently
+- **Actor Caching**: Reduces database lookups
+- **Auto-Recovery**: Handles network interruptions
 
-The sync engine imports AT Protocol data into your slice using multiple
-strategies for optimal performance and reliability.
+### Example: Syncing a Vinyl Community
 
-### Sync Types
+To sync all albums from a vinyl collecting community, you would:
 
-**Bulk Sync**: One-time import of historical data
+- List primary collections (`com.recordcollector.album`,
+  `com.recordcollector.review`)
+- Include external collections (`app.bsky.actor.profile`) to show collector
+  information
 
-- Specify collections to sync
-- Filter by repositories (DIDs)
-- Set limits per repository
-- Uses optimized bulk database operations
+## **Code Generation & XRPC Endpoints**: APIs & SDKs
 
-**User Sync**: Sync data for authenticated user
+### Dynamic API Creation
 
-- Automatic on login
-- Timeout protection (30 seconds default)
-- External collection discovery
-- Synchronous operation for immediate feedback
+Every record-type lexicon automatically generates REST-like XRPC endpoints.
 
-**Jetstream Sync**: Real-time updates via WebSocket
+### Generated Endpoints
 
-- Subscribe to AT Protocol firehose
-- Filter relevant events by slice collections
-- Automatic record updates and deletions
-- Built-in reconnection with exponential backoff
+For `com.recordcollector.album`:
 
-### Sync Process
+#### List Albums
 
-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)
+```http
+POST /xrpc/com.recordcollector.album.getRecords
+{
+  "slice": "at://your-slice-uri",
+  "where": { "genre": { "contains": "jazz" } },
+  "sortBy": [{ "field": "releaseDate", "direction": "desc" }],
+  "limit": 20
+}
+```
 
-### Performance Optimizations
+#### Add Album
 
-**CID-Based Deduplication**
+```http
+POST /xrpc/com.recordcollector.album.createRecord
+Authorization: Bearer YOUR_TOKEN
+{
+  "slice": "at://your-slice-uri",
+  "record": {
+    "title": "Kind of Blue",
+    "artist": "Miles Davis",
+    "releaseDate": "1959-08-17T00:00:00Z",
+    "genre": ["jazz", "modal jazz"],
+    "condition": "Very Good Plus"
+  }
+}
+```
 
-- Compare Content Identifiers (CIDs) before processing
-- Skip records that haven't changed since last sync
-- Reduces unnecessary database operations and validation overhead
+### TypeScript SDK Generation
 
-**Actor Caching**
+Slices generates a fully-typed TypeScript client:
 
-- 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
+```typescript
+// Generated SDK with full type safety
+import { AtprotoClient } from "./generated_client.ts";
 
-### Jetstream Reliability
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: "at://your-slice-uri",
+  auth: oauthClient,
+});
 
-**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
+// Fully typed operations
+const albums = await client.com.recordcollector.album.getRecords({
+  where: {
+    condition: { in: ["Mint", "Near Mint"] },
+    genre: { contains: "jazz" },
+  },
+  sortBy: [{ field: "artist", direction: "asc" }],
+  limit: 50,
+});
 
-### Core Handlers
-
-Built-in endpoints for slice management:
+// Type-safe record creation
+const newAlbum = await client.com.recordcollector.album.createRecord({
+  title: "Blue Train",
+  artist: "John Coltrane",
+  releaseDate: "1958-01-01T00:00:00Z",
+  genre: ["jazz", "hard bop"],
+  condition: "Near Mint",
+  notes: "Original Blue Note pressing",
+});
+```
 
-- `network.slices.slice.stats` - Slice statistics
-- `network.slices.slice.records` - Browse records
-- `network.slices.slice.codegen` - Generate SDKs
-- `network.slices.slice.sync` - Trigger sync
-
-### Handler Authentication
-
-- **Read Operations**: Optional auth (public by default)
-- **Write Operations**: Require OAuth tokens
-- **Admin Operations**: Require slice ownership
+### OAuth Integration
 
-## Generated SDKs
+Built-in OAuth 2.0 with PKCE:
 
-Type-safe client libraries generated from lexicons.
+- Read operations: Public by default
+- Write operations: Require authentication
+- Automatic token refresh
+- Secure session management
 
 ### SDK Features
 
-- **Type Safety**: Full TypeScript types
-- **Nested Structure**: Matches lexicon namespacing
-- **OAuth Integration**: Automatic token handling
-- **Error Handling**: Retry logic and graceful failures
+- **Type Safety**: Full TypeScript types from lexicons
+- **Nested APIs**: `client.com.recordcollector.album.*`
+- **Error Handling**: Automatic retries and graceful failures
+- **Blob Support**: Handle images and media files
 
-### SDK Generation Process
+## How It All Works Together
 
-1. Parse slice lexicons
-2. Generate TypeScript interfaces
-3. Create client classes
-4. Add utility functions
-5. Format and validate
+```
+1. Create Slice → Define namespace (com.recordcollector)
+                ↓
+2. Add Lexicons → Define data structure (album, review, wishlist)
+                ↓
+3. Sync Data → Import existing vinyl collections
+              → Subscribe to real-time updates
+                ↓
+4. Use APIs → Generated endpoints for all operations
+            → Type-safe SDK for your app
+```
 
-### Using Generated SDKs
+## Practical Example: Building a Vinyl Collector App
 
-```typescript Code
-// Initialize client
-const client = new AtProtoClient(apiUrl, sliceUri, oauthClient);
+### Step 1: Create Your Slice
 
-// Use nested structure matching lexicons
-await client.com.recordcollector.album.getRecords();
-await client.app.bsky.actor.profile.getRecord({ uri });
-```
+Create a slice using the Slices CLI or web interface:
 
-## Authentication
+- Name: "Vintage Vinyl Collectors"
+- Domain: "com.recordcollector"
 
-OAuth 2.0 with PKCE for secure authentication.
+### Step 2: Define Lexicons
 
-### OAuth Flow
+Upload your lexicon definitions through the web UI or CLI:
 
-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
+- Album schema (`com.recordcollector.album`)
+- Review schema (`com.recordcollector.review`)
+- Wishlist schema (`com.recordcollector.wishlist`)
 
-### Session Management
+### Step 3: Sync Existing Data
 
-- Encrypted cookies for web sessions
-- Token refresh before expiration
-- Graceful degradation for read-only access
+Start a sync job to import your existing collection:
 
-## Blob Handling
+- Use the Sync tab in the web UI
+- Select collections to sync
+- Specify repositories (or leave empty for all)
 
-Media files use blob references with CDN URLs.
+### Step 4: Build Your App
 
-### Blob Structure
+```javascript
+// Use the generated SDK
+const client = new AtprotoClient(slice.uri);
 
-```json Code
-{
-  "$type": "blob",
-  "ref": { "$link": "bafkreig5bcb..." },
-  "mimeType": "image/jpeg",
-  "size": 127198
-}
-```
-
-### CDN URL Generation
-
-Convert blob references to CDN URLs using Bluesky's CDN:
+// List all jazz albums in mint condition
+const jazzMint = await client.com.recordcollector.album.getRecords({
+  where: {
+    genre: { contains: "jazz" },
+    condition: { eq: "Mint" },
+  },
+});
 
-```typescript Code
-recordBlobToCdnUrl(record, blobRef, "avatar");
-// -> https://cdn.bsky.app/img/avatar/plain/did:plc:abc/bafkrei...@jpeg
+// Add a new album to the collection
+await client.com.recordcollector.album.createRecord({
+  title: "A Love Supreme",
+  artist: "John Coltrane",
+  releaseDate: "1965-02-01T00:00:00Z",
+  genre: ["jazz", "spiritual jazz"],
+  condition: "Near Mint",
+});
 ```
 
-### Bluesky CDN Presets
+## Summary
 
-- `avatar` - Profile pictures
-- `banner` - Cover images
-- `feed_thumbnail` - Small previews
-- `feed_fullsize` - Full resolution
+| Concept      | Purpose                         | Record Collector Example                                    |
+| ------------ | ------------------------------- | ----------------------------------------------------------- |
+| **Slices**   | Isolated data container         | `com.recordcollector` namespace with all your vinyl data    |
+| **Lexicons** | Schema definitions              | `album`, `review`, `wishlist` record types                  |
+| **Sync**     | Data import & real-time updates | Import collections from network, live updates via Jetstream |
+| **Code Gen** | Auto-generated APIs & SDKs      | TypeScript client with `getRecords`, `createRecord`, etc.   |
 
 ## 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
+- [Getting Started](./getting-started.md): Create your first slice
+- [API Reference](./api-reference.md): Detailed endpoint documentation
+- [SDK Usage](./sdk-usage.md): Advanced SDK patterns

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
+# Getting Started
 
-This guide will help you set up Slices and create your first slice.
+Build your first AT Protocol app in minutes with the Slices CLI.
 
-## Creating Your First Slice
+## Quick Start
 
-### 1. Log In
+### Install the CLI
 
-Click "Login" and authenticate with your AT Protocol account.
+You'll need Deno installed first. Get it at [deno.com](https://deno.com/).
 
-### 2. Create a Slice
+```bash
+# Install from JSR
+deno install -g jsr:@slices/cli --name slices
+```
 
-Click "Create Slice" and provide:
+### Create Your Project
 
-- **Name**: A friendly name for your slice
-- **Domain**: Your namespace (e.g., `com.recordcollector`)
+```bash
+# Create a new project with automatic setup
+slices init my-vinyl-app
 
-### 3. Define a Lexicon
+# Or let us generate a name/domain for you
+slices init
+```
 
-Navigate to your slice and go to the Lexicon tab. Create a lexicon for your
-first record type:
+The `slices init` command does everything for you:
 
-```json Code
+- Creates a full-stack Deno app with OAuth authentication
+- Automatically creates a slice on the network
+- Sets up OAuth credentials
+- Pulls standard lexicons (including Bluesky profiles)
+- Generates a TypeScript SDK
+- Initializes a git repository
+
+### Start Developing
+
+```bash
+cd my-vinyl-app
+deno task dev
+```
+
+Visit http://localhost:8080 and you're live!
+
+## What You Get
+
+The `slices init` command creates a production-ready app with:
+
+> More templates/examples coming soon (i.e. React, Expo, Astro, etc)
+
+### Full-Stack Deno Application
+
+- **Server-side rendering** with Preact and JSX
+- **OAuth authentication** with PKCE flow and automatic token refresh
+- **HTMX integration** for dynamic UI without complex JavaScript
+- **Tailwind CSS** for beautiful, responsive styling
+- **SQLite sessions** for secure session management
+- **Feature-based architecture** for scalable code organization
+
+### AT Protocol Integration
+
+- **Configured slice** with your own namespace
+- **Generated TypeScript SDK** from your lexicons
+- **Automatic sync** capabilities
+- **Real-time updates** via Jetstream
+
+### Development Experience
+
+- **Hot reload** in development
+- **Type safety** throughout
+- **Environment variables** pre-configured
+- **Git repository** initialized
+
+## Project Structure
+
+Here's what the generated project structure looks like:
+
+```
+my-vinyl-app/
+├── slices.json              # Slice configuration
+├── .env                     # Your credentials (auto-generated)
+├── deno.json               # Deno configuration
+├── lexicons/               # AT Protocol schemas
+│   ├── com/
+│   │   └── recordcollector/
+│   │       └── album.json
+│   └── app/
+│       └── bsky/
+│           └── actor/
+│               └── profile.json
+└── src/
+    ├── main.ts             # Server entry point
+    ├── config.ts           # App configuration
+    ├── generated_client.ts # Your TypeScript SDK
+    ├── routes/            # HTTP routes
+    ├── features/          # Feature modules
+    │   ├── auth/         # OAuth implementation
+    │   └── dashboard/    # Main app UI
+    ├── shared/           # Reusable components
+    └── utils/           # Helper functions
+```
+
+## CLI Commands
+
+The Slices CLI is your command center:
+
+### Project Management
+
+```bash
+# Create a new project
+slices init my-app
+
+# Check your authentication status
+slices status
+
+# Authenticate with Slices network
+slices login
+```
+
+### Lexicon Management
+
+```bash
+# Pull lexicons from your slice
+slices lexicon pull
+
+# Push local lexicons to your slice
+slices lexicon push
+
+# List lexicons in your slice
+slices lexicon list
+```
+
+### Code Generation
+
+```bash
+# Generate TypeScript SDK from lexicons
+slices codegen
+
+# The SDK is created at src/generated_client.ts
+```
+
+### Monitoring
+
+```bash
+# View real-time Jetstream logs
+slices logs
+
+# See sync activity and data flow
+slices logs --verbose
+```
+
+## Working with Lexicons
+
+Lexicons define your data structure. The init command includes Bluesky profile
+lexicons to get you started, but you'll want to add your own custom lexicons for
+your app.
+
+### Modify an Existing Lexicon
+
+Edit `lexicons/com/recordcollector/album.json`:
+
+```json
 {
   "lexicon": 1,
   "id": "com.recordcollector.album",
   "defs": {
     "main": {
       "type": "record",
-      "description": "A vinyl album record",
+      "description": "A vinyl album in my collection",
       "record": {
         "type": "object",
+        "required": ["title", "artist", "releaseDate"],
         "properties": {
-          "title": {
-            "type": "string",
-            "description": "Album title"
-          },
-          "artist": {
-            "type": "string",
-            "description": "Artist or band name"
-          },
+          "title": { "type": "string" },
+          "artist": { "type": "string" },
           "releaseDate": {
             "type": "string",
-            "format": "datetime",
-            "description": "Original release date"
+            "format": "datetime"
           },
           "genre": {
             "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Music genres"
+            "items": { "type": "string" }
           },
           "condition": {
             "type": "string",
-            "description": "Vinyl condition (Mint, Near Mint, Very Good, etc.)"
+            "enum": [
+              "Mint",
+              "Near Mint",
+              "Very Good Plus",
+              "Very Good",
+              "Good",
+              "Fair",
+              "Poor"
+            ]
           },
-          "notes": {
+          "notes": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+### Create a New Lexicon
+
+Create `lexicons/com/recordcollector/review.json`:
+
+```json
+{
+  "lexicon": 1,
+  "id": "com.recordcollector.review",
+  "defs": {
+    "main": {
+      "type": "record",
+      "description": "Album review",
+      "record": {
+        "type": "object",
+        "required": ["albumUri", "rating", "content"],
+        "properties": {
+          "albumUri": {
             "type": "string",
-            "description": "Collector notes"
+            "format": "at-uri"
+          },
+          "rating": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 5
+          },
+          "content": { "type": "string" },
+          "createdAt": {
+            "type": "string",
+            "format": "datetime"
           }
-        },
-        "required": ["title", "artist", "releaseDate"]
+        }
       }
     }
   }
 }
 ```
 
-### 4. Generate TypeScript Client
+### Update Your Slice
 
-Navigate to the Code Generation tab and click "Generate TypeScript Client". This
-creates a type-safe client library for your slice.
+After modifying lexicons:
 
-### 5. Use the Generated Client
+```bash
+# Push changes to your slice
+slices lexicon push
 
-In your application:
+# Regenerate the TypeScript SDK
+slices codegen
+```
 
-```typescript Code
-import { AtProtoClient } from "./generated-client.ts";
+Your SDK at `src/generated_client.ts` now includes the new types and methods!
 
-const client = new AtProtoClient(
-  "http://localhost:3000",
-  "at://did:plc:your-did/network.slices.slice/your-slice-id",
-);
+**Important:** You must push your lexicons to the slice before you can create
+records. The slice needs to know about your schema in order to validate and
+store records.
 
-// Get albums
-const albums = await client.com.recordcollector.album.getRecords();
+## Using the Generated SDK
+
+The generated SDK provides a type-safe client for your slice:
 
-// Add a new album to your collection
+```typescript
+import { AtprotoClient } from "./generated_client.ts";
+
+// Initialize the client
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: Deno.env.get("SLICE_URI")!,
+});
+
+// List albums with filtering and sorting
+const albums = await client.com.recordcollector.album.getRecords({
+  where: {
+    genre: { contains: "jazz" },
+  },
+  sortBy: [{ field: "releaseDate", direction: "desc" }],
+  limit: 20,
+});
+
+// Add a new album
 const newAlbum = await client.com.recordcollector.album.createRecord({
-  title: "Nevermind",
-  artist: "Nirvana",
-  releaseDate: "1991-09-24",
-  genre: ["grunge", "alternative rock"],
+  title: "Kind of Blue",
+  artist: "Miles Davis",
+  releaseDate: "1959-08-17T00:00:00Z",
+  genre: ["jazz", "modal jazz"],
   condition: "Near Mint",
-  notes: "Original pressing, includes poster",
+  notes: "Original Columbia pressing",
 });
 
 // Get a specific album
 const album = await client.com.recordcollector.album.getRecord({
   uri: newAlbum.uri,
+});
+
+// Update an album
+await client.com.recordcollector.album.updateRecord({
+  uri: album.uri,
+  record: {
+    ...album.value,
+    notes: "Verified as first pressing!",
+  },
+});
+
+// Delete an album
+await client.com.recordcollector.album.deleteRecord({
+  uri: album.uri,
 });
 ```
 
-## Syncing External Data
+### External Collections
 
-To import data from other AT Protocol repositories:
+Since the init command included Bluesky profile lexicons, your SDK has methods
+for querying them:
 
-### 1. Navigate to Sync
+```typescript
+// Query users by display name (from included Bluesky lexicons)
+const profiles = await client.app.bsky.actor.profile.getRecords({
+  where: {
+    displayName: { contains: "vinyl collector" },
+  },
+});
+```
 
-Go to your slice and click the Sync tab.
+Any record-type lexicon you add to your slice will generate corresponding SDK
+methods when you run `slices codegen`.
 
-### 2. Configure Sync
+## Syncing Data
 
-Choose collections to sync:
+Once your app is running, you can sync data from the AT Protocol network.
 
-- **Primary Collections**: Your slice's lexicons
-- **External Collections**: Bluesky or other AT Protocol collections
+### User Authentication Sync
 
-### 3. Start Sync
+When users log in via OAuth, you can sync their data using the
+`syncUserCollections` method. This discovers and imports their external
+collections (like Bluesky profiles and posts).
 
-Specify repositories (DIDs) to sync from, or leave empty to sync all available
-data.
+```typescript
+// After user logs in
+await client.network.slices.slice.syncUserCollections();
+```
 
-### 4. Monitor Progress
+### Manual Bulk Sync
 
-The sync will run in the background. Check the status in the UI or via API.
+Use the web interface at https://slices.network to start a bulk sync job.
+Navigate to your slice's Sync tab to configure which collections and
+repositories to sync.
+
+**Note:** If you created new lexicons, you'll be the only one with records
+initially. As more users adopt your app and write records to their own PDSs, you
+can sync from their repositories to grow your network.
+
+### Real-time Updates
+
+Jetstream automatically tracks creates, updates, and deletes across the network:
+
+```bash
+# Monitor real-time sync
+slices logs --slice $SLICE_URI
+```
+
+## Deployment
+
+Your app is ready for production deployment.
+
+### Deno Deploy
+
+Create a free account at [deno.com/deploy](https://deno.com/deploy). Push your code to GitHub, then connect your repository through the Deno Deploy dashboard to deploy your app.
+
+For production use with Deno Deploy, switch from SQLite to Deno KV for OAuth and session storage:
+
+```typescript
+import { DenoKVOAuthStorage } from "@slices/oauth";
+import { DenoKVAdapter } from "@slices/session";
+
+// Configure OAuth with Deno KV storage
+const oauthClient = new OAuthClient({
+  clientId: Deno.env.get("OAUTH_CLIENT_ID")!,
+  clientSecret: Deno.env.get("OAUTH_CLIENT_SECRET")!,
+  authBaseUrl: Deno.env.get("OAUTH_AIP_BASE_URL")!,
+  redirectUri: Deno.env.get("OAUTH_REDIRECT_URI")!,
+  storage: new DenoKVOAuthStorage(), // Uses Deno KV
+});
+
+// Configure sessions with Deno KV adapter
+const sessionStore = new SessionStore({
+  adapter: new DenoKVAdapter(), // Uses Deno KV
+  cookieOptions: {
+    secure: true,
+    httpOnly: true,
+  },
+});
+```
+
+Deno KV provides serverless-compatible storage that scales automatically with your deployment.
+
+## Manual Setup (Advanced)
+
+If you prefer to set things up manually or need custom configuration:
+
+### 1. Create a Slice via Web UI
+
+Visit https://slices.network and:
+
+1. Log in with your AT Protocol account
+2. Click "Create Slice"
+3. Choose your namespace (e.g., `com.recordcollector`)
+
+### 2. Create OAuth Credentials
+
+In your slice dashboard:
+
+1. Go to Settings → OAuth Clients
+2. Create a new client
+3. Set redirect URI: `http://localhost:8080/oauth/callback`
+4. Copy the Client ID and Secret
+
+### 3. Set Up Your Project
+
+Use any framework you prefer. You can use the generated TypeScript SDK (works
+with any JavaScript/TypeScript environment) or call the XRPC endpoints directly
+from any language:
+
+```bash
+# Configure environment
+cp .env.example .env
+# Edit .env with your credentials
+
+# Start your project
+# (commands depend on your framework choice)
+```
 
 ## 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
+- [Core Concepts](./concepts.md): Understand slices, lexicons, sync, and code
+  generation
+- [API Reference](./api-reference.md): Detailed endpoint documentation
+- [SDK Usage](./sdk-usage.md): Advanced SDK patterns and examples
+- [Examples](./examples/): Sample applications and use cases
+
+## Need Help?
+
+- Join our [Discord community](https://discord.gg/slices)
+- Check out [example apps](https://github.com/slices/examples)
+- Read the [AT Protocol docs](https://atproto.com/)
+- Report issues on [Tangled](https://tangled.sh/slices.network/slices/issues)

docs/intro.md

···
-# Introduction to Slices
+# Introduction
 
-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.
+Slices is an open source platform for building structured data applications on
+the AT Protocol network.
 
-## What is a Slice?
+## What is Slices?
 
-A slice is a custom appview within the AT Protocol ecosystem. Each slice:
+Slices lets you define custom data schemas and build applications that store,
+query, and sync structured records across the decentralized AT Protocol network.
+Think of it as a schema-first backend that automatically handles data
+validation, indexing, and cross-network synchronization.
 
-- 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
+## How Slices Works on AT Protocol
 
-## Why Slices?
+```mermaid
+flowchart LR
+    Users[Users<br/>Create/Update Records] --> PDS[PDS Nodes<br/>Store user data]
+    PDS --> Firehose[Firehose<br/>Stream of all events]
+    Firehose --> SlicesNetwork[Slices Network - AppView<br/>• Monitors all AT Protocol data<br/>• Routes to relevant slices]
+    SlicesNetwork --> SliceA[Slice A<br/>• Blog lexicons<br/>• Post records<br/>• Comment queries]
+    SlicesNetwork --> SliceB[Slice B<br/>• Music lexicons<br/>• Album records<br/>• Playlist queries]
+    SliceA --> ClientA[Application<br/>Client<br/>• Read/write data]
+    SliceB --> ClientB[Application<br/>Client<br/>• Read/write data]
+```
 
-Building AT Protocol applications typically requires:
+**Flow:**
 
-- 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
+1. Users create records on their Personal Data Server (PDS)
+2. The Firehose streams all network events in real-time
+3. The Slices Network monitors the firehose and routes data to relevant slices
+4. Each slice indexes only records matching its specific lexicons
+5. Application clients connect to specific slices to read/write data
 
-Slices provides all of this infrastructure out of the box, letting you focus on
-your application logic.
+## Quick Start
 
-## Key Features
+Get started in under a minute:
 
-### Dynamic API Generation
+```bash
+# Install the CLI globally
+deno install -g jsr:@slices/cli --name slices
 
-Define a lexicon, and Slices automatically creates REST endpoints for:
+# Initialize a new slice project
+slices init my-app
 
-- 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
+# Start developing
+cd my-app
+deno task dev
+```
 
-### Data Synchronization
+The `slices init` command creates a full-stack Deno app with OAuth authentication, automatically creates your slice on the network, and generates a type-safe TypeScript SDK.
 
-Sync AT Protocol data into your slice:
+## Simple Example
 
-- 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)
+Define a schema for vinyl albums:
 
-### Type-Safe SDK Generation
+```json lexicons/com/recordcollector/album.json
+{
+  "lexicon": 1,
+  "id": "com.recordcollector.album",
+  "defs": {
+    "main": {
+      "type": "record",
+      "record": {
+        "type": "object",
+        "required": ["title", "artist", "releaseDate"],
+        "properties": {
+          "title": { "type": "string" },
+          "artist": { "type": "string" },
+          "releaseDate": { "type": "string", "format": "datetime" },
+          "genre": { "type": "array", "items": { "type": "string" } },
+          "condition": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
 
-Automatically generate TypeScript clients with:
+Push your lexicon and regenerate the SDK:
 
-- Full type safety for all record types
-- OAuth authentication integration
-- Nested API structure matching your lexicons
-- Blob/CDN URL utilities for media handling
+```bash
+# Push your lexicon to the slice
+slices lexicon push
+
+# Regenerate TypeScript SDK
+slices codegen
+```
 
-### Multi-Tenant Architecture
+Use the auto-generated, type-safe client:
 
-Each slice operates independently:
+```typescript
+import { AtprotoClient } from "./generated_client.ts";
 
-- Isolated data storage
-- Custom lexicon definitions
-- Separate sync configurations
-- Per-slice statistics and analytics
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: "at://your-slice-uri",
+});
 
-## Use Cases
+// Get all grunge albums
+const albums = await client.com.recordcollector.album.getRecords({
+  where: { genre: { contains: "grunge" } },
+  sortBy: [{ field: "releaseDate", direction: "desc" }],
+});
+```
 
-- **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
+## Key Features
 
-## Architecture Overview
+- **Schema Validation**: Define lexicons that enforce data structure and constraints
+- **Auto-generated APIs**: REST endpoints created automatically from your schemas
+- **TypeScript SDKs**: Type-safe clients generated from your lexicons
+- **Real-time Sync**: Automatic synchronization across the AT Protocol network
+- **Advanced Querying**: Filter, sort, and paginate records with a powerful query API
+- **OAuth Built-in**: Authentication with any AT Protocol account
 
-Slices consists of two main components:
+## When to Use Slices
 
-- **API Server** (Rust): Handles AT Protocol integration, database operations,
-  and API endpoints
-- **Frontend** (Deno): Provides web UI for slice management and user
-  authentication
+Slices is ideal for:
 
-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.
+- **Social Applications**: Build specialized communities, forums, or social features
+- **Content Platforms**: Create blogs, documentation sites, or media libraries
+- **SaaS Products**: Develop collaborative tools with structured data needs
+- **Web APIs**: Design REST APIs with automatic validation and documentation
+- **Decentralized Apps**: Build on AT Protocol without managing infrastructure
 
 ## 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
+- [Core Concepts](./concepts.md) - Understand lexicons and collections
+- [API Reference](./api-reference.md) - Explore the full API

docs/introduction.md

···
-# Introduction
-
-Slices is an open source platform for building structured data applications on
-the AT Protocol network.
-
-## What is Slices?
-
-Slices lets you define custom data schemas and build applications that store,
-query, and sync structured records across the decentralized AT Protocol network.
-Think of it as a schema-first backend that automatically handles data
-validation, indexing, and cross-network synchronization.
-
-## How Slices Works on AT Protocol
-
-```mermaid
-flowchart LR
-    Users[Users<br/>Create/Update Records] --> PDS[PDS Nodes<br/>Store user data]
-    PDS --> Firehose[Firehose<br/>Stream of all events]
-    Firehose --> SlicesNetwork[Slices Network - AppView<br/>• Monitors all AT Protocol data<br/>• Routes to relevant slices]
-    SlicesNetwork --> SliceA[Slice A<br/>• Blog lexicons<br/>• Post records<br/>• Comment queries]
-    SlicesNetwork --> SliceB[Slice B<br/>• Music lexicons<br/>• Album records<br/>• Playlist queries]
-    SliceA --> ClientA[Application<br/>Client<br/>• Read/write data]
-    SliceB --> ClientB[Application<br/>Client<br/>• Read/write data]
-```
-
-**Flow:**
-
-1. Users create records on their Personal Data Server (PDS)
-2. The Firehose streams all network events in real-time
-3. The Slices Network monitors the firehose and routes data to relevant slices
-4. Each slice indexes only records matching its specific lexicons
-5. Application clients connect to specific slices to read/write data
-
-## Quick Start
-
-Get started in under a minute:
-
-```bash
-# Initialize a new slice project
-deno run -A jsr:@slices/cli init
-
-# Follow the prompts to:
-# 1. Name your slice
-# 2. Define your first lexicon
-# 3. Deploy to the network
-```
-
-## Simple Example
-
-Define a schema for a blog post:
-
-```json lexicons/com/myblog/post.json
-{
-  "lexicon": 1,
-  "id": "com.myblog.post",
-  "defs": {
-    "main": {
-      "type": "record",
-      "record": {
-        "type": "object",
-        "required": ["title", "content", "createdAt"],
-        "properties": {
-          "title": { "type": "string", "maxLength": 200 },
-          "content": { "type": "string", "maxLength": 10000 },
-          "tags": { "type": "array", "items": { "type": "string" } },
-          "createdAt": { "type": "string", "format": "datetime" }
-        }
-      }
-    }
-  }
-}
-```
-
-Deploy your lexicon and generate the TypeScript client:
-
-```bash
-# Push your lexicon to the slice
-deno run -A jsr:@slices/cli lexicon push
-
-# Generate TypeScript SDK from your lexicons
-deno run -A jsr:@slices/cli codegen
-```
-
-Query your data using the auto-generated API:
-
-```typescript
-// Get all posts with a specific tag
-const posts = await client.com.myblog.post.getRecords({
-  slice: "at://your-slice-uri",
-  where: { tags: { contains: "javascript" } },
-  sortBy: [{ field: "createdAt", direction: "desc" }],
-});
-```
-
-## Key Features
-
-- **Schema Validation**: Define lexicons that enforce data structure and constraints
-- **Auto-generated APIs**: REST endpoints created automatically from your schemas
-- **TypeScript SDKs**: Type-safe clients generated from your lexicons
-- **Real-time Sync**: Automatic synchronization across the AT Protocol network
-- **Advanced Querying**: Filter, sort, and paginate records with a powerful query API
-- **OAuth Built-in**: Authentication with any AT Protocol account
-
-## When to Use Slices
-
-Slices is ideal for:
-
-- **Social Applications**: Build specialized communities, forums, or social features
-- **Content Platforms**: Create blogs, documentation sites, or media libraries
-- **SaaS Products**: Develop collaborative tools with structured data needs
-- **Web APIs**: Design REST APIs with automatic validation and documentation
-- **Decentralized Apps**: Build on AT Protocol without managing infrastructure
-
-## Next Steps
-
-- [Getting Started](./getting-started.md) - Set up your first slice
-- [Core Concepts](./concepts.md) - Understand lexicons and collections
-- [API Reference](./api-reference.md) - Explore the full API

docs/sdk-usage.md

···
 After generating your TypeScript client, you can use it directly in your
 project:
 
-```typescript Code
-import { AtProtoClient } from "./generated_client.ts";
+```typescript
+import { AtprotoClient } from "./generated_client.ts";
 import { OAuthClient } from "@slices/oauth";
 ```
 
···
 
 ### Without Authentication (Read-Only)
 
-```typescript Code
-const client = new AtProtoClient(
-  "https://api.your-domain.com",
-  "at://did:plc:abc/network.slices.slice/your-slice-rkey",
-);
+```typescript
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: "at://did:plc:abc/network.slices.slice/your-slice-rkey",
+});
 
 // Read operations work without auth
 const albums = await client.com.recordcollector.album.getRecords();
···
 
 ### With Authentication (Full Access)
 
-```typescript Code
+```typescript
 import { OAuthClient } from "@slices/oauth";
 
 // Set up OAuth client
···
 });
 
 // Initialize API client with OAuth
-const client = new AtProtoClient(
-  "https://api.your-domain.com",
-  "at://did:plc:abc/network.slices.slice/your-slice-rekey",
-  oauthClient,
-);
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: "at://did:plc:abc/network.slices.slice/your-slice-rkey",
+  auth: oauthClient,
+});
 ```
 
 ## CRUD Operations
···
 
 The SDK uses `getRecords` for retrieving records:
 
-```typescript Code
+```typescript
 // Get all vinyl records
 const albums = await client.com.recordcollector.album.getRecords();
 
···
 The `countRecords` method allows you to count records without fetching them,
 using the same filtering parameters as `getRecords`:
 
-```typescript Code
+```typescript
 // Count all records
 const total = await client.com.recordcollector.album.countRecords();
 console.log(`Total albums: ${total.count}`);
···
 
 ### Getting a Single Record
 
-```typescript Code
+```typescript
 const album = await client.com.recordcollector.album.getRecord({
   uri: "at://did:plc:abc/com.recordcollector.album/3jklmno456",
 });
···
 
 ### Creating Records
 
-```typescript Code
+```typescript
 // Create with auto-generated key
 const newAlbum = await client.com.recordcollector.album.createRecord({
   title: "In Utero",
···
 
 ### Updating Records
 
-```typescript Code
+```typescript
 // Get the record key from the URI
 const uri = "at://did:plc:abc/com.recordcollector.album/3jklmno456";
 const rkey = uri.split("/").pop(); // '3jklmno456'
···
 
 ### Deleting Records
 
-```typescript Code
+```typescript
 const rkey = "3jklmno456";
 await client.com.recordcollector.album.deleteRecord(rkey);
 ```
···
 
 Access synced external collections like Bluesky profiles:
 
-```typescript Code
+```typescript
 // Get Bluesky profiles in your slice
 const profiles = await client.app.bsky.actor.profile.getRecords();
 
···
 
 ### Uploading Blobs
 
-```typescript Code
+```typescript
 // Read file as ArrayBuffer
 const file = await Deno.readFile("./nevermind-cover.jpg");
 
···
 
 ### Converting Blobs to CDN URLs
 
-```typescript Code
+```typescript
 import { recordBlobToCdnUrl } from "./generated-client.ts";
 
 // Get a record with a blob
···
 
 ## Slice Operations
 
-### Get Slice Statistics
-
-```typescript Code
-const stats = await client.network.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`);
-});
-```
-
 ### Get Actors
 
 The `getActors` method retrieves actors (users) within a slice with powerful
 filtering and sorting capabilities:
 
-```typescript Code
+```typescript
 // Get all actors in the slice
-const actors = await client.network.slices.slice.getActors();
+const actors = await client.getActors();
 
 // With pagination
-const page1 = await client.network.slices.slice.getActors({
+const page1 = await client.getActors({
   limit: 20,
 });
-const page2 = await client.network.slices.slice.getActors({
+const page2 = await client.getActors({
   limit: 20,
   cursor: page1.cursor,
 });
 
 // Filter by specific DIDs
-const specificActors = await client.network.slices.slice.getActors({
+const specificActors = await client.getActors({
   where: {
     did: { in: ["did:plc:user1", "did:plc:user2"] },
   },
 });
 
 // Search by handle
-const searchByHandle = await client.network.slices.slice.getActors({
+const searchByHandle = await client.getActors({
   where: {
     handle: { contains: "alice" },
   },
 });
 
 // Filter by exact handle
-const exactHandle = await client.network.slices.slice.getActors({
+const exactHandle = await client.getActors({
   where: {
     handle: { eq: "user.bsky.social" },
   },
···
 
 ### Browse Slice Records
 
-#### Get Records from Multiple Collections
-
-The `getSliceRecords` method uses the same `where` clause approach:
+The `getSliceRecords` method retrieves records across multiple collections:
 
-```typescript Code
+```typescript
 // Get records from specific collections
-const records = await client.network.slices.slice.getSliceRecords({
+const records = await client.getSliceRecords({
   where: {
-    collection: { eq: "com.example.post" },
+    collection: { eq: "com.recordcollector.album" },
     did: { eq: "did:plc:specific-author" }, // optional
   },
   limit: 50,
···
 });
 
 // Search across collections using specific fields
-const searchResults = await client.network.slices.slice.getSliceRecords({
+const searchResults = await client.getSliceRecords({
   where: {
-    collection: { eq: "com.example.post" },
-    title: { contains: "hello world" },
+    collection: { eq: "com.recordcollector.album" },
+    title: { contains: "nevermind" },
     did: { eq: "did:plc:specific-author" }, // optional
   },
   limit: 50,
 });
 
 // Global search across ALL fields in records
-const globalSearchResults = await client.network.slices.slice.getSliceRecords({
+const globalSearchResults = await client.getSliceRecords({
   where: {
-    collection: { eq: "com.example.post" },
-    json: { contains: "hello world" }, // Searches entire record content
+    collection: { eq: "com.recordcollector.album" },
+    json: { contains: "grunge" }, // Searches entire record content
     did: { eq: "did:plc:specific-author" }, // optional
   },
   limit: 50,
···
 });
 
 // Get records from any collection with global text search
-const allCollectionSearch = await client.network.slices.slice.getSliceRecords({
+const allCollectionSearch = await client.getSliceRecords({
   where: {
-    json: { contains: "important content" }, // Searches ALL fields in ALL collections
+    json: { contains: "seattle" }, // Searches ALL fields in ALL collections
   },
   limit: 20,
 });
···
 
 Search within specific fields of your records:
 
-```typescript Code
+```typescript
 // Search in title field only
 const titleSearch = await client.com.recordcollector.album.getRecords({
   where: {
···
 
 Use the special `json` field to search across **all fields** in a record:
 
-```typescript Code
+```typescript
 // Finds records containing "grunge" anywhere in their data
 const globalSearch = await client.com.recordcollector.album.getRecords({
   where: {
···
 
 When using `getSliceRecords`, you can search across multiple collections:
 
-```typescript Code
+```typescript
 // Search for "seattle" across all collections
-const crossCollectionSearch = await client.network.slices.slice.getSliceRecords(
-  {
-    where: {
-      json: { contains: "seattle" },
-    },
+const crossCollectionSearch = await client.getSliceRecords({
+  where: {
+    json: { contains: "seattle" },
   },
-);
+});
 
 // Limit to specific collections
-const specificSearch = await client.network.slices.slice.getSliceRecords({
+const specificSearch = await client.getSliceRecords({
   where: {
     collection: {
       in: ["com.recordcollector.album", "com.recordcollector.review"],
···
 using the separate `orWhere` parameter. This provides clean type safety and
 autocomplete for field names:
 
-```typescript Code
+```typescript
 // Find albums by either Nirvana OR Alice in Chains
 const albums = await client.com.recordcollector.album.getRecords({
   orWhere: {
···
 // SQL: WHERE release_date = '1991-09-24' AND (artist LIKE '%nirvana%' OR genre LIKE '%grunge%')
 
 // OR queries work with cross-collection searches too
-const crossCollectionOrSearch = await client.network.slices.slice
-  .getSliceRecords({
-    where: {
-      collection: { eq: "com.recordcollector.album" },
-    },
-    orWhere: {
-      artist: { contains: "pearl jam" },
-      genre: { contains: "alternative rock" },
-    },
-  });
+const crossCollectionOrSearch = await client.getSliceRecords({
+  where: {
+    collection: { eq: "com.recordcollector.album" },
+  },
+  orWhere: {
+    artist: { contains: "pearl jam" },
+    genre: { contains: "alternative rock" },
+  },
+});
 
 // You get full autocomplete and type safety for field names in both where and orWhere
 const typedSearch = await client.com.recordcollector.album.getRecords({
···
 
 ### Sync User Collections
 
-```typescript Code
+```typescript
 // Sync current user's data (requires auth)
-const syncResult = await client.network.slices.slice.syncUserCollections({
-  timeoutSeconds: 30,
-});
+const syncResult = await client.syncUserCollections();
 
 console.log(`Synced ${syncResult.recordsSynced} records`);
 ```
 
 ## Error Handling
 
-```typescript Code
+```typescript
 try {
   const post = await client.com.example.post.getRecord({
     uri: "at://invalid-uri",
···
 
 ### 1. Initialize OAuth
 
-```typescript Code
+```typescript
 const oauthClient = new OAuthClient({
   clientId: process.env.OAUTH_CLIENT_ID,
   clientSecret: process.env.OAUTH_CLIENT_SECRET,
···
 
 ### 2. Start Authorization
 
-```typescript Code
+```typescript
 const authResult = await oauthClient.authorize({
   loginHint: "user.bsky.social",
 });
···
 
 ### 3. Handle Callback
 
-```typescript Code
+```typescript
 // In your callback handler
 const urlParams = new URLSearchParams(window.location.search);
 const code = urlParams.get("code");
···
 
 ### 4. Use Authenticated Client
 
-```typescript Code
-const client = new AtProtoClient(apiUrl, sliceUri, oauthClient);
+```typescript
+const client = new AtprotoClient({
+  baseUrl: "https://api.slices.network",
+  sliceUri: "at://did:plc:abc/network.slices.slice/your-slice-rkey",
+  auth: oauthClient,
+});
 
 // OAuth tokens are automatically managed
-const profile = await client.network.slices.actor.profile.createRecord({
-  displayName: "New User",
-  description: "My profile",
-}, true); // useSelfRkey for profile
+const album = await client.com.recordcollector.album.createRecord({
+  title: "Ten",
+  artist: "Pearl Jam",
+  releaseDate: "1991-08-27",
+  genre: ["grunge", "alternative rock"],
+  condition: "Mint",
+});
 ```
 
 ## Type Safety
 
 The generated SDK provides full TypeScript type safety:
 
-```typescript Code
+```typescript
 // TypeScript knows the shape of your records
 const album = await client.com.recordcollector.album.getRecord({ uri });
 
···
 
 ### Batch Operations
 
-```typescript Code
+```typescript
 // Process records in batches
+
 async function* getAllAlbums() {
   let cursor: string | undefined;
 

docs/self-hosting.md

···
 
 This guide covers how to set up and run your own Slices instance.
 
-## 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://tangled.sh/@slices.network/slices
-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/network.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.
+WIP - coming soon

frontend/src/features/docs/handlers.tsx

···
     category: "Getting Started",
     docs: [
       {
-        slug: "introduction",
+        slug: "intro",
         title: "Introduction",
         description: "Overview of Slices platform",
       },
···
   // Custom code block renderer - return content as-is since marked-highlight handles it
   renderer.code = function (token: Tokens.Code) {
     return token.text; // marked-highlight has already processed this
+  };
+
+  // Custom table renderer
+  renderer.table = function (token: Tokens.Table) {
+    const header = token.header
+      .map((cell: Tokens.TableCell, i: number) => {
+        const text = this.parser.parseInline(cell.tokens);
+        const align = token.align[i]
+          ? ` style="text-align: ${token.align[i]}"`
+          : "";
+        return `<th class="px-4 py-2 text-left text-sm font-semibold text-zinc-900 dark:text-white border-b-2 border-zinc-200 dark:border-zinc-700"${align}>${text}</th>`;
+      })
+      .join("");
+
+    const rows = token.rows
+      .map((row: Tokens.TableCell[]) => {
+        const cells = row
+          .map((cell: Tokens.TableCell, i: number) => {
+            const text = this.parser.parseInline(cell.tokens);
+            const align = token.align[i]
+              ? ` style="text-align: ${token.align[i]}"`
+              : "";
+            return `<td class="px-4 py-2 text-sm text-zinc-700 dark:text-zinc-300 border-b border-zinc-100 dark:border-zinc-800"${align}>${text}</td>`;
+          })
+          .join("");
+        return `<tr class="hover:bg-zinc-50 dark:hover:bg-zinc-800/50">${cells}</tr>`;
+      })
+      .join("");
+
+    return `<div class="overflow-x-auto my-6">
+      <table class="min-w-full divide-y divide-zinc-200 dark:divide-zinc-700">
+        <thead class="bg-zinc-50 dark:bg-zinc-800/50">
+          <tr>${header}</tr>
+        </thead>
+        <tbody class="bg-white dark:bg-zinc-900 divide-y divide-zinc-100 dark:divide-zinc-800">
+          ${rows}
+        </tbody>
+      </table>
+    </div>`;
   };
 
   // Set options and use the custom renderer