@mindstudio-ai/remy 0.1.278 → 0.1.280

package/dist/prompt/compiled/interfaces.md

@@ -44,6 +44,7 @@ All fields are nested under the `"web"` key.
 | `devCommand` | `string` | `"npm run dev"` | Command to start the dev server |
 | `defaultPreviewMode` | `"desktop"` \| `"mobile"` | `"desktop"` | Default preview viewport in the editor. Set to `"mobile"` for mobile-first apps. |
 | `prerender` | `object` | — | Opt into prerendering the listed routes/patterns for crawlers/unfurlers. See "Prerendering" below. |
+| `mounts` | `array` | — | Serve other same-workspace apps under path prefixes of this app's hosts. See "Mounting other apps" below. |
 
 ### Frontend SDK
 
@@ -92,6 +93,24 @@ The project uses `"jsx": "react-jsx"` (automatic JSX transform) — do not `impo
 
 On deploy, the platform runs `npm install && npm run build` in the web directory and hosts the output on CDN.
 
+Two serving conventions every web interface must follow:
+
+1. **Assets via `MS_ASSET_BASE_URL`.** The platform build sets this env var to a release-addressed CDN origin. Point the bundler's public path at it so asset URLs work on any host or mount path:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  base: process.env.MS_ASSET_BASE_URL || '/',
+  // ...
+});
+```
+
+2. **Router basename from `platform.basePath`.** The platform injects the path prefix the page is served under ('' on the app's own hosts, the mount path when another app mounts this one). The SDK prefixes its own calls automatically; app code must feed it to the router and avoid hardcoded root-absolute URLs (`<img src="/logo.png">`, raw `location.assign('/about')`):
+
+```ts
+createBrowserRouter(routes, { basename: platform.basePath || '/' });
+```
+
 #### Error Handling and Analytics
 
 The SDK automatically reports uncaught errors, unhandled promise rejections, and pageviews to a per-app dashboard the owner gets for free. No setup required. The analytics dashboard covers visits, unique visitors, top pages, referrers, UTM breakdowns, country-level geo, device/browser/OS, new vs returning, and live online count.
@@ -136,6 +155,21 @@ await prerender.invalidate(['/u/abc']); // omit arg to purge all
 
 `mindstudio-prod prerender` can help you verify/manage snapshots during development.
 
+### Mounting other apps
+
+A web interface can serve other apps from the same workspace under path prefixes of its own hosts (the multi-zone pattern — e.g. a marketing site serving a self-contained demo app at `/demos/vector-search` instead of linking to its subdomain):
+
+```json
+{ "web": { "mounts": [{ "path": "/demos/vector-search", "app": "vector-search-demo" }] } }
+```
+
+- `path`: non-root mount prefix; mounts must be disjoint (none may prefix another).
+- `app`: the target's `custom_subdomain` or appId — a v2 app in the same workspace, validated at build.
+
+Under the mount everything is the child's, served first-class (its live bundle, session, backend, auth, telemetry, frame policy). The child needs no mount-specific config and keeps working at its own subdomain; deploys stay independent. Mount-safety = the two serving conventions above (`MS_ASSET_BASE_URL` assets + `platform.basePath` basename, no hardcoded root-absolute URLs); the parent's build log warns when a target's build isn't mount-safe.
+
+Caveats: prerendering for mounted paths is declared in the PARENT's `prerender.paths`; the auth cookie is per-host, so don't mount an auth-enabled app on a parent that also uses auth; a mount whose target has no live web build falls through to the parent's SPA.
+
 ## API Interface
 
 REST endpoints for external consumers — other services, mobile apps, integrations. This is separate from the web frontend's internal RPC (`@mindstudio-ai/interface` calls `/_/methods` directly and does not use the API interface). The API interface lives at `/_/api/` and exposes only the methods you choose to route.

package/dist/prompt/compiled/jewels.md

@@ -0,0 +1,3 @@
+# Jewels
+
+A "jewel" is an optional AI companion for a single app method (`foo.jewel.ts` beside `foo.ts`): it proposes the method call a human would otherwise make, the method's manifest `autonomy` setting decides what happens to each proposal: recorded silently (`shadow`), queued for human review (`approve`), or committed (`auto`), and every proposal is then graded against what really happened. Jewels are never part of an initial build, and most apps will never need them. By default, build AI features as plain method code - if the user wants to add jewels later on, conversion is easy and additive. Before doing any work with or thinking around jewels, load the `jewels` skill.

package/dist/prompt/compiled/methods.md

@@ -229,6 +229,10 @@ export async function enrichRestaurant(input: { id: string; name: string }) {
 
 This works because the execution environment persists between requests. The un-awaited promise continues after the method returns. DB, auth, and SDK all work normally in the background chain. For critical workflows, write a "pending" record before firing so incomplete tasks can be detected and retried.
 
+## Jewels
+
+A method can optionally have a jewel (`foo.jewel.ts`) — an AI companion that proposes the method's input, routed by the manifest's `autonomy` setting. See the jewels section of this prompt for when they apply; load the `jewels` skill before writing one.
+
 ## Shared Helpers
 
 Code shared between methods goes in `dist/methods/src/common/`. Helpers are not listed in the manifest — they're internal, imported by methods but not directly invocable.

package/dist/prompt/skills/jewels.md

@@ -0,0 +1,296 @@
+---
+name: Jewels
+what: An optional AI companion for a single app method, `foo.jewel.ts` beside `foo.ts`. It proposes the method call a human would otherwise make; the method's manifest `autonomy` decides what happens to each proposal (recorded silently, queued for review, or committed), and every proposal is graded against what really happened. Arbitrary TypeScript (typically deterministic guardrails plus task agents for judgment).
+when: Before writing any `.jewel.ts` file, setting a method's `autonomy` in the manifest, writing a custom `grade`, calling `mindstudio.jewels.*`, or discussing automating one of the app's judgment calls with the user.
+---
+
+# Jewels (`defineJewel`)
+
+## What & When
+
+A jewel attaches to exactly one method and proposes the input a human user would otherwise submit. It is for **decisions**: method invocations someone would otherwise have to make. If the AI's output is content the app displays (a summary, an extraction, a chart caption), that's plain model code inside a method (`runTask` in the body), not a jewel. A jewel exists when there's an accountable disposition to record, review, or grade.
+
+Five decision shapes cover the space. Any recurring human decision in any app is one of these:
+
+- **Choose one of N**: route a ticket, assign a lead, categorize an expense. Closed enum output.
+- **Set a value under policy**: price a job, size a discount, set a reorder quantity. Scalar judgment.
+- **Gate**: approve a refund, advance a candidate, accept a listing. Binary plus reasoning.
+- **Match / reference-pick**: flag a duplicate, pair a reviewer to a submission. Candidate-id enum; abstention dominates, which is correct.
+- **Draft outbound**: a reply, a quote, an offer. Generative, checklist-graded, and the natural home of approve mode.
+
+Not a fit:
+
+- **Reads** (`get-*`, `list-*`): no decision to learn.
+- **Machine-triggered ingest verbs** (webhook/cron/sync handlers): no human demonstration. Ingest *code* may still hand a decision moment to a judgment verb via `mindstudio.jewels.propose` (see Arrival Triggers).
+- **Deterministic mutations**: if the correct input is computable, compute it in the method. A jewel learns judgment, not arithmetic.
+- **AI-as-a-feature**: a method that needs a model as part of its own work just calls `runTask` in its body.
+- **Verbs that should stay human as policy**: declare `"autonomy": "manual"` in the manifest so the choice is recorded.
+
+One jewel per judgment. If a jewel would need to take two actions, the methods are shaped wrong; fix the verbs.
+
+Never include a jewel in an initial build, and don't bring them up while an app is young. Most users will never want one; a few will care a lot. The default posture:
+
+- **Build AI features plainly.** A drafting feature is a method that calls a model and returns text, with no jewel machinery anywhere. Converting it to a jewel later is additive (a `.jewel.ts` beside the method, an `autonomy` line in the manifest); nothing about the plain version is thrown away.
+- **Jewels enter when the user asks** about automating a judgment the app already handles, or picks an automation item off the roadmap. Once an app is solid and a judgment verb sees real use, a benefit-phrased automation item may belong on the roadmap; that is the only proactive channel.
+- **When the user engages, have the conversation first**: what it does in their terms, what the levels mean, what evidence looks like. Then start with exactly one verb.
+
+The examples in this reference are deliberately generic (`categorizeRecord`, `recordId`). Map the shapes onto this app's own judgments; the constructs are identical in every domain.
+
+## Method Shape Comes First
+
+A jewel is only as learnable as the verb it shadows. These four habits are also why converting a plain feature later is cheap:
+
+- **One judgment, one method.** The decision lives in one verb, never split across near-identical mutations. Keep the judgment verb free of housekeeping (read toggles and self-assignment live in a separate edit method) so the default grade tells the whole story.
+- **Subject and decision separable in the input.** The id of the thing being judged is the subject; the fields being set are the decision. A jewel only ever receives the subject.
+- **Event lines for decisions.** Status changes and reassignments append to an activity record; history that reads as decisions is the precedent a jewel cites.
+- **Judgment moments are states; verbs are transitions.** When several jeweled verbs are alternatives on the same subject (a new record gets categorized, merged, or archived, never two of those), don't add an orchestrator to encode the exclusivity. Make it structural: the alternatives compete for one explicit status field, each method's precondition consumes it (`status === 'new'`), and each jewel's matching guardrail (`if (status !== 'new') abstain`) is the same precondition expressed as abstention. The first committed transition wins, every other verb fails closed on its own check, and each jewel answers one clean question ("would my verb apply here?") with abstention doing the routing. If two verbs can't be separated by abstention discipline, that's the diagnostic for a missing union verb: introduce the method whose input carries the real decision (`{ action: 'categorize' | 'merge' | 'archive', ... }`) and jewel that instead.
+
+## The API
+
+**The jewel proposes; the method applies.** A jewel's output type is the shadowed method's input type. It never writes anything itself. Auth checks, validation, and invariants stay in the method, so the jewel walks through the same door as every human and every interface and cannot do anything the app didn't already allow.
+
+Three functions, one call. Declare `subject` before `propose`: the subject type is inferred from the projection's return and flows into `propose`'s parameter.
+
+- **`subject`**: a typed projection from the method's input to what identifies the work (`{ recordId }`). Never include the human's decision fields; the jewel exists to produce the decision, so handing it the answer would poison every pair.
+- **`propose`**: arbitrary TypeScript that returns `{ input: MethodInput | null, reasoning: string }`. `input: null` is abstention, a correct and graded outcome. `reasoning` is written to the ledger and is most valuable on abstention.
+- **`grade`** (optional): scores `{ proposed, actual }` and returns `{ verdict: 'agree' | 'disagree' | 'skip', notes? }`. Omit it for deep-equal on the method input. `skip` means "this pair isn't a graded moment."
+
+The jewel runs as its own platform-managed user with a normal session, so `auth.userId` is set, `requireUser()`-style helpers pass unchanged, and role checks in methods apply to it exactly as they do to humans.
+
+`defineJewel` returns a callable executor with the config attached (`kind`, `method`, `subject`, `propose`, `grade`). The platform invokes it like any method export, with exactly one of two param shapes: `{ humanInput }` (a shadow run: the subject is derived via the projection, and `humanInput` doubles as ground truth) or `{ subject }` (an eval run: no human action, so the record is ungraded). It resolves to a versioned pair record:
+
+```typescript
+interface JewelPairRecord {
+  v: 1;
+  mode: 'shadow' | 'eval';
+  subject?: unknown;
+  proposed?: MethodInput | null; // null = abstention
+  reasoning?: string;
+  actual?: MethodInput;          // the human's input (shadow mode)
+  verdict?: 'agree' | 'disagree' | 'skip';
+  notes?: string;
+  error?: { phase: 'subject' | 'propose'; message: string; stack?: string };
+  startedAt: number;
+  durationMs: number;
+}
+```
+
+The executor never throws: a shadow run must never break anything. Your code failing inside `subject` or `propose` becomes the record's `error`; `grade` failing softens to verdict `skip`.
+
+Shadowing runs only on the deployed app. Dev traffic never fires jewels; dev invocations are synthetic and would pollute the pair ledger.
+
+## Usage
+
+The skeleton: deterministic guardrails before any model call, context via the app's own methods, a runtime-built enum, and fail-closed abstention.
+
+```typescript
+// dist/methods/src/categorizeRecord.jewel.ts
+import { defineJewel, mindstudio } from '@mindstudio-ai/agent';
+import { categorizeRecord } from './categorizeRecord';
+import { getRecord, listCategories } from './common/records';
+
+export default defineJewel(categorizeRecord, {
+  // Projection: what the human was looking at, never what they decided.
+  subject: ({ recordId }) => ({ recordId }),
+
+  propose: async ({ recordId }) => {
+    // Deterministic outs first, as plain-code abstention; no model call needed.
+    const record = await getRecord(recordId);
+    if (!record || record.category) return { input: null, reasoning: 'Nothing to categorize.' };
+
+    const categories = (await listCategories()).map((c) => c.name);
+    try {
+      const task = await mindstudio.runTask({
+        prompt: CATEGORIZATION_POLICY, // operator-voice policy prose (see "Writing propose")
+        input: { record, categories },
+        tools: [{ appMethod: 'list-records', description: 'Find precedent: how comparable records were categorized.' }],
+        outputSchema: {
+          type: 'object',
+          properties: {
+            category: { enum: [...categories, null] }, // runtime enum: it cannot invent a category; null = abstain
+            rationale: { type: 'string' },
+          },
+          required: ['category', 'rationale'],
+        },
+        model: 'claude-5-sonnet', // ask askMindStudioSdk; don't copy this one blind
+        maxTurns: 6,
+      });
+      if (!task.output.category) return { input: null, reasoning: task.output.rationale };
+      return { input: { recordId, category: task.output.category }, reasoning: task.output.rationale };
+    } catch (err) {
+      // Couldn't produce conforming output; abstain with the evidence. Fail closed.
+      return { input: null, reasoning: `Task agent failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+  },
+  // No grade: the whole input is the decision, so default deep-equal is right.
+});
+```
+
+This is choose-one-of-N. The other shapes reuse the skeleton wholesale. What changes is the output schema (a number under policy, a boolean gate, a candidate-id enum, a drafted body) and the grading mode.
+
+## Writing `propose`
+
+To preserve signal integrity, the task prompt inside `propose` addresses the model as the responsible operator. It never mentions shadowing, jewels, mirrors, grading, or a human whose action it should match. Consulting precedent is fine; "look up how comparable records were categorized and follow the team's conventions" is what a real operator does.
+
+- **Keep propose effect-free.** In shadow runs the platform absorbs database reads/writes into a disposable mirror, and that is the ONLY thing it absorbs. Everything else a jewel's code does is real in every mode: an email sends, an HTTP POST posts, a file write persists. If a proposal's job seems to require causing an effect to decide, that's a design error. Gather evidence, propose the input, let the method act.
+- **Guardrails before judgment.** Handle the deterministic outs in plain code before any model call. Every guardrail is a documented abstention in the ledger.
+- **Context is plain imports plus tools.** Prefetch what every run needs (the row, its history, the inventory of valid values) into the task input; expose the app's own read methods as tools for what the agent should decide to look up (precedent, comparables). Tool calls are recorded with the pair.
+- **Use `runTask` with `outputSchema` for the judgment.** Build enums at runtime: a candidate-id enum means the agent structurally cannot reference a row that doesn't exist, and a known-values enum means it cannot invent a category. Put `null` in the enum so abstention is a first-class output rather than a formatting accident.
+- **Catch everything; abstain on failure.** A jewel that can't decide returns `{ input: null, reasoning }` with the evidence. It never throws to say "I don't know."
+- **Propose a subset when that's the honest scope.** A jewel that never sets `assigneeId` and never proposes `closed` (it can't know a fix shipped) is expressing policy through its output shape.
+- **Reasoning is audit-log prose.** Two or three plain sentences a teammate would find useful; name the evidence. No headers, bullets, or emojis.
+
+## Grading
+
+Three modes, matched to the verb's shape:
+
+- **Default (omit `grade`)**: deep-equal on the method input. Right when the whole input is the decision, the hallmark of a well-shaped transition verb.
+- **Field-scoped**: compare only the fields the human decided; return `skip` for housekeeping touches. For methods that must stay wide (judgment mixed with maintenance). A wide method that needs grade gymnastics is often a verb boundary that should be fixed instead:
+
+```typescript
+grade: ({ proposed, actual }) => {
+  const decided = (['status', 'priority', 'owner'] as const).filter((k) => actual[k] !== undefined);
+  if (decided.length === 0) return { verdict: 'skip', notes: 'Housekeeping touch, not a decision.' };
+  if (!proposed) return { verdict: 'disagree', notes: 'Abstained where the human decided.' };
+  const misses = decided.filter((k) => proposed[k] !== actual[k]);
+  return misses.length === 0
+    ? { verdict: 'agree' }
+    : { verdict: 'disagree', notes: misses.map((k) => `${k}: proposed ${proposed[k]}, human ${actual[k]}`).join('; ') };
+},
+```
+
+- **Checklist judge**: for generative verbs (drafts, notes), equality is meaningless; grade with a rubric of booleans, never a preference score. `grade` is arbitrary TS and may be async, so it can call a model:
+
+```typescript
+grade: async ({ proposed, actual }) => {
+  if (!proposed) return { verdict: 'disagree', notes: 'Abstained where the human wrote one.' };
+  try {
+    const rubric = await mindstudio.runTask({
+      prompt: 'Judge whether two drafts responding to the same item take the same action. Grade strictly on substance, not style.',
+      input: { draftA: proposed.body, draftB: actual.body },
+      tools: [],
+      outputSchema: {
+        type: 'object',
+        properties: {
+          sameResolution: { type: 'boolean', description: 'Both take the same substantive action (same resolution, same escalation, same answer), or neither does.' },
+          noContradiction: { type: 'boolean', description: 'DRAFT A asserts nothing DRAFT B contradicts.' },
+        },
+        required: ['sameResolution', 'noContradiction'],
+      },
+      model: 'claude-5-sonnet',
+      maxTurns: 2,
+    });
+    const c = rubric.output;
+    return c.sameResolution && c.noContradiction
+      ? { verdict: 'agree' }
+      : { verdict: 'disagree', notes: `Failed: ${[!c.sameResolution && 'sameResolution', !c.noContradiction && 'noContradiction'].filter(Boolean).join(', ')}` };
+  } catch (err) {
+    return { verdict: 'skip', notes: `Judge failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+},
+```
+
+`actual` is always present in `grade`; grading only happens when a human acted. `proposed` is `null` when the jewel abstained, and whether that's a disagreement is the grade's call (abstaining where the human also did nothing is agreement).
+
+## Autonomy
+
+Four levels: `manual` (no jewel ever; a policy statement), `shadow` (runs silently on every human invocation, pairs recorded, nothing visible), `approve` (jewel drafts, a human accepts, edits, or rejects; the edit is the richest training signal there is), `auto` (the jewel acts under its own identity).
+
+**Auto is the only level you earn with evidence. Shadow and approve are both safe starting points; pick by what the product is.** When the proposals themselves are the product (drafts for review), start at approve; it's often the permanent home. When the evidence is the product (an auto-bound verb), start at shadow. Raising to auto is a reviewed manifest diff justified by agreement numbers.
+
+**Choose approve by the verb's risk shape, not by default.** Reversible state-machine verbs (routing, classification; a mistake is a two-click correction) go shadow → auto with a `sampleRate` canary and skip approve, because a review queue on a high-agreement classifier adds work without adding safety. Approve belongs on irreversible or outward-facing verbs (send, publish, charge, refund): `sampleRate` is population-level risk control, and those verbs need per-instance gating, which is what approve is.
+
+`sampleRate` (optional, default 1) is the level's canary/cost dial: the fraction of eligible decision moments that receive the full autonomy treatment. At `shadow` it's a cost control: `0.25` shadows a quarter of invocations, and expected dashboard coverage drops to match. At higher levels the remainder shadow-records instead, so a ramp keeps measuring its control. Omit it unless the verb is hot enough that shadowing every invocation is a real cost.
+
+The wiring itself is two manifest lines on the method's entry:
+
+```jsonc
+{
+  "id": "categorize-record",
+  "name": "Categorize Record",
+  "path": "dist/methods/src/categorizeRecord.ts",
+  "export": "categorizeRecord",
+  "autonomy": "shadow",
+  "jewel": { "path": "dist/methods/src/categorizeRecord.jewel.ts", "export": "default" }
+}
+```
+
+## Arrival Triggers (`mindstudio.jewels.propose`)
+
+Invocation shadowing fires when a human acts. For decision moments the app detects itself (an ingest branch that lands a row in its pending state), hand the moment to the jewels from backend code:
+
+```typescript
+// In the ingest path, after a record lands in (or regresses back to) status 'new':
+mindstudio.waitUntil(proposeIntake(record.id));
+
+async function proposeIntake(recordId: string): Promise<void> {
+  // Priority is app code: dedupe dominates; a duplicate must never be categorized.
+  const dup = await mindstudio.jewels.propose(
+    'flag-duplicate', { sourceId: recordId }, { idempotencyKey: recordId });
+  if (dup.outcome !== 'committed') {
+    await mindstudio.jewels.propose(
+      'categorize-record', { recordId }, { idempotencyKey: recordId });
+  }
+}
+```
+
+The platform routes each proposal by the method's autonomy: `recorded` (shadow: the proposal waits in a ledger and is graded later against whatever the human eventually does, within the method's `attributionWindow`; if a human then invokes the method, their action grades the waiting proposal instead of firing a second run), `queued` (approve), `committed` (auto: the method ran; check it to short-circuit lower-priority verbs), `abstained`, `disabled` (no jewel or manual; returned, never thrown), `skipped`, `failed`, `pending`.
+
+Rules that matter:
+
+- **Always wrap the chain in `mindstudio.waitUntil(...)`**: each propose blocks for the jewel's run, and ingest must return immediately.
+- **Share one `idempotencyKey` across the moment's verbs** (usually the row's id). It has Stripe semantics (a replayed key returns the original outcome, so webhook retries are invisible), and the shared key is what lets a human action on one verb grade the sibling proposals cross-verb.
+- **The subject you pass must equal what the jewel's projection produces** from the method input (field-pick projections guarantee this); it's the join key between the arrival proposal and the human's later action.
+- **Order alternatives by priority and short-circuit on `committed`.** Exclusivity is enforced by the methods' state preconditions, not by this chain; ordering only saves wasted runs.
+- Propose only at real decision-moment births. Over-proposing costs a cheap guardrail abstention, but a moment that isn't row-backed (no pending state to consume) usually means the schema is missing a state.
+
+## Native Approval Flows (`jewels.queue`)
+
+For `approve`-mode methods, the review inbox belongs in the app, next to the work. Three pieces:
+
+```typescript
+// 1. Backend list method, gated with the APP'S reviewer role.
+export async function listPendingDrafts() {
+  auth.requireRole('reviewer');
+  return mindstudio.jewels.queue.list({ methodId: 'send-message' });
+}
+
+// 2. Frontend inbox UI renders items: subject, proposed input, reasoning.
+
+// 3. Backend resolve method: approve applies, dismiss records.
+export async function reviewDraft(input: {
+  itemId: string;
+  action: 'approve' | 'dismiss';
+  edited?: Record<string, unknown>;
+}) {
+  auth.requireRole('reviewer');
+  return mindstudio.jewels.queue.resolve(input.itemId, {
+    action: input.action,
+    ...(input.edited ? { input: input.edited } : {}),
+  });
+}
+```
+
+What makes this safe with no extra machinery:
+
+- **Approving applies the target method as the signed-in reviewer**: the effect belongs to the human who clicked, and the target method's own auth checks are the real gate on who may approve. Gate the wrapping list/resolve methods with the app's reviewer role as well.
+- **Let reviewers edit before approving**: pass the edited input. The platform captures proposed/edited/final with the pair; an accept/reject-only review UI leaves the most valuable training signal on the table.
+- **Dismissal is not consumption**: the decision moment stays open for other verbs (a dismissed draft doesn't block a later merge). Unresolved items expire at the method's `attributionWindow`, so there's no infinite backlog.
+- `propose` returns `queueItemId` on `queued`, so the app can badge its UI or notify its own way the moment a draft lands.
+
+Before the app has its own review UI (or when the user asks you to act), the same queue is reachable from `mindstudio-prod jewels queue` / `jewels resolve`; approving there applies the method as the user through the identical machinery.
+
+## Verifying a Jewel: the `testJewel` Tool
+
+`testJewel` runs a jewel directly against an input you choose and returns the pair record inline. The method itself is never executed (no data changes) and nothing reaches the pair ledger; it's the authoring loop. The verification cycle:
+
+1. Seed a realistic world first (`runScenario`): the jewel's `propose` reads real state, so it needs something to look at.
+2. Call `testJewel` with `humanInput` set to the exact input a human would have submitted: `{ method: "categorizeRecord", humanInput: { recordId: "...", category: "..." } }`. The jewel derives its subject from it, proposes, and grades against it, and the record comes back with a verdict.
+3. Read the record: does `subject` contain what you projected (and nothing that leaks the answer)? Is `reasoning` grounded? Does the verdict match your expectation? A `pair.error` with phase `subject` or `propose` is your code throwing; fix and re-run.
+4. Repeat across a handful of inputs covering the method's decision space: a clear-cut case, an ambiguous one where abstention (`proposed: null`) is correct, and a housekeeping touch your `grade` should `skip`.
+
+For cases with no known right answer, pass `subject` instead of `humanInput` for an ungraded eval run (propose only). Useful for probing behavior on edge-case subjects before you have ground truth.
+
+Each run also lands in `.logs/requests.ndjson` as a `type: 'jewel'` record if you need the trail.
+
+Once deployed, the prod-side view lives in `mindstudio-prod jewels` (run `--help` for commands): agreement stats, pair records, the approval queue, and `jewels dryrun`, the prod twin of `testJewel`. It runs the LIVE jewel against a real subject inside a disposable database mirror and records nothing.

package/dist/prompt/skills/taskAgents.md

@@ -10,7 +10,7 @@ A user types the name of a restaurant into your app, or uploads a photo of a sto
 
 `runTask()` makes this possible. It runs a multi-step, tool-use agent loop: give it a prompt, a set of tools, and a JSON Schema for the structured output you want (`outputSchema`). The platform runs the loop (calling the model, executing tool calls, feeding results back) until the model produces JSON conforming to your schema — validated every turn, with automatic repair when it doesn't. `result.output` is typed by inference from the schema: no generic argument, no manual validation. The model decides what to do next based on intermediate results — retrying searches with different terms, working around failed tools, batching independent calls in parallel.
 
-Tools are **SDK actions** (`searchGoogle`, `generateImage`, …) and **your own app's methods** (`{ appMethod: 'saveVendor' }`), in any combination. That second half is what makes a task agent part of your app rather than a detached research bot: it can read your tables to decide what to do next, and write results back itself instead of handing them to you to persist.
+Tools are **SDK actions** (`searchGoogle`, `generateImage`, …) and **your own app's methods** (`{ appMethod: 'save-vendor' }`), in any combination. That second half is what makes a task agent part of your app rather than a detached research bot: it can read your tables to decide what to do next, and write results back itself instead of handing them to you to persist.
 
 This is one of the most powerful pieces of the MindStudio SDK, and it can turn an app from amazing into truly magical. Use `askMindStudioSdk` to help construct the right agent for a task — including which model to give it.
 

package/dist/prompt/static/coding.md

@@ -9,6 +9,7 @@
 ### Verification
 Run `lspDiagnostics` after every turn where you have edited code in any meaningful way. You don't need to run it for things like changing copy or CSS colors, but you should run it after any structural changes to code. It catches syntax errors, broken imports, and type mismatches instantly. After a big build or significant changes, also do a lightweight runtime check to catch the things static analysis misses (schema mismatches, missing imports, bad queries). Your runtime check can include:
 - Spot-checking methods with `runMethod`. The dev database is a disposable snapshot that will have been seeded with scenario data, so don't worry about being destructive.
+- Spot-checking jewels with `testJewel` after writing or modifying one (runs the jewel directly and returns its pair record; the method itself is not executed).
 - For frontend work, checking the browser log for any console errors in the user's preview, and — when a change's visual outcome is genuinely uncertain — taking a `screenshot` to confirm the main view renders correctly.
 - Using `runAutomatedBrowserTest` to verify an interactive flow that you can't confirm from a screenshot, when the user reports something broken that you can't identify from code alone, or whenever the verification involves driving the app through multiple interactions.
 

package/dist/prompt/static/team.md

@@ -12,7 +12,7 @@ Your designer. Consult for any visual decision — choosing a color, picking fon
 
 The design expert cannot see your conversation with the user, so include relevant context and requirements in your task. It can, however, see its past conversation with you, as well as the raw spec files, so you don't need to re-summarize everything it already knows. Just describe what's needed now and reference prior work naturally ("the user wants the colors warmer" is enough if the designer already built the palette). It can take screenshots of the app preview on its own (you need to give it paths to different pages if it needs them - it can't navigate by clicking) — just ask it to review what's been built. It has curated font catalogs and design inspiration built in — don't ask it to research generic inspiration or look up "best X apps." Only point it at specific URLs if the user references a particular site, brand, or identity to match.
 
-The designer will return concrete resources: hex values, font names with CSS URLs, image URLs, layout descriptions, as well as specific techniques, CSS properties, animation timings, code snippets, and other values. Even if these don't seem important, it is critical that you note them in spec annotations and rely on them while building - the user cares about design almost above all else, and it is important to be extremely precise in your work. The designer can also return code-fenced typography, color schemes, and wireframes (self-contained HTML and CSS). Write these directly into specs for future reference.
+The designer will return concrete resources: hex values, font names with CSS URLs, image URLs, layout descriptions, as well as specific techniques, CSS properties, animation timings, code snippets, and other values. Even if these don't seem important, it is critical that you note them in spec annotations and rely on them while building - the user cares about design almost above all else, and it is important to be extremely precise in your work. The designer can also return code-fenced typography and color schemes (self-contained HTML and CSS) - write these directly into specs for future reference. Wireframes arrive as file references like `![Feed Post Card](src/.wireframes/feed-post-card-x7f2.html)`: copy the reference line into specs verbatim (it renders as a visual preview in chat and in the spec), and read the file at that path while building to get the exact markup and CSS the designer specified.
 
 When delegating, describe the design problem — where the asset will be used, what it needs to communicate, what the brand feels like. Do not specify technical details like image formats, pixel dimensions, generation techniques, or workarounds. The design expert makes those decisions.
 
@@ -26,7 +26,7 @@ Your product thinking partner. Owns the roadmap in `src/roadmap/` — the lanes,
 
 Your architect for anything that touches external services, AI models, media processing, communication, or third-party APIs. Consult before you reach for an npm package, write boilerplate API code, or try to install system tools. The MindStudio SDK has 200+ managed actions for calling AI models, processing media, sending email/SMS, connecting to third-party APIs, web scraping, and much more. The SDK is already installed and authenticated in the execution environment — no API keys, no configuration, no setup. It handles all the operational complexity so you don't have to. Your instinct will be "I can just write this myself" — but the managed action is almost always the better architectural choice.
 
-Also critical: model IDs in the MindStudio API do not match vendor API model IDs. Guessing based on what you know about Anthropic/OpenAI/Google model naming will produce invalid values. Always look up the correct ID.
+Also critical: model IDs in the MindStudio API do not match vendor API model IDs. Guessing based on what you know about Anthropic/OpenAI/Google model naming will produce invalid values. Always look up the correct ID. A model id may carry an `@vendor` suffix (e.g. `claude-opus-5@amazonBedrock`) pinning it to one serving route — preserve these exactly as written in app specs; never rewrite them to the bare id.
 
 Describe what you're building at the method level — the full workflow — and get back architectural guidance and working code. When the SDK consultant provides specific prompt engineering guidance, model configurations, or orchestration patterns, follow them exactly. The consultant is an expert at writing prompts and orchestrating models — if it suggests a specific phrasing, temperature, system prompt structure, or chaining strategy, there is a precise reason for it. Do not paraphrase, simplify, or "improve" its recommendations.
 

package/dist/subagents/codeSanityCheck/prompt.md

@@ -66,7 +66,7 @@ When a plan includes multiple screens/API calls, always note this item for the d
 
 - **Manual multi-step chains that should be `runTask()`.** If a method chains AI-driven work with branching logic (search, then scrape based on results, then generate based on what was scraped), that's a `runTask()` use case. `runTask()` runs an agent loop that autonomously calls tools and returns structured JSON. The developer writes a prompt and a JSON Schema for the output (`outputSchema`) instead of imperative code. Flag when you see methods with complex sequential/branching chains — especially research, enrichment, or content generation pipelines. Similarly, flag opportunities where the developer might not have realized they could get better and richer data via runTask - it's a really powerful lever for working with data (e.g., user provides some fragment and agent task goes off and enriches it) that the developer might not have remembered when planning their work.
 
-  Tools are SDK actions **and the app's own methods** (`{ appMethod: 'saveVendor', description: '...' }`), which widens this considerably. The pattern most worth looking for: work that needs to *read* app state to decide what to do next (fetch rows, loop, research each, update each) hand-rolled as a loop, when the agent could take a read method and a write method and exercise the judgment itself. App methods run as the invoking user with their roles, so authorization is unchanged.
+  Tools are SDK actions **and the app's own methods** (`{ appMethod: 'save-vendor', description: '...' }`), which widens this considerably. The pattern most worth looking for: work that needs to *read* app state to decide what to do next (fetch rows, loop, research each, update each) hand-rolled as a loop, when the agent could take a read method and a write method and exercise the judgment itself. App methods run as the invoking user with their roles, so authorization is unchanged.
 
   Two things NOT to flag. A deterministic sequence that happens to touch several methods — if the order is known up front and no judgment is involved, imperative code is correct and cheaper. And the fire-and-forget background pattern, where a method kicks off `runTask()` and writes the result back in `.then()` with failures landing in `.catch()`: that write-back is doing status management the agent can't do for itself. That one is the recommended pattern, not a smell.
 

package/dist/subagents/designExpert/prompts/instructions.md

@@ -16,6 +16,7 @@ Think about the ways you can truly elevate the design. Use image generation to c
 - After you've taken a screenshot, use analyze image to ask different questions about it - don't re-screenshot the page unnecessarily.
 - Match the image engine to the job: `renderImage` (a browser rendering HTML you author) for token-exact graphics — share cards, wordmarks, flat icon tiles; `generateImages` (an image model) for organic, photographic, and illustrated work. Don't ask the image model to hit exact hex codes or typography, and don't hand-write SVG path data — compose HTML/CSS and render it.
 - When you write user-facing copy (headlines, captions, labels, body text), hand it to `polishCopy` before finalizing. It tightens prose so it reads like a person wrote it rather than a machine, without changing what it says. Cheap and fast — use it on any copy that will ship.
+- Deliver wireframes with `createWireframe`. Include the returned `![name](src/.wireframes/….html)` line in your response where the wireframe belongs — it renders as a live preview, and the developer reads the file for the exact markup.
 
 ## Voice
 - No emoji, no filler.

package/dist/subagents/designExpert/prompts/ui-patterns.md

@@ -25,7 +25,7 @@ Some surfaces are deep enough to carry their own craft reference in <available_s
 
 ### Wireframes
 
-When you need to show a layout, component, interaction, or animation, use a wireframe. Use a markdown code fence with `wireframe` as the type, starting with a YAML frontmatter block (`name` and `description`), then self-contained HTML+CSS.
+When you need to show a layout, component, interaction, or animation, create a wireframe with the `createWireframe` tool: pass a `name`, a one-line `description`, and self-contained HTML+CSS. The tool saves the wireframe as a file under `src/.wireframes/` and returns a markdown reference line like `![Feed Post Card](src/.wireframes/feed-post-card-x7f2.html)` — include that exact line in your response wherever the wireframe belongs, with your notes in the surrounding prose. The reference line renders as a live visual preview, and the developer reads the file itself for the exact markup and CSS.
 
 Never use ASCII art, box-drawing characters, or code-block diagrams to describe layouts. Always use a wireframe instead, even if it's just grey rectangles with labels. A 20-line wireframe with placeholder boxes communicates proportions, spacing, and hierarchy better than any text diagram. For abstract layouts, use skeleton-style placeholders (grey boxes, rounded rects) rather than mocking up real content.
 
@@ -35,13 +35,11 @@ Wireframes render in a small transparent iframe. Set a background color and shad
 
 Wireframes are vanilla HTML/CSS/JS (no React). For animations beyond CSS, use GSAP via CDN: `<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>`
 
-Quick skeleton wireframe (grey boxes, just showing layout and hierarchy):
+Wireframe files are immutable — to revise one, create a new wireframe. If you're iterating on an earlier one, read its file first and riff from there.
 
-```wireframe
----
-name: Content Card Layout
-description: Card with image area, title, metadata row, rating, and actions. Skeleton placeholders showing proportions and hierarchy.
----
+Quick skeleton wireframe (grey boxes, just showing layout and hierarchy) — `createWireframe` with name "Content Card Layout", description "Card with image area, title, metadata row, rating, and actions. Skeleton placeholders showing proportions and hierarchy.", and this html:
+
+```html
 <html lang="en"><head>
 <meta charset="utf-8"/>
 <style>
@@ -74,13 +72,9 @@ description: Card with image area, title, metadata row, rating, and actions. Ske
 </html>
 ```
 
-Detailed component wireframe (showing specific design decisions):
+Detailed component wireframe (showing specific design decisions) — `createWireframe` with name "Feed Post Card", description "Photo post card with header, image frame, action row (like/comment/share/bookmark), like count, and caption. Shows spacing, typography hierarchy, and icon placement.", and this html:
 
-```wireframe
----
-name: Feed Post Card
-description: Photo post card with header, image frame, action row (like/comment/share/bookmark), like count, and caption. Shows spacing, typography hierarchy, and icon placement.
----
+```html
 <html lang="en"><head>
 <meta charset="utf-8"/>
 <meta content="width=device-width, initial-scale=1.0" name="viewport"/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.278",
+  "version": "0.1.280",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",