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

package/dist/index.d.cts

@@ -1,8 +1,9 @@
 /**
  * Project type / template selection.
  * "blog" is the first content template added for alpha.
+ * "plugin" scaffolds a publishable Nextly plugin package + embedded /dev playground (D44/D45).
  */
-type ProjectType = "blank" | "blog";
+type ProjectType = "blank" | "blog" | "plugin";
 /**
  * Schema approach selection for content templates.
  * - code-first: Full schema definitions in nextly.config.ts (like Payload CMS)
@@ -18,37 +19,42 @@ type DatabaseType = "postgresql" | "mysql" | "sqlite";
  * Options for createNextly function
  */
 interface CreateNextlyOptions {
-    /** Working directory (defaults to process.cwd()) */
-    cwd?: string;
-    /** Skip interactive prompts and use defaults */
-    defaults?: boolean;
-    /** Pre-selected project type / template name */
-    projectType?: ProjectType;
-    /** Pre-selected database type */
-    database?: DatabaseType;
-    /** Skip dependency installation (useful for local testing before packages are published) */
-    skipInstall?: boolean;
-    /** Use yalc for local package installation (for testing before npm publish) */
-    useYalc?: boolean;
-    /**
-     * Project name derived from the CLI's positional `[directory]` argument.
-     * Must be a bare directory name (no slashes). Callers pass the basename
-     * of the user-provided argument.
-     */
-    projectNameFromArg?: string;
-    /**
-     * When true, the CLI was invoked with "." meaning "install in current directory".
-     * Different from projectNameFromArg which creates a subdirectory.
-     */
-    installInCwd?: boolean;
-    /** Schema approach for content templates (code-first, visual) */
-    approach?: ProjectApproach;
-    /** Path to local templates directory (for development, bypasses GitHub download) */
-    localTemplatePath?: string;
-    /** Git branch for template download from GitHub (defaults to "main") */
-    branch?: string;
+  /** Working directory (defaults to process.cwd()) */
+  cwd?: string;
+  /** Skip interactive prompts and use defaults */
+  defaults?: boolean;
+  /** Pre-selected project type / template name */
+  projectType?: ProjectType;
+  /** Pre-selected database type */
+  database?: DatabaseType;
+  /** Skip dependency installation (useful for local testing before packages are published) */
+  skipInstall?: boolean;
+  /** Use yalc for local package installation (for testing before npm publish) */
+  useYalc?: boolean;
+  /**
+   * Project name derived from the CLI's positional `[directory]` argument.
+   * Must be a bare directory name (no slashes). Callers pass the basename
+   * of the user-provided argument.
+   */
+  projectNameFromArg?: string;
+  /**
+   * When true, the CLI was invoked with "." meaning "install in current directory".
+   * Different from projectNameFromArg which creates a subdirectory.
+   */
+  installInCwd?: boolean;
+  /** Schema approach for content templates (code-first, visual) */
+  approach?: ProjectApproach;
+  /** Path to local templates directory (for development, bypasses GitHub download) */
+  localTemplatePath?: string;
+  /** Git branch to take a template from; unset, it comes from this CLI's release */
+  branch?: string;
+  /**
+   * Whether to add the Nextly skills for coding agents to the project.
+   * False skips them without asking; otherwise the developer is asked, and
+   * defaults mode adds them.
+   */
+  skills?: boolean;
 }
-
 /**
  * Main entry point for scaffolding Nextly in a Next.js project.
  *
@@ -64,6 +70,6 @@ interface CreateNextlyOptions {
  * 5. Database selection (sqlite, postgresql, mysql)
  * 6. Database connection string (only for postgresql/mysql)
  */
