@mulmoclaude/core 0.2.11 → 0.2.14

package/assets/helps/billing-invoice.md

@@ -3,11 +3,12 @@
 Read this when the user asks to **set up invoicing / billing** (sample query:
 *"Set up invoicing for my business"*). It scaffolds **two** collection skills:
 
-- **`profile`** — the user's **own** business identity (the "bill-from" block:
-  company name, tax ID, payment details). A singleton (one record, id `me`).
-- **`invoice`** — an invoice ledger; each invoice references a client, embeds the
-  profile as the issuer, and carries a table of line items with host-computed
-  subtotal / tax / total.
+- **`profile`** — the user's **own** business identit(ies) (the "bill-from" block:
+  company name, tax ID, payment details). One or more records, one per issuer; the
+  primary one is id `me`.
+- **`invoice`** — an invoice ledger; each invoice references a client, picks an
+  issuer profile (`issuerId` → `profile`) which it embeds as the bill-from block,
+  and carries a table of line items with host-computed subtotal / tax / total.
 
 This is **Bundle B** of the billing suite. It **builds on Bundle A**
 (`clients` + `worklog`, see `config/helps/billing-clients-worklog.md`):
@@ -37,7 +38,10 @@ use the `mc-` prefix.**
 > other collections in the workspace. The whole point is a reproducible billing
 > suite. (For a *custom* collection, use `config/helps/collection-skills.md`
 > instead.) Existing records under `data/invoice/items` / `data/profile/items`
-> already match these schemas and will render as-is — no data edits needed.
+> render as-is, with one exception: because `invoice.issuerId` is new and
+> required, **backfill `issuerId: "me"` on any pre-existing invoice records** (a
+> `manageCollection` `putItems` with `mode: "merge"`) so their issuer block
+> resolves — otherwise they show a "missing issuer" prompt until set.
 
 ## Slug contract (do not change these)
 
@@ -45,7 +49,7 @@ use the `mc-` prefix.**
 
 | Collection | slug | `dataPath` | referenced by |
 |---|---|---|---|
-| Profile | `profile` | `data/profile/items` | `invoice.issuer` (embed `profile/me`) |
+| Profile | `profile` | `data/profile/items` | `invoice.issuerId` (ref) + `invoice.issuer` (embed via `idField`) |
 | Invoice | `invoice` | `data/invoice/items` | — |
 | Clients | `clients` | `data/clients/items` | `invoice.clientId` (ref, from Bundle A) |
 
@@ -56,13 +60,15 @@ use the `mc-` prefix.**
 
 ## Order: `profile` before `invoice`
 
-`invoice.issuer` embeds the `profile/me` record, so create `profile` first.
+`invoice.issuerId` references a `profile` record (and `issuer` embeds it), so
+create `profile` first.
 
 ---
 
 ## 1. `profile`
 
-`data/skills/profile/schema.json` (a **singleton** — exactly one record, id `me`):
+`data/skills/profile/schema.json` (one record per issuer; the primary one is id
+`me` — **not** a singleton, so an invoice can pick among several issuers):
 
 ```json
 {
@@ -70,7 +76,6 @@ use the `mc-` prefix.**
   "icon": "badge",
   "dataPath": "data/profile/items",
   "primaryKey": "id",
-  "singleton": "me",
   "fields": {
     "id":                { "type": "string",   "label": "ID", "primary": true, "required": true },
     "companyName":       { "type": "string",   "label": "Company / legal name", "required": true },
@@ -90,25 +95,27 @@ use the `mc-` prefix.**
 ```markdown
 ---
 name: profile
-description: The user's own business profile — the issuer ("bill-from") identity
-  used on invoices. A singleton collection with exactly one record, id `me`. The
-  record lives at `data/profile/items/me.json`; the user views and edits it at
-  `/collections/profile`. Record I/O via the `manageCollection` tool (raw
-  Read / Write / Edit on the JSON file is the escape hatch).
+description: The user's own business profile(s) — the issuer ("bill-from") identity
+  used on invoices. One or more records, each an issuer; the primary one is `me`.
+  Records live at `data/profile/items/<id>.json`; the user views and edits them at
+  `/collections/profile`. Each invoice picks one via its `issuerId` ref. Record I/O
+  via the `manageCollection` tool (raw Read / Write / Edit on the JSON is the escape hatch).
 ---
 
 # Business Profile (schema-driven collection)
 
