@loicngr/kobo 1.11.44 → 2.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to Kōbō
+
+Thanks for considering a contribution. This guide covers the from-source setup, available scripts, testing discipline, git workflow, and release process. For architecture, data model, and code conventions, see [`AGENTS.md`](./AGENTS.md).
+
+## Prerequisites
+
+Node.js ≥ 24.15. The repository's `.nvmrc` pins the tested version; run
+`nvm use` when using nvm.
+
+## Setup
+
+```bash
+git clone https://github.com/loicngr/Kobo.git
+cd Kobo
+npm run install-all   # root + client + PWA build dependencies
+npm run dev:all   # backend :3300 + client :8080
+```
+
+A production-installed Kōbō (`npx @loicngr/kobo`) and a dev server can run side by side, since they use separate data directories (`KOBO_HOME=./data` in dev vs `~/.config/kobo/` in production).
+
+## Scripts
+
+```bash
+npm run dev            # backend only (tsx watch, :3300)
+npm run dev:client     # frontend only (quasar dev, :8080)
+npm run dev:all        # both concurrently
+
+npm run build          # production build (client + server)
+npm start              # run the compiled server
+
+npm test               # backend vitest suite
+npm run test:client    # client vitest suite
+npm run test:all       # both
+
+npm run test:package   # after build: install tarball in a disposable home and exercise it
+npm run security:scan  # requires Gitleaks 8.30.1; history + current nonignored source
+
+npm run lint           # biome check (lint + format)
+npm run lint:fix       # biome check --write
+
+npx tsc --noEmit       # backend type check
+npm run typecheck:tests # backend tests and fixtures type check
+(cd src/client && npm run type-check) # client + Vue type check
+
+make ci                # install + audit + lint + type checks + build + both test suites
+make help              # list every Makefile target
+```
+
+Run a single test file with `npx vitest run src/__tests__/<file>.test.ts`, filter by name with `-t "<pattern>"`.
+
+## Testing discipline
+
+TDD for backend changes: write the failing test, confirm it fails for the right reason, implement minimally, then confirm it passes. Frontend tests cover stores, utilities, composables, and selected Vue components using Vue Test Utils and `happy-dom`. Type-checking and browser smoke tests complement this coverage. See [`AGENTS.md`](./AGENTS.md#testing-discipline) for route mocking and cleanup conventions.
+
+Backend tests pin `KOBO_HOME` to a temporary directory; never point tests at your production data. Live MCP tests are a separate, explicit command (`npm run test:mcp:live`) requiring `KOBO_LIVE_ENGINE`, `KOBO_LIVE_MODEL`, and real provider credentials. They stay outside normal CI; see the [MCP guide](./src/mcp-server/README.md#live-engine-validation).
+
+Schema changes must append a migration and update the fresh-install schema, with upgrade tests proving data preservation. See [Database migrations](./AGENTS.md#database-migrations). UI changes must follow [`DESIGN.md`](./DESIGN.md) and update all five translation files for user-visible text.
+
+## Git workflow
+
+- Branch off `develop`: `feature/<slug>` or `fix/<slug>`.
+- Follow [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): subject`.
+- Rebase on `develop` before opening a PR; never merge it in.
+- Keep commits atomic — each one compiles and passes tests.
+- Never force-push to shared branches.
+
+Run `make ci` before pushing. It reinstalls all three dependency trees with `npm ci`, audits them, runs Biome and the three type checks, builds production assets, then runs both test suites. CI runs on pushes to `develop` and PRs targeting `develop` or `main`.
+
+Full commit and branch conventions are in [`AGENTS.md`](./AGENTS.md#git-workflow).
+
+## Release process
+
+Releases are cut from `main`. Prepare the version change in a branch targeting `develop`, keeping `package.json` and its lockfile synchronized; then merge `develop` into `main`. A push to `main` starts the release workflow. Manual dispatch also requires `main`.
+
+The read-only preparation job scans secrets, installs and audits dependencies, lints, type-checks, runs both suites and builds. It creates one tarball and installs that exact artifact in a disposable environment, checking native modules, server/PWA assets and both MCP transports. A separate privileged job verifies its SHA-256 and version/tag availability, publishes that tarball with provenance without rebuilding or running lifecycle hooks, and creates the tag and GitHub Release. `make release` runs the local CI gates plus the version/tag availability checks; publishing remains the workflow's responsibility.
+
+## Public contribution boundaries
+
+Read [Security](./SECURITY.md) before attaching diagnostics and follow the [Code of conduct](./CODE_OF_CONDUCT.md). No paid provider account is needed for deterministic CI; real-provider tests are separate opt-in work. Add new public documentation through the narrow `.gitignore` allowlist instead of publishing all internal plans or captures.
+
+Run secret scanning with Gitleaks 8.30.1 (`GITLEAKS_BINARY` may point to the executable). Findings must be redacted. The single historical fingerprint in `.gitleaksignore` is a reviewed synthetic test fixture; do not add broad path or rule exclusions. A passing scan is evidence for known signatures, not proof that every historical document or binary is public-safe.
+
+See the [opening checklist](./docs/release/public-opening-checklist.md) for remaining human and platform gates. No release, visibility change or repository-history rewrite is implied by local development.

package/DESIGN.md

@@ -0,0 +1,296 @@
+# Design System — Kōbō
+
+## Product Context
+
+- **What this is:** Kōbō — a Claude Code and Codex multi-agent orchestrator. Each "workspace" is a
+  self-contained mission with its own git worktree, branch, agent session, optional dev
+  server, optional Notion source-of-truth, and a dedicated MCP tools server.
+- **Who it's for:** Developers using their own local instance, from a first mission to advanced parallel workflows,
+  distributed via `npx @loicngr/kobo`.
+- **Space/industry:** Developer tools. Peers: Linear, Anthropic Console, Tailscale admin,
+  Vercel dashboard. Not Notion, not Raycast, not Stripe marketing.
+- **Project type:** Local developer tool, served as a Quasar PWA in production.
+  Dark-native, dense, with interconnected workspace, Git, terminal and settings panels.
+
+This document defines the visual rules. The deployed token values live in
+[`src/client/src/css/design-tokens.scss`](./src/client/src/css/design-tokens.scss).
+Implementation notes below distinguish the current UI from outstanding design
+targets; documenting an existing deviation does not authorize expanding it.
+
+## Memorable Thing
+
+If a choice makes the product feel "fun" or
+"chaleureux," it's wrong. If it makes the product feel "serious tool for serious work,"
+it's right.
+
+## Aesthetic Direction
+
+- **Direction:** Brutally Minimal × Industrial
+- **Decoration level:** minimal — typography + whitespace do the work
+- **Mood:** Modern, monochrome, dense-but-aerated. Confident enough to use a single
+  accent color sparingly. No gradients, no glow, no decorative blobs, no illustrations.
+- **Reference sites:** Linear settings, Anthropic Console preferences, Tailscale admin,
+  Vercel dashboard settings.
+
+## Typography
+
+Single typeface family for the entire UI. **Geist** (Vercel) — the modern de-facto
+standard for dev tools. Tabular-nums included. Pair with **Geist Mono** for technical
+values (paths, UUIDs, hex codes, branch names, model identifiers).
+
+- **Display / Section headers:** Geist 600, 24px (`H2` / section titles)
+- **Subsection headers:** Geist 600, 16px (`H3`)
+- **Body / labels:** Geist 500, 14px
+- **Secondary text / hints:** Geist 400, 13px, color `text-secondary`
+- **Mono (paths, hex, IDs, branches, models):** Geist Mono 400, 13px, slight
+  `bg-surface-2` background pill, color `text-secondary`
+- **Loading:** Geist and Geist Mono variable WOFF2 files are vendored in
+  `src/client/public/fonts/` and loaded by `src/client/src/css/fonts.scss`.
+  Their SIL OFL license is shipped alongside them. Keep font requests local.
+
+**Never use:** Inter, Roboto, Arial, system-ui, Open Sans, Poppins, Space Grotesk
+(convergence trap), Lato. They scream "I gave up on typography."
+
+## Color
+
+Dark-first. The default state of Kōbō is the dark theme — light mode is a secondary
+concern (or deliberately absent for now).
+
+Palette aligned with Kobo's existing brand (deep purple-blue darks), refined
+for accessibility. Variant C's cool-gray palette was rejected to keep cohesion
+with the workspaces drawer and activity feed (which use the purple-blue tones).
+
+```
+Canvas / surfaces
+  --kobo-bg            #1a1a2e    /* main canvas — matches workspace drawer body */
+  --kobo-bg-deep       #16162a    /* deepest surface — sidebar nav */
+  --kobo-surface       #222244    /* cards, panels */
+  --kobo-surface-2     #1a1a30    /* inputs, popovers */
+  --kobo-hover         #2a2a4a    /* hover on items in lists */
+
+Borders
+  --kobo-border-subtle #2a2a4a    /* internal section dividers */
+  --kobo-border        #3a3a5e    /* card outlines, input borders */
+  --kobo-border-strong #4a4a6e    /* focus ring (combined with accent) */
+
+Text
+  --kobo-text          #f4f4f5    /* primary */
+  --kobo-text-2        #c9c9e8    /* secondary — most labels */
+  --kobo-text-3        #9a9ab5    /* tertiary — hints, captions */
+  --kobo-text-disabled #5a5a7a
+
+Accent (rare, indigo — only for active states, primary CTAs, focus ring)
+  --kobo-accent        #6c63ff    /* comparison with the palette before PR #34 */
+  --kobo-accent-hover  #5a51e6
+  --kobo-accent-fg     #ffffff
+
+  Measured contrast (WCAG 2.1, sRGB):
+    --kobo-accent-fg on --kobo-accent      4.32:1  temporary comparison value
+    --kobo-accent-fg on --kobo-accent-hover 5.59:1
+    --kobo-accent    on --kobo-bg          3.95:1  AA non-text (1.4.11) ✓
+    --kobo-accent    on --kobo-surface     3.53:1  AA non-text (1.4.11) ✓
+
+  The accent is a BACKGROUND and a UI-component colour. It is never a text
+  colour: white on the accent needs Y <= 0.1833 while the accent read as text
+  on --kobo-bg needs Y >= 0.2270, so no single value can clear 4.5:1 on both
+  sides. Link and emphasis text uses --kobo-text-2 instead.
+
+Semantic (used only when conveying status — keep desaturated)
+  --kobo-success       #34d399
+  --kobo-warning       #fbbf24
+  --kobo-danger        #f87171
+  Info states use --kobo-accent; there is no separate --kobo-info token.
+
+Conversation speaker markers
+  --kobo-turn-user     #ce93d8
+  --kobo-turn-agent    #7986cb
+```
+
+**Rules of color use:**
+
+1. The accent (`--kobo-accent`) appears at most twice per visible screen — typically:
+   the active sidebar item (left-border 2px) and the primary CTA. Never for decoration.
+2. Semantic colors only carry meaning. A red border is a problem, not a style.
+3. No gradients anywhere. Solid fills only. No glow, no shadow halos.
+4. Hover states are a 1-shade nudge (`--kobo-hover`), not a saturation pump.
+
+## Spacing
+
+Base unit **4px**. Compact-aerated density (Linear, not Notion).
+
+```
+2xs   2px
+xs    4px
+sm    8px
+md    12px
+lg    16px
+xl    20px   /* default card padding */
+2xl   24px
+3xl   32px   /* between sections */
+4xl   48px
+```
+
+- Section padding: 20px
+- Row gap (between settings within a section): 16px
+- Section gap (between section headers): 32px
+- Card padding: 20px (when cards are used at all)
+- No element gets more padding than necessary to feel breathable
+
+## Layout
+
+- **Approach:** Sidebar split.
+- **Settings sidebar:** 240px fixed width, dark `--kobo-surface`, sections rendered as
+  `icon (16px Lucide) + label`. Active item: `border-left: 2px solid var(--kobo-accent)`,
+  text in `--kobo-text`, slight background `--kobo-hover`. Inactive: `--kobo-text-2`,
+  no border, hover bg `--kobo-hover`.
+- **Content panel:** max-width 720px, left-aligned. Sections rendered **flat** (not
+  cards): only `--kobo-border-subtle` dividers between rows. Section header on top,
+  rows below, no encompassing card.
+- **Top bar:** 48px tall, contains breadcrumb-style title left + `⌘K` shortcut hint
+  right (muted).
+- **Sticky save bar (when dirty):** full width, `bg-canvas` with `border-top
+  --kobo-border-subtle`, contains "Unsaved changes" text left + primary `Save`
+  button right. Slides up in 150ms when dirty, slides down when saved.
+- **Border radius scale:** `sm 4px` (inputs, small buttons), `md 6px` (cards, larger
+  buttons), `lg 8px` (modals). **No `9999px` pill shapes** — pills feel friendly,
+  Kobo is not friendly, Kobo is precise.
+
+## Motion
+
+**Minimal-functional only.** This is non-negotiable — a dev tool must feel
+instantaneous, not choreographed.
+
+- **Easing:** Hover/focus `ease-out`, dismissals `ease-in`, movements `ease-in-out`
+- **Duration:**
+  - Micro (focus ring, hover): 100ms
+  - Short (toggle, popover open): 150ms
+  - Medium (sticky save bar slide-up): 200ms
+  - Anything longer (or stagger, scroll-driven, entrance animations) is forbidden
+- No spring physics. No bouncing. No `requestAnimationFrame` chains for cosmetic
+  effects. Reserve animation for **state transitions that carry information**.
+
+## Iconography
+
+- **Library:** [Lucide icons](https://lucide.dev) exclusively. Cohérent with Geist.
+- **Size:** 16px in nav, 14px inline, 12px in dense tables
+- **Stroke:** 1.5px (default Lucide)
+- **Color:** `--kobo-text-2` by default, `--kobo-text` on hover/active, `--kobo-accent`
+  only when the icon carries the active-state meaning
+- No emojis as decoration. Emojis are allowed only as user-content (workspace icons,
+  templates), never in chrome.
+
+**Implementation status:** the shipped UI currently uses Quasar `q-icon` with
+the `material-icons` extra registered in `quasar.config.ts`; Lucide is still a
+design target, not an installed icon system. An icon migration must be handled
+as a deliberate UI change rather than assumed complete from this guide.
+
+## Component Patterns
+
+- **Inputs:** Flat. `bg-surface-2`, `border-subtle`, focus → `border-accent` +
+  2px accent-tinted shadow. No bevels.
+- **Buttons:**
+  - Primary: `bg-accent`, `text-accent-fg`, hover `bg-accent-hover`. One per screen
+    (the page's main action — typically Save).
+  - Secondary: `bg-surface-2`, `text`, `border-subtle`. Used for actions like
+    "Refresh", "Reset to default".
+  - Tertiary / link: no background, `--kobo-text-2` text, underline on hover,
+    consistent with the accent contrast rule above.
+- **Toggles:** Quasar's `q-toggle` default, color override to `--kobo-accent`.
+- **Segmented control / radio row:** Active option `bg-accent + text-accent-fg`,
+  inactive `text-2` with hover bg `--kobo-hover`.
+- **Mono pills:** Technical values get a 2px-padded mono pill with `bg-surface-2`
+  background. Example: model IDs, UUIDs, paths, hex codes, branch names.
+
+## Anti-Patterns (forbidden)
+
+- Purple/violet gradients
+- 3-column icon-in-circle feature grids
+- Centered everything with uniform padding
+- Bubble/pill shapes (`border-radius: 9999px`) on rectangular elements
+- Multiple competing accent colors
+- Drop-shadow halos on cards
+- `system-ui` or `-apple-system` as primary display/body font
+- Decorative SVG illustrations in section headers
+- "Welcome back!" / "Let's get started!" tone in microcopy
+
+## Settings-Page-Specific Application
+
+`SettingsPage.vue` now uses `SettingsNavList.vue`, a desktop sidebar and a mobile
+navigation drawer, an active-section content panel, and a dirty-state save bar.
+The old three-tab redesign description is no longer the implementation baseline.
+
+- Section membership is declared by `navItems` in `SettingsPage.vue`: General,
+  Agents, Skills, Git, Prompts, Scripts, Notion, Sentry, Forge, Voice, Notifications,
+  Worktrees, Projects, prompt Templates, Workspace templates, and Export.
+- Git groups workflow preferences, conventions and branch prefixes.
+  Prompts keeps post-PR/MR, review, CI-fix and finalization instructions. Project overrides use
+  the same Git grouping. Retry limits belong to Agents and reminders to Notifications.
+- Keep new sections in the same navigation and guided-tour registry; all labels
+  go through the five locale files.
+- Use flat rows and subtle dividers, a clear section heading, and technical
+  values in Geist Mono. Avoid introducing nested card chrome.
+- Keep colors, spacing, fonts and transitions on the existing tokens. The
+  frontend `design-system-*` tests cover token consistency, palette, typography
+  and contrast; they complement browser review rather than proving every screen
+  follows this guide.
+
+## CSS Variables
+
+The following core tokens mirror `src/client/src/css/design-tokens.scss`.
+That stylesheet also defines font stacks, easing curves and the accent RGB
+triplet. Keep the document and stylesheet synchronized; Quasar theming overrides
+must stay consistent with them.
+
+```scss
+:root {
+  --kobo-bg: #1a1a2e;
+  --kobo-bg-deep: #16162a;
+  --kobo-surface: #222244;
+  --kobo-surface-2: #1a1a30;
+  --kobo-hover: #2a2a4a;
+
+  --kobo-border-subtle: #2a2a4a;
+  --kobo-border: #3a3a5e;
+  --kobo-border-strong: #4a4a6e;
+
+  --kobo-text: #f4f4f5;
+  --kobo-text-2: #c9c9e8;
+  --kobo-text-3: #9a9ab5;
+  --kobo-text-disabled: #5a5a7a;
+
+  --kobo-accent: #6c63ff;
+  --kobo-accent-hover: #5a51e6;
+  --kobo-accent-fg: #ffffff;
+
+  --kobo-success: #34d399;
+  --kobo-warning: #fbbf24;
+  --kobo-danger: #f87171;
+
+  --kobo-turn-user: #ce93d8;
+  --kobo-turn-agent: #7986cb;
+
+  --kobo-radius-sm: 4px;
+  --kobo-radius-md: 6px;
+  --kobo-radius-lg: 8px;
+
+  --kobo-space-2xs: 2px;
+  --kobo-space-xs: 4px;
+  --kobo-space-sm: 8px;
+  --kobo-space-md: 12px;
+  --kobo-space-lg: 16px;
+  --kobo-space-xl: 20px;
+  --kobo-space-2xl: 24px;
+  --kobo-space-3xl: 32px;
+  --kobo-space-4xl: 48px;
+
+  --kobo-duration-micro: 100ms;
+  --kobo-duration-short: 150ms;
+  --kobo-duration-medium: 200ms;
+}
+```
+
+## First-run and optional configuration
+
+The first-run panel stays hidden until settings load and does not interrupt migrated installations. Its diagnostic statuses distinguish ready, missing, failed and unverified; provider authentication is never inferred from a local executable check. Starting from this panel opens the ordinary creation form without automatically launching an agent. Preserve keyboard access, responsive layout and translated remediation text in all five locales.
+
+Direct integration settings show configured status without fetching stored credentials; replacement is explicit and clears local fields only after success. Scheduled-session admission is diagnostic information, not proof that a pending instruction was delivered. Workflow preferences must state their scope separately from engine permissions. Public audio assets are original quiet tones; avoid insulting labels or unverified third-party clips.

package/README.md

@@ -17,20 +17,24 @@ Kōbō (工房, "workshop") turns *one agent, one terminal* into a real workflow
 
 | | |
 |---|---|
-| **🗂️ Isolated worktrees, two engines** | Every workspace is its own git worktree and branch — parallel sessions never collide. Pick Claude Code or OpenAI Codex per workspace, and switch engines later without losing the worktree: Kōbō hands off tasks, git state, and recent context to a fresh session. |
+| **🗂️ Isolated worktrees, two engines** | Every workspace is its own git worktree and branch — parallel sessions never collide. Pick Claude Code or OpenAI Codex per workspace, and [continue in a fresh session](#fresh-sessions-and-llm-handoffs) with the same LLM or a different model/engine, preserving the worktree and mission history. |
 | **💬 Live chat, real diff review** | Streaming responses, inline Edit/Write diffs, a reasoning panel, and a Monaco diff viewer with **inline file editing**, conflict resolution, and one-click `Sync` / `Push` / `Open PR` / `Merge`. |
 | **🔁 Auto-loop, cron, wakeups** | Turn an agent loose on the task list: it works through tasks, retries on rate limits, and stops itself when there's nothing left, progress stalls, or it needs you. Cron schedules and one-shot wakeups keep workspaces moving on their own timeline. |
 | **🔀 Create from a PR/MR, or from a ticket** | Pick an open pull/merge request from GitHub, GitLab, or Bitbucket and Kōbō resolves every local conflict for you before spinning up the workspace. Or start straight from a Notion page or a Sentry issue URL. |
 
 ## Quick start
 
-Requires Node.js ≥ 24.15 and a logged-in Claude Code **or** Codex CLI.
+Requires Node.js ≥ 24.15, Git, Bash and your own Claude Code **or** Codex authentication. No skill plugin or ticket integration is required. Kōbō is a local, single-user tool; each user installs their own instance.
 
 ```bash
 npx @loicngr/kobo@latest
 ```
 
-Open <http://localhost:3000>. Data is persisted under `~/.config/kobo/` (override via `KOBO_HOME`).
+Open <http://localhost:3000> and follow the first-run check. Use **Choose a folder** beside the project field to select a local Git repository; completing setup opens the mission form without launching an agent. New installs use the plugin-free **Standard** suite, **Plan** permissions, manual commit/push/publication preferences, and disabled optional integrations/audio. Existing preferences are preserved on upgrade.
+
+Follow [your first mission](./docs/getting-started.md), [troubleshooting](./docs/troubleshooting.md), or the [security and privacy model](./SECURITY.md).
+
+Data is persisted under `~/.config/kobo/` (override via `KOBO_HOME`).
 
 Default port is `3000`; if it's taken, `SERVER_PORT` (checked first) or `PORT` picks another:
 
@@ -56,11 +60,23 @@ Kōbō's production build is an installable PWA — use your browser's **Install
 - **Interactive Q&A**: an agent can pause mid-session to ask you a question through the UI instead of guessing.
 
   ![Agent asking a clarifying question, awaiting the user's answer](docs/assets/images/agent-question.png)
-- **Quota-aware**: 5-hour / 7-day Claude usage and Codex rate-limit buckets live in the footer; sessions auto-resume after a reset.
+- **Quota-aware**: 5-hour / 7-day Claude usage and Codex rate-limit buckets live in the footer; auto-loops can resume after a reset. Explicit cron/wakeup schedules can also resume work; a manual workspace does not restart solely because its quota resets.
 - **Disk-space purge**: reclaim a merged workspace's `node_modules`/`vendor` weight without losing its chat history — see [`CONFIGURATION.md`](./CONFIGURATION.md#auto-purge-worktree-on-pr-merged).
 - **Lifecycle scripts**: shell scripts run on setup, cleanup, archive, session end, PR merge, or auto-loop stop, with output streamed into the chat.
 - **Observability**: a per-session timeline (duration, tools, tokens, errors) and a downloadable redacted diagnostic JSON.
-- **Optional integrations**: Notion (import missions) and Sentry (fix from issue URL), each independently toggled with a **Test connection** action; local voice transcription via `whisper.cpp`.
+- **Optional integrations**: Notion (import missions) and Sentry (fix from issue URL), usable by both agent engines through saved connections, each independently toggled with a **Test connection** action; local voice transcription via `whisper.cpp`.
+
+## Fresh sessions and LLM handoffs
+
+Long conversation getting crowded? Use **Continue in a fresh session** at the bottom of the right-hand Tools panel. **Change LLM** uses the same transfer flow and also lets you select another model within the current engine.
+
+1. Choose the destination model, reasoning effort and permission mode. A fresh session starts with the workspace's current configuration selected.
+2. Leave **Generate a handoff with the current agent** enabled to have the current conversation summarize the objective, constraints, decisions, verified progress, failed approaches and next action. Disable it when the old provider has no quota left: Kōbō builds context from the mission, tasks, Git state and source history without calling that LLM.
+3. Start the transfer. Kōbō interrupts the current work immediately, waits for confirmed shutdown, prepares the handoff and opens a fresh native conversation that continues the mission automatically.
+
+The workspace, worktree, task list and conversation history remain available. The transfer links to its source session and a Markdown report in **Documents** (`.ai/handoffs/`, ignored by Git). Auto-loop keeps its intent and diagnostic budget; queued instructions retain their delivery state. Pending wakeups from the source conversation follow the fresh session once its startup is confirmed.
+
+If generation fails, choose **Retry**, **Continue without an LLM summary**, or **Cancel transfer**. Cancel and Stop leave the work stopped and restore the source conversation and LLM configuration, including when the destination failed to start. Failed attempts remain in history without being resumed automatically. If there was no source conversation, the next message starts a fresh one. A server restart preserves the transfer and report for an explicit recovery decision; it never automatically replays a potentially delivered prompt. Transfers are manual—conversation size does not trigger them automatically.
 
 ## Configuration
 
@@ -76,24 +92,42 @@ The most common knobs:
 
 Everything else — worktree paths, dev server commands, prompt templates, git conventions, lifecycle scripts, forge selection, permission modes — lives in **Settings**, with per-project values inheriting from global ones. The full reference (every env var, every setting key, MCP server registration, forge/Notion/Sentry/voice setup) is in [`CONFIGURATION.md`](./CONFIGURATION.md).
 
+### Workflow and integration settings
+
+**Settings → Git** groups manual/automatic commit, push and publication preferences,
+Git conventions and branch prefixes. **Prompts** contains post-PR/MR, review, CI-fix
+and finalization instructions. New workspaces snapshot the workflow preferences;
+changing global defaults does not alter existing workspaces. These preferences guide
+agents, while engine permissions remain a separate control.
+
+Notion and Sentry are optional. Save a **Direct connection** in the integration tab,
+enable it, save Settings, then use **Test connection**. Saved direct connections take
+priority over the Claude MCP selector, which is disabled while one exists. Enabled
+connections also reach Claude Code and Codex agents through `kobo-notion-*` and
+`kobo-sentry-*` MCP servers. Stop and resume a running agent to apply a connection
+change. See [managed integration MCPs](./CONFIGURATION.md#managed-integration-mcps-in-agent-sessions)
+for credential priority and native-configuration scope.
+
 ### Docker
 
 An official `Dockerfile` and three ready-to-use Compose files ship in this repository: a quick local test stack, a Traefik-fronted local rehearsal (no domain needed), and a full VPS reference (Traefik + Let's Encrypt, SSH access, optional Docker-socket passthrough). See [`CONFIGURATION.md`](./CONFIGURATION.md#docker-deployment) for every compose file, env var, and volume mount.
 
 ### Network access
 
-Kōbō binds to `127.0.0.1` only by default. Enabling **Settings → Global → Network access** re-binds to the LAN behind a shared token (a QR code makes pairing a phone easy). Plain HTTP — keep it to trusted networks, or front it with HTTPS/a VPN for anything further. Details in [`CONFIGURATION.md`](./CONFIGURATION.md#network-access).
+Kōbō binds to `127.0.0.1` only by default. Enabling **Settings → General → Network access** re-binds to the LAN behind a shared token (a QR code makes pairing a phone easy). Plain HTTP — keep it to trusted networks, or front it with HTTPS/a VPN for anything further. Details in [`CONFIGURATION.md`](./CONFIGURATION.md#network-access).
 
 ## Agent runtimes
 
-- **Claude Code**: authenticate once with `claude /login`. Kōbō calls the embedded SDK directly — no `claude` binary needed at runtime.
+- **Claude Code**: authenticate once with `claude /login`. Kōbō calls the embedded SDK directly — no separately installed Claude CLI is required at runtime; the SDK supplies its runtime.
 - **OpenAI Codex**: run `codex login` or export `OPENAI_API_KEY`. Kōbō spawns a long-lived `codex app-server` subprocess per workspace.
 
 Both engines share task tracking, permission modes, the sub-agent panel, and the quota footer. The mapping of Kōbō's four permission modes (`plan` / `bypass` / `strict` / `interactive`) to each engine's native sandbox semantics is in [`CONFIGURATION.md`](./CONFIGURATION.md#permission-modes).
 
 ## Skill suites
 
-Kōbō's auto-generated prompts (review, auto-loop grooming, QA, brainstorming) can target **[superpowers](https://github.com/obra/superpowers)** (brainstorm → spec → plan → execute, TDD, debugging), **[gstack](https://github.com/garrytan/gstack)** (slash-command workflows for QA, design review, ship pipelines), both together, or your own custom prompts — selectable in **Settings → Skills**. Pairs optionally with **[gbrain](https://github.com/garrytan/gbrain)** for per-project semantic search. Full setup in [`CONFIGURATION.md`](./CONFIGURATION.md#skill-suites).
+**Standard** is the default and works without a skill extension. **Settings → Skills** also offers **Superpowers**, **gstack**, **ECC**, **Superpowers + gstack**, **Superpowers + gstack + ECC**, and **Custom** instructions. These choices adapt the review, grooming, QA and brainstorming instructions; selecting one does not install a suite or change permissions. External skills must already be available to the selected Claude Code or Codex engine.
+
+The Settings guided tour includes a dedicated skill-suite explanation; replay it from the help icon or Help menu. See the [skill-suite reference](./CONFIGURATION.md#skill-suites) for the available choices and custom instructions.
 
 ## Architecture
 
@@ -119,3 +153,9 @@ PRs welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the from-source setu
 ## License
 
 GPL-3.0-or-later. See [`LICENSE`](./LICENSE).
+
+## Community and support
+
+Report reproducible bugs and feature requests in [GitHub Issues](https://github.com/loicngr/Kobo/issues). Read [Contributing](./CONTRIBUTING.md) and the [Code of conduct](./CODE_OF_CONDUCT.md) before participating. Vulnerabilities belong in the private channel described in [Security](./SECURITY.md), not public issues. Support is maintained on a best-effort basis; no response-time commitment is implied.
+
+Platform validation and release blockers are recorded in the [public-readiness evidence](./docs/release/public-readiness-evidence.md). Linux is locally exercised; macOS CI, WSL and real-provider beta sessions require their own evidence. See [third-party notices](./THIRD_PARTY_NOTICES.md) for redistributed assets.

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security
+
+## Report privately
+
+Use [GitHub private vulnerability reporting](https://github.com/loicngr/Kobo/security/advisories/new).
+Private reporting was verified enabled on 2026-09-23. Do not disclose credentials,
+private conversations, customer tickets or an unpatched exploit in a public issue.
+Include the Kōbō version, OS, engine, deployment mode and a minimal reproduction
+using synthetic data. The maintainer handles reports on a best-effort basis; no
+response-time commitment is offered. Fixes target the latest release.
+
+## Trust boundary
+
+Kōbō is a local, single-user development tool. Agents, terminals, project hooks and
+configured MCP commands execute on the **server machine**, with the privileges of
+the account running Kōbō and the selected engine's permission mode. A Git worktree
+isolates a checkout, not processes, credentials or the filesystem. Only open
+projects and configure executable hooks/integrations you trust.
+
+The default listener is loopback. LAN access uses one shared token; it is not
+per-user authorization. Behind a reverse proxy, enable the corresponding setting
+so loopback API/WebSocket requests also require that token. Health checks are
+exempt. Host and Origin validation remain separate protections. Use HTTPS or a
+trusted private network; do not offer this installation as a shared public service.
+
+Git workflow preferences express which automatic actions are wanted. They are not
+a sandbox for arbitrary shell commands or external MCP tools. Claude and Codex
+permission modes have different enforcement mechanisms; unrestricted access can
+modify files outside a worktree. Provider authentication is separate from Kōbō's
+network token.
+
+## Data and credentials
+
+KOBO_HOME stores conversations, workspaces, backups and settings. Direct integration
+commands and credentials live in `integrations.json`, written atomically with mode
+0600 on Unix. They are plaintext local secrets: protect the host account and backups.
+They are excluded from settings exports and are never returned by the connection
+status API. A replacement connection must be entered in full. MCP error text and
+stderr are withheld because third-party processes may echo secrets.
+
+Agents send prompts and applicable project context to the selected provider.
+Notion/Sentry receive requests only when their configured actions are used.
+Git forge actions use your authenticated CLI/configuration. The update checker
+contacts the npm registry. Local history is not a promise that agent execution is
+offline. Review exports and attachments before sharing them: conversation content
+and personal paths may be sensitive even when known credential fields are redacted.
+
+## Development checks
+
+CI scans Git history with a pinned Gitleaks version and runs dependency audits.
+The one historical allowlisted finding is a synthetic test fixture, identified by
+its exact fingerprint in `.gitleaksignore`. A successful scan is not proof that all
+private information has been removed. Historical screenshots, media, author
+metadata, old npm packages and GitHub artifacts need separate review.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,20 @@
+# Distributed assets
+
+Kōbō source code is licensed under GPL-3.0-or-later. Dependency packages retain
+their respective licenses; consult the installed packages and lockfiles.
+
+| Asset | Provenance | License / evidence |
+|---|---|---|
+| `src/client/public/sounds/neutral.wav` and `ready.wav` | Original mathematical sine tones, no samples or recordings | GPL-3.0-or-later; reproducible with `node scripts/generate-notification-sounds.mjs` |
+| Geist and Geist Mono | Vendored font distributions | SIL Open Font License, shipped in `src/client/public/fonts/GEIST-LICENSE.txt` |
+| Quasar Material icons | Installed through `@quasar/extras` | See the package's upstream notices |
+
+Earlier versions included recorded notification sounds without a provenance
+manifest in this repository. Those files are no longer part of the current source
+or newly built package. Existing sound preferences fall back to a neutral tone,
+preserving notification enablement and volume. Older Git refs and published
+artifacts may still contain those recordings and require a separate publication
+decision; removing them from the current tree does not erase history.
+
+Repository screenshots and the application icon still require owner confirmation
+of their provenance before the public-opening gate can be marked complete.

package/dist/mcp-server/kobo-tasks-handlers.js

@@ -1,3 +1,5 @@
+import { DOCUMENT_DIRS } from '../shared/document-roots.js';
+export { DOCUMENT_DIRS } from '../shared/document-roots.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { nanoid } from 'nanoid';
@@ -267,7 +269,6 @@ export function getTicketSourcesHandler(worktreePath) {
 }
 // ── Documents ────────────────────────────────────────────────────────────────
 /** Directories (relative to the worktree root) scanned for AI-generated docs. */
-export const DOCUMENT_DIRS = ['docs/plans', 'docs/superpowers', '.ai/thoughts'];
 /** Depth cap to keep recursion bounded even on pathological symlink loops. */
 const DOC_MAX_DEPTH = 8;
 const DOC_MAX_FILE_BYTES = 1024 * 1024;