contextos-agents 2.2.0 → 2.3.0

package/.agents/generated/gemini/skills/ponytail-mindset/SKILL.md

@@ -1,261 +1,41 @@
 ---
 name: ponytail-mindset
 description: >
-  Minimalist coding mindset based on DietrichGebert/ponytail. Teaches the AI to write only what is strictly necessary. Uses a 7-rung ladder: YAGNI → reuse → stdlib → platform → deps → one-liner → minimum. Minimizes unnecessary boilerplate and over-engineering while keeping all safety, validation and security guards.
+  Choose a minimal maintainable implementation for substantive Build tasks while preserving safety and verification.
 ---
 # ponytail-mindset
 
 ## Overview
 
-Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
+Reduce unnecessary code and dependencies without weakening correctness or security.
 
 ## When to Use
 
-Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
+Substantive implementation and refactoring during Build.
 
 ## Rules & Patterns
 
-Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
+Before adding code, check whether the feature is needed and whether existing code, the standard library, the platform, or an installed dependency handles it. Then implement the smallest readable solution. Avoid premature abstractions. Preserve validation, authorization, parameterized queries, meaningful error handling, and required tests.
 
-> _He says nothing. He writes one line. It works._
+The 7-rung ladder: YAGNI; reuse project code; standard library; native platform;
+installed dependencies; a readable one-liner; the minimum maintainable code.
 
-**Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
-
----
-
-### Core Principle
-
-> **The best code is code you don't write.**  
-> Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
-
----
-
-### The 7-Rung Decision Ladder
-
-**Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
-
-```text
-1. Does this need to exist?
-   → No: YAGNI — skip it entirely. Don't build for "future use."
-
-2. Already in this codebase or component library?
-   → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
-   → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
-
-3. Standard library does it?
-   → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
-
-4. Native platform feature?
-   → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
-   → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
-
-5. Already-installed dependency?
-   → Yes: Use it. Don't install a new library to do what an existing one can.
-
-6. Can it be done in one line?
-   → Yes: One line. No abstraction layer needed.
-
-7. Only then: write the MINIMUM that works.
-   → No classes when a function works. No module when an inline does.
-```
-
----
-
-### The Rule of Three (Do Not Abstract Early)
-
-- **First occurrence**: Write it inline directly where it is needed.
-- **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
-- **Third occurrence**: Only now extract a shared helper or utility.
-
----
-
-### 10 Concrete Over-Engineering Red Flags
-
-1. Creating a `GenericRepository<T>` when you only have 2 database tables.
-2. Creating a custom state machine or complex reducer for 2 boolean flags.
-3. Adding a configuration file or environment variables for values that never change.
-4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
-5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
-6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
-7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
-8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
-9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
-10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
-
----
-
-### The Sacred Exceptions (NEVER Cut These)
-
-The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
-
-#### 1. Input Validation
-
-```javascript
-// [GOOD] Always validate — even if "internal" API
-function createUser(data) {
-  if (!data.email || !isValidEmail(data.email)) {
-    throw new ValidationError('Invalid email');
-  }
-  return db.insert('users', data);
-}
-
-// [BAD] Never skip validation for "speed"
-function createUser(data) {
-  return db.insert('users', data); // NEVER
-}
-```
-
-#### 2. Error Handling
-
-```javascript
-// [GOOD] Always handle errors explicitly
-async function fetchUser(id) {
-  try {
-    const user = await db.findById(id);
-    if (!user) throw new NotFoundError(`User ${id} not found`);
-    return user;
-  } catch (err) {
-    logger.error('fetchUser failed', { id, err });
-    throw err;
-  }
-}
-```
-
-#### 3. Security Checks
-
-- Authorization check BEFORE every query or mutation.
-- Parameterized queries everywhere — zero string concatenation in SQL.
-- Strict sanitization of all rendered HTML and markdown.
-
-#### 4. Type Safety & Behavioral Tests
-
-- Strict TypeScript types — no `any` evasion.
-- Tests covering happy path, 4xx, and 5xx edge cases.
-
----
+Read [references/minimalism.md](references/minimalism.md) for detailed procedures and examples only when needed.
 
 ## Code Examples
 
