create-nextly-app 0.0.2-alpha.7 → 0.0.2-alpha.70

package/skills/nextly-deploy/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: nextly-deploy
+description: >-
+  Use when deploying a Nextly project to production, on Vercel or a Node.js
+  server: choosing the production database, creating and committing
+  migrations, running them on deploy, the environment variables Nextly
+  requires, media storage that survives restarts, and checking the live site.
+  Also use when a deployed Nextly app has missing tables, refuses to start,
+  or loses uploaded files.
+metadata:
+  nextly-version: 0.0.2-alpha.70
+---
+
+# Deploy a Nextly project
+
+A Nextly app is a Next.js app, so it deploys wherever Next.js does. What
+Nextly adds: a production database, migrations applied before the new code
+serves traffic, a few environment variables, and media storage that is not
+the local disk on serverless hosts.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4 and PostgreSQL 17:
+the steps below were run end to end, from an empty database to a published
+post in a production build. Run `npx nextly --version`; if it prints a newer
+version, prefer <https://nextlyhq.com/docs/guides/deployment> where it
+disagrees with this skill.
+
+## 1. Pick the production database, and develop on the same kind
+
+Use PostgreSQL (recommended) or MySQL in production; on Vercel, a managed one
+such as Neon, Supabase or Vercel Postgres. SQLite does not survive on
+serverless hosts.
+
+Develop against the same kind of database, and switch **before** creating the
+first migration. `migrate:create` writes SQL in the dialect of the database
+configured when you run it, so migrations made on SQLite will not run on
+PostgreSQL. If SQLite migrations already exist and nothing has been deployed,
+delete `src/db/migrations/` (the `.sql` files and `meta/`) after switching and
+run `migrate:create` again. A live SQLite installation needs its data moved,
+which this skill does not cover.
+
+To switch a project from SQLite to PostgreSQL:
+
+Nextly's packages are released together, so install each `@nextlyhq/*`
+package at exactly the version of `nextly` the project runs, which `npx nextly
+--version` prints:
+
+```bash
+npm install "@nextlyhq/adapter-postgres@$(npx nextly --version)" pg   # pnpm add / yarn add / bun add
+npm ls nextly @nextlyhq/adapter-postgres     # or pnpm ls / yarn why; both at the same version
+```
+
+Use the project's own package manager throughout, so its lockfile stays the
+one that is deployed.
+
+Then, in `.env`, set `DB_DIALECT=postgresql` and `DATABASE_URL` to a local
+PostgreSQL database, and add `"@nextlyhq/adapter-postgres"` and `"pg"` to
+`serverExternalPackages` in `next.config.ts`. Restart `next dev`.
+
+## 2. Create the migrations and commit them
+
+In development, schema changes apply directly. Production only applies
+migration files. Whenever collections change, before deploying:
+
+```bash
+npx nextly migrate:create <what_changed>
+```
+
+It writes `src/db/migrations/<timestamp>_<name>.sql` and a snapshot in
+`src/db/migrations/meta/`. Commit both. Migrations only move forward: to undo
+one, add a new one.
+
+## 3. Run migrations on every deploy
+
+In `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "nextly migrate && next build"
+  }
+}
+```
+
+`nextly migrate` first creates or updates Nextly's own tables (users, roles,
+media and the rest), then applies your pending migrations, against the
+database in `DATABASE_URL`. On an empty database this is all that is needed
+before the first start.
+
+With several developers or preview deploys pointing at one database, run
+`npx nextly migrate` as its own CI step before the deploy instead, and keep
+`build` as `next build`.
+
+## 4. Environment variables
+
+| Variable                 | Value                                                                                                       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------- |
+| `DB_DIALECT`             | `postgresql` or `mysql`                                                                                     |
+| `DATABASE_URL`           | the production database                                                                                     |
+| `NEXTLY_SECRET`          | at least 32 characters, new for production: `openssl rand -base64 32`                                       |
+| `NEXT_PUBLIC_APP_URL`    | the public URL, such as `https://example.com`                                                               |
+| `NEXTLY_ALLOWED_ORIGINS` | only if browsers reach the app on an origin it does not see itself, such as behind a proxy; comma-separated |
+
+`NEXT_PUBLIC_APP_URL` is built into the client bundle, so set it before the
+build. Never commit `.env` files.
+
+## 5. Media storage
+
+Uploads go to `./public/uploads` by default. That is lost on every deploy or
+cold start on Vercel and other serverless hosts. Use a storage adapter,
+installed at the same version as `nextly` as above:
+
+```ts
+// nextly.config.ts, on Vercel: npm install @nextlyhq/storage-vercel-blob@<nextly version>
+import { defineConfig } from "nextly/config";
+import { vercelBlobStorage } from "@nextlyhq/storage-vercel-blob";
+
+export default defineConfig({
+  storage: [
+    vercelBlobStorage({
+      token: process.env.BLOB_READ_WRITE_TOKEN!,
+      collections: { media: true },
+    }),
+  ],
+  // collections, typescript, ...
+});
+```
+
+Vercel sets `BLOB_READ_WRITE_TOKEN` when Blob storage is added to the project.
+For AWS S3, use `@nextlyhq/storage-s3` with
+`s3Storage({ bucket, region, accessKeyId, secretAccessKey, collections: { media: true } })`.
+Other S3-compatible providers also need their `endpoint`, and a `publicUrl`
+when files are served from another address. For Cloudflare R2:
+
+```ts
+s3Storage({
+  bucket: process.env.R2_BUCKET!,
+  region: "auto",
+  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+  publicUrl: process.env.R2_PUBLIC_URL,
+  collections: { media: true },
+});
+```
+
+For other providers, use the settings in the adapter's README. A Node.js
+server with a persistent disk can keep the default.
+
+On Vercel, uploads from the admin pass through a Vercel Function, which
+refuses request bodies over 4.5 MB (`413 FUNCTION_PAYLOAD_TOO_LARGE`). With
+this setup, files above that size cannot be uploaded through the admin; a
+Node.js server has no such limit.
+
+## 6. Plan how the first admin is created
+
+A new production database has no admin. In production, `/admin/setup` does
+not hand the site to whoever opens it first: it asks for a one-time setup
+token. Pick one of these; both refuse once an admin exists.
+
+- **The setup token, after deploying.** Either set your own token before the
+  deploy, as `NEXTLY_SETUP_TOKEN` (at least 43 characters with at least 16
+  distinct ones; `npx nextly setup-token --generate` prints one), or let
+  Nextly generate one: the first production start prints a line beginning
+  `[nextly] SETUP TOKEN` to the server's output (on Vercel, the runtime logs).
+  Then open `/admin/setup` on the live site and enter it. A generated token
+  lasts 24 hours and one setup; `npx nextly setup-token`, run with the
+  production environment, replaces a lost one.
+- **The CLI, before or after deploying.** With the production environment
+  (`DATABASE_URL`, and every other variable the config reads):
+
+  ```bash
+  NEXTLY_ADMIN_PASSWORD='<your password>' \
+    npx nextly users:create-admin --email admin@example.com --name "Site Admin"
+  ```
+
+  Without `NEXTLY_ADMIN_PASSWORD` it prompts for the password at a terminal. The password must be 8 to 128 characters with a lowercase letter, an uppercase letter, a number and a symbol.
+  It needs no token, and it creates nothing if an account already uses that
+  email.
+
+Both need the release after 0.0.2-alpha.68. On an earlier version there is no
+setup token: whoever opens `/admin/setup` first becomes Super Admin, so keep
+the deployment private, behind your host's access protection, until you have
+created the admin there.
+
+Never run `next dev` against the production database. Development mode
+applies schema changes directly to whatever database it points at.
+
+## 7. Deploy
+
+- **Vercel:** import the repository; Next.js is detected. Add the variables
+  above for Production (and Preview, with its own database), then deploy.
+  The `build` script migrates the database during the build.
+- **Node.js server:** install from the lockfile (`npm ci`, `pnpm install
+--frozen-lockfile`, `yarn install --immutable` on Yarn 2+, `yarn install --frozen-lockfile` on
+  Yarn 1, or `bun install --frozen-lockfile`), run the `build` script, then `next start` under a
+  process manager such as systemd, pm2 or Docker. Put a reverse proxy in
+  front that terminates TLS and forwards `Host`, `X-Forwarded-Proto` and
+  `X-Forwarded-For`.
+
+### Behind a proxy, including Vercel
+
+Nextly ignores `X-Forwarded-For` unless told to trust it, and then it cannot
+tell clients apart: every sign-in, registration and password-reset request
+shares one rate-limit bucket, 30 an hour by default, and everyone gets 429
+after that. When every request reaches the app through a proxy that sets
+`X-Forwarded-For` (Vercel does; configure nginx or Caddy to), trust it:
+
+```ts
+// nextly.config.ts
+import { defineConfig } from "nextly/config";
+
+export default defineConfig({
+  security: { trustProxy: true },
+  // collections, typescript, ...
+});
+```
+
+When requests pass through more than one proxy, list the proxies' addresses
+in `TRUSTED_PROXY_IPS` (comma-separated CIDRs), so the client is read from the
+right hop. Do not turn this on for an app clients can reach directly: they
+could then pick their own address.
+
+## 8. Check the live site
+
+- `npx nextly migrate:status`, run against the production `DATABASE_URL`,
+  shows nothing pending.
+- `/admin/setup` says setup is already complete, and `/admin` signs in with
+  the admin created in step 6.
+- Publish an entry and open a page that lists it: it appears.
+- Upload an image in the admin, redeploy, and check it still loads.
+- Do not use `/api/health` as an uptime probe on serverless hosts. It reports
+  503 until Nextly has started in that same process, which a fresh instance
+  that only receives probes never does. Probe a page that reads content
+  instead.
+
+## If something fails
+
+- **Tables missing, or `relation "dc_..." does not exist`:** the migrations
+  were not committed, or `nextly migrate` did not run against this database.
+- **The admin and its API answer 500 in production:** check the server log.
+  `NEXTLY_SECRET of at least 32 characters is required` means the secret is
+  missing or too short, and `NEXT_PUBLIC_APP_URL is required` that the URL is
+  not set.
+- **Sign-in fails with `CSRF_FAILED` behind a proxy:** add the public origin
+  to `NEXTLY_ALLOWED_ORIGINS`.
+- **`next build` fails on a page reading content:** in an app with
+  `cacheComponents: true`, wrap the read in `cachedFind` (the
+  `nextly-collections` skill) or render it inside `<Suspense>`.

