KIWI unified product plan

Revision 17: P0 finished top-to-bottom. file_organizer moves to exact plans — shared src/skills/fileOrganize.ts (computeOrganizeMoves: extension categories, collision-safe (2) targets, optional archiveAfterDays → _archive), builtin skill stages an exact plan with recovery copies on dryRun:true and executes only with a validated exactPlan:{id,kind:'file_organizer'} + human approval (allow to prepare, confirm to run); the mind automation file-organizer is now preview-only (never moves files, points to the chat-approved exact plan). dev_task default policy is deny in src/config/config.ts (dev_status/dev_cancel refuse when dev mode is off; DevManager.start has no active caller) — its safe replacement is the P1 device-task / P2 interactive-coding flow, not a move/delete ledger. Config/target drift closed: configPath() honors KELVIN_CONFIG_PATH (tests never touch the real kiwi.config.json) and POST /api/documents/root also syncs kiwi.mind.config.skills. Owner memory isolated: GET /api/kiwi/knows reaches the engine only for an admin browser without an authorization header; credentialed accounts get source:'embedded' with their own observations. Bound: readChatBody (500 KB + 100k chars) on /api/documents/chat/stream, engine 413 on both document chat routes before the LLM, /api/chat/files 413 from Content-Length before multipart buffering; scripts/repair-attachment-links.mjs audits and --fixes message_files in a transaction (dedupe keeping MIN(rowid), orphans and mismatched owners removed, files untouched). Two-Windows acceptance stays blocked (no second Windows; VMs are Linux) — documented as the last P0 step. Verification: 132 engine tests (131 passed + one optional semantic skip); 228 mind/web tests in 34 suites; both typechecks passed. No production rollout.

Revision 16: broad move/delete actions now run on persistent exact-action plans with backup and rollback. src/exactions/ledger.ts stages an immutable plan (id, kind, absolute-path ops; sha256 for moves ≤16 MB) before any effect — recovery copies for moves live under data/exactions/<id>/moves/, delete ops move their target into a backup folder instead of rm, ledger data/exactions/ledger.json. Policy (src/security/host-action-policy.ts): exactPlanRefOf accepts only exactPlan:{id,kind} — without it non-dryRun documents_organize and disk_doctor reap stay denied; with a valid reference they become confirm (mandatory human approval, never auto-execution); preparing stays allow (dryRun:true / action=plan_reap). documents_organize stages on dryRun:true (LLM classification, collision-free targets) and executes only with a valid plan; disk_doctor plan_reap/reap runs the same recoverable flow. dev_task and file-organizer remain blocked (exact flows with common-tasks P2, planned in P1). Details: host actions EN / RO. Verification: 124 engine tests (123 passed + one optional semantic skip; +11, tests/exact-plan.test.ts); 222 mind/web tests in 33 suites; both typechecks passed. No production rollout.

Revision 15: plugin skills must declare their effects; undeclared plugins are blocked. Skills loaded from plugins/ carried no capability metadata, so hostSkillPolicy fell back to allow and direct registry.run callers (document skills, CLI diagnostics) bypassed the full policy; now Skill.capabilities (read/write/exec/network/system/media) drives declaredSkillPolicy — no declaration or any mutational effect → confirm, read-only → allow, and a stale configured allow cannot weaken it (fail-closed). SkillRegistry.skillDeclaration feeds the agent JSON/stream/offline loop, the conversation manager and direct Telegram; registry.run refuses an undeclared plugin before run(), and src/skills/plugins.ts warns on load. Details: host actions EN / RO. Verification: 113 engine tests (112 passed + one optional semantic skip; +8); 222 mind/web tests in 33 suites; both typechecks passed. No production rollout.

