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