-Holds the user's **own** business identity — the "bill-from" side of an invoice.
-Counterpart to `clients`, which holds the "bill-to" parties.
+Holds the user's **own** business identit(ies) — the "bill-from" side of an
+invoice. Counterpart to `clients`, which holds the "bill-to" parties.
 
-## Singleton — exactly one record, id `me`
-This collection has **one** record. Its primary key is always the literal string
-`me`, stored at `data/profile/items/me.json`. Never create a second record and
-never invent another id — read, create, and update `me.json` only.
+## Multiple issuers — `me` is the primary one
+This collection can hold **several** records, one per issuer identity (a personal
+name, a company, a second LLC). The primary profile keeps the id `me`, stored at
+`data/profile/items/me.json`; add more with their own kebab-case ids (e.g.
+`pervasive`, `personal`). An invoice points at one via its `issuerId`, so a
+profile must exist before an invoice can reference it.
 
 ## Record shape
-- `id` — string, **primary key**, always `me`
+- `id` — string, **primary key** (kebab-case slug; the primary profile is `me`)
 - `companyName` — string, **required** (the legal/company name shown on invoices)
 - `taxRegistrationId` — string (VAT / EIN / JP T-number — region-dependent)
 - `email` — email
@@ -123,18 +130,20 @@ never invent another id — read, create, and update `me.json` only.
 Leave optional fields the user hasn't given you out of the JSON entirely.
 
 ## What to do
-**Set up / update**: Read `data/profile/items/me.json` (may not exist yet), merge
-changes, Write back. Preserve fields you weren't asked to change. If missing and
-the user wants to set their profile, create it with `id: "me"` plus the fields
-they provided.
+**Set up / update**: Read the relevant `data/profile/items/<id>.json` (the primary
+one is `me.json`, may not exist yet), merge changes, Write back. Preserve fields
+you weren't asked to change. When creating the primary profile use `id: "me"`; for
+an additional issuer, list `data/profile/items/` first and pick a fresh kebab-case
+id.
 
-**Look up**: Read `me.json` and answer from it. If missing, tell the user their
-profile isn't set up yet and offer to collect it (`presentForm` only if several
-fields are needed at once).
+**Look up**: Read the relevant profile JSON and answer from it. If the primary
+`me.json` is missing, tell the user their profile isn't set up yet and offer to
+collect it (`presentForm` only if several fields are needed at once).
 
-**Never delete** the profile unless the user explicitly asks to reset it.
+**Never delete** a profile unless the user explicitly asks to — an invoice's
+`issuerId` ref breaks if you remove a profile it points at.
 
-## Linking to the profile in chat
+## Linking to a profile in chat
 - Do: `[your business profile](/collections/profile?selected=me)`
 - Don't: link the raw JSON path.
 
@@ -147,8 +156,9 @@ only when you genuinely need several fields they haven't provided.
 
 ## 2. `invoice`
 
