[V2:19] Add Theme Development Setup

[ritorhymes]

Part of V2: Multi-repo local build system.

Summary

This PR is the theme-repo setup/documentation rollout for V2. It adds contributor README docs and POSIX/PowerShell scripts/dev-setup wrappers without changing theme templates, styles, Zola config, syntax definitions, or rendering behavior.

Because theme/ is not itself an active proposal repo, the wrappers assume this repo lives at <workspace>/theme and anchor setup through an active proposal checkout. By default that is <workspace>/EIPs (../EIPs from the theme repo), cloned from https://github.com/eips-wg/EIPs.git when missing. ACTIVE_REPO_ROOT can instead select a manifest-bearing Git checkout, typically the workspace’s sibling EIPs or ERCs repo. The normal supported layout keeps the active proposal repo and theme/ under the same workspace root.

The selected active checkout must contain Build.toml. An explicit ACTIVE_REPO_ROOT without that manifest fails with guidance to use a manifest-bearing EIPs/ERCs checkout. A default ../EIPs checkout without Build.toml fails with an explicit rollout-pending message and directs contributors to set ACTIVE_REPO_ROOT until the EIPs default branch carries the manifest.

The wrappers reuse build-eips and Zola from PATH or user-local installs when possible. They install a released build-eips only when needed, verified against release .sha256 sidecars generated by the V2:17 checksum pipeline, and never build it from this checkout. They install Zola 0.22.1 only when it is missing, older, or unparseable; existing 0.22.1+ installs are reused, newer versions are reported and reused, and downloaded Zola archives are verified against per-platform hashes pinned in the scripts.

The wrappers then run build-eips -C "$ACTIVE_REPO_ROOT" init ... and doctor; init failures stop setup, while doctor failures remain warnings rather than setup failures.

The README documents the final post-manifest workspace model: active Build.toml versus workspace-local .build-eips.toml, [theme] as the initial clone/pin source when workspace/theme is missing, and the editable local workspace/theme checkout used at runtime. It removes staging/production/parity workflow language and documents clean comparisons through --clean and --remote-siblings. It also documents final CLI ordering: global --build-root and --remote-siblings options go before the command name, while --only is intentionally limited to local dirty build/serve flows.

Review should focus on POSIX/PowerShell parity, release-binary versus local-source behavior, sidecar versus pinned-hash verification policies, Zola reuse behavior, active-repo/manifest handling, rollout-pending default behavior, flag passthrough, doctor warning behavior, and docs accuracy.

• Add README.md local-development documentation for the theme repo.
• Add POSIX and PowerShell scripts/dev-setup entrypoints for theme contributors.
• Locate, reuse, or install build-eips; verify downloaded release archives with .sha256 sidecars; ensure a supported Zola is available; run workspace init; and run doctor.
• Reuse build-eips and Zola from PATH first, then from the default user-local install path, installing into a writable install directory only when needed.
• Default setup to the surrounding workspace layout one directory above this repo, with this repo as <workspace>/theme/.
• Use https://github.com/eips-wg/EIPs.git as the default EIPs clone URL.
• Require Build.toml after resolving either the default or explicit active proposal checkout, with distinct actionable errors for explicit roots versus the rollout-pending default remote.
• Support ACTIVE_REPO_ROOT for manifest-bearing sibling EIPs or ERCs checkouts.
• Pass optional --template and --platform-dev flags through to build-eips init.
• Print workspace-doc, PATH, and next-command guidance after setup.
• Document Build.toml versus .build-eips.toml, editable local theme behavior, serve/preview, base URL precedence, targeted rendering, and clean source/output comparisons.
• Remove stale staging/production/parity workflow examples.

Review Notes

This is the theme repo setup/documentation rollout. It does not change theme templates, styles, Zola config, syntax definitions, or rendering behavior. The theme rendering changes for the V2 stack are in V2:01.

