feat(agent): add CLI onboarding wizard for first-time configuration

[AlexMikhalev]

Summary

Implements an interactive CLI onboarding wizard for terraphim-agent that provides first-time configuration with:

• 6 Quick-start templates for common use cases
• Custom role configuration with haystacks, LLM, and knowledge graph
• Non-interactive mode for CI/CD and scripting
• Add-role capability to extend existing configurations

Templates Included

Template	Description
terraphim-engineer	Semantic search with knowledge graph embeddings (primary)
llm-enforcer	AI agent hooks with bun install KG (second priority)
rust-engineer	QueryRs integration for Rust docs
local-notes	Ripgrep search for local markdown
ai-engineer	Ollama LLM with knowledge graph support
log-analyst	Quickwit integration for log analysis

Usage

# List available templates
terraphim-agent setup --list-templates

# Apply template directly (non-interactive)
terraphim-agent setup --template terraphim-engineer

# Apply template with custom path
terraphim-agent setup --template local-notes --path ~/my-notes

# Interactive wizard
terraphim-agent setup

# Add role to existing config
terraphim-agent setup --add-role --template rust-engineer

Test Plan

• Unit tests (30 tests passing)
• Integration tests (11 tests passing)
• CLI manual testing (--list-templates, --template, --path, --add-role)
• Phase 4 verification report attached
• Phase 5 validation report attached

Verification & Validation Reports

• Phase 4 (Verification): .docs/verification-cli-onboarding-wizard.md

  • Traceability matrix from design to implementation
  • All 30 unit tests + 11 integration tests passing
  • All 6 templates verified working

• Phase 5 (Validation): .docs/validation-cli-onboarding-wizard.md

  • All 7 original requirements satisfied
  • System tests passing
  • UAT scenarios prepared for sign-off

Files Changed

New Files

• crates/terraphim_agent/src/onboarding/mod.rs - Module root with error types
• crates/terraphim_agent/src/onboarding/templates.rs - Template registry
• crates/terraphim_agent/src/onboarding/wizard.rs - Wizard orchestration
• crates/terraphim_agent/src/onboarding/prompts.rs - Interactive prompts
• crates/terraphim_agent/src/onboarding/validation.rs - Validation utilities
• crates/terraphim_agent/tests/onboarding_integration.rs - Integration tests

Modified Files

• crates/terraphim_agent/Cargo.toml - Added dialoguer dependency
• crates/terraphim_agent/src/main.rs - Added Setup command
• crates/terraphim_agent/src/service.rs - Added add_role/set_role methods
• crates/terraphim_agent/src/lib.rs - Exported onboarding module

Related Issues

Closes #TBD - CLI onboarding wizard implementation

Generated with Terraphim AI

[claude]

Code Review: CLI Onboarding Wizard

Summary

This is a well-structured PR implementing a comprehensive CLI onboarding wizard. Strong type safety, proper error handling, and excellent test coverage (30 unit + 11 integration tests).

Overall: APPROVE with minor suggestions

---

Strengths

Code Quality

• Excellent separation of concerns across 5 modules
• Proper Result<T, E> usage throughout, no .unwrap() calls
• Custom error types with thiserror
• Follows project CLAUDE.md conventions

Testing

• 30 unit tests covering all edge cases
• Integration tests for end-to-end workflows
• Both Phase 4 (verification) and Phase 5 (validation) reports included

Documentation

• Module-level docs with examples
• Comprehensive test plans and evidence

---

Issues & Suggestions

1. Dead Code Warnings (Minor - Easy Fix)

Verification report mentions unused code:

• ValidationError::PathNotFound (never constructed)
• is_first_run() (never used)
• prompt_confirm(), prompt_input() (never used)

Recommendation: Remove OR add #[allow(dead_code)] with TODO comments

2. Tilde Expansion (Security/UX)

Templates use ~/Documents default paths. Ensure validation::expand_tilde() is called before use.

3. Error Messages (UX Enhancement)

Consider adding examples to error messages:

// Instead of:
"Ripgrep haystack should use a local path"

// Consider:
"Ripgrep service requires a local file path (not a URL). Example: ~/Documents"

4. Path Validation TOCTOU

validate_path() warns but doesn't fail if path missing. Ensure service layer handles missing paths gracefully.

5. Missing Documentation

• Add user guide in docs/ directory
• Update main README with terraphim-agent setup command
• Add troubleshooting section

---

Security Assessment

Good - No major concerns:

• No hardcoded credentials
• Proper URL validation
• 1Password integration for secrets
• Read-only haystacks by default
• PathBuf provides path injection protection

---

Performance

• < 200ms startup (excellent)
• No bottlenecks identified
• Appropriate use of synchronous I/O for CLI

---

Test Coverage

Module	Tests	Status
mod	2	✅
templates	10	✅
validation	10	✅
wizard	6	✅
prompts	2	✅
Total	30	✅

Gap: Interactive prompts require manual testing (acceptable given complexity)

---

Action Items

Before Merge:

1. ❗ Fix/annotate dead code warnings for clippy
2. ❗ Verify tilde expansion applied to default paths

After Merge (Enhancements):

3. Create issue for first-run auto-prompt feature
4. Add user documentation
5. Enhance error messages with examples
6. Update README

---

Questions