-`data/skills/invoice/schema.json` (`issuer` embeds `profile/me`; `clientId` is a
-`ref` **to `clients`**; subtotal / tax / total are `derived`):
+`data/skills/invoice/schema.json` (`issuerId` is a `ref` **to `profile`** and
+`issuer` embeds whichever profile it names via `idField`; `clientId` is a `ref`
+**to `clients`**; subtotal / tax / total are `derived`):
 
 ```json
 {
@@ -158,7 +168,8 @@ only when you genuinely need several fields they haven't provided.
   "primaryKey": "id",
   "fields": {
     "id":        { "type": "string", "label": "ID", "primary": true, "required": true },
-    "issuer":    { "type": "embed",  "to": "profile", "id": "me", "label": "From (issuer)" },
+    "issuerId":  { "type": "ref",    "to": "profile", "label": "From (issuer)", "required": true },
+    "issuer":    { "type": "embed",  "to": "profile", "idField": "issuerId", "label": "From (issuer)" },
     "clientId":  { "type": "ref",    "to": "clients", "label": "Client", "required": true },
     "issueDate": { "type": "date",   "label": "Issued", "required": true },
     "dueDate":   { "type": "date",   "label": "Due" },
@@ -196,7 +207,8 @@ name: invoice
 description: A simple invoice ledger — create, list, edit, and remove invoices.
   Records live at `data/invoice/items/<id>.json`; the user views them at
   `/collections/invoice`. Each invoice references a client (`clientId` → the
-  `clients` collection) and embeds the user's `profile/me` as the issuer.
+  `clients` collection) and an issuer profile (`issuerId` → the `profile`
+  collection), which it embeds as the bill-from block.
   Subtotal / tax / total are host-computed — you don't write them.
 ---
 
@@ -207,9 +219,13 @@ description: A simple invoice ledger — create, list, edit, and remove invoices
   counter): `INV-2026-0001`. List `data/invoice/items/` first to find the highest
   number for the year, then increment; pick the next free number rather than
   overwriting.
-- `issuer` — **display-only** embed of `profile/me` (the bill-from block). You do
-  **not** write this — it carries no stored value. If the profile isn't set up,
-  the view shows a "set it up" prompt; point the user at `/collections/profile`.
+- `issuerId` — ref → `profile`, **required**. The bill-from identity. Write the
+  raw profile slug (the primary profile is `me`); the host renders it as a dropdown
+  picker. List `data/profile/items/` to find the right slug; no profile set up yet
+  → point the user at `/collections/profile`.
+- `issuer` — **display-only** embed of the profile named by `issuerId` (the
+  bill-from block). You do **not** write this — it carries no stored value; it
+  follows whatever `issuerId` points at.
 - `clientId` — ref → `clients`, **required**
 - `issueDate` — ISO date `YYYY-MM-DD`, **required** (default today)
 - `dueDate` — ISO date (optional)
@@ -232,8 +248,10 @@ or supply a literal slug. Never invent a clientId — it renders as a broken lin
 
 ## What to do
 **Create**: derive an `id`, build the record, Write `data/invoice/items/<id>.json`.
-Defaults: `status: "draft"`, `issueDate: <today>`. Set `currency` from context —
-don't silently default to USD. Don't write `subtotal` / `tax` / `total`.
+Defaults: `status: "draft"`, `issueDate: <today>`, `issuerId: "me"` (the primary
+profile) unless the user names a different issuer — then resolve it to a real
+`profile` slug. Set `currency` from context — don't silently default to USD. Don't
+write `subtotal` / `tax` / `total`.
 
 **Create from worklog hours** (common): when the user says "invoice Acme for the
 work I did this month":
@@ -304,11 +322,12 @@ and present it in the canvas with the `presentDocument` tool. Steps:
 
 1. **Resolve the recipient (Bill To).** Read `data/clients/items/<clientId>.json`
    for the client's `name`, `address`, `email`.
-2. **Resolve the issuer (From).** Read `data/profile/items/me.json` for
-   `companyName`, `taxRegistrationId`, `address`, `email`, `phone`,
-   `paymentDetails`. **If that file does not exist**, stop and tell the user their
-   business profile isn't set up — point them at `/collections/profile` — and do
-   not write a half-blank invoice.
+2. **Resolve the issuer (From).** Read `data/profile/items/<issuerId>.json` — the
+   invoice's own `issuerId` (fall back to `me` for a legacy invoice without one) —
+   for `companyName`, `taxRegistrationId`, `address`, `email`, `phone`,
+   `paymentDetails`. **If that file does not exist**, stop and tell the user that
+   issuer's business profile isn't set up — point them at `/collections/profile` —
+   and do not write a half-blank invoice.
 3. **Compute totals** from line items: `subtotal` = Σ(`quantity` × `rate`), `tax`
    = `subtotal` × `taxRate` (missing `taxRate` = 0), `total` = `subtotal` + `tax`.
    Format money with the invoice's `currency`.
@@ -332,8 +351,11 @@ The invoice record is in the `<record_data_json>` block above. You are the
 `accounting` role and own `manageAccounting`. Post the double-entry sale journal.
 
 ### 1. Resolve the book
-1. Read `data/profile/items/me.json`. If it has a non-empty `defaultBookId`, use
-   it as `bookId` and skip the rest of this step.
+1. Read `data/profile/items/<issuerId>.json` — the invoice's own `issuerId` (fall
+   back to `me` for a legacy invoice without one). If it has a non-empty
+   `defaultBookId`, use it as `bookId` and skip the rest of this step. If that
+   profile file doesn't exist, tell the user that issuer's profile isn't set up
+   (point them at `/collections/profile`) and stop.
 2. Otherwise call `manageAccounting` `getBooks`. One book → use it. Several →
    keep books whose currency/country fit the invoice; if one remains use it; else
    prefer the book whose name matches the issuer's `companyName`; only if still
@@ -378,11 +400,14 @@ The invoice record is in the `<record_data_json>` block above. You are the
 `accounting` role and own `manageAccounting`. The invoice is paid; post the
 cash-receipt journal that clears the receivable. Payment is always direct deposit
 to the issuer's bank account (the issuer's `paymentDetails` on
-`data/profile/items/me.json`), so the debit is the book's Cash / Checking account.
+`data/profile/items/<issuerId>.json`), so the debit is the book's Cash / Checking
+account.
 
 ### 1. Resolve the book
-Read `data/profile/items/me.json` for a non-empty `defaultBookId`; else `getBooks`
-and pick as in the sale flow. No book → tell the user to set one up and stop.
+Read `data/profile/items/<issuerId>.json` — the invoice's own `issuerId` (fall
+back to `me` for a legacy invoice) — for a non-empty `defaultBookId`; else
+`getBooks` and pick as in the sale flow. No book → tell the user to set one up and
+stop.
 
 ### 2. Resolve real account codes
 `getAccounts` — never invent: **Cash / Checking / Bank** (asset, the debit; if
@@ -418,7 +443,8 @@ The invoice record is in the `<record_data_json>` block above. You are the
 journals posted for it.
 
 ### 1. Resolve the book
-Read `data/profile/items/me.json` for a non-empty `defaultBookId`; else resolve
+Read `data/profile/items/<issuerId>.json` — the invoice's own `issuerId` (fall
+back to `me` for a legacy invoice) — for a non-empty `defaultBookId`; else resolve
 via `getBooks` (as in the sale flow). No book → nothing to void; say so and stop.
 
 ### 2. Resolve the Accounts Receivable code

package/assets/helps/collection-skills.md

@@ -168,10 +168,17 @@ Every field spec needs a `type` and a `label`. Extra keys by type:
   A `derived` field on the same record can also **dereference** a `ref` to read
   a numeric column off the record it points at — see the cross-collection
   formula syntax below.
-- **`embed`** — `to: "<target-slug>"`, `id: "<record-id>"`. Pulls a _fixed_
+- **`embed`** — `to: "<target-slug>"`, plus **exactly one** of `id` (a _fixed_
+  record id, same for every row) or `idField` (a _per-record_ target). Pulls a
   record from another collection into the read-only detail view (display-only,
-  **nothing is stored** on this record). Example: an invoice embedding the
-  user's own profile: `{ "type": "embed", "to": "profile", "id": "me" }`.
+  **nothing is stored** on this record). Fixed — every row embeds the same
+  singleton record (e.g. a one-record `settings` collection):
+  `{ "type": "embed", "to": "settings", "id": "app" }`.
+  Per-record — `idField` names a sibling field (typically a `ref`) holding the
+  target id, so each row embeds a different record; the host renders that
+  sibling as a dropdown picker in the editor and hides its own cell (the embed
+  owns it). E.g. a multi-issuer invoice: a `ref` field `issuerId → profile`
+  plus `{ "type": "embed", "to": "profile", "idField": "issuerId" }`.
 - **`table`** — `of: { <col>: <sub-field-spec>, ... }`. An array of rows. Each
   sub-field is a flat spec; sub-fields **cannot** be `table` or `derived`
   (no nested tables, no computed columns).
@@ -851,8 +858,9 @@ recipe when the user wants any of them, and copy the schema verbatim:
   - **`worklog`** — adds a `ref` (`clientId → clients`), a `date`, a `number`, a
     `boolean`. A companion data source.
 - **`config/helps/billing-invoice.md`** (Bundle B):
-  - **`profile`** — a `singleton` (one record, id `me`): the issuer identity.
-  - **`invoice`** — the full toolkit in one schema: an `embed` issuer
-    (`profile/me`), 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`).
+  - **`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
+    `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/error-recovery.md

