Version 2.5.5 | Apache 2.0 | Open Source | Language: Italian (it)
🚀 New user? Start from START_HERE.md
You do not need to read this README to produce a manual. The operator path is:
START_HERE.md→OperatorGuide/01_Primo_Manuale.md→FIRST_PROJECT.md. This README describes the architecture, for contributors and developers.Operator documents (v2.5.5): START_HERE.md · OperatorGuide/ · WORKFLOW.md · LIFECYCLE.md · PROJECT_STRUCTURE.md · FILE_MATRIX.md · WHO_MODIFIES_WHAT.md · OPERATOR_PROFILE.md · tutorials FIRST_PROJECT.md, FIRST_RENDER.md, FIRST_PDF.md
Note: operator-facing guides are written in Italian — the working language of the manuals and their operators. Framework and architecture docs are in English.
Mini4WD Manual SDK is an open-source framework that enables any AI model to generate professional illustrated painting manuals for Tamiya Mini4WD models, maintaining consistent editorial and graphic standards across hundreds of projects.
The SDK provides a specification layer, component system, prompt engine, design tokens, text engine, and CMS layer required to produce manuals that are visually coherent, technically accurate, and immediately recognizable — regardless of which AI model, tool, or contributor generated them.
This framework draws inspiration from Tamiya's technical catalogs and instruction sheets of the 1990s: clean white backgrounds, precise callout boxes, numbered steps, and a sense of craft that communicated both information and enthusiasm. That foundation is reinterpreted with modern graphic design sensibilities — structured grid systems, a systematic color palette derived from the Tamiya "Star Mark" logo, typographic hierarchy, and render-quality illustrations.
The result is a manual system that feels timeless without feeling dated. Every page should look like it was designed by the same studio, whether it was produced in 2024 or 2034.
All editorial text is produced in Italian only. No Japanese scripts (kanji, hiragana, katakana), no English body text, no Lorem ipsum placeholders are permitted in released pages.
The SDK separates content generation into three independent engines that execute in strict sequence:
TEXT ENGINE → QA ENGINE → RENDER ENGINE → PDF
Generates all editorial text from PROJECT.yaml and Knowledge/ inputs. Output is a validated content.yaml file — the primary source of truth for every page. text.md is derived from content.yaml and is secondary.
Validates content.yaml against the Content Validation suite (8 checks: schema, language, data completeness, metadata, manifest, component mapping, cross-page consistency, mechanical safety) and the Text Validation suite (9 Italian-language compliance checks). A page cannot proceed to rendering until both suites pass.
Reads content.yaml exclusively. Never reads text.md directly. Page text and
layout are produced by a deterministic template (Scripts/render_page.py —
Jinja2/HTML/CSS + Playwright/Chromium), not generated by an AI: zero risk of
hallucinated hex codes, names, or language. An AI model is only needed for the
illustrations still missing (cover render, orthographic views, detail photos) —
one isolated image at a time, never a whole page. See Docs/LOCAL_RENDER_NODE.md
for why this split replaced the earlier whole-page AI rendering approach.
Each page is stored as a self-contained content module with 7 files, inside the project variant folder:
Projects/{Model}/{Variant}/ApprovedText/P001/
├── content.yaml ← PRIMARY source of truth
├── text.md ← derived, read-only after approval
├── metadata.yaml ← page lifecycle state
├── manifest.yaml ← components, images, tokens, dependencies
├── changelog.md ← revision history
├── notes.md ← editorial annotations (not rendered)
└── README.md ← module documentation
Multiple variants of the same model are siblings: Projects/Proto_Emperor/Violet_Phantom/ and Projects/Proto_Emperor/Midnight_Blue/ coexist without conflict.
draft → review → approved → locked → rendered → released → archived
A page advances through the lifecycle only after passing QA at each gate. Locked pages cannot be edited without a formal revision.
Every PromptEngine/ prompt must load context in this order before generating:
DESIGN_LANGUAGE → COMPONENT_SYSTEM → TOKENS → TEXT_ENGINE →
LANGUAGE_POLICY → AI_OPERATING_RULES → PROJECT.yaml → GENERATE
Windows: the commands below (and
Scripts/render_page.py/package_handoff.shlater in the pipeline) are bash scripts. Use Git Bash (bundled with Git for Windows — already installed if you cloned withgit). PowerShell/cmd.exe do not run them natively. Details:FIRST_RENDER.md §Prerequisiti.
Step 1 — Clone the SDK
git clone https://github.com/diegoperu/mini4wdpaintframework.git
cd mini4wdpaintframeworkStep 2 — Create a project
mkdir -p Projects/MyModel/MyVariant/{Images,ApprovedText}
cp Templates/PROJECT.yaml Projects/MyModel/MyVariant/PROJECT.yamlEdit Projects/MyModel/MyVariant/PROJECT.yaml — fill in model name, paint scheme, and set paintScheme.slug (kebab-case, required from v2.5.0).
Step 3 — Run the Text Engine (Phase 2a)
For each page P001–P010, load the prompt from PromptEngine/ following the LOAD sequence above. The Text Engine generates Projects/{Model}/{Variant}/ApprovedText/P00x/content.yaml.
Step 4 — Run Content and Text QA (Phase 2b–2c)
Validate each content.yaml against Tests/ContentValidation.md (8 suites) and Tests/TextValidation.md (9 suites). Fix all blocking failures before proceeding.
Step 5 — Seal Approved Assets (Phase 2d)
Set metadata.yaml → status: locked for each page that passes QA. Locked content cannot be modified without a changelog entry.
Step 6 — Run the Render Engine (Phase 3)
Run Scripts/render_page.py {Model} {Variant} — a deterministic template reads the
locked content.yaml and produces text/layout for every page, no AI involved. For
any illustration slot it reports missing (cover, orthographic views, detail
photos), generate it in a fresh chat per slot using the ready-made prompts in
Projects/{Model}/{Variant}/MISSING_IMAGES_PROMPT.md, then re-run the script to
confirm it's picked up. See FIRST_RENDER.md for the full walkthrough.
Step 7 — Image and Page QA (Phase 4)
Validate any generated illustrations against Core/QA_SYSTEM.md (110-item
checklist) and the visual tests in Tests/ — the text/layout portion is
deterministic and needs no QA pass.
Step 8 — Export PDF (Phase 5)
Once all 10 pages pass QA, export using Templates/PDF_CONFIG.yaml. See Core/PDF_MASTER.md for the full export specification.
For the full pipeline with all phases, see Build/Pipeline.md.
If you are an AI model (ChatGPT, Claude, or any other verified model), read these files in order before generating anything. Do not skip steps. Note: Gemini is supported for Phase 4 only (single-illustration generation) — failed UAT-002 for the old whole-page Phase 3/4 scope, passed UAT-004 under the current split architecture. Phase 1-3 (text/bootstrap) remain unverified. See
UAT/UAT-002.mdandUAT/UAT-004.md.
Step 1 — Read AI_ENTRYPOINT.md
The official SDK entry point. Contains the Bootstrap Contract (binding rules for the entire session), mission, source-of-truth hierarchy, pipeline overview, Golden Rules, and the First Response Policy. After reading this file, produce a Bootstrap Report and wait for user approval before generating any content.
Step 2 — Read SDK_CONTEXT.yaml
Machine-readable SDK identity card. Confirms the version, pipeline sequence, source-of-truth hierarchy, and load order. Use this to verify you have the correct version of the SDK.
Step 3 — Follow BOOTSTRAP.md
Operational guide — expands on the rules and workflow from AI_ENTRYPOINT.md. Contains the detailed pipeline, page/component index, common errors to avoid, and document map.
Step 4 — Read Projects/{ModelFolder}/{VariantFolder}/PROJECT.yaml
Project configuration for the current variant. Contains the model name, paint colors (Tamiya codes + Italian names), paintScheme.slug, and render paths. All content.yaml fields are populated from this file.
Step 5 — Read Projects/{ModelFolder}/{VariantFolder}/ApprovedText/{page}/
Existing sealed content for each page. If metadata.yaml → status: locked, the page is already approved — proceed directly to rendering. Never regenerate locked content.
Step 6 — Load Reference Images
Photography of the physical Mini4WD model. Required by the Render Engine to ensure renders match the real product exactly. Do not modify the model's shape.
After loading all documents: produce a Bootstrap Report (format defined in AI_ENTRYPOINT.md) and wait for user approval before generating any content.
For the full AI context loading order with rationale, see Docs/LOAD_ORDER.md.
For ready-to-use prompts (ChatGPT, Claude), see Docs/AI_BOOTSTRAP_PROMPT.md.
For step-by-step project creation, see Projects/PROJECT_BOOTSTRAP.md.
mini4wdpaintframework/
│
├── README.md ← You are here (human contributors)
├── BOOTSTRAP.md ← Operational guide expanding on AI_ENTRYPOINT.md (AI models)
├── SDK_CONTEXT.yaml ← SDK identity card — version, pipeline, load order
├── STATUS.md ← Implementation status, roadmap, known issues
├── ReleaseInfo.yaml ← Machine-readable release metadata
├── RepositoryManifest.yaml ← Complete file and dependency map
├── CHANGELOG.md ← Version history
├── VERSION ← Current version (2.5.5)
├── MANIFEST.yaml ← Full SDK descriptor (components, tokens, pages)
├── LICENSE ← Apache 2.0
├── STYLE_DECISIONS.md ← Architecture Decision Records (ADR-001–ADR-022)
├── ROADMAP.md ← Planned features and future direction
├── MigrationReport_v2.4.md ← Migration guide from v2.3.0 to v2.4.0
├── MigrationReport_v2.4.1.md ← Migration guide from v2.4.0 to v2.4.1
├── AI_ENTRYPOINT.md ← Official AI entry point — Bootstrap Contract, Golden Rules
├── GPT.md ← Standing project-status brief to attach in a new ChatGPT chat
│
├── START_HERE.md ← Human operator entry point
├── FIRST_PROJECT.md ← Tutorial: create a project
├── FIRST_RENDER.md ← Tutorial: render pages + generate missing illustrations
├── FIRST_PDF.md ← Tutorial: export a PDF
├── WORKFLOW.md ← Operator-facing end-to-end workflow
├── LIFECYCLE.md ← Page lifecycle states explained for operators
├── PROJECT_STRUCTURE.md ← Annotated project folder layout
├── FILE_MATRIX.md ← Which file does what, at a glance
├── WHO_MODIFIES_WHAT.md ← Human vs AI file-ownership matrix
├── OPERATOR_PROFILE.md ← Expected operator background and skills
│
├── Core/ ← Authoritative specification layer (Core/ always wins)
│ ├── DESIGN_LANGUAGE.md ← 65 philosophical rules governing all design decisions
│ ├── STYLE_GUIDE.md ← Colors, typography, grid, spacing
│ ├── COLOR_SYSTEM.md ← Full color palette and usage rules
│ ├── MANUAL_SYSTEM.md ← Architecture overview and lifecycle
│ ├── PAGE_SYSTEM.md ← P001–P010 specifications
│ ├── COMPONENT_SYSTEM.md ← C001–C015 specifications with content.yaml field mapping
│ ├── TEXT_ENGINE.md ← Text Engine spec; content.yaml as primary output
│ ├── AI_OPERATING_RULES.md ← 102 rules for AI model behavior (Rules 059–100: text rendering, 101–102: mechanical safety)
│ ├── RENDER_GUIDE.md ← Rendering standards and AI render prompts
│ ├── PDF_MASTER.md ← Export specification
│ ├── QA_SYSTEM.md ← 110-item quality checklist
│ ├── WORKFLOW.md ← End-to-end process documentation
│ ├── NAMING_CONVENTION.md ← File and folder naming rules
│ ├── DOCUMENTATION_STYLE.md ← How to write SDK documentation
│ └── DEFINITION_OF_DONE.md ← Completion criteria
│
├── Config/ ← Global SDK configuration
│ ├── sdk.yaml ← Global parameters and version
│ ├── render.yaml ← Camera angles, lighting rigs, resolution
│ ├── pdf.yaml ← Export variants (screen / print / archive)
│ ├── quality.yaml ← QA thresholds, blocking/non-blocking classification
│ └── LANGUAGE_POLICY.yaml ← Italian-only policy, forbidden languages, approved placeholders
│
├── PromptEngine/ ← Page-specific AI prompts (model-agnostic)
│ ├── README.md ← LOAD sequence and usage instructions
│ ├── Cover.md ← P001
│ ├── ColorScheme.md ← P002
│ ├── Materials.md ← P003
│ ├── Preparation.md ← P004
│ ├── Painting.md ← P005
│ ├── Masking.md ← P006
│ ├── Details.md ← P007
│ ├── Decals.md ← P008
│ ├── Premium.md ← P009
│ └── FinalChecklist.md ← P010
│
├── Scripts/ ← Utility scripts for operators
│ ├── generate_prompts.py ← Generates pre-filled prompts from PROJECT.yaml (v2.5.0)
│ ├── render_page.py ← Deterministic template renderer (v2.5.5): content.yaml → PNG/PDF, no AI
│ ├── package_handoff.sh ← Packages a single project's illustration-only AI handoff zip
│ ├── requirements.txt ← Python deps for render_page.py (Jinja2, Playwright, PyYAML)
│ └── templates/ ← Jinja2/HTML/CSS page templates, one per page type (P001–P008, P010)
│
├── Templates/ ← Starter files for new projects
│ ├── PROJECT.yaml ← Project configuration template
│ ├── PROJECT.md ← Human-readable project brief template
│ ├── CHECKLIST.md ← Per-project QA checklist
│ ├── COLOR_SCHEME.yaml ← Paint scheme definition template
│ └── PDF_CONFIG.yaml ← PDF export configuration
│
├── Projects/ ← {Model}/{Variant}/ two-level structure (v2.5.0)
│ ├── PROJECT_BOOTSTRAP.md ← Step-by-step guide for starting a new project
│ └── {Model}/{Variant}/ ← e.g. Magnum_Saber_Premium/Cotton_Candy_Drift
│ ├── PROJECT.yaml ← Contains paintScheme.slug
│ ├── Images/ ← Reference photos (ref_*.jpg) AND generated illustrations
│ │ (cover_3q.png, P00x_*.png/.jpg) — single flat folder, no ApprovedImages/
│ ├── ApprovedText/P00x/ ← content.yaml + 6 companion files per page (see CMS Layer above)
│ ├── MISSING_IMAGES.md ← generated by render_page.py: which illustration slots are missing
│ ├── MISSING_IMAGES_PROMPT.md ← ready-to-paste AI prompt per missing slot
│ ├── MISSING_IMAGES.json ← same data, machine-readable
│ └── {Model}_{Variant}.pdf ← merged manual (Scripts/render_page.py ... pdf)
│
├── Assets/ ← Design system, references, approved output
│ ├── DesignSystem/
│ │ ├── Tokens/ ← Design tokens (tokens.example.yaml, tokens.schema.yaml)
│ │ ├── Components/ ← Component wireframes and specs
│ │ ├── Palette/ ← Color swatch references
│ │ ├── Typography/ ← Font specimens + Fonts/ (embedded .otf/.ttf, OFL-licensed, used by render_page.py)
│ │ ├── Icons/ ← Icon library (planned v2.5.0; interim: Unicode symbols)
│ │ └── Layout/ ← Grid and wireframe templates
│ ├── ReferenceModels/ ← Reference photography per model
│ ├── ApprovedManual/ ← Production-approved manual output
│ └── Examples/ ← Example pages for onboarding
│
├── Build/ ← Build pipeline documentation
│ └── Pipeline.md ← 8-phase production pipeline (Phase 0 → Phase 7)
│
├── Tests/ ← QA test suites (9 suites)
│ ├── ContentValidation.md ← 8 suites validating content.yaml (NEW v2.4.0; mechanical safety added v2.5.5)
│ ├── TextValidation.md ← 9 Italian-language compliance tests
│ ├── FrameworkIntegrity.md ← SDK self-consistency
│ ├── PromptValidation.md
│ ├── LayoutValidation.md
│ ├── NamingValidation.md
│ ├── ColorValidation.md
│ ├── PDFValidation.md
│ └── AssetsValidation.md
│
├── Knowledge/ ← Technical and editorial knowledge base (14 documents)
│ ├── Paints.md ← Paint types, properties, compatibility
│ ├── Masking.md ← Masking techniques
│ ├── Preparation.md ← Surface preparation
│ ├── Painting.md ← Painting techniques
│ ├── Decals.md ← Decal application
│ ├── ClearCoat.md ← Clear coat finishing
│ ├── Troubleshooting.md ← Common issues and fixes
│ ├── Glossary.md ← Technical glossary (EN)
│ ├── GlossaryIT.md ← Technical glossary (IT)
│ ├── FAQ.md
│ ├── BestPractices.md
│ ├── EditorialStyle.md ← Italian editorial voice and style
│ ├── Terminology.md ← Approved Italian terminology
│ └── ForbiddenWords.md ← Words and phrases never to use
│
├── Docs/ ← Extended documentation and guides
│ ├── README.md ← Docs/ folder index
│ ├── LOAD_ORDER.md ← Explicit AI context loading order with rationale
│ ├── AI_BOOTSTRAP_PROMPT.md ← Ready-to-use prompts for ChatGPT, Claude (Gemini: Fase 4 only — UAT-004)
│ ├── RUNTIMES.md ← Which runtime (Claude Code / ChatGPT Web / Gemini) does what, and why
│ ├── RENDER_HANDOFF_CONTEXT.md ← Framing doc bundled by package_handoff.sh for AI illustration requests
│ ├── LOCAL_RENDER_NODE.md ← Local AI render node evaluation; rationale for the template+AI split
│ └── migration/
│ └── v1-to-v2.md ← Migration guide: SDK v1.x → v2.x
│
├── OperatorGuide/ ← Human operator playbook, per-runtime (v2.4.1)
│ ├── README.md
│ ├── 01_Primo_Manuale.md … 07_FAQ.md ← 7 numbered chapters
│ └── Runtimes/
│ ├── Claude_Code.md ← Step-by-step for the Claude Code runtime
│ └── ChatGPT_Web.md ← Step-by-step for the ChatGPT Web runtime
│
├── Documentation/ ← Formal governance layer (v2.5.5)
│ ├── OperationalManual/ ← 20-chapter operational manual + Validation/
│ └── QualityManagement/ ← 20-document Quality Management System (release policy,
│ known issues, decision log, golden projects…) + Reports/
│
└── UAT/ ← User Acceptance Test records
├── UAT-001.md
├── UAT-002.md
└── UAT-004.md
| Document | Purpose |
|---|---|
| AI_ENTRYPOINT.md | Official AI entry point — Bootstrap Contract, Golden Rules, First Response Policy |
| BOOTSTRAP.md | Operational guide expanding on AI_ENTRYPOINT.md — pipeline, page/component index, errors to avoid |
| SDK_CONTEXT.yaml | SDK identity card — version, pipeline, source of truth |
| Docs/LOAD_ORDER.md | Explicit context loading order with rationale |
| Docs/AI_BOOTSTRAP_PROMPT.md | Ready-to-use prompts for ChatGPT, Claude (Gemini: Fase 4 only — UAT-004) |
| Projects/PROJECT_BOOTSTRAP.md | Step-by-step new project guide |
| STATUS.md | Implementation status, roadmap, known issues |
| ReleaseInfo.yaml | Machine-readable release metadata |
| RepositoryManifest.yaml | Complete file and dependency map |
| Document | Purpose |
|---|---|
| Core/DESIGN_LANGUAGE.md | 65 rules governing every design decision |
| Core/STYLE_GUIDE.md | Color, typography, grid, spacing specifications |
| Core/PAGE_SYSTEM.md | Specification for pages P001–P010 |
| Core/COMPONENT_SYSTEM.md | Specification for components C001–C015 |
| Core/TEXT_ENGINE.md | Text Engine spec; content.yaml as primary output |
| Core/AI_OPERATING_RULES.md | 102 behavioral rules for AI models |
| Core/RENDER_GUIDE.md | Illustration standards and AI render prompts |
| Core/QA_SYSTEM.md | 110-item quality checklist |
| Core/WORKFLOW.md | End-to-end production workflow |
| Config/LANGUAGE_POLICY.yaml | Italian-only policy and forbidden language rules |
| Build/Pipeline.md | 8-phase production pipeline |
| Document | Purpose |
|---|---|
| Documentation/QualityManagement/ | 20-document evidence-based governance layer: release policy, release criteria, bug/UAT/feature-request templates, decision log, known issues, golden projects, roadmap, change proposals |
| Documentation/QualityManagement/01_RELEASE_POLICY.md | What can go into a Patch / Minor / Major release |
| Documentation/QualityManagement/07_KNOWN_ISSUES.md | Live registry of open and archived known issues |
| UAT/ | User Acceptance Test records (per-runtime evidence, e.g. Gemini Fase 4) |
This project follows Semantic Versioning 2.0.0.
- MAJOR version: breaking changes to page IDs, component IDs, token names, or PROJECT.yaml schema
- MINOR version: new pages, components, tokens, or layers added in a backwards-compatible manner
- PATCH version: bug fixes, clarifications, typo corrections
Version is stored in VERSION and MANIFEST.yaml. Every release is documented in CHANGELOG.md. Breaking changes include a migration guide in Docs/migration/.
| Version | Key Addition |
|---|---|
| 2.1.0 | Core framework: Design Language, Component System, Design Tokens, PromptEngine |
| 2.2.0 | Build pipeline, Config layer, Test suites, AI Operating Rules, Knowledge base |
| 2.3.0 | Text Engine, Editorial Pipeline, Italian language policy, LOAD sequence |
| 2.4.0 | CMS layer (ApprovedAssets/), content.yaml as source of truth, page lifecycle |
| 2.4.1 | UX & Operator Workflow Update: START_HERE, OperatorGuide/, tutorials, single image convention, validation scoping |
| 2.5.0 | Multi-Project Content Isolation: per-variant Projects/{Model}/{Variant}/ structure |
| 2.5.5 | Deterministic Rendering: Scripts/render_page.py template replaces whole-page AI rendering, Scripts/package_handoff.sh narrowed to illustration-only handoff, custom fonts embedded, PDF merge, Gemini restored for Fase 4 |
Contributions are welcome. Before opening a pull request:
- Read
Core/DOCUMENTATION_STYLE.mdto match the existing documentation voice - For any change to
Core/, file an Architecture Decision Record inSTYLE_DECISIONS.md - File a Change Proposal per
Documentation/QualityManagement/15_CHANGE_PROPOSAL_TEMPLATE.mdand check it againstDocumentation/QualityManagement/01_RELEASE_POLICY.md(Patch vs Minor vs Major) - Update
CHANGELOG.mdunder[Unreleased] - Ensure your changes pass the test suites in
Tests/ - Ensure your changes meet the criteria in
Core/DEFINITION_OF_DONE.md
Open issues and feature requests are tracked on GitHub. Tag feature requests with the roadmap label. See ROADMAP.md for what is already planned.
Copyright 2024 Mini4WD Manual SDK Contributors.
Licensed under the Apache License, Version 2.0. See LICENSE for full terms.
Mini4WD Manual SDK is not affiliated with Tamiya Inc. "Mini 4WD" is a trademark of Tamiya Inc. This SDK is an independent open-source project for hobbyist documentation.