contextos-agents 1.5.0

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

@@ -0,0 +1,145 @@
+# 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/context-manager/SKILL.md

@@ -0,0 +1,147 @@
+# context-manager
+
+## Overview
+
+Deterministic context window optimizer. Analyzes user task intent and queries project dependency graphs to inject minimal relevant files and skills, preventing LLM attention loss and context pollution.
+
+## When to Use
+
+Activate during multi-file investigations, large refactorings, or complex tasks where dumping entire directory trees would blow past context budgets.
+
+## Rules & Patterns
+
+You are the **Context Manager**. Your job is to prevent context overload.
+
+## How It Works
+
+When given a task:
+
+### Step 1: Classify the task
+
+```yaml
+task:
+  type: [frontend | backend | fullstack | architecture | bugfix | refactor | deploy | review]
+  scope: [module | feature | file | project-wide]
+  module: {{module_name from Project Graph}}
+```
+
+### Step 2: Consult the Project Graph
+
+If `docs/PROJECT_GRAPH.md` or `.graphify/graph.json` exists (or activate `graphify` skill to extract AST dependencies):
+
+1. Find the module this task belongs to
+2. Get the module's dependencies
+3. Get the module's required skills
+4. Get the files this task will likely touch
+
+### Step 3: Apply Context Rules
+
+Load `references/context-rules.md` and apply the task type → document mapping.
+
+### Step 4: Return Context Package
+
+Output a context package:
+
+```yaml
+context:
+  documents:
+    required:
+      - docs/API.md          # sections: [appointments]
+      - docs/ARCHITECTURE.md # sections: [backend, api-layer]
+    optional:
+      - docs/decisions/0003-postgres.md
+    skipped:
+      - docs/UI.md           # reason: backend task
+      - docs/DATABASE.md     # reason: no schema change
+  
+  skills:
+    loaded: [typescript, node, postgres, testing]
+    skipped: [react, tailwind]  # reason: backend task
+  
+  project_graph:
+    module: appointments
+    dependencies: [auth, patients]
+    affected_files:
+      - src/modules/appointments/api/**
+      - src/modules/appointments/services/**
+```
+
+### Step 5: Validate Budget
+
+Check total token count. If over budget (see context-rules.md):
+
+1. Trim Level 1 docs to summaries
+2. Load only affected sections of Level 2 docs
+3. Keep Level 3 (skills) at full detail
+
+## Context Caching
+
+After first compilation for a module, cache the result:
+
+```
+.cache/
+  frontend.context.yaml
+  backend.context.yaml
+  appointments.context.yaml
+```
+
+Invalidate cache when:
+
+- A document is updated
+- A skill is added/removed
+- The Project Graph changes
+- A Decision Record is added
+
+## Questions the Context Manager Can Answer
+
+- "What documents do I need for this task?"
+- "Which skills should be loaded?"
+- "What modules are affected by this change?"
+- "Is this context package within budget?"
+- "Why was this document skipped?"
+
+
+## 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.
+
+
+# context-manager Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Context Selection
+
+### Anti-pattern: Context Window Dumping
+
+```text
+Agent reads all 180 files in src/ into context to debug a single button click handler.
+Result: Exhausts 150k tokens, reaches rate limits, and forgets user instructions.
+```
+
+### Best practice: ContextOS Standard (Targeted AST Traversal)
+
+```text
+1. Inspect package.json and AGENTS.md.
+2. Grep for target symbol: grep_search for 'SubmitButton'.
+3. Read ONLY components/SubmitButton.tsx and its direct import types/button.ts.
+Total tokens used: <1,500 tokens. Fast, accurate, zero hallucinations.
+```
+
+# context-manager Troubleshooting & Common Mistakes
+
+## 1. Token Budget Blowout
+
+- **Symptom**: Model performance drops significantly, losing earlier conversational context.
+- **Root Cause**: Loading large JSON mocks, lockfiles, or build directories into prompt.
+- **Fix**: Never read package-lock.json, dist/, or build artifacts unless explicitly debugging bundle outputs.

package/.agents/generated/claude/skills/context-os/SKILL.md

