@mulmoclaude/core 0.13.0 → 0.14.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>/`
@@ -761,10 +761,25 @@ 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).
 - **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 +789,24 @@ 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` field — both 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 +815,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/gemini.md

@@ -36,19 +36,21 @@ The Gemini API has a **free tier that is sufficient for personal use**. Higher-v
 1. Open [Google AI Studio → API keys](https://aistudio.google.com/apikey) and sign in with a Google account.
 2. Click **Create API key**. If prompted, select or create a Google Cloud project (any project will do).
 3. Copy the key — it starts with `AIza…`.
-4. Open the project's `.env` file in the repository root (copy `.env.example` first if it doesn't exist yet) and add the line:
+4. Create (or open) a `.env` file **in the directory you launch MulmoClaude from** — i.e. the directory where you run `npx mulmoclaude` (in a cloned repo, that's the repo root). Add the line:
 
-   ```
+   ```dotenv
    GEMINI_API_KEY=AIza…your-key…
    ```
 
+   The key stays in your launch directory, not in the `~/mulmoclaude` workspace (which is managed by the assistant). You can also just `export GEMINI_API_KEY=…` in your shell before launching — an exported value takes precedence over the `.env` file.
+
 5. Restart MulmoClaude so the new environment variable is picked up.
 
 ## Verifying It's Active
 
 The quickest check: switch to the **Artist** role and ask for _"an image of a red panda"_. If a real image appears in the canvas (instead of an italic text marker or a disabled-role hint), the key is wired up correctly.
 
-You can also inspect the server log on startup: messages like `GEMINI_API_KEY not set — image placeholders will render as text markers` indicate the key is missing or misread.
+You can also inspect the server log on startup: a `GEMINI_API_KEY not set — image / audio / video generation is unavailable` warning means the key was not found (missing, misread, or placed outside your launch directory).
 
 ## Security
 

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.