generate-ai-artifacts.py / check-ai-artifacts.py

These scripts produce and validate the machine-consumable AI knowledge artifacts for Juneau documentation.

What They Generate

generate-ai-artifacts.py writes:

static/ai/manifest.json
static/ai/juneau-knowledge.jsonl
static/ai/taxonomy.json
static/llms.txt (llmstxt.org index of the Getting Started, Guides and Documentation sections of the sidebar, served at the site root)

llms-full.txt is not generated: the concatenated topics are about 3 MB.

The output is deterministic to avoid noisy diffs and index churn.

check-ai-artifacts.py verifies:

generated artifact files, including static/llms.txt, are current (--check mode). The comparison is byte-exact except for source_commit in manifest.json, which records the juneau and juneau-docs commits the artifacts were generated from. A new commit in either repo with no content change does not make the artifacts stale,
static/llms.txt exists and starts with the # Apache Juneau H1,
required manifest shape exists,
quickstart dependency version in README.md matches current release,
Javadocs links in docusaurus.config.ts are internally consistent,
current release has a canonical page in pages/release-notes.

From the juneau-docs repository root:

python3 scripts/generate-ai-artifacts.py
python3 scripts/check-ai-artifacts.py

Both default to a sibling ../juneau checkout. For worktrees or other layouts pass the roots explicitly:

python3 scripts/check-ai-artifacts.py --juneau-root /path/to/juneau [--docs-root /path/to/juneau-docs]

Or via npm scripts:

npm run build:ai-artifacts
npm run check:ai-artifacts

The generator consumes documentation pages and release notes plus selected API metadata signals from the sibling juneau repository.
Keep summaries short and descriptive to support low-token retrieval workflows.