Add gated Claw discovery and API projection

[giodl73-repo]

Summary - Adds feature-gated Claw list, search, package-detail, and version-detail APIs. - Fails closed while CLAWHUB_EXPERIMENTAL_CLAWS is disabled: explicit filters are rejected, unscoped results omit Claws, and named reads return not found. - Projects only bounded clawManifestSummary data; the version endpoint returns the summary for the requested release rather than the latest release. - Reuses existing visibility, channel, moderation, scan, and viewer-access rules. This is ClawHub PR 3 of 4 for OpenClaw RFC #27 and its registry package contract. ## Stack 1. #3089: schema and storage 2. #3090: gated publication 3. #3091: gated discovery APIs 4. #3092: hosted feed and OpenClaw bridge proof ## Real behavior proof Behavior or issue addressed: Published Claws can be discovered without exposing workspace instructions, MCP environment references, cron messages, package coordinates, or a full parsed manifest. Real environment tested: Windows 11 source worktree at a5e840893dbc, Bun 1.3.14, real public package/query and HTTP API handler test harnesses. Exact steps or command run after this patch: 1. bun run test -- convex/httpApiV1.handlers.test.ts convex/packages.public.test.ts -t Claw 2. bun x tsc --noEmit 3. bun run lint:oxlint Evidence after fix: text Test Files 2 passed (2) Tests 25 passed | 657 skipped (682) root typecheck: passed type-aware lint: passed Observed result after fix: Disabled reads fail closed across filtered, unfiltered, and named paths. Enabled detail and version responses contain only the bounded summary associated with the selected release. What was not tested: No live deployed HTTP endpoint; tests execute the real handler/query implementations with in-memory Convex contexts. ## Validation - 25 focused Claw discovery/API tests pass. - Schema build, root and CLI typechecks, type-aware lint, format, and git diff --check pass. This remains draft and depends on #3090.

[vercel]

@giodl73-repo is attempting to deploy a commit to the OpenClaw Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 19, 2026, 10:10 PM ET / July 20, 2026, 02:10 UTC.

Summary
The branch introduces an experimental gated claw package family with discovery, search, package/version API projections, CLI/schema support, tests, documentation, and a bounded clawManifestSummary public representation.

Reproducibility: not applicable. this is a new experimental discovery capability, not a report of broken established behavior. The supplied test harness covers intended paths but does not constitute a failure reproduction.

Review metrics: 2 noteworthy metrics.

• Effective stacked surface: 40 files affected; 4,893 additions and 75 deletions. The head includes schema, publication, discovery, CLI, docs, and generated package output, so it requires stack-aware review rather than treating it as a narrow API patch.
• Focused validation: 680 reported handler/query tests across 2 files. This gives useful regression coverage but remains test-harness evidence rather than live public-runtime proof.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
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 live Convex/HTTP evidence for gate-off and gate-on list/search/detail/version responses, including proof that the full manifest is absent.
• Obtain explicit maintainer sponsorship for the staged public claw API and compatibility boundary.
• Refresh review against the prerequisite publication slice once its direction is confirmed.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR provides passing in-memory Convex handler/query tests and build/typecheck output, but it explicitly lacks a live deployed or local runtime HTTP proof for disabled and enabled discovery behavior; add redacted live output 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] Merging creates a new public package family and API projection whose disabled/enabled behavior is an upgrade-sensitive registry contract; maintainers must explicitly sponsor the gate and future compatibility path.
• [P1] The supplied proof is limited to in-memory handler/query tests and build checks, so it does not yet demonstrate disabled and enabled discovery through a real Convex/HTTP runtime or verify the absence of full-manifest leakage on the wire.
• [P1] This branch is a stacked slice depending on the open publication work, so it should be evaluated and landed only in the declared schema → publication → discovery order.

Maintainer options:

1. Approve the experimental API boundary first (recommended)
   Confirm the gated claw family, response shape, and future ungating/compatibility plan before accepting this public registry surface.
2. Pause the stacked rollout
   Defer the branch until the RFC and prerequisite publication slice have maintainer sponsorship and a settled public contract.

Next step before merge

• [P1] The next action is maintainer sponsorship of the new public registry contract plus contributor-provided live behavior proof, not a narrow automated repair.

Maintainer decision needed

• Question: Should ClawHub adopt the proposed experimental public claw discovery contract and gate as the next sponsored stage of the Claw rollout?
• Rationale: The repository vision supports Claws, but this PR adds a durable public family/API contract and explicit deployment gating while the linked RFC and prerequisite publication slice remain open; implementation tests cannot establish that product and compatibility choice.
• Likely owner: afmire877 — Their merged work is the strongest supplied current-main provenance for package discovery semantics; final product sponsorship may require broader repository leadership.
• Options:
  • Sponsor the staged gated contract (recommended): Approve the schema, publication, discovery, and feed slices in order, keeping the gate and bounded public summary until a later compatibility decision removes it.
  • Narrow the discovery contract first: Ask for maintainer-defined list/search/detail/version guarantees before landing any public Claw discovery APIs.
  • Defer until the RFC is settled: Pause the stack until the open RFC confirms the registry-facing package and discovery contract.

Security
Cleared: No concrete security or supply-chain defect is evident in the supplied diff; the new public-manifest projection remains security-sensitive and needs runtime redaction proof before merge.

Review details

Best possible solution:

Sponsor the experimental Claw registry contract as a staged feature, retain the exact CLAWHUB_EXPERIMENTAL_CLAWS=1 compatibility boundary, and add a redacted live Convex/HTTP transcript covering disabled rejection, enabled list/search/detail/version responses, and full-manifest redaction before merge.

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

Not applicable: this is a new experimental discovery capability, not a report of broken established behavior. The supplied test harness covers intended paths but does not constitute a failure reproduction.

