diff --git a/docs/en/tutorials/nextjs-quickstart.md b/docs/en/tutorials/nextjs-quickstart.md
index 29079a19c..3aa4e7fee 100644
--- a/docs/en/tutorials/nextjs-quickstart.md
+++ b/docs/en/tutorials/nextjs-quickstart.md
@@ -1,12 +1,12 @@
 ---
 title: Next.js Quickstart — Display LumiBase Content
-version: 1
-lastUpdated: 2026-08-02T19:05:15.812Z
+version: 5
+lastUpdated: 2026-09-14T19:53:53.530Z
 sourceLang: en
-contentHash: 36f30e29b1d22d3e
-codeVerified: 2026-08-02T19:05:15.812Z
-codeVerifiedHash: 36f30e29b1d22d3e
-codeVerifiedClaims: 14
+contentHash: ca523023eb37e81c
+codeVerified: 2026-09-14T19:53:53.530Z
+codeVerifiedHash: ca523023eb37e81c
+codeVerifiedClaims: 26
 ---
 
 <!--
@@ -14,7 +14,7 @@ codeVerifiedClaims: 14
   │ TUTORIAL VERSIONING — read before editing                                  │
   │                                                                            │
   │ applies_to_min: 0.9.0   ← lowest LumiBase version this tutorial is valid   │