package/skills/nextly-install/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: nextly-install
+description: >-
+  Use when adding Nextly, the open-source CMS that runs inside a Next.js app,
+  to an existing Next.js App Router project: installing its packages,
+  creating nextly.config.ts, mounting the admin panel at /admin, choosing a
+  database, and creating the first admin account. Also use when an existing
+  Nextly install shows no collections, fails to load nextly.config.ts, or its
+  admin panel misbehaves after setup.
+metadata:
+  nextly-version: 0.0.2-alpha.70
+---
+
+# Install Nextly into an existing Next.js app
+
+Nextly runs inside the app: same server, same database, no separate service.
+The project generator detects an existing Next.js app and installs Nextly into
+it, including the build approvals, `esbuild` and the routes the admin needs.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version` after installing; if it prints a newer version, prefer
+<https://nextlyhq.com/docs> where it disagrees with this skill.
+
+## Before you start
+
+- Next.js 16.4.1 or later, or 15.5.28 or later on the 15 line, with the App
+  Router (`app/` or `src/app/`). Earlier versions carry the October 2026
+  security advisories these releases fix.
+- Node.js `^22.12.0 || >=24.0.0`. Node 20 and Node 23 are not supported.
+- A clean git working tree, so every change below is visible in one diff.
+
+## 1. Run the generator in the project root
+
+```bash
+npx create-nextly-app@alpha          # npm
+pnpm dlx create-nextly-app@alpha     # pnpm
+yarn dlx create-nextly-app@alpha     # yarn 2 and later
+yarn create nextly-app               # yarn 1 (Classic): no tag; installs `latest`, the current release
+bunx create-nextly-app@alpha         # bun
+```
+
+It finds `next` in `package.json`, asks "Install Nextly in this project?", then
+asks which database and, for PostgreSQL or MySQL, its connection string. `-y`
+skips the questions and uses SQLite at `./data/nextly.db`. `--database
+postgresql` or `--database mysql` picks another; with `-y` as well, `.env` gets
+a placeholder `DATABASE_URL` to replace before starting.
+
+It installs with the app's own package manager (inside a monorepo, the
+workspace's), adding the packages to the app's own `package.json`. On pnpm 10
+and later it approves the native build scripts Nextly needs (`better-sqlite3`,
+`esbuild`, `sharp`) in the setting that pnpm version reads: `pnpm-workspace.yaml`
+from pnpm 10.6, `package.json` before it. In a monorepo the approvals go at the
+workspace root.
+
+Develop on the database you will run in production. Migrations are written in
+the dialect of the database you develop against (the `nextly-deploy` skill),
+and SQLite is not suitable for serverless hosting.
+
+What it changes. It edits `package.json`, the Next config and pnpm's settings
+in place, and adds to `.env` and `.env.example` only the keys they lack. A file
+it would create that the app already has (`nextly.config.ts`,
+`instrumentation.ts`, the admin's files and the routes) is kept as it is and
+reported as skipped, with what Nextly needs in it. Read its report, then review
+the rest in `git diff`:
+
+| File                                           | What                                                                                                                                                 |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `package.json`                                 | `nextly`, `@nextlyhq/admin`, `@nextlyhq/ui`, the database adapter and driver, `@tanstack/react-query`, `lucide-react`; `esbuild` as a dev dependency |
+| `nextly.config.ts`                             | the config the CMS boots from, with empty `collections` and `singles`                                                                                |
+| `next.config.ts`                               | Nextly, the adapter and the driver added to `serverExternalPackages`                                                                                 |
+| `src/instrumentation.ts`                       | starts Nextly when the server starts                                                                                                                 |
+| `src/app/admin/[[...params]]/`                 | the admin panel page and layout                                                                                                                      |
+| `src/app/admin/api/[[...params]]/route.ts`     | the admin API                                                                                                                                        |
+| `src/app/admin/api/media/[[...path]]/route.ts` | the admin's media route, where it uploads and edits media (signed-in only)                                                                           |
+| `src/app/api/media/[[...path]]/route.ts`       | public, read-only media routes                                                                                                                       |
+| `src/app/api/health/route.ts`                  | a health check                                                                                                                                       |
+| `src/types/generated/`                         | where generated types go                                                                                                                             |
+| `.env`, `.env.example`                         | `DB_DIALECT`, `DATABASE_URL`, `NEXTLY_SECRET`, `NEXT_PUBLIC_APP_URL`, for the keys missing                                                           |
+
+Without a `src/` folder the same files go under `app/`, and `instrumentation.ts`
+sits at the project root.
+
+If it reports that it left the Next config alone (a config it cannot change
+safely), add what it prints. The list it needs holds `nextly`,
+`@nextlyhq/adapter-drizzle`, `drizzle-orm`, `drizzle-kit`, `bcryptjs`,
+`sharp`, `esbuild`, and your adapter and driver: `@nextlyhq/adapter-sqlite`
+and `better-sqlite3`, `@nextlyhq/adapter-postgres` and `pg`, or
+`@nextlyhq/adapter-mysql` and `mysql2`.
+
+## 2. Start it and create the first admin
+
+```bash
+npm run dev
+```
+
+Open `http://localhost:3000/admin/setup` and create the first account; it gets
+the Super Admin role. Nextly creates its own tables when the server starts,
+from `instrumentation.ts`; without that hook, on the first request. Then sign in
+at `/admin`. Keep to one address for the admin: a form posted from an origin
+other than the one serving the request is refused, unless that origin is listed
+in `NEXTLY_ALLOWED_ORIGINS`.
+
+## Check it worked
+
+- `/admin` shows the dashboard after signing in.
+- `npx nextly --version` prints the installed version.
+- The dev server log has no `esbuild` error, and `/api/health` answers.
+
+## Doing it by hand
+
+If the generator cannot be used, the manual steps are at
+<https://nextlyhq.com/docs/getting-started/installation> (option B). They
+include the pnpm build approvals, `esbuild` and the admin's media route, which
+the generator otherwise adds for you.
+
+## Next
+
+- Define content: the `nextly-collections` skill.
+- Who can sign in and what they can do: the `nextly-authentication` skill.
+- Going live: the `nextly-deploy` skill.
+- Every docs page, for agents: <https://nextlyhq.com/llms.txt>.

