orynacode-ai 1.16.2

package/src/cli/error.ts

@@ -0,0 +1,118 @@
+import { NamedError } from "@opencode-ai/core/util/error"
+import { errorFormat } from "@/util/error"
+import { isRecord } from "@/util/record"
+
+type ConfigIssue = { message: string; path: string[] }
+
+function isTaggedError(error: unknown, tag: string): error is Record<string, unknown> {
+  return isRecord(error) && error._tag === tag
+}
+
+function configData(input: unknown, tag: string): Record<string, unknown> | undefined {
+  if (!isRecord(input)) return undefined
+  if (input.name === tag && isRecord(input.data)) return input.data
+  if (input._tag === tag) return input
+  return undefined
+}
+
+function stringField(input: Record<string, unknown>, key: string): string | undefined {
+  return typeof input[key] === "string" ? input[key] : undefined
+}
+
+function configIssues(input: Record<string, unknown>): ConfigIssue[] {
+  return Array.isArray(input.issues)
+    ? input.issues.filter((issue): issue is ConfigIssue => {
+        if (!isRecord(issue)) return false
+        return (
+          typeof issue.message === "string" &&
+          Array.isArray(issue.path) &&
+          issue.path.every((x) => typeof x === "string")
+        )
+      })
+    : []
+}
+
+export function FormatError(input: unknown): string | undefined {
+  if (input instanceof Error && isRecord(input.cause) && "body" in input.cause) {
+    const formatted = FormatError(input.cause.body)
+    if (formatted) return formatted
+  }
+
+  // CliError: domain failure surfaced from an effectCmd handler via fail("...")
+  if (isTaggedError(input, "CliError")) {
+    if (typeof input.exitCode === "number") process.exitCode = input.exitCode
+    return stringField(input, "message") ?? ""
+  }
+
+  // MCPFailed: { name: string }
+  if (NamedError.hasName(input, "MCPFailed")) {
+    const data = isRecord(input) && isRecord(input.data) ? stringField(input.data, "name") : undefined
+    return `MCP server "${data}" failed. Note, opencode does not support MCP authentication yet.`
+  }
+
+  // AccountServiceError, AccountTransportError: TaggedErrorClass
+  if (isTaggedError(input, "AccountServiceError") || isTaggedError(input, "AccountTransportError")) {
+    return stringField(input, "message") ?? ""
+  }
+
+  // ProviderModelNotFoundError: { providerID: string, modelID: string, suggestions?: string[] }
+  const providerModelNotFound = configData(input, "ProviderModelNotFoundError")
+  if (providerModelNotFound) {
+    const suggestions = Array.isArray(providerModelNotFound.suggestions)
+      ? providerModelNotFound.suggestions.filter((x) => typeof x === "string")
+      : []
+    return [
+      `Model not found: ${stringField(providerModelNotFound, "providerID")}/${stringField(providerModelNotFound, "modelID")}`,
+      ...(suggestions.length ? ["Did you mean: " + suggestions.join(", ")] : []),
+      `Try: \`opencode models\` to list available models`,
+      `Or check your config (orynacode.json) provider/model names`,
+    ].join("\n")
+  }
+
+  // ProviderInitError: { providerID: string }
+  const providerInit = configData(input, "ProviderInitError")
+  if (providerInit) {
+    return `Failed to initialize provider "${stringField(providerInit, "providerID")}". Check credentials and configuration.`
+  }
+
+  // ConfigJsonError: { path: string, message?: string }
+  const configJson = configData(input, "ConfigJsonError")
+  if (configJson) {
+    const message = stringField(configJson, "message")
+    return `Config file at ${stringField(configJson, "path")} is not valid JSON(C)` + (message ? `: ${message}` : "")
+  }
+
+  // ConfigDirectoryTypoError: { dir: string, path: string, suggestion: string }
+  const configDirectoryTypo = configData(input, "ConfigDirectoryTypoError")
+  if (configDirectoryTypo) {
+    return `Directory "${stringField(configDirectoryTypo, "dir")}" in ${stringField(configDirectoryTypo, "path")} is not valid. Rename the directory to "${stringField(configDirectoryTypo, "suggestion")}" or remove it. This is a common typo.`
+  }
+
+  // ConfigFrontmatterError: { message: string }
+  const configFrontmatter = configData(input, "ConfigFrontmatterError")
+  if (configFrontmatter) {
+    return stringField(configFrontmatter, "message") ?? ""
+  }
+
+  // ConfigInvalidError: { path?: string, message?: string, issues?: Array<{ message: string, path: string[] }> }
+  const configInvalid = configData(input, "ConfigInvalidError")
+  if (configInvalid) {
+    const path = stringField(configInvalid, "path")
+    const message = stringField(configInvalid, "message")
+    const issues = configIssues(configInvalid)
+    return [
+      `Configuration is invalid${path && path !== "config" ? ` at ${path}` : ""}` + (message ? `: ${message}` : ""),
+      ...issues.map((issue) => "↳ " + issue.message + " " + issue.path.join(".")),
+    ].join("\n")
+  }
+
+  // UICancelledError: user cancelled an interactive CLI prompt
+  if (isTaggedError(input, "UICancelledError") || NamedError.hasName(input, "UICancelledError")) {
+    return ""
+  }
+  return undefined
+}
+
+export function FormatUnknownError(input: unknown): string {
+  return errorFormat(input)
+}

