create-kuckit-app 2.0.2 → 2.1.0

package/templates/base/AGENTS.md

@@ -2,507 +2,244 @@
 
 > **Main Documentation**: [Kuckit SDK](https://github.com/draphonix/kuckit)
 
-## Quick Start
+## Commands
 
 ```bash
-bun install              # Install dependencies
-docker compose up -d     # Start PostgreSQL
-bun run db:push          # Sync schema to database (dev) or db:migrate (prod)
-bun run dev              # Start dev servers (web + server)
-```
-
-## Project Structure
-
-```
-__APP_NAME_KEBAB__/
-├── apps/
-│   ├── server/              # Express + oRPC backend (port 3000)
-│   └── web/                 # React + TanStack Router frontend (port 3001)
-├── packages/
-│   └── items-module/        # Example Kuckit module (reference implementation)
-├── .env.example             # Environment template
-├── docker-compose.yml       # PostgreSQL container
-├── drizzle.config.ts        # Drizzle pointing to @kuckit/db + module schemas
-└── turbo.json               # Turborepo configuration
-```
-
-**Note:** Core packages (`api`, `auth`, `db`, `domain`, `contracts`) are installed from npm as `@kuckit/*` dependencies, not copied into your project.
-
-## Bootstrap Architecture
-
-Kuckit uses **bootstrap packages** to minimize boilerplate in your apps:
-
-### Server Bootstrap (`@kuckit/app-server`)
-
-```typescript
-// apps/server/src/server.ts
-import 'dotenv/config'
-import { runKuckitServer } from '@kuckit/app-server'
-import { loadConfig } from './config/server'
-import { getModuleSpecs } from './config/modules'
-
-runKuckitServer({
-	loadConfig,
-	getModuleSpecs,
-}).catch((error) => {
-	console.error('Failed to start server:', error)
-	process.exit(1)
-})
-```
-
-**What `runKuckitServer` handles automatically:**
-
-- Express app creation with CORS, JSON parsing
-- DI container setup with per-request scoping
-- Module loading and API route wiring
-- Auth, health, metrics endpoints
-- Graceful shutdown
-
-**Customization via hooks:**
-
-```typescript
-runKuckitServer({
-	loadConfig,
-	getModuleSpecs,
-	hooks: {
-		onAppCreated: (app) => app.use(helmet()),
-		onContainerReady: (container) => {
-			/* warm caches */
-		},
-		onServerReady: (port) => console.log(`Listening on ${port}`),
-	},
-})
-```
+# Development
+bun run dev              # Start web + server
+bun run dev:server       # Backend only (port 3000)
+bun run dev:web          # Frontend only (port 5173)
+bun run check-types      # Typecheck all packages
+bun run build            # Build all packages
 
-### Web Bootstrap (`@kuckit/app-web`)
+# Database
+bun run db:push          # Sync schema to database
+bun run db:studio        # Open Drizzle Studio
 
-```typescript
-// apps/web/src/main.tsx
-import { createKuckitWebProvider } from '@kuckit/app-web'
-import { createAuthClient } from 'better-auth/react'
-import config from '../kuckit.config'
-
-const authClient = createAuthClient({
-  baseURL: import.meta.env.VITE_SERVER_URL,
-})
+# Module management
+bunx kuckit generate module <name>   # Scaffold new module
+bunx kuckit doctor                   # Validate setup
 
-const KuckitProvider = createKuckitWebProvider({
-  config,
-  authClient,
-})
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <KuckitProvider>
-      <App />
-    </KuckitProvider>
-  </StrictMode>
-)
 ```
 
-**Access registries and auth via hooks:**
+## Architecture
 
-```typescript
-import { useKuckitWeb, useAuth } from '@kuckit/app-web'
+**Clean Architecture** with **Awilix DI** and **modular plugin system**.
 
-function MyComponent() {
-	const { routeRegistry, navRegistry, slotRegistry } = useKuckitWeb()
-	const authClient = useAuth()
-	const { data: session } = authClient.useSession()
-}
-```
-
-## Module Development
-
-Kuckit uses a **module-based architecture** where each module contains its own Clean Architecture layers internally.
-
-### Module Structure
-
-```
-packages/your-module/
-├── src/
-│   ├── domain/          # Entities with Zod schemas
-│   ├── ports/           # Repository interfaces
-│   ├── adapters/        # Drizzle implementations
-│   ├── usecases/        # Business logic
-│   ├── api/             # oRPC routers
-│   ├── ui/              # React components (optional)
-│   ├── module.ts        # Server module definition
-│   └── client-module.ts # Client module definition
-```
-
-### Creating a New Module
-
-```bash
-bunx kuckit generate module your-module
-```
-
-This scaffolds a full Clean Architecture module. Then:
-
-1. Implement your domain entities in `domain/`
-2. Define repository interfaces in `ports/`
-3. Implement adapters in `adapters/`
-4. Create use cases in `usecases/`
-5. Expose API in `api/` via oRPC router
-6. Register module in `apps/server/src/config/modules.ts`
-7. Add client module to `apps/web/src/modules.client.ts`
-8. Add schema path to `drizzle.config.ts` in project root
-9. Run `bun run db:push` to create the table
+| Layer          | Packages                                                  | Purpose                            |
+| -------------- | --------------------------------------------------------- | ---------------------------------- |
+| Interface      | `apps/web`, `apps/server`                                 | React + Express entry points       |
+| Bootstrap      | `@kuckit/app-server`, `@kuckit/app-web`                   | DI wiring, module loading          |
+| SDK            | `@kuckit/sdk`, `@kuckit/sdk-react`                        | Module system, registries          |
+| Application    | `packages/application`, `packages/api`                    | Use cases, oRPC procedures         |
+| Domain         | `packages/domain`, `packages/contracts`                   | Entities, ports, DTOs              |
+| Infrastructure | `packages/infrastructure`, `packages/db`, `packages/auth` | Repositories, Drizzle, Better-Auth |
 
 ### Dependency Rules
 
-```
-domain → No dependencies (pure Zod schemas)
-   ↓
-ports → Depends on domain only
-   ↓
-usecases → Depends on ports and domain
-   ↓
-adapters → Implements ports, depends on domain
-   ↓
-api → Wires everything together
-```
+| Layer            | CAN Import                     | CANNOT Import           |
+| ---------------- | ------------------------------ | ----------------------- |
+| `domain`         | (nothing)                      | everything else         |
+| `application`    | domain                         | infrastructure, api, db |
+| `infrastructure` | domain                         | application, api        |
+| `contracts`      | zod                            | domain, application     |
+| `api`            | domain, application, contracts | infrastructure, db      |
 
-## SDK Module System
+## Module Quick Reference
 
-> **SDK Documentation**: For comprehensive module patterns, see [@kuckit/sdk](https://github.com/draphonix/kuckit)
-
-### Module Lifecycle
-
-Modules are loaded in a specific sequence:
-
-```
-1. createKuckitContainer()
-   └─► Core services registered (logger, db, cache, eventBus)
-
-2. loadKuckitModules({ modules: [...] })
-   ├─► Phase 1: register() - DI bindings for all modules
-   ├─► Phase 2: registerApi() - API registrations collected
-   ├─► Phase 3: onApiRegistrations callback (wire routers HERE)
-   ├─► Phase 4: onBootstrap() - Startup logic
-   └─► Phase 5: onComplete callback
-
-3. Application runs...
-
-4. disposeContainer()
-   └─► For each module: onShutdown()
+```bash
+bunx kuckit generate module billing --org acme
 ```
 
-### Core Services (CoreCradle)
-
-After container creation, these services are available via DI:
-
-| Token              | Type               | Lifetime  | Description                 |
-| ------------------ | ------------------ | --------- | --------------------------- |
-| `config`           | `CoreConfig`       | Singleton | Application configuration   |
-| `db`               | Drizzle            | Singleton | Database query builder      |
-| `dbPool`           | `Pool`             | Singleton | PostgreSQL connection pool  |
-| `logger`           | `Logger`           | Singleton | Structured logging          |
-| `eventBus`         | `EventBus`         | Singleton | Pub/sub event system        |
-| `clock`            | `Clock`            | Singleton | Time abstraction (testable) |
-| `cacheStore`       | `CacheStore`       | Singleton | Key-value cache             |
-| `rateLimiterStore` | `RateLimiterStore` | Singleton | Rate limiting               |
-| `auth`             | Better-Auth        | Singleton | Authentication utilities    |
-| `requestId`        | `string`           | Scoped    | Per-request unique ID       |
-| `requestLogger`    | `Logger`           | Scoped    | Logger with request context |
-
-### Server Module Definition
+**Server module** (`src/module.ts`):
 
 ```typescript
-import { defineKuckitModule, asClass, asFunction } from '@kuckit/sdk'
+import { defineKuckitModule, asFunction } from '@kuckit/sdk'
 
 export const kuckitModule = defineKuckitModule({
-	id: 'myapp.billing',
-	displayName: 'Billing',
-	version: '1.0.0',
-	capabilities: ['nav.item', 'api.public'],
-
+	id: 'myorg.billing',
 	register(ctx) {
-		// Phase 1: Register DI bindings
 		ctx.container.register({
-			invoiceRepository: asClass(InvoiceRepository).scoped(),
-			createInvoice: asFunction(makeCreateInvoiceUseCase).scoped(),
+			invoiceRepo: asFunction(({ db }) => makeInvoiceRepo(db)).scoped(),
 		})
 	},
-
 	registerApi(ctx) {
-		// Phase 2: Register API routes
-		ctx.addApiRegistration({
-			type: 'rpc-router',
-			name: 'invoices',
-			router: invoicesRouter,
-		})
-	},
-
-	onBootstrap(ctx) {
-		// Phase 4: Startup logic (cache warming, logging, etc.)
-		ctx.container.resolve('logger').info('Billing module started')
-	},
-
-	onShutdown(ctx) {
-		// Cleanup on shutdown
-		ctx.container.resolve('logger').info('Billing module stopped')
+		ctx.addApiRegistration({ type: 'rpc-router', name: 'invoices', router: invoicesRouter })
 	},
 })
 ```
 
-### Client Module Definition
+**Client module** (`src/client-module.ts`):
 
 ```typescript
 import { defineKuckitClientModule } from '@kuckit/sdk-react'
 
 export const kuckitClientModule = defineKuckitClientModule({
-	id: 'myapp.billing',
-	displayName: 'Billing',
-	capabilities: ['nav.item', 'dashboard.widget'],
-
-	routes: [
-		{
-			id: 'billing-invoices',
-			path: '/billing/invoices',
-			component: InvoicesPage,
-		},
-	],
-
-	navItems: [
-		{
-			id: 'billing-nav',
-			label: 'Billing',
-			href: '/billing/invoices',
-			icon: CreditCard,
-			order: 50,
-		},
-	],
-
-	slots: {
-		'dashboard.widgets': {
-			component: BillingWidget,
-			order: 10,
-		},
-	},
+	id: 'myorg.billing',
+	routes: [{ id: 'billing', path: '/billing', component: BillingPage }],
+	navItems: [{ id: 'billing-nav', label: 'Billing', href: '/billing', order: 50 }],
 })
 ```
 
-### Module Capabilities
+**Critical**: oRPC routers must be wired before `RPCHandler` is created. See [SDK docs](./packages/sdk/AGENTS.md).
 
-Modules can declare capabilities for discovery:
+## Coding Standards
 
-- `nav.item` - Provides navigation items
-- `settings.page` - Has settings page
-- `dashboard.widget` - Provides dashboard widgets
-- `api.webhook` - Exposes webhooks
-- `api.public` - Has public API endpoints
-- `slot.provider` - Provides slot components
+- **TypeScript**: Strict mode, no `any`, explicit return types
+- **Factory pattern**: Use `createX()` functions, not direct imports with side effects
+- **DI lifetimes**: `singleton()` for shared, `scoped()` for per-request
+- **Naming**: entities `invoice.ts`, ports `invoice-repository.ts`, use cases `create-invoice.ts`
 
-### useRpc with TanStack Query
+## Issue Tracking (bd)
 
-Module components use the `useRpc` hook to access the API:
-
-```typescript
-import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
-import { useRpc } from '@kuckit/sdk-react'
-
-interface ItemsRpc {
-	items: {
-		list: (input: Record<string, never>) => Promise<Item[]>
-		create: (input: { name: string }) => Promise<Item>
-	}
-}
-
-function ItemsPage() {
-	const rpc = useRpc<ItemsRpc>()
-	const queryClient = useQueryClient()
-
-	const { data: items = [], isLoading } = useQuery({
-		queryKey: ['items'],
-		queryFn: () => rpc.items.list({}),
-	})
-
-	const createMutation = useMutation({
-		mutationFn: (data: { name: string }) => rpc.items.create(data),
-		onSuccess: () => queryClient.invalidateQueries({ queryKey: ['items'] }),
-	})
-
-	// ... component render
-}
-```
-
-### oRPC Router Wiring (Important)
-
-oRPC's `RPCHandler` captures the router object at construction time. Module routers must be wired **before** the handler is created:
-
-1. Modules register routers via `registerApi()` hook
-2. Server wires routers in `onApiRegistrations` into a **mutable router object**
-3. `RPCHandler` is created **after** modules are loaded
-
-```typescript
-// apps/server/src/rpc-router-registry.ts
-export const rootRpcRouter = { ...appRouter }
-
-export const wireModuleRpcRouters = (registrations: ApiRegistration[]) => {
-	for (const reg of registrations) {
-		if (reg.type === 'rpc-router') {
-			rootRpcRouter[reg.name] = reg.router
-		}
-	}
-}
+```bash
+bd ready                              # Show unblocked work
+bd create "Title" -t feature -p 1     # Create issue
+bd update bd-42 --status in_progress  # Claim task
+bd close bd-42 --reason "Done"        # Complete
 ```
 
-### REST Router Pattern
-
-For modules that need direct Express response access (e.g., AI streaming with `pipeUIMessageStreamToResponse`), use REST routers instead of oRPC:
-
-```typescript
-// In your module's registerApi()
-ctx.addApiRegistration({
-	type: 'rest-router',
-	name: 'ai',
-	router: createAiRouter(),
-	prefix: '/ai', // Optional, defaults to /<name>
-})
-```
+Types: `bug`, `feature`, `task`, `epic`, `chore` | Priorities: `0` (critical) → `4` (backlog)
 
-REST routers are mounted at `/api<prefix>` (e.g., `/api/ai/chat`). They receive:
+## AI Planning Documents
 
-- Per-request scoped container via `req.scope`
-- Session via `req.scope.cradle.session`
-- Full Express `Request` and `Response` objects
+Store in `history/` directory, not repo root.
 
-### Typing DI in Routers
+## AI Tool Preferences
 
-Use a module-local interface to type `context.di.cradle`:
+**Codebase exploration** (prefer gkg MCP):
 
-```typescript
-// In your module's router file
-interface BillingCradle {
-	createInvoice: (input: CreateInvoiceInput) => Promise<Invoice>
-}
-
-export const invoicesRouter = {
-	create: protectedProcedure.input(createInvoiceSchema).handler(async ({ input, context }) => {
-		const { createInvoice } = context.di.cradle as BillingCradle
-		return createInvoice(input)
-	}),
-}
-```
+- `mcp__gkg__search_codebase_definitions` - Find functions, classes, interfaces by name
+- `mcp__gkg__get_definition` - Jump to definition from a line of code
+- `mcp__gkg__get_references` - Find all usages of a symbol
+- `mcp__gkg__read_definitions` - Read multiple definition bodies efficiently
+- `mcp__gkg__repo_map` - Get API-style map of directories
 
-## Common Tasks
+**Web/code search & documentation** (prefer Docker Toolkit MCP over built-in):
 
-### Add a new API endpoint
+- `mcp__MCP_DOCKER__web_search_exa` - Real-time web search with content scraping
+- `mcp__MCP_DOCKER__resolve-library-id` - Resolve library name to Context7 ID (call first)
+- `mcp__MCP_DOCKER__get-library-docs` - Fetch up-to-date library documentation from Context7
 
-1. Define input/output schemas in `domain/`
-2. Create use case in `usecases/`
-3. Add to router in `api/`
+**File editing** (prefer morph MCP):
 
-### Add a new database table
+- `mcp__morph_mcp__edit_file` - Fast, accurate edits using `// ... existing code ...` placeholders
+- `mcp__morph_mcp__warpgrep_codebase_search` - **Prefer over built-in Grep** for semantic-aware, faster searches with better context
 
-1. Define schema in your module's `adapters/` directory
-2. Run `bun run db:generate`
-3. Run `bun run db:migrate`
+**Frontend UI** (use `frontend-design` skill + shadcn MCP - do NOT create custom UI components):
 
-### Add authentication to an endpoint
+- Load the `frontend-design` skill for distinctive, production-grade interfaces
+- `mcp__shadcn__search_items_in_registries` - Find components by name
+- `mcp__shadcn__view_items_in_registries` - View component details and files
+- `mcp__shadcn__get_item_examples_from_registries` - Get usage examples/demos
+- `mcp__shadcn__get_add_command_for_items` - Get CLI command to add components
 
-```typescript
-import { protectedProcedure } from '@kuckit/api'
-
-export const myRouter = {
-	protectedRoute: protectedProcedure.input(mySchema).handler(async ({ input, context }) => {
-		const { user } = context // Authenticated user
-		// ...
-	}),
-}
-```
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_START -->
 
-## Scripts
+## MCP Agent Mail: coordination for multi-agent workflows
 
-| Command                | Description                            |
-| ---------------------- | -------------------------------------- |
-| `bun run dev`          | Start all dev servers                  |
-| `bun run build`        | Build all packages                     |
-| `bun run check-types`  | Type check all packages                |
-| `bun run lint`         | Run ESLint on all packages             |
-| `bun run lint:fix`     | Fix ESLint issues automatically        |
-| `bun run format`       | Format code with Prettier              |
-| `bun run format:check` | Check formatting without changes       |
-| `bun run db:generate`  | Generate migration from schema changes |
-| `bun run db:migrate`   | Apply pending migrations               |
-| `bun run db:studio`    | Open Drizzle Studio                    |
+What it is
 
-## Code Quality
+- A mail-like layer that lets coding agents coordinate asynchronously via MCP tools and resources.
+- Provides identities, inbox/outbox, searchable threads, and advisory file reservations, with human-auditable artifacts in Git.
 
-This project includes pre-configured code quality tools:
+Why it's useful
 
-- **ESLint** - TypeScript linting with recommended rules
-- **Prettier** - Code formatting
-- **Husky** - Git hooks for pre-commit checks
-- **lint-staged** - Run linters on staged files only
+- Prevents agents from stepping on each other with explicit file reservations (leases) for files/globs.
+- Keeps communication out of your token budget by storing messages in a per-project archive.
+- Offers quick reads (`resource://inbox/...`, `resource://thread/...`) and macros that bundle common flows.
 
-Pre-commit hooks automatically run `lint-staged` which:
+How to use effectively
 
-1. Runs ESLint on staged `.ts/.tsx/.js/.jsx` files
-2. Runs Prettier on all staged files
+1. Same repository
+   - Register an identity: call `ensure_project`, then `register_agent` using this repo's absolute path as `project_key`.
+   - Reserve files before you edit: `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true)` to signal intent and avoid conflict.
+   - Communicate with threads: use `send_message(..., thread_id="FEAT-123")`; check inbox with `fetch_inbox` and acknowledge with `acknowledge_message`.
+   - Read fast: `resource://inbox/{Agent}?project=<abs-path>&limit=20` or `resource://thread/{id}?project=<abs-path>&include_bodies=true`.
+   - Tip: set `AGENT_NAME` in your environment so the pre-commit guard can block commits that conflict with others' active exclusive file reservations.
 
-To bypass hooks (not recommended): `git commit --no-verify`
+2. Across different repos in one project (e.g., Next.js frontend + FastAPI backend)
+   - Option A (single project bus): register both sides under the same `project_key` (shared key/path). Keep reservation patterns specific (e.g., `frontend/**` vs `backend/**`).
+   - Option B (separate projects): each repo has its own `project_key`; use `macro_contact_handshake` or `request_contact`/`respond_contact` to link agents, then message directly. Keep a shared `thread_id` (e.g., ticket key) across repos for clean summaries/audits.
 
-## Environment Variables
+Macros vs granular tools
 
-See `.env.example` for required variables:
+- Prefer macros when you want speed or are on a smaller model: `macro_start_session`, `macro_prepare_thread`, `macro_file_reservation_cycle`, `macro_contact_handshake`.
+- Use granular tools when you need control: `register_agent`, `file_reservation_paths`, `send_message`, `fetch_inbox`, `acknowledge_message`.
 
-- `DATABASE_URL` - PostgreSQL connection string
-- `BETTER_AUTH_SECRET` - Auth session secret
-- `BETTER_AUTH_URL` - Auth callback URL
-- `PORT` - Server port (default: 3000)
-- `VITE_SERVER_URL` - API URL for frontend
+Common pitfalls
 
-## Troubleshooting
+- "from_agent not registered": always `register_agent` in the correct `project_key` first.
+- "FILE_RESERVATION_CONFLICT": adjust patterns, wait for expiry, or use a non-exclusive reservation when appropriate.
+- Auth errors: if JWT+JWKS is enabled, include a bearer token with a `kid` that matches server JWKS; static bearer is used only when JWT is disabled.
 
-### 404 Errors on API Calls
+## Integrating with Beads (dependency-aware task planning)
 
-**Symptom**: `POST /rpc/items/list 404 (Not Found)` with multiple retries
+Beads provides a lightweight, dependency-aware issue database and a CLI (`bd`) for selecting "ready work," setting priorities, and tracking status. It complements MCP Agent Mail's messaging, audit trail, and file-reservation signals. Project: [steveyegge/beads](https://github.com/steveyegge/beads)
 
-**Cause**: Server and client modules are out of sync. The client has a module registered but the server doesn't.
+Recommended conventions
 
-**Fix**: Ensure both files register the same modules:
+- **Single source of truth**: Use **Beads** for task status/priority/dependencies; use **Agent Mail** for conversation, decisions, and attachments (audit).
+- **Shared identifiers**: Use the Beads issue id (e.g., `bd-123`) as the Mail `thread_id` and prefix message subjects with `[bd-123]`.
+- **Reservations**: When starting a `bd-###` task, call `file_reservation_paths(...)` for the affected paths; include the issue id in the `reason` and release on completion.
 
-- `apps/server/src/config/modules.ts` - Server modules
-- `apps/web/src/modules.client.ts` - Client modules
+Typical flow (agents)
 
-**Prevention**: Run `bunx kuckit doctor` to detect mismatches.
+1. **Pick ready work** (Beads)
+   - `bd ready --json` → choose one item (highest priority, no blockers)
+2. **Reserve edit surface** (Mail)
+   - `file_reservation_paths(project_key, agent_name, ["src/**"], ttl_seconds=3600, exclusive=true, reason="bd-123")`
+3. **Announce start** (Mail)
+   - `send_message(..., thread_id="bd-123", subject="[bd-123] Start: <short title>", ack_required=true)`
+4. **Work and update**
+   - Reply in-thread with progress and attach artifacts/images; keep the discussion in one thread per issue id
+5. **Complete and release**
+   - `bd close bd-123 --reason "Completed"` (Beads is status authority)
+   - `release_file_reservations(project_key, agent_name, paths=["src/**"])`
+   - Final Mail reply: `[bd-123] Completed` with summary and links
 
-### "Relation does not exist" Database Errors
+Mapping cheat-sheet
 
-**Symptom**: `error: relation "items" does not exist`
+- **Mail `thread_id`** ↔ `bd-###`
+- **Mail subject**: `[bd-###] …`
+- **File reservation `reason`**: `bd-###`
+- **Commit messages (optional)**: include `bd-###` for traceability
 
-**Cause**: Module schema not registered in `drizzle.config.ts`.
+Event mirroring (optional automation)
 
-**Fix**: Add the module's schema path to `drizzle.config.ts` (in project root):
+- On `bd update --status blocked`, send a high-importance Mail message in thread `bd-###` describing the blocker.
+- On Mail "ACK overdue" for a critical decision, add a Beads label (e.g., `needs-ack`) or bump priority to surface it in `bd ready`.
 
-```typescript
-schema: [
-	'./node_modules/@kuckit/db/dist/schema/auth.js',
-	'./packages/your-module/src/adapters',
-],
-```
+Pitfalls to avoid
 
-Then run:
+- Don't create or manage tasks in Mail; treat Beads as the single task queue.
+- Always include `bd-###` in message `thread_id` to avoid ID drift across tools.
 
-```bash
-bun run db:generate
-bun run db:migrate
-```
+<!-- MCP_AGENT_MAIL_AND_BEADS_SNIPPET_END -->
 
-### Module Not Appearing in Navigation
+## Landing the Plane (Session Completion)
 
-**Symptom**: Module pages work but nav items don't show.
+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
 
-**Cause**: Client module not registered or missing `navItems`.
+**MANDATORY WORKFLOW:**
 
-**Fix**: Verify module is in `apps/web/src/modules.client.ts` and defines `navItems` in `defineKuckitClientModule()`.
+1. **File issues for remaining work** - Create issues for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **PUSH TO REMOTE** - This is MANDATORY:
+   ```bash
+   git pull --rebase
+   bd sync
+   git push
+   git status  # MUST show "up to date with origin"
+   ```
+5. **Clean up** - Clear stashes, prune remote branches
+6. **Verify** - All changes committed AND pushed
+7. **Hand off** - Provide context for next session
 
-## Related Documentation
+**CRITICAL RULES:**
 
-- [Kuckit SDK](https://github.com/draphonix/kuckit)
-- [oRPC](https://orpc.dev)
-- [Better-Auth](https://better-auth.com)
-- [Drizzle ORM](https://orm.drizzle.team)
-- [TanStack Router](https://tanstack.com/router)
+- Work is NOT complete until `git push` succeeds
+- NEVER stop before pushing - that leaves work stranded locally
+- NEVER say "ready to push when you are" - YOU must push
+- If push fails, resolve and retry until it succeeds