docs: fixes and improvements for setup, distribution and the docs site #355

Context

Fixes and improvements from a code audit of setup and distribution, the docs site, done in October 2026. Roadmap work lives in #340, #341, #342 and #343. Items marked (to confirm) were not reproduced; check them before fixing.

Setup and distribution

Problems

Medium

• devframe installed separately: the install command adds devframe next to the package, which already depends on devframe ^1.2.3. An unpinned devframe can resolve another version, so initDevframe(pangular) mixes two copies. Re-export initDevframe (or a mountPangular() helper) from @pangular-inspector/devtools/devframe and drop devframe from the install command, or move it to peerDependencies with a matching range (README.md:18, apps/docs/src/content/getting-started/installation.md:48-62, installation.md:237-238, packages/devtools/package.json:83).
• one-time code copied by hand: in the client-only setup the CLI prints a localhost:9999/#devframe_otp= link, and the user has to retype the code on the app origin under /__pangular/. Add pangular dev --proxy-origin http://localhost:4200 so startupLines prints the right link. This is a small fix ahead of the builder in phase 3 of 4: a shell you live in #342 (packages/devtools/src/cli.ts:160-177, installation.md:184-186).

Low

• no dev dependency guidance: README and the docs use a plain install, never -D. Show -D for Vite, Analog and client-only setups, and say that an SSR server needs it as a dependency, or as a dev dependency behind a production guard (README.md:18, installation.md:48-62).
• no supported builder list: the docs say nothing on webpack (@angular-devkit/build-angular:browser), Nx executors or Rsbuild, and /vite is described as "for Analog apps" although it works for any Vite-based Angular app. Add a "Supported setups" table and reword the /vite entry (installation.md:68, apps/docs/src/content/getting-started/vite.md:12).
• full-page viewer path disagrees: "Check that it works" says /__devframes/ and assumes ng serve alone, while the client-only setup on the same page serves it at /__pangular/ with the CLI running. Split the check per setup or name both paths (installation.md:197, installation.md:216-231).
• ssrMiddleware not documented in the Express setup: initPangularHub() returns ssrMiddleware, but "Fill the SSR & HTTP tab" never shows app.use(devtools.ssrMiddleware), so SSR render tracing is easy to miss. Add it there, or mount it inside nodeMiddleware (packages/devtools/src/hub.ts:131, apps/docs/src/content/getting-started/express.md:207-240).
• Node floor above Angular 20: engines.node is >=22, while Angular 20 supports Node ^20.19. Angular 20 users on Node 20 get engine warnings, or a failed install with engine-strict. Test on Node 20.19 and lower the floor, or give the reason in the docs (packages/devtools/package.json:119-121, installation.md:17-18) (to confirm).

Improvements

• vite: print a startup hint ("Pangular Inspector: ", plus the popup shortcut) through server.printUrls, so the devtools URL shows in Vite's banner (packages/devtools/src/vite.ts).
• hub: document how to combine Pangular with other devframe tools in one /__devframes/ dock, and pass extra devframes: [...] through initPangularHub and the Vite plugin (packages/devtools/src/hub.ts, packages/devtools/src/vite.ts, express.md, vite.md).
• cli: add npx @pangular-inspector/devtools init, a codemod for Analog, Nx and non-CLI setups that detects angular.json, vite.config or server.ts and patches them. Offer it as an Nx generator too (packages/devtools/src/cli.ts).
• extension: a standalone read-only mode that works without a server, reading window.ng through devtools.inspectedWindow.eval (extension/).
• docs: a "Supported setups" matrix at the top of installation.md (builder x SSR x transport x extension) with the number of steps each takes, plus short Nx, webpack and Rsbuild notes.

Already tracked elsewhere

