@noodleseed/agent-kit 0.94.0 → 0.96.0

package/skills/codex/examples/stateful-draft/src/server.ts

@@ -0,0 +1,159 @@
+import {
+  annotations,
+  authenticatedWebsite,
+  connector,
+  embeddedAssistant,
+  noodleManaged,
+  publicWebsite,
+  server,
+  tool,
+  z,
+} from '@noodleseed/one';
+
+const draft = z.object({
+  title: z.string().trim().min(1).max(120).optional(),
+  audience: z.string().trim().min(1).max(240).optional(),
+  goal: z.string().trim().min(1).max(240).optional(),
+});
+
+const snapshot = z.object({
+  value: draft,
+  revision: z.number().int(),
+  status: z.string(),
+});
+
+const state = connector('noodle_state')
+  .version('1.0.0')
+  .operation('read_state', {
+    type: 'read',
+    input: z.object({ handle: z.string() }),
+    output: snapshot,
+  })
+  .operation('patch_state', {
+    type: 'action',
+    input: z.object({
+      handle: z.string(),
+      expectedRevision: z.number().int().min(0),
+      value: draft,
+    }),
+    output: snapshot,
+  });
+
+const openDraft = tool('open_draft', {
+  title: 'Review your brief',
+  description:
+    'Preview a proposed brief and read the saved brief with its revision. Pass the proposed title, audience, and goal in proposal to prefill the editable preview without saving it. Omit proposal to reload the saved record after a conflict.',
+  input: z.object({ proposal: draft.default({}) }),
+  output: snapshot.extend({ proposal: draft }),
+  fulfil: ({ input, connectors }) => {
+    const saved = connectors.state.readState({ handle: 'draft' });
+    return {
+      value: saved.value,
+      revision: saved.revision,
+      status: saved.status,
+      proposal: input.proposal,
+    };
+  },
+  viewTitle: 'Your project brief',
+  invoking: 'Loading your saved brief…',
+  invoked: 'Your brief is ready to review',
+  view: { component: 'draft-card', entry: './views/draft-card.tsx' },
+  annotations: annotations.readOnly(),
+  viewDescription: 'Review and edit a saved brief before deciding whether to create an account.',
+  csp: { connectDomains: [], resourceDomains: [], frameDomains: [] },
+});
+
+const saveDraft = tool('save_draft', {
+  title: 'Save your brief',
+  description:
+    'Save this reviewed brief for up to 24 hours. This does not create an account or a project.',
+  input: draft.required().extend({
+    expectedRevision: z.number().int().min(0).meta({ title: 'Saved version' }),
+  }),
+  output: snapshot,
+  annotations: annotations.localAction({ destructive: false, confirm: true }),
+  fulfil: ({ input, connectors }) => {
+    const saved = connectors.state.patchState({
+      handle: 'draft',
+      expectedRevision: input.expectedRevision,
+      value: { title: input.title, audience: input.audience, goal: input.goal },
+    });
+    return { value: saved.value, revision: saved.revision, status: saved.status };
+  },
+});
+
+const continueDraft = tool('continue_draft', {
+  title: 'Continue with an account',
+  description:
+    'Read the brief in the signed-in account. Call only when the visitor chooses to continue with an account, after showing useful value. Sign-in carries the saved draft forward; it does not submit, publish, or create a project.',
+  input: z.object({}),
+  output: snapshot.extend({ accountId: z.string() }),
+  annotations: annotations.readOnly(),
+  fulfil: ({ connectors, user }) => {
+    const saved = connectors.state.readState({ handle: 'draft' });
+    return {
+      value: saved.value,
+      revision: saved.revision,
+      status: saved.status,
+      accountId: user.id,
+    };
+  },
+});
+
+export default server(
+  'stateful_draft',
+  {
+    title: 'Your first useful brief',
+    version: '1.0.0',
+    instructions:
+      'Help someone turn their goal into a concise project brief: a title, audience, and desired outcome. Base the brief on information they supply. Propose a sensible editable title; never require a naming question. If the audience and outcome are already clear, immediately show the complete proposed brief. Otherwise ask one short question for missing information and skip anything already answered. Show the useful proposed brief in chat before offering to save it. Do not request an email, password, document, or external research. Read open_draft before save_draft. Saving requires review and confirmation; an unconfirmed save is not persisted. Never claim an account or project was created. After saving, offer continue_draft only as an optional next step; never require signup to see the brief. This is a synthetic onboarding example, not an integration with a specific SaaS product.',
+    branding: {
+      name: 'First Brief',
+      accent: '#2563EB',
+      surface: '#F8FAFC',
+      surfaceDark: '#111827',
+      radius: 'md',
+      density: 'comfortable',
+      typography: 'system',
+      colorScheme: 'auto',
+    },
+    use: { state },
+    state: {
+      handles: {
+        draft: {
+          kind: 'draft',
+          version: 'v2',
+          scope: 'caller',
+          ttlSeconds: 86400,
+          claimOnAuthentication: true,
+          schema: draft,
+        },
+      },
+    },
+    assistant: embeddedAssistant({
+      model: noodleManaged(),
+      privacyUrl: 'https://noodleseed.com/privacy',
+      behavior: { showConfirmationDetails: false },
+      access: [
+        publicWebsite({
+          origins: ['http://localhost:3001'],
+          capabilities: [openDraft, saveDraft, continueDraft],
+          signIn: true,
+        }),
+        authenticatedWebsite({
+          origins: ['http://localhost:3002'],
+          capabilities: [openDraft, saveDraft, continueDraft],
+        }),
+      ],
+      labels: {
+        welcomeHeading: 'What would you like to achieve?',
+        composerPlaceholder: 'Describe your goal…',
+        signInHeading: 'Take your brief with you',
+        signInBody: 'Continue with an account to use your saved brief inside the product.',
+        signInAction: 'Sign in',
+        signUpAction: 'Create account',
+      },
+    }),
+  },
+  [openDraft, saveDraft, continueDraft],
+);

package/skills/codex/examples/stateful-draft/src/views/draft-card.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useState } from 'react';
+import { useCallTool, useSendFollowUpMessage, useToolInfo } from '../helpers.js';
+import './widget-style.css';
+
+type Brief = { title?: string; audience?: string; goal?: string };
+type Snapshot = { value: Brief; revision: number; status: string; proposal?: Brief };
+
+function displayBrief(data: Snapshot | undefined): Brief {
+  const proposal = data?.proposal;
+  return proposal && (proposal.title || proposal.audience || proposal.goal)
+    ? proposal
+    : (data?.value ?? {});
+}
+
+function snapshot(result: unknown): Snapshot | undefined {
+  if (!result || typeof result !== 'object') return;
+  const envelope = result as { isError?: boolean; structuredContent?: Partial<Snapshot> };
+  const data = envelope.structuredContent;
+  if (
+    !envelope.isError &&
+    data &&
+    data.value &&
+    typeof data.value === 'object' &&
+    Number.isInteger(data.revision) &&
+    typeof data.status === 'string'
+  ) {
+    return data as Snapshot;
+  }
+}
+
+export default function DraftCard() {
+  const info = useToolInfo('open_draft');
+  const read = useCallTool('open_draft');
+  const save = useCallTool('save_draft');
+  const followUp = useSendFollowUpMessage();
+  const [saved, setSaved] = useState(() => snapshot(info));
+  const [brief, setBrief] = useState<Brief>(() => displayBrief(snapshot(info)));
+  const [busy, setBusy] = useState(false);
+  const [reloadRequired, setReloadRequired] = useState(false);
+  const [message, setMessage] = useState('Review your brief. An account is optional.');
+  useEffect(() => {
+    const next = snapshot({ structuredContent: info.structuredContent });
+    if (next) {
+      setSaved(next);
+      setBrief(displayBrief(next));
+    }
+  }, [info.structuredContent]);
+  const complete = Boolean(brief.title?.trim() && brief.audience?.trim() && brief.goal?.trim());
+  const unchanged = ['title', 'audience', 'goal'].every(
+    (key) => brief[key as keyof Brief] === saved?.value[key as keyof Brief],
+  );
+
+  async function run(operation: 'load' | 'save') {
+    setBusy(true);
+    try {
+      const result =
+        operation === 'load'
+          ? await read.callTool({})
+          : await save.callTool({ ...brief, expectedRevision: saved?.revision });
+      const next = snapshot(result);
+      if (!next) throw new Error('No authoritative result');
+      setSaved(next);
+      setBrief(displayBrief(next));
+      setReloadRequired(false);
+      setMessage(operation === 'save' ? 'Your brief is saved.' : 'Saved brief loaded.');
+    } catch {
+      setReloadRequired(true);
+      setMessage(
+        'No save was confirmed. Reload saved to check the latest brief before trying again.',
+      );
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <main className="brief-shell">
+      <header>
+        <p className="brief-eyebrow">YOUR FIRST USEFUL STEP</p>
+        <h1>Your project brief</h1>
+        <p>Make something useful before creating an account.</p>
+      </header>
+      <section className="brief-fields">
+        <label>
+          Project title
+          <input
+            required
+            maxLength={120}
+            value={brief.title ?? ''}
+            placeholder="A better first week"
+            onChange={(event) => setBrief({ ...brief, title: event.currentTarget.value })}
+          />
+        </label>
+        <label>
+          Who is this for?
+          <textarea
+            required
+            maxLength={240}
+            rows={2}
+            value={brief.audience ?? ''}
+            placeholder="New teammates joining our product team"
+            onChange={(event) => setBrief({ ...brief, audience: event.currentTarget.value })}
+          />
+        </label>
+        <label>
+          What would success look like?
+          <textarea
+            required
+            maxLength={240}
+            rows={3}
+            value={brief.goal ?? ''}
+            placeholder="Complete their first useful project in a week"
+            onChange={(event) => setBrief({ ...brief, goal: event.currentTarget.value })}
+          />
+        </label>
+        <p role="status" aria-live="polite">
+          {busy ? 'Waiting for the result…' : message}
+        </p>
+        <div className="brief-actions">
+          <button type="button" disabled={busy} onClick={() => void run('load')}>
+            Reload saved
+          </button>
+          <button
+            className="brief-primary"
+            type="button"
+            onClick={() => void run('save')}
+            disabled={busy || !saved || !complete || reloadRequired}
+          >
+            Save brief
+          </button>
+        </div>
+      </section>
+      <footer>
+        <p>
+          A saved brief lasts up to 24 hours and can follow you when you sign in. No project has
+          been created.
+        </p>
+        <button
+          type="button"
+          disabled={
+            busy || !complete || !unchanged || !saved || saved.revision === 0 || reloadRequired
+          }
+          onClick={() =>
+            void followUp({ prompt: 'I would like to continue with my saved brief in an account.' })
+          }
+        >
+          Continue with an account
+        </button>
+      </footer>
+    </main>
+  );
+}

package/skills/codex/examples/stateful-draft/src/views/widget-style.css

@@ -0,0 +1,93 @@
+@layer stateful-draft {
+  .brief-shell {
+    box-sizing: border-box;
+    max-width: 600px;
+    margin: 0 auto;
+    padding: 24px;
+    color: var(--ns-text-primary, #172033);
+    background: var(--ns-surface, #f8fafc);
+    font-family: var(--ns-font, system-ui, sans-serif);
+    line-height: 1.5;
+  }
+  .brief-shell * {
+    box-sizing: border-box;
+  }
+  .brief-shell h1 {
+    margin: 4px 0;
+    font-size: 26px;
+    letter-spacing: -0.03em;
+  }
+  .brief-shell p {
+    color: var(--ns-text-secondary, #526077);
+  }
+  .brief-eyebrow {
+    font-size: 11px;
+    font-weight: 700;
+    letter-spacing: 0.12em;
+  }
+  .brief-fields {
+    display: grid;
+    gap: 16px;
+    margin: 24px 0;
+  }
+  .brief-shell label {
+    display: grid;
+    gap: 6px;
+    font-size: 14px;
+    font-weight: 600;
+  }
+  .brief-shell input,
+  .brief-shell textarea {
+    width: 100%;
+    padding: 10px 12px;
+    border: 1px solid var(--ns-border, #cbd5e1);
+    border-radius: var(--ns-radius-md, 8px);
+    color: inherit;
+    background: var(--ns-surface-raised, #fff);
+    font: inherit;
+    font-weight: 400;
+    resize: vertical;
+  }
+  .brief-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+  .brief-shell button {
+    padding: 10px 16px;
+    border: 1px solid var(--ns-border, #cbd5e1);
+    border-radius: var(--ns-radius-md, 8px);
+    background: var(--ns-surface-raised, #fff);
+    color: inherit;
+    font: inherit;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .brief-shell .brief-primary {
+    background: var(--ns-accent, #2563eb);
+    color: var(--ns-accent-text, #fff);
+    border-color: transparent;
+  }
+  .brief-shell button:disabled {
+    opacity: 0.5;
+    cursor: default;
+  }
+  .brief-shell :focus-visible {
+    outline: 2px solid var(--ns-focus, #2563eb);
+    outline-offset: 3px;
+  }
+  .brief-shell footer {
+    border-top: 1px solid var(--ns-border, #cbd5e1);
+    padding-top: 12px;
+    font-size: 13px;
+  }
+  @media (max-width: 380px) {
+    .brief-shell {
+      padding: 16px;
+    }
+    .brief-actions button {
+      width: 100%;
+    }
+  }
+}

package/skills/codex/examples/stateful-draft/test/draft-card.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const callTool = vi.fn();
+const followUp = vi.fn();
+const initial = {
+  value: { title: 'Team launch', audience: 'New teammates', goal: 'Complete their first project' },
+  revision: 4,
+  status: 'active',
+};
+let entry: unknown = initial;
+vi.mock('../src/helpers.js', () => ({
+  useToolInfo: () => ({ structuredContent: entry }),
+  useCallTool: () => ({ callTool }),
+  useSendFollowUpMessage: () => followUp,
+}));
+
+import DraftCard from '../src/views/draft-card.js';
+
+let host: HTMLDivElement;
+let root: ReturnType<typeof createRoot>;
+beforeEach(async () => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true);
+  callTool.mockReset();
+  followUp.mockReset();
+  entry = initial;
+  host = document.createElement('div');
+  document.body.append(host);
+  root = createRoot(host);
+  await act(async () => root.render(<DraftCard />));
+});
+afterEach(() => {
+  act(() => root.unmount());
+  host.remove();
+});
+function button(label: string) {
+  const found = [...host.querySelectorAll('button')].find((entry) => entry.textContent === label);
+  if (!found) throw new Error(`Missing button: ${label}`);
+  return found;
+}
+
+it('saves using the server revision and displays only the returned result', async () => {
+  callTool.mockResolvedValue({ structuredContent: { ...initial, revision: 8 } });
+  await act(async () => button('Save brief').click());
+  expect(callTool).toHaveBeenCalledWith({ ...initial.value, expectedRevision: 4 });
+  expect(host.textContent).toContain('Your brief is saved.');
+  expect(button('Continue with an account').disabled).toBe(false);
+});
+
+it('shows a proposed brief without pretending it is already saved', async () => {
+  entry = { value: {}, revision: 0, status: 'active', proposal: initial.value };
+  await act(async () => root.render(<DraftCard />));
+  expect(host.querySelector('input')?.value).toBe('Team launch');
+  expect(button('Continue with an account').disabled).toBe(true);
+  callTool.mockResolvedValue({ structuredContent: { ...initial, revision: 1 } });
+  await act(async () => button('Save brief').click());
+  expect(callTool).toHaveBeenCalledWith({ ...initial.value, expectedRevision: 0 });
+});
+
+it('does not invent a save when confirmation is pending or the response is missing', async () => {
+  callTool.mockResolvedValue({});
+  await act(async () => button('Save brief').click());
+  expect(host.textContent).not.toContain('Your brief is saved.');
+  expect(host.textContent).toContain('No save was confirmed.');
+});
+
+it('retains edits on a stale write and requires a reload before another save', async () => {
+  callTool.mockResolvedValue({ isError: true });
+  await act(async () => button('Save brief').click());
+  expect(host.querySelector('input')?.value).toBe('Team launch');
+  expect(button('Save brief').disabled).toBe(true);
+  expect(host.textContent).toContain('Reload saved');
+  callTool.mockResolvedValue({ structuredContent: { ...initial, revision: 7 } });
+  await act(async () => button('Reload saved').click());
+  await act(async () => button('Save brief').click());
+  expect(callTool).toHaveBeenLastCalledWith({ ...initial.value, expectedRevision: 7 });
+});
+
+it('keeps continuing separate from saving and makes no project-creation claim', async () => {
+  await act(async () => button('Continue with an account').click());
+  expect(callTool).not.toHaveBeenCalled();
+  expect(followUp).toHaveBeenCalledWith({
+    prompt: 'I would like to continue with my saved brief in an account.',
+  });
+  expect(host.textContent).not.toContain('Project created');
+});

package/skills/codex/examples/stateful-draft/test/server.test.ts

@@ -0,0 +1,58 @@
+import { fileURLToPath } from 'node:url';
+import { validate } from '@noodleseed/one';
+import { describe, expect, it } from 'vitest';
+import app from '../src/server.js';
+
+describe('stateful draft onboarding reference', () => {
+  it('reads and saves authoritative state instead of a widget-only copy', async () => {
+    const manifest = await app.toManifest();
+    expect(manifest.tools.find((entry) => entry.name === 'open_draft')?.fulfilment.steps).toEqual([
+      expect.objectContaining({ use: 'state.read_state', args: { handle: 'draft' } }),
+    ]);
+    expect(manifest.tools.find((entry) => entry.name === 'save_draft')).toMatchObject({
+      annotations: { readOnlyHint: false, confirm: true },
+      fulfilment: {
+        steps: [
+          expect.objectContaining({
+            use: 'state.patch_state',
+            args: {
+              handle: 'draft',
+              expectedRevision: '${input.expectedRevision}',
+              value: {
+                title: '${input.title}',
+                audience: '${input.audience}',
+                goal: '${input.goal}',
+              },
+            },
+          }),
+        ],
+      },
+    });
+  });
+
+  it('limits anonymous access and transfers only an expiring draft after verified login', async () => {
+    const manifest = await app.toManifest();
+    expect(manifest.state?.handles.draft).toMatchObject({
+      scope: 'caller',
+      ttlSeconds: 86400,
+      claimOnAuthentication: true,
+    });
+    expect(manifest.server.assistant?.surfaces?.map((surface) => surface.mode)).toEqual([
+      'mixed',
+      'authenticated',
+    ]);
+    const continued = manifest.tools.find((entry) => entry.name === 'continue_draft');
+    expect(continued?.annotations?.readOnlyHint).toBe(true);
+    expect(continued?.fulfilment.output).toMatchObject({ accountId: '${user.id}' });
+    expect(continued?.fulfilment.steps).toEqual([
+      expect.objectContaining({ use: 'state.read_state', args: { handle: 'draft' } }),
+    ]);
+  });
+
+  it('compiles through the public validator, including anonymous action confirmation', async () => {
+    const result = await validate({
+      manifestPath: fileURLToPath(new URL('../src/server.ts', import.meta.url)),
+    });
+    expect(result.ok, JSON.stringify(result.ok ? [] : result.errors)).toBe(true);
+  });
+});

package/skills/codex/examples/stateful-draft/vitest.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  oxc: { jsx: { runtime: 'automatic' } },
+  test: { include: ['test/**/*.test.{ts,tsx}'], testTimeout: 30_000, maxWorkers: 2 },
+});

package/skills/codex/examples/weather/README.md

@@ -7,6 +7,10 @@ Capability slots: HTTP connector authoring, ordered fulfilment flows, query/resp
 **list-returning connector output** (a connector that returns a live, variable-length array), and
 sandboxed compute, including an explicit least-privilege per-operation response-size bound.
 
+For a different API with an OpenAPI document, start with `noodle import openapi <file>` in a separate
+directory. Its shared schemas and offline test establish the contract, not live behavior; follow the
+[connector guide](https://docs.noodleseed.dev/docs/guides/connectors) before replacing this curated flow.
+
 1. **`geo.search`** → geocode the city to coordinates (Open-Meteo Geocoding API)
 2. **`forecast.current`** → fetch current weather for those coordinates (Open-Meteo Forecast API)
 3. **`brief.summarize`** → derive a human-readable briefing in a **WASM/QuickJS compute sandbox**

package/skills/codex/executing-noodle-plans/SKILL.md

@@ -3,7 +3,7 @@ name: executing-noodle-plans
 description: "Use when the user asks to execute an approved, decision-complete implementation plan for a Noodle Seed project task by task with test-first changes, review, recovery, and final verification."
 ---
 
-<!-- noodle-skill version:0.94.0 hash:6a9f132ddb79352e -->
+<!-- noodle-skill version:0.96.0 hash:6a9f132ddb79352e -->
 
 # Execute a Noodle Seed implementation plan
 

package/skills/codex/publishing-mcp-integrations/SKILL.md

@@ -3,7 +3,7 @@ name: publishing-mcp-integrations
 description: "Use when preparing, reviewing, or submitting a Noodle Seed MCP integration to a host or app directory."
 ---
 
-<!-- noodle-skill version:0.94.0 hash:0ccafb222038f553 -->
+<!-- noodle-skill version:0.96.0 hash:0ccafb222038f553 -->
 
 # publishing-mcp-integrations
 

package/skills/codex/references/authoring-workflow.md

@@ -22,8 +22,9 @@
 ## Input paths
 
 1. **Website scrape** — if the user gives a URL, scrape it for surface hints (products, services, hours, contact, pricing). Stop there: the URL does not reveal CRM, booking systems, custom APIs, auth model, eligibility rules, quoting logic, or approval flows. Those live in the business systems and the owner’s head — ask.
-2. **OpenAPI import** — `noodle import openapi <file>` emits a starter `server.ts` from a spec. Use it when the user provides an OpenAPI document.
+2. **OpenAPI import** — `noodle import openapi <file>` writes a pinned project at `src/server.ts`, shared operation/tool schemas, managed auth references, and an offline contract test. It does not install dependencies or call the backend. Follow its README, run `agent:check`, and add a reviewed sandbox-operation test; compile success is not live integration proof. Review unsupported-body/auth warnings before deployment. Modified files are preserved unless `--force` is explicit.
 3. **Upstream MCP import** — `noodle import mcp <url> --name <slug> --output <dir>` discovers `tools/list` once, validates and freezes tool schemas into TypeScript, and writes a secret-free drift snapshot. Upstream annotations are untrusted, so generated tools remain destructive confirmed actions until an author verifies and narrows them. Use `--header-env <header>=<ENV_NAME>` for import-only auth and `--check` for classified, non-mutating drift detection. Runtime never performs discovery.
+Both imports use `src/server.ts` as the declared entrypoint, include an offline compile test and `.env.example`, and write files only. Install the pinned dependencies, run the generated checks, then `noodle agents setup --apply`. Never treat generated contract tests as customer authentication or business-workflow evidence.
 4. **User interview** — Noodle does not interview; you do. Cover custom APIs/integrations, eligibility rules, quoting/approval logic, and private schemas (SQL DDL or JSON samples for custom `connector` declarations). Ask for concrete examples and sample payloads; do not guess a schema from a URL or invent endpoints.
 
 ## Fit check
@@ -393,20 +394,14 @@ Compute `run` functions are serialized and sandboxed: no imports, no closure cap
 
 ## Tests
 
-Use Vitest for app-local tests. The generated `npm test` command scans only the project-owned `test/` directory; skill-local example tests are reference material, not part of the app suite. Keep fixtures project-local; do not import from `examples/`. A minimum test suite imports the default server, checks the intended definitions compile, then lets `noodle test --json` perform the loopback MCP smoke.
+Start from the generated `test/server.test.ts`, not a blank test file. `npm test` runs `vitest run --dir test` over the project-owned `test/` directory; skill-local example tests are reference material. The generated suite compiles the actual source/view, lists tools, asserts a representative result and rejects invalid input. It copies source into temporary fixture storage and uses synthetic configuration, never customer secrets or saved hosted targets. The HTTP profile proves one local backend read and zero extra calls for invalid input.
 
-```ts
-import { describe, expect, it } from 'vitest';
-import app from '../src/server.js';
-
-describe('server', () => {
-  it('declares the expected tool surface', () => {
-    expect(app.name).toBe('support_assistant');
-  });
-});
+```sh
+npm test
+npm run agent:check
 ```
 
-After focused tests pass, run `noodle validate --json`, `noodle test --json`, and then `noodle dev` for interactive local verification.
+Adapt the representative arguments and assertions when business contracts change; keep invalid-input and authorization cases. A name/export assertion or `noodle test --json` without `--tool` proves no useful call. After fixture tests pass, bind the real local configuration, run an authorized representative read, and use `noodle dev` for interactive checks. Never use a production mutation or fixture success as customer-readiness evidence.
 
 ## Secrets and variables
 

package/skills/codex/references/build-an-mcp-app.md

@@ -25,14 +25,14 @@ Before implementation, capture a short design spec: target user, conversational
 4. **Preserve fallback.** Every tool that launches a widget must still return useful text without the widget, so unsupported hosts and failed rendering remain usable.
 5. **Decide product-guide coverage.** Record the required product-guide decision and its reason, then use `references/product-agent-guides.md` as the canonical selection and authoring guidance.
 6. **Author and wire the App contract.** Follow `references/widgets-and-apps.md` for the canonical component guidance, view registration, hooks, state, CSP, tool visibility, and output shaping. Keep tool effects and confirmation semantics correct independently of the UI.
-7. **Validate the local artifact.** Run `noodle validate --json`, `noodle test --json`, and `noodle check --json`. Repair failures at the layer that produced them.
+7. **Validate the local artifact.** Run the generated/adapted `npm test`, `noodle validate --json` and `noodle check --json`. Prove a representative result and negative case, not just registration. Synthetic preference previews do not save; replace their backend seam and verify the authorized effect before showing success.
 8. **Inspect the experience.** Run `noodle devtools` and verify loading, empty, error, success, responsive layout, focus/keyboard behavior, and the text fallback.
 9. **Escalate evidence only on request.** Run a host test only when the user requested host verification. Run host-specific compliance only when preparing that host submission; select the exact host-testing or compliance entry from the router lookup catalog only after that evidence level is explicitly requested.
 
 ## Verification evidence
 
 - **Product:** the design spec states the user benefit, UI fit decision, and product-guide decision with its reason.
-- **Server:** `noodle validate --json` and `noodle test --json` succeeded.
+- **Server:** compilation, a representative call and negative input/authorization cases passed; report whether fixtures or a real authorized backend were used.
 - **App contract:** `noodle check --json` succeeded.
 - **Local UX:** `noodle devtools` exercised the relevant states and the useful text fallback without the widget.
 - **Host/compliance:** report each requested host or compliance check with its evidence; report every unperformed higher level as not run.