---
name: flash-executor-setup-zcode
description: Use only when the user explicitly asks to set up, configure, or verify Teralor Flash as a native ZCode subagent executor while keeping ZCode's primary model unchanged. Covers the GUI provider/model fields, secure key entry by the customer, Advanced limits, the flash-executor subagent with explicit Flash selection, the workflow skill, and real verification. Reviewing or downloading this skill is not consent to change anything.
compatibility: Requires the ZCode desktop app on the customer's machine (GUI). Steps are the documented GUI fields, not invented config files; ZCode compacts automatically and has 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 Executor setup — ZCode (native subagent, GUI)

Run this skill only on an explicit user request to set up Flash as an executor in ZCode. 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 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 or changes this task does not own, GUI unavailability, and any metered smoke test outside the authorization. Route: a ZCode-native subagent bound explicitly to a GUI-configured Flash model. ZCode's official docs (https://zcode.z.ai/en/docs/configuration , https://zcode.z.ai/en/docs/subagents , https://zcode.z.ai/en/docs/skill ) describe the fields below; these instructions are documentation-backed, not a claim of live Flash certification.

## 1. Protected scope (never modified)

- ZCode's primary/default chat model selection — Flash must NOT become the primary here.
- Any existing ZCode provider, model, subagent or skill not owned by this task.
- Task-owned additions only: the `Teralor Flash` provider + `Flash` model entries, the `flash-executor` subagent definition, and `~/.zcode/skills/flash-executor/SKILL.md`.

## 2. Discovery and OS awareness

1. Confirm the actual OS and that ZCode is installed and launchable; detect the app version if shown. Steps below follow the documented GUI path — record what the GUI actually displays at each step.
2. Native Windows, macOS and Linux GUI differences matter: describe where the customer clicks; never run invented shell commands against ZCode state. Follow the documented GUI path only — do not invent automation schemas.
3. 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.
4. ZCode discovery is NOT optional: reliable limits must come from a trusted authenticated client call or the app itself. If neither can provide verified capacity metadata, hand off manually or block (`MANUAL_STEP_REQUIRED`/`BLOCKED`) — a saved key plus a saved nonce alone is never enough to proceed, and never substitute a fake probe.
5. Confirm the terminal/shell that will run the `/v1/models` discovery call exists on this machine (Bash, WSL or PowerShell); if it does not, discovery falls back to the in-app key save plus the subagent verification below, and the honest status stays `MANUAL_STEP_REQUIRED`/`BLOCKED` until limits are verified — say so in the report.

## 3. Inspect-before-write plan

- Before adding anything, open the relevant Settings panes and record what already exists (providers, models, subagents, skills). 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 (provider/model names, base URL, limits, subagent settings — never secret values, never the credential store) 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/agent files before touching them; the currently known config path is `~/.zcode/v2/config.json`, but discover and check the current installed version's actual path first and use that. Back up with the file's own permissions, store it privately, never read or print its secret contents into model-visible output. Roll back ONLY the entries this task added, after checking nothing was changed by the customer since.
- 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 rather than guessing fields into existence.

## 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). Never place the key in chat, prompts, argv, URLs, project files, Git, or logs.
- 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. Confirm the provider saves and a fresh session authenticates.

## 5. Verify the target API before configuring

- Target: `https://api.teralor.com/v1`, OpenAI-compatible Chat Completions, exact model `Flash`.
- With the customer's consent, run an authenticated `GET /v1/models` (their key, e.g. via a shell that already holds it in memory) and require an exact `Flash` entry. Stop on 401, missing model, or incompatible protocol — no internal aliases, renamed models, alternate paid providers, or silent fallback.
- Existing account only: no purchases or quota resets; ask before any metered smoke test 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. ZCode's Advanced fields take context window and Max output tokens only — ZCode compacts automatically with its own headroom and exposes NO user-facing threshold and no manual trigger, so do not fabricate a 172032 trigger or `extra_body` JSON fields; the same window/output budgeting still applies. From authenticated `/v1/models` metadata compute the window first: C=min(262144, advertised total), I=min(262144, advertised input), each a positive integer; choose max output O=min(32768, advertised output, 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. Never apply O at or above the client window min(C, I+O), leaving positive prompt room min(C, I+O)−O; set the GUI context window to that client window. Lower the entries 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 entries — `BLOCKED` (or `MANUAL_STEP_REQUIRED` while waiting for metadata). Never fall back to the recommended entries in that state, and never treat `READY` as reachable without verified limits plus the actual subagent check in section 9.

