aayushus-skills 1.0.0

package/agent-config/howto.md

@@ -0,0 +1,194 @@
+---
+tags: [howto, ai-tools, windsurf, vscode, claude-code, setup]
+---
+
+# How to wire AI coding agents to follow project guidelines
+
+This vault contains two sets of rules that all AI coding agents should follow:
+- **Design system** — `design/SKILL.md` + supporting files (Prism)
+- **Engineering guidelines** — `guidelines/` (architecture, security, performance, code quality, documentation)
+
+This guide explains how to load them into Windsurf, VS Code Copilot, and Claude Code so agents follow them automatically — without you having to paste context into every conversation.
+
+---
+
+## Two-layer model
+
+Rules split into two layers so they work across multiple projects (Anti Gravity, new projects, etc.) without rewriting anything:
+
+**Layer 1 — Universal (global, set once)**
+Stack-agnostic hard rules: security principles, code quality, performance budgets, Prism design system, observability. These never change between projects.
+
+**Layer 2 — Project-specific (per repo)**
+Stack decisions, architectural choices, module structure. Different for every project.
+
+| File | Layer | For | Contains |
+|---|---|---|---|
+| `windsurfrules-global` | Universal | Windsurf global settings | Security, code quality, performance, design system — all projects |
+| `project-templates/windsurfrules-node-prisma` | Project | `.windsurfrules` in Node/Prisma repos | Stack-specific rules for this project |
+| `project-templates/windsurfrules-blank` | Project | `.windsurfrules` in any new repo | Template to fill in for a new project |
+| `copilot-instructions.md` | Both | VS Code Copilot | Critical universal rules, compact |
+| `CLAUDE.md` | Both | Claude Code | Rules + skill loading instructions |
+
+The full guidelines are always the source of truth.
+
+---
+
+## Windsurf
+
+### Step 1 — Global rules (one-time setup, applies to every project)
+
+1. Open Windsurf
+2. `Cmd+,` → search **"Rules"** → click **Edit Global Rules**
+3. Paste the full contents of `windsurfrules-global`
+4. Save
+
+Every Cascade conversation in every workspace now follows the universal rules automatically.
+
+### Step 2 — Per-project rules (stack + architecture decisions)
+
+For an existing Node.js + Prisma project:
+```bash
+cp /path/to/obsidian/04_Resources/Skills/agent-config/project-templates/windsurfrules-node-prisma \
+   /your-project/.windsurfrules
+```
+
+For a new project (Anti Gravity, etc.):
+```bash
+cp /path/to/obsidian/04_Resources/Skills/agent-config/project-templates/windsurfrules-blank \
+   /your-project/.windsurfrules
+# Then fill in the stack, decisions, and repo structure sections
+```
+
+Windsurf reads `.windsurfrules` from the project root automatically — no further configuration needed.
+
+**The two layers stack**: global rules apply everywhere, `.windsurfrules` adds project context on top. An agent in Anti Gravity gets the universal security/quality/design rules plus Anti Gravity's specific stack decisions.
+
+---
+
+## VS Code — GitHub Copilot
+
+### Per-project (workspace instructions)
+
+```bash
+mkdir -p /your-project/.github
+cp /path/to/obsidian/04_Resources/Skills/agent-config/copilot-instructions.md \
+   /your-project/.github/copilot-instructions.md
+```
+
+VS Code reads `.github/copilot-instructions.md` automatically in Copilot Chat and inline suggestions. Requires VS Code ≥ 1.90. No setting needed — just commit the file.
+
+### User-level (applies to all projects)
+
+1. `Cmd+,` → search **"Copilot Instructions"**
+2. Click **Edit in settings.json**
+3. Add:
+
+```json
+"github.copilot.chat.codeGeneration.instructions": [
+  {
+    "text": "PASTE CONTENTS OF copilot-instructions.md HERE"
+  }
+]
+```
+
+---
+
+## Claude Code
+
+### Per-project
+
+```bash
+cp /path/to/obsidian/04_Resources/Skills/agent-config/CLAUDE.md /your-project/CLAUDE.md
+```
+
+Claude Code reads `CLAUDE.md` from the project root automatically at the start of every session.
+
+### Global (applies to all projects)
+
+```bash
+cp /path/to/obsidian/04_Resources/Skills/agent-config/CLAUDE.md ~/.claude/CLAUDE.md
+```
+
+Project-level and global `CLAUDE.md` are merged — use global for universal rules, project-level for repo-specific context.
+
+### Design system skill (Claude Code only)
+
+The Prism design system is already set up as a Claude Code skill in this vault. When working on UI, tell Claude:
+
+```
+use the prism-design skill
+```
+
+Claude will load `design/SKILL.md` and the relevant pattern files automatically. No extra setup needed.
+
+---
+
+## What each tool sees
+
+```
+Windsurf global settings (windsurfrules-global)
+  └─ Universal rules: security, code quality, performance budgets, Prism design
+  └─ Active on every conversation, every project — Anti Gravity, new projects, all of them
+
+.windsurfrules (project root — different per project)
+  └─ Stack decisions: "this project uses Supabase not Prisma"
+  └─ Architecture choices: "cursor pagination, ULIDs, REST not GraphQL"
+  └─ Current context: "billing module, don't touch auth branch"
+
+.github/copilot-instructions.md (project root)
+  └─ Compact version of universal rules for Copilot's shorter context window
+  └─ Committed to repo — teammates get it automatically
+
+CLAUDE.md (project root or ~/.claude/)
+  └─ Universal rules + instructions to load Prism skill for UI work
+  └─ Points to full guidelines for deep dives
+```
+
+### Result for any project
+
+An agent in **any** project gets:
+1. Universal hard rules (from global settings) — automatically
+2. That project's stack and architecture decisions (from `.windsurfrules`) — from the repo
+3. Design system (from Prism skill or CLAUDE.md reference) — on demand
+
+---
+
+## Keeping rules in sync
+
+When guidelines change (new architectural decision, updated security rule, etc.):
+
+1. Update the source file in `guidelines/` or `design/`
+2. Update the relevant section in `windsurfrules`, `copilot-instructions.md`, and `CLAUDE.md`
+3. If you used Windsurf global rules, re-paste the updated content into settings
+
+The distillation files should always reflect the most critical rules from the full guidelines. If a rule is important enough to be in the guidelines, it's important enough to be in the distillation.
+
+---
+
+## New project checklist
+
+When starting a new project (Anti Gravity, anything else):
+
+- [ ] Windsurf global rules already set — nothing to do
+- [ ] Copy `project-templates/windsurfrules-blank` → `.windsurfrules` in project root
+- [ ] Fill in: stack, architecture decisions, repo structure, current focus
+- [ ] Copy `copilot-instructions.md` → `.github/copilot-instructions.md`
+- [ ] Copy `CLAUDE.md` → project root `CLAUDE.md`
+- [ ] Commit all three so teammates get them automatically
+
+## Adding a new IDE or coding LLM
+
+The universal rules (security, quality, performance, design system) are written in plain markdown — they work in any tool that accepts a system prompt or rules file:
+
+| Tool | Where to paste `windsurfrules-global` |
+|---|---|
+| Windsurf | Settings → Edit Global Rules |
+| Cursor | Settings → Rules for AI (global) or `.cursorrules` in project root |
+| Cline (VS Code) | Extension settings → System Prompt |
+| Aider | `--system-prompt` flag or `.aider.conf.yml` |
+| GitHub Copilot | `.github/copilot-instructions.md` or user settings.json |
+| Claude Code | `~/.claude/CLAUDE.md` (global) or `CLAUDE.md` (project) |
+| Any chat-based LLM | Paste as the first message or system prompt |
+
+For any new tool: paste `windsurfrules-global` as the system/global rules, then add project context from the relevant `.windsurfrules` template.