-  │ verified_on:    0.10.0  ← version it was last actually tested against      │
+  │ verified_on:    1.0.0-rc.1  ← version it was last actually tested against      │
   │                                                                            │
   │ This tutorial is intentionally version-pinned. Do NOT clone it per         │
   │ release. Only bump `verified_on` (and, if a breaking change forces it,     │
@@ -31,7 +31,7 @@ codeVerifiedClaims: 14
 <p><strong>Go from a clean machine to a Next.js page rendering content from LumiBase.</strong></p>
 
 <p>
-  <img alt="LumiBase version" src="https://img.shields.io/badge/LumiBase-%E2%89%A5%200.9.0%20%C2%B7%20verified%200.10.0-F5A623?style=for-the-badge">
+  <img alt="LumiBase version" src="https://img.shields.io/badge/LumiBase-%E2%89%A5%200.9.0%20%C2%B7%20verified%201.0.0-rc.1-F5A623?style=for-the-badge">
   <img alt="Level" src="https://img.shields.io/badge/Level-Beginner-3DDC97?style=for-the-badge">
   <img alt="Time" src="https://img.shields.io/badge/Time-~20%20min-4A90E2?style=for-the-badge">
   <img alt="Stack" src="https://img.shields.io/badge/Next.js-App%20Router-black?style=for-the-badge&logo=next.js">
@@ -41,7 +41,7 @@ codeVerifiedClaims: 14
 
 > [!NOTE]
 > **Which LumiBase version is this for?** Valid from **LumiBase `0.9.0`** onward (last
-> verified on `0.10.0`).
+> verified on `1.0.0-rc.1`).
 > It stays valid for any newer release **until** one of the API contracts in the
 > [Compatibility](#compatibility) table changes — see that section to pick the right
 > version, with the newest on top.
@@ -51,8 +51,8 @@ You will:
 1. Run LumiBase locally (CMS API + Studio).
 2. Complete the setup wizard and create a `posts` collection with a few published items.
 3. Mint a long-lived API key and find your `siteId`.
-4. Build a tiny Next.js app that reads those posts — first with plain `fetch`, then with
-   the official `@lumibase/sdk`.
+4. Build a tiny Next.js app that reads those posts with the official `lumibase`
+   package (plain `fetch` is shown afterwards as an alternative).
 
 By the end you'll have a working `http://localhost:3000` page listing posts that live in
 LumiBase.
@@ -160,7 +160,7 @@ In **Studio** (`http://localhost:2026`):
 <thead><tr><th>#</th><th>Action</th></tr></thead>
 <tbody>
 <tr><td>1</td><td>Go to <strong>Collections → New Collection</strong>, name it <code>posts</code>.</td></tr>
-<tr><td>2</td><td>Add fields: <code>title</code> (String), <code>body</code> (Text), <code>status</code> (Select: <code>draft</code> / <code>published</code>, default <code>draft</code>).</td></tr>
+<tr><td>2</td><td>Add fields: <code>title</code> (String), <code>body</code> (Text). Do <strong>not</strong> add a <code>status</code> field — every item already has a built-in <code>status</code> column that the publish workflow drives.</td></tr>
 <tr><td>3</td><td>Save the collection.</td></tr>
 <tr><td>4</td><td>Go to <strong>Content → posts → New Item</strong>. Create 2–3 items and set <code>status</code> = <strong>published</strong>.</td></tr>
 </tbody>
@@ -233,6 +233,41 @@ curl http://localhost:1989/api/v1/site \
 > Keep the `lbk_…` key **server-side only** — never ship it to the browser. We use it from
 > a Next.js Server Component below, so it never leaves your server.
 
+**4d. Give the key least privilege.** A fresh key carries no permissions. Rather
+than attaching the Administrator role, create a policy that can only *read*
+`posts`, restrict it to published items, and attach it through a role:
+
+```bash
+# A policy whose single rule is "read published posts"
+curl -X POST http://localhost:1989/api/v1/policies \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" \
+  -d '{ "name": "Blog read-only" }'
+
+curl -X POST http://localhost:1989/api/v1/policies/<policy-id>/permissions \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" \
+  -d '{ "collection": "posts", "action": "read",
+        "permissions": { "status": { "_eq": "published" } } }'
+
+# A role that carries the policy, then attach the role to the key
+curl -X POST http://localhost:1989/api/v1/roles \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "name": "Blog Reader" }'
+
+curl -X POST http://localhost:1989/api/v1/roles/<role-id>/policies \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "policyId": "<policy-id>" }'
+
+curl -X POST http://localhost:1989/api/v1/api-keys/<key-id>/roles \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "roleId": "<role-id>" }'
+```
+
+The rule is enforced **server-side**: a request from this key that omits
+`status=published`, or asks for a draft by id, still gets back only published
+items (`404` for the draft). A write attempt answers `403`.
+
 ---
 
 ## Step 5 — Create the Next.js app
@@ -258,48 +293,61 @@ LUMIBASE_TOKEN=lbk_live_xxxxxxxxxxxxxxxx
 
 ---
 
-## Step 6 (Option A) — Fetch with plain `fetch`
-
-No extra dependency. Replace `app/page.tsx`:
+## Step 6 — Fetch with the SDK
 
-```tsx
-// app/page.tsx
-type Post = { id: string; title: string; body: string; status: string }
+Install `lumibase`. One package gives you both the client you import at runtime
+and the `lumibase` CLI used in Step 7:
 
-async function getPosts(): Promise<Post[]> {
-  const url = new URL('/api/v1/items/posts', process.env.LUMIBASE_API_URL)
-  // The `filter` param accepts two equivalent forms — pick either:
-  //   (A) JSON string:
-  url.searchParams.set('filter', JSON.stringify({ status: { _eq: 'published' } }))
-  //   (B) Bracket form (handy for hand-written URLs):
-  //   url.searchParams.set('filter[status][_eq]', 'published')
-  url.searchParams.set('sort', '-created_at')
+```bash
+npm install lumibase
+```
 
-  const res = await fetch(url, {
-    headers: {
-      Authorization: `Bearer ${process.env.LUMIBASE_TOKEN}`,
-      'X-Lumi-Site': process.env.LUMIBASE_SITE_ID!,
-    },
-    next: { revalidate: 60 }, // ISR-style cache; use 'no-store' for always-fresh
-  })
+Create the client once. It is imported only from Server Components, so the token
+never reaches the browser:
 
-  if (!res.ok) throw new Error(`LumiBase responded ${res.status}: ${await res.text()}`)
+```ts
+// lib/lumibase.ts
+import { createLumiClient, legacyRest, type ItemRow } from 'lumibase'
 
-  const json = (await res.json()) as { data: Post[] }
-  return json.data
+// Your collection's content fields, as declared in Studio.
+export interface PostFields {
+  title: string
+  body: string
+  [key: string]: unknown
 }
 
+export type Post = ItemRow<PostFields>
+
+export const lumibase = createLumiClient<{ posts: PostFields }>({
+  url: process.env.LUMIBASE_API_URL!,
+  siteId: process.env.LUMIBASE_SITE_ID!,
+  // static API key — skips the login flow
+  token: process.env.LUMIBASE_TOKEN!,
+}).with(legacyRest())
+```
+
+```tsx
+// app/page.tsx
+import { lumibase, type Post } from '@/lib/lumibase'
+
 export default async function Home() {
-  const posts = await getPosts()
+  // `status` is a dedicated list parameter, not a filter. Sorting uses the
+  // structural column's snake_case name.
+  const { data: posts } = await lumibase.items('posts').list({
+    status: 'published',
+    sort: ['-created_at'],
+    limit: 20,
+  })
+
   return (
     <main style={{ maxWidth: 640, margin: '2rem auto', fontFamily: 'system-ui' }}>
       <h1>Posts from LumiBase</h1>
       {posts.length === 0 && <p>No published posts yet.</p>}
       <ul>
-        {posts.map((post) => (
+        {posts.map((post: Post) => (
           <li key={post.id} style={{ marginBottom: '1.5rem' }}>
-            <h2>{post.title}</h2>
-            <p>{post.body}</p>
+            <h2>{post.data.title}</h2>
+            <p>{post.data.body}</p>
           </li>
         ))}
       </ul>
@@ -308,10 +356,16 @@ export default async function Home() {
 }
 ```
 
+> [!IMPORTANT]
+> **Content fields live under `.data`.** A row is an `ItemRow`: structural
+> columns (`id`, `status`, `createdAt`, …) are at the top level, while the
+> fields you declared are nested — `post.data.title`, not `post.title`.
+
 Run it:
 
 ```bash
-npm run dev   # open http://localhost:3000
+# open http://localhost:3000
+npm run dev
 ```
 
 You should see your published posts. Here's roughly what renders:
@@ -333,58 +387,138 @@ You should see your published posts. Here's roughly what renders:
 <sub><em>Illustration of the rendered page (not a live screenshot).</em></sub>
 </div>
 
+Reading a single post works the same way. Every non-2xx answer throws a
+`LumiError` carrying the status, which maps cleanly onto `notFound()`:
+
+```tsx
+// app/posts/[id]/page.tsx
+import { notFound } from 'next/navigation'
+import { LumiError } from 'lumibase'
+import { lumibase, type Post } from '@/lib/lumibase'
+
+// Required. Without it this route is cached indefinitely and edits made in
+// Studio never reach the page.
+export const revalidate = 60
+
+export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  let post: Post
+
+  try {
+    const res = await lumibase.items('posts').detail(id)
+    post = res.data
+  } catch (err) {
+    if (err instanceof LumiError && err.status === 404) return notFound()
+    throw err
+  }
+
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <p>{post.data.body}</p>
+    </article>
+  )
+}
+```
+
+A draft the credential cannot see answers `404` — the same path as an unknown
+id — so unpublished content can never surface.
+
+> [!IMPORTANT]
+> **Set `revalidate` on every cached route, not just the list.** A route with
+> `generateStaticParams` but no `revalidate` is rendered once at build time and
+> then cached forever, so edits made in Studio never appear on it. A post
+> published *after* the build is still served: `dynamicParams` defaults to
+> `true`, so Next renders it on demand the first time it is requested.
+
+> **Already depend on `@lumibase/sdk`?** It exports the identical client —
+> `lumibase` simply re-exports it so one name covers both the client and the
+> CLI. Swap `from 'lumibase'` for `from '@lumibase/sdk'` and everything above
+> works unchanged.
+
 ---
 
-## Step 6 (Option B) — Fetch with the SDK
+## Step 7 — Generate types in CI
 
-The SDK removes the boilerplate (URL building, headers, filter encoding) and returns typed
-results.
+`lumibase types` turns the live schema into TypeScript definitions. Commit the
+output and let CI fail when it drifts from the schema.
 
-```bash
-npm install @lumibase/sdk
+Create `lumibase.config.json` next to `package.json` (it is meant to be
+committed — it holds no secret):
+
+```json
+{
+  "url": "http://localhost:1989",
+  "siteId": "__default__",
+  "typegen": { "out": "src/lumibase-types.d.ts" }
+}
 ```
 
-```ts
-// lib/lumibase.ts
-import { createClient } from '@lumibase/sdk'
+```bash
+# write src/lumibase-types.d.ts — commit it
+npx lumibase types
+# exits non-zero if the file is stale
+npx lumibase types --check
+# show the resolved config and probe connectivity
+npx lumibase doctor
+```
 
-export const lumibase = createClient({
-  url: process.env.LUMIBASE_API_URL!,
-  siteId: process.env.LUMIBASE_SITE_ID!,
-  token: process.env.LUMIBASE_TOKEN!, // static API key — skips the login flow
-})
+> [!IMPORTANT]
+> **Typegen needs a staff user token, not an API key.**
+> `GET /api/v1/typegen/schema` sits behind the Studio access wall, which
+> requires a user principal. An API key is rejected with `403` even when its
+> role grants `schema:read`. Use a staff user's access token as a build-time
+> secret for typegen, and keep the read-only API key from Step 4 for the
+> runtime reads your pages do.
+
+The generated file is deterministic — no host, site id or timestamp in its
+header — so the same committed file verifies against any instance:
+
+```yaml
+- run: npm ci
+- run: npx lumibase types --check
+  env:
+    LUMIBASE_URL: ${{ secrets.LUMIBASE_URL }}
+    LUMIBASE_SITE_ID: ${{ secrets.LUMIBASE_SITE_ID }}
+    LUMIBASE_TOKEN: ${{ secrets.LUMIBASE_TYPEGEN_TOKEN }}
 ```
 
+---
+
+## Alternative — the same read with plain `fetch`
+
+The SDK only wraps the HTTP API; nothing stops you calling it directly if you
+would rather not add a dependency. You give up typed results and typegen, and
+you rebuild the URL, headers and filter encoding yourself:
+
 ```tsx
 // app/page.tsx
-import { lumibase } from '@/lib/lumibase'
+type Post = { id: string; status: string; data: { title: string; body: string } }
 
-export default async function Home() {
-  const posts = await lumibase.items('posts').readMany({
-    filter: { status: { _eq: 'published' } },
-    sort: ['-created_at'],
-    limit: 20,
+async function getPosts(): Promise<Post[]> {
+  const url = new URL('/api/v1/items/posts', process.env.LUMIBASE_API_URL)
+  url.searchParams.set('status', 'published')
+  // The `filter` param accepts two equivalent forms — pick either:
+  //   (A) JSON string:       filter={"status":{"_eq":"published"}}
+  //   (B) Bracket form:      filter[status][_eq]=published
+  url.searchParams.set('sort', '-created_at')
+
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${process.env.LUMIBASE_TOKEN}`,
+      'X-Lumi-Site': process.env.LUMIBASE_SITE_ID!,
+    },
+    // ISR-style cache; use 'no-store' for always-fresh
+    next: { revalidate: 60 },
   })
-  return (
-    <main style={{ maxWidth: 640, margin: '2rem auto', fontFamily: 'system-ui' }}>
-      <h1>Posts from LumiBase</h1>
-      {posts.length === 0 && <p>No published posts yet.</p>}
-      <ul>
-        {posts.map((post: any) => (
-          <li key={post.id} style={{ marginBottom: '1.5rem' }}>
-            <h2>{post.title}</h2>
-            <p>{post.body}</p>
-          </li>
-        ))}
-      </ul>
-    </main>
-  )
+
+  if (!res.ok) throw new Error(`LumiBase responded ${res.status}: ${await res.text()}`)
+
+  const json = (await res.json()) as { data: Post[] }
+  return json.data
 }
 ```
 
-Same result, less code. For typed `post.title` instead of `any`, generate types from your
-schema — see [SDK type generation](../sdk/typegen.md).
-
 ---
 
 ## Troubleshooting
@@ -394,7 +528,7 @@ schema — see [SDK type generation](../sdk/typegen.md).
 <tbody>
 <tr><td><code>401 Unauthorized</code></td><td>Missing/invalid token</td><td>Re-check <code>LUMIBASE_TOKEN</code>; recreate the API key (Step 4b)</td></tr>
 <tr><td><code>423 SETUP_REQUIRED</code></td><td>Setup not finished</td><td>Complete <code>http://localhost:1989/setup</code> (Step 2)</td></tr>
-<tr><td><code>404 SITE_NOT_FOUND</code></td><td>Wrong/missing <code>X-Lumi-Site</code></td><td>Use <code>__default__</code> unless you created another site</td></tr>
+<tr><td><code>404 TENANT_NOT_FOUND</code></td><td>Wrong <code>X-Lumi-Site</code> — the header is well-formed but no such site exists</td><td>Use <code>__default__</code> unless you created another site</td></tr>
 <tr><td>Empty <code>data: []</code></td><td>No <strong>published</strong> posts</td><td>Set items to <code>published</code> in Studio</td></tr>
 <tr><td><code>404</code> on items</td><td>Collection name mismatch</td><td>Collection must be named exactly <code>posts</code></td></tr>
 <tr><td>CORS error in browser</td><td>Fetching from client code</td><td>Fetch from a <strong>Server Component</strong> (as above)</td></tr>
@@ -491,7 +625,7 @@ contract it relies on actually changes. Pick the row matching your LumiBase vers
 <table>
 <thead><tr><th>LumiBase version</th><th>This tutorial</th><th>Notes</th></tr></thead>
 <tbody>
-<tr><td><strong>0.9.0 → latest</strong></td><td>✅ This page (verified on <code>0.10.0</code>)</td><td>Login returns <code>{ data: { token } }</code>; API keys via <code>POST /api/v1/api-keys</code> (<code>lbk_</code> prefix); items filter accepts JSON <em>and</em> bracket form; default site <code>__default__</code>.</td></tr>
+<tr><td><strong>0.9.0 → latest</strong></td><td>✅ This page (verified on <code>1.0.0-rc.1</code>)</td><td>Login returns <code>{ data: { token } }</code>; API keys via <code>POST /api/v1/api-keys</code> (<code>lbk_</code> prefix); items filter accepts JSON <em>and</em> bracket form; default site <code>__default__</code>.</td></tr>
 <tr><td>&lt; 0.9.0</td><td>⚠️ Not covered</td><td>Earlier releases predate the contracts above. Upgrade to ≥ 0.9.0, or adapt the auth/filter calls to your version.</td></tr>
 </tbody>
 </table>
@@ -504,7 +638,11 @@ the table above and re-verify — see DoD §5):
 - `GET /api/v1/items/:collection` filter accepts **both** `filter=<JSON>` and
   `filter[field][_op]=value` bracket form (JSON wins if both sent); `sort=<csv>`
 - `GET /api/v1/site` returns the active tenant; default id `__default__`
-- `@lumibase/sdk` `createClient({ url, siteId, token }).items(c).readMany(...)`
+- `lumibase` (re-exports `@lumibase/sdk`) —
+  `createLumiClient({ url, siteId, token }).with(legacyRest()).items(c).list(...)` /
+  `.detail(id)`; rows are `ItemRow` with content fields under `.data`
+- `lumibase types` / `types --check` read `GET /api/v1/typegen/schema`, which
+  requires a **staff user** principal (an API key gets `403`)
 - Rate limiting returns `429 RATE_LIMITED` with `Retry-After`; the "Production &
   security" section additionally covers `503 RATE_LIMIT_UNAVAILABLE` and
   `Deprecation`/`Sunset` headers, both **added in `0.24.0`** (the core flow above still
diff --git a/docs/vi/tutorials/nextjs-quickstart.md b/docs/vi/tutorials/nextjs-quickstart.md
index 3e6feaf64..0c1b6d40d 100644
--- a/docs/vi/tutorials/nextjs-quickstart.md
+++ b/docs/vi/tutorials/nextjs-quickstart.md
@@ -1,15 +1,15 @@
 ---
 title: Next.js Quickstart — Hiển thị nội dung LumiBase
-version: 1
-lastUpdated: 2026-08-02T19:05:15.812Z
+version: 5
+lastUpdated: 2026-09-14T19:53:53.530Z
 sourceLang: en
 translatedFrom: en
-sourceHash: 36f30e29b1d22d3e
+sourceHash: ca523023eb37e81c
 mtEngine: manual
 syncStatus: human-translated
-codeVerified: 2026-08-02T19:05:15.812Z
-codeVerifiedHash: 36f30e29b1d22d3e
-codeVerifiedClaims: 14
+codeVerified: 2026-09-14T19:53:53.530Z
+codeVerifiedHash: ca523023eb37e81c
+codeVerifiedClaims: 26
 ---
 
 <!--
@@ -17,7 +17,7 @@ codeVerifiedClaims: 14
   │ TUTORIAL VERSIONING — đọc trước khi sửa                                     │
   │                                                                            │
   │ applies_to_min: 0.9.0   ← phiên bản LumiBase thấp nhất tutorial còn đúng   │
-  │ verified_on:    0.10.0  ← phiên bản đã thực sự test lần gần nhất           │
+  │ verified_on:    1.0.0-rc.1  ← phiên bản đã thực sự test lần gần nhất           │
   │                                                                            │
   │ Tutorial này cố tình pin theo version. KHÔNG clone tut này theo từng       │
   │ release. Chỉ bump `verified_on` (và `applies_to_min` nếu có breaking       │
@@ -34,7 +34,7 @@ codeVerifiedClaims: 14
 <p><strong>Xây dựng trang Next.js đầu tiên với nội dung được phân phối từ LumiBase.</strong></p>
 
 <p>
-  <img alt="LumiBase version" src="https://img.shields.io/badge/LumiBase-%E2%89%A5%200.9.0%20%C2%B7%20verified%200.10.0-F5A623?style=for-the-badge">
+  <img alt="LumiBase version" src="https://img.shields.io/badge/LumiBase-%E2%89%A5%200.9.0%20%C2%B7%20verified%201.0.0-rc.1-F5A623?style=for-the-badge">
   <img alt="Level" src="https://img.shields.io/badge/C%E1%BA%A5p%20%C4%91%E1%BB%99-C%C6%A1%20b%E1%BA%A3n-3DDC97?style=for-the-badge">
   <img alt="Time" src="https://img.shields.io/badge/Th%E1%BB%9Di%20gian-~20%20ph%C3%BAt-4A90E2?style=for-the-badge">
   <img alt="Stack" src="https://img.shields.io/badge/Next.js-App%20Router-black?style=for-the-badge&logo=next.js">
@@ -44,7 +44,7 @@ codeVerifiedClaims: 14
 
 > [!NOTE]
 > **Tutorial này cho phiên bản nào?** Đúng từ **LumiBase `0.9.0`** trở lên (verify gần nhất
-> trên `0.10.0`). Vẫn đúng cho các bản
+> trên `1.0.0-rc.1`). Vẫn đúng cho các bản
 > mới hơn **cho tới khi** một trong các API contract ở bảng [Tương thích](#compatibility)
 > thay đổi — xem bảng đó để chọn đúng version, **mới nhất ở trên cùng**.
 
@@ -53,8 +53,8 @@ Bạn sẽ:
 1. Chạy LumiBase ở local (CMS API + Studio).
 2. Hoàn tất setup wizard và tạo collection `posts` với vài item đã publish.
 3. Tạo API key dài hạn và xác nhận `siteId`.
-4. Dựng app Next.js nhỏ để đọc các bài viết đó — đầu tiên bằng `fetch` thuần, sau đó bằng
-   `@lumibase/sdk`.
+4. Dựng app Next.js nhỏ để đọc các bài viết đó bằng package `lumibase` chính thức
+   (`fetch` thuần được trình bày sau như một lựa chọn thay thế).
 
 Kết thúc, bạn có trang `http://localhost:3000` liệt kê các bài viết nằm trong LumiBase.
 
@@ -160,7 +160,7 @@ Trong **Studio** (`http://localhost:2026`):
 <thead><tr><th>#</th><th>Thao tác</th></tr></thead>
 <tbody>
 <tr><td>1</td><td>Vào <strong>Collections → New Collection</strong>, đặt tên là <code>posts</code>.</td></tr>
-<tr><td>2</td><td>Thêm các trường: <code>title</code> (String), <code>body</code> (Text), <code>status</code> (Select: <code>draft</code> / <code>published</code>, mặc định <code>draft</code>).</td></tr>
+<tr><td>2</td><td>Thêm các trường: <code>title</code> (String), <code>body</code> (Text). <strong>Không</strong> thêm trường <code>status</code> — mỗi item đã có sẵn cột <code>status</code> dựng sẵn do luồng publish điều khiển.</td></tr>
 <tr><td>3</td><td>Lưu collection.</td></tr>
 <tr><td>4</td><td>Vào <strong>Content → posts → New Item</strong>. Tạo 2–3 mục và đặt <code>status</code> = <strong>published</strong>.</td></tr>
 </tbody>
@@ -233,6 +233,41 @@ curl http://localhost:1989/api/v1/site \
 > Giữ key `lbk_…` **chỉ ở phía server** — không bao giờ gửi xuống browser. Bên dưới ta dùng
 > nó từ Next.js Server Component nên nó không rời khỏi server.
 
+**4d. Cấp quyền tối thiểu cho key.** Key mới tạo chưa có quyền nào. Thay vì gắn
+role Administrator, hãy tạo một policy chỉ *đọc* `posts`, giới hạn ở item đã
+publish, rồi gắn qua một role:
+
+```bash
+# Policy với đúng một quy tắc: "đọc các bài đã publish"
+curl -X POST http://localhost:1989/api/v1/policies \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" \
+  -d '{ "name": "Blog read-only" }'
+
+curl -X POST http://localhost:1989/api/v1/policies/<policy-id>/permissions \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" \
+  -d '{ "collection": "posts", "action": "read",
+        "permissions": { "status": { "_eq": "published" } } }'
+
+# Role mang policy đó, rồi gắn role vào key
+curl -X POST http://localhost:1989/api/v1/roles \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "name": "Blog Reader" }'
+
+curl -X POST http://localhost:1989/api/v1/roles/<role-id>/policies \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "policyId": "<policy-id>" }'
+
+curl -X POST http://localhost:1989/api/v1/api-keys/<key-id>/roles \
+  -H "Content-Type: application/json" -H "Authorization: Bearer <token-from-4a>" \
+  -H "X-Lumi-Site: __default__" -d '{ "roleId": "<role-id>" }'
+```
+
+Quy tắc được áp dụng **ở phía server**: request từ key này dù bỏ qua
+`status=published`, hay hỏi thẳng id của một bản nháp, vẫn chỉ nhận về item đã
+publish (`404` với bản nháp). Thao tác ghi trả về `403`.
+
 ---
 
 ## Step 5 — Create the Next.js app
@@ -258,48 +293,61 @@ LUMIBASE_TOKEN=lbk_live_xxxxxxxxxxxxxxxx
 
 ---
 
-## Step 6 (Option A) — Fetch with plain `fetch`
-
-Không cần dependency thêm. Thay nội dung `app/page.tsx`:
+## Step 6 — Fetch with the SDK
 
-```tsx
-// app/page.tsx
-type Post = { id: string; title: string; body: string; status: string }
+Cài `lumibase`. Một package cung cấp cả client bạn import lúc chạy lẫn CLI
+`lumibase` dùng ở Step 7:
 
-async function getPosts(): Promise<Post[]> {
-  const url = new URL('/api/v1/items/posts', process.env.LUMIBASE_API_URL)
-  // The `filter` param accepts two equivalent forms — pick either:
-  //   (A) JSON string:
-  url.searchParams.set('filter', JSON.stringify({ status: { _eq: 'published' } }))
-  //   (B) Bracket form (handy for hand-written URLs):
-  //   url.searchParams.set('filter[status][_eq]', 'published')
-  url.searchParams.set('sort', '-created_at')
+```bash
+npm install lumibase
+```
 
-  const res = await fetch(url, {
-    headers: {
-      Authorization: `Bearer ${process.env.LUMIBASE_TOKEN}`,
-      'X-Lumi-Site': process.env.LUMIBASE_SITE_ID!,
-    },
-    next: { revalidate: 60 }, // ISR-style cache; use 'no-store' for always-fresh
-  })
+Tạo client một lần. Nó chỉ được import từ Server Component nên token không bao
+giờ xuống tới browser:
 
-  if (!res.ok) throw new Error(`LumiBase responded ${res.status}: ${await res.text()}`)
+```ts
+// lib/lumibase.ts
+import { createLumiClient, legacyRest, type ItemRow } from 'lumibase'
 
-  const json = (await res.json()) as { data: Post[] }
-  return json.data
+// Các trường nội dung của collection, đúng như khai báo trong Studio.
+export interface PostFields {
+  title: string
+  body: string
+  [key: string]: unknown
 }
 
+export type Post = ItemRow<PostFields>
+
+export const lumibase = createLumiClient<{ posts: PostFields }>({
+  url: process.env.LUMIBASE_API_URL!,
+  siteId: process.env.LUMIBASE_SITE_ID!,
+  // API key tĩnh — bỏ qua luồng login
+  token: process.env.LUMIBASE_TOKEN!,
+}).with(legacyRest())
+```
+
+```tsx
+// app/page.tsx
+import { lumibase, type Post } from '@/lib/lumibase'
+
 export default async function Home() {
-  const posts = await getPosts()
+  // `status` là tham số riêng của list, không phải filter. Sắp xếp dùng tên
+  // snake_case của cột cấu trúc.
+  const { data: posts } = await lumibase.items('posts').list({
+    status: 'published',
+    sort: ['-created_at'],
+    limit: 20,
+  })
+
   return (
     <main style={{ maxWidth: 640, margin: '2rem auto', fontFamily: 'system-ui' }}>
       <h1>Posts from LumiBase</h1>
       {posts.length === 0 && <p>No published posts yet.</p>}
       <ul>
-        {posts.map((post) => (
+        {posts.map((post: Post) => (
           <li key={post.id} style={{ marginBottom: '1.5rem' }}>
-            <h2>{post.title}</h2>
-            <p>{post.body}</p>
+            <h2>{post.data.title}</h2>
+            <p>{post.data.body}</p>
           </li>
         ))}
       </ul>
@@ -308,13 +356,19 @@ export default async function Home() {
 }
 ```
 
-Chạy dự án:
+> [!IMPORTANT]
+> **Trường nội dung nằm trong `.data`.** Mỗi dòng là một `ItemRow`: các cột cấu
+> trúc (`id`, `status`, `createdAt`, …) nằm ở cấp ngoài cùng, còn các trường bạn
+> khai báo thì lồng bên trong — `post.data.title`, không phải `post.title`.
+
+Chạy thử:
 
 ```bash
-npm run dev   # open http://localhost:3000
+# mở http://localhost:3000
+npm run dev
 ```
 
-Bạn sẽ thấy các bài viết đã xuất bản. Đây là hình ảnh phỏng dựng kết quả:
+Bạn sẽ thấy các bài đã publish. Giao diện render đại khái như sau:
 
 <div align="center">
 <table border="0" width="520"><tr><td style="border:1px solid #d0d7de;border-radius:10px;padding:20px 28px;background:#ffffff;">
@@ -330,59 +384,139 @@ Bạn sẽ thấy các bài viết đã xuất bản. Đây là hình ảnh ph
 </div>
 </div>
 </td></tr></table>
-<sub><em>Hình ảnh minh họa trang kết quả (không phải ảnh chụp thực tế).</em></sub>
+<sub><em>Minh hoạ trang đã render (không phải ảnh chụp thật).</em></sub>
 </div>
 
+Đọc một bài đơn lẻ cũng tương tự. Mọi phản hồi khác 2xx đều ném `LumiError` kèm
+status, ánh xạ gọn sang `notFound()`:
+
+```tsx
+// app/posts/[id]/page.tsx
+import { notFound } from 'next/navigation'
+import { LumiError } from 'lumibase'
+import { lumibase, type Post } from '@/lib/lumibase'
+
+// Bắt buộc. Thiếu dòng này thì route bị cache vĩnh viễn và nội dung sửa trong
+// Studio không bao giờ hiện ra.
+export const revalidate = 60
+
+export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  let post: Post
+
+  try {
+    const res = await lumibase.items('posts').detail(id)
+    post = res.data
+  } catch (err) {
+    if (err instanceof LumiError && err.status === 404) return notFound()
+    throw err
+  }
+
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <p>{post.data.body}</p>
+    </article>
+  )
+}
+```
+
+Một bản nháp mà credential không được phép thấy sẽ trả `404` — cùng đường đi với
+một id không tồn tại — nên nội dung chưa publish không thể lộ ra.
+
+> [!IMPORTANT]
+> **Khai báo `revalidate` cho mọi route được cache, không chỉ trang danh sách.**
+> Route có `generateStaticParams` nhưng thiếu `revalidate` chỉ được render một
+> lần lúc build rồi cache vĩnh viễn, nên nội dung sửa trong Studio không bao giờ
+> hiện ra. Bài publish *sau* khi build vẫn phục vụ được: `dynamicParams` mặc
+> định là `true` nên Next render on-demand ở lần truy cập đầu tiên.
+
+> **Đang phụ thuộc `@lumibase/sdk`?** Nó export đúng cùng một client —
+> `lumibase` chỉ re-export lại để một cái tên bao trọn cả client lẫn CLI. Đổi
+> `from 'lumibase'` thành `from '@lumibase/sdk'` là mọi thứ ở trên chạy nguyên vẹn.
+
 ---
 
-## Step 6 (Option B) — Fetch with the SDK
+## Step 7 — Generate types in CI
 
-SDK giúp loại bỏ các code mẫu (dựng URL, headers, mã hóa bộ lọc) và trả về kết quả có type.
+`lumibase types` biến schema đang chạy thành định nghĩa TypeScript. Hãy commit
+kết quả và để CI báo lỗi khi nó lệch với schema.
 
-```bash
-npm install @lumibase/sdk
+Tạo `lumibase.config.json` cạnh `package.json` (file này để commit — nó không
+chứa secret):
+
+```json
+{
+  "url": "http://localhost:1989",
+  "siteId": "__default__",
+  "typegen": { "out": "src/lumibase-types.d.ts" }
+}
 ```
 
-```ts
-// lib/lumibase.ts
-import { createClient } from '@lumibase/sdk'
+```bash
+# ghi src/lumibase-types.d.ts — hãy commit
+npx lumibase types
+# thoát khác 0 nếu file đã cũ
+npx lumibase types --check
+# xem cấu hình đã resolve và kiểm tra kết nối
+npx lumibase doctor
+```
 
-export const lumibase = createClient({
-  url: process.env.LUMIBASE_API_URL!,
-  siteId: process.env.LUMIBASE_SITE_ID!,
-  token: process.env.LUMIBASE_TOKEN!, // static API key — skips the login flow
-})
+> [!IMPORTANT]
+> **Typegen cần token của staff user, không phải API key.**
+> `GET /api/v1/typegen/schema` nằm sau bức tường Studio access vốn đòi principal
+> là user. API key bị từ chối với `403` kể cả khi role của nó có `schema:read`.
+> Hãy dùng access token của một staff user làm secret lúc build cho typegen, còn
+> API key chỉ-đọc ở Step 4 thì để cho các lượt đọc lúc chạy của trang.
+
+File sinh ra mang tính tất định — header không chứa host, site id hay timestamp
+— nên cùng một file đã commit verify được trên mọi instance:
+
+```yaml
+- run: npm ci
+- run: npx lumibase types --check
+  env:
+    LUMIBASE_URL: ${{ secrets.LUMIBASE_URL }}
+    LUMIBASE_SITE_ID: ${{ secrets.LUMIBASE_SITE_ID }}
+    LUMIBASE_TOKEN: ${{ secrets.LUMIBASE_TYPEGEN_TOKEN }}
 ```
 
+---
+
+## Alternative — the same read with plain `fetch`
+
+SDK chỉ bọc lại HTTP API; không có gì ngăn bạn gọi thẳng nếu không muốn thêm
+dependency. Đổi lại bạn mất kết quả có kiểu và mất typegen, đồng thời phải tự
+dựng URL, header và mã hoá filter:
+
 ```tsx
 // app/page.tsx
-import { lumibase } from '@/lib/lumibase'
+type Post = { id: string; status: string; data: { title: string; body: string } }
 
-export default async function Home() {
-  const posts = await lumibase.items('posts').readMany({
-    filter: { status: { _eq: 'published' } },
-    sort: ['-created_at'],
-    limit: 20,
+async function getPosts(): Promise<Post[]> {
+  const url = new URL('/api/v1/items/posts', process.env.LUMIBASE_API_URL)
+  url.searchParams.set('status', 'published')
+  // Tham số `filter` nhận hai dạng tương đương — chọn dạng nào cũng được:
+  //   (A) chuỗi JSON:   filter={"status":{"_eq":"published"}}
+  //   (B) dạng ngoặc:   filter[status][_eq]=published
+  url.searchParams.set('sort', '-created_at')
+
+  const res = await fetch(url, {
+    headers: {
+      Authorization: `Bearer ${process.env.LUMIBASE_TOKEN}`,
+      'X-Lumi-Site': process.env.LUMIBASE_SITE_ID!,
+    },
+    // cache kiểu ISR; dùng 'no-store' nếu cần luôn mới
+    next: { revalidate: 60 },
   })
-  return (
-    <main style={{ maxWidth: 640, margin: '2rem auto', fontFamily: 'system-ui' }}>
-      <h1>Posts from LumiBase</h1>
-      {posts.length === 0 && <p>No published posts yet.</p>}
-      <ul>
-        {posts.map((post: any) => (
-          <li key={post.id} style={{ marginBottom: '1.5rem' }}>
-            <h2>{post.title}</h2>
-            <p>{post.body}</p>
-          </li>
-        ))}
-      </ul>
-    </main>
-  )
+
+  if (!res.ok) throw new Error(`LumiBase responded ${res.status}: ${await res.text()}`)
+
+  const json = (await res.json()) as { data: Post[] }
+  return json.data
 }
 ```
 
-Cùng kết quả nhưng ít code hơn. Để có type cho `post.title` thay vì `any`, sinh type từ schema — xem [Sinh type SDK](../sdk/typegen.md).
-
 ---
 
 ## Troubleshooting
@@ -392,7 +526,7 @@ Cùng kết quả nhưng ít code hơn. Để có type cho `post.title` thay vì
 <tbody>
 <tr><td><code>401 Unauthorized</code></td><td>Token thiếu hoặc không hợp lệ</td><td>Kiểm tra lại <code>LUMIBASE_TOKEN</code>; tạo lại API key (Bước 4b)</td></tr>
 <tr><td><code>423 SETUP_REQUIRED</code></td><td>Chưa hoàn tất setup</td><td>Hoàn tất <code>http://localhost:1989/setup</code> (Bước 2)</td></tr>
-<tr><td><code>404 SITE_NOT_FOUND</code></td><td>Sai hoặc thiếu <code>X-Lumi-Site</code></td><td>Dùng <code>__default__</code> trừ khi bạn đã tạo site khác</td></tr>
+<tr><td><code>404 TENANT_NOT_FOUND</code></td><td>Sai <code>X-Lumi-Site</code> — header đúng định dạng nhưng site không tồn tại</td><td>Dùng <code>__default__</code> trừ khi bạn đã tạo site khác</td></tr>
 <tr><td>Mảng trống <code>data: []</code></td><td>Chưa có bài viết <strong>published</strong> nào</td><td>Đặt trạng thái item thành <code>published</code> trong Studio</td></tr>
 <tr><td><code>404</code> trên items</td><td>Sai tên collection</td><td>Collection phải đặt tên chính xác là <code>posts</code></td></tr>
 <tr><td>Lỗi CORS ở trình duyệt</td><td>Gọi API từ client code</td><td>Gọi từ một <strong>Server Component</strong> (như hướng dẫn trên)</td></tr>
@@ -466,7 +600,7 @@ Tutorial này được **ghim vào phiên bản LumiBase tối thiểu** và ch
 <table>
 <thead><tr><th>Phiên bản LumiBase</th><th>Tutorial này</th><th>Ghi chú</th></tr></thead>
 <tbody>
-<tr><td><strong>0.9.0 → mới nhất</strong></td><td>✅ Trang này (đã verify trên <code>0.10.0</code>)</td><td>Đăng nhập trả về <code>{ data: { token } }</code>; API key qua <code>POST /api/v1/api-keys</code> (tiền tố <code>lbk_</code>); bộ lọc item chấp nhận định dạng JSON <em>và</em> ngoặc vuông; site mặc định <code>__default__</code>.</td></tr>
+<tr><td><strong>0.9.0 → mới nhất</strong></td><td>✅ Trang này (đã verify trên <code>1.0.0-rc.1</code>)</td><td>Đăng nhập trả về <code>{ data: { token } }</code>; API key qua <code>POST /api/v1/api-keys</code> (tiền tố <code>lbk_</code>); bộ lọc item chấp nhận định dạng JSON <em>và</em> ngoặc vuông; site mặc định <code>__default__</code>.</td></tr>
 <tr><td>&lt; 0.9.0</td><td>⚠️ Chưa bao phủ</td><td>Các bản cũ hơn trước thời điểm có các hợp đồng trên. Hãy nâng cấp lên ≥ 0.9.0, hoặc điều chỉnh các cuộc gọi auth/filter theo phiên bản của bạn.</td></tr>
 </tbody>
 </table>
@@ -478,7 +612,11 @@ Tutorial này được **ghim vào phiên bản LumiBase tối thiểu** và ch
 - `GET /api/v1/items/:collection` bộ lọc chấp nhận **cả** `filter=<JSON>` và
   dạng ngoặc vuông `filter[field][_op]=value` (JSON ưu tiên hơn nếu gửi cả hai); `sort=<csv>`
 - `GET /api/v1/site` trả về tenant đang hoạt động; id mặc định `__default__`
-- `@lumibase/sdk` `createClient({ url, siteId, token }).items(c).readMany(...)`
+- `lumibase` (re-export `@lumibase/sdk`) —
+  `createLumiClient({ url, siteId, token }).with(legacyRest()).items(c).list(...)` /
+  `.detail(id)`; mỗi dòng là `ItemRow` với trường nội dung nằm trong `.data`
+- `lumibase types` / `types --check` đọc `GET /api/v1/typegen/schema`, vốn đòi
+  principal là **staff user** (API key nhận `403`)
 - Giới hạn tốc độ trả về `429 RATE_LIMITED` kèm `Retry-After`; mục "Production & security" bao phủ thêm `503 RATE_LIMIT_UNAVAILABLE` và
   header `Deprecation`/`Sunset`, cả hai **được thêm từ `0.24.0`** (luồng cốt lõi ở trên vẫn hoạt động không đổi từ `0.9.0`)
 
diff --git a/examples/nextjs-blog/.env.example b/examples/nextjs-blog/.env.example
index 9d8b132d7..b3286323f 100644
--- a/examples/nextjs-blog/.env.example
+++ b/examples/nextjs-blog/.env.example
@@ -1,8 +1,11 @@
-# Base URL of the LumiBase API server
+# Base URL of the LumiBase CMS API
 LUMIBASE_URL=http://127.0.0.1:1989
 
-# Bearer Token or API Key from LumiBase Studio
-LUMIBASE_TOKEN=your-lumibase-api-token-or-dev-token
+# Read-only API key from LumiBase Studio (Settings → API keys).
+# Give it a role that can only READ the collections this site renders — never
+# an admin token. Server-side only: no NEXT_PUBLIC_ prefix, so it stays out of
+# the browser bundle.
+LUMIBASE_TOKEN=lbk_xxxxxxxxxxxxxxxxxxxxxxxx
 
-# Active Tenant Site ID
-LUMIBASE_SITE_ID=your-site-id
+# Tenant (site) id. `__default__` unless you created more sites.
+LUMIBASE_SITE_ID=__default__
diff --git a/examples/nextjs-blog/README.md b/examples/nextjs-blog/README.md
index 41aee8257..63b1a6bc1 100644
--- a/examples/nextjs-blog/README.md
+++ b/examples/nextjs-blog/README.md
@@ -1,56 +1,170 @@
-# Next.js Blog Example with LumiBase GraphQL
+# Next.js Blog Example
 
-This is a minimal, performance-optimized blog application built with Next.js (App Router, Server Components) that fetches data from LumiBase's **GraphQL API** using the `@lumibase/sdk` `graphql()` plugin.
+A minimal blog built with Next.js (App Router, Server Components) that reads
+published posts from a LumiBase CMS through the **`lumibase`** package.
 
-## Features
-- **GraphQL Fetching**: Queries the per-tenant GraphQL endpoint (`POST /api/v1/graphql`) directly inside React Server Components via `lumi.query(...)`.
-- **Type-Safety**: Each query is typed through a generic on `lumi.query<T>(...)` for compiler checks and auto-completion.
-- **Dynamic SSG / ISR**: Demonstrates `generateStaticParams` for pre-rendering pages and `revalidate = 60` for Incremental Static Regeneration.
+`lumibase` is the one dependency you install: its library entry re-exports the
+JS/TS client, and the same package provides the `lumibase` CLI used below for
+type generation. `@lumibase/sdk` remains supported and exports the identical
+client — see [Using `@lumibase/sdk` instead](#using-lumibasesdk-instead).
 
-## GraphQL usage
+This example is **standalone**: copy the directory anywhere outside the
+LumiBase repo and it installs from the registry with no workspace linking.
 
-The client attaches the GraphQL plugin in [`src/lib/lumi.ts`](src/lib/lumi.ts):
+## Prerequisites
 
-```ts
-import { createLumiClient, graphql } from '@lumibase/sdk';
+You need a **running LumiBase CMS** with content to read — this app is only the
+frontend. Follow the [Next.js quickstart](../../docs/en/tutorials/nextjs-quickstart.md)
+to start the CMS, complete the setup wizard, create a `posts` collection, and
+mint an API key.
 
-export const lumi = createLumiClient({ url, token, siteId }).with(graphql());
-```
+This example expects a `posts` collection with the fields `title` (string),
+`body` (text) and `author` (string), and at least one item set to
+**published**.
 
-The schema is built **per tenant at runtime** from your collections. For a `posts`
-collection you get `posts(filter, sort, limit, offset, status, search)` and
-`posts_by_id(id)`. Structural columns are camelCase (`createdAt`); content fields
-keep their declared names. Example list query:
-
-```graphql
-query ListPosts($limit: Int) {
-  posts(status: "published", sort: ["-createdAt"], limit: $limit) {
-    id
-    title
-    content
-    author
-    createdAt
-  }
-}
-```
+## Getting started
 
-See [`docs/en/api/graphql-api-spec.md`](../../docs/en/api/graphql-api-spec.md) for the
-full GraphQL surface (filters, mutations, nested relations, subscriptions).
+1. **Configure the environment**
 
-## Getting Started
-
-1. **Configure Environment Variables**:
-   Copy `.env.example` to `.env.local` and fill in the values:
    ```bash
    cp .env.example .env.local
    ```
-   Set `LUMIBASE_TOKEN` and `LUMIBASE_SITE_ID` to match your local setup or cloud deploy.
 
-2. **Install & Run**:
+   Set `LUMIBASE_URL`, `LUMIBASE_SITE_ID` and `LUMIBASE_TOKEN`. Use a
+   **read-only** API key — the example only lists and reads items. None of
+   these are `NEXT_PUBLIC_*`, so the token stays server-side.
+
+2. **Install and run**
+
    ```bash
-   pnpm install
-   pnpm dev
+   npm install
+   npm run dev
    ```
 
-3. **Open the Application**:
-   Navigate to `http://localhost:3000`.
+3. Open <http://localhost:3000>.
+
+## How it works
+
+The client is built once in [`src/lib/lumi.ts`](src/lib/lumi.ts):
+
+```ts
+import { createLumiClient, legacyRest } from 'lumibase';
+
+export const lumi = createLumiClient<Schema>({ url, token, siteId }).with(legacyRest());
+```
+
+Pages then use the typed resource helpers from Server Components:
+
+```ts
+// list — drafts are filtered out by the server
+const { data } = await lumi.items('posts').list({
+  status: 'published',
+  sort: ['-created_at'],
+  limit: 50,
+});
+
+// detail
+const { data: post } = await lumi.items('posts').detail(id);
+```
+
+Two details worth knowing:
+
+- **Content fields live under `.data`.** A row is an `ItemRow`: structural
+  columns (`id`, `status`, `createdAt`, …) sit at the top level, while your
+  declared fields are nested — `post.data.title`, not `post.title`.
+- **`status` is a list parameter, not a filter**, and sorting uses the
+  structural column's snake_case name (`-created_at`).
+
+Every non-2xx response throws a `LumiError` carrying `.status`, which
+[`src/app/posts/[id]/page.tsx`](src/app/posts/[id]/page.tsx) maps to Next.js's
+`notFound()`:
+
+```ts
+try {
+  const res = await lumi.items('posts').detail(id);
+  post = res.data;
+} catch (err) {
+  if (err instanceof LumiError && err.status === 404) return notFound();
+  throw err;
+}
+```
+
+## Caching
+
+**Both** routes set `export const revalidate = 60`. The list page needs it, and
+so does the detail page — `generateStaticParams` on its own renders each post
+once at build time and then caches it forever, so edits made in Studio would
+never appear. Declaring `revalidate` is what makes the detail page refresh too.
+
+Publishing or editing in Studio is visible to the API immediately, while the
+rendered pages keep serving their cached copy until the window elapses. Lower
+`revalidate`, or use `cache: 'no-store'`, if a page must be always-fresh.
+
+A post published *after* the build is not in `generateStaticParams`. The detail
+route leaves `dynamicParams` at its default (`true`), so Next renders that post
+on demand the first time it is requested and caches it like the rest.
+
+## Type generation
+
+`lumibase types` generates TypeScript definitions from the live schema into
+`src/lumibase-types.d.ts` (path configured in
+[`lumibase.config.json`](lumibase.config.json)), and the generated file is
+committed:
+
+```bash
+npm run types          # write the types
+npm run types:check    # CI: fail if the committed file is stale
+```
+
+> **Typegen needs a different credential from the one this app runs with.**
+> `GET /api/v1/typegen/schema` sits behind the Studio access wall, which
+> requires a **staff user** principal — an API key is rejected with `403` even
+> when its role grants `schema:read`. Use a staff user's access token for
+> typegen (a build-time/CI secret), and keep the read-only API key for the
+> runtime reads. `lumibase doctor` reports which credential it resolved.
+
+The output is deterministic — no host, site id or timestamp in the header — so
+it can be committed and verified in CI:
+
+```yaml
+- run: npm ci
+- run: npx lumibase types --check
+  env:
+    LUMIBASE_URL: ${{ secrets.LUMIBASE_URL }}
+    LUMIBASE_SITE_ID: ${{ secrets.LUMIBASE_SITE_ID }}
+    LUMIBASE_TOKEN: ${{ secrets.LUMIBASE_TYPEGEN_TOKEN }}
+```
+
+`--check` exits `0` when the committed file matches the live schema and
+non-zero when it drifts, without writing anything.
+
+## Security notes
+
+- **Keep the token on the server.** Every fetch here runs in a Server
+  Component. Never move it to `NEXT_PUBLIC_LUMIBASE_TOKEN` — that ships the
+  credential to every visitor.
+- **Use least privilege.** Give the key a role whose policy grants only
+  `read` on the collections you render. A policy rule of
+  `{"status": {"_eq": "published"}}` makes the server withhold drafts even if a
+  request asks for them.
+- **Never use an admin token in a frontend.** It can write and delete content.
+
+## Using `@lumibase/sdk` instead
+
+`lumibase` re-exports `@lumibase/sdk`, so the imports are interchangeable — the
+exported `createLumiClient`, `legacyRest` and `LumiError` are the *same*
+objects. If your project already depends on the SDK directly, swap the import:
+
+```ts
+import { createLumiClient, legacyRest } from '@lumibase/sdk';
+```
+
+In that case point typegen at the same package so the generated file imports
+from what you installed:
+
+```bash
+lumibase types --import-from @lumibase/sdk
+```
+
+(or set `typegen.importFrom` in `lumibase.config.json`). The `lumibase` CLI is
+still what generates the types.
diff --git a/examples/nextjs-blog/lumibase.config.json b/examples/nextjs-blog/lumibase.config.json
new file mode 100644
index 000000000..a2833915f
--- /dev/null
+++ b/examples/nextjs-blog/lumibase.config.json
@@ -0,0 +1,7 @@
+{
+  "url": "http://127.0.0.1:1989",
+  "siteId": "__default__",
+  "typegen": {
+    "out": "src/lumibase-types.d.ts"
+  }
+}
diff --git a/examples/nextjs-blog/package.json b/examples/nextjs-blog/package.json
index 47305fb31..dcb523947 100644
--- a/examples/nextjs-blog/package.json
+++ b/examples/nextjs-blog/package.json
@@ -6,10 +6,12 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "types": "lumibase types",
+    "types:check": "lumibase types --check"
   },
   "dependencies": {
-    "@lumibase/sdk": "workspace:*",
+    "lumibase": "^1.0.0-rc.1",
     "next": "^15.5.19",
     "react": "^18.3.0",
     "react-dom": "^18.3.0"
diff --git a/examples/nextjs-blog/src/app/layout.tsx b/examples/nextjs-blog/src/app/layout.tsx
new file mode 100644
index 000000000..766711a7b
--- /dev/null
+++ b/examples/nextjs-blog/src/app/layout.tsx
@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+
+export const metadata = {
+  title: 'LumiBase Next.js Blog',
+  description: 'Posts served from a LumiBase collection.',
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body style={{ margin: 0, backgroundColor: '#fff' }}>{children}</body>
+    </html>
+  );
+}
diff --git a/examples/nextjs-blog/src/app/page.tsx b/examples/nextjs-blog/src/app/page.tsx
index fbfccde3d..10fa89bb2 100644
--- a/examples/nextjs-blog/src/app/page.tsx
+++ b/examples/nextjs-blog/src/app/page.tsx
@@ -3,28 +3,20 @@ import { lumi, type Post } from '@/lib/lumi';
 
 export const revalidate = 60; // Revalidate every 60 seconds (ISR)
 
-// GraphQL query: list published posts, newest first.
-// The `posts` field + its arguments are generated per tenant from your schema.
-const LIST_POSTS = /* GraphQL */ `
-  query ListPosts($limit: Int) {
-    posts(status: "published", sort: ["-createdAt"], limit: $limit) {
-      id
-      title
-      content
-      author
-      createdAt
-    }
-  }
-`;
-
 export default async function HomePage() {
   let posts: Post[] = [];
   let errorMsg = '';
 
   try {
-    // Fetch only 'published' status posts via GraphQL
-    const data = await lumi.query<{ posts: Post[] }>(LIST_POSTS, { limit: 50 });
-    posts = data.posts;
+    // `status: 'published'` is a dedicated list parameter, not a filter.
+    // Drafts are excluded by the server, so they can never leak here.
+    // Structural columns sort by their snake_case name (`-created_at`).
+    const { data } = await lumi.items('posts').list({
+      status: 'published',
+      sort: ['-created_at'],
+      limit: 50,
+    });
+    posts = data;
   } catch (err: any) {
     errorMsg = err.message || 'Failed to fetch posts from LumiBase';
   }
@@ -34,7 +26,7 @@ export default async function HomePage() {
       <header style={styles.header}>
         <h1 style={styles.title}>LumiBase Next.js Blog</h1>
         <p style={styles.subtitle}>
-          Example app displaying posts fetched via the LumiBase GraphQL API.
+          Example app displaying posts fetched with the LumiBase SDK.
         </p>
       </header>
 
@@ -49,14 +41,14 @@ export default async function HomePage() {
         <div style={styles.grid}>
           {posts.map((post) => (
             <article key={post.id} style={styles.card}>
-              <h2 style={styles.cardTitle}>{post.title}</h2>
+              <h2 style={styles.cardTitle}>{post.data.title}</h2>
               <p style={styles.cardMeta}>
-                By {post.author} • {new Date(post.createdAt || Date.now()).toLocaleDateString()}
+                By {post.data.author} • {new Date(post.createdAt).toLocaleDateString()}
               </p>
               <p style={styles.cardExcerpt}>
-                {post.content.length > 150
-                  ? `${post.content.slice(0, 150)}...`
-                  : post.content}
+                {post.data.body.length > 150
+                  ? `${post.data.body.slice(0, 150)}...`
+                  : post.data.body}
               </p>
               <Link href={`/posts/${post.id}`} style={styles.cardLink}>
                 Read More →
diff --git a/examples/nextjs-blog/src/app/posts/[id]/page.tsx b/examples/nextjs-blog/src/app/posts/[id]/page.tsx
index 7ac7797eb..9c8996620 100644
--- a/examples/nextjs-blog/src/app/posts/[id]/page.tsx
+++ b/examples/nextjs-blog/src/app/posts/[id]/page.tsx
@@ -1,43 +1,33 @@
 import Link from 'next/link';
 import { notFound } from 'next/navigation';
+import { LumiError } from 'lumibase';
 import { lumi, type Post } from '@/lib/lumi';
 
 interface PostPageProps {
-  params: {
-    id: string;
-  };
+  params: Promise<{ id: string }>;
 }
 
-// GraphQL query for a single post by id (`posts_by_id` is generated per tenant).
-const GET_POST = /* GraphQL */ `
-  query GetPost($id: ID!) {
-    posts_by_id(id: $id) {
-      id
-      title
-      content
-      author
-      status
-      createdAt
-    }
-  }
-`;
+// Revalidate on the same cadence as the list page. Without this the route
+// would be cached indefinitely: `generateStaticParams` alone pre-renders each
+// post once at build time and never refreshes it, so edits made in Studio
+// would never reach the detail page.
+export const revalidate = 60;
 
-// Lightweight query used only to collect ids for static generation.
-const LIST_POST_IDS = /* GraphQL */ `
-  query ListPostIds($limit: Int) {
-    posts(status: "published", limit: $limit) {
-      id
-    }
-  }
-`;
+// A post published after the build is not in `generateStaticParams`. Leaving
+// `dynamicParams` at its default (`true`) lets Next render it on demand the
+// first time it is requested, then cache it like the rest.
+export const dynamicParams = true;
 
-// Generate static params for all published posts for static generation (SSG)
+// Pre-render a page per published post. The reader credential cannot see
+// drafts, so this list is exactly the public set.
 export async function generateStaticParams() {
   try {
-    const data = await lumi.query<{ posts: Pick<Post, 'id'>[] }>(LIST_POST_IDS, {
+    const { data } = await lumi.items('posts').list({
+      status: 'published',
+      fields: ['id'],
       limit: 100,
     });
-    return data.posts.map((post) => ({ id: post.id }));
+    return data.map((post) => ({ id: post.id }));
   } catch (err) {
     console.error('Failed to generate static params for posts:', err);
     return [];
@@ -45,20 +35,20 @@ export async function generateStaticParams() {
 }
 
 export default async function PostDetailPage({ params }: PostPageProps) {
-  let post: Post | null = null;
+  const { id } = await params;
+  let post: Post;
 
   try {
-    // Fetch a single post detail via GraphQL
-    const data = await lumi.query<{ posts_by_id: Post | null }>(GET_POST, {
-      id: params.id,
-    });
-    post = data.posts_by_id;
+    // A draft (or unknown id) answers 404 for this credential — the SDK
+    // turns every non-2xx into a `LumiError` carrying the status.
+    const res = await lumi.items('posts').detail(id);
+    post = res.data;
   } catch (err) {
-    // If not found or API error, fall back to 404
-    return notFound();
+    if (err instanceof LumiError && err.status === 404) return notFound();
+    throw err;
   }
 
-  if (!post || post.status !== 'published') {
+  if (post.status !== 'published') {
     return notFound();
   }
 
@@ -69,16 +59,16 @@ export default async function PostDetailPage({ params }: PostPageProps) {
       </Link>
       
       <header style={styles.header}>
-        <h1 style={styles.title}>{post.title}</h1>
+        <h1 style={styles.title}>{post.data.title}</h1>
         <div style={styles.meta}>
-          <span>By <strong>{post.author}</strong></span>
+          <span>By <strong>{post.data.author}</strong></span>
           <span>•</span>
-          <span>{new Date(post.createdAt || Date.now()).toLocaleDateString()}</span>
+          <span>{new Date(post.createdAt).toLocaleDateString()}</span>
         </div>
       </header>
 
       <div style={styles.content}>
-        {post.content.split('\n\n').map((para: string, idx: number) => (
+        {post.data.body.split('\n\n').map((para: string, idx: number) => (
           <p key={idx} style={styles.paragraph}>
             {para}
           </p>
diff --git a/examples/nextjs-blog/src/lib/lumi.ts b/examples/nextjs-blog/src/lib/lumi.ts
index 758740a47..f8bec357f 100644
--- a/examples/nextjs-blog/src/lib/lumi.ts
+++ b/examples/nextjs-blog/src/lib/lumi.ts
@@ -1,4 +1,4 @@
-import { createLumiClient, graphql } from '@lumibase/sdk';
+import { createLumiClient, legacyRest, type ItemRow } from 'lumibase';
 
 const url = process.env.LUMIBASE_URL || 'http://127.0.0.1:1989';
 const token = process.env.LUMIBASE_TOKEN || '';
@@ -10,22 +10,33 @@ if (!token || !siteId) {
   );
 }
 
-// 1. Initialize the client and attach the GraphQL composable plugin.
-//    `.with(graphql())` adds `query()` / `mutate()` that hit POST /api/v1/graphql.
-export const lumi = createLumiClient({
-  url,
-  token,
-  siteId,
-}).with(graphql());
-
-// 2. Shape of a `posts` item as exposed by the per-tenant GraphQL schema.
-//    Content fields (`title`, `content`, `author`) keep their declared names;
-//    structural columns are surfaced as camelCase (`createdAt`, not `created_at`).
-export interface Post {
-  id: string;
+// Content fields of the `posts` collection, exactly as declared in Studio.
+// A schema maps a collection name to its *data* shape only — structural
+// columns (id, status, createdAt, …) are added by `ItemRow` below.
+export interface PostFields {
   title: string;
-  content: string;
+  body: string;
   author: string;
-  status: 'draft' | 'published';
-  createdAt: string;
+  [key: string]: unknown;
 }
+
+// `DefaultSchema` is an index-signature type, so the schema is written as a
+// type alias with one entry per collection you read.
+export type Schema = {
+  posts: PostFields;
+};
+
+/** A `posts` row as the REST API returns it: fields live under `.data`. */
+export type Post = ItemRow<PostFields>;
+
+// The client is created once and reused. `legacyRest()` adds the typed
+// resource helpers (`.items('posts').list()` / `.detail(id)`) over
+// `GET /api/v1/items/posts`.
+//
+// This module is imported only from Server Components, so the token never
+// reaches the browser bundle. Keep it out of `NEXT_PUBLIC_*`.
+export const lumi = createLumiClient<Schema>({
+  url,
+  token,
+  siteId,
+}).with(legacyRest());
diff --git a/examples/nextjs-blog/src/lumibase-types.d.ts b/examples/nextjs-blog/src/lumibase-types.d.ts
new file mode 100644
index 000000000..e23015fe2
--- /dev/null
+++ b/examples/nextjs-blog/src/lumibase-types.d.ts
@@ -0,0 +1,27 @@
+// Generated by `lumibase types` — do not edit by hand.
+// Re-run the command after changing collections or fields.
+
+import type { ID, Locale } from 'lumibase';
+import type { Brand } from 'lumibase';
+
+export interface Posts {
+  readonly id: Brand<'PostsId', string>;
+  status: string;
+  sort: number;
+  readonly user_created?: string | null;
+  readonly user_updated?: string | null;
+  readonly created_at: string;
+  readonly updated_at: string;
+  readonly deleted_at?: string | null;
+  author?: string | null;
+  body?: string | null;
+  title: string | null;
+}
+
+export type PostsExpanded = Posts;
+
+export interface LumibaseCollections {
+  posts: Posts;
+}
+
+export type LumibaseSchema = LumibaseCollections;