@synapta/skills 0.1.1 → 0.2.0

package/dist/index.js

@@ -62,9 +62,16 @@ function parseSkillMd(source) {
 // src/load-bundled.ts
 import { readdir, readFile, stat } from "fs/promises";
 import { existsSync } from "fs";
-import { join, resolve } from "path";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+function resolveDefaultSkillsRoot() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const inPackage = resolve(here, "..", "skills");
+  if (existsSync(inPackage)) return inPackage;
+  return resolve(process.cwd(), "skills");
+}
 async function loadBundledSkills(opts = {}) {
-  const root = opts.skillsRoot ? resolve(opts.skillsRoot) : resolve(process.cwd(), "skills");
+  const root = opts.skillsRoot ? resolve(opts.skillsRoot) : resolveDefaultSkillsRoot();
   if (!existsSync(root)) return [];
   const entries = await readdir(root, { withFileTypes: true });
   const skills = [];
@@ -94,10 +101,10 @@ async function loadBundledSkills(opts = {}) {
 // src/scanner.ts
 import { readdir as readdir2, stat as stat2 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
-import { dirname, join as join2, extname } from "path";
+import { dirname as dirname2, join as join2, extname } from "path";
 var EXECUTABLE_EXTS = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".sh", ".bash", ".py", ".rb"]);
 async function scanSkill(loaded, _opts = {}) {
-  const dir = dirname(loaded.path);
+  const dir = dirname2(loaded.path);
   const execs = await findExecutables(dir);
   return {
     skill: loaded.manifest.name,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synapta/skills",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Agent Skills loader + bundled default skill pack",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,8 +12,7 @@
   },
   "files": [
     "dist",
-    "skills/**/SKILL.md",
-    "skills/**/assets/**",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -27,7 +26,7 @@
   "dependencies": {
     "yaml": "^2.5.0",
     "zod": "^3.23.0",
-    "@synapta/schemas": "0.1.1"
+    "@synapta/schemas": "0.2.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",

package/skills/ATTRIBUTION.md

@@ -0,0 +1,80 @@
+# Synapta Skill Pack — Attribution
+
+Synapta's default skill pack is composed of community-published Agent Skills, adapted "light-touch" (rename, retrigger, add Synapta source frontmatter; body kept verbatim) plus skills we authored from scratch where no upstream existed.
+
+All adopted skills retain their original license. License files and the source `commit:` SHA are recorded in each SKILL.md's `source:` frontmatter block. The clones used during adaptation live in `.research/` (gitignored).
+
+If you author a derivative work from Synapta's skill pack, include the upstream attribution chain.
+
+## Adopted skills (24)
+
+| Synapta skill | Upstream repo | Path | License | Commit |
+|---|---|---|---|---|
+| `mcp-builder` | [anthropics/skills](https://github.com/anthropics/skills) | `skills/mcp-builder` | see `LICENSE.txt` in source | `f458cee31a75` |
+| `apps-sdk-builder` | [openai/skills](https://github.com/openai/skills) | `skills/.curated/chatgpt-apps` | see `LICENSE.txt` in source | `c25113bf4c64` |
+| `playwright-qa` | [openai/skills](https://github.com/openai/skills) | `skills/.curated/playwright` | see `LICENSE.txt` + `NOTICE.txt` in source | `c25113bf4c64` |
+| `deploy-vercel` | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | `skills/deploy-to-vercel` | see source repo | `b9c8ee0643d8` |
+| `deploy-railway` | [railwayapp/railway-skills](https://github.com/railwayapp/railway-skills) | `plugins/railway/skills/use-railway` | MIT (Railway Corporation) | `380a2abbb0f9` |
+| `deploy-cloudflare` | [cloudflare/skills](https://github.com/cloudflare/skills) | `skills/wrangler` | Apache-2.0 | `60147cbb7736` |
+| `deploy-k8s` | [LukasNiessen/kubernetes-skill](https://github.com/LukasNiessen/kubernetes-skill) | `/` | see source repo `LICENSE` | `b7d32502e316` |
+| `deploy-docker` | [github/awesome-copilot](https://github.com/github/awesome-copilot) | `skills/multi-stage-dockerfile` | MIT (GitHub, Inc.) | `4e4b34c48d3f` |
+| `deploy-fly` | [yurikoval/dotfiles](https://github.com/yurikoval/dotfiles) | `claude/.claude/skills/flyctl` | see source repo | `933ff7260f40` |
+| `dep-sbom-scan` | [AgentSecOps/SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit) | `skills/devsecops/sca-trivy` | see source repo | `6e25a4bc5743` |
+| `iac-scan` | [AgentSecOps/SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit) | `skills/devsecops/iac-checkov` | see source repo | `6e25a4bc5743` |
+| `secret-hygiene` | [AgentSecOps/SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit) | `skills/devsecops/secrets-gitleaks` | see source repo | `6e25a4bc5743` |
+| `dast-zap` | [AgentSecOps/SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit) | `skills/appsec/dast-zap` | see source repo | `6e25a4bc5743` |
+| `threat-model` | [sethdford/claude-skills](https://github.com/sethdford/claude-skills) | `security/threat-modeling/skills/stride-analysis` | MIT (Seth Ford) | `00bd9265f5a3` |
+| `incident-triage` | [wshobson/agents](https://github.com/wshobson/agents) | `plugins/incident-response/skills/incident-runbook-templates` | MIT (Seth Hobson) | `112197c6bfd0` |
+| `docs-runbooks` | [wshobson/agents](https://github.com/wshobson/agents) | `plugins/incident-response/skills/postmortem-writing` | MIT (Seth Hobson) | `112197c6bfd0` |
+| `ops-sre` | [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | `categories/03-infrastructure/sre-engineer.md` | MIT (VoltAgent) | `6f804f0cfab2` |
+| `repo-bootstrap` | [netresearch/agent-rules-skill](https://github.com/netresearch/agent-rules-skill) | `skills/agent-rules` | MIT AND CC-BY-SA-4.0 (Netresearch DTT GmbH) | `9d1c57d1a131` |
+| `backlog-planner` | [github/awesome-copilot](https://github.com/github/awesome-copilot) | `plugins/project-planning/skills/breakdown-epic-pm` | MIT (GitHub, Inc.) | `4e4b34c48d3f` |
+| `ui-flow` | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | `.claude/skills/ui-ux-pro-max` | MIT (Next Level Builder) | `b7e3af80f6e3` |
+| `accessibility-audit` | [CrazyDubya/claude-skills](https://github.com/CrazyDubya/claude-skills) | `accessibility-auditor` | see source repo | `2798bb084fdf` |
+| `telegram-control` | [AlexSKuznetsov/claude-skill-telegram](https://github.com/AlexSKuznetsov/claude-skill-telegram) | `/` | see source repo | `06a7b02172c4` |
+| `concept-discovery` | [alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills) | `product-team/code-to-prd/skills/code-to-prd` | MIT (Alireza Rezvani) | `0796e1d70a9d` |
+| `test-strategy` | [nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent) | `skills/software-development/test-driven-development` | MIT | hermes-agent main |
+
+## Authored by Synapta (write-fresh)
+
+These skills had no quality community upstream at adoption time. Synapta authors them with citations to the underlying public docs / patterns rather than community SKILL.md files.
+
+| Synapta skill | Reason | Citation patterns |
+|---|---|---|
+| `architecture-selector` | No upstream selector found (existing skills were framework cheerleaders, not multi-axis selectors) | Twelve-Factor, AWS Well-Architected, Monolith First (Martin Fowler) |
+| `stack-selector` | Same — no multi-axis stack picker | — |
+| `schema-api-contracts` | Existing repos are codegen tools, not contract-first skills | Zod, Prisma, OpenAPI, tRPC docs |
+| `ts-lint` | No SKILL.md found | typescript-eslint, Prettier, tsc strict docs |
+| `release-publish` | skills.rest entry was 403; no good GH source | npm OIDC / Trusted Publishing docs, Changesets docs |
+| `deploy-ssh` | Surprising community gap | DeployHQ rsync patterns, Lambros Petrou zero-downtime patterns |
+| `drive-status-renderer` | Synapta-specific (iOS/CarPlay glanceable cards backed by gateway state) | WidgetKit, ActivityKit |
+| `voice-command-router` | Synapta-specific (Siri/App Intents → gateway approval) | App Intents framework |
+| `approval-policy-enforcer` | Synapta-specific (policies like "never deploy from car") | — |
+| `incident-briefing` | Synapta-specific (voice-only hands-free summary) | TTS providers, SSML |
+| `mobile-pairing` | Synapta-specific (QR/device-code pairing to local gateway) | openclaw pairing model (clean-room) |
+| `apns-notifier` | Synapta-specific (gateway APNs delivery) | Apple Push Notification service docs |
+| `widget-live-activity-sync` | Synapta-specific (Widget + Live Activity ↔ gateway) | ActivityKit, push tokens |
+| `carplay-entitlement-checker` | Synapta-specific (verify entitlement, Track A fallback) | Apple CarPlay programming guide |
+
+## Sister skills available for future expansion
+
+These upstream sources contain additional skills adjacent to what Synapta adopted. Consider pulling them into v0.1+ as sub-packs.
+
+- **threat-modeling pack** ([sethdford/claude-skills](https://github.com/sethdford/claude-skills)/security/threat-modeling/skills/): data-flow-diagram-security, risk-scoring, asset-inventory, attack-tree-modeling, threat-identification, abuse-case-design, threat-library, trust-boundary-analysis
+- **incident-response pack** ([wshobson/agents](https://github.com/wshobson/agents)/plugins/incident-response/skills/): on-call-handoff-patterns, plus all of `sethdford/claude-skills/security/incident-response/skills/`
+- **project-planning pack** ([github/awesome-copilot](https://github.com/github/awesome-copilot)/plugins/project-planning/skills/): breakdown-feature-prd, breakdown-feature-implementation, breakdown-epic-arch, create-implementation-plan, update-implementation-plan, create-technical-spike
+- **secops devsecops pack** ([AgentSecOps/SecOpsAgentKit](https://github.com/AgentSecOps/SecOpsAgentKit)): container-grype, container-hadolint, sast-bandit, sast-semgrep, api-mitmproxy, api-spectral, sca-blackduck, sast-horusec, sbom-syft, reviewdog, policy-opa, vuln-defectdojo
+- **cloudflare pack** ([cloudflare/skills](https://github.com/cloudflare/skills)): durable-objects, agents-sdk, cloudflare-email-service, workers-best-practices, sandbox-sdk, web-perf
+- **vercel pack** ([vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)): web-design-guidelines, vercel-cli-with-tokens, composition-patterns, react-best-practices, react-view-transitions, react-native-skills
+- **hermes software-development** ([nousresearch/hermes-agent](https://github.com/nousresearch/hermes-agent)/skills/software-development/): plan, writing-plans, requesting-code-review, subagent-driven-development, systematic-debugging, spike, hermes-agent-skill-authoring
+- **hermes mcp** (`skills/mcp/native-mcp/` + `optional-skills/mcp/fastmcp/`)
+- **levnikolaevich code auditors** ([levnikolaevich/claude-code-skills](https://github.com/levnikolaevich/claude-code-skills)/plugins/codebase-audit-suite/): 30+ auditor skills (pattern-fitness, layer-ownership, transaction-correctness, test-business-logic, runtime-performance, dependency-topology, etc.)
+
+## License compliance notes
+
+- All upstream licenses observed at adoption time are MIT, Apache-2.0, or repository-defined permissive licenses compatible with Synapta's Apache-2.0.
+- `repo-bootstrap` upstream is dual-licensed (MIT AND CC-BY-SA-4.0); the CC-BY-SA-4.0 portion applies to documentation/examples and requires share-alike attribution when redistributed.
+- `accessibility-audit` and `concept-discovery` sources lacked top-level LICENSE files at time of clone; treat as "all rights reserved" until upstream license is confirmed. Open an issue if you intend to redistribute these.
+- `deploy-fly` source repo (`yurikoval/dotfiles`) lacked a top-level LICENSE file; treat with caution.
+
+If you spot a license-compliance issue, please file an issue or email the contact in `SECURITY.md`.

package/skills/accessibility-audit/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: accessibility-audit
+synapta_original_name: accessibility-auditor
+triggers: [synapta a11y, WCAG, VoiceOver, ARIA, keyboard nav, accessibility]
+network: off
+source:
+  origin: https://github.com/CrazyDubya/claude-skills
+  path: accessibility-auditor
+  commit: 2798bb084fdf
+  license: see source repo
+  adapted: light-touch
+description: Reviews UI components for WCAG compliance, ARIA attributes, keyboard navigation, and screen reader support. Use when building frontend components or user requests accessibility improvements.
+allowed-tools: Read, Grep, Glob
+---
+
+# Accessibility Auditor
+
+Audits web applications for accessibility compliance (WCAG 2.1 Level AA) and suggests improvements.
+
+## When to Use
+- Building or reviewing UI components
+- User requests accessibility improvements
+- Preparing for accessibility audit
+- User mentions "accessibility", "a11y", "WCAG", "screen reader", or "keyboard navigation"
+
+## Instructions
+
+### 1. Semantic HTML Check
+
+**Use proper HTML elements:**
+```html
+<!-- Bad -->
+<div onclick="submit()">Submit</div>
+
+<!-- Good -->
+<button onclick="submit()">Submit</button>
+```
+
+**Semantic structure:**
+- `<header>`, `<nav>`, `<main>`, `<footer>`
+- `<article>`, `<section>`, `<aside>`
+- `<h1>` through `<h6>` in proper hierarchy
+- `<button>` for actions, `<a>` for navigation
+
+### 2. ARIA Attributes
+
+**When to use ARIA:**
+- Custom widgets (tabs, accordions, modals)
+- Dynamic content updates
+- Complex interactions
+- When semantic HTML isn't sufficient
+
+**Common ARIA attributes:**
+```html
+<!-- Landmark roles -->
+<nav role="navigation" aria-label="Main">
+
+<!-- Widget roles -->
+<div role="button" tabindex="0" aria-pressed="false">
+
+<!-- Live regions -->
+<div role="alert" aria-live="assertive">Error occurred</div>
+
+<!-- Labels and descriptions -->
+<button aria-label="Close dialog">×</button>
+<input aria-describedby="password-help" />
+```
+
+**First rule of ARIA:** Don't use ARIA if semantic HTML works
+
+### 3. Keyboard Navigation
+
+**All interactive elements must be keyboard accessible:**
+```javascript
+// Add keyboard support to custom elements
+<div
+  role="button"
+  tabindex="0"
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      handleClick();
+    }
+  }}
+>
+  Click me
+</div>
+```
+
+**Tab order:**
+- Use `tabindex="0"` for custom interactive elements
+- Avoid `tabindex > 0` (creates confusing tab order)
+- Use `tabindex="-1"` for programmatic focus only
+
+**Focus management:**
+- Visible focus indicators
+- Trap focus in modals
+- Return focus when closing dialogs
+- Skip links for main content
+
+### 4. Alt Text and Images
+
+**Informative images:**
+```html
+<img src="chart.png" alt="Sales increased 25% in Q3" />
+```
+
+**Decorative images:**
+```html
+<img src="decoration.png" alt="" />
+<!-- or -->
+<img src="decoration.png" role="presentation" />
+```
+
+**Complex images:**
+```html
+<figure>
+  <img src="complex-chart.png" alt="Quarterly sales chart" />
+  <figcaption>
+    Detailed description of the chart data...
+  </figcaption>
+</figure>
+```
+
+### 5. Color and Contrast
+
+**Contrast ratios (WCAG AA):**
+- Normal text: 4.5:1 minimum
+- Large text (18pt+): 3:1 minimum
+- UI components: 3:1 minimum
+
+**Don't rely on color alone:**
+```html
+<!-- Bad: Color only -->
+<span style="color: red;">Error</span>
+
+<!-- Good: Icon + color -->
+<span style="color: red;">
+  <svg aria-hidden="true"><!-- error icon --></svg>
+  <span class="sr-only">Error: </span>
+  Invalid input
+</span>
+```
+
+### 6. Forms and Labels
+
+**Every input needs a label:**
+```html
+<!-- Explicit label -->
+<label for="email">Email</label>
+<input id="email" type="email" />
+
+<!-- Implicit label -->
+<label>
+  Email
+  <input type="email" />
+</label>
+
+<!-- aria-label for icon buttons -->
+<button aria-label="Search">
+  <svg><!-- search icon --></svg>
+</button>
+```
+
+**Error messages:**
+```html
+<input
+  id="password"
+  aria-invalid="true"
+  aria-describedby="password-error"
+/>
+<div id="password-error" role="alert">
+  Password must be at least 8 characters
+</div>
+```
+
+### 7. Headings and Document Structure
+
+**Proper heading hierarchy:**
+```html
+<h1>Page Title</h1>
+  <h2>Section 1</h2>
+    <h3>Subsection 1.1</h3>
+    <h3>Subsection 1.2</h3>
+  <h2>Section 2</h2>
+```
+
+**Don't skip levels:** h1 → h2 → h3 (not h1 → h3)
+
+### 8. Dynamic Content
+
+**Announce updates to screen readers:**
+```html
+<!-- Polite: wait for user to pause -->
+<div role="status" aria-live="polite">
+  5 new messages
+</div>
+
+<!-- Assertive: interrupt immediately -->
+<div role="alert" aria-live="assertive">
+  Your session will expire in 1 minute
+</div>
+```
+
+**Loading states:**
+```html
+<button aria-busy="true" aria-label="Loading...">
+  <span aria-hidden="true">Loading</span>
+</button>
+```
+
+### 9. Screen Reader Testing
+
+**Screen reader only text:**
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+```
+
+**Hide decorative elements:**
+```html
+<svg aria-hidden="true"><!-- icon --></svg>
+```
+
+### 10. Common Issues to Check
+
+**Missing:**
+- [ ] Alt text on images
+- [ ] Labels on form inputs
+- [ ] Proper heading hierarchy
+- [ ] Keyboard focus indicators
+- [ ] ARIA labels on icon buttons
+
+**Improper:**
+- [ ] Low contrast text
+- [ ] Non-semantic markup (divs as buttons)
+- [ ] Missing focus management in modals
+- [ ] Keyboard traps
+- [ ] Auto-playing media
+
+**Testing:**
+- [ ] Keyboard only navigation
+- [ ] Screen reader (NVDA, JAWS, VoiceOver)
+- [ ] Color blindness simulation
+- [ ] Zoom to 200%
+- [ ] Automated tools (axe, Lighthouse)
+
+### 11. Automated Testing
+
+**Tools:**
+```bash
+# Lighthouse
+npx lighthouse https://example.com --only-categories=accessibility
+
+# axe-core
+npm install --save-dev @axe-core/cli
+npx axe https://example.com
+
+# pa11y
+npm install --save-dev pa11y
+npx pa11y https://example.com
+```
+
+**In tests:**
+```javascript
+import { axe } from 'jest-axe';
+
+test('should have no accessibility violations', async () => {
+  const { container } = render(<MyComponent />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### 12. WCAG 2.1 Level AA Checklist
+
+**Perceivable:**
+- [ ] Text alternatives for non-text content
+- [ ] Captions for audio/video
+- [ ] Content adaptable (semantic markup)
+- [ ] Sufficient color contrast
+
+**Operable:**
+- [ ] Keyboard accessible
+- [ ] No keyboard traps
+- [ ] Adequate time limits (adjustable)
+- [ ] No seizure-inducing flashing
+- [ ] Skip navigation links
+- [ ] Descriptive page titles
+- [ ] Focus order makes sense
+- [ ] Link purpose clear from context
+
+**Understandable:**
+- [ ] Language of page specified (`<html lang="en">`)
+- [ ] Predictable navigation
+- [ ] Input assistance (labels, instructions, error messages)
+
+**Robust:**
+- [ ] Valid HTML
+- [ ] Name, role, value for custom widgets
+- [ ] Compatible with assistive technologies
+
+## Best Practices
+
+- Build accessibility in from start
+- Test with real assistive technologies
+- Use semantic HTML first, ARIA second
+- Maintain logical document structure
+- Provide multiple ways to access content
+- Test keyboard navigation thoroughly
+- Don't disable zoom
+- Use landmarks and headings
+
+## Supporting Files
+- `reference/wcag-checklist.md`: Full WCAG 2.1 AA checklist
+- `reference/aria-patterns.md`: Common ARIA widget patterns

package/skills/accessibility-audit/reference/wcag-checklist.md

@@ -0,0 +1,103 @@
+# WCAG 2.1 Level AA Compliance Checklist
+
+## Principle 1: Perceivable
+
+### 1.1 Text Alternatives
+- [ ] 1.1.1 Non-text Content (A): All images have alt text
+
+### 1.2 Time-based Media
+- [ ] 1.2.1 Audio-only and Video-only (A): Alternatives provided
+- [ ] 1.2.2 Captions (A): Captions for videos
+- [ ] 1.2.3 Audio Description or Media Alternative (A)
+- [ ] 1.2.4 Captions (Live) (AA): Live captions
+- [ ] 1.2.5 Audio Description (AA): Pre-recorded video
+
+### 1.3 Adaptable
+- [ ] 1.3.1 Info and Relationships (A): Semantic markup
+- [ ] 1.3.2 Meaningful Sequence (A): Logical reading order
+- [ ] 1.3.3 Sensory Characteristics (A): Not color/shape only
+- [ ] 1.3.4 Orientation (AA): No orientation lock
+- [ ] 1.3.5 Identify Input Purpose (AA): Autocomplete attributes
+
+### 1.4 Distinguishable
+- [ ] 1.4.1 Use of Color (A): Not sole indicator
+- [ ] 1.4.2 Audio Control (A): Pause/stop audio
+- [ ] 1.4.3 Contrast (Minimum) (AA): 4.5:1 ratio
+- [ ] 1.4.4 Resize text (AA): 200% zoom without loss
+- [ ] 1.4.5 Images of Text (AA): Use real text
+- [ ] 1.4.10 Reflow (AA): No horizontal scrolling at 320px
+- [ ] 1.4.11 Non-text Contrast (AA): UI components 3:1
+- [ ] 1.4.12 Text Spacing (AA): Adjustable spacing
+- [ ] 1.4.13 Content on Hover or Focus (AA): Dismissible
+
+## Principle 2: Operable
+
+### 2.1 Keyboard Accessible
+- [ ] 2.1.1 Keyboard (A): All functionality keyboard accessible
+- [ ] 2.1.2 No Keyboard Trap (A): Can navigate away
+- [ ] 2.1.4 Character Key Shortcuts (A): Remappable
+
+### 2.2 Enough Time
+- [ ] 2.2.1 Timing Adjustable (A): Extend/turn off time limits
+- [ ] 2.2.2 Pause, Stop, Hide (A): Control moving content
+
+### 2.3 Seizures
+- [ ] 2.3.1 Three Flashes or Below Threshold (A)
+
+### 2.4 Navigable
+- [ ] 2.4.1 Bypass Blocks (A): Skip navigation
+- [ ] 2.4.2 Page Titled (A): Descriptive page titles
+- [ ] 2.4.3 Focus Order (A): Logical tab order
+- [ ] 2.4.4 Link Purpose (A): Link text is descriptive
+- [ ] 2.4.5 Multiple Ways (AA): Multiple nav methods
+- [ ] 2.4.6 Headings and Labels (AA): Descriptive
+- [ ] 2.4.7 Focus Visible (AA): Visible focus indicator
+
+### 2.5 Input Modalities
+- [ ] 2.5.1 Pointer Gestures (A): No complex gestures only
+- [ ] 2.5.2 Pointer Cancellation (A): Can abort/undo
+- [ ] 2.5.3 Label in Name (A): Accessible name includes visible text
+- [ ] 2.5.4 Motion Actuation (A): Disable motion triggers
+
+## Principle 3: Understandable
+
+### 3.1 Readable
+- [ ] 3.1.1 Language of Page (A): `<html lang="en">`
+- [ ] 3.1.2 Language of Parts (AA): lang attribute for changes
+
+### 3.2 Predictable
+- [ ] 3.2.1 On Focus (A): No context change on focus
+- [ ] 3.2.2 On Input (A): No unexpected changes
+- [ ] 3.2.3 Consistent Navigation (AA): Same order
+- [ ] 3.2.4 Consistent Identification (AA): Same function = same label
+
+### 3.3 Input Assistance
+- [ ] 3.3.1 Error Identification (A): Errors identified
+- [ ] 3.3.2 Labels or Instructions (A): Labels provided
+- [ ] 3.3.3 Error Suggestion (AA): Correction suggested
+- [ ] 3.3.4 Error Prevention (AA): Confirm/undo for legal/financial
+
+## Principle 4: Robust
+
+### 4.1 Compatible
+- [ ] 4.1.1 Parsing (A): Valid HTML
+- [ ] 4.1.2 Name, Role, Value (A): For custom widgets
+- [ ] 4.1.3 Status Messages (AA): Announced to screen readers
+
+## Testing Tools
+
+- **Automated**: Lighthouse, axe, WAVE
+- **Manual**: Keyboard navigation, screen reader
+- **Color**: Contrast checker
+- **Screen Readers**: NVDA (Windows), JAWS (Windows), VoiceOver (Mac/iOS)
+
+## Common Failures
+
+- Missing alt text
+- Insufficient contrast
+- No keyboard access
+- Empty links/buttons
+- Form inputs without labels
+- Heading hierarchy skipped
+- No focus indicators
+- Using color alone

package/skills/apns-notifier/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: apns-notifier
+description: Send APNs push to paired iOS devices for approval requests and Live Activity updates. Uses JWT-signed Apple connection from the gateway. Silent + alert pushes are separate flows.
+triggers: [synapta push, APNs, push notification, Live Activity update]
+network: allowlist
+tools: []
+source:
+  origin: authored-by-synapta
+  reason: "Synapta-specific APNs integration for gateway → paired devices."
+  citation_patterns:
+    - "APNs documentation (Apple Developer)"
+    - "JWT-based provider authentication (ES256 with Apple .p8 key)"
+    - "sideshow/apns2 (Go) as reference implementation pattern"
+---
+
+# APNs Notifier
+
+Deliver push notifications from the gateway to paired iOS devices. Two flows:
+
+1. **Alert push** — approval requests, incident summaries, deploy-ready prompts. Shows in Notification Center.
+2. **Silent push** — Live Activity content updates + widget timeline reload triggers. No user-visible UI.
+
+## Provider auth
+
+JWT-based, ES256, signed with the Apple Push Notification key (`.p8`). Configured once via `synapta gateway apns setup`:
+
+```yaml
+apns:
+  team_id: "<10-char team id>"
+  key_id: "<10-char key id>"
+  key_path: "/path/to/AuthKey_<key_id>.p8"  # OS-keychain-referenced, never in repo
+  environment: production  # or sandbox for TestFlight
+  bundle_id: "com.synapta.drive"
+```
+
+## Payload shapes
+
+### Alert (approval)
+
+```json
+{
+  "aps": {
+    "alert": { "title": "Approve deploy to Vercel?", "body": "preview → production, ref abc123" },
+    "sound": "default",
+    "interruption-level": "time-sensitive",
+    "category": "APPROVAL_REQUEST"
+  },
+  "synapta": {
+    "kind": "approval_request",
+    "request_id": "ar_...",
+    "expires_at": "2026-05-15T17:30:00Z"
+  }
+}
+```
+
+### Live Activity update
+
+```json
+{
+  "aps": {
+    "timestamp": 1234567890,
+    "event": "update",
+    "content-state": { "phase": "deploying", "pct": 60 },
+    "stale-date": 1234567920
+  }
+}
+```
+
+### Silent (widget reload)
+
+```json
+{ "aps": { "content-available": 1 }, "synapta": { "kind": "widget_reload", "surface": "session_status" } }
+```
+
+## Reliability
+
+- **Retry**: APNs may return `Unregistered` (device token rotated) or `BadDeviceToken`. On either, mark the device's APNs token stale; iOS will re-register on next launch.
+- **Rate**: respect Apple's per-device rate guidance; coalesce Live Activity updates to ≤ 1 / sec.
+- **TTL**: alert pushes carry `apns-expiration: <epoch + 5min>` for time-sensitive approvals so stale prompts don't show after the approval window closes.
+
+## Anti-patterns
+
+- Storing the `.p8` key in the repo
+- Sending alert pushes for non-time-sensitive events (battery drain + iOS deprioritizes the app)
+- Skipping `interruption-level: time-sensitive` for approvals (system may delay delivery)
+- Silent pushes used as a covert message channel (Apple rejects apps that do this)