@@ -0,0 +1,191 @@
+# context-os
+
+## Overview
+
+Operating system and context orchestration layer for AI coding assistants. Standardizes software engineering workflows across requirements, architecture, atomic task planning, implementation, verification, and release.
+
+## When to Use
+
+Activate as the root meta-orchestrator across all development phases to ensure role consistency, quality gates, and structured execution.
+
+## Rules & Patterns
+
+You are the **Context Compiler**. Your job is NOT to know everything. Your job is to **assemble the minimum context** needed for the current task.
+
+## Pipeline
+
+When a user gives you a task, follow this pipeline:
+
+### Stage 1: Intent Analysis
+
+Analyze the user's prompt and determine:
+
+```yaml
+intent:
+  project_type: [webapp, api, mobile, cli, library, saas, crm, ecommerce]
+  industry: [healthcare, fintech, education, social, general]
+  layers:
+    frontend: true/false
+    backend: true/false
+    database: true/false
+    auth: true/false
+    ai: true/false
+    payments: true/false
+    realtime: true/false
+  scope: [new_project, feature, bugfix, refactor, architecture]
+```
+
+### Stage 2: Dependency Resolution
+
+For each required layer, load the skill graph:
+
+1. Read `skill.yaml` from each relevant skill directory
+2. Resolve `requires` — load mandatory dependencies
+3. Check `conflicts` — ensure no incompatible skills are loaded
+4. Apply `optional` — suggest but don't force
+5. Respect project profile (if set) — apply rules from `profiles/`
+
+**Dependency resolution example:**
+
+```
+Need: nextjs
+  → requires: react, typescript
+    → react requires: typescript (already loaded)
+  → optional: tailwind, prisma, next-auth
+  
+Loaded: [nextjs, react, typescript]
+Suggested: [tailwind, prisma, next-auth]
+```
+
+### Stage 3: Context Compilation
+
+Assemble context from three levels:
+
+**Level 1 — Vision (always available):**
+
+- `docs/PRD.md` — what are we building
+- `docs/ROADMAP.md` — where are we going
+- `docs/PROJECT_GRAPH.md` — project structure
+
+**Level 2 — Architecture (load when needed):**
+
+- `docs/ARCHITECTURE.md` — system design
+- `docs/DATABASE.md` — data model
+- `docs/API.md` — API contracts
+- `docs/decisions/` — prior decisions
+
+**Level 3 — Development (load per task):**
+
+- Relevant skill `.md` files
+- `docs/UI.md` — for frontend tasks
+- `docs/TASKS.md` — current sprint
+
+**Context Filtering Rules:**
+See `references/context-rules.md` for the full mapping of task types to required documents.
+
+### Stage 4: Prompt Optimization
+
+Before sending to the AI agent:
+
+1. Remove sections not relevant to the current task
+2. Prioritize: current task context > architecture > vision
+3. Include recent Decision Records that affect the current task
+4. Add coding rules from the loaded skills
+
+## Commands
+
+| Command | Action |
+| --- | --- |
+| `ctx init` | Analyze project idea, generate all docs |
+| `ctx plan` | Generate development plan from PRD |
+| `ctx compile` | Compile context for a specific task |
+| `ctx update` | Update changed documents |
+| `ctx graph` | Show/update Project Graph |
+| `ctx doctor` | Validate skill dependencies, check for conflicts |
+| `ctx explain` | Explain why specific context was loaded |
+
+## Project Initialization Flow
+
+When user says something like "Сделай CRM для стоматологии" or "Build a Trello clone":
+
+1. **Analyze intent** (Stage 1)
+2. **Ask clarifying questions:**
+   - Users and roles?
+   - Tech stack preference?
+   - Mobile app needed?
+   - AI features?
+   - Authentication type?
+   - Expected load?
+   - MVP or Production?
+3. **Select profile** (startup/enterprise/mvp/hackathon)
+4. **Resolve skills** (Stage 2)
+5. **Generate all documents** using `generators/` skill
+6. **Create Project Graph** — the master map of modules → features → tasks → files → skills
+7. **Output agent config** using `adapters/` skill
+
+## Skill Discovery
+
+Skills are discovered by scanning `.agents/skills/*/skill.yaml`. Each `skill.yaml` defines:
+
+```yaml
+id: react
+name: React
+category: frontend
+tags: [frontend, spa, jsx, components]
+requires: [typescript]
+optional: [tailwind, next-auth, react-query]
+conflicts: [vue, angular, svelte]
+weight: 8
+documents:
+  - react.md
+```
+
+The compiler builds a dependency graph from all discovered skills and resolves it for each task.
+
+
+## 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.
+
+
+# context-os Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Project Lifecycle Management
+
+### Anti-pattern: Ad-hoc Unstructured Development
+
+```text
+Coding -> Modifying DB -> Debugging -> Redesigning UI -> Changing Architecture
+All in one unstructured stream of consciousness.
+```
+
+### Best practice: ContextOS Standard (Phase-Gated Development)
+
+```text
+Phase 1: DEFINE (PRD & Requirements)
+Phase 2: PLAN (Atomic Tasks & ADRs)
+Phase 3: BUILD (TDD & Minimalist Implementation)
+Phase 4: VERIFY (Automated Test Proof)
+Phase 5: REVIEW (Design QA & Code Review)
+Phase 6: SHIP (Production Release)
+```
+
+# context-os Troubleshooting & Common Mistakes
+
+## 1. Stale Compiled Artifacts
+
+- **Symptom**: Editor rules don't reflect newly updated skills.
+- **Root Cause**: Modifying .agents/core/skills/ without recompiling exports.
+- **Fix**: Run node .agents/ctx.js export all whenever source skills are updated.

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

@@ -0,0 +1,191 @@
+# 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.