# Fractal

Design guidance for a Pi-based agent using multiple models. Fractal is organized by design domain, with portable skills and explicit context loading.

Start with [SKILL.md](SKILL.md), then [core.md](core.md), then a domain's skill. See [the review guide](review/README.md) for migrated content and decisions.

```text
SKILL.md                 Select domain, then task
core.md                    Small shared interpretation contract
manifest.json              Required context and conditional dependencies
shared/                    Shared colors, fonts, and approved icon catalogue
domains/
  product-ui/              Product interfaces and their foundations
  reports/                 HTML summaries and evidence briefs
  data-visualization/       Charts and scientific figures
  presentations/           Format workflows and opt-in Blueprint profile
  showcase-video/          Product showcase videos composed from scene specs
resources/                 Canonical tokens and optional implementation helpers
assets/typography/         Font assets and license notices
integration/pi.md          Host ingestion contract
scripts/                   Static context resolver and structural validator
review/                    Migration provenance and review decisions
```

Each domain has its own `skills/` and `references/`. Shared files apply only where explicitly imported. The shared palette is the default, including new presentations; product typography, chart semantics, and Blueprint geometry remain scoped. Crystal illustration was intentionally retired.

`fractal-ui` and `fractal-icons` remain separate packages. This repository provides their design direction, not replacement React implementations or a second shipped SVG library. Approved SVG source remains in `design/icons/`; `shared/icons/catalogue.json` links to its catalogue for context loading.

## Inspect and validate

Python 3.10+ is sufficient for the resolver and validator:

```sh
python3 scripts/validate.py
python3 scripts/context.py --list
python3 scripts/context.py --bundle presentation-create --format markdown
python3 scripts/context.py --bundle product-ui --signal product-charts --signal chart-line
```

`--allow-unresolved` is only for inspecting a draft that has open decisions. Normal resolution refuses affected bundles while such decisions remain unresolved. The JSON response includes the actual document texts, paths, hashes, matched conditions, and unused signals; the host can consume it directly.

Pi package metadata lists the domain skill directories. Loading the package advertises skills; domain-first routing and mandatory context delivery still need host integration as described in [integration/pi.md](integration/pi.md). No Pi extension is installed and no model provider is assumed.

The migrated `resources/tokens/colors.css` defines canonical tokens, but is not a complete implementation of the new four-variant button API. Its blue Primary values follow the [shared variant policy](shared/primary-actions.md). Production migration must update the owning package and consumers; public-website main CTAs should select Secondary.

Optional plotting, color-preview, and presentation helpers require their own runtimes/dependencies. Their source is an implementation aid, not evidence automatically loaded into the model. Run presentation helper commands from `resources/presentations/` with absolute input/output paths. Do not assume a shell, renderer, font installation, or Figma access exists in the consuming host.

## Validation scope

Structural validation and resolver behavior are tested. The external checks live in `fractal-testing/evals/pipelines/fractal-next-context/` and can target this checkout through `FRACTAL_NEXT_REPO`. Model selection accuracy and visual quality still require representative runs through the real Pi harness and intended models. The domain-first rewrite is adopted. Consumers must integrate the new SKILL.md/manifest.json loading contract; the old routing.md entry point is retired.
