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:

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.