contextos-agents 1.6.1 → 2.0.0-beta.2

package/.agents/core/skills/web-accessibility/accessibility.md

@@ -1,63 +0,0 @@
-# Web Accessibility — WCAG 2.1 Compliance
-
-## Principles (POUR)
-
-1. **Perceivable** — content can be perceived by all users
-2. **Operable** — interface can be operated by all users
-3. **Understandable** — content and interface are understandable
-4. **Robust** — content works across assistive technologies
-
-## Keyboard Navigation
-
-- All interactive elements must be reachable with Tab
-- Focus order must be logical (DOM order)
-- Custom widgets need keyboard handlers (Enter, Space, Escape, Arrow keys)
-- Visible focus indicator on all interactive elements (never `outline: none` without replacement)
-- Skip navigation link for repeated content
-
-## Semantic HTML
-
-- Use `<button>` not `<div onClick>` for actions
-- Use `<a href>` for navigation
-- Use heading hierarchy (`<h1>` → `<h2>` → `<h3>`)
-- Use `<nav>`, `<main>`, `<article>`, `<aside>` landmarks
-- Use `<label>` with every form input
-
-## ARIA (when HTML alone isn't enough)
-
-- `aria-label` — label for screen readers when no visible text
-- `aria-labelledby` — reference to existing visible text
-- `aria-describedby` — additional description
-- `aria-live="polite"` — announce dynamic changes
-- `aria-expanded` — for collapsible sections
-- `aria-hidden="true"` — hide decorative elements
-
-**Rule: no ARIA is better than bad ARIA.** Use semantic HTML first.
-
-## Color and Contrast
-
-- Text contrast: 4.5:1 minimum (AA), 7:1 (AAA)
-- Large text (18px+ bold, 24px+ regular): 3:1 minimum
-- Never use color alone to convey information
-- Test with grayscale filter
-
-## Images
-
-- All images need `alt` text
-- Decorative images: `alt=""`
-- Complex images: `aria-describedby` with longer description
-- SVG icons: `role="img"` + `aria-label`
-
-## Forms
-
-- Every input needs a visible `<label>`
-- Error messages linked with `aria-describedby`
-- Required fields marked with `aria-required="true"`
-- Group related fields with `<fieldset>` + `<legend>`
-
-## Testing
-
-- Automated: axe-core, Lighthouse accessibility audit
-- Manual: keyboard-only navigation test
-- Screen reader: test with NVDA (Windows), VoiceOver (Mac)
-- Zoom: test at 200% and 400% zoom

package/.agents/core/skills/web-accessibility/skill.yaml

@@ -1,10 +0,0 @@
-id: web-accessibility
-name: Web Accessibility
-category: frontend
-tags: [frontend, a11y, wcag, aria, accessibility]
-requires: []
-optional: [react, nextjs]
-conflicts: []
-weight: 7
-documents:
-  - accessibility.md

package/.agents/generated/claude/skills/adapters/SKILL.md

@@ -1,126 +0,0 @@
-# agent-adapters
-
-## Overview
-
-Unified cross-agent configuration engine. Translates single ContextOS source rules into optimized native formats for Claude Code (CLAUDE.md), Gemini (.agents/skills), Cursor (.cursorrules, .cursor/rules/*.mdc), GitHub Copilot, Zed, Aider, and Continue.
-
-## When to Use
-
-Activate when configuring, synchronizing, or exporting agent rules and skills across multiple IDEs and AI programming assistants.
-
-## Rules & Patterns
-
-ContextOS is agent-agnostic. This skill generates the right config format for any AI agent.
-
-## Supported Agents
-
-| Agent | Config File | Format |
-| --- | --- | --- |
-| **Gemini** | `.agents/AGENTS.md` + `.agents/skills/` | Markdown + YAML skills |
-| **Claude Code** | `CLAUDE.md` | Single markdown file |
-| **GitHub Copilot / Codex** | `AGENTS.md` (root) | Markdown |
-| **Cursor** | `.cursorrules` | Plain text rules |
-| **Aider** | `.aider.conf.yml` | YAML config |
-| **Continue** | `.continuerules` | Markdown rules |
-| **OpenHands** | `openhands.json` | JSON config |
-| **Roo Code** | `.roo/` | Directory with rules |
-| **Windsurf** | `.windsurfrules` | Plain text rules |
-
-## Generation Command
-
-`ctx adapt [agent]` — Generate config for a specific agent.
-
-`ctx adapt all` — Generate configs for all supported agents.
-
-## Adapter Logic
-
-### For Claude Code (`CLAUDE.md`)
-
-Compile into a single markdown file:
-
-1. Project overview from `docs/PRD.md` (summary only)
-2. Architecture summary from `docs/ARCHITECTURE.md`
-3. Coding rules from loaded skills
-4. Active Decision Records
-5. Current tasks from `docs/TASKS.md`
-
-### For Gemini (`.agents/AGENTS.md`)
-
-Already native format. Just ensure:
-
-1. `AGENTS.md` references the skill directory
-2. Skills have proper SKILL.md with frontmatter
-3. Context Manager rules are in AGENTS.md
-
-### For Cursor (`.cursorrules`)
-
-Compile into a flat text file:
-
-1. Project context (condensed)
-2. Coding style rules
-3. Framework-specific instructions
-4. Anti-patterns to avoid
-
-### For Aider (`.aider.conf.yml`)
-
-```yaml
-read:
-  - docs/ARCHITECTURE.md
-  - docs/API.md
-  - docs/PROJECT_GRAPH.md
-conventions:
-  - {{coding rules from skills}}
-```
-
-## Sync Rules
-
-- Adapters read from the canonical ContextOS documents
-- Never edit adapter output files directly
-- Re-run `ctx adapt` after any document change
-- Each adapter file includes a header: `# Generated by ContextOS — do not edit directly`
-
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed code examples.
-
-## Validation Checklist
-
-What to verify during the review phase before completing the task.
-
-## Common Mistakes
-
-Anti-patterns and things to explicitly avoid. See `TROUBLESHOOTING.md`.
-
-## Integration Notes
-
-How this skill interacts with other skills.
-
-
-# adapters Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Multi-Agent Configuration
-
-### Anti-pattern: Manually Syncing 6 Different Rule Files
-
-```text
-Editing .cursorrules, then forgetting to update CLAUDE.md, then editing copilot-instructions.md.
-Rules diverge across teammates using different IDEs.
-```
-
-### Best practice: ContextOS Standard (Single Source of Truth)
-
-```bash
-# Edit skills once in .agents/core/skills/
-# Compile to all agents with one command:
-node .agents/ctx.js export all
-# Automatically updates .cursorrules, CLAUDE.md, copilot-instructions.md, .aider, .zed
-```
-
-# adapters Troubleshooting & Common Mistakes
-
-## 1. Overwriting Custom Configs
-
-- **Symptom**: Custom non-ContextOS rules wiped out during export.
-- **Root Cause**: Running export with force flags over unmanaged files.
-- **Fix**: Keep custom project overrides in dedicated config files or use plugin skills.

package/.agents/generated/claude/skills/architecture-diagrams/SKILL.md

@@ -1,101 +0,0 @@
-# architecture-diagrams
-
-## Overview
-
-Visual architecture engineering skill inspired by [tt-a1i/archify](https://github.com/tt-a1i/archify). Replaces static ASCII art and rigid default diagrams with crisp, self-contained SVG and responsive HTML diagrams featuring modern dark-mode palettes, pulse animations for event flows, and strict C4-model component boundaries.
-
-## When to Use
-
-Activate whenever:
-
-- Designing or explaining distributed systems, microservices, or full-stack architectures.
-- Visualizing complex auth flows (OAuth2, PKCE), multi-step payment sagas, or CDC outbox data pipelines.
-- User requests an architecture diagram, flow chart, sequence diagram, or visual system design.
-
-## Rules & Patterns
-
-### 1. Diagram Types Supported
-
-1. **System Landscape / C4 Container Diagram**:
-   - Clients (Web, Mobile, Third-party) → API Gateway / CDN → Microservices / Serverless → Storage / Event Brokers.
-2. **Sequence Flow Diagram**:
-   - Step-by-step lifecycles with synchronous requests, asynchronous pub/sub events, and compensating transactions.
-3. **Data Pipeline & Event-Driven Topology**:
-   - Primary DB → Transactional Outbox → CDC (Debezium) → Kafka Topic → Consumers → Materialized Views.
-
-### 2. Aesthetic & Visual Invariants
-
-- **Dark Theme by Default**: Surface `#0B0F19`, containers `#1E293B`, borders `#334155`, text `#F8FAFC`.
-- **Semantic Component Accents**:
-  - Client / Frontend: Sky Blue (`#38BDF8`)
-  - API Gateway / Router: Indigo (`#818CF8`)
-  - Business Services: Emerald Green (`#34D399`)
-  - Databases / Storage: Amber / Orange (`#F59E0B`)
-  - Message Brokers / Event Buses: Purple (`#A855F7`)
-- **Active Data-Flow Motion**: Use subtle CSS `@keyframes` on SVG stroke dashes (`stroke-dasharray`, `stroke-dashoffset`) to show active direction of messages and data streams.
-
----
-
-## Code Examples
-
-### Standalone Animated SVG Data-Flow Pattern
-
-```html
-<svg viewBox="0 0 800 200" xmlns="http://www.w3.org/2000/svg" class="bg-slate-950 rounded-xl p-4 w-full">
-  <defs>
-    <style>
-      .flow-line { stroke: #38BDF8; stroke-width: 2; stroke-dasharray: 6,6; animation: flow 1.5s linear infinite; }
-      @keyframes flow { to { stroke-dashoffset: -12; } }
-      .box { fill: #1E293B; stroke: #334155; stroke-width: 1.5; rx: 8; }
-      .text-title { fill: #F8FAFC; font-family: sans-serif; font-size: 14px; font-weight: 600; }
-      .text-sub { fill: #94A3B8; font-family: monospace; font-size: 11px; }
-    </style>
-  </defs>
-
-  <!-- Client Node -->
-  <rect x="30" y="70" width="160" height="60" class="box" />
-  <text x="110" y="96" text-anchor="middle" class="text-title">Next.js Client</text>
-  <text x="110" y="114" text-anchor="middle" class="text-sub">React 19 / RSC</text>
-
-  <!-- Data Flow -->
-  <line x1="190" y1="100" x2="330" y2="100" class="flow-line" />
-
-  <!-- API Gateway -->
-  <rect x="330" y="70" width="160" height="60" class="box" />
-  <text x="410" y="96" text-anchor="middle" class="text-title">API Gateway</text>
-  <text x="410" y="114" text-anchor="middle" class="text-sub">Auth & Rate Limiting</text>
-
-  <!-- Flow to Database -->
-  <line x1="490" y1="100" x2="630" y2="100" class="flow-line" />
-
-  <!-- Database -->
-  <rect x="630" y="70" width="140" height="60" class="box" />
-  <text x="700" y="96" text-anchor="middle" class="text-title">PostgreSQL</text>
-  <text x="700" y="114" text-anchor="middle" class="text-sub">Prisma / Outbox</text>
-</svg>
-```
-
----
-
-## Validation Checklist
-
-- [ ] Diagram clearly identifies all component boundaries, ports, and protocols.
-- [ ] Visual hierarchy is unambiguous (clients on left/top, storage on right/bottom).
-- [ ] Motion/animation is purposeful and lightweight (no heavy canvas frameworks).
-- [ ] Accessible: nodes include semantic labels and readable color contrast.
-
----
-
-## Common Mistakes
-
-- **Messy cross-overs**: Laying out 20 boxes with overlapping lines instead of grouping into clean C4 layers.
-- **Unlabeled connections**: Lines without protocol (HTTPS, gRPC, WSS) or event payload descriptions.
-- **Overwhelming detail**: Drawing internal class diagrams when the user asked for a system-level overview.
-
----
-
-## Integration Notes
-
-- Triggers during `system-design` and `microservices` planning phases.
-- Used to generate visual architecture artifacts in Markdown walkthroughs and specs.
-- Pairs with `ui-ux-pro` for consistent aesthetic styling.

package/.agents/generated/claude/skills/brutalist-design/SKILL.md

@@ -1,145 +0,0 @@
-# SKILL: Industrial Brutalism & Tactical Telemetry UI
-
-## Overview
-
-Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
-
-## When to Use
-
-- When building data-heavy telemetry dashboards, analytics monitors, trading systems, or developer command centers.
-- When creating editorial portfolios, archival indexes, or technical documentation sites requiring an industrial blueprint aesthetic.
-- When explicitly prompted for "brutalist", "tactical", "terminal", "Swiss print", or "mechanical" aesthetics.
-
-## Rules & Patterns
-
-### 1. Visual Archetypes
-
-Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.
-
-#### 1.1 Swiss Industrial Print
-
-Derived from 1960s corporate identity systems and heavy machinery blueprints.
-
-- **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
-
-#### 1.2 Tactical Telemetry & CRT Terminal
-
-Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
-
-- **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
-
-### 2. Typographic Architecture
-
-Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
-
-#### 2.1 Macro-Typography (Structural Headers)
-
-- **Classification:** Neo-Grotesque / Heavy Sans-Serif.
-- **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
-- **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
-- **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
-- **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
-- **Casing:** Exclusively uppercase for structural impact.
-
-#### 2.2 Micro-Typography (Data & Telemetry)
-
-- **Classification:** Monospace / Technical Sans.
-- **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
-- **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
-- **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
-- **Leading:** Standard to tight (`1.2` to `1.4`).
-- **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
-
-#### 2.3 Textural Contrast (Artistic Disruption)
-
-- **Classification:** High-Contrast Serif.
-- **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
-- **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
-
-### 3. Color System
-
-The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
-
-**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
-
-#### Swiss Industrial Print Light Substrate
-
-- **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
-- **Foreground:** `#050505` to `#111111` (Carbon Ink).
-- **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
-
-#### Tactical Telemetry Dark Substrate
-
-- **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
-- **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
-- **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
-- **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
-
-### 4. Layout and Spatial Engineering
-
-- **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
-- **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
-- **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
-- **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
-
-### 5. UI Components and Symbology
-
-- **Syntax Decoration:** Utilization of ASCII characters to frame data points (`[ DELIVERY SYSTEMS ]`, `< RE-IND >`, `>>>`, `///`).
-- **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
-- **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (`REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
-
-### 6. Textural and Post-Processing Effects
-
-- **Halftone and 1-Bit Dithering:** Dot-matrix effects via `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
-- **CRT Scanlines:** `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)` on terminal backgrounds.
-- **Mechanical Noise:** Low-opacity SVG static filter on the DOM root to introduce physical grain.
-
-### 7. Web Engineering Directives
-
-1. **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
-2. **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
-3. **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.
-
-## Code Examples
-
-```tsx
-export function TelemetryModule({ unitId, status, metrics }: { unitId: string; status: string; metrics: { label: string; val: string }[] }) {
-  return (
-    <div className="border-2 border-black dark:border-white bg-[#F4F4F0] dark:bg-[#0A0A0A] font-mono p-4 rounded-none">
-      <div className="flex justify-between border-b border-black/30 dark:border-white/30 pb-2 mb-4 text-xs tracking-widest uppercase">
-        <span>[ UNIT // {unitId} ]</span>
-        <span className="text-[#E61919] font-bold">&lt; STATUS: {status} &gt;</span>
-      </div>
-      <div className="grid grid-cols-2 gap-px bg-black/20 dark:bg-white/20">
-        {metrics.map(m => (
-          <div key={m.label} className="bg-[#F4F4F0] dark:bg-[#0A0A0A] p-2">
-            <div className="text-[10px] text-black/60 dark:text-white/60 tracking-wider">{m.label}</div>
-            <div className="text-sm font-bold tracking-tight">{m.val}</div>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-## Validation Checklist
-
-- [ ] Strict rejection of `border-radius` (all corners 0px / 90 degrees).
-- [ ] Substrate consistency: 100% committed to either Swiss Light or Tactical CRT Dark.
-- [ ] Pure black (`#000000`) avoided for backgrounds.
-- [ ] Monospace typography used for all telemetry, coordinates, and metadata labels.
-- [ ] Dividing lines engineered using solid borders or 1px grid track gaps.
-- [ ] No soft gradients, standard drop shadows, or floating cards.
-
-## Common Mistakes
-
-- Mixing Swiss Industrial Print and Tactical Telemetry substrates within the same view.
-- Introducing rounded corners (`rounded-md`, `rounded-full`) or pill buttons.
-- Using generic body typefaces without tracking adjustments.
-- Applying subtle pastel colors instead of raw carbon ink, off-white, and hazard red.
-
-## Integration Notes
-
-- Complements `impeccable-design` for QA checks on contrast and typography.
-- Pairs with `web-accessibility` to guarantee high-contrast readability (AAA ratio).

package/.agents/generated/claude/skills/database/SKILL.md

@@ -1,191 +0,0 @@
-# database
-
-## Overview
-
-Relational database design, query optimization, migration safety, connection pooling in serverless environments, and ORM usage across PostgreSQL, Prisma, and Drizzle.
-
-## When to Use
-
-Activate for tasks involving database schema design, migrations, indexing, relational models, ORM queries, transactions, or query performance tuning.
-
-## Rules & Patterns
-
-### Negative Constraints (What NOT to Do)
-
-1. **NEVER do `SELECT *` in production**: Always select explicit columns required by the caller to minimize memory bandwidth and lock footprint.
-2. **NEVER run destructive migrations without backward compatibility**: Always follow expand-and-contract (Phase 1: add new column as nullable; Phase 2: backfill; Phase 3: make non-nullable & remove old column).
-3. **NEVER execute queries in loops (The N+1 Anti-Pattern)**: Always use batch loading (`inArray`, `DataLoader`, or relational `include` / `JOIN`).
-4. **NEVER leave foreign keys without indexes**: In PostgreSQL/MySQL, child foreign key columns must always have an index to prevent table-level locking on cascade deletes.
-5. **NEVER perform multi-entity writes without a database transaction**: Any operation touching multiple records must use `prisma.$transaction` or `db.transaction`.
-6. **NEVER open unpooled database connections in Serverless / Edge functions**: Serverless scale-outs will instantly exhaust PostgreSQL's `max_connections`.
-
----
-
-### Zero-Downtime Migrations (Expand-and-Contract)
-
-When modifying schemas with zero downtime:
-
-1. **Phase 1 (Expand)**: Add the new column as `NULLABLE` (or with a default value). Deploy the application code that reads from old column and writes to both old and new.
-2. **Phase 2 (Backfill)**: Run an asynchronous batch migration job in chunks (e.g. 1000 rows at a time) to populate data from old column to new column.
-3. **Phase 3 (Contract)**: Update application code to read and write exclusively from the new column.
-4. **Phase 4 (Cleanup)**: Once traffic is fully shifted, remove the old column and mark the new column as `NOT NULL` in a separate migration.
-
----
-
-### Serverless & Edge Connection Pooling
-
-In serverless environments (AWS Lambda, Vercel Functions):
-
-- Always connect via a connection pooler:
-  - **Prisma**: Use Prisma Accelerate or configure transaction mode connection URLs.
-  - **Drizzle / Node-Postgres**: Use `@neondatabase/serverless` or connect to PgBouncer pooler port (`6543`) with `max: 1` per serverless container.
-- Set strict statement timeouts (e.g. `statement_timeout = '5000'`) to prevent hanging queries from exhausting pool capacity.
-
----
-
-### Indexing & Performance Rules
-
-- **B-Tree Indexes**: For high-cardinality filters (`status`, `user_id`, `created_at`).
-- **Composite Indexes**: When querying multiple columns together (`WHERE organization_id = ? AND status = ?`), order columns in index by equality first, range second.
-- **Partial Indexes**: For sparse boolean flags (`WHERE is_processed = false`).
-- **Covering Indexes**: Include frequently selected columns (`INCLUDE (title, created_at)`) to enable index-only scans without table heap access.
-
----
-
-## Code Examples
-
-### Zero-Downtime Column Rename (Drizzle ORM)
-
-```typescript
-// Step 1 (Expand): Keep old column, add new column
-export const users = pgTable('users', {
-  id: uuid('id').primaryKey().defaultRandom(),
-  fullName: varchar('full_name', { length: 255 }), // new column
-  name: varchar('name', { length: 255 }),           // old column kept during transition
-});
-
-// App write logic during transition:
-await db.insert(users).values({
-  name: input.name,
-  fullName: input.name
-});
-```
-
----
-
-## Validation Checklist
-
-- [ ] All database queries select explicit required columns (no `SELECT *`).
-- [ ] Foreign keys have matching indexes on child tables.
-- [ ] Multi-table writes wrapped in ACID transactions.
-- [ ] No N+1 queries in loops.
-- [ ] Schema migrations tested against expand-and-contract pattern.
-- [ ] Serverless database connection string uses pooling proxy.
-
----
-
-## Common Mistakes
-
-- **Missing pagination limits**: Unbounded `findMany()` calls leading to Out-Of-Memory crashes under production volume.
-- **Locking entire tables**: Adding `NOT NULL` columns with heavy compute defaults in PostgreSQL without concurrent index creation.
-
----
-
-## Integration Notes
-
-- Interacts with `system-design`, `ddd`, and `security` (multi-tenant tenantId scoping).
-
-
-# Database Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Solving the N+1 Query Problem
-
-### Anti-pattern: Anti-pattern (N+1 database queries in a loop)
-
-```typescript
-// BAD: 1 query for users + N queries for posts!
-const users = await prisma.user.findMany();
-const usersWithPosts = [];
-for (const user of users) {
-  const posts = await prisma.post.findMany({ where: { userId: user.id } }); // N queries!
-  usersWithPosts.push({ ...user, posts });
-}
-```
-
-### Best practice: ContextOS Standard (Batch query or relational include)
-
-```typescript
-// GOOD: 1 single optimized batch query
-const usersWithPosts = await prisma.user.findMany({
-  where: { isActive: true },
-  select: {
-    id: true,
-    name: true,
-    email: true,
-    posts: {
-      where: { published: true },
-      select: { id: true, title: true, createdAt: true },
-      take: 5
-    }
-  }
-});
-```
-
----
-
-## Example 2: Safe Atomic Transactions with Locking
-
-### Anti-pattern: Anti-pattern (Unprotected read-modify-write race condition)
-
-```typescript
-// BAD: race condition between reading balance and updating
-const account = await prisma.account.findUnique({ where: { id } });
-if (account.balance >= amount) {
-  await prisma.account.update({
-    where: { id },
-    data: { balance: account.balance - amount }
-  });
-}
-```
-
-### Best practice: ContextOS Standard (Atomic conditional update in transaction)
-
-```typescript
-// GOOD: atomic database transaction with invariant check
-export async function deductBalance(accountId: string, amount: number) {
-  return await prisma.$transaction(async (tx) => {
-    const updated = await tx.account.updateMany({
-      where: {
-        id: accountId,
-        balance: { gte: amount }
-      },
-      data: {
-        balance: { decrement: amount }
-      }
-    });
-
-    if (updated.count === 0) {
-      throw new InsufficientFundsError(accountId);
-    }
-  });
-}
-```
-
-# Database Troubleshooting Guide
-
-## Common Issues & Fixes
-
-### 1. Connection Pool Exhaustion in Serverless / Edge
-
-- **Cause**: Creating a new PrismaClient / DB connection instance on every serverless function invocation.
-- **Fix**: Declare PrismaClient as a global singleton across warm lambdas, and enable PgBouncer or Prisma Accelerate.
-
-### 2. Slow Queries on Large Tables
-
-- **Cause**: Missing composite index on filtered and ordered columns.
-- **Fix**: Run `EXPLAIN ANALYZE <query>` and add targeted indexes matching the WHERE and ORDER BY columns.
-
-### 3. Database Deadlocks during Concurrent Transactions
-
-- **Cause**: Different transactions updating resources in different orders.
-- **Fix**: Always acquire locks and update entities in a deterministic alphabetical or ID-ordered sequence.