@@ -0,0 +1,179 @@
+# Error recovery — when a tool call fails
+
+This is the lookup the agent reads BEFORE asking the user a clarifying
+question or giving up on a failing tool call. Each section is keyed by
+the error message you'd see in tool output, with the cause and the
+documented fix.
+
+Cite the section you used in your reply so the user can follow up
+(e.g. "Per `config/helps/error-recovery.md` § gh-auth / SSH …").
+
+If no section here matches, list the workspace's other help files
+(`ls config/helps/`) and Read whichever name best matches the failing
+area (`sandbox.md`, `github.md`, `collection-skills.md`, etc.) before
+falling back to asking the user.
+
+## gh / git / SSH errors inside the sandbox
+
+### Symptoms
+
+- `gh: To authenticate, please run gh auth login`
+- `git@github.com: Permission denied (publickey)`
+- `Could not resolve host: github.com`
+- `Permission denied (publickey)` on `git push` / `git clone <ssh-url>`
+- `fatal: Could not read from remote repository`
+
+### Cause
+
+The Claude Code agent runs inside a credential-free Docker sandbox by
+default. The host's SSH agent and `gh` config aren't exposed unless the
+user opts them in.
+
+### Fix
+
+Tell the user to enable the two opt-in mounts on the next agent spawn
+(see also `config/helps/sandbox.md` for the full contract):
+
+```bash
+# Forward the host's SSH agent into the container.
+# Private keys stay on the host; only the signing oracle is exposed.
+SANDBOX_FORWARD_SSH_AGENT=1 \
+# Mount allowlisted config files/dirs read-only — including ~/.config/gh.
+SANDBOX_MOUNT_CONFIGS=gh \
+  yarn dev   # or: npx mulmoclaude
+```
+
+Equivalent CLI flags: `--sandbox-forward-ssh-agent --sandbox-mount-configs=gh`.
+
+After restart, inside the agent's first tool turn verify:
+
+```bash
+ssh-add -l                      # should list at least one key
+gh auth status                  # should report logged in
+```
+
+If `ssh-add -l` fails, the host's SSH agent isn't running — tell the
+user to start it (`ssh-add ~/.ssh/id_*` on macOS / Linux). If
+`gh auth status` fails, the user needs to run `gh auth login` on the
+host first (host config is mounted read-only into the sandbox).
+
+### When neither helps
+
+The sandbox itself can be turned off for the session with
+`DISABLE_SANDBOX=1 yarn dev` / `--disable-sandbox`. The agent then
+inherits the user's full environment. Recommend this only when the
+credential mount approach didn't resolve the issue — the sandbox is
+the safer default.
+
+## Collection registry — Contribute / Discover failures
+
+### Symptoms
+
+- Contribute flow: `gh pr create` fails, `git push` rejected, or the
+  registry clone fails inside `github/`.
+- Discover tab loads no entries, or one registry's cards are missing.
+
+### Cause + fix
+
+For the Contribute side, the underlying issue is almost always
+sandbox credentials — see the gh/git/SSH section above before anything
+else.
+
+For Discover, multi-registry config lives at
+`config/collections-registries.json`. A malformed entry there is
+silently dropped; check the server log for
+`[collections-registry] registry config entry rejected`. The file
+format and validation rules are documented in
+`config/helps/collection-skills.md` (Contribute bundle layout) and the
+shipped registry repo's README. Common rejections:
+
+- URL not HTTPS, or includes embedded credentials.
+- `rawBaseUrl` contains a `?` query or `#` fragment.
+- `name` reuses the reserved value `official`.
+- `name` doesn't match `[A-Za-z0-9][A-Za-z0-9_-]{0,31}`.
+
+## Marp slide PDF — empty / image / font issues
+
+### Symptoms
+
+- PDF export of a Marp deck produces tofu (□□□) for Japanese / CJK text.
+- Inline images in a slide are missing from the PDF.
+- A custom Marp `theme: <name>` is ignored.
+
+### Fix
+
+CJK fonts (Hiragino on macOS, Yu Gothic / Meiryo on Windows, Noto Sans
+CJK on Linux) need to exist on the **host running the server**, not
+in the sandbox (PDF render happens server-side via puppeteer). On
+Linux: `sudo apt-get install fonts-noto-cjk`. Docker host:
+`apt-get install -y fonts-noto-cjk` in the production Dockerfile.
+
+Inline images missing from the PDF: paths must be relative to the
+`.md` file, NOT absolute or workspace-rooted. See the "Image
+references in markdown / HTML" section of the system prompt for the
+rule.
+
+Custom theme ignored: themes live in `~/mulmoclaude/config/marp-themes/<name>.css`.
+The filename (sans `.css`) is the theme slug; only `[A-Za-z0-9_-]` is
+allowed. Reload the browser tab after adding a theme — preview caches
+per session.
+
+## Build / yarn workspace ordering
+
+### Symptoms
+
+- `yarn dev` fails on a fresh clone with
+  `Cannot find module '@mulmoclaude/<x>-plugin/server'` or similar.
+- A workspace package's `dist/` is missing on first run.
+
+### Fix
+
+```bash
+yarn build:packages   # builds every shared workspace package in tier order
+yarn dev              # then the dev server picks them up
+```
+
+If a specific package keeps failing, build just it:
+`yarn workspace @mulmoclaude/<name> run build`. The build pipeline
+runs plugins before services so cross-package imports resolve cold.
+
+## Plugin runtime — install / drift
+
+### Symptoms
+
+- A runtime plugin shown in `/skills` doesn't load, or its routes 404.
+- After upgrading the plugin host, a previously-installed plugin
+  reports a peer-dependency mismatch (e.g. `gui-chat-protocol`
+  version skew).
+
+### Fix
+
+Runtime plugins are installed via tgz under `~/mulmoclaude/plugins/`
+with a ledger at `plugins/plugins.json`. Reinstall the failing
+plugin via the `/skills` UI to refresh both the tgz and the ledger.
+A version skew on a peer dep means the plugin was built against an
+older host — bump the plugin via the Discover tab's update flow.
+
+## Fallback
+
+If none of the above matches the failing tool output:
+
+1. `ls config/helps/` to see every shipped help file.
+2. Pick the file whose name most closely matches the failing area
+   (`sandbox.md`, `github.md`, `feeds.md`, `presentation-deck.md`,
+   `mulmoscript.md`, `spreadsheet.md`, etc.) and Read it.
+3. If you find a fix there, apply it and cite the help by path in
+   your reply.
+4. If nothing fits, surface the raw error to the user and say
+   "no documented fix found in `config/helps/` — could you share more
+   context so we can resolve this together?" rather than silently
+   guessing or retrying the same command.
+
+## When you discover a new common error
+
+If you resolve a new class of error that other users are likely to
+hit, suggest to the user that we extend this file. Don't edit it
+yourself — additions to `config/helps/error-recovery.md` are managed
+by the project maintainers so the canonical copy in
+`packages/core/assets/helps/error-recovery.md` and the installed copy
+stay in sync.

