---
name: flash-orchestrator-setup-pi
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as the PRIMARY model in Pi — the selected main session itself runs on Flash, with project-scoped primary selection and compaction. Covers the named `teralor-flash` provider in models.json, secure TERALOR_API_KEY interpolation, project trust, the corrected budget rule with reserveTokens, fresh-session activation and one real marker-read verification. Unlike the Pi executor recipe (an external worker), this DOES change the selected model/provider — and it is NOT delegation. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires a Pi coding-agent install (verify the installed version's syntax before applying), Bash (Linux/macOS/WSL) or native Windows PowerShell as noted, a trusted target project, and network access to https://api.teralor.com. No Hermes dependency, no subagent/extension installation, no global default changes.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash PRIMARY setup — Pi (provider + project primary selection)

Run this skill only on an explicit user request to make Flash the primary orchestrator model in Pi. Reviewing or downloading it is not consent: present a concise plan, then act. The explicit setup request itself authorizes the scoped primary changes below — do not stop for a separate approval per already-authorized edit — while reading or downloading this skill authorizes nothing. Still pause for: software installation, missing secure credentials, project trust, name collisions or changes this task does not own, and any metered smoke test outside the authorization. PRIMARY means the newly selected main session itself runs on Flash. Unlike the Pi executor recipe (a separate Hermes worker driven from Pi's shell that changes no Pi files), this route DOES change Pi's selected model/provider and the chosen project's compaction settings — and it still must not install delegation/subagent extensions or preserve an old primary.

## 1. Protected scope (never modified)

- Pi's GLOBAL startup defaults (other providers, the global default provider/model), every other project's `.pi/settings.json`, existing skills and skill arrays, and any existing Hermes worker profile — all untouched.
- Task-owned additions only: the `teralor-flash` provider block in the actual global model registry, the owned keys (`defaultProvider`, `defaultModel`, `compaction`) in the ONE chosen project's `.pi/settings.json`, the canonical `flash-executor` skill plus its owned local binding, and this optional setup skill.
- If the user wants a different scope (e.g. a global default switch), confirm that explicitly first — the default here is project-scoped.

## 2. Discovery first

1. Detect the actual host OS/shell. Commands below are Bash (Linux/macOS/WSL). On native Windows use PowerShell equivalents; do not blindly run Bash snippets in PowerShell.
2. Verify the installed version: `pi --version`, and recheck the installed build's docs/source for the syntax below before applying (this skill is pinned to upstream documentation evidence, not a claim that your exact build was exercised). Locate the real paths: model registry `~/.pi/agent/models.json` (the agent root moves with `PI_CODING_AGENT_DIR`), global settings `<agent-dir>/settings.json`, project settings `<project>/.pi/settings.json`. There is no project-local `.pi/models.json` — do not invent one.
3. Pi docs: models https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md , settings https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/settings.md , skills https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md . Installing Pi needs the user's approval; never execute a remote installer blindly or make a purchase.

## 3. Inspect-before-write plan

- PROJECT TRUST is material: untrusted project settings and skills are IGNORED, and noninteractive modes default to ignoring them without saved trust. Review the project's resources with the user, have them trust the selected project through the supported UI, then restart. Never set a global always-trust option and never add an approval-bypass flag as a convenience.
- Collision-check the provider name: inspect `~/.pi/agent/models.json` first (leaf reads of provider names/baseUrls — never the whole auth-bearing file into model-visible output). Reuse `teralor-flash` only if an identical owned block already exists; otherwise choose a distinct name and substitute the ACTUAL chosen name in EVERY place below (registry, project settings, launch command, verification) — never mix names. Never adopt built-in provider names.
- Timestamp backups (exclusive names, original permissions, 0600 for secret-bearing) of every file you modify; deep-merge only the owned keys; reject malformed JSON; do not follow unexpected symlinks; reruns stay idempotent.
- Rollback: record owned additions; remove exactly those keys/files after checking for later edits, restoring backups only when the current file still matches the post-setup state. Never a global settings reset or force flags.

## 4. Secure TERALOR_API_KEY

- In `models.json`, `"$TERALOR_API_KEY"` (or `${TERALOR_API_KEY}`) interpolates from the environment; plain `TERALOR_API_KEY` without `$` is a LITERAL, not a lookup, and a missing variable leaves the value unresolved. Do not use `!command` interpolation unless the user separately approves a reviewed secret-manager command — that syntax executes shell code.
- Pi does not load `.env` for you: export the key securely in the launch environment of the actual Pi process. Never the key value in chat, prompts, argv, URLs, project files, Git, config literals or logs; print only set/missing metadata.
- If no key exists for this environment, pause for secure customer entry; never guess or borrow credentials.

## 5. Verify the target API before configuring

- Target: `https://api.teralor.com/v1`, Chat Completions, canonical model ID `Flash` — always send the canonical `Flash` ID in requests (the backend canonicalizes case-insensitive flash requests; the canonical ID is the safe choice everywhere).
- Run an authenticated `GET /v1/models` with the customer key and require exactly one unambiguous `Flash` row with `capabilities.tools: true` (this primary uses tools). Stop on 401, missing model, or ambiguity; no fallback provider/model.
- Existing account only: no purchases or quota resets; ask before any metered smoke test not already authorized.

## 6. Budget validation (corrected rule)

Published ceilings (not additive): total C=262144, input I=262144, output ceiling 131072. From authenticated `/v1/models` metadata require `context_length`, `max_input_tokens` and `max_output_tokens` to be positive integers. Compute:

```text
C = min(262144, advertised context_length)
I = min(262144, advertised max_input_tokens)
O = min(32768, advertised max_output_tokens, floor(C/2))
reject if C < 2 or O is not a positive integer
W = min(C, I + O)        # model contextWindow to configure
P = W - O                # prompt room, <= I; require P > 0
T = floor(P * 3 / 4)     # compaction trigger; require T > 0
R = W - T                # Pi project reserveTokens; must be positive
```

A lower advertised output capacity LOWERS O instead of rejecting the 32768 default. Canonical defaults verified: O=32768 → W=262144, P=229376, T=172032, R=90112. If discovery is missing/unverifiable, any field is invalid, or no positive budget exists, STOP before applying any budget setting — `BLOCKED`/`MANUAL_STEP_REQUIRED`; never fall back to template capacities. Two Pi truths: the model's `maxTokens` default output is further clamped to `contextWindow − estimated context − 4096` (minimum 1), so the wire allowance can be below O; and compaction fires when `contextTokens > contextWindow − reserveTokens` — so R places the trigger ABOVE T, not exactly at it. Preserve a safe existing `keepRecentTokens`; if lowered capacities make the retained history infeasible, stop and reconcile rather than blindly keeping 20000.

## 7. Merge the provider and the project primary selection

Merge this provider into `~/.pi/agent/models.json`, preserving all existing providers and substituting discovered W/O:

```json
{
  "providers": {
    "teralor-flash": {
      "baseUrl": "https://api.teralor.com/v1",
      "api": "openai-completions",
      "apiKey": "$TERALOR_API_KEY",
      "authHeader": true,
      "models": [{
        "id": "Flash",
        "name": "Teralor Flash",
        "input": ["text"],
        "reasoning": false,
        "contextWindow": 262144,
        "maxTokens": 32768,
        "compat": {
          "maxTokensField": "max_tokens",
          "supportsDeveloperRole": false,
          "supportsReasoningEffort": false,
          "supportsStore": false
        }
      }]
    }
  }
}
```

`openai-completions` means Chat Completions (not Responses or legacy completions); `compat.maxTokensField` selects `max_tokens` on the wire; `reasoning: false` plus disabled effort controls only avoid optional client reasoning fields — it does not claim Flash cannot reason.

Then deep-merge the PROJECT primary keys into the chosen trusted project's `.pi/settings.json`, preserving every other setting (a matching example ships at `setup/pi-settings.json` beside the executor examples):

```json
{
  "defaultProvider": "teralor-flash",
  "defaultModel": "Flash",
  "compaction": {
    "enabled": true,
    "reserveTokens": 90112,
    "keepRecentTokens": 20000
  }
}
```

Substitute R (and reconcile `keepRecentTokens` per section 6). IMPORTANT scope trap: the model picker's Ctrl+S (`setDefaultModelAndProvider`) writes GLOBAL settings — never use it to persist a project-only primary selection; edit this project file instead.

## 8. Install Flash and bind it to this primary session

Download the canonical Flash execution skill from `https://teralor.com/assets/neural/skills/flash-executor/SKILL.md` into a task-owned temporary file. Require HTTP success, valid Agent Skills frontmatter with `name: flash-executor` and a nonempty `description`, and no HTML/error body; a failed or truncated download stops setup before installation. Install at `.pi/skills/flash-executor/SKILL.md` only after resolving the actual host/path, checking for symlinks and collisions, and backing up any owned target. Reuse identical bytes; preserve differing/customized skills and stop for reconciliation, never overwrite user additions. Compare the installed canonical body with the validated download before appending the local binding. Keep the body as the single execution procedure, not a copied procedure inside onboarding.

Install in the selected trusted project, not another project or global skill array. Restart Pi from that project, confirm the skill is listed, then invoke `/skill:flash-executor`. Keep the project primary selection from section 7; loading instructions does not select a provider. Do not install delegation extensions.

Append one local routing block after the canonical body, substituting all actual names. On rerun replace only this unambiguous owned block; duplicated/unowned markers mean stop. Preserve surrounding customized text and unrelated skills/config:

```text
<!-- BEGIN FLASH PRIMARY LOCAL BINDING -->
coordinator=Pi primary session; teralor-flash / Flash (substitute the actual provider)
execution=Use this primary session's configured tools for bounded execution. Concurrent workers require a separately configured and verified Flash route; this setup does not add delegation or switch models. Without that capability, execute serially and report it.
<!-- END FLASH PRIMARY LOCAL BINDING -->
```

Confirm discovery and successful loading in the fresh target harness, not merely file existence. Record the download digest, actual installed path, local binding and any deliberate environment-origin adjustment. `READY` requires this check AND the primary-session marker verification below. Skill availability is not proof of concurrent worker support.

This onboarding installs Flash as the separate execution skill; installing this setup skill itself remains optional. Optionally install THIS skill (validate first: HTTP success, frontmatter `name: flash-orchestrator-setup-pi`, nonempty `description`, no HTML/error body) at `.pi/skills/flash-orchestrator-setup-pi/SKILL.md` in the trusted project (project skills work only in a trusted project), or `<agent-dir>/skills/…` globally, or pass it explicitly with `--skill <path>`. Invoke with `/skill:flash-orchestrator-setup-pi`. Preserve existing skill arrays and customizations; no worker/delegation binding belongs in this skill.

## 9. Fresh-session activation and real bounded verification

1. `/model` reloads `models.json` for inspection; explicit selection is `teralor-flash/Flash`. Launch FRESH from the trusted project without `--continue`/`--resume` or a reused session: `pi --provider teralor-flash --model Flash`. Verify BOTH the configured project startup selection and the effective selected provider/model shown in the session — not just the saved files.
2. One authorized marker read through the REAL Flash PRIMARY tool loop: BEFORE the smoke, the trusted setup controller/customer — OUTSIDE the fresh Flash session — writes a fresh nonce into a task-owned temp file; the tested model never generates its own supposedly hidden challenge. Only the file's real path enters the tested session — never the nonce contents, and never a prior conversation containing them. Ask once: "Read the file at <real path> using your file-reading tool and return its exact contents. Do not modify files or perform other tasks." Bounded scripted form from the trusted project: `pi --provider teralor-flash --model Flash --tools read --no-session --mode json -p "<prompt with the real path>"`, with wall time bounded externally by supported local process tooling (do not invent Pi flags).
3. Mechanically compare the final response with the expected bytes AND require an actual file-read tool event for that path plus independent nonsecret evidence of the selected provider/model and effective budgets. A `/models` 200, a saved config, a startup label or a model self-claim is NOT success. A smoke task may take several sampling calls.
4. Confirm Pi's global defaults, other projects and any unrelated providers/workers are unchanged; remove only the owned marker fixture after the process ends; keep sanitized failure evidence. Never reroute to another model or mark READY without this check.

## 10. Final report

Report: harness/version, actual registry/project settings/skill paths, provider/model, advertised versus chosen C/I/O/W/P/T/R, backup and rollback locations, checks run and checks NOT run, customer actions (trust, key entry, restart), and status:

- `READY` — only after the real primary-session marker verification succeeded with verified limits and project trust confirmed.
- `BLOCKED` — failed authentication, absent/ambiguous `Flash`, missing tool capability, invalid/unverifiable capacities, unresolved collision, untrusted project you may not widen, or failed marker verification; describe evidence.
- `MANUAL_STEP_REQUIRED` — secure key entry, project trust, install/restart approval or capacity metadata still pending; name the exact pending step honestly.