---
name: snappy-gateway
role: Cloudflare Worker gateway that publishes, gates, and serves Claude Code skills at skills.snappy.ai
loaded-by: PreToolUse hook (auto-injected when "snappy-gateway" is mentioned)
---

# snappy-gateway -- Agent Loader

You manage the skills.snappy.ai Cloudflare Worker -- a KV-backed gateway that distributes Claude Code skills with tiered access control. This file is the operational contract. Everything load-bearing lives here.

## API module

```typescript
import { listSkills, getSkill, publishSkill } from "../snappy-gateway/api.ts";
```

Or CLI:
```bash
npx tsx ~/.claude/skills/snappy-gateway/api.ts list                  # the catalogue, with each card's check line
npx tsx ~/.claude/skills/snappy-gateway/api.ts get snappy-slack      # a published skill's SKILL.md
npx tsx ~/.claude/skills/snappy-gateway/api.ts card snappy-slack     # build the listing card, publish nothing
npx tsx ~/.claude/skills/snappy-gateway/api.ts publish snappy-slack  # one skill, with its card
npx tsx ~/.claude/skills/snappy-gateway/api.ts publish --base-set    # every base skill; the base-set gate runs first
npx tsx ~/.claude/skills/snappy-gateway/api.ts pull snappy-slack     # Add it, into the person's skills root
```

THE CARD IS THE LISTING. `card.ts` parses the skill rather than describing it:
purpose, verbs with their first call, faces, agents and cross-links from the one
AGENTS.md reader; pass/fail and the failing sentences from `snappy-tool-design
lint`; "covers 9 of 174 operations of Slack, checked <date>" from the committed
vendor corpus. Nothing on a card is a claim a person typed.

THE BASE SET IS THE GATE'S ANSWER. `--base-set` publishes every skill except the
ones `scripts/gates/base-set.mjs` keeps private, read through its own
`personal-tier.mjs`. That gate runs BEFORE any upload and a red gate publishes
nothing.

## API functions

| Function | Purpose |
|----------|---------|
| `listSkills()` | List all skills from the gateway catalog (uses master key if available) |
| `getSkill(name)` | Fetch a specific skill's SKILL.md content from the gateway |
| `publishSkill(skillName, tier?)` | Publish a local skill directory to gateway KV and rebuild the cross-skill graph |

## Operating principle

The gateway is a **distribution channel**, not an authoring tool. It serves skill files from KV, gates access by tier, and provides an operator console for AI provider credentials. All skill content is authored locally in `~/.claude/skills/` and pushed to KV via the publish script. Never edit skill content through the gateway.

---

## Architecture

```
Client Request → skills.snappy.ai (Cloudflare Worker)
  ↓
  index.ts (router) → dispatches by URL path to views or admin handlers
  ↓
  auth.ts → authenticate(request, env) → KeyRecord { tier, name, skills?, expires? }
  ↓
  KV Namespaces:
    SKILLS_STORE  -- skill files + index.json + _graph.json + _logo/*.svg
    API_KEYS      -- access tokens → KeyRecord JSON
    SETTINGS_STORE -- per-user AI provider credentials (keyed by auth token)
  ↓
  Env binding: MASTER_KEY (secret, never in source)
```

### Router pattern (index.ts)

`index.ts` is a single `fetch()` handler. It matches `url.pathname` top-down:

| Path pattern | Handler | Auth |
|---|---|---|
| `/login`, `/logout` | `handleLogin`, `handleLogout` | none |
| `/console` | `serveConsole` (views/console.ts) | session required |
| `/lint` | `serveLintDashboard` (views/lint.ts) | session required |
| `/settings`, `/settings/{provider}` | inline `handleSettings` | session required |
| `/ai/audit` | `handleAiAudit` (ai.ts) | session required |
| `/admin/api-liveness/*` | `handleApiLivenessAdmin` | master key (Bearer) |
| `/admin/lint/*` | `handleLintAdmin` | master key (Bearer or cookie) |
| `/admin/keys`, `/admin/keys/*`, `/admin/graph/rebuild`, `/admin/pid/status` | `handleAdmin` | master key (Bearer) |
| `/api-liveness.json`, `/api-refs.json` | inline read from KV | none (public read) |
| `/logo/{dark,light}.svg` | KV lookup `_logo/{theme}.svg` | none |
| `/install`, `/install.sh` | KV lookup `_install.sh` | none |
| `/download/{name}.zip` | `serveZip` | tier-gated |
| `/skills/{name}` | `serveSkillDetail` (views/skill-detail.ts) | tier-gated |
| `/.well-known/skills/index.json` | `serveIndex` (catalog.ts) | tier-filtered |
| `/.well-known/skills/_graph.json` | graph filtered by key | tier-filtered |
| `/.well-known/skills/{name}/*` | `serveFile` (catalog.ts) | tier-gated |
| `/` | `serveLanding` (views/landing.ts) | none (content filtered) |

Global `?key=xxx` on any GET auto-logs-in: validates key, sets `snappy_auth` cookie (30d, HttpOnly, Secure, SameSite=Lax), 303 redirects to same URL with key stripped.

### View structure

Each view is a TypeScript function returning an HTML string (SSR). No framework -- vanilla JS for interactivity. All views import from `topbar.ts` for shared header/theme.

| View file | URL | Purpose |
|---|---|---|
| `views/landing.ts` | `/` | Card grid of all visible skills, hierarchical tier ordering (hero > orchestrators > domain > standalone) based on graph in/out degree. Each card shows: health dot (API liveness), loader pill (green "loader" text if AGENTS.md in files[]), graph badges (in/out degree), cred dots, size, updated time. |
| `views/skill-detail.ts` | `/skills/{name}` | 3-column docs layout: sidebar (anatomy/config/graph), main (rendered markdown), AI audit panel |
| `views/console.ts` | `/console` | Operator page: AI provider credential management + config map + AI models map |
| `views/lint.ts` | `/lint` | Lint dashboard: static analysis violations across all skills |

### Auth model (auth.ts)

1. `getToken(request)` -- reads `Authorization: Bearer xxx` header OR `snappy_auth` cookie
2. `authenticate(request, env)` -- returns `KeyRecord` with tier + name + optional skills scope
3. `canViewSkill(key, skill)` -- tier-aware visibility (single source of truth for catalog + detail)
4. `canAccessFile(env, key, skillName)` -- per-file gate, reads catalog to prevent URL-guessing bypass

Token priority: Authorization header > cookie. Master key resolves to `{ tier: "personal", name: "robert" }`. No token = `{ tier: "public", name: "anonymous" }`.

### Access tiers

| Tier | Sees | Key Required |
|---|---|---|
| `public` | Only `public` skills | No |
| `client` | `public` + their scoped skills (via `skills[]` array) | Yes |
| `subscriber` | Everything except `personal` | Yes |
| `personal` | Everything | Master key |

---

## Key files and roles

| File | Path (relative to `~/projects/snappy-skills/src/`) | Role | Common edits |
|---|---|---|---|
| `index.ts` | `src/index.ts` | Router -- dispatches to views/admin | Add new route, add POST path to allowlist |
| `types.ts` | `src/types.ts` | `Env`, `KeyRecord`, `SkillEntry`, `SkillMeta` | Add KV binding, extend interfaces |
| `auth.ts` | `src/auth.ts` | Token extraction, key validation, tier gating | Adjust tier logic, cookie params |
| `catalog.ts` | `src/catalog.ts` | `serveIndex`, `serveFile` -- KV reads for catalog | Catalog filter changes |
| `topbar.ts` | `src/topbar.ts` | Shared sticky header: logo, nav, theme toggle, session badge | Add nav items, change theme vars |
| `config-map.ts` | `src/config-map.ts` | Static credential-to-skill and model-to-skill maps | Add new credential, map new skill |
| `settings.ts` | `src/settings.ts` | `SUPPORTED_CREDENTIALS`, per-user KV CRUD | Add new AI provider |
| `graph.ts` | `src/graph.ts` | Cross-skill link graph (parse SKILL.md → nodes/edges) | Adjust edge parsing |
| `lint.ts` | `src/lint.ts` | Static analysis rules engine | Add lint rules |
| `ai.ts` | `src/ai.ts` | AI audit proxy (streams OpenRouter response) | Change model, adjust prompt |
| `markdown.ts` | `src/markdown.ts` | Markdown-to-HTML renderer (links, tables, code blocks) | Fix rendering bugs |
| `anatomy.ts` | `src/anatomy.ts` | SKILL.md section parser (YAML frontmatter, headings) | Adjust section detection |
| `meta.ts` | `src/meta.ts` | Display metadata (icons, colors, descriptions) | Add skill display overrides |
| `views/landing.ts` | `src/views/landing.ts` | Landing page with hierarchical skill cards | Card layout, tier grouping |
| `views/skill-detail.ts` | `src/views/skill-detail.ts` | 3-column detail page | Sidebar panels, content rendering |
| `views/console.ts` | `src/views/console.ts` | AI Keys page + config map + models map + PID health | Add console section |
| `views/lint.ts` | `src/views/lint.ts` | Lint dashboard | Violation display |
| `admin/keys.ts` | `src/admin/keys.ts` | Key CRUD + graph rebuild | New admin endpoints |
| `admin/apiLiveness.ts` | `src/admin/apiLiveness.ts` | Extract/probe/recheck API refs | Probe logic |
| `admin/lint.ts` | `src/admin/lint.ts` | Run/status/rules lint endpoints | New lint routes |
| `wrangler.json` | `wrangler.json` | Worker config: KV bindings, account ID, compatibility date | Add KV namespace |
| `scripts/publish-skill.js` | `scripts/publish-skill.js` | Publish local skill dir to KV | Metadata fields |

---

## Admin endpoints (all require `Authorization: Bearer $MASTER_KEY`)

### Key management
```bash
# List all keys
curl -s -H "Authorization: Bearer $MASTER_KEY" https://skills.snappy.ai/admin/keys

# Create key (scoped to specific skills)
curl -s -H "Authorization: Bearer $MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Acme&tier=client&skills=skill1,skill2&expires=2027-01-01"

# Revoke key
curl -s -H "Authorization: Bearer $MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/revoke?key=snappy_xxx"
```

### Graph rebuild
```bash
# Rebuild cross-skill link graph (run after every publish)
curl -s -H "Authorization: Bearer $MASTER_KEY" https://skills.snappy.ai/admin/graph/rebuild
```

### API liveness (extract-then-probe pipeline)
```bash
# Step 1: Extract all API refs from every skill's SKILL.md
curl -s -X POST -H "Authorization: Bearer $MASTER_KEY" \
  https://skills.snappy.ai/admin/api-liveness/extract

# Step 2: Probe hosts in chunks (free tier = 50 subrequests max)
curl -s -X POST -H "Authorization: Bearer $MASTER_KEY" \
  "https://skills.snappy.ai/admin/api-liveness/probe?offset=0&limit=40"
# Repeat with next_offset until done=true

# Recheck a single skill's hosts (force, no cache)
curl -s -X POST -H "Authorization: Bearer $MASTER_KEY" \
  "https://skills.snappy.ai/admin/api-liveness/recheck?skill=snappy-ops"
```

### Lint
```bash
# Run full lint scan
curl -s -X POST -H "Authorization: Bearer $MASTER_KEY" \
  https://skills.snappy.ai/admin/lint/run

# Get cached results
curl -s -H "Authorization: Bearer $MASTER_KEY" \
  https://skills.snappy.ai/admin/lint/status

# List all rules
curl -s -H "Authorization: Bearer $MASTER_KEY" \
  https://skills.snappy.ai/admin/lint/rules
```

### PID feedback loop
```bash
# Read PID status (pushed to KV `_pid_status` by local collector script)
curl -s -H "Authorization: Bearer $MASTER_KEY" \
  https://skills.snappy.ai/admin/pid/status
```

The `/console` page also renders this data server-side (reads `_pid_status` from SKILLS_STORE KV). The Worker is read-only -- a local script collects feedback log entries, loader coverage, queue depth, and gap signals, then pushes the JSON blob to KV.

---

## Publishing workflow

```bash
# 1. Edit skill content locally
vim ~/.claude/skills/snappy-docs/SKILL.md

# 2. Publish to KV (reads all files, uploads each, updates index.json)
cd ~/projects/snappy-skills
node scripts/publish-skill.js snappy-docs ~/.claude/skills/snappy-docs public

# 3. Rebuild the cross-skill graph
curl -s -H "Authorization: Bearer $MASTER_KEY" https://skills.snappy.ai/admin/graph/rebuild

# 4. Verify
curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq '.skills[] | select(.name=="snappy-docs")'
```

**KV key convention:** `{skillName}/{filename}` (e.g. `snappy-docs/SKILL.md`). The catalog is at key `index.json`. The graph is at `_graph.json`. Logos at `_logo/dark.svg` and `_logo/light.svg`.

**Tiers on publish:** third arg to publish-skill.js: `public`, `client`, `subscriber`, or `personal`.

---

## Console page sections

The `/console` page (views/console.ts) has three sections:

1. **Session** -- signed-in identity, tier, masked token.

