feat(cli): polish terminal branding

[vyctorbrzezowski]

Summary

This PR is a focused CLI polish pass for ClawHub's terminal surface. It keeps command behavior intact while making the output feel branded, intentional, and easier to scan.

• Adds red ClawHub help styling, grouped command sections, and the lobster header for help output.
• Replaces generic spinners with the ClawHub crab loader across the skill/package/moderation CLIs.
• Polishes skill install/update/uninstall/search/explore/package listing output with clearer contrast and spacing.
• Reworks inspect into a structured terminal card with readable UTC dates.
• Reworks sync with the large red ClawHub banner, centered ClawHub // sync tagline, section rails, selected/upload sections, and calmer spacing.
• Extends search responses with optional downloads so CLI search can show downloads instead of score when the registry supports it; older registries still fall back to score.

Scope note

This is cosmetic/branding polish plus the optional search downloads field needed for the CLI display. The old clawhub help / unknown-root-command behavior is handled separately in #2433 and is not part of this PR's claim.

Visual proof

Full gallery: https://stellar-yarrow-9yhz.here.now/

clawhub --help

clawhub inspect weather

clawhub search weather --limit 5

clawhub explore --limit 5

clawhub package explore --limit 5

clawhub install weather --force

clawhub update --all --no-input --force

clawhub uninstall weather --yes

clawhub sync --dry-run --all

Validation

• git diff --check
• bunx vitest run src/cli/ui.test.ts src/cli/commands/skills.test.ts src/cli/commands/packages.test.ts src/cli/commands/sync.test.ts src/cli/commands/inspect.test.ts src/schema/schemas.test.ts from packages/clawhub
• bunx vitest run packages/schema/src/schemas.test.ts convex/httpApiV1.handlers.test.ts
• bunx tsc --noEmit
• bunx tsc -p packages/schema/tsconfig.json --noEmit
• bunx tsc -p packages/clawhub/tsconfig.json --noEmit
• bunx vitest run -c vitest.artifact.config.ts test-artifact/cli.artifact.test.ts from packages/clawhub
• bun run --cwd packages/clawhub build
• bun run ci:packages
• bun run ci:static
• codex review --uncommitted once; completed with exit code 0

[vercel]

@vyctorbrzezowski is attempting to deploy a commit to the Amantus Machina Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 29, 2026, 12:56 PM ET / 16:56 UTC.

Summary
The branch restyles ClawHub CLI help, loaders, search, explore, install, update, uninstall, inspect, sync, package, and moderation output while adding an optional downloads field to API v1 search schemas and responses.

Reproducibility: not applicable. this is a CLI polish PR, not a bug report. The inspected before/after screenshots provide behavior proof for the changed terminal output instead of a failing current-main reproduction.

Review metrics: 2 noteworthy metrics.

• Touched surface: 34 files, +595/-198. The PR is a broad CLI presentation pass plus an additive search response field, so maintainers should review the full terminal surface rather than a single command.
• Visual proof: 9 before/after screenshots. The PR body's screenshot gallery directly covers the visible CLI formatting changes that tests cannot fully show.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

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

Next step before merge

• [P2] No repair lane is needed because the reviewed diff has no actionable correctness finding; the remaining action is maintainer approval and normal merge gating.

Security
Cleared: No concrete security or supply-chain concern was found; the diff does not add workflows, dependencies, secrets handling, package publishing metadata, or third-party code execution paths.

Review details

Best possible solution:

Land the polish if maintainers want this branded terminal direction, keeping the optional downloads field backward-compatible and covered by the included CLI, schema, API, artifact, build, and static checks.

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

Not applicable; this is a CLI polish PR, not a bug report. The inspected before/after screenshots provide behavior proof for the changed terminal output instead of a failing current-main reproduction.

Is this the best way to solve the issue?

Yes; the patch keeps command behavior and API response compatibility intact while focusing changes on CLI formatting, schema, generated schema output, and targeted tests. The remaining decision is whether maintainers want this terminal branding as the default.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 309723f7a863.

Label changes

Label justifications:

• P3: This is low-risk CLI presentation polish and an additive optional API field, with limited urgency and no data/security regression reported.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes an inspected screenshot gallery showing after-change real CLI help, search, sync, and related terminal output, which directly proves the visible behavior changed by this PR.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes an inspected screenshot gallery showing after-change real CLI help, search, sync, and related terminal output, which directly proves the visible behavior changed by this PR.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes an inspected screenshot gallery showing after-change real CLI help, search, sync, and related terminal output, which directly proves the visible behavior changed by this PR.

Evidence reviewed

What I checked:

• Repository policy read: The full target AGENTS.md was read before review; its CLI validation, source/dist schema, Convex, and visual proof guidance shaped the review. (AGENTS.md:1, 309723f7a863)
• Convex guidelines read: Because the PR touches Convex HTTP API code, the repo-local Convex AI guidelines were inspected before reviewing that path. (convex/_generated/ai/guidelines.md:1, 309723f7a863)
• CLI polish diff inspected: The PR diff adds grouped help, styled errors, explicit help command support, and command help grouping in the CLI entrypoint. (packages/clawhub/src/cli.ts:51, 4a83cfe6227c)
• Search response compatibility inspected: The PR adds downloads as an optional search response field, and current main's public skill projection already canonicalizes stats from top-level stat fields before exposing skill.stats. (convex/lib/public.ts:120, 309723f7a863)
• Visual proof inspected: Downloaded and inspected the PR's before/after screenshots for help, search, and sync; they show the visible terminal output changes claimed by the PR. (4a83cfe6227c)
• Area history sampled: Git history on CLI, API, schema, and stat helper paths points to recent area contributors for routing without changing the merge verdict. (309723f7a863)

Likely related people:

• Patrick Erichsen: Recent history shows Patrick carrying the current CLI release base plus adjacent API/schema/security changes on the paths touched by this PR. (role: recent area contributor; confidence: high; commits: 875f026a2300, ff48b2cc7020, 57bc9f2a461e; files: packages/clawhub/src/cli/ui.ts, packages/clawhub/src/cli.ts, convex/httpApiV1/skillsV1.ts)
• Vyctor H. Brzezowski: Current main includes Vyctor's merged CLI command-handling work in packages/clawhub/src/cli.ts and a recent API guard change in convex/httpApiV1/skillsV1.ts. (role: recent CLI/API contributor; confidence: high; commits: 309723f7a863, 97023d3123f4; files: packages/clawhub/src/cli.ts, convex/httpApiV1/skillsV1.ts)
• Momo: Momo introduced the readCanonicalStat/stat migration helper used as review context for the added downloads response field. (role: stat migration contributor; confidence: medium; commits: 530e39eedc70; files: convex/lib/skillStats.ts, convex/schema.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.

[vyctorbrzezowski]

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

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26607810960
• Updated: 2026-05-28T23:20:58.501Z