docs: README still offers @webjsdev/ui to non-WebJs projects, via a 404 command

[vivek7405]

Problem

The root README.md still advertises @webjsdev/ui to non-WebJs projects, which #1235 retired, using a command that does not work from the audience it names.

README.md L60 ends with:

It is auto-installed with @webjsdev/cli, and projects outside WebJs can use npx webjsui add button card dialog.

Two separate defects in that one clause.

1. It contradicts the scoping decision. #1235 (b0bc2742, feat!: scope @webjsdev/ui to WebJs apps, drop project detection) deleted detectProject() / defaultsForProject() and states that WebJs is the only host the kit is tested and supported on. It rewrote packages/ui/README.md accordingly: its Option B is now headed "the standalone binary" and framed as "a WebJs app that skipped the global install", not as a path for other frameworks. The root README kept the old framing, so the project's most-read surface still makes a claim the package deliberately dropped.

2. The command 404s from a clean project. npx webjsui ... resolves the PACKAGE name webjsui, and no such package is published (https://registry.npmjs.org/webjsui returns 404). The binary is declared inside @webjsdev/ui ("bin": {"webjsui": "bin/webjsui.js"}), so npx webjsui only works when @webjsdev/ui is already installed locally and npx resolves node_modules/.bin/webjsui. That is exactly the case the sentence excludes, since it addresses a project that has installed nothing. packages/ui/README.md gets this right by putting npm install -D @webjsdev/ui and npm install @webjsdev/core ahead of the two npx webjsui lines.

Found during the #1100 review cycle. The packages/ui/README.md half was fixed by #1235; the root README was missed.

Implementation plan

Decision: Rewrite the final clause of the root README.md UI bullet so it states the shipped reality from #1235, that the kit ships as a dependency of @webjsdev/cli and a WebJs app therefore installs nothing, and give the one zero-install fallback that actually resolves, npx webjsdev ui add button card dialog. The webjsdev wrapper is published (https://registry.npmjs.org/webjsdev returns 200), it declares a single bin so npx runs it by package name, and it depends on @webjsdev/cli, which resolves the webjsui bin from its own install. That command needs no prior install, keeps the bullet to one sentence, and is already the form used by .agents/skills/webjs/references/ui-kit.md and by the scaffold templates, so the README stops being the odd surface out. In the same pass, replace the three npx webjsui ... hints the CLI PRINTS at runtime with the explicit npx @webjsdev/ui ... form that packages/ui/src/registry/example.js already standardised on for exactly this reason, since a scaffolded app does not pin the kit (packages/cli/lib/create.js L455 says so outright) and the bare bin name only resolves when npm happened to link it into that project's node_modules/.bin.

Rejected:

• Keep an npx webjsui invocation in the README with npm install -D @webjsdev/ui in front of it. Three commands do not fit a one-line bullet, and it re-advertises the standalone binary at the altitude where the audience is a WebJs app.
• Cut the clause entirely and link to packages/ui/README.md. It throws away the useful zero-install answer, and the bullet already links to webjs.dev/ui.
• Reframe the clause as "other frameworks are untested but it renders anywhere". That re-advertises what feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235 deliberately dropped, and it reads as hedged maturity copy.
• Point the fallback at npx @webjsdev/ui add ... instead of npx webjsdev ui add .... Both resolve, but the scaffold and the agent skill already teach the webjsdev wrapper form, and the README should teach one command, not a second dialect.
• Leave packages/ui/src/commands/init.js L165 and add.js L28 / L34 alone. The premise that reaching those lines means the bin is linked does not hold for a scaffolded app, where @webjsdev/ui is intentionally not pinned, and the repo already rejected the bare form in example.js pointerLine.
• Touch packages/ui/README.md L83-L84. Those two npx webjsui lines sit directly under npm install -D @webjsdev/ui, so the bin is linked by then. feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235 wrote them deliberately and they stay.

Steps

1. Rewrite the final sentence of the **WebJs UI is the matching AI-first component library.** bullet at README.md L60, leaving the rest of the bullet untouched.

   Remove:

   It is auto-installed with `@webjsdev/cli`, and projects outside WebJs can use `npx webjsui add button card dialog`.
   

   Write in its place:

   It ships as a dependency of `@webjsdev/cli`, so a WebJs app has nothing to install, and an app without the global CLI can reach the same commands with `npx webjsdev ui add button card dialog`.
   

2. In packages/ui/src/commands/init.js L165, change the success hint from npx webjsui add button card dialog to npx @webjsdev/ui add button card dialog.

3. In packages/ui/src/commands/add.js L28 and L34, apply the same substitution to all three printed commands, so they read npx @webjsdev/ui init, npx @webjsdev/ui add button, and npx @webjsdev/ui list.

4. In website/app/ui/page.ts L124, change the prose reference webjsui view <name> to webjs ui view <name>, so the sentence matches the command form that page's own Install section teaches ten lines earlier.

5. Add the two unit tests described below.

6. State the step 2 and step 3 decision in the PR body with the create.js L455 reason, since the issue asked for it to be recorded rather than done by reflex.

Tests

• Unit: packages/ui/test/init-command.test.js, a new case that stubs console.log, runs await init.parseAsync(['--yes', '--cwd', d, '--registry', 'http://test/r'], { from: 'user' }) against the existing stubFetch() / tmp() harness, and asserts the captured output contains npx @webjsdev/ui add and contains no npx webjsui. logger.info is a thin console.log wrapper (packages/ui/src/utils/logger.js), so the capture is one line of setup.
• Unit: packages/ui/test/add-command.test.js, the same capture applied to the two early-return hint paths, the missing-components.json branch (L28) and the unknown-component branch (L34), asserting the same two conditions.
• Unit for the README sentence and the website prose: N/A, because a prose line has no test layer. The grep-based acceptance criteria below are the check, and inventing a test that greps README.md would pin marketing copy to a string.
• Browser, e2e, smoke, Bun parity: N/A, because nothing here touches a runtime surface. The only source edits are printed strings in two CLI commands, so require-bun-parity-with-runtime-src.sh should not fire, and if it does the change carries no cross-runtime behaviour to prove.
• Counterfactual: restore npx webjsui add button card dialog at init.js L165 with the tests in place. The new init-command.test.js case reds on the captured hint, and reverting only add.js reds the add-command.test.js case.

Doc surfaces

Every path below was confirmed with git grep -n 'npx webjsui\|outside WebJs\|webjsui' across *.md, *.ts, *.js, *.mjs, *.json, plus a targeted sweep of .agents/, packages/cli/templates/, website/, and docs/.

Edited:

• README.md L60, the only surviving "projects outside WebJs" claim in the repository.
• packages/ui/src/commands/init.js L165.
• packages/ui/src/commands/add.js L28, L34.
• website/app/ui/page.ts L124.

Verified and deliberately NOT edited:

• packages/ui/README.md L74-L90, the post-feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235 "Option B : the standalone binary" section. This is the source of truth the README sentence must agree with, and its npx webjsui init / npx webjsui add lines at L83-L84 follow the two install commands.
• packages/ui/AGENTS.md L282-L292, the command table. feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235 already scoped init to fixed constants, and these are bin-name references, not invocations.
• .agents/skills/webjs/references/ui-kit.md L5-L7, L43, L72. Already teaches npx webjsdev ui init / npx webjsdev ui add <name>, which is the form step 1 adopts.
• packages/cli/templates/partials/agents-playbook-fullstack.md L16, L49, L121, and packages/cli/templates/scripts/clear-gallery.mjs L147, L187. Already npx webjsdev ui add <name>.
• website/app/ui/page.ts L89-L98, the Install section. Already scoped to a WebJs app with nothing to install, consistent with feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235.
• website/app/docs/ai-first/page.ts L52, website/app/docs/configuration/page.ts L62, website/app/docs/layout.ts L89. Mention the kit without any host-project claim.
• packages/ui/package.json description. Already definitional and WebJs-scoped after feat: make npm descriptions definitional and add a sameAs graph #1248.
• packages/mcp/README.md L41 and packages/mcp/AGENTS.md L51, which name webjsui view as the CLI leaf the MCP ui tool mirrors. Internal agent docs, not an invocation a reader types.
• changelog/ui/0.3.9.md L11. A frozen historical entry, never rewritten.

Implementation notes (for the implementing agent)

Where to edit:

• README.md L60, the **WebJs UI is the matching AI-first component library.** bullet. The offending clause is the final sentence.
• Read packages/ui/README.md L74-L90 first (the "Option B : the standalone binary" section). That is the corrected wording to align with, and it is the source of truth for the install sequence.
• packages/ui/src/commands/init.js L165 and packages/ui/src/commands/add.js L28, L34.
• website/app/ui/page.ts L124.

Premise, already verified on 2026-08-05, no need to re-derive:

• curl -sS -o /dev/null -w '%{http_code}' https://registry.npmjs.org/webjsui returns 404, and the same call for webjsdev returns 200.
• packages/ui/package.json declares "bin": {"webjsui": "bin/webjsui.js"}, so the binary exists only inside @webjsdev/ui.
• packages/wrappers/webjsdev/package.json is the published unscoped wrapper. It declares the single bin webjs and depends on @webjsdev/cli, which is why npx webjsdev ui add ... works from a project that installed nothing.
• packages/cli/lib/create.js L455 states that @webjsdev/ui is intentionally NOT pinned by the scaffold, which is what makes the bare npx webjsui hint unreliable in a freshly created app.
• packages/ui/src/registry/example.js L80-L88 already documents the explicit npx @webjsdev/ui <cmd> form and the reason for it. Steps 2 and 3 make the two commands agree with the rule the same package wrote down.

Landmines / gotchas:

• README.md is npm-visible for the repo root and is the first thing a newcomer reads, so treat it as marketing copy, not internal notes. Do not add hedged maturity language about what is or is not tested elsewhere; the positive statement is the whole sentence.
• AGENTS.md invariant 11 applies: no em-dash, no space-hyphen or space-semicolon as pause punctuation, and WebJs capitalized wherever it NAMES the project in prose. Lowercase webjs stays only as a literal code token (webjs ui add, @webjsdev/ui, webjs.dev). The .claude/hooks/block-prose-punctuation.sh hook scans new content and will reject a violation.
• The doc gate and the test gate are both satisfied by the plan as written. Steps 2 and 3 stage packages/ui/src, so require-docs-with-src.sh wants a doc surface in the same commit (step 1 and step 4 provide it) and require-tests-with-src.sh wants a test (step 5 provides it). Do not reach for WEBJS_NO_DOC_GATE=1.
• Keep the two npx webjsui lines in packages/ui/README.md L83-L84. They follow npm install -D @webjsdev/ui, so the bin is linked by the time they run. Rewriting them would undo feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235's deliberate wording.

Invariants to respect: AGENTS.md invariant 11 (prose punctuation and brand casing). The framework-root rule that docs must not re-advertise a capability the package dropped, which is the whole point of this issue.

Acceptance criteria

• README.md L60 no longer offers @webjsdev/ui to projects outside WebJs
• No npx webjsui invocation survives in README.md
• The replacement sentence names npx webjsdev ui add button card dialog as the no-install path, matching the agent skill and the scaffold templates
• The wording agrees with packages/ui/README.md's post-feat!: scope @webjsdev/ui to WebJs apps, drop project detection #1235 framing
• git grep -n 'outside WebJs' -- '*.md' 'website/**' returns nothing
• git grep -n 'npx webjsui' -- packages/ui/src/ returns nothing, and packages/ui/README.md L83-L84 are unchanged
• website/app/ui/page.ts L124 reads webjs ui view <name>
• packages/ui/test/init-command.test.js and packages/ui/test/add-command.test.js each assert the printed hint, and each reds when its source line alone is reverted
• The PR body records the decision to change packages/ui/src/commands/init.js L165 and add.js L28 / L34, with the scaffold-does-not-pin reason
• No AGENTS.md invariant 11 violations in the new prose