[first-success] Make public scaffold commands execute the documented journey

[kang-heewon]

Priority

P1

Problem

Croco's public scaffold commands and getting-started narrative do not describe an executable, internally consistent first-success journey.

The package README publishes a command with unsupported options, while the getting-started guide generates a GraphQL ddd-api project and immediately teaches a REST controller at a different URL. The existing verifier passes because it duplicates an older subset of CLI choices and does not inspect the package README or execute the real option normalizer.

Evidence

• packages/create-croco-app/README.md:18 documents:
  pnpm create croco-app my-service --preset saas-api --package-manager pnpm --json
• saas-api is a supported --goal, not a preset; --package-manager is not a CLI option; and JSON/noninteractive generation requires --scope.
• packages/create-croco-app/src/cli.ts:23-55 exposes the actual goal, preset, scope, stack, no-install/no-git, and JSON flags.
• packages/create-croco-app/src/cli.ts:74-78 explicitly requires directory, scope, and goal or preset for JSON output.
• packages/docs/src/content/docs/en/guides/getting-started.mdx:31-43 generates a GraphQL Lambda app and then claims http://localhost:3000/api; the guide proceeds with REST controller examples even though the generated standalone GraphQL app uses the GraphQL runtime/port contract.
• scripts/first-success-verify.mts:90-96 hard-codes a partial preset/flag choice table and has no --goal contract.
• scripts/first-success-verify.mts:1000-1015 validates the root README, docs landing page, and getting-started guide, but not packages/create-croco-app/README.md.

Desired outcome

One canonical public scaffold command generates the app that the getting-started guide actually runs and extends, and drift is caught by executing the real CLI contract rather than a parallel handwritten parser.

Proposed implementation

1. Select --goal saas-api as the canonical SaaS first-success path, or change the guide's claims to exactly match another currently supported generated artifact.
2. Align the root/docs/package README command, generated runtime, local URL, protocol examples, and success state around that single path.
3. Include required --scope and deterministic --no-install --no-git flags where the docs instruct manual installation.
4. Replace duplicated option/choice validation in first-success-verify.mts with imports from the real CLI goal/option definitions where possible.
5. Add packages/create-croco-app/README.md to public command verification.
6. Validate every documented scaffold command through real CLI normalization and a temporary no-install generation.
7. Add one packed generated-app smoke for the canonical command that proves install, typecheck/build, and the documented success endpoint or scenario.

Acceptance criteria

• Every public scaffold command parses through the current CLI and generates successfully.
• No public command uses an unsupported flag or treats a goal as a preset.
• The getting-started guide's protocol, port/URL, generated files, and code examples match its scaffold output.
• The canonical generated app reaches the documented success state without manual package or source fixes.
• Adding/removing a supported goal, preset, or flag cannot leave the verifier's choice table stale.
• The package README is part of the first-success contract.
• Tests fail when a documented command is syntactically valid but generates a different journey than the prose claims.

Validation

• pnpm first-success:verify
• pnpm exec vitest run scripts/tests/first-success-verify.spec.ts --config vitest.config.ts
• pnpm --filter create-croco-app test
• pnpm create-croco-app:smoke
• Packed smoke of the exact canonical public command and documented success endpoint/scenario.

Scope boundaries

Do not broaden this into a rewrite of every preset guide. The target is one truthful canonical first-success loop plus a reusable guard that keeps all public scaffold commands executable.

[kang-heewon]

작업을 시작했습니다. 공개 scaffold 명령을 실제 CLI 정규화·생성과 연결하고, getting-started 문서와 canonical 생성 앱의 실행 경로를 일치시키며 packed smoke로 그 성공 상태를 검증하겠습니다.