Skip to contents

Agent Quickstart

Source: AGENTS.md

README.md is the human quickstart for this repository. AGENTS.md is the agent quickstart.

What rllmdoc does

rllmdoc generates spec-valid llms.txt and llms-full.txt artifacts for:

  • Quarto projects (website and book subtypes)
  • R package documentation sites built with pkgdown

The package uses a hybrid model:

  • Quarto llms-txt: true and pkgdown build_llm_docs() are used to generate supporting markdown companions (.llms.md and .md files).
  • rllmdoc does not treat native llms.txt output as canonical.
  • rllmdoc derives grouping and descriptions from existing project config, validates the final output against the spec, writes the tracked llms.txt itself, and mirrors llms-only artifacts into _llms/.

Current Public Surface

The current exported interface is:

Historical note:

  • Older commits and stale generated docs may reference intermediate names such as detect_project(), use_llms_txt(), build_llms_txt(), and build_llms_full_txt().
  • Those names are useful for archaeology, but they are not the current public API.

Read In This Order

When onboarding to the repo, read in this order:

  1. AGENTS.md
  2. vignettes/rllmdoc.qmd
  3. vignettes/spec-contract.qmd
  4. NEWS.md
  5. The plan next-phase-pipeline in the $AGENTS_HOME plans directory
  6. DISCUSS.md
  7. Then the relevant files in R/ and tests/testthat/

If generated docs under docs/ disagree with source files, prefer the source files and rebuild the generated artifacts.

Canonical Documentation Sources

Source-of-truth documentation lives in:

  • R/ roxygen comments
  • vignettes/
  • README.md
  • AGENTS.md
  • NEWS.md
  • _pkgdown.yml
  • DISCUSS.md for research and discussion context

Generated outputs live in:

  • man/
  • NAMESPACE
  • docs/

Documentation Build Workflow

Run from the package root in an R session:

devtools::document()
pkgdown::clean_site()
pkgdown::build_site()
devtools::load_all(quiet = TRUE)
rllmdoc::build_llms_docs(".")

Why the last step matters:

  • pkgdown::build_site() generates the HTML site and the supporting .md companion files.
  • rllmdoc::build_llms_docs(".") then replaces pkgdown’s native llms.txt with the package’s curated, spec-valid llms.txt, updates llms-full.txt, and refreshes _llms/.

Use a clean site rebuild when generated docs drift, old reference pages linger, or search metadata looks stale.

Project Structure

rllmdoc is a standalone R package.

  • Core implementation lives in R/, usually one concern per file.
  • Tests live in tests/testthat/; shared test helpers are in tests/testthat/helper-rllmdoc.R.
  • Long-form package docs live in vignettes/.
  • JSON schemas live in inst/schemas/.
  • The published pkgdown site lives in tracked docs/.

Coding And Testing

  • Follow the repository’s existing R style: two-space indentation, small focused functions, and fail-fast cli::cli_abort() errors.
  • Exported APIs use snake_case; internal helpers use dotted private names.
  • Add regression tests for behavior changes in tests/testthat/test-*.R.
  • Run devtools::document() after changing roxygen comments or exported functions.

Release History And Planning

  • Update NEWS.md whenever behavior or API changes.
  • Forward-looking roadmap lives in the $AGENTS_HOME plans directory, not in this repo. It is not the source of truth for the current shipped interface.
  • DISCUSS.md is research and exploratory context, not authoritative runtime behavior.

Security

Do not file public security issues. Report them to security@artalytics.app.