@mulmoclaude/core 0.5.0 → 0.6.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,293 @@
+# 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`.
+- **No `capabilities`** — remote views are **read-only** in this phase. There
+  is no write path; a button that should _do_ something uses `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: 1,
+  getItems: (opts) => Promise, // the ONLY way to read records — see below
+  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 — render on
+load), 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.
+- Records come back with computed fields already resolved, like desktop.
+
+### 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>
+```

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,12 @@ 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";
 }
 /** 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-DoDXibCq.cjs");
+const require_server = require("../../../server-Ch1cWphH.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 { G as collectionsRegistriesConfigPath, I as writeFileAtomic, J as log, U as safeRecordId, _ as acceptParsedSchema, g as CollectionSchemaZ, m as errorMessage, p as ONE_SECOND_MS, y as loadCollection } from "../../../server-DRoqc8dL.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-_fgRpzVL.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,6 +143,10 @@ 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<{

package/dist/collection/server/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_server = require("../../server-DoDXibCq.cjs");
+const require_server = require("../../server-Ch1cWphH.cjs");
 const require_collection_paths = require("../paths.cjs");
 exports.COMPUTED_TYPES = require_server.COMPUTED_TYPES;
 exports.CollectionSchemaZ = require_server.CollectionSchemaZ;
@@ -33,6 +33,7 @@ exports.loadCollection = require_server.loadCollection;
 exports.log = require_server.log;
 exports.maybeSpawnSuccessor = require_server.maybeSpawnSuccessor;
 exports.parseCivil = require_server.parseCivil;
+exports.promptPathsFor = require_server.promptPathsFor;
 exports.publishCollectionChange = require_server.publishCollectionChange;
 exports.readCustomViewHtml = require_server.readCustomViewHtml;
 exports.readCustomViewI18n = require_server.readCustomViewI18n;

package/dist/collection/server/index.js

@@ -1,3 +1,3 @@
-import { A as readCustomViewHtml, B as itemFilePath, C as validateCollectionRecords, D as deleteItem, E as buildCollectionActionSeedPrompt, F as writeItem, H as resolveTemplatePath, J as log, K as configureCollectionHost, L as SCHEMA_FILE, M as readItem, N as readSkillTemplate, O as generateItemId, P as resolveCreateItemId, R as isContainedInRoot, S as COMPUTED_TYPES, T as buildActionSeedPrompt, U as safeRecordId, V as resolveDataDir, W as safeSlugName, X as setCollectionChangePublisher, Y as publishCollectionChange, _ as acceptParsedSchema, a as computeSuccessor, b as toDetail, c as isTriggerDue, d as resolveEvery, f as successorId, g as CollectionSchemaZ, h as enrichItems, i as advanceTriggerDate, j as readCustomViewI18n, k as listItems, l as maybeSpawnSuccessor, n as deleteCollection, o as daysInMonth, q as getWorkspaceRoot, r as deleteCollectionRefusalMessage, s as formatCivil, t as deleteCustomView, u as parseCivil, v as discoverCollections, w as validateRecordObject, x as toSummary, y as loadCollection, z as isContainedInWorkspace } from "../../server-DRoqc8dL.js";
+import { A as promptPathsFor, B as isContainedInWorkspace, C as validateCollectionRecords, D as deleteItem, E as buildCollectionActionSeedPrompt, F as resolveCreateItemId, G as safeSlugName, H as resolveDataDir, I as writeItem, J as getWorkspaceRoot, M as readCustomViewI18n, N as readItem, O as generateItemId, P as readSkillTemplate, R as SCHEMA_FILE, S as COMPUTED_TYPES, T as buildActionSeedPrompt, U as resolveTemplatePath, V as itemFilePath, W as safeRecordId, X as publishCollectionChange, Y as log, Z as setCollectionChangePublisher, _ as acceptParsedSchema, a as computeSuccessor, b as toDetail, c as isTriggerDue, d as resolveEvery, f as successorId, g as CollectionSchemaZ, h as enrichItems, i as advanceTriggerDate, j as readCustomViewHtml, k as listItems, l as maybeSpawnSuccessor, n as deleteCollection, o as daysInMonth, q as configureCollectionHost, r as deleteCollectionRefusalMessage, s as formatCivil, t as deleteCustomView, u as parseCivil, v as discoverCollections, w as validateRecordObject, x as toSummary, y as loadCollection, z as isContainedInRoot } from "../../server-_fgRpzVL.js";
 import { isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath } from "../paths.js";
-export { COMPUTED_TYPES, CollectionSchemaZ, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, buildActionSeedPrompt, buildCollectionActionSeedPrompt, computeSuccessor, configureCollectionHost, daysInMonth, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, enrichItems, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, maybeSpawnSuccessor, parseCivil, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readSkillTemplate, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, safeRecordId, safeSlugName, setCollectionChangePublisher, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };
+export { COMPUTED_TYPES, CollectionSchemaZ, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, buildActionSeedPrompt, buildCollectionActionSeedPrompt, computeSuccessor, configureCollectionHost, daysInMonth, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, enrichItems, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, maybeSpawnSuccessor, parseCivil, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readSkillTemplate, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, safeRecordId, safeSlugName, setCollectionChangePublisher, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

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

@@ -133,15 +133,43 @@ export declare function resolveCreateItemId(schema: CollectionSchema, record: Co
  *  the file contents, or null when the path escapes the skill dir, the
  *  resolved target isn't a regular file, or the read fails. */
 export declare function readSkillTemplate(skillDir: string, templateRelPath: string): Promise<string | null>;