2. **Connections** -- all credentials from `config-map.ts` grouped by provider type (AI / Platform / Infra). Each row shows: label, env var, linked skills, usage count badge, and connection status. Browser-storable keys (from `SUPPORTED_CREDENTIALS` in settings.ts) get inline save/clear forms; the rest show "Resolved via .env.cache". Skills with 10+ credential dependencies highlighted.

3. **System Health** -- PID feedback loop status (loader coverage, corrections queue, gap signals).

To add a new console section: add HTML in `renderConsole()`, CSS in the `<style>` block, JS in the `<script>` block. All inline, no bundler.

---

## CSS conventions

All theme colors use oklch via CSS custom properties defined in `topbar.ts` `themeStyles()`:

| Variable | Dark value (oklch) | Purpose |
|---|---|---|
| `--bg` | `0.2679 0.0036 106` | Page background |
| `--fg` | `0.8574 0.0142 93` | Default text |
| `--card` | `0.3085 0.0035 106` | Card background |
| `--card-fg` | `0.9818 0.0054 95` | Card text |
| `--primary` | `0.6724 0.1308 38` | Accent (orange) |
| `--muted` | `0.3213 0.0038 106` | Muted background |
| `--muted-fg` | `0.7213 0.0169 99` | Muted text |
| `--border` | `0.4118 0.0101 106` | Borders |
| `--green` | `0.72 0.17 142` | Success/configured |
| `--red` | `0.65 0.2 25` | Error/danger |

Theme toggle: `html.dark` (default) / `html.light`. Pre-paint script in `<head>` reads `localStorage('snappy_theme')` to avoid flash. Toggle function: `toggleSnappyTheme()` in `topbarScript()`.

Layout patterns: card grid on landing, 3-column on detail (sidebar + main + audit), single-column on console. Max-width 880px. Fonts: Inter (body) + JetBrains Mono (code).

---

## Deploying Worker updates

```bash
cd ~/projects/snappy-skills
npx wrangler deploy
```

The `MASTER_KEY` is set as a Worker secret (not in wrangler.json). To update it:
```bash
cd ~/projects/snappy-skills
echo "the-key-value" | npx wrangler secret put MASTER_KEY
```

---

## Rules

- **KV rate limit (error 10048)** -- wait 60s and retry. Do NOT loop. Cloudflare throttles KV writes at ~1000/sec; the publish script can hit this on bulk publishes.
- **`wrangler deploy` from wrong directory** -- STOP. Must `cd ~/projects/snappy-skills` first. Wrangler reads `wrangler.json` from cwd.
- **Hardcoded API key in source** -- REFUSE to commit. Master key is a Worker secret via `wrangler secret put MASTER_KEY`. Client keys live in API_KEYS KV. Never in source.
- **Subrequest budget exhausted during probe** -- the free-tier 50-fetch cap was hit. Use `?offset=N&limit=40` to chunk probes across multiple invocations. The probe handler detects this and sets `exhausted: true` in the response.
- **Publishing without graph rebuild** -- the detail page cross-references and landing page hierarchy will be stale. Always run `/admin/graph/rebuild` after publish.
- **Creating a `client` key without `skills` array** -- they see only public skills (silently degraded). Always pass `&skills=name1,name2`.
- **Compatibility date bump** -- do NOT change `compatibility_date` in wrangler.json unless tested. Worker is stable on `2025-04-01`.
- **Auth env not loaded** -- master key value lives in `~/.claude/skills/snappy-settings/.env.cache` as `SNAPPY_MASTER_KEY`. Read via `env("SNAPPY_MASTER_KEY")` or `source ~/.claude/skills/snappy-settings/scripts/load-env.sh`. Never hardcode. Bitwarden was removed on 2026-04-08 -- do not reintroduce any sync layer.

---

## Anti-patterns

| WRONG | RIGHT |
|---|---|
| Editing KV directly via `wrangler kv key put` | Use `publish-skill.js` -- it handles index.json + metadata |
| `wrangler kv key list` without `--remote` | Always pass `--remote` -- wrangler defaults to local emulator |
| Publishing without version bump in `.snappy-meta.json` | Bump per semver table in SKILL.md; publish script recomputes checksum |
| Editing skill content via the gateway | Edit locally in `~/.claude/skills/`, then publish |
| Adding a view without importing `topbar.ts` | Every view must use `themeStyles()`, `themeHeadScript()`, `topbarStyles()`, `topbarHtml()`, `topbarScript()` |
| Hardcoding theme colors | Use CSS variables (`--bg`, `--card`, `--primary`, etc.) |
| Adding a POST route without updating the allowlist | `index.ts` has an explicit POST path allowlist -- add your route there |
| Skipping `canAccessFile` check on new file-serving routes | All file/zip endpoints must call `canAccessFile` to prevent URL-guessing bypass |
| Caching subrequest-exhausted probe results | The probe handler already skips caching these -- don't change that |
| Running all probes in one shot | Chunk with `?offset=N&limit=40` to stay under the 50-subrequest cap |

---

## Reference (last resort)

Full docs: `~/.claude/skills/snappy-gateway/SKILL.md`, `infrastructure.md`, `key-management.md`, `publishing.md`. Worker source: `~/projects/snappy-skills/src/`. Read them only when this AGENTS.md doesn't cover the case. Default to this file.


Show produced work with `snappy-faces`: call `draw` for image channels or `lang` for MCP Apps.

<!-- SKILL-INDEX-START -->
[snappy-gateway Index]|root: ~/.claude/skills/snappy-gateway|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,infrastructure.md,key-management.md,publishing.md}
<!-- SKILL-INDEX-END -->

## Used by

- `snappy-skill`

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `get` | `name` | `read` | `npx tsx ~/.claude/skills/snappy-gateway/api.ts get "<name>"` |
| `list` | — | `read` | `npx tsx ~/.claude/skills/snappy-gateway/api.ts list` |
| `card` | `name` | `read` | `npx tsx ~/.claude/skills/snappy-gateway/api.ts card "<name>"` |
| `publish` | `name?`, `tier?` | `post` | `npx tsx ~/.claude/skills/snappy-gateway/api.ts publish` |
| `pull` | `name` | `write-reversible` | `npx tsx ~/.claude/skills/snappy-gateway/api.ts pull "<name>"` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-gateway
reports_to: plumbing
head: false
description: >
  Snappy Skills Gateway -- publish, gate, and distribute Claude Code skills via
  skills.snappy.ai (Cloudflare Worker + KV). Manage API keys, access tiers (public/
  client/subscriber/personal), publish skill bundles with a parsed card a stranger
  can evaluate, pull a published skill into a skills root, version via
  .snappy-meta.json checksums, revoke access, view catalog, deploy Worker updates.
  Implements the Cloudflare Agent Skills Discovery RFC at /.well-known/skills/.
  Triggers on: snappy skills, skills gateway, publish skill, skill card,
  skill keys, manage skills,
  skills.snappy.ai, skill marketplace, create skill key, revoke key, distribute skills,
  skill access, skill tiers, gated skills, .snappy-meta.json, skill checksum, skill
  version, kv namespace, wrangler deploy gateway, well-known skills.
---

# Snappy Skills Gateway

Manage the gated skills gateway at `https://skills.snappy.ai` -- Cloudflare Worker + KV that distributes Claude Code skills with tiered access control.

## Purpose

Publish, distribute, and gate Claude Code skills via `skills.snappy.ai`. Built on Cloudflare Workers + KV following the Agent Skills Discovery RFC (`/.well-known/skills/`). Handles versioning via `.snappy-meta.json` checksums, four access tiers, and per-client skill scoping.

## When to Use This Skill

Activates when:
- Publishing a skill to the gateway (`node scripts/publish-skill.js`)
- Creating, listing, or revoking API keys for clients/subscribers
- Updating a published skill (re-runs publish; checksum tells if anything changed)
- Checking the skills catalog or key list
- Deploying Worker code or KV namespace updates (`npx wrangler deploy`)
- Any mention of "snappy skills", "skills.snappy.ai", "publish skill", "skill keys", ".snappy-meta.json"

---

## Quick Start

### View the catalog
```bash
curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq .
```

### Publish a skill
```bash
cd ~/Projects/snappy-skills
node scripts/publish-skill.js <name> <path> <tier>
```

### Create a client key
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=ClientName&tier=client&skills=skill1,skill2"
```

### List all keys
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  https://skills.snappy.ai/admin/keys | jq .
```

### Revoke a key
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/revoke?key=snappy_xxx"
```

---

## Workflow

The gateway is a **distribution channel** for skills authored locally. It does not generate skill content -- it serves it.

**Inputs (skills/sources that feed this one):**
- `skill-builder` -- provides the structural template skills must follow before publish
- `~/.claude/skills/<name>/` -- local skill directories sourced and uploaded to KV
- `snappy-github` -- provides version control for skill source (publish reads from local FS, but FS tracks git)
- `snappy-deploy` -- provides Worker deploy mechanics (`npx wrangler deploy`)

**Outputs (consumers that read from this one):**
- Claude Code clients fetching `https://skills.snappy.ai/.well-known/skills/index.json`
- Per-client deliverables -- `snappy-client-orbiter`, `snappy-client-scott`, `snappy-client-total` may have skills published as `client` tier
- Subscriber library -- paying mastermind members hit the gateway with their key

**Channels (where output is delivered):**
- HTTPS GET on `skills.snappy.ai` (the gateway IS the channel -- no separate messaging hop)
- `snappy-telegram` -- used to send the API key to a new client/subscriber after creation
- `snappy-email` -- used to onboard new subscribers with their key + access instructions

**Orchestrator:**
- `snappy-ops` triggers a publish whenever a skill is updated and Robert wants subscribers to see it
- `snappy-clients` triggers gating workflows (create key, scope to client skills, send credential)

---

## .snappy-meta.json -- Versioning & Checksums

Every skill in `~/.claude/skills/snappy-*/` carries a `.snappy-meta.json` sidecar that records the version, the SHA-256 checksum of the skill bundle, and per-file sizes. This is the **single source of truth for "did this skill change?"**

### Format

```json
{
  "name": "snappy-gateway",
  "version": "1.0.0",
  "checksum": "sha256:d991ae27468be0f06a210aa249f2f303c5f0163a2b4d81b9d7e97133b5e83470",
  "updated_at": "2026-04-07T10:00:00.000Z",
  "tier": "personal",
  "file_count": 4,
  "total_size": 21726,
  "endpoints_count": 1,
  "files": [
    { "name": "SKILL.md", "size": 6317 },
    { "name": "infrastructure.md", "size": 6314 },
    { "name": "key-management.md", "size": 4632 },
    { "name": "publishing.md", "size": 4463 }
  ]
}
```

### Field semantics

| Field | Source of truth | Meaning |
|-------|----------------|---------|
| `name` | matches directory name | Identifies the skill in the gateway catalog |
| `version` | manual semver | Bumped on publish -- `MAJOR.MINOR.PATCH` (1.0.0 = first published, 1.0.1 = patch fix, 1.1.0 = new section/file, 2.0.0 = breaking restructure) |
| `checksum` | computed from concatenated file bytes | SHA-256 hash; if local computed hash != stored, skill needs republish |
| `updated_at` | ISO 8601, UTC | Last publish timestamp |
| `tier` | `public` / `client` / `subscriber` / `personal` | Access tier -- controls who sees it in the catalog |
| `file_count` | count of files in bundle | Sanity check for publish completeness |
| `total_size` | sum of file bytes | Bandwidth signal for quotas |
| `endpoints_count` | counted from SKILL.md | Number of API endpoints documented (informational) |
| `files[]` | enumerated by publish script | Per-file size -- drives the catalog file listing |

### Compute the checksum locally

```bash
SKILL_DIR="$HOME/.claude/skills/snappy-gateway"
find "$SKILL_DIR" -type f \
  ! -name '.snappy-meta.json' \
  ! -name '.DS_Store' \
  | sort \
  | xargs cat \
  | shasum -a 256 \
  | awk '{print "sha256:"$1}'
```

If the result differs from `.snappy-meta.json` `checksum`, you have local changes that haven't been published.

### When to bump version

| Change | Bump |
|--------|------|
| Typo / link fix / phrasing tweak | PATCH (1.0.0 → 1.0.1) |
| New resource file or new section in SKILL.md | MINOR (1.0.0 → 1.1.0) |
| Restructure that breaks existing references / removed content | MAJOR (1.0.0 → 2.0.0) |
| Tier change (e.g. public → subscriber) | MINOR + record reason in commit message |

### Publish flow (end-to-end)

```
1. Edit ~/.claude/skills/snappy-gateway/* locally
2. Bump version in .snappy-meta.json (per table above)
3. Recompute checksum, update updated_at, file_count, total_size, files[]
   (or just re-run the publish script which does this for you)
4. cd ~/Projects/snappy-skills
5. node scripts/publish-skill.js snappy-gateway ~/.claude/skills/snappy-gateway personal
   ↓
   Reads every file in the directory recursively
   Uploads each file to SKILLS_STORE KV at key `snappy-gateway/<filename>`
   Parses SKILL.md frontmatter (name + description) for catalog
   Updates index.json in KV (upserts the skill entry, records checksum, version, tier)
6. Verify: curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq '.skills[] | select(.name=="snappy-gateway")'
7. Commit .snappy-meta.json + content changes to git (snappy-github tracks history)
```