Is this the best way to solve the issue?

Unclear: feature-gating and bounded summaries are a sensible safety shape, but maintainers must first confirm that this is the intended public Claw discovery contract and then require live runtime proof of that contract.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against aaa73625ed41.

Label changes

Label changes:

• add merge-risk: 🚨 security-boundary: The change deliberately defines which portions of stored Claw manifests may cross the public discovery/API boundary, making serialization and gate behavior security-sensitive.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• remove rating: 🧂 unranked krab: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

• P3: This is an experimental, maintainership-dependent feature rollout rather than an active user-facing regression.
• merge-risk: 🚨 compatibility: The PR introduces a new public package family, query filter, CLI family value, and gated API response contract that callers may adopt.
• merge-risk: 🚨 security-boundary: The change deliberately defines which portions of stored Claw manifests may cross the public discovery/API boundary, making serialization and gate behavior security-sensitive.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A discoverable, inspectable personal-agent template registry directly advances ClawHub’s stated primary-product direction when backed by a maintainable public contract.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR provides passing in-memory Convex handler/query tests and build/typecheck output, but it explicitly lacks a live deployed or local runtime HTTP proof for disabled and enabled discovery behavior; add redacted live output 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

What I checked:

• Current main lacks the proposed feature: The current-main package implementation imports the established skill/plugin package validation and registry helpers but has no Claw-family or experimental-gate helper; the proposed convex/lib/experimentalClaws.ts does not exist on current main. (convex/packages.ts:1, aaa73625ed41)
• Vision alignment: The repository VISION.md calls Claws the primary product object and assigns ClawHub discovery, provenance, version metadata, and install resolution, so this is aligned with the intended product boundary rather than redundant work. (VISION.md:253, aaa73625ed41)
• Public contract is a staged dependency: The PR body and contributor updates identify this as the third slice after the open schema/publication work; the head contains the stacked commits for schema, publication, and discovery, so its public API contract needs an explicit staged-merge decision. (specs/claws.md:1, 3424d29a73cb)
• Proof remains harness-only: The contributor reports 680 passing handler/query tests and explicitly states that no live deployed HTTP endpoint was tested. This is useful validation but not after-fix real runtime proof for the new public discovery boundary. (convex/httpApiV1.handlers.test.ts:15680, 3424d29a73cb)
• Relevant prior discovery history: Public package-search behavior has prior merged history in the related search-token PR, making its author a plausible routing contact for discovery semantics; the Claw work itself remains unmerged and has no current-main feature owner trace available from the supplied checkout evidence. (convex/packages.ts:1, a16e62476675)

Likely related people:

• afmire877: Authored the merged public search-token matching change that is the closest supplied current-main provenance for package discovery semantics. (role: public-search behavior contributor; confidence: medium; commits: a16e62476675; files: convex/packages.ts)
• vincentkoc: Recent supplied repository history connects this person to package visibility, scanning, and public-registry safety work adjacent to the proposed gated discovery and redaction boundary. (role: adjacent package-security contributor; confidence: low; commits: 43d50b8; files: convex/packages.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.

Review history (2 earlier review cycles)

• reviewed 2026-07-16T11:27:36.436Z sha 9023abd :: needs real behavior proof before merge. :: none
• reviewed 2026-07-17T08:39:38.523Z sha 241db05 :: needs real behavior proof before merge. :: none

[giodl73-repo]

Restacked onto the refreshed publication slice (#3090) at 241db05. The fail-closed read/serializer boundary now lives in #3090; this PR is limited to enabled list/search/detail/version discovery and safe clawManifestSummary projection. Focused gate/package/HTTP/schema proof passes 680 tests, ci:types-build and ci:static pass, and Codex review of the effective stacked diff is clean. No reusable local Convex deployment was available, so the body retains that limitation and points to #3092 for the coordinated hosted-package/OpenClaw proof.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Restacked discovery onto refreshed #3090 at 8774028. Disabled list/search/named reads fail closed; enabled detail/version APIs expose only the bounded summary and strip the stored full manifest. The refreshed public/API suites pass 680 tests and the proof is in the PR body.

[giodl73-repo]

@clawsweeper re-review

[giodl73-repo]

Final discovery slice is restacked at 3424d29. Disabled list/search/named reads fail closed; enabled public responses expose only the bounded safe summary and never a full parsed manifest. Public/API tests (2 files, 680 tests), schema build, ClawHub typecheck, diff checks, and the final cumulative Codex review pass.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

[giodl73-repo]

Independent three-agent review fixes are applied at c2393ea11b56: version detail now returns the bounded clawManifestSummary for the requested release rather than the package's latest release, while disabled discovery continues to fail closed. Current-head proof: 25 focused Claw discovery/API tests plus typechecks, type-aware lint, format, and diff checks pass. RFC #27 and its sidecars are updated: openclaw/rfcs#27

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Exact-head CI update: the earlier Claws lint failure is fixed. pr-gates now reports type-aware Oxlint 0 warnings / 0 errors, then runs 4,871 passing unit tests before the unrelated src/__tests__/ui-design-contract.test.ts fails because node_modules/@openclaw/design-system/styles/tokens.css is absent. This stack does not modify that package, dependency, or test; downstream jobs mirror the failed aggregate gate. Local current-head Claws tests, build, typecheck, lint, format, and diff checks remain green.

[giodl73-repo]

Final exact-head correction: a5e840893dbc includes the regenerated schema distribution after the lint-only summary-binding rename; downstream commits were re-signed and restacked with no behavior change. The cumulative schema build is now clean with no generated-file drift.

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: Add gated Claw discovery and API projection This is item 1/1 in the current shard. Shard 6/8.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.