docs(readme): align documentation with current repo state

Update the top-level and package docs to match the current workspace layout,
supported tools, settings flow, and verification commands.

Co-Authored-By: chatgpt-codex-connector[bot] <199175422+chatgpt-codex-connector[bot]@users.noreply.github.com>

Author: Vrtak-CZ

README.md

@@ -4,12 +4,13 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
 
 Klovi lets you browse, search, and present AI coding session history from
-Claude Code, Codex, and OpenCode. It ships in two distribution modes that share
-the same core UI and backend logic:
+Claude Code, Codex CLI, and OpenCode. It ships in two distribution modes that
+share the same backend, plugin, and UI packages:
 
-- Desktop app: native Electrobun shell with updater, menus, and directory picker
-- npm package: `npx @cookielab.io/klovi` or `bunx @cookielab.io/klovi`, serving
-  the shared UI in your browser on `127.0.0.1`
+- Desktop app: native Electrobun shell with menus, updater integration, and
+  directory picker support
+- Browser-served package: `bunx @cookielab.io/klovi`, serving the shared UI in
+  your browser on `127.0.0.1`
 
 ![Klovi homepage screenshot](docs/screenshot-homepage.png)
 ![Klovi homepage screenshot](docs/screenshot-session.png)
@@ -24,15 +25,20 @@ Download the latest release for your platform from the
 ### Browser-served npm package
 
 ```bash
-# Node.js
-npx @cookielab.io/klovi
-
-# Bun
 bunx @cookielab.io/klovi
 ```
 
-That starts a localhost-only server and opens your browser. For programmatic
-embedding:
+Klovi starts a localhost-only server on `http://127.0.0.1:3583`, opens your
+browser by default, and reads session data directly from the local storage used
+by each supported tool.
+
+Compatibility run:
+
+```bash
+npx @cookielab.io/klovi
+```
+
+For programmatic embedding:
 
 ```ts
 import { startKloviServer } from "@cookielab.io/klovi/server";
@@ -47,6 +53,11 @@ Advanced CLI overrides:
 - `KLOVI_STATIC_DIR`
 - `KLOVI_SETTINGS_PATH`
 
+CLI flags:
+
+- `--port <number>`
+- `--no-browser`
+
 ## Development
 
 ```bash
@@ -56,7 +67,7 @@ bun install
 Use the root workspace scripts that match the runtime you want to exercise:
 
 - `bun run dev:desktop` starts the Electrobun desktop app
-- `bun run dev:bun` starts the browser/npm variant through Bun
+- `bun run dev:bun` starts the browser-served package through Bun
 - `bun run dev:node` starts the browser/npm variant through Node/tsx
 
 ## Workspace Layout
@@ -68,7 +79,7 @@ Use the root workspace scripts that match the runtime you want to exercise:
 
 ### Packages
 
-- `packages/server` - internal backend API, Effect-based, dual runtime
+- `packages/server` - backend services, RPC/HTTP server bootstrap, Effect runtime composition
 - `packages/ui` - shared React app shell and transport-neutral UI bootstrap
 - `packages/plugin-core` - plugin contracts and registry primitives
 - `packages/plugin-claude-code` - Claude Code discovery, parsing, frontend integration
@@ -79,11 +90,13 @@ Use the root workspace scripts that match the runtime you want to exercise:
 
 ## Features
 
-- Unified browsing for Claude Code, Codex, and OpenCode sessions
+- Unified browsing for Claude Code, Codex CLI, and OpenCode sessions
 - Project merging across tools that share the same working directory
 - Search across discovered sessions
 - Session presentation mode for demos and talks
-- Desktop-native capabilities in the Electrobun app
+- Per-plugin enable/disable and data-directory settings
+- Security warning onboarding for local session access
+- Desktop-native capabilities in the Electrobun app, including update checks
 - Browser-served mode through a single npm package
 - Plugin-specific tool summaries, input formatting, and resume commands
 
@@ -103,13 +116,13 @@ Use the root workspace scripts that match the runtime you want to exercise:
 | `bun run test:node-smoke` | Run the Node plugin runtime smoke test |
 | `bun run typecheck` | Run TypeScript type checking |
 | `bun run check` | Run Biome lint/format checks |
+| `bun run storybook` | Start the design-system Storybook |
 
 ## Documentation
 
 - [docs/architecture.md](docs/architecture.md) - runtime/package architecture
 - [docs/components.md](docs/components.md) - UI layers and wrapper composition
 - [docs/testing.md](docs/testing.md) - test setup and verification workflow
-- [docs/ARCH2-VISION.md](docs/ARCH2-VISION.md) - canonical Arch2 target state
 - [CONTENT_TYPES.md](CONTENT_TYPES.md) - JSONL content type catalog
 
 ## Contributing

apps/package/README.md

@@ -1,18 +1,23 @@
 # @cookielab.io/klovi
 
-Browse and present AI coding session history. Supports Claude Code, Codex (CLI & app), and OpenCode.
+Browse and present AI coding session history. Supports Claude Code, Codex CLI,
+and OpenCode.
 
 ## Quick Start
 
 ```bash
-# Run with Node.js
-npx @cookielab.io/klovi
-
-# Run with Bun
 bunx @cookielab.io/klovi
 ```
 
