@wowok/skills 1.2.4 → 1.2.6

package/wowok-scenario/SKILL.md

@@ -31,15 +31,29 @@ when_to_use:
 
 A **driving mode** is a curated bundle of: industry traits, default Permission indexes, default Machine node graph, default Guard templates, default Allocator strategy, a 10-round build script, an audit checklist, and a failure playbook. Modes are **presets, not constraints** — every underlying MCP operation remains available. Users can override any default or switch to `general` (free) mode at any time.
 
-> **Authoritative cross-reference**: This skill's mode definitions are aligned with the following internal references:
-> - [Guard Template Library](../references/guard-template-library.md) — Guard templates referenced by mode `Guards` column
-> - [Machine Template Library](../references/machine-template-library.md) — Machine shapes referenced by mode `Machine Shape` column
-> - [Machine Scenario Ledger](../references/machine-scenario-ledger.md) — 10 business scenarios per mode
-> - [Guard Scenario Ledger](../references/guard-scenario-ledger.md) — Guard usage scenarios per mode
-> - [Merchant Scenario Coordination §5](../references/merchant-scenario-coordination.md) — 6 industry modes × merchant perspective
-> - [On-chain Constants](../references/onchain-constants.md) — Permission index ranges and capacity limits
->
-> When a mode's defaults disagree with these references, the **design references** in this directory are authoritative (P15 decision: bidirectional cross-reference, with design references as single source of truth for object semantics).
+### On-Chain Capacity Limits (Inline Reference)
+
+Mode defaults respect these on-chain constants. When a mode's suggested count exceeds a limit, the SDK will reject the operation.
+
+| Constant | Value | Scope |
+|----------|-------|-------|
+| `MAX_NODE_COUNT_SDK` | 100 | Max nodes per Machine (SDK limit; on-chain allows 200) |
+| `MAX_FORWARD_COUNT` | 20 | Max global forwards per Machine |
+| `MAX_FORWARD_ORDER_COUNT` | 20 | Max forwards per node pair |
+| `MAX_NODE_PAIR_COUNT` | 40 | Max pairs per node |
+| `USER_DEFINED_PERM_INDEX_START` | 1000 | Custom permission_index start (0-999 reserved for built-in) |
+| `MAX_PERM_FOR_ENTITY` | 1000 | Max permissions per Entity |
+| `MAX_ADMIN_COUNT` | 500 | Max admins per Permission object |
+| `MAX_AGENT_COUNT` | 10 | Max agents per Order |
+| `MAX_DISPUTE_COUNT` | 10 | Max concurrent disputes per Order |
+| `MAX_SHARING_COUNT` | 100 | Max sharing entries per allocator |
+| `MAX_VOTING_GUARD_COUNT` | 50 | Max voting guards per Arbitration |
+| `MAX_POLICY_COUNT` | 50 | Max policies per Repository |
+| `MAX_ID_COUNT_ONCE` | 100 | Max IDs per Repository operation |
+| `MAX_REWARD_COUNT` | 20 | Max rewards per Demand/Repository |
+| `MAX_CONTEXT_REPOSITORY_COUNT` | 30 | Max context repositories per Progress |
+| `MAX_NAMED_OPERATOR_COUNT` | 60 | Max named operators per Forward |
+| `MAX_NAMED_OPERATOR_ADDRESS_COUNT` | 80 | Max addresses per named operator |
 
 ### What Driving Modes Solve
 
@@ -64,16 +78,7 @@ The selection algorithm maps the user's business description to industry traits,
 
 ### Trait Extraction
 
-```typescript
-type IndustryTraits = {
-  has_logistics: boolean;        // physical goods to ship?
-  communication_heavy: boolean;  // lots of back-and-forth before delivery?
-  pure_digital: boolean;         // deliverable is a file / digital artifact?
-  long_cycle: boolean;           // multi-week or multi-month engagement?
-  deposit_required: boolean;     // collect refundable deposit?
-  multi_tier_allocation: boolean; // pay multiple parties per segment?
-};
-```
+Industry traits used for mode selection: `has_logistics` (physical goods to ship?), `communication_heavy` (lots of back-and-forth before delivery?), `pure_digital` (deliverable is a file/digital artifact?), `long_cycle` (multi-week or multi-month engagement?), `deposit_required` (collect refundable deposit?), `multi_tier_allocation` (pay multiple parties per segment?).
 
 ### Selection Matrix
 
