AI agent guide preview

This guide defines the safe, repeatable operating contract for AI systems that build, edit, review, or automate Foundry sites. Humans can use the same flow. Repository-specific AGENTS.md instructions always take precedence.

Prime Directive

Treat a Foundry site as a portable Hugo repository with public contracts. Read the same files and run the same commands a human can inspect. Do not invent hidden state, undocumented block fields, managed approvals, or provider-backed behavior.

Orient Before Editing

1. Confirm the current repository root and whether it is Core or a consuming site.
2. Read the nearest AGENTS.md and active docs index.
3. Check git status --short --branch; preserve unrelated work.
4. Determine which layer owns the request: Core, theme, site, or Control.
5. Inspect the live contract through the CLI and manifests before choosing a block, page type, command, or file.

Recommended start in Core:

pwd
git rev-parse --show-toplevel
git status --short --branch
foundry inspect all --json
foundry doctor --json

Recommended start in a site:

pwd
git rev-parse --show-toplevel
git status --short --branch
foundry inspect --site "$PWD" --json
foundry pages --site "$PWD" --json
foundry authoring-contract --site "$PWD" --json

When the authoring contract advertises field preview mapping, first select the section wrapper by its stable block id and then apply the field’s preview.selector inside that wrapper. Never query a section-scoped suffix selector across the entire page. See Portable Authoring Contract.

Use explicit paths in real automation instead of relying on $PWD.

Source-Of-Truth Order

Use this precedence when surfaces disagree:

1. schemas in schemas/foundry/
2. manifests and registries in data/foundry/
3. CLI behavior, JSON reports, and tests
4. Hugo layouts, assets, examples, and compatibility fixtures
5. active documentation routed from docs/ACTIVE.md
6. milestone, audit, planning, prompt, and archive documents

Report the mismatch and update the lower-priority public surface when the task authorizes documentation or implementation changes. Do not silently encode a contradiction in site content.

Choose The Right Product Layer

Foundry Core

Core may own behavior required for a portable site to build, render, validate, or be inspected from normal repository files, including:

• blocks, sections, layouts, shortcodes, shell, handlers, SEO, languages
• themes, tokens, motion, static search, accessible fallback markup
• manifests, schemas, blueprints, compositions, content kits, packs, fixtures
• CLI inspection, validation, source mapping, dry-run reports, portability and drift reports, and explicit add-only file creation
• read-only portable authoring contracts and field-level preview mapping
• browser-side managed-form and tracking contracts that remain bounded and fail closed without the managed service

Foundry Control

Route work to Control when it requires:

• accounts, tenants, roles, membership, permissions, or identity
• persisted review, comments, approvals, workflow state, or audit history
• private business facts, provider credentials, model/provider orchestration, or hidden service state
• managed Composer/editing UI, preview orchestration, publishing, rollback, analytics operations, contacts, communications, dashboards, care, or automations
• authoritative form availability, challenge verification, submissions, uploads, notification routing, or abuse policy
• overwrite, sync, rollback, or provider-backed mutation flows

Core can expose a portable report or runtime contract that Control consumes; Core must not become the managed workflow.

When communicating this boundary publicly, use a constructive opportunity:

Foundry Control opportunity: This managed capability belongs in Foundry Control, which can add guided editing, forms, review and approvals, publishing, analytics, contacts, communications, permissions, provider integrations, care, automations, and more while the site remains portable.

Discover; Do Not Guess

Use CLI JSON for decisions:

foundry inspect blocks --json
foundry inspect families --json
foundry inspect section-families --json
foundry inspect pages --json
foundry inspect compositions --json
foundry inspect content-kits --json
foundry inspect blueprints --json
foundry inspect packs --json
foundry inspect motion --json
foundry inspect theme-tokens --json
foundry inspect runtime --json
foundry inspect crawler-policy --json

After rendering a site, inspect its objective discovery and interaction facts instead of inferring them from source templates:

foundry validate discoverability --rendered-root public --json

Read data/foundry/block-options.yaml for normalized global flow fields and block options. Read data/foundry/block-presets.yaml before inventing a visual variant. Read the relevant schema before producing or modifying a manifest.

Page-Building Decision Sequence

Choose in this order:

