feat: Woodpecker CI pipeline + project docs (P0-007, P0-008)

Add Woodpecker CI with install, typecheck, lint, format, test, and
build steps. Add CLAUDE.md for Claude Code sessions. Update AGENTS.md
with project-specific package map and architecture rules.

Closes #7, Closes #8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.woodpecker/ci.yml

@@ -0,0 +1,57 @@
+variables:
+  - &node_image 'node:22-alpine'
+  - &install_deps |
+    corepack enable
+    pnpm install --frozen-lockfile
+
+when:
+  - event: [push, pull_request, manual]
+
+steps:
+  install:
+    image: *node_image
+    commands:
+      - *install_deps
+
+  typecheck:
+    image: *node_image
+    commands:
+      - *install_deps
+      - pnpm typecheck
+    depends_on:
+      - install
+
+  lint:
+    image: *node_image
+    commands:
+      - *install_deps
+      - pnpm lint
+    depends_on:
+      - install
+
+  format:
+    image: *node_image
+    commands:
+      - *install_deps
+      - pnpm format:check
+    depends_on:
+      - install
+
+  test:
+    image: *node_image
+    commands:
+      - *install_deps
+      - pnpm test
+    depends_on:
+      - install
+
+  build:
+    image: *node_image
+    commands:
+      - *install_deps
+      - pnpm build
+    depends_on:
+      - typecheck
+      - lint
+      - format
+      - test

AGENTS.md

@@ -1,4 +1,4 @@
-# Agent Guidelines
+# Agent Guidelines — Mosaic Stack
 
 ## Required Load Order
 
@@ -8,23 +8,48 @@
 4. `~/.config/mosaic/guides/E2E-DELIVERY.md`
 5. `AGENTS.md` (this file)
 6. Runtime-specific guide: `~/.config/mosaic/runtime/<runtime>/RUNTIME.md`
-7. `.mosaic/repo-hooks.sh`
 
-## Session Lifecycle
+## Project Context
+
+Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo with NestJS gateway, Next.js web dashboard, Pi SDK agent runtime, and plugin architecture for Discord/Telegram.
+
+## Package Map
+
+| Package            | Purpose                         | Key Dependencies                 |
+| ------------------ | ------------------------------- | -------------------------------- |
+| `apps/gateway`     | NestJS API + WebSocket hub      | Fastify, Socket.IO, Pi SDK, OTEL |
+| `apps/web`         | Next.js dashboard               | React 19, Tailwind               |
+| `packages/types`   | Shared TypeScript contracts     | class-validator                  |
+| `packages/db`      | Drizzle ORM schema + migrations | drizzle-orm, postgres            |
+| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaic/db          |
+| `packages/brain`   | Data layer (PG-backed)          | @mosaic/db                       |
+| `packages/queue`   | Valkey task queue + MCP         | ioredis                          |
+| `packages/coord`   | Mission coordination            | @mosaic/queue                    |
+| `packages/cli`     | Unified CLI + Pi TUI            | Ink, Pi SDK                      |
+| `plugins/discord`  | Discord channel plugin          | discord.js                       |
+| `plugins/telegram` | Telegram channel plugin         | Telegraf                         |
+
+## Architecture Rules
+
+1. Gateway is the single API surface — all clients connect through it
+2. Pi SDK is ESM-only — gateway and CLI must use ESM
+3. Socket.IO typed events defined in `@mosaic/types` enforce compile-time contracts
+4. OTEL auto-instrumentation loads before NestJS bootstrap
+5. BetterAuth manages auth tables; schema defined in `@mosaic/db`
+6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
+7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)
+
+## Development Workflow
 
 ```bash
-bash scripts/agent/session-start.sh
+docker compose up -d          # Infrastructure
-bash scripts/agent/critical.sh
+pnpm install                  # Dependencies
-bash scripts/agent/session-end.sh
+pnpm typecheck && pnpm lint && pnpm format:check  # Quality gates
 ```
 
-## Shared Tools
-
-- Quality and orchestration guides: `~/.config/mosaic/guides/`
-- Shared automation tools: `~/.config/mosaic/tools/`
-
 ## Repo-Specific Notes
 
-- Add project constraints and workflows here.
+- DTOs in `*.dto.ts` files at module boundaries
-- Implement hook functions in `.mosaic/repo-hooks.sh`.
+- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
-- Scratchpads are mandatory for non-trivial tasks.
+- NodeNext module resolution in all tsconfigs
+- Scratchpads are mandatory for non-trivial tasks

CLAUDE.md

@@ -0,0 +1,45 @@
+# CLAUDE.md — Mosaic Stack
+
+## Project
+
+Self-hosted, multi-user AI agent platform. TypeScript monorepo.
+
+## Stack
+
+- **API**: NestJS + Fastify adapter (`apps/gateway`)
+- **Web**: Next.js 16 + React 19 (`apps/web`)
+- **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`)
+- **Auth**: BetterAuth (`packages/auth`)
+- **Agent**: Pi SDK (`packages/agent`, `packages/cli`)
+- **Queue**: Valkey 8 (`packages/queue`)
+- **Build**: pnpm workspaces + Turborepo
+- **CI**: Woodpecker CI
+- **Observability**: OpenTelemetry → Jaeger
+
+## Commands
+
+```bash
+pnpm typecheck        # TypeScript check (all packages)
+pnpm lint             # ESLint (all packages)
+pnpm format:check     # Prettier check
+pnpm test             # Vitest (all packages)
+pnpm build            # Build all packages
+
+# Database
+pnpm --filter @mosaic/db db:push      # Push schema to PG (dev)
+pnpm --filter @mosaic/db db:generate  # Generate migrations
+pnpm --filter @mosaic/db db:migrate   # Run migrations
+
+# Dev
+docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
+pnpm --filter @mosaic/gateway exec tsx src/main.ts  # Start gateway
+```
+
+## Conventions
+
+- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
+- NodeNext module resolution
+- Explicit `@Inject()` decorators in NestJS (tsx/esbuild doesn't support emitDecoratorMetadata)
+- DTOs in `*.dto.ts` files at module boundaries
+- OTEL tracing imported before NestJS bootstrap (`import './tracing.js'`)
+- All three gates must pass before push: typecheck, lint, format:check

docs/TASKS.md

@@ -7,7 +7,7 @@
 | P0-001 | done        | Phase 0   | Scaffold monorepo                                             | #60 | #1    |
 | P0-002 | done        | Phase 0   | @mosaic/types — migrate and extend shared types               | #65 | #2    |
 | P0-003 | done        | Phase 0   | @mosaic/db — Drizzle schema and PG connection                 | #67 | #3    |
-| P0-004 | not-started | Phase 0   | @mosaic/auth — BetterAuth email/password setup                | —   | #4    |
+| P0-004 | done        | Phase 0   | @mosaic/auth — BetterAuth email/password setup                | #68 | #4    |
 | P0-005 | done        | Phase 0   | Docker Compose — PG 17, Valkey 8, SigNoz                      | #65 | #5    |
 | P0-006 | done        | Phase 0   | OTEL foundation — OpenTelemetry SDK setup                     | #65 | #6    |
 | P0-007 | not-started | Phase 0   | CI pipeline — Woodpecker config                               | —   | #7    |