clawhub-convex

---
name: clawhub-convex
description: Apply ClawHub-specific Convex conventions and route to the right managed Convex skill. Use for any change under convex/, Convex commands or deployment targeting, query performance, migrations, retention, runtime validation, or skill stat reads and writes in the ClawHub repository.
---

# ClawHub Convex

Use the managed Convex guidance for general framework behavior and this skill
for ClawHub's repository-specific boundaries.

## Start Here

1. Read `convex/_generated/ai/guidelines.md` before editing Convex code.
2. Name the target runtime before running a Convex command: `local`, `dev`, or
   `prod`. Include the exact deployment when known and whether the current
   function/schema code has already been pushed there.
3. Route to the most specific companion skill:
   - Query cost, indexes, read amplification, subscriptions, or OCC:
     `convex-performance-audit`
   - Production migration, backfill, schema narrowing, or table reshaping:
     `convex-migration-helper` and `create-and-cleanup-migration`
   - Tables, TTL fields, cleanup crons, retention, auth/session cleanup, metric
     dedupe cleanup, or deprecated table removal: `convex-retention`
   - Auth, reusable components, or setup: use the matching managed Convex skill.

Do not edit upstream-managed Convex skills to store ClawHub policy.

## Commands And Runtime Validation

- Push new or changed functions before `convex run`:
  - dev: `bunx convex dev --once`
  - prod: deploy through the workflow described by
    `clawhub-production-release`
- For a non-interactive direct production deploy when explicitly required, use
  `bunx convex deploy -y`.
- If `bunx convex run --env-file .env.local ...` returns
  `401 MissingAccessToken` after login, omit `--env-file` and target the
  deployment with `--deployment <name>` or `--prod`.
- Regenerate committed API/types with `bunx convex codegen` after Convex
  API/schema changes.
- Import mutations from `convex/functions.ts`, not
  `convex/_generated/server`, so ClawHub's trigger wrapper runs. Type imports
  can still come from `convex/_generated/server`.
- Do not disable typechecking for an ordinary direct deploy. The production
  workflow owns its explicit deploy behavior and exceptions.

Mocked `ctx` tests cover pure business logic only. When behavior depends on
pagination, indexes, validators, auth identity, internal/public boundaries,
schedulers, actions calling functions, HTTP actions, storage, or OCC, also run
a real Convex path such as:

- `bunx convex dev --once`
- `bunx convex run ...`
- an HTTP action smoke
- `bun run test:pw:local-auth`

Tests that invoke a mutation through `._handler` need a mock database with
`normalizeId: vi.fn()` for trigger-wrapper compatibility.

## ClawHub Migration Boundaries

- Default production data changes to `@convex-dev/migrations`; the companion
  skills own batching, dry runs, resume/progress, confirmation, validation, and
  cleanup.
- Put component-backed table-wide backfills in `convex/migrations.ts`.
- Put custom repairs, admin-gated operations, and incident-specific workflows
  in `convex/maintenance.ts`.
- Keep one-off operator migration runs out of `.github/workflows/deploy.yml`.
- Remove temporary migration functions in a follow-up PR after production
  apply and verification unless they are intentionally retained as maintenance
  tooling.

## Query And Bandwidth Work

Use `convex-performance-audit` for the detailed rules on indexes, bounded reads,
denormalization, digest tables, subscriptions, and function limits. Before
writing or reviewing a performance-sensitive query, check deployment health
when available:

```bash
bunx convex insights --details
bunx convex logs --failure
```

Prefer measured runtime signals over speculative restructuring.

## ClawHub Hot-Path Conventions

Use `convex-performance-audit` for the complete workflow. Preserve these
ClawHub-specific implementations when touching their paths:

- Public listing and browse pages use one-shot `ConvexHttpClient.query()` reads
  unless the user needs live updates.
- When a `skillSearchDigest` row exists, resolve owner data with
  `digestToOwnerInfo(digest)`. Do not re-read the owner document when the
  digest already contains the required owner fields.
- Keep denormalized tables synchronized through the existing
  `convex-helpers` triggers and skip writes when derived fields did not change.
- Paginate computed search results client-side after running the scoring
  pipeline once; do not rerun the full vector, lexical, and popularity pipeline
  for each page.
- Add `delayMs` between backfill batches that update reactively subscribed
  tables.
- Split mutations that would read more than the transaction budget through the
  existing action-query-mutation pattern.

## Skill Stat Contract

The `skills` table still has a compatibility shape for four migrated stats:

| Legacy nested field     | Top-level source of truth |
| ----------------------- | ------------------------- |
| `stats.downloads`       | `statsDownloads`          |
| `stats.stars`           | `statsStars`              |
| `stats.installsCurrent` | `statsInstallsCurrent`    |
| `stats.installsAllTime` | `statsInstallsAllTime`    |

- Read these fields with `readCanonicalStat()` from
  `convex/lib/skillStats.ts`. It prefers the top-level field and falls back for
  pre-migration documents.
- Write deltas with `applySkillStatDeltas()`. It updates both shapes in one
  patch.
- Any direct patch touching these values must update both shapes.
- Nested-only reads remain valid for `stats.comments` and `stats.versions`.
- When adding a migrated stat field, use the same dual-write shape and add a
  cursor-based backfill.

More agent context in clawdbot/clawdhub

64 other files this repository gives its agents, the first 60 shown.

Also found in one other repository

The same file, byte for byte, in the weekly crawl of public GitHub.

• openclaw/clawhub9.5k