fix: expand reserved public owner handles to cover all top-level routes

Previously only 'plugins' and 'skills' were protected. Any user could register @admin, @settings, @dashboard, @search, etc. as a publisher handle, shadowing those platform routes via the $owner catch-all. Add all current top-level src/routes/ segments to RESERVED_PUBLIC_OWNER_HANDLES, grouped by purpose: - Content browsing: skills, souls, plugins, packages, publishers, orgs - Profile shortlinks: p, u - User flows: search, import, upload, publish-skill, publish-plugin, stars, dashboard, settings - Admin/internal: admin, management, audits - Informational: docs, cli - Auth/account: user, users Also add a doc comment noting to update this set when new top-level routes are added.
test: add personal-publisher nvidia membership regression tests
2026-08-14 08:52:21 +00:00 · 2026-06-03 05:12:18 -07:00 · 2026-06-03 11:50:34 +00:00 · 2026-06-03 06:44:57 -05:00 · 2026-06-03 05:34:33 -05:00 · 2026-05-30 00:37:40 -05:00
975 changed files with 263064 additions and 31110 deletions
@@ -0,0 +1,196 @@
+---
+name: autoreview
+description: "Use when ClawHub needs Codex review, autoreview, second-model review, or a final advisory review gate before commit, PR update, ship, or maintainer handoff."
+---
+
+# Autoreview
+
+Run Codex's built-in code review as a closeout check. This is code review
+(`codex review`), not Guardian `auto_review` approval routing.
+
+Codex native review mode performs best and is recommended. Non-Codex reviewers
+are fallback or second-opinion paths that receive a generated diff prompt, not
+the full Codex review-mode runtime.
+
+Use when:
+
+- the user asks for Codex review, autoreview, or second-model review
+- after non-trivial code edits, before final/commit/ship
+- reviewing a local branch or PR branch after fixes
+- closing out ClawHub maintainer work that touched source, tests, Convex, UI,
+  CLI packages, or workflows
+
+## 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.
+- Keep going until the selected review path returns no accepted/actionable
+  findings.
+- If a review-triggered fix changes code, rerun focused tests and rerun the
+  review helper.
+- Default to Codex review. If Codex is unavailable or exits with an error, the
+  helper can fall back to `claude -p`, `pi -p`, `opencode run`, `droid exec`, or
+  `copilot`.
+- Stop as soon as the review command/helper exits 0 with no
+  accepted/actionable findings. Do not run an extra direct `codex review` just
+  to get a nicer clean line, a second opinion, or clearer closeout wording.
+- 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
+  future reviewers should know.
+- Do not push just to review. Push only when the user requested push/ship/PR
+  update.
+
+## ClawHub Proof Routing
+
+Pick the smallest proof that matches the touched surface:
+
+| Touched surface                    | Usual proof                                                                                                             |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Formatting/lint/static repo health | `bun run ci:static`                                                                                                     |
+| Unit-tested source behavior        | focused `bunx vitest run ...`, then `bun run ci:unit` when PR-ready                                                     |
+| Convex code                        | read `convex/_generated/ai/guidelines.md` first; run focused tests and the deploy/typecheck path that covers the change |
+| Packages/CLI/mod tool              | `bun run ci:packages` or the package-specific `verify` script                                                           |
+| Runtime/build/package surface      | `bun run ci:types-build`, `bun run ci:e2e-http`, or the matching broader gate                                           |
+| UI behavior                        | use `clawhub-ui-proof` with `proof:ui`; publish proof before final PR comments when needed                              |
+| Linux/CI-parity validation         | use `crabbox`, normally through the repo scripts                                                                        |
+
+For Convex query or schema work, apply the repo's Convex rules: prefer indexes
+over `.filter()` scans, use cursor-based backfills for data shape changes, and
+verify with the repo's Convex/typecheck path before claiming deploy safety.
+
+## Pick Target
+
+Dirty local work:
+
+```bash
+codex review --uncommitted
+```
+
+Use this only when the patch is actually unstaged/staged/untracked in the
+current checkout. For committed, pushed, or PR work, point Codex at the commit
+or branch diff instead. A clean `--uncommitted` review only proves there is no
+local patch.
+
+Branch/PR work:
+
+```bash
+git fetch origin
+codex review --base origin/main
+```
+
+If an open PR exists, use its actual base:
+
+```bash
+base=$(gh pr view --json baseRefName --jq .baseRefName)
+codex review --base "origin/$base"
+```
+
+Do not pass a prompt with `--base`. Some Codex CLI versions reject
+`codex review --base <ref> -` with `--base <BRANCH> cannot be used with
+[PROMPT]`. If that happens, rerun plain `codex review --base <ref>` and report
+that prompt injection was skipped.
+
+Committed single change:
+
+```bash
+codex review --commit HEAD
+```
+
+or with the helper:
+
+```bash
+.agents/skills/autoreview/scripts/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
+.agents/skills/autoreview/scripts/autoreview --parallel-tests "bun run ci:static"
+```
+
+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.
+
+## Context Efficiency
+
+Codex review is usually noisy. Default to a subagent filter when subagents are
+available. Ask it to run the review and return only:
+
+- actionable findings it accepts
+- findings it rejects, with one-line reason
+- exact files/tests to rerun
+
+Run inline only for tiny changes or when subagents are unavailable.
+
+## Helper
+
+Bundled helper:
+
+```bash
+.agents/skills/autoreview/scripts/autoreview --help
+```
+
+The helper:
+
+- chooses dirty `--uncommitted` first
+- otherwise uses current PR base if `gh pr view` works
+- otherwise uses `origin/main` for non-main branches
+- auto-runs `bun run ci:static` in parallel when the repo has `package.json`,
+  `bun.lock`, `node_modules`, and a `ci:static` script; disable with
+  `AUTOREVIEW_AUTO_TESTS=0`
+- 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
+- supports `--reviewer codex|claude|pi|opencode|droid|copilot|auto`; `auto`
+  means Codex first
+- supports `--fallback-reviewer auto|claude|pi|opencode|droid|copilot|none`
+- falls back only when Codex is unavailable or exits nonzero without findings,
+  not when Codex reports findings
+- writes only to stdout unless `--output` or `AUTOREVIEW_OUTPUT` is set
+- supports `--dry-run`, `--parallel-tests`, and commit refs
+- runs nested review with `--dangerously-bypass-approvals-and-sandbox --sandbox
+danger-full-access` by default; use `--no-yolo` or `AUTOREVIEW_YOLO=0` to opt
+  out
+- prints `autoreview clean: no accepted/actionable findings reported` when the
+  selected review command exits 0 and no accepted/actionable findings are
+  reported
+
+## 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 Codex review solely to improve final wording. If the final
+helper run exited 0 and produced no accepted/actionable findings, report that
+exact run as clean.
+
+## PR / CI Closeout
+
+- Prefer direct run/job APIs after CI starts: `gh run view <run-id> --json jobs`;
+  use PR rollup only for final mergeability.
+- After rebase, compare `origin/main..HEAD`; drop CI-fix commits already
+  upstream before pushing.
+- Update the PR body once near the final head unless proof labels are missing
+  or stale enough to block CI.
@@ -0,0 +1,543 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: autoreview [options]
+
+Options:
+  --mode auto|local|branch|commit
+      Target selection. Default: auto.
+  --base REF
+      Base ref for branch review. Default: PR base or origin/main.
+  --commit REF
+      Commit ref for commit review. Default: HEAD.
+  --reviewer codex|claude|pi|opencode|droid|copilot|auto
+      Review engine. Default: Codex with configured fallback on error.
+  --fallback-reviewer auto|claude|pi|opencode|droid|copilot|none
+      Fallback when Codex is unavailable or exits nonzero without findings.
+  --codex-bin PATH
+      Codex binary. Default: codex.
+  --claude-bin PATH
+      Claude binary. Default: claude.
+  --pi-bin PATH
+      Pi binary. Default: pi.
+  --opencode-bin PATH
+      OpenCode binary. Default: opencode.
+  --droid-bin PATH
+      Droid binary. Default: droid.
+  --copilot-bin PATH
+      GitHub Copilot binary. Default: copilot.
+  --full-access
+      Keep yolo/full-access mode enabled. Default.
+  --no-yolo
+      Run nested Codex review with normal sandbox/approval prompts.
+  --output FILE
+      Also save output to file.
+  --parallel-tests CMD
+      Run review and test command concurrently. Pass "" to disable auto-tests.
+      Default: bun run ci:static when package.json, bun.lock, node_modules, and
+      a ci:static script are present.
+  --dry-run
+      Print selected commands, do not run.
+  -h, --help
+      Show help.
+
+Modes:
+  local   codex review --uncommitted
+  branch  codex review --base <ref>
+  commit  codex review --commit <ref>
+  auto    dirty tree -> local, else PR/current branch -> branch
+EOF
+}
+
+mode=auto
+base_ref=
+commit_ref=HEAD
+reviewer=${AUTOREVIEW_REVIEWER:-${CODEX_REVIEW_REVIEWER:-auto}}
+fallback_reviewer=${AUTOREVIEW_FALLBACK_REVIEWER:-${CODEX_REVIEW_FALLBACK_REVIEWER:-auto}}
+codex_bin=${CODEX_BIN:-codex}
+claude_bin=${CLAUDE_BIN:-claude}
+pi_bin=${PI_BIN:-pi}
+opencode_bin=${OPENCODE_BIN:-opencode}
+droid_bin=${DROID_BIN:-droid}
+copilot_bin=${COPILOT_BIN:-copilot}
+yolo=${AUTOREVIEW_YOLO:-${CODEX_REVIEW_YOLO:-1}}
+output=${AUTOREVIEW_OUTPUT:-${CODEX_REVIEW_OUTPUT:-}}
+parallel_tests=
+parallel_tests_set=false
+parallel_tests_auto=false
+dry_run=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode) mode=${2:-}; shift 2 ;;
+    --base) base_ref=${2:-}; shift 2 ;;
+    --commit) commit_ref=${2:-}; shift 2 ;;
+    --reviewer) reviewer=${2:-}; shift 2 ;;
+    --fallback-reviewer) fallback_reviewer=${2:-}; shift 2 ;;
+    --codex-bin) codex_bin=${2:-}; shift 2 ;;
+    --claude-bin) claude_bin=${2:-}; shift 2 ;;
+    --pi-bin) pi_bin=${2:-}; shift 2 ;;
+    --opencode-bin) opencode_bin=${2:-}; shift 2 ;;
+    --droid-bin) droid_bin=${2:-}; shift 2 ;;
+    --copilot-bin) copilot_bin=${2:-}; shift 2 ;;
+    --full-access) yolo=1; shift ;;
+    --no-yolo) yolo=0; shift ;;
+    --output) output=${2:-}; shift 2 ;;
+    --parallel-tests) parallel_tests=${2:-}; parallel_tests_set=true; shift 2 ;;
+    --dry-run) dry_run=true; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) usage >&2; exit 2 ;;
+  esac
+done
+
+case "$mode" in
+  auto|local|branch|commit) ;;
+  *) echo "invalid --mode: $mode" >&2; exit 2 ;;
+esac
+
+case "$reviewer" in
+  auto|codex|claude|pi|opencode|droid|copilot) ;;
+  *) echo "invalid --reviewer: $reviewer" >&2; exit 2 ;;
+esac
+
+case "$fallback_reviewer" in
+  auto|claude|pi|opencode|droid|copilot|none) ;;
+  *) echo "invalid --fallback-reviewer: $fallback_reviewer" >&2; exit 2 ;;
+esac
+
+repo_root=$(git rev-parse --show-toplevel)
+current_branch=$(git branch --show-current 2>/dev/null || true)
+dirty=false
+if [[ -n "$(git status --porcelain)" ]]; then
+  dirty=true
+fi
+
+codex_args=()
+case "$yolo" in
+  0|false|False|FALSE|no|No|NO|off|Off|OFF) ;;
+  *) codex_args+=(--dangerously-bypass-approvals-and-sandbox --sandbox danger-full-access) ;;
+esac
+
+has_package_script() {
+  local script_name=$1
+  command -v node >/dev/null 2>&1 || return 1
+  node -e '
+    const { readFileSync } = require("node:fs");
+    const pkg = JSON.parse(readFileSync(process.argv[1], "utf8"));
+    process.exit(pkg.scripts?.[process.argv[2]] ? 0 : 1);
+  ' "$repo_root/package.json" "$script_name" >/dev/null 2>&1
+}
+
+auto_tests_disabled() {
+  case "${AUTOREVIEW_AUTO_TESTS:-${CODEX_REVIEW_AUTO_TESTS:-1}}" in
+    0|false|False|FALSE|no|No|NO|off|Off|OFF) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+pr_url=
+if [[ -z "$base_ref" && "$mode" != local ]] && command -v gh >/dev/null 2>&1; then
+  if pr_lines=$(gh pr view --json baseRefName,url --jq '[.baseRefName, .url] | @tsv' 2>/dev/null); then
+    base_name=${pr_lines%%$'\t'*}
+    pr_url=${pr_lines#*$'\t'}
+    if [[ -n "$base_name" ]]; then
+      base_ref="origin/$base_name"
+    fi
+  fi
+fi
+
+if [[ -z "$base_ref" ]]; then
+  base_ref=origin/main
+fi
+
+review_kind=
+if [[ "$mode" == local || ( "$mode" == auto && "$dirty" == true ) ]]; then
+  review_kind=local
+elif [[ "$mode" == commit ]]; then
+  review_kind=commit
+elif [[ "$mode" == branch || ( "$mode" == auto && -n "$current_branch" && "$current_branch" != "main" ) ]]; then
+  review_kind=branch
+else
+  echo "no review target: clean main checkout and no forced mode" >&2
+  exit 1
+fi
+
+if [[ "$review_kind" == local ]]; then
+  review_cmd=("$codex_bin" "${codex_args[@]}" review --uncommitted)
+elif [[ "$review_kind" == commit ]]; then
+  review_cmd=("$codex_bin" "${codex_args[@]}" review --commit "$commit_ref")
+else
+  review_cmd=("$codex_bin" "${codex_args[@]}" review --base "$base_ref")
+fi
+
+if [[ "$parallel_tests_set" == false && -z "$parallel_tests" ]] && ! auto_tests_disabled; then
+  if [[ -f "$repo_root/package.json" && -f "$repo_root/bun.lock" && -d "$repo_root/node_modules" ]] &&
+    command -v bun >/dev/null 2>&1 && has_package_script ci:static; then
+    printf -v quoted_repo_root '%q' "$repo_root"
+    parallel_tests="cd $quoted_repo_root && bun run ci:static"
+    parallel_tests_auto=true
+  fi
+fi
+
+printf 'autoreview target: %s\n' "$review_kind"
+printf 'branch: %s\n' "${current_branch:-detached}"
+if [[ -n "$pr_url" ]]; then
+  printf 'pr: %s\n' "$pr_url"
+fi
+if [[ "$reviewer" == auto ]]; then
+  printf 'reviewer: codex\n'
+else
+  printf 'reviewer: %s\n' "$reviewer"
+fi
+if [[ "$reviewer" == auto || "$reviewer" == codex ]]; then
+  printf 'review:'
+  printf ' %q' "${review_cmd[@]}"
+  printf '\n'
+else
+  printf 'review: %s prompt review\n' "$reviewer"
+fi
+if [[ -n "$parallel_tests" ]]; then
+  printf 'tests: %s' "$parallel_tests"
+  if [[ "$parallel_tests_auto" == true ]]; then
+    printf ' (auto)'
+  fi
+  printf '\n'
+fi
+if [[ "$review_kind" == branch ]]; then
+  printf 'fetch: git fetch origin --quiet\n'
+fi
+if [[ -n "$output" ]]; then
+  printf 'output: %s\n' "$output"
+fi
+if [[ "$dry_run" == true ]]; then
+  exit 0
+fi
+
+if [[ "$review_kind" == branch ]]; then
+  git fetch origin --quiet || {
+    echo "warning: git fetch origin failed; reviewing with existing refs" >&2
+  }
+fi
+
+review_output=$output
+review_output_is_temp=false
+prompt_file=
+if [[ -z "$review_output" ]]; then
+  review_output=$(mktemp)
+  review_output_is_temp=true
+fi
+mkdir -p "$(dirname "$review_output")"
+: > "$review_output"
+
+cleanup() {
+  if [[ "${review_output_is_temp:-false}" == true && -n "${review_output:-}" ]]; then
+    rm -f "$review_output"
+  fi
+  if [[ -n "${prompt_file:-}" ]]; then
+    rm -f "$prompt_file"
+  fi
+}
+trap cleanup EXIT
+
+diff_for_review() {
+  case "$review_kind" in
+    local)
+      git -C "$repo_root" diff --stat
+      git -C "$repo_root" diff --cached --stat
+      git -C "$repo_root" diff --find-renames
+      git -C "$repo_root" diff --cached --find-renames
+      while IFS= read -r untracked_file; do
+        [[ -n "$untracked_file" ]] || continue
+        git -C "$repo_root" diff --no-index -- /dev/null "$untracked_file" || true
+      done < <(git -C "$repo_root" ls-files --others --exclude-standard)
+      ;;
+    commit)
+      git -C "$repo_root" show --find-renames --stat --format=fuller "$commit_ref"
+      git -C "$repo_root" show --find-renames --format=medium "$commit_ref"
+      ;;
+    branch)
+      git -C "$repo_root" diff --find-renames --stat "$base_ref"...HEAD
+      git -C "$repo_root" diff --find-renames "$base_ref"...HEAD
+      ;;
+  esac
+}
+
+build_prompt_file() {
+  prompt_file=$(mktemp)
+  {
+    cat <<'EOF'
+You are reviewing a ClawHub diff.
+
+Return only accepted/actionable findings. Verify claims against the diff and
+reject speculative, low-value, or overbroad rewrites.
+
+Use this format for findings:
+[P1] Short title
+File: path:line
+Why: one sentence
+Fix: one sentence
+
+If no accepted/actionable findings, output exactly:
+autoreview clean: no accepted/actionable findings reported
+
+Diff:
+EOF
+    diff_for_review
+  } > "$prompt_file"
+}
+
+review_output_has_clean_marker() {
+  local path=$1
+  grep -Eq '^[^[:alnum:]]*autoreview clean: no accepted/actionable findings reported[[:space:]]*$' "$path"
+}
+
+review_output_has_findings() {
+  grep -Eq '\[P[0-3]\]' "$review_output"
+}
+
+review_output_empty() {
+  [[ ! -s "$review_output" ]] || ! grep -q '[^[:space:]]' "$review_output"
+}
+
+review_output_used_prompt_reviewer() {
+  grep -Eq '^fallback: (claude -p|pi -p|opencode run|droid exec|copilot)$' "$review_output"
+}
+
+run_codex_review() {
+  if ! command -v "$codex_bin" >/dev/null 2>&1; then
+    echo "codex reviewer unavailable: $codex_bin" >&2
+    return 127
+  fi
+  "${review_cmd[@]}" 2>&1 | tee "$review_output"
+}
+
+run_prompt_reviewer() {
+  local selected=$1
+  local status=0
+  local prompt_bytes=0
+  local copilot_prompt=
+  build_prompt_file
+  case "$selected" in
+    claude)
+      command -v "$claude_bin" >/dev/null 2>&1 || {
+        echo "fallback reviewer unavailable: $claude_bin" >&2
+        return 127
+      }
+      printf 'fallback: claude -p\n' | tee -a "$review_output"
+      "$claude_bin" --tools "" --no-session-persistence -p < "$prompt_file" 2>&1 | tee -a "$review_output"
+      status=${PIPESTATUS[0]}
+      ;;
+    pi)
+      command -v "$pi_bin" >/dev/null 2>&1 || {
+        echo "fallback reviewer unavailable: $pi_bin" >&2
+        return 127
+      }
+      printf 'fallback: pi -p\n' | tee -a "$review_output"
+      "$pi_bin" --no-tools --no-session -p < "$prompt_file" 2>&1 | tee -a "$review_output"
+      status=${PIPESTATUS[0]}
+      ;;
+    opencode)
+      command -v "$opencode_bin" >/dev/null 2>&1 || {
+        echo "fallback reviewer unavailable: $opencode_bin" >&2
+        return 127
+      }
+      printf 'fallback: opencode run\n' | tee -a "$review_output"
+      "$opencode_bin" run --pure --dir "$repo_root" "Review the attached prompt file. Do not modify files." --file "$prompt_file" 2>&1 | tee -a "$review_output"
+      status=${PIPESTATUS[0]}
+      ;;
+    droid)
+      command -v "$droid_bin" >/dev/null 2>&1 || {
+        echo "fallback reviewer unavailable: $droid_bin" >&2
+        return 127
+      }
+      printf 'fallback: droid exec\n' | tee -a "$review_output"
+      "$droid_bin" exec --cwd "$repo_root" -f "$prompt_file" 2>&1 | tee -a "$review_output"
+      status=${PIPESTATUS[0]}
+      ;;
+    copilot)
+      command -v "$copilot_bin" >/dev/null 2>&1 || {
+        echo "fallback reviewer unavailable: $copilot_bin" >&2
+        return 127
+      }
+      printf 'fallback: copilot\n' | tee -a "$review_output"
+      prompt_bytes=$(wc -c < "$prompt_file" | tr -d '[:space:]')
+      if (( prompt_bytes > 120000 )); then
+        echo "copilot reviewer unavailable: generated prompt is too large" | tee -a "$review_output"
+        status=1
+      else
+        copilot_prompt=$(< "$prompt_file")
+        "$copilot_bin" -C "$repo_root" --available-tools=none --stream off --output-format text --silent -p "$copilot_prompt" 2>&1 | tee -a "$review_output"
+        status=${PIPESTATUS[0]}
+      fi
+      ;;
+    *)
+      echo "unsupported prompt reviewer: $selected" >&2
+      status=2
+      ;;
+  esac
+  rm -f "$prompt_file"
+  prompt_file=
+  return "$status"
+}
+
+fallback_reviewer_is_available() {
+  local selected=$1
+  case "$selected" in
+    claude) command -v "$claude_bin" >/dev/null 2>&1 ;;
+    pi) command -v "$pi_bin" >/dev/null 2>&1 ;;
+    opencode) command -v "$opencode_bin" >/dev/null 2>&1 ;;
+    droid) command -v "$droid_bin" >/dev/null 2>&1 ;;
+    copilot) command -v "$copilot_bin" >/dev/null 2>&1 ;;
+    *) return 1 ;;
+  esac
+}
+
+run_selected_review() {
+  local selected=$1
+  case "$selected" in
+    codex) run_codex_review ;;
+    claude|pi|opencode|droid|copilot) run_prompt_reviewer "$selected" ;;
+    *) echo "unsupported reviewer: $selected" >&2; return 2 ;;
+  esac
+}
+
+run_auto_fallback_review() {
+  local selected
+  if [[ "$fallback_reviewer" != auto ]]; then
+    run_selected_review "$fallback_reviewer"
+    return $?
+  fi
+  for selected in claude pi opencode droid copilot; do
+    if fallback_reviewer_is_available "$selected"; then
+      run_selected_review "$selected"
+      return $?
+    fi
+  done
+  echo "fallback reviewer unavailable: no configured fallback CLI found" >&2
+  return 127
+}
+
+run_auto_review() {
+  local status=0
+  run_selected_review codex
+  status=$?
+  if [[ "$status" == 0 ]]; then
+    return 0
+  fi
+  if (( status > 128 && status < 192 )); then
+    return "$status"
+  fi
+  if review_output_has_findings; then
+    return "$status"
+  fi
+  if [[ "$fallback_reviewer" == none ]]; then
+    return "$status"
+  fi
+  if [[ "$fallback_reviewer" == auto ]]; then
+    printf 'autoreview warning: codex exited %s; trying configured fallback reviewers\n' "$status" >&2
+  else
+    printf 'autoreview warning: codex exited %s; falling back to %s\n' "$status" "$fallback_reviewer" >&2
+  fi
+  run_auto_fallback_review
+}
+
+elapsed_since() {
+  local started_at=$1
+  local finished_at
+  finished_at=$(date +%s)
+  printf '%s\n' "$((finished_at - started_at))"
+}
+
+format_elapsed() {
+  local seconds=$1
+  if (( seconds < 60 )); then
+    printf '%ss\n' "$seconds"
+  else
+    printf '%sm%ss\n' "$((seconds / 60))" "$((seconds % 60))"
+  fi
+}
+
+report_clean_review_or_fail() {
+  local elapsed_text
+  elapsed_text=$(format_elapsed "${review_elapsed_seconds:-0}")
+  if review_output_has_findings; then
+    printf 'autoreview complete after %s\n' "$elapsed_text"
+    printf 'autoreview findings: accepted/actionable findings reported\n'
+    return 1
+  fi
+  if review_output_empty; then
+    printf 'autoreview complete after %s; no output\n' "$elapsed_text"
+    return 1
+  fi
+  if review_output_used_prompt_reviewer && ! review_output_has_clean_marker "$review_output"; then
+    printf 'autoreview complete after %s\n' "$elapsed_text"
+    printf 'autoreview findings: prompt reviewer did not emit clean marker\n'
+    return 1
+  fi
+  printf 'autoreview complete after %s\n' "$elapsed_text"
+  printf 'autoreview clean: no accepted/actionable findings reported\n'
+}
+
+if [[ -z "$parallel_tests" ]]; then
+  review_started_at=$(date +%s)
+  set +e
+  if [[ "$reviewer" == auto ]]; then
+    run_auto_review
+  else
+    run_selected_review "$reviewer"
+  fi
+  review_status=$?
+  review_elapsed_seconds=$(elapsed_since "$review_started_at")
+  set -e
+  if [[ "$review_status" == 0 ]]; then
+    report_clean_review_or_fail
+    exit $?
+  fi
+  exit "$review_status"
+fi
+
+review_status_file=$(mktemp)
+review_elapsed_file=$(mktemp)
+tests_status_file=$(mktemp)
+
+(
+  set +e
+  review_started_at=$(date +%s)
+  if [[ "$reviewer" == auto ]]; then
+    run_auto_review
+  else
+    run_selected_review "$reviewer"
+  fi
+  status=$?
+  elapsed=$(elapsed_since "$review_started_at")
+  printf '%s\n' "$status" > "$review_status_file"
+  printf '%s\n' "$elapsed" > "$review_elapsed_file"
+) &
+review_pid=$!
+
+(
+  set +e
+  bash -lc "$parallel_tests"
+  status=$?
+  printf '%s\n' "$status" > "$tests_status_file"
+) &
+tests_pid=$!
+
+wait "$review_pid" || true
+wait "$tests_pid" || true
+
+review_status=$(cat "$review_status_file")
+review_elapsed_seconds=$(cat "$review_elapsed_file")
+tests_status=$(cat "$tests_status_file")
+rm -f "$review_status_file" "$review_elapsed_file" "$tests_status_file"
+
+printf 'autoreview exit: %s\n' "$review_status"
+printf 'tests exit: %s\n' "$tests_status"
+
+if [[ "$review_status" != 0 || "$tests_status" != 0 ]]; then
+  exit 1
+fi
+
+report_clean_review_or_fail
@@ -0,0 +1,96 @@
+---
+name: clawhub-moderation
+description: "Use for ClawHub staff moderation actions with the repo-local clawhub-mod tool: unhide skills, ban or unban users, change roles, and verify moderation state."
+---
+
+# ClawHub Moderation
+
+Use the repo-local `clawhub-mod` 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 `skills unhide`, `users ban`, and `users unban`.
+- Before any write, show the exact command and ask for confirmation unless the
+  user already said to proceed or supplied `--yes`.
+- 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.
+
+## Commands
+
+Run from the ClawHub repo root:
+
+```sh
+bun run mod -- --help
+```
+
+Authenticate or validate the current token:
+
+```sh
+bun run mod -- login
+bun run mod -- whoami
+```
+
+Unhide a skill after moderator review:
+
+```sh
+bun run mod -- skills unhide <slug> --reason "<reason>" --yes
+```
+
+List and triage skill reports:
+
+```sh
+bun run mod -- skills reports --status open
+bun run mod -- skills triage-report <report-id> --status confirmed --action hide --note "<note>" --yes
+```
+
+Ban a user:
+
+```sh
+bun run mod -- users ban <handleOrId> --reason "<reason>" --yes
+```
+
+Unban a user:
+
+```sh
+bun run mod -- users unban <handleOrId> --reason "<reason>" --yes
+```
+
+Change a user role:
+
+```sh
+bun run mod -- users set-role <handleOrId> <user|moderator|admin> --yes
+```
+
+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.
+
+The old top-level aliases still exist for user commands:
+
+```sh
+bun run mod -- ban-user <handleOrId> --reason "<reason>" --yes
+bun run mod -- unban-user <handleOrId> --reason "<reason>" --yes
+```
+
+## Verification
+
+- For skills, inspect the page/API status after `skills unhide`.
+- For users, prefer `bun run mod -- whoami` for the current token and user
+  search/admin surfaces for target accounts where available.
+- 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-mod`; use report
+  triage with `--action hide` when resolving a report that should hide a skill.
+- `ban-user` is disruptive: it revokes API tokens, marks the user deleted,
+  hides owned skills, soft-deletes comments, and writes audit logs.
+- `unban-user` is admin-only. It clears ban state and restores skills that were
+  hidden by the matching ban flow; revoked API tokens stay revoked.
@@ -0,0 +1,102 @@
+---
+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
+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.
+
+## 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.
+- 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,93 @@
+---
+name: clawhub-ui-proof
+description: Use when ClawHub UI changes need visual proof, before/after comparison, new-feature screenshots, temporary Playwright scenarios, or Crabbox desktop recordings.
+---
+
+# ClawHub UI Proof
+
+Use `proof:ui` for human-readable UI evidence. The agent should write a
+temporary scenario for the feature instead of manually clicking through the UI.
+
+## Pick A Mode
+
+- Use `--mode before-after` for bug fixes, regressions, changed copy, changed
+  layout, or anything where main-vs-candidate comparison helps. This is the
+  default and runs baseline `origin/main` plus the candidate worktree.
+- Use `--mode feature` for new pages, new workflows, or new UI states that do
+  not exist on main. This runs only the candidate lane.
+- Every proof lane runs full-stack by default: the lane's Git checkout starts
+  its own local Convex backend, pushes that lane's functions/schema, and builds
+  the frontend against that lane-local Convex URL. Add
+  `--seed-command '<command>'` when the scenario needs fixtures.
+- Dev auth is opt-in. Use `--dev-auth` or explicit `--env KEY=VALUE` entries
+  only for scenarios that need development auth controls.
+- Do not use `proof:ui` to inspect contributor-provided screenshots, videos, or
+  logs. Review those artifacts directly and cite what they prove or fail to
+  prove.
+
+## Scenario Shape
+
+Create a temporary scenario under `.artifacts/proof-scenarios/`:
+
+```js
+export default async function scenario({ baseURL, expect, page, proof }) {
+  await proof.step("01 skills list", async () => {
+    await page.goto(`${baseURL}/skills`);
+    await expect(page.getByText("Skills")).toBeVisible();
+  });
+}
+```
+
+Each `proof.step()` captures a screenshot after the step. The runner compares
+`origin/main` to the current worktree by default in `before-after` mode.
+
+## Commands
+
+Dry-run the plan first. Before/after mode is the default:
+
+```sh
+bun run proof:ui -- --mode before-after --scenario .artifacts/proof-scenarios/my-fix.pw.ts --dry-run
+```
+
+For new feature proof, run candidate-only:
+
+```sh
+bun run proof:ui -- --mode feature --scenario .artifacts/proof-scenarios/my-feature.pw.ts --dry-run
+```
+
+Run real desktop proof on a Crabbox-owned provider:
+
+```sh
+bun run proof:ui -- --mode before-after --scenario .artifacts/proof-scenarios/my-fix.pw.ts --provider hetzner
+```
+
+Run proof with seeded lane-local Convex fixtures:
+
+```sh
+bun run proof:ui -- --mode before-after --seed-command 'bunx convex run --no-push devSeed:seedNixSkills' --scenario .artifacts/proof-scenarios/my-fix.pw.ts --provider hetzner
+```
+
+Artifacts are written under `.artifacts/clawhub-ui-proof/<timestamp>/` with
+screenshots, videos when available, `summary.json`, and `report.md`. Feature
+mode has only candidate artifacts. Promote only broadly useful scenarios into
+committed `e2e/proofs/`.
+
+## Publish To A PR
+
+When UI proof should appear on a GitHub PR, publish the completed proof run
+instead of posting local paths:
+
+```sh
+bun run proof:publish -- --proof-dir .artifacts/clawhub-ui-proof/<timestamp> --target-pr <number>
+```
+
+`proof:publish` copies the selected screenshots, video preview GIFs when
+present, MP4s, `summary.json`, and `report.md` to the `qa-artifacts` branch,
+then upserts a marker-backed PR comment with inline screenshots/previews and
+linked MP4s. Use `--dry-run` first when drafting or checking the comment body.
+
+## Share In GitHub Issues
+
+When proof images or screenshots should appear in GitHub issues, share
+`here.now` links instead of uploading image attachments directly to GitHub.
+Include a short note about what the linked image proves.
@@ -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,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,52 @@
+---
+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.
+
+## 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,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 = "bun run setup:worktree -- --quiet"
+
+[[pre-start]]
+deps = "wt step copy-ignored || true; test -x node_modules/.bin/vite || bun install"
+
+[post-start]
+dev = "bun scripts/dev-worktree.ts --detach --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 --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
@@ -4,6 +4,7 @@ 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=

@@ -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,123 @@
+# 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/check-staged-secrets.mjs @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/commentModeration.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/commentScamPrompt.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/cli/commands/sync.ts @openclaw/openclaw-secops @Patrick-Erichsen
+/packages/clawhub/src/cli/scanSkills.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/deploy.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/http-api.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/security.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/webhook.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,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,72 @@
+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/commentModeration.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/commentScamPrompt.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,58 @@
+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/sync.ts
+  - packages/clawhub/src/cli/commands/transfer.ts
+  - packages/clawhub/src/cli/scanSkills.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,39 @@
+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/check-staged-secrets.mjs
+  - 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,41 @@
+version: 2
+updates:
+  - package-ecosystem: "bun"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "America/Los_Angeles"
+    open-pull-requests-limit: 10
+    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:
+      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@d0e04585c26905fdd92c94a09c159544c7ee1b67
+        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@5ca05834db1d3813554d1dd109e5f2087a8d7cbc
+        if: always()
+        env:
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
@@ -4,37 +4,130 @@ 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:
+  static:
+    name: static
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
-      - uses: actions/checkout@v4
-
-      - uses: oven-sh/setup-bun@v2
+      - uses: actions/checkout@v6
        with:
-          bun-version: 1.3.6
+          fetch-depth: 0

-      - name: Install
-        run: bun install --frozen-lockfile
-      - name: Peer deps
-        run: bun run check:peers
+      - uses: ./.github/actions/setup-bun

-      - name: Lint
-        run: bun run lint
+      - name: Static checks
+        run: bun run ci:static

-      - name: Test
-        run: bun run test
+  unit:
+    name: unit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun

      - name: Coverage
-        run: bun run coverage
+        run: bun run ci:unit

-      - name: Typecheck packages
-        run: |
-          bunx tsc -p packages/schema/tsconfig.json --noEmit
-          bunx tsc -p packages/clawdhub/tsconfig.json --noEmit
+  packages:
+    name: packages
+    runs-on: ubuntu-latest
+    timeout-minutes: 15

-      - name: Build
-        run: bun run build
+    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: ubuntu-latest
+    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: ubuntu-latest
+    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: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Install Playwright browsers
+        run: bunx playwright install --with-deps 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:
+    name: playwright-local-auth
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Install Playwright browsers
+        run: bunx playwright install --with-deps chromium
+
+      - name: Local-auth browser e2e
+        run: bun run test:pw:local-auth
+
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: playwright-local-auth-report
+          path: playwright-report/
+          if-no-files-found: ignore
@@ -0,0 +1,285 @@
+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: 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
@@ -0,0 +1,417 @@
+name: ClawHub CLI NPM Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish, for example v0.10.0
+        required: true
+        type: string
+      preflight_only:
+        description: Run validation/build only and skip the gated publish job
+        required: true
+        default: false
+        type: boolean
+      preflight_run_id:
+        description: Existing successful preflight workflow run id to promote without rebuilding
+        required: false
+        type: string
+
+concurrency:
+  group: clawhub-cli-npm-release-${{ inputs.tag }}
+  cancel-in-progress: false
+
+permissions: {}
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+  NODE_VERSION: "24.x"
+  BUN_VERSION: "1.3.10"
+
+jobs:
+  preflight_clawhub_cli_npm:
+    if: ${{ inputs.preflight_only }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Forbid preflight artifact promotion on validation-only runs
+        if: ${{ inputs.preflight_run_id != '' }}
+        run: |
+          echo "preflight_run_id is only valid for real publish runs."
+          exit 1
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          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:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Resolve CLI package directory
+        run: |
+          set -euo pipefail
+          if [[ -d "packages/clawhub" ]]; then
+            echo "PACKAGE_DIR=packages/clawhub" >> "$GITHUB_ENV"
+          elif [[ -d "packages/clawdhub" ]]; then
+            echo "PACKAGE_DIR=packages/clawdhub" >> "$GITHUB_ENV"
+          else
+            echo "Unable to find clawhub CLI package directory." >&2
+            exit 1
+          fi
+
+      - name: Ensure version is not already published
+        env:
+          PREFLIGHT_ONLY: ${{ inputs.preflight_only }}
+        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
+          )"
+
+          if npm view "clawhub@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            if [[ "${PREFLIGHT_ONLY}" == "true" ]]; then
+              echo "clawhub@${PACKAGE_VERSION} is already published on npm; continuing because preflight_only=true."
+              exit 0
+            fi
+            echo "clawhub@${PACKAGE_VERSION} is already published on npm."
+            exit 1
+          fi
+
+          echo "Publishing clawhub@${PACKAGE_VERSION}"
+
+      - 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)"
+          export RELEASE_SHA
+          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
+
+      - name: Pack prepared npm tarball
+        id: packed_tarball
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          pushd "$PACKAGE_DIR" >/dev/null
+          PACK_JSON="$(npm pack --json --ignore-scripts)"
+          echo "$PACK_JSON"
+          PACK_PATH="$(printf '%s\n' "$PACK_JSON" | node --input-type=module -e 'const chunks=[]; process.stdin.on("data", (chunk) => chunks.push(chunk)); process.stdin.on("end", () => { const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8")); const first = Array.isArray(parsed) ? parsed[0] : null; if (!first || typeof first.filename !== "string" || !first.filename) process.exit(1); process.stdout.write(first.filename); });')"
+          popd >/dev/null
+          if [[ -z "${PACK_PATH}" || ! -f "${PACKAGE_DIR}/${PACK_PATH}" ]]; then
+            echo "npm pack did not produce a tarball file." >&2
+            exit 1
+          fi
+          RELEASE_SHA="$(git rev-parse HEAD)"
+          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
+          )"
+          ARTIFACT_DIR="$RUNNER_TEMP/clawhub-cli-npm-preflight"
+          rm -rf "$ARTIFACT_DIR"
+          mkdir -p "$ARTIFACT_DIR"
+          cp "${PACKAGE_DIR}/${PACK_PATH}" "$ARTIFACT_DIR/"
+          printf '%s\n' "$RELEASE_TAG" > "$ARTIFACT_DIR/release-tag.txt"
+          printf '%s\n' "$RELEASE_SHA" > "$ARTIFACT_DIR/release-sha.txt"
+          printf '%s\n' "$PACKAGE_VERSION" > "$ARTIFACT_DIR/package-version.txt"
+          echo "dir=$ARTIFACT_DIR" >> "$GITHUB_OUTPUT"
+
+      - name: Upload prepared npm publish bundle
+        uses: actions/upload-artifact@v7
+        with:
+          name: clawhub-cli-npm-preflight-${{ inputs.tag }}
+          path: ${{ steps.packed_tarball.outputs.dir }}
+          if-no-files-found: error
+
+  validate_publish_request:
+    if: ${{ !inputs.preflight_only }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Require main workflow ref for publish
+        env:
+          WORKFLOW_REF: ${{ github.ref }}
+        run: |
+          set -euo pipefail
+          if [[ "${WORKFLOW_REF}" != "refs/heads/main" ]]; then
+            echo "Real publish runs must be dispatched from main. Use preflight_only=true for branch validation."
+            exit 1
+          fi
+
+      - name: Require preflight artifact promotion on real publish
+        env:
+          PREFLIGHT_RUN_ID: ${{ inputs.preflight_run_id }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${PREFLIGHT_RUN_ID}" ]]; then
+            echo "Real publish requires preflight_run_id from a successful npm preflight run." >&2
+            exit 1
+          fi
+
+  publish_clawhub_cli_npm:
+    needs: [validate_publish_request]
+    if: ${{ !inputs.preflight_only }}
+    runs-on: ubuntu-latest
+    environment: npm-release
+    permissions:
+      actions: read
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          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:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: https://registry.npmjs.org
+
+      - name: Resolve CLI package directory
+        run: |
+          set -euo pipefail
+          if [[ -d "packages/clawhub" ]]; then
+            echo "PACKAGE_DIR=packages/clawhub" >> "$GITHUB_ENV"
+          elif [[ -d "packages/clawdhub" ]]; then
+            echo "PACKAGE_DIR=packages/clawdhub" >> "$GITHUB_ENV"
+          else
+            echo "Unable to find clawhub CLI package directory." >&2
+            exit 1
+          fi
+
+      - name: Ensure version is not already published
+        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
+          )"
+
+          if npm view "clawhub@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "clawhub@${PACKAGE_VERSION} is already published on npm."
+            exit 1
+          fi
+
+          echo "Publishing clawhub@${PACKAGE_VERSION}"
+
+      - name: Verify preflight run metadata
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PREFLIGHT_RUN_ID: ${{ inputs.preflight_run_id }}
+        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
+        uses: actions/download-artifact@v8
+        with:
+          name: clawhub-cli-npm-preflight-${{ inputs.tag }}
+          path: preflight-tarball
+          repository: ${{ github.repository }}
+          run-id: ${{ inputs.preflight_run_id }}
+          github-token: ${{ github.token }}
+
+      - 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)"
+          export RELEASE_SHA
+          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 }}
+        run: |
+          set -euo pipefail
+          EXPECTED_RELEASE_SHA="$(git rev-parse HEAD)"
+          EXPECTED_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
+          )"
+          TAG_FILE="preflight-tarball/release-tag.txt"
+          SHA_FILE="preflight-tarball/release-sha.txt"
+          VERSION_FILE="preflight-tarball/package-version.txt"
+          if [[ ! -f "$TAG_FILE" || ! -f "$SHA_FILE" || ! -f "$VERSION_FILE" ]]; then
+            echo "Prepared preflight metadata is missing." >&2
+            ls -la preflight-tarball >&2 || true
+            exit 1
+          fi
+          ARTIFACT_RELEASE_TAG="$(tr -d '\r\n' < "$TAG_FILE")"
+          ARTIFACT_RELEASE_SHA="$(tr -d '\r\n' < "$SHA_FILE")"
+          ARTIFACT_PACKAGE_VERSION="$(tr -d '\r\n' < "$VERSION_FILE")"
+          if [[ "$ARTIFACT_RELEASE_TAG" != "$RELEASE_TAG" ]]; then
+            echo "Prepared preflight tag mismatch: expected $RELEASE_TAG, got $ARTIFACT_RELEASE_TAG" >&2
+            exit 1
+          fi
+          if [[ "$ARTIFACT_RELEASE_SHA" != "$EXPECTED_RELEASE_SHA" ]]; then
+            echo "Prepared preflight SHA mismatch: expected $EXPECTED_RELEASE_SHA, got $ARTIFACT_RELEASE_SHA" >&2
+            exit 1
+          fi
+          if [[ "$ARTIFACT_PACKAGE_VERSION" != "$EXPECTED_PACKAGE_VERSION" ]]; then
+            echo "Prepared preflight package version mismatch: expected $EXPECTED_PACKAGE_VERSION, got $ARTIFACT_PACKAGE_VERSION" >&2
+            exit 1
+          fi
+
+      - name: Resolve publish tarball
+        id: publish_tarball
+        run: |
+          set -euo pipefail
+          TARBALL_PATH="$(find preflight-tarball -type f -name '*.tgz' -print | sort | tail -n 1)"
+          if [[ -z "$TARBALL_PATH" ]]; then
+            echo "Prepared preflight tarball not found." >&2
+            ls -la preflight-tarball >&2 || true
+            exit 1
+          fi
+          echo "path=$TARBALL_PATH" >> "$GITHUB_OUTPUT"
+
+      - name: Publish
+        run: |
+          set -euo pipefail
+          publish_target="${{ steps.publish_tarball.outputs.path }}"
+          if [[ -n "${publish_target}" ]]; then
+            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: 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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # 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@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # 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@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        with:
+          category: "/codeql-light/${{ matrix.category }}"
@@ -0,0 +1,250 @@
+name: Deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "What to deploy"
+        required: true
+        default: full
+        type: choice
+        options:
+          - 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
+    timeout-minutes: 5
+    outputs:
+      deploy_backend: ${{ steps.mode.outputs.deploy_backend }}
+      deploy_frontend: ${{ steps.mode.outputs.deploy_frontend }}
+      run_smoke: ${{ steps.mode.outputs.run_smoke }}
+      target: ${{ steps.mode.outputs.target }}
+    steps:
+      - name: Require main ref for production deploy
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_REF}" != "refs/heads/main" ]]; then
+            echo "Production deploys must run from main."
+            exit 1
+          fi
+
+      - name: Resolve deploy mode
+        id: mode
+        run: |
+          set -euo pipefail
+          target="${{ inputs.target }}"
+          case "$target" in
+            full)
+              echo "deploy_backend=true" >> "$GITHUB_OUTPUT"
+              echo "deploy_frontend=true" >> "$GITHUB_OUTPUT"
+              echo "run_smoke=true" >> "$GITHUB_OUTPUT"
+              ;;
+            backend)
+              echo "deploy_backend=true" >> "$GITHUB_OUTPUT"
+              echo "deploy_frontend=false" >> "$GITHUB_OUTPUT"
+              echo "run_smoke=true" >> "$GITHUB_OUTPUT"
+              ;;
+            frontend)
+              echo "deploy_backend=false" >> "$GITHUB_OUTPUT"
+              echo "deploy_frontend=true" >> "$GITHUB_OUTPUT"
+              echo "run_smoke=true" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "Unsupported deploy target: $target" >&2
+              exit 1
+              ;;
+          esac
+          echo "target=$target" >> "$GITHUB_OUTPUT"
+
+  deploy-production:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    needs: validate-deploy-request
+    environment:
+      name: Production
+      url: https://clawhub.ai
+    env:
+      CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
+      PLAYWRIGHT_AUTH_STORAGE_STATE_JSON: ${{ secrets.PLAYWRIGHT_AUTH_STORAGE_STATE_JSON }}
+      PLAYWRIGHT_BASE_URL: https://clawhub.ai
+    steps:
+      - name: Check deploy configuration
+        run: |
+          set -euo pipefail
+          missing=()
+
+          if [[ "${{ needs.validate-deploy-request.outputs.deploy_backend }}" == "true" && -z "$CONVEX_DEPLOY_KEY" ]]; then
+            missing+=("CONVEX_DEPLOY_KEY")
+          fi
+
+          if (( ${#missing[@]} > 0 )); then
+            echo "::error::Missing required production environment secrets: ${missing[*]}"
+            exit 1
+          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."
+          fi
+
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
+        with:
+          bun-version: 1.3.10
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Stamp Convex build SHA
+        if: needs.validate-deploy-request.outputs.deploy_backend == 'true'
+        run: bunx convex env set APP_BUILD_SHA "${GITHUB_SHA}" --prod
+
+      - name: Stamp Convex deploy time
+        if: needs.validate-deploy-request.outputs.deploy_backend == 'true'
+        run: bunx convex env set APP_DEPLOYED_AT "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" --prod
+
+      - name: Deploy Convex
+        if: needs.validate-deploy-request.outputs.deploy_backend == 'true'
+        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 }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_SHA: ${{ github.sha }}
+          VERCEL_STATUS_CONTEXT: Vercel – clawhub
+        run: |
+          set -euo pipefail
+          for attempt in {1..90}; do
+            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 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)
+                echo "::error::Vercel production deployment failed for $GITHUB_SHA"
+                exit 1
+                ;;
+              pending)
+                echo "Vercel deployment pending for $GITHUB_SHA on attempt $attempt; waiting..."
+                ;;
+              *)
+                echo "Vercel status for $GITHUB_SHA not published yet on attempt $attempt; waiting..."
+                ;;
+            esac
+
+            sleep 10
+          done
+
+          echo "::error::Timed out waiting for Vercel production deployment for $GITHUB_SHA"
+          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: bun run test:e2e:prod-http
+
+      - name: Write authenticated storage state
+        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 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"}'
@@ -0,0 +1,354 @@
+name: Package Publish
+
+on:
+  workflow_call:
+    inputs:
+      source:
+        description: Package source to publish. Usually owner/repo, owner/repo@ref, or a GitHub URL.
+        required: false
+        type: string
+        default: ""
+      ref:
+        description: Optional ref to append to the source when source is not already pinned.
+        required: false
+        type: string
+      dry_run:
+        description: Preview only. When true, no publish mutation is performed.
+        required: false
+        type: boolean
+        default: true
+      json:
+        description: Emit structured JSON output.
+        required: false
+        type: boolean
+        default: true
+      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
+      owner:
+        description: Optional owner handle override for org/shared publishing.
+        required: false
+        type: string
+      version:
+        description: Optional package version override.
+        required: false
+        type: string
+      tags:
+        description: Optional comma-separated tags override.
+        required: false
+        type: string
+        default: latest
+      source_repo:
+        description: Optional source repo override for local-folder publishes.
+        required: false
+        type: string
+      source_commit:
+        description: Optional source commit override for local-folder publishes.
+        required: false
+        type: string
+      source_ref:
+        description: Optional source ref override for local-folder publishes.
+        required: false
+        type: string
+      source_path:
+        description: Optional source path inside the repository for monorepo package publishes.
+        required: false
+        type: string
+      clawhub_version:
+        description: Legacy npm CLI version input. Kept for compatibility; the workflow now runs the checked-out source.
+        required: false
+        type: string
+        default: latest
+    secrets:
+      clawhub_token:
+        required: false
+    outputs:
+      publish_json:
+        description: Structured JSON output from clawhub package publish.
+        value: ${{ jobs.publish.outputs.publish_json }}
+      release_id:
+        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:
+      contents: read
+      id-token: write
+    outputs:
+      publish_json: ${{ steps.capture.outputs.publish_json }}
+      release_id: ${{ steps.capture.outputs.release_id }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          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 "?"
+          token_url = f"{request_url}{joiner}audience={audience}"
+          request = Request(
+              token_url,
+              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}"
+              )
+
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          with output_path.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 }}
+          JSON_MODE: ${{ inputs.json }}
+          CLAWHUB_TOKEN: ${{ secrets.clawhub_token }}
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+        run: |
+          if [[ "$JSON_MODE" != "true" ]]; then
+            echo "::warning::This reusable workflow always emits JSON output; forcing --json for downstream parsing."
+          fi
+          if [[ "$DRY_RUN" == "true" ]]; then
+            exit 0
+          fi
+          if [[ -n "$CLAWHUB_TOKEN" ]]; then
+            exit 0
+          fi
+          if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" && -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" && -n "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]]; then
+            echo "No ClawHub token provided; publish will rely on GitHub OIDC trusted publishing."
+            exit 0
+          fi
+          echo "::error::Real publishes need secrets.clawhub_token, or GitHub OIDC on workflow_dispatch runs (permissions.id-token=write)."
+          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: Resolve publish command
+        env:
+          INPUT_SOURCE: ${{ inputs.source }}
+          INPUT_REF: ${{ inputs.ref }}
+          INPUT_DRY_RUN: ${{ inputs.dry_run }}
+          INPUT_OWNER: ${{ inputs.owner }}
+          INPUT_VERSION: ${{ inputs.version }}
+          INPUT_TAGS: ${{ inputs.tags }}
+          INPUT_SOURCE_REPO: ${{ inputs.source_repo }}
+          INPUT_SOURCE_COMMIT: ${{ inputs.source_commit }}
+          INPUT_SOURCE_REF: ${{ inputs.source_ref }}
+          INPUT_SOURCE_PATH: ${{ inputs.source_path }}
+          INPUT_SITE: ${{ inputs.site }}
+          INPUT_REGISTRY: ${{ inputs.registry }}
+          CLAWHUB_TOKEN: ${{ secrets.clawhub_token }}
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_REF: ${{ github.ref }}
+          GITHUB_SHA: ${{ github.sha }}
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+          import shlex
+          from pathlib import Path
+
+          source = os.environ["INPUT_SOURCE"].strip()
+          if not source:
+              source = os.environ["GITHUB_REPOSITORY"]
+          source_is_current_repo = source == os.environ["GITHUB_REPOSITORY"]
+          ref = os.environ["INPUT_REF"].strip()
+          if not ref and source_is_current_repo:
+              ref = os.environ["GITHUB_SHA"].strip()
+          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}"
+
+          cli_entry = (
+              Path(os.environ["GITHUB_WORKSPACE"])
+              / "clawhub-source"
+              / "packages"
+              / "clawhub"
+              / "src"
+              / "cli.ts"
+          )
+          if not cli_entry.exists():
+              raise SystemExit(f"Missing ClawHub CLI entrypoint at {cli_entry}")
+
+          cmd = [
+              "bun",
+              str(cli_entry),
+              "package",
+              "publish",
+              source,
+              "--site",
+              os.environ["INPUT_SITE"],
+              "--registry",
+              os.environ["INPUT_REGISTRY"],
+          ]
+
+          if os.environ["INPUT_DRY_RUN"] == "true":
+              cmd.append("--dry-run")
+          cmd.append("--json")
+
+          owner = os.environ["INPUT_OWNER"].strip()
+          version = os.environ["INPUT_VERSION"].strip()
+          tags = os.environ["INPUT_TAGS"].strip()
+          if owner:
+              cmd += ["--owner", owner]
+          if version:
+              cmd += ["--version", version]
+          if tags:
+              cmd += ["--tags", tags]
+          source_repo = os.environ["INPUT_SOURCE_REPO"].strip()
+          source_commit = os.environ["INPUT_SOURCE_COMMIT"].strip()
+          source_ref = os.environ["INPUT_SOURCE_REF"].strip()
+          source_path = os.environ["INPUT_SOURCE_PATH"].strip()
+          if source_repo:
+              cmd += ["--source-repo", source_repo]
+          if source_commit:
+              cmd += ["--source-commit", source_commit]
+          if source_ref:
+              cmd += ["--source-ref", source_ref]
+          elif source_is_current_repo:
+              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",
+                  f"GitHub Actions {os.environ['GITHUB_EVENT_NAME'].strip()} publish via CLAWHUB_TOKEN",
+              ]
+
+          path = Path(os.environ["RUNNER_TEMP"]) / "clawhub-package-publish-command.sh"
+          shell_line = " ".join(shlex.quote(part) for part in cmd)
+          path.write_text("#!/usr/bin/env bash\nset -euo pipefail\n" + shell_line + "\n", encoding="utf-8")
+          path.chmod(0o755)
+          print(shell_line)
+          PY
+
+      - name: Run package publish
+        run: |
+          set -euo pipefail
+          "$RUNNER_TEMP/clawhub-package-publish-command.sh" | tee "$RUNNER_TEMP/package-publish.json"
+
+      - name: Capture workflow outputs
+        id: capture
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+          from pathlib import Path
+
+          output_path = Path(os.environ["RUNNER_TEMP"]) / "package-publish.json"
+          raw = output_path.read_text(encoding="utf-8").strip()
+          parsed = json.loads(raw)
+
+          github_output = Path(os.environ["GITHUB_OUTPUT"])
+          with 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")
+              release_id = str(parsed.get("releaseId", "") or "")
+              fh.write(f"release_id={release_id}\n")
+          PY
+
+      - name: Upload publish JSON artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: clawhub-package-publish-json
+          path: ${{ runner.temp }}/package-publish.json
+          if-no-files-found: error
@@ -0,0 +1,66 @@
+name: "Security Gate: Secret Scanning"
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main, master]
+
+permissions: {}
+
+jobs:
+  trufflehog:
+    name: Scan for Verified Secrets
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read # Required to scan the code in the PR
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # necessary to support the scoping requirements below
+
+      - name: Resolve scan range
+        id: scan_range
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PUSH_BASE_SHA: ${{ github.event.before }}
+          PUSH_HEAD_SHA: ${{ github.sha }}
+          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          zero_sha="0000000000000000000000000000000000000000"
+
+          if [[ "$EVENT_NAME" == "pull_request" ]]; then
+            base="$PR_BASE_SHA"
+            head="$PR_HEAD_SHA"
+          else
+            base="$PUSH_BASE_SHA"
+            head="$PUSH_HEAD_SHA"
+            if [[ -z "$base" || "$base" == "$zero_sha" ]]; then
+              base="origin/$DEFAULT_BRANCH"
+            fi
+          fi
+
+          echo "base=$base" >> "$GITHUB_OUTPUT"
+          echo "head=$head" >> "$GITHUB_OUTPUT"
+
+      - name: TruffleHog OSS
+        id: trufflehog
+        # Use a concrete released ref that resolves in upstream action registry.
+        # v3 (major tag) is not published by trufflesecurity/trufflehog.
+        uses: trufflesecurity/trufflehog@v3.95.3
+        with:
+          path: ./
+          base: ${{ steps.scan_range.outputs.base }}
+          head: ${{ steps.scan_range.outputs.head }}
+          extra_args: --only-verified --debug
+
+      - name: Notify on Failure
+        if: steps.trufflehog.outcome == 'failure'
+        run: |
+          echo "::error::Verified secrets found! This PR contains live credentials that must be rotated immediately."
+          echo "::notice::If these secrets are already in the commit history, they cannot be removed via a simple removal commit/push. A repository owner can contact GitHub Support to purge the cached data: https://support.github.com/contact/private-information"
+          exit 1
@@ -0,0 +1,106 @@
+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: "6"
+      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
+
+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, 4, 5, 6, 7]
+    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'] || '6' }}
+      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,94 @@
+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: "6"
+      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
+
+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, 4, 5, 6, 7]
+    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'] || '6' }}
+      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,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,9 @@ node_modules
 .DS_Store
 .bun-build
 *.bun-build
+.artifacts/
+.cache/
+.data/
 bin/docs-list
 dist
 dist-ssr
@@ -10,7 +13,9 @@ dist-ssr
 *.local
 .vercel
 count.txt
-.env
+.env*
+!.env.local.example
+!.env.example
 .nitro
 .tanstack
 .wrangler
@@ -21,6 +26,33 @@ todos.json
 .vscode
 .env*.local
 coverage
+eval/cache/
+eval/results/
 playwright-report
 test-results
 .playwright
+convex/_generated/*
+!convex/_generated/ai/
+convex/_generated/ai/*
+!convex/_generated/ai/guidelines.md
+!convex/_generated/ai/ai-files.state.json
+skills-lock.json
+*/skills/*
+!.agents/skills/
+!.agents/skills/convex*/
+!.agents/skills/convex*/**
+!.agents/skills/clawhub-ui-proof/
+!.agents/skills/clawhub-ui-proof/**
+!.agents/skills/clawhub-pr-maintainer/
+!.agents/skills/clawhub-pr-maintainer/**
+!.agents/skills/clawhub-moderation/
+!.agents/skills/clawhub-moderation/**
+!.agents/skills/autoreview/
+!.agents/skills/autoreview/**
+skills/*
+.codex/*
+!.codex/environments/
+!.codex/environments/environment.toml
+.crabbox/
+/.comux-hooks
+/.comux
@@ -0,0 +1 @@
+22
@@ -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 @@
+node_modules/
@@ -1,48 +1,142 @@
 # Repository Guidelines

 ## Project Structure & Module Organization
+
 - `src/` — TanStack Start app code (routes, components, styles).
 - `convex/` — Convex backend (schema, queries/mutations/actions, HTTP routes).
 - `convex/_generated/` — generated Convex API/types; committed for builds.
- `docs/` — product/spec docs (see `docs/spec.md`).
+- `docs/` — publishable public/operator docs for the ClawHub docs tab.
+- `specs/` — product specs, plans, regression notes, design history (see `specs/spec.md`).
 - `public/` — static assets.

+## Durable Intent & Specs
+
+- Use `specs/` to persist system/subsystem intent, invariants, and design rationale that future agents should preserve.
+- Keep intended behavior for security-sensitive flows there, especially moderation, upload gating, scanner outcomes, appeals, bans, ownership, package installability, and API trust boundaries.
+- If code changes reveal or change how a subsystem is supposed to work, update the relevant spec or add a focused spec note instead of burying the intent only in PR text or public docs.
+- Keep `docs/` user/operator-facing: explain current behavior and commands there, but put internal “why this must work this way” context in `specs/`.
+
 ## Build, Test, and Development Commands
- `bun run dev` — local app server at `http://localhost:3000`.
+
+Keep this section as the command map agents normally need, not a full `package.json` script index.
+
+- `bun run dev` — foreground local app server at `http://localhost:3000`.
+- `bunx convex dev --typecheck=disable` — local Convex backend/function watcher for manual setup.
+- `bunx convex codegen` — regenerate `convex/_generated` after Convex API/schema changes.
+- `bun run setup:worktree` — link `.env.local` and `.convex` from a usable source worktree into the current worktree. Use `-- --from <path>` or `CLAWHUB_WORKTREE_SOURCE=<path>` when auto-discovery picks the wrong source.
+- `bun run dev:worktree` — Worktrunk-managed detached worktree server. Requires `wt` on `PATH`; from that worktree use `wt --yes url` to print the branch URL and `wt --yes stop` to stop it.
+- `bun run seed:dev` — canonical local seed path; runs worktree setup, waits for local Convex, seeds local fixtures plus the public corpus, and refreshes stats.
 - `bun run build` — production build (Vite + Nitro).
- `bun run preview` — preview built app.
- `bunx convex dev` — Convex dev deployment + function watcher.
- `bunx convex codegen` — regenerate `convex/_generated`.
- `bun run lint` — Biome + oxlint (type-aware).
- `bun run test` — Vitest (unit tests).
- `bun run coverage` — coverage run; keep global >= 80%.
+- `bun run ci:static` — required pre-handoff static gate: peer checks, audit, formatting, lint, and dead-code checks.
+- `bun run ci:unit` — Vitest coverage gate; required for source/test PRs unless docs/config-only.
+- `bun run ci:types-build` — full TypeScript/build gate for app, Convex, and packages.
+- `bun run ci:packages` — schema, CLI, and moderation package verification.
+- `bun run ci:e2e-http` — secretless HTTP and CLI e2e subset.
+- `bun run ci:playwright-smoke` — chromium smoke against the public read backend.
+- `bun run test:pw:local-auth` — local Convex/dev-auth browser gate for signed-in/write flows.
+
+Specialized corpus, scanner, security-worker, UI proof, proof publishing, Crabbox, docs-authoring, and dataset scripts are real maintenance tools, but they should stay in the relevant specs, skills, or package script lookup unless the task touches that subsystem.

 ## Coding Style & Naming Conventions
+
 - TypeScript strict; ESM.
 - Indentation: 2 spaces, single quotes (Biome).
 - Lint/format: Biome + oxlint (type-aware).
 - Convex function names: verb-first (`getBySlug`, `publishVersion`).
+- Inline code comments: add brief comments for tricky, bug-prone, or previously buggy logic.

 ## Testing Guidelines
+
 - Framework: Vitest 4 + jsdom.
 - Tests live in `src/**` and `convex/lib/**`.
 - Coverage threshold: 80% global (lines/functions/branches/statements).
 - Example: `convex/lib/skills.test.ts`.

 ## Commit & Pull Request Guidelines
+
 - Commit messages: Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`…).
 - Keep changes scoped; avoid repo-wide search/replace.
+- Before commit/PR handoff, run `bun run ci:static` so formatting, linting, audit/peer checks, and dead-code export checks match the CI `static` job. For faster inner loops, targeted `bun run format:check -- <files>` / `bun run lint` are fine, but do not treat them as the final pre-push gate.
+- Before commit/PR handoff for non-trivial code changes, use `$autoreview` until no accepted/actionable findings remain, unless equivalent manual review already happened, the change is trivial/docs-only, or the user opts out.
+- Before opening a PR for source or test changes, run the targeted tests for the touched behavior and `bun run ci:unit` (`VITE_CONVEX_URL=https://example.invalid bun run coverage`) unless the change is docs/config-only or the user explicitly asks to rely on CI. For runtime, build, or package changes, also run the matching broader gate when it covers the touched surface: `bun run ci:types-build`, `bun run ci:packages`, `bun run ci:e2e-http`, or `bun run ci:playwright-smoke`.
 - PRs: include summary + test commands run. Add screenshots for UI changes.
+- Before merging any PR, verify TypeScript cleanly with `bunx tsc -p packages/schema/tsconfig.json --noEmit` and `bunx tsc -p packages/clawhub/tsconfig.json --noEmit`; if Convex code changed, also run the repo typecheck path used by deploy so `bunx convex deploy` will not fail on `tsc`.
+- GitHub comments: for multiline `gh` comments/close messages, use `--body-file`, `--input`, or stdin/heredoc with real newlines; never pass literal `\\n` in shell strings.
+- Reject PRs that add skills into source code/repo content directly (for example under `skills/` or seed-only additions intended as published skills). Skills must be uploaded/published via CLI.
+- Repo-local developer skills under `.agents/skills/` are allowed only when they are ClawHub-specific, such as Convex, moderation, PR maintainer, or UI proof workflows. Keep generic shared skills such as `crabbox` and `autoreview` in the global `agent-skills` install, not this repo. Keep top-level `skills/` reserved for installed/published skill content and ignored by git.
+
+## Production Release
+
+- Production deploys are manual-only. Merging to `main` does **not** deploy.
+- To release production, start the GitHub Actions `Deploy` workflow from `main`:
+  `gh workflow run deploy.yml --repo openclaw/clawhub --ref main`
+- The workflow supports `full`, `backend`, and `frontend` targets.
+- `frontend` currently means: wait for the Vercel production deploy for the selected `main` SHA, then run production smoke checks. It does not call `vercel deploy` directly yet.
+- The workflow uses the GitHub `Production` environment for deploy secrets, but it does not require a separate approval step.
+- Prod deploy secrets live on the `Production` environment, not as ordinary repo secrets. Required: `CONVEX_DEPLOY_KEY`. Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`.
+- CLI npm releases are also manual-only and tag-based. Stable tags only: `vX.Y.Z`. Start `ClawHub CLI NPM Release` from `main`, first with `preflight_only=true`, then rerun it with the same tag and the successful `preflight_run_id`.
+- Real CLI publishes wait at the GitHub `npm-release` environment and use npm trusted publishing. Required npm trusted publisher settings: repository `openclaw/clawhub`, workflow `clawhub-cli-npm-release.yml`, environment `npm-release`.

 ## Git Notes
+
 - If `git branch -d/-D <branch>` is policy-blocked, delete the local ref directly: `git update-ref -d refs/heads/<branch>`.

+## URL Quick Reference
+
+- Canonical site: `https://clawhub.ai` (prefer this over legacy domains).
+- Skill page URL format: `https://clawhub.ai/<owner>/<slug>` (owner handle preferred; falls back to owner id).
+- Skill API detail URL: `https://clawhub.ai/api/v1/skills/<slug>`.
+- Skill file URL: `https://clawhub.ai/api/v1/skills/<slug>/file?path=SKILL.md`.
+- For “full URL?” requests, return the canonical page URL first, then API URL if useful.
+
 ## Configuration & Security
+
 - Local env: `.env.local` (never commit secrets).
 - Convex env holds JWT keys; Vercel only needs `VITE_CONVEX_URL` + `VITE_CONVEX_SITE_URL`.
 - OAuth: GitHub OAuth App credentials required for login.

 ## Convex Ops (Gotchas)
+
 - New Convex functions must be pushed before `convex run`: use `bunx convex dev --once` (dev) or `bunx convex deploy` (prod).
 - For non-interactive prod deploys, use `bunx convex deploy -y` to skip confirmation.
 - If `bunx convex run --env-file .env.local ...` returns `401 MissingAccessToken` despite `bunx convex login`, workaround: omit `--env-file` and use `--deployment-name <name>` / `--prod`.
+
+## Convex Query & Bandwidth Rules
+
+- **Always use `.withIndex()` instead of `.filter()` for fields that can be indexed.** `.filter()` causes full table scans — every doc is read and billed. Even a single `.filter()` on a 16K-row table reads ~16 MB per call.
+- **Convex reads entire documents** — no field projections. If you only need a few fields from large docs (~6 KB+), denormalize a lightweight summary onto the parent doc or use a lookup table (see `embeddingSkillMap`, `skill.latestVersionSummary`, `skill.badges` for examples).
+- **Denormalization pattern**: persist computed fields so they can be indexed. Every mutation that updates source fields must also update the denormalized field. Always write a cursor-based backfill for new fields (see `backfillIsSuspiciousInternal`, `backfillLatestVersionSummaryInternal`, `backfillDenormalizedBadgesInternal` for examples).
+- **Cron jobs must never scan entire tables.** Use indexed queries with equality filters. Use cursor-based pagination for large datasets. Prefer incremental/delta tracking over full recounts.
+- **32K document limit per query.** Split `.collect()` calls by a partition field (e.g., one day at a time instead of a 7-day range). See `rebuildTrendingLeaderboardAction` in `convex/leaderboards.ts` for an example.
+- **Common mistakes**: `.filter().collect()` without an index; `ctx.db.get()` on large docs in a loop for list views; while loops that paginate the whole table to find filtered results.
+- **Before writing or reviewing Convex queries, check deployment health.** Run `bunx convex insights` to check for OCC conflicts, `bytesReadLimit`, and `documentsReadLimit` errors. Run `bunx convex logs --failure` to see individual error messages and stack traces. This helps identify which functions are causing bandwidth issues so you can prioritize fixes.
+
+<!-- convex-ai-start -->
+
+This project uses [Convex](https://convex.dev) as its backend.
+
+When working on Convex code, **always read `convex/_generated/ai/guidelines.md` first** for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.
+
+Convex agent skills for common tasks can be installed by running `npx convex ai-files install`.
+
+<!-- convex-ai-end -->
+
+## Stat Field Migration Rules
+
+The `skills` table maintains two parallel sets of stat fields as part of an in-progress field migration:
+
+| Legacy (nested, `@deprecated`) | Top-level (source of truth, indexable) |
+| ------------------------------ | -------------------------------------- |
+| `stats.downloads`              | `statsDownloads`                       |
+| `stats.stars`                  | `statsStars`                           |
+| `stats.installsCurrent`        | `statsInstallsCurrent`                 |
+| `stats.installsAllTime`        | `statsInstallsAllTime`                 |
+
+**Rules:**
+
+- **Always use `readCanonicalStat(skill, field)` (`convex/lib/skillStats.ts`) to read** any of the four migrated fields. It prefers the top-level field and falls back to the nested field for pre-migration documents. Never access `skill.stats.downloads` / `.stars` / `.installsCurrent` / `.installsAllTime` directly.
+- **Always use `applySkillStatDeltas()` to write** stat deltas. It writes both the top-level and nested fields in the same patch to keep them in sync.
+- **Both sets of fields must be written together** in any patch that touches stat values (see the return shape of `applySkillStatDeltas`).
+- **Nested-only reads are acceptable only for** `stats.comments` and `stats.versions` — no top-level field exists for these yet.
+- The four legacy nested fields are marked `@deprecated` in `statsValidator` (schema.ts). Any IDE access to `skill.stats.downloads` etc. will show a strikethrough warning — treat this as a signal to use `readCanonicalStat()` instead.
+- When adding new stat fields, follow the same dual-write pattern and add a cursor-based backfill mutation (see `backfillSkillStatFieldsInternal` for an example).
@@ -1,17 +1,415 @@
 # Changelog

+## Unreleased
+
+### Fixes
+
+- API/CLI: report Skill Card verification with flattened skill/version metadata, ClawScan verdict fields at `security.*`, and supporting scanner evidence under `security.signals`.
+
+## 0.18.0 - 2026-05-25
+
+### Changes
+
+- CLI/API: add Skill Card verification surfaces, including `clawhub skill verify <slug>` JSON output and `--card` Markdown retrieval (#2382).
+- Web/API: surface an "API key required" attribute on skills so listings, cards, and detail views show whether a skill needs an LLM API key, with publish-time inference from skill prompts and metadata (#2353) (thanks @momothemage).
+
+### Fixes
+
+- API: fix `GET /api/v1/skills` pagination so `cursor` advances to the next page instead of repeating the first page for supported non-trending sorts (#2275) (thanks @vyctorbrzezowski, @enerj).
+- Web: block collaborative membership on personal publishers while allowing the linked owner to clean up stale extra membership rows (thanks @vyctorbrzezowski).
+- Security/API: hide owned package/plugin catalog entries, revoke package publish tokens, and restore only matching ban-hidden packages on user unban (thanks @vyctorbrzezowski).
+- API: block public raw skill files when moderation already blocks downloads and reject skill tags that point at another skill's version (thanks @vyctorbrzezowski).
+- Web: stop stale unban restore batches from reactivating skills after the owner is banned again or deactivated (thanks @vyctorbrzezowski).
+- Security/API: reject direct skill owner transfers when the skill is hidden, suspicious, or malicious (thanks @vyctorbrzezowski).
+- Security/API: revalidate package publish actor, owner, and owner publisher active state in the final release insert (thanks @vyctorbrzezowski).
+
+## 0.17.0 - 2026-05-19
+
+- CLI/API: add self-serve org publisher creation with `clawhub publisher create <handle>` and scoped package publish errors that point to the command.
+
+## 0.16.0 - 2026-05-18
+
+### Fixes
+
+- CLI/API: make package publishes robust under parallel same-publisher release jobs by avoiding unnecessary shared publisher writes, retrying transient Convex contention, and labeling contention separately from package validation failures (#2291).
+- Security: move upload ClawScan classification to a GitHub Actions Codex worker, treat VirusTotal as telemetry-only signal, and trust verified `@openclaw/*` plugin packages by default.
+- Security: cancel pending skill ownership transfers before rejecting accept attempts when the requester is inactive or the skill is hidden, removed, or malicious (#2276, #2277) (thanks @vyctorbrzezowski).
+- API/CLI: fix package delete returning 500 for packages with capability tags when no capability search digest row existed yet (#2212) (thanks @momothemage).
+- API: return a clear 400 for `/api/v1/packages/search` without a non-empty `q` instead of treating `search` as a package name (thanks @vyctorbrzezowski).
+- Web/API: keep search results limited to items with match evidence, preserve trust and popularity as tie-breakers, and show `N+` counts without exact count queries (#2206) (thanks @vyctorbrzezowski).
+- Web: preserve `ownerHandle` through legacy skill publish redirects so org admins land in the correct new-version owner context (#2177).
+- Settings: save display name/bio changes even when a legacy personal publisher handle conflict prevents publisher profile sync (#1199).
+- Auth: show a visible error if the GitHub sign-in request fails before the provider redirect starts (#2197).
+- Schema: include `.tsv`, `.conf`, `.properties`, and `.dat` in the exported text-file allowlist and regenerate the committed schema package runtime (#2172, #874) (thanks @alexuser).
+- API: return `400` for invalid known public package filters and invalid skill list sort values, while continuing to ignore unknown query parameters (#2184).
+- API/docs: document v1 plain-text error responses and expose owner metadata in the OpenAPI search result schema (#2187) (thanks @vyctorbrzezowski).
+- Web: rank publisher card preview items by downloads instead of recent publish order (thanks @vyctorbrzezowski).
+- Web: remove the desktop Files tab height cap and make mobile truncation explicit (thanks @vyctorbrzezowski).
+- Web: keep skill/plugin detail tabs at mobile-friendly touch target height.
+
+### Changes
+
+- CLI/API: include skill owner handles in search results so duplicate/common slugs are easier to disambiguate (thanks @vyctorbrzezowski).
+- Web: let skill publishers pick a curated lucide icon for cards and listings (#2174) (thanks @momothemage).
+- Web/API: add keyword-based plugin categories plus API-backed plugin search sorting for recently updated, newest, and name (#2118) (thanks @vyctorbrzezowski).
+- Web: polish the starred skills page with grid/list controls, sorting, and optimistic unstar behavior (#2159) (thanks @vyctorbrzezowski).
+- API/docs: expand the v1 OpenAPI contract with package/plugin catalog endpoints and align documented rate limits with the server constants (#2186) (thanks @vyctorbrzezowski).
+- Admin/Ops: audit profile syncs, self-service account/profile changes, personal publisher syncs, and org trusted-publisher changes so slug and ownership investigations have a complete ledger.
+- Dependencies: update production `@clack/prompts`, `tailwind-merge`, and `yaml` dependencies (#2198).
+
+## 0.15.0 - 2026-05-12
+
+### Changes
+
+- Web: polish dashboard artifact cards, loading skeletons, skill summary/detail layout, and adoption metrics after the 0.14 release (#2150, #2153, #2156, #2157, #2158, #2160).
+- Docs/dev: clarify pre-PR validation gates for local contributors (#2161).
+
+### Fixes
+
+- Web: show plugin settings actions to package managers and preserve manager access in dashboard rows (#2163, #2168).
+- Web: refresh skill star state after mutations and keep skill tabs from causing horizontal scroll (#2154, #2155).
+- Web: show owner names when handles are hidden, and clarify editable skill summary settings copy (#2151, #2162).
+- Dashboard: add a publisher switcher so org-owned skills and plugins are visible to org admins after transfer or publish (#2132).
+- Web: let org publishers/admins republish transferred org-owned skills without the publish form treating the existing slug as taken, including legacy users with synthesized personal publishers (#2171).
+- CLI: send skill ownership command payloads as JSON objects so rename/merge operations reach the API correctly (#1300).
+- CLI: keep an install fingerprint in skill origin metadata so `clawhub update <skill>` does not report fresh installs as local changes when the server cannot resolve the current hash (#169).
+- CLI: migrate cached `registry.clawhub.ai` registries back to `clawhub.ai` so `clawhub explore` no longer talks to the retired Vercel deployment (#1098).
+- CLI: publish `.tsv`, `.conf`, `.properties`, `.dat`, and safe extensionless text files while excluding dotfiles and sampling extensionless files before full reads (#874).
+- Tests: remove obsolete rescan e2e probes that no longer match current moderation behavior (#2152).
+
+## 0.14.0 - 2026-05-11
+
+### Changes
+
+- Dev: auto-start services for Codex worktrees and add a local dev persona FAB (#2146, #2147).
+- Dev: add a local ClawScan dry-run helper script (#2143).
+
+### Fixes
+
+- API: return deterministic 403 responses for skill/package rescan and package transfer permission denials, with CI e2e coverage for protected write endpoints.
+
+## 0.13.0 - 2026-05-11
+
+### Changes
+
+- Web: redesign Settings into focused account, organization, API token, and account deletion views with responsive desktop and mobile layouts (#2134) (thanks @vyctorbrzezowski).
+- Web: replace the Users directory with a Publishers discovery surface covering builders and organizations, add `/publishers` as the canonical route, and keep `/users` compatibility (#2087) (thanks @vyctorbrzezowski).
+- Web: polish browse/listing surfaces across skills, plugins, and search, including plugin card view parity, clearer search controls, visible safety filtering, and more consistent card metadata treatment (#2084) (thanks @vyctorbrzezowski).
+- Web: allow skill owners and publisher admins to edit a skill summary from the detail page (#1411) (thanks @SylvanXiao).
+- CLI/Auth: add device-code login for remote or headless shells, backed by ClawHub device authorization endpoints (#1867) (thanks @LumenFromTheFuture).
+- CLI: add per-skill pinning so installed skills can be frozen against direct updates, bulk updates, and force reinstalls (#1806) (thanks @deepujain).
+- Web: rename the skills and plugins browse alternate view from Cards to Grid while keeping legacy `view=cards` URLs compatible (#2119) (thanks @vyctorbrzezowski).
+- Dev docs: refresh generated Convex AI guidance files (#2000).
+
+### Fixes
+
+- Moderation: stop treating VirusTotal Code Insight/Palm verdicts as a hide authority for skills; real AV-engine hits and ClawScan findings still contribute moderation verdicts.
+- Moderation: stop treating static suspicious-only findings as a verdict; keep file/line evidence for review while VT/LLM decide public suspicious status.
+- ClawScan: reduce false positives for scoped uninstall cleanup, declared provider login flows, Basic Auth/base64 handling, and user-directed provider uploads while hard-blocking stealth browser abuse patterns.
+- ClawScan: lower false positives by treating purpose-aligned notes as benign unless structured LLM findings contain a material concern, and add targeted rescan batches for suspicious skills/plugins.
+- Moderation: split visible ClawScan review guidance from hidden suspicious filtering, and add operator cleanup for stale aggregate rows and obvious test/placeholder suspicious skills.
+- Security: add an admin-only moderation hold lift path for false-positive publisher holds, with audited skill restoration that preserves independently hidden skills (#1133) (thanks @Justincredible-tech).
+- Moderation: let platform moderators and admins trigger skill/package security rescans for any owner from the CLI, without consuming the owner recovery cap.
+- ClawScan: include package `openclaw.environment` env/config declarations in package review prompts so declared plugin runtime requirements are not reported as missing (#2013).
+- Skills/Packages: let publisher admins manage owned lifecycle operations consistently, including skill rename/delete/restore, direct skill moves into org publishers they administer, package restore from the CLI/API, and direct moves back to their personal publisher.
+- Skills: repair publisher-owned skill merges, bound historical slug redirects, block protected slug namespaces, and expire owner-unpublished slug reservations after 30 days (#2115) (thanks @fuller-stack-dev).
+- Skills: allow confirmed owner migration when republishing an existing skill to another publisher, preserving versions, stats, aliases, and audit history (#1998, #2102) (thanks @momothemage).
+- Security: block owner delete/undelete paths from overriding moderator or scanner hides, and return explicit 403 authz responses for owner restore denials (#2078) (thanks @momothemage).
+- CLI/API: send skill transfer payloads as JSON objects so transfer requests reach the API correctly.
+- Packages: keep package search digests schema-safe during delete/restore so package lifecycle CLI calls do not fail after provenance updates.
+- Search: recall skill matches by non-first slug/display-name tokens while keeping multi-token queries on the direct recall path constrained to all query tokens (#2140) (thanks @momothemage).
+- Search/Web: disclose when `/search` is hiding suspicious skills and add an explicit opt-out so unified search no longer silently differs from `/skills` for the same query (#2079) (thanks @momothemage).
+- Uploads: accept PowerShell `.ps1`, `.psm1`, and `.psd1` files as text-based skill files while keeping normal scan coverage (#897) (thanks @cute-omega).
+- Packages: count package install stat events separately from package downloads and record npm tarball fetches as installs (#1712).
+- Web: keep the Publishers directory responsive for high-volume publishers by using bounded published-item previews, and abort stale unified-search plugin requests during route changes.
+- Web: point skill, plugin, and soul owner links directly at canonical `/p/:handle` publisher profiles instead of legacy redirect routes.
+- Web/API: ignore stale public skill-list cursors from older sort or safety-filter indexes instead of throwing pagination errors.
+- Web: restore dashboard skill metrics for owned skills and use pointer cursors on dropdown menu items (#2113) (thanks @fuller-stack-dev).
+- Web: show the skills browse `Hide suspicious` control only when the loaded results include suspicious skills (thanks @vyctorbrzezowski).
+- Web: align signed-in header avatar controls across desktop and mobile so the menu trigger keeps consistent sizing, truncation, and dropdown styling (#2124) (thanks @vyctorbrzezowski).
+- Web: constrain settings, profile content, skill detail, and plugin detail pages to the header content width while preserving profile hero bleed (thanks @vyctorbrzezowski).
+- Web: show publish-page validation next to the relevant fields and upload picker so invalid inputs are not buried below the form (#908) (thanks @AndyZhengyan).
+- Docs: remove README references to the inactive onlycrabs.ai domain while leaving the internal SoulHub configuration generic (#951) (thanks @muescha).
+- Docs/dev: document the local Convex site proxy URL and make worktree setup reject misconfigured local site URLs that break HTTP routes (#2060) (thanks @vyctorbrzezowski).
+- Dev setup: make local seed reset deterministic by cleaning stale seed lookup and badge rows for repeated Convex dev runs (#2057) (thanks @vyctorbrzezowski).
+
+## 0.12.3 - 2026-05-06
+
+### Fixes
+
+- CLI/API: allow skill publishes to target an org/user publisher with `--owner` / `ownerHandle`, and keep root `SKILL.md` publishable even when broad ignore rules match Markdown files (thanks @deepujain).
+- Packages: expose owned plugin/package soft-delete in the CLI and dashboard, keep moderator takedown access, and remove deleted packages from package search surfaces (thanks @Patrick-Erichsen).
+- Packages: support monorepo package publishes, infer package owners from scoped names, and keep dry-run publishes metadata-only.
+- Packages: validate code-plugin runtime entries against extracted files, allow admin plugin release publishes, and raise trusted-publish/admin API rate limits for legitimate publish bursts.
+- API/Search: return lean skill list payloads, route package search through digest indexes, decode scoped package paths, and bound fallback scans to reduce production read pressure.
+- Web: restore skill downloads and search paging, canonicalize scoped plugin paths, and improve mobile layout responsiveness.
+- Security: add scanner checks for confirmation bypasses and Python file upload exfiltration while reducing generic false-positive package tags.
+
+## 0.12.2 - 2026-05-02
+
+### Fixes
+
+- CLI: publish code plugins as clawpacks and allow legacy package downloads to keep older install flows working.
+- API: resolve scoped package routes and accept scoped npm packuments.
+- Schema: allow nullable package SHA values in package responses and refresh generated schema artifacts.
+
+## 0.12.1 - 2026-05-02
+
+### Added
+
+- Packages: add clawpack parsing, uploads, mirror artifact routes, artifact downloads, release moderation, reports, appeals, and official migration management across API, dashboard, and CLI.
+- Security: add ClawScan security surfaces, owner rescan guidance, scanner-specific report pages, security dataset snapshots, and redacted skill-content exports.
+- CLI: add unban support, moderation diagnostics in `inspect`, manual skill-directory listing, package environment filters, and package migration-status commands.
+- Web: add skills/plugins search typeahead, featured plugin curation, plugin management tools, skill upload shortcuts, and dashboard pagination.
+
+### Fixes
+
+- API: raise public read rate limits to reduce false-positive 429s from browser pages and production smoke tests (thanks @steipete).
+- CLI/moderation: allow `delete`, `hide`, `undelete`, and `unhide` to record moderation reasons in skill notes and audit logs for legal or policy reviews (thanks @steipete).
+- Packages: make package publish retries idempotent, constrain catalog queries, keep package list queries single-page, count package archive downloads, and keep beta plugin packages off `latest`.
+- Search: add soul lexical fallback, non-suspicious digest indexes, normalized skill prefix recall, and more stable relevance recall windows.
+- Security: broaden static scanner coverage for unsafe credential, subprocess, browser-file, provider-secret, and remote-recipe patterns while hardening prompt-boundary handling.
+- Deploy/CI: harden production smoke checks, expand PR validation coverage, add dead-code gates, and stabilize CodeQL light coverage.
+- Dependencies: pin `undici` on the Node 20-compatible line after reverting the incompatible v8 update.
+
+## 0.12.0 - 2026-04-28
+
+### Added
+
+- Security: add owner rescan requests, owner flagged inventory, scanner-specific security pages, and in-progress scan states.
+- UI: adopt shadcn-managed primitives and polish the rescan/security surfaces for mobile.
+
+### Fixes
+
+- Moderation: calibrate VirusTotal Code Insight suspicious verdicts so uncorroborated AI-only findings do not keep otherwise clean skills quarantined (#1830, #1841) (thanks @deepujain).
+- Security: flag exposed secrets in skill docs and normalize VirusTotal engine stats before caching.
+- Packages: constrain plugin catalog queries and avoid catalog/package-list query limits.
+- Auth: tolerate stale auth state when reading star status.
+- CI: harden and debounce ClawSweeper dispatch workflows and fix production smoke coverage.
+
+## 0.11.0 - 2026-04-28
+
+### Changed
+
+- Docs: clarify that ClawHub does not support paid skills, per-skill pricing, or paywalled releases (#1752, #1844) (thanks @deepujain).
+- API docs: clarify how third-party directories can reuse public ClawHub catalog endpoints while respecting rate limits and canonical links (#1825, #1845) (thanks @deepujain).
+- Packages docs: document the required fields for code-plugin package publish flows (#1802) (thanks @deepujain).
+- Search: add CJK tokenization support (Chinese/Japanese/Korean) with Intl.Segmenter plus fallback behavior to improve skill query matching (#1596) (thanks @pq-dong).
+- Stats: centralize migrated skill stat fallback reads through `readCanonicalStat()` and add schema/agent guardrails to discourage direct legacy nested-field access (#1709) (thanks @momothemage).
+
+### Fixes
+
+- Packages: use the configured `GITHUB_TOKEN` for trusted-publisher repository identity lookups to avoid anonymous GitHub API rate limits during publish setup (#1820, #1846) (thanks @deepujain).
+- Packages: keep package search fallback scans bounded, stop scanning after the requested result limit, and keep direct plugin-name matches scoped to the requested package family (OpenClaw #64025).
+- Moderation: stop flagging declared env vars sent to their intended API while preserving broad env scraping and exfiltration findings (#1803) (thanks @deepujain).
+- Moderation: stop treating generic webhook integration docs as suspicious unless they include explicit Discord or Slack webhook endpoints (#1716) (thanks @langningchen-openclaw).
+- Search: increase initial vector candidate pools and align CLI search's default limit with the web UI so high-scoring matches are not missed at small limits (#1375, #1429) (thanks @tjefferson).
+- Search: fall back to lexical skill search when embedding generation fails instead of returning empty skill results (#1291) (thanks @goulonghui).
+- Search: rank exact slug matches above longer slugs that merely contain all query tokens (#1130) (thanks @QuinnH496).
+- Search: widen lexical fallback coverage and scan recently created skills so newly published skills can be found before embeddings rank well (#1185, #1200) (thanks @thirumaleshp).
+- Search: preserve vector scores across candidate expansion and require all query tokens to match exact-token filters so relevant skills are not crowded out (#1759, #1762) (thanks @LinPower).
+- Stats maintenance: keep skill stat migration fields synchronized by treating top-level stat fields as canonical during backfill/reconcile fallback reads (#1704) (thanks @momothemage).
+- Skill install: render OpenClaw CLI commands with the bare slug that the current CLI accepts (#1807).
+- Skills: keep historical tags out of public skill detail surfaces while preserving manager visibility (#1804) (thanks @deepujain).
+- Skills moderation: keep hash-based scanner callbacks from overwriting skill-level moderation for older versions (#1805) (thanks @deepujain).
+- Skills: prevent backport publishes from clobbering `latest` state and guard malformed persisted latest semver values during publish comparisons (#1832) (thanks @momothemage).
+
+## 0.10.0 - 2026-04-05
+
+### Added
+
+- Design system: introduce a shared UI component library (`src/components/ui/`) built on Radix UI primitives — Button, Card, Badge, Tabs, Dialog, Input, Textarea, Label, Select, Avatar, Separator, Tooltip, ScrollArea, Sheet, Skeleton, and Table — following the shadcn/ui pattern with `cn()` + Tailwind utilities.
+- Design system: `Button` supports `asChild` via Radix Slot for polymorphic rendering (e.g., wrapping `<Link>` without extra DOM).
+- Layout: add `Container` component with `narrow` / `default` / `wide` size presets and `Breadcrumb` component for hierarchical navigation.
+- Loading: add skeleton loading states (`SkillCardSkeleton`, `SkillDetailSkeleton`, `DashboardSkeleton`) replacing text-based "Loading..." indicators with animated placeholders.
+- Errors: add `ErrorBoundary` with `resetKey` prop that auto-resets on route changes, wired into the root layout.
+- Errors: surface fallback messages from Convex API error payloads in mutation/action error toasts.
+- UX: add `EmptyState` component with icon, headline, description, and optional CTA action used across dashboard, stars, profile, and publish pages.
+- UX: add confirmation dialogs for destructive skill ownership actions (transfer, abandon).
+- Markdown: add `MarkdownPreview` component with `react-markdown`, `remark-gfm`, and `react-syntax-highlighter` for rich rendering of skill/plugin READMEs with syntax-highlighted code blocks, GFM tables, and task lists.
+- Markdown: render tables with the new `Table` UI primitive for consistent styling across skill docs.
+- Navigation: replace DropdownMenu-based mobile nav with a slide-out `Sheet` panel.
+- Validation: add Zod schemas (`src/lib/schemas.ts`) for publish-skill, settings, report, and org forms.
+- Management: restore capability-tags UI (crypto, requires-wallet, can-make-purchases, etc.) that was silently removed during the initial refactor.
+- Management: add `.catch()` error handling with toast feedback on `setSoftDeleted` calls; prompt for hide/restore reasons.
+
+### Changed
+
+- CSS: migrate from a monolithic 5,161-line `styles.css` to Tailwind utilities on components, pruning CSS to ~1,000 lines (81% reduction). Dark mode now uses Tailwind `dark:` variants via a `@variant dark` directive bridging existing CSS custom properties.
+- Tailwind: add `@theme` block mapping all CSS design tokens (`--bg`, `--surface`, `--ink`, `--accent`, `--line`, `--radius-*`, etc.) into first-class Tailwind utilities.
+- Pages: modernize all route pages (home, skills browse, skill detail, dashboard, settings, publish-skill, publish-plugin, import, about, CLI auth, stars, souls, user profile, org profile, management, plugins browse, plugin detail) from CSS class selectors to Tailwind + UI primitives.
+- Skills browse: widen container to `wide` (1400px) for better use of screen space on desktop; same for plugins browse.
+- Skills browse: replace text-based filter toggles with pill chips and modernize toolbar layout.
+- Skill detail: migrate tab controls from CSS-styled buttons to Radix `Tabs` primitive with proper `role="tab"` accessibility.
+- Skill detail: replace inline CSS class-based install card with `SkillInstallCard` using Card + Button primitives.
+- Header/Footer: migrate from CSS classes to Tailwind utilities with responsive Sheet-based mobile navigation.
+- Dashboard: replace CSS table layout with `Table` UI primitive; add metric cards and skeleton loading.
+- Settings: modernize form inputs with `Input`/`Textarea`/`Label` primitives and structured layout.
+- Publish: use `Dialog` primitive for modals; inline validation indicators; modernized file list display.
+
+### Fixed
+
+- Auth: `EmptyState` "Sign in" button on publish page now triggers GitHub OAuth via `useAuthActions` instead of linking to non-existent `/signin` route.
+- API: fix plugins page dev-mode `{"error":"Only HTML requests are supported here"}` by routing SSR and localhost API fetches directly to the Convex site URL instead of through TanStack Start's request pipeline.
+- API: fix CORS error when `credentials: "include"` conflicts with `Access-Control-Allow-Origin: *` by making credentials conditional on same-origin requests.
+- API: fix SSR `packageApiUrl` to always use `VITE_CONVEX_SITE_URL` directly, avoiding `getRequestUrl()` failures when SSR request context is unavailable.
+- Management: restore `setSoftDeleted` reason parameter for hide/restore actions.
+- Tests: rename `settings.test.tsx` to `-settings.test.tsx` to exclude from TanStack Router's file-based route discovery.
+- Tests: add `@convex-dev/auth/react` mock for `useAuthActions` in upload route tests.
+- Tests: update skill detail tests for Radix tab roles (`role="tab"` instead of `role="button"`), skeleton loading classes (`animate-pulse`), and capability tag data.
+- Tests: update skills index tests for refreshed UI copy (placeholder text, empty state wording, loading indicator patterns).
+- Tests: update SkillDiffCard tests for Tailwind active-tab class (`shadow-sm` replacing `.is-active`).
+- Tests: update packages publish route tests for Tailwind border classes.
+- Tests: update packageApi tests for conditional credentials and SSR URL resolution.
+
+## 0.9.0 - 2026-03-23
+
+### Added
+
+- Packages/Plugins: add a first-class OpenClaw package registry across the web app, CLI, and HTTP API. ClawHub now supports package browse/search/detail/version/file/download flows plus `clawhub package explore`, `clawhub package inspect`, and `clawhub package publish` for `skill`, `code-plugin`, and `bundle-plugin` packages. (#1093)
+- Packages/Install: package downloads now ship install-ready archives with a `package/` root, support nested files like `dist/index.js`, and work directly with OpenClaw plugin install flows.
+- Skills/Web: server-render public skill pages and OG assets for faster first loads, cleaner sharing previews, and better cache behavior.
+
+### Changed
+
+- Browse/Search: rebuild public browse/search around denormalized digests, one-shot HTTP fetches, and deterministic cursors so the homepage and `/skills` are faster, more cacheable, and less likely to hit stale-tab or pagination dead ends.
+- Search: default skill search to relevance, keep load-more retryable after fetch failures, and tighten package/skill catalog query paths to reduce inconsistent results under load.
+
+### Fixed
+
+- Packages/Auth: authenticated owners can now list, search, inspect, download, and read files from their own private packages instead of private packages being direct-URL-only. (#1093)
+- Packages/API: stabilize package latest-version pointers, cursor pagination, publish outputs, fallback release resolution, and app-origin auth handling so package publish/search/install flows stay reliable.
+- Visibility/API: prevent skills owned by deleted/banned users from showing up in public detail pages, browse/search results, or version API routes.
+- Skills/API: sanitize public skill and soul version/file reads so hidden or invalid version data does not leak through direct API access.
+- Skills/Web: keep Monaco compare layout toggles reliable while defaulting narrow screens to inline mode (#828) (thanks @geoffrey-xiao).
+
+## 0.8.0 - 2026-03-13
+
+### Added
+
+- Skills/Web: show skill owner avatar + handle on skill cards, lists, and detail pages (#312) (thanks @ianalloway).
+- Skills/Web: add file viewer for skill version files on detail page (#44) (thanks @regenrek).
+- CLI: add `uninstall` command for skills (#241) (thanks @superlowburn).
+- Skills/API/CLI: add ownership transfer workflow with request/list/accept/reject/cancel flows.
+- Skills/Web/API: surface platform/architecture labels and security evaluation results in v1 + inspect views (#499, #362).
+- API: add structured skill moderation responses plus `GET /api/v1/skills/{slug}/moderation` with redacted public evidence and full owner/staff detail (#334) (thanks @ArthurzKV).
+- Moderation: persist structured moderation snapshots (static scan + VT/LLM merged verdict, reason codes, and evidence) on skills and versions (#333) (thanks @ArthurzKV).
+- API: add scan security verification endpoint and non-suspicious filters (#820).
+- Users: add `trustedPublisher` flag and admin mutations to bypass pending-scan auto-hide for trusted publishers (#298) (thanks @autogame-17).
+- Moderation: add comment reporting with per-user active report caps, unique reporter/target enforcement, and auto-hide on the 4th unique report.
+- Moderation: add AI-driven comment scam backfill (`commentModeration:*`) with persisted verdict/confidence/explainer metadata and strict auto-ban for `certain_scam` + `high` confidence.
+- Admin: add manual unban for banned users (clears `deletedAt` + `banReason`, audit log entry). Revoked API tokens stay revoked.
+- Admin: bulk restore skills from GitHub backup; reclaim squatted slugs via v1 endpoints + internal tooling (#298) (thanks @autogame-17).
+- Moderation/Admin: add manual override audit tools for suspicious-skill review.
+- CI/Security: add TruffleHog pull-request scanning for verified leaked credentials (#505) (thanks @akses0).
+
+### Changed
+
+- Skills: make published skill licensing explicit and fixed to MIT-0; require publish consent, surface no-attribution messaging in web/CLI/API, and remove per-skill license metadata.
+- Skill metadata: support env vars, dependency declarations, author, and links in parsed manifest metadata + install UI (#360) (thanks @mahsumaktas).
+- Rate limiting: apply authenticated quotas by user bucket (vs shared IP), emit delay-based reset headers, and improve CLI 429 guidance/retries (#412) (thanks @lc0rp).
+- Skills: reserve deleted slugs for prior owners (90-day cooldown) to prevent squatting; add admin reclaim flow (#298) (thanks @autogame-17).
+- Moderation: ban flow soft-deletes owned skills (reversible) and removes them from vector search (#298) (thanks @autogame-17).
+- Security/docs: document comment reporting/auto-hide behavior alongside existing skill reporting rules.
+- Security/moderation: add bounded explainable auto-ban reasons for scam comments and protect moderator/admin accounts from automated bans.
+- Moderation: banning users now also soft-deletes their authored comments (skill + soul), including legacy cleanup on re-ban.
+- Quality gate: language-aware word counting (`Intl.Segmenter`) and new `cjkChars` signal to reduce false rejects for non-Latin docs.
+- Jobs: run skill stat event processing every 5 minutes (was 15).
+- Deploy: add frontend/backend drift detection plus hardened production smoke/deploy checks.
+- API performance: batch resolve skill/soul tags in v1 list/get endpoints (fewer action->query round-trips) (#112) (thanks @mkrokosz).
+- LLM helpers: centralize OpenAI Responses text extraction for changelog/summary/eval flows (#502) (thanks @ianalloway).
+- Search/listing performance: cut embedding hydration and badge read bandwidth via `embeddingSkillMap` + denormalized skill badges; shift stat-doc sync to low-frequency cron (#441) (thanks @sethconvex).
+- Search/listing performance: move public browse/search hydration onto `skillSearchDigest`, add non-suspicious index paths, and split trending rebuilds to stay under Convex document limits.
+
+### Fixed
+
+- API: accept legacy CLI publish payloads during the v1 migration (#815).
+- Auth/UI: surface OAuth callback failures in the web UI instead of swallowing them (#688).
+- Skills: allow ownership healing when the previous owner was deleted/banned, and sanitize owner data in public payloads (#689, #793).
+- CLI: validate explicit `install --force --version` targets before removing an existing local skill, preventing data loss when the requested version does not exist (#825) (thanks @jonathandeamer).
+- Skills/Web: debounce search URL updates on `/skills` to keep typing responsive, and cancel stale pending navigations on external query changes (#587) (thanks @neeravmakwana).
+- Upload: keep folder-picking enabled after page refresh by reapplying `webkitdirectory`/`directory` on the file input ref (#551) (thanks @MunemHashmi).
+- CLI publish: use a longer multipart upload timeout and normalize abort rejections into proper Errors (#550) (thanks @MunemHashmi).
+- CLI: forward optional auth tokens for `search` and `explore` against authenticated registries (#608) (thanks @artdaal).
+- CLI: respect `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` env vars for outbound registry requests, with troubleshooting docs (#363) (thanks @kerrypotter).
+- CLI: preserve registry base paths when composing API URLs for search/inspect/moderation commands (#486) (thanks @Liknox).
+- CLI: show manual URL guidance when automatic browser opening is unavailable; add regression tests for opener errors (#163) (thanks @aronchick).
+- API/CLI: expose skill security status in version inspect output, with schema wiring and CLI regression coverage (#362) (thanks @abutbul).
+- Moderation: remove over-broad keyword flags for common auth/payment/crypto terms so legitimate skills stop tripping regex prefilters (#273) (thanks @superlowburn).
+- Skills hard-delete: delete `commentReports` rows during moderation cleanup to avoid orphaned report records.
+- Comments: hide entries authored by deleted/deactivated users in `comments:listBySkill`.
+- Admin API: `POST /api/v1/users/reclaim` now performs non-destructive root-slug owner transfer
+  (preserves existing skill versions/stats/metadata) and clears active slug reservations.
+- VirusTotal: use shared AV-engine fallback verdict mapping for pending/backfill flows and keep undetected-only results pending (#591) (thanks @Shuai-DaiDai).
+- Skills/listing: keep non-suspicious browse pagination on one cursor family during `isSuspicious` backfill, and re-sync stale `latestVersionSummary` metadata fields (#572) (thanks @sethconvex).
+- PWA: update `manifest.json` branding so installed apps show the correct ClawHub name (#569) (thanks @Glucksberg).
+- Search/tests: cover soft-deleted skill filtering in vector hydration and lexical exact-slug fallback (#552) (thanks @MunemHashmi).
+- Docs/dev: fix local setup instructions for Node support, Convex env vars, frontend port, and post-seed stats refresh (#584) (thanks @jack-piplabs).
+- Docs/CLI: fix `explore` flag list indentation so `--limit` renders correctly in the command reference (#601) (thanks @gandli).
+- Skill metadata: parse top-level `requires.*`, `primaryEnv`, and homepage fallbacks for security review accuracy (#548) (thanks @MunemHashmi).
+- Users: sync handle on ensure when GitHub login changes (#293) (thanks @christianhpoe).
+- Users/Auth: throttle GitHub profile sync on login; also sync avatar when it changes (#312) (thanks @ianalloway).
+- Upload gate: fetch GitHub account age by immutable account ID (prevents username swaps) (#116) (thanks @mkrokosz).
+- VT fallback: activate only VT-pending hidden skills when scans are unavailable/stale; keep quality/scanner-blocked skills hidden (#300) (thanks @superlowburn).
+- API: return proper status codes for delete/undelete errors (#35) (thanks @sergical).
+- API: for owners, return clearer status/messages for hidden/soft-deleted skills instead of a generic 404.
+- Web: allow copying OpenClaw scan summary text (thanks @borisolver, #322).
+- HTTP/CORS: add preflight handler + include CORS headers on API/download errors; CLI: include auth token for owner-visible installs/updates (#146) (thanks @Grenghis-Khan).
+- CLI: clarify `logout` only removes the local token; token remains valid until revoked in the web UI (#166) (thanks @aronchick).
+- CLI: validate skill slugs used for filesystem operations (prevents path traversal) (#241) (thanks @superlowburn).
+- Skills: keep global sorting across pagination on `/skills` (thanks @CodeBBakGoSu, #98).
+- Skills: allow updating skill description/summary from frontmatter on subsequent publishes (#312) (thanks @ianalloway).
+- Skills/Web: prevent filtered pagination dead-ends and loading-state flicker on `/skills`; move highlighted browse filtering into server list query (#339) (thanks @Marvae).
+- Web: align `/skills` total count with public visibility and format header count (thanks @rknoche6, #76).
+- Skills/Web: centralize public visibility checks and keep `globalStats` skill counts in sync incrementally; remove duplicate `/skills` default-sort fallback and share browse test mocks (thanks @rknoche6, #76).
+- Moderation: clear stale `flagged.suspicious` flags when VirusTotal rescans improve to clean verdicts (#418) (thanks @Phineas1500).
+- API tests: lock `Retry-After` behavior to relative-delay semantics for v1 search 429s (#421) (thanks @apoorvdarshan).
+- CLI tests: assert 5xx HTTP responses still perform retry attempts before surfacing final error (#457) (thanks @YonghaoZhao722).
+- GitHub import: improve storage/publish failure errors with actionable context; add regression tests for error formatting (#512) (thanks @vassiliylakhonin).
+
+## 0.7.0 - 2026-02-16
+
+Reconstructed from the `clawhub@0.7.0` npm publish timestamp (`2026-02-16T05:02:25Z`) and the repo version bump commit (`e352309`).
+
+### Added
+
+- Skills/Web: show owner avatars/handles across cards, lists, and detail pages (#312) (thanks @ianalloway).
+- Skills/Web: add version file viewer on skill detail pages (#44) (thanks @regenrek).
+- CLI: add `uninstall` for installed skills (#241) (thanks @superlowburn).
+- Skills/Web: add non-suspicious browse filter, downloads-first browse defaults, and popular non-suspicious homepage sections.
+- Web: compact-format skill and soul stats, plus split page models for skills/detail rendering.
+- Skills: auto-generate missing summaries and add a resumable/self-scheduling summary backfill job.
+- Moderation/Admin: add anti-spam publish caps, trust-tier quality checks, empty-skill cleanup tooling, and stronger moderator UX.
+
+### Changed
+
+- HTTP/CLI: centralize CORS handling and allow tokenized owner-visible reads through the CLI (#296, #297).
+- API performance: batch resolve tags in v1 list/get flows to cut action-to-query round-trips (#112) (thanks @mkrokosz).
+- Quality gate: add language-aware word counting and tighten spam/quarantine handling around publish flows.
+
+### Fixed
+
+- Skills/Web: fix initial sort wiring, keep global ordering across pagination, prevent pagination dead-ends/flicker, and harden cursor recovery (#92, #98, #339).
+- CLI: normalize abort/timeout errors, secure config-file permissions, clarify logout semantics, and prefer `$HOME` for path resolution (#164, #166, #283, #286, #299).
+- API: return correct delete/undelete status codes and clearer soft-delete/owner-visible error responses (#35) (thanks @sergical).
+- Upload/Auth: gate publish ownership by immutable GitHub account ID and handle duplicate auth-user records safely.
+- Downloads/Search: harden download dedupe/rate limiting, improve SSR host awareness, and fix homepage/search regressions under legacy data.
+
 ## 0.6.1 - 2026-02-13

 ### Added
+
 - Security: add LLM-based security evaluation during skill publish.
 - Parsing: recognize `metadata.openclaw` frontmatter and evaluate all skill files for requirements.

 ### Changed
+
 - Performance: lazy-load Monaco diff viewer on demand (thanks @alexjcm, #212).
 - Search: improve recall/ranking with lexical fallback and relevance prioritization.
 - Moderation UX: collapse OpenClaw analysis by default; update spacing and default reasoning model.

 ### Fixed
+
 - Skills: fix initial `/skills` sort wiring so first page respects selected sort/direction (thanks @bpk9, #92).
 - Search/UI: add embedding request timeout and align `/skills` toolbar + list width (thanks @GhadiSaab, #53).
 - Upload gate: handle GitHub API rate limits and optional authenticated lookup token (thanks @superlowburn, #246).
@@ -24,16 +422,20 @@
 - Web: prevent horizontal overflow from long code blocks in skill pages (thanks @bewithgaurav, #183).

 ## 0.6.0 - 2026-02-10
+
 ### Added
+
 - CLI/API: add `set-role` to change user roles (admin only).
 - Security: quarantine skill publishes with VirusTotal scans + UI (thanks @aleph8, #130).
 - Testing: add tests for badges, skillZip, uploadFiles expandDroppedItems, and ark schema error truncation.
 - Moderation: add ban reasons to API/CLI and show in management UI.

 ### Changed
+
 - Coverage: track `convex/lib/skillZip.ts` in coverage reports.

 ### Fixed
+
 - Web: show pending-scan skills to owners without 404 (thanks @orlyjamie, #136).
 - Users: backfill empty handles from name/email in ensure (thanks @adlai88, #158).
 - Web: update footer branding to OpenClaw (thanks @jontsai, #122).
@@ -42,6 +444,7 @@
 ## 0.5.0 - 2026-02-02

 ### Added
+
 - Admin: ban users and delete owned skills from management console.
 - Moderation: auto-hide skills after 4 unique reports; per-user report cap; moderators can ban users.
 - Uploads: require GitHub accounts to be at least 7 days old for skill + soul publish/import.
@@ -50,25 +453,30 @@
 - Management: add filters for reported skills and users.

 ### Changed
+
 - Deps: update dependencies to latest available versions.
 - Reporting: require reasons, show them in management console, warn about abuse bans.

 ### Fixed
+
 - Bans: batch hard-delete cleanup to avoid Convex read limits on large skills.

 ## 0.4.0 - 2026-01-30

 ### Added
+
 - Web: show published skills on user profiles (thanks @njoylab, #20).
 - CLI: include ClawHub + Moltbot fallback skill roots for sync scans.
 - CLI: support OpenClaw configuration files (`OPENCLAW_CONFIG_PATH` / `OPENCLAW_STATE_DIR`).

 ### Changed
+
 - Brand: rebrand to ClawHub and publish CLI as `clawhub` (legacy `clawdhub` supported).
 - Domain: default site/registry now `https://clawhub.ai`; `.well-known/clawhub.json` preferred.
 - Theme: persist theme under `clawhub-theme` (legacy key still read).

 ### Fixed
+
 - Registry: drop missing skills during search hydration (thanks @aaronn, #28).
 - CLI: use path-based skill metadata lookup for updates (thanks @daveonkels, #22).
 - Search: keep highlighted-only filtering and clamp vector candidates to Convex limits (thanks @aaronn, #30).
@@ -76,6 +484,7 @@
 ## 0.3.0 - 2026-01-19

 ### Added
+
 - CLI: add `explore` command for latest updates, with limit clamping + tests/docs (thanks @jdrhyne, #14).
 - CLI: `explore --json` output + new sorts (`installs`, `installsAllTime`, `trending`) and limit up to 200.
 - API: `/api/v1/skills` supports installs + trending sorts (7-day installs).
@@ -83,17 +492,20 @@
 - Registry: trending leaderboard + daily stats backfill for installs-based sorts.

 ### Fixed
+
 - Web: keep search mode navigation and state in sync (thanks @NACC96, #12).

 ## 0.2.0 - 2026-01-13

 ### Added
+
 - Web: dynamic OG image cards for skills (name, description, version).
 - CLI: auto-scan Clawdbot skill roots (per-agent workspaces, shared skills, extraDirs).
 - Web: import skills from public GitHub URLs (auto-detect `SKILL.md`, smart file selection, provenance).
 - Web/API: SoulHub (SOUL.md registry) with v1 endpoints and first-run auto-seed.

 ### Fixed
+
 - Web: stabilize skill OG image generation on server runtimes.
 - Web: prevent skill OG text overflow outside the card.
 - Registry: make SoulHub auto-seed idempotent and non-user-owned.
@@ -103,18 +515,20 @@

 ## 0.0.6 - 2026-01-07

-
 ### Added
+
 - API: v1 public REST endpoints with rate limits, raw file fetch, and OpenAPI spec.
 - Docs: `docs/api.md` and `DEPRECATIONS.md` for the v1 cutover plan.

 ### Changed
+
 - CLI: publish now uses single multipart `POST /api/v1/skills`.
 - Registry: legacy `/api/*` + `/api/cli/*` marked for deprecation (kept for now).

 ## 0.0.5 - 2026-01-06

 ### Added
+
 - Telemetry: track installs via `clawhub sync` (logged-in only), per root, with 120-day staleness.
 - Skills: show current + all-time installs; sort by installs.
 - Profile: private "Installed" tab with JSON export + delete telemetry controls.
@@ -123,30 +537,36 @@
 - Web: dashboard for managing your published skills (thanks @dbhurley!).

 ### Changed
+
 - CLI: telemetry opt-out via `CLAWHUB_DISABLE_TELEMETRY=1`.
 - Web: move theme picker into mobile menu.

 ### Fixed
+
 - Web: handle shorthand hex colors in diff theme (thanks @dbhurley!).

 ## 0.0.5 - 2026-01-06

 ### Added
+
 - Maintenance: admin backfill to re-parse `SKILL.md` and repair stored summaries/parsed metadata.

 ### Fixed
+
 - CLI sync: ignore plural `skills.md` docs files when scanning for skills.
 - Registry: parse YAML frontmatter (incl multiline `description`) and accept YAML `metadata` objects.

 ## 0.0.4 - 2026-01-05

 ### Added
+
 - Web: `/skills` list view with sorting (newest/downloads/stars/name) + quick filter.
 - Web: admin/moderator highlight toggle on skill detail.
 - Web: canonical skill URLs as `/<owner>/<slug>` (legacy `/skills/<slug>` redirects).
 - Web: upload auto-generates a changelog via OpenAI when left blank (marked as auto-generated).

 ### Fixed
+
 - Web: skill detail shows a loading state instead of flashing "Skill not found".
 - Web: user profile shows avatar + loading state (no "User not found" flash).
 - Web: improved mobile responsiveness (nav menu, skill detail layout, install command overflow).
@@ -155,20 +575,24 @@
 - CLI: ignore legacy `auth.clawdhub.com` registry and prefer site discovery.

 ### Changed
+
 - Web: homepage search now expands into full search mode with live results + highlighted toggle.
 - CLI: sync no longer prompts for changelog; registry auto-generates when blank.

 ## 0.0.3 - 2026-01-04

 ### Added
+
 - CLI sync: concurrency flag to limit registry checks.
 - Home: install command switcher (npm/pnpm/bun).

 ### Changed
+
 - CLI sync: default `--concurrency` is now 4 (was 8).
 - CLI sync: replace boxed notes with plain output for long lists.

 ### Fixed
+
 - CLI sync: wrap note output to avoid terminal overflow; cap list lengths.
 - CLI sync: label fallback scans as fallback locations.
 - CLI package: bundle schema internally (no external `clawhub-schema` publish).
@@ -177,9 +601,11 @@
 ## 0.0.2 - 2026-01-04

 ### Added
+
 - CLI: delete/undelete commands for soft-deleted skills (owner/admin).

 ### Fixed
+
 - CLI sync: dedupe duplicate slugs across scan roots; skip duplicates to avoid double-publish errors.
 - CLI sync: show parsing progress while hashing local skills.
 - CLI sync: prompt only actionable skills; preselect all by default; list synced separately; condensed synced summary when nothing to sync.
@@ -192,6 +618,7 @@
 ## 0.0.1 - 2026-01-04

 ### Features
+
 - CLI auth: login/logout/whoami; browser loopback auth; token storage; site/registry discovery; config overrides.
 - CLI workflow: search, install, update (single/all), list, publish, sync (scan workdir + legacy roots), dry-run, version bumping, tags.
 - Registry/API: skills + versions with semver; tags (latest + custom); changelog per version; SKILL.md frontmatter parsing; text-only validation; zip download; hash resolve; stats (downloads/stars/versions/comments).
@@ -0,0 +1,57 @@
+# ClawHub — Project Rules
+
+## Convex Performance Rules
+
+- For public listing/browse pages, use `ConvexHttpClient.query()` (one-shot fetch),
+  not `useQuery`/`usePaginatedQuery` (reactive subscription). Reserve reactive
+  queries for data the user needs to see update in real time.
+- Denormalize hot read paths into a single lightweight "digest" table. Every
+  `ctx.db.get()` join adds a table to the reactive invalidation scope.
+- When a `skillSearchDigest` row is available, use `digestToOwnerInfo(digest)`
+  to resolve owner data. NEVER call `ctx.db.get(ownerUserId)` when digest
+  owner fields (`ownerHandle`, `ownerName`, `ownerDisplayName`, `ownerImage`)
+  are already present. Reading from `users` adds the entire table to the
+  reactive read set and wastes bandwidth.
+- Use `convex-helpers` Triggers to sync denormalized tables automatically.
+  Always add change detection — skip the write if no fields actually changed.
+- Use compound indexes instead of JS filtering. If you're filtering docs after
+  the query, you're scanning documents you'll throw away.
+- For search results scored by computed values (vector + lexical + popularity),
+  fetch all results once and paginate client-side. Don't re-run the full search
+  pipeline on "load more."
+- Backfills on reactively-subscribed tables need `delayMs` between batches.
+- Mutations that read >8 MB should use the Action → Query → Mutation pattern
+  to split reads across transactions.
+
+## Convex Conventions
+
+- All mutations import from `convex/functions.ts` (not `convex/_generated/server`)
+  to get trigger wrapping. Type imports still come from `convex/_generated/server`.
+- NEVER use `--typecheck=disable` on `npx convex deploy`.
+- Use `npx convex dev --once` to push functions once (not long-running watcher).
+
+## Production Release
+
+- Production deploys are manual-only. Merging to `main` does **not** deploy.
+- Start the GitHub Actions `Deploy` workflow from `main` with `gh workflow run deploy.yml --repo openclaw/clawhub --ref main`.
+- The workflow supports `full`, `backend`, and `frontend` targets.
+- `frontend` currently waits for the Vercel production deploy on the selected `main` SHA and then runs smoke checks. It does not trigger Vercel directly yet.
+- The workflow uses the `Production` environment for deploy secrets, but it does not wait for a separate approval.
+- Required prod secret: `CONVEX_DEPLOY_KEY` on the `Production` environment. Optional smoke secret: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`.
+- CLI npm releases are manual-only and tag-based through `ClawHub CLI NPM Release`. Stable tags only: `vX.Y.Z`. Run a `preflight_only=true` pass first, then rerun with the same tag plus `preflight_run_id` for the real publish.
+- Real CLI publishes wait at `npm-release` and rely on npm trusted publishing for `openclaw/clawhub` + `clawhub-cli-npm-release.yml` + `npm-release`.
+
+## Testing
+
+- Tests use `._handler` to call mutation handlers directly with mock `db` objects.
+- Mock `db` objects MUST include `normalizeId: vi.fn()` for trigger wrapper compatibility.
+
+<!-- convex-ai-start -->
+
+This project uses [Convex](https://convex.dev) as its backend.
+
+When working on Convex code, **always read `convex/_generated/ai/guidelines.md` first** for important guidelines on how to correctly use Convex APIs and patterns. The file contains rules that override what you may have learned about Convex from training data.
+
+Convex agent skills for common tasks can be installed by running `npx convex ai-files install`.
+
+<!-- convex-ai-end -->
@@ -0,0 +1,273 @@
+# Contributing to ClawHub
+
+Welcome! ClawHub is the public skill registry for [OpenClaw](https://github.com/openclaw/openclaw). We appreciate bug fixes, documentation improvements, and feature contributions.
+
+- **Questions?** Ask in [#clawhub on Discord](https://discord.gg/clawd).
+- **Bug fixes** — PRs are welcome.
+- **New features or architectural changes** — please start with a Discord conversation in #clawhub first so we can align on scope.
+
+## Local Development Setup
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) (Convex CLI runs via `bunx`, no global install needed)
+- [Node.js](https://nodejs.org/) v18, 20, 22, or 24 (required by the local Convex backend; v25+ is not yet supported)
+- [Worktrunk](https://github.com/max-sixty/worktrunk) (`wt`) for `bun run dev:worktree` and disposable/Codex worktrees. On macOS, `brew install worktrunk` is the quickest path; shell integration is optional.
+
+### Install and configure
+
+```bash
+bun install
+cp .env.local.example .env.local
+```
+
+Edit `.env.local` with the following values for **local Convex**:
+
+```bash
+# Frontend
+VITE_CONVEX_URL=http://127.0.0.1:3210
+VITE_CONVEX_SITE_URL=http://127.0.0.1:3211
+SITE_URL=http://localhost:3000
+
+# Convex Auth / HTTP routes
+CONVEX_SITE_URL=http://127.0.0.1:3211
+
+# Deployment used by `bunx convex dev`
+CONVEX_DEPLOYMENT=anonymous:anonymous-clawhub
+```
+
+Local Convex serves the function endpoint on port 3210 and HTTP routes (`/api/*` and auth callbacks) through the site proxy on port 3211.
+
+### GitHub OAuth App (for login)
+
+1. Go to [github.com/settings/developers](https://github.com/settings/developers) and create a new OAuth App.
+2. Set **Homepage URL** to `http://localhost:3000`.
+3. Set **Authorization callback URL** to `http://127.0.0.1:3211/api/auth/callback/github`.
+4. Copy the Client ID and generate a Client Secret.
+
+### Run the Convex backend
+
+Start the local Convex backend first — other setup steps depend on it:
+
+```bash
+bunx convex dev --typecheck=disable
+```
+
+### Set backend environment variables
+
+The Convex backend has its own env var store separate from `.env.local`. With the backend running, open a new terminal and set the required variables:
+
+```bash
+bunx convex env set AUTH_GITHUB_ID <your-client-id>
+bunx convex env set AUTH_GITHUB_SECRET <your-client-secret>
+bunx convex env set SITE_URL http://localhost:3000
+```
+
+### JWT keys (for Convex Auth)
+
+With the backend still running, generate the signing keys:
+
+```bash
+bunx @convex-dev/auth
+```
+
+This sets `JWT_PRIVATE_KEY` and `JWKS` on the Convex backend and outputs values you can also save to `.env.local` for reference.
+
+### Run the frontend
+
+```bash
+bun run dev -- --port 3000
+```
+
+Change the port if 3000 is already in use, and update `SITE_URL` in both `.env.local` and the Convex backend (`bunx convex env set SITE_URL ...`) to match.
+
+### Worktree/Codex fast path
+
+Use this path for disposable branches, Codex sessions, or parallel worktrees after one source worktree already has a working `.env.local` and `.convex` local Convex setup:
+
+```bash
+bun run setup:worktree
+bun run dev:worktree
+wt --yes url
+wt --yes stop
+```
+
+`setup:worktree` finds a usable source worktree and symlinks `.env.local` plus `.convex` into the current checkout. If discovery picks the wrong source, pass one explicitly:
+
+```bash
+bun run setup:worktree -- --from /path/to/source/worktree
+CLAWHUB_WORKTREE_SOURCE=/path/to/source/worktree bun run setup:worktree
+```
+
+`dev:worktree` is the Worktrunk entrypoint. It runs the hooks in `.config/wt.toml`, copies ignored dependencies listed in `.worktreeinclude` when possible, falls back to `bun install` if Vite is missing, and starts detached services on a branch-hashed loopback port. Use `wt --yes url` from the same worktree to print the URL.
+
+The detached server writes runtime state under `.codex/runtime/`. Stop it with `wt --yes stop` before removing the worktree.
+
+### Seed the database
+
+Populate local QA fixtures and the committed public corpus so the UI isn't empty:
+
+```bash
+bun run seed:dev
+```
+
+`seed:dev` runs worktree setup, starts or waits for local Convex, seeds the hand-authored local QA fixtures, imports the committed public corpus, and refreshes cached global stats. It is safe to rerun after fixture or schema changes.
+
+Lower-level seed commands are available for manual recovery or focused fixture work:
+
+```bash
+# local moderation/security fixtures only
+bunx convex run --no-push devSeed:seedLocalFixtures
+
+# committed public corpus only
+bun run seed:public-corpus
+
+# validate the committed public corpus fixture
+bun run validate:public-corpus
+
+# 50 extra skills for pagination testing (optional)
+bunx convex run --no-push devSeedExtra:seedExtraSkillsInternal
+
+# Refresh cached global stats after manual seeding
+bunx convex run --no-push statsMaintenance:updateGlobalStatsAction
+```
+
+To reset and re-seed:
+
+```bash
+bunx convex run --no-push devSeed:seedLocalFixtures '{"reset": true}'
+bun run seed:public-corpus -- --reset
+bunx convex run --no-push statsMaintenance:updateGlobalStatsAction
+```
+
+Without `OPENAI_API_KEY`, public corpus import still works, but semantic search quality degrades because embeddings fall back to zero vectors.
+
+### Worktree troubleshooting
+
+- `wt: command not found`: install Worktrunk, then rerun `bun run dev:worktree`. Manual `bun run dev` plus `bunx convex dev --typecheck=disable` still works without Worktrunk.
+- Missing `.env.local` or `.convex`: run `bun run setup:worktree -- --from /path/to/source/worktree`. The source must contain `.env.local` and, for local Convex deployments, `.convex/local/default/config.json`.
+- Wrong local Convex deployment: make sure `CONVEX_DEPLOYMENT` in `.env.local` matches the local Convex deployment in `.convex/local/default/config.json` when using a `local:` deployment.
+- Port mismatch: local Convex normally serves cloud functions at `http://127.0.0.1:3210` and HTTP routes/auth callbacks at `http://127.0.0.1:3211`. Keep `VITE_CONVEX_URL`, `VITE_CONVEX_SITE_URL`, and `CONVEX_SITE_URL` aligned with the local config.
+- `wt step copy-ignored` reports that `.convex` cannot be copied: this can happen when `.convex` is a symlink to the source worktree. The Worktrunk hook continues; confirm `.env.local`, `.convex`, and `node_modules/.bin/vite` exist before debugging deeper.
+- Local Convex functions are not queryable yet during seeding: leave `bunx convex dev --typecheck=disable` running or rerun `bun run seed:dev`; the seed runner retries while Convex finishes pushing functions.
+- Local seeding hits a transient Convex write conflict: `seed:public-corpus` retries retryable batch conflicts. If retries are exhausted, stop other local writers and rerun `bun run seed:dev`.
+- Stale detached services: run `wt --yes stop`, then inspect `.codex/runtime/dev-worktree.log` if the server still does not restart cleanly.
+
+### Optional environment variables
+
+These features degrade gracefully without their keys:
+
+| Variable                                                                  | Purpose                                                   |
+| ------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `OPENAI_API_KEY`                                                          | Embeddings and vector search (falls back to zero vectors) |
+| `VT_API_KEY`                                                              | VirusTotal malware scanning                               |
+| `DISCORD_WEBHOOK_URL`                                                     | Discord notifications                                     |
+| `GITHUB_APP_ID` / `GITHUB_APP_PRIVATE_KEY` / `GITHUB_APP_INSTALLATION_ID` | GitHub backup sync                                        |
+
+## CLI Development
+
+The CLI source lives in [`packages/clawhub/`](packages/clawhub/). Both `clawhub` and `clawdhub` are registered as bin aliases.
+
+To test the CLI against your local instance:
+
+```bash
+CLAWHUB_REGISTRY=http://127.0.0.1:3211 CLAWHUB_SITE=http://localhost:3000 clawhub search "padel"
+```
+
+Use the package-local verification contract when working on the CLI:
+
+```bash
+bun run --cwd packages/clawhub test
+bun run --cwd packages/clawhub verify:build
+bun run --cwd packages/clawhub test:artifact
+bun run --cwd packages/clawhub verify
+```
+
+`bun test packages/clawhub/` is not the supported workflow. Source tests and built-artifact smoke tests are intentionally split.
+
+Manual smoke tests are documented in [`specs/manual-testing.md`](specs/manual-testing.md).
+
+## Skill & Soul Publishing
+
+- Skill format reference: [`docs/skill-format.md`](docs/skill-format.md)
+- Soul format reference: [`docs/soul-format.md`](docs/soul-format.md)
+- End-to-end walkthrough (search, install, publish, sync): [`docs/quickstart.md`](docs/quickstart.md)
+
+Quick publish:
+
+```bash
+clawhub publish <path-to-skill-directory>
+```
+
+## Before Submitting a PR
+
+Run the narrowest meaningful check while iterating, then run the matching CI aliases before handoff:
+
+- All PRs: `bun run ci:static`.
+- Source or test changes: focused tests for the touched behavior plus `bun run ci:unit` unless the change is docs/config-only or a maintainer asks to rely on CI.
+- App runtime, Convex, or build changes: `bun run ci:types-build`.
+- Package changes: `bun run ci:packages`.
+- HTTP/API/CLI integration changes: `bun run ci:e2e-http`.
+- Browser smoke or visual behavior changes: `bun run ci:playwright-smoke`, `bun run test:pw:local-auth`, and/or `bun run proof:ui` depending on the touched flow.
+
+`bun run ci:pr` is the local aggregate for the non-browser PR gates. See [`specs/ci.md`](specs/ci.md) for the full CI contract.
+
+### Crabbox remote checks
+
+Maintainers can run the same checks in a Crabbox lease instead of spending local
+CPU. ClawHub uses Crabbox as the agent-facing command surface; the Testbox
+workflow is only the backend for the default Blacksmith provider.
+
+```bash
+bun run crabbox:warmup -- --provider blacksmith-testbox
+bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run lint"
+bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run test"
+bun run crabbox:run -- --provider blacksmith-testbox --shell -- "bun run build"
+```
+
+Use `--id <id-or-slug>` with `crabbox:run` when reusing an existing warmed lease,
+and stop disposable leases with `bun run crabbox:stop -- --provider <provider>
+<id-or-slug>`.
+Use `CLAWHUB_LOCAL_CHECK_MODE=throttled` or `CLAWHUB_LOCAL_CHECK_MODE=full` as
+the explicit local escape hatch when you intentionally want laptop-side proof.
+If Crabbox auth/provider access is missing, report that instead of falling back
+to a broad local gate that can bog down a dev machine.
+
+**PR guidelines:**
+
+- Keep PRs focused — one concern per PR.
+- Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:`, `docs:`, etc.
+- Include test commands and screenshots for UI changes.
+- Write a clear description of what changed and why.
+
+## AI-Generated Code
+
+AI-assisted contributions are welcome. When submitting AI-generated or AI-assisted code:
+
+- Note it in the PR description.
+- Describe the level of testing you applied.
+- Include prompts if useful for reviewers.
+- Confirm that you understand and can maintain the code.
+
+## Security Reporting
+
+Report vulnerabilities to **security@openclaw.ai** with:
+
+- Severity assessment
+- Technical reproduction steps
+- Suggested remediation
+
+See [`docs/security.md`](docs/security.md) for moderation and upload gating details.
+
+## Reading Order for New Contributors
+
+1. This file (local setup)
+2. [`docs/clawhub.md`](docs/clawhub.md) — public registry overview
+3. [`docs/quickstart.md`](docs/quickstart.md) — end-to-end workflows
+4. [`docs/architecture.md`](docs/architecture.md) — system design
+5. [`docs/skill-format.md`](docs/skill-format.md) — skill structure
+6. [`docs/cli.md`](docs/cli.md) — CLI reference
+7. [`docs/http-api.md`](docs/http-api.md) — HTTP endpoints
+8. [`docs/auth.md`](docs/auth.md) — authentication
+9. [`docs/deploy.md`](docs/deploy.md) — deployment
+10. [`docs/troubleshooting.md`](docs/troubleshooting.md) — common issues
@@ -0,0 +1,362 @@
+# ClawHub Design System
+
+This document outlines the design rules, patterns, and guidelines for the ClawHub platform to ensure consistency, accessibility, and maintainability across all components.
+
+---
+
+## Color System
+
+### Brand Palette (OpenClaw)
+
+ClawHub uses a strict **3-5 color palette** based on the OpenClaw brand:
+
+| Token           | Light Mode | Dark Mode | Usage                                           |
+| --------------- | ---------- | --------- | ----------------------------------------------- |
+| `--accent`      | `#dc2626`  | `#dc2626` | Primary actions, interactive elements, emphasis |
+| `--accent-deep` | `#b91c1c`  | `#ef4444` | Hover states, secondary emphasis                |
+| `--ink`         | `#0a0a0a`  | `#fafafa` | Primary text                                    |
+| `--ink-soft`    | `#525252`  | `#a1a1a1` | Secondary text, descriptions                    |
+| `--surface`     | `#ffffff`  | `#121212` | Card backgrounds, elevated surfaces             |
+| `--bg`          | `#fafafa`  | `#0a0a0a` | Page background                                 |
+
+### Rules
+
+1. **Never exceed 5 colors** without explicit design approval
+2. **Never use purple/violet prominently** unless explicitly requested
+3. **Always override text color** when changing background color to ensure contrast
+4. **Use semantic tokens** (`--accent`, `--ink`, `--surface`) instead of raw colors
+
+---
+
+## Typography
+
+### Font Stack
+
+```css
+--font-sans: "Geist", system-ui, sans-serif;
+--font-mono: "Geist Mono", monospace;
+--font-display: "Geist", system-ui, sans-serif;
+```
+
+### Scale
+
+| Token       | Size            | Usage                    |
+| ----------- | --------------- | ------------------------ |
+| `--fs-xs`   | 0.75rem (12px)  | Labels, badges, metadata |
+| `--fs-sm`   | 0.875rem (14px) | Body text, descriptions  |
+| `--fs-base` | 1rem (16px)     | Default body text        |
+| `--fs-md`   | 1.125rem (18px) | Subheadings              |
+| `--fs-lg`   | 1.25rem (20px)  | Section titles           |
+| `--fs-xl`   | 1.5rem (24px)   | Page headings            |
+
+### Rules
+
+1. **Maximum 2 font families** per page
+2. **Line height 1.4-1.6** for body text (use `leading-relaxed`)
+3. **Never use decorative fonts** for body text
+4. **Minimum font size: 14px** for readability
+5. Use `text-balance` or `text-pretty` for titles
+
+---
+
+## Layout
+
+### Method Priority
+
+Use this hierarchy for layout decisions:
+
+1. **Flexbox** - Default for most layouts
+2. **CSS Grid** - Only for complex 2D layouts (cards, galleries)
+3. **Never use floats** or absolute positioning unless absolutely necessary
+
+### Spacing Scale
+
+```css
+--space-1: 0.25rem /* 4px */ --space-2: 0.5rem /* 8px */ --space-3: 0.75rem /* 12px */
+  --space-4: 1rem /* 16px */ --space-5: 1.5rem /* 24px */ --space-6: 2rem /* 32px */;
+```
+
+### Grid Patterns
+
+#### Auto-fit Grid (Recommended for Cards)
+
+```css
+grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+```
+
+- Automatically adjusts columns based on container width
+- Prevents orphan items on partial rows
+- Maintains consistent card widths
+
+#### Fixed Grid (When exact columns needed)
+
+```css
+/* 3-column at desktop, 2 at tablet, 1 at mobile */
+grid-template-columns: repeat(3, minmax(0, 1fr));
+
+@media (max-width: 860px) {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+@media (max-width: 520px) {
+  grid-template-columns: 1fr;
+}
+```
+
+### Container Widths
+
+| Size    | Max Width               | Usage                   |
+| ------- | ----------------------- | ----------------------- |
+| Default | `--page-max` (1200px)   | Standard pages          |
+| Narrow  | `--page-narrow` (720px) | Reading content, forms  |
+| Wide    | Full width              | Dashboards, data tables |
+
+---
+
+## Components
+
+### Cards
+
+```css
+.card {
+  padding: var(--space-4);
+  border: 1px solid var(--line);
+  border-radius: var(--r-md);
+  background: var(--surface);
+}
+```
+
+**Rules:**
+
+- Always use `display: flex; flex-direction: column;` for consistent height
+- Add `flex: 1` to content area for equal-height cards in grids
+- Include hover state with `border-color` and subtle `box-shadow`
+
+### Buttons
+
+| Variant       | Usage                                 |
+| ------------- | ------------------------------------- |
+| `primary`     | Main actions (Submit, Save, Download) |
+| `secondary`   | Alternative actions                   |
+| `ghost`       | Tertiary actions, navigation          |
+| `destructive` | Delete, remove, dangerous actions     |
+
+**Rules:**
+
+- Always include visible focus state
+- Minimum touch target: 44x44px on mobile
+- Include `aria-label` when icon-only
+
+### Form Controls
+
+- Labels above inputs (not inline)
+- Error states use `--status-error-fg`
+- Focus rings use `--accent` with 0.2 opacity
+- Minimum input height: 40px
+
+---
+
+## Responsive Breakpoints
+
+```css
+/* Mobile first - base styles for mobile */
+
+@media (min-width: 520px) {
+  /* Small tablets, large phones */
+}
+
+@media (min-width: 640px) {
+  /* Tablets */
+}
+
+@media (min-width: 860px) {
+  /* Small desktops, landscape tablets */
+}
+
+@media (min-width: 1024px) {
+  /* Desktops */
+}
+
+@media (min-width: 1280px) {
+  /* Large desktops */
+}
+```
+
+### Rules
+
+1. **Mobile-first approach** - Base styles target mobile
+2. **Progressive enhancement** - Add complexity as viewport increases
+3. **Test intermediate breakpoints** - Avoid jarring layout jumps
+4. **Never hide critical content** on mobile
+
+---
+
+## Accessibility
+
+### Color Contrast
+
+- Normal text: Minimum 4.5:1 ratio
+- Large text (18px+): Minimum 3:1 ratio
+- Interactive elements: Minimum 3:1 ratio
+
+### Focus States
+
+```css
+:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+  border-radius: 2px;
+}
+```
+
+### Screen Readers
+
+- Use `sr-only` class for visually hidden but accessible text
+- Always include `alt` text for images (empty `alt=""` for decorative)
+- Use semantic HTML elements (`main`, `nav`, `article`, `section`)
+- Proper heading hierarchy (h1 > h2 > h3, no skipping)
+
+### Motion
+
+```css
+/* Respect user preference */
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Animation
+
+### Timing
+
+```css
+--transition-fast: 150ms;
+--transition-base: 200ms;
+--transition-slow: 300ms;
+```
+
+### Easing
+
+- Use `ease` or `ease-out` for most transitions
+- Use `ease-in-out` for enter/exit animations
+- Never use `linear` except for continuous animations
+
+### Rules
+
+1. **Subtle by default** - Avoid flashy animations
+2. **Purpose-driven** - Animation should provide feedback
+3. **Respect preferences** - Support `prefers-reduced-motion`
+4. **Performance** - Use `transform` and `opacity` only
+
+---
+
+## Icons
+
+### Usage
+
+- Use Lucide icons consistently
+- Standard sizes: 14px, 16px, 20px, 24px
+- Include `aria-hidden="true"` for decorative icons
+- Never use emojis as icons
+
+### Placement
+
+- Left of labels in buttons and navigation
+- Right of labels for external links or dropdowns
+- Centered when used alone with `aria-label`
+
+---
+
+## Dark Mode
+
+### Implementation
+
+```css
+[data-theme="dark"] {
+  /* Dark mode overrides */
+}
+```
+
+### Rules
+
+1. Never use pure white (`#ffffff`) on dark backgrounds
+2. Reduce shadow intensity in dark mode
+3. Adjust image brightness if needed
+4. Test contrast ratios in both modes
+
+---
+
+## Performance
+
+### CSS
+
+1. Use CSS custom properties for theming
+2. Avoid deeply nested selectors (max 3 levels)
+3. Use `will-change` sparingly
+4. Prefer `transform` over `top/left` for animations
+
+### Images
+
+1. Always specify `width` and `height` attributes
+2. Use `loading="lazy"` for below-fold images
+3. Use appropriate formats (WebP with fallbacks)
+4. Include placeholder or skeleton states
+
+---
+
+## Code Style
+
+### CSS Class Naming
+
+```css
+/* Component */
+.component-name {
+}
+
+/* Component modifier */
+.component-name.variant {
+}
+
+/* Component child */
+.component-name-child {
+}
+
+/* State */
+.component-name.is-active {
+}
+.component-name[data-state="open"] {
+}
+```
+
+### File Organization
+
+```
+src/
+  components/
+    ui/           # Primitive components (Button, Input, Card)
+    layout/       # Layout components (Container, Header)
+  styles.css      # Global styles and design tokens
+  lib/
+    theme.ts      # Theme utilities
+    preferences.ts # User preference management
+```
+
+---
+
+## Checklist
+
+Before shipping any UI changes, verify:
+
+- [ ] Color contrast meets WCAG AA standards
+- [ ] Focus states are visible
+- [ ] Layout works at all breakpoints
+- [ ] Animations respect `prefers-reduced-motion`
+- [ ] Text is readable at default browser zoom
+- [ ] Interactive elements have 44px minimum touch target
+- [ ] Semantic HTML is used appropriately
+- [ ] Dark mode has been tested
@@ -1,4 +1,10 @@
-# ClawHub
+<p align="center">
+  <img src="public/clawd-logo.png" alt="ClawHub" width="120">
+</p>
+
+![ClawHub banner](docs/assets/readme-banner.jpg)
+
+<h1 align="center">ClawHub</h1>

 <p align="center">
  <a href="https://github.com/openclaw/clawhub/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/openclaw/clawhub/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
@@ -6,29 +12,31 @@
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
 </p>

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

-onlycrabs.ai is the **SOUL.md registry**: publish and share system lore the same way you publish skills.
-
-Live: `https://clawhub.ai`
-onlycrabs.ai: `https://onlycrabs.ai`
+<p align="center">
+  <a href="https://clawhub.ai">ClawHub</a> ·
+  <a href="VISION.md">Vision</a> ·
+  <a href="docs/clawhub.md">Docs</a> ·
+  <a href="CONTRIBUTING.md">Contributing</a> ·
+  <a href="https://discord.gg/clawd">Discord</a>
+</p>

 ## What you can do with it

 - Browse skills + render their `SKILL.md`.
 - Publish new skill versions with changelogs + tags (including `latest`).
+- Rename an owned skill without breaking old links or installs.
+- Merge duplicate owned skills into one canonical slug.
 - Browse souls + render their `SOUL.md`.
 - Publish new soul versions with changelogs + tags.
 - Search via embeddings (vector index) instead of brittle keywords.
 - Star + comment; admins/mods can curate and approve skills.
-
-## onlycrabs.ai (SOUL.md registry)
-
- Entry point is host-based: `onlycrabs.ai`.
- On the onlycrabs.ai host, the home page and nav default to souls.
- On ClawHub, souls live under `/souls`.
- Soul bundles only accept `SOUL.md` for now (no extra files).
+- Pin local skill installs so updates and force reinstalls cannot overwrite frozen copies.
+- Browse OpenClaw packages with family/trust/capability metadata.
+- Publish native code plugins and bundle plugins through `/packages` APIs and CLI flows.

 ## How it works (high level)

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

+## CLI
+
+Common CLI flows:
+
+- Auth: `clawhub login`, `clawhub whoami`
+- Remote/headless auth: `clawhub login --device`
+- Discover: `clawhub search ...`, `clawhub explore`
+- Browse unified catalog (skills + plugins): `clawhub package explore`, `clawhub package inspect <name>`
+- Manage local installs: `clawhub install <slug>`, `clawhub pin <slug>`, `clawhub unpin <slug>`, `clawhub uninstall <slug>`, `clawhub list`, `clawhub update --all`
+- Inspect without installing: `clawhub inspect <slug>`
+- Publish/sync skills: `clawhub skill publish <path>`, `clawhub sync`
+- Publish plugins: `clawhub package publish <source>`
+- Code-plugin manifests must include `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion`; see [`docs/cli.md`](docs/cli.md) for a minimal example.
+- Canonicalize owned skills: `clawhub skill rename <slug> <new-slug>`, `clawhub skill merge <source> <target>`
+
+Docs: [`docs/quickstart.md`](docs/quickstart.md), [`docs/cli.md`](docs/cli.md).
+
+### Removal permissions
+
+- `clawhub uninstall <slug>` only removes a local install on your machine.
+- Uploaded registry skills use soft-delete/restore (`clawhub delete <slug>` / `clawhub undelete <slug>` or API equivalents).
+- Soft-delete/restore is allowed for the skill or package owner, publisher owner/admin, moderators, and admins.
+- Packages use `clawhub package delete <name>` / `clawhub package undelete <name>`.
+- Hard delete is admin-only (management tools / ban flows).
+- Owner rename keeps the old slug as a redirect alias.
+- Owner merge hides the source listing and redirects the old slug to the canonical target.

 ## Telemetry

@@ -47,46 +81,52 @@ Disable via:
 export CLAWHUB_DISABLE_TELEMETRY=1
 ```

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

 ## Repo layout

 - `src/` — TanStack Start app (routes, components, styles).
 - `convex/` — schema + queries/mutations/actions + HTTP API routes.
 - `packages/schema/` — shared API types/routes for the CLI and app.
- `docs/spec.md` — product + implementation spec (good first read).
+- [`docs/`](docs/README.md) — publishable ClawHub public/operator docs for users, publishers, API clients, and deploy operators.
+- [`specs/`](specs/README.md) — product specs, plans, regression notes, and design history.
+- [`specs/spec.md`](specs/spec.md) — product + implementation spec (good first read for maintainers).

 ## Local dev

-Prereqs: Bun + Convex CLI.
+Prereqs: [Bun](https://bun.sh/) (Convex runs via `bunx`, no global install needed). The detached worktree path also requires [Worktrunk](https://github.com/max-sixty/worktrunk) (`wt`).

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

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

-# terminal B: Convex dev deployment
-bunx convex dev
+# detached/Codex worktree preview
+bun run setup:worktree
+bun run dev:worktree
+wt --yes url
+
+# seed local QA fixtures and the public corpus
+bun run seed:dev
 ```

-## Auth (GitHub OAuth) setup
-
-Create a GitHub OAuth App, set `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET`, then:
-
-```bash
-bunx auth --deployment-name <deployment> --web-server-url http://localhost:3000
-```
-
-This writes `JWT_PRIVATE_KEY` + `JWKS` to the deployment and prints values for your local `.env.local`.
+`bun run seed:dev` waits for the local Convex deployment, runs the dev fixture seed, and refreshes
+global stats. The fixtures are owned by `@local` and are safe to rerun after fixture or schema
+changes. For reset/manual commands and full setup instructions (env vars, GitHub OAuth, JWT keys,
+database seeding), see [CONTRIBUTING.md](CONTRIBUTING.md).

 ## Environment

 - `VITE_CONVEX_URL`: Convex deployment URL (`https://<deployment>.convex.cloud`).
 - `VITE_CONVEX_SITE_URL`: Convex site URL (`https://<deployment>.convex.site`).
- `VITE_SOULHUB_SITE_URL`: onlycrabs.ai site URL (`https://onlycrabs.ai`).
- `VITE_SOULHUB_HOST`: onlycrabs.ai host match (`onlycrabs.ai`).
+- `VITE_SOULHUB_SITE_URL`: SoulHub site URL.
+- `VITE_SOULHUB_HOST`: SoulHub host match.
 - `VITE_SITE_MODE`: Optional override (`skills` or `souls`) for SSR builds.
 - `CONVEX_SITE_URL`: same as `VITE_CONVEX_SITE_URL` (auth + cookies).
 - `SITE_URL`: App URL (local: `http://localhost:3000`).
@@ -106,7 +146,17 @@ Add this to `SKILL.md`:
 ---
 name: peekaboo
 description: Capture and automate macOS UI with the Peekaboo CLI.
-metadata: {"clawdbot":{"nix":{"plugin":"github:clawdbot/nix-steipete-tools?dir=tools/peekaboo","systems":["aarch64-darwin"]}}}
+metadata:
+  {
+    "clawdbot":
+      {
+        "nix":
+          {
+            "plugin": "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo",
+            "systems": ["aarch64-darwin"],
+          },
+      },
+  }
 ---
 ```

@@ -124,7 +174,18 @@ You can also declare config requirements + an example snippet:
 ---
 name: padel
 description: Check padel court availability and manage bookings via Playtomic.
-metadata: {"clawdbot":{"config":{"requiredEnv":["PADEL_AUTH_FILE"],"stateDirs":[".config/padel"],"example":"config = { env = { PADEL_AUTH_FILE = \\\"/run/agenix/padel-auth\\\"; }; };"}}}
+metadata:
+  {
+    "clawdbot":
+      {
+        "config":
+          {
+            "requiredEnv": ["PADEL_AUTH_FILE"],
+            "stateDirs": [".config/padel"],
+            "example": "config = { env = { PADEL_AUTH_FILE = \\\"/run/agenix/padel-auth\\\"; }; };",
+          },
+      },
+  }
 ---
 ```

@@ -134,7 +195,7 @@ To show CLI help (recommended for nix plugins), include the `cli --help` output:
 ---
 name: padel
 description: Check padel court availability and manage bookings via Playtomic.
-metadata: {"clawdbot":{"cliHelp":"padel --help\\nUsage: padel [command]\\n"}}
+metadata: { "clawdbot": { "cliHelp": "padel --help\\nUsage: padel [command]\\n" } }
 ---
 ```

@@ -142,7 +203,7 @@ metadata: {"clawdbot":{"cliHelp":"padel --help\\nUsage: padel [command]\\n"}}

 ## Skill metadata

-Skills declare their runtime requirements (env vars, binaries, install specs) in the `SKILL.md` frontmatter. ClawHub's security analysis checks these declarations against actual skill behavior.
+Skills declare their runtime requirements (env vars, binaries, install specs) in the `SKILL.md` frontmatter. ClawHub's security analysis checks these declarations against actual skill behavior; medium review findings stay visible, and the suspicious filter is reserved for high-impact or malicious concerns.

 Full reference: [`docs/skill-format.md`](docs/skill-format.md#frontmatter-metadata)

@@ -0,0 +1,19 @@
+# Security Policy
+
+Use GitHub Security Advisories for vulnerabilities in ClawHub itself.
+
+Good ClawHub advisory reports include bugs in:
+
+- the ClawHub website, API, or CLI
+- registry publishing, downloads, installs, or artifact integrity
+- authentication, authorization, or API tokens
+- scanning, moderation, or report handling
+
+Do not use ClawHub advisories for vulnerabilities in a third-party skill or
+plugin's own source code. Report those directly to the publisher or source
+repository linked from the ClawHub listing.
+
+Use ClawHub's listing reports for genuinely malicious or deceptive marketplace
+content, such as malicious listings, misleading metadata, undeclared
+permissions, suspicious install instructions, scam comments, impersonation,
+trademark misuse, or policy violations.
@@ -0,0 +1,98 @@
+## OpenClaw Vision
+
+OpenClaw is the AI that actually does things.
+It runs on your devices, in your channels, with your rules.
+
+This document explains the current state and direction of the project.
+We are still early, so iteration is fast.
+Project overview and developer docs: [`README.md`](README.md)
+
+OpenClaw started as my personal playground to learn AI and build something genuinely useful:
+an assistant that can run real tasks on my computer.
+It evolved through several names and shells: Warelay -> Clawdbot -> Moltbot -> OpenClaw.
+
+The goal? A personal assistant that's easy to use, supports a wide range of platforms, and respects your privacy and security.
+
+The current focus is:
+
+Priority:
+
+- Security and safe defaults
+- Bug fixes and stability
+- Setup reliability and first-run UX
+
+Next priorities:
+
+- Supporting all major model providers
+- Improving support for major messaging channels (and adding a few high-demand ones)
+- Performance and test infrastructure
+- Better computer-use and agent harness capabilities
+- Ergonomics across CLI and web frontend
+- Companion apps on macOS, iOS, Android, Windows, and Linux
+
+## Security
+
+Security in OpenClaw is a deliberate tradeoff: strong defaults without killing capability.
+The goal is to stay powerful for real work while making risky paths explicit and operator-controlled.
+
+Canonical security policy and reporting:
+
+- https://github.com/openclaw/openclaw/blob/main/SECURITY.md
+
+We prioritize secure defaults, but we also expose clear knobs for trusted high-power workflows.
+
+## Plugins & Memory
+
+OpenClaw has an extensive plugin API.
+Core stays lean; optional capability should usually ship as plugins.
+
+Preferred plugin path is npm package distribution plus local extension loading for development.
+If you build a plugin, please host and maintain it in your own repository.
+The bar for adding optional plugins to core is intentionally high.
+
+Memory is a special plugin slot where only one memory plugin can be active at a time.
+Today we ship multiple memory options; over time we plan to converge on one recommended default path.
+
+### Skills
+
+We still ship some bundled skills for baseline UX.
+New skills should be published to ClawHub first (`clawhub.ai`), not added to core by default.
+Core skill additions should be rare and require a strong product or security reason.
+
+### MCP Support
+
+OpenClaw supports MCP through `mcporter`: https://github.com/steipete/mcporter
+
+This keeps MCP integration flexible and decoupled from core runtime:
+
+- add or change MCP servers without restarting the gateway
+- keep core tool/context surface lean
+- reduce MCP churn impact on core stability and security
+
+For now, we prefer this bridge model over building first-class MCP runtime into core.
+If there is an MCP server or feature `mcporter` does not support yet, please open an issue there.
+
+### Setup
+
+OpenClaw is currently terminal-first by design.
+This keeps setup explicit: users see docs, auth, permissions, and security posture up front.
+
+Long term, we want easier onboarding flows as hardening matures.
+We do not want convenience wrappers that hide critical security decisions from users.
+
+### Why TypeScript?
+
+OpenClaw is primarily an orchestration system: prompts, tools, protocols, and integrations.
+TypeScript was chosen to keep OpenClaw hackable by default.
+It is widely known, fast to iterate in, and easy to read, modify, and extend.
+
+## What We Will Not Merge (For Now)
+
+- New core skills when they can live on ClawHub
+- Commercial service integrations that do not clearly fit the model-provider category
+- Wrapper channels around already supported channels without a clear capability or security gap
+- First-class MCP runtime in core when `mcporter` already provides the integration path
+- Heavy orchestration layers that duplicate existing agent and tool infrastructure
+
+This list is a roadmap guardrail, not a law of physics.
+Strong user demand and strong technical rationale can change it.
@@ -3,9 +3,10 @@ import { existsSync } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'

-const distCliUrl = new URL('./packages/clawdhub/dist/cli.js', import.meta.url)
+const packageRootPath = fileURLToPath(new URL('./packages/clawhub/', import.meta.url))
+const distCliUrl = new URL('./packages/clawhub/dist/cli.js', import.meta.url)
 const distCliPath = fileURLToPath(distCliUrl)
-const srcRootPath = fileURLToPath(new URL('./packages/clawdhub/src/', import.meta.url))
+const srcRootPath = fileURLToPath(new URL('./packages/clawhub/src/', import.meta.url))

 const shouldBuild = await (async () => {
  if (!existsSync(distCliPath)) return true
@@ -19,7 +20,8 @@ const shouldBuild = await (async () => {
 })()

 if (shouldBuild) {
-  const proc = Bun.spawn(['bunx', 'tsc', '-p', 'packages/clawdhub/tsconfig.json'], {
+  const proc = Bun.spawn(['bun', 'run', 'build'], {
+    cwd: packageRootPath,
    stdin: 'inherit',
    stdout: 'inherit',
    stderr: 'inherit',
@@ -34,6 +36,7 @@ async function getLatestMtime(root: string) {
  let latest = 0
  const glob = new Bun.Glob('**/*.ts')
  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    if (rel.endsWith('.test.ts')) continue
    const path = `${root}${root.endsWith('/') ? '' : '/'}${rel}`
    try {
      const entry = await stat(path)
@@ -3,9 +3,10 @@ import { existsSync } from 'node:fs'
 import { stat } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'

-const distCliUrl = new URL('./packages/clawdhub/dist/cli.js', import.meta.url)
+const packageRootPath = fileURLToPath(new URL('./packages/clawhub/', import.meta.url))
+const distCliUrl = new URL('./packages/clawhub/dist/cli.js', import.meta.url)
 const distCliPath = fileURLToPath(distCliUrl)
-const srcRootPath = fileURLToPath(new URL('./packages/clawdhub/src/', import.meta.url))
+const srcRootPath = fileURLToPath(new URL('./packages/clawhub/src/', import.meta.url))

 const shouldBuild = await (async () => {
  if (!existsSync(distCliPath)) return true
@@ -19,7 +20,8 @@ const shouldBuild = await (async () => {
 })()

 if (shouldBuild) {
-  const proc = Bun.spawn(['bunx', 'tsc', '-p', 'packages/clawdhub/tsconfig.json'], {
+  const proc = Bun.spawn(['bun', 'run', 'build'], {
+    cwd: packageRootPath,
    stdin: 'inherit',
    stdout: 'inherit',
    stderr: 'inherit',
@@ -34,6 +36,7 @@ async function getLatestMtime(root: string) {
  let latest = 0
  const glob = new Bun.Glob('**/*.ts')
  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    if (rel.endsWith('.test.ts')) continue
    const path = `${root}${root.endsWith('/') ? '' : '/'}${rel}`
    try {
      const entry = await stat(path)
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}
@@ -0,0 +1,6 @@
+{
+  "guidelinesHash": "62d72acb9afcc18f658d88dd772f34b5b1da5fa60ef0402e57a784d97c458e57",
+  "agentsMdSectionHash": "bbf30bd25ceea0aefd279d62e1cb2b4c207fcb712b69adf26f3d02b296ffc7b2",
+  "claudeMdHash": "bbf30bd25ceea0aefd279d62e1cb2b4c207fcb712b69adf26f3d02b296ffc7b2",
+  "agentSkillsSha": "b86618b5c3c4789c9fed98e84bbc34b3e8e70f20"
+}
@@ -0,0 +1,365 @@
+# Convex guidelines
+
+## Function guidelines
+
+### Http endpoint syntax
+
+- HTTP endpoints are defined in `convex/http.ts` and require an `httpAction` decorator. For example:
+
+```typescript
+import { httpRouter } from "convex/server";
+import { httpAction } from "./_generated/server";
+const http = httpRouter();
+http.route({
+  path: "/echo",
+  method: "POST",
+  handler: httpAction(async (ctx, req) => {
+    const body = await req.bytes();
+    return new Response(body, { status: 200 });
+  }),
+});
+```
+
+- HTTP endpoints are always registered at the exact path you specify in the `path` field. For example, if you specify `/api/someRoute`, the endpoint will be registered at `/api/someRoute`.
+
+### Validators
+
+- Below is an example of an array validator:
+
+```typescript
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export default mutation({
+  args: {
+    simpleArray: v.array(v.union(v.string(), v.number())),
+  },
+  handler: async (ctx, args) => {
+    //...
+  },
+});
+```
+
+- Below is an example of a schema with validators that codify a discriminated union type:
+
+```typescript
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  results: defineTable(
+    v.union(
+      v.object({
+        kind: v.literal("error"),
+        errorMessage: v.string(),
+      }),
+      v.object({
+        kind: v.literal("success"),
+        value: v.number(),
+      }),
+    ),
+  ),
+});
+```
+
+- Here are the valid Convex types along with their respective validators:
+  Convex Type | TS/JS type | Example Usage | Validator for argument validation and schemas | Notes |
+  | ----------- | ------------| -----------------------| -----------------------------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+  | Id | string | `doc._id` | `v.id(tableName)` | |
+  | Null | null | `null` | `v.null()` | JavaScript's `undefined` is not a valid Convex value. Functions the return `undefined` or do not return will return `null` when called from a client. Use `null` instead. |
+  | Int64 | bigint | `3n` | `v.int64()` | Int64s only support BigInts between -2^63 and 2^63-1. Convex supports `bigint`s in most modern browsers. |
+  | Float64 | number | `3.1` | `v.number()` | Convex supports all IEEE-754 double-precision floating point numbers (such as NaNs). Inf and NaN are JSON serialized as strings. |
+  | Boolean | boolean | `true` | `v.boolean()` |
+  | String | string | `"abc"` | `v.string()` | Strings are stored as UTF-8 and must be valid Unicode sequences. Strings must be smaller than the 1MB total size limit when encoded as UTF-8. |
+  | Bytes | ArrayBuffer | `new ArrayBuffer(8)` | `v.bytes()` | Convex supports first class bytestrings, passed in as `ArrayBuffer`s. Bytestrings must be smaller than the 1MB total size limit for Convex types. |
+  | Array | Array | `[1, 3.2, "abc"]` | `v.array(values)` | Arrays can have at most 8192 values. |
+  | Object | Object | `{a: "abc"}` | `v.object({property: value})` | Convex only supports "plain old JavaScript objects" (objects that do not have a custom prototype). Objects can have at most 1024 entries. Field names must be nonempty and not start with "$" or "_". |
+| Record      | Record      | `{"a": "1", "b": "2"}` | `v.record(keys, values)`                       | Records are objects at runtime, but can have dynamic keys. Keys must be only ASCII characters, nonempty, and not start with "$" or "\_". |
+
+### Function registration
+
+- Use `internalQuery`, `internalMutation`, and `internalAction` to register internal functions. These functions are private and aren't part of an app's API. They can only be called by other Convex functions. These functions are always imported from `./_generated/server`.
+- Use `query`, `mutation`, and `action` to register public functions. These functions are part of the public API and are exposed to the public Internet. Do NOT use `query`, `mutation`, or `action` to register sensitive internal functions that should be kept private.
+- You CANNOT register a function through the `api` or `internal` objects.
+- ALWAYS include argument validators for all Convex functions. This includes all of `query`, `internalQuery`, `mutation`, `internalMutation`, `action`, and `internalAction`.
+
+### Function calling
+
+- Use `ctx.runQuery` to call a query from a query, mutation, or action.
+- Use `ctx.runMutation` to call a mutation from a mutation or action.
+- Use `ctx.runAction` to call an action from an action.
+- ONLY call an action from another action if you need to cross runtimes (e.g. from V8 to Node). Otherwise, pull out the shared code into a helper async function and call that directly instead.
+- Try to use as few calls from actions to queries and mutations as possible. Queries and mutations are transactions, so splitting logic up into multiple calls introduces the risk of race conditions.
+- All of these calls take in a `FunctionReference`. Do NOT try to pass the callee function directly into one of these calls.
+- When using `ctx.runQuery`, `ctx.runMutation`, or `ctx.runAction` to call a function in the same file, specify a type annotation on the return value to work around TypeScript circularity limitations. For example,
+
+```
+export const f = query({
+  args: { name: v.string() },
+  handler: async (ctx, args) => {
+    return "Hello " + args.name;
+  },
+});
+
+export const g = query({
+  args: {},
+  handler: async (ctx, args) => {
+    const result: string = await ctx.runQuery(api.example.f, { name: "Bob" });
+    return null;
+  },
+});
+```
+
+### Function references
+
+- Use the `api` object defined by the framework in `convex/_generated/api.ts` to call public functions registered with `query`, `mutation`, or `action`.
+- Use the `internal` object defined by the framework in `convex/_generated/api.ts` to call internal (or private) functions registered with `internalQuery`, `internalMutation`, or `internalAction`.
+- Convex uses file-based routing, so a public function defined in `convex/example.ts` named `f` has a function reference of `api.example.f`.
+- A private function defined in `convex/example.ts` named `g` has a function reference of `internal.example.g`.
+- Functions can also registered within directories nested within the `convex/` folder. For example, a public function `h` defined in `convex/messages/access.ts` has a function reference of `api.messages.access.h`.
+
+### Pagination
+
+- Define pagination using the following syntax:
+
+```ts
+import { v } from "convex/values";
+import { query, mutation } from "./_generated/server";
+import { paginationOptsValidator } from "convex/server";
+export const listWithExtraArg = query({
+  args: { paginationOpts: paginationOptsValidator, author: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("messages")
+      .withIndex("by_author", (q) => q.eq("author", args.author))
+      .order("desc")
+      .paginate(args.paginationOpts);
+  },
+});
+```
+
+Note: `paginationOpts` is an object with the following properties:
+
+- `numItems`: the maximum number of documents to return (the validator is `v.number()`)
+- `cursor`: the cursor to use to fetch the next page of documents (the validator is `v.union(v.string(), v.null())`)
+- A query that ends in `.paginate()` returns an object that has the following properties:
+- page (contains an array of documents that you fetches)
+- isDone (a boolean that represents whether or not this is the last page of documents)
+- continueCursor (a string that represents the cursor to use to fetch the next page of documents)
+
+## Schema guidelines
+
+- Always define your schema in `convex/schema.ts`.
+- Always import the schema definition functions from `convex/server`.
+- System fields are automatically added to all documents and are prefixed with an underscore. The two system fields that are automatically added to all documents are `_creationTime` which has the validator `v.number()` and `_id` which has the validator `v.id(tableName)`.
+- Always include all index fields in the index name. For example, if an index is defined as `["field1", "field2"]`, the index name should be "by_field1_and_field2".
+- Index fields must be queried in the same order they are defined. If you want to be able to query by "field1" then "field2" and by "field2" then "field1", you must create separate indexes.
+- Do not store unbounded lists as an array field inside a document (e.g. `v.array(v.object({...}))`). As the array grows it will hit the 1MB document size limit, and every update rewrites the entire document. Instead, create a separate table for the child items with a foreign key back to the parent.
+- Separate high-churn operational data (e.g. heartbeats, online status, typing indicators) from stable profile data. Storing frequently updated fields on a shared document forces every write to contend with reads of the entire document. Instead, create a dedicated table for the high-churn data with a foreign key back to the parent record.
+
+## Authentication guidelines
+
+- Convex supports JWT-based authentication through `convex/auth.config.ts`. ALWAYS create this file when using authentication. Without it, `ctx.auth.getUserIdentity()` will always return `null`.
+- Example `convex/auth.config.ts`:
+
+```typescript
+export default {
+  providers: [
+    {
+      domain: "https://your-auth-provider.com",
+      applicationID: "convex",
+    },
+  ],
+};
+```
+
+The `domain` must be the issuer URL of the JWT provider. Convex fetches `{domain}/.well-known/openid-configuration` to discover the JWKS endpoint. The `applicationID` is checked against the JWT `aud` (audience) claim.
+
+- Use `ctx.auth.getUserIdentity()` to get the authenticated user's identity in any query, mutation, or action. This returns `null` if the user is not authenticated, or a `UserIdentity` object with fields like `subject`, `issuer`, `name`, `email`, etc. The `subject` field is the unique user identifier.
+- In Convex `UserIdentity`, `tokenIdentifier` is guaranteed and is the canonical stable identifier for the authenticated identity. For any auth-linked database lookup or ownership check, prefer `identity.tokenIdentifier` over `identity.subject`. Do NOT use `identity.subject` alone as a global identity key.
+- NEVER accept a `userId` or any user identifier as a function argument for authorization purposes. Always derive the user identity server-side via `ctx.auth.getUserIdentity()`.
+- When using an external auth provider with Convex on the client, use `ConvexProviderWithAuth` instead of `ConvexProvider`:
+
+```tsx
+import { ConvexProviderWithAuth, ConvexReactClient } from "convex/react";
+
+const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
+
+function App({ children }: { children: React.ReactNode }) {
+  return (
+    <ConvexProviderWithAuth client={convex} useAuth={useYourAuthHook}>
+      {children}
+    </ConvexProviderWithAuth>
+  );
+}
+```
+
+The `useAuth` prop must return `{ isLoading, isAuthenticated, fetchAccessToken }`. Do NOT use plain `ConvexProvider` when authentication is needed — it will not send tokens with requests.
+
+## Typescript guidelines
+
+- You can use the helper typescript type `Id` imported from './\_generated/dataModel' to get the type of the id for a given table. For example if there is a table called 'users' you can use `Id<'users'>` to get the type of the id for that table.
+- Use `Doc<"tableName">` from `./_generated/dataModel` to get the full document type for a table.
+- Use `QueryCtx`, `MutationCtx`, `ActionCtx` from `./_generated/server` for typing function contexts. NEVER use `any` for ctx parameters — always use the proper context type.
+- If you need to define a `Record` make sure that you correctly provide the type of the key and value in the type. For example a validator `v.record(v.id('users'), v.string())` would have the type `Record<Id<'users'>, string>`. Below is an example of using `Record` with an `Id` type in a query:
+
+```ts
+import { query } from "./_generated/server";
+import { Doc, Id } from "./_generated/dataModel";
+
+export const exampleQuery = query({
+  args: { userIds: v.array(v.id("users")) },
+  handler: async (ctx, args) => {
+    const idToUsername: Record<Id<"users">, string> = {};
+    for (const userId of args.userIds) {
+      const user = await ctx.db.get("users", userId);
+      if (user) {
+        idToUsername[user._id] = user.username;
+      }
+    }
+
+    return idToUsername;
+  },
+});
+```
+
+- Be strict with types, particularly around id's of documents. For example, if a function takes in an id for a document in the 'users' table, take in `Id<'users'>` rather than `string`.
+
+## Full text search guidelines
+
+- A query for "10 messages in channel '#general' that best match the query 'hello hi' in their body" would look like:
+
+const messages = await ctx.db
+.query("messages")
+.withSearchIndex("search_body", (q) =>
+q.search("body", "hello hi").eq("channel", "#general"),
+)
+.take(10);
+
+## Query guidelines
+
+- Do NOT use `filter` in queries. Instead, define an index in the schema and use `withIndex` instead.
+- If the user does not explicitly tell you to return all results from a query you should ALWAYS return a bounded collection instead. So that is instead of using `.collect()` you should use `.take()` or paginate on database queries. This prevents future performance issues when tables grow in an unbounded way.
+- Never use `.collect().length` to count rows. Convex has no built-in count operator, so if you need a count that stays efficient at scale, maintain a denormalized counter in a separate document and update it in your mutations.
+- Convex queries do NOT support `.delete()`. If you need to delete all documents matching a query, use `.take(n)` to read them in batches, iterate over each batch calling `ctx.db.delete(row._id)`, and repeat until no more results are returned.
+- Convex mutations are transactions with limits on the number of documents read and written. If a mutation needs to process more documents than fit in a single transaction (e.g. bulk deletion on a large table), process a batch with `.take(n)` and then call `ctx.scheduler.runAfter(0, api.myModule.myMutation, args)` to schedule itself to continue. This way each invocation stays within transaction limits.
+- Use `.unique()` to get a single document from a query. This method will throw an error if there are multiple documents that match the query.
+- When using async iteration, don't use `.collect()` or `.take(n)` on the result of a query. Instead, use the `for await (const row of query)` syntax.
+
+### Ordering
+
+- By default Convex always returns documents in ascending `_creationTime` order.
+- You can use `.order('asc')` or `.order('desc')` to pick whether a query is in ascending or descending order. If the order isn't specified, it defaults to ascending.
+- Document queries that use indexes will be ordered based on the columns in the index and can avoid slow table scans.
+
+## Mutation guidelines
+
+- Use `ctx.db.replace` to fully replace an existing document. This method will throw an error if the document does not exist. Syntax: `await ctx.db.replace('tasks', taskId, { name: 'Buy milk', completed: false })`
+- Use `ctx.db.patch` to shallow merge updates into an existing document. This method will throw an error if the document does not exist. Syntax: `await ctx.db.patch('tasks', taskId, { completed: true })`
+
+## Action guidelines
+
+- Always add `"use node";` to the top of files containing actions that use Node.js built-in modules.
+- Never add `"use node";` to a file that also exports queries or mutations. Only actions can run in the Node.js runtime; queries and mutations must stay in the default Convex runtime. If you need Node.js built-ins alongside queries or mutations, put the action in a separate file.
+- `fetch()` is available in the default Convex runtime. You do NOT need `"use node";` just to use `fetch()`.
+- Never use `ctx.db` inside of an action. Actions don't have access to the database.
+- Below is an example of the syntax for an action:
+
+```ts
+import { action } from "./_generated/server";
+
+export const exampleAction = action({
+  args: {},
+  handler: async (ctx, args) => {
+    console.log("This action does not return anything");
+    return null;
+  },
+});
+```
+
+## Scheduling guidelines
+
+### Cron guidelines
+
+- Only use the `crons.interval` or `crons.cron` methods to schedule cron jobs. Do NOT use the `crons.hourly`, `crons.daily`, or `crons.weekly` helpers.
+- Both cron methods take in a FunctionReference. Do NOT try to pass the function directly into one of these methods.
+- Define crons by declaring the top-level `crons` object, calling some methods on it, and then exporting it as default. For example,
+
+```ts
+import { cronJobs } from "convex/server";
+import { internal } from "./_generated/api";
+import { internalAction } from "./_generated/server";
+
+const empty = internalAction({
+  args: {},
+  handler: async (ctx, args) => {
+    console.log("empty");
+  },
+});
+
+const crons = cronJobs();
+
+// Run `internal.crons.empty` every two hours.
+crons.interval("delete inactive users", { hours: 2 }, internal.crons.empty, {});
+
+export default crons;
+```
+
+- You can register Convex functions within `crons.ts` just like any other file.
+- If a cron calls an internal function, always import the `internal` object from '\_generated/api', even if the internal function is registered in the same file.
+
+## Testing guidelines
+
+- Use `convex-test` with `vitest` and `@edge-runtime/vm` to test Convex functions. Always install the latest versions of these packages. Configure vitest with `environment: "edge-runtime"` in `vitest.config.ts`.
+
+Test files go inside the `convex/` directory. You must pass a module map from `import.meta.glob` to `convexTest`:
+
+```typescript
+/// <reference types="vite/client" />
+import { convexTest } from "convex-test";
+import { expect, test } from "vitest";
+import { api } from "./_generated/api";
+import schema from "./schema";
+
+const modules = import.meta.glob("./**/*.ts");
+
+test("some behavior", async () => {
+  const t = convexTest(schema, modules);
+  await t.mutation(api.messages.send, { body: "Hi!", author: "Sarah" });
+  const messages = await t.query(api.messages.list);
+  expect(messages).toMatchObject([{ body: "Hi!", author: "Sarah" }]);
+});
+```
+
+The `modules` argument is required so convex-test can discover and load function files. The `/// <reference types="vite/client" />` directive is needed for TypeScript to recognize `import.meta.glob`.
+
+## File storage guidelines
+
+- The `ctx.storage.getUrl()` method returns a signed URL for a given file. It returns `null` if the file doesn't exist.
+- Do NOT use the deprecated `ctx.storage.getMetadata` call for loading a file's metadata.
+
+Instead, query the `_storage` system table. For example, you can use `ctx.db.system.get` to get an `Id<"_storage">`.
+
+```
+import { query } from "./_generated/server";
+import { Id } from "./_generated/dataModel";
+
+type FileMetadata = {
+    _id: Id<"_storage">;
+    _creationTime: number;
+    contentType?: string;
+    sha256: string;
+    size: number;
+}
+
+export const exampleQuery = query({
+    args: { fileId: v.id("_storage") },
+    handler: async (ctx, args) => {
+        const metadata: FileMetadata | null = await ctx.db.system.get("_storage", args.fileId);
+        console.log(metadata);
+        return null;
+    },
+});
+```
+
+- Convex storage stores items as `Blob` objects. You must convert all items to/from a `Blob` when using Convex storage.
@@ -8,56 +8,124 @@
 * @module
 */

+import type * as appMeta from "../appMeta.js";
 import type * as auth from "../auth.js";
+import type * as cliDeviceAuth from "../cliDeviceAuth.js";
+import type * as commentModeration from "../commentModeration.js";
 import type * as comments from "../comments.js";
 import type * as crons from "../crons.js";
+import type * as depRegistryScan from "../depRegistryScan.js";
 import type * as devSeed from "../devSeed.js";
 import type * as devSeedExtra from "../devSeedExtra.js";
 import type * as downloads from "../downloads.js";
+import type * as functions from "../functions.js";
 import type * as githubBackups from "../githubBackups.js";
 import type * as githubBackupsNode from "../githubBackupsNode.js";
+import type * as githubIdentity from "../githubIdentity.js";
 import type * as githubImport from "../githubImport.js";
+import type * as githubRestore from "../githubRestore.js";
+import type * as githubRestoreMutations from "../githubRestoreMutations.js";
 import type * as githubSoulBackups from "../githubSoulBackups.js";
 import type * as githubSoulBackupsNode from "../githubSoulBackupsNode.js";
 import type * as http from "../http.js";
 import type * as httpApi from "../httpApi.js";
 import type * as httpApiV1 from "../httpApiV1.js";
+import type * as httpApiV1_docsSessionV1 from "../httpApiV1/docsSessionV1.js";
+import type * as httpApiV1_packagesV1 from "../httpApiV1/packagesV1.js";
+import type * as httpApiV1_publishersV1 from "../httpApiV1/publishersV1.js";
+import type * as httpApiV1_shared from "../httpApiV1/shared.js";
+import type * as httpApiV1_skillsV1 from "../httpApiV1/skillsV1.js";
+import type * as httpApiV1_soulsV1 from "../httpApiV1/soulsV1.js";
+import type * as httpApiV1_starsV1 from "../httpApiV1/starsV1.js";
+import type * as httpApiV1_transfersV1 from "../httpApiV1/transfersV1.js";
+import type * as httpApiV1_usersV1 from "../httpApiV1/usersV1.js";
+import type * as httpApiV1_whoamiV1 from "../httpApiV1/whoamiV1.js";
+import type * as httpPreflight from "../httpPreflight.js";
 import type * as leaderboards from "../leaderboards.js";
 import type * as lib_access from "../lib/access.js";
+import type * as lib_apiKeyRequirementPrompt from "../lib/apiKeyRequirementPrompt.js";
 import type * as lib_apiTokenAuth from "../lib/apiTokenAuth.js";
+import type * as lib_artifactModeration from "../lib/artifactModeration.js";
 import type * as lib_badges from "../lib/badges.js";
+import type * as lib_batching from "../lib/batching.js";
 import type * as lib_changelog from "../lib/changelog.js";
+import type * as lib_clawpack from "../lib/clawpack.js";
+import type * as lib_commentScamPrompt from "../lib/commentScamPrompt.js";
+import type * as lib_contentTypes from "../lib/contentTypes.js";
+import type * as lib_depRegistryScan from "../lib/depRegistryScan.js";
+import type * as lib_devAuth from "../lib/devAuth.js";
+import type * as lib_embeddingVisibility from "../lib/embeddingVisibility.js";
 import type * as lib_embeddings from "../lib/embeddings.js";
 import type * as lib_githubAccount from "../lib/githubAccount.js";
+import type * as lib_githubActionsOidc from "../lib/githubActionsOidc.js";
 import type * as lib_githubBackup from "../lib/githubBackup.js";
+import type * as lib_githubIdentity from "../lib/githubIdentity.js";
 import type * as lib_githubImport from "../lib/githubImport.js";
+import type * as lib_githubProfileSync from "../lib/githubProfileSync.js";
+import type * as lib_githubRestoreHelpers from "../lib/githubRestoreHelpers.js";
 import type * as lib_githubSoulBackup from "../lib/githubSoulBackup.js";
+import type * as lib_globalStats from "../lib/globalStats.js";
+import type * as lib_httpHeaders from "../lib/httpHeaders.js";
 import type * as lib_httpRateLimit from "../lib/httpRateLimit.js";
+import type * as lib_httpUtils from "../lib/httpUtils.js";
 import type * as lib_leaderboards from "../lib/leaderboards.js";
+import type * as lib_manualOverrides from "../lib/manualOverrides.js";
 import type * as lib_moderation from "../lib/moderation.js";
+import type * as lib_moderationEngine from "../lib/moderationEngine.js";
+import type * as lib_moderationReasonCodes from "../lib/moderationReasonCodes.js";
+import type * as lib_officialPublishers from "../lib/officialPublishers.js";
+import type * as lib_openaiResponse from "../lib/openaiResponse.js";
+import type * as lib_packageRegistry from "../lib/packageRegistry.js";
+import type * as lib_packageSearchDigest from "../lib/packageSearchDigest.js";
+import type * as lib_packageSecurity from "../lib/packageSecurity.js";
+import type * as lib_parsedEnvSignals from "../lib/parsedEnvSignals.js";
 import type * as lib_public from "../lib/public.js";
+import type * as lib_publicRouteReservations from "../lib/publicRouteReservations.js";
+import type * as lib_publishLimits from "../lib/publishLimits.js";
+import type * as lib_publisherAbuseScoring from "../lib/publisherAbuseScoring.js";
+import type * as lib_publisherStats from "../lib/publisherStats.js";
+import type * as lib_publishers from "../lib/publishers.js";
+import type * as lib_reporting from "../lib/reporting.js";
+import type * as lib_reservedHandles from "../lib/reservedHandles.js";
+import type * as lib_reservedSlugs from "../lib/reservedSlugs.js";
 import type * as lib_searchText from "../lib/searchText.js";
 import type * as lib_securityPrompt from "../lib/securityPrompt.js";
 import type * as lib_skillBackfill from "../lib/skillBackfill.js";
+import type * as lib_skillCapabilityTags from "../lib/skillCapabilityTags.js";
+import type * as lib_skillCards from "../lib/skillCards.js";
+import type * as lib_skillIcon from "../lib/skillIcon.js";
 import type * as lib_skillPublish from "../lib/skillPublish.js";
 import type * as lib_skillQuality from "../lib/skillQuality.js";
 import type * as lib_skillSafety from "../lib/skillSafety.js";
+import type * as lib_skillSearchDigest from "../lib/skillSearchDigest.js";
+import type * as lib_skillSlugValidator from "../lib/skillSlugValidator.js";
 import type * as lib_skillStats from "../lib/skillStats.js";
 import type * as lib_skillSummary from "../lib/skillSummary.js";
 import type * as lib_skillZip from "../lib/skillZip.js";
 import type * as lib_skills from "../lib/skills.js";
 import type * as lib_soulChangelog from "../lib/soulChangelog.js";
 import type * as lib_soulPublish from "../lib/soulPublish.js";
+import type * as lib_staticPublishScan from "../lib/staticPublishScan.js";
 import type * as lib_tokens from "../lib/tokens.js";
 import type * as lib_userSearch from "../lib/userSearch.js";
+import type * as lib_userSkillStats from "../lib/userSkillStats.js";
 import type * as lib_webhooks from "../lib/webhooks.js";
 import type * as llmEval from "../llmEval.js";
 import type * as maintenance from "../maintenance.js";
+import type * as packagePublishTokens from "../packagePublishTokens.js";
+import type * as packages from "../packages.js";
+import type * as publisherAbuse from "../publisherAbuse.js";
+import type * as publishers from "../publishers.js";
 import type * as rateLimits from "../rateLimits.js";
 import type * as search from "../search.js";
+import type * as securityDataset from "../securityDataset.js";
+import type * as securityDatasetNode from "../securityDatasetNode.js";
+import type * as securityScan from "../securityScan.js";
 import type * as seed from "../seed.js";
 import type * as seedSouls from "../seedSouls.js";
+import type * as skillCards from "../skillCards.js";
 import type * as skillStatEvents from "../skillStatEvents.js";
+import type * as skillTransfers from "../skillTransfers.js";
 import type * as skills from "../skills.js";
 import type * as soulComments from "../soulComments.js";
 import type * as soulDownloads from "../soulDownloads.js";
@@ -79,56 +147,124 @@ import type {
 } from "convex/server";

 declare const fullApi: ApiFromModules<{
+  appMeta: typeof appMeta;
  auth: typeof auth;
+  cliDeviceAuth: typeof cliDeviceAuth;
+  commentModeration: typeof commentModeration;
  comments: typeof comments;
  crons: typeof crons;
+  depRegistryScan: typeof depRegistryScan;
  devSeed: typeof devSeed;
  devSeedExtra: typeof devSeedExtra;
  downloads: typeof downloads;
+  functions: typeof functions;
  githubBackups: typeof githubBackups;
  githubBackupsNode: typeof githubBackupsNode;
+  githubIdentity: typeof githubIdentity;
  githubImport: typeof githubImport;
+  githubRestore: typeof githubRestore;
+  githubRestoreMutations: typeof githubRestoreMutations;
  githubSoulBackups: typeof githubSoulBackups;
  githubSoulBackupsNode: typeof githubSoulBackupsNode;
  http: typeof http;
  httpApi: typeof httpApi;
  httpApiV1: typeof httpApiV1;
+  "httpApiV1/docsSessionV1": typeof httpApiV1_docsSessionV1;
+  "httpApiV1/packagesV1": typeof httpApiV1_packagesV1;
+  "httpApiV1/publishersV1": typeof httpApiV1_publishersV1;
+  "httpApiV1/shared": typeof httpApiV1_shared;
+  "httpApiV1/skillsV1": typeof httpApiV1_skillsV1;
+  "httpApiV1/soulsV1": typeof httpApiV1_soulsV1;
+  "httpApiV1/starsV1": typeof httpApiV1_starsV1;
+  "httpApiV1/transfersV1": typeof httpApiV1_transfersV1;
+  "httpApiV1/usersV1": typeof httpApiV1_usersV1;
+  "httpApiV1/whoamiV1": typeof httpApiV1_whoamiV1;
+  httpPreflight: typeof httpPreflight;
  leaderboards: typeof leaderboards;
  "lib/access": typeof lib_access;
+  "lib/apiKeyRequirementPrompt": typeof lib_apiKeyRequirementPrompt;
  "lib/apiTokenAuth": typeof lib_apiTokenAuth;
+  "lib/artifactModeration": typeof lib_artifactModeration;
  "lib/badges": typeof lib_badges;
+  "lib/batching": typeof lib_batching;
  "lib/changelog": typeof lib_changelog;
+  "lib/clawpack": typeof lib_clawpack;
+  "lib/commentScamPrompt": typeof lib_commentScamPrompt;
+  "lib/contentTypes": typeof lib_contentTypes;
+  "lib/depRegistryScan": typeof lib_depRegistryScan;
+  "lib/devAuth": typeof lib_devAuth;
+  "lib/embeddingVisibility": typeof lib_embeddingVisibility;
  "lib/embeddings": typeof lib_embeddings;
  "lib/githubAccount": typeof lib_githubAccount;
+  "lib/githubActionsOidc": typeof lib_githubActionsOidc;
  "lib/githubBackup": typeof lib_githubBackup;
+  "lib/githubIdentity": typeof lib_githubIdentity;
  "lib/githubImport": typeof lib_githubImport;
+  "lib/githubProfileSync": typeof lib_githubProfileSync;
+  "lib/githubRestoreHelpers": typeof lib_githubRestoreHelpers;
  "lib/githubSoulBackup": typeof lib_githubSoulBackup;
+  "lib/globalStats": typeof lib_globalStats;
+  "lib/httpHeaders": typeof lib_httpHeaders;
  "lib/httpRateLimit": typeof lib_httpRateLimit;
+  "lib/httpUtils": typeof lib_httpUtils;
  "lib/leaderboards": typeof lib_leaderboards;
+  "lib/manualOverrides": typeof lib_manualOverrides;
  "lib/moderation": typeof lib_moderation;
+  "lib/moderationEngine": typeof lib_moderationEngine;
+  "lib/moderationReasonCodes": typeof lib_moderationReasonCodes;
+  "lib/officialPublishers": typeof lib_officialPublishers;
+  "lib/openaiResponse": typeof lib_openaiResponse;
+  "lib/packageRegistry": typeof lib_packageRegistry;
+  "lib/packageSearchDigest": typeof lib_packageSearchDigest;
+  "lib/packageSecurity": typeof lib_packageSecurity;
+  "lib/parsedEnvSignals": typeof lib_parsedEnvSignals;
  "lib/public": typeof lib_public;
+  "lib/publicRouteReservations": typeof lib_publicRouteReservations;
+  "lib/publishLimits": typeof lib_publishLimits;
+  "lib/publisherAbuseScoring": typeof lib_publisherAbuseScoring;
+  "lib/publisherStats": typeof lib_publisherStats;
+  "lib/publishers": typeof lib_publishers;
+  "lib/reporting": typeof lib_reporting;
+  "lib/reservedHandles": typeof lib_reservedHandles;
+  "lib/reservedSlugs": typeof lib_reservedSlugs;
  "lib/searchText": typeof lib_searchText;
  "lib/securityPrompt": typeof lib_securityPrompt;
  "lib/skillBackfill": typeof lib_skillBackfill;
+  "lib/skillCapabilityTags": typeof lib_skillCapabilityTags;
+  "lib/skillCards": typeof lib_skillCards;
+  "lib/skillIcon": typeof lib_skillIcon;
  "lib/skillPublish": typeof lib_skillPublish;
  "lib/skillQuality": typeof lib_skillQuality;
  "lib/skillSafety": typeof lib_skillSafety;
+  "lib/skillSearchDigest": typeof lib_skillSearchDigest;
+  "lib/skillSlugValidator": typeof lib_skillSlugValidator;
  "lib/skillStats": typeof lib_skillStats;
  "lib/skillSummary": typeof lib_skillSummary;
  "lib/skillZip": typeof lib_skillZip;
  "lib/skills": typeof lib_skills;
  "lib/soulChangelog": typeof lib_soulChangelog;
  "lib/soulPublish": typeof lib_soulPublish;
+  "lib/staticPublishScan": typeof lib_staticPublishScan;
  "lib/tokens": typeof lib_tokens;
  "lib/userSearch": typeof lib_userSearch;
+  "lib/userSkillStats": typeof lib_userSkillStats;
  "lib/webhooks": typeof lib_webhooks;
  llmEval: typeof llmEval;
  maintenance: typeof maintenance;
+  packagePublishTokens: typeof packagePublishTokens;
+  packages: typeof packages;
+  publisherAbuse: typeof publisherAbuse;
+  publishers: typeof publishers;
  rateLimits: typeof rateLimits;
  search: typeof search;
+  securityDataset: typeof securityDataset;
+  securityDatasetNode: typeof securityDatasetNode;
+  securityScan: typeof securityScan;
  seed: typeof seed;
  seedSouls: typeof seedSouls;
+  skillCards: typeof skillCards;
  skillStatEvents: typeof skillStatEvents;
+  skillTransfers: typeof skillTransfers;
  skills: typeof skills;
  soulComments: typeof soulComments;
  soulDownloads: typeof soulDownloads;
@@ -0,0 +1,7 @@
+import { internal } from "./_generated/api";
+
+// Asserts that the internal-only download counters remain internal-only.
+// Public exposure is prevented at runtime by `internalMutation`; this file
+// just pins the public references that *should* exist.
+void internal.downloads.recordDownloadInternal;
+void internal.soulDownloads.incrementInternal;
@@ -0,0 +1,14 @@
+import { query } from "./functions";
+
+function normalizeEnv(value: string | undefined) {
+  const normalized = value?.trim();
+  return normalized ? normalized : null;
+}
+
+export const getDeploymentInfo = query({
+  args: {},
+  handler: async () => ({
+    appBuildSha: normalizeEnv(process.env.APP_BUILD_SHA),
+    deployedAt: normalizeEnv(process.env.APP_DEPLOYED_AT),
+  }),
+});
@@ -2,7 +2,7 @@ export default {
  providers: [
    {
      domain: process.env.CONVEX_SITE_URL,
-      applicationID: 'convex',
+      applicationID: "convex",
    },
  ],
-}
+};
@@ -1,125 +1,141 @@
-import { describe, expect, it, vi } from 'vitest'
-import type { Id } from './_generated/dataModel'
+import { describe, expect, it, vi } from "vitest";
+import type { Id } from "./_generated/dataModel";
 import {
  BANNED_REAUTH_MESSAGE,
  DELETED_ACCOUNT_REAUTH_MESSAGE,
  handleDeletedUserSignIn,
-} from './auth'
+} from "./auth";

 function makeCtx({
  user,
  banRecords,
 }: {
-  user: { deletedAt?: number; deactivatedAt?: number; purgedAt?: number } | null
-  banRecords?: Array<Record<string, unknown>>
+  user: {
+    deletedAt?: number;
+    deactivatedAt?: number;
+    purgedAt?: number;
+    banReason?: string;
+  } | null;
+  banRecords?: Array<Record<string, unknown>>;
 }) {
  const query = {
    withIndex: vi.fn().mockReturnValue({
      collect: vi.fn().mockResolvedValue(banRecords ?? []),
    }),
-  }
+  };
  const ctx = {
    db: {
      get: vi.fn().mockResolvedValue(user),
      patch: vi.fn().mockResolvedValue(null),
      query: vi.fn().mockReturnValue(query),
    },
-  }
-  return { ctx, query }
+  };
+  return { ctx, query };
 }

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

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

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

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

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

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

-    expect(ctx.db.query).not.toHaveBeenCalled()
-    expect(ctx.db.patch).not.toHaveBeenCalled()
-  })
+    expect(ctx.db.query).not.toHaveBeenCalled();
+    expect(ctx.db.patch).not.toHaveBeenCalled();
+  });

-  it('blocks sign-in for deactivated users', async () => {
-    const { ctx } = makeCtx({ user: { deactivatedAt: 123, purgedAt: 123 } })
+  it("blocks sign-in for deactivated users", async () => {
+    const { ctx } = makeCtx({ user: { deactivatedAt: 123, purgedAt: 123 } });

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

-    expect(ctx.db.query).not.toHaveBeenCalled()
-    expect(ctx.db.patch).not.toHaveBeenCalled()
-  })
+    expect(ctx.db.query).not.toHaveBeenCalled();
+    expect(ctx.db.patch).not.toHaveBeenCalled();
+  });

-  it('migrates legacy self-deleted users and blocks sign-in', async () => {
-    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecords: [] })
+  it("migrates legacy self-deleted users and blocks sign-in", async () => {
+    const { ctx } = makeCtx({ user: { deletedAt: 123 }, banRecords: [] });

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

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

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

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

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

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

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

-    expect(ctx.db.query).not.toHaveBeenCalled()
-    expect(ctx.db.patch).not.toHaveBeenCalled()
-  })
+    expect(ctx.db.query).not.toHaveBeenCalled();
+    expect(ctx.db.patch).not.toHaveBeenCalled();
+  });

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

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

-    expect(ctx.db.patch).not.toHaveBeenCalled()
-  })
+    expect(ctx.db.patch).not.toHaveBeenCalled();
+  });

-  it('blocks users auto-banned for malware', async () => {
+  it("blocks users auto-banned for malware", async () => {
    const { ctx } = makeCtx({
-      user: { deletedAt: 123 },
-      banRecords: [{ action: 'user.autoban.malware' }],
-    })
+      user: { deletedAt: 123, banReason: "malware auto-ban" },
+      banRecords: [{ action: "user.autoban.malware" }],
+    });

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

-    expect(ctx.db.patch).not.toHaveBeenCalled()
-  })
-})
+    expect(ctx.db.patch).not.toHaveBeenCalled();
+  });
+
+  it("includes the moderator ban reason in the sign-in error", async () => {
+    const { ctx } = makeCtx({
+      user: { deletedAt: 123, banReason: "Chargeback fraud" },
+      banRecords: [{ action: "user.ban" }],
+    });
+
+    await expect(
+      handleDeletedUserSignIn(ctx as never, { userId, existingUserId: userId }),
+    ).rejects.toThrow(`${BANNED_REAUTH_MESSAGE} Reason: Chargeback fraud`);
+  });
+});
@@ -1,43 +1,64 @@
-import GitHub from '@auth/core/providers/github'
-import { convexAuth } from '@convex-dev/auth/server'
-import type { GenericMutationCtx } from 'convex/server'
-import { ConvexError } from 'convex/values'
-import type { DataModel, Id } from './_generated/dataModel'
+import GitHub from "@auth/core/providers/github";
+import { ConvexCredentials } from "@convex-dev/auth/providers/ConvexCredentials";
+import { convexAuth } from "@convex-dev/auth/server";
+import type { GenericMutationCtx } from "convex/server";
+import { ConvexError } from "convex/values";
+import { internal } from "./_generated/api";
+import type { DataModel, Id } from "./_generated/dataModel";
+import { isLocalDevAuthEnabled } from "./lib/devAuth";
+import { shouldScheduleGitHubProfileSync } from "./lib/githubProfileSync";

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

-const REAUTH_BLOCKING_BAN_ACTIONS = new Set(['user.ban', 'user.autoban.malware'])
+const REAUTH_BLOCKING_BAN_ACTIONS = new Set(["user.ban", "user.autoban.malware"]);
+const DEV_PERSONAS = new Set(["owner", "user", "admin"]);
+
+function getBannedReauthMessage(reason: string | undefined) {
+  const normalizedReason = reason?.trim();
+  if (!normalizedReason || normalizedReason.toLowerCase() === "malware auto-ban") {
+    return BANNED_REAUTH_MESSAGE;
+  }
+  return `${BANNED_REAUTH_MESSAGE} Reason: ${normalizedReason}`;
+}

 export async function handleDeletedUserSignIn(
  ctx: GenericMutationCtx<DataModel>,
-  args: { userId: Id<'users'>; existingUserId: Id<'users'> | null },
+  args: { userId: Id<"users">; existingUserId: Id<"users"> | null },
+  userOverride?: {
+    deletedAt?: number;
+    deactivatedAt?: number;
+    purgedAt?: number;
+    banReason?: string;
+  } | null,
 ) {
-  const user = await ctx.db.get(args.userId)
-  if (!user?.deletedAt && !user?.deactivatedAt) return
+  const user = userOverride !== undefined ? userOverride : await ctx.db.get(args.userId);
+  if (!user?.deletedAt && !user?.deactivatedAt) return;

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

  if (user.deactivatedAt) {
-    throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE)
+    throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE);
  }

-  const userId = args.userId
-  const deletedAt = user.deletedAt ?? Date.now()
+  const userId = args.userId;
+  const deletedAt = user.deletedAt ?? Date.now();
  const banRecords = await ctx.db
-    .query('auditLogs')
-    .withIndex('by_target', (q) => q.eq('targetType', 'user').eq('targetId', userId.toString()))
-    .collect()
+    .query("auditLogs")
+    .withIndex("by_target", (q) => q.eq("targetType", "user").eq("targetId", userId.toString()))
+    .collect();

-  const hasBlockingBan = banRecords.some((record) => REAUTH_BLOCKING_BAN_ACTIONS.has(record.action))
+  const hasBlockingBan = banRecords.some((record) =>
+    REAUTH_BLOCKING_BAN_ACTIONS.has(record.action),
+  );

  if (hasBlockingBan) {
-    throw new ConvexError(BANNED_REAUTH_MESSAGE)
+    throw new ConvexError(getBannedReauthMessage(user.banReason));
  }

  // Migrate legacy self-deleted accounts (stored in deletedAt) to the new
@@ -47,36 +68,64 @@ export async function handleDeletedUserSignIn(
    deactivatedAt: deletedAt,
    purgedAt: user.purgedAt ?? deletedAt,
    updatedAt: Date.now(),
-  })
+  });

-  throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE)
+  throw new ConvexError(DELETED_ACCOUNT_REAUTH_MESSAGE);
 }

 export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
  providers: [
    GitHub({
-      clientId: process.env.AUTH_GITHUB_ID ?? '',
-      clientSecret: process.env.AUTH_GITHUB_SECRET ?? '',
+      clientId: process.env.AUTH_GITHUB_ID ?? "",
+      clientSecret: process.env.AUTH_GITHUB_SECRET ?? "",
      profile(profile) {
        return {
          id: String(profile.id),
          name: profile.login,
          email: profile.email ?? undefined,
          image: profile.avatar_url,
-        }
+        };
+      },
+    }),
+    ConvexCredentials({
+      id: "dev-persona",
+      authorize: async (credentials, ctx) => {
+        if (!isLocalDevAuthEnabled()) throw new Error("Dev auth is disabled");
+        const persona = typeof credentials.persona === "string" ? credentials.persona : "";
+        if (!DEV_PERSONAS.has(persona)) throw new Error("Unknown dev persona");
+        const userId: Id<"users"> = await ctx.runMutation(internal.users.upsertDevPersonaInternal, {
+          persona: persona as "owner" | "user" | "admin",
+        });
+        return { userId };
      },
    }),
  ],
  callbacks: {
    /**
-     * Block sign-in for deleted/deactivated users.
+     * Block sign-in for deleted/deactivated users and sync GitHub profile.
     *
     * Performance note: This callback runs on every OAuth sign-in, but the
     * audit log query ONLY executes when a legacy deleted user attempts to sign
     * in (user.deletedAt is set). For active users, this is a single field check.
+     *
+     * The GitHub profile sync is scheduled as a background action to handle
+     * the case where a user renames their GitHub account (fixes #303).
     */
    async afterUserCreatedOrUpdated(ctx, args) {
-      await handleDeletedUserSignIn(ctx, args)
+      const user = await ctx.db.get(args.userId);
+      await handleDeletedUserSignIn(ctx, args, user);
+      await ctx.scheduler.runAfter(0, internal.publishers.ensurePersonalPublisherInternal, {
+        userId: args.userId,
+      });
+
+      // Schedule GitHub profile sync to handle username renames (fixes #303)
+      // This runs as a background action so it doesn't block sign-in
+      const now = Date.now();
+      if (shouldScheduleGitHubProfileSync(user, now)) {
+        await ctx.scheduler.runAfter(0, internal.users.syncGitHubProfileAction, {
+          userId: args.userId,
+        });
+      }
    },
  },
-})
+});
@@ -0,0 +1,172 @@
+import { v } from "convex/values";
+import { internalMutation, mutation } from "./functions";
+import { requireUser } from "./lib/access";
+import { generateToken, hashToken } from "./lib/tokens";
+
+const DEVICE_CODE_TTL_MS = 15 * 60_000;
+const DEVICE_POLL_INTERVAL_SECONDS = 5;
+const USER_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+
+export const createInternal = internalMutation({
+  args: {
+    scope: v.optional(v.string()),
+    label: v.optional(v.string()),
+    siteUrl: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const deviceCode = generateOpaqueCode();
+    const userCode = generateUserCode();
+    const now = Date.now();
+    const label = (args.label?.trim() || "CLI device login").slice(0, 120);
+    const scope = (args.scope?.trim() || "read write").slice(0, 200);
+
+    await ctx.db.insert("cliDeviceCodes", {
+      deviceCodeHash: await hashToken(deviceCode),
+      userCodeHash: await hashToken(normalizeUserCode(userCode)),
+      userCode,
+      label,
+      scope,
+      status: "pending",
+      createdAt: now,
+      expiresAt: now + DEVICE_CODE_TTL_MS,
+    });
+
+    const verificationUrl = getVerificationUrl(args.siteUrl, userCode);
+
+    return {
+      device_code: deviceCode,
+      user_code: userCode,
+      verification_uri: verificationUrl.toString(),
+      expires_in: Math.floor(DEVICE_CODE_TTL_MS / 1000),
+      interval: DEVICE_POLL_INTERVAL_SECONDS,
+    };
+  },
+});
+
+export const pollInternal = internalMutation({
+  args: { deviceCode: v.string() },
+  handler: async (ctx, args) => {
+    const deviceCodeHash = await hashToken(args.deviceCode);
+    const row = await ctx.db
+      .query("cliDeviceCodes")
+      .withIndex("by_device_code_hash", (q) => q.eq("deviceCodeHash", deviceCodeHash))
+      .unique();
+    if (!row) return { error: "expired_token" as const };
+
+    const now = Date.now();
+    if (row.expiresAt <= now) {
+      if (row.status !== "expired") await ctx.db.patch(row._id, { status: "expired" });
+      return { error: "expired_token" as const };
+    }
+    if (row.status === "pending") return { error: "authorization_pending" as const };
+    if (row.status === "denied") return { error: "access_denied" as const };
+    if (row.status === "consumed" || row.status === "expired") {
+      return { error: "expired_token" as const };
+    }
+    if (!row.approvedByUserId) return { error: "authorization_pending" as const };
+
+    const { token, prefix } = generateToken();
+    await ctx.db.insert("apiTokens", {
+      userId: row.approvedByUserId,
+      label: row.label,
+      prefix,
+      tokenHash: await hashToken(token),
+      createdAt: now,
+      lastUsedAt: undefined,
+      revokedAt: undefined,
+    });
+    await ctx.db.patch(row._id, { status: "consumed", consumedAt: now });
+    return { access_token: token, token_type: "bearer" as const, scope: row.scope };
+  },
+});
+
+export const approve = mutation({
+  args: { userCode: v.string() },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx);
+    const normalized = normalizeUserCode(args.userCode);
+    if (!normalized) throw new Error("Code required");
+
+    const userCodeHash = await hashToken(normalized);
+    const row = await ctx.db
+      .query("cliDeviceCodes")
+      .withIndex("by_user_code_hash", (q) => q.eq("userCodeHash", userCodeHash))
+      .unique();
+    if (!row) throw new Error("Device code not found");
+
+    const now = Date.now();
+    if (row.expiresAt <= now) {
+      if (row.status !== "expired") await ctx.db.patch(row._id, { status: "expired" });
+      throw new Error("Device code expired");
+    }
+    if (row.status === "consumed") throw new Error("Device code already used");
+    if (row.status === "approved") throw new Error("Device code already authorized");
+    if (row.status === "denied") throw new Error("Device code was denied");
+
+    await ctx.db.patch(row._id, {
+      status: "approved",
+      approvedByUserId: userId,
+      approvedAt: now,
+    });
+    return { ok: true, userCode: row.userCode, expiresAt: row.expiresAt };
+  },
+});
+
+export const deny = mutation({
+  args: { userCode: v.string() },
+  handler: async (ctx, args) => {
+    await requireUser(ctx);
+    const normalized = normalizeUserCode(args.userCode);
+    if (!normalized) throw new Error("Code required");
+    const userCodeHash = await hashToken(normalized);
+    const row = await ctx.db
+      .query("cliDeviceCodes")
+      .withIndex("by_user_code_hash", (q) => q.eq("userCodeHash", userCodeHash))
+      .unique();
+    if (!row) throw new Error("Device code not found");
+    const now = Date.now();
+    if (row.status === "approved") throw new Error("Device code already authorized");
+    if (row.status === "pending") {
+      await ctx.db.patch(row._id, { status: "denied", deniedAt: now });
+    }
+    return { ok: true };
+  },
+});
+
+function normalizeUserCode(value: string) {
+  return value
+    .trim()
+    .toUpperCase()
+    .replace(/[^A-Z0-9]/g, "");
+}
+
+function generateUserCode() {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  const raw = Array.from(
+    bytes,
+    (byte) => USER_CODE_ALPHABET[byte % USER_CODE_ALPHABET.length],
+  ).join("");
+  return `${raw.slice(0, 4)}-${raw.slice(4)}`;
+}
+
+function generateOpaqueCode() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function getVerificationUrl(siteUrlValue: string | undefined, userCode: string) {
+  const baseUrl = siteUrlValue?.trim() || "https://clawhub.ai";
+  let verificationUrl: URL;
+  try {
+    verificationUrl = new URL("/cli/device", baseUrl);
+    if (verificationUrl.protocol !== "http:" && verificationUrl.protocol !== "https:") {
+      verificationUrl = new URL("/cli/device", "https://clawhub.ai");
+    }
+  } catch {
+    verificationUrl = new URL("/cli/device", "https://clawhub.ai");
+  }
+  verificationUrl.searchParams.set("code", userCode);
+  return verificationUrl;
+}
@@ -0,0 +1,290 @@
+/* @vitest-environment node */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("./_generated/api", () => ({
+  internal: {
+    commentModeration: {
+      getCommentScamBackfillPageInternal: Symbol(
+        "commentModeration.getCommentScamBackfillPageInternal",
+      ),
+      applyCommentScamResultInternal: Symbol("commentModeration.applyCommentScamResultInternal"),
+      backfillCommentScamModerationInternal: Symbol(
+        "commentModeration.backfillCommentScamModerationInternal",
+      ),
+      continueCommentScamModerationJobInternal: Symbol(
+        "commentModeration.continueCommentScamModerationJobInternal",
+      ),
+    },
+    llmEval: {
+      evaluateCommentForScam: Symbol("llmEval.evaluateCommentForScam"),
+    },
+    users: {
+      banUserInternal: Symbol("users.banUserInternal"),
+    },
+  },
+}));
+
+const { applyCommentScamResultInternalHandler, backfillCommentScamModerationInternalHandler } =
+  await import("./commentModeration");
+const { internal } = await import("./_generated/api");
+
+const previousOpenAiApiKey = process.env.OPENAI_API_KEY;
+
+beforeEach(() => {
+  process.env.OPENAI_API_KEY = "test-key";
+});
+
+afterEach(() => {
+  if (previousOpenAiApiKey === undefined) {
+    delete process.env.OPENAI_API_KEY;
+    return;
+  }
+  process.env.OPENAI_API_KEY = previousOpenAiApiKey;
+});
+
+describe("commentModeration backfill", () => {
+  it("evaluates comments and bans on certain/high scams", async () => {
+    const runQuery = vi.fn().mockResolvedValueOnce({
+      items: [
+        {
+          commentId: "comments:1",
+          skillId: "skills:1",
+          userId: "users:2",
+          body: 'echo "mal" | base64 -D | bash',
+          softDeletedAt: undefined,
+          scamScanCheckedAt: undefined,
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    });
+    const runAction = vi.fn().mockResolvedValue({
+      ok: true,
+      model: "gpt-5-mini",
+      verdict: "certain_scam",
+      confidence: "high",
+      explanation: "Obfuscated shell execution payload.",
+      evidence: ["base64 decode piped to bash"],
+    });
+    const runMutation = vi.fn().mockResolvedValue({
+      ok: true,
+      shouldBan: true,
+      banned: true,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: false,
+    });
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: "users:admin",
+        dryRun: false,
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.stats.commentsScanned).toBe(1);
+    expect(result.stats.commentsEvaluated).toBe(1);
+    expect(result.stats.certainScams).toBe(1);
+    expect(result.stats.banCandidates).toBe(1);
+    expect(result.stats.usersBanned).toBe(1);
+    expect(runAction).toHaveBeenCalledWith(internal.llmEval.evaluateCommentForScam, {
+      commentId: "comments:1",
+      skillId: "skills:1",
+      userId: "users:2",
+      body: 'echo "mal" | base64 -D | bash',
+    });
+    expect(runMutation).toHaveBeenCalledWith(
+      internal.commentModeration.applyCommentScamResultInternal,
+      {
+        actorUserId: "users:admin",
+        commentId: "comments:1",
+        verdict: "certain_scam",
+        confidence: "high",
+        explanation: "Obfuscated shell execution payload.",
+        evidence: ["base64 decode piped to bash"],
+        model: "gpt-5-mini",
+        checkedAt: expect.any(Number),
+        dryRun: false,
+      },
+    );
+  });
+
+  it("skips previously scanned comments unless rescan=true", async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          commentId: "comments:1",
+          skillId: "skills:1",
+          userId: "users:2",
+          body: "something",
+          softDeletedAt: undefined,
+          scamScanCheckedAt: 123,
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    });
+    const runAction = vi.fn();
+    const runMutation = vi.fn();
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: "users:admin",
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    );
+
+    expect(result.stats.commentsScanned).toBe(1);
+    expect(result.stats.skippedAlreadyScanned).toBe(1);
+    expect(runAction).not.toHaveBeenCalled();
+    expect(runMutation).not.toHaveBeenCalled();
+  });
+
+  it("tracks dry-run ban candidates without banning", async () => {
+    const runQuery = vi.fn().mockResolvedValue({
+      items: [
+        {
+          commentId: "comments:9",
+          skillId: "skills:7",
+          userId: "users:5",
+          body: "run this update installer from random domain",
+          softDeletedAt: undefined,
+          scamScanCheckedAt: undefined,
+        },
+      ],
+      cursor: null,
+      isDone: true,
+    });
+    const runAction = vi.fn().mockResolvedValue({
+      ok: true,
+      model: "gpt-5-mini",
+      verdict: "certain_scam",
+      confidence: "high",
+      explanation: "Social-engineering install command.",
+      evidence: ["unknown update domain"],
+    });
+    const runMutation = vi.fn().mockResolvedValue({
+      ok: true,
+      shouldBan: true,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: true,
+    });
+
+    const result = await backfillCommentScamModerationInternalHandler(
+      { runQuery, runAction, runMutation } as never,
+      {
+        actorUserId: "users:admin",
+        dryRun: true,
+        batchSize: 10,
+        maxBatches: 1,
+      } as never,
+    );
+
+    expect(result.stats.usersBanned).toBe(0);
+    expect(result.stats.usersWouldBeBanned).toBe(1);
+  });
+});
+
+describe("applyCommentScamResultInternalHandler", () => {
+  it("persists scan metadata and triggers ban with bounded reason", async () => {
+    const get = vi
+      .fn()
+      .mockResolvedValueOnce({
+        _id: "comments:1",
+        skillId: "skills:1",
+        userId: "users:2",
+      })
+      .mockResolvedValueOnce({
+        _id: "users:2",
+        role: "user",
+      });
+    const patch = vi.fn();
+    const insert = vi.fn();
+    const runMutation = vi
+      .fn()
+      .mockResolvedValue({ ok: true, alreadyBanned: false, deletedSkills: 0 });
+
+    const result = await applyCommentScamResultInternalHandler(
+      { db: { get, patch, insert }, runMutation } as never,
+      {
+        actorUserId: "users:admin",
+        commentId: "comments:1",
+        verdict: "certain_scam",
+        confidence: "high",
+        explanation: "X".repeat(700),
+        evidence: ["Y".repeat(280), "Z".repeat(280)],
+        model: "gpt-5-mini",
+        checkedAt: 123,
+      } as never,
+    );
+
+    expect(result.banned).toBe(true);
+    expect(insert).toHaveBeenCalledWith("auditLogs", {
+      actorUserId: "users:admin",
+      action: "comment.scam_scan",
+      targetType: "comment",
+      targetId: "comments:1",
+      metadata: {
+        skillId: "skills:1",
+        commentAuthorId: "users:2",
+        verdict: "certain_scam",
+        confidence: "high",
+        shouldBan: true,
+        model: "gpt-5-mini",
+      },
+      createdAt: 123,
+    });
+
+    const banCall = runMutation.mock.calls.find(
+      (call) => call[0] === internal.users.banUserInternal,
+    );
+    expect(banCall).toBeTruthy();
+    if (!banCall) throw new Error("Expected ban mutation to be called");
+    expect((banCall[1] as { reason: string }).reason.length).toBeLessThanOrEqual(500);
+    expect(patch).toHaveBeenCalledWith("comments:1", {
+      scamBanTriggeredAt: 123,
+    });
+  });
+
+  it("skips banning moderator/admin accounts", async () => {
+    const get = vi
+      .fn()
+      .mockResolvedValueOnce({
+        _id: "comments:2",
+        skillId: "skills:2",
+        userId: "users:staff",
+      })
+      .mockResolvedValueOnce({
+        _id: "users:staff",
+        role: "moderator",
+      });
+    const patch = vi.fn();
+    const insert = vi.fn();
+    const runMutation = vi.fn();
+
+    const result = await applyCommentScamResultInternalHandler(
+      { db: { get, patch, insert }, runMutation } as never,
+      {
+        actorUserId: "users:admin",
+        commentId: "comments:2",
+        verdict: "certain_scam",
+        confidence: "high",
+        explanation: "Malicious command spam.",
+        evidence: ["base64|bash"],
+        model: "gpt-5-mini",
+        checkedAt: 300,
+      } as never,
+    );
+
+    expect(result.protectedRole).toBe(true);
+    expect(runMutation).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,479 @@
+import { ConvexError, v } from "convex/values";
+import { internal } from "./_generated/api";
+import type { Id } from "./_generated/dataModel";
+import type { ActionCtx, MutationCtx } from "./_generated/server";
+import { action, internalAction, internalMutation, internalQuery } from "./functions";
+import { assertRole, requireUserFromAction } from "./lib/access";
+import {
+  buildCommentScamBanReason,
+  isCertainScam,
+  type CommentScamConfidence,
+  type CommentScamVerdict,
+} from "./lib/commentScamPrompt";
+
+const DEFAULT_BATCH_SIZE = 25;
+const MAX_BATCH_SIZE = 100;
+const DEFAULT_MAX_BATCHES = 10;
+const MAX_MAX_BATCHES = 200;
+
+type CommentBackfillPageItem = {
+  commentId: Id<"comments">;
+  skillId: Id<"skills">;
+  userId: Id<"users">;
+  body: string;
+  softDeletedAt?: number;
+  scamScanCheckedAt?: number;
+};
+
+type CommentBackfillPageResult = {
+  items: CommentBackfillPageItem[];
+  cursor: string | null;
+  isDone: boolean;
+};
+
+type ApplyCommentScamResult = {
+  ok: true;
+  shouldBan: boolean;
+  banned: boolean;
+  alreadyBanned: boolean;
+  protectedRole: boolean;
+  wouldBan: boolean;
+};
+
+export type CommentScamBackfillStats = {
+  commentsScanned: number;
+  commentsEvaluated: number;
+  certainScams: number;
+  banCandidates: number;
+  usersBanned: number;
+  usersAlreadyBanned: number;
+  usersWouldBeBanned: number;
+  protectedRoleSkips: number;
+  skippedSoftDeleted: number;
+  skippedAlreadyScanned: number;
+  skippedEmptyBody: number;
+  evalErrors: number;
+};
+
+export type CommentScamBackfillActionArgs = {
+  actorUserId: Id<"users">;
+  dryRun?: boolean;
+  batchSize?: number;
+  maxBatches?: number;
+  cursor?: string;
+  rescan?: boolean;
+  includeSoftDeleted?: boolean;
+};
+
+export type CommentScamBackfillActionResult = {
+  ok: true;
+  stats: CommentScamBackfillStats;
+  isDone: boolean;
+  cursor: string | null;
+};
+
+export const getCommentScamBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<CommentBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+    const { page, isDone, continueCursor } = await ctx.db
+      .query("comments")
+      .order("asc")
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+
+    return {
+      items: page.map((comment) => ({
+        commentId: comment._id,
+        skillId: comment.skillId,
+        userId: comment.userId,
+        body: comment.body,
+        softDeletedAt: comment.softDeletedAt,
+        scamScanCheckedAt: comment.scamScanCheckedAt,
+      })),
+      cursor: continueCursor,
+      isDone,
+    };
+  },
+});
+
+export async function applyCommentScamResultInternalHandler(
+  ctx: MutationCtx,
+  args: {
+    actorUserId: Id<"users">;
+    commentId: Id<"comments">;
+    verdict: CommentScamVerdict;
+    confidence: CommentScamConfidence;
+    explanation: string;
+    evidence: string[];
+    model: string;
+    checkedAt: number;
+    dryRun?: boolean;
+  },
+): Promise<ApplyCommentScamResult> {
+  const comment = await ctx.db.get(args.commentId);
+  if (!comment) {
+    throw new ConvexError("Comment not found");
+  }
+
+  const user = await ctx.db.get(comment.userId);
+  if (!user) {
+    throw new ConvexError("Comment author not found");
+  }
+
+  const dryRun = Boolean(args.dryRun);
+  const shouldBan = isCertainScam({
+    verdict: args.verdict,
+    confidence: args.confidence,
+  });
+
+  const explanation = args.explanation.trim().slice(0, 1200);
+  const evidence = args.evidence
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .slice(0, 5);
+
+  if (!dryRun) {
+    await ctx.db.patch(comment._id, {
+      scamScanVerdict: args.verdict,
+      scamScanConfidence: args.confidence,
+      scamScanExplanation: explanation,
+      scamScanEvidence: evidence,
+      scamScanModel: args.model,
+      scamScanCheckedAt: args.checkedAt,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      actorUserId: args.actorUserId,
+      action: "comment.scam_scan",
+      targetType: "comment",
+      targetId: comment._id,
+      metadata: {
+        skillId: comment.skillId,
+        commentAuthorId: comment.userId,
+        verdict: args.verdict,
+        confidence: args.confidence,
+        shouldBan,
+        model: args.model,
+      },
+      createdAt: args.checkedAt,
+    });
+  }
+
+  if (!shouldBan) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: false,
+    };
+  }
+
+  if (user.role === "admin" || user.role === "moderator") {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: true,
+      wouldBan: false,
+    };
+  }
+
+  if (user.deletedAt || user.deactivatedAt) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: true,
+      protectedRole: false,
+      wouldBan: false,
+    };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      shouldBan,
+      banned: false,
+      alreadyBanned: false,
+      protectedRole: false,
+      wouldBan: true,
+    };
+  }
+
+  const reason = buildCommentScamBanReason({
+    commentId: String(comment._id),
+    skillId: String(comment.skillId),
+    explanation,
+    evidence,
+  });
+
+  const banResult = await ctx.runMutation(internal.users.banUserInternal, {
+    actorUserId: args.actorUserId,
+    targetUserId: comment.userId,
+    reason,
+  });
+
+  if (!banResult.alreadyBanned) {
+    await ctx.db.patch(comment._id, {
+      scamBanTriggeredAt: args.checkedAt,
+    });
+  }
+
+  return {
+    ok: true,
+    shouldBan,
+    banned: !banResult.alreadyBanned,
+    alreadyBanned: banResult.alreadyBanned,
+    protectedRole: false,
+    wouldBan: false,
+  };
+}
+
+export const applyCommentScamResultInternal = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    commentId: v.id("comments"),
+    verdict: v.union(v.literal("not_scam"), v.literal("likely_scam"), v.literal("certain_scam")),
+    confidence: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
+    explanation: v.string(),
+    evidence: v.array(v.string()),
+    model: v.string(),
+    checkedAt: v.number(),
+    dryRun: v.optional(v.boolean()),
+  },
+  handler: applyCommentScamResultInternalHandler,
+});
+
+export async function backfillCommentScamModerationInternalHandler(
+  ctx: ActionCtx,
+  args: CommentScamBackfillActionArgs,
+): Promise<CommentScamBackfillActionResult> {
+  if (!process.env.OPENAI_API_KEY) {
+    throw new ConvexError("OPENAI_API_KEY not configured");
+  }
+
+  const dryRun = Boolean(args.dryRun);
+  const rescan = Boolean(args.rescan);
+  const includeSoftDeleted = Boolean(args.includeSoftDeleted);
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES);
+
+  let cursor: string | null = args.cursor ?? null;
+  let isDone = false;
+
+  const stats: CommentScamBackfillStats = {
+    commentsScanned: 0,
+    commentsEvaluated: 0,
+    certainScams: 0,
+    banCandidates: 0,
+    usersBanned: 0,
+    usersAlreadyBanned: 0,
+    usersWouldBeBanned: 0,
+    protectedRoleSkips: 0,
+    skippedSoftDeleted: 0,
+    skippedAlreadyScanned: 0,
+    skippedEmptyBody: 0,
+    evalErrors: 0,
+  };
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(
+      internal.commentModeration.getCommentScamBackfillPageInternal,
+      {
+        cursor: cursor ?? undefined,
+        batchSize,
+      },
+    )) as CommentBackfillPageResult;
+
+    cursor = page.cursor;
+    isDone = page.isDone;
+
+    for (const comment of page.items) {
+      stats.commentsScanned++;
+
+      if (!includeSoftDeleted && comment.softDeletedAt) {
+        stats.skippedSoftDeleted++;
+        continue;
+      }
+      if (!rescan && comment.scamScanCheckedAt) {
+        stats.skippedAlreadyScanned++;
+        continue;
+      }
+
+      const body = comment.body.trim();
+      if (!body) {
+        stats.skippedEmptyBody++;
+        continue;
+      }
+
+      const evalResult = (await ctx.runAction(internal.llmEval.evaluateCommentForScam, {
+        commentId: comment.commentId,
+        skillId: comment.skillId,
+        userId: comment.userId,
+        body,
+      })) as
+        | {
+            ok: true;
+            model: string;
+            verdict: CommentScamVerdict;
+            confidence: CommentScamConfidence;
+            explanation: string;
+            evidence: string[];
+          }
+        | { ok: false; error: string };
+
+      if (!evalResult.ok) {
+        stats.evalErrors++;
+        continue;
+      }
+
+      stats.commentsEvaluated++;
+      const shouldBan = isCertainScam(evalResult);
+      if (evalResult.verdict === "certain_scam") {
+        stats.certainScams++;
+      }
+      if (shouldBan) {
+        stats.banCandidates++;
+      }
+
+      const applyResult = (await ctx.runMutation(
+        internal.commentModeration.applyCommentScamResultInternal,
+        {
+          actorUserId: args.actorUserId,
+          commentId: comment.commentId,
+          verdict: evalResult.verdict,
+          confidence: evalResult.confidence,
+          explanation: evalResult.explanation,
+          evidence: evalResult.evidence,
+          model: evalResult.model,
+          checkedAt: Date.now(),
+          dryRun,
+        },
+      )) as ApplyCommentScamResult;
+
+      if (applyResult.banned) stats.usersBanned++;
+      if (applyResult.alreadyBanned) stats.usersAlreadyBanned++;
+      if (applyResult.wouldBan) stats.usersWouldBeBanned++;
+      if (applyResult.protectedRole) stats.protectedRoleSkips++;
+    }
+
+    if (isDone) break;
+  }
+
+  return {
+    ok: true,
+    stats,
+    isDone,
+    cursor,
+  };
+}
+
+export const backfillCommentScamModerationInternal = internalAction({
+  args: {
+    actorUserId: v.id("users"),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: backfillCommentScamModerationInternalHandler,
+});
+
+export const backfillCommentScamModeration: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<CommentScamBackfillActionResult> => {
+    const { user } = await requireUserFromAction(ctx);
+    assertRole(user, ["admin", "moderator"]);
+
+    return ctx.runAction(internal.commentModeration.backfillCommentScamModerationInternal, {
+      actorUserId: user._id,
+      ...args,
+    }) as Promise<CommentScamBackfillActionResult>;
+  },
+});
+
+export const continueCommentScamModerationJobInternal = internalAction({
+  args: {
+    actorUserId: v.id("users"),
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const result = await backfillCommentScamModerationInternalHandler(ctx, {
+      actorUserId: args.actorUserId,
+      dryRun: args.dryRun,
+      batchSize: args.batchSize,
+      cursor: args.cursor,
+      maxBatches: 1,
+      rescan: args.rescan,
+      includeSoftDeleted: args.includeSoftDeleted,
+    });
+
+    if (!result.isDone && result.cursor) {
+      await ctx.scheduler.runAfter(
+        2_000,
+        internal.commentModeration.continueCommentScamModerationJobInternal,
+        {
+          actorUserId: args.actorUserId,
+          dryRun: Boolean(args.dryRun),
+          batchSize: args.batchSize ?? DEFAULT_BATCH_SIZE,
+          cursor: result.cursor,
+          rescan: Boolean(args.rescan),
+          includeSoftDeleted: Boolean(args.includeSoftDeleted),
+        },
+      );
+    }
+
+    return result;
+  },
+});
+
+export const scheduleCommentScamModeration: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    batchSize: v.optional(v.number()),
+    rescan: v.optional(v.boolean()),
+    includeSoftDeleted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<{ ok: true }> => {
+    const { user } = await requireUserFromAction(ctx);
+    assertRole(user, ["admin", "moderator"]);
+
+    await ctx.scheduler.runAfter(
+      0,
+      internal.commentModeration.continueCommentScamModerationJobInternal,
+      {
+        actorUserId: user._id,
+        dryRun: Boolean(args.dryRun),
+        batchSize: clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE),
+        cursor: undefined,
+        rescan: Boolean(args.rescan),
+        includeSoftDeleted: Boolean(args.includeSoftDeleted),
+      },
+    );
+
+    return { ok: true as const };
+  },
+});
+
+function clampInt(value: number, min: number, max: number) {
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
@@ -1,52 +1,151 @@
-import type { Id } from './_generated/dataModel'
-import type { MutationCtx } from './_generated/server'
-import { assertModerator, requireUser } from './lib/access'
-import { insertStatEvent } from './skillStatEvents'
+import type { Id } from "./_generated/dataModel";
+import type { MutationCtx } from "./_generated/server";
+import { assertModerator, requireUser } from "./lib/access";
+import { requireGitHubAccountAge } from "./lib/githubAccount";
+import {
+  AUTO_HIDE_REPORT_THRESHOLD,
+  MAX_ACTIVE_REPORTS_PER_USER,
+  MAX_REPORT_REASON_LENGTH,
+} from "./lib/reporting";
+import { insertStatEvent } from "./skillStatEvents";

-export async function addHandler(ctx: MutationCtx, args: { skillId: Id<'skills'>; body: string }) {
-  const { userId } = await requireUser(ctx)
-  const body = args.body.trim()
-  if (!body) throw new Error('Comment body required')
+export async function addHandler(ctx: MutationCtx, args: { skillId: Id<"skills">; body: string }) {
+  const { userId } = await requireUser(ctx);
+  await requireGitHubAccountAge(ctx, userId);

-  const skill = await ctx.db.get(args.skillId)
-  if (!skill) throw new Error('Skill not found')
+  const body = args.body.trim();
+  if (!body) throw new Error("Comment body required");

-  await ctx.db.insert('comments', {
+  const skill = await ctx.db.get(args.skillId);
+  if (!skill) throw new Error("Skill not found");
+
+  await ctx.db.insert("comments", {
    skillId: args.skillId,
    userId,
    body,
    createdAt: Date.now(),
    softDeletedAt: undefined,
    deletedBy: undefined,
-  })
+  });

-  await insertStatEvent(ctx, { skillId: skill._id, kind: 'comment' })
+  await insertStatEvent(ctx, { skillId: skill._id, kind: "comment" });
 }

-export async function removeHandler(ctx: MutationCtx, args: { commentId: Id<'comments'> }) {
-  const { user } = await requireUser(ctx)
-  const comment = await ctx.db.get(args.commentId)
-  if (!comment) throw new Error('Comment not found')
-  if (comment.softDeletedAt) return
+export async function removeHandler(ctx: MutationCtx, args: { commentId: Id<"comments"> }) {
+  const { user } = await requireUser(ctx);
+  const comment = await ctx.db.get(args.commentId);
+  if (!comment) throw new Error("Comment not found");
+  if (comment.softDeletedAt) return;

-  const isOwner = comment.userId === user._id
+  const isOwner = comment.userId === user._id;
  if (!isOwner) {
-    assertModerator(user)
+    assertModerator(user);
  }

  await ctx.db.patch(comment._id, {
    softDeletedAt: Date.now(),
    deletedBy: user._id,
-  })
+  });

-  await insertStatEvent(ctx, { skillId: comment.skillId, kind: 'uncomment' })
+  await insertStatEvent(ctx, { skillId: comment.skillId, kind: "uncomment" });

-  await ctx.db.insert('auditLogs', {
+  await ctx.db.insert("auditLogs", {
    actorUserId: user._id,
-    action: 'comment.delete',
-    targetType: 'comment',
+    action: "comment.delete",
+    targetType: "comment",
    targetId: comment._id,
    metadata: { skillId: comment.skillId },
    createdAt: Date.now(),
-  })
+  });
+}
+
+async function countActiveReportsForUser(ctx: MutationCtx, userId: Id<"users">) {
+  const reports = await ctx.db
+    .query("commentReports")
+    .withIndex("by_user", (q) => q.eq("userId", userId))
+    .collect();
+
+  let count = 0;
+  for (const report of reports) {
+    const comment = await ctx.db.get(report.commentId);
+    if (!comment || comment.softDeletedAt) continue;
+    const skill = await ctx.db.get(comment.skillId);
+    if (!skill || skill.softDeletedAt || skill.moderationStatus === "removed") continue;
+    const owner = await ctx.db.get(comment.userId);
+    if (!owner || owner.deletedAt || owner.deactivatedAt) continue;
+    count += 1;
+    if (count >= MAX_ACTIVE_REPORTS_PER_USER) break;
+  }
+
+  return count;
+}
+
+export async function reportHandler(
+  ctx: MutationCtx,
+  args: { commentId: Id<"comments">; reason: string },
+) {
+  const { userId } = await requireUser(ctx);
+  const comment = await ctx.db.get(args.commentId);
+  if (!comment || comment.softDeletedAt) {
+    throw new Error("Comment not found");
+  }
+  const skill = await ctx.db.get(comment.skillId);
+  if (!skill || skill.softDeletedAt || skill.moderationStatus === "removed") {
+    throw new Error("Comment not found");
+  }
+
+  const reason = args.reason.trim();
+  if (!reason) {
+    throw new Error("Report reason required.");
+  }
+
+  const existing = await ctx.db
+    .query("commentReports")
+    .withIndex("by_comment_user", (q) => q.eq("commentId", args.commentId).eq("userId", userId))
+    .unique();
+  if (existing) return { ok: true as const, reported: false, alreadyReported: true };
+
+  const activeReports = await countActiveReportsForUser(ctx, userId);
+  if (activeReports >= MAX_ACTIVE_REPORTS_PER_USER) {
+    throw new Error("Report limit reached. Please wait for moderation before reporting more.");
+  }
+
+  const now = Date.now();
+  await ctx.db.insert("commentReports", {
+    commentId: args.commentId,
+    skillId: comment.skillId,
+    userId,
+    reason: reason.slice(0, MAX_REPORT_REASON_LENGTH),
+    createdAt: now,
+  });
+
+  const nextReportCount = (comment.reportCount ?? 0) + 1;
+  const shouldAutoHide = nextReportCount > AUTO_HIDE_REPORT_THRESHOLD && !comment.softDeletedAt;
+  const updates: {
+    reportCount: number;
+    lastReportedAt: number;
+    softDeletedAt?: number;
+  } = {
+    reportCount: nextReportCount,
+    lastReportedAt: now,
+  };
+  if (shouldAutoHide) {
+    updates.softDeletedAt = now;
+  }
+  await ctx.db.patch(comment._id, updates);
+
+  if (shouldAutoHide) {
+    await insertStatEvent(ctx, { skillId: comment.skillId, kind: "uncomment" });
+
+    await ctx.db.insert("auditLogs", {
+      actorUserId: userId,
+      action: "comment.auto_hide",
+      targetType: "comment",
+      targetId: comment._id,
+      metadata: { skillId: comment.skillId, reportCount: nextReportCount },
+      createdAt: now,
+    });
+  }
+
+  return { ok: true as const, reported: true, alreadyReported: false };
 }
@@ -0,0 +1,127 @@
+/* @vitest-environment node */
+import { describe, expect, it } from "vitest";
+import { listBySkillHandler } from "./comments";
+
+function makeCtx(args: {
+  comments: Array<Record<string, unknown>>;
+  usersById: Record<string, Record<string, unknown> | null>;
+}) {
+  const get = async (id: string) => args.usersById[id] ?? null;
+  const take = async () => args.comments;
+  const order = () => ({ take });
+  const withIndex = () => ({ order });
+  const query = () => ({ withIndex });
+  return { db: { get, query } } as never;
+}
+
+describe("comments.listBySkill", () => {
+  it("skips soft-deleted comments", async () => {
+    const ctx = makeCtx({
+      comments: [
+        {
+          _id: "comments:live",
+          skillId: "skills:1",
+          userId: "users:live",
+          body: "hello",
+        },
+        {
+          _id: "comments:deleted",
+          skillId: "skills:1",
+          userId: "users:live",
+          body: "bye",
+          softDeletedAt: 123,
+        },
+      ],
+      usersById: {
+        "users:live": {
+          _id: "users:live",
+          _creationTime: 1,
+          handle: "live",
+          name: "live",
+          displayName: "Live",
+          image: null,
+          bio: null,
+        },
+      },
+    });
+
+    const result = await listBySkillHandler(ctx, {
+      skillId: "skills:1",
+      limit: 50,
+    } as never);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.comment._id).toBe("comments:live");
+  });
+
+  it("skips comments whose author is deleted/deactivated/missing", async () => {
+    const ctx = makeCtx({
+      comments: [
+        {
+          _id: "comments:ok",
+          skillId: "skills:1",
+          userId: "users:ok",
+          body: "ok",
+        },
+        {
+          _id: "comments:deleted-user",
+          skillId: "skills:1",
+          userId: "users:deleted",
+          body: "hidden",
+        },
+        {
+          _id: "comments:deactivated-user",
+          skillId: "skills:1",
+          userId: "users:deactivated",
+          body: "hidden",
+        },
+        {
+          _id: "comments:missing-user",
+          skillId: "skills:1",
+          userId: "users:missing",
+          body: "hidden",
+        },
+      ],
+      usersById: {
+        "users:ok": {
+          _id: "users:ok",
+          _creationTime: 1,
+          handle: "ok",
+          name: "ok",
+          displayName: "Ok",
+          image: null,
+          bio: null,
+        },
+        "users:deleted": {
+          _id: "users:deleted",
+          _creationTime: 1,
+          handle: "deleted",
+          name: "deleted",
+          displayName: "Deleted",
+          image: null,
+          bio: null,
+          deletedAt: 123,
+        },
+        "users:deactivated": {
+          _id: "users:deactivated",
+          _creationTime: 1,
+          handle: "deactivated",
+          name: "deactivated",
+          displayName: "Deactivated",
+          image: null,
+          bio: null,
+          deactivatedAt: 456,
+        },
+      },
+    });
+
+    const result = await listBySkillHandler(ctx, {
+      skillId: "skills:1",
+      limit: 50,
+    } as never);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.comment._id).toBe("comments:ok");
+    expect(result[0]?.user._id).toBe("users:ok");
+  });
+});
@@ -1,127 +1,614 @@
 /* @vitest-environment node */
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from "vitest";

-vi.mock('./lib/access', () => ({
+vi.mock("./lib/access", () => ({
  assertModerator: vi.fn(),
  requireUser: vi.fn(),
-}))
+}));

-vi.mock('./skillStatEvents', () => ({
+vi.mock("./skillStatEvents", () => ({
  insertStatEvent: vi.fn(),
-}))
+}));

-const { requireUser, assertModerator } = await import('./lib/access')
-const { insertStatEvent } = await import('./skillStatEvents')
-const { addHandler, removeHandler } = await import('./comments.handlers')
+vi.mock("./lib/githubAccount", () => ({
+  requireGitHubAccountAge: vi.fn(),
+}));

-describe('comments mutations', () => {
+const { requireUser, assertModerator } = await import("./lib/access");
+const { insertStatEvent } = await import("./skillStatEvents");
+const { requireGitHubAccountAge } = await import("./lib/githubAccount");
+const { addHandler, removeHandler, reportHandler } = await import("./comments.handlers");
+
+describe("comments mutations", () => {
  afterEach(() => {
-    vi.mocked(assertModerator).mockReset()
-    vi.mocked(requireUser).mockReset()
-    vi.mocked(insertStatEvent).mockReset()
-  })
+    vi.mocked(assertModerator).mockReset();
+    vi.mocked(requireUser).mockReset();
+    vi.mocked(insertStatEvent).mockReset();
+    vi.mocked(requireGitHubAccountAge).mockReset();
+    vi.restoreAllMocks();
+  });

-  it('add avoids direct skill patch and records stat event', async () => {
+  it("add avoids direct skill patch and records stat event", async () => {
    vi.mocked(requireUser).mockResolvedValue({
-      userId: 'users:1',
-      user: { _id: 'users:1', role: 'user' },
-    } as never)
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+    vi.mocked(requireGitHubAccountAge).mockResolvedValue(undefined as never);

    const get = vi.fn().mockResolvedValue({
-      _id: 'skills:1',
-    })
-    const insert = vi.fn()
-    const patch = vi.fn()
-    const ctx = { db: { get, insert, patch } } as never
+      _id: "skills:1",
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const ctx = { db: { get, insert, patch } } as never;

-    await addHandler(ctx, { skillId: 'skills:1', body: ' hello ' } as never)
+    await addHandler(ctx, { skillId: "skills:1", body: " hello " } as never);

-    expect(patch).not.toHaveBeenCalled()
+    expect(requireGitHubAccountAge).toHaveBeenCalledWith(ctx, "users:1");
+    expect(patch).not.toHaveBeenCalled();
    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
-      skillId: 'skills:1',
-      kind: 'comment',
-    })
-  })
+      skillId: "skills:1",
+      kind: "comment",
+    });
+  });

-  it('remove keeps comment soft-delete patch free of updatedAt', async () => {
+  it("add blocks new comments when github account age gate fails", async () => {
    vi.mocked(requireUser).mockResolvedValue({
-      userId: 'users:2',
-      user: { _id: 'users:2', role: 'moderator' },
-    } as never)
+      userId: "users:new",
+      user: { _id: "users:new", role: "user" },
+    } as never);
+    vi.mocked(requireGitHubAccountAge).mockRejectedValue(
+      new Error(
+        "GitHub account must be at least 14 days old to upload skills. Try again in 3 days.",
+      ),
+    );
+
+    const get = vi.fn();
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const ctx = { db: { get, insert, patch } } as never;
+
+    await expect(addHandler(ctx, { skillId: "skills:1", body: "hello" } as never)).rejects.toThrow(
+      /at least 14 days old/i,
+    );
+
+    expect(get).not.toHaveBeenCalled();
+    expect(insert).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalled();
+    expect(insertStatEvent).not.toHaveBeenCalled();
+  });
+
+  it("remove keeps comment soft-delete patch free of updatedAt", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:2",
+      user: { _id: "users:2", role: "moderator" },
+    } as never);

    const comment = {
-      _id: 'comments:1',
-      skillId: 'skills:1',
-      userId: 'users:2',
+      _id: "comments:1",
+      skillId: "skills:1",
+      userId: "users:2",
      softDeletedAt: undefined,
-    }
+    };
    const get = vi.fn(async (id: string) => {
-      if (id === 'comments:1') return comment
-      return null
-    })
-    const insert = vi.fn()
-    const patch = vi.fn()
-    const ctx = { db: { get, insert, patch } } as never
+      if (id === "comments:1") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const ctx = { db: { get, insert, patch } } as never;

-    await removeHandler(ctx, { commentId: 'comments:1' } as never)
+    await removeHandler(ctx, { commentId: "comments:1" } as never);

-    expect(patch).toHaveBeenCalledTimes(1)
-    const deletePatch = vi.mocked(patch).mock.calls[0]?.[1] as Record<string, unknown>
-    expect(deletePatch.updatedAt).toBeUndefined()
+    expect(patch).toHaveBeenCalledTimes(1);
+    const deletePatch = vi.mocked(patch).mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(deletePatch.updatedAt).toBeUndefined();
    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
-      skillId: 'skills:1',
-      kind: 'uncomment',
-    })
-  })
+      skillId: "skills:1",
+      kind: "uncomment",
+    });
+  });

-  it('remove rejects non-owner without moderator permission', async () => {
+  it("remove rejects non-owner without moderator permission", async () => {
    vi.mocked(requireUser).mockResolvedValue({
-      userId: 'users:3',
-      user: { _id: 'users:3', role: 'user' },
-    } as never)
+      userId: "users:3",
+      user: { _id: "users:3", role: "user" },
+    } as never);
    vi.mocked(assertModerator).mockImplementation(() => {
-      throw new Error('Moderator role required')
-    })
+      throw new Error("Moderator role required");
+    });

    const comment = {
-      _id: 'comments:2',
-      skillId: 'skills:2',
-      userId: 'users:9',
+      _id: "comments:2",
+      skillId: "skills:2",
+      userId: "users:9",
      softDeletedAt: undefined,
-    }
-    const get = vi.fn().mockResolvedValue(comment)
-    const insert = vi.fn()
-    const patch = vi.fn()
-    const ctx = { db: { get, insert, patch } } as never
+    };
+    const get = vi.fn().mockResolvedValue(comment);
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const ctx = { db: { get, insert, patch } } as never;

-    await expect(removeHandler(ctx, { commentId: 'comments:2' } as never)).rejects.toThrow(
-      'Moderator role required',
-    )
-    expect(patch).not.toHaveBeenCalled()
-    expect(insertStatEvent).not.toHaveBeenCalled()
-  })
+    await expect(removeHandler(ctx, { commentId: "comments:2" } as never)).rejects.toThrow(
+      "Moderator role required",
+    );
+    expect(patch).not.toHaveBeenCalled();
+    expect(insertStatEvent).not.toHaveBeenCalled();
+  });

-  it('remove no-ops for soft-deleted comment', async () => {
+  it("remove no-ops for soft-deleted comment", async () => {
    vi.mocked(requireUser).mockResolvedValue({
-      userId: 'users:4',
-      user: { _id: 'users:4', role: 'moderator' },
-    } as never)
+      userId: "users:4",
+      user: { _id: "users:4", role: "moderator" },
+    } as never);

    const comment = {
-      _id: 'comments:3',
-      skillId: 'skills:3',
-      userId: 'users:4',
+      _id: "comments:3",
+      skillId: "skills:3",
+      userId: "users:4",
      softDeletedAt: 123,
-    }
-    const get = vi.fn().mockResolvedValue(comment)
-    const insert = vi.fn()
-    const patch = vi.fn()
-    const ctx = { db: { get, insert, patch } } as never
+    };
+    const get = vi.fn().mockResolvedValue(comment);
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const ctx = { db: { get, insert, patch } } as never;

-    await removeHandler(ctx, { commentId: 'comments:3' } as never)
+    await removeHandler(ctx, { commentId: "comments:3" } as never);

-    expect(patch).not.toHaveBeenCalled()
-    expect(insert).not.toHaveBeenCalled()
-    expect(insertStatEvent).not.toHaveBeenCalled()
-  })
-})
+    expect(patch).not.toHaveBeenCalled();
+    expect(insert).not.toHaveBeenCalled();
+    expect(insertStatEvent).not.toHaveBeenCalled();
+  });
+
+  it("report increments count and stores reason", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:1",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 1,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:1") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table === "commentReports") {
+        return {
+          withIndex: (index: string) => {
+            if (index === "by_comment_user") {
+              return { unique: vi.fn().mockResolvedValue(null) };
+            }
+            if (index === "by_user") {
+              return { collect: vi.fn().mockResolvedValue([]) };
+            }
+            throw new Error(`Unexpected index ${index}`);
+          },
+        };
+      }
+      throw new Error(`Unexpected table ${table}`);
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    const result = await reportHandler(ctx, {
+      commentId: "comments:1",
+      reason: "  spam  ",
+    } as never);
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false });
+    expect(insert).toHaveBeenCalledWith("commentReports", {
+      commentId: "comments:1",
+      skillId: "skills:1",
+      userId: "users:1",
+      reason: "spam",
+      createdAt: 1_700_000_000_000,
+    });
+    expect(patch).toHaveBeenCalledWith("comments:1", {
+      reportCount: 2,
+      lastReportedAt: 1_700_000_000_000,
+    });
+    expect(insertStatEvent).not.toHaveBeenCalled();
+  });
+
+  it("report returns alreadyReported for duplicate reporter/comment pair", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:dup",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:dup") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table !== "commentReports") throw new Error(`Unexpected table ${table}`);
+      return {
+        withIndex: (index: string) => {
+          if (index === "by_comment_user") {
+            return { unique: vi.fn().mockResolvedValue({ _id: "commentReports:existing" }) };
+          }
+          throw new Error(`Unexpected index ${index}`);
+        },
+      };
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    const result = await reportHandler(ctx, { commentId: "comments:dup", reason: "spam" } as never);
+
+    expect(result).toEqual({ ok: true, reported: false, alreadyReported: true });
+    expect(insert).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("report rejects empty reason", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:empty",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:empty") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn();
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    await expect(
+      reportHandler(ctx, { commentId: "comments:empty", reason: "   " } as never),
+    ).rejects.toThrow("Report reason required.");
+
+    expect(query).not.toHaveBeenCalled();
+    expect(insert).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("report rejects comment when parent skill is hidden/removed", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:hidden-parent",
+      skillId: "skills:hidden",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:hidden-parent") return comment;
+      if (id === "skills:hidden") {
+        return { _id: "skills:hidden", softDeletedAt: 123, moderationStatus: "removed" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn();
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    await expect(
+      reportHandler(ctx, { commentId: "comments:hidden-parent", reason: "abuse" } as never),
+    ).rejects.toThrow("Comment not found");
+
+    expect(query).not.toHaveBeenCalled();
+    expect(insert).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("report truncates long reason to 500 chars", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_050);
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:long",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:long") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table !== "commentReports") throw new Error(`Unexpected table ${table}`);
+      return {
+        withIndex: (index: string) => {
+          if (index === "by_comment_user") return { unique: vi.fn().mockResolvedValue(null) };
+          if (index === "by_user") return { collect: vi.fn().mockResolvedValue([]) };
+          throw new Error(`Unexpected index ${index}`);
+        },
+      };
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    await reportHandler(ctx, { commentId: "comments:long", reason: "x".repeat(700) } as never);
+
+    const reportInsert = vi.mocked(insert).mock.calls.find((call) => call[0] === "commentReports");
+    expect(reportInsert?.[1]).toMatchObject({
+      commentId: "comments:long",
+      reason: "x".repeat(500),
+    });
+  });
+
+  it("report active-count filter ignores stale/non-active report targets", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:target2",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const reports = [
+      {
+        _id: "commentReports:1",
+        commentId: "comments:deleted",
+        userId: "users:1",
+        skillId: "skills:1",
+      },
+      {
+        _id: "commentReports:2",
+        commentId: "comments:removed-skill",
+        userId: "users:1",
+        skillId: "skills:removed",
+      },
+      {
+        _id: "commentReports:3",
+        commentId: "comments:deleted-owner",
+        userId: "users:1",
+        skillId: "skills:active",
+      },
+    ];
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:target2") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      if (id === "comments:deleted") {
+        return {
+          _id: "comments:deleted",
+          softDeletedAt: 123,
+          skillId: "skills:1",
+          userId: "users:2",
+        };
+      }
+      if (id === "comments:removed-skill") {
+        return {
+          _id: "comments:removed-skill",
+          softDeletedAt: undefined,
+          skillId: "skills:removed",
+          userId: "users:2",
+        };
+      }
+      if (id === "skills:removed") {
+        return { _id: "skills:removed", softDeletedAt: undefined, moderationStatus: "removed" };
+      }
+      if (id === "comments:deleted-owner") {
+        return {
+          _id: "comments:deleted-owner",
+          softDeletedAt: undefined,
+          skillId: "skills:active",
+          userId: "users:deleted-owner",
+        };
+      }
+      if (id === "skills:active") {
+        return { _id: "skills:active", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      if (id === "users:deleted-owner") {
+        return { _id: "users:deleted-owner", deletedAt: 1, deactivatedAt: undefined };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table !== "commentReports") throw new Error(`Unexpected table ${table}`);
+      return {
+        withIndex: (index: string) => {
+          if (index === "by_comment_user") return { unique: vi.fn().mockResolvedValue(null) };
+          if (index === "by_user") return { collect: vi.fn().mockResolvedValue(reports) };
+          throw new Error(`Unexpected index ${index}`);
+        },
+      };
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    const result = await reportHandler(ctx, {
+      commentId: "comments:target2",
+      reason: "still allowed",
+    } as never);
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false });
+    expect(insert).toHaveBeenCalledWith(
+      "commentReports",
+      expect.objectContaining({ commentId: "comments:target2", userId: "users:1" }),
+    );
+  });
+
+  it("report rejects when active report limit is reached", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:target",
+      skillId: "skills:1",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 0,
+    };
+    const reportedComment = {
+      _id: "comments:reported",
+      skillId: "skills:active",
+      userId: "users:owner",
+      softDeletedAt: undefined,
+    };
+    const reports = Array.from({ length: 20 }, (_, i) => ({
+      _id: `commentReports:${i + 1}`,
+      commentId: `comments:reported-${i + 1}`,
+      userId: "users:1",
+      skillId: "skills:active",
+      createdAt: i + 1,
+    }));
+
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:target") return comment;
+      if (id === "skills:1") {
+        return { _id: "skills:1", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      if (id.startsWith("comments:reported-")) return reportedComment;
+      if (id === "skills:active") {
+        return { _id: "skills:active", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      if (id === "users:owner") {
+        return { _id: "users:owner", deletedAt: undefined, deactivatedAt: undefined };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table === "commentReports") {
+        return {
+          withIndex: (index: string) => {
+            if (index === "by_comment_user") {
+              return { unique: vi.fn().mockResolvedValue(null) };
+            }
+            if (index === "by_user") {
+              return { collect: vi.fn().mockResolvedValue(reports) };
+            }
+            throw new Error(`Unexpected index ${index}`);
+          },
+        };
+      }
+      throw new Error(`Unexpected table ${table}`);
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    await expect(
+      reportHandler(ctx, { commentId: "comments:target", reason: "abuse" } as never),
+    ).rejects.toThrow("Report limit reached. Please wait for moderation before reporting more.");
+
+    expect(insert).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("report auto-hides comment after fourth unique report", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_100);
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:3",
+      user: { _id: "users:3", role: "user" },
+    } as never);
+
+    const comment = {
+      _id: "comments:4",
+      skillId: "skills:9",
+      userId: "users:2",
+      softDeletedAt: undefined,
+      reportCount: 3,
+    };
+    const get = vi.fn(async (id: string) => {
+      if (id === "comments:4") return comment;
+      if (id === "skills:9") {
+        return { _id: "skills:9", softDeletedAt: undefined, moderationStatus: "active" };
+      }
+      return null;
+    });
+    const insert = vi.fn();
+    const patch = vi.fn();
+    const query = vi.fn((table: string) => {
+      if (table === "commentReports") {
+        return {
+          withIndex: (index: string) => {
+            if (index === "by_comment_user") {
+              return { unique: vi.fn().mockResolvedValue(null) };
+            }
+            if (index === "by_user") {
+              return { collect: vi.fn().mockResolvedValue([]) };
+            }
+            throw new Error(`Unexpected index ${index}`);
+          },
+        };
+      }
+      throw new Error(`Unexpected table ${table}`);
+    });
+    const ctx = { db: { get, insert, patch, query } } as never;
+
+    const result = await reportHandler(ctx, {
+      commentId: "comments:4",
+      reason: "  hate  ",
+    } as never);
+
+    expect(result).toEqual({ ok: true, reported: true, alreadyReported: false });
+    expect(patch).toHaveBeenCalledWith("comments:4", {
+      reportCount: 4,
+      lastReportedAt: 1_700_000_000_100,
+      softDeletedAt: 1_700_000_000_100,
+    });
+    expect(insertStatEvent).toHaveBeenCalledWith(ctx, {
+      skillId: "skills:9",
+      kind: "uncomment",
+    });
+    expect(insert).toHaveBeenCalledWith("auditLogs", {
+      actorUserId: "users:3",
+      action: "comment.auto_hide",
+      targetType: "comment",
+      targetId: "comments:4",
+      metadata: { skillId: "skills:9", reportCount: 4 },
+      createdAt: 1_700_000_000_100,
+    });
+  });
+});
@@ -1,37 +1,49 @@
-import { v } from 'convex/values'
-import type { Doc } from './_generated/dataModel'
-import { mutation, query } from './_generated/server'
-import { addHandler, removeHandler } from './comments.handlers'
-import { type PublicUser, toPublicUser } from './lib/public'
+import { v } from "convex/values";
+import type { Doc } from "./_generated/dataModel";
+import { addHandler, removeHandler, reportHandler } from "./comments.handlers";
+import { mutation, query } from "./functions";
+import { type PublicUser, toPublicUser } from "./lib/public";

 export const listBySkill = query({
-  args: { skillId: v.id('skills'), limit: v.optional(v.number()) },
-  handler: async (ctx, args) => {
-    const limit = args.limit ?? 50
-    const comments = await ctx.db
-      .query('comments')
-      .withIndex('by_skill', (q) => q.eq('skillId', args.skillId))
-      .order('desc')
-      .take(limit)
+  args: { skillId: v.id("skills"), limit: v.optional(v.number()) },
+  handler: listBySkillHandler,
+});

-    const visible = comments.filter((comment) => !comment.softDeletedAt)
-    return Promise.all(
-      visible.map(
-        async (comment): Promise<{ comment: Doc<'comments'>; user: PublicUser | null }> => ({
-          comment,
-          user: toPublicUser(await ctx.db.get(comment.userId)),
-        }),
-      ),
-    )
-  },
-})
+export async function listBySkillHandler(
+  ctx: import("./_generated/server").QueryCtx,
+  args: { skillId: import("./_generated/dataModel").Id<"skills">; limit?: number },
+) {
+  const limit = args.limit ?? 50;
+  const comments = await ctx.db
+    .query("comments")
+    .withIndex("by_skill", (q) => q.eq("skillId", args.skillId))
+    .order("desc")
+    .take(limit);
+
+  const rows = await Promise.all(
+    comments.map(
+      async (comment): Promise<{ comment: Doc<"comments">; user: PublicUser } | null> => {
+        if (comment.softDeletedAt) return null;
+        const user = toPublicUser(await ctx.db.get(comment.userId));
+        if (!user) return null;
+        return { comment, user };
+      },
+    ),
+  );
+  return rows.filter((row): row is { comment: Doc<"comments">; user: PublicUser } => row !== null);
+}

 export const add = mutation({
-  args: { skillId: v.id('skills'), body: v.string() },
+  args: { skillId: v.id("skills"), body: v.string() },
  handler: addHandler,
-})
+});

 export const remove = mutation({
-  args: { commentId: v.id('comments') },
+  args: { commentId: v.id("comments") },
  handler: removeHandler,
-})
+});
+
+export const report = mutation({
+  args: { commentId: v.id("comments"), reason: v.string() },
+  handler: reportHandler,
+});
--- a/Show More
+++ b/Show More