Add LLM-friendly developer support

[ibgreen]

Goals

• Add first-class support for developers using AI coding agents without changing luma.gl JavaScript APIs or contributor policy.
• Make current documentation retrievable as targeted, rendered Markdown rather than requiring agents to ingest the entire site.
• Encode luma.gl-specific architecture, portability, debugging, and contribution judgment in an installable Agent Skill.
• Provide an offline quality corpus that can measure agent behavior without API keys or model execution in CI.

Changes

• Adds a Working with AI Coding Agents developer guide page and an AI Agents developer-guide tab.
• Adds @signalwire/docusaurus-plugin-llms-txt@^1.2.2, configured to generate:
  • a hierarchical /llms.txt with absolute luma.gl Markdown URLs and descriptions;
  • raw Markdown siblings for current documentation pages;
  • rendered Markdown for MDX/custom components;
  • raw Markdown for generated TypeDoc pages.
• Excludes legacy guides, blogs, standalone pages, and examples from the machine-readable index, and explicitly disables llms-full.txt.
• Adds a post-build checker for required outputs, broken Markdown links, unexpected legacy/example routes, extraction failures, TypeDoc output, and accidental llms-full.txt generation.
• Adds an installable skills/lumagl Agent Skill with focused references for architecture, backend portability, GPU debugging, and repository contribution.
• Adds a nine-case offline eval corpus plus a Node test validating skill frontmatter, local references, eval schema, unique cases, and canonical source paths.
• Adds yaml@^2.8.1 as a direct development dependency for frontmatter validation.

Developer impact

Application developers can install the skill with:

npx skills add visgl/luma.gl --skill lumagl

Agents can start at /llms.txt, fetch only task-relevant Markdown pages, inspect installed package versions and declarations, and follow an observable browser/GPU verification loop.

No luma.gl runtime APIs change.

Verification

• nvm use
• yarn install
• Agent Skill quick_validate.py: passed
• yarn lint fix: clean
• yarn test-node: 197 passed, 2 skipped
• yarn website:build: passed
• (cd website && yarn build): passed
• Generated-output checker: /llms.txt and 412 raw documentation pages validated
• Browser inspection at 900px and 600px: all developer tabs remain visible; narrow layout wraps to two rows without overflow; no console warnings or errors
• yarn build: passed across all workspaces
• CI=1 yarn test: 197 Node tests passed with 2 skipped; 1,286 browser tests passed with 25 skipped
• Commit hooks (yarn lint and yarn test-node): passed

Notes

A native-GPU yarn test run on the development machine reports three DGGS/Arrow WebGPU failures (A5 coordinates become NaN, plus one storage-backed Arrow layer assertion). The same three tests pass in isolation and in the complete suite under the repository's configured CI SwiftShader mode. The changed files do not touch those GPU implementations or tests.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 716f7f495b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chrisgervang]

A similar PR is proposed in react-map-gl. Would be good to align on the tooling and eventually upstream to the website template visgl/react-map-gl#2593

[chrisgervang]

I've been curious to see different ways of "testing" LLM tools for correctness and efficacy.

How does one run them and share that they passed?

[ibgreen-openai]

Agreed. I compared this with visgl/react-map-gl#2593. The two sites currently need different generation strategies: luma.gl extracts rendered MDX/TypeDoc into per-route Markdown, while the react-map-gl proposal assembles custom Mapbox/MapLibre bundles. I don't think forcing one plugin in this PR would improve either use case. The useful common layer is the output contract, base-path handling, and build validation; once both implementations settle, we should upstream those shared pieces to @vis.gl/docusaurus-website and keep framework-specific skill content local.

[chrisgervang]

What were the results for this PR?