# Pi ingestion contract

This is a host integration contract and reference resolver, not an installed Pi extension. The consuming Pi application's source/version was not supplied, so no specific SDK hook is assumed or installed.

## Two supported consumption paths

**Integrated host (preferred).** Supply `core.md` and `SKILL.md` automatically for task selection. Select the design domain through `SKILL.md`, then classify the requested work into manifest bundle IDs, resolve their required context, and supply the resulting documents before implementation. The host may classify from structured application intent, a model decision, or both. A classification decision is not guaranteed correct; dependency expansion is deterministic after selection.

**Standard skills.** Register the skill entry points and directories listed in this repository's `package.json` Pi resource metadata in Pi's resource settings. Pi advertises names/descriptions and the model reads the selected entrypoint and its references. This path is portable but does not guarantee that the model selects or reads everything required. It does not provide the integrated host's loading guarantees.

Ship the entire repository as one unit. Domain references and shared foundations intentionally live outside individual skill folders; copying one skill directory alone is unsupported.

## Resolver interface

Run from any working directory:

```sh
python3 /path/to/fractal/scripts/context.py --list
python3 /path/to/fractal/scripts/context.py --bundle product-ui --signal product-charts --signal chart-line
python3 /path/to/fractal/scripts/context.py --bundle product-ui --signal product-charts --signal chart-line --format markdown
```

JSON output identifies selected bundles, matching conditions, ordered unique documents, their hashes, byte counts, and the context hash. Markdown output supplies the same documents with source-path boundaries. Do not inject the complete manifest or all shared references as design context.

Signals are structured decisions, not keyword matches. For example, `charts` means the artifact actually contains a visualization being authored, not that its prose mentions a chart. Unknown bundles/signals fail rather than silently dropping guidance. Signals apply only to rules reachable from selected bundles. The resolver reports unused signals; the host must resolve a mistaken classification or select the missing bundle instead of treating unused signals as successful activation.

The host must distinguish a new deck, an edit, and explicit Figma output. Brand is independent: only explicit internal Mirror Physics use or explicit Blueprint selection activates that profile. Tool availability cannot select format or brand. Unsupported formats require an explicit limitation, not a renamed output.

## During a run

1. Pin this content checkout/release; record that revision separately from the resolved bundle’s context hash.
2. Select the initial bundles and relevant signals before design work begins. Establish whether interactive surfaces belong to Axon product UI or another domain; retain that choice per app/route/region. Ask the user when context cannot resolve it. Button variant meanings remain fixed across domains.
3. Resolve the full required dependency closure and inject each document once. Do not truncate required guidance to fit; narrow the task or use a larger context budget.
4. When the work gains a new artifact or behavior, resolve again and supply newly required documents before that work. Keep stable document IDs and hashes to deduplicate.
5. Retain active bundles, signals, surface classification, profile, content revision, and context hash as host state. After compaction or a model switch, ensure required documents remain present or reload them; a conversation summary alone is insufficient.
6. Record actual delivered document IDs and hashes for evaluation. Planned reads are not proof that context reached the model.

Rules cannot guarantee model compliance. Use the same canonical guidance for every model and evaluate selection, context delivery, and output behavior separately. Keep model-specific prompt adaptation in the host unless repeated evidence supports a design-content change.

## Tool and asset boundary

Fractal does not assume Codex tools, a particular image model, Figma credentials, shell availability, or a specific provider SDK. Discover capabilities in the actual environment. The host can read/render these static files without granting a shell to the model. Executable helpers and binary assets are resources, never automatically injected instructions.

Use installed `fractal-ui` and `fractal-icons` package APIs. Do not replace their component implementations with prose-derived copies. Fractal owns the canonical source assets and tokens.

## Validation before adoption

In `fractal-testing`, exercise positive, negative, multi-artifact, scope-change, compaction, and model-switch cases across the intended models. Measure required-document coverage, unnecessary loading, design-rule compliance, and final artifact quality. A structural manifest check cannot establish visual quality or prove automatic selection reliability.

Official Pi references (checked 2026-10-20):
- https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md
- https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/sdk.md

Check the installed Pi fork/version before wiring its resource loader or context lifecycle. This resolver deliberately has no dependency on a volatile SDK signature.

The reference resolver requires Python 3.10 or newer. It can run in the host process environment; models do not need Python or shell access. Pi package registration advertises skills only: it does not by itself inject core/routing or implement domain-first activation.

## Instruction-file discovery belongs to the host

Pi’s standard coding-agent loader discovers repository context files such as `AGENTS.md` independently of which model it uses. A custom Pi-based application can replace or disable that loading behavior. Registering this package does not make its repository-maintenance `AGENTS.md` the consumer’s startup prompt.

For the integrated path, explicitly deliver the root `SKILL.md` and `core.md` for design-task selection, then only the resolved domain/task context. Do not depend on incidental discovery of files inside an installed package. Keep this delivery contract when switching models.

For chart work, classify the data purpose as well as the surrounding artifact: `product-charts` selects operational/business defaults, `scientific-charts` selects scientific guidance. `charts` alone loads common fundamentals and does not select a palette. Use both profiles only for distinct plot scopes in a mixed artifact; scientific data does not inherit product status colors.
