AGENTS.md git:20260902.518ee05A

Immutable. This exact content never changes and is served at /api/v1/blob/a04fc9e5e5a926ee.

# Kocoro Project Guide (AGENTS.md)

**Condensed mirror of `CLAUDE.md`** — rules + greppable symbols. If they
disagree, `CLAUDE.md` and the code win.

**Keep this file under 24 KB (CI asserts)** — cut prose, not rules. Within
1 KB of the ceiling, adding bytes requires cutting at least as many from this
file (CI asserts).

Kocoro is the Go CLI/runtime (`shan`) for Shannon agents. Production: daemon +
Desktop + Cloud. Also TUI, one-shot CLI, MCP, schedules.

Layout: `cmd/` (Cobra) + `internal/<pkg>/`; `daemon/` drives `agent/`.

## Working Rules

- `go.mod` is the source of truth for the Go version.
- Prefer existing repo patterns over new abstractions; keep changes tied to the task.
- Verify API response bodies, not just status codes.
- No parallel `_enhanced` variants — update existing code in place.
- Risky behavior changes keep operator-visible flags, rollback paths, focused tests.
- Test locally before pushing dependency or generated-code changes.
- New `const max[A-Z]\w+ = <small_int>`: the comment MUST name (1) the workload,
  (2) the symptom when it binds, (3) the override path. Prefer
  `viper.SetDefault(...)` for liftable caps. Re-check small-int caps on
  model-family upgrades — 200K-era defaults bind silently at 1M.

## Doc Co-Maintenance

Feature changes update `README.md`, `CLAUDE.md`, and this file.

**The bundled `kocoro` skill is the AI-facing source of truth for the daemon HTTP
API.** Every `mux.HandleFunc(...)` in `daemon/server.go` the agent calls
needs a matching `skills/bundled/skills/kocoro/references/*.md` entry in
the SAME PR. Desktop-only transport endpoints stay out; their contract lives in
`docs/desktop-wire-fixtures/`.

## Tools

