Merge pull request #3374 from objectstack-ai/claude/third-party-skills-review-2r4sj1

skills: third-party developer review — fix fabricated/stale surface across all 9 skills

Author: os-zhuang

content/docs/ai/skills-reference.mdx

@@ -45,12 +45,12 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI
 
 | # | Skill | Domain | Path | What it covers |
 | :--- | :--- | :--- | :--- | :--- |
-| 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
+| 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
 | 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
-| 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. |
+| 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, relation expansion, and full-text search. |
 | 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
-| 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. |
-| 6 | [AI](#ai) | `ai` | `skills/objectstack-ai/` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. |
+| 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, scheduled jobs, and webhooks. |
+| 6 | [AI](#ai) | `ai` | `skills/objectstack-ai/` | Design ObjectStack AI skills, tools, knowledge sources, conversations, model registry entries, and MCP integrations. |
 | 7 | [API](#api) | `api` | `skills/objectstack-api/` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |
 | 8 | [i18n](#i18n) | `i18n` | `skills/objectstack-i18n/` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. |
 | 9 | [Formula](#formula) | `expression` | `skills/objectstack-formula/` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. |
@@ -61,7 +61,7 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI
 
 **Domain** `platform` · **Path** `skills/objectstack-platform/`
 
-Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel).
+Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel).
 
 Use when the user is writing `objectstack.config.ts`, building a plugin or driver, wiring a framework adapter, running `os` CLI commands, or planning deployment.
 
@@ -89,7 +89,7 @@ Do not use for querying data (see objectstack-query) or for plugin / kernel hook
 
 **Domain** `query` · **Path** `skills/objectstack-query/`
 
-Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search.
+Construct ObjectQL queries — filters, sorting, pagination, aggregation, relation expansion, and full-text search.
 
 Use when the user is writing a query DSL expression, picking pagination strategy, or designing a list view's filter spec.
 
@@ -117,11 +117,11 @@ Do not use for: data schema (see objectstack-data), interactive screen flows / w
 
 **Domain** `automation` · **Path** `skills/objectstack-automation/`
 
-Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks.
+Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, scheduled jobs, and webhooks.
 
-Use when the user is adding `*.flow.ts` / `*.workflow.ts`, wiring an event-driven rule, or modelling an approval chain.
+Use when the user is adding `*.flow.ts`, wiring an event-driven rule, or modelling an approval chain.
 
-Do not use for data lifecycle hooks at the object layer (see objectstack-data) or for kernel / plugin events (see objectstack-platform). CEL expressions in flow conditions / workflow predicates: load objectstack-formula alongside.
+Do not use for data lifecycle hooks at the object layer (see objectstack-data) or for kernel / plugin events (see objectstack-platform). CEL expressions in flow conditions / edge guards: load objectstack-formula alongside.
 
 **Tags:** `flow`, `workflow`, `trigger`, `approval`, `state-machine`, `scheduled`, `webhook`
 
@@ -131,9 +131,9 @@ Do not use for data lifecycle hooks at the object layer (see objectstack-data) o
 
 **Domain** `ai` · **Path** `skills/objectstack-ai/`
 
-Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations.
+Design ObjectStack AI skills, tools, knowledge sources, conversations, model registry entries, and MCP integrations.
 
-Use when the user is adding `*.agent.ts` / `*.tool.ts` / `*.skill.ts`, configuring an LLM provider, wiring agent tools, or designing an embedding/RAG flow on top of ObjectStack data.
+Use when the user is adding `*.skill.ts` / `*.tool.ts`, configuring an LLM provider, wiring agent tools, or indexing ObjectStack data as a knowledge source for RAG. Agents themselves are platform-internal (`ask` / `build`) — third parties extend them via skills and tools, not by authoring `*.agent.ts`.
 
 Do not use for general LLM prompting questions unrelated to ObjectStack metadata.
 

packages/spec/scripts/build-react-blocks-contract.ts

@@ -77,7 +77,11 @@ function dataProps(schema: any, allow?: string[]): Prop[] {
       name,
       type: renderType(node),
       kind: 'data',
-      required: required.includes(name),
+      // z.toJSONSchema emits output-io semantics, where a `.default()`-carrying
+      // prop is always present — so it lands in `required` even though an author
+      // may omit it. A prop with a default is optional to WRITE, which is what
+      // this contract documents; only default-less required props stay required.
+      required: required.includes(name) && node?.default === undefined,
       description: clip(node?.description),
     }));
 }
