Core and CLI overview

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

Mission: Make Foundry the best and most flexible way to quickly build unique websites for every customer — sites that evolve as needs grow, and that the customer owns outright instead of being locked into a platform.

Read the canonical mission and top goals.

Latest Core release: Foundry Core v1.1.1. Install with go install github.com/jerrybroughton/likestyle-foundry-core/cmd/foundry@v1.1.1 when repository access is configured, then confirm it with foundry version. Verify the remote tag and matching GitHub Release before adoption. The current catalog is Foundry Distribution v0.3.16, stable/LTS bundle v1.0.1, pinning Core v1.0.1. Core v1.1.1 is released, while v1.0.2 remains the latest compatible maintenance patch on the v1.0 LTS branch. Distribution promotion, consumer adoption, and deployment remain separate.

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.

Core is human-first. Essential jobs must work directly through understandable CLI guidance and ordinary repository files. JSON and optional AI are secondary interfaces to the same portable contracts; Foundry Control may add managed workflow, but it is never required to use Core.

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, Section Styles and scorecards, pages, compositions, content kits, packs, and Motion Kit profiles/patterns in data/foundry/
• JSON Schema contracts in schemas/foundry/ — including shell, crawler-policy, Static Origin, 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
• A preview Static Origin Profile with six understandable product rules, sensible defaults, atomic same-filesystem releases, and site-declared exceptions without requiring a CDN
• 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 site, Foundry bundle, and Core version metadata plus a portable, fail-visible Foundry attribution hook with an optional compact version line and public Control policy
• A first-class foundry version identity report plus deterministic Distribution-catalog release/support projections for installed sites
• Explicit stable/LTS support status from the Distribution catalog; version numbers remain technical SemVer identities and never imply LTS by themselves
• Signed release-catalog validation and read-only installed-versus-target upgrade rehearsals with exact runtime identity and output-difference receipts
• Portable conformance contracts for effective authoring inventories and intent-first, no-write content-operation proposals
• Creative Lane v1 contracts for the artist/photographer portfolio profile
• A Go-native foundry check routine lane plus Go foundry inspect, foundry validate, foundry release-check, and foundry task surfaces for contract enforcement, drift detection, smoke checks, framework inventory, no-write reports, and explicit add-only apply work
• A source-first foundry migrate site --source <directory> path that previews and creates a clean, customer-owned Hugo source tree without copying generated output, dependency snapshots, Node tooling, or a managed Control project file
• An explicit HUGO_FOUNDRY_CORE_ONLY=true render mode that keeps portable content and human fallback messaging visible while suppressing optional attribution-policy, managed-form, and tracking requests
• A theme-led, dry-run-first foundry new-site path that creates a complete ordinary Hugo repository without Node, npm, or pnpm

This repo is a module, not a standalone site. Validate it through the Go CLI, Hugo, and, when relevant, a representative consuming site. Foundry Core does not use Node, npm, npx, or pnpm for development, validation, release, migration, or documentation work. Customer-facing browser JavaScript remains ordinary portable source where an interaction needs it.

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:

• Mission And Top Goals for the framework’s canonical purpose, priorities, product boundaries, and current decision authorities.
• Best Framework Plan for the active evidence-integrity, WCAG 2.2, Web Vitals, and convergence program.
• 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, and report workflow.
• Tooling Policy for the enforced Go/Hugo-only framework and release boundary.
• Site Import Contracts for source-directory migration and the advanced immutable-capture recovery path.
• Versioning And Releases for release numbering, immutable tags, CLI identity, and release/support status.
• Static Origin Profile for the six portable direct-origin rules and the small site declaration.
• 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.
• Visual Review Catalog for the integrated Documentation-site view of Theme Families, Brand Systems, Site Foundations, Section Families, and evidence packets.
• 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.27
• Hugo Extended >= 0.165.0 in a consuming site
• Git

Node, npm, npx, and pnpm are not used by Core. The enforced v1 toolchain is Go, Hugo, and Git; see Tooling Policy.

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 foundry check for fast routine validation.
4. Build a consuming site against the updated module before release.

The one generated Core contract is maintained through the same Go CLI. When the block registry, options, schemas, or families change, regenerate it with:

go run ./cmd/foundry generate block-manifest

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

For a new site, compare the Site Types and their Theme Family + reference Brand System directions before writing:

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 \
  --write

The result is ordinary Hugo source with no Node or pnpm prerequisite. Replace the fictional reference Brand System with customer-owned identity before publish.

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 routine path is the Go foundry CLI:

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

Use release-check for the full portable-Core fixture and release lane. Core contains no Node package tooling, and foundry validate tooling makes that a release-blocking contract.

Run the current Go contract validators:

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

For the human-facing Static Origin workflow:

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

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 static-origin --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 family, block, design-control, field, menu, blueprint, global, and preview-mapping contract for portable site editors and Foundry Control.

Run the fast routine check during ordinary work. Human output is progressive; JSON uses the stable foundry.check.v1 report:

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

The routine lane supports site bootstrap checks, site block usage validation, allowlist-aware drift audits, Hugo render smoke, --skip-core, --skip-hugo, and --strict-warnings. It deliberately excludes the full compatibility fixture fleet, generated report-contract checks, visual/stable-layout evidence, and browser proof. doctor remains as a compatibility command. Without browser flags it routes to the same Go-native routine checks while retaining the historical doctor report identity. Use release-check for the complete release lane.

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 browser parity lane locally when the change affects search, article shells, or other interactive fixture surfaces:

go run ./cmd/foundry release-check --browser-smoke --json

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

go run ./cmd/foundry release-check --browser-smoke --require-browser --json

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

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

Include drift audits for proof consumers or reviewed local overrides:

go run ./cmd/foundry check --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
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
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 inspect static-origin --json
foundry validate static-origin --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. The same report exposes both family catalogs, all governed design controls, and portable nested-menu options for editor consumers.

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. Embedded previews also load Core’s small pointer-and-keyboard sender and emit foundry.preview-selection.v1 messages containing only the stable section ID and source-relative field path. Consumers must validate the exact preview window, origin, schema, section, and contract field before changing focus.

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/MATH-NOTATION.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. docs/MATH-NOTATION.md when the article contains equations
4. examples/content-kits/article-rich-body-primitives.md
5. examples/content-kits/article-math-notation.md

Release Notes

Latest Core release: Foundry Core v1.1.1, the portable Steps grid hotfix on the v1.1 feature line. Its immutable tag and matching GitHub Release are published. Distribution v0.3.16 and stable/LTS bundle v1.0.1 pin Core v1.0.1; consumer adoption and deployment remain separate, explicit facts.

Current v1.0 maintenance patch: Foundry Core v1.0.2, including compatible repeated-TOC, rating-semantics, shared-control, and cross-browser repairs. Its applicable fixes are also present in v1.1.1.

Previous patch: Foundry Core v1.0.1, the Go/Hugo-only tooling-boundary stabilization release.

Previous feature release: Foundry Core v1.0.0.

Previous pre-v1 tag: Foundry Core v0.1.54, the governed visual systems, site creation, migration-contract, and source-linked example release. The immutable v0.1.40 through v0.1.54 tags retain the Math Notation V1, validation, article navigation, attribution, source-region, preview-manifest, version identity, release-status, portable Composer, Safari automation, structured-field, Section Type + Style, and Static Origin contract history.

Before tagging a release:

1. Regenerate any derived manifests or safelists.
2. Run go test ./... and go run ./cmd/foundry release-check --json; release-check owns documentation and workflow policy. Run the preview interaction evidence only when the embedded preview integration changes.
3. While repository GitHub Actions is disabled, run the complete local release checklist against the exact release tree and record cross-platform runner verification as deferred.
4. Run go run ./cmd/foundry release-check --site /path/to/site --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.