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 — all on top of Hugo with zero external JS dependencies.

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 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 plus Go foundry doctor and foundry inspect slices for contract enforcement, drift detection, smoke checks, and framework inventory

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

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

• /Users/jerryb/Documents/CodexProjects/likestyle-foundry-docs/docs/FOUNDRY-START-HERE.md
• /Users/jerryb/Documents/CodexProjects/likestyle-foundry-docs/docs/FOUNDRY-DOCUMENTATION-GOVERNANCE.md
• /Users/jerryb/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

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 motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate scaffolds

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

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

Run the current Go core doctor slice. It provides human and JSON output while using Node reference validators for checks that have not yet reached native Go parity:

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 currently delegates to the Node reference fixture validator.

Run the Node reference aggregate 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:

go run ./cmd/foundry doctor --browser-smoke --json
node scripts/foundry-doctor.js --browser-smoke

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

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

Include drift audits for proof consumers or reviewed local overrides:

go run ./cmd/foundry doctor --site /absolute/path/to/site --include-drift-audits --json
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 go run ./cmd/foundry doctor --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.