`.snappy-meta.json` is **not** uploaded to KV -- it lives in the local filesystem only. The catalog `index.json` in KV stores the same metadata (version, checksum, tier) but as the source of truth for the gateway. Local meta is the source of truth for "is this skill ready to publish?"; KV index is the source of truth for "is this skill published?"

---

## The store: a card, the base set, and Add it

⟨the owner, 2026-09-09 16:4x⟩ *"Treat it like a very flexible plugin store …
you can't see what a skill does or evaluate it against another. When someone
installs this they should be able to click and add."*

**The listing is a parse, never a blurb somebody typed.** `card.ts` builds it
from the things that already exist and are already checked: the one AGENTS.md
parser (`snappy-settings/agents-md.ts`) for the purpose, the verbs with their
first call, the faces, the agents and the cross-links; `snappy-tool-design
lint` for the grade; the committed vendor corpus for the trust line. So a card
reads:

```
snappy-slack · 45 of 53 checks pass · covers 9 of 174 operations of Slack, checked 2026-09-09
```

Publishing writes `card.json` beside the files and puts the same card (without
the OpenAPI document) into `index.json`, so a reader compares two skills
without opening either.

```bash
npx tsx ~/.claude/skills/snappy-gateway/api.ts card snappy-slack      # build it, publish nothing
npx tsx ~/.claude/skills/snappy-gateway/api.ts publish --base-set     # every base skill, idempotent by checksum
npx tsx ~/.claude/skills/snappy-gateway/api.ts publish --base-set --dry-run
npx tsx ~/.claude/skills/snappy-gateway/api.ts pull snappy-slack      # Add it, into the person's skills root
```

**The base set is the gate's answer, not a list here.** `--base-set` publishes
every skill this repo holds except the ones
`scripts/gates/base-set.mjs` keeps private, read through its own
`scripts/gates/personal-tier.mjs`. That gate runs FIRST on every publish and
nothing is uploaded if it finds anything of his — a publish is irreversible in
the only way that matters, so the check cannot come afterwards.

**A Worker code change is a separate act.** These verbs write KV. Changing what
skills.snappy.ai SERVES is `npx wrangler deploy` from `~/projects/snappy-skills`
and belongs to whoever runs the release.

## Access Tiers

| Tier | Sees | Key Required | Use Case |
|------|------|-------------|----------|
| `public` | Only `public` skills | No | Free skills for everyone |
| `client` | `public` + their scoped skills | Yes | Skills built for a specific client |
| `subscriber` | Everything except `personal` | Yes | Paying subscribers, full library |
| `personal` | Everything | Master key | Robert only |

### How Gating Works

1. **No key** → user sees only `public` tier skills in the catalog
2. **Client key with `skills` array** → sees only those specific skills (regardless of tier)
3. **Client key without `skills` array** → sees `public` skills only
4. **Subscriber key** → sees all skills except `personal`
5. **Master key** → sees everything

---

## Navigation Guide

| Need to... | Read this |
|------------|-----------|
| Publish skills, manage catalog | [publishing.md](publishing.md) |
| Create/revoke/list API keys | [key-management.md](key-management.md) |
| Deploy Worker updates, infrastructure | [infrastructure.md](infrastructure.md) |

---

## Quick Reference -- All Admin Commands

### Environment Setup
The master key lives in `~/.claude/skills/snappy-settings/.env.cache` as `SNAPPY_MASTER_KEY`. Load it via:
```bash
source ~/.claude/skills/snappy-settings/scripts/load-env.sh
# or from TypeScript: env("SNAPPY_MASTER_KEY") from ../snappy-settings/load.ts
```

### Publish a Skill
```bash
cd ~/Projects/snappy-skills
node scripts/publish-skill.js snappy-docs ~/.claude/skills/snappy-docs public
node scripts/publish-skill.js client-tool ~/.claude/skills/client-tool client
node scripts/publish-skill.js my-private ~/.claude/skills/my-private personal
```

### Key Management
```bash
# Create client key (scoped to specific skills)
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Acme%20Corp&tier=client&skills=acme-workflows,snappy-docs"

# Create subscriber key (sees full library, with expiry)
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=John%20Doe&tier=subscriber&expires=2026-12-31"

# Create client key (no skills scope = public only)
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Free%20User&tier=client"

# List all keys
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  https://skills.snappy.ai/admin/keys | jq .

# Revoke a key
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/revoke?key=snappy_a8f3xxxx"
```

### Test Access
```bash
# Public view (no auth)
curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq .

# Authenticated view
curl -s -H "Authorization: Bearer snappy_a8f3xxxx" \
  https://skills.snappy.ai/.well-known/skills/index.json | jq .

# Fetch a specific skill file
curl -s https://skills.snappy.ai/.well-known/skills/snappy-docs/SKILL.md
```

### Deploy Worker Updates
```bash
cd ~/Projects/snappy-skills
npx wrangler deploy
```

---

## Architecture

```
Client Request
    ↓
skills.snappy.ai (Cloudflare Worker)
    ↓
Auth Check (API_KEYS KV) → KeyRecord { tier, name, skills?, expires? }
    ↓
Tier Filter → catalog filtered by access level
    ↓
SKILLS_STORE KV → serve skill files
```

**Storage:** KV-only (no R2)
- `SKILLS_STORE` -- skill files + index.json
- `API_KEYS` -- access tokens → KeyRecord JSON

**Endpoints:**
- `GET /` -- landing page
- `GET /.well-known/skills/index.json` -- filtered catalog
- `GET /.well-known/skills/{name}/*` -- skill files (access-checked)
- `GET /admin/keys` -- list all keys (master only)
- `GET /admin/keys/create?name=&tier=&skills=&expires=` -- create key
- `GET /admin/keys/revoke?key=` -- revoke key

---

## Key Files

| File | Location |
|------|----------|
| Worker source | `~/Projects/snappy-skills/src/index.ts` |
| Wrangler config | `~/Projects/snappy-skills/wrangler.json` |
| Publish script | `~/Projects/snappy-skills/scripts/publish-skill.js` |

---

## Resource Files

### [publishing.md](publishing.md)
How to publish skills -- tiers, the publish script, skill structure, updating/removing skills

### [key-management.md](key-management.md)
Creating, listing, revoking API keys -- client onboarding, subscriber management, expiry

### [infrastructure.md](infrastructure.md)
Cloudflare Worker deployment, KV namespaces, custom domain, wrangler commands

---

## What AI Agents Get Wrong

| Wrong | Right |
|-------|-------|
| `wrangler kv key list` (no `--remote`) | Always pass `--remote` -- wrangler defaults to local emulator |
| Editing the SKILL.md and assuming the change is live | The change is local until `node scripts/publish-skill.js` runs and the catalog `index.json` updates |
| Hand-editing `.snappy-meta.json` without re-running the publish script | The publish script recomputes checksum + sizes -- let it own the file or use the bash one-liner above |
| Publishing without bumping `version` | Subscribers won't know there's an update; bump per the version table |
| Creating a `client` tier key without `skills` array | They'll see only public skills (silently degraded) -- always pass `&skills=name1,name2` |
| Setting `compatibility_date` to latest | Worker is stable on the date in `wrangler.json` -- do not bump unless tested |
| Forgetting `Authorization: Bearer $SNAPPY_MASTER_KEY` on admin endpoints | All `/admin/*` endpoints 401 without it |
| Hardcoding the master key in scripts | Use `$SNAPPY_MASTER_KEY` env var; the value lives in `~/.claude/skills/snappy-settings/.env.cache` -- read via `env("SNAPPY_MASTER_KEY")` or `source load-env.sh` |

---

## Related Skills

| Skill | Why |
|-------|-----|
| `skill-builder` | Provides the structural template skills must follow before they're publish-worthy (YAML frontmatter, sections, line limits) |
| `snappy-docs` | Notion workspace automation -- published as a `public` skill on the gateway |
| `snappy-deploy` | Generic deploy meta-skill -- covers the `npx wrangler deploy` step for the Worker, but publish-skill.js is gateway-specific and lives here |
| `snappy-github` | Source of truth for skill content -- local files tracked in git, gateway publishes from local FS |
| `snappy-clients` | Triggers the gating workflow when a new client signs on (create key, scope skills, send credentials) |
| `snappy-telegram` | Channel for delivering newly created API keys to clients/subscribers |
| `snappy-email` | Channel for onboarding emails containing skill access credentials |
| `snappy-ops` | Orchestrates publish during weekly review when subscribers need updates |
| `snappy-ax` | NOT this one. It presses buttons on this Mac through Accessibility; the words it shares with this skill are "keys" and "access", and they mean keystrokes and a macOS grant there, an API token and a tier here. |

---

**Skill Status**: COMPLETE
**Line Count**: < 500
**Progressive Disclosure**: 3 resource files

<!-- SNAPPY-NEAR-NEIGHBOURS-START -->
## Near neighbours

These hands share enough of this one's words that a model can pick the wrong
door. Each row says what the other one is for; open that one instead when its
job is the job.

