Skip to content

docs pass: README, SKILL.md, MCP README and --help tell one story (claimed, badge-only proof, person reviews, claim --check records proof) - #32

Merged
HeyGarrison merged 14 commits into
mainfrom
devin/1792542699-docs-pass
Oct 21, 2026
Merged

HeyGarrison merged 14 commits into
mainfrom
devin/1792542699-docs-pass

Conversation

@HeyGarrison

@HeyGarrison HeyGarrison commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Docs pass over everything a reader of this repo meets — root README.md, packages/cli/README.md, packages/mcp/README.md, skills/rgstr/SKILL.md and every command's --help — so they say the same thing as each other, as the code, and as rgstr.org after computesdk/benchmarks-platform#807: the README badge is the only proof, every claim is an application a person reviews (a found badge is evidence, not approval), claim --check is not a read (it records the proof for the claim you filed), "verified" is paid identity verification only, "organization" never "org", rgstr setup with use as the hidden alias.

Branched off main with the branch of #31 (devin/1792533348-rgstr-mcp) merged in first, so this reads as post-merge. Files #31 owns are touched only where the docs pass needed it: one output string in packages/mcp/src/server.ts ("already under review or verified" → "or claimed") and the rgstr_claim_check row in packages/mcp/README.md. CHANGELOG.md untouched; a changeset (.changeset/docs-pass-one-story.md, patch for both packages) covers the user-visible wording changes.

skills/rgstr/SKILL.md and the platform's lib/registry/skill.ts mirror changed together (byte-equal) — the platform PR carries the mirror.

What was wrong → what it says now

packages/cli/README.md

Was Now
"One name, every ecosystem. … look-alikes, hijacked forks and squatted copies get folded under it or flagged." "rgstr is a package name registry over npm and PyPI: claim the name of a package you maintain, prove it with the rgstr badge in your README, and a person reviews the claim."
"rgstr claim --check is read-only: it tells you which README the badge was found in." "looks for the badge in the README rgstr reads and records it for the claim you filed — it files nothing new and writes no files, but it is not a read. A person then approves the claim."
--here "which verifies on the next publish" "rgstr reads it from the published package on the next publish"
whois: "(unclaimed / claimed / verified) … whether it is disputed" "(unclaimed / claimed / verified — claimed plus paid identity verification) … whether a claim is under review" (disputes are not public)
login: "packages and organization read, nothing else" "packages read and write, organization read, nothing else" (RGSTR_OAUTH_SCOPE)
Proof table column "When it verifies" / "When the PR is merged" "When rgstr reads it" / "After the pull request merges (rgstr claim --check)"; new paragraph: a found badge is evidence, a person reviews every claim; "verified" is paid identity verification on top of a claim
"rgstr reads the badge off GitHub and the name is yours" "rgstr reads the badge off GitHub and attaches it to your application; a person approves the claim"
"The only proof that you own a name" "…that you maintain a name"
npx @rgstr/cli claim npx @rgstr/cli@latest claim (as the root README and the skill)

skills/rgstr/SKILL.md (served at rgstr.org/skills/rgstr/SKILL.md)

Was Now
Rules: reading needs no confirmation (nothing about claim --check) "+ claim --check is not a read: it records the proof for a claim the user already confirmed."
MCP: "rgstr_claim_check records the proof and can complete the claim." "rgstr_claim_check is claim --check: it records the proof for a filed claim, so it is not a read."
Step 4: "which can complete that claim: <name>: verified via … means it is in" "<name>: proof found via … means the badge is attached to the application"
Step 5: "A person reviews the claim." "A person reviews every claim; a found badge is evidence, not approval."
whois: "its trust (unclaimed / claimed / verified)" "+ — claimed plus paid identity verification"

packages/mcp/README.md

Was Now
rgstr_claim_check "looks for the badge; records the proof, can complete the claim" "rgstr claim --check: looks for the badge and records the proof for a filed claim; a person then approves"

--help (packages/cli/src/index.ts) and CLI output

Was Now
rgstr — claim, verify and route package names rgstr — claim, prove and route package names
--check: "look for the proof: the badge in the repo README on GitHub, or in the README of the published package" "+ and record it for the claim you filed; a person then approves"
--here: "it then verifies on the next publish (…) rather than on merge" "rgstr then reads it from the published package on the next publish rather than off GitHub after the merge"
claim --check output <name>: verified via … — … / Proof verified and attached to your application <name>: proof found via … — … / Proof found and attached to your application (claim-flow.ts)
<name>: verified — your organization (already) claims it. <name>: already claimed by your organization.
plan text "it verifies on the next publish to npm" (claim.ts, and its test) "rgstr reads it on the next publish to npm"
--here refusal "(verifies on the next publish)" "(rgstr reads it on the next publish)"
MCP plan "already under review or verified" (server.ts) "already under review or claimed"