package/src/cli/heap.ts

@@ -0,0 +1,59 @@
+import path from "path"
+import { writeHeapSnapshot } from "node:v8"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { Global } from "@opencode-ai/core/global"
+import * as Log from "@opencode-ai/core/util/log"
+
+const log = Log.create({ service: "heap" })
+const MINUTE = 60_000
+const LIMIT = 2 * 1024 * 1024 * 1024
+
+let timer: Timer | undefined
+let lock = false
+let armed = true
+
+export function start() {
+  if (!Flag.OPENCODE_AUTO_HEAP_SNAPSHOT) return
+  if (timer) return
+
+  const run = async () => {
+    if (lock) return
+
+    const stat = process.memoryUsage()
+    if (stat.rss <= LIMIT) {
+      armed = true
+      return
+    }
+    if (!armed) return
+
+    lock = true
+    armed = false
+    const file = path.join(
+      Global.Path.log,
+      `heap-${process.pid}-${new Date().toISOString().replace(/[:.]/g, "")}.heapsnapshot`,
+    )
+    log.warn("heap usage exceeded limit", {
+      rss: stat.rss,
+      heap: stat.heapUsed,
+      file,
+    })
+
+    await Promise.resolve()
+      .then(() => writeHeapSnapshot(file))
+      .catch((err) => {
+        log.error("failed to write heap snapshot", {
+          error: err instanceof Error ? err.message : String(err),
+          file,
+        })
+      })
+
+    lock = false
+  }
+
+  timer = setInterval(() => {
+    void run()
+  }, MINUTE)
+  timer.unref?.()
+}
+
+export * as Heap from "./heap"

package/src/cli/logo.ts

@@ -0,0 +1,21 @@
+export const logo = {
+  left: [
+    "                        ",
+    "█▀▀█ █▀▀█ █^^█ █▀▀▄ █▀▀█",
+    "█__█ █__█ _▀▀_ █__█ █__█",
+    "▀▀▀▀ █^▀▀ _▀▀_ ▀~~▀ █▀▀█",
+  ],
+  right: [
+    "             ▄     ",
+    "█▀▀▀ █▀▀█ █▀▀█ █▀▀█",
+    "█___ █__█ █__█ █^^^",
+    "▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀",
+  ],
+}
+
+export const go = {
+  left: ["    ", "█▀▀▀", "█_^█", "▀▀▀▀"],
+  right: ["    ", "█▀▀█", "█__█", "▀▀▀▀"],
+}
+
+export const marks = "_^~,"

package/src/cli/network.ts

