Orchestrator · primary mode

Flash as the primary model

Make Flash the model that plans the work, chooses tools and reviews results. Start with the provider, API key and token budget — the per-harness panels below are complete on their own.

One model, one loop

Flash chooses tool calls; your harness executes them and returns the results to Flash. To keep your current model in charge and delegate only selected tasks, use executor mode.

Your goalOne task, stated outcome

Flash as primary modelChooses tools and reviews their resultsProvider, key and budgets configured first

Read & researchFiles, docs, sourcesExecuted by the harness

Edit & runScoped changes, commandsExecuted by the harness

VerifyChecks inside one loopExecuted by the harness

Reviewed resultYou stay the reviewer

Setup facts

Connection and token budget

Base URL: https://api.teralor.com/v1
Model: Flash
Transport: Chat Completions (POST /v1/chat/completions)

Flash's current limits: 262,144 total context, up to 262,144 input and 131,072 output tokens. These ceilings are not additive: complete prompt tokens + reserved output ≤ 262,144. Input includes system instructions, tools, skills, history and new messages.

Check GET /v1/models with your own key before setup. Use the returned context_length, max_input_tokens and max_output_tokens if lower. A 401means credential or access setup must be fixed. Start with one worker; increase only within your account's verified concurrency allowance.

The downloadable Hermes and Pi example configs request 32,768 output tokens and compact at 172,032 prompt tokens. These are recommended working budgets for those configs, not API limits and not a setting supplied by ZCode or Cursor, which expose no user-facing compaction threshold. Omitting max_tokens reserves the full output ceiling instead, leaving only 131,072 prompt tokens; use a 98,304 compaction trigger for that policy.

One window. Shared by input and output.

262,144 total tokens · recommended working allocation

Prompt ceiling: 229,376
Output reserved: 32,768
Compact near (Hermes/Pi configs): 172,032

Compaction leaves room for the next message and tool results. It is a history-management trigger, not a hard input limit; a single oversized message can still be rejected.

Handle the key securely first

Export your customer key in the shell that launches the harness. Keep it out of config examples, prompts and Git; use your secret manager for persistent service setup. Use a key for the environment shown above. Downloaded configs are canonical public-API examples.

Secure key setup (Bash — Linux, macOS, WSL)

# Bash (Linux / macOS / WSL) — prompt once, keep the key out of history
read -r -s -p 'Teralor API key: ' TERALOR_API_KEY; printf '\n'; export TERALOR_API_KEY

Confirm YOUR access and limits (run before configuring anything else)

# Metadata check with YOUR customer key (process substitution keeps it out of argv)
curl -fsS --header @<(printf 'Authorization: Bearer %s\n' "$TERALOR_API_KEY") https://api.teralor.com/v1/models

Standalone skill

Flash skill

Already configured? Download or copy the Flash skill on its own. The per-harness setup panels below configure your role and install this same skill — you never need the setup package just to carry the skill between machines or share it with a teammate.

Download skill

View skill instructions

---
name: flash-executor
description: Use when executing tasks with Teralor Flash, including independently verifiable coding, research, document and batch outcomes. Preserve the coordinator and use bounded, dependency-ready parallel work.
compatibility: Requires configured, authorized Flash access and supported harness tools. Concurrency requires verified account headroom and an actual concurrent dispatch mechanism.
metadata:
  author: Teralor
  version: "2.0.0"
---

# Flash

Keep the current coordinator model, whether Flash or another model. The coordinator owns decisions, contracts, scheduling and acceptance; Flash executes settled outcomes. Optimize verified completion, not worker count.

## Check readiness

