fix: align og image to new comp

fix: reduce og logo scale
fix: remove og logo panel
2026-08-14 08:52:21 +00:00 · 2026-04-20 21:45:57 -05:00 · 2026-04-20 21:26:26 -05:00 · 2026-04-20 21:13:02 -05:00 · 2026-04-20 20:53:11 -05:00 · 2026-04-20 17:05:26 -05:00
353 changed files with 33339 additions and 8639 deletions
@@ -27,15 +27,22 @@ jobs:

      - name: Test
        run: bun run test
+        env:
+          VITE_CONVEX_URL: https://example.invalid

      - name: Coverage
        run: bun run coverage
+        env:
+          VITE_CONVEX_URL: https://example.invalid
+
+      - name: ClawHub CLI Verify
+        run: bun run --cwd packages/clawhub verify

      - name: Typecheck
        run: |
          bunx tsc --noEmit
          bunx tsc -p packages/schema/tsconfig.json --noEmit
-          bunx tsc -p packages/clawdhub/tsconfig.json --noEmit
+          bunx tsc -p packages/clawhub/tsconfig.json --noEmit

      - name: Build
        run: bun run build
@@ -0,0 +1,314 @@
+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
+
+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: 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@e3914758a49697077f7bcd190d36582a61667aad
+        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: 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: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: refs/tags/${{ inputs.tag }}
+          fetch-depth: 0
+
+      - 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)"
+          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: 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}"
@@ -1,46 +1,100 @@
 name: Deploy

 on:
-  push:
-    branches: [main]
  workflow_dispatch:
+    inputs:
+      target:
+        description: "What to deploy"
+        required: true
+        default: full
+        type: choice
+        options:
+          - full
+          - backend
+          - frontend

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

 jobs:
-  preflight-secrets:
+  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 secrets
+      - name: Check deploy configuration
        run: |
+          set -euo pipefail
          missing=()

-          if [[ -z "$CONVEX_DEPLOY_KEY" ]]; then
+          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 GitHub Actions secrets: ${missing[*]}"
+            echo "::error::Missing required production environment secrets: ${missing[*]}"
            exit 1
          fi

+          echo "Deploy target: ${{ needs.validate-deploy-request.outputs.target }}"
+
          if [[ -z "$PLAYWRIGHT_AUTH_STORAGE_STATE_JSON" ]]; then
            echo "PLAYWRIGHT_AUTH_STORAGE_STATE_JSON not set; authenticated smoke will be skipped."
          fi

-  deploy-convex:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    needs: preflight-secrets
-    env:
-      CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}
-    steps:
      - uses: actions/checkout@v6

      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
@@ -51,35 +105,38 @@ jobs:
        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: bun run convex:deploy

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

-  wait-vercel-production:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    needs:
-      - preflight-secrets
-      - deploy-convex
-    steps:
      - name: Wait for Vercel production deployment
+        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
-            state="$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status" \
+            if ! state="$(gh api "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/status" \
              --jq '.statuses[] | select(.context == env.VERCEL_STATUS_CONTEXT) | .state' \
-              2>/dev/null | head -n1)"
+              2>/dev/null | head -n1)"; then
+              echo "GitHub status check failed for $GITHUB_SHA; retrying..."
+              sleep 10
+              continue
+            fi

            case "$state" in
              success)
@@ -104,35 +161,16 @@ jobs:
          echo "::error::Timed out waiting for Vercel production deployment for $GITHUB_SHA"
          exit 1

-  smoke-production:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    needs:
-      - preflight-secrets
-      - deploy-convex
-      - wait-vercel-production
-    env:
-      PLAYWRIGHT_BASE_URL: https://clawhub.ai
-    steps:
-      - uses: actions/checkout@v6
-
-      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
-        with:
-          bun-version: 1.3.10
-
-      - name: Install
-        run: bun install --frozen-lockfile
-
      - name: Install Playwright browser
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true'
        run: bunx playwright install --with-deps chromium

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

      - name: Smoke test production
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true'
        run: bunx playwright test e2e/menu-smoke.pw.test.ts e2e/upload-auth-smoke.pw.test.ts
@@ -0,0 +1,341 @@
+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
+      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 }}
+
+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@e3914758a49697077f7bcd190d36582a61667aad
+        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_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()
+          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 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@v4
+        with:
+          name: clawhub-package-publish-json
+          path: ${{ runner.temp }}/package-publish.json
+          if-no-files-found: error
@@ -1,6 +1,8 @@
 name: "Security Gate: Secret Scanning"

 on:
+  push:
+    branches: ["**"]
  pull_request:
    branches: [main, master]

@@ -16,6 +18,33 @@ jobs:
        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.
@@ -23,8 +52,8 @@ jobs:
        uses: trufflesecurity/trufflehog@v3.93.8
        with:
          path: ./
-          base: ${{ github.event.pull_request.base.sha }} # scope it to the committed files
-          head: ${{ github.event.pull_request.head.sha }}
+          base: ${{ steps.scan_range.outputs.base }}
+          head: ${{ steps.scan_range.outputs.head }}
          extra_args: --only-verified --debug

      - name: Notify on Failure
@@ -24,3 +24,7 @@ coverage
 playwright-report
 test-results
 .playwright
+convex/_generated/
+skills-lock.json
+*/skills/*
+skills/*
@@ -0,0 +1 @@
+22
@@ -38,10 +38,22 @@
 - Commit messages: Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`…).
 - Keep changes scoped; avoid repo-wide search/replace.
 - PRs: include summary + test commands run. Add screenshots for UI changes.
- Before merging any PR, verify TypeScript cleanly with `bunx tsc -p packages/schema/tsconfig.json --noEmit` and `bunx tsc -p packages/clawdhub/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`.
+- 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.

+## 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>`.
@@ -75,3 +87,31 @@
 - **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,5 +1,64 @@
 # Changelog

+## Unreleased
+
+### Changed
+
+- 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
+
+- Stats maintenance: keep skill stat migration fields synchronized by treating top-level stat fields as canonical during backfill/reconcile fallback reads (#1704) (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
@@ -30,7 +30,26 @@
 - 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 -->
@@ -109,7 +109,7 @@ These features degrade gracefully without their keys:

 ## CLI Development

-The CLI source lives in [`packages/clawdhub/`](packages/clawdhub/). Both `clawhub` and `clawdhub` are registered as bin aliases.
+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:

@@ -117,6 +117,17 @@ To test the CLI against your local instance:
 CLAWHUB_REGISTRY=http://127.0.0.1:3210 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 [`docs/manual-testing.md`](docs/manual-testing.md).

 ## Skill & Soul Publishing
@@ -137,6 +148,7 @@ clawhub publish <path-to-skill-directory>
 bun run lint       # oxlint
 bun run test       # Vitest (80% coverage threshold)
 bun run build      # Vite + Nitro
+bun run --cwd packages/clawhub verify
 ```

 These are the same checks that run in CI (`.github/workflows/ci.yml`).
@@ -0,0 +1,356 @@
+# 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
@@ -10,7 +10,7 @@
  <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).
+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.

@@ -61,8 +61,8 @@ Common CLI flows:
 - Browse unified catalog (skills + plugins): `clawhub package explore`, `clawhub package inspect <name>`
 - Manage local installs: `clawhub install <slug>`, `clawhub uninstall <slug>`, `clawhub list`, `clawhub update --all`
 - Inspect without installing: `clawhub inspect <slug>`
- Publish/sync: `clawhub publish <path>`, `clawhub sync`
- Publish plugins: `clawhub package publish <path> [--owner <handle>] --source-repo <owner/repo> --source-commit <sha>`
+- Publish/sync skills: `clawhub skill publish <path>`, `clawhub sync`
+- Publish plugins: `clawhub package publish <source>`
 - 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).
@@ -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)
@@ -48,6 +48,7 @@ import type * as lib_contentTypes from "../lib/contentTypes.js";
 import type * as lib_embeddingVisibility from "../lib/embeddingVisibility.js";
 import type * as lib_embeddings from "../lib/embeddings.js";
 import type * as lib_githubAccount from "../lib/githubAccount.js";
+import type * as lib_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";
@@ -76,6 +77,7 @@ 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_skillPublish from "../lib/skillPublish.js";
 import type * as lib_skillQuality from "../lib/skillQuality.js";
 import type * as lib_skillSafety from "../lib/skillSafety.js";
@@ -92,11 +94,13 @@ import type * as lib_userSearch from "../lib/userSearch.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 publishers from "../publishers.js";
 import type * as rateLimits from "../rateLimits.js";
 import type * as search from "../search.js";
 import type * as seed from "../seed.js";
+import type * as seedDemo from "../seedDemo.js";
 import type * as seedSouls from "../seedSouls.js";
 import type * as skillStatEvents from "../skillStatEvents.js";
 import type * as skillTransfers from "../skillTransfers.js";
@@ -161,6 +165,7 @@ declare const fullApi: ApiFromModules<{
  "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;
@@ -189,6 +194,7 @@ declare const fullApi: ApiFromModules<{
  "lib/searchText": typeof lib_searchText;
  "lib/securityPrompt": typeof lib_securityPrompt;
  "lib/skillBackfill": typeof lib_skillBackfill;
+  "lib/skillCapabilityTags": typeof lib_skillCapabilityTags;
  "lib/skillPublish": typeof lib_skillPublish;
  "lib/skillQuality": typeof lib_skillQuality;
  "lib/skillSafety": typeof lib_skillSafety;
@@ -205,11 +211,13 @@ declare const fullApi: ApiFromModules<{
  "lib/webhooks": typeof lib_webhooks;
  llmEval: typeof llmEval;
  maintenance: typeof maintenance;
+  packagePublishTokens: typeof packagePublishTokens;
  packages: typeof packages;
  publishers: typeof publishers;
  rateLimits: typeof rateLimits;
  search: typeof search;
  seed: typeof seed;
+  seedDemo: typeof seedDemo;
  seedSouls: typeof seedSouls;
  skillStatEvents: typeof skillStatEvents;
  skillTransfers: typeof skillTransfers;
@@ -10,7 +10,12 @@ function makeCtx({
  user,
  banRecords,
 }: {
-  user: { deletedAt?: number; deactivatedAt?: number; purgedAt?: number } | null;
+  user: {
+    deletedAt?: number;
+    deactivatedAt?: number;
+    purgedAt?: number;
+    banReason?: string;
+  } | null;
  banRecords?: Array<Record<string, unknown>>;
 }) {
  const query = {
@@ -112,7 +117,7 @@ describe("handleDeletedUserSignIn", () => {

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

@@ -122,4 +127,15 @@ describe("handleDeletedUserSignIn", () => {

    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`);
+  });
 });
@@ -7,16 +7,29 @@ import type { DataModel, Id } from "./_generated/dataModel";
 import { shouldScheduleGitHubProfileSync } from "./lib/githubProfileSync";

 export const BANNED_REAUTH_MESSAGE =
-  "Your account has been banned for uploading malicious skills. If you believe this is a mistake, please contact security@openclaw.ai and we will work with you to restore access.";
+  "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.";

 const REAUTH_BLOCKING_BAN_ACTIONS = new Set(["user.ban", "user.autoban.malware"]);

+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 },
-  userOverride?: { deletedAt?: number; deactivatedAt?: number; purgedAt?: number } | null,
+  userOverride?: {
+    deletedAt?: number;
+    deactivatedAt?: number;
+    purgedAt?: number;
+    banReason?: string;
+  } | null,
 ) {
  const user = userOverride !== undefined ? userOverride : await ctx.db.get(args.userId);
  if (!user?.deletedAt && !user?.deactivatedAt) return;
@@ -42,7 +55,7 @@ export async function handleDeletedUserSignIn(
  );

  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
@@ -237,6 +237,74 @@ xuezh snapshot --profile default
 xuezh review next --limit 10
 xuezh audio process-voice --file ./utterance.wav
 \`\`\`
+`,
+  },
+  {
+    slug: "hanzi-helper",
+    displayName: "汉字助手",
+    summary: "汉字学习与分析工具，支持笔画查询、部首检索和组词生成。",
+    version: "0.1.0",
+    metadata: {
+      clawdbot: {
+        nix: {
+          plugin: "github:example/hanzi-helper",
+          systems: ["aarch64-darwin", "x86_64-linux"],
+        },
+        config: {
+          requiredEnv: ["HANZI_DB_PATH"],
+          stateDirs: [".config/hanzi"],
+          example:
+            'config = { env = { HANZI_DB_PATH = ".config/hanzi/db"; }; stateDirs = [ ".config/hanzi" ]; };',
+        },
+        cliHelp: `汉字助手 - Chinese character learning and analysis
+
+Usage:
+  hanzi-helper [command]
+
+Available Commands:
+  lookup      查询汉字信息（笔画、部首、释义）
+  radical     按部首检索汉字
+  stroke      按笔画数筛选汉字
+  words       生成汉字组词
+  practice    练习汉字书写
+  quiz        汉字听写测试
+
+Flags:
+  -h, --help   help for hanzi-helper
+  --json       Output JSON
+`,
+      },
+    },
+    rawSkillMd: `---
+name: hanzi-helper
+description: 汉字学习与分析工具，提供笔画查询、部首检索、组词生成和汉字听写练习功能。
+---
+
+# 汉字助手
+
+## 功能介绍
+
+汉字助手是一个强大的中文汉字学习工具，帮助用户深入了解每个汉字的结构和含义。
+
+## CLI
+
+\`\`\`bash
+hanzi-helper lookup --char 学
+hanzi-helper radical --name 木
+hanzi-helper stroke --count 8
+hanzi-helper words --char 大 --limit 20
+\`\`\`
+
+## 使用场景
+
+- **汉字查询**：输入任意汉字，查看笔画数、部首、繁体形式和基本释义
+- **部首检索**：按部首浏览相关汉字，了解汉字的分类规律
+- **组词生成**：输入一个汉字，自动生成常用词语和成语
+- **听写练习**：随机生成汉字听写测试，巩固学习效果
+
+## 学习建议
+
+建议每天学习五个新汉字，结合组词和例句加深记忆。坚持使用听写练习功能可以有效提高汉字识别能力。
 `,
  },
 ];
@@ -401,6 +469,11 @@ export const seedSkillMutation = internalMutation({
      createdAt: now,
      updatedAt: now,
    });
+    await ctx.db.patch(userId, {
+      publishedSkills: 1,
+      totalStars: 0,
+      totalDownloads: 0,
+    });

    const versionId = await ctx.db.insert("skillVersions", {
      skillId,
@@ -448,6 +448,22 @@ const EXTRA_SEED_SKILLS: SeedSkillSpec[] = [
    ["SSH_KEY_DIR"],
    ["generate", "rotate", "deploy", "list", "revoke"],
  ),
+
+  // CJK Language Support (2)
+  makeSkill(
+    "nihongo-check",
+    "日本語チェッカー",
+    "日本語文章の文法チェックと翻訳支援ツール。Japanese grammar checker and translation assistant.",
+    ["NIHONGO_API_KEY"],
+    ["check", "translate", "kanji", "grammar", "vocabulary"],
+  ),
+  makeSkill(
+    "hangukgeo-helper",
+    "한국어 도우미",
+    "한국어 학습 보조 도구입니다. Korean language learning assistant with vocabulary and grammar support.",
+    ["HANGUL_API_KEY"],
+    ["learn", "quiz", "vocabulary", "grammar", "pronunciation"],
+  ),
 ];

 function injectMetadata(rawSkillMd: string, metadata: Record<string, unknown>) {
@@ -62,10 +62,7 @@ describe("package digest sync", () => {
      },
    };

-    await syncPackageSearchDigestForPackageId(
-      ctx as never,
-      "packages:demo" as never,
-    );
+    await syncPackageSearchDigestForPackageId(ctx as never, "packages:demo" as never);

    expect(ctx.db.insert).toHaveBeenCalledWith(
      "packageSearchDigest",
@@ -128,10 +125,7 @@ describe("package digest sync", () => {
      },
    };

-    await syncPackageSearchDigestForPackageId(
-      ctx as never,
-      "packages:demo" as never,
-    );
+    await syncPackageSearchDigestForPackageId(ctx as never, "packages:demo" as never);

    expect(ctx.db.insert).toHaveBeenCalledWith(
      "packageSearchDigest",
@@ -443,13 +437,11 @@ describe("package digest sync", () => {
      updatedAt: 2,
      verification: undefined,
    };
-    const paginate = vi
-      .fn()
-      .mockResolvedValueOnce({
-        page: [pkg],
-        isDone: true,
-        continueCursor: "",
-      });
+    const paginate = vi.fn().mockResolvedValueOnce({
+      page: [pkg],
+      isDone: true,
+      continueCursor: "",
+    });
    const ctx = {
      db: {
        get: vi.fn(async (id: string) => {
@@ -488,10 +480,7 @@ describe("package digest sync", () => {
      },
    };

-    await syncPackageSearchDigestsForOwnerUserId(
-      ctx as never,
-      "users:owner" as never,
-    );
+    await syncPackageSearchDigestsForOwnerUserId(ctx as never, "users:owner" as never);

    expect(paginate).toHaveBeenCalledWith({ cursor: null, numItems: 100 });
    expect(ctx.db.insert).toHaveBeenCalledWith(
@@ -128,7 +128,8 @@ async function syncPackageSearchDigest(
  });
  await upsertPackageSearchDigest(ctx, {
    ...fields,
-    latestVersion: latestRelease && !latestRelease.softDeletedAt ? latestRelease.version : undefined,
+    latestVersion:
+      latestRelease && !latestRelease.softDeletedAt ? latestRelease.version : undefined,
    ownerHandle: owner?.handle ?? "",
    ownerKind: owner?.kind,
  });
@@ -344,13 +345,15 @@ triggers.register("packages", async (ctx, change) => {

 triggers.register("packageReleases", async (ctx, change) => {
  if (change.operation === "insert") return;
-  if (change.operation === "update" && change.oldDoc.softDeletedAt === change.newDoc.softDeletedAt) {
+  if (
+    change.operation === "update" &&
+    change.oldDoc.softDeletedAt === change.newDoc.softDeletedAt
+  ) {
    return;
  }
  const packageId =
    change.operation === "delete" ? change.oldDoc.packageId : change.newDoc.packageId;
-  const affectedReleaseId =
-    change.operation === "delete" ? change.oldDoc._id : change.newDoc._id;
+  const affectedReleaseId = change.operation === "delete" ? change.oldDoc._id : change.newDoc._id;
  if (change.operation === "delete" || change.newDoc.softDeletedAt) {
    await repointPackageLatestRelease(ctx, packageId, affectedReleaseId);
    return;
@@ -20,10 +20,13 @@ import {
  listPluginsV1Http,
  listSkillsV1Http,
  listSoulsV1Http,
+  mintPublishTokenV1Http,
+  packagesDeleteRouterV1Http,
  packagesGetRouterV1Http,
+  packagesPostRouterV1Http,
  pluginsGetRouterV1Http,
-  publishSkillV1Http,
  publishPackageV1Http,
+  publishSkillV1Http,
  publishSoulV1Http,
  resolveSkillVersionV1Http,
  searchSkillsV1Http,
@@ -124,6 +127,24 @@ http.route({
  handler: publishPackageV1Http,
 });

+http.route({
+  path: ApiRoutes.publishTokenMint,
+  method: "POST",
+  handler: mintPublishTokenV1Http,
+});
+
+http.route({
+  pathPrefix: `${ApiRoutes.packages}/`,
+  method: "POST",
+  handler: packagesPostRouterV1Http,
+});
+
+http.route({
+  pathPrefix: `${ApiRoutes.packages}/`,
+  method: "DELETE",
+  handler: packagesDeleteRouterV1Http,
+});
+
 http.route({
  pathPrefix: `${ApiRoutes.skills}/`,
  method: "POST",
@@ -11,6 +11,12 @@ vi.mock("@convex-dev/auth/server", () => ({
 vi.mock("./lib/apiTokenAuth", () => ({
  requireApiTokenUser: vi.fn(),
  getOptionalApiTokenUserId: vi.fn(),
+  requirePackagePublishAuth: vi.fn(),
+}));
+
+vi.mock("./lib/githubActionsOidc", () => ({
+  fetchGitHubRepositoryIdentity: vi.fn(),
+  verifyGitHubActionsTrustedPublishJwt: vi.fn(),
 }));

 vi.mock("./skills", () => ({
@@ -18,7 +24,10 @@ vi.mock("./skills", () => ({
 }));

 const { getAuthUserId } = await import("@convex-dev/auth/server");
-const { getOptionalApiTokenUserId, requireApiTokenUser } = await import("./lib/apiTokenAuth");
+const { getOptionalApiTokenUserId, requireApiTokenUser, requirePackagePublishAuth } =
+  await import("./lib/apiTokenAuth");
+const { fetchGitHubRepositoryIdentity, verifyGitHubActionsTrustedPublishJwt } =
+  await import("./lib/githubActionsOidc");
 const { publishVersionForUser } = await import("./skills");
 const { __handlers } = await import("./httpApiV1");

@@ -83,6 +92,9 @@ beforeEach(() => {
  vi.mocked(getOptionalApiTokenUserId).mockReset();
  vi.mocked(getOptionalApiTokenUserId).mockResolvedValue(null);
  vi.mocked(requireApiTokenUser).mockReset();
+  vi.mocked(requirePackagePublishAuth).mockReset();
+  vi.mocked(fetchGitHubRepositoryIdentity).mockReset();
+  vi.mocked(verifyGitHubActionsTrustedPublishJwt).mockReset();
  vi.mocked(publishVersionForUser).mockReset();
 });

@@ -1185,6 +1197,154 @@ describe("httpApiV1 handlers", () => {
    expect(json.version.security.virustotalUrl).toContain("virustotal.com/gui/file/");
  });

+  it("surfaces static-scan suspicious status in version security snapshot", async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("slug" in args) {
+        return {
+          skill: { _id: "skills:1", slug: "demo", displayName: "Demo" },
+          latestVersion: null,
+          owner: { handle: "owner", displayName: "Owner", image: null },
+        };
+      }
+      if ("skillId" in args && "version" in args) {
+        return {
+          version: "1.0.0",
+          createdAt: 1,
+          changelog: "c",
+          changelogSource: "auto",
+          sha256hash: "a".repeat(64),
+          staticScan: {
+            status: "suspicious",
+            reasonCodes: ["suspicious.dangerous_exec"],
+            summary: "Detected: suspicious.dangerous_exec",
+            engineVersion: "v2.4.0",
+            checkedAt: 555,
+          },
+          vtAnalysis: {
+            status: "clean",
+            verdict: "benign",
+            checkedAt: 111,
+          },
+          llmAnalysis: {
+            status: "completed",
+            verdict: "benign",
+            checkedAt: 222,
+          },
+          files: [],
+        };
+      }
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/skills/demo/versions/1.0.0"),
+    );
+    expect(response.status).toBe(200);
+    const json = await response.json();
+    expect(json.version.security.status).toBe("suspicious");
+    expect(json.version.security.hasWarnings).toBe(true);
+    expect(json.version.security.hasScanResult).toBe(true);
+    expect(json.version.security.scanners.static.normalizedStatus).toBe("suspicious");
+    expect(json.version.security.scanners.vt.normalizedStatus).toBe("clean");
+    expect(json.version.security.scanners.llm.normalizedStatus).toBe("clean");
+  });
+
+  it("lets static-scan malicious status dominate benign vt and llm results", async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("slug" in args) {
+        return {
+          skill: { _id: "skills:1", slug: "demo", displayName: "Demo" },
+          latestVersion: null,
+          owner: { handle: "owner", displayName: "Owner", image: null },
+        };
+      }
+      if ("skillId" in args && "version" in args) {
+        return {
+          version: "1.0.0",
+          createdAt: 1,
+          changelog: "c",
+          changelogSource: "auto",
+          sha256hash: "a".repeat(64),
+          staticScan: {
+            status: "malicious",
+            reasonCodes: ["malicious.credential_harvest"],
+            summary: "Detected: malicious.credential_harvest",
+            engineVersion: "v2.4.0",
+            checkedAt: 555,
+          },
+          vtAnalysis: {
+            status: "clean",
+            verdict: "benign",
+            checkedAt: 111,
+          },
+          llmAnalysis: {
+            status: "completed",
+            verdict: "benign",
+            checkedAt: 222,
+          },
+          files: [],
+        };
+      }
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/skills/demo/versions/1.0.0"),
+    );
+    expect(response.status).toBe(200);
+    const json = await response.json();
+    expect(json.version.security.status).toBe("malicious");
+    expect(json.version.security.hasWarnings).toBe(true);
+    expect(json.version.security.hasScanResult).toBe(true);
+    expect(json.version.security.checkedAt).toBe(555);
+    expect(json.version.security.scanners.static.normalizedStatus).toBe("malicious");
+  });
+
+  it("treats a static scan by itself as a definitive scan result", async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("slug" in args) {
+        return {
+          skill: { _id: "skills:1", slug: "demo", displayName: "Demo" },
+          latestVersion: null,
+          owner: { handle: "owner", displayName: "Owner", image: null },
+        };
+      }
+      if ("skillId" in args && "version" in args) {
+        return {
+          version: "1.0.0",
+          createdAt: 1,
+          changelog: "c",
+          changelogSource: "auto",
+          staticScan: {
+            status: "clean",
+            reasonCodes: [],
+            summary: "No issues found",
+            engineVersion: "v2.4.0",
+            checkedAt: 555,
+          },
+          files: [],
+        };
+      }
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/skills/demo/versions/1.0.0"),
+    );
+    expect(response.status).toBe(200);
+    const json = await response.json();
+    expect(json.version.security.status).toBe("clean");
+    expect(json.version.security.hasWarnings).toBe(false);
+    expect(json.version.security.hasScanResult).toBe(true);
+    expect(json.version.security.virustotalUrl).toBeNull();
+    expect(json.version.security.scanners.static.normalizedStatus).toBe("clean");
+    expect(json.version.security.scanners.vt).toBeNull();
+    expect(json.version.security.scanners.llm).toBeNull();
+  });
+
  it("keeps hasWarnings true when llm dimensions include non-ok ratings", async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ("slug" in args) {
@@ -1250,6 +1410,7 @@ describe("httpApiV1 handlers", () => {
            changelog: "c",
            changelogSource: "auto",
            sha256hash: "b".repeat(64),
+            capabilityTags: ["crypto", "requires-wallet", "can-make-purchases"],
            vtAnalysis: {
              status: "clean",
              checkedAt: 111,
@@ -1284,6 +1445,11 @@ describe("httpApiV1 handlers", () => {
    const json = await response.json();
    expect(json.security.status).toBe("suspicious");
    expect(json.security.hasScanResult).toBe(true);
+    expect(json.security.capabilityTags).toEqual([
+      "crypto",
+      "requires-wallet",
+      "can-make-purchases",
+    ]);
    expect(json.security.scanners.llm.verdict).toBe("suspicious");
    expect(json.moderation.scope).toBe("skill");
    expect(json.moderation.sourceVersion).toEqual({
@@ -1345,6 +1511,51 @@ describe("httpApiV1 handlers", () => {
    expect(json.security.scanners.llm.normalizedStatus).toBe("error");
  });

+  it("returns capability tags even when no scanner result exists yet", async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("slug" in args) {
+        return {
+          skill: {
+            _id: "skills:1",
+            slug: "demo",
+            displayName: "Demo",
+            summary: "s",
+            tags: { latest: "versions:1" },
+            stats: {},
+            createdAt: 1,
+            updatedAt: 2,
+          },
+          latestVersion: {
+            version: "1.0.0",
+            createdAt: 1,
+            changelog: "c",
+            changelogSource: "auto",
+            capabilityTags: ["posts-externally", "requires-oauth-token"],
+            files: [],
+          },
+          owner: { _id: "users:1", handle: "owner", displayName: "Owner" },
+          moderationInfo: {
+            isPendingScan: true,
+            isMalwareBlocked: false,
+            isSuspicious: false,
+            isHiddenByMod: false,
+            isRemoved: false,
+          },
+        };
+      }
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const response = await __handlers.skillsGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/skills/demo/scan"),
+    );
+    expect(response.status).toBe(200);
+    const json = await response.json();
+    expect(json.security.capabilityTags).toEqual(["posts-externally", "requires-oauth-token"]);
+    expect(json.security.hasScanResult).toBe(false);
+  });
+
  it("keeps hasScanResult true when one scanner returns a definitive verdict", async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ("slug" in args) {
@@ -2405,6 +2616,37 @@ describe("httpApiV1 handlers", () => {
    );
  });

+  it("packages search falls back to anonymous when cookie auth resolves to an invalid user", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:broken" as never);
+    const runQuery = vi.fn(async (query: unknown, args: Record<string, unknown>) => {
+      if (query === internal.users.getByIdInternal) {
+        throw new Error("Table mismatch");
+      }
+      if ("query" in args && args.query === "secret") return [];
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+
+    const response = await __handlers.packagesGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/packages/search?q=secret&channel=community"),
+    );
+
+    expect(response.status).toBe(200);
+    expect(runQuery).toHaveBeenCalledWith(
+      internal.users.getByIdInternal,
+      expect.objectContaining({ userId: "users:broken" }),
+    );
+    expect(runQuery).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        query: "secret",
+        channel: "community",
+        viewerUserId: undefined,
+      }),
+    );
+  });
+
  it("packages detail falls back to public skills", async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ("name" in args) return null;
@@ -2458,6 +2700,51 @@ describe("httpApiV1 handlers", () => {
    });
  });

+  it("packages detail returns stats for plugins", async () => {
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("name" in args) {
+        return {
+          package: {
+            _id: "packages:demo-plugin",
+            name: "demo-plugin",
+            displayName: "Demo Plugin",
+            family: "code-plugin",
+            tags: {},
+            latestReleaseId: "packageReleases:1",
+            channel: "community",
+            isOfficial: false,
+            summary: "Plugin summary",
+            latestVersion: "1.2.3",
+            stats: { downloads: 7, installs: 3, stars: 2, versions: 4 },
+            createdAt: 1,
+            updatedAt: 2,
+          },
+          latestRelease: null,
+          owner: { _id: "users:owner", handle: "owner", displayName: "Owner" },
+        };
+      }
+      return null;
+    });
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+
+    const response = await __handlers.packagesGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/packages/demo-plugin"),
+    );
+
+    if (response.status !== 200) throw new Error(await response.text());
+    await expect(response.json()).resolves.toMatchObject({
+      package: {
+        name: "demo-plugin",
+        latestVersion: "1.2.3",
+        stats: { downloads: 7, installs: 3, stars: 2, versions: 4 },
+      },
+      owner: {
+        handle: "owner",
+      },
+    });
+  });
+
  it("packages file serves SKILL.md for skill README requests", async () => {
    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
      if ("name" in args) return null;
@@ -2994,7 +3281,10 @@ describe("httpApiV1 handlers", () => {
    );

    const zipEntries = unzipSync(new Uint8Array(await response.arrayBuffer()));
-    expect(Object.keys(zipEntries).sort()).toEqual(["package/dist/index.js", "package/package.json"]);
+    expect(Object.keys(zipEntries).sort()).toEqual([
+      "package/dist/index.js",
+      "package/package.json",
+    ]);
    expect(zipEntries["_meta.json"]).toBeUndefined();
  });

@@ -3269,7 +3559,9 @@ describe("httpApiV1 handlers", () => {

    const fileResponse = await __handlers.packagesGetRouterV1Handler(
      makeCtx({ runQuery, runMutation, storage: { get: vi.fn() } }),
-      new Request("https://example.com/api/v1/packages/demo-plugin/file?version=1.0.0&path=README.md"),
+      new Request(
+        "https://example.com/api/v1/packages/demo-plugin/file?version=1.0.0&path=README.md",
+      ),
    );
    const downloadResponse = await __handlers.packagesGetRouterV1Handler(
      makeCtx({ runQuery, runMutation, storage: { get: vi.fn() } }),
@@ -3284,12 +3576,15 @@ describe("httpApiV1 handlers", () => {

  it("package publish uses write rate limiting", async () => {
    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue("users:1" as never);
-    vi.mocked(requireApiTokenUser).mockResolvedValue({
+    vi.mocked(requirePackagePublishAuth).mockResolvedValue({
+      kind: "user",
      userId: "users:1",
      user: { _id: "users:1", handle: "p" },
    } as never);
    const runMutation = vi.fn().mockResolvedValue(okRate());
-    const runAction = vi.fn().mockResolvedValue({ ok: true, packageId: "pkg:1", releaseId: "rel:1" });
+    const runAction = vi
+      .fn()
+      .mockResolvedValue({ ok: true, packageId: "pkg:1", releaseId: "rel:1" });

    const response = await __handlers.publishPackageV1Handler(
      makeCtx({ runAction, runMutation }),
@@ -3335,12 +3630,15 @@ describe("httpApiV1 handlers", () => {

  it("multipart package publish ignores macOS junk files", async () => {
    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue("users:1" as never);
-    vi.mocked(requireApiTokenUser).mockResolvedValue({
+    vi.mocked(requirePackagePublishAuth).mockResolvedValue({
+      kind: "user",
      userId: "users:1",
      user: { _id: "users:1", handle: "p" },
    } as never);
    const runMutation = vi.fn().mockResolvedValue(okRate());
-    const runAction = vi.fn().mockResolvedValue({ ok: true, packageId: "pkg:1", releaseId: "rel:1" });
+    const runAction = vi
+      .fn()
+      .mockResolvedValue({ ok: true, packageId: "pkg:1", releaseId: "rel:1" });
    const form = new FormData();
    form.set(
      "payload",
@@ -3353,10 +3651,7 @@ describe("httpApiV1 handlers", () => {
      }),
    );
    form.append("files", new File(["{}"], ".DS_Store", { type: "application/octet-stream" }));
-    form.append(
-      "files",
-      new File(["{}"], "openclaw.bundle.json", { type: "application/json" }),
-    );
+    form.append("files", new File(["{}"], "openclaw.bundle.json", { type: "application/json" }));

    const response = await __handlers.publishPackageV1Handler(
      makeCtx({
@@ -3388,6 +3683,427 @@ describe("httpApiV1 handlers", () => {
    );
  });

+  it("package publish routes GitHub Actions auth through the trusted publisher action", async () => {
+    vi.mocked(getOptionalApiTokenUserId).mockResolvedValue("users:1" as never);
+    vi.mocked(requirePackagePublishAuth).mockResolvedValue({
+      kind: "github-actions",
+      publishToken: { _id: "packagePublishTokens:1" },
+    } as never);
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const runAction = vi
+      .fn()
+      .mockResolvedValue({ ok: true, packageId: "pkg:1", releaseId: "rel:1" });
+
+    const response = await __handlers.publishPackageV1Handler(
+      makeCtx({ runAction, runMutation }),
+      new Request("https://example.com/api/v1/packages", {
+        method: "POST",
+        headers: {
+          Authorization: "Bearer clh_publish",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          name: "demo-plugin",
+          family: "bundle-plugin",
+          version: "1.0.0",
+          changelog: "init",
+          bundle: { hostTargets: ["desktop"] },
+          files: [
+            {
+              path: "openclaw.bundle.json",
+              size: 2,
+              storageId: "storage:1",
+              sha256: "a".repeat(64),
+            },
+          ],
+        }),
+      }),
+    );
+
+    expect(response.status).toBe(200);
+    expect(runAction).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        publishTokenId: "packagePublishTokens:1",
+      }),
+    );
+  });
+
+  it("returns trusted publisher config for a package", async () => {
+    const runMutation = vi.fn().mockResolvedValue(okRate());
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("name" in args) {
+        return {
+          package: {
+            _id: "packages:1",
+            name: "@openclaw/demo-plugin",
+            displayName: "Demo Plugin",
+            family: "code-plugin",
+            tags: {},
+            channel: "community",
+            isOfficial: false,
+            createdAt: 1,
+            updatedAt: 1,
+          },
+          latestRelease: null,
+          owner: null,
+        };
+      }
+      if ("packageId" in args) {
+        return {
+          _id: "packageTrustedPublishers:1",
+          packageId: "packages:1",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+          environment: "clawhub-release",
+          createdAt: 1,
+          updatedAt: 1,
+        };
+      }
+      return null;
+    });
+
+    const response = await __handlers.packagesGetRouterV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request(
+        "https://example.com/api/v1/packages/%40openclaw%2Fdemo-plugin/trusted-publisher",
+      ),
+    );
+
+    expect(response.status).toBe(200);
+    expect(await response.json()).toEqual({
+      trustedPublisher: {
+        provider: "github-actions",
+        repository: "openclaw/openclaw",
+        repositoryId: "1",
+        repositoryOwner: "openclaw",
+        repositoryOwnerId: "2",
+        workflowFilename: "plugin-clawhub-release.yml",
+        environment: "clawhub-release",
+      },
+    });
+  });
+
+  it("mints a short-lived publish token after verifying GitHub OIDC", async () => {
+    vi.mocked(verifyGitHubActionsTrustedPublishJwt).mockResolvedValue({
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+      workflowFilename: "plugin-clawhub-release.yml",
+      environment: "clawhub-release",
+      runId: "101",
+      runAttempt: "1",
+      sha: "abc123",
+      ref: "refs/heads/main",
+      refType: "branch",
+      actor: "onur",
+      actorId: "42",
+    } as never);
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if ("key" in args) return okRate();
+      return "mutation:ok";
+    });
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("name" in args) {
+        return {
+          _id: "packages:1",
+          name: "@openclaw/demo-plugin",
+          ownerUserId: "users:owner",
+        };
+      }
+      if ("packageId" in args) {
+        return {
+          _id: "packageTrustedPublishers:1",
+          packageId: "packages:1",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+          environment: "clawhub-release",
+        };
+      }
+      return null;
+    });
+
+    const response = await __handlers.mintPublishTokenV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/publish/token/mint", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          packageName: "@openclaw/demo-plugin",
+          version: "1.0.0",
+          githubOidcToken: "gh.jwt",
+        }),
+      }),
+    );
+
+    if (response.status !== 200) throw new Error(await response.text());
+    const body = await response.json();
+    expect(body.token).toEqual(expect.any(String));
+    expect(body.expiresAt).toEqual(expect.any(Number));
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        packageId: "packages:1",
+        version: "1.0.0",
+        repository: "openclaw/openclaw",
+        workflowFilename: "plugin-clawhub-release.yml",
+        environment: "clawhub-release",
+        runId: "101",
+        sha: "abc123",
+      }),
+    );
+  });
+
+  it("mints a short-lived publish token without environment when none is pinned", async () => {
+    vi.mocked(verifyGitHubActionsTrustedPublishJwt).mockResolvedValue({
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+      workflowFilename: "plugin-clawhub-release.yml",
+      environment: "clawhub-release",
+      runId: "101",
+      runAttempt: "1",
+      sha: "abc123",
+      ref: "refs/heads/main",
+      refType: "branch",
+      actor: "onur",
+      actorId: "42",
+    } as never);
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if ("key" in args) return okRate();
+      return "mutation:ok";
+    });
+    const runQuery = vi.fn(async (_query: unknown, args: Record<string, unknown>) => {
+      if ("name" in args) {
+        return {
+          _id: "packages:1",
+          name: "@openclaw/demo-plugin",
+          ownerUserId: "users:owner",
+        };
+      }
+      if ("packageId" in args) {
+        return {
+          _id: "packageTrustedPublishers:1",
+          packageId: "packages:1",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+        };
+      }
+      return null;
+    });
+
+    const response = await __handlers.mintPublishTokenV1Handler(
+      makeCtx({ runQuery, runMutation }),
+      new Request("https://example.com/api/v1/publish/token/mint", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          packageName: "@openclaw/demo-plugin",
+          version: "1.0.0",
+          githubOidcToken: "gh.jwt",
+        }),
+      }),
+    );
+
+    if (response.status !== 200) throw new Error(await response.text());
+    const body = await response.json();
+    expect(body.token).toEqual(expect.any(String));
+    expect(body.expiresAt).toEqual(expect.any(Number));
+    const createCall = runMutation.mock.calls.find(
+      ([, args]) =>
+        typeof args === "object" && args !== null && "packageId" in args && "tokenHash" in args,
+    );
+    expect(createCall?.[1]).toEqual(
+      expect.objectContaining({
+        packageId: "packages:1",
+        version: "1.0.0",
+        repository: "openclaw/openclaw",
+        workflowFilename: "plugin-clawhub-release.yml",
+        runId: "101",
+        sha: "abc123",
+      }),
+    );
+    expect(createCall?.[1]).not.toHaveProperty("environment");
+  });
+
+  it("sets trusted publisher config for a package", async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", handle: "p" },
+    } as never);
+    vi.mocked(fetchGitHubRepositoryIdentity).mockResolvedValue({
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+    } as never);
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if ("key" in args) return okRate();
+      return {
+        _id: "packageTrustedPublishers:1",
+        packageId: "packages:1",
+        provider: "github-actions",
+        repository: "openclaw/openclaw",
+        repositoryId: "1",
+        repositoryOwner: "openclaw",
+        repositoryOwnerId: "2",
+        workflowFilename: "plugin-clawhub-release.yml",
+        environment: "clawhub-release",
+      };
+    });
+
+    const response = await __handlers.packagesPostRouterV1Handler(
+      makeCtx({ runMutation }),
+      new Request(
+        "https://example.com/api/v1/packages/%40openclaw%2Fdemo-plugin/trusted-publisher",
+        {
+          method: "POST",
+          headers: {
+            Authorization: "Bearer clh_test",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            repository: "https://github.com/openclaw/openclaw",
+            workflowFilename: "plugin-clawhub-release.yml",
+            environment: "clawhub-release",
+          }),
+        },
+      ),
+    );
+
+    if (response.status !== 200) throw new Error(await response.text());
+    expect(fetchGitHubRepositoryIdentity).toHaveBeenCalledWith(
+      "https://github.com/openclaw/openclaw",
+    );
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        actorUserId: "users:1",
+        packageName: "@openclaw/demo-plugin",
+        repository: "openclaw/openclaw",
+        workflowFilename: "plugin-clawhub-release.yml",
+        environment: "clawhub-release",
+      }),
+    );
+  });
+
+  it("sets trusted publisher config for a package without environment", async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", handle: "p" },
+    } as never);
+    vi.mocked(fetchGitHubRepositoryIdentity).mockResolvedValue({
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+    } as never);
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if ("key" in args) return okRate();
+      return {
+        _id: "packageTrustedPublishers:1",
+        packageId: "packages:1",
+        provider: "github-actions",
+        repository: "openclaw/openclaw",
+        repositoryId: "1",
+        repositoryOwner: "openclaw",
+        repositoryOwnerId: "2",
+        workflowFilename: "plugin-clawhub-release.yml",
+      };
+    });
+
+    const response = await __handlers.packagesPostRouterV1Handler(
+      makeCtx({ runMutation }),
+      new Request(
+        "https://example.com/api/v1/packages/%40openclaw%2Fdemo-plugin/trusted-publisher",
+        {
+          method: "POST",
+          headers: {
+            Authorization: "Bearer clh_test",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({
+            repository: "https://github.com/openclaw/openclaw",
+            workflowFilename: "plugin-clawhub-release.yml",
+          }),
+        },
+      ),
+    );
+
+    if (response.status !== 200) throw new Error(await response.text());
+    expect(fetchGitHubRepositoryIdentity).toHaveBeenCalledWith(
+      "https://github.com/openclaw/openclaw",
+    );
+    expect(await response.json()).toEqual({
+      trustedPublisher: {
+        provider: "github-actions",
+        repository: "openclaw/openclaw",
+        repositoryId: "1",
+        repositoryOwner: "openclaw",
+        repositoryOwnerId: "2",
+        workflowFilename: "plugin-clawhub-release.yml",
+      },
+    });
+    const setCall = runMutation.mock.calls.find(
+      ([, args]) =>
+        typeof args === "object" && args !== null && "packageName" in args && "actorUserId" in args,
+    );
+    expect(setCall?.[1]).toEqual(
+      expect.objectContaining({
+        actorUserId: "users:1",
+        packageName: "@openclaw/demo-plugin",
+        repository: "openclaw/openclaw",
+        workflowFilename: "plugin-clawhub-release.yml",
+      }),
+    );
+    expect(setCall?.[1]).not.toHaveProperty("environment");
+  });
+
+  it("deletes trusted publisher config for a package", async () => {
+    vi.mocked(requireApiTokenUser).mockResolvedValue({
+      userId: "users:1",
+      user: { _id: "users:1", handle: "p" },
+    } as never);
+    const runMutation = vi.fn(async (_mutation: unknown, args: Record<string, unknown>) => {
+      if ("key" in args) return okRate();
+      return { deleted: true };
+    });
+
+    const response = await __handlers.packagesDeleteRouterV1Handler(
+      makeCtx({ runMutation }),
+      new Request(
+        "https://example.com/api/v1/packages/%40openclaw%2Fdemo-plugin/trusted-publisher",
+        {
+          method: "DELETE",
+          headers: { Authorization: "Bearer clh_test" },
+        },
+      ),
+    );
+
+    expect(response.status).toBe(200);
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        actorUserId: "users:1",
+        packageName: "@openclaw/demo-plugin",
+      }),
+    );
+  });
+
  it("delete/undelete map forbidden/not-found/unknown to 403/404/500", async () => {
    vi.mocked(requireApiTokenUser).mockResolvedValue({
      userId: "users:1",
@@ -4,7 +4,10 @@ import {
  listCodePluginsV1Handler,
  listPackagesV1Handler,
  listPluginsV1Handler,
+  mintPublishTokenV1Handler,
+  packagesDeleteRouterV1Handler,
  packagesGetRouterV1Handler,
+  packagesPostRouterV1Handler,
  pluginsGetRouterV1Handler,
  publishPackageV1Handler,
 } from "./httpApiV1/packagesV1";
@@ -32,8 +35,11 @@ import { whoamiV1Handler } from "./httpApiV1/whoamiV1";
 export const listPackagesV1Http = httpAction(listPackagesV1Handler);
 export const listPluginsV1Http = httpAction(listPluginsV1Handler);
 export const packagesGetRouterV1Http = httpAction(packagesGetRouterV1Handler);
+export const packagesPostRouterV1Http = httpAction(packagesPostRouterV1Handler);
+export const packagesDeleteRouterV1Http = httpAction(packagesDeleteRouterV1Handler);
 export const pluginsGetRouterV1Http = httpAction(pluginsGetRouterV1Handler);
 export const publishPackageV1Http = httpAction(publishPackageV1Handler);
+export const mintPublishTokenV1Http = httpAction(mintPublishTokenV1Handler);
 export const listCodePluginsV1Http = httpAction(listCodePluginsV1Handler);
 export const listBundlePluginsV1Http = httpAction(listBundlePluginsV1Handler);

@@ -63,8 +69,11 @@ export const __handlers = {
  listPackagesV1Handler,
  listPluginsV1Handler,
  packagesGetRouterV1Handler,
+  packagesPostRouterV1Handler,
+  packagesDeleteRouterV1Handler,
  pluginsGetRouterV1Handler,
  publishPackageV1Handler,
+  mintPublishTokenV1Handler,
  listCodePluginsV1Handler,
  listBundlePluginsV1Handler,
  searchSkillsV1Handler,
@@ -1,21 +1,32 @@
 import { getAuthUserId } from "@convex-dev/auth/server";
-import { PackagePublishRequestSchema, parseArk } from "clawhub-schema";
+import {
+  PackagePublishRequestSchema,
+  PackageTrustedPublisherUpsertRequestSchema,
+  PublishTokenMintRequestSchema,
+  parseArk,
+} from "clawhub-schema";
 import { api, internal } from "../_generated/api";
 import type { Doc, Id } from "../_generated/dataModel";
 import type { ActionCtx } from "../_generated/server";
 import { getOptionalApiTokenUserId } from "../lib/apiTokenAuth";
+import {
+  fetchGitHubRepositoryIdentity,
+  verifyGitHubActionsTrustedPublishJwt,
+} from "../lib/githubActionsOidc";
 import { corsHeaders, mergeHeaders } from "../lib/httpHeaders";
+import { applyRateLimit } from "../lib/httpRateLimit";
 import { getPackageDownloadSecurityBlock } from "../lib/packageSecurity";
 import { getPublishFileSizeError, MAX_PUBLISH_FILE_BYTES } from "../lib/publishLimits";
-import { applyRateLimit } from "../lib/httpRateLimit";
-import { buildDeterministicPackageZip } from "../lib/skillZip";
 import { isMacJunkPath, isTextFile } from "../lib/skills";
+import { buildDeterministicPackageZip } from "../lib/skillZip";
+import { generateToken, hashToken } from "../lib/tokens";
 import {
  MAX_RAW_FILE_BYTES,
  getPathSegments,
  json,
  resolveTagsBatch,
  requireApiTokenUserOrResponse,
+  requirePackagePublishAuthOrResponse,
  safeTextFileResponse,
  text,
  toOptionalNumber,
@@ -39,11 +50,20 @@ const internalRefs = internal as unknown as {
    listPageForViewerInternal: unknown;
    searchForViewerInternal: unknown;
    listVersionsForViewerInternal: unknown;
+    getPackageByNameInternal: unknown;
+    getTrustedPublisherByPackageIdInternal: unknown;
    getVersionByNameForViewerInternal: unknown;
    publishPackageForUserInternal: unknown;
+    publishPackageForTrustedPublisherInternal: unknown;
+    setTrustedPublisherForUserInternal: unknown;
+    deleteTrustedPublisherForUserInternal: unknown;
    getReleasesByIdsInternal: unknown;
    getReleaseByPackageAndVersionInternal: unknown;
    getReleaseByIdInternal: unknown;
+    insertAuditLogInternal: unknown;
+  };
+  packagePublishTokens: {
+    createInternal: unknown;
  };
  skills: {
    getSkillBySlugInternal: unknown;
@@ -60,11 +80,21 @@ async function runActionRef<T>(ctx: ActionCtx, ref: unknown, args: unknown): Pro
  return (await ctx.runAction(ref as never, args as never)) as T;
 }

+async function runMutationRef<T>(ctx: ActionCtx, ref: unknown, args: unknown): Promise<T> {
+  return (await ctx.runMutation(ref as never, args as never)) as T;
+}
+
 async function getOptionalViewerUserIdForRequest(ctx: ActionCtx, request: Request) {
  const apiTokenUserId = await getOptionalApiTokenUserId(ctx, request);
  if (apiTokenUserId) return apiTokenUserId;
  try {
-    return (await getAuthUserId(ctx)) ?? null;
+    const userId = (await getAuthUserId(ctx)) ?? null;
+    if (!userId) return null;
+    const user = await runQueryRef<Doc<"users"> | null>(ctx, internal.users.getByIdInternal, {
+      userId,
+    });
+    if (!user || user.deletedAt || user.deactivatedAt) return null;
+    return userId;
  } catch {
    // Public package reads should degrade to anonymous when cookie-backed auth is stale.
    return null;
@@ -134,11 +164,38 @@ type ReleaseLike = {
  softDeletedAt?: number;
 };

+type PackageTrustedPublisherLike = {
+  _id: Id<"packageTrustedPublishers">;
+  packageId: Id<"packages">;
+  provider: "github-actions";
+  repository: string;
+  repositoryId: string;
+  repositoryOwner: string;
+  repositoryOwnerId: string;
+  workflowFilename: string;
+  environment?: string;
+  createdAt: number;
+  updatedAt: number;
+};
+
 function toVisibleRelease(release: ReleaseLike | null) {
  if (!release || ("softDeletedAt" in release && release.softDeletedAt !== undefined)) return null;
  return release;
 }

+function toPublicTrustedPublisher(trustedPublisher: PackageTrustedPublisherLike | null) {
+  if (!trustedPublisher) return null;
+  return {
+    provider: trustedPublisher.provider,
+    repository: trustedPublisher.repository,
+    repositoryId: trustedPublisher.repositoryId,
+    repositoryOwner: trustedPublisher.repositoryOwner,
+    repositoryOwnerId: trustedPublisher.repositoryOwnerId,
+    workflowFilename: trustedPublisher.workflowFilename,
+    ...(trustedPublisher.environment ? { environment: trustedPublisher.environment } : {}),
+  };
+}
+
 function getReleaseSecurityBlock(release: ReleaseLike) {
  return getPackageDownloadSecurityBlock(release);
 }
@@ -149,9 +206,13 @@ async function resolvePackageTags(
 ): Promise<Record<string, string>> {
  const releaseIds = Object.values(tags);
  if (releaseIds.length === 0) return {};
-  const releases = await runQueryRef<ReleaseLike[]>(ctx, internalRefs.packages.getReleasesByIdsInternal, {
-    releaseIds,
-  });
+  const releases = await runQueryRef<ReleaseLike[]>(
+    ctx,
+    internalRefs.packages.getReleasesByIdsInternal,
+    {
+      releaseIds,
+    },
+  );
  const byId = new Map(releases.map((release) => [release._id, release.version]));
  return Object.fromEntries(
    Object.entries(tags)
@@ -222,8 +283,12 @@ function decodeUnifiedCatalogCursor(raw: string | null | undefined): UnifiedCata
    };
  }
  try {
-    const parsed = JSON.parse(raw.slice(UNIFIED_CATALOG_CURSOR_PREFIX.length)) as Partial<UnifiedCatalogCursorState>;
-    const normalize = (input: Partial<CatalogSourceCursorState> | undefined): CatalogSourceCursorState => ({
+    const parsed = JSON.parse(
+      raw.slice(UNIFIED_CATALOG_CURSOR_PREFIX.length),
+    ) as Partial<UnifiedCatalogCursorState>;
+    const normalize = (
+      input: Partial<CatalogSourceCursorState> | undefined,
+    ): CatalogSourceCursorState => ({
      cursor: typeof input?.cursor === "string" ? input.cursor : null,
      offset: typeof input?.offset === "number" && input.offset > 0 ? input.offset : 0,
      pageSize: typeof input?.pageSize === "number" && input.pageSize > 0 ? input.pageSize : null,
@@ -365,6 +430,7 @@ function parsePackagePublishBody(body: unknown) {
    family: "skill" | "code-plugin" | "bundle-plugin";
    version: string;
    changelog: string;
+    manualOverrideReason?: string;
    channel?: "official" | "community" | "private";
    tags?: string[];
    source?: Record<string, unknown>;
@@ -385,6 +451,7 @@ function parsePackagePublishBody(body: unknown) {
    family: parsed.family,
    version: parsed.version,
    changelog: parsed.changelog,
+    manualOverrideReason: parsed.manualOverrideReason?.trim() || undefined,
    channel: parsed.channel ?? undefined,
    tags: parsed.tags?.filter(Boolean) ?? undefined,
    source: parsed.source ?? undefined,
@@ -416,7 +483,9 @@ async function parseMultipartPackagePublish(ctx: ActionCtx, request: Request) {
    }
    const buffer = new Uint8Array(await entry.arrayBuffer());
    const digest = await crypto.subtle.digest("SHA-256", buffer);
-    const sha256 = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const sha256 = Array.from(new Uint8Array(digest), (byte) =>
+      byte.toString(16).padStart(2, "0"),
+    ).join("");
    const storageId = await ctx.storage.store(entry);
    files.push({
      path: entry.name,
@@ -529,7 +598,10 @@ async function listPackages(
      ]);

      if (!packageCandidate && !skillCandidate) break;
-      if (!skillCandidate || (packageCandidate && compareCatalogItems(packageCandidate, skillCandidate) <= 0)) {
+      if (
+        !skillCandidate ||
+        (packageCandidate && compareCatalogItems(packageCandidate, skillCandidate) <= 0)
+      ) {
        items.push(packageCandidate!);
        packageSource.index += 1;
      } else {
@@ -597,7 +669,7 @@ export async function publishPackageV1Handler(ctx: ActionCtx, request: Request)
  const rate = await applyRateLimit(ctx, request, "write");
  if (!rate.ok) return rate.response;

-  const auth = await requireApiTokenUserOrResponse(ctx, request, rate.headers);
+  const auth = await requirePackagePublishAuthOrResponse(ctx, request, rate.headers);
  if (!auth.ok) return auth.response;

  try {
@@ -605,16 +677,222 @@ export async function publishPackageV1Handler(ctx: ActionCtx, request: Request)
    const payload = contentType.includes("multipart/form-data")
      ? await parseMultipartPackagePublish(ctx, request)
      : parsePackagePublishBody(await request.json());
-    const result = await runActionRef(ctx, internalRefs.packages.publishPackageForUserInternal, {
-      actorUserId: auth.userId,
-      payload,
-    });
+    const result =
+      auth.auth.kind === "user"
+        ? await runActionRef(ctx, internalRefs.packages.publishPackageForUserInternal, {
+            actorUserId: auth.auth.userId,
+            payload,
+          })
+        : await runActionRef(ctx, internalRefs.packages.publishPackageForTrustedPublisherInternal, {
+            publishTokenId: auth.auth.publishToken._id,
+            payload,
+          });
    return json(result, 200, rate.headers);
  } catch (error) {
    return text(error instanceof Error ? error.message : "Publish failed", 400, rate.headers);
  }
 }

+async function getPackageAndTrustedPublisherByName(ctx: ActionCtx, packageName: string) {
+  const pkg = await runQueryRef<Doc<"packages"> | null>(
+    ctx,
+    internalRefs.packages.getPackageByNameInternal,
+    {
+      name: packageName,
+    },
+  );
+  if (!pkg || pkg.softDeletedAt) return { pkg: null, trustedPublisher: null };
+  const trustedPublisher = await runQueryRef<PackageTrustedPublisherLike | null>(
+    ctx,
+    internalRefs.packages.getTrustedPublisherByPackageIdInternal,
+    { packageId: pkg._id },
+  );
+  return { pkg, trustedPublisher };
+}
+
+export async function mintPublishTokenV1Handler(ctx: ActionCtx, request: Request) {
+  const rate = await applyRateLimit(ctx, request, "write");
+  if (!rate.ok) return rate.response;
+
+  const parsedBody = await request.json().catch(() => null);
+  if (!parsedBody) return text("Invalid JSON", 400, rate.headers);
+
+  try {
+    const payload = parseArk(
+      PublishTokenMintRequestSchema,
+      parsedBody,
+      "Publish token mint payload",
+    ) as {
+      packageName: string;
+      version: string;
+      githubOidcToken: string;
+    };
+    const { pkg, trustedPublisher } = await getPackageAndTrustedPublisherByName(
+      ctx,
+      payload.packageName,
+    );
+    if (!pkg) return text("Package not found", 404, rate.headers);
+    if (!trustedPublisher) {
+      return text("Trusted publisher config is not set for this package", 403, rate.headers);
+    }
+
+    try {
+      const verified = await verifyGitHubActionsTrustedPublishJwt(payload.githubOidcToken, {
+        repository: trustedPublisher.repository,
+        repositoryId: trustedPublisher.repositoryId,
+        repositoryOwner: trustedPublisher.repositoryOwner,
+        repositoryOwnerId: trustedPublisher.repositoryOwnerId,
+        workflowFilename: trustedPublisher.workflowFilename,
+        ...(trustedPublisher.environment ? { environment: trustedPublisher.environment } : {}),
+      });
+      const { token, prefix } = generateToken();
+      const tokenHash = await hashToken(token);
+      const expiresAt = Date.now() + 15 * 60_000;
+
+      await ctx.runMutation(
+        internalRefs.packagePublishTokens.createInternal as never,
+        {
+          packageId: pkg._id,
+          version: payload.version,
+          prefix,
+          tokenHash,
+          provider: "github-actions",
+          repository: verified.repository,
+          repositoryId: verified.repositoryId,
+          repositoryOwner: verified.repositoryOwner,
+          repositoryOwnerId: verified.repositoryOwnerId,
+          workflowFilename: verified.workflowFilename,
+          ...(trustedPublisher.environment ? { environment: trustedPublisher.environment } : {}),
+          runId: verified.runId,
+          runAttempt: verified.runAttempt,
+          sha: verified.sha,
+          ref: verified.ref,
+          ...(verified.refType ? { refType: verified.refType } : {}),
+          ...(verified.actor ? { actor: verified.actor } : {}),
+          ...(verified.actorId ? { actorId: verified.actorId } : {}),
+          expiresAt,
+        } as never,
+      );
+      await ctx.runMutation(
+        internalRefs.packages.insertAuditLogInternal as never,
+        {
+          actorUserId: pkg.ownerUserId,
+          action: "package.publish_token.mint",
+          targetType: "package",
+          targetId: String(pkg._id),
+          metadata: {
+            version: payload.version,
+            repository: verified.repository,
+            workflowFilename: verified.workflowFilename,
+            ...(verified.environment ? { environment: verified.environment } : {}),
+            runId: verified.runId,
+            runAttempt: verified.runAttempt,
+            sha: verified.sha,
+            ref: verified.ref,
+            decision: "allowed",
+          },
+        } as never,
+      );
+      return json({ token, expiresAt }, 200, rate.headers);
+    } catch (error) {
+      await ctx.runMutation(
+        internalRefs.packages.insertAuditLogInternal as never,
+        {
+          actorUserId: pkg.ownerUserId,
+          action: "package.publish_token.mint_rejected",
+          targetType: "package",
+          targetId: String(pkg._id),
+          metadata: {
+            version: payload.version,
+            repository: trustedPublisher.repository,
+            workflowFilename: trustedPublisher.workflowFilename,
+            ...(trustedPublisher.environment ? { environment: trustedPublisher.environment } : {}),
+            decision: "rejected",
+            reason: error instanceof Error ? error.message : "Token verification failed",
+          },
+        } as never,
+      );
+      throw error;
+    }
+  } catch (error) {
+    return text(error instanceof Error ? error.message : "Token mint failed", 400, rate.headers);
+  }
+}
+
+export async function packagesPostRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const segments = getPathSegments(request, "/api/v1/packages/");
+  if (segments[1] !== "trusted-publisher" || segments.length !== 2) {
+    return text("Not found", 404);
+  }
+  const rate = await applyRateLimit(ctx, request, "write");
+  if (!rate.ok) return rate.response;
+  const auth = await requireApiTokenUserOrResponse(ctx, request, rate.headers);
+  if (!auth.ok) return auth.response;
+
+  try {
+    const body = parseArk(
+      PackageTrustedPublisherUpsertRequestSchema,
+      await request.json(),
+      "Trusted publisher payload",
+    ) as {
+      repository: string;
+      workflowFilename: string;
+      environment?: string;
+    };
+    const repositoryIdentity = await fetchGitHubRepositoryIdentity(body.repository);
+    const trustedPublisher = await runMutationRef<PackageTrustedPublisherLike | null>(
+      ctx,
+      internalRefs.packages.setTrustedPublisherForUserInternal,
+      {
+        actorUserId: auth.userId,
+        packageName: segments[0]!,
+        repository: repositoryIdentity.repository,
+        repositoryId: repositoryIdentity.repositoryId,
+        repositoryOwner: repositoryIdentity.repositoryOwner,
+        repositoryOwnerId: repositoryIdentity.repositoryOwnerId,
+        workflowFilename: body.workflowFilename,
+        ...(body.environment ? { environment: body.environment } : {}),
+      },
+    );
+    return json(
+      { trustedPublisher: toPublicTrustedPublisher(trustedPublisher) },
+      200,
+      rate.headers,
+    );
+  } catch (error) {
+    return text(
+      error instanceof Error ? error.message : "Trusted publisher update failed",
+      400,
+      rate.headers,
+    );
+  }
+}
+
+export async function packagesDeleteRouterV1Handler(ctx: ActionCtx, request: Request) {
+  const segments = getPathSegments(request, "/api/v1/packages/");
+  if (segments[1] !== "trusted-publisher" || segments.length !== 2) {
+    return text("Not found", 404);
+  }
+  const rate = await applyRateLimit(ctx, request, "write");
+  if (!rate.ok) return rate.response;
+  const auth = await requireApiTokenUserOrResponse(ctx, request, rate.headers);
+  if (!auth.ok) return auth.response;
+
+  try {
+    await runMutationRef(ctx, internalRefs.packages.deleteTrustedPublisherForUserInternal, {
+      actorUserId: auth.userId,
+      packageName: segments[0]!,
+    });
+    return json({ ok: true }, 200, rate.headers);
+  } catch (error) {
+    return text(
+      error instanceof Error ? error.message : "Trusted publisher delete failed",
+      400,
+      rate.headers,
+    );
+  }
+}
+
 async function getReleaseForRequest(
  ctx: ActionCtx,
  pkg: Pick<PublicPackageDocLike, "_id" | "tags" | "latestReleaseId">,
@@ -656,9 +934,7 @@ async function getReleaseForRequest(
 function isReadmeVariantPath(path: string) {
  const normalized = path.trim().toLowerCase();
  return (
-    normalized === "readme.md" ||
-    normalized === "readme.mdx" ||
-    normalized === "readme.markdown"
+    normalized === "readme.md" || normalized === "readme.mdx" || normalized === "readme.markdown"
  );
 }

@@ -698,13 +974,11 @@ function resolvePackageFilePath(release: ReleaseLike, requestedPath: string) {
 }

 async function getSkillDetailForRequest(ctx: ActionCtx, slug: string) {
-  return (await runQueryRef(ctx, apiRefs.skills.getBySlug, { slug })) as
-    | {
-        skill: SkillPackageDocLike | null;
-        latestVersion: SkillVersionLike | null;
-        owner: { handle?: string; displayName?: string; image?: string } | null;
-      }
-    | null;
+  return (await runQueryRef(ctx, apiRefs.skills.getBySlug, { slug })) as {
+    skill: SkillPackageDocLike | null;
+    latestVersion: SkillVersionLike | null;
+    owner: { handle?: string; displayName?: string; image?: string } | null;
+  } | null;
 }

 async function getSkillVersionForRequest(
@@ -769,25 +1043,33 @@ async function searchPackages(

  let results: CatalogSearchEntry[];
  if (family === "skill") {
-    results = await runQueryRef<CatalogSearchEntry[]>(ctx, apiRefs.skills.searchPackageCatalogPublic, {
-      query: queryText,
-      limit,
-      channel,
-      isOfficial,
-      executesCode,
-      capabilityTag,
-    });
+    results = await runQueryRef<CatalogSearchEntry[]>(
+      ctx,
+      apiRefs.skills.searchPackageCatalogPublic,
+      {
+        query: queryText,
+        limit,
+        channel,
+        isOfficial,
+        executesCode,
+        capabilityTag,
+      },
+    );
  } else if (family || !includeSkills) {
-    results = await runQueryRef<CatalogSearchEntry[]>(ctx, internalRefs.packages.searchForViewerInternal, {
-      query: queryText,
-      limit,
-      family,
-      channel,
-      isOfficial,
-      executesCode,
-      capabilityTag,
-      viewerUserId: viewerUserId ?? undefined,
-    });
+    results = await runQueryRef<CatalogSearchEntry[]>(
+      ctx,
+      internalRefs.packages.searchForViewerInternal,
+      {
+        query: queryText,
+        limit,
+        family,
+        channel,
+        isOfficial,
+        executesCode,
+        capabilityTag,
+        viewerUserId: viewerUserId ?? undefined,
+      },
+    );
  } else {
    const [packageResults, skillResults] = await Promise.all([
      runQueryRef<CatalogSearchEntry[]>(ctx, internalRefs.packages.searchForViewerInternal, {
@@ -840,20 +1122,14 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques

  const packageName = segments[0] ?? "";
  const viewerUserId = await getOptionalViewerUserIdForRequest(ctx, request);
-  const detail = (await runQueryRef(
-    ctx,
-    internalRefs.packages.getByNameForViewerInternal,
-    {
-      name: packageName,
-      viewerUserId: viewerUserId ?? undefined,
-    },
-  )) as
-    | {
-        package: PublicPackageDocLike | null;
-        latestRelease: ReleaseLike | null;
-        owner: { _id: Id<"users">; handle?: string; displayName?: string; image?: string } | null;
-      }
-    | null;
+  const detail = (await runQueryRef(ctx, internalRefs.packages.getByNameForViewerInternal, {
+    name: packageName,
+    viewerUserId: viewerUserId ?? undefined,
+  })) as {
+    package: PublicPackageDocLike | null;
+    latestRelease: ReleaseLike | null;
+    owner: { _id: Id<"users">; handle?: string; displayName?: string; image?: string } | null;
+  } | null;
  const skillDetail = detail?.package ? null : await getSkillDetailForRequest(ctx, packageName);
  if (!detail?.package && !skillDetail?.skill) return text("Package not found", 404, rate.headers);
  const packageDetail = detail?.package ? detail : null;
@@ -873,23 +1149,44 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques
        rate.headers,
      );
    }
-    return json({
-      package: {
-        ...publicPackage!,
-        tags: await resolvePackageTags(ctx, publicPackage!.tags),
+    return json(
+      {
+        package: {
+          ...publicPackage!,
+          tags: await resolvePackageTags(ctx, publicPackage!.tags),
+        },
+        owner: packageOwner
+          ? {
+              handle: packageOwner.handle ?? null,
+              displayName: packageOwner.displayName ?? null,
+              image: packageOwner.image ?? null,
+            }
+          : null,
      },
-      owner: packageOwner
-        ? {
-            handle: packageOwner.handle ?? null,
-            displayName: packageOwner.displayName ?? null,
-            image: packageOwner.image ?? null,
-          }
-        : null,
-    }, 200, rate.headers);
+      200,
+      rate.headers,
+    );
+  }
+
+  if (segments[1] === "trusted-publisher" && segments.length === 2) {
+    if (!publicPackage) return text("Not found", 404, rate.headers);
+    const trustedPublisher = await runQueryRef<PackageTrustedPublisherLike | null>(
+      ctx,
+      internalRefs.packages.getTrustedPublisherByPackageIdInternal,
+      { packageId: publicPackage._id },
+    );
+    return json(
+      { trustedPublisher: toPublicTrustedPublisher(trustedPublisher) },
+      200,
+      rate.headers,
+    );
  }

  if (segments[1] === "versions" && segments.length === 2) {
-    const limit = Math.max(1, Math.min(toOptionalNumber(new URL(request.url).searchParams.get("limit")) ?? 25, 100));
+    const limit = Math.max(
+      1,
+      Math.min(toOptionalNumber(new URL(request.url).searchParams.get("limit")) ?? 25, 100),
+    );
    const cursor = new URL(request.url).searchParams.get("cursor");
    if (skillDetail?.skill) {
      const result = (await runQueryRef(ctx, apiRefs.skills.listVersionsPage, {
@@ -901,15 +1198,19 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques
        nextCursor: string | null;
      };
      const tags = await resolveSkillTags(ctx, skillDetail.skill.tags);
-      return json({
-        items: result.items.map((version) => ({
-          version: version.version,
-          createdAt: version.createdAt,
-          changelog: version.changelog,
-          distTags: skillVersionTags(tags, version.version),
-        })),
-        nextCursor: result.nextCursor,
-      }, 200, rate.headers);
+      return json(
+        {
+          items: result.items.map((version) => ({
+            version: version.version,
+            createdAt: version.createdAt,
+            changelog: version.changelog,
+            distTags: skillVersionTags(tags, version.version),
+          })),
+          nextCursor: result.nextCursor,
+        },
+        200,
+        rate.headers,
+      );
    }
    const result = await runQueryRef<{
      page: ReleaseLike[];
@@ -920,47 +1221,59 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques
      viewerUserId: viewerUserId ?? undefined,
      paginationOpts: { cursor, numItems: limit },
    });
-    return json({
-      items: result.page.map((release: ReleaseLike) => ({
-        version: release.version,
-        createdAt: release.createdAt,
-        changelog: release.changelog,
-        distTags: release.distTags ?? [],
-      })),
-      nextCursor: result.isDone ? null : result.continueCursor,
-    }, 200, rate.headers);
+    return json(
+      {
+        items: result.page.map((release: ReleaseLike) => ({
+          version: release.version,
+          createdAt: release.createdAt,
+          changelog: release.changelog,
+          distTags: release.distTags ?? [],
+        })),
+        nextCursor: result.isDone ? null : result.continueCursor,
+      },
+      200,
+      rate.headers,
+    );
  }

  if (segments[1] === "versions" && segments[2]) {
    if (skillDetail?.skill) {
-      const version = (await runQueryRef(ctx, internalRefs.skills.getVersionBySkillAndVersionInternal, {
-        skillId: skillDetail.skill._id,
-        version: segments[2],
-      })) as SkillVersionLike | null;
+      const version = (await runQueryRef(
+        ctx,
+        internalRefs.skills.getVersionBySkillAndVersionInternal,
+        {
+          skillId: skillDetail.skill._id,
+          version: segments[2],
+        },
+      )) as SkillVersionLike | null;
      if (!version || version.softDeletedAt) return text("Version not found", 404, rate.headers);
      const tags = await resolveSkillTags(ctx, skillDetail.skill.tags);
-      return json({
-        package: {
-          name: skillDetail.skill.slug,
-          displayName: skillDetail.skill.displayName,
-          family: "skill",
+      return json(
+        {
+          package: {
+            name: skillDetail.skill.slug,
+            displayName: skillDetail.skill.displayName,
+            family: "skill",
+          },
+          version: {
+            version: version.version,
+            createdAt: version.createdAt,
+            changelog: version.changelog,
+            distTags: skillVersionTags(tags, version.version),
+            files: version.files.map((file) => ({
+              path: file.path,
+              size: file.size,
+              sha256: file.sha256,
+              contentType: file.contentType,
+            })),
+            compatibility: null,
+            capabilities: null,
+            verification: null,
+          },
        },
-        version: {
-          version: version.version,
-          createdAt: version.createdAt,
-          changelog: version.changelog,
-          distTags: skillVersionTags(tags, version.version),
-          files: version.files.map((file) => ({
-            path: file.path,
-            size: file.size,
-            sha256: file.sha256,
-            contentType: file.contentType,
-          })),
-          compatibility: null,
-          capabilities: null,
-          verification: null,
-        },
-      }, 200, rate.headers);
+        200,
+        rate.headers,
+      );
    }
    const result = (await runQueryRef(
      ctx,
@@ -972,32 +1285,36 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques
      },
    )) as { package: PublicPackageDocLike; version: ReleaseLike } | null;
    if (!result) return text("Version not found", 404, rate.headers);
-    return json({
-      package: {
-        name: result.package.name,
-        displayName: result.package.displayName,
-        family: result.package.family,
+    return json(
+      {
+        package: {
+          name: result.package.name,
+          displayName: result.package.displayName,
+          family: result.package.family,
+        },
+        version: {
+          version: result.version.version,
+          createdAt: result.version.createdAt,
+          changelog: result.version.changelog,
+          distTags: result.version.distTags ?? [],
+          files: result.version.files.map((file) => ({
+            path: file.path,
+            size: file.size,
+            sha256: file.sha256,
+            contentType: file.contentType,
+          })),
+          compatibility: result.version.compatibility ?? null,
+          capabilities: result.version.capabilities ?? null,
+          verification: result.version.verification ?? null,
+          sha256hash: result.version.sha256hash ?? null,
+          vtAnalysis: result.version.vtAnalysis ?? null,
+          llmAnalysis: result.version.llmAnalysis ?? null,
+          staticScan: result.version.staticScan ?? null,
+        },
      },
-      version: {
-        version: result.version.version,
-        createdAt: result.version.createdAt,
-        changelog: result.version.changelog,
-        distTags: result.version.distTags ?? [],
-        files: result.version.files.map((file) => ({
-          path: file.path,
-          size: file.size,
-          sha256: file.sha256,
-          contentType: file.contentType,
-        })),
-        compatibility: result.version.compatibility ?? null,
-        capabilities: result.version.capabilities ?? null,
-        verification: result.version.verification ?? null,
-        sha256hash: result.version.sha256hash ?? null,
-        vtAnalysis: result.version.vtAnalysis ?? null,
-        llmAnalysis: result.version.llmAnalysis ?? null,
-        staticScan: result.version.staticScan ?? null,
-      },
-    }, 200, rate.headers);
+      200,
+      rate.headers,
+    );
  }

  if (segments[1] === "file") {
@@ -1008,7 +1325,8 @@ export async function packagesGetRouterV1Handler(ctx: ActionCtx, request: Reques
      if (!version || version.softDeletedAt) return text("Version not found", 404, rate.headers);
      const file = resolveSkillFilePath(version, path);
      if (!file) return text("File not found", 404, rate.headers);
-      if (!("storageId" in file) || !file.storageId) return text("File not found", 404, rate.headers);
+      if (!("storageId" in file) || !file.storageId)
+        return text("File not found", 404, rate.headers);
      if (!isTextFile(file.path, file.contentType)) {
        return text("Binary files are not served inline", 415, rate.headers);
      }
@@ -1115,6 +1433,7 @@ type PublicPackageDocLike = {
  compatibility?: Doc<"packages">["compatibility"];
  capabilities?: Doc<"packages">["capabilities"];
  verification?: Doc<"packages">["verification"];
+  stats?: { downloads: number; installs: number; stars: number; versions: number };
  createdAt: number;
  updatedAt: number;
 };
@@ -1,9 +1,9 @@
-import { CliPublishRequestSchema, parseArk } from "clawhub-schema";
+import { CliPublishRequestSchema, normalizeTextContentType, parseArk } from "clawhub-schema";
 import { internal } from "../_generated/api";
 import type { Doc, Id } from "../_generated/dataModel";
 import type { ActionCtx } from "../_generated/server";
 import { assertAdmin } from "../lib/access";
-import { requireApiTokenUser } from "../lib/apiTokenAuth";
+import { requireApiTokenUser, requirePackagePublishAuth } from "../lib/apiTokenAuth";
 import { corsHeaders, mergeHeaders } from "../lib/httpHeaders";
 import { getPublishFileSizeError, MAX_PUBLISH_FILE_BYTES } from "../lib/publishLimits";
 import { isMacJunkPath } from "../lib/skills";
@@ -25,7 +25,9 @@ export function safeTextFileResponse(params: {
  size: number;
  headers?: HeadersInit;
 }) {
-  const isSvg = isSvgLike(params.contentType, params.path);
+  const contentType =
+    normalizeTextContentType(params.path, params.contentType) ?? params.contentType;
+  const isSvg = isSvgLike(contentType, params.path);

  // For any text response that a browser might try to render, lock it down.
  // In particular, this prevents SVG <foreignObject> script execution from reading
@@ -33,8 +35,8 @@ export function safeTextFileResponse(params: {
  const headers = mergeHeaders(
    params.headers,
    {
-      "Content-Type": params.contentType
-        ? `${params.contentType}; charset=utf-8`
+      "Content-Type": contentType
+        ? `${contentType}; charset=utf-8`
        : "text/plain; charset=utf-8",
      "Cache-Control": "private, max-age=60",
      ETag: params.sha256,
@@ -101,6 +103,18 @@ export async function requireApiTokenUserOrResponse(
  }
 }

+export async function requirePackagePublishAuthOrResponse(
+  ctx: ActionCtx,
+  request: Request,
+  headers: HeadersInit,
+) {
+  try {
+    return { ok: true as const, auth: await requirePackagePublishAuth(ctx, request) };
+  } catch {
+    return { ok: false as const, response: text("Unauthorized", 401, headers) };
+  }
+}
+
 export function requireAdminOrResponse(user: Doc<"users">, headers: HeadersInit) {
  try {
    assertAdmin(user);
@@ -1,9 +1,11 @@
 import { api, internal } from "../_generated/api";
+import { normalizeTextContentType } from "clawhub-schema";
 import type { Doc, Id } from "../_generated/dataModel";
 import type { ActionCtx } from "../_generated/server";
 import { getOptionalApiTokenUserId, requireApiTokenUser } from "../lib/apiTokenAuth";
 import { applyRateLimit, parseBearerToken } from "../lib/httpRateLimit";
 import { parseBooleanQueryParam, resolveBooleanQueryParam } from "../lib/httpUtils";
+import type { LlmEvalDimension } from "../lib/securityPrompt";
 import { publishVersionForUser } from "../skills";
 import {
  MAX_RAW_FILE_BYTES,
@@ -69,6 +71,11 @@ type PublicSkillVersionParsed = {
  clawdis?: { os?: string[]; nix?: { plugin?: boolean; systems?: string[] } };
 };

+type PublicSkillVersionStaticScan = Pick<
+  NonNullable<Doc<"skillVersions">["staticScan"]>,
+  "status" | "reasonCodes" | "summary" | "engineVersion" | "checkedAt"
+>;
+
 type PublicSkillVersionResponse = {
  _id: Id<"skillVersions">;
  version: string;
@@ -81,6 +88,8 @@ type PublicSkillVersionResponse = {
  sha256hash?: string;
  vtAnalysis?: Doc<"skillVersions">["vtAnalysis"];
  llmAnalysis?: Doc<"skillVersions">["llmAnalysis"];
+  staticScan?: PublicSkillVersionStaticScan;
+  capabilityTags?: string[];
 };

 type ModerationEvidence = {
@@ -189,7 +198,16 @@ type SkillSecuritySnapshot = {
  hasScanResult: boolean;
  sha256hash: string | null;
  virustotalUrl: string | null;
+  capabilityTags: string[];
  scanners: {
+    static: {
+      status: string;
+      normalizedStatus: NormalizedSecurityStatus;
+      reasonCodes: string[];
+      summary: string | null;
+      engineVersion: string | null;
+      checkedAt: number | null;
+    } | null;
    vt: {
      status: string;
      verdict: string | null;
@@ -204,7 +222,7 @@ type SkillSecuritySnapshot = {
      normalizedStatus: NormalizedSecurityStatus;
      confidence: string | null;
      summary: string | null;
-      dimensions: NonNullable<Doc<"skillVersions">["llmAnalysis"]>["dimensions"] | null;
+      dimensions: LlmEvalDimension[] | null;
      guidance: string | null;
      findings: string | null;
      model: string | null;
@@ -260,7 +278,7 @@ function mergeSecurityStatuses(statuses: NormalizedSecurityStatus[]) {
 }

 function hasLlmDimensionWarnings(
-  dimensions: NonNullable<Doc<"skillVersions">["llmAnalysis"]>["dimensions"] | undefined,
+  dimensions: LlmEvalDimension[] | undefined,
 ) {
  if (!Array.isArray(dimensions)) return false;
  return dimensions.some((dimension) => {
@@ -271,28 +289,37 @@ function hasLlmDimensionWarnings(
 }

 function buildSkillSecuritySnapshot(
-  version: Pick<PublicSkillVersionResponse, "sha256hash" | "vtAnalysis" | "llmAnalysis">,
+  version: Pick<
+    PublicSkillVersionResponse,
+    "sha256hash" | "vtAnalysis" | "llmAnalysis" | "staticScan" | "capabilityTags"
+  >,
 ): SkillSecuritySnapshot | null {
+  const capabilityTags = version.capabilityTags ?? [];
  const sha256hash = version.sha256hash ?? null;
  const vt = version.vtAnalysis;
  const llm = version.llmAnalysis;
+  const staticScan = version.staticScan;

-  if (!sha256hash && !vt && !llm) return null;
+  if (!sha256hash && !vt && !llm && !staticScan && capabilityTags.length === 0) return null;

+  const staticStatus = staticScan ? normalizeSecurityStatus(staticScan.status) : null;
  const vtStatus = vt ? normalizeSecurityStatus(vt.verdict ?? vt.status) : null;
  const llmStatus = llm ? normalizeSecurityStatus(llm.verdict ?? llm.status) : null;

  const statuses: NormalizedSecurityStatus[] = [];
+  if (staticStatus) statuses.push(staticStatus);
  if (vtStatus) statuses.push(vtStatus);
  if (llmStatus) statuses.push(llmStatus);
  if (statuses.length === 0 && sha256hash) statuses.push("pending");
  const status = mergeSecurityStatuses(statuses);
  const hasScanResult =
-    isDefinitiveSecurityStatus(vtStatus) || isDefinitiveSecurityStatus(llmStatus);
+    isDefinitiveSecurityStatus(staticStatus) ||
+    isDefinitiveSecurityStatus(vtStatus) ||
+    isDefinitiveSecurityStatus(llmStatus);
  const hasWarnings =
    status === "suspicious" || status === "malicious" || hasLlmDimensionWarnings(llm?.dimensions);

-  const checkedAtCandidates = [vt?.checkedAt, llm?.checkedAt].filter(
+  const checkedAtCandidates = [staticScan?.checkedAt, vt?.checkedAt, llm?.checkedAt].filter(
    (value): value is number => typeof value === "number",
  );
  const checkedAt = checkedAtCandidates.length > 0 ? Math.max(...checkedAtCandidates) : null;
@@ -305,7 +332,18 @@ function buildSkillSecuritySnapshot(
    hasScanResult,
    sha256hash,
    virustotalUrl: sha256hash ? `https://www.virustotal.com/gui/file/${sha256hash}` : null,
+    capabilityTags,
    scanners: {
+      static: staticScan
+        ? {
+            status: staticScan.status,
+            normalizedStatus: staticStatus ?? "pending",
+            reasonCodes: staticScan.reasonCodes ?? [],
+            summary: staticScan.summary ?? null,
+            engineVersion: staticScan.engineVersion ?? null,
+            checkedAt: staticScan.checkedAt ?? null,
+          }
+        : null,
      vt: vt
        ? {
            status: vt.status,
@@ -726,7 +764,7 @@ export async function skillsGetRouterV1Handler(ctx: ActionCtx, request: Request)
            path: file.path,
            size: file.size,
            sha256: file.sha256,
-            contentType: file.contentType ?? null,
+            contentType: normalizeTextContentType(file.path, file.contentType) ?? null,
          })),
          security: security ?? undefined,
        },
@@ -22,7 +22,10 @@ export async function starsPostRouterV1Handler(ctx: ActionCtx, request: Request)
      skillId: skill._id,
    });
    return json(result, 200, rate.headers);
-  } catch {
+  } catch (e) {
+    if (e instanceof Error && e.message === "Skill not found") {
+      return text("Skill not found", 404, rate.headers);
+    }
    return text("Unauthorized", 401, rate.headers);
  }
 }
@@ -236,9 +236,9 @@ async function handleAdminEnsurePublisher(
  const handle = typeof payload.handle === "string" ? payload.handle.trim().toLowerCase() : "";
  if (!handle) return text("Missing handle", 400, headers);

-  const displayName = typeof payload.displayName === "string" ? payload.displayName.trim() : undefined;
-  const trusted =
-    typeof payload.trusted === "boolean" ? payload.trusted : true;
+  const displayName =
+    typeof payload.displayName === "string" ? payload.displayName.trim() : undefined;
+  const trusted = typeof payload.trusted === "boolean" ? payload.trusted : true;

  try {
    const result = await ctx.runMutation(internal.publishers.ensureOrgPublisherHandleInternal, {
@@ -36,6 +36,17 @@ describe("access.requireUser", () => {
    }
  });

+  it("throws when auth resolves to an invalid user id", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:broken" as never);
+    const dbGet = vi.fn().mockRejectedValue(new Error("Table mismatch"));
+
+    await expect(
+      requireUser({
+        db: { get: dbGet },
+      } as never),
+    ).rejects.toThrow("User not found");
+  });
+
  it("returns auth user when active", async () => {
    vi.mocked(getAuthUserId).mockResolvedValue("users:2" as never);
    const user = { _id: "users:2", role: "user" };
@@ -77,6 +88,17 @@ describe("access.requireUserFromAction", () => {
    }
  });

+  it("throws when action auth resolves to an invalid user id", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:broken" as never);
+    const runQuery = vi.fn().mockRejectedValue(new Error("Table mismatch"));
+
+    await expect(
+      requireUserFromAction({
+        runQuery,
+      } as never),
+    ).rejects.toThrow("User not found");
+  });
+
  it("returns active user from action query", async () => {
    vi.mocked(getAuthUserId).mockResolvedValue("users:9" as never);
    const user = { _id: "users:9", role: "admin" };
@@ -5,10 +5,43 @@ import type { ActionCtx, MutationCtx, QueryCtx } from "../_generated/server";

 export type Role = "admin" | "moderator" | "user";

+export async function getOptionalActiveAuthUserId(
+  ctx: MutationCtx | QueryCtx,
+): Promise<Id<"users"> | undefined> {
+  try {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) return undefined;
+    const user = await ctx.db.get(userId);
+    if (!user || user.deletedAt || user.deactivatedAt) return undefined;
+    return userId;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function getOptionalActiveAuthUserIdFromAction(
+  ctx: ActionCtx,
+): Promise<Id<"users"> | undefined> {
+  try {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) return undefined;
+    const user = await ctx.runQuery(internal.users.getByIdInternal, { userId });
+    if (!user || user.deletedAt || user.deactivatedAt) return undefined;
+    return userId;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function requireUser(ctx: MutationCtx | QueryCtx) {
  const userId = await getAuthUserId(ctx);
  if (!userId) throw new Error("Unauthorized");
-  const user = await ctx.db.get(userId);
+  let user: Doc<"users"> | null;
+  try {
+    user = await ctx.db.get(userId);
+  } catch {
+    throw new Error("User not found");
+  }
  if (!user || user.deletedAt || user.deactivatedAt) throw new Error("User not found");
  return { userId, user };
 }
@@ -18,7 +51,12 @@ export async function requireUserFromAction(
 ): Promise<{ userId: Id<"users">; user: Doc<"users"> }> {
  const userId = await getAuthUserId(ctx);
  if (!userId) throw new Error("Unauthorized");
-  const user = await ctx.runQuery(internal.users.getByIdInternal, { userId });
+  let user: Doc<"users"> | null;
+  try {
+    user = await ctx.runQuery(internal.users.getByIdInternal, { userId });
+  } catch {
+    throw new Error("User not found");
+  }
  if (!user || user.deletedAt || user.deactivatedAt) throw new Error("User not found");
  return { userId, user: user as Doc<"users"> };
 }
@@ -5,6 +5,29 @@ import type { ActionCtx } from "../_generated/server";
 import { hashToken } from "./tokens";

 type TokenAuthResult = { user: Doc<"users">; userId: Doc<"users">["_id"] };
+type ApiTokenDoc = Doc<"apiTokens">;
+type PackagePublishTokenAuthResult = {
+  kind: "github-actions";
+  publishToken: Doc<"packagePublishTokens">;
+};
+type PackagePublishTokenDoc = Doc<"packagePublishTokens">;
+type UserPackagePublishAuthResult = {
+  kind: "user";
+  user: Doc<"users">;
+  userId: Doc<"users">["_id"];
+};
+
+const internalRefs = internal as unknown as {
+  tokens: {
+    getByHashInternal: unknown;
+    getUserForTokenInternal: unknown;
+    touchInternal: unknown;
+  };
+  packagePublishTokens: {
+    getByHashInternal: unknown;
+    touchInternal: unknown;
+  };
+};

 export async function requireApiTokenUser(
  ctx: ActionCtx,
@@ -15,15 +38,26 @@ export async function requireApiTokenUser(
  if (!token) throw new ConvexError("Unauthorized");

  const tokenHash = await hashToken(token);
-  const apiToken = await ctx.runQuery(internal.tokens.getByHashInternal, { tokenHash });
+  const apiToken = (await ctx.runQuery(
+    internalRefs.tokens.getByHashInternal as never,
+    {
+      tokenHash,
+    } as never,
+  )) as ApiTokenDoc | null;
  if (!apiToken || apiToken.revokedAt) throw new ConvexError("Unauthorized");

-  const user = await ctx.runQuery(internal.tokens.getUserForTokenInternal, {
-    tokenId: apiToken._id,
-  });
+  const user = (await ctx.runQuery(
+    internalRefs.tokens.getUserForTokenInternal as never,
+    {
+      tokenId: apiToken._id,
+    } as never,
+  )) as Doc<"users"> | null;
  if (!user || user.deletedAt || user.deactivatedAt) throw new ConvexError("Unauthorized");

-  await ctx.runMutation(internal.tokens.touchInternal, { tokenId: apiToken._id });
+  await ctx.runMutation(
+    internalRefs.tokens.touchInternal as never,
+    { tokenId: apiToken._id } as never,
+  );
  return { user, userId: user._id };
 }

@@ -36,18 +70,55 @@ export async function getOptionalApiTokenUserId(
  if (!token) return null;

  const tokenHash = await hashToken(token);
-  const apiToken = await ctx.runQuery(internal.tokens.getByHashInternal, { tokenHash });
+  const apiToken = (await ctx.runQuery(
+    internalRefs.tokens.getByHashInternal as never,
+    {
+      tokenHash,
+    } as never,
+  )) as ApiTokenDoc | null;
  if (!apiToken || apiToken.revokedAt) return null;

-  const user = await ctx.runQuery(internal.tokens.getUserForTokenInternal, {
-    tokenId: apiToken._id,
-  });
+  const user = (await ctx.runQuery(
+    internalRefs.tokens.getUserForTokenInternal as never,
+    {
+      tokenId: apiToken._id,
+    } as never,
+  )) as Doc<"users"> | null;
  if (!user || user.deletedAt || user.deactivatedAt) return null;

  return user._id;
 }

-function parseBearerToken(header: string | null) {
+export async function requirePackagePublishAuth(
+  ctx: ActionCtx,
+  request: Request,
+): Promise<UserPackagePublishAuthResult | PackagePublishTokenAuthResult> {
+  const header = request.headers.get("authorization") ?? request.headers.get("Authorization");
+  const token = parseBearerToken(header);
+  if (!token) throw new ConvexError("Unauthorized");
+
+  const tokenHash = await hashToken(token);
+  const publishToken = (await ctx.runQuery(
+    internalRefs.packagePublishTokens.getByHashInternal as never,
+    {
+      tokenHash,
+    } as never,
+  )) as PackagePublishTokenDoc | null;
+  if (publishToken && !publishToken.revokedAt && publishToken.expiresAt > Date.now()) {
+    await ctx.runMutation(
+      internalRefs.packagePublishTokens.touchInternal as never,
+      {
+        tokenId: publishToken._id,
+      } as never,
+    );
+    return { kind: "github-actions", publishToken };
+  }
+
+  const auth = await requireApiTokenUser(ctx, request);
+  return { kind: "user", user: auth.user, userId: auth.userId };
+}
+
+export function parseBearerToken(header: string | null) {
  if (!header) return null;
  const trimmed = header.trim();
  if (!trimmed.toLowerCase().startsWith("bearer ")) return null;
@@ -0,0 +1,334 @@
+/* @vitest-environment node */
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  extractWorkflowFilenameFromWorkflowRef,
+  verifyGitHubActionsTrustedPublishJwt,
+  type TrustedGitHubActionsPublisher,
+} from "./githubActionsOidc";
+
+const trustedPublisher: TrustedGitHubActionsPublisher = {
+  repository: "openclaw/openclaw",
+  repositoryId: "123456",
+  repositoryOwner: "openclaw",
+  repositoryOwnerId: "7890",
+  workflowFilename: "plugin-clawhub-release.yml",
+  environment: "clawhub-plugin-release",
+};
+const trustedPublisherWithoutEnvironment: TrustedGitHubActionsPublisher = {
+  ...trustedPublisher,
+  environment: undefined,
+};
+const signingKeyPairPromise = crypto.subtle.generateKey(
+  {
+    name: "RSASSA-PKCS1-v1_5",
+    modulusLength: 2048,
+    publicExponent: new Uint8Array([1, 0, 1]),
+    hash: "SHA-256",
+  },
+  true,
+  ["sign", "verify"],
+);
+
+describe("extractWorkflowFilenameFromWorkflowRef", () => {
+  it("extracts the workflow filename from workflow_ref", () => {
+    expect(
+      extractWorkflowFilenameFromWorkflowRef(
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+        "openclaw/openclaw",
+      ),
+    ).toBe("plugin-clawhub-release.yml");
+  });
+});
+
+describe("verifyGitHubActionsTrustedPublishJwt", () => {
+  it("accepts a valid GitHub Actions token", async () => {
+    const { token, jwks } = await createSignedToken({
+      repository: trustedPublisher.repository,
+      repository_id: trustedPublisher.repositoryId,
+      repository_owner: trustedPublisher.repositoryOwner,
+      repository_owner_id: trustedPublisher.repositoryOwnerId,
+      workflow_ref:
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+      runner_environment: "github-hosted",
+      environment: trustedPublisher.environment,
+      event_name: "workflow_dispatch",
+      workflow: "Plugin ClawHub Release",
+      sha: "deadbeef",
+      ref: "refs/heads/main",
+      ref_type: "branch",
+      actor: "onur",
+      actor_id: "42",
+      run_id: "100",
+      run_attempt: "2",
+      iss: "https://token.actions.githubusercontent.com",
+      aud: "clawhub",
+      exp: Math.floor(Date.now() / 1000) + 300,
+      iat: Math.floor(Date.now() / 1000) - 5,
+    });
+
+    const identity = await verifyGitHubActionsTrustedPublishJwt(token, trustedPublisher, {
+      fetchImpl: async () =>
+        new Response(JSON.stringify({ keys: [jwks] }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+    });
+
+    expect(identity).toMatchObject({
+      repository: trustedPublisher.repository,
+      repositoryId: trustedPublisher.repositoryId,
+      repositoryOwner: trustedPublisher.repositoryOwner,
+      repositoryOwnerId: trustedPublisher.repositoryOwnerId,
+      workflowFilename: trustedPublisher.workflowFilename,
+      environment: trustedPublisher.environment,
+      runId: "100",
+      runAttempt: "2",
+      sha: "deadbeef",
+    });
+  });
+
+  it("accepts a valid GitHub Actions token when no environment is pinned", async () => {
+    const { token, jwks } = await createSignedToken({
+      repository: trustedPublisher.repository,
+      repository_id: trustedPublisher.repositoryId,
+      repository_owner: trustedPublisher.repositoryOwner,
+      repository_owner_id: trustedPublisher.repositoryOwnerId,
+      workflow_ref:
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+      runner_environment: "github-hosted",
+      event_name: "workflow_dispatch",
+      workflow: "Plugin ClawHub Release",
+      sha: "deadbeef",
+      ref: "refs/heads/main",
+      ref_type: "branch",
+      actor: "onur",
+      actor_id: "42",
+      run_id: "100",
+      run_attempt: "2",
+      iss: "https://token.actions.githubusercontent.com",
+      aud: "clawhub",
+      exp: Math.floor(Date.now() / 1000) + 300,
+      iat: Math.floor(Date.now() / 1000) - 5,
+    });
+
+    const identity = await verifyGitHubActionsTrustedPublishJwt(
+      token,
+      trustedPublisherWithoutEnvironment,
+      {
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ keys: [jwks] }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+      },
+    );
+
+    expect(identity).toMatchObject({
+      repository: trustedPublisher.repository,
+      repositoryId: trustedPublisher.repositoryId,
+      repositoryOwner: trustedPublisher.repositoryOwner,
+      repositoryOwnerId: trustedPublisher.repositoryOwnerId,
+      workflowFilename: trustedPublisher.workflowFilename,
+      runId: "100",
+      runAttempt: "2",
+      sha: "deadbeef",
+    });
+    expect(identity.environment).toBeUndefined();
+  });
+
+  it("rejects reusable workflow tokens", async () => {
+    const { token, jwks } = await createSignedToken({
+      repository: trustedPublisher.repository,
+      repository_id: trustedPublisher.repositoryId,
+      repository_owner: trustedPublisher.repositoryOwner,
+      repository_owner_id: trustedPublisher.repositoryOwnerId,
+      workflow_ref:
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+      job_workflow_ref:
+        "openclaw/shared/.github/workflows/reusable-plugin-release.yml@refs/heads/main",
+      runner_environment: "github-hosted",
+      environment: trustedPublisher.environment,
+      event_name: "workflow_dispatch",
+      workflow: "Plugin ClawHub Release",
+      sha: "deadbeef",
+      ref: "refs/heads/main",
+      run_id: "100",
+      run_attempt: "1",
+      iss: "https://token.actions.githubusercontent.com",
+      aud: "clawhub",
+      exp: Math.floor(Date.now() / 1000) + 300,
+      iat: Math.floor(Date.now() / 1000) - 5,
+    });
+
+    await expect(
+      verifyGitHubActionsTrustedPublishJwt(token, trustedPublisher, {
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ keys: [jwks] }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+      }),
+    ).rejects.toThrow("Only the official ClawHub reusable workflow is supported");
+  });
+
+  it("accepts the official ClawHub reusable workflow", async () => {
+    const { token, jwks } = await createSignedToken({
+      repository: trustedPublisher.repository,
+      repository_id: trustedPublisher.repositoryId,
+      repository_owner: trustedPublisher.repositoryOwner,
+      repository_owner_id: trustedPublisher.repositoryOwnerId,
+      workflow_ref:
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+      job_workflow_ref: "openclaw/clawhub/.github/workflows/package-publish.yml@refs/heads/main",
+      runner_environment: "github-hosted",
+      environment: trustedPublisher.environment,
+      event_name: "workflow_dispatch",
+      workflow: "Plugin ClawHub Release",
+      sha: "deadbeef",
+      ref: "refs/heads/main",
+      run_id: "100",
+      run_attempt: "1",
+      iss: "https://token.actions.githubusercontent.com",
+      aud: "clawhub",
+      exp: Math.floor(Date.now() / 1000) + 300,
+      iat: Math.floor(Date.now() / 1000) - 5,
+    });
+
+    await expect(
+      verifyGitHubActionsTrustedPublishJwt(token, trustedPublisher, {
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ keys: [jwks] }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+      }),
+    ).resolves.toMatchObject({
+      repository: trustedPublisher.repository,
+      workflowFilename: trustedPublisher.workflowFilename,
+      jobWorkflowRef: "openclaw/clawhub/.github/workflows/package-publish.yml@refs/heads/main",
+    });
+  });
+
+  it("rejects environment mismatches", async () => {
+    const { token, jwks } = await createSignedToken({
+      repository: trustedPublisher.repository,
+      repository_id: trustedPublisher.repositoryId,
+      repository_owner: trustedPublisher.repositoryOwner,
+      repository_owner_id: trustedPublisher.repositoryOwnerId,
+      workflow_ref:
+        "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+      runner_environment: "github-hosted",
+      environment: "other-environment",
+      event_name: "workflow_dispatch",
+      workflow: "Plugin ClawHub Release",
+      sha: "deadbeef",
+      ref: "refs/heads/main",
+      run_id: "100",
+      run_attempt: "1",
+      iss: "https://token.actions.githubusercontent.com",
+      aud: "clawhub",
+      exp: Math.floor(Date.now() / 1000) + 300,
+      iat: Math.floor(Date.now() / 1000) - 5,
+    });
+
+    await expect(
+      verifyGitHubActionsTrustedPublishJwt(token, trustedPublisher, {
+        fetchImpl: async () =>
+          new Response(JSON.stringify({ keys: [jwks] }), {
+            status: 200,
+            headers: { "Content-Type": "application/json" },
+          }),
+      }),
+    ).rejects.toThrow("GitHub OIDC environment mismatch");
+  });
+
+  it("refreshes JWKS on signing-key cache misses", async () => {
+    const now = Date.now() + 10 * 60_000;
+    const { token, jwks } = await createSignedToken(
+      {
+        repository: trustedPublisher.repository,
+        repository_id: trustedPublisher.repositoryId,
+        repository_owner: trustedPublisher.repositoryOwner,
+        repository_owner_id: trustedPublisher.repositoryOwnerId,
+        workflow_ref:
+          "openclaw/openclaw/.github/workflows/plugin-clawhub-release.yml@refs/heads/main",
+        runner_environment: "github-hosted",
+        environment: trustedPublisher.environment,
+        event_name: "workflow_dispatch",
+        workflow: "Plugin ClawHub Release",
+        sha: "deadbeef",
+        ref: "refs/heads/main",
+        ref_type: "branch",
+        actor: "onur",
+        actor_id: "42",
+        run_id: "100",
+        run_attempt: "2",
+        iss: "https://token.actions.githubusercontent.com",
+        aud: "clawhub",
+        exp: Math.floor(now / 1000) + 300,
+        iat: Math.floor(now / 1000) - 5,
+      },
+      "rotated-key",
+    );
+    const staleJwk = { ...jwks, kid: "stale-key" };
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ keys: [staleJwk] }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      )
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ keys: [jwks] }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+
+    await expect(
+      verifyGitHubActionsTrustedPublishJwt(token, trustedPublisher, {
+        fetchImpl: fetchMock,
+        now: () => now,
+      }),
+    ).resolves.toMatchObject({
+      repository: trustedPublisher.repository,
+      workflowFilename: trustedPublisher.workflowFilename,
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});
+
+async function createSignedToken(payload: Record<string, unknown>, kid = "test-key") {
+  const keyPair = await signingKeyPairPromise;
+  const header = { alg: "RS256", kid, typ: "JWT" };
+  const encodedHeader = base64UrlEncodeJson(header);
+  const encodedPayload = base64UrlEncodeJson(payload);
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signature = new Uint8Array(
+    await crypto.subtle.sign(
+      "RSASSA-PKCS1-v1_5",
+      keyPair.privateKey,
+      new TextEncoder().encode(signingInput),
+    ),
+  );
+  const publicJwk = (await crypto.subtle.exportKey("jwk", keyPair.publicKey)) as JsonWebKey & {
+    kid?: string;
+  };
+  publicJwk.kid = kid;
+  return {
+    token: `${signingInput}.${base64UrlEncodeBytes(signature)}`,
+    jwks: publicJwk,
+  };
+}
+
+function base64UrlEncodeJson(value: unknown) {
+  return base64UrlEncodeBytes(new TextEncoder().encode(JSON.stringify(value)));
+}
+
+function base64UrlEncodeBytes(bytes: Uint8Array) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
@@ -0,0 +1,394 @@
+type JwtHeader = {
+  alg?: unknown;
+  kid?: unknown;
+  typ?: unknown;
+};
+
+type JwtPayload = Record<string, unknown>;
+
+type JwkSet = {
+  keys?: Array<JsonWebKey & { kid?: string; alg?: string; use?: string; kty?: string }>;
+};
+
+export type TrustedGitHubActionsPublisher = {
+  repository: string;
+  repositoryId: string;
+  repositoryOwner: string;
+  repositoryOwnerId: string;
+  workflowFilename: string;
+  environment?: string;
+};
+
+export type VerifiedGitHubActionsIdentity = {
+  repository: string;
+  repositoryId: string;
+  repositoryOwner: string;
+  repositoryOwnerId: string;
+  workflowFilename: string;
+  workflowName: string;
+  workflowRef: string;
+  jobWorkflowRef?: string;
+  environment?: string;
+  runnerEnvironment: string;
+  eventName: string;
+  sha: string;
+  ref: string;
+  refType?: string;
+  actor?: string;
+  actorId?: string;
+  runId: string;
+  runAttempt: string;
+};
+
+type VerifyGitHubActionsOidcOptions = {
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+};
+
+type GitHubRepositoryIdentity = {
+  repository: string;
+  repositoryId: string;
+  repositoryOwner: string;
+  repositoryOwnerId: string;
+};
+
+type ParsedWorkflowRef = {
+  repository: string;
+  workflowFilename: string;
+};
+
+const GITHUB_ACTIONS_ISSUER = "https://token.actions.githubusercontent.com";
+const GITHUB_ACTIONS_JWKS_URL = `${GITHUB_ACTIONS_ISSUER}/.well-known/jwks`;
+const TRUSTED_AUDIENCE = "clawhub";
+const CLOCK_SKEW_MS = 60_000;
+const JWKS_CACHE_TTL_MS = 5 * 60_000;
+const OFFICIAL_REUSABLE_WORKFLOW_REPOSITORY = "openclaw/clawhub";
+const OFFICIAL_REUSABLE_WORKFLOW_FILENAME = "package-publish.yml";
+
+let cachedJwks: { value: JwkSet; fetchedAt: number } | null = null;
+
+export async function verifyGitHubActionsTrustedPublishJwt(
+  jwt: string,
+  trustedPublisher: TrustedGitHubActionsPublisher,
+  options: VerifyGitHubActionsOidcOptions = {},
+): Promise<VerifiedGitHubActionsIdentity> {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const now = (options.now ?? Date.now)();
+  const { signingInput, signature, header, payload } = decodeJwt(jwt);
+
+  if (header.alg !== "RS256") {
+    throw new Error(
+      `Unsupported GitHub OIDC signing algorithm: ${formatClaimValue(header.alg ?? "<missing>")}`,
+    );
+  }
+
+  const keyId = requireString(header.kid, "kid");
+  let jwks = await fetchGitHubActionsJwks(fetchImpl, now);
+  let jwk = jwks.keys?.find((entry) => entry.kid === keyId);
+  if (!jwk) {
+    jwks = await fetchGitHubActionsJwks(fetchImpl, now, true);
+    jwk = jwks.keys?.find((entry) => entry.kid === keyId);
+  }
+  if (!jwk) throw new Error(`Unknown GitHub OIDC signing key: ${keyId}`);
+
+  const key = await crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+  const verified = await crypto.subtle.verify(
+    "RSASSA-PKCS1-v1_5",
+    key,
+    signature,
+    new TextEncoder().encode(signingInput),
+  );
+  if (!verified) throw new Error("Invalid GitHub OIDC signature");
+
+  const issuer = requireString(payload.iss, "iss");
+  if (issuer !== GITHUB_ACTIONS_ISSUER) {
+    throw new Error(`Unexpected GitHub OIDC issuer: ${issuer}`);
+  }
+  if (!claimContainsAudience(payload.aud, TRUSTED_AUDIENCE)) {
+    throw new Error(`Unexpected GitHub OIDC audience: ${formatAudience(payload.aud)}`);
+  }
+  assertTokenTimeWindow(payload, now);
+
+  const repository = requireString(payload.repository, "repository");
+  const repositoryId = requireClaimString(payload.repository_id, "repository_id");
+  const repositoryOwner = requireString(payload.repository_owner, "repository_owner");
+  const repositoryOwnerId = requireClaimString(payload.repository_owner_id, "repository_owner_id");
+  const workflowRef = requireString(payload.workflow_ref, "workflow_ref");
+  const workflow = parseWorkflowRef(workflowRef, repository);
+  const jobWorkflowRef = optionalString(payload.job_workflow_ref);
+  const runnerEnvironment = requireString(payload.runner_environment, "runner_environment");
+  const environment = optionalString(payload.environment);
+  const eventName = requireString(payload.event_name, "event_name");
+  const workflowName = requireString(payload.workflow, "workflow");
+  const sha = requireString(payload.sha, "sha");
+  const ref = requireString(payload.ref, "ref");
+  const runId = requireClaimString(payload.run_id, "run_id");
+  const runAttempt = requireClaimString(payload.run_attempt, "run_attempt");
+  const refType = optionalString(payload.ref_type);
+  const actor = optionalString(payload.actor);
+  const actorId = optionalStringValue(payload.actor_id);
+
+  if (repository !== trustedPublisher.repository) {
+    throw new Error(
+      `GitHub OIDC repository mismatch: expected ${trustedPublisher.repository}, got ${repository}`,
+    );
+  }
+  if (repositoryId !== trustedPublisher.repositoryId) {
+    throw new Error(
+      `GitHub OIDC repository_id mismatch: expected ${trustedPublisher.repositoryId}, got ${repositoryId}`,
+    );
+  }
+  if (repositoryOwner !== trustedPublisher.repositoryOwner) {
+    throw new Error(
+      `GitHub OIDC repository_owner mismatch: expected ${trustedPublisher.repositoryOwner}, got ${repositoryOwner}`,
+    );
+  }
+  if (repositoryOwnerId !== trustedPublisher.repositoryOwnerId) {
+    throw new Error(
+      `GitHub OIDC repository_owner_id mismatch: expected ${trustedPublisher.repositoryOwnerId}, got ${repositoryOwnerId}`,
+    );
+  }
+  if (workflow.workflowFilename !== trustedPublisher.workflowFilename) {
+    throw new Error(
+      `GitHub OIDC workflow mismatch: expected ${trustedPublisher.workflowFilename}, got ${workflow.workflowFilename}`,
+    );
+  }
+  if (jobWorkflowRef) {
+    const reusableWorkflow = parseWorkflowRef(jobWorkflowRef);
+    const usesOfficialReusableWorkflow =
+      reusableWorkflow.repository === OFFICIAL_REUSABLE_WORKFLOW_REPOSITORY &&
+      reusableWorkflow.workflowFilename === OFFICIAL_REUSABLE_WORKFLOW_FILENAME;
+    if (!usesOfficialReusableWorkflow) {
+      throw new Error(
+        "Only the official ClawHub reusable workflow is supported for trusted publishing",
+      );
+    }
+  }
+  if (runnerEnvironment !== "github-hosted") {
+    throw new Error(
+      `Only GitHub-hosted runners may mint trusted publish tokens, got ${runnerEnvironment}`,
+    );
+  }
+  // v1 keeps secretless publishing behind a manual entry point. Environment
+  // pinning is optional, but if configured it must match exactly.
+  if (eventName !== "workflow_dispatch") {
+    throw new Error(`Trusted publishing requires workflow_dispatch, got ${eventName}`);
+  }
+  if (trustedPublisher.environment && environment !== trustedPublisher.environment) {
+    throw new Error(
+      `GitHub OIDC environment mismatch: expected ${trustedPublisher.environment}, got ${formatClaimValue(environment ?? "<missing>")}`,
+    );
+  }
+
+  return {
+    repository,
+    repositoryId,
+    repositoryOwner,
+    repositoryOwnerId,
+    workflowFilename: workflow.workflowFilename,
+    workflowName,
+    workflowRef,
+    ...(jobWorkflowRef ? { jobWorkflowRef } : {}),
+    ...(environment ? { environment } : {}),
+    runnerEnvironment,
+    eventName,
+    sha,
+    ref,
+    ...(refType ? { refType } : {}),
+    ...(actor ? { actor } : {}),
+    ...(actorId ? { actorId } : {}),
+    runId,
+    runAttempt,
+  };
+}
+
+export async function fetchGitHubRepositoryIdentity(
+  repository: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<GitHubRepositoryIdentity> {
+  const normalizedRepository = normalizeGitHubRepository(repository);
+  if (!normalizedRepository) {
+    throw new Error(`Invalid GitHub repository: ${repository}`);
+  }
+  const response = await fetchImpl(`https://api.github.com/repos/${normalizedRepository}`, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "clawhub/package-trusted-publisher",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(
+      `GitHub repository lookup failed for ${normalizedRepository}: ${response.status}`,
+    );
+  }
+  const body = (await response.json()) as {
+    id?: unknown;
+    full_name?: unknown;
+    owner?: { login?: unknown; id?: unknown };
+  };
+  const resolvedRepository = requireString(body.full_name, "full_name");
+  const ownerLogin = requireString(body.owner?.login, "owner.login");
+  return {
+    repository: resolvedRepository,
+    repositoryId: requireClaimString(body.id, "id"),
+    repositoryOwner: ownerLogin,
+    repositoryOwnerId: requireClaimString(body.owner?.id, "owner.id"),
+  };
+}
+
+export function normalizeGitHubRepository(repository: string) {
+  const trimmed = repository
+    .trim()
+    .replace(/^https?:\/\/github\.com\//i, "")
+    .replace(/\.git$/i, "");
+  const match = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(trimmed);
+  if (!match) return null;
+  return `${match[1]}/${match[2]}`;
+}
+
+export function extractWorkflowFilenameFromWorkflowRef(
+  workflowRef: string,
+  expectedRepository?: string,
+) {
+  return parseWorkflowRef(workflowRef, expectedRepository).workflowFilename;
+}
+
+function parseWorkflowRef(workflowRef: string, expectedRepository?: string): ParsedWorkflowRef {
+  const match = /^([^/]+\/[^/]+)\/\.github\/workflows\/([^@/]+)@.+$/.exec(workflowRef.trim());
+  if (!match?.[1] || !match[2]) {
+    throw new Error(`Invalid GitHub workflow_ref claim: ${workflowRef}`);
+  }
+  if (expectedRepository && match[1] !== expectedRepository) {
+    throw new Error(
+      `GitHub workflow_ref repository mismatch: expected ${expectedRepository}, got ${match[1]}`,
+    );
+  }
+  return {
+    repository: match[1],
+    workflowFilename: match[2],
+  };
+}
+
+function decodeJwt(jwt: string) {
+  const parts = jwt.trim().split(".");
+  if (parts.length !== 3) throw new Error("Invalid GitHub OIDC token format");
+  const [encodedHeader, encodedPayload, encodedSignature] = parts;
+  const header = parseJsonSegment<JwtHeader>(encodedHeader, "header");
+  const payload = parseJsonSegment<JwtPayload>(encodedPayload, "payload");
+  return {
+    header,
+    payload,
+    signingInput: `${encodedHeader}.${encodedPayload}`,
+    signature: base64UrlToBytes(encodedSignature),
+  };
+}
+
+function parseJsonSegment<T>(segment: string, label: string) {
+  try {
+    return JSON.parse(new TextDecoder().decode(base64UrlToBytes(segment))) as T;
+  } catch {
+    throw new Error(`Invalid GitHub OIDC ${label}`);
+  }
+}
+
+function base64UrlToBytes(value: string) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+async function fetchGitHubActionsJwks(fetchImpl: typeof fetch, now: number, forceRefresh = false) {
+  if (!forceRefresh && cachedJwks && now - cachedJwks.fetchedAt < JWKS_CACHE_TTL_MS) {
+    return cachedJwks.value;
+  }
+  const response = await fetchImpl(GITHUB_ACTIONS_JWKS_URL, {
+    headers: {
+      Accept: "application/json",
+      "User-Agent": "clawhub/github-actions-oidc",
+    },
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch GitHub OIDC JWKS: ${response.status}`);
+  }
+  const jwks = (await response.json()) as JwkSet;
+  cachedJwks = { value: jwks, fetchedAt: now };
+  return jwks;
+}
+
+function claimContainsAudience(audience: unknown, expected: string) {
+  if (typeof audience === "string") return audience === expected;
+  if (!Array.isArray(audience)) return false;
+  return audience.includes(expected);
+}
+
+function formatAudience(audience: unknown) {
+  if (typeof audience === "string") return audience;
+  if (Array.isArray(audience)) return audience.join(", ");
+  return formatClaimValue(audience ?? "<missing>");
+}
+
+function formatClaimValue(value: unknown) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+function assertTokenTimeWindow(payload: JwtPayload, now: number) {
+  const expiresAt = requireNumericClaim(payload.exp, "exp") * 1000;
+  if (now - CLOCK_SKEW_MS >= expiresAt) {
+    throw new Error("GitHub OIDC token has expired");
+  }
+  const notBefore =
+    payload.nbf === undefined ? undefined : requireNumericClaim(payload.nbf, "nbf") * 1000;
+  if (typeof notBefore === "number" && now + CLOCK_SKEW_MS < notBefore) {
+    throw new Error("GitHub OIDC token is not active yet");
+  }
+}
+
+function requireClaimString(value: unknown, label: string) {
+  const normalized = optionalStringValue(value);
+  if (!normalized) throw new Error(`Missing GitHub OIDC claim: ${label}`);
+  return normalized;
+}
+
+function requireString(value: unknown, label: string) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Missing GitHub OIDC claim: ${label}`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown) {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function optionalStringValue(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return optionalString(value);
+}
+
+function requireNumericClaim(value: unknown, label: string) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  throw new Error(`Missing GitHub OIDC claim: ${label}`);
+}
+
+export const __test = {
+  base64UrlToBytes,
+  claimContainsAudience,
+};
@@ -92,6 +92,173 @@ describe("moderationEngine", () => {
    expect(result.status).toBe("suspicious");
  });

+  it("flags raw user placeholders embedded in generated Python source within markdown", () => {
+    const result = runStaticModerationScan({
+      slug: "word-document-organizer",
+      displayName: "Word Document Organizer",
+      summary: "Organize and restyle Word documents",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 512 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Generate a Python helper like this:",
+            "```python",
+            'doc_path = "${document_path}"',
+            'output_path = "${output_path}" if "${output_path}" else doc_path',
+            'template = "${style_template}"',
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).toContain("suspicious.generated_source_template_injection");
+    expect(result.status).toBe("suspicious");
+  });
+
+  it("does not flag ordinary placeholder usage outside generated source assignments", () => {
+    const result = runStaticModerationScan({
+      slug: "api-docs",
+      displayName: "API Docs",
+      summary: "Shows users how to call an API",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 256 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Use this request template:",
+            "```bash",
+            'curl "https://example.com/search?q=${query}"',
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).not.toContain("suspicious.generated_source_template_injection");
+    expect(result.status).toBe("clean");
+  });
+
+  it("flags hardcoded connection_id UUIDs in markdown examples", () => {
+    const result = runStaticModerationScan({
+      slug: "api-gateway",
+      displayName: "API Gateway",
+      summary: "Route API calls through an authenticated gateway",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 256 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Use this payload:",
+            "```json",
+            '{"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80"}',
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).toContain("suspicious.exposed_resource_identifier");
+    expect(result.status).toBe("suspicious");
+    expect(
+      result.findings.find((finding) => finding.message.includes("connection_id"))?.message,
+    ).toContain("connection_id");
+  });
+
+  it("flags hardcoded Google Sheets spreadsheet IDs in markdown examples", () => {
+    const result = runStaticModerationScan({
+      slug: "api-gateway",
+      displayName: "API Gateway",
+      summary: "Route API calls through an authenticated gateway",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 256 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Call the Sheets bridge like this:",
+            "```python",
+            "req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')",
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).toContain("suspicious.exposed_resource_identifier");
+    expect(result.status).toBe("suspicious");
+    expect(
+      result.findings.find((finding) => finding.message.includes("spreadsheet ID"))?.message,
+    ).toContain("spreadsheet ID");
+  });
+
+  it("does not flag placeholder resource identifiers in markdown examples", () => {
+    const result = runStaticModerationScan({
+      slug: "api-gateway",
+      displayName: "API Gateway",
+      summary: "Route API calls through an authenticated gateway",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 256 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Use placeholders in public docs:",
+            "```json",
+            '{"connection_id": "YOUR_CONNECTION_ID"}',
+            "```",
+            "```python",
+            "req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/YOUR_SPREADSHEET_ID/values/Sheet1!A1:B2')",
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).not.toContain("suspicious.exposed_resource_identifier");
+    expect(result.status).toBe("clean");
+  });
+
+  it("flags a real spreadsheet ID even when a placeholder URL appears first", () => {
+    const result = runStaticModerationScan({
+      slug: "api-gateway",
+      displayName: "API Gateway",
+      summary: "Route API calls through an authenticated gateway",
+      frontmatter: {},
+      metadata: {},
+      files: [{ path: "SKILL.md", size: 512 }],
+      fileContents: [
+        {
+          path: "SKILL.md",
+          content: [
+            "Placeholder example first:",
+            "```python",
+            "req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/YOUR_SPREADSHEET_ID/values/Sheet1!A1:B2')",
+            "```",
+            "Real leaked URL later:",
+            "```python",
+            "req = urllib.request.Request('https://gateway.maton.ai/google-sheets/v4/spreadsheets/122BS1sFN2RKL8AOUQjkLdubzOwgqzPT64KfZ2rvYI4M/values/Sheet1!A1:B2')",
+            "```",
+          ].join("\n"),
+        },
+      ],
+    });
+
+    expect(result.reasonCodes).toContain("suspicious.exposed_resource_identifier");
+    expect(
+      result.findings.find((finding) => finding.message.includes("spreadsheet ID"))?.line,
+    ).toBe(7);
+  });
+
  it("blocks obfuscated terminal install payload prompts in markdown", () => {
    const result = runStaticModerationScan({
      slug: "evil-installer",
@@ -50,6 +50,14 @@ const CODE_EXTENSION = /\.(js|ts|mjs|cjs|mts|cts|jsx|tsx|py|sh|bash|zsh|rb|go)$/
 const STANDARD_PORTS = new Set([80, 443, 8080, 8443, 3000]);
 const RAW_IP_URL_PATTERN = /https?:\/\/\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?(?:\/|["'])/i;
 const INSTALL_PACKAGE_PATTERN = /installer-package\s*:\s*https?:\/\/[^\s"'`]+/i;
+const GENERATED_SOURCE_PLACEHOLDER_PATTERN =
+  /^\s*[A-Za-z_][A-Za-z0-9_]*\s*=.*["']\$\{[A-Za-z_][A-Za-z0-9_-]*\}["']/m;
+const GENERATED_SOURCE_CONTEXT_PATTERN =
+  /```(?:python|py|javascript|js|typescript|ts|shell|bash|sh)\b|cat\s*(?:>|>>)?\s*[^`\n]*\.(?:py|js|ts|sh)\b|python3?\b|node\b/i;
+const HARDCODED_CONNECTION_ID_PATTERN =
+  /["']connection_id["']\s*:\s*["'][0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}["']/i;
+const GOOGLE_SHEETS_SPREADSHEET_URL_PATTERN =
+  /https?:\/\/[^\s"'`]*\/spreadsheets\/([A-Za-z0-9_-]{20,})\/[^\s"'`]*/i;

 function hasMaliciousInstallPrompt(content: string) {
  const hasTerminalInstruction =
@@ -75,6 +83,10 @@ function truncateEvidence(evidence: string, maxLen = 160) {
  return `${evidence.slice(0, maxLen)}...`;
 }

+function looksLikePlaceholderIdentifier(identifier: string) {
+  return /^[A-Z0-9_]+$/.test(identifier) || /(your|example|placeholder)/i.test(identifier);
+}
+
 function addFinding(
  findings: ModerationFinding[],
  finding: Omit<ModerationFinding, "evidence"> & { evidence: string },
@@ -92,6 +104,14 @@ function findFirstLine(content: string, pattern: RegExp) {
  return { line: 1, text: lines[0] ?? "" };
 }

+function findLineAtIndex(content: string, index: number) {
+  const line = content.slice(0, index).split("\n").length;
+  const lineStart = content.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+  const nextNewline = content.indexOf("\n", index);
+  const lineEnd = nextNewline === -1 ? content.length : nextNewline;
+  return { line, text: content.slice(lineStart, lineEnd) };
+}
+
 function scanCodeFile(path: string, content: string, findings: ModerationFinding[]) {
  if (!CODE_EXTENSION.test(path)) return;

@@ -227,6 +247,53 @@ function scanMarkdownFile(path: string, content: string, findings: ModerationFin
      evidence: match.text,
    });
  }
+
+  if (
+    GENERATED_SOURCE_PLACEHOLDER_PATTERN.test(content) &&
+    GENERATED_SOURCE_CONTEXT_PATTERN.test(content)
+  ) {
+    const match = findFirstLine(content, GENERATED_SOURCE_PLACEHOLDER_PATTERN);
+    addFinding(findings, {
+      code: REASON_CODES.GENERATED_SOURCE_TEMPLATE,
+      severity: "critical",
+      file: path,
+      line: match.line,
+      message: "User-controlled placeholder is embedded directly into generated source code.",
+      evidence: match.text,
+    });
+  }
+
+  if (HARDCODED_CONNECTION_ID_PATTERN.test(content)) {
+    const match = findFirstLine(content, HARDCODED_CONNECTION_ID_PATTERN);
+    addFinding(findings, {
+      code: REASON_CODES.EXPOSED_RESOURCE_IDENTIFIER,
+      severity: "critical",
+      file: path,
+      line: match.line,
+      message: "Example code exposes a concrete connection_id instead of a placeholder.",
+      evidence: match.text,
+    });
+  }
+
+  const spreadsheetUrlPattern = new RegExp(
+    GOOGLE_SHEETS_SPREADSHEET_URL_PATTERN.source,
+    `${GOOGLE_SHEETS_SPREADSHEET_URL_PATTERN.flags.replaceAll("g", "")}g`,
+  );
+  for (const spreadsheetUrlMatch of content.matchAll(spreadsheetUrlPattern)) {
+    const spreadsheetId = spreadsheetUrlMatch[1];
+    if (!spreadsheetId || looksLikePlaceholderIdentifier(spreadsheetId)) continue;
+
+    const match = findLineAtIndex(content, spreadsheetUrlMatch.index ?? 0);
+    addFinding(findings, {
+      code: REASON_CODES.EXPOSED_RESOURCE_IDENTIFIER,
+      severity: "critical",
+      file: path,
+      line: match.line,
+      message: "Example code exposes a concrete Google Sheets spreadsheet ID instead of a placeholder.",
+      evidence: match.text,
+    });
+    break;
+  }
 }

 function scanManifestFile(path: string, content: string, findings: ModerationFinding[]) {
@@ -12,11 +12,13 @@ export type ModerationFinding = {
  evidence: string;
 };

-export const MODERATION_ENGINE_VERSION = "v2.2.0";
+export const MODERATION_ENGINE_VERSION = "v2.4.0";

 export const REASON_CODES = {
  DANGEROUS_EXEC: "suspicious.dangerous_exec",
  DYNAMIC_CODE: "suspicious.dynamic_code_execution",
+  GENERATED_SOURCE_TEMPLATE: "suspicious.generated_source_template_injection",
+  EXPOSED_RESOURCE_IDENTIFIER: "suspicious.exposed_resource_identifier",
  CREDENTIAL_HARVEST: "suspicious.env_credential_access",
  EXFILTRATION: "suspicious.potential_exfiltration",
  OBFUSCATED_CODE: "suspicious.obfuscated_code",
@@ -139,9 +139,9 @@ describe("packageRegistry", () => {

  it("validates package name consistency and summary extraction", () => {
    ensurePluginNameMatchesPackage("demo-plugin", { name: "demo-plugin" });
-    expect(() =>
-      ensurePluginNameMatchesPackage("demo-plugin", { name: "other-plugin" }),
-    ).toThrow("must match published package name");
+    expect(() => ensurePluginNameMatchesPackage("demo-plugin", { name: "other-plugin" })).toThrow(
+      "must match published package name",
+    );

    expect(
      summarizePackageForSearch({
@@ -1,3 +1,7 @@
+import {
+  listMissingOpenClawExternalCodePluginFieldPaths,
+  normalizeOpenClawExternalPluginCompatibility,
+} from "clawhub-schema";
 import type {
  BundlePublishMetadata,
  PackageCapabilitySummary,
@@ -84,7 +88,10 @@ export function normalizePublishFiles(files: PublishFile[]) {
  return normalized.map((file) => ({ ...file, path: file.path as string }));
 }

-export function assertPackageVersion(family: "code-plugin" | "bundle-plugin" | "skill", version: string) {
+export function assertPackageVersion(
+  family: "code-plugin" | "bundle-plugin" | "skill",
+  version: string,
+) {
  const trimmed = version.trim();
  if (!trimmed) throw new ConvexError("Version required");
  if (family === "code-plugin" && !semver.valid(trimmed)) {
@@ -125,9 +132,15 @@ function parseJsonFile(text: string, label: string): JsonRecord {
  }
 }

-function deriveSummary(params: { packageName: string; packageJson?: JsonRecord; readmeText?: string | null }) {
+function deriveSummary(params: {
+  packageName: string;
+  packageJson?: JsonRecord;
+  readmeText?: string | null;
+}) {
  const directDescription =
-    typeof params.packageJson?.description === "string" ? params.packageJson.description.trim() : "";
+    typeof params.packageJson?.description === "string"
+      ? params.packageJson.description.trim()
+      : "";
  if (directDescription) return directDescription;
  const readme = params.readmeText?.trim() ?? "";
  if (!readme) return params.packageName;
@@ -165,41 +178,10 @@ function buildVerification(source: SourceInfo | undefined): PackageVerificationS
  };
 }

-function extractOpenClawBlock(packageJson: JsonRecord | undefined) {
-  if (!packageJson) return {};
-  const openclaw = isRecord(packageJson.openclaw) ? packageJson.openclaw : undefined;
-  return {
-    openclaw,
-    compat: isRecord(openclaw?.compat) ? openclaw.compat : undefined,
-    build: isRecord(openclaw?.build) ? openclaw.build : undefined,
-  };
-}
-
-function extractCompatibility(packageJson: JsonRecord | undefined): PackageCompatibility | undefined {
-  const { openclaw, compat, build } = extractOpenClawBlock(packageJson);
-  const install = isRecord(openclaw?.install) ? openclaw.install : undefined;
-  const version =
-    typeof packageJson?.version === "string" ? packageJson.version.trim() : undefined;
-  const minHostVersion =
-    typeof install?.minHostVersion === "string" ? install.minHostVersion.trim() : undefined;
-  const compatibility: PackageCompatibility = {};
-  if (typeof compat?.pluginApi === "string") {
-    compatibility.pluginApiRange = compat.pluginApi.trim();
-  }
-  if (typeof compat?.minGatewayVersion === "string") {
-    compatibility.minGatewayVersion = compat.minGatewayVersion.trim();
-  } else if (minHostVersion) {
-    compatibility.minGatewayVersion = minHostVersion;
-  }
-  if (typeof build?.openclawVersion === "string") {
-    compatibility.builtWithOpenClawVersion = build.openclawVersion.trim();
-  } else if (version) {
-    compatibility.builtWithOpenClawVersion = version;
-  }
-  if (typeof build?.pluginSdkVersion === "string") {
-    compatibility.pluginSdkVersion = build.pluginSdkVersion.trim();
-  }
-  return Object.keys(compatibility).length > 0 ? compatibility : undefined;
+function extractCompatibility(
+  packageJson: JsonRecord | undefined,
+): PackageCompatibility | undefined {
+  return normalizeOpenClawExternalPluginCompatibility(packageJson);
 }

 export function extractCodePluginArtifacts(params: {
@@ -212,7 +194,7 @@ export function extractCodePluginArtifacts(params: {
    throw new ConvexError("Code plugins must include source repo and commit metadata");
  }

-  const { openclaw } = extractOpenClawBlock(params.packageJson);
+  const openclaw = isRecord(params.packageJson.openclaw) ? params.packageJson.openclaw : undefined;
  const extensions = normalizeStringList(openclaw?.extensions);
  if (extensions.length === 0) {
    throw new ConvexError("package.json must declare openclaw.extensions");
@@ -223,11 +205,9 @@ export function extractCodePluginArtifacts(params: {
  if (!runtimeId) throw new ConvexError("openclaw.plugin.json must declare an id");

  const compatibility = extractCompatibility(params.packageJson);
-  if (!compatibility?.pluginApiRange) {
-    throw new ConvexError("package.json openclaw.compat.pluginApi is required");
-  }
-  if (!compatibility.builtWithOpenClawVersion) {
-    throw new ConvexError("package.json openclaw.build.openclawVersion is required");
+  const missingOpenClawFields = listMissingOpenClawExternalCodePluginFieldPaths(params.packageJson);
+  if (missingOpenClawFields.length > 0) {
+    throw new ConvexError(`package.json ${missingOpenClawFields[0]} is required`);
  }

  const channels = uniq([
@@ -269,7 +249,9 @@ export function extractCodePluginArtifacts(params: {
    executesCode: true,
    runtimeId,
    pluginKind:
-      typeof params.pluginManifest.kind === "string" ? params.pluginManifest.kind.trim() : undefined,
+      typeof params.pluginManifest.kind === "string"
+        ? params.pluginManifest.kind.trim()
+        : undefined,
    channels,
    providers,
    hooks,
@@ -311,7 +293,7 @@ export function extractBundlePluginArtifacts(params: {
  bundleMetadata?: BundlePublishMetadata;
  source?: SourceInfo;
 }) {
-  const { openclaw } = extractOpenClawBlock(params.packageJson);
+  const openclaw = isRecord(params.packageJson?.openclaw) ? params.packageJson.openclaw : undefined;
  const manifest = params.bundleManifest;
  const runtimeId =
    (typeof manifest?.id === "string" && manifest.id.trim()) ||
@@ -365,7 +347,9 @@ export function ensurePluginNameMatchesPackage(packageName: string, packageJson:
  const normalizedDeclared = normalizePackageName(declaredName);
  const normalizedExpected = normalizePackageName(packageName);
  if (normalizedDeclared !== normalizedExpected) {
-    throw new ConvexError(`package.json name must match published package name (${normalizedExpected})`);
+    throw new ConvexError(
+      `package.json name must match published package name (${normalizedExpected})`,
+    );
  }
 }

@@ -5,6 +5,8 @@ function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys
  return Object.fromEntries(keys.map((key) => [key, obj[key]])) as Pick<T, K>;
 }

+type SharedPackageKey = Extract<keyof Doc<"packages">, keyof Doc<"packageSearchDigest">>;
+
 const SHARED_KEYS = [
  "name",
  "normalizedName",
@@ -22,7 +24,7 @@ const SHARED_KEYS = [
  "softDeletedAt",
  "createdAt",
  "updatedAt",
-] as const satisfies readonly (keyof Doc<"packages"> & keyof Doc<"packageSearchDigest">)[];
+] as const satisfies readonly SharedPackageKey[];

 const CAPABILITY_SHARED_KEYS = [
  "packageId",
@@ -145,10 +147,7 @@ export async function deletePackageSearchDigests(
 function hasDigestChanged<
  TExisting extends Record<string, unknown>,
  TFields extends Record<string, unknown>,
->(
-  existing: TExisting,
-  fields: TFields,
-): boolean {
+>(existing: TExisting, fields: TFields): boolean {
  for (const key of Object.keys(fields)) {
    const oldValue = (existing as Record<string, unknown>)[key];
    const newValue = (fields as Record<string, unknown>)[key];
@@ -38,4 +38,13 @@ describe("packageSecurity", () => {
      }),
    );
  });
+
+  it("treats suspicious static scans as suspicious even when verification is clean", () => {
+    expect(
+      resolvePackageReleaseScanStatus({
+        staticScan: { status: "suspicious" },
+        verification: { scanStatus: "clean" },
+      } as never),
+    ).toBe("suspicious");
+  });
 });
@@ -25,12 +25,15 @@ export function resolvePackageReleaseScanStatus(
 ): Exclude<PackageScanStatus, undefined> {
  const staticStatus = normalizePackageScanStatus(release.staticScan?.status);
  if (staticStatus === "malicious") return "malicious";
+  if (staticStatus === "suspicious") return "suspicious";

  const vtStatus = normalizePackageScanStatus(release.vtAnalysis?.status);
  if (vtStatus === "malicious") return "malicious";
+  if (vtStatus === "suspicious") return "suspicious";

  const verificationStatus = normalizePackageScanStatus(release.verification?.scanStatus);
  if (verificationStatus === "malicious") return "malicious";
+  if (verificationStatus === "suspicious") return "suspicious";

  if (vtStatus) return vtStatus;
  if (verificationStatus && verificationStatus !== "not-run") return verificationStatus;
@@ -49,7 +52,8 @@ export function getPackageDownloadSecurityBlock(release: PackageReleaseSecurityL
  if (scanStatus === "malicious") {
    return {
      status: 403,
-      message: "Blocked: this package release has been flagged as malicious and cannot be downloaded.",
+      message:
+        "Blocked: this package release has been flagged as malicious and cannot be downloaded.",
    };
  }

@@ -24,6 +24,7 @@ export type PublicSkill = Pick<
  | "forkOf"
  | "latestVersionId"
  | "tags"
+  | "capabilityTags"
  | "badges"
  | "stats"
  | "createdAt"
@@ -50,6 +51,7 @@ export type HydratableSkill = Pick<
  | "latestVersionId"
  | "latestVersionSummary"
  | "tags"
+  | "capabilityTags"
  | "badges"
  | "stats"
  | "statsDownloads"
@@ -141,6 +143,7 @@ export function toPublicSkill(skill: HydratableSkill | null | undefined): Public
    forkOf: skill.forkOf,
    latestVersionId: skill.latestVersionId,
    tags: skill.tags,
+    capabilityTags: skill.capabilityTags,
    badges: skill.badges,
    stats,
    createdAt: skill.createdAt,
@@ -18,8 +18,7 @@ function derivePersonalPublisherHandle(user: Doc<"users">) {
  const emailLocalPart = user.email?.split("@")[0];
  const userIdSuffix = String(user._id).split(":").pop();
  return (
-    normalizePublisherHandle(user.handle ?? user.name ?? emailLocalPart ?? userIdSuffix) ??
-    "user"
+    normalizePublisherHandle(user.handle ?? user.name ?? emailLocalPart ?? userIdSuffix) ?? "user"
  );
 }

@@ -27,7 +26,8 @@ function synthesizePersonalPublisher(user: Doc<"users">): Doc<"publishers"> {
  const handle = derivePersonalPublisherHandle(user);
  const now = user.updatedAt ?? user.createdAt ?? user._creationTime;
  return {
-    _id: (user.personalPublisherId ?? (`publishers:${handle}` as Id<"publishers">)) as Id<"publishers">,
+    _id: (user.personalPublisherId ??
+      (`publishers:${handle}` as Id<"publishers">)) as Id<"publishers">,
    _creationTime: user._creationTime,
    kind: "user",
    handle,
@@ -43,10 +43,7 @@ function synthesizePersonalPublisher(user: Doc<"users">): Doc<"publishers"> {
  };
 }

-export async function getPersonalPublisherForUserOrFallback(
-  ctx: DbCtx,
-  user: Doc<"users">,
-) {
+export async function getPersonalPublisherForUserOrFallback(ctx: DbCtx, user: Doc<"users">) {
  if (user.personalPublisherId) {
    const publisher = await ctx.db.get(user.personalPublisherId);
    if (isPublisherActive(publisher)) return publisher;
@@ -80,10 +77,7 @@ export function isPublisherRoleAllowed(role: PublisherRole, allowed: PublisherRo
  return allowed.some((candidate) => ranks[role] >= ranks[candidate]);
 }

-export async function getPublisherByHandle(
-  ctx: DbCtx,
-  handle: string | undefined | null,
-) {
+export async function getPublisherByHandle(ctx: DbCtx, handle: string | undefined | null) {
  const normalized = normalizePublisherHandle(handle);
  if (!normalized) return null;
  try {
@@ -111,7 +105,12 @@ export async function getUserByHandleOrPersonalPublisher(
  if (user) return user;

  const publisher = await getPublisherByHandle(ctx, normalized);
-  if (!publisher || !isPublisherActive(publisher) || publisher.kind !== "user" || !publisher.linkedUserId) {
+  if (
+    !publisher ||
+    !isPublisherActive(publisher) ||
+    publisher.kind !== "user" ||
+    !publisher.linkedUserId
+  ) {
    return null;
  }

@@ -127,10 +126,7 @@ export async function getActiveUserByHandleOrPersonalPublisher(
  return user;
 }

-export async function getPersonalPublisherForUser(
-  ctx: DbCtx,
-  userId: Id<"users">,
-) {
+export async function getPersonalPublisherForUser(ctx: DbCtx, userId: Id<"users">) {
  try {
    return await ctx.db
      .query("publishers")
@@ -149,10 +145,9 @@ export async function ensurePersonalPublisherForUser(
  const handle = derivePersonalPublisherHandle(user);
  let existing: Doc<"publishers"> | null = null;
  try {
-    existing =
-      user.personalPublisherId
-        ? await ctx.db.get(user.personalPublisherId)
-        : await getPersonalPublisherForUser(ctx, user._id);
+    existing = user.personalPublisherId
+      ? await ctx.db.get(user.personalPublisherId)
+      : await getPersonalPublisherForUser(ctx, user._id);
  } catch (error) {
    if (!isMissingPublisherTableError(error)) throw error;
    return synthesizePersonalPublisher(user);
@@ -240,7 +235,9 @@ export async function ensurePersonalPublisherForUser(

    const existingMember = await ctx.db
      .query("publisherMembers")
-      .withIndex("by_publisher_user", (q) => q.eq("publisherId", publisherId).eq("userId", user._id))
+      .withIndex("by_publisher_user", (q) =>
+        q.eq("publisherId", publisherId).eq("userId", user._id),
+      )
      .unique();
    if (!existingMember) {
      await ctx.db.insert("publisherMembers", {
@@ -47,4 +47,55 @@ describe("searchText", () => {
  it("normalize uses lowercase", () => {
    expect(__test.normalize("AbC")).toBe("abc");
  });
+
+  // CJK (Chinese, Japanese, Korean) support tests
+  describe("CJK tokenization", () => {
+    it("tokenizes Chinese text using Intl.Segmenter", () => {
+      const tokens = tokenize("中文搜索");
+      expect(tokens.length).toBeGreaterThan(0);
+      expect(tokens).toContain("中文");
+      expect(tokens).toContain("搜索");
+    });
+
+    it("tokenizes mixed Chinese and English text", () => {
+      const tokens = tokenize("React 组件开发");
+      expect(tokens).toContain("react");
+      expect(tokens.some((t) => t.includes("组") || t.includes("件"))).toBe(true);
+    });
+
+    it("matches Chinese query tokens against Chinese skill names", () => {
+      const queryTokens = tokenize("翻译");
+      const skillName = "AI翻译助手";
+      expect(matchesExactTokens(queryTokens, [skillName])).toBe(true);
+    });
+
+    it("matches partial Chinese words", () => {
+      const queryTokens = tokenize("助手");
+      const skillName = "AI翻译助手";
+      expect(matchesExactTokens(queryTokens, [skillName])).toBe(true);
+    });
+
+    it("handles Japanese text", () => {
+      const tokens = tokenize("こんにちは世界");
+      expect(tokens.length).toBeGreaterThan(0);
+    });
+
+    it("handles Korean text", () => {
+      const tokens = tokenize("안녕하세요");
+      expect(tokens.length).toBeGreaterThan(0);
+    });
+
+    it("returns empty array for empty or whitespace-only input", () => {
+      expect(tokenize("")).toEqual([]);
+      expect(tokenize("   ")).toEqual([]);
+      expect(tokenize("!!!")).toEqual([]);
+    });
+
+    it("detects CJK language correctly", () => {
+      expect(__test.detectCJKLanguage("中文")).toBe("zh");
+      expect(__test.detectCJKLanguage("こんにちは")).toBe("ja");
+      expect(__test.detectCJKLanguage("안녕하세요")).toBe("ko");
+      expect(__test.detectCJKLanguage("hello")).toBeNull();
+    });
+  });
 });
@@ -1,12 +1,135 @@
-const WORD_RE = /[a-z0-9]+/g;
+const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf\u3041-\u3096\u30a1-\u30fa\uac00-\ud7af]/;
+
+const hasSegmenter = typeof Intl !== "undefined" && "Segmenter" in Intl;
+
+let zhSegmenter: Intl.Segmenter | null = null;
+let jaSegmenter: Intl.Segmenter | null = null;
+let koSegmenter: Intl.Segmenter | null = null;
+
+function getZhSegmenter(): Intl.Segmenter {
+  if (!zhSegmenter) {
+    zhSegmenter = new Intl.Segmenter("zh-CN", { granularity: "word" });
+  }
+  return zhSegmenter;
+}
+
+function getJaSegmenter(): Intl.Segmenter {
+  if (!jaSegmenter) {
+    jaSegmenter = new Intl.Segmenter("ja", { granularity: "word" });
+  }
+  return jaSegmenter;
+}
+
+function getKoSegmenter(): Intl.Segmenter {
+  if (!koSegmenter) {
+    koSegmenter = new Intl.Segmenter("ko", { granularity: "word" });
+  }
+  return koSegmenter;
+}
+
+/**
+ * Fallback: split CJK text into individual characters.
+ * Used when Intl.Segmenter is unavailable (e.g. stripped V8 runtime).
+ */
+function segmentCJKByChar(text: string): string[] {
+  const tokens: string[] = [];
+  for (const ch of text) {
+    if (CJK_RE.test(ch)) {
+      tokens.push(ch);
+    }
+  }
+  return tokens;
+}

 function normalize(value: string) {
  return value.toLowerCase();
 }

+/**
+ * Detect the primary CJK language in a text
+ * Returns 'zh' for Chinese, 'ja' for Japanese, 'ko' for Korean, or null
+ */
+function detectCJKLanguage(text: string): "zh" | "ja" | "ko" | null {
+  const chineseCount = (text.match(/[\u4e00-\u9fff\u3400-\u4dbf]/g) || []).length;
+  const hiraganaCount = (text.match(/[\u3040-\u309f]/g) || []).length;
+  const katakanaCount = (text.match(/[\u30a0-\u30ff]/g) || []).length;
+  const hangulCount = (text.match(/[\uac00-\ud7af]/g) || []).length;
+  if (hiraganaCount + katakanaCount > 0) {
+    return "ja";
+  }
+  if (hangulCount > 0) {
+    return "ko";
+  }
+  if (chineseCount > 0) {
+    return "zh";
+  }
+  return null;
+}
+
+/**
+ * Segment CJK text using Intl.Segmenter, falling back to character-level
+ * tokenization when the API is unavailable.
+ */
+function segmentCJK(text: string): string[] {
+  if (!hasSegmenter) return segmentCJKByChar(text);
+
+  const lang = detectCJKLanguage(text);
+  if (!lang) return [];
+
+  let segmenter: Intl.Segmenter;
+  switch (lang) {
+    case "ja":
+      segmenter = getJaSegmenter();
+      break;
+    case "ko":
+      segmenter = getKoSegmenter();
+      break;
+    default:
+      segmenter = getZhSegmenter();
+  }
+
+  const segments: string[] = [];
+  for (const { segment, isWordLike } of segmenter.segment(text)) {
+    const trimmed = segment.trim();
+    if (trimmed && isWordLike) {
+      segments.push(trimmed);
+    }
+  }
+  return segments;
+}
+
+/**
+ * Tokenize text for search, supporting both English and CJK languages
+ *
+ * For English: uses word boundaries (whitespace, punctuation)
+ * For CJK: uses Intl.Segmenter for proper word segmentation
+ */
 export function tokenize(value: string): string[] {
  if (!value) return [];
-  return normalize(value).match(WORD_RE) ?? [];
+
+  const normalized = normalize(value);
+
+  if (!CJK_RE.test(normalized)) {
+    return normalized.match(/[a-z0-9]+/g) ?? [];
+  }
+
+  const tokens: string[] = [];
+
+  const parts = normalized.split(/([^\u4e00-\u9fff\u3400-\u4dbf\u3041-\u3096\u30a1-\u30fa\uac00-\ud7af]+)/g);
+
+  for (const part of parts) {
+    if (!part.trim()) continue;
+
+    if (CJK_RE.test(part)) {
+      const cjkTokens = segmentCJK(part);
+      tokens.push(...cjkTokens);
+    } else {
+      const asciiTokens = part.match(/[a-z0-9]+/g) ?? [];
+      tokens.push(...asciiTokens);
+    }
+  }
+
+  return tokens;
 }

 export function matchesExactTokens(
@@ -24,4 +147,8 @@ export function matchesExactTokens(
  );
 }

-export const __test = { normalize, tokenize, matchesExactTokens };
+export const __test = {
+  normalize,
+  detectCJKLanguage,
+  segmentCJKByChar,
+};
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { deriveSkillCapabilityTags } from "./skillCapabilityTags";
+
+describe("deriveSkillCapabilityTags", () => {
+  it("detects wallet, payment, and transaction authority from crypto skills", () => {
+    const tags = deriveSkillCapabilityTags({
+      slug: "paytoll",
+      displayName: "PayToll",
+      summary: "DeFi tools paid with x402 micro-payments.",
+      frontmatter: {
+        "requires.env": ["PRIVATE_KEY"],
+      },
+      readmeText:
+        "Payment is the auth. Each tool call costs USDC. The wallet private key signs EIP-712 payment authorizations.",
+      fileContents: [
+        {
+          path: "src/executor.ts",
+          content:
+            "walletClient.sendTransaction({}); if (result.type === 'approval_required') { log('Sending approval transaction...'); }",
+        },
+      ],
+    });
+
+    expect(tags).toEqual([
+      "crypto",
+      "requires-wallet",
+      "can-make-purchases",
+      "can-sign-transactions",
+      "requires-sensitive-credentials",
+    ]);
+  });
+
+  it("detects OAuth-backed external posting behavior", () => {
+    const tags = deriveSkillCapabilityTags({
+      slug: "social-poster",
+      displayName: "Social Poster",
+      frontmatter: {},
+      readmeText:
+        "Post a tweet for the user. Requires an OAuth 2.0 access token with tweet.write scope.",
+      fileContents: [],
+    });
+
+    expect(tags).toEqual([
+      "requires-oauth-token",
+      "requires-sensitive-credentials",
+      "posts-externally",
+    ]);
+  });
+
+  it("detects non-oauth API key skills that still need sensitive credentials", () => {
+    const tags = deriveSkillCapabilityTags({
+      slug: "minimax-usage",
+      displayName: "Minimax Usage",
+      frontmatter: {},
+      readmeText:
+        "Create a .env file with MINIMAX_CODING_API_KEY and MINIMAX_GROUP_ID, then send an authorization: Bearer header to the MiniMax endpoint.",
+      fileContents: [],
+    });
+
+    expect(tags).toEqual(["requires-sensitive-credentials"]);
+  });
+
+  it("does not treat generic broadcast wording as a crypto transaction signal", () => {
+    const tags = deriveSkillCapabilityTags({
+      slug: "notify-bot",
+      displayName: "Notify Bot",
+      frontmatter: {},
+      readmeText: "Broadcast notifications to Slack and email when incidents are opened.",
+      fileContents: [],
+    });
+
+    expect(tags).toEqual([]);
+  });
+});
@@ -0,0 +1,168 @@
+export const SKILL_CAPABILITY_TAGS = [
+  "crypto",
+  "requires-wallet",
+  "can-make-purchases",
+  "can-sign-transactions",
+  "requires-oauth-token",
+  "requires-sensitive-credentials",
+  "posts-externally",
+] as const;
+
+export type SkillCapabilityTag = (typeof SKILL_CAPABILITY_TAGS)[number];
+
+function safeJson(value: unknown) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "";
+  }
+}
+
+function normalizeText(parts: Array<string | undefined>) {
+  return parts
+    .filter((part): part is string => typeof part === "string" && part.trim().length > 0)
+    .join("\n")
+    .toLowerCase();
+}
+
+function matches(text: string, patterns: RegExp[]) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+const CRYPTO_PATTERNS = [
+  /\bcrypto\b/,
+  /\bblockchain\b/,
+  /\bdefi\b/,
+  /\bon-?chain\b/,
+  /\bwallet\b/,
+  /\bprivate key\b/,
+  /\berc20\b/,
+  /\busdc\b/,
+  /\beth(?:ereum)?\b/,
+  /\bbase network\b/,
+  /\barbitrum\b/,
+  /\boptimism\b/,
+  /\bpolygon\b/,
+  /\bavalanche\b/,
+  /\bsolana\b/,
+  /\baave\b/,
+  /\btoken balance\b/,
+  /\bswap\b/,
+  /\bbridge\b/,
+  /\bliquidity\b/,
+  /\bens\b/,
+  /\bx402\b/,
+] satisfies RegExp[];
+
+const WALLET_PATTERNS = [
+  /\bprivate[_ -]?key\b/,
+  /\bwallet\b/,
+  /\bmnemonic\b/,
+  /\bseed phrase\b/,
+  /\bconfigured wallet\b/,
+  /\bsigner\b/,
+  /\beip-712\b/,
+] satisfies RegExp[];
+
+const PURCHASE_PATTERNS = [
+  /\bpay(?:ment|ments)?\b/,
+  /\bpaid automatically\b/,
+  /\bpay per call\b/,
+  /\bmicro-?payments?\b/,
+  /\bpayment required\b/,
+  /\bcosts? \$\d/,
+  /\bcharged?\b/,
+  /\bpurchase\b/,
+  /\bbuy(?:\s+(?:credits?|tokens?|coins?|nft|subscription|plan))\b/,
+  /\bpayment checkout\b/,
+  /\bone-?click checkout\b/,
+] satisfies RegExp[];
+
+const TRANSACTION_PATTERNS = [
+  /\bsign(?:ing)? (?:and )?(?:submit|send|broadcast)? ?transactions?\b/,
+  /\bsendtransaction\b/,
+  /\bapproval_required\b/,
+  /\bon-?chain (?:tx|transaction)\b/,
+  /\bexecute(?:s|d)? transaction\b/,
+  /\bbroadcast (?:transaction|tx)\b/,
+  /\btransaction broadcast\b/,
+  /\bwalletclient\.sendtransaction\b/,
+] satisfies RegExp[];
+
+const OAUTH_PATTERNS = [
+  /\boauth(?: 2\.0)?\b/,
+  /\baccess token\b/,
+  /\brefresh token\b/,
+  /\bbearer token\b/,
+  /\btweet\.write\b/,
+] satisfies RegExp[];
+
+const SENSITIVE_CREDENTIAL_PATTERNS = [
+  /api[_ -]?key\b/,
+  /\baccess token\b/,
+  /\brefresh token\b/,
+  /\bbearer token\b/,
+  /\bsession (?:cookie|cookies)\b/,
+  /\bauth(?:entication)? (?:cookie|cookies)\b/,
+  /\bprivate[_ -]?key\b/,
+  /\bmnemonic\b/,
+  /\bseed phrase\b/,
+  /\bsigner\b/,
+] satisfies RegExp[];
+
+const EXTERNAL_POST_PATTERNS = [
+  /\bpost(?: a| this)? tweet\b/,
+  /\breply to (?:this )?tweet\b/,
+  /\bquote tweet\b/,
+  /\bpost to (?:x|twitter)\b/,
+  /\btwitter-post\b/,
+  /\bpublish post\b/,
+] satisfies RegExp[];
+
+export function deriveSkillCapabilityTags(params: {
+  slug: string;
+  displayName: string;
+  summary?: string;
+  frontmatter?: Record<string, unknown>;
+  readmeText: string;
+  fileContents?: Array<{ path: string; content: string }>;
+}): SkillCapabilityTag[] {
+  const text = normalizeText([
+    params.slug,
+    params.displayName,
+    params.summary,
+    safeJson(params.frontmatter),
+    params.readmeText,
+    ...(params.fileContents ?? []).map((file) => `${file.path}\n${file.content}`),
+  ]);
+
+  const tags = new Set<SkillCapabilityTag>();
+
+  const isCrypto = matches(text, CRYPTO_PATTERNS);
+  const requiresWallet = matches(text, WALLET_PATTERNS);
+  const canMakePurchases = matches(text, PURCHASE_PATTERNS);
+  const canSignTransactions = matches(text, TRANSACTION_PATTERNS);
+  const requiresOauthToken = matches(text, OAUTH_PATTERNS);
+  const requiresSensitiveCredentials = matches(text, SENSITIVE_CREDENTIAL_PATTERNS);
+  const postsExternally = matches(text, EXTERNAL_POST_PATTERNS);
+
+  if (isCrypto) tags.add("crypto");
+  if (requiresWallet) tags.add("requires-wallet");
+  if (canMakePurchases) tags.add("can-make-purchases");
+  if (canSignTransactions) tags.add("can-sign-transactions");
+  if (requiresOauthToken) tags.add("requires-oauth-token");
+  if (requiresSensitiveCredentials) tags.add("requires-sensitive-credentials");
+  if (postsExternally) tags.add("posts-externally");
+
+  if (canSignTransactions || canMakePurchases) {
+    tags.add("crypto");
+  }
+  if (canSignTransactions) {
+    tags.add("requires-wallet");
+  }
+  if (requiresWallet || canSignTransactions || requiresOauthToken) {
+    tags.add("requires-sensitive-credentials");
+  }
+
+  return SKILL_CAPABILITY_TAGS.filter((tag) => tags.has(tag));
+}
@@ -1,4 +1,5 @@
 import { ConvexError } from "convex/values";
+import { normalizeTextContentType } from "clawhub-schema";
 import semver from "semver";
 import { api, internal } from "../_generated/api";
 import type { Doc, Id } from "../_generated/dataModel";
@@ -8,6 +9,13 @@ import { generateChangelogForPublish } from "./changelog";
 import { generateEmbedding } from "./embeddings";
 import { requireGitHubAccountAge } from "./githubAccount";
 import type { PublicUser } from "./public";
+import {
+  findOversizedPublishFile,
+  getPublishFileSizeError,
+  getPublishTotalSizeError,
+  MAX_PUBLISH_TOTAL_BYTES,
+} from "./publishLimits";
+import { deriveSkillCapabilityTags } from "./skillCapabilityTags";
 import {
  computeQualitySignals,
  evaluateQuality,
@@ -29,12 +37,6 @@ import {
 import { generateSkillSummary } from "./skillSummary";
 import { runStaticPublishScan } from "./staticPublishScan";
 import type { WebhookSkillPayload } from "./webhooks";
-import {
-  findOversizedPublishFile,
-  getPublishFileSizeError,
-  getPublishTotalSizeError,
-  MAX_PUBLISH_TOTAL_BYTES,
-} from "./publishLimits";

 const MAX_FILES_FOR_EMBEDDING = 40;
 const QUALITY_WINDOW_MS = 24 * 60 * 60 * 1000;
@@ -112,6 +114,7 @@ export async function publishVersionForUser(
  const sanitizedFiles = args.files.map((file) => ({
    ...file,
    path: sanitizePath(file.path),
+    contentType: normalizeTextContentType(file.path, file.contentType),
  }));
  if (sanitizedFiles.some((file) => !file.path)) {
    throw new ConvexError("Invalid file paths");
@@ -246,6 +249,14 @@ export async function publishVersionForUser(
    readme: readmeText,
    otherFiles,
  });
+  const capabilityTags = deriveSkillCapabilityTags({
+    slug,
+    displayName,
+    summary,
+    frontmatter,
+    readmeText,
+    fileContents,
+  });

  const fingerprintPromise = hashSkillFiles(
    publishFiles.map((file) => ({ path: file.path, sha256: file.sha256 })),
@@ -298,6 +309,7 @@ export async function publishVersionForUser(
      clawdis,
      license: PLATFORM_SKILL_LICENSE,
    },
+    capabilityTags,
    summary,
    staticScan,
    embedding,
@@ -6,6 +6,8 @@ function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys
  return Object.fromEntries(keys.map((k) => [k, obj[k]])) as Pick<T, K>;
 }

+type SharedSkillKey = Extract<keyof Doc<"skills">, keyof Doc<"skillSearchDigest">>;
+
 /**
 * Fields shared 1:1 between `skills` and `skillSearchDigest` (same name,
 * same type).  Used by both `extractDigestFields` and `digestToHydratableSkill`
@@ -22,6 +24,7 @@ const SHARED_KEYS = [
  "latestVersionId",
  "latestVersionSummary",
  "tags",
+  "capabilityTags",
  "badges",
  "stats",
  "statsDownloads",
@@ -34,7 +37,7 @@ const SHARED_KEYS = [
  "moderationReason",
  "createdAt",
  "updatedAt",
-] as const satisfies readonly (keyof Doc<"skills"> & keyof Doc<"skillSearchDigest">)[];
+] as const satisfies readonly SharedSkillKey[];

 /** Fields stored in the skillSearchDigest table. */
 export type SkillSearchDigestFields = Pick<Doc<"skills">, (typeof SHARED_KEYS)[number]> & {
@@ -121,8 +124,7 @@ export function digestToOwnerInfo(
  // Empty string means backfilled but owner has no handle.
  // Use userId as fallback handle, matching the live getOwnerInfo path.
  const handle = digest.ownerHandle || undefined;
-  const fallbackHandle =
-    handle ?? String(digest.ownerPublisherId ?? digest.ownerUserId);
+  const fallbackHandle = handle ?? String(digest.ownerPublisherId ?? digest.ownerUserId);
  const resolvedHandle = handle ?? fallbackHandle;
  // Determine if we have real profile data (deactivated/deleted owners have
  // all profile fields undefined, while handle-less visible owners still have
@@ -10,18 +10,34 @@ type SkillStatDeltas = {
  installsAllTime?: number;
 };

+/**
+ * Read the canonical value of a migrated stat field from a skill document.
+ *
+ * Top-level fields (`statsDownloads`, etc.) are the source of truth — they are
+ * indexable and kept up-to-date by the event pipeline. The nested `stats.*`
+ * fields are only used as a fallback for pre-migration documents where the
+ * top-level field is still `undefined`.
+ *
+ * All code that reads a migrated stat value should go through this function
+ * rather than accessing `skill.stats.*` directly.
+ */
+export function readCanonicalStat(
+  skill: Doc<"skills">,
+  field: "downloads" | "stars" | "installsCurrent" | "installsAllTime",
+): number {
+  const topLevelKey = `stats${field[0].toUpperCase()}${field.slice(1)}` as
+    | "statsDownloads"
+    | "statsStars"
+    | "statsInstallsCurrent"
+    | "statsInstallsAllTime";
+  return typeof skill[topLevelKey] === "number" ? skill[topLevelKey]! : (skill.stats[field] ?? 0);
+}
+
 export function applySkillStatDeltas(skill: Doc<"skills">, deltas: SkillStatDeltas) {
-  const currentDownloads =
-    typeof skill.statsDownloads === "number" ? skill.statsDownloads : skill.stats.downloads;
-  const currentStars = typeof skill.statsStars === "number" ? skill.statsStars : skill.stats.stars;
-  const currentInstallsCurrent =
-    typeof skill.statsInstallsCurrent === "number"
-      ? skill.statsInstallsCurrent
-      : (skill.stats.installsCurrent ?? 0);
-  const currentInstallsAllTime =
-    typeof skill.statsInstallsAllTime === "number"
-      ? skill.statsInstallsAllTime
-      : (skill.stats.installsAllTime ?? 0);
+  const currentDownloads = readCanonicalStat(skill, "downloads");
+  const currentStars = readCanonicalStat(skill, "stars");
+  const currentInstallsCurrent = readCanonicalStat(skill, "installsCurrent");
+  const currentInstallsAllTime = readCanonicalStat(skill, "installsAllTime");

  const currentComments = skill.stats.comments;
  const nextDownloads = Math.max(0, currentDownloads + (deltas.downloads ?? 0));
@@ -150,7 +150,10 @@ describe("skillZip", () => {
      ]);
      const unzipped = unzipSync(zip);

-      expect(Object.keys(unzipped).sort()).toEqual(["package/dist/index.js", "package/package.json"]);
+      expect(Object.keys(unzipped).sort()).toEqual([
+        "package/dist/index.js",
+        "package/package.json",
+      ]);
      expect(unzipped["_meta.json"]).toBeUndefined();
    });
  });
@@ -1,4 +1,5 @@
 import { ConvexError } from "convex/values";
+import { normalizeTextContentType } from "clawhub-schema";
 import semver from "semver";
 import { internal } from "../_generated/api";
 import type { Doc, Id } from "../_generated/dataModel";
@@ -101,7 +102,11 @@ export async function publishSoulVersionForUser(
  const sanitizedFiles = args.files.map((file) => {
    const path = sanitizePath(file.path);
    if (!path) throw new ConvexError("Invalid file paths");
-    return { ...file, path };
+    return {
+      ...file,
+      path,
+      contentType: normalizeTextContentType(file.path, file.contentType),
+    };
  });
  const publishFiles = sanitizedFiles.filter((file) => !isMacJunkPath(file.path));
  if (publishFiles.some((file) => !isTextFile(file.path, file.contentType ?? undefined))) {
@@ -0,0 +1,67 @@
+import type { Doc, Id } from "../_generated/dataModel";
+import type { MutationCtx } from "../_generated/server";
+
+function getSkillContribution(skill: Doc<"skills">) {
+  if (skill.softDeletedAt) {
+    return { publishedSkills: 0, totalStars: 0, totalDownloads: 0 };
+  }
+
+  return {
+    publishedSkills: 1,
+    totalStars: skill.stats?.stars ?? 0,
+    totalDownloads: skill.stats?.downloads ?? 0,
+  };
+}
+
+async function patchUserStats(
+  ctx: Pick<MutationCtx, "db">,
+  userId: Id<"users">,
+  delta: { publishedSkills: number; totalStars: number; totalDownloads: number },
+) {
+  const user = await ctx.db.get(userId);
+  if (!user) return;
+
+  await ctx.db.patch(userId, {
+    publishedSkills: Math.max(0, (user.publishedSkills ?? 0) + delta.publishedSkills),
+    totalStars: Math.max(0, (user.totalStars ?? 0) + delta.totalStars),
+    totalDownloads: Math.max(0, (user.totalDownloads ?? 0) + delta.totalDownloads),
+  });
+}
+
+export async function adjustUserSkillStatsForSkillChange(
+  ctx: Pick<MutationCtx, "db">,
+  previousSkill: Doc<"skills"> | null | undefined,
+  nextSkill: Doc<"skills"> | null | undefined,
+) {
+  if (!previousSkill && !nextSkill) return;
+
+  const prevOwnerId = previousSkill?.ownerUserId ?? null;
+  const nextOwnerId = nextSkill?.ownerUserId ?? null;
+  const prevContribution = previousSkill ? getSkillContribution(previousSkill) : null;
+  const nextContribution = nextSkill ? getSkillContribution(nextSkill) : null;
+
+  if (prevOwnerId && prevOwnerId === nextOwnerId) {
+    await patchUserStats(ctx, prevOwnerId, {
+      publishedSkills: (nextContribution?.publishedSkills ?? 0) - (prevContribution?.publishedSkills ?? 0),
+      totalStars: (nextContribution?.totalStars ?? 0) - (prevContribution?.totalStars ?? 0),
+      totalDownloads: (nextContribution?.totalDownloads ?? 0) - (prevContribution?.totalDownloads ?? 0),
+    });
+    return;
+  }
+
+  if (prevOwnerId) {
+    await patchUserStats(ctx, prevOwnerId, {
+      publishedSkills: -(prevContribution?.publishedSkills ?? 0),
+      totalStars: -(prevContribution?.totalStars ?? 0),
+      totalDownloads: -(prevContribution?.totalDownloads ?? 0),
+    });
+  }
+
+  if (nextOwnerId) {
+    await patchUserStats(ctx, nextOwnerId, {
+      publishedSkills: nextContribution?.publishedSkills ?? 0,
+      totalStars: nextContribution?.totalStars ?? 0,
+      totalDownloads: nextContribution?.totalDownloads ?? 0,
+    });
+  }
+}
@@ -323,7 +323,10 @@ export const evaluatePackageReleaseWithLlm = internalAction({
        const content = await blob.text();
        fileContents.push({ path: f.path, content });
        const lower = f.path.toLowerCase();
-        if (!readmeContent && (lower === "readme.md" || lower === "readme.mdx" || lower === "readme.markdown")) {
+        if (
+          !readmeContent &&
+          (lower === "readme.md" || lower === "readme.mdx" || lower === "readme.markdown")
+        ) {
          readmeContent = content;
        }
      } catch {
@@ -332,8 +335,11 @@ export const evaluatePackageReleaseWithLlm = internalAction({
    }

    if (!readmeContent) {
-      const packageJsonText = fileContents.find((entry) => entry.path.toLowerCase() === "package.json")?.content;
-      readmeContent = packageJsonText ?? `# ${pkg.displayName}\n\n${release.summary ?? pkg.summary ?? pkg.name}`;
+      const packageJsonText = fileContents.find(
+        (entry) => entry.path.toLowerCase() === "package.json",
+      )?.content;
+      readmeContent =
+        packageJsonText ?? `# ${pkg.displayName}\n\n${release.summary ?? pkg.summary ?? pkg.name}`;
    }

    const allContent = [readmeContent, ...fileContents.map((f) => f.content)].join("\n");
@@ -7,6 +7,10 @@ vi.mock("./_generated/api", () => ({
      getSkillBackfillPageInternal: Symbol("getSkillBackfillPageInternal"),
      applySkillBackfillPatchInternal: Symbol("applySkillBackfillPatchInternal"),
      backfillSkillSummariesInternal: Symbol("backfillSkillSummariesInternal"),
+      getUserStatsBackfillPageInternal: Symbol("getUserStatsBackfillPageInternal"),
+      getUserOwnedSkillsBackfillPageInternal: Symbol("getUserOwnedSkillsBackfillPageInternal"),
+      applyUserStatsBackfillPatchInternal: Symbol("applyUserStatsBackfillPatchInternal"),
+      backfillUserStatsInternal: Symbol("backfillUserStatsInternal"),
      getSkillFingerprintBackfillPageInternal: Symbol("getSkillFingerprintBackfillPageInternal"),
      applySkillFingerprintBackfillPatchInternal: Symbol(
        "applySkillFingerprintBackfillPatchInternal",
@@ -36,6 +40,7 @@ const {
  backfillLatestVersionSummaryInternal,
  backfillSkillFingerprintsInternalHandler,
  backfillSkillSummariesInternalHandler,
+  backfillUserStatsInternalHandler,
  cleanupEmptySkillsInternalHandler,
  nominateEmptySkillSpammersInternalHandler,
  upsertSkillBadgeRecordInternal,
@@ -259,6 +264,63 @@ describe("maintenance backfill", () => {
    });
    expect(runAfter).not.toHaveBeenCalled();
  });
+
+  it("backfills denormalized user hover stats from indexed owner pages", async () => {
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce({
+        items: [{ _id: "users:1" }],
+        cursor: null,
+        isDone: true,
+      })
+      .mockResolvedValueOnce({
+        items: [
+          { stats: { stars: 4, downloads: 30 }, softDeletedAt: undefined },
+          { stats: { stars: 2, downloads: 10 }, softDeletedAt: 123 },
+          { stats: { stars: 1, downloads: 5 }, softDeletedAt: undefined },
+        ],
+        cursor: null,
+        isDone: true,
+      });
+    const runMutation = vi.fn().mockResolvedValue({ ok: true });
+
+    const result = await backfillUserStatsInternalHandler(
+      { runQuery, runMutation } as never,
+      { batchSize: 10, skillBatchSize: 50, maxBatches: 1 },
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      stats: {
+        usersScanned: 1,
+        usersPatched: 1,
+      },
+      isDone: true,
+      cursor: null,
+    });
+    expect(runQuery).toHaveBeenNthCalledWith(1, internal.maintenance.getUserStatsBackfillPageInternal, {
+      cursor: undefined,
+      batchSize: 10,
+    });
+    expect(runQuery).toHaveBeenNthCalledWith(
+      2,
+      internal.maintenance.getUserOwnedSkillsBackfillPageInternal,
+      {
+        ownerUserId: "users:1",
+        cursor: undefined,
+        batchSize: 50,
+      },
+    );
+    expect(runMutation).toHaveBeenCalledWith(
+      internal.maintenance.applyUserStatsBackfillPatchInternal,
+      {
+        userId: "users:1",
+        publishedSkills: 2,
+        totalStars: 5,
+        totalDownloads: 35,
+      },
+    );
+  });
 });

 describe("maintenance badge denormalization", () => {
@@ -5,13 +5,14 @@ import type { ActionCtx } from "./_generated/server";
 import { action, internalAction, internalMutation, internalQuery } from "./functions";
 import { assertRole, requireUserFromAction } from "./lib/access";
 import { buildSkillSummaryBackfillPatch, type ParsedSkillData } from "./lib/skillBackfill";
+import { deriveSkillCapabilityTags } from "./lib/skillCapabilityTags";
 import {
  computeQualitySignals,
  evaluateQuality,
  getTrustTier,
  type TrustTier,
 } from "./lib/skillQuality";
-import { hashSkillFiles } from "./lib/skills";
+import { hashSkillFiles, isTextFile } from "./lib/skills";
 import { computeIsSuspicious } from "./lib/skillSafety";
 import { extractDigestFields } from "./lib/skillSearchDigest";
 import { generateSkillSummary } from "./lib/skillSummary";
@@ -22,6 +23,7 @@ const DEFAULT_MAX_BATCHES = 20;
 const MAX_MAX_BATCHES = 200;
 const DEFAULT_EMPTY_SKILL_MAX_README_BYTES = 8000;
 const DEFAULT_EMPTY_SKILL_NOMINATION_THRESHOLD = 3;
+const DEFAULT_CAPABILITY_BACKFILL_DELAY_MS = 500;
 const PLATFORM_SKILL_LICENSE = "MIT-0" as const;

 type BackfillStats = {
@@ -34,6 +36,11 @@ type BackfillStats = {
  missingStorageBlob: number;
 };

+type UserStatsBackfillStats = {
+  usersScanned: number;
+  usersPatched: number;
+};
+
 type BackfillPageItem =
  | {
      kind: "ok";
@@ -55,6 +62,18 @@ type BackfillPageResult = {
  isDone: boolean;
 };

+type UserStatsBackfillPageResult = {
+  items: Array<Pick<Doc<"users">, "_id">>;
+  cursor: string | null;
+  isDone: boolean;
+};
+
+type UserOwnedSkillsBackfillPageResult = {
+  items: Array<Pick<Doc<"skills">, "stats" | "softDeletedAt">>;
+  cursor: string | null;
+  isDone: boolean;
+};
+
 export const getSkillBackfillPageInternal = internalQuery({
  args: {
    cursor: v.optional(v.string()),
@@ -134,6 +153,65 @@ export const applySkillBackfillPatchInternal = internalMutation({
  },
 });

+export const getUserStatsBackfillPageInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<UserStatsBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+    const { page, isDone, continueCursor } = await ctx.db
+      .query("users")
+      .order("asc")
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+    return {
+      items: page.map((user) => ({ _id: user._id })),
+      cursor: continueCursor,
+      isDone,
+    };
+  },
+});
+
+export const getUserOwnedSkillsBackfillPageInternal = internalQuery({
+  args: {
+    ownerUserId: v.id("users"),
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<UserOwnedSkillsBackfillPageResult> => {
+    const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+    const { page, isDone, continueCursor } = await ctx.db
+      .query("skills")
+      .withIndex("by_owner", (q) => q.eq("ownerUserId", args.ownerUserId))
+      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+    return {
+      items: page.map((skill) => ({
+        stats: skill.stats,
+        softDeletedAt: skill.softDeletedAt,
+      })),
+      cursor: continueCursor,
+      isDone,
+    };
+  },
+});
+
+export const applyUserStatsBackfillPatchInternal = internalMutation({
+  args: {
+    userId: v.id("users"),
+    publishedSkills: v.number(),
+    totalStars: v.number(),
+    totalDownloads: v.number(),
+  },
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.userId, {
+      publishedSkills: args.publishedSkills,
+      totalStars: args.totalStars,
+      totalDownloads: args.totalDownloads,
+    });
+    return { ok: true as const };
+  },
+});
+
 export type BackfillActionArgs = {
  dryRun?: boolean;
  batchSize?: number;
@@ -149,6 +227,20 @@ export type BackfillActionResult = {
  cursor: string | null;
 };

+export type UserStatsBackfillActionArgs = {
+  batchSize?: number;
+  skillBatchSize?: number;
+  maxBatches?: number;
+  cursor?: string;
+};
+
+export type UserStatsBackfillActionResult = {
+  ok: true;
+  stats: UserStatsBackfillStats;
+  isDone: boolean;
+  cursor: string | null;
+};
+
 export async function backfillSkillSummariesInternalHandler(
  ctx: ActionCtx,
  args: BackfillActionArgs,
@@ -244,6 +336,73 @@ export async function backfillSkillSummariesInternalHandler(
  return { ok: true as const, stats: totals, isDone, cursor };
 }

+export async function backfillUserStatsInternalHandler(
+  ctx: ActionCtx,
+  args: UserStatsBackfillActionArgs,
+): Promise<UserStatsBackfillActionResult> {
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+  const skillBatchSize = clampInt(args.skillBatchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+  const maxBatches = clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES);
+  const totals: UserStatsBackfillStats = {
+    usersScanned: 0,
+    usersPatched: 0,
+  };
+
+  let cursor: string | null = args.cursor ?? null;
+  let isDone = false;
+
+  for (let i = 0; i < maxBatches; i++) {
+    const page = (await ctx.runQuery(internal.maintenance.getUserStatsBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    })) as UserStatsBackfillPageResult;
+
+    cursor = page.cursor;
+    isDone = page.isDone;
+
+    for (const user of page.items) {
+      totals.usersScanned++;
+      let ownedSkillsCursor: string | null = null;
+      let userPublishedSkills = 0;
+      let userTotalStars = 0;
+      let userTotalDownloads = 0;
+
+      while (true) {
+        const skillPage = (await ctx.runQuery(
+          internal.maintenance.getUserOwnedSkillsBackfillPageInternal,
+          {
+            ownerUserId: user._id,
+            cursor: ownedSkillsCursor ?? undefined,
+            batchSize: skillBatchSize,
+          },
+        )) as UserOwnedSkillsBackfillPageResult;
+
+        for (const skill of skillPage.items) {
+          if (skill.softDeletedAt) continue;
+          userPublishedSkills += 1;
+          userTotalStars += skill.stats?.stars ?? 0;
+          userTotalDownloads += skill.stats?.downloads ?? 0;
+        }
+
+        if (skillPage.isDone) break;
+        ownedSkillsCursor = skillPage.cursor;
+      }
+
+      await ctx.runMutation(internal.maintenance.applyUserStatsBackfillPatchInternal, {
+        userId: user._id,
+        publishedSkills: userPublishedSkills,
+        totalStars: userTotalStars,
+        totalDownloads: userTotalDownloads,
+      });
+      totals.usersPatched++;
+    }
+
+    if (isDone) break;
+  }
+
+  return { ok: true as const, stats: totals, isDone, cursor };
+}
+
 export const backfillSkillSummariesInternal = internalAction({
  args: {
    dryRun: v.optional(v.boolean()),
@@ -255,6 +414,16 @@ export const backfillSkillSummariesInternal = internalAction({
  handler: backfillSkillSummariesInternalHandler,
 });

+export const backfillUserStatsInternal = internalAction({
+  args: {
+    batchSize: v.optional(v.number()),
+    skillBatchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+  },
+  handler: backfillUserStatsInternalHandler,
+});
+
 export const backfillSkillSummaries: ReturnType<typeof action> = action({
  args: {
    dryRun: v.optional(v.boolean()),
@@ -319,6 +488,211 @@ export const continueSkillSummaryBackfillJobInternal = internalAction({
  },
 });

+type CapabilityBackfillStats = {
+  skillsScanned: number;
+  skillsPatched: number;
+  versionsPatched: number;
+  missingVersions: number;
+  missingStorageBlob: number;
+};
+
+type CapabilityBackfillResult = {
+  ok: true;
+  stats: CapabilityBackfillStats;
+  cursor: string | null;
+  isDone: boolean;
+};
+
+export const applySkillCapabilityTagsInternal = internalMutation({
+  args: {
+    skillId: v.id("skills"),
+    versionId: v.id("skillVersions"),
+    capabilityTags: v.array(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const version = await ctx.db.get(args.versionId);
+    if (!version) return { ok: false as const, reason: "missing_version" as const };
+    const skill = await ctx.db.get(args.skillId);
+    if (!skill) return { ok: false as const, reason: "missing_skill" as const };
+
+    const normalizedTags = [...new Set(args.capabilityTags)];
+    let versionPatched = false;
+    let skillPatched = false;
+
+    if (JSON.stringify(version.capabilityTags ?? []) !== JSON.stringify(normalizedTags)) {
+      await ctx.db.patch(version._id, {
+        capabilityTags: normalizedTags.length ? normalizedTags : undefined,
+      });
+      versionPatched = true;
+    }
+
+    if (
+      skill.latestVersionId === version._id &&
+      JSON.stringify(skill.capabilityTags ?? []) !== JSON.stringify(normalizedTags)
+    ) {
+      await ctx.db.patch(skill._id, {
+        capabilityTags: normalizedTags.length ? normalizedTags : undefined,
+        updatedAt: Date.now(),
+      });
+      skillPatched = true;
+    }
+
+    return { ok: true as const, versionPatched, skillPatched };
+  },
+});
+
+export async function backfillSkillCapabilityTagsInternalHandler(
+  ctx: ActionCtx,
+  args: {
+    dryRun?: boolean;
+    cursor?: string;
+    batchSize?: number;
+    maxBatches?: number;
+    delayMs?: number;
+  },
+): Promise<CapabilityBackfillResult> {
+  const dryRun = Boolean(args.dryRun);
+  const batchSize = clampInt(args.batchSize ?? DEFAULT_BATCH_SIZE, 1, MAX_BATCH_SIZE);
+  const maxBatches = dryRun
+    ? clampInt(args.maxBatches ?? DEFAULT_MAX_BATCHES, 1, MAX_MAX_BATCHES)
+    : 1;
+
+  const stats: CapabilityBackfillStats = {
+    skillsScanned: 0,
+    skillsPatched: 0,
+    versionsPatched: 0,
+    missingVersions: 0,
+    missingStorageBlob: 0,
+  };
+
+  let cursor = args.cursor ?? null;
+  let isDone = false;
+
+  for (let batchIndex = 0; batchIndex < maxBatches; batchIndex += 1) {
+    const page = await ctx.runQuery(internal.maintenance.getSkillBackfillPageInternal, {
+      cursor: cursor ?? undefined,
+      batchSize,
+    });
+
+    cursor = page.cursor;
+    isDone = page.isDone;
+
+    for (const item of page.items) {
+      if (item.kind !== "ok") {
+        if (item.kind === "missingVersionDoc" || item.kind === "missingLatestVersion") {
+          stats.missingVersions += 1;
+        }
+        continue;
+      }
+
+      stats.skillsScanned += 1;
+
+      const version = (await ctx.runQuery(internal.skills.getVersionByIdInternal, {
+        versionId: item.versionId,
+      })) as Doc<"skillVersions"> | null;
+      if (!version) {
+        stats.missingVersions += 1;
+        continue;
+      }
+
+      const readmeBlob = await ctx.storage.get(item.readmeStorageId);
+      if (!readmeBlob) {
+        stats.missingStorageBlob += 1;
+        continue;
+      }
+
+      const readmeText = await readmeBlob.text();
+      const fileContents: Array<{ path: string; content: string }> = [];
+      let hasMissingTextBlob = false;
+      for (const file of version.files) {
+        const lower = file.path.toLowerCase();
+        if (lower === "skill.md" || lower === "skills.md") continue;
+        if (!isTextFile(file.path, file.contentType ?? undefined)) continue;
+        const blob = await ctx.storage.get(file.storageId);
+        if (!blob) {
+          stats.missingStorageBlob += 1;
+          hasMissingTextBlob = true;
+          break;
+        }
+        fileContents.push({ path: file.path, content: await blob.text() });
+      }
+
+      if (hasMissingTextBlob) continue;
+
+      const capabilityTags = deriveSkillCapabilityTags({
+        slug: item.skillSlug,
+        displayName: item.skillDisplayName,
+        summary: item.skillSummary ?? undefined,
+        frontmatter: item.versionParsed?.frontmatter,
+        readmeText,
+        fileContents,
+      });
+
+      if (dryRun) continue;
+
+      const result = await ctx.runMutation(internal.maintenance.applySkillCapabilityTagsInternal, {
+        skillId: item.skillId,
+        versionId: item.versionId,
+        capabilityTags,
+      });
+
+      if (result.ok) {
+        if (result.skillPatched) stats.skillsPatched += 1;
+        if (result.versionPatched) stats.versionsPatched += 1;
+      }
+    }
+
+    if (isDone) break;
+  }
+
+  return { ok: true, stats, cursor, isDone };
+}
+
+export const backfillSkillCapabilityTagsInternal = internalAction({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    delayMs: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<CapabilityBackfillResult> => {
+    const result = await backfillSkillCapabilityTagsInternalHandler(ctx, args);
+
+    if (!args.dryRun && !result.isDone && result.cursor) {
+      const delayMs = clampInt(args.delayMs ?? DEFAULT_CAPABILITY_BACKFILL_DELAY_MS, 0, 60_000);
+      await ctx.scheduler.runAfter(
+        delayMs,
+        internal.maintenance.backfillSkillCapabilityTagsInternal,
+        {
+          dryRun: false,
+          cursor: result.cursor,
+          batchSize: args.batchSize,
+          maxBatches: 1,
+          delayMs,
+        },
+      );
+    }
+
+    return result;
+  },
+});
+
+export const backfillSkillCapabilityTags: ReturnType<typeof action> = action({
+  args: {
+    dryRun: v.optional(v.boolean()),
+    cursor: v.optional(v.string()),
+    batchSize: v.optional(v.number()),
+    maxBatches: v.optional(v.number()),
+    delayMs: v.optional(v.number()),
+  },
+  handler: async (ctx, args): Promise<CapabilityBackfillResult> => {
+    const { user } = await requireUserFromAction(ctx);
+    assertRole(user, ["admin"]);
+    return ctx.runAction(internal.maintenance.backfillSkillCapabilityTagsInternal, args);
+  },
+});
+
 type FingerprintBackfillStats = {
  versionsScanned: number;
  versionsPatched: number;
@@ -0,0 +1,70 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "./functions";
+
+export const createInternal = internalMutation({
+  args: {
+    packageId: v.id("packages"),
+    version: v.string(),
+    prefix: v.string(),
+    tokenHash: v.string(),
+    provider: v.literal("github-actions"),
+    repository: v.string(),
+    repositoryId: v.string(),
+    repositoryOwner: v.string(),
+    repositoryOwnerId: v.string(),
+    workflowFilename: v.string(),
+    environment: v.optional(v.string()),
+    runId: v.string(),
+    runAttempt: v.string(),
+    sha: v.string(),
+    ref: v.string(),
+    refType: v.optional(v.string()),
+    actor: v.optional(v.string()),
+    actorId: v.optional(v.string()),
+    expiresAt: v.number(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("packagePublishTokens", {
+      ...args,
+      createdAt: now,
+      lastUsedAt: undefined,
+      revokedAt: undefined,
+    });
+  },
+});
+
+export const getByHashInternal = internalQuery({
+  args: { tokenHash: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("packagePublishTokens")
+      .withIndex("by_hash", (q) => q.eq("tokenHash", args.tokenHash))
+      .unique();
+  },
+});
+
+export const getByIdInternal = internalQuery({
+  args: { tokenId: v.id("packagePublishTokens") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.tokenId);
+  },
+});
+
+export const touchInternal = internalMutation({
+  args: { tokenId: v.id("packagePublishTokens") },
+  handler: async (ctx, args) => {
+    const token = await ctx.db.get(args.tokenId);
+    if (!token || token.revokedAt || token.expiresAt <= Date.now()) return;
+    await ctx.db.patch(token._id, { lastUsedAt: Date.now() });
+  },
+});
+
+export const revokeInternal = internalMutation({
+  args: { tokenId: v.id("packagePublishTokens") },
+  handler: async (ctx, args) => {
+    const token = await ctx.db.get(args.tokenId);
+    if (!token || token.revokedAt) return;
+    await ctx.db.patch(token._id, { revokedAt: Date.now() });
+  },
+});
@@ -8,6 +8,7 @@ import {
  getByName,
  list,
  publishPackage,
+  publishPackageForTrustedPublisherInternal,
  publishPackageForUserInternal,
  getVersionByName,
  insertReleaseInternal,
@@ -176,6 +177,15 @@ const publishPackageForUserInternalHandler = (
    unknown
  >
 )._handler;
+const publishPackageForTrustedPublisherInternalHandler = (
+  publishPackageForTrustedPublisherInternal as unknown as WrappedHandler<
+    {
+      publishTokenId: string;
+      payload: unknown;
+    },
+    unknown
+  >
+)._handler;
 const getPackageReleaseScanBackfillBatchInternalHandler = (
  getPackageReleaseScanBackfillBatchInternal as unknown as WrappedHandler<
    {
@@ -321,8 +331,8 @@ function makeDigestCtx(options: {
  const pageByTable = new Map<
    string,
    Map<
-    string | null,
-    { page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }
+      string | null,
+      { page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }
    >
  >();
  const indexNames: string[] = [];
@@ -420,7 +430,8 @@ function makeDigestCtx(options: {
                    indexName === "by_name"
                      ? matchedValue
                        ? String(pkg.normalizedName) === matchedValue
-                        : String(pkg.normalizedName) >= lowerBound && String(pkg.normalizedName) < upperBound
+                        : String(pkg.normalizedName) >= lowerBound &&
+                          String(pkg.normalizedName) < upperBound
                      : matchedValue
                        ? String(pkg.runtimeId) === matchedValue
                        : String(pkg.runtimeId) >= lowerBound && String(pkg.runtimeId) < upperBound,
@@ -487,12 +498,17 @@ function makeDigestCtx(options: {
                    lt: () => queryBuilder,
                  };
                  builder?.(queryBuilder);
-                  const match = (options.exactDigests ?? []).find((digest) => digest.packageId === packageId);
+                  const match = (options.exactDigests ?? []).find(
+                    (digest) => digest.packageId === packageId,
+                  );
                  return {
                    unique: vi.fn().mockResolvedValue(match ?? null),
                  };
                }
-                if (indexName === "by_active_normalized_name" || indexName === "by_active_runtime_id") {
+                if (
+                  indexName === "by_active_normalized_name" ||
+                  indexName === "by_active_runtime_id"
+                ) {
                  let lowerBound = "";
                  let upperBound = "";
                  const queryBuilder = {
@@ -541,9 +557,7 @@ function makeInsertReleaseCtx(
  recordsById: Record<string, Record<string, unknown>> = {},
 ) {
  const patch = vi.fn();
-  const insert = vi
-    .fn()
-    .mockResolvedValueOnce("packageReleases:new");
+  const insert = vi.fn().mockResolvedValueOnce("packageReleases:new");
  return {
    patch,
    insert,
@@ -610,7 +624,9 @@ function makePackageCtx(options: {
    ctx: {
      db: {
        get: vi.fn(async (id: string) => {
-          if (pkg && id === pkg.ownerUserId) return { _id: id, handle: "owner" };
+          if (typeof id === "string" && id.startsWith("users:")) {
+            return { _id: id, handle: id.split(":").pop() ?? "user" };
+          }
          if (ownerPublisher && pkg && id === pkg.ownerPublisherId) return ownerPublisher;
          if (pkg && id === pkg.latestReleaseId) return latestRelease;
          return null;
@@ -810,10 +826,7 @@ describe("packages public queries", () => {
    const { ctx } = makeDigestCtx({
      pages: [
        {
-          page: [
-            makeDigest("secret-plugin", { channel: "private" }),
-            makeDigest("public-plugin"),
-          ],
+          page: [makeDigest("secret-plugin", { channel: "private" }), makeDigest("public-plugin")],
          isDone: true,
          continueCursor: "",
        },
@@ -1434,10 +1447,11 @@ describe("packages public queries", () => {
      continueCursor: "",
    });
    await expect(
-      getVersionByNameHandler(
-        ctx,
-        { name: "demo-plugin", version: "1.0.0", viewerUserId: "users:owner" } as never,
-      ),
+      getVersionByNameHandler(ctx, {
+        name: "demo-plugin",
+        version: "1.0.0",
+        viewerUserId: "users:owner",
+      } as never),
    ).resolves.toBeNull();
  });

@@ -1498,6 +1512,26 @@ describe("packages public queries", () => {
    expect(detail?.package.name).toBe("demo-plugin");
  });

+  it("treats invalid auth user lookups as anonymous for public package detail", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:broken" as never);
+    const { ctx } = makePackageCtx({
+      pkg: makePackageDoc({ channel: "community" }),
+    });
+    const get = ctx.db.get as ReturnType<typeof vi.fn>;
+    get.mockImplementation(async (id: string) => {
+      if (id === "users:broken") throw new Error("Table mismatch");
+      if (id === "users:owner") return { _id: id, handle: "owner" };
+      if (id === "packageReleases:demo-1") return makeReleaseDoc();
+      return null;
+    });
+
+    const detail = await getByNameHandler(ctx, {
+      name: "demo-plugin",
+    });
+
+    expect(detail?.package.name).toBe("demo-plugin");
+  });
+
  it("does not expose a soft-deleted latest release as latestVersion", async () => {
    const { ctx } = makePackageCtx({
      latestRelease: makeReleaseDoc({ softDeletedAt: 10 }),
@@ -1615,7 +1649,7 @@ describe("packages public queries", () => {
        integritySha256: "abc123",
        runtimeId: "other.plugin",
      }),
-    ).rejects.toThrow('runtime id changes are not allowed');
+    ).rejects.toThrow("runtime id changes are not allowed");
  });

  it("promotes existing packages to official when publisher becomes trusted", async () => {
@@ -2028,11 +2062,296 @@ describe("packages public queries", () => {
    ).rejects.toThrow("Skill packages must use the skills publish flow");
  });

+  it("rejects trusted publish tokens after trusted publisher rotation or deletion", async () => {
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockResolvedValueOnce({
+          _id: "packagePublishTokens:1",
+          packageId: "packages:demo",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+          environment: "clawhub-release",
+          version: "1.0.0",
+          sha: "abc123",
+          ref: "refs/heads/main",
+          runId: "100",
+          runAttempt: "1",
+          expiresAt: Date.now() + 60_000,
+        })
+        .mockResolvedValueOnce(null),
+    };
+
+    await expect(
+      publishPackageForTrustedPublisherInternalHandler(ctx as never, {
+        publishTokenId: "packagePublishTokens:1",
+        payload: {
+          name: "demo-plugin",
+          family: "bundle-plugin",
+          version: "1.0.0",
+          changelog: "init",
+          bundle: { hostTargets: ["desktop"] },
+          files: [],
+        },
+      }),
+    ).rejects.toThrow(
+      "Trusted publish token no longer matches the current package trusted publisher",
+    );
+  });
+
+  it("revokes trusted publish tokens after a successful publish", async () => {
+    const runMutation = vi.fn(async (_ref: unknown, args: unknown) => {
+      if (
+        typeof args === "object" &&
+        args !== null &&
+        "name" in args &&
+        "version" in args &&
+        "files" in args
+      ) {
+        return {
+          ok: true,
+          packageId: "packages:demo",
+          releaseId: "packageReleases:demo-2",
+        };
+      }
+      return null;
+    });
+    const trustedPublisher = {
+      _id: "packageTrustedPublishers:1",
+      packageId: "packages:demo",
+      provider: "github-actions",
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+      workflowFilename: "plugin-clawhub-release.yml",
+      environment: "clawhub-release",
+    };
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockResolvedValueOnce({
+          _id: "packagePublishTokens:1",
+          packageId: "packages:demo",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+          environment: "clawhub-release",
+          version: "1.0.0",
+          sha: "abc123",
+          ref: "refs/heads/main",
+          runId: "100",
+          runAttempt: "1",
+          expiresAt: Date.now() + 60_000,
+        })
+        .mockResolvedValueOnce(trustedPublisher)
+        .mockResolvedValueOnce(makePackageDoc({ family: "bundle-plugin" }))
+        .mockResolvedValueOnce(trustedPublisher)
+        .mockResolvedValueOnce(null),
+      runMutation,
+      scheduler: {
+        runAfter: vi.fn(),
+      },
+      storage: {
+        get: vi.fn(),
+      },
+    };
+
+    await expect(
+      publishPackageForTrustedPublisherInternalHandler(ctx as never, {
+        publishTokenId: "packagePublishTokens:1",
+        payload: {
+          name: "demo-plugin",
+          family: "bundle-plugin",
+          version: "1.0.0",
+          changelog: "init",
+          bundle: { hostTargets: ["desktop"] },
+          files: [],
+        },
+      }),
+    ).resolves.toMatchObject({
+      ok: true,
+      packageId: "packages:demo",
+      releaseId: "packageReleases:demo-2",
+    });
+
+    expect(runMutation).toHaveBeenCalledWith(expect.anything(), {
+      tokenId: "packagePublishTokens:1",
+    });
+  });
+
+  it("accepts trusted publish tokens when no environment is pinned", async () => {
+    const runMutation = vi.fn(async (_ref: unknown, args: unknown) => {
+      if (
+        typeof args === "object" &&
+        args !== null &&
+        "name" in args &&
+        "version" in args &&
+        "files" in args
+      ) {
+        return {
+          ok: true,
+          packageId: "packages:demo",
+          releaseId: "packageReleases:demo-2",
+        };
+      }
+      return null;
+    });
+    const trustedPublisher = {
+      _id: "packageTrustedPublishers:1",
+      packageId: "packages:demo",
+      provider: "github-actions",
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+      workflowFilename: "plugin-clawhub-release.yml",
+    };
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockResolvedValueOnce({
+          _id: "packagePublishTokens:1",
+          packageId: "packages:demo",
+          provider: "github-actions",
+          repository: "openclaw/openclaw",
+          repositoryId: "1",
+          repositoryOwner: "openclaw",
+          repositoryOwnerId: "2",
+          workflowFilename: "plugin-clawhub-release.yml",
+          version: "1.0.0",
+          sha: "abc123",
+          ref: "refs/heads/main",
+          runId: "100",
+          runAttempt: "1",
+          expiresAt: Date.now() + 60_000,
+        })
+        .mockResolvedValueOnce(trustedPublisher)
+        .mockResolvedValueOnce(makePackageDoc({ family: "bundle-plugin" }))
+        .mockResolvedValueOnce(trustedPublisher)
+        .mockResolvedValueOnce(null),
+      runMutation,
+      scheduler: {
+        runAfter: vi.fn(),
+      },
+      storage: {
+        get: vi.fn(),
+      },
+    };
+
+    await expect(
+      publishPackageForTrustedPublisherInternalHandler(ctx as never, {
+        publishTokenId: "packagePublishTokens:1",
+        payload: {
+          name: "demo-plugin",
+          family: "bundle-plugin",
+          version: "1.0.0",
+          changelog: "init",
+          bundle: { hostTargets: ["desktop"] },
+          files: [],
+        },
+      }),
+    ).resolves.toMatchObject({
+      ok: true,
+      packageId: "packages:demo",
+      releaseId: "packageReleases:demo-2",
+    });
+  });
+
+  it("requires manual override for user-auth publishes when trusted publisher config exists", async () => {
+    const runMutation = vi.fn(async (_ref: unknown, args: unknown) => {
+      if (
+        typeof args === "object" &&
+        args !== null &&
+        "actorUserId" in args &&
+        "minimumRole" in args
+      ) {
+        return null;
+      }
+      if (
+        typeof args === "object" &&
+        args !== null &&
+        "name" in args &&
+        "version" in args &&
+        "files" in args
+      ) {
+        return {
+          ok: true,
+          packageId: "packages:demo",
+          releaseId: "packageReleases:demo-2",
+        };
+      }
+      return null;
+    });
+    const trustedPublisher = {
+      _id: "packageTrustedPublishers:1",
+      packageId: "packages:demo",
+      provider: "github-actions",
+      repository: "openclaw/openclaw",
+      repositoryId: "1",
+      repositoryOwner: "openclaw",
+      repositoryOwnerId: "2",
+      workflowFilename: "plugin-clawhub-release.yml",
+      environment: "clawhub-release",
+    };
+    const ctx = {
+      runQuery: vi
+        .fn()
+        .mockResolvedValueOnce(makePackageDoc({ family: "bundle-plugin" }))
+        .mockResolvedValueOnce(trustedPublisher)
+        .mockResolvedValueOnce({
+          _id: "users:owner",
+          githubCreatedAt: Date.now() - 20 * 24 * 60 * 60 * 1000,
+        })
+        .mockResolvedValueOnce(null),
+      runMutation,
+      scheduler: {
+        runAfter: vi.fn(),
+      },
+      storage: {
+        get: vi.fn(),
+      },
+    };
+
+    await expect(
+      publishPackageForUserInternalHandler(ctx as never, {
+        actorUserId: "users:owner",
+        payload: {
+          name: "demo-plugin",
+          family: "bundle-plugin",
+          version: "1.0.0",
+          changelog: "tag publish",
+          bundle: { hostTargets: ["desktop"] },
+          source: {
+            kind: "github",
+            url: "https://github.com/openclaw/openclaw",
+            repo: "openclaw/openclaw",
+            ref: "refs/tags/plugins-2026.4.1-beta.1",
+            commit: "abc123",
+            path: "extensions/discord",
+            importedAt: Date.now(),
+          },
+          files: [],
+        },
+      }),
+    ).rejects.toThrow(
+      "Manual publishes for packages with trusted publisher config require manualOverrideReason",
+    );
+  });
+
  it("scans plugin publishes and forwards scan status to insertReleaseInternal", async () => {
    const runMutation = vi.fn(async (_ref: unknown, args: unknown) => args);
    const ctx = {
      runQuery: vi
        .fn()
+        .mockResolvedValueOnce(null)
        .mockResolvedValueOnce({
          _id: "users:owner",
          githubCreatedAt: Date.now() - 20 * 24 * 60 * 60 * 1000,
@@ -2057,8 +2376,14 @@ describe("packages public queries", () => {
                },
              }),
            ],
-            ["storage:manifest", JSON.stringify({ id: "demo.plugin", tools: [{ name: "demoTool" }] })],
-            ["storage:code", "import { execSync } from 'node:child_process';\nexecSync('curl http://x');\n"],
+            [
+              "storage:manifest",
+              JSON.stringify({ id: "demo.plugin", tools: [{ name: "demoTool" }] }),
+            ],
+            [
+              "storage:code",
+              "import { execSync } from 'node:child_process';\nexecSync('curl http://x');\n",
+            ],
          ]);
          const content = files.get(storageId);
          return content ? new Blob([content]) : null;
@@ -2163,9 +2488,11 @@ describe("packages public queries", () => {
            if (table !== "packages") throw new Error(`Unexpected table ${table}`);
            return {
              withIndex: vi.fn(() => ({
-                unique: vi.fn().mockResolvedValue(
-                  makePackageDoc({ ownerUserId: "users:owner", scanStatus: "pending" }),
-                ),
+                unique: vi
+                  .fn()
+                  .mockResolvedValue(
+                    makePackageDoc({ ownerUserId: "users:owner", scanStatus: "pending" }),
+                  ),
              })),
            };
          }),
@@ -2191,6 +2518,9 @@ describe("packages public queries", () => {
                staticScan: { status: "clean" },
              });
            }
+            if (id === "users:owner") {
+              return { _id: "users:owner", handle: "owner" };
+            }
            if (id === "publishers:owner") {
              return { _id: "publishers:owner", kind: "user", linkedUserId: "users:owner" };
            }
@@ -5,6 +5,7 @@ import {
  listMine,
  migrateLegacyPublisherHandleToOrgInternal,
  removeMember,
+  updateProfile,
 } from "./publishers";

 vi.mock("@convex-dev/auth/server", () => ({
@@ -16,9 +17,11 @@ type WrappedHandler<TArgs, TResult = unknown> = {
 };

 const addMemberHandler = (
-  addMember as unknown as WrappedHandler<
-    { publisherId: string; userHandle: string; role: "owner" | "admin" | "publisher" }
-  >
+  addMember as unknown as WrappedHandler<{
+    publisherId: string;
+    userHandle: string;
+    role: "owner" | "admin" | "publisher";
+  }>
 )._handler;

 const removeMemberHandler = (
@@ -50,6 +53,15 @@ const listMineHandler = (
  listMine as unknown as WrappedHandler<Record<string, never>, Array<unknown>>
 )._handler;

+const updateProfileHandler = (
+  updateProfile as unknown as WrappedHandler<{
+    publisherId: string;
+    displayName: string;
+    bio?: string;
+    image?: string;
+  }>
+)._handler;
+
 describe("publishers membership controls", () => {
  it("prevents admins from promoting members to owner", async () => {
    vi.mocked(getAuthUserId).mockResolvedValue("users:admin" as never);
@@ -232,98 +244,115 @@ describe("publishers membership controls", () => {
        query: vi.fn((table: string) => {
          if (table === "publisherMembers") {
            return {
-              withIndex: vi.fn((indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-                if (indexName !== "by_publisher_user") {
-                  throw new Error(`unexpected index ${indexName}`);
-                }
-                let publisherId = "";
-                let userId = "";
-                const q = {
-                  eq: (field: string, value: string) => {
-                    if (field === "publisherId") publisherId = value;
-                    if (field === "userId") userId = value;
-                    return q;
-                  },
-                };
-                builder?.(q);
-                return {
-                  unique: vi.fn(async () =>
-                    publisherMembers.find(
-                      (member) => member.publisherId === publisherId && member.userId === userId,
-                    ) ?? null,
-                  ),
-                };
-              }),
+              withIndex: vi.fn(
+                (
+                  indexName: string,
+                  builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+                ) => {
+                  if (indexName !== "by_publisher_user") {
+                    throw new Error(`unexpected index ${indexName}`);
+                  }
+                  let publisherId = "";
+                  let userId = "";
+                  const q = {
+                    eq: (field: string, value: string) => {
+                      if (field === "publisherId") publisherId = value;
+                      if (field === "userId") userId = value;
+                      return q;
+                    },
+                  };
+                  builder?.(q);
+                  return {
+                    unique: vi.fn(
+                      async () =>
+                        publisherMembers.find(
+                          (member) =>
+                            member.publisherId === publisherId && member.userId === userId,
+                        ) ?? null,
+                    ),
+                  };
+                },
+              ),
            };
          }
          if (table === "users") {
            return {
-              withIndex: vi.fn((indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-                if (indexName !== "handle") {
-                  throw new Error(`unexpected index ${indexName}`);
-                }
-                let handle = "";
-                const q = {
-                  eq: (field: string, value: string) => {
-                    if (field === "handle") handle = value;
-                    return q;
-                  },
-                };
-                builder?.(q);
-                return {
-                  unique: vi.fn(async () => {
-                    if (handle === "owner") return { _id: "users:owner", handle: "owner" };
-                    return null;
-                  }),
-                };
-              }),
+              withIndex: vi.fn(
+                (
+                  indexName: string,
+                  builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+                ) => {
+                  if (indexName !== "handle") {
+                    throw new Error(`unexpected index ${indexName}`);
+                  }
+                  let handle = "";
+                  const q = {
+                    eq: (field: string, value: string) => {
+                      if (field === "handle") handle = value;
+                      return q;
+                    },
+                  };
+                  builder?.(q);
+                  return {
+                    unique: vi.fn(async () => {
+                      if (handle === "owner") return { _id: "users:owner", handle: "owner" };
+                      return null;
+                    }),
+                  };
+                },
+              ),
            };
          }
          if (table === "publishers") {
            return {
-              withIndex: vi.fn((indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-                let handle = "";
-                let linkedUserId = "";
-                const q = {
-                  eq: (field: string, value: string) => {
-                    if (field === "handle") handle = value;
-                    if (field === "linkedUserId") linkedUserId = value;
-                    return q;
-                  },
-                };
-                builder?.(q);
-                return {
-                  unique: vi.fn(async () => {
-                    if (indexName === "by_handle" && handle === "jaredforreal") {
-                      return {
-                        _id: "publishers:jaredforreal",
-                        _creationTime: 1,
-                        kind: "user",
-                        handle: "jaredforreal",
-                        displayName: "Jared",
-                        linkedUserId: "users:jared",
-                        trustedPublisher: false,
-                        createdAt: 1,
-                        updatedAt: 1,
-                      };
-                    }
-                    if (indexName === "by_linked_user" && linkedUserId === "users:jared") {
-                      return {
-                        _id: "publishers:jaredforreal",
-                        _creationTime: 1,
-                        kind: "user",
-                        handle: "jaredforreal",
-                        displayName: "Jared",
-                        linkedUserId: "users:jared",
-                        trustedPublisher: false,
-                        createdAt: 1,
-                        updatedAt: 1,
-                      };
-                    }
-                    return null;
-                  }),
-                };
-              }),
+              withIndex: vi.fn(
+                (
+                  indexName: string,
+                  builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+                ) => {
+                  let handle = "";
+                  let linkedUserId = "";
+                  const q = {
+                    eq: (field: string, value: string) => {
+                      if (field === "handle") handle = value;
+                      if (field === "linkedUserId") linkedUserId = value;
+                      return q;
+                    },
+                  };
+                  builder?.(q);
+                  return {
+                    unique: vi.fn(async () => {
+                      if (indexName === "by_handle" && handle === "jaredforreal") {
+                        return {
+                          _id: "publishers:jaredforreal",
+                          _creationTime: 1,
+                          kind: "user",
+                          handle: "jaredforreal",
+                          displayName: "Jared",
+                          linkedUserId: "users:jared",
+                          trustedPublisher: false,
+                          createdAt: 1,
+                          updatedAt: 1,
+                        };
+                      }
+                      if (indexName === "by_linked_user" && linkedUserId === "users:jared") {
+                        return {
+                          _id: "publishers:jaredforreal",
+                          _creationTime: 1,
+                          kind: "user",
+                          handle: "jaredforreal",
+                          displayName: "Jared",
+                          linkedUserId: "users:jared",
+                          trustedPublisher: false,
+                          createdAt: 1,
+                          updatedAt: 1,
+                        };
+                      }
+                      return null;
+                    }),
+                  };
+                },
+              ),
            };
          }
          throw new Error(`unexpected table ${table}`);
@@ -352,6 +381,135 @@ describe("publishers membership controls", () => {
      }),
    );
  });
+
+  it("lets org admins update org profile fields", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:admin" as never);
+    const patch = vi.fn(async () => {});
+    const insert = vi.fn(async () => "auditLogs:1");
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "users:admin") return { _id: id };
+          if (id === "publishers:org") {
+            return {
+              _id: id,
+              kind: "org",
+              handle: "shopify",
+              displayName: "Shopify",
+              image: undefined,
+              bio: undefined,
+            };
+          }
+          return null;
+        }),
+        query: vi.fn((table: string) => {
+          if (table === "publisherMembers") {
+            return {
+              withIndex: vi.fn(() => ({
+                unique: vi.fn().mockResolvedValue({
+                  _id: "publisherMembers:admin",
+                  publisherId: "publishers:org",
+                  userId: "users:admin",
+                  role: "admin",
+                }),
+              })),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+        patch,
+        insert,
+        delete: vi.fn(),
+        replace: vi.fn(),
+        normalizeId: vi.fn(),
+      },
+    };
+
+    await expect(
+      updateProfileHandler(
+        ctx as never,
+        {
+          publisherId: "publishers:org",
+          displayName: "Shopify",
+          bio: "Commerce platform",
+          image: "https://cdn.example.com/shopify.png",
+        } as never,
+      ),
+    ).resolves.toEqual({
+      ok: true,
+      publisher: expect.objectContaining({
+        _id: "publishers:org",
+        displayName: "Shopify",
+      }),
+    });
+
+    expect(patch).toHaveBeenCalledWith(
+      "publishers:org",
+      expect.objectContaining({
+        displayName: "Shopify",
+        bio: "Commerce platform",
+        image: "https://cdn.example.com/shopify.png",
+      }),
+    );
+    expect(insert).toHaveBeenCalledWith(
+      "auditLogs",
+      expect.objectContaining({
+        action: "publisher.profile.update",
+        targetId: "publishers:org",
+      }),
+    );
+  });
+
+  it("rejects invalid org profile image URLs", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:admin" as never);
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "users:admin") return { _id: id };
+          if (id === "publishers:org") {
+            return {
+              _id: id,
+              kind: "org",
+              handle: "shopify",
+              displayName: "Shopify",
+            };
+          }
+          return null;
+        }),
+        query: vi.fn((table: string) => {
+          if (table === "publisherMembers") {
+            return {
+              withIndex: vi.fn(() => ({
+                unique: vi.fn().mockResolvedValue({
+                  _id: "publisherMembers:admin",
+                  publisherId: "publishers:org",
+                  userId: "users:admin",
+                  role: "admin",
+                }),
+              })),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+        patch: vi.fn(),
+        insert: vi.fn(),
+        delete: vi.fn(),
+        replace: vi.fn(),
+        normalizeId: vi.fn(),
+      },
+    };
+
+    await expect(
+      updateProfileHandler(
+        ctx as never,
+        {
+          publisherId: "publishers:org",
+          displayName: "Shopify",
+          image: "not-a-url",
+        } as never,
+      ),
+    ).rejects.toThrow("Image must be a valid URL");
+  });
 });

 describe("publisher bootstrap", () => {
@@ -526,101 +684,126 @@ describe("legacy publisher migration", () => {
    const query = vi.fn((table: string) => {
      if (table === "users") {
        return {
-          withIndex: vi.fn((_indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-            let handle = "";
-            const q = {
-              eq: (field: string, value: string) => {
-                if (field === "handle") handle = value;
-                return q;
-              },
-            };
-            builder?.(q);
-            return {
-              unique: vi.fn(async () =>
-                [...users.values()].find((user) => user.handle === handle) ?? null,
-              ),
-            };
-          }),
+          withIndex: vi.fn(
+            (
+              _indexName: string,
+              builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+            ) => {
+              let handle = "";
+              const q = {
+                eq: (field: string, value: string) => {
+                  if (field === "handle") handle = value;
+                  return q;
+                },
+              };
+              builder?.(q);
+              return {
+                unique: vi.fn(
+                  async () => [...users.values()].find((user) => user.handle === handle) ?? null,
+                ),
+              };
+            },
+          ),
        };
      }
      if (table === "publishers") {
        return {
-          withIndex: vi.fn((_indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-            let handle = "";
-            let linkedUserId = "";
-            const q = {
-              eq: (field: string, value: string) => {
-                if (field === "handle") handle = value;
-                if (field === "linkedUserId") linkedUserId = value;
-                return q;
-              },
-            };
-            builder?.(q);
-            return {
-              unique: vi.fn(async () => {
-                if (handle) {
-                  return [...publishers.values()].find((publisher) => publisher.handle === handle) ?? null;
-                }
-                if (linkedUserId) {
-                  return (
-                    [...publishers.values()].find((publisher) => publisher.linkedUserId === linkedUserId) ??
-                    null
-                  );
-                }
-                return null;
-              }),
-            };
-          }),
+          withIndex: vi.fn(
+            (
+              _indexName: string,
+              builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+            ) => {
+              let handle = "";
+              let linkedUserId = "";
+              const q = {
+                eq: (field: string, value: string) => {
+                  if (field === "handle") handle = value;
+                  if (field === "linkedUserId") linkedUserId = value;
+                  return q;
+                },
+              };
+              builder?.(q);
+              return {
+                unique: vi.fn(async () => {
+                  if (handle) {
+                    return (
+                      [...publishers.values()].find((publisher) => publisher.handle === handle) ??
+                      null
+                    );
+                  }
+                  if (linkedUserId) {
+                    return (
+                      [...publishers.values()].find(
+                        (publisher) => publisher.linkedUserId === linkedUserId,
+                      ) ?? null
+                    );
+                  }
+                  return null;
+                }),
+              };
+            },
+          ),
        };
      }
      if (table === "publisherMembers") {
        return {
-          withIndex: vi.fn((_indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-            let publisherId = "";
-            let userId = "";
-            const q = {
-              eq: (field: string, value: string) => {
-                if (field === "publisherId") publisherId = value;
-                if (field === "userId") userId = value;
-                return q;
-              },
-            };
-            builder?.(q);
-            return {
-              unique: vi.fn(async () =>
-                publisherMembers.find(
-                  (member) => member.publisherId === publisherId && member.userId === userId,
-                ) ?? null,
-              ),
-            };
-          }),
+          withIndex: vi.fn(
+            (
+              _indexName: string,
+              builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+            ) => {
+              let publisherId = "";
+              let userId = "";
+              const q = {
+                eq: (field: string, value: string) => {
+                  if (field === "publisherId") publisherId = value;
+                  if (field === "userId") userId = value;
+                  return q;
+                },
+              };
+              builder?.(q);
+              return {
+                unique: vi.fn(
+                  async () =>
+                    publisherMembers.find(
+                      (member) => member.publisherId === publisherId && member.userId === userId,
+                    ) ?? null,
+                ),
+              };
+            },
+          ),
        };
      }
      if (table === "packages") {
        return {
-          withIndex: vi.fn((_indexName: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
-            let ownerUserId = "";
-            let ownerPublisherId = "";
-            const q = {
-              eq: (field: string, value: string) => {
-                if (field === "ownerUserId") ownerUserId = value;
-                if (field === "ownerPublisherId") ownerPublisherId = value;
-                return q;
-              },
-            };
-            builder?.(q);
-            return {
-              collect: vi.fn(async () => {
-                if (ownerUserId) {
-                  return packages.filter((pkg) => pkg.ownerUserId === ownerUserId);
-                }
-                if (ownerPublisherId) {
-                  return packages.filter((pkg) => pkg.ownerPublisherId === ownerPublisherId);
-                }
-                return [];
-              }),
-            };
-          }),
+          withIndex: vi.fn(
+            (
+              _indexName: string,
+              builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+            ) => {
+              let ownerUserId = "";
+              let ownerPublisherId = "";
+              const q = {
+                eq: (field: string, value: string) => {
+                  if (field === "ownerUserId") ownerUserId = value;
+                  if (field === "ownerPublisherId") ownerPublisherId = value;
+                  return q;
+                },
+              };
+              builder?.(q);
+              return {
+                collect: vi.fn(async () => {
+                  if (ownerUserId) {
+                    return packages.filter((pkg) => pkg.ownerUserId === ownerUserId);
+                  }
+                  if (ownerPublisherId) {
+                    return packages.filter((pkg) => pkg.ownerPublisherId === ownerPublisherId);
+                  }
+                  return [];
+                }),
+              };
+            },
+          ),
        };
      }
      if (table === "skills") {
@@ -636,9 +819,7 @@ describe("legacy publisher migration", () => {
    const result = await migrateLegacyPublisherHandleToOrgInternalHandler(
      {
        db: {
-          get: vi.fn(async (id: string) =>
-            users.get(id) ?? publishers.get(id) ?? null,
-          ),
+          get: vi.fn(async (id: string) => users.get(id) ?? publishers.get(id) ?? null),
          query,
          patch,
          insert,
@@ -4,6 +4,7 @@ import type { Doc, Id } from "./_generated/dataModel";
 import type { MutationCtx } from "./_generated/server";
 import { internalMutation, internalQuery, mutation, query } from "./functions";
 import { assertAdmin, requireUser } from "./lib/access";
+import { toPublicPublisher } from "./lib/public";
 import {
  ensurePersonalPublisherForUser,
  getActiveUserByHandleOrPersonalPublisher,
@@ -14,7 +15,6 @@ import {
  isPublisherRoleAllowed,
  normalizePublisherHandle,
 } from "./lib/publishers";
-import { toPublicPublisher } from "./lib/public";

 const PUBLISHER_HANDLE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;

@@ -88,10 +88,9 @@ async function migrateLegacyPublisherHandleToOrgWithActor(
    throw new ConvexError(`Legacy user "@${orgHandle}" not found`);
  }

-  const personalPublisher =
-    legacyUser.personalPublisherId
-      ? await ctx.db.get(legacyUser.personalPublisherId)
-      : await getPersonalPublisherForUser(ctx, legacyUser._id);
+  const personalPublisher = legacyUser.personalPublisherId
+    ? await ctx.db.get(legacyUser.personalPublisherId)
+    : await getPersonalPublisherForUser(ctx, legacyUser._id);
  const convertiblePublisher =
    handlePublisher?.kind === "user" && handlePublisher.linkedUserId === legacyUser._id
      ? handlePublisher
@@ -356,7 +355,9 @@ export const resolvePublishTargetForUserInternal = internalMutation({
  args: {
    actorUserId: v.id("users"),
    ownerHandle: v.optional(v.string()),
-    minimumRole: v.optional(v.union(v.literal("owner"), v.literal("admin"), v.literal("publisher"))),
+    minimumRole: v.optional(
+      v.union(v.literal("owner"), v.literal("admin"), v.literal("publisher")),
+    ),
  },
  handler: async (ctx, args) => {
    const actor = await ctx.db.get(args.actorUserId);
@@ -418,9 +419,9 @@ export const listMine = query({
        if (!publicPublisher) return null;
        return {
          publisher: publicPublisher,
-        role: membership.role,
-      };
-    }),
+          role: membership.role,
+        };
+      }),
    );
    const visiblePublishers = publishers.filter(
      (
@@ -538,6 +539,70 @@ export const createOrg = mutation({
  },
 });

+export const updateProfile = mutation({
+  args: {
+    publisherId: v.id("publishers"),
+    displayName: v.string(),
+    bio: v.optional(v.string()),
+    image: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx);
+    const publisher = await ctx.db.get(args.publisherId);
+    if (!publisher || publisher.deletedAt || publisher.deactivatedAt) {
+      throw new ConvexError("Publisher not found");
+    }
+    if (publisher.kind !== "org") {
+      throw new ConvexError("Only org publishers can be updated here");
+    }
+
+    const membership = await getPublisherMembership(ctx, publisher._id, userId);
+    if (!membership || !isPublisherRoleAllowed(membership.role, ["admin"])) {
+      throw new ConvexError("Forbidden");
+    }
+
+    const displayName = args.displayName.trim() || publisher.handle;
+    const bio = args.bio?.trim() || undefined;
+    const image = args.image?.trim() || undefined;
+    if (image) {
+      let parsed: URL;
+      try {
+        parsed = new URL(image);
+      } catch {
+        throw new ConvexError("Image must be a valid URL");
+      }
+      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new ConvexError("Image must use http or https");
+      }
+    }
+
+    const now = Date.now();
+    await ctx.db.patch(publisher._id, {
+      displayName,
+      bio,
+      image,
+      updatedAt: now,
+    });
+    await ctx.db.insert("auditLogs", {
+      actorUserId: userId,
+      action: "publisher.profile.update",
+      targetType: "publisher",
+      targetId: publisher._id,
+      metadata: {
+        displayName,
+        bio,
+        image,
+      },
+      createdAt: now,
+    });
+
+    return {
+      ok: true as const,
+      publisher: toPublicPublisher(await ctx.db.get(publisher._id)),
+    };
+  },
+});
+
 export const migrateLegacyPublisherHandleToOrg = mutation({
  args: {
    handle: v.string(),
@@ -28,6 +28,9 @@ const users = defineTable({
  githubFetchedAt: v.optional(v.number()),
  githubProfileSyncedAt: v.optional(v.number()),
  trustedPublisher: v.optional(v.boolean()),
+  publishedSkills: v.optional(v.number()),
+  totalStars: v.optional(v.number()),
+  totalDownloads: v.optional(v.number()),
  personalPublisherId: v.optional(v.id("publishers")),
  requiresModerationAt: v.optional(v.number()),
  requiresModerationReason: v.optional(v.string()),
@@ -40,7 +43,8 @@ const users = defineTable({
 })
  .index("email", ["email"])
  .index("phone", ["phone"])
-  .index("handle", ["handle"]);
+  .index("handle", ["handle"])
+  .index("by_active_handle", ["deletedAt", "deactivatedAt", "handle"]);

 const publishers = defineTable({
  kind: v.union(v.literal("user"), v.literal("org")),
@@ -91,10 +95,22 @@ const badgesValidator = v.optional(
  }),
 );

+/**
+ * Nested stat fields on the `skills` document.
+ *
+ * The four migrated fields below are kept for backward compatibility only.
+ * Always use the top-level fields (`statsDownloads`, `statsStars`,
+ * `statsInstallsCurrent`, `statsInstallsAllTime`) as the source of truth,
+ * and use `readCanonicalStat()` / `applySkillStatDeltas()` to read/write them.
+ */
 const statsValidator = v.object({
+  /** @deprecated Use top-level `statsDownloads` instead. */
  downloads: v.number(),
+  /** @deprecated Use top-level `statsInstallsCurrent` instead. */
  installsCurrent: v.optional(v.number()),
+  /** @deprecated Use top-level `statsInstallsAllTime` instead. */
  installsAllTime: v.optional(v.number()),
+  /** @deprecated Use top-level `statsStars` instead. */
  stars: v.number(),
  versions: v.number(),
  comments: v.number(),
@@ -188,6 +204,23 @@ const packageVerificationValidator = v.optional(
  }),
 );

+const packagePublishActorValidator = v.optional(
+  v.union(
+    v.object({
+      kind: v.literal("user"),
+      userId: v.id("users"),
+    }),
+    v.object({
+      kind: v.literal("github-actions"),
+      repository: v.string(),
+      workflow: v.string(),
+      runId: v.string(),
+      runAttempt: v.string(),
+      sha: v.string(),
+    }),
+  ),
+);
+
 const packageScanStatusValidator = v.optional(
  v.union(
    v.literal("clean"),
@@ -228,6 +261,7 @@ const skills = defineTable({
    }),
  ),
  tags: v.record(v.string(), v.id("skillVersions")),
+  capabilityTags: v.optional(v.array(v.string())),
  softDeletedAt: v.optional(v.number()),
  badges: badgesValidator,
  moderationStatus: moderationStatusValidator,
@@ -366,7 +400,8 @@ const souls = defineTable({
  .index("by_slug", ["slug"])
  .index("by_owner", ["ownerUserId"])
  .index("by_owner_publisher", ["ownerPublisherId"])
-  .index("by_updated", ["updatedAt"]);
+  .index("by_updated", ["updatedAt"])
+  .index("by_active_updated", ["softDeletedAt", "updatedAt"]);

 const skillVersions = defineTable({
  skillId: v.id("skills"),
@@ -425,6 +460,7 @@ const skillVersions = defineTable({
      checkedAt: v.number(),
    }),
  ),
+  capabilityTags: v.optional(v.array(v.string())),
  staticScan: v.optional(
    v.object({
      status: v.union(v.literal("clean"), v.literal("suspicious"), v.literal("malicious")),
@@ -566,6 +602,7 @@ const skillSearchDigest = defineTable({
    }),
  ),
  tags: v.record(v.string(), v.id("skillVersions")),
+  capabilityTags: v.optional(v.array(v.string())),
  badges: badgesValidator,
  stats: statsValidator,
  statsDownloads: v.optional(v.number()),
@@ -719,6 +756,7 @@ const packageReleases = defineTable({
  ),
  source: v.optional(v.any()),
  createdBy: v.id("users"),
+  publishActor: packagePublishActorValidator,
  createdAt: v.number(),
  softDeletedAt: v.optional(v.number()),
 })
@@ -727,6 +765,50 @@ const packageReleases = defineTable({
  .index("by_package_version", ["packageId", "version"])
  .index("by_sha256hash", ["sha256hash"]);

+const packageTrustedPublishers = defineTable({
+  packageId: v.id("packages"),
+  provider: v.literal("github-actions"),
+  repository: v.string(),
+  repositoryId: v.string(),
+  repositoryOwner: v.string(),
+  repositoryOwnerId: v.string(),
+  workflowFilename: v.string(),
+  environment: v.optional(v.string()),
+  createdByUserId: v.id("users"),
+  updatedByUserId: v.id("users"),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+})
+  .index("by_package", ["packageId"])
+  .index("by_repository", ["repository", "workflowFilename"]);
+
+const packagePublishTokens = defineTable({
+  packageId: v.id("packages"),
+  version: v.string(),
+  prefix: v.string(),
+  tokenHash: v.string(),
+  provider: v.literal("github-actions"),
+  repository: v.string(),
+  repositoryId: v.string(),
+  repositoryOwner: v.string(),
+  repositoryOwnerId: v.string(),
+  workflowFilename: v.string(),
+  environment: v.optional(v.string()),
+  runId: v.string(),
+  runAttempt: v.string(),
+  sha: v.string(),
+  ref: v.string(),
+  refType: v.optional(v.string()),
+  actor: v.optional(v.string()),
+  actorId: v.optional(v.string()),
+  expiresAt: v.number(),
+  lastUsedAt: v.optional(v.number()),
+  revokedAt: v.optional(v.number()),
+  createdAt: v.number(),
+})
+  .index("by_hash", ["tokenHash"])
+  .index("by_package", ["packageId", "version", "createdAt"]);
+
 const packageSearchDigest = defineTable({
  packageId: v.id("packages"),
  name: v.string(),
@@ -844,12 +926,7 @@ const packageCapabilitySearchDigest = defineTable({
    "executesCode",
    "updatedAt",
  ])
-  .index("by_active_family_tag_updated", [
-    "softDeletedAt",
-    "family",
-    "capabilityTag",
-    "updatedAt",
-  ])
+  .index("by_active_family_tag_updated", ["softDeletedAt", "family", "capabilityTag", "updatedAt"])
  .index("by_active_family_tag_executes_updated", [
    "softDeletedAt",
    "family",
@@ -1255,6 +1332,8 @@ export default defineSchema({
  skillSlugAliases,
  packages,
  packageReleases,
+  packageTrustedPublishers,
+  packagePublishTokens,
  packageSearchDigest,
  packageCapabilitySearchDigest,
  souls,
@@ -240,9 +240,14 @@ describe("search helpers", () => {

    const result = await searchSkillsHandler(
      {
-        vectorSearch: vi.fn().mockResolvedValue(
-          vectorEntries.map((entry, index) => ({ _id: entry.embeddingId, _score: 0.9 - index * 0.01 })),
-        ),
+        vectorSearch: vi
+          .fn()
+          .mockResolvedValue(
+            vectorEntries.map((entry, index) => ({
+              _id: entry.embeddingId,
+              _score: 0.9 - index * 0.01,
+            })),
+          ),
        runQuery,
      },
      { query: "skill-downloader", limit: 10 },
@@ -340,6 +345,55 @@ describe("search helpers", () => {
    expect(result[0].skill.slug).toBe("downloader-1");
  });

+  it("filters vector search results by capability tag", async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce([
+        {
+          embeddingId: "skillEmbeddings:crypto",
+          skill: makePublicSkill({
+            id: "skills:crypto",
+            slug: "wallet-helper",
+            displayName: "Wallet Helper",
+            capabilityTags: ["crypto", "requires-wallet"],
+          }),
+          version: null,
+          ownerHandle: "owner",
+          owner: null,
+        },
+        {
+          embeddingId: "skillEmbeddings:oauth",
+          skill: makePublicSkill({
+            id: "skills:oauth",
+            slug: "x-poster",
+            displayName: "X Poster",
+            capabilityTags: ["requires-oauth-token", "posts-externally"],
+          }),
+          version: null,
+          ownerHandle: "owner",
+          owner: null,
+        },
+      ])
+      .mockResolvedValueOnce([]);
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([
+          { _id: "skillEmbeddings:crypto", _score: 0.9 },
+          { _id: "skillEmbeddings:oauth", _score: 0.8 },
+        ]),
+        runQuery,
+      },
+      { query: "helper", limit: 10, capabilityTag: "crypto" },
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0].skill.slug).toBe("wallet-helper");
+  });
+
  it("deduplicates exact slug injection against vector exact matches", async () => {
    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);

@@ -819,6 +873,7 @@ function makePublicSkill(params: {
  slug: string;
  displayName: string;
  downloads?: number;
+  capabilityTags?: string[];
 }) {
  return {
    _id: params.id,
@@ -831,6 +886,7 @@ function makePublicSkill(params: {
    forkOf: undefined,
    latestVersionId: "skillVersions:1",
    tags: {},
+    capabilityTags: params.capabilityTags,
    badges: {},
    stats: {
      downloads: params.downloads ?? 0,
@@ -7,6 +7,7 @@ import { isSkillHighlighted } from "./lib/badges";
 import { generateEmbedding } from "./lib/embeddings";
 import type { HydratableSkill, PublicPublisher } from "./lib/public";
 import { toPublicPublisher, toPublicSkill, toPublicSoul } from "./lib/public";
+import { SKILL_CAPABILITY_TAGS } from "./lib/skillCapabilityTags";
 import { getOwnerPublisher } from "./lib/publishers";
 import { matchesExactTokens, tokenize } from "./lib/searchText";
 import { isSkillSuspicious } from "./lib/skillSafety";
@@ -51,6 +52,7 @@ const NAME_EXACT_BOOST = 1.1;
 const NAME_PREFIX_BOOST = 0.6;
 const POPULARITY_WEIGHT = 0.08;
 const FALLBACK_SCAN_LIMIT = 500;
+const SKILL_CAPABILITY_TAG_SET = new Set<string>(SKILL_CAPABILITY_TAGS);

 function getNextCandidateLimit(current: number, max: number) {
  const next = Math.min(current * 2, max);
@@ -120,27 +122,38 @@ function isSlugLikeQuery(query: string) {
  return /^[a-z0-9][a-z0-9-]*$/.test(query.trim().toLowerCase());
 }

+function matchesCapabilityTag(
+  skill: Pick<HydratableSkill, "capabilityTags">,
+  capabilityTag?: string,
+) {
+  if (!capabilityTag) return true;
+  return (skill.capabilityTags ?? []).includes(capabilityTag);
+}
+
 export const searchSkills: ReturnType<typeof action> = action({
  args: {
    query: v.string(),
    limit: v.optional(v.number()),
    highlightedOnly: v.optional(v.boolean()),
    nonSuspiciousOnly: v.optional(v.boolean()),
+    capabilityTag: v.optional(v.string()),
  },
  handler: async (ctx, args): Promise<SearchResult[]> => {
    const query = args.query.trim();
    if (!query) return [];
+    if (args.capabilityTag && !SKILL_CAPABILITY_TAG_SET.has(args.capabilityTag)) return [];
    const queryTokens = tokenize(query);
    if (queryTokens.length === 0) return [];
-    const rawExactSlugMatch =
-      isSlugLikeQuery(query)
-        ? ((await ctx.runQuery(internal.search.getExactSkillSlugMatch, {
-            slug: query.toLowerCase(),
-            nonSuspiciousOnly: args.nonSuspiciousOnly,
-          })) as SkillSearchEntry | null)
-        : null;
+    const rawExactSlugMatch = isSlugLikeQuery(query)
+      ? ((await ctx.runQuery(internal.search.getExactSkillSlugMatch, {
+          slug: query.toLowerCase(),
+          nonSuspiciousOnly: args.nonSuspiciousOnly,
+        })) as SkillSearchEntry | null)
+      : null;
    const exactSlugMatch =
-      rawExactSlugMatch && (!args.highlightedOnly || isSkillHighlighted(rawExactSlugMatch.skill))
+      rawExactSlugMatch &&
+      (!args.highlightedOnly || isSkillHighlighted(rawExactSlugMatch.skill)) &&
+      matchesCapabilityTag(rawExactSlugMatch.skill, args.capabilityTag)
        ? rawExactSlugMatch
        : null;
    let vector: number[];
@@ -186,9 +199,11 @@ export const searchSkills: ReturnType<typeof action> = action({

      // Skills already have badges from their docs (via toPublicSkill).
      // No need for a separate badge table lookup.
-      const filtered = args.highlightedOnly
-        ? hydrated.filter((entry) => isSkillHighlighted(entry.skill))
-        : hydrated;
+      const filtered = hydrated.filter(
+        (entry) =>
+          (!args.highlightedOnly || isSkillHighlighted(entry.skill)) &&
+          matchesCapabilityTag(entry.skill, args.capabilityTag),
+      );

      exactMatches = filtered.filter((entry) =>
        matchesExactTokens(queryTokens, [
@@ -220,6 +235,7 @@ export const searchSkills: ReturnType<typeof action> = action({
            limit: Math.min(Math.max(limit * 4, 200), FALLBACK_SCAN_LIMIT),
            highlightedOnly: args.highlightedOnly,
            nonSuspiciousOnly: args.nonSuspiciousOnly,
+            capabilityTag: args.capabilityTag,
            skipExactSlugLookup: true,
          })) as SkillSearchEntry[]);
    const mergedMatches = mergeUniqueBySkillId(primaryMatches, fallbackMatches);
@@ -331,9 +347,11 @@ export const lexicalFallbackSkills = internalQuery({
    limit: v.optional(v.number()),
    highlightedOnly: v.optional(v.boolean()),
    nonSuspiciousOnly: v.optional(v.boolean()),
+    capabilityTag: v.optional(v.string()),
    skipExactSlugLookup: v.optional(v.boolean()),
  },
  handler: async (ctx, args): Promise<SkillSearchEntry[]> => {
+    if (args.capabilityTag && !SKILL_CAPABILITY_TAG_SET.has(args.capabilityTag)) return [];
    const limit = Math.min(Math.max(args.limit ?? 200, 10), FALLBACK_SCAN_LIMIT);
    const seenSkillIds = new Set<Id<"skills">>();
    const candidates: HydratableSkill[] = [];
@@ -353,7 +371,8 @@ export const lexicalFallbackSkills = internalQuery({
      if (
        exactSlugSkill &&
        !exactSlugSkill.softDeletedAt &&
-        (!args.nonSuspiciousOnly || !isSkillSuspicious(exactSlugSkill))
+        (!args.nonSuspiciousOnly || !isSkillSuspicious(exactSlugSkill)) &&
+        matchesCapabilityTag(exactSlugSkill, args.capabilityTag)
      ) {
        seenSkillIds.add(exactSlugSkill._id);
        candidates.push(exactSlugSkill);
@@ -371,6 +390,7 @@ export const lexicalFallbackSkills = internalQuery({
      if (seenSkillIds.has(digest.skillId)) continue;
      const skill = digestToHydratableSkill(digest);
      if (args.nonSuspiciousOnly && isSkillSuspicious(skill)) continue;
+      if (!matchesCapabilityTag(skill, args.capabilityTag)) continue;
      seenSkillIds.add(digest.skillId);
      candidates.push(skill);
      // Pre-resolve owner from digest to avoid users table reads.
@@ -23,6 +23,7 @@ import type { Doc, Id } from "./_generated/dataModel";
 import type { MutationCtx } from "./_generated/server";
 import { internalAction, internalMutation, internalQuery } from "./functions";
 import { applySkillStatDeltas, bumpDailySkillStats } from "./lib/skillStats";
+import { adjustUserSkillStatsForSkillChange } from "./lib/userSkillStats";

 /**
 * Event types that affect skill stats:
@@ -259,6 +260,7 @@ export const processSkillStatEventsInternal = internalMutation({
        // Don't update `updatedAt` — stat changes shouldn't move the
        // skill's position in the by_active_updated index.
        await ctx.db.patch(skill._id, patch);
+        await adjustUserSkillStatsForSkillChange(ctx, skill, { ...skill, ...patch });
      }

      // NOTE: Daily stats (skillDailyStats) are written by the 15-minute
@@ -0,0 +1,173 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@convex-dev/auth/server", () => ({
+  getAuthUserId: vi.fn(),
+  authTables: {},
+}));
+
+const { getAuthUserId } = await import("@convex-dev/auth/server");
+const { deleteTags } = await import("./skills");
+
+type WrappedHandler<TArgs, TResult = unknown> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>;
+};
+
+const deleteTagsHandler = (
+  deleteTags as unknown as WrappedHandler<{
+    skillId: string;
+    tags: string[];
+  }>
+)._handler;
+
+function buildGlobalStatsQuery(table: string) {
+  if (table !== "globalStats") return null;
+  return {
+    withIndex: () => ({
+      unique: async () => ({ _id: "globalStats:1", activeSkillsCount: 100 }),
+    }),
+  };
+}
+
+function buildDigestQuery(table: string) {
+  if (table !== "skillSearchDigest") return null;
+  return {
+    withIndex: () => ({
+      unique: async () => null,
+    }),
+  };
+}
+
+function makeCtx(params: { user: Record<string, unknown>; skill: Record<string, unknown> | null }) {
+  vi.mocked(getAuthUserId).mockResolvedValue(params.user._id as never);
+  const patch = vi.fn(async (_id: string, value: Record<string, unknown>) => value);
+  const db = {
+    get: vi.fn(async (id: string) => {
+      if (id === params.user._id) return params.user;
+      if (params.skill && id === params.skill._id) return params.skill;
+      return null;
+    }),
+    query: vi.fn((table: string) => {
+      const globalStatsQuery = buildGlobalStatsQuery(table);
+      if (globalStatsQuery) return globalStatsQuery;
+      const digestQuery = buildDigestQuery(table);
+      if (digestQuery) return digestQuery;
+      throw new Error(`unexpected table ${table}`);
+    }),
+    insert: vi.fn(),
+    patch,
+    delete: vi.fn(),
+    replace: vi.fn(),
+    normalizeId: vi.fn(() => null),
+  };
+  const auth = { getUserIdentity: vi.fn(async () => ({ tokenIdentifier: "test" })) };
+  return { db, auth, patch };
+}
+
+const ownerUser = {
+  _id: "users:owner",
+  deletedAt: undefined,
+  deactivatedAt: undefined,
+  role: undefined,
+};
+
+const modUser = {
+  _id: "users:mod",
+  deletedAt: undefined,
+  deactivatedAt: undefined,
+  role: "moderator",
+};
+
+const otherUser = {
+  _id: "users:other",
+  deletedAt: undefined,
+  deactivatedAt: undefined,
+  role: undefined,
+};
+
+const baseSkill = {
+  _id: "skills:1",
+  ownerUserId: "users:owner",
+  tags: {
+    latest: "versions:3",
+    stable: "versions:2",
+    beta: "versions:3",
+    "old-tag": "versions:1",
+  },
+  moderationStatus: "active",
+  moderationFlags: undefined,
+  softDeletedAt: undefined,
+};
+
+describe("deleteTags", () => {
+  beforeEach(() => {
+    vi.mocked(getAuthUserId).mockReset();
+  });
+
+  it("deletes specified tags and keeps latest", async () => {
+    const { db, auth, patch } = makeCtx({ user: ownerUser, skill: baseSkill });
+    await deleteTagsHandler(
+      { db, auth } as never,
+      { skillId: "skills:1", tags: ["stable", "old-tag"] } as never,
+    );
+    expect(patch).toHaveBeenCalledOnce();
+    const patchArgs = patch.mock.calls[0];
+    expect(patchArgs[1]).toHaveProperty("tags");
+    const newTags = (patchArgs[1] as Record<string, unknown>).tags as Record<string, string>;
+    expect(newTags).toHaveProperty("latest");
+    expect(newTags).toHaveProperty("beta");
+    expect(newTags).not.toHaveProperty("stable");
+    expect(newTags).not.toHaveProperty("old-tag");
+  });
+
+  it("protects the latest tag from deletion", async () => {
+    const { db, auth, patch } = makeCtx({ user: ownerUser, skill: baseSkill });
+    await deleteTagsHandler(
+      { db, auth } as never,
+      { skillId: "skills:1", tags: ["latest"] } as never,
+    );
+    // No actual tag removed → no db.patch call
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("skips db write when no tags are actually removed", async () => {
+    const { db, auth, patch } = makeCtx({ user: ownerUser, skill: baseSkill });
+    await deleteTagsHandler(
+      { db, auth } as never,
+      { skillId: "skills:1", tags: ["nonexistent", "latest"] } as never,
+    );
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("throws for non-owner non-moderator user", async () => {
+    const { db, auth } = makeCtx({ user: otherUser, skill: baseSkill });
+    await expect(
+      deleteTagsHandler({ db, auth } as never, { skillId: "skills:1", tags: ["stable"] } as never),
+    ).rejects.toThrow();
+  });
+
+  it("allows moderator to delete tags on other user's skill", async () => {
+    const { db, auth, patch } = makeCtx({ user: modUser, skill: baseSkill });
+    await deleteTagsHandler(
+      { db, auth } as never,
+      { skillId: "skills:1", tags: ["beta"] } as never,
+    );
+    expect(patch).toHaveBeenCalledOnce();
+    const newTags = (patch.mock.calls[0][1] as Record<string, unknown>).tags as Record<
+      string,
+      string
+    >;
+    expect(newTags).not.toHaveProperty("beta");
+    expect(newTags).toHaveProperty("latest");
+    expect(newTags).toHaveProperty("stable");
+  });
+
+  it("throws when skill not found", async () => {
+    const { db, auth } = makeCtx({ user: ownerUser, skill: null });
+    await expect(
+      deleteTagsHandler(
+        { db, auth } as never,
+        { skillId: "skills:missing", tags: ["stable"] } as never,
+      ),
+    ).rejects.toThrow("Skill not found");
+  });
+});
@@ -33,6 +33,7 @@ const listPackageCatalogPageHandler = (
        family: "skill";
        channel: "official" | "community";
        isOfficial: boolean;
+        capabilityTags: string[];
      }>;
      isDone: boolean;
      continueCursor: string;
@@ -79,6 +80,7 @@ function makeDigest(
      changelog: "init",
    },
    tags: { latest: `skillVersions:${slug}-1` },
+    capabilityTags: [],
    badges: {},
    stats: {
      downloads: 1,
@@ -103,8 +105,13 @@ function makeDigest(
  };
 }

-function makeCtx(pages: Array<{ page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }>) {
-  const pageByCursor = new Map<string | null, { page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }>();
+function makeCtx(
+  pages: Array<{ page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }>,
+) {
+  const pageByCursor = new Map<
+    string | null,
+    { page: Array<Record<string, unknown>>; isDone: boolean; continueCursor: string }
+  >();
  const allDigests = pages.flatMap((page) => page.page);
  let cursor: string | null = null;
  for (const page of pages) {
@@ -116,7 +123,12 @@ function makeCtx(pages: Array<{ page: Array<Record<string, unknown>>; isDone: bo
      query: (table: string) => {
        if (table === "skills") {
          return {
-            withIndex: (_index: string, builder: (q: { eq: (field: string, value: string) => { field: string; value: string } }) => { field: string; value: string }) => {
+            withIndex: (
+              _index: string,
+              builder: (q: {
+                eq: (field: string, value: string) => { field: string; value: string };
+              }) => { field: string; value: string },
+            ) => {
              const constraint = builder({ eq: (field, value) => ({ field, value }) });
              return {
                unique: async () => {
@@ -205,4 +217,48 @@ describe("skills package catalog queries", () => {
    });
    expect(result[0]?.score).toBeGreaterThan(0);
  });
+
+  it("filters skills by capability tag", async () => {
+    const result = await listPackageCatalogPageHandler(
+      makeCtx([
+        {
+          page: [
+            makeDigest("paytoll", { capabilityTags: ["crypto", "requires-wallet"] }),
+            makeDigest("weather"),
+          ],
+          isDone: true,
+          continueCursor: "",
+        },
+      ]),
+      {
+        capabilityTag: "crypto",
+        paginationOpts: { cursor: null, numItems: 10 },
+      },
+    );
+
+    expect(result.page).toEqual([
+      expect.objectContaining({
+        name: "paytoll",
+        capabilityTags: ["crypto", "requires-wallet"],
+      }),
+    ]);
+  });
+
+  it("returns empty immediately for unknown capability tags", async () => {
+    const result = await listPackageCatalogPageHandler(
+      makeCtx([
+        {
+          page: [makeDigest("paytoll", { capabilityTags: ["crypto", "requires-wallet"] })],
+          isDone: true,
+          continueCursor: "",
+        },
+      ]),
+      {
+        capabilityTag: "not-a-real-tag",
+        paginationOpts: { cursor: null, numItems: 10 },
+      },
+    );
+
+    expect(result).toEqual({ page: [], isDone: true, continueCursor: "" });
+  });
 });
@@ -5,7 +5,10 @@ vi.mock("@convex-dev/auth/server", () => ({
  authTables: {},
 }));

-import { getPendingScanSkillsInternal } from "./skills";
+import {
+  getActiveSkillBatchForStaticScanBackfillInternal,
+  getPendingScanSkillsInternal,
+} from "./skills";

 type PendingScanResult = Array<{
  skillId: string;
@@ -25,6 +28,17 @@ const getPendingScanSkillsHandler = (
  >
 )._handler;

+const getStaticScanBackfillBatchHandler = (
+  getActiveSkillBatchForStaticScanBackfillInternal as unknown as WrappedHandler<
+    Record<string, unknown>,
+    {
+      skills: Array<{ skillId: string; versionId: string; slug: string }>;
+      nextCursor: number;
+      done: boolean;
+    }
+  >
+)._handler;
+
 describe("skills.getPendingScanSkillsInternal", () => {
  it("includes unresolved VT records from the oldest slice and skips finalized ones", async () => {
    const recentSkills = [
@@ -215,6 +229,114 @@ describe("skills.getPendingScanSkillsInternal", () => {
  });
 });

+describe("skills.getActiveSkillBatchForStaticScanBackfillInternal", () => {
+  it("includes latest active skills with missing or stale static scan engine versions", async () => {
+    const skills = [
+      {
+        _id: "skills:missing-static",
+        _creationTime: 10,
+        softDeletedAt: undefined,
+        moderationStatus: "active",
+        latestVersionId: "skillVersions:missing-static",
+        slug: "missing-static",
+      },
+      {
+        _id: "skills:stale-static",
+        _creationTime: 20,
+        softDeletedAt: undefined,
+        moderationStatus: "active",
+        latestVersionId: "skillVersions:stale-static",
+        slug: "stale-static",
+      },
+      {
+        _id: "skills:current-static",
+        _creationTime: 30,
+        softDeletedAt: undefined,
+        moderationStatus: "active",
+        latestVersionId: "skillVersions:current-static",
+        slug: "current-static",
+      },
+      {
+        _id: "skills:hidden-static",
+        _creationTime: 40,
+        softDeletedAt: undefined,
+        moderationStatus: "hidden",
+        latestVersionId: "skillVersions:hidden-static",
+        slug: "hidden-static",
+      },
+    ];
+
+    const versions = new Map<string, unknown>([
+      ["skillVersions:missing-static", { _id: "skillVersions:missing-static" }],
+      [
+        "skillVersions:stale-static",
+        {
+          _id: "skillVersions:stale-static",
+          staticScan: { engineVersion: "v2.2.0" },
+        },
+      ],
+      [
+        "skillVersions:current-static",
+        {
+          _id: "skillVersions:current-static",
+          staticScan: { engineVersion: "v2.4.0" },
+        },
+      ],
+      [
+        "skillVersions:hidden-static",
+        {
+          _id: "skillVersions:hidden-static",
+          staticScan: { engineVersion: "v2.2.0" },
+        },
+      ],
+    ]);
+
+    const ctx = {
+      db: {
+        query: vi.fn((table: string) => {
+          if (table !== "skills") throw new Error(`unexpected table ${table}`);
+          return {
+            withIndex: (
+              indexName: string,
+              builder: (q: { gt: (field: string, value: unknown) => unknown }) => unknown,
+            ) => {
+              builder({ gt: () => ({}) });
+              if (indexName !== "by_creation_time") {
+                throw new Error(`unexpected index ${indexName}`);
+              }
+              return {
+                order: () => ({
+                  take: async () => skills,
+                }),
+              };
+            },
+          };
+        }),
+        get: vi.fn(async (id: string) => versions.get(id) ?? null),
+      },
+    };
+
+    const result = await getStaticScanBackfillBatchHandler(ctx, {
+      batchSize: 10,
+      cursor: 0,
+    });
+
+    expect(result.skills).toEqual([
+      {
+        skillId: "skills:missing-static",
+        versionId: "skillVersions:missing-static",
+        slug: "missing-static",
+      },
+      {
+        skillId: "skills:stale-static",
+        versionId: "skillVersions:stale-static",
+        slug: "stale-static",
+      },
+    ]);
+    expect(result.done).toBe(true);
+  });
+});
+
 function makeSkill(
  id: string,
  versionId: string,
@@ -35,6 +35,12 @@ const getBySlugHandler = (
        image: string | null;
        bio?: string | null;
      } | null;
+      latestVersion?: {
+        files?: Array<{
+          path: string;
+          contentType?: string;
+        }>;
+      } | null;
    } | null
  >
 )._handler;
@@ -171,4 +177,70 @@ describe("skills.getBySlug", () => {

    expect(result).toBeNull();
  });
+
+  it("normalizes misleading file MIME types in public version metadata", async () => {
+    const ctx = makeCtx({
+      skill: {
+        _id: "skills:1",
+        _creationTime: 1,
+        slug: "demo",
+        displayName: "Demo",
+        summary: "Public demo skill",
+        ownerUserId: "users:1",
+        canonicalSkillId: undefined,
+        forkOf: undefined,
+        latestVersionId: "skillVersions:1",
+        tags: {},
+        stats: {
+          downloads: 10,
+          installsCurrent: 2,
+          installsAllTime: 5,
+          stars: 3,
+          versions: 1,
+          comments: 0,
+        },
+        createdAt: 1,
+        updatedAt: 2,
+        moderationStatus: "active",
+        moderationFlags: undefined,
+        softDeletedAt: undefined,
+      },
+      owner: {
+        _id: "users:1",
+        _creationTime: 1,
+        handle: "demo-owner",
+        name: "Demo Owner",
+        displayName: "Demo Owner",
+        image: null,
+      },
+      latestVersion: {
+        _id: "skillVersions:1",
+        _creationTime: 2,
+        skillId: "skills:1",
+        version: "1.0.0",
+        fingerprint: "abc",
+        changelog: "",
+        changelogSource: "user",
+        files: [
+          {
+            path: "src/index.ts",
+            size: 10,
+            sha256: "deadbeef",
+            contentType: "video/mp2t",
+          },
+        ],
+        createdBy: "users:1",
+        createdAt: 2,
+      },
+    });
+
+    const result = await getBySlugHandler(ctx, { slug: "demo" } as never);
+
+    expect(result?.latestVersion?.files).toEqual([
+      expect.objectContaining({
+        path: "src/index.ts",
+        contentType: "application/typescript",
+      }),
+    ]);
+  });
 });
@@ -1,4 +1,5 @@
 import { getAuthUserId } from "@convex-dev/auth/server";
+import { normalizeTextContentType } from "clawhub-schema";
 import { getPage, type IndexKey, paginator } from "convex-helpers/server/pagination";
 import { paginationOptsValidator } from "convex/server";
 import { ConvexError, v, type Value } from "convex/values";
@@ -38,6 +39,7 @@ import { deriveModerationFlags } from "./lib/moderation";
 import { buildModerationSnapshot } from "./lib/moderationEngine";
 import {
  legacyFlagsFromVerdict,
+  MODERATION_ENGINE_VERSION,
  summarizeReasonCodes,
  verdictFromCodes,
 } from "./lib/moderationReasonCodes";
@@ -66,15 +68,23 @@ import {
  reserveSlugForHardDeleteFinalize,
  upsertReservedSlugForRightfulOwner,
 } from "./lib/reservedSlugs";
+import { SKILL_CAPABILITY_TAGS } from "./lib/skillCapabilityTags";
 import {
  fetchText,
  type PublishResult,
  publishVersionForUser,
  queueHighlightedWebhook,
 } from "./lib/skillPublish";
+import { runStaticPublishScan } from "./lib/staticPublishScan";
 import { getFrontmatterValue, hashSkillFiles } from "./lib/skills";
 import { computeIsSuspicious, isSkillSuspicious } from "./lib/skillSafety";
-import { digestToHydratableSkill, digestToOwnerInfo } from "./lib/skillSearchDigest";
+import {
+  digestToHydratableSkill,
+  digestToOwnerInfo,
+  extractDigestFields,
+  upsertSkillSearchDigest,
+} from "./lib/skillSearchDigest";
+import { adjustUserSkillStatsForSkillChange } from "./lib/userSkillStats";
 import schema from "./schema";

 export { publishVersionForUser } from "./lib/skillPublish";
@@ -111,6 +121,7 @@ const DEFAULT_STAFF_AUDIT_LOG_LIMIT = 10;
 const MAX_STAFF_AUDIT_LOG_LIMIT = 50;
 const USER_MODERATION_REASON = "user.moderation";
 const SKILL_CATALOG_CURSOR_PREFIX = "skillcat:";
+const SKILL_CAPABILITY_TAG_SET = new Set<string>(SKILL_CAPABILITY_TAGS);

 function buildStructuredModerationPatch(params: {
  staticScan?: Doc<"skillVersions">["staticScan"];
@@ -316,6 +327,8 @@ const NONSUSPICIOUS_SORT_INDEXES = {
  stars: "by_nonsuspicious_stars",
  installs: "by_nonsuspicious_installs",
 } as const;
+const MAX_FILTERED_PUBLIC_LIST_SCAN_PAGES = 12;
+const MAX_FILTERED_PUBLIC_LIST_SCAN_ROWS = 500;

 function isSkillVersionId(
  value: Id<"skillVersions"> | null | undefined,
@@ -450,7 +463,7 @@ async function syncSkillModerationFromLatestVersion(

 function buildConflictingSkillUrl(
  skill: Doc<"skills">,
-  owner: Doc<"users"> | Doc<"publishers"> | null | undefined,
+  owner: SkillOwnerRef,
 ) {
  if (!owner || owner.deletedAt || owner.deactivatedAt || !isPublicSkillDoc(skill)) return null;
  const ownerParam = owner.handle?.trim() || String(owner._id);
@@ -460,7 +473,7 @@ function buildConflictingSkillUrl(

 function buildSlugTakenErrorMessage(
  skill: Doc<"skills">,
-  owner: Doc<"users"> | Doc<"publishers"> | null | undefined,
+  owner: SkillOwnerRef,
 ) {
  if (!owner || owner.deletedAt || owner.deactivatedAt) {
    return (
@@ -476,7 +489,7 @@ function buildSlugTakenErrorMessage(

 function buildAliasTakenErrorMessage(
  skill: Doc<"skills">,
-  owner: Doc<"users"> | Doc<"publishers"> | null | undefined,
+  owner: SkillOwnerRef,
 ) {
  const base = "Slug redirects to an existing skill. Choose a different slug.";
  const url = buildConflictingSkillUrl(skill, owner);
@@ -488,6 +501,16 @@ function normalizeSkillSlugKey(slug: string) {
  return slug.trim().toLowerCase();
 }

+type SkillOwnerRef =
+  | {
+      _id: Id<"users"> | Id<"publishers">;
+      handle?: string | null;
+      deletedAt?: number | null;
+      deactivatedAt?: number | null;
+    }
+  | null
+  | undefined;
+
 function normalizeSkillSlugForWrite(slug: string) {
  const normalized = normalizeSkillSlugKey(slug);
  if (!normalized || !/^[a-z0-9][a-z0-9-]*$/.test(normalized)) {
@@ -736,6 +759,7 @@ async function hardDeleteSkillStep(
    const nextSkill = { ...skill, ...patch };
    await ctx.db.patch(skill._id, patch);
    await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+    await adjustUserSkillStatsForSkillChange(ctx, skill, nextSkill);
  }

  switch (phase) {
@@ -1041,6 +1065,7 @@ type PublicSkillVersion = {
  createdBy?: Id<"users">;
  createdAt?: number;
  softDeletedAt?: number;
+  capabilityTags?: string[];
  sha256hash?: string;
  vtAnalysis?: Doc<"skillVersions">["vtAnalysis"];
  llmAnalysis?: Doc<"skillVersions">["llmAnalysis"];
@@ -1207,7 +1232,7 @@ function toPublicSkillVersion(
      path: file.path,
      size: file.size,
      sha256: file.sha256,
-      contentType: file.contentType,
+      contentType: normalizeTextContentType(file.path, file.contentType),
    })),
    parsed: version.parsed
      ? {
@@ -1218,6 +1243,7 @@ function toPublicSkillVersion(
    createdBy: version.createdBy,
    createdAt: version.createdAt,
    softDeletedAt: version.softDeletedAt,
+    capabilityTags: version.capabilityTags,
    sha256hash: version.sha256hash,
    vtAnalysis: version.vtAnalysis,
    llmAnalysis: version.llmAnalysis,
@@ -2069,7 +2095,8 @@ export const list = query({
          )
          .unique());
      const isOwnDashboard = Boolean(
-        membership || (userId && ownerPublisher?.kind === "user" && ownerPublisher.linkedUserId === userId),
+        membership ||
+        (userId && ownerPublisher?.kind === "user" && ownerPublisher.linkedUserId === userId),
      );
      const scopedEntries = await ctx.db
        .query("skills")
@@ -2504,6 +2531,7 @@ export const report = mutation({
    const nextSkill = { ...skill, ...updates };
    await ctx.db.patch(skill._id, updates);
    await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+    await adjustUserSkillStatsForSkillChange(ctx, skill, nextSkill);

    if (shouldAutoHide) {
      await setSkillEmbeddingsSoftDeleted(ctx, skill._id, true, now);
@@ -2684,8 +2712,12 @@ export const listPublicPageV4 = query({
    dir: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
    highlightedOnly: v.optional(v.boolean()),
    nonSuspiciousOnly: v.optional(v.boolean()),
+    capabilityTag: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
+    if (args.capabilityTag && !isKnownSkillCapabilityTag(args.capabilityTag)) {
+      return { page: [], hasMore: false, nextCursor: null };
+    }
    const sort = args.sort ?? "newest";
    const dir = args.dir ?? (sort === "name" ? "asc" : "desc");
    const numItems = clampInt(args.numItems ?? 25, 1, MAX_PUBLIC_LIST_LIMIT);
@@ -2698,6 +2730,7 @@ export const listPublicPageV4 = query({
        sort,
        dir,
        numItems,
+        capabilityTag: args.capabilityTag,
        nonSuspiciousOnly: args.nonSuspiciousOnly ?? false,
      });
    }
@@ -2714,46 +2747,113 @@ export const listPublicPageV4 = query({
    const isFirstPage = !decodedCursor;
    const startIndexKey: IndexKey = decodedCursor ?? eqPrefix;

-    const result = await getPage(ctx, {
-      table: "skillSearchDigest",
-      startIndexKey,
-      startInclusive: isFirstPage,
-      endIndexKey: eqPrefix,
-      endInclusive: true,
-      absoluteMaxRows: numItems,
-      order: dir,
-      index: indexName,
-      schema,
-    });
-
-    // Build PublicSkillEntry[] from digests
-    const items: PublicSkillEntry[] = [];
-    for (const digest of result.page) {
-      const hydratable = digestToHydratableSkill(digest);
-      const publicSkill = toPublicSkill(hydratable);
-      if (!publicSkill) continue;
-      const ownerInfo = digestToOwnerInfo(digest);
-      if (!ownerInfo?.owner) continue;
-      const latestVersion = digest.latestVersionSummary
-        ? toPublicSkillListVersionFromSummary(digest.latestVersionSummary, digest.latestVersionId)
-        : null;
-      items.push({
-        skill: publicSkill,
-        latestVersion,
-        ownerHandle: ownerInfo.ownerHandle,
-        owner: ownerInfo.owner,
+    if (!args.capabilityTag) {
+      const result = await getPage(ctx, {
+        table: "skillSearchDigest",
+        startIndexKey,
+        startInclusive: isFirstPage,
+        endIndexKey: eqPrefix,
+        endInclusive: true,
+        absoluteMaxRows: numItems,
+        order: dir,
+        index: indexName,
+        schema,
      });
+
+      const items = result.page
+        .map((digest) => buildPublicSkillEntryFromDigest(digest))
+        .filter((item): item is PublicSkillEntry => item !== null);
+      let nextCursor: string | null = null;
+      if (result.hasMore && result.indexKeys.length > 0) {
+        nextCursor = encodeIndexKey(result.indexKeys[result.indexKeys.length - 1]);
+      }
+
+      return { page: items, hasMore: result.hasMore, nextCursor };
    }

+    const items: PublicSkillEntry[] = [];
+    let scanCursor = startIndexKey;
+    let scanInclusive = isFirstPage;
+    let hasMore = false;
    let nextCursor: string | null = null;
-    if (result.hasMore && result.indexKeys.length > 0) {
-      nextCursor = encodeIndexKey(result.indexKeys[result.indexKeys.length - 1]);
+    let remainingRows = Math.max(numItems, Math.min(MAX_FILTERED_PUBLIC_LIST_SCAN_ROWS, numItems * 12));
+
+    for (let pageCount = 0; pageCount < MAX_FILTERED_PUBLIC_LIST_SCAN_PAGES; pageCount += 1) {
+      if (remainingRows <= 0) break;
+      const batchSize = Math.min(remainingRows, Math.max(numItems * 3, numItems));
+      const result = await getPage(ctx, {
+        table: "skillSearchDigest",
+        startIndexKey: scanCursor,
+        startInclusive: scanInclusive,
+        endIndexKey: eqPrefix,
+        endInclusive: true,
+        absoluteMaxRows: batchSize,
+        order: dir,
+        index: indexName,
+        schema,
+      });
+      remainingRows -= batchSize;
+      if (result.indexKeys.length === 0) {
+        hasMore = false;
+        nextCursor = null;
+        break;
+      }
+
+      for (let index = 0; index < result.page.length; index += 1) {
+        const digest = result.page[index];
+        const cursor = result.indexKeys[index];
+        if ((digest.capabilityTags ?? []).includes(args.capabilityTag)) {
+          const item = buildPublicSkillEntryFromDigest(digest);
+          if (item) items.push(item);
+        }
+        if (items.length >= numItems) {
+          hasMore = result.hasMore || index < result.page.length - 1;
+          nextCursor = hasMore ? encodeIndexKey(cursor) : null;
+          return { page: items, hasMore, nextCursor };
+        }
+      }
+
+      if (!result.hasMore) {
+        hasMore = false;
+        nextCursor = null;
+        break;
+      }
+
+      scanCursor = result.indexKeys[result.indexKeys.length - 1];
+      scanInclusive = false;
+      hasMore = true;
+      nextCursor = encodeIndexKey(scanCursor);
    }

-    return { page: items, hasMore: result.hasMore, nextCursor };
+    // Guard: never signal more pages when the scan budget is exhausted
+    // without finding any items — that would cause the client's
+    // IntersectionObserver auto-load to loop on empty responses.
+    if (items.length === 0) {
+      hasMore = false;
+      nextCursor = null;
+    }
+
+    return { page: items, hasMore, nextCursor };
  },
 });

+function buildPublicSkillEntryFromDigest(digest: Doc<"skillSearchDigest">): PublicSkillEntry | null {
+  const hydratable = digestToHydratableSkill(digest);
+  const publicSkill = toPublicSkill(hydratable);
+  if (!publicSkill) return null;
+  const ownerInfo = digestToOwnerInfo(digest);
+  if (!ownerInfo?.owner) return null;
+  const latestVersion = digest.latestVersionSummary
+    ? toPublicSkillListVersionFromSummary(digest.latestVersionSummary, digest.latestVersionId)
+    : null;
+  return {
+    skill: publicSkill,
+    latestVersion,
+    ownerHandle: ownerInfo.ownerHandle,
+    owner: ownerInfo.owner,
+  };
+}
+
 type PublicSkillCatalogItem = {
  name: string;
  displayName: string;
@@ -2789,12 +2889,13 @@ function decodeSkillCatalogCursor(raw: string | null | undefined): SkillCatalogC
    return { cursor: raw, offset: 0, pageSize: null, done: false };
  }
  try {
-    const parsed = JSON.parse(raw.slice(SKILL_CATALOG_CURSOR_PREFIX.length)) as Partial<SkillCatalogCursorState>;
+    const parsed = JSON.parse(
+      raw.slice(SKILL_CATALOG_CURSOR_PREFIX.length),
+    ) as Partial<SkillCatalogCursorState>;
    return {
      cursor: typeof parsed.cursor === "string" ? parsed.cursor : null,
      offset: typeof parsed.offset === "number" && parsed.offset > 0 ? parsed.offset : 0,
-      pageSize:
-        typeof parsed.pageSize === "number" && parsed.pageSize > 0 ? parsed.pageSize : null,
+      pageSize: typeof parsed.pageSize === "number" && parsed.pageSize > 0 ? parsed.pageSize : null,
      done: parsed.done === true,
    };
  } catch {
@@ -2828,12 +2929,13 @@ function skillCatalogMatchesFilters(
 ) {
  if (!isVisibleSkillCatalogDigest(digest)) return false;
  if (args.channel === "private") return false;
-  if (args.capabilityTag) return false;
  if (args.executesCode === true) return false;
  const isOfficial = isSkillCatalogOfficial(digest);
  const channel = getSkillCatalogChannel(digest);
  if (typeof args.isOfficial === "boolean" && isOfficial !== args.isOfficial) return false;
  if (args.channel && channel !== args.channel) return false;
+  if (args.capabilityTag && !(digest.capabilityTags ?? []).includes(args.capabilityTag))
+    return false;
  return true;
 }

@@ -2851,7 +2953,7 @@ function toPublicSkillCatalogItem(digest: Doc<"skillSearchDigest">): PublicSkill
    createdAt: digest.createdAt,
    updatedAt: digest.updatedAt,
    latestVersion: digest.latestVersionSummary?.version ?? null,
-    capabilityTags: [],
+    capabilityTags: digest.capabilityTags ?? [],
    executesCode: false,
    verificationTier: null,
  };
@@ -2876,16 +2978,25 @@ function scoreSkillCatalogResult(digest: Doc<"skillSearchDigest">, queryText: st
  return score;
 }

+function isKnownSkillCapabilityTag(tag: string | undefined) {
+  return typeof tag === "string" && SKILL_CAPABILITY_TAG_SET.has(tag);
+}
+
 export const listPackageCatalogPage = query({
  args: {
-    channel: v.optional(v.union(v.literal("official"), v.literal("community"), v.literal("private"))),
+    channel: v.optional(
+      v.union(v.literal("official"), v.literal("community"), v.literal("private")),
+    ),
    isOfficial: v.optional(v.boolean()),
    executesCode: v.optional(v.boolean()),
    capabilityTag: v.optional(v.string()),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
-    if (args.channel === "private" || args.executesCode === true || args.capabilityTag) {
+    if (args.capabilityTag && !isKnownSkillCapabilityTag(args.capabilityTag)) {
+      return { page: [], isDone: true, continueCursor: "" };
+    }
+    if (args.channel === "private" || args.executesCode === true) {
      return { page: [], isDone: true, continueCursor: "" };
    }

@@ -2908,7 +3019,9 @@ export const listPackageCatalogPage = query({
      loops += 1;
      const effectivePageSize = Math.min(
        remainingScanBudget,
-        offset > 0 && pageSize ? Math.max(pageSize, offset + 1) : Math.max(targetCount * 3, targetCount),
+        offset > 0 && pageSize
+          ? Math.max(pageSize, offset + 1)
+          : Math.max(targetCount * 3, targetCount),
      );
      if (effectivePageSize <= 0) break;
      remainingScanBudget -= effectivePageSize;
@@ -2962,7 +3075,9 @@ export const searchPackageCatalogPublic = query({
  args: {
    query: v.string(),
    limit: v.optional(v.number()),
-    channel: v.optional(v.union(v.literal("official"), v.literal("community"), v.literal("private"))),
+    channel: v.optional(
+      v.union(v.literal("official"), v.literal("community"), v.literal("private")),
+    ),
    isOfficial: v.optional(v.boolean()),
    executesCode: v.optional(v.boolean()),
    capabilityTag: v.optional(v.string()),
@@ -2970,7 +3085,8 @@ export const searchPackageCatalogPublic = query({
  handler: async (ctx, args) => {
    const queryText = args.query.trim().toLowerCase();
    if (!queryText) return [];
-    if (args.channel === "private" || args.executesCode === true || args.capabilityTag) return [];
+    if (args.capabilityTag && !isKnownSkillCapabilityTag(args.capabilityTag)) return [];
+    if (args.channel === "private" || args.executesCode === true) return [];

    const targetCount = Math.max(1, Math.min(args.limit ?? 20, 100));
    const matches: Array<{ score: number; package: PublicSkillCatalogItem }> = [];
@@ -3034,6 +3150,7 @@ async function fetchHighlightedPage(
    sort: SortKey;
    dir: "asc" | "desc";
    numItems: number;
+    capabilityTag?: string;
    nonSuspiciousOnly: boolean;
  },
 ) {
@@ -3053,6 +3170,7 @@ async function fetchHighlightedPage(
      .unique();
    if (!digest || digest.softDeletedAt) continue;
    if (opts.nonSuspiciousOnly && digest.isSuspicious) continue;
+    if (opts.capabilityTag && !(digest.capabilityTags ?? []).includes(opts.capabilityTag)) continue;
    digests.push(digest);
  }

@@ -3079,23 +3197,9 @@ async function fetchHighlightedPage(
  const trimmed = digests.slice(0, opts.numItems);

  // Build PublicSkillEntry[]
-  const items: PublicSkillEntry[] = [];
-  for (const digest of trimmed) {
-    const hydratable = digestToHydratableSkill(digest);
-    const publicSkill = toPublicSkill(hydratable);
-    if (!publicSkill) continue;
-    const ownerInfo = digestToOwnerInfo(digest);
-    if (!ownerInfo?.owner) continue;
-    const latestVersion = digest.latestVersionSummary
-      ? toPublicSkillListVersionFromSummary(digest.latestVersionSummary, digest.latestVersionId)
-      : null;
-    items.push({
-      skill: publicSkill,
-      latestVersion,
-      ownerHandle: ownerInfo.ownerHandle,
-      owner: ownerInfo.owner,
-    });
-  }
+  const items = trimmed
+    .map((digest) => buildPublicSkillEntryFromDigest(digest))
+    .filter((item): item is PublicSkillEntry => item !== null);

  // Highlighted skills are few enough to return in one page — no cursor needed
  return { page: items, hasMore: false, nextCursor: null };
@@ -3595,6 +3699,56 @@ export const getActiveSkillBatchForLlmBackfillInternal = internalQuery({
  },
 });

+/**
+ * Get active latest skill versions whose static scan is missing or uses an older engine version.
+ * Used to backfill new static rules onto already-published skills.
+ */
+export const getActiveSkillBatchForStaticScanBackfillInternal = internalQuery({
+  args: {
+    cursor: v.optional(v.number()),
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const batchSize = args.batchSize ?? 25;
+    const cursor = args.cursor ?? 0;
+
+    const candidates = await ctx.db
+      .query("skills")
+      .withIndex("by_creation_time", (q) => q.gt("_creationTime", cursor))
+      .order("asc")
+      .take(batchSize * 4);
+
+    const results: Array<{
+      skillId: Id<"skills">;
+      versionId: Id<"skillVersions">;
+      slug: string;
+    }> = [];
+    let nextCursor = cursor;
+
+    for (const skill of candidates) {
+      nextCursor = skill._creationTime;
+      if (results.length >= batchSize) break;
+
+      if (skill.softDeletedAt) continue;
+      if ((skill.moderationStatus ?? "active") !== "active") continue;
+      if (!skill.latestVersionId) continue;
+
+      const version = await ctx.db.get(skill.latestVersionId);
+      if (!version) continue;
+      if (version.staticScan?.engineVersion === MODERATION_ENGINE_VERSION) continue;
+
+      results.push({
+        skillId: skill._id,
+        versionId: version._id,
+        slug: skill.slug,
+      });
+    }
+
+    const done = candidates.length < batchSize * 4;
+    return { skills: results, nextCursor, done };
+  },
+});
+
 /**
 * Get skills with stale moderationReason that have vtAnalysis cached.
 * Used to sync moderationReason with cached VT results.
@@ -3693,6 +3847,159 @@ export const getPendingVTSkillsInternal = internalQuery({
  },
 });

+export const updateSkillVersionStaticScanInternal = internalMutation({
+  args: {
+    skillId: v.id("skills"),
+    versionId: v.id("skillVersions"),
+    staticScan: v.object({
+      status: v.union(v.literal("clean"), v.literal("suspicious"), v.literal("malicious")),
+      reasonCodes: v.array(v.string()),
+      findings: v.array(
+        v.object({
+          code: v.string(),
+          severity: v.union(v.literal("info"), v.literal("warn"), v.literal("critical")),
+          file: v.string(),
+          line: v.number(),
+          message: v.string(),
+          evidence: v.string(),
+        }),
+      ),
+      summary: v.string(),
+      engineVersion: v.string(),
+      checkedAt: v.number(),
+    }),
+  },
+  handler: async (ctx, args) => {
+    const version = await ctx.db.get(args.versionId);
+    if (!version || version.skillId !== args.skillId) return { ok: true as const, skipped: "missing" as const };
+
+    await ctx.db.patch(version._id, {
+      staticScan: args.staticScan,
+    });
+
+    const skill = await ctx.db.get(args.skillId);
+    if (!skill) return { ok: true as const, skipped: "missing" as const };
+    if (skill.latestVersionId !== version._id) {
+      return { ok: true as const, skipped: "not_latest" as const };
+    }
+
+    const owner = skill.ownerUserId ? await ctx.db.get(skill.ownerUserId) : null;
+    const now = Date.now();
+    const updatedVersion = { ...version, staticScan: args.staticScan };
+    const basePatch = buildScannerModerationPatchFromVersion({
+      owner,
+      version: updatedVersion,
+      now,
+    });
+    const patch = applySkillManualOverrideToSkillPatch({
+      skill,
+      basePatch: {
+        ...basePatch,
+        updatedAt: now,
+      },
+      now,
+    });
+    const nextSkill = { ...skill, ...patch };
+    await ctx.db.patch(skill._id, patch);
+    await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+
+    if (patch.moderationVerdict === "malicious" && skill.ownerUserId) {
+      await ctx.scheduler.runAfter(0, internal.users.placeUserUnderModerationInternal, {
+        ownerUserId: skill.ownerUserId,
+        slug: skill.slug,
+        reason:
+          patch.moderationReasonCodes?.find((code) => code.startsWith("malicious.")) ??
+          "malicious.static_scan",
+      });
+    }
+
+    return { ok: true as const, status: args.staticScan.status };
+  },
+});
+
+export const scanSkillVersionStaticallyInternal: ReturnType<typeof internalAction> = internalAction({
+  args: {
+    skillId: v.id("skills"),
+    versionId: v.id("skillVersions"),
+  },
+  handler: async (ctx, args) => {
+    const [skill, version] = await Promise.all([
+      ctx.runQuery(internal.skills.getSkillByIdInternal, { skillId: args.skillId }),
+      ctx.runQuery(internal.skills.getVersionByIdInternal, { versionId: args.versionId }),
+    ]);
+
+    if (!skill || !version) {
+      return { ok: true as const, skipped: "missing" as const };
+    }
+
+    const staticScan = await runStaticPublishScan(ctx, {
+      slug: skill.slug,
+      displayName: skill.displayName,
+      summary: skill.summary ?? undefined,
+      frontmatter: version.parsed?.frontmatter ?? {},
+      metadata: version.parsed?.metadata,
+      files: version.files,
+    });
+
+    return await ctx.runMutation(internal.skills.updateSkillVersionStaticScanInternal, {
+      skillId: skill._id,
+      versionId: version._id,
+      staticScan,
+    });
+  },
+});
+
+export const backfillSkillStaticScansInternal: ReturnType<typeof internalAction> = internalAction({
+  args: {
+    cursor: v.optional(v.number()),
+    batchSize: v.optional(v.number()),
+    rescanned: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const batchSize = Math.max(1, Math.min(args.batchSize ?? 25, 100));
+    const batch = await ctx.runQuery(internal.skills.getActiveSkillBatchForStaticScanBackfillInternal, {
+      cursor: args.cursor,
+      batchSize,
+    });
+
+    let rescanned = args.rescanned ?? 0;
+    for (const skill of batch.skills) {
+      await ctx.scheduler.runAfter(0, internal.skills.scanSkillVersionStaticallyInternal, {
+        skillId: skill.skillId,
+        versionId: skill.versionId,
+      });
+      rescanned += 1;
+    }
+
+    if (!batch.done) {
+      await ctx.scheduler.runAfter(0, internal.skills.backfillSkillStaticScansInternal, {
+        cursor: batch.nextCursor,
+        batchSize,
+        rescanned,
+      });
+    }
+
+    return {
+      rescanned,
+      nextCursor: batch.nextCursor,
+      done: batch.done,
+    };
+  },
+});
+
+export const backfillSkillStaticScans: ReturnType<typeof action> = action({
+  args: {
+    batchSize: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { user } = await requireUserFromAction(ctx);
+    assertAdmin(user);
+    return await ctx.runAction(internal.skills.backfillSkillStaticScansInternal, {
+      batchSize: args.batchSize,
+    });
+  },
+});
+
 /**
 * Emergency escalation by skillId for legacy rows without sha256hash.
 * Rebuilds the full moderation snapshot so legacy rows stay in sync with structured fields.
@@ -3951,6 +4258,7 @@ export const applyBanToOwnedSkillsBatchInternal = internalMutation({
      const nextSkill = { ...skill, ...patch };
      await ctx.db.patch(skill._id, patch);
      await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+      await adjustUserSkillStatsForSkillChange(ctx, skill, nextSkill);
      await setSkillEmbeddingsSoftDeleted(ctx, skill._id, true, args.bannedAt);
    }

@@ -4062,6 +4370,7 @@ export const restoreOwnedSkillsForUnbanBatchInternal = internalMutation({
      const nextSkill = { ...skill, ...patch };
      await ctx.db.patch(skill._id, patch);
      await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+      await adjustUserSkillStatsForSkillChange(ctx, skill, nextSkill);

      await setSkillEmbeddingsSoftDeleted(ctx, skill._id, false, now);
      restoredCount += 1;
@@ -4741,6 +5050,7 @@ export const updateTags = mutation({
          changelogSource: version.changelogSource,
          clawdis: version.parsed?.clawdis,
        };
+        patch.capabilityTags = version.capabilityTags;
      }
    }

@@ -4764,6 +5074,38 @@ export const updateTags = mutation({
  },
 });

+export const deleteTags = mutation({
+  args: {
+    skillId: v.id("skills"),
+    tags: v.array(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const { user } = await requireUser(ctx);
+    const skill = await ctx.db.get(args.skillId);
+    if (!skill) throw new Error("Skill not found");
+    if (skill.ownerUserId !== user._id) {
+      assertModerator(user);
+    }
+
+    const nextTags = { ...skill.tags };
+    let changed = false;
+    for (const tag of args.tags) {
+      if (tag === "latest") continue; // protect the latest tag from deletion
+      if (tag in nextTags) {
+        delete nextTags[tag];
+        changed = true;
+      }
+    }
+
+    if (!changed) return;
+
+    await ctx.db.patch(skill._id, {
+      tags: nextTags,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
 export const setRedactionApproved = mutation({
  args: { skillId: v.id("skills"), approved: v.boolean() },
  handler: async (ctx, args) => {
@@ -4938,7 +5280,11 @@ export const clearSkillManualOverride = mutation({
 });

 export const setSoftDeleted = mutation({
-  args: { skillId: v.id("skills"), deleted: v.boolean() },
+  args: {
+    skillId: v.id("skills"),
+    deleted: v.boolean(),
+    reason: v.optional(v.string()),
+  },
  handler: async (ctx, args) => {
    const { user } = await requireUser(ctx);
    assertModerator(user);
@@ -4946,9 +5292,16 @@ export const setSoftDeleted = mutation({
    if (!skill) throw new Error("Skill not found");

    const now = Date.now();
+    const note = args.reason ? trimManualOverrideNote(args.reason) : undefined;
+    if (!note) {
+      throw new ConvexError(
+        args.deleted ? "Hide reason is required." : "Restore reason is required.",
+      );
+    }
    const patch: Partial<Doc<"skills">> = {
      softDeletedAt: args.deleted ? now : undefined,
      moderationStatus: args.deleted ? "hidden" : "active",
+      moderationNotes: note,
      hiddenAt: args.deleted ? now : undefined,
      hiddenBy: args.deleted ? user._id : undefined,
      lastReviewedAt: now,
@@ -4957,6 +5310,7 @@ export const setSoftDeleted = mutation({
    const nextSkill = { ...skill, ...patch };
    await ctx.db.patch(skill._id, patch);
    await adjustGlobalPublicCountForSkillChange(ctx, skill, nextSkill);
+    await adjustUserSkillStatsForSkillChange(ctx, skill, nextSkill);

    await setSkillEmbeddingsSoftDeleted(ctx, skill._id, args.deleted, now);

@@ -4965,7 +5319,11 @@ export const setSoftDeleted = mutation({
      action: args.deleted ? "skill.delete" : "skill.undelete",
      targetType: "skill",
      targetId: skill._id,
-      metadata: { slug: skill.slug, softDeletedAt: args.deleted ? now : null },
+      metadata: {
+        slug: skill.slug,
+        softDeletedAt: args.deleted ? now : null,
+        reason: note,
+      },
      createdAt: now,
    });
  },
@@ -4991,6 +5349,7 @@ export const changeOwner = mutation({
      lastReviewedAt: now,
      updatedAt: now,
    });
+    await adjustUserSkillStatsForSkillChange(ctx, skill, { ...skill, ownerUserId: args.ownerUserId });

    const embeddings = await listSkillEmbeddingsForSkill(ctx, skill._id);
    for (const embedding of embeddings) {
@@ -5644,6 +6003,72 @@ export const setDeprecatedBadge = mutation({
  },
 });

+export const setSkillCapabilityTags = mutation({
+  args: { skillId: v.id("skills"), capabilityTags: v.array(v.string()) },
+  handler: async (ctx, args) => {
+    const { user } = await requireUser(ctx);
+    assertModerator(user);
+
+    const skill = await ctx.db.get(args.skillId);
+    if (!skill) throw new Error("Skill not found");
+
+    const invalidTags = args.capabilityTags.filter(
+      (tag) => !SKILL_CAPABILITY_TAGS.includes(tag as (typeof SKILL_CAPABILITY_TAGS)[number]),
+    );
+    if (invalidTags.length > 0) {
+      throw new ConvexError(`Unknown capability tags: ${invalidTags.join(", ")}`);
+    }
+
+    const selectedTags = new Set(args.capabilityTags);
+    const normalizedTags = SKILL_CAPABILITY_TAGS.filter((tag) => selectedTags.has(tag));
+    const now = Date.now();
+
+    if (skill.latestVersionId) {
+      const latestVersion = await ctx.db.get(skill.latestVersionId);
+      if (latestVersion) {
+        await ctx.db.patch(latestVersion._id, {
+          capabilityTags: normalizedTags.length ? normalizedTags : undefined,
+        });
+      }
+    }
+
+    const nextSkill = {
+      ...skill,
+      capabilityTags: normalizedTags.length ? normalizedTags : undefined,
+      lastReviewedAt: now,
+      updatedAt: now,
+    };
+
+    await ctx.db.patch(skill._id, {
+      capabilityTags: nextSkill.capabilityTags,
+      lastReviewedAt: now,
+      updatedAt: now,
+    });
+
+    const owner = await getOwnerPublisher(ctx, {
+      ownerPublisherId: nextSkill.ownerPublisherId,
+      ownerUserId: nextSkill.ownerUserId,
+    });
+    await upsertSkillSearchDigest(ctx, {
+      ...extractDigestFields(nextSkill),
+      ownerHandle: owner?.handle ?? "",
+      ownerKind: owner?.kind,
+      ownerName: owner?.linkedUserId ? owner.handle : undefined,
+      ownerDisplayName: owner?.displayName,
+      ownerImage: owner?.image,
+    });
+
+    await ctx.db.insert("auditLogs", {
+      actorUserId: user._id,
+      action: "skill.capability_tags.set",
+      targetType: "skill",
+      targetId: skill._id,
+      metadata: { capabilityTags: normalizedTags },
+      createdAt: now,
+    });
+  },
+});
+
 export const hardDelete = mutation({
  args: { skillId: v.id("skills") },
  handler: async (ctx, args) => {
@@ -5705,6 +6130,7 @@ export const insertVersion = internalMutation({
      clawdis: v.optional(v.any()),
      license: v.optional(v.literal(PLATFORM_SKILL_LICENSE)),
    }),
+    capabilityTags: v.optional(v.array(v.string())),
    summary: v.optional(v.string()),
    qualityAssessment: v.optional(
      v.object({
@@ -5956,6 +6382,7 @@ export const insertVersion = internalMutation({
        forkOf,
        latestVersionId: undefined,
        tags: {},
+        capabilityTags: args.capabilityTags,
        softDeletedAt: undefined,
        badges: {
          redactionApproved: undefined,
@@ -6003,6 +6430,7 @@ export const insertVersion = internalMutation({
        // Digest sync is handled after the version patch below (line ~4222),
        // which captures the final state including latestVersionId and tags.
        await adjustGlobalPublicCountForSkillChange(ctx, null, skill);
+        await adjustUserSkillStatsForSkillChange(ctx, null, skill);
      }
    }

@@ -6024,6 +6452,7 @@ export const insertVersion = internalMutation({
      changelogSource: args.changelogSource,
      files: args.files,
      parsed: args.parsed,
+      capabilityTags: args.capabilityTags,
      staticScan: args.staticScan,
      createdBy: userId,
      createdAt: now,
@@ -6069,6 +6498,7 @@ export const insertVersion = internalMutation({
        clawdis: args.parsed.clawdis,
      },
      tags: nextTags,
+      capabilityTags: args.capabilityTags,
      stats: { ...skill.stats, versions: skill.stats.versions + 1 },
      softDeletedAt: undefined,
      moderationStatus: initialModerationStatus,
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { getSoulBySlugInternal, insertVersion } from "./souls";
+import { getSoulBySlugInternal, insertVersion, list } from "./souls";

 type WrappedHandler<TArgs> = {
  _handler: (ctx: unknown, args: TArgs) => Promise<unknown>;
@@ -10,6 +10,7 @@ const insertVersionHandler = (insertVersion as unknown as WrappedHandler<Record<
 const getSoulBySlugInternalHandler = (
  getSoulBySlugInternal as unknown as WrappedHandler<{ slug: string }>
 )._handler;
+const listHandler = (list as unknown as WrappedHandler<{ ownerUserId?: string; limit?: number }>)._handler;

 describe("souls.insertVersion", () => {
  it("throws a soul-specific ownership error for non-owners", async () => {
@@ -23,7 +24,10 @@ describe("souls.insertVersion", () => {
      query: vi.fn((table: string) => {
        if (table !== "souls") throw new Error(`unexpected table ${table}`);
        return {
-          withIndex: (name: string, build: ((q: { eq: (field: string, value: string) => unknown }) => unknown) | undefined) => {
+          withIndex: (
+            name: string,
+            build: ((q: { eq: (field: string, value: string) => unknown }) => unknown) | undefined,
+          ) => {
            if (name !== "by_slug") throw new Error(`unexpected index ${name}`);
            const q = {
              eq: (field: string, value: string) => {
@@ -92,7 +96,12 @@ describe("souls.insertVersion", () => {
          query: vi.fn((table: string) => {
            if (table !== "souls") throw new Error(`unexpected table ${table}`);
            return {
-              withIndex: (name: string, build: ((q: { eq: (field: string, value: string) => unknown }) => unknown) | undefined) => {
+              withIndex: (
+                name: string,
+                build:
+                  | ((q: { eq: (field: string, value: string) => unknown }) => unknown)
+                  | undefined,
+              ) => {
                if (name !== "by_slug") throw new Error(`unexpected index ${name}`);
                const q = {
                  eq: (field: string, value: string) => {
@@ -131,3 +140,75 @@ describe("souls.insertVersion", () => {
    );
  });
 });
+
+describe("souls.list", () => {
+  it("uses the active browse index and only takes the requested limit", async () => {
+    let requestedIndex: string | null = null;
+    let requestedSoftDeletedAt: number | undefined;
+    let requestedLimit: number | null = null;
+
+    const result = await listHandler(
+      {
+        db: {
+          query: vi.fn((table: string) => {
+            if (table !== "souls") throw new Error(`unexpected table ${table}`);
+            return {
+              withIndex: (
+                name: string,
+                build:
+                  | ((q: { eq: (field: string, value: undefined) => unknown }) => unknown)
+                  | undefined,
+              ) => {
+                requestedIndex = name;
+                const q = {
+                  eq: (field: string, value: undefined) => {
+                    if (field !== "softDeletedAt") throw new Error(`unexpected field ${field}`);
+                    requestedSoftDeletedAt = value;
+                    return q;
+                  },
+                };
+                build?.(q);
+                return {
+                  order: () => ({
+                    take: async (limit: number) => {
+                      requestedLimit = limit;
+                      return [
+                        {
+                          _id: "souls:1",
+                          _creationTime: 1,
+                          slug: "demo-soul",
+                          displayName: "Demo Soul",
+                          summary: "A demo soul",
+                          ownerUserId: "users:owner",
+                          ownerPublisherId: undefined,
+                          latestVersionId: undefined,
+                          tags: {},
+                          softDeletedAt: undefined,
+                          stats: { downloads: 1, stars: 2, versions: 3, comments: 4 },
+                          createdAt: 1,
+                          updatedAt: 2,
+                        },
+                      ];
+                    },
+                  }),
+                };
+              },
+            };
+          }),
+        },
+      } as never,
+      { limit: 7 } as never,
+    );
+
+    expect(requestedIndex).toBe("by_active_updated");
+    expect(requestedSoftDeletedAt).toBeUndefined();
+    expect(requestedLimit).toBe(7);
+    expect(result).toEqual([
+      expect.objectContaining({
+        _id: "souls:1",
+        slug: "demo-soul",
+        displayName: "Demo Soul",
+      }),
+    ]);
+  });
+});
@@ -138,11 +138,10 @@ export const list = query({
    }
    const entries = await ctx.db
      .query("souls")
+      .withIndex("by_active_updated", (q) => q.eq("softDeletedAt", undefined))
      .order("desc")
-      .take(limit * 5);
+      .take(limit);
    return entries
-      .filter((soul) => !soul.softDeletedAt)
-      .slice(0, limit)
      .map((soul) => toPublicSoul(soul))
      .filter((soul): soul is NonNullable<typeof soul> => Boolean(soul));
  },
@@ -34,6 +34,8 @@ export const toggle = mutation({
      return { starred: false };
    }

+    if (skill.softDeletedAt) throw new Error("Skill not found");
+
    await ctx.db.insert("stars", {
      skillId: args.skillId,
      userId,
@@ -70,7 +72,7 @@ export const addStarInternal = internalMutation({
  args: { userId: v.id("users"), skillId: v.id("skills") },
  handler: async (ctx, args) => {
    const skill = await ctx.db.get(args.skillId);
-    if (!skill) throw new Error("Skill not found");
+    if (!skill || skill.softDeletedAt) throw new Error("Skill not found");
    const existing = await ctx.db
      .query("stars")
      .withIndex("by_skill_user", (q) => q.eq("skillId", args.skillId).eq("userId", args.userId))
@@ -0,0 +1,303 @@
+/* @vitest-environment node */
+import { describe, expect, it, vi } from "vitest";
+
+// Mock the Convex function wrappers so that importing statsMaintenance.ts does
+// not attempt to load the Convex runtime (convex/server) in the Node test env.
+vi.mock("./functions", () => ({
+  internalMutation: (def: { handler: unknown }) => def,
+  internalQuery: (def: { handler: unknown }) => def,
+  internalAction: (def: { handler: unknown }) => def,
+}));
+
+vi.mock("./_generated/api", () => ({
+  internal: {
+    statsMaintenance: {
+      backfillSkillStatFieldsInternal: Symbol("backfillSkillStatFieldsInternal"),
+      getSkillStatBackfillStateInternal: Symbol("getSkillStatBackfillStateInternal"),
+      setSkillStatBackfillStateInternal: Symbol("setSkillStatBackfillStateInternal"),
+      reconcileSkillStarCounts: Symbol("reconcileSkillStarCounts"),
+    },
+  },
+}));
+
+const { __test, reconcileSkillStarCountsHandler } = await import("./statsMaintenance");
+const { buildSkillStatPatch } = __test;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a minimal skill doc for testing.  Only the stat-related fields are
+ * required; everything else is left as `undefined` / cast via `as never`.
+ */
+function makeSkill(overrides: {
+  statsDownloads?: number;
+  statsStars?: number;
+  statsInstallsCurrent?: number;
+  statsInstallsAllTime?: number;
+  stats: {
+    downloads: number;
+    stars: number;
+    installsCurrent?: number;
+    installsAllTime?: number;
+    comments: number;
+  };
+}) {
+  return overrides as never;
+}
+
+// ---------------------------------------------------------------------------
+// buildSkillStatPatch
+// ---------------------------------------------------------------------------
+
+describe("buildSkillStatPatch", () => {
+  it("scenario 1: top-level fields present and already in sync with nested → returns null", () => {
+    const skill = makeSkill({
+      statsDownloads: 10,
+      statsStars: 5,
+      statsInstallsCurrent: 3,
+      statsInstallsAllTime: 20,
+      stats: { downloads: 10, stars: 5, installsCurrent: 3, installsAllTime: 20, comments: 1 },
+    });
+
+    expect(buildSkillStatPatch(skill)).toBeNull();
+  });
+
+  it("scenario 2: top-level fields present but nested fields are stale → patches nested to match top-level", () => {
+    const skill = makeSkill({
+      statsDownloads: 10,
+      statsStars: 5,
+      statsInstallsCurrent: 3,
+      statsInstallsAllTime: 20,
+      stats: { downloads: 1, stars: 1, installsCurrent: 0, installsAllTime: 0, comments: 0 },
+    });
+
+    const patch = buildSkillStatPatch(skill);
+    expect(patch).not.toBeNull();
+    // Top-level fields must be written with the canonical (top-level) values.
+    expect(patch!.statsDownloads).toBe(10);
+    expect(patch!.statsStars).toBe(5);
+    expect(patch!.statsInstallsCurrent).toBe(3);
+    expect(patch!.statsInstallsAllTime).toBe(20);
+    // Nested fields must be brought in sync with the top-level values.
+    expect(patch!.stats.downloads).toBe(10);
+    expect(patch!.stats.stars).toBe(5);
+    expect(patch!.stats.installsCurrent).toBe(3);
+    expect(patch!.stats.installsAllTime).toBe(20);
+  });
+
+  it("scenario 3: top-level fields absent (pre-migration doc) → reads from nested, writes both sets", () => {
+    const skill = makeSkill({
+      // No statsDownloads / statsStars / etc. — pre-migration document.
+      stats: { downloads: 7, stars: 3, installsCurrent: 2, installsAllTime: 15, comments: 4 },
+    });
+
+    const patch = buildSkillStatPatch(skill);
+    expect(patch).not.toBeNull();
+    // Top-level fields must be populated from the nested values.
+    expect(patch!.statsDownloads).toBe(7);
+    expect(patch!.statsStars).toBe(3);
+    expect(patch!.statsInstallsCurrent).toBe(2);
+    expect(patch!.statsInstallsAllTime).toBe(15);
+    // Nested fields must remain consistent.
+    expect(patch!.stats.downloads).toBe(7);
+    expect(patch!.stats.stars).toBe(3);
+    expect(patch!.stats.installsCurrent).toBe(2);
+    expect(patch!.stats.installsAllTime).toBe(15);
+  });
+
+  it("scenario 4: top-level fields present but nested is out of sync → patches nested to match top-level (not the other way around)", () => {
+    // This is the exact bug that was previously shipped: the old code wrote
+    // nested → top-level instead of top-level → nested.
+    const skill = makeSkill({
+      statsDownloads: 100,
+      statsStars: 50,
+      statsInstallsCurrent: 30,
+      statsInstallsAllTime: 200,
+      stats: { downloads: 1, stars: 1, installsCurrent: 1, installsAllTime: 1, comments: 0 },
+    });
+
+    const patch = buildSkillStatPatch(skill);
+    expect(patch).not.toBeNull();
+    // The canonical top-level values must win.
+    expect(patch!.statsDownloads).toBe(100);
+    expect(patch!.statsStars).toBe(50);
+    expect(patch!.statsInstallsCurrent).toBe(30);
+    expect(patch!.statsInstallsAllTime).toBe(200);
+    // The stale nested values must be overwritten by the top-level values.
+    expect(patch!.stats.downloads).toBe(100);
+    expect(patch!.stats.stars).toBe(50);
+    expect(patch!.stats.installsCurrent).toBe(30);
+    expect(patch!.stats.installsAllTime).toBe(200);
+  });
+
+  it("preserves unrelated nested fields (e.g. comments) when patching stat fields", () => {
+    const skill = makeSkill({
+      statsDownloads: 5,
+      statsStars: 2,
+      statsInstallsCurrent: 1,
+      statsInstallsAllTime: 10,
+      stats: { downloads: 0, stars: 0, installsCurrent: 0, installsAllTime: 0, comments: 99 },
+    });
+
+    const patch = buildSkillStatPatch(skill);
+    expect(patch).not.toBeNull();
+    // comments is not a stat field managed by buildSkillStatPatch — it must be
+    // carried over unchanged from the original nested object.
+    expect(patch!.stats.comments).toBe(99);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// reconcileSkillStarCountsHandler
+// ---------------------------------------------------------------------------
+
+describe("reconcileSkillStarCounts", () => {
+  /**
+   * Build a minimal db mock that returns a single-page result for skills and
+   * configurable star / comment record counts.
+   */
+  function makeCtx(options: {
+    skill: {
+      _id: string;
+      statsStars?: number;
+      stats: { stars: number; comments: number };
+      softDeletedAt?: number;
+    };
+    actualStarCount: number;
+    actualCommentCount: number;
+  }) {
+    const { skill, actualStarCount, actualCommentCount } = options;
+
+    const starRecords = Array.from({ length: actualStarCount }, (_, i) => ({
+      _id: `stars:${i}`,
+      skillId: skill._id,
+    }));
+
+    const commentRecords = Array.from({ length: actualCommentCount }, (_, i) => ({
+      _id: `comments:${i}`,
+      skillId: skill._id,
+      softDeletedAt: undefined,
+    }));
+
+    const paginate = vi.fn().mockResolvedValue({
+      page: [skill],
+      continueCursor: null,
+      isDone: true,
+    });
+
+    const collect = vi
+      .fn()
+      .mockResolvedValueOnce(starRecords)
+      .mockResolvedValueOnce(commentRecords);
+
+    const withIndex = vi.fn().mockReturnValue({ collect });
+
+    const patch = vi.fn().mockResolvedValue(undefined);
+
+    const ctx = {
+      db: {
+        query: vi.fn().mockReturnValue({
+          order: vi.fn().mockReturnValue({ paginate }),
+          withIndex,
+        }),
+        patch,
+      },
+    } as never;
+
+    return { ctx, patch };
+  }
+
+  it("reads from top-level statsStars (canonical path) when deciding whether to patch", async () => {
+    // statsStars is correct (matches actual count), but stats.stars is stale.
+    // The reconcile job uses the canonical read path (top-level preferred), so
+    // it should NOT trigger a patch based on the star count alone.
+    const skill = {
+      _id: "skills:1",
+      statsStars: 5,           // canonical value — correct
+      stats: { stars: 99, comments: 0 }, // legacy value — stale, but not reconcile's concern
+    };
+
+    const { ctx, patch } = makeCtx({ skill, actualStarCount: 5, actualCommentCount: 0 });
+
+    const result = await reconcileSkillStarCountsHandler(ctx, {});
+
+    expect(result.scanned).toBe(1);
+    expect(result.patched).toBe(0);
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("falls back to stats.stars when statsStars is absent (pre-migration doc)", async () => {
+    // Pre-migration doc: no top-level statsStars.  The canonical read path
+    // falls back to stats.stars.  If that also matches actual count, no patch.
+    const skill = {
+      _id: "skills:1",
+      // statsStars intentionally absent
+      stats: { stars: 3, comments: 0 },
+    };
+
+    const { ctx, patch } = makeCtx({ skill, actualStarCount: 3, actualCommentCount: 0 });
+
+    const result = await reconcileSkillStarCountsHandler(ctx, {});
+
+    expect(result.scanned).toBe(1);
+    expect(result.patched).toBe(0);
+    expect(patch).not.toHaveBeenCalled();
+  });
+
+  it("patches both statsStars and stats.stars when canonical value drifts from actual count", async () => {
+    const skill = {
+      _id: "skills:1",
+      statsStars: 10,           // canonical value — out of sync with actual
+      stats: { stars: 10, comments: 0 },
+    };
+
+    const { ctx, patch } = makeCtx({ skill, actualStarCount: 7, actualCommentCount: 0 });
+
+    const result = await reconcileSkillStarCountsHandler(ctx, {});
+
+    expect(result.scanned).toBe(1);
+    expect(result.patched).toBe(1);
+    expect(patch).toHaveBeenCalledWith("skills:1", expect.objectContaining({
+      statsStars: 7,
+      stats: expect.objectContaining({ stars: 7 }),
+    }));
+  });
+
+  it("patches when comment count drifts even if star count is correct", async () => {
+    const skill = {
+      _id: "skills:1",
+      statsStars: 5,
+      stats: { stars: 5, comments: 10 }, // comments out of sync
+    };
+
+    const { ctx, patch } = makeCtx({ skill, actualStarCount: 5, actualCommentCount: 3 });
+
+    const result = await reconcileSkillStarCountsHandler(ctx, {});
+
+    expect(result.scanned).toBe(1);
+    expect(result.patched).toBe(1);
+    expect(patch).toHaveBeenCalledWith("skills:1", expect.objectContaining({
+      stats: expect.objectContaining({ comments: 3 }),
+    }));
+  });
+
+  it("skips soft-deleted skills", async () => {
+    const skill = {
+      _id: "skills:1",
+      softDeletedAt: 12345,
+      statsStars: 0,
+      stats: { stars: 0, comments: 0 },
+    };
+
+    const { ctx, patch } = makeCtx({ skill, actualStarCount: 5, actualCommentCount: 0 });
+
+    const result = await reconcileSkillStarCountsHandler(ctx, {});
+
+    // Soft-deleted skills are excluded from scanned count and never patched.
+    expect(result.scanned).toBe(0);
+    expect(result.patched).toBe(0);
+    expect(patch).not.toHaveBeenCalled();
+  });
+});
@@ -183,25 +183,53 @@ export const runSkillStatBackfillInternal: ReturnType<typeof internalAction> = i

 function buildSkillStatPatch(skill: Doc<"skills">) {
  const stats = skill.stats;
-  const nextDownloads = stats.downloads;
-  const nextStars = stats.stars;
-  const nextInstallsCurrent = stats.installsCurrent ?? 0;
-  const nextInstallsAllTime = stats.installsAllTime ?? 0;

-  if (
+  // Prefer the top-level stat fields when they exist (they are kept up-to-date
+  // by applySkillStatDeltas on every event flush).  Fall back to the legacy
+  // nested `stats` object only for documents that pre-date the migration.
+  const nextDownloads =
+    typeof skill.statsDownloads === "number" ? skill.statsDownloads : stats.downloads;
+  const nextStars =
+    typeof skill.statsStars === "number" ? skill.statsStars : stats.stars;
+  const nextInstallsCurrent =
+    typeof skill.statsInstallsCurrent === "number"
+      ? skill.statsInstallsCurrent
+      : (stats.installsCurrent ?? 0);
+  const nextInstallsAllTime =
+    typeof skill.statsInstallsAllTime === "number"
+      ? skill.statsInstallsAllTime
+      : (stats.installsAllTime ?? 0);
+
+  // Check whether both sets of fields are already in sync.
+  const topLevelInSync =
    skill.statsDownloads === nextDownloads &&
    skill.statsStars === nextStars &&
    skill.statsInstallsCurrent === nextInstallsCurrent &&
-    skill.statsInstallsAllTime === nextInstallsAllTime
-  ) {
+    skill.statsInstallsAllTime === nextInstallsAllTime;
+
+  const nestedInSync =
+    stats.downloads === nextDownloads &&
+    stats.stars === nextStars &&
+    (stats.installsCurrent ?? 0) === nextInstallsCurrent &&
+    (stats.installsAllTime ?? 0) === nextInstallsAllTime;
+
+  if (topLevelInSync && nestedInSync) {
    return null;
  }

+  // Write both sets of fields so they stay in sync.
  return {
    statsDownloads: nextDownloads,
    statsStars: nextStars,
    statsInstallsCurrent: nextInstallsCurrent,
    statsInstallsAllTime: nextInstallsAllTime,
+    stats: {
+      ...stats,
+      downloads: nextDownloads,
+      stars: nextStars,
+      installsCurrent: nextInstallsCurrent,
+      installsAllTime: nextInstallsAllTime,
+    },
  };
 }

@@ -215,60 +243,79 @@ function buildSkillStatPatch(skill: Doc<"skills">) {
 *
 * Downloads and installs are event-sourced only (no separate table to count from),
 * so they cannot be reconciled this way.
+ *
+ * Exported as a standalone function so it can be unit-tested directly without
+ * going through the Convex internalMutation wrapper.
 */
+export async function reconcileSkillStarCountsHandler(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ctx: { db: { query: any; patch: any } },
+  args: { cursor?: string; batchSize?: number },
+) {
+  const batchSize = clampInt(args.batchSize ?? 50, 1, 200);
+  const now = Date.now();
+
+  const { page, isDone, continueCursor } = await ctx.db
+    .query("skills")
+    .order("asc")
+    .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
+
+  let scanned = 0;
+  let patched = 0;
+  for (const skill of page) {
+    if (skill.softDeletedAt) continue;
+    scanned += 1;
+    // Count actual star records for this skill
+    const starRecords = await ctx.db
+      .query("stars")
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .withIndex("by_skill_user", (q: any) => q.eq("skillId", skill._id))
+      .collect();
+    const actualStars = starRecords.length;
+
+    // Count actual comment records for this skill
+    const commentRecords = await ctx.db
+      .query("comments")
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .withIndex("by_skill", (q: any) => q.eq("skillId", skill._id))
+      .collect();
+    const actualComments = commentRecords.filter((c: { softDeletedAt?: unknown }) => !c.softDeletedAt).length;
+
+    // Check if stats are out of sync (compare against the canonical value
+    // used by toPublicSkill: prefer top-level field, fall back to nested).
+    const currentStars =
+      typeof skill.statsStars === "number" ? skill.statsStars : skill.stats.stars;
+
+    if (currentStars !== actualStars || skill.stats.comments !== actualComments) {
+      const updatedStats = {
+        ...skill.stats,
+        stars: actualStars,
+        comments: actualComments,
+      };
+      // Keep both the top-level index field and the legacy nested field in sync.
+      await ctx.db.patch(skill._id, {
+        statsStars: actualStars,
+        stats: updatedStats,
+        updatedAt: now,
+      });
+      patched += 1;
+    }
+  }
+
+  return {
+    scanned,
+    patched,
+    cursor: isDone ? null : continueCursor,
+    isDone,
+  };
+}
+
 export const reconcileSkillStarCounts = internalMutation({
  args: {
    cursor: v.optional(v.string()),
    batchSize: v.optional(v.number()),
  },
-  handler: async (ctx, args) => {
-    const batchSize = clampInt(args.batchSize ?? 50, 1, 200);
-    const now = Date.now();
-
-    const { page, isDone, continueCursor } = await ctx.db
-      .query("skills")
-      .order("asc")
-      .paginate({ cursor: args.cursor ?? null, numItems: batchSize });
-
-    let patched = 0;
-    for (const skill of page) {
-      // Count actual star records for this skill
-      const starRecords = await ctx.db
-        .query("stars")
-        .withIndex("by_skill_user", (q) => q.eq("skillId", skill._id))
-        .collect();
-      const actualStars = starRecords.length;
-
-      // Count actual comment records for this skill
-      const commentRecords = await ctx.db
-        .query("comments")
-        .withIndex("by_skill", (q) => q.eq("skillId", skill._id))
-        .collect();
-      const actualComments = commentRecords.filter((c) => !c.softDeletedAt).length;
-
-      // Check if stats are out of sync
-      if (skill.stats.stars !== actualStars || skill.stats.comments !== actualComments) {
-        const updatedStats = {
-          ...skill.stats,
-          stars: actualStars,
-          comments: actualComments,
-        };
-        await ctx.db.patch(skill._id, {
-          statsStars: actualStars,
-          stats: updatedStats,
-          updatedAt: now,
-        });
-        patched += 1;
-      }
-    }
-
-    return {
-      scanned: page.length,
-      patched,
-      cursor: isDone ? null : continueCursor,
-      isDone,
-    };
-  },
+  handler: reconcileSkillStarCountsHandler,
 });

 export const runReconcileSkillStarCountsInternal = internalAction({
@@ -305,6 +352,11 @@ function clampInt(value: number, min: number, max: number) {
  return Math.min(Math.max(value, min), max);
 }

+// Exported for unit testing only — not part of the public API.
+export const __test = {
+  buildSkillStatPatch,
+};
+
 /**
 * Count a page of skillSearchDigest docs and return the partial public count.
 * Each query runs in its own transaction (~1000 docs, ~900 KB), well under limits.
@@ -33,9 +33,8 @@ type WrappedHandler<TArgs, TResult> = {
 };

 const meHandler = (me as unknown as WrappedHandler<Record<string, never>, unknown>)._handler;
-const getByHandleHandler = (
-  getByHandle as unknown as WrappedHandler<{ handle: string }, unknown>
-)._handler;
+const getByHandleHandler = (getByHandle as unknown as WrappedHandler<{ handle: string }, unknown>)
+  ._handler;

 function makeCtx() {
  const patch = vi.fn();
@@ -120,12 +119,63 @@ function makeCtx() {
  };
 }

-function makeListCtx(users: Array<Record<string, unknown>>) {
+function makeListCtx(
+  users: Array<Record<string, unknown>>,
+  options?: {
+    publishersByHandle?: Record<string, Record<string, unknown>>;
+    usersById?: Record<string, Record<string, unknown> | null>;
+  },
+) {
  const take = vi.fn(async (n: number) => users.slice(0, n));
  const collect = vi.fn(async () => users);
  const order = vi.fn(() => ({ take, collect }));
-  const query = vi.fn(() => ({ order }));
-  const get = vi.fn();
+  const publishersByHandle = options?.publishersByHandle ?? {};
+  const usersById = options?.usersById ?? {};
+  const query = vi.fn((table: string) => {
+    if (table === "users") {
+      return {
+        order,
+        withIndex: (
+          name: string,
+          cb?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+        ) => {
+          if (name !== "handle") throw new Error(`Unexpected users index ${name}`);
+          let handle = "";
+          cb?.({
+            eq: (field: string, value: string) => {
+              if (field === "handle") handle = value;
+              return {};
+            },
+          });
+          return {
+            unique: vi.fn(async () => users.find((user) => user.handle === handle) ?? null),
+          };
+        },
+      };
+    }
+    if (table === "publishers") {
+      return {
+        withIndex: (
+          name: string,
+          cb?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+        ) => {
+          if (name !== "by_handle") throw new Error(`Unexpected publishers index ${name}`);
+          let handle = "";
+          cb?.({
+            eq: (field: string, value: string) => {
+              if (field === "handle") handle = value;
+              return {};
+            },
+          });
+          return { unique: vi.fn(async () => publishersByHandle[handle] ?? null) };
+        },
+      };
+    }
+    throw new Error(`Unexpected table ${table}`);
+  });
+  const get = vi.fn<(id: string) => Promise<Record<string, unknown> | null>>(
+    async (id: string) => usersById[id] ?? null,
+  );
  return {
    ctx: { db: { query, get, normalizeId: vi.fn() } } as never,
    take,
@@ -339,6 +389,115 @@ describe("ensureHandler", () => {
    });
  });

+  it("repairs an existing handle that is no longer claimable", async () => {
+    const { ctx, patch, query } = makeCtx();
+    query.mockImplementation(((table: string) => {
+      if (table === "reservedHandles") {
+        return {
+          withIndex: (name: string) => {
+            if (name !== "by_handle_active_updatedAt") {
+              throw new Error(`Unexpected reservedHandles index ${name}`);
+            }
+            return { order: () => ({ take: async () => [] }) };
+          },
+        };
+      }
+      if (table === "publishers") {
+        return {
+          withIndex: (
+            name: string,
+            builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+          ) => {
+            let handle = "";
+            let linkedUserId = "";
+            const q = {
+              eq: (field: string, value: string) => {
+                if (field === "handle") handle = value;
+                if (field === "linkedUserId") linkedUserId = value;
+                return q;
+              },
+            };
+            builder?.(q);
+            if (name === "by_handle") {
+              return {
+                unique: vi.fn(async () => {
+                  if (handle === "openclaw") {
+                    return {
+                      _id: "publishers:openclaw",
+                      kind: "org",
+                      handle: "openclaw",
+                      displayName: "OpenClaw",
+                    };
+                  }
+                  return null;
+                }),
+              };
+            }
+            if (name === "by_linked_user") {
+              return {
+                unique: vi.fn(async () =>
+                  linkedUserId === "users:owner"
+                    ? {
+                        _id: "publishers:openclaw-user",
+                        kind: "user",
+                        handle: "openclaw-user",
+                        linkedUserId: "users:owner",
+                        displayName: "OpenClaw User",
+                      }
+                    : null,
+                ),
+              };
+            }
+            throw new Error(`Unexpected publishers index ${name}`);
+          },
+        };
+      }
+      if (table === "publisherMembers") {
+        return {
+          withIndex: (name: string) => {
+            if (name !== "by_publisher_user") {
+              throw new Error(`Unexpected publisherMembers index ${name}`);
+            }
+            return { unique: vi.fn(async () => null) };
+          },
+        };
+      }
+      if (table === "packages" || table === "skills") {
+        return {
+          withIndex: (name: string) => {
+            if (name !== "by_owner_publisher") {
+              throw new Error(`Unexpected ${table} index ${name}`);
+            }
+            return { collect: vi.fn(async () => []) };
+          },
+        };
+      }
+      throw new Error(`Unexpected table ${table}`);
+    }) as never);
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:owner",
+      user: {
+        _id: "users:owner",
+        _creationTime: 1,
+        handle: "openclaw",
+        displayName: "openclaw",
+        name: "openclaw",
+        email: "owner@example.com",
+        role: "user",
+        createdAt: 1,
+        personalPublisherId: "publishers:openclaw-user",
+      },
+    } as never);
+
+    await ensureHandler(ctx);
+
+    expect(patch).toHaveBeenCalledWith("users:owner", {
+      handle: "openclaw-2",
+      displayName: "openclaw-2",
+      updatedAt: expect.any(Number),
+    });
+  });
+
  it("does not auto-claim a reserved handle for another user", async () => {
    const { ctx, patch, query } = makeCtx();
    query.mockImplementation(((table: string) => {
@@ -399,7 +558,10 @@ describe("ensureHandler", () => {
      }
      if (table === "publishers") {
        return {
-          withIndex: (name: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
+          withIndex: (
+            name: string,
+            builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+          ) => {
            let handle = "";
            let linkedUserId = "";
            const q = {
@@ -502,6 +664,19 @@ describe("me", () => {
    expect(result).toBeNull();
    expect(get).not.toHaveBeenCalled();
  });
+
+  it("returns null when auth resolves to an invalid user id", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:broken" as never);
+    const get = vi.fn(async (id: string) => {
+      if (id === "users:broken") throw new Error("Table mismatch");
+      return null;
+    });
+
+    const result = await meHandler({ db: { get } } as never, {});
+
+    expect(result).toBeNull();
+    expect(get).toHaveBeenCalledWith("users:broken");
+  });
 });

 describe("users.getByHandle", () => {
@@ -746,7 +921,10 @@ describe("users.syncGitHubProfileInternal", () => {
      }
      if (table === "publishers") {
        return {
-          withIndex: (name: string, builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown) => {
+          withIndex: (
+            name: string,
+            builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+          ) => {
            let handle = "";
            let linkedUserId = "";
            const q = {
@@ -897,6 +1075,81 @@ describe("users.list", () => {
    expect(result.items[0]?.handle).toBe("alice");
  });

+  it("includes an exact older handle match outside the bounded scan", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:admin",
+      user: { _id: "users:admin", role: "admin" },
+    } as never);
+    const users = [
+      ...Array.from({ length: 500 }, (_value, index) => ({
+        _id: `users:recent-${index}`,
+        _creationTime: 10_000 - index,
+        handle: `recent-${index}`,
+        role: "user",
+      })),
+      { _id: "users:older", _creationTime: 1, handle: "alice", role: "user" },
+    ];
+    const { ctx, take, collect } = makeListCtx(users);
+    const listHandler = (
+      list as unknown as { _handler: (ctx: unknown, args: unknown) => Promise<unknown> }
+    )._handler;
+
+    const result = (await listHandler(ctx, { limit: 50, search: "alice" })) as {
+      items: Array<Record<string, unknown>>;
+      total: number;
+    };
+
+    expect(take).toHaveBeenCalledWith(500);
+    expect(collect).not.toHaveBeenCalled();
+    expect(result.total).toBe(1);
+    expect(result.items[0]?._id).toBe("users:older");
+  });
+
+  it("includes an exact personal publisher handle match without a full collect", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:admin",
+      user: { _id: "users:admin", role: "admin" },
+    } as never);
+    const users = [{ _id: "users:1", _creationTime: 2, handle: "alice", role: "user" }];
+    const { ctx, take, collect } = makeListCtx(users, {
+      publishersByHandle: {
+        lmlukef: {
+          _id: "publishers:lmlukef",
+          kind: "user",
+          handle: "lmlukef",
+          linkedUserId: "users:owner",
+        },
+      },
+      usersById: {
+        "users:owner": {
+          _id: "users:owner",
+          _creationTime: 1,
+          handle: "luke",
+          name: "different-gh-login",
+          displayName: "Luke",
+          role: "user",
+        },
+      },
+    });
+    const listHandler = (
+      list as unknown as { _handler: (ctx: unknown, args: unknown) => Promise<unknown> }
+    )._handler;
+
+    const result = (await listHandler(ctx, { limit: 50, search: "lmLukeF" })) as {
+      items: Array<Record<string, unknown>>;
+      total: number;
+    };
+
+    expect(take).toHaveBeenCalledWith(500);
+    expect(collect).not.toHaveBeenCalled();
+    expect(result.total).toBe(1);
+    expect(result.items[0]).toMatchObject({
+      _id: "users:owner",
+      handle: "luke",
+      displayName: "Luke",
+    });
+  });
+
  it("clamps large limit and search scan size", async () => {
    vi.mocked(requireUser).mockResolvedValue({
      userId: "users:admin",
@@ -951,6 +1204,45 @@ describe("users.list", () => {
    });
  });

+  it("includes an exact publisher-handle match even when the linked user is banned", async () => {
+    vi.mocked(requireUser).mockResolvedValue({
+      userId: "users:admin",
+      user: { _id: "users:admin", role: "admin" },
+    } as never);
+    const users = [
+      {
+        _id: "users:1",
+        _creationTime: 3,
+        handle: "different-login",
+        displayName: "ClawGrid",
+        deletedAt: 123,
+        role: "user",
+      },
+      { _id: "users:2", _creationTime: 2, handle: "alice", role: "user" },
+    ];
+    const { ctx } = makeListCtx(users, {
+      publishersByHandle: {
+        clawgrid: {
+          _id: "publishers:clawgrid",
+          handle: "clawgrid",
+          kind: "user",
+          linkedUserId: "users:1",
+        },
+      },
+      usersById: {
+        "users:1": users[0]!,
+      },
+    });
+    const listHandler = (
+      list as unknown as { _handler: (ctx: unknown, args: unknown) => Promise<unknown> }
+    )._handler;
+
+    await expect(listHandler(ctx, { limit: 10, search: "clawgrid" })).resolves.toMatchObject({
+      total: 1,
+      items: [{ _id: "users:1", deletedAt: 123 }],
+    });
+  });
+
  it("treats whitespace search as empty search", async () => {
    vi.mocked(requireUser).mockResolvedValue({
      userId: "users:admin",
@@ -1058,6 +1350,127 @@ describe("users.searchInternal", () => {
    ]);
  });

+  it("includes an exact personal publisher handle match in admin search", async () => {
+    const users = [
+      { _id: "users:1", _creationTime: 2, handle: "alice", name: "alice", role: "user" },
+    ];
+    const { ctx, get } = makeListCtx(users, {
+      publishersByHandle: {
+        lmlukef: {
+          _id: "publishers:lmlukef",
+          kind: "user",
+          handle: "lmlukef",
+          linkedUserId: "users:owner",
+        },
+      },
+      usersById: {
+        "users:owner": {
+          _id: "users:owner",
+          _creationTime: 1,
+          handle: "luke",
+          name: "different-gh-login",
+          displayName: "Luke",
+          role: "user",
+        },
+      },
+    });
+    const handler = (
+      searchInternal as unknown as { _handler: (ctx: unknown, args: unknown) => Promise<unknown> }
+    )._handler;
+    get.mockImplementation(async (id: string) => {
+      if (id === "users:admin") return { _id: "users:admin", role: "admin" };
+      if (id === "users:owner") {
+        return {
+          _id: "users:owner",
+          _creationTime: 1,
+          handle: "luke",
+          name: "different-gh-login",
+          displayName: "Luke",
+          role: "user",
+        };
+      }
+      return null;
+    });
+
+    const result = (await handler(ctx, {
+      actorUserId: "users:admin",
+      query: "lmLukeF",
+      limit: 25,
+    })) as {
+      items: Array<Record<string, unknown>>;
+      total: number;
+    };
+
+    expect(result.total).toBe(1);
+    expect(result.items[0]).toEqual({
+      userId: "users:owner",
+      handle: "luke",
+      displayName: "Luke",
+      name: "different-gh-login",
+      role: "user",
+    });
+  });
+
+  it("does not double-count total when the fallback user already matched off-page", async () => {
+    const users = [
+      {
+        _id: "users:1",
+        _creationTime: 3,
+        handle: "lmquery-top",
+        name: "lmquery-top",
+        role: "user",
+      },
+      {
+        _id: "users:2",
+        _creationTime: 2,
+        handle: "lmquery-mid",
+        name: "lmquery-mid",
+        role: "user",
+      },
+      {
+        _id: "users:owner",
+        _creationTime: 1,
+        handle: "owner-lmquery",
+        name: "owner-lmquery",
+        displayName: "Owner Lmquery",
+        role: "user",
+      },
+    ];
+    const { ctx, get } = makeListCtx(users, {
+      publishersByHandle: {
+        lmquery: {
+          _id: "publishers:lmquery",
+          kind: "user",
+          handle: "lmquery",
+          linkedUserId: "users:owner",
+        },
+      },
+      usersById: {
+        "users:owner": users[2] as Record<string, unknown>,
+      },
+    });
+    const handler = (
+      searchInternal as unknown as { _handler: (ctx: unknown, args: unknown) => Promise<unknown> }
+    )._handler;
+    get.mockImplementation(async (id: string) => {
+      if (id === "users:admin") return { _id: "users:admin", role: "admin" };
+      if (id === "users:owner") return users[2] as Record<string, unknown>;
+      return null;
+    });
+
+    const result = (await handler(ctx, {
+      actorUserId: "users:admin",
+      query: "lmquery",
+      limit: 2,
+    })) as {
+      items: Array<Record<string, unknown>>;
+      total: number;
+    };
+
+    expect(result.total).toBe(3);
+    expect(result.items.map((item) => item.userId)).toEqual(["users:owner", "users:1"]);
+  });
+
  it("rejects deactivated actors", async () => {
    const { ctx, get } = makeListCtx([]);
    const handler = (
@@ -1080,7 +1493,7 @@ describe("users.searchInternal", () => {
    );
  });

-  it("clamps limit for empty query and uses non-search path", async () => {
+  it("still caps empty-query listing and uses non-search path", async () => {
    const users = Array.from({ length: 400 }, (_value, index) => ({
      _id: `users:${index}`,
      _creationTime: 1_000 - index,
@@ -1,10 +1,9 @@
-import { getAuthUserId } from "@convex-dev/auth/server";
 import { v } from "convex/values";
 import { internal } from "./_generated/api";
 import type { Doc, Id } from "./_generated/dataModel";
-import type { ActionCtx, MutationCtx } from "./_generated/server";
+import type { ActionCtx, MutationCtx, QueryCtx } from "./_generated/server";
 import { internalAction, internalMutation, internalQuery, mutation, query } from "./functions";
-import { assertAdmin, assertModerator, requireUser } from "./lib/access";
+import { assertAdmin, assertModerator, getOptionalActiveAuthUserId, requireUser } from "./lib/access";
 import { syncGitHubProfile } from "./lib/githubAccount";
 import {
  ensurePersonalPublisherForUser,
@@ -57,15 +56,28 @@ export const searchInternal = internalQuery({
    assertAdmin(actor);

    const limit = clampInt(args.limit ?? 20, 1, MAX_USER_LIST_LIMIT);
-    const result = await queryUsersForAdminList(ctx, { limit, search: args.query });
-    const items = result.items.map((user) => ({
+    const exactHandleUser = args.query
+      ? await getUserByHandleOrPersonalPublisher(ctx, args.query)
+      : null;
+    const result = await queryUsersForAdminList(ctx, {
+      limit,
+      search: args.query,
+      exactUserId: exactHandleUser?._id,
+    });
+    const dedupedUsers = exactHandleUser
+      ? [exactHandleUser, ...result.items.filter((user) => user._id !== exactHandleUser._id)]
+      : result.items;
+    const total = exactHandleUser
+      ? result.total + (result.containsExactUser ? 0 : 1)
+      : result.total;
+    const items = dedupedUsers.slice(0, limit).map((user) => ({
      userId: user._id,
      handle: user.handle ?? null,
      displayName: user.displayName ?? null,
      name: user.name ?? null,
      role: user.role ?? null,
    }));
-    return { items, total: result.total };
+    return { items, total };
  },
 });

@@ -166,17 +178,9 @@ export const syncGitHubProfileAction = internalAction({
 export const me = query({
  args: {},
  handler: async (ctx) => {
-    let userId: Awaited<ReturnType<typeof getAuthUserId>>;
-    try {
-      userId = await getAuthUserId(ctx);
-    } catch {
-      // Public pages should treat broken/stale auth as anonymous instead of crashing SSR.
-      return null;
-    }
+    const userId = await getOptionalActiveAuthUserId(ctx);
    if (!userId) return null;
-    const user = await ctx.db.get(userId);
-    if (!user || user.deletedAt || user.deactivatedAt) return null;
-    return user;
+    return await ctx.db.get(userId);
  },
 });

@@ -235,6 +239,9 @@ async function computeEnsureUpdates(ctx: MutationCtx, user: Doc<"users">) {
  const updates: Record<string, unknown> = {};

  const existingHandle = normalizeHandle(user.handle);
+  const existingHandleClaimable = existingHandle
+    ? await canUserClaimHandle(ctx, existingHandle, user._id)
+    : false;
  const githubLogin = normalizeHandle(user.name);
  const requestedHandle = deriveHandle({
    existingHandle,
@@ -245,15 +252,20 @@ async function computeEnsureUpdates(ctx: MutationCtx, user: Doc<"users">) {
    requestedHandle && (await canUserClaimHandle(ctx, requestedHandle, user._id))
      ? requestedHandle
      : undefined;
-  if (!derivedHandle && !existingHandle) {
-    const emailFallback = !requestedHandle && user.email ? user.email.split("@")[0]?.trim() : user.email?.split("@")[0]?.trim();
+  if (!derivedHandle && (!existingHandle || !existingHandleClaimable)) {
+    const emailFallback = normalizeHandle(user.email?.split("@")[0]);
+    const emailFallbackHandle =
+      emailFallback && emailFallback !== requestedHandle
+        ? await resolveAvailableHandle(ctx, emailFallback, user._id)
+        : undefined;
    derivedHandle =
-      (emailFallback &&
-      emailFallback !== requestedHandle &&
-      (await resolveAvailableHandle(ctx, emailFallback, user._id))) ||
-      (await resolveAvailableHandle(ctx, requestedHandle, user._id));
+      (await resolveAvailableHandle(
+        ctx,
+        requestedHandle ?? existingHandle ?? githubLogin ?? emailFallback,
+        user._id,
+      )) ?? emailFallbackHandle;
  }
-  const baseHandle = derivedHandle ?? existingHandle;
+  const baseHandle = derivedHandle ?? (existingHandleClaimable ? existingHandle : undefined);

  if (derivedHandle && existingHandle !== derivedHandle) {
    updates.handle = derivedHandle;
@@ -353,7 +365,41 @@ export const list = query({
    const { user } = await requireUser(ctx);
    assertAdmin(user);
    const limit = clampInt(args.limit ?? 50, 1, MAX_USER_LIST_LIMIT);
-    return queryUsersForAdminList(ctx, { limit, search: args.search });
+    const exactHandleUser = args.search
+      ? await getUserByHandleOrPersonalPublisher(ctx, args.search)
+      : null;
+    const result = await queryUsersForAdminList(ctx, {
+      limit,
+      search: args.search,
+      exactUserId: exactHandleUser?._id,
+    });
+    const dedupedUsers = exactHandleUser
+      ? [exactHandleUser, ...result.items.filter((entry) => entry._id !== exactHandleUser._id)]
+      : result.items;
+    const total = exactHandleUser
+      ? result.total + (result.containsExactUser ? 0 : 1)
+      : result.total;
+    return {
+      items: dedupedUsers.slice(0, limit),
+      total,
+    };
+  },
+});
+
+export const listPublic = query({
+  args: { limit: v.optional(v.number()), search: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    const limit = clampInt(args.limit ?? 40, 1, 100);
+    const result = await queryUsersForPublicList(ctx, {
+      limit,
+      search: args.search,
+    });
+    return {
+      items: result.items
+        .map((user) => toPublicUser(user))
+        .filter((user): user is NonNullable<ReturnType<typeof toPublicUser>> => Boolean(user)),
+      total: result.total,
+    };
  },
 });

@@ -367,26 +413,47 @@ function computeUserSearchScanLimit(limit: number) {
 }

 async function queryUsersForAdminList(
-  ctx: {
-    db: {
-      query: (table: "users") => {
-        order: (order: "desc") => { take: (n: number) => Promise<Doc<"users">[]> };
-      };
-    };
-  },
-  args: { limit: number; search?: string },
+  ctx: Pick<QueryCtx, "db">,
+  args: { limit: number; search?: string; exactUserId?: Id<"users"> },
 ) {
  const normalizedSearch = normalizeSearchQuery(args.search);
  const orderedUsers = ctx.db.query("users").order("desc");

  if (!normalizedSearch) {
    const items = await orderedUsers.take(args.limit);
-    return { items, total: items.length };
+    return { items, total: items.length, containsExactUser: false };
  }

  const scannedUsers = await orderedUsers.take(computeUserSearchScanLimit(args.limit));
  const result = buildUserSearchResults(scannedUsers, normalizedSearch);
-  return { items: result.items.slice(0, args.limit), total: result.total };
+  return {
+    items: result.items.slice(0, args.limit),
+    total: result.total,
+    containsExactUser: args.exactUserId
+      ? result.items.some((user) => user._id === args.exactUserId)
+      : false,
+  };
+}
+
+async function queryUsersForPublicList(
+  ctx: Pick<QueryCtx, "db">,
+  args: { limit: number; search?: string },
+) {
+  const normalizedSearch = normalizeSearchQuery(args.search);
+  const scanLimit = normalizedSearch
+    ? computeUserSearchScanLimit(args.limit)
+    : clampInt(args.limit * 6, args.limit, MAX_USER_SEARCH_SCAN);
+  const scannedUsers = await ctx.db
+    .query("users")
+    .withIndex("by_active_handle", (q) => q.eq("deletedAt", undefined).eq("deactivatedAt", undefined))
+    .order("desc")
+    .take(scanLimit);
+  const activeUsers = scannedUsers.filter((user) => Boolean(user.handle));
+  const result = buildUserSearchResults(activeUsers, normalizedSearch);
+  return {
+    items: result.items.slice(0, args.limit),
+    total: result.total,
+  };
 }

 function clampInt(value: number, min: number, max: number) {
@@ -400,6 +467,20 @@ export const getByHandle = query({
  },
 });

+/** Lightweight stats for user hover tooltips. Uses the skills by_owner index. */
+export const getHoverStats = query({
+  args: { userId: v.id("users") },
+  handler: async (ctx, args) => {
+    const user = await ctx.db.get(args.userId);
+
+    return {
+      publishedSkills: user?.publishedSkills ?? 0,
+      totalStars: user?.totalStars ?? 0,
+      totalDownloads: user?.totalDownloads ?? 0,
+    };
+  },
+});
+
 export const getReservedHandleInternal = internalQuery({
  args: { handle: v.string() },
  handler: async (ctx, args) => {
@@ -161,11 +161,10 @@ describe("package VT retries", () => {
      { releaseId: "packageReleases:demo", attempt: 2 },
    );

-    expect(scheduler.runAfter).toHaveBeenCalledWith(
-      5 * 60 * 1000,
-      expect.anything(),
-      { releaseId: "packageReleases:demo", attempt: 3 },
-    );
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 3,
+    });
  });

  it("retries package upload when VT upload fails", async () => {
@@ -195,7 +194,9 @@ describe("package VT retries", () => {
        runMutation,
        scheduler,
        storage: {
-          get: vi.fn(async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" })),
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
        },
      } as never,
      { releaseId: "packageReleases:demo" },
@@ -208,11 +209,10 @@ describe("package VT retries", () => {
        sha256hash: expect.any(String),
      }),
    );
-    expect(scheduler.runAfter).toHaveBeenCalledWith(
-      5 * 60 * 1000,
-      expect.anything(),
-      { releaseId: "packageReleases:demo", attempt: 2 },
-    );
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 2,
+    });
  });

  it("uses existing AV engine verdicts for packages without re-uploading", async () => {
@@ -258,7 +258,9 @@ describe("package VT retries", () => {
        runMutation,
        scheduler,
        storage: {
-          get: vi.fn(async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" })),
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
        },
      } as never,
      { releaseId: "packageReleases:demo" },
@@ -275,7 +277,73 @@ describe("package VT retries", () => {
    expect(scheduler.runAfter).not.toHaveBeenCalled();
  });

-  it("promotes official source-linked packages with undetected-only VT stats via fallback", async () => {
+  it("does not promote official source-linked packages with suspicious static scans via fallback", async () => {
+    process.env.VT_API_KEY = "test-key";
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 0,
+                harmless: 0,
+                undetected: 66,
+              },
+            },
+          },
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ data: { id: "analysis-123" } }),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const runMutation = vi.fn(async () => null);
+    const scheduler = { runAfter: vi.fn(async () => null) };
+    await scanPackageReleaseWithVirusTotalHandler(
+      {
+        runQuery: vi
+          .fn()
+          .mockResolvedValueOnce({
+            _id: "packageReleases:demo",
+            packageId: "packages:demo",
+            version: "1.0.0",
+            verification: { tier: "source-linked" },
+            llmAnalysis: { status: "clean" },
+            staticScan: { status: "suspicious" },
+            files: [{ path: "package.json", storageId: "storage:pkg" }],
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            name: "demo-plugin",
+            family: "code-plugin",
+            isOfficial: true,
+          }),
+        runMutation,
+        scheduler,
+        storage: {
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
+        },
+      } as never,
+      { releaseId: "packageReleases:demo" },
+    );
+
+    expect(runMutation.mock.calls.length).toBe(1);
+    const mutationCalls = runMutation.mock.calls as unknown as Array<
+      [unknown, Record<string, unknown>]
+    >;
+    expect(mutationCalls.some(([, payload]) => "vtAnalysis" in payload)).toBe(false);
+    expect(fetchMock.mock.calls.length).toBe(2);
+    expect(scheduler.runAfter.mock.calls.length).toBe(1);
+  });
+
+  it("promotes official source-linked packages with clean static scans via fallback", async () => {
    process.env.VT_API_KEY = "test-key";
    const fetchMock = vi.fn().mockResolvedValueOnce({
      ok: true,
@@ -306,7 +374,7 @@ describe("package VT retries", () => {
            version: "1.0.0",
            verification: { tier: "source-linked" },
            llmAnalysis: { status: "clean" },
-            staticScan: { status: "suspicious" },
+            staticScan: { status: "clean" },
            files: [{ path: "package.json", storageId: "storage:pkg" }],
          })
          .mockResolvedValueOnce({
@@ -318,7 +386,9 @@ describe("package VT retries", () => {
        runMutation,
        scheduler,
        storage: {
-          get: vi.fn(async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" })),
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
        },
      } as never,
      { releaseId: "packageReleases:demo" },
@@ -382,7 +452,9 @@ describe("package VT retries", () => {
        runMutation,
        scheduler,
        storage: {
-          get: vi.fn(async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" })),
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
        },
      } as never,
      { releaseId: "packageReleases:demo" },
@@ -422,14 +494,13 @@ describe("package VT retries", () => {
      { releaseId: "packageReleases:demo", attempt: 3 },
    );

-    expect(scheduler.runAfter).toHaveBeenCalledWith(
-      5 * 60 * 1000,
-      expect.anything(),
-      { releaseId: "packageReleases:demo", attempt: 4 },
-    );
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 4,
+    });
  });

-  it("applies the same undetected-only fallback during package polling", async () => {
+  it("does not apply undetected-only fallback during package polling when static scan is suspicious", async () => {
    process.env.VT_API_KEY = "test-key";
    vi.stubGlobal(
      "fetch",
@@ -476,17 +547,8 @@ describe("package VT retries", () => {
      { releaseId: "packageReleases:demo", attempt: 3 },
    );

-    expect(runMutation).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        releaseId: "packageReleases:demo",
-        vtAnalysis: expect.objectContaining({
-          status: "clean",
-          source: "engines-undetected-fallback",
-        }),
-      }),
-    );
-    expect(scheduler.runAfter).not.toHaveBeenCalled();
+    expect(runMutation).not.toHaveBeenCalled();
+    expect(scheduler.runAfter).toHaveBeenCalledTimes(1);
  });

  it("applies the same undetected-only fallback during community package polling", async () => {
@@ -603,10 +665,9 @@ describe("package VT retries", () => {

    expect(runMutation).not.toHaveBeenCalled();
    expect(fetchMock).toHaveBeenCalledTimes(2);
-    expect(scheduler.runAfter).toHaveBeenCalledWith(
-      5 * 60 * 1000,
-      expect.anything(),
-      { releaseId: "packageReleases:demo", attempt: 4 },
-    );
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 4,
+    });
  });
 });
@@ -179,7 +179,7 @@ function buildPackageUndetectedFallbackAnalysis(
    return null;
  }
  if (release.llmAnalysis?.status !== "clean") return null;
-  if (!release.staticScan || release.staticScan.status === "malicious") return null;
+  if (!release.staticScan || release.staticScan.status !== "clean") return null;
  if (stats.malicious !== 0 || stats.suspicious !== 0) return null;
  if ((stats.harmless ?? 0) <= 0 && (stats.undetected ?? 0) <= 0) return null;

@@ -187,7 +187,7 @@ function buildPackageUndetectedFallbackAnalysis(
    status: "clean",
    verdict: "undetected-only-fallback",
    analysis:
-      "VirusTotal reported no malicious or suspicious engine hits. ClawHub promoted this source-linked package after clean LLM and non-malicious static scans.",
+      "VirusTotal reported no malicious or suspicious engine hits. ClawHub promoted this source-linked package after clean LLM and clean static scans.",
    source: "engines-undetected-fallback",
    checkedAt: Date.now(),
  };
@@ -635,10 +635,15 @@ export const scanPackageReleaseWithVirusTotal = internalAction({
        `[vt:package] Release ${args.releaseId} missing ${missingFiles}/${release.files.length} files, retrying`,
      );
      if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-        await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.scanPackageReleaseWithVirusTotal, {
-          releaseId: args.releaseId,
-          attempt: attempt + 1,
-        });
+        await runAfterRef(
+          ctx,
+          PACKAGE_SCAN_RETRY_DELAY_MS,
+          internalRefs.vt.scanPackageReleaseWithVirusTotal,
+          {
+            releaseId: args.releaseId,
+            attempt: attempt + 1,
+          },
+        );
      }
      return;
    }
@@ -686,18 +691,28 @@ export const scanPackageReleaseWithVirusTotal = internalAction({
        const error = await response.text();
        console.error("[vt:package] VirusTotal upload error:", error);
        if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-          await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.scanPackageReleaseWithVirusTotal, {
-            releaseId: args.releaseId,
-            attempt: attempt + 1,
-          });
+          await runAfterRef(
+            ctx,
+            PACKAGE_SCAN_RETRY_DELAY_MS,
+            internalRefs.vt.scanPackageReleaseWithVirusTotal,
+            {
+              releaseId: args.releaseId,
+              attempt: attempt + 1,
+            },
+          );
        }
        return;
      }

-      await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.pollPackageReleaseScanResults, {
-        releaseId: args.releaseId,
-        attempt: 1,
-      });
+      await runAfterRef(
+        ctx,
+        PACKAGE_SCAN_RETRY_DELAY_MS,
+        internalRefs.vt.pollPackageReleaseScanResults,
+        {
+          releaseId: args.releaseId,
+          attempt: 1,
+        },
+      );

      console.log(
        `[vt:package] Uploaded ${pkg.name}@${release.version} for scanning (${sha256hash})`,
@@ -705,10 +720,15 @@ export const scanPackageReleaseWithVirusTotal = internalAction({
    } catch (error) {
      console.error("[vt:package] Failed to upload to VirusTotal:", error);
      if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-        await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.scanPackageReleaseWithVirusTotal, {
-          releaseId: args.releaseId,
-          attempt: attempt + 1,
-        });
+        await runAfterRef(
+          ctx,
+          PACKAGE_SCAN_RETRY_DELAY_MS,
+          internalRefs.vt.scanPackageReleaseWithVirusTotal,
+          {
+            releaseId: args.releaseId,
+            attempt: attempt + 1,
+          },
+        );
      }
    }
  },
@@ -737,10 +757,15 @@ export const pollPackageReleaseScanResults = internalAction({
      const vtResult = await checkExistingFile(apiKey, release.sha256hash);
      if (!vtResult) {
        if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-          await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.pollPackageReleaseScanResults, {
-            releaseId: args.releaseId,
-            attempt: attempt + 1,
-          });
+          await runAfterRef(
+            ctx,
+            PACKAGE_SCAN_RETRY_DELAY_MS,
+            internalRefs.vt.pollPackageReleaseScanResults,
+            {
+              releaseId: args.releaseId,
+              attempt: attempt + 1,
+            },
+          );
        }
        return;
      }
@@ -756,18 +781,28 @@ export const pollPackageReleaseScanResults = internalAction({

      await requestRescan(apiKey, release.sha256hash);
      if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-        await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.pollPackageReleaseScanResults, {
-          releaseId: args.releaseId,
-          attempt: attempt + 1,
-        });
+        await runAfterRef(
+          ctx,
+          PACKAGE_SCAN_RETRY_DELAY_MS,
+          internalRefs.vt.pollPackageReleaseScanResults,
+          {
+            releaseId: args.releaseId,
+            attempt: attempt + 1,
+          },
+        );
      }
    } catch (error) {
      console.error(`[vt:package] Error polling ${release.sha256hash}:`, error);
      if (attempt < PACKAGE_SCAN_MAX_ATTEMPTS) {
-        await runAfterRef(ctx, PACKAGE_SCAN_RETRY_DELAY_MS, internalRefs.vt.pollPackageReleaseScanResults, {
-          releaseId: args.releaseId,
-          attempt: attempt + 1,
-        });
+        await runAfterRef(
+          ctx,
+          PACKAGE_SCAN_RETRY_DELAY_MS,
+          internalRefs.vt.pollPackageReleaseScanResults,
+          {
+            releaseId: args.releaseId,
+            attempt: attempt + 1,
+          },
+        );
      }
    }
  },
@@ -11,7 +11,7 @@ read_when:

 - Web app: TanStack Start (React) under `src/`.
 - Backend: Convex under `convex/` (DB, storage, actions, HTTP routes).
- CLI: `packages/clawdhub/` (published as `clawhub`, legacy `clawdhub`).
+- CLI: `packages/clawhub/` (published as `clawhub`, legacy `clawdhub`).
 - Shared schemas/routes: `packages/schema/` (`clawhub-schema`).

 ## Data + storage
@@ -11,6 +11,7 @@ read_when:

 - Convex Auth + GitHub OAuth App.
 - GitHub is the only supported login provider.
+- Disabled/banned accounts are blocked during OAuth completion and should surface a user-facing reason instead of a generic auth failure.
 - Env vars:
  - `AUTH_GITHUB_ID`
  - `AUTH_GITHUB_SECRET`
@@ -7,7 +7,7 @@ read_when:

 # CLI

-CLI package: `packages/clawdhub/` (published as `clawhub`, bin: `clawhub`).
+CLI package: `packages/clawhub/` (published as `clawhub`, bin: `clawhub`).

 From this repo you can run it via the wrapper script:

@@ -62,6 +62,9 @@ When no proxy variable is set, behavior is unchanged (direct connections).
 Stores your API token + cached registry URL.

 - macOS: `~/Library/Application Support/clawhub/config.json`
+- Linux/XDG: `$XDG_CONFIG_HOME/clawhub/config.json` or `~/.config/clawhub/config.json`
+- Windows: `%APPDATA%\\clawhub\\config.json`
+- Legacy fallback: if `clawhub/config.json` does not exist yet but `clawdhub/config.json` does, the CLI reuses the legacy path
 - override: `CLAWHUB_CONFIG_PATH` (legacy `CLAWDHUB_CONFIG_PATH`)

 ## Commands
@@ -132,12 +135,13 @@ Stores your API token + cached registry URL.
  - refuses by default
  - overwrites with `--force` (or prompt, if interactive)

-### `publish <path>`
+### `skill publish <path>`

 - Publishes via `POST /api/v1/skills` (multipart).
 - Requires semver: `--version 1.2.3`.
 - Publishing a skill means it is released under `MIT-0` on ClawHub.
 - Published skills are free to use, modify, and redistribute without attribution.
+- Legacy alias: `publish <path>`.

 ### `delete <slug>`

@@ -208,11 +212,69 @@ Stores your API token + cached registry URL.
 - `--fuzzy` resolves the handle via fuzzy user search (admin only).
 - `--yes` skips confirmation.

-### `package publish <path>`
+### `package publish <source>`

 - Publishes a code plugin or bundle plugin via `POST /api/v1/packages`.
+- `<source>` accepts:
+  - Local folder path: `./my-plugin`
+  - GitHub repo: `owner/repo` or `owner/repo@ref`
+  - GitHub URL: `https://github.com/owner/repo`
+- Metadata is auto-detected from `package.json`, `openclaw.plugin.json`, and `openclaw.bundle.json`.
+- For GitHub sources, source attribution is auto-populated from the repo, resolved commit, ref, and subpath.
+- For local folders, source attribution is auto-detected from local git when the origin remote points at GitHub.
+- External code plugins must declare `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion` explicitly.
+  Top-level `package.json.version` is not used as a fallback for publish validation.
+- `--dry-run` previews the resolved publish payload without uploading.
+- `--json` emits machine-readable output for CI.
 - `--owner <handle>` lets admins publish under a shared owner account while keeping their own token as the actor.
- Code plugins still require `--source-repo` and `--source-commit`.
+- Existing flags (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) still work as overrides.
+- Private GitHub repos require `GITHUB_TOKEN`.
+
+#### GitHub Actions
+
+ClawHub also ships an official reusable workflow at
+[`/.github/workflows/package-publish.yml`](../.github/workflows/package-publish.yml)
+for plugin repos.
+
+Typical caller setup:
+
+```yaml
+name: Package Publish
+
+on:
+  pull_request:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  dry-run:
+    if: github.event_name == 'pull_request'
+    uses: openclaw/clawhub/.github/workflows/package-publish.yml@main
+    with:
+      dry_run: true
+
+  publish:
+    if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/')
+    permissions:
+      contents: read
+      id-token: write
+    uses: openclaw/clawhub/.github/workflows/package-publish.yml@main
+    with:
+      dry_run: false
+    secrets:
+      clawhub_token: ${{ secrets.CLAWHUB_TOKEN }}
+```
+
+Notes:
+
+- The reusable workflow defaults `source` to the caller repo.
+- `pull_request` should use `dry_run: true` so CI stays non-polluting.
+- Real publishes should be limited to trusted events such as `workflow_dispatch` or tag pushes.
+- Trusted publishing without a secret only works on `workflow_dispatch`; tag pushes still need `clawhub_token`.
+- Keep `clawhub_token` available for first publish, untrusted packages, or break-glass publishes.
+- The workflow uploads the JSON result as an artifact and exposes it as workflow outputs.

 ### `sync`

@@ -25,21 +25,54 @@ bunx convex deploy
 Or use the GitHub Actions pipeline:

 ```bash
-gh workflow run deploy.yml
+gh workflow run deploy.yml --repo openclaw/clawhub --ref main
 ```

-GitHub Actions secrets required for `deploy.yml`:
+Production deploy notes:

- `CONVEX_DEPLOY_KEY`
- Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON` for authenticated smoke coverage
+- `deploy.yml` is manual-only (`workflow_dispatch`). Merging to `main` does not deploy.
+- The workflow must be started from `main`.
+- Deploy targets:
+  - `full`: deploy Convex, verify contract, wait for the matching Vercel production deploy, then run smoke tests
+  - `backend`: deploy Convex, verify contract, then run smoke tests against current production
+  - `frontend`: wait for the Vercel production deploy for the selected `main` SHA, then run smoke tests
+- `frontend` does not call `vercel deploy` directly yet. It relies on the existing Vercel Git-based production deploy for that SHA.
+- The real deploy job uses the GitHub `Production` environment for deploy secrets, but it does not wait for a separate approval.
+- Required `Production` environment secret: `CONVEX_DEPLOY_KEY`.
+- Optional `Production` environment secret: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON` for authenticated smoke coverage.

-`deploy.yml` now fails in preflight if `CONVEX_DEPLOY_KEY` is missing. Web deploy
-verification no longer depends on a separate Vercel token in GitHub Actions.
+## CLI npm release
+
+The `clawhub` CLI package is released separately from the app deploy.
+Only stable releases are supported here: `vX.Y.Z`.
+
+Use the GitHub Actions workflow:
+
+```bash
+gh workflow run clawhub-cli-npm-release.yml \
+  --repo openclaw/clawhub \
+  --ref main \
+  -f tag=v0.10.0 \
+  -f preflight_only=true
+```
+
+Then rerun the same workflow from `main` with:
+
+- the same `tag`
+- `preflight_only=false`
+- `preflight_run_id=<successful preflight run id>`
+
+CLI release notes:
+
+- Real publishes are manual-only and require the workflow to be started from `main`.
+- The publish job waits at the GitHub `npm-release` environment for approval.
+- npm auth is handled through npm trusted publishing, not an `NPM_TOKEN`.
+- npm trusted publisher must be configured for package `clawhub` with repository `openclaw/clawhub`, workflow `clawhub-cli-npm-release.yml`, and environment `npm-release`.

 That workflow assumes Vercel Git integration is enabled for this repo. It does
-not run `vercel deploy` directly; instead it waits for the GitHub commit status
-`Vercel – clawhub` for the pushed SHA, then runs smoke tests against
-production.
+not run `vercel deploy` directly; frontend-related steps wait for the GitHub
+commit status `Vercel – clawhub` for the selected SHA, then run smoke tests
+against production.

 Ensure Convex env is set (auth + embeddings):

@@ -8,6 +8,24 @@ read_when:

 # GitHub import (public repos)

+## CLI
+
+For plugin authors, the recommended GitHub import path is now the CLI:
+
+```bash
+clawhub package publish owner/repo
+clawhub package publish owner/repo@v1.0.0
+clawhub package publish https://github.com/owner/repo
+
+# Preview only
+clawhub package publish owner/repo --dry-run
+
+# CI-friendly output
+clawhub package publish owner/repo --dry-run --json
+```
+
+This keeps package metadata zero-config where possible and auto-populates GitHub provenance.
+
 Goal: paste a GitHub URL → auto-detect skill → preview files → publish (selective) → persist provenance.

 Non-goal (v1): private repos (no OAuth/PAT support).
@@ -237,6 +237,9 @@ Notes:

 - If neither `version` nor `tag` is provided, uses the latest version.
 - Includes normalized verification status plus scanner-specific details.
+- `security.capabilityTags` includes deterministic capability/risk labels such as
+  `crypto`, `requires-wallet`, `can-make-purchases`, `can-sign-transactions`,
+  `requires-oauth-token`, and `posts-externally` when detected.
 - `security.hasScanResult` is `true` only when a scanner produced a definitive verdict (`clean`, `suspicious`, or `malicious`).
 - `moderation` is a current skill-level moderation snapshot derived from the latest version.
 - When querying a historical version, check `moderation.matchesRequestedVersion` and `moderation.sourceVersion` before treating `moderation` and `security` as the same version context.
@@ -47,9 +47,9 @@ read_when:
  - `SKILL.md`
  - `notes.md`
 - Publish:
-  - `bun clawhub publish . --slug clawhub-manual-<ts> --name "Manual <ts>" --version 1.0.0 --tags latest`
+  - `bun clawhub skill publish . --slug clawhub-manual-<ts> --name "Manual <ts>" --version 1.0.0 --tags latest`
 - Publish update with empty changelog:
-  - `bun clawhub publish . --slug clawhub-manual-<ts> --name "Manual <ts>" --version 1.0.1 --tags latest`
+  - `bun clawhub skill publish . --slug clawhub-manual-<ts> --name "Manual <ts>" --version 1.0.1 --tags latest`

 ## Delete / undelete (owner/admin)

@@ -485,4 +485,3 @@ Add or update tests for:
  drift
 - Do not keep slug-only and scoped lookup logic equally primary; one must win
 - Prefer publisher abstraction over `ownerUserId | ownerOrgId` unions
-
@@ -98,7 +98,7 @@ EOF
 Publish:

 ```bash
-bun clawhub publish . \
+bun clawhub skill publish . \
  --slug clawhub-demo-$(date +%s) \
  --name "Demo $(date +%s)" \
  --version 1.0.0 \
@@ -77,7 +77,7 @@ clawhub sync --root /path/to/skills
 - Options:
  - keep local edits; skip updating
  - overwrite: `clawhub update <slug> --force`
-  - publish as fork: copy to new folder/slug then `clawhub publish ... --fork-of upstream@version`
+  - publish as fork: copy to new folder/slug then `clawhub skill publish ... --fork-of upstream@version`

 ## `GET /api/*` works locally but not on Vercel

@@ -86,9 +86,8 @@ clawhub sync --root /path/to/skills

 ## `deploy.yml` fails before deploy or smoke runs

- Ensure GitHub Actions secrets exist for the repo:
+- Ensure GitHub Actions secrets exist on the `Production` environment:
  - `CONVEX_DEPLOY_KEY`
-  - `VERCEL_TOKEN`
  - Optional: `PLAYWRIGHT_AUTH_STORAGE_STATE_JSON`
 - Missing required deploy secrets now fails the preflight job immediately.
 - If the optional Playwright auth secret is missing, authenticated smoke canaries will skip; deploy should still proceed.
@@ -1,552 +0,0 @@
-/* @vitest-environment node */
-
-import { spawnSync } from "node:child_process";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  ApiRoutes,
-  ApiV1SearchResponseSchema,
-  ApiV1WhoamiResponseSchema,
-  parseArk,
-} from "clawhub-schema";
-import { unzipSync } from "fflate";
-import { Agent, setGlobalDispatcher } from "undici";
-import { describe, expect, it } from "vitest";
-import { readGlobalConfig } from "../packages/clawdhub/src/config";
-
-const REQUEST_TIMEOUT_MS = 15_000;
-
-try {
-  setGlobalDispatcher(
-    new Agent({
-      connect: { timeout: REQUEST_TIMEOUT_MS },
-    }),
-  );
-} catch {
-  // ignore dispatcher setup failures
-}
-
-function mustGetToken() {
-  const fromEnv = process.env.CLAWHUB_E2E_TOKEN?.trim() || process.env.CLAWDHUB_E2E_TOKEN?.trim();
-  if (fromEnv) return fromEnv;
-  return null;
-}
-
-function getRegistry() {
-  return (
-    process.env.CLAWHUB_REGISTRY?.trim() ||
-    process.env.CLAWDHUB_REGISTRY?.trim() ||
-    "https://clawhub.ai"
-  );
-}
-
-function getSite() {
-  return (
-    process.env.CLAWHUB_SITE?.trim() || process.env.CLAWDHUB_SITE?.trim() || "https://clawhub.ai"
-  );
-}
-
-async function makeTempConfig(registry: string, token: string | null) {
-  const dir = await mkdtemp(join(tmpdir(), "clawhub-e2e-"));
-  const path = join(dir, "config.json");
-  await writeFile(
-    path,
-    `${JSON.stringify({ registry, token: token || undefined }, null, 2)}\n`,
-    "utf8",
-  );
-  return { dir, path };
-}
-
-async function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(new Error("Timeout")), REQUEST_TIMEOUT_MS);
-  try {
-    return await fetch(input, { ...init, signal: controller.signal });
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-describe("clawhub e2e", () => {
-  it("prints CLI version via --cli-version", async () => {
-    const result = spawnSync("bun", ["clawhub", "--cli-version"], {
-      cwd: process.cwd(),
-      encoding: "utf8",
-    });
-    expect(result.status).toBe(0);
-    expect(result.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
-  });
-
-  it("search endpoint returns a results array (schema parse)", async () => {
-    const registry = getRegistry();
-    const url = new URL(ApiRoutes.search, registry);
-    url.searchParams.set("q", "gif");
-    url.searchParams.set("limit", "5");
-
-    const response = await fetchWithTimeout(url.toString(), {
-      headers: { Accept: "application/json" },
-    });
-    expect(response.ok).toBe(true);
-    const json = (await response.json()) as unknown;
-    const parsed = parseArk(ApiV1SearchResponseSchema, json, "API response");
-    expect(Array.isArray(parsed.results)).toBe(true);
-  });
-
-  it("cli search does not error on multi-result responses", async () => {
-    const registry = getRegistry();
-    const site = getSite();
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-
-    const cfg = await makeTempConfig(registry, token);
-    try {
-      const workdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-workdir-"));
-      const result = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "search",
-          "gif",
-          "--limit",
-          "5",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      await rm(workdir, { recursive: true, force: true });
-
-      expect(result.status).toBe(0);
-      expect(result.stderr).not.toMatch(/API response:/);
-    } finally {
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  });
-
-  it("assumes a logged-in user (whoami succeeds)", async () => {
-    const registry = getRegistry();
-    const site = getSite();
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-    if (!token) {
-      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
-    }
-
-    const cfg = await makeTempConfig(registry, token);
-    try {
-      const whoamiUrl = new URL(ApiRoutes.whoami, registry);
-      const whoamiRes = await fetchWithTimeout(whoamiUrl.toString(), {
-        headers: { Accept: "application/json", Authorization: `Bearer ${token}` },
-      });
-      expect(whoamiRes.ok).toBe(true);
-      const whoami = parseArk(
-        ApiV1WhoamiResponseSchema,
-        (await whoamiRes.json()) as unknown,
-        "Whoami",
-      );
-      expect(whoami.user).toBeTruthy();
-
-      const result = spawnSync(
-        "bun",
-        ["clawhub", "whoami", "--site", site, "--registry", registry],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(result.status).toBe(0);
-      expect(result.stderr).not.toMatch(/not logged in|unauthorized|error:/i);
-    } finally {
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  });
-
-  it("sync dry-run finds skills from an explicit root", async () => {
-    const registry = getRegistry();
-    const site = getSite();
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-    if (!token) {
-      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
-    }
-
-    const cfg = await makeTempConfig(registry, token);
-    const root = await mkdtemp(join(tmpdir(), "clawhub-e2e-sync-"));
-    try {
-      const skillDir = join(root, "cool-skill");
-      await mkdir(skillDir, { recursive: true });
-      await writeFile(join(skillDir, "SKILL.md"), "# Skill\n", "utf8");
-
-      const result = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "sync",
-          "--dry-run",
-          "--all",
-          "--root",
-          root,
-          "--site",
-          site,
-          "--registry",
-          registry,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(result.status).toBe(0);
-      expect(result.stderr).not.toMatch(/error:/i);
-      expect(result.stdout).toMatch(/Dry run/i);
-    } finally {
-      await rm(root, { recursive: true, force: true });
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  });
-
-  it("sync dry-run finds skills from clawdbot.json roots", async () => {
-    const registry = getRegistry();
-    const site = getSite();
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-    if (!token) {
-      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
-    }
-
-    const cfg = await makeTempConfig(registry, token);
-    const root = await mkdtemp(join(tmpdir(), "clawhub-e2e-clawdbot-"));
-    const stateDir = join(root, "state");
-    const configPath = join(root, "clawdbot.json");
-    const workspace = join(root, "clawd-work");
-    const skillsRoot = join(workspace, "skills");
-    const skillDir = join(skillsRoot, "auto-skill");
-
-    try {
-      await mkdir(skillDir, { recursive: true });
-      await writeFile(join(skillDir, "SKILL.md"), "# Skill\n", "utf8");
-
-      const config = `{
-        // JSON5-style comments + trailing commas
-        routing: {
-          agents: {
-            work: { name: 'Work', workspace: '${workspace}', },
-          },
-        },
-      }`;
-      await writeFile(configPath, config, "utf8");
-
-      const result = spawnSync(
-        "bun",
-        ["clawhub", "sync", "--dry-run", "--all", "--site", site, "--registry", registry],
-        {
-          cwd: process.cwd(),
-          env: {
-            ...process.env,
-            CLAWHUB_CONFIG_PATH: cfg.path,
-            CLAWHUB_DISABLE_TELEMETRY: "1",
-            CLAWDBOT_CONFIG_PATH: configPath,
-            CLAWDBOT_STATE_DIR: stateDir,
-          },
-          encoding: "utf8",
-        },
-      );
-      expect(result.status).toBe(0);
-      expect(result.stderr).not.toMatch(/error:/i);
-      expect(result.stdout).toMatch(/Dry run/i);
-      expect(result.stdout).toMatch(/auto-skill/i);
-    } finally {
-      await rm(root, { recursive: true, force: true });
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  });
-
-  it("publishes, deletes, and undeletes a skill (logged-in)", async () => {
-    const registry = getRegistry();
-    const site = getSite();
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-    if (!token) {
-      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
-    }
-
-    const cfg = await makeTempConfig(registry, token);
-    const workdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-publish-"));
-    const installWorkdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-install-"));
-    const slug = `e2e-${Date.now()}`;
-    const skillDir = join(workdir, slug);
-
-    try {
-      await mkdir(skillDir, { recursive: true });
-      await writeFile(join(skillDir, "SKILL.md"), `# ${slug}\n\nHello.\n`, "utf8");
-
-      const publish1 = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "publish",
-          skillDir,
-          "--slug",
-          slug,
-          "--name",
-          `E2E ${slug}`,
-          "--version",
-          "1.0.0",
-          "--tags",
-          "latest",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(publish1.status).toBe(0);
-      expect(publish1.stderr).not.toMatch(/changelog required/i);
-
-      const publish2 = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "publish",
-          skillDir,
-          "--slug",
-          slug,
-          "--name",
-          `E2E ${slug}`,
-          "--version",
-          "1.0.1",
-          "--tags",
-          "latest",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(publish2.status).toBe(0);
-      expect(publish2.stderr).not.toMatch(/changelog required/i);
-
-      const downloadUrl = new URL(ApiRoutes.download, registry);
-      downloadUrl.searchParams.set("slug", slug);
-      downloadUrl.searchParams.set("version", "1.0.1");
-      const zipRes = await fetchWithTimeout(downloadUrl.toString());
-      expect(zipRes.ok).toBe(true);
-      const zipBytes = new Uint8Array(await zipRes.arrayBuffer());
-      const unzipped = unzipSync(zipBytes);
-      expect(Object.keys(unzipped)).toContain("SKILL.md");
-
-      const install = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "install",
-          slug,
-          "--version",
-          "1.0.0",
-          "--force",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          installWorkdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(install.status).toBe(0);
-
-      const list = spawnSync(
-        "bun",
-        ["clawhub", "list", "--site", site, "--registry", registry, "--workdir", installWorkdir],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(list.status).toBe(0);
-      expect(list.stdout).toMatch(new RegExp(`${slug}\\s+1\\.0\\.0`));
-
-      const update = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "update",
-          slug,
-          "--force",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          installWorkdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(update.status).toBe(0);
-
-      const metaUrl = new URL(`${ApiRoutes.skills}/${slug}`, registry);
-      const metaRes = await fetchWithTimeout(metaUrl.toString(), {
-        headers: { Accept: "application/json" },
-      });
-      expect(metaRes.status).toBe(200);
-
-      const del = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "delete",
-          slug,
-          "--yes",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(del.status).toBe(0);
-
-      const metaAfterDelete = await fetchWithTimeout(metaUrl.toString(), {
-        headers: { Accept: "application/json" },
-      });
-      expect(metaAfterDelete.status).toBe(404);
-
-      const downloadAfterDelete = await fetchWithTimeout(downloadUrl.toString());
-      expect(downloadAfterDelete.status).toBe(404);
-
-      const undelete = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "undelete",
-          slug,
-          "--yes",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      expect(undelete.status).toBe(0);
-
-      const metaAfterUndelete = await fetchWithTimeout(metaUrl.toString(), {
-        headers: { Accept: "application/json" },
-      });
-      expect(metaAfterUndelete.status).toBe(200);
-    } finally {
-      const cleanup = spawnSync(
-        "bun",
-        [
-          "clawhub",
-          "delete",
-          slug,
-          "--yes",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      if (cleanup.status !== 0) {
-        // best-effort cleanup
-      }
-      await rm(workdir, { recursive: true, force: true });
-      await rm(installWorkdir, { recursive: true, force: true });
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  }, 180_000);
-
-  it("delete returns proper error for non-existent skill", async () => {
-    const registry = process.env.CLAWDHUB_REGISTRY?.trim() || "https://clawdhub.com";
-    const site = process.env.CLAWDHUB_SITE?.trim() || "https://clawdhub.com";
-    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
-    if (!token) {
-      throw new Error("Missing token. Set CLAWDHUB_E2E_TOKEN or run: bun clawdhub auth login");
-    }
-
-    const cfg = await makeTempConfig(registry, token);
-    const workdir = await mkdtemp(join(tmpdir(), "clawdhub-e2e-delete-"));
-    const nonExistentSlug = `non-existent-skill-${Date.now()}`;
-
-    try {
-      const del = spawnSync(
-        "bun",
-        [
-          "clawdhub",
-          "delete",
-          nonExistentSlug,
-          "--yes",
-          "--site",
-          site,
-          "--registry",
-          registry,
-          "--workdir",
-          workdir,
-        ],
-        {
-          cwd: process.cwd(),
-          env: { ...process.env, CLAWDHUB_CONFIG_PATH: cfg.path, CLAWDHUB_DISABLE_TELEMETRY: "1" },
-          encoding: "utf8",
-        },
-      );
-      // Should fail with non-zero exit code
-      expect(del.status).not.toBe(0);
-      // Error should mention "not found" - not generic "Unauthorized"
-      const output = (del.stdout + del.stderr).toLowerCase();
-      expect(output).toMatch(/not found|404|does not exist/i);
-      expect(output).not.toMatch(/unauthorized/i);
-    } finally {
-      await rm(workdir, { recursive: true, force: true });
-      await rm(cfg.dir, { recursive: true, force: true });
-    }
-  }, 30_000);
-});
@@ -0,0 +1,658 @@
+/* @vitest-environment node */
+
+import { spawnSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ApiRoutes,
+  ApiV1SearchResponseSchema,
+  ApiV1WhoamiResponseSchema,
+  parseArk,
+} from "clawhub-schema";
+import { unzipSync } from "fflate";
+import { Agent, setGlobalDispatcher } from "undici";
+import { describe, expect, it } from "vitest";
+import { readGlobalConfig } from "../packages/clawhub/src/config";
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+try {
+  setGlobalDispatcher(
+    new Agent({
+      connect: { timeout: REQUEST_TIMEOUT_MS },
+    }),
+  );
+} catch {
+  // ignore dispatcher setup failures
+}
+
+function mustGetToken() {
+  const fromEnv = process.env.CLAWHUB_E2E_TOKEN?.trim() || process.env.CLAWDHUB_E2E_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  return null;
+}
+
+function getRegistry() {
+  return (
+    process.env.CLAWHUB_REGISTRY?.trim() ||
+    process.env.CLAWDHUB_REGISTRY?.trim() ||
+    "https://clawhub.ai"
+  );
+}
+
+function getSite() {
+  return (
+    process.env.CLAWHUB_SITE?.trim() || process.env.CLAWDHUB_SITE?.trim() || "https://clawhub.ai"
+  );
+}
+
+function buildE2ESkillMarkdown(slug: string) {
+  return `# ${slug}
+
+## What it does
+
+This skill is used by the ClawHub CLI end-to-end suite to verify publish, install,
+update, delete, and undelete flows against a real registry.
+
+## Usage
+
+- Run the skill after installation to confirm the package can be discovered.
+- Use the published version history to verify update behavior.
+- Delete and undelete the listing to confirm ownership actions still work.
+
+## Notes
+
+This content is intentionally specific and non-templated so the publish pipeline
+accepts it during automated tests.
+`;
+}
+
+function allowLiveMutations() {
+  const value = process.env.CLAWHUB_E2E_ALLOW_MUTATIONS?.trim();
+  return value === "1" || value?.toLowerCase() === "true";
+}
+
+const itIfLiveMutations = allowLiveMutations() ? it : it.skip;
+
+async function makeTempConfig(registry: string, token: string | null) {
+  const dir = await mkdtemp(join(tmpdir(), "clawhub-e2e-"));
+  const path = join(dir, "config.json");
+  await writeFile(
+    path,
+    `${JSON.stringify({ registry, token: token || undefined }, null, 2)}\n`,
+    "utf8",
+  );
+  return { dir, path };
+}
+
+async function fetchWithTimeout(input: RequestInfo | URL, init?: RequestInit) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(new Error("Timeout")), REQUEST_TIMEOUT_MS);
+  try {
+    return await fetch(input, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+describe("clawhub e2e", () => {
+  it("prints CLI version via --cli-version", async () => {
+    const result = spawnSync("bun", ["clawhub", "--cli-version"], {
+      cwd: process.cwd(),
+      encoding: "utf8",
+    });
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  it("search endpoint returns a results array (schema parse)", async () => {
+    const registry = getRegistry();
+    const url = new URL(ApiRoutes.search, registry);
+    url.searchParams.set("q", "gif");
+    url.searchParams.set("limit", "5");
+
+    const response = await fetchWithTimeout(url.toString(), {
+      headers: { Accept: "application/json" },
+    });
+    expect(response.ok).toBe(true);
+    const json = (await response.json()) as unknown;
+    const parsed = parseArk(ApiV1SearchResponseSchema, json, "API response");
+    expect(Array.isArray(parsed.results)).toBe(true);
+  });
+
+  it("cli search does not error on multi-result responses", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+
+    const cfg = await makeTempConfig(registry, token);
+    try {
+      const workdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-workdir-"));
+      const result = spawnSync(
+        "bun",
+        [
+          "clawhub",
+          "search",
+          "gif",
+          "--limit",
+          "5",
+          "--site",
+          site,
+          "--registry",
+          registry,
+          "--workdir",
+          workdir,
+        ],
+        {
+          cwd: process.cwd(),
+          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+          encoding: "utf8",
+        },
+      );
+      await rm(workdir, { recursive: true, force: true });
+
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/API response:/);
+    } finally {
+      await rm(cfg.dir, { recursive: true, force: true });
+    }
+  });
+
+  it("assumes a logged-in user (whoami succeeds)", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+    if (!token) {
+      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
+    }
+
+    const cfg = await makeTempConfig(registry, token);
+    try {
+      const whoamiUrl = new URL(ApiRoutes.whoami, registry);
+      const whoamiRes = await fetchWithTimeout(whoamiUrl.toString(), {
+        headers: { Accept: "application/json", Authorization: `Bearer ${token}` },
+      });
+      expect(whoamiRes.ok).toBe(true);
+      const whoami = parseArk(
+        ApiV1WhoamiResponseSchema,
+        (await whoamiRes.json()) as unknown,
+        "Whoami",
+      );
+      expect(whoami.user).toBeTruthy();
+
+      const result = spawnSync(
+        "bun",
+        ["clawhub", "whoami", "--site", site, "--registry", registry],
+        {
+          cwd: process.cwd(),
+          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+          encoding: "utf8",
+        },
+      );
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/not logged in|unauthorized|error:/i);
+    } finally {
+      await rm(cfg.dir, { recursive: true, force: true });
+    }
+  });
+
+  it("sync dry-run finds skills from an explicit root", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+    if (!token) {
+      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
+    }
+
+    const cfg = await makeTempConfig(registry, token);
+    const root = await mkdtemp(join(tmpdir(), "clawhub-e2e-sync-"));
+    try {
+      const skillDir = join(root, "cool-skill");
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, "SKILL.md"), "# Skill\n", "utf8");
+
+      const result = spawnSync(
+        "bun",
+        [
+          "clawhub",
+          "sync",
+          "--dry-run",
+          "--all",
+          "--root",
+          root,
+          "--site",
+          site,
+          "--registry",
+          registry,
+        ],
+        {
+          cwd: process.cwd(),
+          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+          encoding: "utf8",
+        },
+      );
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/error:/i);
+      expect(result.stdout).toMatch(/Dry run/i);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+      await rm(cfg.dir, { recursive: true, force: true });
+    }
+  });
+
+  it("sync dry-run finds skills from clawdbot.json roots", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+    if (!token) {
+      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
+    }
+
+    const cfg = await makeTempConfig(registry, token);
+    const root = await mkdtemp(join(tmpdir(), "clawhub-e2e-clawdbot-"));
+    const stateDir = join(root, "state");
+    const configPath = join(root, "clawdbot.json");
+    const workspace = join(root, "clawd-work");
+    const skillsRoot = join(workspace, "skills");
+    const skillDir = join(skillsRoot, "auto-skill");
+
+    try {
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(join(skillDir, "SKILL.md"), "# Skill\n", "utf8");
+
+      const config = `{
+        // JSON5-style comments + trailing commas
+        routing: {
+          agents: {
+            work: { name: 'Work', workspace: '${workspace}', },
+          },
+        },
+      }`;
+      await writeFile(configPath, config, "utf8");
+
+      const result = spawnSync(
+        "bun",
+        ["clawhub", "sync", "--dry-run", "--all", "--site", site, "--registry", registry],
+        {
+          cwd: process.cwd(),
+          env: {
+            ...process.env,
+            CLAWHUB_CONFIG_PATH: cfg.path,
+            CLAWHUB_DISABLE_TELEMETRY: "1",
+            CLAWDBOT_CONFIG_PATH: configPath,
+            CLAWDBOT_STATE_DIR: stateDir,
+          },
+          encoding: "utf8",
+        },
+      );
+      expect(result.status).toBe(0);
+      expect(result.stderr).not.toMatch(/error:/i);
+      expect(result.stdout).toMatch(/Dry run/i);
+      expect(result.stdout).toMatch(/auto-skill/i);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+      await rm(cfg.dir, { recursive: true, force: true });
+    }
+  });
+
+  it("package publish --dry-run from a GitHub repo shows a summary", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const result = spawnSync(
+      "bun",
+      [
+        "clawhub",
+        "package",
+        "publish",
+        "pwrdrvr/openclaw-codex-app-server",
+        "--dry-run",
+        "--site",
+        site,
+        "--registry",
+        registry,
+      ],
+      {
+        cwd: process.cwd(),
+        env: { ...process.env, CLAWHUB_DISABLE_TELEMETRY: "1" },
+        encoding: "utf8",
+      },
+    );
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toMatch(/Dry run/i);
+    expect(result.stdout).toMatch(/openclaw-codex-app-server/);
+    expect(result.stdout).toMatch(/code-plugin/i);
+    expect(result.stdout).toMatch(/openclaw\.plugin\.json/);
+  }, 30_000);
+
+  it("package publish --dry-run --json from GitHub outputs valid JSON", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const result = spawnSync(
+      "bun",
+      [
+        "clawhub",
+        "package",
+        "publish",
+        "pwrdrvr/openclaw-codex-app-server",
+        "--dry-run",
+        "--json",
+        "--site",
+        site,
+        "--registry",
+        registry,
+      ],
+      {
+        cwd: process.cwd(),
+        env: { ...process.env, CLAWHUB_DISABLE_TELEMETRY: "1" },
+        encoding: "utf8",
+      },
+    );
+
+    expect(result.status).toBe(0);
+    const output = JSON.parse(result.stdout.trim()) as Record<string, unknown>;
+    expect(String(output.name)).toMatch(/openclaw-codex-app-server/);
+    expect(output.family).toBe("code-plugin");
+    expect(Number(output.files)).toBeGreaterThan(0);
+    expect(output).not.toHaveProperty("releaseId");
+  }, 30_000);
+
+  it("package publish help shows the new source argument and flags", async () => {
+    const result = spawnSync("bun", ["clawhub", "package", "publish", "--help"], {
+      cwd: process.cwd(),
+      encoding: "utf8",
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stdout).toMatch(/<source>/);
+    expect(result.stdout).toMatch(/--dry-run/);
+    expect(result.stdout).toMatch(/--json/);
+  });
+
+  itIfLiveMutations(
+    "publishes, deletes, and undeletes a skill (logged-in)",
+    async () => {
+      const registry = getRegistry();
+      const site = getSite();
+      const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+      if (!token) {
+        throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
+      }
+
+      const cfg = await makeTempConfig(registry, token);
+      const workdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-publish-"));
+      const installWorkdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-install-"));
+      const slug = `e2e-${Date.now()}`;
+      const skillDir = join(workdir, slug);
+
+      try {
+        await mkdir(skillDir, { recursive: true });
+        await writeFile(join(skillDir, "SKILL.md"), buildE2ESkillMarkdown(slug), "utf8");
+
+        const publish1 = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "publish",
+            skillDir,
+            "--slug",
+            slug,
+            "--name",
+            `E2E ${slug}`,
+            "--version",
+            "1.0.0",
+            "--tags",
+            "latest",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            workdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(publish1.status).toBe(0);
+        expect(publish1.stderr).not.toMatch(/changelog required/i);
+
+        const publish2 = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "publish",
+            skillDir,
+            "--slug",
+            slug,
+            "--name",
+            `E2E ${slug}`,
+            "--version",
+            "1.0.1",
+            "--tags",
+            "latest",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            workdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(publish2.status).toBe(0);
+        expect(publish2.stderr).not.toMatch(/changelog required/i);
+
+        const downloadUrl = new URL(ApiRoutes.download, registry);
+        downloadUrl.searchParams.set("slug", slug);
+        downloadUrl.searchParams.set("version", "1.0.1");
+        const zipRes = await fetchWithTimeout(downloadUrl.toString());
+        expect(zipRes.ok).toBe(true);
+        const zipBytes = new Uint8Array(await zipRes.arrayBuffer());
+        const unzipped = unzipSync(zipBytes);
+        expect(Object.keys(unzipped)).toContain("SKILL.md");
+
+        const install = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "install",
+            slug,
+            "--version",
+            "1.0.0",
+            "--force",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            installWorkdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(install.status).toBe(0);
+
+        const list = spawnSync(
+          "bun",
+          ["clawhub", "list", "--site", site, "--registry", registry, "--workdir", installWorkdir],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(list.status).toBe(0);
+        expect(list.stdout).toMatch(new RegExp(`${slug}\\s+1\\.0\\.0`));
+
+        const update = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "update",
+            slug,
+            "--force",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            installWorkdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(update.status).toBe(0);
+
+        const metaUrl = new URL(`${ApiRoutes.skills}/${slug}`, registry);
+        const metaRes = await fetchWithTimeout(metaUrl.toString(), {
+          headers: { Accept: "application/json" },
+        });
+        expect(metaRes.status).toBe(200);
+
+        const del = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "delete",
+            slug,
+            "--yes",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            workdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(del.status).toBe(0);
+
+        const metaAfterDelete = await fetchWithTimeout(metaUrl.toString(), {
+          headers: { Accept: "application/json" },
+        });
+        expect(metaAfterDelete.status).toBe(404);
+
+        const downloadAfterDelete = await fetchWithTimeout(downloadUrl.toString());
+        expect(downloadAfterDelete.status).toBe(404);
+
+        const undelete = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "undelete",
+            slug,
+            "--yes",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            workdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        expect(undelete.status).toBe(0);
+
+        const metaAfterUndelete = await fetchWithTimeout(metaUrl.toString(), {
+          headers: { Accept: "application/json" },
+        });
+        expect(metaAfterUndelete.status).toBe(200);
+      } finally {
+        const cleanup = spawnSync(
+          "bun",
+          [
+            "clawhub",
+            "delete",
+            slug,
+            "--yes",
+            "--site",
+            site,
+            "--registry",
+            registry,
+            "--workdir",
+            workdir,
+          ],
+          {
+            cwd: process.cwd(),
+            env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+            encoding: "utf8",
+          },
+        );
+        if (cleanup.status !== 0) {
+          // best-effort cleanup
+        }
+        await rm(workdir, { recursive: true, force: true });
+        await rm(installWorkdir, { recursive: true, force: true });
+        await rm(cfg.dir, { recursive: true, force: true });
+      }
+    },
+    180_000,
+  );
+
+  it("delete returns proper error for non-existent skill", async () => {
+    const registry = getRegistry();
+    const site = getSite();
+    const token = mustGetToken() ?? (await readGlobalConfig())?.token ?? null;
+    if (!token) {
+      throw new Error("Missing token. Set CLAWHUB_E2E_TOKEN or run: bun clawhub auth login");
+    }
+
+    const cfg = await makeTempConfig(registry, token);
+    const workdir = await mkdtemp(join(tmpdir(), "clawhub-e2e-delete-"));
+    const nonExistentSlug = `non-existent-skill-${Date.now()}`;
+
+    try {
+      const del = spawnSync(
+        "bun",
+        [
+          "clawhub",
+          "delete",
+          nonExistentSlug,
+          "--yes",
+          "--site",
+          site,
+          "--registry",
+          registry,
+          "--workdir",
+          workdir,
+        ],
+        {
+          cwd: process.cwd(),
+          env: { ...process.env, CLAWHUB_CONFIG_PATH: cfg.path, CLAWHUB_DISABLE_TELEMETRY: "1" },
+          encoding: "utf8",
+        },
+      );
+      // Should fail with non-zero exit code
+      expect(del.status).not.toBe(0);
+      // Error should mention "not found" - not generic "Unauthorized"
+      const output = (del.stdout + del.stderr).toLowerCase();
+      expect(output).toMatch(/not found|404|does not exist/i);
+      expect(output).not.toMatch(/unauthorized/i);
+    } finally {
+      await rm(workdir, { recursive: true, force: true });
+      await rm(cfg.dir, { recursive: true, force: true });
+    }
+  }, 30_000);
+});
@@ -0,0 +1,135 @@
+import { expect, test } from "@playwright/test";
+import { expectHealthyPage, trackRuntimeErrors } from "./helpers/runtimeErrors";
+
+// Only run in mobile projects — skip on desktop
+test.beforeEach(({}, testInfo) => {
+  test.skip(
+    !testInfo.project.name.includes("mobile"),
+    "mobile-only test",
+  );
+});
+
+test("browse page has no horizontal overflow on mobile", async ({ page }) => {
+  const errors = trackRuntimeErrors(page);
+
+  await page.goto("/skills?sort=downloads", { waitUntil: "domcontentloaded" });
+  await expect(page.getByRole("heading", { name: /^Skills/ })).toBeVisible();
+  await expect(page.locator(".skill-card, .skill-list-item").first()).toBeVisible();
+
+  const scrollWidth = await page.evaluate(() => document.documentElement.scrollWidth);
+  const clientWidth = await page.evaluate(() => document.documentElement.clientWidth);
+  expect(scrollWidth).toBeLessThanOrEqual(clientWidth + 1);
+
+  await expectHealthyPage(page, errors);
+});
+
+test("browse sidebar toggle opens and closes filters", async ({ page }) => {
+  const errors = trackRuntimeErrors(page);
+
+  await page.goto("/skills?sort=downloads", { waitUntil: "domcontentloaded" });
+  await expect(page.getByRole("heading", { name: /^Skills/ })).toBeVisible();
+
+  const filterButton = page.getByRole("button", { name: "Toggle filters" });
+  await expect(filterButton).toBeVisible();
+
+  // Sidebar should be hidden initially
+  const sidebar = page.locator(".browse-sidebar");
+  await expect(sidebar).not.toBeVisible();
+
+  // Open sidebar
+  await filterButton.click();
+  await expect(sidebar).toBeVisible();
+
+  // Close sidebar
+  await filterButton.click();
+  await expect(sidebar).not.toBeVisible();
+
+  await expectHealthyPage(page, errors);
+});
+
+test("card grid fits within viewport on mobile", async ({ page }) => {
+  const errors = trackRuntimeErrors(page);
+
+  await page.goto("/skills?sort=downloads&view=cards", { waitUntil: "domcontentloaded" });
+  await expect(page.locator(".skill-card").first()).toBeVisible();
+
+  const card = page.locator(".skill-card").first();
+  const cardBox = await card.boundingBox();
+  const viewport = page.viewportSize()!;
+
+  // Card should not exceed viewport width
+  expect(cardBox!.width).toBeLessThanOrEqual(viewport.width);
+
+  await expectHealthyPage(page, errors);
+});
+
+test("skill detail page has no horizontal overflow on mobile", async ({ page, request }) => {
+  const errors = trackRuntimeErrors(page);
+
+  const response = await request.get("/api/v1/skills/gifgrep");
+  test.skip(!response.ok(), "gifgrep fixture missing");
+
+  const payload = (await response.json()) as {
+    owner?: { handle?: string | null };
+    skill?: { slug?: string | null; displayName?: string | null };
+  };
+  const ownerHandle = payload.owner?.handle?.trim();
+  const slug = payload.skill?.slug?.trim();
+  test.skip(!ownerHandle || !slug || !payload.skill?.displayName, "fixture missing owner handle, slug, or displayName");
+
+  await page.goto(`/${ownerHandle}/${slug}`, { waitUntil: "domcontentloaded" });
+  await expect(
+    page.getByRole("heading", { name: payload.skill!.displayName! }),
+  ).toBeVisible();
+
+  const scrollWidth = await page.evaluate(() => document.documentElement.scrollWidth);
+  const clientWidth = await page.evaluate(() => document.documentElement.clientWidth);
+  expect(scrollWidth).toBeLessThanOrEqual(clientWidth + 1);
+
+  await expectHealthyPage(page, errors);
+});
+
+test("detail tabs are scrollable and touch-friendly on mobile", async ({ page, request }) => {
+  const errors = trackRuntimeErrors(page);
+
+  const response = await request.get("/api/v1/skills/gifgrep");
+  test.skip(!response.ok(), "gifgrep fixture missing");
+
+  const payload = (await response.json()) as {
+    owner?: { handle?: string | null };
+    skill?: { slug?: string | null };
+  };
+  const ownerHandle = payload.owner?.handle?.trim();
+  const slug = payload.skill?.slug?.trim();
+  test.skip(!ownerHandle || !slug, "fixture missing");
+
+  await page.goto(`/${ownerHandle}/${slug}`, { waitUntil: "domcontentloaded" });
+
+  // All standard tabs should be accessible (even if scrolled)
+  for (const tabName of ["README", "Files", "Versions"]) {
+    const tab = page.getByRole("button", { name: tabName });
+    await tab.scrollIntoViewIfNeeded();
+    await expect(tab).toBeVisible();
+
+    // Touch target should be at least 44px
+    const box = await tab.boundingBox();
+    expect(box!.height).toBeGreaterThanOrEqual(44);
+  }
+
+  await expectHealthyPage(page, errors);
+});
+
+test("search input font size prevents iOS zoom", async ({ page }) => {
+  const errors = trackRuntimeErrors(page);
+
+  await page.goto("/skills?sort=downloads", { waitUntil: "domcontentloaded" });
+
+  const input = page.locator(".browse-search-input");
+  await expect(input).toBeVisible();
+
+  const fontSize = await input.evaluate((el) => getComputedStyle(el).fontSize);
+  // iOS Safari zooms the page when an input has font-size below 16px
+  expect(parseFloat(fontSize)).toBeGreaterThanOrEqual(16);
+
+  await expectHealthyPage(page, errors);
+});
@@ -69,7 +69,7 @@ describe("prod http smoke", () => {

    expect(html).toContain("<title>ClawHub");
    expect(html).toContain('href="/skills"');
-    expect(html).toContain('href="/upload"');
+    expect(html).toContain('href="/publish-skill"');
    expect(html).not.toContain("Something went wrong!");
  });

@@ -7,17 +7,21 @@
  "type": "module",
  "scripts": {
    "build": "bun --bun vite build && bun scripts/copy-og-assets.ts",
+    "check": "bun run lint",
    "check:peers": "bun scripts/check-peer-deps.ts",
+    "check:secrets": "bun scripts/check-staged-secrets.mjs",
    "convex:deploy": "bunx convex deploy --typecheck=disable --yes",
    "coverage": "vitest run --coverage",
    "dev": "bun --bun vite dev --port 3000",
    "docs:list": "bun scripts/docs-list.ts",
    "format": "oxfmt --write",
+    "install:local-hooks": "bun scripts/install-git-hooks.mjs",
    "lint": "bun run lint:oxlint",
-    "lint:fix": "oxlint --type-aware --tsconfig ./tsconfig.oxlint.json ./src ./convex ./packages/clawdhub/src ./packages/schema/src --fix && bun run format",
-    "lint:oxlint": "oxlint --type-aware --tsconfig ./tsconfig.oxlint.json ./src ./convex ./packages/clawdhub/src ./packages/schema/src",
+    "lint:fix": "oxlint --type-aware --tsconfig ./tsconfig.oxlint.json ./src ./convex ./packages/clawhub/src ./packages/schema/src --fix && bun run format",
+    "lint:oxlint": "oxlint --type-aware --tsconfig ./tsconfig.oxlint.json ./src ./convex ./packages/clawhub/src ./packages/schema/src",
    "preinstall": "bunx only-allow bun",
    "preview": "bun --bun vite preview",
+    "release:clawhub:cli:npm:check": "node scripts/clawhub-cli-npm-release-check.mjs",
    "test": "vitest run",
    "test:e2e": "vitest run -c vitest.e2e.config.ts",
    "test:e2e:local": "bash scripts/run-playwright-local.sh",
@@ -29,59 +33,79 @@
  "dependencies": {
    "@auth/core": "^0.37.4",
    "@convex-dev/auth": "^0.0.91",
+    "@create-markdown/core": "^2.0.2",
+    "@create-markdown/preview": "^2.0.2",
    "@fontsource/bricolage-grotesque": "^5.2.10",
    "@fontsource/ibm-plex-mono": "^5.2.7",
    "@fontsource/manrope": "^5.2.8",
    "@monaco-editor/react": "^4.7.0",
+    "@radix-ui/react-avatar": "^1.1.11",
+    "@radix-ui/react-dialog": "^1.1.15",
    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
    "@radix-ui/react-toggle-group": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
    "@resvg/resvg-wasm": "^2.6.2",
    "@tailwindcss/vite": "^4.2.2",
    "@tanstack/react-devtools": "0.10.0",
    "@tanstack/react-router": "1.168.1",
    "@tanstack/react-router-devtools": "1.166.10",
    "@tanstack/react-start": "1.167.2",
+    "@tanstack/react-table": "^8.21.3",
    "@tanstack/router-plugin": "1.167.2",
    "@vercel/analytics": "^2.0.1",
+    "class-variance-authority": "^0.7.1",
    "clawhub-schema": "workspace:*",
    "clsx": "^2.1.1",
-    "convex": "^1.34.0",
+    "convex": "^1.34.1",
    "convex-helpers": "^0.1.114",
    "fflate": "^0.8.2",
    "h3": "2.0.1-rc.18",
    "ignore": "^7.0.5",
    "lucide-react": "^0.577.0",
    "monaco-editor": "^0.55.1",
+    "next": "^16.2.3",
+    "next-themes": "^0.4.6",
    "nitro": "3.0.260311-beta",
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
    "react-markdown": "^10.1.0",
    "remark-gfm": "^4.0.1",
    "semver": "^7.7.4",
+    "shiki": "^4.0.2",
+    "sonner": "^2.0.7",
    "tailwind-merge": "^3.5.0",
    "tailwindcss": "^4.2.2",
+    "tw-animate-css": "^1.4.0",
    "vite-tsconfig-paths": "^6.1.1",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
  },
  "devDependencies": {
-    "@playwright/test": "^1.58.2",
+    "@playwright/test": "^1.59.1",
    "@tanstack/devtools-vite": "0.6.0",
    "@testing-library/dom": "^10.4.1",
    "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.5.2",
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "@types/semver": "^7.7.1",
    "@vitejs/plugin-react": "6.0.1",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.2",
    "jsdom": "^29.0.1",
    "only-allow": "^1.2.2",
    "oxfmt": "0.41.0",
-    "oxlint": "^1.56.0",
-    "oxlint-tsgolint": "^0.17.1",
+    "oxlint": "^1.58.0",
+    "oxlint-tsgolint": "^0.17.4",
    "typescript": "^5.9.3",
-    "undici": "^7.24.5",
-    "vite": "8.0.1",
-    "vitest": "^4.1.0"
+    "undici": "^7.24.7",
+    "vite": "8.0.5",
+    "vitest": "^4.1.2"
  }
 }
@@ -1,61 +0,0 @@
-# `clawhub`
-
-ClawHub CLI — install, update, search, and publish agent skills plus OpenClaw packages.
-
-## Install
-
-```bash
-# From this repo (shortcut script at repo root)
-bun clawhub --help
-
-# Once published to npm
-# npm i -g clawhub
-```
-
-## Auth (publish)
-
-```bash
-clawhub login
-# or
-clawhub auth login
-
-# Headless / token paste
-# or (token paste / headless)
-clawhub login --token clh_...
-```
-
-Notes:
-
- Browser login opens `https://clawhub.ai/cli/auth` and completes via a loopback callback.
- Token stored in `~/Library/Application Support/clawhub/config.json` on macOS (override via `CLAWHUB_CONFIG_PATH`, legacy `CLAWDHUB_CONFIG_PATH`).
-
-## Examples
-
-```bash
-clawhub search "postgres backups"
-clawhub install my-skill-pack
-clawhub update --all
-clawhub update --all --no-input --force
-clawhub publish ./my-skill-pack --slug my-skill-pack --name "My Skill Pack" --version 1.2.0 --changelog "Fixes + docs"
-clawhub package explore --family skill
-clawhub package explore --family code-plugin
-clawhub package inspect @openclaw/example-plugin
-clawhub package publish ./example-plugin --owner openclaw --source-repo openclaw/example-plugin --source-commit abc123
-```
-
-## Sync (upload local skills)
-
-```bash
-# Start anywhere; scans workdir first, then legacy Clawdis/Clawd/OpenClaw/Moltbot locations.
-clawhub sync
-
-# Explicit roots + non-interactive dry-run
-clawhub sync --root ../clawdis/skills --all --dry-run
-```
-
-## Defaults
-
- Site: `https://clawhub.ai` (override via `--site` or `CLAWHUB_SITE`, legacy `CLAWDHUB_SITE`)
- Registry: discovered from `/.well-known/clawhub.json` on the site (legacy `/.well-known/clawdhub.json`; override via `--registry` or `CLAWHUB_REGISTRY`)
- Workdir: current directory (falls back to Clawdbot workspace if configured; override via `--workdir` or `CLAWHUB_WORKDIR`)
- Install dir: `./skills` under workdir (override via `--dir`)
@@ -1,91 +0,0 @@
-/* @vitest-environment node */
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GlobalOpts } from "../types";
-
-vi.mock("../authToken.js", () => ({
-  requireAuthToken: vi.fn(async () => "tkn"),
-}));
-
-vi.mock("../registry.js", () => ({
-  getRegistry: vi.fn(async () => "https://clawhub.ai"),
-}));
-
-const mockApiRequest = vi.fn();
-vi.mock("../../http.js", () => ({
-  apiRequest: (registry: unknown, args: unknown, schema?: unknown) =>
-    mockApiRequest(registry, args, schema),
-}));
-
-const mockFail = vi.fn((message: string) => {
-  throw new Error(message);
-});
-
-vi.mock("../ui.js", () => ({
-  createSpinner: vi.fn(() => ({ succeed: vi.fn(), fail: vi.fn() })),
-  fail: (message: string) => mockFail(message),
-  formatError: (error: unknown) => (error instanceof Error ? error.message : String(error)),
-  isInteractive: () => false,
-  promptConfirm: vi.fn(async () => true),
-}));
-
-const { cmdDeleteSkill, cmdHideSkill, cmdUndeleteSkill, cmdUnhideSkill } = await import("./delete");
-
-function makeOpts(): GlobalOpts {
-  return {
-    workdir: "/work",
-    dir: "/work/skills",
-    site: "https://clawhub.ai",
-    registry: "https://clawhub.ai",
-    registrySource: "default",
-  };
-}
-
-afterEach(() => {
-  vi.clearAllMocks();
-});
-
-describe("delete/undelete", () => {
-  it("requires --yes when input is disabled", async () => {
-    await expect(cmdDeleteSkill(makeOpts(), "demo", {}, false)).rejects.toThrow(/--yes/i);
-    await expect(cmdUndeleteSkill(makeOpts(), "demo", {}, false)).rejects.toThrow(/--yes/i);
-    await expect(cmdHideSkill(makeOpts(), "demo", {}, false)).rejects.toThrow(/--yes/i);
-    await expect(cmdUnhideSkill(makeOpts(), "demo", {}, false)).rejects.toThrow(/--yes/i);
-  });
-
-  it("calls delete endpoint with --yes", async () => {
-    mockApiRequest.mockResolvedValueOnce({ ok: true });
-    await cmdDeleteSkill(makeOpts(), "demo", { yes: true }, false);
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({ method: "DELETE", path: "/api/v1/skills/demo" }),
-      expect.anything(),
-    );
-  });
-
-  it("calls undelete endpoint with --yes", async () => {
-    mockApiRequest.mockResolvedValueOnce({ ok: true });
-    await cmdUndeleteSkill(makeOpts(), "demo", { yes: true }, false);
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({ method: "POST", path: "/api/v1/skills/demo/undelete" }),
-      expect.anything(),
-    );
-  });
-
-  it("supports hide/unhide aliases", async () => {
-    mockApiRequest.mockResolvedValue({ ok: true });
-    await cmdHideSkill(makeOpts(), "demo", { yes: true }, false);
-    await cmdUnhideSkill(makeOpts(), "demo", { yes: true }, false);
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({ method: "DELETE", path: "/api/v1/skills/demo" }),
-      expect.anything(),
-    );
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({ method: "POST", path: "/api/v1/skills/demo/undelete" }),
-      expect.anything(),
-    );
-  });
-});
@@ -1,94 +0,0 @@
-/* @vitest-environment node */
-
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { GlobalOpts } from "../types";
-
-vi.mock("../authToken.js", () => ({
-  requireAuthToken: vi.fn(async () => "tkn"),
-}));
-
-vi.mock("../registry.js", () => ({
-  getRegistry: vi.fn(async () => "https://clawhub.ai"),
-}));
-
-const mockApiRequest = vi.fn();
-vi.mock("../../http.js", () => ({
-  apiRequest: (registry: unknown, args: unknown, schema?: unknown) =>
-    mockApiRequest(registry, args, schema),
-}));
-
-vi.mock("../ui.js", () => ({
-  createSpinner: vi.fn(() => ({ succeed: vi.fn(), fail: vi.fn() })),
-  fail: (message: string) => {
-    throw new Error(message);
-  },
-  formatError: (error: unknown) => (error instanceof Error ? error.message : String(error)),
-  isInteractive: () => false,
-  promptConfirm: vi.fn(async () => true),
-}));
-
-const { cmdMergeSkill, cmdRenameSkill } = await import("./ownership");
-
-function makeOpts(): GlobalOpts {
-  return {
-    workdir: "/work",
-    dir: "/work/skills",
-    site: "https://clawhub.ai",
-    registry: "https://clawhub.ai",
-    registrySource: "default",
-  };
-}
-
-afterEach(() => {
-  vi.clearAllMocks();
-});
-
-describe("ownership commands", () => {
-  it("rename requires --yes when input is disabled", async () => {
-    await expect(cmdRenameSkill(makeOpts(), "demo", "demo-new", {}, false)).rejects.toThrow(
-      /--yes/i,
-    );
-  });
-
-  it("rename calls rename endpoint", async () => {
-    mockApiRequest.mockResolvedValueOnce({
-      ok: true,
-      slug: "demo-new",
-      previousSlug: "demo",
-    });
-
-    await cmdRenameSkill(makeOpts(), "Demo", "Demo-New", { yes: true }, false);
-
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        method: "POST",
-        path: "/api/v1/skills/demo/rename",
-      }),
-      expect.anything(),
-    );
-    const requestArgs = mockApiRequest.mock.calls[0]?.[1] as { body?: string };
-    expect(requestArgs.body).toContain('"newSlug":"demo-new"');
-  });
-
-  it("merge calls merge endpoint", async () => {
-    mockApiRequest.mockResolvedValueOnce({
-      ok: true,
-      sourceSlug: "demo-old",
-      targetSlug: "demo",
-    });
-
-    await cmdMergeSkill(makeOpts(), "Demo-Old", "Demo", { yes: true }, false);
-
-    expect(mockApiRequest).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({
-        method: "POST",
-        path: "/api/v1/skills/demo-old/merge",
-      }),
-      expect.anything(),
-    );
-    const requestArgs = mockApiRequest.mock.calls[0]?.[1] as { body?: string };
-    expect(requestArgs.body).toContain('"targetSlug":"demo"');
-  });
-});
--- a/Show More
+++ b/Show More