# 0.40.x → 1.0.0 Weekend-Cycle Roadmap

**Status**: Drafted 2026-05-25 — user direction for 4 weekend cycles + interleaved workweek polish.
**Owner**: Rosson + pod-leader
**Cadence**: each cycle = one weekend (critical-path `.0` ship) + the following workweek (`.X` polish + additional items)
**Total scope**: ~4 weeks (4 weekend cycles + 3 workweeks) from 0.40.0 ship to 1.0.0 launch
**Replaces**: the original "Phase 2.6 → Phase 3 → Phase 4" sequencing from `secure-tunnel-monetization-roadmap.md`. The 4-cycle plan reorganizes that work into weekend-shipping milestones.

---

## tl;dr

After 0.39.x (creature comforts workweek), K2SO renames to **K2** at the 0.40.0 ship. Each weekend ships a `.0` critical-path milestone; the following workweek ships `.X` polish items. The arc:

- **0.39.x** (current): K2 Connect remote completeness — **incl. tunnel port-exposure / wildcard `*.<sub>.k2.dev` subdomains (Pro tier, $7.99/mo)**, pulled forward from 0.40.X. Follows the dedicated PRD `.k2so/prds/k2-connect-port-exposure.md` (#643).
- **0.40.0** (Weekend 0): K2SO → K2 rebrand + monetization launch (K2 Companion + K2 Connect)
- **0.40.X** (Workweek 0): Hermes support, HTML dashboard, script system
- **0.41.0** (Weekend 1): Brain/Documentation System
- **0.41.X** (Workweek 1): research folder jailing (silo'd agents), Brain polish
- **0.42.0** (Weekend 2): TTS summaries + Kessel v2 jsonl renderer
- **0.42.X** (Workweek 2): Mobile TTS, Kessel polish, Changes tab cleanup, dormant-session notifications across renderers
- **1.0.0** (Weekend 3): K2 graduates — Owner/Manager grouping + Alakazam Engine SKILLs + advertisement

---

## ⚠️ Critical prerequisite: K2 trademark Class 9 + 42 search

**Before 0.40.0 ships publicly with the K2 name**, a USPTO TESS search across Class 9 (computer software) and Class 42 (SaaS) MUST be completed. Initial scan found K2 Advisors L.L.C. holds K2 in Class 36 (financial services) which does NOT block — but the software-class space hasn't been verified. Strongly recommend a 30-min trademark attorney consult before committing money to marketing materials, app store listings, and the .app bundle ID rename.

If software-class trademark IS blocked: a fallback name decision is needed before 0.40.0. Don't ship the rename in 0.40.0 if trademark posture isn't cleared.

---

## 0.40.x — Weekend 0 cycle (K2 launch + monetization)

### 0.40.0 critical path (ships at Weekend 0)

#### Item 0.40.0.A — Software rename: K2SO → K2

**Scope**:
- All product copy: app name in `tauri.conf.json`, Info.plist, About dialog, Settings UI, generated SKILL.md, release notes, documentation, README, website
- CLI tool: `k2so` command renamed to `k2` (alias for one release cycle, then deprecated)
- Bundle ID: `com.alakazam.k2so` → `com.alakazam.k2` (CAUTION: this breaks existing launchd plists, settings paths, file associations. Plan a migration step that preserves user state.)
- Daemon binary: `k2so-daemon` → `k2-daemon` (per Phase 2 the daemon is sidecar; rename + back-compat symlink for one release)
- File paths: `~/.k2so/` stays as the data directory (don't migrate user data on rename); document that the prefix is historical
- Crate names: `k2so-core` → `k2-core`, `k2so-daemon` → `k2-daemon` (cargo workspace rename — substantial)
- Generated SKILL.md / harness fanout: regenerated content references "K2" not "K2SO"

**Complexity**: Large. Touches every product surface.

**Implementation strategy**: phased — do the user-visible names (UI, CLI alias) first, then bundle ID + crate names (which require careful migration), then internal cleanup.

**Pre-requisite gates**:
1. Trademark Class 9 + 42 cleared
2. `k2.dev` DNS pointed at production infrastructure (or kept as a future-pointer)
3. Bundle ID migration plan reviewed (preserves `~/.k2so/` state, launchd plist transitions cleanly)

---

#### Item 0.40.0.B — K2 Companion working (Phase 3 deliverable)

**Scope**: ship the rebuilt Mobile Companion protocol from Phase 3 Workstream D. Includes:
- WebSocket-first contract (replaces the older HTTP polling)
- CompactLine terminal grid streaming
- Pairing flow against the K2SO Hosted tier OR Free Tailscale tier OR BYO tunnel
- iOS / Android client updates (separate apps; submission cycles may extend beyond 0.40.0 — phase the desktop side from the mobile-app-store side)

**Dependencies**:
- Phase 2.6 tunnel decision must land (Workstream B blocks on it)
- Phase 3 Workstream A (typed router), C (OpenAPI), D (Mobile contract) must be complete

**Effort**: substantial multi-week work compressed into the 0.40.0 weekend. **Realistic check**: this may slip to 0.40.X if Phase 3 Workstream B isn't fully baked by Weekend 0. Plan accordingly.

---

#### Item 0.40.0.C — K2 Connect working

**Scope**: ship the desktop-to-desktop remote K2 workspace access feature (Phase 3 Workstream E):
- A user can run K2 on Machine A (e.g. home desktop) and access it from Machine B (e.g. laptop on the road)
- Reuses the same tunnel infrastructure as Companion
- Frontend: connection list / address book (per Phase 2.6 PRD's `ConnectHost` schema)
- Auth: K2 bearer-token (same as Companion)

**Dependencies**: same as Companion — Phase 3 B + C + E.

**Note**: K2 Connect was previously framed as a sibling of K2 Companion. They share infrastructure (TLS, auth, tunnel) but have different UX (mobile pairing screen vs desktop connection picker).

**Architectural principle — use the REMOTE daemon's installed CLI**: when Machine B connects to Machine A's daemon, agent operations execute on Machine A. The user's installed CLI tool (Claude Code, Codex, Gemini CLI, etc.) on Machine A runs against Machine A's workspace context — its `CLAUDE.md`, `AGENT.md`, `PROJECT.md`, `.k2so/skills/` are what the agent sees. Machine B is just the viewer (streams JSONL output back through the tunnel). **The CLI subscription on Machine A is what's used; Machine B doesn't need any subscription.** This pattern means:
- No credential proxying / forwarding
- Workspace context stays where the workspace lives
- A single subscription on the user's main machine serves any number of thin clients
- K2 Connect's value prop becomes: "access your workspaces from anywhere; pay nothing extra for AI usage beyond the subscription you already have"

---

#### Items 0.40.0.D — Monetization plumbing

**Scope** (Phase 4 work compressed into 0.40.0):
- Stripe webhook integration for subscription lifecycle
- Per-user subdomain provisioning on the chosen tunnel backbone
- Admin UI for monitoring + manual interventions
- Signup flow: user pays → control plane provisions tunnel → credentials delivered to daemon → ready

**Realistic check**: this is the most aggressive part of the 0.40.0 plan. Phase 4 originally estimated 2-3 engineer-weeks. Compressing into a weekend means high risk. If monetization can't ship at 0.40.0, slip it to 0.40.X — the rename + Companion + Connect can ship without billing first.

---

### 0.40.X workweek polish items

#### Item 0.40.X.1 — Hermes support

**Scope**: support Hermes (chats + anything else relevant) in K2.

**Open question**: Hermes is a new context for me — please clarify whether this is:
- A new CLI LLM tool to add to the harness list (alongside Claude / Cursor / Codex / Gemini)?
- A separate chat platform K2 should integrate with?
- An internal codename for something else?

**Implementation surface** (TBD pending clarification):
- If a new CLI LLM tool: add to `crates/k2so-core/src/agents/wake.rs` (or its post-2.5d location) launch profile, add icon to `AgentIcon.tsx`, add to chat-history parser cluster
- If a chat platform: probably a Tauri command + a sidebar tab

**Tests**: end-to-end smoke once scope is clear.

---

#### Item 0.40.X.2 — Publishing local ports over the tunnel → **MOVED TO 0.39.x**

**Pulled forward into 0.39.x.** No longer a 0.40.X item. Follows the dedicated PRD **`.k2so/prds/k2-connect-port-exposure.md`** (task #643).

**What it is**: turn "you bought `<sub>.k2.dev`" into "**you own `*.<sub>.k2.dev`**" — a wildcard slice the user (or an agent) can point at any locally-hosted service. `k2so expose 3000 --as preview` → `https://preview.<sub>.k2.dev`; `k2so expose list` / `k2so unexpose <label>`. Same *capability* as ngrok / Cloudflare-Tunnel (expose a local port at a public URL), but it runs **entirely on K2's own Hetzner tunnel backbone** (frps + Caddy on-demand TLS + control-plane — the `k2-connect-01` box) — **not** ngrok or any third-party tunnel service. That self-hosted infra is the edge: no per-seat ngrok cost, full control, namespaced to the `k2.dev` subdomain the user already owns. The agent self-expose path (an agent spins up a dev server and exposes it) is the differentiator.

**Pricing — Pro tier ($7.99/mo)**: the standard K2 Connect subdomain (`<sub>.k2.dev`, daemon remote-access) is the base tier at **$2.99/mo**; the **wildcard `*.<sub>.k2.dev`** port-exposure is the **Pro unlock at $7.99/mo** — Stripe-backed, and the daemon reads its account tier (never a client flag). Infra: per-user `*.<sub>.k2.dev` DNS + Caddy on-demand TLS + one frpc proxy per mapping via the frps admin API (no restart). See the PRD for the `POST /cli/tunnel/expose` route + the visibility (`--public`/`--private`) model.

> Supersedes the old "port-3000 → `<sub>-3000.k2.dev`" sketch — the model is now the **wildcard `*.<sub>.k2.dev`** Pro subdomain per the PRD.

---

#### Item 0.40.X.3 — Dashboard for all pinned HTML tabs

**Scope**: aggregated view of all HTML files pinned across all workspaces. Useful when a user has multiple dashboards / reports / docs pinned.

**Dependencies**: item 2 from 0.39.x (Pin HTML files feature). Builds on the per-workspace pinning.

**Implementation surface**:
- Cross-workspace query: gather all pinned HTML records from all projects
- New top-level tab or sidebar: "HTML Dashboard"
- Layout: grid of iframes OR list with quick-preview

---

#### Item 0.40.X.4 — Script System

**Scope**: ability to author + run custom scripts within K2 workspaces. Like macros, but more powerful — bash / Python / Node scripts that K2 can invoke from the UI or CLI.

**Open design questions**:
- Where do scripts live? `.k2so/scripts/<name>.sh`?
- How are they invoked? CLI verb `k2 script run <name>`? UI Settings → Scripts section?
- Permissions: do scripts get unrestricted shell access or sandboxed?
- Variables passed in (workspace path, current agent, etc.)?
- Output handling: streamed to a Cmd+T terminal? Logged to activity feed?

**This needs a design conversation** before scope finalizes. Medium-complexity item with ambiguous boundaries.

---

#### Item 0.40.X.5 — K2 Companion: simplified chat UI (alongside terminal mode)

**Context**: K2 Companion ships at 0.40.0 with terminal-grid streaming as the primary chat surface. Terminal is exceptionally powerful for users who want full control. But for users who don't want raw terminal on mobile, a simplified chat UI is a strictly better experience.

**Scope** — two coexisting modes:

1. **Default mode: simplified chat UI** (new, mobile-optimized):
   - Clean message bubbles (user message + agent response), no terminal grid
   - Powered by the **JSONL streaming pattern** (see Item 0.42.0.A for the protocol details): the daemon spawns the user's installed CLI (Claude Code, Codex, Gemini CLI, etc.) in `--output-format stream-json --include-partial-messages` mode, normalizes per-provider events into the unified `StreamEvent` enum, streams those events through the K2 Connect tunnel to the mobile companion
   - The companion renders TextDelta / ThinkingDelta / ToolStart / ToolDone events as message-bubble UI primitives
   - User taps to compose; agent responds in real-time with streaming animation
   - **Uses the daemon's installed CLI subscription** (per the Item 0.40.0.C architectural principle) — no API keys on the phone

2. **Power-user mode: terminal with custom mobile keyboard**:
   - Keeps the full Cmd+T-style terminal experience on mobile
   - Custom virtual keyboard row optimized for terminal use: ESC, Ctrl, Tab, arrow keys, `|`, `~`, `/`, `>`, `<`, common shell shortcuts
   - User toggles between modes per workspace or per session

**Implementation surface**:
- Mobile companion: new "Chat" view alongside existing "Terminal" view; mode toggle in the workspace header
- Daemon: WS event types for normalized `StreamEvent` (already foundational from 0.42.0.A Kessel v2 work)
- Companion's StreamEvent renderer + new component library for message bubbles
- Custom keyboard row component (iOS / Android-specific)

**Why this matters**: removes the "you have to like terminals to use K2 on mobile" friction. Most users don't want raw terminal on a 6" screen — they want a chat experience. Power users keep the terminal mode with mobile ergonomics improved.

**Dependencies**: Item 0.42.0.A (Kessel v2 jsonl renderer + StreamEvent normalization) must land first — provides the streaming primitive this UX consumes.

---

## 0.41.x — Weekend 1 cycle (Brain/Documentation System)

### 0.41.0 critical path

#### Item 0.41.0.A — Brain / Documentation System

**Scope**: a documentation system for workspaces (and maybe across workspaces) that the agent can navigate intelligently. The "brain" metaphor suggests:
- Structured knowledge persisted across sessions
- Agent can read prior decisions, conclusions, design notes
- Agent can write new content into it (not just read)
- Searchable / browseable from the UI

**Open design questions** (substantial):
- Storage: filesystem markdown files (like `.k2so/notes/` or `.k2so/docs/`)? Or a DB table? Or both?
- Schema: free-form markdown OR structured (decision logs, design docs, FAQ, etc.)?
- Cross-workspace: each workspace's brain is independent, or there's a shared "user brain" too?
- Agent interaction: how does the agent decide WHEN to read brain content vs ignore? (Skill-like loading from #7 of 0.39.x?)
- Integration with existing `.k2so/notes/` (which K2 already creates per Phase 2.5d's `agents/workspace.rs` audit)?

**This needs a design PRD** before implementation. Probably its own audit pass + design conversation.

---

### 0.41.X workweek items

#### Item 0.41.X.1 — Research folder jailing (silo'd agents) — BETA

**Scope**: a way to constrain agent activity to a specific "research" sub-folder of the workspace, so the agent can't accidentally write outside it. Useful when a user wants to:
- Let the agent freely explore + write notes / experiments
- But not touch production code or other workspace areas

**Implementation surface**:
- Per-workspace setting: `research_folder: Option<String>` — when set, agent operations are constrained
- Filesystem access guardrails: K2 daemon refuses writes outside the research folder when this mode is active
- UI affordance: "Research Mode" toggle that lets users carve out a sandbox

**Why beta**: this is a security/sandboxing feature. Real attackers won't be stopped by it (agent can probably escape via shell commands), but it's a safety net for accidental damage. Document the trust model clearly.

---

#### Item 0.41.X.2 — Polish Brain / Documentation System

**Scope**: iterate on Brain System based on 0.41.0 ship feedback. UI tweaks, search improvements, agent-interaction patterns.

---

## 0.42.x — Weekend 2 cycle (TTS + Kessel renderer)

### 0.42.0 critical path

#### Item 0.42.0.A — TTS summaries of what AI finished + Kessel v2 jsonl stream renderer

**Two coupled features**:

**TTS summaries**: when an agent completes a task / checkin / heartbeat, K2 generates a short text-to-speech summary. Useful for users who step away and want an audio status update on return ("agent completed PRD draft, no errors, ready for review").

**Kessel v2 jsonl renderer**: revival of Kessel concepts. Kessel was originally an alternative terminal renderer (the "session stream" path) that got mostly retired in 0.39.0 cleanup. v2 brings it back as a JSONL-stream-based chat renderer — agents emit structured JSONL events; renderer parses + displays beyond raw PTY output. Better than Alacritty for chat-style interactions; preserves Alacritty for genuine terminal sessions.

**Architecture — the CLI-subprocess pattern**:

The daemon detects which CLI LLM tool is installed (Claude Code, Codex, Gemini CLI, etc.) and spawns it in its native JSONL streaming mode (e.g. `claude --print --output-format stream-json --verbose --include-partial-messages`). The CLI handles its own authentication via the user's subscription — K2 never touches API keys for this path. The daemon consumes the JSONL stream from the subprocess's stdout, normalizes per-provider event schemas into a **unified `StreamEvent` enum** (`Init`, `TextDelta`, `ThinkingDelta`, `ToolStart`, `ToolDone`, `Error`, `Done`), and ships those normalized events over WS to the renderer.

The renderer consumes the unified `StreamEvent` stream — it doesn't know or care which CLI is running. Same render path for Claude / Codex / Gemini / future CLIs.

**Key implementation patterns** (these inform implementation; tracked as protocol primitives that the Companion (#0.40.X.5) + Chat Mode (#1.1.0.A) also consume):

1. **3-tier CLI binary discovery**:
   - `which <cli-name>` (quick PATH lookup)
   - Login-shell `command -v` (`shell -lc "command -v <name>"` — sources `~/.bashrc` etc. for nvm/asdf/mise shims)
   - Hardcoded candidates: NVM Node versions, asdf shims, Homebrew, `~/.local/bin/`, `~/.npm-global/bin/`, Windows scoop / AppData paths, etc.

2. **Fallback args for cross-version compatibility**:
   - Primary args (modern flags like `--tools`)
   - Fallback 1 (drop `--no-session-persistence`)
   - Fallback 2 (downgrade to older `--allowedTools` + `--disallowedTools` API)
   - Auto-retry on rejection — supports old + new CLI versions without manual user config

3. **Windows command-line length handling**:
   - Detect ≥24KB UTF-16 args (Windows limit)
   - Pipe long prompts to subprocess stdin instead of args

4. **Session persistence via `--resume <session_id>`**:
   - Capture session_id from `system/init` event
   - Store client-side (or in daemon's session state)
   - Pass `--resume <id>` on subsequent calls → conversation continuity with no server-side conversation state

5. **MCP as the tool delivery mechanism**:
   - Pass `--mcp-config '{"mcpServers": {"k2": {"command":"node","args":[...]}}}'` to Claude Code (and similar to other CLIs that support MCP)
   - The CLI's native MCP client handles tool execution (`Read`, `Write`, `Edit`, `Glob`, `Grep`, `LS`)
   - K2 doesn't need to implement tool execution — leverages the CLI's existing tool surface

6. **Tool input accumulation across partial-message deltas**:
   - `input_json_delta` events arrive as chunks; accumulate per `tool_id` in a HashMap
   - Finalize when block ends; fall back to the block's static `input` field if accumulator empty

7. **Auth delegation — no K2-managed credentials for CLI path**:
   - When the CLI emits "not authenticated" errors, K2 surfaces a message: "Run `<cli> auth login` in your terminal."
   - K2 never stores API keys for the CLI-subprocess flow
   - Users keep paying their subscription provider; K2 is the orchestrator + UI shell

**Open design questions**:
- TTS engine: native macOS `say` command? Cloud API (ElevenLabs, OpenAI TTS)? User-configurable?
- Kessel v2 protocol: emit `StreamEvent` (the unified enum above) over a single WS channel? Or per-conversation channels?
- Rendering: HTML + CSS like a normal chat UI? Custom Tauri component?
- ThinkingDelta rendering: collapsed-by-default with expand affordance? Always visible?
- Toggleable per workspace? Per tab?

**Why coupled**: TTS summaries need structured "task completed" events from the agent — those come naturally out of a JSONL stream protocol. Kessel v2's JSONL renderer surfaces those events; TTS reads them. Implementing them together is more efficient than separate passes.

**Memory pointer**: see `reference_kessel_*` memories for Kessel history (originally a T0 SessionStreamSession, archived to `kessel-research-archive.md` PRD during Phase 1).

---

### 0.42.X workweek items

#### Item 0.42.X.1 — Polish TTS (Kessel coupling)

**Scope**: iterate on TTS based on 0.42.0 feedback. Likely fixes for voice clarity, summary content quality, latency.

---

#### Item 0.42.X.2 — Cleanup "Changes" tab — find a changelog expert

**Scope**: the current "Changes" tab (presumably some UI surface showing what changed in K2 between versions, OR per-workspace activity changes) needs UX work. User feedback: it's currently bad enough to need a redesign.

**Action**: find someone (community contributor? user with strong UX background?) who understands changelog rendering patterns. Hire / commission / ask for help.

**Open design questions** — needs scoping:
- Is this the per-version K2 changelog (release notes)?
- OR the per-workspace activity log (what files changed, what agents did)?
- OR both — they're conflated in current UI?

---

#### Item 0.42.X.3 — Dormant-session notifications across Alacritty + Kessel renderers

**Scope**: extension of item 4 from 0.39.x (terminal session resilience + dormancy notifications). Both renderer modes — Alacritty (current) and Kessel (new from 0.42.0) — should emit dormancy notifications consistently.

**Implementation surface**:
- The dormancy detection lives in the daemon (per 0.39.x scope)
- Both renderers subscribe to the same `session.dormant` event
- UI affordance: tab badge + notification, same across renderers

---

#### Item 0.42.X.4 — Mobile Companion App: TTS + Kessel renderer

**Scope**: bring TTS summaries + Kessel renderer to the mobile companion app.

**Dependencies**: 0.40.0's Mobile Companion (Item B) must be in production; this is the natural feature extension after the protocol is stable.

**Mobile considerations**:
- TTS on mobile: use native iOS / Android TTS APIs (no cloud roundtrip)
- Kessel renderer: React Native component vs web view of the desktop component? — design call

---

## 1.0.0 — Weekend 3 cycle (K2 graduation)

### 1.0.0 critical path

#### Item 1.0.0.A — K2 graduates

**Scope**: K2 launches as a v1.0 product:
- Public release with marketing push
- Advertisement (form TBD: blog post? video? Show HN? Product Hunt launch?)
- Website refresh emphasizing "K2 is here" / "v1.0 launch"
- Pricing page finalized with the Hosted tier ($2-?/mo) prominently visible
- Documentation: comprehensive user guide, not just per-feature pages

**Pre-requisite gate**:
- All 0.40.x, 0.41.x, 0.42.x items either shipped or explicitly deferred to 1.0.x
- No critical bugs known in production
- Mobile Companion app store submissions cleared (iOS / Android)

---

#### Item 1.0.0.B — Simplified Owner/Manager Agent Grouping

**Scope**: a UX/conceptual simplification for users who delegate work to multiple K2 instances. Today K2 has "workspace manager mode" + various sub-agent patterns. The simplification likely:
- Owner = the user (you)
- Manager = a workspace that orchestrates others
- (Possibly a third tier — Worker / Specialist agents)
- UI surfaces this hierarchy clearly in the sidebar / Settings

**Open design questions**:
- Is this purely UX renaming, or does it change underlying data model?
- How does it interact with the Phase 2.1 workspace==agent invariant (every workspace has exactly one primary agent)?

**This needs design** — probably an audit pass after 0.42.x to understand the current owner/manager surface before simplifying.

---

#### Item 1.0.0.C — Owner / Manager K2 SKILLs for Alakazam Engine + software auto-builds

**Scope**: ship K2 SKILLs (per 0.39.x item #7) that enable:
- **Alakazam Engine integration**: K2 agents can interact with Alakazam Labs' product infrastructure (more context needed on what this means)
- **Software auto-builds**: a SKILL that teaches K2 how to autonomously build, test, deploy software projects

**Open questions** (substantial):
- What is the Alakazam Engine? — internal Alakazam Labs platform? — third-party integration?
- "Software auto-builds" scope — CI/CD pipeline orchestration? Generative coding assistant? Both?
- Are these SKILLs shipped publicly (any user can install) or private (only Alakazam Labs personnel)?

**This needs a design conversation** — the SKILLs themselves are content authoring; the question is what behaviors they unlock.

---

## 1.1.0 — Weekend 4 cycle (Plug-and-Play Local LLM)

**User direction (2026-05-25)**: "Make it crazy easy to set-up and use local LLM files. I want to make it as plug-and-play as possible for people."

K2 already has llama-cpp baked in for the AI Workspace Assistant (Cmd+L) and heartbeat triage. But getting a usable local model into the right place with the right config is currently a power-user task. Post-K2-graduation, this is the highest-leverage UX moment for users who don't want to depend on cloud APIs — and it aligns with the open-source / "your keys, your terminals" positioning. **Local LLM is a UX moat that closed-source / cloud-first competitors can't easily match.**

### 1.1.0 architectural foundation

#### Item 1.1.0.0 — Unified `AiTarget` abstraction

**Foundational** — informs every other 1.1.0 item.

K2 has multiple ways an agent can be powered: a locally-installed CLI tool (Claude Code, Codex, Gemini CLI via the Item 0.42.0.A pattern), a local LLM runtime (Ollama, LM Studio, llama-cpp via OpenAI-compatible endpoint), a direct API call to a custom OpenAI-compatible endpoint (OpenAI, Anthropic, OpenRouter, Groq, vLLM, etc.), or a K2 Hosted / K2 Connect remote daemon. **These shouldn't be parallel features — they should be variants of one unified target abstraction.**

**The shape**:

```rust
enum AiTarget {
    CliAgent { agent_kind: AgentKind, model: Option<String>, ... },   // Claude Code, Codex, Gemini CLI subprocess
    ApiModel { provider: ApiProvider, model: ModelDef, ... },         // OpenAI-compat HTTP endpoint
    LocalRuntime { runtime: LocalRuntimeKind, model: String, ... },   // Ollama / LM Studio / llama-cpp (also OpenAI-compat)
    RemoteDaemon { connect_host: ConnectHostRef },                    // K2 Connect tunnel to another daemon
}
```

The renderer, the default-target selector in Settings, the status-bar switcher, the resolution logic, and the capability check ALL operate on `AiTarget` — no special-casing per kind. Adding a new kind in the future requires no refactor.

**Scope of 1.1.0.0**:
- Define the `AiTarget` enum + `ApiProvider`, `LocalRuntimeKind`, `ConnectHostRef` types in `crates/k2so-core/src/ai_targets.rs`
- Refactor existing CLI-spawn pathways (Cmd+L Workspace Assistant + heartbeat triage LLM) to use `AiTarget`
- Add Settings → AI Targets section that lists all configured targets, allows add/remove/test, and sets default
- Migrate existing per-feature LLM config to per-`AiTarget` config

**Why this is `1.1.0.0` not `1.1.0.A`**: it's the substrate the other 1.1.0 items (wizard, catalog, starter model, management UI) all sit on. Land first.

---

### 1.1.0 critical path

#### Item 1.1.0.A — Hardware-aware setup wizard

**Scope**: a first-run / Settings-launchable wizard that walks a non-technical user from zero to working local LLM in <5 minutes with no manual decisions required.

- **Hardware detection**: total RAM, GPU presence + VRAM, Metal vs CUDA vs CPU-only, Apple Silicon detection
- **Model recommendation engine**: given hardware, recommend ONE model — not a menu — with a "see other options" disclosure for power users
  - 8GB RAM / no GPU → Phi-3-mini or Llama-3.2-1B (Q4)
  - 16GB RAM / Metal → Qwen2.5-7B or Llama-3.1-8B (Q4_K_M)
  - 32GB+ / GPU → Qwen2.5-14B or Llama-3.1-8B (Q8) etc.
- **Plain-English copy**: "We'll download a model that runs well on your Mac. About 2.3 GB. Takes ~3 minutes."
- **One button**: Download & Set Up. No model picker. No quantization picker. No URL paste.
- **Auto-config**: context length, temperature, system prompt, threads/GPU layers — all set from a profile keyed off model+hardware. User never sees these unless they open "Advanced."

**Verification gate**: after download, run a 1-prompt sanity check ("Say hello in 5 words") with visible streaming so the user sees it working immediately.

#### Item 1.1.0.B — Curated in-app model + provider catalog

**Scope**: ship a `provider-catalog.json` of vetted entries that pre-populate the AI Targets settings UI. Two-section catalog:

**Section 1 — Local model catalog** (~8-15 GGUF model entries):
- Small (Phi-3-mini, Llama-3.2-1B), medium (Qwen2.5-7B, Llama-3.1-8B), large (Qwen2.5-14B, Llama-3.1-70B for high-end users)
- Each: name, size, RAM requirement, quality rating, "best for" tag (general chat, coding, summarization), download URL + checksum
- Bundle a "known-good" catalog with each K2 release; optionally refresh from CDN if reachable

**Section 2 — Provider catalog** (~7-10 pre-built provider entries):
- Pre-filled: OpenAI, Anthropic, Gemini, OpenRouter, Custom OpenAI-compatible, Ollama, LM Studio, Groq, Together (extensible)
- Each entry: provider kind, default base URL, auth shape (`local_file` / `env` / `none`), default model ID, expected headers
- User picks a kind → form auto-fills URL, default model, auth UI shape. They paste an API key (if needed), pick a model, click `Test`, done.

**The `Test` action**: probe the endpoint with a minimal request (`POST /chat/completions` with `{messages: [{role: "user", content: "Reply with exactly OK."}], stream: false}`). Pass/fail UI surface — does NOT validate the model ID exists, just that the endpoint is reachable + auth works.

**Open design question**: bundle the catalog in the app binary (versioned with releases) vs fetch from CDN (always-fresh but adds network dependency). Recommend: bundle a "known-good" catalog with each K2 release + optionally refresh from CDN if reachable.

#### Item 1.1.0.C — Optional bundled starter model

**Scope**: ship K2 with a tiny "starter" model pre-bundled so the out-of-box experience has SOMETHING working immediately — no download required for first contact.

- Candidate: Llama-3.2-1B-Instruct Q4 (~700 MB) or Qwen2.5-0.5B (~400 MB)
- Just enough for the AI Workspace Assistant to be usable for short prompts
- Setup wizard recommends upgrading to a larger model based on hardware, but starter works while download happens

**Trade-off**: increases the K2 download size by ~500 MB-1 GB. For users on slow connections, this is meaningful. Open question: bundle vs. download-on-first-run-with-progress. Recommend: bundle a 400-700 MB starter, gate behind a build-time flag so it can be disabled for a "lite" build for slow-connection regions.

### 1.1.X polish items (workweek cycle)

#### Item 1.1.X.1 — Model management UI

- List all installed models with size, last-used, currently-selected indicator
- One-click switch between models
- One-click uninstall (recycle bin via safe_delete::trash — never permanent for user-downloaded content)
- Disk space dashboard showing total local-model footprint
- "Clean up" recommendation if duplicates or unused models are detected

#### Item 1.1.X.2 — Per-Skill model selection

- Different K2 SKILLs can pin different models (e.g. fast small model for triage, larger model for code review)
- Inherits Settings → Default Model if unset
- Reuses the curated catalog from 1.1.0.B

#### Item 1.1.X.3 — Hardware acceleration auto-tuning

- Auto-detect Metal / CUDA / Vulkan / CPU at launch
- Auto-set GPU layer count based on VRAM
- "Performance report" panel showing tokens/sec for current setup
- Optional benchmark mode that re-tunes after major model swap

#### Item 1.1.X.4 — Connect handoff (optional, requires K2 Connect from 0.40.0)

- For users with K2 Connect: offer cloud model option as an alternative
- Explicit "Where does my data go?" disclosure for cloud handoff
- Default remains LOCAL — Connect is opt-in even when available
- Reinforces the privacy posture: local-first, cloud-by-choice

### Open design questions for 1.1.0

1. **Catalog freshness model**: bundle-only vs CDN-fetch vs both? See Item 1.1.0.B for proposal
2. **Starter model choice**: Llama-3.2-1B vs Qwen2.5-0.5B vs Phi-3-mini-4k? Need to test which gives the best "wow, it just worked" first-prompt experience
3. **GGUF download mirror**: HuggingFace direct vs Modelscope vs our own CDN? Cost/reliability trade-off
4. **Quantization defaults**: do we hide Q4 vs Q8 vs Q8_K_M entirely from the wizard, or expose as a "Quality vs Speed" 3-point slider? Recommend hide entirely from the wizard; expose under Advanced
5. **First-run friction**: should the wizard launch on first app open, or wait until the user tries to use a feature that requires an LLM (Cmd+L, heartbeat triage)? Recommend wait-until-needed — many users may not need local LLM if they're on cloud

### What this enables

- **Non-technical users can use local LLM features in K2 with zero config knowledge.** This is a category-defining UX moment — most local-LLM tools today (Ollama, LM Studio, llama.cpp directly) are unapologetic power-user tools.
- **Marketing leverage**: "K2 is the easiest way to run AI locally" becomes a defensible claim, separate from "K2 is open source."
- **Privacy positioning**: complements the open-source story without contradicting Connect monetization (cloud is opt-in, local is default)
- **Reduces support burden**: every "how do I set up llama-cpp" question on the public repo goes away

### Pre-requisite gate

- 1.0.0 shipped (K2 has graduated; this is a post-1.0 cycle, not pre-1.0 polish)
- Memory feedback_cmd_l_assistant constraint respected: Cmd+L download progress UI must be coherent with the new wizard
- No regression in advanced-user workflows: power users who set up llama-cpp manually must still have full control

---

## Total scope summary

| Cycle | Critical path | Big items |
|---|---|---|
| **0.39.x** (current) | K2 Connect remote completeness | incl. **tunnel port-exposure — wildcard `*.<sub>.k2.dev`, Pro tier $7.99/mo** (pulled from 0.40.X; PRD `k2-connect-port-exposure.md` / #643) |
| **0.40.0** | K2 rename + Companion + Connect + monetization | LARGE — 4 substantial items compressed into one weekend |
| **0.40.X** | Hermes, HTML dashboard, scripts | Medium per item |
| **0.41.0** | Brain / Documentation System | LARGE — needs design PRD |
| **0.41.X** | Research jailing, Brain polish | Medium |
| **0.42.0** | TTS summaries + Kessel v2 renderer | LARGE — coupled features |
| **0.42.X** | Mobile TTS + Kessel, Changes tab cleanup, dormant cross-renderer | Medium |
| **1.0.0** | K2 graduates + Owner/Manager grouping + Alakazam Engine SKILLs | LARGE — needs design conversations |
| **1.1.0** | Plug-and-Play Local LLM (hardware-aware wizard + curated catalog + starter model) | LARGE — first post-1.0 cycle; UX moat |
| **1.1.X** | Model management UI, per-Skill model selection, hardware auto-tuning, Connect handoff | Medium per item |

**Realistic capacity check**: this is an aggressive 5-week plan. Each weekend ships a substantial `.0` item; each workweek ships 2-4 polish items. With one user driving + AI subagent execution, this is feasible but tight. Recommend keeping the `.0` items as MUST-HIT and the `.X` items as STRETCH that can slip into following cycles.

---

## Open questions for design conversations

1. **Hermes** — what is it? (0.40.X.1)
2. **Script System** — design conversation needed (0.40.X.4)
3. **Brain / Documentation System** — needs full design PRD (0.41.0)
4. **Research folder jailing** — trust model + scope (0.41.X.1)
5. **TTS engine choice** — native vs cloud (0.42.0)
6. **Kessel v2 JSONL protocol schema** — design (0.42.0)
7. **Changes tab clarification** — what exactly is broken about it (0.42.X.2)
8. **Owner/Manager grouping** — UX vs data model change (1.0.0.B)
9. **Alakazam Engine integration** — what is it (1.0.0.C)
10. **K2 trademark clearance** — Class 9 + 42 search BEFORE 0.40.0 (critical prerequisite)
11. **1.1.0 catalog freshness model** — bundle-only vs CDN-fetch vs both
12. **1.1.0 starter model choice** — Llama-3.2-1B vs Qwen2.5-0.5B vs Phi-3-mini-4k (first-prompt UX wins)
13. **1.1.0 quantization exposure** — hide Q4/Q8 entirely vs "Quality vs Speed" 3-point slider

---

## Sequencing within Phase 2 / 3 / 4 territory

```
0.39.x workweek (creature comforts) — CURRENT
    ↓
0.40.0 weekend — K2 launch + monetization
    ↓
0.40.X workweek — Hermes, ports, dashboard, scripts
    ↓
0.41.0 weekend — Brain System
    ↓
0.41.X workweek — Research jailing, Brain polish
    ↓
0.42.0 weekend — TTS + Kessel v2
    ↓
0.42.X workweek — Mobile, Changes tab, dormant notifs
    ↓
1.0.0 weekend — K2 graduates 🎉
    ↓
1.1.0 weekend — Plug-and-Play Local LLM
    ↓
1.1.X workweek — Model mgmt UI, per-Skill models, hw tuning, Connect handoff
```

---

## What this PRD does NOT cover

- Implementation details for each item — each `.0` weekend gets its own focused PRD when the cycle starts
- Per-item subagent briefs — written when the cycle begins
- Test plans for individual features — captured per-PRD
- Marketing / launch coordination — separate planning track

---

## References

- `.k2so/prds/secure-tunnel-monetization-roadmap.md` — master roadmap (will be updated to reference this PRD)
- `.k2so/prds/0.39.x-creature-comforts.md` — preceding cycle
- `.k2so/prds/phase-2.6-tunnel-decision.md` — Phase 2.6 work absorbed into 0.40.0
- `.k2so/prds/phase-3-contract-hardening.md` — Phase 3 work absorbed into 0.40.0 (Workstreams D + E)
- Memory `project_k2_dev_domain` — k2.dev domain ownership + rename context
- User direction (2026-05-25): 4-cycle weekend roadmap from 0.40.0 to 1.0.0