Revision 14: the P0 audit closes the mind-automation path and the documents root. The automation branch in mind.hear (only production caller: the brain-down fallback in src/grove-api.ts:122) dispatched the automation skills with ALL permissions and no host-action policy; now hostSkillPolicy classifies the automations (app-launcher/note-taker → confirm; non-dryRun file-organizer → deny with the exact-plan reason; reads stay allow), mind.hear applies the policy before execution (confirm → blocked like an internal thread) and grants only the skill's declared permissions, and app-launcher refuses shell metacharacters. POST /api/documents/root uses resolveDocumentsRoot: new folders may only be created inside PROJECT_ROOT; selecting an existing folder anywhere stays allowed (current KiwiDocs deployment untouched). Details: host actions EN / RO. Verification: 105 engine tests (104 passed + one optional semantic skip); 222 mind/web tests in 33 suites; both typechecks passed. No production rollout.

Revision 13: crash recovery for the owner web chat. When the admin browser disconnects mid-turn the engine still completes and persists the round in the scoped thread, but the web does not save the assistant reply (the SSE loop stops at stopped()). The engine exposes GET /api/chat/scoped/thread (read-only, validates the owner-web:v1: identity) via ConversationManager.getTurns; on GET /api/chat/history?channel=web&sessionId=... for an admin account reconcileOwnerChat (web/src/lib/chat-reconcile.ts) compares the last web message against the last completed engine round and appends the missing reply when the user content matches — tail-only, idempotent, best-effort. Verification: 101 engine tests passed, one optional semantic skip; 222 mind/web tests in 33 suites; both typechecks passed. No production rollout. Details: chat, host actions.

Revision 12: Telegram update_id is deduplicated and the message quota is consumed atomically on the webhook. The webhook records (chat_id, update_id) in telegram_webhook_updates (composite primary key, 200 on duplicates, 48h pruning; pg-schema parity added), and the quota is consumed by a single conditional UPDATE — consumeMessageIfUnder in web/src/lib/billing.ts — placed after the file-only filter and before appendMessage: no double consumption, no overshoot under concurrent deliveries. The engine (src/telegram/run.ts) persists the last processed update_id in data/telegram-owner-offset.json (via dataPath, honours KELVIN_DATA_DIR) and resumes from it on restart, avoiding a queue replay. Verification: 97 engine tests passed, one optional semantic skip; 210 mind/web tests in 31 suites (5 new tests: 4 web dedup/quota + 1 engine offset); both typechecks passed. No production rollout. Details: chat, host actions.

Status: approved by Matei. This file holds only the approved plan (requirements/acceptance criteria) — the live revision log of what has actually shipped lives in CHECKPOINT.md (RO) / CLAUDE.md (EN), not here; the entries above stop at revision 17 for historical reasons. Active stage at revision 68: P0-P5 closed; P1 (the two-Windows-PC device pilot) and P6's Raspberry Pi extension are blocked only on missing physical hardware, not code; P6 (Kiwi OS) is in active work, with a live bootable, verified ISO, but still no persistent installer, signed updates, or a real physical-hardware test — see P6's acceptance criteria below, unchanged, and CHECKPOINT.md for the exact state. Date: 2026-09-14

#Product requirements

• Each user has a personal KIWI, linked to their account, devices, memory and personalities.
• Website-led device pairing. Full PC access requires a locally installed agent; website consent alone cannot grant operating-system access.
• File deletion, command execution, program operations and modifications require confirmation. Pairing is not blanket execution approval. Run with the user's OS permissions; elevation remains subject to OS approval.
• Telegram and web address the user's selected device. Offline devices are reported explicitly; expired approvals must not execute on reconnection.
• Installable terminal product with account login, interactive TUI, coding, installation management and diagnostics.
• Real bootable Kiwi OS ISO with desktop and a settings switch to a fullscreen geometric face with voice interaction.
• Windows is the only supported host for the public companion installer in v1.
• Admin rooms let personal KIWI representatives and personalities exchange useful lessons without personal information. Refer to owners as "my user"; remove identifying context as well as names. Shared participation is opt-in.
• Kiwi OS v1 uses customized Linux. Preserve the experimental Rust kernel as a separate future track.

#Evidence and Grok comparison