package/agent-config/project-templates/windsurfrules-blank

@@ -0,0 +1,50 @@
+# Project-specific rules — [PROJECT NAME]
+# Copy to .windsurfrules in the project root
+# Global rules apply on top of these via Windsurf settings
+
+## Stack
+[e.g. TypeScript + Next.js + Supabase + Vercel]
+[e.g. Python + FastAPI + SQLAlchemy + PostgreSQL]
+[e.g. Go + Gin + GORM + MySQL]
+
+---
+
+## Architecture decisions made for this project
+
+| Decision | Choice | Reason |
+|---|---|---|
+| Database | | |
+| Auth | | |
+| Queue / async | | |
+| Primary keys | | |
+| API style | | |
+| Deployment | | |
+
+---
+
+## Project-specific hard rules
+
+[Add rules specific to this codebase here — things that differ from the global defaults]
+[e.g. "This project uses Supabase RLS instead of app-level tenancy filtering"]
+[e.g. "All API routes are in /app/api/ — never in /pages/api/"]
+[e.g. "Use server actions for mutations, not API routes"]
+
+---
+
+## Current focus / context
+
+[Optional: add sprint/task context here to help the agent stay relevant]
+[e.g. "Currently building the billing module — Stripe webhooks + subscription state machine"]
+[e.g. "Do not touch the auth module — it's being refactored in a separate branch"]
+
+---
+
+## Repo structure
+
+[Brief map of the repo so the agent doesn't guess]
+[e.g.]
+[src/]
+[  app/        — Next.js App Router pages]
+[  components/ — Shared React components (use Prism design system)]
+[  lib/        — Server-side utilities, DB client, auth helpers]
+[  types/      — Shared TypeScript types]

package/agent-config/project-templates/windsurfrules-node-prisma

@@ -0,0 +1,73 @@
+# Project-specific rules — Node.js + Prisma + PostgreSQL + BullMQ
+# Copy to .windsurfrules in the project root
+# Global rules (windsurfrules-global) apply on top of these via Windsurf settings
+
+## Stack
+TypeScript strict + Node.js + Express + Prisma + PostgreSQL + Redis + BullMQ.
+AI service: Python 3.12 + FastAPI (separate process, separate failure domain).
+Frontend: Next.js + React + Prism design system.
+
+---
+
+## Multi-tenancy (existential — never bypass)
+- Every Prisma query on tenant-scoped data MUST filter by `tenantId` — enforced by middleware, but always include explicitly
+- `tenantId` comes from the authenticated session — never from URL params or request body
+- Shared database, shared schema, `tenantId` column — not schema-per-tenant
+- Soft deletes only — `deletedAt` timestamp, never hard DELETE on tenant data
+- No `ON DELETE CASCADE` on tenant-scoped tables
+- Unauthorized reads return 404 not 403 — prevents existence leak
+
+## IDs & pagination
+- ULIDs for all primary keys — not auto-increment integers, not UUIDs
+- Cursor-based pagination only — never offset/limit on large tables
+- Max page size 100 items, default 25
+
+## Database
+- All DB access via Prisma — no raw SQL except `$queryRaw` with tagged templates (requires ticket)
+- Migrations: expand/contract pattern — additive first, destructive deferred to a later deploy
+- Run `CONCURRENTLY` for index creation on large tables
+- No N+1 — use Prisma `include/select`, never query inside a loop
+- Slow query threshold: 50ms dev, 500ms prod
+
+## Queuing
+- All async work via BullMQ on Redis — not Kafka, SQS, RabbitMQ
+- Outbox pattern: write event to DB first, worker picks it up — never `queue.add()` directly from HTTP handler
+- Job defaults: 5 retries, exponential backoff (2s base), idempotent
+- Circuit breaker: open after 5 failures in 10s, stay open 30s
+
+## Auth
+- Argon2id for passwords: `time=3, memory=64MB, parallelism=4`
+- Argon2id for API keys — hashed before storage, shown once only
+- Opaque 256-bit session tokens in Redis — NOT JWTs for user sessions
+- MFA required for `owner` and `admin` roles (TOTP, RFC 6238)
+- Rate limits: 100 req/60s per user (default), 5/60s for login + password-reset
+
+## API design
+- REST + JSON — no GraphQL
+- URL versioning: `/api/v1/`, `/api/v2/`
+- Standard error envelope: `{ code, message, correlationId, details }`
+- Every endpoint: timeout, rate limit, Zod input validation
+
+## Config
+- One place reads `process.env`: `shared/config.ts` with Zod schema
+- All secrets in Doppler — never `.env` files committed, never in code
+
+## Timeouts
+- Internal HTTP calls: 10s
+- Fast external APIs: 5s
+- Slow external APIs: 30s
+- AI calls (async only): 60s
+- Prisma queries: 15s
+
+## Decisions already made — don't reopen
+| Decision | Choice |
+|---|---|
+| DB access | Prisma only |
+| Queue | BullMQ on Redis |
+| Sessions | Opaque tokens in Redis (not JWTs) |
+| Primary keys | ULIDs |
+| Search | PostgreSQL FTS (Typesense at 100k+ users) |
+| API style | REST + JSON |
+| Passwords | Argon2id |
+| Deployment | Fly Machines → ECS → K8s (only with SRE) |
+| Tenancy | Shared DB, shared schema, tenantId column |

package/agent-config/windsurfrules-global.md

@@ -0,0 +1,128 @@
+# Universal coding rules — applies to all projects
+
+These rules are tool-agnostic, stack-agnostic hard constraints.
+Project-specific stack decisions live in .windsurfrules at the project root.
+
+---
+
+## SECURITY — never negotiate these
+
+- Validate every input at every system boundary — HTTP, queue, file upload, CLI args
+- All strings have a max length — no unbounded input
+- Passwords: Argon2id only — never bcrypt, MD5, SHA-1, or SHA-256 for passwords
+- Secrets in a secrets manager (Doppler, AWS Secrets Manager, Vault) — never in code, env files, or logs
+- One place reads environment variables — a config module with schema validation
+- Never reveal whether a user/email/resource exists to an unauthenticated caller
+- Unauthorised reads return 404, not 403 — prevents existence leak
+- Never log secrets, tokens, PII, or raw passwords — redact at the transport layer
+- Session tokens rotate on: login, logout, privilege change
+- File uploads: validate by magic number (not extension), scan for malware, strip metadata
+- SSRF: DNS-resolve before fetching, reject private/loopback IPs
+- Every outbound network call has a hard timeout
+- Retries only on 5xx and network errors — never on 4xx
+- Rate-limit authentication endpoints (login, password reset, MFA)
+- CORS: explicit allowlist — never wildcard `*` in production
+- Security headers on every response: HSTS, X-Frame-Options, CSP
+- TLS 1.2+ everywhere
+
+---
+
+## CODE QUALITY — language-agnostic rules
+
+- Use the strictest type-checking mode available for your language
+- Never use the "any" escape hatch (TypeScript `any`, Python `Any` without bounds, Go `interface{}` without assertion)
+- Functions ≤ 80 lines (aim ≤ 30); files ≤ 500 lines (aim ≤ 300)
+- No `console.log` / `print` in committed code — use a structured logger
+- No commented-out code — delete it; use git history
+- No TODO without author and date; CI should fail if TODOs accumulate
+- Boolean variables use `is/has/can/should` prefix
+- Error handling: throw/panic for programming errors (bugs); return typed errors/Result for expected failures (validation, not-found, rate-limit)
+- Async/await always — never raw promise chains or callbacks
+- Parallelise independent async work — don't await sequentially when parallel is safe
+- No N+1 queries — use eager loading, joins, or batching
+- No circular imports — signals wrong module boundaries
+- PR size ≤ 400 lines unless generated — split larger changes
+- Refactoring and feature work never in the same PR
+
+---
+
+## PERFORMANCE — hard budgets
+
+| Interaction | Budget |
+|---|---|
+| UI response (click, hover, keypress) | ≤ 100ms |
+| Page / view transition | ≤ 200ms |
+| API read (cached) p95 | < 200ms |
+| API read (list) p95 | < 300ms |
+| API write p95 | < 300ms |
+| Anything > 1s | Show progress indicator; consider async |
+| Anything > 10s | Must be async with completion notification |
+| LCP | ≤ 2.5s (p75) |
+| INP | ≤ 200ms (p75) |
+| CLS | ≤ 0.1 (p75) |
+| JS bundle gzipped | ≤ 170KB |
+| CSS bundle gzipped | ≤ 30KB |
+| DB indexed point lookup | ≤ 10ms |
+| DB list query | ≤ 200ms |
+
+- Profile before optimising — never optimise by intuition
+- Every query must hit an index — no sequential scans on large tables
+- Cache keys must include tenant/user scope — never serve one user's cached data to another
+- TTL on every cache entry — no infinite caches
+
+---
+
+## OBSERVABILITY — always
+
+- Structured JSON logs — required fields: `timestamp`, `level`, `service`, `correlationId`, `message`
+- Correlation ID on every log line, every async job, every cross-service call
+- Every HTTP route emits request count + duration metrics
+- Slow queries logged automatically — threshold: 50ms dev, 200ms staging, 500ms prod
+- Audit logs for any action that changes permissions, deletes data, or touches billing — append-only, never editable
+
+---
+
+## PRISM DESIGN SYSTEM — applies to all UI work
+
+- Never hardcode colours, radii, or font names — use CSS tokens (`var(--token-name)`)
+- Never use pure `#000` or `#fff` as text — use `var(--text-default)` (warm off-black)
+- Three colour layers: neutrals (90% of pixels) · product accent (`--accent`) · AI gradient (`--ai-grad`) — never mix
+- Sparkle star is the only AI glyph — no robots, brains, lightbulbs, wands
+- Never import Tailwind, Radix defaults, or shadcn themes — use `components.tsx` from the design system
+- Touch targets: 44×44px minimum on mobile
+- Mobile inputs: `font-size ≥ 16px` — iOS Safari zooms on focus otherwise
+- Dark mode: `[data-theme="dark"]` selector overrides — never `@media (prefers-color-scheme: dark)` in component CSS
+- Spacing: multiples of 4px only — allowed: 4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64
+
+---
+
+## DOCUMENTATION — always
+
+- ADR for every irreversible architectural decision — written before code merges
+- Every public API documented (OpenAPI 3.1 for HTTP, equivalent for others)
+- README passes the "5 minutes to running" test
+- Every migration is reversible or explicitly documented as one-way
+- Diagrams in code (Mermaid preferred) — never in external tools that drift
+
+---
+
+## ASYNC WORK — any language, any queue
+
+- Any work > 1 second belongs in a background job — never block an HTTP handler
+- Every job is idempotent — safe to retry without double side effects
+- Idempotency keys on mutations with external side effects (email, payment, webhook)
+- Jobs have a retry limit with exponential backoff
+- Job failure is observable — dead-letter queue or failure log
+
+---
+
+## WHEN TO CHECK FULL DOCS
+
+Full guidelines live in the Obsidian Skills vault:
+- Any UI work → load `prism-design` skill
+- Architecture, service boundaries, DB design → `guidelines/architecture-guidelines.md`
+- Auth, file upload, external APIs, AI features → `guidelines/security-guidelines.md`
+- Tests, refactoring, PR review → `guidelines/code-quality-guidelines.md`
+- Performance, caching, queries → `guidelines/performance-guidelines.md`
+- ADRs, READMEs, API docs → `guidelines/documentation-guidelines.md`
+- New component from scratch → `design/implementation-guide.md`

package/agent-config/windsurfrules.md

@@ -0,0 +1,155 @@
+# Codebase rules — read before every response
+
+## Stack
+TypeScript (strict) + Node.js + Express + Prisma + PostgreSQL + Redis + BullMQ.
+AI service: Python 3.12 + FastAPI (separate process).
+Frontend: Next.js + React.
+Design system: Prism (tokens.css + components.tsx — see design/ skill folder).
+
+---
+
+## HARD RULES — never violate these
+
+### Data & multi-tenancy (existential)
+- Every Prisma query that touches tenant data MUST filter by `tenantId` — enforced by middleware, but always verify
+- Never use `$queryRaw` or `$executeRaw` unless explicitly reviewed — use parameterised Prisma queries only
+- Shared database, shared schema, `tenantId` column — never schema-per-tenant
+- Soft deletes only — never hard-delete tenant data (`deletedAt` timestamp)
+- No `ON DELETE CASCADE` on tenant-scoped tables
+- Unauthorised reads return 404, not 403 — prevents existence leak
+- `tenantId` comes from the session, never from URL params or request body
+
+### IDs & pagination
+- ULIDs for all primary keys — not auto-increment integers, not UUIDs
+- Cursor-based pagination only — never offset/limit on large tables
+- Max page size: 100 items, default: 25
+
+### Async & queuing
+- Any operation > 1 second must be async via BullMQ — never block an HTTP handler
+- Only queue: BullMQ on Redis — not Kafka, SQS, RabbitMQ
+- Use outbox pattern for events (write to DB first, worker publishes) — never `queue.add()` directly from HTTP handlers
+- Idempotency keys on every mutation that has external side effects
+- Every async job: 5 retries max, exponential backoff (2s base), idempotent
+
+### Network & timeouts
+- Every network call has a timeout: 10s (internal HTTP), 5s (fast external APIs), 30s (slow), 60s (AI — async only)
+- Retries only on 5xx and network errors — NEVER retry 4xx
+- Circuit breaker: open after 5 failures in 10s, stay open 30s
+
+### Auth & security
+- Passwords: Argon2id only (`time=3, memory=64MB, parallelism=4`) — never bcrypt, never MD5, never SHA-1
+- API keys: Argon2id hashed before storage, displayed once only
+- Sessions: opaque 256-bit random tokens stored in Redis — NOT JWTs for user sessions
+- Session rotation on: login, logout, MFA completion, role change
+- Password reset does NOT log the user in — they re-authenticate after
+- Never reveal whether an email exists — always respond `200 RESET_EMAIL_SENT_IF_EXISTS`
+- Failed logins: lock account after 10 failures, rate-limit 5/hour per account
+- MFA required for `owner` and `admin` roles (TOTP, RFC 6238)
+- Role changes require dedicated endpoint — never via generic PATCH, user cannot change own role
+- Admin impersonation TTL: 1 hour max
+
+### Input & output
+- Validate every input at every boundary with Zod (TypeScript) or Pydantic `.strict()` (Python)
+- All strings must have max length — prevents DoS
+- File uploads: magic-number type validation, ClamAV virus scan, re-encode images (strips EXIF), store on object storage only (signed URLs)
+- Never use `dangerouslySetInnerHTML` without DOMPurify + explicit code-review tag
+- AI output: validate with Zod schema before use, never trust for authorisation decisions
+- SSRF: DNS-resolve before fetching, reject private IPs
+
+### Secrets & config
+- All secrets in Doppler or AWS Secrets Manager — never in code, never in `.env` files committed to git
+- One place reads `process.env`: `shared/config.ts` with Zod schema — nowhere else
+- No secrets in logs, errors, or API responses
+- Secrets rotated quarterly — dual-key rotation window
+
+### Logging & observability
+- Structured JSON logs only — required fields: `timestamp`, `level`, `service`, `correlationId`, `tenantId`, `userId`, `message`
+- Correlation ID propagates through all logs, queue jobs, cross-service calls, and audit entries
+- Audit log is append-only — 7-year retention, no UPDATE/DELETE at DB role level
+- Every route emits: `http_requests_total`, `http_request_duration_seconds`
+
+### API design
+- REST + JSON — no GraphQL unless multiple first-party clients with wildly different data needs
+- URL versioning: `/api/v1/`, `/api/v2/` — not header-based
+- Standard error envelope: `{ code, message, correlationId, details }`
+- Rate limits: 100 req/60s per user (default), 5/60s for login and password-reset
+
+---
+
+## CODE QUALITY RULES
+
+- TypeScript `strict: true` + `noUncheckedIndexedAccess` + `noImplicitOverride` — no exceptions
+- Never use `any` — use `unknown` with type narrowing
+- Never use TypeScript `enum` — use string literal unions or `as const` objects
+- Functions ≤ 80 lines (aim ≤ 30), files ≤ 500 lines (aim ≤ 300)
+- No `console.log` — use the structured logger
+- No commented-out code — delete it or put it in a ticket
+- Boolean variables: `is/has/can/should` prefix
+- No N+1 queries — always use Prisma `include/select` or a JOIN
+- Error handling: throw exceptions for programming errors, return Result types for expected failures (validation, not-found, rate-limit)
+- Async/await always — never raw `.then()` chains
+- PR size: ≤ 400 lines unless generated code — split larger changes
+
+---
+
+## PERFORMANCE BUDGETS (hard caps)
+
+| Interaction | Target |
+|---|---|
+| UI response (click, hover) | ≤ 100ms |
+| API read (cached, single) | p95 < 200ms |
+| API read (list, paginated) | p95 < 300ms |
+| API write | p95 < 300ms |
+| LCP | ≤ 2.5s (p75) |
+| INP | ≤ 200ms (p75) |
+| CLS | ≤ 0.1 (p75) |
+| JS bundle (gzipped) | ≤ 170KB |
+| CSS bundle (gzipped) | ≤ 30KB |
+| DB query (indexed lookup) | ≤ 10ms |
+| DB query (list with joins) | ≤ 200ms |
+
+---
+
+## PRISM DESIGN SYSTEM RULES
+
+- Never hardcode colours, radii, or font names — use CSS tokens (`var(--token-name)`)
+- Never use pure `#000` or `#fff` as text — use `rgb(55, 53, 47)` (off-black) via `var(--text-default)`
+- Three colour layers: neutrals (90% of pixels), product accent (`--accent`), AI gradient (`--ai-grad`) — never mix them
+- Sparkle star is the ONLY AI glyph — no robots, brains, lightbulbs, or wands
+- Never import Tailwind, Radix defaults, or shadcn themes — use components.tsx from the design system
+- Touch targets: 44×44px minimum on mobile
+- Never use `font-size` < 16px on mobile inputs — iOS Safari zooms on focus
+- Dark mode: use `[data-theme="dark"]` selector overrides — never `@media (prefers-color-scheme: dark)` in component CSS
+- Every component must work in light AND dark mode
+- Spacing: multiples of 4px only — allowed values: 4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 56, 64
+
+---
+
+## WHEN TO CHECK FULL DOCS
+
+Full guidelines live in the Skills folder. Load them when:
+
+| Situation | Read |
+|---|---|
+| Building any UI component or screen | `design/SKILL.md` → then the relevant `patterns-*.md` |
+| Adding auth, tenant logic, or a new service | `guidelines/architecture-guidelines.md` |
+| Adding file upload, external API, or AI feature | `guidelines/security-guidelines.md` |
+| Writing tests or refactoring | `guidelines/code-quality-guidelines.md` |
+| Slow queries, caching, bundle size | `guidelines/performance-guidelines.md` |
+| Writing an ADR or README | `guidelines/documentation-guidelines.md` |
+| Building a new component from scratch | `design/implementation-guide.md` |
+
+---
+
+## ARCHITECTURE DECISIONS ALREADY MADE (don't re-litigate)
+
+| Decision | Choice | Reason |
+|---|---|---|
+| DB access | Prisma only | Parameterised by default, tenant middleware |
+| Queue | BullMQ on Redis | Single system, battle-tested at this scale |
+| Sessions | Opaque tokens in Redis | Revocable, no JWT signature key management |
+| Search | PostgreSQL FTS | Sufficient to 100k users; extract to Typesense at scale |
+| DB topology | Shared Postgres, tenant_id column | Schema-per-tenant impossible at scale for migrations |
+| API style | REST + JSON | Debuggable, works across Node + Python |
+| Passwords | Argon2id | bcrypt is deprecated for this use case |
+| Deployment | Fly Machines (preferred) → ECS → K8s (only with SRE) | Operational complexity ladder |