---
name: flash-executor-setup-pi
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as a separate executor worker for Pi while keeping Pi's primary model unchanged. Covers a dedicated Hermes worker profile, secure TERALOR_API_KEY handling, budget validation, workflow-skill installation in a trusted project, and real verification. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires Pi with a shell/terminal capability in a trusted project, Bash (or WSL) or native Windows PowerShell as noted, network access to https://api.teralor.com, and Hermes installed on the machine actually running the shell. Installation steps require explicit user approval. The worker is external — no Pi models.json change and no speculative subagent extension.
metadata:
  author: Teralor
  version: "1.1.0"
---

# Flash Executor setup — Pi (external Hermes worker)

Run this skill only on an explicit user request to set up Flash as an executor in Pi. Reviewing or downloading it is not consent: present a concise plan, then act. The explicit setup request itself authorizes the scoped executor-only 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, name collisions or changes this task does not own, and any metered smoke test outside the authorization. Flash runs as a separate Hermes process Pi drives from its shell. Leave `~/.pi/agent/models.json`, Pi's primary model and the project's compaction settings unchanged, and do not install a speculative subagent extension.

## 1. Protected scope (never modified)

- `~/.pi/agent/models.json`, Pi's selected primary model, and `.pi/settings.json` compaction values.
- Any existing Hermes profile, provider or skill not owned by this task.
- Task-owned additions only: the `flash-executor` Hermes profile (if created here), the provider keys listed below inside it, and `.pi/skills/flash-executor/SKILL.md`.

## 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 tools/versions you will rely on: `pi --version`, `hermes --version`, `command -v curl`.
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). No private launcher or GPU/Docker image is required. Installing software needs the user's approval — fetch and review the official script before running it; never execute remote code blindly. Pi documentation: https://github.com/earendil-works/pi with skills docs at https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md — Pi's own model config is NOT touched by this route.

## 3. Inspect-before-write plan

- Before any write: read the target files/dirs you will touch; timestamp backups of every file you modify, keeping their permissions (0600 for anything secret-bearing).
- Parse and merge only the exact owned keys listed here; never dump whole configs or credential stores into model-visible output; do not follow unexpected symlinks.
- If a different `flash-executor` profile or skill already exists, stop that step: reuse only when it already matches, otherwise choose a distinct name. Never overwrite, never create duplicates on rerun.
- Rollback: record every owned addition; to roll back, remove exactly those keys/files and restore the timestamped backups after checking the target was not edited since. Never use destructive resets, force flags, broad chmod, or sudo by default.

## 4. Secure TERALOR_API_KEY

- Resolve the key from the customer's own environment/secret store, or a private profile `.env` (permissions 0600). It must reach the actual worker process — confirm with a fresh launched process, not just a temporary shell export.
- Never place the key in chat, prompts, argv, URLs, project files, Git, config literals, or logs. A trusted local secret client may load it into process memory; print only allowlisted metadata such as set/missing, never the value or a model-visible read of the secret file.
- If no key exists for this environment, pause and ask the customer to enter it securely. Do not guess or borrow credentials from another service.

## 5. Verify the target API before configuring

- Target: `https://api.teralor.com/v1`, Chat Completions, exact model `Flash`.
- Run an authenticated `GET /v1/models` with the customer key and require an exact `Flash` entry. Stop on 401, a missing model, or an incompatible protocol — no internal aliases, renamed models, alternate paid providers, or silent fallback.
- Existing account only: no purchases, no quota resets. Ask before any metered smoke test that is not already authorized.

## 6. Budget validation

Ceilings (not additive): total 262144, input ceiling 262144, output ceiling 131072. Recommended working values: output 32768, prompt room 229376, compaction trigger 172032. Keep these defaults in the YAML template. From the authenticated `/v1/models` metadata compute C and I FIRST: C=min(262144, advertised total), I=min(262144, advertised input); every discovery field must be a positive integer. Then choose O=min(32768, advertised output ceiling, floor(C/2)) — never above the advertised output, and never above floor(C/2): the half-capacity cap reserves at least half the total context for input at small capacities. If C<2, or the resulting O is not a positive integer, reject the budget as `BLOCKED` — a previously recommended output value being too large for the advertised capacity is not a viable budget. Then client_window=min(C, I+O), prompt_room=client_window−O, trigger=floor(prompt_room*3/4); O must leave positive prompt room and is never applied at or above the total window. Lower the template when the account advertises lower. System, tool, skill and history tokens count as input. If discovery is missing or unverifiable, any capacity field is missing or not a positive integer, or a positive safe budget is impossible at the advertised capacity, STOP before applying or using any budget settings — `BLOCKED` (or `MANUAL_STEP_REQUIRED` while waiting for metadata). Never fall back to the template in that state, and never treat `READY` as reachable without verified limits plus the actual worker check in section 9. Hermes 0.21 ignores legacy `model.max_tokens`/`HERMES_MAX_TOKENS`; the output budget lives in provider `extra_body.max_tokens` and the compaction threshold is separate.

## 7. Create the isolated worker profile

Ordering matters. If the customer chose a private worker-profile `.env` and the profile does not exist yet, create ONLY the empty, collision-checked worker profile first, then PAUSE for secure key entry/authentication (`MANUAL_STEP_REQUIRED`) — never apply model/budget configuration before the section-5/6 metadata is verified. Never clone the parent:

