CLI reference preview

The Go foundry CLI is the canonical public tool for humans, CI, AI agents, and Foundry Control integrations. It reads normal repository files, emits human summaries by default, and emits deterministic structured reports with --json.

Invocation

From a Core checkout:

go run ./cmd/foundry --help

As an installed binary:

go install github.com/jerrybroughton/likestyle-foundry-core/cmd/foundry@v1.1.11
foundry --help
foundry help advanced
foundry version

Direct tagged installation requires repository access. The source-tree form remains available from an approved Core checkout.

The commands are identical in both forms. Examples below use foundry.

Common Conventions

Human-friendly aliases exist for some commands, but automation should use the canonical names documented here. Treat JSON field names and manifest contracts as APIs; do not parse human summaries.

Command Map

Version

foundry version [--json]
foundry --version

Human output features the installed Foundry Core number. --json emits the stable foundry.version.v1 report with the product, version, release channel, Go version, and available Git revision/modified evidence. Tagged installs use the immutable Go module tag; source-tree builds report a development identity.

foundry version
foundry version --json

See Versioning And Releases.

Migrate A Site

foundry migrate site --source <source-directory> [--core-version <vX.Y.Z>] [--apply --destination <new-directory>] [--yes] [--json]

Advanced: foundry migrate site --capture <capture.json> [--scope <scope.json>] [--brief <brief.json>] [--core-version <vX.Y.Z>] [--apply --destination <new-directory>] [--rights-attested] [--yes] [--json]

The normal input is a local directory of Hugo/Foundry source files. Preview is the default. It inventories portable content, layouts, assets, static files, data, configuration, and human documentation without writing. Generated Hugo output, installed dependencies, vendored .foundry snapshots, browser output, Node package files, project scripts, and the root foundry-control.yaml file are excluded. Local module replacements are removed, Core is pinned to the requested version, and the destination build command becomes direct Hugo.

foundry migrate site --source /path/to/source-site
foundry migrate site --source /path/to/source-site \
  --apply --destination /path/to/example-foundry

The source is never modified. Apply creates a sibling-staged tree atomically, rehashes every input after preview, refuses symlinks and special files, and can recognize an exact previous result. Existing changed or extra destinations fail without mutation. --json preview is noninteractive; JSON apply requires --yes. Optional Control declarations inside ordinary Hugo configuration are preserved and reported for explicit review, but the migration command itself does not call Control or AI.

To verify the migrated site as portable Core without changing its production configuration, use the explicit render-only switch:

HUGO_FOUNDRY_CORE_ONLY=true hugo --gc --minify

This keeps ordinary content, navigation, attribution, and managed-form fallback messaging visible while suppressing optional attribution-policy, form-metadata, and tracking requests. The same behavior can be declared in a dedicated Hugo environment with params.foundry.core_only: true. It does not rewrite source, grant approvals, or disable normal production integrations unless that build explicitly enables the mode.

For public sites whose source is unavailable, --capture remains the advanced evidence path. It accepts reviewed --scope and --brief reports and keeps the rights-attestation requirements documented in Site Import Contracts. Exactly one of --source or --capture is required. Direct URL input is not a shipped command.

See Site Import Contracts and the LikeStyle whole-site proof.

Static Origin

foundry static-origin [site-path|--site <site-path>] [--json]

This is the human-facing delivery command. With no path, it explains the six Static Origin product rules in plain language. With a site path, it checks the site’s data/foundry/static-origin.json and referenced server config without requiring a Core source checkout.

foundry static-origin
foundry static-origin /path/to/site

Use --json with a site path for integrations. Use foundry inspect static-origin --json for the complete machine profile.

Check, Release Check, Build, And Doctor

foundry check [site-path|--site <site>] [--root <core>] [--include-drift-audits] [--skip-core] [--skip-hugo] [--strict-warnings] [--json]
foundry build [--root <core>] [--site <site>] [doctor flags] [--json]
foundry release-check [--root <core>] [--site <site>] [doctor flags] [--json]
foundry doctor [--root <core>] [--site <site>] [doctor flags] [--json]

check is the normal human and CI starting point. It runs the in-process Go contract validators and, for a site, the bounded site and Hugo smoke checks. It does not invoke an external toolchain or include the compatibility fixture fleet, generated report-contract checks, visual/stable-layout evidence, or browser proof. Human output is emitted as each check completes. Failures include a copyable focused diagnostic command. --json emits the same job as foundry.check.v1 without progress text.

Doctor flags:

doctor is a compatibility route: without browser flags it runs the same Go-native routine checks while retaining the historical foundry.doctor report identity. Its browser flags retain the legacy full-lane behavior for old callers. build is a deprecated no-write compatibility route over the same routine checks; it does not produce site output. Use Hugo directly when the job is an actual build. In site mode, release-check sets strict warnings and includes drift audits by default. New browser release proof should use release-check.

