cybertrain 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213798cb904eb6eb4ba8f45d0ef3c4d89db13533689a40ca0faf8419514bdc25
-  data.tar.gz: 4a975e911f2e3bbd3de9c3e5d126a5095a52a36bbe21365e97620c0b13b921d1
+  metadata.gz: 2bfb12d19791bff7ce88504f9ffb5fe6e2d90ae7a55aa24f5571b1909cf11976
+  data.tar.gz: 0eaac7a028bbf9be6c013b716ecec76f02c91fb10aa04e855f7b777f250c8712
 SHA512:
-  metadata.gz: 44538d5ef1697095ca313333baaf0c7a47ece4ae98ed480b39da2553cb99f3da265862d24e921a7e60f8226bbb02a52b804cbc7f95b553152730b19f626772e9
-  data.tar.gz: 7edfda7ced1ce88bea85fca1a45ced852ebdee842861fb3ebd6ee0cfe9bfdb317bdecce8e1f330a1095ba1712f5e6f122eb2e48e6b0f447849ea1a29db7b95fb
+  metadata.gz: 66bf793c97cf16d109519514b10c15d929e627137e58a4663d04ad3e88a746fa12e95b39358f15ebe8ba643107a2f8f30dbee54cbc9e95ea5127a4cc870fb417
+  data.tar.gz: 02bcced8e7ab059cb479b06835420eb241271b4447ed0e7d16c2801c6ed50b6b0d3587ff6557ae9b36501a5a108b05c2a4e7d5757caf7887c353ed41e4c2deb7

data/README.md

