@wowok/skills 1.2.3 → 1.2.5

package/wowok-safety/SKILL.md

@@ -70,20 +70,7 @@ Empty string `""` means the default account. Always use `""` when the user does
 
 ### 2.1 Confirmation Template
 
-```
-📋 **Operation Preview**
-
-| Field | Value |
-|-------|-------|
-| Operation | {operation_type} — {op} |
-| Object | {object_name} |
-| Network | {network} |
-| Account | {account} |
-
-⚠️ **This will {describe_what_will_happen}**
-
-Proceed with execution?
-```
+Present a preview table (Operation, Object, Network, Account) with a warning describing what will happen, then ask: "Proceed with execution?"
 
 ### 2.2 Amount Verification
 
@@ -98,26 +85,7 @@ Proceed with execution?
 
 ### 2.3 Publish Confirmation
 
-Before publishing a Service or Machine:
-
-1. **Export and review**:
-   - Use `guard2file` to export Guard definitions
-   - Use `machineNode2file` to export Machine nodes
-
-2. **Verify logic**: Confirm Guards and Machine nodes match user intent
-
-3. **Warn about immutability**: Once published, many fields become locked
-
-```
-⚠️ PUBLISH CONFIRMATION REQUIRED
-
-You are about to publish:
-- {Service|Machine}: {name}
-- This will make it publicly accessible on-chain
-- After publish: {list what becomes immutable}
-
-This action cannot be easily undone. Proceed?
-```
+Before publishing a Service or Machine: (1) Export and review — use `guard2file` to export Guard definitions, `machineNode2file` to export Machine nodes; (2) Verify logic — confirm Guards and Machine nodes match user intent; (3) Warn about immutability — once published, many fields become locked. Present a publish confirmation warning listing what becomes immutable, then ask: "This action cannot be easily undone. Proceed?"
 
 ---
 
@@ -209,32 +177,15 @@ Use `Payment` objects for commercial transfers when possible — they offer Guar
 
 ## 8. Testing & Validation Workflow
 
-1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions, Guard instructions, and value types
-
-**Tool**: `wowok_buildin_info` with `info: "built-in permissions"`, `info: "guard instructions"`, or `info: "value types"`.
+1. **Design Phase**: Discover available permissions, Guard instructions, and value types via `wowok_buildin_info` (`info: "built-in permissions"` / `"guard instructions"` / `"value types"`).
+2. **Export & Review**: Before publishing, use `guard2file` and `machineNode2file` to export and review definitions.
+3. **Incremental Testing**: Build objects step-by-step, verifying each step.
+4. **Final Validation**: Test all Guard conditions and Machine transitions before publishing.
+5. **Publish**: Only after thorough testing, publish Service and Machine.
 
 ### 8.1 Value Types — Built-in Type Annotation System
 
-WoWok's value type system is the foundation for type-safe data declarations used across Guards, records, and query instructions. Every data field in a Guard table or Guard submission carries a `value_type` annotation, ensuring the protocol can validate and process data correctly.
-
-**When value types matter:**
-- Defining Guard table columns: each Identifier in a Guard's `table` block requires a `value_type`
-- Submitting data to Guards: `GuardSubmission` entries must match their declared `value_type`
-- Reading Guard exports: `guard2file` output shows `value_type` for every Identifier
-- Designing query instructions: both parameters and return values carry `value_type` annotations
-
-- **String format is recommended** (e.g., `"U64"`, `"Address"`, `"VecString"`) for readability in Guard tables and submissions.
-- Numeric codes (0–18) are accepted but obscure — prefer string names in all user-facing contexts.
-- `Value` (19) is a protocol-internal type for dynamic value handling. It must **never** be used directly in user-defined Guards or submissions.
-**Available value types** (queried via `wowok_buildin_info` with `info: "value types"`)
-
-2. **Export & Review**: Before publishing, use `guard2file` and `machineNode2file` to export and review definitions
-
-3. **Incremental Testing**: Build objects step-by-step, verifying each step
-
-4. **Final Validation**: Test all Guard conditions and Machine transitions before publishing
-
-5. **Publish**: Only after thorough testing, publish Service and Machine
+Every data field in a Guard table or submission carries a `value_type` annotation. Value types matter when: defining Guard table columns, submitting data to Guards, reading `guard2file` exports, and designing query instructions. **String format is recommended** (`"U64"`, `"Address"`, `"VecString"`) for readability; numeric codes (0–18) are accepted but obscure. `Value` (19) is protocol-internal — never use in user-defined Guards. Available types are queried via `wowok_buildin_info` with `info: "value types"`.
 
 ---
 
@@ -251,29 +202,6 @@ For complex objects with many fields (Service, Machine), use **incremental build
 
 ## Schema Reference
 
-| Purpose | Schema Name |
-|---------|-------------|
-| Query toolkit | `query_toolkit` |
-| Token list | `query_toolkit` with `query_type: "token_list"` |
-| Guard export | `guard2file` |
-| Machine export | `machineNode2file` |
-| Build-in info | `wowok_buildin_info` |
-| Built-in permissions | `wowok_buildin_info` with `info: "built-in permissions"` |
-| Guard instructions | `wowok_buildin_info` with `info: "guard instructions"` |
-| Value types | `wowok_buildin_info` with `info: "value types"` |
-
-**Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
-
 **Related Skills**: [wowok-tools](../wowok-tools/SKILL.md) | [wowok-guard](../wowok-guard/SKILL.md) | [wowok-machine](../wowok-machine/SKILL.md) | [wowok-order](../wowok-order/SKILL.md) | [wowok-provider](../wowok-provider/SKILL.md) | [wowok-arbitrator](../wowok-arbitrator/SKILL.md) | [wowok-messenger](../wowok-messenger/SKILL.md)
 
 ---
-
-## 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.

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,13 +107,7 @@ 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)
 
@@ -117,22 +116,41 @@ When two modes specify different Permission indexes for the same role, user deci
 | `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 Audit Checklist (pre-publish BLOCKERS)
+
+- `accept_guard` exists + `gen_passport` tested — BLOCKER (no acceptance = funds stuck)
+- `refund_guard` + 100% refund Allocator — BLOCKER (no refund = dispute deadlock)
+- Machine has terminal nodes for both `completed` and `refunded` — BLOCKER (dead-end = stuck funds)
+- `withdraw_guard` only triggers at `Progress.current=completed` — BLOCKER (prevents premature payout)
+- `deliver_guard` validates WIP hash — recommended
+
+### 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: Permission must include `permissionIndex:1500`, bind Arbitration via `service.arbitrations.list` before publish
+
+### Rental Audit Checklist (pre-publish BLOCKERS)
+
+- `deposit_guard` validates `Order.balance ≥ deposit_amount` — BLOCKER (renter runs off with item)
+- `refund_guard` + 100% refund Allocator — BLOCKER (no refund = deposit theft)
+- `damage_guard` requires pre+post WIP hash diff — BLOCKER (no evidence = arbitrary deduction)
+- Machine has both `deposit_refunded` and `deposit_deducted` terminals — BLOCKER
+- 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
 
@@ -142,29 +160,11 @@ const educationTraits: IndustryTraits = {
 - **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
 
@@ -174,29 +174,11 @@ const travelTraits: IndustryTraits = {
 - **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 +188,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 +203,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 +220,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