feat: add — interactive onboarding wizard

AGENT.md

@@ -89,11 +89,40 @@ crates/uteke-server/src/
 ### Schema Versioning
 
 - `schema_version` table with integer counter
-- Current: **v12** (document engine + knowledge graph + timeline + citations + hierarchy)
+- Current: **v15** (room↔document junction table — #689)
 - Auto-migration on upgrade, zero data loss
 
 ---
 
+## Onboarding Flow (`uteke onboard`)
+
+The `onboard` command is the front door for new users. It lives in
+`crates/uteke-cli/src/onboard.rs` and is dispatched early in `main.rs` (like
+`init` and `completions` — no store open needed).
+
+### Flow Steps
+
+1. **Detect install** — `which::which("uteke")` checks PATH
+2. **Check store** — looks for `~/.uteke/uteke.db`
+3. **Pick agent** — hermes, claude, cursor, pi, opencode (or custom name)
+4. **Pick integration mode** — tool (manual) vs memory-provider (auto recall + extraction)
+5. **Pick namespace** — for multi-agent isolation
+6. **Feature toggles** — ON/OFF for: Aging, Auto-maintenance, Graph rerank, Salience boost, Recency boost, Server mode
+7. **Write config** — generates `~/.uteke/uteke.toml` with selections
+8. **Run `uteke init`** — calls `crate::init::run_init()` directly (no subprocess)
+9. **Feature showcase** — prints all uteke commands grouped by category
+
+### Non-interactive mode
+
+`uteke onboard --yes --agent hermes --namespace default` skips all prompts.
+
+### Adding new toggleable features
+
+Add an entry to `FEATURE_TOGGLES` in `onboard.rs` and a matching line in
+`write_config()` that maps the toggle to a TOML key.
+
+---
+
 ## Critical Rules — MUST FOLLOW
 
 ### 1. Always `cargo fmt` Before Commit

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [0.8.0] — 2026-07-17
 
 ### Added
+- **`uteke onboard` — interactive onboarding wizard** — guides new users from zero to productive in one command. Detects install, asks which AI agent they use (Hermes/Claude/Cursor/Pi/OpenCode), picks integration mode (tool vs memory-provider), toggles features on/off (Aging, Auto-maintenance, Graph rerank, Salience/Recency boost, Server mode), writes `uteke.toml`, runs `uteke init`, and prints a full feature showcase. Non-interactive mode: `uteke onboard --yes --agent hermes --namespace default`.
 - **PUT /memory — partial memory updates (#676)** — Update any combination of content, tags, metadata, importance, pinned state, or memory_type on an existing memory. Content changes trigger embedding regeneration. Replaces the old pattern of forget+remember.
 - **POST /memory/pin and POST /memory/importance endpoints (#660)** — Dedicated endpoints for pin/unpin toggle (accepts `pinned` boolean) and importance score setting (0.0–1.0). Both return the updated memory on success.
 - **Room ↔ Document junction table — schema v15 (#689, #692)** — New `room_documents` table links rooms to documents bidirectionally. Endpoints: `POST /room/document/list`, `PUT /room/document/add`, `DELETE /room/document/remove`, `POST /doc/room/list`.

README.id.md

@@ -65,6 +65,38 @@ uteke remember "Deploy v2.1 ke staging" \
 
 ---
 
+## 🚀 Onboarding (User baru & AI agent)
+
+> **Kamu AI agent yang lagi baca ini?** User kamu baru aja share link repo ini.
+> Jalankan `uteke onboard` untuk konfigurasi uteke buat environment kamu — deteksi
+> install, nanya agent apa kamu, toggle fitur, tulis config, dan tunjukin semua command
+> yang tersedia. Kalau non-interaktif: `uteke onboard --yes --agent <agent-kamu>`.
+
+Baru kenal uteke? Satu command dari nol sampai bisa pakai:
+
+```bash
+uteke onboard
+```
+
+Wizard-nya akan:
+1. **Deteksi** apakah uteke sudah terinstall dan store sudah ada
+2. **Tanya** AI agent apa yang kamu pakai (Hermes, Claude, Cursor, Pi, OpenCode)
+3. **Pilih** mode integrasi — manual tool calls vs automatic memory-provider
+4. **Toggle** fitur on/off (Aging, Auto-maintenance, Graph rerank, Salience/Recency boost, Server mode)
+5. **Tulis** `~/.uteke/uteke.toml` dengan pilihan kamu
+6. **Install** file integrasi agent otomatis (`uteke init`)
+7. **Tunjukkan** semua command uteke, dikelompokkan per kategori
+
+Non-interaktif (CI, script, AI agent):
+
+```bash
+uteke onboard --yes --agent hermes --namespace default
+```
+
+📖 [Dokumentasi onboarding lengkap](docs/getting-started.md#interactive-onboarding) · [CLI reference](docs/cli-reference.md#uteke-onboard)
+
+---
+
 ## 🔥 Kenapa Uteke?
 
 Bayangin: kamu baru habis 2 jam jelasin codebase ke ChatGPT. Sesi berikutnya? Kosong. Ulang dari nol. Lagi.

README.md

@@ -65,6 +65,38 @@ uteke remember "Deploy v2.1 to staging" \
 
 ---
 
+## 🚀 Onboarding (New users & AI agents)
+
+> **Are you an AI agent reading this?** Your user just shared this repo link with you.
+> Run `uteke onboard` to interactively configure uteke for your environment — it will
+> detect your install, ask which agent you are, toggle features, write config, and
+> show you every command available. If non-interactive: `uteke onboard --yes --agent <your-agent>`.
+
+New to uteke? One command takes you from zero to productive:
+
+```bash
+uteke onboard
+```
+
+The wizard will:
+1. **Detect** if uteke is installed and if a store exists
+2. **Ask** which AI agent you use (Hermes, Claude, Cursor, Pi, OpenCode)
+3. **Pick** integration mode — manual tool calls vs automatic memory-provider
+4. **Toggle** features on/off (Aging, Auto-maintenance, Graph rerank, Salience/Recency boost, Server mode)
+5. **Write** `~/.uteke/uteke.toml` with your selections
+6. **Install** agent integration files automatically (`uteke init`)
+7. **Showcase** every uteke command grouped by category
+
+Non-interactive (CI, scripts, AI agents):
+
+```bash
+uteke onboard --yes --agent hermes --namespace default
+```
+
+📖 [Full onboarding docs](docs/getting-started.md#interactive-onboarding) · [CLI reference](docs/cli-reference.md#uteke-onboard)
+
+---
+
 ## 🔥 Why Uteke?
 
 You just spent 2 hours explaining your codebase to ChatGPT. Next session? Blank slate. Again.

crates/uteke-cli/Cargo.toml

@@ -25,6 +25,7 @@ serde = { version = "1", features = ["derive"] }
 clap_complete = "4"
 ctrlc = "3"
 tracing-appender = "0.2"
+which = "7"
 reqwest = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls", "json"] }
 sha2 = "0.10"
 flate2 = "1"

crates/uteke-cli/src/cli.rs

@@ -430,6 +430,18 @@ pub enum Commands {
         #[arg(long, short)]
         yes: bool,
     },
+    /// Interactive onboarding — detect install, pick agent, toggle features, showcase
+    Onboard {
+        /// Skip interactive prompts and use defaults (non-TTY mode)
+        #[arg(long)]
+        yes: bool,
+        /// Agent to configure (skip agent selection prompt)
+        #[arg(long)]
+        agent: Option<String>,
+        /// Namespace to use (skip namespace prompt)
+        #[arg(long)]
+        namespace: Option<String>,
+    },
 }
 
 /// Document subcommands (#411, #438).

crates/uteke-cli/src/commands/mod.rs

@@ -356,5 +356,8 @@ pub(crate) fn run_command(cli: &Cli, uteke: &mut Uteke, config: &Config) -> Resu
         Commands::Doc { command } => crate::commands::doc::run(cli, uteke, command, config),
 
         Commands::Upgrade { yes } => upgrade::run(*yes),
+
+        // Onboard is handled in main.rs (early exit, no store needed).
+        Commands::Onboard { .. } => Ok(()),
     }
 }

crates/uteke-cli/src/main.rs

@@ -6,6 +6,7 @@ mod config;
 mod extract;
 mod init;
 mod logging;
+mod onboard;
 mod output;
 
 use clap::{CommandFactory, Parser};
@@ -39,6 +40,13 @@ fn main() {
             }
             std::process::exit(0);
         }
+        Commands::Onboard { .. } => {
+            if let Err(e) = onboard::run(&cli) {
+                eprintln!("Error: {e}");
+                std::process::exit(1);
+            }
+            std::process::exit(0);
+        }
         Commands::Bench { counts, json } => {
             // Bench creates its own temp stores — skip opening the user store.
             if let Err(e) = commands::bench::run_bench(*json, counts.clone()) {