Read, nothing to change

Root README.md; packages/mcp/README.md Configure / Login / plan→apply / plan_stale / Errors sections; packages/mcp/src/server.ts tool titles and descriptions; packages/cli/src/check.ts output; login / logout / whoami / org / status / whois / route / search / setup help text; rgstr use stays a hidden alias; CHANGELOG.md.

Checks

pnpm install (the packages/mcp node_modules were missing after the workspace move), then pnpm build && pnpm typecheck && pnpm lint && pnpm test: exit 0 — cli 106 tests, mcp 14.

Was flagged, fixed upstream

Link to Devin session: https://app.devin.ai/sessions/ab74b85cc8ad4981a5b7e9ea55d51490
Open in Devin Desktop: https://app.devin.ai/desktop/session/ab74b85cc8ad4981a5b7e9ea55d51490?variant=devin
Requested by: @HeyGarrison


Devin Review

…I errors print code + hint

- pnpm workspace: packages/cli (@rgstr/cli) and packages/mcp (@rgstr/mcp 0.0.1)
- claim, route and check flows moved out of index.ts into claim-flow.ts, route-flow.ts, check-flow.ts so the MCP server runs exactly the CLI's code
- RgstrApiError carries code, hint, requestId, details; the CLI prints the hint last, --json includes code/hint/requestId; claim --check reads 422 proof_not_found as 'no proof yet'
- MCP server: rgstr_whois/search/check, claim/setup/route plan+apply, rgstr_claim_check, rgstr_login; errors are isError results with the same envelope
- SKILL.md: MCP section + the errors rule; changesets for both packages
- rgstr_login no longer hangs when the device-code request fails before a prompt; after login the one organization becomes active (rememberOrganization, shared with rgstr login)
- stored plans remember the organization and host they were made for; apply refuses a different one
- rgstr_setup_apply plans again and refuses when the files changed since the plan
- isError text puts the envelope first so the hint is the last line, as in the CLI
…m (fingerprint includes the current file bytes)
…; a failed /api/v1/me after login forgets the stored organization

- rgstr_claim_apply / rgstr_setup_apply / rgstr_route_apply accept plan_id only; the name/raw-argument paths are gone
- claim plans carry a byte fingerprint of the READMEs they would edit (setup already did); a changed file, organization or host answers isError code plan_stale, hint "Run rgstr_<x>_plan again and show the user the new plan"
- rememberOrganization (rgstr login and rgstr_login): when /api/v1/me fails after approval, the remembered organization is cleared and the error says "Signed in, but no organization was selected; run `rgstr org use <slug>`" (no_organization)
- SKILL.md / README: no apply without a plan; plan_stale
… so rgstr_claim_apply can open the badge pull request
…med, badge-only proof, person reviews, claim --check records proof
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@devin-ai-integration devin-ai-integration Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👀 2 findings need your review

Devin reviewed all 2 findings on 99e1c08 and left them for you. Click a finding below to jump to its comment.

For your review (2)

View all findings in Devin Review

Devin Review

devin-ai-integration[bot]

This comment was marked as resolved.

- search: rgstr.owner is the organization's display name (a string); the CLI prints it again (test against the real API shape)
- rgstr_login tracks the outcome: call again for waiting / approved (and for which organization) / rejected / expired / failed with the next step; no_credentials hints mention the last login outcome; the flow is injectable for tests
- claim plans fingerprint the target manifests too (a renamed package is a new plan); route plans are pinned to the organization they were made for (plan_stale on mismatch)
…nization switch, search shows the organization
@devin-ai-integration

Copy link
Copy Markdown
Contributor

Fixed in #31 b8115607 (merged into this branch).

@devin-ai-integration

Copy link
Copy Markdown
Contributor

By design — see the #31 thread (forgetting a possibly foreign organization when /api/v1/me cannot say whose the login is).

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Devin Review found 1 potential issue.

Devin Review

Comment thread packages/mcp/src/server.ts Resolved
@devin-ai-integration
devin-ai-integration Bot marked this pull request as ready for review October 21, 2026 01:26
@HeyGarrison
HeyGarrison merged commit df90bab into main Oct 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant