@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.5

package/agent/refs/industry-reference-shortlist.md

@@ -0,0 +1,64 @@
+# Find five industry website references
+
+Deliver a current, evidence-backed shortlist of five different businesses with strong website design for the requested industry. The purpose is to help the operator choose references for the template library. Default to worldwide discovery, English-language sites preferred, and diversity in design approach. Honor user-supplied region, niche, or style filters. A website's design does not establish the quality of its business's services.
+
+## Research and selection
+
+- Search the live web using several complementary queries: industry and niche terms, geographic variants, and design/agency showcases. Broaden beyond the first search results. Consider roughly 10-15 plausible candidates when available, then select the strongest complementary five. This is an effort guide, not a quota that establishes quality.
+- Use showcases and award directories to discover candidates, then visit the actual business sites. The final five link directly to working business websites, not search results, screenshots, directories, agency portfolios, or unbuilt template demos. Prefer industry specialists; explain why any mixed-industry business is relevant.
+- Confirm that each selected URL resolves to the intended live business. Use the current canonical URL after redirects. Deduplicate by business and substantially identical design, including related franchise sites or domain aliases. Do not claim different colors on the same layout as five distinct approaches.
+- Inspect the complete home page, at least one useful interior page, and the main conversion/navigation path for each selected site using an available browser capability. Check desktop and mobile, exercise menus and one defining interaction where present, and observe motion if it contributes to the selection. Follow applicable browser tool instructions. A static page or search snippet cannot verify an animation or mobile drawer.
+- Judge visual hierarchy, typography, composition, photography/media, coherent identity, industry suitability, ease of navigation/conversion, responsive execution, and relevant interactions. Choose approaches that differ in composition and visitor journey, such as service-first utility, editorial craft, premium residential, project-led expertise, or friendly local identity. Use labels supported by the actual sites, not a fixed mandatory set.
+- Record the inspected source URLs and observation dates. Separate observed features, inferences about implementation, and unverified behavior. Do not fabricate ratings, awards, traffic, performance measurements, or user preference labels.
+- Replace inaccessible or clearly weak candidates where possible. If fewer than five can be verified after reasonable research, report the concrete limitation and remaining candidates rather than filling the artifact with invented or uninspected recommendations. The renderer intentionally requires five; a partial research report is a separate explicitly incomplete artifact.
+
+Keep candidate URLs, selection/rejection notes, and selected-site observations in the run's `shortlist.json`. Do not clone these websites, collect their assets, alter the existing template gallery, or publish a catalog entry. This workflow creates local reference metadata and a research artifact, not a complete template demonstration. Browser screenshots are optional supporting evidence; do not generate fake previews or use screenshots as a substitute for opening the live site.
+
+## Artifact data
+
+Create a fresh `artifacts/research/industry-references/<industry>-<timestamp>/` directory. Write `shortlist.json` with this shape, supplying real research values rather than leaving the sample text:
+
+```json
+{
+  "industry": "Plumbing",
+  "region": "Worldwide; English-language sites preferred",
+  "researchedAt": "ISO_TIMESTAMP",
+  "criteria": "Visual quality, usability, interactions, and distinct design approaches.",
+  "summary": "Describe the selection and the most useful differences among the five.",
+  "candidatesReviewed": 12,
+  "candidates": [{"name": "Business", "url": "https://business.example/", "decision": "selected or rejection reason"}],
+  "sites": [
+    {
+      "name": "Verified business name",
+      "url": "https://business.example/",
+      "location": "Verified country or region, or unknown",
+      "approach": "Observed design approach",
+      "why": "Specific reason it is a strong reference and complements the other selections.",
+      "layout": "Observed structure, composition, and imagery.",
+      "typography": "Observed type hierarchy and identity; qualify unidentified font names.",
+      "interactions": "Actually exercised navigation, hover, or animation, with unverified behavior stated.",
+      "mobile": "Observed mobile layout and navigation at the checked viewport.",
+      "checkedAt": "ISO_TIMESTAMP",
+      "pages": [{"label": "Service page", "url": "https://business.example/service", "note": "What to inspect here."}],
+      "evidence": [{"label": "Homepage inspected", "url": "https://business.example/"}],
+      "limitations": "Relevant caveats or deliberate gaps; use None observed when appropriate."
+    }
+  ]
+}
+```
+
+Include exactly five site records, each belonging to a different business. `candidatesReviewed` counts distinct candidates actually investigated, not search result counts. `candidates` is an optional audit trail; keep its count consistent with the claimed research. Lists of source links alone do not substantiate invented observations.
+
+Generate the artifact from the repository root:
+
+```text
+node scripts/render-industry-shortlist.mjs --input ABSOLUTE_SHORTLIST_JSON --out ABSOLUTE_INDEX_HTML
+```
+
+The renderer produces a responsive, self-contained HTML file with no remote libraries, embedded websites, or popup scripts. Its ordinary `target="_blank"` links let the user open each reference independently. Each card includes a selectable template-skill command; it does not execute the skill or publish a template.
+
+## Verify and deliver
+
+Open the generated HTML in a browser and check five cards, readable desktop/mobile layout, complete observations, working canonical/interior links, and new-tab behavior. Confirm that source/evidence links support the actual claims. Resolve bad links or factual issues before delivery. Do not automatically open all five sites in user-visible tabs as a substitute for link verification.
+
+Use `open_in_codex` with the artifact's absolute file path when available, then return a clickable file link and the invocation example. State research scope and any material inspection limitations. The artifact is the primary deliverable; do not make the user reconstruct it from chat messages. Leave template selection and subsequent building to the user.

package/agent/refs/inspiration.md

@@ -0,0 +1,17 @@
+# Read references as design systems
+
+The operator's references illustrate thoughtful business-specific design:
+
+- https://verdict-nextjs-template.vercel.app/ — restrained authority, editorial hierarchy, and evidence appropriate to professional services.
+- https://apex-nextjs-template.vercel.app/ — tangible work, materials, process, and a clear service inquiry.
+- https://munch-nextjs-template.vercel.app/ — a restaurant identity expressed through typography, color, photography, and menu presentation.
+
+These are references to inspect when useful, not industry templates to reproduce. Describe the visible relationship you would borrow and why it serves this business. For example, a large project photograph followed by a compact process explanation can move a visitor from evidence to action. A dark band or rounded card by itself has no such rationale.
+
+Look at the whole page and a representative interior. Ask what gets the largest emphasis, where density changes, how photographs are framed, how type creates identity, what repeats, and how a visitor reaches the primary action on mobile. Separate observed reference details from your own proposals.
+
+Use those relationships to develop distinct candidate directions with the actual business facts and available media. Avoid assigning an industry a fixed hero, card style, section sequence, blurred header, or footer treatment. A restaurant with little food photography needs a different solution from an image-rich restaurant, even when both share a category.
+
+Use the local block index only after the narrative and composition are established. Adapt or create site-owned components when needed. Preserve ordinary accessible control behavior and translate ideas into the harness's HTML/CSS system; reference framework APIs are not part of the design brief.
+
+Never import a reference's claims, awards, testimonials, people, prices, or assets as evidence about the client. If a reference cannot be inspected, say so and use the captured business evidence to make the direction decision.

package/agent/refs/interpret.md

