@mulmoclaude/core 0.13.1 → 0.15.0

package/assets/helps/billing-clients-worklog.md

@@ -103,18 +103,19 @@ Don't push for fields the user hasn't given you — leave optional fields out of
 the JSON entirely.
 
 ## What to do
-**Add**: derive an `id`, build the record, Write `data/clients/items/<id>.json`.
-List the directory first and pick a fresh slug if the file already exists — don't
-silently overwrite.
+**Add**: derive an `id`, build the record, write via `manageCollection`
+`putItems` with `mode: "create"` — an id collision comes back as a `rejected`
+row instead of silently overwriting; pick a fresh slug and retry.
 
-**List / look up**: read `data/clients/items/`, answer from those files. Don't
+**List / look up**: `manageCollection` `getItems`, answer from the rows. Don't
 recite the whole table in chat — the user sees it at `/collections/clients`. A
 one-line confirmation ("Added Acme Corp.") is enough.
 
-**Update**: Read → merge changes → Write back. Preserve fields you weren't asked
-to change.
+**Update**: `putItems` with `mode: "merge"` and a partial row
+(`{ id, <changed fields> }`) — the default upsert replaces the whole record.
 
-**Delete**: confirm once if the request is ambiguous, then remove the file.
+**Delete**: confirm once if the request is ambiguous, then remove the file
+(`manageCollection` has no delete).
 
 ## Linking to a client in chat
 Link to the collection view, not the raw JSON path:
@@ -179,18 +180,20 @@ description: A simple timesheet — log billable / non-billable hours per client
 ## clientId resolution
 `clientId` is a `ref` to the `clients` collection — write the raw client slug.
 When the user says "log 2 hours for Acme":
-- List `data/clients/items/` and find the slug whose `name` matches "Acme"
-  (case-insensitive substring is fine).
+- `manageCollection` `getItems` on `clients` (`fields: ["id", "name"]`) and
+  find the slug whose `name` matches "Acme" (case-insensitive substring is
+  fine).
 - If no match: ask whether to create the client first (via the `clients` skill)
   or use a literal slug they supply. Never invent a clientId that doesn't exist —
   it renders as a broken link.
 
 ## What to do
 **Log hours**: derive `id`, default `billable: true`, default `date` to today if
-unspecified, Write the JSON. (This skill tracks total hours per day per client —
-not start/end times.)
+unspecified, write via `manageCollection` `putItems` (`mode: "create"`; fix any
+`rejected` row from its `problem` text and retry). (This skill tracks total
+hours per day per client — not start/end times.)
 
