# IterFact-template-vault

## What this is
A library of `40` interactive HTML engines designed for AI-assisted assembly and IterFact template generation.

The vault is useful for:

- template and product scaffolding
- prospect-specific demos
- operator-assisted delivery
- future structured engine rendering inside IterFact

## Current shape
Each engine currently includes:

- `template.html`
- `meta.json`

The vault root also includes:

- `manifest.json`
- `generate_vault.py`
- `generate_vault_v2.py`
- `assembler.py`
- `templates/`
- `test_plan_earnings.json`
- `test_plan_cim.json`

Reference assets now also include:

- `references/web-capabilities.json`
- `references/web-capabilities-source.html`

Builder-planner assets now also include:

- `spec/ASSEMBLY_SPEC.md`
- `spec/SYSTEM_PROMPT.md`
- `spec/system_prompt_raw.txt`
- `spec/PLANNER_TEST_EXAMPLES.md`
- `spec/planner_api.js`

Recent practical additions:

- `assembler.py` now provides a deterministic assembly pass from JSON plan to single HTML output
- `test_plan_earnings.json` and `test_plan_cim.json` provide worked assembly fixtures
- engines `03-dashboard-kpi` and `17-scenario-modeler` were updated to behave better inside assembled wrapper documents
- the latest merge expanded the vault to `40` engines and refreshed the planner prompt source for the new engine set
- `assembler.py` now recognizes engines `31` through `44` and applies stronger overflow protection inside assembled components
- engine `39-globe-testimonials` adds a token-based Three.js globe for rotating social proof and global footprint storytelling
- engine `44-interactive-ranking-chart` adds a sortable ranked range-bar view for consulting-style market maps, leaderboards, and editorial data storytelling
- `templates/` now holds manifest-driven fixed templates and composable panels for the low-cost slot-fill path

## Template layer
Alongside `engines/`, the vault now also has a first-class `templates/`
directory.

Each template directory can contain:

- `manifest.json`
- `template.html`
- `example-data.json`

The manifest can also declare an `input_contract` so a template can say, in a
first-class way, whether it accepts:

- freeform chat/paste
- `csv`
- `xlsx`
- structured `json`

That contract is enforced by the MCP before a template render starts.

Primary templates can expose named injection points and compose compatible
panel templates. This is the path used by the MCP `generate_from_template`
surface when the goal is deterministic slot fill and composition instead of
full freeform generation.

Important caution:

- the planner and assembly source material is useful, but not fully normalized yet
- some source spec files still lag the newer engine contracts

## IFX annotation model
Templates use machine-readable annotations and metadata that align with the internal `IFX` contract direction.

Important markers include:

- `ENGINE_META`
- `AI_USAGE`
- `CUSTOMIZABLE`
- `AI_HINT`

These help AI systems:

1. match user intent to engines
2. understand safe customization points
3. fill structured content into existing templates
4. avoid regenerating everything from scratch

## Engine count
The vault now contains `40` engines.

Core engine families include:

- presentation
- dashboards and reporting
- scenario and calculator tools
- flow and comparison tools
- narrative and scroll formats
- forms and assessments
- spatial and map surfaces
- portfolio and social-proof surfaces

## Important rule
Do not treat this vault as one giant prompt blob.

The preferred flow is:

1. search engine metadata
2. choose the best engine
3. inspect only that engine's contract and template
4. consult the web capabilities reference if implementation technique choice matters
5. render from structured payloads

Important constraint:

- the web capabilities reference is a quality guide, not a license to ignore IterFact runtime policy
- some cataloged web features are still disallowed or inappropriate in normal artifact delivery
- the builder-planner spec assets are useful source material, but they are not canon by themselves

## Naming
Inside IterFact, this saved package should be referred to as:

- `IterFact-template-vault`

It is a carried-forward source asset, but it now belongs to the IterFact system.
