docs: describe the code that actually ships

astro.config.mjs

@@ -65,7 +65,7 @@ export default defineConfig({
               slug: 'modules/librarian',
             },
             {
-              label: 'KAPOW',
+              label: 'KAPOW!',
               slug: 'modules/kapow',
             },
             {

src/content/docs/contributing/getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: Getting Started Contributing
-description: How to contribute to the Coral ecosystem
+description: Set up a Coral repository locally, follow the shared tooling and commit conventions, and get a pull request merged.
 ---
 
 ## Contributing to Coral
@@ -23,12 +23,26 @@ That gives you the standard Coral app template with TypeScript, Biome, and relea
 
 Choose where you want to contribute:
 
-- **Aurora** - Video client ([github.com/Get-Coral/aurora](https://github.com/Get-Coral/aurora))
-- **Fathom** - Reading interface ([github.com/Get-Coral/fathom](https://github.com/Get-Coral/fathom))
-- **Librarian** - Library management ([github.com/Get-Coral/librarian](https://github.com/Get-Coral/librarian))
-- **KAPOW** - Karaoke manager ([github.com/Get-Coral/KAPOW](https://github.com/Get-Coral/KAPOW))
-- **Jellyfin Client** - API library ([github.com/Get-Coral/jellyfin](https://github.com/Get-Coral/jellyfin))
-- **Ecosystem** - Any module or library
+**Modules**
+
+- **Aurora** — video client ([Get-Coral/aurora](https://github.com/Get-Coral/aurora))
+- **Tide** — torrent client ([Get-Coral/tide](https://github.com/Get-Coral/tide))
+- **Librarian** — download imports and library hygiene ([Get-Coral/librarian](https://github.com/Get-Coral/librarian))
+- **Fathom** — reading interface ([Get-Coral/fathom](https://github.com/Get-Coral/fathom))
+- **Marquee** — ambient display ([Get-Coral/marquee](https://github.com/Get-Coral/marquee))
+- **KAPOW!** — karaoke queue ([Get-Coral/KAPOW](https://github.com/Get-Coral/KAPOW))
+- **Encore** — the module scaffold ([Get-Coral/encore](https://github.com/Get-Coral/encore))
+
+**Libraries and tooling**
+
+- **Jellyfin client** — typed API client ([Get-Coral/jellyfin](https://github.com/Get-Coral/jellyfin))
+- **Coral UI** — shared components ([Get-Coral/coral-ui](https://github.com/Get-Coral/coral-ui))
+- **create-coral** — the scaffolder ([Get-Coral/create-coral](https://github.com/Get-Coral/create-coral))
+- **template** — what create-coral clones ([Get-Coral/template](https://github.com/Get-Coral/template))
+- **dev-standards** — shared Biome and TypeScript configs ([Get-Coral/dev-standards](https://github.com/Get-Coral/dev-standards))
+
+If a module's page says *Early* or *Scaffold*, that is where help goes furthest.
+See [Introduction](/getting-started/introduction/) for the current status of each.
 
 ### 2. Set Up Locally
 
@@ -60,8 +74,7 @@ pnpm dev
 
 ## Branch Strategy
 
-- **main** - Production-ready code
-- **develop** - Development branch (if used)
+- **main** - Production-ready code, and the branch releases cut from
 - **feature/** - New features
 - **fix/** - Bug fixes
 - **docs/** - Documentation changes
@@ -98,20 +111,25 @@ Types:
 
 ## Code Style
 
-All Coral projects use:
+All Coral projects share their tooling through
+[`@get-coral/dev-standards`](https://github.com/Get-Coral/dev-standards):
 
-- **Biome** - Linting and formatting
-- **TypeScript** - Type checker
-- **ESLint** - Code quality
+- **[Biome](https://biomejs.dev)** — linting *and* formatting, via
+  `@get-coral/biome-config`. Coral does not use ESLint or Prettier anywhere
+- **TypeScript** — via `@get-coral/tsconfig`
+- **Vitest** — tests
 
 Run checks before submitting:
 
 ```bash
-pnpm lint
-pnpm type-check
-pnpm format
+pnpm check      # Biome lint + format check
+pnpm typecheck  # TypeScript
+pnpm test       # Vitest
 ```
 
+`pnpm lint` runs Biome with auto-fix. Note the script is `typecheck`, with no
+hyphen.
+
 ## Testing
 
 Include tests for new features:
@@ -159,9 +177,14 @@ Don't worry about feedback — it's how we maintain quality!
 
 ## License
 
-By contributing, you agree to license your contributions under the project's license:
-- Most Coral projects: **MIT**
-- Some may vary — check the LICENSE file
+Coral is MIT licensed. The published npm packages
+(`@get-coral/jellyfin`, `@get-coral/ui`, `@get-coral/tsconfig`,
+`@get-coral/biome-config`, `create-coral`) declare `"license": "MIT"`, and
+Aurora, KAPOW! and Coral UI carry a `LICENSE` file.
+
+Several module repositories do not yet carry one. If you are contributing to a
+repository with no `LICENSE` file, ask before assuming — and adding the file is
+itself a welcome pull request.
 
 ## Building a New Module
 

src/content/docs/contributing/project-templates.md

@@ -1,6 +1,6 @@
 ---
 title: Project Templates
-description: Building new Coral modules with project templates
+description: What the Coral module template contains, how to rename it for your own module, and the conventions every module follows.
 ---
 
 ## Creating a New Coral Module
@@ -78,7 +78,9 @@ If you cloned manually, replace `coral-module` throughout:
 }
 
 # In .github/workflows/docker-publish.yml
-IMAGE_NAME: my-module   # bare name; the workflow builds getcoral/<IMAGE_NAME>
+IMAGE_NAME: my-module   # bare name. The workflow publishes two images:
+                        #   ghcr.io/get-coral/<IMAGE_NAME>
+                        #   <DOCKERHUB_USERNAME>/<IMAGE_NAME>
 
 # In README.md
 # My Module
@@ -92,17 +94,22 @@ pnpm install
 
 ### 4. Create Your App
 
-The template includes:
+The template is deliberately close to empty:
 
 ```
-src/routes/
-├── index.tsx          # Home page
-├── api/
-│   └── example.ts     # API endpoint
-└── components/        # Reusable components
+src/
+├── routes/
+│   ├── __root.tsx     # Root layout
+│   └── index.tsx      # Home page
+├── router.tsx         # Router setup
+├── routeTree.gen.ts   # Generated — do not edit
+├── styles.css
+├── env.d.ts
+└── example.test.tsx
 ```
 
-Add your pages and components following TanStack Start conventions.
+There is no `api/` or `components/` directory yet; create them as you need
+them, following TanStack Start's file-based routing conventions.
 
 ### 5. Configure Jellyfin Connection
 
@@ -128,12 +135,12 @@ Runs on `http://localhost:3000`
 ### Key Directories
 
 - `src/routes/` - Page components and API routes
-- `src/components/` - Reusable UI components
-- `src/lib/` - Utilities and helpers
-- `src/integrations/` - External service integration
 - `public/` - Static assets
 - `.github/workflows/` - CI/CD pipelines
 
+Existing modules also use `src/components/`, `src/lib/` and `src/server/`. Those
+are conventions worth following, not directories the template ships.
+
 ### Configuration Files
 
 - `package.json` - Dependencies
@@ -178,8 +185,9 @@ const client = createClient({
   userId: process.env.JELLYFIN_USER_ID
 })
 
-const items = await getLibraryItems(client, {
-  parentId: 'library-id'
+const items = await getLibraryItems(client, 'Movie', {
+  limit: 24,
+  sortBy: 'SortName'
 })
 ```
 
@@ -261,16 +269,16 @@ Reference existing modules:
 
 - Update dependencies regularly: `pnpm update`
 - Monitor security advisories
-- Update Tailwind CSS v4
-- Update TanStack packages
+- Keep `@get-coral/biome-config` and `@get-coral/tsconfig` current — they carry
+  the shared defaults
 
 ### Upgrading TanStack Start
 
 ```bash
-pnpm add -u @tanstack/start
-pnpm add -u @tanstack/router
+pnpm update @tanstack/react-start @tanstack/react-router
 ```
 
+The package is `@tanstack/react-start`; `@tanstack/start` was its old name.
 Check release notes for breaking changes.
 
 ## Getting Help
@@ -299,3 +307,10 @@ When ready to share:
 ---
 
 Happy building! 🚀
+
+## Related
+
+- [create-coral CLI](/getting-started/create-coral/) — the supported way to start from this template
+- [Encore](/modules/encore/) — a live, unmodified copy of the template
+- [Module contracts](/getting-started/module-contracts/) — if your module needs to talk to another
+- [Contributing](/contributing/getting-started/) — tooling and commit conventions

src/content/docs/getting-started/create-coral.md

@@ -1,6 +1,6 @@
 ---
 title: create-coral CLI
-description: Scaffold a new Coral module with the official create-coral package
+description: Scaffold a new Coral module from the official template — usage, flags, and what you get.
 ---
 
 ## What it is
@@ -74,4 +74,33 @@ The CLI is the recommended path. Manual cloning of `Get-Coral/template` is mainl
 - [Project Templates](/contributing/project-templates/)
 - [Contributing](/contributing/getting-started/)
 - [create-coral on npm](https://www.npmjs.com/package/create-coral)
-- [create-coral on GitHub](https://github.com/Get-Coral/create-coral)
+- [create-coral on GitHub](https://github.com/Get-Coral/create-coral)
+
+## Options
+
+```
+pnpm create coral@latest my-module
+pnpm create coral@latest
+```
+
+| Flag | Purpose |
+|---|---|
+| `--module-name <name>` | Override the module/package name |
+| `--template-repo <org/repo>` | Use a custom template repository (default `Get-Coral/template`) |
+| `--template-ref <ref>` | Template git ref: branch, tag or SHA (default `main`) |
+| `--yes` | Skip prompts and use defaults |
+| `--install` | Run `pnpm install` after scaffolding |
+| `--no-install` | Skip `pnpm install` |
+| `--help` | Show usage |
+
+Non-interactive, for CI or a script:
+
+```bash
+pnpm create coral@latest my-module --yes --install
+```
+
+## Related
+
+- [Project templates](/contributing/project-templates/) — what the scaffold contains and how to rename it
+- [Encore](/modules/encore/) — a live, unmodified copy of the template
+- [Contributing](/contributing/getting-started/) — tooling and commit conventions

src/content/docs/getting-started/docker-compose.md

@@ -1,10 +1,8 @@
 ---
 title: Running a stack with Docker Compose
-description: A working Jellyfin + Aurora + Tide stack, with the wiring between them explained
+description: A working Jellyfin, Aurora, Tide and Librarian stack — including the mount layout that makes hardlinked imports work.
 ---
 
-## Running a stack with Docker Compose
-
 Coral modules are independent containers. They connect to each other through a
 shared Jellyfin server and, where it matters, a shared filesystem. This page is
 a working example of that: Jellyfin, Aurora, Tide and Librarian, with
@@ -27,6 +25,11 @@ Jellyfin scans media/ and finds it named the way it expects
 Aurora reads Jellyfin at http://jellyfin:8096 and shows it
 ```
 
+Each service has its own page: [Aurora](/modules/aurora/),
+[Tide](/modules/tide/) and [Librarian](/modules/librarian/). The cross-module
+link between Tide and Librarian is described in
+[Module contracts](/getting-started/module-contracts/).
+
 Aurora proxies all Jellyfin traffic server-side, so the browser never contacts
 Jellyfin directly. That is why an internal service name works for
 `JELLYFIN_URL` — it only has to resolve from inside Aurora's container.
@@ -239,9 +242,13 @@ Jellyfin has to exist before Aurora can be pointed at it.
 4. Put the key, your user's **UUID** (not the username), your username and
    password, and your `PUID`/`PGID` into `.env`
 5. `docker compose up -d`
-6. Open Librarian at `http://localhost:3002`, connect it to Jellyfin, and turn
-   on the two roots it seeded. Roots arrive switched off: a mounted directory
-   is not permission to write to it.
+6. Open Librarian at `http://localhost:3002`. **It will ask you to sign in.**
+   Librarian requires a Jellyfin sign-in by default, and anything that touches
+   the filesystem additionally requires that account to be a Jellyfin
+   **administrator** — it moves and deletes files, so it does not default open
+   the way Aurora and Tide do.
+7. Connect it to Jellyfin, then turn on the two roots it seeded. Roots arrive
+   switched off: a mounted directory is not permission to write to it.
 
 `JELLYFIN_USER_ID` must be the UUID. The API key alone is enough to browse;
 username and password additionally open a real playback session, which is what
@@ -253,3 +260,8 @@ Jellyfin cannot reach VideoToolbox from a Linux container, so transcoding is
 CPU-only — Direct Play is fine, 4K transcoding is not. Jellyfin's real-time
 library monitoring also depends on inotify, which is unreliable over macOS bind
 mounts; rely on the scheduled scan or trigger one by hand.
+
+## Related
+
+- [Aurora](/modules/aurora/), [Tide](/modules/tide/), [Librarian](/modules/librarian/) — the three modules in this stack
+- [Module contracts](/getting-started/module-contracts/) — how Tide tells Librarian a download finished

src/content/docs/getting-started/introduction.md

@@ -1,18 +1,29 @@
 ---
 title: Introduction to Coral
-description: Get started with the Coral ecosystem
+description: What Coral is, how its modules relate to Jellyfin and to each other, and which one to start with.
 ---
 
 ## What is Coral?
 
 Coral is an open-source ecosystem of independent, modular interfaces for [Jellyfin](https://jellyfin.org/) — a free media system that puts you in control of your entertainment.
 
-Each Coral module is purpose-built for a specific use case:
+Each module runs as its own Docker container, reads Jellyfin over its HTTP API,
+and does one thing:
 
-- **Aurora** - Full-featured video client with personalized home, search, and playback
-- **Fathom** - Elegent reading interface for books, manga, comics, and PDFs
-- **Librarian** - Tools for organizing and enriching your media libraries
-- **KAPOW** - Interactive song selection and voting for group karaoke
+| Module | What it does | Status |
+|---|---|---|
+| [Aurora](/modules/aurora/) | Cinematic video frontend with playback that syncs back to Jellyfin | Shipping |
+| [Tide](/modules/tide/) | Torrent client with real queue limits and a memory guard | Shipping |
+| [KAPOW!](/modules/kapow/) | Karaoke queue for bars and parties, with phone-based voting | Shipping |
+| [Librarian](/modules/librarian/) | Imports finished downloads into your media tree by hardlinking | Early |
+| [Fathom](/modules/fathom/) | Cover-first reading room for books, manga, comics and PDFs | Early |
+| [Marquee](/modules/marquee/) | Always-on ambient display for a spare TV or tablet | Early |
+| [Encore](/modules/encore/) | The module scaffold. Named for a feature that is not built yet | Scaffold |
+
+**Status is not decoration.** *Shipping* means feature-complete for its stated
+purpose. *Early* means it runs and does something useful, but the surface is
+small and moving. *Scaffold* means the published image serves a placeholder.
+Each module page repeats its status and says exactly what is and is not there.
 
 ## Why Coral?
 
@@ -56,14 +67,13 @@ bun create coral@latest
 
 That bootstraps the current Coral template with TypeScript, Biome, and release automation already wired in. For the full flow, see [create-coral CLI](/getting-started/create-coral/).
 
-Choose a module to explore:
+If you want to *run* Coral rather than build on it, start here instead:
 
-- [**Aurora**](/modules/aurora/) - Start building with the video client
-- [**Fathom**](/modules/fathom/) - Set up your reading interface
-- [**Librarian**](/modules/librarian/) - Organize your media
-- [**KAPOW**](/modules/kapow/) - Create the ultimate karaoke experience
-- [**Encore**](/modules/encore/) - Template for building custom modules
-- [**Marquee**](/modules/marquee/) - Template for building custom modules
+- [**Running a stack with Docker Compose**](/getting-started/docker-compose/) —
+  Jellyfin, Aurora, Tide and Librarian together, with the mount layout that
+  makes hardlinked imports work. This is the page most people want.
+- [**Aurora**](/modules/aurora/) — the single most useful module to add to an
+  existing Jellyfin server
 
 ## Development
 
@@ -76,7 +86,8 @@ All Coral modules are built with:
 
 ## Learn More
 
-- Visit [getcoral.dev](https://getcoral.dev) for the main website
+- [getcoral.dev](https://getcoral.dev) — what each module is for, and how it
+  compares to the alternatives. These docs cover how to run them
 - Explore the [Jellyfin API Client](/libraries/jellyfin/) for building with the API
 - Use the [create-coral CLI guide](/getting-started/create-coral/) to scaffold a new module
 - See [Contributing](/contributing/getting-started/) to build your own module