Use the installed harness binding and verify nonsecret route/model evidence; a worker called Flash is not routing proof. If access, budgets or binding are missing, stop and use the harness-specific [Executor onboarding](https://teralor.com/executor) or [Orchestrator onboarding](https://teralor.com/orchestrator). This skill does not configure providers or switch the primary model. Keep credentials out of prompts and artifacts. Raw completions cannot execute tools; treat their proposed patches as unexecuted until the trusted harness validates and applies them.

## Decompose by verifiable outcome

Inspect the inputs and acceptance criteria. Settle shared interfaces first, then split only where each result can be checked independently: a module against a fixed interface, a document batch with distinct outputs, or a research question with its own sources. Keep dependent work queued. For a trivial or serial task, use one bounded execution; never manufacture sixteen tasks.

Maintain a compact ledger: task ID, dependencies, owner, artifact and state (`ready`, `running`, `produced`, `verified`, `failed`, `uncertain`, `blocked`). Only verified artifacts satisfy dependencies.

Give each worker this compact contract, not the full conversation:

- **Outcome:** task ID, observable result and expected artifact/count.
- **Inputs:** baseline, relevant paths/excerpts, settled interfaces and verified dependencies.
- **Ownership:** writable paths, isolated workspace, invariants, non-goals and permissions.
- **Acceptance:** runnable checks, return format, budgets and stop conditions.
- **Return:** actual artifacts/patch, changed paths, checks really run, failures and uncertainty.

For code, require a failing regression/reproducer before the fix where applicable and focused passing checks afterward. Workers must not recursively delegate, change global configuration, publish or broaden permissions.

## Run a replenishing queue

When the account allowance is verified as **16 concurrent requests**, dispatch up to that allowance—not sixteen workers unconditionally. Bound active requests by remaining account headroom, harness/tool limits, resource budget and independently ready work. Count other clients and the coordinator's own Flash requests. A worker can emit multiple requests; request capacity is not a worker entitlement. Unknown allowance: use at most one authorized request while resolving it; zero headroom: queue. Server admission remains authoritative.

Launch independent ready jobs together through supported asynchronous/batch tools, rather than awaiting each before starting the next. Consume completions, verify artifacts and replenish newly ready work without waiting for unrelated slow jobs. Use completion notifications or bounded waits; avoid duplicate submissions.

Concurrent writers require separate workspaces and explicit file ownership. Serialize shared interfaces, databases, ports and remote mutations. Without isolation, parallelize read-only proposals and keep one writer. Without concurrent tools, execute serially and say so.

## Verify, repair, integrate

Inspect actual bytes, scope, baseline compatibility and evidence; reconcile requested IDs against outputs for missing/duplicate items. Run combined integration checks after accepting individual artifacts. Never substitute worker confidence for results.

Repair only the failed slice, once, with concrete failure evidence; retain unaffected verified work. Authentication failure stops dispatch. Rate limits reduce pressure with bounded, safe retries. Interrupted or unknown dispatch stays uncertain until reconciled or confirmed cancelled—never assume its slot/workspace is free or replay blindly.

Report delivered artifacts, actual routing and observed concurrency, checks and remaining blockers. Claim neither parallel execution nor speedup without measured evidence.

Per-harness setup

Set up your harness

Hermes, Pi, ZCode and Cursor support primary setups through Chat Completions or documented BYOK. Codex and Claude Code support Flash as an executor only. Or copy one setup prompt: your agent checks prerequisites and guides the supported configuration. Secure key entry and GUI-only steps may require you; completion is reported only after verification. Each supported setup configures the primary role and installs the Flash skill, so already configured users can just download or copy that skill alone from the standalone section above.

Harness

Manual copy: Hermes primary setup instructions

Download the Hermes setup skill

Set up and verify Teralor Flash as the PRIMARY model in Hermes, following the complete instructions below. PRIMARY means the new selected main session itself runs on Flash: Flash plans, chooses tools and reviews results in that session. Make exactly the primary-mode changes the instructions specify and nothing else — preserve my other profiles, providers, projects, global defaults, executor/delegation settings and all saved credentials; never clone a parent profile and never silently broaden permissions. The setup must also install the canonical Flash skill (identifier flash-executor) at the actual skill path the instructions name, validating the download and stopping on any conflict instead of overwriting existing customizations; the primary model stays Flash and no new delegation, provider or subagent settings are added — the skill's primary tools stay usable serially, and dispatch concurrent workers only when my harness supports it and that support is verified. Pause for me whenever secure credential entry, installation approval, a GUI step, a capacity/name conflict or a metered test needs my action, and only report READY after real verification through the new Flash primary session succeeds AND the installed Flash skill is discoverable and loads through the documented harness instruction.

---
name: flash-orchestrator-setup-hermes
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as the PRIMARY model of a Hermes session — Flash itself plans, chooses tools and reviews results. Covers a collision-checked independent `flash` profile (never a clone), the named `teralor-flash` provider, secure TERALOR_API_KEY handling, authenticated /v1/models discovery, the corrected budget rule, fresh-session activation and one real marker-read verification. This is NOT delegation/executor configuration. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires Hermes 0.21 or compatible, Bash (Linux/macOS/WSL) or native Windows PowerShell as noted, and network access to https://api.teralor.com. Creates a new independent profile; never clones or modifies an existing profile's model, and never changes global defaults.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash PRIMARY setup — Hermes (separate primary profile)

Run this skill only on an explicit user request to make Flash the primary orchestrator model in Hermes. 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 (secure key entry may require the customer), name collisions or changes this task does not own, and any metered smoke test outside the authorization. PRIMARY means the NEW selected main session itself runs on Flash — Flash plans, chooses tools and reviews results. This is NOT the delegation/executor route: do not add `delegation` keys, do not touch any existing orchestrator profile's model, and do not launch an external worker.

## 1. Protected scope (never modified)

- Every existing Hermes profile, provider, identity, memory, tool, plugin, approval and sandbox setting — a new profile is created alongside them, never cloned from or replacing them. New profiles keep separate state and do not inherit the old orchestrator's identity; disclose this.
- Global defaults and any other profile's `model`, `context`, `compression`, fallback, cron or worker settings.
- Task-owned additions only: the new collision-checked profile (default example name `flash`), the `providers.teralor-flash` block, the top-level `model`/`context`/`compression` keys inside THAT new profile's config, the canonical `flash-executor` skill plus its owned local binding, and this optional setup skill under the new profile.
- If the user instead asks to switch their EXISTING orchestrator profile, confirm that exact target and apply an exact scoped merge preserving its non-model state — never silently replace it with a blank profile.

## 2. Discovery first

1. Detect the actual host OS/shell. Commands below are Bash (Linux/macOS/WSL). On native Windows use PowerShell equivalents and the official `install.ps1`; do not blindly run Bash snippets in PowerShell.
2. Check what exists: `hermes --version` (0.21 or compatible), `hermes profile list`. Resolve the real Hermes root/profile paths through the CLI (`hermes -p <name> config path`) — the default profile lives under `~/.hermes`, named profiles under `~/.hermes/profiles/<name>`, and a custom `HERMES_HOME` relocates everything; never blindly write `~/.hermes/profiles/default`.
3. Hermes install docs: https://hermes-agent.nousresearch.com/docs/getting-started/installation/ (CLI installer https://hermes-agent.nousresearch.com/install.sh; Windows native install.ps1). Installing software needs the user's approval — review the official script before running it; never execute remote code blindly or make a purchase. Profiles: https://hermes-agent.nousresearch.com/docs/user-guide/profiles/ ; providers: https://hermes-agent.nousresearch.com/docs/integrations/providers .

## 3. Inspect-before-write plan

- Collision-check the profile name: create `flash` only if absent (`hermes profile create flash --no-alias`; verify `--no-alias` in local help to avoid shell-wrapper changes). If `flash` already exists with different settings, STOP and reconcile — reuse only when it is an identical owned setup, otherwise choose a distinct name and substitute the ACTUAL chosen name in every path, command and reference below (do not blindly append a suffix in only some places).
- Before any write: read the target files/dirs you will touch; timestamp backups (exclusive timestamp/random names) of every file you modify, keeping their permissions (0600 for anything secret-bearing) and store backups privately.
- Merge only the exact owned keys with trusted local parsing; return only allowlisted nonsecret fields — never dump whole `providers`/auth blocks, environments or headers into model-visible output; reject malformed YAML; do not follow unexpected symlinks. Reruns must be idempotent — never create duplicate keys.
- Rollback: record every owned key/file added. Remove exactly those after checking for later edits by others; restore a backup only when the current file still matches the recorded post-setup version, otherwise reconcile key-by-key. Remove the whole new profile only if it remains wholly owned/unused AND deletion is authorized. Never destructive resets, force flags, broad chmod, or sudo by default.

## 4. Secure TERALOR_API_KEY

- The named provider reads its key via `key_env: TERALOR_API_KEY` — an environment-variable NAME, never a value or `$TERALOR_API_KEY`. Supply it through the environment of the process that actually launches Hermes, or a private profile `.env` (permissions 0600) that Hermes loads at startup; confirm a fresh launch sees it, not just a temporary export.
- Never the key value in chat, prompts, argv, URLs, project files, Git, config literals or logs; print only allowlisted metadata (set/missing). Do not add global `OPENAI_BASE_URL`, a literal `model.api_key`, or borrow another service's credential.
- If a blank profile is needed for private key entry, create only that collision-checked blank profile, then PAUSE for secure customer entry (`MANUAL_STEP_REQUIRED`) before any configuration.

## 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 is a tool-using primary, so tool capability is a hard gate. Stop on 401, missing model, or ambiguity. `discover_models: true` is a convenience, not a substitute for this check. No alternative model/endpoint, no silent fallback.
- Existing account only: no purchases, no 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 the authenticated `/v1/models` metadata require `context_length`, `max_input_tokens` and `max_output_tokens` to be positive integers (reject missing/null/boolean/string/fractional values). 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)        # window the client configures
P = W - O                # prompt room, <= I; require P > 0
T = floor(P * 3 / 4)     # compaction threshold cap; require T > 0
```

A lower advertised output capacity LOWERS O instead of rejecting the 32768 default; the half-capacity cap reserves at least half the total context for input at small capacities. Canonical defaults verified: C=I=262144, O=32768 → W=262144, P=229376, T=172032. If discovery is missing or unverifiable, any capacity field is invalid, or a positive safe budget is impossible, STOP before applying or using any budget setting — `BLOCKED` (or `MANUAL_STEP_REQUIRED` while waiting for metadata). Never fall back to template capacities. Prompt room includes system prompts, tool schemas, skills, history and tool output; compaction is history management, not hard admission — never market a tiny marker success as large-window certification.

## 7. Create the primary profile and merge the configuration

Create the profile only after sections 4–6 allow it (blank-profile pause included). Never `--clone`/`--clone-all`, no `profile use` global switching, no gateway/worker changes:

```bash
hermes profile list
hermes profile create flash --no-alias     # only if absent — collision-checked, independent, NOT a clone
hermes -p flash config edit                # merge the keys below; do not replace other settings
```

Merge exactly these keys into the NEW profile's `config.yaml`, substituting the discovered W/O/T values and the ACTUAL chosen provider name (example `teralor-flash`; if the name collides with a different provider, choose a distinct name and propagate it everywhere):

```yaml
providers:
  teralor-flash:
    api: https://api.teralor.com/v1
    key_env: TERALOR_API_KEY
    transport: chat_completions
    default_model: Flash
    discover_models: true
    models:
      Flash:
        context_length: 262144        # replace with discovered W
    extra_body:
      max_tokens: 32768               # replace with discovered O
model:
  provider: custom:teralor-flash
  default: Flash
context:
  engine: compressor
compression:
  enabled: true
  threshold_tokens: 172032            # replace with discovered T
```

Facts to respect: Hermes 0.21 ignores legacy `model.max_tokens`/`HERMES_MAX_TOKENS` and provider output-cap metadata — provider `extra_body.max_tokens` is the supported Chat-Completions passthrough (inspect the effective nonsecret value; request overrides can win), and it does NOT reserve output inside the compressor. `compression.threshold_tokens` is an absolute CAP on the ratio-derived threshold (built-in small-window floors may sit lower); inspect the active context engine and auxiliary compression as additional lower caps, and on an existing target never silently replace its engine or auxiliary routes. Remove only a conflicting target-owned global `model.context_length` pin if this scope authorizes it; never copy another model's pin. Leave reasoning effort unset unless the discovery explicitly supports it. Inspect fallback routing of the NEW profile only — no silent alternate-primary fallback.

## 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 `<actual-profile-home>/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.

