Publication starters and episode proposals

Core can create a complete ordinary Hugo publication through the existing new-site command. Choose a journal, an issue-led magazine or a film programme. The public catalogue, Article renderer and edition contracts are shared; the site owns its shell, fonts, colors, illustrations and editorial choices.

All included stories are fictional. Original SVG illustrations are code-native; fonts include licenses. Audio is silent and film is synthetic compatibility material. Replace them with reviewed reporting, rights-cleared media, accurate captions and transcripts before publishing real work. A reference starter is complete source, not a claim of a customer launch or verified journalism.

Choose, inspect, create

An installed release containing these directions uses its own immutable version: select its complete Core source root explicitly when working in another directory.

foundry new-site --root /path/to/complete-core-root --list --json
foundry inspect site-blueprints --root /path/to/complete-core-root --json
foundry new-site ../my-publication --root /path/to/complete-core-root --site-type publication \
  --direction publication-issue-magazine --title "My Publication" --dry-run --json
foundry new-site ../my-publication --root /path/to/complete-core-root --site-type publication \
  --direction publication-issue-magazine --title "My Publication" --write
cd ../my-publication
hugo server --buildDrafts

During source-tree development, new-site requires --core-version. That pin does not make unmerged features part of the named release. To verify this candidate, use a disposable generated site and an explicit local Go module replacement for this checkout. Remove the replacement and select a release containing the feature before calling the site portable to another computer. Do not publish a development replacement as an immutable release claim.

Dry run lists every file and its exact SHA-256. Existing destinations block the whole preflight before foundation writes. Creation copies common and one direction from the ordinary starter source. source_starter in machine inspection names this source explicitly. These directions do not pretend that the unrelated Creative Home Page Starter built their custom shell. Their brief examples describe new-site option values; they are not new-page --brief inputs.

Keep layouts/blog/*-entry.html as thin references to Core’s shared Article partial. Change identity in site-owned CSS and metadata. Change issue order in selection.include, format scope in selection.formats, and show/season scope through the existing catalogue filters. A text-only journal also includes the ordinary journal content recipe for draft articles without catalogue metadata.

Root and subdirectory base URLs are supported at creation. If you move an existing publication to another base path, update its catalogue’s local public locators, particularly exact chapters_url bindings, then rebuild and inspect.

Plan one episode across its source files

episode-proposal is a dry-run-only composition of the existing site recipe and catalogue. It creates no source files and exposes no apply mode. It returns foundry.episode-proposal.v1, deliberately distinct from the create-only foundry.content-operation-report.v1 contract.

Source-bound planning requires a Git repository with a baseline commit and repository-local materialized dependencies. A normal network-resolved Hugo build is useful for initial viewing, but cannot prove the exact dependency source to this inventory. For a default generated site’s two pinned modules:

cd ../my-publication
hugo mod vendor
go mod edit -replace=github.com/jerrybroughton/likestyle-foundry-core=./_vendor/github.com/jerrybroughton/likestyle-foundry-core
go mod edit -replace=github.com/jerrybroughton/likestyle-foundry-theme-shield=./_vendor/github.com/jerrybroughton/likestyle-foundry-theme-shield
git init
git add .
git commit -m "Establish publication source and pinned local dependencies"

Run vendoring against the reviewed pins or explicit development replacements first; do not substitute an unrelated installed checkout. Keep the local module snapshot with the site. Custom themes use their own declared module identities. The proposal reports external or unmaterialized dependencies as unsupported instead of guessing their source. See Preview Build Manifest.

A packaged Core root selected by --root must include the ordinary starters/publication files as well as the usual manifests, examples, schemas and renderers. The binary alone is not a complete authoring source root.

1. Choose an existing publication and show. The supplied magazine and film starters declare reference-publication and reference-show; a text-only journal needs a real show declaration before planning an episode.
2. Copy the public input example. Replace fictional copy, entry/edition/rendition IDs and prepared media URLs. Set expected_catalogue_sha256 to sha256: followed by the SHA-256 of the exact current data/foundry/publications.json bytes. Do not hash parsed JSON.
3. Use the site’s declared episode recipe, which binds entry_id to publication_entry and always starts with draft: true.

shasum -a 256 data/foundry/publications.json
hugo version
foundry episode-proposal --root /path/to/complete-core-root --site . --site-key my-publication \
  --recipe episode --slug evening-walk --input /path/to/reviewed-episode.json \
  --hugo-version '<the verified Hugo version>' --dry-run --json > /tmp/episode-proposal.json
foundry validate episode-proposal --report /tmp/episode-proposal.json --json

The report reuses Core’s facts-only repository inventory, pinned tool identities, recipe validation and exact draft serializer. It proposes one new Markdown page, one exact replacement of the catalogue with an appended entry, and optionally one new chapter asset. Each operation names expected state/hash and proposed UTF-8 bytes/hash. All operations are one atomic candidate. The existing catalogue is not an add-only file-copy operation.

The catalogue insertion retains every byte outside the insertion, including extension fields, whitespace and numeric spelling. Null extension values remain opaque. Ambiguous duplicate keys, malformed/lossy Unicode, unsupported source, duplicate IDs or full episode numbers, stale hashes, conflicting destinations and symlinks fail closed. Existing reports keep their create-only semantics.

The catalogue must have matching contained inventory evidence; ignored source cannot silently disappear from the report’s dependency identity. New-path absence is also checked through bounded filesystem metadata, since Git omits ignored files. Case collisions, ignored occupied paths and concurrent ignored file creation are rejected. The report retains exact Core/Hugo versions and executable hashes and rechecks the complete toolchain around the composition. These source preconditions still need a fresh atomic check by any later writer.

Optional chapters must name one edition, its exact public URL and a new assets/**/*.chapters.json path. Numeric markers must increase within that edition’s duration. An edition is a cut with its own clock; a translated or video edition never inherits another cut’s timestamps. The source is bounded to 256 KiB and 500 markers; the catalogue to 512 KiB for this proposal lane. Remote media URLs are retained public locators, not fetched or health-checked.

Review the complete candidate together. Any later source-writing adapter must recheck the current tree and expected hashes and either apply every operation or none. A person can make the reviewed changes in a branch using normal source editing. Core’s proposal does not make that write, record approval, or publish. Preview the exact candidate through Hugo before any production build: mounts, page bindings, chapter output URLs, feed inclusion and theme shadows are separate from offline proposal conformance. Media delivery, rights, caption/transcript accuracy and assistive-technology checks also remain explicit.

For source created through an explicitly declared ordinary page recipe, content-document can inspect and propose exact source edits. That bounded editor requires hugo.page.create / hugo.page recipes. The supplied journal and episode recipes have specialized kinds and remain outside that lane. Do not relabel an existing specialized recipe to bypass its source relationship. Publication source remains owner-editable in a reviewed branch, with related catalogue/chapter source validated together. The separate body-source-scope command classifies complete new body bytes; it does not validate that multi-file candidate or grant managed access.

Foundry Control opportunity: Foundry Control can consume this report for guided episode creation, private review, approvals, prepared asset ingestion, conditional branch writes, scheduling and publishing. The public site and source remain portable without that managed workflow.