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.

Read the canonical Foundry mission and top goals before selecting or evaluating work. Plans may advance that mission but must not redefine it.

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, MISSION.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 version --json
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
foundry preview-build-manifest --site "$PWD" --site-key <key> --route / --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. MISSION.md for product purpose, top-goal order, and product boundaries
2. schemas in schemas/foundry/
3. manifests and registries in data/foundry/
4. CLI behavior, JSON reports, and tests
5. Hugo layouts, assets, examples, and compatibility fixtures
6. active documentation routed from docs/ACTIVE.md
7. current execution and release plans linked from MISSION.md
8. milestone, audit, superseded planning, prompt, and archive documents

The mission governs why and priority; machine contracts and tested behavior govern what the current implementation actually does. Neither may be used to invent behavior absent from the other evidence surfaces.

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.

Prove the Core-only path

When the task is portability or source-migration verification, do not exercise optional managed services merely because the production site declares them. Build the unchanged source with the explicit render-only mode:

HUGO_FOUNDRY_CORE_ONLY=true hugo --gc --minify

The rendered site keeps ordinary content and human fallback messaging, but it does not request attribution policy, managed-form metadata, or tracking. Report this separately from the normal production-integration proof.

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 section-catalog --json
foundry inspect section-styles --json
foundry inspect pages --json
foundry inspect compositions --json
foundry inspect content-kits --json
foundry inspect blueprints --json
foundry inspect packs --json
foundry inspect site-types --json
foundry inspect site-blueprints --json
foundry inspect design-systems --json
foundry inspect visual-examples --json
foundry inspect motion --json
foundry inspect theme-tokens --json
foundry inspect runtime --json
foundry inspect crawler-policy --json
foundry inspect static-origin --json
foundry authoring-contract --site "$PWD" --json

Before presenting a visual choice as proven, inspect visual-examples. Treat demonstration and candidate as useful examples, not release proof. Only a release-ready record with exact Distribution/Core binding, copyable source, desktop/mobile artifacts, and passing required checks supports a public-ready claim. Never infer proof from documentation-portal art or a screenshot alone. Pass-level keyboard, accessibility, and performance claims must resolve to the machine-readable browser audit declared by the example; do not copy pass states from prose or an older screenshot. A dirty development audit is useful proof of the current tree, but it is not a clean release binding. Never describe a Visual Example as aesthetically successful while its visual-acceptance check is not-run, partial, or fail. Geometry, accessibility, performance, and source portability do not establish hierarchy, alignment, readability, responsive composition, or creative quality. Do not describe an artifact as current release proof while artifact-freshness is below pass; regenerate it from the declared source and bind it to the exact release identity first. See Visual Examples.

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

foundry inspect blocks --json exposes required content facts plus every governed variant and design control. foundry inspect families --json exposes the full block-governance catalog, while section-families exposes the author-facing chooser menu. Read data/foundry/block-options.yaml only when you need the source prose behind those normalized controls. Read data/foundry/block-presets.yaml before inventing a visual variant. Read the relevant schema before producing or modifying a manifest.

When evaluating or changing a stable Block, apply Block Control Quality Standard. A renderer is not complete merely because it builds: document its visitor job and simple path, prove governed choices are materially different, retain the portable no-JavaScript floor, and link real desktop/mobile evidence with incomplete promotion gates stated honestly.

When work affects a consuming site, also apply the Consumer Integration Quality Gate. The gate is mandatory for changes that can expose mixed-release assets, lose intrinsic control geometry, override native hidden state, or imply behavior the consumer has not implemented. A Core screenshot or passing Hugo build does not replace exact consumer browser and release-identity evidence.

Before presenting owner-facing Controls, read editor_expansion from the authoring contract. Only complete is a finished routine editor experience. expand-next is a roadmap decision, primitive-first requires the named reusable primitive, and guided-advanced remains source-guided. Never promote a Section automatically, discard unknown source fields, or add local CSS, scripts, services, or hidden data to bypass that decision. See DC03-S7 Editor Expansion Matrix.

Page-Building Decision Sequence

Use the canonical definitions and compatibility rules in Page System. A Page Starter is the public creation contract assembled from a blueprint, content kit, and Markdown template; a Page Flow is the public sequence contract implemented by a composition.

Choose in this order:

1. Site Type and Site Blueprint: choose an open capability recipe, then inspect its route, Page Starter, pack, quality, creative starting points, and Extension resolution. When starting a new site, compare at least two declared directions with foundry new-site --list instead of silently choosing the first one. Preview the selection with foundry new-site before any --write; do not route a planned Site Type through an unrelated scaffold just to produce files.
2. Page Type: identify the page’s semantic responsibility.
3. Page Flow: choose an ordered flow of Section jobs.
4. Page Starter: reuse a governed starter and required inputs.
5. Visitor job: use the chooser family to narrow relevant Section Types.
6. Section Type: author type when a public Type fits; use explicit block only for legacy source, a registered site Extension, or advanced technical work that intentionally retains renderer identity.
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.