Resolve the new profile home with `hermes -p flash config path`; the example is `~/.hermes/profiles/flash/skills/flash-executor/SKILL.md`, respecting a custom `HERMES_HOME`. Start fresh with `hermes -p flash chat -s flash-executor`, substituting the actual chosen profile. Verify the loaded skill resolves to that file; `/flash-executor` invokes it interactively. Skill loading does not select a provider.

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=Hermes primary session; custom:teralor-flash / Flash (substitute the actual provider/profile names)
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-hermes`, nonempty `description`, no HTML/error body) as `<actual-profile-home>/skills/flash-orchestrator-setup-hermes/SKILL.md` — for the example profile `~/.hermes/profiles/flash/skills/…` — or a documented explicitly configured skill location after checking trust. Installed skills invoke as `/flash-orchestrator-setup-hermes`; `chat -s <skill>` preloads a skill, not a provider. Preserve existing skills and customizations; stop on collisions.

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

1. Start a FRESH session without resume/continue — editing files does not rebuild an initialized agent: `hermes -p flash chat`. Confirm the banner/effective route, engine, window, output and threshold, not just saved YAML (leaf queries like `hermes -p flash config get model.provider` — never whole secret blocks).
2. One authorized marker read through the REAL Flash PRIMARY tool loop (never delegation): 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." A bounded scripted form: `hermes -p flash chat --oneshot --max-turns 8 -t file -q "<prompt with the real path>"` (quote argv per the actual shell; the file toolset includes write tools — read-only intent is not a sandbox, keep approvals).
3. Mechanically compare the response with the expected nonce AND require an actual file-read tool event for that path plus independent nonsecret route evidence (profile `flash`, `custom:teralor-flash`, model `Flash`, effective budgets). A `/models` 200, a saved config, a startup banner or the model self-claiming success is NOT success. The smoke may involve multiple sampling calls (tool request + final answer) — that is not one billable request.
4. Confirm every other profile and global default is unchanged; clean up only the owned marker fixture after the process ends; keep sanitized failure evidence. Never reroute to another model, add open-ended tests, or mark READY without this check.

## 10. Final report

Report: harness/version, actual profile/config paths, provider/model, advertised versus chosen C/I/O/W/P/T, backup and rollback locations, checks run and checks NOT run, customer actions performed, and status:

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

Manual prompts

Open your harness below and copy the full primary-setup prompt manually, or download its setup skill. Codex and Claude Code support Flash as an executor only — see the executor page.

Hermes — full setup prompt

Download the Hermes setup skill

Set up and verify Teralor Flash as the PRIMARY model in Hermes, following the complete instructions below. PRIMARY means the new selected main session itself runs on Flash: Flash plans, chooses tools and reviews results in that session. Make exactly the primary-mode changes the instructions specify and nothing else — preserve my other profiles, providers, projects, global defaults, executor/delegation settings and all saved credentials; never clone a parent profile and never silently broaden permissions. The setup must also install the canonical Flash skill (identifier flash-executor) at the actual skill path the instructions name, validating the download and stopping on any conflict instead of overwriting existing customizations; the primary model stays Flash and no new delegation, provider or subagent settings are added — the skill's primary tools stay usable serially, and dispatch concurrent workers only when my harness supports it and that support is verified. Pause for me whenever secure credential entry, installation approval, a GUI step, a capacity/name conflict or a metered test needs my action, and only report READY after real verification through the new Flash primary session succeeds AND the installed Flash skill is discoverable and loads through the documented harness instruction.

---
name: flash-orchestrator-setup-hermes
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as the PRIMARY model of a Hermes session — Flash itself plans, chooses tools and reviews results. Covers a collision-checked independent `flash` profile (never a clone), the named `teralor-flash` provider, secure TERALOR_API_KEY handling, authenticated /v1/models discovery, the corrected budget rule, fresh-session activation and one real marker-read verification. This is NOT delegation/executor configuration. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires Hermes 0.21 or compatible, Bash (Linux/macOS/WSL) or native Windows PowerShell as noted, and network access to https://api.teralor.com. Creates a new independent profile; never clones or modifies an existing profile's model, and never changes global defaults.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash PRIMARY setup — Hermes (separate primary profile)

Run this skill only on an explicit user request to make Flash the primary orchestrator model in Hermes. 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 (secure key entry may require the customer), name collisions or changes this task does not own, and any metered smoke test outside the authorization. PRIMARY means the NEW selected main session itself runs on Flash — Flash plans, chooses tools and reviews results. This is NOT the delegation/executor route: do not add `delegation` keys, do not touch any existing orchestrator profile's model, and do not launch an external worker.

## 1. Protected scope (never modified)

- Every existing Hermes profile, provider, identity, memory, tool, plugin, approval and sandbox setting — a new profile is created alongside them, never cloned from or replacing them. New profiles keep separate state and do not inherit the old orchestrator's identity; disclose this.
- Global defaults and any other profile's `model`, `context`, `compression`, fallback, cron or worker settings.
- Task-owned additions only: the new collision-checked profile (default example name `flash`), the `providers.teralor-flash` block, the top-level `model`/`context`/`compression` keys inside THAT new profile's config, the canonical `flash-executor` skill plus its owned local binding, and this optional setup skill under the new profile.
- If the user instead asks to switch their EXISTING orchestrator profile, confirm that exact target and apply an exact scoped merge preserving its non-model state — never silently replace it with a blank profile.

## 2. Discovery first

1. Detect the actual host OS/shell. Commands below are Bash (Linux/macOS/WSL). On native Windows use PowerShell equivalents and the official `install.ps1`; do not blindly run Bash snippets in PowerShell.
2. Check what exists: `hermes --version` (0.21 or compatible), `hermes profile list`. Resolve the real Hermes root/profile paths through the CLI (`hermes -p <name> config path`) — the default profile lives under `~/.hermes`, named profiles under `~/.hermes/profiles/<name>`, and a custom `HERMES_HOME` relocates everything; never blindly write `~/.hermes/profiles/default`.
3. Hermes install docs: https://hermes-agent.nousresearch.com/docs/getting-started/installation/ (CLI installer https://hermes-agent.nousresearch.com/install.sh; Windows native install.ps1). Installing software needs the user's approval — review the official script before running it; never execute remote code blindly or make a purchase. Profiles: https://hermes-agent.nousresearch.com/docs/user-guide/profiles/ ; providers: https://hermes-agent.nousresearch.com/docs/integrations/providers .

## 3. Inspect-before-write plan

- Collision-check the profile name: create `flash` only if absent (`hermes profile create flash --no-alias`; verify `--no-alias` in local help to avoid shell-wrapper changes). If `flash` already exists with different settings, STOP and reconcile — reuse only when it is an identical owned setup, otherwise choose a distinct name and substitute the ACTUAL chosen name in every path, command and reference below (do not blindly append a suffix in only some places).
- Before any write: read the target files/dirs you will touch; timestamp backups (exclusive timestamp/random names) of every file you modify, keeping their permissions (0600 for anything secret-bearing) and store backups privately.
- Merge only the exact owned keys with trusted local parsing; return only allowlisted nonsecret fields — never dump whole `providers`/auth blocks, environments or headers into model-visible output; reject malformed YAML; do not follow unexpected symlinks. Reruns must be idempotent — never create duplicate keys.
- Rollback: record every owned key/file added. Remove exactly those after checking for later edits by others; restore a backup only when the current file still matches the recorded post-setup version, otherwise reconcile key-by-key. Remove the whole new profile only if it remains wholly owned/unused AND deletion is authorized. Never destructive resets, force flags, broad chmod, or sudo by default.

## 4. Secure TERALOR_API_KEY

- The named provider reads its key via `key_env: TERALOR_API_KEY` — an environment-variable NAME, never a value or `$TERALOR_API_KEY`. Supply it through the environment of the process that actually launches Hermes, or a private profile `.env` (permissions 0600) that Hermes loads at startup; confirm a fresh launch sees it, not just a temporary export.
- Never the key value in chat, prompts, argv, URLs, project files, Git, config literals or logs; print only allowlisted metadata (set/missing). Do not add global `OPENAI_BASE_URL`, a literal `model.api_key`, or borrow another service's credential.
- If a blank profile is needed for private key entry, create only that collision-checked blank profile, then PAUSE for secure customer entry (`MANUAL_STEP_REQUIRED`) before any configuration.

## 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 is a tool-using primary, so tool capability is a hard gate. Stop on 401, missing model, or ambiguity. `discover_models: true` is a convenience, not a substitute for this check. No alternative model/endpoint, no silent fallback.
- Existing account only: no purchases, no 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 the authenticated `/v1/models` metadata require `context_length`, `max_input_tokens` and `max_output_tokens` to be positive integers (reject missing/null/boolean/string/fractional values). 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)        # window the client configures
P = W - O                # prompt room, <= I; require P > 0
T = floor(P * 3 / 4)     # compaction threshold cap; require T > 0
```

A lower advertised output capacity LOWERS O instead of rejecting the 32768 default; the half-capacity cap reserves at least half the total context for input at small capacities. Canonical defaults verified: C=I=262144, O=32768 → W=262144, P=229376, T=172032. If discovery is missing or unverifiable, any capacity field is invalid, or a positive safe budget is impossible, STOP before applying or using any budget setting — `BLOCKED` (or `MANUAL_STEP_REQUIRED` while waiting for metadata). Never fall back to template capacities. Prompt room includes system prompts, tool schemas, skills, history and tool output; compaction is history management, not hard admission — never market a tiny marker success as large-window certification.

## 7. Create the primary profile and merge the configuration

Create the profile only after sections 4–6 allow it (blank-profile pause included). Never `--clone`/`--clone-all`, no `profile use` global switching, no gateway/worker changes:

```bash
hermes profile list
hermes profile create flash --no-alias     # only if absent — collision-checked, independent, NOT a clone
hermes -p flash config edit                # merge the keys below; do not replace other settings
```

Merge exactly these keys into the NEW profile's `config.yaml`, substituting the discovered W/O/T values and the ACTUAL chosen provider name (example `teralor-flash`; if the name collides with a different provider, choose a distinct name and propagate it everywhere):

```yaml
providers:
  teralor-flash:
    api: https://api.teralor.com/v1
    key_env: TERALOR_API_KEY
    transport: chat_completions
    default_model: Flash
    discover_models: true
    models:
      Flash:
        context_length: 262144        # replace with discovered W
    extra_body:
      max_tokens: 32768               # replace with discovered O
model:
  provider: custom:teralor-flash
  default: Flash
context:
  engine: compressor
compression:
  enabled: true
  threshold_tokens: 172032            # replace with discovered T
```

Facts to respect: Hermes 0.21 ignores legacy `model.max_tokens`/`HERMES_MAX_TOKENS` and provider output-cap metadata — provider `extra_body.max_tokens` is the supported Chat-Completions passthrough (inspect the effective nonsecret value; request overrides can win), and it does NOT reserve output inside the compressor. `compression.threshold_tokens` is an absolute CAP on the ratio-derived threshold (built-in small-window floors may sit lower); inspect the active context engine and auxiliary compression as additional lower caps, and on an existing target never silently replace its engine or auxiliary routes. Remove only a conflicting target-owned global `model.context_length` pin if this scope authorizes it; never copy another model's pin. Leave reasoning effort unset unless the discovery explicitly supports it. Inspect fallback routing of the NEW profile only — no silent alternate-primary fallback.

## 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 `<actual-profile-home>/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.