@@ -0,0 +1,3 @@
+# interpret
+
+Compatibility entrypoint. Workflow graph uses business.md to interpret the offer and media.md to account for source assets. Load the relevant reference only when needed. Preserve factual accuracy and evidence integrity; keep unsupported assumptions explicit.

package/agent/refs/jev.md

@@ -0,0 +1,166 @@
+# Skill: jev
+# Jev Decision Service & Compact Context Operations
+
+This reference documents the bounded decision service and compact packet mechanisms powered by TypeSafe's Jev model (`jev-1.13.0`) in `@tryvitris/website-harness`.
+
+## Core Philosophy
+
+- **Code Validates & Controls**: Graph transitions, review contracts, browser testing, and exact quote matches remain code-enforced.
+- **Jev Evaluates Bounded Semantics**: Evaluates atomic claim-to-excerpt relations, planned CTA consistency, and engineering change scopes. Jev does not author long-form prose, invent facts, or inspect screenshots.
+- **Critics Retain Full Gate Ownership**: All critic checkpoints, review schemas, and editorial obligations remain 100% intact. Preflights provide supplemental evidence; machine judgments never autonomously pass or fail a review gate.
+
+## Operational Modes & Capability Toggles
+
+The Jev system supports global operational modes and fine-grained capability toggles.
+
+### Global Modes
+
+| Mode | Behavior | Use Case |
+|---|---|---|
+| `off` (default) | Standard full-packet workflow. No Jev API calls or preflight injection. Zero overhead. | Production default until calibrated rollout gates pass. |
+| `shadow` | Runs bounded evaluations in background; writes immutable decision receipts to `agent/decisions/jev/`. Prompt and transitions remain identical to baseline with zero side-effects. | Comparative benchmarking, telemetry, and offline validation without affecting production output. |
+| `assist` | Attaches machine grounding preflight summaries to critic context when `grounding` is assist. Compact packets are a separate toggle. | Additive critic evidence. No workload reduction unless `workOwnership=delegated` and a harness calibration artifact is eligible. |
+
+Configure global mode via:
+- CLI flag: `--jev-mode <off|shadow|assist>`
+- Environment variable: `VITRIS_JEV_MODE=<off|shadow|assist>`
+- Site configuration: `agent/jev.json` (`{ "mode": "off|shadow|assist" }`)
+
+### Granular Capability Toggles
+
+Individual capabilities can be independently configured in `agent/jev.json` under `capabilities`:
+
+```json
+{
+  "mode": "assist",
+  "capabilities": {
+    "grounding": "assist",
+    "sourceSelection": "assist",
+    "retrievalRanking": "assist",
+    "consistency": "assist",
+    "repairAssistance": "assist",
+    "preferenceScoring": "assist"
+  }
+}
+```
+
+- `grounding`: Atomic claim-to-excerpt verification and contradiction tracking (production Jev caller on business/narrative/copy review).
+- `sourceSelection`: Local lexical citation **ordering** on critic preflight (does not drop sources). Business-author field selection batches independent questions: Choice + no-match for single-value fields, per-candidate Noul for offers/locations. Transcription drops only after complete coverage.
+- `retrievalRanking`: Assist mode shortlists with cheap lexical retrieval, then Jev Score for optional excerpts. Cited and contradictory evidence are kept regardless of rank. Shadow computes receipts but does not change packets. Off remains lexical MMR.
+- `consistency`: Cross-stage claim lineage helpers. Registry task is experimental; no production Jev caller.
+- `repairAssistance`: Targeted repair packet construction and resolution helpers. Integrated critic replacement is not claimed.
+- `preferenceScoring`: Local rubric matching. Neural direction/media scoring is experimental and unimplemented as a production caller.
+
+*Note*: An individual capability's effective mode is always clamped to the global mode ceiling (e.g. if global mode is `shadow`, a capability set to `assist` runs in `shadow`).
+
+## Provenance Tracking & Canonical Question Semantics Hashing
+
+To ensure reproducible judgments, auditability, and tamper-resistance:
+- **Canonical Serialization**: Questions and states are canonically serialized and hashed with SHA-256 (`questionSemanticsHash`).
+- **Decoupled Raw Judgments**: Raw model judgments (`choice`, `confidence`, `rationale`) are stored in the Evidence Ledger independently of application policy thresholds. If confidence thresholds change, raw judgments remain valid and are re-evaluated by policy without re-querying the model.
+- **Cache Invalidation**: Inference cache keys in `agent/decisions/jev/cache/<hash>.json` depend on `(inferenceSchema, model, questionVersion, questionSemanticsHash, questions, state)`. Policy version is applied after the raw answer and does not force another TypeSafe call. Legacy unwrapped cache envelopes are ignored.
+
+## Bounded Packet Expansion & Diverse Retrieval
+
+When compact packets (`--compact-packets`) are active, large source dossiers are partitioned into a coverage manifest (`agent/runs/<node>.manifest.json`).
+
+1. **Maximal Marginal Relevance (MMR)**: `selectDiverseEvidence()` balances relevance with source diversity across all captured files, preventing a single verbose harvest file from monopolizing the packet budget.
+2. **Atomic Obligation Partitioning**: `partitionByObligation()` groups evidence items by critic checklist obligations. Items belonging to the same obligation are never split mid-sentence or mid-obligation across packet boundaries.
+3. **Overflow Re-Hashing Verification**: When an agent expands an item from the coverage manifest using `expandPacketItem()`, the system computes a SHA-256 hash of the actual content on disk and compares it against the manifest hash. If content was tampered with, expansion is rejected.
+
+To manually expand excluded context:
+```bash
+node scripts/eval-site.ts --site . --expand-packet <expansion-id> --node <node-id>
+```
+Every packet expansion is logged to `agent/runs/packet-expansions.log`.
+
+## Cross-Stage Lineage & Completeness Auditing
+
+- **Claim Lineage Tracking**: `traceClaimLineage()` maps evidence through all pipeline stages: `Source File -> Harvested Fact -> Copy Plan -> Rendered Page Section -> Review Finding`.
+- **Broken Lineage Detection**: `detectBrokenLineage()` flags copy claims whose cited sources have been modified, retired, or contradicted.
+- **Completeness Auditing**: `auditExtractionCompleteness()` audits copy plans against the Evidence Ledger, reporting:
+  - `uncitedClaims`: facts asserted in copy without declared evidence citations.
+  - `unregisteredClaims`: cited IDs that do not exist in the Evidence Ledger.
+  - `contradictedClaims`: claims citing facts that have unresolved contradiction status.
+
+## Targeted Repair Resolution & Escalation
+
+When a critic checkpoint fails:
+1. **Finding Signatures**: Findings are fingerprinted by target and issue type (`findingId`).
+2. **Targeted Repair Packets**: `buildRepairPacket()` extracts only the specific obligations and evidence slices needed to fix flagged defects, avoiding re-transmitting entire site briefs.
+3. **Repair Resolution Verification**: `verifyRepairResolution()` compares post-repair artifacts against pre-repair artifacts:
+  - Rejects no-op edits where the author claimed to resolve a finding without modifying the affected file.
+  - Detects persistent defect patterns when the same finding signature persists across iterations.
+  - Automatically escalates repeat findings: `polish -> warning -> blocking`.
+
+## Creative Direction & Preference Rubrics
+
+- **Dimensioned Direction Scoring**: `makeDirectionScoreQuestion()` evaluates visual directions against four distinct criteria:
+  - `business_fit`: alignment with industry and business model.
+  - `typography`: font pairing hierarchy, readability, and scale.
+  - `composition`: whitespace balance, layout rhythm, and responsive density.
+  - `authenticity`: bespoke vernacular presentation vs generic stock templates.
+- **Versioned Preference Rubrics**: `matchPreferences()` evaluates directions against client and brand preference rubrics (`agent/preferences.json`), providing positive signal boosts and applying penalties for banned anti-patterns.
+
+## Calibrated Rollout & Evaluation Harness
+
+The evaluation harness in `scripts/eval-jev.ts` provides matched benchmarking across treatment arms:
+
+```bash
+# Evaluate offline mechanics and live model endpoints
+node --experimental-strip-types scripts/eval-jev.ts
+
+# Configure a specific rollout treatment
+node --experimental-strip-types scripts/eval-jev.ts --treatment <A|B|C>
+
+# Measure the marginal impact of ablating a single capability
+node --experimental-strip-types scripts/eval-jev.ts --treatment C --ablation <component>
+
+# Empirically evaluate a completed trial directory with quality margin
+node --experimental-strip-types scripts/eval-jev.ts --trial-dir <path> --quality-margin 0.05
+```
+
+### Rollout Treatments
+
+- **Treatment A**: Jev `off`, `workOwnership=agent`.
+- **Treatment B**: Jev `assist`, `workOwnership=agent` (additive preflight; no claimed reduction).
+- **Treatment C**: Jev `assist`, `workOwnership=delegated` (packet reduction only for harness-calibrated, fully covered tasks). Lexical ranking and unimplemented registry tasks are not part of this treatment.
+
+### Evaluation Metrics
+
+- `shortlistRecall`: Proportion of relevant evidence items captured in the ranked candidate shortlist.
+- `defectRate`: Proportion of defective claims escaping verification gates.
+- `qualityMargin`: Allowable regression margin (default 5%) for quality preservation assertions in `compareRuns()`.
+
+## Implementation & Integration Status
+
+| Capability | Current Status | Architecture & Implementation Details |
+|---|---|---|
+| `grounding` | **Active / Production** | Atomic claim-to-excerpt verification using canonical serialized questions, SHA-256 semantic hashing, Evidence Ledger persistence, bounded batching, and configurable thresholding. |
+| `sourceSelection` | **Split** | Critic citation **ordering** is still lexical and must not drop sources. Business-author field selection batches Choice (single-value) and Noul (multi-value) questions. Default calibration remains ineligible. |
+| `retrievalRanking` | **Assist caller** | Lexical shortlist plus Jev Score for optional evidence when `retrievalRanking=assist` and a client is available. Mandatory/contradictory excerpts are retained. Off/shadow packets stay lexical. |
+| `consistency` | **Pending End-to-End Integration** | Core lineage tracing and broken lineage helpers implemented; cross-stage automated enforcement remains pending. |
+| `repairAssistance` | **Pending End-to-End Integration** | Repair packet building and edit resolution verification implemented; integrated critic repair loops remain pending. |
+| `preferenceScoring` | **Local rubric** | Local brand/craft rubric matching. It is not the creative-dimension caller. |
+| `creativeScoring` | **Advisory caller** | `scoreCreativeCandidates` runs from lifecycle on direction-review and representative-review when the capability is not `off`. Missing or invalid scores stay `unavailable` or `invalid`. They are not stored as zero. Assist text is advisory. Shadow does not change CURRENT.md. |
+| `componentSelection` | **Advisory caller** | Representative and pages preparation can rank a shortlist from semantic section state. Custom remains available. `draftAuthoringSnippet` is non-production and is not an authoring packet. |
+| `compositionCheck` | **Semantic caller plus deterministic preflight** | When the capability is not off, storyboard and representative preparation call `scoreCompositionRepetition` and write `agent/reviews/jev-composition.json`. Assist mode adds those judgments to the prompt. `off` makes no Jev call. Shadow records the receipt without changing the prompt. `agent/reviews/composition-preflight.json` stays a separate deterministic structure check. This task is uncalibrated and does not remove critic duties. Unavailable or invalid responses are not measured low scores. |
+
+> [!NOTE]
+> Evaluation of Treatment C token savings and workflow efficiency requires full empirical 3-arm active-agent runs to local preview with verified, observed quality. Synthetic constant multipliers and unobserved quality assumptions are disallowed.
+
+## Ownership, calibration, and rollout
+
+Confirmed setting name: `workOwnership: "agent" | "delegated"` (default `agent`). Orthogonal to global `off | shadow | assist`.
+
+- `off`: no Jev execution; prompt, ownership, and acceptance unchanged.
+- `shadow`: Jev may run and record receipts; consumed CURRENT.md, ownership, state, and acceptance stay identical to `off`.
+- `assist` + `agent`: grounding preflight and/or a source-bound business draft may be added; no workload reduction is claimed.
+- `assist` + `delegated`: a harness-calibrated, applicable, complete task may remove only its covered pairs/fields from CURRENT.md. Remaining items keep their excerpts. Every failure, incomplete coverage, missing manifest, exhausted budget, or invalid pilot context restores the full obligation.
+
+Delegation is not authorized by site `calibrationGates[].eligible`, registry `delegationEligible`, or a user-editable pilot boolean. Eligibility comes only from a harness-controlled calibration artifact bound to task version, question semantics, model family, dataset version, sample size, metrics, thresholds, and expiration. Pilot-only artifacts also require `issueTrustedPilotContext` passed into `prepareStage({ pilotContext })`.
+
+Default harness artifacts are ineligible. Delegated mode stays off until a task's calibration gate passes. Creative dimension scores are advisory and do not remove the agent's visual judgment. A paid live pilot is not part of `npm test`.
+
+`--design-assist` is the one-step advisory preset. It does not override `--jev-mode off`.
+

package/agent/refs/launch.md

@@ -0,0 +1,11 @@
+# Launch (optional)
+
+Only when the operator asks after `preview_ready`.
+
+1. `gh repo create ORG/SLUG --source . --private --push` (or push to existing remote).
+2. Set the real `launch.json.publicOrigin` and Cloudflare Pages build command to `npm ci && npx playwright install chromium && npm run build && npm run preflight`, output `dist`, production `main`. Set `VITRIS_SITE_ENVIRONMENT=production` on the production branch. Preview branches use `preview` and remain diagnostic. A direct `wrangler pages deploy` must follow a successful current preflight on the exact `dist` bytes.
+3. Register tenant in harness `/ops`: owner email (`launch.json` → `ownerEmail`), `pages_project`, `github_owner`, `github_repo`.
+4. Fill `launch.json` → `github`, `publicOrigin` when known.
+5. Owner admin: `{backendOrigin}/app/login` with `ownerEmail`.
+
+Do not merge secrets into git. Use `.env` for Cloudflare tokens.

package/agent/refs/layout.md

@@ -0,0 +1,7 @@
+# layout
+
+The selected site direction governs identity choices. Typography gives distinct jobs to orientation labels, propositions, explanation, precise data, captions, and actions. Use actual edited copy at real length; do not shrink or drop qualifications to preserve a sketch's silhouette. Test long names, wrapping, zoom, and fallback fonts.
+
+Compose responsive layouts from meaning and reading order. Keep captions with their subjects, qualification with the claim it limits, and action beside the decision it serves. At narrow widths, an honest stack can be the best arrangement. Verify focus order, reflow, and any sticky or overlaid content. Reuse tested primitives and use optional modern CSS only with appropriate fallback.
+
+In `composition-v1`, the creative packet also supplies stage-selected advisory lessons from the pinned release, including expandable bodies. Apply or decline them based on current evidence and inspect the result. In `blocks-v0`, follow the compatible block guidance. Preserve factual accuracy, usable interactions, and accessible markup in both modes. No section, image, font, or motif quota applies.

