@akanjs/cli 3.0.0-alpha.2 → 3.0.0-alpha.3

package/.build-stamp

@@ -1 +1 @@
-5ce0c5971a50c46a41ba69a3a1125bb984dfbb8bc836bb7a817970eca45b7c59
+5f4cb4962f5027c269281e372337f2349defcfca97ac7c862b17e452e9749c5d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.3",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.2",
+    "akanjs": "3.0.0-alpha.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/templates/workspaceRoot/AGENTS.md.template

@@ -881,6 +881,10 @@ A short list of things the type system does not always catch:
   fires no hooks and therefore no cascade.
 - **Removal is always soft, and `delete` is reserved.** `remove(id)`, the facade's `removeMany(query)`, and the
   store's `removeManyByQuery` all stamp `removedAt`; the framework has no hard delete for a model table.
+- **The model facade spells out `Many`/`One` on its writes** — `updateOne`, `updateMany`, `removeOne`, `removeMany`
+  — because a bare `update`/`remove` would read like the document-path `update(id)` / `doc.remove()` while hitting
+  every match. Reads keep the short `find`/`findOne` pair, and counting is `count(query)` (`countDocuments` is
+  `@deprecated`).
 - **`q.search()` is a filter node, not a slice requirement.** Prefer
   `bySearch: filter().arg("text", String).query((text, q) => q.search(text, { prefix: true }))` — the generated
   `listBySearch` / `countBySearch` / `queryBySearch` / `insightBySearch` come for free. Only add a search slice when
@@ -958,8 +962,12 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `pick[Query](args)`, `pickId[Query](args)` | Find one (throw if not found) |
 | `exists[Query](args)`, `count[Query](args)` | Existence check and count |
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
+| `remove[Query](args)`, `removeOne[Query](args)` | Query-level soft remove — all matches, or the newest one (`createdAt` desc, not caller-chosen) |
+| `update[Query](args).set(patch)`, `updateOne[Query](args).set(patch)` | Query-level update — the patch lands on a terminal `.set()`, because a filter's trailing args may be optional |
 
-**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 14 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+
+**The four query-level writes fire no hooks**, so no `_pre`/`_postRemove` and no cascade run — same as `updateManyByQuery`. Reach for them when the model carries no removal side effect; otherwise remove documents one at a time. A filter keyed after its own model (filter `chat` on model `chat`) is rejected at boot, because `removeChat`/`updateChat` would otherwise shadow the generated single-document CRUD.
 
 ## Generated Context