Core and CLI overview

Shared Hugo module for LikeStyle Foundry — a framework for building unique, customer-owned websites fast.

Foundry provides block families, a seven-capability motion framework, governed creative display patterns, governed compositions, content kits, and pack scaffolds on top of Hugo without a required client framework. Optional Control-managed forms can load the fixed Cloudflare Turnstile client when Control requests a challenge.

What This Repo Owns

• 17 governed block families with semantic jobs, need rationale, and block ownership encoded in data/foundry/block-family-manifest.json
• Motion framework — reveal, stagger, parallax, pinned/progress parallax, scrub, marquee, and Ken Burns capabilities in assets/js/foundry-motion.js and assets/css/foundry-motion.css
• Governed creative display patterns — reusable pattern metadata for media-led heroes, pinned stories, reels, chapter indexes, proof marquees, slideshows, stats counters, and scroll cues
• Machine-readable manifests for blocks, section families, pages, compositions, content kits, packs, and Motion Kit profiles/patterns in data/foundry/
• JSON Schema contracts in schemas/foundry/ — including shell, crawler-policy, and portable authoring contracts
• The shell contract route-owner model and page-level chrome exception fields
• Stable runtime contract registry for protected helper, partial, block, and compatibility surfaces
• Purpose-aware crawler policies plus rendered discoverability and agent-readiness validation
• Shared article presentation primitives and preview metadata hooks
• Fail-closed Control-managed forms with bounded metadata/submission requests, accessible fallback behavior, idempotent retry keys, and optional Turnstile UI
• Optional privacy-conscious public journey tracking with bounded offline delivery
• Source-visible Core version metadata and a portable, fail-visible Foundry attribution hook with optional public Control policy
• Creative Lane v1 contracts for the artist/photographer portfolio profile
• Validation scripts plus Go foundry doctor, foundry inspect, foundry validate, and foundry task surfaces for contract enforcement, drift detection, smoke checks, framework inventory, no-write reports, and explicit add-only apply work

This repo is a module, not a standalone site. You validate it through its scripts and, when relevant, through a representative consuming site.

Core implementation docs, manifests, schemas, fixtures, and public CLI/report contracts live in this repo. Product-direction planning can still reference likestyle-foundry-docs, but current Foundry Core behavior should be checked against this repo’s active docs and machine contracts.

Start Here

Choose the path that matches the work:

• Getting Started for installing the CLI, mounting the Hugo module, creating a page, and validating a site.
• Features And Families for the complete product model: blocks, both family layers, page types, compositions, kits, blueprints, packs, motion, themes, shell, search, forms, tracking, and more.
• CLI Reference for every public foundry command, safety mode, flag group, report workflow, and legacy Node maintenance tool.
• AI Agent Guide for source-of-truth order, safe discovery/edit/apply flows, verification, and Core/Control routing.
• Portable Authoring Contract for typed editor fields, section-scoped preview selectors, compatibility, and ownership.
• SEO and AI Discovery for metadata, structured data, crawler policy, and rendered discoverability checks.
• Active Docs for the complete current contract index.
• Historical Archive for milestone evidence and older implementation notes that are not the current product surface.

Want Managed Editing, Forms, Publishing, And More?

Foundry Core keeps the site portable and directly editable as a normal Hugo project. Foundry Control adds the managed experience around it: guided site editing, forms, reviews and approvals, publishing, analytics, contacts, communications, automations, care workflows, and more. When a capability is deliberately outside Core, treat it as a Foundry Control opportunity and consider adding Control to the Foundry site.

See Add Foundry Control To A Foundry Site.

Prerequisites

• Go >= 1.22
• Hugo Extended in a consuming site
• Node.js >= 20

Local Workflow

Typical work here is:

1. Update partials, manifests, schemas, or docs.
2. Regenerate machine-readable artifacts if the registry/options changed.
3. Run the validation scripts in this repo.
4. Build a consuming site against the updated module before release.

Regenerate the block manifest:

node scripts/build-block-manifest.js

Regenerate the Tailwind safelist used by downstream consumers:

node scripts/generate-tailwind-safelist.js

Preferred page creation uses the Go CLI. Briefs can be Markdown, YAML, or JSON; explicit CLI fields override brief values:

go run ./cmd/foundry new-page \
  --brief /absolute/path/to/brief.md \
  --site /absolute/path/to/site \
  --dry-run \
  --json

The older low-level content-kit renderer remains available for compatibility:

node scripts/create-content-draft.js \
  --kit landing-lead-capture \
  --brief /absolute/path/to/brief.json \
  --out /absolute/path/to/site/content/campaigns/spring-offer/_index.md

Local Service and Creative starter templates are generated through foundry new-page --blueprint ..., foundry new-page --brief ..., or foundry new-page --prompt. Use --dry-run --json to inspect the resolved blueprint/content-kit/page/composition contract before writing. Prompt mode defaults to dry-run; pass --write --site /absolute/path/to/site to create the page. Existing files are refused unless --force is provided.

Creative v1 and Local Service route floors can also be checked or generated in one pass:

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

go run ./cmd/foundry scaffold local-service-route-floor \
  --site /absolute/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

Validation

The canonical product tooling direction is the Go foundry CLI. Current Node validators and foundry-doctor.js remain reference/fallback behavior until the equivalent Go commands reach parity.

Run the current Go contract validators:

go run ./cmd/foundry validate runtime
go run ./cmd/foundry validate crawler-policy
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate discoverability --rendered-root public --json
go run ./cmd/foundry validate scaffolds
go run ./cmd/foundry validate tasks

Inspect the framework inventory through the Go CLI:

go run ./cmd/foundry inspect --json
go run ./cmd/foundry inspect blocks --json
go run ./cmd/foundry inspect blueprints --json
go run ./cmd/foundry inspect scaffolds --json
go run ./cmd/foundry inspect discovery --json
go run ./cmd/foundry inspect motion --json
go run ./cmd/foundry inspect theme-tokens --json

Inspect a consuming site’s page, route, block, blueprint, and source-path mapping:

go run ./cmd/foundry inspect --site /absolute/path/to/site --json
go run ./cmd/foundry inspect --site /absolute/path/to/site /welcome/ --json
go run ./cmd/foundry inspect --site /absolute/path/to/site content/welcome.md --json
go run ./cmd/foundry authoring-contract --site /absolute/path/to/site --json

authoring-contract emits the Core-owned, read-only V1 block, field, blueprint, global, and preview-mapping contract for portable site editors and Foundry Control.

Run the current Go core doctor. It provides human and JSON output and uses native Go validators for the Core-owned validation lanes:

go run ./cmd/foundry doctor
go run ./cmd/foundry doctor --json
go run ./cmd/foundry doctor --site /absolute/path/to/site --json

The Go doctor supports site bootstrap checks, site block usage validation, allowlist-aware drift audits, Hugo render smoke, --skip-core, --skip-hugo, --strict-warnings, --browser-smoke, and --require-browser. Browser smoke uses the Go compatibility fixture harness and skips cleanly when Safari WebDriver is unavailable unless --require-browser is set.

Validate the public task/report contract surface when task docs, task manifests, import/apply behavior, or improve-page report fields change:

go run ./cmd/foundry validate tasks
go run ./cmd/foundry validate tasks --json
go run ./cmd/foundry task improve-page --dry-run --site fixtures/compatibility/utility-service-theme-proof --path content/_index.md --json

Run the Node aggregate as a legacy compatibility backstop:

node scripts/foundry-doctor.js

Run the browser parity lane locally when the change affects search, article shells, or other interactive fixture surfaces:

go run ./cmd/foundry doctor --browser-smoke --json

Require a real browser session instead of a skip when validating CI-like macOS environments:

go run ./cmd/foundry doctor --browser-smoke --require-browser --json

Run doctor against a consuming site when the change affects rendering, bootstrap, packs, shell behavior, or downstream adoption:

go run ./cmd/foundry doctor --site /absolute/path/to/site --json

Include drift audits for proof consumers or reviewed local overrides:

go run ./cmd/foundry doctor --site /absolute/path/to/site --include-drift-audits --json

See docs/VALIDATION.md for the full verification path and regression checklist.

Validate internal manifest/docs/contracts consistency:

go run ./cmd/foundry validate block-contracts
go run ./cmd/foundry validate block-governance
go run ./cmd/foundry validate feature-flags
go run ./cmd/foundry validate runtime
go run ./cmd/foundry validate tasks

Validate the shell contract (route-owner, typed surface definitions, compatibility helpers):

go run ./cmd/foundry validate shell

Audit a downstream repo for copied core shadows that turn a consumer into a local framework fork:

go run ./cmd/foundry validate site-shadows --site /path/to/downstream-repo
# With allowlist for documented temporary proof-consumer exceptions:
go run ./cmd/foundry validate site-shadows --site /path/to/downstream-repo \
  --allowlist /path/to/downstream-repo/.planning/foundry-shadow-allowlist.json

Audit a downstream repo for unallowlisted shell shadows:

go run ./cmd/foundry validate shell-overrides --site /path/to/downstream-repo
# With allowlist for documented temporary shadows:
go run ./cmd/foundry validate shell-overrides --site /path/to/downstream-repo \
  --allowlist /path/to/downstream-repo/.planning/shell-shadow-allowlist.json

See docs/SHELL.md for the full shell contract reference and examples/shell/ for adoption examples.

Validate downstream content against the shared block registry:

go run ./cmd/foundry validate site-blocks --site /absolute/path/to/site

Release-safe smoke test from a consumer site:

hugo --minify

Run that in a consuming repo after pointing it at the updated core module.

SEO And AI Discovery

Foundry uses one portable SEO pipeline for people, search engines, and AI discovery systems. The shared renderer emits canonical and robots controls, descriptions, Open Graph and Twitter metadata, language alternates, breadcrumbs, page/article/service/person/FAQ JSON-LD, and visible review evidence through reviewed_on and lastReviewed.

Crawler policy is explicit and owner-controlled. The reviewed registry covers 11 search, AI-search, model-development, and user-fetch agents plus four opt-in profiles. The default inherit profile preserves existing wildcard behavior; no release silently changes a site’s training or search policy.

foundry inspect crawler-policy --json
foundry validate crawler-policy --json
foundry validate discoverability --rendered-root public --strict --json

The rendered audit checks canonicals, index controls, schema/content agreement, headings, internal links, freshness, forms, and accessible control names. It does not invent a GEO score or promise rankings or citations. See SEO and AI Discovery for configuration, guardrails, and the Foundry Control opportunity for managed monitoring and analytics.

Consumption

1. Add the module to the site go.mod.
2. Mount layouts/partials into layouts/partials/foundry.
3. Compose pages with sections front matter.
4. Use design.variant where a block supports multiple layouts.
5. Optionally use bricks and bricks_order for nested composition.
6. Optionally enable preview metadata when editor overlays need source and field selectors.

Preview Metadata

Preview metadata is opt-in and adds data-foundry-* source attributes without changing the rendered content contract.

params:
  foundry:
    preview_metadata:
      enabled: true

Typed golden-block fields expose section-scoped selectors through foundry.authoring-contract.v1. See the Portable Authoring Contract before implementing field focus or overlays; field selectors must be queried inside the selected section wrapper.

When enabled, wrappers expose source path, locale, block key, block id, field path, and document kind metadata for preview overlays and editor integrations. The hero, media-text, gallery, cta, and managed-form golden blocks also expose typed field anchors described by foundry authoring-contract.

Related Docs

• docs/GETTING-STARTED.md
• docs/FEATURES-AND-FAMILIES.md
• docs/CLI-REFERENCE.md
• docs/AI-AGENT-GUIDE.md
• docs/AUTHORING-CONTRACT.md
• docs/BLOCKS.md
• docs/SEO.md
• docs/AI-DISCOVERY.md
• docs/MANAGED-FORMS.md
• docs/TRACKING.md
• docs/FOUNDRY-CONTROL.md
• docs/ACTIVE.md
• docs/SHORTCODES.md
• docs/CREATIVE-LANE.md
• docs/LOCAL-SERVICE-SCAFFOLDING.md
• docs/ARTICLE-PRESENTATION.md
• docs/FOUNDRY-PRODUCT-WORKFLOW-IMPROVE-PAGE.md
• docs/FOUNDRY-CORE-CONTROL-GUIDESTONES.md
• docs/VALIDATION.md
• docs/FEATURE-FLAGS.md
• docs/RELEASE-CHECKLIST.md

For journal/blog/article authoring, start with:

1. docs/SHORTCODES.md
2. docs/ARTICLE-PRESENTATION.md
3. examples/content-kits/article-rich-body-primitives.md

Release Notes

Current release: Foundry Core v0.1.34.

Before tagging a release:

1. Regenerate any derived manifests or safelists.
2. Run go run ./cmd/foundry doctor --json, go run ./cmd/foundry release-check --json, and node scripts/foundry-doctor.js.
3. Run go run ./cmd/foundry doctor --browser-smoke --require-browser --json on a prepared macOS environment when the change touches interactive fixture surfaces or browser behavior.
4. Run go run ./cmd/foundry doctor --site /path/to/site --strict-warnings --json against at least one representative consumer.
5. Review docs/VALIDATION.md and docs/RELEASE-CHECKLIST.md for any change-specific regression steps.
6. Tag the release and let downstream sites update their pins only when approved.