@quickback-dev/cli 0.66.22 → 0.66.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -23,9 +23,9 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
23
23
  | Template | Includes | Command |
24
24
  |----------|----------|---------|
25
25
  | `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
26
- | `todos` | Working todos feature: schema, masking, two actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
26
+ | `todos` | Working todos feature: schema, masking, two transitions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
27
27
 
28
- The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
28
+ The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus transitions and views in ~80 lines you can scan in five minutes.
29
29
 
30
30
  ### Fixed-org starter
31
31
 
@@ -70,7 +70,7 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
70
70
 
71
71
  ### Todos (recommended for newcomers)
72
72
 
73
- Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
73
+ Best for learning by reading. Full multi-tenant security pillars, two transitions (`complete` / `uncomplete`), a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
74
74
 
75
75
  ### Blog (pinned-organization CMS)
76
76
 
@@ -45,8 +45,15 @@ Add to your AI tool's MCP config:
45
45
 
46
46
  ### Available Tools
47
47
 
48
+ The server is a harness, not just a docs index: the agent scaffolds, edits, validates, and builds your project through it, and every compiler error comes back as the tool result. That closed loop is what makes an AI tool converge on a working Quickback backend — the same loop that powers [start.quickback.dev](https://start.quickback.dev), pointed at the project on your disk.
49
+
48
50
  | Tool | Description |
49
51
  |------|-------------|
52
+ | `status` | Onboarding diagnostic: is this a project, are you logged in, is the compiler reachable, what to do next |
53
+ | `create` | Scaffold a new project from a template (`todos`, `saas`, `blog`, `empty`, `cloudflare`) |
54
+ | `validate` | Validation compile of `quickback/` — seconds, no migrations. Returns `DEFINITIONS VALID` plus warnings or the exact errors to fix, and on success writes the authoring surface the compiler tags: the authored-tree types (`quickback/tsconfig.json`, `.quickback/` helpers and the `src/` modules they type against), `api-types.gen.ts` / `quickback.gen.ts`, and the OpenAPI, AsyncAPI, and schema-registry specs. After three consecutive failures the result tells the agent to stop patching and replan |
55
+ | `check` | Typecheck the authored tree against the generated helpers (`quickback check`) — tables, config, and action files all check right after `validate`, no build needed |
56
+ | `build` | Full compile: the deployable runtime in `src/`, migrations, `wrangler.toml` (`quickback build`) |
50
57
  | `list_topics` | List all 100+ documentation topics |
51
58
  | `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
52
59
  | `search_docs` | Search documentation by keyword |
@@ -57,6 +64,8 @@ Add to your AI tool's MCP config:
57
64
 
58
65
  All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.
59
66
 
67
+ `validate` and `build` use your CLI login (`quickback login`, one-time device auth) or `QUICKBACK_API_KEY`. The server reads the directory it was started in, so start it from your project root — or, for a brand-new project, call `create` and then restart it from the new folder.
68
+
60
69
  ## Claude Code Skill
61
70
 
62
71
  ### Installation
@@ -263,7 +272,7 @@ Make sure the skill file exists and Claude Code is restarted. You can also invok
263
272
 
264
273
  ### Generated code has errors
265
274
 
266
- Run `quickback build` to validate. Share the error messages with Claude for fixes.
275
+ Ask the agent to call the `validate` tool (or run `quickback build` yourself and paste the errors). The compiler's messages name the file and the fix.
267
276
 
268
277
  ## Cursor IDE Rules
269
278
 
@@ -165,7 +165,11 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
165
165
  (or a project that has never compiled) exits `2` with a pointer at
166
166
  `quickback build`, which generates the tsconfig, helpers, and compiler types
167
167
  the check resolves against. Re-run `quickback build` after schema changes so
168
- they track your tables.
168
+ they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
169
+ refresh them: it writes the same typing files, client types, and specs from a
170
+ validation compile without producing the runtime — including the handful of
171
+ `src/` modules the `define-action` helper types `db`, `ctx`, and the table
172
+ against, so action files check too.
169
173
 
170
174
  Within a feature, the single helper import
171
175
  (`import { defineAction, tickets } from "../.quickback/define-action"`) is
@@ -45,6 +45,16 @@ Raw-files requests work with both `?complete=true` and `?complete=false`
45
45
  (validation-only) compiles. The v2 action-schema completeness gate applies to
46
46
  both modes; `complete=false` is not an escape hatch for a partial harvest.
47
47
 
48
+ Every generated file carries `path`, `content`, and `type`. Files that make up
49
+ the **authoring surface** additionally carry `authoring: true`: the `quickback/`
50
+ typing files (`tsconfig.json`, the `@quickback/compiler` declaration twin, the
51
+ per-feature `.quickback/define-action` helpers), the root client types
52
+ (`api-types.gen.ts`, `quickback.gen.ts`), the specs under
53
+ `src/apps/__quickback/spec/`, and the transitive import closure each helper
54
+ needs from `src/`. A thin client that wants types and specs during development
55
+ without producing a runtime writes exactly the tagged files from a
56
+ `complete=false` compile — that is what the CLI's [MCP `validate` tool](/tooling/claude-skill#available-tools) does.
57
+
48
58
  ## Edge validation backend
49
59
 
50
60
  Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.
@@ -14,7 +14,7 @@ export const TEMPLATE_REGISTRY = {
14
14
  },
15
15
  "todos-cloudflare": {
16
16
  name: "Todos Example (Cloudflare)",
17
- description: "Working todos example — schema with masking, two record-based actions (complete / uncomplete), Better Auth, D1. Read the source as a learning template.",
17
+ description: "Working todos example — schema with masking, two transitions (complete / uncomplete), a named view, Better Auth, D1. Read the source as a learning template.",
18
18
  tags: ["example", "todos", "actions", "cloudflare", "d1"],
19
19
  includes: ["betterauth", "d1", "hono", "drizzle"],
20
20
  preset: "cloudflare",
@@ -1 +1 @@
1
- {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,MAAM,CAAC,MAAM,iBAAiB,GAAuC;IACjE,0BAA0B,EAAE;QACxB,IAAI,EAAE,+BAA+B;QACrC,WAAW,EAAE,qHAAqH;QAClI,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC;QAC1C,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,kBAAkB,EAAE;QAChB,IAAI,EAAE,4BAA4B;QAClC,WAAW,EAAE,yJAAyJ;QACtK,IAAI,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,IAAI,CAAC;QACzD,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,wFAAwF;IACxF,qEAAqE;IACrE,oBAAoB,EAAE;QAClB,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,gFAAgF;QAC7F,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC;QAC9D,QAAQ,EAAE,CAAC,YAAY,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC;QAC7F,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,iEAAiE;IACjE,iBAAiB,EAAE;QACf,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,4GAA4G;QACzH,IAAI,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,IAAI,CAAC;QAChE,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,MAAM;QACd,kBAAkB,EAAE,IAAI;KAC3B;IACD,kBAAkB,EAAE;QAChB,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE,2FAA2F;QACxG,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC;QAC/C,QAAQ,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC;QACjD,MAAM,EAAE,YAAY;QACpB,kBAAkB,EAAE,IAAI;KAC3B;IACD,2DAA2D;CAC9D,CAAC;AAEF,+BAA+B;AAC/B,yEAAyE;AACzE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACpD,YAAY,EAAE,0BAA0B;IACxC,IAAI,EAAE,0BAA0B;IAChC,MAAM,EAAE,oBAAoB;IAC5B,MAAM,EAAE,iBAAiB;IACzB,OAAO,EAAE,kBAAkB;IAC3B,OAAO,EAAE,kBAAkB;IAC3B,OAAO,EAAE,kBAAkB;IAC3B,UAAU,EAAE,kBAAkB;CACjC,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,WAAmB;IAC3C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC;IAC9D,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,aAAa;IACzB,OAAO,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,kBAAkB;IAC9B,MAAM,KAAK,GAAa,CAAC,wBAAwB,CAAC,CAAC;IAEnD,KAAK,MAAM,CAAC,EAAE,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC1C,KAAK,CAAC,IAAI,CAAC,aAAa,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC7D,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,OAAO,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC"}
1
+ {"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quickback-dev/cli",
3
- "version": "0.66.22",
3
+ "version": "0.66.23",
4
4
  "description": "CLI for Quickback — define your backend in TypeScript, compile to a fully wired Cloudflare Worker (or Bun / Node) with auth, database, migrations, security, CMS, and Account UI.",
5
5
  "author": "Kardoe Incorporated <paul@kardoe.com>",
6
6
  "license": "MIT",
@@ -19,10 +19,7 @@ my-site/
19
19
  │ ├── quickback.config.ts # Pinned-organization config
20
20
  │ └── features/
21
21
  │ └── posts/
22
- │ ├── posts.ts # Schema + security (defineTable)
23
- │ └── actions/
24
- │ ├── publish.ts # Publish action
25
- │ └── unpublish.ts # Unpublish action
22
+ │ └── posts.ts # Schema, security, and publish/unpublish transitions
26
23
  ├── src/ # Compiled output (generated)
27
24
  ├── package.json
28
25
  ├── tsconfig.json
@@ -59,17 +56,16 @@ Replace `org_replace_me` with a real Better Auth organization id before deployin
59
56
  The template includes a `posts` feature with public read access and admin-only write access:
60
57
 
61
58
  ```typescript
62
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
63
- import { defineTable } from "@quickback/compiler";
59
+ import { q, defineTable } from "@quickback/compiler";
64
60
 
65
- export const posts = sqliteTable("posts", {
66
- id: text("id").primaryKey(),
67
- title: text("title").notNull(),
68
- slug: text("slug").notNull().unique(),
69
- content: text("content"),
70
- excerpt: text("excerpt"),
71
- status: text("status").notNull().default("draft"),
72
- publishedAt: text("published_at"),
61
+ export const posts = q.table("posts", {
62
+ id: q.id(),
63
+ title: q.text().required(),
64
+ slug: q.text().required().unique(),
65
+ content: q.text().optional(),
66
+ excerpt: q.text().optional(),
67
+ status: q.text().default("draft").required(),
68
+ publishedAt: q.timestamp().optional(),
73
69
 
74
70
  // Author tracking only — this is metadata, not access control.
75
71
  // Named "authorId" (not "userId") because a `userId` column on a feature
@@ -77,16 +73,13 @@ export const posts = sqliteTable("posts", {
77
73
  // column (that name is `ownerId`), and it errors when it is the only
78
74
  // candidate column on the table. Reads here are gated by PUBLIC; writes by
79
75
  // the admin access check below.
80
- authorId: text("author_id").notNull(),
76
+ authorId: q.text().required(),
81
77
 
82
- // Compiler-managed columns — the audit quartet on every table, plus the
83
- // soft-delete pair because `delete.mode` is "soft".
84
- createdAt: text("created_at").notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()),
85
- modifiedAt: text("modified_at").notNull().default('1970-01-01T00:00:00.000Z').$defaultFn(() => new Date().toISOString()).$onUpdate(() => new Date().toISOString()),
86
- createdBy: text("created_by"),
87
- modifiedBy: text("modified_by"),
88
- deletedAt: text("deleted_at"),
89
- deletedBy: text("deleted_by"),
78
+ // Compiler-managed columns — declared, not magic. `...q.audit()` is the
79
+ // audit quartet on every table; `...q.softDelete()` adds the soft-delete
80
+ // pair because `delete.mode` is "soft".
81
+ ...q.audit(),
82
+ ...q.softDelete(),
90
83
  });
91
84
 
92
85
  export default defineTable(posts, {
@@ -97,9 +90,21 @@ export default defineTable(posts, {
97
90
  softDelete: {},
98
91
  },
99
92
  guards: {
100
- createable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
101
- updatable: ["title", "slug", "content", "excerpt", "status", "publishedAt"],
93
+ createable: ["title", "slug", "content", "excerpt"],
94
+ updatable: ["title", "slug", "content", "excerpt"],
102
95
  immutable: ["id", "authorId"],
96
+ // `status` is workflow-owned: only the transitions below write it.
97
+ protected: { status: ["publish", "unpublish"] },
98
+ },
99
+ // Transitions generate POST /api/v1/posts/:id/publish and its inverse,
100
+ // stamping publishedAt on publish and clearing it on unpublish.
101
+ transitions: {
102
+ publish: {
103
+ field: "status", from: "draft", to: "published",
104
+ stamp: { at: "publishedAt" },
105
+ undo: "unpublish",
106
+ access: { roles: ["admin"] },
107
+ },
103
108
  },
104
109
  read: {
105
110
  access: { roles: ["PUBLIC"] },
@@ -117,42 +122,15 @@ export default defineTable(posts, {
117
122
  - **`authorId`** is plain metadata recording who wrote the post — it is deliberately *not* a firewall scope, because an owner predicate would hide every post from anonymous readers
118
123
  - **`softDelete`** marks posts as deleted rather than removing them from the database
119
124
 
120
- ### Post Actions (actions/publish.ts, actions/unpublish.ts)
125
+ ### Post Transitions (publish / unpublish)
121
126
 
122
- The template scaffolds one file per action under `features/posts/actions/`. Each is a `defineAction` with a record-level access condition and an `execute` handler:
127
+ The template declares the post lifecycle as [transitions](/define/transitions) on the table instead of hand-written action files. The compiler generates both actions — `POST /api/v1/posts/:id/publish` and `POST /api/v1/posts/:id/unpublish` — with the from/to guard, idempotency, and CMS buttons built in:
123
128
 
124
- ```typescript
125
- // quickback/features/posts/actions/publish.ts
126
- import { z } from "zod";
127
- import { eq } from "drizzle-orm";
128
- // The generated per-feature helper re-exports the bound table, so one import
129
- // gets you both — and `posts` here is the GENERATED table, with the audit
130
- // columns visible on `record` without `as any`.
131
- import { defineAction, posts } from "../.quickback/define-action";
132
-
133
- export default defineAction({
134
- description: "Publish a draft post",
135
- input: z.object({}),
136
- access: {
137
- roles: ["admin"],
138
- record: { status: { equals: "draft" } },
139
- },
140
- sideEffects: "sync",
141
- async execute({ db, record }) {
142
- const [updated] = await db
143
- .update(posts)
144
- .set({
145
- status: "published",
146
- publishedAt: new Date().toISOString(),
147
- })
148
- .where(eq(posts.id, record.id))
149
- .returning();
150
- return updated;
151
- },
152
- });
153
- ```
129
+ - **`publish`** requires `status: "draft"`, sets `status: "published"`, and stamps `publishedAt`.
130
+ - **`unpublish`** is the generated `undo` pair: it requires `status: "published"`, reverts to `draft`, and clears `publishedAt`.
131
+ - Both are admin-only via `access: { roles: ["admin"] }`; `guards.protected` means nothing else can write `status`, not even a plain `PATCH`.
154
132
 
155
- `unpublish.ts` is the mirror image — it requires `status: "published"` and reverts the post to draft. These actions are admin-only and include record-level access conditions: you can only publish drafts and unpublish published posts.
133
+ Need custom logic in the handler? Write `actions/publish.ts` yourself — an explicit action file always wins over the generated one — and keep the same `transition:` block so the guard stays compiler-owned. See [Actions](/define/actions).
156
134
 
157
135
  ## Setup Steps
158
136
 
@@ -23,9 +23,9 @@ Cloudflare Workers + D1 + Better Auth with the organization plugin and a `member
23
23
  | Template | Includes | Command |
24
24
  |----------|----------|---------|
25
25
  | `cloudflare` | Bare scaffold — auth + DB + Hono, no example feature | `quickback create cloudflare my-app` |
26
- | `todos` | Working todos feature: schema, masking, two actions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
26
+ | `todos` | Working todos feature: schema, masking, two transitions (`complete` / `uncomplete`), and a `dashboard` named view | `quickback create todos my-app` |
27
27
 
28
- The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus actions and views in ~80 lines you can scan in five minutes.
28
+ The **todos** template is the recommended first read — it exercises every security pillar (firewall, access, guards, masking) plus transitions and views in ~80 lines you can scan in five minutes.
29
29
 
30
30
  ### Fixed-org starter
31
31
 
@@ -70,7 +70,7 @@ Best when you already know the conventions and want empty walls. Multi-tenant or
70
70
 
71
71
  ### Todos (recommended for newcomers)
72
72
 
73
- Best for learning by reading. Full multi-tenant security pillars, two actions, a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
73
+ Best for learning by reading. Full multi-tenant security pillars, two transitions (`complete` / `uncomplete`), a named view (`/api/v1/todos/views/dashboard`), and field masking on the `description` column — all in a single ~80-line file you can copy-edit into your own table.
74
74
 
75
75
  ### Blog (pinned-organization CMS)
76
76
 
@@ -45,8 +45,15 @@ Add to your AI tool's MCP config:
45
45
 
46
46
  ### Available Tools
47
47
 
48
+ The server is a harness, not just a docs index: the agent scaffolds, edits, validates, and builds your project through it, and every compiler error comes back as the tool result. That closed loop is what makes an AI tool converge on a working Quickback backend — the same loop that powers [start.quickback.dev](https://start.quickback.dev), pointed at the project on your disk.
49
+
48
50
  | Tool | Description |
49
51
  |------|-------------|
52
+ | `status` | Onboarding diagnostic: is this a project, are you logged in, is the compiler reachable, what to do next |
53
+ | `create` | Scaffold a new project from a template (`todos`, `saas`, `blog`, `empty`, `cloudflare`) |
54
+ | `validate` | Validation compile of `quickback/` — seconds, no migrations. Returns `DEFINITIONS VALID` plus warnings or the exact errors to fix, and on success writes the authoring surface the compiler tags: the authored-tree types (`quickback/tsconfig.json`, `.quickback/` helpers and the `src/` modules they type against), `api-types.gen.ts` / `quickback.gen.ts`, and the OpenAPI, AsyncAPI, and schema-registry specs. After three consecutive failures the result tells the agent to stop patching and replan |
55
+ | `check` | Typecheck the authored tree against the generated helpers (`quickback check`) — tables, config, and action files all check right after `validate`, no build needed |
56
+ | `build` | Full compile: the deployable runtime in `src/`, migrations, `wrangler.toml` (`quickback build`) |
50
57
  | `list_topics` | List all 100+ documentation topics |
51
58
  | `get_doc` | Get a specific doc (supports fuzzy matching — e.g., "firewall") |
52
59
  | `search_docs` | Search documentation by keyword |
@@ -57,6 +64,8 @@ Add to your AI tool's MCP config:
57
64
 
58
65
  All documentation topics are also registered as MCP resources at `quickback://docs/{topic}`.
59
66
 
67
+ `validate` and `build` use your CLI login (`quickback login`, one-time device auth) or `QUICKBACK_API_KEY`. The server reads the directory it was started in, so start it from your project root — or, for a brand-new project, call `create` and then restart it from the new folder.
68
+
60
69
  ## Claude Code Skill
61
70
 
62
71
  ### Installation
@@ -263,7 +272,7 @@ Make sure the skill file exists and Claude Code is restarted. You can also invok
263
272
 
264
273
  ### Generated code has errors
265
274
 
266
- Run `quickback build` to validate. Share the error messages with Claude for fixes.
275
+ Ask the agent to call the `validate` tool (or run `quickback build` yourself and paste the errors). The compiler's messages name the file and the fix.
267
276
 
268
277
  ## Cursor IDE Rules
269
278
 
@@ -165,7 +165,11 @@ Exit codes: `0` clean · `1` type errors · `2` setup missing. A fresh clone
165
165
  (or a project that has never compiled) exits `2` with a pointer at
166
166
  `quickback build`, which generates the tsconfig, helpers, and compiler types
167
167
  the check resolves against. Re-run `quickback build` after schema changes so
168
- they track your tables.
168
+ they track your tables — or, in an AI tool, let the [MCP `validate` tool](/tooling/claude-skill#available-tools)
169
+ refresh them: it writes the same typing files, client types, and specs from a
170
+ validation compile without producing the runtime — including the handful of
171
+ `src/` modules the `define-action` helper types `db`, `ctx`, and the table
172
+ against, so action files check too.
169
173
 
170
174
  Within a feature, the single helper import
171
175
  (`import { defineAction, tickets } from "../.quickback/define-action"`) is
@@ -45,6 +45,16 @@ Raw-files requests work with both `?complete=true` and `?complete=false`
45
45
  (validation-only) compiles. The v2 action-schema completeness gate applies to
46
46
  both modes; `complete=false` is not an escape hatch for a partial harvest.
47
47
 
48
+ Every generated file carries `path`, `content`, and `type`. Files that make up
49
+ the **authoring surface** additionally carry `authoring: true`: the `quickback/`
50
+ typing files (`tsconfig.json`, the `@quickback/compiler` declaration twin, the
51
+ per-feature `.quickback/define-action` helpers), the root client types
52
+ (`api-types.gen.ts`, `quickback.gen.ts`), the specs under
53
+ `src/apps/__quickback/spec/`, and the transitive import closure each helper
54
+ needs from `src/`. A thin client that wants types and specs during development
55
+ without producing a runtime writes exactly the tagged files from a
56
+ `complete=false` compile — that is what the CLI's [MCP `validate` tool](/tooling/claude-skill#available-tools) does.
57
+
48
58
  ## Edge validation backend
49
59
 
50
60
  Validation compiles (`POST /compile?complete=false`) may be served by an edge Worker instead of the compiler container. This is **transparent to clients**: same endpoint, same auth, same request and response shapes (plain or gzipped JSON, raw-files or parsed input, identical payload limits, error shapes, and generated-file envelopes) — just no container cold start.