```bash
hermes profile list
hermes profile create flash-executor --no-alias --no-skills   # only if absent — empty profile, collision-checked first
# pause here for secure key entry / authentication if the chosen mode needs it
hermes -p flash-executor config edit                          # merge, do not replace
```

Merge exactly these keys into `~/.hermes/profiles/flash-executor/config.yaml`, preserving all other settings. `teralor-flash-executor` is a deliberately distinct provider name, but a name that looks unique is not guaranteed collision-free: inspect the existing providers first, reuse only when an existing block matches exactly, otherwise choose a new name and substitute the ACTUAL chosen name in every path, command, invocation and binding below. Inspect worker fallbacks with `hermes -p flash-executor fallback list` and disable them only through supported CLI subcommands if present (`fallback remove` is interactive and takes no index in this release); never change Pi's configuration or another profile's fallbacks.

```yaml
providers:
  teralor-flash-executor:
    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-executor
  default: Flash
context:
  engine: compressor
compression:
  enabled: true
  threshold_tokens: 172032
```

## 8. Install Flash (separate from this setup skill)

Validate the download BEFORE installing: require HTTP success, expected Agent Skills frontmatter with `name: flash-executor`, and no error/HTML page in the body — on any failure stop and re-check the endpoint instead of installing. Download the canonical Flash execution skill from `https://teralor.com/assets/neural/skills/flash-executor/SKILL.md` and save it as `.pi/skills/flash-executor/SKILL.md` in a trusted project. Restart Pi, then invoke `/skill:flash-executor`. Preserve any existing customized skill (update rather than overwrite, keeping user additions). Align the downloaded workflow's declared endpoint/origin to THIS verified environment (dev copies adapt URLs; downloads stay canonical production). Append exactly ONE owned block delimited by these exact markers — if an unowned or duplicated block makes the delimiters ambiguous, stop:

```text
<!-- BEGIN FLASH EXECUTOR LOCAL BINDING -->
worker=external Hermes profile "flash-executor" (custom:teralor-flash-executor, model Flash)
launch=hermes -p flash-executor chat --oneshot --max-turns 50 -t terminal,file --query-file task.md
binding=Before launching, the parent writes a bounded task file (task.md) in an approved workspace, then invokes the command above with that file; executor work ALWAYS routes through this profile, never any native/extension subagent. On rerun, replace only this owned block and preserve all surrounding custom skill text.
<!-- END FLASH EXECUTOR LOCAL BINDING -->
```

Substitute the ACTUAL chosen profile/provider/skill names everywhere if a collision forced a rename — never leave example placeholders installed. This setup skill and the workflow skill stay distinct: one configures, the other scopes tasks.

Stage the download in a task-owned temporary file before touching the destination; require nonempty `description` as well as the expected name, and reject symlink destinations. Compare the staged bytes with the installed canonical body before adding the local binding. Reuse an identical installation; if an existing body differs or contains customizations, preserve it and stop for reconciliation rather than overwriting it. Replace only an unambiguous owned binding block. In a fresh/reloaded harness, confirm `flash-executor` is actually discoverable at the resolved path and load it with the invocation above; a file existing on disk is not discovery. Report the canonical digest, installed path and any deliberate environment or binding delta. `READY` requires this installation/discovery check as well as the route smoke below. The execution procedure lives only in Flash, not in this onboarding skill.

## 9. Real bounded verification — one marker-read smoke

1. In a task-owned temp directory, create the marker file containing a freshly generated nonsecret nonce; keep the nonce value out of the worker prompt and use the REAL marker path.
2. Through Pi's shell run ONE smoke test from the current project or an approved isolated directory — the actual external worker, `--max-turns 8`, the properly quoted real marker path:

```bash
hermes -p flash-executor chat --oneshot --max-turns 8 -t terminal,file -q "Read the file at \"$MARKER_PATH\" and reply with its exact contents. Do not edit files."
```

Require the EXACT marker content returned, plus route/model/config evidence (profile `flash-executor`, `custom:teralor-flash-executor`, `Flash`). Regular bounded tasks afterwards use the section-8 binding (`task.md`, `--max-turns 50`). This is the one smoke test — do not add extra vague probe tasks.
3. A canned "OK", a config file write, an HTTP 200 on `/models` alone, or the worker self-claiming success is NOT verification. Never substitute fake probes, scratch paths, or another model when verification fails — keep the failure evidence, clean up only the owned temp fixture. Failure means `BLOCKED`, not `READY`.
4. Confirm `~/.pi/agent/models.json`, Pi's primary model and project compaction settings are unchanged, then report. Keep authorizations and sandboxing as they were; no bypass flags and no arbitrary project edits or network broadening.

## 10. Final report

Report: harness/route/model, config path and installed skill path, chosen C/O/prompt/trigger values, backup and rollback locations, the checks actually run, and any step not performed. Status is one of:

- `READY` — only after the real bounded verification above succeeded.
- `BLOCKED` — a required condition failed (missing key, 401, model absent, incompatible protocol, failed verification); describe evidence.
- `MANUAL_STEP_REQUIRED` — something needs the customer (secure key entry, install approval, Pi restart for skill reload); describe precisely what to do, honestly.

References: Hermes installation https://hermes-agent.nousresearch.com/docs/getting-started/installation/ ; Pi repository https://github.com/earendil-works/pi ; Pi skills documentation https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md . The external-worker route deliberately changes no Pi configuration file; no host-private paths or implementation model details apply.