Skip to content

Building with AI Agents

Many Plenary sites are built with help from an AI coding agent such as Claude Code, Cursor, or Copilot. These docs are written to be read by those agents as well as by people. This page explains how to hand the docs to an agent, what access to give it, and which Plenary rules it should follow.

Every page of this site is published in machine-friendly forms:

URL What it contains Use it when
/llms.txt A short summary of Plenary and an index of every page, each with a one-line description and a Markdown link. The agent can fetch pages on demand. This is the best starting point.
/llms-full.txt Every page concatenated into one Markdown file. The agent cannot browse, or you want to give it the whole manual at once.
/llms-small.txt The same, with notes, tips, and collapsed details removed. The full file is too large for the agent’s context window.

Any single page is also available as raw Markdown by adding .md to its URL. For example, the Content API reference is at https://docs.plenarycms.com/reference/content-api.md.

Topic bundles live under /_llms-txt/: guides.txt, examples.txt, and api-and-sdk-reference.txt. Use one when an agent needs a single area in depth.

Most agents read a project instruction file, such as AGENTS.md, CLAUDE.md, or .cursor/rules. Add a short block so the agent knows where the docs are and which rules matter. Adjust the values to match your project.

AGENTS.md
## Plenary CMS
This site reads its content from Plenary.
- Docs index: https://docs.plenarycms.com/llms.txt (append `.md` to any docs URL for Markdown).
- Instance: https://your-instance.plenarycms.io, site key `main`, locale `en-us`.
- Packages: @plenary/client for reads and forms, @plenary/react for page-builder rendering,
@plenary/next for webhook revalidation, @plenary/cli for model YAML.
- Env vars: PLENARY_BASE_URL, PLENARY_SITE_KEY, PLENARY_LOCALE, PLENARY_API_KEY (the site's
public key), PLENARY_CLI_API_KEY (the CLI's private key; never read it from site code).
- Content models are kept as YAML in `plenary/models/` and applied with
`npx plenary metadata push`. Change models there, not in the console.
- Never expose a private API key to the browser.

An agent needs a credential to read content or change models. Give it an API key with only the grants the task requires, rather than your own login.

  • To read published content, a public key is enough. It reads published entries and submits forms, and nothing else.
  • To read drafts or manage models and entries, create a private key with the specific content:* grants needed. For example, content:models:read and content:models:update let an agent sync model YAML without touching entries.
  • API keys never manage users, roles, API keys, or settings. Those changes need a person’s login.

Put a private key for the CLI in the agent’s environment as PLENARY_CLI_API_KEY, and a public key for the site as PLENARY_API_KEY. Do not paste it into a prompt or commit it. See API Keys for how to create one and Permissions for every grant.

The @plenary/cli package provides a plenary command that changes content models without driving the console. Models live as YAML files in your repository, so every change shows up in a diff you can review.

Terminal window
npm install --save-dev @plenary/cli
npx plenary init --base-url https://your-instance.plenarycms.io --site main --locale en-us
npx plenary metadata pull # write the instance's models and forms as YAML
npx plenary metadata diff # validate the local YAML and print what a push would change
npx plenary metadata push # apply it

metadata diff validates the whole tree and prints a plan without writing anything, so an agent can check its own YAML before applying it. A push never deletes a model unless --prune is passed. See Models as Code for the workflow and Model YAML for the file format.

These Plenary behaviors most often trip up code written from general CMS knowledge. Each links to the page with the detail.

  1. Always send a locale. Content reads match the locale exactly. A request for a locale with no content returns 404, or an empty list, rather than falling back to another language. The SDK sends locale for you when it is configured. See Localization.
  2. Field values live under data. An entry’s own properties, such as id, slug, locale, status, and published_at, sit at the top level. The values of the fields you defined are inside data. See Content API.
  3. Public keys see published content only. If drafts are missing, the key is public, not broken. Draft and preview reads need a private key used only on the server. See API Keys.
  4. Page-builder content is a document, not HTML. A blocks field holds a tree of component nodes. Render it with @plenary/react and register a React component for every custom block your editors use. See Page Builder.
  5. Avoid viewport-height units inside the preview bridge. Sizing content with 100vh, min-h-screen, svh, or dvh inside the live-preview frame makes the frame grow without end. See Live Preview.
  6. Build your own forms. Load a form’s definition with getForm and send it with submitForm from @plenary/client. There is no prebuilt form component. Include the anti-spam fields described in Forms.
  7. Use Plenary’s terms. A visitor’s form record is a form entry. An outbound HTTP callback is a webhook. Pre-save JavaScript on a model is a transformer. Searching the docs for these exact words finds the right page.
  8. Branch on error codes, not messages. Every error response carries a stable code, such as authentication_required. See Errors.

A good first prompt names the outcome and points at the docs:

Read https://docs.plenarycms.com/llms.txt. Then add a blog to this Next.js app using
Plenary: a `post` model in plenary/models/, a list page at /blog and a detail page at
/blog/[slug], rendered with @plenary/client. Follow the Blog with Next.js example.

The Examples section has complete builds an agent can follow step by step.