- **Required fields**: every `Run()` MUST check each `ToolInfo.Required` field is
  non-zero right after `json.Unmarshal` and return `agent.ValidationError(...)`,
  NOT a bare `ToolResult{IsError: true}` (Go can't tell missing from zero). The
  `[validation error]` prefix is load-bearing:
  `LoopDetector.isValidationErrorSig` force-stops on 3 consecutive.
- **Priority**: local > MCP > gateway, deduped by name. MCP-vs-MCP collisions
  resolve to the alphabetically-first server (`RebuildRegistryForHealth`); the
  shadowed tool is logged, never registered.
- **Exposure** (`agent/exposure.go EffectiveToolExposure`): explicit
  `ToolExposure` first, then source default — local Direct; MCP/gateway/
  integration Deferred. `ask_user_question` is explicitly Direct. `web_search` /
  `web_fetch` / `x_search` are Direct **only when `ToolSource()==SourceGateway`**
  (`tools/exposure.go ServerTool.ToolExposure`); a same-named MCP or integration
  tool keeps its Deferred default so a third-party catalog cannot widen the base
  schema surface. GUI/process automation and calendar/schedule mutations are
  Deferred; calendar/schedule reads stay Direct.
- `tool_search` uses deterministic BM25 (`agent/toolsearch_index.go`,
  `toolSearchDefaultLimit` 8) with exact `select:` lookup. The 16K Direct-schema
  budget is a regression diagnostic and MUST NEVER reclassify tools at runtime.
- Skill `allowed-tools` is execution-time denial, NOT schema filtering — the tools
  array stays byte-stable for the prompt cache. `agent.SkillExempt` (`think`,
  `tool_search`, `use_skill`) is for pure infrastructure only; do NOT exempt
  side-effecting tools.
- **Concurrency**: the dispatcher batches by `IsConcurrencySafeCall`, not
  `IsReadOnlyCall`; tools without a `ConcurrencySafeChecker` fall back to their
  `IsReadOnlyCall` value. `BashTool` implements it in `tools/bash_concurrency.go`,
  gated by `agent.bash_concurrency_enabled` (default true): only a strict
  read-only leading token AND no shell metacharacters (incl. `\n` / `\r`) is
  eligible; everything else stays in a size-1 serial batch.
- `tool_status` running/completed carry `tool_use_id` (capability
  `tool_use_id_events`).
- `set_work_plan` (`daemon/work_plan.go`): full-snapshot 2–8-step checklist,
  daemon non-ephemeral runs only. Runtime owns
  plan_id/revision/lifecycle/close_reason; closure comes from `LastRunStatus`,
  never a model claim, and bumps the revision. `work_plan.updated` fires only
  after the covering save. Not dup-exempt; `SkillExempt`; never journaled.
  Capability `work_plan_v1`.
- Every `RequiresApproval()==true` tool needs a `description` (5-15 words,
  model-written). The daemon does NOT block on a missing one; UI clients MUST use
  `description?.trim() || fallback`, NOT nullish coalescing.
- Integration `requires_approval=true` → normal approval flow
  (`daemon.auto_approve` bypasses); Always Allow persistence refused —
  `DisallowsAlwaysAllowPersistence` gates flag/broker/persist/runtime; stale
  `always_allow_tools` entries ignored. Config writes (incl. agent-sync pull)
  drop denied entries (`dropRegistryDeniedAlwaysAllow`, registry miss keeps);
  `RefreshIntegrationTools` + `resetIntegrationToolsForPrincipal` prune after
  rebuild (`pruneDeniedAlwaysAllowGrants`). Drop skips the LWW stamp; both
  prunes push on write. Absent=false; Cloud gates marked schemas on
  `integration_requires_approval`.
- Trusted `material_side_effect=false` permits observational batching without
  the journal; absent is fail-closed. Stable `request_id`; material calls add
  `Idempotency-Key`. Only `provider_unavailable`/`provider_rejected` are
  known-no-effect. Preserve provider/model/unit/cost via `ToolResult`/`EmitUsage`.
  Exhausted `call_in_progress` → `outcome_unknown`: never resend under a new ID.
- Outcome-unknown material results narrate as ordinary tool errors; the
  same-turn latch (`agent/unknown_outcome_gate.go`) blocks byte-identical
  tool+args repeats until the next user message.
- SourceIntegration is identity-scoped. Key mutation invalidates generations
  before source clear, without the dispatch writer. Failed new-identity listing
  leaves it empty; same-identity refresh failure keeps it. ServerTool binds list
  credential/principal generation; stale clones fail pre-dispatch, caches can't
  revive them. Auth/integration/MCP-health/reload swaps share one lock. Auth
  rebuilds both overlays: credential-bound cloud/publish/image drop,
  calendar/non-auth tools survive. `cloud_delegate`, publish/list/retract, and
  generate/edit lease generation through all `Run` retries. Serialize auth
  across accounts/keys.
- X publishing only via Cloud X tools (`x_prepare_post` removed).
  `browser`/`computer_use`/builtin Playwright block X composer/publish
  controls; Playwright omits `browser_run_code`/`browser_evaluate`; CDP: any
  X target blocks mutation; non-CDP: no claim; shell/custom MCP unguarded.

## MCP

- Probe and reconnect a supervisor-known-disconnected server BEFORE dispatch.
- Every tools/call is bounded by per-server `tool_timeout_secs` >
  `mcp.tool_timeout_secs` (`mcp.DefaultToolCallTimeout` 300s); an earlier caller
  deadline still wins.
- A post-dispatch transport failure repairs the connection but re-dispatches ONLY
  `mcp.ToolReplaySafe` tools (read-only/idempotent annotations) — a transport
  error after dispatch does NOT prove the server never acted. Everything else
  returns `mcp.OutcomeUnknownError`. Timeouts/protocol errors are never retried.
- A failed async connect is NOT terminal: `ReconnectScheduler`
  (`mcp/reconnect.go`) backs off 5s → 5min, `reconnectMaxAttempts` 6.
  Retries are owned by the manager generation (`SwapMCPReconnectScheduler`,
  `ShutdownCleanup`) so a timer never respawns a subprocess the cleanup is
  reaping. `ForgetMCPReconnect` re-arms an exhausted streak.
- Stdio subprocesses spawn in their own process group, killed via `-pgid` SIGTERM
  + 3s SIGKILL.
- Artifact paths: servers with known path semantics (playwright, or any
  `workspace_base`) get "Saved to:" absolute annotations for files that exist.
  Screenshot filenames default into `~/.shannon/tmp/sessions/<id>/` (swept by
  `daemon.scratch_max_age_days` 14). **`browser_snapshot` NEVER gets a default
  filename** — omitted = inline accessibility snapshot. Model-supplied absolute
  paths always win.

## Permissions and Approvals

```text
hard-block -> denied commands -> compound splitting -> always-ask gates
  -> allowed commands -> default safe -> approval + safe checker
```

- Always-ask runs BEFORE allowlists, so adding a high-risk command to
  `allowed_commands` is a no-op. Unknown tools are denied.
- "Always Allow" on an always-ask command is honored once and NEVER persisted
  (enforced at write time in `cmd/daemon.go` + `server.go`, at runtime in
  `loop.go checkPermissionAndApproval`).
- `HandleAlwaysAllowDecision` (`alwaysallow.go`) is the single decision path
  shared by SSE and WS so transports cannot drift.
- Two deny-lists in `agent/tools.go`: `autoApprovalDenyList`
  (`DisallowsAutoApproval`) = `computer`, `accessibility`, `applescript`,
  `ghostty`; `unattendedAutoApprovalDenyList` (`DisallowsUnattendedAutoApproval`)
  = those four plus `computer_use` and `screenshot`.
- `computer_use` is deliberately absent from the FIRST list — its persisted
  global grant IS the product's Computer Use permission, honored even unattended,
  scoped BY NAME via `unattendedGrantHonored`. Legacy GUI names never use the
  global grant; per-agent `computer_use` is rejected
  (`agents.ValidateAgentPermissionsConfig`) — the grant is global-only.

## Wire Contracts

- **The surface list is `docs/cloud-contract-surface.md`** — what this repo owes
  Shannon Cloud and Kocoro Desktop, with each counterpart symbol. Read it before
  changing anything that crosses a process boundary.
- Payloads decoded by UI clients are pinned by fixtures in
  `docs/desktop-wire-fixtures/` (verified by `wire_fixtures_test.go` through the
  REAL producer path). Change a payload → update fixture + test in the SAME PR.
- Every cross-version contract change mints a capability token in `Capabilities`
  (`daemon/client.go`), surfaced on the WS handshake and `GET /status`.
  Clients gate on tokens — NEVER version sniffing or decode-failure probing.
- New event domains use dotted types with a common envelope; existing flat types
  are additive-only, never repurposed.
- `ApprovalBroker` and `QuestionBroker` are thin faces over ONE shared
  `pendingCore[D]` (`pending.go`). A third interaction kind MUST build on it — do
  NOT copy a broker.
- `ask_user_question` gates on `CanPresentQuestionUI` / `questionUISources` — an
  ALLOW-list, NOT the approval predicate: sources without a question UI DECLINE
  (IM channels have approval cards but no question channel). Capability
  `question_v1`. Ephemeral runs get no asker (`shouldInjectQuestionAsker`).
- Conversation context actions (`conversation_context_actions_v1`, Desktop-only):
  `POST /sessions/{id}/{fork,side-chat}`; `message_index` = RAW-archive turn
  boundary (injected entries counted). Side chats run the NORMAL tool registry +
  SSE approvals but stay ephemeral. Reply envelopes strip head-only, only when
  they parse; limits 400 at `/message` + `/queue`.
- `delivery_ack`: ack an inbound message only AFTER reply delivery succeeds.
  Reply-failure paths skip the ack so replay stays correct.

## Daemon Routing

- Precedence: explicit session, threaded route, per-sender route, agent route,
  legacy channel route. Named agents are multi-session. Routed managers are
  long-lived; bypass/heartbeat short-lived. `tool_status` `running` fires only
  when execution actually starts.
- Config reload is revision-based over ONLY `~/.shannon/config.yaml`
  (`config_reload_state_v1`). Project/local overlays are not watched; never
  advance the applied revision after an unrelated internal mutation.
- Schedule proactive push: `broadcast` (`auto`/`on`/`off`) gates IM push. **The
  target is always the creating channel** (snapshotted `im_status_context`) — a
  schedule created outside an IM chat NEVER pushes, even with `broadcast=on`.
  `thread` → `ProactivePayload.UseThread *bool`: `nil` = anchored, only explicit
  off goes top-level. The two capability tokens are observability only.
- Output profiles, not per-channel syntax: `markdown` default, `plain` for
  Cloud-distributed channels. Feishu/Lark/Teams are cloud sources that stay
  `markdown` (`markdownCloudSources`); WeChat (iLink) stays `plain`.

## Turn Lifecycle and Context

- Only `PhaseAwaitingLLM` / `PhaseForceStop` count as idle (`agent/phase.go`;
  fail-closed, panics under `testing.Testing()` or `SHANNON_PHASE_STRICT=1`).
  Defaults: `agent.idle_soft_timeout_secs` 90, `agent.idle_hard_timeout_secs` 540,
  `agent.stream_idle_timeout_secs` 90.
- Mid-turn checkpoints run after tool batches, after reactive compaction, before
  force-stop; the final save rebuilds from the same baseline.
- Interrupted turns auto-resume at daemon start (newest first, serial) only
  within `agent.interrupted_resume_max_age_hours` (default 4) — older checkpoints
  are abandoned, NEVER executed. Attempt cap (default 3) persists BEFORE the LLM
  call. Recovered runs ALWAYS classify as unattended and pin the original route
  key.
- `agent.context_window` (default 1_000_000) is only a seed;
  `maybeAutoAdjustContextWindow` resets it from `response.model` via
  `agent/modelcontext.go` unless a per-agent override locks it.
- Keep proactive / pre-flight / reactive compaction as SEPARATE gates so context
  errors do not cascade. Thresholds are absolute-buffer complements of the
  fractional lines (`compactAbsoluteBufferTokens`), sized so a compaction cannot
  immediately re-trigger; see CLAUDE.md for the exact formulas.
- Estimate-based gates MUST share the trigger's scale via `estOverheadTokens`,
  persisted in `Session.CompactionCalibration` and restored through
  `SetEstOverheadState` with model-pin and registry-fingerprint validation.
- Summarizer input is budgeted in TOKENS (`summarizeInputCapTokens` 150_000 via
  `conservativeBytesPerToken` 2.5). **Do NOT gate this on `EstimateTokens`** — its
  3.5 chars/token is representative, not conservative. Over-cap transcripts fold
  chunk by chunk (tool pairs atomic, `maxSummaryFoldChunks`) with head+tail fallback.
- Compaction NEVER rewrites the lossless `Session.Messages`;
  `Session.CompactionCheckpoint` is the separate model-live state. Proactive/
  pre-flight re-inject recently read files; reactive skips restoration. Every
  applied compaction snapshots pre-replacement state (`<private_memory>`
  stripped, images → text markers); snapshot failures never block it.
- Tool-result budgeting: per-result spill (`DefaultMaxToolResultSizeChars` 50K,
  grep 20K), per-turn `aggregateCapThreshold` 200K runes, persisted
  replacement/seen maps surviving turns and crash recovery. `file_read` is
  `UnlimitedToolResultSizeChars`, self-bounding at `fileReadHardCapRunes` 500_000.
- Images/attachments: source-time compression, wire-time `filterOversizeImages`,
  persist-time `SanitizedRunMessages`. Any new path MUST pass all three. Caps:
  500 MB/file, 20/msg, inline doc <= 25 MB raw.
- Thinking blocks: preserve `thinking` / `redacted_thinking` in order —
  sanitizers, compaction, fork builders, persistence MUST NOT rewrite them; strip
  only before sync upload (`internal/sync/strip_thinking.go`). The local `think`
  tool skips the default gateway+thinking path (`shouldRegisterThinkTool`), stays
  for disabled-thinking, Ollama, `ForceThinkTool=true`.

## Prompt Cache and Suggestions

- Cloud owns TTL policy. `cache_source` is attribution only, never a Kocoro-side
  TTL selector; preserve `normalizeToolInput` canonicalization. Skill listing
  lives in the scaffolded user message, not the system prompt.
- Any in-place `messages[idx].Content` rewrite MUST call
  `client.LogCacheCompactEvent` — uninstrumented rewrites break drift attribution.
- A rewrite pass MUST NOT run per iteration: a per-turn sliding window advances
  the divergence point every turn and charges cache WRITE for the suffix behind
  it. Fire on a cold prefix or budget — `observation_trigger.go`.
- `agent.response_detail` renders final-answer guidance in BP3 StableContext:
  missing/empty → `balanced` (named agents inherit global), request effort
  unchanged; strict internal loops suppress it explicitly.
- The suggestion fork MUST be byte-equal to the main request except the appended
  reply, suggestion prompt, `SkipCacheWrite`, and fork kind — no tool/max-token/
  thinking/ordering changes. `wantsPromptSuggestion` is an ALLOW-list (`desktop`,
  `kocoro`, `shanclaw`, `web`), so new background sources default to skipped.

## Skills

- `builtinSkills` (`skills/api.go`: `kocoro`, `kocoro-generative-ui`) sync from
  `embed.FS` every startup — user edits are WIPED; fork under a new name.
- `daemon/skill_filter.go` filters `desktopOnlySkills` from the per-request list
  on cloud sources, applied ONCE producer-side right after `LoadGlobalSkills`
  so registry, listing, and semantic discovery stay
  consistent. Drift test `skill_filter_test.go`.
- Skill-install recommendation discovery is binary-pinned and OFFLINE: production
  uses only the embedded eligible catalog (`official_catalog.json`), never the
  GitHub/static/ClawHub registries.
- Two marketplace surfaces MUST NEVER share a response shape:
  `/skills/marketplace/*` (static registry, integer-page — **frozen macOS Desktop
  contract, no source-conditional branches**) and `/skills/clawhub/*` (live
  catalog, opaque cursor). Catalog GETs retry 429/5xx + network
  (`doGETWithRetry`); **4xx never**. `exclude_installed` is ClawHub-only,
  page-granular: when `clawhub_exclude_fill_max_pages` (default 5) binds, the
  page is short/empty with a non-empty cursor and the client MUST keep paging.
- Skill secrets: Keychain `com.shannon.skill.<name>` + a plaintext index of key
  NAMES only, env-var-only injection scoped to the current run's `use_skill`.

## Memory, Sync, Browser Bridge

- Daemon owns sidecar lifecycle; CLI/TUI attach/probe. Bundles:
  `[0.4.0,0.9.0)`; 0.8 W-prior, 0.9 breaking. **API keys never hit disk or
  logs** — only a `sha256[:16]` fingerprint.
- Episodic recall is model-driven: production paths expose `memory_recall` and
  `session_search` directly, never the implicit small-model preflight. Unnamed
  references → session search; stop after a structured no-data. Keep sidecar
  `temporal_status` on recall groups (prefer `current` unless asked about the
  past); preserve unknown sidecar group fields on the round-trip. `aggregator`
  is `direct_relation` only.
- Session sync is opt-in: single Run entry point, flock, atomic markers,
  per-session ACKs. Permanent failures remain until the source session changes.
- Browser file previews stay fail-closed: only effective session CWD and attached
  paths, symlinks resolved on both sides, random tokens, no directory listing,
  teardown on session close.

## Config, Locking, Cross-Platform

- Merge order: global → project → local project. Scalars override, lists
  merge/dedup, structs merge field-by-field. MCP env var casing is preserved by
  direct YAML re-read.
- Persistent JSON indexes use write-temp + rename + an exclusive lock via
  `internal/fslock`, NOT raw `syscall.Flock`. **Never delete lock files** — that
  splits locks across inodes. Rename targets are read lock-free and never locked
  directly; a mandatory `LockFileEx` on the destination would block
  rename-over-open on Windows.
- Cross-compiles to macOS / Linux / Windows with `CGO_ENABLED=0`. Build-tagged:
  `internal/fslock` (flock vs `LockFileEx`), per-package `*_proc_{unix,windows}.go`
  (`Setpgid`+`Kill(-pid)` vs `CREATE_NEW_PROCESS_GROUP`+`taskkill /T /F`),
  `cmd/proc_signal_{unix,windows}.go`,
  `internal/memory/bundle_link_{unix,windows}.go` (symlink vs directory junction),
  `internal/keychain/backend_{keyring,linux,other}.go`.
- Runtime callers MUST gate on `keychain.Supported()` (darwin||windows||linux),
  never raw `runtime.GOOS`; pinned by `TestSupportedMatchesBuildTag`. Pass
  `config.ShannonDir()` to `NewOSStoreAt`. Linux uses a 0600 file store, NOT
  go-keyring's Secret Service (constructs fine, fails every read/write headless).
- **Do not reintroduce raw `syscall.Flock` / `syscall.Kill` / `Setpgid` /
  `os.Symlink` outside a `_unix.go` file** — it breaks the Windows build or fails
  unprivileged there.
- macOS-only GUI tools, including `computer_use`, gate on
  `runtime.GOOS != "darwin"` with a clean error; `notify` is exempt.

## Auth

`/local/auth/*` proxies to Cloud `/api/v1/auth/*`. `AuthManager`
(`daemon/auth.go`) owns the state machine, emits `auth_state_changed`.
**WS runs ONLY in `signed_in`; `WSController.Start`/`Stop` are the only allowed
reconnect-loop call sites.** api_key is source-of-truth in the credential store
(`ai.kocoro.daemon.api_key`); access/refresh tokens RAM only. On
`!keychain.Supported()`: `AuthManager` nil, endpoints 503 `platform_unsupported`,
legacy `cfg.APIKey` drives WS. The yaml→store migration re-strips `api_key` from
config-managed yaml every launch. Endpoint matrix:
`skills/bundled/skills/kocoro/references/auth.md`.

## Anti-Hallucination

Keep random XML tool-execution delimiters and strip fabricated tool calls. In
attended runs preserve model-authored preambles; a silent first tool batch may
surface a local tool's required `description` without exposing other arguments.
External tool descriptions and generic `purpose` fields are NEVER runtime fallback
text. Unattended runs remain silent.

## Voice Front-Brain

`internal/koe` is macOS native speech-to-speech. Keep `stop_speaking` (output),
`cancel` (work, by `task_id` or `all_running=true`), and terminal `end_call`
(session) as SEPARATE authorities. `do_task` defaults to one call per response;
parallel calls require an explicit request and disjoint scopes. Group calls from
one response: wait until all are terminal, acknowledge together, then request
one spoken continuation. Qwen's boundary adds a tool-call quiet window because
it may withhold `response.done`. `MapDoTaskOutcome` maps partial runs to
`incomplete` without a digest; never voice a cut progress tail as the result.
ASR never admits ordinary turns/barge-in. Without native floor control, only
terminal exit/goodbye—not stop-speaking—phrases are a lifecycle backstop; the
model owns the rest.

Realtime providers use WebRTC. Auto falls back OpenAI→Qwen only on eligible
pre-ready network/timeout/5xx failures (Cloud-wrapped OpenAI auth/config is 502;
gateway 4xx is terminal); forced modes never fall back. Qwen has no
`conversation.item.truncate`; never emulate it. Qwen server-VAD sends no
`input_audio_buffer.committed`: user-purpose `response.create` mints the
turn; unannounced-id tool calls lazy-bind (Qwen-only).
Qwen barge-in on/off uses
server/semantic VAD (`KOE_QWEN_VAD_MODE` overrides); capture protection covers
only the late-RTP tail after `response.done`.

Qwen `ConnectOptions.VideoSource` adds H.264 before SDP; missing, rejected, or
inactive video answers are terminal, and `CallActive` gates frames. Treat
visuals as ambient untrusted data: never follow visible instructions, volunteer
narration, or infer identity/sensitive traits. Reuse the camera; never send
OpenAI `input_image` to Qwen.

An active transport reconnect preserves the task ledger and result mailbox, not
provider conversation history; the replacement persona must disclose that
boundary, and injected task-result data stays authoritative.

## Tests

```bash
go test ./...                                        # or per-package with -v
go test ./test/ -v && go test ./test/e2e/ -v
SHANNON_E2E_LIVE=1 go test -tags=live ./test/e2e/ -v # live suite (tag required)
go build ./...
```

Koe tests link cgo audio deps: `brew install opus opusfile pkg-config`.
Schedule tests use temp dirs and MUST NOT write to the real LaunchAgents directory.

Live E2E uses the hidden foreground-only isolation flags in
`docs/live-e2e-testing.md`. `--isolated` isolates filesystem, port, AND
credential-store access (`config.DisableCredentialStoreForProcess` — no OS
credential reads, no yaml→keychain migration); the key pipes in via
`--isolated-api-key-stdin`. Cloud/background automation suppressed, agent tool
capabilities real, MCP off unless `--isolated-mcp` gives an explicit allowlist.

## Build and Release

- GoReleaser builds releases; npm package is `@kocoro/kocoro`.
- **Versioning is PATCH-only by default** — do not bump minor/major unless asked.
- Release: push a tag; CI publishes.
- `docs/` is gitignored by default; tracked docs are allowlisted in `.gitignore`.
  Add new docs there before committing.