-**List / summarize**: read `data/worklog/items/`, answer from the files. Don't
+**List / summarize**: `manageCollection` `getItems`, answer from the rows. Don't
 recite the table — point at `/collections/worklog`. For aggregates ("how many
 hours did I bill Acme last month?") group by clientId + date range and answer in
 one line.

package/assets/helps/collection-skills.md

@@ -31,7 +31,7 @@ data/skills/<slug>/            ← YOU write here (Write / Edit)
   SKILL.md  ·  schema.json  ·  templates/*.md
 
 data/<name>/items/             ← the records (separate from the skill dir)
-  <id>.json         ← one record per file (you write; host reads + renders)
+  <id>.json         ← one record per file (write via manageCollection putItems)
 ```
 
 - **Author under `data/skills/<slug>/`, NEVER `.claude/skills/<slug>/`
@@ -148,7 +148,7 @@ skipped, never crashes the host):
 
 `string` · `text` (multi-line) · `email` · `number` · `date` (`YYYY-MM-DD`) ·
 `datetime` (`YYYY-MM-DDTHH:MM`) · `boolean` · `markdown` · `money` · `enum` ·
-`ref` · `embed` · `table` · `derived` · `image` · `file` · `toggle`
+`ref` · `embed` · `backlinks` · `table` · `derived` · `image` · `file` · `toggle`
 
 Every field spec needs a `type` and a `label`. Extra keys by type:
 
@@ -179,9 +179,23 @@ Every field spec needs a `type` and a `label`. Extra keys by type:
   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" }`.
+- **`backlinks`** — `from: "<source-slug>"`, `via: "<ref-field-in-source>"`,
+  `display: ["<source-col>", ...]`, optional `filter: { "field": ..., "in": [...] }`.
+  The **reverse** side of a `ref`: a read-only sub-table (detail view only) of
+  the records in `from` whose `via` ref points at this record — each row links
+  to that record. **Nothing is stored** on this record (like `derived`/`embed`);
+  you never write it, and the rows update whenever the source records change.
+  `display` names the source columns to show — a derived source column works
+  when its formula is self-contained (e.g. an invoice `total` summing its own
+  line items), but one that derefs yet another collection renders em-dash;
+  `filter` narrows rows by a source field's value, same shape as `when`. E.g. a
+  client's open invoices:
+  `{ "type": "backlinks", "label": "Invoices", "from": "invoice", "via": "clientId", "display": ["issueDate", "total", "status"], "filter": { "field": "status", "in": ["draft", "sent"] } }`.
+  Resolution is fail-soft: an unknown `from` / `via` / `display` column just
+  renders an empty sub-table — no error, so author the `ref` side first.
 - **`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).
+  sub-field is a flat spec; sub-fields **cannot** be `table`, `derived`, or
+  `backlinks` (no nested tables, no computed columns).
 - **`derived`** — `formula: "<expr>"`, optional `display` (`number` default, or
   `money` / `string` / `date`) and `currency`. **Read-only, host-computed** —
   you NEVER write derived values into the JSON; the host recomputes them on
@@ -761,10 +775,32 @@ single source of truth and the "done" checkbox is a `toggle` field projecting it
 
 ## Records — one JSON object per file
 
-- Write each record to `<dataPath>/<id>.json` via the **Write** tool; the `id`
-  field's value is the filename (no extension).
+Each record is a plain file at `<dataPath>/<id>.json` (the `id` field's value is
+the filename, no extension) — that is the storage model. But you read and write
+records through **`manageCollection`**, not raw file I/O:
+
+- **Create / update — `putItems`.** Every row is validated against the schema
+  BEFORE the write (required fields, enum membership, primaryKey = record id)
+  and the result reports `{ written, rejected }` — fix each rejected row from
+  its `problem` text and retry just those rows. Use `mode: "create"` when
+  adding, so an id collision is rejected instead of silently overwritten, and
+  `mode: "merge"` with a partial row (`{ id, <changed fields> }`) when
+  updating — the default upsert replaces the WHOLE record and would erase
+  every optional field the row omits.
+- **Read / list — `getItems`.** The only way to see host-computed `derived` /
+  `toggle` / `embed` values (the stored JSON never contains them). Pass `ids`
+  / `fields` on large collections to keep the result small — e.g.
+  `fields: ["id"]` to check for an id collision before an add.
+- **Delete** — remove the record file (`manageCollection` has no delete).
+- **Cross-collection questions — `getOntology`.** Returns every collection in
+  the workspace with its `primaryKey`, effective `displayField`, record count,
+  and outbound `ref` / `embed` relations (field → target slug, including refs
+  inside `table` columns as `lines.clientId`). When a question spans
+  collections ("which clients have unpaid invoices AND unlogged hours?"),
+  call it first to see which collections exist and how they join, then
+  `getItems` only the ones involved — instead of reading every schema.json.
 - **Id charset** (enforced by `safeRecordId` in
-  `packages/plugins/collection-plugin/src/server/paths.ts` — the single source of
+  `packages/core/src/collection/server/paths.ts` — the single source of
   truth; `manageCollection` rejects ids that fail it): start and end with a
   letter or digit; inside, also `-`, `_`, and `.` are allowed (so natural keys
   like a Slack ts `1718900000.123456` or a SemVer `1.2.3` work). **No** path
@@ -774,6 +810,25 @@ single source of truth and the "done" checkbox is a `toggle` field projecting it
   enforces this on every targeted read/write, so an id that only _looks_ fine in
   a full `getItems` listing but violates the rule can't be updated or deleted by
   id — fix the id, don't work around it with raw file I/O.
+- **Never write `derived` fields**, and never write an `embed` or `backlinks`
+  field — all are display-only / host-computed (`putItems` rejects rows that
+  carry them).
+- Leave optional fields out of the row entirely rather than writing empty
+  strings.
+- For a `ref` field, write the raw target slug, and make sure that record
+  actually exists in the target collection — an invalid slug renders as a broken
+  link. The host enforces structure and safety; **you own semantic correctness**
+  (valid refs, sane values).
+
+### Raw file I/O on records — the escape hatch
+
+Read / Write / Edit on the record files stays available (files are the source
+of truth), but it skips `putItems`' pre-write validation — a mistake lands on
+disk instead of coming back as a `rejected` row. Reach for it only when the
+tool can't do the job: bulk file surgery, or repairing a file so malformed
+that `manageCollection` can't address it. If you do write record files
+directly:
+
 - **The file MUST be valid JSON.** A malformed record is **silently skipped** at
   read time (logged server-side, but invisible in the UI) — so one bad file out
   of fifteen looks like "fourteen records vanished." The #1 cause is an
@@ -782,22 +837,12 @@ single source of truth and the "done" checkbox is a `toggle` field projecting it
   (`text`, `markdown`, a long `objective`), either escape every inner ASCII quote
   as `\"`, or — better — use the language's own quotation marks (`「」`/`『』` for
   Japanese, `‘ ’`/`“ ”` or `'…'` for English) so no escaping is needed.
-  `presentCollection` re-validates the records and reports any unreadable /
+- `presentCollection` re-validates the records and reports any unreadable /
   malformed / schema-violating files back to you (a `⚠️` in its result) — so
-  always follow a batch of writes with a `presentCollection` call and **act on
-  any ⚠️ it returns** (Read → fix → Write), rather than assuming every record
-  landed.
-- **List the directory first** and pick a fresh id rather than silently
-  overwriting. Update = Read, merge, Write back (preserve fields you weren't
-  asked to change). Delete = remove the file.
-- **Never write `derived` fields**, and never write an `embed` field — both are
-  display-only / host-computed.
-- Leave optional fields out of the JSON entirely rather than writing empty
-  strings.
-- For a `ref` field, write the raw target slug, and make sure that record
-  actually exists in the target collection — an invalid slug renders as a broken
-  link. The host enforces structure and safety; **you own semantic correctness**
-  (valid refs, sane values).
+  always follow a batch of direct writes with a `presentCollection` call and
+  **act on any ⚠️ it returns**, rather than assuming every record landed.
+  (This safety net applies after `putItems` batches too, but direct writes are
+  where it earns its keep.)
 
 ## End-to-end: creating a new collection skill
 

package/assets/helps/todo-collection.md

@@ -80,11 +80,16 @@ description: The user's personal todo list. Use whenever they add, list, edit,
 - Do NOT write a `done` field — it's a projection of `status`.
 
 ## What to do
-- **Add**: derive an id, default `status: "todo"`, Write the JSON.
-- **List**: read `data/todos/items/`, answer from the files; point the user at
-  `/collections/todos` rather than reciting the table.
-- **Mark done**: Read → set `status: "done"` → Write.
-- **Edit / Delete**: Read → mutate / remove the file (preserve untouched fields).
+- **Add**: derive an id, default `status: "todo"`, write via `manageCollection`
+  `putItems` (`mode: "create"`; a rejected row comes back with a `problem` to
+  fix and retry).
+- **List**: `manageCollection` `getItems` (the only way to see the computed
+  `done` toggle); point the user at `/collections/todos` rather than reciting
+  the table.
+- **Mark done**: `putItems` with `mode: "merge"` and `{ id, status: "done" }`.
+- **Edit**: `putItems` `mode: "merge"` with a partial row — the default upsert
+  replaces the whole record. **Delete**: remove the file (`manageCollection`
+  has no delete).
 - After a change, call `presentCollection` with slug `todos` (and the id) to show
   it inline.
 ```
@@ -131,8 +136,9 @@ single array) with the columns in the sibling `columns.json`. Convert them:
    the legacy list had.
 3. **Fold `completed` into `status`.** A legacy `completed: true` item belongs in
    the done column; don't carry a separate boolean.
-4. **One file per item.** Split the array into `data/todos/items/<id>.json`,
-   preserving each legacy `id` verbatim.
+4. **One record per item.** Split the array into one `putItems` row per item
+   (stored as `data/todos/items/<id>.json`), preserving each legacy `id`
+   verbatim.
 5. **Convert `createdAt`.** The legacy value is Unix milliseconds — convert it to
    a `YYYY-MM-DD` `date` field. Carry `priority`, `dueDate`, `note` straight
    across.