• ng add schematic and dev-server builder that mounts the hub: phase 3 of 4: a shell you live in #342
• Vite plugin overlay injection with transformIndexHtml: phase 1 of 4: safe by default and wired into your workflow #340
• Hub enabled switch defaulting off in production: phase 1 of 4: safe by default and wired into your workflow #340
• Shared loopback and Host gate for the Express hub: phase 1 of 4: safe by default and wired into your workflow #340
• Extension <all_urls> content scripts and the "Host access" docs: phase 1 of 4: safe by default and wired into your workflow #340; Chrome Web Store, Edge and Firefox publishing: phase 3 of 4: a shell you live in #342

The docs site

Problems

Medium

• Setup and guide pages repeat each other: NativeScript, Angular Native and Analog each have a Getting Started page and a Guides page with near-identical descriptions, so they will drift and readers don't know which one to follow. Merge each pair into one page, or turn the Getting Started page into a short pointer to the guide (apps/docs/src/content/getting-started/nativescript.md vs guides/nativescript.md, getting-started/angular-native.md vs guides/angular-native.md, getting-started/vite.md vs guides/analog.md).
• No API reference: api-gen.plugin.ts is a no-op because apps/docs/ngmd.api.ts does not exist, and per-symbol routes are "not yet wired". initPangularHub, pangular(), createPangular, the overlay and popup entry points and the HTTP interceptor are only described in prose. Add ngmd.api.ts scoped to packages/devtools/src/{hub,vite,devframe,config,overlay,popup,http}.ts and finish the per-symbol routes so the JSDoc on PangularConfig feeds the docs (apps/docs/api-gen.plugin.ts:7-24).
• Troubleshooting is scattered: only Express, Hono/h3/Fastify and Popup and hub have a Troubleshooting section. Vite/Analog, the CLI, MCP and the Chrome extension have none. Add one troubleshooting page indexed by symptom (no page connected, empty tab in a production build, one-time code prompt, port taken) and link it from every Getting Started page and from the panel empty states (getting-started/express.md:256, getting-started/popup-and-hub.md:175, getting-started/other-servers.md:119).

Low

• Sidebar badges mean nothing: 13 nav items carry status: 'new' or 'updated' and nothing ever removes them. Tie each badge to a package version and expire it after the next minor release (apps/docs/src/ngmd.config.ts:180-209).
• CLI help spells the flag wrong: the --force description says --out-dir, while the errors and the CLI page use --outDir. Change the text to --outDir (packages/devtools/src/cli.ts:62, getting-started/cli.md:141-143).
• No page for planned platforms: Capacitor is a Coming Soon view in the panel with plans and PR links, but the docs only mention it in one table row. Add a short Platforms page listing supported and planned targets with their tracking issues, and link it from the coming-soon view (app/src/app.ts:68-72, app/src/pages/coming-soon.ts, getting-started/popup-and-hub.md:122).

Improvements

• A Features overview page that walks every tab with a screenshot and a one-line use case, linking to the inspector page (getting-started/introduction.md).
• Publish /llms.txt (and llms-full.txt) built from the content files; the raw .md routes already exist (apps/docs/raw-md.plugin.ts).
• Short GIF or video clips for interactive flows: pick a component, router probe, HTTP fault injection, NgRx restore (inspectors/*.md, <ngmd-video>).
• Generate the agent tools reference from the tool registrations so ids and parameters can't drift, and add a CI check that every pangular:* id has a heading (packages/devtools/src/devframe.ts, packages/devtools/src/rpc/, agents/tools.md).
• A "Recipes for agents" page with end-to-end prompts for Claude Code, Cursor and Copilot (debug an invalid form, explain a failed navigation, find a missing provider) (agents/).
• A keyboard shortcuts reference; shortcuts are spread over inspectors/components.md, inspectors/injectors.md and getting-started/popup-and-hub.md.
• A version matrix tying each feature to its minimum Angular version (signal graph 20.1, router probe 20.2, Signal Forms 22) (getting-started/installation.md:32).

Already tracked elsewhere

• Screenshots on every inspector page: phase 3 of 4: a shell you live in #342.
• A one-path quick start: phase 3 of 4: a shell you live in #342.
• An "Extending Pangular Inspector" page depends on the public plugin API in phase 4 of 4: deeper diagnosis #343.

Generated by Claude Code