docs: add logo replacement design spec

Refresh Open Graph image (#1754 )
* Refresh OG image and bust cache version - Replace the social preview artwork with a new branded SVG and updated PNG - Add a versioned og image URL in the root head tags to ensure the new asset is served * Refresh OG image design - Redesign the social preview graphic for the new ClawHub branding - Bump the OG image version so the updated asset is served * fix: refine clawhub og image * fix: center og logo layout * fix: emphasize clawhub branding in og image * Refresh OG image branding - Update Open Graph artwork and logo asset - Adjust root metadata to use the new social preview image * fix: refine clawhub og image * fix: tighten og image layout * fix: remove og logo panel * fix: reduce og logo scale * fix: align og image to new comp
2026-08-14 08:52:21 +00:00 · 2026-04-21 13:35:18 -05:00 · 2026-04-20 21:59:08 -05:00 · 2026-04-19 13:25:56 -04:00 · 2026-04-18 20:10:03 -05:00 · 2026-04-18 18:40:56 -05:00
387 changed files with 44463 additions and 8532 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,51 +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 }}
-      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
      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 [[ -z "$VERCEL_TOKEN" ]]; then
-            missing+=("VERCEL_TOKEN")
-          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
@@ -56,68 +105,72 @@ 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

-  deploy-web:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    needs:
-      - preflight-secrets
-      - deploy-convex
-    env:
-      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
-      VITE_APP_BUILD_SHA: ${{ github.sha }}
-    steps:
-      - uses: actions/checkout@v6
+      - 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
+            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)"; then
+              echo "GitHub status check failed for $GITHUB_SHA; retrying..."
+              sleep 10
+              continue
+            fi

-      - uses: oven-sh/setup-bun@e3914758a49697077f7bcd190d36582a61667aad
-        with:
-          bun-version: 1.3.10
+            case "$state" in
+              success)
+                echo "Vercel production deployment ready for $GITHUB_SHA"
+                exit 0
+                ;;
+              failure|error)
+                echo "::error::Vercel production deployment failed for $GITHUB_SHA"
+                exit 1
+                ;;
+              pending)
+                echo "Vercel deployment pending for $GITHUB_SHA; waiting..."
+                ;;
+              *)
+                echo "Vercel status for $GITHUB_SHA not published yet; waiting..."
+                ;;
+            esac

-      - name: Pull Vercel config
-        run: bunx vercel pull --yes --environment=production --token "$VERCEL_TOKEN"
+            sleep 10
+          done

-      - name: Deploy Vercel app
-        run: bunx vercel deploy --yes --prod --token "$VERCEL_TOKEN"
-
-  smoke-production:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    needs:
-      - preflight-secrets
-      - deploy-convex
-      - deploy-web
-    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
+          echo "::error::Timed out waiting for Vercel production deployment for $GITHUB_SHA"
+          exit 1

      - name: Install Playwright browser
+        if: needs.validate-deploy-request.outputs.run_smoke == 'true'
        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,7 +24,7 @@ coverage
 playwright-report
 test-results
 .playwright
