Rename

Author: isTravis

README.md

@@ -1,6 +1,6 @@
 # Underlay
 
-A versioned, content-addressed registry for knowledge corpora. Apps publish snapshots of their data to Underlay; Underlay preserves them, deduplicates files, and exposes them via a stable HTTPS API.
+A versioned, content-addressed registry for knowledge collections. Apps publish snapshots of their data to Underlay; Underlay preserves them, deduplicates files, and exposes them via a stable HTTPS API.
 
 **Underlay is the archive underneath your app.**
 
@@ -49,7 +49,7 @@ The seed creates an admin account you can log in with:
 - **Email:** admin@underlay.org
 - **Password:** admin
 
-It also creates a "Knowledge Futures" org with three sample corpora.
+It also creates a "Knowledge Futures" org with three sample collections.
 
 ## Architecture
 
@@ -70,7 +70,7 @@ src/
 │   ├── plugins/auth.ts   # Authentication (API keys + sessions)
 │   ├── routes/           # API route handlers
 │   │   ├── accounts.ts   # Signup, login, API key CRUD
-│   │   ├── corpora.ts    # Corpus CRUD
+│   │   ├── collections.ts    # Collection CRUD
 │   │   ├── versions.ts   # Version push/pull/diff
 │   │   ├── files.ts      # Content-addressed file storage
 │   │   └── health.ts     # Health check
@@ -88,19 +88,19 @@ src/
 │   └── s3.ts             # S3 client utilities
 ├── pages/
 │   ├── index.astro       # Landing page
-│   ├── explore.astro     # Browse public corpora
+│   ├── explore.astro     # Browse public collections
 │   ├── connect.astro     # Integration guide (for devs and LLMs)
 │   ├── login.astro       # Login form
 │   ├── signup.astro      # Signup form
-│   ├── dashboard.astro   # Authenticated user's corpora
+│   ├── dashboard.astro   # Authenticated user's collections
 │   ├── settings/         # Account settings + API key management
 │   ├── blog/             # Blog posts
 │   ├── docs/             # Documentation (concepts, quickstart, API ref, self-hosting)
 │   └── [owner]/          # Dynamic routes
 │       ├── index.astro           # /:owner — account profile
-│       └── [corpus]/
-│           ├── index.astro       # /:owner/:corpus — corpus overview
-│           └── v/[n].astro       # /:owner/:corpus/v/:n — version detail
+│       └── [collection]/
+│           ├── index.astro       # /:owner/:collection — collection overview
+│           └── v/[n].astro       # /:owner/:collection/v/:n — version detail
 ├── styles/
 │   └── global.css        # Tailwind theme (parchment/ink palette)
 tools/
@@ -124,33 +124,33 @@ All endpoints are under `/api`. Auth via `Authorization: Bearer <api_key>` for w
 | GET | `/api/accounts/keys` | List API keys |
 | DELETE | `/api/accounts/keys/:id` | Revoke API key |
 
