fix: preserve folder upload mode across refresh (#551 ) (thanks @MunemHashmi)

fix(ui): persist folder upload input across hydration and re-renders (#58 )
Replace the useEffect + useRef approach for setting webkitdirectory/ directory attributes with a ref callback that sets the attributes every time the input element is mounted. This ensures folder selection mode persists after page refresh, where React hydration could strip the non-standard attributes. Also removes the @ts-expect-error JSX props since the attributes are now set imperatively via the ref callback.
2026-08-14 08:52:21 +00:00 · 2026-03-07 18:32:58 +00:00 · 2026-03-07 18:31:42 +00:00 · 2026-03-07 18:29:01 +00:00 · 2026-03-07 15:38:01 +00:00 · 2026-03-07 15:38:01 +00:00
221 changed files with 21539 additions and 4444 deletions
@@ -0,0 +1,35 @@
+name: "Security Gate: Secret Scanning"
+
+on:
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  trufflehog:
+    name: Scan for Verified Secrets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # Required to scan the code in the PR
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # necessary to support the scoping requirements below
+
+      - name: TruffleHog OSS
+        id: trufflehog
+        # Use a concrete released ref that resolves in upstream action registry.
+        # v3 (major tag) is not published by trufflesecurity/trufflehog.
+        uses: trufflesecurity/trufflehog@v3.93.6
+        with:
+          path: ./
+          base: ${{ github.event.pull_request.base.sha }} # scope it to the committed files
+          head: ${{ github.event.pull_request.head.sha }}
+          extra_args: --only-verified --debug
+
+      - name: Notify on Failure
+        if: steps.trufflehog.outcome == 'failure'
+        run: |
+          echo "::error::Verified secrets found! This PR contains live credentials that must be rotated immediately."
+          echo "::notice::If these secrets are already in the commit history, they cannot be removed via a simple removal commit/push. A repository owner can contact GitHub Support to purge the cached data: https://support.github.com/contact/private-information"
+          exit 1
@@ -0,0 +1,20 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "experimentalSortImports": {
+    "newlinesBetween": false,
+  },
+  "experimentalSortPackageJson": {
+    "sortScripts": true,
+  },
+  "ignorePatterns": [
+    ".output/",
+    ".tanstack/",
+    "convex/_generated/",
+    "coverage/",
+    "dist/",
+    "node_modules/",
+    "public/",
+    "src/routeTree.gen.ts",
+    "test-results/",
+  ],
+}
@@ -1,3 +1,37 @@
 {
-  "ignorePatterns": ["node_modules", "dist", "coverage", "convex/_generated", ".tanstack", "public"]
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["unicorn", "typescript", "oxc"],
+  "categories": {
+    "correctness": "error",
+    "perf": "error",
+    "suspicious": "error"
+  },
+  "rules": {
+    "curly": "off",
+    "eslint-plugin-unicorn/prefer-array-find": "off",
+    "eslint-plugin-unicorn/no-array-sort": "off",
+    "eslint/no-await-in-loop": "off",
+    "eslint/no-new": "off",
+    "oxc/no-accumulating-spread": "off",
+    "oxc/no-async-endpoint-handlers": "off",
+    "oxc/no-map-spread": "off",
+    "typescript/no-explicit-any": "error",
+    "typescript/no-extraneous-class": "off",
+    "typescript/no-unnecessary-boolean-literal-compare": "off",
+    "typescript/no-unnecessary-type-assertion": "off",
+    "typescript/no-unsafe-type-assertion": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "unicorn/require-post-message-target-origin": "off"
+  },
+  "ignorePatterns": [
+    ".output/",
+    ".tanstack/",
+    "convex/_generated/",
+    "coverage/",
+    "dist/",
+    "node_modules/",
+    "public/",
+    "src/routeTree.gen.ts",
+    "test-results/"
+  ]
 }
@@ -33,6 +33,10 @@
 - Commit messages: Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`…).
 - Keep changes scoped; avoid repo-wide search/replace.
 - PRs: include summary + test commands run. Add screenshots for UI changes.
+- Reject PRs that add skills into source code/repo content directly (for example under `skills/` or seed-only additions intended as published skills). Skills must be uploaded/published via CLI.
+
+## Git Notes
+- If `git branch -d/-D <branch>` is policy-blocked, delete the local ref directly: `git update-ref -d refs/heads/<branch>`.

 ## Configuration & Security
 - Local env: `.env.local` (never commit secrets).
@@ -1,5 +1,66 @@
 # Changelog

+## Unreleased
+
+### Added
+- Moderation: add comment reporting with per-user active report caps, unique reporter/target enforcement, and auto-hide on the 4th unique report.
+- Moderation: add AI-driven comment scam backfill (`commentModeration:*`) with persisted verdict/confidence/explainer metadata and strict auto-ban for `certain_scam` + `high` confidence.
+- Admin: add manual unban for banned users (clears `deletedAt` + `banReason`, audit log entry). Revoked API tokens stay revoked.
+- Admin: bulk restore skills from GitHub backup; reclaim squatted slugs via v1 endpoints + internal tooling (#298) (thanks @autogame-17).
+- Users: add `trustedPublisher` flag and admin mutations to bypass pending-scan auto-hide for trusted publishers (#298) (thanks @autogame-17).
+- Skills/Web: show skill owner avatar + handle on skill cards, lists, and detail pages (#312) (thanks @ianalloway).
+- Skills/Web: add file viewer for skill version files on detail page (#44) (thanks @regenrek).
+- CLI: add `uninstall` command for skills (#241) (thanks @superlowburn).
+- CI/Security: add TruffleHog pull-request scanning for verified leaked credentials (#505) (thanks @akses0).
+
+### Changed
+- Security/docs: document comment reporting/auto-hide behavior alongside existing skill reporting rules.
+- Security/moderation: add bounded explainable auto-ban reasons for scam comments and protect moderator/admin accounts from automated bans.
+- Moderation: banning users now also soft-deletes their authored comments (skill + soul), including legacy cleanup on re-ban.
+- Skill metadata: support env vars, dependency declarations, author, and links in parsed manifest metadata + install UI (#360) (thanks @mahsumaktas).
+- Quality gate: language-aware word counting (`Intl.Segmenter`) and new `cjkChars` signal to reduce false rejects for non-Latin docs.
+- Jobs: run skill stat event processing every 5 minutes (was 15).
+- API performance: batch resolve skill/soul tags in v1 list/get endpoints (fewer action->query round-trips) (#112) (thanks @mkrokosz).
+- Skills: reserve deleted slugs for prior owners (90-day cooldown) to prevent squatting; add admin reclaim flow (#298) (thanks @autogame-17).
+- Moderation: ban flow soft-deletes owned skills (reversible) and removes them from vector search (#298) (thanks @autogame-17).
+- LLM helpers: centralize OpenAI Responses text extraction for changelog/summary/eval flows (#502) (thanks @ianalloway).
+- Rate limiting: apply authenticated quotas by user bucket (vs shared IP), emit delay-based reset headers, and improve CLI 429 guidance/retries (#412) (thanks @lc0rp).
+- Search/listing performance: cut embedding hydration and badge read bandwidth via `embeddingSkillMap` + denormalized skill badges; shift stat-doc sync to low-frequency cron (#441) (thanks @sethconvex).
+
+### Fixed
+- Upload: keep folder-picking enabled after page refresh by reapplying `webkitdirectory`/`directory` on the file input ref (#551) (thanks @MunemHashmi).
+- Skills hard-delete: delete `commentReports` rows during moderation cleanup to avoid orphaned report records.
+- Comments: hide entries authored by deleted/deactivated users in `comments:listBySkill`.
+- Admin API: `POST /api/v1/users/reclaim` now performs non-destructive root-slug owner transfer
+  (preserves existing skill versions/stats/metadata) and clears active slug reservations.
+- VirusTotal: use shared AV-engine fallback verdict mapping for pending/backfill flows and keep undetected-only results pending (#591) (thanks @Shuai-DaiDai).
+- CLI publish: use a longer multipart upload timeout and normalize abort rejections into proper Errors (#550) (thanks @MunemHashmi).
+- CLI: forward optional auth tokens for `search` and `explore` against authenticated registries (#608) (thanks @artdaal).
+- Skill metadata: parse top-level `requires.*`, `primaryEnv`, and homepage fallbacks for security review accuracy (#548) (thanks @MunemHashmi).
+- Users: sync handle on ensure when GitHub login changes (#293) (thanks @christianhpoe).
+- Users/Auth: throttle GitHub profile sync on login; also sync avatar when it changes (#312) (thanks @ianalloway).
+- Upload gate: fetch GitHub account age by immutable account ID (prevents username swaps) (#116) (thanks @mkrokosz).
+- VT fallback: activate only VT-pending hidden skills when scans are unavailable/stale; keep quality/scanner-blocked skills hidden (#300) (thanks @superlowburn).
+- API: return proper status codes for delete/undelete errors (#35) (thanks @sergical).
+- API: for owners, return clearer status/messages for hidden/soft-deleted skills instead of a generic 404.
+- Web: allow copying OpenClaw scan summary text (thanks @borisolver, #322).
+- HTTP/CORS: add preflight handler + include CORS headers on API/download errors; CLI: include auth token for owner-visible installs/updates (#146) (thanks @Grenghis-Khan).
+- CLI: clarify `logout` only removes the local token; token remains valid until revoked in the web UI (#166) (thanks @aronchick).
+- CLI: validate skill slugs used for filesystem operations (prevents path traversal) (#241) (thanks @superlowburn).
+- Skills: keep global sorting across pagination on `/skills` (thanks @CodeBBakGoSu, #98).
+- Skills: allow updating skill description/summary from frontmatter on subsequent publishes (#312) (thanks @ianalloway).
+- Skills/Web: prevent filtered pagination dead-ends and loading-state flicker on `/skills`; move highlighted browse filtering into server list query (#339) (thanks @Marvae).
+- Web: align `/skills` total count with public visibility and format header count (thanks @rknoche6, #76).
+- Skills/Web: centralize public visibility checks and keep `globalStats` skill counts in sync incrementally; remove duplicate `/skills` default-sort fallback and share browse test mocks (thanks @rknoche6, #76).
+- Moderation: clear stale `flagged.suspicious` flags when VirusTotal rescans improve to clean verdicts (#418) (thanks @Phineas1500).
+- CLI: respect `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` env vars for outbound registry requests, with troubleshooting docs (#363) (thanks @kerrypotter).
+- CLI: preserve registry base paths when composing API URLs for search/inspect/moderation commands (#486) (thanks @Liknox).
+- API tests: lock `Retry-After` behavior to relative-delay semantics for v1 search 429s (#421) (thanks @apoorvdarshan).
+- CLI tests: assert 5xx HTTP responses still perform retry attempts before surfacing final error (#457) (thanks @YonghaoZhao722).
+- GitHub import: improve storage/publish failure errors with actionable context; add regression tests for error formatting (#512) (thanks @vassiliylakhonin).
+- CLI: show manual URL guidance when automatic browser opening is unavailable; add regression tests for opener errors (#163) (thanks @aronchick).
+- API/CLI: expose skill security status in version inspect output, with schema wiring and CLI regression coverage (#362) (thanks @abutbul).
+
 ## 0.6.1 - 2026-02-13

 ### Added
@@ -12,8 +73,12 @@
 - Moderation UX: collapse OpenClaw analysis by default; update spacing and default reasoning model.

 ### Fixed
+- Skills: fix initial `/skills` sort wiring so first page respects selected sort/direction (thanks @bpk9, #92).
+- Search/UI: add embedding request timeout and align `/skills` toolbar + list width (thanks @GhadiSaab, #53).
 - Upload gate: handle GitHub API rate limits and optional authenticated lookup token (thanks @superlowburn, #246).
 - HTTP: remove `allowH2` from Undici agent to prevent `fetch failed` on Node.js 22+ (#245).
+- Tests: add root `undici` dev dependency for Node E2E imports (thanks @tanujbhaud, #255).
+- Downloads: add download rate limiting + per-IP/day dedupe + scheduled dedupe pruning; preserve moderation gating and deterministic zips (thanks @regenrek, #43).
 - VirusTotal: fix scan sync race conditions and retry behavior in scan/backfill paths.
 - Metadata: tolerate trailing commas in JSON metadata.
 - Auth: allow soft-deleted users to re-authenticate on fresh login, while keeping banned users blocked (thanks @tanujbhaud, #177).
@@ -0,0 +1,166 @@
+# Contributing to ClawHub
+
+Welcome! ClawHub is the public skill registry for [OpenClaw](https://github.com/openclaw/openclaw). We appreciate bug fixes, documentation improvements, and feature contributions.
+
+- **Questions?** Ask in [#clawhub on Discord](https://discord.gg/clawd).
+- **Bug fixes** — PRs are welcome.
+- **New features or architectural changes** — please start with a Discord conversation in #clawhub first so we can align on scope.
+
+## Local Development Setup
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) (Convex CLI runs via `bunx`, no global install needed)
+
+### Install and configure
+
+```bash
+bun install
+cp .env.local.example .env.local
+```
+
+Edit `.env.local` with the following values for **local Convex**:
+
+```bash
+# Frontend
+VITE_CONVEX_URL=http://127.0.0.1:3210
+VITE_CONVEX_SITE_URL=http://127.0.0.1:3210
+SITE_URL=http://localhost:3000
+CONVEX_SITE_URL=http://127.0.0.1:3210
+
+# Deployment used by `bunx convex dev`
+CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub
+```
+
+### GitHub OAuth App (for login)
+
+1. Go to [github.com/settings/developers](https://github.com/settings/developers) and create a new OAuth App.
+2. Set **Homepage URL** to `http://localhost:3000`.
+3. Set **Authorization callback URL** to `http://127.0.0.1:3210/api/auth/callback/github`.
+4. Copy the Client ID and generate a Client Secret, then add them to `.env.local`:
+
+```bash
+AUTH_GITHUB_ID=<your-client-id>
+AUTH_GITHUB_SECRET=<your-client-secret>
+```
+
+### JWT keys (for Convex Auth)
+
+Generate the signing keys:
+
+```bash
+bunx @convex-dev/auth
+```
+
+This outputs `JWT_PRIVATE_KEY` and `JWKS` values — paste them into `.env.local`.
+
+### Run the app
+
+```bash
+# Terminal A: local Convex backend
+bunx convex dev
+
+# Terminal B: frontend (port 3000)
+bun run dev
+```
+
+### Seed the database
+
+Populate sample data so the UI isn't empty:
+
+```bash
+# 3 sample skills (padel, gohome, xuezh)
+bunx convex run --no-push devSeed:seedNixSkills
+
+# 50 extra skills for pagination testing (optional)
+bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal
+```
+
+To reset and re-seed:
+
+```bash
+bunx convex run --no-push devSeed:seedNixSkills '{"reset": true}'
+```
+
+### Optional environment variables
+
+These features degrade gracefully without their keys:
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENAI_API_KEY` | Embeddings and vector search (falls back to zero vectors) |
+| `VT_API_KEY` | VirusTotal malware scanning |
+| `DISCORD_WEBHOOK_URL` | Discord notifications |
+| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub backup sync |
+
+## CLI Development
+
+The CLI source lives in [`packages/clawdhub/`](packages/clawdhub/). Both `clawhub` and `clawdhub` are registered as bin aliases.
+
+To test the CLI against your local instance:
+
+```bash
+CLAWHUB_REGISTRY=http://127.0.0.1:3210 CLAWHUB_SITE=http://localhost:3000 clawhub search "padel"
+```
+
+Manual smoke tests are documented in [`docs/manual-testing.md`](docs/manual-testing.md).
+
+## Skill & Soul Publishing
+
+- Skill format reference: [`docs/skill-format.md`](docs/skill-format.md)
+- Soul format reference: [`docs/soul-format.md`](docs/soul-format.md)
+- End-to-end walkthrough (search, install, publish, sync): [`docs/quickstart.md`](docs/quickstart.md)
+
+Quick publish:
+
+```bash
+clawhub publish <path-to-skill-directory>
+```
+
+## Before Submitting a PR
+
+```bash
+bun run lint       # oxlint
+bun run test       # Vitest (80% coverage threshold)
+bun run build      # Vite + Nitro
+```
+
+These are the same checks that run in CI (`.github/workflows/ci.yml`).
+
+**PR guidelines:**
+
+- Keep PRs focused — one concern per PR.
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:`, `docs:`, etc.
+- Include test commands and screenshots for UI changes.
+- Write a clear description of what changed and why.
+
+## AI-Generated Code
+
+AI-assisted contributions are welcome. When submitting AI-generated or AI-assisted code:
+
+- Note it in the PR description.
+- Describe the level of testing you applied.
+- Include prompts if useful for reviewers.
+- Confirm that you understand and can maintain the code.
+
+## Security Reporting
+
+Report vulnerabilities to **security@openclaw.ai** with:
+
+- Severity assessment
+- Technical reproduction steps
+- Suggested remediation
+
+See [`docs/security.md`](docs/security.md) for moderation and upload gating details.
+
+## Reading Order for New Contributors
+
+1. This file (local setup)
+2. [`docs/quickstart.md`](docs/quickstart.md) — end-to-end workflows
+3. [`docs/architecture.md`](docs/architecture.md) — system design
+4. [`docs/skill-format.md`](docs/skill-format.md) — skill structure
+5. [`docs/cli.md`](docs/cli.md) — CLI reference
+6. [`docs/http-api.md`](docs/http-api.md) — HTTP endpoints
+7. [`docs/auth.md`](docs/auth.md) — authentication
+8. [`docs/deploy.md`](docs/deploy.md) — deployment
+9. [`docs/troubleshooting.md`](docs/troubleshooting.md) — common issues
@@ -1,4 +1,8 @@
-# ClawHub
+<p align="center">
+  <img src="public/clawd-logo.png" alt="ClawHub" width="120">
+</p>
+
+<h1 align="center">ClawHub</h1>

 <p align="center">
  <a href="https://github.com/openclaw/clawhub/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/openclaw/clawhub/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
@@ -7,12 +11,18 @@
 </p>

 ClawHub is the **public skill registry for Clawdbot**: publish, version, and search text-based agent skills (a `SKILL.md` plus supporting files).
-It’s designed for fast browsing + a CLI-friendly API, with moderation hooks and vector search.
+It's designed for fast browsing + a CLI-friendly API, with moderation hooks and vector search.

 onlycrabs.ai is the **SOUL.md registry**: publish and share system lore the same way you publish skills.

-Live: `https://clawhub.ai`
-onlycrabs.ai: `https://onlycrabs.ai`
+<p align="center">
+  <a href="https://clawhub.ai">ClawHub</a> ·
+  <a href="https://onlycrabs.ai">onlycrabs.ai</a> ·
+  <a href="VISION.md">Vision</a> ·
+  <a href="docs/README.md">Docs</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="https://discord.gg/clawd">Discord</a>
+</p>

 ## What you can do with it

@@ -37,6 +47,25 @@ onlycrabs.ai: `https://onlycrabs.ai`
 - Search: OpenAI embeddings (`text-embedding-3-small`) + Convex vector search.
 - API schema + routes: `packages/schema` (`clawhub-schema`).

+## CLI
+
+Common CLI flows:
+
+- Auth: `clawhub login`, `clawhub whoami`
+- Discover: `clawhub search ...`, `clawhub explore`
+- Manage local installs: `clawhub install <slug>`, `clawhub uninstall <slug>`, `clawhub list`, `clawhub update --all`
+- Inspect without installing: `clawhub inspect <slug>`
+- Publish/sync: `clawhub publish <path>`, `clawhub sync`
+
+Docs: [`docs/quickstart.md`](docs/quickstart.md), [`docs/cli.md`](docs/cli.md).
+
+### Removal permissions
+
+- `clawhub uninstall <slug>` only removes a local install on your machine.
+- Uploaded registry skills use soft-delete/restore (`clawhub delete <slug>` / `clawhub undelete <slug>` or API equivalents).
+- Soft-delete/restore is allowed for the skill owner, moderators, and admins.
+- Hard delete is admin-only (management tools / ban flows).
+

 ## Telemetry

@@ -47,39 +76,36 @@ Disable via:
 export CLAWHUB_DISABLE_TELEMETRY=1
 ```

-Details: `docs/telemetry.md`.
+Details: [`docs/telemetry.md`](docs/telemetry.md).

 ## Repo layout

 - `src/` — TanStack Start app (routes, components, styles).
 - `convex/` — schema + queries/mutations/actions + HTTP API routes.
 - `packages/schema/` — shared API types/routes for the CLI and app.
- `docs/spec.md` — product + implementation spec (good first read).
+- [`docs/`](docs/README.md) — project documentation (architecture, CLI, auth, deployment, and more).
+- [`docs/spec.md`](docs/spec.md) — product + implementation spec (good first read).

 ## Local dev

-Prereqs: Bun + Convex CLI.
+Prereqs: [Bun](https://bun.sh/) (Convex runs via `bunx`, no global install needed).

 ```bash
 bun install
 cp .env.local.example .env.local
+# edit .env.local — see CONTRIBUTING.md for local Convex values

-# terminal A: web app
+# terminal A: local Convex backend
+bunx convex dev
+
+# terminal B: web app (port 3000)
 bun run dev

-# terminal B: Convex dev deployment
-bunx convex dev
+# seed sample data
+bunx convex run --no-push devSeed:seedNixSkills
 ```

-## Auth (GitHub OAuth) setup
-
-Create a GitHub OAuth App, set `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET`, then:
-
-```bash
-bunx auth --deployment-name <deployment> --web-server-url http://localhost:3000
-```
-
-This writes `JWT_PRIVATE_KEY` + `JWKS` to the deployment and prints values for your local `.env.local`.
+For full setup instructions (env vars, GitHub OAuth, JWT keys, database seeding), see [CONTRIBUTING.md](CONTRIBUTING.md).

 ## Environment

@@ -0,0 +1,94 @@
+## OpenClaw Vision
+
+OpenClaw is the AI that actually does things.
+It runs on your devices, in your channels, with your rules.
+
+This document explains the current state and direction of the project.
+We are still early, so iteration is fast.
+Project overview and developer docs: [`README.md`](README.md)
+
+OpenClaw started as my personal playground to learn AI and build something genuinely useful:
+an assistant that can run real tasks on my computer.
+It evolved through several names and shells: Warelay -> Clawdbot -> Moltbot -> OpenClaw.
+
+The goal? A personal assistant that's easy to use, supports a wide range of platforms, and respects your privacy and security.
+
+The current focus is:
+
+Priority:
+- Security and safe defaults
+- Bug fixes and stability
+- Setup reliability and first-run UX
+
+Next priorities:
+- Supporting all major model providers
+- Improving support for major messaging channels (and adding a few high-demand ones)
+- Performance and test infrastructure
+- Better computer-use and agent harness capabilities
+- Ergonomics across CLI and web frontend
+- Companion apps on macOS, iOS, Android, Windows, and Linux
+
+## Security
+
+Security in OpenClaw is a deliberate tradeoff: strong defaults without killing capability.
+The goal is to stay powerful for real work while making risky paths explicit and operator-controlled.
+
+Canonical security policy and reporting:
+- https://github.com/openclaw/openclaw/blob/main/SECURITY.md
+
+We prioritize secure defaults, but we also expose clear knobs for trusted high-power workflows.
+
+## Plugins & Memory
+
+OpenClaw has an extensive plugin API.
+Core stays lean; optional capability should usually ship as plugins.
+
+Preferred plugin path is npm package distribution plus local extension loading for development.
+If you build a plugin, please host and maintain it in your own repository.
+The bar for adding optional plugins to core is intentionally high.
+
+Memory is a special plugin slot where only one memory plugin can be active at a time.
+Today we ship multiple memory options; over time we plan to converge on one recommended default path.
+
+### Skills
+
+We still ship some bundled skills for baseline UX.
+New skills should be published to ClawHub first (`clawhub.ai`), not added to core by default.
+Core skill additions should be rare and require a strong product or security reason.
+
+### MCP Support
+
+OpenClaw supports MCP through `mcporter`: https://github.com/steipete/mcporter
+
+This keeps MCP integration flexible and decoupled from core runtime:
+- add or change MCP servers without restarting the gateway
+- keep core tool/context surface lean
+- reduce MCP churn impact on core stability and security
+
+For now, we prefer this bridge model over building first-class MCP runtime into core.
+If there is an MCP server or feature `mcporter` does not support yet, please open an issue there.
+
+### Setup
+
+OpenClaw is currently terminal-first by design.
+This keeps setup explicit: users see docs, auth, permissions, and security posture up front.
+
+Long term, we want easier onboarding flows as hardening matures.
+We do not want convenience wrappers that hide critical security decisions from users.
+
+### Why TypeScript?
+
+OpenClaw is primarily an orchestration system: prompts, tools, protocols, and integrations.
+TypeScript was chosen to keep OpenClaw hackable by default.
+It is widely known, fast to iterate in, and easy to read, modify, and extend.
+
+## What We Will Not Merge (For Now)
+
+- New core skills when they can live on ClawHub
+- Commercial service integrations that do not clearly fit the model-provider category
+- Wrapper channels around already supported channels without a clear capability or security gap
+- First-class MCP runtime in core when `mcporter` already provides the integration path
+- Heavy orchestration layers that duplicate existing agent and tool infrastructure
+
+This list is a roadmap guardrail, not a law of physics.
+Strong user demand and strong technical rationale can change it.
@@ -1,41 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
-  "files": {
-    "includes": [
-      "**",
-      "!**/.cta.json",
-      "!**/.vscode",
-      "!**/node_modules",
-      "!**/dist",
-      "!**/.output",
-      "!**/coverage",
-      "!**/convex/_generated",
-      "!**/test-results",
-      "!**/src/routeTree.gen.ts",
-      "!**/.tanstack",
-      "!**/public",
-      "!**/.devenv",
-      "!**/.devenv"
-    ]
-  },
-  "assist": { "actions": { "source": { "organizeImports": "on" } } },
-  "formatter": {
-    "enabled": true,
-    "indentStyle": "space",
-    "indentWidth": 2,
-    "lineWidth": 100
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true
-    }
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "single",
-      "semicolons": "asNeeded",
-      "trailingCommas": "all"
-    }
-  }
-}
@@ -24,7 +24,6 @@
        "clawhub-schema": "workspace:*",
        "clsx": "^2.1.1",
        "convex": "^1.31.7",
-        "convex-helpers": "^0.1.111",
        "fflate": "^0.8.2",
        "h3": "2.0.1-rc.11",
        "lucide-react": "^0.563.0",
@@ -41,7 +40,6 @@
        "yaml": "^2.8.2",
      },
      "devDependencies": {
-        "@biomejs/biome": "^2.3.13",
        "@playwright/test": "^1.58.1",
        "@tanstack/devtools-vite": "^0.5.0",
        "@testing-library/dom": "^10.4.1",
@@ -54,16 +52,18 @@
        "@vitest/coverage-v8": "^4.0.18",
        "jsdom": "^28.0.0",
        "only-allow": "^1.2.2",
+        "oxfmt": "0.32.0",
        "oxlint": "^1.42.0",
        "oxlint-tsgolint": "^0.11.4",
        "typescript": "^5.9.3",
+        "undici": "^7.19.2",
        "vite": "^7.3.1",
        "vitest": "^4.0.18",
      },
    },
    "packages/clawdhub": {
      "name": "clawhub",
-      "version": "0.5.0",
+      "version": "0.7.0",
      "bin": {
        "clawhub": "bin/clawdhub.js",
        "clawdhub": "bin/clawdhub.js",
@@ -158,24 +158,6 @@

    "@bcoe/v8-coverage": ["@bcoe/v8-coverage@1.0.2", "", {}, "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA=="],

-    "@biomejs/biome": ["@biomejs/biome@2.3.13", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.3.13", "@biomejs/cli-darwin-x64": "2.3.13", "@biomejs/cli-linux-arm64": "2.3.13", "@biomejs/cli-linux-arm64-musl": "2.3.13", "@biomejs/cli-linux-x64": "2.3.13", "@biomejs/cli-linux-x64-musl": "2.3.13", "@biomejs/cli-win32-arm64": "2.3.13", "@biomejs/cli-win32-x64": "2.3.13" }, "bin": { "biome": "bin/biome" } }, "sha512-Fw7UsV0UAtWIBIm0M7g5CRerpu1eKyKAXIazzxhbXYUyMkwNrkX/KLkGI7b+uVDQ5cLUMfOC9vR60q9IDYDstA=="],
-
-    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.3.13", "", { "os": "darwin", "cpu": "arm64" }, "sha512-0OCwP0/BoKzyJHnFdaTk/i7hIP9JHH9oJJq6hrSCPmJPo8JWcJhprK4gQlhFzrwdTBAW4Bjt/RmCf3ZZe59gwQ=="],
-
-    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.3.13", "", { "os": "darwin", "cpu": "x64" }, "sha512-AGr8OoemT/ejynbIu56qeil2+F2WLkIjn2d8jGK1JkchxnMUhYOfnqc9sVzcRxpG9Ycvw4weQ5sprRvtb7Yhcw=="],
-
-    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.3.13", "", { "os": "linux", "cpu": "arm64" }, "sha512-xvOiFkrDNu607MPMBUQ6huHmBG1PZLOrqhtK6pXJW3GjfVqJg0Z/qpTdhXfcqWdSZHcT+Nct2fOgewZvytESkw=="],
-
-    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.3.13", "", { "os": "linux", "cpu": "arm64" }, "sha512-TUdDCSY+Eo/EHjhJz7P2GnWwfqet+lFxBZzGHldrvULr59AgahamLs/N85SC4+bdF86EhqDuuw9rYLvLFWWlXA=="],
-
-    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.3.13", "", { "os": "linux", "cpu": "x64" }, "sha512-s+YsZlgiXNq8XkgHs6xdvKDFOj/bwTEevqEY6rC2I3cBHbxXYU1LOZstH3Ffw9hE5tE1sqT7U23C00MzkXztMw=="],
-
-    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.3.13", "", { "os": "linux", "cpu": "x64" }, "sha512-0bdwFVSbbM//Sds6OjtnmQGp4eUjOTt6kHvR/1P0ieR9GcTUAlPNvPC3DiavTqq302W34Ae2T6u5VVNGuQtGlQ=="],
-
-    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.3.13", "", { "os": "win32", "cpu": "arm64" }, "sha512-QweDxY89fq0VvrxME+wS/BXKmqMrOTZlN9SqQ79kQSIc3FrEwvW/PvUegQF6XIVaekncDykB5dzPqjbwSKs9DA=="],
-
-    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.3.13", "", { "os": "win32", "cpu": "x64" }, "sha512-trDw2ogdM2lyav9WFQsdsfdVy1dvZALymRpgmWsvSez0BJzBjulhOT/t+wyKeh3pZWvwP3VMs1SoOKwO3wecMQ=="],
-
    "@clack/core": ["@clack/core@0.5.0", "", { "dependencies": { "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-p3y0FIOwaYRUPRcMO7+dlmLh8PSRcrjuTndsiA0WAFbWES0mLZlrjVoBRZ9DzkPFJZG6KGkJmoEAY0ZcVWTkow=="],

    "@clack/prompts": ["@clack/prompts@0.11.0", "", { "dependencies": { "@clack/core": "0.5.0", "picocolors": "^1.0.0", "sisteransi": "^1.0.5" } }, "sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw=="],
@@ -380,6 +362,44 @@

    "@oxc-transform/binding-win32-x64-msvc": ["@oxc-transform/binding-win32-x64-msvc@0.110.0", "", { "os": "win32", "cpu": "x64" }, "sha512-QROrowwlrApI1fEScMknGWKM6GTM/Z2xwMnDqvSaEmzNazBsDUlE08Jasw610hFEsYAVU2K5sp/YaCa9ORdP4A=="],

+    "@oxfmt/binding-android-arm-eabi": ["@oxfmt/binding-android-arm-eabi@0.32.0", "", { "os": "android", "cpu": "arm" }, "sha512-DpVyuVzgLH6/MvuB/YD3vXO9CN/o9EdRpA0zXwe/tagP6yfVSFkFWkPqTROdqp0mlzLH5Yl+/m+hOrcM601EbA=="],
+
+    "@oxfmt/binding-android-arm64": ["@oxfmt/binding-android-arm64@0.32.0", "", { "os": "android", "cpu": "arm64" }, "sha512-w1cmNXf9zs0vKLuNgyUF3hZ9VUAS1hBmQGndYJv1OmcVqStBtRTRNxSWkWM0TMkrA9UbvIvM9gfN+ib4Wy6lkQ=="],
+
+    "@oxfmt/binding-darwin-arm64": ["@oxfmt/binding-darwin-arm64@0.32.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-m6wQojz/hn94XdZugFPtdFbOvXbOSYEqPsR2gyLyID3BvcrC2QsJyT1o3gb4BZEGtZrG1NiKVGwDRLM0dHd2mg=="],
+
+    "@oxfmt/binding-darwin-x64": ["@oxfmt/binding-darwin-x64@0.32.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-hN966Uh6r3Erkg2MvRcrJWaB6QpBzP15rxWK/QtkUyD47eItJLsAQ2Hrm88zMIpFZ3COXZLuN3hqgSlUtvB0Xw=="],
+
+    "@oxfmt/binding-freebsd-x64": ["@oxfmt/binding-freebsd-x64@0.32.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-g5UZPGt8tJj263OfSiDGdS54HPa0KgFfspLVAUivVSdoOgsk6DkwVS9nO16xQTDztzBPGxTvrby8WuufF0g86Q=="],
+
+    "@oxfmt/binding-linux-arm-gnueabihf": ["@oxfmt/binding-linux-arm-gnueabihf@0.32.0", "", { "os": "linux", "cpu": "arm" }, "sha512-F4ZY83/PVQo9ZJhtzoMqbmjqEyTVEZjbaw4x1RhzdfUhddB41ZB2Vrt4eZi7b4a4TP85gjPRHgQBeO0c1jbtaw=="],
+
+    "@oxfmt/binding-linux-arm-musleabihf": ["@oxfmt/binding-linux-arm-musleabihf@0.32.0", "", { "os": "linux", "cpu": "arm" }, "sha512-olR37eG16Lzdj9OBSvuoT5RxzgM5xfQEHm1OEjB3M7Wm4KWa5TDWIT13Aiy74GvAN77Hq1+kUKcGVJ/0ynf75g=="],
+
+    "@oxfmt/binding-linux-arm64-gnu": ["@oxfmt/binding-linux-arm64-gnu@0.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-eZhk6AIjRCDeLoXYBhMW7qq/R1YyVi+tGnGfc3kp7AZQrMsFaWtP/bgdCJCTNXMpbMwymtVz0qhSQvR5w2sKcg=="],
+
+    "@oxfmt/binding-linux-arm64-musl": ["@oxfmt/binding-linux-arm64-musl@0.32.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-UYiqO9MlipntFbdbUKOIo84vuyzrK4TVIs7Etat91WNMFSW54F6OnHq08xa5ZM+K9+cyYMgQPXvYCopuP+LyKw=="],
+
+    "@oxfmt/binding-linux-ppc64-gnu": ["@oxfmt/binding-linux-ppc64-gnu@0.32.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-IDH/fxMv+HmKsMtsjEbXqhScCKDIYp38sgGEcn0QKeXMxrda67PPZA7HMfoUwEtFUG+jsO1XJxTrQsL+kQ90xQ=="],
+
+    "@oxfmt/binding-linux-riscv64-gnu": ["@oxfmt/binding-linux-riscv64-gnu@0.32.0", "", { "os": "linux", "cpu": "none" }, "sha512-bQFGPDa0buYWJFeK2I7ah8wRZjrAgamaG2OAGv+Ua5UMYEnHxmHcv+r8lWUUrwP2oqQGvp1SB8JIVtBbYuAueQ=="],
+
+    "@oxfmt/binding-linux-riscv64-musl": ["@oxfmt/binding-linux-riscv64-musl@0.32.0", "", { "os": "linux", "cpu": "none" }, "sha512-3vFp9DW1ItEKWltADzCFqG5N7rYFToT4ztlhg8wALoo2E2VhveLD88uAF4FF9AxD9NhgHDGmPCV+WZl/Qlj8cQ=="],
+
+    "@oxfmt/binding-linux-s390x-gnu": ["@oxfmt/binding-linux-s390x-gnu@0.32.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-Fub2y8S9ImuPzAzpbgkoz/EVTWFFBolxFZYCMRhRZc8cJZI2gl/NlZswqhvJd/U0Jopnwgm/OJ2x128vVzFFWA=="],
+
+    "@oxfmt/binding-linux-x64-gnu": ["@oxfmt/binding-linux-x64-gnu@0.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-XufwsnV3BF81zO2ofZvhT4FFaMmLTzZEZnC9HpFz/quPeg9C948+kbLlZnsfjmp+1dUxKMCpfmRMqOfF4AOLsA=="],
+
+    "@oxfmt/binding-linux-x64-musl": ["@oxfmt/binding-linux-x64-musl@0.32.0", "", { "os": "linux", "cpu": "x64" }, "sha512-u2f9tC2qYfikKmA2uGpnEJgManwmk0ZXWs5BB4ga4KDu2JNLdA3i634DGHeMLK9wY9+iRf3t7IYpgN3OVFrvDw=="],
+
+    "@oxfmt/binding-openharmony-arm64": ["@oxfmt/binding-openharmony-arm64@0.32.0", "", { "os": "none", "cpu": "arm64" }, "sha512-5ZXb1wrdbZ1YFXuNXNUCePLlmLDy4sUt4evvzD4Cgumbup5wJgS9PIe5BOaLywUg9f1wTH6lwltj3oT7dFpIGA=="],
+
+    "@oxfmt/binding-win32-arm64-msvc": ["@oxfmt/binding-win32-arm64-msvc@0.32.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-IGSMm/Agq+IA0++aeAV/AGPfjcBdjrsajB5YpM3j7cMcwoYgUTi/k2YwAmsHH3ueZUE98pSM/Ise2J7HtyRjOA=="],
+
+    "@oxfmt/binding-win32-ia32-msvc": ["@oxfmt/binding-win32-ia32-msvc@0.32.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-H/9gsuqXmceWMsVoCPZhtJG2jLbnBeKr7xAXm2zuKpxLVF7/2n0eh7ocOLB6t+L1ARE76iORuUsRMnuGjj8FjQ=="],
+
+    "@oxfmt/binding-win32-x64-msvc": ["@oxfmt/binding-win32-x64-msvc@0.32.0", "", { "os": "win32", "cpu": "x64" }, "sha512-fF8VIOeligq+mA6KfKvWtFRXbf0EFy73TdR6ZnNejdJRM8VWN1e3QFhYgIwD7O8jBrQsd7EJbUpkAr/YlUOokg=="],
+
    "@oxlint-tsgolint/darwin-arm64": ["@oxlint-tsgolint/darwin-arm64@0.11.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-IhdhiC183s5wdFDZSQC8PaFFq1QROiVT5ahz7ysgEKVnkNDjy82ieM7ZKiUfm2ncXNX2RcFGSSZrQO6plR+VAQ=="],

    "@oxlint-tsgolint/darwin-x64": ["@oxlint-tsgolint/darwin-x64@0.11.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-KJmBg10Z1uGpJqxDzETXOytYyeVrKUepo8rCXeVkRlZ2QzZqMElgalFN4BI3ccgIPkQpzzu4SVzWNFz7yiKavQ=="],
@@ -770,8 +790,6 @@

    "convex": ["convex@1.31.7", "", { "dependencies": { "esbuild": "0.27.0", "prettier": "^3.0.0" }, "peerDependencies": { "@auth0/auth0-react": "^2.0.1", "@clerk/clerk-react": "^4.12.8 || ^5.0.0", "react": "^18.0.0 || ^19.0.0-0 || ^19.0.0" }, "optionalPeers": ["@auth0/auth0-react", "@clerk/clerk-react", "react"], "bin": { "convex": "bin/main.js" } }, "sha512-PtNMe1mAIOvA8Yz100QTOaIdgt2rIuWqencVXrb4McdhxBHZ8IJ1eXTnrgCC9HydyilGT1pOn+KNqT14mqn9fQ=="],

-    "convex-helpers": ["convex-helpers@0.1.111", "", { "peerDependencies": { "@standard-schema/spec": "^1.0.0", "convex": "^1.25.4", "hono": "^4.0.5", "react": "^17.0.2 || ^18.0.0 || ^19.0.0", "typescript": "^5.5", "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["@standard-schema/spec", "hono", "react", "typescript", "zod"], "bin": { "convex-helpers": "bin.cjs" } }, "sha512-0O59Ohi8HVc3+KULxSC6JHsw8cQJyc8gZ7OAfNRVX7T5Wy6LhPx3l8veYN9avKg7UiPlO7m1eBiQMHKclIyXyQ=="],
-
    "cookie": ["cookie@1.1.1", "", {}, "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ=="],

    "cookie-es": ["cookie-es@2.0.0", "", {}, "sha512-RAj4E421UYRgqokKUmotqAwuplYw15qtdXfY+hGzgCJ/MBjCVZcSoHK/kH9kocfjRjcDME7IiDWR/1WX1TM2Pg=="],
@@ -1124,6 +1142,8 @@

    "oxc-transform": ["oxc-transform@0.110.0", "", { "optionalDependencies": { "@oxc-transform/binding-android-arm-eabi": "0.110.0", "@oxc-transform/binding-android-arm64": "0.110.0", "@oxc-transform/binding-darwin-arm64": "0.110.0", "@oxc-transform/binding-darwin-x64": "0.110.0", "@oxc-transform/binding-freebsd-x64": "0.110.0", "@oxc-transform/binding-linux-arm-gnueabihf": "0.110.0", "@oxc-transform/binding-linux-arm-musleabihf": "0.110.0", "@oxc-transform/binding-linux-arm64-gnu": "0.110.0", "@oxc-transform/binding-linux-arm64-musl": "0.110.0", "@oxc-transform/binding-linux-ppc64-gnu": "0.110.0", "@oxc-transform/binding-linux-riscv64-gnu": "0.110.0", "@oxc-transform/binding-linux-riscv64-musl": "0.110.0", "@oxc-transform/binding-linux-s390x-gnu": "0.110.0", "@oxc-transform/binding-linux-x64-gnu": "0.110.0", "@oxc-transform/binding-linux-x64-musl": "0.110.0", "@oxc-transform/binding-openharmony-arm64": "0.110.0", "@oxc-transform/binding-wasm32-wasi": "0.110.0", "@oxc-transform/binding-win32-arm64-msvc": "0.110.0", "@oxc-transform/binding-win32-ia32-msvc": "0.110.0", "@oxc-transform/binding-win32-x64-msvc": "0.110.0" } }, "sha512-/fymQNzzUoKZweH0nC5yvbI2eR0yWYusT9TEKDYVgOgYrf9Qmdez9lUFyvxKR9ycx+PTHi/reIOzqf3wkShQsw=="],

+    "oxfmt": ["oxfmt@0.32.0", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.32.0", "@oxfmt/binding-android-arm64": "0.32.0", "@oxfmt/binding-darwin-arm64": "0.32.0", "@oxfmt/binding-darwin-x64": "0.32.0", "@oxfmt/binding-freebsd-x64": "0.32.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.32.0", "@oxfmt/binding-linux-arm-musleabihf": "0.32.0", "@oxfmt/binding-linux-arm64-gnu": "0.32.0", "@oxfmt/binding-linux-arm64-musl": "0.32.0", "@oxfmt/binding-linux-ppc64-gnu": "0.32.0", "@oxfmt/binding-linux-riscv64-gnu": "0.32.0", "@oxfmt/binding-linux-riscv64-musl": "0.32.0", "@oxfmt/binding-linux-s390x-gnu": "0.32.0", "@oxfmt/binding-linux-x64-gnu": "0.32.0", "@oxfmt/binding-linux-x64-musl": "0.32.0", "@oxfmt/binding-openharmony-arm64": "0.32.0", "@oxfmt/binding-win32-arm64-msvc": "0.32.0", "@oxfmt/binding-win32-ia32-msvc": "0.32.0", "@oxfmt/binding-win32-x64-msvc": "0.32.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-KArQhGzt/Y8M1eSAX98Y8DLtGYYDQhkR55THUPY5VNcpFQ+9nRZkL3ULXhagHMD2hIvjy8JSeEQEP5/yYJSrLA=="],
+
    "oxlint": ["oxlint@1.42.0", "", { "optionalDependencies": { "@oxlint/darwin-arm64": "1.42.0", "@oxlint/darwin-x64": "1.42.0", "@oxlint/linux-arm64-gnu": "1.42.0", "@oxlint/linux-arm64-musl": "1.42.0", "@oxlint/linux-x64-gnu": "1.42.0", "@oxlint/linux-x64-musl": "1.42.0", "@oxlint/win32-arm64": "1.42.0", "@oxlint/win32-x64": "1.42.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.11.2" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-qnspC/lrp8FgKNaONLLn14dm+W5t0SSlus6V5NJpgI2YNT1tkFYZt4fBf14ESxf9AAh98WBASnW5f0gtw462Lg=="],

    "oxlint-tsgolint": ["oxlint-tsgolint@0.11.4", "", { "optionalDependencies": { "@oxlint-tsgolint/darwin-arm64": "0.11.4", "@oxlint-tsgolint/darwin-x64": "0.11.4", "@oxlint-tsgolint/linux-arm64": "0.11.4", "@oxlint-tsgolint/linux-x64": "0.11.4", "@oxlint-tsgolint/win32-arm64": "0.11.4", "@oxlint-tsgolint/win32-x64": "0.11.4" }, "bin": { "tsgolint": "bin/tsgolint.js" } }, "sha512-VyQc+69TxQwUdsEPiVFN7vNZdDVO/FHaEcHltnWs3O6rvwxv67uADlknQQO714sbRdEahOjgO5dFf+K9ili0gg=="],
@@ -1272,6 +1292,8 @@

    "tinyglobby": ["tinyglobby@0.2.15", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.3" } }, "sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ=="],

+    "tinypool": ["tinypool@2.1.0", "", {}, "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw=="],
+
    "tinyrainbow": ["tinyrainbow@3.0.3", "", {}, "sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q=="],

    "tldts": ["tldts@7.0.19", "", { "dependencies": { "tldts-core": "^7.0.19" }, "bin": { "tldts": "bin/cli.js" } }, "sha512-8PWx8tvC4jDB39BQw1m4x8y5MH1BcQ5xHeL2n7UVFulMPH/3Q0uiamahFJ3lXA0zO2SUyRXuVVbWSDmstlt9YA=="],
@@ -1298,7 +1320,7 @@

    "ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],

-    "undici": ["undici@7.19.2", "", {}, "sha512-4VQSpGEGsWzk0VYxyB/wVX/Q7qf9t5znLRgs0dzszr9w9Fej/8RVNQ+S20vdXSAyra/bJ7ZQfGv6ZMj7UEbzSg=="],
+    "undici": ["undici@7.20.0", "", {}, "sha512-MJZrkjyd7DeC+uPZh+5/YaMDxFiiEEaDgbUSVMXayofAkDWF1088CDo+2RPg7B1BuS1qf1vgNE7xqwPxE0DuSQ=="],

    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],

@@ -1402,8 +1424,12 @@

    "cheerio/parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],

+    "cheerio/undici": ["undici@7.19.2", "", {}, "sha512-4VQSpGEGsWzk0VYxyB/wVX/Q7qf9t5znLRgs0dzszr9w9Fej/8RVNQ+S20vdXSAyra/bJ7ZQfGv6ZMj7UEbzSg=="],
+
    "cheerio/whatwg-mimetype": ["whatwg-mimetype@4.0.0", "", {}, "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg=="],

+    "clawhub/undici": ["undici@7.19.2", "", {}, "sha512-4VQSpGEGsWzk0VYxyB/wVX/Q7qf9t5znLRgs0dzszr9w9Fej/8RVNQ+S20vdXSAyra/bJ7ZQfGv6ZMj7UEbzSg=="],
+
    "convex/esbuild": ["esbuild@0.27.0", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.27.0", "@esbuild/android-arm": "0.27.0", "@esbuild/android-arm64": "0.27.0", "@esbuild/android-x64": "0.27.0", "@esbuild/darwin-arm64": "0.27.0", "@esbuild/darwin-x64": "0.27.0", "@esbuild/freebsd-arm64": "0.27.0", "@esbuild/freebsd-x64": "0.27.0", "@esbuild/linux-arm": "0.27.0", "@esbuild/linux-arm64": "0.27.0", "@esbuild/linux-ia32": "0.27.0", "@esbuild/linux-loong64": "0.27.0", "@esbuild/linux-mips64el": "0.27.0", "@esbuild/linux-ppc64": "0.27.0", "@esbuild/linux-riscv64": "0.27.0", "@esbuild/linux-s390x": "0.27.0", "@esbuild/linux-x64": "0.27.0", "@esbuild/netbsd-arm64": "0.27.0", "@esbuild/netbsd-x64": "0.27.0", "@esbuild/openbsd-arm64": "0.27.0", "@esbuild/openbsd-x64": "0.27.0", "@esbuild/openharmony-arm64": "0.27.0", "@esbuild/sunos-x64": "0.27.0", "@esbuild/win32-arm64": "0.27.0", "@esbuild/win32-ia32": "0.27.0", "@esbuild/win32-x64": "0.27.0" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-jd0f4NHbD6cALCyGElNpGAOtWxSq46l9X/sWB0Nzd5er4Kz2YTm+Vl0qKFT9KUJvD8+fiO8AvoHhFvEatfVixA=="],

    "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
@@ -1412,7 +1438,7 @@

    "htmlparser2/entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],

-    "jsdom/undici": ["undici@7.20.0", "", {}, "sha512-MJZrkjyd7DeC+uPZh+5/YaMDxFiiEEaDgbUSVMXayofAkDWF1088CDo+2RPg7B1BuS1qf1vgNE7xqwPxE0DuSQ=="],
+    "nitro/undici": ["undici@7.19.2", "", {}, "sha512-4VQSpGEGsWzk0VYxyB/wVX/Q7qf9t5znLRgs0dzszr9w9Fej/8RVNQ+S20vdXSAyra/bJ7ZQfGv6ZMj7UEbzSg=="],

    "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],

@@ -9,6 +9,7 @@
 */

 import type * as auth from "../auth.js";
+import type * as commentModeration from "../commentModeration.js";
 import type * as comments from "../comments.js";
 import type * as crons from "../crons.js";
 import type * as devSeed from "../devSeed.js";
@@ -16,30 +17,56 @@ import type * as devSeedExtra from "../devSeedExtra.js";
 import type * as downloads from "../downloads.js";
 import type * as githubBackups from "../githubBackups.js";
 import type * as githubBackupsNode from "../githubBackupsNode.js";
+import type * as githubIdentity from "../githubIdentity.js";
 import type * as githubImport from "../githubImport.js";
+import type * as githubRestore from "../githubRestore.js";
+import type * as githubRestoreMutations from "../githubRestoreMutations.js";
 import type * as githubSoulBackups from "../githubSoulBackups.js";
 import type * as githubSoulBackupsNode from "../githubSoulBackupsNode.js";
 import type * as http from "../http.js";
 import type * as httpApi from "../httpApi.js";
 import type * as httpApiV1 from "../httpApiV1.js";
+import type * as httpApiV1_shared from "../httpApiV1/shared.js";
+import type * as httpApiV1_skillsV1 from "../httpApiV1/skillsV1.js";
+import type * as httpApiV1_soulsV1 from "../httpApiV1/soulsV1.js";
+import type * as httpApiV1_starsV1 from "../httpApiV1/starsV1.js";
+import type * as httpApiV1_usersV1 from "../httpApiV1/usersV1.js";
+import type * as httpApiV1_whoamiV1 from "../httpApiV1/whoamiV1.js";
+import type * as httpPreflight from "../httpPreflight.js";
 import type * as leaderboards from "../leaderboards.js";
 import type * as lib_access from "../lib/access.js";
 import type * as lib_apiTokenAuth from "../lib/apiTokenAuth.js";
 import type * as lib_badges from "../lib/badges.js";
+import type * as lib_batching from "../lib/batching.js";
 import type * as lib_changelog from "../lib/changelog.js";
+import type * as lib_commentScamPrompt from "../lib/commentScamPrompt.js";
+import type * as lib_contentTypes from "../lib/contentTypes.js";
+import type * as lib_embeddingVisibility from "../lib/embeddingVisibility.js";
 import type * as lib_embeddings from "../lib/embeddings.js";
 import type * as lib_githubAccount from "../lib/githubAccount.js";
 import type * as lib_githubBackup from "../lib/githubBackup.js";
+import type * as lib_githubIdentity from "../lib/githubIdentity.js";
 import type * as lib_githubImport from "../lib/githubImport.js";
+import type * as lib_githubProfileSync from "../lib/githubProfileSync.js";
+import type * as lib_githubRestoreHelpers from "../lib/githubRestoreHelpers.js";
 import type * as lib_githubSoulBackup from "../lib/githubSoulBackup.js";
+import type * as lib_globalStats from "../lib/globalStats.js";
+import type * as lib_httpHeaders from "../lib/httpHeaders.js";
+import type * as lib_httpRateLimit from "../lib/httpRateLimit.js";
 import type * as lib_leaderboards from "../lib/leaderboards.js";
 import type * as lib_moderation from "../lib/moderation.js";
+import type * as lib_openaiResponse from "../lib/openaiResponse.js";
 import type * as lib_public from "../lib/public.js";
+import type * as lib_reporting from "../lib/reporting.js";
+import type * as lib_reservedSlugs from "../lib/reservedSlugs.js";
 import type * as lib_searchText from "../lib/searchText.js";
 import type * as lib_securityPrompt from "../lib/securityPrompt.js";
 import type * as lib_skillBackfill from "../lib/skillBackfill.js";
 import type * as lib_skillPublish from "../lib/skillPublish.js";
+import type * as lib_skillQuality from "../lib/skillQuality.js";
+import type * as lib_skillSafety from "../lib/skillSafety.js";
 import type * as lib_skillStats from "../lib/skillStats.js";
+import type * as lib_skillSummary from "../lib/skillSummary.js";
 import type * as lib_skillZip from "../lib/skillZip.js";
 import type * as lib_skills from "../lib/skills.js";
 import type * as lib_soulChangelog from "../lib/soulChangelog.js";
@@ -76,6 +103,7 @@ import type {

 declare const fullApi: ApiFromModules<{
  auth: typeof auth;
+  commentModeration: typeof commentModeration;
  comments: typeof comments;
  crons: typeof crons;
  devSeed: typeof devSeed;
@@ -83,30 +111,56 @@ declare const fullApi: ApiFromModules<{
  downloads: typeof downloads;
  githubBackups: typeof githubBackups;
  githubBackupsNode: typeof githubBackupsNode;
+  githubIdentity: typeof githubIdentity;
  githubImport: typeof githubImport;
+  githubRestore: typeof githubRestore;
+  githubRestoreMutations: typeof githubRestoreMutations;
  githubSoulBackups: typeof githubSoulBackups;
  githubSoulBackupsNode: typeof githubSoulBackupsNode;
  http: typeof http;
  httpApi: typeof httpApi;
  httpApiV1: typeof httpApiV1;
+  "httpApiV1/shared": typeof httpApiV1_shared;
+  "httpApiV1/skillsV1": typeof httpApiV1_skillsV1;
+  "httpApiV1/soulsV1": typeof httpApiV1_soulsV1;
+  "httpApiV1/starsV1": typeof httpApiV1_starsV1;
+  "httpApiV1/usersV1": typeof httpApiV1_usersV1;
+  "httpApiV1/whoamiV1": typeof httpApiV1_whoamiV1;
+  httpPreflight: typeof httpPreflight;
  leaderboards: typeof leaderboards;
  "lib/access": typeof lib_access;
  "lib/apiTokenAuth": typeof lib_apiTokenAuth;
  "lib/badges": typeof lib_badges;
+  "lib/batching": typeof lib_batching;
  "lib/changelog": typeof lib_changelog;
+  "lib/commentScamPrompt": typeof lib_commentScamPrompt;
+  "lib/contentTypes": typeof lib_contentTypes;
+  "lib/embeddingVisibility": typeof lib_embeddingVisibility;
  "lib/embeddings": typeof lib_embeddings;
  "lib/githubAccount": typeof lib_githubAccount;
  "lib/githubBackup": typeof lib_githubBackup;
+  "lib/githubIdentity": typeof lib_githubIdentity;
  "lib/githubImport": typeof lib_githubImport;
+  "lib/githubProfileSync": typeof lib_githubProfileSync;
+  "lib/githubRestoreHelpers": typeof lib_githubRestoreHelpers;
  "lib/githubSoulBackup": typeof lib_githubSoulBackup;
+  "lib/globalStats": typeof lib_globalStats;
+  "lib/httpHeaders": typeof lib_httpHeaders;
+  "lib/httpRateLimit": typeof lib_httpRateLimit;
  "lib/leaderboards": typeof lib_leaderboards;
  "lib/moderation": typeof lib_moderation;
+  "lib/openaiResponse": typeof lib_openaiResponse;
  "lib/public": typeof lib_public;
+  "lib/reporting": typeof lib_reporting;
+  "lib/reservedSlugs": typeof lib_reservedSlugs;
  "lib/searchText": typeof lib_searchText;
  "lib/securityPrompt": typeof lib_securityPrompt;
  "lib/skillBackfill": typeof lib_skillBackfill;
  "lib/skillPublish": typeof lib_skillPublish;
+  "lib/skillQuality": typeof lib_skillQuality;
+  "lib/skillSafety": typeof lib_skillSafety;
  "lib/skillStats": typeof lib_skillStats;
+  "lib/skillSummary": typeof lib_skillSummary;
  "lib/skillZip": typeof lib_skillZip;
  "lib/skills": typeof lib_skills;
  "lib/soulChangelog": typeof lib_soulChangelog;
@@ -1,19 +1,21 @@
 import { describe, expect, it, vi } from 'vitest'
 import type { Id } from './_generated/dataModel'
-import { BANNED_REAUTH_MESSAGE, handleSoftDeletedUserReauth } from './auth'
+import {
+  BANNED_REAUTH_MESSAGE,
+  DELETED_ACCOUNT_REAUTH_MESSAGE,
+  handleDeletedUserSignIn,
+} from './auth'

 function makeCtx({
  user,
-  banRecord,
+  banRecords,
 }: {
-  user: { deletedAt?: number } | null
-  banRecord?: Record<string, unknown> | null
+  user: { deletedAt?: number; deactivatedAt?: number; purgedAt?: number } | null
+  banRecords?: Array<Record<string, unknown>>
 }) {
  const query = {
    withIndex: vi.fn().mockReturnValue({
-      filter: vi.fn().mockReturnValue({
-        first: vi.fn().mockResolvedValue(banRecord ?? null),
-      }),
+      collect: vi.fn().mockResolvedValue(banRecords ?? []),
    }),
  }
  const ctx = {
@@ -26,74 +28,96 @@ function makeCtx({
  return { ctx, query }
 }

-describe('handleSoftDeletedUserReauth', () => {
+describe('handleDeletedUserSignIn', () => {
  const userId = 'users:1' as Id<'users'>

  it('skips when user not found', async () => {
    const { ctx } = makeCtx({ user: null })

-    await handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: userId })
+    await handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId })

    expect(ctx.db.get).toHaveBeenCalledWith(userId)
    expect(ctx.db.query).not.toHaveBeenCalled()
  })

  it('skips active users', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: undefined } })
+    const { ctx } = makeCtx({ user: { deletedAt: undefined, deactivatedAt: undefined } })

-    await handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: userId })
+    await handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId })

    expect(ctx.db.query).not.toHaveBeenCalled()
    expect(ctx.db.patch).not.toHaveBeenCalled()
  })

-  it('restores soft-deleted users when not banned', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecord: null })
+  it('blocks sign-in for deactivated users', async () => {
+    const { ctx } = makeCtx({ user: { deactivatedAt: 123, purgedAt: 123 } })

-    await handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: userId })
+    await expect(
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId }),
+    ).rejects.toThrow(DELETED_ACCOUNT_REAUTH_MESSAGE)
+
+    expect(ctx.db.query).not.toHaveBeenCalled()
+    expect(ctx.db.patch).not.toHaveBeenCalled()
+  })
+
+  it('migrates legacy self-deleted users and blocks sign-in', async () => {
+    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecords: [] })
+
+    await expect(
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId }),
+    ).rejects.toThrow(DELETED_ACCOUNT_REAUTH_MESSAGE)

    expect(ctx.db.patch).toHaveBeenCalledWith(userId, {
      deletedAt: undefined,
+      deactivatedAt: 123,
+      purgedAt: 123,
      updatedAt: expect.any(Number),
    })
  })

-  it('restores soft-deleted users on fresh login (existingUserId is null)', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecord: null })
+  it('migrates legacy users on fresh login (existingUserId is null)', async () => {
+    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecords: [] })

-    await handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: null })
+    await expect(
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: null }),
+    ).rejects.toThrow(DELETED_ACCOUNT_REAUTH_MESSAGE)

    expect(ctx.db.patch).toHaveBeenCalledWith(userId, {
      deletedAt: undefined,
+      deactivatedAt: 123,
+      purgedAt: 123,
      updatedAt: expect.any(Number),
    })
  })

-  it('skips reactivation when existingUserId does not match userId', async () => {
+  it('skips mutation when existingUserId does not match userId', async () => {
    const otherUserId = 'users:999' as Id<'users'>
    const { ctx } = makeCtx({ user: { deletedAt: 123 } })

-    await handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: otherUserId })
+    await handleDeletedUserSignIn(ctx as never, { userId, existingUserId: otherUserId })

    expect(ctx.db.query).not.toHaveBeenCalled()
    expect(ctx.db.patch).not.toHaveBeenCalled()
  })

  it('blocks banned users with a custom message', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecord: { action: 'user.ban' } })
+    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecords: [{ action: 'user.ban' }] })

    await expect(
-      handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: userId }),
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId }),
    ).rejects.toThrow(BANNED_REAUTH_MESSAGE)

    expect(ctx.db.patch).not.toHaveBeenCalled()
  })

-  it('blocks banned users on fresh login (existingUserId is null)', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecord: { action: 'user.ban' } })
+  it('blocks users auto-banned for malware', async () => {
+    const { ctx } = makeCtx({
+      user: { deletedAt: 123 },
+      banRecords: [{ action: 'user.autoban.malware' }],
+    })

    await expect(
-      handleSoftDeletedUserReauth(ctx as never, { userId, existingUserId: null }),
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId }),
    ).rejects.toThrow(BANNED_REAUTH_MESSAGE)

    expect(ctx.db.patch).not.toHaveBeenCalled()
@@ -2,38 +2,57 @@ import GitHub from '@auth/core/providers/github'
 import { convexAuth } from '@convex-dev/auth/server'
 import type { GenericMutationCtx } from 'convex/server'
 import { ConvexError } from 'convex/values'
+import { internal } from './_generated/api'
 import type { DataModel, Id } from './_generated/dataModel'
+import { shouldScheduleGitHubProfileSync } from './lib/githubProfileSync'

 export const BANNED_REAUTH_MESSAGE =
  'Your account has been banned for uploading malicious skills. If you believe this is a mistake, please contact security@openclaw.ai and we will work with you to restore access.'
+export const DELETED_ACCOUNT_REAUTH_MESSAGE =
+  'This account has been permanently deleted and cannot be restored.'

-export async function handleSoftDeletedUserReauth(
+const REAUTH_BLOCKING_BAN_ACTIONS = new Set(['user.ban', 'user.autoban.malware'])
+
+export async function handleDeletedUserSignIn(
  ctx: GenericMutationCtx<DataModel>,
  args: { userId: Id<'users'>; existingUserId: Id<'users'> | null },
+  userOverride?: { deletedAt?: number; deactivatedAt?: number; purgedAt?: number } | null,
 ) {
-  const user = await ctx.db.get(args.userId)
-  if (!user?.deletedAt) return
+  const user = userOverride !== undefined ? userOverride : await ctx.db.get(args.userId)
+  if (!user?.deletedAt && !user?.deactivatedAt) return

-  // Verify that the incoming identity matches the soft-deleted user to prevent bypass.
+  // Verify that the incoming identity matches the existing account to prevent bypass.
  if (args.existingUserId && args.existingUserId !== args.userId) {
    return
  }

+  if (user.deactivatedAt) {
+    throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE)
+  }
+
  const userId = args.userId
-  const banRecord = await ctx.db
+  const deletedAt = user.deletedAt ?? Date.now()
+  const banRecords = await ctx.db
    .query('auditLogs')
    .withIndex('by_target', (q) => q.eq('targetType', 'user').eq('targetId', userId.toString()))
-    .filter((q) => q.eq(q.field('action'), 'user.ban'))
-    .first()
+    .collect()

-  if (banRecord) {
+  const hasBlockingBan = banRecords.some((record) => REAUTH_BLOCKING_BAN_ACTIONS.has(record.action))
+
+  if (hasBlockingBan) {
    throw new ConvexError(BANNED_REAUTH_MESSAGE)
  }

+  // Migrate legacy self-deleted accounts (stored in deletedAt) to the new
+  // irreversible state and reject sign-in.
  await ctx.db.patch(userId, {
    deletedAt: undefined,
+    deactivatedAt: deletedAt,
+    purgedAt: user.purgedAt ?? deletedAt,
    updatedAt: Date.now(),
  })
+
+  throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE)
 }

 export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
@@ -53,15 +72,27 @@ export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  ],
  callbacks: {
    /**
-     * Handle re-authentication of soft-deleted users.
+     * Block sign-in for deleted/deactivated users and sync GitHub profile.
     *
     * Performance note: This callback runs on every OAuth sign-in, but the
-     * audit log query ONLY executes when a soft-deleted user attempts to
-     * sign in (user.deletedAt is set). For normal active users, this is
-     * just a single `if` check on an already-loaded field - no extra queries.
+     * audit log query ONLY executes when a legacy deleted user attempts to sign
+     * in (user.deletedAt is set). For active users, this is a single field check.
+     *
+     * The GitHub profile sync is scheduled as a background action to handle
+     * the case where a user renames their GitHub account (fixes #303).
     */
    async afterUserCreatedOrUpdated(ctx, args) {
-      await handleSoftDeletedUserReauth(ctx, args)
+      const user = await ctx.db.get(args.userId)
+      await handleDeletedUserSignIn(ctx, args, user)
+
+      // Schedule GitHub profile sync to handle username renames (fixes #303)
+      // This runs as a background action so it doesn't block sign-in
+      const now = Date.now()
+      if (shouldScheduleGitHubProfileSync(user, now)) {
+        await ctx.scheduler.runAfter(0, internal.users.syncGitHubProfileAction, {
+          userId: args.userId,
+        })
+      }
    },
  },
 })
@@ -0,0 +1,285 @@
+/* @vitest-environment node */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('./_generated/api', () => ({
+  internal: {
+    commentModeration: {
+      getCommentScamBackfillPageInternal: Symbol('commentModeration.getCommentScamBackfillPageInternal'),
+      applyCommentScamResultInternal: Symbol('commentModeration.applyCommentScamResultInternal'),
+      backfillCommentScamModerationInternal: Symbol('commentModeration.backfillCommentScamModerationInternal'),
+      continueCommentScamModerationJobInternal: Symbol(
+        'commentModeration.continueCommentScamModerationJobInternal',
+      ),
+    },
+    llmEval: {
+      evaluateCommentForScam: Symbol('llmEval.evaluateCommentForScam'),
+    },
+    users: {
+      banUserInternal: Symbol('users.banUserInternal'),
+    },
+  },
+}))
+
+const {
+  applyCommentScamResultInternalHandler,
+  backfillCommentScamModerationInternalHandler,
+} = await import('./commentModeration')
+const { internal } = await import('./_generated/api')
+
+const previousOpenAiApiKey = process.env.OPENAI_API_KEY
+
+beforeEach(() => {
+  process.env.OPENAI_API_KEY = 'test-key'
+})
+
+afterEach(() => {
+  if (previousOpenAiApiKey === undefined) {
+    delete process.env.OPENAI_API_KEY
+    return
+  }
+  process.env.OPENAI_API_KEY = previousOpenAiApiKey
+})
+
+describe('commentModeration backfill', () => {
+  it('evaluates comments and bans on certain/high scams', async () => {
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [
+          {
+            commentId: 'comments:1',
+            skillId: 'skills:1',
+            userId: 'users:2',
+            body: 'echo "mal" | base64 -D | bash',
+            softDeletedAt: undefined,
+            scamScanCheckedAt: undefined,
+          },
+        ],
+        cursor: null,
+        isDone: true,
+      })
+    const runAction = vi.fn().mockResolvedValue({
+      ok: true,
+      model: 'gpt-5-mini',
+      verdict: 'certain_scam',
+      confidence: 'high',
+      explanation: 'Obfuscated shell execution payload.',
+      evidence: ['base64 decode piped to bash'],
+    })
+    const runMutation = vi.fn().mockResolvedValue({
+      ok: true,
+      shouldBan: true,
+      banned: true,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: false,
+    })
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: 'users:admin',
+        dryRun: false,
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.commentsScanned).toBe(1)
+    expect(result.stats.commentsEvaluated).toBe(1)
+    expect(result.stats.certainScams).toBe(1)
+    expect(result.stats.banCandidates).toBe(1)
+    expect(result.stats.usersBanned).toBe(1)
+    expect(runAction).toHaveBeenCalledWith(internal.llmEval.evaluateCommentForScam, {
+      commentId: 'comments:1',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      body: 'echo "mal" | base64 -D | bash',
+    })
+    expect(runMutation).toHaveBeenCalledWith(internal.commentModeration.applyCommentScamResultInternal, {
+      actorUserId: 'users:admin',
+      commentId: 'comments:1',
+      verdict: 'certain_scam',
+      confidence: 'high',
+      explanation: 'Obfuscated shell execution payload.',
+      evidence: ['base64 decode piped to bash'],
+      model: 'gpt-5-mini',
+      checkedAt: expect.any(Number),
+      dryRun: false,
+    })
+  })
+
+  it('skips previously scanned comments unless rescan=true', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          commentId: 'comments:1',
+          skillId: 'skills:1',
+          userId: 'users:2',
+          body: 'something',
+          softDeletedAt: undefined,
+          scamScanCheckedAt: 123,
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+    const runAction = vi.fn()
+    const runMutation = vi.fn()
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: 'users:admin',
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    )
+
+    expect(result.stats.commentsScanned).toBe(1)
+    expect(result.stats.skippedAlreadyScanned).toBe(1)
+    expect(runAction).not.toHaveBeenCalled()
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('tracks dry-run ban candidates without banning', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          commentId: 'comments:9',
+          skillId: 'skills:7',
+          userId: 'users:5',
+          body: 'run this update installer from random domain',
+          softDeletedAt: undefined,
+          scamScanCheckedAt: undefined,
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+    const runAction = vi.fn().mockResolvedValue({
+      ok: true,
+      model: 'gpt-5-mini',
+      verdict: 'certain_scam',
+      confidence: 'high',
+      explanation: 'Social-engineering install command.',
+      evidence: ['unknown update domain'],
+    })
+    const runMutation = vi.fn().mockResolvedValue({
+      ok: true,
+      shouldBan: true,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: true,
+    })
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: 'users:admin',
+        dryRun: true,
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    )
+
+    expect(result.stats.usersBanned).toBe(0)
+    expect(result.stats.usersWouldBeBanned).toBe(1)
+  })
+})
+
+describe('applyCommentScamResultInternalHandler', () => {
+  it('persists scan metadata and triggers ban with bounded reason', async () => {
+    const get = vi
+      .fn()
+      .mockResolvedValueOnce({
+        _id: 'comments:1',
+        skillId: 'skills:1',
+        userId: 'users:2',
+      })
+      .mockResolvedValueOnce({
+        _id: 'users:2',
+        role: 'user',
+      })
+    const patch = vi.fn()
+    const insert = vi.fn()
+    const runMutation = vi.fn().mockResolvedValue({ ok: true, alreadyBanned: false, deletedSkills: 0 })
+
+    const result = await applyCommentScamResultInternalHandler(
+      { db: { get, patch, insert }, runMutation } as never,
+      {
+        actorUserId: 'users:admin',
+        commentId: 'comments:1',
+        verdict: 'certain_scam',
+        confidence: 'high',
+        explanation: 'X'.repeat(700),
+        evidence: ['Y'.repeat(280), 'Z'.repeat(280)],
+        model: 'gpt-5-mini',
+        checkedAt: 123,
+      } as never,
+    )
+
+    expect(result.banned).toBe(true)
+    expect(insert).toHaveBeenCalledWith('auditLogs', {
+      actorUserId: 'users:admin',
+      action: 'comment.scam_scan',
+      targetType: 'comment',
+      targetId: 'comments:1',
+      metadata: {
+        skillId: 'skills:1',
+        commentAuthorId: 'users:2',
+        verdict: 'certain_scam',
+        confidence: 'high',
+        shouldBan: true,
+        model: 'gpt-5-mini',
+      },
+      createdAt: 123,
+    })
+
+    const banCall = runMutation.mock.calls.find(
+      (call) => call[0] === internal.users.banUserInternal,
+    )
+    expect(banCall).toBeTruthy()
+    if (!banCall) throw new Error('Expected ban mutation to be called')
+    expect((banCall[1] as { reason: string }).reason.length).toBeLessThanOrEqual(500)
+    expect(patch).toHaveBeenCalledWith('comments:1', {
+      scamBanTriggeredAt: 123,
+    })
+  })
+
+  it('skips banning moderator/admin accounts', async () => {
+    const get = vi
+      .fn()
+      .mockResolvedValueOnce({
+        _id: 'comments:2',
+        skillId: 'skills:2',
+        userId: 'users:staff',
+      })
+      .mockResolvedValueOnce({
+        _id: 'users:staff',
+        role: 'moderator',
+      })
+    const patch = vi.fn()
+    const insert = vi.fn()
+    const runMutation = vi.fn()
+
+    const result = await applyCommentScamResultInternalHandler(
+      { db: { get, patch, insert }, runMutation } as never,
+      {
+        actorUserId: 'users:admin',
+        commentId: 'comments:2',
+        verdict: 'certain_scam',
+        confidence: 'high',
+        explanation: 'Malicious command spam.',
+        evidence: ['base64|bash'],
+        model: 'gpt-5-mini',
+        checkedAt: 300,
+      } as never,
+    )
+
+    expect(result.protectedRole).toBe(true)
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+})
@@ -0,0 +1,465 @@
+import { ConvexError, v } from 'convex/values'
+import { internal } from './_generated/api'
+import type { Id } from './_generated/dataModel'
+import type { ActionCtx, MutationCtx } from './_generated/server'
+import { action, internalAction, internalMutation, internalQuery } from './_generated/server'
+import { assertRole, requireUserFromAction } from './lib/access'
+import {
+  buildCommentScamBanReason,
+  isCertainScam,
+  type CommentScamConfidence,
+  type CommentScamVerdict,
+} from './lib/commentScamPrompt'
+
+const DEFAULT_BATCH_SIZE = 25
+const MAX_BATCH_SIZE = 100
+const DEFAULT_MAX_BATCHES = 10
+const MAX_MAX_BATCHES = 200
+
+type CommentBackfillPageItem = {
+  commentId: Id<'comments'>
+  skillId: Id<'skills'>
+  userId: Id<'users'>
+  body: string
+  softDeletedAt?: number
+  scamScanCheckedAt?: number
+}
+
+type CommentBackfillPageResult = {
+  items: CommentBackfillPageItem[]
+  cursor: string | null
+  isDone: boolean
+}
+
+type ApplyCommentScamResult = {
+  ok: true
+  shouldBan: boolean
+  banned: boolean
+  alreadyBanned: boolean
+  protectedRole: boolean
+  wouldBan: boolean
+}
+
+export type CommentScamBackfillStats = {
+  commentsScanned: number
+  commentsEvaluated: number
+  certainScams: number
+  banCandidates: number
+  usersBanned: number
+  usersAlreadyBanned: number
+  usersWouldBeBanned: number
+  protectedRoleSkips: number
+  skippedSoftDeleted: number
+  skippedAlreadyScanned: number
+  skippedEmptyBody: number
+  evalErrors: number
+}
+
+export type CommentScamBackfillActionArgs = {
+  actorUserId: Id<'users'>
+  dryRun?: boolean
+  batchSize?: number
+  maxBatches?: number
+  cursor?: string
+  rescan?: boolean
+  includeSoftDeleted?: boolean
+}
+
+export type CommentScamBackfillActionResult = {
+  ok: true
+  stats: CommentScamBackfillStats
+  isDone: boolean
+  cursor: string | null
+}
+
+export const getCommentScamBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<CommentBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+    const { page, isDone, continueCursor } = await ctx.db
+      .query('comments')
+      .order('asc')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    return {
+      items: page.map((comment) => ({
+        commentId: comment._id,
+        skillId: comment.skillId,
+        userId: comment.userId,
+        body: comment.body,
+        softDeletedAt: comment.softDeletedAt,
+        scamScanCheckedAt: comment.scamScanCheckedAt,
+      })),
+      cursor: continueCursor,
+      isDone,
+    }
+  },
+})
+
+export async function applyCommentScamResultInternalHandler(
+  ctx: MutationCtx,
+  args: {
+    actorUserId: Id<'users'>
+    commentId: Id<'comments'>
+    verdict: CommentScamVerdict
+    confidence: CommentScamConfidence
+    explanation: string
+    evidence: string[]
+    model: string
+    checkedAt: number
+    dryRun?: boolean
+  },
+): Promise<ApplyCommentScamResult> {
+  const comment = await ctx.db.get(args.commentId)
+  if (!comment) {
+    throw new ConvexError('Comment not found')
+  }
+
+  const user = await ctx.db.get(comment.userId)
+  if (!user) {
+    throw new ConvexError('Comment author not found')
+  }
+
+  const dryRun = Boolean(args.dryRun)
+  const shouldBan = isCertainScam({
+    verdict: args.verdict,
+    confidence: args.confidence,
+  })
+
+  const explanation = args.explanation.trim().slice(0, 1200)
+  const evidence = args.evidence
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, 5)
+
+  if (!dryRun) {
+    await ctx.db.patch(comment._id, {
+      scamScanVerdict: args.verdict,
+      scamScanConfidence: args.confidence,
+      scamScanExplanation: explanation,
+      scamScanEvidence: evidence,
+      scamScanModel: args.model,
+      scamScanCheckedAt: args.checkedAt,
+    })
+
+    await ctx.db.insert('auditLogs', {
+      actorUserId: args.actorUserId,
+      action: 'comment.scam_scan',
+      targetType: 'comment',
+      targetId: comment._id,
+      metadata: {
+        skillId: comment.skillId,
+        commentAuthorId: comment.userId,
+        verdict: args.verdict,
+        confidence: args.confidence,
+        shouldBan,
+        model: args.model,
+      },
+      createdAt: args.checkedAt,
+    })
+  }
+
+  if (!shouldBan) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: false,
+    }
+  }
+
+  if (user.role === 'admin' || user.role === 'moderator') {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: true,
+      wouldBan: false,
+    }
+  }
+
+  if (user.deletedAt || user.deactivatedAt) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: true,
+      protectedRole: false,
+      wouldBan: false,
+    }
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: true,
+    }
+  }
+
+  const reason = buildCommentScamBanReason({
+    commentId: String(comment._id),
+    skillId: String(comment.skillId),
+    explanation,
+    evidence,
+  })
+
+  const banResult = await ctx.runMutation(internal.users.banUserInternal, {
+    actorUserId: args.actorUserId,
+    targetUserId: comment.userId,
+    reason,
+  })
+
+  if (!banResult.alreadyBanned) {
+    await ctx.db.patch(comment._id, {
+      scamBanTriggeredAt: args.checkedAt,
+    })
+  }
+
+  return {
+    ok: true,
+    shouldBan,
+    banned: !banResult.alreadyBanned,
+    alreadyBanned: Boolean(banResult.alreadyBanned),
+    protectedRole: false,
+    wouldBan: false,
+  }
+}
+
+export const applyCommentScamResultInternal = internalMutation({
+  args: {
+    actorUserId: v.id('users'),
+    commentId: v.id('comments'),
+    verdict: v.union(v.literal('not_scam'), v.literal('likely_scam'), v.literal('certain_scam')),
+    confidence: v.union(v.literal('low'), v.literal('medium'), v.literal('high')),
+    explanation: v.string(),
+    evidence: v.array(v.string()),
+    model: v.string(),
+    checkedAt: v.number(),
+    dryRun: v.optional(v.boolean()),
+  },
+  handler: applyCommentScamResultInternalHandler,
+})
+
+export async function backfillCommentScamModerationInternalHandler(
+  ctx: ActionCtx,
+  args: CommentScamBackfillActionArgs,
+): Promise<CommentScamBackfillActionResult> {
+  if (!process.env.OPENAI_API_KEY) {
+    throw new ConvexError('OPENAI_API_KEY not configured')
+  }
+
+  const dryRun = Boolean(args.dryRun)
+  const rescan = Boolean(args.rescan)
+  const includeSoftDeleted = Boolean(args.includeSoftDeleted)
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+
+  let cursor: string | null = args.cursor ?? null
+  let isDone = false
+
+  const stats: CommentScamBackfillStats = {
+    commentsScanned: 0,
+    commentsEvaluated: 0,
+    certainScams: 0,
+    banCandidates: 0,
+    usersBanned: 0,
+    usersAlreadyBanned: 0,
+    usersWouldBeBanned: 0,
+    protectedRoleSkips: 0,
+    skippedSoftDeleted: 0,
+    skippedAlreadyScanned: 0,
+    skippedEmptyBody: 0,
+    evalErrors: 0,
+  }
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.commentModeration.getCommentScamBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as CommentBackfillPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const comment of page.items) {
+      stats.commentsScanned++
+
+      if (!includeSoftDeleted && comment.softDeletedAt) {
+        stats.skippedSoftDeleted++
+        continue
+      }
+      if (!rescan && comment.scamScanCheckedAt) {
+        stats.skippedAlreadyScanned++
+        continue
+      }
+
+      const body = comment.body.trim()
+      if (!body) {
+        stats.skippedEmptyBody++
+        continue
+      }
+
+      const evalResult = (await ctx.runAction(internal.llmEval.evaluateCommentForScam, {
+        commentId: comment.commentId,
+        skillId: comment.skillId,
+        userId: comment.userId,
+        body,
+      })) as
+        | {
+            ok: true
+            model: string
+            verdict: CommentScamVerdict
+            confidence: CommentScamConfidence
+            explanation: string
+            evidence: string[]
+          }
+        | { ok: false; error: string }
+
+      if (!evalResult.ok) {
+        stats.evalErrors++
+        continue
+      }
+
+      stats.commentsEvaluated++
+      const shouldBan = isCertainScam(evalResult)
+      if (evalResult.verdict === 'certain_scam') {
+        stats.certainScams++
+      }
+      if (shouldBan) {
+        stats.banCandidates++
+      }
+
+      const applyResult = (await ctx.runMutation(internal.commentModeration.applyCommentScamResultInternal, {
+        actorUserId: args.actorUserId,
+        commentId: comment.commentId,
+        verdict: evalResult.verdict,
+        confidence: evalResult.confidence,
+        explanation: evalResult.explanation,
+        evidence: evalResult.evidence,
+        model: evalResult.model,
+        checkedAt: Date.now(),
+        dryRun,
+      })) as ApplyCommentScamResult
+
+      if (applyResult.banned) stats.usersBanned++
+      if (applyResult.alreadyBanned) stats.usersAlreadyBanned++
+      if (applyResult.wouldBan) stats.usersWouldBeBanned++
+      if (applyResult.protectedRole) stats.protectedRoleSkips++
+    }
+
+    if (isDone) break
+  }
+
+  return {
+    ok: true,
+    stats,
+    isDone,
+    cursor,
+  }
+}
+
+export const backfillCommentScamModerationInternal = internalAction({
+  args: {
+    actorUserId: v.id('users'),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: backfillCommentScamModerationInternalHandler,
+})
+
+export const backfillCommentScamModeration: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<CommentScamBackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin', 'moderator'])
+
+    return ctx.runAction(internal.commentModeration.backfillCommentScamModerationInternal, {
+      actorUserId: user._id,
+      ...args,
+    }) as Promise<CommentScamBackfillActionResult>
+  },
+})
+
+export const continueCommentScamModerationJobInternal = internalAction({
+  args: {
+    actorUserId: v.id('users'),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const result = await backfillCommentScamModerationInternalHandler(ctx, {
+      actorUserId: args.actorUserId,
+      dryRun: args.dryRun,
+      batchSize: args.batchSize,
+      cursor: args.cursor,
+      maxBatches: 1,
+      rescan: args.rescan,
+      includeSoftDeleted: args.includeSoftDeleted,
+    })
+
+    if (!result.isDone && result.cursor) {
+      await ctx.scheduler.runAfter(2_000, internal.commentModeration.continueCommentScamModerationJobInternal, {
+        actorUserId: args.actorUserId,
+        dryRun: Boolean(args.dryRun),
+        batchSize: args.batchSize ?? DEFAULT_BATCH_SIZE,
+        cursor: result.cursor,
+        rescan: Boolean(args.rescan),
+        includeSoftDeleted: Boolean(args.includeSoftDeleted),
+      })
+    }
+
+    return result
+  },
+})
+
+export const scheduleCommentScamModeration: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<{ ok: true }> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin', 'moderator'])
+
+    await ctx.scheduler.runAfter(0, internal.commentModeration.continueCommentScamModerationJobInternal, {
+      actorUserId: user._id,
+      dryRun: Boolean(args.dryRun),
+      batchSize: clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE),
+      cursor: undefined,
+      rescan: Boolean(args.rescan),
+      includeSoftDeleted: Boolean(args.includeSoftDeleted),
+    })
+
+    return { ok: true as const }
+  },
+})
+
+function clampInt(value: number, min: number, max: number) {
+  return Math.min(Math.max(Math.trunc(value), min), max)
+}
@@ -0,0 +1,151 @@
+import type { Id } from './_generated/dataModel'
+import type { MutationCtx } from './_generated/server'
+import { assertModerator, requireUser } from './lib/access'
+import { requireGitHubAccountAge } from './lib/githubAccount'
+import {
+  AUTO_HIDE_REPORT_THRESHOLD,
+  MAX_ACTIVE_REPORTS_PER_USER,
+  MAX_REPORT_REASON_LENGTH,
+} from './lib/reporting'
+import { insertStatEvent } from './skillStatEvents'
+
+export async function addHandler(ctx: MutationCtx, args: { skillId: Id<'skills'>; body: string }) {
+  const { userId } = await requireUser(ctx)
+  await requireGitHubAccountAge(ctx, userId)
+
+  const body = args.body.trim()
+  if (!body) throw new Error('Comment body required')
+
+  const skill = await ctx.db.get(args.skillId)
+  if (!skill) throw new Error('Skill not found')
+
+  await ctx.db.insert('comments', {
+    skillId: args.skillId,
+    userId,
+    body,
+    createdAt: Date.now(),
+    softDeletedAt: undefined,
+    deletedBy: undefined,
+  })
+
+  await insertStatEvent(ctx, { skillId: skill._id, kind: 'comment' })
+}
+
+export async function removeHandler(ctx: MutationCtx, args: { commentId: Id<'comments'> }) {
+  const { user } = await requireUser(ctx)
+  const comment = await ctx.db.get(args.commentId)
+  if (!comment) throw new Error('Comment not found')
+  if (comment.softDeletedAt) return
+
+  const isOwner = comment.userId === user._id
+  if (!isOwner) {
+    assertModerator(user)
+  }
+
+  await ctx.db.patch(comment._id, {
+    softDeletedAt: Date.now(),
+    deletedBy: user._id,
+  })
+
+  await insertStatEvent(ctx, { skillId: comment.skillId, kind: 'uncomment' })
+
+  await ctx.db.insert('auditLogs', {
+    actorUserId: user._id,
+    action: 'comment.delete',
+    targetType: 'comment',
+    targetId: comment._id,
+    metadata: { skillId: comment.skillId },
+    createdAt: Date.now(),
+  })
+}
+
+async function countActiveReportsForUser(ctx: MutationCtx, userId: Id<'users'>) {
+  const reports = await ctx.db
+    .query('commentReports')
+    .withIndex('by_user', (q) => q.eq('userId', userId))
+    .collect()
+
+  let count = 0
+  for (const report of reports) {
+    const comment = await ctx.db.get(report.commentId)
+    if (!comment || comment.softDeletedAt) continue
+    const skill = await ctx.db.get(comment.skillId)
+    if (!skill || skill.softDeletedAt || skill.moderationStatus === 'removed') continue
+    const owner = await ctx.db.get(comment.userId)
+    if (!owner || owner.deletedAt || owner.deactivatedAt) continue
+    count += 1
+    if (count >= MAX_ACTIVE_REPORTS_PER_USER) break
+  }
+
+  return count
+}
+
+export async function reportHandler(
+  ctx: MutationCtx,
+  args: { commentId: Id<'comments'>; reason: string },
+) {
+  const { userId } = await requireUser(ctx)
+  const comment = await ctx.db.get(args.commentId)
+  if (!comment || comment.softDeletedAt) {
+    throw new Error('Comment not found')
+  }
+  const skill = await ctx.db.get(comment.skillId)
+  if (!skill || skill.softDeletedAt || skill.moderationStatus === 'removed') {
+    throw new Error('Comment not found')
+  }
+
+  const reason = args.reason.trim()
+  if (!reason) {
+    throw new Error('Report reason required.')
+  }
+
+  const existing = await ctx.db
+    .query('commentReports')
+    .withIndex('by_comment_user', (q) => q.eq('commentId', args.commentId).eq('userId', userId))
+    .unique()
+  if (existing) return { ok: true as const, reported: false, alreadyReported: true }
+
+  const activeReports = await countActiveReportsForUser(ctx, userId)
+  if (activeReports >= MAX_ACTIVE_REPORTS_PER_USER) {
+    throw new Error('Report limit reached. Please wait for moderation before reporting more.')
+  }
+
+  const now = Date.now()
+  await ctx.db.insert('commentReports', {
+    commentId: args.commentId,
+    skillId: comment.skillId,
+    userId,
+    reason: reason.slice(0, MAX_REPORT_REASON_LENGTH),
+    createdAt: now,
+  })
+
+  const nextReportCount = (comment.reportCount ?? 0) + 1
+  const shouldAutoHide = nextReportCount > AUTO_HIDE_REPORT_THRESHOLD && !comment.softDeletedAt
+  const updates: {
+    reportCount: number
+    lastReportedAt: number
+    softDeletedAt?: number
+  } = {
+    reportCount: nextReportCount,
+    lastReportedAt: now,
+  }
+  if (shouldAutoHide) {
+    updates.softDeletedAt = now
+  }
+  await ctx.db.patch(comment._id, updates)
+
+  if (shouldAutoHide) {
+    await insertStatEvent(ctx, { skillId: comment.skillId, kind: 'uncomment' })
+
+    await ctx.db.insert('auditLogs', {
+      actorUserId: userId,
+      action: 'comment.auto_hide',
+      targetType: 'comment',
+      targetId: comment._id,
+      metadata: { skillId: comment.skillId, reportCount: nextReportCount },
+      createdAt: now,
+    })
+  }
+
+  return { ok: true as const, reported: true, alreadyReported: false }
+}
@@ -0,0 +1,127 @@
+/* @vitest-environment node */
+import { describe, expect, it } from 'vitest'
+import { listBySkill } from './comments'
+
+function makeCtx(args: {
+  comments: Array<Record<string, unknown>>
+  usersById: Record<string, Record<string, unknown> | null>
+}) {
+  const get = async (id: string) => args.usersById[id] ?? null
+  const take = async () => args.comments
+  const order = () => ({ take })
+  const withIndex = () => ({ order })
+  const query = () => ({ withIndex })
+  return { db: { get, query } } as never
+}
+
+describe('comments.listBySkill', () => {
+  it('skips soft-deleted comments', async () => {
+    const ctx = makeCtx({
+      comments: [
+        {
+          _id: 'comments:live',
+          skillId: 'skills:1',
+          userId: 'users:live',
+          body: 'hello',
+        },
+        {
+          _id: 'comments:deleted',
+          skillId: 'skills:1',
+          userId: 'users:live',
+          body: 'bye',
+          softDeletedAt: 123,
+        },
+      ],
+      usersById: {
+        'users:live': {
+          _id: 'users:live',
+          _creationTime: 1,
+          handle: 'live',
+          name: 'live',
+          displayName: 'Live',
+          image: null,
+          bio: null,
+        },
+      },
+    })
+
+    const result = await listBySkill._handler(ctx, {
+      skillId: 'skills:1',
+      limit: 50,
+    } as never)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]?.comment._id).toBe('comments:live')
+  })
+
+  it('skips comments whose author is deleted/deactivated/missing', async () => {
+    const ctx = makeCtx({
+      comments: [
+        {
+          _id: 'comments:ok',
+          skillId: 'skills:1',
+          userId: 'users:ok',
+          body: 'ok',
+        },
+        {
+          _id: 'comments:deleted-user',
+          skillId: 'skills:1',
+          userId: 'users:deleted',
+          body: 'hidden',
+        },
+        {
+          _id: 'comments:deactivated-user',
+          skillId: 'skills:1',
+          userId: 'users:deactivated',
+          body: 'hidden',
+        },
+        {
+          _id: 'comments:missing-user',
+          skillId: 'skills:1',
+          userId: 'users:missing',
+          body: 'hidden',
+        },
+      ],
+      usersById: {
+        'users:ok': {
+          _id: 'users:ok',
+          _creationTime: 1,
+          handle: 'ok',
+          name: 'ok',
+          displayName: 'Ok',
+          image: null,
+          bio: null,
+        },
+        'users:deleted': {
+          _id: 'users:deleted',
+          _creationTime: 1,
+          handle: 'deleted',
+          name: 'deleted',
+          displayName: 'Deleted',
+          image: null,
+          bio: null,
+          deletedAt: 123,
+        },
+        'users:deactivated': {
+          _id: 'users:deactivated',
+          _creationTime: 1,
+          handle: 'deactivated',
+          name: 'deactivated',
+          displayName: 'Deactivated',
+          image: null,
+          bio: null,
+          deactivatedAt: 456,
+        },
+      },
+    })
+
+    const result = await listBySkill._handler(ctx, {
+      skillId: 'skills:1',
+      limit: 50,
+    } as never)
+
+    expect(result).toHaveLength(1)
+    expect(result[0]?.comment._id).toBe('comments:ok')
+    expect(result[0]?.user._id).toBe('users:ok')
+  })
+})
@@ -0,0 +1,586 @@
+/* @vitest-environment node */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('./lib/access', () => ({
+  assertModerator: vi.fn(),
+  requireUser: vi.fn(),
+}))
+
+vi.mock('./skillStatEvents', () => ({
+  insertStatEvent: vi.fn(),
+}))
+
+vi.mock('./lib/githubAccount', () => ({
+  requireGitHubAccountAge: vi.fn(),
+}))
+
+const { requireUser, assertModerator } = await import('./lib/access')
+const { insertStatEvent } = await import('./skillStatEvents')
+const { requireGitHubAccountAge } = await import('./lib/githubAccount')
+const { addHandler, removeHandler, reportHandler } = await import('./comments.handlers')
+
+describe('comments mutations', () => {
+  afterEach(() => {
+    vi.mocked(assertModerator).mockReset()
+    vi.mocked(requireUser).mockReset()
+    vi.mocked(insertStatEvent).mockReset()
+    vi.mocked(requireGitHubAccountAge).mockReset()
+    vi.restoreAllMocks()
+  })
+
+  it('add avoids direct skill patch and records stat event', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+    vi.mocked(requireGitHubAccountAge).mockResolvedValue(undefined as never)
+
+    const get = vi.fn().mockResolvedValue({
+      _id: 'skills:1',
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const ctx = { db: { get, insert, patch } } as never
+
+    await addHandler(ctx, { skillId: 'skills:1', body: ' hello ' } as never)
+
+    expect(requireGitHubAccountAge).toHaveBeenCalledWith(ctx, 'users:1')
+    expect(patch).not.toHaveBeenCalled()
+    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
+      skillId: 'skills:1',
+      kind: 'comment',
+    })
+  })
+
+  it('add blocks new comments when github account age gate fails', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:new',
+      user: { _id: 'users:new', role: 'user' },
+    } as never)
+    vi.mocked(requireGitHubAccountAge).mockRejectedValue(
+      new Error('GitHub account must be at least 14 days old to upload skills. Try again in 3 days.'),
+    )
+
+    const get = vi.fn()
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const ctx = { db: { get, insert, patch } } as never
+
+    await expect(addHandler(ctx, { skillId: 'skills:1', body: 'hello' } as never)).rejects.toThrow(
+      /at least 14 days old/i,
+    )
+
+    expect(get).not.toHaveBeenCalled()
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+    expect(insertStatEvent).not.toHaveBeenCalled()
+  })
+
+  it('remove keeps comment soft-delete patch free of updatedAt', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:2',
+      user: { _id: 'users:2', role: 'moderator' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:1',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:1') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const ctx = { db: { get, insert, patch } } as never
+
+    await removeHandler(ctx, { commentId: 'comments:1' } as never)
+
+    expect(patch).toHaveBeenCalledTimes(1)
+    const deletePatch = vi.mocked(patch).mock.calls[0]?.[1] as Record<string, unknown>
+    expect(deletePatch.updatedAt).toBeUndefined()
+    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
+      skillId: 'skills:1',
+      kind: 'uncomment',
+    })
+  })
+
+  it('remove rejects non-owner without moderator permission', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:3',
+      user: { _id: 'users:3', role: 'user' },
+    } as never)
+    vi.mocked(assertModerator).mockImplementation(() => {
+      throw new Error('Moderator role required')
+    })
+
+    const comment = {
+      _id: 'comments:2',
+      skillId: 'skills:2',
+      userId: 'users:9',
+      softDeletedAt: undefined,
+    }
+    const get = vi.fn().mockResolvedValue(comment)
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const ctx = { db: { get, insert, patch } } as never
+
+    await expect(removeHandler(ctx, { commentId: 'comments:2' } as never)).rejects.toThrow(
+      'Moderator role required',
+    )
+    expect(patch).not.toHaveBeenCalled()
+    expect(insertStatEvent).not.toHaveBeenCalled()
+  })
+
+  it('remove no-ops for soft-deleted comment', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:4',
+      user: { _id: 'users:4', role: 'moderator' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:3',
+      skillId: 'skills:3',
+      userId: 'users:4',
+      softDeletedAt: 123,
+    }
+    const get = vi.fn().mockResolvedValue(comment)
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const ctx = { db: { get, insert, patch } } as never
+
+    await removeHandler(ctx, { commentId: 'comments:3' } as never)
+
+    expect(patch).not.toHaveBeenCalled()
+    expect(insert).not.toHaveBeenCalled()
+    expect(insertStatEvent).not.toHaveBeenCalled()
+  })
+
+  it('report increments count and stores reason', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_000)
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:1',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 1,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:1') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table === 'commentReports') {
+        return {
+          withIndex: (index: string) => {
+            if (index === 'by_comment_user') {
+              return { unique: vi.fn().mockResolvedValue(null) }
+            }
+            if (index === 'by_user') {
+              return { collect: vi.fn().mockResolvedValue([]) }
+            }
+            throw new Error(`Unexpected index ${index}`)
+          },
+        }
+      }
+      throw new Error(`Unexpected table ${table}`)
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    const result = await reportHandler(ctx, { commentId: 'comments:1', reason: '  spam  ' } as never)
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false })
+    expect(insert).toHaveBeenCalledWith('commentReports', {
+      commentId: 'comments:1',
+      skillId: 'skills:1',
+      userId: 'users:1',
+      reason: 'spam',
+      createdAt: 1_700_000_000_000,
+    })
+    expect(patch).toHaveBeenCalledWith('comments:1', {
+      reportCount: 2,
+      lastReportedAt: 1_700_000_000_000,
+    })
+    expect(insertStatEvent).not.toHaveBeenCalled()
+  })
+
+  it('report returns alreadyReported for duplicate reporter/comment pair', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:dup',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:dup') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table !== 'commentReports') throw new Error(`Unexpected table ${table}`)
+      return {
+        withIndex: (index: string) => {
+          if (index === 'by_comment_user') {
+            return { unique: vi.fn().mockResolvedValue({ _id: 'commentReports:existing' }) }
+          }
+          throw new Error(`Unexpected index ${index}`)
+        },
+      }
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    const result = await reportHandler(ctx, { commentId: 'comments:dup', reason: 'spam' } as never)
+
+    expect(result).toEqual({ ok: true, reported: false, alreadyReported: true })
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+  })
+
+  it('report rejects empty reason', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:empty',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:empty') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn()
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    await expect(
+      reportHandler(ctx, { commentId: 'comments:empty', reason: '   ' } as never),
+    ).rejects.toThrow('Report reason required.')
+
+    expect(query).not.toHaveBeenCalled()
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+  })
+
+  it('report rejects comment when parent skill is hidden/removed', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:hidden-parent',
+      skillId: 'skills:hidden',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:hidden-parent') return comment
+      if (id === 'skills:hidden') {
+        return { _id: 'skills:hidden', softDeletedAt: 123, moderationStatus: 'removed' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn()
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    await expect(
+      reportHandler(ctx, { commentId: 'comments:hidden-parent', reason: 'abuse' } as never),
+    ).rejects.toThrow('Comment not found')
+
+    expect(query).not.toHaveBeenCalled()
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+  })
+
+  it('report truncates long reason to 500 chars', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_050)
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:long',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:long') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table !== 'commentReports') throw new Error(`Unexpected table ${table}`)
+      return {
+        withIndex: (index: string) => {
+          if (index === 'by_comment_user') return { unique: vi.fn().mockResolvedValue(null) }
+          if (index === 'by_user') return { collect: vi.fn().mockResolvedValue([]) }
+          throw new Error(`Unexpected index ${index}`)
+        },
+      }
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    await reportHandler(ctx, { commentId: 'comments:long', reason: 'x'.repeat(700) } as never)
+
+    const reportInsert = vi.mocked(insert).mock.calls.find((call) => call[0] === 'commentReports')
+    expect(reportInsert?.[1]).toMatchObject({
+      commentId: 'comments:long',
+      reason: 'x'.repeat(500),
+    })
+  })
+
+  it('report active-count filter ignores stale/non-active report targets', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:target2',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const reports = [
+      { _id: 'commentReports:1', commentId: 'comments:deleted', userId: 'users:1', skillId: 'skills:1' },
+      { _id: 'commentReports:2', commentId: 'comments:removed-skill', userId: 'users:1', skillId: 'skills:removed' },
+      { _id: 'commentReports:3', commentId: 'comments:deleted-owner', userId: 'users:1', skillId: 'skills:active' },
+    ]
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:target2') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      if (id === 'comments:deleted') {
+        return { _id: 'comments:deleted', softDeletedAt: 123, skillId: 'skills:1', userId: 'users:2' }
+      }
+      if (id === 'comments:removed-skill') {
+        return {
+          _id: 'comments:removed-skill',
+          softDeletedAt: undefined,
+          skillId: 'skills:removed',
+          userId: 'users:2',
+        }
+      }
+      if (id === 'skills:removed') {
+        return { _id: 'skills:removed', softDeletedAt: undefined, moderationStatus: 'removed' }
+      }
+      if (id === 'comments:deleted-owner') {
+        return {
+          _id: 'comments:deleted-owner',
+          softDeletedAt: undefined,
+          skillId: 'skills:active',
+          userId: 'users:deleted-owner',
+        }
+      }
+      if (id === 'skills:active') {
+        return { _id: 'skills:active', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      if (id === 'users:deleted-owner') {
+        return { _id: 'users:deleted-owner', deletedAt: 1, deactivatedAt: undefined }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table !== 'commentReports') throw new Error(`Unexpected table ${table}`)
+      return {
+        withIndex: (index: string) => {
+          if (index === 'by_comment_user') return { unique: vi.fn().mockResolvedValue(null) }
+          if (index === 'by_user') return { collect: vi.fn().mockResolvedValue(reports) }
+          throw new Error(`Unexpected index ${index}`)
+        },
+      }
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    const result = await reportHandler(
+      ctx,
+      { commentId: 'comments:target2', reason: 'still allowed' } as never,
+    )
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false })
+    expect(insert).toHaveBeenCalledWith(
+      'commentReports',
+      expect.objectContaining({ commentId: 'comments:target2', userId: 'users:1' }),
+    )
+  })
+
+  it('report rejects when active report limit is reached', async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { _id: 'users:1', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:target',
+      skillId: 'skills:1',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 0,
+    }
+    const reportedComment = {
+      _id: 'comments:reported',
+      skillId: 'skills:active',
+      userId: 'users:owner',
+      softDeletedAt: undefined,
+    }
+    const reports = Array.from({ length: 20 }, (_, i) => ({
+      _id: `commentReports:${i + 1}`,
+      commentId: `comments:reported-${i + 1}`,
+      userId: 'users:1',
+      skillId: 'skills:active',
+      createdAt: i + 1,
+    }))
+
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:target') return comment
+      if (id === 'skills:1') {
+        return { _id: 'skills:1', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      if (String(id).startsWith('comments:reported-')) return reportedComment
+      if (id === 'skills:active') {
+        return { _id: 'skills:active', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      if (id === 'users:owner') {
+        return { _id: 'users:owner', deletedAt: undefined, deactivatedAt: undefined }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table === 'commentReports') {
+        return {
+          withIndex: (index: string) => {
+            if (index === 'by_comment_user') {
+              return { unique: vi.fn().mockResolvedValue(null) }
+            }
+            if (index === 'by_user') {
+              return { collect: vi.fn().mockResolvedValue(reports) }
+            }
+            throw new Error(`Unexpected index ${index}`)
+          },
+        }
+      }
+      throw new Error(`Unexpected table ${table}`)
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    await expect(
+      reportHandler(ctx, { commentId: 'comments:target', reason: 'abuse' } as never),
+    ).rejects.toThrow('Report limit reached. Please wait for moderation before reporting more.')
+
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+  })
+
+  it('report auto-hides comment after fourth unique report', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_700_000_000_100)
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: 'users:3',
+      user: { _id: 'users:3', role: 'user' },
+    } as never)
+
+    const comment = {
+      _id: 'comments:4',
+      skillId: 'skills:9',
+      userId: 'users:2',
+      softDeletedAt: undefined,
+      reportCount: 3,
+    }
+    const get = vi.fn(async (id: string) => {
+      if (id === 'comments:4') return comment
+      if (id === 'skills:9') {
+        return { _id: 'skills:9', softDeletedAt: undefined, moderationStatus: 'active' }
+      }
+      return null
+    })
+    const insert = vi.fn()
+    const patch = vi.fn()
+    const query = vi.fn((table: string) => {
+      if (table === 'commentReports') {
+        return {
+          withIndex: (index: string) => {
+            if (index === 'by_comment_user') {
+              return { unique: vi.fn().mockResolvedValue(null) }
+            }
+            if (index === 'by_user') {
+              return { collect: vi.fn().mockResolvedValue([]) }
+            }
+            throw new Error(`Unexpected index ${index}`)
+          },
+        }
+      }
+      throw new Error(`Unexpected table ${table}`)
+    })
+    const ctx = { db: { get, insert, patch, query } } as never
+
+    const result = await reportHandler(ctx, { commentId: 'comments:4', reason: '  hate  ' } as never)
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false })
+    expect(patch).toHaveBeenCalledWith('comments:4', {
+      reportCount: 4,
+      lastReportedAt: 1_700_000_000_100,
+      softDeletedAt: 1_700_000_000_100,
+    })
+    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
+      skillId: 'skills:9',
+      kind: 'uncomment',
+    })
+    expect(insert).toHaveBeenCalledWith('auditLogs', {
+      actorUserId: 'users:3',
+      action: 'comment.auto_hide',
+      targetType: 'comment',
+      targetId: 'comments:4',
+      metadata: { skillId: 'skills:9', reportCount: 4 },
+      createdAt: 1_700_000_000_100,
+    })
+  })
+})
@@ -1,9 +1,8 @@
 import { v } from 'convex/values'
 import type { Doc } from './_generated/dataModel'
 import { mutation, query } from './_generated/server'
-import { assertModerator, requireUser } from './lib/access'
+import { addHandler, removeHandler, reportHandler } from './comments.handlers'
 import { type PublicUser, toPublicUser } from './lib/public'
-import { insertStatEvent } from './skillStatEvents'

 export const listBySkill = query({
  args: { skillId: v.id('skills'), limit: v.optional(v.number()) },
@@ -15,66 +14,29 @@ export const listBySkill = query({
      .order('desc')
      .take(limit)

-    const results: Array<{ comment: Doc<'comments'>; user: PublicUser | null }> = []
-    for (const comment of comments) {
-      if (comment.softDeletedAt) continue
-      const user = toPublicUser(await ctx.db.get(comment.userId))
-      results.push({ comment, user })
-    }
-    return results
+    const rows = await Promise.all(
+      comments.map(async (comment): Promise<{ comment: Doc<'comments'>; user: PublicUser } | null> => {
+        if (comment.softDeletedAt) return null
+        const user = toPublicUser(await ctx.db.get(comment.userId))
+        if (!user) return null
+        return { comment, user }
+      }),
+    )
+    return rows.filter((row): row is { comment: Doc<'comments'>; user: PublicUser } => row !== null)
  },
 })

 export const add = mutation({
  args: { skillId: v.id('skills'), body: v.string() },
-  handler: async (ctx, args) => {
-    const { userId } = await requireUser(ctx)
-    const body = args.body.trim()
-    if (!body) throw new Error('Comment body required')
-
-    const skill = await ctx.db.get(args.skillId)
-    if (!skill) throw new Error('Skill not found')
-
-    await ctx.db.insert('comments', {
-      skillId: args.skillId,
-      userId,
-      body,
-      createdAt: Date.now(),
-      softDeletedAt: undefined,
-      deletedBy: undefined,
-    })
-
-    await insertStatEvent(ctx, { skillId: skill._id, kind: 'comment' })
-  },
+  handler: addHandler,
 })

 export const remove = mutation({
  args: { commentId: v.id('comments') },
-  handler: async (ctx, args) => {
-    const { user } = await requireUser(ctx)
-    const comment = await ctx.db.get(args.commentId)
-    if (!comment) throw new Error('Comment not found')
-    if (comment.softDeletedAt) return
+  handler: removeHandler,
+})

-    const isOwner = comment.userId === user._id
-    if (!isOwner) {
-      assertModerator(user)
-    }
-
-    await ctx.db.patch(comment._id, {
-      softDeletedAt: Date.now(),
-      deletedBy: user._id,
-    })
-
-    await insertStatEvent(ctx, { skillId: comment.skillId, kind: 'uncomment' })
-
-    await ctx.db.insert('auditLogs', {
-      actorUserId: user._id,
-      action: 'comment.delete',
-      targetType: 'comment',
-      targetId: comment._id,
-      metadata: { skillId: comment.skillId },
-      createdAt: Date.now(),
-    })
-  },
+export const report = mutation({
+  args: { commentId: v.id('comments'), reason: v.string() },
+  handler: reportHandler,
 })
@@ -19,11 +19,13 @@ crons.interval(

 crons.interval(
  'skill-stats-backfill',
-  { minutes: 10 },
+  { hours: 6 },
  internal.statsMaintenance.runSkillStatBackfillInternal,
  { batchSize: 200, maxBatches: 5 },
 )

+// Runs frequently to keep dailyStats/trending accurate,
+// but does NOT patch skill documents (only writes to skillDailyStats).
 crons.interval(
  'skill-stat-events',
  { minutes: 15 },
@@ -31,6 +33,23 @@ crons.interval(
  {},
 )

+// Syncs accumulated stat deltas to skill documents every 6 hours.
+// Runs infrequently to avoid thundering-herd reactive query invalidation.
+// Uses processedAt field to track progress (independent of the action cursor).
+crons.interval(
+  'skill-doc-stat-sync',
+  { hours: 6 },
+  internal.skillStatEvents.processSkillStatEventsInternal,
+  { batchSize: 500 },
+)
+
+crons.interval(
+  'global-stats-update',
+  { minutes: 60 },
+  internal.statsMaintenance.updateGlobalStatsInternal,
+  {},
+)
+
 crons.interval('vt-pending-scans', { minutes: 5 }, internal.vt.pollPendingScans, { batchSize: 100 })

 crons.interval('vt-cache-backfill', { minutes: 30 }, internal.vt.backfillActiveSkillsVTCache, {
@@ -40,4 +59,11 @@ crons.interval('vt-cache-backfill', { minutes: 30 }, internal.vt.backfillActiveS
 // Daily re-scan of all active skills at 3am UTC
 crons.daily('vt-daily-rescan', { hourUTC: 3, minuteUTC: 0 }, internal.vt.rescanActiveSkills, {})

+crons.interval(
+  'download-dedupe-prune',
+  { hours: 24 },
+  internal.downloads.pruneDownloadDedupesInternal,
+  {},
+)
+
 export default crons
@@ -435,6 +435,7 @@ export const seedSkillMutation = internalMutation({
      visibility: 'latest-approved',
      updatedAt: now,
    })
+    await ctx.db.insert('embeddingSkillMap', { embeddingId, skillId })

    await ctx.db.patch(skillId, {
      latestVersionId: versionId,
@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { __test } from './downloads'
+
+describe('downloads helpers', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  it('calculates hour start boundaries', () => {
+    const hour = 3_600_000
+    expect(__test.getHourStart(0)).toBe(0)
+    expect(__test.getHourStart(hour - 1)).toBe(0)
+    expect(__test.getHourStart(hour)).toBe(hour)
+    expect(__test.getHourStart(hour + 1)).toBe(hour)
+  })
+
+  it('prefers user identity when token user exists', () => {
+    const request = new Request('https://example.com', {
+      headers: { 'cf-connecting-ip': '1.2.3.4' },
+    })
+    expect(__test.getDownloadIdentityValue(request, 'users_123')).toBe('user:users_123')
+  })
+
+  it('uses cf-connecting-ip for anonymous identity', () => {
+    const request = new Request('https://example.com', {
+      headers: { 'cf-connecting-ip': '1.2.3.4' },
+    })
+    expect(__test.getDownloadIdentityValue(request, null)).toBe('ip:1.2.3.4')
+  })
+
+  it('falls back to forwarded ip when explicitly enabled', () => {
+    vi.stubEnv('TRUST_FORWARDED_IPS', 'true')
+    const request = new Request('https://example.com', {
+      headers: { 'x-forwarded-for': '10.0.0.1, 10.0.0.2' },
+    })
+    expect(__test.getDownloadIdentityValue(request, null)).toBe('ip:10.0.0.1')
+  })
+
+  it('returns null when user and ip are missing', () => {
+    const request = new Request('https://example.com')
+    expect(__test.getDownloadIdentityValue(request, null)).toBeNull()
+  })
+})
@@ -1,9 +1,18 @@
 import { v } from 'convex/values'
-import { api } from './_generated/api'
-import { httpAction, mutation } from './_generated/server'
+import { api, internal } from './_generated/api'
+import { httpAction, internalMutation, mutation } from './_generated/server'
+import { getOptionalApiTokenUserId } from './lib/apiTokenAuth'
+import { applyRateLimit, getClientIp } from './lib/httpRateLimit'
+import { corsHeaders, mergeHeaders } from './lib/httpHeaders'
 import { buildDeterministicZip } from './lib/skillZip'
+import { hashToken } from './lib/tokens'
 import { insertStatEvent } from './skillStatEvents'

+const HOUR_MS = 3_600_000
+const DEDUPE_RETENTION_MS = 7 * 24 * HOUR_MS
+const PRUNE_BATCH_SIZE = 200
+const PRUNE_MAX_BATCHES = 50
+
 export const downloadZip = httpAction(async (ctx, request) => {
  const url = new URL(request.url)
  const slug = url.searchParams.get('slug')?.trim().toLowerCase()
@@ -11,33 +20,54 @@ export const downloadZip = httpAction(async (ctx, request) => {
  const tagParam = url.searchParams.get('tag')?.trim()

  if (!slug) {
-    return new Response('Missing slug', { status: 400 })
+    return new Response('Missing slug', {
+      status: 400,
+      headers: corsHeaders(),
+    })
  }

+  const rate = await applyRateLimit(ctx, request, 'download')
+  if (!rate.ok) return rate.response
+
  const skillResult = await ctx.runQuery(api.skills.getBySlug, { slug })
  if (!skillResult?.skill) {
-    return new Response('Skill not found', { status: 404 })
+    return new Response('Skill not found', {
+      status: 404,
+      headers: mergeHeaders(rate.headers, corsHeaders()),
+    })
  }

-  // Block downloads based on moderation status
+  // Block downloads based on moderation status.
  const mod = skillResult.moderationInfo
  if (mod?.isMalwareBlocked) {
    return new Response(
      'Blocked: this skill has been flagged as malicious by VirusTotal and cannot be downloaded.',
-      { status: 403 },
+      {
+        status: 403,
+        headers: mergeHeaders(rate.headers, corsHeaders()),
+      },
    )
  }
  if (mod?.isPendingScan) {
    return new Response(
      'This skill is pending a security scan by VirusTotal. Please try again in a few minutes.',
-      { status: 423 },
+      {
+        status: 423,
+        headers: mergeHeaders(rate.headers, corsHeaders()),
+      },
    )
  }
  if (mod?.isRemoved) {
-    return new Response('This skill has been removed by a moderator.', { status: 410 })
+    return new Response('This skill has been removed by a moderator.', {
+      status: 410,
+      headers: mergeHeaders(rate.headers, corsHeaders()),
+    })
  }
  if (mod?.isHiddenByMod) {
-    return new Response('This skill is currently unavailable.', { status: 403 })
+    return new Response('This skill is currently unavailable.', {
+      status: 403,
+      headers: mergeHeaders(rate.headers, corsHeaders()),
+    })
  }

  const skill = skillResult.skill
@@ -56,10 +86,16 @@ export const downloadZip = httpAction(async (ctx, request) => {
  }

  if (!version) {
-    return new Response('Version not found', { status: 404 })
+    return new Response('Version not found', {
+      status: 404,
+      headers: mergeHeaders(rate.headers, corsHeaders()),
+    })
  }
  if (version.softDeletedAt) {
-    return new Response('Version not available', { status: 410 })
+    return new Response('Version not available', {
+      status: 410,
+      headers: mergeHeaders(rate.headers, corsHeaders()),
+    })
  }

  const entries: Array<{ path: string; bytes: Uint8Array }> = []
@@ -77,15 +113,31 @@ export const downloadZip = httpAction(async (ctx, request) => {
  })
  const zipBlob = new Blob([zipArray], { type: 'application/zip' })

-  await ctx.runMutation(api.downloads.increment, { skillId: skill._id })
+  try {
+    const userId = await getOptionalApiTokenUserId(ctx, request)
+    const identity = getDownloadIdentityValue(request, userId ? String(userId) : null)
+    if (identity) {
+      await ctx.runMutation(internal.downloads.recordDownloadInternal, {
+        skillId: skill._id,
+        identityHash: await hashToken(identity),
+        hourStart: getHourStart(Date.now()),
+      })
+    }
+  } catch {
+    // Best-effort metric path; do not fail downloads.
+  }

  return new Response(zipBlob, {
    status: 200,
-    headers: {
-      'Content-Type': 'application/zip',
-      'Content-Disposition': `attachment; filename="${slug}-${version.version}.zip"`,
-      'Cache-Control': 'private, max-age=60',
-    },
+    headers: mergeHeaders(
+      rate.headers,
+      {
+        'Content-Type': 'application/zip',
+        'Content-Disposition': `attachment; filename="${slug}-${version.version}.zip"`,
+        'Cache-Control': 'private, max-age=60',
+      },
+      corsHeaders(),
+    ),
  })
 })

@@ -101,3 +153,73 @@ export const increment = mutation({
    })
  },
 })
+
+export const recordDownloadInternal = internalMutation({
+  args: {
+    skillId: v.id('skills'),
+    identityHash: v.string(),
+    hourStart: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query('downloadDedupes')
+      .withIndex('by_skill_identity_hour', (q) =>
+        q
+          .eq('skillId', args.skillId)
+          .eq('identityHash', args.identityHash)
+          .eq('hourStart', args.hourStart),
+      )
+      .unique()
+    if (existing) return
+
+    await ctx.db.insert('downloadDedupes', {
+      skillId: args.skillId,
+      identityHash: args.identityHash,
+      hourStart: args.hourStart,
+      createdAt: Date.now(),
+    })
+
+    await insertStatEvent(ctx, {
+      skillId: args.skillId,
+      kind: 'download',
+    })
+  },
+})
+
+export const pruneDownloadDedupesInternal = internalMutation({
+  args: {},
+  handler: async (ctx) => {
+    const cutoff = Date.now() - DEDUPE_RETENTION_MS
+
+    for (let batches = 0; batches < PRUNE_MAX_BATCHES; batches += 1) {
+      const stale = await ctx.db
+        .query('downloadDedupes')
+        .withIndex('by_hour', (q) => q.lt('hourStart', cutoff))
+        .take(PRUNE_BATCH_SIZE)
+
+      if (stale.length === 0) break
+
+      for (const entry of stale) {
+        await ctx.db.delete(entry._id)
+      }
+
+      if (stale.length < PRUNE_BATCH_SIZE) break
+    }
+  },
+})
+
+export function getHourStart(timestamp: number) {
+  return Math.floor(timestamp / HOUR_MS) * HOUR_MS
+}
+
+export function getDownloadIdentityValue(request: Request, userId: string | null) {
+  if (userId) return `user:${userId}`
+  const ip = getClientIp(request)
+  if (!ip) return null
+  return `ip:${ip}`
+}
+
+export const __test = {
+  getHourStart,
+  getDownloadIdentityValue,
+}
@@ -39,6 +39,7 @@ export type SyncGitHubBackupsResult = {
    skillsScanned: number
    skillsSkipped: number
    skillsBackedUp: number
+    skillsDeleted: number
    skillsMissingVersion: number
    skillsMissingOwner: number
    errors: number
@@ -78,7 +79,7 @@ export const getGitHubBackupPageInternal = internalQuery({
      }

      const owner = await ctx.db.get(skill.ownerUserId)
-      if (!owner || owner.deletedAt) {
+      if (!owner || owner.deletedAt || owner.deactivatedAt) {
        items.push({ kind: 'missingOwner', skillId: skill._id, ownerUserId: skill.ownerUserId })
        continue
      }
@@ -7,9 +7,12 @@ import type { ActionCtx } from './_generated/server'
 import { internalAction } from './_generated/server'
 import {
  backupSkillToGitHub,
+  deleteGitHubSkillBackup,
  fetchGitHubSkillMeta,
  getGitHubBackupContext,
  isGitHubBackupConfigured,
+  listGitHubSkillBackupEntries,
+  normalizeOwner,
 } from './lib/githubBackup'

 const DEFAULT_BATCH_SIZE = 50
@@ -35,6 +38,7 @@ export type GitHubBackupSyncStats = {
  skillsScanned: number
  skillsSkipped: number
  skillsBackedUp: number
+  skillsDeleted: number
  skillsMissingVersion: number
  skillsMissingOwner: number
  errors: number
@@ -87,6 +91,7 @@ export async function syncGitHubBackupsInternalHandler(
    skillsScanned: 0,
    skillsSkipped: 0,
    skillsBackedUp: 0,
+    skillsDeleted: 0,
    skillsMissingVersion: 0,
    skillsMissingOwner: 0,
    errors: 0,
@@ -166,9 +171,69 @@ export async function syncGitHubBackupsInternalHandler(
    if (isDone) break
  }

+  await pruneDeletedSkillBackups(ctx, context, dryRun, stats)
+
  return { stats, cursor, isDone }
 }

+async function pruneDeletedSkillBackups(
+  ctx: ActionCtx,
+  context: Awaited<ReturnType<typeof getGitHubBackupContext>>,
+  dryRun: boolean,
+  stats: GitHubBackupSyncStats,
+) {
+  let entries: Awaited<ReturnType<typeof listGitHubSkillBackupEntries>>
+  try {
+    entries = await listGitHubSkillBackupEntries(context)
+  } catch (error) {
+    console.error('GitHub backup cleanup list failed', error)
+    stats.errors += 1
+    return
+  }
+
+  for (const entry of entries) {
+    try {
+      const skill = (await ctx.runQuery(internal.skills.getSkillBySlugInternal, {
+        slug: entry.slug,
+      })) as Doc<'skills'> | null
+      if (!skill || skill.softDeletedAt) {
+        await deleteBackupIfNeeded(context, entry, dryRun, stats)
+        continue
+      }
+
+      const owner = (await ctx.runQuery(internal.users.getByIdInternal, {
+        userId: skill.ownerUserId,
+      })) as Doc<'users'> | null
+      if (!owner || owner.deletedAt || owner.deactivatedAt) {
+        await deleteBackupIfNeeded(context, entry, dryRun, stats)
+        continue
+      }
+
+      const ownerHandle = normalizeOwner(owner.handle ?? owner._id)
+      if (ownerHandle !== entry.owner) {
+        await deleteBackupIfNeeded(context, entry, dryRun, stats)
+      }
+    } catch (error) {
+      console.error('GitHub backup cleanup failed', error)
+      stats.errors += 1
+    }
+  }
+}
+
+async function deleteBackupIfNeeded(
+  context: Awaited<ReturnType<typeof getGitHubBackupContext>>,
+  entry: Awaited<ReturnType<typeof listGitHubSkillBackupEntries>>[number],
+  dryRun: boolean,
+  stats: GitHubBackupSyncStats,
+) {
+  const result = dryRun
+    ? { deleted: true as const }
+    : await deleteGitHubSkillBackup(context, entry.owner, entry.slug)
+  if (result.deleted) {
+    stats.skillsDeleted += 1
+  }
+}
+
 export const syncGitHubBackupsInternal = internalAction({
  args: {
    dryRun: v.optional(v.boolean()),
@@ -0,0 +1,9 @@
+import { v } from 'convex/values'
+import { internalQuery } from './_generated/server'
+import { getGitHubProviderAccountId } from './lib/githubIdentity'
+
+export const getGitHubProviderAccountIdInternal = internalQuery({
+  args: { userId: v.id('users') },
+  handler: async (ctx, args) => getGitHubProviderAccountId(ctx, args.userId),
+})
+
@@ -0,0 +1,36 @@
+/* @vitest-environment node */
+import { describe, expect, it } from 'vitest'
+import { __test } from './githubImport'
+import { buildGitHubZipForTests } from './lib/githubImport'
+
+describe('githubImport', () => {
+  it('formats storage failure message with file context', () => {
+    const message = __test.buildStoreFailureMessage('skill/SKILL.md', 123, new Error('disk full'))
+    expect(message).toBe('Failed to store file "skill/SKILL.md" (123 bytes). disk full')
+  })
+
+  it('formats publish failure message with fallback text', () => {
+    expect(__test.buildPublishFailureMessage(new Error('slug exists'))).toBe(
+      'Import failed during publish: slug exists. Check skill format, slug availability, and try again.',
+    )
+    expect(__test.buildPublishFailureMessage('unexpected')).toBe(
+      'Import failed during publish: unexpected. Check skill format, slug availability, and try again.',
+    )
+  })
+
+  it('filters mac junk files while unzipping archive entries', () => {
+    const zip = buildGitHubZipForTests({
+      'demo-repo/skill/SKILL.md': '# Demo',
+      'demo-repo/skill/notes.md': 'notes',
+      'demo-repo/skill/.DS_Store': 'junk',
+      'demo-repo/skill/._notes.md': 'junk',
+      'demo-repo/__MACOSX/._SKILL.md': 'junk',
+    })
+
+    const entries = __test.unzipToEntries(zip)
+    expect(Object.keys(entries).sort()).toEqual([
+      'demo-repo/skill/SKILL.md',
+      'demo-repo/skill/notes.md',
+    ])
+  })
+})
@@ -20,7 +20,7 @@ import {
  suggestVersion,
 } from './lib/githubImport'
 import { publishVersionForUser } from './lib/skillPublish'
-import { sanitizePath } from './lib/skills'
+import { isMacJunkPath, sanitizePath } from './lib/skills'

 const MAX_SELECTED_BYTES = 50 * 1024 * 1024
 const MAX_UNZIPPED_BYTES = 80 * 1024 * 1024
@@ -192,7 +192,12 @@ export const importGitHubSkill = action({

      const sha256 = await sha256Hex(bytes)
      const safeBytes = new Uint8Array(bytes)
-      const storageId = await ctx.storage.store(new Blob([safeBytes], { type: 'text/plain' }))
+      let storageId: Id<'_storage'>
+      try {
+        storageId = await ctx.storage.store(new Blob([safeBytes], { type: 'text/plain' }))
+      } catch (error) {
+        throw new ConvexError(buildStoreFailureMessage(sanitized, bytes.byteLength, error))
+      }
      storedFiles.push({
        path: sanitized,
        size: bytes.byteLength,
@@ -213,23 +218,28 @@ export const importGitHubSkill = action({
    if (!displayName) throw new ConvexError('Display name required')
    if (!version || !semver.valid(version)) throw new ConvexError('Version must be valid semver')

-    const result = await publishVersionForUser(ctx, userId, {
-      slug: slugBase,
-      displayName,
-      version,
-      changelog: '',
-      tags,
-      files: storedFiles,
-      source: {
-        kind: 'github',
-        url: resolved.originalUrl,
-        repo: `${resolved.owner}/${resolved.repo}`,
-        ref: resolved.ref,
-        commit: resolved.commit,
-        path: candidate.path,
-        importedAt: Date.now(),
-      },
-    })
+    let result: Awaited<ReturnType<typeof publishVersionForUser>>
+    try {
+      result = await publishVersionForUser(ctx, userId, {
+        slug: slugBase,
+        displayName,
+        version,
+        changelog: '',
+        tags,
+        files: storedFiles,
+        source: {
+          kind: 'github',
+          url: resolved.originalUrl,
+          repo: `${resolved.owner}/${resolved.repo}`,
+          ref: resolved.ref,
+          commit: resolved.commit,
+          path: candidate.path,
+          importedAt: Date.now(),
+        },
+      })
+    } catch (error) {
+      throw new ConvexError(buildPublishFailureMessage(error))
+    }

    return { ok: true, slug: slugBase, version, ...result }
  },
@@ -244,7 +254,7 @@ function unzipToEntries(zipBytes: Uint8Array) {
  for (const [rawPath, bytes] of Object.entries(entries)) {
    const normalizedPath = normalizeZipPath(rawPath)
    if (!normalizedPath) continue
-    if (isJunkPath(normalizedPath)) continue
+    if (isMacJunkPath(normalizedPath)) continue
    if (!bytes) continue
    if (bytes.byteLength > MAX_SINGLE_FILE_BYTES) continue
    totalBytes += bytes.byteLength
@@ -308,10 +318,20 @@ function normalizeZipPath(path: string) {
  return normalized
 }

-function isJunkPath(path: string) {
-  const normalized = path.toLowerCase()
-  if (normalized.startsWith('__macosx/')) return true
-  if (normalized.endsWith('/.ds_store')) return true
-  if (normalized === '.ds_store') return true
-  return false
+function toErrorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function buildStoreFailureMessage(path: string, sizeBytes: number, error: unknown) {
+  return `Failed to store file "${path}" (${sizeBytes} bytes). ${toErrorMessage(error)}`
+}
+
+function buildPublishFailureMessage(error: unknown) {
+  return `Import failed during publish: ${toErrorMessage(error)}. Check skill format, slug availability, and try again.`
+}
+
+export const __test = {
+  buildPublishFailureMessage,
+  buildStoreFailureMessage,
+  unzipToEntries,
 }
@@ -0,0 +1,216 @@
+'use node'
+
+import { v } from 'convex/values'
+import { internal } from './_generated/api'
+import type { Doc, Id } from './_generated/dataModel'
+import { internalAction } from './_generated/server'
+import {
+  fetchGitHubSkillMeta,
+  getGitHubBackupContext,
+  isGitHubBackupConfigured,
+} from './lib/githubBackup'
+import { assertAdmin } from './lib/access'
+import {
+  listGitHubBackupFiles,
+  readGitHubBackupFile,
+} from './lib/githubRestoreHelpers'
+import { publishVersionForUser } from './lib/skillPublish'
+import { guessContentTypeForPath } from './lib/contentTypes'
+
+type RestoreResult = {
+  slug: string
+  status: 'restored' | 'slug_conflict' | 'already_exists' | 'no_backup' | 'error'
+  detail?: string
+}
+
+type BulkRestoreResult = {
+  results: RestoreResult[]
+  totalRestored: number
+  totalConflicts: number
+  totalSkipped: number
+  totalErrors: number
+}
+
+/**
+ * Admin-only: restore a single skill from GitHub backup.
+ * Reads the backup files from the GitHub repo and re-creates the skill in the database.
+ */
+export const restoreSkillFromBackup = internalAction({
+  args: {
+    actorUserId: v.id('users'),
+    ownerHandle: v.string(),
+    ownerUserId: v.id('users'),
+    slug: v.string(),
+    forceOverwriteSquatter: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<RestoreResult> => {
+    try {
+      const actor = await ctx.runQuery(internal.users.getByIdInternal, {
+        userId: args.actorUserId,
+      })
+      if (!actor || actor.deletedAt || actor.deactivatedAt) {
+        return { slug: args.slug, status: 'error', detail: 'Actor not found' }
+      }
+      assertAdmin(actor as Doc<'users'>)
+
+      if (!isGitHubBackupConfigured()) {
+        return { slug: args.slug, status: 'error', detail: 'GitHub backup not configured' }
+      }
+
+      const ghContext = await getGitHubBackupContext()
+
+      // Check if skill already exists in the DB
+      const existingSkill = (await ctx.runQuery(internal.skills.getSkillBySlugInternal, {
+        slug: args.slug,
+      })) as Doc<'skills'> | null
+
+      if (existingSkill) {
+        if (existingSkill.ownerUserId === args.ownerUserId) {
+          return { slug: args.slug, status: 'already_exists', detail: 'Skill already owned by user' }
+        }
+
+        if (!args.forceOverwriteSquatter) {
+          return {
+            slug: args.slug,
+            status: 'slug_conflict',
+            detail: `Slug occupied by another user. Set forceOverwriteSquatter=true to reclaim.`,
+          }
+        }
+
+        // Free the slug in-transaction by renaming the squatter, then enqueue cleanup.
+        await ctx.runMutation(internal.githubRestoreMutations.evictSquatterSkillForRestoreInternal, {
+          actorUserId: args.actorUserId,
+          slug: args.slug,
+          rightfulOwnerUserId: args.ownerUserId,
+        })
+      }
+
+      // Fetch metadata from GitHub backup
+      const meta = await fetchGitHubSkillMeta(ghContext, args.ownerHandle, args.slug)
+      if (!meta) {
+        return { slug: args.slug, status: 'no_backup', detail: 'No backup found in GitHub repo' }
+      }
+
+      // Read the actual files from the backup
+      const backupFiles = await listGitHubBackupFiles(ghContext, args.ownerHandle, args.slug)
+      if (backupFiles.length === 0) {
+        return { slug: args.slug, status: 'no_backup', detail: 'Backup has no files' }
+      }
+
+      // Download and store each file in Convex storage
+      const storedFiles: Array<{
+        path: string
+        size: number
+        storageId: Id<'_storage'>
+        sha256: string
+        contentType: string
+      }> = []
+
+      for (const filePath of backupFiles) {
+        const fileContent = await readGitHubBackupFile(ghContext, args.ownerHandle, args.slug, filePath)
+        if (!fileContent) continue
+
+        const sha256 = await sha256Hex(fileContent)
+        const contentType = guessContentTypeForPath(filePath)
+        const blob = new Blob([Buffer.from(fileContent)], { type: contentType })
+        const storageId = await ctx.storage.store(blob)
+
+        storedFiles.push({
+          path: filePath,
+          size: fileContent.byteLength,
+          storageId,
+          sha256,
+          contentType,
+        })
+      }
+
+      if (storedFiles.length === 0) {
+        return { slug: args.slug, status: 'error', detail: 'Could not download any backup files' }
+      }
+
+      await publishVersionForUser(
+        ctx,
+        args.ownerUserId,
+        {
+          slug: args.slug,
+          displayName: meta.displayName,
+          version: meta.latest.version,
+          changelog: 'Restored from GitHub backup',
+          files: storedFiles,
+        },
+        {
+          bypassGitHubAccountAge: true,
+          bypassNewSkillRateLimit: true,
+          bypassQualityGate: true,
+          skipBackup: true,
+          skipWebhook: true,
+        },
+      )
+
+      return { slug: args.slug, status: 'restored' }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error'
+      console.error(`[restore] Failed to restore ${args.slug}:`, message)
+      return { slug: args.slug, status: 'error', detail: message }
+    }
+  },
+})
+
+/**
+ * Admin-only: bulk restore all skills for a user from GitHub backup.
+ */
+export const restoreUserSkillsFromBackup = internalAction({
+  args: {
+    actorUserId: v.id('users'),
+    ownerHandle: v.string(),
+    ownerUserId: v.id('users'),
+    slugs: v.array(v.string()),
+    forceOverwriteSquatter: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<BulkRestoreResult> => {
+    const results: RestoreResult[] = []
+    let totalRestored = 0
+    let totalConflicts = 0
+    let totalSkipped = 0
+    let totalErrors = 0
+
+    for (const slug of args.slugs) {
+      const result = (await ctx.runAction(internal.githubRestore.restoreSkillFromBackup, {
+        actorUserId: args.actorUserId,
+        ownerHandle: args.ownerHandle,
+        ownerUserId: args.ownerUserId,
+        slug,
+        forceOverwriteSquatter: args.forceOverwriteSquatter,
+      })) as RestoreResult
+
+      results.push(result)
+
+      switch (result.status) {
+        case 'restored':
+          totalRestored += 1
+          break
+        case 'slug_conflict':
+          totalConflicts += 1
+          break
+        case 'already_exists':
+        case 'no_backup':
+          totalSkipped += 1
+          break
+        case 'error':
+          totalErrors += 1
+          break
+      }
+    }
+
+    return { results, totalRestored, totalConflicts, totalSkipped, totalErrors }
+  },
+})
+
+async function sha256Hex(bytes: Uint8Array) {
+  const { createHash } = await import('node:crypto')
+  const hash = createHash('sha256')
+  hash.update(bytes)
+  return hash.digest('hex')
+}
+
+// guessContentTypeForPath in lib/contentTypes.ts
@@ -0,0 +1,84 @@
+import { v } from 'convex/values'
+import { internal } from './_generated/api'
+import { internalMutation } from './_generated/server'
+import { assertAdmin } from './lib/access'
+
+export const evictSquatterSkillForRestoreInternal = internalMutation({
+  args: {
+    actorUserId: v.id('users'),
+    slug: v.string(),
+    rightfulOwnerUserId: v.id('users'),
+  },
+  handler: async (ctx, args) => {
+    const actor = await ctx.db.get(args.actorUserId)
+    if (!actor || actor.deletedAt || actor.deactivatedAt) throw new Error('Actor not found')
+    assertAdmin(actor)
+
+    const slug = args.slug.trim().toLowerCase()
+    if (!slug) throw new Error('Slug required')
+
+    const now = Date.now()
+
+    const existingSkill = await ctx.db
+      .query('skills')
+      .withIndex('by_slug', (q) => q.eq('slug', slug))
+      .unique()
+    if (!existingSkill) return { ok: true as const, action: 'noop' as const }
+    if (existingSkill.ownerUserId === args.rightfulOwnerUserId) {
+      return { ok: true as const, action: 'already_owned' as const }
+    }
+
+    const evictedSlug = buildEvictedSlug(slug, now)
+
+    // Free the slug immediately (same transaction) by renaming the squatter's skill.
+    await ctx.db.patch(existingSkill._id, {
+      slug: evictedSlug,
+      softDeletedAt: now,
+      hiddenAt: existingSkill.hiddenAt ?? now,
+      hiddenBy: existingSkill.hiddenBy ?? actor._id,
+      updatedAt: now,
+    })
+
+    // Remove from vector search ASAP.
+    const embeddings = await ctx.db
+      .query('skillEmbeddings')
+      .withIndex('by_skill', (q) => q.eq('skillId', existingSkill._id))
+      .collect()
+    for (const embedding of embeddings) {
+      await ctx.db.patch(embedding._id, {
+        visibility: 'deleted',
+        updatedAt: now,
+      })
+    }
+
+    // Cleanup the rest asynchronously (versions, fingerprints, installs, etc.)
+    await ctx.scheduler.runAfter(0, internal.skills.hardDeleteInternal, {
+      skillId: existingSkill._id,
+      actorUserId: actor._id,
+      phase: 'versions',
+    })
+
+    await ctx.db.insert('auditLogs', {
+      actorUserId: actor._id,
+      action: 'slug.reclaim.sync',
+      targetType: 'skill',
+      targetId: existingSkill._id,
+      metadata: {
+        slug,
+        evictedSlug,
+        squatterUserId: existingSkill.ownerUserId,
+        rightfulOwnerUserId: args.rightfulOwnerUserId,
+        reason: 'Synchronous eviction during GitHub restore',
+      },
+      createdAt: now,
+    })
+
+    return { ok: true as const, action: 'evicted' as const, evictedSlug }
+  },
+})
+
+function buildEvictedSlug(slug: string, now: number) {
+  const suffix = now.toString(36)
+  return `${slug}-evicted-${suffix}`
+}
+
@@ -78,7 +78,7 @@ export const getGitHubSoulBackupPageInternal = internalQuery({
      }

      const owner = await ctx.db.get(soul.ownerUserId)
-      if (!owner || owner.deletedAt) {
+      if (!owner || owner.deletedAt || owner.deactivatedAt) {
        items.push({ kind: 'missingOwner', soulId: soul._id, ownerUserId: soul.ownerUserId })
        continue
      }
@@ -32,6 +32,7 @@ import {
  usersPostRouterV1Http,
  whoamiV1Http,
 } from './httpApiV1'
+import { preflightHandler } from './httpPreflight'

 const http = httpRouter()

@@ -145,6 +146,12 @@ http.route({
  handler: soulsDeleteRouterV1Http,
 })

+http.route({
+  pathPrefix: '/api/',
+  method: 'OPTIONS',
+  handler: preflightHandler,
+})
+
 // TODO: remove legacy /api routes after deprecation window.
 http.route({
  path: LegacyApiRoutes.download,
@@ -11,6 +11,7 @@ import type { Id } from './_generated/dataModel'
 import type { ActionCtx } from './_generated/server'
 import { httpAction } from './_generated/server'
 import { requireApiTokenUser } from './lib/apiTokenAuth'
+import { corsHeaders, mergeHeaders } from './lib/httpHeaders'
 import { publishVersionForUser } from './skills'

 type SearchSkillEntry = {
@@ -241,20 +242,26 @@ export const cliTelemetrySyncHttp = httpAction(cliTelemetrySyncHandler)
 function json(value: unknown, status = 200) {
  return new Response(JSON.stringify(value), {
    status,
-    headers: {
-      'Content-Type': 'application/json',
-      'Cache-Control': 'no-store',
-    },
+    headers: mergeHeaders(
+      {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+      },
+      corsHeaders(),
+    ),
  })
 }

 function text(value: string, status: number) {
  return new Response(value, {
    status,
-    headers: {
-      'Content-Type': 'text/plain; charset=utf-8',
-      'Cache-Control': 'no-store',
-    },
+    headers: mergeHeaders(
+      {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'no-store',
+      },
+      corsHeaders(),
+    ),
  })
 }

@@ -3,13 +3,14 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'

 vi.mock('./lib/apiTokenAuth', () => ({
  requireApiTokenUser: vi.fn(),
+  getOptionalApiTokenUserId: vi.fn(),
 }))

 vi.mock('./skills', () => ({
  publishVersionForUser: vi.fn(),
 }))

-const { requireApiTokenUser } = await import('./lib/apiTokenAuth')
+const { getOptionalApiTokenUserId, requireApiTokenUser } = await import('./lib/apiTokenAuth')
 const { publishVersionForUser } = await import('./skills')
 const { __handlers } = await import('./httpApiV1')

@@ -27,6 +28,12 @@ function isRateLimitArgs(args: unknown): args is RateLimitArgs {
  )
 }

+function hasSlugArgs(args: unknown): args is { slug: string } {
+  if (!args || typeof args !== 'object') return false
+  const value = args as Record<string, unknown>
+  return typeof value.slug === 'string'
+}
+
 function makeCtx(partial: Record<string, unknown>) {
  const partialRunQuery =
    typeof partial.runQuery === 'function'
@@ -59,6 +66,8 @@ const blockedRate = () => ({
 })

 beforeEach(() => {
+  vi.mocked(getOptionalApiTokenUserId).mockReset()
+  vi.mocked(getOptionalApiTokenUserId).mockResolvedValue(null)
  vi.mocked(requireApiTokenUser).mockReset()
  vi.mocked(publishVersionForUser).mockReset()
 })
@@ -78,6 +87,124 @@ describe('httpApiV1 handlers', () => {
    expect(runAction).not.toHaveBeenCalled()
  })

+  it('users/restore forbids non-admin api tokens', async () => {
+    const runQuery = vi.fn()
+    const runAction = vi.fn()
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:actor',
+      user: { _id: 'users:actor', role: 'user' },
+    } as never)
+
+    const response = await __handlers.usersPostRouterV1Handler(
+      makeCtx({ runQuery, runAction, runMutation }),
+      new Request('https://example.com/api/v1/users/restore', {
+        method: 'POST',
+        body: JSON.stringify({ handle: 'target', slugs: ['a'] }),
+      }),
+    )
+    expect(response.status).toBe(403)
+    expect(runQuery).not.toHaveBeenCalled()
+    expect(runAction).not.toHaveBeenCalled()
+  })
+
+  it('users/restore calls restore action for admin', async () => {
+    const runAction = vi.fn().mockResolvedValue({ ok: true, totalRestored: 1, results: [] })
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if (isRateLimitArgs(args)) return okRate()
+      return { ok: true }
+    })
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('handle' in args) return { _id: 'users:target' }
+      return null
+    })
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:admin',
+      user: { _id: 'users:admin', role: 'admin' },
+    } as never)
+
+    const response = await __handlers.usersPostRouterV1Handler(
+      makeCtx({ runQuery, runAction, runMutation }),
+      new Request('https://example.com/api/v1/users/restore', {
+        method: 'POST',
+        body: JSON.stringify({
+          handle: 'Target',
+          slugs: ['a', 'b'],
+          forceOverwriteSquatter: true,
+        }),
+      }),
+    )
+    if (response.status !== 200) throw new Error(await response.text())
+    expect(runAction).toHaveBeenCalledWith(expect.anything(), {
+      actorUserId: 'users:admin',
+      ownerHandle: 'target',
+      ownerUserId: 'users:target',
+      slugs: ['a', 'b'],
+      forceOverwriteSquatter: true,
+    })
+  })
+
+  it('users/reclaim forbids non-admin api tokens', async () => {
+    const runQuery = vi.fn()
+    const runAction = vi.fn()
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:actor',
+      user: { _id: 'users:actor', role: 'user' },
+    } as never)
+
+    const response = await __handlers.usersPostRouterV1Handler(
+      makeCtx({ runQuery, runAction, runMutation }),
+      new Request('https://example.com/api/v1/users/reclaim', {
+        method: 'POST',
+        body: JSON.stringify({ handle: 'target', slugs: ['a'] }),
+      }),
+    )
+    expect(response.status).toBe(403)
+    expect(runQuery).not.toHaveBeenCalled()
+  })
+
+  it('users/reclaim calls reclaim mutation for admin', async () => {
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if (isRateLimitArgs(args)) return okRate()
+      return { ok: true, action: 'ownership_transferred' }
+    })
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('handle' in args) return { _id: 'users:target' }
+      return null
+    })
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:admin',
+      user: { _id: 'users:admin', role: 'admin' },
+    } as never)
+
+    const response = await __handlers.usersPostRouterV1Handler(
+      makeCtx({ runQuery, runAction: vi.fn(), runMutation }),
+      new Request('https://example.com/api/v1/users/reclaim', {
+        method: 'POST',
+        body: JSON.stringify({ handle: 'Target', slugs: [' A ', 'b'], reason: 'r' }),
+      }),
+    )
+    if (response.status !== 200) throw new Error(await response.text())
+
+    const reclaimCalls = runMutation.mock.calls.filter(([, args]) => hasSlugArgs(args))
+    expect(reclaimCalls).toHaveLength(2)
+    expect(reclaimCalls[0]?.[1]).toMatchObject({
+      actorUserId: 'users:admin',
+      slug: 'a',
+      rightfulOwnerUserId: 'users:target',
+      reason: 'r',
+      transferRootSlugOnly: true,
+    })
+    expect(reclaimCalls[1]?.[1]).toMatchObject({
+      actorUserId: 'users:admin',
+      slug: 'b',
+      rightfulOwnerUserId: 'users:target',
+      reason: 'r',
+      transferRootSlugOnly: true,
+    })
+  })
+
  it('search forwards limit and highlightedOnly', async () => {
    const runAction = vi.fn().mockResolvedValue([
      {
@@ -110,6 +237,19 @@ describe('httpApiV1 handlers', () => {
    expect(response.status).toBe(429)
  })

+  it('429 Retry-After is a relative delay, not an absolute epoch', async () => {
+    const runMutation = vi.fn().mockResolvedValue(blockedRate())
+    const response = await __handlers.searchSkillsV1Handler(
+      makeCtx({ runAction: vi.fn(), runMutation }),
+      new Request('https://example.com/api/v1/search?q=test'),
+    )
+    expect(response.status).toBe(429)
+    const retryAfter = Number(response.headers.get('Retry-After'))
+    // Retry-After must be a small relative delay (seconds), not a Unix epoch
+    expect(retryAfter).toBeGreaterThanOrEqual(1)
+    expect(retryAfter).toBeLessThanOrEqual(120)
+  })
+
  it('resolve validates hash', async () => {
    const runMutation = vi.fn().mockResolvedValue(okRate())
    const response = await __handlers.resolveSkillVersionV1Handler(
@@ -148,7 +288,7 @@ describe('httpApiV1 handlers', () => {
    expect(json.match.version).toBe('1.0.0')
  })

-  it('lists skills with resolved tags', async () => {
+  it('lists skills with resolved tags using batch query', async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ('cursor' in args || 'limit' in args) {
        return {
@@ -170,7 +310,10 @@ describe('httpApiV1 handlers', () => {
          nextCursor: null,
        }
      }
-      if ('versionId' in args) return { version: '1.0.0' }
+      // Batch query: versionIds (plural)
+      if ('versionIds' in args) {
+        return [{ _id: 'versions:1', version: '1.0.0', softDeletedAt: undefined }]
+      }
      return null
    })
    const runMutation = vi.fn().mockResolvedValue(okRate())
@@ -183,6 +326,209 @@ describe('httpApiV1 handlers', () => {
    expect(json.items[0].tags.latest).toBe('1.0.0')
  })

+  it('batches tag resolution across multiple skills into single query', async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('cursor' in args || 'limit' in args) {
+        return {
+          items: [
+            {
+              skill: {
+                _id: 'skills:1',
+                slug: 'skill-a',
+                displayName: 'Skill A',
+                summary: 's',
+                tags: { latest: 'versions:1', stable: 'versions:2' },
+                stats: { downloads: 0, stars: 0, versions: 2, comments: 0 },
+                createdAt: 1,
+                updatedAt: 2,
+              },
+              latestVersion: { version: '2.0.0', createdAt: 3, changelog: 'c' },
+            },
+            {
+              skill: {
+                _id: 'skills:2',
+                slug: 'skill-b',
+                displayName: 'Skill B',
+                summary: 's',
+                tags: { latest: 'versions:3' },
+                stats: { downloads: 0, stars: 0, versions: 1, comments: 0 },
+                createdAt: 1,
+                updatedAt: 2,
+              },
+              latestVersion: { version: '1.0.0', createdAt: 3, changelog: 'c' },
+            },
+          ],
+          nextCursor: null,
+        }
+      }
+      // Batch query should receive all version IDs from all skills
+      if ('versionIds' in args) {
+        const ids = args.versionIds as string[]
+        expect(ids).toHaveLength(3)
+        expect(ids).toContain('versions:1')
+        expect(ids).toContain('versions:2')
+        expect(ids).toContain('versions:3')
+        return [
+          { _id: 'versions:1', version: '2.0.0', softDeletedAt: undefined },
+          { _id: 'versions:2', version: '1.0.0', softDeletedAt: undefined },
+          { _id: 'versions:3', version: '1.0.0', softDeletedAt: undefined },
+        ]
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.listSkillsV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/skills'),
+    )
+    expect(response.status).toBe(200)
+    const json = await response.json()
+    // Verify tags are correctly resolved for each skill
+    expect(json.items[0].tags.latest).toBe('2.0.0')
+    expect(json.items[0].tags.stable).toBe('1.0.0')
+    expect(json.items[1].tags.latest).toBe('1.0.0')
+    // Verify batch query was called exactly once (not per-tag)
+    const batchCalls = runQuery.mock.calls.filter(
+      ([, args]) => args && 'versionIds' in (args as Record<string, unknown>),
+    )
+    expect(batchCalls).toHaveLength(1)
+  })
+
+  it('lists souls with resolved tags using batch query', async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('cursor' in args || 'limit' in args) {
+        return {
+          items: [
+            {
+              soul: {
+                _id: 'souls:1',
+                slug: 'demo-soul',
+                displayName: 'Demo Soul',
+                summary: 's',
+                tags: { latest: 'soulVersions:1' },
+                stats: { downloads: 0, stars: 0, versions: 1, comments: 0 },
+                createdAt: 1,
+                updatedAt: 2,
+              },
+              latestVersion: { version: '1.0.0', createdAt: 3, changelog: 'c' },
+            },
+          ],
+          nextCursor: null,
+        }
+      }
+      if ('versionIds' in args) {
+        return [{ _id: 'soulVersions:1', version: '1.0.0', softDeletedAt: undefined }]
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.listSoulsV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/souls?limit=1'),
+    )
+    expect(response.status).toBe(200)
+    const json = await response.json()
+    expect(json.items[0].tags.latest).toBe('1.0.0')
+  })
+
+  it('batches tag resolution across multiple souls into single query', async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('cursor' in args || 'limit' in args) {
+        return {
+          items: [
+            {
+              soul: {
+                _id: 'souls:1',
+                slug: 'soul-a',
+                displayName: 'Soul A',
+                summary: 's',
+                tags: { latest: 'soulVersions:1', stable: 'soulVersions:2' },
+                stats: { downloads: 0, stars: 0, versions: 2, comments: 0 },
+                createdAt: 1,
+                updatedAt: 2,
+              },
+              latestVersion: { version: '2.0.0', createdAt: 3, changelog: 'c' },
+            },
+            {
+              soul: {
+                _id: 'souls:2',
+                slug: 'soul-b',
+                displayName: 'Soul B',
+                summary: 's',
+                tags: { latest: 'soulVersions:3' },
+                stats: { downloads: 0, stars: 0, versions: 1, comments: 0 },
+                createdAt: 1,
+                updatedAt: 2,
+              },
+              latestVersion: { version: '1.0.0', createdAt: 3, changelog: 'c' },
+            },
+          ],
+          nextCursor: null,
+        }
+      }
+      if ('versionIds' in args) {
+        const ids = args.versionIds as string[]
+        expect(ids).toHaveLength(3)
+        expect(ids).toContain('soulVersions:1')
+        expect(ids).toContain('soulVersions:2')
+        expect(ids).toContain('soulVersions:3')
+        return [
+          { _id: 'soulVersions:1', version: '2.0.0', softDeletedAt: undefined },
+          { _id: 'soulVersions:2', version: '1.0.0', softDeletedAt: undefined },
+          { _id: 'soulVersions:3', version: '1.0.0', softDeletedAt: undefined },
+        ]
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.listSoulsV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/souls'),
+    )
+    expect(response.status).toBe(200)
+    const json = await response.json()
+    expect(json.items[0].tags.latest).toBe('2.0.0')
+    expect(json.items[0].tags.stable).toBe('1.0.0')
+    expect(json.items[1].tags.latest).toBe('1.0.0')
+    const batchCalls = runQuery.mock.calls.filter(
+      ([, args]) => args && 'versionIds' in (args as Record<string, unknown>),
+    )
+    expect(batchCalls).toHaveLength(1)
+  })
+
+  it('souls get resolves tags using batch query', async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('slug' in args) {
+        return {
+          soul: {
+            _id: 'souls:1',
+            slug: 'demo-soul',
+            displayName: 'Demo Soul',
+            summary: 's',
+            tags: { latest: 'soulVersions:1' },
+            stats: { downloads: 0, stars: 0, versions: 1, comments: 0 },
+            createdAt: 1,
+            updatedAt: 2,
+          },
+          latestVersion: { version: '1.0.0', createdAt: 3, changelog: 'c' },
+          owner: null,
+        }
+      }
+      if ('versionIds' in args) {
+        return [{ _id: 'soulVersions:1', version: '1.0.0', softDeletedAt: undefined }]
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.soulsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/souls/demo-soul'),
+    )
+    expect(response.status).toBe(200)
+    const json = await response.json()
+    expect(json.soul.tags.latest).toBe('1.0.0')
+  })
+
  it('lists skills supports sort aliases', async () => {
    const checks: Array<[string, string]> = [
      ['rating', 'stars'],
@@ -218,6 +564,52 @@ describe('httpApiV1 handlers', () => {
    expect(response.status).toBe(404)
  })

+  it('get skill returns pending-scan message for owner api token', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('slug' in args) {
+        return {
+          _id: 'skills:1',
+          slug: 'demo',
+          ownerUserId: 'users:1',
+          moderationStatus: 'hidden',
+          moderationReason: 'pending.scan',
+        }
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/skills/demo'),
+    )
+    expect(response.status).toBe(423)
+    expect(await response.text()).toContain('security scan is pending')
+  })
+
+  it('get skill returns undelete hint for owner soft-deleted skill', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('slug' in args) {
+        return {
+          _id: 'skills:1',
+          slug: 'demo',
+          ownerUserId: 'users:1',
+          softDeletedAt: 1,
+          moderationStatus: 'hidden',
+        }
+      }
+      return null
+    })
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request('https://example.com/api/v1/skills/demo'),
+    )
+    expect(response.status).toBe(410)
+    expect(await response.text()).toContain('clawhub undelete demo')
+  })
+
  it('get skill returns payload', async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ('slug' in args) {
@@ -241,7 +633,10 @@ describe('httpApiV1 handlers', () => {
          owner: { handle: 'p', displayName: 'Peter', image: null },
        }
      }
-      if ('versionId' in args) return { version: '1.0.0' }
+      // Batch query for tag resolution
+      if ('versionIds' in args) {
+        return [{ _id: 'versions:1', version: '1.0.0', softDeletedAt: undefined }]
+      }
      return null
    })
    const runMutation = vi.fn().mockResolvedValue(okRate())
@@ -477,6 +872,50 @@ describe('httpApiV1 handlers', () => {
    }
  })

+  it('publish multipart ignores mac junk files', async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValueOnce({
+      userId: 'users:1',
+      user: { handle: 'p' },
+    } as never)
+    vi.mocked(publishVersionForUser).mockResolvedValueOnce({
+      skillId: 's',
+      versionId: 'v',
+      embeddingId: 'e',
+    } as never)
+    const runMutation = vi.fn().mockResolvedValue(okRate())
+    const store = vi.fn().mockResolvedValue('storage:1')
+    const form = new FormData()
+    form.set(
+      'payload',
+      JSON.stringify({
+        slug: 'demo',
+        displayName: 'Demo',
+        version: '1.0.0',
+        changelog: '',
+        tags: ['latest'],
+      }),
+    )
+    form.append('files', new Blob(['hello'], { type: 'text/plain' }), 'SKILL.md')
+    form.append('files', new Blob(['junk'], { type: 'application/octet-stream' }), '.DS_Store')
+    const response = await __handlers.publishSkillV1Handler(
+      makeCtx({ runMutation, storage: { store } }),
+      new Request('https://example.com/api/v1/skills', {
+        method: 'POST',
+        headers: { Authorization: 'Bearer clh_test' },
+        body: form,
+      }),
+    )
+    if (response.status !== 200) {
+      throw new Error(await response.text())
+    }
+
+    expect(store).toHaveBeenCalledTimes(1)
+    const publishArgs = vi.mocked(publishVersionForUser).mock.calls[0]?.[2] as
+      | { files?: Array<{ path: string }> }
+      | undefined
+    expect(publishArgs?.files?.map((file) => file.path)).toEqual(['SKILL.md'])
+  })
+
  it('publish rejects missing token', async () => {
    const runMutation = vi.fn().mockResolvedValue(okRate())
    const response = await __handlers.publishSkillV1Handler(
@@ -662,6 +1101,7 @@ describe('httpApiV1 handlers', () => {
  })

  it('stars add succeeds', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
    vi.mocked(requireApiTokenUser).mockResolvedValue({
      userId: 'users:1',
      user: { handle: 'p' },
@@ -670,7 +1110,6 @@ describe('httpApiV1 handlers', () => {
    const runMutation = vi
      .fn()
      .mockResolvedValueOnce(okRate())
-      .mockResolvedValueOnce(okRate())
      .mockResolvedValueOnce({ ok: true, starred: true, alreadyStarred: false })
    const response = await __handlers.starsPostRouterV1Handler(
      makeCtx({ runQuery, runMutation }),
@@ -686,6 +1125,7 @@ describe('httpApiV1 handlers', () => {
  })

  it('stars delete succeeds', async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue('users:1' as never)
    vi.mocked(requireApiTokenUser).mockResolvedValue({
      userId: 'users:1',
      user: { handle: 'p' },
@@ -694,7 +1134,6 @@ describe('httpApiV1 handlers', () => {
    const runMutation = vi
      .fn()
      .mockResolvedValueOnce(okRate())
-      .mockResolvedValueOnce(okRate())
      .mockResolvedValueOnce({ ok: true, unstarred: true, alreadyUnstarred: false })
    const response = await __handlers.starsDeleteRouterV1Handler(
      makeCtx({ runQuery, runMutation }),
@@ -708,4 +1147,61 @@ describe('httpApiV1 handlers', () => {
    expect(json.ok).toBe(true)
    expect(json.unstarred).toBe(true)
  })
+
+  it('delete/undelete map forbidden/not-found/unknown to 403/404/500', async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { handle: 'p' },
+    } as never)
+
+    const runMutationForbidden = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('key' in args) return okRate()
+      throw new Error('Forbidden')
+    })
+    const forbidden = await __handlers.skillsDeleteRouterV1Handler(
+      makeCtx({ runMutation: runMutationForbidden }),
+      new Request('https://example.com/api/v1/skills/demo', {
+        method: 'DELETE',
+        headers: { Authorization: 'Bearer clh_test' },
+      }),
+    )
+    expect(forbidden.status).toBe(403)
+    expect(await forbidden.text()).toBe('Forbidden')
+
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { handle: 'p' },
+    } as never)
+    const runMutationNotFound = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('key' in args) return okRate()
+      throw new Error('Skill not found')
+    })
+    const notFound = await __handlers.skillsPostRouterV1Handler(
+      makeCtx({ runMutation: runMutationNotFound }),
+      new Request('https://example.com/api/v1/skills/demo/undelete', {
+        method: 'POST',
+        headers: { Authorization: 'Bearer clh_test' },
+      }),
+    )
+    expect(notFound.status).toBe(404)
+    expect(await notFound.text()).toBe('Skill not found')
+
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: 'users:1',
+      user: { handle: 'p' },
+    } as never)
+    const runMutationUnknown = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ('key' in args) return okRate()
+      throw new Error('boom')
+    })
+    const unknown = await __handlers.soulsDeleteRouterV1Handler(
+      makeCtx({ runMutation: runMutationUnknown }),
+      new Request('https://example.com/api/v1/souls/demo-soul', {
+        method: 'DELETE',
+        headers: { Authorization: 'Bearer clh_test' },
+      }),
+    )
+    expect(unknown.status).toBe(500)
+    expect(await unknown.text()).toBe('Internal Server Error')
+  })
 })
@@ -0,0 +1,326 @@
+import { CliPublishRequestSchema, parseArk } from 'clawhub-schema'
+import { internal } from '../_generated/api'
+import type { Doc, Id } from '../_generated/dataModel'
+import type { ActionCtx } from '../_generated/server'
+import { assertAdmin } from '../lib/access'
+import { requireApiTokenUser } from '../lib/apiTokenAuth'
+import { corsHeaders, mergeHeaders } from '../lib/httpHeaders'
+import { isMacJunkPath } from '../lib/skills'
+
+export const MAX_RAW_FILE_BYTES = 200 * 1024
+
+const SAFE_TEXT_FILE_CSP =
+  "default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+function isSvgLike(contentType: string | undefined, path: string) {
+  return contentType?.toLowerCase().includes('svg') || path.toLowerCase().endsWith('.svg')
+}
+
+export function safeTextFileResponse(params: {
+  textContent: string
+  path: string
+  contentType?: string
+  sha256: string
+  size: number
+  headers?: HeadersInit
+}) {
+  const isSvg = isSvgLike(params.contentType, params.path)
+
+  // For any text response that a browser might try to render, lock it down.
+  // In particular, this prevents SVG <foreignObject> script execution from reading
+  // localStorage tokens on this origin.
+  const headers = mergeHeaders(
+    params.headers,
+    {
+      'Content-Type': params.contentType
+        ? `${params.contentType}; charset=utf-8`
+        : 'text/plain; charset=utf-8',
+      'Cache-Control': 'private, max-age=60',
+      ETag: params.sha256,
+      'X-Content-SHA256': params.sha256,
+      'X-Content-Size': String(params.size),
+      'X-Content-Type-Options': 'nosniff',
+      'X-Frame-Options': 'DENY',
+      'Content-Security-Policy': SAFE_TEXT_FILE_CSP,
+      ...(isSvg ? { 'Content-Disposition': 'attachment' } : {}),
+    },
+    corsHeaders(),
+  )
+
+  return new Response(params.textContent, { status: 200, headers })
+}
+
+export function json(value: unknown, status = 200, headers?: HeadersInit) {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: mergeHeaders(
+      {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+      },
+      headers,
+      corsHeaders(),
+    ),
+  })
+}
+
+export function text(value: string, status: number, headers?: HeadersInit) {
+  return new Response(value, {
+    status,
+    headers: mergeHeaders(
+      {
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Cache-Control': 'no-store',
+      },
+      headers,
+      corsHeaders(),
+    ),
+  })
+}
+
+export async function parseJsonPayload(request: Request, headers: HeadersInit) {
+  try {
+    const payload = (await request.json()) as Record<string, unknown>
+    return { ok: true as const, payload }
+  } catch {
+    return { ok: false as const, response: text('Invalid JSON', 400, headers) }
+  }
+}
+
+export async function requireApiTokenUserOrResponse(
+  ctx: ActionCtx,
+  request: Request,
+  headers: HeadersInit,
+) {
+  try {
+    const auth = await requireApiTokenUser(ctx, request)
+    return { ok: true as const, userId: auth.userId, user: auth.user as Doc<'users'> }
+  } catch {
+    return { ok: false as const, response: text('Unauthorized', 401, headers) }
+  }
+}
+
+export function requireAdminOrResponse(user: Doc<'users'>, headers: HeadersInit) {
+  try {
+    assertAdmin(user)
+    return { ok: true as const }
+  } catch {
+    return { ok: false as const, response: text('Forbidden', 403, headers) }
+  }
+}
+
+export function getPathSegments(request: Request, prefix: string) {
+  const pathname = new URL(request.url).pathname
+  if (!pathname.startsWith(prefix)) return []
+  const rest = pathname.slice(prefix.length)
+  return rest
+    .split('/')
+    .map((segment) => segment.trim())
+    .filter(Boolean)
+    .map((segment) => decodeURIComponent(segment))
+}
+
+export function toOptionalNumber(value: string | null) {
+  if (!value) return undefined
+  const parsed = Number.parseInt(value, 10)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+/**
+ * Batch resolve soul version tags to version strings.
+ * Collects all version IDs, fetches them in a single query, then maps back.
+ * Reduces N sequential queries to 1 batch query.
+ */
+export async function resolveSoulTagsBatch(
+  ctx: ActionCtx,
+  tagsList: Array<Record<string, Id<'soulVersions'>>>,
+): Promise<Array<Record<string, string>>> {
+  return resolveVersionTagsBatch(ctx, tagsList, internal.souls.getVersionsByIdsInternal)
+}
+
+export async function resolveTagsBatch(
+  ctx: ActionCtx,
+  tagsList: Array<Record<string, Id<'skillVersions'>>>,
+): Promise<Array<Record<string, string>>> {
+  return resolveVersionTagsBatch(ctx, tagsList, internal.skills.getVersionsByIdsInternal)
+}
+
+/**
+ * Batch resolve version tags to version strings.
+ * Collects all version IDs, fetches them in a single query, then maps back.
+ *
+ * Notes:
+ * - Uses `internal.*` queries to avoid expanding the public Convex API surface.
+ * - Sorts ids for stable query args (helps caching/log diffs).
+ */
+export async function resolveVersionTagsBatch<TTable extends 'skillVersions' | 'soulVersions'>(
+  ctx: ActionCtx,
+  tagsList: Array<Record<string, Id<TTable>>>,
+  getVersionsByIdsQuery: unknown,
+): Promise<Array<Record<string, string>>> {
+  const allVersionIds = new Set<Id<TTable>>()
+  for (const tags of tagsList) {
+    for (const versionId of Object.values(tags)) allVersionIds.add(versionId)
+  }
+
+  if (allVersionIds.size === 0) return tagsList.map(() => ({}))
+
+  const versionIds = [...allVersionIds].sort() as Array<Id<TTable>>
+  const versions =
+    ((await ctx.runQuery(getVersionsByIdsQuery as never, { versionIds } as never)) as Array<{
+      _id: Id<TTable>
+      version: string
+      softDeletedAt?: unknown
+    }> | null) ?? []
+
+  const versionMap = new Map<Id<TTable>, string>()
+  for (const v of versions) {
+    if (!v?.softDeletedAt) versionMap.set(v._id, v.version)
+  }
+
+  return tagsList.map((tags) => {
+    const resolved: Record<string, string> = {}
+    for (const [tag, versionId] of Object.entries(tags)) {
+      const version = versionMap.get(versionId)
+      if (version) resolved[tag] = version
+    }
+    return resolved
+  })
+}
+
+async function sha256Hex(bytes: Uint8Array) {
+  const data = new Uint8Array(bytes)
+  const digest = await crypto.subtle.digest('SHA-256', data)
+  return toHex(new Uint8Array(digest))
+}
+
+function toHex(bytes: Uint8Array) {
+  let out = ''
+  for (const byte of bytes) out += byte.toString(16).padStart(2, '0')
+  return out
+}
+
+type FileLike = {
+  name: string
+  size: number
+  type: string
+  arrayBuffer: () => Promise<ArrayBuffer>
+}
+
+type FileLikeEntry = FormDataEntryValue & FileLike
+
+function toFileLike(entry: FormDataEntryValue): FileLikeEntry | null {
+  if (typeof entry === 'string') return null
+  const candidate = entry as Partial<FileLike>
+  if (typeof candidate.name !== 'string') return null
+  if (typeof candidate.size !== 'number') return null
+  if (typeof candidate.arrayBuffer !== 'function') return null
+  return entry as FileLikeEntry
+}
+
+export async function parseMultipartPublish(
+  ctx: ActionCtx,
+  request: Request,
+): Promise<{
+  slug: string
+  displayName: string
+  version: string
+  changelog: string
+  tags?: string[]
+  forkOf?: { slug: string; version?: string }
+  files: Array<{
+    path: string
+    size: number
+    storageId: Id<'_storage'>
+    sha256: string
+    contentType?: string
+  }>
+}> {
+  const form = await request.formData()
+  const payloadRaw = form.get('payload')
+  if (!payloadRaw || typeof payloadRaw !== 'string') {
+    throw new Error('Missing payload')
+  }
+  let payload: Record<string, unknown>
+  try {
+    payload = JSON.parse(payloadRaw) as Record<string, unknown>
+  } catch {
+    throw new Error('Invalid JSON payload')
+  }
+
+  const files: Array<{
+    path: string
+    size: number
+    storageId: Id<'_storage'>
+    sha256: string
+    contentType?: string
+  }> = []
+
+  for (const entry of form.getAll('files')) {
+    const file = toFileLike(entry)
+    if (!file) continue
+    const path = file.name
+    if (isMacJunkPath(path)) continue
+    const size = file.size
+    const contentType = file.type || undefined
+    const buffer = new Uint8Array(await file.arrayBuffer())
+    const sha256 = await sha256Hex(buffer)
+    const storageId = await ctx.storage.store(file as Blob)
+    files.push({ path, size, storageId, sha256, contentType })
+  }
+
+  const forkOf = payload.forkOf && typeof payload.forkOf === 'object' ? payload.forkOf : undefined
+  const body = {
+    slug: payload.slug,
+    displayName: payload.displayName,
+    version: payload.version,
+    changelog: typeof payload.changelog === 'string' ? payload.changelog : '',
+    tags: Array.isArray(payload.tags) ? payload.tags : undefined,
+    ...(payload.source ? { source: payload.source } : {}),
+    files,
+    ...(forkOf ? { forkOf } : {}),
+  }
+
+  return parsePublishBody(body)
+}
+
+export function parsePublishBody(body: unknown) {
+  const parsed = parseArk(CliPublishRequestSchema, body, 'Publish payload')
+  if (parsed.files.length === 0) throw new Error('files required')
+  const tags = parsed.tags && parsed.tags.length > 0 ? parsed.tags : undefined
+  return {
+    slug: parsed.slug,
+    displayName: parsed.displayName,
+    version: parsed.version,
+    changelog: parsed.changelog,
+    tags,
+    source: parsed.source ?? undefined,
+    forkOf: parsed.forkOf
+      ? {
+          slug: parsed.forkOf.slug,
+          version: parsed.forkOf.version ?? undefined,
+        }
+      : undefined,
+    files: parsed.files.map((file) => ({
+      ...file,
+      storageId: file.storageId as Id<'_storage'>,
+    })),
+  }
+}
+
+export function softDeleteErrorToResponse(
+  entity: 'skill' | 'soul',
+  error: unknown,
+  headers: HeadersInit,
+) {
+  const message = error instanceof Error ? error.message : `${entity} delete failed`
+  const lower = message.toLowerCase()
+
+  if (lower.includes('unauthorized')) return text('Unauthorized', 401, headers)
+  if (lower.includes('forbidden')) return text('Forbidden', 403, headers)
+  if (lower.includes('not found')) return text(message, 404, headers)
+  if (lower.includes('slug required')) return text('Slug required', 400, headers)
+
+  // Unknown: server-side failure. Keep body generic.
+  return text('Internal Server Error', 500, headers)
+}
@@ -0,0 +1,550 @@
+import { api, internal } from '../_generated/api'
+import type { Doc, Id } from '../_generated/dataModel'
+import type { ActionCtx } from '../_generated/server'
+import { getOptionalApiTokenUserId, requireApiTokenUser } from '../lib/apiTokenAuth'
+import { applyRateLimit, parseBearerToken } from '../lib/httpRateLimit'
+import { publishVersionForUser } from '../skills'
+import {
+  MAX_RAW_FILE_BYTES,
+  getPathSegments,
+  json,
+  parseMultipartPublish,
+  parsePublishBody,
+  resolveTagsBatch,
+  safeTextFileResponse,
+  softDeleteErrorToResponse,
+  text,
+  toOptionalNumber,
+} from './shared'
+
+type SearchSkillEntry = {
+  score: number
+  skill: {
+    slug?: string
+    displayName?: string
+    summary?: string | null
+    updatedAt?: number
+  } | null
+  version: { version?: string; createdAt?: number } | null
+}
+
+type ListSkillsResult = {
+  items: Array<{
+    skill: {
+      _id: Id<'skills'>
+      slug: string
+      displayName: string
+      summary?: string
+      tags: Record<string, Id<'skillVersions'>>
+      stats: unknown
+      createdAt: number
+      updatedAt: number
+      latestVersionId?: Id<'skillVersions'>
+    }
+    latestVersion: {
+      version: string
+      createdAt: number
+      changelog: string
+      parsed?: { clawdis?: { os?: string[]; nix?: { plugin?: boolean; systems?: string[] } } }
+    } | null
+  }>
+  nextCursor: string | null
+}
+
+type SkillFile = Doc<'skillVersions'>['files'][number]
+
+type GetBySlugResult = {
+  skill: {
+    _id: Id<'skills'>
+    slug: string
+    displayName: string
+    summary?: string
+    tags: Record<string, Id<'skillVersions'>>
+    stats: unknown
+    createdAt: number
+    updatedAt: number
+  } | null
+  latestVersion: Doc<'skillVersions'> | null
+  owner: { _id: Id<'users'>; handle?: string; displayName?: string; image?: string } | null
+  moderationInfo?: {
+    isPendingScan: boolean
+    isMalwareBlocked: boolean
+    isSuspicious: boolean
+    isHiddenByMod: boolean
+    isRemoved: boolean
+    reason?: string
+  } | null
+} | null
+
+type ListVersionsResult = {
+  items: Array<{
+    version: string
+    createdAt: number
+    changelog: string
+    changelogSource?: 'auto' | 'user'
+    files: Array<{
+      path: string
+      size: number
+      storageId: Id<'_storage'>
+      sha256: string
+      contentType?: string
+    }>
+    softDeletedAt?: number
+  }>
+  nextCursor: string | null
+}
+
+export async function searchSkillsV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const url = new URL(request.url)
+  const query = url.searchParams.get('q')?.trim() ?? ''
+  const limit = toOptionalNumber(url.searchParams.get('limit'))
+  const highlightedOnly = url.searchParams.get('highlightedOnly') === 'true'
+
+  if (!query) return json({ results: [] }, 200, rate.headers)
+
+  const results = (await ctx.runAction(api.search.searchSkills, {
+    query,
+    limit,
+    highlightedOnly: highlightedOnly || undefined,
+  })) as SearchSkillEntry[]
+
+  return json(
+    {
+      results: results.map((result) => ({
+        score: result.score,
+        slug: result.skill?.slug,
+        displayName: result.skill?.displayName,
+        summary: result.skill?.summary ?? null,
+        version: result.version?.version ?? null,
+        updatedAt: result.skill?.updatedAt,
+      })),
+    },
+    200,
+    rate.headers,
+  )
+}
+
+export async function resolveSkillVersionV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const url = new URL(request.url)
+  const slug = url.searchParams.get('slug')?.trim().toLowerCase()
+  const hash = url.searchParams.get('hash')?.trim().toLowerCase()
+  if (!slug || !hash) return text('Missing slug or hash', 400, rate.headers)
+  if (!/^[a-f0-9]{64}$/.test(hash)) return text('Invalid hash', 400, rate.headers)
+
+  const resolved = await ctx.runQuery(api.skills.resolveVersionByHash, { slug, hash })
+  if (!resolved) return text('Skill not found', 404, rate.headers)
+
+  return json({ slug, match: resolved.match, latestVersion: resolved.latestVersion }, 200, rate.headers)
+}
+
+type SkillListSort =
+  | 'updated'
+  | 'downloads'
+  | 'stars'
+  | 'installsCurrent'
+  | 'installsAllTime'
+  | 'trending'
+
+function parseListSort(value: string | null): SkillListSort {
+  const normalized = value?.trim().toLowerCase()
+  if (normalized === 'downloads') return 'downloads'
+  if (normalized === 'stars' || normalized === 'rating') return 'stars'
+  if (
+    normalized === 'installs' ||
+    normalized === 'install' ||
+    normalized === 'installscurrent' ||
+    normalized === 'installs-current'
+  ) {
+    return 'installsCurrent'
+  }
+  if (normalized === 'installsalltime' || normalized === 'installs-all-time') {
+    return 'installsAllTime'
+  }
+  if (normalized === 'trending') return 'trending'
+  return 'updated'
+}
+
+export async function listSkillsV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const url = new URL(request.url)
+  const limit = toOptionalNumber(url.searchParams.get('limit'))
+  const rawCursor = url.searchParams.get('cursor')?.trim() || undefined
+  const sort = parseListSort(url.searchParams.get('sort'))
+  const cursor = sort === 'trending' ? undefined : rawCursor
+
+  const result = (await ctx.runQuery(api.skills.listPublicPage, {
+    limit,
+    cursor,
+    sort,
+  })) as ListSkillsResult
+
+  // Batch resolve all tags in a single query instead of N queries
+  const resolvedTagsList = await resolveTagsBatch(
+    ctx,
+    result.items.map((item) => item.skill.tags),
+  )
+
+  const items = result.items.map((item, idx) => ({
+    slug: item.skill.slug,
+    displayName: item.skill.displayName,
+    summary: item.skill.summary ?? null,
+    tags: resolvedTagsList[idx],
+    stats: item.skill.stats,
+    createdAt: item.skill.createdAt,
+    updatedAt: item.skill.updatedAt,
+    latestVersion: item.latestVersion
+      ? {
+          version: item.latestVersion.version,
+          createdAt: item.latestVersion.createdAt,
+          changelog: item.latestVersion.changelog,
+        }
+      : null,
+    metadata: item.latestVersion?.parsed?.clawdis
+      ? {
+          os: item.latestVersion.parsed.clawdis.os ?? null,
+          systems: item.latestVersion.parsed.clawdis.nix?.systems ?? null,
+        }
+      : null,
+  }))
+
+  return json({ items, nextCursor: result.nextCursor ?? null }, 200, rate.headers)
+}
+
+async function describeOwnerVisibleSkillState(
+  ctx: ActionCtx,
+  request: Request,
+  slug: string,
+): Promise<{ status: number; message: string } | null> {
+  const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+  if (!skill) return null
+
+  const apiTokenUserId = await getOptionalApiTokenUserId(ctx, request)
+  const isOwner = Boolean(apiTokenUserId && apiTokenUserId === skill.ownerUserId)
+  if (!isOwner) return null
+
+  if (skill.softDeletedAt) {
+    return {
+      status: 410,
+      message: `Skill is hidden/deleted. Run "clawhub undelete ${slug}" to restore it.`,
+    }
+  }
+
+  if (skill.moderationStatus === 'hidden') {
+    if (skill.moderationReason === 'pending.scan' || skill.moderationReason === 'scanner.vt.pending') {
+      return {
+        status: 423,
+        message: 'Skill is hidden while security scan is pending. Try again in a few minutes.',
+      }
+    }
+    if (skill.moderationReason === 'quality.low') {
+      return {
+        status: 403,
+        message:
+          'Skill is hidden by quality checks. Update SKILL.md content or run "clawhub undelete <slug>" after review.',
+      }
+    }
+    return {
+      status: 403,
+      message: `Skill is hidden by moderation${
+        skill.moderationReason ? ` (${skill.moderationReason})` : ''
+      }.`,
+    }
+  }
+
+  if (skill.moderationStatus === 'removed') {
+    return { status: 410, message: 'Skill has been removed by moderation.' }
+  }
+
+  return null
+}
+
+export async function skillsGetRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/skills/')
+  if (segments.length === 0) return text('Missing slug', 400, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  const second = segments[1]
+  const third = segments[2]
+
+  if (segments.length === 1) {
+    const result = (await ctx.runQuery(api.skills.getBySlug, { slug })) as GetBySlugResult
+    if (!result?.skill) {
+      const hidden = await describeOwnerVisibleSkillState(ctx, request, slug)
+      if (hidden) return text(hidden.message, hidden.status, rate.headers)
+      return text('Skill not found', 404, rate.headers)
+    }
+
+    const [tags] = await resolveTagsBatch(ctx, [result.skill.tags])
+    return json(
+      {
+        skill: {
+          slug: result.skill.slug,
+          displayName: result.skill.displayName,
+          summary: result.skill.summary ?? null,
+          tags,
+          stats: result.skill.stats,
+          createdAt: result.skill.createdAt,
+          updatedAt: result.skill.updatedAt,
+        },
+        latestVersion: result.latestVersion
+          ? {
+              version: result.latestVersion.version,
+              createdAt: result.latestVersion.createdAt,
+              changelog: result.latestVersion.changelog,
+            }
+          : null,
+        metadata: result.latestVersion?.parsed?.clawdis
+          ? {
+              os: result.latestVersion.parsed.clawdis.os ?? null,
+              systems: result.latestVersion.parsed.clawdis.nix?.systems ?? null,
+            }
+          : null,
+        owner: result.owner
+          ? {
+              handle: result.owner.handle ?? null,
+              userId: result.owner._id,
+              displayName: result.owner.displayName ?? null,
+              image: result.owner.image ?? null,
+            }
+          : null,
+        moderation: result.moderationInfo
+          ? {
+              isSuspicious: result.moderationInfo.isSuspicious ?? false,
+              isMalwareBlocked: result.moderationInfo.isMalwareBlocked ?? false,
+            }
+          : null,
+      },
+      200,
+      rate.headers,
+    )
+  }
+
+  if (second === 'versions' && segments.length === 2) {
+    const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+    if (!skill || skill.softDeletedAt) return text('Skill not found', 404, rate.headers)
+
+    const url = new URL(request.url)
+    const limit = toOptionalNumber(url.searchParams.get('limit'))
+    const cursor = url.searchParams.get('cursor')?.trim() || undefined
+    const result = (await ctx.runQuery(api.skills.listVersionsPage, {
+      skillId: skill._id,
+      limit,
+      cursor,
+    })) as ListVersionsResult
+
+    const items = result.items
+      .filter((version) => !version.softDeletedAt)
+      .map((version) => ({
+        version: version.version,
+        createdAt: version.createdAt,
+        changelog: version.changelog,
+        changelogSource: version.changelogSource ?? null,
+      }))
+
+    return json({ items, nextCursor: result.nextCursor ?? null }, 200, rate.headers)
+  }
+
+  if (second === 'versions' && third && segments.length === 3) {
+    const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+    if (!skill || skill.softDeletedAt) return text('Skill not found', 404, rate.headers)
+
+    const version = await ctx.runQuery(api.skills.getVersionBySkillAndVersion, {
+      skillId: skill._id,
+      version: third,
+    })
+    if (!version) return text('Version not found', 404, rate.headers)
+    if (version.softDeletedAt) return text('Version not available', 410, rate.headers)
+
+    // Map llmAnalysis to security status
+    let security = undefined
+    if (version.llmAnalysis) {
+      const analysis = version.llmAnalysis
+      let status: 'clean' | 'suspicious' | 'malicious' | 'pending' | 'error'
+      switch (analysis.verdict) {
+        case 'benign':
+          status = 'clean'
+          break
+        case 'suspicious':
+          status = 'suspicious'
+          break
+        case 'malicious':
+          status = 'malicious'
+          break
+        default:
+          status = analysis.status === 'error' ? 'error' : 'pending'
+      }
+
+      const hasWarnings =
+        analysis.verdict === 'suspicious' ||
+        analysis.verdict === 'malicious' ||
+        (Array.isArray(analysis.dimensions) &&
+          analysis.dimensions.some((dimension) => {
+            if (!dimension || typeof dimension !== 'object') return false
+            const rating = (dimension as { rating?: unknown }).rating
+            return typeof rating === 'string' && rating !== 'ok'
+          }))
+
+      security = {
+        status,
+        hasWarnings,
+        checkedAt: analysis.checkedAt ?? null,
+        model: analysis.model || null,
+      }
+    }
+
+    return json(
+      {
+        skill: { slug: skill.slug, displayName: skill.displayName },
+        version: {
+          version: version.version,
+          createdAt: version.createdAt,
+          changelog: version.changelog,
+          changelogSource: version.changelogSource ?? null,
+          files: version.files.map((file: SkillFile) => ({
+            path: file.path,
+            size: file.size,
+            sha256: file.sha256,
+            contentType: file.contentType ?? null,
+          })),
+          security,
+        },
+      },
+      200,
+      rate.headers,
+    )
+  }
+
+  if (second === 'file' && segments.length === 2) {
+    const url = new URL(request.url)
+    const path = url.searchParams.get('path')?.trim()
+    if (!path) return text('Missing path', 400, rate.headers)
+    const versionParam = url.searchParams.get('version')?.trim()
+    const tagParam = url.searchParams.get('tag')?.trim()
+
+    const skillResult = (await ctx.runQuery(api.skills.getBySlug, { slug })) as GetBySlugResult
+    if (!skillResult?.skill) return text('Skill not found', 404, rate.headers)
+
+    let version = skillResult.latestVersion
+    if (versionParam) {
+      version = await ctx.runQuery(api.skills.getVersionBySkillAndVersion, {
+        skillId: skillResult.skill._id,
+        version: versionParam,
+      })
+    } else if (tagParam) {
+      const versionId = skillResult.skill.tags[tagParam]
+      if (versionId) {
+        version = await ctx.runQuery(api.skills.getVersionById, { versionId })
+      }
+    }
+
+    if (!version) return text('Version not found', 404, rate.headers)
+    if (version.softDeletedAt) return text('Version not available', 410, rate.headers)
+
+    const normalized = path.trim()
+    const normalizedLower = normalized.toLowerCase()
+    const file =
+      version.files.find((entry) => entry.path === normalized) ??
+      version.files.find((entry) => entry.path.toLowerCase() === normalizedLower)
+    if (!file) return text('File not found', 404, rate.headers)
+    if (file.size > MAX_RAW_FILE_BYTES) return text('File exceeds 200KB limit', 413, rate.headers)
+
+    const blob = await ctx.storage.get(file.storageId)
+    if (!blob) return text('File missing in storage', 410, rate.headers)
+    const textContent = await blob.text()
+    return safeTextFileResponse({
+      textContent,
+      path: file.path,
+      contentType: file.contentType ?? undefined,
+      sha256: file.sha256,
+      size: file.size,
+      headers: rate.headers,
+    })
+  }
+
+  return text('Not found', 404, rate.headers)
+}
+
+export async function publishSkillV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  try {
+    if (!parseBearerToken(request)) return text('Unauthorized', 401, rate.headers)
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+  const { userId } = await requireApiTokenUser(ctx, request)
+
+  const contentType = request.headers.get('content-type') ?? ''
+  try {
+    if (contentType.includes('application/json')) {
+      const body = await request.json()
+      const payload = parsePublishBody(body)
+      const result = await publishVersionForUser(ctx, userId, payload)
+      return json({ ok: true, ...result }, 200, rate.headers)
+    }
+
+    if (contentType.includes('multipart/form-data')) {
+      const payload = await parseMultipartPublish(ctx, request)
+      const result = await publishVersionForUser(ctx, userId, payload)
+      return json({ ok: true, ...result }, 200, rate.headers)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Publish failed'
+    return text(message, 400, rate.headers)
+  }
+
+  return text('Unsupported content type', 415, rate.headers)
+}
+
+export async function skillsPostRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/skills/')
+  if (segments.length !== 2 || segments[1] !== 'undelete') {
+    return text('Not found', 404, rate.headers)
+  }
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    await ctx.runMutation(internal.skills.setSkillSoftDeletedInternal, {
+      userId,
+      slug,
+      deleted: false,
+    })
+    return json({ ok: true }, 200, rate.headers)
+  } catch (error) {
+    return softDeleteErrorToResponse('skill', error, rate.headers)
+  }
+}
+
+export async function skillsDeleteRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/skills/')
+  if (segments.length !== 1) return text('Not found', 404, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    await ctx.runMutation(internal.skills.setSkillSoftDeletedInternal, {
+      userId,
+      slug,
+      deleted: true,
+    })
+    return json({ ok: true }, 200, rate.headers)
+  } catch (error) {
+    return softDeleteErrorToResponse('skill', error, rate.headers)
+  }
+}
@@ -0,0 +1,340 @@
+import { api, internal } from '../_generated/api'
+import type { Doc, Id } from '../_generated/dataModel'
+import type { ActionCtx } from '../_generated/server'
+import { requireApiTokenUser } from '../lib/apiTokenAuth'
+import { applyRateLimit, parseBearerToken } from '../lib/httpRateLimit'
+import { publishSoulVersionForUser } from '../souls'
+import {
+  MAX_RAW_FILE_BYTES,
+  getPathSegments,
+  json,
+  parseMultipartPublish,
+  parsePublishBody,
+  resolveSoulTagsBatch,
+  safeTextFileResponse,
+  softDeleteErrorToResponse,
+  text,
+  toOptionalNumber,
+} from './shared'
+
+type ListSoulsResult = {
+  items: Array<{
+    soul: {
+      _id: Id<'souls'>
+      slug: string
+      displayName: string
+      summary?: string
+      tags: Record<string, Id<'soulVersions'>>
+      stats: unknown
+      createdAt: number
+      updatedAt: number
+      latestVersionId?: Id<'soulVersions'>
+    }
+    latestVersion: { version: string; createdAt: number; changelog: string } | null
+  }>
+  nextCursor: string | null
+}
+
+type GetSoulBySlugResult = {
+  soul: {
+    _id: Id<'souls'>
+    slug: string
+    displayName: string
+    summary?: string
+    tags: Record<string, Id<'soulVersions'>>
+    stats: unknown
+    createdAt: number
+    updatedAt: number
+  } | null
+  latestVersion: Doc<'soulVersions'> | null
+  owner: { handle?: string; displayName?: string; image?: string } | null
+} | null
+
+type ListSoulVersionsResult = {
+  items: Array<{
+    version: string
+    createdAt: number
+    changelog: string
+    changelogSource?: 'auto' | 'user'
+    files: Array<{
+      path: string
+      size: number
+      storageId: Id<'_storage'>
+      sha256: string
+      contentType?: string
+    }>
+    softDeletedAt?: number
+  }>
+  nextCursor: string | null
+}
+
+type SoulFile = Doc<'soulVersions'>['files'][number]
+
+export async function listSoulsV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const url = new URL(request.url)
+  const limit = toOptionalNumber(url.searchParams.get('limit'))
+  const cursor = url.searchParams.get('cursor')?.trim() || undefined
+
+  const result = (await ctx.runQuery(api.souls.listPublicPage, {
+    limit,
+    cursor,
+  })) as ListSoulsResult
+
+  // Batch resolve all tags in a single query instead of N queries
+  const resolvedTagsList = await resolveSoulTagsBatch(
+    ctx,
+    result.items.map((item) => item.soul.tags),
+  )
+
+  const items = result.items.map((item, idx) => ({
+    slug: item.soul.slug,
+    displayName: item.soul.displayName,
+    summary: item.soul.summary ?? null,
+    tags: resolvedTagsList[idx],
+    stats: item.soul.stats,
+    createdAt: item.soul.createdAt,
+    updatedAt: item.soul.updatedAt,
+    latestVersion: item.latestVersion
+      ? {
+          version: item.latestVersion.version,
+          createdAt: item.latestVersion.createdAt,
+          changelog: item.latestVersion.changelog,
+        }
+      : null,
+  }))
+
+  return json({ items, nextCursor: result.nextCursor ?? null }, 200, rate.headers)
+}
+
+export async function soulsGetRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/souls/')
+  if (segments.length === 0) return text('Missing slug', 400, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  const second = segments[1]
+  const third = segments[2]
+
+  if (segments.length === 1) {
+    const result = (await ctx.runQuery(api.souls.getBySlug, { slug })) as GetSoulBySlugResult
+    if (!result?.soul) return text('Soul not found', 404, rate.headers)
+
+    const [tags] = await resolveSoulTagsBatch(ctx, [result.soul.tags])
+    return json(
+      {
+        soul: {
+          slug: result.soul.slug,
+          displayName: result.soul.displayName,
+          summary: result.soul.summary ?? null,
+          tags,
+          stats: result.soul.stats,
+          createdAt: result.soul.createdAt,
+          updatedAt: result.soul.updatedAt,
+        },
+        latestVersion: result.latestVersion
+          ? {
+              version: result.latestVersion.version,
+              createdAt: result.latestVersion.createdAt,
+              changelog: result.latestVersion.changelog,
+            }
+          : null,
+        owner: result.owner
+          ? {
+              handle: result.owner.handle ?? null,
+              displayName: result.owner.displayName ?? null,
+              image: result.owner.image ?? null,
+            }
+          : null,
+      },
+      200,
+      rate.headers,
+    )
+  }
+
+  if (second === 'versions' && segments.length === 2) {
+    const soul = await ctx.runQuery(internal.souls.getSoulBySlugInternal, { slug })
+    if (!soul || soul.softDeletedAt) return text('Soul not found', 404, rate.headers)
+
+    const url = new URL(request.url)
+    const limit = toOptionalNumber(url.searchParams.get('limit'))
+    const cursor = url.searchParams.get('cursor')?.trim() || undefined
+    const result = (await ctx.runQuery(api.souls.listVersionsPage, {
+      soulId: soul._id,
+      limit,
+      cursor,
+    })) as ListSoulVersionsResult
+
+    const items = result.items
+      .filter((version) => !version.softDeletedAt)
+      .map((version) => ({
+        version: version.version,
+        createdAt: version.createdAt,
+        changelog: version.changelog,
+        changelogSource: version.changelogSource ?? null,
+      }))
+
+    return json({ items, nextCursor: result.nextCursor ?? null }, 200, rate.headers)
+  }
+
+  if (second === 'versions' && third && segments.length === 3) {
+    const soul = await ctx.runQuery(internal.souls.getSoulBySlugInternal, { slug })
+    if (!soul || soul.softDeletedAt) return text('Soul not found', 404, rate.headers)
+
+    const version = await ctx.runQuery(api.souls.getVersionBySoulAndVersion, {
+      soulId: soul._id,
+      version: third,
+    })
+    if (!version) return text('Version not found', 404, rate.headers)
+    if (version.softDeletedAt) return text('Version not available', 410, rate.headers)
+
+    return json(
+      {
+        soul: { slug: soul.slug, displayName: soul.displayName },
+        version: {
+          version: version.version,
+          createdAt: version.createdAt,
+          changelog: version.changelog,
+          changelogSource: version.changelogSource ?? null,
+          files: version.files.map((file: SoulFile) => ({
+            path: file.path,
+            size: file.size,
+            sha256: file.sha256,
+            contentType: file.contentType ?? null,
+          })),
+        },
+      },
+      200,
+      rate.headers,
+    )
+  }
+
+  if (second === 'file' && segments.length === 2) {
+    const url = new URL(request.url)
+    const path = url.searchParams.get('path')?.trim()
+    if (!path) return text('Missing path', 400, rate.headers)
+    const versionParam = url.searchParams.get('version')?.trim()
+    const tagParam = url.searchParams.get('tag')?.trim()
+
+    const soulResult = (await ctx.runQuery(api.souls.getBySlug, { slug })) as GetSoulBySlugResult
+    if (!soulResult?.soul) return text('Soul not found', 404, rate.headers)
+
+    let version = soulResult.latestVersion
+    if (versionParam) {
+      version = await ctx.runQuery(api.souls.getVersionBySoulAndVersion, {
+        soulId: soulResult.soul._id,
+        version: versionParam,
+      })
+    } else if (tagParam) {
+      const versionId = soulResult.soul.tags[tagParam]
+      if (versionId) {
+        version = await ctx.runQuery(api.souls.getVersionById, { versionId })
+      }
+    }
+
+    if (!version) return text('Version not found', 404, rate.headers)
+    if (version.softDeletedAt) return text('Version not available', 410, rate.headers)
+
+    const normalized = path.trim()
+    const normalizedLower = normalized.toLowerCase()
+    const file =
+      version.files.find((entry) => entry.path === normalized) ??
+      version.files.find((entry) => entry.path.toLowerCase() === normalizedLower)
+    if (!file) return text('File not found', 404, rate.headers)
+    if (file.size > MAX_RAW_FILE_BYTES) return text('File exceeds 200KB limit', 413, rate.headers)
+
+    const blob = await ctx.storage.get(file.storageId)
+    if (!blob) return text('File missing in storage', 410, rate.headers)
+    const textContent = await blob.text()
+
+    void ctx.runMutation(api.soulDownloads.increment, { soulId: soulResult.soul._id })
+    return safeTextFileResponse({
+      textContent,
+      path: file.path,
+      contentType: file.contentType ?? undefined,
+      sha256: file.sha256,
+      size: file.size,
+      headers: rate.headers,
+    })
+  }
+
+  return text('Not found', 404, rate.headers)
+}
+
+export async function publishSoulV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  try {
+    if (!parseBearerToken(request)) return text('Unauthorized', 401, rate.headers)
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+  const { userId } = await requireApiTokenUser(ctx, request)
+
+  const contentType = request.headers.get('content-type') ?? ''
+  try {
+    if (contentType.includes('application/json')) {
+      const body = await request.json()
+      const payload = parsePublishBody(body)
+      const result = await publishSoulVersionForUser(ctx, userId, payload)
+      return json({ ok: true, ...result }, 200, rate.headers)
+    }
+
+    if (contentType.includes('multipart/form-data')) {
+      const payload = await parseMultipartPublish(ctx, request)
+      const result = await publishSoulVersionForUser(ctx, userId, payload)
+      return json({ ok: true, ...result }, 200, rate.headers)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Publish failed'
+    return text(message, 400, rate.headers)
+  }
+
+  return text('Unsupported content type', 415, rate.headers)
+}
+
+export async function soulsPostRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/souls/')
+  if (segments.length !== 2 || segments[1] !== 'undelete') {
+    return text('Not found', 404, rate.headers)
+  }
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    await ctx.runMutation(internal.souls.setSoulSoftDeletedInternal, {
+      userId,
+      slug,
+      deleted: false,
+    })
+    return json({ ok: true }, 200, rate.headers)
+  } catch (error) {
+    return softDeleteErrorToResponse('soul', error, rate.headers)
+  }
+}
+
+export async function soulsDeleteRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/souls/')
+  if (segments.length !== 1) return text('Not found', 404, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    await ctx.runMutation(internal.souls.setSoulSoftDeletedInternal, {
+      userId,
+      slug,
+      deleted: true,
+    })
+    return json({ ok: true }, 200, rate.headers)
+  } catch (error) {
+    return softDeleteErrorToResponse('soul', error, rate.headers)
+  }
+}
@@ -0,0 +1,51 @@
+import { internal } from '../_generated/api'
+import type { ActionCtx } from '../_generated/server'
+import { requireApiTokenUser } from '../lib/apiTokenAuth'
+import { applyRateLimit } from '../lib/httpRateLimit'
+import { getPathSegments, json, text } from './shared'
+
+export async function starsPostRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/stars/')
+  if (segments.length !== 1) return text('Not found', 404, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+    if (!skill) return text('Skill not found', 404, rate.headers)
+
+    const result = await ctx.runMutation(internal.stars.addStarInternal, {
+      userId,
+      skillId: skill._id,
+    })
+    return json(result, 200, rate.headers)
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+}
+
+export async function starsDeleteRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/stars/')
+  if (segments.length !== 1) return text('Not found', 404, rate.headers)
+  const slug = segments[0]?.trim().toLowerCase() ?? ''
+
+  try {
+    const { userId } = await requireApiTokenUser(ctx, request)
+    const skill = await ctx.runQuery(internal.skills.getSkillBySlugInternal, { slug })
+    if (!skill) return text('Skill not found', 404, rate.headers)
+
+    const result = await ctx.runMutation(internal.stars.removeStarInternal, {
+      userId,
+      skillId: skill._id,
+    })
+    return json(result, 200, rate.headers)
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+}
@@ -0,0 +1,247 @@
+import { api, internal } from '../_generated/api'
+import type { Id } from '../_generated/dataModel'
+import type { ActionCtx } from '../_generated/server'
+import { requireApiTokenUser } from '../lib/apiTokenAuth'
+import { applyRateLimit } from '../lib/httpRateLimit'
+import {
+  getPathSegments,
+  json,
+  parseJsonPayload,
+  requireAdminOrResponse,
+  requireApiTokenUserOrResponse,
+  text,
+  toOptionalNumber,
+} from './shared'
+
+export async function usersPostRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'write')
+  if (!rate.ok) return rate.response
+
+  const segments = getPathSegments(request, '/api/v1/users/')
+  if (segments.length !== 1) {
+    return text('Not found', 404, rate.headers)
+  }
+  const action = segments[0]
+  if (action !== 'ban' && action !== 'role' && action !== 'restore' && action !== 'reclaim') {
+    return text('Not found', 404, rate.headers)
+  }
+
+  const payloadResult = await parseJsonPayload(request, rate.headers)
+  if (!payloadResult.ok) return payloadResult.response
+  const payload = payloadResult.payload
+
+  const authResult = await requireApiTokenUserOrResponse(ctx, request, rate.headers)
+  if (!authResult.ok) return authResult.response
+  const actorUserId = authResult.userId
+  const actorUser = authResult.user
+
+  // Restore and reclaim have different parameter shapes, handle them separately
+  if (action === 'restore') {
+    const admin = requireAdminOrResponse(actorUser, rate.headers)
+    if (!admin.ok) return admin.response
+    return handleAdminRestore(ctx, request, payload, actorUserId, rate.headers)
+  }
+
+  if (action === 'reclaim') {
+    const admin = requireAdminOrResponse(actorUser, rate.headers)
+    if (!admin.ok) return admin.response
+    return handleAdminReclaim(ctx, request, payload, actorUserId, rate.headers)
+  }
+
+  const handleRaw = typeof payload.handle === 'string' ? payload.handle.trim() : ''
+  const userIdRaw = typeof payload.userId === 'string' ? payload.userId.trim() : ''
+  const reasonRaw = typeof payload.reason === 'string' ? payload.reason.trim() : ''
+  if (!handleRaw && !userIdRaw) {
+    return text('Missing userId or handle', 400, rate.headers)
+  }
+
+  const roleRaw = typeof payload.role === 'string' ? payload.role.trim().toLowerCase() : ''
+  if (action === 'role' && !roleRaw) {
+    return text('Missing role', 400, rate.headers)
+  }
+  const role = roleRaw === 'user' || roleRaw === 'moderator' || roleRaw === 'admin' ? roleRaw : null
+  if (action === 'role' && !role) {
+    return text('Invalid role', 400, rate.headers)
+  }
+
+  let targetUserId: Id<'users'> | null = userIdRaw ? (userIdRaw as Id<'users'>) : null
+  if (!targetUserId) {
+    const handle = handleRaw.toLowerCase()
+    const user = await ctx.runQuery(api.users.getByHandle, { handle })
+    if (!user?._id) return text('User not found', 404, rate.headers)
+    targetUserId = user._id
+  }
+
+  if (action === 'ban') {
+    const reason = reasonRaw.length > 0 ? reasonRaw : undefined
+    if (reason && reason.length > 500) {
+      return text('Reason too long (max 500 chars)', 400, rate.headers)
+    }
+    try {
+      const result = await ctx.runMutation(internal.users.banUserInternal, {
+        actorUserId,
+        targetUserId,
+        reason,
+      })
+      return json(result, 200, rate.headers)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Ban failed'
+      if (message.toLowerCase().includes('forbidden')) {
+        return text('Forbidden', 403, rate.headers)
+      }
+      if (message.toLowerCase().includes('not found')) {
+        return text(message, 404, rate.headers)
+      }
+      return text(message, 400, rate.headers)
+    }
+  }
+
+  if (!role) {
+    return text('Invalid role', 400, rate.headers)
+  }
+
+  try {
+    const result = await ctx.runMutation(internal.users.setRoleInternal, {
+      actorUserId,
+      targetUserId,
+      role,
+    })
+    return json({ ok: true, role: result.role ?? role }, 200, rate.headers)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Role change failed'
+    if (message.toLowerCase().includes('forbidden')) {
+      return text('Forbidden', 403, rate.headers)
+    }
+    if (message.toLowerCase().includes('not found')) {
+      return text(message, 404, rate.headers)
+    }
+    return text(message, 400, rate.headers)
+  }
+}
+
+/**
+ * POST /api/v1/users/restore
+ * Admin-only: restore skills from GitHub backup for a user.
+ * Body: { handle: string, slugs: string[], forceOverwriteSquatter?: boolean }
+ */
+async function handleAdminRestore(
+  ctx: ActionCtx,
+  _request: Request,
+  payload: Record<string, unknown>,
+  actorUserId: Id<'users'>,
+  headers: HeadersInit,
+) {
+  const handle = typeof payload.handle === 'string' ? payload.handle.trim().toLowerCase() : ''
+  if (!handle) return text('Missing handle', 400, headers)
+
+  const slugs = Array.isArray(payload.slugs) ? payload.slugs.filter((s): s is string => typeof s === 'string') : []
+  if (slugs.length === 0) return text('Missing slugs array', 400, headers)
+  if (slugs.length > 100) return text('Too many slugs (max 100)', 400, headers)
+
+  const forceOverwriteSquatter = Boolean(payload.forceOverwriteSquatter)
+
+  const targetUser = await ctx.runQuery(api.users.getByHandle, { handle })
+  if (!targetUser?._id) return text('User not found', 404, headers)
+
+  try {
+    const result = await ctx.runAction(internal.githubRestore.restoreUserSkillsFromBackup, {
+      actorUserId,
+      ownerHandle: handle,
+      ownerUserId: targetUser._id,
+      slugs,
+      forceOverwriteSquatter,
+    })
+    return json(result, 200, headers)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Restore failed'
+    if (message.toLowerCase().includes('forbidden')) {
+      return text('Forbidden', 403, headers)
+    }
+    return text(message, 400, headers)
+  }
+}
+
+/**
+ * POST /api/v1/users/reclaim
+ * Admin-only: reclaim root slugs for the rightful owner.
+ * Default behavior is non-destructive owner transfer for existing skills
+ * (preserves versions/stats/metadata) and leaves missing slugs untouched.
+ * Body: { handle: string, slugs: string[], reason?: string }
+ */
+async function handleAdminReclaim(
+  ctx: ActionCtx,
+  _request: Request,
+  payload: Record<string, unknown>,
+  actorUserId: Id<'users'>,
+  headers: HeadersInit,
+) {
+  const handle = typeof payload.handle === 'string' ? payload.handle.trim().toLowerCase() : ''
+  if (!handle) return text('Missing handle', 400, headers)
+
+  const slugs = Array.isArray(payload.slugs) ? payload.slugs.filter((s): s is string => typeof s === 'string') : []
+  if (slugs.length === 0) return text('Missing slugs array', 400, headers)
+  if (slugs.length > 200) return text('Too many slugs (max 200)', 400, headers)
+
+  const reason = typeof payload.reason === 'string' ? payload.reason.trim() : undefined
+
+  const targetUser = await ctx.runQuery(api.users.getByHandle, { handle })
+  if (!targetUser?._id) return text('User not found', 404, headers)
+
+  const results: Array<{ slug: string; ok: boolean; action?: string; error?: string }> = []
+  for (const slug of slugs) {
+    try {
+      const result = (await ctx.runMutation(internal.skills.reclaimSlugInternal, {
+        actorUserId,
+        slug: slug.trim().toLowerCase(),
+        rightfulOwnerUserId: targetUser._id,
+        reason,
+        transferRootSlugOnly: true,
+      })) as { action?: string }
+      results.push({ slug, ok: true, action: result.action })
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Reclaim failed'
+      results.push({ slug, ok: false, error: message })
+    }
+  }
+
+  const succeeded = results.filter((r) => r.ok).length
+  const failed = results.filter((r) => !r.ok).length
+
+  return json({ ok: true, results, succeeded, failed }, 200, headers)
+}
+
+export async function usersListV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  const url = new URL(request.url)
+  const limitRaw = toOptionalNumber(url.searchParams.get('limit'))
+  const query = url.searchParams.get('q') ?? url.searchParams.get('query') ?? ''
+
+  let actorUserId: Id<'users'>
+  try {
+    const auth = await requireApiTokenUser(ctx, request)
+    actorUserId = auth.userId
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+
+  const limit = Math.min(Math.max(limitRaw ?? 20, 1), 200)
+  try {
+    const result = await ctx.runQuery(internal.users.searchInternal, {
+      actorUserId,
+      query,
+      limit,
+    })
+    return json(result, 200, rate.headers)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'User search failed'
+    if (message.toLowerCase().includes('forbidden')) {
+      return text('Forbidden', 403, rate.headers)
+    }
+    if (message.toLowerCase().includes('unauthorized')) {
+      return text('Unauthorized', 401, rate.headers)
+    }
+    return text(message, 400, rate.headers)
+  }
+}
@@ -0,0 +1,26 @@
+import type { ActionCtx } from '../_generated/server'
+import { requireApiTokenUser } from '../lib/apiTokenAuth'
+import { applyRateLimit } from '../lib/httpRateLimit'
+import { json, text } from './shared'
+
+export async function whoamiV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, 'read')
+  if (!rate.ok) return rate.response
+
+  try {
+    const { user } = await requireApiTokenUser(ctx, request)
+    return json(
+      {
+        user: {
+          handle: user.handle ?? null,
+          displayName: user.displayName ?? null,
+          image: user.image ?? null,
+        },
+      },
+      200,
+      rate.headers,
+    )
+  } catch {
+    return text('Unauthorized', 401, rate.headers)
+  }
+}
@@ -0,0 +1,37 @@
+import { httpAction } from './_generated/server'
+import { corsHeaders, mergeHeaders } from './lib/httpHeaders'
+
+function getHeader(request: Request, name: string) {
+  return request.headers.get(name) ?? request.headers.get(name.toLowerCase())
+}
+
+export function buildPreflightHeaders(request: Request) {
+  const requestedHeaders = getHeader(request, 'Access-Control-Request-Headers')?.trim() || null
+  const requestedMethod = getHeader(request, 'Access-Control-Request-Method')?.trim() || null
+
+  const vary = [
+    ...(requestedMethod ? ['Access-Control-Request-Method'] : []),
+    ...(requestedHeaders ? ['Access-Control-Request-Headers'] : []),
+  ].join(', ')
+
+  return mergeHeaders(
+    corsHeaders(),
+    {
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD',
+      'Access-Control-Allow-Headers':
+        requestedHeaders ?? 'Content-Type, Authorization, Digest, X-Clawhub-Version',
+      'Access-Control-Max-Age': '86400',
+      ...(vary ? { Vary: vary } : {}),
+    },
+  )
+}
+
+export const preflightHandler = httpAction(async (_ctx, request) => {
+  // No cookies/credentials supported; allow any origin for simple browser access.
+  // If we ever add cookie auth, this must switch to reflecting origin + Allow-Credentials.
+  return new Response(null, {
+    status: 204,
+    headers: buildPreflightHeaders(request),
+  })
+})
+
@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from 'vitest'
+
+vi.mock('@convex-dev/auth/server', () => ({
+  getAuthUserId: vi.fn(),
+}))
+
+const { getAuthUserId } = await import('@convex-dev/auth/server')
+const {
+  assertAdmin,
+  assertModerator,
+  assertRole,
+  requireUser,
+  requireUserFromAction,
+} = await import('./access')
+
+describe('access.requireUser', () => {
+  it('throws when auth is missing', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue(null)
+    await expect(
+      requireUser({
+        db: { get: vi.fn() },
+      } as never),
+    ).rejects.toThrow('Unauthorized')
+  })
+
+  it('throws when user is deleted/deactivated/missing', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue('users:1' as never)
+
+    for (const value of [null, { _id: 'users:1', deletedAt: Date.now() }, { _id: 'users:1', deactivatedAt: Date.now() }]) {
+      const dbGet = vi.fn().mockResolvedValue(value as never)
+      await expect(
+        requireUser({
+          db: { get: dbGet },
+        } as never),
+      ).rejects.toThrow('User not found')
+    }
+  })
+
+  it('returns auth user when active', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue('users:2' as never)
+    const user = { _id: 'users:2', role: 'user' }
+    const dbGet = vi.fn().mockResolvedValue(user as never)
+
+    const result = await requireUser({
+      db: { get: dbGet },
+    } as never)
+
+    expect(dbGet).toHaveBeenCalledWith('users:2')
+    expect(result).toEqual({ userId: 'users:2', user })
+  })
+})
+
+describe('access.requireUserFromAction', () => {
+  it('throws when auth is missing', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue(null)
+    await expect(
+      requireUserFromAction({
+        runQuery: vi.fn(),
+      } as never),
+    ).rejects.toThrow('Unauthorized')
+  })
+
+  it('throws when action lookup returns deleted/deactivated/missing user', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue('users:1' as never)
+
+    for (const value of [null, { _id: 'users:1', deletedAt: Date.now() }, { _id: 'users:1', deactivatedAt: Date.now() }]) {
+      const runQuery = vi.fn().mockResolvedValue(value as never)
+      await expect(
+        requireUserFromAction({
+          runQuery,
+        } as never),
+      ).rejects.toThrow('User not found')
+    }
+  })
+
+  it('returns active user from action query', async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue('users:9' as never)
+    const user = { _id: 'users:9', role: 'admin' }
+    const runQuery = vi.fn().mockResolvedValue(user as never)
+
+    const result = await requireUserFromAction({
+      runQuery,
+    } as never)
+
+    expect(runQuery).toHaveBeenCalledTimes(1)
+    expect(result).toEqual({ userId: 'users:9', user })
+  })
+})
+
+describe('access role assertions', () => {
+  it('assertRole allows matching roles and rejects missing role', () => {
+    expect(() => assertRole({ role: 'admin' } as never, ['admin'])).not.toThrow()
+    expect(() => assertRole({ role: undefined } as never, ['admin'])).toThrow('Forbidden')
+    expect(() => assertRole({ role: 'user' } as never, ['admin'])).toThrow('Forbidden')
+  })
+
+  it('assertAdmin/assertModerator enforce expected policy', () => {
+    expect(() => assertAdmin({ role: 'admin' } as never)).not.toThrow()
+    expect(() => assertAdmin({ role: 'moderator' } as never)).toThrow('Forbidden')
+
+    expect(() => assertModerator({ role: 'admin' } as never)).not.toThrow()
+    expect(() => assertModerator({ role: 'moderator' } as never)).not.toThrow()
+    expect(() => assertModerator({ role: 'user' } as never)).toThrow('Forbidden')
+  })
+})
@@ -1,6 +1,6 @@
 import { getAuthUserId } from '@convex-dev/auth/server'
 import { internal } from '../_generated/api'
-import type { Doc } from '../_generated/dataModel'
+import type { Doc, Id } from '../_generated/dataModel'
 import type { ActionCtx, MutationCtx, QueryCtx } from '../_generated/server'

 export type Role = 'admin' | 'moderator' | 'user'
@@ -9,15 +9,17 @@ export async function requireUser(ctx: MutationCtx | QueryCtx) {
  const userId = await getAuthUserId(ctx)
  if (!userId) throw new Error('Unauthorized')
  const user = await ctx.db.get(userId)
-  if (!user || user.deletedAt) throw new Error('User not found')
+  if (!user || user.deletedAt || user.deactivatedAt) throw new Error('User not found')
  return { userId, user }
 }

-export async function requireUserFromAction(ctx: ActionCtx) {
+export async function requireUserFromAction(
+  ctx: ActionCtx,
+): Promise<{ userId: Id<'users'>; user: Doc<'users'> }> {
  const userId = await getAuthUserId(ctx)
  if (!userId) throw new Error('Unauthorized')
  const user = await ctx.runQuery(internal.users.getByIdInternal, { userId })
-  if (!user || user.deletedAt) throw new Error('User not found')
+  if (!user || user.deletedAt || user.deactivatedAt) throw new Error('User not found')
  return { userId, user: user as Doc<'users'> }
 }

@@ -0,0 +1,110 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getOptionalApiTokenUserId } from './apiTokenAuth'
+import { hashToken } from './tokens'
+
+describe('getOptionalApiTokenUserId', () => {
+  it('returns null when auth header is missing', async () => {
+    const ctx = {
+      runQuery: vi.fn(),
+    }
+    const request = new Request('https://example.com')
+
+    const userId = await getOptionalApiTokenUserId(ctx as never, request)
+
+    expect(userId).toBeNull()
+    expect(ctx.runQuery).not.toHaveBeenCalled()
+  })
+
+  it('returns null for unknown token', async () => {
+    const ctx = {
+      runQuery: vi.fn().mockResolvedValue(null),
+    }
+    const request = new Request('https://example.com', {
+      headers: { authorization: 'Bearer token-1' },
+    })
+
+    const userId = await getOptionalApiTokenUserId(ctx as never, request)
+
+    expect(userId).toBeNull()
+    expect(ctx.runQuery).toHaveBeenCalledTimes(1)
+    expect(ctx.runQuery.mock.calls[0]?.[1]).toEqual({
+      tokenHash: await hashToken('token-1'),
+    })
+  })
+
+  it('returns user id when token and user are valid', async () => {
+    const tokenId = 'apiTokens_1'
+    const expectedUserId = 'users_1'
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockImplementation(async (_fn, args: { tokenHash?: string; tokenId?: string }) => {
+          if (args.tokenHash) {
+            return { _id: tokenId, revokedAt: undefined }
+          }
+          if (args.tokenId) {
+            return { _id: expectedUserId, deletedAt: undefined }
+          }
+          return null
+        }),
+    }
+    const request = new Request('https://example.com', {
+      headers: { authorization: 'Bearer token-2' },
+    })
+
+    const userId = await getOptionalApiTokenUserId(ctx as never, request)
+
+    expect(userId).toBe(expectedUserId)
+    expect(ctx.runQuery).toHaveBeenCalledTimes(2)
+  })
+
+  it('returns null when user is deleted', async () => {
+    const tokenId = 'apiTokens_2'
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockImplementation(async (_fn, args: { tokenHash?: string; tokenId?: string }) => {
+          if (args.tokenHash) {
+            return { _id: tokenId, revokedAt: undefined }
+          }
+          if (args.tokenId) {
+            return { _id: 'users_deleted', deletedAt: Date.now() }
+          }
+          return null
+        }),
+    }
+    const request = new Request('https://example.com', {
+      headers: { authorization: 'Bearer token-3' },
+    })
+
+    const userId = await getOptionalApiTokenUserId(ctx as never, request)
+
+    expect(userId).toBeNull()
+    expect(ctx.runQuery).toHaveBeenCalledTimes(2)
+  })
+
+  it('returns null when user is deactivated', async () => {
+    const tokenId = 'apiTokens_3'
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockImplementation(async (_fn, args: { tokenHash?: string; tokenId?: string }) => {
+          if (args.tokenHash) {
+            return { _id: tokenId, revokedAt: undefined }
+          }
+          if (args.tokenId) {
+            return { _id: 'users_deactivated', deactivatedAt: Date.now() }
+          }
+          return null
+        }),
+    }
+    const request = new Request('https://example.com', {
+      headers: { authorization: 'Bearer token-4' },
+    })
+
+    const userId = await getOptionalApiTokenUserId(ctx as never, request)
+
+    expect(userId).toBeNull()
+    expect(ctx.runQuery).toHaveBeenCalledTimes(2)
+  })
+})
@@ -21,12 +21,32 @@ export async function requireApiTokenUser(
  const user = await ctx.runQuery(internal.tokens.getUserForTokenInternal, {
    tokenId: apiToken._id,
  })
-  if (!user || user.deletedAt) throw new ConvexError('Unauthorized')
+  if (!user || user.deletedAt || user.deactivatedAt) throw new ConvexError('Unauthorized')

  await ctx.runMutation(internal.tokens.touchInternal, { tokenId: apiToken._id })
  return { user, userId: user._id }
 }

+export async function getOptionalApiTokenUserId(
+  ctx: ActionCtx,
+  request: Request,
+): Promise<Doc<'users'>['_id'] | null> {
+  const header = request.headers.get('authorization') ?? request.headers.get('Authorization')
+  const token = parseBearerToken(header)
+  if (!token) return null
+
+  const tokenHash = await hashToken(token)
+  const apiToken = await ctx.runQuery(internal.tokens.getByHashInternal, { tokenHash })
+  if (!apiToken || apiToken.revokedAt) return null
+
+  const user = await ctx.runQuery(internal.tokens.getUserForTokenInternal, {
+    tokenId: apiToken._id,
+  })
+  if (!user || user.deletedAt || user.deactivatedAt) return null
+
+  return user._id
+}
+
 function parseBearerToken(header: string | null) {
  if (!header) return null
  const trimmed = header.trim()
@@ -35,7 +35,7 @@ export async function getSkillBadgeMap(
  const records = await ctx.db
    .query('skillBadges')
    .withIndex('by_skill', (q) => q.eq('skillId', skillId))
-    .collect()
+    .take(10)
  return buildBadgeMap(records)
 }

@@ -0,0 +1,15 @@
+import type { Scheduler } from 'convex/server'
+
+export function scheduleNextBatchIfNeeded<TArgs extends { cursor?: string }>(
+  scheduler: Scheduler,
+  fn: unknown,
+  args: TArgs,
+  isDone: boolean,
+  continueCursor: string | null,
+) {
+  if (isDone) return
+  void scheduler.runAfter(0, fn as never, {
+    ...args,
+    cursor: continueCursor ?? undefined,
+  } as never)
+}
@@ -1,6 +1,7 @@
 import { internal } from '../_generated/api'
 import type { Doc, Id } from '../_generated/dataModel'
 import type { ActionCtx } from '../_generated/server'
+import { extractResponseText } from './openaiResponse'

 const CHANGELOG_MODEL = process.env.OPENAI_CHANGELOG_MODEL ?? 'gpt-4.1'
 const MAX_README_CHARS = 8_000
@@ -59,27 +60,6 @@ function pickPaths(values: string[]) {
  return values.slice(0, MAX_PATHS_IN_PROMPT)
 }

-function extractResponseText(payload: unknown) {
-  if (!payload || typeof payload !== 'object') return null
-  const output = (payload as { output?: unknown }).output
-  if (!Array.isArray(output)) return null
-  const chunks: string[] = []
-  for (const item of output) {
-    if (!item || typeof item !== 'object') continue
-    if ((item as { type?: unknown }).type !== 'message') continue
-    const content = (item as { content?: unknown }).content
-    if (!Array.isArray(content)) continue
-    for (const part of content) {
-      if (!part || typeof part !== 'object') continue
-      if ((part as { type?: unknown }).type !== 'output_text') continue
-      const text = (part as { text?: unknown }).text
-      if (typeof text === 'string' && text.trim()) chunks.push(text)
-    }
-  }
-  const joined = chunks.join('\n').trim()
-  return joined || null
-}
-
 async function generateWithOpenAI(args: {
  slug: string
  version: string
@@ -0,0 +1,77 @@
+/* @vitest-environment node */
+import { describe, expect, it } from 'vitest'
+import {
+  assembleCommentScamEvalUserMessage,
+  buildCommentScamBanReason,
+  isCertainScam,
+  parseCommentScamEvalResponse,
+} from './commentScamPrompt'
+
+describe('commentScamPrompt', () => {
+  it('parses valid JSON response', () => {
+    const parsed = parseCommentScamEvalResponse(
+      JSON.stringify({
+        verdict: 'certain_scam',
+        confidence: 'high',
+        explanation: 'Comment instructs users to decode base64 and pipe to bash.',
+        evidence: ['echo + base64 -D | bash', 'fake update-service domain'],
+      }),
+    )
+
+    expect(parsed).toEqual({
+      verdict: 'certain_scam',
+      confidence: 'high',
+      explanation: 'Comment instructs users to decode base64 and pipe to bash.',
+      evidence: ['echo + base64 -D | bash', 'fake update-service domain'],
+    })
+  })
+
+  it('parses markdown-fenced JSON', () => {
+    const parsed = parseCommentScamEvalResponse(`\`\`\`json
+{"verdict":"likely_scam","confidence":"medium","explanation":"Suspicious terminal one-liner.","evidence":["curl | bash"]}
+\`\`\``)
+
+    expect(parsed).toMatchObject({
+      verdict: 'likely_scam',
+      confidence: 'medium',
+    })
+  })
+
+  it('rejects invalid response payloads', () => {
+    expect(parseCommentScamEvalResponse('{"verdict":"ban"}')).toBeNull()
+    expect(parseCommentScamEvalResponse('not-json')).toBeNull()
+  })
+
+  it('builds bounded ban reason', () => {
+    const reason = buildCommentScamBanReason({
+      commentId: 'comments:1',
+      skillId: 'skills:1',
+      explanation: 'A'.repeat(700),
+      evidence: ['B'.repeat(300), 'C'.repeat(300), 'D'.repeat(300), 'E'.repeat(300)],
+    })
+
+    expect(reason.length).toBeLessThanOrEqual(500)
+    expect(reason).toContain('commentId=comments:1')
+    expect(reason).toContain('skillId=skills:1')
+  })
+
+  it('marks certainty only for high-confidence certain_scam', () => {
+    expect(isCertainScam({ verdict: 'certain_scam', confidence: 'high' })).toBe(true)
+    expect(isCertainScam({ verdict: 'certain_scam', confidence: 'medium' })).toBe(false)
+    expect(isCertainScam({ verdict: 'likely_scam', confidence: 'high' })).toBe(false)
+  })
+
+  it('builds compact user message with context', () => {
+    const message = assembleCommentScamEvalUserMessage({
+      commentId: 'comments:1',
+      skillId: 'skills:3',
+      userId: 'users:9',
+      body: ' test ',
+    })
+
+    expect(message).toContain('Comment ID: comments:1')
+    expect(message).toContain('Skill ID: skills:3')
+    expect(message).toContain('Author User ID: users:9')
+    expect(message).toContain('test')
+  })
+})
@@ -0,0 +1,155 @@
+export type CommentScamVerdict = 'not_scam' | 'likely_scam' | 'certain_scam'
+export type CommentScamConfidence = 'low' | 'medium' | 'high'
+
+export type CommentScamEvalResponse = {
+  verdict: CommentScamVerdict
+  confidence: CommentScamConfidence
+  explanation: string
+  evidence: string[]
+}
+
+export const COMMENT_SCAM_EVAL_MAX_OUTPUT_TOKENS = 1200
+const MAX_COMMENT_CHARS = 4000
+const MAX_EXPLANATION_CHARS = 1200
+const MAX_EVIDENCE_ITEMS = 5
+const MAX_EVIDENCE_ITEM_CHARS = 160
+const MAX_BAN_REASON_CHARS = 500
+
+const VALID_VERDICTS = new Set<CommentScamVerdict>(['not_scam', 'likely_scam', 'certain_scam'])
+const VALID_CONFIDENCES = new Set<CommentScamConfidence>(['low', 'medium', 'high'])
+
+export const COMMENT_SCAM_EVALUATOR_SYSTEM_PROMPT = `You are a trust and safety classifier for user comments on a software registry.
+
+Goal: detect comment scams with high precision.
+
+A "certain_scam" verdict is only allowed when the comment clearly attempts fraud, credential theft, malware delivery, or social-engineering abuse.
+
+High-confidence scam patterns include:
+- Instructing users to run suspicious shell commands (especially obfuscated/base64/piped-to-bash/curl installer tricks).
+- Fake support/update instructions pointing to unknown domains, executables, or terminal one-liners.
+- Requests for private keys, seed phrases, passwords, API keys, session tokens, or wallet recovery data.
+- Impersonation or urgent pressure language to bypass trust checks.
+- Known scam payload structure (e.g. echo+base64+decode+bash, hidden downloader chains).
+
+Important anti-false-positive rules:
+- Do NOT mark legitimate troubleshooting or normal install instructions as "certain_scam" unless the malicious intent is explicit.
+- If suspicious but ambiguous, use "likely_scam".
+- If benign/unclear, use "not_scam".
+
+Output JSON only:
+{
+  "verdict": "not_scam" | "likely_scam" | "certain_scam",
+  "confidence": "low" | "medium" | "high",
+  "explanation": "short plain-language rationale",
+  "evidence": ["short concrete signal", "..."]
+}`
+
+export function getCommentScamEvalModel(): string {
+  return process.env.OPENAI_COMMENT_EVAL_MODEL ?? process.env.OPENAI_EVAL_MODEL ?? 'gpt-5-mini'
+}
+
+export function assembleCommentScamEvalUserMessage(args: {
+  commentId: string
+  skillId: string
+  userId: string
+  body: string
+}): string {
+  const trimmed = args.body.trim()
+  const body =
+    trimmed.length > MAX_COMMENT_CHARS
+      ? `${trimmed.slice(0, MAX_COMMENT_CHARS)}\n…[truncated]`
+      : trimmed
+
+  return [
+    `Comment ID: ${args.commentId}`,
+    `Skill ID: ${args.skillId}`,
+    `Author User ID: ${args.userId}`,
+    'Comment body:',
+    '```',
+    body,
+    '```',
+    'Respond with a single JSON object.',
+  ].join('\n')
+}
+
+function stripCodeFence(raw: string): string {
+  const text = raw.trim()
+  if (!text.startsWith('```')) return text
+  const firstNewline = text.indexOf('\n')
+  if (firstNewline === -1) return text
+  const withoutOpening = text.slice(firstNewline + 1)
+  const lastFence = withoutOpening.lastIndexOf('```')
+  if (lastFence === -1) return withoutOpening.trim()
+  return withoutOpening.slice(0, lastFence).trim()
+}
+
+function truncate(value: string, max: number): string {
+  if (value.length <= max) return value
+  if (max <= 3) return value.slice(0, max)
+  return `${value.slice(0, max - 3)}...`
+}
+
+export function parseCommentScamEvalResponse(raw: string): CommentScamEvalResponse | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(stripCodeFence(raw))
+  } catch {
+    return null
+  }
+
+  if (!parsed || typeof parsed !== 'object') return null
+  const obj = parsed as Record<string, unknown>
+
+  const verdict =
+    typeof obj.verdict === 'string' ? (obj.verdict.toLowerCase() as CommentScamVerdict) : null
+  if (!verdict || !VALID_VERDICTS.has(verdict)) return null
+
+  const confidence =
+    typeof obj.confidence === 'string'
+      ? (obj.confidence.toLowerCase() as CommentScamConfidence)
+      : null
+  if (!confidence || !VALID_CONFIDENCES.has(confidence)) return null
+
+  const rawExplanation = typeof obj.explanation === 'string' ? obj.explanation.trim() : ''
+  if (!rawExplanation) return null
+
+  const rawEvidence = Array.isArray(obj.evidence) ? obj.evidence : []
+  const evidence = rawEvidence
+    .map((item) => (typeof item === 'string' ? item.trim() : ''))
+    .filter(Boolean)
+    .slice(0, MAX_EVIDENCE_ITEMS)
+    .map((item) => truncate(item, MAX_EVIDENCE_ITEM_CHARS))
+
+  return {
+    verdict,
+    confidence,
+    explanation: truncate(rawExplanation, MAX_EXPLANATION_CHARS),
+    evidence,
+  }
+}
+
+export function isCertainScam(result: {
+  verdict: CommentScamVerdict
+  confidence: CommentScamConfidence
+}): boolean {
+  return result.verdict === 'certain_scam' && result.confidence === 'high'
+}
+
+export function buildCommentScamBanReason(args: {
+  commentId: string
+  skillId: string
+  explanation: string
+  evidence: string[]
+}): string {
+  const explanation = args.explanation.trim()
+  const evidence = args.evidence
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, 3)
+
+  const suffix = ` commentId=${args.commentId} skillId=${args.skillId}`
+  const evidenceSegment = evidence.length > 0 ? ` evidence: ${evidence.join('; ')}.` : ''
+  const core = `comment scam auto-ban. ${explanation}.${evidenceSegment}`
+  const maxCoreChars = Math.max(0, MAX_BAN_REASON_CHARS - suffix.length)
+  return `${truncate(core, maxCoreChars)}${suffix}`
+}
@@ -0,0 +1,18 @@
+const EXT_TO_TYPE: Record<string, string> = {
+  md: 'text/markdown',
+  mdx: 'text/markdown',
+  json: 'application/json',
+  json5: 'application/json',
+  yaml: 'application/yaml',
+  yml: 'application/yaml',
+  toml: 'application/toml',
+  svg: 'image/svg+xml',
+}
+
+export function guessContentTypeForPath(path: string) {
+  const trimmed = path.trim().toLowerCase()
+  if (!trimmed) return 'application/octet-stream'
+  const ext = trimmed.split('.').at(-1) ?? ''
+  return EXT_TO_TYPE[ext] ?? 'application/octet-stream'
+}
+
@@ -0,0 +1,17 @@
+export type EmbeddingVisibility =
+  | 'latest'
+  | 'latest-approved'
+  | 'archived'
+  | 'archived-approved'
+  | 'deleted'
+
+export function embeddingVisibilityFor(isLatest: boolean, isApproved: boolean): Exclude<
+  EmbeddingVisibility,
+  'deleted'
+> {
+  if (isLatest && isApproved) return 'latest-approved'
+  if (isLatest) return 'latest'
+  if (isApproved) return 'archived-approved'
+  return 'archived'
+}
+
@@ -0,0 +1,95 @@
+/* @vitest-environment node */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { EMBEDDING_DIMENSIONS, generateEmbedding } from './embeddings'
+
+const fetchMock = vi.fn<typeof fetch>()
+const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+const originalFetch = globalThis.fetch
+const originalApiKey = process.env.OPENAI_API_KEY
+
+function jsonResponse(payload: unknown, init?: ResponseInit) {
+  return new Response(JSON.stringify(payload), {
+    status: 200,
+    headers: {
+      'content-type': 'application/json',
+    },
+    ...init,
+  })
+}
+
+beforeEach(() => {
+  fetchMock.mockReset()
+  globalThis.fetch = fetchMock as typeof fetch
+  process.env.OPENAI_API_KEY = 'test-key'
+  consoleWarnSpy.mockClear()
+})
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+
+  if (originalApiKey === undefined) {
+    delete process.env.OPENAI_API_KEY
+  } else {
+    process.env.OPENAI_API_KEY = originalApiKey
+  }
+
+  vi.useRealTimers()
+})
+
+describe('generateEmbedding', () => {
+  it('returns zero embedding when OPENAI_API_KEY is missing', async () => {
+    delete process.env.OPENAI_API_KEY
+    const result = await generateEmbedding('hello world')
+
+    expect(result).toHaveLength(EMBEDDING_DIMENSIONS)
+    expect(result.every((value) => value === 0)).toBe(true)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('retries on 429 responses and then succeeds', async () => {
+    vi.useFakeTimers()
+    fetchMock.mockResolvedValueOnce(new Response('rate limited', { status: 429 }))
+    fetchMock.mockResolvedValueOnce(jsonResponse({ data: [{ embedding: [0.25, 0.75] }] }))
+
+    const promise = generateEmbedding('retry me')
+    await vi.runAllTimersAsync()
+
+    await expect(promise).resolves.toEqual([0.25, 0.75])
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry non-retryable 4xx responses', async () => {
+    fetchMock.mockResolvedValueOnce(new Response('bad request', { status: 400 }))
+
+    await expect(generateEmbedding('bad')).rejects.toThrow('Embedding failed: bad request')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries on network failures and then succeeds', async () => {
+    vi.useFakeTimers()
+    fetchMock.mockRejectedValueOnce(new TypeError('fetch failed'))
+    fetchMock.mockResolvedValueOnce(jsonResponse({ data: [{ embedding: [1, 2, 3] }] }))
+
+    const promise = generateEmbedding('network retry')
+    await vi.runAllTimersAsync()
+
+    await expect(promise).resolves.toEqual([1, 2, 3])
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries timeouts up to max attempts and preserves timeout error', async () => {
+    vi.useFakeTimers()
+    fetchMock.mockRejectedValue(new DOMException('aborted', 'AbortError'))
+
+    const promise = generateEmbedding('always timeout')
+    const rejection = expect(promise).rejects.toThrow(
+      'OpenAI API request timed out after 10 seconds',
+    )
+    await vi.runAllTimersAsync()
+
+    await rejection
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+  })
+})
@@ -1,10 +1,67 @@
 export const EMBEDDING_MODEL = 'text-embedding-3-small'
 export const EMBEDDING_DIMENSIONS = 1536

+const EMBEDDING_ENDPOINT = 'https://api.openai.com/v1/embeddings'
+const REQUEST_TIMEOUT_MS = 10_000
+const MAX_ATTEMPTS = 3
+const BASE_RETRY_DELAY_MS = 1_000
+
+class RetryableEmbeddingError extends Error {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'RetryableEmbeddingError'
+  }
+}
+
 function emptyEmbedding() {
  return Array.from({ length: EMBEDDING_DIMENSIONS }, () => 0)
 }

+function parseRetryAfterMs(retryAfterHeader: string | null) {
+  if (!retryAfterHeader) return null
+
+  const seconds = Number(retryAfterHeader)
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1000)
+  }
+
+  const dateMs = Date.parse(retryAfterHeader)
+  if (Number.isFinite(dateMs)) {
+    return Math.max(0, dateMs - Date.now())
+  }
+
+  return null
+}
+
+function getRetryDelayMs(attempt: number, retryAfterMs: number | null) {
+  const exponentialDelayMs = BASE_RETRY_DELAY_MS * 2 ** attempt
+  if (retryAfterMs == null) return exponentialDelayMs
+  return Math.max(exponentialDelayMs, retryAfterMs)
+}
+
+function normalizeRetryableNetworkError(error: unknown) {
+  if (!(error instanceof Error)) return null
+
+  if (error.name === 'AbortError') {
+    return new RetryableEmbeddingError(
+      `OpenAI API request timed out after ${Math.floor(REQUEST_TIMEOUT_MS / 1000)} seconds`,
+      { cause: error },
+    )
+  }
+
+  if (error instanceof TypeError) {
+    return new RetryableEmbeddingError(`Embedding request failed: ${error.message}`, { cause: error })
+  }
+
+  return null
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
 export async function generateEmbedding(text: string) {
  const apiKey = process.env.OPENAI_API_KEY
  if (!apiKey) {
@@ -12,27 +69,77 @@ export async function generateEmbedding(text: string) {
    return emptyEmbedding()
  }

-  const response = await fetch('https://api.openai.com/v1/embeddings', {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      model: EMBEDDING_MODEL,
-      input: text,
-    }),
-  })
+  let lastRetryableError: RetryableEmbeddingError | null = null

-  if (!response.ok) {
-    const message = await response.text()
-    throw new Error(`Embedding failed: ${message}`)
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+
+    try {
+      const response = await fetch(EMBEDDING_ENDPOINT, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: EMBEDDING_MODEL,
+          input: text,
+        }),
+        signal: controller.signal,
+      })
+
+      if (!response.ok) {
+        const message = await response.text()
+        const isRetryableStatus = response.status === 429 || response.status >= 500
+        if (isRetryableStatus) {
+          const retryableError = new RetryableEmbeddingError(
+            `Embedding failed (${response.status}): ${message}`,
+          )
+          lastRetryableError = retryableError
+
+          if (attempt < MAX_ATTEMPTS - 1) {
+            const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'))
+            const delayMs = getRetryDelayMs(attempt, retryAfterMs)
+            console.warn(
+              `OpenAI embeddings retry in ${delayMs}ms (attempt ${attempt + 1}/${MAX_ATTEMPTS})`,
+            )
+            await sleep(delayMs)
+            continue
+          }
+
+          throw retryableError
+        }
+
+        throw new Error(`Embedding failed: ${message}`)
+      }
+
+      const payload = (await response.json()) as {
+        data?: Array<{ embedding: number[] }>
+      }
+      const embedding = payload.data?.[0]?.embedding
+      if (!embedding) throw new Error('Embedding missing from response')
+      return embedding
+    } catch (error) {
+      const retryableNetworkError = normalizeRetryableNetworkError(error)
+      if (retryableNetworkError) {
+        lastRetryableError = retryableNetworkError
+        if (attempt < MAX_ATTEMPTS - 1) {
+          const delayMs = getRetryDelayMs(attempt, null)
+          console.warn(
+            `OpenAI embeddings network retry in ${delayMs}ms (attempt ${attempt + 1}/${MAX_ATTEMPTS})`,
+          )
+          await sleep(delayMs)
+          continue
+        }
+        throw retryableNetworkError
+      }
+
+      throw error
+    } finally {
+      clearTimeout(timeoutId)
+    }
  }

-  const payload = (await response.json()) as {
-    data?: Array<{ embedding: number[] }>
-  }
-  const embedding = payload.data?.[0]?.embedding
-  if (!embedding) throw new Error('Embedding missing from response')
-  return embedding
+  throw lastRetryableError ?? new Error('Embedding failed after retries')
 }
@@ -2,13 +2,17 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'

 import { internal } from '../_generated/api'
-import { requireGitHubAccountAge } from './githubAccount'
+import { requireGitHubAccountAge, syncGitHubProfile } from './githubAccount'

 vi.mock('../_generated/api', () => ({
  internal: {
+    githubIdentity: {
+      getGitHubProviderAccountIdInternal: Symbol('getGitHubProviderAccountIdInternal'),
+    },
    users: {
      getByIdInternal: Symbol('getByIdInternal'),
-      updateGithubMetaInternal: Symbol('updateGithubMetaInternal'),
+      setGitHubCreatedAtInternal: Symbol('setGitHubCreatedAtInternal'),
+      syncGitHubProfileInternal: Symbol('syncGitHubProfileInternal'),
    },
  },
 }))
@@ -19,21 +23,23 @@ describe('requireGitHubAccountAge', () => {
  beforeEach(() => {
    vi.restoreAllMocks()
    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
  })

  afterEach(() => {
+    vi.useRealTimers()
    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
  })

-  it('uses cached githubCreatedAt when fresh', async () => {
+  it('uses cached githubCreatedAt when present', async () => {
    vi.useFakeTimers()
    const now = new Date('2026-02-02T12:00:00Z')
    vi.setSystemTime(now)
+
    const runQuery = vi.fn().mockResolvedValue({
      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: now.getTime() - 10 * ONE_DAY_MS,
-      githubFetchedAt: now.getTime() - ONE_DAY_MS + 1000,
+      githubCreatedAt: now.getTime() - 20 * ONE_DAY_MS,
    })
    const runMutation = vi.fn()
    const fetchMock = vi.fn()
@@ -44,40 +50,55 @@ describe('requireGitHubAccountAge', () => {
    expect(fetchMock).not.toHaveBeenCalled()
    expect(runMutation).not.toHaveBeenCalled()
    expect(runQuery).toHaveBeenCalledWith(internal.users.getByIdInternal, { userId: 'users:1' })
-
-    vi.useRealTimers()
+    expect(runQuery).not.toHaveBeenCalledWith(
+      internal.githubIdentity.getGitHubProviderAccountIdInternal,
+      { userId: 'users:1' },
+    )
  })

-  it('rejects accounts younger than 7 days', async () => {
+  it('rejects deactivated users', async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      _id: 'users:1',
+      deactivatedAt: Date.now(),
+    })
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(
+      requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never),
+    ).rejects.toThrow(/User not found/i)
+
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('rejects accounts younger than 14 days', async () => {
    vi.useFakeTimers()
    const now = new Date('2026-02-02T12:00:00Z')
    vi.setSystemTime(now)
+
    const runQuery = vi.fn().mockResolvedValue({
      _id: 'users:1',
-      handle: 'newbie',
      githubCreatedAt: now.getTime() - 2 * ONE_DAY_MS,
-      githubFetchedAt: now.getTime() - ONE_DAY_MS / 2,
    })
    const runMutation = vi.fn()

    await expect(
      requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never),
-    ).rejects.toThrow(/GitHub account must be at least 7 days old/i)
-
-    vi.useRealTimers()
+    ).rejects.toThrow(/GitHub account must be at least 14 days old/i)
  })

-  it('refreshes githubCreatedAt when cache is stale', async () => {
+  it('fetches githubCreatedAt when missing (by providerAccountId)', async () => {
    vi.useFakeTimers()
    const now = new Date('2026-02-02T12:00:00Z')
    vi.setSystemTime(now)

-    const runQuery = vi.fn().mockResolvedValue({
-      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: undefined,
-      githubFetchedAt: now.getTime() - 2 * ONE_DAY_MS,
-    })
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
    const runMutation = vi.fn()
    const fetchMock = vi.fn().mockResolvedValue({
      ok: true,
@@ -90,27 +111,60 @@ describe('requireGitHubAccountAge', () => {
    await requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never)

    expect(fetchMock).toHaveBeenCalledWith(
-      'https://api.github.com/users/steipete',
+      'https://api.github.com/user/12345',
      expect.objectContaining({
        headers: expect.objectContaining({ 'User-Agent': 'clawhub' }),
      }),
    )
-    expect(runMutation).toHaveBeenCalledWith(internal.users.updateGithubMetaInternal, {
+    expect(runMutation).toHaveBeenCalledWith(internal.users.setGitHubCreatedAtInternal, {
      userId: 'users:1',
      githubCreatedAt: Date.parse('2020-01-01T00:00:00Z'),
-      githubFetchedAt: now.getTime(),
    })
+  })

-    vi.useRealTimers()
+  it('rejects when providerAccountId is missing', async () => {
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce(null)
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(
+      requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never),
+    ).rejects.toThrow(/GitHub account required/i)
+
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('rejects when providerAccountId is invalid', async () => {
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('abc123')
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(
+      requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never),
+    ).rejects.toThrow(/GitHub account lookup failed/i)
+
+    expect(fetchMock).not.toHaveBeenCalled()
  })

  it('throws when GitHub lookup fails', async () => {
-    const runQuery = vi.fn().mockResolvedValue({
-      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: undefined,
-      githubFetchedAt: 0,
-    })
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
    const runMutation = vi.fn()
    const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 404 })
    vi.stubGlobal('fetch', fetchMock)
@@ -121,12 +175,12 @@ describe('requireGitHubAccountAge', () => {
  })

  it('throws rate-limit error on 403', async () => {
-    const runQuery = vi.fn().mockResolvedValue({
-      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: undefined,
-      githubFetchedAt: 0,
-    })
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
    const runMutation = vi.fn()
    const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 403 })
    vi.stubGlobal('fetch', fetchMock)
@@ -137,12 +191,12 @@ describe('requireGitHubAccountAge', () => {
  })

  it('throws rate-limit error on 429', async () => {
-    const runQuery = vi.fn().mockResolvedValue({
-      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: undefined,
-      githubFetchedAt: 0,
-    })
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
    const runMutation = vi.fn()
    const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 429 })
    vi.stubGlobal('fetch', fetchMock)
@@ -152,6 +206,25 @@ describe('requireGitHubAccountAge', () => {
    ).rejects.toThrow(/rate limit exceeded/i)
  })

+  it('throws when GitHub returns an invalid payload', async () => {
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({}),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await expect(
+      requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never),
+    ).rejects.toThrow(/GitHub account lookup failed/i)
+  })
+
  it('includes Authorization header when GITHUB_TOKEN is set', async () => {
    vi.useFakeTimers()
    const now = new Date('2026-02-02T12:00:00Z')
@@ -159,12 +232,12 @@ describe('requireGitHubAccountAge', () => {

    vi.stubEnv('GITHUB_TOKEN', 'ghp_test123')

-    const runQuery = vi.fn().mockResolvedValue({
-      _id: 'users:1',
-      handle: 'steipete',
-      githubCreatedAt: undefined,
-      githubFetchedAt: now.getTime() - 2 * ONE_DAY_MS,
-    })
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        githubCreatedAt: undefined,
+      })
+      .mockResolvedValueOnce('12345')
    const runMutation = vi.fn()
    const fetchMock = vi.fn().mockResolvedValue({
      ok: true,
@@ -177,7 +250,7 @@ describe('requireGitHubAccountAge', () => {
    await requireGitHubAccountAge({ runQuery, runMutation } as never, 'users:1' as never)

    expect(fetchMock).toHaveBeenCalledWith(
-      'https://api.github.com/users/steipete',
+      'https://api.github.com/user/12345',
      expect.objectContaining({
        headers: {
          'User-Agent': 'clawhub',
@@ -185,7 +258,139 @@ describe('requireGitHubAccountAge', () => {
        },
      }),
    )
+  })
+})

+describe('syncGitHubProfile', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  afterEach(() => {
    vi.useRealTimers()
+    vi.unstubAllEnvs()
+    vi.unstubAllGlobals()
+  })
+
+  it('skips recent syncs (throttle)', async () => {
+    vi.useFakeTimers()
+    const now = new Date('2026-02-02T12:00:00Z')
+    vi.setSystemTime(now)
+
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        name: 'oldname',
+        githubProfileSyncedAt: now.getTime(),
+      })
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+
+    await syncGitHubProfile({ runQuery, runMutation } as never, 'users:1' as never)
+
+    expect(fetchMock).not.toHaveBeenCalled()
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('updates profile even when only avatar changes', async () => {
+    vi.useFakeTimers()
+    const now = new Date('2026-02-02T12:00:00Z')
+    vi.setSystemTime(now)
+
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        name: 'same',
+        image: 'https://avatars.githubusercontent.com/u/1?v=3',
+        githubProfileSyncedAt: now.getTime() - 10 * ONE_DAY_MS,
+      })
+      .mockResolvedValueOnce('12345')
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        login: 'same',
+        avatar_url: 'https://avatars.githubusercontent.com/u/1?v=4',
+      }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await syncGitHubProfile({ runQuery, runMutation } as never, 'users:1' as never)
+
+    expect(runMutation).toHaveBeenCalledWith(internal.users.syncGitHubProfileInternal, {
+      userId: 'users:1',
+      name: 'same',
+      image: 'https://avatars.githubusercontent.com/u/1?v=4',
+      syncedAt: now.getTime(),
+    })
+  })
+
+  it('updates name and records sync timestamp', async () => {
+    vi.useFakeTimers()
+    const now = new Date('2026-02-02T12:00:00Z')
+    vi.setSystemTime(now)
+
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        name: 'old',
+        githubProfileSyncedAt: now.getTime() - 10 * ONE_DAY_MS,
+      })
+      .mockResolvedValueOnce('12345')
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        login: 'new',
+        avatar_url: 'https://avatars.githubusercontent.com/u/1?v=1',
+      }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await syncGitHubProfile({ runQuery, runMutation } as never, 'users:1' as never)
+
+    expect(runMutation).toHaveBeenCalledWith(internal.users.syncGitHubProfileInternal, {
+      userId: 'users:1',
+      name: 'new',
+      image: 'https://avatars.githubusercontent.com/u/1?v=1',
+      syncedAt: now.getTime(),
+    })
+  })
+
+  it('forwards GitHub profile name (full name) when present', async () => {
+    vi.useFakeTimers()
+    const now = new Date('2026-02-02T12:00:00Z')
+    vi.setSystemTime(now)
+
+    const runQuery = vi.fn()
+      .mockResolvedValueOnce({
+        _id: 'users:1',
+        name: 'same',
+        githubProfileSyncedAt: now.getTime() - 10 * ONE_DAY_MS,
+      })
+      .mockResolvedValueOnce('12345')
+    const runMutation = vi.fn()
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        login: 'same',
+        name: 'Real Name',
+        avatar_url: 'https://avatars.githubusercontent.com/u/1?v=1',
+      }),
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    await syncGitHubProfile({ runQuery, runMutation } as never, 'users:1' as never)
+
+    expect(runMutation).toHaveBeenCalledWith(internal.users.syncGitHubProfileInternal, {
+      userId: 'users:1',
+      name: 'same',
+      image: 'https://avatars.githubusercontent.com/u/1?v=1',
+      profileName: 'Real Name',
+      syncedAt: now.getTime(),
+    })
  })
 })
@@ -2,36 +2,56 @@ import { ConvexError } from 'convex/values'
 import { internal } from '../_generated/api'
 import type { Id } from '../_generated/dataModel'
 import type { ActionCtx } from '../_generated/server'
+import { GITHUB_PROFILE_SYNC_WINDOW_MS } from './githubProfileSync'

 const GITHUB_API = 'https://api.github.com'
-const MIN_ACCOUNT_AGE_MS = 7 * 24 * 60 * 60 * 1000
-const FETCH_TTL_MS = 24 * 60 * 60 * 1000
+const MIN_ACCOUNT_AGE_MS = 14 * 24 * 60 * 60 * 1000
+
+type GitHubAccountGateCtx = Pick<ActionCtx, 'runQuery' | 'runMutation'>

 type GitHubUser = {
+  login?: string
+  name?: string
+  avatar_url?: string
  created_at?: string
 }

-export async function requireGitHubAccountAge(ctx: ActionCtx, userId: Id<'users'>) {
-  const user = await ctx.runQuery(internal.users.getByIdInternal, { userId })
-  if (!user || user.deletedAt) throw new ConvexError('User not found')
+function assertGitHubNumericId(providerAccountId: string) {
+  if (!/^[0-9]+$/.test(providerAccountId)) {
+    throw new ConvexError('GitHub account lookup failed')
+  }
+}

-  const handle = user.handle?.trim()
-  if (!handle) throw new ConvexError('GitHub handle required')
+function buildGitHubHeaders() {
+  const headers: Record<string, string> = { 'User-Agent': 'clawhub' }
+  const token = process.env.GITHUB_TOKEN
+  if (token) {
+    headers.Authorization = `Bearer ${token}`
+  }
+  return headers
+}
+
+export async function requireGitHubAccountAge(ctx: GitHubAccountGateCtx, userId: Id<'users'>) {
+  const user = await ctx.runQuery(internal.users.getByIdInternal, { userId })
+  if (!user || user.deletedAt || user.deactivatedAt) throw new ConvexError('User not found')

  const now = Date.now()
  let createdAt = user.githubCreatedAt ?? null
-  const fetchedAt = user.githubFetchedAt ?? 0
-  const stale = !createdAt || now - fetchedAt > FETCH_TTL_MS

-  if (stale) {
-    const headers: Record<string, string> = { 'User-Agent': 'clawhub' }
-    const token = process.env.GITHUB_TOKEN
-    if (token) {
-      headers.Authorization = `Bearer ${token}`
+  if (!createdAt) {
+    const providerAccountId = await ctx.runQuery(
+      internal.githubIdentity.getGitHubProviderAccountIdInternal,
+      { userId },
+    )
+    if (!providerAccountId) {
+      // Invariant: GitHub is our only auth provider, so this should never happen.
+      throw new ConvexError('GitHub account required')
    }
+    assertGitHubNumericId(providerAccountId)

-    const response = await fetch(`${GITHUB_API}/users/${encodeURIComponent(handle)}`, {
-      headers,
+    // Fetch by immutable GitHub numeric ID to avoid username swap attacks entirely.
+    const response = await fetch(`${GITHUB_API}/user/${providerAccountId}`, {
+      headers: buildGitHubHeaders(),
    })
    if (!response.ok) {
      if (response.status === 403 || response.status === 429) {
@@ -45,10 +65,9 @@ export async function requireGitHubAccountAge(ctx: ActionCtx, userId: Id<'users'
    if (!Number.isFinite(parsed)) throw new ConvexError('GitHub account lookup failed')

    createdAt = parsed
-    await ctx.runMutation(internal.users.updateGithubMetaInternal, {
+    await ctx.runMutation(internal.users.setGitHubCreatedAtInternal, {
      userId,
      githubCreatedAt: createdAt,
-      githubFetchedAt: now,
    })
  }

@@ -59,9 +78,66 @@ export async function requireGitHubAccountAge(ctx: ActionCtx, userId: Id<'users'
    const remainingMs = MIN_ACCOUNT_AGE_MS - ageMs
    const remainingDays = Math.max(1, Math.ceil(remainingMs / (24 * 60 * 60 * 1000)))
    throw new ConvexError(
-      `GitHub account must be at least 7 days old to upload skills. Try again in ${remainingDays} day${
+      `GitHub account must be at least 14 days old to publish skills or post comments. Try again in ${remainingDays} day${
        remainingDays === 1 ? '' : 's'
      }.`,
    )
  }
 }
+
+/**
+ * Sync the user's GitHub profile (username, avatar) from the GitHub API.
+ * This handles the case where a user renames their GitHub account.
+ * Uses the immutable GitHub numeric ID to fetch the current profile.
+ */
+export async function syncGitHubProfile(ctx: ActionCtx, userId: Id<'users'>) {
+  const user = await ctx.runQuery(internal.users.getByIdInternal, { userId })
+  if (!user || user.deletedAt || user.deactivatedAt) return
+
+  const now = Date.now()
+  const lastSyncedAt = user.githubProfileSyncedAt ?? null
+  if (lastSyncedAt && now - lastSyncedAt < GITHUB_PROFILE_SYNC_WINDOW_MS) return
+
+  const providerAccountId = await ctx.runQuery(
+    internal.githubIdentity.getGitHubProviderAccountIdInternal,
+    { userId },
+  )
+  if (!providerAccountId) return
+
+  assertGitHubNumericId(providerAccountId)
+
+  const response = await fetch(`${GITHUB_API}/user/${providerAccountId}`, {
+    headers: buildGitHubHeaders(),
+  })
+  if (!response.ok) {
+    // Silently fail - this is a best-effort sync, not critical path
+    console.warn(`[syncGitHubProfile] GitHub API error for user ${userId}: ${response.status}`)
+    return
+  }
+
+  const payload = (await response.json()) as GitHubUser
+  const newLogin = payload.login?.trim()
+  const newImage = payload.avatar_url?.trim()
+
+  const profileName = payload.name?.trim()
+
+  if (!newLogin) return
+
+  const args: {
+    userId: Id<'users'>
+    name: string
+    image?: string
+    syncedAt: number
+    profileName?: string
+  } = {
+    userId,
+    name: newLogin,
+    image: newImage,
+    syncedAt: now,
+  }
+  if (profileName && profileName !== newLogin) {
+    args.profileName = profileName
+  }
+
+  await ctx.runMutation(internal.users.syncGitHubProfileInternal, args)
+}
@@ -74,6 +74,13 @@ export type GitHubBackupContext = {
  root: string
 }

+export type GitHubSkillBackupEntry = {
+  owner: string
+  slug: string
+  rootPath: string
+  metaPath: string
+}
+
 export function isGitHubBackupConfigured() {
  return Boolean(
    process.env.GITHUB_APP_ID &&
@@ -108,6 +115,103 @@ export async function fetchGitHubSkillMeta(
  )
 }

+export async function listGitHubSkillBackupEntries(
+  context: GitHubBackupContext,
+): Promise<GitHubSkillBackupEntry[]> {
+  const ref = await githubGet<GitRef>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/ref/heads/${context.branch}`,
+  )
+  const baseCommit = await githubGet<GitCommit>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/commits/${ref.object.sha}`,
+  )
+  const tree = await githubGet<GitTree>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/trees/${baseCommit.tree.sha}?recursive=1`,
+  )
+
+  const prefix = context.root ? `${context.root}/` : ''
+  const entries: GitHubSkillBackupEntry[] = []
+  for (const entry of tree.tree ?? []) {
+    if (entry.type !== 'blob' || !entry.path) continue
+    if (!entry.path.startsWith(prefix) || !entry.path.endsWith(`/${META_FILENAME}`)) continue
+    const relative = entry.path.slice(prefix.length)
+    const segments = relative.split('/')
+    if (segments.length !== 3) continue
+    const [owner, slug, file] = segments
+    if (file !== META_FILENAME) continue
+    const rootPath = prefix ? `${prefix}${owner}/${slug}` : `${owner}/${slug}`
+    entries.push({ owner, slug, rootPath, metaPath: entry.path })
+  }
+
+  return entries
+}
+
+export async function deleteGitHubSkillBackup(
+  context: GitHubBackupContext,
+  ownerHandle: string,
+  slug: string,
+) {
+  const skillRoot = buildSkillRoot(context.root, ownerHandle, slug)
+  const ref = await githubGet<GitRef>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/ref/heads/${context.branch}`,
+  )
+  const baseCommitSha = ref.object.sha
+  const baseCommit = await githubGet<GitCommit>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/commits/${baseCommitSha}`,
+  )
+  const baseTreeSha = baseCommit.tree.sha
+  const existingTree = await githubGet<GitTree>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/trees/${baseTreeSha}?recursive=1`,
+  )
+
+  const prefix = `${skillRoot}/`
+  const pathsToDelete = (existingTree.tree ?? [])
+    .filter((entry) => entry.type === 'blob' && entry.path?.startsWith(prefix))
+    .map((entry) => entry.path ?? '')
+    .filter(Boolean)
+
+  if (!pathsToDelete.length) return { deleted: false as const }
+
+  const treeEntries = pathsToDelete.map((path) => ({
+    path,
+    mode: '100644' as const,
+    type: 'blob' as const,
+    sha: null,
+  }))
+
+  const newTree = await githubPost<{ sha: string }>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/trees`,
+    {
+      base_tree: baseTreeSha,
+      tree: treeEntries,
+    },
+  )
+
+  const commit = await githubPost<GitCommit>(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/commits`,
+    {
+      message: `delete: ${skillRoot}`,
+      tree: newTree.sha,
+      parents: [baseCommitSha],
+    },
+  )
+
+  await githubPatch(
+    context.token,
+    `/repos/${context.repoOwner}/${context.repoName}/git/refs/heads/${context.branch}`,
+    { sha: commit.sha },
+  )
+
+  return { deleted: true as const }
+}
+
 export async function backupSkillToGitHub(
  ctx: ActionCtx,
  params: BackupParams,
@@ -397,7 +501,7 @@ function parseRepo(repo: string) {
  return [owner, name] as const
 }

-function normalizeOwner(value: string) {
+export function normalizeOwner(value: string) {
  const normalized = value
    .trim()
    .toLowerCase()
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { canHealSkillOwnershipByGitHubProviderAccountId } from './githubIdentity'
+
+describe('canHealSkillOwnershipByGitHubProviderAccountId', () => {
+  it('denies when either providerAccountId is missing', () => {
+    expect(canHealSkillOwnershipByGitHubProviderAccountId(undefined, undefined)).toBe(false)
+    expect(canHealSkillOwnershipByGitHubProviderAccountId('123', undefined)).toBe(false)
+    expect(canHealSkillOwnershipByGitHubProviderAccountId(undefined, '123')).toBe(false)
+    expect(canHealSkillOwnershipByGitHubProviderAccountId(null, '123')).toBe(false)
+  })
+
+  it('denies when providerAccountId differs', () => {
+    expect(canHealSkillOwnershipByGitHubProviderAccountId('123', '456')).toBe(false)
+  })
+
+  it('allows when providerAccountId matches', () => {
+    expect(canHealSkillOwnershipByGitHubProviderAccountId('123', '123')).toBe(true)
+  })
+})
@@ -0,0 +1,22 @@
+import type { Id } from '../_generated/dataModel'
+import type { QueryCtx } from '../_generated/server'
+
+export function canHealSkillOwnershipByGitHubProviderAccountId(
+  ownerProviderAccountId: string | null | undefined,
+  callerProviderAccountId: string | null | undefined,
+) {
+  // Security invariant: missing identity must never grant ownership.
+  if (!ownerProviderAccountId || !callerProviderAccountId) return false
+  return ownerProviderAccountId === callerProviderAccountId
+}
+
+export async function getGitHubProviderAccountId(
+  ctx: Pick<QueryCtx, 'db'>,
+  userId: Id<'users'>,
+): Promise<string | null> {
+  const account = await ctx.db
+    .query('authAccounts')
+    .withIndex('userIdAndProvider', (q) => q.eq('userId', userId).eq('provider', 'github'))
+    .unique()
+  return account?.providerAccountId ?? null
+}
@@ -0,0 +1,19 @@
+export const GITHUB_PROFILE_SYNC_WINDOW_MS = 6 * 60 * 60 * 1000
+
+export function shouldScheduleGitHubProfileSync(
+  user:
+    | {
+        deletedAt?: number
+        deactivatedAt?: number
+        githubProfileSyncedAt?: number
+      }
+    | null
+    | undefined,
+  now: number,
+) {
+  if (!user || user.deletedAt || user.deactivatedAt) return false
+  const lastSyncedAt = user.githubProfileSyncedAt ?? null
+  if (lastSyncedAt && now - lastSyncedAt < GITHUB_PROFILE_SYNC_WINDOW_MS) return false
+  return true
+}
+
@@ -0,0 +1,54 @@
+/* @vitest-environment node */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { GitHubBackupContext } from './githubBackup'
+import { readGitHubBackupFile } from './githubRestoreHelpers'
+
+function makeContext(): GitHubBackupContext {
+  return {
+    token: 'token',
+    repo: 'owner/repo',
+    repoOwner: 'owner',
+    repoName: 'repo',
+    branch: 'main',
+    root: 'skills',
+  }
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.restoreAllMocks()
+})
+
+  describe('githubRestoreHelpers', () => {
+  it('decodes base64 payloads (including newlines) into bytes', async () => {
+    const content = 'SGVs\n bG8h' // "Hello!" with whitespace/newline
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({ content, encoding: 'base64' }),
+        text: async () => '',
+      })),
+    )
+
+    const bytes = await readGitHubBackupFile(makeContext(), 'Owner', 'slug', 'SKILL.md')
+    expect(bytes).not.toBeNull()
+    expect(Buffer.from(bytes!).toString('utf8')).toBe('Hello!')
+  })
+
+  it('throws on unsupported GitHub content encoding', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({ content: 'eA==', encoding: 'utf-16' }),
+        text: async () => '',
+      })),
+    )
+
+    await expect(readGitHubBackupFile(makeContext(), 'Owner', 'slug', 'SKILL.md')).rejects.toThrow(
+      /Unsupported GitHub content encoding/i,
+    )
+  })
+})
@@ -0,0 +1,159 @@
+'use node'
+
+import type { GitHubBackupContext } from './githubBackup'
+
+const GITHUB_API = 'https://api.github.com'
+const META_FILENAME = '_meta.json'
+const USER_AGENT = 'clawhub/skills-restore'
+
+type GitHubContentsEntry = {
+  name?: string
+  path?: string
+  type?: string // 'file' | 'dir'
+  size?: number
+}
+
+type GitHubBlobResponse = {
+  content?: string
+  encoding?: string
+  size?: number
+}
+
+/**
+ * List all files in a skill's backup directory (excluding _meta.json).
+ * Uses the Contents API scoped to the target directory instead of fetching
+ * the entire repository tree, which is critical for bulk restore performance.
+ * Returns relative file paths (e.g. "SKILL.md", "lib/helper.ts").
+ */
+export async function listGitHubBackupFiles(
+  context: GitHubBackupContext,
+  ownerHandle: string,
+  slug: string,
+): Promise<string[]> {
+  const skillRoot = buildSkillRoot(context.root, ownerHandle, slug)
+  return listFilesRecursive(context, skillRoot, '')
+}
+
+/**
+ * Recursively list files under a directory using the GitHub Contents API.
+ * Each call is scoped to one directory, avoiding full-repo tree downloads.
+ */
+async function listFilesRecursive(
+  context: GitHubBackupContext,
+  basePath: string,
+  relativePath: string,
+): Promise<string[]> {
+  const dirPath = relativePath ? `${basePath}/${relativePath}` : basePath
+
+  try {
+    const entries = await githubGet<GitHubContentsEntry[]>(
+      context.token,
+      `/repos/${context.repoOwner}/${context.repoName}/contents/${encodePath(dirPath)}?ref=${context.branch}`,
+    )
+
+    if (!Array.isArray(entries)) return []
+
+    const files: string[] = []
+    for (const entry of entries) {
+      if (!entry.name || !entry.type) continue
+
+      const entryRelative = relativePath ? `${relativePath}/${entry.name}` : entry.name
+
+      if (entry.type === 'file') {
+        // Skip the meta file
+        if (entry.name === META_FILENAME) continue
+        files.push(entryRelative)
+      } else if (entry.type === 'dir') {
+        // Recurse into subdirectories
+        const subFiles = await listFilesRecursive(context, basePath, entryRelative)
+        files.push(...subFiles)
+      }
+    }
+
+    return files
+  } catch (error) {
+    if (isNotFoundError(error)) return []
+    throw error
+  }
+}
+
+/**
+ * Read a single file from the GitHub backup repository.
+ * Returns the file content as a Uint8Array, or null if not found.
+ */
+export async function readGitHubBackupFile(
+  context: GitHubBackupContext,
+  ownerHandle: string,
+  slug: string,
+  filePath: string,
+): Promise<Uint8Array | null> {
+  const skillRoot = buildSkillRoot(context.root, ownerHandle, slug)
+  const fullPath = `${skillRoot}/${filePath}`
+
+  try {
+    const response = await githubGet<GitHubBlobResponse>(
+      context.token,
+      `/repos/${context.repoOwner}/${context.repoName}/contents/${encodePath(fullPath)}?ref=${context.branch}`,
+    )
+
+    if (!response.content) return null
+
+    if (response.encoding && response.encoding !== 'base64') {
+      throw new Error(`Unsupported GitHub content encoding: ${response.encoding}`)
+    }
+
+    return fromBase64Bytes(response.content)
+  } catch (error) {
+    if (isNotFoundError(error)) return null
+    throw error
+  }
+}
+
+function buildSkillRoot(root: string, ownerHandle: string, slug: string) {
+  const ownerSegment = normalizeOwner(ownerHandle)
+  return `${root}/${ownerSegment}/${slug}`
+}
+
+function normalizeOwner(value: string) {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return normalized || 'unknown'
+}
+
+function encodePath(path: string) {
+  return path
+    .split('/')
+    .map((segment) => encodeURIComponent(segment))
+    .join('/')
+}
+
+function fromBase64Bytes(value: string) {
+  // GitHub may include newlines in the base64 payload.
+  const normalized = value.replace(/\s/g, '')
+  return new Uint8Array(Buffer.from(normalized, 'base64'))
+}
+
+async function githubGet<T>(token: string, path: string): Promise<T> {
+  const response = await fetch(`${GITHUB_API}${path}`, {
+    headers: {
+      Authorization: `token ${token}`,
+      Accept: 'application/vnd.github+json',
+      'User-Agent': USER_AGENT,
+    },
+  })
+  if (!response.ok) {
+    const message = await response.text()
+    throw new Error(`GitHub GET ${path} failed: ${message}`)
+  }
+  return (await response.json()) as T
+}
+
+function isNotFoundError(error: unknown) {
+  return (
+    error instanceof Error && (error.message.includes('404') || error.message.includes('Not Found'))
+  )
+}
@@ -0,0 +1,141 @@
+import type { Doc } from '../_generated/dataModel'
+import type { MutationCtx, QueryCtx } from '../_generated/server'
+
+export const GLOBAL_STATS_KEY = 'default'
+
+type SkillVisibilityFields = Pick<
+  Doc<'skills'>,
+  'softDeletedAt' | 'moderationStatus' | 'moderationFlags'
+>
+
+type GlobalStatsReadCtx = Pick<MutationCtx | QueryCtx, 'db'>
+type GlobalStatsWriteCtx = Pick<MutationCtx, 'db'>
+
+export function isPublicSkillDoc(skill: SkillVisibilityFields | null | undefined) {
+  if (!skill || skill.softDeletedAt) return false
+  if (skill.moderationStatus && skill.moderationStatus !== 'active') return false
+  if (skill.moderationFlags?.includes('blocked.malware')) return false
+  return true
+}
+
+export function getPublicSkillVisibilityDelta(
+  before: SkillVisibilityFields | null | undefined,
+  after: SkillVisibilityFields | null | undefined,
+) {
+  const beforePublic = isPublicSkillDoc(before)
+  const afterPublic = isPublicSkillDoc(after)
+  if (beforePublic === afterPublic) return 0
+  return afterPublic ? 1 : -1
+}
+
+function getErrorMessage(error: unknown) {
+  if (typeof error === 'string') return error
+  if (error && typeof error === 'object' && 'message' in error) {
+    const message = (error as { message?: unknown }).message
+    if (typeof message === 'string') return message
+  }
+  return ''
+}
+
+export function isGlobalStatsStorageNotReadyError(error: unknown) {
+  const message = getErrorMessage(error).toLowerCase()
+  if (!message) return false
+  const referencesGlobalStats = message.includes('globalstats') || message.includes('by_key')
+  if (!referencesGlobalStats) return false
+  return (
+    message.includes('table') ||
+    message.includes('index') ||
+    message.includes('schema') ||
+    message.includes('not found') ||
+    message.includes('does not exist') ||
+    message.includes('unknown')
+  )
+}
+
+export async function countPublicSkillsForGlobalStats(ctx: GlobalStatsReadCtx) {
+  const skills = await ctx.db
+    .query('skills')
+    .withIndex('by_active_updated', (q) => q.eq('softDeletedAt', undefined))
+    .collect()
+  let count = 0
+  for (const skill of skills) {
+    if (isPublicSkillDoc(skill)) count += 1
+  }
+  return count
+}
+
+export async function setGlobalPublicSkillsCount(
+  ctx: GlobalStatsWriteCtx,
+  count: number,
+  now = Date.now(),
+) {
+  const normalizedCount = Math.max(0, Math.trunc(Number.isFinite(count) ? count : 0))
+  try {
+    const existing = await ctx.db
+      .query('globalStats')
+      .withIndex('by_key', (q) => q.eq('key', GLOBAL_STATS_KEY))
+      .unique()
+
+    if (existing) {
+      await ctx.db.patch(existing._id, { activeSkillsCount: normalizedCount, updatedAt: now })
+    } else {
+      await ctx.db.insert('globalStats', {
+        key: GLOBAL_STATS_KEY,
+        activeSkillsCount: normalizedCount,
+        updatedAt: now,
+      })
+    }
+  } catch (error) {
+    if (isGlobalStatsStorageNotReadyError(error)) return
+    throw error
+  }
+}
+
+export async function adjustGlobalPublicSkillsCount(
+  ctx: GlobalStatsWriteCtx,
+  delta: number,
+  now = Date.now(),
+) {
+  const normalizedDelta = Math.trunc(Number.isFinite(delta) ? delta : 0)
+  if (normalizedDelta === 0) return
+
+  let existing:
+    | {
+        _id: Doc<'globalStats'>['_id']
+        activeSkillsCount: number
+      }
+    | null
+    | undefined
+  try {
+    existing = await ctx.db
+      .query('globalStats')
+      .withIndex('by_key', (q) => q.eq('key', GLOBAL_STATS_KEY))
+      .unique()
+  } catch (error) {
+    if (isGlobalStatsStorageNotReadyError(error)) return
+    throw error
+  }
+
+  if (!existing) {
+    // No baseline yet (e.g. fresh deploy). Initialize via full recount once.
+    const count = await countPublicSkillsForGlobalStats(ctx)
+    await setGlobalPublicSkillsCount(ctx, count, now)
+    return
+  }
+
+  const nextCount = Math.max(0, existing.activeSkillsCount + normalizedDelta)
+  await ctx.db.patch(existing._id, { activeSkillsCount: nextCount, updatedAt: now })
+}
+
+export async function readGlobalPublicSkillsCount(ctx: GlobalStatsReadCtx) {
+  try {
+    const stats = await ctx.db
+      .query('globalStats')
+      .withIndex('by_key', (q) => q.eq('key', GLOBAL_STATS_KEY))
+      .unique()
+    return stats?.activeSkillsCount ?? null
+  } catch (error) {
+    if (isGlobalStatsStorageNotReadyError(error)) return null
+    throw error
+  }
+}
@@ -0,0 +1,19 @@
+function toHeaderRecord(init?: HeadersInit): Record<string, string> {
+  if (!init) return {}
+  if (init instanceof Headers) return Object.fromEntries(init.entries())
+  if (Array.isArray(init)) return Object.fromEntries(init)
+  return { ...(init as Record<string, string>) }
+}
+
+export function mergeHeaders(...inits: Array<HeadersInit | undefined>): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const init of inits) {
+    Object.assign(out, toHeaderRecord(init))
+  }
+  return out
+}
+
+export function corsHeaders(origin: string = '*'): Record<string, string> {
+  return { 'Access-Control-Allow-Origin': origin }
+}
+
@@ -0,0 +1,296 @@
+/* @vitest-environment node */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { applyRateLimit, getClientIp } from './httpRateLimit'
+
+type MockRateLimitStatus = {
+  allowed: boolean
+  remaining: number
+  limit: number
+  resetAt: number
+}
+
+type MockRateLimitPlan = {
+  ip: MockRateLimitStatus
+  user?: MockRateLimitStatus
+  tokenValid?: boolean
+  userActive?: boolean
+}
+
+function makeRateLimitCtx(plan: MockRateLimitPlan) {
+  const runQuery = vi.fn(async (_fn: unknown, args: Record<string, unknown>) => {
+    if ('tokenHash' in args) {
+      if (plan.tokenValid === false) return null
+      return { _id: 'token_1', revokedAt: undefined }
+    }
+    if ('tokenId' in args) {
+      if (plan.userActive === false) return null
+      return { _id: 'users_123', deletedAt: undefined, deactivatedAt: undefined }
+    }
+    if ('key' in args && 'limit' in args && 'windowMs' in args) {
+      const key = String(args.key)
+      if (key.startsWith('ip:')) return plan.ip
+      if (key.startsWith('user:')) return plan.user
+    }
+    throw new Error(`Unexpected runQuery args: ${JSON.stringify(args)}`)
+  })
+
+  const runMutation = vi.fn(async (_fn: unknown, args: Record<string, unknown>) => {
+    const key = String(args.key)
+    const source = key.startsWith('user:') ? plan.user : plan.ip
+    if (!source) throw new Error(`Missing rate limit source for ${key}`)
+    return { allowed: source.allowed, remaining: source.remaining }
+  })
+
+  return {
+    runQuery,
+    runMutation,
+  } as unknown as Parameters<typeof applyRateLimit>[0]
+}
+
+describe('getClientIp', () => {
+  let prev: string | undefined
+  beforeEach(() => {
+    prev = process.env.TRUST_FORWARDED_IPS
+  })
+  afterEach(() => {
+    if (prev === undefined) {
+      delete process.env.TRUST_FORWARDED_IPS
+    } else {
+      process.env.TRUST_FORWARDED_IPS = prev
+    }
+  })
+
+  it('returns null when cf-connecting-ip is missing (CF-only default)', () => {
+    const request = new Request('https://example.com', {
+      headers: {
+        'x-forwarded-for': '203.0.113.9',
+      },
+    })
+    delete process.env.TRUST_FORWARDED_IPS
+    expect(getClientIp(request)).toBeNull()
+  })
+
+  it('keeps forwarded headers disabled when TRUST_FORWARDED_IPS=false', () => {
+    const request = new Request('https://example.com', {
+      headers: {
+        'x-forwarded-for': '203.0.113.9',
+      },
+    })
+    process.env.TRUST_FORWARDED_IPS = 'false'
+    expect(getClientIp(request)).toBeNull()
+  })
+
+  it('returns first ip from cf-connecting-ip', () => {
+    const request = new Request('https://example.com', {
+      headers: {
+        'cf-connecting-ip': '203.0.113.1, 198.51.100.2',
+      },
+    })
+    expect(getClientIp(request)).toBe('203.0.113.1')
+  })
+
+  it('uses forwarded headers when opt-in enabled', () => {
+    const request = new Request('https://example.com', {
+      headers: {
+        'x-forwarded-for': '203.0.113.9, 198.51.100.2',
+      },
+    })
+    process.env.TRUST_FORWARDED_IPS = 'true'
+    expect(getClientIp(request)).toBe('203.0.113.9')
+  })
+
+  it('prefers x-forwarded-for over x-real-ip when trusted mode is enabled', () => {
+    const request = new Request('https://example.com', {
+      headers: {
+        'x-forwarded-for': '203.0.113.9, 198.51.100.2',
+        'x-real-ip': '198.51.100.77',
+      },
+    })
+    process.env.TRUST_FORWARDED_IPS = 'true'
+    expect(getClientIp(request)).toBe('203.0.113.9')
+  })
+})
+
+describe('applyRateLimit headers', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('returns delay-seconds Retry-After on 429 (not epoch)', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(1_000_000)
+    const runMutation = vi.fn()
+    const ctx = {
+      runQuery: vi.fn().mockResolvedValue({
+        allowed: false,
+        remaining: 0,
+        limit: 20,
+        resetAt: 1_030_500,
+      }),
+      runMutation,
+    } as unknown as Parameters<typeof applyRateLimit>[0]
+    const request = new Request('https://example.com', {
+      headers: { 'cf-connecting-ip': '203.0.113.1' },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.response.status).toBe(429)
+    expect(result.response.headers.get('Retry-After')).toBe('31')
+    expect(result.response.headers.get('X-RateLimit-Reset')).toBe('1031')
+    expect(result.response.headers.get('RateLimit-Reset')).toBe('31')
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('includes rate-limit headers without Retry-After when allowed', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(2_000_000)
+    const ctx = {
+      runQuery: vi.fn().mockResolvedValue({
+        allowed: true,
+        remaining: 19,
+        limit: 20,
+        resetAt: 2_015_000,
+      }),
+      runMutation: vi.fn().mockResolvedValue({
+        allowed: true,
+        remaining: 18,
+      }),
+    } as unknown as Parameters<typeof applyRateLimit>[0]
+    const request = new Request('https://example.com', {
+      headers: { 'cf-connecting-ip': '203.0.113.1' },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const headers = new Headers(result.headers)
+    expect(headers.get('X-RateLimit-Limit')).toBe('20')
+    expect(headers.get('X-RateLimit-Remaining')).toBe('18')
+    expect(headers.get('X-RateLimit-Reset')).toBe('2015')
+    expect(headers.get('RateLimit-Limit')).toBe('20')
+    expect(headers.get('RateLimit-Remaining')).toBe('18')
+    expect(headers.get('RateLimit-Reset')).toBe('15')
+    expect(headers.get('Retry-After')).toBeNull()
+  })
+
+  it('allows authenticated users when user bucket is healthy and shared ip bucket is exhausted', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(3_000_000)
+    const ctx = makeRateLimitCtx({
+      ip: {
+        allowed: false,
+        remaining: 0,
+        limit: 20,
+        resetAt: 3_040_000,
+      },
+      user: {
+        allowed: true,
+        remaining: 42,
+        limit: 120,
+        resetAt: 3_010_000,
+      },
+    })
+    const request = new Request('https://example.com', {
+      headers: {
+        authorization: 'Bearer clh_token',
+        'cf-connecting-ip': '203.0.113.1',
+      },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const headers = new Headers(result.headers)
+    expect(headers.get('X-RateLimit-Limit')).toBe('120')
+    expect(headers.get('X-RateLimit-Remaining')).toBe('42')
+    expect(headers.get('Retry-After')).toBeNull()
+  })
+
+  it('does not consume ip bucket for authenticated requests', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(3_100_000)
+    const ctx = makeRateLimitCtx({
+      ip: {
+        allowed: true,
+        remaining: 19,
+        limit: 20,
+        resetAt: 3_140_000,
+      },
+      user: {
+        allowed: true,
+        remaining: 41,
+        limit: 120,
+        resetAt: 3_110_000,
+      },
+    })
+    const request = new Request('https://example.com', {
+      headers: {
+        authorization: 'Bearer clh_token',
+        'cf-connecting-ip': '203.0.113.1',
+      },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(true)
+    const runMutation = (ctx as unknown as { runMutation: ReturnType<typeof vi.fn> }).runMutation
+    const consumedKeys = runMutation.mock.calls.map(([, args]) => String(args.key))
+    expect(consumedKeys.some((key) => key.startsWith('user:'))).toBe(true)
+    expect(consumedKeys.some((key) => key.startsWith('ip:'))).toBe(false)
+  })
+
+  it('denies authenticated users when user bucket is exhausted even if ip bucket is healthy', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(4_000_000)
+    const ctx = makeRateLimitCtx({
+      ip: {
+        allowed: true,
+        remaining: 19,
+        limit: 20,
+        resetAt: 4_020_000,
+      },
+      user: {
+        allowed: false,
+        remaining: 0,
+        limit: 120,
+        resetAt: 4_030_000,
+      },
+    })
+    const request = new Request('https://example.com', {
+      headers: {
+        authorization: 'Bearer clh_token',
+        'cf-connecting-ip': '203.0.113.1',
+      },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.response.status).toBe(429)
+    expect(result.response.headers.get('X-RateLimit-Limit')).toBe('120')
+    expect(result.response.headers.get('X-RateLimit-Remaining')).toBe('0')
+    expect(result.response.headers.get('Retry-After')).toBe('30')
+  })
+
+  it('falls back to ip enforcement when bearer token is invalid', async () => {
+    vi.spyOn(Date, 'now').mockReturnValue(5_000_000)
+    const ctx = makeRateLimitCtx({
+      tokenValid: false,
+      ip: {
+        allowed: false,
+        remaining: 0,
+        limit: 20,
+        resetAt: 5_030_000,
+      },
+    })
+    const request = new Request('https://example.com', {
+      headers: {
+        authorization: 'Bearer invalid',
+        'cf-connecting-ip': '203.0.113.1',
+      },
+    })
+
+    const result = await applyRateLimit(ctx, request, 'download')
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.response.status).toBe(429)
+    expect(result.response.headers.get('X-RateLimit-Limit')).toBe('20')
+    expect(result.response.headers.get('Retry-After')).toBe('30')
+  })
+})
@@ -0,0 +1,209 @@
+import { internal } from '../_generated/api'
+import type { ActionCtx } from '../_generated/server'
+import { getOptionalApiTokenUserId } from './apiTokenAuth'
+import { corsHeaders, mergeHeaders } from './httpHeaders'
+
+const RATE_LIMIT_WINDOW_MS = 60_000
+export const RATE_LIMITS = {
+  read: { ip: 120, key: 600 },
+  write: { ip: 30, key: 120 },
+  download: { ip: 20, key: 120 },
+} as const
+
+type RateLimitResult = {
+  allowed: boolean
+  remaining: number
+  limit: number
+  resetAt: number
+}
+
+export async function applyRateLimit(
+  ctx: ActionCtx,
+  request: Request,
+  kind: keyof typeof RATE_LIMITS,
+): Promise<{ ok: true; headers: HeadersInit } | { ok: false; response: Response }> {
+  const userId = await getOptionalApiTokenUserId(ctx, request)
+  const ip = getClientIp(request) ?? 'unknown'
+  const ipSource = getClientIpSource(request)
+  const hasClientIp = ip !== 'unknown'
+
+  // Authenticated requests are enforced and consumed by user bucket only to
+  // avoid draining shared IP quota.
+  if (userId) {
+    const userResult = await checkRateLimit(ctx, `user:${userId}`, RATE_LIMITS[kind].key)
+    const headers = rateHeaders(userResult)
+    if (!userResult.allowed) {
+      console.info('rate_limit_denied', {
+        kind,
+        auth: true,
+        userAllowed: false,
+        ipAllowed: null,
+        ipSource,
+        hasClientIp,
+      })
+      return {
+        ok: false,
+        response: new Response('Rate limit exceeded', {
+          status: 429,
+          headers: mergeHeaders(
+            {
+              'Content-Type': 'text/plain; charset=utf-8',
+              'Cache-Control': 'no-store',
+            },
+            headers,
+            corsHeaders(),
+          ),
+        }),
+      }
+    }
+    return { ok: true, headers }
+  }
+
+  // Anonymous requests remain IP-enforced.
+  const ipResult = await checkRateLimit(ctx, `ip:${ip}`, RATE_LIMITS[kind].ip)
+  const headers = rateHeaders(ipResult)
+
+  if (!ipResult.allowed) {
+    console.info('rate_limit_denied', {
+      kind,
+      auth: false,
+      userAllowed: null,
+      ipAllowed: ipResult.allowed,
+      ipSource,
+      hasClientIp,
+    })
+    return {
+      ok: false,
+      response: new Response('Rate limit exceeded', {
+        status: 429,
+        headers: mergeHeaders(
+          {
+            'Content-Type': 'text/plain; charset=utf-8',
+            'Cache-Control': 'no-store',
+          },
+          headers,
+          corsHeaders(),
+        ),
+      }),
+    }
+  }
+
+  return { ok: true, headers }
+}
+
+export function getClientIp(request: Request) {
+  const cfHeader = request.headers.get('cf-connecting-ip')
+  if (cfHeader) return splitFirstIp(cfHeader)
+
+  if (!shouldTrustForwardedIps()) return null
+
+  const forwarded =
+    request.headers.get('x-forwarded-for') ??
+    request.headers.get('x-real-ip') ??
+    request.headers.get('fly-client-ip')
+
+  return splitFirstIp(forwarded)
+}
+
+function getClientIpSource(request: Request) {
+  if (request.headers.get('cf-connecting-ip')) return 'cf-connecting-ip'
+  if (!shouldTrustForwardedIps()) return 'none'
+  if (request.headers.get('x-forwarded-for')) return 'x-forwarded-for'
+  if (request.headers.get('x-real-ip')) return 'x-real-ip'
+  if (request.headers.get('fly-client-ip')) return 'fly-client-ip'
+  return 'none'
+}
+
+async function checkRateLimit(
+  ctx: ActionCtx,
+  key: string,
+  limit: number,
+): Promise<RateLimitResult> {
+  // Step 1: Read-only check to avoid write conflicts on denied requests.
+  const status = (await ctx.runQuery(internal.rateLimits.getRateLimitStatusInternal, {
+    key,
+    limit,
+    windowMs: RATE_LIMIT_WINDOW_MS,
+  })) as RateLimitResult
+
+  if (!status.allowed) {
+    return status
+  }
+
+  // Step 2: Consume with a mutation only when still allowed.
+  let result: { allowed: boolean; remaining: number }
+  try {
+    result = (await ctx.runMutation(internal.rateLimits.consumeRateLimitInternal, {
+      key,
+      limit,
+      windowMs: RATE_LIMIT_WINDOW_MS,
+    })) as { allowed: boolean; remaining: number }
+  } catch (error) {
+    if (isRateLimitWriteConflict(error)) {
+      return {
+        allowed: false,
+        remaining: 0,
+        limit: status.limit,
+        resetAt: status.resetAt,
+      }
+    }
+    throw error
+  }
+
+  return {
+    allowed: result.allowed,
+    remaining: result.remaining,
+    limit: status.limit,
+    resetAt: status.resetAt,
+  }
+}
+
+function rateHeaders(result: RateLimitResult): HeadersInit {
+  const nowMs = Date.now()
+  const resetSeconds = Math.ceil(result.resetAt / 1000)
+  const resetDelaySeconds = Math.max(1, Math.ceil((result.resetAt - nowMs) / 1000))
+  return {
+    'X-RateLimit-Limit': String(result.limit),
+    'X-RateLimit-Remaining': String(result.remaining),
+    'X-RateLimit-Reset': String(resetSeconds),
+    'RateLimit-Limit': String(result.limit),
+    'RateLimit-Remaining': String(result.remaining),
+    'RateLimit-Reset': String(resetDelaySeconds),
+    ...(result.allowed ? {} : { 'Retry-After': String(resetDelaySeconds) }),
+  }
+}
+
+export function parseBearerToken(request: Request) {
+  const header = request.headers.get('authorization') ?? request.headers.get('Authorization')
+  if (!header) return null
+  const trimmed = header.trim()
+  if (!trimmed.toLowerCase().startsWith('bearer ')) return null
+  const token = trimmed.slice(7).trim()
+  return token || null
+}
+
+function splitFirstIp(header: string | null) {
+  if (!header) return null
+  if (header.includes(',')) return header.split(',')[0]?.trim() || null
+  const trimmed = header.trim()
+  return trimmed || null
+}
+
+function shouldTrustForwardedIps() {
+  const value = String(process.env.TRUST_FORWARDED_IPS ?? '')
+    .trim()
+    .toLowerCase()
+  // Hardening default: CF-only. Forwarded headers are trivial to spoof unless you
+  // control the trusted proxy layer.
+  if (!value) return false
+  if (value === '1' || value === 'true' || value === 'yes') return true
+  return false
+}
+
+function isRateLimitWriteConflict(error: unknown) {
+  if (!(error instanceof Error)) return false
+  return (
+    error.message.includes('rateLimits') &&
+    error.message.includes('changed while this mutation was being run')
+  )
+}
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { extractResponseText } from './openaiResponse'
+
+describe('extractResponseText', () => {
+  it('returns null for invalid payload shapes', () => {
+    expect(extractResponseText(null)).toBeNull()
+    expect(extractResponseText({})).toBeNull()
+    expect(extractResponseText({ output: {} })).toBeNull()
+  })
+
+  it('extracts output_text chunks from message content', () => {
+    const payload = {
+      output: [
+        { type: 'reasoning', content: [] },
+        {
+          type: 'message',
+          content: [
+            { type: 'output_text', text: 'First line' },
+            { type: 'output_text', text: 'Second line' },
+          ],
+        },
+      ],
+    }
+
+    expect(extractResponseText(payload)).toBe('First line\nSecond line')
+  })
+
+  it('ignores blank and non-output_text parts', () => {
+    const payload = {
+      output: [
+        {
+          type: 'message',
+          content: [
+            { type: 'input_text', text: 'ignored' },
+            { type: 'output_text', text: '   ' },
+            { type: 'output_text', text: 'kept' },
+          ],
+        },
+      ],
+    }
+
+    expect(extractResponseText(payload)).toBe('kept')
+  })
+})
@@ -0,0 +1,20 @@
+export function extractResponseText(payload: unknown): string | null {
+  if (!payload || typeof payload !== 'object') return null
+  const output = (payload as { output?: unknown }).output
+  if (!Array.isArray(output)) return null
+  const chunks: string[] = []
+  for (const item of output) {
+    if (!item || typeof item !== 'object') continue
+    if ((item as { type?: unknown }).type !== 'message') continue
+    const content = (item as { content?: unknown }).content
+    if (!Array.isArray(content)) continue
+    for (const part of content) {
+      if (!part || typeof part !== 'object') continue
+      if ((part as { type?: unknown }).type !== 'output_text') continue
+      const text = (part as { text?: unknown }).text
+      if (typeof text === 'string' && text.trim()) chunks.push(text)
+    }
+  }
+  const joined = chunks.join('\n').trim()
+  return joined || null
+}
@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import type { Doc } from '../_generated/dataModel'
+import { toPublicSkill } from './public'
+
+function makeSkill(overrides: Partial<Doc<'skills'>> = {}): Doc<'skills'> {
+  return {
+    _id: 'skills:1' as Doc<'skills'>['_id'],
+    _creationTime: 1,
+    slug: 'demo',
+    displayName: 'Demo',
+    summary: 'Demo summary',
+    ownerUserId: 'users:1' as Doc<'skills'>['ownerUserId'],
+    canonicalSkillId: undefined,
+    forkOf: undefined,
+    latestVersionId: undefined,
+    tags: {},
+    badges: {},
+    moderationStatus: 'active',
+    moderationReason: undefined,
+    moderationNotes: undefined,
+    moderationFlags: undefined,
+    hiddenAt: undefined,
+    lastReviewedAt: undefined,
+    softDeletedAt: undefined,
+    reportCount: 0,
+    lastReportedAt: undefined,
+    quality: undefined,
+    statsDownloads: 0,
+    statsStars: 0,
+    statsInstallsCurrent: 0,
+    statsInstallsAllTime: 0,
+    stats: {
+      downloads: 0,
+      installsCurrent: 0,
+      installsAllTime: 0,
+      stars: 0,
+      versions: 0,
+      comments: 0,
+    },
+    createdAt: 1,
+    updatedAt: 1,
+    ...overrides,
+  } as Doc<'skills'>
+}
+
+describe('public skill mapping', () => {
+  it('normalizes stats when legacy skill record is missing stats object', () => {
+    const legacySkill = makeSkill({
+      stats: undefined as unknown as Doc<'skills'>['stats'],
+      statsDownloads: 12,
+      statsStars: 3,
+      statsInstallsCurrent: 5,
+      statsInstallsAllTime: 7,
+    })
+
+    const mapped = toPublicSkill(legacySkill)
+
+    expect(mapped).not.toBeNull()
+    expect(mapped?.stats).toEqual({
+      downloads: 12,
+      stars: 3,
+      installsCurrent: 5,
+      installsAllTime: 7,
+      versions: 0,
+      comments: 0,
+    })
+  })
+
+  it('returns skill when moderationStatus is active', () => {
+    const skill = makeSkill({ moderationStatus: 'active' })
+    expect(toPublicSkill(skill)).not.toBeNull()
+  })
+
+  it('filters out skill when moderationStatus is hidden', () => {
+    const skill = makeSkill({ moderationStatus: 'hidden' })
+    expect(toPublicSkill(skill)).toBeNull()
+  })
+
+  it('returns skill when moderationStatus is undefined (legacy)', () => {
+    const skill = makeSkill({ moderationStatus: undefined })
+    expect(toPublicSkill(skill)).not.toBeNull()
+  })
+
+  it('filters out soft-deleted skills', () => {
+    const skill = makeSkill({ softDeletedAt: Date.now() })
+    expect(toPublicSkill(skill)).toBeNull()
+  })
+
+  it('filters out skills with blocked.malware flag', () => {
+    const skill = makeSkill({
+      moderationStatus: 'active',
+      moderationFlags: ['blocked.malware'],
+    })
+    expect(toPublicSkill(skill)).toBeNull()
+  })
+})
@@ -1,4 +1,5 @@
 import type { Doc } from '../_generated/dataModel'
+import { isPublicSkillDoc } from './globalStats'

 export type PublicUser = Pick<
  Doc<'users'>,
@@ -39,7 +40,7 @@ export type PublicSoul = Pick<
 >

 export function toPublicUser(user: Doc<'users'> | null | undefined): PublicUser | null {
-  if (!user || user.deletedAt) return null
+  if (!user || user.deletedAt || user.deactivatedAt) return null
  return {
    _id: user._id,
    _creationTime: user._creationTime,
@@ -52,9 +53,25 @@ export function toPublicUser(user: Doc<'users'> | null | undefined): PublicUser
 }

 export function toPublicSkill(skill: Doc<'skills'> | null | undefined): PublicSkill | null {
-  if (!skill || skill.softDeletedAt) return null
-  if (skill.moderationStatus && skill.moderationStatus !== 'active') return null
-  if (skill.moderationFlags?.includes('blocked.malware')) return null
+  if (!skill) return null
+  if (!isPublicSkillDoc(skill)) return null
+  const stats = {
+    downloads:
+      typeof skill.statsDownloads === 'number'
+        ? skill.statsDownloads
+        : (skill.stats?.downloads ?? 0),
+    stars: typeof skill.statsStars === 'number' ? skill.statsStars : (skill.stats?.stars ?? 0),
+    installsCurrent:
+      typeof skill.statsInstallsCurrent === 'number'
+        ? skill.statsInstallsCurrent
+        : (skill.stats?.installsCurrent ?? 0),
+    installsAllTime:
+      typeof skill.statsInstallsAllTime === 'number'
+        ? skill.statsInstallsAllTime
+        : (skill.stats?.installsAllTime ?? 0),
+    versions: skill.stats?.versions ?? 0,
+    comments: skill.stats?.comments ?? 0,
+  }
  return {
    _id: skill._id,
    _creationTime: skill._creationTime,
@@ -67,7 +84,7 @@ export function toPublicSkill(skill: Doc<'skills'> | null | undefined): PublicSk
    latestVersionId: skill.latestVersionId,
    tags: skill.tags,
    badges: skill.badges,
-    stats: skill.stats,
+    stats,
    createdAt: skill.createdAt,
    updatedAt: skill.updatedAt,
  }
@@ -0,0 +1,3 @@
+export const MAX_ACTIVE_REPORTS_PER_USER = 20
+export const AUTO_HIDE_REPORT_THRESHOLD = 3
+export const MAX_REPORT_REASON_LENGTH = 500
@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  enforceReservedSlugCooldownForNewSkill,
+  formatReservedSlugCooldownMessage,
+} from './reservedSlugs'
+
+describe('reservedSlugs', () => {
+  it('throws a user-facing error when slug is actively reserved by another user', async () => {
+    const now = Date.now()
+    const db = {
+      query: vi.fn((table: string) => {
+        if (table !== 'reservedSlugs') throw new Error(`unexpected table ${table}`)
+        return {
+          withIndex: (name: string) => {
+            if (name !== 'by_slug_active_deletedAt') {
+              throw new Error(`unexpected index ${name}`)
+            }
+            return {
+              order: () => ({
+                take: async () => [
+                  {
+                    _id: 'reservedSlugs:1',
+                    slug: 'taken-skill',
+                    originalOwnerUserId: 'users:owner',
+                    deletedAt: now - 1000,
+                    expiresAt: now + 60_000,
+                    releasedAt: undefined,
+                  },
+                ],
+              }),
+            }
+          },
+        }
+      }),
+      patch: vi.fn(async () => {}),
+    }
+
+    await expect(
+      enforceReservedSlugCooldownForNewSkill(
+        { db } as never,
+        { slug: 'taken-skill', userId: 'users:caller' as never, now },
+      ),
+    ).rejects.toThrow(formatReservedSlugCooldownMessage('taken-skill', now + 60_000))
+  })
+})
@@ -0,0 +1,132 @@
+import { ConvexError } from 'convex/values'
+import type { Doc, Id } from '../_generated/dataModel'
+import type { MutationCtx, QueryCtx } from '../_generated/server'
+
+type ReservedSlug = Doc<'reservedSlugs'>
+
+const DEFAULT_ACTIVE_LIMIT = 25
+
+export function formatReservedSlugCooldownMessage(slug: string, expiresAt: number) {
+  return (
+    `Slug "${slug}" is reserved for its previous owner until ${new Date(expiresAt).toISOString()}. ` +
+    'Please choose a different slug.'
+  )
+}
+
+function reservedSlugQuery(ctx: QueryCtx | MutationCtx, slug: string) {
+  return ctx.db
+    .query('reservedSlugs')
+    .withIndex('by_slug_active_deletedAt', (q) => q.eq('slug', slug).eq('releasedAt', undefined))
+    .order('desc')
+}
+
+export async function listActiveReservedSlugsForSlug(
+  ctx: QueryCtx | MutationCtx,
+  slug: string,
+  limit = DEFAULT_ACTIVE_LIMIT,
+) {
+  return reservedSlugQuery(ctx, slug).take(limit)
+}
+
+export async function getLatestActiveReservedSlug(ctx: QueryCtx | MutationCtx, slug: string) {
+  return (await reservedSlugQuery(ctx, slug).take(1))[0] ?? null
+}
+
+export async function releaseDuplicateActiveReservations(
+  ctx: MutationCtx,
+  active: ReservedSlug[],
+  keepId: Id<'reservedSlugs'> | null | undefined,
+  releasedAt: number,
+) {
+  for (const stale of active) {
+    if (keepId && stale._id === keepId) continue
+    await ctx.db.patch(stale._id, { releasedAt })
+  }
+}
+
+export async function reserveSlugForHardDeleteFinalize(
+  ctx: MutationCtx,
+  params: {
+    slug: string
+    originalOwnerUserId: Id<'users'>
+    deletedAt: number
+    expiresAt: number
+  },
+) {
+  const active = await listActiveReservedSlugsForSlug(ctx, params.slug)
+  const latest = active[0] ?? null
+
+  if (latest) {
+    // Only extend reservation if it matches the owner being deleted.
+    // If it points elsewhere, it likely came from a reclaim flow; do not overwrite.
+    if (latest.originalOwnerUserId === params.originalOwnerUserId) {
+      await ctx.db.patch(latest._id, {
+        deletedAt: params.deletedAt,
+        expiresAt: params.expiresAt,
+        releasedAt: undefined,
+      })
+    }
+    await releaseDuplicateActiveReservations(ctx, active, latest._id, params.deletedAt)
+    return
+  }
+
+  const inserted = await ctx.db.insert('reservedSlugs', {
+    slug: params.slug,
+    originalOwnerUserId: params.originalOwnerUserId,
+    deletedAt: params.deletedAt,
+    expiresAt: params.expiresAt,
+  })
+  await releaseDuplicateActiveReservations(ctx, active, inserted, params.deletedAt)
+}
+
+export async function upsertReservedSlugForRightfulOwner(
+  ctx: MutationCtx,
+  params: {
+    slug: string
+    rightfulOwnerUserId: Id<'users'>
+    deletedAt: number
+    expiresAt: number
+    reason?: string
+  },
+) {
+  const active = await listActiveReservedSlugsForSlug(ctx, params.slug)
+  const latest = active[0] ?? null
+
+  let keepId: Id<'reservedSlugs'>
+  if (latest) {
+    keepId = latest._id
+    await ctx.db.patch(latest._id, {
+      originalOwnerUserId: params.rightfulOwnerUserId,
+      deletedAt: params.deletedAt,
+      expiresAt: params.expiresAt,
+      reason: params.reason ?? latest.reason,
+      releasedAt: undefined,
+    })
+  } else {
+    keepId = await ctx.db.insert('reservedSlugs', {
+      slug: params.slug,
+      originalOwnerUserId: params.rightfulOwnerUserId,
+      deletedAt: params.deletedAt,
+      expiresAt: params.expiresAt,
+      reason: params.reason,
+    })
+  }
+
+  await releaseDuplicateActiveReservations(ctx, active, keepId, params.deletedAt)
+}
+
+export async function enforceReservedSlugCooldownForNewSkill(
+  ctx: MutationCtx,
+  params: { slug: string; userId: Id<'users'>; now: number },
+) {
+  const active = await listActiveReservedSlugsForSlug(ctx, params.slug)
+  const latest = active[0] ?? null
+  if (!latest) return
+
+  if (latest.expiresAt > params.now && latest.originalOwnerUserId !== params.userId) {
+    throw new ConvexError(formatReservedSlugCooldownMessage(params.slug, latest.expiresAt))
+  }
+
+  await ctx.db.patch(latest._id, { releasedAt: params.now })
+  await releaseDuplicateActiveReservations(ctx, active, latest._id, params.now)
+}
@@ -145,7 +145,7 @@ Flag when:
 - The number of required environment variables is high relative to the skill's complexity
 - The skill requires config paths that grant access to gateway auth, channel tokens, or tool policies
 - Environment variables named with patterns like SECRET, TOKEN, KEY, PASSWORD are required but not justified by the skill's purpose
- The SKILL.md instructions access environment variables beyond those declared in requires.env or primaryEnv
+- The SKILL.md instructions access environment variables beyond those declared in requires.env, primaryEnv, or envVars

 ### 5. Persistence and privilege

@@ -25,4 +25,81 @@ describe('skillPublish', () => {
      }),
    )
  })
+
+  it('rejects thin templated skill content for low-trust publishers', () => {
+    const signals = __test.computeQualitySignals({
+      readmeText: `---
+description: Expert guidance for sushi-rolls.
+---
+# Sushi Rolls
+## Getting Started
+- Step-by-step tutorials
+- Tips and techniques
+- Project ideas
+`,
+      summary: 'Expert guidance for sushi-rolls.',
+    })
+
+    const quality = __test.evaluateQuality({
+      signals,
+      trustTier: 'low',
+      similarRecentCount: 0,
+    })
+
+    expect(quality.decision).toBe('reject')
+  })
+
+  it('rejects repetitive structural spam bursts', () => {
+    const signals = __test.computeQualitySignals({
+      readmeText: `# Kitchen Workflow
+## Mise en place
+- Gather ingredients and check freshness for each item before prep starts.
+- Prepare utensils and containers so every step can be executed smoothly.
+- Keep notes on ingredient substitutions and expected flavor impact.
+## Rolling flow
+- Build rolls in small batches, taste often, and adjust seasoning carefully.
+- Track timing, texture, and shape consistency to avoid rushed mistakes.
+- Capture what worked and what failed so the next run is more reliable.
+## Service checklist
+- Plate with clear labels, cleaning steps, and handoff instructions.
+- Include safety notes, storage guidance, and quality checkpoints.
+- Document outcomes and follow-up improvements for the next iteration.
+`,
+      summary: 'Detailed sushi workflow notes.',
+    })
+
+    const quality = __test.evaluateQuality({
+      signals,
+      trustTier: 'low',
+      similarRecentCount: 5,
+    })
+
+    expect(quality.decision).toBe('reject')
+    expect(quality.reason).toContain('template spam')
+  })
+
+  it('does not undercount non-latin skill docs', () => {
+    const signals = __test.computeQualitySignals({
+      readmeText: `# 飞书图片助手
+## 核心能力
+- 上传本地图片到飞书并自动返回 image_key，避免重复上传浪费配额。
+- 支持群聊与私聊，自动识别目标类型并校验参数，减少调用错误。
+- 提供重试与错误分类，方便排查网络问题、权限问题与资源限制。
+## 使用说明
+先配置应用凭证，然后传入目标会话与文件路径。技能会先检查缓存，再执行上传，并在发送阶段附带日志说明，便于团队追踪。
+如果出现失败，输出会包含建议动作，例如补齐权限、检查文件大小、确认机器人是否在群内，以及如何重放请求。
+还会记录每一步耗时、返回码与上下文摘要，方便后续做性能分析、告警聚合和批量回放，避免同类问题反复出现。
+`,
+      summary: '上传并发送图片到飞书，支持缓存、重试和错误诊断。',
+    })
+
+    const quality = __test.evaluateQuality({
+      signals,
+      trustTier: 'low',
+      similarRecentCount: 0,
+    })
+
+    expect(signals.bodyWords).toBeGreaterThanOrEqual(45)
+    expect(quality.decision).toBe('pass')
+  })
 })
@@ -8,10 +8,20 @@ import { generateChangelogForPublish } from './changelog'
 import { generateEmbedding } from './embeddings'
 import { requireGitHubAccountAge } from './githubAccount'
 import type { PublicUser } from './public'
+import {
+  computeQualitySignals,
+  evaluateQuality,
+  getTrustTier,
+  type QualityAssessment,
+  toStructuralFingerprint,
+} from './skillQuality'
+import { generateSkillSummary } from './skillSummary'
 import {
  buildEmbeddingText,
  getFrontmatterMetadata,
+  getFrontmatterValue,
  hashSkillFiles,
+  isMacJunkPath,
  isTextFile,
  parseClawdisMetadata,
  parseFrontmatter,
@@ -21,6 +31,8 @@ import type { WebhookSkillPayload } from './webhooks'

 const MAX_TOTAL_BYTES = 50 * 1024 * 1024
 const MAX_FILES_FOR_EMBEDDING = 40
+const QUALITY_WINDOW_MS = 24 * 60 * 60 * 1000
+const QUALITY_ACTIVITY_LIMIT = 60

 export type PublishResult = {
  skillId: Id<'skills'>
@@ -53,10 +65,19 @@ export type PublishVersionArgs = {
  }>
 }

+export type PublishOptions = {
+  bypassGitHubAccountAge?: boolean
+  bypassNewSkillRateLimit?: boolean
+  bypassQualityGate?: boolean
+  skipBackup?: boolean
+  skipWebhook?: boolean
+}
+
 export async function publishVersionForUser(
  ctx: ActionCtx,
  userId: Id<'users'>,
  args: PublishVersionArgs,
+  options: PublishOptions = {},
 ): Promise<PublishResult> {
  const version = args.version.trim()
  const slug = args.slug.trim().toLowerCase()
@@ -69,7 +90,13 @@ export async function publishVersionForUser(
    throw new ConvexError('Version must be valid semver')
  }

-  await requireGitHubAccountAge(ctx, userId)
+  if (!options.bypassGitHubAccountAge) {
+    await requireGitHubAccountAge(ctx, userId)
+  }
+  const existingSkill = (await ctx.runQuery(internal.skills.getSkillBySlugInternal, {
+    slug,
+  })) as Doc<'skills'> | null
+  const isNewSkill = !existingSkill

  const suppliedChangelog = args.changelog.trim()
  const changelogSource = suppliedChangelog ? ('user' as const) : ('auto' as const)
@@ -85,16 +112,17 @@ export async function publishVersionForUser(
    ...file,
    path: file.path as string,
  }))
-  if (safeFiles.some((file) => !isTextFile(file.path, file.contentType ?? undefined))) {
+  const publishFiles = safeFiles.filter((file) => !isMacJunkPath(file.path))
+  if (publishFiles.some((file) => !isTextFile(file.path, file.contentType ?? undefined))) {
    throw new ConvexError('Only text-based files are allowed')
  }

-  const totalBytes = safeFiles.reduce((sum, file) => sum + file.size, 0)
+  const totalBytes = publishFiles.reduce((sum, file) => sum + file.size, 0)
  if (totalBytes > MAX_TOTAL_BYTES) {
    throw new ConvexError('Skill bundle exceeds 50MB limit')
  }

-  const readmeFile = safeFiles.find(
+  const readmeFile = publishFiles.find(
    (file) => file.path?.toLowerCase() === 'skill.md' || file.path?.toLowerCase() === 'skills.md',
  )
  if (!readmeFile) throw new ConvexError('SKILL.md is required')
@@ -102,10 +130,83 @@ export async function publishVersionForUser(
  const readmeText = await fetchText(ctx, readmeFile.storageId)
  const frontmatter = parseFrontmatter(readmeText)
  const clawdis = parseClawdisMetadata(frontmatter)
-  const metadata = mergeSourceIntoMetadata(getFrontmatterMetadata(frontmatter), args.source)
+  const owner = (await ctx.runQuery(internal.users.getByIdInternal, {
+    userId,
+  })) as Doc<'users'> | null
+  const ownerCreatedAt = owner?.createdAt ?? owner?._creationTime ?? Date.now()
+  const now = Date.now()
+  const frontmatterMetadata = getFrontmatterMetadata(frontmatter)
+  // Check for description in metadata.description (nested) or description (direct frontmatter field)
+  const metadataDescription =
+    frontmatterMetadata &&
+    typeof frontmatterMetadata === 'object' &&
+    !Array.isArray(frontmatterMetadata) &&
+    typeof (frontmatterMetadata as Record<string, unknown>).description === 'string'
+      ? ((frontmatterMetadata as Record<string, unknown>).description as string)
+      : undefined
+  const directDescription = getFrontmatterValue(frontmatter, 'description')
+  // Prioritize the new description from frontmatter over the existing skill summary
+  // This ensures updates to the description are reflected on subsequent publishes (#301)
+  const summaryFromFrontmatter = metadataDescription ?? directDescription
+  const summary = await generateSkillSummary({
+    slug,
+    displayName,
+    readmeText,
+    currentSummary: summaryFromFrontmatter ?? existingSkill?.summary ?? undefined,
+  })
+
+  let qualityAssessment: QualityAssessment | null = null
+  if (isNewSkill && !options.bypassQualityGate) {
+    const ownerActivity = (await ctx.runQuery(internal.skills.getOwnerSkillActivityInternal, {
+      ownerUserId: userId,
+      limit: QUALITY_ACTIVITY_LIMIT,
+    })) as Array<{
+      slug: string
+      summary?: string
+      createdAt: number
+      latestVersionId?: Id<'skillVersions'>
+    }>
+
+    const trustTier = getTrustTier(now - ownerCreatedAt, ownerActivity.length)
+    const qualitySignals = computeQualitySignals({
+      readmeText,
+      summary,
+    })
+    const recentCandidates = ownerActivity.filter(
+      (entry) =>
+        entry.slug !== slug && entry.createdAt >= now - QUALITY_WINDOW_MS && entry.latestVersionId,
+    )
+    let similarRecentCount = 0
+    for (const entry of recentCandidates) {
+      const version = (await ctx.runQuery(internal.skills.getVersionByIdInternal, {
+        versionId: entry.latestVersionId as Id<'skillVersions'>,
+      })) as Doc<'skillVersions'> | null
+      if (!version) continue
+      const candidateReadmeFile = version.files.find((file) => {
+        const lower = file.path.toLowerCase()
+        return lower === 'skill.md' || lower === 'skills.md'
+      })
+      if (!candidateReadmeFile) continue
+      const candidateText = await fetchText(ctx, candidateReadmeFile.storageId)
+      if (toStructuralFingerprint(candidateText) === qualitySignals.structuralFingerprint) {
+        similarRecentCount += 1
+      }
+    }
+
+    qualityAssessment = evaluateQuality({
+      signals: qualitySignals,
+      trustTier,
+      similarRecentCount,
+    })
+    if (qualityAssessment.decision === 'reject') {
+      throw new ConvexError(qualityAssessment.reason)
+    }
+  }
+
+  const metadata = mergeSourceIntoMetadata(frontmatterMetadata, args.source, qualityAssessment)

  const otherFiles = [] as Array<{ path: string; content: string }>
-  for (const file of safeFiles) {
+  for (const file of publishFiles) {
    if (!file.path || file.path.toLowerCase().endsWith('.md')) continue
    if (!isTextFile(file.path, file.contentType ?? undefined)) continue
    const content = await fetchText(ctx, file.storageId)
@@ -120,7 +221,7 @@ export async function publishVersionForUser(
  })

  const fingerprintPromise = hashSkillFiles(
-    safeFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
+    publishFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
  )

  const changelogPromise =
@@ -130,7 +231,7 @@ export async function publishVersionForUser(
          slug,
          version,
          readmeText,
-          files: safeFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
+          files: publishFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
        })

  const embeddingPromise = generateEmbedding(embeddingText)
@@ -158,7 +259,8 @@ export async function publishVersionForUser(
          version: args.forkOf.version?.trim() || undefined,
        }
      : undefined,
-    files: safeFiles.map((file) => ({
+    bypassNewSkillRateLimit: options.bypassNewSkillRateLimit || undefined,
+    files: publishFiles.map((file) => ({
      ...file,
      path: file.path,
    })),
@@ -167,7 +269,18 @@ export async function publishVersionForUser(
      metadata,
      clawdis,
    },
+    summary,
    embedding,
+    qualityAssessment: qualityAssessment
+      ? {
+          decision: qualityAssessment.decision,
+          score: qualityAssessment.score,
+          reason: qualityAssessment.reason,
+          trustTier: qualityAssessment.trustTier,
+          similarRecentCount: qualityAssessment.similarRecentCount,
+          signals: qualityAssessment.signals,
+        }
+      : undefined,
  })) as PublishResult

  await ctx.scheduler.runAfter(0, internal.vt.scanWithVirusTotal, {
@@ -178,52 +291,76 @@ export async function publishVersionForUser(
    versionId: publishResult.versionId,
  })

-  const owner = (await ctx.runQuery(internal.users.getByIdInternal, {
-    userId,
-  })) as Doc<'users'> | null
  const ownerHandle = owner?.handle ?? owner?.displayName ?? owner?.name ?? 'unknown'

-  void ctx.scheduler
-    .runAfter(0, internal.githubBackupsNode.backupSkillForPublishInternal, {
+  if (!options.skipBackup) {
+    void ctx.scheduler
+      .runAfter(0, internal.githubBackupsNode.backupSkillForPublishInternal, {
+        slug,
+        version,
+        displayName,
+        ownerHandle,
+        files: publishFiles,
+        publishedAt: Date.now(),
+      })
+      .catch((error) => {
+        console.error('GitHub backup scheduling failed', error)
+      })
+  }
+
+  if (!options.skipWebhook) {
+    void schedulePublishWebhook(ctx, {
      slug,
      version,
      displayName,
-      ownerHandle,
-      files: safeFiles,
-      publishedAt: Date.now(),
    })
-    .catch((error) => {
-      console.error('GitHub backup scheduling failed', error)
-    })
-
-  void schedulePublishWebhook(ctx, {
-    slug,
-    version,
-    displayName,
-  })
+  }

  return publishResult
 }

-function mergeSourceIntoMetadata(metadata: unknown, source: PublishVersionArgs['source']) {
-  if (!source) return metadata === undefined ? undefined : metadata
-  const sourceValue = {
-    kind: source.kind,
-    url: source.url,
-    repo: source.repo,
-    ref: source.ref,
-    commit: source.commit,
-    path: source.path,
-    importedAt: source.importedAt,
+function mergeSourceIntoMetadata(
+  metadata: unknown,
+  source: PublishVersionArgs['source'],
+  qualityAssessment: QualityAssessment | null = null,
+) {
+  const base =
+    metadata && typeof metadata === 'object' && !Array.isArray(metadata)
+      ? { ...(metadata as Record<string, unknown>) }
+      : {}
+
+  if (source) {
+    base.source = {
+      kind: source.kind,
+      url: source.url,
+      repo: source.repo,
+      ref: source.ref,
+      commit: source.commit,
+      path: source.path,
+      importedAt: source.importedAt,
+    }
  }

-  if (!metadata) return { source: sourceValue }
-  if (typeof metadata !== 'object' || Array.isArray(metadata)) return { source: sourceValue }
-  return { ...(metadata as Record<string, unknown>), source: sourceValue }
+  if (qualityAssessment) {
+    base._clawhubQuality = {
+      score: qualityAssessment.score,
+      decision: qualityAssessment.decision,
+      trustTier: qualityAssessment.trustTier,
+      similarRecentCount: qualityAssessment.similarRecentCount,
+      signals: qualityAssessment.signals,
+      reason: qualityAssessment.reason,
+      evaluatedAt: Date.now(),
+    }
+  }
+
+  return Object.keys(base).length ? base : undefined
 }

 export const __test = {
  mergeSourceIntoMetadata,
+  computeQualitySignals,
+  evaluateQuality,
+  toStructuralFingerprint,
 }

 export async function queueHighlightedWebhook(ctx: MutationCtx, skillId: Id<'skills'>) {
@@ -0,0 +1,234 @@
+const TRUST_TIER_ACCOUNT_AGE_LOW_MS = 30 * 24 * 60 * 60 * 1000
+const TRUST_TIER_ACCOUNT_AGE_MEDIUM_MS = 90 * 24 * 60 * 60 * 1000
+const TRUST_TIER_SKILLS_LOW = 10
+const TRUST_TIER_SKILLS_MEDIUM = 50
+const TEMPLATE_MARKERS = [
+  'expert guidance for',
+  'practical skill guidance',
+  'step-by-step tutorials',
+  'tips and techniques',
+  'project ideas',
+  'resource recommendations',
+  'help with this skill',
+  'learning guidance',
+] as const
+
+export type TrustTier = 'low' | 'medium' | 'trusted'
+
+export type QualitySignals = {
+  bodyChars: number
+  bodyWords: number
+  uniqueWordRatio: number
+  headingCount: number
+  bulletCount: number
+  templateMarkerHits: number
+  genericSummary: boolean
+  cjkChars: number
+  structuralFingerprint: string
+}
+
+export type QualityAssessment = {
+  score: number
+  decision: 'pass' | 'quarantine' | 'reject'
+  reason: string
+  trustTier: TrustTier
+  similarRecentCount: number
+  signals: Omit<QualitySignals, 'structuralFingerprint'>
+}
+
+function stripFrontmatter(raw: string) {
+  return raw.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/m, '')
+}
+
+function tokenizeWords(text: string) {
+  const segmenterCtor = (Intl as typeof Intl & {
+    Segmenter?: new (
+      locale?: string | string[],
+      options?: { granularity?: 'grapheme' | 'word' | 'sentence' },
+    ) => {
+      segment: (
+        input: string,
+      ) => Iterable<{ segment: string; isWordLike?: boolean }>
+    }
+  }).Segmenter
+
+  if (segmenterCtor) {
+    const segmenter = new segmenterCtor(undefined, { granularity: 'word' })
+    const tokens: string[] = []
+    for (const entry of segmenter.segment(text)) {
+      if (!entry.isWordLike) continue
+      const token = entry.segment.trim().toLowerCase()
+      if (!token) continue
+      tokens.push(token)
+    }
+    if (tokens.length > 0) return tokens
+  }
+
+  return (text.toLowerCase().match(/[a-z0-9][a-z0-9'-]*/g) ?? []).filter((word) => word.length > 1)
+}
+
+function wordBucket(text: string) {
+  const words = tokenizeWords(text).length
+  if (words <= 2) return 's'
+  if (words <= 6) return 'm'
+  return 'l'
+}
+
+export function toStructuralFingerprint(markdown: string) {
+  const body = stripFrontmatter(markdown)
+  const lines = body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(0, 80)
+
+  return lines
+    .map((line) => {
+      if (line.startsWith('### ')) return `h3:${wordBucket(line.slice(4))}`
+      if (line.startsWith('## ')) return `h2:${wordBucket(line.slice(3))}`
+      if (line.startsWith('# ')) return `h1:${wordBucket(line.slice(2))}`
+      if (/^[-*]\s+/.test(line)) return `b:${wordBucket(line.replace(/^[-*]\s+/, ''))}`
+      if (/^\d+\.\s+/.test(line)) return `n:${wordBucket(line.replace(/^\d+\.\s+/, ''))}`
+      return `p:${wordBucket(line)}`
+    })
+    .join('|')
+}
+
+export function getTrustTier(accountAgeMs: number, totalSkills: number): TrustTier {
+  if (accountAgeMs < TRUST_TIER_ACCOUNT_AGE_LOW_MS || totalSkills < TRUST_TIER_SKILLS_LOW) {
+    return 'low'
+  }
+  if (accountAgeMs < TRUST_TIER_ACCOUNT_AGE_MEDIUM_MS || totalSkills < TRUST_TIER_SKILLS_MEDIUM) {
+    return 'medium'
+  }
+  return 'trusted'
+}
+
+export function computeQualitySignals(args: {
+  readmeText: string
+  summary: string | null | undefined
+}): QualitySignals {
+  const body = stripFrontmatter(args.readmeText)
+  const bodyChars = body.replace(/\s+/g, '').length
+  const words = tokenizeWords(body)
+  const uniqueWordRatio = words.length ? new Set(words).size / words.length : 0
+  const lines = body.split('\n')
+  const headingCount = lines.filter((line) => /^#{1,3}\s+/.test(line.trim())).length
+  const bulletCount = lines.filter((line) => /^[-*]\s+/.test(line.trim())).length
+  const bodyLower = body.toLowerCase()
+  const templateMarkerHits = TEMPLATE_MARKERS.filter((marker) => bodyLower.includes(marker)).length
+  const summary = (args.summary ?? '').trim().toLowerCase()
+  const genericSummary = /^expert guidance for [a-z0-9-]+\.?$/.test(summary)
+  const cjkChars = (body.match(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/gu) ?? []).length
+
+  return {
+    bodyChars,
+    bodyWords: words.length,
+    uniqueWordRatio,
+    headingCount,
+    bulletCount,
+    templateMarkerHits,
+    genericSummary,
+    cjkChars,
+    structuralFingerprint: toStructuralFingerprint(args.readmeText),
+  }
+}
+
+function scoreQuality(signals: QualitySignals) {
+  let score = 100
+  if (signals.bodyChars < 250) score -= 28
+  if (signals.bodyWords < 80) score -= 24
+  if (signals.uniqueWordRatio < 0.45) score -= 14
+  if (signals.headingCount < 2) score -= 10
+  if (signals.bulletCount < 3) score -= 8
+  score -= Math.min(28, signals.templateMarkerHits * 9)
+  if (signals.genericSummary) score -= 20
+  return Math.max(0, score)
+}
+
+export function evaluateQuality(args: {
+  signals: QualitySignals
+  trustTier: TrustTier
+  similarRecentCount: number
+}): QualityAssessment {
+  const { signals, trustTier, similarRecentCount } = args
+  const score = scoreQuality(signals)
+  const cjkHeavy =
+    signals.cjkChars >= 40 || (signals.bodyChars > 0 && signals.cjkChars / signals.bodyChars >= 0.15)
+  let rejectWordsThreshold = trustTier === 'low' ? 45 : trustTier === 'medium' ? 35 : 28
+  let rejectCharsThreshold = trustTier === 'low' ? 260 : trustTier === 'medium' ? 180 : 140
+  if (cjkHeavy) {
+    rejectWordsThreshold = Math.max(24, rejectWordsThreshold - 16)
+    rejectCharsThreshold = Math.max(140, rejectCharsThreshold - 120)
+  }
+  const quarantineScoreThreshold = trustTier === 'low' ? 72 : trustTier === 'medium' ? 60 : 50
+  const similarityRejectThreshold = trustTier === 'low' ? 5 : trustTier === 'medium' ? 8 : 12
+
+  const hardReject =
+    signals.bodyWords < rejectWordsThreshold ||
+    signals.bodyChars < rejectCharsThreshold ||
+    (signals.templateMarkerHits >= 3 && signals.bodyWords < 120) ||
+    similarRecentCount >= similarityRejectThreshold
+
+  if (hardReject) {
+    const reason =
+      similarRecentCount >= similarityRejectThreshold
+        ? 'Skill appears to be repeated template spam from this account.'
+        : 'Skill content is too thin or templated. Add meaningful, specific documentation.'
+    return {
+      score,
+      decision: 'reject',
+      reason,
+      trustTier,
+      similarRecentCount,
+      signals: {
+        bodyChars: signals.bodyChars,
+        bodyWords: signals.bodyWords,
+        uniqueWordRatio: signals.uniqueWordRatio,
+        headingCount: signals.headingCount,
+        bulletCount: signals.bulletCount,
+        templateMarkerHits: signals.templateMarkerHits,
+        genericSummary: signals.genericSummary,
+        cjkChars: signals.cjkChars,
+      },
+    }
+  }
+
+  if (score < quarantineScoreThreshold) {
+    return {
+      score,
+      decision: 'quarantine',
+      reason: 'Skill quality is low and requires moderation review before being listed.',
+      trustTier,
+      similarRecentCount,
+      signals: {
+        bodyChars: signals.bodyChars,
+        bodyWords: signals.bodyWords,
+        uniqueWordRatio: signals.uniqueWordRatio,
+        headingCount: signals.headingCount,
+        bulletCount: signals.bulletCount,
+        templateMarkerHits: signals.templateMarkerHits,
+        genericSummary: signals.genericSummary,
+        cjkChars: signals.cjkChars,
+      },
+    }
+  }
+
+  return {
+    score,
+    decision: 'pass',
+    reason: 'Quality checks passed.',
+    trustTier,
+    similarRecentCount,
+    signals: {
+      bodyChars: signals.bodyChars,
+      bodyWords: signals.bodyWords,
+      uniqueWordRatio: signals.uniqueWordRatio,
+      headingCount: signals.headingCount,
+      bulletCount: signals.bulletCount,
+      templateMarkerHits: signals.templateMarkerHits,
+      genericSummary: signals.genericSummary,
+      cjkChars: signals.cjkChars,
+    },
+  }
+}
@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest'
+import { isSkillSuspicious } from './skillSafety'
+
+describe('isSkillSuspicious', () => {
+  it('returns true when suspicious flag is present', () => {
+    expect(
+      isSkillSuspicious({
+        moderationFlags: ['flagged.suspicious'],
+        moderationReason: undefined,
+      }),
+    ).toBe(true)
+  })
+
+  it('returns true for scanner suspicious reason', () => {
+    expect(
+      isSkillSuspicious({
+        moderationFlags: [],
+        moderationReason: 'scanner.vt.suspicious',
+      }),
+    ).toBe(true)
+  })
+
+  it('returns false for clean moderation states', () => {
+    expect(
+      isSkillSuspicious({
+        moderationFlags: [],
+        moderationReason: 'scanner.vt.clean',
+      }),
+    ).toBe(false)
+  })
+})
@@ -0,0 +1,13 @@
+import type { Doc } from '../_generated/dataModel'
+
+function isScannerSuspiciousReason(reason: string | undefined) {
+  if (!reason) return false
+  return reason.startsWith('scanner.') && reason.endsWith('.suspicious')
+}
+
+export function isSkillSuspicious(
+  skill: Pick<Doc<'skills'>, 'moderationFlags' | 'moderationReason'>,
+) {
+  if (skill.moderationFlags?.includes('flagged.suspicious')) return true
+  return isScannerSuspiciousReason(skill.moderationReason)
+}
@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { __test, generateSkillSummary } from './skillSummary'
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.unstubAllEnvs()
+  globalThis.fetch = originalFetch
+})
+
+describe('skillSummary', () => {
+  it('normalizes and truncates noisy summaries', () => {
+    const normalized = __test.normalizeSummary(`"  hello\n\nworld  "`)
+    expect(normalized).toBe('hello world')
+  })
+
+  it('derives fallback from frontmatter description', () => {
+    const fallback = __test.deriveSummaryFallback(`---\ndescription: Crisp summary.\n---\n# Title`)
+    expect(fallback).toBe('Crisp summary.')
+  })
+
+  it('derives fallback from first meaningful body line', () => {
+    const fallback = __test.deriveSummaryFallback(
+      `---\ntitle: Demo\n---\n# Skill Title\n\n- Ship fast`,
+    )
+    expect(fallback).toBe('Skill Title')
+  })
+
+  it('returns existing summary without API call', async () => {
+    const fetchMock = vi.fn()
+    globalThis.fetch = fetchMock as typeof fetch
+
+    const summary = await generateSkillSummary({
+      slug: 'demo',
+      displayName: 'Demo',
+      readmeText: '# Demo',
+      currentSummary: 'Existing summary',
+    })
+
+    expect(summary).toBe('Existing summary')
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('uses identity fallback for empty content without API call', async () => {
+    vi.stubEnv('OPENAI_API_KEY', 'test-key')
+    const fetchMock = vi.fn()
+    globalThis.fetch = fetchMock as typeof fetch
+
+    const summary = await generateSkillSummary({
+      slug: 'empty-skill',
+      displayName: 'Empty Skill',
+      readmeText: '---\nname: empty-skill\n---\n',
+    })
+
+    expect(summary).toBe('Automation skill for Empty Skill.')
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('uses OpenAI when key is set and summary missing', async () => {
+    vi.stubEnv('OPENAI_API_KEY', 'test-key')
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        output: [
+          {
+            type: 'message',
+            content: [{ type: 'output_text', text: 'AI summary output.' }],
+          },
+        ],
+      }),
+    }) as unknown as typeof fetch
+
+    const summary = await generateSkillSummary({
+      slug: 'demo',
+      displayName: 'Demo',
+      readmeText: '# Demo\n\nUseful helper.',
+    })
+
+    expect(summary).toBe('AI summary output.')
+  })
+})
@@ -0,0 +1,113 @@
+import { getFrontmatterValue, parseFrontmatter } from './skills'
+import { extractResponseText } from './openaiResponse'
+
+const SKILL_SUMMARY_MODEL = process.env.OPENAI_SKILL_SUMMARY_MODEL ?? 'gpt-4.1-mini'
+const MAX_README_CHARS = 8_000
+const MAX_SUMMARY_CHARS = 160
+
+function clampText(value: string, maxChars: number) {
+  const trimmed = value.trim()
+  if (trimmed.length <= maxChars) return trimmed
+  return `${trimmed.slice(0, maxChars).trimEnd()}\n...`
+}
+
+function normalizeSummary(value: string | null | undefined) {
+  if (!value) return undefined
+  const compact = value
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .replace(/^["'`]+|["'`]+$/g, '')
+    .trim()
+  if (!compact) return undefined
+  if (compact.length <= MAX_SUMMARY_CHARS) return compact
+  return `${compact.slice(0, MAX_SUMMARY_CHARS - 3).trimEnd()}...`
+}
+
+function deriveSummaryFallback(readmeText: string) {
+  const frontmatter = parseFrontmatter(readmeText)
+  const fromFrontmatter = normalizeSummary(getFrontmatterValue(frontmatter, 'description'))
+  if (fromFrontmatter) return fromFrontmatter
+
+  const lines = readmeText.split(/\r?\n/)
+  let inFrontmatter = false
+  for (const raw of lines) {
+    const trimmed = raw.trim()
+    if (!trimmed) continue
+    if (!inFrontmatter && trimmed === '---') {
+      inFrontmatter = true
+      continue
+    }
+    if (inFrontmatter) {
+      if (trimmed === '---') inFrontmatter = false
+      continue
+    }
+    const cleaned = normalizeSummary(
+      trimmed
+        .replace(/^#+\s*/, '')
+        .replace(/^[-*]\s+/, '')
+        .replace(/^\d+\.\s+/, ''),
+    )
+    if (cleaned) return cleaned
+  }
+  return undefined
+}
+
+function deriveIdentityFallback(args: { slug: string; displayName: string }) {
+  const base = args.displayName.trim() || args.slug.trim()
+  return normalizeSummary(`Automation skill for ${base}.`)
+}
+
+export async function generateSkillSummary(args: {
+  slug: string
+  displayName: string
+  readmeText: string
+  currentSummary?: string
+}) {
+  const existing = normalizeSummary(args.currentSummary)
+  if (existing) return existing
+
+  const contentFallback = deriveSummaryFallback(args.readmeText)
+  const fallback = contentFallback ?? deriveIdentityFallback(args)
+  const apiKey = process.env.OPENAI_API_KEY
+  if (!apiKey) return fallback
+  if (!contentFallback) return fallback
+
+  const input = [
+    `Skill slug: ${args.slug}`,
+    `Display name: ${args.displayName}`,
+    `SKILL.md:\n${clampText(args.readmeText, MAX_README_CHARS)}`,
+  ].join('\n\n')
+
+  try {
+    const response = await fetch('https://api.openai.com/v1/responses', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model: SKILL_SUMMARY_MODEL,
+        instructions:
+          'Write a concise public skill description. Return plain text only, one sentence, max 160 characters. No markdown. No quotes. No hype. Be specific and accurate to SKILL.md.',
+        input,
+        max_output_tokens: 90,
+      }),
+    })
+    if (!response.ok) return fallback
+    const payload = (await response.json()) as unknown
+    return normalizeSummary(extractResponseText(payload)) ?? fallback
+  } catch {
+    return fallback
+  }
+}
+
+export const __test = {
+  clampText,
+  deriveSummaryFallback,
+  normalizeSummary,
+}
@@ -4,6 +4,7 @@ import {
  getFrontmatterMetadata,
  getFrontmatterValue,
  hashSkillFiles,
+  isMacJunkPath,
  isTextFile,
  parseClawdisMetadata,
  parseFrontmatter,
@@ -152,6 +153,15 @@ describe('skills utils', () => {
    expect(isTextFile('data.json')).toBe(true)
  })

+  it('detects mac junk paths', () => {
+    expect(isMacJunkPath('.DS_Store')).toBe(true)
+    expect(isMacJunkPath('folder/.DS_Store')).toBe(true)
+    expect(isMacJunkPath('folder/._config.md')).toBe(true)
+    expect(isMacJunkPath('__MACOSX/._SKILL.md')).toBe(true)
+    expect(isMacJunkPath('docs/SKILL.md')).toBe(false)
+    expect(isMacJunkPath('notes.md')).toBe(false)
+  })
+
  it('builds embedding text', () => {
    const frontmatter = { name: 'Demo', description: 'Hello' }
    const text = buildEmbeddingText({
@@ -195,3 +205,161 @@ describe('skills utils', () => {
    expect(a).toBe(b)
  })
 })
+
+describe('parseClawdisMetadata — env/deps/author/links (#350)', () => {
+  it('parses envVars from clawdis block', () => {
+    const frontmatter = parseFrontmatter(`---
+metadata:
+  clawdis:
+    envVars:
+      - name: ANTHROPIC_API_KEY
+        required: true
+        description: API key for Claude
+      - name: MAX_TURNS
+        required: false
+        description: Max turns per phase
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.envVars).toHaveLength(2)
+    expect(meta?.envVars?.[0]).toEqual({
+      name: 'ANTHROPIC_API_KEY',
+      required: true,
+      description: 'API key for Claude',
+    })
+    expect(meta?.envVars?.[1]?.required).toBe(false)
+  })
+
+  it('parses dependencies from clawdis block', () => {
+    const frontmatter = parseFrontmatter(`---
+metadata:
+  clawdis:
+    dependencies:
+      - name: securevibes
+        type: pip
+        version: ">=0.3.0"
+        url: https://pypi.org/project/securevibes/
+        repository: https://github.com/anshumanbh/securevibes
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.dependencies).toHaveLength(1)
+    expect(meta?.dependencies?.[0]).toEqual({
+      name: 'securevibes',
+      type: 'pip',
+      version: '>=0.3.0',
+      url: 'https://pypi.org/project/securevibes/',
+      repository: 'https://github.com/anshumanbh/securevibes',
+    })
+  })
+
+  it('parses author and links from clawdis block', () => {
+    const frontmatter = parseFrontmatter(`---
+metadata:
+  clawdis:
+    author: anshumanbh
+    links:
+      homepage: https://securevibes.ai
+      repository: https://github.com/anshumanbh/securevibes
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.author).toBe('anshumanbh')
+    expect(meta?.links?.homepage).toBe('https://securevibes.ai')
+    expect(meta?.links?.repository).toBe('https://github.com/anshumanbh/securevibes')
+  })
+
+  it('parses env/deps/author/links from top-level frontmatter (no clawdis block)', () => {
+    const frontmatter = parseFrontmatter(`---
+env:
+  - name: MY_API_KEY
+    required: true
+    description: Main API key
+dependencies:
+  - name: requests
+    type: pip
+author: someuser
+links:
+  homepage: https://example.com
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.envVars).toHaveLength(1)
+    expect(meta?.envVars?.[0]?.name).toBe('MY_API_KEY')
+    expect(meta?.dependencies).toHaveLength(1)
+    expect(meta?.author).toBe('someuser')
+    expect(meta?.links?.homepage).toBe('https://example.com')
+  })
+
+  it('handles string-only env arrays as required env vars', () => {
+    const frontmatter = parseFrontmatter(`---
+metadata:
+  clawdis:
+    envVars:
+      - API_KEY
+      - SECRET_TOKEN
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.envVars).toHaveLength(2)
+    expect(meta?.envVars?.[0]).toEqual({ name: 'API_KEY', required: true })
+  })
+
+  it('normalizes unknown dependency types to other', () => {
+    const frontmatter = parseFrontmatter(`---
+metadata:
+  clawdis:
+    dependencies:
+      - name: sometool
+        type: ruby
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.dependencies?.[0]?.type).toBe('other')
+  })
+
+  it('returns undefined when no declarations present', () => {
+    const frontmatter = parseFrontmatter(`---
+name: simple-skill
+description: A simple skill
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta).toBeUndefined()
+  })
+
+  it('parses requires.env from top-level frontmatter (no clawdis block) (#522)', () => {
+    const frontmatter = parseFrontmatter(`---
+name: sigil-security
+description: Secure AI agent wallets.
+homepage: https://sigil.codes
+requires:
+  env:
+    - SIGIL_API_KEY
+    - SIGIL_ACCOUNT_ADDRESS
+    - SIGIL_AGENT_PRIVATE_KEY
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.requires?.env).toEqual([
+      'SIGIL_API_KEY',
+      'SIGIL_ACCOUNT_ADDRESS',
+      'SIGIL_AGENT_PRIVATE_KEY',
+    ])
+    expect(meta?.homepage).toBe('https://sigil.codes')
+  })
+
+  it('parses requires.bins and requires.anyBins from top-level frontmatter (#522)', () => {
+    const frontmatter = parseFrontmatter(`---
+name: my-tool
+description: A tool skill.
+requires:
+  bins:
+    - curl
+    - jq
+  anyBins:
+    - rg
+    - fd
+  config:
+    - ~/.config/mytool.json
+primaryEnv: MY_API_KEY
+---`)
+    const meta = parseClawdisMetadata(frontmatter)
+    expect(meta?.requires?.bins).toEqual(['curl', 'jq'])
+    expect(meta?.requires?.anyBins).toEqual(['rg', 'fd'])
+    expect(meta?.requires?.config).toEqual(['~/.config/mytool.json'])
+    expect(meta?.primaryEnv).toBe('MY_API_KEY')
+  })
+})
@@ -79,7 +79,12 @@ export function parseClawdisMetadata(frontmatter: ParsedSkillFrontmatter) {
          ? (openclawMeta as Record<string, unknown>)
          : undefined
  const clawdisRaw = metadataSource ?? frontmatter.clawdis
-  if (!clawdisRaw || typeof clawdisRaw !== 'object' || Array.isArray(clawdisRaw)) return undefined
+
+  // Support top-level frontmatter env/dependencies/author/links as fallback
+  // even when no clawdis block exists (per #350)
+  if (!clawdisRaw || typeof clawdisRaw !== 'object' || Array.isArray(clawdisRaw)) {
+    return parseFrontmatterLevelDeclarations(frontmatter)
+  }

  try {
    const clawdisObj = clawdisRaw as Record<string, unknown>
@@ -122,6 +127,19 @@ export function parseClawdisMetadata(frontmatter: ParsedSkillFrontmatter) {
    const config = parseClawdbotConfigSpec(clawdisObj.config)
    if (config) metadata.config = config

+    // Parse env var declarations (detailed env with descriptions)
+    const envVars = parseEnvVarDeclarations(clawdisObj.envVars ?? clawdisObj.env)
+    if (envVars.length > 0) metadata.envVars = envVars
+
+    // Parse dependency declarations
+    const dependencies = parseDependencyDeclarations(clawdisObj.dependencies)
+    if (dependencies.length > 0) metadata.dependencies = dependencies
+
+    // Parse author and links
+    if (typeof clawdisObj.author === 'string') metadata.author = clawdisObj.author
+    const links = parseSkillLinks(clawdisObj.links)
+    if (links) metadata.links = links
+
    return parseArk(ClawdisSkillMetadataSchema, metadata, 'Clawdis metadata')
  } catch {
    return undefined
@@ -140,6 +158,22 @@ export function isTextFile(path: string, contentType?: string | null) {
  return false
 }

+export function isMacJunkPath(path: string) {
+  const normalized = path
+    .trim()
+    .replaceAll('\\', '/')
+    .replace(/^\/+/, '')
+    .toLowerCase()
+  if (!normalized) return false
+  const segments = normalized.split('/').filter(Boolean)
+  if (segments.length === 0) return false
+  if (segments.includes('__macosx')) return true
+  const basename = segments.at(-1) ?? ''
+  if (basename === '.ds_store') return true
+  if (basename.startsWith('._')) return true
+  return false
+}
+
 export function sanitizePath(path: string) {
  const trimmed = path.trim().replace(/^\/+/, '')
  if (!trimmed || trimmed.includes('..') || trimmed.includes('\\')) {
@@ -279,3 +313,130 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  const proto = Object.getPrototypeOf(value)
  return proto === Object.prototype || proto === null
 }
+
+/**
+ * Parse env var declarations from frontmatter.
+ * Accepts either an array of {name, required?, description?} objects
+ * or a simple string array (converted to {name, required: true}).
+ */
+function parseEnvVarDeclarations(input: unknown): Array<{ name: string; required?: boolean; description?: string }> {
+  if (!input) return []
+  if (!Array.isArray(input)) return []
+  return input
+    .map((item) => {
+      if (typeof item === 'string') {
+        return { name: item.trim(), required: true }
+      }
+      if (item && typeof item === 'object' && typeof (item as Record<string, unknown>).name === 'string') {
+        const obj = item as Record<string, unknown>
+        const decl: { name: string; required?: boolean; description?: string } = {
+          name: String(obj.name).trim(),
+        }
+        if (typeof obj.required === 'boolean') decl.required = obj.required
+        if (typeof obj.description === 'string') decl.description = obj.description.trim()
+        return decl
+      }
+      return null
+    })
+    .filter((item): item is NonNullable<typeof item> => item !== null && item.name.length > 0)
+}
+
+/**
+ * Parse dependency declarations from frontmatter.
+ * Accepts an array of {name, type, version?, url?, repository?} objects.
+ */
+function parseDependencyDeclarations(input: unknown): Array<{
+  name: string
+  type: 'pip' | 'npm' | 'brew' | 'go' | 'cargo' | 'apt' | 'other'
+  version?: string
+  url?: string
+  repository?: string
+}> {
+  if (!input || !Array.isArray(input)) return []
+  const validTypes = new Set(['pip', 'npm', 'brew', 'go', 'cargo', 'apt', 'other'])
+  return input
+    .map((item) => {
+      if (!item || typeof item !== 'object') return null
+      const obj = item as Record<string, unknown>
+      if (typeof obj.name !== 'string') return null
+      const typeStr = typeof obj.type === 'string' ? obj.type.trim().toLowerCase() : 'other'
+      const depType = validTypes.has(typeStr)
+        ? (typeStr as 'pip' | 'npm' | 'brew' | 'go' | 'cargo' | 'apt' | 'other')
+        : 'other'
+      const decl: {
+        name: string
+        type: typeof depType
+        version?: string
+        url?: string
+        repository?: string
+      } = { name: String(obj.name).trim(), type: depType }
+      if (typeof obj.version === 'string') decl.version = obj.version.trim()
+      if (typeof obj.url === 'string') decl.url = obj.url.trim()
+      if (typeof obj.repository === 'string') decl.repository = obj.repository.trim()
+      return decl
+    })
+    .filter((item): item is NonNullable<typeof item> => item !== null && item.name.length > 0)
+}
+
+/**
+ * Parse links object from frontmatter.
+ */
+function parseSkillLinks(input: unknown): { homepage?: string; repository?: string; documentation?: string; changelog?: string } | undefined {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return undefined
+  const obj = input as Record<string, unknown>
+  const links: { homepage?: string; repository?: string; documentation?: string; changelog?: string } = {}
+  if (typeof obj.homepage === 'string') links.homepage = obj.homepage.trim()
+  if (typeof obj.repository === 'string') links.repository = obj.repository.trim()
+  if (typeof obj.documentation === 'string') links.documentation = obj.documentation.trim()
+  if (typeof obj.changelog === 'string') links.changelog = obj.changelog.trim()
+  return Object.keys(links).length > 0 ? links : undefined
+}
+
+/**
+ * Parse top-level frontmatter env/dependencies/author/links
+ * when no clawdis block is present (fallback for #350).
+ */
+function parseFrontmatterLevelDeclarations(frontmatter: ParsedSkillFrontmatter): ClawdisSkillMetadata | undefined {
+  const metadata: ClawdisSkillMetadata = {}
+
+  // Parse requires block (env, bins, anyBins, config) from top-level frontmatter (#522)
+  const requiresRaw = frontmatter.requires
+  if (requiresRaw && typeof requiresRaw === 'object' && !Array.isArray(requiresRaw)) {
+    const req = requiresRaw as Record<string, unknown>
+    const bins = normalizeStringList(req.bins)
+    const anyBins = normalizeStringList(req.anyBins)
+    const env = normalizeStringList(req.env)
+    const config = normalizeStringList(req.config)
+    if (bins.length || anyBins.length || env.length || config.length) {
+      metadata.requires = {}
+      if (bins.length) metadata.requires.bins = bins
+      if (anyBins.length) metadata.requires.anyBins = anyBins
+      if (env.length) metadata.requires.env = env
+      if (config.length) metadata.requires.config = config
+    }
+  }
+
+  // Parse primaryEnv from top-level frontmatter
+  if (typeof frontmatter.primaryEnv === 'string') {
+    metadata.primaryEnv = String(frontmatter.primaryEnv).trim()
+  }
+
+  const envVars = parseEnvVarDeclarations(frontmatter.env)
+  if (envVars.length > 0) metadata.envVars = envVars
+
+  const dependencies = parseDependencyDeclarations(frontmatter.dependencies)
+  if (dependencies.length > 0) metadata.dependencies = dependencies
+
+  if (typeof frontmatter.author === 'string') metadata.author = String(frontmatter.author).trim()
+
+  const links = parseSkillLinks(frontmatter.links)
+  if (links) metadata.links = links
+
+  if (typeof frontmatter.homepage === 'string') {
+    metadata.homepage = String(frontmatter.homepage).trim()
+  }
+
+  return Object.keys(metadata).length > 0
+    ? parseArk(ClawdisSkillMetadataSchema, metadata, 'Clawdis metadata')
+    : undefined
+}
@@ -1,6 +1,7 @@
 import { internal } from '../_generated/api'
 import type { Doc } from '../_generated/dataModel'
 import type { ActionCtx } from '../_generated/server'
+import { extractResponseText } from './openaiResponse'

 const CHANGELOG_MODEL = process.env.OPENAI_CHANGELOG_MODEL ?? 'gpt-4.1'
 const MAX_README_CHARS = 8_000
@@ -59,27 +60,6 @@ function pickPaths(values: string[]) {
  return values.slice(0, MAX_PATHS_IN_PROMPT)
 }

-function extractResponseText(payload: unknown) {
-  if (!payload || typeof payload !== 'object') return null
-  const output = (payload as { output?: unknown }).output
-  if (!Array.isArray(output)) return null
-  const chunks: string[] = []
-  for (const item of output) {
-    if (!item || typeof item !== 'object') continue
-    if ((item as { type?: unknown }).type !== 'message') continue
-    const content = (item as { content?: unknown }).content
-    if (!Array.isArray(content)) continue
-    for (const part of content) {
-      if (!part || typeof part !== 'object') continue
-      if ((part as { type?: unknown }).type !== 'output_text') continue
-      const text = (part as { text?: unknown }).text
-      if (typeof text === 'string' && text.trim()) chunks.push(text)
-    }
-  }
-  const joined = chunks.join('\n').trim()
-  return joined || null
-}
-
 async function generateWithOpenAI(args: {
  slug: string
  version: string
@@ -10,6 +10,7 @@ import {
  getFrontmatterMetadata,
  getFrontmatterValue,
  hashSkillFiles,
+  isMacJunkPath,
  isTextFile,
  parseFrontmatter,
  sanitizePath,
@@ -100,22 +101,23 @@ export async function publishSoulVersionForUser(
  const sanitizedFiles = args.files.map((file) => {
    const path = sanitizePath(file.path)
    if (!path) throw new ConvexError('Invalid file paths')
-    if (!isTextFile(path, file.contentType ?? undefined)) {
-      throw new ConvexError('Only text-based files are allowed')
-    }
    return { ...file, path }
  })
+  const publishFiles = sanitizedFiles.filter((file) => !isMacJunkPath(file.path))
+  if (publishFiles.some((file) => !isTextFile(file.path, file.contentType ?? undefined))) {
+    throw new ConvexError('Only text-based files are allowed')
+  }

-  const totalBytes = sanitizedFiles.reduce((sum, file) => sum + file.size, 0)
+  const totalBytes = publishFiles.reduce((sum, file) => sum + file.size, 0)
  if (totalBytes > MAX_TOTAL_BYTES) {
    throw new ConvexError('Soul bundle exceeds 50MB limit')
  }

  const isSoulFile = (path: string) => path.toLowerCase() === 'soul.md'
-  const readmeFile = sanitizedFiles.find((file) => isSoulFile(file.path))
+  const readmeFile = publishFiles.find((file) => isSoulFile(file.path))
  if (!readmeFile) throw new ConvexError('SOUL.md is required')

-  const nonSoulFiles = sanitizedFiles.filter((file) => !isSoulFile(file.path))
+  const nonSoulFiles = publishFiles.filter((file) => !isSoulFile(file.path))
  if (nonSoulFiles.length > 0) {
    throw new ConvexError('Only SOUL.md is allowed for soul bundles')
  }
@@ -132,8 +134,8 @@ export async function publishSoulVersionForUser(
  })

  const fingerprint = await hashSkillFiles(
-    sanitizedFiles.map((file) => ({
-      path: file.path ?? '',
+    publishFiles.map((file) => ({
+      path: file.path,
      sha256: file.sha256,
    })),
  )
@@ -145,7 +147,7 @@ export async function publishSoulVersionForUser(
          slug,
          version,
          readmeText,
-          files: sanitizedFiles.map((file) => ({ path: file.path ?? '', sha256: file.sha256 })),
+          files: publishFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
        })

  const embeddingPromise = generateEmbedding(embeddingText)
@@ -166,7 +168,7 @@ export async function publishSoulVersionForUser(
    changelogSource,
    tags: args.tags?.map((tag) => tag.trim()).filter(Boolean),
    fingerprint,
-    files: sanitizedFiles,
+    files: publishFiles,
    parsed: {
      frontmatter,
      metadata,
@@ -186,7 +188,7 @@ export async function publishSoulVersionForUser(
      version,
      displayName,
      ownerHandle,
-      files: sanitizedFiles,
+      files: publishFiles,
      publishedAt: Date.now(),
    })
    .catch((error) => {
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import { buildUserSearchResults } from './userSearch'
+
+function makeUser(overrides: Record<string, unknown> = {}) {
+  return {
+    _id: 'users:1',
+    _creationTime: 1,
+    handle: 'alice',
+    name: 'alice-gh',
+    displayName: 'Alice',
+    email: 'alice@example.com',
+    ...overrides,
+  } as never
+}
+
+describe('buildUserSearchResults', () => {
+  it('returns all users when query is empty', () => {
+    const users = [makeUser({ _id: 'users:1' }), makeUser({ _id: 'users:2', handle: 'bob' })]
+    const result = buildUserSearchResults(users)
+    expect(result.total).toBe(2)
+    expect(result.items).toHaveLength(2)
+  })
+
+  it('matches compact handle/search variants', () => {
+    const users = [makeUser({ handle: 'alice-dev' }), makeUser({ _id: 'users:2', handle: 'bob' })]
+    const result = buildUserSearchResults(users, 'alicedev')
+    expect(result.total).toBe(1)
+    expect(result.items[0]?.handle).toBe('alice-dev')
+  })
+
+  it('does not throw on malformed legacy field types', () => {
+    const users = [
+      makeUser({
+        _id: 'users:legacy',
+        handle: 42,
+        name: { bad: true },
+        displayName: null,
+        email: ['legacy@example.com'],
+      }),
+      makeUser({ _id: 'users:2', handle: 'carol' }),
+    ]
+
+    expect(() => buildUserSearchResults(users, 'car')).not.toThrow()
+    const result = buildUserSearchResults(users, 'car')
+    expect(result.total).toBe(1)
+    expect(result.items[0]?._id).toBe('users:2')
+  })
+
+  it('ranks exact id match above fuzzy matches', () => {
+    const users = [
+      makeUser({ _id: 'users:target', handle: 'target-user', _creationTime: 1 }),
+      makeUser({ _id: 'users:2', handle: 'users:target', _creationTime: 10 }),
+    ]
+
+    const result = buildUserSearchResults(users, 'users:target')
+    expect(result.total).toBe(2)
+    expect(result.items[0]?._id).toBe('users:target')
+  })
+
+  it('uses creation time as tie-break when scores are equal', () => {
+    const users = [
+      makeUser({ _id: 'users:older', handle: 'alpha', _creationTime: 1 }),
+      makeUser({ _id: 'users:newer', handle: 'alpha-two', _creationTime: 50 }),
+    ]
+
+    const result = buildUserSearchResults(users, 'pha')
+    expect(result.total).toBe(2)
+    expect(result.items[0]?._id).toBe('users:newer')
+    expect(result.items[1]?._id).toBe('users:older')
+  })
+})
@@ -14,11 +14,15 @@ function normalizeCompact(value: string) {
  return value.toLowerCase().replace(/[^a-z0-9]/g, '')
 }

+function toSearchText(value: unknown) {
+  return typeof value === 'string' ? value.toLowerCase() : ''
+}
+
 function scoreUser(user: Doc<'users'>, query: string, compactQuery: string) {
-  const handle = user.handle?.toLowerCase() ?? ''
-  const name = user.name?.toLowerCase() ?? ''
-  const displayName = user.displayName?.toLowerCase() ?? ''
-  const email = user.email?.toLowerCase() ?? ''
+  const handle = toSearchText(user.handle)
+  const name = toSearchText(user.name)
+  const displayName = toSearchText(user.displayName)
+  const email = toSearchText(user.email)
  const id = String(user._id).toLowerCase()

  let score = 0
@@ -2,6 +2,13 @@ import { v } from 'convex/values'
 import { internal } from './_generated/api'
 import type { Doc, Id } from './_generated/dataModel'
 import { internalAction } from './_generated/server'
+import {
+  assembleCommentScamEvalUserMessage,
+  COMMENT_SCAM_EVALUATOR_SYSTEM_PROMPT,
+  COMMENT_SCAM_EVAL_MAX_OUTPUT_TOKENS,
+  getCommentScamEvalModel,
+  parseCommentScamEvalResponse,
+} from './lib/commentScamPrompt'
 import type { SkillEvalContext } from './lib/securityPrompt'
 import {
  assembleEvalUserMessage,
@@ -11,32 +18,12 @@ import {
  parseLlmEvalResponse,
  SECURITY_EVALUATOR_SYSTEM_PROMPT,
 } from './lib/securityPrompt'
+import { extractResponseText } from './lib/openaiResponse'

 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

-function extractResponseText(payload: unknown): string | null {
-  if (!payload || typeof payload !== 'object') return null
-  const output = (payload as { output?: unknown }).output
-  if (!Array.isArray(output)) return null
-  const chunks: string[] = []
-  for (const item of output) {
-    if (!item || typeof item !== 'object') continue
-    if ((item as { type?: unknown }).type !== 'message') continue
-    const content = (item as { content?: unknown }).content
-    if (!Array.isArray(content)) continue
-    for (const part of content) {
-      if (!part || typeof part !== 'object') continue
-      if ((part as { type?: unknown }).type !== 'output_text') continue
-      const text = (part as { text?: unknown }).text
-      if (typeof text === 'string' && text.trim()) chunks.push(text)
-    }
-  }
-  const joined = chunks.join('\n').trim()
-  return joined || null
-}
-
 function verdictToStatus(verdict: string): string {
  switch (verdict) {
    case 'benign':
@@ -142,6 +129,8 @@ export const evaluateWithLlm = internalAction({
    // 6. Build eval context
    const parsed = version.parsed as SkillEvalContext['parsed']
    const fm = parsed.frontmatter ?? {}
+    const clawdisRecord = (parsed.clawdis ?? {}) as Record<string, unknown>
+    const clawdisLinks = (clawdisRecord.links ?? {}) as Record<string, unknown>

    const evalCtx: SkillEvalContext = {
      slug: skill.slug,
@@ -151,7 +140,11 @@ export const evaluateWithLlm = internalAction({
      createdAt: version.createdAt,
      summary: (skill.summary as string | undefined) ?? undefined,
      source: (fm.source as string | undefined) ?? undefined,
-      homepage: (fm.homepage as string | undefined) ?? undefined,
+      homepage:
+        (fm.homepage as string | undefined) ??
+        (clawdisRecord.homepage as string | undefined) ??
+        (clawdisLinks.homepage as string | undefined) ??
+        undefined,
      parsed,
      files: version.files.map((f) => ({ path: f.path, size: f.size })),
      skillMdContent,
@@ -251,23 +244,8 @@ export const evaluateWithLlm = internalAction({
      `[llmEval] Evaluated ${skill.slug}@${version.version}: ${result.verdict} (${result.confidence} confidence)`,
    )

-    // 10. Update moderation flags — re-read version to get the sha256hash
-    // that VT may have stored while we were evaluating (both run concurrently).
-    const freshVersion = (await ctx.runQuery(internal.skills.getVersionByIdInternal, {
-      versionId: args.versionId,
-    })) as Doc<'skillVersions'> | null
-
-    const sha256hash = freshVersion?.sha256hash ?? version.sha256hash
-    if (sha256hash) {
-      const status = verdictToStatus(result.verdict)
-      if (status === 'malicious' || status === 'suspicious' || status === 'clean') {
-        await ctx.runMutation(internal.skills.approveSkillByHashInternal, {
-          sha256hash,
-          scanner: 'llm',
-          status,
-        })
-      }
-    }
+    // Moderation visibility is finalized by VT results.
+    // LLM eval only stores analysis payload on the version.
  },
 })

@@ -396,3 +374,87 @@ export const backfillLlmEval = internalAction({
    return result
  },
 })
+
+export const evaluateCommentForScam = internalAction({
+  args: {
+    commentId: v.id('comments'),
+    skillId: v.id('skills'),
+    userId: v.id('users'),
+    body: v.string(),
+  },
+  handler: async (_ctx, args) => {
+    const apiKey = process.env.OPENAI_API_KEY
+    if (!apiKey) {
+      return { ok: false as const, error: 'OPENAI_API_KEY not configured' }
+    }
+
+    const model = getCommentScamEvalModel()
+    const input = assembleCommentScamEvalUserMessage({
+      commentId: String(args.commentId),
+      skillId: String(args.skillId),
+      userId: String(args.userId),
+      body: args.body,
+    })
+
+    const requestBody = JSON.stringify({
+      model,
+      instructions: COMMENT_SCAM_EVALUATOR_SYSTEM_PROMPT,
+      input,
+      max_output_tokens: COMMENT_SCAM_EVAL_MAX_OUTPUT_TOKENS,
+      text: {
+        format: {
+          type: 'json_object',
+        },
+      },
+    })
+
+    const MAX_RETRIES = 3
+    let response: Response | null = null
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      response = await fetch('https://api.openai.com/v1/responses', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: requestBody,
+      })
+
+      if ((response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+        const delay = 2 ** attempt * 2000 + Math.random() * 1000
+        await new Promise((resolve) => setTimeout(resolve, delay))
+        continue
+      }
+      break
+    }
+
+    if (!response || !response.ok) {
+      const errorText = response ? await response.text() : 'No response'
+      return {
+        ok: false as const,
+        error: `OpenAI API error (${response?.status}): ${errorText.slice(0, 200)}`,
+      }
+    }
+
+    const payload = (await response.json()) as unknown
+    const raw = extractResponseText(payload)
+    if (!raw) {
+      return { ok: false as const, error: 'Empty response from OpenAI' }
+    }
+
+    const parsed = parseCommentScamEvalResponse(raw)
+    if (!parsed) {
+      console.error(`[commentScam] Parse failure for ${args.commentId}: ${raw.slice(0, 400)}`)
+      return { ok: false as const, error: 'Failed to parse scam evaluation response' }
+    }
+
+    return {
+      ok: true as const,
+      model,
+      verdict: parsed.verdict,
+      confidence: parsed.confidence,
+      explanation: parsed.explanation,
+      evidence: parsed.evidence,
+    }
+  },
+})
@@ -12,12 +12,35 @@ vi.mock('./_generated/api', () => ({
        'applySkillFingerprintBackfillPatchInternal',
      ),
      backfillSkillFingerprintsInternal: Symbol('backfillSkillFingerprintsInternal'),
+      getEmptySkillCleanupPageInternal: Symbol('getEmptySkillCleanupPageInternal'),
+      applyEmptySkillCleanupInternal: Symbol('applyEmptySkillCleanupInternal'),
+      nominateUserForEmptySkillSpamInternal: Symbol('nominateUserForEmptySkillSpamInternal'),
+      cleanupEmptySkillsInternal: Symbol('cleanupEmptySkillsInternal'),
+      nominateEmptySkillSpammersInternal: Symbol('nominateEmptySkillSpammersInternal'),
+    },
+    skills: {
+      getVersionByIdInternal: Symbol('skills.getVersionByIdInternal'),
+      getOwnerSkillActivityInternal: Symbol('skills.getOwnerSkillActivityInternal'),
+    },
+    users: {
+      getByIdInternal: Symbol('users.getByIdInternal'),
    },
  },
 }))

-const { backfillSkillFingerprintsInternalHandler, backfillSkillSummariesInternalHandler } =
-  await import('./maintenance')
+vi.mock('./lib/skillSummary', () => ({
+  generateSkillSummary: vi.fn(),
+}))
+
+const {
+  backfillSkillFingerprintsInternalHandler,
+  backfillSkillSummariesInternalHandler,
+  cleanupEmptySkillsInternalHandler,
+  nominateEmptySkillSpammersInternalHandler,
+  upsertSkillBadgeRecordInternal,
+} = await import('./maintenance')
+const { internal } = await import('./_generated/api')
+const { generateSkillSummary } = await import('./lib/skillSummary')

 function makeBlob(text: string) {
  return { text: () => Promise.resolve(text) } as unknown as Blob
@@ -30,6 +53,8 @@ describe('maintenance backfill', () => {
        {
          kind: 'ok',
          skillId: 'skills:1',
+          skillSlug: 'skill-1',
+          skillDisplayName: 'Skill 1',
          versionId: 'skillVersions:1',
          skillSummary: '>',
          versionParsed: { frontmatter: { description: '>' } },
@@ -73,6 +98,8 @@ describe('maintenance backfill', () => {
        {
          kind: 'ok',
          skillId: 'skills:1',
+          skillSlug: 'skill-1',
+          skillDisplayName: 'Skill 1',
          versionId: 'skillVersions:1',
          skillSummary: '>',
          versionParsed: { frontmatter: { description: '>' } },
@@ -102,6 +129,8 @@ describe('maintenance backfill', () => {
        {
          kind: 'ok',
          skillId: 'skills:1',
+          skillSlug: 'skill-1',
+          skillDisplayName: 'Skill 1',
          versionId: 'skillVersions:1',
          skillSummary: null,
          versionParsed: { frontmatter: {} },
@@ -123,6 +152,128 @@ describe('maintenance backfill', () => {
    expect(result.stats.missingStorageBlob).toBe(1)
    expect(runMutation).not.toHaveBeenCalled()
  })
+
+  it('fills empty summary via AI when useAi is enabled', async () => {
+    vi.mocked(generateSkillSummary).mockResolvedValue('AI generated summary.')
+
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          kind: 'ok',
+          skillId: 'skills:1',
+          skillSlug: 'ai-skill',
+          skillDisplayName: 'AI Skill',
+          versionId: 'skillVersions:1',
+          skillSummary: null,
+          versionParsed: { frontmatter: {} },
+          readmeStorageId: 'storage:1',
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    })
+
+    const runMutation = vi.fn().mockResolvedValue({ ok: true })
+    const storageGet = vi.fn().mockResolvedValue(makeBlob('# AI Skill\n\nUseful automation.'))
+
+    const result = await backfillSkillSummariesInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1, useAi: true },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.stats.skillsPatched).toBe(1)
+    expect(result.stats.aiSummariesPatched).toBe(1)
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      skillId: 'skills:1',
+      versionId: 'skillVersions:1',
+      summary: 'AI generated summary.',
+      parsed: {
+        frontmatter: {},
+        metadata: undefined,
+        clawdis: undefined,
+      },
+    })
+  })
+})
+
+describe('maintenance badge denormalization', () => {
+  it('upserts table badge and keeps skill.badges in sync', async () => {
+    const unique = vi.fn().mockResolvedValue(null)
+    const query = vi.fn().mockReturnValue({
+      withIndex: () => ({ unique }),
+    })
+    const insert = vi.fn().mockResolvedValue('skillBadges:1')
+    const get = vi.fn().mockResolvedValue({ _id: 'skills:1', badges: undefined })
+    const patch = vi.fn().mockResolvedValue(undefined)
+
+    const ctx = {
+      db: {
+        query,
+        insert,
+        get,
+        patch,
+      },
+    } as never
+
+    const result = await (
+      upsertSkillBadgeRecordInternal as unknown as { _handler: Function }
+    )._handler(ctx, {
+      skillId: 'skills:1',
+      kind: 'highlighted',
+      byUserId: 'users:1',
+      at: 123,
+    })
+
+    expect(result).toEqual({ inserted: true })
+    expect(insert).toHaveBeenCalledWith('skillBadges', {
+      skillId: 'skills:1',
+      kind: 'highlighted',
+      byUserId: 'users:1',
+      at: 123,
+    })
+    expect(patch).toHaveBeenCalledWith('skills:1', {
+      badges: {
+        highlighted: { byUserId: 'users:1', at: 123 },
+      },
+    })
+  })
+
+  it('resyncs denormalized badge even when table record already exists', async () => {
+    const unique = vi.fn().mockResolvedValue({ _id: 'skillBadges:existing' })
+    const query = vi.fn().mockReturnValue({
+      withIndex: () => ({ unique }),
+    })
+    const insert = vi.fn()
+    const get = vi.fn().mockResolvedValue({ _id: 'skills:1', badges: {} })
+    const patch = vi.fn().mockResolvedValue(undefined)
+
+    const ctx = {
+      db: {
+        query,
+        insert,
+        get,
+        patch,
+      },
+    } as never
+
+    const result = await (
+      upsertSkillBadgeRecordInternal as unknown as { _handler: Function }
+    )._handler(ctx, {
+      skillId: 'skills:1',
+      kind: 'official',
+      byUserId: 'users:2',
+      at: 456,
+    })
+
+    expect(result).toEqual({ inserted: false })
+    expect(insert).not.toHaveBeenCalled()
+    expect(patch).toHaveBeenCalledWith('skills:1', {
+      badges: {
+        official: { byUserId: 'users:2', at: 456 },
+      },
+    })
+  })
 })

 describe('maintenance fingerprint backfill', () => {
@@ -268,3 +419,212 @@ describe('maintenance fingerprint backfill', () => {
    })
  })
 })
+
+describe('maintenance empty skill cleanup', () => {
+  it('dryRun detects empty skills and returns nominations', async () => {
+    const runQuery = vi.fn().mockImplementation(async (endpoint: unknown) => {
+      if (endpoint === internal.maintenance.getEmptySkillCleanupPageInternal) {
+        return {
+          items: [
+            {
+              skillId: 'skills:1',
+              slug: 'spam-skill',
+              ownerUserId: 'users:1',
+              latestVersionId: 'skillVersions:1',
+              softDeletedAt: undefined,
+              summary: 'Expert guidance for spam-skill.',
+            },
+          ],
+          cursor: null,
+          isDone: true,
+        }
+      }
+      if (endpoint === internal.skills.getVersionByIdInternal) {
+        return {
+          _id: 'skillVersions:1',
+          files: [{ path: 'SKILL.md', size: 120, storageId: 'storage:1' }],
+        }
+      }
+      if (endpoint === internal.users.getByIdInternal) {
+        return { _id: 'users:1', handle: 'spammer', _creationTime: Date.now() }
+      }
+      if (endpoint === internal.skills.getOwnerSkillActivityInternal) {
+        return []
+      }
+      throw new Error(`Unexpected endpoint: ${String(endpoint)}`)
+    })
+
+    const runMutation = vi.fn()
+    const storageGet = vi
+      .fn()
+      .mockResolvedValue(
+        makeBlob(`# Demo\n- Step-by-step tutorials\n- Tips and techniques\n- Project ideas`),
+      )
+
+    const result = await cleanupEmptySkillsInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: true, batchSize: 10, maxBatches: 1, nominationThreshold: 1 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.isDone).toBe(true)
+    expect(result.cursor).toBeNull()
+    expect(result.stats.emptyDetected).toBe(1)
+    expect(result.stats.skillsDeleted).toBe(0)
+    expect(result.nominations).toEqual([
+      {
+        userId: 'users:1',
+        handle: 'spammer',
+        emptySkillCount: 1,
+        sampleSlugs: ['spam-skill'],
+      },
+    ])
+    expect(runMutation).not.toHaveBeenCalled()
+  })
+
+  it('apply mode deletes empty skills', async () => {
+    const runQuery = vi.fn().mockImplementation(async (endpoint: unknown) => {
+      if (endpoint === internal.maintenance.getEmptySkillCleanupPageInternal) {
+        return {
+          items: [
+            {
+              skillId: 'skills:1',
+              slug: 'spam-a',
+              ownerUserId: 'users:1',
+              latestVersionId: 'skillVersions:1',
+              summary: 'Expert guidance for spam-a.',
+            },
+            {
+              skillId: 'skills:2',
+              slug: 'spam-b',
+              ownerUserId: 'users:1',
+              latestVersionId: 'skillVersions:2',
+              summary: 'Expert guidance for spam-b.',
+            },
+          ],
+          cursor: null,
+          isDone: true,
+        }
+      }
+      if (endpoint === internal.skills.getVersionByIdInternal) {
+        return {
+          files: [{ path: 'SKILL.md', size: 120, storageId: 'storage:1' }],
+        }
+      }
+      if (endpoint === internal.users.getByIdInternal) {
+        return { _id: 'users:1', handle: 'spammer', _creationTime: Date.now() }
+      }
+      if (endpoint === internal.skills.getOwnerSkillActivityInternal) {
+        return []
+      }
+      throw new Error(`Unexpected endpoint: ${String(endpoint)}`)
+    })
+
+    const runMutation = vi.fn().mockImplementation(async (endpoint: unknown) => {
+      if (endpoint === internal.maintenance.applyEmptySkillCleanupInternal) {
+        return { deleted: true }
+      }
+      throw new Error(`Unexpected mutation endpoint: ${String(endpoint)}`)
+    })
+
+    const storageGet = vi
+      .fn()
+      .mockResolvedValue(
+        makeBlob(`# Demo\n- Step-by-step tutorials\n- Tips and techniques\n- Project ideas`),
+      )
+
+    const result = await cleanupEmptySkillsInternalHandler(
+      { runQuery, runMutation, storage: { get: storageGet } } as never,
+      { dryRun: false, batchSize: 10, maxBatches: 1, nominationThreshold: 2 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.isDone).toBe(true)
+    expect(result.cursor).toBeNull()
+    expect(result.stats.emptyDetected).toBe(2)
+    expect(result.stats.skillsDeleted).toBe(2)
+    expect(result.nominations).toEqual([
+      {
+        userId: 'users:1',
+        handle: 'spammer',
+        emptySkillCount: 2,
+        sampleSlugs: ['spam-a', 'spam-b'],
+      },
+    ])
+  })
+})
+
+describe('maintenance empty skill nominations', () => {
+  it('creates ban nominations from backfilled empty deletions', async () => {
+    const runQuery = vi.fn().mockImplementation(async (endpoint: unknown, args: unknown) => {
+      if (endpoint === internal.maintenance.getEmptySkillCleanupPageInternal) {
+        const cursor = (args as { cursor?: string | undefined }).cursor
+        if (!cursor) {
+          return {
+            items: [
+              {
+                skillId: 'skills:1',
+                slug: 'spam-a',
+                ownerUserId: 'users:1',
+                softDeletedAt: 1,
+                moderationReason: 'quality.empty.backfill',
+              },
+              {
+                skillId: 'skills:2',
+                slug: 'spam-b',
+                ownerUserId: 'users:1',
+                softDeletedAt: 1,
+                moderationReason: 'quality.empty.backfill',
+              },
+            ],
+            cursor: 'next',
+            isDone: false,
+          }
+        }
+        return {
+          items: [
+            {
+              skillId: 'skills:3',
+              slug: 'valid-hidden',
+              ownerUserId: 'users:2',
+              softDeletedAt: 1,
+              moderationReason: 'scanner.vt.suspicious',
+            },
+          ],
+          cursor: null,
+          isDone: true,
+        }
+      }
+      if (endpoint === internal.users.getByIdInternal) {
+        return { _id: 'users:1', handle: 'spammer' }
+      }
+      throw new Error(`Unexpected query endpoint: ${String(endpoint)}`)
+    })
+
+    const runMutation = vi.fn().mockImplementation(async (endpoint: unknown) => {
+      if (endpoint === internal.maintenance.nominateUserForEmptySkillSpamInternal) {
+        return { created: true }
+      }
+      throw new Error(`Unexpected mutation endpoint: ${String(endpoint)}`)
+    })
+
+    const result = await nominateEmptySkillSpammersInternalHandler(
+      { runQuery, runMutation } as never,
+      { batchSize: 10, maxBatches: 2, nominationThreshold: 2 },
+    )
+
+    expect(result.ok).toBe(true)
+    expect(result.isDone).toBe(true)
+    expect(result.stats.usersFlagged).toBe(1)
+    expect(result.stats.nominationsCreated).toBe(1)
+    expect(result.stats.nominationsExisting).toBe(0)
+    expect(result.nominations).toEqual([
+      {
+        userId: 'users:1',
+        handle: 'spammer',
+        emptySkillCount: 2,
+        sampleSlugs: ['spam-a', 'spam-b'],
+      },
+    ])
+  })
+})
@@ -5,16 +5,26 @@ import type { ActionCtx } from './_generated/server'
 import { action, internalAction, internalMutation, internalQuery } from './_generated/server'
 import { assertRole, requireUserFromAction } from './lib/access'
 import { buildSkillSummaryBackfillPatch, type ParsedSkillData } from './lib/skillBackfill'
+import {
+  computeQualitySignals,
+  evaluateQuality,
+  getTrustTier,
+  type TrustTier,
+} from './lib/skillQuality'
+import { generateSkillSummary } from './lib/skillSummary'
 import { hashSkillFiles } from './lib/skills'

 const DEFAULT_BATCH_SIZE = 50
 const MAX_BATCH_SIZE = 200
 const DEFAULT_MAX_BATCHES = 20
 const MAX_MAX_BATCHES = 200
+const DEFAULT_EMPTY_SKILL_MAX_README_BYTES = 8000
+const DEFAULT_EMPTY_SKILL_NOMINATION_THRESHOLD = 3

 type BackfillStats = {
  skillsScanned: number
  skillsPatched: number
+  aiSummariesPatched: number
  versionsPatched: number
  missingLatestVersion: number
  missingReadme: number
@@ -25,6 +35,8 @@ type BackfillPageItem =
  | {
      kind: 'ok'
      skillId: Id<'skills'>
+      skillSlug: string
+      skillDisplayName: string
      versionId: Id<'skillVersions'>
      skillSummary: Doc<'skills'>['summary']
      versionParsed: Doc<'skillVersions'>['parsed']
@@ -80,6 +92,8 @@ export const getSkillBackfillPageInternal = internalQuery({
      items.push({
        kind: 'ok',
        skillId: skill._id,
+        skillSlug: skill.slug,
+        skillDisplayName: skill.displayName,
        versionId: version._id,
        skillSummary: skill.summary,
        versionParsed: version.parsed,
@@ -120,28 +134,37 @@ export type BackfillActionArgs = {
  dryRun?: boolean
  batchSize?: number
  maxBatches?: number
+  useAi?: boolean
+  cursor?: string
 }

-export type BackfillActionResult = { ok: true; stats: BackfillStats }
+export type BackfillActionResult = {
+  ok: true
+  stats: BackfillStats
+  isDone: boolean
+  cursor: string | null
+}

 export async function backfillSkillSummariesInternalHandler(
  ctx: ActionCtx,
  args: BackfillActionArgs,
 ): Promise<BackfillActionResult> {
  const dryRun = Boolean(args.dryRun)
+  const useAi = Boolean(args.useAi)
  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)

  const totals: BackfillStats = {
    skillsScanned: 0,
    skillsPatched: 0,
+    aiSummariesPatched: 0,
    versionsPatched: 0,
    missingLatestVersion: 0,
    missingReadme: 0,
    missingStorageBlob: 0,
  }

-  let cursor: string | null = null
+  let cursor: string | null = args.cursor ?? null
  let isDone = false

  for (let i = 0; i < maxBatches; i++) {
@@ -181,8 +204,24 @@ export async function backfillSkillSummariesInternalHandler(
        currentParsed: item.versionParsed as ParsedSkillData,
      })

-      if (!patch.summary && !patch.parsed) continue
-      if (patch.summary) totals.skillsPatched++
+      let nextSummary = patch.summary
+      const missingSummary = !item.skillSummary?.trim()
+      if (!nextSummary && useAi && missingSummary) {
+        nextSummary = await generateSkillSummary({
+          slug: item.skillSlug,
+          displayName: item.skillDisplayName,
+          readmeText,
+        })
+      }
+
+      const shouldPatchSummary =
+        typeof nextSummary === 'string' && nextSummary.trim() && nextSummary !== item.skillSummary
+
+      if (!shouldPatchSummary && !patch.parsed) continue
+      if (shouldPatchSummary) {
+        totals.skillsPatched++
+        if (!patch.summary) totals.aiSummariesPatched++
+      }
      if (patch.parsed) totals.versionsPatched++

      if (dryRun) continue
@@ -190,7 +229,7 @@ export async function backfillSkillSummariesInternalHandler(
      await ctx.runMutation(internal.maintenance.applySkillBackfillPatchInternal, {
        skillId: item.skillId,
        versionId: item.versionId,
-        summary: patch.summary,
+        summary: shouldPatchSummary ? nextSummary : undefined,
        parsed: patch.parsed,
      })
    }
@@ -198,11 +237,7 @@ export async function backfillSkillSummariesInternalHandler(
    if (isDone) break
  }

-  if (!isDone) {
-    throw new ConvexError('Backfill incomplete (maxBatches reached)')
-  }
-
-  return { ok: true as const, stats: totals }
+  return { ok: true as const, stats: totals, isDone, cursor }
 }

 export const backfillSkillSummariesInternal = internalAction({
@@ -210,6 +245,8 @@ export const backfillSkillSummariesInternal = internalAction({
    dryRun: v.optional(v.boolean()),
    batchSize: v.optional(v.number()),
    maxBatches: v.optional(v.number()),
+    useAi: v.optional(v.boolean()),
+    cursor: v.optional(v.string()),
  },
  handler: backfillSkillSummariesInternalHandler,
 })
@@ -219,6 +256,8 @@ export const backfillSkillSummaries: ReturnType<typeof action> = action({
    dryRun: v.optional(v.boolean()),
    batchSize: v.optional(v.number()),
    maxBatches: v.optional(v.number()),
+    useAi: v.optional(v.boolean()),
+    cursor: v.optional(v.string()),
  },
  handler: async (ctx, args): Promise<BackfillActionResult> => {
    const { user } = await requireUserFromAction(ctx)
@@ -231,7 +270,7 @@ export const backfillSkillSummaries: ReturnType<typeof action> = action({
 })

 export const scheduleBackfillSkillSummaries: ReturnType<typeof action> = action({
-  args: { dryRun: v.optional(v.boolean()) },
+  args: { dryRun: v.optional(v.boolean()), useAi: v.optional(v.boolean()) },
  handler: async (ctx, args) => {
    const { user } = await requireUserFromAction(ctx)
    assertRole(user, ['admin'])
@@ -239,11 +278,43 @@ export const scheduleBackfillSkillSummaries: ReturnType<typeof action> = action(
      dryRun: Boolean(args.dryRun),
      batchSize: DEFAULT_BATCH_SIZE,
      maxBatches: DEFAULT_MAX_BATCHES,
+      useAi: Boolean(args.useAi),
    })
    return { ok: true as const }
  },
 })

+export const continueSkillSummaryBackfillJobInternal = internalAction({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+    useAi: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<BackfillActionResult> => {
+    const result = await backfillSkillSummariesInternalHandler(ctx, {
+      dryRun: false,
+      cursor: args.cursor,
+      batchSize: args.batchSize ?? DEFAULT_BATCH_SIZE,
+      maxBatches: 1,
+      useAi: Boolean(args.useAi),
+    })
+
+    if (!result.isDone && result.cursor) {
+      await ctx.scheduler.runAfter(
+        0,
+        internal.maintenance.continueSkillSummaryBackfillJobInternal,
+        {
+          cursor: result.cursor,
+          batchSize: args.batchSize ?? DEFAULT_BATCH_SIZE,
+          useAi: Boolean(args.useAi),
+        },
+      )
+    }
+
+    return result
+  },
+})
+
 type FingerprintBackfillStats = {
  versionsScanned: number
  versionsPatched: number
@@ -571,17 +642,32 @@ export const upsertSkillBadgeRecordInternal = internalMutation({
    at: v.number(),
  },
  handler: async (ctx, args) => {
+    const syncDenormalizedBadge = async () => {
+      const skill = await ctx.db.get(args.skillId)
+      if (!skill) return
+      await ctx.db.patch(args.skillId, {
+        badges: {
+          ...(skill.badges as Record<string, unknown> | undefined),
+          [args.kind]: { byUserId: args.byUserId, at: args.at },
+        },
+      })
+    }
+
    const existing = await ctx.db
      .query('skillBadges')
      .withIndex('by_skill_kind', (q) => q.eq('skillId', args.skillId).eq('kind', args.kind))
      .unique()
-    if (existing) return { inserted: false as const }
+    if (existing) {
+      await syncDenormalizedBadge()
+      return { inserted: false as const }
+    }
    await ctx.db.insert('skillBadges', {
      skillId: args.skillId,
      kind: args.kind,
      byUserId: args.byUserId,
      at: args.at,
    })
+    await syncDenormalizedBadge()
    return { inserted: true as const }
  },
 })
@@ -833,6 +919,616 @@ export const scheduleBackfillSkillBadgeTable: ReturnType<typeof action> = action
  },
 })

+type EmptySkillCleanupPageItem = {
+  skillId: Id<'skills'>
+  slug: string
+  ownerUserId: Id<'users'>
+  latestVersionId?: Id<'skillVersions'>
+  softDeletedAt?: number
+  moderationReason?: string
+  summary?: string
+}
+
+type EmptySkillCleanupPageResult = {
+  items: EmptySkillCleanupPageItem[]
+  cursor: string | null
+  isDone: boolean
+}
+
+type EmptySkillCleanupStats = {
+  skillsScanned: number
+  skillsEvaluated: number
+  emptyDetected: number
+  skillsDeleted: number
+  missingLatestVersion: number
+  missingVersionDoc: number
+  missingReadme: number
+  missingStorageBlob: number
+  skippedLargeReadme: number
+}
+
+type EmptySkillCleanupNomination = {
+  userId: Id<'users'>
+  handle: string | null
+  emptySkillCount: number
+  sampleSlugs: string[]
+}
+
+export type EmptySkillCleanupActionArgs = {
+  cursor?: string
+  dryRun?: boolean
+  batchSize?: number
+  maxBatches?: number
+  maxReadmeBytes?: number
+  nominationThreshold?: number
+}
+
+export type EmptySkillCleanupActionResult = {
+  ok: true
+  cursor: string | null
+  isDone: boolean
+  stats: EmptySkillCleanupStats
+  nominations: EmptySkillCleanupNomination[]
+}
+
+export const getEmptySkillCleanupPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<EmptySkillCleanupPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+    const { page, isDone, continueCursor } = await ctx.db
+      .query('skills')
+      .order('asc')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    return {
+      items: page.map((skill) => ({
+        skillId: skill._id,
+        slug: skill.slug,
+        ownerUserId: skill.ownerUserId,
+        latestVersionId: skill.latestVersionId,
+        softDeletedAt: skill.softDeletedAt,
+        moderationReason: skill.moderationReason,
+        summary: skill.summary,
+      })),
+      cursor: continueCursor,
+      isDone,
+    }
+  },
+})
+
+export const applyEmptySkillCleanupInternal = internalMutation({
+  args: {
+    skillId: v.id('skills'),
+    reason: v.string(),
+    quality: v.object({
+      score: v.number(),
+      trustTier: v.union(v.literal('low'), v.literal('medium'), v.literal('trusted')),
+      signals: v.object({
+        bodyChars: v.number(),
+        bodyWords: v.number(),
+        uniqueWordRatio: v.number(),
+        headingCount: v.number(),
+        bulletCount: v.number(),
+        templateMarkerHits: v.number(),
+        genericSummary: v.boolean(),
+        cjkChars: v.optional(v.number()),
+      }),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const skill = await ctx.db.get(args.skillId)
+    if (!skill) return { deleted: false as const, reason: 'missing_skill' as const }
+    if (skill.softDeletedAt) return { deleted: false as const, reason: 'already_deleted' as const }
+
+    const now = Date.now()
+    await ctx.db.patch(skill._id, {
+      softDeletedAt: now,
+      moderationStatus: 'hidden',
+      moderationReason: 'quality.empty.backfill',
+      moderationNotes: args.reason,
+      quality: {
+        score: args.quality.score,
+        decision: 'reject',
+        trustTier: args.quality.trustTier,
+        similarRecentCount: 0,
+        reason: args.reason,
+        signals: args.quality.signals,
+        evaluatedAt: now,
+      },
+      updatedAt: now,
+    })
+
+    await ctx.db.insert('auditLogs', {
+      actorUserId: skill.ownerUserId,
+      action: 'skill.delete.empty.backfill',
+      targetType: 'skill',
+      targetId: skill._id,
+      metadata: {
+        slug: skill.slug,
+        score: args.quality.score,
+        trustTier: args.quality.trustTier,
+        signals: args.quality.signals,
+      },
+      createdAt: now,
+    })
+
+    return {
+      deleted: true as const,
+      ownerUserId: skill.ownerUserId,
+      slug: skill.slug,
+    }
+  },
+})
+
+export const nominateUserForEmptySkillSpamInternal = internalMutation({
+  args: {
+    userId: v.id('users'),
+    emptySkillCount: v.number(),
+    sampleSlugs: v.array(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query('auditLogs')
+      .withIndex('by_target', (q) => q.eq('targetType', 'user').eq('targetId', args.userId))
+      .filter((q) => q.eq(q.field('action'), 'user.ban.nomination.empty-skill-spam'))
+      .first()
+    if (existing) return { created: false as const }
+
+    const now = Date.now()
+    await ctx.db.insert('auditLogs', {
+      actorUserId: args.userId,
+      action: 'user.ban.nomination.empty-skill-spam',
+      targetType: 'user',
+      targetId: args.userId,
+      metadata: {
+        emptySkillCount: args.emptySkillCount,
+        sampleSlugs: args.sampleSlugs.slice(0, 10),
+      },
+      createdAt: now,
+    })
+
+    return { created: true as const }
+  },
+})
+
+export async function cleanupEmptySkillsInternalHandler(
+  ctx: ActionCtx,
+  args: EmptySkillCleanupActionArgs,
+): Promise<EmptySkillCleanupActionResult> {
+  const dryRun = args.dryRun !== false
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+  const maxReadmeBytes = clampInt(
+    args.maxReadmeBytes ?? DEFAULT_EMPTY_SKILL_MAX_README_BYTES,
+    256,
+    65536,
+  )
+  const nominationThreshold = clampInt(
+    args.nominationThreshold ?? DEFAULT_EMPTY_SKILL_NOMINATION_THRESHOLD,
+    1,
+    100,
+  )
+
+  const totals: EmptySkillCleanupStats = {
+    skillsScanned: 0,
+    skillsEvaluated: 0,
+    emptyDetected: 0,
+    skillsDeleted: 0,
+    missingLatestVersion: 0,
+    missingVersionDoc: 0,
+    missingReadme: 0,
+    missingStorageBlob: 0,
+    skippedLargeReadme: 0,
+  }
+
+  const ownerTrustCache = new Map<string, { trustTier: TrustTier; handle: string | null }>()
+  const emptyByOwner = new Map<string, EmptySkillCleanupNomination>()
+
+  let cursor: string | null = args.cursor ?? null
+  let isDone = false
+  const now = Date.now()
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getEmptySkillCleanupPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as EmptySkillCleanupPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.skillsScanned++
+      if (item.softDeletedAt) continue
+
+      if (!item.latestVersionId) {
+        totals.missingLatestVersion++
+        continue
+      }
+
+      const version = (await ctx.runQuery(internal.skills.getVersionByIdInternal, {
+        versionId: item.latestVersionId,
+      })) as Doc<'skillVersions'> | null
+      if (!version) {
+        totals.missingVersionDoc++
+        continue
+      }
+
+      const readmeFile = version.files.find((file) => {
+        const lower = file.path.toLowerCase()
+        return lower === 'skill.md' || lower === 'skills.md'
+      })
+      if (!readmeFile) {
+        totals.missingReadme++
+        continue
+      }
+
+      if (readmeFile.size > maxReadmeBytes) {
+        totals.skippedLargeReadme++
+        continue
+      }
+
+      const blob = await ctx.storage.get(readmeFile.storageId)
+      if (!blob) {
+        totals.missingStorageBlob++
+        continue
+      }
+      const readmeText = await blob.text()
+      totals.skillsEvaluated++
+
+      const ownerKey = String(item.ownerUserId)
+      let ownerTrust = ownerTrustCache.get(ownerKey)
+      if (!ownerTrust) {
+        const owner = (await ctx.runQuery(internal.users.getByIdInternal, {
+          userId: item.ownerUserId,
+        })) as Doc<'users'> | null
+        const ownerActivity = (await ctx.runQuery(internal.skills.getOwnerSkillActivityInternal, {
+          ownerUserId: item.ownerUserId,
+          limit: 60,
+        })) as Array<{
+          slug: string
+          summary?: string
+          createdAt: number
+          latestVersionId?: Id<'skillVersions'>
+        }>
+
+        const ownerCreatedAt = owner?.createdAt ?? owner?._creationTime ?? now
+        ownerTrust = {
+          trustTier: getTrustTier(now - ownerCreatedAt, ownerActivity.length),
+          handle: owner?.handle ?? null,
+        }
+        ownerTrustCache.set(ownerKey, ownerTrust)
+      }
+
+      const qualitySignals = computeQualitySignals({
+        readmeText,
+        summary: item.summary ?? undefined,
+      })
+      const quality = evaluateQuality({
+        signals: qualitySignals,
+        trustTier: ownerTrust.trustTier,
+        similarRecentCount: 0,
+      })
+      if (quality.decision !== 'reject') continue
+
+      totals.emptyDetected++
+
+      const nomination = emptyByOwner.get(ownerKey) ?? {
+        userId: item.ownerUserId,
+        handle: ownerTrust.handle,
+        emptySkillCount: 0,
+        sampleSlugs: [],
+      }
+      nomination.emptySkillCount += 1
+      if (nomination.sampleSlugs.length < 10 && !nomination.sampleSlugs.includes(item.slug)) {
+        nomination.sampleSlugs.push(item.slug)
+      }
+      emptyByOwner.set(ownerKey, nomination)
+
+      if (dryRun) continue
+
+      const result = await ctx.runMutation(internal.maintenance.applyEmptySkillCleanupInternal, {
+        skillId: item.skillId,
+        reason: quality.reason,
+        quality: {
+          score: quality.score,
+          trustTier: quality.trustTier,
+          signals: quality.signals,
+        },
+      })
+      if (result.deleted) totals.skillsDeleted++
+    }
+
+    if (isDone) break
+  }
+
+  const nominations = Array.from(emptyByOwner.values())
+    .filter((entry) => entry.emptySkillCount >= nominationThreshold)
+    .sort((a, b) => b.emptySkillCount - a.emptySkillCount)
+
+  return {
+    ok: true as const,
+    cursor,
+    isDone,
+    stats: totals,
+    nominations: nominations.slice(0, 200),
+  }
+}
+
+export const cleanupEmptySkillsInternal = internalAction({
+  args: {
+    cursor: v.optional(v.string()),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    maxReadmeBytes: v.optional(v.number()),
+    nominationThreshold: v.optional(v.number()),
+  },
+  handler: cleanupEmptySkillsInternalHandler,
+})
+
+export const cleanupEmptySkills: ReturnType<typeof action> = action({
+  args: {
+    cursor: v.optional(v.string()),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    maxReadmeBytes: v.optional(v.number()),
+    nominationThreshold: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<EmptySkillCleanupActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(internal.maintenance.cleanupEmptySkillsInternal, args)
+  },
+})
+
+type EmptySkillBanNominationStats = {
+  skillsScanned: number
+  usersFlagged: number
+  nominationsCreated: number
+  nominationsExisting: number
+}
+
+export type EmptySkillBanNominationActionArgs = {
+  cursor?: string
+  batchSize?: number
+  maxBatches?: number
+  nominationThreshold?: number
+}
+
+export type EmptySkillBanNominationActionResult = {
+  ok: true
+  cursor: string | null
+  isDone: boolean
+  stats: EmptySkillBanNominationStats
+  nominations: EmptySkillCleanupNomination[]
+}
+
+export async function nominateEmptySkillSpammersInternalHandler(
+  ctx: ActionCtx,
+  args: EmptySkillBanNominationActionArgs,
+): Promise<EmptySkillBanNominationActionResult> {
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE)
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+  const nominationThreshold = clampInt(
+    args.nominationThreshold ?? DEFAULT_EMPTY_SKILL_NOMINATION_THRESHOLD,
+    1,
+    100,
+  )
+
+  const totals: EmptySkillBanNominationStats = {
+    skillsScanned: 0,
+    usersFlagged: 0,
+    nominationsCreated: 0,
+    nominationsExisting: 0,
+  }
+
+  const ownerHandleCache = new Map<string, string | null>()
+  const emptyByOwner = new Map<string, EmptySkillCleanupNomination>()
+
+  let cursor: string | null = args.cursor ?? null
+  let isDone = false
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getEmptySkillCleanupPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as EmptySkillCleanupPageResult
+
+    cursor = page.cursor
+    isDone = page.isDone
+
+    for (const item of page.items) {
+      totals.skillsScanned++
+      if (!item.softDeletedAt) continue
+      if (item.moderationReason !== 'quality.empty.backfill') continue
+
+      const ownerKey = String(item.ownerUserId)
+      let handle = ownerHandleCache.get(ownerKey)
+      if (handle === undefined) {
+        const owner = (await ctx.runQuery(internal.users.getByIdInternal, {
+          userId: item.ownerUserId,
+        })) as Doc<'users'> | null
+        handle = owner?.handle ?? null
+        ownerHandleCache.set(ownerKey, handle)
+      }
+
+      const nomination = emptyByOwner.get(ownerKey) ?? {
+        userId: item.ownerUserId,
+        handle,
+        emptySkillCount: 0,
+        sampleSlugs: [],
+      }
+      nomination.emptySkillCount += 1
+      if (nomination.sampleSlugs.length < 10 && !nomination.sampleSlugs.includes(item.slug)) {
+        nomination.sampleSlugs.push(item.slug)
+      }
+      emptyByOwner.set(ownerKey, nomination)
+    }
+
+    if (isDone) break
+  }
+
+  const nominations = Array.from(emptyByOwner.values())
+    .filter((entry) => entry.emptySkillCount >= nominationThreshold)
+    .sort((a, b) => b.emptySkillCount - a.emptySkillCount)
+  totals.usersFlagged = nominations.length
+
+  if (isDone) {
+    for (const nomination of nominations) {
+      const result = await ctx.runMutation(
+        internal.maintenance.nominateUserForEmptySkillSpamInternal,
+        {
+          userId: nomination.userId,
+          emptySkillCount: nomination.emptySkillCount,
+          sampleSlugs: nomination.sampleSlugs,
+        },
+      )
+      if (result.created) totals.nominationsCreated++
+      else totals.nominationsExisting++
+    }
+  }
+
+  return {
+    ok: true as const,
+    cursor,
+    isDone,
+    stats: totals,
+    nominations: nominations.slice(0, 200),
+  }
+}
+
+export const nominateEmptySkillSpammersInternal = internalAction({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    nominationThreshold: v.optional(v.number()),
+  },
+  handler: nominateEmptySkillSpammersInternalHandler,
+})
+
+export const nominateEmptySkillSpammers: ReturnType<typeof action> = action({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    nominationThreshold: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<EmptySkillBanNominationActionResult> => {
+    const { user } = await requireUserFromAction(ctx)
+    assertRole(user, ['admin'])
+    return ctx.runAction(internal.maintenance.nominateEmptySkillSpammersInternal, args)
+  },
+})
+
+// Backfill embeddingSkillMap from existing skillEmbeddings.
+// Run once after deploying the schema change:
+//   npx convex run maintenance:backfillEmbeddingSkillMapInternal --prod
+export const backfillEmbeddingSkillMapInternal = internalMutation({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const batchSize = clampInt(args.batchSize ?? 200, 10, 500)
+    const { page, continueCursor, isDone } = await ctx.db
+      .query('skillEmbeddings')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    let inserted = 0
+    for (const embedding of page) {
+      const existing = await ctx.db
+        .query('embeddingSkillMap')
+        .withIndex('by_embedding', (q) => q.eq('embeddingId', embedding._id))
+        .unique()
+      if (!existing) {
+        await ctx.db.insert('embeddingSkillMap', {
+          embeddingId: embedding._id,
+          skillId: embedding.skillId,
+        })
+        inserted++
+      }
+    }
+
+    if (!isDone) {
+      await ctx.scheduler.runAfter(0, internal.maintenance.backfillEmbeddingSkillMapInternal, {
+        cursor: continueCursor,
+        batchSize: args.batchSize,
+      })
+    }
+
+    return { inserted, isDone, scanned: page.length }
+  },
+})
+
+// Sync skillBadges table → denormalized skill.badges field.
+// Run after deploying the badge-read removal to ensure all skills
+// have up-to-date badges on the skill doc itself.
+export const backfillDenormalizedBadgesInternal = internalMutation({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const batchSize = clampInt(args.batchSize ?? 100, 10, 200)
+    const { page, continueCursor, isDone } = await ctx.db
+      .query('skills')
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize })
+
+    let patched = 0
+    for (const skill of page) {
+      const records = await ctx.db
+        .query('skillBadges')
+        .withIndex('by_skill', (q) => q.eq('skillId', skill._id))
+        .take(10)
+
+      // Build canonical badge map from the table
+      const canonical: Record<string, { byUserId: Id<'users'>; at: number }> = {}
+      for (const r of records) {
+        canonical[r.kind] = { byUserId: r.byUserId, at: r.at }
+      }
+
+      // Compare with existing denormalized badges (keys + values)
+      const existing = (skill.badges ?? {}) as Record<
+        string,
+        { byUserId?: Id<'users'>; at?: number } | undefined
+      >
+      const canonicalKeys = Object.keys(canonical)
+      const existingKeys = Object.keys(existing).filter((k) => existing[k] !== undefined)
+      const needsPatch =
+        canonicalKeys.length !== existingKeys.length ||
+        canonicalKeys.some((k) => {
+          const current = existing[k]
+          const next = canonical[k]
+          return (
+            !current ||
+            current.byUserId !== next.byUserId ||
+            current.at !== next.at
+          )
+        })
+
+      if (needsPatch) {
+        await ctx.db.patch(skill._id, { badges: canonical })
+        patched++
+      }
+    }
+
+    if (!isDone) {
+      await ctx.scheduler.runAfter(0, internal.maintenance.backfillDenormalizedBadgesInternal, {
+        cursor: continueCursor,
+        batchSize: args.batchSize,
+      })
+    }
+
+    return { patched, isDone, scanned: page.length }
+  },
+})
+
 function clampInt(value: number, min: number, max: number) {
  const rounded = Math.trunc(value)
  if (!Number.isFinite(rounded)) return min
@@ -3,8 +3,6 @@ import { defineSchema, defineTable } from 'convex/server'
 import { v } from 'convex/values'
 import { EMBEDDING_DIMENSIONS } from './lib/embeddings'

-const authSchema = authTables as unknown as Record<string, ReturnType<typeof defineTable>>
-
 const users = defineTable({
  name: v.optional(v.string()),
  image: v.optional(v.string()),
@@ -19,6 +17,10 @@ const users = defineTable({
  role: v.optional(v.union(v.literal('admin'), v.literal('moderator'), v.literal('user'))),
  githubCreatedAt: v.optional(v.number()),
  githubFetchedAt: v.optional(v.number()),
+  githubProfileSyncedAt: v.optional(v.number()),
+  trustedPublisher: v.optional(v.boolean()),
+  deactivatedAt: v.optional(v.number()),
+  purgedAt: v.optional(v.number()),
  deletedAt: v.optional(v.number()),
  banReason: v.optional(v.string()),
  createdAt: v.optional(v.number()),
@@ -79,6 +81,26 @@ const skills = defineTable({
  ),
  moderationNotes: v.optional(v.string()),
  moderationReason: v.optional(v.string()),
+  quality: v.optional(
+    v.object({
+      score: v.number(),
+      decision: v.union(v.literal('pass'), v.literal('quarantine'), v.literal('reject')),
+      trustTier: v.union(v.literal('low'), v.literal('medium'), v.literal('trusted')),
+      similarRecentCount: v.number(),
+      reason: v.string(),
+      signals: v.object({
+        bodyChars: v.number(),
+        bodyWords: v.number(),
+        uniqueWordRatio: v.number(),
+        headingCount: v.number(),
+        bulletCount: v.number(),
+        templateMarkerHits: v.number(),
+        genericSummary: v.boolean(),
+        cjkChars: v.optional(v.number()),
+      }),
+      evaluatedAt: v.number(),
+    }),
+  ),
  moderationFlags: v.optional(v.array(v.string())),
  lastReviewedAt: v.optional(v.number()),
  // VT scan tracking
@@ -113,6 +135,15 @@ const skills = defineTable({
  .index('by_stats_installs_all_time', ['statsInstallsAllTime', 'updatedAt'])
  .index('by_batch', ['batch'])
  .index('by_active_updated', ['softDeletedAt', 'updatedAt'])
+  .index('by_active_created', ['softDeletedAt', 'createdAt'])
+  .index('by_active_name', ['softDeletedAt', 'displayName'])
+  .index('by_active_stats_downloads', ['softDeletedAt', 'statsDownloads', 'updatedAt'])
+  .index('by_active_stats_stars', ['softDeletedAt', 'statsStars', 'updatedAt'])
+  .index('by_active_stats_installs_all_time', [
+    'softDeletedAt',
+    'statsInstallsAllTime',
+    'updatedAt',
+  ])
  .index('by_canonical', ['canonicalSkillId'])
  .index('by_fork_of', ['forkOf.skillId'])

@@ -279,6 +310,14 @@ const skillEmbeddings = defineTable({
    filterFields: ['visibility'],
  })

+// Lightweight lookup: embeddingId → skillId (~100 bytes per doc).
+// Avoids reading full skillEmbeddings docs (~12KB each with vector)
+// during search hydration.
+const embeddingSkillMap = defineTable({
+  embeddingId: v.id('skillEmbeddings'),
+  skillId: v.id('skills'),
+}).index('by_embedding', ['embeddingId'])
+
 const skillDailyStats = defineTable({
  skillId: v.id('skills'),
  day: v.number(),
@@ -311,6 +350,12 @@ const skillStatBackfillState = defineTable({
  updatedAt: v.number(),
 }).index('by_key', ['key'])

+const globalStats = defineTable({
+  key: v.string(),
+  activeSkillsCount: v.number(),
+  updatedAt: v.number(),
+}).index('by_key', ['key'])
+
 const skillStatEvents = defineTable({
  skillId: v.id('skills'),
  kind: v.union(
@@ -364,12 +409,37 @@ const comments = defineTable({
  skillId: v.id('skills'),
  userId: v.id('users'),
  body: v.string(),
+  reportCount: v.optional(v.number()),
+  lastReportedAt: v.optional(v.number()),
+  scamScanVerdict: v.optional(
+    v.union(v.literal('not_scam'), v.literal('likely_scam'), v.literal('certain_scam')),
+  ),
+  scamScanConfidence: v.optional(v.union(v.literal('low'), v.literal('medium'), v.literal('high'))),
+  scamScanExplanation: v.optional(v.string()),
+  scamScanEvidence: v.optional(v.array(v.string())),
+  scamScanModel: v.optional(v.string()),
+  scamScanCheckedAt: v.optional(v.number()),
+  scamBanTriggeredAt: v.optional(v.number()),
  createdAt: v.number(),
  softDeletedAt: v.optional(v.number()),
  deletedBy: v.optional(v.id('users')),
 })
  .index('by_skill', ['skillId'])
  .index('by_user', ['userId'])
+  .index('by_scam_scan_checked', ['scamScanCheckedAt'])
+
+const commentReports = defineTable({
+  commentId: v.id('comments'),
+  skillId: v.id('skills'),
+  userId: v.id('users'),
+  reason: v.optional(v.string()),
+  createdAt: v.number(),
+})
+  .index('by_comment', ['commentId'])
+  .index('by_comment_createdAt', ['commentId', 'createdAt'])
+  .index('by_skill', ['skillId'])
+  .index('by_user', ['userId'])
+  .index('by_comment_user', ['commentId', 'userId'])

 const skillReports = defineTable({
  skillId: v.id('skills'),
@@ -462,6 +532,28 @@ const rateLimits = defineTable({
  .index('by_key_window', ['key', 'windowStart'])
  .index('by_key', ['key'])

+const downloadDedupes = defineTable({
+  skillId: v.id('skills'),
+  identityHash: v.string(),
+  hourStart: v.number(),
+  createdAt: v.number(),
+})
+  .index('by_skill_identity_hour', ['skillId', 'identityHash', 'hourStart'])
+  .index('by_hour', ['hourStart'])
+
+const reservedSlugs = defineTable({
+  slug: v.string(),
+  originalOwnerUserId: v.id('users'),
+  deletedAt: v.number(),
+  expiresAt: v.number(),
+  reason: v.optional(v.string()),
+  releasedAt: v.optional(v.number()),
+})
+  .index('by_slug', ['slug'])
+  .index('by_slug_active_deletedAt', ['slug', 'releasedAt', 'deletedAt'])
+  .index('by_owner', ['originalOwnerUserId'])
+  .index('by_expiry', ['expiresAt'])
+
 const githubBackupSyncState = defineTable({
  key: v.string(),
  cursor: v.optional(v.string()),
@@ -507,7 +599,7 @@ const userSkillRootInstalls = defineTable({
  .index('by_skill', ['skillId'])

 export default defineSchema({
-  ...authSchema,
+  ...authTables,
  users,
  skills,
  souls,
@@ -517,13 +609,16 @@ export default defineSchema({
  skillBadges,
  soulVersionFingerprints,
  skillEmbeddings,
+  embeddingSkillMap,
  soulEmbeddings,
  skillDailyStats,
  skillLeaderboards,
  skillStatBackfillState,
+  globalStats,
  skillStatEvents,
  skillStatUpdateCursors,
  comments,
+  commentReports,
  skillReports,
  soulComments,
  stars,
@@ -532,6 +627,8 @@ export default defineSchema({
  vtScanLogs,
  apiTokens,
  rateLimits,
+  downloadDedupes,
+  reservedSlugs,
  githubBackupSyncState,
  userSyncRoots,
  userSkillInstalls,
@@ -2,11 +2,10 @@

 import { describe, expect, it, vi } from 'vitest'
 import { tokenize } from './lib/searchText'
-import { __test, lexicalFallbackSkills, searchSkills } from './search'
+import { __test, hydrateResults, lexicalFallbackSkills, searchSkills } from './search'

-const { generateEmbeddingMock, getSkillBadgeMapsMock } = vi.hoisted(() => ({
+const { generateEmbeddingMock } = vi.hoisted(() => ({
  generateEmbeddingMock: vi.fn(),
-  getSkillBadgeMapsMock: vi.fn(),
 }))

 vi.mock('./lib/embeddings', () => ({
@@ -14,17 +13,27 @@ vi.mock('./lib/embeddings', () => ({
 }))

 vi.mock('./lib/badges', () => ({
-  getSkillBadgeMaps: getSkillBadgeMapsMock,
  isSkillHighlighted: (skill: { badges?: Record<string, unknown> }) =>
    Boolean(skill.badges?.highlighted),
 }))

 type WrappedHandler = {
-  _handler: (ctx: unknown, args: unknown) => Promise<unknown>
+  _handler: (
+    ctx: unknown,
+    args: unknown,
+  ) => Promise<Array<{ skill: { slug: string; _id: string } }>>
 }

 const searchSkillsHandler = (searchSkills as unknown as WrappedHandler)._handler
 const lexicalFallbackSkillsHandler = (lexicalFallbackSkills as unknown as WrappedHandler)._handler
+const hydrateResultsHandler = (
+  hydrateResults as unknown as {
+    _handler: (
+      ctx: unknown,
+      args: unknown,
+    ) => Promise<Array<{ skill: { slug: string; _id: string } }>>
+  }
+)._handler

 describe('search helpers', () => {
  it('returns fallback results when vector candidates are empty', async () => {
@@ -34,13 +43,13 @@ describe('search helpers', () => {
        skill: makePublicSkill({ id: 'skills:orf', slug: 'orf', displayName: 'ORF' }),
        version: null,
        ownerHandle: 'steipete',
+        owner: null,
      },
    ]
    const runQuery = vi
      .fn()
-      .mockResolvedValueOnce([])
-      .mockResolvedValueOnce([])
-      .mockResolvedValueOnce(fallback)
+      .mockResolvedValueOnce([]) // hydrateResults
+      .mockResolvedValueOnce(fallback) // lexicalFallbackSkills

    const result = await searchSkillsHandler(
      {
@@ -59,18 +68,15 @@ describe('search helpers', () => {
  })

  it('applies highlightedOnly filtering in lexical fallback', async () => {
-    const highlighted = makeSkillDoc({
-      id: 'skills:hl',
-      slug: 'orf-highlighted',
-      displayName: 'ORF Highlighted',
-    })
+    const highlighted = {
+      ...makeSkillDoc({
+        id: 'skills:hl',
+        slug: 'orf-highlighted',
+        displayName: 'ORF Highlighted',
+      }),
+      badges: { highlighted: { byUserId: 'users:mod', at: 1 } },
+    }
    const plain = makeSkillDoc({ id: 'skills:plain', slug: 'orf-plain', displayName: 'ORF Plain' })
-    getSkillBadgeMapsMock.mockResolvedValueOnce(
-      new Map([
-        ['skills:hl', { highlighted: { byUserId: 'users:mod', at: 1 } }],
-        ['skills:plain', {}],
-      ]),
-    )

    const result = await lexicalFallbackSkillsHandler(
      makeLexicalCtx({
@@ -84,9 +90,29 @@ describe('search helpers', () => {
    expect(result[0].skill.slug).toBe('orf-highlighted')
  })

+  it('applies nonSuspiciousOnly filtering in lexical fallback', async () => {
+    const suspicious = makeSkillDoc({
+      id: 'skills:suspicious',
+      slug: 'orf-suspicious',
+      displayName: 'ORF Suspicious',
+      moderationFlags: ['flagged.suspicious'],
+    })
+    const clean = makeSkillDoc({ id: 'skills:clean', slug: 'orf-clean', displayName: 'ORF Clean' })
+
+    const result = await lexicalFallbackSkillsHandler(
+      makeLexicalCtx({
+        exactSlugSkill: null,
+        recentSkills: [suspicious, clean],
+      }),
+      { query: 'orf', queryTokens: ['orf'], nonSuspiciousOnly: true, limit: 10 },
+    )
+
+    expect(result).toHaveLength(1)
+    expect(result[0].skill.slug).toBe('orf-clean')
+  })
+
  it('includes exact slug match from by_slug even when recent scan is empty', async () => {
    const exactSlugSkill = makeSkillDoc({ id: 'skills:orf', slug: 'orf', displayName: 'ORF' })
-    getSkillBadgeMapsMock.mockResolvedValueOnce(new Map([['skills:orf', {}]]))
    const ctx = makeLexicalCtx({
      exactSlugSkill,
      recentSkills: [],
@@ -116,6 +142,7 @@ describe('search helpers', () => {
        }),
        version: null,
        ownerHandle: 'one',
+        owner: null,
      },
      {
        embeddingId: 'skillEmbeddings:b',
@@ -127,6 +154,7 @@ describe('search helpers', () => {
        }),
        version: null,
        ownerHandle: 'two',
+        owner: null,
      },
    ]
    const fallbackEntries = [
@@ -139,6 +167,7 @@ describe('search helpers', () => {
        }),
        version: null,
        ownerHandle: 'one',
+        owner: null,
      },
      {
        skill: makePublicSkill({
@@ -149,14 +178,14 @@ describe('search helpers', () => {
        }),
        version: null,
        ownerHandle: 'three',
+        owner: null,
      },
    ]

    const runQuery = vi
      .fn()
-      .mockResolvedValueOnce(vectorEntries)
-      .mockResolvedValueOnce([])
-      .mockResolvedValueOnce(fallbackEntries)
+      .mockResolvedValueOnce(vectorEntries) // hydrateResults
+      .mockResolvedValueOnce(fallbackEntries) // lexicalFallbackSkills

    const result = await searchSkillsHandler(
      {
@@ -174,6 +203,37 @@ describe('search helpers', () => {
    expect(new Set(result.map((entry: { skill: { _id: string } }) => entry.skill._id)).size).toBe(2)
  })

+  it('filters suspicious vector results in hydrateResults when requested', async () => {
+    const result = await hydrateResultsHandler(
+      {
+        db: {
+          get: vi.fn(async (id: string) => {
+            if (id === 'skillEmbeddings:1') {
+              return { _id: 'skillEmbeddings:1', skillId: 'skills:1', versionId: 'skillVersions:1' }
+            }
+            if (id === 'skills:1') {
+              return makeSkillDoc({
+                id: 'skills:1',
+                slug: 'suspicious',
+                displayName: 'Suspicious',
+                moderationFlags: ['flagged.suspicious'],
+              })
+            }
+            if (id === 'users:owner') return { _id: 'users:owner', handle: 'owner' }
+            if (id === 'skillVersions:1') return { _id: 'skillVersions:1', version: '1.0.0' }
+            return null
+          }),
+          query: vi.fn(() => ({
+            withIndex: () => ({ unique: vi.fn().mockResolvedValue(null) }),
+          })),
+        },
+      },
+      { embeddingIds: ['skillEmbeddings:1'], nonSuspiciousOnly: true },
+    )
+
+    expect(result).toHaveLength(0)
+  })
+
  it('advances candidate limit until max', () => {
    expect(__test.getNextCandidateLimit(50, 1000)).toBe(100)
    expect(__test.getNextCandidateLimit(800, 1000)).toBe(1000)
@@ -259,12 +319,19 @@ function makePublicSkill(params: {
  }
 }

-function makeSkillDoc(params: { id: string; slug: string; displayName: string }) {
+function makeSkillDoc(params: {
+  id: string
+  slug: string
+  displayName: string
+  moderationFlags?: string[]
+  moderationReason?: string
+}) {
  return {
    ...makePublicSkill(params),
    _creationTime: 1,
    moderationStatus: 'active',
-    moderationFlags: [],
+    moderationFlags: params.moderationFlags ?? [],
+    moderationReason: params.moderationReason,
    softDeletedAt: undefined,
  }
 }
@@ -1,17 +1,36 @@
 import { v } from 'convex/values'
 import { internal } from './_generated/api'
 import type { Doc, Id } from './_generated/dataModel'
+import type { QueryCtx } from './_generated/server'
 import { action, internalQuery } from './_generated/server'
-import { getSkillBadgeMaps, isSkillHighlighted, type SkillBadgeMap } from './lib/badges'
+import { isSkillHighlighted } from './lib/badges'
 import { generateEmbedding } from './lib/embeddings'
-import { toPublicSkill, toPublicSoul } from './lib/public'
+import { toPublicSkill, toPublicSoul, toPublicUser } from './lib/public'
 import { matchesExactTokens, tokenize } from './lib/searchText'
+import { isSkillSuspicious } from './lib/skillSafety'
+
+type OwnerInfo = { handle: string | null; owner: ReturnType<typeof toPublicUser> | null }
+
+function makeOwnerInfoGetter(ctx: Pick<QueryCtx, 'db'>) {
+  const ownerCache = new Map<Id<'users'>, Promise<OwnerInfo>>()
+  return (ownerUserId: Id<'users'>) => {
+    const cached = ownerCache.get(ownerUserId)
+    if (cached) return cached
+    const ownerPromise = ctx.db.get(ownerUserId).then((ownerDoc) => ({
+      handle: ownerDoc?.handle ?? (ownerDoc?._id ? String(ownerDoc._id) : null),
+      owner: toPublicUser(ownerDoc),
+    }))
+    ownerCache.set(ownerUserId, ownerPromise)
+    return ownerPromise
+  }
+}

 type SkillSearchEntry = {
  embeddingId?: Id<'skillEmbeddings'>
  skill: NonNullable<ReturnType<typeof toPublicSkill>>
  version: Doc<'skillVersions'> | null
  ownerHandle: string | null
+  owner: ReturnType<typeof toPublicUser> | null
 }

 type SearchResult = SkillSearchEntry & { score: number }
@@ -21,7 +40,7 @@ const SLUG_PREFIX_BOOST = 0.8
 const NAME_EXACT_BOOST = 1.1
 const NAME_PREFIX_BOOST = 0.6
 const POPULARITY_WEIGHT = 0.08
-const FALLBACK_SCAN_LIMIT = 1200
+const FALLBACK_SCAN_LIMIT = 500

 function getNextCandidateLimit(current: number, max: number) {
  const next = Math.min(current * 2, max)
@@ -92,6 +111,7 @@ export const searchSkills: ReturnType<typeof action> = action({
    query: v.string(),
    limit: v.optional(v.number()),
    highlightedOnly: v.optional(v.boolean()),
+    nonSuspiciousOnly: v.optional(v.boolean()),
  },
  handler: async (ctx, args): Promise<SearchResult[]> => {
    const query = args.query.trim()
@@ -122,27 +142,18 @@ export const searchSkills: ReturnType<typeof action> = action({

      hydrated = (await ctx.runQuery(internal.search.hydrateResults, {
        embeddingIds: results.map((result) => result._id),
+        nonSuspiciousOnly: args.nonSuspiciousOnly,
      })) as SkillSearchEntry[]

      scoreById = new Map<Id<'skillEmbeddings'>, number>(
        results.map((result) => [result._id, result._score]),
      )

-      const badgeMapEntries = (await ctx.runQuery(internal.search.getSkillBadgeMapsInternal, {
-        skillIds: hydrated.map((entry) => entry.skill._id),
-      })) as Array<[Id<'skills'>, SkillBadgeMap]>
-      const badgeMapBySkillId = new Map(badgeMapEntries)
-      const hydratedWithBadges = hydrated.map((entry) => ({
-        ...entry,
-        skill: {
-          ...entry.skill,
-          badges: badgeMapBySkillId.get(entry.skill._id) ?? {},
-        },
-      }))
-
+      // Skills already have badges from their docs (via toPublicSkill).
+      // No need for a separate badge table lookup.
      const filtered = args.highlightedOnly
-        ? hydratedWithBadges.filter((entry) => isSkillHighlighted(entry.skill))
-        : hydratedWithBadges
+        ? hydrated.filter((entry) => isSkillHighlighted(entry.skill))
+        : hydrated

      exactMatches = filtered.filter((entry) =>
        matchesExactTokens(queryTokens, [
@@ -169,6 +180,7 @@ export const searchSkills: ReturnType<typeof action> = action({
            queryTokens,
            limit: Math.min(Math.max(limit * 4, 200), FALLBACK_SCAN_LIMIT),
            highlightedOnly: args.highlightedOnly,
+            nonSuspiciousOnly: args.nonSuspiciousOnly,
          })) as SkillSearchEntry[])

    const mergedMatches = mergeUniqueBySkillId(exactMatches, fallbackMatches)
@@ -193,42 +205,39 @@ export const searchSkills: ReturnType<typeof action> = action({
  },
 })

-export const getBadgeMapsForSkills = internalQuery({
-  args: { skillIds: v.array(v.id('skills')) },
-  handler: async (ctx, args): Promise<Array<[Id<'skills'>, SkillBadgeMap]>> => {
-    const badgeMap = await getSkillBadgeMaps(ctx, args.skillIds)
-    return Array.from(badgeMap.entries())
-  },
-})
-
 export const hydrateResults = internalQuery({
-  args: { embeddingIds: v.array(v.id('skillEmbeddings')) },
+  args: {
+    embeddingIds: v.array(v.id('skillEmbeddings')),
+    nonSuspiciousOnly: v.optional(v.boolean()),
+  },
  handler: async (ctx, args): Promise<SkillSearchEntry[]> => {
-    const ownerHandleCache = new Map<Id<'users'>, Promise<string | null>>()
+    const getOwnerInfo = makeOwnerInfoGetter(ctx)

-    const getOwnerHandle = (ownerUserId: Id<'users'>) => {
-      const cached = ownerHandleCache.get(ownerUserId)
-      if (cached) return cached
-      const handlePromise = ctx.db
-        .get(ownerUserId)
-        .then((owner) => owner?.handle ?? owner?._id ?? null)
-      ownerHandleCache.set(ownerUserId, handlePromise)
-      return handlePromise
-    }
-
-    const entries = await Promise.all(
+    const entries: Array<SkillSearchEntry | null> = await Promise.all(
      args.embeddingIds.map(async (embeddingId) => {
-        const embedding = await ctx.db.get(embeddingId)
-        if (!embedding) return null
-        const skill = await ctx.db.get(embedding.skillId)
+        // Use lightweight lookup table (~100 bytes) instead of full embedding doc (~12KB).
+        const lookup = await ctx.db
+          .query('embeddingSkillMap')
+          .withIndex('by_embedding', (q) => q.eq('embeddingId', embeddingId))
+          .unique()
+        // Fallback to full embedding doc for rows not yet backfilled.
+        const skillId = lookup
+          ? lookup.skillId
+          : await ctx.db.get(embeddingId).then((e) => e?.skillId)
+        if (!skillId) return null
+        const skill = await ctx.db.get(skillId)
        if (!skill || skill.softDeletedAt) return null
-        const [version, ownerHandle] = await Promise.all([
-          ctx.db.get(embedding.versionId),
-          getOwnerHandle(skill.ownerUserId),
-        ])
+        if (args.nonSuspiciousOnly && isSkillSuspicious(skill)) return null
+        const ownerInfo = await getOwnerInfo(skill.ownerUserId)
        const publicSkill = toPublicSkill(skill)
        if (!publicSkill) return null
-        return { embeddingId, skill: publicSkill, version, ownerHandle }
+        return {
+          embeddingId,
+          skill: publicSkill,
+          version: null as Doc<'skillVersions'> | null,
+          ownerHandle: ownerInfo.handle,
+          owner: ownerInfo.owner,
+        }
      }),
    )

@@ -242,6 +251,7 @@ export const lexicalFallbackSkills = internalQuery({
    queryTokens: v.array(v.string()),
    limit: v.optional(v.number()),
    highlightedOnly: v.optional(v.boolean()),
+    nonSuspiciousOnly: v.optional(v.boolean()),
  },
  handler: async (ctx, args): Promise<SkillSearchEntry[]> => {
    const limit = Math.min(Math.max(args.limit ?? 200, 10), FALLBACK_SCAN_LIMIT)
@@ -254,7 +264,11 @@ export const lexicalFallbackSkills = internalQuery({
        .query('skills')
        .withIndex('by_slug', (q) => q.eq('slug', slugQuery))
        .unique()
-      if (exactSlugSkill && !exactSlugSkill.softDeletedAt) {
+      if (
+        exactSlugSkill &&
+        !exactSlugSkill.softDeletedAt &&
+        (!args.nonSuspiciousOnly || !isSkillSuspicious(exactSlugSkill))
+      ) {
        seenSkillIds.add(exactSlugSkill._id)
        candidateSkills.push(exactSlugSkill)
      }
@@ -268,6 +282,7 @@ export const lexicalFallbackSkills = internalQuery({

    for (const skill of recentSkills) {
      if (seenSkillIds.has(skill._id)) continue
+      if (args.nonSuspiciousOnly && isSkillSuspicious(skill)) continue
      seenSkillIds.add(skill._id)
      candidateSkills.push(skill)
    }
@@ -277,46 +292,29 @@ export const lexicalFallbackSkills = internalQuery({
    )
    if (matched.length === 0) return []

-    const ownerHandleCache = new Map<Id<'users'>, Promise<string | null>>()
-    const getOwnerHandle = (ownerUserId: Id<'users'>) => {
-      const cached = ownerHandleCache.get(ownerUserId)
-      if (cached) return cached
-      const handlePromise = ctx.db
-        .get(ownerUserId)
-        .then((owner) => owner?.handle ?? owner?._id ?? null)
-      ownerHandleCache.set(ownerUserId, handlePromise)
-      return handlePromise
-    }
+    const getOwnerInfo = makeOwnerInfoGetter(ctx)

    const entries = await Promise.all(
      matched.map(async (skill) => {
-        const [version, ownerHandle] = await Promise.all([
-          skill.latestVersionId ? ctx.db.get(skill.latestVersionId) : Promise.resolve(null),
-          getOwnerHandle(skill.ownerUserId),
-        ])
+        const ownerInfo = await getOwnerInfo(skill.ownerUserId)
        const publicSkill = toPublicSkill(skill)
        if (!publicSkill) return null
-        return { skill: publicSkill, version, ownerHandle }
+        return {
+          skill: publicSkill,
+          version: null as Doc<'skillVersions'> | null,
+          ownerHandle: ownerInfo.handle,
+          owner: ownerInfo.owner,
+        }
      }),
    )
    const validEntries = entries.filter((entry): entry is SkillSearchEntry => entry !== null)
    if (validEntries.length === 0) return []

-    const badgeMap = await getSkillBadgeMaps(
-      ctx,
-      validEntries.map((entry) => entry.skill._id),
-    )
-    const withBadges = validEntries.map((entry) => ({
-      ...entry,
-      skill: {
-        ...entry.skill,
-        badges: badgeMap.get(entry.skill._id) ?? {},
-      },
-    }))
-
+    // Skills already have badges from their docs (via toPublicSkill).
+    // No need for a separate badge table lookup.
    const filtered = args.highlightedOnly
-      ? withBadges.filter((entry) => isSkillHighlighted(entry.skill))
-      : withBadges
+      ? validEntries.filter((entry) => isSkillHighlighted(entry.skill))
+      : validEntries
    return filtered.slice(0, limit)
  },
 })
@@ -416,14 +414,6 @@ export const hydrateSoulResults = internalQuery({
  },
 })

-export const getSkillBadgeMapsInternal = internalQuery({
-  args: { skillIds: v.array(v.id('skills')) },
-  handler: async (ctx, args) => {
-    const badgeMap = await getSkillBadgeMaps(ctx, args.skillIds)
-    return Array.from(badgeMap.entries())
-  },
-})
-
 export const __test = {
  getNextCandidateLimit,
  matchesAllTokens,
@@ -3,14 +3,18 @@
 *
 * Instead of updating skill stats synchronously in the hot path (which can cause
 * contention when multiple users download/star/install the same skill), we insert
- * lightweight event records and process them in batches via a cron job.
+ * lightweight event records and process them in batches via cron jobs.
 *
- * Flow:
- * 1. User action (download, star, install) → insertStatEvent() writes to skillStatEvents table
- * 2. Cron job runs every 5 minutes → processSkillStatEventsInternal() processes batches
- * 3. Events are aggregated per-skill to minimize database operations
- * 4. Stats are applied to skill documents and daily stats tables
- * 5. Events are marked as processed (kept forever for auditing)
+ * Two processing paths run at different frequencies to balance freshness vs bandwidth:
+ *
+ * 1. **Daily stats (15-minute cron)** — `processSkillStatEventsAction`
+ *    Writes to skillDailyStats for trending/leaderboards. Uses a cursor in
+ *    skillStatUpdateCursors. Does NOT touch skill documents.
+ *
+ * 2. **Skill doc sync (6-hour cron)** — `processSkillStatEventsInternal`
+ *    Patches skill documents with accumulated stat deltas. Uses processedAt
+ *    field to track progress. Runs infrequently because patching skill docs
+ *    invalidates reactive queries for all subscribers (thundering herd).
 */

 import { v } from 'convex/values'
@@ -175,7 +179,7 @@ function aggregateEvents(events: Doc<'skillStatEvents'>[]): AggregatedDeltas {
 /**
 * Process a batch of unprocessed stat events.
 *
- * Called by cron every 5 minutes. Processes up to batchSize events (default 100).
+ * Called by the 6-hour cron to sync stats to skill docs. Processes up to batchSize events (default 500).
 * If the batch is full, schedules an immediate follow-up run to drain the queue.
 *
 * Processing steps:
@@ -198,7 +202,7 @@ function aggregateEvents(events: Doc<'skillStatEvents'>[]): AggregatedDeltas {
 export const processSkillStatEventsInternal = internalMutation({
  args: { batchSize: v.optional(v.number()) },
  handler: async (ctx, args) => {
-    const batchSize = args.batchSize ?? 100
+    const batchSize = args.batchSize ?? 500
    const now = Date.now()

    // Level 1: Fetch a batch of unprocessed events
@@ -252,25 +256,13 @@ export const processSkillStatEventsInternal = internalMutation({
          installsAllTime: deltas.installsAllTime,
          installsCurrent: deltas.installsCurrent,
        })
-        await ctx.db.patch(skill._id, {
-          ...patch,
-          updatedAt: now,
-        })
+        // Don't update `updatedAt` — stat changes shouldn't move the
+        // skill's position in the by_active_updated index.
+        await ctx.db.patch(skill._id, patch)
      }

-      // Update daily stats for trending/leaderboards
-      // We use the ORIGINAL event timestamp (occurredAt) so that:
-      // - A download at Mon 11:55 PM counts toward Monday's stats
-      // - Even if the cron processes it on Tuesday
-      //
-      // Level 4: bumpDailySkillStats does its own coalescing - multiple
-      // events on the same day will update the same daily record
-      for (const occurredAt of deltas.downloadEvents) {
-        await bumpDailySkillStats(ctx, { skillId, now: occurredAt, downloads: 1 })
-      }
-      for (const occurredAt of deltas.installNewEvents) {
-        await bumpDailySkillStats(ctx, { skillId, now: occurredAt, installs: 1 })
-      }
+      // NOTE: Daily stats (skillDailyStats) are written by the 15-minute
+      // action cron (processSkillStatEventsAction), not here.

      // Mark all events for this skill as processed
      for (const event of skillEvents) {
@@ -352,11 +344,11 @@ const skillDeltaValidator = v.object({
 })

 /**
- * Apply aggregated stats to skills and update the cursor.
+ * Write aggregated daily stats and advance the cursor.
 * This is a single atomic mutation that:
- * 1. Updates all affected skills with their aggregated deltas
- * 2. Updates daily stats for trending
- * 3. Advances the cursor to the new position
+ * 1. Updates daily stats for trending/leaderboards (skillDailyStats)
+ * 2. Advances the cursor to the new position
+ * NOTE: Does NOT patch skill documents — that's handled by processSkillStatEventsInternal.
 */
 export const applyAggregatedStatsAndUpdateCursor = internalMutation({
  args: {
@@ -366,37 +358,8 @@ export const applyAggregatedStatsAndUpdateCursor = internalMutation({
  handler: async (ctx, args) => {
    const now = Date.now()

-    // Process each skill's aggregated deltas
+    // Update daily stats for trending/leaderboards
    for (const delta of args.skillDeltas) {
-      const skill = await ctx.db.get(delta.skillId)
-
-      // Skill was deleted - skip
-      if (!skill) {
-        continue
-      }
-
-      // Apply aggregated deltas to skill stats
-      if (
-        delta.downloads !== 0 ||
-        delta.stars !== 0 ||
-        delta.comments !== 0 ||
-        delta.installsAllTime !== 0 ||
-        delta.installsCurrent !== 0
-      ) {
-        const patch = applySkillStatDeltas(skill, {
-          downloads: delta.downloads,
-          stars: delta.stars,
-          comments: delta.comments,
-          installsAllTime: delta.installsAllTime,
-          installsCurrent: delta.installsCurrent,
-        })
-        await ctx.db.patch(skill._id, {
-          ...patch,
-          updatedAt: now,
-        })
-      }
-
-      // Update daily stats for trending/leaderboards
      for (const occurredAt of delta.downloadEvents) {
        await bumpDailySkillStats(ctx, { skillId: delta.skillId, now: occurredAt, downloads: 1 })
      }
@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest'
+import { countPublicSkills } from './skills'
+
+type WrappedHandler<TArgs, TResult> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>
+}
+
+const countPublicSkillsHandler = (
+  countPublicSkills as unknown as WrappedHandler<Record<string, never>, number>
+)._handler
+
+function makeSkillsQuery(skills: Array<{ softDeletedAt?: number; moderationStatus?: string | null }>) {
+  return {
+    withIndex: (name: string) => {
+      if (name !== 'by_active_updated') throw new Error(`unexpected skills index ${name}`)
+      return {
+        collect: async () => skills,
+      }
+    },
+  }
+}
+
+describe('skills.countPublicSkills', () => {
+  it('returns precomputed global stats count when available', async () => {
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table === 'globalStats') {
+            return {
+              withIndex: () => ({
+                unique: async () => ({ _id: 'globalStats:1', activeSkillsCount: 123 }),
+              }),
+            }
+          }
+          if (table === 'skills') {
+            return makeSkillsQuery([])
+          }
+          throw new Error(`unexpected table ${table}`)
+        }),
+      },
+    }
+
+    const result = await countPublicSkillsHandler(ctx, {})
+    expect(result).toBe(123)
+  })
+
+  it('falls back to live count when global stats row is missing', async () => {
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table === 'globalStats') {
+            return {
+              withIndex: () => ({
+                unique: async () => null,
+              }),
+            }
+          }
+          if (table === 'skills') {
+            return makeSkillsQuery([
+              { softDeletedAt: undefined, moderationStatus: 'active' },
+              { softDeletedAt: undefined, moderationStatus: 'hidden' },
+              { softDeletedAt: undefined, moderationStatus: 'active' },
+            ])
+          }
+          throw new Error(`unexpected table ${table}`)
+        }),
+      },
+    }
+
+    const result = await countPublicSkillsHandler(ctx, {})
+    expect(result).toBe(2)
+  })
+
+  it('falls back to live count when globalStats table is unavailable', async () => {
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table === 'globalStats') {
+            throw new Error('unexpected table globalStats')
+          }
+          if (table === 'skills') {
+            return makeSkillsQuery([
+              { softDeletedAt: undefined, moderationStatus: 'active' },
+              { softDeletedAt: undefined, moderationStatus: 'active' },
+            ])
+          }
+          throw new Error(`unexpected table ${table}`)
+        }),
+      },
+    }
+
+    const result = await countPublicSkillsHandler(ctx, {})
+    expect(result).toBe(2)
+  })
+})
@@ -0,0 +1,369 @@
+/* @vitest-environment node */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { getSkillBadgeMapMock, getSkillBadgeMapsMock, isSkillHighlightedMock } = vi.hoisted(() => ({
+  getSkillBadgeMapMock: vi.fn(),
+  getSkillBadgeMapsMock: vi.fn(),
+  isSkillHighlightedMock: vi.fn(),
+}))
+
+vi.mock('./lib/badges', () => ({
+  getSkillBadgeMap: getSkillBadgeMapMock,
+  getSkillBadgeMaps: getSkillBadgeMapsMock,
+  isSkillHighlighted: isSkillHighlightedMock,
+}))
+
+import { listPublicPageV2 } from './skills'
+
+type ListArgs = {
+  paginationOpts: { cursor: string | null; numItems: number; id?: number }
+  sort?: 'newest' | 'updated' | 'downloads' | 'installs' | 'stars' | 'name'
+  dir?: 'asc' | 'desc'
+  highlightedOnly?: boolean
+  nonSuspiciousOnly?: boolean
+}
+
+type ListResult = {
+  page: Array<{ skill: { slug: string } }>
+  continueCursor: string | null
+  isDone: boolean
+}
+
+type WrappedHandler<TArgs, TResult> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>
+}
+
+const listPublicPageV2Handler = (listPublicPageV2 as unknown as WrappedHandler<ListArgs, ListResult>)
+  ._handler
+
+describe('skills.listPublicPageV2', () => {
+  beforeEach(() => {
+    getSkillBadgeMapMock.mockReset()
+    getSkillBadgeMapsMock.mockReset()
+    getSkillBadgeMapsMock.mockResolvedValue(new Map())
+    isSkillHighlightedMock.mockReset()
+    isSkillHighlightedMock.mockImplementation((skill: { slug?: string }) =>
+      Boolean(skill.slug?.startsWith('hl-')),
+    )
+  })
+
+  it('applies highlightedOnly and nonSuspiciousOnly together', async () => {
+    const highlightedClean = makeSkill('skills:hl-clean', 'hl-clean', 'users:1', 'skillVersions:1')
+    const plainClean = makeSkill('skills:plain', 'plain', 'users:2', 'skillVersions:2')
+    const highlightedSuspicious = makeSkill(
+      'skills:hl-suspicious',
+      'hl-suspicious',
+      'users:3',
+      'skillVersions:3',
+      ['flagged.suspicious'],
+    )
+
+    const paginateMock = vi.fn().mockResolvedValue({
+      page: [highlightedClean, plainClean, highlightedSuspicious],
+      continueCursor: 'next-cursor',
+      isDone: false,
+      pageStatus: null,
+      splitCursor: null,
+    })
+    const orderMock = vi.fn(() => ({ paginate: paginateMock }))
+    const eqMock = vi.fn(() => ({}))
+    const withIndexMock = vi.fn((_index: string, builder: (q: { eq: typeof eqMock }) => unknown) => {
+      builder({ eq: eqMock })
+      return { order: orderMock }
+    })
+    const getMock = vi.fn(async (id: string) => {
+      if (id.startsWith('users:')) return makeUser(id)
+      if (id.startsWith('skillVersions:')) return makeVersion(id)
+      return null
+    })
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table !== 'skills') throw new Error(`unexpected table ${table}`)
+          return { withIndex: withIndexMock }
+        }),
+        get: getMock,
+      },
+    }
+
+    const result = await listPublicPageV2Handler(ctx, {
+      paginationOpts: { cursor: null, numItems: 25 },
+      sort: 'downloads',
+      dir: 'desc',
+      highlightedOnly: true,
+      nonSuspiciousOnly: true,
+    })
+
+    expect(result.page).toHaveLength(1)
+    expect(result.page[0]?.skill.slug).toBe('hl-clean')
+    expect(result.continueCursor).toBe('next-cursor')
+    expect(result.isDone).toBe(false)
+    expect(withIndexMock).toHaveBeenCalledWith('by_active_stats_downloads', expect.any(Function))
+    expect(orderMock).toHaveBeenCalledWith('desc')
+    expect(paginateMock).toHaveBeenCalledWith({ cursor: null, numItems: 25 })
+    expect(eqMock).toHaveBeenCalledWith('softDeletedAt', undefined)
+  })
+
+  it('skips fully filtered pages until it finds matching skills', async () => {
+    const plain = makeSkill('skills:plain', 'plain', 'users:1', 'skillVersions:1')
+    const highlightedClean = makeSkill('skills:hl-clean', 'hl-clean', 'users:2', 'skillVersions:2')
+    const paginateMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        page: [plain],
+        continueCursor: 'next-cursor',
+        isDone: false,
+        pageStatus: null,
+        splitCursor: null,
+      })
+      .mockResolvedValueOnce({
+        page: [highlightedClean],
+        continueCursor: 'after-highlighted',
+        isDone: false,
+        pageStatus: null,
+        splitCursor: null,
+      })
+    const ctx = {
+      db: {
+        query: vi.fn(() => ({
+          withIndex: vi.fn(() => ({
+            order: vi.fn(() => ({ paginate: paginateMock })),
+          })),
+        })),
+        get: vi.fn(async (id: string) => {
+          if (id.startsWith('users:')) return makeUser(id)
+          if (id.startsWith('skillVersions:')) return makeVersion(id)
+          return null
+        }),
+      },
+    }
+
+    const result = await listPublicPageV2Handler(ctx, {
+      paginationOpts: { cursor: null, numItems: 25 },
+      sort: 'downloads',
+      dir: 'desc',
+      highlightedOnly: true,
+      nonSuspiciousOnly: false,
+    })
+
+    expect(result.page).toHaveLength(1)
+    expect(result.page[0]?.skill.slug).toBe('hl-clean')
+    expect(result.continueCursor).toBe('after-highlighted')
+    expect(result.isDone).toBe(false)
+    expect(paginateMock).toHaveBeenCalledTimes(2)
+    expect(paginateMock).toHaveBeenNthCalledWith(1, { cursor: null, numItems: 25 })
+    expect(paginateMock).toHaveBeenNthCalledWith(2, { cursor: 'next-cursor', numItems: 25 })
+  })
+
+  it('returns exhausted when filtered pages remain empty to the end', async () => {
+    const plain = makeSkill('skills:plain', 'plain', 'users:1', 'skillVersions:1')
+    const paginateMock = vi.fn().mockResolvedValue({
+      page: [plain],
+      continueCursor: null,
+      isDone: true,
+      pageStatus: null,
+      splitCursor: null,
+    })
+    const ctx = {
+      db: {
+        query: vi.fn(() => ({
+          withIndex: vi.fn(() => ({
+            order: vi.fn(() => ({ paginate: paginateMock })),
+          })),
+        })),
+        get: vi.fn(),
+      },
+    }
+
+    const result = await listPublicPageV2Handler(ctx, {
+      paginationOpts: { cursor: null, numItems: 25 },
+      sort: 'downloads',
+      dir: 'desc',
+      highlightedOnly: true,
+      nonSuspiciousOnly: false,
+    })
+
+    expect(result.page).toEqual([])
+    expect(result.continueCursor).toBeNull()
+    expect(result.isDone).toBe(true)
+    expect(paginateMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('restarts pagination from first page when cursor is stale', async () => {
+    const plain = makeSkill('skills:plain', 'plain', 'users:1', 'skillVersions:1')
+    const paginateMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('Failed to parse cursor'))
+      .mockResolvedValueOnce({
+        page: [plain],
+        continueCursor: 'next-cursor',
+        isDone: false,
+        pageStatus: null,
+        splitCursor: null,
+      })
+    const ctx = {
+      db: {
+        query: vi.fn(() => ({
+          withIndex: vi.fn(() => ({
+            order: vi.fn(() => ({ paginate: paginateMock })),
+          })),
+        })),
+        get: vi.fn(async (id: string) => {
+          if (id.startsWith('users:')) return makeUser(id)
+          if (id.startsWith('skillVersions:')) return makeVersion(id)
+          return null
+        }),
+      },
+    }
+
+    const result = await listPublicPageV2Handler(ctx, {
+      paginationOpts: { cursor: 'stale-cursor', numItems: 25, id: 123456 },
+      sort: 'downloads',
+      dir: 'desc',
+      highlightedOnly: false,
+      nonSuspiciousOnly: false,
+    })
+
+    expect(result.page).toHaveLength(1)
+    expect(result.page[0]?.skill.slug).toBe('plain')
+    expect(result.continueCursor).toBe('next-cursor')
+    expect(result.isDone).toBe(false)
+    expect(paginateMock).toHaveBeenNthCalledWith(1, { cursor: 'stale-cursor', numItems: 25 })
+    expect(paginateMock).toHaveBeenNthCalledWith(2, { cursor: null, numItems: 25 })
+    expect(paginateMock).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: expect.any(Number),
+      }),
+    )
+  })
+
+  it('drops pagination id from client options on first-page queries', async () => {
+    const plain = makeSkill('skills:plain', 'plain', 'users:1', 'skillVersions:1')
+    const paginateMock = vi.fn().mockResolvedValue({
+      page: [plain],
+      continueCursor: 'next-cursor',
+      isDone: false,
+      pageStatus: null,
+      splitCursor: null,
+    })
+    const ctx = {
+      db: {
+        query: vi.fn(() => ({
+          withIndex: vi.fn(() => ({
+            order: vi.fn(() => ({ paginate: paginateMock })),
+          })),
+        })),
+        get: vi.fn(async (id: string) => {
+          if (id.startsWith('users:')) return makeUser(id)
+          if (id.startsWith('skillVersions:')) return makeVersion(id)
+          return null
+        }),
+      },
+    }
+
+    const result = await listPublicPageV2Handler(ctx, {
+      paginationOpts: { cursor: null, numItems: 25, id: 999_999_999 },
+      sort: 'downloads',
+      dir: 'desc',
+      highlightedOnly: false,
+      nonSuspiciousOnly: false,
+    })
+
+    expect(result.page).toHaveLength(1)
+    expect(paginateMock).toHaveBeenCalledTimes(1)
+    expect(paginateMock).toHaveBeenCalledWith({ cursor: null, numItems: 25 })
+    expect(paginateMock).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: expect.any(Number),
+      }),
+    )
+  })
+
+  it('does not swallow non-cursor paginate errors', async () => {
+    const paginateMock = vi.fn().mockRejectedValue(new Error('database unavailable'))
+    const ctx = {
+      db: {
+        query: vi.fn(() => ({
+          withIndex: vi.fn(() => ({
+            order: vi.fn(() => ({ paginate: paginateMock })),
+          })),
+        })),
+        get: vi.fn(),
+      },
+    }
+
+    await expect(
+      listPublicPageV2Handler(ctx, {
+        paginationOpts: { cursor: 'stale-cursor', numItems: 25, id: 999_999_999 },
+        sort: 'downloads',
+        dir: 'desc',
+        highlightedOnly: false,
+        nonSuspiciousOnly: false,
+      }),
+    ).rejects.toThrow('database unavailable')
+
+    expect(paginateMock).toHaveBeenCalledTimes(1)
+    expect(paginateMock).toHaveBeenCalledWith({ cursor: 'stale-cursor', numItems: 25 })
+  })
+})
+
+function makeSkill(
+  id: string,
+  slug: string,
+  ownerUserId: string,
+  latestVersionId: string,
+  moderationFlags?: string[],
+) {
+  return {
+    _id: id,
+    _creationTime: 1,
+    slug,
+    displayName: slug,
+    summary: `${slug} summary`,
+    ownerUserId,
+    canonicalSkillId: undefined,
+    forkOf: undefined,
+    latestVersionId,
+    tags: {},
+    badges: {},
+    stats: {
+      downloads: 0,
+      stars: 0,
+      installsCurrent: 0,
+      installsAllTime: 0,
+      versions: 1,
+      comments: 0,
+    },
+    createdAt: 1,
+    updatedAt: 1,
+    softDeletedAt: undefined,
+    moderationStatus: 'active',
+    moderationFlags,
+  }
+}
+
+function makeUser(id: string) {
+  return {
+    _id: id,
+    _creationTime: 1,
+    handle: 'owner',
+    name: 'Owner',
+    displayName: 'Owner',
+    image: null,
+    bio: null,
+    deletedAt: undefined,
+    deactivatedAt: undefined,
+  }
+}
+
+function makeVersion(id: string) {
+  return {
+    _id: id,
+    _creationTime: 1,
+    version: '1.0.0',
+    createdAt: 1,
+    changelog: '',
+    changelogSource: 'user',
+    parsed: {},
+  }
+}
@@ -0,0 +1,202 @@
+import { describe, expect, it, vi } from 'vitest'
+import { getPendingScanSkillsInternal } from './skills'
+
+type PendingScanResult = Array<{
+  skillId: string
+  versionId: string | null
+  sha256hash: string | null
+  checkCount: number
+}>
+
+type WrappedHandler<TArgs, TResult> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>
+}
+
+const getPendingScanSkillsHandler = (
+  getPendingScanSkillsInternal as unknown as WrappedHandler<Record<string, unknown>, PendingScanResult>
+)._handler
+
+describe('skills.getPendingScanSkillsInternal', () => {
+  it('includes unresolved VT records from the oldest slice and skips finalized ones', async () => {
+    const recentSkills = [
+      makeSkill('skills:recent-clean', 'skillVersions:recent-clean', 'scanner.llm.clean'),
+      makeSkill('skills:recent-malicious', 'skillVersions:recent-malicious', 'scanner.vt.pending'),
+    ]
+    const oldestSkills = [
+      makeSkill('skills:old-pending', 'skillVersions:old-pending', 'scanner.vt.pending'),
+      makeSkill('skills:old-stale', 'skillVersions:old-stale', 'scanner.llm.clean'),
+      makeSkill('skills:old-no-hash', 'skillVersions:old-no-hash', 'scanner.vt.pending'),
+    ]
+
+    const versions = new Map<string, unknown>([
+      [
+        'skillVersions:recent-clean',
+        { _id: 'skillVersions:recent-clean', sha256hash: 'a'.repeat(64), vtAnalysis: { status: 'clean' } },
+      ],
+      [
+        'skillVersions:recent-malicious',
+        {
+          _id: 'skillVersions:recent-malicious',
+          sha256hash: 'b'.repeat(64),
+          vtAnalysis: { status: 'malicious' },
+        },
+      ],
+      [
+        'skillVersions:old-pending',
+        { _id: 'skillVersions:old-pending', sha256hash: 'c'.repeat(64), vtAnalysis: { status: 'pending' } },
+      ],
+      [
+        'skillVersions:old-stale',
+        { _id: 'skillVersions:old-stale', sha256hash: 'd'.repeat(64), vtAnalysis: { status: 'stale' } },
+      ],
+      ['skillVersions:old-no-hash', { _id: 'skillVersions:old-no-hash' }],
+    ])
+
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table !== 'skills') throw new Error(`unexpected table ${table}`)
+          return {
+            withIndex: (
+              indexName: string,
+              builder: (q: { eq: (field: string, value: unknown) => unknown }) => unknown,
+            ) => {
+              builder({ eq: () => ({}) })
+              if (indexName === 'by_active_updated') {
+                return {
+                  order: () => ({
+                    take: async () => recentSkills,
+                  }),
+                }
+              }
+              if (indexName === 'by_active_created') {
+                return {
+                  order: () => ({
+                    take: async () => oldestSkills,
+                  }),
+                }
+              }
+              throw new Error(`unexpected index ${indexName}`)
+            },
+          }
+        }),
+        get: vi.fn(async (id: string) => versions.get(id) ?? null),
+      },
+    }
+
+    const result = await getPendingScanSkillsHandler(ctx, {
+      limit: 25,
+      skipRecentMinutes: 0,
+    })
+
+    const ids = new Set(result.map((entry) => entry.skillId))
+    expect(ids.has('skills:old-pending')).toBe(true)
+    expect(ids.has('skills:old-stale')).toBe(true)
+    expect(ids.has('skills:recent-clean')).toBe(false)
+    expect(ids.has('skills:recent-malicious')).toBe(false)
+    expect(ids.has('skills:old-no-hash')).toBe(false)
+  })
+
+  it('exhaustive mode ignores recent-check suppression for manual backfills', async () => {
+    const now = Date.now()
+    const allSkills = [
+      makeSkill('skills:recently-checked', 'skillVersions:recently-checked', 'scanner.vt.pending', now),
+    ]
+    const versions = new Map<string, unknown>([
+      [
+        'skillVersions:recently-checked',
+        { _id: 'skillVersions:recently-checked', sha256hash: 'e'.repeat(64) },
+      ],
+    ])
+
+    const withIndex = vi.fn(
+      (
+        indexName: string,
+        builder: (q: { eq: (field: string, value: unknown) => unknown }) => unknown,
+      ) => {
+        builder({ eq: () => ({}) })
+        if (indexName !== 'by_active_updated') throw new Error(`unexpected index ${indexName}`)
+        return {
+          collect: async () => allSkills,
+        }
+      },
+    )
+
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table !== 'skills') throw new Error(`unexpected table ${table}`)
+          return { withIndex }
+        }),
+        get: vi.fn(async (id: string) => versions.get(id) ?? null),
+      },
+    }
+
+    const result = await getPendingScanSkillsHandler(ctx, {
+      limit: 25,
+      skipRecentMinutes: 60,
+      exhaustive: true,
+    })
+
+    expect(result).toHaveLength(1)
+    expect(result[0]?.skillId).toBe('skills:recently-checked')
+  })
+
+  it('does not clamp exhaustive mode to 100 records', async () => {
+    const allSkills = Array.from({ length: 150 }, (_, i) =>
+      makeSkill(`skills:bulk-${i}`, `skillVersions:bulk-${i}`, 'scanner.vt.pending'),
+    )
+    const versions = new Map<string, unknown>(
+      allSkills.map((skill) => {
+        const versionId = skill.latestVersionId as string
+        return [versionId, { _id: versionId, sha256hash: `${String(versionId).slice(-8)}${'f'.repeat(56)}` }]
+      }),
+    )
+
+    const withIndex = vi.fn(
+      (
+        indexName: string,
+        builder: (q: { eq: (field: string, value: unknown) => unknown }) => unknown,
+      ) => {
+        builder({ eq: () => ({}) })
+        if (indexName !== 'by_active_updated') throw new Error(`unexpected index ${indexName}`)
+        return {
+          collect: async () => allSkills,
+        }
+      },
+    )
+
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table !== 'skills') throw new Error(`unexpected table ${table}`)
+          return { withIndex }
+        }),
+        get: vi.fn(async (id: string) => versions.get(id) ?? null),
+      },
+    }
+
+    const result = await getPendingScanSkillsHandler(ctx, {
+      limit: 10000,
+      exhaustive: true,
+      skipRecentMinutes: 0,
+    })
+
+    expect(result).toHaveLength(150)
+  })
+})
+
+function makeSkill(
+  id: string,
+  versionId: string,
+  moderationReason: string,
+  scanLastCheckedAt?: number,
+) {
+  return {
+    _id: id,
+    moderationStatus: 'active',
+    moderationReason,
+    latestVersionId: versionId,
+    scanLastCheckedAt,
+  }
+}
@@ -0,0 +1,510 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  approveSkillByHashInternal,
+  clearOwnerSuspiciousFlagsInternal,
+  escalateByVtInternal,
+  insertVersion,
+} from './skills'
+
+type WrappedHandler<TArgs> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<unknown>
+}
+
+const insertVersionHandler = (insertVersion as unknown as WrappedHandler<Record<string, unknown>>)
+  ._handler
+const approveSkillByHashHandler = (
+  approveSkillByHashInternal as unknown as WrappedHandler<Record<string, unknown>>
+)._handler
+const escalateByVtHandler = (
+  escalateByVtInternal as unknown as WrappedHandler<Record<string, unknown>>
+)._handler
+const clearOwnerSuspiciousFlagsHandler = (
+  clearOwnerSuspiciousFlagsInternal as unknown as WrappedHandler<Record<string, unknown>>
+)._handler
+
+function buildGlobalStatsQuery(table: string) {
+  if (table !== 'globalStats') return null
+  return {
+    withIndex: (name: string) => {
+      if (name !== 'by_key') throw new Error(`unexpected globalStats index ${name}`)
+      return {
+        unique: async () => ({
+          _id: 'globalStats:1',
+          activeSkillsCount: 100,
+        }),
+      }
+    },
+  }
+}
+
+function createPublishArgs(overrides?: Partial<Record<string, unknown>>) {
+  return {
+    userId: 'users:owner',
+    slug: 'spam-skill',
+    displayName: 'Spam Skill',
+    version: '1.0.0',
+    changelog: 'Initial release',
+    changelogSource: 'user',
+    tags: ['latest'],
+    fingerprint: 'f'.repeat(64),
+    files: [
+      {
+        path: 'SKILL.md',
+        size: 128,
+        storageId: '_storage:1',
+        sha256: 'a'.repeat(64),
+        contentType: 'text/markdown',
+      },
+    ],
+    parsed: {
+      frontmatter: { description: 'test' },
+      metadata: {},
+      clawdis: {},
+    },
+    embedding: [0.1, 0.2],
+    ...overrides,
+  }
+}
+
+describe('skills anti-spam guards', () => {
+  it('blocks low-trust users after hourly new-skill cap', async () => {
+    const now = Date.now()
+    const ownerSkills = Array.from({ length: 5 }, (_, i) => ({
+      _id: `skills:${i}`,
+      createdAt: now - i * 10_000,
+    }))
+
+    const db = {
+      get: vi.fn(async () => ({
+        _id: 'users:owner',
+        _creationTime: now - 2 * 24 * 60 * 60 * 1000,
+        createdAt: now - 2 * 24 * 60 * 60 * 1000,
+        deletedAt: undefined,
+      })),
+      query: vi.fn((table: string) => {
+        const globalStatsQuery = buildGlobalStatsQuery(table)
+        if (globalStatsQuery) return globalStatsQuery
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name === 'by_slug') {
+                return { unique: async () => null }
+              }
+              if (name === 'by_owner') {
+                return {
+                  order: () => ({
+                    take: async () => ownerSkills,
+                  }),
+                }
+              }
+              throw new Error(`unexpected index ${name}`)
+            },
+          }
+        }
+        if (table === 'reservedSlugs') {
+          return {
+            withIndex: (name: string) => {
+              if (name === 'by_slug_active_deletedAt') {
+                return { order: () => ({ take: async () => [] }) }
+              }
+              throw new Error(`unexpected index ${name}`)
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+    }
+
+    await expect(
+      insertVersionHandler({ db } as never, createPublishArgs() as never),
+    ).rejects.toThrow(/max 5 new skills per hour/i)
+  })
+
+  it('returns a user-facing slug-taken message when publishing to another owner slug', async () => {
+    let authAccountLookupCount = 0
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'users:caller') return { _id: 'users:caller', deletedAt: undefined }
+        if (id === 'users:owner') {
+          return {
+            _id: 'users:owner',
+            handle: 'alice',
+            deletedAt: undefined,
+            deactivatedAt: undefined,
+          }
+        }
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_slug') throw new Error(`unexpected skills index ${name}`)
+              return {
+                unique: async () => ({
+                  _id: 'skills:1',
+                  slug: 'taken-skill',
+                  ownerUserId: 'users:owner',
+                  softDeletedAt: undefined,
+                  moderationStatus: 'active',
+                  moderationFlags: undefined,
+                }),
+              }
+            },
+          }
+        }
+        if (table === 'authAccounts') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'userIdAndProvider') throw new Error(`unexpected auth index ${name}`)
+              return {
+                unique: async () => {
+                  authAccountLookupCount += 1
+                  return authAccountLookupCount === 1
+                    ? { providerAccountId: 'owner-gh' }
+                    : { providerAccountId: 'caller-gh' }
+                },
+              }
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+    }
+
+    await expect(
+      insertVersionHandler(
+        { db } as never,
+        createPublishArgs({
+          userId: 'users:caller',
+          slug: 'taken-skill',
+        }) as never,
+      ),
+    ).rejects.toThrow('Slug is already taken. Choose a different slug. Existing skill: /alice/taken-skill')
+  })
+
+  it('does not include a URL in slug-taken message when conflicting owner is deleted', async () => {
+    let authAccountLookupCount = 0
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'users:caller') return { _id: 'users:caller', deletedAt: undefined }
+        if (id === 'users:owner') {
+          return {
+            _id: 'users:owner',
+            handle: 'alice',
+            deletedAt: Date.now(),
+            deactivatedAt: undefined,
+          }
+        }
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_slug') throw new Error(`unexpected skills index ${name}`)
+              return {
+                unique: async () => ({
+                  _id: 'skills:1',
+                  slug: 'taken-skill',
+                  ownerUserId: 'users:owner',
+                  softDeletedAt: undefined,
+                  moderationStatus: 'active',
+                  moderationFlags: undefined,
+                }),
+              }
+            },
+          }
+        }
+        if (table === 'authAccounts') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'userIdAndProvider') throw new Error(`unexpected auth index ${name}`)
+              return {
+                unique: async () => {
+                  authAccountLookupCount += 1
+                  return authAccountLookupCount === 1
+                    ? { providerAccountId: 'owner-gh' }
+                    : { providerAccountId: 'caller-gh' }
+                },
+              }
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+    }
+
+    await expect(
+      insertVersionHandler(
+        { db } as never,
+        createPublishArgs({
+          userId: 'users:caller',
+          slug: 'taken-skill',
+        }) as never,
+      ),
+    ).rejects.toThrow('Slug is already taken. Choose a different slug.')
+  })
+
+  it('keeps suspicious skills visible for low-trust publishers', async () => {
+    const patch = vi.fn(async () => {})
+    const version = { _id: 'skillVersions:1', skillId: 'skills:1' }
+    const skill = {
+      _id: 'skills:1',
+      slug: 'spam-skill',
+      ownerUserId: 'users:owner',
+      moderationFlags: undefined,
+      moderationReason: undefined,
+    }
+    const owner = {
+      _id: 'users:owner',
+      _creationTime: Date.now() - 2 * 24 * 60 * 60 * 1000,
+      createdAt: Date.now() - 2 * 24 * 60 * 60 * 1000,
+      deletedAt: undefined,
+    }
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'skills:1') return skill
+        if (id === 'users:owner') return owner
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        const globalStatsQuery = buildGlobalStatsQuery(table)
+        if (globalStatsQuery) return globalStatsQuery
+        if (table === 'skillVersions') {
+          return {
+            withIndex: () => ({
+              unique: async () => version,
+            }),
+          }
+        }
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name === 'by_owner') {
+                return {
+                  order: () => ({
+                    take: async () => [],
+                  }),
+                }
+              }
+              throw new Error(`unexpected skills index ${name}`)
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+    }
+
+    await approveSkillByHashHandler(
+      { db, scheduler: { runAfter: vi.fn() } } as never,
+      {
+        sha256hash: 'h'.repeat(64),
+        scanner: 'vt',
+        status: 'suspicious',
+      } as never,
+    )
+
+    expect(patch).toHaveBeenCalledWith(
+      'skills:1',
+      expect.objectContaining({
+        moderationStatus: 'active',
+        moderationReason: 'scanner.vt.suspicious',
+        moderationFlags: ['flagged.suspicious'],
+      }),
+    )
+  })
+
+  it('keeps admin-owned skills non-suspicious for suspicious scanner verdicts', async () => {
+    const patch = vi.fn(async () => {})
+    const version = { _id: 'skillVersions:1', skillId: 'skills:1' }
+    const skill = {
+      _id: 'skills:1',
+      slug: 'trusted-skill',
+      ownerUserId: 'users:owner',
+      moderationFlags: ['flagged.suspicious'],
+      moderationReason: 'scanner.vt.suspicious',
+    }
+    const owner = {
+      _id: 'users:owner',
+      role: 'admin',
+      _creationTime: Date.now() - 60 * 24 * 60 * 60 * 1000,
+      createdAt: Date.now() - 60 * 24 * 60 * 60 * 1000,
+      deletedAt: undefined,
+    }
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'skills:1') return skill
+        if (id === 'users:owner') return owner
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        const globalStatsQuery = buildGlobalStatsQuery(table)
+        if (globalStatsQuery) return globalStatsQuery
+        if (table === 'skillVersions') {
+          return {
+            withIndex: () => ({
+              unique: async () => version,
+            }),
+          }
+        }
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name === 'by_owner') {
+                return {
+                  order: () => ({
+                    take: async () => [],
+                  }),
+                }
+              }
+              throw new Error(`unexpected skills index ${name}`)
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+    }
+
+    await approveSkillByHashHandler(
+      { db, scheduler: { runAfter: vi.fn() } } as never,
+      {
+        sha256hash: 'h'.repeat(64),
+        scanner: 'llm',
+        status: 'suspicious',
+      } as never,
+    )
+
+    expect(patch).toHaveBeenCalledWith(
+      'skills:1',
+      expect.objectContaining({
+        moderationStatus: 'active',
+        moderationReason: 'scanner.llm.clean',
+        moderationFlags: undefined,
+      }),
+    )
+  })
+
+  it('vt suspicious escalation does not keep suspicious flags for admin owners', async () => {
+    const patch = vi.fn(async () => {})
+    const version = { _id: 'skillVersions:1', skillId: 'skills:1' }
+    const skill = {
+      _id: 'skills:1',
+      slug: 'trusted-skill',
+      ownerUserId: 'users:owner',
+      moderationFlags: ['flagged.suspicious'],
+      moderationReason: 'scanner.llm.suspicious',
+    }
+    const owner = {
+      _id: 'users:owner',
+      role: 'admin',
+      deletedAt: undefined,
+    }
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'skills:1') return skill
+        if (id === 'users:owner') return owner
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        const globalStatsQuery = buildGlobalStatsQuery(table)
+        if (globalStatsQuery) return globalStatsQuery
+        if (table === 'skillVersions') {
+          return {
+            withIndex: () => ({
+              unique: async () => version,
+            }),
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+    }
+
+    await escalateByVtHandler(
+      { db, scheduler: { runAfter: vi.fn() } } as never,
+      {
+        sha256hash: 'h'.repeat(64),
+        status: 'suspicious',
+      } as never,
+    )
+
+    expect(patch).toHaveBeenCalledWith(
+      'skills:1',
+      expect.objectContaining({
+        moderationFlags: undefined,
+        moderationReason: 'scanner.llm.clean',
+      }),
+    )
+  })
+
+  it('bulk-clears suspicious flags/reasons for privileged owner skills', async () => {
+    const patch = vi.fn(async () => {})
+    const owner = {
+      _id: 'users:owner',
+      role: 'admin',
+      deletedAt: undefined,
+    }
+    const skills = [
+      {
+        _id: 'skills:1',
+        moderationFlags: ['flagged.suspicious'],
+        moderationReason: 'scanner.vt.suspicious',
+        moderationStatus: 'hidden',
+        softDeletedAt: undefined,
+      },
+      {
+        _id: 'skills:2',
+        moderationFlags: undefined,
+        moderationReason: 'scanner.llm.clean',
+        moderationStatus: 'active',
+        softDeletedAt: undefined,
+      },
+    ]
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'users:owner') return owner
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        const globalStatsQuery = buildGlobalStatsQuery(table)
+        if (globalStatsQuery) return globalStatsQuery
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_owner') throw new Error(`unexpected skills index ${name}`)
+              return {
+                order: () => ({
+                  take: async () => skills,
+                }),
+              }
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+    }
+
+    const result = await clearOwnerSuspiciousFlagsHandler(
+      { db } as never,
+      { ownerUserId: 'users:owner', limit: 20 } as never,
+    )
+
+    expect(result).toEqual({ inspected: 2, updated: 1 })
+    expect(patch).toHaveBeenCalledWith(
+      'skills:1',
+      expect.objectContaining({
+        moderationFlags: undefined,
+        moderationReason: 'scanner.vt.clean',
+        moderationStatus: 'active',
+      }),
+    )
+  })
+})
@@ -0,0 +1,150 @@
+import { describe, expect, it, vi } from 'vitest'
+import { reclaimSlugInternal } from './skills'
+
+type WrappedHandler<TArgs> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<unknown>
+}
+
+const reclaimSlugInternalHandler = (
+  reclaimSlugInternal as unknown as WrappedHandler<Record<string, unknown>>
+)._handler
+
+describe('skills reclaim ownership transfer', () => {
+  it('transfers ownership in-place when transferRootSlugOnly is true', async () => {
+    const now = Date.now()
+    const patch = vi.fn(async () => {})
+    const insert = vi.fn(async () => {})
+    const runAfter = vi.fn(async () => {})
+
+    const existingSkill = {
+      _id: 'skills:1',
+      slug: 'capability-evolver',
+      ownerUserId: 'users:old',
+    }
+    const activeReservation = {
+      _id: 'reservedSlugs:1',
+      slug: 'capability-evolver',
+      originalOwnerUserId: 'users:old',
+      deletedAt: now - 1_000,
+      expiresAt: now + 10_000,
+    }
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'users:admin') return { _id: 'users:admin', role: 'admin' }
+        if (id === 'users:new') return { _id: 'users:new', role: 'user' }
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_slug') throw new Error(`unexpected skills index ${name}`)
+              return { unique: async () => existingSkill }
+            },
+          }
+        }
+        if (table === 'skillEmbeddings') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_skill') throw new Error(`unexpected embeddings index ${name}`)
+              return {
+                collect: async () => [{ _id: 'skillEmbeddings:1', skillId: 'skills:1', ownerId: 'users:old' }],
+              }
+            },
+          }
+        }
+        if (table === 'reservedSlugs') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_slug_active_deletedAt') {
+                throw new Error(`unexpected reservedSlugs index ${name}`)
+              }
+              return {
+                order: () => ({
+                  take: async () => [activeReservation],
+                }),
+              }
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+      insert,
+    }
+
+    const result = (await reclaimSlugInternalHandler(
+      { db, scheduler: { runAfter } } as never,
+      {
+        actorUserId: 'users:admin',
+        slug: 'Capability-Evolver',
+        rightfulOwnerUserId: 'users:new',
+        transferRootSlugOnly: true,
+      } as never,
+    )) as { ok: boolean; action: string }
+
+    expect(result).toEqual({ ok: true, action: 'ownership_transferred' })
+    expect(runAfter).not.toHaveBeenCalled()
+    expect(patch).toHaveBeenCalledWith(
+      'skills:1',
+      expect.objectContaining({
+        ownerUserId: 'users:new',
+      }),
+    )
+    expect(patch).toHaveBeenCalledWith(
+      'skillEmbeddings:1',
+      expect.objectContaining({
+        ownerId: 'users:new',
+      }),
+    )
+    expect(patch).toHaveBeenCalledWith(
+      'reservedSlugs:1',
+      expect.objectContaining({
+        releasedAt: expect.any(Number),
+      }),
+    )
+  })
+
+  it('returns missing without reserving when transferRootSlugOnly is true and slug does not exist', async () => {
+    const insert = vi.fn(async () => {})
+    const patch = vi.fn(async () => {})
+    const runAfter = vi.fn(async () => {})
+
+    const db = {
+      get: vi.fn(async (id: string) => {
+        if (id === 'users:admin') return { _id: 'users:admin', role: 'admin' }
+        if (id === 'users:new') return { _id: 'users:new', role: 'user' }
+        return null
+      }),
+      query: vi.fn((table: string) => {
+        if (table === 'skills') {
+          return {
+            withIndex: (name: string) => {
+              if (name !== 'by_slug') throw new Error(`unexpected skills index ${name}`)
+              return { unique: async () => null }
+            },
+          }
+        }
+        throw new Error(`unexpected table ${table}`)
+      }),
+      patch,
+      insert,
+    }
+
+    const result = (await reclaimSlugInternalHandler(
+      { db, scheduler: { runAfter } } as never,
+      {
+        actorUserId: 'users:admin',
+        slug: 'missing-slug',
+        rightfulOwnerUserId: 'users:new',
+        transferRootSlugOnly: true,
+      } as never,
+    )) as { ok: boolean; action: string }
+
+    expect(result).toEqual({ ok: true, action: 'missing' })
+    expect(runAfter).not.toHaveBeenCalled()
+    expect(patch).not.toHaveBeenCalled()
+  })
+})
+
--- a/Show More
+++ b/Show More