feat: add uteke onboard — interactive onboarding wizard

[gnoviawan]

Summary

Adds a new uteke onboard command that guides new users from zero to productive in a single interactive flow.

Flow

1. Detect install — checks if uteke is on PATH (via which crate) and if a store exists
2. Agent selection — Hermes, Claude, Cursor, Pi, or OpenCode
3. Integration mode — manual tool (explicit calls) vs memory-provider (auto recall + extraction)
4. Namespace — for multi-agent isolation
5. Feature toggles — ON/OFF for: Aging, Auto-maintenance, Graph rerank, Salience boost, Recency boost, Server mode
6. Config write — generates ~/.uteke/uteke.toml with selections
7. Agent init — runs uteke init --agent <choice> (or --memory-provider) automatically
8. Feature showcase — prints all uteke commands grouped by category (Core Memory, Documents, Knowledge Graph, Rooms, Memory Lifecycle, Maintenance, Import/Export, Agent Integration)

Non-interactive mode

uteke onboard --yes --agent hermes --namespace default

Files changed

File	Change
crates/uteke-cli/src/onboard.rs	New — ~520 lines, full wizard implementation
crates/uteke-cli/src/cli.rs	Add Onboard variant to Commands enum
crates/uteke-cli/src/main.rs	Early-exit dispatch (like init, no store needed)
crates/uteke-cli/src/commands/mod.rs	Non-exhaustive match coverage
crates/uteke-cli/Cargo.toml	Add which = "7" dependency
AGENT.md	Onboarding flow docs + schema v12→v13 fix
CHANGELOG.md	Entry under [Unreleased]
docs/getting-started.md	Interactive Onboarding section
docs/cli-reference.md	Full uteke onboard command reference

Testing

• cargo fmt --check ✅
• cargo clippy -p uteke-cli -- -D warnings ✅ (0 warnings)
• cargo test -p uteke-cli ✅ (43 passed, 0 failed)
• Manual test: ./target/release/uteke onboard --yes --agent hermes runs end-to-end successfully

Note: Could not full-build with onnx feature (no libssl-dev in dev env), but cargo check + cargo clippy + cargo test all pass with onnx temporarily disabled. CI will validate the full build.

[ajianaz]

Code Review: uteke onboard PR #696

Overall: good feature, well-structured code, clean separation. CI all green. But there are issues to address before merge.

---

🔴 Must Fix

1. AGENT.md schema version is wrong (v13 → should be v15)
CURRENT_SCHEMA_VERSION on develop is already 15 (crates/uteke-core/src/memory/store.rs:176). The develop AGENT.md was already stale at v12; this PR bumps it to v13, still behind. Full version map (crates/uteke-core/src/memory/crud.rs:815):

• v15 = room↔document junction table (#689) ← current
• v14 = FTS5 memory_type column (#662)
• v13 = global docs, remove namespace isolation (#614)
• v12 = hierarchical docs (#438)

-- Current: **v13** (global documents, author column, duplicate slug cleanup)
++ Current: **v15** (room↔document junction table — #689)

Also: the PR's description ("author column", "duplicate slug cleanup") doesn't map cleanly to v13/v14/v15 — please correct the description too.

2. get_stats() returns hardcoded placeholder "existing" (onboard.rs:224-228)

fn get_stats() -> String {
    // We can't easily open the store here without uteke-core's onnx feature.
    "existing".to_string()
}

Prints ✓ Existing memory store found: existing memories (:105) — misleading (says "memories" but shows no count). Two options:

• (a) Drop the count claim: just ✓ Existing memory store found (pragmatic, zero-risk).
• (b) Query SELECT COUNT(*) FROM memories — but not via Uteke::open (that triggers validate_backend/onnx embedding init, see main.rs:66 fail-fast — exactly what onboard deliberately avoids, per the author's own comment at onboard.rs:225). Needs a lightweight raw rusqlite connection (add dep to uteke-cli, or expose a count() from uteke-core).

3. write_config() destructively overwrites existing uteke.toml (onboard.rs:367)

std::fs::write(&config_path, toml).map_err(...)?;

If the user already has a uteke.toml, this replaces it wholesale — including the [embedding] section's api_key (config.rs:41, OpenAI key) when they stored it in TOML (rather than via the UTEKE_EMBEDDING_API_KEY env var). That's silent credential loss, not just custom settings. At minimum, when the file already exists and --yes is not set:

⚠ Config file already exists at ~/.uteke/uteke.toml — overwrite? [y/N]

(prefer: backup .bak or merge with existing keys.)

---

🟡 Should Fix

4. prompt_integration_mode() is silent for custom agents (onboard.rs:264-268)

let supports_mp = matches!(agent, "hermes" | "claude" | "cursor" | "pi" | "opencode");
if !supports_mp {
    return Ok(false);
}

Custom agent names skip the prompt with no output at all, which is confusing. Add a line like → Integration mode: uteke-tool (custom agent).

5. validate_agent() is a no-op (onboard.rs:382-389)
Both branches return Ok(agent.to_string()). The name/docstring imply validation, but every input passes. Either remove it and inline agent.clone(), or actually validate (warn on unrecognized agents).

6. Banner box alignment is off by 1 (onboard.rs:74-77, also :188-190)

╔════════════════════════════════════════════════════════════╗
║           Welcome to Uteke Onboarding                       ║
║     The Brain for Your AI — persistent memory engine        ║
╚════════════════════════════════════════════════════════════╝

Top/bottom borders are 64 inner chars; content lines are 65 → the right ║ is pushed out by exactly 1 column. The em-dash — (:76) is also ambiguous-width in many terminals. Same issue in the "Onboarding complete!" box. Use a format/pad helper for consistency.

7. --json flag produces mixed output (new)
onboard forwards the global cli.json flag to run_init (onboard.rs:171 & :173; flag at cli.rs:27) but never handles it itself — so uteke onboard --json prints ASCII banners/steps to stdout interleaved with potential JSON from run_init. Output can't be parsed. Fix: ignore cli.json in onboard (always human-readable) — one line.

---

🟢 Nice to Have

8. Install URL points to main (onboard.rs:85)

println!("    curl -fsSL https://raw.githubusercontent.com/codecoradev/uteke/main/install.sh | sh");

Repo default branch is develop; install.sh exists on both branches, so main resolves fine — but worth confirming whether main is the intended stable/release branch or should follow the develop convention.

9. No unit tests for onboard.rs
515 lines, zero tests. At minimum the pure functions — no stdin mocking needed:

• write_config() output (TOML parse round-trip)
• get_toggle() logic
• validate_agent() behavior

---

✅ What's Good

• Clean early-exit dispatch pattern (matches init/completions/bench convention)
• Direct crate::init::run_init() call instead of subprocess — correct approach
• TOML key mapping matches the actual Config struct fields
• Docs coverage: README, README.id, getting-started, cli-reference, AGENT.md, CHANGELOG — thorough
• Non-interactive --yes mode well designed
• Feature showcase at the end is a nice UX touch

Fix the 🔴 items and I'll approve.

[gnoviawan]

Review Feedback Addressed

Commit: fea30a8

🔴 Must Fix — All Done ✅

1. AGENT.md schema version v13→v15 — Fixed. Now reads Current: **v15** (room↔document junction table — #689).

2. get_stats() hardcoded placeholder — Fixed. Removed the function entirely. Now just prints ✓ Existing memory store found without the misleading count claim.

3. write_config() destructive overwrite — Fixed. Now backs up existing uteke.toml to uteke.toml.bak before overwriting, and prompts for confirmation in interactive mode (--yes skips the prompt but still backs up).

🟡 Should Fix — All Done ✅

4. prompt_integration_mode() silent for custom agents — Fixed. Now prints → Integration mode: uteke-tool (custom agent).

5. validate_agent() no-op — Fixed. Now warns on unrecognized agents: ⚠ 'xyz' is not a recognized agent — init step will be skipped. and lists recognized agents.

6. Banner box alignment — Fixed. Replaced Unicode box-drawing chars with a print_banner() helper that uses ASCII (+/-/|//) with consistent padding. Eliminates the off-by-1 alignment issue and ambiguous-width em-dash.

7. --json flag mixed output — Fixed. Onboard now intentionally ignores the global --json flag — always human-readable. Init is called with json=false.

🟢 Nice to Have — Both Done ✅

8. Install URL — Changed from main to develop to match repo convention.

9. Unit tests — Added 7 tests: get_toggle (3 tests), validate_agent (2 tests), print_banner (1 test), write_config TOML structure (1 test).

Verification

• cargo fmt --check ✅
• cargo clippy -p uteke-cli -- -D warnings ✅ (0 warnings)
• cargo test -p uteke-cli ✅ (50 passed, 0 failed)

[ajianaz]

Migration

Fork repository has been deleted, so this PR branch can no longer be updated directly. All review feedback has been addressed + clippy errors fixed. Closing this PR and recreating from the codecoradev/uteke repo branch.