# Atlas full documentation

> Complete canonical context for Atlas. Use llms.txt and individual Markdown alternates when a smaller context is sufficient.

<document path="llms.txt">
# Atlas

> Two boilerplates: composable Bun/TypeScript packages for APIs, full-stack applications, command-line tools, retrieval, and tool-using agents; and a Rust workspace on gpui and guise for native desktop applications.

Atlas installs as `@wess/atlas`. Public imports use `@wess/atlas/<package>`. The shorter
`@atlas/<package>` spelling requires the optional path aliases documented in the project README.

When generating Atlas code:

- Read the agent guide, then only the package references required by the task.
- Use functions and immutable data; do not introduce classes or mutate inputs.
- Prefer Bun and Web APIs over compatibility packages.
- Treat an export as unavailable unless it appears in a canonical package reference or the API index.
- Run `bun run check`, `bun run typecheck`, and `bun test` before declaring repository work complete.

## Start here

- [Agent guide](https://wess.io/atlas/docs/agents/index.md): Grounding order, import rules, package selection, MCP safety, context budgets, and verification.
- [Quick start](https://wess.io/atlas/docs/quickstart/index.md): Build an authenticated application with storage and administration.
- [API reference](https://wess.io/atlas/docs/api/index.md): Condensed cross-package exports, types, and signatures.
- [Documentation map](https://wess.io/atlas/docs/index.md): Every guide and package reference.
- [Field survey](https://wess.io/atlas/index.md): The site's branching entry point; each numbered section ends in a concrete stack, command, and code.

## Package references

- [config](https://wess.io/atlas/docs/config/index.md): Typed environment variables through `defineConfig` and `env`.
- [db](https://wess.io/atlas/docs/db/index.md): Query building, schemas, changesets, and database drivers.
- [migrate](https://wess.io/atlas/docs/migrate/index.md): Timestamped migrations and schema diffing.
- [server](https://wess.io/atlas/docs/server/index.md): Pipe-based HTTP, typed routes, WebSockets, and server-sent events.
- [edge](https://wess.io/atlas/docs/edge/index.md): TLS-terminating reverse proxy.
- [auth](https://wess.io/atlas/docs/auth/index.md): Passwords, tokens, sessions, authentication flows, and social sign-in.
- [security](https://wess.io/atlas/docs/security/index.md): Headers, rate limits, audit logs, TOTP, and revocable sessions.
- [oauth](https://wess.io/atlas/docs/oauth/index.md): OAuth 2.1 authorization server.
- [sso](https://wess.io/atlas/docs/sso/index.md): OIDC relying party.
- [email](https://wess.io/atlas/docs/email/index.md): Provider-neutral delivery and account templates.
- [share](https://wess.io/atlas/docs/share/index.md): Share URLs and server-side share-by-email.
- [storage](https://wess.io/atlas/docs/storage/index.md): S3-compatible object operations and presigned URLs.
- [cache](https://wess.io/atlas/docs/cache/index.md): Redis caching and cache-aside helpers.
- [request](https://wess.io/atlas/docs/request/index.md): Fetch client, retries, interceptors, and provider presets.
- [cli](https://wess.io/atlas/docs/cli/index.md): Commands, scaffolding, documentation lookup, and process management.
- [ui](https://wess.io/atlas/docs/ui/index.md): React application blocks.
- [admin](https://wess.io/atlas/docs/admin/index.md): Schema-driven administration.
- [mcp](https://wess.io/atlas/docs/mcp/index.md): Documentation access and runtime introspection over MCP.
- [ai](https://wess.io/atlas/docs/ai/index.md): Chat, embeddings, retrieval, streaming, and tool-use loops.

## Desktop

- [Desktop architecture](https://wess.io/atlas/docs/desktop/architecture/index.md): Crate layering, the tokio bridge, state scopes, and the store.
- [Desktop scaffolding](https://wess.io/atlas/docs/desktop/scaffolding/index.md): The scaffolding script, the three templates, and renaming an application.
- [Desktop packaging](https://wess.io/atlas/docs/desktop/packaging/index.md): macOS, Linux, and Windows artifacts and where each comes from.
- [Desktop releases](https://wess.io/atlas/docs/desktop/release/index.md): Signing, notarization, release cutting, and in-place self-update.
- [Desktop gotchas](https://wess.io/atlas/docs/desktop/gotchas/index.md): gpui and guise traps, each with the symptom that led to it.

## Machine-readable interfaces

- [Complete documentation context](https://wess.io/atlas/llms-full.txt): Combined canonical guides and package references for one-fetch indexing.
- [Search index](https://wess.io/atlas/search.json): Titles, descriptions, source kind, routes, and searchable text.
- [MCP reference](https://wess.io/atlas/docs/mcp/index.md): `docs.list`, `docs.read`, health, and conditional service tools.
- [CLI reference](https://wess.io/atlas/docs/cli/index.md): Local documentation access with `atlas docs [name]`.

## Optional

- [Architecture overview](https://wess.io/atlas/docs/overview/index.md): Package graph, design philosophy, and module boundaries.
- [Cookbook](https://wess.io/atlas/docs/cookbook/index.md): Practical cross-package recipes.
- [Project README](https://wess.io/atlas/docs/readme/index.md): Installation, templates, development, and package inventory.
</document>

<document path="docs/agents.md">
# Atlas Agent Guide

Atlas exposes the same documentation through the web, package files, the CLI, and MCP. Use the
smallest transport and context set that can answer the task.

## Fast Path

1. Fetch `https://wess.io/atlas/llms.txt`.
2. Read this guide and the reference for each package the task actually uses.
3. Use the API reference only when a signature is still unclear.
4. Load the architecture overview only for cross-package design decisions.
5. Run the repository checks before presenting generated code as complete.

Do not begin by loading every package reference. Atlas is intentionally composable; most changes
need two or three packages.

## Documentation Transports

| Transport | Entry point | Best use |
|---|---|---|
| Concise web index | `/atlas/llms.txt` | Discover the minimum relevant sources |
| Complete web context | `/atlas/llms-full.txt` | One-fetch offline indexing or large-context work |
| Page Markdown | `/atlas/docs/<name>/index.md` | Fetch one canonical guide or package reference |
| Search index | `/atlas/search.json` | Programmatic title, description, kind, and text search |
| Installed CLI | `atlas docs [name]` | Read package-local docs without network access |
| MCP | `atlas mcp` | Discover docs and inspect a running Atlas application |

Every documentation HTML page declares its Markdown alternate and the covering `llms.txt` file in
the document head.

## Import Rule

Atlas installs as one package:

```bash
bun add @wess/atlas
```

Use public subpath imports in generated consumer code:

```ts
import { defineConfig, env } from "@wess/atlas/config"
import { connect } from "@wess/atlas/db"
import { get, json, serve } from "@wess/atlas/server"
```

The shorter `@atlas/<package>` spelling appears in some repository examples. It requires the
`tsconfig.json` path aliases documented in the README. Do not emit it for a new consumer unless
that alias is already configured.

## Package Selection

| Need | Read first | Common companions |
|---|---|---|
| Environment and configuration | `config` | `server`, `db` |
| SQL, schemas, and validation | `db` | `migrate`, `admin` |
| HTTP routes and responses | `server` | `config`, `security` |
| Login and sessions | `auth` | `db`, `security`, `email` |
| Authorization server | `oauth` | `auth`, `security` |
| Sign in with an identity provider | `sso` | `auth`, `security` |
| Files and object storage | `storage` | `server`, `security` |
| Redis-backed state | `cache` | `server` |
| Outbound HTTP | `request` | `config` |
| TLS edge routing | `edge` | `server` |
| React application blocks | `ui` | `server`, `auth` |
| Generated administration | `admin` | `db`, `ui` |
| Chat, retrieval, or tool loops | `ai` | `request`, `server` |
| Runtime introspection | `mcp` | the services being exposed |
| Commands and scaffolding | `cli` | the packages in the generated template |

## Generation Contract

When writing Atlas code:

- Use functions and immutable values. Do not introduce classes or mutate inputs.
- Prefer Bun and Web APIs over compatibility packages.
- Import from `@wess/atlas/<package>` in consumer projects.
- Read each selected package's canonical reference before inventing an export.
- Derive database row types with `RowOf<typeof schema>`.
- Compose HTTP behavior with `pipeline()`; use `halt()` for deliberate short-circuiting.
- Use typed `route()` validation rather than parsing the same request body manually.
- Keep filenames lowercase with no dashes, underscores, or spaces.
- Put tests under `packages/<name>/test/` when changing Atlas itself.

If a requested export is absent from the package reference and API lookup, treat it as absent. Do
not infer an API from a neighboring framework or package.

## MCP Workflow

`atlas mcp` always exposes:

- `docs.list` to discover package, guide, and root documentation identifiers.
- `docs.read` to read one canonical source.
- `health.check` to report configured service connectivity.

Additional tools appear only when their service is present in the MCP context. Read-only
introspection includes schema, route, migration-status, cache-read, storage-list, and log-tail
operations. Migration, cache-write, cache-delete, cache-flush, and other state-changing tools must
be treated as mutations, not discovery.

Recommended sequence:

1. Call `docs.list`.
2. Read the references needed for the task.
3. Call `health.check` and read-only inspection tools.
4. Explain the intended mutation before invoking a state-changing tool.
5. Re-read the affected state after the mutation.

## Context Budgets

### Small

Use `llms.txt`, this guide, and one package reference.

### Feature

Add the quick start or API reference plus every package directly involved in the feature.

### Architecture

Add the overview and references for both sides of each package boundary.

### Complete

Use `llms-full.txt` only when building a local index, working offline after one fetch, or when the
available context can hold the full corpus. It duplicates the sources linked by `llms.txt`.

## Verification

Run checks in this order:

```bash
bun run check
bun run typecheck
bun test
```

For documentation work, also run:

```bash
bun run site:build
bun test site/test/site.test.ts
```

Generated code is not grounded until its imports exist, its package references agree with the
usage, and the relevant checks pass.
</document>

<document path="docs/overview.md">
# Atlas: Architecture Overview

Atlas is a collection of composable, functional Bun/TypeScript packages for building APIs, full-stack applications, and CLI tools. This document describes the architecture, package relationships, and design philosophy.

## Dependency Graph

```
@atlas/config (foundation — typed env loading)
  ├── @atlas/db
  ├── @atlas/server
  ├── @atlas/storage
  └── @atlas/cli

@atlas/migrate (depends on @atlas/db)
@atlas/auth (depends on @atlas/db, @atlas/server)
  └── @atlas/auth/social (subpath — OAuth-client side: Google/GitHub/Apple/MS/FB/X/TikTok)
@atlas/admin (depends on @atlas/db, @atlas/server)
@atlas/security (depends on @atlas/db, @atlas/auth)
@atlas/oauth (depends on @atlas/db, @atlas/server, @atlas/auth)
@atlas/sso (depends on @atlas/db, @atlas/server, @atlas/auth)
@atlas/edge (standalone — no sibling deps)
@atlas/email (standalone — no sibling deps)
@atlas/share (depends on @atlas/email — share URL builders + server-side share-by-email)

@atlas/cache (optional, can use @atlas/config)
@atlas/request (standalone — no sibling deps)
@atlas/mcp (depends on @atlas/db, @atlas/server, @atlas/config)
@atlas/ai (depends on @atlas/server for the withAi pipe; no external deps)

@atlas/ui (frontend, optional browser-side usage)
```

Packages are shallow — max 1 level of dependencies on siblings. This keeps them lightweight and composable.

## Core Packages

### Config

`@atlas/config` is the foundation. It provides typed environment variable loading that reads `.env` at startup and produces a frozen, immutable config object.

```ts
const config = defineConfig({
  database: env("DATABASE_URL"),
  port: env("PORT", { parse: Number, default: "3000" }),
})
```

All other packages optionally depend on config or accept config values directly. No forced wiring.

### Database

`@atlas/db` is the largest package, with three layers:

1. **Query Builder** — Ecto-inspired fluent chains for SELECT, INSERT, UPDATE, DELETE, JOIN operations. Fully immutable, functional API.
2. **Drivers** — Uniform interface to Postgres (via `Bun.sql`) and SQLite (via `bun:sqlite`) with transaction support.
3. **Schemas & Changesets** — Type-safe table definitions and Zod-powered input validation.

```ts
const users = defineSchema("users", {
  id: column.serial().primaryKey(),
  email: column.text().unique(),
})

const query = from(users).where(q => q("email").equals("user@test.com"))
const result = await db.one(query)
```

### Server

`@atlas/server` wraps `Bun.serve` with a Plug-inspired pipe system. Requests flow through immutable `Conn` objects that pipes transform.

Sub-modules:
- `@atlas/server` — Core HTTP routing with `get()`, `post()`, `put()`, `patch()`, `del()` route builders, plus the adapter pattern (`createAdapter`, `compose`) for running multiple listeners
- `@atlas/server/ws` — WebSocket support
- `@atlas/server/sse` — Server-Sent Events

```ts
const logger = pipe(c => { console.log(c.method); return c })
const auth = pipe(c => {
  const token = c.headers.get("authorization")
  return token ? assign(c, { userId: decode(token).id }) : halt(c, 401)
})

serve({
  routes: [
    get("/users", pipeline(logger, auth)(handler)),
  ],
})
```

Pipes are composable via `pipeline()`, which short-circuits on `halt()`. This approach is borrowed from Elixir and is more testable and readable than middleware.

### Edge

`@atlas/edge` is a TLS-terminating reverse proxy with built-in Let's Encrypt automation — the layer that would otherwise be Caddy or nginx in front of a Bun app.

- **ACME v2 client** — ECDSA P-256 account, JWS-signed requests, HTTP-01 challenge solver, hand-rolled CSR via a small DER encoder. No external deps.
- **Reverse proxy** — forwards requests with `X-Real-IP`, `X-Forwarded-For` (appended), `X-Forwarded-Proto`, `X-Forwarded-Host`. Hop-by-hop headers stripped. Host rewritten unless `preserveHost: true`.
- **Cert lifecycle** — certs persist to a configurable store (filesystem default, in-memory for tests). A renewal timer reissues 30 days before expiry and `server.reload({ tls })` swaps without dropping connections.
- **Localhost dev** — when every site host matches `isLocalHost`, the edge runs plain HTTP on a non-privileged port. No certs, no sudo. The same `edge.ts` runs in dev and prod.

```ts
import { defineEdge, proxy } from "@atlas/edge"

defineEdge({
  acme: { email: "you@example.com", storage: "/var/atlas/edge" },
  sites: [{
    host: process.env.DOMAIN!,
    compress: ["gzip", "zstd"],
    routes: [{ handler: proxy("http://app:3000") }],
  }],
}).listen()
```

The `templates/edge` scaffold ships a complete deploy pattern: Procfile for local, Dockerfile + compose.yaml for production, with the cert volume and ACME staging-then-prod recipe pre-wired.

### Auth

`@atlas/auth` provides:

- **Primitives** — `hash()`, `verify()`, `token.sign()`, `token.verify()` built on Bun's crypto
- **Flows** — Prebuilt pipes like `signup()`, `login()`, `requireAuth()`, `passwordReset()` that work with `@atlas/server` and `@atlas/db`
- **Social login** (`@atlas/auth/social` subpath) — pluggable OAuth-*client* for Google, GitHub, Apple, Microsoft, Facebook, X (Twitter), and TikTok. PKCE-S256 mandatory, state + verifier held in a signed HttpOnly cookie so the flow stays stateless. Your app owns the user table — `onSuccess` receives a normalized `SocialProfile` and you decide upsert/link.

```ts
const signupPipe = signup({
  db,
  table: "users",
  fields: ["email", "password"],
  onSuccess: (c, user) => json(c, 201, user),
})

// Social — same Conn/PipeFn shape:
const social = socialAuth({
  secret,
  providers: {
    google: google({ clientId, clientSecret, redirectUri }),
    github: github({ clientId, clientSecret, redirectUri }),
    tiktok: tiktok({ clientKey, clientSecret, redirectUri }),
    // …apple, microsoft, facebook, twitter
  },
})
get("/auth/google", social.start("google"))
get("/auth/google/callback", social.callback("google", {
  onSuccess: async (c, { profile }) => json(c, 200, { profile }),
}))
```

### Security

`@atlas/security` ships hardening primitives most apps end up writing themselves:

- `withSecurityHeaders()` — strict default headers (HSTS, COOP/CORP, Permissions-Policy) and a CSP that defaults to `'self'`-only with no inline script in production. Also stashes the real Bun socket peer onto `req.peerIp` so downstream rate-limit / audit code does not have to trust client-supplied `X-Forwarded-For`.
- `createDbRateLimit()` / `createMemoryRateLimit()` — atomic UPSERT on Postgres, transactional read-modify-write on SQLite, in-memory for tests.
- `clientIp(req, { trustedProxies })` — only honors forwarded headers when the request actually arrived from a configured trusted proxy.
- `createSessionStore()` — DB-backed, revocable JWT sessions with `last_used_at` tracking and a sweep helper. Pair with `@atlas/auth#requireAuth`.
- `generateSecret` / `verifyTotp` / `otpauthUrl` / `generateBackupCodes` — pure `node:crypto` TOTP with backup codes.
- `decideInline()` — safe-MIME allowlist for `Content-Disposition: inline` (never inlines SVG).
- `createAuditLogger()` — fire-and-forget audit-event recorder; never throws, never blocks the response.

### OAuth

`@atlas/oauth` is an OAuth 2.1 server: PKCE-required authorization code, refresh-token rotation, device-code flow, RFC 8414 discovery, RFC 7009 revoke, and admin client management.

```ts
import { oauthRoutes } from "@atlas/oauth"
import { requireAuth } from "@atlas/auth"

serve({
  routes: [
    ...oauthRoutes({
      db,
      secret,
      scopes: ["read", "write"],
      loadUser,
      buildAccessTokenClaims,
      requireUser: requireAuth({ secret }),
      requireAdmin,
    }),
    ...appRoutes,
  ],
})
```

`oauthRoutes(cfg)` returns every endpoint as a flat `Route[]` ready to spread into `serve`. Mount only what you need by calling the per-flow factories (`oauthAuthorizeRoutes`, `oauthTokenRoutes`, …) directly. Sweeps for expired auth codes / refresh tokens / device codes are exported separately so you can run them on a schedule.

### Email

`@atlas/email` is a provider-agnostic transport plus a small HTML shell and two stock templates.

```ts
import { createEmailer, inviteEmail } from "@atlas/email"

const emailer = createEmailer({ apiKey: process.env.RESEND_API_KEY, from: process.env.RESEND_FROM })
await emailer.send({ to: "user@example.com", ...inviteEmail({ inviterName, product, signupUrl }) })
```

`createEmailer` returns the real Resend transport when both env vars are set and a console transport otherwise — dev environments stay unblocked without configuring a sending domain. `send` never throws; failures come back as `{ ok: false, error }`. The included `layout()` is a 560px Outlook-friendly card; always pass user-supplied strings through `escapeHtml`.

### Share

`@atlas/share` is the smallest practical layer for "share this link" UX. Pure URL builders for the eight channels users actually use, plus a server-side `shareEmail` that dispatches through any `@atlas/email` transport.

```ts
import { share, shareUrl, shareEmail } from "@atlas/share"

shareUrl("twitter", { url, title, hashtags: ["atlas"] })
// → https://twitter.com/intent/tweet?url=…&text=…&hashtags=atlas

share({ url, title, text })
// → { twitter, facebook, linkedin, reddit, whatsapp, telegram, sms, email }

await shareEmail({
  emailer,
  to: "friend@example.com",
  sharerName: "Wess",
  content: { url, title },
})
```

The URL builders have zero dependencies; `shareEmail` reuses the same `layout()` shell as `inviteEmail`/`passwordResetEmail` and escapes untrusted strings the same way.

### Storage

`@atlas/storage` provides S3-compatible object storage with:

- `upload()` — PUT file to bucket
- `download()` — GET file from bucket
- `presign()` — Generate presigned URLs for direct client access
- `list()` — List objects by prefix

Uses AWS Signature V4 (implemented from scratch, ~250 lines) with no external dependencies.

### Cache

`@atlas/cache` wraps `Bun.redis` with:

- `createCache()` — Redis-backed cache
- `createMemoryCache()` — In-memory (for testing)
- `cached()` — Cache-aside pattern: fetch from cache, fallback to function, store result
- `invalidate()` — Bust cache keys

```ts
const getUser = cached(cache, "user", async (id) => {
  return await db.one(from(users).where(q => q("id").equals(id)))
}, { ttl: 600 })
```

### Request

`@atlas/request` is an HTTP client built on `fetch` with:

- `request()` — One-off requests
- `createClient()` — Preconfigured clients with base URL, headers, retries
- Providers — Drop-in configs for GitHub, Stripe, OpenAI, Resend (import from `@atlas/request/providers`)
- Retry logic with exponential backoff
- Request/response interceptors

```ts
import { github } from "@atlas/request/providers"

const gh = github({ token: process.env.GITHUB_TOKEN! })
const repos = await (await gh.get("/user/repos")).json()
```

### CLI

`@atlas/cli` provides:

- **Command parser** — Define commands, flags, subcommands; parse argv
- **Foreman** — Procfile parser and concurrent process runner with colored output
- **Built-in commands** — `atlas init` (scaffold project), `atlas add` (add packages), `atlas dev` (start dev server), `atlas mcp` (launch MCP server)

```ts
cli("myapp", [
  command("serve", {
    flags: { port: flag("p", { type: "number", default: 3000 }) },
    run: ({ flags }) => startServer(flags.port),
  }),
])

await foreman({ web: "bun run server.ts", worker: "bun run worker.ts" })
```

### Migrate

`@atlas/migrate` manages timestamped SQL migrations with up/down support.

```ts
migrate.create("./migrations", "add_users")
await migrate.up(db, "./migrations")
await migrate.status(db, "./migrations")
```

Tracks applied migrations in `schema_migrations` table. Works with Postgres and SQLite.

### UI

`@atlas/ui` is a modular React + Mantine package with independent blocks:

- `@atlas/ui/provider` — Theme and layout shell
- `@atlas/ui/forms` — Form primitives and helpers
- `@atlas/ui/table` — Data tables with sort/filter/pagination
- `@atlas/ui/auth` — Login, signup, password reset pages
- `@atlas/ui/storage` — File upload and image preview
- `@atlas/ui/nav` — Navigation components
- `@atlas/ui/cache` — Cache inspector and status badge
- `@atlas/ui/ai` — Chat panel, message list, streaming display

Each block is independently importable and tree-shakeable.

### Admin

`@atlas/admin` auto-generates a Django-style admin panel from `@atlas/db` schemas. Provides:

- **API routes** — CRUD endpoints for each model
- **Admin SPA** — React UI with list, detail, create views, search, filters, bulk actions, custom actions, query builder
- **Metadata routes** — Schema introspection, field info, relation discovery

```ts
const panel = admin({
  db,
  models: [
    model({
      schema: users,
      searchFields: ["email", "name"],
      filterFields: ["status"],
      bulkActions: ["delete", "export"],
    }),
  ],
})

serve({ routes: panel.mount([]) })
```

Serves SPA at `/admin` with full CRUD UI.

### MCP

`@atlas/mcp` provides a Model Context Protocol server for AI/LLM debugging and introspection. It exposes your app's database, routes, config, and logs to AI agents through the standard MCP protocol.

```ts
import { collectTools, createContext, createMcpServer } from "@atlas/mcp"

const ctx = createContext({ db, routes: myRoutes, config })
const mcp = createMcpServer(collectTools(ctx), ctx)

mcp.start()
```

Launch via CLI: `atlas mcp`. AI agents can then query your database, inspect routes, view config, and read logs interactively.

### AI

`@atlas/ai` provides a unified interface for AI/LLM operations with zero external dependencies — it calls provider REST APIs directly via `fetch`.

- **Providers** — `createProvider({ provider, key })` returns an `AiProvider` for `"openai"`, `"anthropic"`, or `"ollama"`
- **Chat** — `provider.chat(opts)` for completions, `provider.chatStream(opts)` for streaming `StreamChunk`s
- **Conversations** — `createConversation`/`send` for immutable message-history tracking
- **Embeddings** — `embed(provider, inputs)` plus an in-memory `createVectorStore()`
- **RAG** — `index(rag, id, text)` + `query(rag, question)` over a `{ ai, store, topK? }` bag
- **Agents** — `runAgent({ ai, system?, tools, maxIterations? }, prompt)` for tool-using loops
- **Server pipe** — `withAi(provider)` attaches the provider to `conn.assigns.ai`

```ts
import { createProvider, send, createConversation, runAgent, tool } from "@atlas/ai"

const openai = createProvider({ provider: "openai", key: process.env.OPENAI_API_KEY! })

const conv = createConversation("You are a helpful assistant")
const { response } = await send(openai, conv, "Hello")

for await (const chunk of openai.chatStream({ messages: [{ role: "user", content: "Hi" }] })) {
  if (chunk.type === "text") process.stdout.write(chunk.content ?? "")
}
```

Works with OpenAI, Anthropic, Ollama, or any OpenAI-compatible endpoint (`baseUrl` override).

## Templates

Atlas ships with 10 project templates, scaffolded via `atlas init --template <name>`:

| Template | Description | Key Packages |
|----------|-------------|-------------|
| `minimal` | Just server + config | config, server |
| `api` | REST API with db, auth, migrations | config, db, migrate, server, auth |
| `edge` | App + TLS-terminating edge (replaces Caddy/nginx) | config, server, edge |
| `fullstack` | API + React frontend | config, db, server, auth, ui |
| `admin` | API + admin panel | config, db, server, auth, admin |
| `worker` | Background job processor | config, db, cache, cli |
| `realtime` | WebSocket + SSE | config, server |
| `socialnetwork` | Users, posts, follows, likes, feeds, media, real-time | config, db, server, auth, cache, storage |
| `cms` | Headless CMS with content types, publishing, webhooks | config, db, server, auth, storage, admin |
| `ai` | Chatbot, RAG, agents, embeddings, streaming | config, server, ai |

## Composition Patterns

### Typical Backend App

```ts
// 1. Config
const config = defineConfig({ database: env("DATABASE_URL"), ... })

// 2. Database
const db = connect({ driver: "postgres", url: config.database })

// 3. Migrations
await migrate.up(db)

// 4. HTTP with pipes
serve({
  routes: [
    post("/auth/signup", signup({ db, table: "users", ... })),
    post("/auth/login", login({ db, table: "users", ... })),
    get("/api/users", pipeline(requireAuth({ secret }))(listUsers)),
    post("/api/files", pipeline(requireAuth({ secret }), parseMultipart)(uploadFile)),
  ],
})
```

### Full Stack

Use `@atlas/ui` blocks on the client:

```tsx
// server.ts
import { get, halt, pipe, putHeader, serve } from "@atlas/server"

const page = await Bun.file("./admin.html").text() // HTML file that loads the React SPA
const spa = pipe((c) => putHeader(halt(c, 200, page), "content-type", "text/html; charset=utf-8"))

serve({
  routes: [
    get("/admin", spa),
    get("/admin/*", spa),
    ...apiRoutes,
  ],
})
```

```html
<!-- admin.html -->
<html>
  <body>
    <div id="root"></div>
    <script type="module" src="./admin.tsx"></script>
  </body>
</html>
```

```tsx
// admin.tsx
import { AdminApp } from "@atlas/admin"
import { createRoot } from "react-dom/client"

const root = createRoot(document.getElementById("root")!)
root.render(<AdminApp />)
```

## AGENTS.md Convention

Each package includes an `AGENTS.md` at its root — a compact manifest (~80 lines) of the public API.

**Structure:**

- **Exports** — Each public function/type with signature and return type
- **Types** — Data shapes that users need to generate correct code
- **Usage** — Minimal working example
- **Dependencies** — Sibling and external packages

**Why this matters:**

LLMs can read `packages/db/AGENTS.md` instead of traversing 20+ source files. This is critical for token efficiency in prompt engineering and code generation workflows.

**Conventions:**

- Keep under 100 lines
- Every public export must be listed
- Include return types and argument types
- Update whenever the API changes
- Treat as part of the build process

## Design Philosophy

1. **Functional** — No classes, immutable data, composition over inheritance
2. **Minimal dependencies** — Wrap Bun's native APIs, don't reach for external packages
3. **Composable** — Each package works independently or with others
4. **AI/LLM-friendly** — Clear APIs, good types, predictable patterns, AGENTS.md reference
5. **No framework lock-in** — Use what you need, combine with anything else
6. **Bun-native** — Idiomatic to Bun's philosophy and APIs
7. **Shallow dependencies** — Max 1 level of sibling package dependencies

## External Dependencies

| Package | Deps |
|---------|------|
| config | none |
| db | `zod` |
| migrate | none |
| server | none |
| auth | none |
| security | none |
| oauth | none |
| edge | none |
| email | none |
| share | none |
| storage | none |
| cache | none |
| request | none |
| sso | none |
| cli | none |
| ui | `react`, `@mantine/*`, `@tanstack/*`, `lucide-react` |
| admin | `react`, `@mantine/*`, `@tanstack/*`, `lucide-react` |
| mcp | none |
| ai | none |

Total: Only `zod` on the backend. Frontend uses React + Mantine + TanStack.

## Development Environment

- **Monorepo** — Bun workspaces
- **Testing** — `bun test` across all packages
- **TypeScript** — Strict mode
- **Linting** — Biome (run `bun run check` / `bun run tidy`)
- **File naming** — All lowercase, no dashes or underscores, subdirectories for organization
- **Environment** — `.env` in root (Postgres on localhost, SQLite in memory for tests)
</document>

<document path="docs/quickstart.md">
# Atlas Quick Start

This guide walks you through building a complete app with user authentication, file uploads, and an admin panel.

## Prerequisites

- **Bun 1.0+** — Install from https://bun.sh
- **Postgres** (optional) — For production; SQLite works for development
- **Redis** (optional) — For caching; memory cache works for dev

This guide uses SQLite for simplicity.

## Step 1: Create a Project

```bash
mkdir myapp
cd myapp
bun init -y
```

Add Atlas:

```bash
bun add @wess/atlas
```

Every package is a subpath export (`@wess/atlas/config`, `@wess/atlas/db`, …).
To use the `@atlas/<pkg>` spelling this guide uses, map it via `tsconfig.json`
`paths` (bun reads tsconfig paths at runtime) — the full mapping lives in the
README's Install section.

Create `.env`:

```
DATABASE_URL="sqlite:./app.db"
PORT=3000
SECRET="dev-secret-key-change-in-production"
S3_ENDPOINT="http://localhost:9000"
S3_BUCKET="files"
S3_ACCESS_KEY="minioadmin"
S3_SECRET_KEY="minioadmin"
```

## Step 2: Define Schemas

Create `src/schema.ts`:

```ts
import { defineSchema, column } from "@atlas/db"

export const users = defineSchema("users", {
  id: column.serial().primaryKey(),
  email: column.text().unique(),
  name: column.text(),
  passwordHash: column.text(),
  createdAt: column.timestamp().defaultRaw("CURRENT_TIMESTAMP"),
})

export const uploads = defineSchema("uploads", {
  id: column.serial().primaryKey(),
  userId: column.integer().ref("users", "id"),
  filename: column.text(),
  key: column.text(),
  size: column.integer(),
  contentType: column.text(),
  createdAt: column.timestamp().defaultRaw("CURRENT_TIMESTAMP"),
})
```

## Step 3: Set Up Config

Create `src/config.ts`:

```ts
import { defineConfig, env } from "@atlas/config"

export const config = defineConfig({
  database: env("DATABASE_URL"),
  port: env("PORT", { parse: Number, default: "3000" }),
  secret: env("SECRET"),
  s3: {
    endpoint: env("S3_ENDPOINT"),
    bucket: env("S3_BUCKET"),
    accessKey: env("S3_ACCESS_KEY"),
    secretKey: env("S3_SECRET_KEY"),
  },
})
```

## Step 4: Create Migrations

You can hand-write migrations under `migrations/<timestamp>_<name>/{up,down}.sql`,
or — preferred — generate them from the `defineSchema()` you already wrote:

```ts
// scripts/diff.ts
import { connect } from "@atlas/db"
import { migrate } from "@atlas/migrate"
import { users, uploads } from "../src/schema"

const db = connect({ driver: "sqlite", path: "./app.db" })
const result = await migrate.diff(db, [users, uploads], { name: "init" })
if (result.noop) console.log("schema in sync")
else console.log(`wrote ${result.path}`)
await db.close()
```

```bash
bun scripts/diff.ts   # writes migrations/<ts>_init/up.sql + down.sql
```

`migrate.diff` introspects the live database and emits SQL for any new tables,
added/removed columns, and (as `-- ALTER` comments) type/nullability mismatches.
Re-running it after a schema edit produces an incremental migration.

For reference, here's what an init migration ends up looking like:

```sql
-- migrations/<ts>_init/up.sql (generated)
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  email TEXT NOT NULL,
  name TEXT NOT NULL,
  passwordHash TEXT NOT NULL,
  createdAt TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE uploads (
  id INTEGER PRIMARY KEY,
  userId INTEGER NOT NULL,
  filename TEXT NOT NULL,
  key TEXT NOT NULL,
  size INTEGER NOT NULL,
  contentType TEXT NOT NULL,
  createdAt TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
```

## Step 5: Build the API

Create `src/server.ts`:

```ts
import { config } from "./config"
import { users, uploads } from "./schema"
import { connect, from, type RowOf } from "@atlas/db"
import { migrate } from "@atlas/migrate"
import {
  serve,
  pipeline,
  parseMultipart,
  json,
  badRequest,
  getR,
  postR,
  post,
  parseJson,
} from "@atlas/server"
import { token, signup, login, requireAuth } from "@atlas/auth"
import { createStore, upload as uploadFile, presign } from "@atlas/storage"
import { admin, model } from "@atlas/admin"

// Connect to database
const db = connect({ driver: "sqlite", path: "./app.db" })

// Run migrations
await migrate.up(db, "./migrations")

// Storage setup
const store = createStore({
  endpoint: config.s3.endpoint,
  bucket: config.s3.bucket,
  accessKey: config.s3.accessKey,
  secretKey: config.s3.secretKey,
})

// Pipes that populate conn.assigns.auth (claims from the JWT).
const authGuard = requireAuth({ secret: config.secret })
type AuthClaims = { auth: { id: number } }

// Typed routes — c.assigns.auth.id is `number`, no casts.
const meRoute = getR<Record<string, never>, never, Record<string, string>, AuthClaims>(
  "/api/me",
  { before: [authGuard], assigns: {} as AuthClaims },
  (c) => json(c, 200, { id: c.assigns.auth.id }),
)

const filesRoute = getR<Record<string, never>, never, Record<string, string>, AuthClaims>(
  "/api/files",
  { before: [authGuard], assigns: {} as AuthClaims },
  async (c) => {
    type UploadRow = RowOf<typeof uploads>
    const rows: Pick<UploadRow, "id" | "filename" | "key" | "size" | "createdAt">[] = await db.all(
      from(uploads)
        .where((q) => q("userId").equals(c.assigns.auth.id))
        .select("id", "filename", "key", "size", "createdAt"),
    )
    return json(c, 200, rows)
  },
)

// Multipart upload still uses parseMultipart in `before` — typed body validators
// expect JSON. `throw badRequest(...)` becomes a 400 with { error, code? }.
const uploadRoute = post(
  "/api/upload",
  pipeline(authGuard, parseMultipart)(async (c) => {
    const userId = (c.assigns.auth as { id: number }).id
    const body = c.body as FormData
    const file = body.get("file") as File | null
    if (!file) throw badRequest("missing file", { code: "MISSING_FILE" })

    const key = `uploads/${userId}/${file.name}`
    await uploadFile(store, { key, body: file, contentType: file.type })

    const [created] = await db.execute(
      from(uploads)
        .insert({
          userId,
          filename: file.name,
          key,
          size: file.size,
          contentType: file.type,
        })
        .returning("id"),
    )

    return json(c, 201, {
      id: created?.id,
      filename: file.name,
      url: presign(store, key, { expires: 3600 }),
    })
  }),
)

// Admin panel
const adminPanel = admin({
  db,
  basePath: "/admin",
  auth: { secret: config.secret },
  models: [
    model({
      schema: users,
      searchFields: ["email", "name"],
      filterFields: ["createdAt"],
    }),
    model({
      schema: uploads,
      searchFields: ["filename"],
      readOnly: true,
    }),
  ],
})

// Routes
serve({
  port: config.port,
  hostname: "0.0.0.0",
  routes: [
    // Auth
    post("/auth/signup", pipeline(parseJson)(
      signup({
        db,
        table: "users",
        fields: ["email", "name", "password"],
        onSuccess: (c, user) =>
          json(c, 201, {
            id: user.id,
            email: user.email,
            name: user.name,
          }),
      })
    )),

    post("/auth/login", pipeline(parseJson)(
      login({
        db,
        table: "users",
        identity: "email",
        password: "password",
        onSuccess: async (c, user) =>
          json(c, 200, {
            token: await token.sign({ id: user.id }, config.secret),
            user: { id: user.id, email: user.email, name: user.name },
          }),
      })
    )),

    // Protected API
    meRoute,
    uploadRoute,
    filesRoute,

    // Admin
    ...adminPanel.mount([]),
  ],

  development: true,
})

console.log(`Server running on http://localhost:${config.port}`)
console.log(`Admin panel at http://localhost:${config.port}/admin`)
```

## Step 6: Run the Server

```bash
bun src/server.ts
```

You should see:
```
Server running on http://localhost:3000
Admin panel at http://localhost:3000/admin
```

## Step 7: Test the API

### Sign up a user:

```bash
curl -X POST http://localhost:3000/auth/signup \
  -H "content-type: application/json" \
  -d '{
    "email": "user@example.com",
    "name": "John Doe",
    "password": "secure123"
  }'
```

Response:
```json
{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe"
}
```

### Log in:

```bash
curl -X POST http://localhost:3000/auth/login \
  -H "content-type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure123"
  }'
```

Response:
```json
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": { "id": 1, "email": "user@example.com", "name": "John Doe" }
}
```

### Get authenticated user info:

```bash
curl -X GET http://localhost:3000/api/me \
  -H "authorization: Bearer <token>"
```

### Upload a file:

```bash
curl -X POST http://localhost:3000/api/upload \
  -H "authorization: Bearer <token>" \
  -F "file=@/path/to/file.pdf"
```

### List files:

```bash
curl -X GET http://localhost:3000/api/files \
  -H "authorization: Bearer <token>"
```

## Step 8: Access the Admin Panel

Open http://localhost:3000/admin in your browser.

You'll see:
- **Users** list with email and name search
- **Uploads** list (read-only) showing all file uploads
- Full CRUD for users (create, edit, delete)
- Filters, bulk actions, custom query builder

## Next Steps

### Add Frontend

Create a React frontend using `@atlas/ui` blocks:

```tsx
// frontend.tsx
import React from "react"
import { createRoot } from "react-dom/client"
import { AtlasProvider, AppShell } from "@atlas/ui/provider"
import { LoginPage } from "@atlas/ui/auth"
import { FileUpload } from "@atlas/ui/storage"

export default function App() {
  const [token, setToken] = React.useState<string | null>(null)

  if (!token) {
    return (
      <LoginPage
        onSubmit={async ({ email, password }) => {
          const res = await fetch("/auth/login", {
            method: "POST",
            headers: { "content-type": "application/json" },
            body: JSON.stringify({ email, password }),
          })
          const data = await res.json()
          if (data.token) {
            setToken(data.token)
            return {}
          }
          return { error: "Login failed" }
        }}
      />
    )
  }

  return (
    <AtlasProvider>
      <AppShell>
        <FileUpload
          onUpload={async (file) => {
            const form = new FormData()
            form.append("file", file)
            await fetch("/api/upload", {
              method: "POST",
              headers: { authorization: `Bearer ${token}` },
              body: form,
            })
          }}
        />
      </AppShell>
    </AtlasProvider>
  )
}

const root = createRoot(document.body)
root.render(<App />)
```

### Add Caching

```ts
import { createCache, cached } from "@atlas/cache"

const cache = createCache({ url: process.env.REDIS_URL || "redis://localhost" })

const getUser = cached(cache, "user", async (id: number) => {
  return await db.one(from(users).where(q => q("id").equals(id)))
}, { ttl: 600 })

const user = await getUser(1) // cached for 10 minutes
```

### Use Postgres in Production

```ts
const db = connect({
  driver: "postgres",
  url: config.database,
  pool: 10,
})
```

Update migrations path as needed. Everything else stays the same.

### Add AI

```ts
import { createProvider } from "@atlas/ai"

const openai = createProvider({ provider: "openai", key: process.env.OPENAI_API_KEY! })

const reply = await openai.chat({
  messages: [{ role: "user", content: "Summarize this document" }],
})

// Streaming
for await (const chunk of openai.chatStream({ messages: [{ role: "user", content: "Stream me" }] })) {
  if (chunk.type === "text") process.stdout.write(chunk.content ?? "")
}
```

Add the AI UI block to your frontend:

```tsx
import { ChatWindow } from "@atlas/ui/ai"

<ChatWindow messages={messages} onSend={(text) => sendToApi(text)} />
```

### Add Social Login

Drop "Sign in with Google / GitHub / etc." onto the existing password flow.
PKCE + state ride in a signed HttpOnly cookie, so the flow stays stateless —
no extra schema, no session table.

```ts
import { socialAuth, google, github, tiktok } from "@atlas/auth/social"
import { token } from "@atlas/auth"
import { get, post, redirect, putHeader, parseForm, pipeline } from "@atlas/server"

const origin = `http://localhost:${config.port}`

const social = socialAuth({
  secret: process.env.OAUTH_STATE_SECRET!,
  cookie: { secure: process.env.NODE_ENV === "production" },
  providers: {
    google: google({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      redirectUri: `${origin}/auth/google/callback`,
    }),
    github: github({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
      redirectUri: `${origin}/auth/github/callback`,
    }),
    tiktok: tiktok({
      clientKey: process.env.TIKTOK_CLIENT_KEY!,
      clientSecret: process.env.TIKTOK_CLIENT_SECRET!,
      redirectUri: `${origin}/auth/tiktok/callback`,
    }),
    // Add apple/microsoft/facebook/twitter the same way.
  },
})

const onSocialSuccess = async (c, { profile }) => {
  // Upsert by (provider, providerId); see docs/cookbook.md for the full pattern.
  const user = await upsertUserFromProfile(profile)
  const jwt = await token.sign({ id: user.id }, config.secret, { expiresIn: 86400 })
  return redirect(putHeader(c, "set-cookie", `session=${jwt}; HttpOnly; Path=/`), "/")
}

const socialRoutes = [
  get("/auth/google",           social.start("google")),
  get("/auth/google/callback",  social.callback("google", { onSuccess: onSocialSuccess })),
  get("/auth/github",           social.start("github")),
  get("/auth/github/callback",  social.callback("github", { onSuccess: onSocialSuccess })),
  get("/auth/tiktok",           social.start("tiktok")),
  get("/auth/tiktok/callback",  social.callback("tiktok", { onSuccess: onSocialSuccess })),
  // Apple delivers form_post → use POST + parseForm:
  // post("/auth/apple/callback", pipeline(parseForm)(social.callback("apple", { onSuccess: onSocialSuccess }))),
]
```

Slot `...socialRoutes` into your `serve({ routes: [...] })`. The full provider
matrix and Apple-specific notes live in `docs/cookbook.md`.

### Add Share Buttons

```ts
import { share, shareUrl, shareEmail } from "@atlas/share"
import { createEmailer } from "@atlas/email"

const content = { url: "https://example.com/post/123", title: "Look at this" }

// One channel:
shareUrl("twitter", { ...content, hashtags: ["atlas"] })

// All eight channels at once — render however your UI prefers:
share(content)
// → { twitter, facebook, linkedin, reddit, whatsapp, telegram, sms, email }

// Server-side share-by-email (reuses your @atlas/email transport):
const emailer = createEmailer({ apiKey: process.env.RESEND_API_KEY, from: process.env.RESEND_FROM })
await shareEmail({ emailer, to: "friend@example.com", sharerName: "Wess", content })
```

### Add External API Calls

```ts
import { github } from "@atlas/request/providers"

const gh = github({ token: process.env.GITHUB_TOKEN! })
const repos = await (await gh.get("/user/repos")).json()
```

### Add MCP Debugging

```ts
import { collectTools, createContext, createMcpServer } from "@atlas/mcp"

const ctx = createContext({ db, routes: myRoutes, config })
const mcp = createMcpServer(collectTools(ctx), ctx)
mcp.start()
```

Or launch via the CLI: `atlas mcp`

## Templates

Scaffold a complete project with `atlas init`:

```bash
atlas init -n myapp --template <template>
```

| Template | Description |
|----------|-------------|
| `minimal` | Just server + config |
| `api` | REST API with db, auth, migrations |
| `edge` | App + TLS-terminating edge (replaces Caddy/nginx) |
| `fullstack` | API + React frontend |
| `admin` | API + admin panel |
| `worker` | Background job processor |
| `realtime` | WebSocket + SSE |
| `socialnetwork` | Users, posts, follows, likes, feeds, media, real-time |
| `cms` | Headless CMS with content types, publishing, webhooks |
| `ai` | Chatbot, RAG, agents, embeddings, streaming |

Examples:

```bash
atlas init -n myapi --template api
atlas init -n mysite --template fullstack
atlas init -n mybot --template ai
atlas init -n mysocial --template socialnetwork
```

### Deploy with TLS (no Caddy / nginx)

`@atlas/edge` terminates TLS, automates Let's Encrypt, and reverse-proxies
to your app. The `edge` template ships a complete pattern — a one-line
edge.ts, a Dockerfile, and a compose.yaml that drops the typical caddy
sidecar entirely.

Add it to an existing app:

```ts
// edge.ts
import { LETSENCRYPT_PROD, LETSENCRYPT_STAGING, defineEdge, proxy } from "@atlas/edge"

const isProd = Boolean(process.env.ADMIN_EMAIL)

defineEdge({
  acme: isProd
    ? {
        email: process.env.ADMIN_EMAIL!,
        storage: process.env.CERT_DIR ?? "/var/atlas/edge",
        directoryUrl: process.env.ACME_STAGING ? LETSENCRYPT_STAGING : LETSENCRYPT_PROD,
      }
    : undefined,
  sites: [{
    host: process.env.DOMAIN ?? "localhost",
    compress: ["gzip", "zstd"],
    routes: [{ handler: proxy(`http://localhost:${process.env.APP_PORT ?? 3000}`) }],
  }],
}).listen()
```

In dev (`DOMAIN` unset), the edge auto-detects localhost and runs plain
HTTP on `:8080` — no certs, no sudo. In production, it listens on `:80`
+ `:443`, issues real certs, and renews them automatically 30 days
before expiry.

**First prod boot — use staging once.** Let's Encrypt's prod endpoint has
a 5-failures-per-hostname-per-hour rate limit. Run with `ACME_STAGING=1`
the first time to verify the wiring (browser will show "untrusted
issuer" — that's expected for staging certs), then clear the cert volume
and bring the service back up without `ACME_STAGING`.

## Troubleshooting

**SQLite database locked** — Close other connections or use WAL mode:
```sql
PRAGMA journal_mode=WAL;
```

**Admin panel 404** — Make sure migrations ran successfully:
```ts
const statuses = await migrate.status(db, "./migrations")
console.log(statuses)
```

**S3 upload fails** — Check endpoint and credentials in `.env`. MinIO local: `http://localhost:9000`

**Auth token invalid** — Make sure SECRET is the same in config and token.verify
</document>

<document path="docs/api.md">
# Atlas API Reference

## @atlas/config
```
env(name, opts?) → EnvRef<T>          opts: { parse: (s)=>T, default: string }
defineConfig(schema) → Readonly<T>    resolves all EnvRef values, freezes
```

## @atlas/db
```
from(schema, alias?) → Chainable<RowOf<schema>>   typed Ecto-style chain
from(table: string, alias?) → Chainable<any>      dynamic / cross-table chain
  .select(...keys)         narrows row to Pick<Row, K>
  .where(cb) .join(t, on) .leftJoin(t, on) .innerJoin(t, on)
  .orderBy(col, dir?, nulls?) .groupBy(...cols) .having(cb)
  .limit(n) .offset(n) .distinct(...cols)
  .insert(data) .insertMany(data[]) .update(data) .del() .truncate(cascade?)
  .returning(...keys) .onConflict(spec) .cte(name, sub) .recursiveCte(name, sub)
  .toSql(dialect?) → SqlResult<Selected>
raw(sql, ...values) → Fragment
defineSchema(table, columns) → Schema<T>
column.serial() → number   .text() → string   .integer() → number
  .bigint() → bigint   .real() → number   .boolean() → boolean
  .timestamp() → Date  .json<T>() → T       .uuid() → string
  modifiers: .primaryKey() .unique() .nullable() (widens to T|null)
             .default(val) .defaultRaw(sql) .ref(table, col)
RowOf<typeof schema>                             extract row TS type
changeset(schema, { cast, required?, validate? }) → (data) => ChangesetResult
connect({ driver, path|url, pool? }) → Connection
  Connection: .execute<Row>(q) → Row[]
              .one<Row>(q) → Row | null
              .all<Row>(q) → Row[]
              .transaction(fn) .close()
              row type is inferred from the chain when from(schema) is used
```

## @atlas/migrate
```
migrate.create(dir, name)            creates timestamped up.sql/down.sql
migrate.up(db, dir)                  runs pending migrations
migrate.down(db, dir)                rolls back last migration
migrate.status(db, dir)              lists migration status
migrate.plan(db, schemas) → DiffPlan       compute up/down SQL (read-only)
migrate.diff(db, schemas, { name?, dir? }) → DiffWriteResult
                                     introspect live DB, write a new migration
                                     folder with up/down SQL — { noop: true }
                                     when in sync. Type/nullability mismatches
                                     emit `-- ALTER` comments for review.
```

## @atlas/server
```
createConn(req, params?) → Conn      immutable connection from Request
assign(conn, data) → Conn            merge into conn.assigns
putHeader(conn, key, val) → Conn     add response header
halt(conn, status, body?) → Conn     stop pipeline
setStatus(conn, status) → Conn
pipe(fn) → PipeFn                    type-inference wrapper
pipeline(...pipes)(handler) → PipeFn compose pipes, halt short-circuits
get|post|put|patch|del|head|options(path, handler) → Route
router(...routes) → fetch handler
serve({ port, routes, hostname?, websocket? })
json(conn, status, data) → Conn
text(conn, status, body) → Conn
redirect(conn, location, status?) → Conn
stream(conn, status, readable) → Conn
parseJson | parseForm | parseMultipart   built-in parser pipes
onError(handler) → error pipe
createAdapter(name, start) → ServerAdapter
compose(adapters) → ComposedServer

route(method, path, schemas, handler) → Route        validated, typed route
getR | postR | putR | patchR | delR(path, schemas, handler) → Route
  schemas: { params?, body?, query?, before?, assigns? }
  - params/body/query: Validator<T> = (input) => T  |  { parse(input): T }
    (Zod, plain functions, or any Standard-Schema-shape qualify)
  - before: PipeFn[] (run ahead of validation; e.g., requireAuth)
  - assigns: phantom — `{} as MyClaims` types c.assigns for the handler
  body schema auto-parses JSON; rejects non-application/json content-types.
  validation failures → unprocessable("Invalid <where>", VALIDATION_FAILED)

httpError(status, message, { code?, details?, headers? }) → HttpError
isHttpError(value) → bool                            type guard
haltWith(conn, error) → Conn                         halt with HttpError
notFound | unauthorized | forbidden | badRequest | conflict | gone |
unprocessable | tooManyRequests | methodNotAllowed | internal |
serviceUnavailable(message?, opts?) → HttpError
  router catches `throw httpError(...)` and renders { error, code?, details? }
```

## @atlas/edge
```
defineEdge(config) → { ...config, listen() → Promise<RunningEdge> }
runEdge(config) → Promise<RunningEdge>          { mode: "tls"|"plain", stop() }
proxy(upstream, { preserveHost? }) → EdgeHandler   reverse proxy with X-Forwarded-*
forward(req, options, ctx) → Promise<Response>     low-level proxy primitive
files({ root, index?, stripPrefix? }) → EdgeHandler   static file serving via Bun.file
compressResponse(res, accept, allow) → Response    apply gzip/zstd
matchHost(host, pattern) → bool                    literal or "*.x.com"
matchRoute(req, url, matcher?) → bool              path (regex|string|*) + method
isLocalHost(host) → bool                           localhost / 127.0.0.1 / ::1 / *.localhost

provisionCertificate({ directoryUrl, accountKey, contactEmail, hosts, challenge }) → { certPem, keyPem }
generateKeyPair() → AcmeKeyPair                    ECDSA P-256 via Web Crypto
importKeyPair(jwk) | jwkThumbprint(jwk)
LETSENCRYPT_PROD | LETSENCRYPT_STAGING             directory URLs

issueCert({ directoryUrl, contactEmail, hosts, store, challenge }) → CertRecord
loadOrCreateAccount(store) → AcmeKeyPair
fileStore(root) | memoryStore() → CertStore       .load .save .loadAccountJwk .saveAccountJwk
certKey(hosts) → string                            stable map key for a host list
createRenewalScheduler(onRenew) → { schedule, cancel, stop }
renewAt(record) → number                           unix ms; 30 days before expiry, clamped

EdgeConfig: { acme?, sites: Site[], insecure?, httpPort?, httpsPort? }
Site: { host, routes: Route[], compress?: ("gzip"|"zstd")[] }
Route: { match?: { path?, method? }, handler: (req, ctx) => Promise<Response> }
ForwardContext: { remoteIp, tls, host }
```

## @atlas/server/ws
```
ws(config) → { websocket, rooms, upgrade }
channel(name, handlers) → Channel
createRooms() → { join, leave, leaveAll, broadcast, members }
WsConn<T>: wrapped ws with auto-JSON send
```

## @atlas/server/sse
```
createSseChannel() → { broadcast, pipe, clients }
eventStream(conn, generator) → SSE response
SseClient: { id, send, close }
```

## @atlas/auth
```
hash(password) → Promise<string>           Argon2id via Bun.password
verify(password, hashed) → Promise<bool>
token.sign(payload, secret, opts?) → Promise<string>   opts: { expiresIn: seconds }
token.verify(jwt, secret) → Promise<TokenPayload>
createMemoryStore({ ttl? }) → SessionStore dev/testing session store; ttl seconds expires entries
signup({ db, table, fields, onSuccess }) → PipeFn
login({ db, table, identity, password, onSuccess }) → PipeFn
requireAuth({ secret }) → PipeFn           reads Bearer token, sets conn.assigns.auth
passwordReset({ db, table, secret, transport, expiresIn? }) → PipeFn
```

## @atlas/auth/social
```
socialAuth({ secret, providers, cookie? }) → SocialAuth
  SocialAuth: { providers,
                authorize(name, { scopes?, returnTo?, extraParams? }?) → { url, cookie },
                complete(name, conn) → { provider, tokens, profile, returnTo? },
                start(name, opts?) → PipeFn,                     302s + sets state cookie
                callback(name, { onSuccess, onError? }) → PipeFn  validates state, exchanges code, clears cookie }
Provider factories — each returns a `SocialProvider`:
  google({ clientId, clientSecret, redirectUri, hostedDomain?, prompt? })
  github({ clientId, clientSecret, redirectUri, allowSignup? })
  apple({ clientId, teamId, keyId, privateKey, redirectUri, responseMode? })
    mints ES256 client_secret JWT per exchange; default response_mode=form_post
  microsoft({ clientId, clientSecret, redirectUri, tenant?, prompt? })   tenant defaults to "common"
  facebook({ clientId, clientSecret, redirectUri, apiVersion?, profileFields? })
  twitter({ clientId, clientSecret?, redirectUri, userFields? })          Basic auth for confidential clients
  tiktok({ clientKey, clientSecret, redirectUri, userFields? })           uses `client_key`, comma-joined scopes, id is open_id
SocialProfile: { provider, id, email?, emailVerified?, name?, picture?, username?, raw }
TokenSet: { accessToken, tokenType?, expiresIn?, refreshToken?, idToken?, scope?, raw }
State + PKCE verifier live in a signed, HttpOnly, SameSite=lax cookie
  (`_atlas_oauth_state`, 10 min TTL). Override via cookie: { name?, path?, secure?, sameSite? }.
```

## @atlas/share
```
shareUrl(channel, content) → string           throws on unknown channel or missing url
share(content) → Record<ShareChannel, string> all eight URLs at once
listChannels() → { channel, label }[]         ordered list with display labels
channels                                       readonly ShareChannel[]
ShareChannel = "twitter" | "facebook" | "linkedin" | "reddit" | "whatsapp" | "telegram" | "sms" | "email"
ShareContent: { url, title?, text?, hashtags?, via?, phone?, to?, cc?, bcc? }
  url required; unknown fields ignored per channel.
Provider re-exports (each is a `ShareProvider { channel, label, build }`):
  twitter, facebook, linkedin, reddit, whatsapp, telegram, sms, email
shareEmail({ emailer, to, from?, replyTo?, sharerName?, product?, message?, content, brand?, accent? })
  → Promise<SendResult>                        dispatches a branded HTML email through @atlas/email
renderShareEmailMessage(opts) → { subject, html, text }   pure preview/render
```

## @atlas/email
```
createEmailer({ apiKey?, from? }) → Emailer    auto-picks Resend if both set, else console
createResendEmailer({ apiKey, from }) → Emailer
createConsoleEmailer() → Emailer               dev fallback; logs and returns ok:true
Emailer: { enabled, send(msg) → Promise<SendResult> }
EmailMessage: { to, subject, html, text?, replyTo?, from? }
SendResult: { ok: true, id?, logged? } | { ok: false, error }
inviteEmail(opts) | passwordResetEmail(opts) → { subject, html, text }
layout({ title, body, brand?, footer?, accent? }) → string
escapeHtml(s) → string                          always wrap untrusted input
```

## @atlas/oauth
```
oauthRoutes(cfg, { basePath?, adminBasePath? }) → Route[]   all OAuth endpoints
oauthAuthorizeRoutes(cfg, base) | oauthTokenRoutes | oauthRevokeRoutes
oauthDeviceRoutes | oauthDiscoveryRoutes | oauthClientRoutes(cfg, adminBase)
findClient(db, id) | verifyClientCredentials(db, id, secret)
sweepExpired(cfg) | sweepExpiredAuthCodes | sweepExpiredRefreshTokens | sweepExpiredDeviceCodes(cfg)
helpers: parseScope, formatScope, includesScopes, isAllowedRedirect,
         verifyPkceS256, randomId, shortId, sha256, newUserCode, normalizeUserCode
constants: ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS,
           AUTH_CODE_TTL_SECONDS, DEVICE_CODE_TTL_SECONDS, DEVICE_POLL_INTERVAL_SECONDS
types: OAuthConfig, OAuthUser, ClientRow, AuthCodeRow, RefreshTokenRow,
       DeviceCodeRow, OAuthAuditEvent, RequestContext
```

## @atlas/sso
```
mountSso(cfg: SsoConfig) → readonly Route[]            mount /login + /callback + /backchannel-logout
ensureSsoStateTable(db, table?)                        idempotent CREATE TABLE IF NOT EXISTS
sweepExpiredSsoState(db, table?)                       prune expired state rows (10m TTL)
clearDiscoveryCache()                                  for tests / hot-reload

SsoConfig: { db, issuerUrl, clientId, clientSecret,
             onAuthenticated(db, claims) → { localUserId, displayName? },
             issueSession(conn, user, claims) → Conn,
             redirectUri?, scopes?, basePath?, defaultPostLoginPath?, stateTable?,
             findLocalUserBySub?(db, sub), invalidateSessions?(db, { sub, localUserId }) }
IdTokenClaims: { sub, iss, aud, email?, email_verified?, name?, preferred_username?, picture?, ... }
DiscoveryDoc: { issuer, authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint?, end_session_endpoint? }
```

## @atlas/security
```
withSecurityHeaders(fetch, { dev?, csp?, disableCsp? }) → fetch     HSTS/CSP/COOP/CORP + req.peerIp shim
developmentCsp | productionCsp                                       string CSP presets
decideInline(mime, name, wantInline) → { contentType, disposition }  safe-MIME allowlist for inline
createDbRateLimit({ db }) | createMemoryRateLimit() → RateLimit      .check(bucket, max, windowSec) .reset(bucket) .sweep(olderThanSec)
clientIp(req, { trustedProxies? }) → string                          honors X-Forwarded-For only via trusted proxy
userAgent(req) → string | undefined
parseTrustedProxies(env) → string[]
createAuditLogger({ db }) → { log(event), ... }                      fire-and-forget; never throws
createSessionStore<U>({ db, secret, ttlSeconds }) → SessionStore     DB-backed JWT sessions
  .issue(user, ctx) .isActive(jti) .touch(jti) .revoke(jti, userId) .revokeAll(userId, keep?) .sweepExpired()
newJti() → string
generateSecret() → string                       TOTP base32 secret
totpAt(secret, epochSec) → string               6-digit code at time
verifyTotp(secret, code, { window? }) → bool    window=1 accepts ±30s
otpauthUrl({ secret, account, issuer }) → string
generateBackupCodes(n?) → string[]              store hashed
base32Encode(bytes) | base32Decode(str)
```

## @atlas/storage
```
createStore({ endpoint, bucket, region, accessKey, secretKey }) → Store
upload(store, { key, body, contentType }) → Promise
download(store, key) → Promise<Response>
list(store, prefix?) → Promise<ListResult>
remove(store, key) → Promise
presign(store, key, { expires?, method? }) → string
```

## @atlas/cache
```
createCache({ url }) → Cache               Redis-backed
createMemoryCache() → Cache                 in-memory for dev
cached(cache, prefix, fn, { ttl? }) → cached function
invalidate(cache, prefix, ...args) → Promise
```

## @atlas/request
```
request(url, opts?) → Promise<Response>     opts: { json, headers, method, body, retry, timeout (ms) }
createClient({ baseUrl, headers?, retry?, interceptors?, timeout? }) → Client
  Client: .get .post .put .patch .del .request — all return Promise<Response>
withRetry(fn, { attempts?, delay?, backoff?, retryOn? })
github({ token }) | stripe({ key }) | openai({ key }) | resend({ key })
  preconfigured clients — import from @atlas/request/providers
```

## @atlas/cli
```
cli(name, commands)                  run CLI with command definitions
command(name, { flags?, run })       define a command
flag(short, { type, default? })      define a flag
parseArgs(argv, flags) → ParsedArgs
foreman(procs) | parseProcfile(str)  process manager
initCommand | addCommand | docsCommand   built-in atlas commands
questions | applyDefaults | generateProject   scaffolding

CLI surface:
  atlas init [-y] [-n name]            scaffold a new project
  atlas add <pkg>...                   install @atlas/* packages
  atlas dev                             foreman → Procfile
  atlas mcp                             start MCP server
  atlas docs [<pkg>|<doc>|<root>]      print canonical documentation to stdout
```

## @atlas/ui
```
@atlas/ui/provider:  AtlasProvider, AppShell
@atlas/ui/forms:     createForm, TextField, SelectField, SubmitButton
@atlas/ui/table:     createTable, TextColumn, DateColumn, ActionColumn
@atlas/ui/auth:      LoginPage, SignupPage, ResetPasswordPage
@atlas/ui/storage:   FileUpload, ImagePreview
@atlas/ui/nav:       Sidebar, NavLink, Breadcrumb
@atlas/ui/cache:     CacheInspector, CacheStatus
@atlas/ui/ai:        ChatWindow, MessageBubble, PromptInput, AiSearch, GenerateButton
```

## @atlas/admin
```
admin({ db, models, basePath?, auth? }) → { mount, routes }
model({ schema, listFields?, searchFields?, filterFields?, relations?, actions?, bulkActions?, readOnly? }) → ModelConfig
Components: AdminApp, AdminSidebar, Dashboard, ModelList, Detail, Create, FilterBuilder, QueryBuilder, BulkBar
```

## @atlas/mcp
```
createContext(opts?) → AtlasMcpContext      opts: { db?, cache?, routes?, config?, storage?, migrationsDir?, logBuffer? }
collectTools(ctx) → Tool[]                  tools auto-register from what's in ctx
createMcpServer(tools, ctx) → McpServer
defineTool({ name, description, inputSchema, handler }) → Tool
McpServer: .start() .stop()

Always-on tools (independent of context):
  docs.list                              list package, guide, and root documentation sources
  docs.read({ package?, doc?, root? })   read one canonical source; docs/agents.md is the grounding guide
```

## @atlas/ai
```
createProvider({ provider, key?, baseUrl? }) → AiProvider   provider: "openai"|"anthropic"|"ollama"
createConversation(system?) → Conversation
addMessage(conv, msg) → Conversation
send(provider, conv, content, opts?) → { conversation, response }
userMessage|assistantMessage|systemMessage(content) → Message
toolMessage(toolCallId, content) → Message
chatStream: provider.chatStream(opts) → AsyncIterable
collectStream(stream) → ChatResponse
streamToSse(stream) → ReadableStream
parseSSE(text) → events
embed(provider, input) → number[][]        input: string | string[]
cosineSimilarity(a, b) → number
createVectorStore() → { add, search, size }
generateJson<T>(provider, prompt, opts?) → T
tool(name, desc, parameters) → ToolDef
index(rag, id, text, metadata?) → Promise  rag: { ai, store, topK? }
query(rag, question) → { answer, sources }
runAgent({ ai, system?, tools, maxIterations? }, prompt) → { response, messages, iterations }
withAi(provider) → PipeFn                  adds ai to conn.assigns
```
</document>

<document path="docs/cookbook.md">
# Atlas Cookbook

Short recipes for patterns that don't justify a full package — copy-paste them
into your app, change the table names, and move on.

## Invite tokens

Single-use, unguessable tokens that grant access to one signup. The plaintext
token is shown to the inviter exactly once; only the SHA-256 hash is stored at
rest, so a database leak doesn't compromise unredeemed invites.

**Schema**

```sql
CREATE TABLE invites (
  id          SERIAL PRIMARY KEY,
  token_hash  TEXT UNIQUE NOT NULL,
  email       TEXT NULL,             -- optional: pre-bind to an email
  invited_by  INTEGER NOT NULL,
  used_at     TIMESTAMPTZ NULL,
  used_by     INTEGER NULL,
  created_at  TIMESTAMPTZ DEFAULT NOW()
);
```

**Routes**

```ts
import { from } from "@atlas/db"
import { del, get, json, parseJson, pipeline, post } from "@atlas/server"
import { requireAuth } from "@atlas/auth"
import { randomBytes, createHash } from "node:crypto"

const randomToken = () => randomBytes(32).toString("base64url")
const sha256Hex = (s: string) => createHash("sha256").update(s).digest("hex")

export const inviteRoutes = (db, secret: string) => {
  const guard = pipeline(requireAuth({ secret }))
  const authed = pipeline(requireAuth({ secret }), parseJson)

  return [
    // List my invites — no plaintext tokens, only metadata.
    get("/invites", guard(async (c) => {
      const userId = c.assigns.auth.id
      const rows = await db.execute(
        from("invites")
          .where(q => q("invited_by").equals(userId))
          .select("id", "email", "used_at", "used_by", "created_at")
          .orderBy("created_at", "DESC"),
      )
      return json(c, 200, rows)
    })),

    // Create — plaintext token returned exactly once.
    post("/invites", authed(async (c) => {
      const userId = c.assigns.auth.id
      const { email } = c.body as { email?: string }
      const token = randomToken()
      const rows = await db.execute(
        from("invites")
          .insert({
            token_hash: sha256Hex(token),
            email: email?.toLowerCase() ?? null,
            invited_by: userId,
          })
          .returning("id", "email", "created_at"),
      )
      return json(c, 201, { ...rows[0], token })
    })),

    // Verify a token without consuming it (signup form prefill).
    get("/invites/:token/check", async (c) => {
      const row = await db.one(
        from("invites")
          .where(q => q("token_hash").equals(sha256Hex(c.params.token)))
          .select("email", "used_at"),
      )
      if (!row) return json(c, 404, { valid: false, error: "Invalid invite" })
      if (row.used_at) return json(c, 410, { valid: false, error: "Already used" })
      return json(c, 200, { valid: true, email: row.email })
    }),

    // Revoke an unused invite.
    del("/invites/:id", guard(async (c) => {
      const userId = c.assigns.auth.id
      const id = Number(c.params.id)
      const row = await db.one(
        from("invites")
          .where(q => q("id").equals(id))
          .where(q => q("invited_by").equals(userId)),
      )
      if (!row) return json(c, 404, { error: "Not found" })
      if (row.used_at) return json(c, 409, { error: "Cannot revoke a used invite" })
      await db.execute(from("invites").where(q => q("id").equals(id)).del())
      return json(c, 200, { revoked: id })
    })),
  ]
}
```

**Consuming an invite at signup** is just `UPDATE invites SET used_at = …,
used_by = … WHERE token_hash = … AND used_at IS NULL` inside the same
transaction that inserts the new user. The atomic check prevents double-use.

Pair with `@atlas/email`'s `inviteEmail` template to send the link.

---

## Waitlist

Trivially small — collect email addresses (with optional name + reason) before
launch. Useful as a one-route module.

**Schema**

```sql
CREATE TABLE invite_requests (
  id          SERIAL PRIMARY KEY,
  email       TEXT NOT NULL,
  name        TEXT NULL,
  reason      TEXT NULL,
  created_at  TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX ON invite_requests (email);
```

**Route**

```ts
import { from } from "@atlas/db"
import { json, parseJson, pipeline, post } from "@atlas/server"
import { createDbRateLimit, clientIp } from "@atlas/security"

const isEmail = (s: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)

export const waitlistRoutes = (db) => {
  const open = pipeline(parseJson)
  const limiter = createDbRateLimit({ db })

  return [
    post("/invite-requests", open(async (c) => {
      const { email, name, reason } = c.body as {
        email?: string; name?: string; reason?: string
      }
      const e = (email ?? "").trim().toLowerCase()
      if (!e || !isEmail(e)) return json(c, 422, { error: "Valid email required" })
      if ((reason?.length ?? 0) > 1000) return json(c, 422, { error: "Reason too long" })

      // Optional: rate-limit per IP so a bot can't pile junk entries.
      const { ok } = await limiter.check(`waitlist:${clientIp(c.request)}`, 5, 3600)
      if (!ok) return json(c, 429, { error: "Slow down" })

      await db.execute(
        from("invite_requests").insert({
          email: e,
          name: name?.trim() || null,
          reason: reason?.trim() || null,
        }),
      )
      return json(c, 200, { ok: true })
    })),
  ]
}
```

That's the whole feature. Add an admin list view on top when you're ready to
process the queue.

---

## Search query DSL

A small parser that lets users type `type:image foo bar` or `ext:pdf invoice`
and converts the result into something you can pass to `@atlas/db`. It's about
50 lines and is roughly the same in every app, so keep it inline.

```ts
export type ParsedQuery = {
  name: string
  types: string[]
  exts: string[]
}

const MIME_CLASSES: Record<string, string[]> = {
  image: ["image/%"],
  video: ["video/%"],
  audio: ["audio/%"],
  text:  ["text/%"],
  document: [
    "application/pdf",
    "application/vnd.openxmlformats-officedocument.%",
    "application/msword",
    "application/vnd.ms-excel",
    "application/vnd.ms-powerpoint",
  ],
}

export const mimePatternsFor = (klass: string): string[] =>
  MIME_CLASSES[klass] ?? []

export const escapeLike = (s: string): string =>
  s.replace(/([\\%_])/g, "\\$1")

export const parseQuery = (input: string): ParsedQuery => {
  const tokens = input.trim().split(/\s+/).filter(Boolean)
  const types: string[] = []
  const exts: string[] = []
  const name: string[] = []

  for (const tok of tokens) {
    const colon = tok.indexOf(":")
    if (colon > 0) {
      const key = tok.slice(0, colon).toLowerCase()
      const val = tok.slice(colon + 1).toLowerCase()
      if (!val) continue
      if (key === "type" && MIME_CLASSES[val]) { types.push(val); continue }
      if (key === "ext") { exts.push(val.replace(/^\./, "")); continue }
    }
    name.push(tok)
  }

  return { name: name.join(" "), types, exts }
}
```

**Using it**

```ts
import { from, raw } from "@atlas/db"

const { name, types, exts } = parseQuery(qParam)
const pattern = `%${escapeLike(name)}%`

let q = from("files")
  .where(p => p("user_id").equals(userId))
  .where(p => p("deleted_at").isNull())

if (name) q = q.where(p => p("name").ilike(pattern))

if (types.length > 0) {
  const mimes = types.flatMap(mimePatternsFor)
  q = q.where(p => p.or(...mimes.map(m => p("mime").ilike(m))))
}

if (exts.length > 0) {
  const patterns = exts.map(e => `%.${escapeLike(e)}`)
  q = q.where(p => p.or(...patterns.map(e => p("name").ilike(e))))
}

// Postgres pg_trgm: rank by similarity for free-text matches.
if (name) q = q.orderBy(raw("similarity(name, $1)", name), "DESC")
```

Add new operators (`size:>1mb`, `created:after:2025-01-01`, etc.) by extending
the `colon > 0` branch — the rest of the parser stays the same.

---

## Typed routes with auth + body validation

`@atlas/server` ships a `route()` helper (and `getR / postR / putR / patchR /
delR` shortcuts) that validates `params`, `body`, and `query` *before* your
handler runs and types `c.assigns` from your `before` pipes. JSON body parsing
is automatic when a `body` schema is set — you don't need to add `parseJson` to
`before`. Validation failures throw `unprocessable("Invalid <where>", ...)` so
they render as `422` JSON the same way every other `HttpError` does.

```ts
import { z } from "zod"
import { from, type RowOf } from "@atlas/db"
import { conflict, getR, json, notFound, postR } from "@atlas/server"
import { requireAuth } from "@atlas/auth"
import { posts } from "./schema"

type AuthClaims = { auth: { id: number } }

export const postRoutes = (db, secret: string) => {
  const auth = requireAuth({ secret })

  return [
    // GET /posts/:id  →  one post by id, typed end-to-end.
    getR<{ id: number }, never, Record<string, string>, AuthClaims>(
      "/posts/:id",
      {
        params: z.object({ id: z.coerce.number() }),
        before: [auth],
        assigns: {} as AuthClaims,
      },
      async (c) => {
        type Post = RowOf<typeof posts>
        const post: Post | null = await db.one(
          from(posts).where(q => q("id").equals(c.params.id))
        )
        if (!post) throw notFound("post")
        return json(c, 200, post)
      },
    ),

    // POST /posts  →  validated body; row is typed from the schema.
    postR<Record<string, never>, { content: string }, Record<string, string>, AuthClaims>(
      "/posts",
      {
        body: z.object({ content: z.string().min(1).max(280) }),
        before: [auth],
        assigns: {} as AuthClaims,
      },
      async (c) => {
        const [created] = await db.execute(
          from(posts)
            .insert({ userId: c.assigns.auth.id, content: c.body.content })
            .returning("id", "content"),
        )
        if (!created) throw conflict("could not create post")
        return json(c, 201, created)
      },
    ),
  ]
}
```

The `assigns: {} as AuthClaims` line is a *type-only* phantom — it doesn't run
at runtime; it just tells the handler that whatever ran in `before` populated
`c.assigns` with that shape. Pair it with a guard pipe like `requireAuth` that
actually does the assignment.

---

## Schema-first migrations with `migrate.diff`

`defineSchema()` already encodes your tables. Instead of hand-writing
`up.sql/down.sql`, point `migrate.diff` at the live database and let it emit
the SQL.

```ts
// scripts/diff.ts — run after editing src/schema.ts
import { connect } from "@atlas/db"
import { migrate } from "@atlas/migrate"
import { posts, users, follows, likes } from "../src/schema"

const db = connect({ driver: "postgres", url: process.env.DATABASE_URL! })
const result = await migrate.diff(db, [users, posts, follows, likes], {
  name: process.argv[2] ?? "diff",
  dir: "./migrations",
})

if (result.noop) console.log("schema in sync; nothing to write")
else console.log(`wrote ${result.path} (${result.plan.ops.length} ops)`)

await db.close()
```

```bash
bun scripts/diff.ts add_likes
# →  wrote ./migrations/20260508_add_likes (1 ops)

bun scripts/diff.ts            # idempotent: no-op when in sync
# →  schema in sync; nothing to write
```

**Watch the comments.** Type or nullability changes are emitted as `-- ALTER
table.column …` *comments*, never raw `ALTER` statements. Destructive
migrations need a human's eyes — the diff surfaces them but does not run them.

`migrate.plan(db, schemas)` returns the same `{ ops, up, down }` plan without
writing files; useful for CI checks ("fail if there are pending diffs"):

```ts
const plan = await migrate.plan(db, schemas)
if (plan.ops.length > 0) {
  console.error("schema drift detected:")
  console.error(plan.up)
  process.exit(1)
}
```

---

## Throw-style errors

Routes don't need to thread error responses through `if/else if (...)`. Throw
an `HttpError` and the router renders it as JSON with the right status, code,
and any custom headers.

```ts
import { conflict, getR, json, notFound, tooManyRequests } from "@atlas/server"
import { from } from "@atlas/db"

getR("/users/:id", { params: z.object({ id: z.coerce.number() }) }, async (c) => {
  const user = await db.one(from(users).where(q => q("id").equals(c.params.id)))
  if (!user) throw notFound("user not found")
  return json(c, 200, user)
})

// Custom headers ride along with the response.
postR("/heavy", { body: z.object({ /* … */ }) }, async (c) => {
  const allowed = await rateLimiter.check(`heavy:${c.assigns.auth.id}`, 10, 60)
  if (!allowed.ok) {
    throw tooManyRequests("slow down", {
      code: "RATE_LIMITED",
      headers: { "Retry-After": String(allowed.retryAfterSeconds) },
    })
  }
  // …
})
```

Available factories: `badRequest`, `unauthorized`, `forbidden`, `notFound`,
`methodNotAllowed`, `conflict`, `gone`, `unprocessable`, `tooManyRequests`,
`internal`, `serviceUnavailable`. All accept `(message?, { code?, details?,
headers? })`. Use `haltWith(conn, error)` if you'd rather short-circuit the
pipeline than `throw`.

---

## Social login (Google, GitHub, Apple, Microsoft, Facebook, X, TikTok)

`@atlas/auth/social` is the OAuth-*client* side: the user signs into Google/
GitHub/etc. and your app receives a normalized profile. State + PKCE verifier
ride in an HttpOnly, signed-JWT cookie (`_atlas_oauth_state`, 10-minute TTL)
so the flow stays stateless — no server-side session table required.

Your app still owns the user table. The callback hands you a `SocialProfile`
+ raw `TokenSet`; do whatever upsert/link logic you want, then mint your own
session JWT.

```ts
import { socialAuth, google, github, apple, microsoft, facebook, twitter, tiktok } from "@atlas/auth/social"
import { token, requireAuth } from "@atlas/auth"
import { from } from "@atlas/db"
import { get, post, redirect, putHeader, json, parseForm, pipeline } from "@atlas/server"

const origin = process.env.PUBLIC_ORIGIN!

const social = socialAuth({
  secret: process.env.OAUTH_STATE_SECRET!,
  cookie: { secure: process.env.NODE_ENV === "production" }, // off in HTTP dev
  providers: {
    google:    google({ clientId, clientSecret, redirectUri: `${origin}/auth/google/callback` }),
    github:    github({ clientId, clientSecret, redirectUri: `${origin}/auth/github/callback` }),
    apple:     apple({ clientId, teamId, keyId, privateKey, redirectUri: `${origin}/auth/apple/callback` }),
    microsoft: microsoft({ clientId, clientSecret, redirectUri: `${origin}/auth/microsoft/callback` }),
    facebook:  facebook({ clientId, clientSecret, redirectUri: `${origin}/auth/facebook/callback` }),
    twitter:   twitter({ clientId, redirectUri: `${origin}/auth/twitter/callback` }),
    tiktok:    tiktok({ clientKey, clientSecret, redirectUri: `${origin}/auth/tiktok/callback` }),
  },
})

const upsertFromProfile = async (p: typeof social.providers.google extends never ? never : any) => {
  // Look up by (provider, providerId); fall back to email; create if neither matches.
  const existing = await db.one(
    from("users").where(q => q("provider").equals(p.provider)).where(q => q("providerId").equals(p.id))
  )
  if (existing) return existing
  const [created] = await db.execute(
    from("users").insert({
      provider: p.provider,
      providerId: p.id,
      email: p.email ?? null,
      name: p.name ?? null,
      picture: p.picture ?? null,
    }).returning("id", "email", "name")
  )
  return created
}

export const socialAuthRoutes = [
  // Start: one route per provider. Optional returnTo encodes the post-login destination.
  get("/auth/google",    social.start("google",    { returnTo: "/welcome" })),
  get("/auth/github",    social.start("github",    { returnTo: "/welcome" })),
  get("/auth/microsoft", social.start("microsoft", { returnTo: "/welcome" })),
  get("/auth/facebook",  social.start("facebook",  { returnTo: "/welcome" })),
  get("/auth/twitter",   social.start("twitter",   { returnTo: "/welcome" })),
  get("/auth/tiktok",    social.start("tiktok",    { returnTo: "/welcome" })),
  get("/auth/apple",     social.start("apple",     { returnTo: "/welcome" })),

  // Callback: app issues its own session JWT after upserting the user.
  get("/auth/google/callback", social.callback("google", {
    onSuccess: async (c, { profile, returnTo }) => {
      const user = await upsertFromProfile(profile)
      const jwt = await token.sign({ id: user.id }, process.env.JWT_SECRET!, { expiresIn: 86400 })
      const c2 = putHeader(c, "set-cookie", `session=${jwt}; HttpOnly; Path=/; SameSite=Lax`)
      return redirect(c2, returnTo ?? "/")
    },
    onError: async (c, err) => json(c, 401, { error: err.message }),
  })),
  // …same shape for github / microsoft / facebook / twitter / tiktok …

  // Apple uses response_mode=form_post by default, so its callback arrives as POST
  // with form-encoded code/state in the body. Compose parseForm in front of it:
  post("/auth/apple/callback", pipeline(parseForm)(
    social.callback("apple", { onSuccess: /* same as above */, onError: /* … */ }),
  )),
]
```

### Notes that bite people

- **Apple**: the `privateKey` is the PEM of the `.p8` you downloaded from
  Apple. `mintClientSecret` runs on every exchange — TTL is 15 minutes; no
  caching is needed for normal traffic. The callback is a `POST` because the
  default `response_mode` is `form_post`.
- **GitHub**: if `user:email` scope is granted but the primary email is
  private, the provider falls back to `GET /user/emails` automatically.
- **Facebook**: scopes are comma-joined (not space-joined). The package handles
  that for you, but if you pass `extraParams` keep it in mind.
- **Twitter/X**: public PKCE-only clients leave `clientSecret` undefined.
  Confidential clients pass it; the package switches to HTTP Basic auth on
  the token endpoint automatically. Twitter does not return an email; treat
  the profile email as always `null`.
- **TikTok**: the dashboard calls it `client_key`, not `client_id`. The stable
  user id is `open_id`. Email is never returned.
- **Cookie in HTTPS-only browsers**: `Secure` is on by default. If you're
  running over plain HTTP on something other than `localhost`, pass
  `cookie: { secure: false }` or your browser will silently drop the cookie
  and every callback will fail with "Missing OAuth state cookie".

---

## Sharing a link (Twitter/X, Facebook, LinkedIn, Reddit, WhatsApp, Telegram, SMS, email)

`@atlas/share` builds the URL the user's browser opens to share to each
channel. URL builders are **pure**: no DOM, no fetch — call them on the
server while rendering, or in a React component, doesn't matter.

```ts
import { share, shareUrl, listChannels, shareEmail } from "@atlas/share"

const content = {
  url: "https://example.com/post/123",
  title: "Look at this",
  text: "A short blurb",
  hashtags: ["atlas", "bun"], // twitter
  via: "atlas",                // twitter
}

shareUrl("twitter", content)
// → https://twitter.com/intent/tweet?url=…&text=…&hashtags=atlas%2Cbun&via=atlas

share(content)
// → { twitter, facebook, linkedin, reddit, whatsapp, telegram, sms, email }

// Render a row of "share to X" buttons from the registry:
listChannels()
// → [{ channel: "twitter", label: "X (Twitter)" }, … ]
```

### Server-side share-by-email

Pair with `@atlas/email`. Falls back to the console transport in dev like
every other Atlas email path, so it's safe to wire before configuring a
sending domain.

```ts
import { createEmailer } from "@atlas/email"
import { shareEmail } from "@atlas/share"

const emailer = createEmailer({
  apiKey: process.env.RESEND_API_KEY,
  from: process.env.RESEND_FROM,
})

await shareEmail({
  emailer,
  to: "friend@example.com",
  replyTo: "wess@example.com",   // so replies go to the sharer, not no-reply
  sharerName: "Wess",
  product: "Atlas",
  message: "thought you'd like this",
  content: { url: "https://example.com/post/123", title: "Look at this" },
})
```

Use `renderShareEmailMessage(opts)` if you want to preview the
`{ subject, html, text }` without sending. Untrusted strings are HTML-escaped
automatically; the body is wrapped in `@atlas/email`'s 560px Outlook-safe
card via `layout()`.
</document>

<document path="README.md">
# Atlas

Composable Bun/TypeScript packages for building APIs, full-stack apps, and CLI tools.

[Documentation](https://wess.io/atlas/) · [API reference](https://wess.io/atlas/docs/api/) · [Quick start](https://wess.io/atlas/docs/quickstart/)

## What is Atlas

Atlas is an à la carte set of functional, minimal-dependency packages that snap together like Lego blocks. Pick what you need — config, database, HTTP server, auth, storage — and compose them into your app. Inspired by Elixir's ecosystem, idiomatic to TypeScript and Bun's native APIs.

No framework lock-in. No classes. Just functions and immutable data flowing through pipes.

## Install

```bash
bun add @wess/atlas
```

Every package is a subpath export, so you can import directly:

```ts
import { defineConfig, env } from "@wess/atlas/config"
import { connect } from "@wess/atlas/db"
import { serve, router, get, json } from "@wess/atlas/server"
```

Prefer the `@atlas/<pkg>` spelling used throughout these docs? Map it via
`tsconfig.json` `paths` (bun reads tsconfig paths at runtime):

```json
{
  "compilerOptions": {
    "paths": {
      "@atlas/auth":        ["./node_modules/@wess/atlas/packages/auth/index.ts"],
      "@atlas/auth/social": ["./node_modules/@wess/atlas/packages/auth/social/index.ts"],
      "@atlas/cache":       ["./node_modules/@wess/atlas/packages/cache/index.ts"],
      "@atlas/cli":         ["./node_modules/@wess/atlas/packages/cli/index.ts"],
      "@atlas/config":      ["./node_modules/@wess/atlas/packages/config/index.ts"],
      "@atlas/db":          ["./node_modules/@wess/atlas/packages/db/index.ts"],
      "@atlas/edge":        ["./node_modules/@wess/atlas/packages/edge/index.ts"],
      "@atlas/email":       ["./node_modules/@wess/atlas/packages/email/index.ts"],
      "@atlas/mcp":         ["./node_modules/@wess/atlas/packages/mcp/index.ts"],
      "@atlas/migrate":     ["./node_modules/@wess/atlas/packages/migrate/index.ts"],
      "@atlas/oauth":       ["./node_modules/@wess/atlas/packages/oauth/index.ts"],
      "@atlas/request":     ["./node_modules/@wess/atlas/packages/request/index.ts"],
      "@atlas/request/providers": ["./node_modules/@wess/atlas/packages/request/providers/index.ts"],
      "@atlas/security":    ["./node_modules/@wess/atlas/packages/security/index.ts"],
      "@atlas/server":      ["./node_modules/@wess/atlas/packages/server/index.ts"],
      "@atlas/server/ws":   ["./node_modules/@wess/atlas/packages/server/ws/index.ts"],
      "@atlas/server/sse":  ["./node_modules/@wess/atlas/packages/server/sse/index.ts"],
      "@atlas/share":       ["./node_modules/@wess/atlas/packages/share/index.ts"],
      "@atlas/sso":         ["./node_modules/@wess/atlas/packages/sso/index.ts"],
      "@atlas/storage":     ["./node_modules/@wess/atlas/packages/storage/index.ts"],
      "@atlas/ai":          ["./node_modules/@wess/atlas/packages/ai/index.ts"],
      "@atlas/admin":       ["./node_modules/@wess/atlas/packages/admin/index.ts"],
      "@atlas/ui":          ["./node_modules/@wess/atlas/packages/ui/index.ts"],
      "@atlas/ui/*":        ["./node_modules/@wess/atlas/packages/ui/*/index.tsx"]
    }
  }
}
```

Installing straight from the repo also works (`bun add github:wess/atlas`) and
lands in the same `node_modules/@wess/atlas/` location.

Bump atlas with `bun update @wess/atlas`.

## Packages

| Package | Description | External deps |
|---------|-------------|---|
| `@atlas/config` | Typed environment variables and config resolution | none |
| `@atlas/db` | Query builder, schemas, changesets, drivers (Postgres/SQLite) | `zod` |
| `@atlas/migrate` | Database migration manager | none |
| `@atlas/server` | Bun.serve with Plug-inspired pipe system | none |
| `@atlas/edge` | TLS-terminating reverse proxy with built-in Let's Encrypt | none |
| `@atlas/auth` | Password hashing, JWT, session management, auth flows | none |
| `@atlas/security` | CSP/headers, rate limit, audit log, TOTP, revocable DB-backed sessions | none |
| `@atlas/oauth` | OAuth 2.1 server: PKCE, refresh rotation, device flow, RFC 8414 discovery | none |
| `@atlas/sso` | OIDC relying-party (Sign in with $IdP): discovery, PKCE, state, code exchange, id_token verify | none |
| `@atlas/email` | Provider-agnostic transport (Resend) + invite/reset templates | none |
| `@atlas/share` | Share-URL builders (socials, messengers, mailto) + server-side share-by-email | none |
| `@atlas/storage` | S3-compatible object storage with presigned URLs | none |
| `@atlas/cache` | Redis-backed caching with TTL and cache-aside patterns | none |
| `@atlas/request` | HTTP client with retries, interceptors, provider configs | none |
| `@atlas/cli` | CLI framework and Foreman process manager | none |
| `@atlas/ui` | React + Mantine frontend blocks (forms, tables, auth UI) | `react`, `@mantine/*`, `@tanstack/*` |
| `@atlas/admin` | Django-style auto-generated admin panel | `react`, `@mantine/*`, `@tanstack/*` |
| `@atlas/mcp` | MCP server for AI/LLM debugging and introspection | none |
| `@atlas/ai` | AI providers, chat, embeddings, RAG, agents, streaming | none |

## Quick Start

Build a user API with authentication in 60 lines.

```bash
mkdir myapp && cd myapp
bun init -y
bun add @wess/atlas
```

The example below uses the `@atlas/<pkg>` aliases from the Install section.

Create `.env`:
```
DATABASE_URL="sqlite:./app.db"
PORT=3000
SECRET="your-secret-key-here"
```

Create `schema.ts`:
```ts
import { defineSchema, column } from "@atlas/db"

export const users = defineSchema("users", {
  id: column.serial().primaryKey(),
  email: column.text().unique(),
  passwordHash: column.text(),
  createdAt: column.timestamp().defaultRaw("CURRENT_TIMESTAMP"),
})
```

Create `server.ts`:
```ts
import { defineConfig, env } from "@atlas/config"
import { connect } from "@atlas/db"
import { migrate } from "@atlas/migrate"
import { serve, router, pipeline, parseJson, json, get, post } from "@atlas/server"
import { signup, login, requireAuth, token } from "@atlas/auth"

const config = defineConfig({
  database: env("DATABASE_URL"),
  port: env("PORT", { parse: Number, default: "3000" }),
  secret: env("SECRET"),
})

const db = connect({ driver: "sqlite", path: "./app.db" })
await migrate.up(db, "./migrations")

const api = pipeline(parseJson)

serve({
  port: config.port,
  routes: [
    post("/signup", api(
      signup({
        db,
        table: "users",
        fields: ["email", "password"],
        onSuccess: (c, user) => json(c, 201, { id: user.id, email: user.email }),
      })
    )),
    post("/login", api(
      login({
        db,
        table: "users",
        identity: "email",
        password: "password",
        onSuccess: async (c, user) =>
          json(c, 200, { token: await token.sign({ id: user.id }, config.secret) }),
      })
    )),
    get("/me", pipeline(requireAuth({ secret: config.secret }))(
      (c) => json(c, 200, { id: c.assigns.auth.id })
    )),
  ],
})
```

Run it:
```bash
bun server.ts
```

## Templates

Scaffold a new project with `atlas init --template <name>`:

| Template | Description |
|----------|-------------|
| `minimal` | Just server + config |
| `api` | REST API with db, auth, migrations |
| `edge` | App + TLS-terminating edge (replaces Caddy/nginx) |
| `fullstack` | API + React frontend |
| `admin` | API + admin panel |
| `worker` | Background job processor |
| `realtime` | WebSocket + SSE |
| `socialnetwork` | Users, posts, follows, likes, feeds, media, real-time |
| `cms` | Headless CMS with content types, publishing, webhooks |
| `ai` | Chatbot, RAG, agents, embeddings, streaming |

## Development

```bash
bun install
bun test
bun run lint
```

## For agents

Atlas exposes one canonical documentation set through four transports:

- [`llms.txt`](https://wess.io/atlas/llms.txt) — concise, specification-shaped discovery index.
- [`llms-full.txt`](https://wess.io/atlas/llms-full.txt) — the complete guide and package corpus.
- [Agent guide](https://wess.io/atlas/docs/agents/) — grounding order, imports, package selection, MCP safety, and context budgets.
- `packages/<name>/AGENTS.md` — canonical per-package APIs, also published as page-level Markdown.

Read them from the repository or installed package, run `atlas docs <name>`, or connect to
`atlas mcp` and call `docs.list` / `docs.read`. Every documentation page advertises its
Markdown alternate and the covering `llms.txt` index.

## Philosophy

- **Functional** — no classes, immutable data, composition over inheritance
- **Minimal deps** — wrap Bun's native APIs, not external packages
- **Composable** — each package works independently or with others
- **AI-friendly** — clear APIs, good types, predictable patterns
- **No framework lock-in** — use what you need, combine with anything else
- **Bun-native** — idiomatic to Bun's APIs and philosophy

## License

MIT

♥ [Sponsor this project](https://github.com/sponsors/wess)
</document>

<document path="../desktop/docs/architecture.md">
# Architecture

The shape every Atlas Desktop app has, and why the boundaries sit where they do.

## The layers

A Cargo workspace, bottom-up. Each crate depends only on those below it.

```
model      the domain types, pure serde                          no gpui
store      JSON under ~/.<app>/ + the OS keychain                no gpui
<domain>   whatever the app does — a client, a parser, an engine no gpui
host       the async service facade the UI calls                 no gpui
app        the gpui application                                  gpui
```

The line that matters is the last one. **Nothing below `app` imports gpui.**

That is not tidiness. It means the app's behavior — every rule about what a
valid project is, what a failed connection does, how a document is written — can
be tested without opening a window, on a headless CI runner, in milliseconds. It
also means the part of the codebase most likely to outlive the UI framework does
not depend on it.

The cost is real and small: values cross the boundary as plain data, and the
`app` crate translates. That translation is where `Load<T>` and the bridge live.

## The seam

Everything asynchronous crosses at one place:

```rust
bridge::run(cx, async move { host.items().await }, move |result, cx| {
    items.set(cx, result.into());
});
```

`run` puts the future on the process-wide tokio runtime and delivers the result
to the gpui main thread. There is exactly one runtime, and one place to look
when a result never arrives.

The handoff is a `futures` oneshot rather than a tokio one because the receiving
half is awaited on gpui's executor, which is not a tokio context.

`stream` is the same shape for a producer that yields many items — logs, tokens,
an event firehose. Cancellation is implicit: when the view goes away the
receiver drops, the producer's `send` starts failing, and it stops. There is no
abort registry to keep in sync.

## State

Two kinds, and the difference is lifetime.

**App state** is provided as context by the root and lives for the whole
process: the route, the settings, the toasts, whatever list the app is about.

**Scoped state** is provided by the view that owns a scope and dies with it. In
the `workspace` template that is `WorkspaceState` — the open project's entries,
selection, and active tab. The root drops the workspace entity when the route
returns home, so nothing from a closed project can leak into the next one, and
no in-flight load can land in a view that has moved on.

Both are built from `Signal<T>`. A view `watch`es the signals it reads, so a
change repaints the views that depend on it and only those.

### `Load<T>`

```rust
pub enum Load<T> { Loading, Ready(T), Failed(String) }
```

`Option<Vec<T>>` collapses two states that need different screens: a list that
failed and a list that has not arrived both read as `None`, so the view renders
a spinner over an error. And `Some(vec![])` looks like a still-loading fetch to
an `.is_empty()` check, so an empty table spins forever.

Three states, three screens. `Result` converts into it, so no view writes the
match itself.

## The store

Plain JSON documents under `~/.<slug>/`, one per thing, plus the OS keychain for
secrets. Not a database — these are files a user can open, diff, and fix by
hand, which is worth more than any query the app would have run.

Two behaviors are load-bearing:

- **Writes rename into place.** The temporary file is in the same directory, so
  the rename is atomic; a crash mid-write leaves the previous document intact
  rather than a truncated one. A settings file that lost the last change is a
  shrug. One that will not load is a support ticket.
- **A corrupt document is backed up, not deleted.** It may be the only copy of
  something the user typed. An unexplained extra file beats silent data loss.

`<SLUG>_DIR` relocates the root, which is how tests get a scratch directory
without stubbing the filesystem — and how you try a change against a clean
profile without losing yours.

Secrets go to the keychain, never into the JSON. The values are written as
single-line JSON because **the macOS keychain hex-encodes a value containing a
newline**, which silently corrupts it on read.

## The chrome

`atlas-shell` is everything that draws and is not the product:

- **`theme`** — a `Scheme` (neutral ramp, accent, radius, font) built into a
  guise `Theme`, plus the resolved `Palette` views read surfaces from. Reading
  every visual from here is what makes light/dark switching free.
- **`menu`** — `Chrome` builds the Application/Edit/View/Help menus, installs
  their keybindings, and handles the four actions that belong to the OS. What is
  left for the app is what is actually its own.
- **`window`** — `MainWindow`, with the defaults every app converged on.
- **`sheet`** — a modal that dropdowns can live inside. See
  [gotchas](gotchas.md).
- **`toasts`** — one severity vocabulary, so an error is not teal in one view
  and red in the next.
- **`nav`** — the collapsing rail.
- **`about`** — guise's card, filled from the build stamp.
- **`update`** — guise's self-update, told which repository and which Developer
  ID.
- **`focus`** — the window's fallback focus. See [gotchas](gotchas.md).

## The build stamp

`atlas-build::stamp("HOPPER")` emits two things a binary cannot work out at
runtime: the day it was built, and whether it is *the* build of its version or
just a checkout carrying that number. Only the release workflow sets
`HOPPER_RELEASE=1`.

Printing "Released 2026-08-21" on a developer's local build is a small lie that
costs a bug report.
</document>

<document path="../desktop/docs/scaffolding.md">
# Scaffolding

## Starting an app

```sh
scripts/new.sh <Name> <target-dir> [options]
```

| option | default | what it sets |
|---|---|---|
| `--template` | `sidebar` | `minimal`, `sidebar`, or `workspace` |
| `--slug` | the name, lowercased | the binary, `~/.<slug>`, the `.deb`, the icon file |
| `--id` | `io.wess.<slug>` | the macOS bundle identifier |
| `--repo` | `wess/<slug>` | where releases are published and the updater looks |
| `--desc` | a placeholder | one line, used in six manifests |
| `--vendor` | `Wess Cope` | the copyright holder and package author |
| `--email` | `opensource@wess.io` | the Cargo author and Debian maintainer |
| `--accent` | `#4C6EF5` | the placeholder icon's colour |
| `--atlas` | `git` | `git` for a normal app, `path` to work on Atlas alongside it |

It assembles the template, `templates/shared`, the packaging scripts, the
manifests and the workflows into one directory, rewrites every placeholder,
generates an icon, and makes the first commit.

The slug is stripped to lowercase letters and digits, because anything else
breaks a cargo bin name, a Debian package name, or a keychain service — better
here than three minutes into a release.

The MSI `UpgradeCode` is generated once, at scaffold time, and **must never
change**: it is what tells Windows that version 2 replaces version 1 rather than
installing beside it.

## The templates

### `minimal`

`model` + `store` + `app`. One window, settings, About, self-update. No async
layer at all.

Start here unless you already know you need more. Its `AGENTS.md` says what to
add when it outgrows itself, and each of those additions is one of the other two
templates.

### `sidebar`

`model` + `store` + `host` + `app`. A collapsing nav rail, routed views, an
async host reached through the bridge, `Load<T>` in the views. The Hopper shape.

This is the one to read to understand how the pieces fit.

### `workspace`

`model` + `store` + `host` + `app`, with two state scopes: a home screen listing
projects, and a workspace — sidebar plus tabbed pane — for whichever one is
open. The Tables shape.

Take it when the app *opens* something: a database, a repository, a document.
The per-project state contract is the part worth having.

## Renaming an app

`packaging/app.env` holds every name the app is known by. bash sources it,
PowerShell parses it, and the release workflow loads it into `$GITHUB_ENV` — so
a rename is one edit there plus:

- the `[[bin]]` name and `[package.metadata.deb]` block in `crates/app/Cargo.toml`
- the strings in `crates/app/src/main.rs`, `update.rs`, and `store`'s
  `Store::new`
- `atlasbuild::stamp` in `crates/app/build.rs`

Nothing else hardcodes a name. Anything that does is a bug — that is what
`app.env` is for.

## Developing Atlas and an app together

```sh
scripts/new.sh Acme ~/Dev/acme --atlas path
```

The app's `Cargo.toml` then points at this checkout, so a change here is visible
in the app on the next build. Switch it to the git dependency before publishing.

The three templates work the same way against `crates/` and are compiled in
place, which is the regression test for this library: **a change to a crate here
is verified by building all three templates.**
</document>

<document path="../desktop/docs/packaging.md">
# Packaging

Every artifact an app ships, and where it comes from.

`packaging/app.env` is the single source of naming truth. Every script below
sources or parses it, and so does the release workflow.

## macOS

```sh
scripts/bundle.sh     # dist/<Name>.app, signed
scripts/dmg.sh        # dist/<Name>.dmg, with an /Applications symlink
```

`bundle.sh` builds `-p app` in release, assembles the bundle, writes the
`Info.plist` from `app.env` and the workspace version, and codesigns
inside-out — the executable first, then the bundle.

Signing is controlled by `CODESIGN_IDENTITY`:

- **unset or `-`** — an ad-hoc signature. The app runs on the machine that built
  it and nowhere else. Fine for local work.
- **a Developer ID** — adds `--options runtime --timestamp`, which is what makes
  the build notarizable, and what the in-app updater verifies before it installs
  anything.

`assets/entitlements.plist` is not optional. gpui renders through Metal and JITs
its shaders, so a hardened-runtime build without `allow-jit` notarizes cleanly
and then **crashes on first paint**.

### The icon

`scripts/icon.sh` renders the 1024px master with `scripts/icon.swift`, builds
the `.iconset`, compiles `assets/icon.icns`, and writes the 512px downscale
Linux packaging needs. macOS only.

The generated icon is a placeholder — the app's first letter on a gradient
squircle in the accent from `app.env` — so a new app is recognisably its own
from the first build. Replace `icon.swift` with the real artwork; nothing else
cares where the master PNG came from.

## Linux

```sh
scripts/linux.sh [x86_64|aarch64]
```

Produces all three of `.tar.gz`, `.deb` (via `cargo deb`) and `.AppImage` (via
`linuxdeploy` + `appimagetool`) in `dist/linux`.

It **does not cross-compile**. The architecture argument only labels the
artifacts and picks the right helper downloads, so run it on the machine whose
architecture you want — which is what the release workflow's matrix does.

Two things that look arbitrary and are not:

- The AppImage gets the **512px** icon, not the 1024px master: `linuxdeploy`
  rejects anything but a standard icon size.
- `APPIMAGE_EXTRACT_AND_RUN=1` is set because CI runners usually lack FUSE, and
  the helpers are themselves AppImages.

System dependencies for a gpui build: `clang`, `libasound2-dev`,
`libfontconfig-dev`, `libssl-dev`, `libvulkan1`, `libwayland-dev`,
`libx11-xcb-dev`, `libxkbcommon-x11-dev`, plus `curl` and `file`.

## Windows

```sh
pwsh scripts/windows.ps1 [-Arch x86_64]
```

A portable `.zip` and a WiX v4 `.msi`. The MSI is best-effort: a WiX failure
warns and leaves the zip, because a release that ships nothing is worse than one
that ships only the portable build. The script exits 0 in that case on purpose —
a cargo failure would have thrown much earlier.

Windows builds are **unsigned** until an Authenticode certificate is wired in;
expect a SmartScreen "unknown publisher" prompt. To sign, add the certificate as
a CI secret and a `signtool sign` step after `wix build`. An EV certificate is
what actually clears SmartScreen reputation.

### Package managers

Both manifests point at the release `.zip` and carry placeholder versions and
checksums in git:

- **Scoop** (`packaging/scoop/app.json`) — the workflow rewrites the version,
  URL, `extract_dir` and SHA-256 and commits it back.
- **Chocolatey** (`packaging/chocolatey/`) — the workflow rewrites the version
  and checksum, runs `choco pack`, and uploads the `.nupkg` to the release.
  Pushing to the community feed passes moderation and is deliberately not
  automated.

## Homebrew

The release workflow writes a cask into `wess/homebrew-packages` pointing at the
published DMG. It needs `HOMEBREW_TAP_TOKEN` in the app's repository secrets.

It waits for the DMG to appear before hashing it: a GitHub release is published
*before* CI finishes uploading to it, so the asset can 404 for a few minutes.
</document>

<document path="../desktop/docs/release.md">
# Releasing

## Cutting one

Bump `version` in the workspace `Cargo.toml`, write the matching section in
`CHANGELOG.md`, and push to `main`.

That is the release. The workflow tags it, publishes the notes from the
changelog, and builds every artifact.

Run the gate first — `cargo test`, `cargo clippy --all-targets`, and a release
build — because the version bump *is* the trigger and there is no draft step to
catch a failure behind.

### Why the changelog and not generated notes

Release notes generated from commit subjects say what was touched. The changelog
says what changed for the person installing it. `scripts/notes.sh` extracts the
section for a version and exits non-zero when there is none, so the workflow can
fall back to generated notes with a warning rather than publishing an empty
release body.

## What the workflow does

| job | output |
|---|---|
| `check-version` | reads `app.env` and the version; skips if the tag exists |
| `create-release` | tags, publishes the release with the changelog section |
| `macos` | `.app` → notarize → `.dmg` → notarize → checksum → upload |
| `linux` | x86_64 and aarch64 matrix: `.tar.gz`, `.deb`, `.AppImage`, checksums |
| `windows` | `.zip`, `.msi`, `.nupkg` |
| `homebrew` | rewrites the cask in `wess/homebrew-packages` |
| `scoop` | rewrites `packaging/scoop/app.json` and commits it back |

`check-version` decides by asking whether the tag already exists, not by
diffing `HEAD~1`. A diff would miss a manual dispatch and a re-released version;
this is idempotent for both.

The Scoop job retries its push with a rebase up to five times. It runs after the
Windows build, by which point `main` has often moved — the release commit is
rarely the last one pushed — and a plain push is rejected non-fast-forward,
silently missing the release. The manifest is the only file it touches, so a
rebase has nothing to conflict with.

## Signing and notarization

Signing credentials are **optional**. Without them every job still runs and
produces ad-hoc-signed artifacts, with a warning in the log. That keeps a fork
building.

With them, the macOS job imports the Developer ID into a temporary keychain
(wiped when the job ends), signs with a hardened runtime and a timestamp, and
notarizes and staples both the `.app` and the `.dmg`.

Repository secrets:

| secret | what it is |
|---|---|
| `APPLE_SIGNING_IDENTITY` | the identity string, e.g. `Developer ID Application: … (TEAMID)` |
| `APPLE_CERT_P12` | the exported certificate, base64 |
| `APPLE_CERT_PASSWORD` | its export password |
| `KEYCHAIN_PASSWORD` | any value; it protects the temporary keychain |
| `APPLE_ID` / `APPLE_APP_PASSWORD` / `APPLE_TEAM_ID` | notarytool credentials |
| `HOMEBREW_TAP_TOKEN` | write access to the tap repository |

### Verifying it actually notarized

A signed-but-not-notarized build looks identical until someone else downloads
it. Check the staple, not just the signature:

```sh
xcrun stapler validate dist/<Name>.dmg
spctl -a -vvv -t install dist/<Name>.dmg
codesign --verify --strict --verbose=2 dist/<Name>.app
```

`spctl` should say `accepted` and `source=Notarized Developer ID`.

## Self-update

Set the Developer ID team in `crates/app/src/update.rs`:

```rust
Update::github("Acme", env!("CARGO_PKG_VERSION"), "wess/acme").team_id("XXXXXXXXXX")
```

Without it guise refuses to execute a downloaded bundle and opens the release
page instead — so an app that ships notarized builds and leaves this off has
quietly lost its own update path.

The install is **in place**: on macOS the DMG is mounted and rsynced onto the
installed `.app`, so the bundle's path and inode never change and
LaunchServices' registration stays valid. On Linux the new AppImage is renamed
over the running one. Everything else (a distro package, a dev build, Windows)
opens the release page.

A release is only offered once it has published the asset *this* machine would
install. Release hosts publish before CI uploads, so a newer tag can be visible
for the length of a notarization run with nothing usable on it; prompting in
that window yields an Update button that can only fail.
</document>

<document path="../desktop/docs/gotchas.md">
# Gotchas

Things that look like bugs and are not, each with the symptom that led to it.
Every one of these cost someone an afternoon at least once.

## The menu bar is greyed out and its shortcuts do nothing

**gpui dispatches an action along the focus path.** An action handled on an
element is unreachable while nothing in the window is focused — so the menu item
bound to it renders disabled, and its shortcut is swallowed.

It reads as a broken menu bar. It is a focus problem.

```rust
// Root::new
let focus = cx.focus_handle();

// Root::render
atlasshell::focus::claim(window, cx, &self.focus);
div().track_focus(&self.focus).on_action(cx.listener(…))
```

`claim` is safe to call every frame — it does nothing once something else has
focus, so a text field the user clicked keeps the caret.

## "cannot call defer_draw during deferred drawing"

guise's `Modal` is a gpui `deferred` element, and so is a `Select`'s dropdown.
gpui forbids calling `defer_draw` while already inside a deferred draw, so a
`Select` opened inside a `Modal` aborts the frame.

Use `atlasshell::Sheet` for any overlay that might contain a dropdown. It paints
inline — an absolutely-positioned scrim sized to the viewport, drawn last — so
anything inside it defers at the top level and never nests.

## A theme read that will not compile

`theme(cx)` borrows `cx` immutably; `cx.listener(…)` needs it mutably. Reading a
colour *after* building a listener overlaps the borrows, and the error does not
say that.

Resolve every theme value into a local at the top of `render`, before the first
listener. Closures stored on elements must be `'static`, so they need the
resolved `Hsla`/`f32`, not a `&Theme` borrow, anyway.

## A window that never repaints

**A gpui window that has never been focused keeps painting its first frame.**
Background work completes and signals update, but nothing repaints — so a
screenshot taken from a script shows a stale UI and the app looks broken.

Focus the window before you trust what it is showing.

## The store test that passes and writes to your home directory

A test that spells out the override variable by hand:

```rust
std::env::set_var("HOPPR_DIR", &dir);   // typo
```

…does not fail. `Store::new` falls back to `~/.hopper`, the round-trip passes,
and the test has quietly written into the user's real state. Ask for the name:

```rust
std::env::set_var(Paths::new("hopper").env_var(), &dir);
```

Environment variables are also process-global, so two tests sharing one race —
the loser reads the winner's scratch directory after it has been deleted. Give
each test its own slug.

## A keychain value that comes back mangled on macOS

**The macOS keychain returns a value containing a newline hex-encoded**, which
silently corrupts it on read. `atlasstore::Keychain::put_json` writes single-line
JSON and asserts it in debug builds for exactly this reason.

## A delete button that also opens the thing

A click on a control inside a clickable card reaches the card too. Call
`cx.stop_propagation()` in the inner handler, or the row's own click fires on the
item that was just deleted.

## An app that notarizes cleanly and crashes on first paint

gpui renders through Metal and JITs its shaders. Under a hardened runtime that
needs `com.apple.security.cs.allow-jit`,
`allow-unsigned-executable-memory`, and `disable-library-validation` — the three
entries in `assets/entitlements.plist`.

Nothing warns you. The build signs, notarizes, staples, and dies on launch.

## An update prompt whose button can only fail

A release host publishes the release *before* CI uploads assets to it, so a
newer tag can be visible for the length of a notarization run with nothing on it
this machine can install. guise's `Release::ready_for` gates on the asset for
this OS *and* architecture actually being present, which is what stops the
prompt appearing in that window.

## A settings file that loses every preference after an upgrade

A settings struct without `#[serde(default)]` **on the container** fails to
parse a document written before a field was added — and the whole document is
lost, not just the missing key.

```rust
#[serde(rename_all = "camelCase", default)]
pub struct Settings { … }
```

## An empty list that spins forever

`Option<Vec<T>>` cannot tell "not loaded" from "loaded and empty" from "failed".
A view checking `.is_empty()` renders a spinner over an error, and an empty
table never stops loading. Use `atlascore::Load<T>`.
</document>

<document path="packages/config/AGENTS.md">
# @atlas/config

Typed environment variable access and config resolution for Bun apps.

## Exports

- `env(name, opts?)` → `EnvRef<T>` — reference to an env var, resolved lazily
  - `opts.parse`: `(string) => T` — transform the raw string
  - `opts.default`: `string` — fallback if var is missing
- `defineConfig(schema)` → `Readonly<ResolvedSchema>` — resolve all env refs into a frozen config object

## Types

- `EnvRef<T>` — `{ read: () => T }` — lazy reference to an env var
- `ResolveConfig<T>` — recursively resolves EnvRef values in a config schema

## Usage

```ts
import { defineConfig, env } from "@atlas/config"

const config = defineConfig({
  database: {
    url: env("DATABASE_URL"),
    pool: env("DB_POOL_SIZE", { parse: Number, default: "5" }),
  },
  http: {
    port: env("PORT", { parse: Number, default: "3000" }),
  },
})

// config.database.url → string
// config.http.port → number
```

## Depends on

Nothing. Zero dependencies.
</document>

<document path="packages/db/AGENTS.md">
# @atlas/db

Functional query builder, schema definitions, changesets, and database drivers for Postgres and SQLite.

## Exports

### Query Builder
- `from(table: string | Schema, alias?: string) => Chainable` - entry point for all queries
- `raw(sql: string, ...values: any[]) => Fragment` - raw SQL fragment with bind values
- `isFragment(value: unknown) => boolean` - type guard for Fragment
- `createWhereBuilder() => WhereBuilder` - standalone predicate builder

### Chainable Methods
Select: `.select(...cols)`, `.distinct(...cols)`, `.where(cb)`, `.join(t, on, alias?)`,
`.leftJoin(t, on, alias?)`, `.innerJoin(t, on, alias?)`, `.orderBy(col, dir?, nulls?)`,
`.groupBy(...cols)`, `.having(cb)`, `.limit(n)`, `.offset(n)`, `.returning(...cols)`

Mutate: `.insert(data)`, `.insertMany(data[])`, `.insertFrom(cols, source)`,
`.update(data)`, `.del()`, `.truncate(cascade?)`

Advanced: `.onConflict(spec)`, `.cte(name, sub)`, `.recursiveCte(name, sub)`

Terminal: `.toSql(dialect?) => SqlResult`, `.toQuery() => Query`

### Schema
- `defineSchema(table: string, columns: T) => Schema<T>` - define a table schema
- `column.serial()` → `number`, `.text()` → `string`, `.integer()` → `number`,
  `.bigint()` → `bigint`, `.real()` → `number`, `.boolean()` → `boolean`,
  `.timestamp()` → `Date`, `.json<T>()` → `T`, `.uuid()` → `string`
- Column modifiers: `.primaryKey()`, `.unique()`, `.nullable()` (widens to `T | null`),
  `.default(val)` (JS value), `.defaultRaw(sql)` (SQL expression, e.g. `"now()"`, emitted
  into DDL generated by `migrate.diff`), `.ref(table, col)`
- `RowOf<typeof schema>` extracts the row TypeScript type; nullable columns become `T | null`.

### Changeset
- `changeset(schema, opts: { cast, required?, validate? }) => (data) => ChangesetResult`

### Drivers
- `connect(opts: ConnectOptions) => Connection`
  - sqlite: `{ driver: "sqlite", path: string }`
  - postgres: `{ driver: "postgres", url: string, pool?: number }`

## Key Types

```ts
type Dialect = "postgres" | "sqlite"
type SqlResult = { text: string, values: readonly any[] }
type Schema<T> = { table: string, columns: T }
type Connection = { dialect: Dialect, execute(q: SqlResult): Promise<any[]>,
  one(q: SqlResult): Promise<any>, all(q: SqlResult): Promise<any[]>,
  transaction<T>(fn: (conn: Connection) => Promise<T>): Promise<T>, close(): Promise<void> }
type ChangesetResult<T> = { valid: boolean, changes: Partial<T>,
  errors: Record<string, string[]> }
```

## Usage

```ts
import { connect, defineSchema, column, from, changeset, type RowOf } from "@atlas/db"
import { z } from "zod"

// 1. define schema — column types thread through to the row type.
const users = defineSchema("users", {
  id: column.serial().primaryKey(),         // number
  name: column.text(),                       // string
  email: column.text().unique(),             // string
  bio: column.text().nullable(),             // string | null
})

type User = RowOf<typeof users>
// { id: number; name: string; email: string; bio: string | null }

// 2. connect
const db = connect({ driver: "sqlite", path: ":memory:" })

// 3. build & run queries — return types are inferred end-to-end.
await db.execute(from(users).insert({ name: "Ada", email: "ada@example.com" }))

const rows: User[] = await db.all(from(users))                 // User[]
const trimmed = await db.all(from(users).select("id", "name")) // { id: number; name: string }[]
const one = await db.one(from(users).where(q => q("id").equals(1))) // User | null

// `from(string)` still works for dynamic / cross-table queries; rows stay `any`.
const adminRows = await db.all<{ id: number }>(from("users").select("id"))

// 4. validate input
const validate = changeset(users, {
  cast: ["name", "email"] as const,
  required: ["name", "email"] as const,
  validate: { email: z.string().email() },
})
const result = validate({ name: "", email: "bad" })
// result.valid === false, result.errors contains field errors
```

## Where Callback

```ts
from("users").where(q => q("age").greaterThan(18))
from("users").where(q => q.or(q("role").equals("admin"), q("role").equals("mod")))
from("users").where(q => q.raw(raw("active = $1", true)))
```

## Dependencies

Sibling: none. External: `zod` (changeset validation). Runtime: `Bun.sql` (postgres), `bun:sqlite`.
</document>

<document path="packages/server/AGENTS.md">
# @atlas/server

Bun.serve wrapper with an Elixir Plug-inspired pipe system.

## Exports

### Conn (`conn/index.ts`)
- `Conn` — immutable connection type carrying request/response state
- `createConn(req, params?)` — create Conn from a Request
- `assign(conn, data)` — merge data into conn.assigns
- `putHeader(conn, key, value)` — add a response header
- `halt(conn, status, body?)` — stop pipeline, set status
- `setStatus(conn, status)` — set response status

### Pipe (`pipe/index.ts`)
- `PipeFn` — type: `(conn: Conn) => Conn | Promise<Conn>`
- `pipe(fn)` — identity wrapper for type inference
- `pipeline(...pipes)(handler)` — compose pipes, short-circuits on halt

### Router (`router/index.ts`)
- `Route` — type: `{ method, pattern, handler }`
- `get(path, handler)` — create GET route
- `post(path, handler)` — create POST route
- `put(path, handler)` — create PUT route
- `patch(path, handler)` — create PATCH route
- `del(path, handler)` — create DELETE route
- `head(path, handler)` — create HEAD route
- `options(path, handler)` — create OPTIONS route
- `router(...routes)` — create fetch handler from Route objects
- `serve(options)` — start Bun.serve with routes, port, hostname, websocket

### Typed routes (`route/index.ts`)
- `route(method, path, schemas, handler)` — Route with validated, typed input
- `getR | postR | putR | patchR | delR` — method-specific shortcuts
- `Validator<T>` — `(input: unknown) => T` *or* `{ parse(input): T }` (Zod-compatible)
- `RouteSchemas<P, B, Q, A>` — `{ params?, body?, query?, before?, assigns? }`
- `TypedConn<P, B, Q, A>` — `Conn` with narrowed `params`, `body`, `query`, `assigns`

```ts
import { getR, postR, pipeline } from "@atlas/server"
import { requireAuth } from "@atlas/auth"

postR(
  "/users/:groupId",
  {
    params: z.object({ groupId: z.coerce.number() }),
    body: z.object({ email: z.string().email(), name: z.string().min(1) }),
    before: [requireAuth({ secret })],
    assigns: {} as { auth: { id: number } },
  },
  async (c) => {
    // c.params.groupId: number
    // c.body: { email: string; name: string }
    // c.assigns.auth.id: number
    return json(c, 201, await createUser(c.assigns.auth.id, c.params.groupId, c.body))
  },
)
```

Validation failures throw `unprocessable("Invalid <where>")` with `code: "VALIDATION_FAILED"`
and `details: { where, issues }`. JSON body parsing happens automatically when a `body`
schema is provided — no need to add `parseJson` to `before`.

### Response (`response/index.ts`)
- `json(conn, status, data)` — JSON response, sets content-type
- `text(conn, status, body)` — plain text response
- `redirect(conn, location, status?)` — redirect (default 302)
- `stream(conn, status, readable)` — streaming response

### Parsers (`parsers/index.ts`)
- `parseJson` — pipe that parses JSON body
- `parseForm` — pipe that parses URL-encoded form body
- `parseMultipart` — pipe that parses multipart form data

### Errors (`errors/index.ts`)
- `HttpError` — tagged error object: `{ status, message, code?, details?, headers? }`
- `httpError(status, message, opts?)` — build an `HttpError`
- `isHttpError(value)` — type guard; routers/onError use it to render the right status
- `badRequest`, `unauthorized`, `forbidden`, `notFound`, `methodNotAllowed`, `conflict`,
  `gone`, `unprocessable`, `tooManyRequests`, `internal`, `serviceUnavailable` —
  status-specific factories: `notFound("user not found")` → throws as 404
- `haltWith(conn, error)` — short-circuit the pipeline with an `HttpError` (alternative to `throw`)
- `onError(handler)` — register a custom error handler pipe for the router

### Throw-style error handling

```ts
import { notFound, conflict, get, json, pipe } from "@atlas/server"

get("/users/:id", pipe(async (c) => {
  const user = await db.one(from(users).where(q => q("id").equals(c.params.id)))
  if (!user) throw notFound("user not found")
  return json(c, 200, user)
}))
```

The router catches thrown `HttpError`s and renders them as JSON with the right status,
code, details, and any custom headers. Non-`HttpError`s become 500s with stack traces
logged server-side only.

### Adapter (`adapter/index.ts`)
- `ServerAdapter<TConfig>` — generic adapter type with name + start
- `createAdapter(name, start)` — create a named server adapter
- `compose(adapters)` — start multiple adapters, returns `ComposedServer` with `stop()`

### WebSocket (`ws/index.ts`) — import from `@atlas/server/ws`
- `WsConn<T>` — wrapped websocket connection with auto-JSON send
- `channel(name, handlers)` — define a typed pub/sub channel
- `createRooms()` — room manager with join/leave/broadcast/members
- `ws(config)` — build websocket handler + rooms + upgrade helper
- `wsAdapter` — standalone WS adapter for use with `compose()`

### SSE (`sse/index.ts`) — import from `@atlas/server/sse`
- `SseClient` — client with id, send, close
- `createSseChannel()` — managed SSE channel with broadcast + pipe
- `eventStream(conn, generator)` — one-off SSE response helper

## Usage

```ts
import { pipe, pipeline, router, serve, json, assign, parseJson, get, post } from "@atlas/server"

const logger = pipe((c) => {
  console.log(`${c.method} ${c.path}`)
  return c
})

const authed = pipeline(logger, parseJson)

serve({
  port: 3000,
  routes: [
    get("/", pipe((c) => json(c, 200, { status: "ok" }))),
    get("/users/:id", authed(
      pipe((c) => json(c, 200, { id: c.params.id }))
    )),
    post("/users", authed(
      pipe((c) => json(c, 201, { created: true, body: c.body }))
    )),
  ],
})
```

## Architecture
- All functions are pure and return new Conn (immutable)
- Pipes compose via `pipeline()`, halt short-circuits
- Route builders (`get`, `post`, `put`, etc.) create typed Route objects
- `router(...routes)` matches requests against Route objects
- No classes, fully functional
</document>

<document path="packages/auth/AGENTS.md">
# @atlas/auth

Authentication primitives and prebuilt auth flow pipes for the Atlas framework.

## Exports

### Password Hashing

- `hash(password: string): Promise<string>` - Hash a password using Argon2id via Bun.password
- `verify(password: string, hashed: string): Promise<boolean>` - Verify a password against a hash

### JWT Tokens (`token` namespace)

- `token.sign(payload, secret, opts?): Promise<string>` - Create an HS256 JWT
  - `opts.expiresIn` - seconds until expiration
- `token.verify(token, secret): Promise<TokenPayload>` - Verify and decode a JWT
  - Throws on invalid signature, bad format, or expiration
- `TokenPayload` - `Record<string, unknown> & { iat?: number; exp?: number }`

### Session Management

- `createMemoryStore({ ttl? }): SessionStore` - In-memory session store for dev/testing; `ttl` (seconds) expires sessions, without it they live until `destroy`
- `SessionStore` type with `create`, `get`, `destroy` methods

### Auth Flows (PipeFn factories for @atlas/server)

- `signup({ db, table, fields, onSuccess })` - Registration pipe; `table` is a name string or a `defineSchema` object
  - Reads body fields, hashes password, inserts into DB
  - Calls onSuccess with conn and new user record
- `login({ db, table, identity, password, onSuccess })` - Login pipe
  - Looks up user by identity field, verifies password
  - Calls onSuccess or halts 401
- `requireAuth({ secret })` - JWT guard pipe
  - Reads Bearer token from Authorization header
  - Puts decoded payload into `conn.assigns.auth`
  - Halts 401 if missing or invalid
- `passwordReset({ db, table, secret, transport, expiresIn? })` - Password reset pipe
  - Generates reset token (JWT signed with `secret`, TTL `expiresIn` seconds, default 3600), calls transport function
  - Always returns 200 to prevent email enumeration

## Usage

```ts
import { hash, verify, token, requireAuth, login, signup } from "@atlas/auth"

// password hashing
const hashed = await hash("mypassword")
const ok = await verify("mypassword", hashed)

// JWT
const jwt = await token.sign({ userId: 1 }, SECRET, { expiresIn: 3600 })
const payload = await token.verify(jwt, SECRET)

// auth guard pipe
const guard = requireAuth({ secret: SECRET })

// login flow
const loginPipe = login({
  db,
  table: "users",
  identity: "email",
  password: "password",
  onSuccess: async (conn, user) =>
    json(conn, 200, { token: await token.sign({ userId: user.id }, SECRET) }),
})
```

### Social Login (`@atlas/auth/social`)

Pluggable OAuth-client side of authentication. Seven built-in providers — each
exported as a factory that takes its config and returns a `SocialProvider`.

| Factory | Provider | Notes |
|---------|----------|-------|
| `google({ clientId, clientSecret, redirectUri, hostedDomain?, prompt? })` | Google OIDC | id_token-based profile, `offline` access |
| `github({ clientId, clientSecret, redirectUri, allowSignup? })` | GitHub OAuth2 | falls back to `/user/emails` when primary email is private |
| `apple({ clientId, teamId, keyId, privateKey, redirectUri, responseMode? })` | Sign in with Apple | mints ES256 client_secret JWT per request; default `response_mode=form_post` |
| `microsoft({ clientId, clientSecret, redirectUri, tenant?, prompt? })` | Microsoft / Entra ID | tenant-aware (`common`, `consumers`, `organizations`, or a tenant ID) |
| `facebook({ clientId, clientSecret, redirectUri, apiVersion?, profileFields? })` | Meta Graph API | scope joined with commas, default `v19.0` |
| `twitter({ clientId, clientSecret?, redirectUri, userFields? })` | X (OAuth 2 + PKCE) | confidential clients use Basic auth on `/oauth2/token` |
| `tiktok({ clientKey, clientSecret, redirectUri, userFields? })` | TikTok Login Kit | uses `client_key` (not `client_id`), scopes are comma-joined, profile id is `open_id` |

All providers are PKCE-S256, scope-configurable, and return a normalized
`SocialProfile`:

```ts
type SocialProfile = {
  provider: string
  id: string
  email?: string | null
  emailVerified?: boolean
  name?: string | null
  picture?: string | null
  username?: string | null
  raw: Record<string, unknown>
}
```

#### Usage

```ts
import {
  socialAuth, google, github, apple, microsoft, facebook, twitter, tiktok,
} from "@atlas/auth/social"
import { get, redirect, putHeader } from "@atlas/server"
import { token } from "@atlas/auth"

const social = socialAuth({
  secret: process.env.OAUTH_STATE_SECRET!,
  providers: {
    google:    google({ clientId, clientSecret, redirectUri: `${origin}/auth/google/callback` }),
    github:    github({ clientId, clientSecret, redirectUri: `${origin}/auth/github/callback` }),
    apple:     apple({ clientId, teamId, keyId, privateKey, redirectUri: `${origin}/auth/apple/callback` }),
    microsoft: microsoft({ clientId, clientSecret, redirectUri: `${origin}/auth/microsoft/callback` }),
    facebook:  facebook({ clientId, clientSecret, redirectUri: `${origin}/auth/facebook/callback` }),
    twitter:   twitter({ clientId, redirectUri: `${origin}/auth/twitter/callback` }),
    tiktok:    tiktok({ clientKey, clientSecret, redirectUri: `${origin}/auth/tiktok/callback` }),
  },
})

const routes = [
  get("/auth/google", social.start("google", { returnTo: "/welcome" })),
  get("/auth/google/callback", social.callback("google", {
    onSuccess: async (conn, { profile, returnTo }) => {
      // app owns the user table — upsert here
      const user = await upsertUserFromProfile(profile)
      const jwt = await token.sign({ sub: user.id }, JWT_SECRET, { expiresIn: 3600 })
      return redirect(putHeader(conn, "set-cookie", `session=${jwt}; HttpOnly; Path=/`), returnTo ?? "/")
    },
  })),
  // …same for github / apple / microsoft / facebook / twitter
]
```

Apple uses `response_mode=form_post` by default, so the callback arrives as a
`POST` with form-encoded `code`/`state` in the body — mount the route with
`post(...)` and compose `parseForm` before `social.callback("apple", …)`.

#### Stateless flow

State + PKCE verifier live in a signed, HttpOnly, SameSite=lax cookie
(`_atlas_oauth_state` by default, 10-minute TTL). Override via
`socialAuth({ cookie: { name?, path?, secure?, sameSite? } })`. Behind a
non-HTTPS dev proxy, set `cookie: { secure: false }`.

#### Pure helpers

If you need to render the consent flow yourself (e.g. show a "Continue with X"
button list), call `social.authorize(name, opts?)` to get `{ url, cookie }`
without writing to a `Conn`. `social.complete(name, conn)` is the inverse —
verifies + exchanges + fetches and returns the normalized result.

## Dependencies

- `@atlas/db` - database access for flows
- `@atlas/server` - Conn/PipeFn types for flows and social pipes
- Zero external dependencies; uses Bun.password, Web Crypto, and `fetch`

## Testing

```sh
bun test packages/auth/
```
</document>

<document path="packages/security/AGENTS.md">
# @atlas/security

Security primitives every web app needs: response-hardening headers, rate
limiting, audit logging, TOTP/2FA, and revocable JWT sessions.

## Modules

| Submodule | What it gives you |
|-----------|------------------|
| `headers` | `withSecurityHeaders` — strict default headers + CSP, plus a peer-IP shim that stashes `req.peerIp` for `clientIp` to read |
| `inline` | `decideInline` — safe-MIME allowlist for `Content-Disposition: inline` decisions |
| `ratelimit` | `createDbRateLimit` / `createMemoryRateLimit` + `clientIp` / `userAgent` / `parseTrustedProxies` |
| `audit` | `createAuditLogger` — fire-and-forget audit-event recorder |
| `totp` | `generateSecret`, `totpAt`, `verifyTotp`, `otpauthUrl`, `generateBackupCodes` |
| `sessions` | `createSessionStore` — DB-backed JWT sessions with revoke, sweep, and `last_used_at` |

Everything is exported from the package root: `import { ... } from "@atlas/security"`.

## Headers

```ts
import { withSecurityHeaders } from "@atlas/security"
import { serve } from "@atlas/server"

const fetch = withSecurityHeaders(buildFetch(routes), { dev: process.env.NODE_ENV !== "production" })
Bun.serve({ port: 3000, fetch })
```

Sets HSTS, `X-Content-Type-Options`, `X-Frame-Options: DENY`, `Referrer-Policy`,
`Permissions-Policy` (camera/mic/geo/cohort off), COOP/CORP same-origin, and a
`Content-Security-Policy` that defaults to `'self'`-only with no inline scripts
in production. Pass `{ dev: true }` to relax script/connect for HMR, or `{ csp:
"…" }` to override entirely. Set `{ disableCsp: true }` for API-only origins.

The wrapper also stashes the Bun socket peer onto the request as `req.peerIp`
so downstream rate-limit / audit code reads the *real* peer rather than
trusting `X-Forwarded-For` from the client.

## Inline downloads

```ts
import { decideInline } from "@atlas/security"

const { contentType, disposition } = decideInline(file.mime, file.name, wantInline)
```

Forces `application/octet-stream; attachment` for any MIME outside a narrow
safe-list (images, video, audio, PDF, plain text). SVG is excluded — it parses
as XML and runs script.

## Rate limiting

```ts
import { createDbRateLimit, clientIp, parseTrustedProxies } from "@atlas/security"

const trustedProxies = parseTrustedProxies(process.env.TRUSTED_PROXIES)
const limiter = createDbRateLimit({ db })

const { ok, retryAfterSeconds } = await limiter.check(`signup:ip:${clientIp(req, { trustedProxies })}`, 5, 3600)
if (!ok) return Response.json({ error: "rate_limited", retry_after: retryAfterSeconds }, { status: 429 })
```

Postgres uses an atomic UPSERT; SQLite uses a transactional read-modify-write
inside a single transaction. Schema:

```sql
CREATE TABLE rate_limits (
  bucket TEXT PRIMARY KEY,
  count INTEGER NOT NULL,
  window_started_at TIMESTAMPTZ NOT NULL  -- INTEGER unix-seconds on SQLite
);
```

`createMemoryRateLimit()` returns the same interface for tests / dev (it also
self-sweeps expired buckets opportunistically).

Both limiters expose `sweep(olderThanSeconds)` — drop buckets whose window
started more than that many seconds ago, returning the removed count. Run it
periodically (cron) with a value >= your longest window to keep the table/map
from accumulating one row per bucket key forever.

`clientIp(req, { trustedProxies })` returns the real client IP. It honors
`X-Forwarded-For` / `X-Real-IP` *only* when the request actually arrived from a
configured trusted proxy — otherwise the headers are attacker-supplied.

## Audit log

```ts
import { createAuditLogger } from "@atlas/security"

const audit = createAuditLogger({ db })

audit.log({ userId: 42, event: "user.login", ip: clientIp(req), userAgent: userAgent(req) })
```

Schema:

```sql
CREATE TABLE audit_events (
  id          SERIAL PRIMARY KEY,
  user_id     INTEGER NULL,
  event       TEXT NOT NULL,
  metadata    TEXT NULL,            -- JSON
  ip          TEXT NULL,
  user_agent  TEXT NULL,
  created_at  TIMESTAMPTZ DEFAULT NOW()
);
```

Logging is fire-and-forget — `log` never throws and never blocks the response.

## TOTP / 2FA

```ts
import { generateSecret, otpauthUrl, verifyTotp, generateBackupCodes } from "@atlas/security"

const secret = generateSecret()
const provisioning = otpauthUrl({ secret, account: user.email, issuer: "Atlas" })
// render `provisioning` as a QR code

if (!verifyTotp(secret, code, { window: 1 })) return Response.json({ error: "invalid_code" }, { status: 401 })

const backupCodes = generateBackupCodes()  // store hashed; show plaintext exactly once
```

Pure `node:crypto` — no external deps. SHA-1 / 6-digit / 30-second steps,
matching every authenticator app in the wild. `window: 1` accepts ±30s of
clock skew.

## Sessions

```ts
import { createSessionStore } from "@atlas/security"

const sessions = createSessionStore<{ id: number; email: string }>({
  db,
  secret: process.env.JWT_SECRET!,
  ttlSeconds: 86400 * 7,
})

// login
const { token, jti } = await sessions.issue(user, { ip: clientIp(req), userAgent: userAgent(req) })

// every request
const status = await sessions.isActive(jwtPayload.jti)
if (!status.active) return halt(conn, 401)
sessions.touch(jwtPayload.jti)

// logout / logout-everywhere
await sessions.revoke(jti, user.id)
await sessions.revokeAll(user.id, /* keep current */ jti)

// nightly cleanup
await sessions.sweepExpired()
```

The JWT stays stateless, but the embedded `jti` is bound to a row whose
`revoked_at` lets you kill a session server-side. Pair with
`@atlas/auth#requireAuth` plus a sessions check to enforce the revocation.

Schema:

```sql
CREATE TABLE sessions (
  id            TEXT PRIMARY KEY,        -- the jti
  user_id       INTEGER NOT NULL,
  ip            TEXT NULL,
  user_agent    TEXT NULL,
  created_at    TIMESTAMPTZ DEFAULT NOW(),
  last_used_at  TIMESTAMPTZ NULL,
  expires_at    TIMESTAMPTZ NOT NULL,
  revoked_at    TIMESTAMPTZ NULL
);
```

Note: `@atlas/auth` already exports an in-memory `SessionStore` for simple
flows. The store here is a different (richer) interface — DB-backed,
revocable, with audit context. Pick whichever fits.

## Dependencies

- `@atlas/auth` — for `token.sign` (sessions only)
- `@atlas/db` — for the rate-limit / audit / session tables
- `node:crypto` — for TOTP and `randomUUID`

## Testing

```sh
bun test packages/security/
```
</document>

<document path="packages/oauth/AGENTS.md">
# @atlas/oauth

Pluggable OAuth 2.1 authorization server. PKCE-required, refresh-token
rotation with reuse detection, RFC 8628 device-code flow, dynamic client
management, and RFC 8414 discovery — all as `Route[]` you mount on
`@atlas/server`.

The package is route-only. Your app owns the user table, the consent UI, and
whatever guard pipes you want to put in front of it.

## Quick start

```ts
import { oauthRoutes } from "@atlas/oauth"
import { requireAuth } from "@atlas/auth"
import { from } from "@atlas/db"
import { router } from "@atlas/server"

const cfg = {
  db,
  secret: process.env.JWT_SECRET!,
  scopes: ["read", "write", "share"],
  loadUser: (db, id) => db.one(from("users").where(q => q("id").equals(id))),
  buildAccessTokenClaims: (user) => ({
    id: user.id,
    email: user.email,
    username: user.username,
    name: user.name,
  }),
  requireUser: requireAuth({ secret: process.env.JWT_SECRET! }),
  requireAdmin: ownerOnlyPipe,  // your own admin guard
}

Bun.serve({
  port: 3000,
  fetch: router(...oauthRoutes(cfg), ...yourAppRoutes),
})
```

## What gets mounted

`oauthRoutes(cfg, { basePath?, adminBasePath? })` returns:

| Method | Path (under basePath) | Auth | Description |
|--------|----------------------|------|-------------|
| GET    | `/authorize/info`           | requireUser  | Validate authorize params, return client + scopes for the consent screen |
| POST   | `/authorize/approve`        | requireUser  | Issue an auth code; returns `redirect_url` |
| POST   | `/authorize/deny`           | requireUser  | Returns the error redirect URL |
| POST   | `/token`                    | client cred  | `authorization_code`, `refresh_token`, `device_code` grants |
| POST   | `/revoke`                   | open         | RFC 7009 revocation |
| POST   | `/device/authorize`         | open         | RFC 8628 — start device-code flow |
| GET    | `/device/info`              | requireUser  | Consent metadata for `/pair` SPA |
| POST   | `/device/approve`           | requireUser  | Record approval against a user_code |
| POST   | `/device/deny`              | requireUser  | Record denial |
| GET    | `/.well-known/oauth-authorization-server` | open | RFC 8414 discovery |

Plus admin (under `adminBasePath`, default `/admin/oauth`):

| Method | Path | Description |
|--------|------|-------------|
| GET    | `/clients`                       | List clients |
| POST   | `/clients`                       | Create client (returns `client_secret` once for confidential clients) |
| PATCH  | `/clients/:id`                   | Update name / description / scopes / redirect_uris |
| POST   | `/clients/:id/rotate-secret`     | Rotate secret + invalidate all refresh tokens |
| DELETE | `/clients/:id`                   | Soft-revoke client + invalidate refresh tokens |

## Configuration

```ts
type OAuthConfig = {
  db: Connection
  secret: string                      // JWT signing secret
  scopes: readonly string[]           // scopes you're willing to grant

  loadUser: (db, userId) => Promise<OAuthUser | null>
  buildAccessTokenClaims: (user) => Record<string, unknown>

  requireUser: PipeFn                 // guard for consent screens — usually requireAuth
  requireAdmin: PipeFn                // guard for /admin/oauth/clients

  userIdFromConn?: (conn) => number | string  // default: conn.assigns.auth.id
  audit?: (ev) => void                        // optional audit hook
  requestContext?: (req) => { ip?, userAgent? }
  buildVerificationUri?: (req) => string      // default: ${origin}/pair

  tables?: {
    clients?: string                  // default oauth_clients
    authorizationCodes?: string       // default oauth_authorization_codes
    refreshTokens?: string            // default oauth_refresh_tokens
    deviceCodes?: string              // default oauth_device_codes
  }
}
```

`buildAccessTokenClaims` is the only place your user shape leaks into the JWT.
The library merges in `{ client_id, scope, jti }` regardless of what you
return.

`audit` integrates cleanly with `@atlas/security`'s `AuditLogger`:

```ts
import { createAuditLogger } from "@atlas/security"
const audit = createAuditLogger({ db })
const cfg: OAuthConfig = { ...rest, audit: audit.log }
```

## Schema

```sql
-- clients
CREATE TABLE oauth_clients (
  id                  SERIAL PRIMARY KEY,
  client_id           TEXT UNIQUE NOT NULL,
  client_secret_hash  TEXT NULL,         -- null = public client (PKCE only)
  name                TEXT NOT NULL,
  description         TEXT NULL,
  icon_url            TEXT NULL,
  redirect_uris       TEXT NOT NULL,     -- JSON array
  allowed_scopes      TEXT NOT NULL,     -- JSON array
  is_official         BOOLEAN NOT NULL DEFAULT FALSE,
  created_by          INTEGER NULL,
  created_at          TIMESTAMPTZ DEFAULT NOW(),
  revoked_at          TIMESTAMPTZ NULL
);

-- single-use authorization codes (60s TTL)
CREATE TABLE oauth_authorization_codes (
  code                  TEXT PRIMARY KEY,
  client_id             TEXT NOT NULL,
  user_id               INTEGER NOT NULL,
  redirect_uri          TEXT NOT NULL,
  code_challenge        TEXT NOT NULL,
  code_challenge_method TEXT NOT NULL,
  scope                 TEXT NOT NULL,
  expires_at            TIMESTAMPTZ NOT NULL,
  used_at               TIMESTAMPTZ NULL,
  nonce                 TEXT NULL,
  auth_time             INTEGER NULL
);

-- refresh tokens (30d TTL, rotated on every use)
CREATE TABLE oauth_refresh_tokens (
  token_hash         TEXT PRIMARY KEY,   -- SHA-256 hex of the plaintext
  client_id          TEXT NOT NULL,
  user_id            INTEGER NOT NULL,
  scope              TEXT NOT NULL,
  parent_token_hash  TEXT NULL,
  created_at         TIMESTAMPTZ DEFAULT NOW(),
  expires_at         TIMESTAMPTZ NOT NULL,
  revoked_at         TIMESTAMPTZ NULL
);

-- device-flow codes (10m TTL)
CREATE TABLE oauth_device_codes (
  device_code      TEXT PRIMARY KEY,
  user_code        TEXT UNIQUE NOT NULL,
  client_id        TEXT NOT NULL,
  scope            TEXT NOT NULL,
  user_id          INTEGER NULL,
  approved_at      TIMESTAMPTZ NULL,
  denied_at        TIMESTAMPTZ NULL,
  last_polled_at   TIMESTAMPTZ NULL,
  expires_at       TIMESTAMPTZ NOT NULL
);
```

## Sweeps

```ts
import { sweepExpired } from "@atlas/oauth"

setInterval(() => sweepExpired(cfg), 60 * 60 * 1000)  // hourly
```

`sweepExpired` runs all three table sweeps in parallel; each is also exported
individually if you want to schedule them differently.

## Helpers

`@atlas/oauth` re-exports the building blocks:

```ts
import {
  randomId, shortId,           // ID minting
  verifyPkceS256, sha256,      // crypto
  parseScope, formatScope, includesScopes, isAllowedRedirect,
  newUserCode, normalizeUserCode,
  ACCESS_TOKEN_TTL_SECONDS, REFRESH_TOKEN_TTL_SECONDS,
  AUTH_CODE_TTL_SECONDS, DEVICE_CODE_TTL_SECONDS, DEVICE_POLL_INTERVAL_SECONDS,
} from "@atlas/oauth"
```

## Security notes

- **PKCE is mandatory** for the authorization-code grant — no `code_challenge`
  → `invalid_request`.
- Refresh tokens are **rotated on every use** and the **prior chain is burned
  on revoked-token reuse** (a strong leakage signal).
- `redirect_uri` matching is **exact-string only**, per OAuth 2.0 Security
  BCP. No prefix or substring matching.
- Client secrets are stored as SHA-256 hex; verification is constant-time.
- The plaintext `client_secret` is returned **exactly once** at creation /
  rotation. Surface that in your admin UI and discard.

## Dependencies

- `@atlas/auth` — `token.sign` for access-token JWTs
- `@atlas/db` — query builder
- `@atlas/server` — route + pipe types

## Testing

```sh
bun test packages/oauth/
```
</document>

<document path="packages/request/AGENTS.md">
# @atlas/request

HTTP client for outbound API/web requests, built on fetch.

## Exports

### `request(url, opts?)`

One-off HTTP request. Accepts `RequestOptions` with optional `method`, `headers`, `json`, `body`, `retry`, and `timeout` (ms; each retry attempt gets its own window).

```ts
import { request } from "@atlas/request"

const res = await request("https://api.example.com/data", {
  method: "POST",
  json: { name: "atlas" },
})
```

When `json` is provided, the body is serialized and `content-type: application/json` is set automatically.

### `createClient(opts)`

Returns a `Client` with preconfigured `baseUrl`, default `headers`, optional `retry`, and `interceptors`.

```ts
import { createClient } from "@atlas/request"

const api = createClient({
  baseUrl: "https://api.example.com",
  headers: { authorization: "Bearer tok_123" },
  retry: { attempts: 3 },
})

const res = await api.get("/users")
const created = await api.post("/users", { json: { name: "Wess" } })
```

### `Client` type

```ts
{
  get(path, opts?): Promise<Response>
  post(path, opts?): Promise<Response>
  put(path, opts?): Promise<Response>
  patch(path, opts?): Promise<Response>
  del(path, opts?): Promise<Response>
  request(path, opts?): Promise<Response>
}
```

### `withRetry(fn, opts?)`

Wraps a fetch call with retry logic. Options: `attempts` (default 3), `delay` (default 1000ms), `backoff` (default 2x), `retryOn` (default: status >= 500).

```ts
import { withRetry } from "@atlas/request"

const res = await withRetry(() => fetch("https://api.example.com/health"), {
  attempts: 5,
  delay: 500,
})
```

### Interceptors

Request and response interceptors transform the url/init or response in sequence.

```ts
import { createClient } from "@atlas/request"

const client = createClient({
  baseUrl: "https://api.example.com",
  interceptors: {
    request: [(url, init) => ({ url, init: { ...init, headers: { ...init.headers as any, "x-trace": "abc" } } })],
    response: [(res) => { console.log(res.status); return res }],
  },
})
```

### Providers

Preconfigured clients for common APIs. Import from `@atlas/request/providers`.

```ts
import { github, stripe, openai, resend } from "@atlas/request/providers"

const gh = github({ token: process.env.GITHUB_TOKEN! })
const res = await gh.get("/user")

const mail = resend({ key: process.env.RESEND_KEY! })
await mail.post("/emails", { json: { to: "user@example.com", subject: "Hi" } })
```

Available providers: `github`, `stripe`, `openai`, `resend`.

## File structure

- `client/index.ts` -- request(), createClient(), types
- `retry/index.ts` -- withRetry()
- `interceptors/index.ts` -- interceptor types and apply functions
- `providers/index.ts` -- preconfigured clients
- `index.ts` -- re-exports

## Types

- `RequestOptions = { method?, headers?, json?, body?, retry?, timeout? }`
- `Client = { get, post, put, patch, del, request }` — all return `Promise<Response>`
- `ClientOptions = { baseUrl, headers?, retry?, interceptors?, timeout? }`
- `RetryOptions = { attempts?, delay?, backoff?, retryOn? }`
- `Interceptors = { request?: RequestInterceptor[]; response?: ResponseInterceptor[] }`
- `RequestInterceptor = (url, init) => { url, init }` (or Promise of)
- `ResponseInterceptor = (res) => Response` (or Promise of)

## Dependencies

- Sibling packages: none — `@atlas/request` is standalone.
- External: none. Built on the platform `fetch`.

## Testing

```sh
bun test packages/request/
```
</document>

<document path="packages/storage/AGENTS.md">
# @atlas/storage

S3-compatible object storage with zero external dependencies.

## Exports

- `createStore(opts)` → `Store`
- `upload(store, { key, body, contentType? })` → `Promise<{ key, url }>`
- `download(store, key)` → `Promise<Response>`
- `remove(store, key)` → `Promise<void>` (no-ops on 404)
- `list(store, prefix?)` → `Promise<ListResult>`
- `presign(store, key, { expires?, method? })` → `string`

## Types

- `Store = { endpoint, bucket, region, accessKey, secretKey }`
- `UploadOptions = { key; body: string | Uint8Array | Blob | ReadableStream; contentType? }`
- `ListResult = { keys: string[]; truncated: boolean }`

## Architecture

- `store/` — Store type and createStore factory
- `signing/` — AWS Signature V4 implementation using node:crypto
- `operations/` — upload, download, remove, list (signed S3 requests)
- `presign/` — presigned URL generation for direct client access

## API

### createStore(opts) => Store

Creates a store configuration object.

```ts
const store = createStore({
  endpoint: "http://localhost:9000",
  bucket: "mybucket",
  accessKey: "minioadmin",
  secretKey: "minioadmin",
  region: "us-east-1", // optional, defaults to us-east-1
})
```

### upload(store, opts) => Promise<{ key, url }>

Upload a file. Body can be string, Uint8Array, Blob, or ReadableStream.

```ts
await upload(store, { key: "photos/cat.jpg", body: file, contentType: "image/jpeg" })
```

### download(store, key) => Promise<Response>

Download a file. Returns the raw fetch Response.

### remove(store, key) => Promise<void>

Delete a file. No-ops on 404.

### list(store, prefix?) => Promise<{ keys, truncated }>

List objects by prefix. Returns key strings.

### presign(store, key, opts?) => string

Generate a presigned URL for direct client access.

```ts
const url = presign(store, "file.pdf", { expires: 900, method: "GET" })
```

## Testing

```sh
bun test packages/storage/          # signing + presign (no server needed)
S3_TEST=1 bun test packages/storage/ # includes operations (needs S3 server)
```

## Conventions

- Functional style, no classes
- Zero external dependencies (node:crypto only)
- All files lowercase, no dashes or underscores

## Dependencies

- Sibling packages: none — `@atlas/storage` is standalone.
- External: none. Uses `node:crypto` for AWS Signature V4 and `fetch` for transport.
</document>

<document path="packages/cache/AGENTS.md">
# @atlas/cache

Thin wrapper around Bun.redis for key-value caching with JSON serialization.

## Types

### Cache

```ts
type Cache = {
  get: <T>(key: string) => Promise<T | null>
  set: (key: string, value: unknown, opts?: { ttl?: number }) => Promise<void>
  del: (key: string) => Promise<void>
  expire: (key: string, seconds: number) => Promise<void>
  flush: () => Promise<void>
  close: () => Promise<void>
}
```

## Exports

### `createCache({ url })`
Creates a Cache backed by `Bun.redis`. Values are JSON serialized automatically.
`set` with `ttl` uses Redis EX (seconds). `flush` runs FLUSHDB.

### `createMemoryCache()`
In-memory Cache implementation for testing. Same interface, no Redis needed.

### `cached(cache, prefix, fn, opts?)`
Cache-aside helper. Wraps an async function with automatic caching.
Keys are built as `prefix:arg1:arg2:...`. Returns cached value on hit,
calls `fn` and stores result on miss.

### `invalidate(cache, prefix, ...args)`
Deletes the cache key for the given prefix and args, forcing a fresh fetch
on the next `cached()` call.

## Usage

```ts
import { createMemoryCache, cached, invalidate } from "@atlas/cache"

const cache = createMemoryCache()

const getUser = cached(cache, "user", async (id: string) => {
  return await db.query("SELECT * FROM users WHERE id = ?", [id])
}, { ttl: 60 })

const user = await getUser("123") // fetches from db
const again = await getUser("123") // returns cached

await invalidate(cache, "user", "123") // bust cache
```

## Testing

```sh
bun test packages/cache/
```

Tests use `createMemoryCache()` so no Redis instance is required.
</document>

<document path="packages/cli/AGENTS.md">
# @atlas/cli

CLI framework, Foreman-style process manager, and project scaffolding tool. Zero external dependencies.

## Modules

### command/index.ts

Minimal CLI argument parser and command router.

- `flag(short, opts)` — create a flag definition with short alias, type, default, description
- `command(name, opts)` — create a command definition with flags, args, subcommands, run handler
- `parseArgs(argv, flagDefs)` — parse argv into `{ args, flags }` using flag definitions
- `cli(name, commands)` — entry point that reads `process.argv`, matches command, parses args, runs handler

Types: `FlagDef`, `CommandDef`, `ParsedArgs`

### foreman/index.ts

Procfile parser and parallel process runner with color-coded output.

- `parseProcfile(content)` — parse Procfile string into `Record<string, string>`
- `foreman(procs)` — spawn all processes, prefix output with colored names, handle SIGINT/SIGTERM

Type: `ProcSpec` (alias for `Record<string, string>`)

### init/questions.ts

Interactive question definitions for project scaffolding.

- `questions` — array of `Question` objects (name, database, features, frontend, port)
- `getQuestionSpec()` — returns questions array (for LLM/AI programmatic access)
- `askQuestions()` — interactive stdin prompt, returns `Answers`
- `applyDefaults(partial?)` — non-interactive, fills defaults with optional overrides

Types: `Question`, `Answers`

### init/templates.ts

Project file generators based on user answers.

- `generatePackageJson(answers)` — package.json with selected atlas deps
- `generateEnv(answers)` — .env with db, cache, storage, auth config
- `generateServerTs(answers)` — working server.ts with selected features
- `generateTsconfig()` — standard bun tsconfig
- `generateProcfile(answers)` — Procfile for atlas dev
- `generateGitignore()` — standard gitignore
- `generateSchemaTs(answers)` — example db schema (postgres or sqlite)
- `generateProject(answers)` — returns all files as `{ path, content }[]`

### init/index.ts

The `atlas init` command. Flags: `--yes/-y` (skip prompts), `--name/-n` (project name), `--template/-t` (project template).

### add/index.ts

The `atlas add` command. Maps short names (auth, db, cache, etc.) to `@atlas/*` packages and runs `bun add`.

### entry.ts

CLI bin entry point. Registers init, add, dev, mcp, and docs commands, then calls `cli("atlas", commands)`.

## CLI Commands

### atlas init

Create a new Atlas project interactively.

```sh
atlas init              # interactive prompts
atlas init -y           # use all defaults
atlas init -y -n myapp  # defaults with custom name
```

### atlas add

Add Atlas packages to an existing project.

```sh
atlas add auth cache    # installs @atlas/auth @atlas/cache
atlas add               # lists available packages
```

### atlas dev

Start development servers from Procfile.

```sh
atlas dev
```

### atlas docs

Print Atlas documentation directly to stdout — `atlas docs` for the index,
`atlas docs <package>` for a package's `AGENTS.md`, `atlas docs <doc>` for a
top-level `docs/<name>.md` file, or `atlas docs <file>` for a root agent file
(`llms.txt`, `SOUL.md`, `CLAUDE.md`, `README.md`).

```sh
atlas docs              # list packages, top-level docs, and root agent files
atlas docs db           # print packages/db/AGENTS.md
atlas docs agents       # print the agent grounding guide
atlas docs api          # print docs/api.md
atlas docs cookbook     # print docs/cookbook.md
atlas docs llms.txt     # print root llms.txt
```

Useful for terminal lookups and for piping into agent tools (`atlas docs db | ...`).
The same content is exposed as the `docs.list` / `docs.read` tools by `atlas mcp`.

## Programmatic Usage

The questions and templates are designed for programmatic access:

```ts
import { applyDefaults, generateProject } from "@atlas/cli"

// Generate a project with specific answers (no interactive prompts)
const answers = applyDefaults({
  name: "my-api",
  database: "postgres",
  features: ["auth", "cache", "migrate"],
  frontend: false,
  port: "4000",
})

const files = generateProject(answers)
// files = [{ path: "package.json", content: "..." }, ...]
```

To inspect available questions:

```ts
import { getQuestionSpec } from "@atlas/cli"

const questions = getQuestionSpec()
// Returns typed Question[] with id, prompt, type, options, default
```

## Global Installation

```sh
bun add -g @atlas/cli
atlas init
```

## Usage

### CLI commands

```ts
import { cli, command, flag } from "@atlas/cli"

cli("myapp", [
  command("serve", {
    description: "Start the server",
    flags: {
      port: flag("p", { type: "number", default: 3000 }),
      verbose: flag("v", { type: "boolean", description: "Verbose output" }),
    },
    run: ({ flags }) => {
      console.log(`Listening on port ${flags.port}`)
    },
  }),
])
```

### Foreman

```ts
import { foreman } from "@atlas/cli"

// From a Procfile path
await foreman("./Procfile")

// From an object
await foreman({
  web: "bun run server.ts",
  worker: "bun run worker.ts",
})
```

### Procfile format

```
web: bun run server.ts
worker: bun run worker.ts
# comments are ignored
```

## Testing

```sh
bun test packages/cli/
```

## Conventions

- Functional style, no classes
- All file names lowercase, no dashes or underscores
- Zero external dependencies, Bun APIs only
</document>

<document path="packages/ui/AGENTS.md">
# @atlas/ui

React + Mantine + TanStack frontend package with modular blocks.

## Architecture

Each block lives at `@atlas/ui/<block>` and can be imported independently.
All exports are also available from `@atlas/ui` for convenience.

## Blocks

### provider (`@atlas/ui/provider`)
- `AtlasProvider` — Root Mantine provider wrapper. Accepts optional `theme`.
- `AppShell` — Layout shell with optional `nav` and `header` slots.

### forms (`@atlas/ui/forms`)
- `createForm<T>(config)` — Returns a hook that provides `form` and `handleSubmit`. Supports optional Zod schema validation.
- `TextField` — Text input bound to a form field.
- `SelectField` — Select input bound to a form field with `options`.
- `SubmitButton` — Submit button with optional `loading` state.

### table (`@atlas/ui/table`)
- `TextColumn<T>(config)` — Column definition for text values.
- `DateColumn<T>(config)` — Column definition that formats dates.
- `ActionColumn<T>(config)` — Column with edit/delete action buttons.
- `createTable<T>(config)` — Returns a component rendering a data table with optional `pagination` and `search`.

### auth (`@atlas/ui/auth`)
- `LoginPage` — Email + password login form.
- `SignupPage` — Name + email + password signup form.
- `ResetPasswordPage` — Email-only password reset form.
All accept `onSubmit` returning `{ error?: string }` and optional `title`.

### storage (`@atlas/ui/storage`)
- `FileUpload` — Hidden file input with button trigger and filename display.
- `ImagePreview` — Image display inside a bordered paper.

### nav (`@atlas/ui/nav`)
- `NavLink` — Single navigation link with optional icon and active state.
- `Sidebar` — Vertical stack container for nav links.
- `Breadcrumb` — Breadcrumb trail from an array of `{ label, href? }` items.

### cache (`@atlas/ui/cache`)
- `CacheInspector` — Table view of cache entries with invalidate/flush actions.
- `CacheStatus` — Badge showing connection status, entry count, and hit rate.

### ai (`@atlas/ui/ai`)
- `ChatWindow` — Full chat interface with scrollable message list, auto-scroll, loading indicator, and `PromptInput` at the bottom. Props: `messages`, `onSend`, `loading?`, `title?`, `placeholder?`, `height?`.
- `MessageBubble` — Single message display with user (right-aligned) or assistant (left-aligned) styling and basic markdown rendering. Props: `role`, `content`, `timestamp?`.
- `PromptInput` — Textarea with send button. Enter to send, Shift+Enter for newline, loading/disabled states. Props: `onSend`, `loading?`, `placeholder?`, `disabled?`.
- `AiSearch` — Debounced semantic search input with results dropdown showing relevance scores. Props: `onSearch`, `placeholder?`, `debounceMs?`.
- `GenerateButton` — One-click AI content generation with loading state and Sparkles icon. Props: `onGenerate`, `label?`, `onResult`, `variant?` (`"button"` | `"icon"`).

## Usage

```tsx
// Import specific block
import { AtlasProvider, AppShell } from "@atlas/ui/provider"
import { createTable, TextColumn } from "@atlas/ui/table"

// Or import everything
import { AtlasProvider, createTable, LoginPage } from "@atlas/ui"
```

## Testing

```sh
bun test packages/ui/
```

## Icons

`lucide-react` is available and used throughout blocks for consistent iconography:
- **auth** — `Mail`, `Lock`, `User` icons on form fields
- **storage** — `Upload` on file button, `ImageIcon` as placeholder
- **nav** — Re-exports `Home`, `Users`, `Settings`, `FileText`, `LayoutDashboard` for convenience
- **cache** — `Database` in title, `Trash2` on invalidate, `RefreshCw` on flush
- **table** — `ChevronUp` / `ChevronDown` for sort indicators

When adding new blocks, prefer Lucide icons over unicode symbols or custom SVGs.

## Dependencies

- `@mantine/core`, `@mantine/hooks`, `@mantine/form` (v7)
- `@tanstack/react-table` (v8)
- `lucide-react`
- `react`, `react-dom` (v19)
</document>

<document path="packages/admin/AGENTS.md">
# @atlas/admin

Django-style admin panel that auto-generates CRUD API routes from @atlas/db schemas.

## Exports

### Factory
- `admin(config: AdminConfig)` — creates admin routes from config, returns `{ routes: Route[], mount: (existing: Route[]) => Route[] }`
- `model(config: ModelConfig)` — creates a model configuration

### Types
- `AdminConfig` — top-level config: `{ db, models, basePath?, auth? }`
- `ModelConfig` — per-model config: `{ schema, listFields?, searchFields?, filterFields?, relations?, actions?, bulkActions?, readOnly? }`
- `CustomAction<T>` — custom action: `{ name, label, handler }`
- `BulkAction` — `"delete" | "export"`
- `RelationConfig` — relation: `{ schema, foreignKey, label? }`
- `QueryPayload` — query builder payload: `{ table, select?, filters?, sort?, limit?, offset?, groupBy? }`
- `QueryFilter` — filter: `{ field, op, value? }` where op is `eq|neq|gt|gte|lt|lte|like|ilike|in|null|notnull`

## Generated Routes

For each model with table name `T` at `basePath` (default `/admin`):

| Method | Path | Description |
|--------|------|-------------|
| GET | `{base}/api/schema` | All model metadata |
| GET | `{base}/api/{T}` | List (paginated, searchable, filterable, sortable) |
| GET | `{base}/api/{T}/:id` | Get one record |
| POST | `{base}/api/{T}` | Create record (unless readOnly) |
| PUT | `{base}/api/{T}/:id` | Update record (unless readOnly) |
| DELETE | `{base}/api/{T}/:id` | Delete record (unless readOnly) |
| POST | `{base}/api/{T}/bulk` | Bulk action (unless readOnly) |
| POST | `{base}/api/{T}/action` | Custom action |
| GET | `{base}/api/{T}/:id/relations/{R}` | Related records |
| POST | `{base}/api/query` | Execute query builder payload |
| POST | `{base}/api/query/preview` | Preview SQL without executing |

List endpoint query params: `?page=1&limit=20&sort=name&order=asc&search=foo&filter.status=active`

## Usage

```ts
import { admin, model } from "@atlas/admin"
import { defineSchema, column, connect } from "@atlas/db"
import { serve, get, pipe, json } from "@atlas/server"

const users = defineSchema("users", {
  id: column.serial().primaryKey(),
  email: column.text().unique(),
  name: column.text(),
})

const posts = defineSchema("posts", {
  id: column.serial().primaryKey(),
  title: column.text(),
  userid: column.integer(),
})

const db = connect({ driver: "sqlite", path: "./app.db" })

const panel = admin({
  db,
  basePath: "/admin",
  auth: { secret: "my-secret" },
  models: [
    model({
      schema: users,
      searchFields: ["email", "name"],
      filterFields: ["name"],
      bulkActions: ["delete", "export"],
      relations: [{ schema: posts, foreignKey: "userid" }],
      actions: [{
        name: "deactivate",
        label: "Deactivate",
        handler: async (db, ids) => ({ message: `Deactivated ${ids.length}` }),
      }],
    }),
    model({ schema: posts, readOnly: true }),
  ],
})

serve({
  port: 3000,
  routes: panel.mount([
    get("/", pipe(c => json(c, 200, { status: "ok" }))),
  ]),
})
```

## UI Components

Frontend React SPA in `ui/`:

| File | Export | Description |
|------|--------|-------------|
| `ui/app.tsx` | `AdminApp` | Main SPA shell (sidebar + content, client-side routing) |
| `ui/dashboard.tsx` | `Dashboard` | Overview page with model record counts |
| `ui/list.tsx` | `ModelList` | Model list view (table, search, filters, sort, pagination, bulk actions) |
| `ui/detail.tsx` | `Detail` | Model detail/edit view (auto-generated form from schema) |
| `ui/create.tsx` | `Create` | Model create view (empty form) |
| `ui/query.tsx` | `QueryBuilder` | Visual query builder (select, filter, sort, group, preview SQL, execute) |
| `ui/components/sidebar.tsx` | `AdminSidebar` | Nav sidebar with model links and query builder link |
| `ui/components/filter.tsx` | `FilterBuilder` | Row-based filter builder |
| `ui/components/bulkbar.tsx` | `BulkBar` | Bulk action toolbar (appears when rows selected) |
| `ui/shell.ts` | `adminHtml` | Generates the HTML shell for serving the SPA |
| `ui/entry.tsx` | — | Browser entry point, mounts AdminApp |
| `ui/index.html` | — | HTML template for Bun HTML imports |
| `ui/styles.css` | — | Base styles |

The admin SPA is served at `GET {basePath}` and `GET {basePath}/*`. Uses React, Mantine, TanStack Table, and lucide-react.

## Dependencies

- `@atlas/db` — schema, query builder, connection
- `@atlas/server` — pipe, pipeline, router, json, parseJson
- `@atlas/auth` — requireAuth (optional, when auth config provided)
- `@mantine/core`, `@mantine/hooks`, `@mantine/form` — UI components and hooks
- `@tanstack/react-table` — table with sorting, selection, pagination
- `react`, `react-dom` — rendering
- `lucide-react` — icons
</document>

<document path="packages/mcp/AGENTS.md">
# @atlas/mcp

MCP (Model Context Protocol) server exposing Atlas app internals as tools for AI/LLM debugging.

## Architecture

JSON-RPC over stdio with Content-Length framing (like LSP). No external dependencies.

## Key Exports

- `createMcpServer(tools, ctx)` — creates an MCP server with stdin/stdout transport
- `createContext(opts?)` — builds an `AtlasMcpContext` from optional service references
- `collectTools(ctx)` — returns tools based on what services are available in context
- `defineTool(tool)` — identity helper for defining a tool with type safety

## AtlasMcpContext

Holds optional references: `db`, `cache`, `routes`, `config`, `storage`, `migrationsDir`, `logBuffer`.
Tools auto-register based on which fields are present.

## Built-in Tools

| Tool | Requires | Description |
|------|----------|-------------|
| `db.query` | db | Execute SQL, returns rows as JSON |
| `db.schemas` | db | List tables and columns |
| `migrate.status` | db + migrationsDir | Show applied/pending migrations |
| `migrate.up` | db + migrationsDir | Run pending migrations |
| `migrate.down` | db + migrationsDir | Rollback last migration |
| `cache.get` | cache | Get value by key |
| `cache.set` | cache | Set value with optional TTL |
| `cache.del` | cache | Delete a key |
| `cache.flush` | cache | Flush all entries |
| `routes.list` | routes | List HTTP routes |
| `config.show` | config | Show config (secrets redacted) |
| `storage.list` | storage | List files with optional prefix |
| `storage.presign` | storage | Generate presigned URL |
| `health.check` | (always) | Check service connectivity |
| `docs.list` | (always) | List every package reference, guide including `docs/agents.md`, and root documentation entry point |
| `docs.read` | (always) | Read one package, guide, or root documentation source |
| `logs.tail` | logBuffer | Get recent log lines |

The `docs.*` tools are always present so an agent connected to an Atlas-built
app can self-introspect the framework — no web fetch required.

## Usage

### Programmatic

```ts
import { createContext, collectTools, createMcpServer } from "@atlas/mcp"

const ctx = createContext({ db, cache, routes })
const tools = collectTools(ctx)
const server = createMcpServer(tools, ctx)
await server.start()
```

### CLI

```sh
atlas mcp
```

Or directly:

```sh
bun run packages/mcp/entry.ts
```

Environment variables: `DATABASE_URL`, `DATABASE_PATH`, `REDIS_URL`, `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION`.

## Types

- `McpServer = { start(): Promise<void>; stop(): void }`
- `AtlasMcpContext = { db?, cache?, routes?, config?, storage?, migrationsDir?, logBuffer? }`
- `Tool = { name; description; inputSchema; handler(input, ctx) → Promise<unknown> }`
- `ToolInput` — JSON-schema-shaped input descriptor

## Dependencies

Sibling packages are *optional* — pass only the services you want exposed:

- `@atlas/db` — enables `db.*` and `migrate.*` tools
- `@atlas/cache` — enables `cache.*` tools
- `@atlas/server` — enables `routes.list`
- `@atlas/config` — enables `config.show` (secrets redacted)
- `@atlas/storage` — enables `storage.*` tools
- `@atlas/migrate` — enables `migrate.up` / `migrate.down`

External: none. Pure JSON-RPC over stdio with Content-Length framing.

## Testing

```sh
bun test packages/mcp/
```
</document>

<document path="packages/ai/AGENTS.md">
# @atlas/ai

Unified AI provider abstraction with chat, embeddings, streaming, RAG, and agent support. Zero external dependencies -- uses fetch for all API calls.

## Exports

Provider:
- `createProvider({ provider, key?, baseUrl? })` → `AiProvider` — provider is `"openai" | "anthropic" | "ollama"`
- `AiProvider` exposes `.chat(opts)`, `.chatStream(opts)`, `.embed(opts)`

Chat:
- `createConversation(system?)` → `Conversation`
- `addMessage(conv, msg)` → `Conversation` (immutable)
- `send(provider, conv, content, opts?)` → `{ conversation, response }`
- `userMessage`, `assistantMessage`, `systemMessage`, `toolMessage`

Stream:
- `parseSSE(text)` → events
- `collectStream(stream)` → `ChatResponse`
- `streamToSse(stream)` → `ReadableStream` (for HTTP responses)

Embeddings:
- `embed(provider, inputs)` → `number[][]` — inputs: `string | string[]`
- `cosineSimilarity(a, b)` → `number`
- `createVectorStore()` → `{ add, search, size }`

Structured / tools:
- `generateJson<T>(provider, prompt, opts?)` → `T`
- `tool(name, description, parameters)` → `ToolDef`

RAG:
- `index(rag, id, text)` → `Promise<void>` — `rag = { ai, store, topK? }`
- `query(rag, question)` → `{ answer, sources }`

Agents:
- `runAgent({ ai, system?, tools, maxIterations? }, prompt)` → result

Server pipe:
- `withAi(provider)` → `PipeFn` — adds `provider` to `conn.assigns.ai`

## Types

- `ProviderConfig`, `Message`, `ChatOptions`, `ChatResponse`, `StreamChunk`
- `EmbedOptions`, `EmbedResponse`, `ToolDef`, `ToolCall`
- `Conversation`, `VectorStore`, `VectorEntry`, `RagOptions`
- `AgentTool`, `AgentOptions`

## Provider setup

```ts
import { createProvider } from "@atlas/ai"

const openai = createProvider({ provider: "openai", key: process.env.OPENAI_API_KEY! })
const anthropic = createProvider({ provider: "anthropic", key: process.env.ANTHROPIC_API_KEY! })
const ollama = createProvider({ provider: "ollama" }) // local, no key needed
```

## Chat

```ts
import { createConversation, send } from "@atlas/ai"

const conv = createConversation("You are a helpful assistant")
const { conversation, response } = await send(openai, conv, "Hello!")
// conversation tracks full message history immutably
```

## Streaming

```ts
import { collectStream, streamToSse } from "@atlas/ai"

const stream = openai.chatStream({ messages: [{ role: "user", content: "Hi" }] })
const full = await collectStream(stream) // collect into ChatResponse
const sse = streamToSse(stream) // convert to ReadableStream for HTTP responses
```

## Embeddings and vector search

```ts
import { embed, cosineSimilarity, createVectorStore } from "@atlas/ai"

const vectors = await embed(openai, ["hello", "world"])
const score = cosineSimilarity(vectors[0]!, vectors[1]!)

const store = createVectorStore()
store.add("id1", vectors[0]!, { text: "hello" })
const results = store.search(vectors[1]!, 5) // top 5 nearest
```

## Structured output

```ts
import { generateJson, tool } from "@atlas/ai"

const user = await generateJson<{ name: string }>(openai, "Generate a user")
const searchTool = tool("search", "Search the web", { type: "object", properties: { query: { type: "string" } } })
```

## RAG

```ts
import { index, query, createVectorStore, createProvider } from "@atlas/ai"

const store = createVectorStore()
const rag = { ai: openai, store, topK: 3 }

await index(rag, "doc1", "Document text here...")
const result = await query(rag, "What does the document say?")
// result.answer, result.sources
```

## Agent loop

```ts
import { runAgent, tool } from "@atlas/ai"

const result = await runAgent({
  ai: openai,
  system: "You are a calculator assistant",
  tools: [{
    definition: tool("multiply", "Multiply two numbers", {
      type: "object",
      properties: { a: { type: "number" }, b: { type: "number" } },
    }),
    handler: async (args) => String((args.a as number) * (args.b as number)),
  }],
  maxIterations: 5,
}, "What is 6 times 7?")
```

## Server pipe

```ts
import { withAi } from "@atlas/ai"

// Add AI provider to conn.assigns.ai in a server pipeline
const aiPipe = withAi(openai)
```

## Architecture

- `provider/` -- Provider interface and adapters (openai, anthropic, ollama)
- `chat/` -- Immutable conversation management
- `stream/` -- SSE parsing, stream collection, SSE response generation
- `embeddings/` -- Vector embeddings and in-memory vector store
- `structured/` -- JSON mode and tool definitions
- `rag/` -- Retrieval-augmented generation pipeline
- `agents/` -- Tool-use agent loop with iteration limits
- `pipes/` -- Server middleware integration

## Dependencies

- `@atlas/server` — only for the `withAi` pipe; the rest of the package stands alone.
- External: none. All provider calls go through `fetch`.

## Testing

All tests use mock providers. No real API calls.

```sh
bun test packages/ai/
```
</document>

<document path="packages/edge/AGENTS.md">
# @atlas/edge

TLS-terminating reverse proxy with built-in Let's Encrypt automation.
Replaces a Caddy/nginx layer in front of a Bun app.

## Exports

### Top-level (`index.ts`)
- `defineEdge(config)` — build a config object with a `.listen()` method
- `runEdge(config)` — start the edge directly, returns `RunningEdge`
- `proxy(upstream, opts?)` — handler that forwards to an upstream URL
- `files(options)` — handler that serves files from disk
- `forward(req, options, ctx)` — low-level proxy primitive
- `compressResponse(res, accept, allow)` — apply gzip/zstd to a Response
- `matchHost(host, pattern)` — host-pattern matcher (literal or `*.x.com`)
- `matchRoute(req, url, matcher?)` — route matcher (path + method)
- `isLocalHost(host)` — recognises localhost / 127.0.0.1 / ::1 / *.localhost

### ACME (`acme/index.ts`)
- `provisionCertificate(opts)` — orchestrates the full LE flow
- `generateKeyPair()` / `importKeyPair(jwk)` / `jwkThumbprint(jwk)`
- `LETSENCRYPT_PROD` / `LETSENCRYPT_STAGING` — directory URLs

### Certs (`certs/index.ts`)
- `fileStore(root)` / `memoryStore()` — `CertStore` implementations
- `issueCert(params)` — issue a fresh cert (HTTP-01 challenge)
- `loadOrCreateAccount(store)` — recover or generate an ACME account key
- `createRenewalScheduler(onRenew)` — timer-based renewal at 30 days remaining

### Site (`site/index.ts`)
- `dispatch(req, ctx, sites)` — host + route lookup with compression
- `createChallengeStore()` — in-memory ACME http-01 token store

## Types

```ts
type EdgeConfig = {
  acme?: { email: string; directoryUrl?: string; storage: string | { directory: string } }
  sites: ReadonlyArray<{
    host: string                              // "example.com" or "*.example.com"
    routes: ReadonlyArray<{
      match?: { path?: RegExp | string; method?: string | string[] }
      handler: (req, ctx) => Promise<Response>
    }>
    compress?: ReadonlyArray<"gzip" | "zstd">
  }>
  insecure?: boolean       // skip TLS (useful for tests)
  httpPort?: number        // default 80
  httpsPort?: number       // default 443
}

type ForwardContext = { remoteIp: string; tls: boolean; host: string }
```

## Usage

```ts
import { defineEdge, proxy, files } from "@atlas/edge"

defineEdge({
  acme: { email: "you@example.com", storage: "/var/atlas/edge" },
  sites: [{
    host: process.env.DOMAIN!,
    compress: ["gzip", "zstd"],
    routes: [
      { match: { path: /^\/[^/]+\/[^/]+\.git(?:\/.*)?$/ }, handler: proxy("http://api:3000") },
      { match: { path: "/static/*" }, handler: files({ root: "./public", stripPrefix: "/static" }) },
      { handler: proxy("http://web:3001") }, // catch-all
    ],
  }],
}).listen()
```

## Behaviour

- **Localhost dev** — if every site host matches `isLocalHost`, the edge
  starts a single plain-HTTP listener (no ACME, no :443). No certificate
  setup is required for development.
- **Production** — :80 serves ACME http-01 challenges and 308-redirects
  everything else to https. :443 terminates TLS using SNI-keyed certs and
  dispatches requests to sites by Host header.
- **Cert lifecycle** — on first run, missing certs are issued via LE prod
  (override with `directoryUrl: LETSENCRYPT_STAGING` for testing). Certs
  persist to `<storage>/certs/<key>/{cert,key,meta}.pem` plus a single
  `<storage>/account.json` ACME account key. A renewal timer fires 30
  days before `notAfter` and `server.reload({ tls })` swaps in the new
  pair without dropping connections.
- **Proxy headers** — every forwarded request gets `X-Real-IP`,
  `X-Forwarded-For` (appended), `X-Forwarded-Proto`, `X-Forwarded-Host`.
  Hop-by-hop headers are stripped. `Host` is rewritten to the upstream
  unless `proxy(url, { preserveHost: true })`.
- **Compression** — gzip is always available; zstd is enabled only when
  the running Bun build exposes `Bun.zstdCompressSync`. Brotli is not
  implemented — browsers fall back to gzip.

## Testing

```sh
bun test packages/edge/
```

Tests cover the DER encoder, JWS signing, host/route matchers, the
proxy header policy, and the renewal scheduler. End-to-end ACME flow is
not unit-tested — point at `LETSENCRYPT_STAGING` for live verification.
</document>

<document path="packages/email/AGENTS.md">
# @atlas/email

Provider-agnostic email transport plus a minimal HTML email shell and two
ready-to-use templates (invite, password reset).

## Transports

```ts
import { createEmailer, createResendEmailer, createConsoleEmailer } from "@atlas/email"

// auto-detect: real Resend transport when both env vars are set, otherwise console
const emailer = createEmailer({
  apiKey: process.env.RESEND_API_KEY,
  from: process.env.RESEND_FROM,
})

// or pick directly
const real = createResendEmailer({ apiKey: KEY, from: "no-reply@example.com" })
const dev  = createConsoleEmailer()  // logs subject/body, returns ok: true, logged: true
```

The console transport is the default fall-through when `apiKey` or `from` are
blank — keeps dev environments unblocked without configuring a sending domain.

```ts
type Emailer = {
  readonly enabled: boolean
  readonly send: (msg: EmailMessage) => Promise<SendResult>
}

type EmailMessage = {
  readonly to: string | readonly string[]
  readonly subject: string
  readonly html: string
  readonly text?: string
  readonly replyTo?: string
  readonly from?: string  // overrides the transport default
}

type SendResult = { ok: true; id?: string; logged?: boolean } | { ok: false; error: string }
```

`send` never throws — failures come back as `{ ok: false, error }`. Surface
those to the caller (or audit-log them) rather than ignoring.

## Templates

```ts
import { inviteEmail, passwordResetEmail } from "@atlas/email"

const invite = inviteEmail({
  inviterName: "Wess",
  product: "Atlas",
  signupUrl: "https://app.example.com/signup?invite=…",
  note: "Excited to have you!",
  brand: "Atlas",       // optional, shown at the top of the card
  accent: "#5e81ac",    // optional, color of buttons / links
})

await emailer.send({ to: "user@example.com", ...invite })
```

Templates return `{ subject, html, text }` so they drop straight into
`Emailer.send`. Both `inviteEmail` and `passwordResetEmail` accept `brand` and
`accent` for theming; omit them for an unbranded card.

### Layout helper

```ts
import { layout, escapeHtml } from "@atlas/email"

const html = layout({
  title: "Welcome",
  body: `<p>Hi ${escapeHtml(user.name)} — glad you're here.</p>`,
  brand: "Atlas",
  footer: "Atlas · self-hostable apps",
  accent: "#5e81ac",
})
```

`layout` is a single-column 560px card with a gentle Nord-flavored palette,
inline-friendly styles (works in Outlook), and a button class (`<a class="btn">…`).
Always pass user-supplied strings through `escapeHtml` before interpolating.

## Dependencies

Zero — uses `fetch` (Bun / Node 18+). No SDK dependencies.

## Adding a provider

The `Emailer` interface is the only contract. To add Postmark, SES, etc., write
a `createXxxEmailer(opts)` that returns `{ enabled, send }` and falls back to
`createConsoleEmailer()` when not configured.

## Testing

```sh
bun test packages/email/
```
</document>

<document path="packages/share/AGENTS.md">
# @atlas/share

Tiny composable helpers for sharing a URL via the channels users actually use:
the major socials (Twitter/X, Facebook, LinkedIn, Reddit), messengers
(WhatsApp, Telegram, SMS), and email (both `mailto:` links *and* server-side
send through `@atlas/email`).

The URL builders are pure functions — no DOM, no fetch, no SDKs. Render them in
React, Mantine, server-side templates, anywhere.

## Quick start

```ts
import { share, shareUrl, shareEmail, listChannels } from "@atlas/share"
import { createEmailer } from "@atlas/email"

const content = {
  url: "https://example.com/post/123",
  title: "Look at this",
  text: "A short blurb",
  hashtags: ["atlas", "bun"],   // twitter
  via: "atlas",                  // twitter
}

shareUrl("twitter", content)
// → https://twitter.com/intent/tweet?url=…&text=…&hashtags=atlas%2Cbun&via=atlas

share(content)
// → { twitter, facebook, linkedin, reddit, whatsapp, telegram, sms, email }

listChannels()
// → [{ channel: "twitter", label: "X (Twitter)" }, ...]

// Server-side share-by-email through any @atlas/email transport
const emailer = createEmailer({ apiKey: process.env.RESEND_API_KEY, from: "no-reply@example.com" })
await shareEmail({
  emailer,
  to: "friend@example.com",
  sharerName: "Wess",
  product: "Atlas",
  message: "thought you'd like this",
  content,
})
```

## ShareContent

```ts
type ShareContent = {
  url: string                          // required
  title?: string                       // headline / tweet text
  text?: string                        // longer copy / body
  hashtags?: readonly string[]         // twitter — no leading '#'
  via?: string                         // twitter handle, no leading '@'
  phone?: string                       // sms — e.g. "+15551234567"
  to?:  string | readonly string[]     // mailto
  cc?:  string | readonly string[]     // mailto
  bcc?: string | readonly string[]     // mailto
}
```

Each channel uses whichever fields make sense for it; unknown fields are
ignored. Required: `url`.

## Channels

| Channel | URL form |
|---------|----------|
| `twitter`  | `https://twitter.com/intent/tweet?url=&text=&hashtags=&via=` |
| `facebook` | `https://www.facebook.com/sharer/sharer.php?u=&quote=` |
| `linkedin` | `https://www.linkedin.com/sharing/share-offsite/?url=` |
| `reddit`   | `https://www.reddit.com/submit?url=&title=` |
| `whatsapp` | `https://wa.me/?text=` (title + text + url joined by blank lines) |
| `telegram` | `https://t.me/share/url?url=&text=` |
| `sms`      | `sms:[phone]?body=` |
| `email`    | `mailto:[to]?cc=&bcc=&subject=&body=` |

## Server-side email

`shareEmail(opts)` renders a single-column branded HTML email (uses
`@atlas/email`'s `layout` helper) and dispatches it through whatever
`Emailer` you hand it. Falls back to the console transport in dev exactly
like `inviteEmail` / `passwordResetEmail`.

```ts
type ShareEmailOptions = {
  emailer: Emailer
  to: string | readonly string[]
  from?: string
  replyTo?: string
  sharerName?: string
  product?: string
  message?: string
  content: ShareContent
  brand?: string
  accent?: string
}
```

Set `replyTo` to the sharer's email so the recipient can reply to them rather
than the sending domain.

`renderShareEmailMessage(opts)` returns the same `{ subject, html, text }`
without sending — useful for previews and tests.

## Adding a channel

Add a folder under `providers/<name>/index.ts` that exports a `ShareProvider`:

```ts
export const bluesky: ShareProvider = {
  channel: "bluesky",
  label: "Bluesky",
  build: (content) => `https://bsky.app/intent/compose?text=${encodeURIComponent(content.text ?? content.url)}`,
}
```

Then register it in `providers/index.ts` and `index.ts` (registry + channel
union).

## Dependencies

- `@atlas/email` — used by `shareEmail` for transport + HTML layout. URL
  builders themselves have zero deps and can be tree-shaken if you import
  channels directly.

## Testing

```sh
bun test packages/share/
```
</document>

<document path="packages/sso/AGENTS.md">
# @atlas/sso

Drop-in OIDC relying-party. Any Atlas app gains "Sign in with $IdP" by calling
`mountSso(cfg)` and providing two callbacks: `onAuthenticated` (claims → local
user row) and `issueSession` (set whatever session the host app uses). The
package handles discovery, PKCE, state, code exchange, id_token verification,
and back-channel logout.

## Exports

```
mountSso(cfg: SsoConfig) → readonly Route[]      mount /login + /callback + /backchannel-logout
ensureSsoStateTable(db, table?)                  idempotent CREATE TABLE IF NOT EXISTS
sweepExpiredSsoState(db, table?)                 delete expired state rows
clearDiscoveryCache()                            for tests / hot-reload
```

## Types

```
IdTokenClaims { sub, iss, aud, email?, email_verified?, name?, preferred_username?, picture?, ... }

AuthenticatedUser { localUserId: number|string, displayName? }

SessionIssuer = (conn, user, claims) => Promise<Conn> | Conn

SsoConfig {
  db: Connection
  issuerUrl: string                          // base URL — discovery doc lives at ${issuerUrl}/.well-known/openid-configuration
  clientId: string
  clientSecret: string
  redirectUri?: string                       // default: ${request.origin}${basePath}/callback
  scopes?: readonly string[]                 // default: ["openid","email","profile"] — openid is always added
  basePath?: string                          // default: "/auth/sso"
  defaultPostLoginPath?: string              // default: "/"
  stateTable?: string                        // default: "sso_state"

  onAuthenticated(db, claims) → AuthenticatedUser      // upsert local user, return its id
  issueSession(conn, user, claims) → Conn              // set cookie/JWT/etc., redirect home

  findLocalUserBySub?(db, sub) → number|string|null    // for back-channel logout
  invalidateSessions?(db, { sub, localUserId }) → void // revoke all sessions for that user
}

DiscoveryDoc { issuer, authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint?, end_session_endpoint?, id_token_signing_alg_values_supported? }
```

## Routes mounted

`mountSso` returns three routes under `basePath` (default `/auth/sso`):

| Method + Path | Purpose |
|---|---|
| `GET /login`          | Generate state + PKCE + nonce, persist them, 302 to IdP's authorize endpoint. Honors `?return_to=` for deep links. |
| `GET /callback`       | Validate state, exchange code, verify id_token, call `onAuthenticated`, then `issueSession`. |
| `POST /backchannel-logout` | Receive IdP-pushed logout token, verify, look up `localUserId` via `findLocalUserBySub`, call `invalidateSessions`. |

## Wire up

```ts
import { connect, from } from "@atlas/db"
import { router, serve } from "@atlas/server"
import { ensureSsoStateTable, mountSso, type IdTokenClaims, type SsoConfig } from "@atlas/sso"

const db = connect({ driver: "sqlite", path: "./app.db" })
await ensureSsoStateTable(db)

const cfg: SsoConfig = {
  db,
  issuerUrl: process.env.SSO_ISSUER!,
  clientId: process.env.SSO_CLIENT_ID!,
  clientSecret: process.env.SSO_CLIENT_SECRET!,
  onAuthenticated: async (db, claims) => {
    const id = await upsertUserFromClaims(db, claims)
    return { localUserId: id, displayName: claims.name ?? claims.preferred_username }
  },
  issueSession: async (conn, user, _claims) => issueLocalSession(conn, user.localUserId),
}

serve({ routes: router(...mountSso(cfg)) })
```

## State table

`ensureSsoStateTable` creates the transient row store that bridges the
/login → /callback redirect:

```sql
CREATE TABLE IF NOT EXISTS sso_state (
  state       TEXT PRIMARY KEY,
  verifier    TEXT NOT NULL,
  nonce       TEXT NOT NULL,
  return_to   TEXT NOT NULL DEFAULT '/',
  expires_at  TIMESTAMPTZ NOT NULL,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
)
```

Schedule `sweepExpiredSsoState(db)` to run periodically (rows TTL is 10 min):

```ts
setInterval(() => sweepExpiredSsoState(db), 60 * 60 * 1000)  // hourly
```

## Discovery

`@atlas/sso` fetches the IdP's discovery doc lazily on the first request
(and caches it). Tests can call `clearDiscoveryCache()` between runs.

## Dependencies

- `@atlas/auth` — JWT verification for id_tokens
- `@atlas/db` — state-row persistence
- `@atlas/server` — `mountSso` returns `Route[]` you spread into your router
- External: none. Uses `fetch` and Web Crypto.

## Compared to `@atlas/auth/social`

- `@atlas/auth/social` — provider-specific factories (Google, GitHub, Apple, …). Best for consumer apps with named providers.
- `@atlas/sso` — generic OIDC relying-party. Best for enterprise SSO (Keycloak, Auth0, Okta, Castle, anything OIDC-conformant).
</document>

<document path="packages/migrate/AGENTS.md">
# @atlas/migrate

Database migration manager using `@atlas/db` for Postgres and SQLite.

## Exports

### Migration Operations
- `up(db: Connection, dir?: string) => Promise<string[]>` - run pending migrations, returns names of applied
- `down(db: Connection, dir?: string) => Promise<string | null>` - rollback most recent migration
- `status(db: Connection, dir?: string) => Promise<MigrationStatus[]>` - list all migrations with applied status
- `ensureTable(db: Connection) => Promise<void>` - create `schema_migrations` table if missing

### File Operations
- `createMigration(dir: string, name: string) => MigrationFile` - scaffold new migration folder with up.sql/down.sql
- `scanMigrations(dir: string) => MigrationFile[]` - scan directory for migration folders, sorted by name

### Diff (schema → migration)
- `plan(db, schemas) => Promise<DiffPlan>` — compute up/down SQL by introspecting the
  live DB and comparing it to a list of `defineSchema()` results. Read-only.
- `writeDiff(db, schemas, { dir?, name? }) => Promise<DiffWriteResult>` — same plan,
  but writes a new timestamped migration folder with `up.sql`/`down.sql` if the diff
  is non-empty. Returns `{ noop: true, path: null }` when the schema is in sync.

```ts
import { migrate } from "@atlas/migrate"
import { users, posts } from "./schema"

const result = await migrate.diff(db, [users, posts], { name: "add_users" })
if (result.noop) console.log("schema in sync; nothing to write")
else console.log(`wrote ${result.path}`)
```

Postgres uses `information_schema`; SQLite uses `pragma table_info`. Type/nullability
mismatches are emitted as `-- ALTER table.col …` comments so destructive migrations
land in front of the user instead of running silently. `serial`/`integer` and PK
nullability quirks are normalized — they won't show up as spurious diffs.

### Convenience
- `migrate` - namespace object with `{ up, down, status, create, ensureTable, diff, plan }`

## Types

```ts
type MigrationFile = {
  name: string        // "20260402_add_users"
  timestamp: string   // "20260402"
  upPath: string      // full path to up.sql
  downPath: string    // full path to down.sql
}

type MigrationStatus = {
  name: string
  appliedAt: Date | null  // null = pending
}
```

## Migration Directory Structure

```
migrations/
  20260402_add_users/
    up.sql
    down.sql
  20260403_add_posts/
    up.sql
    down.sql
```

## Usage

```ts
import { connect } from "@atlas/db"
import { migrate } from "@atlas/migrate"

const db = connect({ driver: "sqlite", path: "./app.db" })

// create a new migration
migrate.create("./migrations", "add_users")

// run all pending
const ran = await migrate.up(db, "./migrations")

// check status
const statuses = await migrate.status(db, "./migrations")

// rollback last
const rolled = await migrate.down(db, "./migrations")

await db.close()
```

## Dependencies

Sibling: `@atlas/db`. Runtime: `bun:sqlite`, `node:fs`.
</document>