contextos-agents 1.5.0

package/.agents/generated/claude/skills/react-best-practices/SKILL.md

@@ -0,0 +1,146 @@
+# Vercel React Best Practices
+
+## Overview
+
+Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring, code generation, and production review.
+
+## When to Use
+
+- When authoring new React functional components or Next.js App Router pages.
+- When implementing data fetching (client or server-side Server Actions, RSC).
+- When reviewing pull requests for rendering bottlenecks or memory leaks.
+- When optimizing bundle size, eliminating network waterfalls, or improving Core Web Vitals (LCP, INP, CLS).
+
+## Rules & Patterns
+
+### Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
+| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
+| 3 | Server-Side Performance | HIGH | `server-` |
+| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
+| 5 | Re-render Optimization | MEDIUM | `rerender-` |
+| 6 | Rendering Performance | MEDIUM | `rendering-` |
+| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+### 1. Eliminating Waterfalls (CRITICAL)
+
+- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values.
+- `async-defer-await` - Move await into branches where actually used.
+- `async-parallel` - Use `Promise.all()` for independent asynchronous operations.
+- `async-dependencies` - Use better-all for partial dependencies.
+- `async-api-routes` - Start promises early, await late in API routes.
+- `async-suspense-boundaries` - Use Suspense to stream content progressively.
+
+### 2. Bundle Size Optimization (CRITICAL)
+
+- `bundle-barrel-imports` - Import directly from specific modules, avoid broad barrel files (`index.ts`).
+- `bundle-analyzable-paths` - Prefer statically analyzable import paths to avoid bloated traces.
+- `bundle-dynamic-imports` - Use `next/dynamic` or `React.lazy()` for heavy interactive components.
+- `bundle-defer-third-party` - Load analytics and logging scripts after hydration.
+- `bundle-conditional` - Load modules only when feature flags or user actions require them.
+- `bundle-preload` - Preload assets on hover or focus for perceived instant navigation.
+
+### 3. Server-Side Performance (HIGH)
+
+- `server-auth-actions` - Always authenticate server actions like API routes.
+- `server-cache-react` - Use `React.cache()` for per-request deduplication.
+- `server-cache-lru` - Use LRU cache for cross-request caching.
+- `server-dedup-props` - Avoid duplicate serialization in RSC props.
+- `server-hoist-static-io` - Hoist static I/O to module level.
+- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR.
+- `server-serialization` - Minimize data passed across the server-client boundary.
+- `server-parallel-fetching` - Restructure components to parallelize fetches.
+- `server-after-nonblocking` - Use `after()` for non-blocking operations like analytics logging.
+
+### 4. Client-Side Data Fetching (MEDIUM-HIGH)
+
+- `client-swr-dedup` - Use SWR or TanStack Query for automatic request deduplication.
+- `client-event-listeners` - Deduplicate global event listeners.
+- `client-passive-event-listeners` - Use passive listeners for scroll and touch.
+- `client-localstorage-schema` - Version and minimize data stored in localStorage.
+
+### 5. Re-render Optimization (MEDIUM)
+
+- `rerender-defer-reads` - Don't subscribe to state only used in callbacks.
+- `rerender-memo` - Extract expensive work into memoized components.
+- `rerender-memo-with-default-value` - Hoist default non-primitive props.
+- `rerender-dependencies` - Use primitive dependencies in effects and callbacks.
+- `rerender-derived-state` - Subscribe to derived booleans, not raw high-frequency values.
+- `rerender-derived-state-no-effect` - Derive state during render, never in `useEffect`.
+- `rerender-functional-setstate` - Use functional `setState` for stable callback references.
+- `rerender-lazy-state-init` - Pass initializer functions to `useState` for expensive computations.
+- `rerender-transitions` - Use `startTransition` for non-urgent state updates.
+- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive.
+- `rerender-no-inline-components` - Never define subcomponents inside component render bodies.
+
+### 6. Rendering Performance (MEDIUM)
+
+- `rendering-content-visibility` - Use `content-visibility: auto` for long offscreen lists.
+- `rendering-hoist-jsx` - Extract static JSX elements outside components.
+- `rendering-conditional-render` - Use ternary (`condition ? <Comp /> : null`), not `&&` to avoid 0 rendering.
+- `rendering-usetransition-loading` - Prefer `useTransition` for loading state indicators.
+
+### 7. JavaScript Performance (LOW-MEDIUM)
+
+- `js-index-maps` - Build `Map` for repeated lookups instead of repeated array searches.
+- `js-cache-property-access` - Cache object properties in tight loops.
+- `js-early-exit` - Return early from functions to avoid nested complexity.
+- `js-hoist-regexp` - Hoist RegExp creation outside loops and functions.
+- `js-set-map-lookups` - Use `Set` / `Map` for O(1) lookups.
+
+### 8. Advanced Patterns (LOW)
+
+- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps.
+- `advanced-event-handler-refs` - Store event handlers in refs for stable listener attachments.
+- `advanced-init-once` - Initialize app singletons once per lifecycle.
+
+## Code Examples
+
+```tsx
+// [GOOD] Parallel server fetching without waterfall
+import { cache } from 'react';
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+
+export default async function UserPage({ params }: { params: { id: string } }) {
+  // Parallel dispatch
+  const userPromise = getUser(params.id);
+  const postsPromise = getPosts(params.id);
+
+  const [user, posts] = await Promise.all([userPromise, postsPromise]);
+
+  return (
+    <main>
+      <h1>{user.name}</h1>
+      <PostList posts={posts} />
+    </main>
+  );
+}
+```
+
+## Validation Checklist
+
+- [ ] All independent async fetches use `Promise.all()` instead of sequential `await`.
+- [ ] Direct imports used instead of barrel file imports for large libraries.
+- [ ] No `useEffect` used for deriving computed state from props or state.
+- [ ] Heavy interactive modals/drawers loaded dynamically via `next/dynamic`.
+- [ ] Server actions perform authentication checks before data mutations.
+- [ ] Zero subcomponents defined inside the body of parent components.
+
+## Common Mistakes
+
+- Writing sequential `await fetchA(); await fetchB();` creating avoidable network waterfalls.
+- Importing from package root barrel files triggering full bundle inclusion.
+- Setting state inside `useEffect` in response to prop changes.
+- Serializing full database models with sensitive or unused fields to Client Components.
+
+## Integration Notes
+
+- Pairs with `react` and `nextjs` skills for idiomatic App Router patterns.
+- Complements `performance` for Lighthouse and Core Web Vitals verification.