-skills/
-docs/
-convex/
+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>`.
@@ -83,3 +95,23 @@ When working on Convex code, **always read `convex/_generated/ai/guidelines.md`

 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,10 +1,83 @@
 # Changelog

-## 0.9.0 - Unreleased
+## 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
+
+- Packages/Plugins: add a first-class OpenClaw package registry across the web app, CLI, and HTTP API. ClawHub now supports package browse/search/detail/version/file/download flows plus `clawhub package explore`, `clawhub package inspect`, and `clawhub package publish` for `skill`, `code-plugin`, and `bundle-plugin` packages. (#1093)
+- Packages/Install: package downloads now ship install-ready archives with a `package/` root, support nested files like `dist/index.js`, and work directly with OpenClaw plugin install flows.
+- Skills/Web: server-render public skill pages and OG assets for faster first loads, cleaner sharing previews, and better cache behavior.
+
+### Changed
+
+- Browse/Search: rebuild public browse/search around denormalized digests, one-shot HTTP fetches, and deterministic cursors so the homepage and `/skills` are faster, more cacheable, and less likely to hit stale-tab or pagination dead ends.
+- Search: default skill search to relevance, keep load-more retryable after fetch failures, and tighten package/skill catalog query paths to reduce inconsistent results under load.
+
+### Fixed
+
+- Packages/Auth: authenticated owners can now list, search, inspect, download, and read files from their own private packages instead of private packages being direct-URL-only. (#1093)
+- Packages/API: stabilize package latest-version pointers, cursor pagination, publish outputs, fallback release resolution, and app-origin auth handling so package publish/search/install flows stay reliable.
 - Visibility/API: prevent skills owned by deleted/banned users from showing up in public detail pages, browse/search results, or version API routes.
+- Skills/API: sanitize public skill and soul version/file reads so hidden or invalid version data does not leak through direct API access.
 - Skills/Web: keep Monaco compare layout toggles reliable while defaulting narrow screens to inline mode (#828) (thanks @geoffrey-xiao).

 ## 0.8.0 - 2026-03-13
@@ -30,6 +30,17 @@
 - 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.
@@ -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> --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";
@@ -66,13 +67,17 @@ import type * as lib_moderationReasonCodes from "../lib/moderationReasonCodes.js
 import type * as lib_openaiResponse from "../lib/openaiResponse.js";
 import type * as lib_packageRegistry from "../lib/packageRegistry.js";
 import type * as lib_packageSearchDigest from "../lib/packageSearchDigest.js";
+import type * as lib_packageSecurity from "../lib/packageSecurity.js";
 import type * as lib_public from "../lib/public.js";
+import type * as lib_publishLimits from "../lib/publishLimits.js";
+import type * as lib_publishers from "../lib/publishers.js";
 import type * as lib_reporting from "../lib/reporting.js";
 import type * as lib_reservedHandles from "../lib/reservedHandles.js";
 import type * as lib_reservedSlugs from "../lib/reservedSlugs.js";
 import type * as lib_searchText from "../lib/searchText.js";
 import type * as lib_securityPrompt from "../lib/securityPrompt.js";
 import type * as lib_skillBackfill from "../lib/skillBackfill.js";
+import type * as lib_skillCapabilityTags from "../lib/skillCapabilityTags.js";
 import type * as lib_skillPublish from "../lib/skillPublish.js";
 import type * as lib_skillQuality from "../lib/skillQuality.js";
 import type * as lib_skillSafety from "../lib/skillSafety.js";
@@ -83,15 +88,19 @@ import type * as lib_skillZip from "../lib/skillZip.js";
 import type * as lib_skills from "../lib/skills.js";
 import type * as lib_soulChangelog from "../lib/soulChangelog.js";
 import type * as lib_soulPublish from "../lib/soulPublish.js";
+import type * as lib_staticPublishScan from "../lib/staticPublishScan.js";
 import type * as lib_tokens from "../lib/tokens.js";
 import type * as lib_userSearch from "../lib/userSearch.js";
 import type * as lib_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";
@@ -156,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;
@@ -174,13 +184,17 @@ declare const fullApi: ApiFromModules<{
  "lib/openaiResponse": typeof lib_openaiResponse;
  "lib/packageRegistry": typeof lib_packageRegistry;
  "lib/packageSearchDigest": typeof lib_packageSearchDigest;
+  "lib/packageSecurity": typeof lib_packageSecurity;
  "lib/public": typeof lib_public;
+  "lib/publishLimits": typeof lib_publishLimits;
+  "lib/publishers": typeof lib_publishers;
  "lib/reporting": typeof lib_reporting;
  "lib/reservedHandles": typeof lib_reservedHandles;
  "lib/reservedSlugs": typeof lib_reservedSlugs;
  "lib/searchText": typeof lib_searchText;
  "lib/securityPrompt": typeof lib_securityPrompt;
  "lib/skillBackfill": typeof lib_skillBackfill;
+  "lib/skillCapabilityTags": typeof lib_skillCapabilityTags;
  "lib/skillPublish": typeof lib_skillPublish;
  "lib/skillQuality": typeof lib_skillQuality;
  "lib/skillSafety": typeof lib_skillSafety;
@@ -191,15 +205,19 @@ declare const fullApi: ApiFromModules<{
  "lib/skills": typeof lib_skills;
  "lib/soulChangelog": typeof lib_soulChangelog;
  "lib/soulPublish": typeof lib_soulPublish;
+  "lib/staticPublishScan": typeof lib_staticPublishScan;
  "lib/tokens": typeof lib_tokens;
  "lib/userSearch": typeof lib_userSearch;
  "lib/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
@@ -86,6 +99,9 @@ export const { auth, signIn, signOut, store, isAuthenticated } = convexAuth({
    async afterUserCreatedOrUpdated(ctx, args) {
      const user = await ctx.db.get(args.userId);
      await handleDeletedUserSignIn(ctx, args, user);
+      await ctx.scheduler.runAfter(0, internal.publishers.ensurePersonalPublisherInternal, {
+        userId: args.userId,
+      });

      // Schedule GitHub profile sync to handle username renames (fixes #303)
      // This runs as a background action so it doesn't block sign-in
@@ -58,6 +58,13 @@ crons.interval("vt-cache-backfill", { minutes: 30 }, internal.vt.backfillActiveS
  batchSize: 100,
 });

+crons.interval(
+  "package-scan-backfill",
+  { minutes: 30 },
+  internal.packages.backfillPackageReleaseScansInternal,
+  { batchSize: 100 },
+);
+
 // Daily re-scan of all active skills at 3am UTC
 crons.daily("vt-daily-rescan", { hourUTC: 3, minuteUTC: 0 }, internal.vt.rescanActiveSkills, {});

@@ -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>) {
@@ -1,8 +1,10 @@
 /* @vitest-environment node */

 import { describe, expect, it, vi } from "vitest";
+import { internal } from "./_generated/api";
 import {
  repointPackageLatestRelease,
+  scheduleOwnerPublisherDigestSync,
  syncPackageSearchDigestForPackageId,
  syncPackageSearchDigestsForOwnerUserId,
 } from "./functions";
@@ -60,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",
@@ -126,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",
@@ -441,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) => {
@@ -486,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(
@@ -501,3 +492,35 @@ describe("package digest sync", () => {
    );
  });
 });
+
+describe("publisher digest scheduling", () => {
+  it("schedules package and skill digest sync in separate background mutations", async () => {
+    const ctx = {
+      scheduler: {
+        runAfter: vi.fn().mockResolvedValue(undefined),
+      },
+    };
+
+    await scheduleOwnerPublisherDigestSync(ctx as never, "publishers:demo" as never);
+
+    expect(ctx.scheduler.runAfter).toHaveBeenCalledTimes(2);
+    expect(ctx.scheduler.runAfter).toHaveBeenNthCalledWith(
+      1,
+      0,
+      internal.functions.syncPackageSearchDigestsForOwnerPublisherIdInternal,
+      { ownerPublisherId: "publishers:demo" },
+    );
+    expect(ctx.scheduler.runAfter).toHaveBeenNthCalledWith(
+      2,
+      0,
+      internal.functions.syncSkillSearchDigestsForOwnerPublisherIdInternal,
+      { ownerPublisherId: "publishers:demo" },
+    );
+  });
+
+  it("skips scheduling when the trigger context has no scheduler", async () => {
+    await expect(
+      scheduleOwnerPublisherDigestSync({} as never, "publishers:demo" as never),
+    ).resolves.toBeUndefined();
+  });
+});
@@ -1,6 +1,8 @@
 import { customCtx, customMutation } from "convex-helpers/server/customFunctions";
 import { Triggers } from "convex-helpers/server/triggers";
+import { v } from "convex/values";
 import semver from "semver";
+import { internal } from "./_generated/api";
 import type { DataModel, Doc, Id } from "./_generated/dataModel";
 import {
  mutation as rawMutation,
@@ -17,11 +19,20 @@ import {
  extractPackageDigestFields,
  upsertPackageSearchDigest,
 } from "./lib/packageSearchDigest";
+import { getOwnerPublisher } from "./lib/publishers";
 import { extractDigestFields, upsertSkillSearchDigest } from "./lib/skillSearchDigest";

 const triggers = new Triggers<DataModel>();

+function isMissingTableError(error: unknown, table: string) {
+  return (
+    error instanceof Error &&
+    new RegExp(`unexpected (query )?table:? ${table}`, "i").test(error.message)
+  );
+}
+
 type PackageDigestSyncCtx = Pick<MutationCtx, "db">;
+type OwnerPublisherDigestScheduleCtx = Pick<Partial<MutationCtx>, "scheduler">;
 type LatestPackageRelease = Pick<
  Doc<"packageReleases">,
  | "_id"
@@ -33,7 +44,9 @@ type LatestPackageRelease = Pick<
  | "capabilities"
  | "verification"
  | "distTags"
->;
+> & {
+  scanStatus?: Doc<"packages">["scanStatus"];
+};

 function toPackageLatestVersionSummary(
  release: LatestPackageRelease | null,
@@ -92,6 +105,7 @@ async function getPreferredFallbackPackageRelease(
        compatibility: release.compatibility,
        capabilities: release.capabilities,
        verification: release.verification,
+        scanStatus: release.verification?.scanStatus,
        distTags: release.distTags,
      };
      if (!best || compareFallbackReleases(family, candidate, best) > 0) best = candidate;
@@ -108,19 +122,16 @@ async function syncPackageSearchDigest(
  if (!pkg) return;
  const latestRelease = pkg.latestReleaseId ? await ctx.db.get(pkg.latestReleaseId) : null;
  const fields = extractPackageDigestFields(pkg);
-  const owner = await ctx.db.get(pkg.ownerUserId);
+  const owner = await getOwnerPublisher(ctx, {
+    ownerPublisherId: pkg.ownerPublisherId,
+    ownerUserId: pkg.ownerUserId,
+  });
  await upsertPackageSearchDigest(ctx, {
    ...fields,
-    latestVersion: latestRelease && !latestRelease.softDeletedAt ? latestRelease.version : undefined,
-    ownerHandle:
-      owner &&
-      typeof owner === "object" &&
-      owner &&
-      !("deletedAt" in owner && owner.deletedAt) &&
-      !("deactivatedAt" in owner && owner.deactivatedAt) &&
-      "handle" in owner
-        ? ((owner.handle as string | undefined) ?? "")
-        : "",
+    latestVersion:
+      latestRelease && !latestRelease.softDeletedAt ? latestRelease.version : undefined,
+    ownerHandle: owner?.handle ?? "",
+    ownerKind: owner?.kind,
  });
 }

@@ -140,19 +151,127 @@ export async function syncPackageSearchDigestsForOwnerUserId(
 ) {
  if (!ownerUserId) return;
  let cursor: string | null = null;
-  while (true) {
-    const page = await ctx.db
-      .query("packages")
-      .withIndex("by_owner", (q) => q.eq("ownerUserId", ownerUserId))
-      .paginate({ cursor, numItems: 100 });
-    for (const pkg of page.page) {
-      await syncPackageSearchDigest(ctx, pkg);
+  try {
+    while (true) {
+      const page = await ctx.db
+        .query("packages")
+        .withIndex("by_owner", (q) => q.eq("ownerUserId", ownerUserId))
+        .paginate({ cursor, numItems: 100 });
+      for (const pkg of page.page) {
+        await syncPackageSearchDigest(ctx, pkg);
+      }
+      if (page.isDone) break;
+      cursor = page.continueCursor;
    }
-    if (page.isDone) break;
-    cursor = page.continueCursor;
+  } catch (error) {
+    if (isMissingTableError(error, "packages")) return;
+    throw error;
  }
 }

+export async function syncPackageSearchDigestsForOwnerPublisherId(
+  ctx: PackageDigestSyncCtx,
+  ownerPublisherId: Id<"publishers"> | null | undefined,
+) {
+  if (!ownerPublisherId) return;
+  let cursor: string | null = null;
+  try {
+    while (true) {
+      const page = await ctx.db
+        .query("packages")
+        .withIndex("by_owner_publisher", (q) => q.eq("ownerPublisherId", ownerPublisherId))
+        .paginate({ cursor, numItems: 100 });
+      for (const pkg of page.page) {
+        await syncPackageSearchDigest(ctx, pkg);
+      }
+      if (page.isDone) break;
+      cursor = page.continueCursor;
+    }
+  } catch (error) {
+    if (isMissingTableError(error, "packages")) return;
+    throw error;
+  }
+}
+
+async function syncSkillSearchDigestForSkill(
+  ctx: PackageDigestSyncCtx,
+  skill: Doc<"skills"> | null | undefined,
+) {
+  if (!skill) return;
+  const fields = extractDigestFields(skill);
+  const owner = await getOwnerPublisher(ctx, {
+    ownerPublisherId: skill.ownerPublisherId,
+    ownerUserId: skill.ownerUserId,
+  });
+  await upsertSkillSearchDigest(ctx, {
+    ...fields,
+    ownerHandle: owner?.handle ?? "",
+    ownerKind: owner?.kind,
+    ownerName: owner?.linkedUserId ? owner.handle : undefined,
+    ownerDisplayName: owner?.displayName,
+    ownerImage: owner?.image,
+  });
+}
+
+export async function syncSkillSearchDigestsForOwnerPublisherId(
+  ctx: PackageDigestSyncCtx,
+  ownerPublisherId: Id<"publishers"> | null | undefined,
+) {
+  if (!ownerPublisherId) return;
+  let cursor: string | null = null;
+  try {
+    while (true) {
+      const page = await ctx.db
+        .query("skills")
+        .withIndex("by_owner_publisher", (q) => q.eq("ownerPublisherId", ownerPublisherId))
+        .paginate({ cursor, numItems: 100 });
+      for (const skill of page.page) {
+        await syncSkillSearchDigestForSkill(ctx, skill);
+      }
+      if (page.isDone) break;
+      cursor = page.continueCursor;
+    }
+  } catch (error) {
+    if (isMissingTableError(error, "skills")) return;
+    throw error;
+  }
+}
+
+export async function scheduleOwnerPublisherDigestSync(
+  ctx: OwnerPublisherDigestScheduleCtx,
+  ownerPublisherId: Id<"publishers"> | null | undefined,
+) {
+  if (!ownerPublisherId || !ctx.scheduler) return;
+  await ctx.scheduler.runAfter(
+    0,
+    internal.functions.syncPackageSearchDigestsForOwnerPublisherIdInternal,
+    { ownerPublisherId },
+  );
+  await ctx.scheduler.runAfter(
+    0,
+    internal.functions.syncSkillSearchDigestsForOwnerPublisherIdInternal,
+    { ownerPublisherId },
+  );
+}
+
+export const syncPackageSearchDigestsForOwnerPublisherIdInternal = rawInternalMutation({
+  args: {
+    ownerPublisherId: v.id("publishers"),
+  },
+  handler: async (ctx, args) => {
+    await syncPackageSearchDigestsForOwnerPublisherId(ctx, args.ownerPublisherId);
+  },
+});
+
+export const syncSkillSearchDigestsForOwnerPublisherIdInternal = rawInternalMutation({
+  args: {
+    ownerPublisherId: v.id("publishers"),
+  },
+  handler: async (ctx, args) => {
+    await syncSkillSearchDigestsForOwnerPublisherId(ctx, args.ownerPublisherId);
+  },
+});
+
 export async function repointPackageLatestRelease(
  ctx: PackageDigestSyncCtx,
  packageId: Id<"packages"> | null | undefined,
@@ -197,6 +316,7 @@ export async function repointPackageLatestRelease(
    patch.compatibility = nextLatest?.compatibility;
    patch.capabilities = nextLatest?.capabilities;
    patch.verification = nextLatest?.verification;
+    patch.scanStatus = nextLatest?.scanStatus;
  }
  await ctx.db.patch(pkg._id, patch);
  await syncPackageSearchDigest(ctx, { ...pkg, ...patch });
@@ -210,20 +330,7 @@ triggers.register("skills", async (ctx, change) => {
      .unique();
    if (existing) await ctx.db.delete(existing._id);
  } else {
-    const fields = extractDigestFields(change.newDoc);
-    const owner = await ctx.db.get(change.newDoc.ownerUserId);
-    const isOwnerVisible = owner && !owner.deletedAt && !owner.deactivatedAt;
-    await upsertSkillSearchDigest(ctx, {
-      ...fields,
-      // Use '' as sentinel for "visible user without a handle" so
-      // digestToOwnerInfo can distinguish from undefined (not backfilled).
-      // Deactivated/deleted owners also get '' → digestToOwnerInfo returns
-      // null owner, matching the live path.
-      ownerHandle: isOwnerVisible ? (owner.handle ?? "") : "",
-      ownerName: isOwnerVisible ? owner.name : undefined,
-      ownerDisplayName: isOwnerVisible ? owner.displayName : undefined,
-      ownerImage: isOwnerVisible ? owner.image : undefined,
-    });
+    await syncSkillSearchDigestForSkill(ctx, change.newDoc);
  }
 });

@@ -238,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;
@@ -265,6 +374,11 @@ triggers.register("users", async (ctx, change) => {
  await syncPackageSearchDigestsForOwnerUserId(ctx, ownerUserId);
 });

+triggers.register("publishers", async (ctx, change) => {
+  const ownerPublisherId = change.operation === "delete" ? change.id : change.newDoc._id;
+  await scheduleOwnerPublisherDigestSync(ctx, ownerPublisherId);
+});
+
 export const mutation = customMutation(rawMutation, customCtx(triggers.wrapDB));
 export const internalMutation = customMutation(rawInternalMutation, customCtx(triggers.wrapDB));
 export { query, internalQuery, action, internalAction, httpAction };
@@ -17,11 +17,16 @@ import {
  listBundlePluginsV1Http,
  listCodePluginsV1Http,
  listPackagesV1Http,
+  listPluginsV1Http,
  listSkillsV1Http,
  listSoulsV1Http,
+  mintPublishTokenV1Http,
+  packagesDeleteRouterV1Http,
  packagesGetRouterV1Http,
-  publishSkillV1Http,
+  packagesPostRouterV1Http,
+  pluginsGetRouterV1Http,
  publishPackageV1Http,
+  publishSkillV1Http,
  publishSoulV1Http,
  resolveSkillVersionV1Http,
  searchSkillsV1Http,
@@ -74,6 +79,12 @@ http.route({
  handler: listPackagesV1Http,
 });

+http.route({
+  path: ApiRoutes.plugins,
+  method: "GET",
+  handler: listPluginsV1Http,
+});
+
 http.route({
  path: ApiRoutes.codePlugins,
  method: "GET",
@@ -98,6 +109,12 @@ http.route({
  handler: packagesGetRouterV1Http,
 });

+http.route({
+  pathPrefix: `${ApiRoutes.plugins}/`,
+  method: "GET",
+  handler: pluginsGetRouterV1Http,
+});
+
 http.route({
  path: ApiRoutes.skills,
  method: "POST",
@@ -110,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",
@@ -3,7 +3,12 @@ import {
  listBundlePluginsV1Handler,
  listCodePluginsV1Handler,
  listPackagesV1Handler,
+  listPluginsV1Handler,
+  mintPublishTokenV1Handler,
+  packagesDeleteRouterV1Handler,
  packagesGetRouterV1Handler,
+  packagesPostRouterV1Handler,
+  pluginsGetRouterV1Handler,
  publishPackageV1Handler,
 } from "./httpApiV1/packagesV1";
 import {
@@ -28,8 +33,13 @@ import { usersListV1Handler, usersPostRouterV1Handler } from "./httpApiV1/usersV
 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);

@@ -57,8 +67,13 @@ export const usersListV1Http = httpAction(usersListV1Handler);

 export const __handlers = {
  listPackagesV1Handler,
+  listPluginsV1Handler,
  packagesGetRouterV1Handler,
+  packagesPostRouterV1Handler,
+  packagesDeleteRouterV1Handler,
+  pluginsGetRouterV1Handler,
  publishPackageV1Handler,
+  mintPublishTokenV1Handler,
  listCodePluginsV1Handler,
  listBundlePluginsV1Handler,
  searchSkillsV1Handler,
@@ -1,10 +1,11 @@
-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";

 export const MAX_RAW_FILE_BYTES = 200 * 1024;
@@ -24,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
@@ -32,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,
@@ -100,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);
@@ -263,6 +278,9 @@ export async function parseMultipartPublish(
    const path = file.name;
    if (isMacJunkPath(path)) continue;
    const size = file.size;
+    if (size > MAX_PUBLISH_FILE_BYTES) {
+      throw new Error(getPublishFileSizeError(path));
+    }
    const contentType = file.type || undefined;
    const buffer = new Uint8Array(await file.arrayBuffer());
    const sha256 = await sha256Hex(buffer);
@@ -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);
  }
 }
@@ -22,7 +22,13 @@ export async function usersPostRouterV1Handler(ctx: ActionCtx, request: Request)
    return text("Not found", 404, rate.headers);
  }
  const action = segments[0];
-  if (action !== "ban" && action !== "role" && action !== "restore" && action !== "reclaim") {
+  if (
+    action !== "ban" &&
+    action !== "role" &&
+    action !== "restore" &&
+    action !== "reclaim" &&
+    action !== "publisher"
+  ) {
    return text("Not found", 404, rate.headers);
  }

@@ -48,6 +54,12 @@ export async function usersPostRouterV1Handler(ctx: ActionCtx, request: Request)
    return handleAdminReclaim(ctx, request, payload, actorUserId, rate.headers);
  }

+  if (action === "publisher") {
+    const admin = requireAdminOrResponse(actorUser, rate.headers);
+    if (!admin.ok) return admin.response;
+    return handleAdminEnsurePublisher(ctx, payload, actorUserId, rate.headers);
+  }
+
  const handleRaw = typeof payload.handle === "string" ? payload.handle.trim() : "";
  const userIdRaw = typeof payload.userId === "string" ? payload.userId.trim() : "";
  const reasonRaw = typeof payload.reason === "string" ? payload.reason.trim() : "";
@@ -215,6 +227,39 @@ async function handleAdminReclaim(
  return json({ ok: true, results, succeeded, failed }, 200, headers);
 }

+async function handleAdminEnsurePublisher(
+  ctx: ActionCtx,
+  payload: Record<string, unknown>,
+  actorUserId: Id<"users">,
+  headers: HeadersInit,
+) {
+  const handle = typeof payload.handle === "string" ? payload.handle.trim().toLowerCase() : "";
+  if (!handle) return text("Missing handle", 400, headers);
+
+  const 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, {
+      actorUserId,
+      handle,
+      displayName,
+      trusted,
+    });
+    return json(result, 200, headers);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Publisher ensure failed";
+    if (message.toLowerCase().includes("forbidden")) {
+      return text("Forbidden", 403, headers);
+    }
+    if (message.toLowerCase().includes("not found")) {
+      return text(message, 404, headers);
+    }
+    return text(message, 400, headers);
+  }
+}
+
 export async function usersListV1Handler(ctx: ActionCtx, request: Request) {
  const rate = await applyRateLimit(ctx, request, "read");
  if (!rate.ok) return rate.response;
@@ -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,
+};
@@ -5,9 +5,9 @@ import { corsHeaders, mergeHeaders } from "./httpHeaders";

 const RATE_LIMIT_WINDOW_MS = 60_000;
 export const RATE_LIMITS = {
-  read: { ip: 120, key: 600 },
-  write: { ip: 30, key: 120 },
-  download: { ip: 20, key: 120 },
+  read: { ip: 180, key: 900 },
+  write: { ip: 45, key: 180 },
+  download: { ip: 30, key: 180 },
 } as const;

 type RateLimitResult = {
@@ -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",
@@ -46,9 +46,11 @@ describe("packageRegistry", () => {

    expect(result.runtimeId).toBe("demo.plugin");
    expect(result.compatibility?.pluginApiRange).toBe("^1.2.0");
+    expect(result.compatibility?.minGatewayVersion).toBe("2026.3.0");
    expect(result.capabilities.executesCode).toBe(true);
    expect(result.capabilities.toolNames).toContain("demoTool");
    expect(result.verification.tier).toBe("source-linked");
+    expect(result.verification.scanStatus).toBe("not-run");
  });

  it("requires source metadata for code plugins", () => {
@@ -69,6 +71,63 @@ describe("packageRegistry", () => {
    ).toThrow("source repo and commit");
  });

+  it("maps legacy minHostVersion to minGatewayVersion instead of pluginApiRange", () => {
+    expect(() =>
+      extractCodePluginArtifacts({
+        packageName: "@openclaw/matrix",
+        packageJson: {
+          name: "@openclaw/matrix",
+          version: "2026.3.13",
+          openclaw: {
+            extensions: ["./index.ts"],
+            install: {
+              npmSpec: "@openclaw/matrix",
+              localPath: "extensions/matrix",
+              defaultChoice: "npm",
+              minHostVersion: "2026.3.13",
+            },
+          },
+        },
+        pluginManifest: {
+          id: "matrix",
+          channels: ["matrix"],
+          configSchema: { type: "object" },
+        },
+        source: {
+          kind: "github",
+          url: "https://github.com/openclaw/openclaw",
+          repo: "openclaw/openclaw",
+          ref: "refs/tags/v2026.3.13",
+          commit: "abc123",
+          path: "extensions/matrix",
+          importedAt: Date.now(),
+        },
+      }),
+    ).toThrow("package.json openclaw.compat.pluginApi is required");
+  });
+
+  it("extracts legacy minHostVersion as minGatewayVersion while preserving build metadata", () => {
+    const result = extractBundlePluginArtifacts({
+      packageName: "@openclaw/matrix-bundle",
+      packageJson: {
+        name: "@openclaw/matrix-bundle",
+        version: "2026.3.13",
+        openclaw: {
+          install: {
+            minHostVersion: "2026.3.13",
+          },
+        },
+      },
+      bundleManifest: {
+        hostTargets: ["openclaw"],
+      },
+    });
+
+    expect(result.compatibility?.pluginApiRange).toBeUndefined();
+    expect(result.compatibility?.minGatewayVersion).toBe("2026.3.13");
+    expect(result.compatibility?.builtWithOpenClawVersion).toBe("2026.3.13");
+  });
+
  it("requires host targets for bundle plugins", () => {
    expect(() =>
      extractBundlePluginArtifacts({
@@ -80,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,30 +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 { compat, build } = extractOpenClawBlock(packageJson);
-  const compatibility: PackageCompatibility = {};
-  if (typeof compat?.pluginApi === "string") compatibility.pluginApiRange = compat.pluginApi.trim();
-  if (typeof compat?.minGatewayVersion === "string") {
-    compatibility.minGatewayVersion = compat.minGatewayVersion.trim();
-  }
-  if (typeof build?.openclawVersion === "string") {
-    compatibility.builtWithOpenClawVersion = build.openclawVersion.trim();
-  }
-  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: {
@@ -201,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");
@@ -212,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([
@@ -258,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,
@@ -300,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()) ||
@@ -354,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",
@@ -13,14 +15,16 @@ const SHARED_KEYS = [
  "channel",
  "isOfficial",
  "ownerUserId",
+  "ownerPublisherId",
  "summary",
  "capabilityTags",
  "executesCode",
  "runtimeId",
+  "scanStatus",
  "softDeletedAt",
  "createdAt",
  "updatedAt",
-] as const satisfies readonly (keyof Doc<"packages"> & keyof Doc<"packageSearchDigest">)[];
+] as const satisfies readonly SharedPackageKey[];

 const CAPABILITY_SHARED_KEYS = [
  "packageId",
@@ -31,13 +35,16 @@ const CAPABILITY_SHARED_KEYS = [
  "channel",
  "isOfficial",
  "ownerUserId",
+  "ownerPublisherId",
  "ownerHandle",
+  "ownerKind",
  "summary",
  "latestVersion",
  "runtimeId",
  "capabilityTags",
  "executesCode",
  "verificationTier",
+  "scanStatus",
  "softDeletedAt",
  "createdAt",
  "updatedAt",
@@ -47,6 +54,7 @@ export type PackageSearchDigestFields = Pick<Doc<"packages">, (typeof SHARED_KEY
  packageId: Id<"packages">;
  latestVersion?: string;
  ownerHandle?: string;
+  ownerKind?: "user" | "org";
  verificationTier?: Doc<"packageSearchDigest">["verificationTier"];
 };

@@ -139,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];
@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+  getPackageDownloadSecurityBlock,
+  isPackageBlockedFromPublic,
+  resolvePackageReleaseScanStatus,
+} from "./packageSecurity";
+
+describe("packageSecurity", () => {
+  it("treats pending package scans as public", () => {
+    expect(isPackageBlockedFromPublic("pending")).toBe(false);
+  });
+
+  it("allows package downloads while VT is pending", () => {
+    expect(
+      getPackageDownloadSecurityBlock({
+        sha256hash: "a".repeat(64),
+      } as never),
+    ).toBeNull();
+  });
+
+  it("still resolves sha256-only releases to pending", () => {
+    expect(
+      resolvePackageReleaseScanStatus({
+        sha256hash: "a".repeat(64),
+      } as never),
+    ).toBe("pending");
+  });
+
+  it("still blocks malicious package releases", () => {
+    expect(isPackageBlockedFromPublic("malicious")).toBe(true);
+    expect(
+      getPackageDownloadSecurityBlock({
+        vtAnalysis: { status: "malicious" },
+      } as never),
+    ).toEqual(
+      expect.objectContaining({
+        status: 403,
+      }),
+    );
+  });
+
+  it("treats suspicious static scans as suspicious even when verification is clean", () => {
+    expect(
+      resolvePackageReleaseScanStatus({
+        staticScan: { status: "suspicious" },
+        verification: { scanStatus: "clean" },
+      } as never),
+    ).toBe("suspicious");
+  });
+});
@@ -0,0 +1,61 @@
+import type { Doc } from "../_generated/dataModel";
+
+export type PackageScanStatus = Doc<"packages">["scanStatus"];
+
+type PackageReleaseSecurityLike = Pick<
+  Doc<"packageReleases">,
+  "sha256hash" | "vtAnalysis" | "verification" | "staticScan"
+>;
+
+export function normalizePackageScanStatus(status: string | null | undefined): PackageScanStatus {
+  switch (status?.trim().toLowerCase()) {
+    case "clean":
+    case "suspicious":
+    case "malicious":
+    case "pending":
+    case "not-run":
+      return status.trim().toLowerCase() as PackageScanStatus;
+    default:
+      return undefined;
+  }
+}
+
+export function resolvePackageReleaseScanStatus(
+  release: PackageReleaseSecurityLike,
+): 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;
+  if (release.sha256hash) return "pending";
+
+  return verificationStatus ?? "not-run";
+}
+
+export function isPackageBlockedFromPublic(scanStatus: PackageScanStatus) {
+  return scanStatus === "malicious";
+}
+
+export function getPackageDownloadSecurityBlock(release: PackageReleaseSecurityLike) {
+  const scanStatus = resolvePackageReleaseScanStatus(release);
+
+  if (scanStatus === "malicious") {
+    return {
+      status: 403,
+      message:
+        "Blocked: this package release has been flagged as malicious and cannot be downloaded.",
+    };
+  }
+
+  return null;
+}
@@ -6,6 +6,11 @@ export type PublicUser = Pick<
  "_id" | "_creationTime" | "handle" | "name" | "displayName" | "image" | "bio"
 >;

+export type PublicPublisher = Pick<
+  Doc<"publishers">,
+  "_id" | "_creationTime" | "kind" | "handle" | "displayName" | "image" | "bio" | "linkedUserId"
+>;
+
 export type PublicSkill = Pick<
  Doc<"skills">,
  | "_id"
@@ -14,10 +19,12 @@ export type PublicSkill = Pick<
  | "displayName"
  | "summary"
  | "ownerUserId"
+  | "ownerPublisherId"
  | "canonicalSkillId"
  | "forkOf"
  | "latestVersionId"
  | "tags"
+  | "capabilityTags"
  | "badges"
  | "stats"
  | "createdAt"
@@ -38,11 +45,13 @@ export type HydratableSkill = Pick<
  | "displayName"
  | "summary"
  | "ownerUserId"
+  | "ownerPublisherId"
  | "canonicalSkillId"
  | "forkOf"
  | "latestVersionId"
  | "latestVersionSummary"
  | "tags"
+  | "capabilityTags"
  | "badges"
  | "stats"
  | "statsDownloads"
@@ -65,6 +74,7 @@ export type PublicSoul = Pick<
  | "displayName"
  | "summary"
  | "ownerUserId"
+  | "ownerPublisherId"
  | "latestVersionId"
  | "tags"
  | "stats"
@@ -85,6 +95,22 @@ export function toPublicUser(user: Doc<"users"> | null | undefined): PublicUser
  };
 }

+export function toPublicPublisher(
+  publisher: Doc<"publishers"> | null | undefined,
+): PublicPublisher | null {
+  if (!publisher || publisher.deletedAt || publisher.deactivatedAt) return null;
+  return {
+    _id: publisher._id,
+    _creationTime: publisher._creationTime,
+    kind: publisher.kind,
+    handle: publisher.handle,
+    displayName: publisher.displayName,
+    image: publisher.image,
+    bio: publisher.bio,
+    linkedUserId: publisher.linkedUserId,
+  };
+}
+
 export function toPublicSkill(skill: HydratableSkill | null | undefined): PublicSkill | null {
  if (!skill) return null;
  if (!isPublicSkillDoc(skill)) return null;
@@ -112,10 +138,12 @@ export function toPublicSkill(skill: HydratableSkill | null | undefined): Public
    displayName: skill.displayName,
    summary: skill.summary,
    ownerUserId: skill.ownerUserId,
+    ownerPublisherId: skill.ownerPublisherId,
    canonicalSkillId: skill.canonicalSkillId,
    forkOf: skill.forkOf,
    latestVersionId: skill.latestVersionId,
    tags: skill.tags,
+    capabilityTags: skill.capabilityTags,
    badges: skill.badges,
    stats,
    createdAt: skill.createdAt,
@@ -132,6 +160,7 @@ export function toPublicSoul(soul: Doc<"souls"> | null | undefined): PublicSoul
    displayName: soul.displayName,
    summary: soul.summary,
    ownerUserId: soul.ownerUserId,
+    ownerPublisherId: soul.ownerPublisherId,
    latestVersionId: soul.latestVersionId,
    tags: soul.tags,
    stats: soul.stats,
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import {
+  findOversizedPublishFile,
+  getPublishFileSizeError,
+  getPublishTotalSizeError,
+  MAX_PUBLISH_FILE_BYTES,
+} from "./publishLimits";
+
+describe("publishLimits", () => {
+  it("finds files over the max publish file size", () => {
+    expect(
+      findOversizedPublishFile([
+        { path: "small.txt", size: 128 },
+        { path: "big.txt", size: MAX_PUBLISH_FILE_BYTES + 1 },
+      ]),
+    ).toEqual({
+      path: "big.txt",
+      size: MAX_PUBLISH_FILE_BYTES + 1,
+    });
+  });
+
+  it("formats user-facing size errors", () => {
+    expect(getPublishFileSizeError("dist/plugin.wasm")).toBe(
+      'File "dist/plugin.wasm" exceeds 10MB limit',
+    );
+    expect(getPublishTotalSizeError("package")).toBe("Package exceeds 50MB limit");
+  });
+});
@@ -0,0 +1,19 @@
+export const MAX_PUBLISH_TOTAL_BYTES = 50 * 1024 * 1024;
+export const MAX_PUBLISH_FILE_BYTES = 10 * 1024 * 1024;
+
+type SizedPathLike = {
+  path: string;
+  size: number;
+};
+
+export function findOversizedPublishFile<TFile extends SizedPathLike>(files: TFile[]) {
+  return files.find((file) => file.size > MAX_PUBLISH_FILE_BYTES) ?? null;
+}
+
+export function getPublishFileSizeError(path: string) {
+  return `File "${path}" exceeds 10MB limit`;
+}
+
+export function getPublishTotalSizeError(target: "skill bundle" | "package") {
+  return `${target[0]?.toUpperCase() ?? ""}${target.slice(1)} exceeds 50MB limit`;
+}
@@ -0,0 +1,338 @@
+import { ConvexError } from "convex/values";
+import type { Doc, Id } from "../_generated/dataModel";
+import type { MutationCtx, QueryCtx } from "../_generated/server";
+
+export type PublisherRole = "owner" | "admin" | "publisher";
+
+type DbCtx = Pick<QueryCtx | MutationCtx, "db">;
+
+function isMissingPublisherTableError(error: unknown) {
+  if (!(error instanceof Error)) return false;
+  return (
+    /unexpected (query |insert )?table:? (publishers|publishermembers)/i.test(error.message) ||
+    /innerdb\.(insert|patch) is not a function/i.test(error.message)
+  );
+}
+
+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"
+  );
+}
+
+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">,
+    _creationTime: user._creationTime,
+    kind: "user",
+    handle,
+    displayName: user.displayName?.trim() || user.name?.trim() || handle,
+    bio: user.bio?.trim() || undefined,
+    image: user.image,
+    linkedUserId: user._id,
+    trustedPublisher: user.trustedPublisher,
+    createdAt: user.createdAt ?? now,
+    updatedAt: now,
+    deletedAt: undefined,
+    deactivatedAt: undefined,
+  };
+}
+
+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;
+  }
+  try {
+    const publisher = await getPersonalPublisherForUser(ctx, user._id);
+    if (isPublisherActive(publisher)) return publisher;
+  } catch (error) {
+    if (!isMissingPublisherTableError(error)) throw error;
+  }
+  return synthesizePersonalPublisher(user);
+}
+
+export function normalizePublisherHandle(handle: string | undefined | null) {
+  const normalized = handle?.trim().replace(/^@+/, "").toLowerCase();
+  return normalized ? normalized : undefined;
+}
+
+export function isPublisherActive(
+  publisher: Pick<Doc<"publishers">, "deletedAt" | "deactivatedAt"> | null | undefined,
+) {
+  return Boolean(publisher && !publisher.deletedAt && !publisher.deactivatedAt);
+}
+
+export function isPublisherRoleAllowed(role: PublisherRole, allowed: PublisherRole[]) {
+  const ranks: Record<PublisherRole, number> = {
+    publisher: 1,
+    admin: 2,
+    owner: 3,
+  };
+  return allowed.some((candidate) => ranks[role] >= ranks[candidate]);
+}
+
+export async function getPublisherByHandle(ctx: DbCtx, handle: string | undefined | null) {
+  const normalized = normalizePublisherHandle(handle);
+  if (!normalized) return null;
+  try {
+    return await ctx.db
+      .query("publishers")
+      .withIndex("by_handle", (q) => q.eq("handle", normalized))
+      .unique();
+  } catch (error) {
+    if (isMissingPublisherTableError(error)) return null;
+    throw error;
+  }
+}
+
+export async function getUserByHandleOrPersonalPublisher(
+  ctx: DbCtx,
+  handle: string | undefined | null,
+) {
+  const normalized = normalizePublisherHandle(handle);
+  if (!normalized) return null;
+
+  const user = await ctx.db
+    .query("users")
+    .withIndex("handle", (q) => q.eq("handle", normalized))
+    .unique();
+  if (user) return user;
+
+  const publisher = await getPublisherByHandle(ctx, normalized);
+  if (
+    !publisher ||
+    !isPublisherActive(publisher) ||
+    publisher.kind !== "user" ||
+    !publisher.linkedUserId
+  ) {
+    return null;
+  }
+
+  return await ctx.db.get(publisher.linkedUserId);
+}
+
+export async function getActiveUserByHandleOrPersonalPublisher(
+  ctx: DbCtx,
+  handle: string | undefined | null,
+) {
+  const user = await getUserByHandleOrPersonalPublisher(ctx, handle);
+  if (!user || user.deletedAt || user.deactivatedAt) return null;
+  return user;
+}
+
+export async function getPersonalPublisherForUser(ctx: DbCtx, userId: Id<"users">) {
+  try {
+    return await ctx.db
+      .query("publishers")
+      .withIndex("by_linked_user", (q) => q.eq("linkedUserId", userId))
+      .unique();
+  } catch (error) {
+    if (isMissingPublisherTableError(error)) return null;
+    throw error;
+  }
+}
+
+export async function ensurePersonalPublisherForUser(
+  ctx: Pick<MutationCtx, "db">,
+  user: Doc<"users">,
+) {
+  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);
+  } catch (error) {
+    if (!isMissingPublisherTableError(error)) throw error;
+    return synthesizePersonalPublisher(user);
+  }
+  if (existing && isPublisherActive(existing)) {
+    const existingPublisher = existing;
+    const now = Date.now();
+    const conflict = await getPublisherByHandle(ctx, handle);
+    if (conflict && conflict._id !== existingPublisher._id) {
+      throw new ConvexError(`Publisher handle "@${handle}" is already claimed`);
+    }
+    try {
+      await ctx.db.patch(existingPublisher._id, {
+        handle,
+        displayName: user.displayName?.trim() || user.name?.trim() || handle,
+        bio: user.bio?.trim() || undefined,
+        image: user.image,
+        linkedUserId: user._id,
+        trustedPublisher: user.trustedPublisher,
+        deletedAt: undefined,
+        deactivatedAt: undefined,
+        updatedAt: now,
+      });
+      if (user.personalPublisherId !== existingPublisher._id) {
+        await ctx.db.patch(user._id, {
+          personalPublisherId: existingPublisher._id,
+          updatedAt: now,
+        });
+      }
+      const existingMember = await ctx.db
+        .query("publisherMembers")
+        .withIndex("by_publisher_user", (q) =>
+          q.eq("publisherId", existingPublisher._id).eq("userId", user._id),
+        )
+        .unique();
+      if (!existingMember) {
+        await ctx.db.insert("publisherMembers", {
+          publisherId: existingPublisher._id,
+          userId: user._id,
+          role: "owner",
+          createdAt: now,
+          updatedAt: now,
+        });
+      }
+      return await ctx.db.get(existingPublisher._id);
+    } catch (error) {
+      if (isMissingPublisherTableError(error)) return synthesizePersonalPublisher(user);
+      throw error;
+    }
+  }
+
+  const conflict = await getPublisherByHandle(ctx, handle);
+  if (conflict && conflict.linkedUserId !== user._id) {
+    throw new ConvexError(`Publisher handle "@${handle}" is already claimed`);
+  }
+
+  const now = Date.now();
+  try {
+    const publisherId =
+      conflict?._id ??
+      (await ctx.db.insert("publishers", {
+        kind: "user",
+        handle,
+        displayName: user.displayName?.trim() || user.name?.trim() || handle,
+        bio: user.bio?.trim() || undefined,
+        image: user.image,
+        linkedUserId: user._id,
+        trustedPublisher: user.trustedPublisher,
+        createdAt: now,
+        updatedAt: now,
+      }));
+
+    if (conflict) {
+      await ctx.db.patch(conflict._id, {
+        displayName: user.displayName?.trim() || user.name?.trim() || handle,
+        bio: user.bio?.trim() || undefined,
+        image: user.image,
+        linkedUserId: user._id,
+        trustedPublisher: user.trustedPublisher,
+        deletedAt: undefined,
+        deactivatedAt: undefined,
+        updatedAt: now,
+      });
+    }
+
+    const existingMember = await ctx.db
+      .query("publisherMembers")
+      .withIndex("by_publisher_user", (q) =>
+        q.eq("publisherId", publisherId).eq("userId", user._id),
+      )
+      .unique();
+    if (!existingMember) {
+      await ctx.db.insert("publisherMembers", {
+        publisherId,
+        userId: user._id,
+        role: "owner",
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+
+    await ctx.db.patch(user._id, {
+      personalPublisherId: publisherId,
+      updatedAt: now,
+    });
+
+    return await ctx.db.get(publisherId);
+  } catch (error) {
+    if (isMissingPublisherTableError(error)) return synthesizePersonalPublisher(user);
+    throw error;
+  }
+}
+
+export async function getPublisherMembership(
+  ctx: DbCtx,
+  publisherId: Id<"publishers">,
+  userId: Id<"users">,
+) {
+  try {
+    return await ctx.db
+      .query("publisherMembers")
+      .withIndex("by_publisher_user", (q) => q.eq("publisherId", publisherId).eq("userId", userId))
+      .unique();
+  } catch (error) {
+    if (isMissingPublisherTableError(error)) return null;
+    throw error;
+  }
+}
+
+export async function requirePublisherRole(
+  ctx: DbCtx,
+  params: {
+    publisherId: Id<"publishers">;
+    userId: Id<"users">;
+    allowed: PublisherRole[];
+  },
+) {
+  const publisher = await ctx.db.get(params.publisherId);
+  if (!isPublisherActive(publisher)) throw new ConvexError("Publisher not found");
+  const membership = await getPublisherMembership(ctx, params.publisherId, params.userId);
+  if (!membership || !isPublisherRoleAllowed(membership.role, params.allowed)) {
+    throw new ConvexError("Forbidden");
+  }
+  return { publisher, membership };
+}
+
+export async function resolvePublisherForActor(
+  ctx: Pick<MutationCtx, "db">,
+  params: {
+    actor: Doc<"users">;
+    ownerHandle?: string | null;
+    allowed: PublisherRole[];
+  },
+) {
+  const personalPublisher = await ensurePersonalPublisherForUser(ctx, params.actor);
+  const requestedHandle = normalizePublisherHandle(params.ownerHandle);
+  if (!requestedHandle) {
+    return personalPublisher;
+  }
+  if (requestedHandle === personalPublisher?.handle) return personalPublisher;
+
+  const publisher = await getPublisherByHandle(ctx, requestedHandle);
+  if (!publisher || !isPublisherActive(publisher)) {
+    throw new ConvexError(`Publisher "@${requestedHandle}" not found`);
+  }
+  const membership = await getPublisherMembership(ctx, publisher._id, params.actor._id);
+  if (!membership || !isPublisherRoleAllowed(membership.role, params.allowed)) {
+    throw new ConvexError(`You do not have publish access for "@${requestedHandle}"`);
+  }
+  return publisher;
+}
+
+export async function getOwnerPublisher(
+  ctx: DbCtx,
+  params: {
+    ownerPublisherId?: Id<"publishers"> | null;
+    ownerUserId?: Id<"users"> | null;
+  },
+) {
+  if (params.ownerPublisherId) {
+    const publisher = await ctx.db.get(params.ownerPublisherId);
+    if (isPublisherActive(publisher)) return publisher;
+  }
+  if (!params.ownerUserId) return null;
+  const user = await ctx.db.get(params.ownerUserId);
+  if (!user || user.deletedAt || user.deactivatedAt) return null;
+  return await getPersonalPublisherForUserOrFallback(ctx, user);
+}
@@ -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";
@@ -7,8 +8,14 @@ import { getSkillBadgeMap, isSkillHighlighted } from "./badges";
 import { generateChangelogForPublish } from "./changelog";
 import { generateEmbedding } from "./embeddings";
 import { requireGitHubAccountAge } from "./githubAccount";
-import { runStaticModerationScan } from "./moderationEngine";
 import type { PublicUser } from "./public";
+import {
+  findOversizedPublishFile,
+  getPublishFileSizeError,
+  getPublishTotalSizeError,
+  MAX_PUBLISH_TOTAL_BYTES,
+} from "./publishLimits";
+import { deriveSkillCapabilityTags } from "./skillCapabilityTags";
 import {
  computeQualitySignals,
  evaluateQuality,
@@ -28,9 +35,9 @@ import {
  sanitizePath,
 } from "./skills";
 import { generateSkillSummary } from "./skillSummary";
+import { runStaticPublishScan } from "./staticPublishScan";
 import type { WebhookSkillPayload } from "./webhooks";

-const MAX_TOTAL_BYTES = 50 * 1024 * 1024;
 const MAX_FILES_FOR_EMBEDDING = 40;
 const QUALITY_WINDOW_MS = 24 * 60 * 60 * 1000;
 const QUALITY_ACTIVITY_LIMIT = 60;
@@ -73,6 +80,7 @@ export type PublishOptions = {
  bypassQualityGate?: boolean;
  skipBackup?: boolean;
  skipWebhook?: boolean;
+  ownerPublisherId?: Id<"publishers">;
 };

 export async function publishVersionForUser(
@@ -106,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");
@@ -119,9 +128,14 @@ export async function publishVersionForUser(
    throw new ConvexError("Only text-based files are allowed");
  }

+  const oversizedFile = findOversizedPublishFile(publishFiles);
+  if (oversizedFile) {
+    throw new ConvexError(getPublishFileSizeError(oversizedFile.path));
+  }
+
  const totalBytes = publishFiles.reduce((sum, file) => sum + file.size, 0);
-  if (totalBytes > MAX_TOTAL_BYTES) {
-    throw new ConvexError("Skill bundle exceeds 50MB limit");
+  if (totalBytes > MAX_PUBLISH_TOTAL_BYTES) {
+    throw new ConvexError(getPublishTotalSizeError("skill bundle"));
  }

  const readmeFile = publishFiles.find(
@@ -221,14 +235,13 @@ export async function publishVersionForUser(
    .filter((file) => !file.path.toLowerCase().endsWith(".md"))
    .slice(0, MAX_FILES_FOR_EMBEDDING);

-  const staticScan = runStaticModerationScan({
+  const staticScan = await runStaticPublishScan(ctx, {
    slug,
    displayName,
    summary,
    frontmatter,
    metadata,
-    files: publishFiles.map((file) => ({ path: file.path, size: file.size })),
-    fileContents,
+    files: publishFiles,
  });

  const embeddingText = buildEmbeddingText({
@@ -236,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 })),
@@ -263,6 +284,7 @@ export async function publishVersionForUser(

  const publishResult = (await ctx.runMutation(internal.skills.insertVersion, {
    userId,
+    ownerPublisherId: options.ownerPublisherId,
    slug,
    displayName,
    version,
@@ -287,6 +309,7 @@ export async function publishVersionForUser(
      clawdis,
      license: PLATFORM_SKILL_LICENSE,
    },
+    capabilityTags,
    summary,
    staticScan,
    embedding,
@@ -157,13 +157,14 @@ describe("digestToOwnerInfo", () => {
    expect(result).not.toBeNull();
    expect(result!.ownerHandle).toBe("jdoe");
    expect(result!.owner).toEqual({
-      _id: "users:owner",
+      _id: "publishers:missing",
      _creationTime: 0,
+      kind: "user",
      handle: "jdoe",
-      name: "John",
      displayName: "John Doe",
      image: "https://example.com/avatar.png",
      bio: undefined,
+      linkedUserId: "users:owner",
    });
  });

@@ -190,13 +191,14 @@ describe("digestToOwnerInfo", () => {
    expect(result).not.toBeNull();
    expect(result!.ownerHandle).toBe("users:owner");
    expect(result!.owner).toEqual({
-      _id: "users:owner",
+      _id: "publishers:missing",
      _creationTime: 0,
-      handle: undefined,
-      name: "No Handle User",
+      kind: "user",
+      handle: "users:owner",
      displayName: "No Handle",
      image: "https://example.com/avatar.png",
      bio: undefined,
+      linkedUserId: "users:owner",
    });
  });

@@ -1,11 +1,13 @@
 import type { Doc, Id } from "../_generated/dataModel";
 import type { MutationCtx } from "../_generated/server";
-import type { HydratableSkill, PublicUser } from "./public";
+import type { HydratableSkill, PublicPublisher } from "./public";

 function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
  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`
