Core and CLI overview

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

Foundry provides block families, a 5-engine motion framework, governed compositions, content kits, and pack scaffolds — all on top of Hugo with zero external JS dependencies.

What This Repo Owns

• 16 governed block families with semantic jobs, need rationale, and block ownership encoded in data/foundry/block-family-manifest.json
• Motion framework — reveal, stagger, parallax, scrub, marquee, Ken Burns engines in assets/js/foundry-motion.js and assets/css/foundry-motion.css
• Machine-readable manifests for blocks, pages, compositions, content kits, and packs in data/foundry/
• JSON Schema contracts in schemas/foundry/ — including the shell contract (shell-manifest, page-shell)
• The shell contract route-owner model and page-level chrome exception fields
• Stable runtime contract registry for protected helper, partial, block, and compatibility surfaces
• Shared article presentation primitives and preview metadata hooks
• Creative Lane v1 contracts for the artist/photographer portfolio profile
• Validation scripts and a foundry doctor wrapper for contract enforcement, drift detection, and smoke checks

This repo is a module, not a standalone site. You validate it through its scripts and through a consuming site such as restricted proof consumer or restricted proof consumer.

Canonical Foundry product/framework planning and documentation-governance rules live in likestyle-foundry-docs:

• /Users/gb/Library/Mobile Documents/com~apple~CloudDocs/Documents/CodexProjects/likestyle-foundry-docs/docs/FOUNDRY-START-HERE.md
• /Users/gb/Library/Mobile Documents/com~apple~CloudDocs/Documents/CodexProjects/likestyle-foundry-docs/docs/FOUNDRY-DOCUMENTATION-GOVERNANCE.md
• /Users/gb/Library/Mobile Documents/com~apple~CloudDocs/Documents/CodexProjects/likestyle-foundry-docs/docs/FOUNDRY-PLANNING-INDEX.md

If a change is about product direction or framework canon, do not make that decision only in this repo. Route it through the docs repo first.

Start Here

Use the docs repo as the routing layer:

• if you are working on Foundry itself, start with FOUNDRY-START-HERE.md
• if you are using Foundry to build a site, FOUNDRY-START-HERE.md will route you to the starter/site-building path too

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

Create a starter draft from a content kit:

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 currently scaffold manually from examples/content-kits/. CLI wiring for foundry new-page --blueprint ... is planned but not shipped yet; see docs/LOCAL-SERVICE-SCAFFOLDING.md and docs/CREATIVE-LANE.md for the current template inventory.

Validation

Run the default core safety path:

node scripts/foundry-doctor.js

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

node scripts/foundry-doctor.js --browser-smoke

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

node scripts/foundry-doctor.js --browser-smoke --require-browser

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

node scripts/foundry-doctor.js --site /absolute/path/to/site

Include drift audits for proof consumers or reviewed local overrides:

node scripts/foundry-doctor.js --site /absolute/path/to/site --include-drift-audits

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

Validate internal manifest/docs/contracts consistency:

node scripts/validate-block-contract.js
node scripts/validate-block-governance.js
node scripts/validate-feature-flags.js
node scripts/validate-runtime-contracts.js

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

node scripts/validate-shell-contract.js

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

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

Audit a downstream repo for unallowlisted shell shadows:

node scripts/validate-shell-overrides.js /path/to/downstream-repo
# With allowlist for documented temporary shadows:
node scripts/validate-shell-overrides.js /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:

node scripts/validate-blocks.js /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.

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

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

When enabled, wrappers expose source path, locale, block key, block id, field path, and document kind metadata for preview overlays and editor integrations.

Related Docs

• docs/BLOCKS.md
• docs/SHORTCODES.md
• docs/CREATIVE-LANE.md
• docs/LOCAL-SERVICE-SCAFFOLDING.md
• docs/ARTICLE-PRESENTATION.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

Before tagging a release:

1. Regenerate any derived manifests or safelists.
2. Run node scripts/foundry-doctor.js.
3. Run node scripts/foundry-doctor.js --browser-smoke --require-browser on a prepared macOS environment when the change touches interactive fixture surfaces or browser behavior.
4. Run node scripts/foundry-doctor.js --site /path/to/site --strict-warnings 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.