--- 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 config path`) — the default profile lives under `~/.hermes`, named profiles under `~/.hermes/profiles/`, 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 `/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 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. ``` 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 `/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 ` 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 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 ""` (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.