@wowok/skills 1.2.7 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/wowok-machine/SKILL.md

@@ -65,9 +65,9 @@ This Skill keeps the **workflow conversation guidance**, **business flow design
 | `permissionIndex` | Shared across ALL Progress instances | Internal staff (warehouse, admin, platform) — same for every order |
 | `namedOperator` | Per-Progress namespace | Roles that differ per order (delivery person, reviewer, agent) |
 
-- `namedOperator: ""` (empty string): grants **order owner and agents** the right to execute. Standard way to let customers operate.
-- `namedOperator: "<role_name>"`: role-based operators managed per Progress instance. Each Progress independently assigns addresses to role names.
-- **Both fields set**: executor needs EITHER permission — internal staff OR external roles.
+- `namedOperator: ""` (empty string): grants **order owner and agents** the right to execute. Standard way to let customers operate. **⚠ Must be advanced via `order.progress`** (uses `order.has_op_permission`); direct `progress::next` aborts with Permission denied (code 5).
+- `namedOperator: "<role_name>"`: role-based operators managed per Progress instance. Each Progress independently assigns addresses to role names. **Advanced via `progress.operate`** directly.
+- **Both fields set**: executor needs EITHER permission — internal staff OR external roles. **Advanced via `progress.operate`** (the non-empty namedOperator takes precedence for routing).
 - **Design principle**: Use custom permissions (dedicated Permission object with custom indices), not built-in indices. Define workflow-specific roles, reference those indices in Forwards.
 
 ### Guard on Forwards

package/wowok-messenger/SKILL.md

@@ -56,14 +56,14 @@ Every conversation between two addresses has a deterministic session. Messages a
 Before any communication:
 
 1. **Account must exist** → `account_operation` (gen)
-2. **Enable messenger** → `account_operation` (messenger), set a messenger name
+2. **Enable messenger** → `account_operation` (messenger), set `enabled: true`
 3. **Get your address** → `account_operation` (get) — share this address with your counterparties
 
-> The messenger name is required for message delivery. Without it, your account has no messenger endpoint and cannot receive messages.
+> Messenger must be enabled for message delivery. Without it, your account has no messenger endpoint and cannot receive messages. Account name is used for messenger identity lookup.
 
 ### Account Limit
 
-A single device supports up to 1000 messenger accounts. Exceeding this returns "Maximum 1000 messenger accounts allowed". Use `account_operation → messenger { m: null }` to disable unused accounts.
+A single device supports up to 1000 messenger accounts. Exceeding this returns "Maximum 1000 messenger accounts allowed". Use `account_operation → messenger { enabled: false }` to disable unused accounts.
 
 ### Contact Object (On-Chain Bridge)
 
@@ -225,7 +225,7 @@ When a dispute requires evidence: (1) `generate_wts` → export messages by time
 ## Common Pitfalls
 
 - **One-message limit trap**: Sending a vague first message to a stranger wastes your only chance. Make the first message complete and actionable.
-- **Disabled messenger**: Without a messenger name set, your account has no endpoint — counterparties cannot find or message you.
+- **Disabled messenger**: Without messenger enabled, your account has no endpoint — counterparties cannot find or message you.
 - **WTS range too narrow**: Selecting only favorable messages undermines evidence credibility. Include the full conversation.
 - **Guard list without strategy**: Adding a Guard to your list without testing it (`gen_passport`) means you don't know what conditions strangers must meet — you may be blocking legitimate contacts.
 - **`allowStrangerMessages: false` with no guard list and no friends**: Nobody can contact you. Always ensure at least one inbound path exists.

package/wowok-order/SKILL.md

