Plan publication and materialization

Use this guide when the site has enough versions, refs, or imported inputs that you need an explicit planning step before staging starts.

Keep three concerns separate

The model separates:

version selection
source materialization
staging

That separation matters because a cache branch, snapshot store, or generated local tree is a materialization strategy, not a publication concept.

Request a machine-readable build plan

For automation, request the report schema explicitly:

1site-pipeline plan --for build --report-format json --report-schema-version 1

An abridged report entry looks like this:

 1{
 2  "schemaVersion": 1,
 3  "target": "build",
 4  "entries": [
 5    {
 6      "sourceKey": "runtime",
 7      "inputKind": "released",
 8      "componentSlug": "spark",
 9      "artifactKey": "runtime",
10      "version": "4.0.0",
11      "tag": "v4.0.0",
12      "expectedLocalPath": "/workspace/components/runtime/docs/releases/4.0.0",
13      "status": "present",
14      "provenance": "snapshot",
15      "watchEligible": false
16    }
17  ],
18  "diagnostics": []
19}

expectedLocalPath is a local filesystem path, not a public URL or staged route. A report can complete successfully while entries are missing, stale, or unresolved; those states tell the consumer what acquisition work remains.

Use --for watch when the consumer needs watch eligibility and watch-scoped input requirements. Write the report to a file with --report-output when a wrapper needs to consume it after the command exits.

Materialize outside the pipeline

For every entry that is not ready:

Resolve the source key, ref, tag, or version with consumer-owned SCM or cache tooling.
Populate the exact local path described by the report.
Rerun plan until the inventory reflects the expected state.

Site Pipeline deliberately does not fetch repositories, update cache branches, or choose a snapshot-store implementation. That keeps acquisition credentials and network behavior outside the staging process.

Validate and stage

Once the selected local inputs exist:

1site-pipeline check
2site-pipeline build

For a long-running local renderer loop, use watch only after a watch plan says the relevant inputs are watch-eligible.

Complete workflow

decide which publication contexts should exist for the target build or watch cycle
use the planning step to resolve which local inputs are required
- these can include top-level site pages, top-level site assets, top-level vendor asset roots, and the selected component docs trees
materialize those inputs using the consumer’s chosen strategy
run check to validate the resolved inputs and authored metadata
run build or watch once the local trees are ready

Failure and recovery behavior

Invalid invocation or a JSON report without an explicit schema version fails before planning.
Missing or stale inputs remain report data; the consumer decides whether and how to acquire them.
Error diagnostics that prevent a usable plan return a domain failure.
check can still find invalid content, links, references, or routes after all inputs are present.
Acquisition should be repeatable: rerunning it for an already-correct input should not change publication policy or staged paths.

This separation makes it possible to replace an SCM checkout strategy with a cache or snapshot store without changing the catalog or downstream stage.