# Internals & Maintainers

> A compact map for people changing Kin. Everyday usage belongs in the task guides; this page points to the implementation contracts, verification discipline, and decision record.

A compact map for people changing Kin. Everyday usage belongs in the task
guides; this page points to the implementation contracts, verification
discipline, and decision record.

<!-- SOURCE: AGENTS.md, CONSTITUTION.md, STATUS.md, REFERENCE.md, Taskfile.yml, docs/decisions/ -->

## Start with the owning document

- [STATUS.md](https://github.com/kinra-ai/kin/blob/dev/STATUS.md) — a bounded,
  actionable view of active proofs, ranked next work, blockers, and recent
  landings. Git history remains the journal of record.
- [CONSTITUTION.md](https://github.com/kinra-ai/kin/blob/dev/CONSTITUTION.md)
  — the AI-peer engineering contract, governing principles, and deliberate
  negative space.
- [REFERENCE.md](https://github.com/kinra-ai/kin/blob/dev/REFERENCE.md) —
  security invariants, footguns, and postmortems, organized by symbol and
  topic.
- [PROTOCOL.md](https://github.com/kinra-ai/kin/blob/dev/PROTOCOL.md) — the
  Outpost v1 wire contract; use the [protocol index](/docs/kin/protocol/) for
  navigation.
- Tier guides:
  [harness](https://github.com/kinra-ai/kin/blob/dev/src/kin/harness/AGENTS.md),
  [TUI](https://github.com/kinra-ai/kin/blob/dev/src/kin/tui/AGENTS.md), and
  [Outpost](https://github.com/kinra-ai/kin/blob/dev/container/AGENTS.md).

## Maintainer paths

- [Testing](/docs/kin/internals/testing/) — focused repair loops, the exhaustive local promotion
  gate, markers, fixtures, and isolation.
- [Extending tools](/docs/kin/internals/extending-tools/) — add a built-in tool, permission kind,
  event, or profile without breaking the harness seam.
- [Multi-machine setup](/docs/kin/internals/multi-machine-setup/) — matched development machines
  and build-worktree separation.
- [Outpost operations](/docs/kin/internals/outpost-operations/) — deployment, SSO/proxy,
  lifecycle, machine-door, and dashboard implementation detail.
- [Automation operations](https://github.com/kinra-ai/kin/blob/dev/docs/internals/automation-operations.md) — scheduler, governor,
  reliability, APIs, and verification.
- [Rig operations](https://github.com/kinra-ai/kin/blob/dev/docs/internals/rig-operations.md) — persistent-computer deployment, tool,
  and VM detail.
- [TUI snapshots](https://github.com/kinra-ai/kin/blob/dev/tests/test_snapshot.py)
  and [browser captures](https://github.com/kinra-ai/kin/blob/dev/scripts/docs_screenshots_web.py)
  — the ten TUI and five browser guide-capture owners. See the generated-asset
  discipline in
  [snapshots/README.md](https://github.com/kinra-ai/kin/blob/dev/snapshots/README.md).

## Decision records

Each row is intentionally limited to the decision title, recorded status, and
one-sentence purpose. Open the record for context, rejected alternatives,
consequences, and references.

| Decision | Status | Summary |
|---|---|---|
| [0160 — Qwen / llama.cpp bounded-thinking model route](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0160-qwen-llamacpp-bounded-thinking-route.md) | Accepted 2026-08-09 | Adds an explicit route-local Qwen profile with token-budget labels, pinned llama.cpp wire mapping, Utility final-answer headroom, and structural absence for every unrelated provider. |
| [0156 — Provider-neutral context admission and exact Responses counting](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0156-provider-neutral-context-admission.md) | Implemented 2026-08-07 | Removes the unused provider-specific surface, generalizes one-shot context/body rejection recovery, and lets advertising Responses endpoints supply exact proactive admission counts. |
| [0151 — The model's own network-shaped shell/run_code output is framed untrusted](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0151-frame-model-network-shell-output.md) | Accepted 2026-08-01 | DR 0075 framed the human's `!curl` but the model's own `curl`/`wget`/`urllib` output entered history unframed (a zero-approval injection vector in auto mode); `shell`/`run_code` now frame output when the command/code is network-shaped, best-effort, keeping local output clean. |
| [0150 — run_code never joins the "always allow this session" tier](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0150-run-code-never-reusable-grant.md) | Accepted 2026-08-01 | run_code's signature is the generic `tool:run_code`, so one "always" auto-ALLOWed arbitrary Python for the session; `approval_reusable → False` (the force-push precedent) makes the modal once/deny only, with interpreter head grants recorded as a named non-goal. |
| [0149 — Protected-write footholds are denied at the sandbox, not just the EDIT gate](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0149-protected-write-via-sandboxed-shell.md) | Accepted 2026-08-01 | A sandboxed auto-mode shell could silently rewrite `.envrc`/`.mcp.json`/`.kin` config where the EDIT tools ASK; both sandbox backends now write-deny the foothold/harness-config files (keeping reads), deliberately excluding lockfiles (whose sandboxed-shell write is the normal path) and correcting the container-mode REFERENCE claim. |
| [0148 — Secret-path reads never auto-run through shell](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0148-secret-read-via-shell.md) | Accepted 2026-08-01 | A shell command that lexically names a credential store (`~/.ssh`, a project `.env`, …) is downgraded from any ALLOW to ASK with no "always" tier, and the sandbox now masks kin's own `~/.kin/settings.toml`/`mcp.json` — the allowlist stops undermining the read tools' secret deny without being promoted to a boundary. |
| [0147 — Shell-path nested guidance — the tool-authored `guidance_paths` seam](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0147-guidance-paths-seam.md) | SHIPPED 2026-08-01 | Amends DR 0073: the READ/EDIT+path trigger gate becomes the default of a tool-authored `guidance_paths` seam; shell/run_code override it with a bounded raw-text extractor, and dir-valued paths walk dir-inclusive for every tool. |
| [0146 — Provider keys are collected at the point of need; the hub keeps sole writer authority](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0146-point-of-need-provider-key-entry.md) | Accepted 2026-07-30 | Amends DR 0142's surface rule: a no-key `/model` pick opens a one-field key prompt right there instead of refusing toward the hub; the locked hub transaction stays the sole writer. |
| [0145 — Project MCP config is kin-owned at `.kin/mcp.json`; a root `.mcp.json` is adoption material](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0145-kin-owned-project-mcp-config.md) | Accepted 2026-07-30 | Stop auto-loading (and writing) the cross-tool `.mcp.json` at the workspace root: kin reads its own file, and a foreign file becomes something you adopt explicitly. |
| [0144 — Type gate for the Textual client](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0144-type-gate-for-the-textual-client.md) | Accepted 2026-07-24 | Extend the `ty` gate from the harness to `src/kin/tui` by declaring each mixin's `self` contract with the session-islands idiom; `container/` stays out of scope. |
| [0143 — MCP OAuth for pre-registered clients](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0143-mcp-oauth-preregistered-clients.md) | Accepted 2026-07-24 | Reach authorization servers that never implement dynamic client registration, without weakening the loopback + PKCE posture or adding a second credential surface. |
| [0142 — Job-first model configuration hub](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0142-job-first-model-configuration-hub.md) | Accepted 2026-07-22 | Stage and atomically apply human-owned jobs, connections, credentials, routes, and assignments without changing the TOML schema or model-write boundary. |
| [0139 — Named model routes for role-specific inference](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0139-named-model-routes.md) | Accepted 2026-07-21 | Bind the MCA, semantic vision, Rig, tasks, workflows, and agent profiles to operator-owned provider/model routes without coupling orchestration to a wire. |
| [0138 — Bounded documentation operating model](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0138-bounded-documentation-operating-model.md) | Accepted 2026-07-21 | Keep root and tier docs as ownership maps, bound the actionable status board, and enforce its exact structural claims in the local promotion gate. |
| [0137 — Kin-native skill discovery](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0137-kin-native-skill-discovery.md) | Accepted 2026-07-20 | Discover only Kin-owned skill roots; adapt explicitly named foreign skills through `skill-creator` instead of loading them as live configuration. |
| [0136 — Multiple independent Kin sessions per workspace](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0136-multiple-independent-workspace-sessions.md) | Implemented and verified on dev 2026-07-20 | Give every Kin process a unique managed instance while preserving bare unattended recovery, exact live-conversation ownership, explicit mirroring, and `/fork` as the journal branch. |
| [0135 — Structured Git and GitHub publication boundary](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0135-structured-git-and-github-publication.md) | Implemented on dev 2026-07-20 | Replace recurring Git shell/credential exceptions with bounded daily Git and PR tools, secret-free host-route trust, exact force leases, and an unchanged Beam checkpoint. |
| [0134 — Code is content — conventional syntax semantics in the code band](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0134-code-is-content-syntax-remap.md) | Implemented on dev 2026-07-18 | Stop painting code in brand roles: muted-green strings, bone functions, cyan only on keywords, amber only on numbers, and inline code in body bone on the band. |
| [0133 — The shelf — peer-curated jobs per workspace](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0133-the-shelf.md) | Accepted 2026-07-18 | Track rock-sized future work as durable git cards that can run on Outpost and return through a verified card update. |
| [0132 — get.kinra.ai product front door and independent Paddock channel](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0132-get-kinra-product-front-door.md) | Accepted and deployed 2026-07-18 | Present Kin and Paddock as independent products, make Kin's installer universally useful, and give both release channels disjoint ownership in a durable public docroot. |
| [0131 — Event-driven supervision discourages polling](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0131-event-driven-supervision-no-polling.md) | Accepted 2026-07-18 | State the DR 0117 event contract everywhere the MCA looks and clamp the wait tools, so a healthy running child is never polled, hurried, or killed out of impatience. |
| [0130 — KinMarkdown — the one markdown identity surface](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0130-markdown-identity-kinmarkdown.md) | Implemented on dev 2026-07-18 | Pin every markdown body element to the Graphite+ palette in one class-scoped widget, deleting the fence wiring's global mutation and import-order invariant. |
| [0129 — Typed, scoped sandbox access](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0129-typed-scoped-sandbox-access.md) | Accepted 2026-07-18 | Replace command-pattern sandbox bypasses with capability grants, immutable denial-bound retry, and one human-owned lifetime decision. |
| [0128 — Task-first, screenshot-rich user guide](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0128-task-first-screenshot-rich-guide.md) | Accepted 2026-07-17 | Make the shortest everyday path the guide's organizing principle, while preserving exhaustive operator and implementation material behind it. |
| [0127 — Targeted plan revision under the planning freeze](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0127-targeted-plan-revision-under-freeze.md) | Accepted 2026-07-17 | The adversarial plan-review option deliberately keeps the session in its read-only planning freeze. |
| [0126 — Editable queued input + intentional tool disclosure](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0126-editable-queued-input-and-intentional-tool-disclosure.md) | Accepted 2026-07-17 | The TUI protects the harness from overlapping user turns with one latest-wins queued-message slot. |
| [0125 — Documentation screenshot baselines](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0125-documentation-screenshot-baselines.md) | Accepted 2026-07-17 | Publish three high-information TUI scenes as their own generated snapshot baselines, with a deterministic ownership graph in the promotion gate and machine-sensitive rendering kept outside it. |
| [0124 — Agent-first local promotion gate](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0124-agent-first-local-promotion-gate.md) | Accepted 2026-07-17 | Records the rationale, boundary, and consequences for agent-first local promotion gate. |
| [0123 — Subagents run to completion](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0123-subagents-run-to-completion.md) | Accepted 2026-07-17 | Kin's bundled agent profiles predated model-owned supervision and carried fixed `max-turns` values from 15 to 50. |
| [0122 — TUI timeline presentation + interrupt settlement](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0122-tui-timeline-presentation-and-interrupt-settlement.md) | SHIPPED 2026-07-16 | The timeline should read as a considered work log: calm at rest, specific while active, and visibly terminal when the user interrupts it. |
| [0121 — Tag-gated update channel + kin update](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0121-update-channel-and-kin-update.md) | Tag-gated update channel + kin update SHIPPED 2026-07-16 | Deployed kin instances had no update story — nothing bumped the version, nothing told a user they were stale, and nothing applied an update. |
| [0120 — Cloud-provider hardening and plan-aware subagent capacity](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0120-cloud-provider-hardening-and-plan-capacity.md) | Implemented and live-gated 2026-07-16 | Makes the MiniMax and Z.ai presets reflect their current subscription surfaces, carries provider-tier subagent capacity into live sessions, and turns opaque subscription failures into actionable diagnostics. |
| [0119 — Tier-aware Kimi Code provider](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0119-tier-aware-kimi-code-provider.md) | Superseded by DR 0156 on 2026-08-07 | Historical provider-specific integration removed in favor of provider-neutral context admission. |
| [0118 — Full-context fork_agent delegation](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0118-full-context-fork-agent.md) | Accepted 2026-07-16 | Kin's named `task` agents deliberately start from isolated history. |
| [0117 — Model-owned subagent supervision](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0117-model-owned-subagent-supervision.md) | Accepted 2026-07-15 | Background `task` agents originally reported completion on the next human turn. |
| [0116 — Human-readable agent panel](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0116-human-readable-agent-panel.md) | Accepted 2026-07-14 | The agent panel exposed the right underlying facts but presented them as three equally sized log boxes. |
| [0115 — Network-capable workspace sandbox](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0115-network-capable-sandbox.md) | Recorded | Kin's original auto-mode sandbox coupled two independent boundaries: workspace-confined writes and total network isolation. |
| [0114 — Session nudges supersede Ultracode](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0114-session-nudges.md) | Accepted 2026-07-14 | Replace one overpromising workflow-mode toggle with a small, stackable vocabulary of session-scoped behavioral preferences. |
| [0113 — Hybrid workspace search and bounded grep](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0113-hybrid-workspace-search.md) | Hybrid workspace search SHIPPED 2026-07-14 | Give Kin one stable exact-search contract and one ranked discovery contract, with real CPU and secret-content bounds. |
| [0112 — Durable project prompt history](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0112-durable-project-prompt-history.md) | Durable project prompt history SHIPPED 2026-07-14 | Make the composer's existing ↑/↓ recall and Ctrl+R search survive restarts without making conversation journals own another lifecycle. |
| [0111 — Transparent terminal-ground default theme](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0111-transparent-default-theme.md) | Transparent terminal-ground default theme SHIPPED 2026-07-12 | Let the user's terminal own kin's canvas without giving up Graphite+'s role-based truecolor language or its deterministic opaque fallback. |
| [0110 — Bounded, filterable Outpost supervision](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0110-bounded-filterable-supervision.md) | accepted 2026-07-12 | Keep Activity and Automations calm at a glance without letting filtering hide live work, blur independent truth axes, or pretend a bounded response is complete history. |
| [0109 — Human-friendly Outpost presentation](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0109-human-friendly-outpost-presentation.md) | accepted 2026-07-12 | Translate stable automation and workspace contracts into an approachable daily surface without hiding, renaming, or weakening the underlying truth. |
| [0108 — Adaptive visual system and causal-motion doctrine](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0108-adaptive-visual-and-causal-motion.md) | accepted 2026-07-12 | Let Outpost use hierarchy and motion where they make the product easier to understand, without turning status into theater or weakening accessibility. |
| [0107 — Outpost truth model and five-destination information architecture](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0107-outpost-truth-and-information-architecture.md) | accepted 2026-07-12 | Rebuild the Outpost around the operator's actual questions, with one authoritative meaning for present-tense attention across every projection. |
| [0106 — Retire Matrix for sovereign Kin Chat](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0106-retire-matrix-for-sovereign-chat.md) | accepted and executed 2026-07-12 | Matrix was chosen when the Outpost had no dependable way to reach the operator. |
| [0105 — Graphite v2 — the chat-era Outpost design doctrine](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0105-graphite-v2-chat-doctrine.md) | SHIPPED 2026-07-11 (doctrine and dormant tokens; surface adoption staged) | Extend Graphite+ for Kin Chat without weakening the dashboard's settled motion, accessibility, or identity constraints. |
| [0104 — Durable beam card with hybrid persistence](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0104-durable-beam-card.md) | ACCEPTED 2026-07-11 | Persist handoff identity locally while leaving lifecycle truth on Outpost. |
| [0103 — Native beam controller and composed confirmation](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0103-native-beam-controller.md) | ACCEPTED 2026-07-11 | Make a human-started handoff quiet and inspectable without adding a lifecycle-hook policy engine. |
| [0102 — Rig — Kin's computer](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0102-the-rig.md) | Accepted 2026-07-11; W0 contract and critic pass complete; implementation waves W1–W5… | Rig is one warm, persistent machine beside Outpost: a semantic-first, headful browser and shell that Kin can turn to during a conversation, with screenshots on demand, its own memory, an append-only journal, and an SSO-gated human… |
| [0102 — Execution profiles by validated reference](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0102-execution-profiles-by-reference.md) | ACCEPTED 2026-07-11 | Run machine-door jobs on an intentional model without moving endpoint or credential material. |
| [0101 — Structured, Codex-style diff rendering](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0101-codex-style-diff-render.md) | Implemented on dev 2026-07-11 | The TUI coloured raw unified diff lines, leaving transport chrome (`---`, `+++`, and `@@`) prominent while omitting line numbers and per-file change counts. |
| [0100 — Titlebar spinner and workspace identity](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0100-titlebar-spinner.md) | Implemented on dev 2026-07-11 | DR `0021` made the terminal title a curated, sanitized surface and named title grammar extension as its R4 re-engage point. |
| [0099 — Outpost presence in the TUI](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0099-outpost-presence-in-tui.md) | Outpost presence in the TUI SHIPPED 2026-07-11 | Make remote jobs visible beside local sessions without pretending they are attachable sessions. |
| [0098 — Beam sequential handoff](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0098-beam-sequential-handoff.md) | Beam sequential handoff SHIPPED 2026-07-11 | Move work from a departing local machine to Outpost without creating two live writers. |
| [0097 — Multi-session kin — switcher, `kin ls`, reaper, attention, `--bg`](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0097-live-session-switcher.md) | Shipped on dev 2026-07-11; live-driven against real tmux 3.7b (crash forensics +… | One terminal, N projects. |
| [0096 — `rain` — the matrix-rain busy spinner replaces `bloom` as the default](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0096-rain-spinner-default.md) | Shipped on dev 2026-07-11 | DR `0078` curated the spinner-vibe set and picked `bloom` — the calm breathing asterisk family (`· ✢ ✳ ✶ ✻ ✽ …`) — as the default. |
| [0095 — Copy-on-select + code-fence click-to-copy](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0095-copy-on-select.md) | Shipped on dev 2026-07-11 | Mouse text selection in the transcript already worked (Textual 8.2.7's built-in selection is on by default and kin never disabled it), but nothing happened on release — copying required knowing about `Screen.action_copy_text`, which kin… |
| [0094 — Detach/reattach — the fully-hidden managed tmux wrapper](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0094-detach-reattach-tmux-wrapper.md) | Shipped on dev 2026-07-11; the manual live gate (checklist below) is the dev→main… | `kin` can optionally run inside a managed, invisible tmux session (one per workdir, dedicated `-L kin` server): `/detach` returns the terminal to the shell with the session — a live turn included — still running, and `kin` in the same… |
| [0093 — Provider-real /effort vocabularies for the MiniMax & Z.ai presets](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0093-provider-real-effort-vocab.md) | Implemented; live-key spike passed 2026-07-16 | Narrows the `/effort` picker to each Anthropic-compat provider's REAL wire knob: MiniMax gets the `thinking.type` tri-state, Z.ai gets a two-value `reasoning_effort` (`max`/`high`) shipped via a new attr-gated `extra_body` seam on… |
| [0092 — get.kinra.ai installer + public docs.kinra.ai + `kin doctor`](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0092-get-kinra-ai-installer.md) | Shipped 2026-07-10 (get.kinra.ai installer wave) | Bringing up a fresh machine (Blake's next Fedora/macOS box, or a stranger's) meant hand-cloning a private repo, knowing about `uv`, and knowing that `uv sync` alone never puts `kin` on PATH. |
| [0091 — Composer paste interception — file drops normalize to `@`-mentions](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0091-composer-paste-files.md) | Shipped 2026-07-10 (drag-and-drop/file-paste wave, Rock 3) | Finder drag-drops and terminal pastes of absolute file paths reach the Composer as raw text today (a Finder multi-file drop arrives as a newline-joined absolute-path string; Ghostty backslash-escapes spaced paths; iTerm newline-joins). |
| [0090 — read_file learns Word (.docx) + Excel (.xlsx)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0090-read-file-docx-xlsx.md) | Shipped 2026-07-10 (docx/xlsx read_file wave) | `read_file` detected media by extension — image / PDF / SVG / text — and everything unrecognized fell through to `_read_text`, which opens the file `encoding="utf-8", errors="replace"`. |
| [0089 — TUI two-phase quit with visible memory curation + skip](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0089-two-phase-quit.md) | Shipped 2026-07-10 (Workstream B of the workspace-scoped memory + two-phase quit plan;… | End-of-quit memory reflection (STRATEGY §7, unified by DR 0019) ran inside `KinApp.on_unmount` AFTER the UI tore down. |
| [0088 — Workspace-scoped memory — auto-stamped frontmatter + read-seam filtering](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0088-workspace-scoped-memory.md) | Shipped 2026-07-10 (Workstream A of the workspace-scoped memory + two-phase quit plan;… | kin's agent memory (DR 0015/0019) is fully global: one root (`settings.memory_dir()`, default `~/.kin/memory`), one FTS index at `<root>/.index.db`, and the `workdir` threaded through `memory.recall()` / `index_block()` was only… |
| [0087 — Skills catalog — per-profile `skill` grants (coder + researcher only)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0087-skills-catalog-per-profile-grants.md) | Shipped 2026-07-10 (prompt-polish deferred follow-ups wave, Step 6) | The bundled `defaults/skills/` catalog sits directly after `SYSTEM_PROMPT` in `compose_system` as the cache anchor (the stable prefix every child inherits verbatim — DR 0081's "append-only" cache argument). |
| [0086 — Subagent-result trust framing — third formal re-reject](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0086-subagent-result-trust-re-reject.md) | Shipped 2026-07-10 (prompt-polish deferred follow-ups wave, Step 4, doc-only) | Records the rationale, boundary, and consequences for subagent-result trust framing — third formal re-reject. |
| [0085 — Schema-up-front dispatch note — top-level field list for `agent(schema=…)`](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0085-schema-up-front-dispatch-note.md) | Shipped 2026-07-10 (prompt-polish deferred follow-ups wave, Step 3) | The `agent(schema=…)` path (`run_subagent` with `schema=`) post-hoc structures the child's prose answer via a Tier-1 forced `tool_choice` + Tier-2 prompt-JSON fallback (DR 0069; see REFERENCE.md § "Dynamic workflows"). |
| [0084 — Live `planning` walk-up — root-resolving property + satisfies DR 0081's revisit trigger](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0084-live-planning-walk-up.md) | Shipped 2026-07-10 (prompt-polish deferred follow-ups wave, Step 1) | Revisit trigger: if `sess.planning` ever becomes a live property that walks to the root, planner fan-out becomes safe to reconsider. |
| [0083 — The liveliness doctrine — motion, freshness honesty, and the settled state (Outpost polish wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0083-liveliness-doctrine.md) | SHIPPED | The Outpost dashboard grew its live surfaces piecemeal: the Activity feed got a pulsing dot grammar (green `running`, amber `pulse-wait` for needs-human), the header got a pulsing "live" pill, DR 0021 gave the tabs a deliberately… |
| [0082 — Model-facing truth — the context tells the model the truth about its own harness](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0082-model-facing-truth.md) | Shipped 2026-07-09 (prompt-polish wave, Rocks 2–4) | Records the rationale, boundary, and consequences for model-facing truth — the context tells the model the truth about its own harness. |
| [0081 — Subagent dispatch contract — shared preamble + the non-interactive invariant](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0081-subagent-dispatch-contract.md) | Shipped 2026-07-09 (prompt-polish wave, Rock 1) | Records the rationale, boundary, and consequences for subagent dispatch contract — shared preamble + the non-interactive invariant. |
| [0080 — TUI voice conventions: one hint voice, toast governance, safe defaults](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0080-tui-voice-conventions.md) | SHIPPED (polish wave, Rocks C1–C3) | **Placement addendum (2026-07-16):** DR 0122 keeps this record's hint grammar but supersedes the identical-full-hint placement. |
| [0079 — Approval modal: native bodies, honest choice architecture, deny-with-note](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0079-approval-modal-native-bodies.md) | SHIPPED (polish wave, Rocks B1–B5) | The `ApprovalModal` rendered every tool identically: `"? |
| [0078 — Spinner vibes + the "one heartbeat, colour elsewhere" doctrine (POLISH r11)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0078-spinner-vibes-and-one-heartbeat.md) | SHIPPED (polish wave, Rocks A1–A4) | Partially superseded by [0096](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0096-rain-spinner-default.md): the default is now `rain` and `bloom` is removed from the vibe set. |
| [0077 — Deferred: local-model escalation routing (G6.2, Step 8 of the field-gap Wave B)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0077-escalation-routing-deferred.md) | Deferred 2026-07-09 | The 2026-07-09 field-gap analysis (`research/2026-07-09-kin-vs-field-gap-analysis.md` § G6, item 2) named the 2025–26 practitioner consensus: SLM-first with automatic escalation to a stronger model on trouble signals (schema violations,… |
| [0076 — Session handoff — REJECTED (G4c, Step 7 of the field-gap Wave B)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0076-session-handoff-rejected.md) | Rejected 2026-07-09 | The field ships live session handoff: Cursor's "Cloud Handoff" lets a user pick up a running agent session in the browser/mobile that was started locally (or vice versa), attaching a second live surface to the same running conversation. |
| [0075 — `!` shell passthrough — composer-only shell escape (G8e, field-gap Wave B, Step 6)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0075-shell-passthrough.md) | Shipped 2026-07-09 | The 2026-07-09 field-gap analysis named the missing `!` shell escape as one of the TUI QoL batch's five items (`docs/decisions/0074-tui-qol-batch.md` carries the other four: `/export`, `/fork`, `/editor`, Ctrl+R history search). |
| [0074 — TUI QoL batch: /export, /fork, /editor, Ctrl+R history search (G8, field-gap Wave B)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0074-tui-qol-batch.md) | Steps 2–5 (/export, /fork, /editor, Ctrl+R history search) SHIPPED | **Historical privacy boundary:** DR 0112 supersedes this section's in-memory-only storage choice with bounded, project-scoped durable history. |
| [0073 — Nested/lazy AGENTS.md discovery (G7 — Step 1 of the field-gap Wave B)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0073-nested-agents-md.md) | SHIPPED 2026-07-09 | `agents_md.discover(workdir)` reads exactly three fixed paths at session start — workdir `AGENTS.md`, workdir `CLAUDE.md` (fallback only), and `~/.config/kin/AGENTS.md` — with no nested walk and no `@`-import expansion (both… |
| [0072 — Mid-run steering — a steer-file channel across the subprocess boundary (G4b, Step 7 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0072-mid-run-steering.md) | Proposed 2026-07-09 | Records the rationale, boundary, and consequences for mid-run steering — a steer-file channel across the subprocess boundary (g4b, step 7 of the field-gap wave a). |
| [0071 — The kill switch — one cancel-semantics core behind three doors (G4a, Step 6 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0071-kill-switch.md) | SHIPPED 2026-07-09 | A queued or running job's operator gets a real Stop, not just Pause. |
| [0070 — No user-configurable lifecycle hooks (G3 — Step 5 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0070-no-hooks.md) | Rejected 2026-07-09 | The absence is currently undocumented: `src/kin/harness/` has no lifecycle hook mechanism, and no prior DR ever considered adding one. |
| [0069 — Guided-decoding probe + scheduler compact default (G6.1 + G6.3 — Step 4 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0069-local-model-levers.md) | SHIPPED 2026-07-09 | The 2026-07-09 field-gap analysis named G6.1 (structured-output fast path) as a candidate build: attach vLLM's guided-decoding params to `force_tool_call` so Tier-1 structured output stops relying on the model "just complying" with a… |
| [0068 — Terminal bell / OSC 9 walk-away notification (G5 — Step 3 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0068-terminal-notification.md) | SHIPPED 2026-07-09 | The 2026-07-09 field-gap analysis (`.kin/2026-07-09-gap-analysis-vs-field.md` — moved to `research/2026-07-09-kin-vs-field-gap-analysis.md` at the wave's Step 8 close-out) named a real ergonomics gap: kin gives no walk-away signal. |
| [0067 — File snapshots-before-write + `/rewind` file restore (G2 — Step 2 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0067-file-snapshots-rewind.md) | SHIPPED 2026-07-09 | The 2026-07-09 field-gap analysis named a real gap: `HistoryOps.rewind` truncates the CONVERSATION at a user-turn boundary, but it never touches FILE state. |
| [0066 — Diagnostics-after-edit (G1.1 — Step 1 of the field-gap Wave A)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0066-diagnostics-after-edit.md) | SHIPPED 2026-07-09 | "LSP servers can get out of sync, use significant memory, and slow down agent workflows.". |
| [0065 — Deep-link targets for run_report and alert taps (Step 4 of the mobile control-plane wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0065-push-deep-links.md) | Deep-link targets for run_report and alert taps — SHIPPED 2026-07-09 | The push lane is a *complete* control plane now: lock-screen delivery (DR 0063), lock-screen one-tap actions for the low/medium-risk lane (DR 0064), and — with this step — a per-kind deep-link grammar so a `run_report` tap lands on the… |
| [0064 — One-tap approve/dismiss for medium-risk inbox items (Step 2 of the mobile control-plane wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0064-push-one-tap-actions.md) | One-tap approve/dismiss for medium-risk inbox items — SHIPPED 2026-07-09 | The phone stops being an *information* surface and becomes an *action* surface — at least for the low/medium-risk lane. |
| [0063 — Push all three event kinds with rich, typed envelopes (Step 1 of the mobile control-plane wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0063-push-all-event-kinds.md) | Push all three event kinds with rich, typed envelopes — SHIPPED 2026-07-09 | The phone stops being silent on `run_report` and `alert` events. |
| [0062 — Dip-in transcript modal — read-only view of a child agent's transcript (Step 7 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0062-dip-in-modal.md) | Dip-in transcript modal — SHIPPED 2026-07-09 | The retention keystone (DR 0058) parks a child idle with its full transcript surviving `aclose`. |
| [0061 — Headless retry posture — children retry through mid-stream errors (Step 5 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0061-headless-retry-posture.md) | Headless retry posture — SHIPPED 2026-07-09 | Today, a transient wire error mid-stream lands as `done("error")` + the partial prose for EVERY session — root included. |
| [0060 — `agent_message` — coordinator-only resume on a parked subagent (Step 6 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0060-agent-message-resume.md) | `agent_message` — SHIPPED 2026-07-09 | The retention keystone (DR 0058) parks a finished child instead of destroying it; that parked child is a live `Session`. |
| [0059 — Subagent failure semantics — kill the silent-partial family (Step 4 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0059-subagent-failure-semantics.md) | Subagent failure semantics — SHIPPED 2026-07-09 | A worse bug than the brief knew: when a foreground subagent dies on a transient wire error *after* streaming prose, the loop emits `events.error` + `events.done("error")` and returns normally — `ForwardingEmit` dropped `error` events,… |
| [0058 — Subagent retention — child journals + park + deliberate close (Step 3 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0058-subagent-retention.md) | Subagent retention — SHIPPED 2026-07-08 | Records the rationale, boundary, and consequences for subagent retention — child journals + park + deliberate close (step 3 of the subagent-retention wave). |
| [0057 — Unified agent registry — every child gets a stable id + handle (Step 1 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0057-unified-agent-registry.md) | Unified agent registry — SHIPPED 2026-07-08 | Background subagents already had a registry (`BgSubagents` / `BgAgent`) and a stable id; foreground subagents did not. |
| [0056 — Remove the redundant TodoList header pulse (Step 0 of the subagent-retention wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0056-todo-pulse-removal.md) | Remove the redundant TodoList header pulse — SHIPPED 2026-07-08 | The `TodoList` panel's leading-glyph hex pulse (`PRIMARY` → `PRIMARY_DIM` driven by app-level `harness_busy`) was a redundant twin of the StatusBar `shimmer_text` heartbeat — both answered the same "is kin working?" question on the same… |
| [0055 — The `code-audit` gate — cite symbols not line numbers + move-tombstone class check](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0055-code-audit-gate.md) | The `code-audit` gate (symbols not line numbers + move-tombstone classes) SHIPPED… | A new `task ship` gate (`task code-audit`) that forbids `file:line` citations in non-test code comments/docstrings and flags duplicate module-level class definitions inside a package. |
| [0054 — Move landing composer to `templates/landing.py` (Step 6 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0054-templates-landing-composer.md) | Move landing composer to `templates/landing.py` (Step 6 of the 2026-07-08 dashboard… | Step 6 of the dashboard mega-templates wave moves the landing-page composer `_build_landing_html` out of `container/dashboard/app.py` into `templates/landing.py`. |
| [0053 — Move run-detail page + `_shell` to `templates/run_page.py` (Step 5 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0053-templates-run-page.md) | Move run-detail page + `_shell` to `templates/run_page.py` (Step 5 of the 2026-07-08… | Step 5 of the dashboard mega-templates wave moves the run-detail page composer (`_build_run_page_html`) plus `_shell` (the GitHub OAuth status pages) plus two sole-consumer prep helpers (`_sanitize_plain`, `_classify_run_source`) out of… |
| [0052 — Move landing `<script>` block to `templates/landing_js.py` (Step 4 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0052-templates-landing-js.md) | Move landing `<script>` block to `templates/landing_js.py` (Step 4 of the 2026-07-08… | Step 4 of the dashboard mega-templates wave moves the 2955-line landing JS block (`_build_landing_html`'s `<script nonce="…">` body) out of `container/dashboard/app.py` into `templates/landing_js.py` as the f-string function `landing_js`. |
| [0051 — Extract landing body HTML to `templates/landing_body.py` (Step 3 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0051-templates-landing-body.md) | Extract landing body HTML to `templates/landing_body.py` (Step 3 of the 2026-07-08… | Step 3 of the dashboard mega-templates wave moves the landing page's ~554-line body block (five tab sections + the inbox action bar) out of `container/dashboard/app.py` into `templates/landing_body.py` as six plain-string constants:… |
| [0050 — Extract landing `<style>` block to `templates/landing_css.py` (Step 2 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0050-templates-landing-css.md) | Extract landing `<style>` block to `templates/landing_css.py` (Step 2 of the… | Step 2 of the dashboard mega-templates wave moves the 415-line landing CSS block (`_build_landing_html`'s `<style>` body) out of `container/dashboard/app.py` into `templates/landing_css.py` as the f-string function `LANDING_CSS`. |
| [0049 — Create `templates/` + extract plain-string head fragments to `templates/fragments.py` (Step 1 of the 2026-07-08 dashboard mega-templates wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0049-templates-fragments.md) | Create `templates/` + extract plain-string head fragments (Step 1 of the 2026-07-08… | Step 1 of the dashboard mega-templates wave: a `container/dashboard/templates/` package is created and the eight plain-string CSS/JS head fragments (`_FAVICON_LINK`, `_THEME_COLOR_META`, `_MANIFEST_LINK`, `_APPLE_TOUCH_ICON_LINK`,… |
| [0047 — Session collaborators — REJECTED. The mixin shape is the endpoint.](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0047-session-collaborators-rejected.md) | Session collaborators REJECTED 2026-07-08 | The post-Tier-2 re-premise check (Step 0 of the `.kin/plans/2026-07-08-session-facade-plan.md`) **kills** the "convert Session from mixins + all-state-on-core to state-owning collaborator objects" refactor. |
| [0046 — Roundtrip island (C2 rock)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0046-roundtrip-island.md) | Roundtrip island (C2 rock) SHIPPED 2026-07-08 | The `RoundTripOps` mixin (24 methods across 4 groups) and the `NeedsHumanError` class are peeled out of `session/core.py` into `session/roundtrip.py` (Step 7 of the 2026-07-08 Tier-2 session-islands wave). |
| [0045 — Subagents island](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0045-subagents-island.md) | Subagents island SHIPPED 2026-07-08 | The `SubagentOps` mixin (4 methods + 1 property) and 8 module-level helpers (incl. |
| [0044 — DR 0044 — swap-island (Step 5 of the 2026-07-08 Tier-2 session-islands wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0044-swap-island.md) | SHIPPED 2026-07-08 | The third of five island extractions: peels `BackendSwap` (the C4 coupling to `persistence.wire_shape` / `strip_thinking` / `rebuild_history` / `to_neutral_turns` that backs `Session.set_provider`'s live cross-provider history… |
| [0043 — DR 0043 — controls-island (Step 4 of the 2026-07-08 Tier-2 session-islands wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0043-controls-island.md) | SHIPPED 2026-07-08 | Folds the two tiny "controls" concerns (ModeToggle + ReasoningEffort) into one `ControlOps` mixin in `session/controls.py`, the second of five island extractions. |
| [0042 — Extract HistoryRewind → session/history.py (Step 3 of the 2026-07-08 Tier-2 session-islands wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0042-history-island.md) | Extract HistoryRewind → session/history.py (Step 3 of the 2026-07-08 Tier-2… | Step 3 of the 2026-07-08 Tier-2 session-islands wave. |
| [0041 — Convert session.py into a session/ package (Step 2 of the 2026-07-08 Tier-2 session-islands wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0041-session-package.md) | Convert session.py into a session/ package (Step 2 of the 2026-07-08 Tier-2… | Step 2 of the 2026-07-08 Tier-2 session-islands wave. |
| [0040 — Harness settings package](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0040-settings-package.md) | Harness settings package SHIPPED 2026-07-08 | The 950-line `src/kin/harness/settings.py` is split into a 5-submodule `settings/` package (Step 1 of the 2026-07-08 Tier-1-finish wave); the public import surface stays byte-for-byte stable so no downstream caller touches its `from… |
| [0039 — Harness persistence package](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0039-persistence-package.md) | Harness persistence package SHIPPED 2026-07-08 | The 867-line `src/kin/harness/persistence.py` is split into a 3-submodule `persistence/` package (Step 5 of the 2026-07-07 Tier-1 package-conversion wave); the public import surface stays byte-for-byte stable so no downstream caller… |
| [0038 — Harness MCP package](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0038-mcp-package.md) | Harness MCP package SHIPPED 2026-07-08 | The 1104-line `src/kin/harness/mcp.py` is split into a 6-submodule `mcp/` package (Step 4 of the 2026-07-07 Tier-1 package-conversion wave); the public import surface stays byte-for-byte stable so no downstream caller touches its `from… |
| [0037 — TUI modals package](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0037-modals-package.md) | TUI modals package SHIPPED 2026-07-08 | The 2307-line `src/kin/tui/modals.py` is split into a 12-submodule. |
| [0036 — TUI widgets package](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0036-widgets-package.md) | TUI widgets package SHIPPED 2026-07-08 | The 2358-line `src/kin/tui/widgets.py` is split into a 12-submodule. |
| [0035 — TUI diff module (C1 keystone of Tier-1 wave)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0035-tui-diff-module.md) | Landed on `dev` 2026-07-07 | The four unified-diff helpers move from `widgets.py` into a new `kin.tui.diff` module so `ToolCall` and `ProposalModal` can render diffs without crossing the widgets/modals package boundary. |
| [0034 — Matrix as the Outpost's communication fabric](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0034-matrix-as-fabric.md) | historical; Matrix surface retired by… | The `.kin/plans/2026-07-07-matrix-as-communication-fabric-plan.md` close-out record: Matrix = projection + command rail, Outpost = the only mutator, one inbox store, one answer service — and the honest verification state as of landing. |
| [0033 — The kin ↔ Outpost middle way — the Outpost becomes the automation layer](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0033-outpost-automation-layer.md) | accepted 2026-07-06 (docs + constitution only; the ttyd cut is Step 3) | Step 0 of `.kin/plans/2026-07-06-kin-outpost-middle-way-plan.md`. |
| [0032 — Matrix multi-room + the loops unlock](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0032-matrix-multi-room-and-loops.md) | Historical; retired by 0106 | The messenger becomes multi-operator and makes completion reports first-class; the surface was later retired for sovereign Chat. |
| [0031 — Run inspection — Trace / Files / Diff / Memory panes](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0031-run-inspection.md) | WP8 shipped on `feat/outpost-wp8-inspect` (2026-07-06) | The run-detail page's WP8 inspection surfaces: a Trace pane over the harness's metadata-only spans JSONL, a Files pane for the workspace tree + text file preview, a Diff pane that stacks journal-derived edits + `git diff` vs HEAD with… |
| [0030 — Workspace snapshots / fork / restore (WP10)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0030-workspace-snapshots.md) | Recorded | WP10 closes the last Outpost gap that was left open after WP0–WP7: there was no way to safely reverse a destructive operator action on a workspace, and no way to fork a workspace at a known point. |
| [0030 — Agent recipes gallery — bundled Qwen-tested recipe JSONs + the Jobs-tab UI](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0030-recipes.md) | landed 2026-07-06 | WP9 of the Outpost stack plan (`.kin/plans/2026-07-05-outpost-stack-plan.md`). |
| [0029 — Inbound triggers — generic webhook, GitHub, Slack slash-command](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0029-inbound-triggers.md) | landed 2026-07-06 | WP7: per-service triggers whose per-source signature-auth receiver fires governed one-shot jobs. |
| [0028 — Live transcript — journal tail over SSE](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0028-transcript.md) | WP3 shipped on dev (2026-07-06) | The run-detail page's Transcript pane: a per-pane SSE stream that tails the run's append-only JSONL journal and renders sanitized render-events in real time. |
| [0027 — Matrix reachability + ntfy retirement](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0027-matrix-reachability.md) | Historical; retired by 0106 | Records self-hosted Synapse as the former Outpost delivery surface and the retirement of the legacy ntfy path. |
| [0026 — GPU-fairness governor — admission control over background runs](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0026-gpu-governor.md) | WP4 landed on dev (2026-07-05) | An in-process admission module (`container/dashboard/governor.py`) now governs every background run sharing the same vLLM as the live interactive TUI: per-class `max_concurrent` caps (api 2, scheduled 2; the global… |
| [0025 — Outpost Developers portal — the service-registry front door (WP5)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0025-developers-portal.md) | WP5 landed on dev (2026-07-05) | Wave 1 / WP5 of the Outpost stack plan (`.kin/plans/2026-07-05-outpost-stack-plan.md`). |
| [0024 — The resume seam — `kin -p --resume` + the Inbox answer service](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0024-resume-seam.md) | WP2 landed on dev (2026-07-05) | A halted headless run (`needs_human`, exit 2) is now resumable **by continuation**: a second headless run loads the saved journal (which already contains the model's `ask` tool call + its structured needs-human tool error) and runs a… |
| [0023 — Outpost Activity tab + Inbox UI — the console spine (WP1)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0023-outpost-activity-inbox.md) | WP1 landed on dev (2026-07-05) | Wave 1 / WP1 of the Outpost stack plan (`.kin/plans/2026-07-05-outpost-stack-plan.md`). |
| [0022 — Outpost foundations — unified run model, inbox store, delivery seam, run pages](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0022-outpost-foundations.md) | WP0 landed on dev (2026-07-05) | The WP0 foundation for the Outpost stack plan (Wave 0): four new modules + a server-rendered run-detail page that unblock WP1 (Activity tab + Inbox UI), WP2 (resume seam), WP3 (live transcript), and WP8 (run inspection). |
| [0021 — Lively tab titles — TUI (OSC 0/2) + Outpost dashboard tabs](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0021-lively-tab-titles.md) | Lively tab titles — implemented on dev (2026-07-05) | One pure `derived_tab_title(...)` grammar in `kin.harness/`, written change-guarded to (a) the host terminal's tab title from the TUI via OSC 0/2 and (b) the Outpost dashboard's Run + Jobs tab buttons via the payload `refreshRun`… |
| [0020 — TUI liveliness (hex pulse + reasoning sweep) + collapsible todo panel](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0020-liveliness-pulse-and-todo-expand.md) | Liveliness + collapsible todo — SHIPPED to main 2026-07-05 | Three additions that signal "kin is working" without breaking the POLISH r1–r10 invariants or the reduced-motion byte-identical guarantee: a breathing hex glyph on the live surfaces (per-surface local liveness, NOT a global busy… |
| [0019 — Memory capture unification — one write path, auto-capture everywhere](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0019-memory-reflection-unification.md) | Memory capture unification — SHIPPED 2026-07-05 | kin gets exactly ONE memory-write mechanism — a guarded end-of-run *reflection* turn over the live `memory` tool — fired automatically on every client (TUI, `kin -p`, Outpost scheduled jobs) and on demand via `/memory`. |
| [0018 — Re-inject task/todo state on compact (don't nag)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0018-reinject-task-state-on-compact.md) | Re-inject task/todo state on compact SHIPPED 2026-07-05 | After a context compact the model lost awareness of the task list — even though the durable `tasks` DAG survived structurally. |
| [0017 — Plan routing & no-inline-self-audit rule](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0017-plan-inline-self-review-rule.md) | Plan routing & no-inline-self-audit rule SHIPPED 2026-07-05 | Encode Blake's inline-vs-dispatch routing rule at the prompt surface AND replace structural self-review with a context-aware nudge at the trap moment (the inline initial-draft return). |
| [0016 — Plan thoroughness respec](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0016-plan-thoroughness-respec.md) | Plan thoroughness respec SHIPPED 2026-07-04 | Plans are written to be executed against a CLEARED context by a smaller model — the whole planning flow now states that bar explicitly at every surface, instead of assuming it. |
| [0015 — Agent memory floor](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0015-agent-memory-floor.md) | Agent memory floor SHIPPED 2026-07-03 | Persistent cross-session memory for kin: a markdown file-based store under `~/.kin/memory/`, two-channel recall (cached prefix + volatile `<system-reminder>`), and session-end consolidation — so the model can carry state past the prompt… |
| [0014 — Git network tools](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0014-git-network-tools.md) | Git network tools SHIPPED 2026-06-30 | Three dedicated tools (`git-push` / `git-pull` / `git-fetch`) that run git network operations outside the auto-mode OS sandbox with structured-args-only argv assembly, modeled on the SSH egress pattern. |
| [0013 — v3 sections 4-7 batch](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0013-v3-4-7-batch.md) | v3 sections 4-7 batch SHIPPED 2026-06-28 | Four tightly-coupled v3 rocks landed together (ssh egress outside the network-off sandbox, bundled exemplar skills/commands, `search_workspace` Tier 1 FTS5, and the settings tool + `/settings`) — each behind its own headless gate, with… |
| [0012 — File-extraction refactor](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0012-file-extraction-refactor.md) | File-extraction refactor SHIPPED 2026-06-24 | Eleven commits on `dev` moved every hardcoded agent-config surface to markdown+frontmatter (skills, agents, slash commands, AGENTS.md/CLAUDE.md) and surfaced three real security findings — all fixed. |
| [0011 — Go to Python pivot thesis + scope](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0011-pivot-thesis-and-scope.md) | Go to Python pivot thesis + scope CAPTURED 2026-06-23 | The Textual UI in this repo stayed; the harness moved from the Go `kin` sibling into the same Python repo and dropped the NDJSON wire, so the seam became a function call instead of a subprocess pipe. |
| [0010 — 2026 agent benchmarks + external context](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0010-2026-agent-benchmarks.md) | 2026 agent benchmarks + external context CAPTURED 2026-07-03 | Captures 2026-07-03 sweep findings on Textual ≥8.2.7 capabilities kin underuses, Textual API gotchas to verify against kin, and where kin sits vs 2026 agent-harness UX benchmarks — reference material for future rocks. |
| [0009 — Anti-regression list](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0009-anti-regression-list.md) | Anti-regression list CAPTURED 2026-07-03 | The settled-good decisions from the 2026-07-03 review — preserved as a single anchor so future refactors do not quietly undo them. |
| [0008 — Effort vocabulary dispatch](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0008-effort-vocabulary-dispatch.md) | Effort vocabulary dispatch SHIPPED 2026-07-01. Superseded in part by… | Cross-wire reasoning-effort controls (`/effort` slash command + per-serve picker) that translate a single human-set "effort level" into the right wire knob per active backend (Anthropic `thinking.type`, OpenAI top-level… |
| [0007 — Planning-freeze design](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0007-planning-freeze-design.md) | Planning-freeze design SHIPPED 2026-06-27 | Planning is a transient gate-enforced freeze overlay (not a mode), paired with an auto-first two-mode collapse, so the model can self-enter read-only deliberation while only a human can ever exit it. |
| [0006 — Headless runs + the needs-human envelope](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0006-headless-needs-human-envelope.md) | Headless runs + the needs-human envelope SHIPPED 2026-07-02 | Headless cron/CI runs need an in-process one-shot path that fails closed on a human-gated event instead of hanging forever or silently auto-allowing — so `kin -p` carries an explicit `needs-human` exit code plus the structured… |
| [0005 — v3 permission model](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0005-v3-permission-model.md) | CAPTURED 2026-06-27 (direction doc; most sections since shipped) | A captured direction document for the v3 permission-model rocks — auto-first two-mode collapse, visible plans, plan lifecycle, SSH egress, bundled exemplars, optional DB-mode search, settings-tool + `/settings`, and computer use —… |
| [0004 — Strategy: missing lanes the critique surfaced](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0004-strategy-missing-lanes.md) | Strategy: missing lanes the critique surfaced CAPTURED 2026-07-03 | Atomic decision record for the five future-pass lanes the 2026-07 strategy critic flagged as worth their own pass but which were NOT in the 9-lane research set, captured here so `STRATEGY` can be relocated/trimmed without losing the… |
| [0003 — Background subagents + Tasks DAG](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0003-bg-subagents-and-tasks-dag.md) | Background subagents + Tasks DAG SHIPPED 2026-06-26 | The agents surface grew from "delegate one focused job to a subagent" into "the model can run profiles, fan-out work in parallel in the background, and maintain a session-long work graph" — without breaking the foreground path or the… |
| [0002 — Environment context cache split](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0002-env-cache-split.md) | Environment context cache split SHIPPED 2026-06-24 | Prompt-caching fails when per-turn content sits behind the cache anchor, so the environment context is split into a cached stable prefix and a per-turn volatile reminder. |
| [0001 — Strategy build decisions (2026-07)](https://github.com/kinra-ai/kin/blob/dev/docs/decisions/0001-strategy-build-decisions.md) | Strategy build decisions (2026-07) SHIPPED 2026-07-03 | Canonical record for the 11 rocks of the July-2026 strategy build — this is the home docstring citations (`STRATEGY §N` and `STRATEGY Tier Xy`) point to, written so the planned `STRATEGY` →… |