@@ -0,0 +1,64 @@
+import type { Argv, InferredOptionTypes } from "yargs"
+import { ConfigV1 } from "@opencode-ai/core/v1/config/config"
+import type { Config } from "@/config/config"
+import { Effect } from "effect"
+
+const options = {
+  port: {
+    type: "number" as const,
+    describe: "port to listen on",
+    default: 0,
+  },
+  hostname: {
+    type: "string" as const,
+    describe: "hostname to listen on",
+    default: "127.0.0.1",
+  },
+  mdns: {
+    type: "boolean" as const,
+    describe: "enable mDNS service discovery (defaults hostname to 0.0.0.0)",
+    default: false,
+  },
+  "mdns-domain": {
+    type: "string" as const,
+    describe: "custom domain name for mDNS service (default: opencode.local)",
+    default: "opencode.local",
+  },
+  cors: {
+    type: "string" as const,
+    array: true,
+    describe: "additional domains to allow for CORS",
+    default: [] as string[],
+  },
+}
+
+export type NetworkOptions = InferredOptionTypes<typeof options>
+
+export function withNetworkOptions<T>(yargs: Argv<T>) {
+  return yargs.options(options)
+}
+export const resolveNetworkOptions = Effect.fn("Cli.resolveNetworkOptions")(function* (args: NetworkOptions) {
+  const { Config } = yield* Effect.promise(() => import("@/config/config"))
+  const config = yield* Config.Service.use((cfg) => cfg.getGlobal())
+  return resolveNetworkOptionsNoConfig(args, config)
+})
+
+export function resolveNetworkOptionsNoConfig(args: NetworkOptions, config?: ConfigV1.Info) {
+  const portExplicitlySet = process.argv.includes("--port")
+  const hostnameExplicitlySet = process.argv.includes("--hostname")
+  const mdnsExplicitlySet = process.argv.includes("--mdns")
+  const mdnsDomainExplicitlySet = process.argv.includes("--mdns-domain")
+  const mdns = mdnsExplicitlySet ? args.mdns : (config?.server?.mdns ?? args.mdns)
+  const mdnsDomain = mdnsDomainExplicitlySet ? args["mdns-domain"] : (config?.server?.mdnsDomain ?? args["mdns-domain"])
+  const port = portExplicitlySet ? args.port : (config?.server?.port ?? args.port)
+  const hostname = hostnameExplicitlySet
+    ? args.hostname
+    : mdns && !config?.server?.hostname
+      ? "0.0.0.0"
+      : (config?.server?.hostname ?? args.hostname)
+  const configCors = config?.server?.cors ?? []
+  const argsCors = Array.isArray(args.cors) ? args.cors : args.cors ? [args.cors] : []
+  const cors = [...configCors, ...argsCors]
+
+  return { hostname, port, mdns, mdnsDomain, cors }
+}

package/src/cli/ui.ts

@@ -0,0 +1,132 @@
+import { EOL } from "os"
+import { Schema } from "effect"
+import { logo as glyphs } from "./logo"
+
+const wordmark = [
+  `⠀                                ▄     `,
+  `█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█`,
+  `█  █ █  █ █▀▀▀ █  █ █    █  █ █  █ █▀▀▀`,
+  `▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀  ▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀`,
+]
+
+export class CancelledError extends Schema.TaggedErrorClass<CancelledError>()("UICancelledError", {}) {}
+
+export const Style = {
+  TEXT_HIGHLIGHT: "\x1b[96m",
+  TEXT_HIGHLIGHT_BOLD: "\x1b[96m\x1b[1m",
+  TEXT_DIM: "\x1b[90m",
+  TEXT_DIM_BOLD: "\x1b[90m\x1b[1m",
+  TEXT_NORMAL: "\x1b[0m",
+  TEXT_NORMAL_BOLD: "\x1b[1m",
+  TEXT_WARNING: "\x1b[93m",
+  TEXT_WARNING_BOLD: "\x1b[93m\x1b[1m",
+  TEXT_DANGER: "\x1b[91m",
+  TEXT_DANGER_BOLD: "\x1b[91m\x1b[1m",
+  TEXT_SUCCESS: "\x1b[92m",
+  TEXT_SUCCESS_BOLD: "\x1b[92m\x1b[1m",
+  TEXT_INFO: "\x1b[94m",
+  TEXT_INFO_BOLD: "\x1b[94m\x1b[1m",
+}
+
+export function println(...message: string[]) {
+  print(...message)
+  process.stderr.write(EOL)
+}
+
+export function print(...message: string[]) {
+  blank = false
+  process.stderr.write(message.join(" "))
+}
+
+let blank = false
+export function empty() {
+  if (blank) return
+  println("" + Style.TEXT_NORMAL)
+  blank = true
+}
+
+export function logo(pad?: string) {
+  if (!process.stdout.isTTY && !process.stderr.isTTY) {
+    const result = []
+    for (const row of wordmark) {
+      if (pad) result.push(pad)
+      result.push(row)
+      result.push(EOL)
+    }
+    return result.join("").trimEnd()
+  }
+
+  const result: string[] = []
+  const reset = "\x1b[0m"
+  const left = {
+    fg: "\x1b[90m",
+    shadow: "\x1b[38;5;235m",
+    bg: "\x1b[48;5;235m",
+  }
+  const right = {
+    fg: reset,
+    shadow: "\x1b[38;5;238m",
+    bg: "\x1b[48;5;238m",
+  }
+  const gap = " "
+  const draw = (line: string, fg: string, shadow: string, bg: string) => {
+    const parts: string[] = []
+    for (const char of line) {
+      if (char === "_") {
+        parts.push(bg, " ", reset)
+        continue
+      }
+      if (char === "^") {
+        parts.push(fg, bg, "▀", reset)
+        continue
+      }
+      if (char === "~") {
+        parts.push(shadow, "▀", reset)
+        continue
+      }
+      if (char === " ") {
+        parts.push(" ")
+        continue
+      }
+      parts.push(fg, char, reset)
+    }
+    return parts.join("")
+  }
+  glyphs.left.forEach((row, index) => {
+    if (pad) result.push(pad)
+    result.push(draw(row, left.fg, left.shadow, left.bg))
+    result.push(gap)
+    const other = glyphs.right[index] ?? ""
+    result.push(draw(other, right.fg, right.shadow, right.bg))
+    result.push(EOL)
+  })
+  return result.join("").trimEnd()
+}
+
+export async function input(prompt: string): Promise<string> {
+  const readline = require("readline")
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer: string) => {
+      rl.close()
+      resolve(answer.trim())
+    })
+  })
+}
+
+export function error(message: string) {
+  if (message.startsWith("Error: ")) {
+    message = message.slice("Error: ".length)
+  }
+  println(Style.TEXT_DANGER_BOLD + "Error: " + Style.TEXT_NORMAL + message)
+}
+
+export function markdown(text: string): string {
+  return text
+}
+
+export * as UI from "./ui"

package/src/cli/upgrade.ts

@@ -0,0 +1,53 @@
+import { Config } from "@/config/config"
+import { AppRuntime } from "@/effect/app-runtime"
+import { Flag } from "@opencode-ai/core/flag/flag"
+import { Installation } from "@/installation"
+import { InstallationVersion } from "@opencode-ai/core/installation/version"
+import { GlobalBus } from "@/bus/global"
+
+export async function upgrade() {
+  const config = await AppRuntime.runPromise(Config.Service.use((cfg) => cfg.getGlobal()))
+  if (config.autoupdate === false || Flag.OPENCODE_DISABLE_AUTOUPDATE) return
+  const method = await Installation.method()
+  const latest = await Installation.latest(method).catch(() => {})
+  if (!latest) return
+
+  if (Flag.OPENCODE_ALWAYS_NOTIFY_UPDATE) {
+    GlobalBus.emit("event", {
+      directory: "global",
+      payload: {
+        type: Installation.Event.UpdateAvailable.type,
+        properties: { version: latest },
+      },
+    })
+    return
+  }
+
+  if (InstallationVersion === latest) return
+
+  const kind = Installation.getReleaseType(InstallationVersion, latest)
+
+  if (config.autoupdate === "notify" || kind !== "patch") {
+    GlobalBus.emit("event", {
+      directory: "global",
+      payload: {
+        type: Installation.Event.UpdateAvailable.type,
+        properties: { version: latest },
+      },
+    })
+    return
+  }
+
+  if (method === "unknown") return
+  await Installation.upgrade(method, latest)
+    .then(() =>
+      GlobalBus.emit("event", {
+        directory: "global",
+        payload: {
+          type: Installation.Event.Updated.type,
+          properties: { version: latest },
+        },
+      }),
+    )
+    .catch(() => {})
+}

package/src/command/index.ts

