contextos-agents 1.5.0

package/.agents/generated/gemini/skills/vercel-optimize/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: vercel-optimize
+description: >
+  Observability-first Vercel performance and cost reduction optimization skill.
+---
+# Vercel Optimize
+
+## Overview
+
+Observability-first Vercel performance and cost reduction optimization skill. Evaluates deployed Next.js, SvelteKit, Nuxt, and Astro projects using production telemetry signals (`signals.json`), deterministic candidate gating, and code scanning to deliver ranked, verified architectural recommendations.
+
+## When to Use
+
+- When tasked with reducing Vercel bills, Function Invocations, Fast Data Transfer, or Build Minutes.
+- When diagnosing slow serverless routes, cold starts, or Edge vs Node runtime mismatches.
+- When evaluating caching opportunities (`stale-while-revalidate`, ISR, CDN edge caching) or Core Web Vitals degradation.
+
+## Rules & Patterns
+
+### 1. Prerequisites & Framework Support
+
+- Vercel CLI v53+ with `vercel metrics`, `vercel usage`, `vercel contract`, and `vercel api`.
+- Authenticated CLI session (`vercel login`) and linked app directory (`vercel link`).
+- Framework support: Next.js App Router (Full), Pages Router (Supported), SvelteKit (Supported), Nuxt (Supported), Astro (Limited).
+- Security rule: Never put auth tokens in shell commands (`VERCEL_TOKEN=...` is banned in chat/logs).
+
+### 2. Core Doctrine & Gating Pipeline
+
+- **Metrics First:** Recommendations start from Vercel production signals (14-day window), not repo-wide grep.
+- **Deterministic Gates:** `scripts/gate-investigations.mjs` selects code-scope and platform-scope candidates.
+- **Candidate-Bound Scope:** Inspect only files named by a candidate or a route-local import chain.
+- **Version-Aware Citations:** Use only verified citations matching the target framework version.
+- **Specific Cache Policies:** When recommending caching, state the exact cache policy and headers; keep auth-sensitive and error responses dynamic.
+
+### 3. Recommendation Rules
+
+- Every recommendation must trace to a launched candidate and include observed metric evidence.
+- Cite verified files with line numbers when code changes are proposed.
+- Use precise observed performance numbers; avoid customer-facing speculative `$N` savings formulas.
+- Do not recommend duration reductions for Vercel Workflow runtime endpoints (`/.well-known/workflow/v1/*`).
+
+## Code Examples
+
+```typescript
+// [GOOD] Next.js Route Segment Config for Caching & Edge Runtime
+export const dynamic = 'force-static';
+export const revalidate = 3600; // Cache at Edge for 1 hour
+
+export default async function CachedCatalogPage() {
+  const products = await getCatalogData();
+  return <CatalogGrid items={products} />;
+}
+```
+
+```bash
+# Running the signals collection and gate
+node scripts/collect-signals.mjs [projectId] > "$RUN_DIR/vercel-signals.json"
+node scripts/scan-codebase.mjs <repo-root> > "$RUN_DIR/codebase.json"
+node scripts/merge-signals.mjs "$RUN_DIR/vercel-signals.json" "$RUN_DIR/codebase.json" --out "$RUN_DIR/signals.json"
+node scripts/gate-investigations.mjs "$RUN_DIR/signals.json" > "$RUN_DIR/gate.json"
+```
+
+## Validation Checklist
+
+- [ ] Project is properly linked with valid team/personal scope (`vercel link`).
+- [ ] Production metrics signals collected across 14-day window before inspecting code.
+- [ ] No secrets or tokens passed in command line arguments.
+- [ ] Recommendations grounded in specific verified file paths and line numbers.
+- [ ] Unsafe or auth-sensitive paths kept strictly dynamic.
+
+## Common Mistakes
+
+- Inspecting repository source code before metric signals exist.
+- Hardcoding `VERCEL_TOKEN` into terminal commands or prompt logs.
+- Recommending duration reductions on long-lived streaming routes or workflow runners.
+- Applying static caching to user-specific or authenticated routes.
+
+## Integration Notes
+
+- Complements `nextjs` and `react-best-practices` for server-side optimization.
+- Pairs with `performance` and `security` skills.
+

