Distillation

Date: Sep 8, 2026

• 🔴 (09:42) User stated opencode configuration is strictly validated and invalid fields cause startup failure; the authoritative schema is https://opencode.ai/config.json, and every opencode.json should declare "$schema": "https://opencode.ai/config.json".
• 🔴 (09:42) User stated opencode config is loaded once at startup and is not hot-reloaded; after changing opencode.json, an agent file, a skill, a plugin, or another config-time file, opencode must be quit and restarted.
• 🔴 (09:42) User stated model always carries a provider prefix, specifically "anthropic/claude-sonnet-4-6".
• 🔴 (09:42) User stated skills is an object with paths and/or urls, never an array.
• 🔴 (09:42) User stated references is an object keyed by alias; each value is a local path, Git repository, or string shorthand.
• 🔴 (09:42) User stated agent is an object keyed by agent name, never an array.
• 🔴 (09:42) User stated command is an object keyed by command name, never an array.
• 🔴 (09:42) User stated plugin is an array containing strings or [name, options] tuples, never an object.
• 🔴 (09:42) User stated mcp[name].command is an array of strings, never a single string, and type is required.
• 🔴 (09:42) User stated permission is either a string action or an object keyed by tool name; top-level permission: "allow" allows everything and is rarely desirable, while per-agent permission: overrides top-level permissions.
• 🔴 (09:42) User stated skill frontmatter requires a lowercase hyphen-separated name of up to 64 characters that matches the folder name.
• 🔴 (09:42) User stated a skill description is effectively required: skills without one are filtered out and never surfaced to the model.
• 🔴 (09:42) User stated skill descriptions should cover what the skill does and when to use it, use third person such as "Use when...", front-load concrete trigger keywords and filenames, and use "Use ONLY when..." to avoid activation on adjacent topics.
• 🔴 (09:42) User stated local reference path values may be relative to the declaring config, absolute, or use ~/; Git repository values accept Git URLs, host/path references, and GitHub owner/repo shorthand, with optional branch, description, and hidden.
• 🔴 (09:42) User stated an agent Markdown file’s body becomes its prompt; prompt: must not also appear in frontmatter.
• 🔴 (09:42) User stated a command Markdown file’s body is its required template; template: must not also appear in frontmatter. $ARGUMENTS expands to all text after the command, while $1, $2, etc. select positional arguments.
• 🔴 (09:42) User stated local MCP environment sets environment variables; header tokens support {env:VAR} and {file:path} interpolation, while shell-style ${VAR} is not substituted.
• 🟡 (09:42) Assistant committed to inspecting frozen pilot files and the existing smoke contract, patching only approved paths, and not touching production or controlling any service.
• 🟡 (09:42) Inspected pilot root /home/byk/.local/share/opencode-v2-pilot/config/opencode, which contains exactly 9 entries: bun.lock, node_modules/, opencode.json, package.json, plugins/, service-v2-pilot.json, test/, tsconfig.json, and types/.
• 🟡 (09:42) Pilot inspection identified test file /home/byk/.local/share/opencode-v2-pilot/config/opencode/test/followup.test.ts; the recursive file result was truncated after the first 100 entries.
• 🟡 (09:42) Inspected a PTY plugin source under /home/byk/.local/share/opencode-v2-pilot/config/opencode; visible technical details included PtyPluginOptions, SupervisorOptions, CLOSE_TIMEOUT_MS = 27_000, KillInput, SupervisorTransport, Plugin.define, authorize, requireSession, MAX_COMMAND_LENGTH, permission action "shell", and process termination using "SIGKILL".