feat: overhaul llms.txt generation

[willeastcott]

What

Overhauls the generated llms.txt so it actively steers LLMs and coding agents toward correct PlayCanvas code, instead of being a flat link dump.

New llms.txt structure

# PlayCanvas Developer Documentation
> blockquote + metadata (Base URL, Engine Version, Total Documents, Generated)
## Instructions for Large Language Models   <- NEW: WRONG/CORRECT code patterns
## Recommended Entry Points                  <- now spec-format links with descriptions
## Essential API                             <- NEW: 26 curated engine classes + all API ref sections
## User Manual                               <- entries now `- [Title](url): description`
## Optional                                  <- NEW: account management, glossary, press pack, security

Changes

• Instructions section: hand-written guidance covering the four PlayCanvas workflows (Editor, engine-only, React, Web Components), ESM vs classic script syntax with explicit WRONG/CORRECT examples, and npm/CDN setup. All snippets verified against the engine, react, and web-components repos.
• Spec-compliant entries: the llms.txt spec format is - [Title](url): description. The plugin already extracted per-page descriptions (100% of docs have hand-written frontmatter descriptions) but never used them — they're now wired in.
• Essential API section: api.playcanvas.com was previously absent from the file entirely. Adds 26 curated engine class links (all verified 200) plus the other API reference sections.
• ## Optional section: spec mechanism for content consumers can skip — account management, glossary, press pack, security.
• Tutorials excluded from both generated files: many are dated or are bare project links; removing them avoids feeding stale patterns to LLMs. One-line excludeDirs change, easy to revert after a tutorial refresh.
• Engine version in metadata: read from the installed playcanvas package at build time; the line is dropped gracefully if resolution fails.
• Subcategory ordering fixes: dead 'index' entry replaced with 'Overview'; supersplat, splat-transform, security were missing from the order list and now match sidebars.js.
• Preview harness: npm run preview-llms [outDir] generates both files in ~2 seconds without a full Docusaurus build, for fast iteration on the curated content.

The hand-written header lives in utils/plugins/llms/llms-header.md (placeholder-substituted at build time), so content edits don't touch plugin code. llms-full.txt generation logic is unchanged.

Verification

• Baseline/after comparison via the preview harness: llms-full.txt URL set differs from baseline by exactly the 147 tutorial docs — zero User Manual docs lost, zero additions.
• New llms.txt: 452 docs + 42 curated entries, all in - [Title](url): description format; zero old-format lines; zero unresolved {{placeholders}}; Engine Version: 2.19.6 present; balanced code fences; Optional partition verified.
• All 33 curated api.playcanvas.com URLs and spot-checked developer-site URLs return 200.
• npm run lint passes (1248 files, 0 errors).

Follow-ups (separate PRs)

• Emit a per-page .md next to each built HTML page and link those from llms.txt (link construction is isolated in formatDocEntry for this).
• An llms.txt for api.playcanvas.com.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR overhauls llms.txt generation to provide a spec-formatted, LLM-steering overview of the PlayCanvas docs (with a curated, hand-written header), adds engine-version metadata, and introduces a fast local preview workflow for iterating on the generated outputs.

Changes:

• Adds a hand-written llms.txt header template (with placeholder substitution) containing workflow guidance, recommended entry points, and curated API links.
• Updates the LLM generation plugin to emit spec-style entries (- [Title](url): description), reorder User Manual sections, add an Optional partition, exclude tutorials by default, and include engine version metadata when resolvable.
• Adds a preview harness (npm run preview-llms) to generate llms.txt and llms-full.txt without a full Docusaurus build.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
utils/plugins/llms/preview.mjs	Adds a standalone script to run the plugin’s postBuild and write preview outputs to a chosen directory.
utils/plugins/llms/llms-header.md	Introduces the curated header content used as the top of generated llms.txt.
utils/plugins/docusaurus-plugin-llms.mjs	Refactors llms.txt generation to use the header template, spec-formatted entries with descriptions, optional partitioning, tutorial exclusion, and engine-version resolution.
package.json	Adds preview-llms npm script for the preview harness.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.