clawhub-convex

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.

1. 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.