Source: https://x.ai/news/introducing-grok-bot (read 2026-09-08). The article describes cloud computers, persistent conversations, agent coordination, group threads and routines learned from demonstrations. It does not establish a Telegram implementation.

#Delivery order and acceptance criteria

##P0 — Architecture baseline and acceptance scenarios

Trace an actual request through web, Telegram, engine, memory and execution. Resolve embedded per-user brain ownership before consolidation. Audit existing authorization and OpenCode runtime callers. Preserve unrelated work. Acceptance: documented state ownership, two-user/two-device isolation scenarios, and confirmed baseline failures.

##P1 — Local agent, account pairing and action approval

Website offers install/open agent, account login, short-lived single-use pairing and local device acceptance. Agent establishes an authenticated outbound encrypted connection. Users can revoke devices. Route tasks and approvals by user, device and exact action; reject replay, changed actions and expired approval. Show command/path/change preview and results. Prevent duplicate execution after reconnect. Start with a minimal local installer required for pairing. Acceptance: two users cannot access each other's devices; proposed write cannot run before approval; revocation and reconnect behave correctly; host PC is never a fallback execution target.

##P2 — Distribution and full TUI

Package name/registry ownership must be verified before promising npm install kiwi. Provide a built executable package and explicit launch after installation, then browser login and TUI. Global installation and local project installation have different commands; document the real supported commands once ownership is verified. Do not start an interactive application in an npm install lifecycle hook. Provide chat, project selection, coding diffs, approvals, cancel, tasks, device status and diagnosis. Plan update/uninstall and clean-machine verification. Do not require the development repository to run. Acceptance: clean machine installation, account association and an approved coding task work end to end; denial leaves project unchanged.

##P3 — Telegram and shared task experience

Link Telegram identity to account securely. Select device, chat naturally, exchange voice/files, show progress and offer approve/reject/cancel. Resume task context across interfaces with explicit conversation boundaries. Never send private PC approvals into shared group chats. Acceptance: a Telegram request executes only on the linked selected PC after its required approval, and results match the web/TUI task record.

##P4 — Reliable memory and learning infrastructure

Keep private user memory distinct from approved shared knowledge and agent interpretations. Preserve PDF sources/pages, correction and deletion. Keep memory ownership consistent across clients. Add behavioral evaluations for recall, privacy, unsupported conclusions and restart continuity. Acceptance: retained claims are traceable and correctable, users remain isolated, and changes can be evaluated against a baseline.

##P5 — Admin rooms and continuous improvement

Personal representatives coordinate their personalities in scoped rooms. Private rooms remain per account; shared rooms receive only opt-in sanitized lessons. Administrators see shared discussions, candidate lessons and evaluation results, not private source conversations. Remove names, contacts, paths, secrets, document excerpts and combinations of details that identify an owner. A rejected candidate never enters the shared room. Model expressions of frustration/comfort are generated role behavior, not evidence of subjective suffering. Learning loop: observed outcome -> reflection -> candidate lesson -> privacy/provenance checks -> evaluation -> versioned adoption -> rollback if regression. Dialogue alone does not train model weights or prove improvement. Optional model fine-tuning is a separate evaluated pipeline with consented data, held-out tests and rollback, not autonomous production weight changes. Bound sessions by turns, cost and stop conditions. No room may issue PC actions outside the normal approval pathway. Acceptance: measurable improvement on held-out cases without private-data leakage or personality collapse; unproven lessons remain candidates.

##P6 — Kiwi OS product

