@ztothez/design-engineering 2.0.0

package/knowledge-base/benchmarks/scenestart/product-contract.yaml

@@ -0,0 +1,427 @@
+version: "1.1"
+id: scenestart
+name: SceneStart Local-First Demoscene Learning Studio
+status: benchmark
+purpose: >-
+  Help a complete beginner or independent maker learn demoscene concepts through direct
+  experimentation, compose a coherent timed production, preserve editable work locally,
+  export a self-contained offline artifact, and document release provenance without
+  implying certification, rights ownership, or competition eligibility.
+
+authority:
+  behavior: Current SceneStart behavior summarized in SOURCE-EVIDENCE.md overrides historical product plans and visual mockups.
+  visual: Current SceneStart components and tokens guide identity, but task completion, readable state, and responsive accessibility override fixed compositions.
+  precedence:
+    - path: SOURCE-EVIDENCE.md
+      role: Current implementation snapshot, behavior boundaries, and source hashes.
+      authority: primary
+    - path: MANIFEST.md
+      role: Benchmark scope, authority order, and clean-room usage rules.
+      authority: supporting
+    - path: ../../../clean-room-ux-design-spec.md
+      role: Independent implementation, provenance, local-first, and abstention requirements.
+      authority: supporting
+
+actors:
+  - id: beginner-maker
+    name: Beginner demoscene maker
+    goals:
+      - See a meaningful visual result before specialist setup becomes a barrier.
+      - Understand how parameter changes affect motion, rhythm, depth, and composition.
+      - Finish and keep a working production that can be replayed offline.
+    responsibilities:
+      - Choose a handle and creative direction without treating starter content as proof of originality.
+      - Preview and review the complete sequence before export.
+      - Preserve downloaded project and production files on their own device.
+  - id: independent-producer
+    name: Independent producer
+    goals:
+      - Compose, reorder, preview, save, reopen, and export a multi-scene production.
+      - Document contributors, tools, external assets, licences, and run instructions.
+      - Distinguish technical readiness from event-specific and rights review.
+    responsibilities:
+      - Resolve external-asset rights and required credits before release.
+      - Test the exported artifact in the intended environment.
+      - Check current event rules independently.
+  - id: workshop-facilitator
+    name: Workshop facilitator
+    goals:
+      - Guide beginners through a bounded first-success path without accounts or cloud setup.
+      - Observe where learners require assistance and whether concepts transfer.
+      - Hand each learner an editable and playable artifact they control.
+    responsibilities:
+      - Avoid presenting estimated completion time as a countdown or guarantee.
+      - Record representative-user evidence only with participant consent.
+      - Separate observed task outcomes from product analytics or fabricated success claims.
+
+outputs:
+  - id: editable-project
+    name: Editable SceneStart project
+    sourceOfTruth: Sanitized version 2 production project with shared identity, palette, and one to eight ordered scenes.
+    requiredEvidence:
+      - Versioned JSON schema and filename
+      - Scene order, effect, message, duration, transition, cue, and parameters
+      - Successful parse or actionable rejection
+  - id: offline-production
+    name: Self-contained browser production
+    sourceOfTruth: HTML generated directly from the current sanitized production project.
+    requiredEvidence:
+      - Current handle, palette, ordered scenes, durations, transitions, and effect parameters
+      - Inline playback implementation with start and Escape behavior
+      - No runtime network dependencies
+  - id: local-progress
+    name: Local learning progress
+    sourceOfTruth: Versioned browser storage owned by the applicable workshop or learning path.
+    requiredEvidence:
+      - Completed step, lesson, mission, or requirement identifiers
+      - Coercion against the current registry
+      - Visible progress derived from stored state
+  - id: provenance-ledger
+    name: Release provenance ledger
+    sourceOfTruth: Current local release state containing assets, creators, sources, licences, modifications, credits, and rights decisions.
+    requiredEvidence:
+      - Unresolved entries remain visibly unresolved
+      - Rights confirmation is explicit and user-controlled
+      - No certification claim is inferred from completion
+  - id: release-readme
+    name: Plain-text release readme
+    sourceOfTruth: Deterministic text generated from the current release state and local handle.
+    requiredEvidence:
+      - Run instructions, target, requirements, contributors, tools, assets, credits, and AI-use disclosure
+      - Unresolved rights remain marked
+      - SceneStart non-certification disclaimer
+
+modes:
+  - id: studio-production
+    name: Demo Studio
+    purpose: Compose and export a complete timed production with direct control over scenes and shared project identity.
+    input: Local production fields or a valid version 2 SceneStart JSON project under 64 KB.
+    outputs: [editable-project, offline-production]
+  - id: guided-workshop
+    name: Guided Workshop
+    purpose: Complete a six-step opening, build, ending workflow and continue with the same project in Studio.
+    input: A valid two-to-eight-character handle and guided parameter decisions.
+    outputs: [editable-project, offline-production, local-progress]
+  - id: learning-path
+    name: Learning Paths
+    purpose: Complete bounded concepts and hands-on activities while preserving progress on the current device.
+    input: A selected goal, role, lesson, or activity response.
+    outputs: [local-progress]
+  - id: release-preparation
+    name: Release, Rights and Community
+    purpose: Document provenance and technical release information without replacing legal, authorship, or event review.
+    input: Local contributor, asset, licence, disclosure, run, and checklist information.
+    outputs: [provenance-ledger, release-readme, local-progress]
+
+stateMachines:
+  - id: production-authoring
+    initial: loaded
+    states:
+      - id: loaded
+        category: idle
+        userVisible: true
+        requirement: A valid local default, migrated project, or imported project is visible and editable.
+      - id: editing
+        category: idle
+        userVisible: true
+        requirement: Every change updates the current project and preview without disconnecting scene identity or timeline order.
+      - id: previewing
+        category: loading
+        userVisible: true
+        requirement: Playback exposes current scene and elapsed time and remains stoppable without losing edits.
+      - id: export-ready
+        category: success
+        userVisible: true
+        requirement: At least three valid scenes exist and both editable-project and offline-production actions are available.
+      - id: exported
+        category: terminal
+        userVisible: true
+        requirement: The downloaded filename and content derive from the current project without mutating it.
+      - id: invalid-project
+        category: error
+        userVisible: true
+        requirement: Invalid, unsupported, unreadable, or oversized files produce an actionable message and preserve the current project.
+    transitions:
+      - from: loaded
+        to: editing
+        trigger: Change a project or scene field
+      - from: editing
+        to: previewing
+        trigger: Start production playback
+      - from: previewing
+        to: editing
+        trigger: Pause, restart, finish, or stop playback
+      - from: editing
+        to: export-ready
+        trigger: Project contains at least three valid scenes
+      - from: export-ready
+        to: exported
+        trigger: Save project or export offline HTML
+      - from: loaded
+        to: invalid-project
+        trigger: Open an invalid or unsupported project file
+      - from: invalid-project
+        to: editing
+        trigger: Continue editing the preserved project
+  - id: guided-progression
+    initial: not-started
+    states:
+      - id: not-started
+        category: idle
+        userVisible: true
+        requirement: The first task and six-step scope are visible without a countdown.
+      - id: in-progress
+        category: loading
+        userVisible: true
+        requirement: Current, completed, and remaining steps are distinguishable and the project is saved locally.
+      - id: workshop-complete
+        category: success
+        userVisible: true
+        requirement: Export and Continue in Demo Studio actions use the completed workshop project.
+      - id: storage-unavailable
+        category: fallback
+        userVisible: true
+        requirement: The workshop remains usable for the current session and does not claim progress was saved.
+    transitions:
+      - from: not-started
+        to: in-progress
+        trigger: Enter a valid handle and continue
+      - from: in-progress
+        to: workshop-complete
+        trigger: Finish the watch-the-whole-arc step
+      - from: not-started
+        to: storage-unavailable
+        trigger: Browser storage is unavailable
+      - from: in-progress
+        to: storage-unavailable
+        trigger: Persisting workshop state fails
+  - id: release-documentation
+    initial: draft
+    states:
+      - id: draft
+        category: idle
+        userVisible: true
+        requirement: Release fields, checklist state, and provenance entries remain editable locally.
+      - id: rights-unresolved
+        category: error
+        userVisible: true
+        requirement: Incomplete asset provenance is counted and explained without blocking continued documentation.
+      - id: documented
+        category: success
+        userVisible: true
+        requirement: The readme reflects current data while retaining the non-certification disclaimer.
+    transitions:
+      - from: draft
+        to: rights-unresolved
+        trigger: Add an incomplete or unconfirmed external asset
+      - from: rights-unresolved
+        to: documented
+        trigger: Complete provenance and explicitly confirm rights
+      - from: draft
+        to: documented
+        trigger: Generate readme with no external assets
+
+metrics:
+  - id: scene-count
+    name: Production scene count
+    definition: Number of sanitized ordered scenes in the current editable production.
+    sourceOfTruth: Current version 2 project scenes array.
+    format: count
+    evidenceRequired: true
+    range: { min: 1, max: 8 }
+  - id: production-duration
+    name: Production duration
+    definition: Sum of current sanitized scene durations, not a separately entered estimate.
+    sourceOfTruth: Current project scene durationMs values.
+    format: duration
+    evidenceRequired: true
+    range: { min: 2, max: 480 }
+  - id: learning-progress
+    name: Learning path progress
+    definition: Completed requirements divided by the current path registry total.
+    sourceOfTruth: Coerced versioned local progress and current lesson or requirement registry.
+    format: percentage
+    evidenceRequired: true
+    range: { min: 0, max: 100 }
+  - id: release-checklist-count
+    name: Release checklist completion
+    definition: Number of current release checklist items explicitly checked by the producer.
+    sourceOfTruth: Current local release checklist record.
+    format: count
+    evidenceRequired: true
+    range: { min: 0, max: 9 }
+
+constraints:
+  outOfScope:
+    - Certifying competition eligibility, originality, authorship, rights ownership, or event acceptance.
+    - Replacing specialist trackers, graphics tools, video editors, game engines, or hardware testing.
+    - Accounts, social feeds, cloud project storage, marketplace features, or public engagement statistics.
+    - Automatic publication or submission of exported work.
+  prohibitedClaims:
+    - Assembly-ready, competition-compliant, rights-cleared, original, or certified without independent current review.
+    - Representative-user success, completion time, or learning effectiveness without consented study evidence.
+    - Offline public application operation when only downloaded production artifacts are guaranteed offline.
+    - Community scale, popularity, creator counts, or completion statistics without a current source of truth.
+  mockData:
+    allowedEnvironments: [development, test, demo]
+    mustBeLabeled: true
+    prohibitedInProduction: true
+    fallbackDisclosure: Starter projects, preset effects, example copy, and tutorial state must remain labeled as editable starting material and never be presented as user authorship, rights evidence, or competition readiness.
+
+acceptanceCriteria:
+  - id: project-state-integrity
+    title: Project state remains coherent and recoverable
+    severity: blocker
+    requirement: Identity, palette, scene order, timing, transitions, messages, cues, and effect parameters share one sanitized project source of truth; invalid imports preserve the current work and explain the rejection.
+    evidence: [contract, runtime]
+    appliesToModes: [studio-production, guided-workshop]
+  - id: offline-export-integrity
+    title: Export matches the current production and runs offline
+    severity: blocker
+    requirement: The downloaded production contains the current sanitized project, meaningful filename, start and Escape controls, deterministic renderers, and no playback-time network dependency.
+    evidence: [contract, runtime, export]
+    appliesToModes: [studio-production, guided-workshop]
+  - id: editable-project-integrity
+    title: Editable project download preserves current work
+    severity: blocker
+    requirement: Saving the project downloads a versioned, size-bounded JSON recipe representing the current production without uploading or mutating it.
+    evidence: [contract, runtime, export]
+    appliesToModes: [studio-production]
+  - id: guided-task-continuity
+    title: Guided workshop produces a transferable project
+    severity: blocker
+    requirement: The six-step route shows current progress, never imposes a countdown, and transfers the same completed project into Studio or offline export.
+    evidence: [runtime, screenshot]
+    appliesToModes: [guided-workshop]
+  - id: learning-progress-persistence
+    title: Learning progress is local, derived, and durable
+    severity: blocker
+    requirement: Completing a lesson updates versioned device-local state, survives navigation, and is recomputed against the current registry instead of duplicated as presentation-only progress.
+    evidence: [contract, runtime]
+    appliesToModes: [learning-path]
+  - id: provenance-workflow-integrity
+    title: Release provenance remains explicit
+    severity: blocker
+    requirement: Incomplete external-asset records remain unresolved until asset, creator, licence, and explicit rights confirmation exist; generated readme output preserves unresolved status and disclosure fields.
+    evidence: [contract, runtime, export]
+    appliesToModes: [release-preparation]
+  - id: honest-product-scope
+    title: Product scope and non-certification are explicit
+    severity: blocker
+    requirement: SceneStart distinguishes technical preparation from legal, originality, authorship, and event review and does not turn checklist completion into certification.
+    evidence: [contract, runtime]
+    appliesToModes: [studio-production, guided-workshop, learning-path, release-preparation]
+  - id: local-first-boundary
+    title: Creative state remains local to the user
+    severity: blocker
+    requirement: Project content, learning progress, workshop state, and provenance data are not sent to an application backend; hosting operations and optional external links are disclosed separately.
+    evidence: [contract, manual-review]
+    appliesToModes: [studio-production, guided-workshop, learning-path, release-preparation]
+  - id: responsive-integrity
+    title: Creation and learning tasks reflow without loss
+    severity: blocker
+    requirement: At 320, 390, 768, 1024, and 1440 CSS pixels, controls, timeline state, preview, progress, provenance fields, and download actions remain readable, operable, and free from page-level horizontal overflow.
+    evidence: [runtime, screenshot]
+    appliesToModes: [studio-production, guided-workshop, learning-path, release-preparation]
+  - id: accessible-operation
+    title: Critical workflows are keyboard and assistive-technology operable
+    severity: blocker
+    requirement: Inputs and controls have accessible names, focus remains visible and unobscured, progress and errors are announced, touch targets remain operable, status is not color-only, and authoring motion respects reduced-motion preferences.
+    evidence: [runtime, accessibility]
+    appliesToModes: [studio-production, guided-workshop, learning-path, release-preparation]
+
+verification:
+  journeyFile: journeys.json
+  viewports:
+    - { name: mobile-320, width: 320, height: 800 }
+    - { name: mobile-390, width: 390, height: 844 }
+    - { name: tablet-768, width: 768, height: 1024 }
+    - { name: desktop-1024, width: 1024, height: 768 }
+    - { name: wide-1440, width: 1440, height: 900 }
+  bindings:
+    - profile: studio-export
+      journey: compose-save-export
+      actor: independent-producer
+      mode: studio-production
+      acceptanceCriteria: [project-state-integrity, offline-export-integrity, editable-project-integrity, honest-product-scope, responsive-integrity, accessible-operation]
+    - profile: guided-workshop
+      journey: complete-guided-production
+      actor: beginner-maker
+      mode: guided-workshop
+      acceptanceCriteria: [project-state-integrity, offline-export-integrity, guided-task-continuity, honest-product-scope, responsive-integrity, accessible-operation]
+    - profile: learning-persistence
+      journey: complete-and-resume-lesson
+      actor: beginner-maker
+      mode: learning-path
+      acceptanceCriteria: [learning-progress-persistence, honest-product-scope, responsive-integrity, accessible-operation]
+    - profile: release-provenance
+      journey: document-asset-and-readme
+      actor: independent-producer
+      mode: release-preparation
+      acceptanceCriteria: [provenance-workflow-integrity, honest-product-scope, local-first-boundary, responsive-integrity, accessible-operation]
+
+benchmark:
+  archetype: full-stack-workflow
+  interface: browser
+  qualityDimensions:
+    - { id: truthful-disclosure, status: required, reason: "Local-first storage, exports, and asset rights require explicit boundaries." }
+    - { id: information-design, status: required, reason: "Creators must understand progression, project state, release readiness, and next actions." }
+    - { id: visual-system, status: required, reason: "Workshop, Studio, learning, and release surfaces require coherent hierarchy." }
+    - { id: accessibility, status: required, reason: "Authoring and learning workflows require keyboard, reflow, and non-color operation." }
+    - { id: responsive-structure, status: required, reason: "Core workflows are verified from 320px mobile through wide desktop." }
+    - { id: state-integrity, status: required, reason: "Workshop handoff, saved project state, learning progress, and exports must persist." }
+    - { id: maintainability, status: required, reason: "Learning, authoring, storage, export, and provenance concerns require stable boundaries." }
+  tasks:
+    - id: workshop-to-studio
+      primary: true
+      actor: beginner-maker
+      mode: guided-workshop
+      intent: Complete the guided production workflow and continue into Studio with the project handle and scenes intact.
+      start:
+        stateMachine: guided-progression
+        state: not-started
+        observable: The learner can begin a new guided project from Workshop.
+      success:
+        stateMachine: guided-progression
+        state: workshop-complete
+        observable: Workshop is complete and the same project opens in Studio with its creative state preserved.
+        evidence: [contract, runtime, manual-review]
+      recovery:
+        required: true
+        failure:
+          stateMachine: guided-progression
+          state: storage-unavailable
+          observable: Local storage failure is disclosed without claiming successful persistence.
+        observable: The learner can retain the current in-memory project, retry storage, or export before leaving.
+      journey: { profile: guided-workshop, journey: complete-guided-production }
+      browser: { route: /workshop, narrowViewport: mobile-320 }
+    - id: export-offline-production
+      primary: true
+      actor: independent-producer
+      mode: studio-production
+      intent: Save an editable project and export a working offline HTML production without uploading creative data.
+      start:
+        stateMachine: production-authoring
+        state: loaded
+        observable: A local project is loaded in Studio and available for editing.
+      success:
+        stateMachine: production-authoring
+        state: exported
+        observable: Editable project data and offline HTML are downloaded with the expected project content.
+        evidence: [contract, runtime, export, manual-review]
+      recovery:
+        required: true
+        failure:
+          stateMachine: production-authoring
+          state: invalid-project
+          observable: Invalid imported project data is rejected with a visible explanation.
+        observable: The producer can return to the intact current project or import a corrected local file.
+      journey: { profile: studio-export, journey: compose-save-export }
+      browser: { route: /studio, narrowViewport: mobile-320 }
+  evidencePolicy:
+    missingEvidence: unverified
+    failedBehavior: failed
+    unsupportedCapability: limitation
+  comparison:
+    taskContractId: scenestart-production-continuity
+    crossContractRanking: false

package/knowledge-base/dependencies.yaml

@@ -0,0 +1,69 @@
+version: "1.0"
+lockfile: package-lock.json
+policy:
+  strategicCapabilitiesMustRemainProjectOwned: true
+  allowedLicenses: [MIT, ISC, Apache-2.0, BSD-2-Clause, BSD-3-Clause]
+dependencies:
+  - name: "@modelcontextprotocol/sdk"
+    scope: runtime
+    versionRange: "^1.30.0"
+    resolvedVersion: "1.30.0"
+    license: MIT
+    role: replaceable-infrastructure
+    boundary: MCP server registration, transports, and protocol client tests.
+    fallback: CLI validators and quality-gate commands remain usable without an MCP host.
+    replacementTrigger: Protocol incompatibility, unacceptable license change, or unmaintained security risk.
+  - name: playwright-core
+    scope: runtime
+    versionRange: "^1.62.1"
+    resolvedVersion: "1.62.1"
+    license: Apache-2.0
+    role: replaceable-infrastructure
+    boundary: Browser launch, page automation, screenshots, and rendered evidence capture.
+    fallback: Static architecture audit, contract validation, and explicit runtime-unavailable reporting.
+    replacementTrigger: Unsupported target browsers, unacceptable installation cost, or unresolved security risk.
+  - name: typescript
+    scope: runtime
+    versionRange: "^5.9.3"
+    resolvedVersion: "5.9.3"
+    license: Apache-2.0
+    role: replaceable-infrastructure
+    boundary: Source parsing for deterministic audits and project compilation.
+    fallback: Contract, retrieval, heuristic, and manifest validators do not depend on compiler execution.
+    replacementTrigger: Parser incompatibility with supported source syntax or unacceptable license change.
+  - name: yaml
+    scope: runtime
+    versionRange: "^2.9.0"
+    resolvedVersion: "2.9.0"
+    license: ISC
+    role: replaceable-infrastructure
+    boundary: Parsing versioned local contracts, manifests, reviews, provenance, and dependency inventories.
+    fallback: Every executable contract accepts JSON where its public schema permits it.
+    replacementTrigger: Security issue, specification incompatibility, or unacceptable license change.
+  - name: zod
+    scope: runtime
+    versionRange: "^4.4.3"
+    resolvedVersion: "4.4.3"
+    license: MIT
+    role: replaceable-infrastructure
+    boundary: Runtime validation and MCP structured-output schemas.
+    fallback: Portable JSON Schemas preserve public artifact contracts for independent validators.
+    replacementTrigger: Runtime incompatibility, unacceptable bundle cost, or license change.
+  - name: "@types/node"
+    scope: development
+    versionRange: "^26.3.0"
+    resolvedVersion: "26.3.0"
+    license: MIT
+    role: replaceable-infrastructure
+    boundary: Compile-time Node.js API declarations only.
+    fallback: Pin a compatible declarations release or maintain minimal local declarations temporarily.
+    replacementTrigger: Node.js support mismatch or incompatible declaration changes.
+  - name: tsx
+    scope: development
+    versionRange: "^4.23.12"
+    resolvedVersion: "4.23.12"
+    license: MIT
+    role: replaceable-infrastructure
+    boundary: Development-only execution of the audit CLI before compilation.
+    fallback: Build with TypeScript and run the compiled JavaScript CLI.
+    replacementTrigger: Node.js incompatibility, security risk, or unacceptable license change.

