docs: refresh README versions and add non-interactive flow demos (#487)

Address the v0.21.0 README follow-ups from the roadmap.

- #454: refresh the shell snippet and benchmark caption to the current
  release, correct the "not supported" list for v0.21.0 (DDL runs
  in-memory; transaction control, VACUUM, ATTACH/DETACH, and DCL are
  rejected), and add a Go test that fails when a README "sqly vX.Y.Z"
  string drifts from the latest CHANGELOG version.
- #455: add VHS demos and examples for --inspect (including
  --inspect-sample 0 for a schema-only report), --stdin combined with
  --sql-file (via the committed doc/vhs/join.sql), and the write-back
  safety boundaries (--save requires --force; a schema change is
  rejected up front). The new example commands are exercised end-to-end
  by the shellspec suite.

Closes #454
Closes #455

Author: nao1215

CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## [Unreleased]
+
+### Documentation
+* README Version Refresh: Refresh the shell snippet and benchmark caption to the current release, correct the "not supported" list for v0.21.0 (DDL runs in-memory; transaction control, VACUUM, ATTACH/DETACH, and DCL are rejected), and add a Go test that fails when a README `sqly vX.Y.Z` string drifts from the latest CHANGELOG version (#454).
+* README Demos For Non-Interactive Flows: Add VHS demos and examples for `--inspect` (including `--inspect-sample 0` for a schema-only report), `--stdin` combined with `--sql-file`, and the write-back safety boundaries (`--save` requires `--force`; a schema change is rejected up front). The new example commands are exercised end-to-end by the shellspec suite (#455).
+
 ## [v0.21.0](https://github.com/nao1215/sqly/compare/v0.20.0...v0.21.0) (2026-06-01)
 
 ### Breaking Changes

README.md

@@ -97,7 +97,7 @@ Run `sqly` without `--sql` to open the shell. It behaves like `sqlite3` or `mysq
 
 ```shell
 $ sqly testdata/user.csv
-sqly v0.19.0
+sqly v0.21.0
 
 enter "SQL query" or "sqly command that begins with a dot".
 .help print usage, .exit exit sqly.
@@ -206,11 +206,13 @@ $ printf '.tables\nSELECT COUNT(*) FROM user\n' | sqly testdata/user.csv
 
 `--sql-file PATH` runs SQL read from a file (multiple `;`-separated statements allowed). It cannot be combined with `--sql`. Because the query comes from a file, stdin stays free for a dataset:
 
+![sql-file demo](./doc/img/sql-file-demo.gif)
+
 ```shell
-$ cat testdata/user.csv | sqly --stdin csv --sql-file join.sql testdata/identifier.csv
+$ cat testdata/user.csv | sqly --stdin csv --sql-file doc/vhs/join.sql testdata/identifier.csv
 ```
 
-where `join.sql` holds:
+where `doc/vhs/join.sql` holds:
 
 ```sql
 SELECT s.user_name, i.position
@@ -223,6 +225,8 @@ ORDER BY s.identifier;
 
 `--inspect` imports the inputs, prints a JSON report of every table (name, source, columns, row count, sample rows), and exits without the shell. It is the non-interactive equivalent of `.tables` + `.schema` + `.describe`, useful for scripts and LLMs. Import progress goes to stderr, so stdout is JSON only. `--inspect-sample N` sets the sample size (default 5; `0` for schema only).
 
+![inspect demo](./doc/img/inspect-demo.gif)
+
 ```shell
 $ sqly --inspect --inspect-sample 1 testdata/identifier.csv
 {
@@ -243,6 +247,12 @@ $ sqly --inspect --inspect-sample 1 testdata/identifier.csv
 }
 ```
 
+Use `--inspect-sample 0` for a schema-only report (no `sample_rows`), so a script can read column types without pulling any data:
+
+```shell
+$ sqly --inspect --inspect-sample 0 testdata/identifier.csv
+```
+
 ## Inspect schema: .schema and .describe
 
 ```shell
@@ -271,6 +281,17 @@ $ sqly --sql "UPDATE user SET first_name = 'Rachelle' WHERE identifier = 1" --sa
 $ sqly --sql "DELETE FROM user WHERE identifier > 100" --save --force testdata/user.csv
 ```
 
+Write-back is deliberately strict about what it will touch. `--save` refuses to run without `--force`, and a run whose SQL changes schema (DDL such as `CREATE TABLE ... AS SELECT`) is rejected up front, before any output is written, since only row changes map back to a file:
+
+![write-back safety demo](./doc/img/writeback-demo.gif)
+
+```shell
+$ sqly --sql "UPDATE user SET identifier = identifier + 100" --save testdata/user.csv
+--save overwrites source files; pass --force to confirm, or use --save-dir DIR to write elsewhere
+$ sqly --sql "CREATE TABLE backup AS SELECT * FROM user" --save-dir ./out testdata/user.csv
+--save/--save-dir cannot persist "CREATE TABLE backup AS SELECT * FROM user": ... only INSERT/UPDATE/DELETE on imported tables are saved
+```
+
 Only tables mapping one-to-one to a single CSV, TSV, LTSV, or Parquet source can be written. Tables created by SQL, directory imports, and multi-table sources (Excel, ACH, Fedwire) are rejected with a clear error before anything is written.
 
 ## Directory import
@@ -379,7 +400,7 @@ SELECT * FROM `customers100000` WHERE `Index` BETWEEN 1000 AND 2000 ORDER BY `In
 |--------:|--------:|------------:|--------------:|-------------------:|
 | 100,000 | 12 | 515 ms | 161 MB | 2.82M |
 
-Measured on an AMD Ryzen 7 5800U, Go 1.25, sqly v0.19.0. Run `make bench` to reproduce on your machine.
+Measured on an AMD Ryzen 7 5800U, Go 1.25, sqly v0.21.0. Run `make bench` to reproduce on your machine.
 
 ## Comparison with similar tools
 
@@ -406,9 +427,13 @@ sqly stays in the same sub-second range as the CSV-focused tools while reading t
 
 ## Limitations (not supported)
 
-- DDL such as CREATE
-- DML such as GRANT
-- TCL such as transactions
+sqly runs each statement in its own transaction on an in-memory database, so a few SQLite statements are rejected with a clear error rather than failing in confusing ways:
+
+- Explicit transaction control: `BEGIN`, `COMMIT`, `ROLLBACK`, `SAVEPOINT`, `RELEASE`
+- `VACUUM` / `VACUUM INTO`, and `ATTACH` / `DETACH DATABASE`
+- DCL such as `GRANT` / `REVOKE`
+
+DDL (`CREATE`, `DROP`, `ALTER`, ...) runs against the in-memory tables, but a non-interactive `--save`/`--save-dir` run rejects a schema change up front, since only `INSERT`/`UPDATE`/`DELETE` on an imported table can be written back to a file.
 
 ## Contributing
 

doc/img/inspect-demo.gif

@@ -0,0 +1,20 @@
+# --inspect demo: machine-readable JSON report, with and without sample rows.
+# Regenerate with: vhs doc/vhs/inspect.tape  (run from the repository root)
+Output "doc/img/inspect-demo.gif"
+Set Shell "bash"
+Set FontSize 16
+Set Width 1100
+Set Height 560
+Set Padding 18
+Hide
+Type "export PATH=$PWD:$PATH PS1='$ '; clear"
+Enter
+Show
+Type "sqly --inspect --inspect-sample 1 testdata/identifier.csv"
+Sleep 600ms
+Enter
+Sleep 3s
+Type "sqly --inspect --inspect-sample 0 testdata/identifier.csv"
+Sleep 600ms
+Enter
+Sleep 3s

doc/img/sql-file-demo.gif

@@ -0,0 +1,6 @@
+-- Join a piped --stdin dataset (table "stdin") with a file argument.
+-- Run with: cat user.csv | sqly --stdin csv --sql-file doc/vhs/join.sql identifier.csv
+SELECT s.user_name, i.position
+FROM stdin s
+JOIN identifier i ON s.identifier = i.id
+ORDER BY s.identifier;

doc/img/writeback-demo.gif

@@ -0,0 +1,16 @@
+# --stdin + --sql-file demo: piped dataset queried by a script read from a file.
+# Regenerate with: vhs doc/vhs/sql_file.tape  (run from the repository root)
+Output "doc/img/sql-file-demo.gif"
+Set Shell "bash"
+Set FontSize 16
+Set Width 1100
+Set Height 320
+Set Padding 18
+Hide
+Type "export PATH=$PWD:$PATH PS1='$ '; clear"
+Enter
+Show
+Type "cat testdata/user.csv | sqly --stdin csv --sql-file doc/vhs/join.sql testdata/identifier.csv"
+Sleep 600ms
+Enter
+Sleep 3s

doc/vhs/inspect.tape

@@ -0,0 +1,29 @@
+# Write-back safety demo: --save needs --force, schema changes are rejected,
+# and --save --force overwrites the source in place.
+# Regenerate with: vhs doc/vhs/writeback.tape  (run from the repository root)
+Output "doc/img/writeback-demo.gif"
+Set Shell "bash"
+Set FontSize 16
+Set Width 1180
+Set Height 460
+Set Padding 18
+Hide
+Type "WORK=$(mktemp -d); cp testdata/user.csv $WORK/; export PATH=$PWD:$PATH; cd $WORK; export PS1='$ '; clear"
+Enter
+Show
+Type "sqly --sql 'UPDATE user SET identifier = identifier + 100' --save user.csv"
+Sleep 600ms
+Enter
+Sleep 2500ms
+Type "sqly --sql 'CREATE TABLE backup AS SELECT * FROM user' --save-dir ./out user.csv"
+Sleep 600ms
+Enter
+Sleep 2500ms
+Type "sqly --sql 'UPDATE user SET identifier = identifier + 100' --save --force user.csv"
+Sleep 600ms
+Enter
+Sleep 2s
+Type "head -2 user.csv"
+Sleep 600ms
+Enter
+Sleep 2s

doc/vhs/join.sql

@@ -0,0 +1,45 @@
+package main
+
+import (
+	"os"
+	"regexp"
+	"testing"
+)
+
+// TestREADMEVersionMatchesChangelog guards against release-era version drift in
+// the README: every "sqly vX.Y.Z" string (the shell welcome snippet and the
+// benchmark caption) must match the latest version heading in CHANGELOG.md. When a
+// release bumps the changelog, this fails until the README is refreshed too, so
+// stale version strings cannot silently linger. Ref #454.
+func TestREADMEVersionMatchesChangelog(t *testing.T) {
+	t.Parallel()
+
+	changelog, err := os.ReadFile("CHANGELOG.md")
+	if err != nil {
+		t.Fatalf("read CHANGELOG.md: %v", err)
+	}
+	// The first "## [vX.Y.Z]" heading is the latest released version.
+	headingRe := regexp.MustCompile(`(?m)^## \[(v\d+\.\d+\.\d+)\]`)
+	heading := headingRe.FindSubmatch(changelog)
+	if heading == nil {
+		t.Fatal("no version heading found in CHANGELOG.md")
+	}
+	latest := string(heading[1])
+
+	readme, err := os.ReadFile("README.md")
+	if err != nil {
+		t.Fatalf("read README.md: %v", err)
+	}
+	// Match the version that trails an explicit "sqly v" reference, which is what a
+	// release bump must keep current. Other incidental version strings are ignored.
+	versionRe := regexp.MustCompile(`sqly (v\d+\.\d+\.\d+)`)
+	matches := versionRe.FindAllStringSubmatch(string(readme), -1)
+	if len(matches) == 0 {
+		t.Fatal(`no "sqly vX.Y.Z" reference found in README.md`)
+	}
+	for _, m := range matches {
+		if m[1] != latest {
+			t.Errorf("README.md has %q but the latest CHANGELOG version is %q; refresh the README version strings", m[0], latest)
+		}
+	}
+}