@@ -0,0 +1,181 @@
+import { InstanceState } from "@/effect/instance-state"
+import { EffectBridge } from "@/effect/bridge"
+import type { InstanceContext } from "@/project/instance-context"
+import { SessionID, MessageID } from "@/session/schema"
+import { Effect, Layer, Context, Schema } from "effect"
+import { Config } from "@/config/config"
+import { MCP } from "../mcp"
+import { Skill } from "../skill"
+import { EventV2 } from "@opencode-ai/core/event"
+import PROMPT_INITIALIZE from "./template/initialize.txt"
+import PROMPT_REVIEW from "./template/review.txt"
+
+type State = {
+  commands: Record<string, Info>
+}
+
+export const Event = {
+  Executed: EventV2.define({
+    type: "command.executed",
+    schema: {
+      name: Schema.String,
+      sessionID: SessionID,
+      arguments: Schema.String,
+      messageID: MessageID,
+    },
+  }),
+}
+
+export const Info = Schema.Struct({
+  name: Schema.String,
+  description: Schema.optional(Schema.String),
+  agent: Schema.optional(Schema.String),
+  model: Schema.optional(Schema.String),
+  source: Schema.optional(Schema.Literals(["command", "mcp", "skill"])),
+  // Some command templates are lazy promises from MCP prompt resolution.
+  template: Schema.Unknown,
+  subtask: Schema.optional(Schema.Boolean),
+  hints: Schema.Array(Schema.String),
+}).annotate({ identifier: "Command" })
+
+export type Info = Omit<Schema.Schema.Type<typeof Info>, "template"> & { template: Promise<string> | string }
+
+export function hints(template: string) {
+  const result: string[] = []
+  const numbered = template.match(/\$\d+/g)
+  if (numbered) {
+    for (const match of [...new Set(numbered)].sort()) result.push(match)
+  }
+  if (template.includes("$ARGUMENTS")) result.push("$ARGUMENTS")
+  return result
+}
+
+export const Default = {
+  INIT: "init",
+  REVIEW: "review",
+} as const
+
+export interface Interface {
+  readonly get: (name: string) => Effect.Effect<Info | undefined>
+  readonly list: () => Effect.Effect<Info[]>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/Command") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const config = yield* Config.Service
+    const mcp = yield* MCP.Service
+    const skill = yield* Skill.Service
+
+    const init = Effect.fn("Command.state")(function* (ctx: InstanceContext) {
+      const cfg = yield* config.get()
+      const bridge = yield* EffectBridge.make()
+      const commands: Record<string, Info> = {}
+
+      commands[Default.INIT] = {
+        name: Default.INIT,
+        description: "guided AGENTS.md setup",
+        source: "command",
+        get template() {
+          return PROMPT_INITIALIZE.replace("${path}", ctx.worktree)
+        },
+        hints: hints(PROMPT_INITIALIZE),
+      }
+      commands[Default.REVIEW] = {
+        name: Default.REVIEW,
+        description: "review changes [commit|branch|pr], defaults to uncommitted",
+        source: "command",
+        get template() {
+          return PROMPT_REVIEW.replace("${path}", ctx.worktree)
+        },
+        subtask: true,
+        hints: hints(PROMPT_REVIEW),
+      }
+
+      for (const [name, command] of Object.entries(cfg.command ?? {})) {
+        commands[name] = {
+          name,
+          agent: command.agent,
+          model: command.model,
+          description: command.description,
+          source: "command",
+          get template() {
+            return command.template
+          },
+          subtask: command.subtask,
+          hints: hints(command.template),
+        }
+      }
+
+      for (const [name, prompt] of Object.entries(yield* mcp.prompts())) {
+        commands[name] = {
+          name,
+          source: "mcp",
+          description: prompt.description,
+          get template() {
+            return bridge.promise(
+              mcp
+                .getPrompt(
+                  prompt.client,
+                  prompt.name,
+                  prompt.arguments
+                    ? Object.fromEntries(prompt.arguments.map((argument, i) => [argument.name, `$${i + 1}`]))
+                    : {},
+                )
+                .pipe(
+                  Effect.map(
+                    (template) =>
+                      template?.messages
+                        .map((message) => (message.content.type === "text" ? message.content.text : ""))
+                        .join("\n") || "",
+                  ),
+                ),
+            )
+          },
+          hints: prompt.arguments?.map((_, i) => `$${i + 1}`) ?? [],
+        }
+      }
+
+      for (const item of yield* skill.all()) {
+        if (commands[item.name]) continue
+        commands[item.name] = {
+          name: item.name,
+          description: item.description,
+          source: "skill",
+          get template() {
+            return item.content
+          },
+          hints: [],
+        }
+      }
+
+      return {
+        commands,
+      }
+    })
+
+    const state = yield* InstanceState.make<State>((ctx) => init(ctx))
+
+    const get = Effect.fn("Command.get")(function* (name: string) {
+      const s = yield* InstanceState.get(state)
+      return s.commands[name]
+    })
+
+    const list = Effect.fn("Command.list")(function* () {
+      const s = yield* InstanceState.get(state)
+      return Object.values(s.commands)
+    })
+
+    return Service.of({ get, list })
+  }),
+)
+
+export const defaultLayer = layer.pipe(
+  Layer.provide(Config.defaultLayer),
+  Layer.provide(MCP.defaultLayer),
+  Layer.provide(Skill.defaultLayer),
+)
+
+export * as Command from "."

