@@ -0,0 +1,10 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): validation examples guard nullable fields, hooks teach `body`, the `requires:` table names `mailbox` and `package-registry`, `os generate` drops `agent`
+
+Clause-②: no
+Metadata-protocol: none
+
+`objectstack-data` `rules/validation.md` now guards every ordering or arithmetic operand in its examples with `!= null` (the due-date, date-range, amount, discount and order-total predicates) and states the rule once: an unguarded `<` or `+` on a field with no `required: true` / `defaultValue` is refused at publish. Its external-validation hook and the `examples-objects.md` lifecycle hook are written as a sandboxed `body`, and the `SKILL.md` index names the inline `handler` only as the deprecated form; the validation section says a `body` has no outbound HTTP, so an external-API check goes through a Connector recipe. `objectstack-platform` lists `mailbox` (`@objectstack/service-mailbox`) and `package-registry` (`@objectstack/service-package`) in the `requires:` table, and `references/operations.md` no longer offers the retired `os generate agent`. The platform behaviour already shipped; this release only teaches it.
@@ -43,7 +43,7 @@ Detailed rules, with incorrect/correct examples:
 - **[Validation Rules](./rules/validation.md)** — All validation types, script inversion, severity levels
 - **[Index Strategy](./rules/indexing.md)** — btree/gin/gist/fulltext, composite indexes, partial indexes
 - **[Data Lifecycle & Retention](./rules/lifecycle.md)** — `lifecycle` classes (record/audit/telemetry/transient/event), retention/TTL/rotation/archive policies; ❗ append-only objects must declare one (distinct from lifecycle *hooks* below); plus the **save notice** a hook hands the saver (`ctx.notice`)
-- **[Lifecycle Hooks](./references/data-hooks.md)** — the lifecycle events, `handler` vs sandboxed `body` (ctx + capability contract), registration, canonical patterns
+- **[Lifecycle Hooks](./references/data-hooks.md)** — the lifecycle events, the sandboxed `body` (ctx + capability contract; the inline `handler` is deprecated), registration, canonical patterns
 - **[Datasources & Federation](./rules/datasources.md)** — `defineDatasource`, external/federated objects (`remoteName`/`columnMap`), auto-connect gating, credentials; ❌ no `field.columnName` on external objects
 - **[Security & Access Control](./rules/security.md)** — permission sets, assignment rows, RLS policies, `secret` / `requiredPermissions`, `tenancy`, platform-global posture
 
 
@@ -90,6 +90,16 @@
         "must_contain": ["INVALID_FIELD", "is_not_null"],
         "must_not_contain": ["starts_with"]
       }
+    },
+    {
+      "id": 10,
+      "prompt": "An `account` whose `tax_id` appears in our `blocked_tax_id` object must not save, on create or edit. Our tax authority also offers a lookup API; can the same hook call it?",
+      "expected_output": "A `beforeInsert` / `beforeUpdate` hook on `account` with a sandboxed `body: { language: 'js', source, capabilities: ['api.read'] }`: the source returns when the write carries no `tax_id`, reads `ctx.api.object('blocked_tax_id').findOne({ where: { tax_id: ctx.input.tax_id } })` and throws when it finds a row. Not a validation rule (there is no `custom` / `async` type) and not the deprecated inline `handler`. The tax-authority API is not called from the hook: a `body` has no outbound HTTP, so that check goes through a Connector recipe.",
+      "files": [],
+      "assertions": {
+        "must_contain": ["beforeInsert", "beforeUpdate", "language: 'js'", "'api.read'", "ctx.api.object("],
+        "must_not_contain": ["handler:", "HookContext", "'http.fetch'"]
+      }
     }
   ]
 }
@@ -53,7 +53,8 @@
           "unique: 'organization'",
           "state_machine",
           "transitions",
-          "record."
+          "record.",
+          "!= null"
         ],
         "must_not_contain": [
           "type: 'unique'",
 
@@ -113,25 +113,23 @@ Declared `indexes` are a separate decision — see
 
 <!-- os:check -->
 ```typescript
-import { defineHook, HookContext } from '@objectstack/spec/data';
+import { defineHook } from '@objectstack/spec/data';
 
 export default defineHook({
   name: 'crm_account_defaults',
   object: 'account',
   events: ['beforeInsert'],
-  handler: async (ctx: HookContext) => {
-    if (!ctx.input.industry) {
-      ctx.input.industry = 'Other';
-    }
-    ctx.input.created_at = new Date().toISOString();
+  body: {
+    language: 'js',
+    source: `if (!ctx.input.industry) ctx.input.industry = 'Other';`,
   },
 });
 ```
 
-The `handler` above is the inline (in-process) form. The **preferred**,
-metadata-native form is a sandboxed `body` — `{ language: 'js', source, capabilities }`
-run in an isolated VM, the shape that AI/Studio-authored hooks and every build
-artifact carry. See [references/data-hooks.md](./data-hooks.md) for all 8
+`body` is the metadata-native form: `source` is a function body run against
+`ctx` in an isolated VM (`capabilities` gates `ctx.api`, `ctx.log`, …), the
+shape AI/Studio-authored hooks and every build artifact carry. The inline
+`handler` function is deprecated. See [references/data-hooks.md](./data-hooks.md) for all 8
 lifecycle events, both registration forms, the **sandboxed `body` ctx + capability
 contract**, and the canonical patterns.
 
 
@@ -6,8 +6,6 @@
 - [External / Custom Validation → Lifecycle Hooks](#external--custom-validation--lifecycle-hooks) · [Validation Properties](#validation-properties)
 - [Incorrect vs Correct](#incorrect-vs-correct)
 
-Comprehensive guide for implementing validation rules in ObjectStack.
-
 ## Available Rule Types
 
 The **complete** set of `type` discriminators accepted by `ValidationRuleSchema`:
@@ -25,9 +23,7 @@ There is no other type. In particular:
 
 - **No `unique` type** (removed from the spec) — enforce uniqueness
   with a **unique index** ([see below](#uniqueness--use-unique-indexes)).
-- **No `async` / `custom` type** — external checks and arbitrary validation
-  code belong in a `beforeInsert` / `beforeUpdate` **lifecycle hook**
-  (see [references/data-hooks.md](../references/data-hooks.md)).
+- **No `async` / `custom` type** — see [External / Custom Validation](#external--custom-validation--lifecycle-hooks).
 
 ## Expression Syntax
 
@@ -36,6 +32,8 @@ There is no other type. In particular:
 as CEL. Record fields are addressed as `record.<field>`; on update the prior
 row is available as `previous.<field>`. CEL operator and null-handling rules:
 see **objectstack-formula**.
+An ordering or arithmetic operator on a field with no `required: true` /
+`defaultValue` is refused at publish unless a `!= null` test guards it.
 
 **⚠️ CRITICAL:** For `script` **and** `cross_field`, the predicate expresses
 the **failure** condition — validation **fails** when it evaluates to `true`.
@@ -51,14 +49,15 @@ from a transition onward is not this tool: use `requiredWhen` or a field bound
 stored row (see **Choose by intent — invariant or transition gate** in
 `SKILL.md`).
 
+<!-- os:check -->
 ```typescript
 import { P } from '@objectstack/spec';
 
 const validations = [
   {
     name: 'prevent_past_dates',
     type: 'script',
-    condition: P`record.due_date < today()`,  // ❌ Fails when this is TRUE
+    condition: P`record.due_date != null && record.due_date < today()`,  // ❌ Fails when this is TRUE
     message: 'Due date cannot be in the past',
     severity: 'error',
     events: ['insert', 'update'],
@@ -70,16 +69,13 @@ const validations = [
 
 ```typescript
 // Prevent negative values
-condition: P`record.amount < 0`
+condition: P`record.amount != null && record.amount < 0`
 
 // Require field when another field has value
 condition: P`record.status == 'approved' && isBlank(record.approver_id)`
 
 // Date range validation
-condition: P`record.end_date < record.start_date`
-
-// Conditional required field
-condition: P`record.type == 'enterprise' && isBlank(record.account_manager)`
+condition: P`record.start_date != null && record.end_date != null && record.end_date < record.start_date`
 ```
 
 > On **insert**, an optional field omitted from the payload reads as `null`
@@ -160,14 +156,14 @@ validations: [
   {
     name: 'date_range',
     type: 'cross_field',
-    condition: P`record.end_date <= record.start_date`,  // ❌ TRUE = invalid
+    condition: P`record.start_date != null && record.end_date != null && record.end_date <= record.start_date`,  // ❌ TRUE = invalid
     message: 'End date must be after start date',
     fields: ['start_date', 'end_date'],
   },
   {
     name: 'discount_limit',
     type: 'cross_field',
-    condition: P`record.discount_amount > record.subtotal * 0.5`,
+    condition: P`record.discount_amount != null && record.subtotal != null && record.discount_amount > record.subtotal * 0.5`,
     message: 'Discount cannot exceed 50% of subtotal',
     fields: ['discount_amount', 'subtotal'],
   },
@@ -227,7 +223,7 @@ With an `otherwise` branch:
 {
   name: 'payment_validation',
   type: 'conditional',
-  when: P`record.order_total > 10000`,
+  when: P`record.order_total != null && record.order_total > 10000`,
   message: 'Order validation',
   then: {
     name: 'manager_approval_required',
@@ -246,21 +242,27 @@ With an `otherwise` branch:
 
 ## External / Custom Validation → Lifecycle Hooks
 
-Calling an external API, hitting another object, or running arbitrary code is
-**not** a validation type. Implement it as a `beforeInsert` / `beforeUpdate`
-lifecycle hook and throw on failure:
+Hitting another object or running arbitrary code is **not** a validation type.
+Implement it as a `beforeInsert` / `beforeUpdate` lifecycle hook whose `body`
+throws on failure. A `body` has no outbound HTTP: an external-API check goes
+through a Connector recipe ([data-hooks.md](../references/data-hooks.md#capabilities--the-complete-list)).
 
+<!-- os:check -->
 ```typescript
-import { defineHook, HookContext } from '@objectstack/spec/data';
+import { defineHook } from '@objectstack/spec/data';
 
 const taxIdCheck = defineHook({
-  name: 'crm_tax_id_external_check',
+  name: 'crm_tax_id_blocklist_check',
   object: 'account',
   events: ['beforeInsert', 'beforeUpdate'],
-  handler: async (ctx: HookContext) => {
-    if (ctx.input.tax_id && !(await verifyTaxId(ctx.input.tax_id))) {
-      throw new Error('Invalid tax ID');
-    }
+  body: {
+    language: 'js',
+    source: `
+      if (!ctx.input.tax_id) return;
+      const hit = await ctx.api.object('blocked_tax_id').findOne({ where: { tax_id: ctx.input.tax_id } });
+      if (hit) throw new Error('Tax ID is blocked');
+    `,
+    capabilities: ['api.read'],
   },
 });
 ```
@@ -301,30 +303,8 @@ priority: 100    // Application validations (default)
 priority: 1000   // User validations (run last)
 ```
 
-Lower numbers execute **first**.
-
 ## Incorrect vs Correct
 
-### ❌ Incorrect — Script Logic Inverted
-
-```typescript
-{
-  type: 'script',
-  condition: P`record.amount > 0`,  // ❌ Fails when amount > 0 (inverted!)
-  message: 'Amount must be positive',
-}
-```
-
-### ✅ Correct — Script Logic
-
-```typescript
-{
-  type: 'script',
-  condition: P`record.amount <= 0`,  // ✅ Fails when amount <= 0
-  message: 'Amount must be positive',
-}
-```
-
 ### ❌ Incorrect — Validation Fires Too Often
 
 ```typescript
 
@@ -165,9 +165,7 @@ what the platform owns.
   generic connector executors in `plugins:`; and the eight generator barrels
   (`objects`, `views`, `actions`, `flows`, `dashboards`, `apps`, `skills`, `picklists`),
   each `src/*/index.ts` handed to the stack key of its name through
-  `exportsOf` — the scaffolded `AGENTS.md` says how to add to them. The
-  memory driver and the Hono server are NOT in the file — the CLI
-  auto-registers both at boot
+  `exportsOf` — the scaffolded `AGENTS.md` says how to add to them.
 
 The five retired remote templates (`todo`, `compliance`, `content`,
 `contracts`, `procurement`) are refused by name.
@@ -305,7 +303,8 @@ token through the `CAPABILITY_PROVIDERS` registry in
 |:--|:--|
 | `automation` | `@objectstack/service-automation` — flows, and any declarative `connectors:` entry |
 | `analytics` `cache` `storage` `queue` `job` `messaging` `realtime` `settings` `sms` `push` | `@objectstack/service-` + the token ([the `push` block](./references/operations.md#mobile-push)) |
-| `marketplace` | `@objectstack/service-package` |
+| `mailbox` | `@objectstack/service-mailbox` — inbound mail |
+| `marketplace` `package-registry` | `@objectstack/service-package` |
 | `audit` `email` `sharing` `approvals` `webhooks` | `@objectstack/plugin-` + the token |
 | `pinyin-search` | `@objectstack/plugin-pinyin-search` |
 | `mcp` | `@objectstack/mcp` |
 
@@ -301,6 +301,38 @@
           "os push"
         ]
       }
+    },
+    {
+      "id": 18,
+      "prompt": "Our `os serve` app must receive customers' inbound email into mailboxes and link each message to its records. What turns that on?",
+      "expected_output": "`requires: ['mailbox']` on the stack root: the token mounts `@objectstack/service-mailbox` (inbound mail). No `MailboxServicePlugin` instance in `plugins:` and no hand-built mail objects; `defineStack` rejects an unknown token at authoring time.",
+      "files": [],
+      "assertions": {
+        "must_contain": [
+          "requires",
+          "'mailbox'",
+          "@objectstack/service-mailbox"
+        ],
+        "must_not_contain": [
+          "MailboxServicePlugin("
+        ]
+      }
+    },
+    {
+      "id": 19,
+      "prompt": "Scaffold, with the CLI, an object, a flow and an AI agent for our support app.",
+      "expected_output": "`os generate object <name>` and `os generate flow <name>` scaffold the first two. There is no agent generator: `os generate agent` is retired (agents are platform-internal, ADR-0063 §2), so the AI extension is a skill, `os generate skill <name>`. No hand-written `defineAgent` file.",
+      "files": [],
+      "assertions": {
+        "must_contain": [
+          "os generate object",
+          "os generate flow",
+          "os generate skill"
+        ],
+        "must_not_contain": [
+          "defineAgent("
+        ]
+      }
     }
   ]
 }
@@ -20,7 +20,7 @@
 | `os compile` | Compile to portable JSON artifact (for runtime hydration) |
 | `os serve` | Serve a compiled stack in production mode |
 | `os start` | Quick-start a server: auto-compiles `objectstack.config.ts` when no artifact is present, and falls back to an empty kernel with the Console + marketplace when there is no config at all. It does **not** validate env or apply migrations — run `os validate` / `os migrate apply` yourself |
-| `os generate <kind>` | Scaffold an object / view / flow / agent from a template |
+| `os generate <kind>` | Scaffold an object / view / flow / skill from a template |
 
 ## Verify your work
Original file line number	Diff line number	Diff line change
`@@ -90,6 +90,16 @@`
`90`	`90`	`"must_contain": ["INVALID_FIELD", "is_not_null"],`
`91`	`91`	`"must_not_contain": ["starts_with"]`
`92`	`92`	`}`
	`93`	`+ },`
	`94`	`+ {`
	`95`	`+ "id": 10,`
	`96`	+ "prompt": "An `account` whose `tax_id` appears in our `blocked_tax_id` object must not save, on create or edit. Our tax authority also offers a lookup API; can the same hook call it?",
	`97`	+ "expected_output": "A `beforeInsert` / `beforeUpdate` hook on `account` with a sandboxed `body: { language: 'js', source, capabilities: ['api.read'] }`: the source returns when the write carries no `tax_id`, reads `ctx.api.object('blocked_tax_id').findOne({ where: { tax_id: ctx.input.tax_id } })` and throws when it finds a row. Not a validation rule (there is no `custom` / `async` type) and not the deprecated inline `handler`. The tax-authority API is not called from the hook: a `body` has no outbound HTTP, so that check goes through a Connector recipe.",
	`98`	`+ "files": [],`
	`99`	`+ "assertions": {`
	`100`	`+ "must_contain": ["beforeInsert", "beforeUpdate", "language: 'js'", "'api.read'", "ctx.api.object("],`
	`101`	`+ "must_not_contain": ["handler:", "HookContext", "'http.fetch'"]`
	`102`	`+ }`
`93`	`103`	`}`
`94`	`104`	`]`
`95`	`105`	`}`