package/knowledge-base/design-intelligence/MASTER.md

@@ -0,0 +1,87 @@
+# Design Intelligence Router
+
+Use this maintained module set when a request needs product intake, interface trust, operational information design, visual polish, brand identity, Figma libraries, generated or sourced assets, icon systems, presentations, licensing records, or visual-accessibility review. Keep the root `SKILL.md` authoritative and load only the modules required by the deliverables.
+
+## Required Workflow
+
+For an interface system, use this order and record every stage in `design-deliverable.yaml`:
+
+1. Validate the product evidence and generation boundary from `product-design-brief.template.yaml`.
+2. Compile the brief with `compile_design_plan`, then resolve provisional contract decisions and
+   preserve route mapping for the target adapter.
+3. Validate the product task and product contract.
+4. Create and validate the truth and data-source contract from `interface-trust.template.yaml`.
+5. Create and validate the information architecture from `information-design.template.yaml`.
+6. Declare the interaction and state model.
+7. Declare the visual direction using `visual-polish.md`.
+8. Build primitive, semantic, and component token layers.
+9. When the recompiled plan is implementation-ready and a new independent React fixture is
+   appropriate, read `generation-adapter.md` and run only the contained CLI adapter.
+10. Implement the smallest coherent task path manually when no qualified adapter applies.
+11. When a product contract needs task progress, recovery, keyboard, export, or offline evidence,
+    read `interaction-recovery-verification.md` and declare only applicable executable states.
+12. Attach deterministic automated verification evidence, including every maintained viewport and
+    implemented color scheme for instrumented composition.
+13. When a generated fixture has a supported architecture or runtime finding, read
+    `closed-loop-repair.md` and use the bounded CLI workflow. Stop and restore on repeated failure.
+14. Request attributable human visual review of rendered output. Automated repair evidence cannot
+    satisfy a human obligation.
+
+Before this sequence, inspect the existing brand, tokens, components, assets, rights records, and implementation stack. Preserve coherent systems unless redesign is requested. During it, route to the smallest relevant modules, record rights evidence for every distributable asset, and keep unresolved assets out of production output. A declaration validator cannot prove pixels, runtime behavior, legal clearance, usability, or human validation.
+
+## Module Routing
+
+| Deliverable | Read |
+|---|---|
+| New product, consequential redesign, audience, task, data, assumptions, or generation readiness | `product-design-brief.md` |
+| Deterministic planning, route proposals, component and state ownership, contract readiness, or verification obligations | `design-plan.md` |
+| Contained generation of a new independent React and TypeScript fixture from an implementation-ready plan | `generation-adapter.md` |
+| Finding-bound repair of a generated React fixture with before and after evidence | `closed-loop-repair.md` |
+| Executable task progress, recovery, keyboard, export, or offline verification | `interaction-recovery-verification.md` |
+| Operational state, external data, generated results, fallback, history, or export provenance | `interface-trust.md` |
+| Operational metrics, findings, charts, hierarchy, long labels, or large collections | `information-design.md` |
+| Visual direction, typography, composition, density, states, motion, charts, or rendered visual review | `visual-polish.md` |
+| Brand identity, logo family, voice, or visual direction | `brand-systems.md` |
+| Figma variables, modes, components, libraries, or handoff | `figma-production.md` |
+| Generated images, illustrations, photos, textures, charts, audio, or video | `asset-generation.md` |
+| Product icons or a custom icon family | `iconography.md` |
+| Presentation deck, report slides, or reusable masters | `presentation-design.md` |
+| Any third-party, generated, commissioned, or user-provided asset | `licensing-and-provenance.md` |
+| Color, contrast, non-color cues, alternatives, or export accessibility | `visual-accessibility.md` |
+
+## Evidence Boundary
+
+The design-deliverable manifest is a structured claim with evidence references. Passing validation means the declaration is internally consistent and its recorded token math meets the implemented checks. It does not mean:
+
+- Every screen or exported asset uses the declared tokens.
+- A Figma file contains the declared pages, variables, properties, or states.
+- A rights basis is legally sufficient in every jurisdiction or channel.
+- Generated media is free of confusing similarity or third-party claims.
+- Rendered contrast, reading order, alternative text, or interaction behavior passes review.
+
+Use source inspection, Figma inspection, export inspection, browser verification, and qualified human review to close those evidence gaps.
+
+The product design brief proves that generation inputs are internally consistent, source-traceable,
+and acceptance-covered. It does not prove product desirability, implementation correctness, or
+release readiness.
+
+The interface-trust contract has the same boundary. Passing validation proves internal source and disclosure consistency, not that the rendered interface displays the declarations or that an external service is available.
+
+The information-design contract proves declaration structure and decision traceability only. It does not prove correct calculations, rendered hierarchy, responsive behavior, or representative-user comprehension.
+
+The visual-polish report separates structural pass, verified rendered evidence, attributable human review, and release readiness. Planned screenshots and agent-authored critique never satisfy the latter two gates.
+
+The integrated design report also separates generation readiness, contract validation, automated verification, and human review. `passed` means the manifest is internally consistent; only `integration.releaseReady` means every declared V2 gate is complete.
+
+## Completion Gate
+
+A design-intelligence deliverable is ready for handoff only when:
+
+- The manifest passes with no errors.
+- Every shipped asset has approved rights status and traceable evidence.
+- Token references terminate at valid primitives and declared contrast pairs pass.
+- Semantic icons have accessible names or equivalent visible text.
+- Presentation slides use declared masters and have explicit reading order.
+- Final artifacts have been inspected at their actual size and channel.
+- Interface systems have verified captures at 375, 768, 1024, and 1440 CSS pixels and attributable human review before visual release.
+- Remaining warnings and limitations are reported rather than hidden.