package/.agents/generated/gemini/skills/web-accessibility/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: Web Accessibility
+description: >
+  ContextOS skill for Web Accessibility
+---
+# Web Accessibility & Interface Guidelines
+
+## Overview
+
+Enforces universal accessibility compliance (WCAG 2.1 AA / AAA), rigorous semantic markup, keyboard navigability with focus traps, screen reader live regions, and Web Interface Guidelines standards.
+
+## When to Use
+
+Activate whenever building, styling, or reviewing user interfaces, forms, modals, menus, navigation drawers, custom interactive widgets, or media elements.
+
+## Negative Constraints (What NOT to Do)
+
+1. **NEVER use `outline: none` without a custom `:focus-visible` replacement**: Keyboard users must always have a distinct, high-contrast visual focus ring.
+2. **NEVER use non-semantic elements (`<div onClick>`) for interactive triggers**: Always use native `<button>` or `<a href>`.
+3. **NEVER create modals or dialogs without keyboard focus traps**: Focus must remain trapped inside open dialogs during Tab / Shift-Tab navigation and restore to trigger on close.
+4. **NEVER rely exclusively on color to indicate state or errors**: Always pair colors with text labels, icons, or ARIA attributes (`aria-invalid="true"`).
+5. **NEVER trap screen readers with missing form labels or error associations**: Every input must link to `<label htmlFor="id">` and errors via `aria-describedby`.
+6. **NEVER play animations without honoring `prefers-reduced-motion`**: Respect user OS motion reduction preferences.
+
+## Rules & Patterns
+
+### 1. Focus Visible & High-Contrast Focus Rings
+
+```css
+button:focus-visible,
+a:focus-visible,
+input:focus-visible {
+  outline: 2px solid #6366f1;
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+
+button:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+### 2. Accessible Modal & Focus Trap Contract
+
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { createPortal } from 'react-dom';
+
+interface ModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+  titleId: string;
+  children: React.ReactNode;
+}
+
+export function AccessibleModal({ isOpen, onClose, titleId, children }: ModalProps) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    triggerRef.current = document.activeElement as HTMLElement;
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      }
+
+      if (e.key === 'Tab') {
+        const focusables = dialogRef.current?.querySelectorAll<HTMLElement>(
+          'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+        ) || [];
+        if (!focusables.length) return;
+
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      }
+    };
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.removeEventListener('keydown', handleKeyDown);
+      triggerRef.current?.focus();
+    };
+  }, [isOpen, onClose]);
+
+  if (!isOpen) return null;
+
+  return createPortal(
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4">
+      <div 
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className="w-full max-w-lg rounded-xl bg-background p-6 shadow-2xl border"
+      >
+        {children}
+      </div>
+    </div>,
+    document.body
+  );
+}
+```
+
+### 3. Accessible Forms & Error Association
+
+```tsx
+export function EmailInput({ error, ...props }: { error?: string } & React.InputHTMLAttributes<HTMLInputElement>) {
+  const inputId = 'user-email';
+  const errorId = 'user-email-error';
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <label htmlFor={inputId} className="text-sm font-medium">
+        Email Address <span aria-hidden="true" className="text-destructive">*</span>
+      </label>
+      <input
+        id={inputId}
+        type="email"
+        autoComplete="email"
+        required
+        aria-invalid={Boolean(error)}
+        aria-describedby={error ? errorId : undefined}
+        className="rounded-md border p-2 text-sm focus-visible:ring-2"
+        {...props}
+      />
+      {error && (
+        <p id={errorId} role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed dialog, menu, and form examples.
+
+## Validation Checklist
+
+- [ ] All interactive elements are fully operable via Keyboard (`Tab`, `Enter`, `Space`, `Escape`).
+- [ ] Visual `:focus-visible` styling is distinct and high contrast (≥ 3:1).
+- [ ] Modals use `role="dialog"`, `aria-modal="true"`, focus trap, and restore focus on close.
+- [ ] Text contrast ratios satisfy WCAG AA (≥ 4.5:1 for normal text, ≥ 3:1 for large text).
+- [ ] Forms pair inputs with `<label htmlFor>`, valid `autocomplete` tokens, and `aria-invalid`.
+- [ ] Non-text media contains descriptive `alt` attributes or `aria-hidden="true"` for decorative icons.
+
+## Common Mistakes
+
+- Hiding outline focus indicators globally without `:focus-visible` fallback.
+- Forgetting to trap focus in modal dialogs or not returning focus to trigger when modal closes.
+- Missing `aria-expanded` attributes on disclosure buttons and dropdown toggles.
+
+## Integration Notes
+
+- Pairs with `ui-ux-pro` and `impeccable-design` for visual contrast and component standards.
+- Pairs with `react` and `nextjs` for accessible dialogs and focus restoration across route transitions.
+
+
+<!-- Source: accessibility.md -->
+
+# 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
+
+<!-- Source: EXAMPLES.md -->
+
+# web-accessibility Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Semantic Buttons vs Clickable Divs
+
+### Anti-pattern: Clickable Div
+
+```tsx
+// BAD: Cannot be focused with Tab, does not respond to Enter or Space, silent to screen readers
+<div className="button" onClick={handleSubmit}>Submit</div>
+```
+
+### Best practice: ContextOS Standard (Semantic Button Element)
+
+```tsx
+// GOOD: Keyboard focusable, native Enter/Space handling, properly announced by assistive tech
+<button type="button" onClick={handleSubmit} className="btn btn-primary">
+  Submit
+</button>
+```
+
+---
+
+## Example 2: Icon-only Buttons
+
+### Anti-pattern: Unlabelled Icon Button
+
+```tsx
+// BAD: Screen reader announces "button", user has zero idea what it does
+<button onClick={onClose}><XIcon /></button>
+```
+
+### Best practice: ContextOS Standard (Accessible Label)
+
+```tsx
+// GOOD: Explicit aria-label and hidden decorative icon
+<button type="button" onClick={onClose} aria-label="Close modal window">
+  <XIcon aria-hidden="true" />
+</button>
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# web-accessibility Troubleshooting & Common Mistakes
+
+## 1. Trapping Keyboard Users in Inactive Elements
+
+- **Symptom**: Tab key moves focus into invisible elements hidden offscreen.
+- **Root Cause**: Using display: none vs opacity: 0 or left: -9999px.
+- **Fix**: Always apply display: none / hidden or inert attribute to elements that are currently not visible.
+
+## 2. Color Contrast Violations
+
+- **Symptom**: Text is unreadable for users with low vision or in bright sunlight.
+- **Root Cause**: Contrast ratio between text and background color is below WCAG AA thresholds.
+- **Fix**: Ensure contrast ratio is at least 4.5:1 for body text and 3:1 for large text / graphical controls.
+
+## 3. Silent Dynamic Updates
+
+- **Symptom**: Asynchronous error messages or notifications appear on screen without screen reader announcement.
+- **Root Cause**: Missing ARIA live region.
+- **Fix**: Wrap notification banners in aria-live="polite" and role="status".