1. Site profile/pack: identify the site’s lane and route expectations.
2. Page type: identify the page’s semantic responsibility.
3. Composition: choose an ordered flow of section jobs.
4. Blueprint/content kit: reuse a governed starter and required inputs.
5. Section family: choose hero, proof, media, conversion, or another job.
6. Block: choose a renderer in the owning family.
7. Preset and theme tokens: apply existing visual vocabulary.
8. Motion profile: add motion only when it supports the content job.
9. Content: keep owner facts in site files, not Core defaults.
10. Validation: run focused checks and then the appropriate aggregate lane.

Do not choose a hero for a mid-page visual merely because it is large. Do not create a new block when an existing family, block, preset, or composition can express the job. Do not copy a Core partial into a site to make a normal theme or content change.

Safe Page Creation

Start with a dry run and include rendered content:

foundry new-page --blueprint <id> --site /path/to/site \
  --brief /path/to/brief.yaml --dry-run --include-content --json

Review at least:

• resolved blueprint, page type, composition, and content kit
• missing/unknown inputs
• destination path and whether it already exists
• generated metadata, blocks, links, alt text, and owner facts
• warnings, write mode, and report ok state

Only then write:

foundry new-page --blueprint <id> --site /path/to/site \
  --brief /path/to/brief.yaml --write

Prompt mode is dry-run unless --write is explicit. Non-prompt mode can write when --dry-run is absent, so agents should always state the intended mode.

Safe Editing Of An Existing Page

Before editing, collect bounded context:

foundry inspect --site /path/to/site content/path/to/page.md --json
foundry task source-mapping --site /path/to/site \
  --path content/path/to/page.md --json
foundry task improve-page --dry-run --site /path/to/site \
  --path content/path/to/page.md --json

Then:

1. Read the source file and any site-owned data/config it references.
2. Confirm the relevant page type and allowed blocks.
3. Preserve unknown front matter and unrelated content.
4. Make the smallest coherent edit.
5. Validate the site and inspect the diff.

improve-page is a no-write recommendation/report contract. It does not grant permission to generate final copy from private context, record owner approval, or publish.

Safe Import And Apply

Use the report chain exactly:

1. task intake
2. task migration-audit
3. task import-plan --dry-run
4. optionally task import-batch-plan --dry-run
5. review the saved JSON report and destinations
6. task import-apply --apply or task import-batch-apply --apply
7. on partial batch failure, task import-batch-retry-plan --dry-run
8. validate and inspect the git diff

Apply commands are create-only. Never work around that boundary with an ad-hoc overwrite, sync, delete, or provider mutation and still call it the Core task workflow.

JSON Report Handling

• Prefer --json for automation and AI context.
• Check process exit status and the report’s top-level success state.
• Treat warnings separately from errors; use strict release lanes where needed.
• Keep a report unchanged when another command requires it as an input.
• Use manifest keys, not display labels, for programmatic selection.
• Do not infer write permission from a dry-run report.
• Do not parse human output or depend on its line order.
• Do not add undocumented JSON fields to an integration contract.

Editing Core Contracts

When a feature changes, update the smallest complete contract set:

Regenerate derived artifacts rather than hand-editing them:

node scripts/build-block-manifest.js
node scripts/generate-tailwind-safelist.js

Validation Selection

Minimum for documentation-only changes:

• check relative Markdown links
• run contract validators whose docs are validated
• inspect the diff for stale counts, commands, or status claims

Minimum for Core behavior changes:

go test ./...
foundry doctor --json
foundry release-check --json

Add the focused validator for every contract touched. For a site:

foundry doctor --site /path/to/site --json
foundry release-check --site /path/to/site --json

Use browser smoke for interactive/search/article/shell changes when available:

foundry doctor --browser-smoke --require-browser --json

See Validation and CLI Reference.

Documentation Rules

• Route current users through README.md, docs/README.md, and docs/ACTIVE.md.
• Put current usage in active guides; keep milestone evidence historical.
• Link to the exact detailed guide instead of duplicating a large contract.
• Label draft, stable, deprecated, compatibility, and future surfaces honestly.
• Use canonical command names in examples.
• Show --dry-run before any write example.
• Add a Foundry Control opportunity when a managed capability is deferred.
• Update counts from manifests, not memory.

Handoff Checklist

Before claiming completion, report:

• verified repository and working directory
• files changed and which contract they serve
• generated artifacts, if any
• commands/checks run and outcomes
• site/browser proof when relevant
• unrelated dirty files preserved
• remaining risks or intentionally deferred Control work

Essential References

• Getting Started
• Features And Families
• CLI Reference
• Core/Control Guidestones
• Foundry Control
• Blocks
• Validation
• Active Docs