foundry check
foundry check /path/to/site
foundry check --json
foundry doctor --json
foundry release-check --site /path/to/site --json
foundry release-check --browser-smoke --require-browser --json

On Safari 26 for macOS, keep the Safari automation window in its normal (unzoomed) state. The browser lane reapplies a requested window rectangle up to three times and returns an actionable infrastructure error if Safari keeps the automation window zoomed; it does not call Safari’s hanging minimize endpoint. Safari’s minimum automation width is 336 CSS pixels, so an explicit 320-pixel fixture scenario runs at that platform floor and must still pass all of its responsive geometry assertions.

Inspect

For rendered alignment, gap and containment diagnostics, use foundry layout-check --rendered-root public --site /path/to/site. Native browser setup, contract declarations, coverage states and the contract-only exit behavior are documented in Layout Check. This explicit browser lane does not change the scope of routine check.

Inspect Core contracts:

foundry inspect [target] [--root <core>] [--json]

Targets:

• all
• blocks
• families
• pages
• handlers
• compositions
• content-kits
• packs
• site-blueprints (aliases: site-types, site-recipes)
• design-systems (aliases: theme-families, brand-systems)
• section-families
• section-catalog
• section-styles (aliases: styles, family-scorecards)
• visual-examples (aliases: rendered-examples, visual-proofs)
• discovery-gaps
• motion
• theme-tokens
• blueprints
• scaffolds
• runtime
• crawler-policy
• static-origin
• manifests

With no target, Core inspection defaults to the complete inventory.

foundry inspect --json
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 site-types --json
foundry inspect design-systems --json
foundry inspect visual-examples --json
foundry inspect discovery-gaps --json
foundry inspect theme-tokens --json
foundry inspect crawler-policy --json
foundry inspect static-origin --json

inspect blocks includes required content facts, every block variant and design field, the global section-flow controls, and aggregate control counts. inspect families returns the full block-family governance catalog rather than only family keys. inspect section-families returns the semantic chooser menus; every registered block must appear in at least one. inspect section-catalog returns the complete public Section Type and renderer disposition matrix. It resolves each Type’s capabilities and recommended presets from its chooser family while preserving the separate technical renderer family, compatibility target, migration posture, and rollback. inspect section-styles returns every cataloged Type+Style presentation contract plus the 18 family scorecards. It exposes responsive, accessibility, no-JavaScript, token-inheritance, maintenance, and rollback facts without claiming that separate representative human proof is complete. inspect site-types returns the open Site Type capability recipes and their technical Site Blueprint resolution. It includes best-for/not-for guidance, starter routes, repeatable route families, navigation intent, quality profiles, and explicit Brand System, Theme Family, facts, manual-assembly, and Extension ownership boundaries. inspect site-blueprints also includes each recipe’s joined creative starting points: executable route, Theme Family, reference Brand System, page preset, Visual Example proof state, copyable brief, creative levers, human steps, and AI guardrails.

inspect design-systems returns Theme Family art-direction grammar, reference Customer Brand Systems, inheritance and ownership policies, three mapped reference outcomes, source evidence, and independent brand/theme rollback.

inspect visual-examples joins discoverable product keys to real Hugo fixture routes, copyable source, source mapping, viewport evidence, required check states, limitations, invalidation rules, and exact release binding. Its counts separate demonstrations from release-ready proof and expose uncovered subject kinds. Portal art and screenshots alone never satisfy this contract. See Visual Examples.

Site inspection resolves authored sections[].type entries and reports the authored identity_key, identity_value, public section_type, and resolved block key separately. Explicit legacy blocks keep identity_key: block and their exact renderer key.

Inspect a site or one page:

foundry inspect [site|route|content-path] --site <site> [--root <core>] [--json]

foundry inspect --site /path/to/site --json
foundry inspect site --site /path/to/site --json
foundry inspect /services/example/ --site /path/to/site --json
foundry inspect content/services/example/index.md --site /path/to/site --json

The page report includes bounded repo-visible context, source mapping, blocks, page/blueprint relationships, authored or inferred discovery kind, authored seo.image and service type, service-schema eligibility, canonical review date, and other contract facts suitable for an editor or AI agent.

Authoring Contract

foundry authoring-contract --site <site> [--root <core>]
  [--core-version <version>] [--site-key <key>] [--commit-sha <sha>] [--json]