The setup scripts are front-door convenience wrappers for theme contributors. They install a released build-eips binary when needed, or reuse an existing build-eips on PATH or in the default user-local install path. They do not build build-eips from this theme checkout.

Zola follows the same reuse-first shape: the scripts use Zola from PATH or the default user-local install path when available. They install Zola 0.22.1 if the discovered version is missing, older than 0.22.1, or unparseable; they reuse 0.22.1 and report-but-continue for newer versions.

build-eips release downloads are verified against fetched .sha256 sidecars generated by the release checksum pipeline added in V2:17. Zola downloads are verified against per-platform hashes pinned in these scripts.

Because theme/ is not an active proposal repo, setup is anchored through a proposal checkout. By default that is ../EIPs, using https://github.com/eips-wg/EIPs.git if the checkout is absent. The active checkout must contain Build.toml.

ACTIVE_REPO_ROOT can select a manifest-bearing Git checkout, normally the sibling EIPs or ERCs repo in the same workspace. If an explicit root has no Build.toml, setup tells the contributor to choose a manifest-bearing checkout. If the default EIPs checkout lacks Build.toml, setup explains that the EIPs default branch is awaiting the manifest rollout and directs the contributor to set ACTIVE_REPO_ROOT.

--template and --platform-dev are forwarded to build-eips init unchanged. Their semantics live in the preprocessor; this script does no per-flag bootstrapping of its own.

The scripts run build-eips doctor after init and surface doctor failures as warnings rather than hard setup failures. A local editable theme checkout that differs from the active manifest pin is also a nonfatal doctor warning: runtime intentionally uses the local workspace/theme checkout.

The README documents the final preprocessor commands and workspace model: init, doctor, serve, preview, --base-url, --build-root, --remote-siblings, and local dirty --only workflows. --build-root and --remote-siblings are global options and therefore appear before build, serve, or preview in the examples.

Clean remote-sibling comparison is documented as:

build-eips --build-root <path> --remote-siblings -C <repo> build --clean

--only is not offered for that clean path.

The README distinguishes active Build.toml from local .build-eips.toml: the active manifest identifies the active repo, maps proposal repositories and base URLs, and supplies the [theme] source/pin used when init first creates workspace/theme. .build-eips.toml holds workspace-local server, base URL, build-root, and rendering settings. An existing local workspace/theme checkout remains editable and is not reset by init.

The README points contributors to ../WORKSPACE.md for the full command reference. That file is generated by build-eips init from the workspace docs completed in [V2:18](eips-wg/preprocessor#32), so this README stays theme-focused instead of duplicating every command edge case.

Verification

• Review scripts/dev-setup and scripts/dev-setup.ps1 for POSIX/PowerShell parity across tool reuse, build-eips release install, checksum sidecar verification, Zola install/reuse, default EIPs bootstrap, active Build.toml validation, ACTIVE_REPO_ROOT, optional flag forwarding, workspace init, doctor warning behavior, PATH guidance, and next commands.
• Review README.md for theme contributor setup, workspace layout, Build.toml versus .build-eips.toml, rollout-pending default setup guidance, serve versus preview guidance, local server/base URL settings, local --only behavior, global option ordering, clean remote-sibling comparisons, and handoff to ../WORKSPACE.md.
• Integrated validation used the freshly built final build-eips binary. It exercised a disposable theme/scripts/dev-setup run with ACTIVE_REPO_ROOT set to a local manifest-bearing EIPs checkout; the script selected that binary, reached build-eips -C "$ACTIVE_REPO_ROOT" init ..., ran doctor, and did not modify the real workspace.
• POSIX syntax and runtime behavior were exercised. PowerShell parity was reviewed against the matching implementation, but PowerShell was not available in the validation environment for a live parse/run.
• Fresh EIPs/ERCs workspace init, doctor, base-URL precedence, local editable-theme behavior, local targeted builds, a full clean remote-sibling EIPs build, changed-command smoke tests, README command parsing, and stale-surface sweeps were covered in the integrated final validation gate.