Deliver an actual bootable x86_64 UEFI ISO based on customized Linux, with KIWI branding, desktop, browser, terminal, settings and integrated agent. Select and pin the maintained Linux base during OS implementation after checking drivers, redistribution and reproducible image tooling. Keep the Rust kernel in its existing directory as an experimental track, outside v1 delivery. The Linux agent adapter is internal to the OS; it does not expand the public companion installer beyond Windows. Preserve face milestones from CHECKPOINT.md: M1 math/presets, M2 renderer, M3 integration, M4 live state/audio, M5 validated deployment. Add desktop-to-face mode switching, microphone consent, interruption, voice tasks with explicit spoken/visual confirmation and keyboard fallback. Reuse account, local agent, task and memory contracts across modes. Acceptance: ISO boots in VM; desktop and face mode switch both ways; microphone/speaker and an approved task work; restart of an installed system preserves settings. Ship live preview first, followed by an installer with explicit target-disk confirmation, persistent user storage and recovery path. Never overwrite a physical disk during unattended validation. Verify signed update artifacts, recovery from failed update, ISO checksum and one named physical test device before claiming hardware support. Existing four-week estimates are not adopted without validation.

#Target architecture and state ownership

• Clients: web, Telegram, TUI, and OS desktop/face.
• Shared control service: account identity, device registry, conversation/task records, approvals and routing. Retain the existing local hosting plus tunnel for pilot deployment; do not migrate hosting or database without a demonstrated requirement.
• Personal mind: one logical owner of memory, persona and conversation state per account. Audit existing embedded web and engine brains before choosing code to retain. An offline fallback must not silently create competing authoritative memories.
• Device agent: local file, process, command and desktop interaction adapters; enforce approval locally as well as on the server. Tokens are per device, revocable and stored using OS credential facilities.
• Learning service: sanitized proposals, shared discussions and versioned evaluation/adoption. It cannot invoke device tools.
• Persistent records: account/device, conversation/message, task/action/approval/event, memory/source, room/participant/lesson/evaluation. Every private record and lookup is scoped to its owner.

Task path: client -> authenticated account -> selected device -> proposal -> exact-action approval -> local validation -> execution -> recorded result. No device selection may resolve to the project host by default.

#Action and autonomy contract

• Access is as the signed-in Windows user, not unrestricted administrator access. UAC and protected OS surfaces still apply.
• Reading is limited to user-enabled locations and capabilities; never upload the whole disk for context. Screen/browser inspection starts only in an enabled task context.
• Commands, file writes/deletes and program operations require an approval preview, including target device, paths, command or diff and expected effects. A materially changed action requires a new approval.
• Approval binds owner, device, action digest and expiry and is consumed once. Offer reject, cancel and revoke from the user's authenticated private interface.
• Track proposed, awaiting approval, running, succeeded, failed, cancelled and unknown outcomes. A lost connection after execution is an unknown outcome to reconcile, not permission to repeat a non-idempotent action.
• Cancellation stops further work and attempts to stop the active process; completed side effects cannot always be undone. Prefer recoverable deletes and backups for edits where practical.
• Voice confirmations follow the same action contract. Use an authenticated visual confirmation for ambiguous/high-impact requests; background audio must not authorize a sensitive action.
• No unattended overnight PC work while a device is off. Cloud conversation availability depends on the hosted service being online. Cloud execution machines are outside v1.

#Face and voice milestones retained from the previous checkpoint

1. M1: math primitives and expression presets.
2. M2: geometric Canvas renderer, gaze, breathing and blinking; performance measured on a named test machine.
3. M3: replace the existing /os face while preserving boot/sleep/mode behavior; respect reduced motion and pause unnecessary rendering.
4. M4: connect listening/thinking/speaking to actual task and audio events; microphone opt-in, interruption, connection-loss state and keyboard fallback.
5. M5: verify web deployment, then reuse the face in the Linux desktop shell. Target 60 fps rather than claiming it before measurement.

No permanent text overlays in face mode. A separate confirmation/settings surface is available when the user must inspect an action; returning restores the face.

#Rollout, verification and recovery

