create-grist-widget 0.3.6 → 0.3.9

package/README.md

@@ -6,13 +6,82 @@ Scaffold a new [Grist](https://www.getgrist.com/) custom widget, preconfigured w
 ```bash
 npm create grist-widget my-widget
 cd my-widget
-pnpm install
 pnpm dev
 ```
 
-The template ships embedded in this package — nothing is fetched from GitHub at
-scaffold time. See [Getting started](https://gristwidgets.com/docs/sdk/guide/getting-started)
-for the full walkthrough (dev loop, deploying, embedding in Grist).
+The template — plus every starting example and the logic that composes them — ships
+embedded in this package. Nothing is fetched from GitHub or npm at scaffold time; the SDK
+install right after is the only network access any of these commands make. See
+[Getting started](https://gristwidgets.com/docs/sdk/guide/getting-started) for the full
+walkthrough (dev loop, deploying, embedding in Grist).
+
+By default the scaffold starts blank (a two-field editor) and installs its own
+dependencies automatically, detecting whichever package manager you invoked this with. Add
+`--example <id>` to start from a real widget instead — `create-grist-widget list` shows
+what's available — or just run `npm create grist-widget` with no name for an interactive
+prompt that asks for both.
+
+## The four commands
+
+| Command | What it does |
+| --- | --- |
+| `create <name> [--example <id>]` | Scaffold a new widget into `./<name>` (the command above, or run explicitly) |
+| `init [--example <id>]` | Scaffold into the **current** directory instead of a new one — for an already-cloned or agent-initialized repo |
+| `use <example-id>` | Swap the current project's widget for a different example |
+| `list [--json]` | Print the available starting examples |
+
+Common flags for `create`/`init`: `--yes` skips interactive prompts and uses
+flags/defaults only; `--no-install` skips the automatic dependency install;
+`--pm <name>` picks a specific package manager instead of auto-detecting one.
+`init` additionally takes `--name <name>` (default: the current directory's
+name) and `--force` (overwrite files that already exist and differ from the
+template — see below).
+
+### `init` — starting from an already-initialized directory
+
+`create` refuses a non-empty target directory; `init` is the fix for the case that comes
+up constantly with cloud coding agents, which typically start from an already-cloned or
+already-`git init`'d repo rather than an empty one:
+
+```bash
+mkdir my-widget && cd my-widget
+git init   # or: this is already a fresh GitHub Pages / template clone
+npx create-grist-widget init --example form-edit
+```
+
+Files that already exist and are identical to the template are left untouched; the four
+identity-bearing files (`package.json`, `README.md`, `index.html`, `src/App.tsx`) get the
+usual name/title substitution even if present. Anything else that already exists **and**
+differs from the template's own copy stops the run with a list of the conflicting paths —
+pass `--force` to overwrite anyway. If `.git` already exists, `init` never auto-commits;
+review and commit the result yourself. If it doesn't, `init` sets up `main` + `dev` and an
+initial commit exactly like `create` does.
+
+### `use` — swapping to a different example later
+
+Changed your mind about which example to start from, or want to compare two? `use` swaps
+`src/App.tsx` (and any example-specific files) for a different one, in place:
+
+```bash
+create-grist-widget use task-board
+```
+
+It only ever touches `src/**` — never `main.tsx`, `vite.config.ts`, or the deploy
+workflow — and it requires a clean git working tree first (`git status --porcelain`
+empty), so the swap is always a single reviewable, revertible diff. Commit or stash first
+if you have uncommitted changes; `use` refuses to run otherwise.
+
+### `list` — what's available
+
+```bash
+create-grist-widget list          # id / title / description, one per line
+create-grist-widget list --json   # the same, as JSON
+```
+
+> **Note:** `create`, `init`, `use`, and `list` are themselves valid widget names — a bare
+> `create-grist-widget list` runs the `list` command, not "scaffold a widget named list."
+> Use the explicit form (`create-grist-widget create list`) for a widget with one of these
+> names.
 
 ## Using Claude Code?
 
@@ -80,9 +149,12 @@ simplest way to get from zero to a deployed widget:
 
    > ⚠️ **Merging without a version bump publishes nothing.** The release
    > build skips whenever the version already has a published `v<version>/`
-   > directory, which is always true if you forgot to bump it. The PR merges
-   > cleanly and CI runs "successfully," but `/latest/` doesn't change. Bump
-   > the version *before* merging.
+   > directory, which is always true if you forgot to bump it. Bump the
+   > version *before* merging. After your first release, the deploy workflow
+   > catches the common case of this and fails the run loudly instead of
+   > silently reporting success — but only when it can tell the previous
+   > commit had the exact same version; it's a backstop, not a substitute
+   > for bumping it yourself.
 
    Keep committing to the same `dev` branch afterward — it's the permanent
    working/preview branch, not a one-off branch to delete per change.