package/.agents/generated/claude/skills/redesign-audit/SKILL.md

@@ -0,0 +1,112 @@
+# Redesign Skill & UI Audit
+
+## Overview
+
+A systematic redesign and auditing protocol designed to elevate existing websites, dashboards, and web applications to world-class agency quality. It diagnoses and eradicates generic AI design fingerprints, sloppy typography, inconsistent palettes, and absent interaction states without breaking business logic or underlying component contracts.
+
+## When to Use
+
+- When auditing an existing UI codebase for design quality, responsiveness, or accessibility.
+- When modernizing a legacy application or uplifting generic templates.
+- When tasked to "redesign", "clean up the layout", "audit UI", or "make it look expensive and modern".
+
+## Rules & Patterns
+
+### 1. Workflow: Scan → Diagnose → Fix
+
+1. **Scan:** Read the codebase. Identify the framework, styling method (Tailwind v3/v4, vanilla CSS, CSS Modules), and established design tokens.
+2. **Diagnose:** Run through the design audit categories. Catalog generic patterns, missing states, and optical alignment flaws.
+3. **Fix:** Apply surgical, targeted upgrades working within the existing stack. Do not rewrite from scratch.
+
+### 2. Design Audit Categories
+
+#### Typography
+
+- **Replace Browser Defaults:** Swap generic `Inter`, `Roboto`, or system fonts with expressive typefaces (`Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`).
+- **Presence & Scale:** Increase display text size, tighten letter-spacing (`-0.02em` to `-0.04em`), reduce line-height on headlines.
+- **Reading Comfort:** Limit body text to 65 characters per line (`max-w-prose`), increase line-height to 1.6.
+- **Figures:** Enable tabular figures (`font-variant-numeric: tabular-nums`) for numbers in tables and data readouts.
+- **Orphan Prevention:** Apply `text-wrap: balance` on headlines and `text-wrap: pretty` on paragraphs.
+
+#### Color and Surfaces
+
+- **No Pure Black Backgrounds:** Replace `#000000` with tinted dark charcoal (`#0A0A0A`, `#121212`).
+- **Desaturate Accents:** Keep accent saturation below 80% so it blends harmoniously with neutrals.
+- **Single Accent Color:** Commit to one dominant accent hue; remove conflicting secondary tints.
+- **Tinted Shadows:** Tint shadows to match the background hue rather than harsh black opacity.
+- **Background Depth:** Prevent sterile flat sections by layering subtle noise overlays, ambient gradients, or masked imagery.
+
+#### Layout and Space
+
+- **Asymmetry & Bento Grids:** Break repetitive 3-column Bootstrap grids with asymmetrical spans or offset cards.
+- **Mobile Viewport Bug Fix:** Never use `height: 100vh`; always use `min-height: 100dvh`.
+- **Vertical Alignment:** Pin action buttons to the bottom of card groups (`mt-auto` or grid alignment) to maintain horizontal baseline harmony across differing text heights.
+- **Optical Centering:** Adjust icons, badges, and play buttons optically by 1-2px rather than relying solely on pure mathematical centering.
+
+#### Interactivity and States
+
+- **Interactive Feedback:** Add 200-300ms transitions, distinct hover shifts, and physical active presses (`scale(0.98)`).
+- **Visible Focus Rings:** Mandatory `:focus-visible` styling for keyboard navigation.
+- **States Completeness:** Always provide designed skeleton loaders, empty states, and inline error messages.
+
+#### Content & Code Quality
+
+- **Eradicate AI Clichés:** Remove buzzwords ("Elevate", "Seamless", "Unleash", "Next-Gen") and placeholder latin text.
+- **Semantic HTML:** Replace nested div containers with `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`.
+- **Relative Units:** Use `rem`, `%`, and CSS Grid rather than hardcoded pixel widths.
+
+### 3. Fix Priority
+
+1. **Font Swap:** Biggest instant aesthetic elevation with lowest regression risk.
+2. **Palette Cleanup:** Eliminate clashing or oversaturated colors.
+3. **States & Feedback:** Add hover, active, focus, loading, and empty states.
+4. **Layout & Alignment:** Fix container widths, baseline alignment, and mobile viewport heights.
+5. **Component Polish:** Replace generic cards and accordion boxes with modern minimal equivalents.
+
+## Code Examples
+
+```tsx
+// [BEFORE] Generic, misaligned card with generic shadow
+<div className="bg-white border rounded shadow p-4">
+  <h2>{title}</h2>
+  <p>{desc}</p>
+  <button className="bg-blue-500 text-white p-2">Click</button>
+</div>
+
+// [AFTER] Polished card with optical baseline alignment, tinted surface, and micro-interaction
+<div className="flex flex-col bg-[#FFFFFF] dark:bg-[#121212] border border-black/5 dark:border-white/10 rounded-2xl p-6 hover:shadow-[0_4px_20px_rgba(0,0,0,0.04)] transition-all duration-200">
+  <h3 className="font-semibold text-lg tracking-tight text-neutral-900 dark:text-neutral-100 text-balance mb-2">
+    {title}
+  </h3>
+  <p className="text-sm text-neutral-600 dark:text-neutral-400 leading-relaxed text-pretty mb-6">
+    {desc}
+  </p>
+  <button 
+    type="button" 
+    className="mt-auto inline-flex items-center justify-center font-medium text-sm px-4 py-2.5 rounded-xl bg-neutral-900 dark:bg-neutral-100 text-white dark:text-black hover:bg-neutral-800 active:scale-[0.98] transition-transform duration-150 focus-visible:ring-2 focus-visible:ring-neutral-400"
+  >
+    Continue
+  </button>
+</div>
+```
+
+## Validation Checklist
+
+- [ ] All headings have `text-wrap: balance` and appropriate negative letter tracking.
+- [ ] No pure black `#000000` backgrounds or oversaturated accent colors (>80% saturation).
+- [ ] All interactive elements include `:hover`, `:active`, and `:focus-visible` styles.
+- [ ] Cards in side-by-side grids align primary CTA buttons along the same bottom baseline.
+- [ ] Viewport containers use `100dvh` instead of `100vh`.
+- [ ] All lists, tables, and feeds have a designed empty state.
+
+## Common Mistakes
+
+- Rewriting components from scratch and breaking existing prop contracts or unit tests.
+- Forcing full-width sections without `max-w` constraints on ultra-wide screens.
+- Leaving action buttons at random heights inside differing text content cards.
+- Introducing external UI libraries without checking existing `package.json` dependencies.
+
+## Integration Notes
+
+- Complements `impeccable-design` for hard 50-rule QA verification.
+- Works alongside `ui-ux-pro` for token generation and color theory.

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