+/** Host-controlled canonical paths threaded into the seed prompt so a
+ *  template that shells out to a bundled ingest script (e.g. `python3
+ *  data/<slug>/fetch.py`) can point at the paths the host actually reads
+ *  from — not the (author-declared) paths the script's `--out-dir` default
+ *  bakes in. `dataPath` is the R3-normalized value (`data/collections/<slug>/
+ *  items`), NOT whatever the author wrote in schema.json before import.
+ *  `skillDir` and `dataPath` are meant to be workspace-relative so shell
+ *  commands run against the workspace CWD without ceremony. `slug` is the
+ *  post-rename local slug for scripts that need to log / self-identify.
+ *  All three are host-derived (never user-writable input), so they don't
+ *  need `sanitizeDeep` for injection defense — the standard `<`-escape on
+ *  the JSON block covers a hypothetical hostile character. Fixes #1891. */
+export interface CollectionPromptPaths {
+    slug: string;
+    dataPath: string;
+    skillDir: string;
+}
+/** Build the paths block from a discovered collection. `skillDir` is
+ *  converted to workspace-relative so shell / script invocations compose
+ *  cleanly with the workspace-relative `dataPath`; if the skill lives outside
+ *  the workspace (user-scope collection under `~/.claude/skills/`), the
+ *  absolute path is emitted so the agent can still address it. `dataPath` is
+ *  read straight from the schema — post-R3-normalization for imported
+ *  collections, so it reflects what the host actually reads/writes. */
+export declare function promptPathsFor(collection: Pick<LoadedCollection, "slug" | "schema" | "skillDir">, workspaceRoot: string): CollectionPromptPaths;
 /** Build the seed prompt for a `kind: "chat"` action: a security-
- *  boundary instruction + the record as a sanitized JSON data block +
- *  the template text verbatim. Pure + exported for tests. Domain-free —
- *  the template (skill-owned) carries every specific instruction; the
- *  host only injects the record's own data. */
-export declare function buildActionSeedPrompt(record: CollectionItem, templateText: string): string;
+ *  boundary instruction + optional host paths block + the record as a
+ *  sanitized JSON data block + the template text verbatim. Pure + exported
+ *  for tests. Domain-free — the template (skill-owned) carries every
+ *  specific instruction; the host only injects the record's own data and
+ *  its canonical paths. */
+export declare function buildActionSeedPrompt(record: CollectionItem, templateText: string, paths?: CollectionPromptPaths): string;
 /** Build the seed prompt for a collection-level `kind: "chat"` action: a
- *  security-boundary instruction + a compact progress summary of every
- *  record (see `progressSummary`) + the template verbatim. Pure +
- *  exported for tests. Domain-free — the template carries the specifics. */
-export declare function buildCollectionActionSeedPrompt(items: CollectionItem[], schema: CollectionSchema, templateText: string): string;
+ *  security-boundary instruction + optional host paths block + a compact
+ *  progress summary of every record (see `progressSummary`) + the template
+ *  verbatim. Pure + exported for tests. Domain-free — the template carries
+ *  the specifics. The paths arg (#1891) plugs the R3-normalization gap so
+ *  ingest scripts write to the location the host actually reads from. */
+export declare function buildCollectionActionSeedPrompt(items: CollectionItem[], schema: CollectionSchema, templateText: string, paths?: CollectionPromptPaths): string;
 export {};

package/dist/collection-watchers/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_collection_index = require("../collection/index.cjs");
-const require_server = require("../server-DoDXibCq.cjs");
+const require_server = require("../server-Ch1cWphH.cjs");
 const require_notifier = require("../notifier-bS8IEeLA.cjs");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");

package/dist/collection-watchers/index.js

@@ -1,5 +1,5 @@
 import { whenMatches } from "../collection/index.js";
-import { M as readItem, c as isTriggerDue, k as listItems, l as maybeSpawnSuccessor, v as discoverCollections, y as loadCollection } from "../server-DRoqc8dL.js";
+import { N as readItem, c as isTriggerDue, k as listItems, l as maybeSpawnSuccessor, v as discoverCollections, y as loadCollection } from "../server-_fgRpzVL.js";
 import { d as publish, m as updateForPlugin, n as clear, s as listAll } from "../notifier-ChpY0XrY.js";
 import { watch } from "node:fs";
 import { mkdir } from "node:fs/promises";