@wowok/skills 1.2.3 → 1.2.5

package/wowok-order/SKILL.md

@@ -48,7 +48,7 @@ Allocation evaluates when Progress reaches **any** configured node (not just exi
 
 ### E1 — Service Basic Status
 
-Query `query_toolkit` → `onchain_objects` for `<service_name_or_id>`. Fields in schema. Save: `bPublished`, `bPaused`, `sales`, `machine`, `buy_guard`, `customer_required`, `arbitrations`, `compensation_fund`, `compensation_lock_duration`, `order_allocators`, `um`.
+Query `query_toolkit` → `onchain_objects` for `<service_name_or_id>`. Save: `bPublished`, `bPaused`, `sales`, `machine`, `buy_guard`, `customer_required`, `arbitrations`, `compensation_fund`, `compensation_lock_duration`, `order_allocators`, `um`.
 
 - `bPublished === false` → 🔴 **ABORT**
 - `bPaused === true` → 🔴 **ABORT**
@@ -130,7 +130,7 @@ Guard structure and instruction reference: [wowok-guard](../wowok-guard/SKILL.md
 
 ### E5 — Fund Allocation Rules
 
-From E1 `order_allocators.allocators[]`. Fields in schema. For each Allocator: cross-reference Guard (E4) → trigger condition; map to Machine node (E3) → when it fires; present distribution outcome.
+From E1 `order_allocators.allocators[]`. For each Allocator: cross-reference Guard (E4) → trigger condition; map to Machine node (E3) → when it fires; present distribution outcome.
 
 **Risk Rules**:
 
@@ -147,7 +147,7 @@ From E1 `order_allocators.allocators[]`. Fields in schema. For each Allocator: c
 
 ### E6 — Arbitration Availability
 
-Batch query E1 `arbitrations[]` via `onchain_objects`. Fields in schema. Arb process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
+Batch query E1 `arbitrations[]` via `onchain_objects`. Arb process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
 
 Also: `onchain_events` → `type: "ArbEvent"`, `limit: 20`, filter for these Arb IDs.
 
@@ -159,7 +159,7 @@ Also: `onchain_events` → `type: "ArbEvent"`, `limit: 20`, filter for these Arb
 
 ### E7 — Compensation Fund
 
-From E1: `compensation_fund`, `compensation_lock_duration`. Balance type in schema.
+From E1: `compensation_fund`, `compensation_lock_duration`.
 
 - Balance < planned order amount → ⚠️ may not cover award
 - Lock near expiry → ⚠️ provider may withdraw
@@ -168,7 +168,7 @@ From E1: `compensation_fund`, `compensation_lock_duration`. Balance type in sche
 
 ### E8 — Contact Channel
 
-Query `onchain_objects` for E1 `um` ID. Contact fields in schema.
+Query `onchain_objects` for E1 `um` ID.
 
 - `um === null` → 🔴 **ABORT**
 - `ims[]` empty → 🔴 **No Messenger**
@@ -178,7 +178,7 @@ Query `onchain_objects` for E1 `um` ID. Contact fields in schema.
 
 ### E9 — Chain Reputation
 
-**Sentiment**: `query_toolkit` → `onchain_table_item_entity_linker` for provider address. Compute likes/dislikes ratio from `votes[]` (fields in schema).
+**Sentiment**: `query_toolkit` → `onchain_table_item_entity_linker` for provider address. Compute likes/dislikes ratio from `votes[]`.
 
 **Orders**: Batch query `votes[].address` via `onchain_objects` (50/batch, max 200). Filter Order-type objects where `service` matches. Aggregate dispute rate (`dispute ≠ []` / total) and repeat buyer ratio.
 
@@ -198,28 +198,9 @@ For matched: present value, ask "correct?" and "OK to send?". For missing: ask u
 
 ### Pre-Purchase GATE
 
-```
-┌──────────────────────────────────────────────────────┐
-│              PRE-PURCHASE GATE                        │
-├──────────┬───────────────────────────────────────────┤
-│ E1       │ Service Status          [ ] OK  [ ] ⚠️    │
-│ E2       │ Product & WIP           [ ] OK  [ ] ⚠️    │
-│ E3       │ Machine Workflow        [ ] OK  [ ] ⚠️    │
-│ E4       │ Guards Logic            [ ] OK  [ ] 🔴    │
-│ E5       │ Fund Allocation         [ ] OK  [ ] ⚠️    │
-│ E6       │ Arbitration             [ ] OK  [ ] ⚠️    │
-│ E7       │ Compensation Fund       [ ] OK  [ ] ⚠️    │
-│ E8       │ Contact Channel         [ ] OK  [ ] ⚠️    │
-│ E9       │ Chain Reputation        [ ] OK  [ ] ⚠️    │
-│ E10      │ Privacy Info Match      [ ] OK  [ ] ⚠️    │
-├──────────┴───────────────────────────────────────────┤
-│ ⛔ E1 bPublished=false / E8 um=null → ABORT           │
-│ ⛔ E3 no-refund + E6 no-arb → strongly advise ABORT   │
-│ ⛔ E4 ambiguous Guards → user MUST manually review    │
-│ ⛔ Any ⚠️ → explain risk, wait for user decision      │
-│ ✅ All OK → Phase 2                                   │
-└──────────────────────────────────────────────────────┘
-```
+**Abort conditions**: E1 `bPublished=false`/`bPaused=true` → ABORT; E8 `um=null` → ABORT; E3 no-refund + E6 no-arb → strongly advise ABORT; E4 ambiguous Guards → user MUST manually review.
+
+**Any ⚠️** → explain risk, wait for user decision. **All OK** → Phase 2.
 
 ---
 
@@ -245,8 +226,6 @@ Clarify via Messenger: deliverables (E2 WIP), timeline (E3 nodes), refund/cancel
 
 ## Phase 3: Order Creation
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_service" })`. Safety: [wowok-safety](../wowok-safety/SKILL.md).
-
 **Not in schema**:
 - Excess `buy.total_pay` auto-refunded. Agents cannot withdraw.
 - Discounts: query `onchain_received` (type `0x2::service::Discount`), filter by `service`, validate time/benchmark. Rate: `total_pay × (off / 10000)`. Fixed: `min(off, total_pay)`.
@@ -257,8 +236,6 @@ Post-creation: notify via Messenger with order ID.
 
 ## Phase 4: Order Operations
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_order" })`.
-
 ### Progress Advancement
 
 When user reaches a node, AI MUST cross-reference Phase 1:
@@ -277,7 +254,7 @@ Present all three dimensions. Never just the operation name.
 
 ## Phase 5: Arbitration
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_arbitration" })`. Process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
+Process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
 
 Flow: `arbitration.dispute` → WTS evidence → Messenger → `order.arb_confirm` → voting → (`order.arb_objection`) → `order.arb_claim_compensation`.
 
@@ -287,145 +264,30 @@ Flow: `arbitration.dispute` → WTS evidence → Messenger → `order.arb_confir
 
 ## Fund Management
 
-Schema: `onchain_operations_order`. Builder-only operations: `order.transfer_to` (ownership), `order.receive` (withdraw — agents can execute, only builder receives).
+Builder-only operations: `order.transfer_to` (ownership), `order.receive` (withdraw — agents can execute, only builder receives).
 
 ---
 
-## Phase 3: Customer Intelligence (Optional Enhancement)
-
-> **When to use**: When `customer_intelligence` runtime service is enabled (default ON), the MCP server automatically populates `semantic.customer_advice` in order/query operations. This is a layer ON TOP of E1-E10 — never a replacement for due diligence.
-
-### Information Puzzle (6 dimensions)
-
-E1-E10 captures static facts. The information puzzle assembles them into a dynamic, evolving picture that gets richer with every query:
-
-| Dimension | Source | Fragments |
-|-----------|--------|-----------|
-| Service basics | E1 query | publish/pause/price/sales/WIP |
-| Workflow structure | E3 machineNode2file | nodes/forwards/user-operable/refund path |
-| Fund safety | E5 + E7 | allocators/compensation/price anomaly |
-| Trust signals | E6 + E9 | arbitration/reviews/dispute rate |
-| Merchant behavior | onchain_events | completion rate/trend/refund rate |
-| Market context | batch query_toolkit | similar services/price distribution |
-
-**Incremental collection**: Don't fetch all 6 every time. Browse = dim 1+6, Evaluate = +2/3/4, Preorder = +5, Monitoring = 2+5.
-
-### Risk Scoring (4 dimensions, 100 points)
-
-E1-E10 produces ⚠️/🔴 flags. Risk scoring converts them to a quantitative score:
-
-| Dimension | Max | Key checks |
-|-----------|-----|------------|
-| Workflow | 35 | refund path / arbitration path / user-operable / dead ends |
-| Fund | 25 | compensation coverage / allocator fairness / price anomaly / lock duration |
-| Trust | 20 | arbitration independence / dispute rate / reputation / trust score |
-| Behavior | 20 | completion trend / response time / refund rate / arb loss rate / anomalies |
-
-**Levels**: 🟢 ≥85 low | 🟡 70-84 medium-low | 🟠 50-69 medium-high | 🔴 <50 high (advise against)
-
-### User Preference Matching (7 dimensions, 100 points)
-
-When the user has 3+ historical orders, the system infers preferences and scores each Service:
-
-| Dimension | Max | What it measures |
-|-----------|-----|------------------|
-| Price | 25 | budget fit or market avg comparison |
-| Time | 15 | cycle ≤ max_acceptable_cycle |
-| Region | 10 | preferred_region match |
-| Brand | 10 | min_order_history + merchant age |
-| Bargain | 15 | reward/discount presence |
-| Emotion | 10 | after_sales_expectation + transparency |
-| Risk | 15 | risk_score ≥ min_trust_score + arb/comp requirements |
-
-**Score ≥ 75** = strong match. **< 50** = significant mismatch. The `matches`/`mismatches` arrays explain the score so you can present tradeoffs to the user.
-
-### Reminder System (6 stages, 4 priorities)
-
-Reminders are populated in `semantic.customer_advice.reminders` based on the operation stage:
+## Phase 3: Customer Intelligence (MCP-Handled)
 
-| Stage | When | Example reminders |
-|-------|------|-------------------|
-| browse | query_toolkit on Service | reviews summary / price anomaly / no arb / no comp |
-| evaluate | deeper analysis | checklist / high risk (required) / ambiguous guard (required) / no refund path |
-| preorder | order creation | payment confirm (required) / compensation insufficient / arb missing (required) |
-| in_progress | order monitoring | progress stalled / compensation drop / messenger unanswered |
-| complete | order done | review reminder / review window |
-| after_sale | post-purchase | arb window / refund received |
+> **MCP auto-populates `semantic.customer_advice`** in order/query responses when `customer_intelligence` is ON (default). Read these fields from MCP output — do NOT recompute internally.
 
-**Priority order**: `required` (blocks purchase) > `recommended` (strong caution) > `info` (advisory) > `reminder` (timed nudge). Fatigue control: max 3 high-risk reminders per response.
-
-### Game Strategy Quick Reference (8 scenarios)
-
-When the user faces a specific negotiation, refer to the strategy matrix:
-
-| Scenario | Merchant tactic | User strategy |
-|----------|------------------|---------------|
-| Info asymmetry | Hides Machine details | Demand machineNode2file export + Messenger Q&A |
-| Fund safety | No/low compensation | Require 100% coverage + WTS agreement |
-| Refund dispute | No refund path | Demand 100%→Order Allocator + Messenger terms |
-| Arb fairness | Self-built arbitration | Verify arb owner via query_toolkit |
-| Pricing | Price >120% market avg | Reference market_context.avg_price + request discount/Reward |
-| Delivery SLA | No milestone nodes | Require milestone config + written timeline |
-| Quality | WIP hash unverified | Require WIP verify + sample/staged delivery |
-| After-sales | No Messenger | Require Messenger config + written after-sales terms |
+**Key fields in `semantic.customer_advice`**:
+- `reminders[]`: stage-aware reminders with priority (`required` blocks purchase; `recommended` = strong caution; `info` = advisory; `reminder` = timed nudge)
+- `risk_score`: 0-100 (🟢≥85 low | 🟡70-84 | 🟠50-69 | 🔴<50 high — advise against purchase)
+- `preference_match`: 0-100 score with `matches`/`mismatches` arrays (≥75 strong match, <50 significant mismatch)
 
 **Red lines** (do not purchase): no arb + no refund path, OR compensation_ratio < 0.5.
 
-### Industry Personalization (6 industries)
-
-Each industry has specific risk checks and preference templates:
-
-| Industry | Cycle (days) | Response (h) | Arb | Comp | Risk appetite | Delivery |
-|----------|--------------|--------------|-----|------|---------------|----------|
-| freelance | 30 | 4 | ✓ | ✓ | balanced | normal |
-| rental | 7 | 8 | ✓ | ✓ | conservative | normal |
-| education | 90 | 24 | ✓ | ✓ | conservative | flexible |
-| travel | 14 | 2 | ✓ | ✓ | conservative | urgent |
-| subscription | 30 | 24 | – | – | aggressive | normal |
-| retail | 7 | 8 | ✓ | ✓ | balanced | normal |
-
-**Industry-specific risks**: freelance checks WIP verified + milestone nodes; rental checks compensation coverage + lock duration; travel checks urgent delivery + Messenger; subscription checks no-lockin + user-operable; etc.
-
-### Post-Purchase Support (4 phases)
-
-When the order is in progress or completed, post-purchase support covers:
-
-- **Refund tracking**: monitor refund Allocator triggers, check refunded vs order amount
-- **Quality issue**: WIP hash mismatch detection + evidence collection (≥3 items recommended)
-- **Merchant unreachable**: >3 days warning, >7 days arbitration advice (if available)
-- **Arbitration support**: evidence collection → application template → progress monitoring → result interpretation
+**Post-purchase**: monitor refund Allocator triggers, WIP hash mismatch, merchant unreachable (>3d warning, >7d arb advice), evidence collection (≥3 items).
 
-### Runtime Service Toggles
-
-Use `config_operation` to toggle Phase 3 services at runtime:
-
-| Service | Default | What it controls |
-|---------|---------|------------------|
-| `customer_intelligence` | ON | Populates `semantic.customer_advice` (reminders + risk + preference match) |
-| `order_monitor` | OFF | Active order monitoring (Progress stall + compensation change + Messenger timeout) |
-
-Toggle example: `config_operation` → `action: "toggle"`, `service: "order_monitor"` to enable active monitoring when the user has active orders.
+**Runtime toggle**: `config_operation` → `action: "toggle"`, `service: "order_monitor"` (default OFF) to enable active Progress stall + compensation change + Messenger timeout monitoring.
 
 ---
 
-## Quick Reference
-
-Schemas: `schema_query({ action: "get", name: "<name>" })` for `onchain_operations_service`, `onchain_operations_order`, `onchain_operations_arbitration`, `messenger_operation`, `query_toolkit`, `onchain_table_data`, `wip_file`.
-
 ### Phase Dependency
 
-```
-E1 (Service) ──→ E2 (Products/WIP)
-  │    │
-  │    ├──→ E8 (Contact)   ├──→ E7 (Compensation)
-  │    ├──→ E10 (Privacy)  └──→ E6 (Arbitrations)
-  │
-  └──→ E3 (Machine) ──→ E4 (Guards) ──→ E5 (Allocators)
-         │
-         └──→ E9 (Reputation)
-```
-
-> E3→E4→E5 is a strict chain. E6-E10 run in parallel after E1.
+E1 (Service) → E2 (Products/WIP), E8 (Contact), E10 (Privacy), E7 (Compensation), E6 (Arbitrations) run in parallel after E1. E3 (Machine) → E4 (Guards) → E5 (Allocators) is a strict chain. E9 (Reputation) follows E3.
 
 ### ⚠️ Critical Attention Items
 
@@ -437,14 +299,3 @@ E1 (Service) ──→ E2 (Products/WIP)
 6. **Phase 3 customer_advice** — when `customer_intelligence` is ON, read `semantic.customer_advice` first in every order/query response. The `reminders` array is pre-sorted by priority; `required` items block purchase.
 
 ---
-
-## 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
-> - Phase 3 Integration — information puzzle + risk scoring + preference matching + game strategy + post-purchase playbook
->
-> Load APPENDIX.md when the user needs guided dialogue, recovery help, or tier-specific guidance.

package/wowok-output/SKILL.md

@@ -146,13 +146,3 @@ When user asks about field meanings:
 | [wowok-messenger](../wowok-messenger/SKILL.md) | Encrypted communication |
 
 ---
-
-## 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-planner/SKILL.md

@@ -62,12 +62,31 @@ A confirmed ODG JSON document (see §ODG Data Structure) with: scenario tag, com
 
 ---
 
-## 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.
+## ODG Data Structure
+
+The ODG (Object Dependency Graph) is the single output artifact, persisted via `local_info_operation` and consumed by the Harness:
+
+```json
+{
+  "task_id": "task_20260714_001",
+  "scenario": "freelance",
+  "version": 1,
+  "status": "confirmed",
+  "account": "merchant_v1",
+  "objects": [
+    { "id": "obj_permission", "type": "permission", "status": "planned", "reversible": true, "dependencies": [], "user_decisions": { "reuse": false, "indexes": { "provider": 1000, "arbiter": 1500 } } },
+    { "id": "obj_service", "type": "service", "status": "planned", "reversible": true, "dependencies": ["obj_permission"], "user_decisions": { "name": "...", "publish": "deferred" } },
+    { "id": "obj_machine", "type": "machine", "status": "planned", "reversible": false, "dependencies": ["obj_permission"], "user_decisions": { "nodes": [...], "forwards": [...], "publish": "deferred" } }
+  ],
+  "phases": [
+    { "phase": 1, "objects": ["obj_permission"], "gate": "user_confirm" },
+    { "phase": 2, "objects": ["obj_service", "obj_machine"], "gate": "risk_check" },
+    { "phase": 3, "objects": ["obj_guard_*"], "gate": "passport_test" },
+    { "phase": 4, "objects": ["obj_allocator_*"], "gate": "allocation_audit" },
+    { "phase": 5, "objects": ["publish"], "gate": "final_audit" }
+  ],
+  "risk_assessment": { "critical": [], "warnings": [], "irreversible_count": 1 }
+}
+```
+
+Each object has: `id`, `type`, `status` (planned/created/published), `reversible` (true/false), `dependencies` (other object IDs), `user_decisions` (typed fields). Phases gate progression — `risk_check` calls `aggregate_risks`, `final_audit` calls `generate_deployment_doc` + `trace_substeps`.

package/wowok-provider/SKILL.md

@@ -22,7 +22,23 @@ when_to_use:
 # WoWok Service Provider Guide
 
 > **Role**: Service Provider (Merchant/Seller)
-> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-machine](../wowok-machine/SKILL.md) (workflow), [wowok-guard](../wowok-guard/SKILL.md) (validation rules), [wowok-messenger](../wowok-messenger/SKILL.md) (communication), [wowok-safety](../wowok-safety/SKILL.md) (safety), [wowok-tools](../wowok-tools/SKILL.md) (MCP tools)
+> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-machine](../wowok-machine/SKILL.md) (workflow), [wowok-messenger](../wowok-messenger/SKILL.md) (communication), [wowok-distill](../wowok-distill/SKILL.md) (distillation review)
+
+---
+
+## MCP Knowledge Layer
+
+The following rule tables have been pushed down to the MCP knowledge layer and are automatically applied during project operations. You do NOT need to manually check these — the MCP server enforces them.
+
+| Rule Category | MCP Knowledge Module | Applied By |
+|---------------|---------------------|------------|
+| Safety rules (confirmation, immutability, object reuse) | `knowledge/safety-rules.ts` | `aggregate_risks` + `onchain_operations` pre-publish |
+| Guard design patterns | `knowledge/guard-design-patterns.ts` | `aggregate_risks` (guard risk assessment) |
+| Machine topology rules | `knowledge/machine-risk.ts` | `aggregate_risks` (machine risk assessment) |
+| Scenario mode defaults | `knowledge/scenario-modes.ts` | `analyze_intent` (pass `industry` parameter) |
+| Tool reference (gas, faucet, wrappers) | `knowledge/tools-reference.ts` | All tool calls automatically |
+
+**How to use**: Call `project_operation` with `action: "aggregate_risks"` after completing your puzzle — the MCP server will automatically apply all relevant safety rules and return risk findings.
 
 ---
 
@@ -91,45 +107,47 @@ STEP 0: Present checklist R1-R7 to user
 Once R1-R7 confirmed, execute in strict order. All operations use R1 (Account) as `env.account`.
 
 ```
+All Tool: references below are sub-tools invoked via wowok({ tool: "<name>", data: { operation_type: "<type>", ... } })
+
 STEP 1: Foundation
 ├── Permission — REUSE existing (strongly recommended)
-│     Tool: onchain_operations (permission) | Fields: name, type_parameter
+│     Tool: "onchain_operations" (permission) | Fields: name, type_parameter
 ├── Service (unpublished) — CREATE new
-│     Tool: onchain_operations (service) | Fields: name, type_parameter, permission
+│     Tool: "onchain_operations" (service) | Fields: name, type_parameter, permission
 └── Machine (unpublished) — CREATE new or REUSE template
-      Tool: onchain_operations (machine) | Fields: nodes, pairs, forwards
-      Discovery: query_toolkit (account_list, local_mark_list, onchain_objects)
-      Template: machineNode2file (export existing for editing)
+      Tool: "onchain_operations" (machine) | Fields: nodes, pairs, forwards
+      Discovery: "query_toolkit" (account_list, local_mark_list, onchain_objects)
+      Template: "machineNode2file" (export existing for editing)
 
 STEP 2: Trust Layer
 └── Guards — CREATE new or REUSE existing
-      Tool: onchain_operations (guard) | Fields: logic, instructions
-      Template: guard2file (export existing for editing)
+      Tool: "onchain_operations" (guard) | Fields: logic, instructions
+      Template: "guard2file" (export existing for editing)
       ⚠️ Design your Guard tables based on how the target object reads data:
          - buy_guard → pass/fail only, no data extraction
          - Allocator guard → pass/fail only
          - Machine forward guard → if retained_submission is used, ensure b_submission:true entries match expected types
          - Reward guard → pass/fail only
-      Full design reference: [wowok-guard](../wowok-guard/SKILL.md)
+      Guard design patterns: MCP `knowledge/guard-design-patterns.ts` (auto-applied via `aggregate_risks`)
 
 STEP 3: Business Logic (MODIFY)
 ├── Machine — bind Guards to forwards
-│     Tool: onchain_operations (machine)
+│     Tool: "onchain_operations" (machine)
 ├── Service — set Allocators
-│     Tool: onchain_operations (service) | Fields: order_allocators
+│     Tool: "onchain_operations" (service) | Fields: order_allocators
 ├── Arbitrations (optional) — REUSE existing Arb services
-│     Tool: onchain_operations (service) | Fields: arbitrations.list
+│     Tool: "onchain_operations" (service) | Fields: arbitrations.list
 ├── Compensation Fund (optional): compensation_fund_add + setting_locked_time_add (default 30 days, configurable)
-│     Tool: onchain_operations (service)
+│     Tool: "onchain_operations" (service)
 └── Reward (optional) — incentive pools
 
 STEP 4: Publication
 ├── Publish Machine → IMMUTABLE
-│     Tool: onchain_operations (machine) | publish: true
+│     Tool: "onchain_operations" (machine) | publish: true
 ├── Bind Machine to Service
-│     Tool: onchain_operations (service) | machine: "<machine_id>"
+│     Tool: "onchain_operations" (service) | machine: "<machine_id>"
 └── Publish Service → machine/allocators LOCKED
-      Tool: onchain_operations (service) | publish: true
+      Tool: "onchain_operations" (service) | publish: true
 
       ⚠️ Pre-Publish Verification:
       1. Re-check PRE-FLIGHT: all R1-R7 still confirmed?
@@ -163,8 +181,7 @@ STEP 5: Post-Publish (MODIFY Service — mutable after publish)
 
 ### Service Object Relationships
 
-> **Authoritative source**: [Object Collaboration Diagram](../references/object-collaboration.md) §1 (22-object collaboration DAG, 83 relationships).
-> This tree is a simplified view. Cross-reference the above for the full graph and [Object Boundary Conditions](../references/object-collaboration.md#boundary-conditions) for mutability rules.
+> **Boundary conditions**: Use MCP `project_operation` with action `get_reversibility` to query the full 22-object lifecycle reversibility matrix (mutability, prerequisites, capacity limits, irreversibility). Key rules: Service/Machine are IMMUTABLE after publish; Payment is FROZEN at creation; Order/Progress/Arbitration operations are irreversible.
 
 ```
 Service (merchant storefront)
@@ -187,10 +204,10 @@ Order (per purchase, runtime-created)
 ├── arbitration → Arbitration (optional, immutable once set)
 └── allocation → Fund distribution engine (triggered via Progress.forward)
 
-Cross-object references (see [Object Collaboration Diagram §6](../references/object-collaboration.md#guard-and-machine-global-usage) for Guard/Machine global usage):
+Cross-object references:
 - Guard is referenced by 9 object types (Service.buy_guard, Machine.forward.guard, Allocation.allocation_guard, Arbitration.voting_guard, Reward.claim_guard, Repository.write_guard, Treasury.external_guard, Demand.recommend_guard, Passport.guard)
 - Machine is referenced by 4 object types (Service.machine, Order.machine, Progress.machine, Order snapshot)
-- Permission is the central hub — 11 objects hold BuiltinPermissionIndex (see [Object Collaboration Diagram §5](../references/object-collaboration.md#permission-reverse-reference-table) for reverse-reference table)
+- Permission is the central hub — 11 objects hold BuiltinPermissionIndex
 ```
 
 ### Allocators + Machine Integration
@@ -233,7 +250,7 @@ Each `sharing[].who` field determines where funds go. Choose the correct type ba
 After the Progress reaches a terminal state, the fund allocation is NOT automatic — it must be triggered explicitly. **Anyone can call this operation**; the caller does not need to be the merchant or customer. The Guard verification determines which allocator's rules apply.
 
 ```
-Tool: onchain_operations (allocation)
+Tool: wowok({ tool: "onchain_operations", data: { operation_type: "allocation", ... } })
 Operation: alloc_by_guard
 Required submission: Order ID (matching the Guard's b_submission identifier)
 ```
@@ -249,8 +266,8 @@ Required submission: Order ID (matching the Guard's b_submission identifier)
 Immutable product commitment for arbitration evidence.
 
 ```
-Create:  wip_file → generate → markdown_text + images → outputPath
-Attach: onchain_operations (service) → sales.sales[{
+Create:  wowok({ tool: "wip_file", data: { op: "generate", ... } }) → markdown_text + images → outputPath
+Attach: wowok({ tool: "onchain_operations", data: { operation_type: "service", ... } }) → sales.sales[{
           name, price, stock, wip: "<URL>", wip_hash: "" (auto)
         }]
 ```
@@ -262,41 +279,66 @@ Attach: onchain_operations (service) → sales.sales[{
 
 ---
 
-## Order Fulfillment
+## Project Iteration: Fork vs In-Place
 
-| Object | Purpose | Operation |
-|--------|---------|-----------|
-| Order | Fund escrow | Read-only |
-| **Progress** | Workflow state | **Operate this** — `hold: true` (lock) → work → `hold: false` (submit) |
+When a merchant wants to modify an existing service (change workflow, add allocators, update guards), the AI must determine whether to modify the current version (in-place) or fork a new version.
 
-**AI Reminder**: When fulfilling, check `customer_required` fields. Missing → prompt via Messenger.
+### Decision Rule
 
----
+| Scenario | Strategy | MCP Action |
+|----------|----------|------------|
+| Service NOT yet published | **In-place** — modify the current version directly | `onchain_operations` (modify) |
+| Service IS published | **Fork** — create a new version, preserve original as read-only | `project_operation` → `fork_project` |
+
+### Fork Workflow
 
-## Quick Reference
+When the service is already published and the user wants structural changes, use MCP `project_operation` action `fork_project` (creates a new version with copies of stage.json/manifest/deployment docs; original v1 stays read-only; no on-chain objects copied since they're immutable). Then work on v2 using the normal 5-stage flow, reusing v1 on-chain objects by address and creating new objects only for changed parts. Publish v2 when ready — v1 continues running uninterrupted.
 
-| Purpose | Schema |
-|---------|--------|
-| Service ops | `onchain_operations_service` |
-| Machine ops | `onchain_operations_machine` |
-| Guard ops | `onchain_operations_guard` |
-| Progress ops | `onchain_operations_progress` |
-| WIP generation | `wip_file` |
-| Messenger | `messenger_operation` |
-| Query | `query_toolkit` |
+Before forking, verify necessity via `get_reversibility` (query_object_type: "service", query_lifecycle_state: "published") → `struct_reversible="immutable"` confirms fork is required, or `get_project_status` → `has_published_object=true`.
 
-**Export**: `machineNode2file`, `guard2file` | **Query Schema**: `schema_query({ action: "get", name: "<name>" })`
+### When to Recommend Forking
+
+- User says "I want to change my workflow" → check if published → recommend fork
+- User says "I want to add a new product line" → if same Machine can handle it, in-place modify Service.sales; if needs new Machine, fork
+- User says "I want to change fund distribution" → if Service not published, in-place; if published, fork (allocators are frozen after publish)
 
 ---
 
+## Distillation Review
+
+The MCP server runs an offline flywheel that collects operational signals from your deployments and generates improvement proposals. Periodically review these proposals to optimize your service.
+
+### When to Review
+
+- After publishing a service and running it for a while
+- When the user asks "any improvements?" or "what did the system learn?"
+- As part of routine service maintenance
+
+### How to Review
+
+Use the [wowok-distill](../wowok-distill/SKILL.md) skill for guided review, or call MCP `project_operation` actions directly in order: (1) `get_improvement_queue` with `queue_filter_status: "pending"` to list proposals (title, priority, confidence, description); (2) `apply_improvement` with `proposal_id` + `review_status: "approved"` or `"rejected"` — approved proposals write overrides to `~/.wowok/overrides/` (config) or `patches/` (source); (3) `get_flywheel_config` to verify `applied_count` increased and `pending_count` decreased. Overrides are hot-loaded — next operation uses the new config immediately.
+
+### Override Categories
+
+Only these categories can be overridden (no arbitrary changes):
+
+| Category | What It Controls | Example |
+|----------|-----------------|---------|
+| risk-thresholds | Risk assessment cutoffs | max_retries, min_deposit |
+| descriptions | AI guidance text | industry descriptions |
+| industry-profiles | Industry trait profiles | rental traits, freelance traits |
+| scenario-defaults | Default parameters per scenario | default allocators, machine nodes |
+| recovery-priorities | Error recovery order | which failures to fix first |
+
 ---
 
-## Appendices (Progressive Disclosure)
+## Order Fulfillment
 
-> 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.
+| Object | Purpose | Operation |
+|--------|---------|-----------|
+| Order | Fund escrow | Read-only |
+| **Progress** | Workflow state | **Operate this** — `hold: true` (lock) → work → `hold: false` (submit) |
+
+**AI Reminder**: When fulfilling, check `customer_required` fields. Missing → prompt via Messenger.
+
+---