Workshop adoption doctrine and execution plan

Status: agreed direction; execution checklist starts open, 2026-09-20.

Outcome and doctrine

Turn the five demos into an adoption loop: encounter a familiar problem, get a useful result, use Workshop on your own configuration, and keep using it. More Catalog coverage alone does not establish that loop. Each demo is also a hook for ConfigHub: it must reveal why the model matters and offer a useful next action, not merely demonstrate a diagnostic command.

Help people turn configuration intent into working, maintainable systems, starting with the chart, app or configuration they already have. A whole stack is an optional starting point and a natural extension, not an entrance requirement.

Configuration as data means making actual configuration explicit: flattening source templates and generators into concrete objects we can inspect, compare, adapt and retain. Where behavior cannot safely be flattened, preserve its source, lifecycle requirements and authority explicitly. Flattening alone establishes neither successful deployment nor safe upgrades or rollback.

Users should understand that simple foundation. They should not have to master OCI shapes, lifecycle routes or proof-lane vocabulary before getting help. Explain why, what and how upfront. Defer operational depth to readable Guides and reference docs; machine contracts support the Guide rather than replace it.

The agent proposes; independent checks determine what passed. Neither confident language nor a static result proves application health. The manual path remains first-class, including CI and recovery without AI.

The governing question is: what responsibility can a user confidently hand over today, and what additional evidence lets them hand over more tomorrow?

Scope and relationship to existing plans

This is the current adoption delivery sequence, supplementing the unified backend ledger and agent configuration work. Their unfinished integrity, source, runtime and infrastructure obligations remain open; this plan does not reset their statuses. Use existing issues and evidence before making new ones. Seven implemented technical blocks do not establish an adoption outcome.

Preserve the current website IA. Do not add navigation sections, redesign all pages or launch another general prose pass. Improve complete journeys within the existing pages and Guides, starting with measured obstacles. No homepage framing or commercial positioning choice is silently settled by a pilot experiment.

The five demo journeys reviewed at commit b82bcb4 are core acceptance journeys, not the entire market. Flux and Argo onboarding, Kubara platform composition and GPU/fleet keystones remain parallel entry points. They do not require users to progress through a Helm tutorial first.

Five hooks and their ConfigHub reveal

Each follows: recognizable pain -> discovery -> useful resolution -> demonstrated ConfigHub value or explicitly labelled continuation -> one next action. A local Workshop check must never be presented as having exercised Server.

Guide and public-page contract

A demo shows value; a Guide helps a person and agent do the work on their own inputs. Each journey must map an existing entry page to an existing Guide, demo, commands, evidence and own-input continuation. Repair existing Guides before creating duplicates. Missing mappings become tasks, not invented URLs.

The initial view explains the problem, simple model, expected outcome and one primary next action. Within the Guide provide:

• Prerequisites, tested versions and approximate time, separating setup from work.
• AI mission and deterministic manual path with equivalent acceptance outcomes.
• Meaningful choices and their consequences; do not hide a lost requirement to pass a check.
• Expected artifacts, success, specific refusals and recovery instructions.
• What was checked, what remains unknown, and what needs authorization or a target.
• Save/resume and one action on the user's own input.
• Optional ConfigHub continuation with its actual value and dependencies.

Keep essential model explanations visible. Put detailed syntax and evidence behind relevant links. Professional presentation means consistent hierarchy, terminology and spacing, fewer competing actions and less repeated prose-not simply shorter text. Inspect desktop and narrow layouts. Use human feedback for visual quality; agent success alone cannot establish it.

Existing Guide starting points

These are audit starting points, not assertions of complete journey coverage. A0 must resolve the full demo commit SHA and verify the entry links and evidence at the pinned revisions; record any changes since the reviewed baseline.

Executable work queue

One lead owns synthesis, acceptance and integration. Bounded audits and routine fixes go to lower-cost agents. Every row produces a reviewable artifact and can be resumed from its ID. Checkboxes are completion records, not forecasts.

Rapid delivery cadence

First work session: A0 and A1 in parallel, then a short ranked blocker list and small reliability PR. Next session: A3 and the A4 pilot, while A7 inventories parallel Guides and A8 prepares recruitment. Propagate with A5 only after pilot acceptance. A6 fills evidenced product gaps concurrently in isolated branches. Sessions describe sequencing, not guaranteed wall-clock delivery or daily quotas.

Each PR should be reviewable in about ten minutes. Record what changed, the receipt or test proving it, gates and person dependencies. Run narrow checks, then the repository's required full gate on the final source; use exact-head CI before an authorized merge. Never bypass checks for speed or add new failures to the known-red register. Reuse successful checks only for unchanged inputs.

Parallel entry points: required acceptance

Use the fleet requirements and existing UX readiness work; do not duplicate their contracts. No representative fleet CRD, target access or H100 evidence is invented to finish this plan. Record the dependency, owner role and independently runnable next task.

Measurements and acceptance decisions

For every trial retain: journey, date, pinned revisions/tool versions, manual or agent mode/model, setup time, time to first useful result, help/retries, checks run, retained artifacts, outcome, unsupported claims, comprehension and next action. Private configurations and credentials stay private; public reports use consented, anonymized observations and synthetic or approved artifacts.

Use a simple 0/1/2 rubric: failed, completed with intervention, independently completed. Score outcome correctness, intent preservation, model comprehension, evidence limits and save/resume separately. Record elapsed time, not just a score. Ask the person to explain what configuration-as-data means, what changed, what was proved and why ConfigHub helps. Do not prompt them with the desired answer.

Operating thresholds for this first experiment (not market claims): obtain three fresh agent trials and two human trials of the pilot, with at least two of three agent trials and both human trials independently reaching a correct useful result. Both humans must explain the basic model and identify the next action without coaching. Retest with fresh sessions after material fixes. If human participants are unavailable, mark human acceptance pending and limit propagation to objective correctness fixes. Widen outreach beyond the initial cohort only after at least six of ten people reach useful results on their own inputs and at least three demonstrate a second use or retained workflow within the agreed observation window; otherwise investigate the failing stage. These small-sample thresholds are practical stop/go rules, not estimates of population adoption.

Pilot acceptance also requires correct results, no critical authority/secret/evidence violation, no lost requirement, and no regression in locating the next action. Expand only when observed friction decreases and human review supports clearer presentation. A small trial is directional evidence, not statistical superiority.

Adoption funnel: relevant arrival -> useful result -> own-input success -> repeat use or retained CI/agent check -> team sharing/governance. Record denominators and observation windows. Check return use after seven days where participants consent; distinguish no response from confirmed non-use. Treat GitOps/platform and enterprise fleet cycles separately from quick individual trials.

The release gate and adoption gate differ: passing scripts/CI permits shipping; it does not prove usefulness, demand or retention. We have not met the adoption goal until actual users supply that evidence.

Cost discipline and handoff

Default bounded execution to a lower-cost agent. Give it only the necessary paths, one concrete outcome, forbidden mutations and a stopping condition. Use at most two cheap workers plus the lead initially; increase only for clearly independent work. Reuse compact evidence maps instead of repeatedly sending the whole chat. Stop a worker after one report/PR; escalate ambiguous semantics to the lead instead of repeated blind attempts.

Reserve stronger reasoning for doctrine, prioritization, UX synthesis, technical ambiguity and final review. Separate implementation agents from fresh trial agents. Run live lanes serially on an awake machine; never parallelize shared regeneration or cluster work. Record agent/model, elapsed time and available usage information; do not invent monetary savings. Avoid redundant full-suite runs.

Each completed work item records status, PR, exact evidence, unresolved limits and next ID in the tracking issue. A resumed session reads this plan and that issue, selects the first ready item and updates the user with findings-not activity counts.