@@ -102,101 +107,81 @@ When two modes specify different Permission indexes for the same role, user deci
 
 ## Phase 1 Mode Details (Freelance & Rental)
 
-> The full detail for Phase 1 priority modes (Freelance & Rental) — including industry traits, Machine templates, Guard templates, Allocator strategies, 10-round build scripts, audit checklists, and failure playbooks — has been extracted to [MODE-DETAILS.md](./MODE-DETAILS.md) for on-demand loading.
->
-> **Load MODE-DETAILS.md when:**
-> - User selects `freelance` or `rental` mode
-> - wowok-onboard R3-R8 needs Machine/Guard/Allocator defaults
-> - User asks "what does the freelance/rental mode include?"
-> - Pre-publish audit needs mode-specific checklist
+> **Mode defaults** (traits, machine_shape, guards, allocator, key_risk, build_notes) are provided by MCP `project_operation` action `analyze_intent` — pass `industry` parameter and the MCP auto-fills scenario defaults from `knowledge/scenario-modes.ts`. The AI does NOT need to look up per-industry presets manually.
 
 ### Quick Reference (mode summaries)
 
 | Mode | Machine Shape | Guards | Allocators | Key Risk |
 |------|---------------|--------|------------|----------|
-| `freelance` | 7 nodes (ordered→...→completed/refunded) | 5 (buy/deliver/accept/withdraw/refund) | 2 (100% provider / 100% refund) | Customer never accepts delivery |
-| `rental` | 10 nodes (reserved→...→deposit_refunded/deducted) | 5 (deposit/return/inspect/refund/damage) | 3 (rent / refund / deduct) | Owner claims damage without pre-rental WIP |
+| `freelance` | 7 nodes (ordered→...→completed→{wonder\|no_wonder}) | 5 (buy/deliver/accept/withdraw/rating_window) | 2 (100% provider at completed / 0 at wonder-no_wonder) | Customer never accepts delivery |
+| `rental` | 10 nodes (reserved→...→completed→{wonder\|no_wonder}) | 5 (deposit/return/inspect/damage/rating_window) | 3 (rent at completed / refund-to-order via Allocator / damage deduct) | Owner claims damage without pre-rental WIP |
+
+> **Dispute Independence**: `refunded`/`disputed`/`arb` MUST NOT appear as Machine nodes (R-M1-11 critical). Refunds flow through Allocator (100%→OrderHolder) or Arbitration (dispute → ruling → arb_withdraw), both off-Machine. Wonder/no_wonder are post-completion reputation terminals only.
+
+### Freelance Audit Checklist (pre-publish BLOCKERS)
+
+- `accept_guard` exists + `gen_passport` tested — BLOCKER (no acceptance = funds stuck)
+- 100% refund Allocator (sharing.who=OrderHolder) — BLOCKER (no refund path = dispute deadlock)
+- Machine MUST NOT contain `refunded`/`disputed`/`arb` nodes (R-M1-11 critical) — BLOCKER. Refund flows through Allocator or Arbitration, both off-Machine
+- `withdraw_guard` only triggers at `Progress.current=completed` — BLOCKER (prevents premature payout)
+- `deliver_guard` validates WIP hash — recommended
+- Optional: wonder/no_wonder terminals after `completed` for post-purchase rating (enables Reward wonder_praise template)
+
+### Freelance Failure Playbooks
+
+- Customer never accepts: `accept_guard` includes timeout auto-accept forward (threshold met by `namedOperator:""` after N days)
+- Wrong deliverable hash: `deliver_guard` enforces WIP match → re-generate WIP, re-submit via `progress.hold:false`
+- No arbiter assigned: bind Arbitration via `service.arbitrations` AND configure `Arbitration.voting_guard` (NOT Permission index 1500 — arbiters live in voting_guard, never in Permission)
+
+### Rental Audit Checklist (pre-publish BLOCKERS)
+
+- `deposit_guard` validates `Order.balance ≥ deposit_amount` — BLOCKER (renter runs off with item)
+- 100% refund Allocator (sharing.who=OrderHolder) — BLOCKER (no refund = deposit theft)
+- `damage_guard` requires pre+post WIP hash diff — BLOCKER (no evidence = arbitrary deduction)
+- Machine MUST NOT contain `deposit_refunded`/`deposit_deducted`/`refunded` nodes (R-M1-11 critical) — BLOCKER. Deposit refund/deduction flows through Allocator, not Machine terminals
+- Pre-rental WIP generated + hash stored — BLOCKER (can't prove damage without pre-hash)
+- Rental period timeout forward on `in_use` node — recommended
+
+### Rental Failure Playbooks
+
+- Renter never returns: timeout forward to `damage_confirmed`, `deposit_deduct` Allocator fires
+- No pre-rental WIP: impossible post-publish — audit checklist blocks this at publish time
+- Owner refuses inspect: timeout forward auto-passes `inspect_guard`, `refund_guard` fires, deposit returns
+- Double-spend dispute: Machine topology ensures mutually exclusive forwards (first-Pair-wins), `escalate_arbiter` routes to Arbitration
 
 ---
 
 ## Education Mode (Phase 2 — Outline)
 
-### Industry Traits
-
-```typescript
-const educationTraits: IndustryTraits = {
-  has_logistics: false,
-  communication_heavy: true,
-  pure_digital: false,
-  long_cycle: true,
-  deposit_required: true,  // tuition pre-pay
-  multi_tier_allocation: false,
-};
-```
+**Traits**: communication_heavy, long_cycle, deposit_required (tuition pre-pay), not pure_digital.
 
 ### Mode Outline
 
-- **Default Machine**: enroll → pay_tuition → session_1 → session_2 → ... → session_N → completed / refunded
+- **Default Machine**: enroll → pay_tuition → session_1 → session_2 → ... → session_N → completed → {wonder | no_wonder}
 - **Default Guards**: `attendance_guard` (per session, student signs), `refund_guard` (institution approval OR arbiter)
 - **Default Allocator**: 1/N of tuition released per session attendance; unearned portion refundable on `refund_guard`
 - **Key trait**: `setting_locked_time` on Service prevents institution from changing rules mid-semester (regulatory compliance)
 - **GTM angle**: targets "tutoring institutions run away with prepaid tuition" pain point; policy-driven adoption
 
-### Phase 2 Build Status
-
-- Machine template: drafted, needs 1 pilot institution test
-- Guards: `attendance_guard` needs WIP hash for session content commitment
-- Allocator: per-session release needs threshold-based trigger
-- Audit checklist: pending real-world pilot
-
 ---
 
 ## Travel Mode (Phase 2 — Outline)
 
-### Industry Traits
-
-```typescript
-const travelTraits: IndustryTraits = {
-  has_logistics: false,
-  communication_heavy: true,
-  pure_digital: false,
-  long_cycle: true,
-  deposit_required: true,  // deposit + final payment
-  multi_tier_allocation: true,  // agency → hotel → guide → driver
-};
-```
+**Traits**: communication_heavy, long_cycle, deposit_required (deposit + final payment), multi_tier_allocation (agency → hotel → guide → driver).
 
 ### Mode Outline
 
-- **Default Machine**: order → pay_deposit → pay_final → segment_D1 → segment_D2 → ... → return → completed / refunded
+- **Default Machine**: order → pay_deposit → pay_final → segment_D1 → segment_D2 → ... → return → completed → {wonder | no_wonder}
 - **Default Guards**: `segment_guard` (per-segment arrival WIP, e.g., hotel check-in), `refund_guard` (agency approval OR arbiter for trip interruption)
 - **Default Allocator**: multi-tier — deposit 20% to agency, final 80% to agency, then agency-side Allocation splits to hotel/guide/driver per segment
 - **Key trait**: multi-tier Allocation is WoWok's unique advantage over traditional travel platforms
 - **GTM angle**: targets "paid in full then service shrinks" pain point
 
-### Phase 2 Build Status
-
-- Machine template: drafted, needs multi-tier Allocation pilot
-- Guards: `segment_guard` needs standardized WIP templates per segment type (hotel, transport, activity)
-- Allocator: multi-tier waterfall needs guard chaining validation
-- Audit checklist: pending real-world pilot
-
 ---
 
 ## Subscription Mode (Phase 3 — Outline)
 
-### Industry Traits
-
-```typescript
-const subscriptionTraits: IndustryTraits = {
-  has_logistics: false,
-  communication_heavy: false,
-  pure_digital: true,
-  long_cycle: true,
-  deposit_required: false,
-  multi_tier_allocation: false,
-};
-```
+**Traits**: pure_digital, long_cycle, not deposit_required, not communication_heavy.
 
 ### Mode Outline
 
@@ -206,13 +191,6 @@ const subscriptionTraits: IndustryTraits = {
 - **Key trait**: pure digital, native WoWok soil; directly attacks "auto-renew trap" and "platform takes 30%" pain points
 - **GTM angle**: independent creators (Indie Hackers, niche SaaS, paid newsletters)
 
-### Phase 3 Build Status
-
-- Machine template: planned
-- Guards: `charge_guard` needs periodic trigger mechanism (off-chain scheduler + on-chain Guard)
-- Allocator: per-period release straightforward
-- Audit checklist: pending design review
-
 ---
 
 ## Escape Hatch
@@ -228,14 +206,7 @@ Any user can switch from a driving mode to `general` (free) mode at any time. Th
 
 ### How to Switch
 
-```
-User says: "switch to general mode" or "configure manually"
-├── Stop applying mode defaults to remaining rounds
-├── Surface the IndustryModeSchema shape as a blank template
-├── User provides: Permission indexes, Machine nodes, Guards, Allocators manually
-├── wowok-onboard R3-R8 still execute, but with empty defaults
-└── wowok-machine / wowok-guard / wowok-provider become primary references
-```
+When user says "switch to general mode" or "configure manually": stop applying mode defaults to remaining rounds, surface the `IndustryModeSchema` shape as a blank template, let user provide Permission indexes/Machine nodes/Guards/Allocators manually. wowok-onboard R3-R8 still execute with empty defaults; wowok-machine / wowok-guard / wowok-provider become primary references.
 
 ### Warning
 
@@ -252,11 +223,8 @@ User can switch back to a driving mode after using general mode:
 
 ---
 
-## Appendices (Progressive Disclosure)
+## Tier Layering
 
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Tier Layering — expertise-tier based guidance
-> - IndustryModeSchema — schema reference
-> - Quick Reference — lookup table
->
-> Load APPENDIX.md when the user needs tier-specific guidance, schema reference, or quick lookup.
+- **Novice**: Full driving mode — mode defaults fill all rounds, user only confirms
+- **Advanced**: Customize defaults — user overrides specific fields (e.g., Allocator split), audit checklist still runs
+- **Expert**: General mode — no defaults, raw MCP operations, wowok-machine/guard/provider become primary references

package/wowok-tools/SKILL.md

@@ -142,90 +142,95 @@ Step 3: MODIFY reward { object: "reward_v1", guard_add: [...] } // bind guard
 
 ---
 
-## The 17 Sub-Tools (all via `wowok({ tool, data })`)
+## Sub-Tool Schema-Inexpressible Constraints
 
-### 1. `onchain_operations` — 16 Sub-Types
+> MCP schemas define field types/validation. The constraints below are business rules NOT expressible in schemas — AI must know them before calling.
 
-> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations" } })` for the full discriminated union. Per-type schemas: `onchain_operations_service`, `onchain_operations_machine`, etc.
+### `onchain_operations` (18 sub-types)
 
-| `operation_type` | Schema-Inexpressible Constraints |
+| `operation_type` | Key Constraints (not in schema) |
 |-----------------|----------------------------------|
-| `service` | `machine` field must reference a **published** Machine. Allocators evaluated in array order (first-Guard-wins). Publish locks `machine`/`order_allocators`; `sales`/`discount`/`description` remain mutable. |
-| `machine` | Nodes immutable after publish. Forward requires ≥1 of `namedOperator`/`permissionIndex` (both empty = SDK error). Weight `u16` (0–65535), threshold `u32`. `""` = entry node. Full lifecycle → [wowok-machine](../wowok-machine/SKILL.md). |
-| `progress` | Two-phase advancement: `hold: true` (lock) → `hold: false` (submit). `adminUnhold: true` force-releases others' locks. SDK fetches Machine internally when resolving `object_address`. |
-| `arbitration` | MAX 20 propositions, 520 voters. Non-Finished withdrawal triggers 30-day mandatory wait. Verdict (state 2→3) is **irreversible** by arbitrator — only customer can object via `order.arb_objection`. Voting weight from Guard `b_submission:true` must be numeric (U8–U256→u32). Full workflow → [wowok-arbitrator](../wowok-arbitrator/SKILL.md). |
-| `guard` | Two creation modes: `root.type: "node"` (inline) or `"file"` (from JSON/Markdown). MAX 4 `rely` dependencies. Guards with `rep: false` **excluded** from other Guards' `rely` lists. Global system addresses (`0xaab` EntityRegistrar, `0xaaa` EntityLinker) require table entries. Full design → [wowok-guard](../wowok-guard/SKILL.md). |
-| `gen_passport` | MAX 20 Guards/call (AND-ed — all must pass). Omit `info` to auto-fetch submissions from Guards. Passport frozen after creation (immutable credential). Usage → [wowok-guard](../wowok-guard/SKILL.md). |
-| `order` | Builder-owned: agents can operate but **cannot withdraw** — only builder receives funds. `order.progress` with Guard requires Passport (mandatory, not bypassable). Arbitration via `order.arb_confirm`/`arb_objection` (not via `arbitration` directly). `arb_claim_compensation` once-only, from Service's compensation fund. Full flow → [wowok-order](../wowok-order/SKILL.md). |
-| `payment` | `type_parameter` required (e.g., `"0x2::wow::WOW"`). Irreversible — no refund mechanism. |
-| `personal` | **Permanently public** — no private field exists. Warn users before writing sensitive data. |
-| `demand` | Guard-gated: `guards` filter which presenters can submit solutions. Separate from Service. |
-| `treasury` | Guardable deposits (`external_deposit_guard`) and withdrawals (`external_withdraw_guard`). Each entry creates a Payment record in history table for auditability. |
-| `repository` | Composite key: `name + entity` (address or number). Guardable writes validate both writer eligibility and data content. |
-| `reward` | `guard_add` AmountType: `Fixed` (equal) or `GuardU64Identifier` (dynamic from submission). `guard_expiration_time` freezes the Guard list; `null` to remove. |
-| `allocation` | Auto-executes on Progress advancement; modes evaluated in order (Amount → Rate → Surplus), first-Guard-wins per mode. |
-| `contact` | Bridge between Service (`um` field) and Messenger: holds `ims[]` (messenger addresses). |
-| `permission` | Indices 0–65535 (0–999 reserved for protocol; custom ≥1000). SDK rejects custom below 1000. Reuse across objects. |
-
-### WIP Hash Dispute-Prevention Mechanism
-
-When a customer browses products, the AI agent MUST capture the `wip_hash` from the Service query result (the `sale.wip_hash` field for each product). When creating an order, pass the captured hash in `buy.items[].wip_hash`.
-
-This is a two-layer protection:
-1. **Off-chain** (SDK `verify_wip`): downloads the WIP file and verifies its hash matches the captured hash — detects WIP file tampering.
-2. **On-chain** (Move contract `assert!(sale.wip_hash == i.wip_hash)`): confirms the Service's sale hasn't been updated between browse and purchase time.
-
-If the merchant swaps the WIP file or changes `sale.wip_hash` after the customer browses, the order will fail — the customer is protected from bait-and-switch.
+| `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`. |
+| `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) |
+| `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. |
+| `treasury` | Guardable deposits/withdrawals. Each entry creates Payment record for audit. |
+| `repository` | Composite key: `name + entity`. Guard validates writer + content. |
+| `reward` | `guard_add`: `Fixed` (equal) or `GuardU64Identifier` (dynamic). `guard_expiration_time` freezes Guard list; `null` removes. |
+| `allocation` | Auto-executes on Progress advance. Order: Amount → Rate → Surplus, first-Guard-wins per mode. |
+| `contact` | Bridge: Service `um` ↔ Messenger `ims[]`. IM mutations need permission index 453; no events (poll `ims[]`). |
+| `permission` | 0–999 reserved; custom ≥1000. SDK rejects <1000. Reusable across objects. |
+| `proof` | Immutable (freeze_object). `proof_type=1` reserved for WTS; >100 for custom. Large data → Repository + `about_address`, not inline. |
+| `gen_proof` | Convenience wrapper: creates Proof without `namedNew`. Same immutability rules. Use `proof` with `namedNew` when naming is needed. |
+
+**WIP hash anti-bait**: Capture `sale.wip_hash` when browsing; pass in `buy.items[].wip_hash`. Two-layer: SDK verifies file hash off-chain, Move asserts on-chain. Merchant swap = order fails.
+
+### Other Tools (compact)
+
+| Tool | Key Constraints |
+|------|----------------|
+| `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. |
+| `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) |
+| `wip_file` | `verify`: hash → signatures stepwise. `wip2html`: single file or directory. |
+| `guard2file` | Read-only export to JSON/Markdown. |
+| `machineNode2file` | Read-only; exports complete topology. |
+| `onchain_events` | 6 event types; cursor `{eventSeq, txDigest}`. |
+| `wowok_buildin_info` | 5 info types. Guard instructions filter by `name`/`return_type`/`param_count`. **Never use Value type 19**. |
+| `schema_query` | `list` returns empty if schemas not generated → `npm run generate:schemas`. |
 
 ---
 
-### 2. `query_toolkit` — Read (Local + On-Chain)
+## Supporting Objects — When to Use
 
-9 query types. Schema-inexpressible: `token_list` is **cached** (populated on first query). `account_balance` dual-mode: `balance=true` for totals, `coin={cursor,limit}` for paginated coin objects. `onchain_objects` batches 50/request internally. `local_names` resolves to account names AND local marks simultaneously.
+> MCP handles risk assessment + confirmation rules automatically. This section covers business decisions NOT in schemas — WHEN and WHY to choose each object type.
 
-### 3. `onchain_table_data` — Dynamic Table Queries
+### Proof vs WIP
 
-12 query types. **Global** (no `parent`): `entity_registrar`, `entity_linker`. All others require `parent`. `onchain_table_item_generic` accepts arbitrary key types — universal fallback for custom objects.
+| Aspect | Proof (on-chain) | WIP (off-chain file) |
+|--------|-----------------|---------------------|
+| Purpose | Cryptographic attestation (merkle root, server signature, timestamp) | Product description + images for arbitration evidence |
+| Immutability | `freeze_object` — permanent on-chain record | File hash anchored on-chain; file stored off-chain |
+| Size | `MAX_PROOF_SIZE` (compact digests only) | Unlimited (file-based) |
+| Use when | Need on-chain timestamp + signature verification | Need product evidence for order disputes |
 
-### 4. `account_operation` — Wallet (ALL LOCAL)
+`gen_proof` = convenience (no `namedNew` wrapper). `proof` with `namedNew` = named object for reuse by reference. For large data, store in Repository and set `about_address` to the Repository ID.
 
-`faucet` only testnet/localnet. `gen` with `m` enables Messenger. `signData` supports UTF-8/base64/hex. `get` with `balance_required` splits existing coins (no minting). Private keys never leave the device.
+### Treasury vs Allocation
 
-**Mainnet operations**: `faucet` is unavailable on mainnet. To fund new accounts, use `transfer` from an existing account with sufficient balance:
-```
-{"transfer": {"amount": 1000000000, "name_or_address_from": "", "name_or_address_to": "new_account", "network": "mainnet"}}
-```
-- 1 WOW (10^9 base units) per account is sufficient for dozens of transactions
-- `name_or_address_from: ""` uses the default account
-
-### 5. `local_mark_operation` — Address Book (ALL LOCAL)
-
-Max 50 tags/entry (64 chars each). `replaceExistName:true` steals existing names — prefer versioned names (`_v1`, `_v2`).
+| Aspect | Treasury | Allocation |
+|--------|----------|------------|
+| Purpose | Team fund management (deposit/withdraw with audit trail) | Order fund distribution (auto-trigger on Progress advance) |
+| Trigger | Manual deposit/withdraw (Guard-gated) | Automatic when Progress reaches configured node |
+| Guard | External guard on withdrawals | Allocation guard on distribution rules |
+| Use when | Holding pooled funds, compensation funds, team wallets | Splitting order payments among recipients |
 
-### 6. `local_info_operation` — Private Data (ALL LOCAL)
+Compensation fund = Treasury bound to Service. Each Treasury entry creates a Payment record for audit. Withdrawal requires Guard verification.
 
-Max 50 contents/entry, 300 chars each.
+### Reward (Incentive Pools)
 
----
+Guard-gated claim pools: `claim_guard` verifies eligibility before payout. `guard_add` modes: `Fixed` (equal split among claimants) or `GuardU64Identifier` (dynamic amount from Guard table index). `guard_expiration_time` freezes the Guard list (set `null` to remove freeze). Use cases: customer loyalty rewards, referral bonuses, airdrop campaigns, attendance rewards. Query claim history via `query_toolkit` → `onchain_table_item_reward_record`.
 
-### 7. `messenger_operation` — Encrypted Messaging
+### Demand (Customer-Posted Requests)
 
-**Stranger rules** (not in schema): 1 message before reply required (max ~480 chars); reply auto-adds stranger to friends; cool-down window after rejection.
+Demand is the **inverse** of Service: customer posts a request + optional reward pool, providers submit offers. Guard-gated: `guards` filter which providers can present. `recommend_guard` filters presenter submissions. Separate `operation_type: "demand"` — NOT `service`. Use when: customer needs competitive bids (custom work, bulk procurement, reverse-auction marketplace). Pair with Reward to incentivize providers.
 
-**Guard flow** (not in schema): When guard blocks a stranger message, rejection reply includes guard list — sender must obtain valid Passport to resend.
+### Repository (On-Chain Database)
 
-**WTS** (not in schema): `generate` requires continuous sequences (gaps break chain). `verify` → `sign` → `wts2html` pipeline. `proof_message` anchors to blockchain. Full design → [wowok-messenger](../wowok-messenger/SKILL.md).
+Composite key: `name + entity`. Guard validates writer identity + content integrity. `id_from_submission` (must be Address) and `data_from_submission` (must match Repository's `value_type`) extract structured data from Guard submissions. Use cases: supply-chain tracking, multi-party attestation, dynamic pricing data, KYC registries. MAX 50 policies per Repository, 100 IDs per operation. Guard design: see [wowok-guard](../wowok-guard/SKILL.md) §"Where Guards Attach".
 
----
+### Contact (Service.um Bridge)
 
-| # | Tool | Schema-Inexpressible |
-|---|------|---------------------|
-| 8 | `wip_file` | `verify` checks hash → signatures stepwise. `wip2html` accepts single file or directory. |
-| 9 | `guard2file` | Read-only export to JSON/Markdown. |
-| 10 | `machineNode2file` | Read-only; exports complete topology. |
-| 11 | `onchain_events` | 6 event types; paginated via cursor `{eventSeq, txDigest}`. |
-| 12 | `wowok_buildin_info` | 5 info types. Guard instructions filter by `name`/`return_type`/`param_count`. **Never use Value type 19** (internal, SDK rejects). |
-| 13 | `schema_query` | `list` returns empty if schemas not generated → run `npm run generate:schemas`. |
+Contact is the on-chain bridge: `Service.um` → `Contact` → `ims[]` (Messenger endpoints). Create BEFORE Service publish when `customer_required` is set. Contact can also bind to `Permission.um` (bidirectional dependency — clear `Permission.um` via `permission_um_set(null)` before deleting Contact). IM list mutations (`im_add`/`im_remove`) require permission index 453; no events emitted (poll `ims[]` field). Full Messenger integration: see [wowok-messenger](../wowok-messenger/SKILL.md).
 
 ---
 
@@ -250,41 +255,7 @@ Discover?    → tool: "schema_query" / "wowok_buildin_info" / "onchain_events"
 
 ## Examples Reference
 
-The deployment package includes 5 complete examples in the `examples/` directory. These serve as reference implementations to help explain concepts and demonstrate patterns to users.
-
-### Matching User Intent to Examples
-
-When a user describes their needs, reference the appropriate example to illustrate the approach:
-
-| User Intent | Example | Complexity | Key Techniques Demonstrated |
-|-------------|---------|------------|----------------------------|
-| Simple service with time-lock | Insurance | ⭐ Low | Two-node workflow, convert_witness, time-lock Guard |
-| E-commerce store setup | MyShop | ⭐⭐ Medium | Four-node workflow, Permission indexes, Messenger integration, discounts |
-| Complex multi-path order flow | MyShop_Advanced | ⭐⭐⭐ High | 11+ nodes, dual-signature (threshold=2), Merkle Root verification, Reward pool |
-| Weather/data validation service | Travel | ⭐⭐⭐ High | Repository queries, convert_number_address, supply chain sub-orders |
-| Signature/authorization service | ThreeBody_Signature | ⭐ Low | Buy Guard for access control, Machine-Service binding |
-
-### Finding Examples by Technique
-
-When explaining a specific technique to users, reference where it appears:
-
-| Technique | Example | Location |
-|-----------|---------|----------|
-| convert_witness: 100 (Order to Progress) | Insurance, Travel | Insurance Step 2 |
-| Repository data query Guard | Travel | Step 3.1 |
-| Dual-signature (threshold=2) | MyShop_Advanced | Lost/Return nodes |
-| Reward pool with Guard verification | MyShop_Advanced | reward_wonderful_v2 Guards |
-| Buy Guard (restricting purchasers) | ThreeBody_Signature | Step 2 |
-| Discount coupons | MyShop | Step 8 |
-| Arbitration with voting_guard | MyShop_Advanced | Step 9 |
-| Time-lock Guard | Insurance, Travel | Step 2 / Step 3.2 |
-
-### How to Use Examples with Users
-
-1. **Assess complexity** — Match user requirements to the appropriate complexity level
-2. **Reference the example** — Show users the relevant example path and explain which techniques it demonstrates
-3. **Extract patterns** — Use JSON snippets from examples as templates to help users understand the structure
-4. **Reference test results** — Each example includes `*_TestResults.md` with real testnet execution results for troubleshooting
+5 examples in `examples/` directory: **Insurance** (⭐ time-lock Guard), **MyShop** (⭐⭐ e-commerce, Messenger, discounts), **MyShop_Advanced** (⭐⭐⭐ 11+ nodes, dual-sig, Merkle Root, Reward), **Travel** (⭐⭐⭐ Repository Guard, supply chain), **ThreeBody_Signature** (⭐ Buy Guard). Each includes `*_TestResults.md` with real testnet data. Match user intent → example complexity → extract JSON patterns.
 
 ---
 
@@ -305,13 +276,3 @@ When explaining a specific technique to users, reference where it appears:
 | Arbitration called directly | Customer path: `order.arb_confirm` / `order.arb_objection`. Order is the interface |
 
 ---
-
-## Appendices (Progressive Disclosure)
-
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Dialogue Scripts (R1-R10) — guided conversation scripts
-> - Decision Trees — branching logic reference
-> - Failure Playbooks — recovery scenarios
-> - Tier Layering — expertise-tier based guidance
->
-> Load APPENDIX.md when the user needs guided dialogue, recovery help, or tier-specific guidance.