th-7f1da8: Presence glow-up + CLI spec — branded help, ai explainer, --json conformance - #491
Merged
Conversation
…--json conformance Bare 'th --help' now renders a branded grouped map (wordmark gradient, 7 sections, teal literals, dimmed blurbs) with a two-way sync test pinning it to the clap tree; --help-full keeps the native view and all per-command help is themed via clap styles. Pipe/NO_COLOR = plain text. Append 'ai' to any command path (smoo org ai, th ai) for a generated markdown guide: about, subcommands, flags, curated examples, and the house conventions — built for humans and AI agents, zero per-module maintenance. docs/Engineering/CLI-Spec.md codifies the interface contract (noun-verb, standard verbs/flags, output rules, Presence color rules, preview-first writes). New conformance test enforces --json on every platform list verb — found 19 violations, all backfilled (lane w7), including a real bug: jobs list sent organization_id where the API wants organizationId, so the org filter always 400'd. Gates: 760 tests green, clippy 0 errors, fmt clean. Rendered live on a TTY (tmux capture) + verified NO_COLOR/piped output is escape-free. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
brentrager
enabled auto-merge (squash)
August 20, 2026 17:09
🦋 Changeset detectedLatest commit: 376bf66 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
th --helpwall of white text becomes a branded map, the interface contract gets codified and test-enforced, and every command grows an AI-ready explainer.What changed
th --helprenders the wordmark (teal→blue gradient, reserved per Presence) + 7 grouped sections with teal command literals and dimmed blurbs. A two-way sync test pins the curated groups to the clap tree — add a command without adding it to a section and CI fails.th --help-fullkeeps the native flat tree; all per-command help themed via clapstyles(bold headers, teal literals). Pipe andNO_COLORoutput verified escape-free.aiexplainer: appendaito any command path —smoo org ai,th pearls ai, bareth ai— for generated markdown (about, subcommands incl. aliases, flags, curated examples, house conventions). Generated from the clap tree, so new commands appear automatically; only the examples table is curated.docs/Engineering/CLI-Spec.md: the codified contract — noun-verb shape, standard verbs (list/show/create/update/rm/search), standard flags (--jsonon every read,--org-id/--org,--confirmfor send/spend/destroy), output rules (empty = confirmed answer, truncation reported, two-line errors, results-on-stdout), Presence color rules, and the add-a-surface checklist.spec_every_platform_list_has_jsonwalks the smoo tree and fails on anylistwithout--json. It found 19 violations, all backfilled — plus a real bug it flushed out:smoo api jobs list --org-idsentorganization_idwhere the API wantsorganizationId, 400ing every filtered call.Verification
760 tests green (sync test, ai-explainer resolution incl. aliases, conformance, parse tests per backfilled module), clippy 0 errors, TTY render captured via tmux,
NO_COLOR/piped output byte-checked for escapes, three backfilled verbs live-smoked as valid JSON against the real org.🤖 Generated with Claude Code