@@ -79,12 +79,14 @@ Use `wip_file` → `op: "verify"`, `wipFilePath: "<wip_url>"`, `hash_equal: "<wi
 
 **Step 3: Classify every forward**:
 
-| `namedOperator` | `guard` | User Can Execute? |
-|-----------------|---------|-------------------|
-| `Some("")` | `None` | ✅ Independently via `order.progress` |
-| `Some("")` | `Some({...})` | ⚠️ Need Guard passport — **no bypass** |
-| `None` | Any | ❌ Provider/permission-holder only |
-| `Some("<other>")` | Any | ❌ Named operator required |
+| `namedOperator` | `guard` | User Can Execute? | Operation Path |
+|-----------------|---------|-------------------|----------------|
+| `Some("")` | `None` | ✅ Independently | **`order.progress`** (uses `order.has_op_permission`) |
+| `Some("")` | `Some({...})` | ⚠️ Need Guard passport — **no bypass** | **`order.progress`** + Passport |
+| `None` | Any | ❌ Provider/permission-holder only | `progress.operate` (provider path) |
+| `Some("<other>")` | Any | ❌ Named operator required | `progress.operate` (named operator path) |
+
+> **⚠ CRITICAL ROUTING RULE**: When `namedOperator=""` (empty string = OrderHolder), you MUST use `order.progress` (NOT `progress.operate`). Direct `progress::next` will abort with "Permission denied" (code 5) because the Progress-level permission check does not recognize the OrderHolder short-circuit. The empty-string `namedOperator` is set automatically by `service::buy` when an Order is created — the customer (order.builder) becomes the operator for the `""` namespace. In ALL other cases (non-empty `namedOperator` or `permissionIndex`-only), use `progress.operate` on the Progress object directly.
 
 **Step 4: Detect paths**:
 - Terminal nodes (no outgoing forwards) → order ends

package/wowok-provider/SKILL.md

@@ -311,6 +311,16 @@ Before forking, verify necessity via `get_project_detail` → `has_published_obj
 | Order | Fund escrow | Read-only |
 | **Progress** | Workflow state | **Operate this** — `hold: true` (lock) → work → `hold: false` (submit) |
 
