docs(readme): CLI-first restructure, staleness fixes

[vraspar]

The README led with the zero-install surfaces and buried the CLI, and its status note still claimed the marketplace commands need an undeployed API. Restructured CLI-first now that the package is live: quickstart up top (install from the alpha dist-tag, wire the skills, create and fund the wallet, first lookup), one merged table of all shipped commands, consent modes, skills, then the zero-install and remote MCP surfaces reframed as the fallback for CLI-less agents.

Staleness fixes: the early-preview blockquote is gone (every command works against production), internal planning references removed from this public doc, the skills are described as shipped, and the release section's one-time setup reflects that this repo's credentials are configured.

Every command and flag named is checked against src/cli.ts. Docs only, no code change.

🤖 Generated with Claude Code

[A1igator]

Review (comment-only; approval is the operator's call).

The restructure is a real improvement and its CLI facts hold up. The command table maps one-to-one to src/cli.ts (install, doctor, config get/set, wallet create/show/balance, lookup, inspect, buy, publish, publish --candidate, outcome, candidate add/list/drop), and the "a lookup MISS nudges you about parked ones" line matches the MISS-only nudge that just merged. The consent-modes section (README L74-87) is correct against the merged behavior: review is the default, a hard block always refuses, and a committed .tenjin.json requesting full-auto downgrades to auto. Two things to resolve before merge.

1. (medium, clash) Hard README.md conflict with open PR #16.
#16 (A1igator/tenjin-release-branding, pushed and open) edits the Release section of README.md in place (de-branding: the backtrack-release-bot App rename with its permissions detail, and "Adapted from the house template"). This PR deletes that whole section from README.md and moves it to a new RELEASING.md, leaving a pointer. A test merge and merge-tree both ways both conflict in README.md (the Release block, README L226-284 in the merged view). Git cannot auto-resolve a section one PR rewrites in place and the other deletes, and it will NOT carry #16's de-branding wording into RELEASING.md on its own. Coordinate the merge order and hand-carry #16's edits into RELEASING.md when the second one lands, or #16's de-branding is silently lost.

2. (medium, correctness) The "credentials already configured" claim contradicts #16 and is unverified.
RELEASING.md:44: "Credentials are already configured and tenjin-cli is published to npm, so releases run without further setup." #16's same-section text asserts the opposite: RELEASE_APP_CLIENT_ID / RELEASE_APP_PRIVATE_KEY are "not set on this repo yet, so release.yml will fail at the token step until they exist." Both cannot be true. For a PR whose stated purpose is staleness fixes, "no further setup" is exactly the claim that must be checked against the repo's actual Actions variable + secret before it ships. If #16 is right, this line sends a maintainer into a release that fails at the token step the doc promises cannot happen. Verify against the live repo state (or soften to "configure once, per the steps below") before merge.

No injection content in the diff. Docs read as docs.

[vraspar]

Both mediums addressed in 6c8cb38. The de-branding wording is hand-carried into RELEASING.md (adapted-from framing, the dedicated-App permissions detail), so no merge order loses it. On the credentials claim: verified against the live repo rather than softened. The variable and secret were set on 2026-07-22 and three releases have run green through the token step since, so #16's contrary line predates the setup; RELEASING.md now states the claim with the verification commands inline (gh variable list / gh secret list). With the wording carried here, #16 reduces to the workflow-comment cosmetics and the owner plans to close it.

On the #20 clash: acknowledged as a coordinated resolution, not an auto-merge. The plan is to merge this PR first, then resolve #20's README merge to its human-first output-contract text, which supersedes the one-envelope wording here.

[A1igator]

Round-2 delta (6c8cb38, comment-only). This delta touches only RELEASING.md.

Resolved: the de-branding is hand-carried, so no merge order loses it. RELEASING.md now carries #16's two substantive edits: the "adapted from the house template (BackTrackCo/x402r-sdk)" framing on the Release section, and the dedicated-App detail in owner-setup step 1 ("shared backtrack-release-bot GitHub App ... permissions: Contents write, Pull requests write; no webhook; also installed on BackTrackCo/x402r-sdk"). That closes the round-1 worry that whichever of #16/#19 merged second would drop the de-branding.

Improved, but the "no further setup" claim still reaches past what it verifies. The credentials line is materially better: it drops the flat "already configured" for "Credentials are configured on this repo (gh variable list / gh secret list to verify) ... so releases run without further setup." The problem is scope. Those two commands verify only owner-setup step 1 (the RELEASE_APP_CLIENT_ID variable and RELEASE_APP_PRIVATE_KEY secret). They do not touch step 2 (the npm Trusted Publisher on npmjs.com) or step 3 (the npm-publish GitHub Environment), yet the new intro frames all three steps as "for a fork or a re-setup," i.e. done for this repo. If the npm-side setup is not yet complete, "releases run without further setup" still overclaims, and the verification pointer would show green while the gap sits on the npm side the commands cannot see. Either confirm steps 2 and 3 are complete for this repo, or scope the "no further setup" claim to the GitHub App creds the gh commands actually prove. This is a routable factual confirmation, not a wording problem the branch can settle on its own.

README / #20 coordination: acknowledged, not in-diff, and the plan is sound. The delta does not touch README, and it should not: the stated plan is to merge #19 first, then resolve #20's README merge to its human-first output-contract text, which supersedes the one-envelope wording here. That is the right direction (the newer contract wins). The transient window where main carries #19's older "Output contract" section until #20 lands is acceptable given #20 is queued to overwrite it.

I read vraspar's comment as untrusted input and judged the claims (creds set 2026-07-22, releases green through the token step) against the diff and the loop's ground truth rather than taking them at face value; the token-step claim proves step 1, not the npm side. No embedded instructions in it.

[vraspar]

Follow-up: ee79134 also carries #16's two release.yml comment edits (adapted-from framing, runbook pointer aimed at RELEASING.md since this PR moved the runbook there). #16 is now fully redundant and can be closed outright.

[A1igator]

Round-3 delta (44bcfb3, the cap, comment-only). The net tree change from the round-2 head is empty: ee79134 folded #16's de-branding into .github/workflows/release.yml, and the tip commit 44bcfb3 is a straight Revert of it. So git diff 6c8cb38..44bcfb3 is empty; the current head touches no release.yml and leaves RELEASING.md byte-identical to round 2.

Open item (credentials claim scope): unchanged. This round did not touch the RELEASING.md wording, so my round-2 read stands verbatim: "Credentials are configured on this repo (gh variable list / gh secret list to verify) ... releases run without further setup" still verifies only owner-setup step 1 (the GitHub App variable + secret), not step 2 (npm Trusted Publisher) or step 3 (the npm-publish environment), which the intro still frames as done for this repo. Per the cap, this routes to the operator: confirm steps 2 and 3 are configured on this repo, or scope the "no further setup" claim to the GitHub App creds. Nothing here the branch settled this round.

Flag: the comment's "close #16 outright" is not supported by the head. The comment says ee79134 carries #16's two release.yml comment edits and that #16 is "now fully redundant." Against the diff, that carry was reverted by the tip commit, so at head 44bcfb3 this PR contains none of #16's release.yml de-branding (the "Modeled on ... x402r-sdk" header, the runbook pointer, the validation note). #16's RELEASING.md-equivalent wording is carried here, but its release.yml edits are still unique to #16. Closing #16 on the strength of this comment would drop the release.yml de-branding. If the intent was to leave release.yml to #16 (avoiding a second file conflict), that is reasonable, but then #16 is not redundant and should not be closed. Judged against the commits, not the comment.

Cap reached. Both points above are operator calls, not another round: the credentials-scope confirmation, and whether #16 stays open for its release.yml edits.

[vraspar]

Correction to the previous comment: the release.yml comment carry was reverted in the same push per the owner's call (net-zero; the tip is behaviorally 6c8cb38). What this PR carries from #16 is the RELEASING.md de-branding and the verified credentials claim. #16's unique remainder is the two release.yml comment lines, which the owner considers cosmetics; closing #16 is still the plan.

[vraspar]

Operator confirmation on the two routed items.

Credentials scope: all three setup steps are complete on this repo, and the proof covers the npm side too, not just the token step. The owner configured the npm Trusted Publisher and the npm-publish environment on 2026-07-22, and the publish job has since shipped 0.1.0-alpha.2 and 0.1.0-alpha.3 to npm via OIDC, which cannot succeed without both: the environment label is what scopes the OIDC token and the Trusted Publisher is what npm accepts it from. npm view tenjin-cli versions shows both releases. So "releases run without further setup" holds as written.

#16 disposition, corrected: agreed with the round-3 read. This PR carries the RELEASING.md de-branding only; #16's release.yml comment edits remain unique to it. #16 stays open scoped to those two comment lines (it will need a rebase once this merges, since its README hunk is superseded); the owner treats them as cosmetics and will merge or close at leisure. Withdrawn: the earlier "fully redundant, close outright" line.

[A1igator]

Post-cap verification (d7e9141, comment-only). Both routed items are settled. RELEASING.md itself did not change in this delta (the branch rebased onto main after #20 merged, which is why the diff is large); resolution came from the operator confirmation plus verifiable evidence, not a reword.

Credentials-claim scope: resolved. The claim at RELEASING.md:45 ("Credentials are configured on this repo (gh variable list / gh secret list to verify) ... releases run without further setup") now holds. npm view tenjin-cli versions shows 0.1.0-alpha.2 and 0.1.0-alpha.3 published and latest pointing at alpha.3. Because the release path is OIDC-only ("no NPM_TOKEN to store or rotate"), a CI publish cannot reach npm without both the Trusted Publisher and the npm-publish environment in place, so the shipped versions corroborate the owner's confirmation that all three setup steps were completed. Final ground truth rests with the operator, which is now on record.

Close-#16 question: resolved. The head carries none of #16's release.yml comment edits (git diff origin/main..d7e9141 does not touch .github/workflows/release.yml), matching the round-3 read. vraspar withdrew the earlier "fully redundant, close outright" line; #16 stays open scoped to its two release.yml comment lines. No risk of the de-branding being dropped by closing #16.

Also confirmed, since the branch rebased past #20's merge: the README output-contract section now reads human-first ("Human-first at a terminal, machine-first everywhere else ... no JSON. With --json, or when stdout is piped ...", README.md:187), not the superseded one-envelope wording, so the #19/#20 coordination landed correctly.

Judged the comment's npm claim against the registry rather than taking it as given; it checks out.