package/agent/refs/media.md

@@ -0,0 +1,35 @@
+# Understand and account for media
+
+Run `npm.cmd run media:prepare` on Windows (or `npm run media:prepare` elsewhere). It creates an inventory and HTML contact sheet without discarding prior decisions.
+
+Run `npm run media:serve` from the site and open its loopback contact-sheet URL in a browser. Inspect in batches and open candidates at full size. If the browser cannot reach the loopback URL, view local media files directly with an image viewer; a browser refusal of `file:` URLs does not waive visual inspection. Identify actual subjects, projects, people, illustrations, text baked into images, transparency, duplicate crops, and usable dimensions. Do not trust alt text as visual classification.
+
+Account for each image as use, retain, duplicate, or exclude with a specific reason. Keep important project collections available for interior pages; the shortlist can expand. Selected assets need actual visual inspection and intended route placements. If a signature asset appears in the source but is absent locally, recover it before passing; record unresolved acquisition separately.
+
+Keep onboarding/brief.json, onboarding/raw, and media/harvest immutable after acquisition. Save recovered originals under media/recovered and derived/cropped variants separately. Register each local recovered file with the installed harness tool, for example `npm.cmd run media:register -- media/recovered/mark.png --source onboarding/brief.json --disposition use --role logo --description "Customer wordmark"`. The command computes SHA-256 from actual bytes; repeat registration of identical bytes is safe, while changed bytes or conflicting IDs are rejected. Use `--disposition retain` for retained originals too. For videos supply `--poster media/recovered/poster.jpg`; the tool hashes both files. Registration leaves `inspected:false`: inspect the media, set disposition details and proposed placements, and add identityEvidence from captured source paths before completing media. Never hand-enter or silently replace an accepted hash. Inventory placements are proposed routes; the storyboard establishes final route/section placement.
+
+Choose treatments that fit the material: contain device mockups and diagrams; crop photography around its subject; avoid turning full illustrations into tiny icons. Don't force an image-count quota or use all assets for its own sake.
+
+
+## Preserve identity and supplement deliberately
+
+Record origin as customer, stock, or unknown. For a logo, founder, team, actual product, premises, project, or brand artwork, record identity and identityEvidence as a path array with captured source-page evidence, for example `"identityEvidence":["onboarding/brief.json"]`. A filename or face is not identity evidence. Existing-site images can themselves be stock or third-party logos. Keep uncertainty explicit. Every omitted identity asset needs identityDecision explaining recovery, replacement with another evidenced original, or omission; do not force unusable images into the page.
+
+Stock can illustrate a service or establish atmosphere. It cannot replace an evidenced founder, logo, real team, or completed-project proof. Never add customer assets to the shared stock library automatically. Keep original files unchanged and derived crops separate.
+
+During media, search the shared catalog using the harness script:
+
+```text
+node HARNESS/bin/vitris-stock.js search --query "electrical service" --industry trades
+node HARNESS/bin/vitris-stock.js import --site . --id ASSET_ID --reason "Illustrate the service; not our actual team" --route /
+```
+
+Use the Harness directory from CURRENT.md in place of HARNESS. Search also accepts --role and --kind. Imports validate hashes, copy local originals/posters into media/stock, and merge into the inventory. The default cache is HARNESS/artifacts/stock-library; missing files use pinned provider URLs and must match hashes. Import during the media stage. Later additions require an explicit restart from media so downstream approvals cannot silently survive changed inputs.
+
+Create onboarding/media-requests.json as {"slots":[{"id":"home-service","route":"/","purpose":"Illustrate electrical repairs","kind":"image","minWidth":1000}]} for section-specific shortlists. For slots showing the actual founder/team/logo/project, add the appropriate identity constraint. No suitable candidate is a valid result.
+
+During storyboard, write onboarding/media-selection.json with version:1 and placements containing slot, assetId, reason, and optional crop; or noMatch:true with a reason and no assetId. For storyboard version 3, add slot.placement as section, header, or footer, and add slot.sectionId for section slots. Shared slots need a row for every declared route. Bind the chosen IDs to storyboard sections or globalMedia. Account for every usable identity asset, either in placements or with an explicit identityDecision recorded during media. Repeated stock is allowed when purposeful, not to fill a quota.
+
+Jev mediaClassification, mediaSelection, mediaSetReview, and mediaProvenance are independently configurable off/shadow/assist capabilities. Read preparation-bound media-assist reports. Scores are based on supplied observations, not direct visual inspection. Missing/partial judgments never mean bad imagery. Keep all visual and identity obligations when inference is unavailable. Jev must not infer who a photographed person is.
+
+Use contain for logos and artwork; inspect photo crops at phone and desktop sizes. Videos need a local poster, muted inline playback when decorative, a static fallback under prefers-reduced-motion, and no autoplay with sound. Avoid making a video the only carrier of essential content. Inspect sampled footage and actual playback/crop before accepting a placement. Final reviews check that selection-manifest assets actually appear on their planned routes.

package/agent/refs/motif.md

@@ -0,0 +1,3 @@
+# motif
+
+Compatibility entrypoint. Workflow graph uses direction.md for this task; load it only when needed. The selected site direction governs aesthetic choices. Preserve factual accuracy, usable interactions, and accessible markup. Do not add section/image quotas or a fixed motif count.

package/agent/refs/motion-count.md

@@ -0,0 +1,13 @@
+# Verified magnitude, calm emphasis
+
+Use a count once for an important supplied statistic. Quote its source in the plan; `data-motion-fact` binds that source reference. Example below is FICTIONAL teaching: the brief supplies exactly 1,250 repaired books, not customer evidence.
+
+```html
+<p><strong id="books" data-motion="count" data-motion-kind="statistic"
+ data-motion-value="1250" data-motion-suffix=" repaired books" data-motion-fact="brief:books"
+ data-motion-duration="900">1,250 repaired books</strong></p>
+```
+
+The final string must match metadata exactly or compilation fails. Preserve qualifiers. Canonical author text remains in the accessibility tree and flow; the temporary visual number is aria-hidden, unselectable and absolutely overlaid, reserving the full final width. No aria-live. One shared frame runs only while counts are active. Focus/cancel/reduced/no JS show the exact final string immediately. Mobile can use same or `data-motion-mobile="static"`.
+
+Contraindications: phone/date/postal/model numbers, fees/prices, identifiers, uncertain claims, misleading intermediate percentages. A count is not evidence of business quality. Missing facts means omit it. Confirm accessible snapshot contains final text once during playback, stable geometry with delayed fonts, exact finish and no reversal replay. See motion-numeric.md for formatting and the count lesson for normal/static/reduced playback.

package/agent/refs/motion-image.md

@@ -0,0 +1,12 @@
+# Image followed by a quiet caption
+
+Let authentic evidence earn attention: subtle 1.015 to 1 scale, then a caption. Preserve crop, dimensions, alt text, provenance and links. Keep primary hero/LCP media still. This is a short sequence, followed by quiet reading.
+
+```html
+<figure id="detail" data-motion="sequence" data-motion-duration="650" data-motion-stagger="90" data-motion-distance="6" data-motion-mobile="static">
+ <img data-motion-child data-motion-role="image" src="/media/verified-detail.jpg" width="1000" height="600" alt="Accurately described supplied detail">
+ <figcaption data-motion-child data-motion-role="caption">Unchanged supplied caption.</figcaption>
+</figure>
+```
+
+Allow crop margin; avoid scale for edge-critical evidence. Mobile static is often clearer. No captions covering evidence, invented provenance, image swapping or animation on every gallery tile. Normal/static/reduced hold content/layout/media fixed. Watch actual crop and caption timing and keyboard focus; see image lesson.

package/agent/refs/motion-numeric.md

@@ -0,0 +1,14 @@
+# Precise and qualified formats
+
+FICTIONAL teaching facts only: a research workshop conserved approximately $12.5m of materials; supplied change was -3.25 units; recorded capacity was +1,250 units. These are display examples, not financial/customer claims. Prefix/suffix are authored literal text; numeric display may use 0–3 decimals, grouping (default true), and sign auto/always. Values are bounded to ±1e12. Exact final text is validated, never synthesized as a replacement claim.
+
+```html
+<strong id="materials" data-motion="count" data-motion-kind="statistic"
+ data-motion-value="12.5" data-motion-decimals="1" data-motion-prefix="~$"
+ data-motion-suffix="m conserved" data-motion-fact="brief:materials">~$12.5m conserved</strong>
+<strong id="change" data-motion="count" data-motion-kind="statistic"
+ data-motion-value="-3.25" data-motion-decimals="2" data-motion-suffix=" units"
+ data-motion-fact="brief:change">-3.25 units</strong>
+```
+
+An approved abbreviated numeric value is explicitly the displayed scale (12.5m), with the source fact documenting full magnitude. Use `data-motion-sign="always"` for + values, `data-motion-group="false"` where supplied formatting requires it. Percent suffix is permitted only when intermediate emphasis cannot imply a live result; usually keep rates/static financial data still. Do not localize canonical formatting silently: v1 uses en-US numeric grouping, literals supply units. Other locales remain static until authored/verified. Normal/static/reduced lessons preserve identical strings and width. No rounding beyond authored precision and no invented facts.

package/agent/refs/motion-page.md

@@ -0,0 +1,23 @@
+# Whole-page temporal composition
+
+Compose every authored route as one journey. Begin with its visitor task and the site's motion character, then locate opening, development, connections and ending in the actual content. Stillness connects active moments; it does not excuse an untouched remainder. Representative success does not cover contact, service, project, about or expansion routes.
+
+New scaffolds use `motionComposition:{version:2,routes:"all-authored"}` and the supported `scrollMotion:{version:1,policy:"enabled"}`. Historical sites omit the authoring marker. A deliberate reauthor of an existing route can select `motionComposition:{version:2,routes:["/route"]}`; other routes remain historical. Managed upgrade changes knowledge, never customer policy. Explicit operator off, OS reduced motion and no-JS/failure states remain authoritative. System-generated cookie/error/redirect pages stay static and are not omitted authored coverage. Do not call a customer contact/legal page a utility to bypass the responsibility.
+
+Extend the existing `motionPlan` to version 2, retaining its scene contract. Add `routes:[{route,task,character,normal,mobile,reduced,ending,available:["primary-message","contact-action"],beats:[{sectionId,role,change,scenes:["accent-id"],transition}]}]`. Beat IDs follow storyboard sections and actual output in document order. Roles are opening/development/closing, or whole for a genuinely single-beat short page. Every scene belongs to its real beat. Quiet beats use `scenes:[]` and `connects:["earlier-active-target","later-active-target"]`; explain the continuity. `available` identifies essential messages/actions/forms that remain immediately readable and operable. Counts also carry supplied fact references and exact final text. Never fabricate a statistic or image to fill a beat.
+
+Opening: keep identity, h1, LCP image and action visible. A secondary rule, graphic or supporting visual can introduce the character. Initially visible text/sequence entrances are deliberately static safeguards: choose an appropriate supporting draw/progress accent rather than claiming those skipped entrances run.
+
+Development: express useful evidence. Use a verified count, selected phrase, authentic image/caption, process accent or another existing primitive only when content warrants it. Relate direction, cadence or a shared accent across sections. Keep ordinary paragraphs, specifications and service/legal detail readable. Do not force a sticky story onto short content.
+
+Ending: resolve a supporting accent or brief visual sequence near the next action, with the action available throughout. Never animate form fields, move a submit button, delay labels or make a contact page artificially long. A short page can have one coherent accent across its brief opening/ending; it needs no animation quota.
+
+Positive text-led example: a visible offer with a secondary ledger rule establishes precise continuity; a later scope comparison changes emphasis; a still detail interval connects to a closing margin accent beside an immediately usable inquiry. On the service interior, use the actual ordered work/process relationship instead of repeating the homepage phrase-plus-rule pair. On contact, a small supporting accent resolves the same identity beside static fields.
+
+Positive image-led example: a quiet authentic project hero with a supporting accent; later project/caption movement clarifies a material or spatial relationship; the project list stays readable; a closing image detail or simple rule connects to the inquiry. The interior can follow project evidence at its own cadence, not duplicate the homepage arrangement.
+
+Negative examples: two effects in one section with all remaining sections called quiet; fade-up every section; adding ornaments at fixed percentages; unsupported counts; introducing empty spacer sections to meet coverage; competing large image/text motion; hiding primary headings/actions; using a static mobile treatment for every active moment. None establishes good choreography.
+
+Watch every route from first view to ending in normal desktop/mobile, then reduced/static readability. Full journey evidence must include the quiet middle at readable traversal speed, ordered section/scene positions, actual changing scene states and source/output/scenario hashes. Target checkpoints alone are insufficient. Recordings are review evidence, separate from performance runs. Concentration flags detect incompleteness, never establish aesthetic quality or a numeric motion score.
+
+Critique every route with located checkpoints: opening-to-ending contribution; distribution/connections; business-specific rhythm; competition/inert stretches; differences among routes; immediate reading/navigation/action in mobile/reduced views. Return an actionable repair for a concentrated or inert plan even when runtime tests pass. Record findings as agent assessment, with human preference unset.

package/agent/refs/motion-process.md

@@ -0,0 +1,12 @@
+# Process accent without false completion
+
+A precise decorative line introduces a documented sequence; all steps remain in flow. It describes reading order, never completed work or live analytics.
+
+```html
+<svg id="process-line" data-motion="draw" data-motion-duration="800" aria-hidden="true" viewBox="0 0 600 40" width="600" height="40" style="max-width:100%;overflow:visible">
+ <path data-motion-path d="M10 20 H590" fill="none" stroke="currentColor" stroke-width="2"/>
+</svg>
+<ol><li>Understand the brief.</li><li>Compare the evidence.</li><li>Choose the next step.</li></ol>
+```
+
+Stroke draw has measured paint cost: few simple paths only, SVG aria-hidden, no essential text in the SVG. Complete strokes remain without JS/reduced/off/failure. For scroll progress use existing progress with a separate stable trigger and reachable normalized range. Mobile can use static. Avoid busy diagrams, unsupported live state, looped arrows and scrubbed essential text. Watch before/during/after and reversal in the process lesson.

package/agent/refs/motion-sequence.md

@@ -0,0 +1,7 @@
+# Rhythm: two moments and a pause
+
+Choose relationships, not quotas. A warm workshop pairs an authentic detail and caption, leaves a paragraph still, then emphasizes one supplied statistic. A precise practice may draw one process rule and leave service detail still. An energetic performer may emphasize one phrase while booking remains immediate.
+
+Use motion-image.md sequence markup with direct data-motion-child elements; roles image/caption/text/accent express intent. Nested roots do not run twice. Total stagger delay <=300ms; complete within 1.5s. Mobile static or simpler phrase. Separate moments with ordinary quiet content instead of a giant timeline. Story uses CSS sticky beside flowing paragraphs and stacks on mobile.
+
+The composed fictional lesson combines image/caption, a still interval, a secondary phrase and decorative process rule. Counts require supplied facts, never invented effect coverage. Review recordings for competition and sufficient stillness. Contraindications: identical entrances everywhere, parallel large effects, replay on reversal, hidden primary messaging, trapped sticky reading or forced horizontal progress. Normal/static/reduced share content/layout/media. Label agent assessment separately; human preference stays unlabeled.

package/agent/refs/motion-text.md

@@ -0,0 +1,12 @@
+# A selected phrase, with room to read
+
+Warm phrasing can arrive in two beats; precise phrasing may use a brief masked accent. Keep full semantic text in initial HTML. Author one to eight spans with natural spaces and inline emphasis/links; no character splitter or forced desktop line breaks. Do not animate the primary h1, ordinary paragraphs, navigation, legal copy or essential actions.
+
+```html
+<h2 id="care" data-motion="text" data-motion-treatment="phrase" data-motion-duration="500" data-motion-stagger="80">
+ <span data-motion-word style="display:inline-block">Care for the object.</span>
+ <span data-motion-word style="display:inline-block"><em>Keep its story.</em></span>
+</h2>
+```
+
+Second treatment: `data-motion-treatment="mask"` uses a temporary clip on each authored phrase; a static underline may emphasize the selected word. Each span wraps naturally inside its parent; never set a fixed line height/mask height. No duplicated text, synthetic spaces or changed heading names. Selection/copy preserves the original message. Font completion/viewport resize finishes copy rather than recalculating fragile line splits. Focus and anchors finish immediately; an already visible heading stays still. Mobile may use static when the phrase consumes most of the screen. After <=1.5s the whole message is available with a quiet interval. Watch wrapping at 375px and 200% zoom, delayed fonts, focus inside a phrase and reverse scroll. Profile optional clipping paint cost. See phrase lesson for both treatments and normal/static/reduced controls.

package/agent/refs/motion.md

@@ -0,0 +1,11 @@
+# Deliberate scroll motion (contract v1 runtime, v2 authoring)
+
+Motion is a normal responsibility for the whole experience on every new/reauthored content route. Compose a usable opening, meaningful development, connected still intervals and a supporting closing moment. Adapt the site's motion character to each route's task. Two effects in one location do not establish a composed page. Neither do repeated fade-ups or a fixed effect count. Read [page choreography](motion-page.md) for the compact v2 plan, complete examples and review contract.
+
+New scaffolds intentionally enable `scrollMotion:{version:1,policy:"enabled"}` and declare `motionComposition:{version:2,routes:"all-authored"}`. Explicit operator off disables all effects. Historical absent policy remains legacy-only and historical plans remain readable; upgrade never silently migrates them. Reauthor a historical route through the normal prepared workflow and record its v2 responsibility. Existing legacy `motion.strength:"off"` is a component default with instance precedence; explicit new policy off overrides both. Legacy zero-child staggers animate the wrapper; marked groups animate only marked children. New empty staggers are errors.
+
+Native HTML, components and composition-v1 share stable `id` and `data-motion`: entrance, stagger, count, text, sequence, draw, drift, progress, story. Stagger/sequence use `[data-motion-child]`; semantic text uses authored `[data-motion-word]`; decorative SVG uses `[data-motion-path]`. Do not wrap pages or target nested content twice. Hero/page shells, fixed/sticky/very large targets stay static. Initially visible text/sequence entrances stay readable and static; a supporting draw accent can run in the opening. Planned active scenes must actually change during full-route traversal.
+
+Load selected recipes: [counts](motion-count.md), [formats](motion-numeric.md), [phrases](motion-text.md), [images/captions](motion-image.md), [process](motion-process.md), [rhythm](motion-sequence.md). Runtime count defaults to 900ms; other effects 550ms; bounded duration 120-1200ms, delay 0-300ms, stagger 0-120ms with total delay capped 300ms, distance 0-32px. Counts start at 35% visibility, preserve canonical accessible final text and need supplied facts. No counting phones/dates/identifiers or inventing proof. Reduced/no-JS/failure states are immediately complete. Keep primary messages, LCP content, actions, paragraphs and form fields usable throughout. No scroll hijacking, perpetual loops or replay on reversal.
+
+Watch normal desktop/mobile full journeys and reduced/static readability; keep target behavioral checks, focus/anchors/restoration/fonts/resize/teardown and factual/media/navigation/mock-form checks. Recordings stay separate from performance. Critique located whole-route rhythm and cross-route differences, not API counts. Agent assessment, measured performance and human preference are separate; human labels remain unset. Explicit off plus rebuild is the local rollback.

package/agent/refs/narrative.md

@@ -0,0 +1,9 @@
+# Shared narrative brief
+
+Write `onboarding/narrative-brief.json` schemaVersion 2 after reviewed business evidence and inspected media. This artifact is shared by every concept. It is not marketing copy and not a style direction. Include visitor questions, proof status (`strong`, `limited`, or `missing`), asset strengths and limitations, tone constraints, recorded user goals, and design opportunities. An opportunity is `evidence-backed` only with evidence ids. A `design-hypothesis` must include `uncertainty`. Do not treat a filled opportunity as proof of aesthetic merit.
+
+Identify the actual customer, the customer problem, the distinct offer, service scope, the best available proof, the primary conversion, purchase objections, and claims the source does not support. Every factual claim and proof choice must cite harvested evidence IDs or fact IDs. If a relationship is unresolved, record it as an uncertainty rather than flattening it into a slogan.
+
+Do not import the operator's future platform strategy, harness internals, or reference-site demo people, phone numbers, ratings, or awards as this customer's facts. Keep audit caveats in this operator artifact; public copy later may preserve only the qualifications that affect a purchase decision.
+
+The homepage first screen must be explainable from this brief: who this is for, what is offered, and the next step. Interior pages get their own purpose from the same facts, not a restatement of the hero.