+**⚠ Progress Routing Rule** (critical):
+
+| Forward `namedOperator` | Required Operation | Why |
+|------------------------|--------------------|-----|
+| `""` (empty = OrderHolder) | `order.progress` | Uses `order.has_op_permission` — order owner/agents authorized |
+| `"<role_name>"` (non-empty) | `progress.operate` | Uses Progress named_operator namespace |
+| `None` + `permissionIndex` | `progress.operate` | Uses Permission object entity table |
+
+Wrong path → "Permission denied" (Move abort code 5). The empty-string `namedOperator` is set automatically by `service::buy` — the customer becomes the operator. Providers who need to act on a forward should either use a non-empty `namedOperator` (and `progress.operate`) or use `permissionIndex` (requiring a custom permission grant in the Service's Permission object).
+
 **AI Reminder**: When fulfilling, check `customer_required` fields. Missing → prompt via Messenger.
 
 ---

package/wowok-safety/SKILL.md

@@ -118,16 +118,19 @@ When users request complex systems without naming, propose this scheme:
 
 ### 4.1 `replaceExistName` Flag
 
-Controls name collision behavior:
+Controls name collision behavior. **DISCOURAGED** — prefer versioned names (`_v1`, `_v2`).
 
 | Value | Effect |
 |-------|--------|
 | `false` (default) | Throws error if name is in use — safe default |
-| `true` | Steals name from existing object; old object becomes unnamed |
+| `true` | Existing object/account with the same name is **suspended** (deactivated) to free the name |
 
-- Use `true` during development to reuse fixed names without cleanup
-- Default to `false` in production to prevent accidental name hijacking
-- Prefer versioned names (`_v1`, `_v2`) over `replaceExistName` for production
+**Account-specific rules** (stricter than on-chain objects):
+- `replaceExistName: true` on the **default account** (`name=''` or omitted) is **FORBIDDEN** — throws error. The default account is unique and cannot be suspended by replacement; use `suspend()` explicitly if needed.
+- On non-default account names, `replaceExistName: true` **suspends** the old account (moves to Suspended tab, clears name + messenger). The old account can be reactivated via `resume(address, new_name)`.
+- This prevents the "orphan unnamed account" bug where old accounts leaked into the Active list without a name.
+
+**On-chain objects** (NamedObjectSchema): `replaceExistName: true` steals the name; the old object becomes unnamed (address-only reference). Prefer versioned names for production.
 
 ---
 

package/wowok-tools/SKILL.md

@@ -152,11 +152,11 @@ Step 3: MODIFY reward { object: "reward_v1", guard_add: [...] } // bind guard
 |-----------------|----------------------------------|
 | `service` | `machine` must be **published**. Allocators: array order = priority (first-Guard-wins). Publish locks `machine`/`order_allocators`; `sales`/`discount`/`description` stay mutable. |
 | `machine` | Nodes immutable after publish. Forward needs ≥1 of `namedOperator`/`permissionIndex` (both empty = SDK error). `""` = entry node. → [wowok-machine](../wowok-machine/SKILL.md) |
-| `progress` | Two-phase: `hold:true` (lock) → `hold:false` (submit). `adminUnhold:true` force-releases. SDK auto-fetches Machine when resolving `object_address`. |
+| `progress` | Two-phase: `hold:true` (lock) → `hold:false` (submit). `adminUnhold:true` force-releases. SDK auto-fetches Machine when resolving `object_address`. **⚠ Routing rule**: Use `progress.operate` ONLY for forwards with non-empty `namedOperator` or `permissionIndex`-only. For forwards with `namedOperator=""` (OrderHolder), use `order.progress` instead — direct `progress::next` aborts with Permission denied (code 5). |
 | `arbitration` | MAX 20 propositions, 520 voters. Verdict (2→3) **irreversible** — only customer can `order.arb_objection`. Non-Finished withdrawal = 30-day wait. → [wowok-arbitrator](../wowok-arbitrator/SKILL.md) |
 | `guard` | `root.type:"node"` (inline) or `"file"` (JSON/MD). MAX 4 `rely`. `rep:false` Guards excluded from others' `rely`. System addresses `0xaab`/`0xaaa` need table entries. → [wowok-guard](../wowok-guard/SKILL.md) |
 | `gen_passport` | MAX 20 Guards/call (AND-ed). Omit `info` to auto-fetch. Passport = frozen immutable credential. |
-| `order` | Agents can operate but **cannot withdraw** — only builder. `order.progress`+Guard requires Passport. Arb via `order.arb_confirm`/`arb_objection` (not `arbitration` directly). `arb_claim_compensation` once-only. → [wowok-order](../wowok-order/SKILL.md) |
+| `order` | Agents can operate but **cannot withdraw** — only builder. `order.progress`+Guard requires Passport. **⚠ Routing rule**: `order.progress` works ONLY for forwards with `namedOperator=""` (OrderHolder) — uses `order.has_op_permission`. For non-empty `namedOperator` or `permissionIndex`-only forwards, use `progress.operate` on the Progress object directly. Arb via `order.arb_confirm`/`arb_objection` (not `arbitration` directly). `arb_claim_compensation` once-only. → [wowok-order](../wowok-order/SKILL.md) |
 | `payment` | `type_parameter` required. **Irreversible** — no refund. |
 | `personal` | **Permanently public** — warn users before writing sensitive data. |
 | `demand` | Guard-gated: `guards` filter presenters. Separate from Service. |
@@ -177,7 +177,7 @@ Step 3: MODIFY reward { object: "reward_v1", guard_add: [...] } // bind guard
 |------|----------------|
 | `query_toolkit` | `token_list` cached (first query populates). `account_balance`: `balance=true` for totals, `coin={cursor,limit}` for paginated. `onchain_objects` batches 50/req. `local_names` resolves accounts + marks. |
 | `onchain_table_data` | 12 types. Global (no `parent`): `entity_registrar`, `entity_linker`. `onchain_table_item_generic` = universal fallback. |
-| `account_operation` | `faucet` testnet/localnet only. Mainnet funding: `transfer` from existing account (1 WOW = 10^9 base units). `gen` with `m` enables Messenger. Private keys never leave device. |
+| `account_operation` | `faucet` testnet/localnet only. Mainnet funding: `transfer` from existing account (1 WOW = 10^9 base units). `gen` with `messenger: true` enables Messenger. **Naming convention**: `<role>-<number>` (e.g. `shop-001`, `user-001`, `arb-001`) for easy filtering. `gen.replaceExistName:true` is DISCOURAGED — suspends old account; FORBIDDEN on default account (name=''). Private keys never leave device. |
 | `local_mark_operation` | Max 50 tags/entry (64 chars). `replaceExistName:true` steals names — prefer `_v1`/`_v2`. |
 | `local_info_operation` | Max 50 contents/entry, 300 chars each. |
 | `messenger_operation` | Stranger: 1 msg before reply (~480 chars). Guard block → rejection includes guard list; sender needs Passport. WTS: `generate` needs continuous sequences. → [wowok-messenger](../wowok-messenger/SKILL.md) |