Resolve the new profile home with `hermes -p flash config path`; the example is `~/.hermes/profiles/flash/skills/flash-executor/SKILL.md`, respecting a custom `HERMES_HOME`. Start fresh with `hermes -p flash chat -s flash-executor`, substituting the actual chosen profile. Verify the loaded skill resolves to that file; `/flash-executor` invokes it interactively. Skill loading does not select a provider.

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=Hermes primary session; custom:teralor-flash / Flash (substitute the actual provider/profile names)
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-hermes`, nonempty `description`, no HTML/error body) as `<actual-profile-home>/skills/flash-orchestrator-setup-hermes/SKILL.md` — for the example profile `~/.hermes/profiles/flash/skills/…` — or a documented explicitly configured skill location after checking trust. Installed skills invoke as `/flash-orchestrator-setup-hermes`; `chat -s <skill>` preloads a skill, not a provider. Preserve existing skills and customizations; stop on collisions.

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

1. Start a FRESH session without resume/continue — editing files does not rebuild an initialized agent: `hermes -p flash chat`. Confirm the banner/effective route, engine, window, output and threshold, not just saved YAML (leaf queries like `hermes -p flash config get model.provider` — never whole secret blocks).
2. One authorized marker read through the REAL Flash PRIMARY tool loop (never delegation): 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." A bounded scripted form: `hermes -p flash chat --oneshot --max-turns 8 -t file -q "<prompt with the real path>"` (quote argv per the actual shell; the file toolset includes write tools — read-only intent is not a sandbox, keep approvals).
3. Mechanically compare the response with the expected nonce AND require an actual file-read tool event for that path plus independent nonsecret route evidence (profile `flash`, `custom:teralor-flash`, model `Flash`, effective budgets). A `/models` 200, a saved config, a startup banner or the model self-claiming success is NOT success. The smoke may involve multiple sampling calls (tool request + final answer) — that is not one billable request.
4. Confirm every other profile and global default is unchanged; clean up only the owned marker fixture after the process ends; keep sanitized failure evidence. Never reroute to another model, add open-ended tests, or mark READY without this check.

## 10. Final report

Report: harness/version, actual profile/config paths, provider/model, advertised versus chosen C/I/O/W/P/T, backup and rollback locations, checks run and checks NOT run, customer actions performed, and status:

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

Pi — full setup prompt

Download the Pi setup skill

Set up and verify Teralor Flash as the PRIMARY model in Pi, following the complete instructions below. PRIMARY means the new selected main session itself runs on Flash: Flash plans, chooses tools and reviews results in that session. Make exactly the primary-mode changes the instructions specify and nothing else — preserve my other profiles, providers, projects, global defaults, executor/delegation settings and all saved credentials; never clone a parent profile and never silently broaden permissions. The setup must also install the canonical Flash skill (identifier flash-executor) at the actual skill path the instructions name, validating the download and stopping on any conflict instead of overwriting existing customizations; the primary model stays Flash and no new delegation, provider or subagent settings are added — the skill's primary tools stay usable serially, and dispatch concurrent workers only when my harness supports it and that support is verified. Pause for me whenever secure credential entry, installation approval, a GUI step, a capacity/name conflict or a metered test needs my action, and only report READY after real verification through the new Flash primary session succeeds AND the installed Flash skill is discoverable and loads through the documented harness instruction.

---
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.

ZCode — full setup prompt

Download the ZCode setup skill

Set up and verify Teralor Flash as the PRIMARY model in ZCode, following the complete instructions below. PRIMARY means the new selected main session itself runs on Flash: Flash plans, chooses tools and reviews results in that session. Make exactly the primary-mode changes the instructions specify and nothing else — preserve my other profiles, providers, projects, global defaults, executor/delegation settings and all saved credentials; never clone a parent profile and never silently broaden permissions. The setup must also install the canonical Flash skill (identifier flash-executor) at the actual skill path the instructions name, validating the download and stopping on any conflict instead of overwriting existing customizations; the primary model stays Flash and no new delegation, provider or subagent settings are added — the skill's primary tools stay usable serially, and dispatch concurrent workers only when my harness supports it and that support is verified. Pause for me whenever secure credential entry, installation approval, a GUI step, a capacity/name conflict or a metered test needs my action, and only report READY after real verification through the new Flash primary session succeeds AND the installed Flash skill is discoverable and loads through the documented harness instruction.

---
name: flash-orchestrator-setup-zcode
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as the PRIMARY chat model in ZCode — a new task/chat selects Flash itself. Covers the documented GUI provider/model fields, customer key entry, authenticated capacity evidence, the corrected budget rule, new-session model selection, canonical Flash skill installation and one real marker-read verification. This is chat-model selection, NOT @flash-executor subagent creation. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires the ZCode desktop app on the customer's machine (GUI), documented at https://zcode.z.ai/en/docs/configuration . Steps are the documented GUI fields, not invented config files. ZCode compacts automatically and exposes no user-facing compaction threshold. If GUI automation is unavailable, hand the customer precise manual steps instead of fabricating configuration changes.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash PRIMARY setup — ZCode (chat model selection, GUI)

Run this skill only on an explicit user request to make Flash the primary model in ZCode. 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 change — while reading or downloading this skill authorizes nothing. Still pause for: app installation, missing secure credentials (GUI key entry is the customer's action), collisions with existing entries, GUI unavailability or label differences from the docs, and any metered smoke test outside the authorization. PRIMARY here means: in a NEW task/chat the model picker shows Flash and the main session itself runs on Flash. Do NOT create a `@flash-executor` subagent, do not touch subagent settings, and do not install an executor workflow to fake primary support. These instructions follow the official docs (https://zcode.z.ai/en/docs/configuration , https://zcode.z.ai/en/docs/skill ) and are documentation-backed, not a claim of live Flash certification.

## 1. Protected scope (never modified)

- Every existing ZCode provider, model, subagent, skill and setting not owned by this task — inspect first, reuse an identical entry, stop on a conflicting one rather than overwriting it.
- Subagent definitions — primary selection is a chat-model choice, not a subagent.
- Task-owned additions only: the `Teralor Flash` provider + `Flash` model entries (or an identical existing pair reused), the canonical `flash-executor` skill plus its owned local binding, and this optional setup skill at `~/.zcode/skills/flash-orchestrator-setup-zcode/SKILL.md`.

## 2. Discovery and OS awareness

1. Confirm the actual OS and that ZCode is installed and launchable; record the app version if shown. Native Windows/macOS/Linux GUI differences matter: describe where the customer clicks; never run invented shell commands against ZCode state or invent automation schemas.
2. If ZCode is missing, installation is the customer's action from the official site/docs, with their approval — never blind remote-code execution or a purchase.
3. Capacity discovery is NOT optional: reliable limits must come from an authorized authenticated `/v1/models` call (customer key, e.g. a shell that already holds it in memory) or trusted in-app capacity evidence. If neither can provide verified capacity metadata, hand off manually or block (`MANUAL_STEP_REQUIRED`/`BLOCKED`) — never substitute a fake probe or remembered defaults.

## 3. Inspect-before-write plan (GUI)

- Before adding anything, open the relevant Settings panes and record what already exists (providers, models, skills — nonsecret values only: names, base URL, limits). Reuse an existing identical entry; stop rather than overwrite or duplicate a different one on rerun.
- Before ANY change, record ONLY the nonsecret UI field values (prior selected model, provider list, base URL, limits) in your plan so they can be restored. When the on-disk layout exists and is documented, additionally make an opaque, permission-preserving private backup of the actual config files before touching them; a known path is `~/.zcode/v2/config.json`, but discover and check the CURRENT installed version's actual path first. Back up with the file's own permissions, store it privately, and never read or print its secret contents into model-visible output.
- Do not read or dump ZCode's credential storage or full app config to model-visible output; do not follow unexpected symlinks; no destructive resets, broad chmod, or sudo by default.
- If any pane's labels or controls differ from the linked docs, stop that step, describe the actual UI, and ask the customer how to proceed (`MANUAL_STEP_REQUIRED`) rather than guessing fields into existence.
- Rollback: undo ONLY the entries this task added, after checking nothing was changed by the customer since; restore an opaque backup only if the live file still matches the backed-up state.

## 4. Secure key handling

- The key goes ONLY into the app's own secure API-key field, entered by the customer (GUI key entry may require customer action — pause for it). Never place the key in chat, prompts, argv, URLs, project files, Git, logs or screenshots.
- If no key exists for this environment, pause and ask the customer to obtain/enter one securely; never guess or borrow credentials from another service.

## 5. Verify the target API before configuring

- Target: `https://api.teralor.com/v1`, OpenAI-compatible 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).
- With the customer's consent, run the authenticated `GET /v1/models` and require exactly one unambiguous `Flash` row; require `capabilities.tools: true` for this tool-using primary. Stop on 401, missing model, or ambiguity — no aliases, renamed models, alternate providers, or silent fallback.
- 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 metadata require positive integer `context_length`, `max_input_tokens`, `max_output_tokens`, then:

```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)        # GUI context window
P = W - O                # prompt room, <= I; require P > 0
```

A lower advertised output capacity LOWERS O instead of rejecting the 32768 default; the half-capacity cap keeps at least half the total context for input at small capacities. ZCode's Advanced fields take the context window (W) and Max output tokens (O) only. ZCode compacts automatically with its own headroom and exposes NO user-facing threshold or trigger — do not fabricate a 172032 trigger or `extra_body` JSON fields, and do not claim a configured exact trigger. If discovery is missing/unverifiable, a field is invalid, or no positive budget exists, STOP before applying any budget entry — `BLOCKED`/`MANUAL_STEP_REQUIRED`; never fall back to recommended entries. System, tool, skill and history tokens count as input.

## 7. GUI configuration (exact documented fields)

Follow Settings → Model Settings / Manage Models (the docs also call this Model Providers):

1. At the bottom of the provider list, Add Provider named `Teralor Flash`; choose the OpenAI-compatible protocol/endpoint, not Anthropic; API base URL exactly `https://api.teralor.com/v1` (match the verified environment); the customer enters their own key into the app's secure API-key field; save.
2. Add Model with the exact ID `Flash`; enable the provider/model. Inspect first — reuse an identical entry, stop on a conflicting existing provider/model rather than overwriting it or changing the wire model ID.
3. Open the model's Advanced settings: context window `262144` (=W) and Max output tokens `32768` (=O), reduced per section 6 for verified lower capacity. These are product/recommended values, not ZCode defaults; custom-provider context edits apply only to NEW sessions after saving.
4. Keep optional thinking controls unset unless the route supports them; arbitrary provider `options` such as `reasoning_effort` are ignored — ZCode recognizes connection settings only.

## 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 `~/.zcode/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.

Use Settings → Skills → Refresh, confirm the correct source and enabled switch, then invoke `$flash-executor` in the newly selected Flash chat. For remote/Cloud workspaces, inspect the actual execution host and supported Sync → Sync Skill path; do not enable sync without authorization. This is an instruction skill, not an `@flash-executor` subagent.

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=ZCode primary chat; Teralor Flash / Flash (substitute actual GUI provider name)
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-zcode`, nonempty `description` ≤1024 chars, body ≤100KB, no HTML/error page) at `~/.zcode/skills/flash-orchestrator-setup-zcode/SKILL.md`, then Settings → Skills → Refresh, confirm the correct source and enabled switch, and invoke `$flash-orchestrator-setup-zcode` (type `$` and select it; docs also expose a slash-menu Skills group). Remote/Cloud ZCode workspaces need workspace-header Sync → Sync Skill for user-level skills — install on the machine actually running the workspace and do not enable cloud sync or broaden scope without authorization. Preserve existing skills; stop on collisions.

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

1. Save and start a NEW task/chat (running sessions do not hot-reload and context edits apply to new sessions only), open its model picker and select `Teralor Flash / Flash` explicitly as the primary chat model. Confirm the picker displays Flash BEFORE testing. Do not launch a subagent.
2. One authorized marker read through the REAL Flash PRIMARY loop: BEFORE the smoke, the trusted setup controller/customer — OUTSIDE the fresh Flash chat — 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."
3. Require the EXACT nonce returned, a visible real read-tool call/result for that path, and session/model-indicator evidence the reply came from the selected Flash model — not the previous primary. A saved key, a saved config, an HTTP 200 on `/models` alone, or a canned "OK" is NOT verification. Failure means `BLOCKED`; keep sanitized evidence, clean up only the owned marker fixture, never substitute fake probes or another model.
4. Confirm no other provider, model, subagent or skill was modified and no permissions were broadened.

## 10. Final report

Report all of the following — no field may be summarized away:

- harness/app version, route/model: ZCode / `Teralor Flash` + `Flash` as the primary chat model
- actual installed Flash skill path and discovery/loading evidence
- configuration entries created (provider, model, Advanced W/O values) and the `/v1/models` evidence behind them; compaction status reported honestly as automatic with no user-facing control
- what was recorded before each GUI change (rollback notes) and where backups live
- the checks actually run (models discovery, marker-nonce primary-session round-trip, picker evidence) and every step the customer performed manually (key entry, clicks, new chat)

Status is one of:

- `READY` — only after the real bounded primary-session verification succeeded with verified limits.
- `BLOCKED` — failed authentication, absent/ambiguous `Flash`, invalid/unverifiable capacities, conflicting entries, GUI state differing from docs, or failed verification; describe evidence.
- `MANUAL_STEP_REQUIRED` — GUI automation unavailable or a step needs the customer (key entry, capacity metadata, new-chat selection, install approval); hand over the precise click-path honestly instead of fabricating configuration changes. Missing GUI or missing metadata NEVER yields READY.

References: https://zcode.z.ai/en/docs/configuration , https://zcode.z.ai/en/docs/skill .

Cursor — full setup prompt

Download the Cursor setup skill

Set up and verify Teralor Flash as the PRIMARY model in Cursor, following the complete instructions below. PRIMARY means the new selected main session itself runs on Flash: Flash plans, chooses tools and reviews results in that session. Make exactly the primary-mode changes the instructions specify and nothing else — preserve my other profiles, providers, projects, global defaults, executor/delegation settings and all saved credentials; never clone a parent profile and never silently broaden permissions. The setup must also install the canonical Flash skill (identifier flash-executor) at the actual skill path the instructions name, validating the download and stopping on any conflict instead of overwriting existing customizations; the primary model stays Flash and no new delegation, provider or subagent settings are added — the skill's primary tools stay usable serially, and dispatch concurrent workers only when my harness supports it and that support is verified. Pause for me whenever secure credential entry, installation approval, a GUI step, a capacity/name conflict or a metered test needs my action, and only report READY after real verification through the new Flash primary session succeeds AND the installed Flash skill is discoverable and loads through the documented harness instruction.

---
name: flash-orchestrator-setup-cursor
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as the PRIMARY model in Cursor through BYOK — a new Agent chat selects Flash itself. Covers Cursor Settings → Models key entry by the customer, the Override OpenAI Base URL scope warning, custom-model addition with the exact ID Flash, the honest no-budget-controls status, new-chat selection and one real marker-read verification. Bounded primary BYOK only — budgets are not configurable and long-context safety is not certified. Reviewing or downloading this skill is not consent to change anything.
compatibility: >-
  Requires Cursor with BYOK support (Cursor Settings → Models / API Keys) on the machine actually running the
  workspace. Support-backed recipe, not a tested native integration: the base-URL override redirects ALL
  OpenAI-family requests, every request transits Cursor's backend, and no per-custom-model
  context/output/compaction controls exist. GUI unavailability keeps the setup MANUAL_STEP_REQUIRED.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash PRIMARY setup — Cursor (BYOK primary, bounded)

Run this skill only on an explicit user request to make Flash the primary model in Cursor. Reviewing or downloading it is not consent: present a concise plan — including the scope warning in section 3 — and get the customer's acknowledgment BEFORE changing any setting. The explicit setup request authorizes the scoped BYOK changes once that warning is acknowledged; reading or downloading this skill authorizes nothing. Still pause for: secure key entry (customer action), GUI controls whose labels differ from support guidance, entitlement/plan gates, and any metered smoke test outside the authorization. PRIMARY here means a NEW Agent chat explicitly selects Flash (not Auto) and that chat's main loop plans and chooses tools. There is no subagent or worker step in this route, and no runtime executor skill is required for the primary connection. This is a docs/support-backed recipe ( https://cursor.com/docs/settings/api-keys , https://cursor.com/docs/models , https://cursor.com/docs/skills and the cited forum replies), not a claim of live Flash certification.

## 1. Protected scope and material warnings (state these first)

- The **Override OpenAI Base URL** applies to ALL OpenAI-family requests — including built-in picker models — not just Flash. Disable it when returning to ordinary Cursor/OpenAI models, and restore the prior key/toggle/base-URL states for a full rollback.
- Every request transits Cursor's backend for final prompt construction; the key is sent on each request over encrypted connections and, per Cursor, not persisted server-side. BYOK does not cover Tab completion and Cursor's Zero Data Retention policy does not apply to BYOK.
- A valid provider key does NOT guarantee Agent access (support records a Pro-account plan-gate failure with the key attached) and BYOK does not eliminate Cursor charges — current models docs specify a Cursor Token Rate on Teams/Enterprise BYOK. No purchase, upgrade or quota reset is ever authorized by this setup.
- Protected: every unrelated Cursor setting, other providers/keys, Tab settings, privacy settings, existing skills. Task-owned changes only: the OpenAI key field + toggles + base-URL override (all restorable), the custom `Flash` model entry, the canonical `flash-executor` skill plus its owned local binding, and this optional setup skill.

## 2. Discovery first

1. Record the Cursor version and the CURRENT nonsecret state of Settings → Models / API Keys before touching anything: prior selected model, whether Use OpenAI API Key was on, whether the override was on, the prior base URL, and any existing OpenAI key presence. If an existing key would be replaced, require that the customer can restore it from their own secret store first — otherwise STOP (`BLOCKED`).
2. Never screenshot an exposed key, read credential storage, or guess-edit a settings JSON or internal app database — no verified portable Cursor credential/config backup schema exists, so rollback for GUI-owned settings is GUI rollback.
3. If the custom-model add control is absent in the installed build, or its labels differ from the support guidance, stop as `MANUAL_STEP_REQUIRED`, describe the actual UI, and ask the customer — do not present "Add Custom Model" as a universally verified caption, and do not rename Flash or use Auto-mode round-trip workarounds to manipulate catalog matching (both violate the exact-ID primary contract).

## 3. Plan acknowledgment and secure key handling

- Present the section-1 warnings and the change list; obtain the customer's explicit acknowledgment before any mutation.
- The customer enters their Teralor key ONLY into Cursor's own OpenAI key field (GUI entry is the customer's action — pause for it). Never the key in chat, prompts, argv, URLs, project files, Git or logs.
- With consent, verify the route first: an authenticated `GET /v1/models` with the customer key, from the SAME endpoint the override will point at, must return exactly one unambiguous `Flash` row with `capabilities.tools: true`. Stop on 401 or a missing model — no fallback model or endpoint.
- Validated-capacity prerequisite BEFORE any GUI/configuration change: the same authenticated discovery must advertise `context_length`, `max_input_tokens` and `max_output_tokens` as positive integers — reject missing/null/boolean/string/fractional values. Record the verified capacities in the plan even though Cursor cannot set client budgets from them (section 4). Missing, unverifiable or invalid capacity metadata means STOP — `BLOCKED` (or `MANUAL_STEP_REQUIRED` while waiting for the metadata) — never proceed with recommended values as a fallback.

## 4. Budget truth (never certify what Cursor cannot configure)

No supported per-custom-model context, output or compaction controls were established. Report all three as **UNSUPPORTED / NOT CONFIGURED** — never "262144 / 32768 / 172032 configured". Support reports unknown custom IDs default to an ASSUMED 1M context ( https://forum.cursor.com/t/does-max-mode-work-for-custom-api-openai-compatible-endpoint-models-what-decides-their-context-window/169950/5 ); Cursor cannot detect or manually set the real endpoint limit, so auto-compaction can occur far too late for Flash's actual 262144 total / 262144 input / 131072 output ceilings (not additive). `fullContextTokenLimit: 30000` is explicitly not the BYOK window control, and Max Mode has no documented effect on this budget (current docs limit Max Mode to legacy request-based plans). Practical mitigations, stated honestly: keep tasks and attached context small, start fresh chats, and recommend executor mode ( https://teralor.com/executor ) whenever explicit budgets or long tasks are required. If explicit configured budgets are an acceptance requirement, Cursor primary is `BLOCKED` for that requirement.

## 5. GUI configuration (documented steps; inspect before changing)

1. Cursor Settings → Models (the section is also called API Keys): in the OpenAI / OpenAI API Key row, the customer enters their Teralor key and clicks Save. Saving the key and enabling its toggle are SEPARATE steps.
2. Ensure **Use OpenAI API Key** is ON. Enable **Override OpenAI Base URL** and set it to exactly `https://api.teralor.com/v1` (match the verified environment). ( https://cursor.com/docs/settings/api-keys )
3. In the model list, use the custom-model add control to add the exact server model ID `Flash` and enable it. Do not rename it, do not alter the wire ID, and stop per section 2 if the control is unavailable.