| Hand | What it is for |
|---|---|
| `snappy-agent-host` | Run the REAL Claude Code, Codex, and Gemini CLIs through ACP via the skills MCP, with durable per-folder se... |
| `snappy-client-template` | Canonical template for creating per-client skills (snappy-client-CLIENTNAME) |
| `snappy-deploy` | Meta-deployment skill that orchestrates ALL Snappy project deployments across the four supported platforms... |
| `snappy-github` | Centralized GitHub operations across all Snappy client repos via the `gh` CLI -- pull request creation, cod... |
| `snappy-imessage` | iMessage on THIS Mac -- the one holding Messages.app -- through the hand's own verbs (`api.ts send/recent/c... |
| `snappy-maintenance` | Snappy project maintenance -- keeping all client and internal systems healthy across Vercel, Fly.io, Cloudf... |
| `snappy-openrouter` | Single canonical interface to OpenRouter for the Snappy system |
| `snappy-slack` | Slack operations channel for Snappy via Xano API (`api:hZB4Dj0c` + `api:XOwEm4wm`) |
| `snappy-telegram` | Telegram Bot API channel for Snappy: direct calls to api.telegram.org (no Xano middleware) to send text, ph... |
| `snappy-whatsapp` | WhatsApp messaging channel for Snappy via Xano API (`api:hZB4Dj0c`) |
| `snappy-xano-mcp` | THE EXISTING, DEPLOYED Snappy MCP server: the Cloudflare Worker exposing the Snappy Xano API (email, calend... |
<!-- SNAPPY-NEAR-NEIGHBOURS-END -->

#!/usr/bin/env npx tsx
/**
 * snappy-gateway/api.ts -- the store at skills.snappy.ai, from this repo.
 *
 * ⟨the owner, 2026-09-09 16:4x⟩ *"If there are base skills, treat it like a very
 * flexible plugin store … When someone installs this they should be able to
 * click and add. I have skills.snappy.ai — the concept was to share these
 * capabilities."*
 *
 * FIVE VERBS, and the shape of the store is in them: `list` and `get` read the
 * catalogue, `card` is what a stranger evaluates a skill BY, `publish` puts the
 * base set there with its card, and `pull` is Add it.
 *
 * THE WORK IS NOT HERE. `card.ts` builds the listing out of the one AGENTS.md
 * parser, the one grader and the committed vendor corpus; `publish.ts` is the
 * one road to KV and the one road back. This file is the CLI and the contract
 * over them, and it keeps no second opinion about anything they answer.
 *
 * Usage:
 *   npx tsx api.ts list
 *   npx tsx api.ts get snappy-slack
 *   npx tsx api.ts card snappy-slack
 *   npx tsx api.ts publish snappy-slack
 *   npx tsx api.ts publish --base-set [--dry-run]
 *   npx tsx api.ts pull snappy-slack [--root DIR]
 */

import { env } from "../snappy-settings/load.ts";
import { boundRows, limitSchema, takeLimit } from "../snappy-settings/read-limit.ts";
import { realpathSync } from "fs";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";
import { GATEWAY } from "./publish.ts";

/**
 * THE MASTER KEY HAS ONE SPELLING AND IT IS `SNAPPY_MASTER_KEY`.
 *
 * Measured 2026-09-09: this function read `SNAPPY_GATEWAY_MASTER_KEY` and
 * `MASTER_KEY`, and the cache holds neither — so every `list` here had been
 * quietly answering with the PUBLIC view of the catalogue while reporting
 * nothing was wrong. `SKILL.md` has named the real key since April; the two
 * fallbacks are kept because a Worker secret is spelled `MASTER_KEY` and an
 * operator with it exported should not be refused.
 */
function masterKey(): string {
  return env("SNAPPY_MASTER_KEY", false) || env("SNAPPY_GATEWAY_MASTER_KEY", false) || env("MASTER_KEY", false) || "";
}

/** List all skills from the gateway catalog. */
export async function listSkills(): Promise<any[]> {
  const key = masterKey();
  const headers: Record<string, string> = key ? { Authorization: `Bearer ${key}` } : {};
  const res = await fetch(`${GATEWAY}/.well-known/skills/index.json`, { headers });
  if (!res.ok) throw new Error(`Gateway list failed: ${res.status}`);
  const data = await res.json();
  return data.skills || [];
}

/** Get a specific skill's SKILL.md from the catalog. */
export async function getSkill(name: string): Promise<any> {
  const key = masterKey();
  const headers: Record<string, string> = key ? { Authorization: `Bearer ${key}` } : {};
  const res = await fetch(`${GATEWAY}/.well-known/skills/${name}/SKILL.md`, { headers });
  if (!res.ok) throw new Error(`Skill ${name} not found: ${res.status}`);
  return { name, content: await res.text() };
}

/** THE CARD for one local skill, without publishing anything. */
export async function skillCard(name: string) {
  const { buildCard, originTier, readCardSources } = await import("./card.ts");
  const { SKILLS_ROOT, gatewayTier } = await import("./publish.ts");
  const { join } = await import("node:path");
  const sources = await readCardSources(SKILLS_ROOT);
  let openapi = null;
  try {
    const { contractOpenApi } = await import("../snappy-settings/contract-openapi.ts");
    const { loadContract } = await import("../snappy-tool-design/api.ts");
    openapi = contractOpenApi(await loadContract(name) as never);
  } catch { /* instructions, not a hand — the card says so by carrying none */ }
  return buildCard(SKILLS_ROOT, name, sources, { tier: gatewayTier(originTier(join(SKILLS_ROOT, name))), openapi });
}

/** Publish one skill, or the whole base set, with its card. */
export async function publishSkill(
  skillName?: string,
  options: { baseSet?: boolean; dryRun?: boolean; force?: boolean; newCatalog?: boolean } = {},
) {
  const { baseSetSkills, publishSkills } = await import("./publish.ts");
  const names = options.baseSet ? await baseSetSkills() : [skillName!];
  return publishSkills(names, options);
}

/** Add it: install a published skill into a person's own skills root. */
export async function pull(name: string, root?: string) {
  const { pullSkill } = await import("./publish.ts");
  return pullSkill(name, { root, key: masterKey() || undefined });
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
export const HAND_CONTRACT = {
  skill: "snappy-gateway",
  description: "Snappy Skills Gateway -- publish, gate, and distribute Claude Code skills via skills.snappy.ai (Cloudflare Worker + KV). Manage API keys, access tiers (public/ client/subscriber/personal), publish skill bundles with a parsed card a stranger can evaluate, pull a published skill into a skills root, version via .snappy-meta.json checksums, revoke access, view catalog, deploy Worker updates. Implements the Cloudflare Agent Skills Discovery RFC at /.well-known/skills/. Triggers on: snappy skills, skills gateway, publish skill, skill card, skill keys, manage skills, skills.snappy.ai, skill marketplace, create skill key, revoke key, distribute skills, skill access, skill tiers, gated skills, .snappy-meta.json, skill checksum, skill version, kv namespace, wrangler deploy gateway, well-known skills.",
  managed: true,
  requires: [] as string[],
  refusals: refusalTable("unknown_verb", "missing_argument", "missing_credential", "not_found", "approval_required"),
  verbs: {
    get: {
      args: ["name"], effect: "read",
      class: "read", execution: "call", openWorld: true,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
      inputSchema: { properties: { name: { type: "string", description: "Gateway entry to read" } } },
    },
    list: {
      args: [], flags: { limit: "--limit" }, effect: "read",
      class: "read", execution: "call", openWorld: true,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
      inputSchema: { properties: {
        limit: limitSchema(200, "How many gateway entries to return"),
      } },
    },
    card: {
      args: ["name"], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      inputSchema: { properties: { name: { type: "string", description: "Local skill whose listing card is built and printed" } } },
    },
    publish: {
      args: ["name?", "tier?"], effect: "post",
      flags: { "base-set": "--base-set", "dry-run": "--dry-run", force: "--force", "new-catalog": "--new-catalog" },
      class: "send-to-a-person", execution: "call", openWorld: true,
      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
      inputSchema: { properties: {
        name: { type: "string", description: "Gateway entry published; omit with --base-set" },
        tier: { type: "string", description: "Audience tier the entry is published to" },
      } },
    },
    pull: {
      args: ["name"], effect: "write-reversible",
      flags: { root: "--root" },
      class: "additive-write", execution: "call", idempotent: true, openWorld: true,
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
      inputSchema: { properties: {
        name: { type: "string", description: "Published skill installed into the person's skills root" },
        root: { type: "string", description: "Directory the skill is written into; defaults to the runner's recorded skills root" },
      } },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;
    const flag = (name: string) => args.includes(`--${name}`);
    const value = (name: string) => {
      const at = args.indexOf(`--${name}`);
      return at >= 0 ? args[at + 1] : undefined;
    };
    // A flag that takes a value swallows the word after it, so that word is
    // not a positional. Without this, `pull x --root /tmp/y` read /tmp/y as a
    // second skill name.
    const VALUE_FLAGS = new Set(["--root", "--limit"]);
    const words = args.filter((arg, index) => !arg.startsWith("--") && !VALUE_FLAGS.has(args[index - 1] ?? ""));

    switch (cmd) {
      case "list": {
        const bound = takeLimit(args, { maximum: 200 });
        if (bound.refusal) { console.log(JSON.stringify(bound.refusal, null, 2)); process.exit(1); }
        const skills = boundRows(await listSkills(), bound.limit);
        for (const s of skills) {
          const checks = s.card?.checks?.line ? `\t${s.card.checks.line}` : "";
          console.log(`${s.name}\t${s.tier || "?"}${checks}\t${(s.description || "").slice(0, 100)}`);
        }
        break;
      }
      case "get": {
        const [name] = words;
        if (!name) { console.error("Usage: api.ts get <name>"); process.exit(1); }
        const skill = await getSkill(name);
        console.log(skill.content);
        break;
      }
      case "card": {
        const [name] = words;
        if (!name) { console.error("Usage: api.ts card <name>"); process.exit(1); }
        console.log(JSON.stringify(await skillCard(name), null, 2));
        break;
      }
      case "publish": {
        const baseSet = flag("base-set");
        const [name, tier] = words;
        if (!baseSet && !name) { console.error("Usage: api.ts publish <name> [tier] | api.ts publish --base-set"); process.exit(1); }
        void tier;
        const report = await publishSkill(name, {
          baseSet, dryRun: flag("dry-run"), force: flag("force"), newCatalog: flag("new-catalog"),
        });
        for (const row of report.rows) {
          if (row.state === "unchanged") { console.log(`  unchanged  ${row.skill} v${row.version}`); continue; }
          console.log(`  published  ${row.skill} v${row.version} (${row.files} files, ${row.checks}${row.coverage ? `, ${row.coverage}` : ""})`);
        }
        console.log(`${report.dry_run ? "[dry run] " : ""}${report.published} published, ${report.unchanged} unchanged, ${report.catalog_size} in the catalogue`);
        break;
      }
      case "pull": {
        const [name] = words;
        if (!name) { console.error("Usage: api.ts pull <name> [--root DIR]"); process.exit(1); }
        const done = await pull(name, value("root"));
        console.log(`${done.skill} → ${done.root}/${done.skill} (${done.files.length} files${done.card ? " + card" : ""})`);
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|get|card|publish|pull] ...");
    }
  })().catch((error) => {
    console.error(error instanceof Error ? error.message : String(error));
    process.exitCode = 1;
  });
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { mkdirSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { buildCard, bundleChecksum, bundleFiles, indexCard, originTier, releaseFiles, type CardSources } from "./card.ts";
import { baseSetSkills, gatewayTier, REPO_ROOT, SKILLS_ROOT } from "./publish.ts";
import { personalSkills } from "../../scripts/gates/personal-tier.mjs";

/**
 * THE CARD IS THE PRODUCT HERE ⟨the owner, 2026-09-09 16:2x: "the card as the
 * shareable, evaluable unit — kind of like an eval"⟩, so what is tested is what
 * a stranger reads off it, and the one thing that must never happen: a folder
 * the base-set gate keeps private appearing in the store's publish list.
 *
 * Nothing below reaches the network or wrangler. The two heavy sources — the
 * grader and the vendor corpus — are handed in, which is exactly why
 * `buildCard` takes a `CardSources` instead of fetching its own.
 */

function scratchSkill(): { dir: string; clean: () => void } {
  const dir = mkdtempSync(join(tmpdir(), "snappy-card-"));
  mkdirSync(join(dir, "skills/snappy-fake/resources"), { recursive: true });
  const skill = join(dir, "skills/snappy-fake");
  writeFileSync(join(skill, "SKILL.md"), "---\nname: snappy-fake\n---\n# snappy-fake\n");
  writeFileSync(join(skill, "AGENTS.md"), "# snappy-fake\n\nA loader.\n");
  writeFileSync(join(skill, "resources/deep.md"), "deep\n");
  writeFileSync(join(skill, ".snappy-meta.json"), JSON.stringify({ name: "snappy-fake", tier: "base" }));
  writeFileSync(join(skill, ".DS_Store"), "junk");
  writeFileSync(join(skill, "config.env"), "TOKEN=nope");
  return { dir: skill, clean: () => rmSync(dir, { recursive: true, force: true }) };
}

test("the bundle carries the skill and never a dotfile, a .DS_Store or config.env", () => {
  const { dir, clean } = scratchSkill();
  try {
    assert.deepEqual(bundleFiles(dir), ["AGENTS.md", "SKILL.md", "resources/deep.md"]);
  } finally { clean(); }
});

test("the checksum is the version: same bytes same hash, one byte changed a different one", () => {
  const { dir, clean } = scratchSkill();
  try {
    const files = bundleFiles(dir);
    const first = bundleChecksum(dir, files);
    assert.equal(bundleChecksum(dir, files), first, "the same bundle must hash the same twice, or nothing is idempotent");
    writeFileSync(join(dir, "SKILL.md"), "---\nname: snappy-fake\n---\n# snappy-fake\n\nedited\n");
    assert.notEqual(bundleChecksum(dir, files), first);
  } finally { clean(); }
});

test("an unmarked skill is base, never excused — the same default the gate takes", () => {
  const { dir, clean } = scratchSkill();
  try {
    assert.equal(originTier(dir), "base");
    writeFileSync(join(dir, ".snappy-meta.json"), JSON.stringify({ tier: "personal" }));
    assert.equal(originTier(dir), "personal");
    writeFileSync(join(dir, ".snappy-meta.json"), "{ not json");
    assert.equal(originTier(dir), "base", "a meta nobody can parse is not a claim of privacy");
  } finally { clean(); }
});

test("only personal stays personal; base and unmarked publish as public", () => {
  assert.equal(gatewayTier("personal"), "personal");
  assert.equal(gatewayTier("base"), "public");
  assert.equal(gatewayTier(""), "public");
});

/** The one that matters. A name in both lists is a client's folder on a public
 *  URL, and nobody would find out from this repo. */
test("the publish list never contains a skill the base-set gate keeps private", async () => {
  const personal = personalSkills(REPO_ROOT) as Set<string>;
  const publishing = await baseSetSkills();
  assert.ok(personal.size > 0, "the gate should be withholding something; if it withholds nothing, this test proves nothing");
  for (const name of personal) {
    assert.ok(!publishing.includes(name), `${name} is kept private by the gate but the store would publish it`);
  }
  assert.ok(publishing.includes("snappy-runner"), "the product skill is the first card a stranger sees and must be in the base set");
});

function sources(over: Partial<CardSources> = {}): CardSources {
  return {
    lint: new Map([["snappy-fake", {
      pass: 45, fail: 2, defer: 8,
      rules: [
        { id: 4, rule: "Near-neighbour descriptions cross-reference each other", status: "FAIL", detail: "near neighbours not named: snappy-desktop" },
        { id: 54, rule: "At least three eval scenarios precede ready status", status: "FAIL", detail: "1 scenario, 3 precede ready" },
        { id: 1, rule: "Skill name satisfies the open spec", status: "PASS", detail: "ok" },
      ],
    }]]),
    specs: new Map([["snappy-fake", {
      kind: "openapi", url: "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/x.json",
      version: "1.7.0", family: "swagger", fetched_at: "2026-09-09T04:00:00.000Z",
      operations: { a: {}, b: {}, c: {} }, operations_total: 174,
    }]]),
    loaders: new Map(),
    usedBy: new Map([["snappy-fake", ["snappy-ops"]]]),
    ...over,
  };
}

test("the eval line counts the checks that RAN — a DEFER is not a failure", () => {
  const { dir, clean } = scratchSkill();
  try {
    const card = buildCard(join(dir, ".."), "snappy-fake", sources(), { tier: "public" });
    assert.equal(card.checks.line, "45 of 47 checks pass");
    assert.equal(card.checks.defer, 8);
    assert.deepEqual(card.checks.failing.map((one) => one.id), [4, 54]);
    assert.equal(card.checks.failing[1].says, "1 scenario, 3 precede ready", "the grader's own sentence, verbatim");
  } finally { clean(); }
});

test("the trust line names the vendor, the numerator, the denominator and the date", () => {
  const { dir, clean } = scratchSkill();
  try {
    const card = buildCard(join(dir, ".."), "snappy-fake", sources(), { tier: "public" });
    assert.equal(card.coverage, "covers 3 of 174 operations of Slack, checked 2026-09-09");
    assert.equal(card.spec?.covers, 3);
    assert.equal(card.spec?.of, 174);
  } finally { clean(); }
});

test("a skill with no vendor document says nothing rather than guessing", () => {
  const { dir, clean } = scratchSkill();
  try {
    const card = buildCard(join(dir, ".."), "snappy-fake", sources({ specs: new Map() }), { tier: "public" });
    assert.equal(card.coverage, null);
    assert.equal(card.spec, null);
  } finally { clean(); }
});

test("a skill nothing has graded says so, and never reports 0 of 0 as a pass rate", () => {
  const { dir, clean } = scratchSkill();
  try {
    const card = buildCard(join(dir, ".."), "snappy-fake", sources({ lint: new Map() }), { tier: "public" });
    assert.equal(card.checks.line, "not graded yet");
    assert.deepEqual(card.checks.failing, []);
  } finally { clean(); }
});

test("the index card drops the OpenAPI document and points at it instead", () => {
  const { dir, clean } = scratchSkill();
  try {
    const card = buildCard(join(dir, ".."), "snappy-fake", sources(), {
      tier: "public",
      openapi: { openapi: "3.1.0", info: { title: "x", version: "1" }, "x-snappy-transport": "cli", servers: [], paths: {}, components: { schemas: {} } },
    });
    const listed = indexCard(card, "https://skills.snappy.ai");
    assert.equal("openapi" in listed, false);
    assert.equal(listed.openapi_url, "https://skills.snappy.ai/.well-known/skills/snappy-fake/card.json");
    assert.equal(listed.checks.line, card.checks.line, "the comparison table keeps every field a reader compares by");
  } finally { clean(); }
});

test("the skills root the publisher reads is this checkout's, not another lane's", () => {
  assert.equal(SKILLS_ROOT, join(REPO_ROOT, "skills"));
});

/** THE NEAR MISS THIS TEST STANDS ON ⟨2026-09-09⟩. The base-set gate judges the
 *  TRACKED tree; a file git does not know about is a file nothing has looked
 *  at. `skills/snappy-tool-design/tool-design-probe.json` is gitignored because
 *  it "holds his mail and his calendar", and a publisher that walked the
 *  directory would have put it on a public URL. */
test("an untracked file inside a skill is never part of what gets published", () => {
  const stray = join(SKILLS_ROOT, "snappy-gateway", "stray-untracked-probe.json");
  writeFileSync(stray, JSON.stringify({ pretend: "his mail" }));
  try {
    const released = releaseFiles(REPO_ROOT, "snappy-gateway", join(SKILLS_ROOT, "snappy-gateway"));
    assert.ok(released.includes("card.ts"), "the tracked files are still there");
    assert.ok(!released.includes("stray-untracked-probe.json"), "an untracked file reached the release set");
    assert.ok(bundleFiles(join(SKILLS_ROOT, "snappy-gateway")).includes("stray-untracked-probe.json"),
      "the plain walk DOES see it — which is exactly why the release reads git instead");
  } finally { unlinkSync(stray); }
});

test("a gitignored vendor tree is not in the release set", () => {
  const released = releaseFiles(REPO_ROOT, "snappy-faces", join(SKILLS_ROOT, "snappy-faces"));
  assert.ok(released.length > 0);
  assert.ok(!released.some((file) => file.startsWith("node_modules")), "node_modules reached the release set");
});

/**
 * THE CARD — the shareable, evaluable unit of a skill.
 *
 * ⟨the owner, 2026-09-09 16:2x–16:4x⟩ *"If there are base skills, treat it like
 * a very flexible plugin store. skills.sh's knocks: full of crap, and you can't
 * see what a skill does or evaluate it against another. When someone installs
 * this they should be able to click and add."* … *"The card as the shareable,
 * evaluable unit — kind of like an eval."*
 *
 * A LISTING IS A PARSE, NEVER A DESCRIPTION SOMEBODY TYPED. Every field below
 * is read out of something that already exists and is already checked:
 *
 *   purpose, verbs, faces, agents, uses, usedBy
 *        → `snappy-settings/agents-md.ts` — the ONE reader of AGENTS.md.
 *   checks (pass / fail / the failing sentences)
 *        → `snappy-tool-design lint` — the ONE grader. This module keeps no
 *          second opinion about how well a hand is built; it reads the grade.
 *   coverage ("covers 9 of 174 operations of Slack, checked <date>")
 *        → `snappy-tool-design/tool-design-specs.json`, the committed vendor
 *          corpus rule 61 reads. Same numerator, same denominator, one file.
 *   openapi
 *        → `snappy-settings/contract-openapi.ts` over the hand's HAND_CONTRACT.
 *
 * So there is no field here a person can inflate, and no field that can be true
 * on the card and false in the repo ⟨CLAUDE.md §4: one representation⟩. That is
 * the whole reason the card is worth comparing two of: it is a MEASUREMENT of a
 * skill, published beside the skill, refreshed every time the skill is.
 *
 * WHAT THE CARD DOES NOT CARRY. No credential, no path inside this Mac, no
 * mail address, no client's name. The card is generated from files the base-set
 * gate (`scripts/gates/base-set.mjs`) has already judged, and the publisher
 * runs that gate before it uploads anything — a red gate stops the publish
 * rather than being noticed afterwards on a public URL.
 */
import { spawnSync } from "node:child_process";
import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
import { createHash } from "node:crypto";
import { dirname, join } from "node:path";
import { parseAgentsMd, usedByIndex, type AgentsMd, type AgentsMdAgent, type AgentsMdVerb } from "../snappy-settings/agents-md.ts";
import { readSpecFile, vendorOf } from "../snappy-tool-design/spec-corpus.ts";
import type { ContractOpenApi } from "../snappy-settings/contract-openapi.ts";

/** The card's own version. A reader that does not know this string should say
 *  so rather than guess at the shape; that is why it is a field and not a
 *  comment. */
export const CARD_SCHEMA = "snappy-card/1" as const;

/** One failing check, in the grader's own sentence. The store shows these
 *  verbatim: "R54 … has 1 eval scenario, 3 precede ready" tells a stranger
 *  more about a skill than any star rating, and it is already written. */
export interface CardCheck {
  id: number;
  rule: string;
  says: string;
}

export interface CardChecks {
  pass: number;
  fail: number;
  defer: number;
  /** "47 of 52 checks pass" — the eval line, computed once so every reader
   *  (the site, the bar, an AI) says the same sentence. DEFER is excluded from
   *  the denominator on purpose: a rule that could not be evaluated is not a
   *  check this skill failed, and counting it would make every hand without a
   *  probe corpus look broken. */
  line: string;
  failing: CardCheck[];
}

/** The vendor document this hand stands on, when it names one. */
export interface CardSpec {
  kind: string;
  vendor: string;
  version: string;
  url: string;
  checked: string;
  /** How many of the vendor's operations this hand's verbs cover, over how many
   *  the document publishes. */
  covers: number;
  of: number;
}

/** The eval manifest's own counts ⟨R55 / R57⟩. A stranger reads this before
 *  Add it: a skill with three scenarios and a disjoint holdout has been driven,
 *  and one with none has not. */
export interface CardEvals {
  scenarios: number;
  holdout: number;
  line: string;
}

export interface SkillCard {
  schema: typeof CARD_SCHEMA;
  skill: string;
  /** The gateway tier this card was published at. */
  tier: string;
  /** The kernel's own word from `.snappy-meta.json`, or "base" when a skill
   *  carries no meta — the same default `scripts/gates/base-set.mjs` takes,
   *  and for its reason: an unmarked skill is judged, never excused. */
  origin_tier: string;
  purpose: string;
  verbs: AgentsMdVerb[];
  faces: string[];
  agents: AgentsMdAgent[];
  uses: string[];
  used_by: string[];
  checks: CardChecks;
  coverage: string | null;
  spec: CardSpec | null;
  evals: CardEvals | null;
  files: string[];
  total_size: number;
  checksum: string;
  built_at: string;
  /** The hand's own contract as an OpenAPI 3.1 document. Present on the card
   *  stored beside the files; DROPPED from the copy in index.json, because the
   *  index is the comparison table and 92 embedded documents would make it a
   *  megabyte nobody can read. `IndexCard` is that projection. */
  openapi: ContractOpenApi | null;
}

/** The card as `index.json` carries it: everything a reader compares two skills
 *  by, without the OpenAPI document. Fetch `<skill>/card.json` for that. */
export type IndexCard = Omit<SkillCard, "openapi"> & { openapi_url: string };

export function indexCard(card: SkillCard, gateway: string): IndexCard {
  const { openapi: _openapi, ...rest } = card;
  return { ...rest, openapi_url: `${gateway}/.well-known/skills/${card.skill}/card.json` };
}

/** Dotfiles, `.DS_Store` and `config.env` never leave this Mac. The list is the
 *  publish script's own, plus `node_modules`, which is a vendor tree a person
 *  installs and never a thing to serve out of KV. */
const EXCLUDED = new Set([".DS_Store", ".gitkeep", "Thumbs.db", "config.env", "node_modules"]);
const isExcluded = (name: string): boolean => name.startsWith(".") || EXCLUDED.has(name);

/**
 * Every file a skill publishes, relative to its directory, sorted.
 *
 * A SYMLINK IS NOT A FILE HERE, and that is measured rather than tidy
 * ⟨2026-09-09, the first base-set dry run: `EISDIR: illegal operation on a
 * directory, read`⟩. `skills/snappy-faces/node_modules` is a symlink to a
 * directory, `Dirent.isDirectory()` answers false for it, and the naive `else`
 * filed it as a file the publisher then tried to read. A bundle is bytes a
 * stranger receives; a link into this Mac's filesystem is not bytes, and there
 * is nothing on the far end of it once it lands on theirs.
 */
export function bundleFiles(dir: string, prefix = ""): string[] {
  const found: string[] = [];
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    if (isExcluded(entry.name)) continue;
    const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
    if (entry.isDirectory()) found.push(...bundleFiles(join(dir, entry.name), rel));
    else if (entry.isFile()) found.push(rel);
  }
  return found.sort();
}

/**
 * WHAT A SKILL ACTUALLY PUBLISHES: THE TRACKED FILES, AND ONLY THOSE.
 *
 * ⟨the near miss, 2026-09-09, this lane⟩ The first working publisher walked the
 * directory. The base-set gate judges the TRACKED TREE — that is what a clone
 * hands a stranger — so a file git does not know about is a file NOTHING has
 * looked at, and the publisher would have put it on a public URL. Sitting in
 * `skills/snappy-tool-design/` at any moment are `tool-design-probe.json` and
 * `tool-design-render.json`: gitignored on purpose, because, in that module's
 * own words, they "hold his mail and his calendar". This worktree happened not
 * to have them. The next one will.
 *
 * So the release unit is `git ls-files`, and the gate and the publisher are
 * then looking at exactly the same bytes. A directory git knows nothing about —
 * a stranger's unpacked copy, a scratch fixture in a test — falls back to the
 * walk, because there the tracked set is not a smaller answer, it is no answer.
 */
export function releaseFiles(repoRoot: string, skill: string, dir: string): string[] {
  const listed = spawnSync("git", ["ls-files", "-z", "--", `skills/${skill}`], {
    cwd: repoRoot, encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
  });
  if (listed.status !== 0) return bundleFiles(dir);
  const prefix = `skills/${skill}/`;
  const files = listed.stdout.split("\0").filter(Boolean)
    .filter((path) => path.startsWith(prefix))
    .map((path) => path.slice(prefix.length))
    .filter((rel) => !rel.split("/").some((part) => isExcluded(part)));
  return files.length > 0 ? files.sort() : bundleFiles(dir);
}

/**
 * THE CHECKSUM IS THE VERSION, and it is computed exactly the way the gateway
 * has computed it since April — sha256 over each sorted filename followed by
 * its bytes. Publishing is idempotent because of this one number: a skill whose
 * checksum equals the catalog's is not uploaded again.
 */
export function bundleChecksum(dir: string, files: readonly string[]): string {
  const hash = createHash("sha256");
  for (const file of [...files].sort()) {
    hash.update(file);
    hash.update(readFileSync(join(dir, file)));
  }
  return `sha256:${hash.digest("hex")}`;
}

export function bundleSize(dir: string, files: readonly string[]): number {
  return files.reduce((total, file) => total + statSync(join(dir, file)).size, 0);
}

/** The kernel's own tier word, or "base" when the skill carries no meta. */
export function originTier(dir: string): string {
  const meta = join(dir, ".snappy-meta.json");
  if (!existsSync(meta)) return "base";
  try {
    const tier = (JSON.parse(readFileSync(meta, "utf8")) as { tier?: unknown }).tier;
    return typeof tier === "string" && tier !== "" ? tier : "base";
  } catch {
    return "base";
  }
}

/** `evals.json`, counted the way R55 and R57 count it. */
function readEvals(dir: string): CardEvals | null {
  const path = join(dir, "evals.json");
  if (!existsSync(path)) return null;
  try {
    const parsed = JSON.parse(readFileSync(path, "utf8")) as { scenarios?: Array<{ split?: string }> };
    const scenarios = Array.isArray(parsed.scenarios) ? parsed.scenarios : [];
    const holdout = scenarios.filter((one) => one?.split === "holdout").length;
    return {
      scenarios: scenarios.length,
      holdout,
      line: `${scenarios.length} eval scenario${scenarios.length === 1 ? "" : "s"}${holdout > 0 ? `, ${holdout} held out` : ""}`,
    };
  } catch {
    return null;
  }
}

function readLoader(dir: string): AgentsMd | null {
  const path = join(dir, "AGENTS.md");
  if (!existsSync(path)) return null;
  return parseAgentsMd(readFileSync(path, "utf8"));
}

const EMPTY_LOADER: Omit<AgentsMd, "skill"> = {
  purpose: "", rules: [], verbs: [], faces: [], agents: [], uses: [], usedBy: [],
  apiModule: null, index: null, unknownSections: [], headings: [],
};

/** What a build needs that is read ONCE for the whole collection: the grade,
 *  the vendor corpus, and every loader (for the derived `## Used by`). */
export interface CardSources {
  /** skill → the grader's result. */
  lint: Map<string, { pass: number; fail: number; defer: number; rules: Array<{ id: number; rule: string; status: string; detail: string }> }>;
  /** skill → the vendor projection rule 61 reads. */
  specs: Map<string, { kind: string; url: string; version: string; family: string; fetched_at: string; operations: Record<string, unknown>; operations_total: number }>;
  loaders: Map<string, AgentsMd>;
  usedBy: Map<string, string[]>;
}

/**
 * READ THE COLLECTION ONCE. `lintAll()` loads every hand's module graph through
 * the one pool; calling it per skill would cost that 92 times over a base-set
 * publish. Both heavy modules are imported dynamically so that merely loading
 * `snappy-gateway`'s contract — which `snappy-tool-design` itself does, for
 * every hand, on every lint — does not drag the grader in behind it.
 */
export async function readCardSources(skillsRoot: string): Promise<CardSources> {
  const { lintAll } = await import("../snappy-tool-design/api.ts");

  const lint = new Map<string, CardSources["lint"] extends Map<string, infer V> ? V : never>();
  for (const result of await lintAll()) {
    lint.set(result.skill, {
      pass: result.pass, fail: result.fail, defer: result.defer,
      rules: result.rules.map((rule) => ({ id: rule.id, rule: rule.rule, status: rule.status, detail: rule.detail })),
    });
  }

  const specs = new Map<string, CardSources["specs"] extends Map<string, infer V> ? V : never>();
  const corpus = readSpecFile(join(skillsRoot, "snappy-tool-design"));
  for (const [skill, projection] of Object.entries(corpus?.skills ?? {})) specs.set(skill, projection);

  // EVERY loader, not just the ones being published: `## Used by` is derived
  // from who names a skill, and a skill named only by an unpublished one is
  // still named ⟨agents-md.ts usedByIndex⟩.
  const loaders = new Map<string, AgentsMd>();
  for (const name of readdirSync(skillsRoot, { withFileTypes: true })) {
    if (!name.isDirectory() || !name.name.startsWith("snappy-")) continue;
    const parsed = readLoader(join(skillsRoot, name.name));
    if (parsed !== null) loaders.set(name.name, parsed);
  }
  return { lint, specs, loaders, usedBy: usedByIndex(loaders) };
}

/**
 * THE CARD, for one skill. Pure over `sources` — the network and the module
 * graph were spent once, above.
 */
export function buildCard(
  skillsRoot: string,
  skill: string,
  sources: CardSources,
  options: { tier: string; openapi?: ContractOpenApi | null } = { tier: "public" },
): SkillCard {
  const dir = join(skillsRoot, skill);
  const loader = sources.loaders.get(skill) ?? { skill, ...EMPTY_LOADER };
  const files = releaseFiles(dirname(skillsRoot), skill, dir);
  const graded = sources.lint.get(skill);

  const pass = graded?.pass ?? 0;
  const fail = graded?.fail ?? 0;
  const defer = graded?.defer ?? 0;
  const ran = pass + fail;
  const checks: CardChecks = {
    pass, fail, defer,
    line: ran === 0 ? "not graded yet" : `${pass} of ${ran} checks pass`,
    failing: (graded?.rules ?? [])
      .filter((rule) => rule.status === "FAIL")
      .map((rule) => ({ id: rule.id, rule: rule.rule, says: rule.detail })),
  };

  const projection = sources.specs.get(skill);
  let spec: CardSpec | null = null;
  let coverage: string | null = null;
  if (projection !== undefined) {
    const vendor = vendorOf(projection.url);
    const covers = Object.keys(projection.operations ?? {}).length;
    spec = {
      kind: projection.kind, vendor, version: projection.version, url: projection.url,
      checked: projection.fetched_at.slice(0, 10), covers, of: projection.operations_total,
    };
    coverage = `covers ${covers} of ${projection.operations_total} operations of ${vendor}, checked ${spec.checked}`;
  }

  return {
    schema: CARD_SCHEMA,
    skill,
    tier: options.tier,
    origin_tier: originTier(dir),
    purpose: loader.purpose,
    verbs: loader.verbs as AgentsMdVerb[],
    faces: loader.faces,
    agents: loader.agents as AgentsMdAgent[],
    uses: loader.uses,
    used_by: sources.usedBy.get(skill) ?? [],
    checks,
    coverage,
    spec,
    evals: readEvals(dir),
    files,
    total_size: bundleSize(dir, files),
    checksum: bundleChecksum(dir, files),
    built_at: new Date().toISOString(),
    openapi: options.openapi ?? null,
  };
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES, type RefusalCode } from "../snappy-settings/refusal-codes.ts";

/** RULE 33 COVERAGE, AGAINST THE ONE CLOSED TABLE ⟨lane r30, 2026-09-09⟩.
 *  This file used to restate a refusal row's own properties — that it has a
 *  `contract_slice`, that it has a `fix`, that it leaks no token — once per
 *  hand, 48 times, over rows that all come from the SAME object. Forty-eight
 *  copies of one check is the duplicate road the closed table exists to end:
 *  `snappy-settings/refusal-codes.test.ts` runs those checks ONCE over every
 *  row, and the second test below proves this hand carries THE ROW ITSELF and
 *  not a copy — an identity a drifted duplicate cannot fake. Before this, each
 *  hand hand-wrote its own row, and the wording had already drifted: the
 *  inline `unknown_verb` said "Call one of the verbs named in
 *  HAND_CONTRACT.verbs" while the closed table says "Call one of the verbs the
 *  contract declares; the refusal lists them."
 *
 *  DECLARED stays a literal list, deliberately. It is this hand's coverage
 *  manifest and it is what rule 33's lint reads out of the test SOURCE to ask
 *  "did a person look at this code" — deriving it from Object.keys would make
 *  the test pass for a hand with no refusals at all. `satisfies readonly
 *  RefusalCode[]` makes the compiler refuse a name the one table does not
 *  have. It NAMES codes; it no longer DEFINES them. */
const DECLARED = [
  "unknown_verb",
  "missing_argument",
  "missing_credential",
  "not_found",
  "approval_required",
] as const satisfies readonly RefusalCode[];

test("snappy-gateway: the refusal table declares exactly the codes this test names", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals ?? {}).sort(), [...DECLARED].sort());
});