@@ -101,7 +105,7 @@ const blocks = REACT_BLOCKS.map((b) => {
 const contract = {
   version: 2,
   adr: 'ADR-0081',
-  source: 'GENERATED from packages/spec/src/ui/react-blocks.ts — data props from the spec zod schemas, binding/controlled/callback from the React overlay.',
+  source: "GENERATED from the REACT_BLOCKS definition in the '@objectstack/spec/ui' module — data props from the spec zod schemas, binding/controlled/callback from the React overlay.",
   note: "Props each component accepts in kind:'react' page source. Reference blocks by their PascalCase tag. kind: data=declarative config (from the spec schema) · binding=connects to data · controlled=React state · callback=React function. These blocks are for DATA. Live data: const adapter = useAdapter(); adapter.find/findOne/create/update. STYLING (ADR-0065) — a page's source is runtime metadata, so the console's build-time Tailwind NEVER scans it: utility classNAMES silently produce no CSS. Do NOT use Tailwind className in page source. (a) Layout/chrome: inline style={} with hsl(var(--token)) theme colors — e.g. color:'hsl(var(--foreground))', background:'hsl(var(--card))', border:'1px solid hsl(var(--border))', and px/flex for layout. (b) Overlays: render <ObjectForm formType='drawer'|'modal' open onOpenChange> (a pre-styled Sheet/Dialog) — never hand-roll a fixed inset-0 backdrop.",
   blocks,
 };
@@ -112,7 +116,7 @@ const esc = (s: string) => String(s).replace(/\|/g, '\\|');
 const L: string[] = [];
 L.push('---');
 L.push('title: React-tier component contract');
-L.push("description: Props each injected component accepts in kind:'react' page source (ADR-0081). GENERATED from packages/spec/src/ui/react-blocks.ts — do not edit by hand.");
+L.push("description: Props each injected component accepts in kind:'react' page source (ADR-0081). GENERATED from the REACT_BLOCKS definition in the '@objectstack/spec/ui' module — do not edit by hand.");
 L.push('---');
 L.push('');
 L.push('{/* GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not edit. */}');

packages/spec/scripts/build-skill-references.ts

@@ -53,6 +53,7 @@ const SKILL_MAP: Record<string, string[]> = {
   'objectstack-query': [
     'data/query.zod.ts',
     'data/filter.zod.ts',
+    'data/date-macros.zod.ts',
   ],
   'objectstack-ai': [
     'ai/agent.zod.ts',
@@ -62,6 +63,8 @@ const SKILL_MAP: Record<string, string[]> = {
     'ai/conversation.zod.ts',
     'ai/mcp.zod.ts',
     'ai/embedding.zod.ts',
+    'ai/knowledge-source.zod.ts',
+    'ai/knowledge-document.zod.ts',
     'ai/usage.zod.ts',
   ],
   'objectstack-api': [
@@ -78,11 +81,13 @@ const SKILL_MAP: Record<string, string[]> = {
   'objectstack-automation': [
     'automation/flow.zod.ts',
     'automation/trigger-registry.zod.ts',
+    'automation/time-relative-trigger.zod.ts',
     'automation/approval.zod.ts',
     'automation/state-machine.zod.ts',
     'automation/execution.zod.ts',
     'automation/webhook.zod.ts',
     'automation/node-executor.zod.ts',
+    'data/validation.zod.ts',
   ],
   'objectstack-ui': [
     'ui/view.zod.ts',
@@ -95,6 +100,7 @@ const SKILL_MAP: Record<string, string[]> = {
     'ui/component.zod.ts',
     'ui/report.zod.ts',
     'ui/theme.zod.ts',
+    'ui/dataset.zod.ts',
   ],
   'objectstack-platform': [
     // project setup (was objectstack-quickstart)
@@ -115,6 +121,10 @@ const SKILL_MAP: Record<string, string[]> = {
     'system/translation.zod.ts',
     'ui/i18n.zod.ts',
   ],
+  'objectstack-formula': [
+    'shared/expression.zod.ts',
+    'data/date-macros.zod.ts',
+  ],
 };
 
 // ── Import resolver ──────────────────────────────────────────────────────────
@@ -174,7 +184,13 @@ function resolveAll(entryFiles: string[]): { files: string[]; missing: string[]
       if (!visited.has(dep)) queue.push(dep);
     }
   }
-  return { files: [...visited].sort(), missing };
+  // Only `src/**/*.zod.ts` ships in the published package (`files` allowlist in
+  // package.json) — a pointer to any other src file 404s in a consumer's
+  // node_modules (#skills-review: lazy-schema.ts, visibility.ts,
+  // public-auth-features.ts all leaked through transitive imports). Traverse
+  // through non-shipping files (they may import shipping ones) but never list them.
+  const shipped = [...visited].filter((rel) => rel.endsWith('.zod.ts'));
+  return { files: shipped.sort(), missing };
 }
 
 // ── JSDoc description extractor ──────────────────────────────────────────────
@@ -213,8 +229,9 @@ function generateIndex(skillName: string, coreFiles: string[], allFiles: string[
   const lines: string[] = [
     `# ${skillName} — Schema References`,
     '',
-    '> **Auto-generated** by `packages/spec/scripts/build-skill-references.ts`.',
-    `> Do not edit — re-run \`pnpm --filter ${SPEC_PKG} run gen:skill-refs\` to update.`,
+    '> **Auto-generated** — do not edit. Maintainers regenerate this in the',
+    `> framework repo with \`pnpm --filter ${SPEC_PKG} run gen:skill-refs\``,
+    '> (not runnable in an installed app).',
     '',
     `Schemas live in the published \`${SPEC_PKG}\` package. Read them directly`,
     'from `node_modules` — there is no local copy in the skill bundle.',
@@ -246,8 +263,10 @@ function generateIndex(skillName: string, coreFiles: string[], allFiles: string[
     `   \`.describe()\` text, enums, and refinements.`,
     `2. TypeScript types: \`import type { … } from '${SPEC_PKG}'\` (or the`,
     '   matching subpath export).',
-    '3. Runtime values: `import { … } from \'' + SPEC_PKG + '\'` — the package',
-    '   re-exports every schema and helper.',
+    '3. Runtime values: import from the **matching subpath** shown in the',
+    `   schema's directory (\`'${SPEC_PKG}/data'\`, \`'${SPEC_PKG}/ai'\`, …).`,
+    '   The root barrel re-exports the common factories, but not every symbol —',
+    '   when in doubt, use the subpath.',
     '',
   );
 

scripts/role-word-baseline.json

@@ -34,12 +34,12 @@
   "content/docs/releases/v14.mdx": 5,
   "content/docs/releases/v16.mdx": 5,
   "content/docs/ui/forms.mdx": 3,
-  "skills/objectstack-ai/SKILL.md": 8,
+  "skills/objectstack-ai/SKILL.md": 6,
   "skills/objectstack-api/SKILL.md": 1,
   "skills/objectstack-automation/SKILL.md": 1,
-  "skills/objectstack-data/SKILL.md": 8,
+  "skills/objectstack-data/SKILL.md": 4,
   "skills/objectstack-data/rules/relationships.md": 1,
-  "skills/objectstack-platform/SKILL.md": 3,
+  "skills/objectstack-platform/SKILL.md": 2,
   "skills/objectstack-query/rules/filters.md": 9,
   "skills/objectstack-ui/SKILL.md": 2
 }

skills/README.md

@@ -1,9 +1,22 @@
 # ObjectStack Skills
 
 Domain-scoped instructions for AI coding assistants (Claude Code, Copilot, Cursor)
-working in the ObjectStack monorepo. Each skill is self-contained: a `SKILL.md`
-with YAML frontmatter, plus a `references/_index.md` that points into the
-authoritative Zod sources in `node_modules/@objectstack/spec/src/...`.
+working in **any ObjectStack app** — this monorepo *and* third-party projects.
+`npm create objectstack` installs them into new apps automatically; existing
+projects add (or update) the bundle with:
+
+```bash
+npx skills add objectstack-ai/framework/skills --all
+```
+
+The `/skills` subpath matters: it is the published catalog boundary — pointing
+the skills CLI at the repo root would also pick up repo-internal skills (#3101).
+
+Each skill is self-contained: a `SKILL.md` with YAML frontmatter, plus a
+`references/_index.md` that points into the authoritative Zod sources in
+`node_modules/@objectstack/spec/src/...` (the published `@objectstack/spec`
+package ships these `.zod.ts` sources, so the pointers resolve in consumer
+apps too).
 
 > **Always read the spec source for exact field shapes.** Skills give shape and
 > intent; the Zod schemas are the truth.
@@ -16,12 +29,12 @@ authoritative Zod sources in `node_modules/@objectstack/spec/src/...`.
 
 | Skill | Domain | What it covers |
 |:------|:-------|:---------------|
-| [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
+| [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
 | [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seeds (`defineSeed()`) that load fixtures and reference data alongside them. |
-| [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. |
+| [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, relation expansion, and full-text search. |
 | [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
-| [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. |
-| [AI](./objectstack-ai/SKILL.md) | `ai` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. |
+| [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Triggers, Approvals, state machines, scheduled jobs, and webhooks. |
+| [AI](./objectstack-ai/SKILL.md) | `ai` | Design ObjectStack AI skills, tools, knowledge sources, conversations, model registry entries, and MCP integrations. |
 | [API](./objectstack-api/SKILL.md) | `api` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. |
 | [i18n](./objectstack-i18n/SKILL.md) | `i18n` | Author ObjectStack translation bundles — object/field labels, view text, app navigation strings, automation messages — and configure locale fallback, coverage reporting, and the per-locale source layout. |
 | [Formula](./objectstack-formula/SKILL.md) | `expression` | Author CEL expressions used across ObjectStack — formula fields, field conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`), validation / sharing / visibility predicates, flow conditions, and dynamic seed values. |
@@ -37,8 +50,13 @@ authoritative Zod sources in `node_modules/@objectstack/spec/src/...`.
 ```
 skills/<skill-name>/
 ├── SKILL.md              # frontmatter + prose guide
-└── references/
-    └── _index.md         # pointers into @objectstack/spec sources
+├── references/
+│   └── _index.md         # generated pointers into @objectstack/spec sources
+│                         # (pnpm --filter @objectstack/spec gen:skill-refs — do not hand-edit)
+├── rules/                # (optional) detailed per-topic rule files linked from SKILL.md
+├── contracts/            # (optional) generated machine-readable contracts (e.g. react-blocks)
+└── evals/                # skill eval fixtures — used by maintainers to score the skill,
+                          # inert (but harmless) in consumer installs
 ```
 
 `SKILL.md` frontmatter fields: