Site IA - phase 3: earn trust, prompt action

Phase 1 built the section structure; phase 2 settled the IA (one page per concept, evidence on GitHub, five-section nav). Phase 3 works the layer phase 2 left alone: the words and the wayfinding on the pages a reader actually lands on.

Purpose

The site is now navigable but not yet persuasive, and structure is the wrong lever to keep pulling. So phase 3 has one job: make every top page earn trust and move the reader to run cub. Above all, the home page must say, in order, (a) why we are here, (b) what you can do, and (c) what you actually get - and the rest is links. Each finished page passes two tests:

• Trust. Every claim is honest and traceable; no hero-level overclaim, no vocabulary drift, evidence one click away.
• Action. A newcomer knows exactly what they can DO next and why; every heading and lead carries a verb; the free/account/paid path is obvious; no page is a dead end.

Who does what

• The top pages: the maintainer authors, the site session implements. The maintainer hand-crafts the content and structure for each top page; the session turns it into the generator's builders and the UX-contract terms, runs the full gate set, and keeps the site consistent.
• The columns and the code-block doctrine: the site session owns them. These are wayfinding and layout, not voice.

The top pages (hand-crafted, in order)

1. index.html - home (fully specified below).
2. charts/index.html - Catalog.
3. config.html - Config.
4. stack.html - Stacks.
5. how-it-works.html - Operate.
6. confighub.html - ConfigHub Server (the conversion / product page).

Each gets its own worked section in this doc as the maintainer hands over its content. Home is done; the rest are placeholders until then.

Doctrine: code blocks (applies to EVERY page)

The maintainer marked this doctrine, so it is a hard rule, enforced by the UX contract, not a per-page preference:

1. The comment goes ABOVE its command, never after it.
2. No line wraps. No command or comment line may run to two or more visual lines; shorten the command, the path, or the comment instead.
3. Comments are short, relevant, and real - one plain phrase that says what the command does or shows, not a label or filler.
4. No label text bleeds into a block (e.g. the stack.html block currently opens with "one install, three commands" as if it were code - that is a heading, and belongs outside the block).

Implementation: one shared code-block renderer (commandBlock(...) or similar) that takes {comment, command, result?} rows and emits comment-above, no-wrap-checked markup, so a block cannot be authored the wrong way. A UX-contract check scans every generated <pre><code> for a command line preceded (not followed) by its comment and for over-long lines, and fails the build otherwise. Audit order, worst first: charts/index.html, stack.html ("one install, three commands"), index.html, then the rest.

Retitle the home ladder caption free check → certified stack → governed release toward "use cub open source, or upload to ConfigHub Server."

The columns (left and right)

Left column. Content pages carry a "Sections" sidebar that is the entire site map, repeated identically everywhere, unscoped, with inconsistent labels (short nouns next to long questions). Phase 3:

• Give the labels one consistent style.
• Scope/highlight it to where the reader is ("you are here").
• Home gets its own left column: a curated action/persona column (distinct content from the Sections sidebar, same visual pattern) - the five persona doors expanded to 7–10 action links.

Right column. Today it is the on-page TOC (the current page's h2s). Keep that, and add a short "where to go next" so the rail is not a dead end.

Home page - worked specification (from the maintainer's notes)

Target spine: why → what you can do → what you get → links.

1. Why we are here (top, unchanged in place)

The hero ("Compose a platform or stack from the public Catalog") and the one-line paragraph: "ConfigHub Workshop is a verified catalog of tested configuration, stacks and platforms on demand. You can use these for apps, platforms, and stacks in ConfigHub."

2. What you can do (MOVE UP, under that paragraph; improve)

The "What do you need help with?" section, moved directly under the intro paragraph and rewritten to the maintainer's copy:

• Intro: "You need a configuration, you have one, or you want a whole platform. Start from where you are. Each path gives you exact files and a result you can keep, and the free ones need no account." + a Search entry.
• Six numbered paths: (1) You need a configuration; (2) You have one - is it right?; (3) You want a whole platform; (4) You already run Flux or Argo CD; (5) A team needs to share, approve, and promote it; (6) You run AI on GPUs. (Full copy in the maintainer's notes; carry it verbatim, subject to the 32-word cap and the code-block doctrine.)
• The five-word definitions block (config, app, stack, platform, fleet), each pointing at its canonical page.
• The upstream-moved note (successor + digest-drift check) and the closing links (six worked examples, the short Redis example, choose a deployment method).
• A light version of "Four common Helm questions" folds in here; the full content moves to the Helm/ask page (both).

3. What you get (MOVE DOWN; strengthen)

"What ConfigHub Workshop is" moved below "what you can do", kept as the three parts, strengthened per the notes: (1) A verified catalog (112 components, 139 versions; verified, certified, and signed); (2) Stacks and platforms on demand; (3) Operate apps, platforms, and stacks correctly in ConfigHub. Each part keeps its "What you can do" / "What problem this solves" pair.

4. Links and relocations

• The five persona buttons become the home left-hand action column (7–10 links), same visual pattern as other pages' sidebars.
• The verb-strip ("cub is ConfigHub's command line…") comes OUT from under the code block into a small "Getting started with cub" block (install cub → add the plugin → what is free), not caption text.
• "Check the result and the limits" - internal jargon; fold into Catalog or Docs, off the home page.

Gates (every page, before it ships)

• The code-block doctrine check (comment-above, no-wrap, no bled-in labels).
• The trust test: no unbacked claim; every "verified/certified/signed" style claim traceable; house voice (verbs in headings, no banned patterns, 32-word cap).
• The action test: each page names a next step; the free/account/paid path is visible.
• The full CI verifier set, run locally: code-blocks:verify, site:ux:verify, site:verify, variant:command-surface:verify, verify:machine-contract, chart-claim-integrity:verify, config-model:verify, docs:verify, doc-freshness:verify, verify:no-personal-names. Adding an authored doc also requires npm run doc-freshness and committing its snapshot.

Order of work

1. The shared code-block renderer + its contract check, applied to the three worst pages (charts/index, stack, home).
2. The home page restructure (this spec) + its left action column.
3. The left/right column pass across the content pages.
4. Catalog, Config, Stacks, Operate, ConfigHub Server - each as the maintainer hands over its content.

Open questions for the maintainer

1. The home left action column: which 7–10 links? (Draft: the five persona doors + Search + Catalog + Try Redis + the ten-minute demo.)
2. Do the content pages keep the full-site "Sections" sidebar, or does it also become scoped/curated like the home column?
3. "Check the result and the limits" - Catalog or Docs as its new home?