package/assets/helps/index.md

@@ -63,6 +63,7 @@ See [Wiki](config/helps/wiki.md) for details on how it works.
 - [Spreadsheet](config/helps/spreadsheet.md) — cell format, formulas, date handling, and format codes for the presentSpreadsheet plugin
 - [presentHtml](config/helps/presenthtml.md) — self-contained HTML rules and the three-`../` relative-path convention used by the presentHtml plugin to keep generated files portable under `file://`
 - [Sandbox](config/helps/sandbox.md) — how the Docker sandbox isolates the agent, what it can access, and how to disable it
+- [Error recovery](config/helps/error-recovery.md) — the lookup the agent reads on tool failures (gh/git/SSH inside the sandbox, Marp PDF, registry import, build/workspace, plugin runtime) before asking the user
 - [Telegram Bridge](config/helps/telegram.md) — how to talk to MulmoClaude from the Telegram app: creating a bot, starting the bridge, allowlisting chat IDs, commands, and troubleshooting
 - [Feeds](config/helps/feeds.md) — register a self-refreshing data feed (RSS/Atom/JSON) by authoring `feeds/<slug>/schema.json`: schema shape, the `ingest` block, raw-item field mapping, and `maxItems` retention
 - [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

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

@@ -220,9 +220,20 @@ export interface CollectionFieldSpec {
      *  record to pull from the `to` collection (e.g. `me` for the
      *  singleton mc-profile). Nothing is stored on this record — the
      *  embed is a display-only directive resolved at render time, so
-     *  it never appears in the list table or the edit form. Required
-     *  when type is `embed`; ignored on every other type. */
+     *  it never appears in the list table or the edit form. Supply
+     *  either this (a fixed target, same for every record) or
+     *  `idField` (a per-record target) — exactly one. Ignored on every
+     *  other type. */
     id?: string;
+    /** When `type === "embed"`: the name of a sibling top-level field
+     *  whose value names the target record's primary key — letting the
+     *  embed point at a *different* record per row (e.g. an invoice's
+     *  `issuerId` ref selects which `profile` to embed as the
+     *  bill-from block). The renderer reads `record[idField]` at render
+     *  time; an absent/empty value resolves to "no record" (the same
+     *  fail-soft as a missing fixed `id`). Mutually exclusive with `id`
+     *  — an embed must declare exactly one. Ignored on every other type. */
+    idField?: string;
     /** When `type === "money"` (or `type === "derived"` with
      *  `display: "money"`): a literal ISO 4217 currency code passed to
      *  `Intl.NumberFormat` for display — fixed for every record. The
@@ -401,3 +412,9 @@ export interface CollectionDetail extends CollectionSummary {
     schema: CollectionSchema;
 }
 export type CollectionItem = Record<string, unknown>;
+/** Resolve an `embed` field's target record id: the fixed `id`, or the value
+ *  of the sibling `idField` on this record (empty string when neither applies
+ *  — the caller renders that as "no record"). Pure + isomorphic so the server
+ *  projection (`derive.ts`) and the client preview (`useCollectionRendering`)
+ *  resolve embeds identically. */
+export declare function embedTargetId(field: CollectionFieldSpec, record: CollectionItem | null): string;

package/dist/collection/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_deriveAll = require("../deriveAll-VRWrs3SF.cjs");
+const require_deriveAll = require("../deriveAll-Cb9rWjan.cjs");
 //#region src/collection/core/presentCollection.ts
 var TOOL_NAME = "presentCollection";
 var TOOL_DEFINITION = {
@@ -760,6 +760,7 @@ exports.daySlice = daySlice;
 exports.defangForPrompt = defangForPrompt;
 exports.deriveAll = require_deriveAll.deriveAll;
 exports.draftToRecord = draftToRecord;
+exports.embedTargetId = require_deriveAll.embedTargetId;
 exports.emptyRow = emptyRow;
 exports.enumColorClasses = enumColorClasses;
 exports.enumSortValue = enumSortValue;

package/dist/collection/index.js

@@ -1,4 +1,4 @@
-import { a as FEED_SCHEDULES, i as AGENT_INGEST_KIND, n as resolveRowRefs, o as INGEST_KINDS, r as evaluateDerived, s as isFieldDrivenEvery, t as deriveAll } from "../deriveAll-vzIhhKBK.js";
+import { a as FEED_SCHEDULES, c as isFieldDrivenEvery, i as AGENT_INGEST_KIND, n as resolveRowRefs, o as INGEST_KINDS, r as evaluateDerived, s as embedTargetId, t as deriveAll } from "../deriveAll-D3wFH4Tw.js";
 //#region src/collection/core/presentCollection.ts
 var TOOL_NAME = "presentCollection";
 var TOOL_DEFINITION = {
@@ -735,6 +735,6 @@ function defangForPrompt(value) {
 	return value.replace(/[<>]/g, "").replace(/`/g, "'").replace(/\$\{/g, "$ {").replace(/\s+/g, " ").slice(0, DEFANG_MAX_LEN);
 }
 //#endregion
-export { AGENT_INGEST_KIND, ENUM_ALERT, ENUM_NEUTRAL, ENUM_NUDGE, FEED_SCHEDULES, INGEST_KINDS, MINUTES_PER_DAY, TOOL_DEFINITION, TOOL_NAME, actionVisible, assignLanes, boolSortValue, bucketRecords, buildMonthGrid, buildUpdatedRecord, coerceInlineValue, compareSortValues, compareYmd, dateOf, dateSortValue, daySlice, defangForPrompt, deriveAll, draftToRecord, emptyRow, enumColorClasses, enumSortValue, enumValueIndex, errorMessage, evaluateDerived, executePresentCollection, fieldVisible, firstMissingRequiredField, isFieldDrivenEvery, isSortableField, itemIdOf, itemLabelOf, labelFieldFor, monthAnchorDate, nextSortDirection, numericSortValue, parseIsoDate, parseIsoDateTime, parseTimeRange, recordSpan, resolveEnumColor, resolveRowRefs, rowFromItem, shortHexId, sortItems, spanCoversDay, stringSortValue, whenMatches, ymdKey };
+export { AGENT_INGEST_KIND, ENUM_ALERT, ENUM_NEUTRAL, ENUM_NUDGE, FEED_SCHEDULES, INGEST_KINDS, MINUTES_PER_DAY, TOOL_DEFINITION, TOOL_NAME, actionVisible, assignLanes, boolSortValue, bucketRecords, buildMonthGrid, buildUpdatedRecord, coerceInlineValue, compareSortValues, compareYmd, dateOf, dateSortValue, daySlice, defangForPrompt, deriveAll, draftToRecord, embedTargetId, emptyRow, enumColorClasses, enumSortValue, enumValueIndex, errorMessage, evaluateDerived, executePresentCollection, fieldVisible, firstMissingRequiredField, isFieldDrivenEvery, isSortableField, itemIdOf, itemLabelOf, labelFieldFor, monthAnchorDate, nextSortDirection, numericSortValue, parseIsoDate, parseIsoDateTime, parseTimeRange, recordSpan, resolveEnumColor, resolveRowRefs, rowFromItem, shortHexId, sortItems, spanCoversDay, stringSortValue, whenMatches, ymdKey };
 
 //# sourceMappingURL=index.js.map

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

@@ -32,6 +32,7 @@ export declare const CollectionSchemaZ: z.ZodObject<{
         required: z.ZodOptional<z.ZodBoolean>;
         to: z.ZodOptional<z.ZodString>;
         id: z.ZodOptional<z.ZodString>;
+        idField: z.ZodOptional<z.ZodString>;
         currency: z.ZodOptional<z.ZodString>;
         currencyField: z.ZodOptional<z.ZodString>;
         values: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/collection/server/index.cjs

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

package/dist/collection/server/index.js

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

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-DAyIQ5rT.cjs");
+const require_server = require("../server-BjXvqGrE.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 { A as readItem, D as listItems, _ as loadCollection, c as isTriggerDue, g as discoverCollections, l as maybeSpawnSuccessor } from "../server-D2QZuMS2.js";
+import { A as readItem, D as listItems, _ as loadCollection, c as isTriggerDue, g as discoverCollections, l as maybeSpawnSuccessor } from "../server-CRlmOBVQ.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";

package/dist/{deriveAll-VRWrs3SF.cjs → deriveAll-Cb9rWjan.cjs}

@@ -27,6 +27,16 @@ var FEED_SCHEDULES = [
 function isFieldDrivenEvery(every) {
 	return "fromField" in every;
 }
+/** Resolve an `embed` field's target record id: the fixed `id`, or the value
+*  of the sibling `idField` on this record (empty string when neither applies
+*  — the caller renders that as "no record"). Pure + isomorphic so the server
+*  projection (`derive.ts`) and the client preview (`useCollectionRendering`)
+*  resolve embeds identically. */
+function embedTargetId(field, record) {
+	if (field.id) return field.id;
+	if (field.idField && record) return String(record[field.idField] ?? "");
+	return "";
+}
 //#endregion
 //#region src/collection/core/derivedFormula.ts
 function evaluateDerived(formula, ctx) {
@@ -391,6 +401,12 @@ Object.defineProperty(exports, "deriveAll", {
 		return deriveAll;
 	}
 });
+Object.defineProperty(exports, "embedTargetId", {
+	enumerable: true,
+	get: function() {
+		return embedTargetId;
+	}
+});
 Object.defineProperty(exports, "evaluateDerived", {
 	enumerable: true,
 	get: function() {
@@ -410,4 +426,4 @@ Object.defineProperty(exports, "resolveRowRefs", {
 	}
 });
 
-//# sourceMappingURL=deriveAll-VRWrs3SF.cjs.map
+//# sourceMappingURL=deriveAll-Cb9rWjan.cjs.map