# Adapting a selected template

Direct input: `vitris site create --from URL --template "catalog ID, name, or hosted URL" --content "exact text"` (or `--content-file FILE`) records the chosen template upfront; `vitris run` and `npm run go -- ...` accept the same template/content options. A recorded direct request has `adaptation.checkpoints: "automatic"`, `sections: "agent-decides"`, and `aiImages: "no-ai"`. Continue the active-agent loop through local preview without asking for picker selection, adaptation setup, missing-content decisions, or representative feedback. Read `onboarding/additional-content.md` alongside harvested evidence, preserving supplied wording and explicit corrections. Inspect and inventory the chosen template, retain its defining relationships, and keep all critic, fidelity, browser and quality gates. Use the representative comparison to repair defects before expansion. Missing facts become visible fill-ins and still block launch. This is an operational continuation contract, not a fabricated answer or human design endorsement. The interactive instructions below apply when automatic checkpoints have not been explicitly requested; exact image/removal policies and any saved feedback still apply.

New redesign scaffolds enable `launch.json.templateAdaptation: {version:2}` and template selection. This adds a common checkpoint for picker, chat, CLI and imported choices. A choice without adaptation preferences stops before reference authoring and offers preserve-and-ask and ask-each suggestions. Suggestions never become answers automatically. Existing selections retain their policies until explicitly opting in; managed upgrades preserve launch.json and do not manufacture migration answers.

The workflow writes pending questions to `agent/template-questions.json` before creating a stage lease or consuming an attempt. Ask related content questions together, show each exact image treatment separately, and retain existing session authorization. Record a prior explicit answer verbatim when it already resolves the current question. Use `vitris-themes answer --site ABSOLUTE_SITE --file ABSOLUTE_RESPONSE_JSON`, with `{id,proposalHash,source:"user-chat"|"user-ui",instruction:"exact answer",value:...}`. Policy value is the preference object below; content value is `defer`, `provided`, or `request-removal`; image value is `approve` or `decline`. Keep supplied notes in instruction. `defer` completes the decision while retaining a designed fill-in. Removal requests stop dependent work until the exact removal proposal is revised and its existing human instruction recorded. Retries retain answers; changed questions require new answers. Test simulations use the distinct test-simulation source and never establish human preference.

Before direction, the separate `template-reference-review` critic examines `onboarding/template-inventory.json` against every pageId in the selected catalog revision. The reference-analysis owner writes `{version:1,selectionHash,evidence:[{path,sha256}],pages:[{key:"catalog pageId",url,sections:[{id,label,role,mediaRole,rhythm}]}]}`. Section IDs are globally unique, including recurring navigation, opening, development, case modules and closing. Evidence hashes bind real inspected captures. Independently inspect the reference and evaluate page/section coverage, media roles, personality/rhythm and customer mapping. Do not call an author inventory complete without checking it against the live reference. Every adaptation section includes `referenceIds`; several related reference sections may map to a useful customer section with an explained relationship. Missing inventory pages or unmapped section IDs fail. The critic writes a standard version-2 review bound to the current inventory, adaptation and selection via `vitris-eval --subject`, with located checks for `page-coverage`, `section-coverage`, `media-roles`, `personality-and-rhythm`, and `customer-mapping`. A critic assessment remains distinct from human approval.

For each AI image proposal in version 2, include `commissionHash: digest(exact VisualCommission)` and `references: [{assetId,path,sha256}]` (an empty list for an original illustration). Plan the full commission alongside the proposal so the eventual asset brief reproduces it. Hashes cover purpose, treatment, identity, commission and reference bytes; the decision store separately binds the selected template. Generation dispatch checks authorization before calling the host adapter or writing a generation record, and registration checks again. Changed commission or source bytes require a revised proposal and answer. Valid earlier exact image decisions remain valid; declined proposals retain the agreed placeholder or alternative. A host image tool called directly outside the harness must follow the same human instruction; the harness cannot intercept unrelated external calls.

Before copy expansion, show the actual representative homepage and interior with the current reference comparison and ask for feedback. Save `representative-feedback` with `continue` or `refine`. Refinement feedback is retained and blocks expansion until a repaired comparison receives a new response. No author lease or repeated attempt is consumed while waiting. `vitris-themes queue --site ABSOLUTE_SITE` derives a current content refinement queue with route, target, owner, status, exact decision and next action. For archived experiments ask about original context, historical process and lessons; do not imply an active project or require current results. Unfinished sections continue to block launch.