test("snappy-gateway: every declared refusal is the one closed table's own row, never a copy", () => {
  const declared = Object.entries(HAND_CONTRACT.refusals ?? {});
  assert.ok(declared.length > 0, "HAND_CONTRACT.refusals is empty");
  for (const [code, row] of declared) {
    assert.ok(code in REFUSAL_CODES, `${code} is not a row of snappy-settings/refusal-codes.ts`);
    assert.equal(row, REFUSAL_CODES[code as RefusalCode], `${code} is a copy of the closed table's row, not the row itself`);
  }
});

# Infrastructure

## Table of Contents
- [Architecture Overview](#architecture-overview)
- [Cloudflare Account](#cloudflare-account)
- [KV Namespaces](#kv-namespaces)
- [Worker Deployment](#worker-deployment)
- [Custom Domain](#custom-domain)
- [Wrangler Commands](#wrangler-commands)
- [Troubleshooting](#troubleshooting)

---

## Architecture Overview

```
                    ┌─────────────────────────┐
                    │   skills.snappy.ai      │
                    │   (Cloudflare Worker)    │
                    └──────────┬──────────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
    ┌─────────▼──────┐ ┌──────▼───────┐ ┌──────▼──────┐
    │   API_KEYS     │ │ SKILLS_STORE │ │ MASTER_KEY  │
    │   (KV)         │ │ (KV)         │ │ (Secret)    │
    │                │ │              │ │             │
    │ snappy_xxx →   │ │ index.json   │ │ Worker env  │
    │ {tier, name,   │ │ skill/file   │ │ secret      │
    │  skills, exp}  │ │ skill/file2  │ │             │
    └────────────────┘ └──────────────┘ └─────────────┘
```

- **No R2** -- everything is KV-based
- **No database** -- keys and files stored as KV key-value pairs
- **No external dependencies** -- fully self-contained Worker

---

## Cloudflare Account

| Property | Value |
|----------|-------|
| Account | Daniel@boulos.io's Account |
| Account ID | `91e4e6d01964d00df36b85bd7e1549eb` |
| Zone | `snappy.ai` |
| Zone ID | `61f56ae113c796ea8da142d1e18b99e0` |
| Worker name | `snappy-skills` |
| Worker URL | `https://snappy-skills.daniel-91e.workers.dev` |
| Custom domain | `https://skills.snappy.ai` |

---

## KV Namespaces

### SKILLS_STORE -- Skill files + catalog
- **ID:** `a090cf5f476946c28ee0e9059865bc37`
- **Contents:** `index.json` + all skill files keyed as `skillname/filename`
- **Example keys:** `index.json`, `snappy-docs/SKILL.md`, `snappy-docs/api-reference.md`

### API_KEYS -- Access tokens
- **ID:** `8ef6507cecc94c5a915e4f0017a88644`
- **Contents:** API key strings → KeyRecord JSON
- **Example key:** `snappy_a8f3e2b1c4d5...` → `{"tier":"client","name":"Acme"}`

---

## Worker Deployment

### Deploy updates
```bash
cd ~/Projects/snappy-skills
npx wrangler deploy
```

### Set/update the master key secret
Load the key from `.env.cache` (single source of truth), then pipe to wrangler:
```bash
cd ~/Projects/snappy-skills
source ~/.claude/skills/snappy-settings/scripts/load-env.sh
echo "$SNAPPY_MASTER_KEY" | npx wrangler secret put MASTER_KEY
```

### View logs
```bash
cd ~/Projects/snappy-skills
npx wrangler tail
```

### Local dev
```bash
cd ~/Projects/snappy-skills
npx wrangler dev
```

---

## Custom Domain

The domain `skills.snappy.ai` is configured as a Workers Custom Domain on Daniel's account. Cloudflare automatically provisions SSL and routes traffic to the Worker.

### Verify domain
```bash
curl -s https://skills.snappy.ai/ | head -5
```

### If domain needs re-attaching
Use the Cloudflare API (requires a valid OAuth token from wrangler config):
```bash
CF_TOKEN=$(cat ~/Library/Preferences/.wrangler/config/default.toml | grep -A2 oauth_token | grep -oE '"[^"]+"' | tr -d '"')

curl -s -X PUT "https://api.cloudflare.com/client/v4/accounts/91e4e6d01964d00df36b85bd7e1549eb/workers/domains" \
  -H "Authorization: Bearer $CF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "skills.snappy.ai",
    "service": "snappy-skills",
    "zone_id": "61f56ae113c796ea8da142d1e18b99e0",
    "environment": "production"
  }'
```

---

## Wrangler Commands

### KV Operations (SKILLS_STORE)
```bash
# List all keys in skills store
wrangler kv key list --namespace-id "a090cf5f476946c28ee0e9059865bc37" --remote | jq -r '.[].name'

# Get a specific file
wrangler kv key get --namespace-id "a090cf5f476946c28ee0e9059865bc37" "index.json" --remote

# Put a file
wrangler kv key put --namespace-id "a090cf5f476946c28ee0e9059865bc37" "key" --path "/path/to/file" --remote

# Delete a key
wrangler kv key delete --namespace-id "a090cf5f476946c28ee0e9059865bc37" "key" --remote
```

### KV Operations (API_KEYS)
```bash
# List all API keys
wrangler kv key list --namespace-id "8ef6507cecc94c5a915e4f0017a88644" --remote | jq -r '.[].name'

# Get a key record
wrangler kv key get --namespace-id "8ef6507cecc94c5a915e4f0017a88644" "snappy_xxx" --remote
```

### IMPORTANT: Always use `--remote`
Wrangler defaults to local persistence. Always add `--remote` to KV commands.

---

## Key Files

| File | Purpose |
|------|---------|
| `~/Projects/snappy-skills/src/index.ts` | Worker source code |
| `~/Projects/snappy-skills/wrangler.json` | Worker configuration |
| `~/Projects/snappy-skills/scripts/publish-skill.js` | Skill publishing script |
| `~/Projects/snappy-skills/package.json` | Project dependencies |
| `~/Projects/snappy-skills/tsconfig.json` | TypeScript config |

---

## Troubleshooting

### "Resource location: local" in wrangler output
You forgot `--remote`. All wrangler KV/R2 commands default to local emulator.

### Skills not appearing after publish
1. Check the publish script output says "Resource location: remote"
2. Verify: `curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq .`
3. KV has eventual consistency -- wait 10-30 seconds and retry

### Auth not working
1. Verify master key is set: `npx wrangler secret list` in the project directory
2. Test: `curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" https://skills.snappy.ai/admin/keys`
3. If 401, re-set the secret: `echo "key" | npx wrangler secret put MASTER_KEY`

### Custom domain not resolving
1. Check DNS: `dig skills.snappy.ai`
2. Check worker is deployed: `curl -s https://snappy-skills.daniel-91e.workers.dev/`
3. Re-attach domain using the API command above

### wrangler OAuth token expired
```bash
npx wrangler login
```
This refreshes the token at `~/Library/Preferences/.wrangler/config/default.toml`.

# Key Management

## Table of Contents
- [Key Concepts](#key-concepts)
- [Creating Keys](#creating-keys)
- [Listing Keys](#listing-keys)
- [Revoking Keys](#revoking-keys)
- [Key Record Structure](#key-record-structure)
- [Common Scenarios](#common-scenarios)

---

## Key Concepts

Every API key maps to a `KeyRecord` stored in KV:

```json
{
  "tier": "client",
  "name": "Acme Corp",
  "skills": ["acme-workflows", "snappy-docs"],
  "expires": "2026-12-31"
}
```

- **tier** -- determines base visibility (public, client, subscriber, personal)
- **name** -- human label for the key holder
- **skills** -- optional array; if set, ONLY these skills are visible regardless of tier
- **expires** -- optional ISO date; after this date, key degrades to public access

All admin endpoints require the master key. Load from `.env.cache`:
```bash
source ~/.claude/skills/snappy-settings/scripts/load-env.sh
# $SNAPPY_MASTER_KEY is now exported
```

---

## Creating Keys

### Client key -- scoped to specific skills
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Acme%20Corp&tier=client&skills=acme-workflows,snappy-docs" | jq .
```
Response:
```json
{
  "key": "snappy_a8f3e2b1c4d5...",
  "tier": "client",
  "name": "Acme Corp",
  "skills": ["acme-workflows", "snappy-docs"]
}
```

### Subscriber key -- full library access with expiry
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=John%20Doe&tier=subscriber&expires=2026-12-31" | jq .
```

### Client key -- no skills scope (sees public only)
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Free%20Trial&tier=client" | jq .
```

### Parameters

| Param | Required | Default | Description |
|-------|----------|---------|-------------|
| `name` | Yes | -- | Human-readable label |
| `tier` | No | `client` | `public`, `client`, `subscriber`, `personal` |
| `skills` | No | -- | Comma-separated skill names to scope access |
| `expires` | No | -- | ISO date string (e.g., `2026-12-31`) |

---

## Listing Keys

```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  https://skills.snappy.ai/admin/keys | jq .
```

Response:
```json
{
  "keys": [
    {
      "key": "snappy_a8f3e2b1c4d5...",
      "tier": "client",
      "name": "Acme Corp",
      "skills": ["acme-workflows"]
    },
    {
      "key": "snappy_b9c4d5e6f7a8...",
      "tier": "subscriber",
      "name": "John Doe",
      "expires": "2026-12-31"
    }
  ]
}
```

---

## Revoking Keys

```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/revoke?key=snappy_a8f3e2b1c4d5..." | jq .
```

Response:
```json
{
  "revoked": true
}
```

Revocation is instant. The key is deleted from KV -- any subsequent request with that key falls back to public access.

---

## Key Record Structure

Keys are stored in the `API_KEYS` KV namespace. The key string (e.g., `snappy_a8f3...`) is the KV key, and the value is a JSON `KeyRecord`:

```typescript
interface KeyRecord {
  tier: "public" | "personal" | "client" | "subscriber";
  name: string;
  skills?: string[];   // if set, only these skills visible
  expires?: string;    // ISO date, optional
}
```

### Visibility Rules

| Tier | `skills` set? | What they see |
|------|--------------|---------------|
| `public` | -- | Only `public` tier skills |
| `client` | Yes | Only the listed skills |
| `client` | No | Only `public` tier skills |
| `subscriber` | -- | All skills except `personal` |
| `personal` | -- | Everything |

### Expiry Behavior
When a key expires (current date > `expires`), it silently degrades to `public` access. The key still works but only sees public skills.

---

## Common Scenarios

### New client project
1. Build their skills locally in `~/.claude/skills/client-name/`
2. Publish: `node scripts/publish-skill.js client-name ~/.claude/skills/client-name client`
3. Create key: `?name=Client%20Name&tier=client&skills=client-name`
4. Send them the key

### Monthly subscriber
1. Create key with 30-day expiry: `?name=Sub%20Name&tier=subscriber&expires=2026-04-23`
2. They get full library access until the date
3. To renew: revoke old key, create new one with new expiry

### Revoking a client
1. List keys to find theirs: `GET /admin/keys`
2. Revoke: `?key=snappy_their_key`
3. Optionally remove their skill files from KV

### Testing what a client sees
```bash
# Use their key to see their view
curl -s -H "Authorization: Bearer snappy_clientkey" \
  https://skills.snappy.ai/.well-known/skills/index.json | jq .
```

/**
 * THE PUBLISHER — one road from this repo to skills.snappy.ai, and one road
 * back.
 *
 * ⟨the owner, 2026-09-09 16:4x⟩ *"If there are base skills, treat it like a very
 * flexible plugin store … When someone installs this they should be able to
 * click and add. I have skills.snappy.ai — the concept was to share these
 * capabilities."*
 *
 * ── WHY THE PUBLISHER MOVED INTO THE SKILL ──────────────────────────────────
 *
 * `snappy-gateway/api.ts publish` used to shell out to
 * `~/projects/snappy-skills/scripts/publish-skill.js`, and that script is now
 * the OLD road. It is not a style preference; three things it could not do are
 * the job:
 *
 *  1. IT COULD NOT CARRY THE CARD. The listing a stranger evaluates is a PARSE
 *     of the skill (`card.ts`) — the loader's verbs and agents, the grader's
 *     pass/fail, the vendor coverage. That parse lives in this repo, beside the
 *     skills; a script in the Worker's repo cannot reach it.
 *  2. IT WROTE `index.json` ONCE PER SKILL. Ninety-two publishes would have
 *     been ninety-two read-modify-writes of one document, each one able to lose
 *     the one before it. The base-set run writes the catalogue ONCE, at the end.
 *  3. IT SPAWNED ONE `wrangler` PER FILE. Measured shape: ~5 files a skill,
 *     92 skills — 460 processes at a second or two each. `wrangler kv bulk put`
 *     takes a whole skill in one call.
 *
 * So this is a COLLAPSE to one, not a second implementation ⟨CLAUDE.md §4:
 * collapsing to one is preferred over reconciling two⟩. The old script must be
 * deleted from the Worker repo by whoever owns that tree; until it is, the two
 * roads exist and this comment is the notice.
 *
 * ── WHAT IT WILL NOT DO ─────────────────────────────────────────────────────
 *
 * IT REFUSES ON A RED GATE. `scripts/gates/base-set.mjs` decides what a
 * stranger may receive; this runs it FIRST, over the whole tracked tree, and
 * uploads nothing if it finds anything of his. A publish is irreversible in the
 * only way that matters — the bytes were public for a while — so the check
 * cannot be after the fact.
 *
 * IT WITHHOLDS EXACTLY WHAT THE GATE WITHHOLDS. The private list comes from
 * `scripts/gates/personal-tier.mjs`, the gate's own reader, imported. There is
 * no list of names in this file.
 *
 * IT DEPLOYS NO WORKER. `wrangler deploy` changes the CODE at skills.snappy.ai
 * and belongs to the person running the release. This writes KV and nothing
 * else.
 */
import { execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { buildCard, indexCard, originTier, readCardSources, type IndexCard, type SkillCard } from "./card.ts";

const HERE = dirname(realpathSync(fileURLToPath(import.meta.url)));
export const SKILLS_ROOT = dirname(HERE);
export const REPO_ROOT = dirname(SKILLS_ROOT);

export const GATEWAY = "https://skills.snappy.ai";

/** SKILLS_STORE. The id is the Worker's, published in `infrastructure.md`; it
 *  is a namespace identifier and not a credential. */
const KV_NAMESPACE_ID = "a090cf5f476946c28ee0e9059865bc37";

/** `wrangler` reads its account and config from the cwd it is started in, so
 *  every call below is made from the Worker's own repo ⟨AGENTS.md: "wrangler
 *  deploy from wrong directory — STOP"⟩. */
const WORKER_REPO = join(homedir(), "projects/snappy-skills");

/** THE KERNEL'S TIER WORD → THE GATEWAY'S. `base` and an unmarked skill are
 *  the product, and the product is what he wanted to share, so both publish as
 *  `public`. `personal` never reaches this map: the gate's list is subtracted
 *  before anything is built. */
export function gatewayTier(originTier: string): string {
  return originTier === "personal" ? "personal" : "public";
}

export interface CatalogEntry {
  name: string;
  description: string;
  tier: string;
  install_method: "files";
  version: string;
  checksum: string;
  updated_at: string;
  total_size: number;
  files: string[];
  /** The parsed card — what makes this catalogue comparable rather than a list
   *  of names ⟨the owner: "you can't see what a skill does or evaluate it
   *  against another"⟩. */
  card: IndexCard;
}

export interface Catalog { skills: Array<CatalogEntry | Record<string, unknown>> }

function wrangler(args: readonly string[], input?: string): string {
  const call = ["wrangler", ...args];
  return execFileSync("npx", call, {
    cwd: WORKER_REPO, encoding: "utf8", timeout: 180_000, maxBuffer: 256 * 1024 * 1024,
    input, stdio: ["pipe", "pipe", "pipe"],
  });
}

/**
 * READ THE CATALOGUE, and say whether it was actually read.
 *
 * A catalogue that cannot be read is an ABSENT catalogue and never an empty
 * one ⟨CLAUDE.md §10: a status is only as true as the artifact it implies⟩.
 * Returning `{skills:[]}` on a wrangler timeout and then WRITING that back
 * would delete every skill already published, and every step would report
 * success. So the reading carries `read`, and the write below refuses without
 * it unless the caller says in words that it means to start a new catalogue.
 */
export function readCatalog(): { catalog: Catalog; read: boolean; why?: string } {
  try {
    const raw = wrangler(["kv", "key", "get", "--namespace-id", KV_NAMESPACE_ID, "index.json", "--remote"]);
    const parsed = JSON.parse(raw) as Catalog;
    if (!Array.isArray(parsed?.skills)) return { catalog: { skills: [] }, read: false, why: "index.json holds no skills array" };
    return { catalog: parsed, read: true };
  } catch (error) {
    // WHY IT COULD NOT BE READ, carried out. A refusal that says only "could
    // not be read" makes a transient wrangler timeout look like an empty store.
    return { catalog: { skills: [] }, read: false, why: error instanceof Error ? error.message.split("\n")[0] : String(error) };
  }
}

/** One KV write per call, for the two singleton documents. */
function kvPut(key: string, value: string): void {
  const dir = mkdtempSync(join(tmpdir(), "snappy-kv-"));
  const path = join(dir, "value");
  try {
    writeFileSync(path, value);
    wrangler(["kv", "key", "put", "--namespace-id", KV_NAMESPACE_ID, key, "--path", path, "--remote"]);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

/** A whole skill in ONE call. */
function kvBulkPut(pairs: ReadonlyArray<{ key: string; value: string }>): void {
  if (pairs.length === 0) return;
  const dir = mkdtempSync(join(tmpdir(), "snappy-kv-bulk-"));
  const path = join(dir, "pairs.json");
  try {
    writeFileSync(path, JSON.stringify(pairs));
    wrangler(["kv", "bulk", "put", path, "--namespace-id", KV_NAMESPACE_ID, "--remote"]);
  } finally {
    rmSync(dir, { recursive: true, force: true });
  }
}

export interface GateReading { ok: boolean; output: string }

/** THE RELEASE GATE, run before a byte moves. */
export function runBaseSetGate(): GateReading {
  try {
    const output = execFileSync("node", [join(REPO_ROOT, "scripts/gates/base-set.mjs"), "--all"], {
      cwd: REPO_ROOT, encoding: "utf8", timeout: 300_000, maxBuffer: 64 * 1024 * 1024,
    });
    return { ok: true, output };
  } catch (error) {
    const failed = error as { stdout?: string; stderr?: string; message?: string };
    return { ok: false, output: `${failed.stdout ?? ""}${failed.stderr ?? failed.message ?? ""}` };
  }
}

/**
 * THE BASE SET, as the gate defines it: every skill folder in this repo that is
 * a skill, minus the folders the gate keeps private. No list of names here.
 */
export async function baseSetSkills(): Promise<string[]> {
  const { personalSkills } = await import("../../scripts/gates/personal-tier.mjs") as {
    personalSkills: (root: string) => Set<string>;
  };
  const personal = personalSkills(REPO_ROOT);
  return readdirSync(SKILLS_ROOT, { withFileTypes: true })
    .filter((entry) => entry.isDirectory() && entry.name.startsWith("snappy-"))
    .map((entry) => entry.name)
    .filter((name) => !personal.has(name) && existsSync(join(SKILLS_ROOT, name, "SKILL.md")))
    .sort();
}

/** The first line of a skill's description, for the catalogue's own field. The
 *  card carries the parsed purpose; this stays because every reader written
 *  before the card reads `description`. */
function descriptionOf(card: SkillCard, skillMd: string): string {
  const front = /description:\s*>?\s*\n?\s*([\s\S]+?)(?:\n---|\n[a-z_]+:)/u.exec(skillMd);
  const said = front === null ? card.purpose : front[1].trim().replace(/\n\s+/gu, " ");
  return said.slice(0, 500);
}

function bumpPatch(previous: string): string {
  const parts = previous.split(".").map(Number);
  if (parts.length !== 3 || parts.some((part) => !Number.isFinite(part))) return "1.0.0";
  parts[2] += 1;
  return parts.join(".");
}

export interface PublishRow {
  skill: string;
  tier: string;
  version: string;
  /** `published` — bytes moved · `unchanged` — checksum matched, nothing moved. */
  state: "published" | "unchanged";
  files: number;
  checks: string;
  coverage: string | null;
}

export interface PublishReport {
  gate: GateReading;
  rows: PublishRow[];
  published: number;
  unchanged: number;
  catalog_size: number;
  dry_run: boolean;
}

/**
 * PUBLISH. Idempotent by checksum: a skill whose bundle hashes to what the
 * catalogue already holds is not uploaded, and its version does not move.
 */
export async function publishSkills(
  names: readonly string[],
  options: { dryRun?: boolean; force?: boolean; newCatalog?: boolean } = {},
): Promise<PublishReport> {
  const gate = runBaseSetGate();
  if (!gate.ok) {
    throw new Error(`the base set carries his data — nothing was published.\n${gate.output.trim()}`);
  }

  const { contractOpenApi } = await import("../snappy-settings/contract-openapi.ts");
  const { loadContract } = await import("../snappy-tool-design/api.ts");

  const sources = await readCardSources(SKILLS_ROOT);
  const reading = readCatalog();
  if (!reading.read && options.newCatalog !== true) {
    throw new Error(
      `index.json could not be read from KV (${reading.why ?? "no reason given"}) — refusing to publish, because writing a catalogue built on an unread one deletes every skill already there. Retry, or pass --new-catalog if the store really is empty.`,
    );
  }
  const held = new Map(reading.catalog.skills.map((entry) => [String((entry as CatalogEntry).name), entry as CatalogEntry]));

  const rows: PublishRow[] = [];
  for (const skill of names) {
    const dir = join(SKILLS_ROOT, skill);
    if (!existsSync(join(dir, "SKILL.md"))) {
      throw new Error(`${skill}: no SKILL.md — every published skill has one`);
    }
    const previous = held.get(skill);
    const tier = gatewayTier(originTier(dir));
    if (tier === "personal") throw new Error(`${skill}: tier personal is never published`);

    let openapi = null;
    try {
      openapi = contractOpenApi(await loadContract(skill) as never);
    } catch {
      // A skill with no HAND_CONTRACT is instructions, not a hand. Its card
      // says so by carrying no OpenAPI document rather than by refusing.
    }
    const card = buildCard(SKILLS_ROOT, skill, sources, { tier, openapi });

    const unchanged = !options.force && previous?.checksum === card.checksum;
    const version = unchanged
      ? previous.version
      : previous === undefined ? "1.0.0" : bumpPatch(previous.version);

    const row: PublishRow = {
      skill, tier, version, state: unchanged ? "unchanged" : "published",
      files: card.files.length, checks: card.checks.line, coverage: card.coverage,
    };
    rows.push(row);
    if (unchanged) continue;

    const updatedAt = new Date().toISOString();
    const meta = {
      name: skill, version, checksum: card.checksum, updated_at: updatedAt, tier,
      file_count: card.files.length, total_size: card.total_size,
      files: card.files.map((file) => ({ name: file })),
    };
    const pairs = [
      ...card.files.map((file) => ({ key: `${skill}/${file}`, value: readFileSync(join(dir, file), "utf8") })),
      { key: `${skill}/_meta.json`, value: JSON.stringify(meta, null, 2) },
      { key: `${skill}/card.json`, value: JSON.stringify(card, null, 2) },
    ];
    if (!options.dryRun) kvBulkPut(pairs);

    const entry: CatalogEntry = {
      name: skill,
      description: descriptionOf(card, readFileSync(join(dir, "SKILL.md"), "utf8")),
      tier, install_method: "files", version, checksum: card.checksum, updated_at: updatedAt,
      total_size: card.total_size, files: card.files, card: indexCard(card, GATEWAY),
    };
    held.set(skill, entry);
  }

  // THE CATALOGUE IS WRITTEN ONCE. Ninety-two read-modify-writes of one
  // document is ninety-two chances to lose the write before it.
  const wrote = [...held.values()].sort((a, b) => String(a.name).localeCompare(String(b.name)));
  const moved = rows.filter((row) => row.state === "published").length;
  if (moved > 0 && !options.dryRun) kvPut("index.json", JSON.stringify({ skills: wrote }, null, 2));

  return {
    gate, rows, published: moved, unchanged: rows.length - moved,
    catalog_size: wrote.length, dry_run: options.dryRun === true,
  };
}

/**
 * PULL — Add it, from the store into a person's own skills root.
 *
 * WHERE IT LANDS. `~/.snappy-skills/skills-root` is a document holding one
 * absolute path, and the runner is its one reader and one writer
 * (`snappy-runner/src/skills-root.ts`). This READS it and never writes it: a
 * publisher that could re-point somebody's collection is a publisher that can
 * make their hands disappear. `--root` overrides it, which is how a test — and
 * this lane's own proof — installs into a scratch directory instead.
 *
 * It fetches over HTTPS from the gateway, exactly the way a stranger's install
 * does, rather than copying from this checkout. A pull that read the local
 * repo would prove nothing about whether the skill was actually published.
 */
export async function pullSkill(
  name: string,
  options: { root?: string; key?: string } = {},
): Promise<{ skill: string; root: string; files: string[]; card: boolean }> {
  const root = options.root ?? personSkillsRoot();
  const headers: Record<string, string> = options.key ? { Authorization: `Bearer ${options.key}` } : {};

  const catalogAnswer = await fetch(`${GATEWAY}/.well-known/skills/index.json`, { headers });
  if (!catalogAnswer.ok) throw new Error(`the store did not answer: HTTP ${catalogAnswer.status}`);
  const catalog = await catalogAnswer.json() as Catalog;
  const entry = catalog.skills.find((one) => String((one as CatalogEntry).name) === name) as CatalogEntry | undefined;
  if (entry === undefined) {
    const offered = catalog.skills.map((one) => String((one as CatalogEntry).name)).sort();
    throw new Error(`${name} is not in the store; it offers ${offered.length ? offered.join(", ") : "nothing"}`);
  }

  const into = join(root, name);
  const written: string[] = [];
  for (const file of entry.files ?? []) {
    const answer = await fetch(`${GATEWAY}/.well-known/skills/${name}/${file}`, { headers });
    if (!answer.ok) throw new Error(`${name}/${file}: HTTP ${answer.status}`);
    const target = join(into, file);
    mkdirSync(dirname(target), { recursive: true });
    writeFileSync(target, await answer.text());
    written.push(file);
  }

  // The card comes down with the skill so the bar can draw what it installed
  // without asking the network again. Best effort: a skill published before
  // cards existed still installs.
  let card = false;
  const cardAnswer = await fetch(`${GATEWAY}/.well-known/skills/${name}/card.json`, { headers });
  if (cardAnswer.ok) {
    writeFileSync(join(into, "card.json"), await cardAnswer.text());
    card = true;
  }
  return { skill: name, root, files: written, card };
}

/** The person's own skills root, as the runner records it. Read-only. */
export function personSkillsRoot(): string {
  const override = process.env.SNAPPY_SKILLS_ROOT;
  if (override !== undefined && override !== "") return override;
  const home = process.env.SNAPPY_SKILLS_HOME ?? join(homedir(), ".snappy-skills");
  const document = join(home, "skills-root");
  if (existsSync(document)) {
    const said = readFileSync(document, "utf8").trim();
    if (said !== "") return said;
  }
  throw new Error(
    `no skills root is set — ${document} does not name one. Point the bar's first-run pane at a folder, or pass --root <dir>.`,
  );
}

# Publishing Skills

## Table of Contents
- [Publish Script](#publish-script)
- [Skill Structure](#skill-structure)
- [Tier Selection](#tier-selection)
- [Publishing Examples](#publishing-examples)
- [Updating a Skill](#updating-a-skill)
- [Removing a Skill](#removing-a-skill)
- [Viewing the Catalog](#viewing-the-catalog)

---

## Publish Script

Location: `~/Projects/snappy-skills/scripts/publish-skill.js`

```bash
cd ~/Projects/snappy-skills
node scripts/publish-skill.js <skill-name> <local-path> [tier]
```

The script:
1. Reads all files in `<local-path>` recursively
2. Uploads each file to KV with key `<skill-name>/<filename>`
3. Parses `SKILL.md` frontmatter for the description
4. Updates `index.json` in KV (upserts the skill entry)
5. Excludes `config.env` and dotfiles from the public file list

---

## Skill Structure

A publishable skill folder should have:

```
~/.claude/skills/my-skill/
├── SKILL.md          # Required -- main file with frontmatter
├── config.env        # Optional -- excluded from public listing
├── resource1.md      # Optional -- additional docs
├── resource2.md      # Optional -- more docs
└── subfolder/        # Optional -- nested files supported
    └── deep-doc.md
```

The `SKILL.md` frontmatter is parsed for the description:
```yaml
---
name: my-skill
description: >
  This text becomes the catalog description (first 200 chars).
---
```

---

## Tier Selection

| Tier | Who sees it | When to use |
|------|-------------|-------------|
| `public` | Everyone (no key needed) | Free community skills |
| `client` | Only keys with this skill in their `skills` array | Custom skills for a specific client |
| `subscriber` | All subscriber and personal keys | Paid library content |
| `personal` | Master key only | Robert's private skills |

---

## Publishing Examples

### Public skill (free for everyone)
```bash
node scripts/publish-skill.js snappy-docs ~/.claude/skills/snappy-docs public
```

### Client-only skill
```bash
node scripts/publish-skill.js acme-workflows ~/.claude/skills/acme-workflows client
```
Then create a key for the client (see [key-management.md](key-management.md)):
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  "https://skills.snappy.ai/admin/keys/create?name=Acme%20Corp&tier=client&skills=acme-workflows"
```

### Subscriber skill (paid tier)
```bash
node scripts/publish-skill.js advanced-prompting ~/.claude/skills/advanced-prompting subscriber
```

### Personal skill (Robert only)
```bash
node scripts/publish-skill.js my-secret-sauce ~/.claude/skills/my-secret-sauce personal
```

---

## Updating a Skill

Re-run the same publish command. The script upserts -- if the skill name already exists in `index.json`, it updates the entry:

```bash
# Edit files locally, then re-publish
node scripts/publish-skill.js snappy-docs ~/.claude/skills/snappy-docs public
```

---

## Removing a Skill

There's no delete script yet. To remove a skill manually:

### 1. Delete skill files from KV
```bash
# List keys for the skill
wrangler kv key list --namespace-id "a090cf5f476946c28ee0e9059865bc37" --remote \
  | jq -r '.[].name' | grep "^skill-name/"

# Delete each key
wrangler kv key delete --namespace-id "a090cf5f476946c28ee0e9059865bc37" \
  "skill-name/SKILL.md" --remote
wrangler kv key delete --namespace-id "a090cf5f476946c28ee0e9059865bc37" \
  "skill-name/other-file.md" --remote
```

### 2. Update index.json
```bash
# Download current index
wrangler kv key get --namespace-id "a090cf5f476946c28ee0e9059865bc37" \
  "index.json" --remote > /tmp/index.json

# Edit /tmp/index.json -- remove the skill entry from the "skills" array

# Re-upload
wrangler kv key put --namespace-id "a090cf5f476946c28ee0e9059865bc37" \
  "index.json" --path /tmp/index.json --remote
```

---

## Viewing the Catalog

### Public view (what unauthenticated users see)
```bash
curl -s https://skills.snappy.ai/.well-known/skills/index.json | jq .
```

### Full view (master key -- sees everything including tier info)
```bash
curl -s -H "Authorization: Bearer $SNAPPY_MASTER_KEY" \
  https://skills.snappy.ai/.well-known/skills/index.json | jq .
```

### Fetch a specific skill file
```bash
curl -s https://skills.snappy.ai/.well-known/skills/snappy-docs/SKILL.md
```

### Test as a specific client
```bash
curl -s -H "Authorization: Bearer snappy_clientkey123" \
  https://skills.snappy.ai/.well-known/skills/index.json | jq .
```