@mulmoclaude/core 0.5.1 → 0.7.0

package/assets/helps/collection-skills.md

@@ -122,27 +122,27 @@ when the user makes a request.
 Top-level shape (validated on discovery; a malformed schema is logged and
 skipped, never crashes the host):
 
-| Key                    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title`                | Human name shown in the sidebar / header. Required.                                                                                                                                                                                                                                                                                                                                                                           |
-| `icon`                 | A **Material Symbols** name (`receipt_long`, `people`, `schedule`, `menu_book`). Required.                                                                                                                                                                                                                                                                                                                                    |
-| `dataPath`             | Workspace-relative records folder, e.g. `data/recipes/items`. Must stay under the workspace. Required.                                                                                                                                                                                                                                                                                                                        |
-| `primaryKey`           | The field name whose value is the filename. That field MUST set `primary: true`. The value must be a valid record id (see the **Records** section's id-charset rule). Required.                                                                                                                                                                                                                                               |
-| `singleton`            | Optional. When set, at most one record exists, pinned to this exact id (e.g. `me`). Host pre-fills + locks the create form and hides Add once it exists.                                                                                                                                                                                                                                                                      |
-| `fields`               | Ordered map of field-name → field spec. **Insertion order = column order** in the table. Required.                                                                                                                                                                                                                                                                                                                            |
-| `actions`              | Optional array of per-record buttons (see below).                                                                                                                                                                                                                                                                                                                                                                             |
-| `completionField`      | Optional. Name of the field whose value marks an item as "done" — when set, item-create fires a bell notification that clears once the field reaches one of `completionDoneValues`. Must name a real field in `fields`. Paired with `completionDoneValues` (both set, or both omitted).                                                                                                                                       |
-| `completionDoneValues` | Optional. Non-empty array of values that count as "done" for `completionField` (e.g. `["Done"]`, `["paid", "void"]`). Compared as strings.                                                                                                                                                                                                                                                                                    |
-| `notifyWhen`           | Optional. A `when` predicate (`{ "field": "...", "in": [...] }`) that **gates** the completion bell: fire it only for records matching the predicate (e.g. `{ "field": "priority", "in": ["high", "urgent"] }`). Requires `completionField`; `field` must name a real field. Absent ⇒ notify for every open record.                                                                                                           |
-| `displayField`         | Optional. Name of a field whose value is shown as the human-readable label in the completion notification's title (e.g. `Contacts: Jane Doe` instead of the opaque primaryKey). Must name a real field in `fields`. Falls back to the primaryKey value when unset or when the record's value is empty.                                                                                                                        |
-| `triggerField`         | Optional. Name of a `date` field that **delays** the completion bell until that date arrives (instead of firing on create). Requires `completionField` / `completionDoneValues` (the bell still clears via the done value). Must name a real `date` field. See "Time-gated bells" below.                                                                                                                                      |
-| `triggerLeadDays`      | Optional. Non-negative integer: fire the bell this many days **before** `triggerField` (e.g. `10` = "remind me 10 days early"). Requires `triggerField`. Default `0` (fire on the trigger date).                                                                                                                                                                                                                              |
-| `spawn`                | Optional. Host-driven **recurrence**: when a record reaches a configured value (e.g. `status: paid`), the host auto-creates the next record with a forward-advanced `triggerField` date. Requires `triggerField`. See "Recurring obligations" below.                                                                                                                                                                          |
-| `calendarField`        | Optional. Name of a `date` (or `datetime`) field that anchors the **calendar view** (a month grid; each record lands on its date cell). When unset, the table↔calendar toggle still appears if the schema has any `date`/`datetime` field — the first one is used, switchable in-view. Set this to pin a specific anchor. Must name a real `date`/`datetime` field. See "Calendar view" below.                                |
-| `calendarEndField`     | Optional. A second `date`/`datetime` field marking the END of a multi-day span on the calendar (the record renders across `calendarField` → this date). Requires `calendarField`. Must name a real `date`/`datetime` field.                                                                                                                                                                                                   |
-| `calendarTimeField`    | Optional. Name of a string field holding a free-form time or time-range (`"14:00-17:00"`, `"17:00-"`, `"16:30"`) used to place records on the calendar's **day (time-allocation) view**. Consulted only when the date fields are date-only — a `datetime` anchor/end pair carries its own clock and takes precedence. Requires `calendarField`. See "Calendar view" below.                                                    |
-| `kanbanField`          | Optional. Name of an `enum` field that groups records into columns on the **Kanban board** (one column per declared value). When unset, the Kanban toggle still appears if the schema has any `enum` field — the first one is used, switchable in-view. Set this to pin a specific group field. Must name a real `enum` field. See "Kanban view" below.                                                                       |
-| `views`                | Optional. Custom (LLM-authored) HTML views: `[{ id, label, icon?, file, capabilities? }]`. Each renders an HTML file under `views/*.html` in a sandboxed iframe over the records, for layouts the built-ins don't cover (year/quarter overview, Gantt, report). `capabilities` is `["read"]` (default) or `["read","write"]`. See "Custom views" below and **`config/helps/custom-view.md`** for the full authoring contract. |
+| Key                    | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                | Human name shown in the sidebar / header. Required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `icon`                 | A **Material Symbols** name (`receipt_long`, `people`, `schedule`, `menu_book`). Required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `dataPath`             | Workspace-relative records folder, e.g. `data/recipes/items`. Must stay under the workspace. Required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `primaryKey`           | The field name whose value is the filename. That field MUST set `primary: true`. The value must be a valid record id (see the **Records** section's id-charset rule). Required.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `singleton`            | Optional. When set, at most one record exists, pinned to this exact id (e.g. `me`). Host pre-fills + locks the create form and hides Add once it exists.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `fields`               | Ordered map of field-name → field spec. **Insertion order = column order** in the table. Required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `actions`              | Optional array of per-record buttons (see below).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `completionField`      | Optional. Name of the field whose value marks an item as "done" — when set, item-create fires a bell notification that clears once the field reaches one of `completionDoneValues`. Must name a real field in `fields`. Paired with `completionDoneValues` (both set, or both omitted).                                                                                                                                                                                                                                                                                            |
+| `completionDoneValues` | Optional. Non-empty array of values that count as "done" for `completionField` (e.g. `["Done"]`, `["paid", "void"]`). Compared as strings.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `notifyWhen`           | Optional. A `when` predicate (`{ "field": "...", "in": [...] }`) that **gates** the completion bell: fire it only for records matching the predicate (e.g. `{ "field": "priority", "in": ["high", "urgent"] }`). Requires `completionField`; `field` must name a real field. Absent ⇒ notify for every open record.                                                                                                                                                                                                                                                                |
+| `displayField`         | Optional. Name of a field whose value is shown as the human-readable label in the completion notification's title (e.g. `Contacts: Jane Doe` instead of the opaque primaryKey). Must name a real field in `fields`. Falls back to the primaryKey value when unset or when the record's value is empty.                                                                                                                                                                                                                                                                             |
+| `triggerField`         | Optional. Name of a `date` field that **delays** the completion bell until that date arrives (instead of firing on create). Requires `completionField` / `completionDoneValues` (the bell still clears via the done value). Must name a real `date` field. See "Time-gated bells" below.                                                                                                                                                                                                                                                                                           |
+| `triggerLeadDays`      | Optional. Non-negative integer: fire the bell this many days **before** `triggerField` (e.g. `10` = "remind me 10 days early"). Requires `triggerField`. Default `0` (fire on the trigger date).                                                                                                                                                                                                                                                                                                                                                                                   |
+| `spawn`                | Optional. Host-driven **recurrence**: when a record reaches a configured value (e.g. `status: paid`), the host auto-creates the next record with a forward-advanced `triggerField` date. Requires `triggerField`. See "Recurring obligations" below.                                                                                                                                                                                                                                                                                                                               |
+| `calendarField`        | Optional. Name of a `date` (or `datetime`) field that anchors the **calendar view** (a month grid; each record lands on its date cell). When unset, the table↔calendar toggle still appears if the schema has any `date`/`datetime` field — the first one is used, switchable in-view. Set this to pin a specific anchor. Must name a real `date`/`datetime` field. See "Calendar view" below.                                                                                                                                                                                     |
+| `calendarEndField`     | Optional. A second `date`/`datetime` field marking the END of a multi-day span on the calendar (the record renders across `calendarField` → this date). Requires `calendarField`. Must name a real `date`/`datetime` field.                                                                                                                                                                                                                                                                                                                                                        |
+| `calendarTimeField`    | Optional. Name of a string field holding a free-form time or time-range (`"14:00-17:00"`, `"17:00-"`, `"16:30"`) used to place records on the calendar's **day (time-allocation) view**. Consulted only when the date fields are date-only — a `datetime` anchor/end pair carries its own clock and takes precedence. Requires `calendarField`. See "Calendar view" below.                                                                                                                                                                                                         |
+| `kanbanField`          | Optional. Name of an `enum` field that groups records into columns on the **Kanban board** (one column per declared value). When unset, the Kanban toggle still appears if the schema has any `enum` field — the first one is used, switchable in-view. Set this to pin a specific group field. Must name a real `enum` field. See "Kanban view" below.                                                                                                                                                                                                                            |
+| `views`                | Optional. Custom (LLM-authored) HTML views: `[{ id, label, icon?, file, capabilities?, target? }]`. Each renders an HTML file under `views/*.html` in a sandboxed iframe over the records, for layouts the built-ins don't cover (year/quarter overview, Gantt, report). `capabilities` is `["read"]` (default) or `["read","write"]`. `target: "mobile"` makes it a **remote view** for the phone app (different runtime contract — **`config/helps/custom-view-remote.md`**). See "Custom views" below and **`config/helps/custom-view.md`** for the desktop authoring contract. |
 
 ### Field types
 
@@ -744,7 +744,10 @@ in the collection's view-mode selector.
 The host holds **zero** view-specific code — the view is data, like the rest of
 the collection. Full authoring contract (the `window.__MC_VIEW` shape, the
 read/write API, the sandbox rules, and two complete sample views):
-**`config/helps/custom-view.md`**. Read it before authoring a view.
+**`config/helps/custom-view.md`**. Read it before authoring a view. For a view
+that runs on the **phone remote app** (`target: "mobile"` in the `views[]`
+entry) the contract is different and incompatible — read
+**`config/helps/custom-view-remote.md`** instead.
 
 ### Worked example: a Todo list
 
@@ -861,6 +864,6 @@ recipe when the user wants any of them, and copy the schema verbatim:
   - **`profile`** — one record per issuer identity (primary id `me`); each invoice
     picks one.
   - **`invoice`** — the full toolkit in one schema: a `ref` issuer (`issuerId →
-    profile`) embedded via an `idField` `embed`, a `ref` client (`clients`), a
+profile`) embedded via an `idField` `embed`, a `ref` client (`clients`), a
     `table` of line items, three `derived` money fields, an `enum` status, and four
     `actions` (PDF always-on; sale / payment / void gated by `status` via `when`).

package/assets/helps/custom-view-remote.md

@@ -0,0 +1,429 @@
+# Remote custom views (LLM-authored HTML for the phone)
+
+A **remote custom view** is an HTML file you write that renders a collection's
+records **on the user's phone**, inside the mobile remote app. Same idea as a
+desktop custom view (`config/helps/custom-view.md`) — the user asks in plain
+language, you author one HTML file and register it — but the runtime contract
+is **different and incompatible**: the phone cannot reach this machine, so
+there is **no token, no dataUrl, and no `fetch` of any kind**. Records arrive
+through an async bridge instead. Never mix the two contracts in one file.
+
+Read `config/helps/collection-skills.md` first for the collection/schema DSL.
+This file is only about the **remote view** layer.
+
+## Where the files go
+
+Same place as desktop views — the HTML lives under `views/` and must end in
+`.html`. Register it in the collection's `schema.json` with
+**`target: "mobile"`** (that's the whole difference in registration):
+
+```jsonc
+{
+  "views": [{ "id": "phone", "label": "Phone", "target": "mobile", "file": "views/phone.html" }],
+}
+```
+
+- **`target: "mobile"`** — required; without it the view is treated as a
+  desktop view and is never served to the phone.
+- `id` / `label` / `icon` / `i18n` — as for desktop views. The selector icon
+  defaults to `smartphone`.
+- **Read-only by default.** A view with no `editableFields` and no `allowDelete`
+  cannot mutate anything — its `updateItem` / `deleteItem` reject. Declare a
+  write surface only when the user asks the view to _change_ data (toggle a
+  checkbox, delete a row); see **Writing records** below. For anything more
+  open-ended (compose a message, kick off a task) use `startChat`.
+
+Feed collections register theirs in `feeds/<slug>/schema.json` with the HTML
+at `feeds/<slug>/views/<name>.html`, like desktop views.
+
+## Previewing without a phone
+
+After you Write + register the view, its button appears in the collection's
+view selector **on the desktop** and renders inside a **phone-sized frame
+(390×844)** — the exact same wrapped document the phone receives, with the same
+sandbox rules and the same data bridge. A caption under the frame shows the
+file's size against its **900 KB budget** (the view travels to the phone inside
+a size-capped message — stay well under it; a normal view is tens of KB).
+Iterate against this preview; if it works there, it works on the phone.
+
+## The runtime contract — `window.__MC_VIEW`
+
+The host injects a bootstrap into your page **before any of your scripts run**:
+
+```js
+window.__MC_VIEW = {
+  slug: "annual-plan", // this collection
+  locale: "en", // active app locale ("" when no translations)
+  target: "mobile",
+  protocol: 2,
+  writable: false, // true iff the view declared editableFields / allowDelete
+  getItems: (opts) => Promise, // the ONLY way to read records — see below
+  updateItem: (id, patch) => Promise, // patch declared fields (see Writing records)
+  deleteItem: (id) => Promise, // remove a record (requires allowDelete)
+  startChat: (prompt, role) => void, // draft a new chat for the user
+  t: (key, named) => string, // vue-i18n-style dict lookup (same as desktop)
+};
+```
+
+What is deliberately **absent** compared to the desktop contract: `token`,
+`dataUrl` (nothing to fetch), `onChange` (no live refresh yet — re-call
+`getItems` after a mutate resolves), and `openItem` (no host record panel on
+the phone yet).
+
+### Reading records — `getItems` (paginated, always)
+
+```js
+const page = await window.__MC_VIEW.getItems({
+  offset: 0,
+  limit: 50, // clamped to [1, 200]
+  fields: ["title", "start", "status"], // project — list ONLY what you render
+});
+// page = { items: [...], total: 123, offset: 0, limit: 50 }
+```
+
+- **Pagination is mandatory.** Each page travels to the phone through a
+  size-capped channel; you can never assume one call returns everything.
+  Render the first page, then offer a **"Load more"** affordance while
+  `items.length < total` (see the example).
+- **Always pass `fields`.** The projection keeps pages small (the primary key
+  is always included). List the columns your view actually renders.
+- The promise **rejects** on failure or after a 30 s timeout — catch it and
+  show the message; don't fail silently.
+- **`derived` formulas that read only the record's own fields come back
+  resolved** (e.g. `won * 3 + drawn`). Formulas that dereference a `ref`
+  field, and `embed` fields, are NOT resolved on the phone — don't rely on
+  them; compute from base fields or omit.
+
+### Writing records — `updateItem` / `deleteItem`
+
+A remote view may **change** data too — flip a todo's `done`, edit a status,
+delete a row — but only within a surface the view **declares** and the host
+**enforces**. Nothing is writable by default.
+
+**1. Declare the surface** in the `views[]` entry:
+
+```jsonc
+{
+  "id": "phone",
+  "label": "Todos",
+  "target": "mobile",
+  "file": "views/phone.html",
+  "editableFields": ["done"], // ONLY these fields may be patched
+  "allowDelete": true, // omit / false ⇒ deleteItem is refused
+}
+```
+
+**2. Call the methods** (both resolve/reject like `getItems`):
+
+```js
+const { item } = await window.__MC_VIEW.updateItem(id, { done: true });
+// patch is a partial record; the host merges it onto the stored record and
+// returns the merged { item }.
+
+const { id: removed } = await window.__MC_VIEW.deleteItem(id);
+```
+
+- **The host is the authority, not the view.** Every mutate is re-checked
+  server-side: a patch key not in `editableFields` (or the primary key) is
+  **refused**; `deleteItem` without `allowDelete` is **refused**. The promise
+  rejects with the reason — surface it. Declaring the surface honestly is how
+  you keep the blast radius small.
+- **No `writable` declaration ⇒ the methods reject** (`"this view is
+  read-only"`). Check `window.__MC_VIEW.writable` before showing edit affordances
+  if you want to degrade gracefully.
+- **`editableFields` never includes the primary key** — a record's id is fixed.
+- **Re-render after a mutate resolves.** There is no live `onChange` yet: either
+  optimistically update your local copy from the returned `item`, or re-call
+  `getItems` to refetch. The preview's real write also refreshes the desktop
+  collection, so you see the true result while iterating.
+- **Create is not available** in this phase — `updateItem` only patches an
+  existing record; use `startChat` to ask the agent to add a new one.
+
+### Starting a chat — `startChat`
+
+Identical to the desktop helper: opens a **new chat with your prompt prefilled
+as an editable draft** — it does NOT auto-send; the user reviews and sends.
+This is the only way a remote view "does" anything beyond display:
+
+```js
+window.__MC_VIEW.startChat("Mark task " + item.id + " as done.");
+```
+
+### Translations — `t`
+
+Same contract as desktop: declare `"i18n": "views/<name>.i18n.json"` in the
+`views[]` entry (vue-i18n locale-message shape); the host picks the active
+locale's flat dict server-side and `t(key, named)` interpolates `{name}`
+placeholders, falling back to the key.
+
+## Design for the phone — not a shrunken desktop
+
+The frame is a real phone viewport. **Do not miniaturize a desktop layout**
+(a 12-month grid becomes an unreadable postage stamp); pick a vertically
+composable idiom instead — a scrolling agenda, a card list, stacked sections.
+
+- **Required `<head>`**: build a full document with
+  `<meta charset="utf-8">` and
+  `<meta name="viewport" content="width=device-width, initial-scale=1">`.
+- **Single column, vertical scroll.** No fixed pixel widths, no horizontal
+  scroll, percentages / flex / grid over absolute positioning.
+- **Touch, not pointer**: tap targets ≥ 44px tall, generous spacing, **no
+  hover-dependent affordances** (there is no hover).
+- **Respect the notch**: pad fixed headers/footers with
+  `env(safe-area-inset-top)` / `env(safe-area-inset-bottom)`.
+- **System fonts** (`system-ui, sans-serif`) render instantly; heavy chart
+  libraries that feel fine on desktop are sluggish on a phone — prefer plain
+  DOM/SVG unless a chart is the point.
+
+## Sandbox rules (what the view may and may not do)
+
+The view runs in a `sandbox="allow-scripts"` iframe with a CSP **stricter**
+than desktop views:
+
+- **`fetch` / XHR / WebSocket are blocked to EVERY origin** (`connect-src
+'none'`). There is nothing to fetch — records come only through
+  `getItems`. Never write `fetch(...)` in a remote view.
+- **Inline `<script>` / `<style>` work**, and external scripts/styles/fonts
+  may load from the same curated CDNs as desktop views (`cdn.jsdelivr.net`,
+  `unpkg.com`, `cdnjs.cloudflare.com`, Google Fonts, `cdn.plot.ly`) — the
+  phone has internet; only this machine is unreachable. Prefer self-contained
+  HTML anyway (see the size budget).
+- **`<img>` / `<audio>` / `<video>` may load any `https:` URL** (plus `data:`
+  / `blob:`) — a record's public image/media URL renders. A **workspace file
+  path does not** (it lives on this machine, which the phone can't reach):
+  treat `image`-type fields as desktop-only and skip or placeholder them.
+- **Outbound links**: `<a href="…" target="_blank" rel="noopener">` opens
+  normally; a same-tab `<a href>` is blocked by the sandbox.
+- No cookies, no `localStorage`, no parent access — and no token exists in
+  this contract at all.
+
+## Editing / iterating
+
+Read + Edit the `views/<name>.html` file under the collection's skill dir,
+exactly like a desktop view; the desktop preview re-renders on reload. To
+remove one, delete the file and its `views[]` entry.
+
+---
+
+## Example — mobile card list with "Load more"
+
+A phone-first record list: single column, 44px+ tap targets, paginated through
+`getItems`, a `startChat` action per card. Schema has `title` (string),
+`status` (enum), `start` (date). Registration:
+`{ "id": "phone", "label": "Phone", "target": "mobile", "file": "views/phone.html" }`.
+
+`data/skills/annual-plan/views/phone.html`:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        margin: 0;
+        padding: 12px;
+        padding-bottom: calc(12px + env(safe-area-inset-bottom));
+        background: #f8fafc;
+        color: #1e293b;
+      }
+      h1 {
+        font-size: 17px;
+        margin: 4px 4px 12px;
+      }
+      .card {
+        background: white;
+        border: 1px solid #e2e8f0;
+        border-radius: 12px;
+        padding: 12px 14px;
+        margin-bottom: 10px;
+        min-height: 44px;
+      }
+      .card b {
+        font-size: 15px;
+      }
+      .meta {
+        display: flex;
+        gap: 8px;
+        margin-top: 6px;
+        font-size: 13px;
+        color: #64748b;
+        align-items: center;
+      }
+      .badge {
+        background: #eef2ff;
+        color: #3730a3;
+        border-radius: 999px;
+        padding: 2px 10px;
+        font-size: 12px;
+      }
+      button {
+        min-height: 44px;
+        border: 0;
+        border-radius: 10px;
+        font-size: 15px;
+        font-weight: 600;
+      }
+      .chat {
+        margin-left: auto;
+        background: #f1f5f9;
+        color: #334155;
+        padding: 0 14px;
+      }
+      .more {
+        width: 100%;
+        background: #4f46e5;
+        color: white;
+        margin-top: 4px;
+      }
+      .err {
+        color: #b91c1c;
+        padding: 12px;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Annual plan</h1>
+    <div id="list"></div>
+    <button id="more" class="more" hidden>Load more</button>
+    <script>
+      var FIELDS = ["title", "status", "start"]; // project ONLY what we render
+      var PAGE = 50;
+      var loaded = [];
+      var total = 0;
+
+      function card(item) {
+        var el = document.createElement("div");
+        el.className = "card";
+        var meta =
+          '<div class="meta"><span class="badge">' +
+          (item.status || "-") +
+          "</span><span>" +
+          (item.start || "") +
+          "</span>" +
+          '<button class="chat" data-id="' +
+          item.id +
+          '">Chat</button></div>';
+        el.innerHTML = "<b></b>" + meta;
+        el.querySelector("b").textContent = item.title || item.id;
+        return el;
+      }
+
+      function render(items) {
+        var list = document.getElementById("list");
+        items.forEach(function (item) {
+          list.appendChild(card(item));
+        });
+        document.getElementById("more").hidden = loaded.length >= total;
+      }
+
+      async function loadMore() {
+        var page = await window.__MC_VIEW.getItems({ offset: loaded.length, limit: PAGE, fields: FIELDS });
+        total = page.total;
+        loaded = loaded.concat(page.items);
+        render(page.items);
+      }
+
+      document.getElementById("more").onclick = function () {
+        loadMore().catch(showError);
+      };
+      document.getElementById("list").onclick = function (e) {
+        var btn = e.target.closest(".chat");
+        if (!btn) return;
+        var item = loaded.find(function (r) {
+          return String(r.id) === btn.dataset.id;
+        });
+        if (item) window.__MC_VIEW.startChat("Give me an update plan for: " + (item.title || item.id));
+      };
+
+      function showError(err) {
+        document.getElementById("list").innerHTML = '<div class="err">Could not load: ' + err.message + "</div>";
+      }
+      loadMore().catch(showError);
+    </script>
+  </body>
+</html>
+```
+
+## Example — writable todo (toggle `done`, delete)
+
+A phone-first todo list that **checks off** and **deletes** records. Schema has
+`title` (string) and `done` (boolean). Registration declares the write surface:
+`{ "id": "phone", "label": "Todos", "target": "mobile", "file": "views/phone.html", "editableFields": ["done"], "allowDelete": true }`.
+
+The core of `views/phone.html` (styles/`<head>` as above):
+
+```html
+<div id="list"></div>
+<script>
+  var items = [];
+
+  function row(item) {
+    var el = document.createElement("div");
+    el.className = "card";
+    el.innerHTML =
+      '<label class="meta"><input type="checkbox" data-toggle="' +
+      item.id +
+      '"' +
+      (item.done ? " checked" : "") +
+      ' style="width:22px;height:22px"><b></b>' +
+      '<button class="chat" data-del="' +
+      item.id +
+      '" style="margin-left:auto">Delete</button></label>';
+    el.querySelector("b").textContent = item.title || item.id;
+    if (item.done) el.style.opacity = 0.5;
+    return el;
+  }
+
+  function render() {
+    var list = document.getElementById("list");
+    list.innerHTML = "";
+    items.forEach(function (item) {
+      list.appendChild(row(item));
+    });
+  }
+
+  async function load() {
+    var page = await window.__MC_VIEW.getItems({ offset: 0, limit: 200, fields: ["title", "done"] });
+    items = page.items;
+    render();
+  }
+
+  document.getElementById("list").addEventListener("change", async function (e) {
+    var id = e.target.dataset.toggle;
+    if (!id) return;
+    try {
+      // Host merges the patch and returns the merged record; reflect it.
+      var res = await window.__MC_VIEW.updateItem(id, { done: e.target.checked });
+      var i = items.findIndex(function (r) {
+        return String(r.id) === id;
+      });
+      if (i >= 0) items[i] = res.item;
+      render();
+    } catch (err) {
+      e.target.checked = !e.target.checked; // revert on refusal
+      alert(err.message);
+    }
+  });
+
+  document.getElementById("list").addEventListener("click", async function (e) {
+    var id = e.target.dataset.del;
+    if (!id) return;
+    try {
+      await window.__MC_VIEW.deleteItem(id);
+      items = items.filter(function (r) {
+        return String(r.id) !== id;
+      });
+      render();
+    } catch (err) {
+      alert(err.message);
+    }
+  });
+
+  load().catch(function (err) {
+    document.getElementById("list").innerHTML = '<div class="err">' + err.message + "</div>";
+  });
+</script>
+```

package/assets/helps/custom-view.md

@@ -7,7 +7,10 @@ collection's data. The user asks for it in plain language ("give me a view that
 shows my whole year"); you author the HTML and register it.
 
 Read `config/helps/collection-skills.md` first for the collection/schema DSL.
-This file is only about the **view** layer.
+This file is only about the **desktop view** layer. For a view that runs on the
+**phone remote app** (`target: "mobile"` in the `views[]` entry), read
+`config/helps/custom-view-remote.md` instead — its runtime contract is
+different and incompatible (no token, no dataUrl, no fetch).
 
 ## Where the files go
 
@@ -32,9 +35,7 @@ the collection's `schema.json`:
   "icon": "calendar_month",
   "dataPath": "data/annual-plan/items",
   "primaryKey": "id",
-  "fields": {
-    /* … */
-  },
+  "fields": {/* … */},
   "views": [
     { "id": "year", "label": "Year", "icon": "grid_view", "file": "views/year.html", "capabilities": ["read"] },
     { "id": "planner", "label": "Planner", "icon": "edit_calendar", "file": "views/planner.html", "capabilities": ["read", "write"] },

package/assets/helps/index.md

@@ -43,7 +43,11 @@ See [Collection skills](config/helps/collection-skills.md) for the full schema D
 
 When the built-in table / calendar / kanban / dashboard views don't fit what you want to _see_ — a year-at-a-glance planner, a Gantt bar, a heat-map, a printable report — Claude authors a **custom view**: a single HTML file rendered in a sandboxed iframe over the collection's records. It reads (and optionally writes) records through a scoped token, stays live as the data changes, and can hand work back to a chat — all without any view-specific host code. The view is data, just like the rest of the collection, so you can ask for an entirely new way to look at your data in plain language and get it.
 
-See [Custom views](config/helps/custom-view.md) for the authoring contract.
+See [Custom views](config/helps/custom-view.md) for the authoring contract. A
+view can also target the **mobile remote app** (`target: "mobile"`) — rendered
+on the user's phone and previewed on the desktop in a phone-sized frame; that
+variant has a different, incompatible runtime contract described in
+[Remote custom views](config/helps/custom-view-remote.md).
 
 ## Wiki — Long-Term Memory
 
@@ -69,6 +73,7 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [GitHub repositories in the workspace](config/helps/github.md) — clone-destination rules under `github/<name>/` and how to handle existing directories with matching or different remotes
 - [Collection skills](config/helps/collection-skills.md) — build a data app (model + UI + relations + computed fields + action buttons) by authoring a `schema.json` collection skill: the DSL, field types, derived formulas, actions, records
 - [Custom views](config/helps/custom-view.md) — give a collection a view the built-ins don't cover (year/quarter overview, Gantt): an HTML file under `views/`, registered in `schema.json`, rendered in a sandboxed iframe over the records
+- [Remote custom views](config/helps/custom-view-remote.md) — author a collection view for the **phone remote app** (`target: "mobile"` in `views[]`): records via the `getItems` bridge (no token, no fetch), mobile-first layout rules, phone-frame preview
 - [Todo list collection](config/helps/todo-collection.md) — the canonical recipe for building or migrating a todo / task list: full schema (status enum + `done` toggle + priority bells), `SKILL.md`, and legacy `todo-plugin` migration steps
 - [Vocabulary collection](config/helps/vocabulary.md) — recipe for a language-learning word deck (any language): `proficiency` enum + `mastered` toggle + `meaning`/`example` fields, a kanban for drag-to-promote review, and bulk-add / quiz workflows
 - [Lessons collection](config/helps/lessons-collection.md) — recipe for a multi-session **curriculum** (any topic): one lesson per record, a `status` kanban, a `file` link to each lesson's HTML, and per-lesson + course-level **Learn** actions run by the Tutor

package/dist/collection/core/schema.d.ts

@@ -176,6 +176,21 @@ export interface CollectionCustomView {
      *  (least privilege); declare `["read","write"]` only for views that
      *  edit records. The mint endpoint clamps any requested caps to this. */
     capabilities?: CollectionViewCapability[];
+    /** Where the view runs. Absent ⇒ `"desktop"` (this token/dataUrl contract).
+     *  `"mobile"` ⇒ a remote view for the phone client: served through the
+     *  command channel's `getRemoteView` over the postMessage contract
+     *  (`@mulmoclaude/core/remote-view` — no token, `connect-src 'none'`) and
+     *  previewed on desktop inside a phone-sized frame. */
+    target?: "desktop" | "mobile";
+    /** **Mobile-only** (ignored for desktop views, which use token-scoped
+     *  `capabilities`). The whitelist of field names a `target: "mobile"` view
+     *  may patch via `__MC_VIEW.updateItem(id, patch)`. Default-deny: absent or
+     *  empty ⇒ updates are refused host-side. Never include the primary key.
+     *  See plans/feat-remote-writable-view.md. */
+    editableFields?: string[];
+    /** **Mobile-only.** When `true`, a `target: "mobile"` view may remove a
+     *  record via `__MC_VIEW.deleteItem(id)`. Absent/`false` ⇒ deletes refused. */
+    allowDelete?: boolean;
 }
 /** A schema-declared, per-record action rendered as a button in the
  *  read-only detail view. Pure UI/behaviour directive — never stored,

package/dist/collection/registry/server/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../../../rolldown-runtime-D6vf50IK.cjs");
-const require_server = require("../../../server-cmnH6g2O.cjs");
+const require_server = require("../../../server-DBi5HmrM.cjs");
 const require_collection_paths = require("../../paths.cjs");
 const require_types = require("../../../types-CNqkLT4M.cjs");
 const require_skill_bridge_index = require("../../../skill-bridge/index.cjs");

package/dist/collection/registry/server/index.js

@@ -1,4 +1,4 @@
-import { K as collectionsRegistriesConfigPath, L as writeFileAtomic, W as safeRecordId, Y as log, _ as acceptParsedSchema, g as CollectionSchemaZ, m as errorMessage, p as ONE_SECOND_MS, y as loadCollection } from "../../../server-D44bvGjw.js";
+import { K as collectionsRegistriesConfigPath, L as writeFileAtomic, W as safeRecordId, Y as log, _ as acceptParsedSchema, g as CollectionSchemaZ, m as errorMessage, p as ONE_SECOND_MS, y as loadCollection } from "../../../server-DgAdWcCM.js";
 import { isSafeActionTemplatePath } from "../../paths.js";
 import { n as parseRegistryIndex, r as isRecord, t as OFFICIAL_REGISTRY_NAME } from "../../../types-BKVZrtyc.js";
 import { claudeSkillDir, dataSkillDir, mirrorSkillWrite } from "../../../skill-bridge/index.js";

package/dist/collection/server/discovery.d.ts

@@ -143,12 +143,18 @@ export declare const CollectionSchemaZ: z.ZodObject<{
         id: z.ZodString;
         label: z.ZodString;
         icon: z.ZodOptional<z.ZodString>;
+        target: z.ZodOptional<z.ZodEnum<{
+            desktop: "desktop";
+            mobile: "mobile";
+        }>>;
         file: z.ZodString;
         i18n: z.ZodOptional<z.ZodString>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
             read: "read";
             write: "write";
         }>>>;
+        editableFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowDelete: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     notifyWhen: z.ZodOptional<z.ZodObject<{
         field: z.ZodString;

package/dist/collection/server/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("../../server-cmnH6g2O.cjs");
+const require_server = require("../../server-DBi5HmrM.cjs");
 const require_collection_paths = require("../paths.cjs");
 exports.COMPUTED_TYPES = require_server.COMPUTED_TYPES;
 exports.CollectionSchemaZ = require_server.CollectionSchemaZ;