@@ -16,11 +18,13 @@ const SHARED_KEYS = [
  "displayName",
  "summary",
  "ownerUserId",
+  "ownerPublisherId",
  "canonicalSkillId",
  "forkOf",
  "latestVersionId",
  "latestVersionSummary",
  "tags",
+  "capabilityTags",
  "badges",
  "stats",
  "statsDownloads",
@@ -33,13 +37,14 @@ 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]> & {
  skillId: Id<"skills">;
  isSuspicious?: boolean;
  ownerHandle?: string;
+  ownerKind?: "user" | "org";
  ownerName?: string;
  ownerDisplayName?: string;
  ownerImage?: string;
@@ -106,14 +111,21 @@ function hasDigestChanged(
 export function digestToOwnerInfo(
  digest: Pick<
    Doc<"skillSearchDigest">,
-    "ownerHandle" | "ownerName" | "ownerDisplayName" | "ownerImage" | "ownerUserId"
+    | "ownerHandle"
+    | "ownerKind"
+    | "ownerName"
+    | "ownerDisplayName"
+    | "ownerImage"
+    | "ownerUserId"
+    | "ownerPublisherId"
  >,
-): { ownerHandle: string | null; owner: PublicUser | null } | null {
+): { ownerHandle: string | null; owner: PublicPublisher | null } | null {
  if (digest.ownerHandle === undefined) return null;
  // 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.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
  // name/displayName/image populated).
@@ -126,13 +138,14 @@ export function digestToOwnerInfo(
    owner:
      handle || hasProfileData
        ? {
-            _id: digest.ownerUserId,
+            _id: digest.ownerPublisherId ?? ("publishers:missing" as Id<"publishers">),
            _creationTime: 0,
-            handle,
-            name: digest.ownerName,
-            displayName: digest.ownerDisplayName,
+            handle: resolvedHandle,
+            displayName: digest.ownerDisplayName ?? digest.ownerName ?? resolvedHandle,
            image: digest.ownerImage,
            bio: undefined,
+            kind: digest.ownerKind ?? "user",
+            linkedUserId: digest.ownerKind === "org" ? undefined : digest.ownerUserId,
          }
        : null,
  };
@@ -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,42 @@
+import type { ActionCtx } from "../_generated/server";
+import { runStaticModerationScan, type StaticScanResult } from "./moderationEngine";
+import { readStorageText } from "./packageRegistry";
+import { isTextFile } from "./skills";
+
+type PublishFile = {
+  path: string;
+  size: number;
+  storageId: string;
+  contentType?: string;
+};
+
+type StaticPublishScanInput = {
+  slug: string;
+  displayName: string;
+  summary?: string;
+  frontmatter?: Record<string, unknown>;
+  metadata?: unknown;
+  files: PublishFile[];
+};
+
+export async function runStaticPublishScan(
+  ctx: Pick<ActionCtx, "storage">,
+  input: StaticPublishScanInput,
+): Promise<StaticScanResult> {
+  const fileContents: Array<{ path: string; content: string }> = [];
+  for (const file of input.files) {
+    if (!isTextFile(file.path, file.contentType ?? undefined)) continue;
+    const content = await readStorageText(ctx, file.storageId);
+    fileContents.push({ path: file.path, content });
+  }
+
+  return runStaticModerationScan({
+    slug: input.slug,
+    displayName: input.displayName,
+    summary: input.summary,
+    frontmatter: input.frontmatter ?? {},
+    metadata: input.metadata,
+    files: input.files.map((file) => ({ path: file.path, size: file.size })),
+    fileContents,
+  });
+}
@@ -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,
+    });
+  }
+}
@@ -20,6 +20,30 @@ import {
  SECURITY_EVALUATOR_SYSTEM_PROMPT,
 } from "./lib/securityPrompt";

+const internalRefs = internal as unknown as {
+  packages: {
+    getReleaseByIdInternal: unknown;
+    getPackageByIdInternal: unknown;
+    updateReleaseLlmAnalysisInternal: unknown;
+  };
+};
+
+async function runQueryRef<T>(
+  ctx: { runQuery: (ref: never, args: never) => Promise<unknown> },
+  ref: unknown,
+  args: unknown,
+): Promise<T> {
+  return (await ctx.runQuery(ref as never, args as never)) as T;
+}
+
+async function runMutationRef<T>(
+  ctx: { runMutation: (ref: never, args: never) => Promise<unknown> },
+  ref: unknown,
+  args: unknown,
+): Promise<T> {
+  return (await ctx.runMutation(ref as never, args as never)) as T;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -249,6 +273,182 @@ export const evaluateWithLlm = internalAction({
  },
 });

