@everystack/mcp 0.2.0

package/src/resources/getting-started.md

@@ -0,0 +1,75 @@
+# What is everystack?
+
+everystack helps you build apps. Real apps that work on iPhones, Android phones, tablets, computers, and the web — all from the same code.
+
+You describe what you want. Claude helps you build it. everystack provides the building blocks.
+
+**A note about difficulty:** Building software is hard. Professional engineers are paid well to do this, and projects often take months or years. Claude and everystack make it much more accessible, but you are still building real software with real infrastructure. Things will break. You will hit errors you don't understand. That's normal. The key is to keep going, ask questions, and learn as you go.
+
+## How it works
+
+You start simple: a running app on your screen. Then you build from there.
+
+Every app starts the same way — a basic Expo app that works on phones, tablets, and the web. You build the screens, the navigation, the look and feel. Everything is visual and immediate.
+
+When your app needs more — user accounts, saved data, file uploads — you add those capabilities one at a time. You never throw away what you already built. Your app grows with you.
+
+## What you need to get started
+
+These are tools that run on your computer. Claude will help you install each one.
+
+**Node.js** — Runs your code. Your app is written in TypeScript (a programming language). Node.js is the engine that makes it work, like how a car needs an engine to drive.
+- Without it: Nothing runs.
+
+**git** — Tracks every change you make to your code. Like an unlimited undo button for your entire project. You can always go back to any previous version.
+- Without it: You cannot track changes or undo mistakes.
+
+**pnpm** (recommended) — A faster way to install code libraries your app depends on. Recommended but Claude can work without it.
+
+That's it. Those three tools are all you need to create an app and see it running on your computer.
+
+### When your app needs a database (later)
+
+If your app needs user accounts or saved data, you'll add a database. This is not needed to start — only when a feature demands it.
+
+**PostgreSQL** — A database that stores your app's data: users, posts, recipes, or whatever your app needs. Like a spreadsheet that your app reads and writes automatically. Read everystack://adding-database when you're ready for this step.
+
+### To deploy to the internet (later)
+
+You don't need these right away. Install them when you're ready to put your app online so other people can use it.
+
+**AWS account + AWS CLI** — AWS (Amazon Web Services) is where your app lives on the internet. Other people's computers run your app so anyone can use it. The AWS CLI is a tool that lets Claude talk to AWS from your computer.
+- Without it: Your app only works on your computer. Nobody else can use it.
+- Setting up AWS requires a credit card for verification. AWS has a free tier for the first 12 months. You control all costs and can delete everything at any time.
+
+**AWS credentials** — A password file that proves your computer is allowed to deploy to your AWS account. You create this once during setup.
+- Without them: AWS will reject all deploy commands.
+- New to AWS? Read everystack://aws-setup for a complete walkthrough of creating an account and setting up credentials.
+
+## The path from idea to running app
+
+1. **You describe your idea.** "I want to build a recipe sharing app."
+2. **Claude checks your computer.** Runs a tool to see what's installed and what's missing.
+3. **Claude helps you install anything missing.** Step by step, one tool at a time. Each one explained before you install it.
+4. **Claude creates your app.** A stock Expo app with the everystack building blocks installed.
+5. **You see it running on your computer.** Your app opens in a browser. You can change things and see updates instantly. Read everystack://first-run for details on this step.
+6. **You build together.** Describe what you want — screens, buttons, colors, layout. Claude builds it. You see changes in real time. This is where most of the work happens.
+7. **Your app grows when it needs to.** When a feature needs user accounts or saved data, Claude helps you add a database. When you need file uploads, you add that too. One thing at a time.
+8. **When you're ready, you deploy.** Your app gets a real URL that anyone can visit. This is a separate step — there's no rush.
+
+## Common questions
+
+**Do I need to know how to code?**
+Not to start. Claude writes the code and explains what it's doing. But you're building real software — the same kind that teams of engineers get paid to build. Things will break. You'll need to learn as you go. The more you understand, the better your app will be.
+
+**How much does AWS cost?**
+For a small app with low traffic, typically under $5/month for a static site and around $20/month once you add a database (the database is the main cost). AWS has a free tier for the first 12 months that covers most of what everystack uses. You can build and run locally for free with no AWS account at all.
+
+**Can I change things later?**
+Yes. everystack is built for this. Start with a simple app, add user accounts when you need them, add file uploads when you need them. You never throw away what you already built.
+
+**What if something goes wrong?**
+Claude can debug it. everystack has built-in tools that check your project for common mistakes and security issues. And git tracks every change, so you can always go back. Expect things to go wrong — that's part of building software. The tools are here to help you recover.
+
+**Do I need a Mac?**
+For now, yes. everystack's setup tools are designed for macOS. Windows and Linux support may come later.