package/templates/base/.env.example

@@ -5,12 +5,27 @@
 DB_DIALECT={{databaseDialect}}
 DATABASE_URL={{databaseUrl}}
 
-# Authentication (REQUIRED)
-# Generate with: openssl rand -base64 32
-NEXTLY_SECRET=change-me-generate-a-secure-secret
+# Authentication (REQUIRED): a random secret of at least 32 characters, for
+# example from `openssl rand -base64 32`. The real one goes in .env, never here.
+NEXTLY_SECRET=
 
-# Application URL
+# Where the Nextly app itself lives: the admin, the API, and the origin its
+# emails and preview links point at.
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 
-# Storage Configuration
-{{storageEnvVars}}
+# Where READERS find the public site. Used for canonical links, Open Graph
+# tags, the sitemap and RSS. Set it when the public site is served from a
+# different origin than the app above; otherwise the app's origin is used.
+# NEXT_PUBLIC_SITE_URL=https://example.com
+
+# Development diagnostics (opt-in)
+# Uncomment to add a _devDiagnostics field to error responses, carrying the
+# error's log context and the underlying cause, so a failure names itself while
+# you build instead of only in the server log.
+#
+# Left commented on purpose. It is the SECOND of two independent signals — the
+# first is NODE_ENV — and the second exists precisely because NODE_ENV is a
+# runtime value a deployment can carry by mistake. A default that ships in this
+# file would be true in exactly that case, which is the one it guards against.
+# NEXTLY_DEV_DIAGNOSTICS=1
+