## 7. GUI configuration (exact fields; leave the primary model unchanged)

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

1. 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.
2. Add Model with the exact ID `Flash`; enable the provider/model.
3. Advanced settings for the model: context window `262144`, Max output tokens `32768`, or lower if the authenticated `/v1/models` result says so. Custom-provider context edits apply to new sessions after saving.
4. Keep optional thinking controls unset unless the route supports them; provider options accept connection fields only — arbitrary reasoning/extra_body keys are silently ignored.
5. Settings → Subagents → New (custom subagents are Beta and user-level). Name it `flash-executor`; choose the configured `Teralor Flash` / `Flash` model EXPLICITLY — not "Inherit default". Definitions persist under `~/.zcode/agents/<name>.md`, but choose model/provider in the UI rather than inventing persisted IDs in a file.
6. Initially grant only Read/Grep/Glob; authorize Edit/Write/Bash only for coding tasks the customer approves. Save and enable.

## 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` into `~/.zcode/skills/flash-executor/SKILL.md`, then Settings → Skills → Refresh and enable; invoke `$flash-executor`. Preserve existing customizations (keep user additions); a skill adds instructions and is not a subagent or provider configuration. 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=native ZCode subagent "flash-executor" (provider Teralor Flash, model Flash, explicit selection)
launch=@flash-executor in a new session; workflow invoked with $flash-executor
binding=Before launching, the parent writes a bounded task file (task.md) in an approved workspace and passes only that bounded task; executor work ALWAYS routes through the explicitly-selected Flash subagent, never the primary model. On rerun, replace only this owned block and preserve all surrounding custom skill text.
<!-- END FLASH EXECUTOR LOCAL BINDING -->
```

Substitute the ACTUAL chosen provider/subagent/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 subagent prompt and use the REAL marker path.
2. Start a NEW session (running sessions do not hot-reload) and invoke `@flash-executor` ONCE with the single bounded marker-file read — one smoke, not a README test plus another task — and require the EXACT marker content returned plus evidence the reply came from the explicitly selected Flash model (model indicator/agent metadata in the session) — not the primary model.
3. A canned "OK", a saved config file, an HTTP 200 on `/models` alone, or the subagent self-claiming success is NOT verification. Never substitute fake probes, scratch paths, or another model on failure — keep failure evidence, clean up only the owned temp fixture. Failure means `BLOCKED`, not `READY`.
4. Confirm the primary model selection is unchanged and no other provider/subagent was modified. No arbitrary project edits or permission broadening.

## 10. Final report

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

- harness/route/model: ZCode / native `flash-executor` subagent / explicit `Teralor Flash` + `Flash`
- configuration entries created (provider, model, Advanced values) and the installed skill path
- chosen context-window and max-output numbers and the `/v1/models` evidence behind them
- what was recorded before each GUI change (rollback notes) and where
- the checks actually run (models discovery, marker-nonce subagent round-trip, primary-model confirmation)
- every step the customer performed manually (key entry, clicks, session restart)

Status is one of:

- `READY` — only after the real bounded verification above succeeded with verified limits.
- `BLOCKED` — a required condition failed (missing key, 401, model absent, capacity metadata missing/unverifiable, GUI state differs from docs); describe evidence.
- `MANUAL_STEP_REQUIRED` — GUI automation is unavailable or a step needs the customer (key entry, subagent creation, session restart, providing capacity metadata); hand over the precise click-path honestly instead of fabricating config changes. Missing GUI or missing metadata NEVER yields READY.

References: https://zcode.z.ai/en/docs/configuration , https://zcode.z.ai/en/docs/subagents , https://zcode.z.ai/en/docs/skill . No host-private paths or implementation model details apply.