• P0 baseline first; P1 minimal pairing/execution is the first demo. P2 and P3 depend on P1. P4 basic ownership is required by P1, while richer memory work is delivered after P3. P5 depends on P4. Face M1-M3 can proceed after shared state contracts are settled; OS integration depends on the shared agent/task contracts and M4.
• Start with the owner's Windows PC, then a second test account/device, then an opt-in pilot. Keep existing chat usable during migration through explicit feature flags and reversible schema changes.
• Run repository commands from the root: npm run typecheck, npm run typecheck:web, npm run test, npm run test:mind as relevant. Use existing deploy/test skills. Package and ISO checks are additional dedicated gates, not substitutes.
• Exercise account isolation, pairing replay/expiry, device revocation, denied and changed actions, double delivery, disconnect after execution, restart, secret redaction and backup restoration.
• Verify TUI resizing, Unicode, cancellation, clean-machine installation and removal. Verify Telegram private identity binding and that group messages cannot approve private actions.
• Measure task completion, incorrect actions, latency, repeated approvals and memory quality before and after changes. Shared lessons use held-out evaluation cases and preserve individual personalities.
• Start rooms manually with bounded sessions; scheduled operation remains disabled until a per-session and daily spending limit is configured. Log usage without private prompts or secrets.
• Publishing npm packages, distributing installers/ISO and production rollout are explicit release gates after validation; this planning document performs none of them.

#Approved decisions and first executable milestone

Approved decisions: Windows companion only; Linux x86_64 UEFI OS; existing hosting for pilot; explicit per-action approvals; opt-in sanitized room participation; no administrator access to private source chats; manual room sessions initially; no production model-weight training in v1.

First delivery milestone: baseline audit plus one vertical slice in which two test accounts pair separate Windows devices, submit a proposed file edit from the web, approve or reject it, and see a recorded result only from the correct device. Include expiry, revocation and duplicate-delivery checks before expanding tools.

Budget and schedule are estimated after P0 using actual module condition and installer constraints. Do not promise the previous four-week OS schedule.

This approved plan supersedes earlier product priorities. CHECKPOINT.md tracks execution; the former face-only checkpoint and Rust plan remain historical references. Implementation may proceed within the approved scope.

#Documentation maintenance

Canonical pair: docs/KIWI-UNIFIED-PLAN.en.md and docs/KIWI-UNIFIED-PLAN.ro.md. Update both in the same change when scope, decisions, acceptance criteria or stage status change. Keep revision numbers aligned. Update CHECKPOINT.md with actual evidence, remaining work and the next step after each milestone. Do not mark planned behavior as implemented. Record new architecture decisions in docs/adr; preserve historical decisions and mark supersession explicitly. Read relevant project skills before each task; use kiwi-test and kiwi-deploy for their workflows.

#P0 implementation evidence (partial)

• ADR-0006 documents a single-tenant admin engine and an embedded per-user brain for other users; this must be reconciled with the new account/device model, not flattened into shared state.
• web/src/app/api/chat/route.ts resolves browser or machine identity through currentUserIdFrom, scopes attachment selection by userId, and checks CLI subscription access. Complete downstream ownership and approval checks remain to be traced.
• The non-streaming chat route incorrectly sent all users to the owner engine. Corrected locally: only admin browser requests without Authorization may use it; other identities use their personal embedded brain. Both chat routes now reject foreign/missing/malformed attachment IDs before history/quota consumption and link each verified file once. Clean SQLite startup creates the missing message_files table.
• Direct owner Telegram now denies empty allowlists and group commands; action/proposal callbacks bind the trusted sender, private chat and delivered message, expire after five minutes and are single-use. /open requires confirmation. The shared owner brain and remaining broad execution paths still need audit; this is not the P1 device contract.
• Test environment blockers were repaired. Validation and remaining gaps are recorded in the P0 audit and Windows pilot. No deployment or two-PC acceptance. The read-only attachment preflight on data/kelvin.db found no message_files table; the startup migration remains required and no production data was changed.

Revision 11: body/message bounds on the chat routes — revision 11 details live in the P0 audit and chat continuity; 205 mind/web tests in 30 suites.

