Skip to main content

INDEX — documentation map and decision log

Start with the documentation home for maintained guides and reference. This file retains the topic index and dated decision history. Descriptions inside dated milestones describe those milestones, not necessarily the current product.

Documentation site — 2026-11-11​

Docusaurus publishes the canonical repository sources through GitHub Pages. The architecture map describes the active implementation; documentation maintenance defines source ownership, generated references, executable examples and checks. Existing document paths remain stable. The site includes plugin-owned READMEs and changelogs without introducing separately maintained copies.

Topics​

#FileTopicStatus
14harness-research-2026-11.mdSource and test study of 18 agent harnesses, execution contracts, recovery and the current Compositor baselinedated research, 2026-11-11; candidate work is not an approved roadmap
13plugin-testing.mdMandatory test model: host contracts, component/trait cases, live evaluation, artifact verification and release evidencemandatory case matrix and fail-closed certification; existing coverage gaps block releases
101-concept.mdConcept: what we are building and whyaccepted
202-ui.mdUI: the pane model, Ink, swappable renderersaccepted
303-contracts.mdContracts for writing CLI pluginsdraft
404-motivation.mdMotivation: why the world needs thisaccepted
505-prior-art.mdPrior art: architecture of Claude Code, VS Code, Neovim, Sway, Linux; what we adoptaccepted
606-core-blueprint.mdCore blueprint: best-of harvest from 8 local reference codebases; subsystem → reference → what we takeproposal
7agent-features.mdImplemented agent plan: commands, providers, auto, checkpoints, worktrees, extensions, usage and setup limitsimplemented
12plugin-standard.mdPlugin standard 1: scoped opt-in, QA plans, independent releases, archive/Git updates and rollbackavailable since v0.4.0
11plugin-authoring.mdCreate, check and activate extensions inside Compositor; bundled plugin skillsavailable since v0.4.0
10workspaces-and-web.mdKeyless internet tools, attached projects, path completion, scope and concurrent agentsimplemented
9ui-controllers.mdPrivate editor/dialog/history/placement controllers and full session repositoriesimplemented
8core-customization.mdDomain-independent composition, replaceable execution/context strategies, tool selection and extension eventsimplemented; see companion UI/storage contracts

Decision log​

DateDecisionStatusContext
2026-11-10Keep all filesystem plugins off until scoped opt-in; ship the repository as the offline default market and version/test/release plugins independentlyacceptedUser chose independent versions and releases in this monorepo. Standard 1 adds QA plans, API compatibility, content locks, archive updates and rollback. Kernel management remains available for bootstrap.
2026-11-10One native package may combine agent logic, UI, tools, skills and MCP under one marketplace lifecycleacceptedAdded multi-component authoring, a shared native/Claude stdio MCP declaration reader, package resources and full install/update/disable/remove checks. See plugin-authoring.md.
2026-11-10Ship plugin authoring as a replaceable plugin with a progressively loaded skill and installed-contract helperacceptedUser requested creating plugins through Compositor itself. Native plugin skills follow enabled owner lifecycle; authoring uses normal filesystem policy and the existing reload boundary.
2026-11-10Domain behavior is composed over a neutral kernel; replace turn, tool scheduling, context and journal implementations through public servicesacceptedUser explicitly requested a customizable kernel rather than DevOps integrations. Added exact capability selection, explicit tool providers, extension event definitions and real middleware continuations. See core-customization.md for current scope.
2026-11-10Tiling is the only fixed product mechanism; all other UI and agent behavior must have replaceable implementationsacceptedUser selected this boundary after the concept audit. Rendering, input, state and lifecycle must all be replaceable; editor/dialog/history controllers and session repositories now have selected implementations. See 01-concept and 03-contracts.
2026-11-07Build the compositor, don't rewrite the coreacceptedThe core is a driver stack; a rewrite is months of work with no architectural gain
2026-11-07Ink as the TUI component modelacceptedCommunity and example-code density are critical for agent-driven development; the render engine is a consumable
2026-11-07Claude Mods API compatibility as the entry pointacceptedXwayland strategy: compatibility with an existing protocol brings users from day one
2026-11-07"Everything inside the core is an event"acceptedEvery $-API call goes through the event bus; extensibility without forking
2026-11-08Public repository, MIT licenseacceptedFrictionless reuse is part of the project's motivation
2026-11-08English-only documentationacceptedAudience is the world, not one team
2026-11-08Mirror Claude Mods event/API taxonomy 1:1acceptedXwayland strategy, confirmed against the v2.1.290 official reference
2026-11-08Prior-art synthesis (see 05)acceptedFive reference systems studied at code level; adoption table is the v1 blueprint
2026-11-08Code starts with contracts: events + protocol packagesacceptedRuntime core ports from the kimi-code fork; everything else derives from the catalog
2026-11-08Catalog as zod-defined source of truth, docs generatedacceptedNeovim api-metadata pattern; closes review gap #2; CI enforces drift
2026-11-08Wire protocol handshake = LSP-style capabilities + semveracceptedMajor mismatch fails; minor negotiates to lower; no shared surface fails
2026-11-08Runtime dispatcher as the first code above the wireacceptedOnion chains, tier order, budgets (own/thread/yield), fail-operational, chain trace; Xwayland hook API sits on top of this
2026-11-08Response forms matched by discriminating key + safeParseacceptedz.object with z.unknown() accepts missing keys — safeParse alone cannot discriminate forms
2026-11-08$ API methods are service.* events; core resolvers at chain endacceptedMods insight "each $ method is itself an event": interception via {deny}/{value} needs the call to flow through the dispatcher like any other event
2026-11-08Core written greenfield as best-of harvest over 8 reference codebases (codex, gemini-cli, qwen-code, opencode, aider, crush, goose, kimi fork) — cloned under projects/reference/acceptedNikita (10:21): the 14-CLI research must drive the design, not a single codebase; core is plugin-first from day one. Supersedes open item #3 ("port the fork loop")

