create-rindle 0.10.4 → 0.10.5

package/README.md

@@ -1,90 +1,17 @@
 # create-rindle
 
-Scaffold a new **SQL-first [Rindle](https://github.com/rindle-sh/rindle) app on
-[TanStack Start](https://tanstack.com/start)** in one command.
+Create a [Rindle](https://rindle.sh) application with TanStack Start, live queries,
+optimistic writes, SQL migrations, and local guidance for coding agents.
 
 ```bash
 npm create rindle@latest my-app
-# or
-npx create-rindle my-app
-# or: pnpm create rindle my-app · yarn create rindle my-app · bun create rindle my-app
-```
-
-Then:
-
-```bash
 cd my-app
-pnpm dev
-```
-
-Full docs — what the template contains and how to grow it:
-**[rindle.sh/docs/create-rindle](https://rindle.sh/docs/create-rindle)** · markdown
-mirror: [`create-rindle.md`](https://rindle.sh/docs/create-rindle.md) · for agents:
-[llms.txt](https://rindle.sh/llms.txt)
-
-## What you get
-
-A minimal but real three-tier Rindle app (a tiny forum-of-rooms with **live message counts**):
-
-- **Browser** — a TanStack Start SPA whose data layer is Rindle's in-process wasm IVM engine: local
-  instant reads, optimistic writes, fragment-rooted `useRoot` reads, and a dev-only Rindle devtools
-  pane.
-- **API server** — the authority: named-query resolution, authoritative SQL mutators, and policy (a
-  `"spam"` rejection demo shows the optimistic snap-back + toast).
-- **Daemon** (`rindled`) — owns the SQLite data + live incremental views, streamed to subscribers.
-
-The schema is **SQL-first**: `migrations/*.sql` is the source of truth, and the `@rindle/client`
-schema is generated from it into `shared/schema.gen.ts` (`rindle up --migrate --gen shared/schema.gen.ts --watch` in
-the dev loop), so the TypeScript can't drift from the DDL.
-
-The prebuilt `rindle` + `rindled` binaries come from `@rindle/cli` (per-platform, installed as a dev
-dependency) — **no Rust toolchain required**.
-
-## Fragment flow in the template
-
-The generated routes use the current co-located fragment pattern:
-
-- `src/components/*.queries.ts` defines each component's `defineFragment` beside the named
-  `defineQuery` that roots it.
-- The home route declares `roomsQuery()` through `@rindle/tanstack`'s `rindle.loader`, which seeds
-  SSR and waits for the same live query on client navigation, then calls
-  `useRoot(roomsQuery, RoomCardFragment)` to receive opaque room refs.
-- Row components call `useFragment(RoomCardFragment, room)` to open narrow local reads without a
-  new server subscription.
-- The room detail route calls `useRoot(roomDetailQuery, id)` when the route itself owns the root
-  fields and passes child message refs down with `fragmentKey(ref)` list keys.
-
-## Usage
-
-```
-create-rindle [directory] [options]
-
-Options:
-  --no-install    Don't run the package-manager install after scaffolding
-  --pm <name>     Package manager: npm | pnpm | yarn | bun (default: auto-detected)
-  --link          Internal: wire @rindle/* to this monorepo's workspace (for apps/* in the repo)
-  -h, --help      Show help
+npm run dev
 ```
 
-`--link` is for developing the template *inside* the Rindle monorepo: it rewrites the `@rindle/*`
-dependencies to `workspace:*` and switches `vite.config.ts` / `tsconfig.json` to the `@rindle/source`
-aliases the in-repo examples use, so a scaffold dropped into `apps/` typechecks against source. CI
-uses it to typecheck the generated app on every change.
-
-
-## Devtools in generated apps
-
-The default template mounts `@rindle/react-devtools` in development and attaches
-`@rindle/devtools` to the generated Rindle client. Click the floating **🌊 Rindle** launcher to
-inspect the optimistic mutation timeline, live queries, and raw delta stream. Both packages are
-imported behind `import.meta.env.DEV`, so they tree-shake out of production builds.
-
-## Templates
-
-| name | description |
-|---|---|
-| `minimal` (default) | rooms + messages with live counts, optimistic writes, SSR, the auth seam |
-
-## Requirements
+Published scaffold releases use matching Rindle packages and documentation.
+Use `--no-agents` to skip local documentation and skill installation.
 
-The generated app runs the `.ts` server files via Node's built-in type stripping — **Node ≥ 22.18**.
+- [Scaffold guide](https://rindle.sh/docs/create-rindle)
+- [Agent installation and version checks](https://rindle.sh/docs/for-agents)
+- [Documentation index for agents](https://rindle.sh/llms.txt)

package/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // `npm create rindle@latest [dir]` / `npx create-rindle [dir]` — scaffold a SQL-first Rindle app on
-// TanStack Start. Zero runtime dependencies: argument parsing, a minimal interactive prompt, and the
-// template copy all run on Node built-ins, so this boots with nothing installed.
+// TanStack Start. The bundled agent context and scaffold use Node built-ins. No native
+// binaries are needed until the generated application's development server starts.
 //
 //   create-rindle my-app                 # scaffold ./my-app (the only template today: "minimal")
 //   create-rindle my-app --no-install    # skip the package-manager install
@@ -12,6 +12,7 @@ import { spawnSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
+import { setupAgentContext } from "@rindle/agent-context";
 
 import { isValidPackageName, packageNameFromDir, scaffold } from "./lib/scaffold.mjs";
 
@@ -19,11 +20,12 @@ const here = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = "minimal";
 
 function parseArgs(argv) {
-  const opts = { dir: undefined, install: true, pm: undefined, link: false, help: false };
+  const opts = { dir: undefined, install: true, agents: true, pm: undefined, link: false, help: false };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h") opts.help = true;
     else if (a === "--no-install") opts.install = false;
+    else if (a === "--no-agents") opts.agents = false;
     else if (a === "--link") opts.link = true;
     else if (a === "--pm") opts.pm = argv[++i];
     else if (a.startsWith("--pm=")) opts.pm = a.slice("--pm=".length);
@@ -31,6 +33,10 @@ function parseArgs(argv) {
     else if (opts.dir === undefined) opts.dir = a;
     else fail(`unexpected argument: ${a}`);
   }
+  if (opts.pm !== undefined && !["npm", "pnpm", "yarn", "bun"].includes(opts.pm)) {
+    fail("--pm must be npm, pnpm, yarn, or bun");
+  }
+  if (argv.includes("--pm") && opts.pm === undefined) fail("--pm requires a package manager");
   return opts;
 }
 
@@ -47,6 +53,7 @@ Usage:
 
 Options:
   --no-install      Don't run the package-manager install after scaffolding
+  --no-agents       Skip local documentation, skill, and agent instruction setup
   --pm <name>       Package manager to use (npm | pnpm | yarn | bun); default: auto-detect
   --link            Internal: wire @rindle/* to this monorepo's workspace (for apps/* in the repo)
   -h, --help        Show this help
@@ -94,7 +101,7 @@ async function main() {
   process.stdout.write(`\n  Scaffolding a Rindle app in ${targetDir}\n`);
   let created;
   try {
-    created = await scaffold({ templateDir, targetDir, projectName, link: opts.link });
+    created = await scaffold({ templateDir, targetDir, projectName, link: opts.link, agents: opts.agents });
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err));
   }
@@ -105,8 +112,12 @@ async function main() {
     process.stdout.write(`\n  Installing dependencies with ${pm}…\n\n`);
     const install = spawnSync(pm, ["install"], { cwd: targetDir, stdio: "inherit", shell: process.platform === "win32" });
     if (install.status !== 0) {
-      process.stdout.write(`\n  Install failed or was skipped — run \`${pm} install\` yourself.\n`);
+      process.stderr.write(`\n  The project was created, but dependency installation failed${install.error ? `: ${install.error.message}` : "."}\n`);
+      process.stderr.write(`  Run \`${pm} install\` in ${targetDir}${opts.agents ? `, then \`${pm === "npm" ? "npx" : `${pm} exec`} rindle agents setup\` to verify its documentation` : ""}.\n`);
+      process.exitCode = 1;
+      return;
     }
+    if (opts.agents) await setupAgentContext({ projectDir: targetDir });
   }
 
   const run = pm === "npm" ? "npm run" : pm;
@@ -114,11 +125,15 @@ async function main() {
     `\n  Done. Next steps:\n\n` +
       `    cd ${dir}\n` +
       (opts.install ? "" : `    ${pm} install\n`) +
+      (!opts.install && opts.agents ? `    ${pm === "npm" ? "npx" : `${pm} exec`} rindle agents setup\n` : "") +
       `    ${run} dev\n\n` +
       `  The migrations in migrations/*.sql are the source of truth — \`${run} dev\` applies them,\n` +
       `  generates shared/schema.gen.ts, and boots the topology pair + Vite (app + /api/rindle routes).\n` +
       `  Open two browser windows, create a room, and watch writes sync live.\n\n`,
   );
+  if (opts.agents) {
+    process.stdout.write("  Agent guidance is in AGENTS.md and CLAUDE.md. Local docs: .rindle/agent-context/index.md\n");
+  }
 }
 
 main().catch((err) => fail(err instanceof Error ? err.stack ?? err.message : String(err)));

package/lib/scaffold.mjs

@@ -1,15 +1,17 @@
 // The scaffold engine: copy a template tree into a target directory, substituting the project name
 // and renaming the `_`-prefixed dotfiles npm refuses to publish (`_gitignore` → `.gitignore`). Pure
-// Node built-ins, no dependencies — so `npm create rindle` runs with nothing installed.
+// Node built-ins plus the bundled agent-context package; no native tools are needed.
 //
 // `--link` mode (internal/dev) rewrites the generated app to consume the @rindle/* packages from the
 // surrounding pnpm WORKSPACE instead of npm: deps become `workspace:*`, and vite/tsconfig switch to the
 // `@rindle/source` aliases the in-repo examples use. That lets us scaffold straight into `apps/` and
 // typecheck the output against the real source — the "CI typechecks the generated app" discipline.
 
-import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { cp, lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, join, relative } from "node:path";
+import { setupAgentContext } from "@rindle/agent-context";
+
+const SCAFFOLD_VERSION = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
 
 /** The token the template files carry wherever the project's package name belongs. */
 export const PROJECT_NAME_TOKEN = "__PROJECT_NAME__";
@@ -143,17 +145,42 @@ export async function applyWorkspaceLinks(targetDir) {
   await writeFile(join(targetDir, "tsconfig.json"), WORKSPACE_TSCONFIG);
 }
 
-/** Full scaffold: validate the target, copy the template, optionally apply workspace links. */
-export async function scaffold({ templateDir, targetDir, projectName, link = false }) {
-  if (existsSync(targetDir)) {
-    const entries = await readdir(targetDir).catch(() => []);
+/** Pin the generated app to the same release as its template and documentation. */
+export async function pinRindleVersion(targetDir, version) {
+  if (version === "0.0.0") return; // An unreleased source checkout has no registry release to pin.
+  const pkgPath = join(targetDir, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const name of Object.keys(pkg[field] ?? {})) {
+      if (name.startsWith("@rindle/")) pkg[field][name] = version;
+    }
+  }
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+/** Copy a new application, then install its bundled agent documentation. */
+export async function scaffold({ templateDir, targetDir, projectName, link = false, agents = true, rindleVersion = SCAFFOLD_VERSION }) {
+  const targetStat = await lstat(targetDir).catch(error => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (targetStat) {
+    if (targetStat.isSymbolicLink() || !targetStat.isDirectory()) {
+      throw new Error(`target must be a real directory, not a file or symlink: ${targetDir}`);
+    }
+    const entries = await readdir(targetDir);
     if (entries.length > 0) {
       throw new Error(`target directory is not empty: ${targetDir}`);
     }
   }
   const created = await copyTemplate(templateDir, targetDir, projectName);
   if (link) await applyWorkspaceLinks(targetDir);
-  return created;
+  else await pinRindleVersion(targetDir, rindleVersion);
+  if (agents) {
+    const context = await setupAgentContext({ projectDir: targetDir, allowUninstalled: true, deferVersionCheck: true });
+    created.push(...context.files);
+  }
+  return [...new Set(created)].sort();
 }
 
 // Re-exported for the CLI's "is this a sane package name?" check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rindle",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -21,6 +21,9 @@
   "engines": {
     "node": ">=22"
   },
+  "dependencies": {
+    "@rindle/agent-context": "0.10.5"
+  },
   "keywords": [
     "rindle",
     "tanstack",

package/templates/minimal/AGENTS.md

@@ -1,94 +1,46 @@
-# AGENTS.md — working on __PROJECT_NAME__
+# Working on __PROJECT_NAME__
 
-Guidance for coding agents (and new humans). This is a **Rindle** app — an
-incremental-view-maintenance (IVM) engine keeps every registered query's result
-exact on each write instead of re-running it. Three tiers: a TanStack Start SPA
-running the wasm engine in-process, an API authority, and the data tier — the one
-topology (design 214): a `rindle-replicator` write-master + a `rindled`
-read-follower (`followers = 1` = the colocated pair). The correctness contract
-everywhere is **view-after-write == fresh-query**.
+This project uses TanStack Start and Rindle. The browser has optimistic writes.
+The application's API authorizes named queries and mutations. `rindle.ncl`
+selects a replicated data tier with one write master and one read follower.
 
-Rindle docs are served as raw markdown for LLMs: index at
-<https://rindle.sh/llms.txt>, the whole app track in one file at
-<https://rindle.sh/llms-app.txt>.
+## Project commands
 
-## Commands
+- `pnpm dev` starts the data tier and application, applies migrations, and generates schema types.
+- `pnpm typecheck` generates the route tree and checks TypeScript.
+- `pnpm migrate` applies the files in `migrations/` to the configured local data tier.
+- `pnpm rindle:deploy` deploys the data tier to Rindle Cloud after `rindle login`.
+- `pnpm rindle:migrate:cloud` applies migrations to the linked Cloud database.
 
-- `pnpm dev` — the one lifecycle command: `rindle dev` evaluates `rindle.ncl`
-  once, supervises the `rindle-replicator` write-master + `rindled` follower +
-  fleet edge (prebuilt binaries from `@rindle/cli`, no Rust toolchain), waits for
-  them, applies `migrations/*.sql`, regenerates `shared/schema.gen.ts`, then runs
-  Vite on :3000 with `RINDLE_URL` + `RINDLE_DATABASE_TOKEN`. It watches migration
-  and follower-schema changes and tears down the whole process tree together.
-- `pnpm typecheck` — regenerates the route tree, then `tsc --noEmit`.
-- `pnpm migrate` — one-shot `rindle migrate apply` against the unified ingress derived
-  from `rindle.ncl` (the follower's `/migrate` is write-fenced). The dev loop already
-  applies on boot + on every `migrations/` change.
-- `pnpm rindle:deploy` / `pnpm rindle:migrate:cloud` — deploy the data tier to
-  Rindle Cloud (reads `rindle.ncl`, the same file `rindle up` runs locally; run
-  `rindle login` once first) and push `migrations/*.sql` to the deployed master.
+With npm, use `npm run` followed by the script name.
 
-## Rules that keep the app correct
+## Application files
 
-Break one of these and the app goes subtly wrong. Treat violations as bugs in
-review:
-
-1. **SQL is the source of truth.** Change the schema by **adding** a
-   `migrations/*.sql` file (SQL DDL: `CREATE TABLE` / `ADD COLUMN` /
-   `CREATE INDEX`, plus the destructive `DROP TABLE` / `DROP COLUMN` /
-   `DROP INDEX` — no `RENAME`; every table a single primary key). **Never
-   hand-edit `shared/schema.gen.ts`** — it is generated from the live daemon
-   and overwritten on the next migration.
-2. **Mutators are one isomorphic body, deterministic and replayable**
-   (`shared/app-def.ts`): a generator that `yield`s logical ops
-   (`yield tx.insert(...)`), paired with its zod arg schema via
-   `shared(args, gen)`. No `Date.now()`, no `Math.random()`, no I/O — the client
-   re-invokes the body on every rebase. Generate ids and timestamps at the
-   callsite and pass them in as args; the acting user is `ctx.user` (injected
-   per tier), never an arg.
-3. **The server drives the same body** — `sharedApiMutators` in
-   `server/app-api.ts` auto-wraps the whole registry (parse the untrusted wire
-   args through each mutator's `.args`, inject the authenticated principal,
-   render every op to SQL). Add an explicit entry ONLY for server-only
-   authority the client must not predict (a policy guard, a raw `tx.exec`
-   relational gate). Only `(name, args)` ever crosses the wire; `throw` to
-   hard-reject (the optimistic write snaps back on its own; write no rollback
-   code).
-4. **Remote subscriptions must be named.** Define queries with `defineQuery` in
-   `src/components/*.queries.ts` and register them in `server/app-api.ts`. An
-   ad-hoc `store.query.…` builder resolves **locally only** — it never opens a
-   server subscription.
-5. **Database tokens are server-only.** `rindle dev` injects the one application connection as
-   `RINDLE_URL` + `RINDLE_DATABASE_TOKEN`; the bearer must never reach the browser. The browser
-   learns only the public WebSocket endpoint + placement ticket from its query-lease response.
-   Never copy topology ports into package scripts or add a browser config endpoint.
-6. **Subscribe to windows, not whole tables** — order + `limit`, and ratchet
-   `limit` up for "load more". The engine keeps the window (and any `countAs`)
-   exact as rows enter and leave.
-7. **Keep `*.queries.ts` modules React-free** — no `.tsx` imports. The browser,
-   the API authority, and the SSR loader all import these same modules.
-8. **Declare route reads through `rindle.loader(...)`** (`src/rindle-tanstack.ts`).
-   It owns server preloading, client navigation readiness/cancellation, and
-   blocking stale reloads. Keep `rindle.Provider` at the root; do not recreate
-   the old `useMatches()` merge or a separate `<RindleSSR>` wrapper.
-
-## File map
-
-| Path | What it is |
+| Path | Purpose |
 | --- | --- |
-| `migrations/*.sql` | the real schema — the only place DDL lives |
-| `shared/schema.gen.ts` | **generated** table schema — do not edit |
-| `shared/app-def.ts` | the shared contract: relationships, query builder, isomorphic mutators |
-| `src/components/*.queries.ts` | named queries + fragments, co-located with their components |
-| `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
-| `src/rindle-tanstack.ts` | the shared `rindle.loader` + `rindle.Provider` integration |
-| `server/app-api.ts` | the authority: `registerQueries` + `sharedApiMutators` + server-only policy |
-| `src/routes/api.rindle.*.tsx` | TanStack Start server routes exposing the authority over HTTP |
-| `rindle.ncl` | the one topology (the colocated pair) — `rindle up` runs it locally, `rindle deploy` provisions it |
-| `src/ssr.ts` | SSR preload of the same named queries for first paint |
-
-## Reading more
-
-Per-page markdown mirrors live at `https://rindle.sh/docs/<slug>.md`. Most
-relevant here: `synced-app-quickstart`, `client`, `api-server`, `schema`,
-`fragments`, `ssr`, `supported-queries-ts`, `change-model`.
+| `migrations/*.sql` | Ordered database migrations |
+| `shared/schema.gen.ts` | Generated schema types. Do not edit this file. |
+| `shared/app-def.ts` | Relationships, query builder, and shared mutators |
+| `src/components/*.queries.ts` | Named queries and component fragments |
+| `src/rindle-client.ts` | Browser client initialization |
+| `src/rindle-tanstack.ts` | Route loaders and the shared Rindle provider |
+| `src/routes/__root.tsx` | Application root with `rindle.Provider` |
+| `src/ssr.ts` | Server preloading through the application's API authority |
+| `server/app-api.ts` | Query registration and authoritative mutation handlers |
+| `server/auth-dev.ts` | Demonstration identity provider |
+| `src/routes/api.rindle.*.tsx` | Browser-facing API routes |
+| `rindle.ncl` | Local and Cloud data-tier configuration |
+
+Keep shared query modules independent of React components and server secrets.
+Use the existing `rindle.loader` and `rindle.Provider` integration for route reads.
+
+## Demonstration identity
+
+`server/auth-dev.ts` accepts an unverified `x-rindle-user` header.
+Reads are public. The header lets the demonstration create writes without an account.
+Before production, replace this provider with verified application authentication and review access policies.
+
+## Product documentation
+
+The agent setup command adds the local documentation index and skill below.
+If setup was skipped, start with <https://rindle.sh/docs/for-agents.md>.

package/templates/minimal/README.md

@@ -20,10 +20,10 @@ Three tiers, same as the Rindle flagship examples:
   reaches it through TanStack Start **server routes** (`src/routes/api.rindle.{query,read,mutate}.tsx`,
   via `server/rindle-http.ts`) that run in the same server as the app, and SSR calls the very same
   factory **in-process** (no network hop).
-- **Data tier** — the one topology (design 214): a `rindle-replicator` **write-master** plus a
+- **Data tier** — the topology selected by this template: a `rindle-replicator` **write-master** plus a
   `rindled` **read-follower** that owns the live IVM and streams normalized deltas to subscribers.
   Writes land on the master; the follower serves reads. `followers = 1` is the *colocated pair* —
-  both processes on one box, the smallest shape.
+  both processes on one box.
 
 ## SQL is the source of truth
 
@@ -65,7 +65,7 @@ see the rejection path (the optimistic write snaps back + a toast).
 
 ## Deploy
 
-`rindle.ncl` describes the **one topology** — the same file `rindle up` runs locally. To run the
+`rindle.ncl` describes this application’s **data topology** — the same file `rindle up` runs locally. To run the
 **data tier** on Rindle Cloud:
 
 ```bash
@@ -85,6 +85,23 @@ public WebSocket endpoint from that same URL, so there is no browser-side topolo
 the deployment has one follower or many. Set the server-only `RINDLE_WS_URL` override only when a
 host exposes WebSocket ingress at a different origin.
 
+## Coding agents
+
+The default scaffold installs a local documentation snapshot and the Rindle skill.
+`AGENTS.md` contains this application's commands and file map. Its managed block
+and `CLAUDE.md` point to `.rindle/agent-context/index.md`.
+
+After installing or upgrading Rindle packages, run:
+
+```bash
+npx rindle agents setup
+npx rindle agents setup --check
+```
+
+The second command checks the installed files and package versions without writing files.
+If you used `--no-agents`, setup installs the guidance when you need it.
+See [agent setup](https://rindle.sh/docs/for-agents) for the compatibility rules.
+
 ## Devtools
 
 In development a floating **🌊 Rindle** devtools pane is mounted (`src/devtools.tsx`): a live view of the