Revision 10: chat continuity and coordinated deletion: ConversationManager serializes per-thread delivery (runSerialized), the engine exposes DELETE /api/chat/scoped (validates the owner-web:v1:<sha256> identity and waits for the in-flight turn before forgetting the thread), and the web, on deleting an admin browser session, asks the engine to forget the matching scoped thread without blocking on engine failure. POST /api/documents/organize refuses any non-dryRun. Verification: 96 engine tests passed, one optional semantic skip; 200 mind/web tests in 29 suites; both typechecks passed.

Revision 8: chat transport continuity routes admin browser JSON and SSE through the same owner endpoint. An engine failure is explicit and never switches to the embedded account mind; the browser never automatically repeats a failed or partial request through JSON. SSE rejects Authorization headers, including alongside an admin cookie. The owner reply is buffered, not incremental model streaming. Current verification: 192 mind/web tests in 28 suites, web typecheck, isolated production build and Edge chat probe passed. Persistent personal state, internal engine fallback and explicit conversation boundaries remain open. No production deployment.

Revision 7: host action authorization now enforces tool scope in JSON/stream/offline paths, composes configured and caller restrictions, preserves the originating approval policy and prevents internal routine text from authorizing mutations. Known host changes require confirmation; previews are complete or refused. Direct Telegram rechecks policy. Autonomous dev launch, bulk document moves and disk reaping are blocked pending exact plans. Revision 7 validation: 90 engine tests passed, one optional semantic test skipped; 180 mind/web tests in 27 suites passed. P0 remains open for memory continuity, background automation/plugin paths and exact target migration. No production rollout.

#Execution status — revision 17 (P2 row updated revision 21; P3 row updated revision 26; P4 row updated revision 27; P5 row updated revision 28)

The P1 pilot is isolated test infrastructure while P0 remains open; it does not bypass the P0 release gate. No stage is marked complete solely because a unit suite passes. Continue by closing the named P0 gaps and validating the first P1 device demonstration before broadening execution.

Revision 6 evidence: attachment lifecycle now checks conversation ownership, reserves upload quota transactionally, confines deletion to managed files and respects explicit expiry. Unknown/legacy files are preserved by scheduled cleanup; source PDF libraries are unchanged. Invalid API credentials no longer inherit browser access. Isolated verification builds current sources against an empty DB and synthetic configuration; the production build passed after fixing eager email-client initialization. Web/mind validation passes 177 tests in 27 suites. The Edge/HTTP probe also passed with two synthetic accounts, a real temporary edit, denial/revocation and result persistence after restarting the probe server. Local APPLY was simulated on one PC; two-PC acceptance remains open.

#Recommendations integrated into delivery

• P0/P1: reconcile identity and state ownership before adding more agents. Trace one complete task through every boundary instead of inferring isolation from folder structure.
• P1/P3: persist task results and reconcile unknown outcomes; provider failure, PC restart or network loss must not duplicate side effects. Reuse the same approval and task contract across clients.
• P4: treat the PDF library as source knowledge, not automatic model training. Store provenance, distinguish facts from inference and test correction, forgetting and restart recall.
• P5: evaluate shared lessons against held-out cases before adoption. Track helpfulness and regressions; keep personal voices distinct and allow rollback.
• P6: reuse shared services and validate desktop, microphone, audio and recovery before hardware expansion. The Rust boot result is historical evidence, not proof of Linux OS delivery.
• Across stages: measure completion, latency, memory accuracy and restore reliability against the P0 baseline. Prioritize confirmed defects over additional subsystems.

#Documentation completion criteria

For every relevant project change, update this plan and its translation, affected documents under docs/present/en and docs/present/ro, the architecture map when contracts change, and CHECKPOINT.md before handoff. Record changed behavior, evidence, limitations and the next step. Read affected source documents in full before editing their technical claims. Research guides and ADR history are references, not proof of implementation. Do not rewrite unrelated facts or translate secrets/private conversations into documentation.

Navigation and coverage: Documentation index. Historical presentation details are not renewed release promises. P0 is in progress; P1 has a local disabled pilot and P2 initial package evidence. P2–P6 are not accepted deliveries.