v2.5.0 — Multi-Project Content Isolation

Breaking change: per-project content isolation. ApprovedAssets/Text/ and
ApprovedAssets/Images/ (global) replaced by per-variant directories inside
each project. No functional change to Prompt Engine, Text Engine, or QA logic.

Breaking Changes

• Content path: ApprovedAssets/Text/P{NNN}/ → Projects/{Model}/{Variant}/ApprovedText/P{NNN}/
• Images path: ApprovedAssets/Images/P{NNN}/ → Projects/{Model}/{Variant}/ApprovedImages/P{NNN}/
• Index path: ApprovedAssets/index.yaml → Projects/{Model}/{Variant}/index.yaml
• paintScheme.slug field now REQUIRED in PROJECT.yaml

Added

• Projects/{Model}/{Variant}/ two-level project structure: model folder + variant folder
• paintScheme.slug field in Templates/PROJECT.yaml (kebab-case, source for variant folder name)
• Core/NAMING_CONVENTION.md §3.1 — variant folder naming rule and examples
• Projects/Proto_Emperor/Violet_Phantom/ — reference project migrated to v2.5.0 structure

Changed

• PromptEngine/*.md (all 10) — Save output to: path updated to Projects/{Model}/{Variant}/ApprovedText/P{NNN}/content.yaml
• Core/TEXT_ENGINE.md — v2.5.0 row added to output format table; Render Engine contract path updated
• Core/PAGE_SYSTEM.md — module storage path updated
• AI_ENTRYPOINT.md — Bootstrap Contract required_read_order path updated
• BOOTSTRAP.md — Phase 2a output, Phase 3 output, Phase 7 index paths updated
• Docs/LOAD_ORDER.md — Step 12 path updated
• Docs/AI_BOOTSTRAP_PROMPT.md — Fase 2 write path and Fase 4 output path updated
• Scripts/generate_prompts.py — path construction dynamic from PROJECT.yaml location; variant folder derived from parent dir; paintScheme.slug cross-check; output saved to project dir by default
• VERSION → 2.5.0; SDK_CONTEXT.yaml version updated

Migration from v2.4.x

For each existing project Projects/{Model}/:

1. Create subfolder Projects/{Model}/{Variant}/ (variant = paintScheme.name in Title_Case_Underscore)
2. Move PROJECT.yaml, Images/, Output/, Notes/ into the variant folder
3. Add paintScheme.slug: "variant-slug" to PROJECT.yaml
4. Move any existing ApprovedAssets/Text/ content to Projects/{Model}/{Variant}/ApprovedText/

Full changelog: CHANGELOG.md

v2.4.1 — UX & Operator Workflow Update

UX & Operator Workflow Update

UX-only patch release driven by UAT-001, the first test with an external operator. No framework behavior changes: architecture, Prompt Engine, Text Engine, Component System, Page System and ApprovedAssets structure are untouched. Existing v2.4.0 projects require no action.

The goal: a brand-new operator can clone the repo, create a project, fill PROJECT.yaml, drop in reference photos, get Bootstrap OK and generate P001 — without knowing the framework's inner workings.

🚀 New — Operator Layer

• START_HERE.md — the first document a new user reads: checklist, diagram, do/don't table, chat map (2 pages max)
• OperatorGuide/ — 7-document guide: Primo Manuale, Workflow, File da Modificare, File da NON Modificare, Checklist, Errori Comuni, FAQ
• WORKFLOW.md — operational state machine: Nuovo Progetto → Bootstrap → Testi → QA → Approved Text → Rendering → QA → Approved Images → PDF → Golden Project, each state with obiettivo/input/output/prossimo stato
• FILE_MATRIX.md — every file: editable yes/no, when, by whom, in which phase
• PROJECT_STRUCTURE.md — folders to create / NOT create; single image convention: all operator images in Projects/{Model}/Images/
• FIRST_PROJECT.md / FIRST_RENDER.md / FIRST_PDF.md — end-to-end tutorials with real examples
• WHO_MODIFIES_WHAT.md, LIFECYCLE.md, OPERATOR_PROFILE.md (roles: Operatore, Reviewer, Maintainer, Developer)
• UAT/UAT-001.md — the real-world test report: 8 documentation defects, each with description, cause, applied fix, updated document

🔧 Changed

• Projects/PROJECT_BOOTSTRAP.md — fully rewritten as an operational PASSO 1–8 guide (Italian)
• Docs/AI_BOOTSTRAP_PROMPT.md — restructured by phase (Bootstrap → Testi → QA → Rendering → PDF); each phase declares Input, Output, Prompt, Nuova chat SÌ/NO
• Config/LANGUAGE_POLICY.yaml — exceptions split into 5 explicit language-neutral categories: paint codes (TS-37, XF-1, X-10, X-11…), technical terms (Primer, Topcoat, Masking Tape…), commercial names (Chrome Silver, Gun Metal, Semi Gloss Black, Flat Black…), YAML keys/schema values, structural metadata (Header, Footer, draft). The validator no longer flags these as language violations
• Tests/ContentValidation.md / Tests/TextValidation.md — new §Validation Scope: Template vs Draft vs Approved. Templates (status draft + empty fields) are never validated as final content — generate first, validate after
• Single reference-image convention applied across all docs (Core/WORKFLOW.md, Build/Pipeline.md, Core/MANUAL_SYSTEM.md, Templates/CHECKLIST.md, Tests/AssetsValidation.md, AI_ENTRYPOINT.md); Assets/ReferenceModels/ reserved to the Maintainer
• 13 folder READMEs — standard header: a cosa serve / chi la modifica / quando
• Templates/PROJECT.yaml — legacy ApprovedText/ fields marked v2.3.0-compatibility-only

📋 Ambiguities eliminated (from UAT-001)

1. Reference-image location (two conflicting conventions → one)
2. Template validated as final content (P001 FAIL by construction)
3. Language false positives on technical/commercial terms and metadata
4. Folder name vs modelSlug (underscore vs kebab-case)
5. Minimal project file set (PROJECT.yaml + Images/ + Output/ + Notes/)
6. Placeholder convention (TODO: vs [TITOLO])
7. Phase → prompt → chat mapping
8. Missing human entry point (AI-only bootstrap docs)

Compatibility

Backward compatible with 2.1.0 → 2.4.0. PROJECT.yaml schema, Page IDs, Component IDs, tokens, PromptEngine: unchanged.

Full migration report: MigrationReport_v2.4.1.md · UAT report: UAT/UAT-001.md

v2.4.0 — CMS Layer: Pages as Structured Content Modules

v2.4.0 — CMS Layer

SDK evolves from editorial framework to full CMS. Pages are now structured content modules with lifecycle management.

Novità principali

• ApprovedAssets/ — Layer CMS completo con moduli pagina P001–P010
• content.yaml come fonte unica di verità — il Render Engine legge esclusivamente questo file (non PROJECT.yaml)
• Ciclo di vita della pagina — draft → review → approved → locked → rendered → released → archived
• P009 condizionale — inclusa solo se premiumVariant.enabled: true
• Tests/ContentValidation.md — suite TEST-CV-001→009 (375 check totali)
• MigrationReport_v2.4.md — log completo della migrazione

Struttura ogni modulo pagina

ApprovedAssets/Text/P{NNN}/
├── content.yaml    ← SOURCE OF TRUTH
├── text.md         ← derivato (revisione editoriale)
├── metadata.yaml   ← lifecycle + approvazioni
├── manifest.yaml   ← componenti, immagini, token
├── changelog.md    ← storia revisioni per pagina
├── notes.md        ← annotazioni editoriali
└── README.md       ← documentazione modulo

ADR introdotti

• ADR-019 — content.yaml come fonte unica di verità
• ADR-020 — Page-as-Module Architecture con lifecycle
• ADR-021 — Render Engine legge content.yaml esclusivamente

Compatibilità

Nessuna breaking change. I progetti v2.3.0 continuano a funzionare senza modifiche. ApprovedText/ mantenuto per retrocompatibilità.

File modificati/aggiunti

89 file: 77 nuovi in ApprovedAssets/, aggiornamenti a Build/Pipeline.md, Core/TEXT_ENGINE.md, Core/COMPONENT_SYSTEM.md, Core/PAGE_SYSTEM.md, PromptEngine/README.md, MANIFEST.yaml, STYLE_DECISIONS.md, CHANGELOG.md, ROADMAP.md, VERSION.

---

Repo · MigrationReport

Mini4WD Manual SDK v2.3.0 — Text Engine

Mini4WD Manual SDK v2.3.0

Theme: Text Engine + Editorial Pipeline

Full backward-compatible evolution. All v2.2.0 projects work without modification.

---

Architecture Change

SDK evolves from documentation framework to editorial framework. Text and rendering are now fully decoupled:

PROJECT.yaml
    ↓
Knowledge Load (GlossaryIT, EditorialStyle, LANGUAGE_POLICY)
    ↓
Text Engine → Italian editorial content
    ↓
Editorial QA (Tests/TextValidation.md)
    ↓
ApprovedText/ (P001.md – P010.md) ← sealed, language-validated
    ↓
Render Engine ← reads ApprovedText/ as read-only
    ↓
Page QA → Approved Manual → PDF

---

What's New

Text Engine

• Core/TEXT_ENGINE.md — complete Text Engine specification
• Templates/APPROVED_TEXT.md — output file template with YAML frontmatter
• Projects/*/ApprovedText/ — per-project approved text directory

Language Policy

• Config/LANGUAGE_POLICY.yaml — machine-enforceable Italian-only policy
  • Zero tolerance for Japanese scripts (kanji, hiragana, katakana)
  • Forbidden: Lorem ipsum, English body text, fake text
  • Approved placeholders: [TITOLO], [TESTO], [VALORE NON SPECIFICATO]

Test Suite

• Tests/TextValidation.md — 40-item editorial QA (TEST-TX-001–009)
  • Language compliance (Unicode range checks for CJK)
  • Fake text prohibition
  • Token resolution verification
  • Terminology consistency
  • Tone and register validation

Italian Knowledge Base

• Knowledge/EditorialStyle.md — voice, tone, sentence structure, numbers
• Knowledge/GlossaryIT.md — authoritative Italian terminology, page labels, component labels
• Knowledge/Terminology.md — technical term equivalents
• Knowledge/ForbiddenWords.md — forbidden scripts, phrases, marketing language

AI Operating Rules Expanded

• Core/AI_OPERATING_RULES.md — Rules 059–100: TEXT RENDERING RULES
  • 42 new rules for Italian-only content generation
  • Explicit Japanese prohibition
  • Render Engine text placement rules

Updated Documents

• Core/DESIGN_LANGUAGE.md — Rules 55–65: visual Japanese aesthetic ≠ Italian editorial language
• Core/STYLE_GUIDE.md — Typography Rules section (type hierarchy, capitalization, max lengths)
• Core/COMPONENT_SYSTEM.md — Text Source Declaration per component
• Build/Pipeline.md — Phases 2/2a/2b/2c added
• PromptEngine/README.md — LOAD sequence defined
• Templates/PROJECT.yaml — text: section added

---

Migration from v2.2.0

No breaking changes.

Optional steps:

1. Add text: block to PROJECT.yaml files
2. Create ApprovedText/ directory in project folder
3. Use updated LOAD sequence in prompts for better language compliance

---

Stats

• Total files: 97
• New files: 10
• Modified files: 11
• New AI rules: 42 (Rules 059–100)
• New QA items: 40 (TextValidation)
• New ADRs: 3 (ADR-016, 017, 018)

Mini4WD Manual SDK v2.2.0

Mini4WD Manual SDK v2.2.0

Full backward-compatible evolution of the SDK. All v2.1.0 projects work without modification.

---

What's New

Build System

• Build/Pipeline.md — complete 7-phase production pipeline with input/output contracts per phase (Project Setup → Reference Models → Prompt Engine → Render Engine → QA → PDF Generation → Release)

Configuration Layer

• Config/sdk.yaml — global SDK parameters, page/component registry, naming rules
• Config/render.yaml — camera angles, lighting rigs, resolution requirements
• Config/pdf.yaml — export variants (screen/print/archive), page order, metadata fields
• Config/quality.yaml — QA thresholds, blocking vs non-blocking failure classification

Test Suites

• Tests/FrameworkIntegrity.md — SDK self-consistency checks
• Tests/PromptValidation.md — prompt template correctness
• Tests/LayoutValidation.md — page and component layout
• Tests/NamingValidation.md — file and folder naming
• Tests/ColorValidation.md — color accuracy and token usage
• Tests/PDFValidation.md — PDF export correctness
• Tests/AssetsValidation.md — asset presence and format

AI Operating Rules

• Core/AI_OPERATING_RULES.md — 58 mandatory behavioral rules for AI models across 9 categories (DATA, DESIGN, LAYOUT, COLOR, CONTENT, RENDER, COMPONENT, TOKEN, OUTPUT)

Knowledge Base

• Knowledge/Paints.md — Tamiya, Mr. Hobby, Vallejo product lines and code formats
• Knowledge/Masking.md — tape types, masking order, common defects
• Knowledge/Preparation.md — 6-step surface preparation sequence
• Knowledge/Painting.md — spray, brush, and airbrush techniques
• Knowledge/Decals.md — water-slide decal application process
• Knowledge/ClearCoat.md — finish types, compatibility matrix, polishing
• Knowledge/Troubleshooting.md — surface and decal defect diagnosis
• Knowledge/Glossary.md — technical terminology reference
• Knowledge/FAQ.md — common questions and answers
• Knowledge/BestPractices.md — 25 expert recommendations

SDK Manifest

• MANIFEST.yaml — machine-readable SDK descriptor with directory map, page/component registry, AI requirements, compatibility matrix

---

Updated Documents

• STYLE_DECISIONS.md — ADR-011 through ADR-015 added
• ROADMAP.md — v2.3.0 and v3.0.0 scopes refined
• CHANGELOG.md — v2.2.0 entry

---

Migration from v2.1.0

No action required. All v2.1.0 PROJECT.yaml files are fully compatible.

---

Stats

• Total files: 85 (57 from v2.1.0 + 28 new)
• New lines: ~3,900
• Breaking changes: None