A creative_starting_points record is a joined recommendation, not customer content. Use its best_for and avoid_when guidance, keep its creative_levers open, follow its ai_guardrails, and dry-run its brief_example. Never copy a reference Brand System as customer identity, invent facts to complete the brief, or report demonstration Visual Example evidence as release proof.

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.

Never provide type and block on the same Section. Use optional top-level style only with type and only when the catalog declares that exact pair. Do not provide Style with block or invent a Style as a CSS/design escape hatch. Do not translate an existing explicit block to a Type merely because the catalog names a target; legacy alias replacement requires the later no-write migration preview and review contract.

For an existing explicit block, use the Core report instead of inventing a replacement:

foundry task section-migration-preview --dry-run --render \
  --site /path/to/site --path content/path/to/page.md --json

The report proposes exact Type + Style source. A record is ready for review only when complete field validation and isolated render equivalence pass. Proposed source, validation, and render evidence are not permission to copy, apply, approve, or publish the change; Core exposes no Section migration apply command. Render proof uses independent legacy/proposed clones and two passes per variant. If runtime_shadows is non-empty and output differs, converge the reported framework shadow before reconsidering source migration; do not bypass the site’s effective runtime or normalize missing visitor output.

An advanced site may override only foundry/framework/render-section-wrapper.html for reviewed outer-wrapper semantics after declaring that exact mounted path in .planning/foundry-shadow-allowlist.json. Core must continue to own Section identity, Saved Sections, presets, validation, preview metadata, and renderer selection. Do not copy render-sections.html to customize anchors or wrapper markup. A source with build.render: never or draft: true receives complete validation and a not-applicable render result because the normal proof build should not publish it. If both independent builds omit the same route output, the report also marks comparison not-applicable and requires a separate site-readiness decision; never infer that the route should publish.

In Git sites, the report discovers and clones tracked and unignored files only, then follows Hugo’s effective content mounts. This includes mounted source with build.list: never and excludes inactive content trees. Do not force ignored backups, generated output, secrets, or cloud placeholders into the proof boundary. Hydrate a repository-visible dataless file or remove it through normal reviewed source work. A render timeout is a blocker, not permission to skip comparison. The isolated build strips ambient secrets, denies network and write access, and permits only the Hugo/Go module path. It never binds or executes a consumer dependency tree or Node toolchain.

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

For a new site direction, first inspect site-blueprints --json, select one of its declared creative starting points, and use that record’s Page Starter and copyable fictional brief. Replace fictional values with owner-approved facts; the supplied brief is shape and creative-orientation evidence, not final copy.

Review at least:

• requested and resolved Page Starter identity, including any compatibility alias
• resolved Page Type, Page Flow, blueprint, and content kit
• missing/unknown inputs
• destination path and whether it already exists
• generated metadata, Section Types and Styles, 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. Confirm the consumer supports the report and region schema versions.
2. Bind every proposed text edit to the reported source identity and region precondition.
3. Read the source file and any site-owned data/config it references.
4. Confirm the relevant page type and allowed blocks.
5. Preserve protected regions, unknown front matter, and unrelated content byte-for-byte.
6. Write only through a compatible conditional-write contract; stale, incomplete, overlapping, or unrecognized region evidence is a stop condition.
7. Make the smallest coherent edit, then 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. source-mapping and patch-preview are also no-write contracts; their preconditions are evidence for a future or external guarded write, not permission to mutate the repository.

For a structured field declared by the authoring contract, consume the document.sections[].fields[] evidence from source-mapping and submit a foundry.structured-field-proposal.v1 to patch-preview with --field-proposal-report. Treat absent, protected, stale, multiline, opaque, or unknown fields as source-only. Never infer front-matter byte ranges from a field path in Control or another consumer.

For one coherent page draft containing several declared fields and/or editable Markdown/source regions, submit foundry.multi-change-proposal.v1 with --multi-change-proposal-report. Require foundry.patch-preview.v4, atomic: true, the unchanged-span and protected-fact evidence, and the exact proposed source identity. One invalid item invalidates the whole proposal. external_apply_ready is still evidence, not authority; only the authorized consumer may perform one conditional draft write after rechecking repository, revision, actor, and idempotency preconditions.

Before asking an external system to build a preview, generate foundry.preview-build-manifest.v1 for the exact route and tree. Treat any error diagnostic as a stop condition. Permission requests are not grants, and the report is not an isolation boundary; the external consumer must enforce operator policy in an approved sandbox.

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:

go run ./cmd/foundry generate block-manifest

Core v1 uses shipped CSS, tokens, layouts, and Hugo Pipes; it does not require or execute a utility-package toolchain.

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

For delivery, cache, security-header, atomic-release, rollback, or restoration work, also run:

foundry static-origin /path/to/site
foundry inspect static-origin --json
foundry validate static-origin --site /path/to/site --json

Begin site delivery work with prompts/CODEX-STATIC-ORIGIN-AUDIT.md. The prompt is read-only-first and cannot grant permission to deploy or change provider state.

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