package/templates/base/AGENTS.md.template

@@ -0,0 +1,226 @@
+<!-- nextly:managed:start -->
+<!--
+  Everything between these markers is generated by create-nextly-app and may be
+  replaced when the project is upgraded. Write your own notes OUTSIDE the block:
+  anything above or below it is yours and is preserved.
+-->
+
+# Agent guide for this Nextly project
+
+A Next.js app with [Nextly](https://nextlyhq.com) for content. The CMS runs
+inside this app rather than beside it: same server, same database, no separate
+service to start.
+
+## Where things are
+
+| path                   | what it is                                                         |
+| ---------------------- | ------------------------------------------------------------------ |
+| `nextly.config.ts`     | the config the whole app boots from — collections, database, admin |
+| `src/collections/`     | code-first collection definitions, when this project uses them     |
+| `src/app/(frontend)/`  | the public site                                                    |
+| `src/app/admin/`       | the admin panel, served at `/admin`                                |
+| `migrations/`          | SQL migrations, in this project's dialect                          |
+| `src/types/generated/` | generated types — never edit by hand                               |
+
+## Commands
+
+```bash
+{{runCommand}} dev                  # start Next.js; schema changes apply in-process
+{{runCommand}} build                # migrate, then build
+{{runCommand}} db:setup             # first run: create the schema
+{{runCommand}} db:migrate           # apply pending migrations
+{{runCommand}} db:migrate:status    # what has and has not been applied
+{{runCommand}} db:migrate:fresh     # drop everything and re-run (destructive)
+{{runCommand}} types:generate       # regenerate types after a schema change
+```
+
+This project uses **{{databaseDialect}}**.
+
+## Reading content
+
+Content is read through the Direct API, on the server:
+
+```ts
+import { getNextly } from "nextly";
+import nextlyConfig from "@nextly-config";
+
+const nextly = await getNextly({ config: nextlyConfig });
+const posts = await nextly.find({ collection: "posts", limit: 10 });
+```
+
+**`find()` returns loosely-typed documents until types are generated.** Without
+`{{runCommand}} types:generate`, `posts.items` is `Record<string, unknown>[]` and a
+field access is `unknown`. Generating types makes the slug and the return type
+infer, so `posts.items` becomes `Post[]`.
+
+Until then, narrow with a runtime check rather than an assertion — a document
+missing a field yields `undefined`, and asserting the type only moves the
+failure to where the value is used:
+
+```ts
+const slug = typeof doc.slug === "string" ? doc.slug : undefined;
+```
+
+## Things that surprise people
+
+- **Users are not a normal collection.** Read them through `nextly.users`, not
+  `find({ collection: "users" })`. The users namespace supports pagination and
+  `search`; it does not support a `where` filter.
+- **A migration you generate is one file, in THIS project's dialect.**
+  `{{execCommand}} nextly migrate:create <name>` (no package.json script exists for it) writes a
+  single `migrations/<timestamp>_<slug>.sql` containing **{{databaseDialect}}**
+  SQL — no `.mysql.sql` or `.sqlite.sql` beside it. Edit that file.
+- **A suffixed set means the migration was shipped, not generated.** A template
+  that supports every dialect ships `0001_x.sql` (Postgres) alongside
+  `0001_x.mysql.sql` and `0001_x.sqlite.sql`, and the CLI runs the variant for
+  the configured dialect. Those are prebuilt. Adding companion variants to a
+  migration you generated is not part of the normal workflow, and nothing will
+  run them unless this project is itself meant to support several dialects.
+- **The admin needs a first user.** Visit `/admin` after `{{runCommand}} dev` and
+  complete the setup screen.
+- **Cache tags come from `nextly/runtime`.** Wrap PUBLIC reads in `cachedFind`
+  and tag them with `nextlyTags(collection)` so a write invalidates the right
+  pages.
+
+  **`keyParts` is a security boundary, not a performance detail.** Two callers
+  whose `keyParts` match share one cache entry. So if the read applies any
+  per-caller rule — a code-defined `access.read` that reads the caller's
+  roles or permissions, an API key's narrowed scope — the caller's identity
+  has to be IN the key, or one user's rows get served to another:
+
+  **A shared cache entry is only safe if the read is public for EVERY reader.**
+  Two independent things can make it not so, and each needs its own answer:
+
+  - **drafts** — `find()` defaults to `overrideAccess: true`, a trusted server
+    read, so a slug filter alone can return an unpublished row. `status:
+    "published"` is enforced even on a trusted read and fixes this one.
+  - **access rules** — a code-defined `access.read` on the collection that
+    decides on the caller (their roles, their permissions, whether they are
+    signed in at all), or an API key's narrowed scope. `status` does NOT
+    evaluate these; it is a draft/published lifecycle filter and nothing more.
+    A published row that only some readers may see is still returned by the
+    query above.
+
+  - **field-level read rules** — a field can carry its own `access.read` even
+    when the collection declares none. The shared branch below reads with the
+    Direct API's default `overrideAccess: true`, which bypasses field rules
+    too, so the cached row holds every field and the entry serves fields the
+    schema meant to redact. A collection with ANY field-level read rule takes
+    the per-caller branch — or selects only fields known to be public.
+
+  So the decision is: **does this collection declare a read rule, on the
+  collection or on any of its fields?**
+
+  ```ts
+  import { cachedFind, nextlyTags } from "nextly/runtime";
+
+  // NO read rule, on the collection OR its fields — the result is identical for
+  // every reader, so one shared entry is correct and gets the full ISR benefit.
+  // `find()` always returns the list envelope `{ items, meta }`, so a detail route takes the
+  // first item — and caches THAT, not the envelope around it.
+  cachedFind(
+    async () =>
+      (
+        await nextly.find({
+          collection: "posts",
+          where: { slug: { equals: slug } },
+          status: "published",
+          limit: 1,
+        })
+      ).items[0] ?? null,
+    { tags: nextlyTags("posts"), keyParts: ["posts", slug] }
+  );
+
+  // A READ RULE — evaluate it as the caller, and key by EVERY dimension the
+  // rule reads, not just who the caller is.
+  //
+  // Both role fields are optional and Nextly reads BOTH: the many-to-many
+  // `roles` unioned with the singular `role`. Deduped and sorted, so one role
+  // set spelled two ways is one cache entry rather than two.
+  const roleKey = (u: { role?: string; roles?: string[] }) =>
+    [...new Set([...(u.roles ?? []), u.role ?? []].flat())].sort().join(",");
+
+  cachedFind(
+    () => nextly.find({ collection: "orders", user, overrideAccess: false }),
+    {
+      tags: nextlyTags("orders"),
+      keyParts: ["orders", "list", user.id, roleKey(user)],
+    }
+  );
+  ```
+
+  **`user.id` alone is not the authorization context.** Roles change, custom
+  claims change, an API key's scope is narrower than its owner's. A key built
+  from identity alone survives all of those, so the same person can fill the
+  entry while privileged and read it back after being downgraded — the tags bust
+  on CONTENT changes, and a permission change is not one. Include whatever the
+  rules actually read: the role set, the claim, the key's scope.
+
+  If you are unsure whether a collection or any of its fields declares a read
+  rule, do not cache it. A missing cache is slow; a shared one leaks.
+
+## Which Nextly this is, and where its docs are
+
+An agent working here will otherwise answer from whatever it remembers of some
+other version. Ask the project instead:
+
+```bash
+{{execCommand}} nextly --version      # the running core version
+```
+
+That is the same version the plugin resolver validates a plugin's `nextly`
+range against, so a compatibility answer and a reported version cannot
+disagree. The dependency range this project pins is in `package.json` under
+`nextly`; the resolved version is what the command above prints.
+
+**The authoritative documentation is <https://nextlyhq.com/docs>.** Two files
+are published for machine readers and are the ones to fetch:
+
+| file | what it is |
+| ---- | ---------- |
+| <https://nextlyhq.com/llms.txt> | the index — every documentation page, with a one-line summary |
+| <https://nextlyhq.com/llms-full.txt> | the same documentation as one file |
+
+Both are generated from the pages the site publishes, so they cannot describe a
+page that does not exist. Neither is version-stamped: they describe the CURRENT
+release, so check the version above before trusting a detail against an older
+pin.
+
+## Skills for Nextly tasks
+
+If this project has `.agents/skills/`, it holds skills for common Nextly
+tasks, and `.claude/skills/` holds the same files for Claude Code. Load the
+one that matches a task before starting it. They were written for the Nextly
+release this project was created with.
+
+Each skill names the Nextly release it was checked against in its
+frontmatter, as `metadata.nextly-version`. The command below installs skills
+written for `{{skillsVersion}}`. Restore them as they were released only when
+`.agents/skills/nextly-install/SKILL.md` exists, its `metadata.nextly-version`
+is exactly `{{skillsVersion}}`, and `{{execCommand}} nextly --version` prints
+exactly `{{skillsVersion}}`:
+
+```bash
+npx skills add 'nextlyhq/nextly#v{{skillsTag}}' --skill '*' --agent claude-code codex cursor --copy -y
+```
+
+It rewrites both folders, so edits made to a skill there are replaced.
+`{{skillsTag}}` is the release of `create-nextly-app` that made this project,
+whose tag publishes these skills. Releases up to 0.0.2-alpha.66 publish no
+skills for building apps: installing from one of those tags brings the skills
+Nextly's own contributors use, so never put an older version in its place.
+
+Otherwise, with no skills or with skills for a different release than this
+project runs, do not run the command above: it would install skills written
+for another release. See <https://nextlyhq.com/docs/guides/coding-agents> for
+skills that match.
+
+## Conventions worth keeping
+
+- Server components read content directly; do not build an API route to fetch
+  your own content.
+- Regenerate types in the same change as the schema edit that needs them.
+- Migrations are append-only once shared. Add a new one rather than editing an
+  applied file.
+
+<!-- nextly:managed:end -->

package/templates/base/CLAUDE.md.template

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/base/gitignore

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts