feat(init): seed starter KB for first-run onboarding

[Crystora]

What changed

vouch init now seeds a starter source and cited starter claim, rebuilds the search index, and prints concrete next steps. The README also includes a 30-second tour that works against the seeded starter KB.

Why

This makes first-run onboarding smoother for new users and agents by giving them an immediately searchable, cited example KB instead of an empty .vouch/ directory. Part of #54.

What might break

No files move. No object model, bundle format, audit-log shape, or kb.* method changes.

Newly initialized KBs will contain one starter source and one starter claim by default. Existing KBs can also receive that starter content if vouch init is run again and the starter claim is not already present.

VEP

Not required. This does not change the object model, kb.* methods, on-disk schema/layout, bundle format, or audit-log shape.

Tests

• make check passes locally (lint + mypy + pytest)
• New / changed behaviour has a test
• CHANGELOG.md updated under ## [Unreleased]

Summary by CodeRabbit

• New Features
  • vouch init now seeds a starter knowledge base (starter source + reviewed claim) and prints clearer multi-step "Next steps" guidance.
• Documentation
  • Added a "30-second tour" demo loop and updated file layout to document seeded starter claim filenames.
• Tests
  • Added onboarding tests validating seeding, idempotency, CLI output, and searchability of the starter KB.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds a deterministic, idempotent starter KB seeder and integrates it into vouch init, updates storage defaults and embedder error handling, adds tests verifying seeding and CLI behavior, and documents the three-step 30-second onboarding tour.

Changes

Onboarding First-Run Experience

Layer / File(s)	Summary
Starter KB content and seeding module src/vouch/onboarding.py	Defines fixed starter markdown source and claim text as module constants. Introduces StarterSeedResult dataclass to report which artifacts were created. Main seed_starter_kb(store, approved_by) entrypoint calls _starter_source and _starter_claim helpers to idempotently create or skip starter source and claim via filesystem/store checks and SHA-256 deterministic IDs.
Storage layer config defaults and error handling src/vouch/storage.py	New _starter_config() helper centralizes default KB configuration (version, review rules, retrieval backends, agent workflow). KBStore.init uses it to populate config.yaml when missing. Embedding error handler broadened to catch both ImportError and KeyError for missing embedder dependencies.
CLI init command integration and output src/vouch/cli.py	vouch init now imports and calls seed_starter_kb(store, approved_by=_whoami()), rebuilds search index after seeding, and replaces the single "Next: vouch serve" message with expanded "Next steps" list (status, search agent, serve). Prints claim id when starter claim is newly created.
Test coverage for onboarding behavior tests/test_onboarding.py	Four test functions validate that seed_starter_kb creates starter claim with correct evidence and approver; seeding is idempotent (no duplicates on rerun); init command produces searchable starter KB with expected console output; init command succeeds on second run with appropriate messaging.
User documentation and changelog README.md, CHANGELOG.md	README adds a "30-second tour" section with quick init/status/search/cite workflow and guidance for replacing starter claim. File layout section describes starter claim entry vouch-starter-.... CHANGELOG documents new onboarding behavior under Unreleased/Added.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI as "vouch init"
  participant Seeder as seed_starter_kb
  participant Store as KBStore
  participant Index as "search index"
  User->>CLI: run `vouch init`
  CLI->>Seeder: seed_starter_kb(store, approved_by)
  Seeder->>Store: check/create starter source (sha256 id)
  Seeder->>Store: get_claim / put_claim if missing (with evidence)
  Seeder->>CLI: return StarterSeedResult
  CLI->>Index: rebuild index
  CLI->>User: print Next steps and created-claim id (if any)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A starter claim in every KB,
One command to initialize with glee,
Idempotent seeds that never repeat,
Next steps printed, the tour is neat,
Hop in — thirty seconds to see!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(init): seed starter KB for first-run onboarding' clearly and concisely summarizes the main change: adding a starter knowledge base seeding feature to the init command for improved first-run onboarding.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 121: Replace the ambiguous fragment "claims/vouch-starter-..." with an
explicit claim file pattern (for example "claims/vouch-starter-*.claim") so it
reads like the other entries in README.md; update the line that currently
contains that fragment to include the file extension and wildcard to indicate
it’s a claim filename pattern.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: df302aa3-5548-41d7-8c74-5bba08775536

📥 Commits

Reviewing files that changed from the base of the PR and between 96028f5 and 030fab5.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• src/vouch/cli.py
• src/vouch/onboarding.py
• src/vouch/storage.py
• tests/test_onboarding.py

[plind-junior]

Fix MR conflict

[Crystora]

@plind-junior Pls review again

[plind-junior]

It's really needed, thanks for your contribution @bittoby