Current application composition​

The interactive product path is app → AppUI → protocol → renderer-ink; input returns through the same protocol. core is the active multi-turn engine. agent and its pane demo remain historical reference code. plugins is a compatibility facade over the shared loader implementation. The app resolves config permissions, enables configurable compaction, and injects a skill index plus a service-backed skills tool. /reload performs explicit hot reload between turns. The legacy --plain/piped REPL remains available for script compatibility, outside the grid renderer path.

DateDecisionStatusContext
2026-11-08App TUI uses protocol-only renderer accessacceptedCore-side UI controller owns drafts, history, permission prompts and intent routing; Ink draws surfaces
2026-11-08Share disk loading and reject sandboxed modules before importacceptedQuickJS is not linked; plugins delegates to loader, app directory overrides are preserved
2026-11-08Wire config permissions, compaction and progressive skills into appacceptedApp assembly owns defaults; full skill bodies are loaded through an interceptable service

Tiling compositor (2026-11-08)​

The app now owns a binary split tree per workspace. Windows support geometric focus, directional swaps, nearest-container resize, close/collapse, and fullscreen. The message input and status stay docked. Plugin text surfaces use service.ui.surface / $.ui.surface; focused plugin keys use ui.press. Protocol 0.2 adds resolved rectangle layout messages, gated by the Layout element capability. Layout state is currently in-memory; multiple conversation views share the same core session. See the app README for terminal bindings and limitations.

Plugin placement policy (2026-11-08)​

$.ui.surface accepts optional placement hints for split, sidebar, inspector and status-bar. App config ui.sites and ui.rules override hints. Rules match plugin identity and local surface id, last matching field wins. The compositor inserts windows into workspace trees; the renderer continues receiving resolved rectangles only. Placement is creation-only so content updates preserve manual layout and focus.

Placement control panel (2026-11-08)​

The app exposes plugin surface placement through [Plugins], Alt+p and /plugins. Draft edits are applied explicitly. Save writes a project-local JSONC rule with exact plugin/surface selectors, preserving comments and unrelated settings. The core-side controller relocates existing windows; renderers still receive only protocol frames. Full tree persistence remains outside this feature.

Mouse window operations (2026-11-08)​

Protocol 0.3 adds optional mouse press/move/release phases, window title controls and drop preview hints. The renderer decodes SGR reports and draws the preview; the compositor owns capture, hit testing, splitting, swapping, workspace drops and resize rollback. Press-only peers retain click focus.

Hover pointer feedback (2026-11-08)​

Protocol 0.4 adds capability-gated pointer messages. The compositor hit tests hover; Ink translates pointer shapes into OSC 22 and enables all-motion mouse reporting. Supported terminal emulators show grab, resize, button and text pointers; unsupported terminals keep their native pointer.

UI presentation plugins (2026-11-09)​

Accepted: retain the tiling compositor and introduce a shared default theme, semantic conversation/tool rows and a compact contextual footer. Plugins can replace their appearance contribution with $.ui.configure and override named portable text views through ui.render. Unload removes contributions; stale async views are discarded. Protocol 0.5 transports resolved chrome. See UI appearance and view plugins.

Main agent integration (2026-11-09)​

Merged upstream through 70ebf21: task/subagents, ask_user, tools.ts plugins, stdio MCP and workflows. The common loader supports tools-only plugins while retaining manifest validation, trust rules, command metadata and reload. TUI questions use the same onAsk channel as the CLI; child questions inherit it. Reload updates hooks, tools and future child composition together. Parent interruption propagates to the child; child tool declarations are deduplicated.

Documentation rules​