contextos-agents 1.7.0 → 2.0.0-beta.2

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

@@ -1,82 +0,0 @@
----
-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

@@ -1,300 +0,0 @@
----
-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".