docs: tell quickstart readers the setup wizard exists

cli/commands/init/interactive-wizard.test.ts

@@ -4,10 +4,16 @@ import "#veryfront/schemas/_test-setup.ts";
  * @module cli/commands/init/interactive-wizard.test
  */
 
-import { assertEquals } from "#veryfront/testing/assert.ts";
+import { assertEquals, assertExists, assertStringIncludes } from "#veryfront/testing/assert.ts";
 import { describe, it } from "#veryfront/testing/bdd.ts";
 import { formatWizardIntro, SETUP_COPY, shouldRunWizard } from "./interactive-wizard.ts";
 
+const GETTING_STARTED_DIR = new URL("../../../docs/getting-started/", import.meta.url);
+
+function readGettingStartedDoc(name: string): Promise<string> {
+  return Deno.readTextFile(new URL(name, GETTING_STARTED_DIR));
+}
+
 describe("interactive-wizard", () => {
   it("starts directly with the setup task", () => {
     assertEquals(formatWizardIntro(), "\nLet's set up your project.");
@@ -38,6 +44,29 @@ describe("interactive-wizard", () => {
     });
   });
 
+  describe("getting-started docs match wizard behaviour", () => {
+    it("keeps the quickstart create command out of the wizard", async () => {
+      const quickstart = await readGettingStartedDoc("quickstart.md");
+      const createCommand = quickstart
+        .split("\n")
+        .find((line) => line.includes("create veryfront"));
+      assertExists(createCommand, "quickstart.md must show a create command");
+
+      // shouldRunWizard() is the gate. Without --template the documented command
+      // opens a blocking template/runtime/git wizard in a real terminal, which
+      // the quickstart presents as a single automatic step.
+      const template = /--template\s+([a-z0-9-]+)/.exec(createCommand)?.[1];
+      assertEquals(shouldRunWizard({ template }), false);
+    });
+
+    it("names every wizard prompt on the create-project page", async () => {
+      const createProject = await readGettingStartedDoc("create-project.md");
+      for (const prompt of [SETUP_COPY.template, SETUP_COPY.runtime, SETUP_COPY.git]) {
+        assertStringIncludes(createProject, prompt);
+      }
+    });
+  });
+
   describe("runInteractiveWizard (non-TTY skipped path)", () => {
     it("returns runtime: 'node' by default when not interactive", async () => {
       const { runInteractiveWizard } = await import("./interactive-wizard.ts");

docs/getting-started/create-project.md

@@ -18,9 +18,21 @@ veryfront init test-app
 cd test-app
 ```
 
-The wizard preselects the `ai-agent` template. Choose another template when you
-want a different starting point. In non-interactive environments, `ai-agent` is
-used automatically.
+The wizard asks three questions in order and waits for an answer on each:
+
+```text
+Choose a starter template:   preselects ai-agent
+Select runtime:              preselects Node.js
+Initialize Git?              preselects Yes
+```
+
+Press Enter three times to accept the preselected answers, or use the arrow keys
+to change an answer first.
+
+The wizard needs a terminal. In non-interactive environments (CI, piped stdin,
+scripts), `veryfront init` skips every prompt and uses `ai-agent` on Node.js
+without initializing Git. Passing `--template` also skips the whole wizard,
+including the runtime and Git questions.
 
 Choose a starting point directly when you already know what you want to build,
 or when running the command from a non-interactive script:

docs/getting-started/quickstart.md

@@ -14,12 +14,17 @@ globally, run them with `npx veryfront@latest ...`.
 ## Create the app
 
 ```bash
-npm create veryfront@latest support-agent
+npm create veryfront@latest support-agent -- --template ai-agent
 cd support-agent
 ```
 
-The `ai-agent` starter is the default. Pass `-- --template <template>` when you
-want a different starting point.
+Passing `-- --template <template>` scaffolds straight away and is what the rest
+of this page assumes. Omit it and the command opens an interactive setup wizard
+that waits for three answers (starter template, runtime, and whether to
+initialize Git) before it writes anything. See
+[Create project](./create-project.md) for the wizard. The wizard only appears in
+a terminal; in CI, scripts, and other non-interactive shells the command falls
+back to `ai-agent` on Node.js without Git.
 
 The `ai-agent` template creates a runnable chat app: