Skip to main content

AI Knowledge Authoring Guide

This guide defines how Juneau documentation should be authored and published so AI agents can consume it reliably.

Canonical Sources​

Use these source-of-truth locations:

  • Concepts and behavior: pages/topics/*.md
  • Versioned changes: pages/release-notes/*.md and migration guides
  • Project overviews: src/pages/about/*.mdx, with names, taglines and modules from src/data/projects.ts
  • API semantics: Java sources and Javadocs in the main juneau repository

Do not treat todo/*.md as authoritative runtime behavior documentation unless content is explicitly promoted into docs/release notes.

Canonical AI Artifacts​

Generated artifacts live in:

  • static/ai/manifest.json
  • static/ai/juneau-knowledge.jsonl
  • static/ai/taxonomy.json

These files are the machine-first entrypoint for AI indexing/RAG pipelines and local coding agents.

The generator also writes static/llms.txt, served at https://juneau.apache.org/llms.txt. It follows the llmstxt.org convention: an # Apache Juneau H1, a short summary, one H2 section per top-level section (Getting Started, Guides) and per Documentation section (each topic is a - [Title](URL): summary bullet reusing the JSONL summary), an ## About section listing the project pages, and a resources section linking the current release notes, migration guide, Javadocs, JSONL and manifest. Coding agents look for this file at the site root, so keep topic summary text (the first paragraph of each page) self-explanatory.

llms-full.txt (all topics concatenated) is intentionally not generated: the topic markdown totals about 3 MB, too large to be useful as a single context-window file. Agents should follow the links in llms.txt or query juneau-knowledge.jsonl instead.

Field Guidance (summary vs description)​

Use a short summary for compact, token-efficient explanations and a fuller description for nuance:

  • summary: One sentence, plain language, no paragraphs.
  • description: Longer explanation with context, caveats, and examples.
  • Prefer explicit summary metadata from annotations (summary / su) when available.

Regeneration Workflow​

From juneau-docs:

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

The first command regenerates deterministic artifacts. The second verifies:

  • generated AI files (including static/llms.txt) are up to date,
  • required manifest/record shape is present,
  • README quickstart version matches current Juneau release,
  • Javadocs link paths in docs config are consistent,
  • canonical release-note source for current release exists.

Java Code Fences​

Every ```java fence is parsed by scripts/check-java-fences.py (JDK parser only: no symbol resolution, no compile). The docs build and the docs gate run it with --strict, so a fence that is not valid Java fails the build.

A fence passes if it parses as a compilation unit, as class-body members, as statements, or as a sequence of those (for example a class declaration followed by loose statements).

When a snippet is deliberately not complete Java, add the word fragment to the fence info string:

```java fragment
.setMaximum(100)
.setExclusiveMaximum(true)
```

Use fragment for:

  • placeholders such as ... or {...},
  • a method-chain tail, a bare expression, or a signature without a body,
  • an annotation or constructor shown without its enclosing class.

Do not use it to hide a real mistake (unbalanced braces, a stray ;, a missing parenthesis): fix the sample. If the content is not Java at all (properties, XML, shell), give the fence its real language instead. The word is invisible in the rendered page; Docusaurus highlights the fence as Java either way.

Guide Fences​

Guide pages (pages/guides/) show code that lives in the Juneau repository's juneau-examples/juneau-examples-guides test module, which the Juneau build compiles and tests. Each fence names its source with a guide=FILE#REGION word in the info string (the class here is illustrative, not one of the guides):

```java guide=PetResource.java#resource
@Rest(path="/pets")
public class PetResource extends BasicRestResource { ... }
```
  • FILE is a file under the module's src/test/java or src/test/resources. A bare file name (PetResource.java) must match exactly one file; a relative path (SpringBootRestApi/pom.xml) is tried under each of the two roots.
  • REGION is the text between the comment lines region NAME and endregion NAME in that file, written as //, # or <!-- --> comments.
  • scripts/check-guide-snippets.py compares each fence with its region, after expanding tabs, dropping trailing spaces, the common indent and leading and trailing blank lines, and prints a diff when they differ. The docs build (Links stage) and the docs gate run it.
  • On a guide page every fence must carry a pointer unless its language is bash, sh, shell, console or text. A text fence may carry one, so the "Run it" output can point at a file the guide's test asserts against.
  • guide= and fragment are independent: a guide's ```java fence is still parse-checked unless it is also marked fragment.

To change a guide's code, edit the module file first, run the module's tests (mvn -q test -f juneau-examples/juneau-examples-guides/pom.xml), then copy the region into the page.

Definition Of Done (Docs-Affecting PRs)​

  • New or changed feature docs are added under canonical source locations.
  • AI artifacts are regenerated if source content changed.
  • check-ai-artifacts.py passes locally.
  • check-java-fences.py --strict passes locally.
  • summary text is concise and description adds non-redundant detail.
  • Source provenance remains traceable via source_path in JSONL output.