FN-5813: update fn onboard help and CLI docs

Align onboarding HELP text and CLI reference with current fn onboarding behavior.

- Document onboarding auto-launch conditions around missing central DB and interactive command flow.
- Add and clarify onboarding escape hatches: --skip-onboarding and FUSION_SKIP_ONBOARDING.
- Add an onboard docs parity test to keep HELP and docs aligned for key onboarding terms.
- Add a patch changeset for @runfusion/fusion describing the documentation/help update.

Files changed:
 .changeset/fn-5813-onboard-docs.md                 |  5 ++++
 docs/cli-reference.md                              | 21 +++++++++-----
 packages/cli/src/bin.ts                            |  4 ++-
 packages/cli/src/commands/__tests__/onboard-docs.test.ts    | 33 ++++++++++++++++++++++
 4 files changed, 55 insertions(+), 8 deletions(-)

Fusion-Task-Id: FN-5813

Fusion-Task-Lineage: 14a74ad9-5f09-471a-878d-aa120a28ef41

.changeset/fn-5813-onboard-docs.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Update `fn onboard` CLI HELP text and CLI reference docs to match shipped onboarding behavior, including auto-launch conditions, skip paths, and onboarding escape hatches (`--skip-onboarding`, `FUSION_SKIP_ONBOARDING`).

docs/cli-reference.md

@@ -58,20 +58,27 @@ the onboarding flow.
 ```bash
 fn onboard
 fn onboard --force
+fn --skip-onboarding dashboard
+FUSION_SKIP_ONBOARDING=1 fn dashboard
 ```
 
 | Option | Description |
 |---|---|
 | `--force` | Re-run onboarding even when `cliOnboardingCompletedAt` is already set. |
+| `--skip-onboarding` | Global escape hatch that bypasses onboarding auto-launch for this invocation. |
+| `FUSION_SKIP_ONBOARDING` | Environment-variable escape hatch (`1`, `true`, `yes`, or `on`) that bypasses onboarding auto-launch. |
 
-The command is safe to re-run and only updates the settings you confirm during
+On successful completion, Fusion records `cliOnboardingCompletedAt` in global
-prompts.
+settings.
 
-Backward compatibility guarantee: onboarding auto-launch never interrupts
+Auto-launch behavior: before interactive commands, Fusion auto-launches onboarding
-existing setups and never blocks headless usage. It is skipped when both the
+only when the central DB at `getDefaultCentralDbPath()` is missing. Auto-launch
-central DB and local project DB already exist, and it never prompts in non-TTY,
+is skipped for `serve`, `daemon`, non-TTY runs, `--skip-onboarding`, and
-`serve`, `daemon`, `--skip-onboarding`, `FUSION_SKIP_ONBOARDING`, piped, or
+`FUSION_SKIP_ONBOARDING`.
-agent-run invocations.
+
+Backward-compatibility guard: existing setups are never blocked — when central DB
+already exists (including the central-DB + registered-project case), onboarding
+does not auto-launch.
 
 ---
 

packages/cli/src/bin.ts

@@ -256,7 +256,9 @@ fn — AI-orchestrated task board
 Usage:
   fn                                  Launch the dashboard (same as fn dashboard)
   fn init [opts]                      Initialize a new fn project (--name, --path, --git)
-  fn onboard [--force]                Run the interactive onboarding wizard
+  fn onboard [--force] [--skip-onboarding]
+                                      Run onboarding on demand; auto-launch runs before interactive commands when central DB is missing,
+                                      and auto-skips for serve/daemon, non-TTY, --skip-onboarding, and FUSION_SKIP_ONBOARDING
   fn dashboard                        Start the board web UI
   fn dashboard --paused               Start with automation paused
   fn dashboard --dev                  Start web UI only (no AI engine)

packages/cli/src/commands/__tests__/onboard-docs.test.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const binSource = readFileSync(resolve(__dirname, "../../bin.ts"), "utf8");
+const cliReference = readFileSync(resolve(__dirname, "../../../../../docs/cli-reference.md"), "utf8");
+
+function extractOnboardSection(markdown: string): string {
+  const start = markdown.indexOf("## `fn onboard`");
+  const end = markdown.indexOf("---", start);
+  return start >= 0 ? markdown.slice(start, end >= 0 ? end : undefined) : "";
+}
+
+describe("onboard help/docs parity", () => {
+  it("always documents fn onboard and --force in both HELP and CLI reference", () => {
+    const onboardDocs = extractOnboardSection(cliReference);
+
+    expect(binSource).toContain("fn onboard");
+    expect(onboardDocs).toContain("fn onboard");
+
+    expect(binSource).toContain("--force");
+    expect(onboardDocs).toContain("--force");
+  });
+
+  it("keeps conditional onboarding escape hatches in parity between HELP and docs", () => {
+    const onboardDocs = extractOnboardSection(cliReference);
+    const parityTerms = ["--skip-onboarding", "FUSION_SKIP_ONBOARDING"];
+
+    for (const term of parityTerms) {
+      expect(binSource.includes(term)).toBe(onboardDocs.includes(term));
+    }
+  });
+});