-declare function createNextly(options?: CreateNextlyOptions): Promise<void>;
-
-export { type CreateNextlyOptions, createNextly };
+export declare function createNextly(options?: CreateNextlyOptions): Promise<void>;
+export type { CreateNextlyOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * Project type / template selection.
  * "blog" is the first content template added for alpha.
+ * "plugin" scaffolds a publishable Nextly plugin package + embedded /dev playground (D44/D45).
  */
-type ProjectType = "blank" | "blog";
+type ProjectType = "blank" | "blog" | "plugin";
 /**
  * Schema approach selection for content templates.
  * - code-first: Full schema definitions in nextly.config.ts (like Payload CMS)
@@ -18,37 +19,42 @@ type DatabaseType = "postgresql" | "mysql" | "sqlite";
  * Options for createNextly function
  */
 interface CreateNextlyOptions {
-    /** Working directory (defaults to process.cwd()) */
-    cwd?: string;
-    /** Skip interactive prompts and use defaults */
-    defaults?: boolean;
-    /** Pre-selected project type / template name */
-    projectType?: ProjectType;
-    /** Pre-selected database type */
-    database?: DatabaseType;
-    /** Skip dependency installation (useful for local testing before packages are published) */
-    skipInstall?: boolean;
-    /** Use yalc for local package installation (for testing before npm publish) */
-    useYalc?: boolean;
-    /**
-     * Project name derived from the CLI's positional `[directory]` argument.
-     * Must be a bare directory name (no slashes). Callers pass the basename
-     * of the user-provided argument.
-     */
-    projectNameFromArg?: string;
-    /**
-     * When true, the CLI was invoked with "." meaning "install in current directory".
-     * Different from projectNameFromArg which creates a subdirectory.
-     */
-    installInCwd?: boolean;
-    /** Schema approach for content templates (code-first, visual) */
-    approach?: ProjectApproach;
-    /** Path to local templates directory (for development, bypasses GitHub download) */
-    localTemplatePath?: string;
-    /** Git branch for template download from GitHub (defaults to "main") */
-    branch?: string;
+  /** Working directory (defaults to process.cwd()) */
+  cwd?: string;
+  /** Skip interactive prompts and use defaults */
+  defaults?: boolean;
+  /** Pre-selected project type / template name */
+  projectType?: ProjectType;
+  /** Pre-selected database type */
+  database?: DatabaseType;
+  /** Skip dependency installation (useful for local testing before packages are published) */
+  skipInstall?: boolean;
+  /** Use yalc for local package installation (for testing before npm publish) */
+  useYalc?: boolean;
+  /**
+   * Project name derived from the CLI's positional `[directory]` argument.
+   * Must be a bare directory name (no slashes). Callers pass the basename
+   * of the user-provided argument.
+   */
+  projectNameFromArg?: string;
+  /**
+   * When true, the CLI was invoked with "." meaning "install in current directory".
+   * Different from projectNameFromArg which creates a subdirectory.
+   */
+  installInCwd?: boolean;
+  /** Schema approach for content templates (code-first, visual) */
+  approach?: ProjectApproach;
+  /** Path to local templates directory (for development, bypasses GitHub download) */
+  localTemplatePath?: string;
+  /** Git branch to take a template from; unset, it comes from this CLI's release */
+  branch?: string;
+  /**
+   * Whether to add the Nextly skills for coding agents to the project.
+   * False skips them without asking; otherwise the developer is asked, and
+   * defaults mode adds them.
+   */
+  skills?: boolean;
 }
-
 /**
  * Main entry point for scaffolding Nextly in a Next.js project.
  *
@@ -64,6 +70,6 @@ interface CreateNextlyOptions {
  * 5. Database selection (sqlite, postgresql, mysql)
  * 6. Database connection string (only for postgresql/mysql)
  */
-declare function createNextly(options?: CreateNextlyOptions): Promise<void>;
-
-export { type CreateNextlyOptions, createNextly };
+export declare function createNextly(options?: CreateNextlyOptions): Promise<void>;
+export type { CreateNextlyOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.mjs

@@ -1,6 +1 @@
-import { createRequire } from 'module';
-export { createNextly } from './chunk-RPGFJSDP.mjs';
-
-createRequire(import.meta.url);
-//# sourceMappingURL=index.mjs.map
-//# sourceMappingURL=index.mjs.map
+export { t as createNextly } from "./create-nextly-5wiGMVI6.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextly-app",
-  "version": "0.0.2-alpha.7",
+  "version": "0.0.2-alpha.71",
   "description": "CLI to scaffold Nextly in your Next.js project",
   "license": "MIT",
   "type": "module",
@@ -20,34 +20,45 @@
   "files": [
     "dist",
     "bin",
+    "skills",
     "templates"
   ],
   "dependencies": {
+    "@babel/parser": "^7.29.7",
     "@clack/prompts": "^1.1.0",
     "commander": "^14.0.2",
+    "dotenv-expand": "10.0.0",
     "execa": "^9.6.0",
     "fs-extra": "^11.3.0",
-    "ora": "^9.0.0",
     "picocolors": "^1.1.1",
-    "tar": "^7.4.0"
+    "picomatch": "^4.0.5",
+    "tar": "^7.5.19",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
+    "@babel/types": "^7.29.7",
+    "@nextlyhq/eslint-plugin": "0.0.2-alpha.71",
+    "@nextlyhq/module-specifiers": "0.0.2-alpha.71",
+    "@nextlyhq/telemetry": "0.0.2-alpha.71",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.71",
+    "@testing-library/react": "^16.3.0",
     "@types/fs-extra": "^11.0.4",
+    "@types/node": "^22.20.5",
+    "@types/picomatch": "^4.0.3",
     "@types/tar": "^6.1.13",
-    "@types/node": "^20.19.17",
-    "@vitest/coverage-v8": "^4.0.8",
-    "@vitest/ui": "^4.0.8",
-    "eslint": "^9.34.0",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
+    "@vitest/coverage-v8": "^5.0.5",
+    "@vitest/ui": "^5.0.5",
+    "jsdom": "^27.1.0",
+    "oxc-parser": "^0.155.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "tsdown": "^0.23.1",
+    "typescript": "7.0.2",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.8",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.6",
-    "@nextlyhq/telemetry": "0.0.2-alpha.6",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.6"
+    "vitest": "^5.0.5"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": "^22.12.0 || >=24.0.0"
   },
   "keywords": [
     "nextly",
@@ -74,11 +85,9 @@
   },
   "author": "Nextly <contact@nextlyhq.com> (https://nextlyhq.com)",
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "check-types": "tsc --noEmit",
-    "lint": "eslint . --max-warnings 0",
-    "lint:fix": "eslint . --fix",
+    "build": "tsdown --config-loader tsx",
+    "dev": "tsdown --config-loader tsx --watch",
+    "check-types": "node ../../scripts/tsc.mjs --noEmit && node ../../scripts/tsc.mjs --noEmit -p tsconfig.tests.json",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
     "clean": "rimraf dist"

package/skills/nextly-authentication/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: nextly-authentication
+description: >-
+  Use when deciding who can sign in to a Nextly project and what they can do:
+  the first admin account, roles, access rules on collections, API keys for
+  other apps and scripts, checking the signed-in user in your own server
+  code, and extra fields on users. Also use when asked to add login or
+  sign-up to a Nextly site, so the answer matches what Nextly provides.
+metadata:
+  nextly-version: 0.0.2-alpha.71
+---
+
+# Authentication and access in Nextly
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version`; if it prints a newer version, prefer
+<https://nextlyhq.com/docs/guides/authentication> where it disagrees with this
+skill.
+
+## What is built in, and what is not
+
+Nextly has its own email and password sign-in for the **people who run the
+site**: admins, editors and authors who use the admin panel at `/admin`. It is
+not built on NextAuth or any OAuth library, and it needs no setup beyond
+`NEXTLY_SECRET`.
+
+Its session cookies are scoped to `/admin`. So in this release Nextly does
+**not** provide sign-in for the visitors of your public site, nor social or
+OAuth login. If the site needs visitor accounts, use an auth library for the
+site and keep Nextly for content; do not try to reuse the admin sign-in for
+visitors.
+
+In particular, do not build a sign-in form for your own pages on the Direct
+API's `nextly.login()`. It is for trusted server code, not for signing people
+in, and this release has no ready path for members-only pages. Protect those
+with the auth library the site uses.
+
+## The secret
+
+`NEXTLY_SECRET` signs the session tokens. The installer generates one in
+`.env`. In production it must be at least 32 characters; generate one with:
+
+```bash
+openssl rand -base64 32
+```
+
+Never commit it, and use a different one per environment.
+
+## The first admin
+
+Open `/admin/setup` once and create the first account. It gets the **Super
+Admin** role, which passes every check. After that, setup is closed, and people
+are added in the admin under **Users**. Under `next dev` the form needs nothing
+else.
+
+In production (from the release after 0.0.2-alpha.68), the form also asks for a
+one-time setup token: `NEXTLY_SETUP_TOKEN` if you set one (at least 43
+characters, 16 distinct), or the one printed to the server's output on a line
+beginning `[nextly] SETUP TOKEN`. Or skip the browser and run
+`npx nextly users:create-admin --email <email> --name <name>` with the
+production environment, the password in `NEXTLY_ADMIN_PASSWORD` or typed at the
+prompt. Self-registration (`auth.allowRegistration`, off by default) never
+creates an admin.
+
+Built-in roles: `super-admin`, `admin`, `editor`, `author`, `viewer`. Roles and
+their permissions are managed in the admin under **Settings > Roles**.
+
+## Access rules on a collection
+
+Each operation takes `true`, `false` or a function. A function receives
+`{ user, roles, permissions, operation, collection }`, where `roles` are role
+slugs such as `"editor"` and `user` is `null` for a request with no session.
+
+```ts
+import { defineCollection, text } from "nextly/config";
+import type { AccessControlFunction } from "nextly";
+
+const signedIn: AccessControlFunction = ({ user }) => Boolean(user);
+const editors: AccessControlFunction = ({ roles }) =>
+  roles.includes("admin") || roles.includes("editor");
+
+export const Articles = defineCollection({
+  slug: "articles",
+  fields: [text({ name: "title", required: true })],
+  access: {
+    read: () => true,
+    create: signedIn,
+    update: editors,
+    delete: editors,
+  },
+});
+```
+
+- A Super Admin passes every rule; test rules with another role.
+- These rules are applied to requests to the admin API and to Direct API
+  reads made with `overrideAccess: false`. A plain server-side
+  `nextly.find(...)` is a trusted read that skips them.
+- `read: () => true` does not make the admin API public. Every request to
+  `/admin/api/...` needs a session or an API key, and is refused with 401
+  otherwise. Public pages read content on the server with `getNextly` (the
+  `nextly-collections` skill).
+
+To apply the rules for a particular user in server code:
+
+```ts
+const result = await nextly.find({
+  collection: "articles",
+  overrideAccess: false,
+  user: { id: userId },
+});
+```
+
+## API keys, for other apps and scripts
+
+Create keys in the admin under **Settings > API Keys**. The full key is shown
+once. Send it as a bearer token:
+
+```bash
+curl -H "Authorization: Bearer $NEXTLY_API_KEY" \
+  "https://example.com/admin/api/collections/posts/entries?limit=10"
+```
+
+A **Read-only** key can read and is refused writes (403). **Full access**
+carries its creator's permissions; **Role-based** carries the permissions of a
+role you choose. Keys can expire and be revoked. Keep keys in environment
+variables, never in client code.
+
+## The signed-in user in your own server code
+
+```ts
+// src/app/admin/me/route.ts: the session cookie only reaches /admin paths
+import { getNextly } from "nextly";
+import { getSession, isSuperAdmin } from "nextly/auth";
+
+import nextlyConfig from "../../../../nextly.config";
+
+export async function GET(request: Request) {
+  // Start Nextly first: this route may be the first request a server handles.
+  await getNextly({ config: nextlyConfig });
+  const session = await getSession(request, process.env.NEXTLY_SECRET ?? "");
+  if (!session.authenticated) {
+    return Response.json({ error: "Not signed in" }, { status: 401 });
+  }
+  return Response.json({
+    email: session.user.email,
+    superAdmin: await isSuperAdmin(session.user.id),
+  });
+}
+```
+
+- The route must live under `/admin`, or the browser never sends the session
+  cookie to it.
+- `session.user.roleIds` holds role **IDs**, not role slugs, so
+  `hasRole(user, "editor")` from `nextly/auth` does not match by slug in this
+  release. Use `isSuperAdmin(user.id)`, or put role decisions in collection
+  access rules, where `roles` are slugs.
+
+## Extra fields on users
+
+```ts
+import { defineConfig, text, textarea } from "nextly/config";
+
+export default defineConfig({
+  users: {
+    fields: [
+      textarea({ name: "bio", maxLength: 500 }),
+      text({ name: "avatarUrl" }),
+    ],
+  },
+  // collections, typescript, ...
+});
+```
+
+Read users with `nextly.users.find()`, not `find({ collection: "users" })`.
+
+## Password reset and verification emails
+
+These need an email provider. Without one, tokens come back in the API
+response as a development fallback. See
+<https://nextlyhq.com/docs/guides/email>.
+
+## Check it worked
+
+- `/admin/setup` creates the first account, and `/admin` signs in.
+- A request to `/admin/api/collections/<slug>/entries` without a session or
+  key answers 401.
+- A read-only API key reads entries and gets 403 on a write.

package/skills/nextly-collections/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: nextly-collections
+description: >-
+  Use when defining or changing content types in a Nextly project in code:
+  writing a collection with defineCollection, choosing field types, adding
+  draft and published status, registering it in nextly.config.ts, generating
+  TypeScript types, creating a migration, and reading entries from a Next.js
+  Server Component with getNextly and find. Also use when a collection does
+  not appear in the admin, a field change does not reach the database, or a
+  page reading content fails to build.
+metadata:
+  nextly-version: 0.0.2-alpha.71
+---
+
+# Define a collection in Nextly
+
+A collection is a content type with many entries: posts, products, authors.
+Each one becomes a database table, an admin list and edit screen, and a type
+you can query. Collections can also be made in the admin's visual Schema
+Builder; this skill covers the code-first way.
+
+Checked against `nextly` 0.0.2-alpha.67 with Next.js 16.4. Run
+`npx nextly --version`; if it prints a newer version, prefer
+<https://nextlyhq.com/docs> where it disagrees with this skill. Nextly must
+already be installed (the `nextly-install` skill), with `esbuild` among the
+dev dependencies.
+
+## 1. Write the collection
+
+`src/collections/posts.ts`:
+
+```ts
+import {
+  defineCollection,
+  text,
+  textarea,
+  richText,
+  date,
+  select,
+} from "nextly/config";
+
+export const Posts = defineCollection({
+  slug: "posts",
+  labels: { singular: "Post", plural: "Posts" },
+  fields: [
+    text({ name: "title", required: true }),
+    text({ name: "slug", required: true, unique: true }),
+    textarea({ name: "excerpt" }),
+    richText({ name: "content" }),
+    date({ name: "publishedAt" }),
+    select({
+      name: "category",
+      options: [
+        { label: "News", value: "news" },
+        { label: "Guide", value: "guide" },
+      ],
+    }),
+  ],
+  // Draft and Published, with Save draft and Publish buttons in the admin.
+  status: true,
+  admin: { useAsTitle: "title" },
+  access: {
+    read: () => true,
+    create: ({ user }) => Boolean(user),
+    update: ({ user }) => Boolean(user),
+    delete: ({ roles }) => roles.includes("admin"),
+  },
+});
+```
+
+Rules that matter:
+
+- Import from `nextly/config` in collection files and in `nextly.config.ts`.
+- Use **relative imports** in these files, never the `@/` alias. The Nextly
+  CLI loads them with Node.js, which does not know Next.js aliases.
+- `slug` is the table and API name: lowercase, stable. Renaming it later is a
+  migration, not an edit.
+- `id`, `createdAt` and `updatedAt` are added for you; do not declare them.
+  Declare `title` and `slug` yourself, as above, or the admin shows no input
+  for them and the slug is not unique. The admin fills an empty `slug` from
+  the title.
+- Field helpers in this release: `text`, `textarea`, `richText`, `email`,
+  `password`, `code`, `number`, `checkbox`, `date`, `select`, `radio`,
+  `chips`, `upload`, `relationship`, `repeater`, `array`, `group`, `json`.
+  `relationship({ name: "author", relationTo: "users" })` links entries;
+  add `hasMany: true` for several. `upload({ name: "image", relationTo: "media" })`
+  links a media file.
+- Access rules are explained in the `nextly-authentication` skill.
+
+## 2. Register it
+
+`nextly.config.ts`:
+
+```ts
+import { defineConfig } from "nextly/config";
+
+import { Posts } from "./src/collections/posts";
+
+export default defineConfig({
+  collections: [Posts],
+  singles: [],
+  typescript: {
+    outputFile: "./src/types/generated/nextly-types.ts",
+  },
+});
+```
+
+## 3. Apply it in development
+
+Restart `next dev` after adding or changing a collection. The change is
+applied to the development database on the first request after the restart:
+the log says `Code-first sync completed`. On Next.js 16.4 the in-process
+reload does not pick up a changed field without a restart.
+
+Then open `/admin`: the collection is in the sidebar, with list and create
+screens.
+
+## 4. Generate types
+
+```bash
+npx nextly generate:types
+```
+
+This writes the file named in `typescript.outputFile`, and Zod schemas under
+`src/db/schemas/collections/zod/` (`db/schemas/collections/zod/` without a
+`src/` folder). With them, `find({ collection: "posts" })` is typed; without
+them, entries are loosely typed and fields read as `unknown`. Regenerate in
+the same change as every schema edit.
+
+The Zod schemas import `z` from `nextly/zod`, so the project needs no `zod`
+dependency of its own. To combine them with your own Zod code, import `z`
+from `nextly/zod` there too.
+
+## 5. Read entries in a page
+
+Content is read on the server with the Direct API. Do not build an API route
+to fetch your own content.
+
+```tsx
+// src/app/posts/page.tsx
+import { getNextly } from "nextly";
+import { cachedFind, nextlyTags } from "nextly/runtime";
+
+import nextlyConfig from "../../../nextly.config";
+
+async function getPublishedPosts() {
+  return cachedFind(
+    async () => {
+      const nextly = await getNextly({ config: nextlyConfig });
+      const { items } = await nextly.find({
+        collection: "posts",
+        status: "published",
+        limit: 10,
+      });
+      return items;
+    },
+    { tags: nextlyTags("posts"), keyParts: ["posts", "list"] }
+  );
+}
+
+export default async function PostsPage() {
+  const posts = await getPublishedPosts();
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={String(post.id)}>{String(post.title)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+- Without a `src/` folder the page is `app/posts/page.tsx`, importing
+  `"../../nextly.config"`.
+- `find()` returns `{ items, meta }`. `meta` holds the totals and pages.
+- `status: "published"` keeps drafts off the page. Without it a trusted
+  server read returns drafts too.
+- `cachedFind` with `nextlyTags("posts")` caches the result and clears it when
+  a post is saved, so the page updates on publish. It also lets the page build
+  in an app with `cacheComponents: true`, where an uncached database read
+  outside `<Suspense>` fails `next build`.
+- `keyParts` names the cache entry, and everyone whose read uses the same key
+  gets the same rows. Cache only reads that are the same for every reader:
+  published content of a collection with no read rule, on the collection or
+  on any of its fields. Do not cache a read that applies a reader's access
+  rules (`overrideAccess: false` with a `user`): the reader's roles and
+  permissions can change without any content changing, so no tag clears the
+  entry. Read it uncached inside `<Suspense>` instead.
+- Rich text comes back as Lexical JSON. Pass `richTextFormat: "html"` to
+  `find()` to get HTML instead.
+- Users are not a normal collection: read them with `nextly.users.find()`,
+  which supports pagination and `search` but not `where`.
+
+## 6. Make a migration before deploying
+
+Development applies changes directly; production applies migration files.
+When the change is ready to ship:
+
+```bash
+npx nextly migrate:create add_posts
+```
+
+This compares the config with the last migration's snapshot and writes
+`src/db/migrations/<timestamp>_add_posts.sql` plus a snapshot under
+`src/db/migrations/meta/`. Read the SQL, then commit both with the config
+change. `npx nextly migrate` applies pending migrations; the `nextly-deploy`
+skill runs it on every deploy. Once a migration is shared, never edit it: add
+a new one.
+
+## Check it worked
+
+- The admin lists the collection and saves an entry.
+- `npx nextly generate:types` succeeds and `npx tsc --noEmit` is clean.
+- The page shows a published entry, and a draft does not appear.
+- `next build` succeeds.