Emits foundry.authoring-contract.v1 directly for Foundry Control or another portable editor. The report derives its block inventory from the Core block manifest, both family catalogs from their manifests, normalized global and per-block design controls from block options, typed editor fields from block schemas, the editor-expansion decision for every public Section Type, a portable Hugo menu model, template structure from blueprints, and site identity from an explicit value or optional foundry-control.yaml plus Git. Without a managed site key, Core derives a portable key from the site directory name. It does not write to Core or the site.

blocks[].design_options exposes every registered block’s variants and design controls. section_design_controls exposes the shared section-flow controls. menus advertises multiple and nested menus, destination types, ordering, custom parameters, recommended menu roles, and all native Hugo menu-entry fields; when present, its source_path points to the site’s normal Hugo menu config.

Typed fields include a source-relative path and a preview object with a section scope and deterministic CSS selector. Consumers must query that selector inside the already-selected section wrapper. See Portable Authoring Contract for the mapping algorithm and compatibility rules.

Blocks that have completed the typed-Control contract include an additive editor_projection with human recommendations, complete control groups, recommended/inherited/customized states, and safe reset semantics. Absence of that projection means the block’s technical fields or design options must not be presented as a completed first-class owner editor.

editor_expansion makes that rule explicit across the full public Section Catalog. Only complete is a finished routine Control; expand-next, primitive-first, and guided-advanced are safe planning and source-guidance states. Automatic projection is disabled and the Hugo repository remains the source of truth.

When the effective site proves Math Notation V1, capabilities.math_notation advertises its exact delimiters, MathML renderer, surface, limitations, and foundry.math-validation.v1 validation boundary. The field is omitted for inactive, misconfigured, overridden, missing, or unsupported runtime evidence.

foundry authoring-contract --site /path/to/site --json \
  > authoring-contract.json

--core-version, --site-key, and --commit-sha are snapshot overrides for packaged or exported repositories where Git/config identity cannot be resolved. The schema is schemas/foundry/authoring-contract.schema.json.

Effective Authoring Inventory

foundry effective-authoring-inventory --site <site> [--root <core>]
  [--site-key <key>] [--commit-sha <sha>] [--core-version <version>]
  [--hugo-version <version>] [--json]

Resolves inert data/foundry/authoring/*.json declarations across site, configured theme, materialized module, and Core layers. Core derives source and renderer hashes and emits foundry.effective-authoring-inventory.v1; it does not invoke Hugo, accept repository commands, or write. Missing renderers fall back to source-only and unknown required capabilities fail closed only at their declared scope. See Effective Authoring Inventory.

Preview Build Manifest

foundry preview-build-manifest --site <site> --site-key <key>
  --route </path/> [--route </other/>] [--hugo <executable>] [--json]

Emits foundry.preview-build-manifest.v1 directly. --site-key and at least one --route are required; routes are typed data and cannot supply a command, argv, shell fragment, destination root, or arbitrary environment value. The optional --hugo selects an operator-owned executable whose version and bytes are hashed into the report.

The command scans the Git working tree, materialized local modules, Hugo mounts, toolchain hashes, and permission requests. It may invoke the operator-selected executable only to read hugo version; it does not run a build or server, write, grant a permission, or persist workflow. Error diagnostics keep the JSON structurally valid and cause exit 1 so unsupported topology cannot be mistaken for a safe plan. See Preview Build Manifest.

foundry preview-build-manifest --site /path/to/site \
  --site-key customer-site --route /journal/example/ --json

Pages

foundry pages [site-path] [--root <core>] [--site <site>] [--json]

Inventories site content and reports page/route-floor facts.

foundry pages --site /path/to/site --json

New Site

foundry new-site --list [--root <core>] [--json]
foundry new-site <destination> --site-type <key> --direction <key>
  [--core-version <version>] [--theme-version <version>]
  [--module <path>] [--title <text>] [--base-url <url>]
  [--dry-run|--write] [--force] [--root <core>] [--json]
  [--field value...]

new-site is the v1 primary creation path. --list exposes every Site Type, its Site Blueprint, and at least two creative directions with the associated Theme Family and fictional reference Brand System. Directions without a finished route-floor scaffold remain visible as planned, but the command refuses to manufacture an incomplete site from them.

Creation defaults to dry-run. The report names every foundation file and Page Starter route, exposes SHA-256 checksums in JSON, and records that Node and pnpm are not required. --write creates ordinary Hugo source; existing generated paths are refused unless --force is explicit.

foundry new-site --list
foundry new-site ./my-site \
  --site-type local-service \
  --direction local-service-clear
foundry new-site ./my-site \
  --site-type local-service \
  --direction local-service-clear \
  --title "My Service Business" \
  --write
cd ./my-site && hugo server --buildDrafts

An installed release uses its own immutable version for the generated go.mod. Source-tree development builds require --core-version; this keeps an unreleased checkout from silently becoming a portable dependency claim. The generated reference Brand System must be replaced with customer-owned identity values before publish.

New Page

foundry new-page [--blueprint <id>] [--brief <file>] [--content-kit <id>]
  [--prompt] [--dry-run|--write] [--include-content] [--force]
  [--root <core>] [--site <site>] [--json] [--field value ...]

Key behavior:

• Briefs may be Markdown, YAML, or JSON.
• Explicit --field value arguments override brief values; dashes normalize to underscores (--primary-cta-url becomes primary_cta_url).
• --prompt asks only for unresolved required inputs and defaults to dry-run.
• --include-content includes rendered page content in the report.
• Non-prompt mode writes unless --dry-run is supplied.
• Existing files are refused unless --force is supplied.
• Use foundry inspect blueprints --json to discover IDs and input contracts.
• Use foundry inspect site-blueprints --json to discover joined creative directions and copyable fictional briefs for a new site.
• Page Starter aliases are declared in blueprint source. Reports expose the requested ID, canonical ID, alias status, Page Type, Page Flow, content kit, and type-first source contract. See Page System.

foundry new-page --blueprint service --prompt --dry-run --json
foundry new-page --brief /path/to/brief.yaml --site /path/to/site \
  --dry-run --include-content --json
foundry new-page --blueprint contact --site /path/to/site --prompt --write

Scaffold

foundry scaffold creative-route-floor|local-service-route-floor
  [--dry-run] [--include-content] [--force]
  [--root <core>] [--site <site>] [--json] [--field value ...]

Scaffold writes by default. Use --dry-run --json first.

foundry scaffold creative-route-floor --site /path/to/site \
  --artist-name "Creative Studio" --artist-role "Photographer" \
  --primary-email hello@example.com --dry-run --json

foundry scaffold local-service-route-floor --site /path/to/site \
  --business-name "Local Business" --service-name "Primary Service" \
  --city-name "Sample City" --region-name "Region" \
  --primary-phone "(555) 555-0100" --dry-run --json

See Creative Lane and Local Service Scaffolding.

Route Floor And Quality Floor

foundry route-floor local-service-route-floor
  [--root <core>] [--site <site>] [--json] [--field value ...]

foundry quality-floor local-service-route-floor
  [--root <core>] [--site <site>] [--json] [--field value ...]

Both commands are read-only. Route floor checks required/optional route coverage; quality floor checks local-service quality evidence and reports gaps. Established sites can map portable page roles to local routes, or document a role as not required, through data/foundry/route-floor.json. Both reports consume the same profile and expose its path in JSON output.

foundry route-floor local-service-route-floor --site /path/to/site --json
foundry quality-floor local-service-route-floor --site /path/to/site \
  --business-name "Local Business" --service-name "Primary Service" \
  --city-name "Sample City" --region-name "Region" --json

Task Commands

The backing contract is data/foundry/task-contract-manifest.json. Core tasks operate only on repo-visible inputs. Commands reject overwrite, delete, sync, provider, and managed-workflow modes.

Read-Only Reports

foundry task intake [site-path] [--root <core>] [--site <site>] [--json]
foundry task migration-audit [site-path] [--root <core>] [--site <site>] [--json]
foundry task file-presence [site-path] [--path <relative>] [--expect <relative> ...]
  [--root <core>] [--site <site>] [--json]
foundry task source-mapping [site-path] [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task effective-page [site-path] --path <content-relative>
  [--root <core>] [--site <site>] [--json]
foundry task site-update-report [site-path] --source <file> --blueprint <id>
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task validate-improve-page-report --report <file>
  [--root <core>] [--site <site>] [--json]
foundry task validate-site-capture --report <file> [--json]
foundry task qualify-site --dry-run --capture <file> [--json]
foundry task validate-site-qualification --report <file> [--json]
foundry task validate-site-scope --capture <file>
  --qualification <file> --scope <file> [--json]
foundry task plan-site-conversion --dry-run --capture <file>
  --qualification <file> --scope <file> [--json]
foundry task validate-site-conversion-plan --capture <file>
  --qualification <file> --scope <file> --plan <file> [--json]
foundry task generate-site-materialization-bundle --dry-run --capture <file>
  --qualification <file> --scope <file> --plan <file> --brief <file> [--json]

The whole-site contracts are documented in Site Import Contracts. They are distinct from the record-oriented, single-blueprint import-plan workflow.

migration-audit also joins authored Sections to Core’s declared compatibility field aliases. Each Section is classified as upgrade-only, normalization-available, or manual-review. An upgrade-only result means a Core upgrade is sufficient. normalization-available identifies optional canonical-field cleanup while the compatibility alias remains supported. manual-review means both names are present and Core will not guess which value should win. The audit is always read-only: automatic_rewrite and apply_available remain false, and no consumer source is materialized or changed. A future apply path must first provide exact-source preview, stale-byte preconditions, rollback, conflict review, and rendered-equivalence proof.

effective-page joins exact source evidence to the current type/style and legacy block Section identities and typed field contracts. Its foundry.effective-page.v1 output lists every authored Section in order, semantic preview anchors, ordinary Markdown as source-only, protected islands, and unmapped scalar facts. coverage_complete means nothing was silently omitted; writes: false, mutation_authority: none, and mutation_authorized: false remain absolute. See Effective Page Report.

Dry-Run-Only Reports

foundry task section-migration-preview [site-path] --dry-run [--render]
  [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task patch-preview [site-path] --dry-run
  [--source-mapping-report <file>]
  [--proposal-report <file>|--field-proposal-report <file>|
   --multi-change-proposal-report <file>]
  [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task layout-repair [site-path] --dry-run
  --layout-report <file> --route </route/> --check <id> --section <id>
  --field <content-or-design.path> [--replacement <value>]
  [--root <core>] [--site <site>] [--json]
foundry task improve-page [site-path] --dry-run [--path <relative>]
  [--root <core>] [--site <site>] [--json]
foundry task import-plan [site-path] --dry-run --source <file> --blueprint <id>
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task import-batch-plan [site-path] --dry-run --dry-run-report <file>
  --source <file> --blueprint <id>
  (--record-id <id>|--record-index <n>)...
  [--content-kit <id>] [--root <core>] [--site <site>] [--json]
foundry task import-batch-retry-plan [site-path] --dry-run
  --batch-apply-report <file> [--root <core>] [--site <site>] [--json]

section-migration-preview finds only cataloged preview-required compatibility aliases. It emits the exact prior source, an exact no-write block to governed type + style preview, complete YAML/TOML/JSON validation, Stable/LTS support, exact rollback, and optional isolated Hugo before/after hashes. A proposal becomes ready-for-review only when validation and the applicable render gate pass; apply_available is always false. Sources that declare build.render: never or draft: true must pass complete source validation and are reported as not-applicable for render comparison. When both independent proof builds omit the same route output, render comparison is also not-applicable; a separate site-readiness gate must establish whether that route is intended to publish. One-sided missing output remains a failure.

layout-repair is a narrow bridge from a failed, source-visible layout-check relationship to an existing normal authoring control. It re-maps the current source and fails closed if the report is stale. A human or AI chooses an already supported replacement value; Core then returns only an exact external patch preview. The command never chooses a value, deletes a field for a reset, writes a source file, or owns approval and publishing.

For a Git site, discovery and temporary clones include tracked and unignored files only. Within that repository-visible set, discovery follows Hugo’s effective content mounts, including sources with build.list: never, instead of assuming every file below content/ is active. Ignored backups, generated output, secrets, cloud placeholders, inactive content trees, and other local debris do not enter release evidence. A repository-visible macOS dataless file fails immediately with its path, and each Hugo render has a two-minute timeout. --render builds independent legacy and proposed temporary source clones twice each so generated inputs stabilize symmetrically. It uses Hugo and Go module replacements only, reports critical site-owned runtime shadows and the declared advanced Section wrapper Extension, and never builds from or writes to the original site. Proof builds remove ambient secrets, deny network access and writes, and never bind or execute a consumer dependency tree or package toolchain. See DC02-S7 Fleet Release Evidence.

improve-page is the canonical owner-facing page-improvement report. It may expose facts, gaps, preview copy, guardrails, and portable decision descriptors, but it does not persist approvals, generate final copy from private context, or publish. Those are Foundry Control responsibilities.

Markdown content records from source-mapping use foundry.source-mapping.v2 and include exact source identity plus half-open byte ranges for editable Markdown and protected front matter, shortcode, raw HTML, template, and fenced-code islands. When patch-preview consumes that saved report, it rejects stale or tampered source evidence before returning context. Compatible saved V1 reports remain accepted for their original scalar and region contracts; they do not acquire V2 structural-list authority. Both commands remain no-write. See Source Mapping And Region Preconditions.

When --proposal-report supplies a foundry.source-region-proposal.v1 document, patch preview emits foundry.patch-preview.v2 with the complete proposed UTF-8 source, exact replacement operations, unchanged spans, preserved region identities, and original/proposed byte hashes. Core still writes nothing and apply_available remains false; external_apply_ready means only that a separate authorized consumer has complete conditional-write evidence.

Saved Section bundles under content/_foundry/saved-sections/<id>/index.md are reported with foundry.saved-section-linkage.v1 evidence: exact source revision, every affected route, non-published build state, no-instance-override state, and the explicit detach contract. A page links one with saved_section: <id> and may not add per-instance overrides.

When --field-proposal-report supplies a foundry.structured-field-proposal.v1 document, patch preview emits foundry.patch-preview.v3. Core re-resolves the concrete document, section, declared authoring field, exact scalar bytes, source hash, and field hash before returning the complete proposed source. YAML, TOML, and JSON scalar values keep their existing representation where safe; multiline, opaque, undeclared, or unsupported values remain protected. The command never writes, and custom front matter outside the one proven scalar remains byte-for-byte unchanged.

Source mapping can also emit additive foundry.structured-controls.v1 groupings for declared object and array fields. Scalar controls carry choice, reference, and numeric-bound constraints; declared booleans, integers, and finite numbers retain native YAML, TOML, or JSON types. Existing child leaves retain the same exact V3/V4 field evidence. Duplicate or missing item identities fall back to explicit indexes and unknown children remain protected. Structural list operations are available only for declared block-style YAML object sequences with exact source-mapping V2 container and item preconditions.

When --multi-change-proposal-report supplies a foundry.multi-change-proposal.v1 document, patch preview emits foundry.patch-preview.v4. One bounded proposal may combine several declared scalar fields and editable source or Markdown regions on one exact page. Core validates the complete set before returning one proposed source; a stale, duplicate, protected, ambiguous, no-op, oversized, out-of-root, or overlapping change rejects the entire set.

V4 returns one atomic: true patch with exact replacement evidence, unchanged spans, preserved non-overlapping regions, protected unknown scalar facts, and the complete proposed UTF-8 identity. external_apply_ready is conditional write evidence for an authorized consumer, never permission. Core reports can_apply: false, writes: false, and apply_available: false.

When the input is foundry.multi-change-proposal.v2, patch preview emits foundry.patch-preview.v5. V2 retains every V1 scalar and Markdown operation and adds structured-list-add, structured-list-remove, and structured-list-move for declared block-style YAML object sequences. V5 includes explicit structured_lists evidence and the same atomic no-write guarantees. TOML, JSON, flow-style or anchored YAML, and ambiguous shapes stay unavailable instead of being reparsed or rewritten by a consumer.

Explicit Add-Only Apply

foundry task import-apply [site-path] --apply --dry-run-report <file>
  --source <file> --blueprint <id>
  (--record-id <id>|--record-index <n>) [--content-kit <id>]
  [--root <core>] [--site <site>] [--json]

foundry task import-batch-apply [site-path] --apply --batch-plan-report <file>
  --source <file> --blueprint <id> [--content-kit <id>]
  [--root <core>] [--site <site>] [--json]

Apply is create-only, requires the reviewed report chain, and is designed to be idempotent. Existing destinations are not overwritten. Partial batch failures produce a report that can feed import-batch-retry-plan.

Example safe chain:

foundry task import-plan --dry-run --site /path/to/site \
  --source data/import/services.csv --blueprint service \
  --content-kit service-detail-starter --json > reports/import-plan.json

foundry task import-apply --apply --site /path/to/site \
  --dry-run-report reports/import-plan.json \
  --source data/import/services.csv --blueprint service \
  --content-kit service-detail-starter --record-id Botox --json

Upgrade And Drift Reports

foundry upgrade [--dry-run] [--rehearse] [--to <bundle-or-version>]
  [--release-catalog <path>] [--root <core>] [--site <site>] [--json]
foundry upgrade owner-inventory [--release-catalog <path>]
  [--root <core>] [--site <site>] [--json]
foundry upgrade portability [--root <core>] [--site <site>] [--json]
foundry upgrade starter-drift [--root <core>] [--json]
foundry upgrade framework-drift [--root <core>] [--json]

The base upgrade command is read-only; apply/write mode is not implemented. Human output is the default, and --json exposes the same deterministic facts for AI agents and other tools. The reports cover:

• target bundle/version planning
• explicit supported-path qualification, one catalog-declared hop at a time
• disposable installed-versus-target differential rehearsal without changing the source site
• site-owned versus framework-owned files
• portability warnings
• starter/template drift
• framework drift scorecards

From a consumer checkout, foundry upgrade discovers the site, its local Core replacement, and a catalog at .foundry/release-catalog.json, .foundry/modules/distribution/release-catalog.json, or release-catalog.json. Explicit flags always win. Discovery is local and read-only; no missing dependency or catalog is downloaded.

When --release-catalog points to the digest-bound v2 catalog exported by Foundry Distribution, both the base report and owner inventory include a foundry.release-status.v1 projection. It reports the installed bundle, current stable and LTS versions, support state, owner status, and the exact source-to-target upgrade impact. It does not perform a network lookup or write to the site. Historical releases without declared support metadata are reported as unclassified, not guessed.

The base report also emits foundry.upgrade-qualification.v1. It never infers compatibility from SemVer proximity, a point-version relationship, or LTS status. Every source-to-target hop must be declared by the target release. The human states are:

• You are current — stay here for a supported current LTS/default target;
• Safe update available only for one stable verify-only hop with no site changes, no unresolved site drift, and an exact target Core component pin;
• Guided migration available for optional adoption, required migration, preview/unclassified targets, or multi-hop paths; and
• Cannot safely upgrade automatically for breaking paths. Unknown or contradictory contracts are blocked.

--rehearse clones only repository-visible site files into two disposable workspaces, rewrites relative local module replacements inside the clones, renders the installed Core baseline and the candidate --root, and reports a file-level differential with route losses. The receipt binds catalog, manifest, site lock, go.mod, source, runtime, and platform evidence. Temporary homes, disabled Go module downloads, and Hugo HTTP denial reduce ambient access. The report still states that allowed child processes are not OS-network-sandboxed. A passing render against a dirty checkout is compatibility evidence, not exact release proof. Rehearsal never updates a lockfile, dependency, source file, or release.

Catalog SHA-256 fields prove byte identity, not publisher authenticity. Any managed apply lane must independently verify trusted Distribution provenance, authorization, rollback readiness, and operational policy. Those persisted and mutating responsibilities belong in Foundry Control, not Core.

The machine contracts are schemas/foundry/upgrade-report.schema.json, schemas/foundry/upgrade-baseline.schema.json, schemas/foundry/upgrade-qualification.schema.json and schemas/foundry/upgrade-rehearsal.schema.json.

Foundry Control opportunity: consider Foundry Control for a managed upgrade workflow with persisted review, approvals, branch diffs, validation, publishing, and operational rollback. Those workflows do not live in portable Core.

foundry upgrade --dry-run --to v0.2.0 --site /path/to/site --json
foundry upgrade --dry-run --release-catalog /path/to/release-catalog.json --site /path/to/site --json
foundry upgrade --release-catalog /path/to/release-catalog.json \
  --site /path/to/site --to stable --rehearse
foundry upgrade owner-inventory --site /path/to/site --json
foundry upgrade portability --site /path/to/site --json
foundry upgrade starter-drift --json
foundry upgrade framework-drift --json

Validate Commands

foundry validate <target> [target flags] [--json]

Target-specific forms:

foundry validate block-contracts [--root <core>] [--json]
foundry validate block-governance [--root <core>] [--json]
foundry validate content-kits [--root <core>] [--json]
foundry validate creative-lane [--root <core>] [--json]
foundry validate runtime [--root <core>] [--json]
foundry validate math [site-path] [--root <core>] [--site <site>] [--json]
foundry validate crawler-policy [--root <core>] [--json]
foundry validate static-origin [--root <core>] [--site <site>] [--json]
foundry validate discoverability --rendered-root <public>
  [--max-review-age-days <days>] [--strict] [--json]
foundry validate search-index --rendered-root <public> [--json]
foundry validate discovery-fields [--root <core>] [--site <site>] [--json]
foundry validate motion [--root <core>] [--json]
foundry validate feature-flags [--root <core>] [--json]
foundry validate documentation [--root <core>] [--json]
foundry validate workflows [--root <core>] [--json]
foundry validate shell [--root <core>] [--json]
foundry validate section-families [--root <core>] [--json]
foundry validate section-catalog [--root <core>] [--json]
foundry validate section-styles [--root <core>] [--json]
foundry validate site-blueprints [--root <core>] [--json]
foundry validate design-systems [--root <core>] [--json]
foundry validate visual-examples [--root <core>] [--json]
foundry validate scaffolds [--root <core>] [--json]
foundry validate tasks [--root <core>] [--json]

foundry validate compatibility-fixtures [fixture ...] [--root <core>]
  [--keep-temp] [--verbose] [--browser-smoke] [--require-browser] [--json]

foundry validate quality [--root <core>] [--rendered-root <public>]
  [--skip-source] [--json]

foundry validate site-blocks [site-path] [--root <core>] [--site <site>] [--json]
foundry validate site-shadows [site-path] [--root <core>] [--site <site>]
  [--allowlist <file>] [--verbose] [--json]
foundry validate shell-overrides [site-path] [--site <site>]
  [--allowlist <file>] [--verbose] [--json]

--keep-temp retains materialized compatibility fixtures for debugging. --require-browser turns a browser skip into failure. --skip-source on the quality validator is useful when checking only an already-rendered tree. --strict on the discoverability validator promotes review warnings to errors; its default review-age window is 730 days. The validator also reports advertised feed and feed-entry counts and fails malformed or inconsistent structured-data/feed facts that can be proved from the rendered tree.

Internal-Link Opportunity Report

foundry inspect link-opportunities --rendered-root <public> \
  [--limit <count>] [--json]

The read-only foundry.internal-link-opportunities.v1 report scores unlinked, indexable page pairs using rendered Pagefind series, topic, tag, audience, and kind filters. It defaults to 100 results, favors a lower-inbound target, and includes the shared values behind every score. It does not generate anchor text, modify content, contact a provider, or persist a decision. JSON is governed by schemas/foundry/internal-link-opportunities.schema.json.

Static Search Index

foundry search build --rendered-root <public> [--pagefind <executable>] [--json]
foundry validate search-index --rendered-root <public> [--json]

foundry search build invokes a standalone Pagefind executable from --pagefind or PATH; it never downloads Pagefind and does not require Node. After a successful build it records pagefind/foundry-search-index.json with deterministic rendered and index digests. Validation fails when the index is incomplete, modified, or stale relative to Hugo output.

Discovery Change Report

foundry discovery-changes \
  --before-rendered-root <previous-public> \
  --after-rendered-root <candidate-public> [--json]

The read-only report compares indexable routes, canonical URLs, and rendered digests. JSON uses foundry.discovery-change-report.v1 and includes portable Foundry Control handoff descriptors. Core does not contact search providers, store credentials, persist approvals, or submit URLs.

Foundry Control opportunity: see Foundry Control for managed review, publishing, Search Console or Bing operations, permissions, and operational history.

Static Origin Validation Report

foundry validate static-origin is read-only. Without --site, it validates Core’s public profile, schemas, prompt, documentation sources, cache defaults, security-header requirements, and atomic release contract. With --site, it also validates data/foundry/static-origin.json and every referenced repo-visible server config file.

The site declaration contains only its adapter, config file paths, and real exceptions. JSON output uses foundry.static-origin-validation.v1; the published report schema is schemas/foundry/static-origin-validation-report.schema.json.

This command never connects to a server, changes provider state, deploys, persists approval, or performs rollback. See Static Origin.

Math Validation Report

foundry validate math is read-only. It verifies the target site’s effective Core capability, rejects malformed V1 delimiter pairs in Markdown source, and runs Hugo against a temporary destination that is deleted afterward. It never writes the site repository.

With --json, it emits foundry.math-validation.v1:

{
  "report_schema": "foundry.math-validation.v1",
  "command": "foundry validate math",
  "ok": false,
  "site": "/absolute/path/to/site",
  "runtime": {
    "core_version": "v0.1.42",
    "hugo_version": "v0.164.0+extended"
  },
  "capability": {
    "status": "active",
    "code": "active"
  },
  "summary": {
    "errors": 1,
    "warnings": 0
  },
  "findings": [
    {
      "code": "invalid_math_notation",
      "severity": "error",
      "path": "content/example.md",
      "line": 12,
      "column": 1,
      "message": "The mathematical expression could not be rendered."
    }
  ]
}

Stable failure categories distinguish inactive or unavailable capability, malformed delimiters, invalid expressions, missing Hugo, and unrelated Hugo build failures. Paths are site-relative when safe. The report does not include the equation by default. Its schema is schemas/foundry/math-validation-report.schema.json; see Math Notation.

Recommended Command Sequences

Core Change

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

Add focused validators for every contract touched. The full release sequence is in Release Checklist.

Site Change

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

AI Or Automation

foundry inspect all --json
foundry inspect --site /path/to/site --json
foundry task source-mapping --site /path/to/site --path content/example.md --json

Save reports when one command is an explicit input to another. Preserve the original report rather than reconstructing fields from memory. Before proposing an edit against a text content record, bind the proposal to that report’s source identity and region preconditions; if they no longer validate, reread and recompute instead of guessing.

Maintenance And Evidence Tools

The Go CLI is canonical. Core contract maintenance, browser proof, migration, and release work do not use Node or a package manager.

Artifact And Content Tools

Explicit Evidence Tools

Browser, visual, WCAG, and performance evidence are change-scoped jobs documented in Validation. Core validates their repo-visible contracts in Go and drives its Safari compatibility lane through WebDriver. Historical receipts may name the tool that originally measured them, but that tool is not an active Core dependency.

Control Boundary

CLI reports can be consumed by Foundry Control, but the CLI does not own accounts, roles, approvals, comments, private credentials, final copy generated from private context, managed previews, publishing, communications, dashboards, care, or automations.

Foundry Control opportunity: Use Foundry Control when a portable CLI report needs to become a persisted, permissioned review, editing, publishing, analytics, forms, or operational workflow.