@mars-stack/cli 0.2.0 → 0.2.2

package/template/.cursor/skills/test-api-route/SKILL.md

@@ -0,0 +1,219 @@
+# Skill: Test an API Route
+
+Write unit tests for a MARS API route using Vitest, mock-auth, and Prisma mocking.
+
+## When to Use
+
+Use this skill when the user asks to test an API endpoint, write backend tests, or add test coverage for a route handler.
+
+## Architecture
+
+MARS API route tests:
+- Import and call the exported handler function directly (no HTTP server needed)
+- Mock Prisma, auth session, and external services
+- Assert response status and body
+- Test all paths: success, validation errors, auth errors, database errors
+
+## Template: Full API Route Test
+
+```typescript
+// src/app/api/protected/projects/route.test.ts
+import { mockAuth, createTestRequest, createTestRequestWithBody } from '@mars-stack/core/test-utils';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GET, POST } from './route';
+
+// Mock database
+const mockFindMany = vi.fn();
+const mockCreate = vi.fn();
+
+vi.mock('@/lib/prisma', () => ({
+  prisma: {
+    project: {
+      findMany: (...args: unknown[]) => mockFindMany(...args),
+      create: (...args: unknown[]) => mockCreate(...args),
+    },
+  },
+  isDatabaseError: vi.fn(() => false),
+  formatDatabaseError: vi.fn(),
+}));
+
+// Mock auth -- return a valid session
+vi.mock('@/lib/mars', () => ({
+  verifySessionForAPI: vi.fn(() => Promise.resolve(mockAuth)),
+}));
+
+describe('GET /api/protected/projects', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns projects for the authenticated user', async () => {
+    const projects = [
+      { id: '1', name: 'Project A', userId: mockAuth.userId },
+      { id: '2', name: 'Project B', userId: mockAuth.userId },
+    ];
+    mockFindMany.mockResolvedValue(projects);
+
+    const request = createTestRequest('GET', '/api/protected/projects');
+    const response = await GET(request);
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body).toHaveLength(2);
+    expect(mockFindMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { userId: mockAuth.userId },
+      }),
+    );
+  });
+
+  it('returns 401 when not authenticated', async () => {
+    const { verifySessionForAPI } = await import('@/lib/mars');
+    vi.mocked(verifySessionForAPI).mockResolvedValueOnce(null);
+
+    const request = createTestRequest('GET', '/api/protected/projects');
+    const response = await GET(request);
+
+    expect(response.status).toBe(401);
+  });
+});
+
+describe('POST /api/protected/projects', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('creates a project with valid data', async () => {
+    const newProject = { id: '3', name: 'New Project', userId: mockAuth.userId };
+    mockCreate.mockResolvedValue(newProject);
+
+    const request = createTestRequestWithBody('POST', '/api/protected/projects', {
+      name: 'New Project',
+    });
+    const response = await POST(request);
+    const body = await response.json();
+
+    expect(response.status).toBe(201);
+    expect(body.name).toBe('New Project');
+    expect(mockCreate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          name: 'New Project',
+          userId: mockAuth.userId,
+        }),
+      }),
+    );
+  });
+
+  it('returns 400 for invalid input', async () => {
+    const request = createTestRequestWithBody('POST', '/api/protected/projects', {
+      name: '', // Empty name should fail validation
+    });
+    const response = await POST(request);
+
+    expect(response.status).toBe(400);
+  });
+
+  it('returns 503 when database is unavailable', async () => {
+    const dbError = new Error("Can't reach database server");
+    Object.defineProperty(dbError, 'name', { value: 'PrismaClientInitializationError' });
+    mockCreate.mockRejectedValue(dbError);
+
+    const { isDatabaseError } = await import('@/lib/prisma');
+    vi.mocked(isDatabaseError).mockReturnValueOnce(true);
+
+    const request = createTestRequestWithBody('POST', '/api/protected/projects', {
+      name: 'Test Project',
+    });
+    const response = await POST(request);
+
+    expect(response.status).toBe(503);
+  });
+});
+```
+
+## Mock Auth Utilities
+
+MARS provides mock auth utilities via `@mars-stack/core/test-utils`:
+
+```typescript
+import { mockAuth, mockAuthAsAdmin, mockAuthAsUser } from '@mars-stack/core/test-utils';
+import { createTestRequest, createTestRequestWithBody } from '@mars-stack/core/test-utils';
+
+// mockAuth — default mock session object
+// mockAuthAsAdmin / mockAuthAsUser — role-specific variants
+// createTestRequest(method, path) — build a NextRequest without a body
+// createTestRequestWithBody(method, path, body) — build a NextRequest with JSON body
+```
+
+## Testing Patterns
+
+### Test Auth Required
+
+```typescript
+it('returns 401 when not authenticated', async () => {
+  const { verifySessionForAPI } = await import('@/lib/mars');
+  vi.mocked(verifySessionForAPI).mockResolvedValueOnce(null);
+  // ...assert 401
+});
+```
+
+### Test Role Requirement
+
+```typescript
+it('returns 403 for non-admin users', async () => {
+  const { verifySessionForAPI } = await import('@/lib/mars');
+  vi.mocked(verifySessionForAPI).mockResolvedValueOnce({ ...mockAuth, role: 'user' });
+
+  // For withRole, also mock the DB role check
+  mockFindUnique.mockResolvedValueOnce({ role: 'user' });
+
+  // ...assert 403
+});
+```
+
+### Test Validation Errors
+
+```typescript
+it('returns 400 with validation errors', async () => {
+  const request = createTestRequestWithBody('POST', '/api/protected/resource', {
+    email: 'not-an-email',
+  });
+  const response = await handler(request);
+  const body = await response.json();
+
+  expect(response.status).toBe(400);
+  expect(body.error).toBeDefined();
+});
+```
+
+### Test Database Errors
+
+```typescript
+it('returns 503 when database is down', async () => {
+  mockFindMany.mockRejectedValueOnce(new Error("Can't reach database"));
+  // ... assert 503
+});
+```
+
+## Running Tests
+
+```bash
+yarn test                     # Run all tests
+yarn test src/app/api/        # Run only API tests
+yarn test:watch               # Watch mode
+yarn test:coverage            # With coverage report
+```
+
+## Checklist
+
+- [ ] Test file created next to route (`route.test.ts`)
+- [ ] Prisma mocked with `vi.mock('@/lib/prisma')`
+- [ ] Auth session mocked with `vi.mock('@/lib/mars')`
+- [ ] `vi.clearAllMocks()` in `beforeEach`
+- [ ] Success path tested
+- [ ] 401 unauthorized tested
+- [ ] 400 validation error tested
+- [ ] 403 forbidden tested (if role-gated)
+- [ ] 503 database error tested
+- [ ] Response status AND body assertions

package/template/.cursor/skills/update-architecture-docs/SKILL.md

@@ -0,0 +1,99 @@
+# Skill: Update Architecture Docs
+
+Keep the project documentation in sync with code changes. Covers when and how to update AGENTS.md, QUALITY_SCORE.md, and related docs.
+
+## When to Use
+
+Use this skill when:
+- You have just added a new feature, service, or module
+- You have changed the database schema
+- You have completed an execution plan
+- The user asks to update docs, sync docs, or refresh documentation
+- Another skill's checklist includes "update docs"
+
+## Prerequisites
+
+- Read `AGENTS.md` for the project-level agent guide.
+- Read `docs/QUALITY_SCORE.md` for current quality grades.
+
+## Document Index
+
+| Document | Location | Purpose | Update frequency |
+|----------|----------|---------|------------------|
+| `AGENTS.md` | Repo root | First file any agent reads. Overview + pointers | On structure changes |
+| `docs/QUALITY_SCORE.md` | Docs | Quality grades by domain | After every improvement |
+| `docs/design-docs/` | Docs | Architecture decisions and design documents | On architectural changes |
+
+## When to Update Each Document
+
+### AGENTS.md
+
+Update when:
+- The directory structure changes (new route groups, new features)
+- New feature modules are added
+- The config structure changes
+- New "How to Run" commands are added
+- Key constraints change
+
+Keep it concise — AGENTS.md should fit in a single context window.
+
+### docs/QUALITY_SCORE.md
+
+Update when:
+- A quality grade changes (feature implemented, bug fixed, test added)
+- A new domain is added to the grading table
+- An execution plan is completed
+
+How to update:
+1. Find the relevant row in the appropriate table
+2. Update the grade (A/B/C/D/F)
+3. Update the notes to reflect current state
+
+```markdown
+| Dashboard | B | Basic layout with stat cards. Missing: chart widgets, date range filter |
+```
+
+## Step-by-Step: After Adding a Feature
+
+1. **QUALITY_SCORE.md** — Update the grade for the relevant domain:
+
+```markdown
+| Billing | B | Stripe checkout, portal, webhook. Missing: usage-based billing |
+```
+
+2. **AGENTS.md** — If the feature adds new directories or conventions:
+
+```markdown
+├── features/
+│   └── billing/         # Subscription management
+```
+
+3. **Execution plan** — Mark tasks complete, update verification:
+
+```markdown
+- [x] **3.1 Billing page** — Done. `src/app/(protected)/billing/page.tsx`
+```
+
+## Step-by-Step: After a Schema Change
+
+1. **AGENTS.md** — Update the schema file listing if new schema files added
+2. **QUALITY_SCORE.md** — Update database-related grades
+3. **Design docs** — Add a design doc if the schema change represents a significant architectural decision
+
+## Validation
+
+After updating docs, verify:
+
+1. **No broken links** — Check that referenced files exist
+2. **Consistent terminology** — Use the same names as the code
+3. **Up-to-date grades** — Quality scores reflect actual state
+4. **AGENTS.md fits in context** — Keep it under ~200 lines
+
+## Checklist
+
+- [ ] Identified which documents need updating
+- [ ] AGENTS.md updated (if structure or workflow change)
+- [ ] QUALITY_SCORE.md grades updated
+- [ ] Design docs updated (if architectural decision)
+- [ ] No broken internal links
+- [ ] Execution plan marked as complete (if applicable)

package/template/AGENTS.md

@@ -0,0 +1,104 @@
+# Project Agent Guide
+
+> First file any agent reads. Fits in a single context window by design.
+> This file is generated by Mars and customized per project.
+
+## Overview
+
+This is a Next.js SaaS application generated by [Mars](https://github.com/mars-js/mars). It includes authentication, role-based access control, design tokens, structured logging, and rate limiting out of the box.
+
+**Tech stack:** Next.js 16 (App Router), TypeScript, Prisma (PostgreSQL), Tailwind CSS v4, Zod, Vitest, Playwright.
+
+## Architecture (Layer Model)
+
+```
+Presentation   src/app/          Pages, layouts, API routes (may import from any layer)
+     ↓
+Features       src/features/     Feature modules with components/, server/, hooks/
+     ↓
+Library        src/lib/          Wiring layer: mars.ts (core re-exports), prisma.ts
+     ↓
+Packages       @mars-stack/core      Auth, email, rate limiting, env, logging, SEO
+               @mars-stack/ui        Primitives, patterns, hooks, design tokens
+     ↓
+Database       prisma/schema/    Prisma schema files (base.prisma, auth.prisma, ...)
+```
+
+**Dependency direction is strictly top-down.** Features never import from other features. Shared logic goes in `src/lib/`.
+
+## Directory Structure
+
+```
+src/
+├── app/                      Next.js App Router
+│   ├── (auth)/               Auth pages (sign-in, register, forgot/reset password, verify)
+│   ├── (protected)/          Authenticated pages (dashboard, settings)
+│   ├── api/                  API routes
+│   │   ├── auth/             Public auth endpoints (login, signup, forgot, reset, verify)
+│   │   ├── protected/        Authenticated API routes (must use withAuth/withRole/withOwnership)
+│   │   └── csrf/             CSRF token endpoint
+│   └── layout.tsx            Root layout with providers
+├── config/
+│   ├── app.config.ts         Single source of truth: identity, features, services, theme
+│   └── routes.ts             Route constants
+├── features/
+│   └── auth/                 Auth feature module
+│       ├── context/          AuthContext provider
+│       ├── server/           Server-only auth logic (user queries, session, consent)
+│       └── validators.ts     Zod validation schemas
+├── lib/
+│   ├── mars.ts               Re-exports from @mars-stack/core (logger, auth middleware, email, etc.)
+│   └── prisma.ts             Prisma client singleton
+├── styles/
+│   ├── globals.css           CSS entry point
+│   └── brand.css             Brand token overrides
+└── proxy.ts                  Route protection, CSRF validation, auth redirects (Next.js 16 proxy)
+```
+
+## Key Constraints
+
+1. **Protected API routes must use auth middleware** — `withAuth`, `withRole`, or `withOwnership` from `@/lib/mars`.
+2. **Never import across features** — `src/features/billing/` cannot import from `src/features/auth/`. Shared logic goes in `src/lib/`.
+3. **Use design tokens, not raw colors** — No `bg-blue-500`. Use semantic tokens from `@mars-stack/ui/styles`.
+4. **Server modules must import `"server-only"`** — Any file under `*/server/` needs `import 'server-only'` as its first import.
+5. **Parse data at the boundary** — Zod validation on every API route input.
+6. **User-scoped queries use session userId** — Never accept userId from request params for authorization.
+7. **Constant-time comparison for secrets** — Use `constantTimeEqual` from `@mars-stack/core`, never `===`.
+
+## Config
+
+`src/config/app.config.ts` is the single source of truth for:
+- App identity (name, URL, support email)
+- Feature flags (auth, admin, billing, notifications, etc.)
+- Service providers (email, storage, database, payments, etc.)
+- Theme (primary/secondary color, font, design direction)
+
+## How to Run
+
+```bash
+yarn dev              # Start Next.js dev server
+yarn build            # Production build
+yarn test             # Run Vitest unit tests
+yarn test:e2e         # Run Playwright e2e tests
+yarn lint             # ESLint
+yarn db:push          # Push Prisma schema to database
+yarn db:generate      # Generate Prisma client
+yarn db:seed          # Seed database
+yarn db:studio        # Open Prisma Studio
+```
+
+## Working Discipline
+
+1. **Commit after every step.** When executing a plan, commit after each completed task — not at the end. Version control is the progress log. Each commit message should reference the plan and step (e.g., `feat(billing): add Subscription model (billing-plan step 1.1)`).
+2. **Document every executed plan.** All plans — whether they started in a chat, a Cursor plan file, or someone's head — must end up in `docs/exec-plans/completed/` with decisions, discoveries, and outcomes recorded. Use the `capture-conversation-context` skill.
+3. **Feed conversations back.** Decisions, discoveries, and context that live only in chat threads are invisible to future agents. See [docs/design-docs/conversation-as-system-record.md](docs/design-docs/conversation-as-system-record.md).
+
+## Pointers
+
+- **Architecture details:** [docs/design-docs/](docs/design-docs/)
+- **Core beliefs:** [docs/design-docs/core-beliefs.md](docs/design-docs/core-beliefs.md)
+- **Conversation feedback:** [docs/design-docs/conversation-as-system-record.md](docs/design-docs/conversation-as-system-record.md)
+- **Execution plans:** [docs/exec-plans/](docs/exec-plans/)
+- **Quality scores:** [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md)
+- **Skills:** [.cursor/skills/](.cursor/skills/)
+- **Rules:** [.cursor/rules/](.cursor/rules/)

package/template/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Application Architecture
+
+## Layer Model
+
+```mermaid
+flowchart TD
+    Presentation["Presentation Layer<br/>src/app/ — Pages, layouts, API routes"]
+    Features["Feature Layer<br/>src/features/ — Domain modules"]
+    Library["Library Layer<br/>src/lib/ — Wiring (mars.ts, prisma.ts)"]
+    Packages["Package Layer<br/>@mars-stack/core, @mars-stack/ui"]
+    Database["Database Layer<br/>prisma/schema/ — Prisma models"]
+
+    Presentation --> Features
+    Presentation --> Library
+    Presentation --> Packages
+    Features --> Library
+    Features --> Packages
+    Library --> Packages
+    Packages --> Database
+```
+
+**Dependency direction is strictly top-down.** A lower layer never imports from a higher layer. Features never import from other features.
+
+## Cross-Cutting Concerns
+
+All cross-cutting infrastructure is wired through `configureMars()` in `src/lib/mars.ts`:
+
+| Concern | Mechanism | Import |
+|---------|-----------|--------|
+| Authentication | JWE sessions (HKDF + A256GCM) | `@/lib/mars` → `withAuth`, `withRole`, `withOwnership` |
+| CSRF Protection | HMAC tokens with session fingerprint binding | `@/lib/mars` → `generateCSRFToken`, `validateCSRFRequest` |
+| Logging | Pino structured logging (domain-scoped loggers) | `@/lib/mars` → `logger`, `authLogger`, `apiLogger` |
+| Error Handling | Typed API errors with consistent response format | `@/lib/mars` → `handleApiError` |
+| Rate Limiting | Upstash Redis with in-memory fallback | `@mars-stack/core/rate-limit` |
+| Email | Provider interface (SendGrid, Resend, Console) | `@/lib/mars` → `sendEmail` |
+| SEO | JSON-LD structured data builders | `@/lib/mars` → `buildOrganizationJsonLd`, etc. |
+| Env Validation | Zod-based lazy proxy with build-time relaxation | `@/lib/mars` → `env`, `validateJWTSecret` |
+
+## Database Schema
+
+Prisma schema files live in `prisma/schema/`:
+
+- `base.prisma` — Datasource config, generator config
+- `auth.prisma` — User, Session, VerificationToken models
+
+**Naming conventions:** Models are PascalCase singular (`User`, not `Users`). Fields are camelCase. Relations use the model name as the field name.
+
+**Entity relationships:**
+```
+User 1──* Session          (active sessions per user)
+User 1──* VerificationToken (email verification / password reset)
+```
+
+## API Route Conventions
+
+**Public auth routes** (`src/app/api/auth/`):
+- Rate limited via `checkRateLimit`
+- Validate input with Zod schemas
+- Return consistent JSON responses via `handleApiError`
+
+**Protected routes** (`src/app/api/protected/`):
+- Wrapped with `withAuth`, `withRole`, or `withOwnership`
+- UserId comes from the verified session, never from request params
+- CSRF validation handled by middleware for state-changing methods
+
+**Handler pattern:**
+```typescript
+import { withAuth } from '@/lib/mars';
+
+export const GET = withAuth(async (request, context, session) => {
+  // session.userId is verified
+  // Use prisma with userId in where clause
+});
+```
+
+## Client-Side Patterns
+
+- **AuthContext:** Provides `user`, `isLoading`, `logout` via React Context. Wraps the app in `src/app/providers.tsx`.
+- **Forms:** `useZodForm` hook from `@mars-stack/ui/hooks` for type-safe form state with Zod validation.
+- **Server vs Client Components:** Pages are server components by default. Interactive components use `"use client"` directive. Auth state comes from AuthContext (client) or session verification (server).
+
+## Design Token System
+
+Three-layer OKLCH system:
+
+1. **Primitives** (`@mars-stack/ui/styles/primitives.css`): Raw OKLCH color scales — `--brand-50` through `--brand-950`, plus neutral, feedback colors
+2. **Semantic Tokens** (`@mars-stack/ui/styles/tokens.css`): Intent-mapped tokens — `--surface-primary`, `--text-primary`, `--border-default`, etc. Includes `.dark` overrides.
+3. **Theme** (`@mars-stack/ui/styles/theme.css`): Tailwind CSS v4 `@theme` block wiring semantic tokens to utility classes
+
+**Override path:** Projects customize via `src/styles/brand.css` which overrides primitive values. The semantic layer automatically adapts.
+
+## Proxy (Middleware)
+
+`src/proxy.ts` runs on every matched request (Next.js 16 uses `proxy.ts` instead of `middleware.ts`):
+
+1. Coming-soon mode redirect
+2. JWT_SECRET validation
+3. Session decryption (non-blocking — null session = unauthenticated)
+4. CSRF validation for state-changing API requests
+5. Auth route redirect (authenticated users → dashboard)
+6. Protected route redirect (unauthenticated users → sign-in with callback URL)
+7. Admin route access control (role check from session)

package/template/docs/QUALITY_SCORE.md

@@ -0,0 +1,20 @@
+# Quality Score
+
+Grades by domain. Updated as features are built and tested.
+
+**Grading scale:**
+- **A** — Complete, tested, documented, meets all quality bars
+- **B** — Functional with minor gaps
+- **C** — Partially implemented, needs significant work
+- **D** — Scaffolded but not implemented
+- **F** — Missing entirely
+
+| Domain | Grade | Notes |
+|--------|-------|-------|
+| Auth API | A | Rate limited, CSRF protected, tested |
+| Auth pages | B+ | All flows present. Terms/privacy links need real pages |
+| Middleware | B | Route protection, CSRF validation, auth redirects |
+| Dashboard | D | Placeholder — needs real content |
+| Settings | D | Read-only — needs forms for profile, password, sessions |
+| Navigation | D | Needs responsive nav shell |
+| Accessibility | N/A | Audit pending |

package/template/docs/design-docs/conversation-as-system-record.md

@@ -0,0 +1,70 @@
+# Design Doc: Conversation as System Record
+
+**Status:** Accepted
+**Created:** 2026-03-11
+
+## Problem
+
+Agent conversations produce valuable context — architectural decisions, trade-off analysis, debugging insights, root cause analysis — that evaporates when the chat session ends. Future agents (and humans) working on the same codebase have no access to why decisions were made, what alternatives were considered, or what pitfalls were discovered.
+
+This is the same problem the Harness Engineering team identified: *"Knowledge that lives in Google Docs, chat threads, or people's heads is not accessible to the system."* The solution for conversations is the same as for design docs and plans — feed them back into the repository.
+
+## Principle
+
+**Every significant agent conversation must produce a persistent artifact in the repository.** The artifact type depends on the conversation:
+
+| Conversation Type | Artifact Location | Format |
+|---|---|---|
+| Planning / roadmap | `docs/exec-plans/active/` → `completed/` | Execution plan markdown |
+| Architecture decision | `docs/design-docs/` | Design doc markdown |
+| Bug investigation | `docs/exec-plans/active/` | Bug fix plan with root cause |
+| Feature implementation | `docs/exec-plans/completed/` | Completed plan with decisions |
+| Refactoring rationale | `docs/design-docs/` | Design doc explaining why |
+| Quality/debt discovery | `docs/QUALITY_SCORE.md` + `docs/exec-plans/tech-debt.md` | Grade updates + debt items |
+
+## What to Capture
+
+Not every message needs to be saved. Capture the **decisions and their context**, not the transcript:
+
+1. **What was decided** — the actual choice made
+2. **What alternatives were considered** — and why they were rejected
+3. **What was discovered** — bugs found, constraints identified, assumptions invalidated
+4. **What changed** — files modified, architecture updated, quality scores adjusted
+5. **What remains** — open questions, known limitations, follow-up work
+
+## What NOT to Capture
+
+- The conversational back-and-forth (tone, corrections, false starts)
+- Implementation details already visible in the code diff
+- Obvious choices that don't need justification
+
+## Process
+
+### During the conversation
+
+1. When a significant decision is made, note it. Don't wait until the end.
+2. When an unexpected constraint is discovered (e.g., "Next.js 16 uses proxy.ts, not middleware.ts"), document it immediately in the relevant artifact.
+3. When a plan is being executed, update the plan file as tasks complete.
+
+### At the end of the conversation
+
+1. If the conversation produced a plan, ensure it's in `docs/exec-plans/` with correct status.
+2. If architectural decisions were made, ensure they're in `docs/design-docs/` or in `ARCHITECTURE.md`.
+3. If quality changed, update `docs/QUALITY_SCORE.md`.
+4. If tech debt was discovered, update `docs/exec-plans/tech-debt.md`.
+5. If core beliefs were validated or updated, update `docs/design-docs/core-beliefs.md`.
+
+### For future agents
+
+The `AGENTS.md` file points to `docs/` as the knowledge base. Future agents should:
+
+1. Read `docs/exec-plans/completed/` to understand how the system was built and why
+2. Read `docs/design-docs/` to understand architectural decisions
+3. Read `docs/QUALITY_SCORE.md` to understand current state and priorities
+4. Read `docs/exec-plans/tech-debt.md` to understand known limitations
+
+## Origin
+
+This design doc was created after executing the Mars Product Roadmap — a plan that served as the complete blueprint for building the Mars system. The plan itself was originally stored in a Cursor-specific file (`.cursor/plans/`), invisible to all future agents. Moving it to `docs/exec-plans/completed/mars-product-roadmap.md` was the first application of this principle.
+
+The Mars Product Roadmap is the most important completed execution plan in the repository. It documents every phase of the system's construction, every cross-cutting concern, every key decision made during execution, and the influencing principles from the Harness Engineering article on agent-first development.

package/template/docs/design-docs/core-beliefs.md

@@ -0,0 +1,43 @@
+# Core Beliefs
+
+Architectural opinions that govern this project. Enforced mechanically where possible via linters and structural tests.
+
+## Data Validation
+
+- Parse data shapes at the boundary — Zod validation on every API route input.
+- Fail fast with clear, structured error messages.
+
+## Security
+
+- Server-only modules must import `"server-only"` to prevent client-side bundling of secrets.
+- User-scoped queries must include userId from the session, never from request parameters.
+- Constant-time comparison (`constantTimeEqual`) for all secret/token comparisons.
+- Derive keys with domain separators, never reuse JWT_SECRET directly.
+
+## Architecture
+
+- No cross-feature imports. Shared logic goes in `src/lib/`.
+- `app.config.ts` is the single source of truth for feature flags and service providers.
+- Composition over inheritance — `configureMars()` wires services via function composition.
+
+## Technology
+
+- Prefer boring, well-documented technology: Next.js, Prisma, Tailwind, Zod.
+- Official SDKs over wrapper libraries for third-party integrations.
+
+## Testing
+
+- Every server function needs a corresponding test.
+- Structural tests validate architecture invariants (dependency direction, auth coverage, design tokens).
+
+## Accessibility
+
+- All UI components must meet WCAG 2.1 AA (keyboard navigation, focus management, ARIA, contrast).
+
+## Agent-First Development
+
+- The repository is the system of record. All knowledge lives in code, docs, skills, and rules.
+- Every agent conversation must feed decisions and context back into the repository as persistent artifacts (execution plans, design docs, quality score updates). See `docs/design-docs/conversation-as-system-record.md`.
+- All executed plans are documented in `docs/exec-plans/completed/`. Plans are references for future agents — they record what was built, what decisions were made, and what was discovered.
+- Commit after every step in a plan. Version control is the progress log. Do not batch all changes into one commit at the end.
+- When documentation falls short, promote the rule into a linter with an agent-legible error message.

package/template/docs/design-docs/index.md

@@ -0,0 +1,8 @@
+# Design Documents
+
+Catalog of architectural decisions and design rationale for this project.
+
+| Document | Status | Summary |
+|----------|--------|---------|
+| [core-beliefs.md](core-beliefs.md) | Active | Architectural operating principles |
+| [conversation-as-system-record.md](conversation-as-system-record.md) | Accepted | Every conversation feeds back into the repo |