package/src/resources/handler-options.md

@@ -0,0 +1,114 @@
+# Handler Options Reference
+
+> Complete reference for `createHandler(db, schema, options)` from `@everystack/api/handler`.
+
+## When to Use
+Read this when configuring the PostgREST handler for a V2+ app. Every option is optional -- start minimal and add as needed.
+
+## Setup
+
+```typescript
+import { createHandler } from '@everystack/api/handler';
+import * as schema from '../db/schema';
+
+const handler = createHandler(db, schema, {
+  basePath: '/api',  // Strip this prefix from incoming URLs
+  // ... options below
+});
+```
+
+Returns `(request: Request) => Promise<Response>`.
+
+## Options
+
+### auth
+```typescript
+auth: {
+  verifyToken: async (token: string) => payload | null,  // Required for auth
+  publicRoutes: ['GET'],       // Methods that skip token verification
+  publicRpc: ['health'],       // RPC functions that skip all auth (token + client)
+  roleHierarchy: ['public', 'authenticated', 'admin'],  // For RPC role gates
+  roleField: 'role',           // JWT field containing user's role
+  onAuthenticated: (user) => {},  // Callback after successful auth
+  // Client credentials (two-tier auth)
+  verifyClient: async (clientId, clientSecret, referer?) => client | null,
+  clientHeaders: { id: 'X-Client-Id', secret: 'X-Client-Secret' },
+  onClientAuthenticated: (client) => {},
+}
+```
+
+### pgSettings (RLS)
+```typescript
+pgSettings: (user, client) => ({
+  role: user?.role === 'admin' ? 'admin' : user ? 'authenticated' : 'anon',
+  'request.jwt.claims': JSON.stringify(user || { role: 'anon' }),
+  'app.user_id': String(user?.sub || ''),
+})
+```
+The `role` key triggers `SET LOCAL ROLE`. All other keys use `set_config(key, value, true)`. Everything is LOCAL scope (resets when transaction ends).
+
+### relations
+```typescript
+relations: {
+  posts: {
+    author: { table: 'users', from: 'authorId', to: 'id' },         // many-to-one
+    comments: { table: 'comments', from: 'id', to: 'postId', many: true },  // one-to-many
+  },
+}
+```
+Enables `?select=*,author(*)` embedding. Resolved via batched `WHERE IN` (no N+1).
+
+### rpc
+```typescript
+rpc: {
+  health: async (body) => ({ status: 'ok' }),                    // Function syntax
+  timeline: { fn: async (body, user) => {}, role: 'authenticated' },  // Object + role
+  admin_stats: { fn: async (body, user) => {}, role: 'admin' },
+}
+```
+Function syntax uses publicRpc/publicRoutes rules. Object syntax enforces role requirement.
+
+### hooks
+```typescript
+hooks: {
+  posts: {
+    beforeCreate: async (body, user, client) => ({ ...body, authorId: user?.sub }),
+    afterCreate: async (row, user, client) => {},
+    beforeUpdate: async (body, user, client) => body,
+    afterUpdate: async (rows, user, client) => {},
+    beforeDelete: async (user, client) => {},
+    afterDelete: async (rows, user, client) => {},
+  },
+}
+```
+`beforeCreate`/`beforeUpdate` can modify the body by returning a new object.
+
+### Access Control
+```typescript
+exposedTables: ['posts', 'profiles'],          // 404 for unlisted tables
+hiddenColumns: { users: ['passwordHash'] },     // Strip from all responses
+protectedFields: { profiles: ['role'] },        // Strip from incoming writes
+rowOwnership: { posts: { column: 'authorId', userField: 'sub' } },  // Scope writes to owner
+```
+
+### Safety Limits
+```typescript
+maxEmbedDepth: 3,     // Max relation nesting depth (default: 3)
+maxLimit: 1000,        // Max ?limit= value (default: 10000)
+```
+
+### Other
+```typescript
+softDelete: { column: 'deletedAt', tables: ['posts'] },  // DELETE -> UPDATE SET deletedAt
+naming: 'snake_case',  // Response key format ('camelCase' default)
+```
+
+## Gotchas
+
+- `pgSettings` wraps every query in a transaction. Without it, queries execute directly (no RLS).
+- `hiddenColumns` strips AFTER query execution. Columns are still in the SQL result, just removed from JSON.
+- `protectedFields` strips BEFORE hooks run. Hooks never see protected fields.
+- `exposedTables` doesn't affect RPC endpoints.
+- `rowOwnership` only affects PATCH and DELETE. Reads are governed by RLS.
+- The `role` value in pgSettings is validated against `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+- DELETE without filters returns 400 (safety). Always include at least one filter.

package/src/resources/images.md

@@ -0,0 +1,73 @@
+# Image Processing
+
+> On-demand Sharp image processing on Lambda. Import from `@everystack/images`.
+
+## When to Use
+Read this when adding image resizing, format conversion, or variant generation (V3).
+
+## Setup
+
+```typescript
+// server/image.ts
+import { createImageHandler } from '@everystack/server/image';
+
+export const handler = createImageHandler({
+  bucket: Resource.Media.name,
+  pathPrefix: '/media/',
+});
+```
+
+## URL-based Processing
+
+Images are processed on-the-fly via query parameters:
+
+```
+/media/photo.jpg?w=400&h=300&fit=cover&fm=webp&q=80
+```
+
+| Parameter | Description | Values |
+|-----------|-------------|--------|
+| `w` | Width | pixels |
+| `h` | Height | pixels |
+| `fit` | Resize mode | `cover`, `contain`, `fill`, `inside`, `outside` |
+| `fm` | Output format | `webp`, `avif`, `jpeg`, `png` |
+| `q` | Quality | 1-100 |
+
+## Variant Generation
+
+Pre-generate variants via background jobs:
+
+```typescript
+import { generateVariants } from '@everystack/images/jobs';
+
+await publishJob('image:process', {
+  key: 'uploads/photo.jpg',
+  variants: [
+    { name: 'thumb', width: 150, height: 150, fit: 'cover' },
+    { name: 'large', width: 1200, format: 'webp', quality: 85 },
+  ],
+});
+```
+
+## EXIF Extraction
+
+```typescript
+import { extractExif } from '@everystack/images';
+
+const exif = await extractExif(buffer);
+// { width, height, orientation, gps, camera, ... }
+```
+
+## Schema
+
+```typescript
+import { imagesSchema } from '@everystack/images/schema';
+// Adds: image_variants table tracking generated variants
+```
+
+## Gotchas
+
+- Sharp runs on Lambda ARM64 (uses Lambda layer or bundled binary)
+- First request for a variant is slow (processing), subsequent are cached
+- CloudFront caches processed images (set appropriate Cache-Control)
+- AVIF encoding is slower than WebP but produces smaller files

package/src/resources/index.ts

@@ -0,0 +1,224 @@
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// Resolve the directory containing resource files.
+// tsx (our runtime) polyfills __dirname in ESM. ts-jest uses CJS where __dirname is native.
+// We use a dynamic eval to avoid import.meta.url appearing in CJS output (which would throw).
+function getResourcesDir(): string {
+  // In CJS (ts-jest), __dirname is a global
+  try {
+    return (globalThis as Record<string, unknown>).__dirname as string
+      || eval('__dirname') as string;
+  } catch {
+    // In pure ESM, fall back to import.meta.url
+    const { fileURLToPath } = require('node:url');
+    return dirname(fileURLToPath(eval('import.meta.url')));
+  }
+}
+
+const RESOURCES_DIR = getResourcesDir();
+
+function loadResource(filename: string): string {
+  return readFileSync(join(RESOURCES_DIR, filename), 'utf-8');
+}
+
+interface ResourceDef {
+  uri: string;
+  name: string;
+  description: string;
+  filename: string;
+}
+
+const RESOURCES: ResourceDef[] = [
+  // Beginner — plain English intro, read first for new users
+  {
+    uri: 'everystack://getting-started',
+    name: 'Getting Started (Beginners)',
+    description:
+      'Plain English intro for complete beginners. What everystack is, what the tiers mean, what each prerequisite is and why. Read this FIRST for users with no programming experience or no existing project.',
+    filename: 'getting-started.md',
+  },
+
+  // Beginner — AWS account and credential setup
+  {
+    uri: 'everystack://aws-setup',
+    name: 'AWS Setup (Beginners)',
+    description:
+      'Step-by-step AWS account creation and IAM credential setup for beginners. Read when check_environment reports missing AWS credentials.',
+    filename: 'aws-setup.md',
+  },
+
+  // Beginner — first local run walkthrough
+  {
+    uri: 'everystack://first-run',
+    name: 'First Run (Beginners)',
+    description:
+      'What happens when you run your app locally for the first time. Explains Metro bundler, hot reload, opening in browser or phone, and common first-run errors. Read after scaffolding a new project.',
+    filename: 'first-run.md',
+  },
+
+  // Beginner — V2 transition guide (adding database to existing app)
+  {
+    uri: 'everystack://adding-database',
+    name: 'Adding a Database (V2 Transition)',
+    description:
+      'Guide for adding PostgreSQL, API handler, and authentication to an existing Expo app. Read this when a feature needs data persistence or user accounts. Covers PostgreSQL setup, V2 package installation, schema creation, handler config, auth flow, migrations, and RLS security.',
+    filename: 'adding-database.md',
+  },
+
+  // Core — read these first (for developers)
+  {
+    uri: 'everystack://core',
+    name: 'everystack Core Architecture',
+    description:
+      'Architecture, package map, V1-V2-V3 tiers, key patterns, project conventions, handler overview, CLI commands. Read this first.',
+    filename: 'core.md',
+  },
+  {
+    uri: 'everystack://security',
+    name: 'everystack Security',
+    description:
+      'Three-layer security model (Edge/API/Database), AWS IAM profiles (Create/Manage/Deploy), RLS guide with copy-paste policies, deployment checklist. Read before any auth or deployment guidance.',
+    filename: 'security.md',
+  },
+
+  // Detail — load on demand
+  {
+    uri: 'everystack://handler-options',
+    name: 'Handler Options Reference',
+    description:
+      'Complete createHandler() options: auth, relations, rpc, hooks, pgSettings, softDelete, naming, exposedTables, hiddenColumns, protectedFields, rowOwnership, cache.',
+    filename: 'handler-options.md',
+  },
+  {
+    uri: 'everystack://query-protocol',
+    name: 'Query Protocol',
+    description:
+      'PostgREST query protocol: filters (eq, neq, gt, lt, like, ilike, is, in), negation, logical groups (or, and), column selection, relation embedding, ordering, pagination, aggregates, JSON path filtering.',
+    filename: 'query-protocol.md',
+  },
+  {
+    uri: 'everystack://client-api',
+    name: 'Client API',
+    description:
+      'Typed client: createClient(), query builder (.from, .eq, .select, .order, .limit), mutations (.insert, .update, .delete), token refresh, error handling.',
+    filename: 'client-api.md',
+  },
+  {
+    uri: 'everystack://auth',
+    name: 'Authentication',
+    description:
+      'JWT auth: createAuthHandlers(), signup/signin/refresh flows, HS256 edge verification, OAuth, password hashing, token lifecycle, AuthProvider React context.',
+    filename: 'auth.md',
+  },
+  {
+    uri: 'everystack://schema-patterns',
+    name: 'Schema Design Patterns',
+    description:
+      'Drizzle schema design: pgTable, column types, relations, indexes, timestamps, soft delete, UUID vs serial, migration workflow, drizzle-kit commands.',
+    filename: 'schema-patterns.md',
+  },
+  {
+    uri: 'everystack://deployment',
+    name: 'Deployment Guide',
+    description:
+      'SST deployment: sst.config.ts setup, secrets, stages (dev/production), CloudFront, Lambda configuration, VPC, RDS Aurora Serverless, resource linking.',
+    filename: 'deployment.md',
+  },
+  {
+    uri: 'everystack://admin',
+    name: 'Admin Dashboard',
+    description:
+      'Declarative admin: AdminRoot, AdminLayout, resource config, field types, EverystackAdapter, presets, custom widgets, navigation.',
+    filename: 'admin.md',
+  },
+  {
+    uri: 'everystack://jobs',
+    name: 'Background Jobs',
+    description:
+      'SQS background workers: createWorkerHandler, publishJob, job types, dead letter queue, cron scheduling, Postgres materialization adapter.',
+    filename: 'jobs.md',
+  },
+  {
+    uri: 'everystack://storage',
+    name: 'File Storage',
+    description:
+      'S3 file storage: createStorageHandler, presigned uploads, MIME validation, CDN delivery, ownership enforcement, client upload flow.',
+    filename: 'storage.md',
+  },
+  {
+    uri: 'everystack://logging',
+    name: 'Logging & Analytics',
+    description:
+      'Structured logging: log levels, crash reports, analytics events, S3 log storage, CloudWatch ingestion trigger, client SDK, admin dashboard integration.',
+    filename: 'logging.md',
+  },
+  {
+    uri: 'everystack://security-device',
+    name: 'Device Security',
+    description:
+      'Device attestation: Apple App Attest, Google Play Integrity, RS256 device keys, biometric auth, certificate pinning.',
+    filename: 'security-device.md',
+  },
+  {
+    uri: 'everystack://testing',
+    name: 'Testing Patterns',
+    description:
+      'Testing conventions: Jest setup, TDD workflow, test file structure, mocking patterns (ESM, sharp, AWS SDK), template database isolation, integration tests.',
+    filename: 'testing.md',
+  },
+  {
+    uri: 'everystack://plugins',
+    name: 'Plugin Architecture',
+    description:
+      'Plugin system: createPluginLambdaHandler, Plugin type, PluginContext, composing handlers from multiple packages, plugin registration order.',
+    filename: 'plugins.md',
+  },
+  {
+    uri: 'everystack://ssr',
+    name: 'Server-Side Rendering',
+    description:
+      'SSR: getWebHandler, direct Drizzle queries in loaders, JSON-LD structured data, OG meta tags, cache headers, hydration debugging.',
+    filename: 'ssr.md',
+  },
+  {
+    uri: 'everystack://images',
+    name: 'Image Processing',
+    description:
+      'Sharp image processing: createImageHandler, on-demand resizing, format conversion, EXIF extraction, variant generation, CDN delivery.',
+    filename: 'images.md',
+  },
+  {
+    uri: 'everystack://events',
+    name: 'Events & WebSocket',
+    description:
+      'Real-time events: PostgreSQL LISTEN/NOTIFY, WebSocket fan-out, Lambda event bridge, client useSignal hook, table change notifications.',
+    filename: 'events.md',
+  },
+  {
+    uri: 'everystack://cli',
+    name: 'CLI Reference',
+    description:
+      'Full CLI command reference: update, db:migrate, db:seed, db:psql, console, logs:errors, logs:tail, logs:query, cache:purge, certs, channels, diag, analyze:ssr.',
+    filename: 'cli.md',
+  },
+  {
+    uri: 'everystack://project-claude-md',
+    name: 'Project CLAUDE.md Template',
+    description:
+      'Template for a project-level CLAUDE.md file. Read this and adapt it when scaffolding a new everystack app. Replace placeholders ({PROJECT_NAME}, {ONE_LINE_DESCRIPTION}, {ANNOTATED_DIRECTORY_TREE}) with actual project details.',
+    filename: 'project-claude-md.md',
+  },
+];
+
+export function registerResources(server: McpServer): void {
+  for (const r of RESOURCES) {
+    const content = loadResource(r.filename);
+    server.resource(r.name, r.uri, { mimeType: 'text/markdown' }, async () => ({
+      contents: [{ uri: r.uri, mimeType: 'text/markdown' as const, text: content }],
+    }));
+  }
+}
+
+export { RESOURCES, loadResource };

package/src/resources/jobs.md

@@ -0,0 +1,97 @@
+# Background Jobs
+
+> SQS background workers for everystack apps. Import from `@everystack/jobs`.
+
+## When to Use
+Read this when adding background processing (V3): email sending, image processing, analytics aggregation, etc.
+
+## Setup
+
+### Infrastructure
+```typescript
+// sst.config.ts
+const dlq = new sst.aws.Queue('DeadLetterQueue');
+const jobs = new sst.aws.Queue('Jobs', { dlq: dlq.arn });
+
+const worker = new sst.aws.Function('Worker', {
+  handler: 'server/worker.handler',
+  link: [database, jobs, media],
+  vpc,
+});
+
+jobs.subscribe(worker.arn);
+```
+
+### Worker Handler
+```typescript
+// server/worker.ts
+import { createWorkerHandler } from '@everystack/server/worker';
+
+export const handler = createWorkerHandler(async () => ({
+  'image:process': async (payload) => {
+    // payload: { imageId, variants: ['thumb', 'large'] }
+  },
+  'email:send': async (payload) => {
+    // payload: { to, subject, body }
+  },
+  'analytics:aggregate': async (payload) => {
+    // payload: { date, metrics: ['pageviews', 'signups'] }
+  },
+}));
+```
+
+### Dispatching Jobs
+```typescript
+import { publishJob } from '@everystack/jobs';
+
+await publishJob('image:process', {
+  imageId: 'abc-123',
+  variants: ['thumb', 'large'],
+});
+```
+
+## Client SDK
+
+```typescript
+import { createJobClient } from '@everystack/jobs/client';
+
+const jobs = createJobClient({ baseUrl: '/api' });
+await jobs.submit('email:send', { to: 'user@example.com', subject: 'Welcome' });
+```
+
+## SQS Adapter
+
+```typescript
+import { createSqsAdapter } from '@everystack/jobs';
+
+const adapter = createSqsAdapter({
+  queueUrl: Resource.Jobs.url,
+  region: 'us-east-1',
+});
+```
+
+Progressive dispatch: starts with direct function calls, moves to SQS when you need async processing.
+
+## Postgres Materialization
+
+Optional: materialize job state to PostgreSQL for dashboard visibility:
+
+```typescript
+import { jobsSchema } from '@everystack/jobs/schema';
+// Adds: jobs table with status, type, payload, result, timestamps
+```
+
+## Plugin
+
+```typescript
+import { jobsPlugin } from '@everystack/jobs/plugin';
+// Adds job dispatch routes to the handler
+```
+
+## Gotchas
+
+- Workers run in a separate Lambda (not the API Lambda)
+- Dead letter queue catches failed jobs after max retries
+- Job payloads must be JSON-serializable
+- SQS has a 256KB message size limit
+- Workers should be idempotent (SQS delivers at-least-once)

package/src/resources/logging.md

@@ -0,0 +1,91 @@
+# Logging & Analytics
+
+> Structured logging, crash reports, and analytics. Import from `@everystack/logging`.
+
+## When to Use
+Read this when adding observability to a V2+ app.
+
+## Setup
+
+### Server-side Logging
+```typescript
+import { createLogSink } from '@everystack/logging';
+
+const logSink = createLogSink({
+  storage: 's3',
+  bucket: Resource.LogsBucket.name,
+});
+
+// Pass to Lambda handler
+createLambdaHandler({ logSink, /* ... */ });
+```
+
+### Client-side SDK
+```typescript
+import { createLogClient } from '@everystack/logging/client';
+
+const logger = createLogClient({
+  baseUrl: '/api/logs',
+  batchSize: 10,
+  flushInterval: 30000,
+});
+
+logger.info('Page viewed', { page: '/home' });
+logger.error('Payment failed', { error, userId });
+logger.event('button_click', { button: 'signup' });
+```
+
+## Log Levels
+
+| Level | Use case |
+|-------|----------|
+| `debug` | Development-only, verbose details |
+| `info` | Normal operations, user actions |
+| `warn` | Degraded state, retries, fallbacks |
+| `error` | Failed operations, caught exceptions |
+| `fatal` | Unrecoverable errors, crash reports |
+
+## Schema
+
+```typescript
+import { loggingSchema } from '@everystack/logging/schema';
+// Adds: logs table with level, source, message, data, traceId, userId, deviceId, etc.
+```
+
+Include in your handler's schema for database-backed log querying.
+
+## CloudWatch Trigger
+
+```typescript
+import { createLogIngestionHandler } from '@everystack/logging/trigger';
+// Processes CloudWatch log events, extracts structured data, stores in S3/DB
+```
+
+## Admin Integration
+
+```typescript
+import { loggingAdminConfig } from '@everystack/logging/admin';
+// Adds log viewer widget to admin dashboard
+```
+
+## CLI Integration
+
+```bash
+everystack logs:errors --stage dev          # Recent errors (DB -> S3 fallback)
+everystack logs:query --stage dev --level error --source api
+everystack logs:tail --stage dev            # Raw CloudWatch output
+```
+
+## Plugin
+
+```typescript
+import { loggingPlugin } from '@everystack/logging/plugin';
+// Adds log ingestion routes and log query RPC
+```
+
+## Gotchas
+
+- Logs are stored in S3 (cheap, durable) with optional DB materialization
+- Client SDK batches logs and flushes periodically (not per-event)
+- `logs:errors` queries DB first, falls back to S3 if logs table doesn't exist
+- `logs:tail` reads CloudWatch (Lambda container output), not application logs