[automation] Update Convex AI files

[openclaw-barnacle]

Summary

• refresh Convex-managed AI guidance files
• keep AGENTS.md / CLAUDE.md Convex sections in sync when Convex updates them
• update repo-local Convex developer skills under .agents/skills

Validation

• $(bun pm bin)/convex ai-files status

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clawhub	Ready	Preview	Sep 14, 2026 7:28am UTC

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 15, 2026, 11:59 AM ET / 15:59 UTC (Revision 147).

ClawSweeper review

What this changes

Refreshes Convex developer skills, component examples, framework guidance, and generated synchronization metadata.

Merge readiness

⛔ Needs changes before merge - 4 items remain

The refresh remains absent from current main and retains useful changes, but all three previously reported component-example defects remain unresolved.

Priority: P3
Reviewed head: 5490214d1e746d8ca67bbf0963d89b72853f2271

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	Useful, narrowly scoped maintenance remains blocked by three concrete defects in one example.
Proof confidence	🌊 off-meta tidepool	Not applicable: This bot-authored guidance refresh is exempt from contributor runtime proof; the listed synchronization check and Vercel preview do not validate the changed component example.
Patch quality	🦐 gold shrimp (3/6)	3 actionable review findings remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This bot-authored guidance refresh is exempt from contributor runtime proof; the listed synchronization check and Vercel preview do not validate the changed component example.
Evidence reviewed	8 items	Applicable repository policy: Read the complete root AGENTS.md and ClawHub maintainer/Convex skills. No applicable nested AGENTS.md or maintainer-notes directory was found. Applied component-boundary, generated-guidance, and validation guidance within the read-only review contract. Introduced example defects: The pinned parent-to-head diff introduces internalQuery without an import, args.id without a handler argument, and a users-table lookup in the component example. Documented component contract: The companion skeleton defines only notifications, stores userId as a string, and imports mutation/query. Its critical rules explicitly prohibit component access to parent-app tables. The changed schema and database calls establish a direct dependency on Convex’s component contract.
Findings	3 actionable findings	[P2] Import the new internalQuery builder [P2] Receive the declared argument in the notification handler [P2] Keep the lookup compatible with the documented component schema
Security	None	None.

How this fits together

ClawHub’s scheduled updater imports Convex guidance into repository-local instructions used by coding agents. These examples influence future backend implementations without directly changing the running application.

flowchart LR
  A[Convex guidance] --> B[Scheduled updater]
  B --> C[Tracked skills and guidelines]
  C --> D[Coding agent]
  D --> E[Component implementation]
  E --> F[Typecheck and runtime validation]

Loading

Before merge

• Import the new internalQuery builder (P2) - The example now calls internalQuery, but this block imports only v and schema, and the companion skeleton imports only mutation and query. Following either documented arrangement leaves an unresolved identifier. Add the component-local ./_generated/server.js import. This previously reported defect remains unresolved.
• Receive the declared argument in the notification handler (P2) - The new lookup reads args.id, but the handler accepts only ctx and no outer args exists. The copied example cannot typecheck and would throw when invoked without typechecking. Accept (ctx, args). This previously reported defect remains unresolved.
• Keep the lookup compatible with the documented component schema (P2) - The companion component defines only notifications, with userId: v.string(). This new lookup requires an undeclared component-local users table and cannot read the parent app’s users through the component database. Even after fixing the identifiers, the example remains invalid against its documented schema. Remove the join and demonstrate validator derivation using notification fields. This previously reported defect remains unresolved.
• Complete next step (P2) - Fix the component example’s import, handler argument, and unsupported users lookup, then validate the complete example against the documented schema.

Findings

• [P2] Import the new internalQuery builder — .agents/skills/convex-create-component/references/advanced-patterns.md:54
• [P2] Receive the declared argument in the notification handler — .agents/skills/convex-create-component/references/advanced-patterns.md:57-58
• [P2] Keep the lookup compatible with the documented component schema — .agents/skills/convex-create-component/references/advanced-patterns.md:60-64

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
LOC	+45/-50 across 10 files	The refresh changes developer guidance and synchronization metadata, with no application runtime or test-code changes.

Technical review

Best possible solution:

Keep the managed refresh while making the validator example self-contained and compatible with the existing notifications-only component schema.

Do we have a high-confidence way to reproduce the issue?

Yes, by source inspection: using the revised example with its documented component skeleton leaves two unresolved identifiers and queries an undeclared table. No example execution or tests were run.

Is this the best way to solve the issue?

No, the refresh is appropriate but its example is not usable as written; deriving and returning the existing notification document avoids adding an unrelated users schema or cross-component lookup.

Full review comments:

• [P2] Import the new internalQuery builder — .agents/skills/convex-create-component/references/advanced-patterns.md:54
  The example now calls internalQuery, but this block imports only v and schema, and the companion skeleton imports only mutation and query. Following either documented arrangement leaves an unresolved identifier. Add the component-local ./_generated/server.js import. This previously reported defect remains unresolved.
  Confidence: 0.99
