GeezerVison

Follow-up to #6762.

Summary

Install command. --global → -g, which is what every comparable CLI documents. Drops the yarn tab: it read yarn global add sim, which works on Yarn 1 only — Yarn 2 removed global installs, so that command fails for anyone on a modern Yarn. Adds npx sim for running without installing.

Trimmed the CLI guides: 1016 lines → 763, 12 callouts → 3. The pages had accumulated design rationale that belongs in code comments rather than user docs — why the filter grammar is JSON, why the config section naming is asymmetric, why an unexpected error keeps its stack trace. I surveyed how gh, Vercel, Turborepo, Deno, Bun and Supabase write their CLI docs: none carry that kind of justification, and callouts are reserved for content whose absence produces a wrong result, not for general asides. The three that remain are the pairing-code check, that sim logout does not revoke the key, and the --limit 100 default on batch-delete/batch-update, which silently truncates a larger match. Troubleshooting drops the entries whose error message already contained its own fix and keeps the seven whose cause is not obvious.

JSON-LD never reached the HTML. All four structured-data blocks (WebSite, TechArticle, BreadcrumbList, SoftwareApplication) were rendered with next/script, which never emitted a script tag. Measured on a production build, /api-reference/getting-started contained zero <script type="application/ld+json"> elements — the payload existed only in the __next_s client-injection queue and the RSC flight data, so anything reading the served HTML saw no structured data. React was also logging Encountered a script tag while rendering React component on every page. next/script is for loading and executing JavaScript; JSON-LD is data, and Next's own guidance is a native <script> in the component. serializeJsonLd already performs the escaping that guidance calls for, so only the element changes. Same build after the fix: three valid tags per page with WebSite in <head>, injection queue gone.

Sidebar separator spacing. [data-separator]:not([data-separator] ~ [data-separator]) was meant to keep the first sidebar group flush against the top padding, but ~ only reaches siblings, so it also matched the first separator inside every expanded folder. Under Self-Hosting, "Install" lost its top margin and crowded "Architecture" — 25px of gap where "Configure" and "Operate" below it had 40px. :first-child expresses the intent directly; only the four sidebar roots open with a separator, so nothing else changes.

Type of Change

• Bug fix (JSON-LD not served; sidebar spacing; a documented install command that fails on Yarn 2+)
• Documentation

Testing

• JSON-LD measured before and after on a production build and over HTTP: 0 → 3 valid tags per page, WebSite in <head>, __next_s queue absent
• Sidebar rule verified against all 21 meta.json files — only the four sidebar roots open with a separator, so no nested folder regresses
• Non-global npm install verified to leave the binary in node_modules/.bin and off PATH, confirming -g is required
• bun run check:audits (29/29), 242 CLI tests, type-checks clean on apps/docs and packages/sim-cli, full site builds, all routes 200

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)