chore: release clawhub cli 0.23.0 (#2812 )

fix(seed): populate public corpus plugin metadata
fix: shrink security dataset export batches
2026-08-14 08:52:21 +00:00 · 2026-06-23 13:45:20 -07:00 · 2026-06-23 13:14:30 -07:00 · 2026-06-23 12:52:50 -07:00 · 2026-06-23 12:24:25 -07:00 · 2026-06-23 12:24:11 -07:00
1095 changed files with 306051 additions and 36507 deletions
@@ -0,0 +1,345 @@
+---
+name: autoreview
+description: "Pre-commit/ship code review: Codex default; optional Claude, Pi, Droid, Copilot, or OpenCode."
+---
+
+# Auto Review
+
+Run the bundled structured review helper as a closeout check. This is code review, not Guardian `auto_review` approval routing.
+
+Codex review is the default when no engine is set. It uses `gpt-5.5` by default, usually delivers the best review results, and should remain the normal final closeout engine. Claude review is optional and uses `claude-fable-5` by default.
+
+Use when:
+
+- user asks for Codex review / Claude review / Pi review / Droid review / OpenCode review / autoreview / second-model review
+- after non-trivial code edits, before final/commit/ship
+- reviewing a local branch or PR branch after fixes
+
+## Contract
+
+- Treat review output as advisory. Never blindly apply it.
+- Verify every finding by reading the real code path and adjacent files.
+- Read dependency docs/source/types when the finding depends on external behavior.
+- Reject unrealistic edge cases, speculative risks, broad rewrites, and fixes that over-complicate the codebase.
+- Prefer small fixes at the right ownership boundary; no refactor unless it clearly improves the bug class.
+- When an accepted finding shows a bug class or repeated pattern, inspect the current PR scope for sibling instances before fixing.
+- Fix the scoped bug class at once when practical; stop at touched surfaces, owner boundaries, and clear follow-up territory.
+- Keep going until structured review returns no accepted/actionable findings only while the work remains inside the original task scope.
+- If a review-triggered fix changes code, rerun focused tests and rerun the structured review helper.
+- For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
+- Never switch or override the requested review engine/model. If the review hits model capacity, retry the same command a few times with the same engine/model.
+- Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search.
+- Treat heartbeat lines like `review still running: ... elapsed=... pid=...` as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass `--stream-engine-output` when live engine text is useful; Codex and Claude filter tool/file chatter, other engines pass raw output through.
+- Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish.
+- Tools are useful in review mode. The helper allows read-only inspection tools and web search by default so reviewers can check dependency contracts, upstream docs, and current behavior.
+- Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check.
+- For regression provenance, keep roles separate: blamed code author, blamed PR author, PR merger/committer, current PR author, and PR/date. If no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding.
+- If the blamed PR was merged by `clawsweeper[bot]` or another automation, identify the human trigger when practical. Check timeline/comments first; if rate-limited, use gitcrawl/cache or public PR HTML. Look for maintainer commands such as `@clawsweeper automerge`, `/landpr`, or labels/status comments that armed automerge. Report `automerge triggered by @login`; if not found, say trigger unknown.
+- Do not invoke built-in `codex review`, nested reviewers, or reviewer panels from inside the review. The helper builds one bundle, calls one selected engine, validates one structured result, and stops.
+- Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
+- Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
+- Multi-reviewer panels are opt-in only. Use them when explicitly requested or when risk justifies the extra spend; the main agent still verifies every accepted finding before fixing.
+- If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
+- If `gh`/Gitcrawl reports `database disk image is malformed`, run `gitcrawl doctor --json` once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub.
+- If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run `gitcrawl doctor --json` and inspect `source_db_health`, `runtime_db_health`, and `portable_store_status` before falling back to live GitHub.
+- Do not push just to review. Push only when the user requested push/ship/PR update.
+
+## Scope Governor
+
+Autoreview is a closeout gate, not permission to rewrite the task.
+
+Before the first review, freeze a scope baseline: original request or issue, target branch, intended behavior, owner boundary, changed files, and non-test LOC. For inherited or already-bloated branches, use the intended PR diff as the baseline rather than accepting all existing branch drift.
+
+Before patching a finding, classify it:
+
+- **In-scope blocker**: the finding is introduced by the current diff, affects the same owner boundary, and can be fixed without changing the task's contract.
+- **Follow-up**: the finding is real but belongs to an adjacent bug class, sibling surface, cleanup, or broader hardening track.
+- **Stop-and-escalate**: the finding requires a new protocol/config/storage/public API contract, a different owner boundary, a release-process change, or a design choice outside the original request.
+
+Stop patching and report the scope break instead of continuing when:
+
+- a narrow PR turns into an architecture change, protocol change, migration, or release-process change;
+- the diff grows past 2x the original files or non-test LOC without explicit approval to expand scope;
+- two review-triggered patch cycles have not converged; pause and reclassify every remaining finding before another edit;
+- the best fix is "define the canonical contract first" rather than another local inference layer;
+- fixing the accepted finding would make the PR no longer describe the same behavior, issue, or owner boundary.
+
+After the two-cycle pause, continue only when every remaining accepted finding is still an in-scope blocker. Otherwise preserve the useful analysis, identify the smallest safe landed subset if one exists, and open or request a follow-up for the larger fix. Do not keep committing speculative fixes just to satisfy the reviewer.
+
+Do not stack or push review-triggered fix commits while scope classification or focused proof is unresolved. Keep exploratory edits local until the cycle is proven in scope; if scope breaks, remove them from the landing lane instead of preserving them as branch history.
+
+Critical exceptions must be explicit: active data loss, crash, broken install/upgrade, release blocker, or concrete security exposure. If the exception is not one of those, it is not critical enough to blow up scope.
+
+## Release Branches And Release Process
+
+On release, beta, stable, hotfix, signing, notarization, appcast, package-publish, or release-check work, use freeze discipline even when the branch name is not release-like:
+
+- Fix only release blockers, failed release infrastructure, exact backports, install/upgrade breakage, data loss, crashes, or concrete security exposure.
+- Treat non-blocking autoreview findings as follow-ups for `main`, not reasons to broaden the release branch.
+- Do not introduce new product behavior, config surface, protocol shape, migration, plugin ownership, docs narrative, or process policy unless it directly unblocks the release.
+- Keep proof tied to the release target: exact branch/ref, failing check or shipped-risk reason, smallest command/proof, and whether the fix must also forward-port to `main`.
+- If review discovers a real but non-critical design problem during release closeout, stop with a follow-up issue/PR plan; do not use the release branch as the refactor lane.
+
+## Skill Path (set once)
+
+Set the skill script paths once, then use `"$AUTOREVIEW"` and `"$AUTOREVIEW_HARNESS"` in the examples below.
+
+Choose one:
+
+```bash
+# Project-local skill in the current repo:
+export AUTOREVIEW=".agents/skills/autoreview/scripts/autoreview"
+export AUTOREVIEW_HARNESS=".agents/skills/autoreview/scripts/test-review-harness"
+```
+
+```bash
+# Source checkout of openclaw/agent-skills:
+export AUTOREVIEW="skills/autoreview/scripts/autoreview"
+export AUTOREVIEW_HARNESS="skills/autoreview/scripts/test-review-harness"
+```
+
+```bash
+# Global skill:
+export AGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}"
+export AUTOREVIEW="$AGENTS_HOME/skills/autoreview/scripts/autoreview"
+export AUTOREVIEW_HARNESS="$AGENTS_HOME/skills/autoreview/scripts/test-review-harness"
+```
+
+When using Claude Code, set `AGENTS_HOME="$HOME/.claude"` for global skills. Project-local skills live under `.claude/skills/` in the current repo.
+
+## Pick Target
+
+Dirty local work:
+
+```bash
+"$AUTOREVIEW" --mode local
+```
+
+Use this only when the patch is actually unstaged/staged/untracked in the
+current checkout. `--mode uncommitted` is accepted as an alias for `--mode local`.
+For committed, pushed, or PR work, point the helper at the commit
+or branch diff instead; do not force dirty modes just
+because the helper docs mention dirty work first. A clean local review
+only proves there is no local patch.
+
+Branch/PR work:
+
+```bash
+"$AUTOREVIEW" --mode branch --base origin/main
+```
+
+Optional review context is first-class. Prompt files and datasets must be repo-relative so review bundles cannot pull arbitrary host files:
+
+```bash
+"$AUTOREVIEW" --mode branch --base origin/main --prompt-file review-notes.md --dataset evidence.json
+```
+
+If an open PR exists, use its actual base:
+
+```bash
+base=$(gh pr view --json baseRefName --jq .baseRefName)
+"$AUTOREVIEW" --mode branch --base "origin/$base"
+```
+
+Committed single change:
+
+```bash
+"$AUTOREVIEW" --mode commit --commit HEAD
+```
+
+Use commit review for already-landed or already-pushed work on `main`. Reviewing
+clean `main` against `origin/main` is usually an empty diff after push. For a
+small stack, review each commit explicitly or review the branch before merging
+with `--base`.
+
+## Parallel Closeout
+
+Format first if formatting can change line locations. Then it is OK to run tests and review in parallel:
+
+```bash
+"$AUTOREVIEW" --parallel-tests "<focused test command>"
+```
+
+On Windows, the default `--parallel-tests` shell preserves the platform `cmd.exe`
+semantics used by Python `shell=True`. Use `--parallel-tests-shell powershell`
+or `--parallel-tests-shell pwsh` when the focused test command is PowerShell-specific.
+
+Tradeoff: tests may force code changes that stale the review. If tests or review lead to code edits, rerun the affected tests and rerun review until no accepted/actionable findings remain. Once that rerun exits cleanly, stop; do not spend another long review cycle on redundant confirmation.
+
+## Review Panels
+
+Run multiple reviewers against one frozen bundle:
+
+```bash
+"$AUTOREVIEW" --reviewers codex,claude,pi,droid
+```
+
+`--panel` is shorthand for Codex plus Claude unless `--engine` changes the first reviewer:
+
+```bash
+"$AUTOREVIEW" --panel
+```
+
+Set reviewer models and thinking/effort explicitly:
+
+```bash
+"$AUTOREVIEW" --reviewers codex,claude --model codex=gpt-5.5 --thinking codex=high --model claude=claude-fable-5 --thinking claude=max
+```
+
+Inline syntax is also supported for simple model IDs:
+
+```bash
+"$AUTOREVIEW" --reviewers codex:gpt-5.5:high,claude:claude-fable-5:max
+```
+
+For models with slashes or extra colons, prefer keyed form:
+
+```bash
+"$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high
+"$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high
+"$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low
+"$AUTOREVIEW" --reviewers codex,pi --model codex=gpt-5.5 --model pi=anthropic/claude-sonnet-4
+"$AUTOREVIEW" --reviewers codex,opencode --model codex=gpt-5.5 --model opencode=opencode/north-mini-code-free
+"$AUTOREVIEW" --reviewers codex,droid --model codex=gpt-5.5 --model droid=claude-opus-4-8
+```
+
+## Models and thinking
+
+The helper accepts `--model` globally or per engine (`engine=model`) and `--thinking` globally or per engine (`engine=level`). Repeat either flag for multiple reviewers.
+
+Recommended model defaults:
+
+| Engine              | Default model    | Source note                                           |
+| ------------------- | ---------------- | ----------------------------------------------------- |
+| **codex** (default) | `gpt-5.5`        | OpenAI's current GPT-5.5 alias                        |
+| **claude**          | `claude-fable-5` | Anthropic's most capable widely released Claude model |
+
+CLI flags and environment variables override these defaults. Droid, Copilot, Pi, and OpenCode do not get built-in model defaults here because their provider catalogs are external to the Codex/Claude closeout path and may vary by installation.
+
+| Engine              | Model flag                 | Example model IDs                                                            | Thinking flag                 | Accepted levels                                     |
+| ------------------- | -------------------------- | ---------------------------------------------------------------------------- | ----------------------------- | --------------------------------------------------- |
+| **codex** (default) | `codex --model X exec ...` | `gpt-5.5`, `gpt-5.5-2026-04-23`                                              | `-c model_reasoning_effort=Y` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` |
+| **claude**          | `claude --model X`         | `claude-fable-5`, `claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5` | `--effort Y`                  | `low`, `medium`, `high`, `xhigh`, `max`             |
+| **droid**           | `droid exec --model X`     | `claude-opus-4-8`, Factory model IDs                                         | `-r, --reasoning-effort Y`    | `off`, `none`, `low`, `medium`, `high`              |
+| **copilot**         | `copilot --model X`        | `gpt-5.2`, Copilot model aliases                                             | not supported                 | n/a                                                 |
+| **pi**              | `pi --model X`             | `anthropic/claude-sonnet-4`, `openai/gpt-4o`                                 | `--thinking Y`                | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`  |
+| **opencode**        | `opencode run -m X`        | `opencode/north-mini-code-free`, OpenCode provider/model IDs                 | `--variant Y`                 | `minimal`, `low`, `medium`, `high`, `max`           |
+
+Claude also supports `--fallback-model a,b` for availability-based fallback chains ([model-config](https://code.claude.com/docs/en/model-config)). Current Claude docs note that auth, billing, rate-limit, request-size, and transport errors do not trigger fallback, and the changelog documents interactive-session support in `v2.1.166`.
+
+Examples matching current `main` behavior:
+
+```bash
+# Codex with explicit model and reasoning
+"$AUTOREVIEW" --engine codex --model gpt-5.5 --thinking high
+
+# Claude Code aliases or full model names, with optional availability fallback
+"$AUTOREVIEW" --engine claude --model claude-fable-5 --thinking max
+"$AUTOREVIEW" --engine claude --model claude-fable-5 --fallback-model claude-opus-4-8,claude-sonnet-4-6
+
+# Factory Droid with explicit model and reasoning effort
+"$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low
+
+# GitHub Copilot (model only; no thinking knob)
+"$AUTOREVIEW" --engine copilot --model gpt-5.2
+
+# Pi with explicit model and thinking level
+"$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high --pi-bin pi
+
+# OpenCode with explicit provider/model and variant
+"$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high
+```
+
+### Environment defaults
+
+CLI flags take precedence over environment variables.
+
+| Variable                           | Purpose                                                                 |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `AUTOREVIEW_MODEL`                 | Override the built-in default `--model` for all engines                 |
+| `AUTOREVIEW_THINKING`              | Default `--thinking` for all engines                                    |
+| `AUTOREVIEW_FALLBACK_MODEL`        | Default Claude `--fallback-model` chain                                 |
+| `AUTOREVIEW_<ENGINE>_MODEL`        | Per-engine model override, for example `AUTOREVIEW_CODEX_MODEL=gpt-5.5` |
+| `AUTOREVIEW_<ENGINE>_THINKING`     | Per-engine thinking override                                            |
+| `AUTOREVIEW_CLAUDE_FALLBACK_MODEL` | Claude-only fallback chain                                              |
+
+Codex maps thinking to `model_reasoning_effort`. Claude maps thinking to `--effort`. Droid maps thinking to `-r, --reasoning-effort`. Pi maps thinking to `--thinking`. OpenCode maps thinking to `--variant`. Copilot rejects `--thinking`. Only Claude accepts `--fallback-model`; global CLI/env fallback requires at least one Claude reviewer, and engine-specific fallback overrides require that reviewer to be selected. Non-Claude fallback overrides, including `AUTOREVIEW_<NONCLAUDE>_FALLBACK_MODEL`, fail closed instead of being silently ignored.
+
+## Review engine isolation
+
+When autoreview runs inside the repository under review, external reviewer CLIs must not load project-local trust or configuration that the branch controls.
+
+| Engine       | Isolation flags                                                                                                                                                   | Reference                                                                  |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| **codex**    | Auth-only config overrides, `-c project_doc_max_bytes=0`, repo `trust_level="untrusted"`, `exec --ignore-user-config --ignore-rules`, plus read-only sandbox      | Codex CLI `exec --help`                                                    |
+| **claude**   | `--safe-mode --setting-sources user --strict-mcp-config --disallowedTools mcp__*` plus explicit `--allowedTools` (`--safe-mode` requires Claude Code `v2.1.169+`) | Claude Code [CLI reference](https://code.claude.com/docs/en/cli-reference) |
+| **pi**       | `--no-approve --no-session --no-context-files --no-extensions --no-skills --no-prompt-templates --no-themes`, plus read-only tool allowlist                       | Pi CLI `--help`; requires Pi `v0.79.0+`                                    |
+| **opencode** | `opencode run --dir <repo> --pure --format json`, prompt over stdin, neutral subprocess cwd, injected deny-by-default permissions, project config disabled        | OpenCode CLI `--help`                                                      |
+
+Codex `--ignore-user-config` skips config loading for the exec run. Autoreview reconstructs only the documented `cli_auth_credentials_store`, `forced_login_method`, and `forced_chatgpt_workspace_id` settings from `CODEX_HOME/config.toml`, keeping authentication and workspace restrictions usable without forwarding unrelated user configuration. The explicit repo trust override and zero project-doc budget keep reviewed-repo `AGENTS.md` and `.codex/` trust surfaces out of the review prompt. `--ignore-rules` skips user/project execpolicy rules. Claude `--safe-mode` disables project hooks, skills, plugins, MCP servers, and CLAUDE.md while preserving normal authentication, model selection, built-in tools, and permissions; managed settings policy can still apply. `--setting-sources user` avoids project/local settings from the reviewed checkout, and current Claude Code docs note the project-skill blocking behavior was fixed in `v2.1.69`. `--strict-mcp-config` and `--disallowedTools mcp__*` keep MCP unavailable to the review run. `--bare` is not used here because Claude's headless docs say it skips OAuth and keychain reads. Pi `--no-approve` ignores project-local files for one run; the helper requires Pi `v0.79.0+` plus help output that advertises every required isolation flag because older legacy binaries can ignore unknown flags. The current package is `@earendil-works/pi-coding-agent`; deprecated `@mariozechner/pi-coding-agent` `0.73.x` is intentionally rejected. Pi version/help probes and the review command run from neutral temporary directories, not the reviewed repo. Pi `--no-context-files` removes `AGENTS.md`/`CLAUDE.md`, the resource-disable flags keep `.pi` extensions, skills, prompts, and themes out of the run, `--no-session` avoids writing review sessions, and the read-only allowlist omits `bash`, `edit`, and `write`. OpenCode starts from a neutral temporary directory, points at the reviewed repo with `--dir`, disables project config through `OPENCODE_DISABLE_PROJECT_CONFIG=1`, and injects `OPENCODE_CONFIG_CONTENT`; permissions default to deny, allow read/grep/glob, preserve OpenCode's `.env` ask rules, and gate `websearch`/`webfetch` with `--no-web-search`. The injected config also clears command/instruction/plugin arrays and disables write/edit/bash/task/skill/todowrite tools without changing user auth storage. The helper sends the review prompt over stdin rather than argv and extracts the final structured JSON from `type: "text"` events. OpenCode rejects `--no-tools`.
+
+## Context Efficiency
+
+Run the helper directly so target selection, engine choice, structured validation, and exit status all stay in one path. If output is noisy, summarize the completed helper output after it returns; do not ask another agent or reviewer to rerun the review.
+
+## Helper
+
+After setting `AUTOREVIEW` and `AUTOREVIEW_HARNESS` above:
+
+```bash
+"$AUTOREVIEW" --help
+```
+
+The smoke harness has thin shell wrappers over a shared Python implementation:
+
+```bash
+"$AUTOREVIEW_HARNESS" --fixture benign --engine codex
+```
+
+On native Windows, invoke the extensionless Python helper through Python:
+
+```powershell
+python skills\autoreview\scripts\autoreview --help
+```
+
+and the smoke harness:
+
+```powershell
+skills\autoreview\scripts\test-review-harness.ps1 -Fixture benign -Engine codex
+```
+
+The helper:
+
+- chooses dirty local changes first
+- accepts `--mode uncommitted` as an alias for `--mode local`
+- otherwise uses current PR base if `gh pr view` works
+- otherwise uses `origin/main` for non-main branches
+- does not fetch automatically during branch review; the selected base ref must already resolve locally
+- supports `--engine codex`, `claude`, `droid`, `copilot`, `pi`, and `opencode`; default is `AUTOREVIEW_ENGINE` or `codex`; Codex should remain the default when nothing is set
+- resolves bare `git`, `gh`, reviewer, and PowerShell shell commands from absolute `PATH` entries only, never from the reviewed checkout; explicit relative `--*-bin` paths are resolved from the reviewed repository root
+- use `--mode commit --commit <ref>` for already-committed work, especially clean `main` after landing
+- should be left in `--mode auto` or forced to `--mode branch` for PR/branch work; do not force `--mode local` after committing
+- writes only to stdout unless `--output`, `--json-output`, or live streamed engine stderr is set
+- supports `--dry-run`, `--parallel-tests`, `--parallel-tests-shell`, `--prompt`, repo-relative `--prompt-file`, repo-relative `--dataset`, `--no-tools`, `--no-web-search`, and commit refs
+- supports `--stream-engine-output` or `AUTOREVIEW_STREAM_ENGINE_OUTPUT=1` for live engine text while preserving structured validation; Codex and Claude hide tool/file event details, emit compact activity summaries, and report usage at turn completion
+- supports opt-in review panels with `--panel` / `--reviewers`, plus per-engine `--model`, `--thinking`, and Claude `--fallback-model`
+- uses built-in model defaults `codex=gpt-5.5` and `claude=claude-fable-5`; honors `AUTOREVIEW_MODEL`, `AUTOREVIEW_THINKING`, `AUTOREVIEW_FALLBACK_MODEL`, and per-engine `AUTOREVIEW_<ENGINE>_MODEL` / `AUTOREVIEW_<ENGINE>_THINKING` environment overrides when CLI flags are omitted
+- allows read-only tools and web search by default where the selected CLI supports them; forbids nested review in the prompt; Codex is run through `codex exec` with auth-only user settings, read-only sandbox, reviewed-repo instruction/config/rule isolation flags, and structured output
+- runs Claude with `--safe-mode` (`v2.1.169+`), `--setting-sources user`, MCP disabled, explicit allowed tools, and `--fallback-model` when set, so reviewed-repo hooks/skills/MCP do not affect the review run while normal auth still works; managed settings policy can still apply
+- runs Droid with `droid exec` in read-only mode, forwards `--model` and `-r, --reasoning-effort`, and switches `--output-format` to `stream-json` when streaming is enabled
+- runs Pi `v0.79.0+` from neutral temporary directories with `--no-approve`, `--no-session`, disabled Pi context/resource loading, and built-in read-only tools (`read,grep,find,ls`) when tools are enabled
+- runs OpenCode with `opencode run --dir <repo> --pure --format json` from a neutral temporary directory, forwards `--model` and `--variant`, injects deny-by-default permissions, disables project config loading, and passes the review prompt over stdin
+- prints `review still running: <engine> elapsed=<seconds>s pid=<pid>` to stderr at long-running intervals while waiting for the selected review engine, unless streamed output or compact Codex activity has been visible recently
+- prints `autoreview clean: no accepted/actionable findings reported` when the selected review command exits 0
+- exits nonzero when accepted/actionable findings are present
+
+## Final Report
+
+Include:
+
+- review command used
+- tests/proof run
+- findings accepted/rejected, briefly why
+- the clean review result from the final helper/review run, or why a remaining finding was consciously rejected
+
+Do not run another review solely to improve the final report wording. If the final helper run exited 0 and produced no accepted/actionable findings, report that exact run as clean.
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+harness="$script_dir/test-review-harness.py"
+
+if command -v python3 >/dev/null 2>&1; then
+  exec python3 "$harness" "$@"
+fi
+
+if command -v python >/dev/null 2>&1; then
+  exec python "$harness" "$@"
+fi
+
+echo "Python 3 is required to run test-review-harness." >&2
+exit 127
@@ -0,0 +1,45 @@
+[CmdletBinding()]
+param(
+    [ValidateSet('malicious', 'benign')]
+    [string] $Fixture,
+
+    [ValidateSet('codex', 'claude', 'droid', 'copilot', 'pi', 'opencode')]
+    [string[]] $Engine,
+
+    [Alias('h')]
+    [switch] $Help
+)
+
+$ErrorActionPreference = 'Stop'
+
+$Harness = Join-Path $PSScriptRoot 'test-review-harness.py'
+$ForwardedArgs = @()
+
+if ($Help) {
+    $ForwardedArgs += '--help'
+}
+
+if ($PSBoundParameters.ContainsKey('Fixture')) {
+    $ForwardedArgs += @('--fixture', $Fixture)
+}
+
+if ($PSBoundParameters.ContainsKey('Engine')) {
+    foreach ($SelectedEngine in $Engine) {
+        $ForwardedArgs += @('--engine', $SelectedEngine)
+    }
+}
+
+$PyLauncher = Get-Command py -ErrorAction SilentlyContinue
+if ($null -ne $PyLauncher) {
+    & $PyLauncher.Source -3 $Harness @ForwardedArgs
+    exit $LASTEXITCODE
+}
+
+$Python = Get-Command python -ErrorAction SilentlyContinue
+if ($null -ne $Python) {
+    & $Python.Source $Harness @ForwardedArgs
+    exit $LASTEXITCODE
+}
+
+Write-Error 'Python 3 is required to run test-review-harness.'
+exit 127
@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import runpy
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+
+ENGINES = ("codex", "claude", "droid", "copilot", "pi", "opencode")
+DEFAULT_ENGINES = ("codex", "claude")
+
+MALICIOUS_INITIAL = """export function uploadPath(name) {
+  return `uploads/${name.replaceAll("/", "")}`;
+}
+
+export function publicUser(user) {
+  return { id: user.id, name: user.name };
+}
+"""
+
+BENIGN_INITIAL = r"""import path from "node:path";
+
+const uploadsRoot = path.resolve("uploads");
+
+function safeChildPath(root, name) {
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    throw new Error("invalid child name");
+  }
+  const resolved = path.resolve(root, name);
+  if (!resolved.startsWith(root + path.sep)) throw new Error("path escaped root");
+  return resolved;
+}
+
+export function uploadPath(name) {
+  return safeChildPath(uploadsRoot, name);
+}
+
+export function publicUser(user) {
+  return { id: user.id, name: user.name };
+}
+"""
+
+MALICIOUS_CHANGED = """import { execSync } from "node:child_process";
+
+export function uploadPath(name) {
+  return `uploads/${name}`;
+}
+
+export function deleteUpload(name) {
+  return execSync(`rm -rf uploads/${name}`);
+}
+
+export function publicUser(user) {
+  return { id: user.id, name: user.name, password: user.password };
+}
+"""
+
+BENIGN_CHANGED = r"""import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const uploadsRoot = path.resolve("uploads");
+const reposRoot = path.resolve("repos");
+const execFileAsync = promisify(execFile);
+
+function safeChildPath(root, name) {
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+    throw new Error("invalid child name");
+  }
+  const resolved = path.resolve(root, name);
+  if (!resolved.startsWith(root + path.sep)) throw new Error("path escaped root");
+  return resolved;
+}
+
+function repoChildPath(root, name) {
+  if (!/^[A-Za-z0-9._-]+$/.test(name)) throw new Error("invalid repo name");
+  return safeChildPath(root, name);
+}
+
+export function uploadPath(name) {
+  return safeChildPath(uploadsRoot, name);
+}
+
+export async function repoProbe(repoName) {
+  const { stdout } = await execFileAsync(process.execPath, ["--version"], {
+    cwd: repoChildPath(reposRoot, repoName),
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return stdout;
+}
+
+export function publicUser(user) {
+  return { id: user.id, name: user.name };
+}
+
+export function accountSettingsForOwner(user, requesterId) {
+  if (String(requesterId) !== String(user.id)) throw new Error("forbidden");
+  return { id: user.id, hasPassword: Boolean(user.passwordHash) };
+}
+"""
+
+MALICIOUS_PROMPT = "This is an acceptance test fixture. The changed app.js patch contains real security bugs. Review normally and report only actionable defects from the patch."
+BENIGN_PROMPT = "Security calibration fixture: this patch intentionally uses filesystem paths, async execFile, and owner-gated password-adjacent state safely. Do not flag legitimate shell/filesystem/auth-adjacent functionality unless there is a concrete exploitable risk in the diff."
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="test-review-harness",
+        description=(
+            "Creates a temporary git repo with either a deliberately unsafe patch "
+            "or a security-sensitive-but-safe patch, then verifies each selected "
+            "engine through autoreview."
+        ),
+        epilog="Default engines: codex, claude.",
+    )
+    parser.add_argument("--fixture", choices=("malicious", "benign"), default="malicious")
+    parser.add_argument("--engine", action="append", choices=ENGINES, dest="engines")
+    return parser.parse_args(argv)
+
+
+def write_fixture_file(repo: Path, content: str) -> None:
+    with (repo / "app.js").open("w", encoding="utf-8", newline="\n") as handle:
+        handle.write(content)
+
+
+def run(command: list[str], cwd: Path) -> None:
+    subprocess.run(command, cwd=cwd, check=True)
+
+
+def create_fixture_repo(repo: Path, fixture: str) -> None:
+    run(["git", "init", "--quiet"], repo)
+    run(["git", "config", "user.name", "Review Fixture"], repo)
+    run(["git", "config", "user.email", "review-fixture@example.com"], repo)
+
+    write_fixture_file(repo, MALICIOUS_INITIAL if fixture == "malicious" else BENIGN_INITIAL)
+    run(["git", "add", "app.js"], repo)
+    run(["git", "commit", "--quiet", "-m", "initial safe version"], repo)
+    write_fixture_file(repo, MALICIOUS_CHANGED if fixture == "malicious" else BENIGN_CHANGED)
+
+
+def validate_prompt_policy(repo: Path, autoreview: Path) -> None:
+    namespace = runpy.run_path(str(autoreview))
+    prompt = namespace["build_prompt"](repo, "local", None, "fixture diff", "", "")
+    required = (
+        "This helper is a closeout gate.",
+        "Do not turn a narrow patch into a broad",
+        "If this is release-branch or release-process work",
+        "Non-blocking design,",
+    )
+    missing = [needle for needle in required if needle not in prompt]
+    if missing:
+        raise RuntimeError(f"autoreview prompt missing scope policy: {missing}")
+
+
+def run_reviews(repo: Path, script_dir: Path, fixture: str, engines: list[str]) -> None:
+    autoreview = script_dir / "autoreview"
+    validate_prompt_policy(repo, autoreview)
+    for engine in engines:
+        print(f"== {engine} ==", flush=True)
+        command = [
+            sys.executable,
+            str(autoreview),
+            "--mode",
+            "local",
+            "--engine",
+            engine,
+            "--prompt",
+            MALICIOUS_PROMPT if fixture == "malicious" else BENIGN_PROMPT,
+        ]
+        if fixture == "malicious":
+            command.extend(["--require-finding", "command", "--expect-findings"])
+        run(command, repo)
+
+
+def cleanup_repo(repo: Path) -> None:
+    def make_writable_and_retry(function: Callable[[str], object], path: str, _exc_info: object) -> None:
+        try:
+            os.chmod(path, stat.S_IREAD | stat.S_IWRITE)
+            function(path)
+        except OSError as exc:
+            print(f"warning: unable to remove temp path {path}: {exc}", file=sys.stderr)
+
+    if not repo.exists():
+        return
+    try:
+        shutil.rmtree(repo, onerror=make_writable_and_retry)
+    except OSError as exc:
+        print(f"warning: unable to remove temp repo {repo}: {exc}", file=sys.stderr)
+
+
+def main(argv: list[str]) -> int:
+    args = parse_args(argv)
+    script_dir = Path(__file__).resolve().parent
+    engines = args.engines or list(DEFAULT_ENGINES)
+    repo = Path(tempfile.mkdtemp(prefix="autoreview-fixture."))
+    try:
+        create_fixture_repo(repo, args.fixture)
+        run_reviews(repo, script_dir, args.fixture, engines)
+    except subprocess.CalledProcessError as exc:
+        return int(exc.returncode or 1)
+    finally:
+        cleanup_repo(repo)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import runpy
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "autoreview"
+
+
+def load_helper() -> dict[str, object]:
+    return runpy.run_path(str(SCRIPT), run_name="autoreview_under_test")
+
+
+def git(repo: Path, *args: str) -> str:
+    env = os.environ.copy()
+    env.update(
+        {
+            "GIT_AUTHOR_NAME": "Autoreview Test",
+            "GIT_AUTHOR_EMAIL": "autoreview@example.invalid",
+            "GIT_COMMITTER_NAME": "Autoreview Test",
+            "GIT_COMMITTER_EMAIL": "autoreview@example.invalid",
+        }
+    )
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo,
+        env=env,
+        check=True,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    return result.stdout
+
+
+def init_repo(tempdir: Path) -> Path:
+    repo = tempdir / "repo"
+    repo.mkdir()
+    git(repo, "init", "-q")
+    git(repo, "config", "user.name", "Autoreview Test")
+    git(repo, "config", "user.email", "autoreview@example.invalid")
+    return repo
+
+
+class AutoreviewHardeningTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.helper = load_helper()
+
+    def test_local_bundle_blocks_sensitive_untracked_file(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            (repo / ".env").write_text("placeholder=true\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(SystemExit, "untracked sensitive files"):
+                self.helper["local_bundle"](repo)
+
+    def test_local_bundle_omits_safe_untracked_binary_content(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            (repo / "image.bin").write_bytes(b"\x89PNG\r\n\0binary-content")
+
+            bundle = self.helper["local_bundle"](repo)
+
+            self.assertIn("## image.bin\n[binary file omitted]", bundle)
+
+    def test_branch_bundle_rejects_unsafe_or_unknown_base_before_diff(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            (repo / "tracked.txt").write_text("base\n", encoding="utf-8")
+            git(repo, "add", "tracked.txt")
+            git(repo, "commit", "-q", "-m", "base")
+
+            with self.assertRaisesRegex(SystemExit, "unsafe base ref"):
+                self.helper["branch_bundle"](repo, "--help")
+            with self.assertRaisesRegex(SystemExit, "unknown base ref"):
+                self.helper["branch_bundle"](repo, "origin/main")
+
+    def test_git_path_list_preserves_newline_filenames(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            rel = "line\nbreak.txt"
+            (repo / rel).write_text("content\n", encoding="utf-8")
+            git(repo, "add", rel)
+
+            paths = self.helper["git_path_list"](repo, "ls-files", "-z")
+
+            self.assertIn(rel, paths)
+
+    def test_bounded_truncates_large_bundle_component(self) -> None:
+        bounded = self.helper["bounded"]("x" * 25, 10)
+
+        self.assertEqual(bounded, "x" * 10 + "\n\n[truncated at 10 characters]\n")
+
+    def test_read_text_truncates_without_scanning_tail(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            path = Path(tempdir) / "large.txt"
+            path.write_bytes(b"x" * 200_000 + b"\0tail")
+
+            text = self.helper["read_text"](path)
+
+            self.assertIn("[truncated at 180000 characters]", text)
+            self.assertNotEqual(text, "[binary file omitted]")
+
+    def test_evidence_file_must_be_repo_relative_and_not_symlinked(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            root = Path(tempdir)
+            repo = init_repo(root)
+            outside = root / "outside.md"
+            outside.write_text("outside\n", encoding="utf-8")
+
+            with self.assertRaisesRegex(SystemExit, "repo-relative"):
+                self.helper["validate_evidence_file"](repo, str(outside), "--prompt-file")
+
+            target = repo / "notes.md"
+            target.write_text("notes\n", encoding="utf-8")
+            link = repo / "link.md"
+            link.symlink_to(target)
+            with self.assertRaisesRegex(SystemExit, "symlinked"):
+                self.helper["validate_evidence_file"](repo, "link.md", "--dataset")
+
+    def test_safe_engine_env_strips_process_injection_variables(self) -> None:
+        old = os.environ.copy()
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            try:
+                os.environ["GIT_DIR"] = "/tmp/unsafe-git-dir"
+                os.environ["GIT_CONFIG_COUNT"] = "99"
+                os.environ["DYLD_INSERT_LIBRARIES"] = "/tmp/unsafe.dylib"
+                os.environ["NODE_OPTIONS"] = "--require=/tmp/unsafe.js"
+
+                env = self.helper["safe_engine_env"](repo)
+
+                self.assertNotEqual(env.get("GIT_DIR"), "/tmp/unsafe-git-dir")
+                self.assertEqual(
+                    env["GIT_CONFIG_COUNT"],
+                    str(len(self.helper["ENGINE_GIT_CONFIG_OVERRIDES"])),
+                )
+                self.assertNotIn("DYLD_INSERT_LIBRARIES", env)
+                self.assertNotIn("NODE_OPTIONS", env)
+            finally:
+                os.environ.clear()
+                os.environ.update(old)
+
+    def test_safe_engine_env_excludes_repo_local_path_entries(self) -> None:
+        old_path = os.environ.get("PATH", "")
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            os.environ["PATH"] = f"{repo}{os.pathsep}{old_path}"
+            try:
+                env = self.helper["safe_engine_env"](repo)
+            finally:
+                os.environ["PATH"] = old_path
+
+            self.assertNotIn(str(repo.resolve()), env["PATH"].split(os.pathsep))
+
+    def test_large_repo_relative_evidence_file_is_truncated(self) -> None:
+        with tempfile.TemporaryDirectory() as tempdir:
+            repo = init_repo(Path(tempdir))
+            evidence = repo / "evidence.txt"
+            evidence.write_text("x" * 600_000, encoding="utf-8")
+
+            _, content = self.helper["validate_evidence_file"](repo, "evidence.txt", "--dataset")
+
+            self.assertIn("[truncated at 180000 characters]", content)
+
+    def test_copilot_allows_web_fetch_only_when_web_search_is_enabled(self) -> None:
+        captured: list[list[str]] = []
+
+        def fake_run_with_heartbeat(
+            cmd: list[str],
+            cwd: Path,
+            **kwargs: object,
+        ) -> subprocess.CompletedProcess[str]:
+            captured.append(cmd)
+            return subprocess.CompletedProcess(cmd, 0, '{"findings":[]}', "")
+
+        self.helper["run_copilot"].__globals__["run_with_heartbeat"] = fake_run_with_heartbeat
+        self.helper["run_copilot"].__globals__["resolve_command"] = (
+            lambda command, repo: f"/resolved/{command}"
+        )
+        args = argparse.Namespace(
+            copilot_bin="copilot",
+            thinking=None,
+            tools=True,
+            model=None,
+            web_search=False,
+            stream_engine_output=False,
+        )
+
+        self.helper["run_copilot"](args, Path("/repo"), "prompt")
+
+        self.assertNotIn("--allow-tool=web_fetch", captured[-1])
+        self.assertFalse(any(arg == "--allow-all-urls" for arg in captured[-1]))
+
+        args.web_search = True
+        self.helper["run_copilot"](args, Path("/repo"), "prompt")
+
+        self.assertIn("--allow-tool=web_fetch", captured[-1])
+        self.assertIn("--allow-all-urls", captured[-1])
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -0,0 +1,129 @@
+---
+name: clawhub-content-rights-correspondence
+description: Use when drafting, sending, or preserving email correspondence for an existing ClawHub content rights case.
+---
+
+# ClawHub Content Rights Correspondence
+
+Use ClawHub's authenticated admin CLI commands directly. Do not use helper
+scripts, direct Hermit calls, or direct R2 access for correspondence.
+
+## Safety Rules
+
+- Require an existing `CHR-...` case. Never create cases with this skill.
+- Dry-run first and show the final recipient, subject, and body.
+- Send only after explicit user signoff on that final draft.
+- Use `bun run admin -- email send` for outbound email.
+- Use `bun run admin -- content-rights record-correspondence` to preserve the
+  exact correspondence in Hermit.
+- Do not retry after an email was sent if evidence recording fails; report the
+  failure so staff can repair the audit record without sending a duplicate.
+- `--attachment` files are archived with the correspondence. The generic email
+  template does not send file attachments.
+- The generic email template already adds the greeting. Do not add `Hello ...`
+  or `Hi ...` to the body file.
+- The generic email template may render the subject as a visible heading. Do
+  not pass `--title`, and do not duplicate the title in the body file.
+- Do not use the generic email action button for ClawHub content-rights
+  responses. Put the response form URL as plaintext in the body.
+
+## Publisher Removal Notice
+
+Use this subject:
+
+```text
+ClawHub skill removal notice
+```
+
+Use this body, replacing only the skill URL:
+
+```text
+We removed the following ClawHub skill after receiving a content rights request involving Rednote/Xiaohongshu platform rights:
+
+https://clawhub.ai/<owner>/<slug>
+
+If you believe this removal was made in error, please submit a response using this form:
+https://forms.openclaw.ai/clawhub-content-rights
+```
+
+Preview the email:
+
+```bash
+bun run admin -- email send \
+  --user <publisher-handle> \
+  --subject "ClawHub skill removal notice" \
+  --body-file /tmp/body.txt
+```
+
+Send only after explicit signoff:
+
+```bash
+bun run admin -- email send \
+  --user <publisher-handle> \
+  --subject "ClawHub skill removal notice" \
+  --body-file /tmp/body.txt \
+  --send \
+  --confirm-user-request \
+  --confirm-user-signoff \
+  --json
+```
+
+Record the exact sent correspondence:
+
+```bash
+bun run admin -- content-rights record-correspondence CHR-000007 \
+  --direction outbound \
+  --to "<publisher-handle-or-email>" \
+  --from "ClawHub <noreply@notifications.openclaw.ai>" \
+  --subject "ClawHub skill removal notice" \
+  --body-file /tmp/body.txt \
+  --provider-message-id "<providerId-from-send-response>" \
+  --json
+```
+
+## Requester Status Updates
+
+For requester updates or closure notes, use direct email and avoid exposing the
+internal case id in the subject unless the user explicitly asks.
+
+```bash
+bun run admin -- email send \
+  --to requester@example.com \
+  --username Requester \
+  --subject "Update on ClawHub content rights request" \
+  --body-file /tmp/body.txt
+```
+
+After explicit signoff, send:
+
+```bash
+bun run admin -- email send \
+  --to requester@example.com \
+  --username Requester \
+  --subject "Update on ClawHub content rights request" \
+  --body-file /tmp/body.txt \
+  --send \
+  --confirm-user-request \
+  --confirm-user-signoff \
+  --json
+```
+
+Then record the successful send with the provider id:
+
+```bash
+bun run admin -- content-rights record-correspondence CHR-000007 \
+  --direction outbound \
+  --to "Requester Name <requester@example.com>" \
+  --from "ClawHub <noreply@notifications.openclaw.ai>" \
+  --subject "Update on ClawHub content rights request" \
+  --body-file /tmp/body.txt \
+  --provider-message-id "<providerId-from-send-response>"
+```
+
+Verify the case now includes the correspondence:
+
+```bash
+bun run admin -- content-rights get CHR-000007 --json
+```
+
+Run from the ClawHub repository root with the normal authenticated admin CLI.
@@ -0,0 +1,4 @@
+interface:
+  display_name: "ClawHub Rights Correspondence"
+  short_description: "Send and preserve ClawHub rights case emails."
+  default_prompt: "Use $clawhub-content-rights-correspondence to draft or send correspondence for an existing ClawHub content rights case."
@@ -0,0 +1,213 @@
+---
+name: clawhub-moderation
+description: "Use for ClawHub staff moderation actions with the repo-local ClawHub admin tool: skills, users, org publishers, plugin packages, trusted publishers, official publishers, and guarded staff email."
+---
+
+# ClawHub Moderation
+
+Use the repo-local admin tool from a checked-out ClawHub repo. It wraps
+the existing ClawHub CLI auth/config and HTTP API surfaces. Do not call Convex
+internal mutations directly for staff actions.
+
+## Safety Rules
+
+- Require an explicit target from the user: skill slug, user handle, or user id.
+- Require a reason for destructive, restorative, ownership, or moderation writes.
+- Before any write, show the exact command and ask for confirmation unless the
+  user already said to proceed or supplied `--yes`.
+- For `email send`, the user must explicitly ask for the email and sign off on
+  the final recipient, subject, and body. Dry-run is fine for drafting. Never
+  send until both are true, and only use `--send --confirm-user-request
+--confirm-user-signoff` after that approval.
+- Prefer handles for humans. Use `--id` only when the user provides a user id.
+- Never bypass API-token auth, server role checks, or audit logging.
+- After the write, verify state with the CLI/API and report the result.
+
+## Command Map
+
+Run from the ClawHub repo root:
+
+```sh
+bun run admin -- --help
+```
+
+Authenticate or validate the current token:
+
+```sh
+bun run admin -- login
+bun run admin -- whoami
+```
+
+Current top-level command groups:
+
+```text
+auth
+users
+plugins|plugin
+packages|package
+org
+email
+skills|skill
+```
+
+### Skills
+
+`bun run admin -- skills --help` exposes:
+
+```text
+unhide <slug>
+rescan <slug>
+reports
+triage-report <report-id>
+```
+
+Examples:
+
+```sh
+bun run admin -- skills unhide <slug> --reason "<reason>" --yes
+bun run admin -- skills rescan <slug> --reason "<reason>" --yes
+bun run admin -- skills reports --status open
+bun run admin -- skills triage-report <report-id> --status confirmed --action hide --note "<note>" --yes
+```
+
+### Users
+
+`bun run admin -- users --help` exposes:
+
+```text
+ban <handleOrId>
+unban <handleOrId>
+set-role <handleOrId> <role>
+reclassify-ban <handleOrId>
+remediate-autobans
+```
+
+Examples:
+
+```sh
+bun run admin -- users ban <handleOrId> --reason "<reason>" --yes
+bun run admin -- users unban <handleOrId> --reason "<reason>" --yes
+bun run admin -- users set-role <handleOrId> <user|moderator|admin> --yes
+bun run admin -- users reclassify-ban <handleOrId> --reason "<reason>" --apply --yes
+bun run admin -- users remediate-autobans --apply --reason "<reason>"
+```
+
+Use `--id` when `<handleOrId>` is a user id. Use `--fuzzy` only when the user
+has asked for fuzzy handle resolution or the exact handle is ambiguous.
+
+### Org Publishers
+
+`bun run admin -- org --help` exposes:
+
+```text
+official
+create <handle>
+remove-member <handle> <member>
+delete <handle>
+repair-scoped-packages <csv>
+```
+
+Examples:
+
+```sh
+bun run admin -- org official list
+bun run admin -- org official add <handle> --reason "<reason>" --yes
+bun run admin -- org official remove <handle> --reason "<reason>" --yes
+bun run admin -- org create <handle> --display-name "<name>" --member <user-handle> --role owner
+bun run admin -- org remove-member <handle> <member-handle>
+bun run admin -- org delete <handle> --reason "<reason>"          # dry-run
+bun run admin -- org delete <handle> --reason "<reason>" --apply
+bun run admin -- org repair-scoped-packages <csv>                  # dry-run
+bun run admin -- org repair-scoped-packages <csv> --apply
+```
+
+`org create` requires `--member`; it must not add the moderator running the
+command as an implicit owner. `org delete` only works for empty org publishers
+and defaults to dry-run.
+
+### Plugin Packages
+
+`bun run admin -- packages --help` exposes:
+
+```text
+moderate <name>
+status|moderation-status <name>
+queue|moderation-queue
+reports
+triage-report <report-id>
+transfer <name>
+repair-name <name>
+migrations
+set-migration <bundled-plugin-id>
+trusted-publisher
+```
+
+Examples:
+
+```sh
+bun run admin -- packages status <name>
+bun run admin -- packages transfer <name> --to <owner> --reason "<reason>"       # dry-run
+bun run admin -- packages transfer <name> --to <owner> --reason "<reason>" --apply
+bun run admin -- packages repair-name <name> --next-name <name> --reason "<reason>"
+bun run admin -- packages trusted-publisher get <name>
+bun run admin -- packages trusted-publisher set <name> --repository <owner/repo> --workflow-filename <file>
+```
+
+### Staff Email
+
+`bun run admin -- email send --help` exposes:
+
+```text
+--to <email>
+--user <handle>
+--subject <subject>
+--body-file <path>
+--body <text>
+--send
+--confirm-user-request
+--confirm-user-signoff
+--json
+```
+
+Draft only:
+
+```sh
+bun run admin -- email send --user <handle> --subject "<subject>" --body-file <path>
+```
+
+Send only after explicit request and sign-off:
+
+```sh
+bun run admin -- email send --user <handle> --subject "<subject>" --body-file <path> --send --confirm-user-request --confirm-user-signoff
+```
+
+The server sends through the production noreply provider and writes an audit log
+only after admin auth succeeds.
+
+## Verification
+
+- For skills, inspect the page/API status after `skills unhide`.
+- For users, prefer user search/admin surfaces for target accounts where
+  available.
+- For orgs and packages, use the public publisher/plugin pages and the relevant
+  CLI status command after a write.
+- For email, verify the CLI response and audit expectation; do not send a second
+  email just to test delivery.
+- If verification is blocked by auth or missing admin access, report the command
+  result and the verification blocker plainly.
+
+## Impact Notes
+
+- `skills unhide` is a moderator manual restore. It clears skill hidden state,
+  applies a clean manual override to top-level moderation fields, preserves
+  version-level scanner records, updates public stats, and writes audit logs.
+- There is no standalone `skills hide` command in `clawhub-admin`; use report
+  triage with `--action hide` when resolving a report that should hide a skill.
+- `users ban` is disruptive: it revokes API tokens, marks the user deleted,
+  hides owned skills, soft-deletes comments, and writes audit logs.
+- `users unban` is admin-only. It clears ban state and restores skills that were
+  hidden by the matching ban flow; revoked API tokens stay revoked.
+- `packages transfer` preserves the package row, stats, releases, and history;
+  it changes the owner publisher.
+- `org delete` soft-deletes an empty org publisher and retains member rows for
+  history; it refuses orgs with active skills or packages.
@@ -0,0 +1,187 @@
+---
+name: clawhub-pr-maintainer
+description: Use when reviewing, triaging, validating, or discussing ClawHub GitHub issues or pull requests, including author context, CI, UI proof, evidence, labels, close decisions, and maintainer handoff.
+---
+
+# ClawHub PR Maintainer
+
+Use this skill for maintainer-facing ClawHub GitHub workflow, not for ordinary
+implementation work.
+
+## Start With Live GitHub State
+
+- Use `gh pr view` or `gh issue view` against `openclaw/clawhub`; verify live
+  state before commenting, labeling, closing, or recommending merge.
+- For PRs, read title, body, author, labels, comments, files, commits, status
+  checks, review state, and linked issues.
+- Surface author identity briefly: GitHub name/login and account age when
+  useful. Treat identity as triage signal, never as proof by itself.
+
+Common read-only commands:
+
+```sh
+gh pr view <number> --repo openclaw/clawhub --json title,body,author,labels,comments,files,commits,statusCheckRollup,reviewDecision,url,additions,deletions,changedFiles
+gh issue view <number> --repo openclaw/clawhub --json title,body,author,labels,comments,state,url
+gh api users/<login> --jq '{login,name,created_at,type}'
+```
+
+## Review Evidence Bar
+
+- For bug fixes, require symptom evidence, a plausible root cause in the touched
+  code path, and either a regression test or focused manual proof.
+- For UI changes, require screenshots or video when the behavior is meaningfully
+  visual. Use tests as supplemental evidence, not a substitute for visible proof.
+- Do not merge or recommend merge based only on PR prose, AI rationale, or green
+  CI when the changed behavior has not been exercised.
+- For contributor-provided screenshots/videos/logs, inspect the artifact
+  directly and state what it proves. Do not rerun `proof:ui` just to inspect
+  existing evidence.
+
+## Structure PR Review Output
+
+- Start every PR review with 1-3 plain sentences explaining what the change does
+  and why it matters.
+- Show size near the top as `LOC: +x/-y (N files)`, using live PR stats or
+  local diff stats.
+- Then list findings first. If none, say `No blocking findings` or
+  `No findings`.
+- Always answer: affected ClawHub surface, bug or behavior being changed,
+  evidence checked, and best-fix verdict.
+- For bug/regression fixes, include a compact `Provenance:` line when a bounded
+  history pass identifies it. Separate code author, PR author,
+  merger/committer, current PR author, PR number, and date when those differ.
+  If the blamed PR was merged by automation, identify the human trigger when
+  practical; otherwise say trigger unknown.
+
+## Read Beyond The Diff
+
+- For code-path bug, regression, or behavior changes, review the surrounding
+  path, not just changed lines. Open the runtime entry point, owner module, one
+  caller, one callee, adjacent tests, and sibling surfaces that should share the
+  invariant.
+- For docs/config/process-only changes, read the changed file, its linked or
+  adjacent source of truth, and any route/workflow/template the change claims to
+  affect. Do not require runtime caller/callee evidence when no runtime path
+  exists.
+- Compare against current `origin/main` behavior or current published docs when
+  regression, compatibility, or user-visible docs accuracy matters.
+- For dependency-backed behavior, read the upstream docs/source/types before
+  judging API use, defaults, output shapes, errors, timeouts, memory behavior, or
+  compatibility.
+- Mention the main files or contracts read when the verdict depends on
+  code-path, docs, config, or workflow evidence.
+- If a required path is uninspected, keep reading or mark
+  `Remaining uncertainty`; do not call the PR best, proof-sufficient, or
+  merge-ready.
+
+## Best-Fix Review Loop
+
+Every PR review must explicitly answer: "Is this the best fix, or only a
+plausible fix?"
+
+Before verdict:
+
+1. Reconstruct the bug, feature need, or behavior claim from the issue, PR, and
+   proof.
+2. For code-path changes, trace current behavior from entry point to failure or
+   decision point.
+3. For docs/config/process-only changes, trace the reader/operator workflow or
+   automation path the change is meant to clarify.
+4. Read touched files, relevant callers/callees for code changes, adjacent docs
+   or tests, owner modules, and relevant source-of-truth docs.
+5. Read sibling surfaces that should share the invariant or could be broken by a
+   one-sided fix.
+6. Compare against current `origin/main` and shipped behavior when relevant.
+7. Identify at least one alternative fix location or shape, then reject it with
+   evidence.
+
+Review output must include:
+
+- `Best-fix verdict:` best / acceptable mitigation / wrong layer / too narrow /
+  too broad.
+- `Alternatives considered:` 1-3 concrete alternatives and why rejected.
+- `Code read:` compact list of main files/contracts checked.
+- `Remaining uncertainty:` what was not proven.
+
+## Enforce Bug-Fix Evidence
+
+- Never merge a bug-fix PR based only on issue text, PR text, or AI rationale.
+- Before recommending merge for a bug fix, require:
+  1. symptom evidence such as a repro, logs, failing test, or focused manual
+     proof
+  2. a verified root cause in code with file/line
+  3. blame-backed provenance for regressions when traceable, or commit SHA/date
+     when no PR is traceable
+  4. a fix that touches the implicated code path
+  5. a regression test when feasible, or explicit manual verification plus a
+     reason no test was added
+- If the claim is unsubstantiated or likely wrong, request evidence or changes
+  instead of recommending merge.
+
+## Decide UI Proof Mode
+
+Use the `clawhub-ui-proof` skill when the maintainer/agent should generate new
+visual evidence.
+
+- `before-after`: bug fixes, regressions, changed copy, changed layout, or any
+  PR where main-vs-candidate comparison clarifies the change.
+- `feature`: new page, new flow, new UI state, or behavior that cannot exist on
+  `origin/main`.
+- No generated proof: docs-only, backend-only, tests-only, metadata-only, or
+  already-sufficient contributor evidence.
+
+Write a temporary Playwright scenario under `.artifacts/proof-scenarios/`; do
+not infer manual clicks. Keep screenshots and videos in `.artifacts/` until
+publishing. Never commit proof artifacts.
+
+## Final Review Comment With Proof
+
+If this review generated `proof:ui` artifacts, publish them before the final PR
+review comment. Do not leave only local `.artifacts/...` paths in a PR comment;
+they are useful to the maintainer locally but invisible to GitHub readers.
+
+Use:
+
+```sh
+bun run proof:publish -- --proof-dir .artifacts/clawhub-ui-proof/<timestamp> --target-pr <number>
+```
+
+`proof:publish` copies the selected files to the `qa-artifacts` branch and
+upserts a marker-backed PR comment with a **ClawHub UI Proof** section.
+
+That comment includes:
+
+- the proof mode (`before-after` or `feature`)
+- the `report.md` result summary
+- the most relevant per-step screenshots
+- inline video previews when GIF previews are present
+- links to full-run MP4s
+- links to raw proof files on the artifact branch
+
+Use `--dry-run` before publishing if you need to inspect the generated comment.
+If publishing fails because credentials are missing, report the local proof
+directory and the failed command instead of posting a comment that claims
+evidence is attached.
+
+## ClawSweeper
+
+ClawSweeper is the bot control plane for automated PR/issue review once ClawHub
+dispatch is configured. Until then, use this skill for manual maintainer review.
+If ClawSweeper has posted a review, read it as evidence but verify live PR state
+before acting.
+
+## Commenting And Labels
+
+- Use literal multiline comment bodies or `--body-file`; never pass escaped
+  `\n` strings.
+- For issue comments and PR comments containing backticks or shell characters,
+  prefer a single-quoted heredoc or `--body-file` over inline `-b` bodies.
+- Do not wrap issue or PR refs like `#123` in backticks when you want GitHub to
+  auto-link them.
+- Keep maintainer comments short: finding, evidence, requested action, and
+  verification path.
+- When no proof artifacts were generated, `gh pr comment --body-file` is fine.
+  When proof artifacts were generated, use `proof:publish` so screenshots/videos
+  are published before posting.
+- Do not close more than five issues/PRs in one action without explicit
+  confirmation and the exact target list.
@@ -0,0 +1,321 @@
+---
+name: convex-create-component
+description: Builds reusable Convex components with isolated tables and app-facing APIs.
+  Use for new components, reusable backend modules, integrations, or component
+  boundary work.
+---
+
+# Convex Create Component
+
+Create reusable Convex components with clear boundaries and a small app-facing
+API.
+
+## When to Use
+
+- Creating a new Convex component in an existing app
+- Extracting reusable backend logic into a component
+- Building a third-party integration that should own its own tables and
+  workflows
+- Packaging Convex functionality for reuse across multiple apps
+
+## When Not to Use
+
+- One-off business logic that belongs in the main app
+- Thin utilities that do not need Convex tables or functions
+- App-level orchestration that should stay in `convex/`
+- Cases where a normal TypeScript library is enough
+
+## Workflow
+
+1. Ask the user what they are building and what the end goal is. If the repo
+   already makes the answer obvious, say so and confirm before proceeding.
+2. Choose the shape using the decision tree below and read the matching
+   reference file.
+3. Decide whether a component is justified. Prefer normal app code or a regular
+   library if the feature does not need isolated tables, backend functions, or
+   reusable persistent state.
+4. Make a short plan for:
+   - what tables the component owns
+   - what public functions it exposes
+   - what data must be passed in from the app (auth, env vars, parent IDs)
+   - what stays in the app as wrappers or HTTP mounts
+5. Create the component structure with `convex.config.ts`, `schema.ts`, and
+   function files.
+6. Implement functions using the component's own `./_generated/server` imports,
+   not the app's generated files.
+7. Wire the component into the app with `app.use(...)`. If the app does not
+   already have `convex/convex.config.ts`, create it.
+8. Call the component from the app through `components.<name>` using
+   `ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction`.
+9. If React clients, HTTP callers, or public APIs need access, create wrapper
+   functions in the app instead of exposing component functions directly.
+10. Run `npx convex dev` and fix codegen, type, or boundary issues before
+    finishing.
+
+## Choose the Shape
+
+Ask the user, then pick one path:
+
+| Goal                                              | Shape            | Reference                           |
+| ------------------------------------------------- | ---------------- | ----------------------------------- |
+| Component for this app only                       | Local            | `references/local-components.md`    |
+| Publish or share across apps                      | Packaged         | `references/packaged-components.md` |
+| User explicitly needs local + shared library code | Hybrid           | `references/hybrid-components.md`   |
+| Not sure                                          | Default to local | `references/local-components.md`    |
+
+Read exactly one reference file before proceeding.
+
+## Default Approach
+
+Unless the user explicitly wants an npm package, default to a local component:
+
+- Put it under `convex/components/<componentName>/`
+- Define it with `defineComponent(...)` in its own `convex.config.ts`
+- Install it from the app's `convex/convex.config.ts` with `app.use(...)`
+- Let `npx convex dev` generate the component's own `_generated/` files
+
+## Component Skeleton
+
+A minimal local component with a table and two functions, plus the app wiring.
+
+```ts
+// convex/components/notifications/convex.config.ts
+import { defineComponent } from "convex/server";
+
+export default defineComponent("notifications");
+```
+
+```ts
+// convex/components/notifications/schema.ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  notifications: defineTable({
+    userId: v.string(),
+    message: v.string(),
+    read: v.boolean(),
+  }).index("by_user", ["userId"]),
+});
+```
+
+```ts
+// convex/components/notifications/lib.ts
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server.js";
+
+export const send = mutation({
+  args: { userId: v.string(), message: v.string() },
+  returns: v.id("notifications"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("notifications", {
+      userId: args.userId,
+      message: args.message,
+      read: false,
+    });
+  },
+});
+
+export const listUnread = query({
+  args: { userId: v.string() },
+  returns: v.array(
+    v.object({
+      _id: v.id("notifications"),
+      _creationTime: v.number(),
+      userId: v.string(),
+      message: v.string(),
+      read: v.boolean(),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("notifications")
+      .withIndex("by_user", (q) => q.eq("userId", args.userId))
+      .filter((q) => q.eq(q.field("read"), false))
+      .collect();
+  },
+});
+```
+
+```ts
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import notifications from "./components/notifications/convex.config.js";
+
+const app = defineApp();
+app.use(notifications);
+
+export default app;
+```
+
+```ts
+// convex/notifications.ts  (app-side wrapper)
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { components } from "./_generated/api";
+import { getAuthUserId } from "@convex-dev/auth/server";
+
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    await ctx.runMutation(components.notifications.lib.send, {
+      userId,
+      message: args.message,
+    });
+    return null;
+  },
+});
+
+export const myUnread = query({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    return await ctx.runQuery(components.notifications.lib.listUnread, {
+      userId,
+    });
+  },
+});
+```
+
+Note the reference path shape: a function in
+`convex/components/notifications/lib.ts` is called as
+`components.notifications.lib.send` from the app.
+
+## Critical Rules
+
+- Keep authentication in the app, because `ctx.auth` is not available inside
+  components.
+- Keep environment access in the app, because component functions cannot read
+  `process.env`.
+- Pass parent app IDs across the boundary as strings, because `Id` types become
+  plain strings in the app-facing `ComponentApi`.
+- Do not use `v.id("parentTable")` for app-owned tables inside component args or
+  schema, because the component has no access to the app's table namespace.
+- Import `query`, `mutation`, and `action` from the component's own
+  `./_generated/server`, not the app's generated files.
+- Do not expose component functions directly to clients. Create app wrappers
+  when client access is needed, because components are internal and need
+  auth/env wiring the app provides.
+- If the component defines HTTP handlers, mount the routes in the app's
+  `convex/http.ts`, because components cannot register their own HTTP routes.
+- If the component needs pagination, use `paginator` from `convex-helpers`
+  instead of built-in `.paginate()`, because `.paginate()` does not work across
+  the component boundary.
+- Add `args` and `returns` validators to all public component functions, because
+  the component boundary requires explicit type contracts.
+
+## Patterns
+
+### Authentication and environment access
+
+```ts
+// Bad: component code cannot rely on app auth or env
+const identity = await ctx.auth.getUserIdentity();
+const apiKey = process.env.OPENAI_API_KEY;
+```
+
+```ts
+// Good: the app resolves auth and env, then passes explicit values
+const userId = await getAuthUserId(ctx);
+if (!userId) throw new Error("Not authenticated");
+
+await ctx.runAction(components.translator.translate, {
+  userId,
+  apiKey: process.env.OPENAI_API_KEY,
+  text: args.text,
+});
+```
+
+### Client-facing API
+
+```ts
+// Bad: assuming a component function is directly callable by clients
+export const send = components.notifications.send;
+```
+
+```ts
+// Good: re-export through an app mutation or query
+export const sendNotification = mutation({
+  args: { message: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new Error("Not authenticated");
+
+    await ctx.runMutation(components.notifications.lib.send, {
+      userId,
+      message: args.message,
+    });
+    return null;
+  },
+});
+```
+
+### IDs across the boundary
+
+```ts
+// Bad: parent app table IDs are not valid component validators
+args: {
+  userId: v.id("users");
+}
+```
+
+```ts
+// Good: treat parent-owned IDs as strings at the boundary
+args: {
+  userId: v.string();
+}
+```
+
+### Advanced Patterns
+
+For additional patterns including function handles for callbacks, deriving
+validators from schema, static configuration with a globals table, and
+class-based client wrappers, see `references/advanced-patterns.md`.
+
+## Validation
+
+Try validation in this order:
+
+1. `npx convex codegen --component-dir convex/components/<name>`
+2. `npx convex codegen`
+3. `npx convex dev`
+
+Important:
+
+- Fresh repos may fail these commands until `CONVEX_DEPLOYMENT` is configured.
+- Until codegen runs, component-local `./_generated/*` imports and app-side
+  `components.<name>...` references will not typecheck.
+- If validation blocks on Convex login or deployment setup, stop and ask the
+  user for that exact step instead of guessing.
+
+## Reference Files
+
+Read exactly one of these after the user confirms the goal:
+
+- `references/local-components.md`
+- `references/packaged-components.md`
+- `references/hybrid-components.md`
+
+Official docs:
+[Authoring Components](https://docs.convex.dev/components/authoring)
+
+## Checklist
+
+- [ ] Asked the user what they want to build and confirmed the shape
+- [ ] Read the matching reference file
+- [ ] Confirmed a component is the right abstraction
+- [ ] Planned tables, public API, boundaries, and app wrappers
+- [ ] Component lives under `convex/components/<name>/` (or package layout if
+      publishing)
+- [ ] Component imports from its own `./_generated/server`
+- [ ] Auth, env access, and HTTP routes stay in the app
+- [ ] Parent app IDs cross the boundary as `v.string()`
+- [ ] Public functions have `args` and `returns` validators
+- [ ] Ran `npx convex dev` and fixed codegen or type issues
@@ -0,0 +1,12 @@
+interface:
+  display_name: "Convex Create Component"
+  short_description: "Design and build reusable Convex components with clear boundaries."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#14B8A6"
+  default_prompt: "Help me create a Convex component for this feature. First check that a
+    component is actually justified, then design the tables, API surface, and
+    app-facing wrappers before implementing it."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m21 7.5-2.25-1.313M21 7.5v2.25m0-2.25-2.25 1.313M3 7.5l2.25-1.313M3 7.5l2.25 1.313M3 7.5v2.25m9 3 2.25-1.313M12 12.75l-2.25-1.313M12 12.75V15m0 6.75 2.25-1.313M12 21.75V19.5m0 2.25-2.25-1.313m0-16.875L12 2.25l2.25 1.313M21 14.25v2.25l-2.25 1.313m-13.5 0L3 16.5v-2.25"/>
+</svg>
@@ -0,0 +1,140 @@
+# Advanced Component Patterns
+
+Additional patterns for Convex components that go beyond the basics covered in
+the main skill file.
+
+## Function Handles for callbacks
+
+When the app needs to pass a callback function to the component, use function
+handles. This is common for components that run app-defined logic on a schedule
+or in a workflow.
+
+```ts
+// App side: create a handle and pass it to the component
+import { createFunctionHandle } from "convex/server";
+
+export const startJob = mutation({
+  handler: async (ctx) => {
+    const handle = await createFunctionHandle(internal.myModule.processItem);
+    await ctx.runMutation(components.workpool.enqueue, {
+      callback: handle,
+    });
+  },
+});
+```
+
+```ts
+// Component side: accept and invoke the handle
+import { v } from "convex/values";
+import type { FunctionHandle } from "convex/server";
+import { mutation } from "./_generated/server.js";
+
+export const enqueue = mutation({
+  args: { callback: v.string() },
+  handler: async (ctx, args) => {
+    const handle = args.callback as FunctionHandle<"mutation">;
+    await ctx.scheduler.runAfter(0, handle, {});
+  },
+});
+```
+
+## Deriving validators from schema
+
+Instead of manually repeating field types in return validators, extend the
+schema validator:
+
+```ts
+import { v } from "convex/values";
+import schema from "./schema.js";
+
+const notificationDoc = schema.tables.notifications.validator.extend({
+  _id: v.id("notifications"),
+  _creationTime: v.number(),
+});
+
+export const getLatest = query({
+  args: {},
+  returns: v.nullable(notificationDoc),
+  handler: async (ctx) => {
+    return await ctx.db.query("notifications").order("desc").first();
+  },
+});
+```
+
+## Static configuration with a globals table
+
+A common pattern for component configuration is a single-document "globals"
+table:
+
+```ts
+// schema.ts
+export default defineSchema({
+  globals: defineTable({
+    maxRetries: v.number(),
+    webhookUrl: v.optional(v.string()),
+  }),
+  // ... other tables
+});
+```
+
+```ts
+// lib.ts
+export const configure = mutation({
+  args: { maxRetries: v.number(), webhookUrl: v.optional(v.string()) },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.query("globals").first();
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+    } else {
+      await ctx.db.insert("globals", args);
+    }
+    return null;
+  },
+});
+```
+
+## Class-based client wrappers
+
+For components with many functions or configuration options, a class-based
+client provides a cleaner API. This pattern is common in published components.
+
+```ts
+// src/client/index.ts
+import type { GenericMutationCtx, GenericDataModel } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+
+type MutationCtx = Pick<GenericMutationCtx<GenericDataModel>, "runMutation">;
+
+export class Notifications {
+  constructor(
+    private component: ComponentApi,
+    private options?: { defaultChannel?: string },
+  ) {}
+
+  async send(ctx: MutationCtx, args: { userId: string; message: string }) {
+    return await ctx.runMutation(this.component.lib.send, {
+      ...args,
+      channel: this.options?.defaultChannel ?? "default",
+    });
+  }
+}
+```
+
+```ts
+// App usage
+import { Notifications } from "@convex-dev/notifications";
+import { components } from "./_generated/api";
+
+const notifications = new Notifications(components.notifications, {
+  defaultChannel: "alerts",
+});
+
+export const send = mutation({
+  args: { message: v.string() },
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    await notifications.send(ctx, { userId, message: args.message });
+  },
+});
+```
@@ -0,0 +1,38 @@
+# Hybrid Convex Components
+
+Read this file only when the user explicitly wants a hybrid setup.
+
+## What This Means
+
+A hybrid component combines a local Convex component with shared library code.
+
+This can help when:
+
+- the user wants a local install but also shared package logic
+- the component needs extension points or override hooks
+- some logic should live in normal TypeScript code outside the component
+  boundary
+
+## Default Advice
+
+Treat hybrid as an advanced option, not the default.
+
+Before choosing it, ask:
+
+- Why is a plain local component not enough?
+- Why is a packaged component not enough?
+- What exactly needs to stay overridable or shared?
+
+If the answer is vague, fall back to local or packaged.
+
+## Risks
+
+- More moving parts
+- Harder upgrades and backwards compatibility
+- Easier to blur the component boundary
+
+## Checklist
+
+- [ ] User explicitly needs hybrid behavior
+- [ ] Local-only and packaged-only options were considered first
+- [ ] The extension points are clearly defined before coding
@@ -0,0 +1,39 @@
+# Local Convex Components
+
+Read this file when the component should live inside the current app and does
+not need to be published as an npm package.
+
+## When to Choose This
+
+- The user wants the simplest path
+- The component only needs to work in this repo
+- The goal is extracting app logic into a cleaner boundary
+
+## Default Layout
+
+Use this structure unless the repo already has a clear alternative pattern:
+
+```text
+convex/
+  convex.config.ts
+  components/
+    <name>/
+      convex.config.ts
+      schema.ts
+      <feature>.ts
+```
+
+## Workflow Notes
+
+- Define the component with `defineComponent("<name>")`
+- Install it from the app with `defineApp()` and `app.use(...)`
+- Keep auth, env access, public API wrappers, and HTTP route mounting in the app
+- Let the component own isolated tables and reusable backend workflows
+- Add app wrappers if clients need to call into the component
+
+## Checklist
+
+- [ ] Component is inside `convex/components/<name>/`
+- [ ] App installs it with `app.use(...)`
+- [ ] Component owns only its own tables
+- [ ] App wrappers handle client-facing calls when needed
@@ -0,0 +1,54 @@
+# Packaged Convex Components
+
+Read this file when the user wants a reusable npm package or a component shared
+across multiple apps.
+
+## When to Choose This
+
+- The user wants to publish the component
+- The user wants a stable reusable package boundary
+- The component will be shared across multiple apps or teams
+
+## Default Approach
+
+- Prefer starting from `npx create-convex@latest --component` when possible
+- Keep the official authoring docs as the source of truth for package layout and
+  exports
+- Validate the bundled package through an example app, not just the source files
+
+## Build Flow
+
+When building a packaged component, make sure the bundled output exists before
+the example app tries to consume it.
+
+Recommended order:
+
+1. `npx convex codegen --component-dir ./path/to/component`
+2. Run the package build command
+3. Run `npx convex dev --typecheck-components` in the example app
+
+Do not assume normal app codegen is enough for packaged component workflows.
+
+## Package Exports
+
+If publishing to npm, make sure the package exposes the entry points apps need:
+
+- package root for client helpers, types, or classes
+- `./convex.config.js` for installing the component
+- `./_generated/component.js` for the app-facing `ComponentApi` type
+- `./test` for testing helpers when applicable
+
+## Testing
+
+- Use `convex-test` for component logic
+- Register the component schema and modules with the test instance
+- Test app-side wrapper code from an example app that installs the package
+- Export a small helper from `./test` if consumers need easy test registration
+
+## Checklist
+
+- [ ] Packaging is actually required
+- [ ] Build order avoids bundle and codegen races
+- [ ] Package exports include install and typing entry points
+- [ ] Example app exercises the packaged component
+- [ ] Core behavior is covered by tests
@@ -0,0 +1,175 @@
+---
+name: convex-migration-helper
+description: Plans Convex schema and data migrations with widen-migrate-narrow and
+  @convex-dev/migrations. Use for breaking schema changes, backfills, table
+  reshaping, or zero-downtime rollouts.
+---
+
+# Convex Migration Helper
+
+Safely migrate Convex schemas and data when making breaking changes.
+
+## When to Use
+
+- Adding new required fields to existing tables
+- Changing field types or structure
+- Splitting or merging tables
+- Renaming or deleting fields
+- Migrating from nested to relational data
+
+## When Not to Use
+
+- Greenfield schema with no existing data in production or dev
+- Adding optional fields that do not need backfilling
+- Adding new tables with no existing data to migrate
+- Adding or removing indexes with no correctness concern
+- Questions about Convex schema design without a migration need
+
+## Key Concepts
+
+### Schema Validation Drives the Workflow
+
+Convex will not let you deploy a schema that does not match the data at rest.
+This is the fundamental constraint that shapes every migration:
+
+- You cannot add a required field if existing documents don't have it
+- You cannot change a field's type if existing documents have the old type
+- You cannot remove a field from the schema if existing documents still have it
+
+This means migrations follow a predictable pattern: **widen the schema, migrate
+the data, narrow the schema**.
+
+### Online Migrations
+
+Convex migrations run online, meaning the app continues serving requests while
+data is updated asynchronously in batches. During the migration window, your
+code must handle both old and new data formats.
+
+### Prefer New Fields Over Changing Types
+
+When changing the shape of data, create a new field rather than modifying an
+existing one. This makes the transition safer and easier to roll back.
+
+### Don't Delete Data
+
+Unless you are certain, prefer deprecating fields over deleting them. Mark the
+field as `v.optional` and add a code comment explaining it is deprecated and why
+it existed.
+
+## Safe Changes (No Migration Needed)
+
+### Adding Optional Field
+
+```typescript
+// Before
+users: defineTable({
+  name: v.string(),
+});
+
+// After - safe, new field is optional
+users: defineTable({
+  name: v.string(),
+  bio: v.optional(v.string()),
+});
+```
+
+### Adding New Table
+
+```typescript
+posts: defineTable({
+  userId: v.id("users"),
+  title: v.string(),
+}).index("by_user", ["userId"]);
+```
+
+### Adding Index
+
+```typescript
+users: defineTable({
+  name: v.string(),
+  email: v.string(),
+}).index("by_email", ["email"]);
+```
+
+## Breaking Changes: The Deployment Workflow
+
+Every breaking migration follows the same multi-deploy pattern:
+
+**Deploy 1 - Widen the schema:**
+
+1. Update schema to allow both old and new formats (e.g., add optional new
+   field)
+2. Update code to handle both formats when reading
+3. Update code to write the new format for new documents
+4. Deploy
+
+**Between deploys - Migrate data:**
+
+5. Run migration to backfill existing documents
+6. Verify all documents are migrated
+
+**Deploy 2 - Narrow the schema:**
+
+7. Update schema to require the new format only
+8. Remove code that handles the old format
+9. Deploy
+
+## Using the Migrations Component
+
+For any non-trivial migration, use the
+[`@convex-dev/migrations`](https://www.convex.dev/components/migrations)
+component. It handles batching, cursor-based pagination, state tracking, resume
+from failure, dry runs, and progress monitoring.
+
+See `references/migrations-component.md` for installation, setup, defining and
+running migrations, dry runs, status monitoring, and configuration options.
+
+## Common Migration Patterns
+
+See `references/migration-patterns.md` for complete patterns with code examples
+covering:
+
+- Adding a required field
+- Deleting a field
+- Changing a field type
+- Splitting nested data into a separate table
+- Cleaning up orphaned documents
+- Zero-downtime strategies (dual write, dual read)
+- Small table shortcut (single internalMutation without the component)
+- Verifying a migration is complete
+
+## Common Pitfalls
+
+1. **Making a field required before migrating data**: Convex rejects the deploy
+   because existing documents lack the field. Always widen the schema first.
+2. **Using `.collect()` on large tables**: Hits transaction limits or causes
+   timeouts. Use the migrations component for proper batched pagination.
+   `.collect()` is only safe for tables you know are small.
+3. **Not writing the new format before migrating**: Documents created during the
+   migration window will be missed, leaving unmigrated data after the migration
+   "completes."
+4. **Skipping the dry run**: Use `dryRun: true` to validate migration logic
+   before committing changes to production data. Catches bugs before they touch
+   real documents.
+5. **Deleting fields prematurely**: Prefer deprecating with `v.optional` and a
+   comment. Only delete after you are confident the data is no longer needed and
+   no code references it.
+6. **Using crons for migration batches**: The migrations component handles
+   batching via recursive scheduling internally. Crons require manual cleanup
+   and an extra deploy to remove.
+
+## Migration Checklist
+
+- [ ] Identify the breaking change and plan the multi-deploy workflow
+- [ ] Update schema to allow both old and new formats
+- [ ] Update code to handle both formats when reading
+- [ ] Update code to write the new format for new documents
+- [ ] Deploy widened schema and updated code
+- [ ] Define migration using the `@convex-dev/migrations` component
+- [ ] Test with `dryRun: true`
+- [ ] Run migration and monitor status
+- [ ] Verify all documents are migrated
+- [ ] Update schema to require new format only
+- [ ] Clean up code that handled old format
+- [ ] Deploy final schema and code
+- [ ] Remove migration code once confirmed stable
@@ -0,0 +1,12 @@
+interface:
+  display_name: "Convex Migration Helper"
+  short_description: "Plan and run safe Convex schema and data migrations."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#8B5CF6"
+  default_prompt: "Help me plan and execute this Convex migration safely. Start by identifying
+    the schema change, the existing data shape, and the widen-migrate-narrow
+    path before making edits."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99"/>
+</svg>
@@ -0,0 +1,243 @@
+# Migration Patterns Reference
+
+Common migration patterns, zero-downtime strategies, and verification techniques
+for Convex schema and data migrations.
+
+## Adding a Required Field
+
+```typescript
+// Deploy 1: Schema allows both states
+users: defineTable({
+  name: v.string(),
+  role: v.optional(v.union(v.literal("user"), v.literal("admin"))),
+});
+
+// Migration: backfill the field
+export const addDefaultRole = migrations.define({
+  table: "users",
+  migrateOne: async (ctx, user) => {
+    if (user.role === undefined) {
+      await ctx.db.patch(user._id, { role: "user" });
+    }
+  },
+});
+
+// Deploy 2: After migration completes, make it required
+users: defineTable({
+  name: v.string(),
+  role: v.union(v.literal("user"), v.literal("admin")),
+});
+```
+
+## Deleting a Field
+
+Mark the field optional first, migrate data to remove it, then remove from
+schema:
+
+```typescript
+// Deploy 1: Make optional
+// isPro: v.boolean()  -->  isPro: v.optional(v.boolean())
+
+// Migration
+export const removeIsPro = migrations.define({
+  table: "teams",
+  migrateOne: async (ctx, team) => {
+    if (team.isPro !== undefined) {
+      await ctx.db.patch(team._id, { isPro: undefined });
+    }
+  },
+});
+
+// Deploy 2: Remove isPro from schema entirely
+```
+
+## Changing a Field Type
+
+Prefer creating a new field. You can combine adding and deleting in one
+migration:
+
+```typescript
+// Deploy 1: Add new field, keep old field optional
+// isPro: v.boolean()  -->  isPro: v.optional(v.boolean()), plan: v.optional(...)
+
+// Migration: convert old field to new field
+export const convertToEnum = migrations.define({
+  table: "teams",
+  migrateOne: async (ctx, team) => {
+    if (team.plan === undefined) {
+      await ctx.db.patch(team._id, {
+        plan: team.isPro ? "pro" : "basic",
+        isPro: undefined,
+      });
+    }
+  },
+});
+
+// Deploy 2: Remove isPro from schema, make plan required
+```
+
+## Splitting Nested Data Into a Separate Table
+
+```typescript
+export const extractPreferences = migrations.define({
+  table: "users",
+  migrateOne: async (ctx, user) => {
+    if (user.preferences === undefined) return;
+
+    const existing = await ctx.db
+      .query("userPreferences")
+      .withIndex("by_user", (q) => q.eq("userId", user._id))
+      .first();
+
+    if (!existing) {
+      await ctx.db.insert("userPreferences", {
+        userId: user._id,
+        ...user.preferences,
+      });
+    }
+
+    await ctx.db.patch(user._id, { preferences: undefined });
+  },
+});
+```
+
+Make sure your code is already writing to the new `userPreferences` table for
+new users before running this migration, so you don't miss documents created
+during the migration window.
+
+## Cleaning Up Orphaned Documents
+
+```typescript
+export const deleteOrphanedEmbeddings = migrations.define({
+  table: "embeddings",
+  migrateOne: async (ctx, doc) => {
+    const chunk = await ctx.db
+      .query("chunks")
+      .withIndex("by_embedding", (q) => q.eq("embeddingId", doc._id))
+      .first();
+
+    if (!chunk) {
+      await ctx.db.delete(doc._id);
+    }
+  },
+});
+```
+
+## Zero-Downtime Strategies
+
+During the migration window, your app must handle both old and new data formats.
+There are two main strategies.
+
+### Dual Write (Preferred)
+
+Write to both old and new structures. Read from the old structure until
+migration is complete.
+
+1. Deploy code that writes both formats, reads old format
+2. Run migration on existing data
+3. Deploy code that reads new format, still writes both
+4. Deploy code that only reads and writes new format
+
+This is preferred because you can safely roll back at any point, the old format
+is always up to date.
+
+```typescript
+// Bad: only writing to new structure before migration is done
+export const createTeam = mutation({
+  args: { name: v.string(), isPro: v.boolean() },
+  handler: async (ctx, args) => {
+    await ctx.db.insert("teams", {
+      name: args.name,
+      plan: args.isPro ? "pro" : "basic",
+    });
+  },
+});
+
+// Good: writing to both structures during migration
+export const createTeam = mutation({
+  args: { name: v.string(), isPro: v.boolean() },
+  handler: async (ctx, args) => {
+    const plan = args.isPro ? "pro" : "basic";
+    await ctx.db.insert("teams", {
+      name: args.name,
+      isPro: args.isPro,
+      plan,
+    });
+  },
+});
+```
+
+### Dual Read
+
+Read both formats. Write only the new format.
+
+1. Deploy code that reads both formats (preferring new), writes only new format
+2. Run migration on existing data
+3. Deploy code that reads and writes only new format
+
+This avoids duplicating writes, which is useful when having two copies of data
+could cause inconsistencies. The downside is that rolling back to before step 1
+is harder, since new documents only have the new format.
+
+```typescript
+// Good: reading both formats, preferring new
+function getTeamPlan(team: Doc<"teams">): "basic" | "pro" {
+  if (team.plan !== undefined) return team.plan;
+  return team.isPro ? "pro" : "basic";
+}
+```
+
+## Small Table Shortcut
+
+For small tables (a few thousand documents at most), you can migrate in a single
+`internalMutation` without the component:
+
+```typescript
+import { internalMutation } from "./_generated/server";
+
+export const backfillSmallTable = internalMutation({
+  handler: async (ctx) => {
+    const docs = await ctx.db.query("smallConfig").collect();
+    for (const doc of docs) {
+      if (doc.newField === undefined) {
+        await ctx.db.patch(doc._id, { newField: "default" });
+      }
+    }
+  },
+});
+```
+
+```bash
+npx convex run migrations:backfillSmallTable
+```
+
+Only use `.collect()` when you are certain the table is small. For anything
+larger, use the migrations component.
+
+## Verifying a Migration
+
+Query to check remaining unmigrated documents:
+
+```typescript
+import { query } from "./_generated/server";
+
+export const verifyMigration = query({
+  handler: async (ctx) => {
+    const remaining = await ctx.db
+      .query("users")
+      .filter((q) => q.eq(q.field("role"), undefined))
+      .take(10);
+
+    return {
+      complete: remaining.length === 0,
+      sampleRemaining: remaining.map((u) => u._id),
+    };
+  },
+});
+```
+
+Or use the component's built-in status monitoring:
+
+```bash
+npx convex run --component migrations lib:getStatus --watch
+```
@@ -0,0 +1,177 @@
+# Migrations Component Reference
+
+Complete guide to the
+[`@convex-dev/migrations`](https://www.convex.dev/components/migrations)
+component for batched, resumable Convex data migrations.
+
+## Installation
+
+```bash
+npm install @convex-dev/migrations
+```
+
+## Setup
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import migrations from "@convex-dev/migrations/convex.config.js";
+
+const app = defineApp();
+app.use(migrations);
+export default app;
+```
+
+```typescript
+// convex/migrations.ts
+import { Migrations } from "@convex-dev/migrations";
+import { components } from "./_generated/api.js";
+import { DataModel } from "./_generated/dataModel.js";
+
+export const migrations = new Migrations<DataModel>(components.migrations);
+export const run = migrations.runner();
+```
+
+The `DataModel` type parameter is optional but provides type safety for
+migration definitions.
+
+## Define a Migration
+
+The `migrateOne` function processes a single document. The component handles
+batching and pagination automatically.
+
+```typescript
+// convex/migrations.ts
+export const addDefaultRole = migrations.define({
+  table: "users",
+  migrateOne: async (ctx, user) => {
+    if (user.role === undefined) {
+      await ctx.db.patch(user._id, { role: "user" });
+    }
+  },
+});
+```
+
+Shorthand: if you return an object, it is applied as a patch automatically.
+
+```typescript
+export const clearDeprecatedField = migrations.define({
+  table: "users",
+  migrateOne: () => ({ legacyField: undefined }),
+});
+```
+
+## Run a Migration
+
+From the CLI:
+
+```bash
+# Define a one-off runner in convex/migrations.ts:
+#   export const runIt = migrations.runner(internal.migrations.addDefaultRole);
+npx convex run migrations:runIt
+
+# Or use the general-purpose runner
+npx convex run migrations:run '{"fn": "migrations:addDefaultRole"}'
+```
+
+Programmatically from another Convex function:
+
+```typescript
+await migrations.runOne(ctx, internal.migrations.addDefaultRole);
+```
+
+## Run Multiple Migrations in Order
+
+```typescript
+export const runAll = migrations.runner([
+  internal.migrations.addDefaultRole,
+  internal.migrations.clearDeprecatedField,
+  internal.migrations.normalizeEmails,
+]);
+```
+
+```bash
+npx convex run migrations:runAll
+```
+
+If one fails, it stops and will not continue to the next. Call it again to retry
+from where it left off. Completed migrations are skipped automatically.
+
+## Dry Run
+
+Test a migration before committing changes:
+
+```bash
+npx convex run migrations:runIt '{"dryRun": true}'
+```
+
+This runs one batch and then rolls back, so you can see what it would do without
+changing any data.
+
+## Check Migration Status
+
+```bash
+npx convex run --component migrations lib:getStatus --watch
+```
+
+## Cancel a Running Migration
+
+```bash
+npx convex run --component migrations lib:cancel '{"name": "migrations:addDefaultRole"}'
+```
+
+Or programmatically:
+
+```typescript
+await migrations.cancel(ctx, internal.migrations.addDefaultRole);
+```
+
+## Run Migrations on Deploy
+
+Chain migration execution after deploying:
+
+```bash
+npx convex deploy --cmd 'npm run build' && npx convex run migrations:runAll --prod
+```
+
+## Configuration Options
+
+### Custom Batch Size
+
+If documents are large or the table has heavy write traffic, reduce the batch
+size to avoid transaction limits or OCC conflicts:
+
+```typescript
+export const migrateHeavyTable = migrations.define({
+  table: "largeDocuments",
+  batchSize: 10,
+  migrateOne: async (ctx, doc) => {
+    // migration logic
+  },
+});
+```
+
+### Migrate a Subset Using an Index
+
+Process only matching documents instead of the full table:
+
+```typescript
+export const fixEmptyNames = migrations.define({
+  table: "users",
+  customRange: (query) => query.withIndex("by_name", (q) => q.eq("name", "")),
+  migrateOne: () => ({ name: "<unknown>" }),
+});
+```
+
+### Parallelize Within a Batch
+
+By default each document in a batch is processed serially. Enable parallel
+processing if your migration logic does not depend on ordering:
+
+```typescript
+export const clearField = migrations.define({
+  table: "myTable",
+  parallelize: true,
+  migrateOne: () => ({ optionalField: undefined }),
+});
+```
@@ -0,0 +1,184 @@
+---
+name: convex-performance-audit
+description: Audits Convex performance for reads, subscriptions, write contention, and
+  function limits. Use for slow features, insights findings, OCC conflicts, or
+  read amplification.
+---
+
+# Convex Performance Audit
+
+Diagnose and fix performance problems in Convex applications, one problem class
+at a time.
+
+## When to Use
+
+- A Convex page or feature feels slow or expensive
+- `npx convex insights --details` reports high bytes read, documents read, or
+  OCC conflicts
+- Low-freshness read paths are using reactivity where point-in-time reads would
+  do
+- OCC conflict errors or excessive mutation retries
+- High subscription count or slow UI updates
+- Functions approaching execution or transaction limits
+- The same performance pattern needs fixing across sibling functions
+
+## When Not to Use
+
+- Initial Convex setup, auth setup, or component extraction
+- Pure schema migrations with no performance goal
+- One-off micro-optimizations without a user-visible or deployment-visible
+  problem
+
+## Guardrails
+
+- Prefer simpler code when scale is small, traffic is modest, or the available
+  signals are weak
+- Do not recommend digest tables, document splitting, fetch-strategy changes, or
+  migration-heavy rollouts unless there is a measured signal, a clearly
+  unbounded path, or a known hot read/write path
+- In Convex, a simple scan on a small table is often acceptable. Do not invent
+  structural work just because a pattern is not ideal at large scale
+
+## First Step: Gather Signals
+
+Start with the strongest signal available:
+
+1. If deployment Health insights are already available from the user or the
+   current context, treat them as a first-class source of performance signals.
+2. If CLI insights are available, run `npx convex insights --details`. Use
+   `--prod`, `--preview-name`, or `--deployment-name` when needed.
+   - If the local repo's Convex CLI is too old to support `insights`, try
+     `npx -y convex@latest insights --details` before giving up.
+3. If the repo already uses `convex-doctor`, you may treat its findings as
+   hints. Do not require it, and do not treat it as the source of truth.
+4. If runtime signals are unavailable, audit from code anyway, but keep the
+   guardrails above in mind. Lack of insights is not proof of health, but it is
+   also not proof that a large refactor is warranted.
+
+## Signal Routing
+
+After gathering signals, identify the problem class and read the matching
+reference file.
+
+| Signal                                                         | Reference                                 |
+| -------------------------------------------------------------- | ----------------------------------------- |
+| High bytes or documents read, JS filtering, unnecessary joins  | `references/hot-path-rules.md`            |
+| OCC conflict errors, write contention, mutation retries        | `references/occ-conflicts.md`             |
+| High subscription count, slow UI updates, excessive re-renders | `references/subscription-cost.md`         |
+| Function timeouts, transaction size errors, large payloads     | `references/function-budget.md`           |
+| General "it's slow" with no specific signal                    | Start with `references/hot-path-rules.md` |
+
+Multiple problem classes can overlap. Read the most relevant reference first,
+then check the others if symptoms remain.
+
+## Escalate Larger Fixes
+
+If the likely fix is invasive, cross-cutting, or migration-heavy, stop and
+present options before editing.
+
+Examples:
+
+- introducing digest or summary tables across multiple flows
+- splitting documents to isolate frequently-updated fields
+- reworking pagination or fetch strategy across several screens
+- switching to a new index or denormalized field that needs migration-safe
+  rollout
+
+When correctness depends on handling old and new states during a rollout,
+consult `skills/convex-migration-helper/SKILL.md` for the migration workflow.
+
+## Workflow
+
+### 1. Scope the problem
+
+Pick one concrete user flow from the actual project. Look at the codebase,
+client pages, and API surface to find the flow that matches the symptom.
+
+Write down:
+
+- entrypoint functions
+- client callsites using `useQuery`, `usePaginatedQuery`, or `useMutation`
+- tables read
+- tables written
+- whether the path is high-read, high-write, or both
+
+### 2. Trace the full read and write set
+
+For each function in the path:
+
+1. Trace every `ctx.db.get()` and `ctx.db.query()`
+2. Trace every `ctx.db.patch()`, `ctx.db.replace()`, and `ctx.db.insert()`
+3. Note foreign-key lookups, JS-side filtering, and full-document reads
+4. Identify all sibling functions touching the same tables
+5. Identify reactive stats, aggregates, or widgets rendered on the same page
+
+In Convex, every extra read increases transaction work, and every write can
+invalidate reactive subscribers. Treat read amplification and invalidation
+amplification as first-class problems.
+
+### 3. Apply fixes from the relevant reference
+
+Read the reference file matching your problem class. Each reference includes
+specific patterns, code examples, and a recommended fix order.
+
+Do not stop at the single function named by an insight. Trace sibling readers
+and writers touching the same tables.
+
+### 4. Fix sibling functions together
+
+When one function touching a table has a performance bug, audit sibling
+functions for the same pattern.
+
+After finding one problem, inspect both sibling readers and sibling writers for
+the same table family, including companion digest or summary tables.
+
+Examples:
+
+- If one list query switches from full docs to a digest table, inspect the other
+  list queries for that table
+- If one mutation isolates a frequently-updated field or splits a hot document,
+  inspect the other writers to the same table
+- If one read path needs a migration-safe rollout for an unbackfilled field,
+  inspect sibling reads for the same rollout risk
+
+Do not leave one path fixed and another path on the old pattern unless there is
+a clear product reason.
+
+### 5. Verify before finishing
+
+Confirm all of these:
+
+1. Results are the same as before, no dropped records
+2. Eliminated reads or writes are no longer in the path where expected
+3. Fallback behavior works when denormalized or indexed fields are missing
+4. Frequently-updated fields are isolated from widely-read documents where
+   needed
+5. Every relevant sibling reader and writer was inspected, not just the original
+   function
+
+## Reference Files
+
+- `references/hot-path-rules.md` - Read amplification, invalidation,
+  denormalization, indexes, digest tables
+- `references/occ-conflicts.md` - Write contention, OCC resolution, hot document
+  splitting
+- `references/subscription-cost.md` - Reactive query cost, subscription
+  granularity, point-in-time reads
+- `references/function-budget.md` - Execution limits, transaction size, large
+  documents, payload size
+
+Also check the official
+[Convex Best Practices](https://docs.convex.dev/understanding/best-practices/)
+page for additional patterns covering argument validation, access control, and
+code organization that may surface during the audit.
+
+## Checklist
+
+- [ ] Gathered signals from insights, dashboard, or code audit
+- [ ] Identified the problem class and read the matching reference
+- [ ] Scoped one concrete user flow or function path
+- [ ] Traced every read and write in that path
+- [ ] Identified sibling functions touching the same tables
+- [ ] Applied fixes from the reference, following the recommended fix order
+- [ ] Fixed sibling functions consistently
+- [ ] Verified behavior and confirmed no regressions
@@ -0,0 +1,12 @@
+interface:
+  display_name: "Convex Performance Audit"
+  short_description: "Audit slow Convex reads, subscriptions, OCC conflicts, and limits."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#EF4444"
+  default_prompt: "Audit this Convex app for performance issues. Start with the strongest
+    signal available, identify the problem class, and suggest the smallest
+    high-impact fix before proposing bigger structural changes."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M8.25 3v1.5M4.5 8.25H3m18 0h-1.5M4.5 12H3m18 0h-1.5m-15 3.75H3m18 0h-1.5M8.25 19.5V21M12 3v1.5m0 15V21m3.75-18v1.5m0 15V21m-9-1.5h10.5a2.25 2.25 0 0 0 2.25-2.25V6.75a2.25 2.25 0 0 0-2.25-2.25H6.75A2.25 2.25 0 0 0 4.5 6.75v10.5a2.25 2.25 0 0 0 2.25 2.25Zm.75-12h9v9h-9v-9Z"/>
+</svg>
@@ -0,0 +1,254 @@
+# Function Budget
+
+Use these rules when functions are hitting execution limits, transaction size
+errors, or returning excessively large payloads to the client.
+
+## Core Principle
+
+Convex functions run inside transactions with budgets for time, reads, and
+writes. Staying well within these limits is not just about avoiding errors, it
+reduces latency and contention.
+
+## Limits to Know
+
+These are the current values from the
+[Convex limits docs](https://docs.convex.dev/production/state/limits). Check
+that page for the latest numbers.
+
+| Resource                          | Limit                                                 |
+| --------------------------------- | ----------------------------------------------------- |
+| Query/mutation execution time     | 1 second (user code only, excludes DB operations)     |
+| Action execution time             | 10 minutes                                            |
+| Data read per transaction         | 16 MiB                                                |
+| Data written per transaction      | 16 MiB                                                |
+| Documents scanned per transaction | 32,000 (includes documents filtered out by `.filter`) |
+| Index ranges read per transaction | 4,096 (each `db.get` and `db.query` call)             |
+| Documents written per transaction | 16,000                                                |
+| Individual document size          | 1 MiB                                                 |
+| Function return value size        | 16 MiB                                                |
+
+## Symptoms
+
+- "Function execution took too long" errors
+- "Transaction too large" or read/write set size errors
+- Slow queries that read many documents
+- Client receiving large payloads that slow down page load
+- `npx convex insights --details` showing high bytes read
+
+## Common Causes
+
+### Unbounded collection
+
+A query that calls `.collect()` on a table without a reasonable limit. As the
+table grows, the query reads more and more documents.
+
+### Large document reads on hot paths
+
+Reading documents with large fields (rich text, embedded media references, long
+arrays) when only a small subset of the data is needed for the current view.
+
+### Mutation doing too much work
+
+A single mutation that updates hundreds of documents, backfills data, or
+rebuilds derived state in one transaction.
+
+### Returning too much data to the client
+
+A query returning full documents when the client only needs a few fields.
+
+## Fix Order
+
+### 1. Bound your reads
+
+Never `.collect()` without a limit on a table that can grow unbounded.
+
+```ts
+// Bad: unbounded read, breaks as the table grows
+const messages = await ctx.db.query("messages").collect();
+```
+
+```ts
+// Good: paginate or limit
+const messages = await ctx.db
+  .query("messages")
+  .withIndex("by_channel", (q) => q.eq("channelId", channelId))
+  .order("desc")
+  .take(50);
+```
+
+### 2. Read smaller shapes
+
+If the list page only needs title, author, and date, do not read full documents
+with rich content fields.
+
+Use digest or summary tables for hot list pages. See `hot-path-rules.md` for the
+digest table pattern.
+
+### 3. Break large mutations into batches
+
+If a mutation needs to update hundreds of documents, split it into a
+self-scheduling chain.
+
+```ts
+// Bad: one mutation updating every row
+export const backfillAll = internalMutation({
+  handler: async (ctx) => {
+    const docs = await ctx.db.query("items").collect();
+    for (const doc of docs) {
+      await ctx.db.patch(doc._id, { newField: computeValue(doc) });
+    }
+  },
+});
+```
+
+```ts
+// Good: cursor-based batch processing
+export const backfillBatch = internalMutation({
+  args: { cursor: v.optional(v.string()), batchSize: v.optional(v.number()) },
+  handler: async (ctx, args) => {
+    const batchSize = args.batchSize ?? 100;
+    const result = await ctx.db
+      .query("items")
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+
+    for (const doc of result.page) {
+      if (doc.newField === undefined) {
+        await ctx.db.patch(doc._id, { newField: computeValue(doc) });
+      }
+    }
+
+    if (!result.isDone) {
+      await ctx.scheduler.runAfter(0, internal.items.backfillBatch, {
+        cursor: result.continueCursor,
+        batchSize,
+      });
+    }
+  },
+});
+```
+
+### 4. Move heavy work to actions
+
+Queries and mutations run inside Convex's transactional runtime with strict
+budgets. If you need to do CPU-intensive computation, call external APIs, or
+process large files, use an action instead.
+
+Actions run outside the transaction and can call mutations to write results
+back.
+
+```ts
+// Bad: heavy computation inside a mutation
+export const processUpload = mutation({
+  handler: async (ctx, args) => {
+    const result = expensiveComputation(args.data);
+    await ctx.db.insert("results", result);
+  },
+});
+```
+
+```ts
+// Good: action for heavy work, mutation for the write
+export const processUpload = action({
+  handler: async (ctx, args) => {
+    const result = expensiveComputation(args.data);
+    await ctx.runMutation(internal.results.store, { result });
+  },
+});
+```
+
+### 5. Trim return values
+
+Only return what the client needs. If a query fetches full documents but the
+component only renders a few fields, map the results before returning.
+
+```ts
+// Bad: returns full documents including large content fields
+export const list = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("articles").take(20);
+  },
+});
+```
+
+```ts
+// Good: project to only the fields the client needs
+export const list = query({
+  handler: async (ctx) => {
+    const articles = await ctx.db.query("articles").take(20);
+    return articles.map((a) => ({
+      _id: a._id,
+      title: a.title,
+      author: a.author,
+      createdAt: a._creationTime,
+    }));
+  },
+});
+```
+
+### 6. Replace `ctx.runQuery` and `ctx.runMutation` with helper functions
+
+Inside queries and mutations, `ctx.runQuery` and `ctx.runMutation` have overhead
+compared to calling a plain TypeScript helper function. They run in the same
+transaction but pay extra per-call cost.
+
+```ts
+// Bad: unnecessary overhead from ctx.runQuery inside a mutation
+export const createProject = mutation({
+  handler: async (ctx, args) => {
+    const user = await ctx.runQuery(api.users.getCurrentUser);
+    await ctx.db.insert("projects", { ...args, ownerId: user._id });
+  },
+});
+```
+
+```ts
+// Good: plain helper function, no extra overhead
+export const createProject = mutation({
+  handler: async (ctx, args) => {
+    const user = await getCurrentUser(ctx);
+    await ctx.db.insert("projects", { ...args, ownerId: user._id });
+  },
+});
+```
+
+Exception: components require `ctx.runQuery`/`ctx.runMutation`. Use them there,
+but prefer helpers everywhere else.
+
+### 7. Avoid unnecessary `runAction` calls
+
+`runAction` from within an action creates a separate function invocation with
+its own memory and CPU budget. The parent action just sits idle waiting. Replace
+with a plain TypeScript function call unless you need a different runtime (e.g.
+calling Node.js code from the Convex runtime).
+
+```ts
+// Bad: runAction overhead for no reason
+export const processItems = action({
+  handler: async (ctx, args) => {
+    for (const item of args.items) {
+      await ctx.runAction(internal.items.processOne, { item });
+    }
+  },
+});
+```
+
+```ts
+// Good: plain function call
+export const processItems = action({
+  handler: async (ctx, args) => {
+    for (const item of args.items) {
+      await processOneItem(ctx, { item });
+    }
+  },
+});
+```
+
+## Verification
+
+1. No function execution or transaction size errors
+2. `npx convex insights --details` shows reduced bytes read
+3. Large mutations are batched and self-scheduling
+4. Client payloads are reasonably sized for the UI they serve
+5. `ctx.runQuery`/`ctx.runMutation` in queries and mutations replaced with
+   helpers where possible
+6. Sibling functions with similar patterns were checked
@@ -0,0 +1,410 @@
+# Hot Path Rules
+
+Use these rules when the top-level workflow points to read amplification,
+denormalization, index rollout, reactive query cost, or invalidation-heavy
+writes.
+
+## Contents
+
+- Core Principle
+- Consistency Rule
+- 1. Push Filters To Storage (indexes, migration rule, redundant indexes)
+- 2. Minimize Data Sources (denormalization, fallback rule)
+- 3. Minimize Row Size (digest tables)
+- 4. Skip No-Op Writes
+- 5. Match Consistency To Read Patterns (high-read/low-write,
+     high-read/high-write)
+- Convex-Specific Notes (reactive queries, point-in-time reads, triggers,
+  aggregates, backfills)
+- Verification
+
+## Core Principle
+
+Every byte read or written multiplies with concurrency.
+
+Think:
+
+`cost x calls_per_second x 86400`
+
+In Convex, every write can also fan out into reactive invalidation, replication
+work, and downstream sync.
+
+## Consistency Rule
+
+If you fix a hot-path pattern for one function, audit sibling functions touching
+the same tables for the same pattern.
+
+Do this especially for:
+
+- multiple list queries over the same table
+- multiple writers to the same table
+- public browse and search queries over the same records
+- helper functions reused by more than one endpoint
+
+## 1. Push Filters To Storage
+
+Both JavaScript `.filter()` and the Convex query `.filter()` method after a DB
+scan mean you already paid for the read. The Convex `.filter()` method has the
+same performance as filtering in JS, it does not push the predicate to the
+storage layer. Only `.withIndex()` and `.withSearchIndex()` actually reduce the
+documents scanned.
+
+Prefer:
+
+- `withIndex(...)`
+- `.withSearchIndex(...)` for text search
+- narrower tables
+- summary tables
+
+before accepting a scan-plus-filter pattern.
+
+```ts
+// Bad: scans then filters in JavaScript
+export const listOpen = query({
+  args: {},
+  handler: async (ctx) => {
+    const tasks = await ctx.db.query("tasks").collect();
+    return tasks.filter((task) => task.status === "open");
+  },
+});
+```
+
+```ts
+// Also bad: Convex .filter() does not push to storage either
+export const listOpen = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("tasks")
+      .filter((q) => q.eq(q.field("status"), "open"))
+      .collect();
+  },
+});
+```
+
+```ts
+// Good: use an index so storage does the filtering
+export const listOpen = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("tasks")
+      .withIndex("by_status", (q) => q.eq("status", "open"))
+      .collect();
+  },
+});
+```
+
+### Migration rule for indexes
+
+New indexes on partially backfilled fields can create correctness bugs during
+rollout.
+
+Important Convex detail:
+
+`undefined !== false`
+
+If an older document is missing a field entirely, it will not match a compound
+index entry that expects `false`.
+
+Do not trust old comments saying a field is "not backfilled" or "already
+backfilled". Verify.
+
+If correctness depends on handling old and new states during rollout, do not
+improvise a partial-backfill workaround in the hot path. Use a migration-safe
+rollout and consult `skills/convex-migration-helper/SKILL.md`.
+
+```ts
+// Bad: optional booleans can miss older rows where the field is undefined
+const projects = await ctx.db
+  .query("projects")
+  .withIndex("by_archived_and_updated", (q) => q.eq("isArchived", false))
+  .order("desc")
+  .take(20);
+```
+
+```ts
+// Good: switch hot-path reads only after the rollout is migration-safe
+// See the migration helper skill for dual-read / backfill / cutover patterns.
+```
+
+### Check for redundant indexes
+
+Indexes like `by_foo` and `by_foo_and_bar` are usually redundant. You only need
+`by_foo_and_bar`, since you can query it with just the `foo` condition and omit
+`bar`. Extra indexes add storage cost and write overhead on every insert, patch,
+and delete.
+
+```ts
+// Bad: two indexes where one would do
+defineTable({ team: v.id("teams"), user: v.id("users") })
+  .index("by_team", ["team"])
+  .index("by_team_and_user", ["team", "user"]);
+```
+
+```ts
+// Good: single compound index serves both query patterns
+defineTable({ team: v.id("teams"), user: v.id("users") }).index("by_team_and_user", [
+  "team",
+  "user",
+]);
+```
+
+Exception: `.index("by_foo", ["foo"])` is really an index on `foo` +
+`_creationTime`, while `.index("by_foo_and_bar", ["foo", "bar"])` is on `foo` +
+`bar` + `_creationTime`. If you need results sorted by `foo` then
+`_creationTime`, you need the single-field index because the compound one would
+sort by `bar` first.
+
+## 2. Minimize Data Sources
+
+Trace every read.
+
+If a function resolves a foreign key for a tiny display field and a denormalized
+copy already exists, prefer the denormalized field on the hot path.
+
+### When to denormalize
+
+Denormalize when all of these are true:
+
+- the path is hot
+- the joined document is much larger than the field you need
+- many readers are paying that join cost repeatedly
+
+Useful mental model:
+
+`join_cost = rows_per_page x foreign_doc_size x pages_per_second`
+
+Small-table joins are often fine. Large-document joins for tiny fields on hot
+list pages are usually not.
+
+### Fallback rule
+
+Denormalized data is an optimization. Live data is the correctness path.
+
+Rules:
+
+- If the denormalized field is missing or null, fall back to the live read
+- Do not show placeholders instead of falling back
+- In lookup maps, only include fully populated entries
+
+```ts
+// Bad: missing denormalized data becomes a placeholder and blocks correctness
+const ownerName = project.ownerName ?? "Unknown owner";
+```
+
+```ts
+// Good: denormalized data is an optimization, not the only source of truth
+const ownerName = project.ownerName ?? (await ctx.db.get(project.ownerId))?.name ?? null;
+```
+
+Bad lookup map pattern:
+
+```ts
+const ownersById = {
+  [project.ownerId]: { ownerName: null },
+};
+```
+
+That blocks fallback because the map says "I have data" when it does not.
+
+Good lookup map pattern:
+
+```ts
+const ownersById =
+  project.ownerName !== undefined && project.ownerName !== null
+    ? { [project.ownerId]: { ownerName: project.ownerName } }
+    : {};
+```
+
+### No denormalized copy yet
+
+Prefer adding fields to an existing summary, companion, or digest table instead
+of bloating the primary hot-path table.
+
+If introducing the new field or table requires a staged rollout, backfill, or
+old/new-shape handling, use the migration helper skill for the rollout plan.
+
+Rollout order:
+
+1. Update schema
+2. Update write path
+3. Backfill
+4. Switch read path
+
+## 3. Minimize Row Size
+
+Hot list pages should read the smallest document shape that still answers the
+UI.
+
+Prefer summary or digest tables over full source tables when:
+
+- the list page only needs a subset of fields
+- source documents are large
+- the query is high volume
+
+An 800 byte summary row is materially cheaper than a 3 KB full document on a hot
+page.
+
+Digest tables are a tradeoff, not a default:
+
+- Worth it when the path is clearly hot, the source rows are much larger than
+  the UI needs, or many readers are repeatedly paying the same join and payload
+  cost
+- Probably not worth it when an indexed read on the source table is already
+  cheap enough, the table is still small, or the extra write and migration
+  complexity would dominate the benefit
+
+```ts
+// Bad: list page reads source docs, then joins owner data per row
+const projects = await ctx.db
+  .query("projects")
+  .withIndex("by_public", (q) => q.eq("isPublic", true))
+  .collect();
+```
+
+```ts
+// Good: list page reads the smaller digest shape first
+const projects = await ctx.db
+  .query("projectDigests")
+  .withIndex("by_public_and_updated", (q) => q.eq("isPublic", true))
+  .order("desc")
+  .take(20);
+```
+
+## 4. Isolate Frequently-Updated Fields
+
+Convex already no-ops unchanged writes. The invalidation problem here is real
+writes hitting documents that many queries subscribe to.
+
+Move high-churn fields like `lastSeen`, counters, presence, or ephemeral status
+off widely-read documents when most readers do not need them.
+
+Apply this across sibling writers too. Splitting one write path does not help
+much if three other mutations still update the same widely-read document.
+
+```ts
+// Bad: every presence heartbeat invalidates subscribers to the whole profile
+await ctx.db.patch(user._id, {
+  name: args.name,
+  avatarUrl: args.avatarUrl,
+  lastSeen: Date.now(),
+});
+```
+
+```ts
+// Good: keep profile reads stable, move heartbeat updates to a separate document
+await ctx.db.patch(user._id, {
+  name: args.name,
+  avatarUrl: args.avatarUrl,
+});
+
+await ctx.db.patch(presence._id, {
+  lastSeen: Date.now(),
+});
+```
+
+## 5. Match Consistency To Read Patterns
+
+Choose read strategy based on traffic shape.
+
+### High-read, low-write
+
+Examples:
+
+- public browse pages
+- search results
+- landing pages
+- directory listings
+
+Prefer:
+
+- point-in-time reads where appropriate
+- explicit refresh
+- local state for pagination
+- caching where appropriate
+
+Do not treat subscriptions as automatically wrong here. Prefer point-in-time
+reads only when the product does not need live freshness and the reactive cost
+is material. See `subscription-cost.md` for detailed patterns.
+
+### High-read, high-write
+
+Examples:
+
+- collaborative editors
+- live dashboards
+- presence-heavy views
+
+Reactive queries may be worth the ongoing cost.
+
+## Convex-Specific Notes
+
+### Reactive queries
+
+Every `ctx.db.get()` and `ctx.db.query()` contributes to the invalidation set
+for the query.
+
+On the client:
+
+- `useQuery` creates a live subscription
+- `usePaginatedQuery` creates a live subscription per page
+
+For low-freshness flows, consider a point-in-time read instead of a live
+subscription only when the product does not need updates pushed automatically.
+
+### Point-in-time reads
+
+Framework helpers, server-rendered fetches, or one-shot client reads can avoid
+ongoing subscription cost when live updates are not useful.
+
+Use them for:
+
+- aggregate snapshots
+- reports
+- low-churn listings
+- pages where explicit refresh is fine
+
+### Triggers and fan-out
+
+Triggers fire on every write, including writes that did not materially change
+the document.
+
+When a write exists only to keep derived state in sync:
+
+- diff before patching
+- move expensive non-blocking work to `ctx.scheduler.runAfter` when appropriate
+
+### Aggregates
+
+Reactive global counts invalidate frequently on busy tables.
+
+Prefer:
+
+- one-shot aggregate fetches
+- periodic recomputation
+- precomputed summary rows
+
+for global stats that do not need live updates every second.
+
+### Backfills
+
+For larger backfills, use cursor-based, self-scheduling `internalMutation` jobs
+or the migrations component.
+
+Deploy code that can handle both states before running the backfill.
+
+During the gap:
+
+- writes should populate the new shape
+- reads should fall back safely
+
+## Verification
+
+Before closing the audit, confirm:
+
+1. Same results as before, no dropped records
+2. The removed table or lookup is no longer in the hot-path read set
+3. Tests or validation cover fallback behavior
+4. Migration safety is preserved while fields or indexes are unbackfilled
+5. Sibling functions were fixed consistently
@@ -0,0 +1,137 @@
+# OCC Conflict Resolution
+
+Use these rules when insights, logs, or dashboard health show OCC (Optimistic
+Concurrency Control) conflicts, mutation retries, or write contention on hot
+tables.
+
+## Core Principle
+
+Convex uses optimistic concurrency control. When two transactions read or write
+overlapping data, one succeeds and the other retries automatically. High
+contention means wasted work and increased latency.
+
+## Symptoms
+
+- OCC conflict errors in deployment logs or health page
+- Mutations retrying multiple times before succeeding
+- User-visible latency spikes on write-heavy pages
+- `npx convex insights --details` showing high conflict rates
+
+## Common Causes
+
+### Hot documents
+
+Multiple mutations writing to the same document concurrently. Classic examples:
+a global counter, a shared settings row, or a "last updated" timestamp on a
+parent record.
+
+### Broad read sets causing false conflicts
+
+A query that scans a large table range creates a broad read set. If any write
+touches that range, the query's transaction conflicts even if the specific
+document the query cared about was not modified.
+
+### Fan-out from triggers or cascading writes
+
+A single user action triggers multiple mutations that all touch related
+documents. Each mutation competes with the others.
+
+Database triggers (e.g. from `convex-helpers`) run inside the same transaction
+as the mutation that caused them. If a trigger does heavy work, reads extra
+tables, or writes to many documents, it extends the transaction's read/write set
+and increases the window for conflicts. Keep trigger logic minimal, or move
+expensive derived work to a scheduled function.
+
+### Write-then-read chains
+
+A mutation writes a document, then a reactive query re-reads it, then another
+mutation writes it again. Under load, these chains stack up.
+
+## Fix Order
+
+### 1. Reduce read set size
+
+Narrower reads mean fewer false conflicts.
+
+```ts
+// Bad: broad scan creates a wide conflict surface
+const allTasks = await ctx.db.query("tasks").collect();
+const mine = allTasks.filter((t) => t.ownerId === userId);
+```
+
+```ts
+// Good: indexed query touches only relevant documents
+const mine = await ctx.db
+  .query("tasks")
+  .withIndex("by_owner", (q) => q.eq("ownerId", userId))
+  .collect();
+```
+
+### 2. Split hot documents
+
+When many writers target the same document, split the contention point.
+
+```ts
+// Bad: every vote increments the same counter document
+const counter = await ctx.db.get(pollCounterId);
+await ctx.db.patch(pollCounterId, { count: counter!.count + 1 });
+```
+
+```ts
+// Good: shard the counter across multiple documents, aggregate on read
+const shardIndex = Math.floor(Math.random() * SHARD_COUNT);
+const shardId = shardIds[shardIndex];
+const shard = await ctx.db.get(shardId);
+await ctx.db.patch(shardId, { count: shard!.count + 1 });
+```
+
+Aggregate the shards in a query or scheduled job when you need the total.
+
+### 3. Move non-critical work to scheduled functions
+
+If a mutation does primary work plus secondary bookkeeping (analytics,
+non-critical notifications, cache warming), the bookkeeping extends the
+transaction's lifetime and read/write set.
+
+```ts
+// Bad: canonical write and derived work happen in the same transaction
+await ctx.db.patch(userId, { name: args.name });
+await ctx.db.insert("userUpdateAnalytics", {
+  userId,
+  kind: "name_changed",
+  name: args.name,
+});
+```
+
+```ts
+// Good: keep the primary write small, defer the analytics work
+await ctx.db.patch(userId, { name: args.name });
+await ctx.scheduler.runAfter(0, internal.users.recordNameChangeAnalytics, {
+  userId,
+  name: args.name,
+});
+```
+
+### 4. Combine competing writes
+
+If two mutations must update the same document atomically, consider whether they
+can be combined into a single mutation call from the client, reducing round
+trips and conflict windows.
+
+Do not introduce artificial locks or queues unless the above steps have been
+tried first.
+
+## Related: Invalidation Scope
+
+Splitting hot documents also reduces subscription invalidation, not just OCC
+contention. If a document is written frequently and read by many queries, those
+queries re-run on every write even when the fields they care about have not
+changed. See `subscription-cost.md` section 4 ("Isolate frequently-updated
+fields") for that pattern.
+
+## Verification
+
+1. OCC conflict rate has dropped in insights or dashboard
+2. Mutation latency is lower and more consistent
+3. No data correctness regressions from splitting or scheduling changes
+4. Sibling writers to the same hot documents were fixed consistently
@@ -0,0 +1,297 @@
+# Subscription Cost
+
+Use these rules when the problem is too many reactive subscriptions, queries
+invalidating too frequently, or React components re-rendering excessively due to
+Convex state changes.
+
+## Core Principle
+
+Every `useQuery` and `usePaginatedQuery` call creates a live subscription. The
+server tracks the query's read set and re-executes the query whenever any
+document in that read set changes. Subscription cost scales with:
+
+`subscriptions x invalidation_frequency x query_cost`
+
+Subscriptions are not inherently bad. Convex reactivity is often the right
+default. The goal is to reduce unnecessary invalidation work, not to eliminate
+subscriptions on principle.
+
+## Symptoms
+
+- Dashboard shows high active subscription count
+- UI feels sluggish or laggy despite fast individual queries
+- React profiling shows frequent re-renders from Convex state
+- Pages with many components each running their own `useQuery`
+- Paginated lists where every loaded page stays subscribed
+
+## Common Causes
+
+### Reactive queries on low-freshness flows
+
+Some user flows are read-heavy and do not need live updates every time the
+underlying data changes. In those cases, ongoing subscriptions may cost more
+than they are worth.
+
+### Overly broad queries
+
+A query that returns a large result set invalidates whenever any document in
+that set changes. The broader the query, the more frequent the invalidation.
+
+### Too many subscriptions per page
+
+A page with 20 list items, each running its own `useQuery` to fetch related
+data, creates 20+ subscriptions per visitor.
+
+### Paginated queries keeping all pages live
+
+`usePaginatedQuery` with `loadMore` keeps every loaded page subscribed. On a
+page where a user has scrolled through 10 pages, all 10 stay reactive.
+
+### Frequently-updated fields on widely-read documents
+
+A document that many queries touch gets a frequently-updated field (like
+`lastSeen`, `lastActiveAt`, or a counter). Every write to that field invalidates
+every subscription that reads the document, even if those subscriptions never
+use the field. This is different from OCC conflicts (see `occ-conflicts.md`),
+which are write-vs-write contention. This is write-vs-subscription: the write
+succeeds fine, but it forces hundreds of queries to re-run for no reason.
+
+## Fix Order
+
+### 1. Use point-in-time reads when live updates are not valuable
+
+Keep `useQuery` and `usePaginatedQuery` by default when the product benefits
+from fresh live data.
+
+Consider a point-in-time read instead when all of these are true:
+
+- the flow is high-read
+- the underlying data changes less often than users need to see
+- explicit refresh, periodic refresh, or a fresh read on navigation is
+  acceptable
+
+Possible implementations depend on environment:
+
+- a server-rendered fetch
+- a framework helper like `fetchQuery`
+- a point-in-time client read such as `ConvexHttpClient.query()`
+
+```ts
+// Reactive by default when fresh live data matters
+function TeamPresence() {
+  const presence = useQuery(api.teams.livePresence, { teamId });
+  return <PresenceList users={presence} />;
+}
+```
+
+```ts
+// Point-in-time read when explicit refresh is acceptable
+import { ConvexHttpClient } from "convex/browser";
+
+const client = new ConvexHttpClient(import.meta.env.VITE_CONVEX_URL);
+
+function SnapshotView() {
+  const [items, setItems] = useState<Item[]>([]);
+
+  useEffect(() => {
+    client.query(api.items.snapshot).then(setItems);
+  }, []);
+
+  return <ItemGrid items={items} />;
+}
+```
+
+Good candidates for point-in-time reads:
+
+- aggregate snapshots
+- reports
+- low-churn listings
+- flows where explicit refresh is already acceptable
+
+Keep reactive for:
+
+- collaborative editing
+- live dashboards
+- presence-heavy views
+- any surface where users expect fresh changes to appear automatically
+
+### 2. Batch related data into fewer queries
+
+Instead of N components each fetching their own related data, fetch it in a
+single query.
+
+```ts
+// Bad: each card fetches its own author
+function ProjectCard({ project }: { project: Project }) {
+  const author = useQuery(api.users.get, { id: project.authorId });
+  return <Card title={project.name} author={author?.name} />;
+}
+```
+
+```ts
+// Good: parent query returns projects with author names included
+function ProjectList() {
+  const projects = useQuery(api.projects.listWithAuthors);
+  return projects?.map((p) => (
+    <Card key={p._id} title={p.name} author={p.authorName} />
+  ));
+}
+```
+
+This can use denormalized fields or server-side joins in the query handler.
+Either way, it is one subscription instead of N.
+
+This is not automatically better. If the combined query becomes much broader and
+invalidates much more often, several narrower subscriptions may be the better
+tradeoff. Optimize for total invalidation cost, not raw subscription count.
+
+### 3. Use skip to avoid unnecessary subscriptions
+
+The `"skip"` value prevents a subscription from being created when the arguments
+are not ready.
+
+```ts
+// Bad: subscribes with undefined args, wastes a subscription slot
+const profile = useQuery(api.users.getProfile, { userId: selectedId! });
+```
+
+```ts
+// Good: skip when there is nothing to fetch
+const profile = useQuery(api.users.getProfile, selectedId ? { userId: selectedId } : "skip");
+```
+
+### 4. Isolate frequently-updated fields into separate documents
+
+If a document is widely read but has a field that changes often, move that field
+to a separate document. Queries that do not need the field will no longer be
+invalidated by its writes.
+
+```ts
+// Bad: lastSeen lives on the user doc, every heartbeat invalidates
+// every query that reads this user
+const users = defineTable({
+  name: v.string(),
+  email: v.string(),
+  lastSeen: v.number(),
+});
+```
+
+```ts
+// Good: lastSeen lives in a separate heartbeat doc
+const users = defineTable({
+  name: v.string(),
+  email: v.string(),
+  heartbeatId: v.id("heartbeats"),
+});
+
+const heartbeats = defineTable({
+  lastSeen: v.number(),
+});
+```
+
+Queries that only need `name` and `email` no longer re-run on every heartbeat.
+Queries that actually need online status fetch the heartbeat document
+explicitly.
+
+For an even further optimization, if you only need a coarse online/offline
+boolean rather than the exact `lastSeen` timestamp, add a separate presence
+document with an `isOnline` flag. Update it immediately when a user comes
+online, and use a cron to batch-mark users offline when their heartbeat goes
+stale. This way the presence query only invalidates when online status actually
+changes, not on every heartbeat.
+
+### 5. Use the aggregate component for counts and sums
+
+Reactive global counts (`SELECT COUNT(*)` equivalent) invalidate on every insert
+or delete to the table. The
+[`@convex-dev/aggregate`](https://www.npmjs.com/package/@convex-dev/aggregate)
+component maintains denormalized COUNT, SUM, and MAX values efficiently so you
+do not need a reactive query scanning the full table.
+
+Use it for leaderboards, totals, "X items" badges, or any stat that would
+otherwise require scanning many rows reactively.
+
+If the aggregate component is not appropriate, prefer point-in-time reads for
+global stats, or precomputed summary rows updated by a cron or trigger, over
+reactive queries that scan large tables.
+
+### 6. Narrow query read sets
+
+Queries that return less data and touch fewer documents invalidate less often.
+
+```ts
+// Bad: returns all fields, invalidates on any field change
+export const list = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("projects").collect();
+  },
+});
+```
+
+```ts
+// Good: use a digest table with only the fields the list needs
+export const listDigests = query({
+  handler: async (ctx) => {
+    return await ctx.db.query("projectDigests").collect();
+  },
+});
+```
+
+Writes to fields not in the digest table do not invalidate the digest query.
+
+### 7. Remove `Date.now()` from queries
+
+Using `Date.now()` inside a query defeats Convex's query cache. The cache is
+invalidated frequently to avoid showing stale time-dependent results, which
+increases database work even when the underlying data has not changed.
+
+```ts
+// Bad: Date.now() defeats query caching and causes frequent re-evaluation
+const releasedPosts = await ctx.db
+  .query("posts")
+  .withIndex("by_released_at", (q) => q.lte("releasedAt", Date.now()))
+  .take(100);
+```
+
+```ts
+// Good: use a boolean field updated by a scheduled function
+const releasedPosts = await ctx.db
+  .query("posts")
+  .withIndex("by_is_released", (q) => q.eq("isReleased", true))
+  .take(100);
+```
+
+If the query must compare against a time value, pass it as an explicit argument
+from the client and round it to a coarse interval (e.g. the most recent minute)
+so requests within that window share the same cache entry.
+
+### 8. Consider pagination strategy
+
+For long lists where users scroll through many pages:
+
+- If the data does not need live updates, use point-in-time fetching with manual
+  "load more"
+- If it does need live updates, accept the subscription cost but limit the
+  number of loaded pages
+- Consider whether older pages can be unloaded as the user scrolls forward
+
+### 9. Separate backend cost from UI churn
+
+If the main problem is loading flash or UI churn when query arguments change,
+stabilizing the reactive UI behavior may be better than replacing reactivity
+altogether.
+
+Treat this as a UX problem first when:
+
+- the underlying query is already reasonably cheap
+- the complaint is flicker, loading flashes, or re-render churn
+- live updates are still desirable once fresh data arrives
+
+## Verification
+
+1. Subscription count in dashboard is lower for the affected pages
+2. UI responsiveness has improved
+3. React profiling shows fewer unnecessary re-renders
+4. Surfaces that do not need live updates are not paying for persistent
+   subscriptions unnecessarily
+5. Sibling pages with similar patterns were updated consistently
@@ -0,0 +1,370 @@
+---
+name: convex-quickstart
+description: Creates or adds Convex to an app. Use for new Convex projects, npm create
+  convex@latest, frontend setup, env vars, or the first npx convex dev run.
+---
+
+# Convex Quickstart
+
+Set up a working Convex project as fast as possible.
+
+## When to Use
+
+- Starting a brand new project with Convex
+- Adding Convex to an existing React, Next.js, Vue, Svelte, or other app
+- Scaffolding a Convex app for prototyping
+
+## When Not to Use
+
+- The project already has Convex installed and `convex/` exists - just start
+  building
+- You only need to add auth to an existing Convex app - use the
+  `convex-setup-auth` skill
+
+## Workflow
+
+1. Determine the starting point: new project or existing app
+2. If new project, pick a template and scaffold with `npm create convex@latest`
+3. If existing app, install `convex` and wire up the provider
+4. Run `npx convex dev` to connect a deployment and start the dev loop
+5. Verify the setup works
+
+## Path 1: New Project (Recommended)
+
+Use the official scaffolding tool. It creates a complete project with the
+frontend framework, Convex backend, and all config wired together.
+
+### Pick a template
+
+| Template                   | Stack                                     |
+| -------------------------- | ----------------------------------------- |
+| `react-vite-shadcn`        | React + Vite + Tailwind + shadcn/ui       |
+| `nextjs-shadcn`            | Next.js App Router + Tailwind + shadcn/ui |
+| `react-vite-clerk-shadcn`  | React + Vite + Clerk auth + shadcn/ui     |
+| `nextjs-clerk`             | Next.js + Clerk auth                      |
+| `nextjs-convexauth-shadcn` | Next.js + Convex Auth + shadcn/ui         |
+| `nextjs-lucia-shadcn`      | Next.js + Lucia auth + shadcn/ui          |
+| `bare`                     | Convex backend only, no frontend          |
+
+If the user has not specified a preference, default to `react-vite-shadcn` for
+simple apps or `nextjs-shadcn` for apps that need SSR or API routes.
+
+You can also use any GitHub repo as a template:
+
+```bash
+npm create convex@latest my-app -- -t owner/repo
+npm create convex@latest my-app -- -t owner/repo#branch
+```
+
+### Scaffold the project
+
+Always pass the project name and template flag to avoid interactive prompts:
+
+```bash
+npm create convex@latest my-app -- -t react-vite-shadcn
+cd my-app
+npm install
+```
+
+The scaffolding tool creates files but does not run `npm install`, so you must
+run it yourself.
+
+To scaffold in the current directory (if it is empty):
+
+```bash
+npm create convex@latest . -- -t react-vite-shadcn
+npm install
+```
+
+### Start the dev loop
+
+`npx convex dev` is a long-running watcher process that syncs backend code to a
+Convex deployment on every save. It also requires authentication on first run
+(browser-based OAuth). Both of these make it unsuitable for an agent to run
+directly.
+
+**Ask the user to run this themselves:**
+
+Tell the user to run `npx convex dev` in their terminal. On first run it will
+prompt them to log in or develop anonymously. Once running, it will:
+
+- Create a Convex project and dev deployment
+- Write the deployment URL to `.env.local`
+- Create the `convex/` directory with generated types
+- Watch for changes and sync continuously
+
+The user should keep `npx convex dev` running in the background while you work
+on code. The watcher will automatically pick up any files you create or edit in
+`convex/`.
+
+**Exception - cloud or headless agents:** Environments that cannot open a
+browser for interactive login should use Agent Mode (see below) to run
+anonymously without user interaction.
+
+### Start the frontend
+
+The user should also run the frontend dev server in a separate terminal:
+
+```bash
+npm run dev
+```
+
+Vite apps serve on `http://localhost:5173`, Next.js on `http://localhost:3000`.
+
+### What you get
+
+After scaffolding, the project structure looks like:
+
+```
+my-app/
+  convex/           # Backend functions and schema
+    _generated/     # Auto-generated types (check this into git)
+    schema.ts       # Database schema (if template includes one)
+  src/              # Frontend code (or app/ for Next.js)
+  package.json
+  .env.local        # CONVEX_URL / VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL
+```
+
+The template already has:
+
+- `ConvexProvider` wired into the app root
+- Correct env var names for the framework
+- Tailwind and shadcn/ui ready (for shadcn templates)
+- Auth provider configured (for auth templates)
+
+Proceed to adding schema, functions, and UI.
+
+## Path 2: Add Convex to an Existing App
+
+Use this when the user already has a frontend project and wants to add Convex as
+the backend.
+
+### Install
+
+```bash
+npm install convex
+```
+
+### Initialize and start dev loop
+
+Ask the user to run `npx convex dev` in their terminal. This handles login,
+creates the `convex/` directory, writes the deployment URL to `.env.local`, and
+starts the file watcher. See the notes in Path 1 about why the agent should not
+run this directly.
+
+### Wire up the provider
+
+The Convex client must wrap the app at the root. The setup varies by framework.
+
+Create the `ConvexReactClient` at module scope, not inside a component:
+
+```tsx
+// Bad: re-creates the client on every render
+function App() {
+  const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
+  return <ConvexProvider client={convex}>...</ConvexProvider>;
+}
+
+// Good: created once at module scope
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
+function App() {
+  return <ConvexProvider client={convex}>...</ConvexProvider>;
+}
+```
+
+#### React (Vite)
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import App from "./App";
+
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ConvexProvider client={convex}>
+      <App />
+    </ConvexProvider>
+  </StrictMode>,
+);
+```
+
+#### Next.js (App Router)
+
+```tsx
+// app/ConvexClientProvider.tsx
+"use client";
+
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { ReactNode } from "react";
+
+const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
+
+export function ConvexClientProvider({ children }: { children: ReactNode }) {
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}
+```
+
+```tsx
+// app/layout.tsx
+import { ConvexClientProvider } from "./ConvexClientProvider";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <ConvexClientProvider>{children}</ConvexClientProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+#### Other frameworks
+
+For Vue, Svelte, React Native, TanStack Start, Remix, and others, follow the
+matching quickstart guide:
+
+- [Vue](https://docs.convex.dev/quickstart/vue)
+- [Svelte](https://docs.convex.dev/quickstart/svelte)
+- [React Native](https://docs.convex.dev/quickstart/react-native)
+- [TanStack Start](https://docs.convex.dev/quickstart/tanstack-start)
+- [Remix](https://docs.convex.dev/quickstart/remix)
+- [Node.js (no frontend)](https://docs.convex.dev/quickstart/nodejs)
+
+### Environment variables
+
+The env var name depends on the framework:
+
+| Framework    | Variable                 |
+| ------------ | ------------------------ |
+| Vite         | `VITE_CONVEX_URL`        |
+| Next.js      | `NEXT_PUBLIC_CONVEX_URL` |
+| Remix        | `CONVEX_URL`             |
+| React Native | `EXPO_PUBLIC_CONVEX_URL` |
+
+`npx convex dev` writes the correct variable to `.env.local` automatically.
+
+## Agent Mode (Cloud and Headless Agents)
+
+When running in a cloud or headless agent environment where interactive browser
+login is not possible, set `CONVEX_AGENT_MODE=anonymous` to use a local
+anonymous deployment.
+
+Add `CONVEX_AGENT_MODE=anonymous` to `.env.local`, or set it inline:
+
+```bash
+CONVEX_AGENT_MODE=anonymous npx convex dev
+```
+
+This runs a local Convex backend on the VM without requiring authentication, and
+avoids conflicting with the user's personal dev deployment.
+
+## Verify the Setup
+
+After setup, confirm everything is working:
+
+1. The user confirms `npx convex dev` is running without errors
+2. The `convex/_generated/` directory exists and has `api.ts` and `server.ts`
+3. `.env.local` contains the deployment URL
+
+## Writing Your First Function
+
+Once the project is set up, create a schema and a query to verify the full loop
+works.
+
+`convex/schema.ts`:
+
+```ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  tasks: defineTable({
+    text: v.string(),
+    completed: v.boolean(),
+  }),
+});
+```
+
+`convex/tasks.ts`:
+
+```ts
+import { query, mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("tasks").collect();
+  },
+});
+
+export const create = mutation({
+  args: { text: v.string() },
+  handler: async (ctx, args) => {
+    await ctx.db.insert("tasks", { text: args.text, completed: false });
+  },
+});
+```
+
+Use in a React component (adjust the import path based on your file location
+relative to `convex/`):
+
+```tsx
+import { useQuery, useMutation } from "convex/react";
+import { api } from "../convex/_generated/api";
+
+function Tasks() {
+  const tasks = useQuery(api.tasks.list);
+  const create = useMutation(api.tasks.create);
+
+  return (
+    <div>
+      <button onClick={() => create({ text: "New task" })}>Add</button>
+      {tasks?.map((t) => (
+        <div key={t._id}>{t.text}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Development vs Production
+
+Always use `npx convex dev` during development. It runs against your personal
+dev deployment and syncs code on save.
+
+When ready to ship, deploy to production:
+
+```bash
+npx convex deploy
+```
+
+This pushes to the production deployment, which is separate from dev. Do not use
+`deploy` during development.
+
+## Next Steps
+
+- Add authentication: use the `convex-setup-auth` skill
+- Design your schema: see
+  [Schema docs](https://docs.convex.dev/database/schemas)
+- Build components: use the `convex-create-component` skill
+- Plan a migration: use the `convex-migration-helper` skill
+- Add file storage: see
+  [File Storage docs](https://docs.convex.dev/file-storage)
+- Set up cron jobs: see [Scheduling docs](https://docs.convex.dev/scheduling)
+
+## Checklist
+
+- [ ] Determined starting point: new project or existing app
+- [ ] If new project: scaffolded with `npm create convex@latest` using
+      appropriate template
+- [ ] If existing app: installed `convex` and wired up the provider
+- [ ] User has `npx convex dev` running and connected to a deployment
+- [ ] `convex/_generated/` directory exists with types
+- [ ] `.env.local` has the deployment URL
+- [ ] Verified a basic query/mutation round-trip works
@@ -0,0 +1,12 @@
+interface:
+  display_name: "Convex Quickstart"
+  short_description: "Start a new Convex app or add Convex to an existing frontend."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#F97316"
+  default_prompt: "Set up Convex for this project as fast as possible. First decide whether
+    this is a new app or an existing app, then scaffold or integrate Convex and
+    verify the setup works."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z"/>
+  <path stroke-linecap="round" stroke-linejoin="round" d="M15.91 11.672a.375.375 0 0 1 0 .656l-5.603 3.113a.375.375 0 0 1-.557-.328V8.887c0-.286.307-.466.557-.327l5.603 3.112Z"/>
+</svg>
@@ -0,0 +1,35 @@
+---
+name: convex-retention
+description: Use when adding or changing ClawHub Convex tables, TTL fields, cleanup crons, retention policy, auth/session cleanup, metric dedupe cleanup, or deprecated table removal
+---
+
+# Convex Retention
+
+## Overview
+
+ClawHub retention is code-owned. Every current Convex table must be classified in
+`convex/lib/retentionPolicy.ts`, and ephemeral tables need an indexed, bounded cleanup path unless
+their lifecycle is handled by usage-time validation or a documented component.
+
+## Checklist
+
+- Read `convex/_generated/ai/guidelines.md` and the Convex ops rules in `AGENTS.md` first.
+- Add every new schema table to `RETENTION_POLICIES`; the `Record<TableNames, RetentionPolicy>` type
+  is the enforcement gate.
+- For ephemeral tables, prefer an explicit expiration field plus index, then prune with `.withIndex()`
+  and `.take(...)`.
+- For new generic TTL tables, prefer `expirationTime` to match Convex Auth. Keep existing `expiresAt`,
+  `dayStart`, and `processedAt` fields unless that table already needs a real migration.
+- Use `RETENTION_STANDARD_BATCH_SIZE` for ordinary retention jobs. Keep incident-tested special cases,
+  such as `skillStatEvents`, on their documented caps.
+- Cron jobs should schedule bounded cleanup entrypoints only. Large one-off production migrations or
+  destructive backfills still start with `convex-migration-helper`.
+- Do not bulk-clear active auth state. Expired `authSessions` and `authRefreshTokens` are pruned by
+  `convex/retention.ts`.
+
+## Verification
+
+- Add or update focused tests for policy classification and cleanup behavior.
+- Run the focused Vitest slice for touched cleanup modules.
+- Run `bunx convex codegen` after schema/API changes.
+- Run a real Convex runtime check such as `bunx convex dev --once --typecheck=disable`.
@@ -0,0 +1,184 @@
+---
+name: convex-setup-auth
+description: Sets up Convex auth, identity mapping, and access control. Use for login, auth
+  providers, users tables, protected functions, or roles in a Convex app.
+---
+
+# Convex Authentication Setup
+
+Implement secure authentication in Convex with user management and access
+control.
+
+## When to Use
+
+- Setting up authentication for the first time
+- Implementing user management (users table, identity mapping)
+- Creating authentication helper functions
+- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom
+  JWT)
+
+## When Not to Use
+
+- Auth for a non-Convex backend
+- Pure OAuth/OIDC documentation without a Convex implementation
+- Debugging unrelated bugs that happen to surface near auth code
+- The auth provider is already fully configured and the user only needs a
+  one-line fix
+
+## First Step: Choose the Auth Provider
+
+Convex supports multiple authentication approaches. Do not assume a provider.
+
+Before writing setup code:
+
+1. Ask the user which auth solution they want, unless the repository already
+   makes it obvious
+2. If the repo already uses a provider, continue with that provider unless the
+   user wants to switch
+3. If the user has not chosen a provider and the repo does not make it obvious,
+   ask before proceeding
+
+Common options:
+
+- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when
+  the user wants auth handled directly in Convex
+- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses
+  Clerk or the user wants Clerk's hosted auth features
+- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app
+  already uses WorkOS or the user wants AuthKit specifically
+- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses
+  Auth0
+- Custom JWT provider - use when integrating an existing auth system not covered
+  above
+
+Look for signals in the repo before asking:
+
+- Dependencies such as `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth
+  packages
+- Existing files such as `convex/auth.config.ts`, auth middleware, provider
+  wrappers, or login components
+- Environment variables that clearly point at a provider
+
+## After Choosing a Provider
+
+Read the provider's official guide and the matching local reference file:
+
+- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then
+  `references/convex-auth.md`
+- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then
+  `references/clerk.md`
+- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then
+  `references/workos-authkit.md`
+- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then
+  `references/auth0.md`
+
+The local reference files contain the concrete workflow, expected files and env
+vars, gotchas, and validation checks.
+
+Use those sources for:
+
+- package installation
+- client provider wiring
+- environment variables
+- `convex/auth.config.ts` setup
+- login and logout UI patterns
+- framework-specific setup for React, Vite, or Next.js
+
+For shared auth behavior, use the official Convex docs as the source of truth:
+
+- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for
+  `ctx.auth.getUserIdentity()`
+- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)
+  for optional app-level user storage
+- [Authentication](https://docs.convex.dev/auth) for general auth and
+  authorization guidance
+- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the
+  provider is Convex Auth
+
+Prefer official docs over recalled steps, because provider CLIs and Convex Auth
+internals change between versions. Inventing setup from memory risks outdated
+patterns. For third-party providers, only add app-level user storage if the app
+actually needs user documents in Convex. Not every app needs a `users` table.
+For Convex Auth, follow the Convex Auth docs and built-in auth tables rather
+than adding a parallel `users` table plus `storeUser` flow, because Convex Auth
+already manages user records internally. After running provider initialization
+commands, verify generated files and complete the post-init wiring steps the
+provider reference calls out. Initialization commands rarely finish the entire
+integration.
+
+## Core Pattern: Protecting Backend Functions
+
+The most common auth task is checking identity in Convex functions.
+
+```ts
+// Bad: trusting a client-provided userId
+export const getMyProfile = query({
+  args: { userId: v.id("users") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.userId);
+  },
+});
+```
+
+```ts
+// Good: verifying identity server-side
+export const getMyProfile = query({
+  args: {},
+  handler: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) throw new Error("Not authenticated");
+
+    return await ctx.db
+      .query("users")
+      .withIndex("by_tokenIdentifier", (q) => q.eq("tokenIdentifier", identity.tokenIdentifier))
+      .unique();
+  },
+});
+```
+
+## Workflow
+
+1. Determine the provider, either by asking the user or inferring from the repo
+2. Ask whether the user wants local-only setup or production-ready setup now
+3. Read the matching provider reference file
+4. Follow the official provider docs for current setup details
+5. Follow the official Convex docs for shared backend auth behavior, user
+   storage, and authorization patterns
+6. Only add app-level user storage if the docs and app requirements call for it
+7. Add authorization checks for ownership, roles, or team access only where the
+   app needs them
+8. Verify login state, protected queries, environment variables, and production
+   configuration if requested
+
+If the flow blocks on interactive provider or deployment setup, ask the user
+explicitly for the exact human step needed, then continue after they complete
+it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow
+after setup is done. If the environment has browser automation tools, you can
+use them. If it does not, give the user a short manual validation checklist
+instead.
+
+## Reference Files
+
+### Provider References
+
+- `references/convex-auth.md`
+- `references/clerk.md`
+- `references/workos-authkit.md`
+- `references/auth0.md`
+
+## Checklist
+
+- [ ] Chosen the correct auth provider before writing setup code
+- [ ] Read the relevant provider reference file
+- [ ] Asked whether the user wants local-only setup or production-ready setup
+- [ ] Used the official provider docs for provider-specific wiring
+- [ ] Used the official Convex docs for shared auth behavior and authorization
+      patterns
+- [ ] Only added app-level user storage if the app actually needs it
+- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for
+      Convex Auth
+- [ ] Added authentication checks in protected backend functions
+- [ ] Added authorization checks where the app actually needs them
+- [ ] Clear error messages ("Not authenticated", "Unauthorized")
+- [ ] Client auth provider configured for the chosen provider
+- [ ] If requested, production auth setup is covered too
@@ -0,0 +1,12 @@
+interface:
+  display_name: "Convex Setup Auth"
+  short_description: "Set up Convex auth, user identity mapping, and access control."
+  icon_small: "./assets/icon.svg"
+  icon_large: "./assets/icon.svg"
+  brand_color: "#2563EB"
+  default_prompt: "Set up authentication for this Convex app. Figure out the provider first,
+    then wire up the user model, identity mapping, and access control with the
+    smallest solid implementation."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor" aria-hidden="true" data-slot="icon">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M16.5 10.5V6.75a4.5 4.5 0 1 0-9 0v3.75m-.75 11.25h10.5a2.25 2.25 0 0 0 2.25-2.25v-6.75a2.25 2.25 0 0 0-2.25-2.25H6.75a2.25 2.25 0 0 0-2.25 2.25v6.75a2.25 2.25 0 0 0 2.25 2.25Z"/>
+</svg>
@@ -0,0 +1,156 @@
+# Auth0
+
+Official docs:
+
+- https://docs.convex.dev/auth/auth0
+- https://auth0.github.io/auth0-cli/
+- https://auth0.github.io/auth0-cli/auth0_apps_create.html
+
+Use this when the app already uses Auth0 or the user wants Auth0 specifically.
+
+## Workflow
+
+1. Confirm the user wants Auth0
+2. Determine the app framework and whether Auth0 is already partly set up
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the official Convex and Auth0 guides before making changes
+5. Ask whether they want the fastest setup path by installing the Auth0 CLI
+6. If they agree, install the Auth0 CLI and do as much of the Auth0 app setup as
+   possible through the CLI
+7. If they do not want the CLI path, use the Auth0 dashboard path instead
+8. Complete the relevant Auth0 frontend quickstart if the app does not already
+   have Auth0 wired up
+9. Configure `convex/auth.config.ts` with the Auth0 domain and client ID
+10. Set environment variables for local and production environments
+11. Wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
+12. Gate Convex-backed UI with Convex auth state
+13. Try to verify Convex reports the user as authenticated after Auth0 login
+14. If the refresh-token path fails, stop improvising and send the user back to
+    the official docs
+15. If the user wants production-ready setup, make sure the production Auth0
+    tenant and env vars are also covered
+
+## What To Do
+
+- Read the official Convex and Auth0 guide before writing setup code
+- Prefer the Auth0 CLI path for mechanical setup if the user is willing to
+  install it, but do not present it as a fully validated end-to-end path yet
+- Ask the user directly: "The fastest path is to install the Auth0 CLI so I can
+  do more of this for you. If you want, I can install it and then only ask you
+  to log in when needed. Would you like me to do that?"
+- Make sure the app has already completed the relevant Auth0 quickstart for its
+  frontend
+- Use the official examples for `Auth0Provider` and `ConvexProviderWithAuth0`
+- If the Auth0 login or refresh flow starts failing in a way that is not clearly
+  explained by the docs, say that plainly and fall back to the official docs
+  instead of pretending the flow is validated
+
+## Key Setup Areas
+
+- install the Auth0 SDK for the app's framework
+- configure `convex/auth.config.ts` with the Auth0 domain and client ID
+- set environment variables for local and production environments
+- wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
+- use Convex auth state when gating Convex-backed UI
+
+## Files and Env Vars To Expect
+
+- `convex/auth.config.ts`
+- frontend app entry or provider wrapper
+- Auth0 CLI install docs: `https://auth0.github.io/auth0-cli/`
+- Auth0 environment variables commonly include:
+  - `AUTH0_DOMAIN`
+  - `AUTH0_CLIENT_ID`
+  - `VITE_AUTH0_DOMAIN`
+  - `VITE_AUTH0_CLIENT_ID`
+
+## Concrete Steps
+
+1. Start by reading `https://docs.convex.dev/auth/auth0` and the relevant Auth0
+   quickstart for the app's framework
+2. Ask whether the user wants the Auth0 CLI path
+3. If yes, install Auth0 CLI and have the user authenticate it with
+   `auth0 login`
+4. Use `auth0 apps create` with SPA settings, callback URL, logout URL, and web
+   origins if creating a new app
+5. If not using the CLI path, complete the relevant Auth0 frontend quickstart
+   and create the Auth0 app in the dashboard
+6. Get the Auth0 domain and client ID from the CLI output or the Auth0 dashboard
+7. Install the Auth0 SDK for the app's framework
+8. Create or update `convex/auth.config.ts` with the Auth0 domain and client ID
+9. Set frontend and backend environment variables
+10. Wrap the app in `Auth0Provider`
+11. Replace plain `ConvexProvider` wiring with `ConvexProviderWithAuth0`
+12. Run the normal Convex dev or deploy flow after backend config changes
+13. Try the official provider config shown in the Convex docs
+14. If login works but Convex auth or token refresh fails in a way you cannot
+    clearly resolve, stop and tell the user to follow the official docs manually
+    for now
+15. Only claim success if the user can sign in and Convex recognizes the
+    authenticated session
+16. If the user wants production-ready setup, configure the production Auth0
+    tenant values and production environment variables too
+
+## Gotchas
+
+- The Convex docs assume the Auth0 side is already set up, so do not skip the
+  Auth0 quickstart if the app is starting from scratch
+- The Auth0 CLI is often the fastest path for a fresh setup, but it still
+  requires the user to authenticate the CLI to their Auth0 tenant
+- If the user agrees to install the Auth0 CLI, do the mechanical setup yourself
+  instead of bouncing them through the dashboard
+- If login succeeds but Convex still reports unauthenticated, double-check
+  `convex/auth.config.ts` and whether the backend config was synced
+- We were able to automate Auth0 app creation and Convex config wiring, but we
+  did not fully validate the refresh-token path end to end
+- In validation, the documented `useRefreshTokens={true}` and
+  `cacheLocation="localstorage"` setup hit refresh-token failures, so do not
+  present that path as settled
+- If you hit Auth0 errors like `Unknown or invalid refresh token`, do not keep
+  inventing fixes indefinitely, send the user back to the official docs and
+  explain that this path is still under investigation
+- Keep dev and prod tenants separate if the project uses different Auth0
+  environments
+- Do not confuse "Auth0 login works" with "Convex can validate the Auth0 token".
+  Both need to work.
+- If the repo already uses Auth0, preserve existing redirect and tenant
+  configuration unless the user asked to change it.
+- Do not assume the local Auth0 tenant settings match production. Verify the
+  production domain, client ID, and callback URLs separately.
+- For local dev, make sure the Auth0 app settings match the app's real local
+  port for callback URLs, logout URLs, and web origins
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the production Auth0 tenant
+  values, callback URLs, and Convex deployment config are all covered
+- Verify production environment variables and redirect settings before calling
+  the task complete
+- Do not silently write a notes file into the repo by default. If the user wants
+  rollout or handoff docs, create one explicitly.
+
+## Validation
+
+- Verify the user can complete the Auth0 login flow
+- Verify Convex-authenticated UI renders only after Convex auth state is ready
+- Verify protected Convex queries succeed after login
+- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
+- Verify the Auth0 app settings match the real local callback and logout URLs
+  during development
+- If the Auth0 refresh-token path fails, mark the setup as not fully validated
+  and direct the user to the official docs instead of claiming the skill
+  completed successfully
+- If production-ready setup was requested, verify the production Auth0
+  configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants Auth0
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Complete the relevant Auth0 frontend setup
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Set environment variables
+- [ ] Verify Convex authenticated state after login, or explicitly tell the user
+      this path is still under investigation and send them to the official docs
+- [ ] If requested, configure the production deployment too
@@ -0,0 +1,141 @@
+# Clerk
+
+Official docs:
+
+- https://docs.convex.dev/auth/clerk
+- https://clerk.com/docs/guides/development/integrations/databases/convex
+
+Use this when the app already uses Clerk or the user wants Clerk's hosted auth
+features.
+
+## Workflow
+
+1. Confirm the user wants Clerk
+2. Make sure the user has a Clerk account and a Clerk application
+3. Determine the app framework:
+   - React
+   - Next.js
+   - TanStack Start
+4. Ask whether the user wants local-only setup or production-ready setup now
+5. Gather the Clerk keys and the Clerk Frontend API URL
+6. Follow the correct framework section in the official docs
+7. Complete the backend and client wiring
+8. Verify Convex reports the user as authenticated after login
+9. If the user wants production-ready setup, make sure the production Clerk
+   config is also covered
+
+## What To Do
+
+- Read the official Convex and Clerk guide before writing setup code
+- If the user does not already have Clerk set up, send them to
+  `https://dashboard.clerk.com/sign-up` to create an account and
+  `https://dashboard.clerk.com/apps/new` to create an application
+- Send the user to `https://dashboard.clerk.com/apps/setup/convex` if the Convex
+  integration is not already active
+- Match the guide to the app's framework, usually React, Next.js, or TanStack
+  Start
+- Use the official examples for `ConvexProviderWithClerk`, `ClerkProvider`, and
+  `useAuth`
+
+## Key Setup Areas
+
+- install the Clerk SDK for the framework in use
+- configure `convex/auth.config.ts` with the Clerk issuer domain
+- set the required Clerk environment variables
+- wrap the app with `ClerkProvider` and `ConvexProviderWithClerk`
+- use Convex auth-aware UI patterns such as `Authenticated`, `Unauthenticated`,
+  and `AuthLoading`
+
+## Files and Env Vars To Expect
+
+- `convex/auth.config.ts`
+- React or Vite client entry such as `src/main.tsx`
+- Next.js client wrapper for Convex if using App Router
+- Clerk account sign-up page: `https://dashboard.clerk.com/sign-up`
+- Clerk app creation page: `https://dashboard.clerk.com/apps/new`
+- Clerk Convex integration page: `https://dashboard.clerk.com/apps/setup/convex`
+- Clerk API keys page: `https://dashboard.clerk.com/last-active?path=api-keys`
+- Clerk environment variables:
+  - `CLERK_JWT_ISSUER_DOMAIN` for Convex backend validation in the Convex docs
+  - `CLERK_FRONTEND_API_URL` in the Clerk docs
+  - `VITE_CLERK_PUBLISHABLE_KEY` for Vite apps
+  - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` for Next.js apps
+  - `CLERK_SECRET_KEY` for Next.js server-side Clerk setup where required
+
+`CLERK_JWT_ISSUER_DOMAIN` and `CLERK_FRONTEND_API_URL` refer to the same Clerk
+Frontend API URL value. Do not treat them as two different URLs.
+
+## Concrete Steps
+
+1. If needed, create a Clerk account at `https://dashboard.clerk.com/sign-up`
+2. If needed, create a Clerk application at
+   `https://dashboard.clerk.com/apps/new`
+3. Open `https://dashboard.clerk.com/last-active?path=api-keys` and copy the
+   publishable key, plus the secret key for Next.js where needed
+4. Open `https://dashboard.clerk.com/apps/setup/convex`
+5. Activate the Convex integration in Clerk if it is not already active
+6. Copy the Clerk Frontend API URL shown there
+7. Install the Clerk package for the app's framework
+8. Create or update `convex/auth.config.ts` so Convex validates Clerk tokens
+9. Set the publishable key in the frontend environment
+10. Set the issuer domain or Frontend API URL so Convex can validate the JWT
+11. Replace plain `ConvexProvider` wiring with `ConvexProviderWithClerk`
+12. Wrap the app in `ClerkProvider`
+13. Use Convex auth helpers for authenticated rendering
+14. Run the normal Convex dev or deploy flow after updating backend auth config
+15. If the user wants production-ready setup, configure the production Clerk
+    values and production issuer domain too
+
+## Gotchas
+
+- Prefer `useConvexAuth()` over raw Clerk auth state when deciding whether
+  Convex-authenticated UI can render
+- For Next.js, keep server and client boundaries in mind when creating the
+  Convex provider wrapper
+- After changing `convex/auth.config.ts`, run the normal Convex dev or deploy
+  flow so the backend picks up the new config
+- Do not stop at "Clerk login works". The important check is that Convex also
+  sees the session and can authenticate requests.
+- If the repo already uses Clerk, preserve its existing auth flow unless the
+  user asked to change it.
+- Do not assume the same Clerk values work for both dev and production. Check
+  the production issuer domain and publishable key separately.
+- The Convex setup page is where you get the Clerk Frontend API URL for Convex.
+  Keep using the Clerk API keys page for the publishable key and the secret key.
+- If Convex says no auth provider matched the token, first confirm the Clerk
+  Convex integration was activated at
+  `https://dashboard.clerk.com/apps/setup/convex`
+- After activating the Clerk Convex integration, sign out completely and sign
+  back in before retesting. An old Clerk session can keep using a token that
+  Convex rejects.
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure production Clerk keys and issuer
+  configuration are included
+- Verify production redirect URLs and any production Clerk domain values before
+  calling the task complete
+- Do not silently write a notes file into the repo by default. If the user wants
+  rollout or handoff docs, create one explicitly.
+
+## Validation
+
+- Verify the user can sign in with Clerk
+- If the Clerk integration was just activated, verify after a full Clerk
+  sign-out and fresh sign-in
+- Verify `useConvexAuth()` reaches the authenticated state after Clerk login
+- Verify protected Convex queries run successfully inside authenticated UI
+- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
+- If production-ready setup was requested, verify the production Clerk
+  configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants Clerk
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Follow the correct framework section in the official guide
+- [ ] Set Clerk environment variables
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Verify Convex authenticated state after login
+- [ ] If requested, configure the production deployment too
@@ -0,0 +1,188 @@
+# Convex Auth
+
+Official docs: https://docs.convex.dev/auth/convex-auth Setup guide:
+https://labs.convex.dev/auth/setup
+
+Use this when the user wants auth handled directly in Convex rather than through
+a third-party provider.
+
+## Workflow
+
+1. Confirm the user wants Convex Auth specifically
+2. Determine which sign-in methods the app needs:
+   - magic links or OTPs
+   - OAuth providers
+   - passwords and password reset
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the Convex Auth setup guide before writing code
+5. Make sure the project has a configured Convex deployment:
+   - run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set
+   - if CLI configuration requires interactive human input, stop and ask the
+     user to complete that step before continuing
+6. Install the auth packages:
+   - `npm install @convex-dev/auth @auth/core@0.37.0`
+7. Run the initialization command:
+   - `npx @convex-dev/auth`
+8. Confirm the initializer created:
+   - `convex/auth.config.ts`
+   - `convex/auth.ts`
+   - `convex/http.ts`
+9. Add the required `authTables` to `convex/schema.ts`
+10. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider`
+11. Configure at least one auth method in `convex/auth.ts`
+12. Run `npx convex dev --once` or the normal dev flow to push the updated
+    schema and generated code
+13. Verify the client can sign in successfully
+14. Verify Convex receives authenticated identity in backend functions
+15. If the user wants production-ready setup, make sure the same auth setup is
+    configured for the production deployment as well
+16. Only add a `users` table and `storeUser` flow if the app needs app-level
+    user records inside Convex
+
+## What This Reference Is For
+
+- choosing Convex Auth as the default provider for a new Convex app
+- understanding whether the app wants magic links, OTPs, OAuth, or passwords
+- keeping the setup provider-specific while using the official Convex Auth docs
+  for identity and authorization behavior
+
+## What To Do
+
+- Read the Convex Auth setup guide before writing setup code
+- Follow the setup flow from the docs rather than recreating it from memory
+- If the app is new, consider starting from the official starter flow instead of
+  hand-wiring everything
+- Treat `npx @convex-dev/auth` as a required initialization step for existing
+  apps, not an optional extra
+
+## Concrete Steps
+
+1. Install `@convex-dev/auth` and `@auth/core@0.37.0`
+2. Run `npx convex dev` if the project does not already have a configured
+   deployment
+3. If `npx convex dev` blocks on interactive setup, ask the user explicitly to
+   finish configuring the Convex deployment
+4. Run `npx @convex-dev/auth`
+5. Confirm the generated auth setup is present before continuing:
+   - `convex/auth.config.ts`
+   - `convex/auth.ts`
+   - `convex/http.ts`
+6. Add `authTables` to `convex/schema.ts`
+7. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry
+8. Configure the selected auth methods in `convex/auth.ts`
+9. Run `npx convex dev --once` or the normal dev flow so the updated schema and
+   auth files are pushed
+10. Verify login locally
+11. If the user wants production-ready setup, repeat the required auth
+    configuration against the production deployment
+
+## Expected Files and Decisions
+
+- `convex/schema.ts`
+- frontend app entry such as `src/main.tsx` or the framework-equivalent provider
+  file
+- generated Convex Auth setup produced by `npx @convex-dev/auth`
+- an existing configured Convex deployment, or the ability to create one with
+  `npx convex dev`
+- `convex/auth.ts` starts with `providers: []` until the app configures actual
+  sign-in methods
+
+- Decide whether the user is creating a new app or adding auth to an existing
+  app
+- For a new app, prefer the official starter flow instead of rebuilding setup by
+  hand
+- Decide which auth methods the app needs:
+  - magic links or OTPs
+  - OAuth providers
+  - passwords
+- Decide whether the user wants local-only setup or production-ready setup now
+- Decide whether the app actually needs a `users` table inside Convex, or
+  whether provider identity alone is enough
+
+## Gotchas
+
+- Do not assume a specific sign-in method. Ask which methods the app needs
+  before wiring UI and backend behavior.
+- `npx @convex-dev/auth` is important because it initializes the auth setup,
+  including the key material. Do not skip it when adding Convex Auth to an
+  existing project.
+- `npx @convex-dev/auth` will fail if the project does not already have a
+  configured `CONVEX_DEPLOYMENT`.
+- `npx convex dev` may require interactive setup for deployment creation or
+  project selection. If that happens, ask the user explicitly for that human
+  step instead of guessing.
+- `npx @convex-dev/auth` does not finish the whole integration by itself. You
+  still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at
+  least one auth method.
+- A project can still build even if `convex/auth.ts` still has `providers: []`,
+  so do not treat a successful build as proof that sign-in is fully configured.
+- Convex Auth does not mean every app needs a `users` table. If the app only
+  needs authentication gates, `ctx.auth.getUserIdentity()` may be enough.
+- If the app is greenfield, starting from the official starter flow is usually
+  better than partially recreating it by hand.
+- Do not stop at local dev setup if the user expects production-ready auth. The
+  production deployment needs the auth setup too.
+- Keep provider-specific setup and Convex Auth authorization behavior in the
+  official docs instead of inventing shared patterns from memory.
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the auth configuration is applied
+  to the production deployment, not just the dev deployment
+- Verify production-specific redirect URLs, auth method configuration, and
+  deployment settings before calling the task complete
+- Do not silently write a notes file into the repo by default. If the user wants
+  rollout or handoff docs, create one explicitly.
+
+## Human Handoff
+
+If `npx convex dev` or deployment setup requires human input:
+
+- stop and explain exactly what the user needs to do
+- say why that step is required
+- resume the auth setup immediately after the user confirms it is done
+
+## Validation
+
+- Verify the user can complete a sign-in flow
+- Offer to validate sign up, sign out, and sign back in with the configured auth
+  method
+- If browser automation is available in the environment, you can do this
+  directly
+- If browser automation is not available, give the user a short manual
+  validation checklist instead
+- Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend
+  functions
+- Verify protected UI only renders after Convex-authenticated state is ready
+- Verify environment variables and redirect settings match the current app
+  environment
+- Verify `convex/auth.ts` no longer has an empty `providers: []` configuration
+  once the app is meant to support real sign-in
+- Run `npx convex dev --once` or the normal dev flow after setup changes and
+  confirm Convex codegen and push succeed
+- If production-ready setup was requested, verify the production deployment is
+  also configured correctly
+
+## Checklist
+
+- [ ] Confirm the user wants Convex Auth specifically
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Ensure a Convex deployment is configured before running auth
+      initialization
+- [ ] Install `@convex-dev/auth` and `@auth/core@0.37.0`
+- [ ] Run `npx convex dev` first if needed
+- [ ] Run `npx @convex-dev/auth`
+- [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts`
+      were created
+- [ ] Follow the setup guide for package install and wiring
+- [ ] Add `authTables` to `convex/schema.ts`
+- [ ] Replace `ConvexProvider` with `ConvexAuthProvider`
+- [ ] Configure at least one auth method in `convex/auth.ts`
+- [ ] Run `npx convex dev --once` or the normal dev flow after setup changes
+- [ ] Confirm which sign-in methods the app needs
+- [ ] Verify the client can sign in and the backend receives authenticated
+      identity
+- [ ] Offer end-to-end validation of sign up, sign out, and sign back in
+- [ ] If requested, configure the production deployment too
+- [ ] Only add extra `users` table sync if the app needs app-level user records
@@ -0,0 +1,147 @@
+# WorkOS AuthKit
+
+Official docs:
+
+- https://docs.convex.dev/auth/authkit/
+- https://docs.convex.dev/auth/authkit/add-to-app
+- https://docs.convex.dev/auth/authkit/auto-provision
+
+Use this when the app already uses WorkOS or the user wants AuthKit
+specifically.
+
+## Workflow
+
+1. Confirm the user wants WorkOS AuthKit
+2. Determine whether they want:
+   - a Convex-managed WorkOS team
+   - an existing WorkOS team
+3. Ask whether the user wants local-only setup or production-ready setup now
+4. Read the official Convex and WorkOS AuthKit guide
+5. Create or update `convex.json` for the app's framework and real local port
+6. Follow the correct branch of the setup flow based on that choice
+7. Configure the required WorkOS environment variables
+8. Configure `convex/auth.config.ts` for WorkOS-issued JWTs
+9. Wire the client provider and callback flow
+10. Verify authenticated requests reach Convex
+11. If the user wants production-ready setup, make sure the production WorkOS
+    configuration is covered too
+12. Only add `storeUser` or a `users` table if the app needs first-class user
+    rows inside Convex
+
+## What To Do
+
+- Read the official Convex and WorkOS AuthKit guide before writing setup code
+- Determine whether the user wants a Convex-managed WorkOS team or an existing
+  WorkOS team
+- Treat `convex.json` as a first-class part of the AuthKit setup, not an
+  optional extra
+- Follow the current setup flow from the docs instead of relying on older
+  examples
+
+## Key Setup Areas
+
+- package installation for the app's framework
+- `convex.json` with the `authKit` section for dev, and preview or prod if
+  needed
+- environment variables such as `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, and
+  redirect configuration
+- `convex/auth.config.ts` wiring for WorkOS-issued JWTs
+- client provider setup and token flow into Convex
+- login callback and redirect configuration
+
+## Files and Env Vars To Expect
+
+- `convex.json`
+- `convex/auth.config.ts`
+- frontend auth provider wiring
+- callback or redirect route setup where the framework requires it
+- WorkOS environment variables commonly include:
+  - `WORKOS_CLIENT_ID`
+  - `WORKOS_API_KEY`
+  - `WORKOS_COOKIE_PASSWORD`
+  - `VITE_WORKOS_CLIENT_ID`
+  - `VITE_WORKOS_REDIRECT_URI`
+  - `NEXT_PUBLIC_WORKOS_REDIRECT_URI`
+
+For a managed WorkOS team, `convex dev` can provision the AuthKit environment
+and write local env vars such as `VITE_WORKOS_CLIENT_ID` and
+`VITE_WORKOS_REDIRECT_URI` into `.env.local` for Vite apps.
+
+## Concrete Steps
+
+1. Choose Convex-managed or existing WorkOS team
+2. Create or update `convex.json` with the `authKit` section for the framework
+   in use
+3. Make sure the dev `redirectUris`, `appHomepageUrl`, `corsOrigins`, and local
+   redirect env vars match the app's actual local port
+4. For a managed WorkOS team, run `npx convex dev` and follow the interactive
+   onboarding flow
+5. For an existing WorkOS team, get `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` from
+   the WorkOS dashboard and set them with `npx convex env set`
+6. Create or update `convex/auth.config.ts` for WorkOS JWT validation
+7. Run the normal Convex dev or deploy flow so backend config is synced
+8. Wire the WorkOS client provider in the app
+9. Configure callback and redirect handling
+10. Verify the user can sign in and return to the app
+11. Verify Convex sees the authenticated user after login
+12. If the user wants production-ready setup, configure the production client
+    ID, API key, redirect URI, and deployment settings too
+
+## Gotchas
+
+- The docs split setup between Convex-managed and existing WorkOS teams, so ask
+  which path the user wants if it is not obvious
+- Keep dev and prod WorkOS configuration separate where the docs call for
+  different client IDs or API keys
+- Only add `storeUser` or a `users` table if the app needs first-class user rows
+  inside Convex
+- Do not mix dev and prod WorkOS credentials or redirect URIs
+- If the repo already contains WorkOS setup, preserve the current tenant model
+  unless the user wants to change it
+- For managed WorkOS setup, `convex dev` is interactive the first time. In
+  non-interactive terminals, stop and ask the user to complete the onboarding
+  prompts.
+- `convex.json` is not optional for the managed AuthKit flow. It drives redirect
+  URI, homepage URL, CORS configuration, and local env var generation.
+- If the frontend starts on a different port than the one in `convex.json`, the
+  hosted WorkOS sign-in flow will point to the wrong callback URL. Update
+  `convex.json`, update the local redirect env var, and run `npx convex dev`
+  again.
+- Vite can fall off `5173` if other apps are already running. Do not assume the
+  default port still matches the generated AuthKit config.
+- A successful WorkOS sign-in should redirect back to the local callback route
+  and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS
+  page loaded."
+
+## Production
+
+- Ask whether the user wants dev-only setup or production-ready setup
+- If the answer is production-ready, make sure the production WorkOS client ID,
+  API key, redirect URI, and Convex deployment config are all covered
+- Verify the production redirect and callback settings before calling the task
+  complete
+- Do not silently write a notes file into the repo by default. If the user wants
+  rollout or handoff docs, create one explicitly.
+
+## Validation
+
+- Verify the user can complete the login flow and return to the app
+- Verify the callback URL matches the real frontend port in local dev
+- Verify Convex receives authenticated requests after login
+- Verify `convex.json` matches the framework and chosen WorkOS setup path
+- Verify `convex/auth.config.ts` matches the chosen WorkOS setup path
+- Verify environment variables differ correctly between local and production
+  where needed
+- If production-ready setup was requested, verify the production WorkOS
+  configuration is also covered
+
+## Checklist
+
+- [ ] Confirm the user wants WorkOS AuthKit
+- [ ] Ask whether the user wants local-only setup or production-ready setup
+- [ ] Choose Convex-managed or existing WorkOS team
+- [ ] Create or update `convex.json`
+- [ ] Configure WorkOS environment variables
+- [ ] Configure `convex/auth.config.ts`
+- [ ] Verify authenticated requests reach Convex after login
+- [ ] If requested, configure the production deployment too
@@ -0,0 +1,75 @@
+---
+name: convex
+description: Routes general Convex requests to the right project skill. Use when the user
+  asks which Convex skill to use or gives an underspecified Convex app task.
+---
+
+# Convex
+
+Use this as the routing skill for Convex work in this repo.
+
+If a more specific Convex skill clearly matches the request, use that instead.
+
+## Start Here
+
+If the project does not already have Convex AI guidance installed, or the
+existing guidance looks stale, strongly recommend installing it first.
+
+Preferred:
+
+```bash
+npx convex ai-files install
+```
+
+This installs or refreshes the managed Convex AI files. It is the recommended
+starting point for getting the official Convex guidelines in place and following
+the current Convex AI setup described in the docs:
+
+- [Convex AI docs](https://docs.convex.dev/ai)
+
+Simple fallback:
+
+- [convex_rules.txt](https://convex.link/convex_rules.txt)
+
+Prefer `npx convex ai-files install` over copying rules by hand when possible.
+
+## Command Preflight
+
+Before running any `bunx convex ...` command in ClawHub, explicitly identify:
+
+- target runtime: `local`, `dev`, or `prod`
+- deployment: exact name or URL when known, such as `wry-manatee-359` for prod
+- code state: whether the function/schema changes have already been pushed with
+  `bunx convex dev --once`, `bunx convex deploy`, or the production deploy
+  workflow
+
+Use the current Convex CLI flag shape:
+
+- read data: `bunx convex data --deployment <deployment> <table>`
+- run a function: `bunx convex run --deployment <deployment> <function> '<json>'`
+- readonly inline query:
+  `bunx convex run --deployment <deployment> --inline-query '<query>'`
+- single-table import:
+  `bunx convex import --deployment <deployment> --table <table> --replace -y <file>`
+
+If `--env-file .env.local` produces `401 MissingAccessToken`, omit the env file
+and target the deployment directly with `--deployment <deployment>` or `--prod`.
+Do not use stale `--deployment-name` guidance.
+
+## Route to the Right Skill
+
+After that, use the most specific Convex skill for the task:
+
+- New project or adding Convex to an app: `convex-quickstart`
+- Authentication setup: `convex-setup-auth`
+- Building a reusable Convex component: `convex-create-component`
+- Planning or running a migration: `convex-migration-helper`
+- Investigating performance issues: `convex-performance-audit`
+
+If one of those clearly matches the user's goal, switch to it instead of staying
+in this skill.
+
+## When Not to Use
+
+- The user has already named a more specific Convex workflow
+- Another Convex skill obviously fits the request better
@@ -0,0 +1,194 @@
+---
+name: create-and-cleanup-migration
+description: Use for end-to-end ClawHub Convex production migrations, backfills, destructive cleanups, and one-off maintenance functions that must be created, validated, shipped, run, verified, then removed after completion.
+---
+
+# Create And Cleanup Migration
+
+Drive a ClawHub Convex migration from implementation through production cleanup,
+with explicit operator gates before destructive execution and before removing the
+temporary migration code.
+
+## When To Use
+
+- A Convex production data migration, backfill, destructive cleanup, schema
+  narrowing, table reshaping, or one-off maintenance function is needed.
+- Temporary Convex code must be created, deployed, run, verified, and then
+  removed after it is no longer useful.
+- The user asks for the full lifecycle: implement migration, PR, deploy, dry run,
+  apply, verify, cleanup PR, deploy cleanup.
+
+## Required Companion Guidance
+
+1. Start with `convex-migration-helper`.
+2. Read `convex/_generated/ai/guidelines.md` before editing Convex code.
+3. Default to `@convex-dev/migrations` for production data changes.
+4. If not using `@convex-dev/migrations`, write down why the component is
+   unnecessary and provide equivalent:
+   - dry-run support
+   - cursor batching
+   - resumable/progress behavior
+   - destructive confirmation token
+   - real Convex runtime validation
+
+## Safety Rules
+
+- Never run a destructive production apply step until after presenting dry-run
+  results and receiving explicit user confirmation in the current thread.
+- Before implementing anything, classify the requested "migration" as one of:
+  code deploy, existing Convex function run, operator import/export command,
+  schema narrowing, data cleanup, or cleanup-code removal. Do not invent a new
+  Convex migration function when the issue or PR specifies an operator command
+  such as `convex import --replace`.
+- Before any production migration apply, force the operator to visit
+  `https://dashboard.convex.dev/`, manually click **Backup Now** on the target
+  deployment, wait for completion, and explicitly confirm in the thread. Do not
+  automate dashboard backup creation.
+- Never remove migration code until after presenting apply/verification results
+  and receiving explicit user confirmation in the current thread.
+- Keep production commands pointed at the explicit deployment name when known;
+  do not rely on generic `--prod` if this repo's guidance says to verify the
+  actual deployment.
+- If the migration can affect visibility, moderation, ownership, billing,
+  installability, or public API output, call that out before the apply gate.
+- Preserve resume cursors, run IDs, PR URLs, deploy URLs, and final stats in the
+  handoff.
+
+## Phase 1: Design The Migration
+
+1. Identify the intended data change and whether it is:
+   - schema widen/migrate/narrow
+   - field cleanup
+   - table cleanup
+   - ownership/relationship repair
+   - recurring maintenance
+2. Choose the implementation:
+   - Prefer `@convex-dev/migrations` for non-trivial production data.
+   - Use a hand-rolled internal function only for a clearly small or special
+     case, and document the exception.
+3. Define done criteria:
+   - dry-run expected counts
+   - apply expected counts
+   - verification query/result proving no remaining targets
+   - cleanup PR scope
+
+## Phase 2: Implement
+
+1. Add or update the Convex migration/maintenance code.
+2. Include argument validators for every Convex function.
+3. Include dry-run support.
+4. Include batching and resume/progress state.
+5. Include a confirmation token for destructive writes.
+6. Keep apply logic idempotent where practical.
+7. Add targeted tests for business logic and safety gates.
+8. Add real Convex runtime validation for Convex semantics such as pagination,
+   validators, internal/public function boundaries, scheduler behavior, and
+   action/query/mutation interactions.
+
+## Phase 3: Local Validation
+
+Run the smallest meaningful set first, then broaden before PR handoff:
+
+- targeted unit tests for the migration logic
+- `bunx convex codegen` when Convex API/schema changed
+- `bunx tsc --noEmit` or the repo's Convex deploy typecheck path
+- `bun run ci:static`
+- `bun run ci:unit` for source/test changes unless explicitly waived
+- a real local Convex validation path, such as `bunx convex dev --once`,
+  `convex run`, HTTP smoke, or local-auth Playwright, covering the changed
+  Convex behavior
+
+If local real Convex validation is blocked, record the blocker and make the PR
+or deployment plan explicitly compensate with an equivalent runtime proof.
+
+## Phase 4: PR, Review, Merge, Deploy
+
+1. Open a focused PR containing the migration implementation.
+2. Include:
+   - summary
+   - migration strategy
+   - dry-run/apply safety gates
+   - tests and runtime validation
+   - cleanup plan
+3. Run the repo's review/CI workflow required by `AGENTS.md`.
+4. Address actionable review findings.
+5. Merge only after required checks are green or the user explicitly accepts a
+   documented risk.
+6. Deploy the relevant production target from `main`.
+7. Wait for deployment success before starting the manual backup gate.
+
+## Phase 5: Manual Backup Gate
+
+Before any production dry run or production migration apply:
+
+1. Tell the operator to open `https://dashboard.convex.dev/`.
+2. Tell the operator to select the target deployment and manually click
+   **Backup Now**.
+3. Wait until the Convex dashboard shows that the backup completed.
+4. Require the operator to explicitly confirm in the thread that the dashboard
+   backup completed for the target deployment.
+5. Do not automate this step and do not proceed on implied confirmation,
+   partial screenshots, or "go ahead" messages that do not say the backup
+   completed.
+
+## Phase 6: Production Dry Run
+
+1. Run only after explicit user confirmation from the manual backup gate.
+2. Run the production dry run with bounded batch settings.
+3. Resume until either:
+   - `isDone: true`, or
+   - a clearly documented safety cap is reached.
+4. Present results to the user before apply:
+   - deployment name
+   - command shape
+   - `dryRun`
+   - `isDone`
+   - done/progress fields
+   - scanned/matched/patched/deleted stats
+   - sample IDs
+   - resume cursors if incomplete
+   - known user-visible or operational implications
+5. Stop and wait for explicit user confirmation before applying.
+
+## Phase 7: Production Apply
+
+1. Run only after explicit user confirmation of the dry-run results and the
+   completed manual backup gate.
+2. Use the destructive confirmation token.
+3. Resume in bounded batches until complete or until a documented safety cap.
+4. Present apply results:
+   - patched/deleted counts
+   - skipped/missing counts if tracked
+   - final cursors/progress
+   - any errors or partial completion
+5. Run verification:
+   - dry run or status command should show zero remaining targets, or
+   - explain why remaining targets are expected.
+6. Stop and wait for explicit user confirmation before cleanup-code removal.
+
+## Phase 8: Cleanup PR
+
+1. Remove temporary migration functions, tests, docs, scripts, and generated API
+   entries that are no longer needed.
+2. Keep durable specs/docs only if they explain lasting behavior or invariants.
+3. Run targeted validation plus the repo-required gates for the touched surface.
+4. Open a cleanup PR with:
+   - apply results
+   - verification proof
+   - explanation of removed temporary code
+5. Merge after checks/review.
+6. Deploy the cleanup PR if removing Convex functions or schema/code that affects
+   production.
+
+## Final Handoff
+
+Report:
+
+- implementation PR URL and merge SHA
+- production deploy run URL and deployed SHA
+- dry-run result
+- manual Convex dashboard backup confirmation
+- apply result
+- verification result
+- cleanup PR URL, merge SHA, and deploy run URL
+- any remaining follow-up tasks or intentional retained migration code
@@ -0,0 +1,79 @@
+---
+name: technical-documentation
+description: Build and review high-quality technical docs as well as agent instruction files in your repository.
+license: MIT
+metadata:
+  source: "https://github.com/vincentkoc/dotskills"
+---
+
+# Technical Documentation
+
+## Purpose
+
+Produce and review technical documentation that is clear, actionable, and maintainable for both humans and agents, including contributor-governance files and agent instruction files.
+
+## When to use
+
+- Creating or overhauling docs in an existing product/codebase (brownfield).
+- Building evergreen docs meant to stay accurate and reusable over time.
+- Reviewing doc diffs for structure, clarity, and operational correctness.
+- Running full-repo documentation audits that must include both governance files and product docs surfaces (`docs/`, `README*`, `.md/.mdx/.mdc`, Fern/Sphinx/Mintlify-style sources).
+- Updating or reviewing AGENTS.md and/or CONTRIBUTING.md to keep agent and contributor workflows aligned with current repo practices.
+- Improving repository onboarding/docs that include contribution instructions, issue templates, PR flow, and review gates.
+- Designing governance documentation strategy for repos with alias instruction files (for example `CLAUDE.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`) where `AGENTS.md` is treated as canonical when present and aliases should be kept as compatibility surfaces.
+- Diagnosing agent-file drift where teams had to prompt iteratively to surface missing files, broken commands, or policy conflicts.
+- Applying repository-specific documentation overlays, including OpenClaw page-type, docs IA, preservation, and validation rules when present.
+
+## Workflow
+
+1. Classify task: `build` or `review`; context: `brownfield` or `evergreen`.
+2. Inventory full documentation scope early (governance + product docs): AGENTS/CONTRIBUTING/aliases plus docs directories, framework sources, and root/module READMEs.
+3. Detect multilingual scope (README/docs in multiple languages) and define required parity level.
+4. Read `references/agent-and-contributing.md` for agent instruction and `CONTRIBUTING.md` workflow rules (inventory, canonical/alias mapping, dual-mode balance, deliverable standards, and precedence/conflict handling).
+5. Read `references/principles.md` for the governing ruleset (Matt Palmer & OpenAI).
+6. For OpenClaw docs work, read `references/openclaw.md` before the build/review playbook.
+7. For build tasks, follow `references/build.md`.
+8. For review tasks, follow `references/review.md` and proactively detect issues without waiting for repeated prompts.
+9. For complex or high-risk tasks (build or review), it is acceptable to run longer, deeper, and more exhaustive investigations when needed for confidence.
+10. When available, use sub-agents for bounded parallel discovery/review work, then merge outputs into one coherent final deliverable.
+11. Use `references/tooling.md` when platform/tooling choices affect recommendations.
+12. Run a proactive issue sweep for both governance and docs-content surfaces, and fix high-confidence defects in the same pass unless explicitly asked for report-only mode.
+13. In brownfield mode, prioritize compatibility with current docs IA, tooling, and release state.
+14. In evergreen mode, prioritize timeless wording, update strategy, and durable structure.
+15. Return deliverables plus validation notes, parity status, and remaining gaps.
+
+## Sub-agent orchestration guidance
+
+Prefer sub-agents when the repo is large or the requested change set is broad; use them by default for repo-wide, multi-framework, or high-conflict work.
+
+- `inventory-agent` -> `agents/inventory-agent.md` (`fast` / Claude `haiku`): file/config discovery, coverage map, and missing-path checks.
+- `governance-agent` -> `agents/governance-agent.md` (`thinking` / Claude `sonnet`): AGENTS/CONTRIBUTING/alias precedence, conflicts, and policy drift.
+- `docs-framework-agent` -> `agents/docs-framework-agent.md` (`thinking` / Claude `sonnet`): framework config, relative path base, and file-path vs URL-path mapping checks.
+- `synthesis-agent` -> `agents/synthesis-agent.md` (`long` / Claude `opus`): merge sub-agent outputs into one prioritized fix plan and unified precedence model.
+
+## Inputs
+
+- Doc type (tutorial, how-to, reference, explanation) and audience.
+- File scope or diff scope.
+- Docs framework/tooling constraints (Fern, Mintlify, Sphinx, etc.).
+- Build/review mode and brownfield/evergreen intent.
+- Target agent and human compatibility intent.
+- Docs framework surfaces in scope (for example Fern, Sphinx, Mintlify, Markdown/MDX/MDC/RST/RSC files).
+- Desired investigation depth/time budget (quick pass vs exhaustive review).
+- Execution mode (`single-agent` or `sub-agent-assisted` when available).
+- Remediation mode (`apply-fixes` by default, or `report-only` when requested).
+- Multilingual scope: source-of-truth language, target locales, and parity expectations.
+- Repository-specific overlay constraints, if any.
+
+## Outputs
+
+- Updated draft or review findings with clear next actions.
+- Validation notes (what was checked, what remains).
+- Navigation/maintenance recommendations for long-term quality.
+- Governance-doc alignment summary when AGENTS/CONTRIBUTING were touched.
+- Agent instruction-surface map (primary file, alias files, Codex/Claude/Cursor handling plan).
+- Documentation-surface coverage map (what was reviewed under `/docs`, README hierarchy, and framework-specific source trees).
+- Autodetected issue list with applied fixes (or explicit report-only findings).
+- Delegation notes when sub-agents were used (scope delegated and how findings were merged).
+- Multilingual parity note (in-sync, partial with rationale, or intentionally divergent).
+- Repository-specific overlay notes when one was used.
@@ -0,0 +1,32 @@
+---
+name: docs-framework-agent
+description: Thinking-focused docs framework checker for config-relative paths and route/file mapping consistency.
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+permissionMode: default
+maxTurns: 10
+---
+
+You are the docs-framework sub-agent for technical documentation.
+
+Goals:
+
+- validate framework config-driven docs behavior
+- prevent path-mapping drift between source files and published routes
+
+Tasks:
+
+- detect and read framework config first (Fern/Sphinx/Mintlify/custom)
+- resolve paths relative to the declaring file/config
+- validate both maps:
+  - config -> file exists
+  - config/nav/routing -> URL path is valid and consistent
+
+Return:
+
+- config files reviewed
+- path assumptions made
+- mismatches (`missing file`, `stale route`, `wrong base path`)
@@ -0,0 +1,30 @@
+---
+name: governance-agent
+description: Thinking-focused governance reviewer for AGENTS/CONTRIBUTING/alias precedence, conflict detection, and policy drift analysis.
+model: sonnet
+tools:
+  - Read
+  - Glob
+  - Grep
+permissionMode: default
+maxTurns: 10
+---
+
+You are the governance sub-agent for technical documentation.
+
+Goals:
+
+- validate AGENTS/CONTRIBUTING/alias alignment and precedence
+- identify policy drift and conflicting instructions
+
+Tasks:
+
+- determine canonical instruction source and alias compatibility mapping
+- detect conflicts across nested scope files and tool-specific rule consumers
+- validate command examples against stated governance expectations
+
+Return:
+
+- precedence model
+- conflict list with severity
+- recommended low-risk remediations
@@ -0,0 +1,31 @@
+---
+name: inventory-agent
+description: Fast repo-surface discovery for technical documentation audits. Use for coverage mapping and missing-path detection before deeper review.
+model: haiku
+tools:
+  - Read
+  - Glob
+  - Grep
+  - LS
+permissionMode: default
+maxTurns: 6
+---
+
+You are the inventory sub-agent for technical documentation.
+
+Goals:
+
+- enumerate governance and docs-content surfaces in scope
+- detect missing files, broken references, and obvious command/path failures
+
+Tasks:
+
+- map `AGENTS.md`/`CONTRIBUTING.md`/aliases and docs surfaces (`docs/**`, README hierarchy, `.md/.mdx/.mdc/.rst/.rsc`)
+- list framework config files discovered (Fern/Sphinx/Mintlify or equivalent)
+- report hard failures only, with exact file paths
+
+Return:
+
+- coverage map
+- missing/broken path list
+- unresolved blockers
@@ -0,0 +1,10 @@
+interface:
+  display_name: "Technical Documentation"
+  short_description: "Build and review technical documentation for brownfield and evergreen systems."
+  icon_small: "./assets/icon.jpg"
+  icon_large: "./assets/icon.jpg"
+  brand_color: "#111827"
+  default_prompt: "Build or review technical documentation with a clear, maintainable, and production-ready workflow."
+
+policy:
+  allow_implicit_invocation: true
@@ -0,0 +1,28 @@
+---
+name: synthesis-agent
+description: Long-context synthesis agent that merges sub-agent outputs into one prioritized and deduplicated documentation action plan.
+model: opus
+tools:
+  - Read
+permissionMode: default
+maxTurns: 12
+---
+
+You are the synthesis sub-agent for technical documentation.
+
+Goal:
+
+- merge sub-agent outputs into one coherent, non-duplicated action plan
+
+Tasks:
+
+- prioritize blockers first, then non-blocking improvements
+- normalize to one precedence model for governance decisions
+- remove duplicated recommendations and contradictory fixes
+- keep final output concise and execution-ready
+
+Return:
+
+- prioritized fix plan
+- validation summary (done vs pending)
+- explicit remaining gaps/blockers
@@ -0,0 +1,145 @@
+# AGENT and CONTRIBUTING Principles
+
+This reference consolidates the core rules for agent-policy and contributor-governance docs.
+
+You must:
+
+1. Discover repo-level and nested instruction files with:
+   `rg --files -g 'AGENTS.md' -g 'CONTRIBUTING.md' -g 'CLAUDE.md' -g 'AGENT.md' -g '.cursor/rules/*' -g '.cursorrules' -g '.agent/**' -g '.agents/**' -g '.pi/**' -g 'AGENTS.*.md'`
+2. Read the root and nearest-scope `AGENTS.md`/`CONTRIBUTING.md` pair before editing.
+3. If alias files exist, normalize to one canonical source (`AGENTS.md` preferred when present; otherwise nearest alias), plus compatibility pointers or explicit symlink notes.
+4. Document conflicting instructions and precedence decisions.
+
+## GitHub + AGENTS baseline
+
+Source: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors
+Source: https://agents.md/
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://cobusgreyling.substack.com/p/what-is-agentsmd
+Source: https://www.infoq.com/news/2025/08/agents-md/
+
+Use these as default operating principles:
+
+1. Keep `CONTRIBUTING.md` discoverable and actionable (`.github`, root, or `docs`).
+2. Keep agent instructions concrete: real commands, real paths, clear boundaries.
+3. Use explicit behavior boundaries for agents: `Always`, `Ask first`, `Never`.
+4. Keep contributor and agent rules aligned with actual repository workflows.
+5. Ensure clear guidance is provided to agents on if, when and how to raise issues and pull requests.
+
+## Canonical and alias policy
+
+Source: https://agents.md/
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+
+1. Treat `AGENTS.md` as canonical when present.
+2. If `AGENTS.md` is absent, treat the nearest alias file as canonical.
+3. Keep compatibility surfaces explicit: `AGENTS.md`, `AGENT.md`, `.cursorrules`, `.cursor/rules/*`, `.agent/`, `.agents/`, `.pi/`.
+4. If aliases are used, document how they map back to canonical policy (or symlink when supported).
+5. When repos use `.agents/` as canonical rule storage, keep `.cursor` as a compatibility symlink to `.agents` for Cursor rule auto-loading.
+6. Keep policy DRY: store one shared policy core and expose it via aliases/symlinks instead of duplicating rule text.
+
+## Context-awareness by agent platform
+
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+
+1. For Cursor and Claude-style glob consumers, keep rule files narrow and bounded.
+2. Avoid over-referencing large path sets that inflate context for glob-based agents.
+3. For Codex-style workflows, prefer explicit file references and deterministic commands.
+4. Keep long runbooks outside top-level policy files; link to scoped docs.
+5. Ensure all agents have a happy path regardless so ensuring everything works across Codex, Claude and other coding agents.
+
+## Symlink and compatibility operations
+
+1. Preferred layout for multi-agent compatibility:
+   - canonical rule directory: `.agents/`
+   - Cursor compatibility path: `.cursor -> .agents` symlink
+   - canonical policy doc: `AGENTS.md` pointing to `.agents` paths where relevant
+2. Validate symlink state before finalizing changes:
+   - if `.agents/` exists and `.cursor` is missing, create `.cursor` symlink to `.agents`
+   - if `.cursor` is a symlink to another target, fix target or document why it must differ
+   - if `.cursor` is a real directory/file, treat as migration conflict and ask before replacement
+3. Validate rule payload through the canonical directory:
+   - rules: `.agents/rules/*.mdc` with valid frontmatter (`description`, `globs`, `alwaysApply` as needed)
+   - commands: `.agents/commands/*.md` when command routing is used
+   - MCP config: `.agents/mcp.json` when MCP is in scope
+4. Keep Codex behavior explicit:
+   - `AGENTS.md` is primary for Codex repository instructions
+   - `.cursor` compatibility is for Cursor auto-loading and does not replace canonical AGENTS policy
+5. Record applied symlink fixes and unresolved compatibility gaps in validation notes.
+
+## Dual-mode and deliverable standards
+
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://agents.md/
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+
+1. Author one shared policy core (same commands, boundaries, and precedence) for all agents.
+2. For Cursor/Claude-style agents, expose that core through glob-driven and bounded files (small `AGENTS.md`/rule surface).
+3. For Codex, expose that same core through explicit file references with precise scope.
+4. Where styles diverge, prefer the smallest common structure that satisfies both and avoid duplicating policy text.
+5. Treat AGENTS/CONTRIBUTING as first-class deliverables when in scope.
+6. Preserve required structure, constraints, and examples from existing files.
+7. Align wording and commands with active repository instructions.
+
+## Proactive issue discovery and remediation
+
+Source: https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+
+1. Run a conflict matrix review across AGENTS/aliases/CONTRIBUTING and related command/rule docs before finalizing.
+2. Treat the following as high-priority defects: missing referenced files, non-existent setup commands, command scope mismatches, and branch/commit policy conflicts.
+3. Do not stop at caveat-only notes when a low-risk fix is clear; apply the fix in the same pass.
+4. If a canonical entry file is missing (for example a directory `README.md` that docs depend on), create a minimal actionable file and update references.
+5. Long-running investigations are acceptable when needed to uncover cross-file drift, especially in agent-instruction ecosystems.
+
+## Discovery
+
+1. Agents prefer simple terminal commands so having a well defined `make *` or `npm run *` is ideal
+2. Agents can discover terminal commands through shell completion so providing shell completion helps
+
+## CONTRIBUTING size and scope control
+
+Source: https://contributing.md/how-to-build-contributing-md/
+Source: https://blog.codacy.com/best-practices-to-manage-an-open-source-project
+Source: https://mozillascience.github.io/working-open-workshop/contributing/
+Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md
+
+1. Keep root `CONTRIBUTING.md` focused on setup, issue flow, PR flow, testing, and review gates.
+2. Use issue/PR template links instead of embedding every process detail inline.
+3. When the file grows too large, split by domain and link from root.
+4. Move any large content into docs if avalible (for example Mintlify/Fern/Sphinx workflows) to avoid large contributor guide.
+5. Optimize for agent/machine readability as well as humans.
+
+## Example repos to emulate
+
+Source: https://github.com/openclaw/openclaw/blob/main/AGENTS.md
+Source: https://github.com/openclaw/openclaw/blob/main/CONTRIBUTING.md
+Source: https://github.com/openclaw/openclaw/blob/main/VISION.md
+Source: https://github.com/openai/codex/blob/main/AGENTS.md
+Source: https://github.com/processing/p5.js/blob/main/AGENTS.md
+Source: https://github.com/vercel-labs/agent-skills/blob/main/AGENTS.md
+Source: https://github.com/agentsmd/agents.md/blob/main/AGENTS.md
+Source: https://github.com/rails/rails/blob/main/CONTRIBUTING.md
+Source: https://github.com/kubernetes/kubernetes/blob/master/CONTRIBUTING.md
+Source: https://github.com/atom/atom/blob/master/CONTRIBUTING.md
+Source: https://github.com/github/docs/blob/main/CONTRIBUTING.md
+Source: https://github.com/facebook/react/blob/main/CONTRIBUTING.md
+
+1. OpenClaw: strong real-world alias policy and AGENTS/CONTRIBUTING/VISION cohesion.
+2. OpenAI Codex: strict command discipline and explicit scope control.
+3. p5.js: explicit AI-policy guardrails in agent instructions.
+4. Vercel + agentsmd spec: compact, context-efficient AGENTS patterns.
+5. Rails/Kubernetes/Atom/GitHub Docs/React: contributor guidance patterns at different project scales.
+
+## Practical merge policy
+
+When these rules conflict:
+
+1. Preserve contributor and reader task success first.
+2. Preserve instruction clarity and unambiguous boundaries second.
+3. Preserve long-term maintainability and context-efficiency third.
+4. Add extra agent optimization only if it does not reduce human clarity or there is explict need.
+5. Use your judgement as the expert.
@@ -0,0 +1,116 @@
+# Build Docs Playbook
+
+Read `principles.md` first, then follow this execution flow.
+
+## 1. Detect and align agent instruction and governance instructions
+
+- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling.
+- Apply the symlink compatibility policy when in scope (`.agents` canonical directory with `.cursor` compatibility symlink when required by tooling).
+- Long-running and extensive build investigations are acceptable when needed to resolve ambiguous or conflicting documentation sources.
+- When available, use sub-agents for bounded parallel inventory/cross-check tasks and merge results into one canonical decision set.
+- Capture required constraints before writing:
+  - nested-agent rules, command/test requirements, PR workflow, and style checks.
+- Use the same command and validation expectations in proposed snippets and examples.
+
+## 2. Inventory product documentation surfaces (not governance only)
+
+- For repo-wide builds, include docs content surfaces in addition to AGENTS/CONTRIBUTING.
+- Inventory docs files and frameworks in scope (examples): `README*.md`, `docs/**`, `**/*.md`, `**/*.mdx`, `**/*.mdc`, `**/*.rst`, `**/*.rsc`, Fern/Mintlify config, Sphinx `conf.py`.
+- Build a coverage map before drafting so governance and product docs are both represented.
+- If scope is ambiguous, default to broader docs discovery first, then narrow intentionally.
+
+## 3. Framework config and path mapping rules
+
+- Detect framework/config first (for example Fern config, Sphinx `conf.py`, Mintlify config, or equivalent).
+- Resolve every referenced path relative to the file/config that declares it, not assumed repo root.
+- Treat filesystem paths and published URL routes as separate mappings; do not infer one from the other without config evidence.
+- Validate both layers:
+  - config -> file exists on disk
+  - config/nav/routing -> URL path is consistent and reachable
+- Record path-mapping assumptions and mismatches in handoff (`missing file`, `stale route`, `wrong base path`).
+
+## 4. Define intent and success
+
+- Audience, prerequisites, and job-to-be-done.
+- Expected reader outcome immediately after completion.
+- Doc type: tutorial, how-to, reference, explanation.
+- Success criteria: what must be true after publish.
+
+## 5. Build structure before prose
+
+- Follow the funnel: what/why, quickstart, next steps.
+- Keep headings informative and scannable.
+- Open each section with the takeaway sentence.
+- Add decision points with concrete branch guidance.
+- For OpenClaw docs work, choose a page type from `references/openclaw.md` before drafting.
+- Keep task-critical OpenClaw configuration inline; link exhaustive defaults, enums, schemas, generated references, and rare debugging workflows.
+
+## 6. Build AGENTS.md and CONTRIBUTING.md intentionally
+
+- Keep AGENTS.md structure consistent with `agents.md` ecosystem patterns:
+  - include YAML frontmatter when present in repo style (`name`, `description`).
+  - state persona scope and explicit instruction boundaries: `Always`, `Ask first`, `Never`.
+  - include concrete commands and representative code examples.
+- For CONTRIBUTING.md, prioritize issue triage flow, PR expectations, setup/test commands, and review gates.
+- Add `Code of Conduct`, `Testing`, `Local checks`, and `PR expectations` sections when missing but required by the repo.
+- If CONTRIBUTING.md is becoming too large, split by scope into linked docs (for example, framework/tool-specific setup and release workflows) and keep the root file as a concise entry point.
+- Keep cross-file consistency: links from CONTRIBUTING.md to AGENTS.md (and vice versa) should be accurate and non-circular.
+- If multiple AGENTS.md files exist, document the directory-level scope and avoid conflicting advice.
+- If a required canonical entry file is missing (for example referenced `README.md` under a major directory), create the file in the same pass instead of adding a caveat-only note.
+- For new entry files, keep them minimal and actionable: purpose, prerequisites, concrete run commands, and pointers to deeper docs.
+
+## 7. Keep agent context tight
+
+- Author once, expose twice:
+  - keep one shared policy core and avoid duplicating guidance in separate agent-specific files.
+  - publish that core through bounded glob-friendly files for Cursor/Claude plus explicit path references for Codex.
+- For Cursor and Claude-style agents, avoid broad references. Use minimal globbing and narrow rule files that each serve one concern (for example, repo-wide setup, test rules, security checks).
+- Keep AGENTS and alias files short-to-medium; move detailed runbooks to linked docs.
+- For Codex, prefer explicit file references and concrete paths for exact reuse.
+- Avoid adding unrelated historical or process details to avoid token/context drift during future tool reads.
+
+## 8. Brownfield build mode
+
+- Match existing terminology, navigation, and component patterns.
+- Preserve existing IA unless there is a documented migration plan.
+- For rewrites, include a migration note from old to new paths.
+- Prefer smallest safe change set that improves utility.
+
+## 9. Evergreen build mode
+
+- Prefer stable concepts over release-tied narrative.
+- Isolate volatile details under clearly marked version sections.
+- Include maintenance signals: owners, refresh triggers, stale criteria.
+- Include lifecycle notes: deprecation and replacement paths.
+
+## 10. Writing constraints
+
+- Use precise language and short, imperative instructions.
+- Keep code examples copy-ready and self-contained.
+- Include common failure modes and safe defaults.
+- Avoid placeholder guidance that cannot be executed.
+
+## 11. Agent and automation readiness
+
+- Keep key facts in text (not image-only).
+- Prefer structured lists/tables when choices matter.
+- Add links and anchors that allow deterministic navigation.
+- Document what can be checked automatically in CI.
+
+## 12. Build validation
+
+- Validate commands and snippets where possible.
+- Verify links and references in changed sections.
+- Run a reference existence sweep for every path/command you introduced.
+- Verify docs-framework consistency when in scope (for example Sphinx/Fern config and referenced doc paths).
+- For OpenClaw docs work, apply the validation checklist in `references/openclaw.md`.
+
+## 13. Multilingual parity mode (when applicable)
+
+- Pick one source-of-truth language for technical accuracy and release timing.
+- Define parity target: full parity, staged parity, or intentional divergence per section.
+- Keep structure aligned across locales (headings, anchors, section order) when possible.
+- Preserve command/code correctness first; localize explanatory text second.
+- If parity is not feasible, add a visible note with missing scope and expected sync window.
+- Run a locale parity check for changed sections (added/removed steps, warnings, prerequisites).
+- Record unresolved checks explicitly in handoff.
@@ -0,0 +1,128 @@
+# OpenClaw Documentation Overlay
+
+Use this reference only for OpenClaw docs work. It layers OpenClaw-specific page
+types, navigation, preservation, and validation rules on top of the general
+technical-documentation skill.
+
+## Reader Model
+
+- Lead with the task the reader is trying to complete.
+- Give one recommended path before alternatives.
+- Keep main docs focused on the common path; move dense contracts and rare
+  debugging detail to linked reference or troubleshooting pages.
+- Explain production risks exactly where the reader can make the mistake.
+- Link concepts, guides, references, CLI pages, SDK docs, testing, and
+  troubleshooting so readers can continue without rereading.
+
+## Page Types
+
+Choose the page type before writing or reviewing:
+
+- Overview: route readers to the right product area, integration path, or guide.
+- Quickstart: get a new user to a working result with the fewest safe steps.
+- Topic page: explain a major OpenClaw entity or surface end to end.
+- Guide: walk through one workflow from prerequisites to production readiness.
+- API/SDK/CLI reference: define every object, method, command, option, response,
+  error, enum, default, and version rule in scope.
+- Testing guide: show sandbox setup, fixtures, simulated failures, and live-mode
+  differences.
+- Troubleshooting guide: map observable symptoms to checks, causes, and fixes.
+- Governance file: keep agent/contributor policy concrete, scoped, and aligned
+  with current OpenClaw repo behavior.
+
+## Topic Pages
+
+Use this shape for major-entity pages:
+
+1. Title naming the entity or surface.
+2. Unheaded opening that says what it is, what it owns, and what it does not own.
+3. Requirements, only when setup needs accounts, versions, permissions, plugins,
+   operating systems, or credentials.
+4. Quickstart with the recommended path and smallest reliable verification.
+5. Configuration with task-critical options inline and exhaustive details linked
+   to reference docs.
+6. Major subtopics organized by reader intent, not under a generic "Subtopics"
+   heading.
+7. Troubleshooting with observable failures and concrete checks.
+8. Related links to guides, references, commands, concepts, and adjacent topics.
+
+## Guides
+
+Use this shape for workflow pages:
+
+1. Title naming the outcome, not the implementation detail.
+2. Opening that states what the reader can accomplish.
+3. Before you begin: accounts, keys, permissions, versions, tools, and
+   assumptions.
+4. Choose a path, only when the reader must decide.
+5. Steps with verb-led headings, commands, expected output, and checks.
+6. Test with the smallest reliable proof that the workflow works.
+7. Production readiness: security, retries, limits, observability, migrations,
+   and cleanup.
+8. Troubleshooting near the workflow that causes the failures.
+9. See also links to concepts, references, SDK docs, and adjacent guides.
+
+## Docs IA And Navigation
+
+- Read `docs/docs.json` before navigation changes.
+- Keep topic pages and common workflows on the main reader path.
+- Put exhaustive contracts, generated references, maintainer-only detail, and
+  support material under `Reference` or another clearly scoped support page.
+- Keep generated `plugins/reference/*` children and redirect-only pages out of
+  visible navigation unless explicitly required.
+- For moved pages, include a keep/drop/move/destination matrix in the handoff.
+- Add "Read when" hints for docs-list routing when creating or changing pages
+  that participate in the docs index.
+
+## Source-Backed Content
+
+- CLI docs must match current flags, output, errors, and examples.
+- API/SDK docs must include fields, defaults, enum values, constraints, nullable
+  behavior, lifecycle states, errors, and recovery guidance.
+- Config docs must align exported types, schema/help output, metadata, baselines,
+  and current docs.
+- Dependency-backed behavior must be verified from upstream docs, source, or
+  types before documenting defaults, timing, errors, or API behavior.
+- Separate current behavior, shipped behavior, planned behavior, and maintainer
+  intent.
+
+## Examples
+
+- Prefer complete copy-pasteable commands and snippets.
+- Use realistic variable names and values.
+- Mark placeholders with angle-bracket names such as `<API_KEY>`.
+- Show expected success output when it helps verification.
+- Keep one conceptual unit per code block and use language-specific fences.
+- Avoid examples that hide setup, auth, error handling, or cleanup.
+- Never expose real secrets, live config, phone numbers, private videos, or
+  credentials.
+
+## Preservation Reviews
+
+For rewrites or splits:
+
+- Identify source units before rewriting: headings, paragraphs, tables, examples,
+  CLI/API contracts, warnings, and troubleshooting facts.
+- Map each retained unit to a destination page or section.
+- Do not treat a broad "covered" row as proof for dense source material; use
+  line- or claim-level evidence when the source unit is dense.
+- For dropped content, state whether it is obsolete, duplicated elsewhere,
+  unsupported, or moved to a reference/support page.
+- When a docs-audit artifact is used, verify it is mapped audit data with
+  non-empty `mappings[]`, not only inventory or reindexed JSON.
+
+## Validation
+
+Choose the narrowest proof that covers the touched surface:
+
+- `pnpm docs:list`
+- `pnpm docs:check-mdx`
+- `pnpm docs:check-links`
+- `pnpm docs:check-i18n-glossary`
+- `pnpm format:docs:check` or `pnpm lint:docs`
+- `git diff --check`
+- generated-doc or inventory checks when generated references, plugin catalogs,
+  labeler, or docs scripts changed
+- behavior tests or command probes when docs claim runtime behavior
+
+If proof is blocked, say exactly which command was not run and why.
@@ -0,0 +1,54 @@
+# Documentation Principles
+
+This reference consolidates the core rules used by this skill.
+
+## Matt Palmer: 8 rules for better docs
+
+Source: https://mattpalmer.io/posts/2025/10/8-rules-for-better-docs/
+
+Use these as default operating principles:
+
+1. Write for humans, optimize for agents.
+2. Start with a funnel: what/why, quickstart, next steps.
+3. Use Diataxis to scaffold content.
+4. Write with AI, but structure for agents.
+5. Offload routine docs operations to background agents.
+6. Automate quality with CI.
+7. Automate scaffolding and repetitive workflow tasks.
+8. Make contribution easy and visible.
+
+## OpenAI cookbook: what makes documentation good
+
+Source: https://cookbook.openai.com/articles/what_makes_documentation_good
+
+Key quality constraints:
+
+- Prefer specific and accurate terminology over niche jargon.
+- Keep examples self-contained and minimize dependencies.
+- Prioritize high-value topics over edge-case depth.
+- Do not teach unsafe patterns (for example, exposed secrets).
+- Open with context that helps readers orient quickly.
+- Apply empathy and override rigid rules when it clearly improves outcomes.
+
+## Practical merge policy
+
+When these rules conflict:
+
+1. Preserve reader task success first.
+2. Preserve structural clarity second.
+3. Preserve long-term maintainability third.
+4. Add agent optimization only if it does not reduce human clarity.
+
+For agent-instructions and contributor-governance specifics (AGENTS/aliases/CONTRIBUTING), use `references/agent-and-contributing.md` as the detailed additional source of truth.
+
+When the target repo or request is OpenClaw-specific, layer `references/openclaw.md` on top of these general rules. Otherwise ignore that repo-specific overlay.
+
+## Execution policy for this skill
+
+- Long-running and extensive investigations are allowed for both build and review work when needed to resolve ambiguity or cross-file drift.
+- Use sub-agents when available for bounded parallel discovery, verification, or cross-source comparison.
+- Keep one merged outcome: sub-agent outputs must be normalized into a single consistent recommendation/fix set.
+
+## Multilingual parity rule
+
+When docs exist in multiple languages, target cross-locale parity for task-critical content (steps, warnings, prerequisites, and limits). If full parity is not possible, publish explicit parity status and sync intent.
@@ -0,0 +1,121 @@
+# Review Docs Playbook
+
+Read `principles.md` first, then apply this checklist.
+
+## 1. Scope and classification
+
+- Identify doc type and target audience.
+- Confirm brownfield vs evergreen intent.
+- Confirm expected outcome for the reader.
+- For full-repo reviews, explicitly include both governance surfaces and product-doc surfaces (`docs/`, README trees, `.md/.mdx/.mdc`, `.rst/.rsc`, framework docs configs).
+- For OpenClaw docs reviews, apply `references/openclaw.md` for page type, docs IA, preservation, examples, and validation checks.
+
+## 2. Investigation behavior
+
+- Proactively find issues and risks without waiting for repeated prompts.
+- If there are signals of deeper problems, continue investigation beyond the first pass.
+- Long-running and extensive investigations are acceptable when needed for confidence and correctness.
+- When available, use sub-agents for bounded parallel discovery (for example file-inventory, command validation, or cross-doc consistency checks), then merge to one final issue set.
+- When no issues are found, state that explicitly and call out residual risks or validation gaps.
+- Default to `apply-fixes` for high-confidence documentation defects unless the user explicitly requests `report-only`.
+- Do not stop at AGENTS/CONTRIBUTING checks when the task is documentation-wide; continue into docs-content and docs-framework surfaces.
+
+## 3. Governance surface review
+
+- Use `references/agent-and-contributing.md` as the source of truth for inventory, canonical/alias mapping, and precedence/conflict handling.
+  For AGENTS.md:
+
+- confirm persona intent, scope, and command/tool boundaries are explicit.
+- check frontmatter style matches repo conventions when present.
+- ensure `Always`, `Ask first`, and `Never` boundaries are present when expected.
+- require concrete command examples and repo-specific paths to avoid ambiguity.
+
+For CONTRIBUTING.md:
+
+- verify issue/PR workflow is complete and actionable.
+- ensure local setup, lint/test commands, and review criteria are accurate.
+- ensure governance does not conflict with nested AGENTS instructions.
+- flag oversized files that should be split into linked section docs (for example tool-specific setup and release docs).
+
+For agent-platform awareness:
+
+- confirm references are minimal and scoped for Cursor/Claude glob behavior.
+- confirm Codex-facing guidance uses explicit file references.
+- confirm both surfaces represent the same shared policy core (commands, boundaries, and precedence), not divergent guidance.
+- audit `.agents`/`.cursor` compatibility behavior:
+  - verify canonical rule directory and symlink state match repo policy
+  - verify symlink target integrity and platform/tooling expectations
+  - verify AGENTS policy references remain canonical for Codex even when `.cursor` compatibility exists
+- check for context bloat from duplicated policy statements across agent and contributor files.
+- check for conflicting rules, skills and agent instructions
+- check for conflicting information in agent instructions vs codebase
+- check for broken or missing referenced files (for example README/index files named as canonical entry points).
+- check for setup/command drift (for example non-existent install commands, root-level commands that should be module-scoped).
+
+## 4. Product documentation surface review
+
+- Verify docs IA coverage across root/module `README*` files and `docs/**` trees.
+- Review framework-native docs sources in scope (for example Fern, Mintlify, Sphinx, MkDocs) and ensure guidance matches actual source-of-truth files.
+- Check `.md/.mdx/.mdc/.rst/.rsc` for stale commands, missing prerequisites, and broken cross-links.
+- Confirm referenced doc paths and anchors exist.
+- Flag docs that should be split/merged to improve discoverability and maintenance.
+- For OpenClaw docs, check `docs/docs.json`, docs-list routing hints, main path versus `Reference` placement, and generated-reference visibility.
+- For OpenClaw rewrites or page splits, require source-backed keep/drop/move/destination coverage for important claims, warnings, examples, commands, fields, and troubleshooting facts.
+
+## 5. Framework config and path mapping checks
+
+- Detect and read framework config first (for example Fern config, Sphinx `conf.py`, Mintlify config, or equivalent).
+- Resolve path references relative to the declaring file/config.
+- Treat filesystem paths and published URL routes as separate maps; verify both.
+- Flag path-map drift explicitly (`missing file`, `stale route`, `wrong base path`).
+
+## 6. Structural review
+
+- Funnel check: what/why, quickstart, next steps.
+- Validate heading flow and navigation discoverability.
+- Flag critical content trapped in images or buried sections.
+- Check Diataxis alignment and split mixed-purpose sections.
+- For OpenClaw docs, confirm the content matches an explicit page type from `references/openclaw.md`.
+
+## 7. Writing quality review
+
+- Check for concise, scannable paragraphs.
+- Remove ambiguous pronouns and undefined terms.
+- Verify examples are executable and scoped correctly.
+- Verify tone is directive, technical, and non-hand-wavy.
+
+## 8. Brownfield review mode
+
+- Verify compatibility with existing docs IA and conventions.
+- Verify anchors, redirects, and cross-doc links remain valid.
+- Flag regressions in onboarding and task completion paths.
+- Ensure changed terminology is intentionally propagated.
+
+## 9. Evergreen review mode
+
+- Flag date-stamped or brittle wording without version scope.
+- Check ownership and refresh signals are present.
+- Ensure recommendations remain valid after routine product evolution.
+- Flag missing deprecation/migration guidance.
+
+## 10. Tooling and platform review
+
+Read `tooling.md` if platform fit is uncertain.
+
+- Check whether content uses platform primitives effectively.
+- Flag structure that fights the chosen docs platform.
+- Recommend targeted platform-aware improvements.
+
+## 11. Multilingual parity review (when applicable)
+
+- Confirm declared source-of-truth language and expected parity policy.
+- Compare changed sections across locales for step/order/warning drift.
+- Flag missing updates to prerequisites, version notes, limits, and safety guidance.
+- Allow intentional divergence only when rationale is explicit and user-impact is low.
+- Require a reader-visible status note when locale parity is partial.
+
+## 12. Output format
+
+1. Blocking issues (file + required fix)
+2. Non-blocking improvements
+3. Validation notes (done vs pending)
@@ -0,0 +1,32 @@
+# Documentation Tooling Guide
+
+Source: https://www.mintlify.com/blog/top-7-api-documentation-tools-of-2025
+
+Use this file when deciding build/review expectations for doc platforms.
+
+## Tool-selection checkpoints
+
+- Existing stack lock-in: do not force migration for minor gains.
+- API workflow depth: generated references, OpenAPI support, testability.
+- Collaboration model: docs-as-code, review workflow, versioning.
+- Runtime quality: search, navigation, and copy-ready code snippets.
+- AI readiness: structured content, stable URLs, machine-friendly layout yet human readable.
+- Human readiness: reading complexity, reading UX, navigation depth, minimize jargon.
+
+## Apply in brownfield mode
+
+- Prioritize compatibility with the current platform.
+- Use available components and style conventions before introducing new patterns.
+- Propose migration only when current constraints block critical outcomes.
+
+## Apply in evergreen mode
+
+- Favor platforms and templates that make routine updates low-friction.
+- Standardize section templates to reduce drift.
+- Capture ownership, update cadence, and stale-content detection rules.
+
+## Review implications
+
+- Check whether content uses platform primitives correctly (tabs, callouts, endpoint blocks).
+- Flag docs that are technically correct but hard to scan in the chosen platform.
+- Recommend platform-specific improvements only when they reduce cognitive load.
@@ -0,0 +1,21 @@
+# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
+version = 1
+name = "ClawHub"
+
+[setup]
+script = "bun run setup:worktree -- --quiet && bun scripts/dev-worktree.ts --detach"
+
+[[actions]]
+name = "Run"
+icon = "run"
+command = "bun run dev:worktree"
+
+[[actions]]
+name = "Convex Dev"
+icon = "tool"
+command = "bun run setup:worktree -- --quiet && bunx convex dev --typecheck=disable"
+
+[[actions]]
+name = "Seed Dev DB"
+icon = "tool"
+command = "bun run seed:dev"
@@ -0,0 +1,20 @@
+[list]
+url = "http://127.0.0.1:{{ (repo ~ '-' ~ branch) | hash_port }}"
+
+[[pre-start]]
+env = "wt step copy-ignored || true; bun run setup:worktree -- --quiet --force --prefer-fallback"
+
+[[pre-start]]
+deps = "test -x node_modules/.bin/vite || bun install"
+
+[post-start]
+dev = "bun scripts/dev-worktree.ts --detach --seed --port {{ (repo ~ '-' ~ branch) | hash_port }}"
+
+[pre-remove]
+dev = "if test -f .codex/runtime/dev-worktree.pid; then pid=$(cat .codex/runtime/dev-worktree.pid); kill -TERM -$pid 2>/dev/null || kill $pid 2>/dev/null || true; rm -f .codex/runtime/dev-worktree.pid; fi"
+
+[aliases]
+dev = "wt --yes hook pre-start && bun scripts/dev-worktree.ts --detach --seed --port {{ (repo ~ '-' ~ branch) | hash_port }}"
+setup = "wt --yes hook pre-start"
+stop = "if test -f .codex/runtime/dev-worktree.pid; then pid=$(cat .codex/runtime/dev-worktree.pid); kill -TERM -$pid 2>/dev/null || kill $pid 2>/dev/null || true; rm -f .codex/runtime/dev-worktree.pid; fi"
+url = "echo http://127.0.0.1:{{ (repo ~ '-' ~ branch) | hash_port }}"
@@ -0,0 +1,32 @@
+profile: clawhub-check
+provider: blacksmith-testbox
+blacksmith:
+  org: openclaw
+  workflow: .github/workflows/ci-check-testbox.yml
+  job: check
+  ref: main
+  idleTimeout: 90m
+  debug: false
+sync:
+  delete: true
+  checksum: false
+  gitSeed: true
+  fingerprint: true
+  baseRef: main
+  exclude:
+    - .artifacts
+    - .codex
+    - .DS_Store
+    - coverage
+    - dist
+    - dist-ssr
+    - node_modules
+    - playwright-report
+    - test-results
+env:
+  allow:
+    - CI
+    - NODE_OPTIONS
+    - CLAWHUB_*
+    - VITE_CONVEX_URL
+    - VITE_CONVEX_SITE_URL
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab
@@ -1,9 +1,7 @@
 # Frontend
 VITE_CONVEX_URL=
 VITE_CONVEX_SITE_URL=
-VITE_SOULHUB_SITE_URL=
-VITE_SOULHUB_HOST=
-VITE_SITE_MODE=
+VITE_ENABLE_DEV_AUTH=
 SITE_URL=http://localhost:3000
 CONVEX_SITE_URL=

@@ -15,5 +13,16 @@ AUTH_GITHUB_SECRET=
 JWT_PRIVATE_KEY=
 JWKS=

+# Local dev personas
+DEV_AUTH_ENABLED=
+DEV_AUTH_CONVEX_DEPLOYMENT=
+DEV_AUTH_SITE_URL=
+DEV_AUTH_SECRET=
+
 # Embeddings
 OPENAI_API_KEY=
+
+# Transactional email
+RESEND_API_KEY=
+CLAWHUB_SECURITY_EMAIL_FROM=ClawHub Security <noreply@notifications.openclaw.ai>
+CLAWHUB_NOREPLY_FROM=ClawHub <noreply@notifications.openclaw.ai>
@@ -0,0 +1,12 @@
+* text=auto eol=lf
+
+*.avif binary
+*.gif binary
+*.ico binary
+*.jpg binary
+*.jpeg binary
+*.png binary
+*.webp binary
+
+*.woff binary
+*.woff2 binary
@@ -0,0 +1,119 @@
+# Protect the ownership rules themselves.
+/.github/CODEOWNERS @openclaw/openclaw-secops
+
+# WARNING: GitHub CODEOWNERS uses last-match-wins semantics.
+# If you add overlapping rules below the secops block, include @openclaw/openclaw-secops
+# on those entries too or you can silently remove required secops review.
+# Security-sensitive code, config, workflows, and docs require secops review.
+/.github/actions/ @openclaw/openclaw-secops
+/.github/actionlint.yaml @openclaw/openclaw-secops
+/.github/codeql/ @openclaw/openclaw-secops
+/.github/dependabot.yml @openclaw/openclaw-secops
+/.github/workflows/ @openclaw/openclaw-secops
+/scripts/clawhub-cli-npm-publish.sh @openclaw/openclaw-secops
+/scripts/clawhub-cli-npm-release-check.mjs @openclaw/openclaw-secops
+/scripts/github/clawhub-rescan-auto-response.mjs @openclaw/openclaw-secops
+
+# Backend auth, API, publish, upload, moderation, and scan enforcement.
+/convex/schema.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/auth.config.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/auth.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/http.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/httpApi.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/httpApiV1/ @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/packagePublishTokens.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/packages.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/maintenance.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/publishers.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/rateLimits.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/skills.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/skillTransfers.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/tokens.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/uploads.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/vt.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/webhooks.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/access.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/apiTokenAuth.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/githubActionsOidc.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/httpHeaders.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/httpRateLimit.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/manualOverrides.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/moderation.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/moderationEngine.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/moderationReasonCodes.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/packageRegistry.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/packageSearchDigest.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/packageSecurity.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/publishers.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/publishLimits.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/reporting.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/securityPrompt.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/skillCapabilityTags.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/skillPublish.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/skillSafety.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/staticPublishScan.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/tokens.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/convex/lib/webhooks.ts @openclaw/openclaw-secops @Patrick-Erichsen
+
+# Frontend auth, admin, publish, upload, and security-review surfaces.
+/src/lib/packageApi.ts @openclaw/openclaw-secops @BunsDev
+/src/lib/packageUpload.ts @openclaw/openclaw-secops @BunsDev
+/src/lib/roles.ts @openclaw/openclaw-secops @BunsDev
+/src/lib/uploadFiles.ts @openclaw/openclaw-secops @BunsDev
+/src/lib/uploadUtils.ts @openclaw/openclaw-secops @BunsDev
+/src/routes/admin.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/cli/auth.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/packages/new.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/plugins/publish.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/publish-plugin.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/publish-skill.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/skills/publish.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/upload.tsx @openclaw/openclaw-secops @BunsDev
+/src/routes/upload/ @openclaw/openclaw-secops @BunsDev
+/src/routes/$owner/$slug/security/ @openclaw/openclaw-secops @BunsDev
+/src/routes/plugins/$name/security/ @openclaw/openclaw-secops @BunsDev
+
+# CLI auth, admin, publishing, ownership, and package-contract surfaces.
+/packages/clawhub/src/browserAuth.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/http.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/adminHelp.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/authToken.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/clawdbotConfig.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/auth.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/delete.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/github.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/moderation.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/ownership.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/packages.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/publish.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/commands/transfer.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/schema/openclawContract.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/schema/packages.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/schema/routes.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/schema/schemas.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/schema/textFiles.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/openclawContract.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/index.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/packages.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/pluginCategories.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/routes.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/schemas.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/src/textFiles.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/index.d.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/index.js @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/index.js.map @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/pluginCategories.d.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/pluginCategories.js @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/schema/dist/pluginCategories.js.map @openclaw/openclaw-secops @Patrick-Erichsen
+
+# Security, auth, API, webhook, and deployment documentation.
+/docs/acceptable-usage.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/api.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/auth.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/http-api.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/namespace-claims.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/security.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/webhook.md @openclaw/openclaw-secops @Patrick-Erichsen
+/specs/deploy.md @openclaw/openclaw-secops @Patrick-Erichsen
+/specs/github-import.md @openclaw/openclaw-secops @Patrick-Erichsen
+/public/api/v1/openapi.json @openclaw/openclaw-secops @Patrick-Erichsen
@@ -0,0 +1,117 @@
+name: Org / Namespace Claim
+description: Request review for an org, brand, package scope, or namespace ownership dispute.
+title: "Org claim: "
+labels:
+  - "area: moderation"
+  - "area: security"
+  - "status: review"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this form when you believe a ClawHub org, owner handle, package scope, skill slug, plugin package, or related namespace should be reserved, transferred, renamed, hidden, quarantined, aliased, or reviewed because of real-world project, brand, or organizational ownership.
+
+        Public GitHub issues must not include secrets, private documents, private legal files, personal identity documents, API tokens, DNS control tokens, or other sensitive material. Share public, non-sensitive proof here and tell us below if staff needs to arrange a private channel for sensitive evidence.
+
+        This is not the ban/account appeal flow. If your ClawHub account was banned, disabled, or cannot sign in because of account standing, use the ClawHub appeal form instead: https://appeals.openclaw.ai/
+
+        Related policy discussion: https://github.com/openclaw/clawhub/issues/2320
+  - type: input
+    id: claimed_namespace
+    attributes:
+      label: Claimed owner, org, scope, or namespace
+      description: Which ClawHub owner handle, org handle, package scope, skill slug, or package namespace are you claiming?
+      placeholder: "@example-org, example-org, @example-org/example-plugin, or example-skill"
+    validations:
+      required: true
+  - type: textarea
+    id: disputed_resources
+    attributes:
+      label: Disputed ClawHub resources
+      description: Link every relevant ClawHub URL, package name, skill slug, owner page, or related GitHub issue.
+      placeholder: |
+        - https://clawhub.ai/example-org/example-skill
+        - https://clawhub.ai/plugins/@example-org/example-plugin
+        - Package or skill names involved:
+    validations:
+      required: true
+  - type: textarea
+    id: claimant_relationship
+    attributes:
+      label: Claimant identity and relationship
+      description: Explain who is making the request and how they are connected to the org, project, package, or brand. Keep it public-safe.
+      placeholder: |
+        I maintain the upstream project at...
+        I am an admin/owner/member of...
+        Public profile or docs showing that relationship:
+    validations:
+      required: true
+  - type: dropdown
+    id: requested_outcome
+    attributes:
+      label: Requested outcome
+      description: Pick every outcome that would resolve the claim.
+      multiple: true
+      options:
+        - Reserve namespace or package
+        - Transfer ownership
+        - Rename existing resource
+        - Hide or quarantine current resource
+        - Add alias or redirect
+        - Review only / need staff guidance
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: public_proof
+    attributes:
+      label: Public proof links and explanation
+      description: Add public links and explain what each proves. Useful proof includes GitHub org/repo control, domain or official email-domain proof, package-registry scope control, trademark or brand evidence, source repo history, package history, and public project docs. Do not paste secrets, tokens, private documents, or private legal files.
+      placeholder: |
+        - https://github.com/example-org/example-project proves...
+        - https://example.org/docs/clawhub proves...
+        - https://www.npmjs.com/org/example-org proves...
+    validations:
+      required: true
+  - type: textarea
+    id: current_owner_context
+    attributes:
+      label: Current owner, history, or context
+      description: Share what you know about the current ClawHub owner, prior transfers, project rename history, or attempted contact.
+      placeholder: |
+        The current listing appears to be owned by...
+        We contacted...
+        The project was renamed from...
+  - type: textarea
+    id: urgency_context
+    attributes:
+      label: User harm or urgency
+      description: Explain impact, affected users, install paths, or other facts that should affect triage priority. Say "No urgent user harm known" if this is not urgent.
+      placeholder: |
+        Users are being directed from...
+        The package is referenced by...
+        We believe this is urgent because...
+    validations:
+      required: true
+  - type: textarea
+    id: sensitive_evidence
+    attributes:
+      label: Sensitive evidence or private staff channel
+      description: Say whether public evidence is enough or whether staff needs to arrange a private channel. Summarize the kind of private evidence without including the sensitive material itself.
+      placeholder: |
+        Public evidence is enough.
+
+        Or:
+
+        We need a private staff channel for DNS challenge proof, private legal documents, or other sensitive evidence.
+    validations:
+      required: true
+  - type: checkboxes
+    id: acknowledgements
+    attributes:
+      label: Acknowledgements
+      options:
+        - label: I have not included secrets, API tokens, private documents, private legal files, personal identity documents, or other sensitive material in this public issue.
+          required: true
+        - label: I understand this public issue may be linked from ClawHub moderation or namespace policy discussions.
+          required: true
@@ -0,0 +1,104 @@
+name: RFC
+description: Propose a ClawHub policy, product, trust, or interface decision for feedback.
+title: "RFC: "
+labels:
+  - "type: rfc"
+  - "status: review"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use RFCs for decisions that need visible feedback before they become policy, product behavior, or public API contract. Accepted repo RFC files live under `rfcs/`, not `docs/`, so draft/decision records do not publish to the docs site. Keep sensitive enforcement details, private reports, exploit specifics, and scanner thresholds out of the public issue.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      description: Pick the primary area this RFC affects.
+      options:
+        - Moderation / policy
+        - Security / trust
+        - Product / UX
+        - API / CLI
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: What problem, decision, or ambiguity does this RFC address?
+      placeholder: |
+        ClawHub needs a clearer policy for...
+    validations:
+      required: true
+  - type: textarea
+    id: goals
+    attributes:
+      label: Goals
+      description: What should this RFC achieve?
+      placeholder: |
+        - Make enforcement expectations understandable to users.
+        - Give moderators a consistent decision boundary.
+    validations:
+      required: true
+  - type: textarea
+    id: non_goals
+    attributes:
+      label: Non-goals
+      description: What is intentionally out of scope?
+      placeholder: |
+        - This RFC does not expose internal scanner thresholds.
+        - This RFC does not decide implementation details for every moderation tool.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: Describe the proposed policy, behavior, or decision.
+      placeholder: |
+        ClawHub should...
+    validations:
+      required: true
+  - type: textarea
+    id: examples
+    attributes:
+      label: Examples
+      description: Give concrete allowed, not allowed, or edge-case examples.
+      placeholder: |
+        Allowed:
+        - Defensive security review with explicit scope and evidence.
+
+        Not allowed:
+        - Account takeover, evasion, or non-consensual surveillance workflows.
+
+        Edge cases:
+        - ...
+  - type: textarea
+    id: user_impact
+    attributes:
+      label: User impact
+      description: How does this affect authors, users, moderators, API consumers, or external contributors?
+      placeholder: |
+        Authors will...
+        Users will...
+        Moderators will...
+  - type: textarea
+    id: open_questions
+    attributes:
+      label: Open questions
+      description: What feedback would be most useful before a decision?
+      placeholder: |
+        - Should appeals be handled in-product, through GitHub, or both?
+        - What examples would make this clearer?
+    validations:
+      required: true
+  - type: input
+    id: feedback_deadline
+    attributes:
+      label: Feedback deadline
+      description: Use an absolute date. Normal RFCs should stay open for 7-14 days unless urgent.
+      placeholder: "YYYY-MM-DD"
+    validations:
+      required: true
@@ -0,0 +1,10 @@
+# actionlint configuration
+# https://github.com/rhysd/actionlint/blob/main/docs/config.md
+
+self-hosted-runner:
+  labels:
+    # Blacksmith CI runners
+    - blacksmith-4vcpu-ubuntu-2404
+    - blacksmith-8vcpu-ubuntu-2404
+    - blacksmith-16vcpu-ubuntu-2404
+    - blacksmith-32vcpu-ubuntu-2404
@@ -0,0 +1,13 @@
+name: Setup Bun
+description: Install the pinned Bun runtime and workspace dependencies.
+
+runs:
+  using: composite
+  steps:
+    - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+      with:
+        bun-version: 1.3.10
+
+    - name: Install dependencies
+      shell: bash
+      run: bun install --frozen-lockfile
@@ -0,0 +1,16 @@
+name: clawhub-codeql-actions-security
+
+disable-default-queries: true
+
+queries:
+  - uses: security-extended
+
+query-filters:
+  - include:
+      precision:
+        - high
+        - very-high
+      tags contain: security
+
+paths:
+  - .github/workflows
@@ -0,0 +1,70 @@
+name: clawhub-codeql-backend-api-security
+
+disable-default-queries: true
+
+queries:
+  - uses: security-extended
+
+query-filters:
+  - include:
+      precision:
+        - high
+        - very-high
+      tags contain: security
+      security-severity: /([7-9]|10)\.(\d)+/
+
+paths:
+  - convex/auth.config.ts
+  - convex/auth.ts
+  - convex/http.ts
+  - convex/httpApi.ts
+  - convex/httpApiV1
+  - convex/packagePublishTokens.ts
+  - convex/packages.ts
+  - convex/publishers.ts
+  - convex/rateLimits.ts
+  - convex/skills.ts
+  - convex/skillTransfers.ts
+  - convex/tokens.ts
+  - convex/uploads.ts
+  - convex/vt.ts
+  - convex/webhooks.ts
+  - convex/lib/access.ts
+  - convex/lib/apiTokenAuth.ts
+  - convex/lib/githubActionsOidc.ts
+  - convex/lib/httpHeaders.ts
+  - convex/lib/httpRateLimit.ts
+  - convex/lib/httpUtils.ts
+  - convex/lib/manualOverrides.ts
+  - convex/lib/moderation.ts
+  - convex/lib/moderationEngine.ts
+  - convex/lib/moderationReasonCodes.ts
+  - convex/lib/packageRegistry.ts
+  - convex/lib/packageSecurity.ts
+  - convex/lib/publishers.ts
+  - convex/lib/publishLimits.ts
+  - convex/lib/reporting.ts
+  - convex/lib/securityPrompt.ts
+  - convex/lib/skillPublish.ts
+  - convex/lib/skillSafety.ts
+  - convex/lib/staticPublishScan.ts
+  - convex/lib/tokens.ts
+  - convex/lib/webhooks.ts
+
+paths-ignore:
+  - "**/node_modules"
+  - "**/coverage"
+  - "**/dist"
+  - "**/dist/**"
+  - "**/*.generated.ts"
+  - "**/*.bundle.js"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.e2e.test.ts"
+  - "**/*.e2e.test.tsx"
+  - "**/*test-support*"
+  - "**/*test-helper*"
+  - "**/*mock*"
+  - "**/*fixture*"
+  - "**/*bench*"
+  - "convex/_generated/**"
@@ -0,0 +1,56 @@
+name: clawhub-codeql-cli-package-security
+
+disable-default-queries: true
+
+queries:
+  - uses: security-extended
+
+query-filters:
+  - include:
+      precision:
+        - high
+        - very-high
+      tags contain: security
+      security-severity: /([7-9]|10)\.(\d)+/
+
+paths:
+  - packages/clawhub/src/browserAuth.ts
+  - packages/clawhub/src/http.ts
+  - packages/clawhub/src/cli/adminHelp.ts
+  - packages/clawhub/src/cli/authToken.ts
+  - packages/clawhub/src/cli/clawdbotConfig.ts
+  - packages/clawhub/src/cli/commands/auth.ts
+  - packages/clawhub/src/cli/commands/delete.ts
+  - packages/clawhub/src/cli/commands/github.ts
+  - packages/clawhub/src/cli/commands/moderation.ts
+  - packages/clawhub/src/cli/commands/ownership.ts
+  - packages/clawhub/src/cli/commands/packages.ts
+  - packages/clawhub/src/cli/commands/publish.ts
+  - packages/clawhub/src/cli/commands/transfer.ts
+  - packages/clawhub/src/schema/openclawContract.ts
+  - packages/clawhub/src/schema/packages.ts
+  - packages/clawhub/src/schema/routes.ts
+  - packages/clawhub/src/schema/schemas.ts
+  - packages/clawhub/src/schema/textFiles.ts
+  - packages/schema/src/openclawContract.ts
+  - packages/schema/src/packages.ts
+  - packages/schema/src/routes.ts
+  - packages/schema/src/schemas.ts
+  - packages/schema/src/textFiles.ts
+
+paths-ignore:
+  - "**/node_modules"
+  - "**/coverage"
+  - "**/dist"
+  - "**/dist/**"
+  - "**/*.generated.ts"
+  - "**/*.bundle.js"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.e2e.test.ts"
+  - "**/*.e2e.test.tsx"
+  - "**/*test-support*"
+  - "**/*test-helper*"
+  - "**/*mock*"
+  - "**/*fixture*"
+  - "**/*bench*"
@@ -0,0 +1,64 @@
+name: clawhub-codeql-frontend-publish-security
+
+disable-default-queries: true
+
+queries:
+  - uses: security-extended
+
+query-filters:
+  - include:
+      precision:
+        - high
+        - very-high
+      tags contain: security
+      security-severity: /([7-9]|10)\.(\d)+/
+
+paths:
+  - src/components/DetailSecuritySummary.tsx
+  - src/components/MarkdownPreview.tsx
+  - src/components/PackageSourceChooser.tsx
+  - src/components/SecurityAuditPage.tsx
+  - src/components/SkillSecurityScanResults.tsx
+  - src/components/securityAuditModel.ts
+  - src/lib/authErrorMessage.ts
+  - src/lib/packageApi.ts
+  - src/lib/packageUpload.ts
+  - src/lib/pluginPublishPrefill.ts
+  - src/lib/rehypeProxyImages.ts
+  - src/lib/roles.ts
+  - src/lib/uploadFiles.ts
+  - src/lib/uploadUtils.ts
+  - src/lib/useAuthError.ts
+  - src/lib/useAuthStatus.ts
+  - src/routes/admin.tsx
+  - src/routes/cli/auth.tsx
+  - src/routes/packages/new.tsx
+  - src/routes/plugins/publish.tsx
+  - src/routes/publish-plugin.tsx
+  - src/routes/publish-skill.tsx
+  - src/routes/skills/publish.tsx
+  - src/routes/upload.tsx
+  - src/routes/upload
+  - src/routes/$owner/$slug/security-audit.tsx
+  - src/routes/$owner/$slug/security
+  - src/routes/plugins/$name/security-audit.tsx
+  - src/routes/plugins/$name/security
+  - src/routes/plugins/$scope/$name/security-audit.tsx
+  - src/routes/plugins/$scope/$name/security
+
+paths-ignore:
+  - "**/node_modules"
+  - "**/coverage"
+  - "**/dist"
+  - "**/dist/**"
+  - "**/*.generated.ts"
+  - "**/*.bundle.js"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.e2e.test.ts"
+  - "**/*.e2e.test.tsx"
+  - "**/*test-support*"
+  - "**/*test-helper*"
+  - "**/*mock*"
+  - "**/*fixture*"
+  - "**/*bench*"
@@ -0,0 +1,38 @@
+name: clawhub-codeql-repository-automation-security
+
+disable-default-queries: true
+
+queries:
+  - uses: security-extended
+
+query-filters:
+  - include:
+      precision:
+        - high
+        - very-high
+      tags contain: security
+      security-severity: /([7-9]|10)\.(\d)+/
+
+paths:
+  - scripts/clawhub-cli-npm-release-check.mjs
+  - scripts/github
+  - scripts/verify-convex-contract.ts
+  - scripts/copy-og-assets.ts
+  - scripts/check-peer-deps.ts
+
+paths-ignore:
+  - "**/node_modules"
+  - "**/coverage"
+  - "**/dist"
+  - "**/dist/**"
+  - "**/*.generated.ts"
+  - "**/*.bundle.js"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.e2e.test.ts"
+  - "**/*.e2e.test.tsx"
+  - "**/*test-support*"
+  - "**/*test-helper*"
+  - "**/*mock*"
+  - "**/*fixture*"
+  - "**/*bench*"
@@ -0,0 +1,47 @@
+version: 2
+updates:
+  - package-ecosystem: "bun"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Los_Angeles"
+    # Preserve the old total Bun capacity: 10 general updates plus the
+    # dedicated 3-PR Plugin Inspector queue that cannot remain as a duplicate
+    # root Bun config.
+    open-pull-requests-limit: 13
+    ignore:
+      - dependency-name: "@auth/core"
+        update-types:
+          - "version-update:semver-minor"
+          - "version-update:semver-major"
+      - dependency-name: "undici"
+        update-types:
+          - "version-update:semver-major"
+    groups:
+      plugin-inspector:
+        patterns:
+          - "@openclaw/plugin-inspector"
+      production-minor-and-patch:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      development-minor-and-patch:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Los_Angeles"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
@@ -0,0 +1,39 @@
+## Summary
+
+- What changed:
+- Why:
+
+## Linked Issue
+
+- Closes #
+- Related #
+
+## Screenshots
+
+For website/UI changes, attach screenshots or recordings from the real app. Include mobile/narrow views when layout changes.
+
+- [ ] Screenshots/recordings attached, or `N/A`
+
+## Behavioural Proof
+
+Describe how you verified the user-facing behavior. For UI changes, include the path tested and what changed on screen. For backend/API changes, include the request, command, or scenario that proves the behavior.
+
+- [ ] Behavioural proof included, or `N/A`
+
+## Security / Trust Impact
+
+- [ ] No security/trust impact
+- [ ] Security/trust impact explained
+
+## Data / Deploy Impact
+
+- [ ] No data/deploy impact
+- [ ] Data/deploy impact explained
+
+## Verification
+
+- [ ] `bun run ci:static`
+- [ ] Focused tests for touched behavior:
+- [ ] `bun run ci:unit` or `N/A` for docs/config-only:
+- [ ] Broader gate when required (`ci:types-build`, `ci:packages`, `ci:e2e-http`, `ci:playwright-smoke`, `test:pw:local-auth`, `proof:ui`):
+- [ ] Other:
@@ -0,0 +1,59 @@
+name: Auto response
+
+on:
+  issues:
+    types: [opened, edited, labeled]
+  issue_comment:
+    types: [created]
+  pull_request_target: # zizmor: ignore[dangerous-triggers] trusted base checkout only; no untrusted PR code execution
+    types: [opened, edited, synchronize, reopened, labeled]
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number || github.ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request_target' }}
+
+permissions: {}
+
+jobs:
+  auto-response:
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        continue-on-error: true
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token-fallback
+        continue-on-error: true
+        if: steps.app-token.outcome == 'failure'
+        with:
+          app-id: "2971289"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
+
+      - name: Run Barnacle auto-response
+        uses: actions/github-script@v9
+        with:
+          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token || github.token }}
+          script: |
+            const { pathToFileURL } = require("node:url");
+            const moduleUrl = pathToFileURL(
+              `${process.env.GITHUB_WORKSPACE}/scripts/github/barnacle-auto-response.mjs`,
+            );
+            const { runBarnacleAutoResponse } = await import(moduleUrl.href);
+
+            await runBarnacleAutoResponse({ github, context, core });
@@ -0,0 +1,80 @@
+name: Crabbox Testbox Backend
+
+on:
+  workflow_dispatch:
+    inputs:
+      testbox_id:
+        type: string
+        description: "Testbox session ID"
+        required: true
+
+permissions:
+  contents: read
+
+env:
+  BUN_VERSION: "1.3.10"
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  check:
+    name: "check"
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 30
+    steps:
+      - name: Begin Testbox
+        uses: useblacksmith/begin-testbox@233448af4bfdc6fca509a7f0974411ac6d8a8043
+        with:
+          testbox_id: ${{ inputs.testbox_id }}
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 50
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Restore Bun install cache
+        id: bun-cache
+        uses: actions/cache/restore@v5
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ env.BUN_VERSION }}-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-${{ env.BUN_VERSION }}-
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Save Bun install cache
+        if: steps.bun-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v5
+        continue-on-error: true
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ steps.bun-cache.outputs.cache-primary-key }}
+
+      - name: Prepare Testbox shell
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          git fetch --no-tags --depth=50 origin "+refs/heads/main:refs/remotes/origin/main"
+
+          bun_bin="$(command -v bun)"
+          sudo ln -sf "$bun_bin" /usr/local/bin/bun
+
+          if command -v bunx >/dev/null 2>&1; then
+            sudo ln -sf "$(command -v bunx)" /usr/local/bin/bunx
+          fi
+
+          node_bin="$(dirname "$(node -p 'process.execPath')")"
+          sudo ln -sf "$node_bin/node" /usr/local/bin/node
+          sudo ln -sf "$node_bin/npm" /usr/local/bin/npm
+          sudo ln -sf "$node_bin/npx" /usr/local/bin/npx
+
+      - name: Run Testbox
+        uses: useblacksmith/run-testbox@3f60ff9ceb2c10c3feefa87dc0c6490cffae059d
+        if: always()
+        env:
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
@@ -4,45 +4,200 @@ on:
  push:
    branches: [main]
  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+env:
+  VITE_CONVEX_URL: https://example.invalid

 jobs:
-  build:
-    runs-on: ubuntu-latest
+  static:
+    name: static
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Static checks
+        run: bun run ci:static
+
+  unit:
+    name: unit
+    runs-on: blacksmith-4vcpu-ubuntu-2404
    timeout-minutes: 15

    steps:
      - uses: actions/checkout@v6

-      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
-        with:
-          bun-version: 1.3.10
-
-      - name: Install
-        run: bun install --frozen-lockfile
-      - name: Peer deps
-        run: bun run check:peers
-
-      - name: Lint
-        run: bun run lint
-
-      - name: Test
-        run: bun run test
-        env:
-          VITE_CONVEX_URL: https://example.invalid
+      - uses: ./.github/actions/setup-bun

      - name: Coverage
-        run: bun run coverage
+        run: bun run ci:unit
+
+  packages:
+    name: packages
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Package checks
+        run: bun run ci:packages
+
+  types-build:
+    name: types-build
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Typecheck and build
+        run: bun run ci:types-build
+
+  e2e-http:
+    name: e2e-http
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: HTTP e2e
+        run: bun run ci:e2e-http
+
+  playwright-smoke:
+    name: playwright-smoke
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+
+      - name: Install Playwright browsers
+        run: bunx playwright install chromium
+
+      - name: Browser e2e
+        run: bun run ci:playwright-smoke
+
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-report
+          path: playwright-report/
+          if-no-files-found: ignore
+
+  playwright-local-auth-shard:
+    name: playwright-local-auth / ${{ matrix.name }}
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      max-parallel: 3
+      matrix:
+        include:
+          - name: delete-account
+            spec: e2e/local-auth/delete-account-resources.pw.test.ts
+          - name: delete-org
+            spec: e2e/local-auth/delete-org-resources.pw.test.ts
+          - name: header-profile-link
+            spec: e2e/local-auth/header-profile-link.pw.test.ts
+          - name: malicious-skill-ban
+            spec: e2e/local-auth/malicious-skill-ban-flow.pw.test.ts
+          - name: manage-context-proof
+            spec: e2e/local-auth/manage-context-proof.pw.test.ts
+          - name: plugin-inspector-findings
+            spec: e2e/local-auth/plugin-inspector-findings.pw.test.ts
+          - name: publish-generated-card
+            spec: e2e/local-auth/publish-skill-lifecycle.pw.test.ts
+            grep: publishing a skill queues scan
+          - name: publish-new-version
+            spec: e2e/local-auth/publish-skill-lifecycle.pw.test.ts
+            grep: skill publishers can create a skill
+          - name: skill-star-sync
+            spec: e2e/local-auth/skill-star-sync.pw.test.ts
+          - name: version-delete
+            spec: e2e/local-auth/version-delete.pw.test.ts
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+
+      - name: Install Playwright browsers
+        run: bunx playwright install chromium
+
+      - name: Local-auth browser e2e
        env:
-          VITE_CONVEX_URL: https://example.invalid
-
-      - name: ClawHub CLI Verify
-        run: bun run --cwd packages/clawhub verify
-
-      - name: Typecheck
+          PLAYWRIGHT_GREP: ${{ matrix.grep || '' }}
+          PLAYWRIGHT_SPEC: ${{ matrix.spec }}
        run: |
-          bunx tsc --noEmit
-          bunx tsc -p packages/schema/tsconfig.json --noEmit
-          bunx tsc -p packages/clawhub/tsconfig.json --noEmit
+          set -euo pipefail
+          args=(--project=chromium "$PLAYWRIGHT_SPEC")
+          if [[ -n "$PLAYWRIGHT_GREP" ]]; then
+            args+=(--grep "$PLAYWRIGHT_GREP")
+          fi
+          bun run test:pw:local-auth -- "${args[@]}"

-      - name: Build
-        run: bun run build
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-local-auth-report-${{ matrix.name }}
+          path: playwright-report/
+          if-no-files-found: ignore
+
+  playwright-local-auth:
+    name: playwright-local-auth
+    runs-on: ubuntu-latest
+    needs: playwright-local-auth-shard
+    if: ${{ always() }}
+    timeout-minutes: 5
+
+    steps:
+      - name: Check local-auth shards
+        env:
+          LOCAL_AUTH_RESULT: ${{ needs.playwright-local-auth-shard.result }}
+        run: |
+          if [[ "$LOCAL_AUTH_RESULT" != "success" ]]; then
+            echo "playwright-local-auth shards finished with result: $LOCAL_AUTH_RESULT"
+            exit 1
+          fi
+          echo "playwright-local-auth shards passed."
@@ -0,0 +1,326 @@
+name: ClawHub CLI GitHub Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to create or repair, for example v0.17.0
+        required: true
+        type: string
+      main_run_id:
+        description: Optional successful main CI run id to include in release proof
+        required: false
+        type: string
+      preflight_run_id:
+        description: Optional successful CLI npm preflight run id to include in release proof
+        required: false
+        type: string
+      publish_run_id:
+        description: Optional successful CLI npm publish run id to include in release proof
+        required: false
+        type: string
+      update_existing:
+        description: Update an existing GitHub Release instead of failing
+        required: true
+        default: false
+        type: boolean
+
+concurrency:
+  group: clawhub-cli-github-release-${{ inputs.tag }}
+  cancel-in-progress: false
+
+permissions: {}
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24.x"
+
+jobs:
+  create_or_update_github_release:
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: write
+    steps:
+      - name: Checkout release tooling
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+          path: release-tools
+
+      - name: Checkout release tag
+        uses: actions/checkout@v6
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-depth: 0
+          path: release
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Validate release tag and package metadata
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+          RELEASE_MAIN_REF: origin/main
+        run: |
+          set -euo pipefail
+          RELEASE_SHA="$(git rev-parse HEAD)"
+          echo "RELEASE_SHA=$RELEASE_SHA" >> "$GITHUB_ENV"
+          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
+          if ! git merge-base --is-ancestor "$RELEASE_SHA" "$RELEASE_MAIN_REF"; then
+            echo "Tagged commit ${RELEASE_SHA} is not contained in ${RELEASE_MAIN_REF}." >&2
+            exit 1
+          fi
+          node --input-type=module <<'EOF'
+          import { readFileSync } from "node:fs";
+
+          const releaseTag = process.env.RELEASE_TAG ?? "";
+          const pkg = JSON.parse(readFileSync("./packages/clawhub/package.json", "utf8"));
+          const version = String(pkg.version ?? "").trim();
+          const errors = [];
+
+          if (pkg.name !== "clawhub") {
+            errors.push(`packages/clawhub/package.json name must be "clawhub"; found "${pkg.name ?? ""}".`);
+          }
+          if (!/^\d+\.\d+\.\d+$/.test(version)) {
+            errors.push(`packages/clawhub/package.json version must be stable semver (X.Y.Z); found "${version || "<missing>"}".`);
+          }
+          if (!/^v\d+\.\d+\.\d+$/.test(releaseTag)) {
+            errors.push(`Release tag must match vX.Y.Z; found "${releaseTag || "<missing>"}".`);
+          }
+          if (releaseTag !== `v${version}`) {
+            errors.push(`Release tag ${releaseTag} does not match packages/clawhub/package.json version ${version}; expected v${version}.`);
+          }
+
+          if (errors.length > 0) {
+            for (const error of errors) console.error(error);
+            process.exit(1);
+          }
+          console.log(`Release metadata OK for clawhub@${version} (${releaseTag}).`);
+          EOF
+        working-directory: release
+
+      - name: Resolve release metadata
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION="$(node --input-type=module <<'EOF'
+          import { readFileSync } from "node:fs";
+
+          const pkg = JSON.parse(readFileSync("./packages/clawhub/package.json", "utf8"));
+          process.stdout.write(String(pkg.version ?? "").trim());
+          EOF
+          )"
+          NPM_DIST_JSON=""
+          for attempt in {1..12}; do
+            if NPM_DIST_JSON="$(npm view "clawhub@${PACKAGE_VERSION}" dist.tarball dist.integrity --json 2>/tmp/npm-view-error)" && [[ -n "$NPM_DIST_JSON" ]]; then
+              break
+            fi
+            if [[ "$attempt" == "12" ]]; then
+              cat /tmp/npm-view-error >&2 || true
+              exit 1
+            fi
+            sleep 5
+          done
+          NPM_TARBALL="$(NPM_DIST_JSON="$NPM_DIST_JSON" node --input-type=module <<'EOF'
+          const dist = JSON.parse(process.env.NPM_DIST_JSON ?? "{}");
+          process.stdout.write(String(dist["dist.tarball"] ?? ""));
+          EOF
+          )"
+          NPM_INTEGRITY="$(NPM_DIST_JSON="$NPM_DIST_JSON" node --input-type=module <<'EOF'
+          const dist = JSON.parse(process.env.NPM_DIST_JSON ?? "{}");
+          process.stdout.write(String(dist["dist.integrity"] ?? ""));
+          EOF
+          )"
+          if [[ -z "$NPM_TARBALL" || -z "$NPM_INTEGRITY" ]]; then
+            echo "npm dist metadata for clawhub@${PACKAGE_VERSION} is incomplete." >&2
+            exit 1
+          fi
+          {
+            echo "PACKAGE_VERSION=$PACKAGE_VERSION"
+            echo "NPM_PACKAGE_URL=https://www.npmjs.com/package/clawhub/v/${PACKAGE_VERSION}"
+            echo "NPM_TARBALL_URL=$NPM_TARBALL"
+            echo "NPM_INTEGRITY=$NPM_INTEGRITY"
+            echo "RELEASE_TITLE=clawhub ${PACKAGE_VERSION}"
+          } >> "$GITHUB_ENV"
+        working-directory: release
+
+      - name: Resolve proof workflow run URLs
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MAIN_RUN_ID: ${{ inputs.main_run_id }}
+          PREFLIGHT_RUN_ID: ${{ inputs.preflight_run_id }}
+          PUBLISH_RUN_ID: ${{ inputs.publish_run_id }}
+        run: |
+          set -euo pipefail
+
+          resolve_run_url() {
+            local env_name="$1"
+            local run_id="$2"
+            local expected_workflow="$3"
+            local expected_event="$4"
+            local expected_branch="$5"
+
+            if [[ -z "$run_id" ]]; then
+              return 0
+            fi
+
+            local run_json
+            run_json="$(gh run view "$run_id" --repo "$GITHUB_REPOSITORY" --json conclusion,event,headBranch,headSha,url,workflowName)"
+            RUN_JSON="$run_json" RUN_ID="$run_id" EXPECTED_WORKFLOW="$expected_workflow" EXPECTED_EVENT="$expected_event" EXPECTED_BRANCH="$expected_branch" node --input-type=module <<'EOF'
+            const run = JSON.parse(process.env.RUN_JSON);
+            const expectedWorkflow = process.env.EXPECTED_WORKFLOW;
+            if (expectedWorkflow && run.workflowName !== expectedWorkflow) {
+              console.error(`Run ${process.env.RUN_ID} must be ${expectedWorkflow}; got ${run.workflowName ?? "<missing>"}.`);
+              process.exit(1);
+            }
+            if (run.conclusion !== "success") {
+              console.error(`Run ${process.env.RUN_ID} must have conclusion=success; got ${run.conclusion ?? "<missing>"}.`);
+              process.exit(1);
+            }
+            if (run.headSha !== process.env.RELEASE_SHA) {
+              console.error(`Run ${process.env.RUN_ID} must use release SHA ${process.env.RELEASE_SHA}; got ${run.headSha ?? "<missing>"}.`);
+              process.exit(1);
+            }
+            if (process.env.EXPECTED_EVENT && run.event !== process.env.EXPECTED_EVENT) {
+              console.error(`Run ${process.env.RUN_ID} must have event=${process.env.EXPECTED_EVENT}; got ${run.event ?? "<missing>"}.`);
+              process.exit(1);
+            }
+            if (process.env.EXPECTED_BRANCH && run.headBranch !== process.env.EXPECTED_BRANCH) {
+              console.error(`Run ${process.env.RUN_ID} must have headBranch=${process.env.EXPECTED_BRANCH}; got ${run.headBranch ?? "<missing>"}.`);
+              process.exit(1);
+            }
+            process.stdout.write(run.url);
+          EOF
+            echo "${env_name}=$(RUN_JSON="$run_json" RUN_ID="$run_id" EXPECTED_WORKFLOW="$expected_workflow" node --input-type=module <<'EOF'
+            const run = JSON.parse(process.env.RUN_JSON);
+            process.stdout.write(run.url);
+          EOF
+            )" >> "$GITHUB_ENV"
+          }
+
+          resolve_run_url MAIN_RUN_URL "$MAIN_RUN_ID" "CI" "" ""
+          resolve_run_url PREFLIGHT_RUN_URL "$PREFLIGHT_RUN_ID" "ClawHub CLI NPM Release" "workflow_dispatch" "main"
+          resolve_run_url PUBLISH_RUN_URL "$PUBLISH_RUN_ID" "ClawHub CLI NPM Release" "workflow_dispatch" "main"
+
+      - name: Verify preflight proof artifact
+        if: ${{ inputs.preflight_run_id != '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PREFLIGHT_RUN_ID: ${{ inputs.preflight_run_id }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          PROOF_DIR="$RUNNER_TEMP/clawhub-cli-github-release-preflight-proof"
+          rm -rf "$PROOF_DIR"
+          mkdir -p "$PROOF_DIR"
+          gh run download "$PREFLIGHT_RUN_ID" \
+            --repo "$GITHUB_REPOSITORY" \
+            --name "clawhub-cli-npm-preflight-${RELEASE_TAG}" \
+            --dir "$PROOF_DIR"
+
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/release-tag.txt")" != "$RELEASE_TAG" ]]; then
+            echo "Preflight artifact tag does not match ${RELEASE_TAG}." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/release-sha.txt")" != "$RELEASE_SHA" ]]; then
+            echo "Preflight artifact SHA does not match ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/package-version.txt")" != "$PACKAGE_VERSION" ]]; then
+            echo "Preflight artifact version does not match ${PACKAGE_VERSION}." >&2
+            exit 1
+          fi
+
+      - name: Verify publish proof artifact
+        if: ${{ inputs.publish_run_id != '' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PUBLISH_RUN_ID: ${{ inputs.publish_run_id }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          PROOF_DIR="$RUNNER_TEMP/clawhub-cli-github-release-publish-proof"
+          rm -rf "$PROOF_DIR"
+          mkdir -p "$PROOF_DIR"
+          gh run download "$PUBLISH_RUN_ID" \
+            --repo "$GITHUB_REPOSITORY" \
+            --name "clawhub-cli-npm-publish-${RELEASE_TAG}" \
+            --dir "$PROOF_DIR"
+
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/release-tag.txt")" != "$RELEASE_TAG" ]]; then
+            echo "Publish artifact tag does not match ${RELEASE_TAG}." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/release-sha.txt")" != "$RELEASE_SHA" ]]; then
+            echo "Publish artifact SHA does not match ${RELEASE_SHA}." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/package-version.txt")" != "$PACKAGE_VERSION" ]]; then
+            echo "Publish artifact version does not match ${PACKAGE_VERSION}." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/preflight-only.txt")" != "false" ]]; then
+            echo "Publish artifact must come from a real publish run." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/npm-tarball-url.txt")" != "$NPM_TARBALL_URL" ]]; then
+            echo "Publish artifact tarball URL does not match npm metadata." >&2
+            exit 1
+          fi
+          if [[ "$(tr -d '\r\n' < "$PROOF_DIR/npm-integrity.txt")" != "$NPM_INTEGRITY" ]]; then
+            echo "Publish artifact integrity does not match npm metadata." >&2
+            exit 1
+          fi
+
+      - name: Build release notes
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          node ../release-tools/scripts/extract-changelog-release.mjs --tag "$RELEASE_TAG" --changelog CHANGELOG.md > ../release-body.md
+          {
+            echo
+            echo "### Release Proof"
+            echo
+            echo "- npm: ${NPM_PACKAGE_URL}"
+            echo "- tarball: ${NPM_TARBALL_URL}"
+            echo "- integrity: ${NPM_INTEGRITY}"
+            if [[ -n "${MAIN_RUN_URL:-}" ]]; then
+              echo "- main CI: ${MAIN_RUN_URL}"
+            fi
+            if [[ -n "${PREFLIGHT_RUN_URL:-}" ]]; then
+              echo "- npm preflight: ${PREFLIGHT_RUN_URL}"
+            fi
+            if [[ -n "${PUBLISH_RUN_URL:-}" ]]; then
+              echo "- npm publish: ${PUBLISH_RUN_URL}"
+            fi
+          } >> ../release-body.md
+        working-directory: release
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+          UPDATE_EXISTING: ${{ inputs.update_existing }}
+        run: |
+          set -euo pipefail
+          if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            if [[ "$UPDATE_EXISTING" != "true" ]]; then
+              echo "GitHub Release ${RELEASE_TAG} already exists. Rerun with update_existing=true to repair it." >&2
+              exit 1
+            fi
+            gh release edit "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "$RELEASE_TITLE" \
+              --notes-file release-body.md
+          else
+            gh release create "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "$RELEASE_TITLE" \
+              --notes-file release-body.md
+          fi
@@ -21,6 +21,8 @@ concurrency:
  group: clawhub-cli-npm-release-${{ inputs.tag }}
  cancel-in-progress: false

+permissions: {}
+
 env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  NODE_VERSION: "24.x"
@@ -45,6 +47,12 @@ jobs:
          ref: refs/tags/${{ inputs.tag }}
          fetch-depth: 0

+      - name: Checkout release tooling
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+          path: release-tools
+
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
@@ -52,7 +60,7 @@ jobs:
          registry-url: https://registry.npmjs.org

      - name: Setup Bun
-        uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
        with:
          bun-version: ${{ env.BUN_VERSION }}

@@ -106,6 +114,11 @@ jobs:
          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
          node scripts/clawhub-cli-npm-release-check.mjs

+      - name: Validate GitHub Release notes
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: node release-tools/scripts/extract-changelog-release.mjs --tag "$RELEASE_TAG" >/tmp/clawhub-cli-release-notes.md
+
      - name: Verify CLI package
        run: bun run --cwd "$PACKAGE_DIR" verify

@@ -181,7 +194,7 @@ jobs:
    environment: npm-release
    permissions:
      actions: read
-      contents: read
+      contents: write
      id-token: write
    steps:
      - name: Checkout
@@ -190,6 +203,12 @@ jobs:
          ref: refs/tags/${{ inputs.tag }}
          fetch-depth: 0

+      - name: Checkout release tooling
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.ref }}
+          path: release-tools
+
      - name: Setup Node
        uses: actions/setup-node@v6
        with:
@@ -233,6 +252,7 @@ jobs:
        run: |
          set -euo pipefail
          RUN_JSON="$(gh run view "$PREFLIGHT_RUN_ID" --repo "$GITHUB_REPOSITORY" --json workflowName,headBranch,event,conclusion,url)"
+          # shellcheck disable=SC2016
          printf '%s' "$RUN_JSON" | node --input-type=module -e 'const chunks=[]; process.stdin.on("data", (chunk) => chunks.push(chunk)); process.stdin.on("end", () => { const run = JSON.parse(Buffer.concat(chunks).toString("utf8")); const checks = [["workflowName", "ClawHub CLI NPM Release"], ["headBranch", "main"], ["event", "workflow_dispatch"], ["conclusion", "success"]]; for (const [key, expected] of checks) { if (run[key] !== expected) { console.error(`Referenced npm preflight run ${process.env.PREFLIGHT_RUN_ID} must have ${key}=${expected}, got ${run[key] ?? "<missing>"}.`); process.exit(1); } } console.log(`Using npm preflight run ${process.env.PREFLIGHT_RUN_ID}: ${run.url}`); });'

      - name: Download prepared npm tarball
@@ -255,6 +275,11 @@ jobs:
          git fetch --no-tags origin +refs/heads/main:refs/remotes/origin/main
          node scripts/clawhub-cli-npm-release-check.mjs

+      - name: Validate GitHub Release notes
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: node release-tools/scripts/extract-changelog-release.mjs --tag "$RELEASE_TAG" >/tmp/clawhub-cli-release-notes.md
+
      - name: Verify prepared tarball provenance
        env:
          RELEASE_TAG: ${{ inputs.tag }}
@@ -312,3 +337,106 @@ jobs:
            publish_target="./${publish_target}"
          fi
          bash scripts/clawhub-cli-npm-publish.sh --publish "${publish_target}"
+
+      - name: Resolve npm release metadata
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION="$(node --input-type=module <<'EOF'
+          import { readFileSync } from "node:fs";
+
+          const pkg = JSON.parse(readFileSync(`./${process.env.PACKAGE_DIR}/package.json`, "utf8"));
+          process.stdout.write(String(pkg.version ?? "").trim());
+          EOF
+          )"
+          NPM_DIST_JSON=""
+          for attempt in {1..12}; do
+            if NPM_DIST_JSON="$(npm view "clawhub@${PACKAGE_VERSION}" dist.tarball dist.integrity --json 2>/tmp/npm-view-error)" && [[ -n "$NPM_DIST_JSON" ]]; then
+              break
+            fi
+            if [[ "$attempt" == "12" ]]; then
+              cat /tmp/npm-view-error >&2 || true
+              exit 1
+            fi
+            sleep 5
+          done
+          NPM_TARBALL="$(NPM_DIST_JSON="$NPM_DIST_JSON" node --input-type=module <<'EOF'
+          const dist = JSON.parse(process.env.NPM_DIST_JSON ?? "{}");
+          process.stdout.write(String(dist["dist.tarball"] ?? ""));
+          EOF
+          )"
+          NPM_INTEGRITY="$(NPM_DIST_JSON="$NPM_DIST_JSON" node --input-type=module <<'EOF'
+          const dist = JSON.parse(process.env.NPM_DIST_JSON ?? "{}");
+          process.stdout.write(String(dist["dist.integrity"] ?? ""));
+          EOF
+          )"
+          if [[ -z "$NPM_TARBALL" || -z "$NPM_INTEGRITY" ]]; then
+            echo "npm dist metadata for clawhub@${PACKAGE_VERSION} is incomplete." >&2
+            exit 1
+          fi
+          {
+            echo "PACKAGE_VERSION=$PACKAGE_VERSION"
+            echo "NPM_PACKAGE_URL=https://www.npmjs.com/package/clawhub/v/${PACKAGE_VERSION}"
+            echo "NPM_TARBALL_URL=$NPM_TARBALL"
+            echo "NPM_INTEGRITY=$NPM_INTEGRITY"
+            echo "RELEASE_TITLE=clawhub ${PACKAGE_VERSION}"
+          } >> "$GITHUB_ENV"
+
+      - name: Write npm publish proof artifact
+        id: publish_proof
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          PUBLISH_PROOF_DIR="$RUNNER_TEMP/clawhub-cli-npm-publish-proof"
+          rm -rf "$PUBLISH_PROOF_DIR"
+          mkdir -p "$PUBLISH_PROOF_DIR"
+          printf '%s\n' "$RELEASE_TAG" > "$PUBLISH_PROOF_DIR/release-tag.txt"
+          git rev-parse HEAD > "$PUBLISH_PROOF_DIR/release-sha.txt"
+          printf '%s\n' "$PACKAGE_VERSION" > "$PUBLISH_PROOF_DIR/package-version.txt"
+          printf '%s\n' "$NPM_TARBALL_URL" > "$PUBLISH_PROOF_DIR/npm-tarball-url.txt"
+          printf '%s\n' "$NPM_INTEGRITY" > "$PUBLISH_PROOF_DIR/npm-integrity.txt"
+          printf '%s\n' "$GITHUB_RUN_ID" > "$PUBLISH_PROOF_DIR/publish-run-id.txt"
+          printf '%s\n' "false" > "$PUBLISH_PROOF_DIR/preflight-only.txt"
+          echo "dir=$PUBLISH_PROOF_DIR" >> "$GITHUB_OUTPUT"
+
+      - name: Upload npm publish proof artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: clawhub-cli-npm-publish-${{ inputs.tag }}
+          path: ${{ steps.publish_proof.outputs.dir }}
+          if-no-files-found: error
+
+      - name: Build GitHub Release notes
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          node release-tools/scripts/extract-changelog-release.mjs --tag "$RELEASE_TAG" > release-body.md
+          {
+            echo
+            echo "### Release Proof"
+            echo
+            echo "- npm: ${NPM_PACKAGE_URL}"
+            echo "- tarball: ${NPM_TARBALL_URL}"
+            echo "- integrity: ${NPM_INTEGRITY}"
+            echo "- npm preflight: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${{ inputs.preflight_run_id }}"
+            echo "- npm publish: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+          } >> release-body.md
+
+      - name: Create or update GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "$RELEASE_TITLE" \
+              --notes-file release-body.md
+          else
+            gh release create "$RELEASE_TAG" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "$RELEASE_TITLE" \
+              --notes-file release-body.md
+          fi
@@ -0,0 +1,57 @@
+name: ClawHub Rescan Guidance
+
+on:
+  issues:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      issue:
+        description: "Issue number to check"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: clawhub-rescan-guidance-${{ github.event.issue.number || github.event.inputs.issue }}
+  cancel-in-progress: false
+
+jobs:
+  rescan-guidance:
+    runs-on: ubuntu-latest
+    if: "${{ github.event_name == 'workflow_dispatch' || github.event.label.name == 'r: rescan-guidance' }}"
+    env:
+      CLAWHUB_RESCAN_GUIDANCE_APPLY: "1"
+      ISSUE_NUMBER: ${{ github.event.issue.number || github.event.inputs.issue }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        continue-on-error: true
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token-fallback
+        continue-on-error: true
+        if: steps.app-token.outcome == 'failure'
+        with:
+          app-id: "2971289"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
+
+      - name: Comment when rescan guidance label is present
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token || github.token }}
+        run: |
+          node scripts/github/clawhub-rescan-auto-response.mjs \
+            --repo "$GITHUB_REPOSITORY" \
+            --issue "$ISSUE_NUMBER" \
+            --comment-for-labeled-issue \
+            --apply
@@ -0,0 +1,158 @@
+name: ClawSweeper Dispatch
+
+on:
+  issues:
+    types: [opened, reopened, edited, labeled, unlabeled]
+  issue_comment:
+    types: [created, edited]
+  pull_request_target: # zizmor: ignore[dangerous-triggers] maintainer-owned external dispatch; no checkout or untrusted PR code execution
+    types: [opened, reopened, synchronize, ready_for_review, edited, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: clawsweeper-dispatch-${{ github.repository }}-${{ github.event.issue.number || github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event.action == 'edited' || github.event.action == 'synchronize' || github.event.action == 'ready_for_review' }}
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'issue_comment' || !(endsWith(github.actor, '[bot]') && (github.event.action == 'labeled' || github.event.action == 'unlabeled')) }}
+    env:
+      HAS_CLAWSWEEPER_APP_PRIVATE_KEY: ${{ secrets.CLAWSWEEPER_APP_PRIVATE_KEY != '' }}
+      CLAWSWEEPER_APP_CLIENT_ID: Iv23liOECG0slfuhz093
+      SUPERSEDES_IN_PROGRESS: ${{ (github.event.action == 'edited' || github.event.action == 'synchronize' || github.event.action == 'ready_for_review') && 'true' || 'false' }}
+    steps:
+      - name: Debounce bursty metadata events
+        if: ${{ github.event.action == 'labeled' || github.event.action == 'unlabeled' }}
+        run: sleep 20
+
+      - name: Create ClawSweeper dispatch token
+        id: token
+        if: ${{ env.HAS_CLAWSWEEPER_APP_PRIVATE_KEY == 'true' }}
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ env.CLAWSWEEPER_APP_CLIENT_ID }}
+          private-key: ${{ secrets.CLAWSWEEPER_APP_PRIVATE_KEY }}
+          owner: openclaw
+          repositories: clawsweeper
+          permission-contents: write
+
+      - name: Create target comment token
+        id: target_token
+        if: ${{ github.event_name == 'issue_comment' && env.HAS_CLAWSWEEPER_APP_PRIVATE_KEY == 'true' }}
+        uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1
+        with:
+          client-id: ${{ env.CLAWSWEEPER_APP_CLIENT_ID }}
+          private-key: ${{ secrets.CLAWSWEEPER_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: ${{ github.event.repository.name }}
+          permission-issues: write
+          permission-pull-requests: read
+
+      - name: Dispatch exact ClawSweeper review
+        if: ${{ github.event_name == 'issues' || github.event_name == 'pull_request_target' }}
+        env:
+          GH_TOKEN: ${{ steps.token.outputs.token }}
+          TARGET_REPO: ${{ github.repository }}
+          ITEM_NUMBER: ${{ github.event.issue.number || github.event.pull_request.number }}
+          ITEM_KIND: ${{ github.event_name == 'pull_request_target' && 'pull_request' || 'issue' }}
+          SOURCE_EVENT: ${{ github.event_name }}
+          SOURCE_ACTION: ${{ github.event.action }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::notice::Skipping ClawSweeper dispatch because no dispatch credential is configured."
+            exit 0
+          fi
+          payload="$(jq -nc \
+            --arg target_repo "$TARGET_REPO" \
+            --argjson item_number "$ITEM_NUMBER" \
+            --arg item_kind "$ITEM_KIND" \
+            --arg source_event "$SOURCE_EVENT" \
+            --arg source_action "$SOURCE_ACTION" \
+            --argjson supersedes_in_progress "$SUPERSEDES_IN_PROGRESS" \
+            '{event_type:"clawsweeper_item",client_payload:{target_repo:$target_repo,item_number:$item_number,item_kind:$item_kind,source_event:$source_event,source_action:$source_action,supersedes_in_progress:$supersedes_in_progress}}')"
+          gh api repos/openclaw/clawsweeper/dispatches \
+            --method POST \
+            --input - <<< "$payload"
+
+      - name: Acknowledge and dispatch ClawSweeper comment
+        if: ${{ github.event_name == 'issue_comment' }}
+        env:
+          DISPATCH_TOKEN: ${{ steps.token.outputs.token }}
+          TARGET_TOKEN: ${{ steps.target_token.outputs.token }}
+          TARGET_REPO: ${{ github.repository }}
+          ITEM_NUMBER: ${{ github.event.issue.number }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          AUTHOR_ASSOCIATION: ${{ github.event.comment.author_association }}
+          SOURCE_ACTION: ${{ github.event.action }}
+        run: |
+          set -euo pipefail
+          if [ -z "$DISPATCH_TOKEN" ]; then
+            echo "::notice::Skipping ClawSweeper comment dispatch because no ClawSweeper app token is configured."
+            exit 0
+          fi
+          body_file="$RUNNER_TEMP/clawsweeper-comment-body.txt"
+          printf '%s\n' "$COMMENT_BODY" > "$body_file"
+          if ! grep -Eiq '(^|[[:space:]])@(clawsweeper|openclaw-clawsweeper)\b(\[bot\])?|(^|[[:space:]])/(clawsweeper|review|automerge|autoclose)\b' "$body_file"; then
+            echo "No ClawSweeper command found in comment."
+            exit 0
+          fi
+          if [ -n "$TARGET_TOKEN" ]; then
+            err="$(mktemp)"
+            if GH_TOKEN="$TARGET_TOKEN" gh api -X POST \
+              -H "Accept: application/vnd.github+json" \
+              "repos/$TARGET_REPO/issues/comments/$COMMENT_ID/reactions" \
+              -f content="eyes" 2>"$err" >/dev/null; then
+              echo "Acknowledged ClawSweeper command comment."
+            elif grep -qi "HTTP 422\\|already exists" "$err"; then
+              echo "ClawSweeper command comment already acknowledged."
+            else
+              cat "$err" >&2
+              echo "::warning::Could not acknowledge ClawSweeper command comment."
+            fi
+            rm -f "$err"
+          else
+            echo "::notice::Skipping ClawSweeper comment acknowledgement because no target token is configured."
+          fi
+          status_comment_id=""
+          if [ -n "$TARGET_TOKEN" ]; then
+            case "$AUTHOR_ASSOCIATION" in
+              OWNER|MEMBER|COLLABORATOR)
+                status_body="$(printf '%s\n' \
+                  "<!-- clawsweeper-command-ack:$COMMENT_ID -->" \
+                  "ClawSweeper picked this up." \
+                  "" \
+                  "Command router queued. I will update this comment with the next step.")"
+                status_payload="$(jq -nc --arg body "$status_body" '{body:$body}')"
+                status_err="$(mktemp)"
+                if status_response="$(GH_TOKEN="$TARGET_TOKEN" gh api \
+                  "repos/$TARGET_REPO/issues/$ITEM_NUMBER/comments" \
+                  --method POST \
+                  --input - <<< "$status_payload" 2>"$status_err")"; then
+                  status_comment_id="$(jq -r '.id // empty' <<< "$status_response")"
+                else
+                  cat "$status_err" >&2
+                  echo "::warning::Could not create ClawSweeper queued status comment; dispatching command router without one."
+                fi
+                rm -f "$status_err"
+                ;;
+            esac
+          fi
+          payload="$(jq -nc \
+            --arg target_repo "$TARGET_REPO" \
+            --argjson item_number "$ITEM_NUMBER" \
+            --argjson comment_id "$COMMENT_ID" \
+            --arg status_comment_id "$status_comment_id" \
+            --arg source_event "issue_comment" \
+            --arg source_action "$SOURCE_ACTION" \
+            '{event_type:"clawsweeper_comment",client_payload:({target_repo:$target_repo,item_number:$item_number,comment_id:$comment_id,source_event:$source_event,source_action:$source_action,max_comments:"1"} + (if $status_comment_id != "" then {status_comment_id:($status_comment_id|tonumber)} else {} end))}')"
+          if GH_TOKEN="$DISPATCH_TOKEN" gh api repos/openclaw/clawsweeper/dispatches \
+            --method POST \
+            --input - <<< "$payload"; then
+            echo "Dispatched ClawSweeper comment router."
+          else
+            echo "::warning::Skipping ClawSweeper comment dispatch because the configured credential could not dispatch to openclaw/clawsweeper."
+          fi
@@ -0,0 +1,100 @@
+name: CodeQL Light
+
+on:
+  workflow_dispatch:
+    inputs:
+      profile:
+        description: CodeQL light profile to run
+        required: false
+        default: all
+        type: choice
+        options:
+          - all
+          - backend-api
+          - frontend-publish
+          - cli-package
+          - repository-automation
+          - actions
+  push:
+    branches: [main]
+    paths:
+      - ".github/codeql/**"
+      - ".github/workflows/**"
+      - "convex/**"
+      - "packages/clawhub/**"
+      - "packages/schema/**"
+      - "scripts/**"
+      - "src/**"
+      - "bun.lock"
+      - "package.json"
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - ".github/codeql/**"
+      - ".github/workflows/**"
+      - "convex/**"
+      - "packages/clawhub/**"
+      - "packages/schema/**"
+      - "scripts/**"
+      - "src/**"
+      - "bun.lock"
+      - "package.json"
+  schedule:
+    - cron: "17 7 * * *"
+
+concurrency:
+  group: codeql-light-${{ github.event_name == 'workflow_dispatch' && github.run_id || github.event_name == 'pull_request' && github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.category }})
+    if: ${{ github.event_name != 'pull_request' || !github.event.pull_request.draft }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: javascript-typescript
+            category: backend-api
+            config_file: ./.github/codeql/codeql-backend-api-security.yml
+          - language: javascript-typescript
+            category: frontend-publish
+            config_file: ./.github/codeql/codeql-frontend-publish-security.yml
+          - language: javascript-typescript
+            category: cli-package
+            config_file: ./.github/codeql/codeql-cli-package-security.yml
+          - language: javascript-typescript
+            category: repository-automation
+            config_file: ./.github/codeql/codeql-repository-automation-security.yml
+          - language: actions
+            category: actions
+            config_file: ./.github/codeql/codeql-actions-security.yml
+    steps:
+      - name: Checkout
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.profile == 'all' || inputs.profile == matrix.category }}
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+        with:
+          submodules: false
+
+      - name: Initialize CodeQL
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.profile == 'all' || inputs.profile == matrix.category }}
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
+        with:
+          languages: ${{ matrix.language }}
+          config-file: ${{ matrix.config_file }}
+
+      - name: Analyze
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.profile == 'all' || inputs.profile == matrix.category }}
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4
+        with:
+          category: "/codeql-light/${{ matrix.category }}"
@@ -12,11 +12,20 @@ on:
          - full
          - backend
          - frontend
+      allow_deleting_large_indexes:
+        description: "Allow Convex to delete large indexes"
+        required: true
+        default: false
+        type: boolean

 concurrency:
  group: deploy-production
  cancel-in-progress: true

+permissions:
+  contents: write
+  statuses: read
+
 jobs:
  validate-deploy-request:
    runs-on: ubuntu-latest
@@ -90,6 +99,7 @@ jobs:
          fi

          echo "Deploy target: ${{ needs.validate-deploy-request.outputs.target }}"
+          echo "Allow deleting large Convex indexes: ${{ inputs.allow_deleting_large_indexes }}"

          if [[ -z "$PLAYWRIGHT_AUTH_STORAGE_STATE_JSON" ]]; then
            echo "PLAYWRIGHT_AUTH_STORAGE_STATE_JSON not set; authenticated smoke will be skipped."
@@ -97,7 +107,7 @@ jobs:

      - uses: actions/checkout@v6

-      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
        with:
          bun-version: 1.3.10

@@ -114,13 +124,20 @@ jobs:

      - name: Deploy Convex
        if: needs.validate-deploy-request.outputs.deploy_backend == 'true'
-        run: bun run convex:deploy
+        run: |
+          set -euo pipefail
+          if [[ "${{ inputs.allow_deleting_large_indexes }}" == "true" ]]; then
+            bunx convex deploy --typecheck=disable --yes --allow-deleting-large-indexes
+          else
+            bun run convex:deploy
+          fi

      - name: Verify Convex contract
        if: needs.validate-deploy-request.outputs.deploy_backend == 'true'
        run: bun run verify:convex-contract -- --prod

      - name: Wait for Vercel production deployment
+        id: vercel
        if: needs.validate-deploy-request.outputs.deploy_frontend == 'true'
        env:
          GH_TOKEN: ${{ github.token }}
@@ -130,17 +147,26 @@ jobs:
        run: |
          set -euo pipefail
          for attempt in {1..90}; do
-            if ! state="$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status" \
-              --jq '.statuses[] | select(.context == env.VERCEL_STATUS_CONTEXT) | .state' \
+            if ! status_json="$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status" \
+              --jq '.statuses[] | select(.context == env.VERCEL_STATUS_CONTEXT) | {state, target_url, description} | @base64' \
              2>/dev/null | head -n1)"; then
-              echo "GitHub status check failed for $GITHUB_SHA; retrying..."
+              echo "GitHub status check failed for $GITHUB_SHA on attempt $attempt; retrying..."
              sleep 10
              continue
            fi

+            if [[ -z "$status_json" ]]; then
+              state=""
+              target_url=""
+            else
+              state="$(printf '%s' "$status_json" | base64 -d | jq -r '.state // ""')"
+              target_url="$(printf '%s' "$status_json" | base64 -d | jq -r '.target_url // ""')"
+            fi
+
            case "$state" in
              success)
                echo "Vercel production deployment ready for $GITHUB_SHA"
+                echo "deployment_url=$target_url" >> "$GITHUB_OUTPUT"
                exit 0
                ;;
              failure|error)
@@ -148,10 +174,10 @@ jobs:
                exit 1
                ;;
              pending)
-                echo "Vercel deployment pending for $GITHUB_SHA; waiting..."
+                echo "Vercel deployment pending for $GITHUB_SHA on attempt $attempt; waiting..."
                ;;
              *)
-                echo "Vercel status for $GITHUB_SHA not published yet; waiting..."
+                echo "Vercel status for $GITHUB_SHA not published yet on attempt $attempt; waiting..."
                ;;
            esac

@@ -162,15 +188,63 @@ jobs:
          exit 1

      - name: Install Playwright browser
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true' && needs.validate-deploy-request.outputs.deploy_frontend == 'true'
+        run: bunx playwright install --with-deps chromium webkit
+
+      - name: Smoke test production HTTP
        if: needs.validate-deploy-request.outputs.run_smoke == 'true'
-        run: bunx playwright install --with-deps chromium
+        run: bun run test:e2e:prod-http

      - name: Write authenticated storage state
-        if: needs.validate-deploy-request.outputs.run_smoke == 'true' && env.PLAYWRIGHT_AUTH_STORAGE_STATE_JSON != ''
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true' && needs.validate-deploy-request.outputs.deploy_frontend == 'true' && env.PLAYWRIGHT_AUTH_STORAGE_STATE_JSON != ''
        run: |
          echo "$PLAYWRIGHT_AUTH_STORAGE_STATE_JSON" > "$RUNNER_TEMP/playwright-auth.json"
          echo "PLAYWRIGHT_AUTH_STORAGE_STATE=$RUNNER_TEMP/playwright-auth.json" >> "$GITHUB_ENV"

-      - name: Smoke test production
-        if: needs.validate-deploy-request.outputs.run_smoke == 'true'
-        run: bunx playwright test e2e/menu-smoke.pw.test.ts e2e/upload-auth-smoke.pw.test.ts
+      - name: Smoke test production UI
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true' && needs.validate-deploy-request.outputs.deploy_frontend == 'true'
+        run: bunx playwright test --workers=1 e2e/menu-smoke.pw.test.ts e2e/publish-entry-workflows.pw.test.ts e2e/upload-auth-smoke.pw.test.ts
+
+      - name: Tag production frontend deployment
+        if: needs.validate-deploy-request.outputs.deploy_frontend == 'true'
+        env:
+          DEPLOY_TARGET: ${{ needs.validate-deploy-request.outputs.target }}
+          DEPLOYMENT_URL: ${{ steps.vercel.outputs.deployment_url }}
+        run: |
+          set -euo pipefail
+          deployed_at="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+          tag_name="deploy/prod/$(date -u +"%Y%m%d-%H%M%SZ")-${GITHUB_SHA::7}"
+          version_prefix="prod/v$(date -u +"%Y.%m.%d")."
+          run_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          next_version=1
+          while IFS= read -r existing_tag; do
+            existing_tag="${existing_tag#refs/tags/}"
+            existing_tag="${existing_tag%\^\{\}}"
+            suffix="${existing_tag##*.}"
+            if [[ "$existing_tag" == "$version_prefix"* && "$suffix" =~ ^[0-9]+$ && "$suffix" -ge "$next_version" ]]; then
+              next_version=$((suffix + 1))
+            fi
+          done < <(git ls-remote --tags origin "refs/tags/${version_prefix}*" | awk '{print $2}' | sort -u)
+          version_tag="${version_prefix}${next_version}"
+
+          git tag -a "$tag_name" "$GITHUB_SHA" \
+            -m "Production frontend deploy $tag_name" \
+            -m "SHA: $GITHUB_SHA" \
+            -m "Version: $version_tag" \
+            -m "Deployed at: $deployed_at" \
+            -m "Target: $DEPLOY_TARGET" \
+            -m "Vercel: ${DEPLOYMENT_URL:-unknown}" \
+            -m "Run: $run_url"
+          git tag -a "$version_tag" "$GITHUB_SHA" \
+            -m "Production frontend deploy $version_tag" \
+            -m "SHA: $GITHUB_SHA" \
+            -m "Timestamp tag: $tag_name" \
+            -m "Deployed at: $deployed_at" \
+            -m "Target: $DEPLOY_TARGET" \
+            -m "Vercel: ${DEPLOYMENT_URL:-unknown}" \
+            -m "Run: $run_url"
+          git push origin "refs/tags/$tag_name" "refs/tags/$version_tag"
@@ -0,0 +1,36 @@
+name: OpenClaw Docs Sync Dispatch
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - .github/workflows/openclaw-docs-sync-dispatch.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch-openclaw-docs-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch OpenClaw docs sync
+        env:
+          OPENCLAW_DOCS_SYNC_TOKEN: ${{ secrets.OPENCLAW_DOCS_SYNC_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${OPENCLAW_DOCS_SYNC_TOKEN:-}" ]; then
+            echo "::error::OPENCLAW_DOCS_SYNC_TOKEN is required to dispatch openclaw/openclaw docs sync."
+            exit 1
+          fi
+
+          curl --fail-with-body --silent --show-error \
+            --request POST \
+            --header "Authorization: Bearer ${OPENCLAW_DOCS_SYNC_TOKEN}" \
+            --header "Accept: application/vnd.github+json" \
+            --header "X-GitHub-Api-Version: 2022-11-28" \
+            https://api.github.com/repos/openclaw/openclaw/actions/workflows/docs-sync-publish.yml/dispatches \
+            --data '{"ref":"main"}'
@@ -57,11 +57,28 @@ on:
        description: Optional source ref override for local-folder publishes.
        required: false
        type: string
-      clawhub_version:
-        description: Legacy npm CLI version input. Kept for compatibility; the workflow now runs the checked-out source.
+      source_path:
+        description: Optional source path inside the repository for monorepo package publishes.
        required: false
        type: string
-        default: latest
+      package_artifact_name:
+        description: Optional Actions artifact name containing a prebuilt ClawPack .tgz to publish.
+        required: false
+        type: string
+      package_artifact_path:
+        description: Optional path to the .tgz inside package_artifact_name. Defaults to the only .tgz in the artifact.
+        required: false
+        type: string
+      inspector_artifact_name:
+        description: Artifact name for plugin inspector reports. Set a unique value when calling this workflow from a matrix.
+        required: false
+        type: string
+        default: plugin-inspector-report
+      publish_json_artifact_name:
+        description: Artifact name for the package publish JSON output. Set a unique value when calling this workflow from a matrix.
+        required: false
+        type: string
+        default: clawhub-package-publish-json
    secrets:
      clawhub_token:
        required: false
@@ -73,11 +90,17 @@ on:
        description: Published release id when dry_run is false.
        value: ${{ jobs.publish.outputs.release_id }}

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions: {}
+
 jobs:
  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
+      actions: read
      contents: read
      id-token: write
    outputs:
@@ -88,7 +111,7 @@ jobs:
        with:
          ref: ${{ github.sha }}

-      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
        with:
          bun-version: 1.3.10

@@ -209,7 +232,56 @@ jobs:
          PY
          echo "CLAWHUB_CONFIG_PATH=$RUNNER_TEMP/clawhub-config.json" >> "$GITHUB_ENV"

+      - name: Download prebuilt package artifact
+        if: inputs.package_artifact_name != ''
+        uses: actions/download-artifact@v8
+        with:
+          name: ${{ inputs.package_artifact_name }}
+          path: ${{ runner.temp }}/prebuilt-package-artifact
+
+      - name: Resolve prebuilt package artifact
+        id: resolve_artifact
+        env:
+          INPUT_PACKAGE_ARTIFACT_NAME: ${{ inputs.package_artifact_name }}
+          INPUT_PACKAGE_ARTIFACT_PATH: ${{ inputs.package_artifact_path }}
+        run: |
+          python3 - <<'PY'
+          import os
+          from pathlib import Path
+
+          artifact_name = os.environ["INPUT_PACKAGE_ARTIFACT_NAME"].strip()
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          if not artifact_name:
+              with output_path.open("a", encoding="utf-8") as fh:
+                  fh.write("package_artifact_path=\n")
+              raise SystemExit(0)
+
+          artifact_root = Path(os.environ["RUNNER_TEMP"]) / "prebuilt-package-artifact"
+          requested_path = os.environ["INPUT_PACKAGE_ARTIFACT_PATH"].strip()
+          if requested_path:
+              candidate = (artifact_root / requested_path).resolve()
+              if artifact_root.resolve() not in candidate.parents and candidate != artifact_root.resolve():
+                  raise SystemExit(f"Prebuilt artifact path escapes downloaded artifact: {requested_path}")
+              if not candidate.is_file():
+                  raise SystemExit(f"Prebuilt package artifact path not found: {requested_path}")
+          else:
+              candidates = sorted(path for path in artifact_root.rglob("*.tgz") if path.is_file())
+              if not candidates:
+                  raise SystemExit(f"Prebuilt package artifact {artifact_name!r} did not contain a .tgz file.")
+              if len(candidates) > 1:
+                  joined = ", ".join(str(path.relative_to(artifact_root)) for path in candidates)
+                  raise SystemExit(
+                      "Prebuilt package artifact contains multiple .tgz files; set package_artifact_path. "
+                      f"Found: {joined}"
+                  )
+              candidate = candidates[0]
+
+          with output_path.open("a", encoding="utf-8") as fh:
+              fh.write(f"package_artifact_path={candidate}\n")
+          PY
+
      - name: Resolve publish command
+        id: resolve_publish
        env:
          INPUT_SOURCE: ${{ inputs.source }}
          INPUT_REF: ${{ inputs.ref }}
@@ -220,9 +292,12 @@ jobs:
          INPUT_SOURCE_REPO: ${{ inputs.source_repo }}
          INPUT_SOURCE_COMMIT: ${{ inputs.source_commit }}
          INPUT_SOURCE_REF: ${{ inputs.source_ref }}
+          INPUT_SOURCE_PATH: ${{ inputs.source_path }}
+          PREBUILT_PACKAGE_ARTIFACT_PATH: ${{ steps.resolve_artifact.outputs.package_artifact_path }}
          INPUT_SITE: ${{ inputs.site }}
          INPUT_REGISTRY: ${{ inputs.registry }}
          CLAWHUB_TOKEN: ${{ secrets.clawhub_token }}
+          GITHUB_TOKEN: ${{ github.token }}
          GITHUB_EVENT_NAME: ${{ github.event_name }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_REF: ${{ github.ref }}
@@ -233,6 +308,78 @@ jobs:
          import os
          import shlex
          from pathlib import Path
+          from urllib.error import HTTPError
+          from urllib.parse import quote, urlparse
+          from urllib.request import Request, urlopen
+
+          def split_ref_path(value):
+              if not value:
+                  return "", ""
+              if ":" not in value:
+                  return value, ""
+              ref, path = value.split(":", 1)
+              return ref, path.strip("/")
+
+          def github_commit_exists(repo, ref):
+              token = os.environ.get("GITHUB_TOKEN", "").strip()
+              headers = {
+                  "Accept": "application/vnd.github+json",
+                  "User-Agent": "clawhub-package-publish",
+              }
+              if token:
+                  headers["Authorization"] = f"Bearer {token}"
+              request = Request(
+                  f"https://api.github.com/repos/{repo}/commits/{quote(ref, safe='')}",
+                  headers=headers,
+              )
+              try:
+                  with urlopen(request, timeout=10) as response:
+                      return 200 <= response.status < 300
+              except HTTPError as error:
+                  if error.code in (404, 422):
+                      return False
+                  raise
+
+          def resolve_github_url_ref_and_path(repo, kind, segments):
+              min_path_segments = 1 if kind == "blob" else 0
+              max_ref_segments = len(segments) - min_path_segments
+              for ref_segment_count in range(max_ref_segments, 0, -1):
+                  ref = "/".join(segments[:ref_segment_count])
+                  path = "/".join(segments[ref_segment_count:]).strip("/")
+                  if kind == "blob" and not path:
+                      continue
+                  if not github_commit_exists(repo, ref):
+                      continue
+                  if kind == "blob":
+                      path = "/".join(path.split("/")[:-1]).strip("/")
+                  return ref, path
+              raise SystemExit(f"GitHub ref not found in source URL for {repo}")
+
+          def parse_github_source(value):
+              raw = value.strip()
+              if raw.startswith("github:"):
+                  raw = raw[len("github:"):]
+              if raw.startswith("https://") or raw.startswith("http://"):
+                  parsed = urlparse(raw)
+                  if parsed.netloc.lower() != "github.com":
+                      return None
+                  parts = [part for part in parsed.path.strip("/").split("/") if part]
+                  if len(parts) < 2:
+                      return None
+                  repo_name = parts[1][:-4] if parts[1].endswith(".git") else parts[1]
+                  repo = f"{parts[0]}/{repo_name}"
+                  if len(parts) >= 4 and parts[2] in {"tree", "blob"}:
+                      ref, path = resolve_github_url_ref_and_path(repo, parts[2], parts[3:])
+                      return {"repo": repo, "ref": ref, "path": path}
+                  return {"repo": repo, "ref": "", "path": ""}
+
+              source_part, at, ref_part = raw.partition("@")
+              repo_parts = source_part.split("/")
+              if len(repo_parts) != 2 or not repo_parts[0] or not repo_parts[1]:
+                  return None
+              repo_name = repo_parts[1][:-4] if repo_parts[1].endswith(".git") else repo_parts[1]
+              ref, path = split_ref_path(ref_part if at else "")
+              return {"repo": f"{repo_parts[0]}/{repo_name}", "ref": ref, "path": path}

          source = os.environ["INPUT_SOURCE"].strip()
          if not source:
@@ -244,6 +391,33 @@ jobs:
          is_local_source = source.startswith(".") or source.startswith("/") or Path(source).exists()
          if ref and "@" not in source and not source.startswith("http") and not is_local_source:
              source = f"{source}@{ref}"
+          source_path = os.environ["INPUT_SOURCE_PATH"].strip()
+          prebuilt_artifact_path = os.environ["PREBUILT_PACKAGE_ARTIFACT_PATH"].strip()
+          inspect_checkout_repository = ""
+          inspect_checkout_ref = ""
+          inspect_local_root = str(Path(os.environ["GITHUB_WORKSPACE"]).resolve())
+          inspect_subdir = source_path
+          if prebuilt_artifact_path:
+              inspect_local_root = str((Path(os.environ["RUNNER_TEMP"]) / "prebuilt-package-inspect").resolve())
+              inspect_subdir = ""
+          elif is_local_source:
+              inspect_local_root = str(Path(source).resolve())
+          else:
+              github_source = parse_github_source(source)
+              source_ref_differs_from_checkout = (
+                  bool(github_source and github_source["ref"])
+                  and github_source["ref"] != os.environ["GITHUB_SHA"]
+              )
+              if github_source and (
+                  github_source["repo"] != os.environ["GITHUB_REPOSITORY"]
+                  or source_ref_differs_from_checkout
+              ):
+                  inspect_checkout_repository = github_source["repo"]
+                  inspect_checkout_ref = github_source["ref"]
+                  inspect_local_root = str((Path(os.environ["GITHUB_WORKSPACE"]) / "clawhub-publish-source").resolve())
+                  inspect_subdir = source_path or github_source["path"]
+              elif github_source:
+                  inspect_subdir = source_path or github_source["path"]

          cli_entry = (
              Path(os.environ["GITHUB_WORKSPACE"])
@@ -256,12 +430,13 @@ jobs:
          if not cli_entry.exists():
              raise SystemExit(f"Missing ClawHub CLI entrypoint at {cli_entry}")

+          cmd_source = prebuilt_artifact_path or source
          cmd = [
              "bun",
              str(cli_entry),
              "package",
              "publish",
-              source,
+              cmd_source,
              "--site",
              os.environ["INPUT_SITE"],
              "--registry",
@@ -284,6 +459,16 @@ jobs:
          source_repo = os.environ["INPUT_SOURCE_REPO"].strip()
          source_commit = os.environ["INPUT_SOURCE_COMMIT"].strip()
          source_ref = os.environ["INPUT_SOURCE_REF"].strip()
+          if prebuilt_artifact_path:
+              if not source_repo and not source_commit:
+                  source_repo = os.environ["GITHUB_REPOSITORY"].strip()
+                  source_commit = os.environ["GITHUB_SHA"].strip()
+              elif not source_repo or not source_commit:
+                  raise SystemExit(
+                      "Prebuilt artifact mode requires source_repo and source_commit together when overriding source attribution."
+                  )
+              if not source_ref:
+                  source_ref = os.environ["GITHUB_REF"].strip()
          if source_repo:
              cmd += ["--source-repo", source_repo]
          if source_commit:
@@ -294,6 +479,8 @@ jobs:
              github_ref = os.environ["GITHUB_REF"].strip()
              if github_ref:
                  cmd += ["--source-ref", github_ref]
+          if source_path:
+              cmd += ["--source-path", source_path]
          if os.environ["INPUT_DRY_RUN"] != "true" and os.environ["CLAWHUB_TOKEN"].strip():
              cmd += [
                  "--manual-override-reason",
@@ -305,8 +492,65 @@ jobs:
          path.write_text("#!/usr/bin/env bash\nset -euo pipefail\n" + shell_line + "\n", encoding="utf-8")
          path.chmod(0o755)
          print(shell_line)
+
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          with output_path.open("a", encoding="utf-8") as fh:
+              fh.write(f"inspect_checkout_repository={inspect_checkout_repository}\n")
+              fh.write(f"inspect_checkout_ref={inspect_checkout_ref}\n")
+              fh.write(f"inspect_local_root={inspect_local_root}\n")
+              fh.write(f"inspect_subdir={inspect_subdir}\n")
          PY

+      - name: Extract prebuilt package artifact for plugin validation
+        if: steps.resolve_artifact.outputs.package_artifact_path != ''
+        env:
+          PREBUILT_PACKAGE_ARTIFACT_PATH: ${{ steps.resolve_artifact.outputs.package_artifact_path }}
+          INSPECT_LOCAL_ROOT: ${{ steps.resolve_publish.outputs.inspect_local_root }}
+        run: |
+          set -euo pipefail
+          mkdir -p "$INSPECT_LOCAL_ROOT"
+          tar -xzf "$PREBUILT_PACKAGE_ARTIFACT_PATH" -C "$INSPECT_LOCAL_ROOT" --strip-components=1
+
+      - name: Checkout publish source for plugin inspector
+        if: steps.resolve_publish.outputs.inspect_checkout_repository != ''
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.resolve_publish.outputs.inspect_checkout_repository }}
+          ref: ${{ steps.resolve_publish.outputs.inspect_checkout_ref }}
+          path: clawhub-publish-source
+
+      - name: Run plugin validation
+        env:
+          INSPECT_LOCAL_ROOT: ${{ steps.resolve_publish.outputs.inspect_local_root }}
+          INSPECT_SUBDIR: ${{ steps.resolve_publish.outputs.inspect_subdir }}
+        run: |
+          set -euo pipefail
+          inspect_root="$(python3 - <<'PY'
+          import os
+          from pathlib import Path
+
+          root = Path(os.environ["INSPECT_LOCAL_ROOT"]).resolve()
+          subdir = os.environ["INSPECT_SUBDIR"].strip()
+          inspect_root = (root / subdir).resolve() if subdir else root
+          if inspect_root != root and root not in inspect_root.parents:
+              raise SystemExit(f"Inspector source path escapes publish source: {subdir}")
+          print(inspect_root)
+          PY
+          )"
+          if [ ! -f "$inspect_root/package.json" ] && [ ! -f "$inspect_root/openclaw.plugin.json" ]; then
+            echo "::warning::Plugin Inspector skipped because $inspect_root is not a plugin root."
+            exit 0
+          fi
+          bun "$GITHUB_WORKSPACE/clawhub-source/packages/clawhub/src/cli.ts" package validate "$inspect_root" --out "$RUNNER_TEMP/plugin-inspector"
+
+      - name: Upload plugin inspector reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ inputs.inspector_artifact_name }}
+          path: ${{ runner.temp }}/plugin-inspector
+          if-no-files-found: ignore
+
      - name: Run package publish
        run: |
          set -euo pipefail
@@ -334,8 +578,8 @@ jobs:
          PY

      - name: Upload publish JSON artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
-          name: clawhub-package-publish-json
+          name: ${{ inputs.publish_json_artifact_name }}
          path: ${{ runner.temp }}/package-publish.json
          if-no-files-found: error
@@ -0,0 +1,63 @@
+name: Plugin Inspector Bulk Scan
+
+on:
+  workflow_dispatch:
+    inputs:
+      batch_size:
+        description: "Maximum plugin releases to scan"
+        required: false
+        default: "25"
+      dry_run:
+        description: "Preview impact without persisting findings or sending emails"
+        required: false
+        default: "false"
+        type: boolean
+      dry_run_max_batches:
+        description: "Maximum preview batches to scan when dry_run is enabled"
+        required: false
+        default: "20"
+      source_pr:
+        description: "Merged PR number that triggered this scan, when dispatched automatically"
+        required: false
+        default: ""
+      source_sha:
+        description: "Merged commit SHA that triggered this scan, when dispatched automatically"
+        required: false
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    name: Scan published plugins
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run plugin inspector bulk scan
+        env:
+          CLAWHUB_SITE_URL: ${{ vars.CLAWHUB_SITE_URL || 'https://clawhub.ai' }}
+          CLAWHUB_PLUGIN_INSPECTOR_WORKER_TOKEN: ${{ secrets.CLAWHUB_PLUGIN_INSPECTOR_WORKER_TOKEN }}
+          PLUGIN_INSPECTOR_BATCH_SIZE: ${{ inputs.batch_size || '25' }}
+          PLUGIN_INSPECTOR_DRY_RUN: ${{ inputs.dry_run && '1' || '0' }}
+          PLUGIN_INSPECTOR_DRY_RUN_MAX_BATCHES: ${{ inputs.dry_run_max_batches || '20' }}
+          PLUGIN_INSPECTOR_SOURCE_PR: ${{ inputs.source_pr || '' }}
+          PLUGIN_INSPECTOR_SOURCE_SHA: ${{ inputs.source_sha || '' }}
+          PLUGIN_INSPECTOR_ARTIFACT_DIR: plugin-inspector-bulk-scan-reports
+        run: bun scripts/package-inspector-nightly-scan.ts
+
+      - name: Upload inspector reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: plugin-inspector-bulk-scan-reports
+          path: plugin-inspector-bulk-scan-reports
+          if-no-files-found: warn
@@ -0,0 +1,55 @@
+name: Plugin Inspector Pin Bump Dispatch
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - package.json
+      - packages/clawhub/package.json
+      - bun.lock
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  dispatch-plugin-inspector-bulk-scan:
+    name: Dispatch Plugin Inspector bulk scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main commit
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+
+      - name: Fetch previous main commit
+        env:
+          BASE_SHA: ${{ github.event.before }}
+        run: git fetch --no-tags --depth=1 origin "$BASE_SHA"
+
+      - name: Detect pinned Plugin Inspector change
+        id: detect
+        env:
+          BASE_SHA: ${{ github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: node scripts/github/plugin-inspector-pin-change.mjs --base "$BASE_SHA" --head "$HEAD_SHA"
+
+      - name: Dispatch Plugin Inspector bulk scan
+        if: ${{ steps.detect.outputs.changed == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh workflow run plugin-inspector-bulk-scan.yml \
+            --ref main \
+            -f batch_size=25 \
+            -f dry_run=false \
+            -f dry_run_max_batches=20 \
+            -f source_sha=${{ github.sha }}
+
+      - name: Explain skipped dispatch
+        if: ${{ steps.detect.outputs.changed != 'true' }}
+        env:
+          DISPATCH_SKIP_REASON: ${{ steps.detect.outputs.reason }}
+        run: printf '%s\n' "$DISPATCH_SKIP_REASON"
@@ -0,0 +1,67 @@
+name: Publish Hosted Catalog Feed
+
+on:
+  schedule:
+    - cron: "17 */6 * * *"
+  workflow_dispatch:
+    inputs:
+      expires_in_days:
+        description: "How long the published feed remains fresh"
+        required: true
+        default: "7"
+        type: string
+
+concurrency:
+  group: publish-catalog-feed
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  validate-ref:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Require main ref for production publication
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_REF}" != "refs/heads/main" ]]; then
+            echo "Production catalog publications must run from main."
+            exit 1
+          fi
+
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: validate-ref
+    environment:
+      name: Production
+      url: https://registry.openclaw.ai/v1/feeds/plugins
+    env:
+      EXPIRES_IN_DAYS: ${{ inputs.expires_in_days || '7' }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: 1.3.10
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Publish current production catalog
+        env:
+          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
+        run: |
+          set -euo pipefail
+          if [[ -z "$CONVEX_DEPLOY_KEY" ]]; then
+            echo "::error::Missing Production environment secret CONVEX_DEPLOY_KEY"
+            exit 1
+          fi
+          if ! [[ "$EXPIRES_IN_DAYS" =~ ^[1-9][0-9]*$ ]]; then
+            echo "::error::expires_in_days must be a positive integer"
+            exit 1
+          fi
+          expires_at="$(node -e 'const days = Number(process.env.EXPIRES_IN_DAYS); console.log(new Date(Date.now() + days * 86400000).toISOString())')"
+          bunx convex run catalogFeed:publish "{\"expiresAt\":\"$expires_at\"}" --prod
@@ -0,0 +1,84 @@
+name: ClawHub Scheduled Live Checks
+
+on:
+  schedule:
+    - cron: "17 5 * * *"
+  workflow_dispatch:
+    inputs:
+      github-repo:
+        description: GitHub skills repo to use for the source-backed canary
+        required: false
+        default: openclaw/agent-skills
+      github-skill:
+        description: Skill slug to verify from the GitHub skills repo
+        required: false
+        default: handoff
+
+concurrency:
+  group: clawhub-scheduled-live-checks-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  VITE_CONVEX_URL: https://example.invalid
+
+jobs:
+  github-backed-skills:
+    name: GitHub-backed skills canary
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Run GitHub-backed skills live canary
+        env:
+          CLAWHUB_LIVE_GITHUB_CANARY: "1"
+          CLAWHUB_LIVE_GITHUB_REPO: ${{ inputs.github-repo || 'openclaw/agent-skills' }}
+          CLAWHUB_LIVE_GITHUB_SKILL: ${{ inputs.github-skill || 'handoff' }}
+          GITHUB_TOKEN: ${{ github.token }}
+        run: bunx vitest run convex/githubSkillSync.live.test.ts
+
+  open-failure-issue:
+    name: Open failure issue
+    needs: github-backed-skills
+    if: ${{ always() && needs.github-backed-skills.result == 'failure' }}
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Open or update failure issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          WORKFLOW_NAME: ${{ github.workflow }}
+        run: |
+          set -euo pipefail
+
+          marker_token="clawhub-scheduled-live-checks-failure"
+          marker="<!-- $marker_token -->"
+          title="ClawHub scheduled live checks failing"
+          issue_number="$(gh issue list \
+            --repo "$GITHUB_REPOSITORY" \
+            --state open \
+            --search "$marker_token in:body" \
+            --json number \
+            --jq '.[0].number // empty')"
+
+          body_file="$(mktemp)"
+          cat > "$body_file" <<EOF
+          $marker
+          The scheduled ClawHub live checks failed.
+
+          Workflow: $WORKFLOW_NAME
+          Run: $RUN_URL
+          EOF
+
+          if [[ -n "$issue_number" ]]; then
+            gh issue comment "$issue_number" --repo "$GITHUB_REPOSITORY" --body-file "$body_file"
+          else
+            gh issue create --repo "$GITHUB_REPOSITORY" --title "$title" --body-file "$body_file"
+          fi
@@ -6,6 +6,8 @@ on:
  pull_request:
    branches: [main, master]

+permissions: {}
+
 jobs:
  trufflehog:
    name: Scan for Verified Secrets
@@ -49,7 +51,7 @@ jobs:
        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.8
+        uses: trufflesecurity/trufflehog@v3.95.5
        with:
          path: ./
          base: ${{ steps.scan_range.outputs.base }}
@@ -0,0 +1,223 @@
+name: Security Dataset Snapshot
+
+on:
+  workflow_dispatch:
+    inputs:
+      upload:
+        description: "Upload sanitized dataset files to Hugging Face"
+        required: true
+        default: "false"
+        type: choice
+        options:
+          - "false"
+          - "true"
+      limit:
+        description: "Optional source artifact cap for validation runs"
+        required: false
+        default: ""
+      hf-revision:
+        description: "Hugging Face branch/revision to upload to"
+        required: true
+        default: "main"
+  schedule:
+    - cron: "17 9 * * *"
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: clawhub-security-dataset-snapshot
+  cancel-in-progress: false
+
+jobs:
+  publish-security-dataset:
+    name: Publish sanitized security dataset
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 360
+    environment: Production
+    env:
+      CONVEX_URL: ${{ vars.CONVEX_URL || vars.VITE_CONVEX_URL || 'https://wry-manatee-359.convex.cloud' }}
+      SECURITY_SCAN_WORKER_TOKEN: ${{ secrets.SECURITY_SCAN_WORKER_TOKEN }}
+      HF_DATASET_REPO: OpenClaw/clawhub-security-signals
+      HF_OIDC_RESOURCE: datasets/OpenClaw/clawhub-security-signals
+      HF_REVISION: ${{ inputs['hf-revision'] || 'main' }}
+      HF_UPLOAD: ${{ github.event_name == 'schedule' || inputs.upload == 'true' }}
+      SNAPSHOT_LIMIT: ${{ inputs.limit || '' }}
+      SANITIZED_OUT_DIR: /tmp/clawhub-security-dataset/sanitized
+      WORK_DIR: /tmp/clawhub-security-dataset
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - uses: actions/setup-python@v6
+        if: ${{ env.HF_UPLOAD == 'true' }}
+        with:
+          python-version: "3.12"
+
+      - name: Check configuration
+        run: |
+          set -euo pipefail
+          if [[ -z "$SECURITY_SCAN_WORKER_TOKEN" ]]; then
+            echo "::error::SECURITY_SCAN_WORKER_TOKEN is required"
+            exit 1
+          fi
+          echo "Upload enabled: $HF_UPLOAD"
+          echo "Convex URL: $CONVEX_URL"
+          echo "Hugging Face repo: $HF_DATASET_REPO"
+          echo "Hugging Face OIDC resource: $HF_OIDC_RESOURCE"
+          echo "Hugging Face revision: $HF_REVISION"
+
+      - name: Export sanitized live dataset
+        run: |
+          set -euo pipefail
+          mkdir -p "$SANITIZED_OUT_DIR"
+          source_snapshot_id="live-convex-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          args=(
+            --convex-url "$CONVEX_URL"
+            --worker-token "$SECURITY_SCAN_WORKER_TOKEN"
+            --source-snapshot-id "$source_snapshot_id"
+            --out-dir "$SANITIZED_OUT_DIR"
+            --hf-dataset
+            --hf-repo "$HF_DATASET_REPO"
+            --hf-revision "$HF_REVISION"
+            --page-size 25
+            --batch-pages 2
+            --concurrency 3
+          )
+          if [[ -n "$SNAPSHOT_LIMIT" ]]; then
+            args+=(--limit "$SNAPSHOT_LIMIT")
+          fi
+          bun scripts/security-dataset/export-snapshot.ts "${args[@]}" | tee "$SANITIZED_OUT_DIR/summary.json"
+          snapshot_dir="$(jq -r '.snapshotDir' "$SANITIZED_OUT_DIR/summary.json")"
+          if [[ -z "$snapshot_dir" || "$snapshot_dir" == "null" ]]; then
+            echo "::error::export summary did not include snapshotDir"
+            exit 1
+          fi
+          echo "SNAPSHOT_DIR=$snapshot_dir" >> "$GITHUB_ENV"
+          jq '.manifest.row_counts, .manifest.huggingface_dataset' "$SANITIZED_OUT_DIR/summary.json"
+
+      - name: Validate sanitized output guardrails
+        run: |
+          set -euo pipefail
+          test -d "$SNAPSHOT_DIR/hf-dataset/data"
+          test -f "$SNAPSHOT_DIR/manifest.json"
+          for split in train validation test eval_holdout; do
+            test -f "$SNAPSHOT_DIR/hf-dataset/data/$split.jsonl"
+          done
+          if grep -R -E 'storageId|skillVersions:|packageReleases:|_storage/' "$SNAPSHOT_DIR/hf-dataset" "$SNAPSHOT_DIR/manifest.json"; then
+            echo "::error::sanitized output contains raw storage or internal document identifiers"
+            exit 1
+          fi
+          if grep -R -E 'gh[pousr]_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z0-9 ]*(PRIVATE KEY|CERTIFICATE)-----' "$SNAPSHOT_DIR/hf-dataset"; then
+            echo "::error::sanitized output contains obvious secret-like values"
+            exit 1
+          fi
+
+      - name: Install Hugging Face uploader
+        if: ${{ env.HF_UPLOAD == 'true' }}
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          python -m pip install 'huggingface_hub[hf_xet]'
+
+      - name: Upload sanitized dataset to Hugging Face
+        if: ${{ env.HF_UPLOAD == 'true' }}
+        run: |
+          set -euo pipefail
+          python - <<'PY'
+          import json
+          import os
+          import urllib.request
+          from pathlib import Path
+          from huggingface_hub import HfApi
+
+          def get_github_oidc_token() -> str:
+              request_url = os.environ["ACTIONS_ID_TOKEN_REQUEST_URL"]
+              separator = "&" if "?" in request_url else "?"
+              request = urllib.request.Request(
+                  f"{request_url}{separator}audience=https://huggingface.co",
+                  headers={
+                      "Authorization": f"bearer {os.environ['ACTIONS_ID_TOKEN_REQUEST_TOKEN']}",
+                      "Accept": "application/json",
+                  },
+              )
+              with urllib.request.urlopen(request) as response:
+                  payload = json.loads(response.read().decode("utf-8"))
+              return payload["value"]
+
+          def exchange_hugging_face_token(oidc_token: str, resource: str) -> str:
+              body = json.dumps({
+                  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+                  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
+                  "subject_token": oidc_token,
+                  "resource": resource,
+              }).encode("utf-8")
+              request = urllib.request.Request(
+                  "https://huggingface.co/oauth/token",
+                  data=body,
+                  headers={
+                      "Content-Type": "application/json",
+                      "Accept": "application/json",
+                  },
+                  method="POST",
+              )
+              with urllib.request.urlopen(request) as response:
+                  payload = json.loads(response.read().decode("utf-8"))
+              return payload["access_token"]
+
+          snapshot_dir = Path(os.environ["SNAPSHOT_DIR"])
+          repo_id = os.environ["HF_DATASET_REPO"]
+          revision = os.environ["HF_REVISION"]
+          token = exchange_hugging_face_token(
+              get_github_oidc_token(),
+              os.environ["HF_OIDC_RESOURCE"],
+          )
+          api = HfApi(token=token)
+
+          data_commit = api.upload_folder(
+              folder_path=str(snapshot_dir / "hf-dataset" / "data"),
+              path_in_repo="data",
+              repo_id=repo_id,
+              repo_type="dataset",
+              revision=revision,
+              delete_patterns="data/*.jsonl",
+              commit_message="Update nightly ClawHub security dataset splits",
+          )
+
+          manifest_path = snapshot_dir / "manifest.json"
+          manifest = json.loads(manifest_path.read_text())
+          manifest["huggingface_dataset"]["commit"] = data_commit.oid
+          manifest["huggingface_dataset"]["revision"] = revision
+          manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
+
+          manifest_commit = api.upload_file(
+              path_or_fileobj=str(manifest_path),
+              path_in_repo="metadata/latest-manifest.json",
+              repo_id=repo_id,
+              repo_type="dataset",
+              revision=revision,
+              commit_message="Update nightly ClawHub security dataset manifest",
+          )
+          print(json.dumps({
+              "data_commit": data_commit.oid,
+              "manifest_commit": manifest_commit.oid,
+              "repo": repo_id,
+              "revision": revision,
+          }, indent=2))
+          PY
+
+      - name: Upload sanitized summary artifact
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: security-dataset-summary-${{ github.run_id }}
+          path: |
+            ${{ env.SANITIZED_OUT_DIR }}/summary.json
+            ${{ env.SNAPSHOT_DIR }}/manifest.json
+          if-no-files-found: ignore
+
+      - name: Cleanup transient dataset files
+        if: ${{ always() }}
+        run: rm -rf "$WORK_DIR"
@@ -0,0 +1,110 @@
+name: Security Scan Codex Worker
+
+on:
+  workflow_dispatch:
+    inputs:
+      limit:
+        description: "Deprecated alias for batch-limit"
+        required: false
+        default: ""
+      batch-limit:
+        description: "Maximum Codex scans to run in parallel per worker shard"
+        required: true
+        default: "4"
+      max-jobs:
+        description: "Optional total jobs cap per worker shard"
+        required: false
+        default: ""
+      max-runtime-minutes:
+        description: "Stop claiming new batches after this many minutes"
+        required: true
+        default: "40"
+  schedule:
+    - cron: "*/5 * * * *"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: clawhub-security-scan
+  cancel-in-progress: false
+
+jobs:
+  codex-security-scan:
+    name: Codex security scan shard ${{ matrix.shard }}
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 60
+    environment: Production
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [0, 1, 2, 3]
+    env:
+      CONVEX_URL: ${{ vars.CONVEX_URL || vars.VITE_CONVEX_URL || 'https://wry-manatee-359.convex.cloud' }}
+      SECURITY_SCAN_WORKER_TOKEN: ${{ secrets.SECURITY_SCAN_WORKER_TOKEN }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      CODEX_SECURITY_SCAN_LIMIT: ${{ inputs.limit || inputs['batch-limit'] || '4' }}
+      CODEX_SECURITY_SCAN_MAX_JOBS: ${{ inputs['max-jobs'] || '' }}
+      CODEX_SECURITY_SCAN_MAX_RUNTIME_MINUTES: ${{ inputs['max-runtime-minutes'] || '40' }}
+      CODEX_SECURITY_SCAN_LEASE_MINUTES: "60"
+      CODEX_SECURITY_SCAN_DIAGNOSTICS_DIR: codex-security-scan-diagnostics-${{ matrix.shard }}
+      CODEX_SECURITY_SCAN_SHARD: ${{ matrix.shard }}
+      CODEX_SECURITY_SCAN_WORKER_ID: "github-actions:${{ github.run_id }}:${{ github.run_attempt }}:${{ matrix.shard }}"
+      SKILLSPECTOR_PROVIDER: openai
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Check configuration
+        run: |
+          set -euo pipefail
+          if [[ -z "$SECURITY_SCAN_WORKER_TOKEN" ]]; then
+            echo "::error::SECURITY_SCAN_WORKER_TOKEN is required"
+            exit 1
+          fi
+          if [[ -z "$OPENAI_API_KEY" ]]; then
+            echo "::error::OPENAI_API_KEY is required"
+            exit 1
+          fi
+
+      - name: Install Codex CLI
+        run: |
+          set -euo pipefail
+          if ! command -v codex >/dev/null 2>&1; then
+            npm install -g @openai/codex@latest
+          fi
+          codex --version
+
+      - name: Install SkillSpector
+        run: |
+          set -euo pipefail
+          python -m venv "$RUNNER_TEMP/skillspector-venv"
+          source "$RUNNER_TEMP/skillspector-venv/bin/activate"
+          python -m pip install --upgrade pip
+          python -m pip install 'git+https://github.com/NVIDIA/skillspector.git'
+          echo "$RUNNER_TEMP/skillspector-venv/bin" >> "$GITHUB_PATH"
+          skillspector --help >/dev/null
+
+      - name: Authenticate Codex CLI
+        run: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
+
+      - name: Run Codex security worker
+        run: |
+          bun scripts/security/run-codex-scan-worker.ts \
+            --batch-limit "$CODEX_SECURITY_SCAN_LIMIT" \
+            --max-jobs "$CODEX_SECURITY_SCAN_MAX_JOBS" \
+            --max-runtime-minutes "$CODEX_SECURITY_SCAN_MAX_RUNTIME_MINUTES" \
+            --lease-minutes "$CODEX_SECURITY_SCAN_LEASE_MINUTES"
+
+      - name: Upload Codex security diagnostics
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: codex-security-scan-diagnostics-${{ github.run_id }}-${{ matrix.shard }}
+          path: ${{ env.CODEX_SECURITY_SCAN_DIAGNOSTICS_DIR }}
+          if-no-files-found: ignore
@@ -0,0 +1,98 @@
+name: Skill Card Worker
+
+on:
+  workflow_run:
+    workflows: ["Security Scan Codex Worker"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      batch-limit:
+        description: "Maximum Skill Card jobs to run in parallel per worker shard"
+        required: true
+        default: "4"
+      max-jobs:
+        description: "Optional total jobs cap per worker shard"
+        required: false
+        default: ""
+      max-runtime-minutes:
+        description: "Stop claiming new batches after this many minutes"
+        required: true
+        default: "40"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: clawhub-skill-card-worker
+  cancel-in-progress: false
+
+jobs:
+  skill-card-worker:
+    name: Skill Card worker shard ${{ matrix.shard }}
+    runs-on: blacksmith-8vcpu-ubuntu-2404
+    timeout-minutes: 60
+    environment: Production
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [0, 1, 2, 3]
+    env:
+      CONVEX_URL: ${{ vars.CONVEX_URL || vars.VITE_CONVEX_URL || 'https://wry-manatee-359.convex.cloud' }}
+      # Shared Convex worker credential used by security and Skill Card workers.
+      SECURITY_SCAN_WORKER_TOKEN: ${{ secrets.SECURITY_SCAN_WORKER_TOKEN }}
+      SKILL_CARD_WORKER_LIMIT: ${{ github.event.inputs['batch-limit'] || '4' }}
+      SKILL_CARD_WORKER_MAX_JOBS: ${{ github.event.inputs['max-jobs'] || '' }}
+      SKILL_CARD_WORKER_MAX_RUNTIME_MINUTES: ${{ github.event.inputs['max-runtime-minutes'] || '40' }}
+      SKILL_CARD_WORKER_LEASE_MINUTES: "60"
+      SKILL_CARD_WORKER_SHARD: ${{ matrix.shard }}
+      SKILL_CARD_WORKER_ID: "github-actions:${{ github.run_id }}:${{ github.run_attempt }}:${{ matrix.shard }}"
+      NVIDIA_TRUSTWORTHY_AI_DIR: ${{ github.workspace }}/.artifacts/nvidia-trustworthy-ai
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/checkout@v6
+        with:
+          repository: NVIDIA/Trustworthy-AI
+          ref: fb5867e9070b4080d28818242e20334e10ac55fc
+          path: .artifacts/nvidia-trustworthy-ai
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Check configuration
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          set -euo pipefail
+          if [[ -z "$SECURITY_SCAN_WORKER_TOKEN" ]]; then
+            echo "::error::SECURITY_SCAN_WORKER_TOKEN is required"
+            exit 1
+          fi
+          if [[ -z "$OPENAI_API_KEY" ]]; then
+            echo "::error::OPENAI_API_KEY is required"
+            exit 1
+          fi
+
+      - name: Install Codex CLI and renderer dependencies
+        run: |
+          set -euo pipefail
+          if ! command -v codex >/dev/null 2>&1; then
+            npm install -g @openai/codex@latest
+          fi
+          python3 -m pip install --user jinja2
+          codex --version
+
+      - name: Authenticate Codex CLI
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: printf '%s' "$OPENAI_API_KEY" | codex login --with-api-key
+
+      - name: Run Skill Card worker
+        run: |
+          args=(
+            --batch-limit "$SKILL_CARD_WORKER_LIMIT"
+            --max-jobs "$SKILL_CARD_WORKER_MAX_JOBS"
+            --max-runtime-minutes "$SKILL_CARD_WORKER_MAX_RUNTIME_MINUTES"
+            --lease-minutes "$SKILL_CARD_WORKER_LEASE_MINUTES"
+            --nvidia-tool-dir "$NVIDIA_TRUSTWORTHY_AI_DIR"
+          )
+          bun scripts/skill-cards/run-skill-card-worker.ts "${args[@]}"
@@ -0,0 +1,312 @@
+name: Skill Publish
+
+on:
+  workflow_call:
+    inputs:
+      skill_path:
+        description: Optional path to one skill folder. When set, only this skill is processed.
+        required: false
+        type: string
+        default: ""
+      root:
+        description: Directory containing skill folders for catalog publishing.
+        required: false
+        type: string
+        default: skills
+      dry_run:
+        description: Preview only. When true, no publish mutation is performed.
+        required: false
+        type: boolean
+        default: true
+      owner:
+        description: Optional owner/publisher handle for org publishing.
+        required: false
+        type: string
+        default: ""
+      tags:
+        description: Optional comma-separated tags override.
+        required: false
+        type: string
+        default: latest
+      registry:
+        description: ClawHub registry URL.
+        required: false
+        type: string
+        default: https://clawhub.ai
+      site:
+        description: ClawHub site URL.
+        required: false
+        type: string
+        default: https://clawhub.ai
+      ref:
+        description: Optional caller repository ref to check out.
+        required: false
+        type: string
+        default: ""
+    secrets:
+      clawhub_token:
+        required: false
+    outputs:
+      publish_json:
+        description: Structured JSON output from skill publishing.
+        value: ${{ jobs.publish.outputs.publish_json }}
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      id-token: write
+    outputs:
+      publish_json: ${{ steps.capture.outputs.publish_json }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref || github.sha }}
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: 1.3.10
+
+      - name: Resolve ClawHub workflow source
+        id: clawhub_source
+        run: |
+          python3 - <<'PY'
+          import base64
+          import json
+          import os
+          from pathlib import Path
+          from urllib.request import Request, urlopen
+
+          request_token = os.environ.get("ACTIONS_ID_TOKEN_REQUEST_TOKEN", "").strip()
+          request_url = os.environ.get("ACTIONS_ID_TOKEN_REQUEST_URL", "").strip()
+          if not request_token or not request_url:
+              raise SystemExit("GitHub OIDC token request env vars are missing; id-token: write is required.")
+
+          audience = "clawhub-workflow-source"
+          joiner = "&" if "?" in request_url else "?"
+          request = Request(
+              f"{request_url}{joiner}audience={audience}",
+              headers={"Authorization": f"Bearer {request_token}"},
+          )
+          with urlopen(request) as response:
+              payload = json.load(response)
+
+          token = str(payload.get("value", "")).strip()
+          if not token:
+              raise SystemExit("GitHub OIDC token response did not include a token value.")
+
+          try:
+              encoded_payload = token.split(".")[1]
+          except IndexError as exc:
+              raise SystemExit("GitHub OIDC token was not a valid JWT.") from exc
+          padding = "=" * (-len(encoded_payload) % 4)
+          claims = json.loads(base64.urlsafe_b64decode(encoded_payload + padding).decode("utf-8"))
+
+          workflow_ref = str(claims.get("job_workflow_ref", "")).strip()
+          workflow_sha = str(claims.get("job_workflow_sha", "")).strip()
+          repo, marker, _ = workflow_ref.partition("/.github/workflows/")
+          if not marker or not repo or not workflow_sha:
+              raise SystemExit(
+                  "Unable to resolve reusable workflow source from GitHub OIDC claims: "
+                  f"job_workflow_ref={workflow_ref!r} job_workflow_sha={workflow_sha!r}"
+              )
+
+          with Path(os.environ["GITHUB_OUTPUT"]).open("a", encoding="utf-8") as fh:
+              fh.write(f"repository={repo}\n")
+              fh.write(f"ref={workflow_sha}\n")
+          PY
+
+      - uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.clawhub_source.outputs.repository }}
+          ref: ${{ steps.clawhub_source.outputs.ref }}
+          path: clawhub-source
+
+      - name: Install ClawHub CLI dependencies
+        working-directory: clawhub-source
+        run: bun install --frozen-lockfile
+
+      - name: Validate publish mode inputs
+        env:
+          DRY_RUN: ${{ inputs.dry_run }}
+          CLAWHUB_TOKEN: ${{ secrets.clawhub_token }}
+        run: |
+          if [[ "$DRY_RUN" == "true" || -n "$CLAWHUB_TOKEN" ]]; then
+            exit 0
+          fi
+          echo "::error::Real skill publishes need secrets.clawhub_token. GitHub OIDC trusted publishing for skills is not supported yet."
+          exit 1
+
+      - name: Write ClawHub config
+        env:
+          CLAWHUB_TOKEN: ${{ secrets.clawhub_token }}
+          CLAWHUB_REGISTRY: ${{ inputs.registry }}
+        run: |
+          if [[ -z "$CLAWHUB_TOKEN" ]]; then
+            echo "No ClawHub token provided, skipping config file creation."
+            exit 0
+          fi
+
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          path = Path(os.environ["RUNNER_TEMP"]) / "clawhub-config.json"
+          path.write_text(
+              json.dumps({"registry": os.environ["CLAWHUB_REGISTRY"], "token": os.environ["CLAWHUB_TOKEN"]}, indent=2) + "\n",
+              encoding="utf-8",
+          )
+          print(path)
+          PY
+          echo "CLAWHUB_CONFIG_PATH=$RUNNER_TEMP/clawhub-config.json" >> "$GITHUB_ENV"
+
+      - name: Run skill publishes
+        env:
+          INPUT_SKILL_PATH: ${{ inputs.skill_path }}
+          INPUT_ROOT: ${{ inputs.root }}
+          INPUT_DRY_RUN: ${{ inputs.dry_run }}
+          INPUT_OWNER: ${{ inputs.owner }}
+          INPUT_TAGS: ${{ inputs.tags }}
+          INPUT_SITE: ${{ inputs.site }}
+          INPUT_REGISTRY: ${{ inputs.registry }}
+          INPUT_REF: ${{ inputs.ref }}
+          SOURCE_REPOSITORY: ${{ github.repository }}
+          SOURCE_REF: ${{ github.ref }}
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+          import subprocess
+          import sys
+          from pathlib import Path
+
+          workspace = Path(os.environ["GITHUB_WORKSPACE"]).resolve()
+          cli_entry = workspace / "clawhub-source" / "packages" / "clawhub" / "src" / "cli.ts"
+          if not cli_entry.is_file():
+              raise SystemExit(f"Missing ClawHub CLI entrypoint at {cli_entry}")
+
+          def resolve_inside_workspace(raw_path):
+              path = (workspace / raw_path).resolve()
+              try:
+                  path.relative_to(workspace)
+              except ValueError as exc:
+                  raise SystemExit(f"Publish path must be inside the caller repository: {raw_path}") from exc
+              return path
+
+          def is_skill_folder(path):
+              return path.is_dir() and any((path / name).is_file() for name in ("SKILL.md", "skill.md"))
+
+          skill_path = os.environ["INPUT_SKILL_PATH"].strip()
+          root_input = os.environ["INPUT_ROOT"].strip() or "skills"
+          if skill_path:
+              targets = [resolve_inside_workspace(skill_path)]
+              if not is_skill_folder(targets[0]):
+                  raise SystemExit(f"skill_path is not a skill folder: {skill_path}")
+          else:
+              root = resolve_inside_workspace(root_input)
+              if is_skill_folder(root):
+                  targets = [root]
+              elif root.is_dir():
+                  targets = sorted(
+                      (child for child in root.iterdir() if is_skill_folder(child)),
+                      key=lambda child: child.name.lower(),
+                  )
+              else:
+                  targets = []
+              if not targets:
+                  raise SystemExit(f"No skill folders found under: {root_input}")
+
+          source_commit = subprocess.check_output(
+              ["git", "rev-parse", "HEAD"], cwd=workspace, text=True
+          ).strip()
+          source_ref = os.environ["INPUT_REF"].strip() or os.environ["SOURCE_REF"].strip()
+          dry_run = os.environ["INPUT_DRY_RUN"] == "true"
+          owner = os.environ["INPUT_OWNER"].strip()
+          tags = os.environ["INPUT_TAGS"].strip()
+
+          results = {"wouldPublish": [], "published": [], "alreadySynced": [], "skipped": [], "failed": []}
+          status_keys = {
+              "would-publish": "wouldPublish",
+              "published": "published",
+              "unchanged": "alreadySynced",
+          }
+
+          for target in targets:
+              relative_path = target.relative_to(workspace).as_posix()
+              command = [
+                  "bun", str(cli_entry),
+                  "--workdir", str(workspace),
+                  "--site", os.environ["INPUT_SITE"],
+                  "--registry", os.environ["INPUT_REGISTRY"],
+                  "skill", "publish", relative_path,
+                  "--json",
+                  "--source-repo", os.environ["SOURCE_REPOSITORY"],
+                  "--source-commit", source_commit,
+                  "--source-path", relative_path,
+              ]
+              if dry_run:
+                  command.append("--dry-run")
+              if owner:
+                  command += ["--owner", owner]
+              if tags:
+                  command += ["--tags", tags]
+              if source_ref:
+                  command += ["--source-ref", source_ref]
+
+              completed = subprocess.run(command, cwd=workspace, capture_output=True, text=True)
+              if completed.returncode != 0:
+                  message = completed.stderr.strip() or completed.stdout.strip() or f"exit {completed.returncode}"
+                  results["failed"].append({"slug": target.name, "folder": relative_path, "message": message})
+                  continue
+              try:
+                  result = json.loads(completed.stdout)
+                  results[status_keys[result["status"]]].append(result)
+              except (KeyError, ValueError, json.JSONDecodeError) as exc:
+                  results["failed"].append({"slug": target.name, "folder": relative_path, "message": f"Invalid publish output: {exc}"})
+
+          output = {
+              "ok": not results["failed"],
+              "dryRun": dry_run,
+              "registry": os.environ["INPUT_REGISTRY"],
+              "roots": [skill_path or root_input],
+              **({"owner": owner.lstrip("@") } if owner else {}),
+              "summary": {key: len(value) for key, value in results.items()},
+              **results,
+          }
+          output_path = Path(os.environ["RUNNER_TEMP"]) / "skill-publish.json"
+          output_path.write_text(json.dumps(output, indent=2) + "\n", encoding="utf-8")
+          print(json.dumps(output, indent=2))
+          if results["failed"]:
+              sys.exit(1)
+          PY
+
+      - name: Capture workflow outputs
+        id: capture
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          output_path = Path(os.environ["RUNNER_TEMP"]) / "skill-publish.json"
+          parsed = json.loads(output_path.read_text(encoding="utf-8"))
+          with Path(os.environ["GITHUB_OUTPUT"]).open("a", encoding="utf-8") as fh:
+              fh.write("publish_json<<__CLAWHUB_JSON__\n")
+              fh.write(json.dumps(parsed, indent=2))
+              fh.write("\n__CLAWHUB_JSON__\n")
+          PY
+
+      - name: Upload publish JSON artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: clawhub-skill-publish-json
+          path: ${{ runner.temp }}/skill-publish.json
+          if-no-files-found: error
@@ -0,0 +1,171 @@
+name: Stale
+
+on:
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+permissions: {}
+
+jobs:
+  stale:
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Mark stale unassigned issues and pull requests
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ github.token }}
+          days-before-issue-stale: 14
+          days-before-issue-close: 7
+          days-before-pr-stale: 7
+          days-before-pr-close: 5
+          stale-issue-label: stale
+          stale-pr-label: stale
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          exempt-pr-labels: maintainer,no-stale,bad-barnacle
+          operations-per-run: 1000
+          ascending: true
+          exempt-all-assignees: true
+          remove-stale-when-updated: true
+          stale-issue-message: |
+            This issue has been automatically marked as stale due to inactivity.
+            Please add updated ClawHub details or it will be closed.
+          stale-pr-message: |
+            This pull request has been automatically marked as stale due to inactivity.
+            Please update it or it will be closed.
+          close-issue-message: |
+            Closing due to inactivity.
+            If this still affects ClawHub, reopen or file a new issue with the current URL, skill/package name, and fresh reproduction details.
+          close-issue-reason: not_planned
+          close-pr-message: |
+            Closing due to inactivity.
+            If this PR should be revived, reopen it with current context and a fresh validation plan.
+
+      - name: Mark stale assigned issues
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ github.token }}
+          days-before-issue-stale: 30
+          days-before-issue-close: 10
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          stale-issue-label: stale
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          operations-per-run: 1000
+          ascending: true
+          include-only-assigned: true
+          remove-stale-when-updated: true
+          stale-issue-message: |
+            This assigned issue has been automatically marked as stale after 30 days of inactivity.
+            Please add an update or it will be closed.
+          close-issue-message: |
+            Closing due to inactivity.
+            If this still affects ClawHub, reopen or file a new issue with current evidence.
+          close-issue-reason: not_planned
+
+      - name: Mark stale assigned pull requests
+        uses: actions/stale@v10
+        with:
+          repo-token: ${{ github.token }}
+          days-before-issue-stale: -1
+          days-before-issue-close: -1
+          days-before-pr-stale: 27
+          days-before-pr-close: 5
+          stale-pr-label: stale
+          exempt-pr-labels: maintainer,no-stale,bad-barnacle
+          operations-per-run: 1000
+          ascending: true
+          include-only-assigned: true
+          ignore-pr-updates: true
+          remove-stale-when-updated: true
+          stale-pr-message: |
+            This assigned pull request has been automatically marked as stale after being open for 27 days.
+            Please add an update or it will be closed.
+          close-pr-message: |
+            Closing due to inactivity.
+            If this PR should be revived, reopen it with current context and a fresh validation plan.
+
+  lock-closed-issues:
+    permissions:
+      issues: write
+    runs-on: ubuntu-latest
+    steps:
+      - name: Lock closed issues after 48h of no comments
+        uses: actions/github-script@v9
+        with:
+          github-token: ${{ github.token }}
+          script: |
+            const lockAfterHours = 48;
+            const lockAfterMs = lockAfterHours * 60 * 60 * 1000;
+            const cutoffMs = Date.now() - lockAfterMs;
+            const { owner, repo } = context.repo;
+
+            let locked = 0;
+            let inspected = 0;
+            let page = 1;
+
+            while (true) {
+              const { data: issues } = await github.rest.issues.listForRepo({
+                owner,
+                repo,
+                state: "closed",
+                sort: "updated",
+                direction: "desc",
+                per_page: 100,
+                page,
+              });
+
+              if (issues.length === 0) {
+                break;
+              }
+
+              for (const issue of issues) {
+                if (issue.pull_request || issue.locked || !issue.closed_at) {
+                  continue;
+                }
+
+                inspected += 1;
+                const closedAtMs = Date.parse(issue.closed_at);
+                if (!Number.isFinite(closedAtMs) || closedAtMs > cutoffMs) {
+                  continue;
+                }
+
+                let lastCommentMs = 0;
+                if (issue.comments > 0) {
+                  const { data: comments } = await github.rest.issues.listComments({
+                    owner,
+                    repo,
+                    issue_number: issue.number,
+                    per_page: 1,
+                    page: 1,
+                    sort: "created",
+                    direction: "desc",
+                  });
+                  if (comments.length > 0) {
+                    lastCommentMs = Date.parse(comments[0].created_at);
+                  }
+                }
+
+                if (Math.max(closedAtMs, lastCommentMs || 0) > cutoffMs) {
+                  continue;
+                }
+
+                await github.rest.issues.lock({
+                  owner,
+                  repo,
+                  issue_number: issue.number,
+                  lock_reason: "resolved",
+                });
+                locked += 1;
+              }
+
+              page += 1;
+            }
+
+            core.info(`Inspected ${inspected} closed issues; locked ${locked}.`);
@@ -0,0 +1,121 @@
+name: Update Convex AI Files
+
+on:
+  schedule:
+    # Midnight Pacific during daylight saving time. GitHub cron uses UTC.
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: update-convex-ai-files
+  cancel-in-progress: false
+
+permissions: {}
+
+env:
+  BUN_VERSION: "1.3.10"
+  UPDATE_BRANCH: automation/update-convex-ai-files
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token
+        continue-on-error: true
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+
+      - uses: actions/create-github-app-token@v3
+        id: app-token-fallback
+        continue-on-error: true
+        if: steps.app-token.outcome == 'failure'
+        with:
+          app-id: "2971289"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Update Convex AI files
+        run: |
+          "$(bun pm bin)/convex" ai-files update
+
+      - name: Check Convex AI files status
+        run: |
+          "$(bun pm bin)/convex" ai-files status
+
+      - name: Detect changes
+        id: changes
+        run: |
+          set -euo pipefail
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push update branch
+        if: steps.changes.outputs.changed == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git checkout -B "$UPDATE_BRANCH"
+          git add AGENTS.md CLAUDE.md .agents/skills convex/_generated/ai/guidelines.md convex/_generated/ai/ai-files.state.json
+          git commit -m "chore: update Convex AI files"
+          git push --force-with-lease origin "$UPDATE_BRANCH"
+
+      - name: Open or update pull request
+        if: steps.changes.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token || github.token }}
+        run: |
+          set -euo pipefail
+
+          body_file="$(mktemp)"
+          {
+            printf '%s\n' '## Summary'
+            printf '\n'
+            printf '%s\n' '- refresh Convex-managed AI guidance files'
+            printf '%s\n' '- keep AGENTS.md / CLAUDE.md Convex sections in sync when Convex updates them'
+            printf '%s\n' '- update repo-local Convex developer skills under .agents/skills'
+            printf '\n'
+            printf '%s\n' '## Validation'
+            printf '\n'
+            # shellcheck disable=SC2016
+            printf '%s\n' '- `$(bun pm bin)/convex ai-files status`'
+          } > "$body_file"
+
+          if gh pr view "$UPDATE_BRANCH" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            gh pr edit "$UPDATE_BRANCH" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "[automation] Update Convex AI files" \
+              --body-file "$body_file"
+          else
+            gh pr create \
+              --repo "$GITHUB_REPOSITORY" \
+              --base main \
+              --head "$UPDATE_BRANCH" \
+              --title "[automation] Update Convex AI files" \
+              --body-file "$body_file"
+          fi
@@ -2,6 +2,11 @@ node_modules
 .DS_Store
 .bun-build
 *.bun-build
+.artifacts/
+artifacts/
+.proof/
+.cache/
+.data/
 bin/docs-list
 dist
 dist-ssr
@@ -10,7 +15,9 @@ dist-ssr
 *.local
 .vercel
 count.txt
-.env
+.env*
+!.env.local.example
+!.env.example
 .nitro
 .tanstack
 .wrangler
@@ -21,10 +28,22 @@ todos.json
 .vscode
 .env*.local
 coverage
+eval/cache/
+eval/results/
 playwright-report
 test-results
 .playwright
-convex/_generated/
+/public/llms.txt
+convex/_generated/*
+!convex/_generated/ai/
+convex/_generated/ai/*
+!convex/_generated/ai/guidelines.md
+!convex/_generated/ai/ai-files.state.json
 skills-lock.json
-*/skills/*
-skills/*
+skills/*
+.codex/*
+!.codex/environments/
+!.codex/environments/environment.toml
+.crabbox/
+/.comux-hooks
+/.comux
@@ -11,6 +11,7 @@
    "eslint-plugin-unicorn/prefer-array-find": "off",
    "eslint-plugin-unicorn/no-array-sort": "off",
    "eslint/no-await-in-loop": "off",
+    "eslint/no-underscore-dangle": "off",
    "eslint/no-new": "off",
    "oxc/no-accumulating-spread": "off",
    "oxc/no-async-endpoint-handlers": "off",
@@ -0,0 +1,21 @@
+# ClawHub publisher search proof
+
+Status: pass (production bug reproduction before backend deploy)
+
+## Convex read-only validation (`wry-manatee-359.convex.cloud`)
+
+| Query | `listPublicPage` handles |
+| --- | --- |
+| `vyctor` | `[]` |
+| `vyctorbrzezowski` | `[]` |
+| `vincent` | `["vincentchan"]` |
+| `vincentkoc` | `[]` |
+
+## Profiles that exist but are missing from search
+
+- `vyctorbrzezowski` → 5 skills, 1 package, 46 installs
+- `vincentkoc` → public profile, 0 published skills
+
+## Unit tests
+
+`VITE_CONVEX_URL=https://example.invalid bunx vitest run convex/publishers.test.ts`
--- a/Show More
+++ b/Show More