-Klovi starts a local server on `http://127.0.0.1:3583` and opens your browser. All data stays on your machine — sessions are read directly from each tool's local storage.
+Klovi starts a local server on `http://127.0.0.1:3583` and opens your browser.
+All data stays on your machine. Sessions are read directly from each tool's
+local storage.
+
+Compatibility run:
+
+```bash
+npx @cookielab.io/klovi
+```
 
 ## CLI Options
 
@@ -65,9 +70,21 @@ Starts the Klovi backend server. Returns `{ url, stop() }`.
 ## Supported Tools
 
 - **Claude Code** — reads from `~/.claude/projects/`
-- **Codex** (CLI & app) — reads from `~/.codex/sessions/`
+- **Codex CLI** — reads from `~/.codex/sessions/`
 - **OpenCode** — reads from `~/.local/share/opencode/opencode.db`
 
+## Settings
+
+Klovi stores settings in `~/.klovi/settings.json` by default. The settings file
+tracks:
+
+- enabled/disabled state for each built-in plugin
+- optional custom data directory overrides per plugin
+- general UI settings such as the security warning preference
+
+In browser-served mode there is no native directory picker, so custom plugin
+paths are edited manually.
+
 ## License
 
 MIT

docs/architecture.md

@@ -14,6 +14,12 @@ The shared source-of-truth packages are:
 - `packages/plugin-*`, `packages/ui-components`, and `packages/design-system`
   for plugins and reusable UI
 
+Built-in plugins currently cover:
+
+- Claude Code
+- Codex CLI
+- OpenCode
+
 ## Workspace Structure
 
 ```text
@@ -64,7 +70,7 @@ Klovi/
 
 At runtime:
 
-1. The user runs `npx @cookielab.io/klovi` or `bunx @cookielab.io/klovi`
+1. The user runs `bunx @cookielab.io/klovi` or `npx @cookielab.io/klovi`
 2. `startKloviPackageServer(...)` starts the backend and serves the UI bundle
 3. The browser loads `packages/ui` assets and talks to `/api/rpc/:method`
 
@@ -149,6 +155,7 @@ shared bootstrap logic in `packages/server/src/effect/bootstrap.ts`.
 - HTTP RPC routing in `src/effect/http-app.ts`
 - service composition in `src/effect/server-services.ts`
 - registry creation and settings-backed refresh in `src/services/**`
+- built-in plugin catalog and auto-discovery based on configured data directories
 
 Plugins remain separate packages:
 
@@ -158,6 +165,13 @@ Plugins remain separate packages:
 
 `packages/plugin-core` provides the registry and canonical plugin contracts.
 
+Settings are stored in JSON and include:
+
+- per-plugin `enabled` state
+- per-plugin `dataDir` overrides
+- general security warning preference
+- desktop update channel/check interval/auto-download preferences
+
 ## UI Layering
 
 UI is split into two layers:
@@ -172,11 +186,14 @@ primitives consumed by `packages/ui` and `packages/ui-components`.
 
 ## Verification Workflow
 
-The baseline verification set for the implemented architecture is:
+The repository baseline verification set is:
 
 - `bun run check`
 - `bun run typecheck`
 - `bun test`
+
+Additional release/runtime verification:
+
 - `bun run test:node-smoke`
 - `bun run stage:npm`
 - `bun run verify:packed-artifact`

docs/components.md

@@ -32,6 +32,8 @@ This keeps distribution-specific behavior out of the reusable rendering layer.
 - `hooks/useViewState.ts` for route restoration and navigation
 - `hooks/useUpdateStatus.ts` for updater status subscription through the host bridge
 - `hooks/useTheme.ts` and `hooks/useHiddenProjects.ts` for persisted UI state
+- `hooks/usePresentationMode.ts`, `hooks/useKeyboard.ts`, and related utilities
+  for session presentation UX
 
 ### Wrapper components
 
@@ -52,6 +54,22 @@ These components connect `packages/ui-components` to `KloviClient`,
 The `Package*` prefix is intentional: these are app-shell wrappers around the
 reusable UI package, not dead code.
 
+## Settings and Onboarding
+
+`packages/ui/src/app/components/ui/Onboarding.tsx` drives first-run setup:
+
+- step 1 shows the local security notice
+- step 2 lets the user enable/disable plugins and adjust plugin data paths
+
+`packages/ui/src/app/components/settings/SettingsView.tsx` owns the in-app
+settings experience. The current sidebar tabs are:
+
+- `general`
+- `plugins`
+
+In desktop mode the general tab also surfaces update controls through
+`KloviHostBridge`.
+
 ## Reusable UI (`packages/ui-components`)
 
 ### Messages

docs/testing.md

@@ -43,19 +43,18 @@ bun test packages/plugin-opencode/src
 
 ### `apps/package`
 
-- `src/cli.test.ts`
 - `src/cli-config.test.ts`
 - `src/server.test.ts`
 - `src/integration.test.ts`
-- `src/http-app.test.ts`
-- `src/static-handler.test.ts`
 
 These validate CLI wiring, package-only HTTP composition, and the browser/npm
 distribution entrypoint.
 
 ### `apps/desktop`
 
 - `src/bun/updater.test.ts`
+- `scripts/package-appimage.test.ts`
+- `scripts/verify-macos-wrapper-contract.test.ts`
 
 Desktop-specific tests are currently concentrated around updater behavior and
 desktop packaging/runtime wiring.