Site publishing and shared appearance¶

One marketing site presents three independently released products. The site stays in the vibe-qc repository: its build reads core and vibe-basis versions from this checkout and links to companion releases. No website repository, sibling checkout fetch, or shared theme package is required.

Publisher boundaries¶

Public path	Source	Publishing ref	Owner
`/`	project 34, `website/`	`main`, when website files change	vibe-qc documentation
`/preview/`	project 34, `website/`	`main`, when website files change	vibe-qc documentation
`/docs/`	project 34, `docs/`	`release`	vibe-qc documentation
`/vibe-view/docs/`	project 35, its Sphinx sources	its protected release ref	vibe-view
`/vibe-queue/docs/`	project 36, its Sphinx sources	its protected release ref	vibe-queue

Each publisher uses rsync --delete-after only inside its assigned destination. The root deploy is the exception that contains other publishers: it must keep its exclusions for /docs/, /updates/, /preview/, /vibe-view/, /vibe-queue/ and the server-managed files in .gitlab-ci.yml. Never add --delete-excluded. Companion jobs target /web/vibe-view/docs/ or /web/vibe-queue/docs/, never /web/.

Marketing product pages live at /products/vibe-qc/, /products/vibe-view/ and /products/vibe-queue/. The entire /vibe-view/ and /vibe-queue/ roots are reserved for the companions, so marketing pages cannot live there. Preview marketing links use /preview/products/; documentation links always use the canonical publisher paths above. Companion docs content is linked, not embedded or imported into the Astro build.

A website edit on main goes public on push. A core Sphinx edit on main waits for the next tag and fast-forward of release by the release owner. There is no manual main docs-deploy override. See the release process for release authority and local checks. Companions tag and publish independently of the engine.

SSH key availability¶

DEPLOY_SSH_KEY_B64 is an instance-level protected CI variable. Companions can reuse it without creating a secret, but their actual publishing branches and tags must be protected before running the job. Check that the variable is present without printing its value, and preserve the pinned host-key and strict host checking setup when adapting the core deploy job.

The v0.16.0 core docs job failed with error in libcrypto because release was unprotected: the missing variable produced a zero-byte key file. Project 34 now protects release and v*. If a companion sees the same error, first check its protected refs and whether the key file is empty.

Shared Furo CSS export¶

The source of truth is project 34, docs/_static/custom.css. It is a small Furo override file, currently providing codename image styling and leaving Furo’s stock palette intact. The Astro marketing stylesheet is a separate surface; copying this file does not reproduce the marketing header.

Companions deliberately vendor this one file into their own docs/_static/custom.css. Each companion owns its copy and chooses when to update it. Its normal build uses that committed copy, with no network fetch and no runtime or build dependency on a theme package.

When adopting or updating the export:

Select an immutable core tag or full commit SHA and obtain the file from that revision. Copy it byte for byte, preserving its license and comments.
Commit a receipt alongside it, such as docs/_static/custom.css.source.json, recording the source repository, path, full commit SHA, optional tag, SHA-256 of the copied bytes, and synchronization date. Do not put a mutable main URL alone in the receipt. The core repository’s MPL-2.0 license applies to this file.
Configure Furo with html_static_path = ['_static'] and html_css_files = ['custom.css']. Put product-specific additions in a separate stylesheet loaded afterwards, keeping the shared copy unchanged.
Review the upstream diff since the previous receipt and build the companion docs locally. Check light and dark themes, narrow layouts, navigation, and a codename image. Commit the copy and receipt together, then publish through that product’s release process.

Core CSS changes must be noted in the CHANGELOG and documentation handover, with the source revision and a short description of what companions should review. Companion owners compare that revision with their receipt; updates are deliberate release work, not automatic drift. A core release does not silently change either companion’s already published appearance.

A possible later refinement is a versioned artifact containing the CSS and header/footer partials at a stable public URL, with checksums and immutable version URLs. Companion builds could fetch a deliberately pinned version. This is a proposal only: no endpoint, package, or build fetch is implemented.

Codename galleries¶

Galleries are per product. Each repository owns its release images, gallery page, and contact sheet, and publishes them under its own docs path. The vibe-qc homepage and contact sheet contain only vibe-qc releases. vibe-view and vibe-queue start their own series and numbering; their version numbers and release dates need not match the engine’s.

All products use the 1672 x 941 PNG canvas. Filenames include the product, version, and codename; alt text names the product and version and identifies AI-generated artwork. Keep generation provenance with the owning assets. Release owners approve a codename before promoting its artwork to the released gallery. Update that product’s contact sheet at the same time.

The six upcoming vibe-qc images, v0.17.0 through v1.0.0, remain candidate or provisional planning assets. They do not announce shipped releases. A future marketing family gallery may link the three product galleries, with explicit product labels; it should not merge their version sequences or duplicate their image collections.