feat: allow official skill card uploads

[Patrick-Erichsen]

Summary

• allow official org publishers to publish a bundled root skill-card.md
• keep generated Skill Cards as the default for non-official publishers and for official publishes without a bundled card
• teach card, verify, public metadata, and CLI publish paths to preserve/trust bundled cards only for official org cases

Tests

• bunx vitest run -c vitest.config.ts convex/lib/officialPublishers.test.ts convex/lib/skillPublish.test.ts convex/lib/skillCards.test.ts convex/skillCards.test.ts convex/httpApiV1.handlers.test.ts
• bunx vitest run -c vitest.config.ts src/cli/commands/publish.test.ts src/cli/commands/sync.test.ts
• bun run format:check -- docs/quickstart.md docs/cli.md convex/lib/officialPublishers.test.ts convex/lib/skillPublish.test.ts convex/lib/skillCards.test.ts convex/skillCards.test.ts convex/httpApiV1.handlers.test.ts packages/clawhub/src/cli/commands/publish.test.ts packages/clawhub/src/cli/commands/sync.test.ts
• bun run lint -- docs/quickstart.md docs/cli.md convex/lib/officialPublishers.test.ts convex/lib/officialPublishers.ts convex/lib/skillPublish.test.ts convex/lib/skillPublish.ts convex/lib/skillCards.test.ts convex/lib/skillCards.ts convex/skillCards.test.ts convex/skillCards.ts convex/httpApiV1.handlers.test.ts convex/httpApiV1/skillsV1.ts convex/skills.ts packages/clawhub/src/cli/commands/publish.test.ts packages/clawhub/src/cli/commands/publish.ts packages/clawhub/src/cli/commands/sync.test.ts
• bunx tsc --noEmit
• bunx tsc -p packages/clawhub/tsconfig.json --noEmit

Notes

Autoreview initially caught two gaps: bundled cards needed to be readable from /card//verify, and the CLI should not preserve root skill-card.md for ordinary owner publishes. Both are fixed here. A final autoreview rerun wedged emitting only model warnings, so I killed the stuck process after the targeted gates passed.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clawhub	Ready	Preview, Comment	May 31, 2026 4:01pm

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed May 31, 2026, 12:06 PM ET / 16:06 UTC.

Summary
The PR lets allowlisted official org publishers preserve and publish a root skill-card.md, then teaches publish, Skill Card generation, /card, /verify, public metadata, and CLI paths to trust that card only for official org cases.

Reproducibility: not applicable. as a bug reproduction; this is a feature PR. Source inspection confirms current main rejects direct skill-card.md publishes, while the PR tests model the new official-org cases.

Review metrics: 1 noteworthy metric.

• Changed surface: 16 files, +541/-51. The diff spans backend publish validation, public API card verification, generation queue behavior, CLI upload packaging, docs, and tests.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🦐 gold shrimp
Result: blocked until real behavior proof from a real setup is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted terminal output or logs for an official org publish that preserves skill-card.md and a community publish that rejects or strips it.
• Update specs/official-publishers.md and the public /verify or /card docs to describe official-org supplied trusted Skill Cards.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists test and typecheck commands, but does not include real after-fix terminal output, logs, or artifacts showing an official org publish and /card or /verify readback; add redacted proof before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

• [P1] The PR intentionally broadens a security-sensitive trust boundary: official org supplied skill-card.md can satisfy /verify and public card reads, so the durable policy/spec and API docs need to match before merge.
• [P1] The CLI now preserves any root skill-card.md for openclaw and nvidia owner publishes; maintainers should explicitly accept that existing official-owner workflows with downloaded/generated cards will no longer strip that file.
• [P1] Contributor real behavior proof is missing, so reviewers cannot yet see an actual official org publish and readback path working outside mocks/tests.

Maintainer options:

1. Document and prove the trust contract (recommended)
   Update the durable spec and public API docs for official supplied Skill Cards, then add redacted real publish plus /card or /verify proof before merge.
2. Accept official-owner preservation semantics
   Maintainers may intentionally accept that openclaw and nvidia CLI publishes now preserve any root skill-card.md instead of stripping it as generated output.
3. Pause for a policy split
   If uploaded official Skill Cards need an explicit flag or server-advertised capability rather than owner-handle detection, pause this PR for product/API direction.

Next step before merge

• [P1] Human review is needed because only the contributor can supply real behavior proof from their setup, and maintainers should explicitly accept the official-card trust and compatibility contract.

Security
Needs attention: The code keeps the new trust path server-gated to allowlisted org publishers, but the security contract is not yet persisted in specs/API docs.

