fix(app-shell): previews read only spec-declared keys (#3275, #3281) (#3285)

The previews and the console samples were wrong TOGETHER, so the gallery
looked healthy. objectui#3266 corrected the samples and the gallery
immediately rendered LESS: agent TOOLS/KNOWLEDGE, skill TRIGGER PHRASES,
app's per-item row and `Dashboard` badge, datasource CAPABILITIES all
vanished or degraded. Those blocks were only ever lit up by metadata that
cannot be saved. Renderer half of that finding; same fix as PR #3258.

Deleted (retiredKey tombstones, rejected by name): `agent.tools`
(#3894), `agent.knowledge` (#3896), `skill.triggerPhrases` (#3896).

AppPreview/AppNavCanvas: read the `type` discriminator and each branch's
own target key; route via `resolveHref`, the shell's own nav -> URL
mapping. `homePageId` renders as the nav item id it is, resolved to the
entry it selects, never as a path.

DatasourcePreview: `capabilities` rendered as the boolean-flag OBJECT it
is (`Array.isArray` lit up only for the form the schema refuses); dropped
`driver ?? d.type` and the `isDefault ?? default` pill.

SkillPreview: trigger conditions as three columns field/operator/value,
replacing `cond.expression ?? cond.value` under a `cond.type` gutter.

ValidationPreview (#3281): removed the `unique`/`async`/`custom` branches
(each redirects to the layer that owns the job), the `condition ??
expression` and `pattern ?? regex` aliases for keys that never existed,
fixed `conditional` to read `when`, and added the missing `json_schema`
branch. `validation.object` stays — anchors.ts matches standalone rules by
it.

Verified in the preview gallery before/after per designer.


Claude-Session: https://claude.ai/code/session_01NVPjPzmmAJ2Ngtvgg5MSRa

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/previews-read-only-spec-declared-keys.md

@@ -0,0 +1,76 @@
+---
+"@object-ui/app-shell": patch
+---
+
+Five metadata designers stop rendering keys `@objectstack/spec` rejects, and start
+rendering the keys it declares (objectui#3275, objectui#3281).
+
+The previews and the console's sample drafts had been wrong TOGETHER, which is
+why the gallery looked healthy. objectui#3266 corrected the samples and the
+gallery immediately rendered LESS — agent's TOOLS and KNOWLEDGE blocks, skill's
+TRIGGER PHRASES, app's per-item row and `Dashboard` badge, and datasource's
+CAPABILITIES all vanished or degraded. Nothing had broken: those blocks were only
+ever lit up by metadata that cannot be saved. This is the renderer half of that
+finding, and the same fix objectui#3236 / PR #3258 made to `ToolPreview`.
+
+A preview that renders a rejected key does not just show something useless — it
+tells the author "this is correct" until publish refuses it. For AI-generated
+metadata that is where a stale key hides and multiplies, so every read below was
+deleted rather than kept behind a fallback (AGENTS.md #0.1).
+
+**Retired keys, deleted** — each is a `retiredKey()` tombstone rejected by name:
+`agent.tools` (objectstack#3894 — an agent reaches exactly the tools its skills
+declare, ADR-0064), `agent.knowledge` (objectstack#3896 — it never scoped
+retrieval), `skill.triggerPhrases` (objectstack#3896 — phrases were never matched
+against a user's message).
+
+**`AppPreview` / `AppNavCanvas`** — `AppSchema.navigation` is a discriminated
+union on `type` whose every branch is `.strict()`. Both surfaces ignored the
+discriminator: kind came from `it.object` / `it.dashboard`, the route from
+`it.path ?? it.href ?? it.route ?? it.url`, and the landing from
+`landingRoute ?? landing ?? defaultRoute ?? '/'`. Not one of those is a key
+(`landing` was removed in objectstack#4001), so the reading was exactly inverted —
+a valid app showed generic badges, no targets and an invented `Landing: /`. Now
+`type` is the badge, each branch's own key is the target
+(`objectName`/`pageName`/`dashboardName`/`url`/`reportName`/`componentRef`/
+`actionDef.actionName`), and the route comes from `resolveHref`, the shell's own
+nav → URL mapping that `useNavPins` and `SearchResultsPage` already share — so a
+link in the preview is the link the runtime follows. `homePageId` is rendered as
+the nav item **id** it is, resolved to the entry it selects; it is never printed
+as a path.
+
+**`DatasourcePreview`** — `capabilities` is a `DatasourceCapabilities` object of
+boolean flags, and the preview tested `Array.isArray`, lighting the block up only
+for the pre-17 token array the schema refuses. It now lists the flags set to
+`true`. The `driver ?? d.type` fallback is gone (the schema's own hint is
+`type` → `driver`), as is the `default` pill behind `isDefault ?? default` —
+routing is declared at stack level via `datasourceMapping`, never on the
+datasource.
+
+**`SkillPreview`** — the trigger-conditions table read `cond.expression ??
+cond.value` under a `cond.type` gutter, so a spec-valid condition rendered as
+`COND | sales_order` with the field it tests and the operator it applies both
+invisible. It is now three columns — `field` / `operator` / `value` — straight off
+`SkillTriggerConditionSchema`, and a row missing one of those required cells says
+so instead of rendering a blank that reads as fine.
+
+**`ValidationPreview`** (objectui#3281) — drew nine rule types where the union has
+six. `unique`, `async` and `custom` were removed by one paragraph of
+`validation.zod.ts`, because a rule must be a deterministic, synchronous,
+side-effect-free predicate over one record; each now redirects to the layer that
+does the job (a unique **index** — a SELECT-then-INSERT rule is racy, TOCTOU — a
+form-layer check, a lifecycle hook). Two alias fallbacks went with them:
+`condition ?? expression` and `pattern ?? regex`, where neither `expression` nor
+`pattern` has ever been a key on any branch — which is precisely why a bogus
+`expression` sat unnoticed in the console sample. Two branches were also simply
+wrong: `conditional` read `condition` instead of its `when` (a valid rule showed
+"No expression set", and its nested `then`/`otherwise` now render), and
+`json_schema` had no branch at all, so a valid rule displayed "Unknown rule type".
+
+`validation.object` is deliberately still read: `anchors.ts` registers a
+standalone `validation` resource matched by `anchorByField('object')`, so a
+standalone rule genuinely carries it. Not every key a union omits is residue.
+
+Verified in the preview gallery before and after, per designer; each preview also
+gains tests that feed a spec-valid draft and assert the block renders, then feed a
+stale draft carrying the retired key and assert nothing renders from it.

packages/app-shell/src/views/metadata-admin/previews/AgentPreview.test.tsx

@@ -0,0 +1,112 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * AgentPreview must not render retired `AgentSchema` keys (objectui#3275).
+ *
+ * `agent.tools` (objectstack#3894) and `agent.knowledge` (objectstack#3896)
+ * are `retiredKey()` tombstones in `@objectstack/spec` 17 — `AgentSchema`
+ * rejects each BY NAME, so no draft carrying them can be saved. The preview
+ * nevertheless read both off the raw draft and painted a TOOLS chip strip and
+ * a `KNOWLEDGE (RAG)` block.
+ *
+ * That inverted the preview's whole purpose. The two shapes an author can
+ * write are (a) spec-valid, which rendered NOTHING in those blocks, and
+ * (b) retired, which rendered a full, healthy-looking summary right up until
+ * publish refused it. The designer was rewarding the unsaveable draft — the
+ * tolerant-consumer failure AGENTS.md #0.1 names, and the reason objectui#3266
+ * saw the gallery render LESS after its samples were corrected.
+ *
+ * These tests pin both directions: a VALID draft renders its capabilities, and
+ * a STALE draft renders nothing from the retired keys. The second half matters
+ * because the names survive in the spec's tombstone guidance, so a future
+ * reader has a plausible-looking reason to "restore" them.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { AgentPreview } from './AgentPreview';
+
+afterEach(cleanup);
+
+/** Parses clean against `ObjectStackSchema` — mirrors the gallery's sample. */
+const VALID_DRAFT = {
+  name: 'sales_copilot',
+  label: 'Sales Copilot',
+  role: 'Assistant for sales reps',
+  active: true,
+  model: { provider: 'openai', model: 'gpt-4o', temperature: 0.4, maxTokens: 2048 },
+  instructions: 'You are a helpful sales assistant.',
+  skills: ['summarize_account', 'draft_email'],
+} satisfies Record<string, unknown>;
+
+/** A draft as an author wrote it *before* the removals — both retired keys present. */
+const STALE_DRAFT = {
+  ...VALID_DRAFT,
+  tools: [
+    { type: 'objectql', name: 'query_orders' },
+    { type: 'http', name: 'lookup_company' },
+  ],
+  knowledge: { sources: [{ id: 'sales_playbook', type: 'vector' }] },
+} satisfies Record<string, unknown>;
+
+function renderPreview(draft: Record<string, unknown>) {
+  return render(
+    <AgentPreview {...({ type: 'agent', name: 'sales_copilot' } as never)} draft={draft} />,
+  );
+}
+
+describe('AgentPreview renders what a spec-valid agent declares', () => {
+  it('renders the skills chips — the whole of an agent capability surface', () => {
+    renderPreview(VALID_DRAFT);
+    expect(screen.getByText('Capabilities')).toBeTruthy();
+    expect(screen.getByText('Skills')).toBeTruthy();
+    expect(screen.getByText('summarize_account')).toBeTruthy();
+    expect(screen.getByText('draft_email')).toBeTruthy();
+  });
+
+  it('keeps persona, model pills and instructions', () => {
+    renderPreview(VALID_DRAFT);
+    expect(screen.getByText('Sales Copilot')).toBeTruthy();
+    expect(screen.getByText('sales_copilot')).toBeTruthy();
+    expect(screen.getByText('Assistant for sales reps')).toBeTruthy();
+    expect(screen.getByText('openai · gpt-4o')).toBeTruthy();
+    expect(screen.getByText('You are a helpful sales assistant.')).toBeTruthy();
+  });
+
+  it('says where tools come from, so the missing TOOLS block is not read as a gap', () => {
+    renderPreview(VALID_DRAFT);
+    expect(screen.getByText(/tools come from the attached skills/i)).toBeTruthy();
+  });
+
+  it('an agent with no skills gets an explicit empty state, not a blank', () => {
+    renderPreview({ ...VALID_DRAFT, skills: [] });
+    expect(screen.getByText(/no skills attached/i)).toBeTruthy();
+  });
+});
+
+describe('AgentPreview renders nothing from retired AgentSchema keys', () => {
+  it('paints no TOOLS block for a stale draft carrying `tools`', () => {
+    renderPreview(STALE_DRAFT);
+    // The chip-list heading is gone with the read...
+    expect(screen.queryByText('Tools')).toBeNull();
+    // ...and so is every tool name it used to advertise.
+    expect(screen.queryByText('query_orders')).toBeNull();
+    expect(screen.queryByText('lookup_company')).toBeNull();
+  });
+
+  it('paints no KNOWLEDGE (RAG) block for a stale draft carrying `knowledge`', () => {
+    renderPreview(STALE_DRAFT);
+    expect(screen.queryByText(/knowledge/i)).toBeNull();
+    expect(screen.queryByText('sales_playbook')).toBeNull();
+  });
+
+  it('renders the stale draft exactly as if the retired keys were absent', () => {
+    const { container: stale } = renderPreview(STALE_DRAFT);
+    const staleHtml = stale.innerHTML;
+    cleanup();
+    const { container: valid } = renderPreview(VALID_DRAFT);
+    // The strongest form of "the key is not read": the two drafts differ only
+    // by `tools`/`knowledge`, so identical output proves neither reaches the DOM.
+    expect(staleHtml).toBe(valid.innerHTML);
+  });
+});

packages/app-shell/src/views/metadata-admin/previews/AgentPreview.tsx

@@ -8,10 +8,20 @@
  *   • Persona header (avatar, label, role, active flag).
  *   • Model config (provider, model id, temperature, max tokens).
  *   • System prompt / instructions in a scrollable monospace block.
- *   • Skills + Tools as two collapsible chip lists.
- *   • Knowledge sources (RAG indices) when present.
+ *   • Skills as a chip list.
  *   • Planning + guardrails callouts.
  *
+ * NOT shown — `agent.tools` and `agent.knowledge` (objectui#3275).
+ * Both are `retiredKey()` tombstones in `@objectstack/spec` 17
+ * (objectstack#3894 / #3896): `AgentSchema` rejects them BY NAME, so a
+ * draft carrying either cannot be saved. This preview used to read both
+ * and paint a TOOLS chip strip plus a `KNOWLEDGE (RAG)` block, which told
+ * the author their draft was fine right up until publish refused it —
+ * the tolerant-consumer shape AGENTS.md #0.1 forbids. An agent reaches
+ * exactly the tools its skills declare (ADR-0064), and grounding is
+ * described in `instructions`, so the Skills list below is the whole
+ * truth about what this agent can do.
+ *
  * We intentionally do **not** wire a live chat into this preview:
  *   1. The draft may reference unsaved skills/tools the runtime can't
  *      resolve, so a chat would just error.
@@ -27,7 +37,6 @@ import {
   Activity,
   Bot,
   BrainCircuit,
-  Database,
   ExternalLink,
   Eye,
   EyeOff,
@@ -36,7 +45,6 @@ import {
   ScrollText,
   Shield,
   Sparkles,
-  Wrench,
 } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import type { MetadataPreviewProps } from '../preview-registry';
@@ -49,11 +57,6 @@ interface ModelConfig {
   maxTokens?: number;
 }
 
-interface ToolRef {
-  type?: string;
-  name?: string;
-}
-
 export function AgentPreview({ name, draft }: MetadataPreviewProps) {
   const d = draft as Record<string, unknown>;
   const agentName = String(d.name ?? name ?? '');
@@ -64,14 +67,12 @@ export function AgentPreview({ name, draft }: MetadataPreviewProps) {
   const active = d.active !== false;
   const model = (d.model ?? {}) as ModelConfig;
   const skills: string[] = Array.isArray(d.skills) ? (d.skills as string[]) : [];
-  const tools: ToolRef[] = Array.isArray(d.tools) ? (d.tools as ToolRef[]) : [];
-  const knowledge = d.knowledge as Record<string, unknown> | undefined;
   const planning = d.planning as Record<string, unknown> | undefined;
   const memory = d.memory as Record<string, unknown> | undefined;
   const guardrails = d.guardrails as Record<string, unknown> | undefined;
   const permissions = Array.isArray(d.permissions) ? (d.permissions as string[]) : [];
 
-  if (!agentName && !instructions && skills.length === 0 && tools.length === 0) {
+  if (!agentName && !instructions && skills.length === 0) {
     return (
       <PreviewShell hint="agent">
         <PreviewMessage>Fill in label, role, and instructions in the Form tab to see the agent preview.</PreviewMessage>
@@ -136,34 +137,24 @@ export function AgentPreview({ name, draft }: MetadataPreviewProps) {
               )}
             </Section>
 
-            {/* Capabilities */}
-            <Section title="Capabilities" icon={Wrench}>
+            {/* Capabilities — skills only. `tools` is a retired tombstone
+                (objectstack#3894); an agent's reachable tool surface IS the
+                union of its skills' own `tools` (ADR-0064). */}
+            <Section title="Capabilities" icon={Sparkles}>
               <div className="space-y-2">
                 <ChipList
                   label="Skills"
-                  emptyHint="Attach skills (preferred)"
+                  emptyHint="No skills attached — this agent can reach no tools."
                   items={skills.map((s) => ({ key: s, label: s }))}
                   icon={Sparkles}
                   tone="violet"
                   mono
                 />
-                <ChipList
-                  label="Tools"
-                  emptyHint="No direct tools (skills can provide them)"
-                  items={tools.map((t, i) => ({ key: `${t.type ?? ''}:${t.name ?? i}`, label: t.name ?? String(t), hint: t.type }))}
-                  icon={Wrench}
-                  tone="blue"
-                  mono
-                />
+                <div className="text-[10px] text-muted-foreground">
+                  Tools come from the attached skills; grounding is described in the instructions.
+                </div>
               </div>
             </Section>
-
-            {/* Knowledge */}
-            {knowledge && Object.keys(knowledge).length > 0 && (
-              <Section title="Knowledge (RAG)" icon={Database}>
-                <KnowledgeSummary knowledge={knowledge} />
-              </Section>
-            )}
           </div>
 
           {/* Side rail: planning / memory / guardrails / permissions */}
@@ -207,36 +198,6 @@ export function AgentPreview({ name, draft }: MetadataPreviewProps) {
   );
 }
 
-function KnowledgeSummary({ knowledge }: { knowledge: Record<string, unknown> }) {
-  const sources = Array.isArray(knowledge.sources) ? (knowledge.sources as unknown[]) : [];
-  const indexes = Array.isArray(knowledge.indexes) ? (knowledge.indexes as unknown[]) : [];
-  const items = [...sources, ...indexes];
-  if (items.length === 0) {
-    const keys = Object.keys(knowledge);
-    return (
-      <div className="text-xs text-muted-foreground font-mono">
-        {keys.length ? keys.join(', ') : 'configured'}
-      </div>
-    );
-  }
-  return (
-    <ul className="rounded border bg-background divide-y text-xs">
-      {items.map((s, i) => {
-        const obj = (s ?? {}) as Record<string, unknown>;
-        const id = (obj.id ?? obj.name ?? `source ${i + 1}`) as string;
-        const kind = (obj.type ?? obj.kind ?? '') as string;
-        return (
-          <li key={i} className="flex items-center gap-2 px-2.5 py-1.5">
-            <Database className="h-3 w-3 text-muted-foreground" />
-            <span className="font-mono">{String(id)}</span>
-            {kind && <span className="text-[10px] uppercase text-muted-foreground">{kind}</span>}
-          </li>
-        );
-      })}
-    </ul>
-  );
-}
-
 function Section({
   title,
   icon: Icon,
@@ -262,19 +223,14 @@ function Empty({ children }: { children: React.ReactNode }) {
 }
 
 /**
- * Tone presets for capability chips — keep skills and tools visually
- * distinct at a glance. Full Tailwind class strings (JIT) with light +
- * dark variants.
+ * Tone preset for capability chips. Full Tailwind class strings (JIT)
+ * with light + dark variants.
  */
 const CHIP_TONE = {
   violet: {
     chip: 'border-violet-200 bg-violet-50 text-violet-700 dark:border-violet-900 dark:bg-violet-950/40 dark:text-violet-300',
     icon: 'text-violet-500 dark:text-violet-400',
   },
-  blue: {
-    chip: 'border-blue-200 bg-blue-50 text-blue-700 dark:border-blue-900 dark:bg-blue-950/40 dark:text-blue-300',
-    icon: 'text-blue-500 dark:text-blue-400',
-  },
 } as const;
 
 function ChipList({