+export const evaluatePackageReleaseWithLlm = internalAction({
+  args: {
+    releaseId: v.id("packageReleases"),
+  },
+  handler: async (ctx, args) => {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      console.log("[llmEval] OPENAI_API_KEY not configured, skipping package evaluation");
+      return;
+    }
+
+    const model = getLlmEvalModel();
+    const storeError = async (message: string) => {
+      console.error(`[llmEval:package] ${message}`);
+      await runMutationRef(ctx, internalRefs.packages.updateReleaseLlmAnalysisInternal, {
+        releaseId: args.releaseId,
+        llmAnalysis: {
+          status: "error",
+          summary: message,
+          model,
+          checkedAt: Date.now(),
+        },
+      });
+    };
+
+    const release = (await runQueryRef(ctx, internalRefs.packages.getReleaseByIdInternal, {
+      releaseId: args.releaseId,
+    })) as Doc<"packageReleases"> | null;
+    if (!release || release.softDeletedAt) {
+      await storeError(`Release ${args.releaseId} not found`);
+      return;
+    }
+
+    const pkg = (await runQueryRef(ctx, internalRefs.packages.getPackageByIdInternal, {
+      packageId: release.packageId,
+    })) as Doc<"packages"> | null;
+    if (!pkg) {
+      await storeError(`Package ${release.packageId} not found`);
+      return;
+    }
+
+    let readmeContent = "";
+    const fileContents: Array<{ path: string; content: string }> = [];
+    for (const f of release.files) {
+      try {
+        const blob = await ctx.storage.get(f.storageId as Id<"_storage">);
+        if (!blob) continue;
+        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")
+        ) {
+          readmeContent = content;
+        }
+      } catch {
+        // Best-effort read.
+      }
+    }
+
+    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 allContent = [readmeContent, ...fileContents.map((f) => f.content)].join("\n");
+    const injectionSignals = detectInjectionPatterns(allContent);
+
+    const evalCtx: SkillEvalContext = {
+      slug: pkg.name,
+      displayName: pkg.displayName,
+      ownerUserId: String(pkg.ownerUserId),
+      version: release.version,
+      createdAt: release.createdAt,
+      summary: release.summary ?? pkg.summary ?? undefined,
+      source: pkg.sourceRepo ?? undefined,
+      homepage: undefined,
+      parsed: {
+        frontmatter: {},
+        metadata: {
+          compatibility: release.compatibility,
+          capabilities: release.capabilities,
+          verification: release.verification,
+          staticScan: release.staticScan,
+        },
+      },
+      files: release.files.map((f) => ({ path: f.path, size: f.size })),
+      skillMdContent: readmeContent,
+      fileContents,
+      injectionSignals,
+    };
+
+    const userMessage = assembleEvalUserMessage(evalCtx);
+    const MAX_RETRIES = 3;
+    let raw: string | null = null;
+    try {
+      const body = JSON.stringify({
+        model,
+        instructions: SECURITY_EVALUATOR_SYSTEM_PROMPT,
+        input: userMessage,
+        max_output_tokens: LLM_EVAL_MAX_OUTPUT_TOKENS,
+        text: {
+          format: {
+            type: "json_object",
+          },
+        },
+      });
+
+      let response: Response | null = null;
+      for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        response = await fetch("https://api.openai.com/v1/responses", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body,
+        });
+
+        if (response.status === 429 || response.status >= 500) {
+          if (attempt < MAX_RETRIES) {
+            const delay = 2 ** attempt * 2000 + Math.random() * 1000;
+            await new Promise((r) => setTimeout(r, delay));
+            continue;
+          }
+        }
+        break;
+      }
+
+      if (!response || !response.ok) {
+        const errorText = response ? await response.text() : "No response";
+        await storeError(`OpenAI API error (${response?.status}): ${errorText.slice(0, 200)}`);
+        return;
+      }
+
+      const payload = (await response.json()) as unknown;
+      raw = extractResponseText(payload);
+    } catch (error) {
+      await storeError(
+        `OpenAI API call failed: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return;
+    }
+
+    if (!raw) {
+      await storeError("Empty response from OpenAI");
+      return;
+    }
+
+    const result = parseLlmEvalResponse(raw);
+    if (!result) {
+      await storeError("Failed to parse LLM evaluation response");
+      return;
+    }
+
+    await runMutationRef(ctx, internalRefs.packages.updateReleaseLlmAnalysisInternal, {
+      releaseId: args.releaseId,
+      llmAnalysis: {
+        status: verdictToStatus(result.verdict),
+        verdict: result.verdict,
+        confidence: result.confidence,
+        summary: result.summary,
+        dimensions: result.dimensions,
+        guidance: result.guidance,
+        findings: result.findings || undefined,
+        model,
+        checkedAt: Date.now(),
+      },
+    });
+  },
+});
+
 // ---------------------------------------------------------------------------
 // Convenience: evaluate a single skill by slug (for testing / manual runs)
 // Usage: npx convex run llmEval:evaluateBySlug '{"slug": "transcribeexx"}'
@@ -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() });
+  },
+});
@@ -0,0 +1,875 @@
+import { getAuthUserId } from "@convex-dev/auth/server";
+import { describe, expect, it, vi } from "vitest";
+import {
+  addMember,
+  listMine,
+  migrateLegacyPublisherHandleToOrgInternal,
+  removeMember,
+  updateProfile,
+} from "./publishers";
+
+vi.mock("@convex-dev/auth/server", () => ({
+  getAuthUserId: vi.fn(),
+}));
+
+type WrappedHandler<TArgs, TResult = unknown> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>;
+};
+
+const addMemberHandler = (
+  addMember as unknown as WrappedHandler<{
+    publisherId: string;
+    userHandle: string;
+    role: "owner" | "admin" | "publisher";
+  }>
+)._handler;
+
+const removeMemberHandler = (
+  removeMember as unknown as WrappedHandler<{ publisherId: string; userId: string }>
+)._handler;
+
+const migrateLegacyPublisherHandleToOrgInternalHandler = (
+  migrateLegacyPublisherHandleToOrgInternal as unknown as WrappedHandler<
+    {
+      actorUserId: string;
+      handle: string;
+      fallbackUserHandle?: string;
+      displayName?: string;
+    },
+    {
+      ok: true;
+      handle: string;
+      orgPublisherId: string;
+      legacyUserId: string;
+      fallbackUserHandle: string;
+      personalPublisherId: string | null;
+      convertedExistingPublisher: boolean;
+      packagesMigrated: number;
+    }
+  >
+)._handler;
+
+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);
+    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: "acme",
+              displayName: "Acme",
+            };
+          }
+          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}`);
+        }),
+        insert: vi.fn(),
+        patch: vi.fn(),
+        delete: vi.fn(),
+        replace: vi.fn(),
+        normalizeId: vi.fn(),
+      },
+    };
+
+    await expect(
+      addMemberHandler(
+        ctx as never,
+        { publisherId: "publishers:org", userHandle: "peter", role: "owner" } as never,
+      ),
+    ).rejects.toThrow("Only org owners can promote members to owner");
+  });
+
+  it("prevents removing the last remaining owner", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:owner" as never);
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "users:owner") return { _id: id };
+          if (id === "publishers:org") {
+            return {
+              _id: id,
+              kind: "org",
+              handle: "acme",
+              displayName: "Acme",
+            };
+          }
+          return null;
+        }),
+        query: vi.fn((table: string) => {
+          if (table === "publisherMembers") {
+            return {
+              withIndex: vi.fn((indexName: string) => {
+                if (indexName === "by_publisher_user") {
+                  return {
+                    unique: vi
+                      .fn()
+                      .mockResolvedValueOnce({
+                        _id: "publisherMembers:owner-actor",
+                        publisherId: "publishers:org",
+                        userId: "users:owner",
+                        role: "owner",
+                      })
+                      .mockResolvedValueOnce({
+                        _id: "publisherMembers:owner-target",
+                        publisherId: "publishers:org",
+                        userId: "users:owner",
+                        role: "owner",
+                      }),
+                  };
+                }
+                if (indexName === "by_publisher") {
+                  return {
+                    collect: vi.fn().mockResolvedValue([
+                      {
+                        _id: "publisherMembers:owner-target",
+                        publisherId: "publishers:org",
+                        userId: "users:owner",
+                        role: "owner",
+                      },
+                    ]),
+                  };
+                }
+                throw new Error(`unexpected index ${indexName}`);
+              }),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+        delete: vi.fn(),
+        insert: vi.fn(),
+        patch: vi.fn(),
+        replace: vi.fn(),
+        normalizeId: vi.fn(),
+      },
+    };
+
+    await expect(
+      removeMemberHandler(
+        ctx as never,
+        { publisherId: "publishers:org", userId: "users:owner" } as never,
+      ),
+    ).rejects.toThrow("Publisher must have at least one owner");
+  });
+
+  it("adds a member when the requested handle resolves via a personal publisher", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:owner" as never);
+    const publisherMembers: Array<Record<string, unknown>> = [
+      {
+        _id: "publisherMembers:owner",
+        publisherId: "publishers:org",
+        userId: "users:owner",
+        role: "owner",
+      },
+    ];
+    const insert = vi.fn(async (table: string, value: Record<string, unknown>) => {
+      if (table === "publisherMembers") {
+        const row = { _id: "publisherMembers:new", ...value };
+        publisherMembers.push(row);
+        return row._id;
+      }
+      if (table === "auditLogs") return "auditLogs:1";
+      if (table === "publishers") return "publishers:jaredforreal";
+      throw new Error(`unexpected insert ${table}`);
+    });
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "users:owner") return { _id: id };
+          if (id === "users:jared") {
+            return {
+              _id: id,
+              _creationTime: 1,
+              handle: undefined,
+              name: "JaredForReal",
+              displayName: "Jared",
+              trustedPublisher: false,
+              createdAt: 1,
+              updatedAt: 1,
+            };
+          }
+          if (id === "publishers:org") {
+            return {
+              _id: id,
+              kind: "org",
+              handle: "zai-org",
+              displayName: "ZAI Org",
+            };
+          }
+          if (id === "publishers:jaredforreal") {
+            return {
+              _id: id,
+              _creationTime: 1,
+              kind: "user",
+              handle: "jaredforreal",
+              displayName: "Jared",
+              linkedUserId: "users:jared",
+              trustedPublisher: false,
+              createdAt: 1,
+              updatedAt: 1,
+            };
+          }
+          return null;
+        }),
+        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,
+                    ),
+                  };
+                },
+              ),
+            };
+          }
+          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;
+                    }),
+                  };
+                },
+              ),
+            };
+          }
+          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;
+                    }),
+                  };
+                },
+              ),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+        insert,
+        patch: vi.fn(),
+        delete: vi.fn(),
+        replace: vi.fn(),
+        normalizeId: vi.fn(),
+      },
+    };
+
+    await expect(
+      addMemberHandler(
+        ctx as never,
+        { publisherId: "publishers:org", userHandle: "jaredforreal", role: "admin" } as never,
+      ),
+    ).resolves.toEqual({ ok: true });
+
+    expect(insert).toHaveBeenCalledWith(
+      "publisherMembers",
+      expect.objectContaining({
+        publisherId: "publishers:org",
+        userId: "users:jared",
+        role: "admin",
+      }),
+    );
+  });
+
+  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", () => {
+  it("lists a synthesized personal publisher when membership rows are missing", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:alice" as never);
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "users:alice") {
+            return {
+              _id: id,
+              _creationTime: 1,
+              handle: "alice",
+              displayName: "Alice",
+              trustedPublisher: false,
+              createdAt: 1,
+              updatedAt: 1,
+            };
+          }
+          return null;
+        }),
+        query: vi.fn((table: string) => {
+          if (table === "publisherMembers") {
+            return {
+              withIndex: vi.fn((indexName: string) => {
+                if (indexName !== "by_user") throw new Error(`unexpected index ${indexName}`);
+                return { collect: vi.fn().mockResolvedValue([]) };
+              }),
+            };
+          }
+          if (table === "publishers") {
+            return {
+              withIndex: vi.fn((indexName: string) => {
+                if (indexName !== "by_linked_user") {
+                  throw new Error(`unexpected index ${indexName}`);
+                }
+                return { unique: vi.fn().mockResolvedValue(null) };
+              }),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+      },
+    };
+
+    await expect(listMineHandler(ctx as never, {} as never)).resolves.toEqual([
+      expect.objectContaining({
+        role: "owner",
+        publisher: expect.objectContaining({
+          handle: "alice",
+          kind: "user",
+          linkedUserId: "users:alice",
+        }),
+      }),
+    ]);
+  });
+});
+
+describe("legacy publisher migration", () => {
+  it("converts a legacy personal publisher into an org and rehomes package ownership", async () => {
+    vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000);
+
+    const users = new Map<string, Record<string, unknown>>([
+      ["users:admin", { _id: "users:admin", role: "admin" }],
+      [
+        "users:openclaw",
+        {
+          _id: "users:openclaw",
+          _creationTime: 1,
+          handle: "openclaw",
+          displayName: "OpenClaw",
+          trustedPublisher: true,
+          personalPublisherId: "publishers:openclaw",
+          createdAt: 1,
+          updatedAt: 1,
+        },
+      ],
+    ]);
+    const publishers = new Map<string, Record<string, unknown>>([
+      [
+        "publishers:openclaw",
+        {
+          _id: "publishers:openclaw",
+          _creationTime: 1,
+          kind: "user",
+          handle: "openclaw",
+          displayName: "OpenClaw",
+          linkedUserId: "users:openclaw",
+          trustedPublisher: true,
+          createdAt: 1,
+          updatedAt: 1,
+        },
+      ],
+      [
+        "publishers:openclaw-user",
+        {
+          _id: "publishers:openclaw-user",
+          _creationTime: 1,
+          kind: "user",
+          handle: "openclaw-user",
+          displayName: "OpenClaw User",
+          linkedUserId: "users:openclaw",
+          trustedPublisher: true,
+          createdAt: 1,
+          updatedAt: 1,
+        },
+      ],
+    ]);
+    const packages = [
+      {
+        _id: "packages:demo",
+        ownerUserId: "users:openclaw",
+        ownerPublisherId: undefined,
+        updatedAt: 1,
+      },
+    ];
+    const publisherMembers = [
+      {
+        _id: "publisherMembers:openclaw-owner",
+        publisherId: "publishers:openclaw",
+        userId: "users:openclaw",
+        role: "owner",
+        createdAt: 1,
+        updatedAt: 1,
+      },
+    ];
+
+    const patch = vi.fn(async (id: string, value: Record<string, unknown>) => {
+      if (users.has(id)) {
+        users.set(id, { ...users.get(id), ...value });
+        return;
+      }
+      if (publishers.has(id)) {
+        publishers.set(id, { ...publishers.get(id), ...value });
+        return;
+      }
+      const pkg = packages.find((entry) => entry._id === id);
+      if (pkg) {
+        Object.assign(pkg, value);
+        return;
+      }
+      const member = publisherMembers.find((entry) => entry._id === id);
+      if (member) {
+        Object.assign(member, value);
+        return;
+      }
+      throw new Error(`unexpected patch ${id}`);
+    });
+
+    const insert = vi.fn(async (table: string, value: Record<string, unknown>) => {
+      if (table === "publishers") {
+        const id = "publishers:openclaw-user";
+        publishers.set(id, { _id: id, _creationTime: 1, ...value });
+        return id;
+      }
+      if (table === "publisherMembers") {
+        const id = `publisherMembers:${publisherMembers.length + 1}`;
+        publisherMembers.push({
+          _id: id,
+          publisherId: String(value.publisherId),
+          userId: String(value.userId),
+          role: String(value.role),
+          createdAt: Number(value.createdAt),
+          updatedAt: Number(value.updatedAt),
+        });
+        return id;
+      }
+      if (table === "auditLogs") return "auditLogs:1";
+      throw new Error(`unexpected insert ${table}`);
+    });
+
+    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,
+                ),
+              };
+            },
+          ),
+        };
+      }
+      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;
+                }),
+              };
+            },
+          ),
+        };
+      }
+      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,
+                ),
+              };
+            },
+          ),
+        };
+      }
+      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 [];
+                }),
+              };
+            },
+          ),
+        };
+      }
+      if (table === "skills") {
+        return {
+          withIndex: vi.fn(() => ({
+            collect: vi.fn(async () => []),
+          })),
+        };
+      }
+      throw new Error(`unexpected table ${table}`);
+    });
+
+    const result = await migrateLegacyPublisherHandleToOrgInternalHandler(
+      {
+        db: {
+          get: vi.fn(async (id: string) => users.get(id) ?? publishers.get(id) ?? null),
+          query,
+          patch,
+          insert,
+          delete: vi.fn(),
+          replace: vi.fn(),
+          normalizeId: vi.fn(),
+        },
+      } as never,
+      {
+        actorUserId: "users:admin",
+        handle: "openclaw",
+        fallbackUserHandle: "openclaw-user",
+        displayName: "OpenClaw",
+      } as never,
+    );
+
+    expect(result).toMatchObject({
+      ok: true,
+      handle: "openclaw",
+      orgPublisherId: "publishers:openclaw",
+      legacyUserId: "users:openclaw",
+      fallbackUserHandle: "openclaw-user",
+      personalPublisherId: "publishers:openclaw-user",
+      convertedExistingPublisher: true,
+      packagesMigrated: 1,
+    });
+    expect(users.get("users:openclaw")).toEqual(
+      expect.objectContaining({
+        handle: "openclaw-user",
+        personalPublisherId: "publishers:openclaw-user",
+      }),
+    );
+    expect(publishers.get("publishers:openclaw")).toEqual(
+      expect.objectContaining({
+        kind: "org",
+        handle: "openclaw",
+        linkedUserId: undefined,
+      }),
+    );
+    expect(publishers.get("publishers:openclaw-user")).toEqual(
+      expect.objectContaining({
+        kind: "user",
+        handle: "openclaw-user",
+        linkedUserId: "users:openclaw",
+      }),
+    );
+    expect(packages[0]).toEqual(
+      expect.objectContaining({
+        ownerPublisherId: "publishers:openclaw",
+      }),
+    );
+  });
+});
@@ -0,0 +1,757 @@
+import { getAuthUserId } from "@convex-dev/auth/server";
+import { ConvexError, v } from "convex/values";
+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,
+  getPublisherByHandle,
+  getPublisherMembership,
+  getPersonalPublisherForUserOrFallback,
+  getPersonalPublisherForUser,
+  isPublisherRoleAllowed,
+  normalizePublisherHandle,
+} from "./lib/publishers";
+
+const PUBLISHER_HANDLE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
+
+function validateHandle(rawHandle: string) {
+  const handle = normalizePublisherHandle(rawHandle);
+  if (!handle) throw new ConvexError("Handle is required");
+  if (!PUBLISHER_HANDLE_PATTERN.test(handle)) {
+    throw new ConvexError("Handle must be lowercase, url-safe, and 2-40 characters");
+  }
+  return handle;
+}
+
+async function getUserByHandle(ctx: Pick<MutationCtx, "db">, handle: string) {
+  return await ctx.db
+    .query("users")
+    .withIndex("handle", (q) => q.eq("handle", handle))
+    .unique();
+}
+
+function appendHandleSuffix(base: string, suffix: number) {
+  const suffixText = suffix <= 1 ? "" : `-${suffix}`;
+  const maxBaseLength = Math.max(2, 40 - suffixText.length);
+  const trimmedBase = base.slice(0, maxBaseLength);
+  return `${trimmedBase}${suffixText}`;
+}
+
+async function resolveAvailableUserHandle(
+  ctx: Pick<MutationCtx, "db">,
+  baseHandle: string,
+  excludeUserId?: Id<"users">,
+) {
+  for (let suffix = 1; suffix <= 50; suffix += 1) {
+    const candidate = appendHandleSuffix(baseHandle, suffix);
+    if (!PUBLISHER_HANDLE_PATTERN.test(candidate)) continue;
+    const existingUser = await getUserByHandle(ctx, candidate);
+    if (existingUser && existingUser._id !== excludeUserId) continue;
+    const existingPublisher = await getPublisherByHandle(ctx, candidate);
+    if (
+      existingPublisher &&
+      !(existingPublisher.kind === "user" && existingPublisher.linkedUserId === excludeUserId)
+    ) {
+      continue;
+    }
+    return candidate;
+  }
+  throw new ConvexError(`Unable to find an available fallback handle for "@${baseHandle}"`);
+}
+
+async function migrateLegacyPublisherHandleToOrgWithActor(
+  ctx: Pick<MutationCtx, "db">,
+  args: {
+    actorUserId: Id<"users">;
+    handle: string;
+    fallbackUserHandle?: string;
+    displayName?: string;
+  },
+) {
+  const actor = await ctx.db.get(args.actorUserId);
+  if (!actor || actor.deletedAt || actor.deactivatedAt) throw new ConvexError("Unauthorized");
+  assertAdmin(actor);
+
+  const orgHandle = validateHandle(args.handle);
+  const fallbackBase = validateHandle(args.fallbackUserHandle ?? `${orgHandle}-user`);
+  const now = Date.now();
+
+  const handlePublisher = await getPublisherByHandle(ctx, orgHandle);
+  const legacyUser =
+    (handlePublisher?.linkedUserId ? await ctx.db.get(handlePublisher.linkedUserId) : null) ??
+    (await getUserByHandle(ctx, orgHandle));
+  if (!legacyUser || legacyUser.deletedAt || legacyUser.deactivatedAt) {
+    throw new ConvexError(`Legacy user "@${orgHandle}" not found`);
+  }
+
+  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
+      : personalPublisher?.kind === "user" &&
+          personalPublisher.linkedUserId === legacyUser._id &&
+          personalPublisher.handle === orgHandle
+        ? personalPublisher
+        : null;
+
+  const fallbackHandle = await resolveAvailableUserHandle(ctx, fallbackBase, legacyUser._id);
+  let nextLegacyUser: Doc<"users"> = legacyUser;
+  const needsDetachedPersonalPublisher = Boolean(
+    convertiblePublisher && legacyUser.personalPublisherId === convertiblePublisher._id,
+  );
+  if (legacyUser.handle === orgHandle || needsDetachedPersonalPublisher) {
+    const userPatch: Partial<Doc<"users">> = {
+      updatedAt: now,
+    };
+    if (legacyUser.handle === orgHandle) {
+      userPatch.handle = fallbackHandle;
+    }
+    if (needsDetachedPersonalPublisher) {
+      userPatch.personalPublisherId = undefined;
+    }
+    await ctx.db.patch(legacyUser._id, userPatch);
+    nextLegacyUser = {
+      ...legacyUser,
+      ...userPatch,
+    };
+  }
+
+  let orgPublisherId: Id<"publishers">;
+  let convertedExistingPublisher = false;
+  if (handlePublisher?.kind === "org") {
+    orgPublisherId = handlePublisher._id;
+    if (args.displayName?.trim() && handlePublisher.displayName !== args.displayName.trim()) {
+      await ctx.db.patch(handlePublisher._id, {
+        displayName: args.displayName.trim(),
+        updatedAt: now,
+      });
+    }
+  } else if (convertiblePublisher) {
+    orgPublisherId = convertiblePublisher._id;
+    convertedExistingPublisher = true;
+    await ctx.db.patch(convertiblePublisher._id, {
+      kind: "org",
+      handle: orgHandle,
+      displayName: args.displayName?.trim() || convertiblePublisher.displayName,
+      linkedUserId: undefined,
+      trustedPublisher: convertiblePublisher.trustedPublisher ?? legacyUser.trustedPublisher,
+      updatedAt: now,
+    });
+  } else {
+    orgPublisherId = await ctx.db.insert("publishers", {
+      kind: "org",
+      handle: orgHandle,
+      displayName: args.displayName?.trim() || legacyUser.displayName?.trim() || orgHandle,
+      bio: undefined,
+      image: undefined,
+      linkedUserId: undefined,
+      trustedPublisher: legacyUser.trustedPublisher,
+      createdAt: now,
+      updatedAt: now,
+    });
+  }
+
+  const membership = await getPublisherMembership(ctx, orgPublisherId, legacyUser._id);
+  if (membership) {
+    if (membership.role !== "owner") {
+      await ctx.db.patch(membership._id, { role: "owner", updatedAt: now });
+    }
+  } else {
+    await ctx.db.insert("publisherMembers", {
+      publisherId: orgPublisherId,
+      userId: legacyUser._id,
+      role: "owner",
+      createdAt: now,
+      updatedAt: now,
+    });
+  }
+
+  const ensuredPersonalPublisher = await ensurePersonalPublisherForUser(ctx, nextLegacyUser);
+
+  const packages = await ctx.db
+    .query("packages")
+    .withIndex("by_owner", (q) => q.eq("ownerUserId", legacyUser._id))
+    .collect();
+  let packagesMigrated = 0;
+  for (const pkg of packages) {
+    if (pkg.ownerPublisherId === orgPublisherId) continue;
+    await ctx.db.patch(pkg._id, {
+      ownerPublisherId: orgPublisherId,
+      updatedAt: now,
+    });
+    packagesMigrated += 1;
+  }
+
+  await ctx.db.insert("auditLogs", {
+    actorUserId: args.actorUserId,
+    action: "publisher.legacy_handle.migrate",
+    targetType: "publisher",
+    targetId: orgPublisherId,
+    metadata: {
+      handle: orgHandle,
+      legacyUserId: legacyUser._id,
+      fallbackUserHandle: nextLegacyUser.handle ?? fallbackHandle,
+      convertedExistingPublisher,
+      packagesMigrated,
+      personalPublisherId: ensuredPersonalPublisher?._id ?? null,
+    },
+    createdAt: now,
+  });
+
+  return {
+    ok: true as const,
+    handle: orgHandle,
+    orgPublisherId,
+    legacyUserId: legacyUser._id,
+    fallbackUserHandle: nextLegacyUser.handle ?? fallbackHandle,
+    personalPublisherId: ensuredPersonalPublisher?._id ?? null,
+    convertedExistingPublisher,
+    packagesMigrated,
+  };
+}
+
+async function ensureOrgPublisherHandleWithActor(
+  ctx: Pick<MutationCtx, "db">,
+  args: {
+    actorUserId: Id<"users">;
+    handle: string;
+    fallbackUserHandle?: string;
+    displayName?: string;
+    trusted?: boolean;
+  },
+) {
+  const actor = await ctx.db.get(args.actorUserId);
+  if (!actor || actor.deletedAt || actor.deactivatedAt) throw new ConvexError("Unauthorized");
+  assertAdmin(actor);
+
+  const handle = validateHandle(args.handle);
+  const now = Date.now();
+  const existingPublisher = await getPublisherByHandle(ctx, handle);
+  const existingUser = await getUserByHandle(ctx, handle);
+
+  if (existingPublisher?.kind === "org") {
+    await ctx.db.patch(existingPublisher._id, {
+      displayName: args.displayName?.trim() || existingPublisher.displayName,
+      trustedPublisher: args.trusted ?? existingPublisher.trustedPublisher,
+      updatedAt: now,
+    });
+    const membership = await getPublisherMembership(ctx, existingPublisher._id, args.actorUserId);
+    if (!membership) {
+      await ctx.db.insert("publisherMembers", {
+        publisherId: existingPublisher._id,
+        userId: args.actorUserId,
+        role: "owner",
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+    return {
+      ok: true as const,
+      publisherId: existingPublisher._id,
+      handle,
+      created: false,
+      migrated: false,
+      trusted: args.trusted ?? existingPublisher.trustedPublisher ?? false,
+    };
+  }
+
+  if (existingPublisher || existingUser) {
+    const result = await migrateLegacyPublisherHandleToOrgWithActor(ctx, {
+      actorUserId: args.actorUserId,
+      handle,
+      fallbackUserHandle: args.fallbackUserHandle,
+      displayName: args.displayName,
+    });
+    if (typeof args.trusted === "boolean") {
+      await ctx.db.patch(result.orgPublisherId, {
+        trustedPublisher: args.trusted,
+        updatedAt: now,
+      });
+    }
+    return {
+      ok: true as const,
+      publisherId: result.orgPublisherId,
+      handle,
+      created: false,
+      migrated: true,
+      trusted: args.trusted ?? existingPublisher?.trustedPublisher ?? false,
+    };
+  }
+
+  const publisherId = await ctx.db.insert("publishers", {
+    kind: "org",
+    handle,
+    displayName: args.displayName?.trim() || handle,
+    bio: undefined,
+    image: undefined,
+    linkedUserId: undefined,
+    trustedPublisher: args.trusted || undefined,
+    createdAt: now,
+    updatedAt: now,
+  });
+  await ctx.db.insert("publisherMembers", {
+    publisherId,
+    userId: args.actorUserId,
+    role: "owner",
+    createdAt: now,
+    updatedAt: now,
+  });
+  await ctx.db.insert("auditLogs", {
+    actorUserId: args.actorUserId,
+    action: "publisher.org.ensure",
+    targetType: "publisher",
+    targetId: publisherId,
+    metadata: {
+      handle,
+      trusted: args.trusted === true,
+    },
+    createdAt: now,
+  });
+  return {
+    ok: true as const,
+    publisherId,
+    handle,
+    created: true,
+    migrated: false,
+    trusted: args.trusted ?? false,
+  };
+}
+
+export const getByIdInternal = internalQuery({
+  args: { publisherId: v.id("publishers") },
+  handler: async (ctx, args) => await ctx.db.get(args.publisherId),
+});
+
+export const getByHandleInternal = internalQuery({
+  args: { handle: v.string() },
+  handler: async (ctx, args) => await getPublisherByHandle(ctx, args.handle),
+});
+
+export const getMemberRoleInternal = internalQuery({
+  args: {
+    publisherId: v.id("publishers"),
+    userId: v.id("users"),
+  },
+  handler: async (ctx, args) =>
+    (await getPublisherMembership(ctx, args.publisherId, args.userId))?.role ?? null,
+});
+
+export const ensurePersonalPublisherInternal = internalMutation({
+  args: { userId: v.id("users") },
+  handler: async (ctx, args) => {
+    const user = await ctx.db.get(args.userId);
+    if (!user || user.deletedAt || user.deactivatedAt) return null;
+    return await ensurePersonalPublisherForUser(ctx, user);
+  },
+});
+
+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")),
+    ),
+  },
+  handler: async (ctx, args) => {
+    const actor = await ctx.db.get(args.actorUserId);
+    if (!actor || actor.deletedAt || actor.deactivatedAt) throw new ConvexError("Unauthorized");
+    const minimumRole = args.minimumRole ?? "publisher";
+    const requestedHandle = normalizePublisherHandle(args.ownerHandle);
+    const personal = await ensurePersonalPublisherForUser(ctx, actor);
+    if (!personal) throw new ConvexError("Personal publisher not found");
+    if (!requestedHandle) {
+      return {
+        publisherId: personal._id,
+        handle: personal.handle,
+        kind: personal.kind,
+        linkedUserId: personal.linkedUserId,
+      };
+    }
+
+    if (personal && requestedHandle === personal.handle) {
+      return {
+        publisherId: personal._id,
+        handle: personal.handle,
+        kind: personal.kind,
+        linkedUserId: personal.linkedUserId,
+      };
+    }
+
+    const publisher = await getPublisherByHandle(ctx, requestedHandle);
+    if (!publisher || publisher.deletedAt || publisher.deactivatedAt) {
+      throw new ConvexError(`Publisher "@${requestedHandle}" not found`);
+    }
+    const membership = await getPublisherMembership(ctx, publisher._id, actor._id);
+    if (!membership || !isPublisherRoleAllowed(membership.role, [minimumRole])) {
+      throw new ConvexError(`Forbidden for "@${requestedHandle}"`);
+    }
+    return {
+      publisherId: publisher._id,
+      handle: publisher.handle,
+      kind: publisher.kind,
+      linkedUserId: publisher.linkedUserId,
+    };
+  },
+});
+
+export const listMine = query({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) return [];
+    const user = await ctx.db.get(userId);
+    if (!user || user.deletedAt || user.deactivatedAt) return [];
+    const memberships = await ctx.db
+      .query("publisherMembers")
+      .withIndex("by_user", (q) => q.eq("userId", userId))
+      .collect();
+    const publishers = await Promise.all(
+      memberships.map(async (membership) => {
+        const publisher = await ctx.db.get(membership.publisherId);
+        const publicPublisher = toPublicPublisher(publisher);
+        if (!publicPublisher) return null;
+        return {
+          publisher: publicPublisher,
+          role: membership.role,
+        };
+      }),
+    );
+    const visiblePublishers = publishers.filter(
+      (
+        item,
+      ): item is {
+        publisher: NonNullable<ReturnType<typeof toPublicPublisher>>;
+        role: Doc<"publisherMembers">["role"];
+      } => Boolean(item),
+    );
+    const personalPublisher = toPublicPublisher(
+      await getPersonalPublisherForUserOrFallback(ctx, user),
+    );
+    if (
+      personalPublisher &&
+      !visiblePublishers.some((entry) => entry.publisher._id === personalPublisher._id)
+    ) {
+      visiblePublishers.unshift({
+        publisher: personalPublisher,
+        role: "owner",
+      });
+    }
+    return visiblePublishers;
+  },
+});
+
+export const getByHandle = query({
+  args: { handle: v.string() },
+  handler: async (ctx, args) => toPublicPublisher(await getPublisherByHandle(ctx, args.handle)),
+});
+
+export const listMembers = query({
+  args: { publisherHandle: v.string() },
+  handler: async (ctx, args) => {
+    const publisher = await getPublisherByHandle(ctx, args.publisherHandle);
+    if (!publisher || publisher.deletedAt || publisher.deactivatedAt) return null;
+    const memberships = await ctx.db
+      .query("publisherMembers")
+      .withIndex("by_publisher", (q) => q.eq("publisherId", publisher._id))
+      .collect();
+    const items = await Promise.all(
+      memberships.map(async (membership) => {
+        const user = await ctx.db.get(membership.userId);
+        if (!user || user.deletedAt || user.deactivatedAt) return null;
+        return {
+          role: membership.role,
+          user: {
+            _id: user._id,
+            handle: user.handle ?? null,
+            displayName: user.displayName ?? user.name ?? null,
+            image: user.image ?? null,
+          },
+        };
+      }),
+    );
+    return {
+      publisher: toPublicPublisher(publisher),
+      members: items.filter(Boolean),
+    };
+  },
+});
+
+export const createOrg = mutation({
+  args: {
+    handle: v.string(),
+    displayName: v.string(),
+    bio: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const { user, userId } = await requireUser(ctx);
+    await ensurePersonalPublisherForUser(ctx, user);
+
+    const handle = validateHandle(args.handle);
+    const existingPublisher = await getPublisherByHandle(ctx, handle);
+    if (existingPublisher) throw new ConvexError(`Publisher "@${handle}" already exists`);
+
+    const existingUser = await ctx.db
+      .query("users")
+      .withIndex("handle", (q) => q.eq("handle", handle))
+      .unique();
+    if (existingUser && existingUser._id !== userId) {
+      throw new ConvexError(`Handle "@${handle}" is already claimed`);
+    }
+
+    const now = Date.now();
+    const publisherId = await ctx.db.insert("publishers", {
+      kind: "org",
+      handle,
+      displayName: args.displayName.trim() || handle,
+      bio: args.bio?.trim() || undefined,
+      image: undefined,
+      linkedUserId: undefined,
+      trustedPublisher: false,
+      createdAt: now,
+      updatedAt: now,
+    });
+    await ctx.db.insert("publisherMembers", {
+      publisherId,
+      userId,
+      role: "owner",
+      createdAt: now,
+      updatedAt: now,
+    });
+    await ctx.db.insert("auditLogs", {
+      actorUserId: userId,
+      action: "publisher.create",
+      targetType: "publisher",
+      targetId: publisherId,
+      metadata: { kind: "org", handle },
+      createdAt: now,
+    });
+    return {
+      publisher: toPublicPublisher(await ctx.db.get(publisherId)),
+      role: "owner" as const,
+    };
+  },
+});
+
+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(),
+    fallbackUserHandle: v.optional(v.string()),
+    displayName: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const { userId } = await requireUser(ctx);
+    return await migrateLegacyPublisherHandleToOrgWithActor(ctx, {
+      actorUserId: userId,
+      ...args,
+    });
+  },
+});
+
+export const ensureOrgPublisherHandleInternal = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    handle: v.string(),
+    fallbackUserHandle: v.optional(v.string()),
+    displayName: v.optional(v.string()),
+    trusted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => await ensureOrgPublisherHandleWithActor(ctx, args),
+});
+
+export const addMember = mutation({
+  args: {
+    publisherId: v.id("publishers"),
+    userHandle: v.string(),
+    role: v.union(v.literal("owner"), v.literal("admin"), v.literal("publisher")),
+  },
+  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");
+    }
+    const membership = await getPublisherMembership(ctx, publisher._id, userId);
+    if (!membership || !isPublisherRoleAllowed(membership.role, ["admin"])) {
+      throw new ConvexError("Forbidden");
+    }
+    if (args.role === "owner" && membership.role !== "owner") {
+      throw new ConvexError("Only org owners can promote members to owner");
+    }
+    const handle = normalizePublisherHandle(args.userHandle);
+    if (!handle) throw new ConvexError("User handle is required");
+    const targetUser = await getActiveUserByHandleOrPersonalPublisher(ctx, handle);
+    if (!targetUser) {
+      throw new ConvexError(`User "@${handle}" not found`);
+    }
+    await ensurePersonalPublisherForUser(ctx, targetUser);
+    const existing = await getPublisherMembership(ctx, publisher._id, targetUser._id);
+    const now = Date.now();
+    if (existing) {
+      await ctx.db.patch(existing._id, { role: args.role, updatedAt: now });
+    } else {
+      await ctx.db.insert("publisherMembers", {
+        publisherId: publisher._id,
+        userId: targetUser._id,
+        role: args.role,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+    await ctx.db.insert("auditLogs", {
+      actorUserId: userId,
+      action: "publisher.member.upsert",
+      targetType: "publisher",
+      targetId: publisher._id,
+      metadata: {
+        memberUserId: targetUser._id,
+        memberHandle: targetUser.handle ?? handle,
+        role: args.role,
+      },
+      createdAt: now,
+    });
+    return { ok: true };
+  },
+});
+
+export const removeMember = mutation({
+  args: {
+    publisherId: v.id("publishers"),
+    userId: v.id("users"),
+  },
+  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");
+    }
+    const actorMembership = await getPublisherMembership(ctx, publisher._id, userId);
+    if (!actorMembership || !isPublisherRoleAllowed(actorMembership.role, ["admin"])) {
+      throw new ConvexError("Forbidden");
+    }
+    const targetMembership = await getPublisherMembership(ctx, publisher._id, args.userId);
+    if (!targetMembership) return { ok: true };
+    if (targetMembership.role === "owner" && actorMembership.role !== "owner") {
+      throw new ConvexError("Only org owners can remove other owners");
+    }
+    if (targetMembership.role === "owner") {
+      const members = await ctx.db
+        .query("publisherMembers")
+        .withIndex("by_publisher", (q) => q.eq("publisherId", publisher._id))
+        .collect();
+      const remainingOwners = members.filter(
+        (member) => member.role === "owner" && member.userId !== args.userId,
+      );
+      if (remainingOwners.length === 0) {
+        throw new ConvexError("Publisher must have at least one owner");
+      }
+    }
+    await ctx.db.delete(targetMembership._id);
+    await ctx.db.insert("auditLogs", {
+      actorUserId: userId,
+      action: "publisher.member.remove",
+      targetType: "publisher",
+      targetId: publisher._id,
+      metadata: { memberUserId: args.userId },
+      createdAt: Date.now(),
+    });
+    return { ok: true };
+  },
+});
+
+export const setTrustedPublisherInternal = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    publisherId: v.id("publishers"),
+    trustedPublisher: v.boolean(),
+  },
+  handler: async (ctx, args) => {
+    const actor = await ctx.db.get(args.actorUserId);
+    if (!actor || actor.deletedAt || actor.deactivatedAt) throw new ConvexError("Unauthorized");
+    assertAdmin(actor);
+    await ctx.db.patch(args.publisherId, {
+      trustedPublisher: args.trustedPublisher,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const migrateLegacyPublisherHandleToOrgInternal = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    handle: v.string(),
+    fallbackUserHandle: v.optional(v.string()),
+    displayName: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => await migrateLegacyPublisherHandleToOrgWithActor(ctx, args),
+});
@@ -28,6 +28,10 @@ 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()),
  deactivatedAt: v.optional(v.number()),