-### Native Platform vs Over-Built Package
-
-**Over-build**:
-
-```bash
-npm install flatpickr
-# Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
-```
-
-**Ponytail approach (rung 4)**:
-
-```html
-<input type="date" name="date" aria-label="Appointment date" />
-```
-
-### Next.js App Router Server Action vs REST Endpoint
-
-```typescript
-// Instead of /api/users/[id]/route.ts + custom fetch wrapper:
-"use server";
-
-export async function updateUser(id: string, data: UpdateUserInput) {
-  const session = await getSession(); // auth check — never skip
-  if (session?.userId !== id) throw new Error("Forbidden");
-  return db.users.update(id, data);
-}
-```
-
----
+Reuse the existing date formatter. A shorter database query still needs authorization and validated input.
 
 ## Validation Checklist
 
-- [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
-- [ ] No single-use abstractions, wrappers, or interfaces created.
-- [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
-- [ ] All code written passes all existing unit and integration tests.
-
----
+- [ ] The requested outcome is handled.
+- [ ] Relevant verification and safety boundaries are preserved.
+- [ ] Limitations are stated.
 
 ## Common Mistakes
 
-- **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
-- **Creating utilities "for future use"**: Only write utilities when used 3+ times.
-- **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
-
----
+Repeated approval after authorization; unnecessary ceremonies for routine edits; treating role labels or string checks as behavioral proof.
 
 ## Integration Notes
 
-- Runs at the start of every `[PHASE: Build]` and `[PHASE: Review]`.
-- Enforces minimalism alongside `system-design` (think at scale, implement minimally).
-- Pairs with `impeccable-design` for UI tasks.
-
-
-<!-- Source: EXAMPLES.md -->
-
-# ponytail-mindset Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Data Formatting and Manipulation
-
-### Anti-pattern: Over-engineered Custom Utility Class
-
-```typescript
-// BAD: 40 lines of boilerplate for relative date formatting
-export class DateFormatterService {
-  private static instance: DateFormatterService;
-  public static getInstance() { /* singleton boilerplate */ }
-  public formatRelative(date: Date): string {
-    const diff = Date.now() - date.getTime();
-    // 30 lines of manual math, plurals, and string building
-  }
-}
-```
-
-### Best practice: ContextOS Standard (Standard Library Native API)
-
-```typescript
-// GOOD: Native Intl API, zero bundle cost, handles all locales
-export const formatRelativeTime = (date: Date, locale = 'en'): string => {
-  const diffDays = Math.round((date.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
-  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
-};
-```
-
----
-
-## Example 2: Component Library Reuse
-
-### Anti-pattern: Hand-rolled Modal from Scratch
-
-```text
-BAD: Writing custom overlay DOM, manual scroll locking, manual focus trapping,
-and custom keydown listeners. Burns 300+ lines of fragile code.
-```
-
-### Best practice: ContextOS Standard (Leverage Established Primitives)
-
-```bash
-# GOOD: Install battle-tested primitive that handles ARIA, portals, and keyboard navigation
-npx shadcn@latest add dialog
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# ponytail-mindset Troubleshooting & Common Mistakes
-
-## 1. Conflating Minimalism with Cutting Safety Guards
-
-- **Symptom**: Agent removes input validation, error handling, or security checks in the name of "less code".
-- **Root Cause**: Misunderstanding the Ponytail principle. Ponytail cuts unnecessary abstractions, never safety invariants.
-- **Fix**: Invariant: Always retain 100% of input sanitization, error boundaries, and type safety checks.
-
-## 2. "Just In Case" Speculative Coding (YAGNI Violation)
-
-- **Symptom**: Adding config options, generics, and plugin interfaces for features not requested.
-- **Root Cause**: Premature future-proofing.
-- **Fix**: Apply Rung 1 of the ladder: If it doesn't solve the immediate requirement, do not write it.
-
-## 3. Reinventing Installed Dependencies
-
-- **Symptom**: Writing a deep-clone helper when Lodash or native structuredClone is available.
-- **Root Cause**: Skipping inspection of package.json and runtime environment.
-- **Fix**: Inspect installed dependencies before writing utility functions.
+Load relevant domain skills and supporting resources on demand. Compatibility identifiers remain available.

package/.agents/generated/gemini/skills/ponytail-mindset/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# ponytail-mindset Troubleshooting & Common Mistakes
+
+## 1. Conflating Minimalism with Cutting Safety Guards
+
+- **Symptom**: Agent removes input validation, error handling, or security checks in the name of "less code".
+- **Root Cause**: Misunderstanding the Ponytail principle. Ponytail cuts unnecessary abstractions, never safety invariants.
+- **Fix**: Invariant: Always retain 100% of input sanitization, error boundaries, and type safety checks.
+
+## 2. "Just In Case" Speculative Coding (YAGNI Violation)
+
+- **Symptom**: Adding config options, generics, and plugin interfaces for features not requested.
+- **Root Cause**: Premature future-proofing.
+- **Fix**: Apply Rung 1 of the ladder: If it doesn't solve the immediate requirement, do not write it.
+
+## 3. Reinventing Installed Dependencies
+
+- **Symptom**: Writing a deep-clone helper when Lodash or native structuredClone is available.
+- **Root Cause**: Skipping inspection of package.json and runtime environment.
+- **Fix**: Inspect installed dependencies before writing utility functions.

package/.agents/generated/gemini/skills/ponytail-mindset/VALIDATION.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "rules_followed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "rules_followed"
+  ]
+}

package/.agents/generated/gemini/skills/ponytail-mindset/references/minimalism.md

@@ -0,0 +1,186 @@
+
+# ponytail-mindset
+
+## Overview
+
+Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
+
+## When to Use
+
+Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
+
+## Rules & Patterns
+
+Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
+
+> _He says nothing. He writes one line. It works._
+
+**Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
+
+---
+
+### Core Principle
+
+> **The best code is code you don't write.**\
+> Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
+
+---
+
+### The 7-Rung Decision Ladder
+
+**Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
+
+```text
+1. Does this need to exist?
+   → No: YAGNI — skip it entirely. Don't build for "future use."
+
+2. Already in this codebase or component library?
+   → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
+   → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
+
+3. Standard library does it?
+   → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
+
+4. Native platform feature?
+   → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
+   → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
+
+5. Already-installed dependency?
+   → Yes: Use it. Don't install a new library to do what an existing one can.
+
+6. Can it be done in one line?
+   → Yes: One line. No abstraction layer needed.
+
+7. Only then: write the MINIMUM that works.
+   → No classes when a function works. No module when an inline does.
+```
+
+---
+
+### The Rule of Three (Do Not Abstract Early)
+
+- **First occurrence**: Write it inline directly where it is needed.
+- **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
+- **Third occurrence**: Only now extract a shared helper or utility.
+
+---
+
+### 10 Concrete Over-Engineering Red Flags
+
+1. Creating a `GenericRepository<T>` when you only have 2 database tables.
+2. Creating a custom state machine or complex reducer for 2 boolean flags.
+3. Adding a configuration file or environment variables for values that never change.
+4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
+5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
+6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
+7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
+8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
+9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
+10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
+
+---
+
+### The Sacred Exceptions (NEVER Cut These)
+
+The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
+
+#### 1. Input Validation
+
+```javascript
+// [GOOD] Always validate — even if "internal" API
+function createUser(data) {
+  if (!data.email || !isValidEmail(data.email)) {
+    throw new ValidationError('Invalid email');
+  }
+  return db.insert('users', data);
+}
+
+// [BAD] Never skip validation for "speed"
+function createUser(data) {
+  return db.insert('users', data); // NEVER
+}
+```
+
+#### 2. Error Handling
+
+```javascript
+// [GOOD] Always handle errors explicitly
+async function fetchUser(id) {
+  try {
+    const user = await db.findById(id);
+    if (!user) throw new NotFoundError(`User ${id} not found`);
+    return user;
+  } catch (err) {
+    logger.error('fetchUser failed', { id, err });
+    throw err;
+  }
+}
+```
+
+#### 3. Security Checks
+
+- Authorization check BEFORE every query or mutation.
+- Parameterized queries everywhere — zero string concatenation in SQL.
+- Strict sanitization of all rendered HTML and markdown.
+
+#### 4. Type Safety & Behavioral Tests
+
+- Strict TypeScript types — no `any` evasion.
+- Tests covering happy path, 4xx, and 5xx edge cases.
+
+---
+
+## Code Examples
+
+### Native Platform vs Over-Built Package
+
+**Over-build**:
+
+```bash
+npm install flatpickr
+# Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
+```
+
+**Ponytail approach (rung 4)**:
+
+```html
+<input type="date" name="date" aria-label="Appointment date" />
+```
+
+### Next.js App Router Server Action vs REST Endpoint
+
+```typescript
+// Instead of /api/users/[id]/route.ts + custom fetch wrapper:
+"use server";
+
+export async function updateUser(id: string, data: UpdateUserInput) {
+  const session = await getSession(); // auth check — never skip
+  if (session?.userId !== id) throw new Error("Forbidden");
+  return db.users.update(id, data);
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
+- [ ] No single-use abstractions, wrappers, or interfaces created.
+- [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
+- [ ] All code written passes all existing unit and integration tests.
+
+---
+
+## Common Mistakes
+
+- **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
+- **Creating utilities "for future use"**: Only write utilities when used 3+ times.
+- **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
+
+---
+
+## Integration Notes
+
+- Applies during substantive Build work and reviews of implementation complexity.
+- Enforces minimalism alongside `system-design` (think at scale, implement minimally).
+- Pairs with `impeccable-design` for UI tasks.

package/.agents/generated/gemini/skills/security/EXAMPLES.md

@@ -0,0 +1,64 @@
+# Application Security Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Timing-Safe Secret Verification
+
+### Anti-pattern: Anti-pattern (Vulnerable to side-channel timing attack)
+
+```typescript
+// BAD: string comparison returns early on the first mismatched byte
+export function verifyApiKey(providedKey: string, storedKey: string): boolean {
+  return providedKey === storedKey; // Vulnerable to timing analysis!
+}
+```
+
+### Best practice: ContextOS Standard (Constant-time buffer comparison)
+
+```typescript
+// GOOD: crypto.timingSafeEqual executes in constant time
+import crypto from 'crypto';
+
+export function verifyApiKey(providedKey: string, storedKey: string): boolean {
+  const providedBuffer = Buffer.from(providedKey, 'utf8');
+  const storedBuffer = Buffer.from(storedKey, 'utf8');
+
+  if (providedBuffer.length !== storedBuffer.length) {
+    return false;
+  }
+
+  return crypto.timingSafeEqual(providedBuffer, storedBuffer);
+}
+```
+
+---
+
+## Example 2: Preventing IDOR (Insecure Direct Object Reference)
+
+### Anti-pattern: Anti-pattern (Trusting client ID without ownership check)
+
+```typescript
+// BAD: any authenticated user can delete any other user's document!
+app.delete('/api/documents/:id', requireAuth, async (req, res) => {
+  await prisma.document.delete({ where: { id: req.params.id } });
+  res.status(204).end();
+});
+```
+
+### Best practice: ContextOS Standard (Multi-tenant scoped authorization check)
+
+```typescript
+// GOOD: document deletion is strictly scoped to authenticated user or org
+app.delete('/api/documents/:id', requireAuth, async (req, res) => {
+  const deleted = await prisma.document.deleteMany({
+    where: {
+      id: req.params.id,
+      organizationId: req.user.organizationId, // Tenant isolation
+    },
+  });
+
+  if (deleted.count === 0) {
+    return res.status(404).json({ error: 'Document not found or access denied' });
+  }
+
+  return res.status(204).end();
+});
+```

package/.agents/generated/gemini/skills/security/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: Application Security
+name: security
 description: >
-  ContextOS skill for Application Security
+  Protect authentication, authorization, sensitive data, untrusted input, external integrations, and agent tool execution.
 ---
 # security
 
@@ -182,93 +182,3 @@ export async function fetchFromAllowlist(
 - Runs in the REVIEW phase for every backend route, auth flow, and database mutation.
 - Integrates with `engineering-workflow` during Phase 5 (5-axis quality gate).
 - Pairs with `system-design` to mandate secure network boundaries and authorization layers.
-
-
-<!-- Source: EXAMPLES.md -->
-
-# Application Security Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Timing-Safe Secret Verification
-
-### Anti-pattern: Anti-pattern (Vulnerable to side-channel timing attack)
-
-```typescript
-// BAD: string comparison returns early on the first mismatched byte
-export function verifyApiKey(providedKey: string, storedKey: string): boolean {
-  return providedKey === storedKey; // Vulnerable to timing analysis!
-}
-```
-
-### Best practice: ContextOS Standard (Constant-time buffer comparison)
-
-```typescript
-// GOOD: crypto.timingSafeEqual executes in constant time
-import crypto from 'crypto';
-
-export function verifyApiKey(providedKey: string, storedKey: string): boolean {
-  const providedBuffer = Buffer.from(providedKey, 'utf8');
-  const storedBuffer = Buffer.from(storedKey, 'utf8');
-
-  if (providedBuffer.length !== storedBuffer.length) {
-    return false;
-  }
-
-  return crypto.timingSafeEqual(providedBuffer, storedBuffer);
-}
-```
-
----
-
-## Example 2: Preventing IDOR (Insecure Direct Object Reference)
-
-### Anti-pattern: Anti-pattern (Trusting client ID without ownership check)
-
-```typescript
-// BAD: any authenticated user can delete any other user's document!
-app.delete('/api/documents/:id', requireAuth, async (req, res) => {
-  await prisma.document.delete({ where: { id: req.params.id } });
-  res.status(204).end();
-});
-```
-
-### Best practice: ContextOS Standard (Multi-tenant scoped authorization check)
-
-```typescript
-// GOOD: document deletion is strictly scoped to authenticated user or org
-app.delete('/api/documents/:id', requireAuth, async (req, res) => {
-  const deleted = await prisma.document.deleteMany({
-    where: {
-      id: req.params.id,
-      organizationId: req.user.organizationId, // Tenant isolation
-    },
-  });
-
-  if (deleted.count === 0) {
-    return res.status(404).json({ error: 'Document not found or access denied' });
-  }
-
-  return res.status(204).end();
-});
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# security Troubleshooting & Common Mistakes
-
-## 1. Insecure Direct Object References (IDOR)
-
-- **Symptom**: User A can access User B's invoices by simply modifying the ID in the URL.
-- **Root Cause**: Querying by record ID without scoping to the authenticated `user.id` or tenant ID.
-- **Fix**: Always query with ownership predicate: `db.invoice.findFirst({ where: { id, userId: auth.user.id } })`.
-
-## 2. SQL Injection via Raw String Concatenation
-
-- **Symptom**: Database compromised through input fields.
-- **Root Cause**: String templating in raw queries (`db.query("SELECT * FROM users WHERE id = " + id)`).
-- **Fix**: Always use parameterized queries (`$1, $2`) or ORM/query-builder methods.
-
-## 3. Storing Sensitive Secrets in Git or Client Bundles
-
-- **Symptom**: API keys or JWT signing secrets exposed publicly.
-- **Root Cause**: Hardcoding secrets in source files or prefixing server secrets with NEXT_PUBLIC_.
-- **Fix**: Store all secrets in server-only environment variables; add git-secrets to pre-commit hooks.

package/.agents/generated/gemini/skills/security/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# security Troubleshooting & Common Mistakes
+
+## 1. Insecure Direct Object References (IDOR)
+
+- **Symptom**: User A can access User B's invoices by simply modifying the ID in the URL.
+- **Root Cause**: Querying by record ID without scoping to the authenticated `user.id` or tenant ID.
+- **Fix**: Always query with ownership predicate: `db.invoice.findFirst({ where: { id, userId: auth.user.id } })`.
+
+## 2. SQL Injection via Raw String Concatenation
+
+- **Symptom**: Database compromised through input fields.
+- **Root Cause**: String templating in raw queries (`db.query("SELECT * FROM users WHERE id = " + id)`).
+- **Fix**: Always use parameterized queries (`$1, $2`) or ORM/query-builder methods.
+
+## 3. Storing Sensitive Secrets in Git or Client Bundles
+
+- **Symptom**: API keys or JWT signing secrets exposed publicly.
+- **Root Cause**: Hardcoding secrets in source files or prefixing server secrets with NEXT_PUBLIC_.
+- **Fix**: Store all secrets in server-only environment variables; add git-secrets to pre-commit hooks.