Review findings

• [P2] Document the trusted official-card contract — convex/httpApiV1/skillsV1.ts:1597-1602

Review details

Best possible solution:

Land this only after the official-org-only trusted-card contract is recorded in specs/API docs and the contributor adds redacted real publish/readback proof for both accepted official and rejected or stripped community cases.

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

Not applicable as a bug reproduction; this is a feature PR. Source inspection confirms current main rejects direct skill-card.md publishes, while the PR tests model the new official-org cases.

Is this the best way to solve the issue?

Partly: the server-side official-org gate is the right narrow boundary, but the solution is incomplete until the trust contract is documented and proven in a real publish/readback setup.

Full review comments:

• [P2] Document the trusted official-card contract — convex/httpApiV1/skillsV1.ts:1597-1602
  This makes a publisher-supplied skill-card.md count as available for /verify when the owner is an allowlisted org, but the public API docs still say ok requires a generated Skill Card and specs/official-publishers.md still lists only UI/channel effects. Since this changes upload gating and an API trust boundary, update the durable spec and public docs with the official-org-only trusted-card rule before merge.
  Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.76

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9fc2da4dc437.

Label changes

Label changes:

• add P2: This is a normal-priority feature with a limited but security-sensitive publishing and verification blast radius.
• add merge-risk: 🚨 compatibility: Merging changes CLI packaging behavior for existing official-owner publishes that contain a root skill-card.md.
• add merge-risk: 🚨 security-boundary: Merging changes which uploaded content can be trusted by /verify and Skill Card readers.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists test and typecheck commands, but does not include real after-fix terminal output, logs, or artifacts showing an official org publish and /card or /verify readback; add redacted proof before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P2: This is a normal-priority feature with a limited but security-sensitive publishing and verification blast radius.
• merge-risk: 🚨 security-boundary: Merging changes which uploaded content can be trusted by /verify and Skill Card readers.
• merge-risk: 🚨 compatibility: Merging changes CLI packaging behavior for existing official-owner publishes that contain a root skill-card.md.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body lists test and typecheck commands, but does not include real after-fix terminal output, logs, or artifacts showing an official org publish and /card or /verify readback; add redacted proof before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence reviewed

Security concerns:

• [medium] Trusted-card policy is undocumented — convex/httpApiV1/skillsV1.ts:1597
  The PR broadens verification from generated cards to official org supplied cards, while the durable official-publisher spec and public /verify docs still describe the older generated-card-only contract.
  Confidence: 0.82

What I checked:

• Current-main behavior: Current main rejects any publish payload containing a root Skill Card, so the PR is adding a new capability rather than fixing an already-implemented path. (convex/lib/skillPublish.ts:155, 9fc2da4dc437)
• PR trust-boundary change: The PR changes /verify to treat a selected card as available when selectTrustedSkillCardFile accepts publisher-supplied cards for an official org publisher. (convex/httpApiV1/skillsV1.ts:1597, 47bdad288c46)
• Durable intent gap: The PR head still has public API docs saying /verify passes only with a generated Skill Card, which no longer matches the new official-supplied-card behavior. (docs/http-api.md:382, 47bdad288c46)
• Official-publisher policy context: The existing spec says the official policy signal appears in publisher/profile UI and owned package UI; it does not record official org Skill Card upload trust. (specs/official-publishers.md:16, 9fc2da4dc437)
• Proof assessment: The PR body lists unit/static/typecheck commands, but the discussion does not include terminal output, logs, linked artifacts, or other real setup proof for an official org publish plus /card or /verify readback.
• Ownership history: Blame and log show the current official publisher policy originated in 90de729f..., NVIDIA allowlist work in 9a20795b..., and Skill Card/publish helpers in the v0.18.0 release baseline. (convex/lib/officialPublishers.ts:10, 90de729fe135)

Likely related people:

• Patrick Erichsen: Recent current-main history includes the Skill Card/publish helper baseline, NVIDIA official-publisher allowlist work, and the reusable skill publish workflow touched by this PR. (role: recent area contributor; confidence: high; commits: 875f026a2300, 9a20795b5432, 6fc5bb7cd80f; files: convex/lib/skillCards.ts, convex/lib/skillPublish.ts, convex/lib/officialPublishers.ts)
• Jesse Merhi: Blame shows the simplified official publisher policy file was introduced in commit 90de729f..., which is central to deciding who may supply trusted cards. (role: official-publisher policy introducer; confidence: medium; commits: 90de729fe135; files: convex/lib/officialPublishers.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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