init

Init — First-Time Setup Wizard

Purpose

Onboards a new user in three acts: capture + verify the LinkdAPI key, delegate thesis/profile drafting to ts-interview, then atomically write everything on explicit confirmation. The thesis is the single source of truth for who we're looking for — ts-interview owns that conversation, init owns the write.

States

welcome → key → thesis_draft → summary → write. A reinit or legacy-migration branch may intercept before welcome.

State 1: welcome

Informational. Auto-advance to key.

"Talent-scout finds pre-founders worth backing. Setup has two parts: your API key, then a short interview to capture who you're looking for. Nothing is written to disk until you confirm at the end."

State 2: key

First, check whether a key is already configured. Call configure_api_key with { verify: true }:

• { ok: true, data: { verified: true, key_preview } }: Announce "Key already configured: <preview>" and advance to thesis_draft.
• { ok: true, data: { configured: false } } or verified: false: fall through to the chat prompt below.

Ask the user directly:

"Paste your LinkdAPI key and I'll store it in ~/.talent-scout/.env (chmod 600). The key will appear in the transcript — delete the message after if you'd like. Get one at linkdapi.com/dashboard if you don't have it."

Dispatch on their reply:

• Key pasted: call configure_api_key with { key: "<pasted-key>" }.
  • verified: true → announce preview, advance to thesis_draft.
  • verified: false / INVALID_KEY → say so, ask again.
  • Other error → surface and ask again.
• "cancel" / "skip": halt with "No key set. Rerun /talent-scout:init when you're ready."
• "I'll set it manually": halt with "Got it — set LINKDAPI_KEY in ~/.talent-scout/.env (chmod 600) and rerun /talent-scout:init."

The key file is written by configure_api_key. No other disk writes happen in this state.

State 3: thesis_draft

Tell the user, then invoke the ts-interview skill:

"Next I'll hand off to the thesis interview — it captures who you're looking for in enough detail that the scout agent can run without further input. Accept the cyber defaults as-is, or walk through the 10 questions to tailor them."

Invoke ts-interview with a hint that this is the init entry point. The interview runs its flow (accept-all or walk-through), previews the drafted thesis.md and profile.json, and returns control to init with the drafted artifacts without writing them. Init remains the single write-site.

Init expects back: thesis_md (string), profile_json (object), and a dry-run triage summary for display in the summary.

If the user aborts, halt with "Setup cancelled. No files written. Rerun /talent-scout:init when you're ready."

State 4: summary

Display the pending configuration:

Setup Summary
─────────────
API key:       [verified preview]
Thesis:        [one-line derived from thesis_md]
Triage filters:
  - required_domain_keywords: [first few]
  - auto_skip_roles:          [count]
  - geo:                      [countries / require_match]
Display dimensions: [names derived from profile_json]

Prompt: "Confirm to write this to disk, or say 'go back to thesis' to revise."

Do NOT call `bootstrap_data_dir` until the user explicitly confirms. "go" / "yes" / "looks good" are approvals; silence is not.

State 5: write

On explicit approval:

1. Call bootstrap_data_dir with { thesis_md, profile_json, reinit_mode } where reinit_mode is "fresh", "reconfigure", or omitted for first-time setup. The tool writes config/thesis.md, config/profile.json, and scaffolds data/ atomically.
2. If the tool returns an error, surface it and offer retry — the drafted artifacts are held in working memory, so re-invoke without re-prompting.
3. On success, run the doctor skill and render its output as the completion message.
4. Final line: "Setup complete. Say `start scouting` to start your first scouting session."

---

Transaction boundary

Nothing is persisted before the summary-confirm step, with one exception: the API key file (written by configure_api_key in State 2 so we can verify it before moving on).

• Thesis and profile drafts live in working memory until bootstrap_data_dir runs in State 5.
• Aborting at summary = no config files, no data directory, no git init. A partial install leaves a verified key and nothing else.
• bootstrap_data_dir writes atomically (tmp → rename); a crash mid-write leaves the directory prior-consistent.

---

Reinit path

Before welcome, call read_thesis to detect an existing ~/.talent-scout/config/thesis.md. If found, ask:

"Talent-scout is already set up. Want to keep the current config, reconfigure (re-run the interview, keep candidates), or fresh init (archive current data to a timestamped backup and start over)?"

• keep → exit with "No changes. Say `start scouting` when you're ready."
• reconfigure → skip key if already verified, run thesis_draft, pass reinit_mode: "reconfigure" to bootstrap_data_dir (meta files preserved).
• fresh init → run the full wizard, pass reinit_mode: "fresh" — the tool archives the old data/ before scaffolding.

Legacy migration

If read_thesis reports no thesis but legacy config exists (detect via read_meta for a pre-redesign marker like "rubric.json"), inform the user their old setup will be migrated (nothing deleted, old config preserved for reference), then call migrate_legacy (Task 25) to seed the interview defaults and enter thesis_draft. If migrate_legacy is not yet available, fall back to thesis_draft with the seed defaults and note manual review in the summary.

---

Error paths

• Key verification fails: stay in key, re-prompt. Do not advance.
• ts-interview aborted or errors out: halt cleanly, no writes. The key file (if created) survives.
• bootstrap_data_dir error on write: surface the error, keep the drafted artifacts in memory, offer a retry. If the error is a reinit-mode mismatch (Config already exists), prompt for reconfigure vs fresh and retry.
• User pastes a LinkedIn URL mid-wizard: acknowledge and note that seed profiles are captured by ts-interview in its hunting-grounds question — steer them there.