• [P2] Receive the declared argument in the notification handler — .agents/skills/convex-create-component/references/advanced-patterns.md:57-58
  The new lookup reads args.id, but the handler accepts only ctx and no outer args exists. The copied example cannot typecheck and would throw when invoked without typechecking. Accept (ctx, args). This previously reported defect remains unresolved.
  Confidence: 1
• [P2] Keep the lookup compatible with the documented component schema — .agents/skills/convex-create-component/references/advanced-patterns.md:60-64
  The companion component defines only notifications, with userId: v.string(). This new lookup requires an undeclared component-local users table and cannot read the parent app’s users through the component database. Even after fixing the identifiers, the example remains invalid against its documented schema. Remove the join and demonstrate validator derivation using notification fields. This previously reported defect remains unresolved.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 91aecdc22c53.

Labels

Label justifications:

• P3: This is developer-guidance maintenance with bounded example defects and no demonstrated running-product failure.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This bot-authored guidance refresh is exempt from contributor runtime proof; the listed synchronization check and Vercel preview do not validate the changed component example.

Evidence

Acceptance criteria:

• [P1] bun run ci:static.
• [P1] bunx tsc -p packages/schema/tsconfig.json --noEmit.
• [P1] bunx tsc -p packages/clawhub/tsconfig.json --noEmit.
• [P1] bunx tsc --noEmit.
• [P1] bunx convex ai-files status.

What I checked:

• Applicable repository policy: Read the complete root AGENTS.md and ClawHub maintainer/Convex skills. No applicable nested AGENTS.md or maintainer-notes directory was found. Applied component-boundary, generated-guidance, and validation guidance within the read-only review contract. (AGENTS.md:1, 5490214d1e74)
• Introduced example defects: The pinned parent-to-head diff introduces internalQuery without an import, args.id without a handler argument, and a users-table lookup in the component example. (.agents/skills/convex-create-component/references/advanced-patterns.md:54, 5490214d1e74)
• Documented component contract: The companion skeleton defines only notifications, stores userId as a string, and imports mutation/query. Its critical rules explicitly prohibit component access to parent-app tables. The changed schema and database calls establish a direct dependency on Convex’s component contract. (.agents/skills/convex-create-component/SKILL.md:96, 5490214d1e74)
• Official component boundary documentation: Convex’s authoring documentation confirms that components have isolated tables, their own generated function builders, and distinct ID namespaces. The documentation source repository was not established.
• Current-main necessity: Current main retains the earlier schema-validator example and synchronization state with agentSkillsSha 6843b65f3cbcee34bb2bc984d444f42ac7ca2a61; the gateway and framework-guidance updates also remain absent. (convex/_generated/ai/ai-files.state.json:5, 91aecdc22c53)
• Release and related-update check: The v0.23.3 state records an earlier, different guidance snapshot. GitHub confirms [automation] Update Convex AI files #3443 merged an earlier refresh; it does not establish implementation of this update. (convex/_generated/ai/ai-files.state.json:5, 87ca030c30f3)

Likely related people:

• Patrick-Erichsen: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Correct the import, handler argument, and schema assumptions, then typecheck the complete example against the documented component schema.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (146 earlier review cycles; latest 8 shown)

• reviewed 2026-09-03T18:44:49.885Z sha 94218ea :: blocked before merge. :: [P2] Import internalQuery before using it | [P2] Receive args in the notification handler | [P2] Include pre-1.45 Cloud deployments in the fallback
• reviewed 2026-09-03T19:31:22.492Z sha 94218ea :: blocked before merge. :: [P2] Import internalQuery before using it | [P2] Receive args in the notification handler | [P2] Route pre-1.45 Cloud deployments to the fallback
• reviewed 2026-09-03T21:41:14.847Z sha 94218ea :: blocked before merge. :: [P2] Import internalQuery before using it | [P2] Receive args in the notification handler | [P2] Route pre-1.45 Cloud deployments to the fallback
• reviewed 2026-09-03T22:41:01.064Z sha 94218ea :: blocked before merge. :: [P2] Import internalQuery before calling it | [P2] Accept the declared args parameter | [P2] Include pre-1.45 Cloud deployments in the fallback
• reviewed 2026-09-04T04:52:36.792Z sha 94218ea :: blocked before merge. :: [P2] Import internalQuery before calling it | [P2] Receive the declared id argument in the handler | [P2] Include pre-1.45 Cloud deployments in the fallback
• reviewed 2026-09-07T07:27:58.746Z sha 4118af5 :: needs changes before merge. :: [P2] Import the new internalQuery builder | [P2] Receive the declared argument in the notification handler
• reviewed 2026-09-11T18:38:17.023Z sha 4118af5 :: needs changes before merge. :: [P2] Import the new internalQuery builder | [P2] Receive the declared argument in the notification handler | [P2] Keep the example compatible with the documented component schema
• reviewed 2026-09-14T07:33:03.923Z sha 5490214 :: needs changes before merge. :: [P2] Import the new internalQuery builder | [P2] Receive the declared argument in the notification handler | [P2] Keep the lookup compatible with the documented component schema