## 6. 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 `<approved-workspace>/.cursor/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 on the host actually running the workspace; local files do not automatically exist in SSH/Cloud sessions. Restart/reopen Cursor, confirm the exact source under Customize → Skills and invoke `/flash-executor` in the new Agent chat with Flash explicitly selected. Do not alter the primary selection or install subagents as part of skill binding.

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=Cursor primary Agent chat; explicitly selected Flash via the verified BYOK route
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-cursor` matching its folder, nonempty `description`, no HTML/error body) at `<approved-workspace>/.cursor/skills/flash-orchestrator-setup-cursor/SKILL.md`; restart/reopen Cursor for startup discovery, inspect discovery under Customize → Skills, and invoke `/flash-orchestrator-setup-cursor` in Agent chat. `disable-model-invocation: true` is documented and appropriate for explicit-only setup. Install on the machine actually running the workspace — local user skills do not automatically exist in SSH/Cloud environments — and preserve existing skills; stop on collisions.

## 7. New-chat activation and real bounded verification

1. Start a NEW Agent chat and select Flash explicitly — not Auto. Official help says model selection persists across conversations, so recheck the fresh chat's selection rather than assuming a reset.
2. One authorized marker read through the REAL Flash PRIMARY loop: BEFORE the smoke, the trusted setup controller/customer — OUTSIDE the fresh Agent chat — 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 edit files or delegate."
3. Require the EXACT nonce returned, a visible real read-tool call/result for that path, and evidence the chat ran with Flash explicitly selected (model indicator; redacted provider request/usage metadata strengthens wire identity). Never infer backend model identity from the model's self-description; a saved key, `/models` 200 or canned "OK" is NOT success. A brief smoke does NOT certify long-context safety or prove any output cap. Failure means `BLOCKED`; keep sanitized evidence and remove only the owned marker fixture.

## 8. Rollback

- Undo GUI-owned settings through the GUI: restore the prior Use-OpenAI-key toggle, the prior override state and base URL, and disable/remove only the Flash entry this task added; have the customer re-enter any prior credential privately from their own secret store. Recheck for intervening user edits before restoring anything; remove only task-added entries/files.
- Turn the base-URL override OFF immediately whenever work returns to ordinary Cursor/OpenAI models, because the override redirects those requests too.

## 9. Final report

Report: Cursor version, installed Flash skill path and discovery/loading evidence, route/model (`Flash` via BYOK override to `https://api.teralor.com/v1`), the prior-state record and rollback locations, budget-control status stated honestly as UNSUPPORTED/NOT CONFIGURED, the checks actually run (models discovery, marker-nonce primary round-trip, explicit-selection evidence), every customer action (key entry, toggles, new chat), and the acknowledged scope/privacy effects. Status is one of:

- `READY` — bounded primary BYOK ONLY: setup saved and read back, Flash explicitly selected in a new chat, authorized marker check passed with route evidence, the section-3 capacity evidence verified (positive-integer advertised capacities recorded) — with unsupported numeric controls and the context/privacy/routing risks explicitly acknowledged. Never budget-certified or long-context-ready. If the user requires enforceable numeric controls, this remains `BLOCKED` regardless.
- `BLOCKED` — failed authentication, absent `Flash`, plan/entitlement rejection, conflicting entry that cannot be preserved, unavailable GUI route, failed marker check, or explicit configured budgets required (then direct the user to executor mode).
- `MANUAL_STEP_REQUIRED` — key entry, GUI/version inspection, new-chat selection, capacity metadata, or smoke authorization still pending; name the exact pending step honestly. GUI unavailability NEVER yields READY.

Hermes — separate primary profile

Make Flash the primary model of a NEW, independent Hermes profile — not a delegation or executor configuration, and not a clone of your existing orchestrator profile (profiles keep separate state, so the new profile does not inherit the old one's identity; existing profiles and global defaults stay untouched). Settings checked against Hermes 0.21.0 source; install Hermes from its official installation guide (installation needs your approval — never execute a remote script blindly).

Prerequisites: hermes --version (0.21 or compatible) and a collision check — hermes profile list. Create the primary profile only if flash is absent; if it exists with different settings, inspect it and choose a distinct name, then substitute the ACTUAL chosen name everywhere below. Never --clone.
Check and create (Bash example)
```
hermes --version
hermes profile list
hermes profile create flash --no-alias
hermes -p flash config edit
```
Secure credentials: the key is read from TERALOR_API_KEY via the named provider's key_env (a variable NAME, never a value or $VAR). Export it in the environment of the process that launches Hermes, or place it in the new profile's private .env (permissions 0600). Never the key in chat, prompts, argv, URLs, Git, logs or a config literal. If a key is needed before the profile exists, create only the blank profile, then pause for secure entry.
Authenticated limits: before configuring, run GET https://api.teralor.com/v1/models with your key and require exactly one unambiguous Flash row with capabilities.tools: true; a 401 or missing model stops the setup here.
Limits are not additive (total 262144, input ceiling 262144, output ceiling 131072). After an authenticated GET /v1/models confirms the exact Flash entry, validate the advertised context_length, max_input_tokens and max_output_tokens as positive integers, then set C=min(262144, total), I=min(262144, input) and O=min(32768, advertised output, floor(C/2)) — a lower advertised capacity lowers the output budget instead of rejecting the 32768 default. Reject C<2 or a non-positive O, then window W=min(C, I+O), prompt room P=W−O and compaction threshold T=floor(P×3/4). Hermes reads output from provider extra_body.max_tokens (0.21 ignores legacy model.max_tokens/HERMES_MAX_TOKENS) and compaction from the separate absolute cap compression.threshold_tokens. Missing or unverifiable metadata, or no positive budget at the advertised capacity, means stop before applying any budget setting — never fall back to the template defaults.

Primary profile config

Download hermes-primary.yaml

Merge into ~/.hermes/profiles/flash/config.yaml (hermes -p flash config edit); preserve other settings and all other profiles. Confirm the real path with `hermes -p flash config path` — HERMES_HOME relocates it; never write profiles/default blindly.

Substitute your discovered W/O/T values and, if a name collision forced a rename, the ACTUAL chosen provider name everywhere. Hermes 0.21 sends extra_body.max_tokens: 32768 as the wire output allowance and treats threshold_tokens: 172032 as a cap on the ratio-derived compaction threshold; the compressor does not infer output headroom from the wire parameter. Leave reasoning effort unset. See the provider reference and profiles docs.

View hermes-primary.yaml

# Teralor Flash as the PRIMARY model in Hermes 0.21 (verified against 0.21.0).
# Apply to a NEW profile so existing settings are never overwritten:
#   hermes profile create flash
#   hermes -p flash config edit      # merge this YAML, do not replace other settings
#   hermes -p flash chat
# The key is read from the TERALOR_API_KEY environment variable — never paste a
# key literal into this file, a prompt, or source control.
providers:
  teralor-flash:
    api: https://api.teralor.com/v1
    key_env: TERALOR_API_KEY
    transport: chat_completions
    default_model: Flash
    discover_models: true
    models:
      Flash:
        context_length: 262144
    extra_body:
      max_tokens: 32768
model:
  provider: custom:teralor-flash
  default: Flash
context:
  engine: compressor
compression:
  enabled: true
  threshold_tokens: 172032

Activate in a fresh session (no resume/continue — editing files does not rebuild an already-initialized agent) and confirm the banner and effective route, not just the saved YAML:
Confirm keys, then start a fresh primary session
```
hermes -p flash config get model.provider
hermes -p flash config get providers.teralor-flash.models.Flash.context_length
hermes -p flash config get compression.threshold_tokens
hermes -p flash chat
```
Setup skill (optional): Download the Hermes primary setup skill. Install it under the new profile's skills directory (~/.hermes/profiles/flash/skills/flash-orchestrator-setup-hermes/SKILL.md, invoked as /flash-orchestrator-setup-hermes) — or just paste the complete one-prompt instructions.
Install the Flash skill (required). Download the canonical SKILL.md into a unique temp file, requiring HTTP success; parse valid YAML frontmatter and require name: flash-executor plus a non-empty description; reject an HTML or error-page body (valid skills may contain HTML comments) and reject symlinks. Stop on any failure BEFORE installing. Install at the new profile's actual skills path — ~/.hermes/profiles/<name>/skills/flash-executor/SKILL.md for a named profile (the HERMES_HOME root moves it) — as a required step. If a file already exists there, stop on the conflict — reuse the identical file or preserve the existing customization rather than overwriting.
Verify discovery and load: start a fresh session and load it with hermes -p flash chat -s flash-executor, requiring the skill to be discovered and its instructions active. The primary model stays Flash — the skill adds task instructions only. Add no new delegation, provider or subagent settings for it; its primary tools stay usable serially, and dispatch concurrent workers only when your harness supports it and that support is verified.
Confirm setup: primary READY requires BOTH checks. First, in the fresh Flash session, run ONE bounded marker read: BEFORE the smoke, the trusted setup controller/customer — outside the fresh Flash session — creates a task-owned temp file with a fresh nonce; only its real path enters the tested session (never the nonce contents, and never a prior conversation containing them — the tested model never generates its own hidden challenge). Ask the session to read that real path with its own file tool and require the exact nonce bytes back plus route evidence that the primary session ran on custom:teralor-flash / Flash. Second, confirm the installed Flash skill is discoverable and loads in that session (e.g. hermes -p flash chat -s flash-executor). A /models 200 or a saved config file is not success. Keep normal approvals — no bypass flags — and confirm other profiles and global defaults are unchanged.
Rollback: make timestamped backups of every file you modify, keeping their original permissions (0600 for secret-bearing files), before touching them. To roll back, remove exactly the keys/entries/files this setup added after checking nothing else changed since — restore a backup only when the current file still matches the post-setup state. Never destructive resets, profile deletion of inherited profiles, or overwriting a collision.

Pi — provider + project primary

Unlike Pi's executor recipe (an external worker that changes no Pi files), a PRIMARY setup DOES change Pi's selected model/provider and the chosen project's compaction settings. These steps follow the Pi model documentation and are documentation-backed, not a claim of live Flash certification. Global startup defaults and other projects stay unchanged.

Prerequisites: Pi installed (pi --version) and the target project trusted — untrusted project settings and skills are ignored, and noninteractive modes default to ignoring them. Review the project, trust it via the supported UI, then restart. Do not set global project-trust to always or use approval bypass flags.
Secure credentials: ~/.pi/agent/models.json interpolates $TERALOR_API_KEY (a $ reference — plain TERALOR_API_KEY is a literal, not a lookup). Pi does not load .env for you: export the key securely in the launch environment. Never the key value in chat, argv, URLs, files, Git or logs. Authenticated limits: GET https://api.teralor.com/v1/models with your key must list the exact Flash before you configure anything.
Limits are not additive (total 262144, input ceiling 262144, output ceiling 131072). After an authenticated GET /v1/models confirms the exact Flash entry, validate the advertised context_length, max_input_tokens and max_output_tokens as positive integers, then set C=min(262144, total), I=min(262144, input) and O=min(32768, advertised output, floor(C/2)) — a lower advertised capacity lowers the output budget instead of rejecting the 32768 default. Reject C<2 or a non-positive O, then window W=min(C, I+O), prompt room P=W−O and compaction threshold T=floor(P×3/4). Pi additionally needs reserve R=W−T as reserveTokens; note Pi clamps wire output to contextWindow − estimated context − 4096 (minimum 1), so the wire allowance can sit below O. Missing or unverifiable metadata, or no positive budget at the advertised capacity, means stop before applying any budget setting — never fall back to the template defaults.
Provider and model
Download pi-models.json
Merge the teralor-flash provider into ~/.pi/agent/models.json (agent root moves with PI_CODING_AGENT_DIR); keep every existing provider. If the name collides with a different block, choose a distinct name and substitute it everywhere.
openai-completions means Chat Completions. reasoning: false only disables optional client effort controls — it does not claim Flash cannot reason.
View pi-models.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
          }
        }
      ]
    }
  }
}
```
Project primary selection + compaction
Download pi-settings.json
Deep-merge into .pi/settings.json in your trusted Flash project; preserve other settings. This is PROJECT scope: never persist it with the /model picker Ctrl+S, which writes global defaults.
defaultProvider/defaultModelselect Flash as this project's primary. Pi compacts above contextWindow − reserveTokens, so 90112 places the trigger at 172032; substitute your discovered W/R values, and stop rather than blindly preserving keepRecentTokens if lowered capacities make the retained history infeasible. See Pi settings.
View pi-settings.json
```
{
  "defaultProvider": "teralor-flash",
  "defaultModel": "Flash",
  "compaction": {
    "enabled": true,
    "reserveTokens": 90112,
    "keepRecentTokens": 20000
  }
}
```
Activate in a fresh launch from the trusted project (no --continue/--resume); /model reloads models.json when inspecting. Verify BOTH the configured project startup selection and the effective provider/model in the session header:
Fresh primary launch
```
pi --provider teralor-flash --model Flash
```
Setup skill (optional): Download the Pi primary setup skill. Install it at .pi/skills/flash-orchestrator-setup-pi/SKILL.md in the trusted project (or the agent-dir skills path) and invoke /skill:flash-orchestrator-setup-pi; pasting the complete one-prompt instructions needs no installation of this setup skill itself — the canonical Flash skill installation in the next step stays required.
Install the Flash skill (required). Download the canonical SKILL.md into a unique temp file, requiring HTTP success; parse valid YAML frontmatter and require name: flash-executor plus a non-empty description; reject an HTML or error-page body (valid skills may contain HTML comments) and reject symlinks. Stop on any failure BEFORE installing. Install at .pi/skills/flash-executor/SKILL.md in the trusted project — as a required step (an untrusted project ignores skills entirely). If a file already exists there, stop on the conflict — reuse the identical file or preserve the existing customization rather than overwriting.
Verify discovery and load: restart Pi and invoke /skill:flash-executor, requiring the skill to load with its instructions visible. The primary model stays Flash — the skill adds task instructions only. Add no new delegation, provider or subagent settings for it; its primary tools stay usable serially, and dispatch concurrent workers only when your harness supports it and that support is verified.
Confirm setup:primary READY requires BOTH checks. In the fresh Flash-primary session run ONE bounded marker read — BEFORE the smoke the trusted setup controller/customer prepares a task-owned temp nonce file OUTSIDE the fresh session; only its real path enters the tested session (never the nonce contents or a prior conversation containing them; the tested model never generates its own challenge) — read through the session's real file tool, and require the exact nonce bytes plus evidence the session ran on teralor-flash / Flash with your chosen budgets. Then confirm the installed Flash skill is discoverable and loads (/skill:flash-executor in the fresh session). A /models200 or a saved config file is not success. Confirm Pi's global defaults, other projects and any Hermes worker are untouched.
Rollback: make timestamped backups of every file you modify, keeping their original permissions (0600 for secret-bearing files), before touching them. To roll back, remove exactly the keys/entries/files this setup added after checking nothing else changed since — restore a backup only when the current file still matches the post-setup state. Never destructive resets, profile deletion of inherited profiles, or overwriting a collision. Project-scope keys/files only — never a global-settings reset.

ZCode — chat model selection (GUI)

ZCode primary means selecting Flash as the chat model in a new task — it is NOT creating a @flash-executor subagent. These GUI steps follow the linked ZCode docs and are not a claim of live Flash certification. If GUI automation is unavailable on your machine, perform the precise manual clicks yourself rather than letting an agent fabricate configuration changes.

Prerequisites: ZCode installed from the official site (installing software needs your approval) and your Teralor key available for secure GUI entry. Authenticated limits first: an authenticated GET https://api.teralor.com/v1/models (or trusted in-app capacity evidence) must confirm the exact Flash entry and positive-integer capacities — define C = advertised context_length and I = advertised max_input_tokens; reject missing/null/boolean/string/fractional values. Missing or unverifiable metadata stays a pending/manual prerequisite, never a verified default.
Open the relevant Settings panes and record what already exists (providers, models, skills — nonsecret values only). Reuse an identical entry; stop rather than overwrite or duplicate a conflicting one.
Provider and model configuration — complete these documented GUI substeps (numbered within the group):
1. Install ZCode from its official docs, then open the chat model selector → Manage Models → Settings / Model Settings (the docs also call this Model Providers). See the ZCode configuration docs.
2. Add a Provider named Teralor Flash; choose the OpenAI-compatible protocol/endpoint, not Anthropic. The API base URL must be https://api.teralor.com/v1(match the environment), and enter your own matching customer key in the app's API-key field — never paste the key into chat or source control.
3. Add a Model with the exact ID Flash and enable the provider/model.
4. Open the model's Advanced settings: context window 262144, Max output tokens 32768, or lower if your authenticated /v1/models result says so. These are the product context and recommended per-reply output, not additive limits. Custom-provider context edits apply to new sessions after saving.
5. Keep optional thinking controls unset unless your route supports them. Provider options only accept connection fields — arbitrary reasoning/extra_body keys are silently ignored.

Budget rule: limits are not additive — from the validated capacities of step 1 set the GUI context window to W=min(C, I+O) and Max output tokens to O=min(32768, advertised max_output_tokens, floor(C/2)), lowering both when the account advertises less. ZCode compacts automatically with its own headroom and exposes no user-facing threshold — do not add the 172032 trigger or invented request fields.
Save, start a NEW task/chat (context edits apply only to new sessions), open the model picker and select Teralor Flash / Flash explicitly as the primary chat model — no subagent. Check the picker displays Flash before testing.
Setup skill (optional): Download the ZCode primary setup skill. Install it at ~/.zcode/skills/flash-orchestrator-setup-zcode/SKILL.md, then Settings → Skills → Refresh and enable, and invoke $flash-orchestrator-setup-zcode; pasting the complete one-prompt instructions needs no installation of this setup skill itself — the canonical Flash skill installation below stays required.
Install the Flash skill (required). Download the canonical SKILL.md into a unique temp file, requiring HTTP success; parse valid YAML frontmatter and require name: flash-executor plus a non-empty description; reject an HTML or error-page body (valid skills may contain HTML comments) and reject symlinks. Stop on any failure BEFORE installing. Install at ~/.zcode/skills/flash-executor/SKILL.md — as a required step. If a file already exists there, stop on the conflict — reuse the identical file or preserve the existing customization rather than overwriting.
Verify discovery and load: Settings → Skills → Refresh, enable the skill, and invoke $flash-executor in a new chat, requiring it to load. The primary model stays Flash — the skill adds task instructions only. Add no new delegation, provider or subagent settings for it; its primary tools stay usable serially, and dispatch concurrent workers only when your harness supports it and that support is verified.
Confirm setup: primary READY requires BOTH checks. In the fresh Flash chat run ONE bounded marker read — BEFORE the smoke the trusted setup controller/customer prepares a task-owned temp nonce file OUTSIDE the fresh session; only its real path enters the tested chat (never the nonce contents or a prior conversation containing them; the tested model never generates its own challenge) — read through the real read tool, requiring the exact nonce bytes back plus visible evidence the reply came from the selected Flash model. Then confirm the installed Flash skill is discoverable and loads ($flash-executor after Refresh/enable). A saved key or a /models 200 is not verification.
Rollback:record the prior GUI state (selected model, provider list, limits) before changes and undo only this setup's entries; a verified-version check of the on-disk config comes before touching any opaque private backup, whose secret contents are never read. If explicit configured budgets are a hard requirement, ZCode's automatic compaction may not satisfy it — consider executor mode.

Cursor — BYOK primary, with limits

This is a docs/support-backed BYOK recipe, not a tested native Flash integration, and it carries real scope effects — read the warning before changing anything.

Scope warning first:the OpenAI base-URL override applies to ALL OpenAI-family requests, including built-in picker models — not just Flash — and every request transits Cursor's backend for final prompt construction (key sent on each request over encrypted connections; per Cursor not persisted server-side). BYOK does not cover Tab completion and Zero Data Retention does not apply to BYOK. Record the prior key-toggle/base-URL states before any change so you can restore them, and disable the override when returning to ordinary Cursor models. A valid provider key does not guarantee Agent access (a Pro plan-gate failure despite a valid key is on record) and does not eliminate Cursor charges, including a Token Rate on Teams/Enterprise BYOK.
Secure credentials + limits: enter your Teralor key ONLY in Cursor's own OpenAI key field (customer action; never in chat or files), then confirm an authenticated GET https://api.teralor.com/v1/models lists the exact Flash. Before any GUI/configuration change the same discovery must also advertise context_length, max_input_tokens and max_output_tokens as positive integers (reject missing/null/boolean/string/fractional values); record the verified capacities even though Cursor cannot set client budgets from them. Missing, unverifiable or invalid capacity metadata means STOP — BLOCKED/MANUAL_STEP_REQUIRED, never recommended values as a fallback.
In Cursor Settings → Models (API Keys): save the key, ensure Use OpenAI API Key is ON (saving and toggling are separate), enable Override OpenAI Base URL and set https://api.teralor.com/v1. See the Cursor API-keys docs. Then use the model-list custom-model add control to add the exact server ID Flash and enable it — the current official pages do not pin the exact add-button caption, so inspect your build and pause as MANUAL_STEP_REQUIRED if the control is unavailable. Do not rename Flash or use Auto-mode workarounds to manipulate catalog matching.
Budget truth: no supported per-custom-model context/output/compaction controls exist — report all three as NOT CONFIGURED, never as 262144/32768/172032 set. Support reports unknown IDs assume a 1M context, so auto-compaction can fire far too late for Flash's real 262144 window; Max Mode is not a verified fix and fullContextTokenLimit is not the BYOK window control. Keep tasks and attached context small and start fresh chats; when you need explicit budgets or long tasks, use executor mode instead.
Activate in a new Agent chat with Flash selected explicitly (not Auto) — selection persists across conversations, so recheck rather than assume — then run ONE bounded marker read: BEFORE the smoke the trusted setup controller/customer prepares a task-owned temp nonce file OUTSIDE the fresh chat; only its real path enters the tested session (never the nonce contents or a prior conversation containing them; the tested model never generates its own challenge) read through the real tool, requiring exact nonce bytes back plus Flash-selection evidence. A saved key or /models 200 is not success, and a brief smoke does not certify long-context safety. Cursor READY requires BOTH this primary marker smoke and Flash skill discovery/loading below — the skill must be discovered under Customize → Skills and load when invoked.
Setup skill (optional): Download the Cursor primary setup skill. Install it at .cursor/skills/flash-orchestrator-setup-cursor/SKILL.md in the approved workspace (restart for discovery; inspect under Customize → Skills) and invoke /flash-orchestrator-setup-cursor; pasting the complete one-prompt instructions needs no installation of this setup skill itself — the canonical Flash skill installation below stays required. Install on the machine actually running the workspace — local skills do not exist automatically in SSH/Cloud environments.
Install the Flash skill (required). Download the canonical SKILL.md into a unique temp file, requiring HTTP success; parse valid YAML frontmatter and require name: flash-executor plus a non-empty description; reject an HTML or error-page body (valid skills may contain HTML comments) and reject symlinks. Stop on any failure BEFORE installing. Install at .cursor/skills/flash-executor/SKILL.md in the actual workspace on the machine running it — as a required step. If a file already exists there, stop on the conflict — reuse the identical file or preserve the existing customization rather than overwriting.
Verify discovery and load: restart Cursor, confirm discovery under Customize → Skills, and invoke /flash-executor, requiring it to load. The primary model stays Flash — the skill adds task instructions only. Add no new delegation, provider or subagent settings for it; its primary tools stay usable serially, and dispatch concurrent workers only when your harness supports it and that support is verified.
Rollback: make timestamped backups of every file you modify, keeping their original permissions (0600 for secret-bearing files), before touching them. To roll back, remove exactly the keys/entries/files this setup added after checking nothing else changed since — restore a backup only when the current file still matches the post-setup state. Never destructive resets, profile deletion of inherited profiles, or overwriting a collision. GUI-owned settings roll back through the GUI: restore the prior key-toggle and base-URL states, and have the customer re-enter any replaced credential privately from their own secret store — stop rather than guess a settings file or internal database.

Codex — executor only

Using Flash as the primary/orchestrator model in Codex is not possible at the moment. There is no supported primary-mode configuration to document here — no bridge, no setup prompt and no setup download. Do not edit ~/.codex/config.toml, switch Codex's provider, or add Responses-API bridges. Flash is recommended only as a separate executor in Codex while keeping your current model in charge.

Claude Code — executor only

Using Flash as the primary/orchestrator model in Claude Code is not possible at the moment. There is no supported primary-mode configuration to document here — no bridge, no setup prompt and no setup download. Do not change Claude's model, settings, ANTHROPIC_BASE_URL or native subagent models. Flash is recommended only as a separate executor in Claude Code while keeping your current model in charge.