Docs AI Prompt and Schemas

@pagesmith/docs now ships dedicated setup and upgrade prompts plus version-matched JSON schemas so an agent can bootstrap or upgrade a docs integration without guessing the expected file layout.

Setup Prompt

Use this prompt file when you want an agent to set up docs in an existing repository:

The docs site now exposes two ready-to-use agent flows:

• Bootstrap or retrofit docs in a repository that does not already use @pagesmith/docs
• Upgrade an existing @pagesmith/docs integration and adopt compatible new guidance/features

Upgrade Prompt

Use this prompt file when the repository already uses @pagesmith/docs and you want an agent to upgrade the package, refresh AI artifacts, and adopt compatible new guidance/features:

Recommended instruction:

1Upgrade the existing @pagesmith/docs integration in this repository. Read node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/migration.md first and follow it exactly.

Recommended Agent Instruction

Use a prompt like this:

1Set up docs using Pagesmith for this repository. Read https://projects.sujeet.pro/pagesmith/prompts/setup-docs.md first and follow it exactly.

If the package is already installed and you want the version-matched local copy instead of the hosted one:

1Set up docs using Pagesmith for this repository. Read node_modules/@pagesmith/docs/skills/pagesmith-docs-setup/references/setup-docs.md first and follow it exactly.

Version-Matched Schemas

These schema files are useful when an agent is editing pagesmith.config.json5, meta.json5, or docs frontmatter:

Bundled Agent Indexes

Every release ships a compact AI index (llms.txt) and a full-context bundle (llms-full.txt) both at the site root and per package. Agents can fetch whichever surface they need without installing the package:

These are emitted by the assets passthrough in pagesmith.config.json5 and covered by the repo’s validate:pagesmith script so every bundled URL stays referenced from documentation.

What The Prompt Enforces

The setup prompt tells the agent to:

• install @pagesmith/docs at the repo root
• prefer npx pagesmith-docs init with explicit values after installation when the repo is a good fit for the built-in scaffolder
• treat rerunning npx pagesmith-docs init as safe for backfilling missing config fields and refreshing the config $schema
• inspect the repo for an existing docs-like directory before creating a new one
• detect a GitHub Pages-style origin and basePath from the repo owner and repo name
• confirm the chosen docs folder with the user when an existing candidate is found
• create root pagesmith.config.json5 with $schema: './node_modules/@pagesmith/docs/schemas/pagesmith-config.schema.json' and root package.json docs scripts
• scaffold a working home page plus guide/ and reference/ sections
• update CLAUDE.md and AGENTS.md so future sessions read the package guidance and schema files
• use .pagesmith/markdown-guidelines.md for markdown authoring once AI artifacts are installed

Related Files

• AI Assistants
• Agent Prompts Cookbook
• Docs Configuration Reference
• Page Frontmatter Reference