docs(onboard): document FSM migration target

[cv]

Summary

Document the target architecture for finishing the onboarding FSM migration. The new machine README clarifies state ownership, runtime responsibilities, event semantics, and the remaining stages needed to make the FSM the primary onboarding control plane.

Changes

• Add src/lib/onboard/machine/README.md with the intended runOnboardMachine(context) architecture.
• Document the distinction between persisted session steps and machine state.
• Capture handler, runtime, event, and migration-stage expectations for the remaining stack.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation for the onboarding system's state machine architecture, including state definitions, handler contracts, runtime responsibilities, and migration guidelines.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: dec15bbe-c09a-454f-aabd-548926d06f86

📥 Commits

Reviewing files that changed from the base of the PR and between c4e3f0d and 6b753bf.

📒 Files selected for processing (1)

• src/lib/onboard/machine/README.md

---

📝 Walkthrough

Walkthrough

This PR adds a new README file documenting the target architecture for the onboarding finite-state machine layer. The specification defines the expected design for refactoring src/lib/onboard.ts into a thin entrypoint, describes state ownership contracts between session steps and FSM state, outlines handler and runtime responsibilities, and lists migration completion criteria.

Changes

Onboarding FSM Architecture Documentation

Layer / File(s)	Summary
FSM architecture specification and handler contract src/lib/onboard/machine/README.md	Documents the target runner architecture, state-vs-step vocabulary, handler contract rules (validation, repairs, side effects, explicit results, secret safety), OnboardRuntime responsibilities (transition validation, safe context updates, terminal handling, redacted event emission), event payload semantics for JSONL safety, and migration completion checklist.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested reviewers

• ericksoa
• sandl99

Poem

🐰 A roadmap etched in careful prose,
The FSM path that onboarding goes,
State contracts carved and handlers clear—
The architecture we build starts here! 📋✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding documentation for the FSM migration target architecture in the onboarding system.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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
• Commit unit tests in branch stack/onboard-fsm-doc

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. Documentation-only change under src/lib/onboard/machine. It cannot affect runtime behavior or real assistant user flows, so no E2E jobs are needed.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario workflow, scenario metadata, scenario runtime, or validation-suite files changed.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[cjagwani]

lgtm. clean architectural target doc for the FSM migration — clarifies state ownership, runtime authority over transitions, event payload redaction rules, and the six-stage completion definition. pure docs, no risk, aligns with the runtime/handler split already in progress.

dismissed — posted without maintainer authorization

[cjagwani]

approving per content audit above — verified state vocab + OnboardRuntime contract match implementation, CI green, docs accurate.