@@ -1,10 +1,21 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="site/assets/brand/lockup-stacked-dark.svg">
+    <img alt="CyberTrain" src="site/assets/brand/lockup-stacked-light.svg" width="360">
+  </picture>
+</p>
+<p align="center">
+  <a href="https://saeki-mototsune.github.io/CyberTrain/">Homepage</a> ·
+  <a href="https://saeki-mototsune.github.io/CyberTrain/tutorial.html">Tutorial</a>
+</p>
+
 # cybertrain
 
 cybertrain is a Rails-shaped web application framework written natively for
 [Spinel](https://github.com/matz/spinel), matz's ahead-of-time Ruby compiler.
 There is no Rack, no gems at runtime, and no Ruby interpreter in the deployed
-artifact: `spin build` compiles an application — controllers, models, views
-and the framework itself — into a single native binary. Where Rails leans on
+artifact: `cybertrain build` compiles an application — controllers, models,
+views and the framework itself — into a single native binary. Where Rails leans on
 runtime metaprogramming (`method_missing`, `define_method`, `eval`) for
 `before_action :set_post` or `Post.where(title: "x")`, cybertrain gets the
 same vocabulary by generating plain, committed Ruby from `db/schema.rb` and
@@ -25,51 +36,135 @@ Rails" below.
 
 ## Requirements
 
-- Spinel `2026.09.12`, with `spinel` and `spin` on `PATH` (see `SPINEL_TAG`
-  in [.github/workflows/ci.yml](.github/workflows/ci.yml)); untested against
-  other versions.
-- A C toolchain (`cc`) — Spinel compiles every program to C.
-- Ruby 3.2+ and RubyGems, for the `cybertrain` command only (applications
-  never run on CRuby).
+- Spinel `2026.09.12` (`Cybertrain::SPINEL_TAG`, the same release as
+  `SPINEL_TAG` in [.github/workflows/ci.yml](.github/workflows/ci.yml));
+  untested against other versions. You do not install it by hand: the
+  `cybertrain` command builds that release into `~/.cybertrain` the first
+  time it needs it (`cybertrain setup` does that on request), unless a
+  `spinel` of that release is already on `PATH` — see "Installing the CLI".
+- To build it: a C toolchain (`cc`, or the compiler `CC` names) and `make`
+  — Spinel compiles every program to C — plus `git` and `curl`.
 - SQLite 3 headers/library (`libsqlite3-dev` on Debian/Ubuntu; present with
   Xcode's command line tools on macOS) — models use Spinel's FFI directly,
-  not a gem. Building Spinel itself also needs OpenSSL's headers
-  (`libssl-dev`); cybertrain itself does not link OpenSSL.
+  not a gem.
+- Ruby 3.2+ and RubyGems, for the `cybertrain` command only (applications
+  never run on CRuby).
+- OpenSSL's headers (`libssl-dev`) are optional: without them Spinel builds
+  without its `openssl` package, which cybertrain does not use.
+
+`cybertrain doctor` checks these tools and headers and the Spinel install;
+when a required one is missing it also prints the install command for your
+platform.
 
-The framework has no separate test runner; it tests itself:
+The framework has no separate test runner; it tests itself. `spin` comes
+with Spinel, and `cybertrain spin` runs the copy `cybertrain` installs
+without touching `PATH` (or put that copy on `PATH` with the `export
+PATH=...` line `cybertrain setup` prints, and call `spin` directly):
 
 ```sh
-spin test
+cybertrain spin test
 ```
 
 compiles and runs every program under `test/` and diffs its output against a
 committed `test/<name>.rb.expected` snapshot — minitest/RSpec can't run under
 Spinel, since they find test methods by reflection and an ahead-of-time
-compiler has nothing to reflect on at run time. `spin test --regen
-test/<name>.rb` rewrites a snapshot from CRuby's output; a few tests that
+compiler has nothing to reflect on at run time. `cybertrain spin test
+--regen test/<name>.rb` rewrites a snapshot from CRuby's output; a few tests that
 touch SQLite through FFI take theirs from the compiled binary instead
-([spikes/NOTES.md](spikes/NOTES.md), rule 23).
+([spikes/NOTES.md](spikes/NOTES.md), rule 23); `script/regen-snapshot
+test/<name>.rb` does that build-then-capture step for you and prints the diff stat.
 
 ## Installing the CLI
 
 ```sh
 gem install cybertrain
+cybertrain new blog    # also installs Spinel, the first time (a few minutes)
+cd blog
+cybertrain g scaffold article title:string body:text
+cybertrain db migrate
+cybertrain server      # http://127.0.0.1:3000
+cybertrain build       # production: dist/
 ```
 
 The `cybertrain` command is plain Ruby and the gem runs it under CRuby
-(3.2 or newer); the framework itself is not in the gem. Two commands:
-`cybertrain new NAME` scaffolds an application, `cybertrain generate
-scaffold NAME field:type ...` (alias `g scaffold`) adds a resource to one.
-
-`cybertrain new` points the app's `spin.toml` at the release matching the
-CLI — `cybertrain = { git = "https://github.com/saeki-mototsune/cybertrain",
-ref = "v0.1.0" }` — then runs `spin lock` (spin fetches the framework into
-its cache, `~/.cache/spin/packages/`, and pins the commit in `spin.lock`)
-and `spin run gen`, much as `rails new` runs `bundle install`. Nothing of
-the framework is copied into the app; commit `spin.toml` and `spin.lock`.
-`--skip-spin` leaves both steps for later, `--path DIR` depends on a local
-checkout instead, and `--version V` on an index version once cybertrain is
-on a `spin-index`.
+(3.2 or newer); neither the framework nor Spinel is in the gem. Its
+commands (`cybertrain help` prints them):
+
+- `cybertrain new NAME [--path DIR | --version V | --git URL [--ref R]]
+  [--skip-spin]` creates an application in NAME, then runs `spin lock` and
+  `spin run gen` in it, installing Spinel first when it is needed.
+- `cybertrain generate scaffold NAME field:type ...` (alias `g scaffold`)
+  adds a resource to the application in the current directory.
+- `cybertrain db migrate` generates, applies pending migrations, and
+  generates again (`spin run gen; spin run db -- migrate; spin run gen`);
+  `cybertrain migration` is kept as an alias.
+- `cybertrain db COMMAND...` runs any other database command after `spin
+  run gen`: `status`, `rollback [N]` (which generates again afterwards),
+  `schema:dump`, `create`.
+- `cybertrain server [PORT]` generates, then starts the development server
+  (`spin run gen; spin run NAME`, or `spin run NAME -- PORT`; default port
+  3000).
+- `cybertrain build` builds NAME with `app/views/` embedded and assembles
+  `dist/` (the binary, `public/`, `storage/`, `tmp/`).
+- `cybertrain spin ARGS...` runs `spin` with the pinned Spinel from any
+  directory (`cybertrain spin test`, `cybertrain spin run gen -- --check`).
+- `cybertrain setup [--force]` installs Spinel `2026.09.12` into
+  `~/.cybertrain` unless a `spinel` of that release is already on `PATH`;
+  `--force` rebuilds the copy under `~/.cybertrain`.
+- `cybertrain doctor` checks the C toolchain, the SQLite headers and the
+  Spinel install.
+- `cybertrain version` prints the version.
+
+`db`, `server` and `build` run inside an application; NAME is the
+`[package] name` in its `spin.toml`.
+
+Every command that runs `spin` (`new`, `db`, `server`, `build`, `spin`) first makes
+sure a Spinel of the release in `Cybertrain::SPINEL_TAG` is available. A
+`spinel` on `PATH` (with a `spin`) whose `spinel --version` reports that
+release is used as it is; otherwise the copy `cybertrain` keeps under
+`~/.cybertrain/spinel/2026.09.12/` is used; otherwise `cybertrain` builds
+that copy from the release tag (`git clone`, `make deps`, `make -j`, `make
+install PREFIX=...`), once, in a few minutes. The build log is
+`~/.cybertrain/log/spinel-2026.09.12-build.log` (its last lines are printed
+if a step fails); if a tool the build needs is missing, `cybertrain` says
+which and prints the install command for your platform before it starts. A
+`spinel` of another release on `PATH` is never used or touched:
+`cybertrain` keeps its own copy (and says so when it installs it).
+
+`cybertrain setup` does the same on request and, whenever its own copy is
+the one in use, prints the line that puts it on `PATH`, for running `spin`
+yourself (`~/.cybertrain/bin` holds `spinel` and `spin` links to the release
+in use, so the line survives a release bump; `cybertrain spin ...` needs no
+`PATH` at all):
+
+```sh
+export PATH="$HOME/.cybertrain/bin:$PATH"
+```
+
+Two environment variables override all this: `CYBERTRAIN_HOME` replaces
+`~/.cybertrain` (a path without spaces, quotes, `$` or `:`, which Spinel's
+Makefile and `PATH` cannot take), and `CYBERTRAIN_SPINEL_HOME=PREFIX` forces
+an existing install — `cybertrain` then uses the `spinel` and `spin` in `PREFIX/bin` (or
+in `PREFIX` itself, if `spinel` is directly in it) and stops with an error
+if they are not that release.
+
+`cybertrain new` writes the application with its `spin.toml` pointing at
+the release matching the CLI (`cybertrain = { git =
+"https://github.com/saeki-mototsune/cybertrain", ref = "v0.2.0" }`), makes
+sure Spinel is installed, then runs `spin lock` (spin fetches the framework
+into its cache, `~/.cache/spin/packages/`, and pins the commit in
+`spin.lock`) and `spin run gen`, much as `rails new` runs `bundle install`,
+and prints the next steps. Nothing of the framework is copied into the app;
+commit `spin.toml` and `spin.lock`. If Spinel or one of the two `spin`
+steps fails, the files stay, `new` exits with 1 and prints what to run once
+the cause is fixed (for Spinel: `cybertrain setup`, then `cybertrain spin
+lock && cybertrain spin run gen` in the new directory).
+
+`--skip-spin` only writes the files: no Spinel install, no `spin lock`, no
+`spin run gen`. `--path DIR` depends on a local checkout instead,
+`--git URL [--ref R]` on the framework at URL (at branch or tag R), and
+`--version V` on an index version once cybertrain is on a `spin-index`.
+Give only one of `--path`, `--version` and `--git`; `--ref` needs `--git`.
 
 Working on cybertrain itself, run the CLI from the checkout (`spin install`
 builds `bin/cybertrain.rb` into `~/.local/bin/cybertrain`; `ruby -I.
@@ -87,7 +182,7 @@ articles and comments.
 ```sh
 cybertrain new blog
 cd blog
-spin build            # works right away: `new` already locked the framework and ran `spin run gen`
+cybertrain server            # works right away: `new` already locked the framework and ran `spin run gen`
 ```
 
 ```
@@ -95,10 +190,23 @@ blog/
   spin.toml  config/app.rb  config/routes.rb
   db/schema.rb  db/migrate/
   app/controllers/application_controller.rb  app/models/  app/views/  app/helpers/
-  public/  bin/server.rb  bin/gen.rb  bin/db.rb
+  public/  bin/blog.rb  bin/gen.rb  bin/db.rb
   gen/  storage/  tmp/  test/
 ```
 
+`bin/blog.rb` is the application's one entry point, the program `spin build
+blog` compiles: `./blog` serves, `./blog migrate` and `./blog db status`
+manage the database. `bin/gen.rb` runs the generator (`spin run gen`), and
+`bin/db.rb` runs the migrator during development (`cybertrain db migrate`
+uses it, since `bin/blog.rb` cannot compile until the first migration has
+generated `gen/models/`). `gen/` already holds `views.rb`, the committed,
+empty table of embedded views (see "How it works").
+
+Apps created before `cybertrain build` existed have `bin/server.rb` and
+no `bin/<name>.rb`: copy `bin/<name>.rb` from a fresh `cybertrain new` (with
+the same NAME), delete `bin/server.rb`, add `/dist/` to `.gitignore` (the old
+template did not ignore it) and run `cybertrain spin run gen`.
+
 `ApplicationController` starts with the one thing every controller inherits:
 
 ```ruby
@@ -181,19 +289,23 @@ end
 ### Generate, migrate, run
 
 ```sh
-spin run gen          # reads db/schema.rb + config/routes.rb, scans app/, writes gen/
-spin run db -- migrate   # applies db/migrate/*.rb, rewrites db/schema.rb (arguments go after --)
-spin run server       # http://127.0.0.1:3000
+cybertrain db migrate    # spin run gen; spin run db -- migrate; spin run gen
+cybertrain server        # http://127.0.0.1:3000; rebuilds on Ruby edits, views reload without a rebuild
 ```
 
-Re-run `spin run gen` (and commit `gen/`) after touching the schema, routes,
-or a controller/model's callbacks and ivars — the dev server does this for
+`spin run gen` reads `db/schema.rb` and `config/routes.rb`, scans `app/` and
+writes `gen/`; `spin run db -- migrate` applies `db/migrate/*.rb` and
+rewrites `db/schema.rb`.
+
+Re-run `cybertrain spin run gen` (and commit `gen/`) after touching the
+schema, routes, or a controller/model's callbacks and ivars — the dev server does this for
 you automatically (see "How it works").
 
 ### Add comments, nested under articles
 
 ```sh
 cybertrain generate scaffold comment commenter:string body:text article:references
+cybertrain db migrate    # the scaffold wrote a migration for the comments table
 ```
 
 `article:references` adds an `article_id` column, index and foreign key —
@@ -277,6 +389,27 @@ child routes to the nested collection (`article_comments_path`), a persisted
 one to the nested member (`article_comment_path`) — generated into
 `gen/routes.rb` from the nested `resources` block above.
 
+### Build for deployment
+
+```sh
+cybertrain build
+```
+
+writes `dist/`: `dist/blog`, the app compiled with every `app/views/`
+template embedded (rendered from memory, error messages still say
+`articles/show.html.erb:12`), `dist/public/`, and empty `dist/storage/` and
+`dist/tmp/`. Copy `dist/` to a machine with the same OS and CPU (the binary
+links the system SQLite) and run `./blog migrate && ./blog`; a built binary
+is production by default (`CYBERTRAIN_ENV` overrides). Set
+`CYBERTRAIN_SECRET_KEY_BASE`. Static files can also be served by the reverse
+proxy from `dist/public/` — see [docs/deploy.md](docs/deploy.md).
+
+A running `cybertrain server` skips its rebuilds while `cybertrain build` is
+in progress (the build holds `tmp/cybertrain-build.lock`, since both write
+`build/bin/blog`), logs the skip, and rebuilds as usual on the next save
+once the build has finished. The lock records the build's PID; one left
+behind by a killed build is ignored and removed.
+
 ## How it works
 
 **Build-time code generation.** `spin run gen` (`bin/gen.rb`) executes
@@ -289,17 +422,24 @@ zero-argument `def`s. From that it writes plain, readable Ruby under `gen/`:
 `gen/models/<name>.rb` (accessors, casts, finders, FK-derived associations),
 `gen/routes.rb` (route table, dispatcher, `*_path`/`*_url` helpers),
 `gen/controllers.rb` (`view_assigns` and `run_callback` per controller),
-`gen/migrations.rb` and `gen/app.rb` (the `require_relative` manifest).
+`gen/migrations.rb`, `gen/views.rb` (the embedded views table, empty unless
+building for deployment) and `gen/app.rb` (the `require_relative` manifest).
 `gen/` is committed, not gitignored — `spin build`/`spin test` have no hook
 to generate first, so the checked-in output has to already be what compiles.
 CI re-runs `spin run gen` and fails on a diff, so stale generated code can't
 merge.
 
 **Views are interpreted, not compiled.** `app/views/**/*.html.erb` files look
-like Rails ERB but are read from disk, parsed into an AST at request time
-(cached after first parse in production; re-parsed on change in
-development), then walked by a tree-walking interpreter — Spinel has no
-`eval`, so this is a closed grammar (literals, `@ivar`/local lookups, calls
+like Rails ERB but are parsed into an AST at request time, then walked by a
+tree-walking interpreter. Where the source comes from depends on the mode:
+in development (and test) the engine reads `app/views/` from disk, and in
+development re-parses a template when it changes, so view edits need no rebuild.
+`cybertrain build` runs `spin run gen -- --embed-views`, which writes every
+template's source into `gen/views.rb` as a string table for that one `spin
+build`, then runs `spin run gen` again to restore the empty table that is
+committed; the production binary renders only that table (parsing each
+template once) and refuses to boot when it is empty (`error: views are not
+embedded in this binary`). Spinel has no `eval`, so this is a closed grammar (literals, `@ivar`/local lookups, calls
 through fixed per-type dispatch tables, `if`/`unless`,
 `each`/`each_with_index`/one helper block), not real Ruby. Full grammar,
 helpers and gaps: [docs/template-language.md](docs/template-language.md).
@@ -316,13 +456,15 @@ faster and stall-free for this I/O-bound shape at 100 concurrent connections.
 and foreign keys on; every query is bound, never interpolated. It's the only
 adapter today (PostgreSQL via `libpq` FFI is noted as possible future work).
 
-**The development loop.** `spin run server` in `development` (the default
-`CYBERTRAIN_ENV`) also polls `app/**/*.rb`, `config/**/*.rb`, `db/schema.rb`
+**The development loop.** `cybertrain server` (`spin run gen`, then `spin run NAME`) in
+`development` (the default `CYBERTRAIN_ENV`, except in a binary from
+`cybertrain build`) also polls `app/**/*.rb`, `config/**/*.rb`, `db/schema.rb`
 and `gen/**/*.rb` every half second (views are excluded — the engine reloads
-those itself). A change runs `spin run gen && spin build server` in the
-background; success sends the server `SIGHUP`, whose handler stops listening
-and `execv`s the new binary on the same port and PID, invisible to a client
-mid-session. A failed build keeps serving the old binary and banners the
+those itself — and so is `gen/views.rb`, empty in development). A change runs `spin run gen && spin build NAME` in the
+background; success requests a restart (the same flag an external `kill -HUP`
+sets): a monitor thread stops the listener and drains open requests, then the
+main thread `execv`s the new binary on the same port and PID, invisible to a
+client mid-session. A failed build keeps serving the old binary and banners the
 compiler output on every HTML response. None of this loads in production.
 
 ## Differences from Rails
@@ -330,7 +472,7 @@ compiler output on every HTML response. None of this loads in production.
 | Rails | cybertrain |
 | --- | --- |
 | `rails console` | No console — Spinel has no `eval` |
-| Edit code, the running app picks it up | Ruby needs a rebuild; `spin run server` in development does this for you (rebuild, `SIGHUP`, `execv`) |
+| Edit code, the running app picks it up | Ruby needs a rebuild; `cybertrain server` in development does this for you (rebuild, stop, `execv`) |
 | Edit a view, no reload needed | Same — views are parsed from disk per request in development |
 | `def new` | `def new_action` (`new` would shadow `Klass.new(ctx)`) |
 | `before_action { do_thing }` (implicit `self`) | `before_action { \|c\| c.do_thing }` — no `instance_exec` on a stored block, so callbacks take the controller/record explicitly |
@@ -361,7 +503,7 @@ end
 
 | Variable | Attribute | Default |
 | --- | --- | --- |
-| `CYBERTRAIN_ENV` | `env` | `"development"` (also `"test"`, `"production"`) |
+| `CYBERTRAIN_ENV` | `env` | `"development"`; `"production"` in a binary from `cybertrain build` (also `"test"`) |
 | `PORT` | `port` | `3000` |
 | `CYBERTRAIN_DATABASE` | `database_path` | `storage/#{env}.sqlite3` |
 | `CYBERTRAIN_SECRET_KEY_BASE` | `secret_key_base` | required in production; dev/test auto-generate one into `tmp/secret_key` |
@@ -374,10 +516,12 @@ Other attributes with fixed, overridable defaults: `host` (`"127.0.0.1"`),
 marks the session cookie `Secure`; `false` elsewhere), `pool_size` (4),
 `static_files`/`csrf` (`true`).
 
-**Deployment:** `spin build server` produces `build/bin/server`. Ship it with
-`app/views/` (read at request time, never compiled in), `public/` (static
-assets, or let a reverse proxy serve it) and `storage/` (the SQLite file),
-`CYBERTRAIN_ENV=production` and `CYBERTRAIN_SECRET_KEY_BASE` set. The binary
+**Deployment:** `cybertrain build` produces `dist/`: the binary `dist/NAME`
+with the views embedded, `dist/public/` (static assets, or let a reverse
+proxy serve it), and `dist/storage/` (the SQLite file by default) and
+`dist/tmp/`. Run it from `dist/` with `CYBERTRAIN_SECRET_KEY_BASE` set;
+it is production unless `CYBERTRAIN_ENV` says otherwise, and `./NAME
+migrate` applies the migrations compiled into it. The binary
 speaks plain HTTP/1.1 only; put nginx/Caddy in front for TLS and HTTP/2 (the
 session cookie is `Secure` in production, so serve it over HTTPS). In
 production an exception answers 500 and a bare error response (the router's
@@ -395,7 +539,7 @@ systemd, Caddy with HTTPS, redeploys, rollbacks and backups.
 App tests are plain Spinel programs under `test/`, like the framework's own:
 
 ```ruby
-require "cybertrain/test"
+require_relative "support/blog_test"   # the app, BLOG and Cybertrain::Test
 
 test "title must be present" do
   article = Article.new(body: "a body long enough to pass length")
@@ -410,29 +554,47 @@ full HTTP flows, `Cybertrain::Test::Client` drives an app in-process (no
 socket) with a cookie jar, so sessions and CSRF behave as behind a browser:
 
 ```ruby
-require "cybertrain/test/client"
-
-client = Cybertrain::Test::Client.new(BLOG)
-client.get("/articles/new")
-res = client.post("/articles", "article[title]" => "Hello",
-                                "article[body]" => "I am on Rails!",
-                                "authenticity_token" => token)  # from the rendered form
-assert_redirected_to res, "/articles/1"
-assert_response res, :see_other
+require_relative "support/blog_test"   # the app, BLOG and Cybertrain::Test
+
+test "POST /articles creates an article and redirects to it" do
+  client = Cybertrain::Test::Client.new(BLOG)
+  client.get("/articles/new")
+  res = client.post("/articles", { "authenticity_token" => BlogTest.form_token(client),
+                                   "article[title]" => "Hello Rails",
+                                   "article[body]" => "I am on Rails! This is my first article." })
+  assert_redirected_to res, BlogTest.article_path(Article.last)
+  assert_response res, :see_other
+end
 ```
 
-`examples/blog/test/articles.rb`/`comments.rb` (setup in
-`test/support/blog_test.rb`) show the full pattern, including token
-extraction, against a freshly migrated `storage/test.sqlite3`.
-
-Run with `spin test`: it compiles each `test/*.rb` into its own program and
-diffs stdout against `test/<name>.rb.expected`. Regenerate with `spin test
---regen test/<name>.rb`; FFI/database tests can't run under CRuby, so their
-snapshot comes from the compiled binary instead: `spin test test/<name>.rb &&
-./build/test/<name> > test/<name>.rb.expected`.
+Both snippets start from the example's helper,
+[`examples/blog/test/support/blog_test.rb`](examples/blog/test/support/blog_test.rb):
+copy it into an app's `test/support/`, where files are required, not run.
+It migrates a fresh `storage/test.sqlite3`, boots the app as `BLOG`, loads
+`Cybertrain::Test` and its client, and reads the CSRF token out of the last
+rendered form (`BlogTest.form_token`). End each test file with
+`Cybertrain::Test.run!`; `examples/blog/test/articles.rb` and `comments.rb`
+show the full pattern.
+
+Run with `cybertrain spin test`: it compiles each `test/*.rb` into its own
+program and diffs its output (stdout and stderr together) against
+`test/<name>.rb.expected`. Regenerate with `cybertrain spin test --regen
+test/<name>.rb`; FFI/database tests can't run under CRuby, so their snapshot
+comes from the compiled binary instead: `rm -f build/test/<name>; cybertrain
+spin test test/<name>.rb; [ -x build/test/<name> ] && ./build/test/<name> >
+test/<name>.rb.expected 2>&1` (`cybertrain spin test` exits non-zero while the
+snapshot is stale, so it is followed by `;`, not `&&`; the `[ -x ]` check skips
+the capture when the compile failed, so the old snapshot is kept; in the
+framework checkout, `script/regen-snapshot test/<name>.rb` does exactly this and
+prints the diff stat).
 
 ## Learn more
 
+- [Homepage](https://saeki-mototsune.github.io/CyberTrain/) and
+  [tutorial](https://saeki-mototsune.github.io/CyberTrain/tutorial.html) —
+  the source lives in [site/](site/), published by
+  [.github/workflows/pages.yml](.github/workflows/pages.yml); the logo files and
+  brand notes are in [site/assets/brand/](site/assets/brand/BRAND.md).
 - [docs/design.md](docs/design.md) — the design record (Japanese): every
   decision, what was rejected and why, and the Spinel constraints behind it.
 - [docs/template-language.md](docs/template-language.md) — the full template
@@ -453,8 +615,13 @@ before the gem is pushed:
 1. Bump `Cybertrain::VERSION` (`cybertrain/version.rb`) and `version` in
    `spin.toml` together (CI checks they match); spin caches a git
    dependency by that version.
-2. Merge to `main`, then tag and push: `git tag v0.1.0 && git push origin v0.1.0`.
-3. `gem build cybertrain.gemspec && gem push cybertrain-0.1.0.gem`.
+2. Merge to `main`, then tag and push: `git tag v0.2.0 && git push origin v0.2.0`.
+3. `gem build cybertrain.gemspec && gem push cybertrain-0.2.0.gem`.
+
+`Cybertrain::SPINEL_TAG` (also in `cybertrain/version.rb`) is the Spinel
+release `cybertrain setup` installs. It must equal `SPINEL_TAG` in
+[.github/workflows/ci.yml](.github/workflows/ci.yml), which CI checks, so
+change the two together when the framework moves to another Spinel release.
 
 ## License