1. Are prompt_confirm()/prompt_input() needed for future work?
2. Should we track auto-launch wizard as a GitHub issue?
3. Is haystack weight parameter planned for follow-up?
4. Is 10 themes (vs desktop's 21) intentional for CLI simplicity?

---

Final Recommendation

APPROVE 🎉

Why:

• Follows all project conventions
• Strong test coverage (100% passing)
• Requirements fully implemented
• Comprehensive documentation
• Low risk, high confidence

The disciplined development approach (research → design → implementation → verification → validation) has produced a robust, well-tested feature. Identified issues are minor and can be addressed in follow-ups.

Great work! 🚀

[claude]

Code Review: CLI Onboarding Wizard

Overview

This is a well-implemented feature that successfully adds an interactive CLI onboarding wizard to terraphim-agent. The implementation is thorough, well-tested, and follows Rust best practices.

Strengths

Code Quality & Architecture

• Clean module organization with clear separation of concerns
• Strong type safety with custom error types and enums
• Good abstraction with ConfigTemplate pattern
• Comprehensive error handling

Test Coverage

• 30 unit tests passing across all modules
• 11 integration tests covering end-to-end workflows
• Verification and validation reports included

Documentation

• Excellent module-level documentation with usage examples
• Clear inline comments
• Comprehensive reports in .docs/

Feature Implementation

• 6 well-designed templates covering common use cases
• Feature parity with desktop ConfigWizard
• CLI-exclusive enhancements: path/URL validation, 1Password integration

Issues & Recommendations

Critical: None

Important

1. Typo at terraphim_service/src/lib.rs:121
Line has double .to() - needs fix before merge:

let is_file_not_found = e.to().to_string().contains("file not found");

Should be:

let is_file_not_found = e.to_string().contains("file not found");

2. Dead Code Warnings
Several unused items per verification report:

• validation.rs:31 - ValidationError::PathNotFound
• wizard.rs:113 - is_first_run()
• prompts.rs:576,585 - prompt_confirm(), prompt_input()

Recommendation: Add #[allow(dead_code)] or remove unused items.

Moderate

3. Missing Feature Gate Documentation
The repl-interactive feature should be documented in module comments.

4. Error String Matching
Consider documenting why string matching is necessary for OpenDAL errors.

Security Review

✅ No security concerns identified

• Good path validation with tilde expansion
• Proper URL scheme validation
• Appropriate credential handling

Final Verdict

✅ APPROVED WITH MINOR FIXES

Required Before Merge:

1. Fix typo at terraphim_service/src/lib.rs:121
2. Address dead code warnings

Recommended:

3. Add feature gate documentation
4. Document error matching approach

Test Results

• ✅ 30/30 unit tests passing
• ✅ 11/11 integration tests passing
• ✅ All 6 templates functional
• ✅ Phase 4 verification: PASS
• ✅ Phase 5 validation: PASS

Excellent work on comprehensive testing, documentation, and following the disciplined development process!

---

Generated with Terraphim AI

[claude]

Code Review: PR #492 - CLI Onboarding Wizard

Overall Assessment

Verdict: ✅ Approve with minor suggestions

This is a well-structured feature implementation that follows disciplined development practices (Phases 1-5). The PR demonstrates:

• ✅ Comprehensive test coverage (30 unit + 11 integration tests)
• ✅ Formal verification and validation reports
• ✅ Clear modular architecture
• ✅ Requirements traceability
• ✅ Non-breaking additive changes

Positive Highlights

1. Excellent Modular Architecture

The onboarding feature is cleanly separated into focused modules:

• mod.rs - Error types and module organization
• templates.rs - Template registry (data layer)
• wizard.rs - Orchestration logic (business layer)
• prompts.rs - User interaction (presentation layer)
• validation.rs - Input validation (cross-cutting concern)

This separation of concerns follows Rust best practices and makes the code maintainable.

2. Comprehensive Testing Strategy

• 30 unit tests + 11 integration tests is excellent coverage
• Integration tests in separate tests/ directory (follows Cargo conventions)
• Phase 4 verification and Phase 5 validation reports demonstrate thorough QA

3. User Experience Design

• Multiple interaction modes (interactive, non-interactive, list-only)
• Quick-start templates reduce friction
• --add-role flag for incremental configuration (non-destructive)
• Clear command-line interface following Unix conventions

4. Documentation

• Inline documentation in PR description
• Verification/validation reports for traceability
• Website documentation updated

Areas for Improvement

1. Path Validation Security ⚠️ (Medium Priority)

Observation: Templates support path substitution (e.g., --path ~/my-notes).

Security Concerns:

• Shell expansion of ~ must be handled securely
• Path traversal attacks (e.g., ../../etc/passwd)
• Symlink following behavior should be explicit

Recommendation:

• Use shellexpand::tilde() or dirs::home_dir() for ~ expansion
• Canonicalize paths with std::fs::canonicalize() to resolve symlinks
• Validate that resolved paths don't escape expected boundaries
• Document the security model in comments

2. Template Data Validation (Medium Priority)

Observation: 6 templates with hardcoded configurations.

Potential issues:

• URLs in templates may become stale
• Paths may not exist on all systems
• LLM endpoints may require authentication

Recommendation:

• Add runtime validation for template URLs (optional health check)
• Document template assumptions (e.g., "requires Ollama running locally")
• Consider a terraphim-agent setup --validate-template <name> command

3. Error Handling & User Feedback (Minor)

Recommendation: Ensure all interactive prompts have:

• Clear error messages when validation fails
• Graceful handling of Ctrl+C (SIGINT)
• Helpful hints for common mistakes

4. Test Coverage Enhancements (Low Priority)

Current: 30 unit + 11 integration tests (excellent!)

Additional test scenarios to consider:

• Error cases: Invalid template name, write permission denied, malformed config
• Edge cases: Empty path input, special characters, existing config
• Platform differences: Windows paths, macOS case-insensitive filesystems

5. Performance Considerations

Recommendations:

• Ensure terraphim-agent setup --list-templates is fast (<100ms)
• Config writing should be atomic (write to temp, then rename)
• Consider lazy-loading templates to reduce startup time

6. Dependency Audit

New dependency: dialoguer

Recommendation:

• Verify dialoguer is actively maintained
• Review transitive dependencies for security advisories (cargo audit)
• Consider feature-gating to reduce binary size

Security Review

Potential Security Issues

1. Path Injection - See path validation recommendations above
2. Config File Permissions - Sensitive data (API keys) should be 0600
3. TOCTOU - Time-of-check-time-of-use races in path validation

Recommendations

• Add #[forbid(unsafe_code)] to onboarding module
• Sanitize all user inputs before writing to config
• Set restrictive permissions on config files (Unix: 0600)
• Document that secrets should use environment variables, not config files
• Add security audit to CI pipeline (cargo audit)

Compliance with CLAUDE.md Guidelines

✅ Follows project conventions:

• Rust edition 2024
• Snake_case naming
• Modular organization
• Comprehensive testing
• No mocks in tests

✅ Error handling:

• Custom error type (OnboardingError) follows thiserror pattern

Final Recommendations

Must Address Before Merge (P0):

1. ⚠️ Security: Verify path validation prevents traversal attacks
2. ✅ Testing: Run full test suite on CI (cargo test --workspace)
3. ⚠️ Permissions: Set config file permissions to 0600

Should Address (P1):

1. Add --dry-run flag for safety
2. Verify all template URLs are valid
3. Add shell completion support
4. Test on Windows and macOS

Nice to Have (P2):

1. Add template URL health checks
2. Create user-facing documentation
3. Add telemetry for template usage analytics

Questions for Author

1. How are template URLs validated? Are there health checks?
2. What happens if --add-role is used with a duplicate role name?
3. How does the wizard handle Ctrl+C gracefully?
4. Are config file permissions set securely (0600 on Unix)?

Conclusion

This is a high-quality PR that demonstrates disciplined engineering:

• Clear requirements → design → implementation → verification → validation
• Comprehensive test coverage
• Well-organized code structure
• Thoughtful UX design

Recommendation: ✅ Approve pending verification of security concerns (path validation, file permissions) and test suite passing on CI.

The code follows Terraphim AI best practices and will significantly improve the first-run user experience. Great work!

---

Reviewed by: Claude Code (Terraphim AI)
Date: 2026-01-29
PR: #492

[claude]

Code Review: CLI Onboarding Wizard

This is high-quality work with excellent test coverage (41 tests passing). The implementation follows Rust best practices with proper error handling and no unsafe code.

✅ Strengths

• Comprehensive error handling with custom OnboardingError enum
• 30 unit + 11 integration tests with Phase 4/5 verification reports
• Strong security: URL/path validation, no hardcoded credentials
• Clean module structure with good separation of concerns

🔍 Issues Found

1. Dead Code Warnings (Minor) - validation.rs:31, wizard.rs:113, prompts.rs:576,585

   • Recommendation: Add #[allow(dead_code)] or implement usage

2. Async Without Await (wizard.rs:2369)

   • run_setup_wizard is async but has no .await calls
   • Consider making it synchronous

3. Feature Gate Bug (wizard.rs:2371-2376)

   • TTY check only runs with repl-interactive feature
   • Should always check for TTY to prevent confusing errors

4. URL Validation (validation.rs:2044)

   • Only checks prefix/length - consider using url crate for robust parsing

5. Test Improvements

   • Use .expect() instead of .unwrap() for better error messages

🔒 Security Assessment

✅ No injection vulnerabilities
✅ Proper input validation
✅ Safe path handling
⚠️ Consider warning about plain text API key storage

Performance & Documentation

• Negligible overhead for CLI usage
• Well-documented with rustdoc
• Could add more examples in docs

🎬 Verdict

Status: ✅ Approved pending fixes

Required before merge:

1. Fix TTY check feature gate issue
2. Fix or document dead code warnings
3. Consider making run_setup_wizard non-async

Optional improvements:

• Strengthen URL validation with url crate
• Add API key storage warnings
• Use .expect() in tests

Excellent work on this feature! 🚀

---

Generated with Terraphim AI