@@ -39,7 +43,36 @@ 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")),
+  handle: v.string(),
+  displayName: v.string(),
+  bio: v.optional(v.string()),
+  image: v.optional(v.string()),
+  linkedUserId: v.optional(v.id("users")),
+  trustedPublisher: v.optional(v.boolean()),
+  deactivatedAt: v.optional(v.number()),
+  deletedAt: v.optional(v.number()),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+})
+  .index("by_handle", ["handle"])
+  .index("by_linked_user", ["linkedUserId"])
+  .index("by_kind_handle", ["kind", "handle"]);
+
+const publisherMembers = defineTable({
+  publisherId: v.id("publishers"),
+  userId: v.id("users"),
+  role: v.union(v.literal("owner"), v.literal("admin"), v.literal("publisher")),
+  createdAt: v.number(),
+  updatedAt: v.number(),
+})
+  .index("by_publisher", ["publisherId"])
+  .index("by_user", ["userId"])
+  .index("by_publisher_user", ["publisherId", "userId"]);

 // Shared validator fragments used by both `skills` and `skillSearchDigest`.
 const forkOfValidator = v.optional(
@@ -62,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(),
@@ -159,6 +204,33 @@ 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"),
+    v.literal("suspicious"),
+    v.literal("malicious"),
+    v.literal("pending"),
+    v.literal("not-run"),
+  ),
+);
+
 const packageFilesValidator = v.array(
  v.object({
    path: v.string(),
@@ -175,6 +247,7 @@ const skills = defineTable({
  summary: v.optional(v.string()),
  resourceId: v.optional(v.string()),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  canonicalSkillId: v.optional(v.id("skills")),
  forkOf: forkOfValidator,
  latestVersionId: v.optional(v.id("skillVersions")),
@@ -188,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,
@@ -255,6 +329,7 @@ const skills = defineTable({
 })
  .index("by_slug", ["slug"])
  .index("by_owner", ["ownerUserId"])
+  .index("by_owner_publisher", ["ownerPublisherId"])
  .index("by_updated", ["updatedAt"])
  .index("by_stats_downloads", ["statsDownloads", "updatedAt"])
  .index("by_stats_stars", ["statsStars", "updatedAt"])
@@ -295,18 +370,21 @@ const skillSlugAliases = defineTable({
  slug: v.string(),
  skillId: v.id("skills"),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  createdAt: v.number(),
  updatedAt: v.number(),
 })
  .index("by_slug", ["slug"])
  .index("by_skill", ["skillId"])
-  .index("by_owner", ["ownerUserId"]);
+  .index("by_owner", ["ownerUserId"])
+  .index("by_owner_publisher", ["ownerPublisherId"]);

 const souls = defineTable({
  slug: v.string(),
  displayName: v.string(),
  summary: v.optional(v.string()),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  latestVersionId: v.optional(v.id("soulVersions")),
  tags: v.record(v.string(), v.id("soulVersions")),
  softDeletedAt: v.optional(v.number()),
@@ -321,7 +399,9 @@ const souls = defineTable({
 })
  .index("by_slug", ["slug"])
  .index("by_owner", ["ownerUserId"])
-  .index("by_updated", ["updatedAt"]);
+  .index("by_owner_publisher", ["ownerPublisherId"])
+  .index("by_updated", ["updatedAt"])
+  .index("by_active_updated", ["softDeletedAt", "updatedAt"]);

 const skillVersions = defineTable({
  skillId: v.id("skills"),
@@ -380,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")),
@@ -471,6 +552,7 @@ const skillEmbeddings = defineTable({
  skillId: v.id("skills"),
  versionId: v.id("skillVersions"),
  ownerId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  embedding: v.array(v.number()),
  isLatest: v.boolean(),
  isApproved: v.boolean(),
@@ -501,7 +583,9 @@ const skillSearchDigest = defineTable({
  displayName: v.string(),
  summary: v.optional(v.string()),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  ownerHandle: v.optional(v.string()),
+  ownerKind: v.optional(v.union(v.literal("user"), v.literal("org"))),
  ownerName: v.optional(v.string()),
  ownerDisplayName: v.optional(v.string()),
  ownerImage: v.optional(v.string()),
@@ -518,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()),
@@ -566,6 +651,7 @@ const packages = defineTable({
  displayName: v.string(),
  summary: v.optional(v.string()),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  family: packageFamilyValidator,
  channel: packageChannelValidator,
  isOfficial: v.boolean(),
@@ -588,6 +674,7 @@ const packages = defineTable({
  compatibility: packageCompatibilityValidator,
  capabilities: packageCapabilitiesValidator,
  verification: packageVerificationValidator,
+  scanStatus: packageScanStatusValidator,
  stats: packageStatsValidator,
  softDeletedAt: v.optional(v.number()),
  createdAt: v.number(),
@@ -595,6 +682,7 @@ const packages = defineTable({
 })
  .index("by_name", ["normalizedName"])
  .index("by_owner", ["ownerUserId"])
+  .index("by_owner_publisher", ["ownerPublisherId"])
  .index("by_family_updated", ["family", "updatedAt"])
  .index("by_family_channel_updated", ["family", "channel", "updatedAt"])
  .index("by_family_official_updated", ["family", "isOfficial", "updatedAt"])
@@ -615,14 +703,111 @@ const packageReleases = defineTable({
  compatibility: packageCompatibilityValidator,
  capabilities: packageCapabilitiesValidator,
  verification: packageVerificationValidator,
+  sha256hash: v.optional(v.string()),
+  vtAnalysis: v.optional(
+    v.object({
+      status: v.string(),
+      verdict: v.optional(v.string()),
+      analysis: v.optional(v.string()),
+      source: v.optional(v.string()),
+      checkedAt: v.number(),
+    }),
+  ),
+  llmAnalysis: v.optional(
+    v.object({
+      status: v.string(),
+      verdict: v.optional(v.string()),
+      confidence: v.optional(v.string()),
+      summary: v.optional(v.string()),
+      dimensions: v.optional(
+        v.array(
+          v.object({
+            name: v.string(),
+            label: v.string(),
+            rating: v.string(),
+            detail: v.string(),
+          }),
+        ),
+      ),
+      guidance: v.optional(v.string()),
+      findings: v.optional(v.string()),
+      model: v.optional(v.string()),
+      checkedAt: v.number(),
+    }),
+  ),
+  staticScan: v.optional(
+    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(),
+    }),
+  ),
  source: v.optional(v.any()),
  createdBy: v.id("users"),
+  publishActor: packagePublishActorValidator,
  createdAt: v.number(),
  softDeletedAt: v.optional(v.number()),
 })
  .index("by_package", ["packageId"])
  .index("by_package_active_created", ["packageId", "softDeletedAt", "createdAt"])
-  .index("by_package_version", ["packageId", "version"]);
+  .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"),
@@ -633,13 +818,16 @@ const packageSearchDigest = defineTable({
  channel: packageChannelValidator,
  isOfficial: v.boolean(),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  ownerHandle: v.optional(v.string()),
+  ownerKind: v.optional(v.union(v.literal("user"), v.literal("org"))),
  summary: v.optional(v.string()),
  latestVersion: v.optional(v.string()),
  runtimeId: v.optional(v.string()),
  capabilityTags: v.optional(v.array(v.string())),
  executesCode: v.optional(v.boolean()),
  verificationTier: v.optional(packageVerificationTierValidator),
+  scanStatus: packageScanStatusValidator,
  softDeletedAt: v.optional(v.number()),
  createdAt: v.number(),
  updatedAt: v.number(),
@@ -702,6 +890,8 @@ const packageSearchDigest = defineTable({
    "executesCode",
    "updatedAt",
  ])
+  .index("by_active_normalized_name", ["softDeletedAt", "normalizedName", "updatedAt"])
+  .index("by_active_runtime_id", ["softDeletedAt", "runtimeId", "updatedAt"])
  .index("by_active_name", ["softDeletedAt", "displayName"]);

 const packageCapabilitySearchDigest = defineTable({
@@ -713,7 +903,9 @@ const packageCapabilitySearchDigest = defineTable({
  channel: packageChannelValidator,
  isOfficial: v.boolean(),
  ownerUserId: v.id("users"),
+  ownerPublisherId: v.optional(v.id("publishers")),
  ownerHandle: v.optional(v.string()),
+  ownerKind: v.optional(v.union(v.literal("user"), v.literal("org"))),
  summary: v.optional(v.string()),
  latestVersion: v.optional(v.string()),
  runtimeId: v.optional(v.string()),
@@ -721,6 +913,7 @@ const packageCapabilitySearchDigest = defineTable({
  capabilityTag: v.string(),
  executesCode: v.optional(v.boolean()),
  verificationTier: v.optional(packageVerificationTierValidator),
+  scanStatus: packageScanStatusValidator,
  softDeletedAt: v.optional(v.number()),
  createdAt: v.number(),
  updatedAt: v.number(),
@@ -733,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",
@@ -1138,10 +1326,14 @@ const skillOwnershipTransfers = defineTable({
 export default defineSchema({
  ...authTables,
  users,
+  publishers,
+  publisherMembers,
  skills,
  skillSlugAliases,
  packages,
  packageReleases,
+  packageTrustedPublishers,
+  packagePublishTokens,
  packageSearchDigest,
  packageCapabilitySearchDigest,
  souls,
@@ -46,8 +46,8 @@ describe("search helpers", () => {
        owner: null,
      },
    ];
-    // With incremental hydration, empty vector results skip the hydrate call entirely.
-    const runQuery = vi.fn().mockResolvedValueOnce(fallback); // lexicalFallbackSkills (only call)
+    // Slug-like queries now do an indexed exact-slug lookup before lexical fallback.
+    const runQuery = vi.fn().mockResolvedValueOnce(null).mockResolvedValueOnce(fallback);

    const result = await searchSkillsHandler(
      {
@@ -183,6 +183,7 @@ describe("search helpers", () => {

    const runQuery = vi
      .fn()
+      .mockResolvedValueOnce(null) // getExactSkillSlugMatch
      .mockResolvedValueOnce(vectorEntries) // hydrateResults
      .mockResolvedValueOnce(fallbackEntries); // lexicalFallbackSkills

@@ -204,6 +205,289 @@ describe("search helpers", () => {
    );
  });

+  it("always includes an exact slug match even when vector exact matches already fill the limit", async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);
+
+    const vectorEntries = Array.from({ length: 10 }, (_, index) => ({
+      embeddingId: `skillEmbeddings:${index}`,
+      skill: makePublicSkill({
+        id: `skills:${index}`,
+        slug: `downloader-${index}`,
+        displayName: `Downloader ${index}`,
+        downloads: 100 - index,
+      }),
+      version: null,
+      ownerHandle: "owner",
+      owner: null,
+    }));
+
+    const exactSlugEntry = {
+      skill: makePublicSkill({
+        id: "skills:exact",
+        slug: "skill-downloader",
+        displayName: "Skill Downloader",
+        downloads: 1,
+      }),
+      version: null,
+      ownerHandle: "yyang100",
+      owner: null,
+    };
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(exactSlugEntry)
+      .mockResolvedValueOnce(vectorEntries);
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi
+          .fn()
+          .mockResolvedValue(
+            vectorEntries.map((entry, index) => ({
+              _id: entry.embeddingId,
+              _score: 0.9 - index * 0.01,
+            })),
+          ),
+        runQuery,
+      },
+      { query: "skill-downloader", limit: 10 },
+    );
+
+    expect(result).toHaveLength(10);
+    expect(result[0].skill.slug).toBe("skill-downloader");
+    expect(runQuery).toHaveBeenCalledTimes(2);
+  });
+
+  it("omits exact slug injection when nonSuspiciousOnly excludes it", async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);
+
+    const vectorEntries = [
+      {
+        embeddingId: "skillEmbeddings:1",
+        skill: makePublicSkill({
+          id: "skills:1",
+          slug: "downloader-1",
+          displayName: "Downloader 1",
+          downloads: 50,
+        }),
+        version: null,
+        ownerHandle: "owner",
+        owner: null,
+      },
+    ];
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(vectorEntries)
+      .mockResolvedValueOnce([]);
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([{ _id: "skillEmbeddings:1", _score: 0.9 }]),
+        runQuery,
+      },
+      { query: "skill-downloader", limit: 10, nonSuspiciousOnly: true },
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0].skill.slug).toBe("downloader-1");
+  });
+
+  it("omits exact slug injection when highlightedOnly excludes it", async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);
+
+    const exactSlugEntry = {
+      skill: makePublicSkill({
+        id: "skills:exact",
+        slug: "skill-downloader",
+        displayName: "Skill Downloader",
+        downloads: 1,
+      }),
+      version: null,
+      ownerHandle: "yyang100",
+      owner: null,
+    };
+
+    const vectorEntries = [
+      {
+        embeddingId: "skillEmbeddings:1",
+        skill: {
+          ...makePublicSkill({
+            id: "skills:1",
+            slug: "downloader-1",
+            displayName: "Downloader 1",
+            downloads: 50,
+          }),
+          badges: { highlighted: { byUserId: "users:mod", at: 1 } },
+        },
+        version: null,
+        ownerHandle: "owner",
+        owner: null,
+      },
+    ];
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(exactSlugEntry)
+      .mockResolvedValueOnce(vectorEntries)
+      .mockResolvedValueOnce([]);
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([{ _id: "skillEmbeddings:1", _score: 0.9 }]),
+        runQuery,
+      },
+      { query: "skill-downloader", limit: 10, highlightedOnly: true },
+    );
+
+    expect(result).toHaveLength(1);
+    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]);
+
+    const sharedSkill = makePublicSkill({
+      id: "skills:exact",
+      slug: "skill-downloader",
+      displayName: "Skill Downloader",
+      downloads: 100,
+    });
+    const exactSlugEntry = {
+      skill: sharedSkill,
+      version: null,
+      ownerHandle: "yyang100",
+      owner: null,
+    };
+    const vectorEntries = [
+      {
+        embeddingId: "skillEmbeddings:exact",
+        skill: sharedSkill,
+        version: null,
+        ownerHandle: "yyang100",
+        owner: null,
+      },
+      {
+        embeddingId: "skillEmbeddings:other",
+        skill: makePublicSkill({
+          id: "skills:other",
+          slug: "downloader-2",
+          displayName: "Downloader 2",
+          downloads: 50,
+        }),
+        version: null,
+        ownerHandle: "owner",
+        owner: null,
+      },
+    ];
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(exactSlugEntry)
+      .mockResolvedValueOnce(vectorEntries)
+      .mockResolvedValueOnce([]);
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([
+          { _id: "skillEmbeddings:exact", _score: 0.95 },
+          { _id: "skillEmbeddings:other", _score: 0.8 },
+        ]),
+        runQuery,
+      },
+      { query: "skill-downloader", limit: 10 },
+    );
+
+    expect(result).toHaveLength(2);
+    expect(result.filter((entry) => entry.skill._id === "skills:exact")).toHaveLength(1);
+  });
+
+  it("skips duplicate slug lookup inside lexical fallback when search action already did it", async () => {
+    generateEmbeddingMock.mockResolvedValueOnce([0, 1, 2]);
+
+    const fallbackEntries = [
+      {
+        skill: makePublicSkill({
+          id: "skills:orf",
+          slug: "orf",
+          displayName: "ORF",
+        }),
+        version: null,
+        ownerHandle: "steipete",
+        owner: null,
+      },
+    ];
+
+    const runQuery = vi
+      .fn()
+      .mockResolvedValueOnce(null)
+      .mockImplementationOnce(async (_ref: unknown, args: { skipExactSlugLookup?: boolean }) => {
+        expect(args.skipExactSlugLookup).toBe(true);
+        return fallbackEntries;
+      });
+
+    const result = await searchSkillsHandler(
+      {
+        vectorSearch: vi.fn().mockResolvedValue([]),
+        runQuery,
+      },
+      { query: "orf", limit: 10 },
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0].skill.slug).toBe("orf");
+  });
+
  it("filters suspicious vector results in hydrateResults when requested", async () => {
    const result = await hydrateResultsHandler(
      {
@@ -525,7 +809,10 @@ describe("search helpers", () => {

    const hydrateCalls: string[][] = [];
    const runQuery = vi.fn(
-      async (_ref: unknown, args: { embeddingIds?: string[]; query?: string }) => {
+      async (_ref: unknown, args: { embeddingIds?: string[]; query?: string; slug?: string }) => {
+        if (args.slug) {
+          return null; // getExactSkillSlugMatch
+        }
        if (args.embeddingIds) {
          hydrateCalls.push(args.embeddingIds);
          return args.embeddingIds.map((embeddingId: string) => ({
@@ -586,6 +873,7 @@ function makePublicSkill(params: {
  slug: string;
  displayName: string;
  downloads?: number;
+  capabilityTags?: string[];
 }) {
  return {
    _id: params.id,
@@ -598,6 +886,7 @@ function makePublicSkill(params: {
    forkOf: undefined,
    latestVersionId: "skillVersions:1",
    tags: {},
+    capabilityTags: params.capabilityTags,
    badges: {},
    stats: {
      downloads: params.downloads ?? 0,
@@ -5,27 +5,33 @@ import type { QueryCtx } from "./_generated/server";
 import { action, internalQuery } from "./functions";
 import { isSkillHighlighted } from "./lib/badges";
 import { generateEmbedding } from "./lib/embeddings";
-import type { HydratableSkill } from "./lib/public";
-import { toPublicSkill, toPublicSoul, toPublicUser } from "./lib/public";
+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";
 import { digestToHydratableSkill, digestToOwnerInfo } from "./lib/skillSearchDigest";

-type OwnerInfo = { ownerHandle: string | null; owner: ReturnType<typeof toPublicUser> | null };
+type OwnerInfo = { ownerHandle: string | null; owner: PublicPublisher | null };

 function makeOwnerInfoGetter(ctx: Pick<QueryCtx, "db">) {
-  const ownerCache = new Map<Id<"users">, Promise<OwnerInfo>>();
-  return (ownerUserId: Id<"users">) => {
-    const cached = ownerCache.get(ownerUserId);
+  const ownerCache = new Map<string, Promise<OwnerInfo>>();
+  return (ownerUserId: Id<"users">, ownerPublisherId?: Id<"publishers"> | null) => {
+    const cacheKey = String(ownerPublisherId ?? ownerUserId);
+    const cached = ownerCache.get(cacheKey);
    if (cached) return cached;
-    const ownerPromise = ctx.db.get(ownerUserId).then((ownerDoc) => {
-      const owner = toPublicUser(ownerDoc);
+    const ownerPromise = getOwnerPublisher(ctx, {
+      ownerPublisherId,
+      ownerUserId,
+    }).then((ownerDoc) => {
+      const owner = toPublicPublisher(ownerDoc);
      return {
-        ownerHandle: owner?.handle ?? owner?.name ?? null,
+        ownerHandle: owner?.handle ?? null,
        owner,
      };
    });
-    ownerCache.set(ownerUserId, ownerPromise);
+    ownerCache.set(cacheKey, ownerPromise);
    return ownerPromise;
  };
 }
@@ -35,7 +41,7 @@ type SkillSearchEntry = {
  skill: NonNullable<ReturnType<typeof toPublicSkill>>;
  version: Doc<"skillVersions"> | null;
  ownerHandle: string | null;
-  owner: ReturnType<typeof toPublicUser> | null;
+  owner: PublicPublisher | null;
 };

 type SearchResult = SkillSearchEntry & { score: number };
@@ -46,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);
@@ -111,18 +118,44 @@ function mergeUniqueBySkillId(primary: SkillSearchEntry[], fallback: SkillSearch
  return out;
 }

+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 exactSlugMatch =
+      rawExactSlugMatch &&
+      (!args.highlightedOnly || isSkillHighlighted(rawExactSlugMatch.skill)) &&
+      matchesCapabilityTag(rawExactSlugMatch.skill, args.capabilityTag)
+        ? rawExactSlugMatch
+        : null;
    let vector: number[];
    try {
      vector = await generateEmbedding(query);
@@ -166,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, [
@@ -187,8 +222,12 @@ export const searchSkills: ReturnType<typeof action> = action({
      candidateLimit = nextLimit;
    }

+    const primaryMatches = exactSlugMatch
+      ? mergeUniqueBySkillId([exactSlugMatch], exactMatches)
+      : exactMatches;
+
    const fallbackMatches =
-      exactMatches.length >= limit
+      primaryMatches.length >= limit
        ? []
        : ((await ctx.runQuery(internal.search.lexicalFallbackSkills, {
            query,
@@ -196,9 +235,10 @@ 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(exactMatches, fallbackMatches);
+    const mergedMatches = mergeUniqueBySkillId(primaryMatches, fallbackMatches);

    return mergedMatches
      .map((entry) => {
@@ -220,6 +260,33 @@ export const searchSkills: ReturnType<typeof action> = action({
  },
 });

+export const getExactSkillSlugMatch = internalQuery({
+  args: {
+    slug: v.string(),
+    nonSuspiciousOnly: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args): Promise<SkillSearchEntry | null> => {
+    const skill = await ctx.db
+      .query("skills")
+      .withIndex("by_slug", (q) => q.eq("slug", args.slug))
+      .unique();
+    if (!skill || skill.softDeletedAt) return null;
+    if (args.nonSuspiciousOnly && isSkillSuspicious(skill)) return null;
+
+    const getOwnerInfo = makeOwnerInfoGetter(ctx);
+    const resolved = await getOwnerInfo(skill.ownerUserId, skill.ownerPublisherId);
+    const publicSkill = toPublicSkill(skill);
+    if (!publicSkill || !resolved.owner) return null;
+
+    return {
+      skill: publicSkill,
+      version: null,
+      ownerHandle: resolved.ownerHandle,
+      owner: resolved.owner,
+    };
+  },
+});
+
 export const hydrateResults = internalQuery({
  args: {
    embeddingIds: v.array(v.id("skillEmbeddings")),
@@ -254,7 +321,9 @@ export const hydrateResults = internalQuery({
        // Use pre-resolved owner from digest to avoid reading the users table.
        // Fall back to live lookup when digest owner is null (deactivated/deleted user).
        const preResolved = digest ? digestToOwnerInfo(digest) : null;
-        const resolved = preResolved?.owner ? preResolved : await getOwnerInfo(skill.ownerUserId);
+        const resolved = preResolved?.owner
+          ? preResolved
+          : await getOwnerInfo(skill.ownerUserId, skill.ownerPublisherId);
        const publicSkill = toPublicSkill(skill);
        if (!publicSkill || !resolved.owner) return null;
        return {
@@ -278,20 +347,23 @@ 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[] = [];
    // Keep digest rows around so we can resolve owner info without hitting users table.
    const preResolvedOwners = new Map<
      Id<"skills">,
-      { ownerHandle: string | null; owner: ReturnType<typeof toPublicUser> | null }
+      { ownerHandle: string | null; owner: PublicPublisher | null }
    >();

    // Exact slug match via the skills table (only one row, cheap).
    const slugQuery = args.query.trim().toLowerCase();
-    if (/^[a-z0-9][a-z0-9-]*$/.test(slugQuery)) {
+    if (!args.skipExactSlugLookup && /^[a-z0-9][a-z0-9-]*$/.test(slugQuery)) {
      const exactSlugSkill = await ctx.db
        .query("skills")
        .withIndex("by_slug", (q) => q.eq("slug", slugQuery))
@@ -299,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);
@@ -317,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.
@@ -335,7 +409,9 @@ export const lexicalFallbackSkills = internalQuery({
    const entries = await Promise.all(
      matched.map(async (skill) => {
        const preResolved = preResolvedOwners.get(skill._id);
-        const resolved = preResolved?.owner ? preResolved : await getOwnerInfo(skill.ownerUserId);
+        const resolved = preResolved?.owner
+          ? preResolved
+          : await getOwnerInfo(skill.ownerUserId, skill.ownerPublisherId);
        const publicSkill = toPublicSkill(skill);
        if (!publicSkill || !resolved.owner) return null;
        return {
@@ -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
@@ -61,7 +61,7 @@ describe("skillTransfers", () => {
            if (table === "users") {
              return {
                withIndex: () => ({
-                  first: async () => ({ _id: "users:2", handle: "alice", displayName: "Alice" }),
+                  unique: async () => ({ _id: "users:2", handle: "alice", displayName: "Alice" }),
                }),
              };
            }
@@ -102,6 +102,242 @@ describe("skillTransfers", () => {
    );
  });

+  it("requestTransferInternal resolves recipient via personal publisher handle", async () => {
+    const insert = vi.fn(async (table: string) => {
+      if (table === "skillOwnershipTransfers") return "skillOwnershipTransfers:new";
+      return "auditLogs:1";
+    });
+
+    const result = (await requestTransferInternalHandler(
+      {
+        db: {
+          normalizeId: vi.fn(),
+          get: vi.fn(async (id: string) => {
+            if (id === "users:1") return { _id: "users:1", handle: "owner" };
+            if (id === "users:2") {
+              return {
+                _id: "users:2",
+                handle: undefined,
+                name: "Alice",
+                displayName: "Alice",
+              };
+            }
+            if (id === "skills:1") {
+              return {
+                _id: "skills:1",
+                slug: "demo",
+                displayName: "Demo",
+                ownerUserId: "users:1",
+              };
+            }
+            if (id === "publishers:alice") {
+              return {
+                _id: "publishers:alice",
+                kind: "user",
+                handle: "alice",
+                displayName: "Alice",
+                linkedUserId: "users:2",
+              };
+            }
+            return null;
+          }),
+          query: vi.fn((table: string) => {
+            if (table === "users") {
+              return {
+                withIndex: () => ({
+                  unique: async () => null,
+                }),
+              };
+            }
+            if (table === "publishers") {
+              return {
+                withIndex: () => ({
+                  unique: async () => ({
+                    _id: "publishers:alice",
+                    kind: "user",
+                    handle: "alice",
+                    displayName: "Alice",
+                    linkedUserId: "users:2",
+                  }),
+                }),
+              };
+            }
+            if (table === "skillOwnershipTransfers") {
+              return {
+                withIndex: () => ({
+                  collect: async () => [],
+                }),
+              };
+            }
+            throw new Error(`unexpected table ${table}`);
+          }),
+          patch: vi.fn(async () => {}),
+          insert,
+        },
+      } as never,
+      {
+        actorUserId: "users:1",
+        skillId: "skills:1",
+        toUserHandle: "@alice",
+      } as never,
+    )) as { ok: boolean; transferId: string };
+
+    expect(result).toEqual(
+      expect.objectContaining({
+        ok: true,
+        transferId: "skillOwnershipTransfers:new",
+        toUserHandle: "alice",
+      }),
+    );
+    expect(insert).toHaveBeenCalledWith(
+      "skillOwnershipTransfers",
+      expect.objectContaining({
+        toUserId: "users:2",
+      }),
+    );
+  });
+
+  it("acceptTransferInternal updates skill and alias ownership to the recipient publisher", async () => {
+    const patch = vi.fn(async () => {});
+    const insert = vi.fn(async () => "auditLogs:1");
+    const newPublisher = {
+      _id: "publishers:alice",
+      handle: "alice",
+      displayName: "Alice",
+      linkedUserId: "users:2",
+      trustedPublisher: false,
+    };
+    const existingMember = {
+      _id: "publisherMembers:1",
+      publisherId: "publishers:alice",
+      userId: "users:2",
+      role: "owner",
+    };
+    const aliases = [
+      {
+        _id: "skillSlugAliases:1",
+        slug: "demo-old",
+        skillId: "skills:1",
+        ownerUserId: "users:1",
+        ownerPublisherId: "publishers:owner",
+      },
+      {
+        _id: "skillSlugAliases:2",
+        slug: "demo-legacy",
+        skillId: "skills:1",
+        ownerUserId: "users:1",
+        ownerPublisherId: "publishers:owner",
+      },
+    ];
+
+    const result = (await acceptTransferInternalHandler(
+      {
+        db: {
+          normalizeId: vi.fn(),
+          get: vi.fn(async (id: string) => {
+            if (id === "users:2") {
+              return {
+                _id: "users:2",
+                handle: "alice",
+                personalPublisherId: "publishers:alice",
+                trustedPublisher: false,
+              };
+            }
+            if (id === "skillOwnershipTransfers:1") {
+              return {
+                _id: "skillOwnershipTransfers:1",
+                skillId: "skills:1",
+                fromUserId: "users:1",
+                toUserId: "users:2",
+                status: "pending",
+                requestedAt: Date.now() - 1_000,
+                expiresAt: Date.now() + 10_000,
+              };
+            }
+            if (id === "skills:1") {
+              return {
+                _id: "skills:1",
+                slug: "demo",
+                ownerUserId: "users:1",
+                ownerPublisherId: "publishers:owner",
+              };
+            }
+            if (id === "publishers:alice") {
+              return newPublisher;
+            }
+            return null;
+          }),
+          query: vi.fn((table: string) => {
+            if (table === "skillSlugAliases") {
+              return {
+                withIndex: (indexName: string) => {
+                  expect(indexName).toBe("by_skill");
+                  return {
+                    collect: async () => aliases,
+                  };
+                },
+              };
+            }
+            if (table === "publishers") {
+              return {
+                withIndex: (indexName: string) => {
+                  expect(indexName).toBe("by_handle");
+                  return {
+                    unique: async () => newPublisher,
+                  };
+                },
+              };
+            }
+            if (table === "publisherMembers") {
+              return {
+                withIndex: (indexName: string) => {
+                  expect(indexName).toBe("by_publisher_user");
+                  return {
+                    unique: async () => existingMember,
+                  };
+                },
+              };
+            }
+            throw new Error(`unexpected table ${table}`);
+          }),
+          patch,
+          insert,
+        },
+      } as never,
+      {
+        actorUserId: "users:2",
+        transferId: "skillOwnershipTransfers:1",
+      } as never,
+    )) as { ok: boolean; skillSlug: string };
+
+    expect(result).toEqual({ ok: true, skillSlug: "demo" });
+    expect(patch).toHaveBeenCalledWith(
+      "skills:1",
+      expect.objectContaining({
+        ownerUserId: "users:2",
+        ownerPublisherId: "publishers:alice",
+      }),
+    );
+    expect(patch).toHaveBeenCalledWith(
+      "skillSlugAliases:1",
+      expect.objectContaining({
+        ownerUserId: "users:2",
+        ownerPublisherId: "publishers:alice",
+      }),
+    );
+    expect(patch).toHaveBeenCalledWith(
+      "skillSlugAliases:2",
+      expect.objectContaining({
+        ownerUserId: "users:2",
+        ownerPublisherId: "publishers:alice",
+      }),
+    );
+    expect(patch).toHaveBeenCalledWith(
+      "skillOwnershipTransfers:1",
+      expect.objectContaining({ status: "accepted" }),
+    );
+  });
+
  it("acceptTransferInternal cancels stale transfer when ownership changed", async () => {
    const patch = vi.fn(async () => {});

@@ -1,6 +1,10 @@
 import { v } from "convex/values";
 import type { Doc, Id } from "./_generated/dataModel";
 import { internalMutation, internalQuery } from "./functions";
+import {
+  ensurePersonalPublisherForUser,
+  getActiveUserByHandleOrPersonalPublisher,
+} from "./lib/publishers";
 const TRANSFER_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;

 type TransferDoc = Doc<"skillOwnershipTransfers">;
@@ -111,11 +115,8 @@ export const requestTransferInternal = internalMutation({
    const toHandle = normalizeHandle(args.toUserHandle);
    if (!toHandle) throw new Error("toUserHandle required");

-    const toUser = await ctx.db
-      .query("users")
-      .withIndex("handle", (q) => q.eq("handle", toHandle))
-      .first();
-    if (!toUser || toUser.deletedAt || toUser.deactivatedAt) throw new Error("User not found");
+    const toUser = await getActiveUserByHandleOrPersonalPublisher(ctx, toHandle);
+    if (!toUser) throw new Error("User not found");
    if (toUser._id === args.actorUserId) throw new Error("Cannot transfer to yourself");

    const activePending = await getActivePendingTransferForSkill(ctx, args.skillId, now);
@@ -157,7 +158,7 @@ export const acceptTransferInternal = internalMutation({
  },
  handler: async (ctx, args) => {
    const now = Date.now();
-    await requireActiveUserById(ctx, args.actorUserId);
+    const newOwner = await requireActiveUserById(ctx, args.actorUserId);

    const transfer = await validatePendingTransferForActor(ctx, {
      transferId: args.transferId,
@@ -173,10 +174,27 @@ export const acceptTransferInternal = internalMutation({
      throw new Error("Transfer is no longer valid");
    }

+    const newPublisher = await ensurePersonalPublisherForUser(ctx, newOwner);
+    if (!newPublisher) throw new Error("Failed to resolve publisher for new owner");
+
    await ctx.db.patch(skill._id, {
      ownerUserId: args.actorUserId,
+      ownerPublisherId: newPublisher._id,
      updatedAt: now,
    });
+
+    const aliases = await ctx.db
+      .query("skillSlugAliases")
+      .withIndex("by_skill", (q) => q.eq("skillId", skill._id))
+      .collect();
+    for (const alias of aliases) {
+      await ctx.db.patch(alias._id, {
+        ownerUserId: args.actorUserId,
+        ownerPublisherId: newPublisher._id,
+        updatedAt: now,
+      });
+    }
+
    await ctx.db.patch(transfer._id, { status: "accepted", respondedAt: now });

    await ctx.db.insert("auditLogs", {
@@ -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");
+  });
+});
@@ -0,0 +1,124 @@
+import { getAuthUserId } from "@convex-dev/auth/server";
+import { describe, expect, it, vi } from "vitest";
+import { list } from "./skills";
+
+vi.mock("@convex-dev/auth/server", () => ({
+  getAuthUserId: vi.fn(),
+  authTables: {},
+}));
+
+type WrappedHandler<TArgs, TResult = unknown> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>;
+};
+
+const listHandler = (
+  list as unknown as WrappedHandler<
+    { ownerPublisherId?: string; ownerUserId?: string; limit?: number },
+    Array<{ slug: string }>
+  >
+)._handler;
+
+describe("skills.list", () => {
+  it("includes legacy personal skills when listing a personal publisher", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:owner" as never);
+    const legacySkill = {
+      _id: "skills:legacy",
+      _creationTime: 1,
+      slug: "legacy-skill",
+      displayName: "Legacy Skill",
+      summary: "Pre-backfill skill",
+      ownerUserId: "users:owner",
+      ownerPublisherId: undefined,
+      canonicalSkillId: undefined,
+      forkOf: undefined,
+      latestVersionId: undefined,
+      tags: {},
+      badges: undefined,
+      stats: {
+        downloads: 0,
+        installsCurrent: 0,
+        installsAllTime: 0,
+        stars: 0,
+        versions: 1,
+        comments: 0,
+      },
+      createdAt: 1,
+      updatedAt: 2,
+      softDeletedAt: undefined,
+      moderationStatus: "active",
+      moderationFlags: [],
+      moderationReason: undefined,
+    };
+
+    const ctx = {
+      db: {
+        get: vi.fn(async (id: string) => {
+          if (id === "publishers:self") {
+            return {
+              _id: "publishers:self",
+              _creationTime: 1,
+              kind: "user",
+              handle: "owner",
+              displayName: "Owner",
+              linkedUserId: "users:owner",
+            };
+          }
+          if (id === "users:owner") {
+            return {
+              _id: "users:owner",
+              _creationTime: 1,
+              handle: "owner",
+              displayName: "Owner",
+            };
+          }
+          return null;
+        }),
+        query: vi.fn((table: string) => {
+          if (table === "publisherMembers") {
+            return {
+              withIndex: vi.fn(() => ({
+                unique: vi.fn().mockResolvedValue(null),
+              })),
+            };
+          }
+          if (table === "skills") {
+            return {
+              withIndex: vi.fn((indexName: string) => {
+                if (indexName === "by_owner_publisher") {
+                  return {
+                    order: vi.fn(() => ({
+                      take: vi.fn().mockResolvedValue([]),
+                    })),
+                  };
+                }
+                if (indexName === "by_owner") {
+                  return {
+                    order: vi.fn(() => ({
+                      take: vi.fn().mockResolvedValue([legacySkill]),
+                    })),
+                  };
+                }
+                throw new Error(`unexpected skills index ${indexName}`);
+              }),
+            };
+          }
+          if (table === "skillBadges") {
+            return {
+              withIndex: vi.fn(() => ({
+                take: vi.fn().mockResolvedValue([]),
+              })),
+            };
+          }
+          throw new Error(`unexpected table ${table}`);
+        }),
+      },
+    };
+
+    const result = await listHandler(
+      ctx as never,
+      { ownerPublisherId: "publishers:self", limit: 10 } as never,
+    );
+
+    expect(result).toEqual([expect.objectContaining({ slug: "legacy-skill" })]);
+  });
+});
@@ -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;
@@ -113,13 +119,14 @@ describe("skills.getBySlug", () => {
    const result = await getBySlugHandler(ctx, { slug: "demo" } as never);

    expect(result?.owner).toEqual({
-      _id: "users:1",
+      _id: "publishers:demo-owner",
      _creationTime: 1,
+      kind: "user",
      handle: "demo-owner",
-      name: "Demo Owner",
      displayName: "Demo Owner",
      image: null,
      bio: "Ships demo skills",
+      linkedUserId: "users:1",
    });
    expect(result?.owner).not.toHaveProperty("email");
    expect(result?.owner).not.toHaveProperty("emailVerificationTime");
@@ -170,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",
+      }),
+    ]);
+  });
 });
@@ -37,6 +37,7 @@ function makeCtx() {
    slug: "padel",
    displayName: "Padel",
    ownerUserId: "users:owner",
+    ownerPublisherId: "publishers:local",
    latestVersionId: "skillVersions:1",
    manualOverride: {
      verdict: "clean",
@@ -103,6 +104,15 @@ function makeCtx() {
    switch (id) {
      case "skillVersions:1":
        return latestVersion;
+      case "publishers:local":
+        return {
+          _id: "publishers:local",
+          _creationTime: 1,
+          kind: "user",
+          handle: "local-publisher",
+          displayName: "Local Dev",
+          linkedUserId: "users:owner",
+        };
      case "users:owner":
        return {
          _id: "users:owner",
@@ -150,7 +160,7 @@ describe("getBySlugForStaff audit logs", () => {
    vi.mocked(requireUser).mockReset();
  });

-  it("returns reviewer info and recent audit logs with actor handles", async () => {
+  it("returns publisher-backed owner info plus recent audit logs with actor handles", async () => {
    vi.mocked(requireUser).mockResolvedValue({
      userId: "users:moderator",
      user: { _id: "users:moderator", role: "moderator" },
@@ -162,6 +172,7 @@ describe("getBySlugForStaff audit logs", () => {
      slug: "padel",
      auditLogLimit: 5,
    })) as {
+      owner: { handle?: string | null } | null;
      overrideReviewer: { handle?: string | null } | null;
      auditLogs: Array<{
        actor: { handle?: string | null } | null;
@@ -171,6 +182,7 @@ describe("getBySlugForStaff audit logs", () => {

    expect(getSkillBadgeMap).toHaveBeenCalled();
    expect(auditTake).toHaveBeenCalledWith(5);
+    expect(result.owner?.handle).toBe("local-publisher");
    expect(result.overrideReviewer?.handle).toBe("moddy");
    expect(result.auditLogs).toHaveLength(2);
    expect(result.auditLogs[0]?.action).toBe("skill.manual_override.set");
@@ -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.
@@ -1,5 +1,9 @@
 import { afterEach, describe, expect, it, vi } from "vitest";

+vi.mock("@convex-dev/auth/server", () => ({
+  getAuthUserId: vi.fn(),
+}));
+
 vi.mock("./lib/access", async () => {
  const actual = await vi.importActual<typeof import("./lib/access")>("./lib/access");
  return { ...actual, requireUser: vi.fn() };
@@ -10,21 +14,48 @@ vi.mock("./skillStatEvents", () => ({
 }));

 const { requireUser } = await import("./lib/access");
+const { getAuthUserId } = await import("@convex-dev/auth/server");
 const { insertStatEvent } = await import("./skillStatEvents");
 const {
  ensureHandler,
+  getByHandle,
  list,
  searchInternal,
  banUserInternal,
+  me,
  placeUserUnderModerationInternal,
  reserveHandleInternal,
  syncGitHubProfileInternal,
 } = await import("./users");

+type WrappedHandler<TArgs, TResult> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>;
+};
+
+const meHandler = (me as unknown as WrappedHandler<Record<string, never>, unknown>)._handler;
+const getByHandleHandler = (getByHandle as unknown as WrappedHandler<{ handle: string }, unknown>)
+  ._handler;
+
 function makeCtx() {
  const patch = vi.fn();
-  const get = vi.fn();
-  const insert = vi.fn();
+  const publisherRows = new Map<string, Record<string, unknown>>();
+  const publisherMembers: Array<Record<string, unknown>> = [];
+  const get = vi.fn(async (id: string) => publisherRows.get(id) ?? null);
+  const insert = vi.fn(async (table: string, value: Record<string, unknown>) => {
+    if (table === "publishers") {
+      const handle = typeof value.handle === "string" ? value.handle : "user";
+      const id = `publishers:${handle}`;
+      publisherRows.set(id, { _id: id, _creationTime: 1, ...value });
+      return id;
+    }
+    if (table === "publisherMembers") {
+      const id = `publisherMembers:${publisherMembers.length + 1}`;
+      publisherMembers.push({ _id: id, ...value });
+      return id;
+    }
+    if (table === "auditLogs") return "auditLogs:1";
+    return `${table}:1`;
+  });
  const query = vi.fn((table: string) => {
    if (table === "reservedHandles") {
      return {
@@ -44,6 +75,39 @@ function makeCtx() {
        },
      };
    }
+    if (table === "publishers") {
+      return {
+        withIndex: (name: string) => {
+          if (name === "by_handle") {
+            return { unique: vi.fn(async () => null) };
+          }
+          if (name === "by_linked_user") {
+            return { unique: vi.fn(async () => 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}`);
  });
  return {
@@ -55,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,
@@ -116,6 +231,7 @@ function makeBanCtx() {
 describe("ensureHandler", () => {
  afterEach(() => {
    vi.mocked(requireUser).mockReset();
+    vi.mocked(getAuthUserId).mockReset();
  });

  it("updates handle and display name when GitHub login changes", async () => {
@@ -212,7 +328,14 @@ describe("ensureHandler", () => {

    const result = await ensureHandler(ctx);

-    expect(patch).not.toHaveBeenCalled();
+    expect(patch).not.toHaveBeenCalledWith(
+      "users:4",
+      expect.objectContaining({
+        handle: expect.anything(),
+        displayName: expect.anything(),
+        role: expect.anything(),
+      }),
+    );
    expect(get).toHaveBeenCalledWith("users:4");
    expect(result).toMatchObject({ _id: "users:4" });
  });
@@ -266,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) => {
@@ -310,6 +542,303 @@ describe("ensureHandler", () => {

    expect(patch).not.toHaveBeenCalled();
  });
+
+  it("does not auto-claim a handle already owned by an org publisher", 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 () =>
+                  handle === "openclaw"
+                    ? {
+                        _id: "publishers:openclaw",
+                        kind: "org",
+                        handle: "openclaw",
+                        displayName: "OpenClaw",
+                      }
+                    : null,
+                ),
+              };
+            }
+            if (name === "by_linked_user") {
+              return {
+                unique: vi.fn(async () =>
+                  linkedUserId === "users:other"
+                    ? {
+                        _id: "publishers:openclaw-user",
+                        kind: "user",
+                        handle: "openclaw-user",
+                        linkedUserId: "users:other",
+                        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:other",
+      user: {
+        _id: "users:other",
+        _creationTime: 1,
+        handle: undefined,
+        displayName: undefined,
+        name: "openclaw",
+        email: undefined,
+        role: "user",
+        createdAt: 1,
+      },
+    } as never);
+
+    await ensureHandler(ctx);
+
+    expect(patch).not.toHaveBeenCalledWith(
+      "users:other",
+      expect.objectContaining({ handle: "openclaw" }),
+    );
+  });
+});
+
+describe("me", () => {
+  afterEach(() => {
+    vi.mocked(getAuthUserId).mockReset();
+  });
+
+  it("returns null when auth resolution throws", async () => {
+    vi.mocked(getAuthUserId).mockRejectedValue(new Error("stale session"));
+    const get = vi.fn();
+
+    const result = await meHandler({ db: { get } } as never, {});
+
+    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", () => {
+  it("normalizes the incoming handle before querying", async () => {
+    const unique = vi.fn(async () => ({
+      _id: "users:owner",
+      _creationTime: 1,
+      handle: "jaredforreal",
+      name: "jaredforreal",
+      displayName: "Jared",
+      image: undefined,
+      bio: undefined,
+    }));
+
+    const result = await getByHandleHandler(
+      {
+        db: {
+          query: vi.fn((table: string) => {
+            if (table !== "users") throw new Error(`Unexpected table ${table}`);
+            return {
+              withIndex: (
+                name: string,
+                builder?: (q: { eq: (field: string, value: string) => unknown }) => unknown,
+              ) => {
+                if (name !== "handle") throw new Error(`Unexpected index ${name}`);
+                let handle = "";
+                const q = {
+                  eq: (field: string, value: string) => {
+                    if (field === "handle") handle = value;
+                    return q;
+                  },
+                };
+                builder?.(q);
+                expect(handle).toBe("jaredforreal");
+                return { unique };
+              },
+            };
+          }),
+          get: vi.fn(),
+        },
+      } as never,
+      { handle: " @JaredForReal " },
+    );
+
+    expect(unique).toHaveBeenCalledOnce();
+    expect(result).toMatchObject({
+      _id: "users:owner",
+      handle: "jaredforreal",
+      displayName: "Jared",
+    });
+  });
+
+  it("falls back to the linked user for a personal publisher handle", async () => {
+    const userUnique = vi.fn(async () => null);
+    const publisherUnique = vi.fn(async () => ({
+      _id: "publishers:jaredforreal",
+      kind: "user",
+      handle: "jaredforreal",
+      linkedUserId: "users:owner",
+      displayName: "Jared",
+    }));
+    const get = vi.fn(async (id: string) =>
+      id === "users:owner"
+        ? {
+            _id: "users:owner",
+            _creationTime: 1,
+            handle: "jared",
+            name: "jaredforreal",
+            displayName: "Jared",
+            image: undefined,
+            bio: "Profile",
+          }
+        : null,
+    );
+
+    const result = await getByHandleHandler(
+      {
+        db: {
+          query: vi.fn((table: string) => {
+            if (table === "users") {
+              return {
+                withIndex: (name: string) => {
+                  if (name !== "handle") throw new Error(`Unexpected users index ${name}`);
+                  return { unique: userUnique };
+                },
+              };
+            }
+            if (table === "publishers") {
+              return {
+                withIndex: (name: string) => {
+                  if (name !== "by_handle") throw new Error(`Unexpected publishers index ${name}`);
+                  return { unique: publisherUnique };
+                },
+              };
+            }
+            throw new Error(`Unexpected table ${table}`);
+          }),
+          get,
+        },
+      } as never,
+      { handle: "jaredforreal" },
+    );
+
+    expect(userUnique).toHaveBeenCalledOnce();
+    expect(publisherUnique).toHaveBeenCalledOnce();
+    expect(get).toHaveBeenCalledWith("users:owner");
+    expect(result).toMatchObject({
+      _id: "users:owner",
+      handle: "jared",
+      name: "jaredforreal",
+      displayName: "Jared",
+      bio: "Profile",
+    });
+  });
+
+  it("does not resolve a deleted personal publisher handle", async () => {
+    const userUnique = vi.fn(async () => null);
+    const publisherUnique = vi.fn(async () => ({
+      _id: "publishers:jaredforreal",
+      kind: "user",
+      handle: "jaredforreal",
+      linkedUserId: "users:owner",
+      deletedAt: 1_700_000_000_000,
+      displayName: "Jared",
+    }));
+    const get = vi.fn(async () => {
+      throw new Error("linked user should not be loaded for inactive publishers");
+    });
+
+    const result = await getByHandleHandler(
+      {
+        db: {
+          query: vi.fn((table: string) => {
+            if (table === "users") {
+              return {
+                withIndex: (name: string) => {
+                  if (name !== "handle") throw new Error(`Unexpected users index ${name}`);
+                  return { unique: userUnique };
+                },
+              };
+            }
+            if (table === "publishers") {
+              return {
+                withIndex: (name: string) => {
+                  if (name !== "by_handle") throw new Error(`Unexpected publishers index ${name}`);
+                  return { unique: publisherUnique };
+                },
+              };
+            }
+            throw new Error(`Unexpected table ${table}`);
+          }),
+          get,
+        },
+      } as never,
+      { handle: "jaredforreal" },
+    );
+
+    expect(userUnique).toHaveBeenCalledOnce();
+    expect(publisherUnique).toHaveBeenCalledOnce();
+    expect(get).not.toHaveBeenCalled();
+    expect(result).toBeNull();
+  });
 });

 describe("users.syncGitHubProfileInternal", () => {
@@ -370,6 +899,122 @@ describe("users.syncGitHubProfileInternal", () => {
      expect.objectContaining({ handle: "openclaw" }),
    );
  });
+
+  it("keeps a derived handle unchanged when the new login belongs to an org publisher", async () => {
+    const { ctx, get, patch, query } = makeCtx();
+    get.mockResolvedValue({
+      _id: "users:other",
+      handle: "old-handle",
+      displayName: "old-handle",
+      name: "old-handle",
+    });
+    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 () =>
+                  handle === "openclaw"
+                    ? {
+                        _id: "publishers:openclaw",
+                        kind: "org",
+                        handle: "openclaw",
+                        displayName: "OpenClaw",
+                      }
+                    : null,
+                ),
+              };
+            }
+            if (name === "by_linked_user") {
+              return {
+                unique: vi.fn(async () =>
+                  linkedUserId === "users:other"
+                    ? {
+                        _id: "publishers:old-handle",
+                        kind: "user",
+                        handle: "old-handle",
+                        linkedUserId: "users:other",
+                        displayName: "Old Handle",
+                      }
+                    : 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);
+
+    const handler = (
+      syncGitHubProfileInternal as unknown as {
+        _handler: (ctx: unknown, args: unknown) => Promise<void>;
+      }
+    )._handler;
+
+    await handler(ctx, {
+      userId: "users:other",
+      name: "openclaw",
+      syncedAt: 10,
+    });
+
+    expect(patch).toHaveBeenCalledWith(
+      "users:other",
+      expect.objectContaining({
+        githubProfileSyncedAt: 10,
+        name: "openclaw",
+      }),
+    );
+    expect(patch).not.toHaveBeenCalledWith(
+      "users:other",
+      expect.objectContaining({ handle: "openclaw" }),
+    );
+  });
 });

 describe("users.list", () => {
@@ -430,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",
@@ -484,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",
@@ -591,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 = (
@@ -613,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,11 +1,16 @@
-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,
+  getActiveUserByHandleOrPersonalPublisher,
+  getPublisherByHandle,
+  getUserByHandleOrPersonalPublisher,
+} from "./lib/publishers";
 import { toPublicUser } from "./lib/public";
 import {
  getLatestActiveReservedHandle,
@@ -32,6 +37,13 @@ export const getByIdInternal = internalQuery({
  handler: async (ctx, args) => ctx.db.get(args.userId),
 });

+export const getByHandleInternal = internalQuery({
+  args: { handle: v.string() },
+  handler: async (ctx, args) => {
+    return await getUserByHandleOrPersonalPublisher(ctx, args.handle);
+  },
+});
+
 export const searchInternal = internalQuery({
  args: {
    actorUserId: v.id("users"),
@@ -44,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 };
  },
 });

@@ -84,7 +109,7 @@ export const syncGitHubProfileInternal = internalMutation({
  handler: async (ctx, args) => {
    const user = await ctx.db.get(args.userId);
    if (!user || user.deletedAt || user.deactivatedAt) return;
-    const canClaimNewHandle = !(await isHandleReservedForAnotherUser(ctx, args.name, args.userId));
+    const canClaimNewHandle = await canUserClaimHandle(ctx, args.name, args.userId);

    const updates: Partial<Doc<"users">> = { githubProfileSyncedAt: args.syncedAt };
    let didChangeProfile = false;
@@ -134,6 +159,8 @@ export const syncGitHubProfileInternal = internalMutation({
      updates.updatedAt = Date.now();
    }
    await ctx.db.patch(args.userId, updates);
+    const nextUser = didChangeProfile ? ({ ...user, ...updates } as Doc<"users">) : user;
+    await ensurePersonalPublisherForUser(ctx, nextUser);
  },
 });

@@ -151,11 +178,9 @@ export const syncGitHubProfileAction = internalAction({
 export const me = query({
  args: {},
  handler: async (ctx) => {
-    const userId = await getAuthUserId(ctx);
+    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);
  },
 });

@@ -176,21 +201,71 @@ function deriveHandle(args: { existingHandle?: string; githubLogin?: string; ema
  return undefined;
 }

+function appendHandleSuffix(base: string, suffix: number) {
+  const suffixText = suffix <= 1 ? "" : `-${suffix}`;
+  const maxBaseLength = Math.max(2, 40 - suffixText.length);
+  return `${base.slice(0, maxBaseLength)}${suffixText}`;
+}
+
+async function resolveAvailableHandle(
+  ctx: MutationCtx,
+  preferredHandle: string | undefined,
+  userId: Id<"users">,
+) {
+  const normalizedHandle = normalizeReservedHandle(preferredHandle);
+  if (!normalizedHandle) return undefined;
+  for (let suffix = 1; suffix <= 50; suffix += 1) {
+    const candidate = appendHandleSuffix(normalizedHandle, suffix);
+    if (await canUserClaimHandle(ctx, candidate, userId)) return candidate;
+  }
+  return undefined;
+}
+
+async function canUserClaimHandle(
+  ctx: MutationCtx,
+  handle: string | undefined,
+  userId: Id<"users">,
+) {
+  const normalizedHandle = normalizeReservedHandle(handle);
+  if (!normalizedHandle) return false;
+  if (await isHandleReservedForAnotherUser(ctx, normalizedHandle, userId)) return false;
+
+  const publisher = await getPublisherByHandle(ctx, normalizedHandle);
+  if (!publisher || publisher.deletedAt || publisher.deactivatedAt) return true;
+  return publisher.kind === "user" && publisher.linkedUserId === userId;
+}
+
 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,
    githubLogin,
    email: user.email,
  });
-  const derivedHandle =
-    requestedHandle && !(await isHandleReservedForAnotherUser(ctx, requestedHandle, user._id))
+  let derivedHandle =
+    requestedHandle && (await canUserClaimHandle(ctx, requestedHandle, user._id))
      ? requestedHandle
      : undefined;
-  const baseHandle = derivedHandle ?? existingHandle;
+  if (!derivedHandle && (!existingHandle || !existingHandleClaimable)) {
+    const emailFallback = normalizeHandle(user.email?.split("@")[0]);
+    const emailFallbackHandle =
+      emailFallback && emailFallback !== requestedHandle
+        ? await resolveAvailableHandle(ctx, emailFallback, user._id)
+        : undefined;
+    derivedHandle =
+      (await resolveAvailableHandle(
+        ctx,
+        requestedHandle ?? existingHandle ?? githubLogin ?? emailFallback,
+        user._id,
+      )) ?? emailFallbackHandle;
+  }
+  const baseHandle = derivedHandle ?? (existingHandleClaimable ? existingHandle : undefined);

  if (derivedHandle && existingHandle !== derivedHandle) {
    updates.handle = derivedHandle;
@@ -216,12 +291,14 @@ export async function ensureHandler(ctx: MutationCtx) {
  const { userId, user } = await requireUser(ctx);
  const updates = await computeEnsureUpdates(ctx, user);

+  const hasUpdates = Object.keys(updates).length > 0;
  if (Object.keys(updates).length > 0) {
    updates.updatedAt = Date.now();
    await ctx.db.patch(userId, updates);
  }
-
-  return ctx.db.get(userId);
+  const ensuredUser = hasUpdates ? ({ ...user, ...updates } as Doc<"users">) : ((await ctx.db.get(userId)) ?? user);
+  await ensurePersonalPublisherForUser(ctx, ensuredUser);
+  return await ctx.db.get(userId);
 }

 export const updateProfile = mutation({
@@ -236,6 +313,10 @@ export const updateProfile = mutation({
      bio: args.bio?.trim(),
      updatedAt: Date.now(),
    });
+    const user = await ctx.db.get(userId);
+    if (user) {
+      await ensurePersonalPublisherForUser(ctx, user);
+    }
  },
 });

@@ -284,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,
+    };
  },
 });

@@ -298,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) {
@@ -327,11 +463,21 @@ function clampInt(value: number, min: number, max: number) {
 export const getByHandle = query({
  args: { handle: v.string() },
  handler: async (ctx, args) => {
-    const user = await ctx.db
-      .query("users")
-      .withIndex("handle", (q) => q.eq("handle", args.handle))
-      .unique();
-    return toPublicUser(user);
+    return toPublicUser(await getActiveUserByHandleOrPersonalPublisher(ctx, args.handle));
+  },
+});
+
+/** 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,
+    };
  },
 });

@@ -713,6 +859,111 @@ export const setTrustedPublisherInternal = internalMutation({
  },
 });

+async function ensurePublisherHandleWithActor(
+  ctx: MutationCtx,
+  args: {
+    actorUserId: Id<"users">;
+    handle: string;
+    displayName?: string;
+    trusted?: boolean;
+  },
+) {
+  const actor = await ctx.db.get(args.actorUserId);
+  if (!actor || actor.deletedAt || actor.deactivatedAt) throw new Error("User not found");
+  assertAdmin(actor);
+
+  const normalizedHandle = normalizeReservedHandle(args.handle);
+  if (!normalizedHandle) throw new Error("Handle required");
+
+  const existing = await ctx.db
+    .query("users")
+    .withIndex("handle", (q) => q.eq("handle", normalizedHandle))
+    .unique();
+  if (existing?.deletedAt || existing?.deactivatedAt) {
+    throw new Error("Handle belongs to a deleted or deactivated user");
+  }
+
+  const now = Date.now();
+  const displayName = args.displayName?.trim() || normalizedHandle;
+  const trusted = args.trusted === false ? undefined : true;
+  const userId =
+    existing?._id ??
+    (await ctx.db.insert("users", {
+      handle: normalizedHandle,
+      displayName,
+      role: "user",
+      trustedPublisher: trusted,
+      createdAt: now,
+      updatedAt: now,
+    }));
+
+  if (existing) {
+    const nextDisplayName =
+      args.displayName?.trim() && (!existing.displayName || existing.displayName === existing.handle)
+        ? displayName
+        : existing.displayName;
+    await ctx.db.patch(existing._id, {
+      displayName: nextDisplayName,
+      trustedPublisher: trusted,
+      updatedAt: now,
+    });
+  }
+
+  await upsertReservedHandleForRightfulOwner(ctx, {
+    handle: normalizedHandle,
+    rightfulOwnerUserId: userId,
+    reason: "shared publisher",
+    now,
+  });
+
+  await ctx.db.insert("auditLogs", {
+    actorUserId: args.actorUserId,
+    action: "user.publisher.ensure",
+    targetType: "user",
+    targetId: userId,
+    metadata: {
+      handle: normalizedHandle,
+      trusted: trusted === true,
+    },
+    createdAt: now,
+  });
+
+  return {
+    ok: true as const,
+    userId,
+    handle: normalizedHandle,
+    created: !existing,
+    trusted: trusted === true,
+  };
+}
+
+export const ensurePublisherHandle = mutation({
+  args: {
+    handle: v.string(),
+    displayName: v.optional(v.string()),
+    trusted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => {
+    const { user } = await requireUser(ctx);
+    return await ensurePublisherHandleWithActor(ctx, {
+      actorUserId: user._id,
+      handle: args.handle,
+      displayName: args.displayName,
+      trusted: args.trusted,
+    });
+  },
+});
+
+export const ensurePublisherHandleInternal = internalMutation({
+  args: {
+    actorUserId: v.id("users"),
+    handle: v.string(),
+    displayName: v.optional(v.string()),
+    trusted: v.optional(v.boolean()),
+  },
+  handler: async (ctx, args) => await ensurePublisherHandleWithActor(ctx, args),
+});
+
 /**
 * Auto-ban a user whose skill was flagged malicious by VT.
 * Skips moderators/admins. No actor required — this is a system-level action.
@@ -47,12 +47,16 @@ function makeActionCtx(args: {
  soul?: Record<string, unknown> | null;
  version?: Record<string, unknown> | null;
  actor?: Record<string, unknown> | null;
+  publisherMemberRole?: "owner" | "admin" | "publisher" | null;
 }) {
  return {
    runQuery: vi.fn(async (_endpoint: unknown, payload: Record<string, unknown>) => {
      if (payload.versionId && args.version) return args.version ?? null;
      if (payload.skillId && args.skill) return args.skill ?? null;
      if (payload.soulId && args.soul) return args.soul ?? null;
+      if (payload.publisherId && payload.userId === args.actor?._id) {
+        return args.publisherMemberRole ?? null;
+      }
      if (payload.userId === args.actor?._id) {
        return args.actor ?? null;
      }
@@ -104,6 +108,28 @@ describe("version file access actions", () => {
    ).resolves.toEqual({ path: "SKILL.md", text: "# skill" });
  });

+  it("allows org collaborators to read hidden skill versions", async () => {
+    vi.mocked(getAuthUserId).mockResolvedValue("users:member" as never);
+    const ctx = makeActionCtx({
+      actor: { _id: "users:member", role: "user" },
+      publisherMemberRole: "publisher",
+      version: makeSkillVersion(),
+      skill: {
+        _id: "skills:1",
+        ownerUserId: "users:owner",
+        ownerPublisherId: "publishers:org",
+        softDeletedAt: undefined,
+        moderationStatus: "hidden",
+        moderationReason: "pending.scan",
+        moderationFlags: [],
+      },
+    });
+
+    await expect(
+      getSkillReadmeHandler._handler(ctx, { versionId: "skillVersions:1" } as never),
+    ).resolves.toEqual({ path: "SKILL.md", text: "# skill" });
+  });
+
  it("allows owners to read hidden skill files", async () => {
    vi.mocked(getAuthUserId).mockResolvedValue("users:owner" as never);
    const ctx = makeActionCtx({
@@ -1,5 +1,37 @@
-import { describe, expect, it } from "vitest";
-import { __test } from "./vt";
+/* @vitest-environment node */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { __test, pollPackageReleaseScanResults, scanPackageReleaseWithVirusTotal } from "./vt";
+
+type WrappedHandler<TArgs, TResult> = {
+  _handler: (ctx: unknown, args: TArgs) => Promise<TResult>;
+};
+
+const scanPackageReleaseWithVirusTotalHandler = (
+  scanPackageReleaseWithVirusTotal as unknown as WrappedHandler<
+    { releaseId: string; attempt?: number },
+    void
+  >
+)._handler;
+
+const pollPackageReleaseScanResultsHandler = (
+  pollPackageReleaseScanResults as unknown as WrappedHandler<
+    { releaseId: string; attempt?: number },
+    void
+  >
+)._handler;
+
+const originalVtApiKey = process.env.VT_API_KEY;
+
+afterEach(() => {
+  if (originalVtApiKey === undefined) {
+    delete process.env.VT_API_KEY;
+  } else {
+    process.env.VT_API_KEY = originalVtApiKey;
+  }
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});

 describe("vt activation fallback", () => {
  it("activates only VT-pending hidden skills", () => {
@@ -100,3 +132,542 @@ describe("vt AV engine fallback verdicts", () => {
    ).toBeNull();
  });
 });
+
+describe("package VT retries", () => {
+  it("retries package scan when release files are not readable yet", async () => {
+    process.env.VT_API_KEY = "test-key";
+    const scheduler = { runAfter: vi.fn(async () => null) };
+
+    await scanPackageReleaseWithVirusTotalHandler(
+      {
+        runQuery: vi
+          .fn()
+          .mockResolvedValueOnce({
+            _id: "packageReleases:demo",
+            packageId: "packages:demo",
+            version: "1.0.0",
+            files: [{ path: "package.json", storageId: "storage:pkg" }],
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            name: "demo-plugin",
+          }),
+        runMutation: vi.fn(async () => null),
+        scheduler,
+        storage: {
+          get: vi.fn(async () => null),
+        },
+      } as never,
+      { releaseId: "packageReleases:demo", attempt: 2 },
+    );
+
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 3,
+    });
+  });
+
+  it("retries package upload when VT upload fails", async () => {
+    process.env.VT_API_KEY = "test-key";
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(new Response("", { status: 404 }))
+      .mockResolvedValueOnce(new Response("rate limited", { status: 429 }));
+    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",
+            files: [{ path: "package.json", storageId: "storage:pkg" }],
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            name: "demo-plugin",
+          }),
+        runMutation,
+        scheduler,
+        storage: {
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
+        },
+      } as never,
+      { releaseId: "packageReleases:demo" },
+    );
+
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        releaseId: "packageReleases:demo",
+        sha256hash: expect.any(String),
+      }),
+    );
+    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 () => {
+    process.env.VT_API_KEY = "test-key";
+    const fetchMock = vi.fn().mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          attributes: {
+            last_analysis_stats: {
+              malicious: 0,
+              suspicious: 1,
+              harmless: 10,
+              undetected: 40,
+            },
+          },
+        },
+      }),
+    });
+    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: "clean" },
+            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).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        releaseId: "packageReleases:demo",
+        vtAnalysis: expect.objectContaining({ status: "suspicious", source: "engines" }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(scheduler.runAfter).not.toHaveBeenCalled();
+  });
+
+  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,
+      json: async () => ({
+        data: {
+          attributes: {
+            last_analysis_stats: {
+              malicious: 0,
+              suspicious: 0,
+              harmless: 0,
+              undetected: 66,
+            },
+          },
+        },
+      }),
+    });
+    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: "clean" },
+            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).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        releaseId: "packageReleases:demo",
+        vtAnalysis: expect.objectContaining({
+          status: "clean",
+          source: "engines-undetected-fallback",
+          verdict: "undetected-only-fallback",
+        }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(scheduler.runAfter).not.toHaveBeenCalled();
+  });
+
+  it("promotes community source-linked packages with undetected-only VT stats 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,
+            },
+          },
+        },
+      }),
+    });
+    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: "clean" },
+            files: [{ path: "package.json", storageId: "storage:pkg" }],
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            name: "demo-plugin",
+            family: "code-plugin",
+            isOfficial: false,
+          }),
+        runMutation,
+        scheduler,
+        storage: {
+          get: vi.fn(
+            async () => new Blob(['{"name":"demo-plugin"}'], { type: "application/json" }),
+          ),
+        },
+      } as never,
+      { releaseId: "packageReleases:demo" },
+    );
+
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        releaseId: "packageReleases:demo",
+        vtAnalysis: expect.objectContaining({
+          status: "clean",
+          source: "engines-undetected-fallback",
+          verdict: "undetected-only-fallback",
+        }),
+      }),
+    );
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(scheduler.runAfter).not.toHaveBeenCalled();
+  });
+
+  it("retries package poll when VT lookup throws", async () => {
+    process.env.VT_API_KEY = "test-key";
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network error")));
+
+    const scheduler = { runAfter: vi.fn(async () => null) };
+    await pollPackageReleaseScanResultsHandler(
+      {
+        runQuery: vi.fn().mockResolvedValue({
+          _id: "packageReleases:demo",
+          packageId: "packages:demo",
+          version: "1.0.0",
+          sha256hash: "abc123",
+        }),
+        runMutation: vi.fn(async () => null),
+        scheduler,
+      } as never,
+      { releaseId: "packageReleases:demo", attempt: 3 },
+    );
+
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 4,
+    });
+  });
+
+  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",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 0,
+                harmless: 0,
+                undetected: 66,
+              },
+            },
+          },
+        }),
+      }),
+    );
+
+    const runMutation = vi.fn(async () => null);
+    const scheduler = { runAfter: vi.fn(async () => null) };
+    await pollPackageReleaseScanResultsHandler(
+      {
+        runQuery: vi
+          .fn()
+          .mockResolvedValueOnce({
+            _id: "packageReleases:demo",
+            packageId: "packages:demo",
+            version: "1.0.0",
+            sha256hash: "abc123",
+            verification: { tier: "source-linked" },
+            llmAnalysis: { status: "clean" },
+            staticScan: { status: "suspicious" },
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            family: "code-plugin",
+            isOfficial: true,
+          }),
+        runMutation,
+        scheduler,
+      } as never,
+      { releaseId: "packageReleases:demo", attempt: 3 },
+    );
+
+    expect(runMutation).not.toHaveBeenCalled();
+    expect(scheduler.runAfter).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies the same undetected-only fallback during community package polling", async () => {
+    process.env.VT_API_KEY = "test-key";
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          data: {
+            attributes: {
+              last_analysis_stats: {
+                malicious: 0,
+                suspicious: 0,
+                harmless: 0,
+                undetected: 66,
+              },
+            },
+          },
+        }),
+      }),
+    );
+
+    const runMutation = vi.fn(async () => null);
+    const scheduler = { runAfter: vi.fn(async () => null) };
+    await pollPackageReleaseScanResultsHandler(
+      {
+        runQuery: vi
+          .fn()
+          .mockResolvedValueOnce({
+            _id: "packageReleases:demo",
+            packageId: "packages:demo",
+            version: "1.0.0",
+            sha256hash: "abc123",
+            verification: { tier: "source-linked" },
+            llmAnalysis: { status: "clean" },
+            staticScan: { status: "clean" },
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            family: "code-plugin",
+            isOfficial: false,
+          }),
+        runMutation,
+        scheduler,
+      } as never,
+      { releaseId: "packageReleases:demo", attempt: 3 },
+    );
+
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        releaseId: "packageReleases:demo",
+        vtAnalysis: expect.objectContaining({
+          status: "clean",
+          source: "engines-undetected-fallback",
+          verdict: "undetected-only-fallback",
+        }),
+      }),
+    );
+    expect(scheduler.runAfter).not.toHaveBeenCalled();
+  });
+
+  it("does not promote undetected-only community packages without trusted verification", 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 () => ({}),
+      });
+    vi.stubGlobal("fetch", fetchMock);
+
+    const runMutation = vi.fn(async () => null);
+    const scheduler = { runAfter: vi.fn(async () => null) };
+    await pollPackageReleaseScanResultsHandler(
+      {
+        runQuery: vi
+          .fn()
+          .mockResolvedValueOnce({
+            _id: "packageReleases:demo",
+            packageId: "packages:demo",
+            version: "1.0.0",
+            sha256hash: "abc123",
+            verification: { tier: "artifact-only" },
+            llmAnalysis: { status: "clean" },
+            staticScan: { status: "clean" },
+          })
+          .mockResolvedValueOnce({
+            _id: "packages:demo",
+            family: "code-plugin",
+            isOfficial: false,
+          }),
+        runMutation,
+        scheduler,
+      } as never,
+      { releaseId: "packageReleases:demo", attempt: 3 },
+    );
+
+    expect(runMutation).not.toHaveBeenCalled();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(scheduler.runAfter).toHaveBeenCalledWith(5 * 60 * 1000, expect.anything(), {
+      releaseId: "packageReleases:demo",
+      attempt: 4,
+    });
+  });
+});
@@ -1,9 +1,46 @@
 import { v } from "convex/values";
 import { internal } from "./_generated/api";
-import type { Id } from "./_generated/dataModel";
+import type { Doc, Id } from "./_generated/dataModel";
 import type { ActionCtx } from "./_generated/server";
 import { action, internalAction, internalMutation } from "./functions";
-import { buildDeterministicZip } from "./lib/skillZip";
+import { buildDeterministicPackageZip, buildDeterministicZip } from "./lib/skillZip";
+
+const internalRefs = internal as unknown as {
+  packages: {
+    getReleaseByIdInternal: unknown;
+    getPackageByIdInternal: unknown;
+    updateReleaseScanResultsInternal: unknown;
+  };
+  vt: {
+    scanPackageReleaseWithVirusTotal: unknown;
+    pollPackageReleaseScanResults: unknown;
+  };
+};
+
+async function runQueryRef<T>(
+  ctx: { runQuery: (ref: never, args: never) => Promise<unknown> },
+  ref: unknown,
+  args: unknown,
+): Promise<T> {
+  return (await ctx.runQuery(ref as never, args as never)) as T;
+}
+
+async function runMutationRef<T>(
+  ctx: { runMutation: (ref: never, args: never) => Promise<unknown> },
+  ref: unknown,
+  args: unknown,
+): Promise<T> {
+  return (await ctx.runMutation(ref as never, args as never)) as T;
+}
+
+async function runAfterRef(
+  ctx: { scheduler: { runAfter: (delayMs: number, ref: never, args: never) => Promise<unknown> } },
+  delayMs: number,
+  ref: unknown,
+  args: unknown,
+) {
+  return await ctx.scheduler.runAfter(delayMs, ref as never, args as never);
+}

 /**
 * Fix skills that have version.vtAnalysis but null skill.moderationReason.
@@ -123,6 +160,70 @@ type VTFileResponse = {
 };

 type VTAnalysisStats = NonNullable<VTFileResponse["data"]["attributes"]["last_analysis_stats"]>;
+type PackageReleaseScanDoc = Pick<
+  Doc<"packageReleases">,
+  "verification" | "llmAnalysis" | "staticScan"
+>;
+type PackageScanDoc = Pick<Doc<"packages">, "family" | "isOfficial">;
+
+function buildPackageUndetectedFallbackAnalysis(
+  release: PackageReleaseScanDoc,
+  pkg: PackageScanDoc,
+  stats?: VTAnalysisStats,
+) {
+  if (!stats) return null;
+  if (pkg.family === "skill") return null;
+
+  const tier = release.verification?.tier;
+  if (tier !== "source-linked" && tier !== "provenance-verified" && tier !== "rebuild-verified") {
+    return null;
+  }
+  if (release.llmAnalysis?.status !== "clean") 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;
+
+  return {
+    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 clean static scans.",
+    source: "engines-undetected-fallback",
+    checkedAt: Date.now(),
+  };
+}
+
+function buildPackageScanAnalysisFromVtResult(
+  release: PackageReleaseScanDoc,
+  pkg: PackageScanDoc,
+  vtResult: VTFileResponse,
+) {
+  const aiResult = vtResult.data.attributes.crowdsourced_ai_results?.find(
+    (r) => r.category === "code_insight",
+  );
+  if (aiResult) {
+    const verdict = normalizeVerdict(aiResult.verdict);
+    return {
+      status: verdictToStatus(verdict),
+      verdict: aiResult.verdict,
+      analysis: aiResult.analysis,
+      source: aiResult.source,
+      checkedAt: Date.now(),
+    };
+  }
+
+  const stats = vtResult.data.attributes.last_analysis_stats;
+  const status = statusFromAvStats(stats);
+  if (status) {
+    return {
+      status,
+      source: "engines",
+      checkedAt: Date.now(),
+    };
+  }
+
+  return buildPackageUndetectedFallbackAnalysis(release, pkg, stats);
+}

 type ScanQueueHealth = {
  queueSize: number;
@@ -484,6 +585,229 @@ export const scanWithVirusTotal = internalAction({
  },
 });

+const PACKAGE_SCAN_RETRY_DELAY_MS = 5 * 60 * 1000;
+const PACKAGE_SCAN_MAX_ATTEMPTS = 10;
+
+export const scanPackageReleaseWithVirusTotal = internalAction({
+  args: {
+    releaseId: v.id("packageReleases"),
+    attempt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const apiKey = process.env.VT_API_KEY;
+    if (!apiKey) {
+      console.log("[vt:package] VT_API_KEY not configured, skipping package release scan");
+      return;
+    }
+
+    const release = (await runQueryRef(ctx, internalRefs.packages.getReleaseByIdInternal, {
+      releaseId: args.releaseId,
+    })) as Doc<"packageReleases"> | null;
+    if (!release || release.softDeletedAt) {
+      console.error(`[vt:package] Release ${args.releaseId} not found for scanning`);
+      return;
+    }
+
+    const pkg = (await runQueryRef(ctx, internalRefs.packages.getPackageByIdInternal, {
+      packageId: release.packageId,
+    })) as Doc<"packages"> | null;
+    if (!pkg) {
+      console.error(`[vt:package] Package ${release.packageId} not found for scanning`);
+      return;
+    }
+
+    const attempt = args.attempt ?? 1;
+    const entries: Array<{ path: string; bytes: Uint8Array }> = [];
+    let missingFiles = 0;
+    for (const file of release.files) {
+      const content = await ctx.storage.get(file.storageId);
+      if (!content) {
+        missingFiles += 1;
+        continue;
+      }
+      entries.push({
+        path: file.path,
+        bytes: new Uint8Array(await content.arrayBuffer()),
+      });
+    }
+    if (entries.length === 0 || missingFiles > 0) {
+      console.warn(
+        `[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,
+          },
+        );
+      }
+      return;
+    }
+
+    const zipArray = buildDeterministicPackageZip(entries);
+    const hashBuffer = await crypto.subtle.digest("SHA-256", zipArray);
+    const sha256hash = Array.from(new Uint8Array(hashBuffer))
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+
+    await runMutationRef(ctx, internalRefs.packages.updateReleaseScanResultsInternal, {
+      releaseId: args.releaseId,
+      sha256hash,
+    });
+
+    try {
+      const existingFile = await checkExistingFile(apiKey, sha256hash);
+      const vtAnalysis = existingFile
+        ? buildPackageScanAnalysisFromVtResult(release, pkg, existingFile)
+        : null;
+
+      if (vtAnalysis) {
+        await runMutationRef(ctx, internalRefs.packages.updateReleaseScanResultsInternal, {
+          releaseId: args.releaseId,
+          vtAnalysis,
+        });
+        return;
+      }
+    } catch (error) {
+      console.error("[vt:package] Error checking existing file in VT:", error);
+    }
+
+    const formData = new FormData();
+    const blob = new Blob([zipArray], { type: "application/zip" });
+    formData.append("file", blob, "package.zip");
+
+    try {
+      const response = await fetch("https://www.virustotal.com/api/v3/files", {
+        method: "POST",
+        headers: { "x-apikey": apiKey },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        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,
+            },
+          );
+        }
+        return;
+      }
+
+      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})`,
+      );
+    } 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,
+          },
+        );
+      }
+    }
+  },
+});
+
+export const pollPackageReleaseScanResults = internalAction({
+  args: {
+    releaseId: v.id("packageReleases"),
+    attempt: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const apiKey = process.env.VT_API_KEY;
+    if (!apiKey) return;
+
+    const release = (await runQueryRef(ctx, internalRefs.packages.getReleaseByIdInternal, {
+      releaseId: args.releaseId,
+    })) as Doc<"packageReleases"> | null;
+    if (!release || release.softDeletedAt || !release.sha256hash) return;
+    const pkg = (await runQueryRef(ctx, internalRefs.packages.getPackageByIdInternal, {
+      packageId: release.packageId,
+    })) as Doc<"packages"> | null;
+    if (!pkg || pkg.softDeletedAt) return;
+
+    const attempt = args.attempt ?? 1;
+    try {
+      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,
+            },
+          );
+        }
+        return;
+      }
+
+      const vtAnalysis = buildPackageScanAnalysisFromVtResult(release, pkg, vtResult);
+      if (vtAnalysis) {
+        await runMutationRef(ctx, internalRefs.packages.updateReleaseScanResultsInternal, {
+          releaseId: args.releaseId,
+          vtAnalysis,
+        });
+        return;
+      }
+
+      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,
+          },
+        );
+      }
+    } 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,
+          },
+        );
+      }
+    }
+  },
+});
+
 /**
 * Poll for pending scans and update skill moderation status
 * Called by cron job to check VT results for skills awaiting scan
@@ -0,0 +1,59 @@
+---
+summary: "Marketplace policy: what ClawHub will not allow."
+read_when:
+  - Reviewing uploads for abuse or policy violations
+  - Writing moderation docs or reviewer runbooks
+  - Deciding whether a skill should be hidden or a user banned
+---
+
+# Acceptable Usage
+
+This page describes the kinds of skills and content ClawHub is not okay with.
+
+These rules are intentionally practical. We care most about end-to-end abuse workflows, not just isolated keywords. If a skill is built to evade defenses, abuse platforms, scam people, invade privacy, or enable non-consensual behavior, it does not belong on ClawHub.
+
+## Not okay
+
+- Security-bypass or unauthorized-access workflows.
+  - Examples: auth bypass, account takeover, CAPTCHA bypass, Cloudflare or anti-bot evasion, rate-limit bypass, stealth scraping designed to defeat protections, live call or agent takeover, reusable session theft, auto-approving pairing flows for unapproved users.
+
+- Platform abuse and ban evasion.
+  - Examples: stealth accounts after bans, account warming/farming, fake engagement, karma or follower cultivation, multi-account automation, mass posting, spam bots, marketplace or social automation built to avoid detection.
+
+- Fraud, scams, and deceptive financial workflows.
+  - Examples: fake certificates, fake invoices, deceptive payment flows, scam outreach, fake social proof, tools that enable spending or charging without clear human approval and transparent controls, or synthetic-identity workflows built to create accounts for fraud.
+
+- Privacy-invasive scraping, enrichment, or surveillance.
+  - Examples: scraping contact details at scale for spam, doxxing, stalking, lead extraction paired with unsolicited outreach, covert monitoring, face search or biometric matching used without clear consent, or buying, publishing, downloading, or operationalizing leaked data or breach dumps.
+
+- Non-consensual impersonation or deceptive identity manipulation.
+  - Examples: face swap, digital twins, fake personas, cloned influencers, or other identity-manipulation tooling used to impersonate or mislead.
+
+- Explicit sexual content and safety-disabled adult generation.
+  - Examples: NSFW image/video/content generation, adult-content wrappers around third-party APIs, or skills whose primary purpose is explicit sexual content.
+
+- Hidden, unsafe, or misleading execution requirements.
+  - Examples: obfuscated install commands, `curl | sh`, undeclared secret requirements, undeclared private-key use, remote `npx @latest` execution without clear reviewability, misleading metadata that hides what the skill really needs to run.
+
+## Recent patterns we are explicitly not okay with
+
+- “Create stealth seller accounts after marketplace bans.”
+- “Modify Telegram pairing so unapproved users automatically receive pairing codes.”
+- “Cultivate Reddit/Twitter accounts with undetectable automation.”
+- “Generate professional certificates or invoices for arbitrary use.”
+- “Generate NSFW content with safety checks disabled.”
+- “Scrape leads, enrich contacts, and launch cold outreach at scale.”
+- “Buy, publish, or download leaked data or breach dumps.”
+- “Bulk-create email or social accounts with synthetic identities or CAPTCHA solving.”
+
+## Notes for reviewers
+
+- Context matters. The same topic can be legitimate in a narrow defensive or consent-based setting and unacceptable when packaged as an abuse workflow.
+- We should bias toward action when a skill is clearly optimized for evasion, deception, or non-consensual use.
+- Repeated uploads in these categories are grounds for hiding content and banning the account.
+
+## Enforcement
+
+- We may hide, remove, or hard-delete violating skills.
+- We may revoke tokens, soft-delete associated content, and ban repeat or severe offenders.
+- We do not guarantee warning-first enforcement for obvious abuse.
@@ -24,8 +24,8 @@ Auth-aware enforcement:
 - Authenticated requests (valid Bearer token): per user bucket.
 - Missing/invalid token falls back to IP enforcement.

- Read: 120/min per IP, 600/min per key
- Write: 30/min per IP, 120/min per key
+- Read: 180/min per IP, 900/min per key
+- Write: 45/min per IP, 180/min per key

 Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After` (on 429).

@@ -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,6 +212,70 @@ Stores your API token + cached registry URL.
 - `--fuzzy` resolves the handle via fuzzy user search (admin only).
 - `--yes` skips confirmation.

+### `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.
+- 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`

 - Scans for local skill folders and publishes new/changed ones.
@@ -25,17 +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`
- `VERCEL_TOKEN`
- 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 either required secret is missing. It no
-longer reports a successful workflow while skipping the actual deploy jobs.
+## 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; 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):

@@ -63,11 +100,9 @@ Deploy order:

 1. Convex
 2. contract verify
-3. web
+3. wait for Vercel production deploy for the same Git SHA
 4. smoke

-Do not let Vercel auto-promote a newer web build before Convex is deployed.
-
 ## 3) Route `/api/*` to Convex

 This repo currently uses `vercel.json` rewrites:
@@ -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).
--- a/Show More
+++ b/Show More