feat(cli): make os validate the author-time gate; steer scaffolds/skills/examples/docs to it

.changeset/cli-validate-author-gate.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/cli": minor
+"create-objectstack": minor
+---
+
+Make `os validate` the author-time verification gate and steer scaffolds toward it.
+
+- **`os validate`** now runs the same CEL/predicate gate as `os build`/`os compile`
+ (ADR-0032): every `visible`/`disabled`/`requiredWhen`/validation/flow/sharing
+ predicate is checked for CEL syntax and `record.<field>` existence on the target
+ object. It already ran the protocol schema and widget-binding checks; the
+ expression gate closes the gap so a bare field ref (`done` instead of
+ `record.done`) — which silently hides an action on every record at runtime
+ (#2183/#2185) — fails validation instead of shipping. `os validate` is now a
+ read-only superset of the build's checks (no artifact emitted).
+- **`create-objectstack`** now emits an `AGENTS.md` (and `.github/copilot-instructions.md`)
+ into every generated project instructing coding agents to run `npm run validate`
+ after editing metadata, aligns the blank template's `dev`/`start` scripts with the
+ example apps (`objectstack dev`/`objectstack start`), and sharpens the post-create
+ "Next steps" output.

content/docs/getting-started/cli.mdx

@@ -47,7 +47,7 @@ Open [http://localhost:3000/_console/](http://localhost:3000/_console/) — you'
 ### Validate & Build
 
 ```bash
-os validate # Check schema correctness
+os validate # Check schema + CEL predicates + widget bindings (no artifact)
 os compile # Build production artifact → dist/objectstack.json
 ```
 
@@ -303,7 +303,7 @@ shape they accept. See [Source vs Artifact](#source-vs-artifact) below.
 | Command | Description |
 |---------|-------------|
 | `os compile [config]` | Compile configuration to a JSON artifact (`dist/objectstack.json`) |
-| `os validate [config]` | Validate configuration against the ObjectStack Protocol schema |
+| `os validate [config]` | Validate schema, CEL predicates, and widget bindings — the same gates as `os compile`/`os build`, no artifact emitted |
 | `os info [config]` | Display metadata summary (objects, fields, apps, agents, etc.) |
 
 #### `os compile`
@@ -346,7 +346,9 @@ over HTTP from another runtime. See [`os start`](#os-start) and
 
 #### `os validate`
 
-Standalone schema validation with rich error output. Use to check your configuration without compiling.
+The fast, artifact-free verification gate. It runs the **same structural and
+semantic checks as `os compile`/`os build`** but writes no `dist/`, so it is the
+command to run after every metadata edit. Use it before reporting a change done.
 
 ```bash
 os validate # Validate current directory
@@ -355,16 +357,37 @@ os validate --json # JSON output for CI
 os validate path/to/config # Validate specific file
 ```
 
+**Gates run (each exits non-zero with a located, corrective message):**
+1. **Protocol schema** — the stack conforms to `ObjectStackDefinitionSchema`
+ (`@objectstack/spec`).
+2. **CEL / predicate validation (ADR-0032)** — every `visible` / `disabled` /
+ `requiredWhen` / validation rule / flow condition / sharing rule is parsed
+ for CEL syntax **and** checked that each `record.<field>` reference exists on
+ the target object. This catches a **bare field ref** (`done` instead of
+ `record.done`) that would otherwise evaluate to `null` and silently hide an
+ action on every record (#2183/#2185).
+3. **Widget-binding integrity (ADR-0021)** — every dashboard widget's
+ `dataset` / `dimensions` / `values` resolves to a declared dataset/field, so
+ a dangling binding fails here instead of rendering an empty chart.
+
 **Options:**
 - `--strict` — Treat warnings as errors (exit code 1)
 - `--json` — Output results as JSON
 
-**Warnings checked:**
+**Warnings checked (advisory, non-blocking unless `--strict`):**
 - Missing `manifest.id` (required for deployment)
 - Missing `manifest.namespace` (required for multi-app hosting)
 - No objects defined
 - No apps or plugins defined
 
+<Callout type="tip">
+`os validate` and `os build` share one validator, so a config that passes
+`os validate` will not fail the build on schema/predicate/binding grounds. In a
+scaffolded project these are wired as `npm run validate` and `npm run build`;
+your `AGENTS.md` tells coding agents to run `npm run validate` after editing
+metadata. See [Validating metadata](/docs/guides/validating-metadata).
+</Callout>
+
 #### `os info`
 
 Displays a summary of your metadata without compilation or validation:

content/docs/guides/meta.json

@@ -12,6 +12,7 @@
  "seed-data",
  "common-patterns",
  "formula",
+ "validating-metadata",
  "analytics-datasets",
  "airtable-dashboard-analysis",
  "---Building---",

content/docs/guides/validating-metadata.mdx

@@ -0,0 +1,104 @@
+---
+title: Validating Metadata
+description: Why ObjectStack metadata mistakes fail silently at runtime, and the one command that catches them at author time — run it after every metadata edit.
+---
+
+# Validating Metadata
+
+ObjectStack metadata is data, not code paths — so most mistakes are **not** caught
+by the TypeScript compiler. They pass `tsc`, load fine, and then fail **silently
+at runtime**. The fix is one command you run after every metadata edit:
+
+```bash
+os validate # schema + CEL predicates + widget bindings — no artifact
+```
+
+In a scaffolded project this is wired as `npm run validate`. Your generated
+`AGENTS.md` instructs coding agents (Claude Code, Cursor, Copilot) to run it
+after editing metadata.
+
+## Why typecheck isn't enough
+
+Two classes of bug type-check cleanly but break at runtime:
+
+### 1. Bare-field predicates
+
+Predicates — an action's `visible`/`disabled`, a field's `requiredWhen`, a
+validation rule, a flow condition, a sharing rule — are **CEL expressions**, and
+they reference record fields through the `record.` scope:
+
+```ts
+// ✗ Wrong — `done` is a bare reference. It type-checks (it's just a string),
+// but at runtime it resolves to null → the action is hidden on EVERY record.
+{ name: 'mark_done', visible: '!done' }
+
+// ✓ Right
+{ name: 'mark_done', visible: '!record.done' }
+```
+
+This is the trap behind the recurring "the button never shows / the rule never
+fires" bugs (#2183/#2185). `os validate` parses every predicate and checks that
+each `record.<field>` exists on the target object, so the bare ref fails the
+gate with a located, did-you-mean message instead of shipping.
+
+### 2. Dangling widget bindings
+
+A dashboard widget points at a `dataset` and reads `dimensions`/`values` from it.
+If a name doesn't resolve, the chart renders **empty** — no error (ADR-0021).
+`os validate` resolves every binding against the declared datasets and fails on a
+dangling one.
+
+## The one gate, two entry points
+
+`os validate` and `os build` (alias `os compile`) run the **same** validator:
+
+| | `os validate` | `os build` |
+|---|---|---|
+| Protocol schema (Zod) | ✓ | ✓ |
+| CEL / predicate validation | ✓ | ✓ |
+| Widget-binding integrity | ✓ | ✓ |
+| Emits `dist/objectstack.json` | — | ✓ |
+
+So `os validate` is the fast inner-loop check (no artifact); `os build` is what
+you run when you need the deployable artifact. A config that passes `os validate`
+will not fail `os build` on schema/predicate/binding grounds.
+
+<Callout type="info">
+`os lint` is a **separate** pass — style and convention checks (snake_case
+naming, required labels, namespace prefixes, data-model patterns). Run it too,
+but it does not replace `os validate`, and `os validate` does not replace it.
+</Callout>
+
+## The workflow
+
+```bash
+# after editing any *.object.ts / *.view.ts / *.action.ts / *.flow.ts / *.dashboard.ts
+npm run validate # os validate — schema + predicates + bindings
+npm run typecheck # tsc --noEmit — types against @objectstack/spec
+```
+
+**Rule of thumb: never report a metadata change as done until `npm run validate`
+passes.** In the example apps the equivalent is `pnpm --filter <pkg> validate`
+(`pnpm verify` in `app-showcase`, which chains validate + typecheck + test).
+
+### Checking a single expression
+
+To validate one CEL expression *before* you write it into a file — for example
+inside an AI build loop — call the `validate_expression` agent tool, which runs
+the same predicate validator inline. See the
+[objectstack-formula skill](/docs/guides/formula).
+
+## In CI
+
+Both commands support `--json` and exit non-zero on failure:
+
+```yaml
+- name: Validate ObjectStack metadata
+ run: npx objectstack validate --strict --json
+```
+
+## See also
+
+- [Command Line Interface](/docs/getting-started/cli) — full `os validate` / `os build` reference
+- [Formula & Predicates](/docs/guides/formula) — the CEL surface and `record.` scope
+- [Data Modeling](/docs/guides/data-modeling) — objects, fields, validations, sharing

examples/AGENTS.md

@@ -0,0 +1,33 @@
+# Examples — Agent Instructions
+
+These are reference ObjectStack apps (`app-crm`, `app-todo`, `app-showcase`).
+They double as the canonical shape of a user-scaffolded project, so the metadata
+here should always be correct.
+
+## Verify after every metadata change
+
+ObjectStack metadata mistakes fail **silently at runtime**, not at edit time:
+
+- a bare field ref in a predicate (`done` instead of `record.done`) evaluates to
+ `null` and silently hides the action/validation on every record (#2183/#2185);
+- a dangling dashboard widget binding renders an empty chart (ADR-0021).
+
+`objectstack validate` catches both at author time. It runs the same gates as
+`objectstack build` — Zod protocol schema, CEL/predicate validation with
+`record.<field>` existence checks, and widget-binding integrity — but emits no
+`dist/`, so it is the fast inner-loop check. It exits non-zero with a located,
+corrective message.
+
+After editing any `*.object.ts` / `*.view.ts` / `*.action.ts` / `*.flow.ts` /
+`*.dashboard.ts`, run the gate for that example:
+
+```bash
+pnpm --filter @objectstack/example-crm validate # + typecheck, test
+pnpm --filter @objectstack/example-todo validate
+pnpm --filter @objectstack/example-showcase verify # validate + typecheck + test
+```
+
+**Do not report a metadata change as done until `validate` passes.** When in
+doubt about how to express a predicate or binding, consult the relevant
+`objectstack-*` skill (e.g. `objectstack-formula` for CEL, `objectstack-ui` for
+views/actions/dashboards).

examples/app-crm/package.json

@@ -14,6 +14,7 @@
  "dev": "objectstack dev",
  "start": "objectstack start",
  "build": "objectstack build",
+ "validate": "objectstack validate",
  "typecheck": "tsc --noEmit",
  "test": "vitest run"
  },

examples/app-showcase/package.json

@@ -15,9 +15,10 @@
  "dev": "objectstack dev --seed-admin",
  "start": "objectstack start",
  "build": "objectstack build",
+ "validate": "objectstack validate",
  "typecheck": "tsc --noEmit",
  "test": "vitest run",
- "verify": "pnpm typecheck && pnpm test",
+ "verify": "pnpm validate && pnpm typecheck && pnpm test",
  "test:smoke": "playwright test --config=playwright.config.ts"
  },
  "dependencies": {

examples/app-todo/package.json

@@ -14,6 +14,7 @@
  "dev": "objectstack dev",
  "start": "objectstack start",
  "build": "objectstack build",
+ "validate": "objectstack validate",
  "typecheck": "tsc --noEmit",
  "test": "objectstack test",
  "test:ai": "tsx test/ai.test.ts",

packages/cli/src/commands/validate.ts

@@ -5,6 +5,7 @@ import chalk from 'chalk';
 import { ZodError } from 'zod';
 import { ObjectStackDefinitionSchema, normalizeStackInput } from '@objectstack/spec';
 import { loadConfig } from '../utils/config.js';
+import { validateStackExpressions } from '../utils/validate-expressions.js';
 import { validateWidgetBindings } from '../utils/validate-widget-bindings.js';
 import {
  printHeader,
@@ -19,7 +20,8 @@ import {
 } from '../utils/format.js';
 
 export default class Validate extends Command {
- static override description = 'Validate ObjectStack configuration against the protocol schema';
+ static override description =
+ 'Validate ObjectStack configuration against the protocol schema, CEL expressions, and widget bindings (no artifact emitted)';
 
  static override args = {
  config: Args.string({ description: 'Configuration file path', required: false }),
@@ -70,6 +72,37 @@ export default class Validate extends Command {
  this.exit(1);
  }
 
+ // 2b. Expression validation (ADR-0032 §1a/1b) — the same gate `os build`
+ // runs, brought to the read-only check so authors catch it without
+ // emitting an artifact. CEL predicates in actions/validations/flows/
+ // sharing/hooks are checked for syntax AND that `record.<field>`
+ // references resolve on the target object. This is what catches a
+ // BARE field ref (`done` instead of `record.done`) that would
+ // otherwise silently hide an action on every record (#2183/#2185).
+ if (!flags.json) printStep('Validating expressions (ADR-0032)...');
+ const exprIssues = validateStackExpressions(result.data as Record<string, unknown>);
+ const exprErrors = exprIssues.filter((i) => i.severity !== 'warning');
+ const exprWarnings = exprIssues.filter((i) => i.severity === 'warning');
+
+ if (exprErrors.length > 0) {
+ if (flags.json) {
+ console.log(JSON.stringify({
+ valid: false,
+ errors: exprErrors,
+ warnings: exprWarnings,
+ duration: timer.elapsed(),
+ }, null, 2));
+ this.exit(1);
+ }
+ console.log('');
+ printError(`Expression validation failed (${exprErrors.length} issue${exprErrors.length > 1 ? 's' : ''})`);
+ for (const i of exprErrors.slice(0, 50)) {
+ console.log(` • ${i.where}: ${i.message}`);
+ console.log(chalk.dim(` source: \`${i.source}\``));
+ }
+ this.exit(1);
+ }
+
  // 3. Dashboard widget reference integrity (issue #1721) — a semantic
  // cross-reference pass the protocol schema cannot express: every
  // widget's `dataset`/`dimensions`/`values` and chartConfig
@@ -108,7 +141,7 @@ export default class Validate extends Command {
  valid: true,
  manifest: config.manifest,
  stats,
- warnings: widgetWarnings,
+ warnings: [...exprWarnings, ...widgetWarnings],
  duration: timer.elapsed(),
  }, null, 2));
  return;
@@ -117,6 +150,9 @@ export default class Validate extends Command {
  // 5. Warnings (non-blocking)
  const warnings: string[] = [];
 
+ for (const i of exprWarnings) {
+ warnings.push(`${i.where}: ${i.message}`);
+ }
  for (const f of widgetWarnings) {
  warnings.push(`${f.where}: ${f.message}`);
  }

packages/create-objectstack/src/index.ts

@@ -335,6 +335,49 @@ function rewriteProjectIdentity(
  md = md.replace(/^#\s+.*$/m, `# ${title}`);
  fs.writeFileSync(readmePath, md);
  }
+
+ writeAgentGuides(targetDir, title, projectName);
+}
+
+// Emit the cross-agent guidance file (AGENTS.md) and the GitHub Copilot variant
+// (.github/copilot-instructions.md) from the shared template. This is what tells
+// the coding agent to run `npm run validate` after editing metadata — the gate
+// that catches bare-field predicates and dangling bindings that otherwise fail
+// silently at runtime. Skip either file if the template already shipped its own,
+// so a curated template can override the default.
+function writeAgentGuides(targetDir: string, title: string, projectName: string) {
+ const templatePath = path.join(BUNDLED_TEMPLATES_DIR, 'AGENTS.md');
+ let template: string;
+ try {
+ template = fs.readFileSync(templatePath, 'utf8');
+ } catch (err: any) {
+ if (err?.code === 'ENOENT') return; // bundled template absent — nothing to emit
+ throw err;
+ }
+
+ const rendered = template
+ .replace(/\{\{PROJECT_TITLE\}\}/g, title)
+ .replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+
+ // Atomic exclusive-create (the `wx` flag) instead of existsSync()+writeFileSync():
+ // it fails with EEXIST if the file already exists, so a curated template that
+ // ships its own guide is preserved — without the check-then-write TOCTOU race a
+ // separate existence check introduces.
+ writeIfAbsent(path.join(targetDir, 'AGENTS.md'), rendered);
+
+ const copilotPath = path.join(targetDir, '.github', 'copilot-instructions.md');
+ fs.mkdirSync(path.dirname(copilotPath), { recursive: true });
+ writeIfAbsent(copilotPath, rendered);
+}
+
+// Create a file only if it does not already exist, atomically — no time-of-check
+// to time-of-use gap between an existence test and the write.
+function writeIfAbsent(filePath: string, contents: string) {
+ try {
+ fs.writeFileSync(filePath, contents, { flag: 'wx' });
+ } catch (err: any) {
+ if (err?.code !== 'EEXIST') throw err;
+ }
 }
 
 // ─── CLI Program ────────────────────────────────────────────────────
@@ -450,7 +493,8 @@ const program = new Command()
  console.log(chalk.dim(' npm install'));
  }
  console.log(chalk.dim(' npm run dev # Start development server'));
- console.log(chalk.dim(' npm run validate # Check configuration'));
+ console.log(chalk.dim(' npm run validate # Verify metadata: schema + predicates + bindings'));
+ console.log(chalk.dim(' # (run after every metadata edit — see AGENTS.md)'));
  if (options.skipInstall || options.skipSkills) {
  console.log('');
  console.log(chalk.bold(' AI Skills (recommended):'));