Core and CLI overview

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

Current production release: Foundry Core v0.1.53

Install with go install github.com/jerrybroughton/likestyle-foundry-core/cmd/foundry@v0.1.53, then confirm it with foundry version.

Release candidate: Foundry Core v0.1.54 is being validated locally. It is not yet the production installation pin.

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, 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
• 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
• 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.
• Versioning And Releases for production 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.
• 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 static-origin
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

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

Candidate: Foundry Core v0.1.54, the governed visual systems, site creation, migration-contract, and source-linked example candidate. It is not yet the production pin.

Current release: Foundry Core v0.1.53, the portable owner-editing contract release layered onto the v0.1.52 Static Origin profile. The immutable v0.1.40 through v0.1.53 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 run ./cmd/foundry doctor --json, go run ./cmd/foundry release-check --json, and node scripts/foundry-doctor.js.
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 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.