@@ -0,0 +1,237 @@
+# security
+
+## Overview
+
+Enforces zero-trust defense-in-depth, OWASP API Top 10 mitigation, cryptographic hardening, sensitive data leakage protection, and AI/LLM safety across all services, endpoints, and agent integrations.
+
+## When to Use
+
+Activate whenever writing authentication, authorization, session management, database queries, cryptography, external API integrations, user input handling, or agent tool calling.
+
+## Rules & Patterns
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER use standard string comparison (`===`) for secrets/hashes**: Always use `crypto.timingSafeEqual` to prevent timing attacks.
+2. **NEVER store sensitive JWT access/refresh tokens in `localStorage`**: Store tokens in `httpOnly`, `Secure`, `SameSite=Strict` cookies.
+3. **NEVER return raw database/internal error messages or stack traces to the client**: Return standardized generic error codes (`INTERNAL_SERVER_ERROR`) and log details internally.
+4. **NEVER trust client-provided IDs for authorization without tenant/ownership checks**: Always verify `where: { id, userId: session.userId }` to prevent Broken Object Level Authorization (BOLA/IDOR).
+5. **NEVER disable CSRF protection, CORS allow-all (`*`), or TLS verification (`NODE_TLS_REJECT_UNAUTHORIZED=0`) in production**: Always enforce strict origin whitelists and HTTPS.
+6. **NEVER pass un-sanitized third-party content directly into system prompts or shell execution**: Treat all external data as potentially adversarial.
+
+---
+
+### OWASP Top 10 for Modern APIs & Full-Stack
+
+#### 1. Injection (SQL, NoSQL, Command)
+
+- Always use parameterized queries — never concatenate user input into SQL or shell commands.
+- Use ORMs (Prisma, Drizzle, SQLAlchemy) with strict schema validation.
+- Validate and sanitize all user input before processing.
+
+#### 2. Broken Object Level Authorization (BOLA / IDOR)
+
+- Validate user ownership on EVERY database read, update, or delete:
+
+  ```typescript
+  // [GOOD] Scoped to authenticated user
+  const doc = await db.document.findFirst({
+    where: { id: documentId, tenantId: session.tenantId }
+  });
+  ```
+
+#### 3. Broken Authentication & Session Management
+
+- Use Argon2id or bcrypt (cost factor ≥ 12) for password hashing.
+- Short-lived access tokens (15 min) + secure HTTP-only refresh tokens.
+- Enforce rate limiting and brute-force lockouts on auth endpoints.
+
+#### 4. SSRF (Server-Side Request Forgery)
+
+- Restrict server-side URL fetching: validate URL scheme (`https:` only), resolve IP, and block private CIDR blocks (`10.0.0.0/8`, `127.0.0.0/8`, `169.254.0.0/16`, `192.168.0.0/16`).
+
+#### 5. Security Misconfiguration & Headers
+
+Enforce modern production security headers:
+
+```http
+Content-Security-Policy: default-src 'self'
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+---
+
+### AI Agent & LLM Security Invariants
+
+When building AI workflows, tools, or MCP servers:
+
+1. **Prompt Injection Defense**:
+   - Clearly delineate untrusted user/web content using boundary markers (e.g. `<untrusted_content>` tags).
+   - Never allow untrusted content to override system instructions or tool execution permissions.
+2. **Tool Execution Boundaries**:
+   - Destructive operations (database drops, file deletions, payment triggers) MUST require explicit user confirmation.
+   - Restrict file system tools to the workspace root — block directory traversal (`../`).
+3. **Secret Masking & Output Sanitization**:
+   - Scrub API keys (`sk-...`, `Bearer ...`), tokens, and credentials before writing to agent logs or step summaries.
+
+---
+
+## Code Examples
+
+### Timing-Safe Secret Verification
+
+```javascript
+import crypto from 'node:crypto';
+
+export function verifyWebhookSignature(payload, signature, secret) {
+  const hmac = crypto.createHmac('sha256', secret);
+  const digest = Buffer.from(hmac.update(payload).digest('hex'), 'utf8');
+  const sigBuffer = Buffer.from(signature, 'utf8');
+
+  if (digest.length !== sigBuffer.length) return false;
+  return crypto.timingSafeEqual(digest, sigBuffer);
+}
+```
+
+### Safe SSRF Prevention Wrapper
+
+```typescript
+import dns from 'node:dns/promises';
+
+export async function validateSafeUrl(urlString: string): Promise<URL> {
+  const parsed = new URL(urlString);
+  if (parsed.protocol !== 'https:') {
+    throw new Error('Only HTTPS protocol is permitted');
+  }
+
+  const { address } = await dns.lookup(parsed.hostname);
+  if (
+    address.startsWith('127.') ||
+    address.startsWith('10.') ||
+    address.startsWith('192.168.') ||
+    address === '169.254.169.254'
+  ) {
+    throw new Error('Access to private/metadata IP addresses is blocked');
+  }
+
+  return parsed;
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] All database queries parameterized or managed by type-safe ORM.
+- [ ] BOLA/IDOR prevented: all entity queries scoped by tenant/user id.
+- [ ] Cookies set with `HttpOnly`, `Secure`, and `SameSite=Strict` or `Lax`.
+- [ ] Passwords hashed with Argon2id / bcrypt.
+- [ ] Security headers active in middleware/reverse proxy.
+- [ ] No secrets or tokens checked into source control or exposed in logs.
+
+---
+
+## Common Mistakes
+
+- **Trusting client-side claims**: Checking role or permissions only on the frontend without server-side validation.
+- **Timing attacks on tokens**: Comparing tokens with `token === expectedToken` instead of `timingSafeEqual`.
+- **Exposing internal stack traces**: Returning full error objects to client in production.
+- **Unvalidated redirects / URLs**: Allowing arbitrary URLs in redirect or fetch parameters.
+
+---
+
+## Integration Notes
+
+- 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.
+
+
+# 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();
+});
+```
+
+# 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/claude/skills/soft-design/SKILL.md

@@ -0,0 +1,103 @@
+# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
+
+## Overview
+
+Engineers high-end, agency-level digital experiences characterized by tactile haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and fluid spring physics. Rejects generic commodity SaaS templates in favor of bespoke layout archetypes, nested double-bezel enclosures, and purposeful motion dynamics.
+
+## When to Use
+
+- When tasked with creating luxury, premium, Awwwards-tier landing pages, portfolio showpieces, or editorial SaaS interfaces.
+- When explicitly prompted for "soft UI", "expensive design", "Apple-level polish", or "calm aesthetics".
+- When standard component libraries feel too clinical or generic.
+
+## Rules & Patterns
+
+### 1. Absolute Zero Directive (Strict Anti-Patterns)
+
+- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Use `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans`).
+- **Banned Icons:** Thick-stroked Lucide, FontAwesome, or Material Icons. Use ultra-light, precise line icons (Phosphor Light, Remix Line).
+- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh dark drop shadows (`rgba(0,0,0,0.3)`).
+- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical 3-column Bootstrap-style grids without massive whitespace.
+- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
+
+### 2. The Creative Variance Engine
+
+Before writing code, consciously pick ONE combination:
+
+#### Vibe & Texture Archetypes
+
+1. **Ethereal Glass (SaaS / AI / Tech):** Deep OLED black (`#050505`), subtle radial mesh gradients, vantablack cards with `backdrop-blur-2xl` and white/10 hairlines.
+2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. Variable serif headings with subtle CSS noise overlay (`opacity-[0.03]`).
+3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or pure white backgrounds, bold grotesk typography, airy floating components with ultra-diffuse ambient shadows.
+
+#### Layout Archetypes
+
+1. **The Asymmetrical Bento:** Masonry CSS Grid of varying card spans. (Collapses to single-column `grid-cols-1 gap-6` on mobile).
+2. **The Z-Axis Cascade:** Stacked cards with varying depth of field and subtle `-2deg` or `3deg` rotations. (Rotations removed on mobile).
+3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with horizontal interactive card ribbons on the right.
+
+### 3. Haptic Micro-Aesthetics
+
+- **The Double-Bezel (Doppelrand):**
+  - **Outer Shell:** Wrapper `div` with subtle background (`bg-black/5` or `bg-white/5`), hairline border (`border border-white/10`), padding (`p-2`), and large outer radius (`rounded-[2rem]`).
+  - **Inner Core:** Nested card inside shell with distinct background, inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and mathematically concentric smaller radius (`rounded-[calc(2rem-0.5rem)]`).
+- **Button-in-Button Trailing Icon:** Pill-shaped primary buttons (`rounded-full px-6 py-3`) with trailing arrows nested inside their own dedicated circular badge (`w-8 h-8 rounded-full bg-black/5 flex items-center justify-center`).
+- **Macro-Whitespace:** Minimum `py-24` to `py-40` for section padding.
+
+### 4. Motion Choreography & Performance Guardrails
+
+- **Custom Physics:** All transitions use custom cubic-beziers: `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`.
+- **GPU-Safe Animation:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, or `height`.
+- **Blur Discipline:** Restrict `backdrop-blur` to fixed or sticky elements (navbars, modals). Never apply to scrolling containers.
+
+## Code Examples
+
+```tsx
+export function DoubleBezelCard({ title, subtitle, tag }: { title: string; subtitle: string; tag: string }) {
+  return (
+    // Outer Shell
+    <div className="p-2 rounded-[2rem] bg-black/5 dark:bg-white/5 border border-black/10 dark:border-white/10 transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)] hover:shadow-2xl">
+      // Inner Core
+      <div className="p-8 rounded-[calc(2rem-0.5rem)] bg-[#FFFFFF] dark:bg-[#0E0E0E] shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)] flex flex-col justify-between min-h-[320px]">
+        <div>
+          <span className="inline-block px-3 py-1 rounded-full text-[10px] uppercase tracking-[0.2em] font-medium bg-black/5 dark:bg-white/10 text-neutral-600 dark:text-neutral-400 mb-4">
+            {tag}
+          </span>
+          <h3 className="text-2xl font-bold tracking-tight text-neutral-900 dark:text-white mb-2">{title}</h3>
+          <p className="text-sm text-neutral-500 dark:text-neutral-400 leading-relaxed">{subtitle}</p>
+        </div>
+        <button 
+          type="button" 
+          className="group mt-6 inline-flex items-center justify-between pl-6 pr-2 py-2 rounded-full bg-neutral-900 dark:bg-white text-white dark:text-neutral-950 font-medium text-sm active:scale-[0.98] transition-all duration-300"
+        >
+          <span>Explore Experience</span>
+          <span className="w-8 h-8 rounded-full bg-white/10 dark:bg-black/10 flex items-center justify-center transition-transform duration-300 group-hover:translate-x-0.5 group-hover:-translate-y-0.5">
+            ↗
+          </span>
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Validation Checklist
+
+- [ ] All major cards and interactive modules use the Double-Bezel concentric architecture.
+- [ ] Primary buttons feature the nested button-in-button trailing icon pattern.
+- [ ] Section vertical padding is at minimum `py-24`.
+- [ ] Transitions use spring or custom cubic-bezier curves (no default linear transitions).
+- [ ] Layout collapses gracefully to single-column on mobile viewports (<768px).
+- [ ] Animations use only `transform` and `opacity`.
+
+## Common Mistakes
+
+- Using standard `shadow-md` or harsh dark drop shadows instead of soft ambient shadows.
+- Failing to recalculate concentric inner border-radii (`calc(outer - padding)`).
+- Applying `backdrop-blur` on large scrolling sections, triggering GPU repaints.
+- Sticking to generic 3-column Bootstrap grids.
+
+## Integration Notes
+
+- Complements `impeccable-design` for QA and anti-pattern enforcement.
+- Pairs with `ui-ux-pro` for color palette harmony and accessibility compliance.