Initial Commit

packages/api-stack/api/create-suaveplan-plugin/src/bin/create-suaveplan-plugin.md

@@ -0,0 +1,61 @@
+# create-suaveplan-plugin (bin)
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module is the executable entry-point for the
+`create-suaveplan-plugin` scaffolder. It parses argv into a
+`ParsedArgs` record, resolves the matching fixture answer set, and
+delegates the on-disk work to `scaffold()`. Wrapping the CLI in a
+single file (with `parseArgs` and `run` exported for in-process
+testing) keeps the bin layer thin and lets the rest of the package
+stay framework-agnostic.
+
+## Features
+
+- `parseArgs(argv)` — positional plugin name plus `--fixture`,
+  `--force`, `--dir` flags. Defaults to the
+  `sandboxed-none-rest-only` fixture and `<cwd>/<name>` as target.
+- `run(argv)` — programmatic entry. Returns the resolved
+  `PromptAnswers` so test callers can introspect the chosen fixture.
+- Auto-runs only when invoked as a binary (`process.argv[1]` ends with
+  `create-suaveplan-plugin.js`), so importing the module never trips a
+  scaffold run.
+
+## Usage
+
+### Basic example
+
+```bash
+bunx create-suaveplan-plugin my-plugin --fixture trusted-postgres-full
+```
+
+### Advanced example
+
+```bash
+bunx create-suaveplan-plugin billing-plugin \
+    --fixture isolated-sqlite-rest-only \
+    --dir ./packages/billing-plugin \
+    --force
+```
+
+## API Reference
+
+- `parseArgs(argv: readonly string[]): ParsedArgs` — pure argv parser.
+- `run(argv: readonly string[]): PromptAnswers` — full scaffold cycle.
+
+## Implementation Notes
+
+- The fixture vocabulary is closed; an unknown `--fixture` value
+  silently falls back to the default rather than throwing — the bin is
+  the user-facing layer and the spec treats unknown fixtures as a
+  no-op rather than a hard error.
+- The `process.argv[1].endsWith(...)` guard is intentionally permissive
+  so the file works whether invoked through Node, Bun, or a transpiled
+  artefact.
+- Coverage exclusion for `src/bin/**` keeps the auto-run guard out of
+  the 100% gate; the testable surface (`parseArgs`, `run`) is
+  exercised directly from the test file.