package/agent/refs/performance.md

@@ -0,0 +1,36 @@
+# Performance
+
+Ship static HTML, the CSS of components that are used, and islands only when a page needs them. The Vitris starting budgets are project policy: 100 KiB gzip of first-party JavaScript, 100 KiB gzip of CSS, 200 KiB of fonts, and 1.5 MiB initial transfer. They are not Core Web Vitals.
+
+[Core Web Vitals](https://web.dev/articles/vitals) field targets are LCP 2.5s, INP 200ms, and CLS 0.1 at the 75th percentile. A lab run is not field INP. Missing field data is unknown, not a pass. A broken or empty shipped file still blocks.
+
+
+For scroll motion, use the stage-scoped `motion.md` contract. Choose business-specific scenes and quiet intervals; preserve operator policies. Carry motionPlan v2 for every new/reauthored route (historical v1 remains compatible) from direction/storyboard to unique native/component target IDs, then inspect before/during/after normal and reduced scrolling. Temporal claims require live observations or recordings; agent review is not human preference.
+
+## Responsive delivery and measured acceptance
+
+The standard build generates content-addressed responsive WebP derivatives for local JPEG, PNG, WebP and AVIF img sources. Originals and inventory hashes stay unchanged. Animated files, vectors, authored picture/srcset markup and data-media-optimize="off" retain their delivery. Use data-media-format="avif" for an explicitly reviewed AVIF placement. Remote URLs are never downloaded by this step. Cache files under .vitris/cache/media are disposable and never part of source evidence.
+
+Mark the route's actual above-fold image data-media-priority="critical"; the compiler emits loading="eager" and fetchpriority="high". Mark later images data-media-priority="deferred" for lazy/low priority. Native lazy loading can fetch nearby images, so all photographs still need small derivatives. Do not mark every slide critical or hide the heading until fonts/media finish. For inactive overlapping carousel slides, author source activation on selection; verify initial requests in a browser.
+
+Author sizes for the real layout, for example sizes="(min-width: 1000px) 33vw, (min-width: 650px) 50vw, 100vw" for cards. The conservative fallback is 100vw. Derivatives retain the source aspect ratio and transparency; existing CSS object-fit/object-position and reviewed crops remain authoritative. Inspect crops and text contrast on phone and desktop.
+
+New redesign sites enable launch.json performance.enabled with three runs. Final browser verification runs Lighthouse on home, the representative interior and the heaviest built interior; performance.routes adds coverage. Defaults: median mobile performance >=95, LCP <=2500ms, TBT <=200ms, CLS <=0.1 and transfer <=1.5 MiB. Reports bind source, output and launch/storyboard configuration plus hashes of raw Lighthouse JSON. Missing, failed or stale runs block completion. This is a lab gate, not field INP or a promise of a field CWV pass.
+
+Run npm run verify:performance for a standalone local check. Run npm run verify:performance -- --origin https://DEPLOYMENT for a hosted check against the existing local dist. Hosted results have a separate report and never satisfy local-build evidence. vitris deploy performs the hosted check automatically when enabled. Direct wrangler deployments require the hosted command separately.
+
+Existing sites retain their configuration: opt into performance.enabled after planning a managed kit upgrade, then fix measured failures rather than bypassing the gate. Preserve mode keeps its captured appearance and delivery; no image rewrite is silently applied there.
+
+A cover-cropped image can need more source pixels than its CSS width. Author sizes for the effective crop (or a reviewed picture source/crop); final browser checks reject undersized cover images. Do not improve transfer by accepting blurred or changed crops.
+
+Optional launch.json apiChecks entries are {"url":"/api/inquiries/config"} (or an explicit backend URL). Hosted verification performs GET-only JSON contracts and rejects HTTP-200 HTML fallbacks. This does not establish draft saving, submission or email delivery.
+
+For real-user CWV, enable Cloudflare Web Analytics for the site and configure its public webAnalyticsToken in launch.json when manual injection is needed. It is omitted from preview builds. Avoid duplicate dashboard/manual beacon injection. Inspect route/device LCP, INP and CLS in Web Analytics; absent or insufficient visitor data stays unknown. This hook does not provision an account resource or invent field measurements.
+
+The standard build also writes a genuine 404, a working fallback favicon when no icon is authored, absolute sitemap discovery when publicOrigin is configured, consistent trailing-slash links/canonicals, route CSS/islands, separated embedded WOFF fonts, and immutable content-addressed assets. TTF-to-WOFF2 conversion/subsetting and custom SVG simplification remain explicit media authoring tasks; preserve source licenses and map interactions. Configure a reviewed production origin before launch. Review deployments intentionally remain noindex.
+
+For before/after comparisons, pin the same browser executable with CHROME_PATH, record the Lighthouse/browser versions from every raw report, and run serially after other browser work finishes. Preserve failures from other browser versions as diagnostics; never selectively replace valid low samples or relax budgets to finish.
+
+Initialize noncritical footer clocks and expensive Intl formatters when they become visible, cache formatter instances, and stop timers while hidden. Verify real startup tasks and live measurements; fast image delivery does not compensate for blocking JavaScript. For a text LCP, inspect font discovery and preload the exact critical extracted font with matching type/crossorigin settings; preserve the component root and verify a single font request.
+
+Lighthouse gates launch a fresh Chrome profile directly through chrome-launcher, using a single browser controller. Do not attach a Playwright controller to the same measured browser: target/debugger coordination can contaminate main-thread timings. Use Playwright separately for screenshots and interaction checks.

package/agent/refs/preview.md

@@ -0,0 +1,3 @@
+# preview
+
+Compatibility entrypoint. Workflow graph uses browser.md for this task; load it only when needed. The selected site direction governs aesthetic choices. Preserve factual accuracy, usable interactions, and accessible markup. Do not add section/image quotas or a fixed motif count.

package/agent/refs/production-quality.md

@@ -0,0 +1,33 @@
+# Source and realization contract v1 (explicit launch opt-in)
+
+Only active when `launch.json.productionQuality` is `source-and-realization-v1`. Keep all ordinary prepare/work/complete gates. No authoring-mode default changes.
+
+## Business and content
+
+At business, enumerate important captured facts and individual services in `onboarding/content-requirements.json`: `{version:1,sourceHash,operatorHash,items:[{id,disposition:"required",factIds:["supported-business-fact-id"],equivalents:["faithful display wording"],equivalenceReason:"why equivalent"}]}`. Hashes use artifacts.fingerprint(root, CONTENT_SOURCE) and contentOperatorHash(root) from production-quality.ts. Every approved fact needs a disposition; multiple atomic services can share a group but each must have its own entry. Enumerate source requirements before compressing the offer. Compare the source with the ledger during business-review.
+
+Keep independently important fields atomic, including a person's name, phone and street address. A compound business fact can support several required ledger entries with the same fact ID, so faithful grouped fields can change order or occupy separate lines without requiring the original sentence. Each field still needs its own coverage match. `equivalents` are alternatives for one item, not a list of different fields that may substitute for each other. Record the actual faithful wording; never replace a complete contact requirement with a name-only alias. If an accepted compound requirement needs this decomposition, reopen business through the supported factual revision rather than forcing pages to copy the harvested sentence.
+
+Optional immutable operator input (also accepted in the pinned launch.json `contentRequirements` field) `agent/content-requirements.json`: `{version:1,requirements:[{id,claim,source:"onboarding/raw/...",excerpt:"captured source excerpt",equivalents:["approved faithful alternative"],allowExclusion:false}]}`. Include every supplied ID in the business ledger and its supported business fact; never delete one to pass a gate. Operator aliases take priority over agent aliases. For a legitimate outdated/excluded source item use `disposition:"excluded",factIds:[...],exclusion:{reason:"specific justification",evidence:"specific source/operator evidence"}`. Operator-required items cannot be excluded without permission recorded in the input. This ledger requires source review; it does not claim automatic semantic enumeration of every harvested sentence.
+
+Copy expansion checks each required item's wording AND fact IDs in an individual copy section. Faithful paraphrases are accepted through recorded alternatives; generic category labels do not replace an individual service. The final browser tool saves visible text per route/width. At content-review compute `coverageAudit(root)` from production-quality.ts and save its exact result to `agent/reviews/content-coverage.json`. The evaluator recomputes it, rejects omissions and stale evidence. An unchanged route list cannot establish coverage. Fix copy/page omissions through the normal owner; justified changes to requirements reopen business.
+
+## Media ownership
+
+Inspect all used customer assets during media. Each needs actual sha256, structured `inspection:{assetHash,description,evidence:[existing-paths],...}`, dimensions and supported identity. Use actual viewed pixels; never invent inspection metadata. Preserve these accepted rows at asset-production. If an older audit lacks inspection metadata, use the supported media revision operation with `kind:"inspection"` to reopen media and dependents BEFORE changing it. Never edit STATE or restore old receipts to recover.
+
+## Direction through rendering
+
+Browser reports and their screenshots belong to the scheduled browser tool nodes. During representative/pages authoring, build into the absolute SITE/dist path and inspect the live preview. If manual diagnostic captures are needed, keep them in a clearly scoped temporary directory outside the protected site tree; they do not replace the runner's evidence. Complete the authoring preparation so the runner can execute its browser node, then inspect its current screenshots at the critic stage. Do not run verify-browser early or create agent/reviews/browser.json, agent/reviews/representative-browser.json or their screenshot directories during an authoring preparation.
+
+At direction add `realizationContract:{version:1,axes:[{axis,intention,observable,decisionIds:[existing-decision-id]}]}` for all nine axes: opening, navigation, typography, imagery, density, proof, interior, mobile, actions. Describe concrete relationships and customer constraints. Specify what type does, how imagery relates to facts, proportions/pacing, how evidence/work can be explored, and important action behavior. An appropriate image-free solution is valid. Do not force a palette, page skeleton or novelty.
+
+At storyboard add `realizationMap:[{axis,routes:["/",...],implementation:"specific sections/global relationships carrying this intent"}]` for all axes. Carry these accepted decisions into representative and expanded pages. Authors may record justified deviations at those stages in `onboarding/direction-deviations.json`: `{version:1,deviations:[{id,axis,reason,preservedConstraints}]}`. Explain actual tradeoffs rather than silently erasing the direction.
+
+At representative-review and visual-review, inspect the CURRENT rendered screenshots. Add `directionFidelity:{subjectHash,observations:[{axis,width:375|1080,screenshot:"current browser PNG path",sha256:"raw image hash",observed:"concrete pixels/geometry/content",relationship:"how these implement the accepted intent",verdict:"survived"|"justified-deviation",deviationId:"when needed"}]}` to the ordinary review. Cover all axes at both widths, including a substantive interior. subjectHash uses fingerprint of direction.json, storyboard.json, direction-deviations.json and the relevant browser report. A screenshot path alone is insufficient; record what it shows. A failed relationship needs ordinary findings and repair, not a fabricated pass. Byte checks bind evidence; they do not prove design quality or human preference. At expansion and final review compare the actual relationships against the accepted direction again.
+
+## Active-agent quality completion
+
+At representative-quality, when you are the active visual reviewer, actually open the current capability probe and every current representative PNG with an approved image tool. Record the real successful calls in a JSON array outside the protected site tree: `[{"tool":"view_image","path":"actual image path","success":true,"hash":"actual raw PNG SHA256"}]`. Each entry must describe an image call you actually performed; computing hashes or listing files is not inspection. Use the observed probe color, never read its answer from implementation metadata. Read current capture paths/hashes through the supported design-quality exports if needed; those lists do not substitute for opening pixels.
+
+Pass the absolute event-file path to the ordinary completion command: `vitris-go --site ABSOLUTE_SITE --complete --preparation CURRENT_ID --visual-tool-events ABSOLUTE_EVENTS_JSON --no-preview-server`. The completion runner records the active-agent-visual receipt bound to the preparation, probe and captures. Do not hand-write the receipt or claim an external adapter invocation. The events are self-recorded observations, not an exported host transcript, independently verified tool-call log or human review. Never invent successful events, dataBlobIds, old session identifiers or usage. Missing events/current hashes/preparation bindings and unavailable pixels still fail; configured external adapters retain their supported provenance path. A quality failure consumes its preparation; resume for a new one through the ordinary owner and budget.

package/agent/refs/psychology.md

@@ -0,0 +1,3 @@
+# psychology
+
+Compatibility entrypoint. Workflow graph uses direction.md for this task; load it only when needed. The selected site direction governs aesthetic choices. Preserve factual accuracy, usable interactions, and accessible markup. Do not add section/image quotas or a fixed motif count.

package/agent/refs/refine.md

@@ -0,0 +1,14 @@
+# Later-life refinement
+
+For an opted-in reference release, retain the accepted reference relationships and current direction identity unless the classified change request explicitly revises them. Inspect relevant integrity-bound working-set expansions only as needed. Evaluate repaired production pixels against customer facts, the accepted identity and existing functional gates; do not reopen all catalog discovery or transfer fictional teaching content.
+
+Use this skill only when `agent/change-request.json` is present. Do not restart harvest. Load site memory and the classified slice, not the full onboarding kit.
+
+Keep `originalRequest` verbatim. Expand `proposedChanges` into concrete, file-level edits before changing source. Write `implementationReason`, and record likes, dislikes, and preserve items at website, page, section, or element grain (`path`, `sectionId`, `hook` when known).
+
+Honor current memory decisions. Treat `superseded` items as historical experiments. Do not invent business facts or drop original media IDs. If layout and navigation hashes are unchanged after a copy edit, do not rewrite pages for their own sake; content review still applies.
+
+After the edit, the runner writes `agent/refine-report.json` and updates `agent/site-memory.json`. Do not mark STATE passed by hand.
+
+
+Whole-page motion responsibility: for new/reauthored routes use motionPlan v2 and read `motion-page`. Cover every authored route, including expansion/contact; locate opening, development, connected quiet intervals and closing in actual IDs. Keep essential content/actions static and readable. Representative runtime success or two colocated effects is insufficient. Inspect normal desktop/mobile full journeys and reduced/static views; critique distribution, continuity, inert stretches, competition and meaningful differences among routes with located evidence. Return actionable repairs, preserving operator off and historical records. Human preference stays unset.