Agent Notes for Coddy

Short map for automation-friendly contributors.

Repository navigation

Builds

coddy serve is the only long-running command: it starts every subsystem config.yaml enables (httpserver.enable, default true; gateways.telegram.enable; gateways.pachca.enable; swarm.enable; scheduler.enable; metrics.enable, auxiliary: it serves beside the others and never keeps the process up on its own) over one session manager. A subsystem enabled but not compiled in is a startup error naming the tag. Run make build TAGS=http for the HTTP surface only (REST and /docs, no npm). Run make build TAGS=cli for the interactive console (bare coddy on a terminal; see docs/surfaces/console.md). Run make build TAGS="http ui" to link the embedded SPA (Makefile runs ui-build before go build). Recommended full image matches Dockerfile (make build TAGS="http ui scheduler memory cli gateway swarm metrics"). Default make build omits HTTPServer, scheduler, and memory to keep dependency surface lean.

Primary conversational surface for bundled UI lives at POST /v1/responses with stream:true. Prefer it over POST /v1/chat/completions when shipping Coddy-hosted experiences.

Run make android for the Android (Termux) binaries, build/coddy-android-arm64 and build/coddy-android-amd64: GOOS=android with cgo, linked by the Android NDK against Bionic (scripts/android-cc.sh finds the NDK), a position-independent executable naming /system/bin/linker64, which Termux can start where it runs programs through the system linker (the static GOOS=linux build is refused there with has unexpected e_type: 2). The release publishes them as coddy_X.Y.Z_android_arm64.tar.gz and coddy_X.Y.Z_android_amd64.tar.gz; a build without cgo does not compile (internal/platform/android_nocgo.go). What Termux patches into its own Go is done at run time by internal/platform/android*.go (the binary's own path under the linker, certificates, TMPDIR), and every exec.Cmd goes through platform.AdaptCommand before Start (held by TestEverySpawnSiteAdaptsTheCommand). Guide: docs/getting-started/android.md.

Run make deb / make rpm for the Linux packages (PKG_ARCHS, PKG_TAGS, DIST_DIR knobs; nfpm is fetched on demand, nothing to install) and make brew VERSION=X.Y.Z to render the Homebrew cask for a release. CI builds the Linux packages on every pull request.

Run make check-image to build the runtime image for linux/amd64 and linux/arm64 and check that each variant carries a /bin/coddy of its own platform (scripts/check-image.sh reads the ELF header; Docker with buildx is all it needs, the build stages cross-compile and nothing runs under emulation). The Docker image job runs it on every pull request and the release workflow runs it before it pushes. Guide: docs/getting-started/docker.md (Checking the platforms of the image).

Swagger lives at /docs/, OpenAPI YAML at /openapi.yaml.

Pre-commit gate

A git pre-commit hook runs the linter before every commit, so nothing lands with lint errors. It is the single enforcement point for humans and coding agents alike. Tests are opt-in on commit: make test (the express run: the SPA's vitest suite, then every optional module compiled in once) belongs before the push, and the per-combination tag matrix (make test-matrix) runs on GitHub Actions for every pull request, as does make test-race: the race detector over the whole tree with every tag but ui, clean in every package. Run it before the push when a change touches goroutines, locks or a test harness that drives a live loop. Two groups run on their own: make test-cache (the features/prompt_cache_*.feature specs and the TestPromptCache* tests, part of make test: what each request sends the provider, byte for byte across a session - run it when a change touches the system prompt, the rules, the history or the send boundary) and make test-perf (the benchmarks of the perf_test.go files, never part of make test: timings and the context a session costs, as token metrics).

• Enable once per clone: make hooks (sets core.hooksPath=.githooks; this is local config and is not committed, so every clone runs it once).
• AppSec scanning is opt-in the same way: make security (trivy + semgrep + govulncheck over the checkout, docker fallback when the binaries are absent; govulncheck fails on a vulnerable function the code calls, the standard library of the toolchain line of go.mod included) is what .github/workflows/security.yaml runs on pull requests, pushes to main and a weekly cron; make sec-report scans without failing on findings. Reports and the severity summary land in dist/security/; the gate knobs (SEC_FAIL_TRIVY, SEC_FAIL_SEMGREP, SEC_FAIL_GOVULNCHECK, GOVULNCHECK_TAGS, SEC_DOCKER, SEMGREP_CONFIGS) and the triage workflow (.trivyignore.yaml, trivy.yaml skip-dirs, nosemgrep) are in docs/contributing/security-scanning.md.
• On commit, .githooks/pre-commit calls scripts/checks.sh, which runs make lint by default: make fmt-check (gofmt -s -l over every Go file git tracks, whatever its build tags or platform), golangci-lint over the untagged tree, over every tag but ui and over the shipped tag set, so every Go file of the host platform but the http && !<tag> stubs of external/httpserver is compiled once (.golangci.yml enables the gofmt -s formatter there too), then tsc --noEmit over the SPA sources (make ui-typecheck); then, when the commit stages SPA sources, Prettier over the whole SPA (make ui-format-check, prettier --check . in external/ui, .prettierignore keeping the build output and the vendored grammars out), which CI's Lint job runs too: the tree is Prettier-clean, and npm run fmt in external/ui keeps it so. Commits touching only non-code files (docs, etc.) skip the gate.
• Scope knobs: CODDY_HOOK_TESTS=fast also runs a quick go test ./..., CODDY_HOOK_TESTS=full the express make test, CODDY_HOOK_TESTS=matrix every tag combination; CODDY_HOOK_LINT=0 skips the linter; CODDY_HOOK_FORMAT=0 skips the Prettier check; CODDY_HOOK_SKIP=1 bypasses everything.
• Emergency bypass for a single commit: git commit --no-verify.
• The Android half of internal/platform (//go:build android) is compiled by neither gate either: make check-android runs go vet with GOOS=android and cgo through the Android NDK, test files included, and CI runs it in the Android cross-build job, which also uploads both release-shaped binaries as artifacts.
• Both gates compile the host platform only. Changing a file behind //go:build windows, or a signature it shares with the rest of the tree, needs make check-windows (cross-build plus go vet over every non-ui tag combination, test files included) and make lint-windows. CI runs both, and additionally runs the complete Go suite (go test ./... with the shipped tag set), the rule adapters and the SPA's vitest suite on a real windows-latest runner (job Test suite (Windows)), so every _windows_test.go file (internal/platform, internal/textenc and the rest) runs there and every test that writes files or compares paths meets the runner's CRLF checkout. The platform packages and the console suite run on a macos-latest runner as well (job test-macos), which also builds the console and drives the binary through a real pty with examples/cli/cli_e2e_startup.py (first frame, keys, exit); the cli job of the Linux test matrix runs that pty script too, and the Telegram stand (tgfake) job builds the gateway binary with the exporter (TAGS="gateway metrics") and runs examples/gateway/tg_e2e_offline.sh with TG_E2E_METRICS=1, which scrapes the exporter after the chat: the real coddy serve against the fake Bot API and the scripted model of the tgfake release binary of the version go.mod pins, installed by tgfake's own action, no Telegram and no LLM.

Documentation contract

The documentation is the tree under docs/, mapped by docs/nav.yaml: getting-started/, surfaces/, operate/, features/, reference/, contributing/, tutorials/, and docs/assets/ for everything a page embeds. docs/plans/ (design records, never rewritten to match a later rename) is internal and stays out of the map, so the hub and the llms files do not carry it. Anything git ignores under docs/ is not documentation at all and is not walked. docs/README.md (the hub), the field tables of docs/reference/config.md, the help screens of docs/reference/cli.md and the inventory of docs/assets/INDEX.md are generated by internal/docsgen (make docs), which also builds llms.txt and llms-full.txt straight into the site layer - they are a concatenation of every page, so a copy in this index conflicted in every branch that touched any page, and .gitignore keeps them out; make docs-check (the CI job Documentation, and the pre-commit hook for commits that touch the docs) fails on a stale generated block, a page missing from the map, a broken relative link or anchor, and an asset no page uses. make docs-changelog refreshes docs/getting-started/changelog.md from the GitHub Releases. The documentation is also in Russian: docs/ru/<group>/<page>.md translates docs/<group>/<page>.md under the same path, docs/ru/nav.yaml and docs/ru/config-descriptions.yaml translate the map and the schema descriptions, and the binary carries both languages (every surface shows the one it knows the reader uses). A change to an English page carries into its translation in the same pull request and is restamped with make docs-stamp PAGES=...; make docs-check fails on a missing or stale translation and on headings that differ from the source. The conventions and the writing rules for both languages are the paired documentation translation rule (Cursor, Claude Code). The full guide, page types included, is docs/contributing/documentation.md.

A change to Coddy carries its documentation in the same pull request (step 10 of the paired workflow rule - Cursor, Claude Code): a new capability gets its page, its nav.yaml entry and its row in the reference of its kind (tools.md, slash-commands.md, environment-variables.md, keyboard.md); a changed behaviour updates the page that describes it (git grep -n '<key or command>' docs/); a web UI or console feature is shown with a screenshot of the real surface embedded on its page, Dark 1280 wide, named <feature>-<state>-<theme>-<width>.png under docs/assets/<page>/; a demo video goes to docs/assets/video/ and is embedded on the page as a GitHub attachment URL with the repository copy linked under it (Videos in docs/contributing/documentation.md). Add screenshots under docs/assets/ only when they document a new UI/UX feature or a changed existing UI/UX feature, and embed every such asset on its documentation page. Keep pull-request-only evidence out of docs/assets: publish it on the screenshots branch of this repository (coddy-project/coddy-agent, never a personal fork) under a pull-request-specific directory, then embed its raw GitHub URLs in the pull request description. make docs-check governs every asset committed under docs/assets/. A page that moves takes its address with it: there are no redirect stubs. Every page of the map also has a stable address on coddy.dev: coddy.dev/docs/<slug> sends a person to the page on GitHub and coddy.dev/docs/<slug>.md to its raw Markdown (one generated script behind the site's 404.html, nothing duplicated), while llms.txt and llms-full.txt at the site root index the raw Markdown on main; the binary, the schema and the bundled skill print those addresses and nothing else. make site-docs renders the layer into the site checkout and make site-docs-check reports drift - a change to a page, to nav.yaml or to the schema is published to the site with the same pull request (workflow step 8).

Human prose for HTTP lives in docs/reference/http-api.md. Visual spec for SPA lives in DESIGN.md (this repo root). Architectural narrative remains under docs/contributing/architecture.md.

internal/config/config.schema.json is embedded into the binary (go:embed in internal/config/schema.go: it is what -t / --test-config validates a file against, its description strings are the doc: lines of that report and the Description column of the generated docs/reference/config.md tables) and leaves this repository: it is served at https://coddy.dev/config.schema.json, the address Coddy writes as a modeline into every config it saves, out of the site repository coddy-project.github.io as a verbatim copy. Touching the YAML config surface means make docs and make site-schema (and make site-schema-check to see whether the published copy is stale) - a schema that stops here leaves every editor validating against one the binary no longer matches. Hold the site push until the release when a key was renamed or removed: the schema sets additionalProperties: false, so the new file marks the old key as an error in configs already on disk. Full step: the paired workflow rule.

All code comments plus technical markdown authored for this repo (including docs/, DESIGN.md, AGENTS.md) stay English unless an operator explicitly asks for another natural language.

Prose skills

Prose this repository publishes - the pages under docs/ in both languages, DESIGN.md, the dictionaries under external/ui/src/ui/i18n/messages/, commit messages, pull request and issue text, review replies - is often drafted by a coding agent, and an agent's draft carries the patterns of machine-written text: stock openers, binary contrasts, em dashes, officialese, calques from English in Russian. Whoever works on this repository with an agent installs these four skills and runs a draft through them before it is final:

The universal skills CLI installs each one where the agents on the machine read skills:

npx skills add hardikpandya/stop-slop
npx skills add ilyautov/humanizer-ru
npx skills add talkstream/ru-text
npx skills add EvilFreelancer/logika

Without it, clone each repository into your agent's skill folder under the skill's name: ~/.claude/skills/<name> (Claude Code), ~/.codex/skills/<name> (Codex), ~/.cursor/skills/<name> (Cursor), ~/.agents/skills/<name> or ${CODDY_HOME:-~/.coddy}/skills/<name> (Coddy). Coddy also installs logika by itself with coddy skills sync, from the rpa-skills catalog it ships as a built-in source.

How they apply here:

• write the draft first, then run it through the skills; humanize only what the agent wrote, never a quotation, the operator's own wording or literal text (code, keys, commands, the labels a page takes from the dictionaries);
• documentation and interface copy are technical text for humanizer-ru: fix the critical patterns and the calques, keep the structure, the terms and the format;
• where a skill and this repository disagree, the repository wins: typography follows the paired documentation translation rule (a hyphen with spaces, never an em or en dash; straight quotes, never the guillemets ru-text would put in), the glossary there and the paired Russian wording rule hold, and a translation still says what its English page says.

Agent host integrations

AGENTS.md is the repository-wide baseline, and CLAUDE.md remains its compatibility symlink. Cursor and Claude Code use paired native rule trees under .cursor/rules/ and .claude/rules/. Their bodies and activation intent stay equivalent, but neither vendor tree is a universal policy format.

Codex, OpenCode and ZCode use repository adapters that read .cursor/rules/*.mdc. The Cursor tree is the adapters' input as well as Cursor's native representation; it is not the conceptual owner of project policy. Run make test-agent-rules after changing an adapter or rule frontmatter.

A scoped model rule is context, not an enforcement boundary. Hooks and plugins can be untrusted, disabled, fail open or miss an opaque write, so critical trust, security and destructive-operation constraints stay in root policy, code, permissions, tests or CI.

Codex

Codex resolves its AGENTS.md chain once per session, walking from the repository root down to the launch directory, so a session started at the root never discovers nested instructions later. The project hook closes the scoped-rule gap for the events and payloads it understands:

• .codex/hooks.json wires .codex/hooks/attach_rules.py to SessionStart and to PreToolUse on apply_patch / Edit / Write;
• session start attaches every alwaysApply: true rule;
• pre-tool use extracts patch headers and structured path fields, then attaches unsent scoped rules whose scalar or YAML-list globs match;
• the hook parses .mdc frontmatter directly, needs no manually maintained index and fails open.

Codex requires explicit approval for hooks and tracks it by content hash. Run /hooks once per clone and again after either hook file changes. Project-local hooks also require a trusted .codex/ layer. The full guide and manual probes are in docs/contributing/codex-hooks.md.

OpenCode

The project plugin .opencode/plugins/project-rules.js injects always-on and active scoped rules into model requests, accepts scalar and YAML-list globs, and preserves active rules through compaction. When a write tool first reveals a scoped rule, the plugin rejects that call once so OpenCode retries with the rule in context. See docs/contributing/opencode-hooks.md.

ZCode

.zcode/config.json wires .zcode/hooks/attach_rules.py to SessionStart and PreToolUse on Edit / Write / MultiEdit / ApplyPatch. The behavior matches the Codex adapter, but ZCode supplies edited paths as structured JSON fields. Configuration-file hooks run because the committed config sets hooks.enabled: true; there is no per-hook trust prompt. The command uses python rather than the Microsoft Store python3 stub on Windows. See docs/contributing/zcode-hooks.md.

Code review invariants

Every reviewer applies this section to changed files. Keep entries behavioral and repository-specific; formatting and lint stay in CI, where the pre-commit gate already runs make lint.

HTTP surface

• Do not change routes, request or response shapes, or status codes in external/httpserver/server.go without updating external/httpserver/openapi.go in the same change. The served spec is what /docs/ and generated clients consume, so drift is a silent API break. Safe path: update both, then reconcile docs/reference/http-api.md.

Provider transport

• Do not add a provider request path that can bypass providers[].proxy. Completions, streams, model discovery, usage, OAuth/device sign-in, refresh and revoke all build through llm.HTTPClientForProviderProxy; a test-only explicit client may be accepted, but nil must return an error rather than fall back to http.DefaultClient. When a Settings sign-in starts before Save, apply the form's current proxy after resolving the row. Safe path: extend features/provider_proxy.feature, keep TestProviderProxyGuard green, and cover the request class through the proxy harness.

Build tags

• Do not let a package that builds by default import one that lives behind the http, ui, scheduler, memory, or gateway tags. Plain make build must keep compiling with the lean dependency set. Safe path: put the new code behind the same tag, or invert the dependency into an interface owned by the core package.

Project-local configuration

• Do not read, merge, or execute project-local configuration (.coddy/mcp.json, MCP server definitions, hook scripts) without routing it through TrustGate in internal/mcp. Opening an untrusted checkout must not by itself grant code execution. Safe path: gate the read on the workspace trust decision and persist the approval through TrustStore.
• The same holds for project-scope subagent definitions (.agents/agents and .coddy/agents under the workspace, or any subagents.dirs entry there): they load and spawn only as subagents.project_trust allows, a receipt in subagents.TrustStore is bound to the file digest, and a definition must never widen what the parent could do - permission_mode, tools and disallowed_tools only narrow, and the mandatory exclusions stay. Safe path: resolve the definition once, decide trust on that value with subagents.Decide, and derive the child's tool set with subagents.EffectiveTools.
• The same holds for project scheduler jobs (<workspace>/.coddy/scheduler/*.md): one runs, on cron or by hand, only as scheduler.project_trust allows, and a receipt in <home>/scheduler-trust.json is bound to the project (mcp.TrustWorkspace), the job id and the file digest. Trust is decided on one storage.JobSnapshot and that same snapshot is what runs; an edit through Coddy re-issues a receipt only for a job that was trusted before it; no agent tool approves a project job; links under the project folder are refused and nothing the scheduler writes (the .state sidecar) lands in the checkout. Safe path: read with storage.ReadSnapshot, decide with schedservice.Decide, and route mutations through the session's workspace (resolveSessionCWD), never a raw cwd. Design: docs/plans/scheduler-project-jobs.md.
• A linked git worktree shares what its project decided, never more. Every trust store keys its receipts, and mcp-overrides.json its switches, by mcp.TrustWorkspace: the canonical workspace, or for a folder of a linked worktree the same folder of its main checkout, which gitws.MainCheckoutFolder answers only when the repository, read where its storage really is, names the worktree back, the repository is not bare and the answer stays inside the main checkout once links are resolved, outside any repository nested there (a .git file copied into another folder, a .git that is a link, an archive that brings storage of its own or a link out of the main checkout lends nothing). It reads only regular files, each up to a small limit, so a FIFO or a device named .git never blocks a trust decision. The digest still binds, so what a branch adds or changes asks again, and each checkout keeps its own receipt under the shared key (Checkout, mcp.ReceiptCheckout): Approve replaces only its checkout's receipt, an implicit revoke (a deleted or renamed scheduler job, a dropped marketplace entry) takes only its own, and an explicit untrust takes the project's. A project MCP server that does not name ${CWD} has one pool entry for the project's checkouts; the scheduler scans projects (ScanWorkspaces and the registry go through mcp.TrustWorkspace), so a job never runs on cron from a worktree. Paths stay on the real workspace: where a file is read, what a hook file is relative to, where a job file and its state live. Safe path: key a new store by mcp.TrustWorkspace inside the store, never by a raw or merely canonical path. Design: docs/plans/worktree-shared-project-config.md.

Packaging

• Do not add, rename or remove a CLI subcommand, a serve verb or a flag without updating packaging/man/coddy.1 and packaging/completions/coddy.bash / coddy.zsh in the same change (and topLevelCommands in cmd/coddy/usage_test.go for a command). Every install route ships those files as the documentation of the command set - the release archive through install.sh, the Homebrew cask and coddy update, the packages, the formula - and nothing generates them: the test holds the commands and the serve verbs to printUsage, flags are kept in step by hand. Step 11 of the paired workflow rule.
• Do not move /usr/bin/coddy or add a second packaged copy of the binary. coddy update asks dpkg-query -S / rpm -qf who owns the executable it is about to replace, and a packaged file that no database claims would be silently overwritten. Safe path: keep the single contents entry in packaging/nfpm.yaml.
• Keep the packaged service an opt-in systemd user unit that the package installs and never enables. Do not add a system service, a system account or files under /etc, and do not enable, start or disable the unit from a maintainer script. Coddy's state is per-user under ~/.coddy, and each user decides with coddy serve install / coddy serve uninstall. The unit is rendered by serve.PackagedUnitFile(): change the renderer and regenerate packaging/systemd/coddy.service, never the file alone.
• Do not add a file to the release .tar.gz layout without checking the Homebrew cask: packaging/homebrew/coddy.rb.tmpl links artefacts out of that archive by name.
• Do not move the man page or the completions inside the repository without updating packaging/homebrew/coddy-formula.rb.tmpl. The formula installs them from their source paths, and a from-source build is the only packaging route that reads the tree rather than a staged archive. Its test do block is coupled the same way: it asserts on the output of coddy -v, coddy sessions list (the SESSION_ID header) and coddy skills list (the Search roots: line), and once the formula is in homebrew/core those strings are checked by Homebrew's CI, not ours.
• Do not document, script or test a Homebrew install from a URL or a file path (brew install --cask <URL>, brew install --cask ./coddy.rb): current Homebrew loads a cask only out of a tap and refuses both outside HOMEBREW_DEVELOPER mode (issue #269). The route is the tap, brew install coddy-project/coddy-agent/coddy. Its Casks/coddy.rb is generated: change packaging/homebrew/coddy.rb.tmpl, never the tap, and let the release publish it. A template change is proven by the Homebrew tap workflow installing it on macOS with current Homebrew, not by ruby -c alone: Homebrew 7 warns on stanzas that still parse (verified:, Ruby flight blocks, completions linked as a binary), and features/homebrew_tap.feature holds the rendered cask to that list.
• Do not conflate the two Homebrew artefacts. The cask installs prebuilt macOS archives and is upgraded with brew upgrade --cask coddy out of a Caskroom; the formula builds from source and is upgraded with brew upgrade coddy out of a Cellar. internal/update reads which of the two owns the running executable off its path, so a change to that detection has to keep both hints correct - the wrong flag fails on the user's machine.

Docker image

• Do not give an automatic platform argument (TARGETOS, TARGETARCH, TARGETPLATFORM, BUILDPLATFORM and the rest) a default value in the Dockerfile. A default wins over the value BuildKit passes, and the linux/arm64 image shipped an x86-64 binary that way for months (issue #482): Docker still labels the variant arm64, and a host with qemu-user-static even runs it. Keep the build stages on --platform=$BUILDPLATFORM with GOOS / GOARCH taken from TARGETOS / TARGETARCH, so the Go stage cross-compiles and no step runs under emulation. Safe path: features/docker_image_platforms.feature (part of make test, it reads the Dockerfile the way BuildKit resolves those arguments) and make check-image, which builds the image and reads each binary.

Documentation

• Do not add a user-visible capability, change what a documentation page describes, or add a tool, a slash command, an environment variable or a key without carrying the change into docs/ in the same pull request: the page under features/, surfaces/ or operate/, its entry in docs/nav.yaml, the reference of its kind, a screenshot on the page when the change is visible in the web UI or the console. make docs-check catches a missing map entry, a broken link and an unused asset, but it cannot tell that a paragraph went stale - that is what the review is for. Safe path: git grep -n '<key or command>' docs/ before the change, update every hit, then make docs.
• Do not commit screenshots or videos that no page references, and do not put pull request evidence under docs/assets/. Do not delete or move a page without repairing the links make docs-check reports and republishing the site layer (make site-docs).
• Do not edit inside a <!-- docsgen:*:start --> block by hand; change the source (nav.yaml, the schema description, printUsage) and run make docs.

Embedded UI

• Do not treat a UI change as complete when only external/ui/src/ moved. The binary serves go:embed assets, so unrebuilt sources ship the previous SPA. Safe path: run make build TAGS="http ui" and include the regenerated assets in the change.

HTTP API development flow

When changing behavior for the OpenAI-compatible HTTP gateway or bundled UI:

• Add or update tests first (red), then implement (green). The happy path of a feature (and a bug's reproduction) is a Gherkin spec in the repo-root features/ directory, run by a godog harness (e.g. external/httpserver/bdd_*_test.go); edge/error cases go in ordinary unit tests, not features/. See the paired workflow rule.
• If the external HTTP surface changes, update external/httpserver/openapi.go so the served OpenAPI matches handlers in external/httpserver/server.go.
• Keep docs/reference/http-api.md aligned with the live behavior.
• For UI changes, update sources under external/ui/src/ and rebuild embedded assets via make build TAGS="http ui" (runs npm via make ui-build).
• Every UI edit in a PR ships with a screenshot of the surface it changed (before/after when the surface already existed) — see step 5 of the paired workflow rule. If a surface cannot be captured, say so in the PR instead of omitting it.
• Run make test (the express run over the shipped tag set), then make lint. The tag matrix runs in CI on the pull request; do not walk it locally.

UI sources (external/ui/)

DESIGN.md is the contract for layout, tokens, and SPA component behavior. After changing external/ui/src/, rebuild embedded assets with make build TAGS="http ui" before relying on go:embed.

The composer exposes Mode (agent / plan / ask) and a separate Model YAML backend selector (metadata.model; every row of GET /v1/models but the agent / plan / ask profiles, told apart by their id: a provider row may itself be named coddy). A new chat takes the model the cookie coddy_llm_model remembers when it is still listed, else the alphabetically first YAML row; the row that response marks default: true (what a session with no selection runs on: agent.model, or the first models[] row when it is not listed) is for API clients and the remote console and does not drive the pick. Parallel POST /v1/responses per session, Stop (cancel + partial assistant persistence), and transcript merge after GET .../messages are specified in DESIGN.md (Multi-session streaming and Stop) and docs/surfaces/web-ui.md.

MarkdownLineEditor (external/ui/src/ui/markdown/) is the shared markdown body editor (line gutter, wrap-aware numbering, active-line highlight, content-driven height). Used in the plan document card and scheduler job body. Visual and behaviour contract: DESIGN.md (Markdown line editor, Plan mode plan document card); functional checklist: docs/surfaces/web-ui.md.

UI localization lives in external/ui/src/ui/i18n/ (translate/t, I18nProvider + useT()). locales.ts is the single registry that connects each supported locale to its picker label and dictionary; English and Russian ship today. Add a locale by adding its dictionary and one registry entry — picker options, locale validation, bootstrap, and parity coverage derive from that registry. In Russian copy the adjective for agent/agentic is агентный, never агентский; a spawned agent is a субагент, never сабагент; a git worktree stays worktree, never рабочее дерево (the paired Russian wording rule - Cursor, Claude Code - held by ruWording.test.ts; git grep -n -i 'агентск' and git grep -n -i 'сабагент' find nothing but the rules that forbid them). When user-facing copy is added or changed on a localized surface, add the key to every registered dictionary in the same change; messagesParity.test.ts enforces key and interpolation-token parity. Counted copy ("N tasks") goes through translatePlural / tp(key, count) with one entry per CLDR category (key.one / key.few / key.many / key.other) so each language declines by number; a locale must carry exactly the categories its own Intl.PluralRules produces. main.tsx bootstraps locale (?lang= > cookie > navigator.language) and wraps <App/> plus the shared confirmation provider in <I18nProvider>. The language picker is in Settings → Appearance, under the theme grid (AppearanceLanguagePicker); cookie coddy_ui_lang mirrors coddy_ui_theme (client-side only, no config save). Appearance, Settings, shared destructive confirmation dialogs, and the conversation surfaces (nav, hero, composer, messages, prompts, plan card, History, scheduler, background tasks, env banner) and the swarm screen (including the topology graph) are translated. Visual contract: DESIGN.md (Localization and language); functional checklist: docs/surfaces/web-ui.md.

Python samples (examples/)

See examples/README.md for layout (examples/httpserver/, examples/acp/, examples/shared/). Scripts may use a project-local interpreter (.venv recommended); follow each script header for prerequisites.

• examples/build_coddy.sh - runs make build TAGS="http scheduler memory" (override TAGS as needed) and prints coddy -v.
• examples/test_acp.sh - wrapper that runs examples/acp/test_acp.sh (all ACP acp_*.py demos in one pass).
• examples/test_httpserver.sh - wrapper that runs examples/httpserver/test_httpserver.sh (temp coddy serve, all HTTP harnesses including http_e2e_scheduler_api and http_e2e_scheduler_agent).

Example HTTP scripts that call completion endpoints expect a reachable provider and return non-zero on HTTP errors.