@owlmeans/client-planning 0.1.18-rc.17 → 0.1.18-rc.19

package/README.md

@@ -9,7 +9,7 @@ planning service runs in-process.
 ## Installation
 
 ```bash
-bun add @owlmeans/client-planning@^0.1.18-rc.17
+bun add @owlmeans/client-planning@^0.1.18-rc.19
 ```
 
 ## Concepts
@@ -119,7 +119,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.45
+npx @owlmeans/agent-skills@^0.1.18-rc.46
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client-planning",
-  "version": "0.1.18-rc.17",
-  "generatedAt": "2026-10-02T19:07:09.545Z",
+  "version": "0.1.18-rc.19",
+  "generatedAt": "2026-10-03T15:33:53.022Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client-planning/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/client-planning
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-planning": "^0.1.18-rc.17"` in `dependencies`
+**Install:** `"@owlmeans/client-planning": "^0.1.18-rc.19"` in `dependencies`
 
 The client half of OwlMeans planning. It answers the `PlanningFacade` interface of
 `@owlmeans/planning` over the protocol tree a server mounted with `@owlmeans/server-planning`, keeps
@@ -60,8 +60,8 @@ appendPlanningStores(context)        // a browser mirror; a Node client usually
 - `bind: false` when the host already bound the tree.
 - The service answers under `PLANNING_SERVICE`, the alias the server's service uses, so
   `context.planning().for(scope)` is the same call in a handler and in a screen. The scope is
-  **advisory**: the server takes the entity and the actor from the credential. The execution's own
-  `actor` is never sent.
+  **advisory** — it changes nothing the server decides: the server takes the entity and the actor
+  from the credential. The execution's own `actor` is never sent.
 - A client runs no middleware and folds nothing: `store()`, `committed()` and a plugin carrying
   `before`/`after`/`store`/`mintCode` answer `PlanningUnsupported`. `use()` accepts a schemas-only
   plugin, layered over the server's bundle.
@@ -87,16 +87,33 @@ whole cache — an organization-wide write reaches every project's layer — and
 `model(card)` of a card resolves its type in its project's layer (a project's own id, a card's
 `parent`); a specification's type is always code's. A tree without `definitions` has none of this.
 
+## Mounting in a target
+
+A generated target's web reads the STOCK tree its api serves (`server-planning` → Mounting in a
+target) — the one `makePlanningProtocols({ base: { alias: 'api:planning' }, guards: DEFAULT_GUARD,
+definitions: true })` declared in the target's common package.
+
+- `appendPlanningClient(context, { protocols, bind: false })` — the target binds its common tree
+  itself — plus `appendPlanningStores(context)`. No `socket`: the target api serves no commit
+  socket, so `commits.wait` long-polls.
+- Screens read the mirror with `useStoreList` / `useStoreModel` (`@owlmeans/client`), never a
+  fetched array kept in component state.
+- Lists reach the store through `syncCards` or `makePlanningFeed` (with `refresh`), NEVER
+  `replace()` — the one card store holds every kind.
+- Every write is `facade.execute(...)` with a `key` (a retried click or a double submit answers
+  the first receipt) and `{ wait: true }` where the screen shows the result.
+- Never call a route with an empty id; a picker offers no archived parent (`intrinsic: closed`).
+
 ## Reading
 
 ```typescript
 const planning = context.planning().for()
 
-const stories = await planning.cards.list({ parent: projectId, type: STORY, sort: ['order'], size: 0 })
-const board = await planning.cards.summary([projectId])
-const brief = await planning.specifications.current(projectId, 'specification')
-const story = await planning.model(storyId)
-story.available().map(rule => rule.name)
+const tools = await planning.cards.list({ parent: shedId, type: 'shed:tool', sort: ['order'], size: 0 })
+const board = await planning.cards.summary([shedId])
+const rules = await planning.specifications.current(shedId, 'house-rules')
+const drill = await planning.model(drillId)
+drill.available().map(rule => rule.name)
 ```
 
 - The facade takes the rich `WorkcardQuery`; it encodes the scalar wire shape itself
@@ -136,8 +153,8 @@ The fold rules, shared by `syncCards`, `applyCards`, `applyCommitEvent` and `com
 
 ```typescript
 const feed = makePlanningFeed(context, {
-  query: { parent: projectId, type: STORY },
-  filter: { project: projectId },
+  query: { parent: shedId, type: 'shed:tool' },
+  filter: { project: shedId },
   refresh: 15_000,
   onChange: state => setState(state),
 })
@@ -197,18 +214,14 @@ A Node client passes no opener and relies on the long poll.
 (run by `execute` whenever stores are registered) raises the stored card's `head` to the new
 transition's `seq`, so `model.pending()` is true before any frame arrives; the commit's fold brings
 `seq` up to it. The mirror only ever grows `head`, so a list fetched before the append does not
-clear the marker. A model's writes default `expectSeq` to `record.head ?? record.seq`; a stale model
-gets `WorkcardConflict` — reload and retry.
+clear the marker. A model's `expectSeq` default and its `WorkcardConflict` are `planning` → Models.
 
 ## Gotchas
 
 - Mount a feed once per screen; read the store everywhere else.
-- Do not `replace()` the card store — it holds every kind. Use `syncCards` with a `where`.
 - A refusal crosses the hop as its class (`IllegalTransition`, `WorkcardConflict`,
   `FieldsInvalid`, a plugin's own class) — branch on `instanceof`, never on message text.
 - `CommitTimeout` is not a failure of the transition; re-wait or re-read the card.
-- The scope passed to `for()` changes nothing the server decides; it exists so code written against
-  `PlanningFacade` reads the same on both sides.
 
 ## Depends On
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-planning",
-  "version": "0.1.18-rc.17",
+  "version": "0.1.18-rc.19",
   "license": "MIT",
   "description": "The client half of OwlMeans planning — the remote planning facade, the state mirror and its commit fold, and the subscribe-then-poll commit wait. React-free: it runs in a browser and in a Node client alike.",
   "type": "module",
@@ -23,16 +23,16 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.37",
-    "@owlmeans/client-context": "^0.1.18-rc.44",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.43",
+    "@owlmeans/auth": "^0.1.18-rc.38",
+    "@owlmeans/client-context": "^0.1.18-rc.45",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.44",
     "@owlmeans/context": "^0.1.18-rc.32",
-    "@owlmeans/entrypoint": "^0.1.18-rc.38",
+    "@owlmeans/entrypoint": "^0.1.18-rc.39",
     "@owlmeans/error": "^0.1.18-rc.36",
-    "@owlmeans/planning": "^0.1.18-rc.14",
+    "@owlmeans/planning": "^0.1.18-rc.16",
     "@owlmeans/resource": "^0.1.18-rc.37",
     "@owlmeans/route": "^0.1.18-rc.33",
-    "@owlmeans/socket": "^0.1.18-rc.36",
+    "@owlmeans/socket": "^0.1.18-rc.37",
     "@owlmeans/state": "^0.1.18-rc.36"
   },
   "peerDependencies": {
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/server-planning": "^0.1.18-rc.17",
+    "@owlmeans/server-planning": "^0.1.18-rc.19",
     "@owlmeans/test": "^0.1.18-rc.33",
     "@types/bun": "^1.4.0",
     "ajv": "^8.17.1",