package/src/command/template/initialize.txt

@@ -0,0 +1,66 @@
+Create or update `AGENTS.md` for this repository.
+
+The goal is a compact instruction file that helps future OrynaCode sessions avoid mistakes and ramp up quickly. Every line should answer: "Would an agent likely miss this without help?" If not, leave it out.
+
+User-provided focus or constraints (honor these):
+$ARGUMENTS
+
+## How to investigate
+
+Read the highest-value sources first:
+- `README*`, root manifests, workspace config, lockfiles
+- build, test, lint, formatter, typecheck, and codegen config
+- CI workflows and pre-commit / task runner config
+- existing instruction files (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- repo-local OrynaCode config such as `orynacode.json`
+
+If architecture is still unclear after reading config and docs, inspect a small number of representative code files to find the real entrypoints, package boundaries, and execution flow. Prefer reading the files that explain how the system is wired together over random leaf files.
+
+Prefer executable sources of truth over prose. If docs conflict with config or scripts, trust the executable source and only keep what you can verify.
+
+## What to extract
+
+Look for the highest-signal facts for an agent working in this repo:
+- exact developer commands, especially non-obvious ones
+- how to run a single test, a single package, or a focused verification step
+- required command order when it matters, such as `lint -> typecheck -> test`
+- monorepo or multi-package boundaries, ownership of major directories, and the real app/library entrypoints
+- framework or toolchain quirks: generated code, migrations, codegen, build artifacts, special env loading, dev servers, infra deploy flow
+- repo-specific style or workflow conventions that differ from defaults
+- testing quirks: fixtures, integration test prerequisites, snapshot workflows, required services, flaky or expensive suites
+- important constraints from existing instruction files worth preserving
+
+Good `AGENTS.md` content is usually hard-earned context that took reading multiple files to infer.
+
+## Questions
+
+Only ask the user questions if the repo cannot answer something important. Use the `question` tool for one short batch at most.
+
+Good questions:
+- undocumented team conventions
+- branch / PR / release expectations
+- missing setup or test prerequisites that are known but not written down
+
+Do not ask about anything the repo already makes clear.
+
+## Writing rules
+
+Include only high-signal, repo-specific guidance such as:
+- exact commands and shortcuts the agent would otherwise guess wrong
+- architecture notes that are not obvious from filenames
+- conventions that differ from language or framework defaults
+- setup requirements, environment quirks, and operational gotchas
+- references to existing instruction sources that matter
+
+Exclude:
+- generic software advice
+- long tutorials or exhaustive file trees
+- obvious language conventions
+- speculative claims or anything you could not verify
+- content better stored in another file referenced via `orynacode.json` `instructions`
+
+When in doubt, omit.
+
+Prefer short sections and bullets. If the repo is simple, keep the file simple. If the repo is large, summarize the few structural facts that actually change how an agent should work.
+
+If `AGENTS.md` already exists at `${path}`, improve it in place rather than rewriting blindly. Preserve verified useful guidance, delete fluff or stale claims, and reconcile it with the current codebase.