-### Corpora
+### Collections
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/corpora` | Browse public corpora |
-| POST | `/api/accounts/:owner/corpora` | Create corpus |
-| GET | `/api/corpora/:owner/:slug` | Corpus metadata |
-| PATCH | `/api/corpora/:owner/:slug` | Update corpus |
-| DELETE | `/api/corpora/:owner/:slug` | Delete corpus |
-| GET | `/api/accounts/:owner/corpora` | List owner's corpora |
+| GET | `/api/collections` | Browse public collections |
+| POST | `/api/accounts/:owner/collections` | Create collection |
+| GET | `/api/collections/:owner/:slug` | Collection metadata |
+| PATCH | `/api/collections/:owner/:slug` | Update collection |
+| DELETE | `/api/collections/:owner/:slug` | Delete collection |
+| GET | `/api/accounts/:owner/collections` | List owner's collections |
 
 ### Versions
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| POST | `/api/corpora/:owner/:slug/versions` | Push a version |
-| GET | `/api/corpora/:owner/:slug/versions` | List versions |
-| GET | `/api/corpora/:owner/:slug/versions/latest` | Latest version |
-| GET | `/api/corpora/:owner/:slug/versions/:n` | Get version |
-| GET | `/api/corpora/:owner/:slug/versions/:n/records` | Get records |
-| GET | `/api/corpora/:owner/:slug/versions/:n/manifest` | Get manifest |
-| GET | `/api/corpora/:owner/:slug/versions/:n/diff` | Diff versions |
+| POST | `/api/collections/:owner/:slug/versions` | Push a version |
+| GET | `/api/collections/:owner/:slug/versions` | List versions |
+| GET | `/api/collections/:owner/:slug/versions/latest` | Latest version |
+| GET | `/api/collections/:owner/:slug/versions/:n` | Get version |
+| GET | `/api/collections/:owner/:slug/versions/:n/records` | Get records |
+| GET | `/api/collections/:owner/:slug/versions/:n/manifest` | Get manifest |
+| GET | `/api/collections/:owner/:slug/versions/:n/diff` | Diff versions |
 
 ### Files
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| HEAD | `/api/corpora/:owner/:slug/files/:hash` | Check existence |
-| GET | `/api/corpora/:owner/:slug/files/:hash` | Download |
-| PUT | `/api/corpora/:owner/:slug/files/:hash` | Upload |
+| HEAD | `/api/collections/:owner/:slug/files/:hash` | Check existence |
+| GET | `/api/collections/:owner/:slug/files/:hash` | Download |
+| PUT | `/api/collections/:owner/:slug/files/:hash` | Upload |
 
 ## Scripts
 

public/.well-known/ai.txt

@@ -23,15 +23,15 @@ There are two auth methods:
    POST /api/accounts/logout clears the session.
    GET /api/accounts/me returns the current user (works with either auth method).
 
-Public endpoints (browsing corpora, reading public versions) require no auth.
+Public endpoints (browsing collections, reading public versions) require no auth.
 Write endpoints require a key with "write" scope or an active session.
 Delete endpoints require "admin" scope.
 
 ---
 
 ## Core Concepts
 
-- Corpus: a named, versioned body of data owned by an account. Identified by :owner/:slug.
+- Collection: a named, versioned body of data owned by an account. Identified by :owner/:slug.
 - Version: an immutable snapshot containing a JSON Schema, records, and file references. Sequential integer numbers, auto-derived semver.
 - Record: a flat JSON object with { id, type, data }. Records reference other records by id and files by hash.
 - File: a binary blob stored by SHA-256 hash, referenced in record data as {"$file": "sha256:<hex>"}.
@@ -41,27 +41,27 @@ Delete endpoints require "admin" scope.
 
 ## Reading Data
 
-### Browse corpora
-GET /api/corpora                                    → list public corpora (?q=search&limit=50&offset=0)
-GET /api/corpora/:owner/:slug                       → corpus metadata + latest version summary
+### Browse collections
+GET /api/collections                                    → list public collections (?q=search&limit=50&offset=0)
+GET /api/collections/:owner/:slug                       → collection metadata + latest version summary
 
 ### Read versions
-GET /api/corpora/:owner/:slug/versions              → list versions (newest first, ?limit=50&offset=0)
-GET /api/corpora/:owner/:slug/versions/latest       → latest version with full metadata
-GET /api/corpora/:owner/:slug/versions/:n            → specific version by number
+GET /api/collections/:owner/:slug/versions              → list versions (newest first, ?limit=50&offset=0)
+GET /api/collections/:owner/:slug/versions/latest       → latest version with full metadata
+GET /api/collections/:owner/:slug/versions/:n            → specific version by number
 
 ### Read records and files
-GET /api/corpora/:owner/:slug/versions/:n/records   → records for a version (?type=TypeName&limit=100&offset=0)
-GET /api/corpora/:owner/:slug/versions/:n/manifest  → lightweight manifest: record ids/types + file hashes
-GET /api/corpora/:owner/:slug/files/:hash            → download a file by hash
-HEAD /api/corpora/:owner/:slug/files/:hash           → check if a file exists (returns Content-Length, Content-Type)
+GET /api/collections/:owner/:slug/versions/:n/records   → records for a version (?type=TypeName&limit=100&offset=0)
+GET /api/collections/:owner/:slug/versions/:n/manifest  → lightweight manifest: record ids/types + file hashes
+GET /api/collections/:owner/:slug/files/:hash            → download a file by hash
+HEAD /api/collections/:owner/:slug/files/:hash           → check if a file exists (returns Content-Length, Content-Type)
 
 ### Diff
-GET /api/corpora/:owner/:slug/versions/:n/diff?from=:m → diff between version m and n (added, updated, removed records)
+GET /api/collections/:owner/:slug/versions/:n/diff?from=:m → diff between version m and n (added, updated, removed records)
 
 ### Export
-GET /api/corpora/:owner/:slug/export                → download .tar.gz archive (manifest.json + records/*.ndjson + files/*)
-GET /api/corpora/:owner/:slug/export?version=3      → export a specific version
+GET /api/collections/:owner/:slug/export                → download .tar.gz archive (manifest.json + records/*.ndjson + files/*)
+GET /api/collections/:owner/:slug/export?version=3      → export a specific version
 
 ---
 
@@ -70,13 +70,13 @@ GET /api/corpora/:owner/:slug/export?version=3      → export a specific versio
 This is the canonical workflow for syncing an app's data to Underlay:
 
 ### Step 1: Get current state
-GET /api/corpora/:owner/:slug/versions/latest
+GET /api/collections/:owner/:slug/versions/latest
 
 Response includes { number, semver, hash, recordCount, fileCount }.
 If 404, no versions exist yet — your first push should use base_version: null.
 
 ### Step 2: Fetch the manifest (optional, for diffing)
-GET /api/corpora/:owner/:slug/versions/:n/manifest
+GET /api/collections/:owner/:slug/versions/:n/manifest
 
 Response:
 {
@@ -92,15 +92,15 @@ Compare this against your local data to determine what changed.
 ### Step 3: Upload new files (if any)
 For each file your app has that Underlay doesn't:
 
-PUT /api/corpora/:owner/:slug/files/sha256:<hex>
+PUT /api/collections/:owner/:slug/files/sha256:<hex>
 Content-Type: application/octet-stream
 Body: raw file bytes
 
 The server verifies the SHA-256 hash matches the body. Existing hashes are idempotent (200 OK).
 Check existence first with HEAD if you want to skip uploads.
 
 ### Step 4: Push the version
-POST /api/corpora/:owner/:slug/versions
+POST /api/collections/:owner/:slug/versions
 Content-Type: application/json
 Authorization: Bearer ul_<key>
 
@@ -173,7 +173,7 @@ Set base_version to null. Put all records in changes.added. Include the schema.
   }
 }
 
-- id: stable, unique within the corpus. Use your app's primary key or generate a deterministic one.
+- id: stable, unique within the collection. Use your app's primary key or generate a deterministic one.
 - type: groups records by kind (e.g. "Article", "Author", "Grant").
 - data: flat JSON object. Reference other records by id. Reference files with {"$file": "sha256:<hex>"}.
 
@@ -191,12 +191,12 @@ The schema declares which fields are references, so tools can resolve them at re
 
 ---
 
-## Corpus Management
+## Collection Management
 
-POST /api/accounts/:owner/corpora              → create corpus {"slug", "name", "description", "public"}
-PATCH /api/corpora/:owner/:slug                → update {"name", "description", "public"}
-DELETE /api/corpora/:owner/:slug               → delete corpus (requires admin scope)
-GET /api/accounts/:owner/corpora               → list corpora for an account
+POST /api/accounts/:owner/collections              → create collection {"slug", "name", "description", "public"}
+PATCH /api/collections/:owner/:slug                → update {"name", "description", "public"}
+DELETE /api/collections/:owner/:slug               → delete collection (requires admin scope)
+GET /api/accounts/:owner/collections               → list collections for an account
 
 ---
 
@@ -214,7 +214,7 @@ DELETE /api/accounts/keys/:id → revoke a key
 400 — Validation error (bad request body)
 401 — Authentication required
 403 — Insufficient scope (e.g. read key used for write)
-404 — Not found (or private corpus you can't access)
+404 — Not found (or private collection you can't access)
 409 — Version conflict (re-fetch and retry with new base_version)
 422 — Missing files (upload them first, then retry push)
 

src/api/plugins/auth.ts

@@ -8,7 +8,7 @@ declare module "fastify" {
   interface FastifyRequest {
     accountId?: string;
     apiKeyScope?: "read" | "write" | "admin";
-    apiKeyCorpusId?: string | null;
+    apiKeyCollectionId?: string | null;
     sessionUserId?: string;
   }
 }
@@ -17,7 +17,7 @@ async function authPlugin(app: FastifyInstance) {
   // API key auth via Bearer token
   app.decorateRequest("accountId", undefined);
   app.decorateRequest("apiKeyScope", undefined);
-  app.decorateRequest("apiKeyCorpusId", undefined);
+  app.decorateRequest("apiKeyCollectionId", undefined);
   app.decorateRequest("sessionUserId", undefined);
 
   app.addHook("onRequest", async (request: FastifyRequest) => {
@@ -30,7 +30,7 @@ async function authPlugin(app: FastifyInstance) {
         if (match) {
           request.accountId = key.accountId;
           request.apiKeyScope = key.scope as "read" | "write" | "admin";
-          request.apiKeyCorpusId = key.corpusId;
+          request.apiKeyCollectionId = key.collectionId;
           await db
             .update(schema.apiKeys)
             .set({ lastUsedAt: new Date() })