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.
Give your agent the docs
Section titled “Give your agent the docs”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.
Add Plenary to your project instructions
Section titled “Add Plenary to your project instructions”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.
## 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.Give the agent a scoped API key
Section titled “Give the agent a scoped API key”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:readandcontent:models:updatelet 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.
Let the agent change models with the CLI
Section titled “Let the agent change models with the CLI”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.
npm install --save-dev @plenary/clinpx plenary init --base-url https://your-instance.plenarycms.io --site main --locale en-usnpx plenary metadata pull # write the instance's models and forms as YAMLnpx plenary metadata diff # validate the local YAML and print what a push would changenpx plenary metadata push # apply itmetadata 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.
Rules agents commonly get wrong
Section titled “Rules agents commonly get wrong”These Plenary behaviors most often trip up code written from general CMS knowledge. Each links to the page with the detail.
- 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 sendslocalefor you when it is configured. See Localization. - Field values live under
data. An entry’s own properties, such asid,slug,locale,status, andpublished_at, sit at the top level. The values of the fields you defined are insidedata. See Content API. - 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.
- Page-builder content is a document, not HTML. A
blocksfield holds a tree of component nodes. Render it with@plenary/reactand register a React component for every custom block your editors use. See Page Builder. - Avoid viewport-height units inside the preview bridge. Sizing content with
100vh,min-h-screen,svh, ordvhinside the live-preview frame makes the frame grow without end. See Live Preview. - Build your own forms. Load a form’s definition with
getFormand send it withsubmitFormfrom@plenary/client. There is no prebuilt form component. Include the anti-spam fields described in Forms. - 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.
- Branch on error codes, not messages. Every error response carries a stable
code, such asauthentication_required. See Errors.
Start a task
Section titled “Start a task”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 usingPlenary: 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.