package/knowledge-base/design-intelligence/asset-generation.md

@@ -0,0 +1,66 @@
+# Asset Generation
+
+Treat asset creation as a controlled production pipeline. Generate or source real assets only after their role, constraints, evidence, and fallback behavior are known.
+
+## Step 1: Write The Asset Brief
+
+For each asset, define:
+
+- A stable identifier, one concrete purpose, and the decision or task it supports.
+- Product task and location.
+- Information the asset must communicate.
+- Audience, channel, dimensions, crop behavior, and density.
+- Brand attributes and prohibited traits.
+- Required subject accuracy and details that must remain visible.
+- Background, transparency, safe area, and text-overlay constraints.
+- Alternative-content requirement.
+- Failure behavior: hide decorative media, preserve a text alternative, show a factual placeholder,
+  offer retry, or block only when the task cannot remain truthful without the asset.
+- Rights and provenance requirements.
+
+Do not use an atmospheric placeholder where users need to inspect a product, person, state, place, or result.
+
+## Step 2: Choose A Production Method
+
+Use existing approved assets when they satisfy the brief. Use licensed libraries for commodity imagery or media when terms fit the channels. Commission or create original work when distinctiveness, factual control, or long-term ownership matters. Use generative tools when iteration speed is valuable and the output can be reviewed, corrected, and documented.
+
+Keep generation provider-neutral. Record provider, model, prompt artifact, human selection and editing, and every reference asset. Do not use references with pending, rejected, or unknown rights. Do not request imitation of a living artist, competitor identity, protected character, or identifiable private person without an appropriate basis and review.
+
+## Step 3: Generate And Select
+
+Generate purposeful variants that test composition, hierarchy, crop, lighting, and brand fit. Do not treat minor seed changes as meaningful exploration.
+
+Reject output with:
+
+- Incorrect product geometry or UI.
+- Invented text, metrics, controls, logos, or certification marks.
+- Inconsistent hands, faces, perspective, shadows, or reflections.
+- Visual ambiguity at intended size.
+- Inaccessible text baked into imagery.
+- Unclear resemblance or source provenance.
+- A composition that cannot survive responsive cropping.
+
+Selection must be based on the brief and not only visual novelty.
+
+## Step 4: Finish The Asset
+
+- Retouch factual and visual errors.
+- Rebuild logos, diagrams, charts, and icons as controlled vector or code-native artifacts when appropriate.
+- Remove metadata that should not ship while preserving internal provenance records.
+- Export intended formats and densities.
+- Compress without damaging text, line art, or required detail.
+- Define focal point, crop rules, alt text or equivalent, and fallback behavior.
+- Test on actual backgrounds and viewport ranges.
+
+## Step 5: Record Provenance
+
+Every version 2.1 asset record must include purpose, origin, creator, local path, rights status,
+rights basis, evidence, restrictions, attribution when required, alternative-content classification,
+and explicit failure behavior. Generated assets also require model and prompt records, human
+contributions, and reference-rights status.
+
+An `approved` label without a source URL or evidence path is invalid. Generated output is not automatically owned, copyrightable, non-infringing, or suitable for every use.
+
+## Validation
+
+Run the design-deliverable validator, then inspect the actual asset at 100 percent, intended display size, smallest responsive crop, and highest-risk background. Use human review for product accuracy, resemblance, taste, cultural context, and brand distinctiveness.