When a selection has `adaptation: {version:1, sections, aiImages, priorities}`, treat it as the user's adaptation contract. The picker asks these questions before saving. Chat choices use `vitris-themes select ... --adaptation-file ABSOLUTE_JSON`; keep exact wording in notes and priorities. Legacy selections without this field remain compatible. Test simulations and agent delegation never establish human preference.

During reference-analysis, inspect the actual selected template, including its interior pages and interactions. Write `onboarding/template-adaptation.json`:

```json
{
  "version": 1,
  "selectionHash": "currentSelectionHash from the selection store",
  "reference": {"url": "https://hosted-template/", "evidence": ["onboarding/reference-home.png"]},
  "qualities": [{"id": "cinematic-opening", "relationship": "Describe the actual visual/emotional relationship", "implementation": "Locate the customer equivalent and its interaction"}],
  "sections": [{"id": "selected-work", "referenceSection": "Selected work browsing", "disposition": "adapt", "route": "/", "targetId": "selected-work", "content": "placeholder", "nextStep": "Ask the owner to supply project scope and results; retain until answered"}],
  "images": [{"id": "project-cover", "purpose": "Work preview", "treatment": "Exact proposed art direction", "identity": "Concept artwork, not a customer project photograph", "status": "proposed"}]
}
```

Inventory every major reference section and recurring experience, including footer, navigation, project browsing and case-page development. Do not reduce a rich template to a palette, large heading and two rows. Preserve its relationships, density changes, media roles, motion and quiet intervals. An intentional customer adaptation can change labels and facts while preserving that experience. Missing source material calls for a content question, draft copy or a placeholder, with a concrete next action. Inspect retained raw markup before claiming the source has no content.

For `sections: preserve-ask`, every removal needs a direct human answer. For `aiImages: ask-each`, propose each image's purpose, treatment and identity separately and wait for that answer before generating. `no-ai` prohibits AI production. Approved proposals and removals are recorded in `agent/template-decisions.json` as `{version:1,selectionHash,decisions:[{kind:"generate-image"|"remove-section",id,proposalHash,source:"user-chat"|"user-ui",instruction:"exact answer"}]}`. Compute proposalHash with `templateProposalHash`; changed image treatment/identity or changed selection invalidates the answer. Do not write that decision file from an authoring stage or fabricate an answer. Image status alone is not approval. Declined/proposed images retain their visual place using a placeholder or agreed alternative.

Bind retained sections to real route target IDs. Visible content gaps carry `data-content-gap="SECTION_ID"` and a readable fill-in prompt; no hidden dummy content or fictional achievements. Author drafts as explicitly unfinished local-preview content and keep them separate from verified business facts. A local preview may have these gaps; launch preflight blocks them until resolved. Record the content owner/question in nextStep. Follow existing source/media provenance and accessibility requirements.

Before expansion, compare the representative page with the selected reference and follow the recorded feedback policy. During representative-review and visual-review, add `templateFidelity: {selectionHash,distHash,qualities:[{id,referenceEvidence,referenceHash,implementedEvidence,implementedHash,observation,verdict:"pass"|"fail"}]}` to the normal review. Reference evidence must be a PNG or JPEG listed in the adaptation brief and, when template inventory is enabled, in its hashed evidence list. Implementation evidence must be a successful screenshot in the current representative-browser or browser report. Each hash is `fingerprint(siteRoot, [evidencePath])`; use the exact current file. Include every brief quality, explain the visual relationship observed, and capture before/during/after for temporal claims. Passing a mechanical check does not establish expressive motion or human approval. Repair lost relationships before expansion.

During refinement, resolve the recorded gaps one by one: fill, revise or ask before removal. Preserve the original brief and decision history through supported workflow invalidation/managed-kit upgrades.

For directions defined by movement, follow [the temporal comparison contract](template-motion.md). Keep its plan, captures, critic observations and actual human feedback distinct.

An answer may include a durable `operationId` to distinguish a new instruction from a replay. Exact retries do not change history; a new explicit reversal becomes the current response for that proposal. Refine feedback returns ownership to representative authoring through normal workflow invalidation. A removal request returns to reference-analysis to revise the exact mapped proposal and record the existing instruction. These are agent repairs, not new unanswered human questions. Counter history and prior responses remain intact.

For sites with typography version 1, load `typography.md`. Establish concrete shared roles before authoring, reuse sizes and weights across routes, retain the 12px rendered floor, and repair browser typography findings before acceptance. Template identity does not waive this policy.