feat(cli): `dirctl init` — interactive onboarding wizard for a new environment

[akijakya]

dirctl init is the guided first-run experience for a new user — an interactive, multi-step wizard (in the spirit of create-react-app / create-next-app) that walks through setting up the local environment to work with this Directory. It is not a thin mirror of dirctl install: it orchestrates several setup concerns, of which installing the DIR MCP server + skills is only one, and presents each as an explained, skippable step.

UX: a step-per-concern wizard

Each step explains what it does in plain language and lets the user opt in/out and configure it. Background work (e.g. agent detection) runs while the user reads, so the options are ready by the time they reach the step.

Step 1 — Directory MCP server & skills

• Explain what the DIR MCP server (a dirctl mcp serve entry pointed at the active dirctl context) and the DIR skills (feat: split DIR Agent Skill into installation/discovery/export skills under /skills #1704) are, and why an agent would want them.
• Let the user skip this entirely, or choose which artifacts to install (MCP server, skills, or both).
• Agent selection: detection runs in the background; the detected agents are listed as toggleable options (pre-selected), so the user picks which detected agents to install into.
• Under the hood this reuses the shared placement engine cli/internal/agentcfg (built for dirctl install, feat(cli): dirctl install — install record artifacts into AI coding agent configs #1737) — same per-agent paths, JSON/YAML/TOML codec, managed-block merge, atomic writes. The wizard is only the front-end; the placement machinery is shared. Content here is Directory-provided (a context-injected MCP entry + embedded skills), with no Directory round-trip.

Step 2 — OASF taxonomy extractor

• Explain what the extractor package is for (LLM-free record enrichment and future free-text search; see epic Epic: OASF taxonomy extractor for LLM-free enrichment and free-text search oasf-sdk#172).
• Ask whether it's OK to download and provision the assets (the ~89 MB sentence-transformer model + the OASF taxonomy).
• Let the user choose the OASF URL to pull the taxonomy from, showing the default (the configured/official OASF endpoint) as the pre-filled option.
• Implementation of the actual provisioning + warm daemon is tracked in feat(cli): provision the OASF extractor assets in dirctl init #1743.

Further steps can be added as init grows (e.g. context/auth setup), each following the same explain → opt-in → configure pattern.

Notes

• Reuses cli/internal/agentcfg for the MCP/skills step — no duplicated placement logic. The feat/dirctl-integrate prototype's placement logic was extracted into that package as part of feat(cli): dirctl install — install record artifacts into AI coding agent configs #1737; there is no separate dirctl integrate command.
• Surgical & idempotent: re-running init detects what is already present and only adds/updates what is missing or changed; all other config is preserved; writes are atomic.

Open questions

• Non-interactive mode for CI/automation (e.g. a --yes plus per-step flags to drive the wizard headlessly) — needed, and what does that flag surface look like?
• Undo: does init offer a way to reverse what it set up, or is removal deferred to other commands?
• TUI approach: which interactive prompt/TUI library, and how to fall back gracefully when stdin is not a TTY.

Acceptance criteria

• dirctl init launches an interactive wizard that, step by step, explains and lets the user opt into (1) installing the DIR MCP server/skills into selected detected agents, and (2) provisioning the extractor with a chosen OASF URL.
• Agent detection runs in the background; detected agents appear as toggleable, pre-selected options.
• The MCP/skills step reuses cli/internal/agentcfg (no duplicated placement logic).
• Each step is skippable; skipping leaves the corresponding configuration untouched.

Dependencies

• Depends on feat: split DIR Agent Skill into installation/discovery/export skills under /skills #1704 (the DIR skills).
• Builds on the shared placement engine from feat(cli): dirctl install — install record artifacts into AI coding agent configs #1737 (dirctl install, implemented).
• Extractor step provisioning: feat(cli): provision the OASF extractor assets in dirctl init #1743 (epic: Epic: OASF taxonomy extractor for LLM-free enrichment and free-text search oasf-sdk#172).

[ramizpolic]

Can we usedir init instead? dir integrate just sounds a bit verbose