@wowok/skills 1.2.4 → 1.2.6

package/wowok-machine/SKILL.md

@@ -26,7 +26,7 @@ Design, build, and operate automated workflow templates.
 
 > **Role**: Service Provider or Workflow Designer
 > **Key Tools**: `onchain_operations` with `operation_type: "machine"`
-> **Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) (Guards), [wowok-provider](../wowok-provider/SKILL.md) (Service binding), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-messenger](../wowok-messenger/SKILL.md) (privacy), [wowok-safety](../wowok-safety/SKILL.md) (safety), [wowok-tools](../wowok-tools/SKILL.md) (schema reference)
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (Service binding), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-messenger](../wowok-messenger/SKILL.md) (privacy)
 
 ---
 
@@ -36,93 +36,27 @@ Design, build, and operate automated workflow templates.
 
 Machines are **immutable after `publish: true`**; Guards are **CREATE-only**. Design the complete workflow before publishing.
 
-## Semantic Layer (Knowledge Modules)
+## MCP Knowledge Layer
 
-The Machine knowledge system provides 8 TypeScript modules that encode the canonical design knowledge for Machine generation. These modules power the L4 Harness Plan Loop and are the **source of truth** for scene/template selection, pattern matching, risk evaluation, topology analysis, and the fail-closed publish gate.
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill no longer duplicates it:
 
-> **Design reference**: [Machine Design Reference](../references/machine-design-reference.md) — covering architecture, core elements, puzzle model, translation patterns, risk rules, and publish flow. Verification notes (06 §14) are embedded in code as `MACHINE_VERIFICATION_NOTES`.
+| Content | MCP Knowledge Module | Applied Via |
+|---------|---------------------|-------------|
+| Node design rules (node type specs, forward guard design patterns, topology limits) | `knowledge/machine-risk.ts` (`MACHINE_RISK_RULES`), `machine-topology.ts`, `machine-translation.ts` | `project_operation.analyze_intent` (business puzzle) + `project_operation.aggregate_risks` (via `assessMachineRisks`) |
+| Machine scene/template selection | `knowledge/machine-ledger.ts`, `machine-templates.ts` | `project_operation.analyze_intent` |
+| Forward Guard design patterns | `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`) | `project_operation.aggregate_risks` (via `assessGuardRisks`) |
+| Safety rules (immutability, confirmation) | `knowledge/safety-rules.ts` | Pre-publish checks + `project_operation.aggregate_risks` |
+| Publish gate (4-layer fail-closed: checklist → risk → user → environment) | `knowledge/machine-confirm.ts` (`PUBLISH_CHECKLIST`, `confirmPublish`) | `project_operation.aggregate_risks` + pre-publish gate |
 
-### Module API Reference
-
-| Module | Entry Points | Purpose |
-|--------|--------------|---------|
-| `machine-ledger.ts` | `MACHINE_SCENES`, `inferSceneFromFlow(flow)`, `findScene(id)` | 10 industry scenes + keyword-based scene inference |
-| `machine-templates.ts` | `MACHINE_TEMPLATES`, `getTemplateById(id)`, `fillTemplate(id, params)`, `forkTemplate(id, overrides)`, `walkDecisionTree(answers)` | 10 starter templates + parameter fill + Q1-Q9 decision tree |
-| `machine-translation.ts` | `SEMANTIC_TO_MACHINE_RULES`, `MACHINE_CONSTRAINT_RULES`, `matchSemanticPattern(text)`, `identifyExecutionMode(threshold, fwdCount)`, `identifyTopology(pairs)`, `explainForwardPermission(fwd)` | 12 semantic patterns + 28 on-chain constraints (creation/structure/node_operation/publish/runtime) |
-| `machine-topology.ts` | `analyzeTopology(nodes, pairs)`, `identifyTopologyPattern(topology)`, `formatTopologySummary(topology)`, `MAX_NODE_COUNT=200`, `MAX_NODE_PAIR_COUNT=40`, `MAX_FORWARD_COUNT=20` | DAG analysis: entry/terminal/orphaned/dead-branch/cycle, on-chain limit checks |
-| `machine-risk.ts` | `MACHINE_RISK_RULES` (39 rules), `assessMachineRisks(machine, ctx)`, `getRiskRulesByCategory(cat)`, `getRiskSummary(assessment)` | 5 risk dimensions (R-M1 structural, R-M2 guard, R-M3 permission, R-M4 immutability, R-M5 environment) |
-| `machine-puzzle.ts` | `initPuzzleFromIntent(intent)`, `initPuzzleFromTemplate(id)`, `checkPuzzleCompleteness(puzzle)`, `recommendNextStep(puzzle)`, `derivePuzzleFromMachineJson(json)`, `generateConfirmationText(puzzle)` | 8-dimension information model (A-H): business_flow, node_design, guard_acceptance, permission_model, threshold_weight, branch_topology, overall_objective, risk_assessment |
-| `machine-confirm.ts` | `PUBLISH_CHECKLIST` (10 items C-01..C-10), `CONFIRMATION_QUESTIONS` (6 items Q1-Q6), `runStaticChecklist(machine)`, `integrateRiskAssessment(machine, ctx)`, `parseUserConfirmation(input)`, `verifyEnvironment(machine, ctx, isMainnet)`, `confirmPublish(machine, ctx, isMainnet, userInput)`, `progressiveCheck(machine, scope)`, `overrideBlockWithReason(result, reason)`, `generateFullConfirmationText(...)` | 4-layer fail-closed gate: checklist → risk → user → environment. **CRITICAL risks cannot be overridden.** |
-| `machine-context.ts` | `injectMachineContext(intent, mode, options)`, `suggestWorkflow(intent)`, `buildPromptFromContext(bundle)`, `getMachineKnowledgeSnapshot()`, `getRelatedGuardScenes(sceneId)`, `getVerificationNotes(mode?)`, `CONTEXT_PRESETS.{newUserIntent, midDesignReview, prePublishFull, crossMachine, guardIntegration, allocationIntegration}` | Aggregator module. **8 injection modes** select curated subset of knowledge based on user task. Use this as the main entry point. |
-
-### The 8 Context Injection Modes
-
-The user's current task determines what context to surface (never dump everything):
-
-| Mode | When to Use | What It Surfaces |
-|------|-------------|------------------|
-| `initial_design` | User just described intent | Matched scene + top 3 templates + initial puzzle |
-| `mid_design_review` | User is mid-design | Missing puzzle dimensions + structure/node_op constraints |
-| `pre_publish_check` | User about to publish | Full risk assessment + progressive checklist (R5 subset) + verification notes |
-| `post_publish_runtime` | Machine already published | Runtime-only constraints + environment risks |
-| `intent_match` | Lightweight intent inference | Top 2 templates + creation constraints (no verification notes) |
-| `cross_machine` | Cross-Machine dependency design | P-M-CROSS-MACHINE pattern + structure/publish constraints |
-| `guard_integration` | Deep-dive on Guard binding | Guard bridge to `guard-ledger.ts` + R-M2 risks |
-| `allocation_integration` | Deep-dive on Allocator at terminals | P-M-ALLOCATION-INTEGRATED pattern + Allocator-related risks |
-
-### Recommended Usage Pattern
-
-```typescript
-// 1. First user message — lightweight workflow suggestion
-const suggestion = suggestWorkflow(userIntent);
-// suggestion.matched_scene, suggestion.suggested_templates, suggestion.initial_puzzle, suggestion.next_step
-
-// 2. Mid-design — inject context to surface missing info
-const bundle = injectMachineContext(intent, 'mid_design_review', { existing_puzzle: puzzle });
-
-// 3. Pre-publish — full ConfirmGate
-const gate = confirmPublish(machineJson, projectContext, isMainnet, userConfirmationInput);
-if (gate.status !== 'approved') {
-    // STOP — do not call onchain_operations with publish: true
-    console.log(gate.block_reason);
-}
-
-// 4. Or use the preset wrapper for common cases
-const preset = CONTEXT_PRESETS.prePublishFull(intent, machineJson, projectContext);
-const prompt = buildPromptFromContext(preset);  // inject into AI prompt
-```
-
-### Verification Notes (06 §14)
-
-Five topics were verified at the code level. These notes are embedded in `MACHINE_VERIFICATION_NOTES` and surfaced whenever the consumer's mode touches them:
-
-| Topic | Judgment | Verified Semantic |
-|-------|----------|-------------------|
-| `bReplace` | YES | Acts at pairs-list level of an existing node (NOT whole-Machine). `false`=merge, `true`=replace that node's pairs list. |
-| `um` | PARTIAL | Messenger Contact reference (off-chain metadata). Omitting has zero on-chain impact. |
-| `consensus_repositories` | PARTIAL | Declarative-only field. Not consumed by on-chain flow. Hint for off-chain tooling. |
-| `namedOperator_assignment` | PARTIAL | Move `progress::new` does NOT accept namedOperator. MCP/SDK translates to separate `namedOperator_add` tx (permission index 221). |
-| `cross_machine_dependency` | PARTIAL | Indirect via `progress::new -> assert_published`. Use `convert_witness` TypeOrderProgress (100) / TypeOrderProgressSession (103). |
-
-> **Test coverage**: 8 `.spec.ts` files covering machine-ledger, machine-templates, machine-translation, machine-topology, machine-risk, machine-puzzle, machine-confirm, and machine-context — over 400 tests, all passing.
+This Skill keeps the **workflow conversation guidance**, **business flow design patterns**, and **machine lifecycle scripts**. The MCP layer handles node-design rule evaluation, scene/template selection, and risk aggregation.
 
 ---
 
 ## Machine Architecture
 
-```
-Machine
-└── Nodes
-    └── Pairs
-        ├── prev_node: which prior node ("" = entry point, multiple allowed)
-        ├── threshold: required total forward weight to advance
-        └── Forwards (MachineForward)
-            ├── name, weight
-            ├── permissionIndex | namedOperator: who can execute
-            └── guard (optional): condition that must pass
-```
+**Machine** → **Nodes** → **Pairs** (`prev_node` ["" = entry, multiple allowed], `threshold` [required total forward weight to advance]) → **Forwards** (`name`, `weight`, `permissionIndex` | `namedOperator` [who can execute], `guard` [optional condition]).
 
-> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_machine" } })` — all field types, limits, valid values. This document focuses on design decisions **not captured** by the schema.
+> All field types, limits, and valid values are in the MCP schema (`onchain_operations_machine`). This document focuses on design decisions **not captured** by the schema.
 
 ### Forward Permission Model
 
@@ -140,7 +74,7 @@ Machine
 
 A Guard validates the Forward's execution condition. **Retained submissions**: when `retained_submission` is set on a Guard, submitted values are stored in Progress history, uniquely located by `(current_node, next_node, forward_name)`. Later nodes query these values from history.
 
-> **Guard construction**: See [wowok-guard](../wowok-guard/SKILL.md) for table design, computation trees, and query instructions.
+> **Guard construction**: Forward Guard design patterns (table design, computation trees, query instructions) now live in the MCP knowledge layer — see `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`), auto-applied via `project_operation.aggregate_risks`. Query available Guard instructions via `wowok_buildin_info`.
 
 ### Threshold Mechanics
 
@@ -166,30 +100,19 @@ Users execute Forwards from the current node, accumulating weight within a **ses
 
 ### Dependency-First Construction
 
-Build in this exact order:
-
-```
-1. Permission (CREATE/MODIFY) → access control foundation
-2. Machine (CREATE, unpublished) → define all nodes
-3. Guards (CREATE) → build validation conditions
-4. Bind Guards to Forwards (MODIFY Machine) → set `guard` on each Forward; all operations (`add`, `set`, `add forward`) accept full `MachineForward` including `guard` + `retained_submission`
-5. Publish Machine → nodes IMMUTABLE
-6. Bind Machine to Service → workflow goes live
-```
+Build in this exact order: (1) Permission (CREATE/MODIFY) → access control foundation; (2) Machine (CREATE, unpublished) → define all nodes; (3) Guards (CREATE) → build validation conditions; (4) Bind Guards to Forwards (MODIFY Machine) → set `guard` on each Forward; all operations (`add`, `set`, `add forward`) accept full `MachineForward` including `guard` + `retained_submission`; (5) Publish Machine → nodes IMMUTABLE; (6) Bind Machine to Service → workflow goes live.
 
 **Why this order matters**: Publishing locks the Machine. Guards are immutable. Publishing before Guards are ready means Guards can never be added — the Machine is frozen without validation rules. **Create Guards, test them, then publish.**
 
 ### Node Operations (Pre-Publish Only)
 
-Nine operations are available via the `node` field. Query schema for full parameters. Key design notes not captured by schema:
+Nine operations are available via the `node` field. Key design notes not captured by schema:
 
 - `add` / `set` with `bReplace: false` (default) **merges** into existing nodes; `true` replaces all.
 - `clear` is **irreversible** — instant wipe with no undo. Export via `machineNode2file` first.
 - `exchange` swaps two node positions without delete/recreate. `rename` auto-updates all Pair references.
 - `add forward` supports the full `MachineForward` structure including `guard` with `retained_submission`.
 
-> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_machine" } })` for full operation parameters.
-
 ### File-Based Workflow
 
 ```
@@ -220,22 +143,11 @@ Two paths: **Service Order** (automatic when Order created on Service with bound
 
 Two-phase operations (`hold`/`unhold`) allow locking resources during multi-step operations; `adminUnhold` force-releases stale locks.
 
-> **Querying**: Progress state via `onchain_objects`, history via `onchain_table` / `onchain_table_item_progress_history`. Schema: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_table_data" } })`.
+> **Querying**: Progress state via `onchain_objects`, history via `onchain_table` / `onchain_table_item_progress_history`.
 
 ### Runtime: Advancing the Workflow
 
-The runtime loop (schema: `onchain_operations` with `operation_type: "progress"` or `"order"`):
-
-```
-1. Query active Forwards → onchain_objects reveals current node name and available Pairs/Forwards
-2. Execute Forward → weight accumulates in session; Guard validates (pass/fail);
-                    retained_submission stores values indexed by (current_node, next_node, forward_name)
-3. Threshold met → session commits to history (all completed Forwards recorded);
-                    node transitions; session resets; new Forwards unlocked
-4. OR threshold NOT met → session stays open; more Forwards can execute in same session;
-                          weight from repeated same Forwards ignored
-5. OR competing Pair wins first → other incomplete Pairs abandoned; next session starts on winner node
-```
+The runtime loop: (1) Query active Forwards via `onchain_objects` (reveals current node + available Pairs/Forwards); (2) Execute Forward → weight accumulates in session, Guard validates (pass/fail), `retained_submission` stores values indexed by `(current_node, next_node, forward_name)`; (3) Threshold met → session commits to history, node transitions, session resets, new Forwards unlocked; (4) Threshold NOT met → session stays open, more Forwards can execute, repeated same Forwards ignored; (5) Competing Pair wins first → other incomplete Pairs abandoned.
 
 **What the user sees**: At any node, callers can discover which Forwards are available (by querying the Machine definition and cross-referencing with their permissions). Executing a Forward that requires a Guard triggers Guard verification — the caller must submit required data. Successful Forward execution is recorded on-chain; failed Guard rejections are visible as transaction errors.
 
@@ -286,7 +198,7 @@ Decompose complex workflows into multiple Machines connected by Guard-based vali
 3. "Does any step depend on an external process completing first?"
 4. "Which party creates the sub-order, and which party verifies it?"
 
-> **Guard construction**: Cross-Machine Guards use `convert_witness` with Progress query instructions. See [wowok-guard](../wowok-guard/SKILL.md). Query available Guard instructions via `wowok_buildin_info`.
+> **Guard construction**: Cross-Machine Guards use `convert_witness` with Progress query instructions. Design rules now live in the MCP knowledge layer — see `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`), applied via `project_operation.aggregate_risks`. Query available Guard instructions via `wowok_buildin_info`.
 
 ### Dual-Signature Consensus
 
@@ -329,28 +241,10 @@ Before `publish: true`, verify:
 
 ## Guard + Machine Immutability Deadlock
 
-Both Guards and published Machines are **immutable**:
-
-```
-Guard created with bug → Cannot fix (immutable)
-  → Must create new Guard
-    → Must rebind to Machine
-      → Machine already published? Cannot modify (immutable)
-        → DEADLOCK: new Guard exists but cannot be attached
-```
+Both Guards and published Machines are **immutable**. A Guard created with a bug cannot be fixed (immutable) → must create new Guard → must rebind to Machine → but Machine already published cannot be modified (immutable) → **DEADLOCK**: new Guard exists but cannot be attached.
 
 **Prevention**: Test every Guard via `gen_passport` before binding. Verify computation tree, submission types, and query instructions against all scenarios.
 
 **If deadlocked**: Only recovery is a completely new Machine with new nodes and Guard bindings, then rebind to Service. Keep Machines unpublished until all Guards are verified.
 
----
-
-## Appendices (Progressive Disclosure)
-
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Dialogue Scripts / Onboarding Flow (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-messenger/SKILL.md

@@ -25,7 +25,7 @@ always: false
 End-to-end encrypted messaging with tamper-proof audit trails.
 
 > **Role**: Any WoWok participant
-> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "messenger_operation" } })` — all 16 operations with full parameter types and constraints. This document focuses on **design decisions and strategy** not captured by the schema.
+> All 16 operations with full parameter types and constraints are in the MCP schema (`messenger_operation`). This document focuses on **design decisions and strategy** not captured by the schema.
 > **Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) (guard design), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (WTS evidence in disputes), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-provider](../wowok-provider/SKILL.md) (service provider perspective), [wowok-safety](../wowok-safety/SKILL.md) (safety)
 
 ---
@@ -65,6 +65,14 @@ Before any communication:
 
 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.
 
+### Contact Object (On-Chain Bridge)
+
+The on-chain **Contact** object (`operation_type: "contact"`) is the bridge between a Service and Messenger: `Service.um` → Contact → `ims[]` (Messenger endpoint addresses). Customers query the Contact's `ims[]` to find where to send messages.
+
+**When to create**: Before Service publish, when `customer_required` is set (Service.um must point to a Contact). Reuse an existing Contact if you serve multiple Services with the same support channel.
+
+**Lifecycle**: Contact is mutable (unlike Proof/Guard). `im_add`/`im_remove` require permission index 453 (CONTACT_IM). No events emitted on IM mutations — poll `ims[]` field. If Contact is bound to `Permission.um` via `permission_um_set`, clear that binding BEFORE deleting the Contact (else dangling pointer). Full business guidance: [wowok-tools](../wowok-tools/SKILL.md) §"Contact (Service.um Bridge)".
+
 ---
 
 ## Daily Communication
@@ -109,12 +117,7 @@ Three independently managed lists. Schema covers all operations — here are the
 
 ## Anti-Spam Strategy
 
-The four-layer protection model evaluates every incoming message:
-
-```
-Blacklist → Friends List → Guard Verification → Stranger Rules
-   (reject)     (accept)      (accept if passport valid)    (one-message limit)
-```
+The four-layer protection model evaluates every incoming message: Blacklist (reject) → Friends List (accept) → Guard Verification (accept if passport valid) → Stranger Rules (one-message limit).
 
 This section covers **how to configure these layers intelligently** for different user profiles — configuration combinations, not just field descriptions.
 
@@ -193,15 +196,7 @@ A WTS file is a **tamper-proof, self-verifying export** of a continuous conversa
 
 ### The Workflow
 
-When a dispute requires evidence:
-
-```
-1. generate_wts  → export messages by time/messageId/seqIndex range
-2. sign_wts      → add your Falcon512 signature (both parties can sign)
-3. verify_wts    → validate hash chain, continuity, and all signatures
-4. wts2html      → (optional) convert to human-readable HTML
-5. send_file     → submit signed WTS to the arbitrator via messenger
-```
+When a dispute requires evidence: (1) `generate_wts` → export messages by time/messageId/seqIndex range; (2) `sign_wts` → add your Falcon512 signature (both parties can sign); (3) `verify_wts` → validate hash chain, continuity, and all signatures; (4) `wts2html` → (optional) convert to human-readable HTML; (5) `send_file` → submit signed WTS to the arbitrator via messenger.
 
 > **Key design decision**: Include the **full conversation** when generating WTS for arbitration — not just favorable messages. The arbitrator needs to see who said what, who acknowledged what, and the exact sequence. Selective exports undermine your credibility.
 
@@ -219,41 +214,11 @@ When a dispute requires evidence:
 
 ## Messenger Across Roles
 
-This section shows **how Messenger fits into each participant's workflow** — not detailed SOP (see the role-specific skills for complete workflows), but the Messenger-specific touchpoints.
-
-### Customer
-
-| Touchpoint | Messenger Operation | When |
-|------------|-------------------|------|
-| Pre-order inquiry | `send_message` to service provider | Before order creation — ask about service details, pricing, custom requirements |
-| Submit required info | `send_message` with delivery address, phone, etc. | After order creation — the Service's `customer_required` fields dictate what to send |
-| Track progress | `watch_messages` with provider | During order fulfillment — receive status updates |
-| Raise dispute | `generate_wts` + `sign_wts` + `send_file` to arbitrator | When resolution fails — submit evidence |
+**Customer**: Pre-order inquiry (`send_message` to provider) → submit required info (`customer_required` fields) → track progress (`watch_messages`) → raise dispute (`generate_wts` + `sign_wts` + `send_file` to arbitrator). Full workflow: [wowok-order](../wowok-order/SKILL.md).
 
-> **Full workflow**: See [wowok-order](../wowok-order/SKILL.md) for the complete customer journey.
+**Service Provider**: Monitor inquiries (`watch_conversations` with `unreadOnly` or `listFilterMode: "stranger"`) → respond to customers (reply auto-adds to friends) → request customer info → document agreements (creates evidence trail) → dispute defense (`generate_wts` + `sign_wts` + `send_file`). Full workflow: [wowok-provider](../wowok-provider/SKILL.md).
 
-### Service Provider
-
-| Touchpoint | Messenger Operation | When |
-|------------|-------------------|------|
-| Monitor inquiries | `watch_conversations` with `unreadOnly` or `listFilterMode: "stranger"` | Daily — check for new customer messages |
-| Respond to customers | `send_message` (reply auto-adds to friends) | As needed — timely response builds trust |
-| Request customer info | `send_message` asking for `customer_required` fields | After order creation if not yet provided |
-| Document agreements | `send_message` confirming terms, changes, custom work | Immediately after agreement — creates evidence trail |
-| Dispute defense | `generate_wts` + `sign_wts` + `send_file` | When a customer escalates — prove good-faith communication |
-
-> **Full workflow**: See [wowok-provider](../wowok-provider/SKILL.md) for the complete service provider journey.
-
-### Arbitrator
-
-| Touchpoint | Messenger Operation | When |
-|------------|-------------------|------|
-| Receive evidence | `watch_messages` or `watch_conversations` | When parties submit WTS files |
-| Verify evidence | `verify_wts` on received files | Before reviewing — ensure evidence integrity |
-| Communicate with parties | `send_message` for clarification requests | During dispute review |
-| Sign attestation | `sign_wts` on verified evidence | After verification — arbitrator endorses authenticity |
-
-> **Full workflow**: See [wowok-arbitrator](../wowok-arbitrator/SKILL.md) for the complete arbitration process.
+**Arbitrator**: Receive evidence (`watch_messages`/`watch_conversations`) → verify evidence (`verify_wts`) → communicate with parties (`send_message` for clarifications) → sign attestation (`sign_wts` on verified evidence). Full workflow: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
 
 ---
 
@@ -267,13 +232,3 @@ This section shows **how Messenger fits into each participant's workflow** — n
 - **Stale passports**: `passportValiditySeconds` too short causes frequent re-verification failures. Match duration to your Guard's data volatility.
 
 ---
-
-## 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-onboard/SKILL.md

@@ -24,7 +24,21 @@ when_to_use:
 
 Guides a new merchant from zero to first published Service in 10 rounds. Each round collects one core decision, calls specific MCP operations, and verifies success before advancing.
 
-> **Related Skills**: [wowok-scenario](../wowok-scenario/SKILL.md) (industry modes), [wowok-tools](../wowok-tools/SKILL.md) (MCP reference), [wowok-provider](../wowok-provider/SKILL.md) (post-onboard operations), [wowok-safety](../wowok-safety/SKILL.md) (immutability rules), [wowok-guard](../wowok-guard/SKILL.md) (Guard design), [wowok-machine](../wowok-machine/SKILL.md) (workflow design)
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (post-onboard operations), [wowok-machine](../wowok-machine/SKILL.md) (workflow design)
+
+---
+
+## MCP Knowledge Layer
+
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill no longer duplicates it:
+
+| Content | MCP Knowledge Module | Applied Via |
+|---------|---------------------|-------------|
+| Scenario mode details (per-industry Permission/Machine/Guard/Allocator defaults) | `knowledge/scenario-modes.ts` (`SCENARIO_MODES`, `matchScenarioMode`, `inferScenarioTraits`) | `project_operation.analyze_intent` — auto-applied when `industry` parameter is passed |
+| Safety rules (immutability, confirmation, object reuse) | `knowledge/safety-rules.ts` (`CONFIRMATION_RULES`) | Pre-publish checks + `project_operation.aggregate_risks` |
+| Guard / Machine design rules | `knowledge/guard-design-patterns.ts`, `machine-risk.ts` | `project_operation.aggregate_risks` |
+
+This Skill keeps the **overall onboarding flow** and **R1-R10 build order** (see below). Pass the user's industry to `analyze_intent` and the MCP layer auto-fills the scenario defaults — no need to look up per-industry presets manually.
 
 ---
 
@@ -35,7 +49,7 @@ The onboarding skill dismantles the "16 operation_type × 14 object_type" wall.
 ### What This Skill Does
 
 - Converts "I want to open a shop" into a 10-round guided build plan
-- Loads industry defaults from [wowok-scenario](../wowok-scenario/SKILL.md) to pre-fill parameters
+- Industry defaults auto-applied via `project_operation.analyze_intent` (pass `industry` parameter; defaults sourced from MCP `knowledge/scenario-modes.ts`)
 - Enforces dependency order: Permission → Service → Machine → Progress → Guard → Allocation → Order → Publish
 - Persists checkpoints after each round via `local_info_operation` so users can resume
 - Hands off to [wowok-provider](../wowok-provider/SKILL.md) once the Service is published
@@ -53,13 +67,29 @@ A published Service with: published Machine, bound Progress, validated Guards, c
 
 ---
 
-## Appendices (Progressive Disclosure)
-
-> The following sections have been extracted to [APPENDIX.md](./APPENDIX.md) for on-demand loading:
-> - Dialogue Scripts / Onboarding Flow (R1-R10) — guided conversation scripts
-> - Decision Trees — branching logic reference
-> - Failure Playbooks — recovery scenarios
-> - Tier Layering — expertise-tier based guidance
-> - Handoff Protocol — handoff triggers and packet format
->
-> Load APPENDIX.md when the user needs guided dialogue, recovery help, tier-specific guidance, or handoff context.
+## MCP 5-Stage Pipeline Integration
+
+The onboarding flow is gated by the MCP project-based 5-stage deployment pipeline. Each stage gates progression — the AI MUST honor `can_proceed: false` by stopping and fixing reported issues:
+
+| Stage | Rounds | MCP Action | Gate |
+|-------|--------|------------|------|
+| 1. Project Naming | R1-R2 | Establish `project` + `version` namespace | — |
+| 2. Business Puzzle | R2 | `analyze_intent` (pass `industry`) → ODG + missing fields + `next_step` | — |
+| 3. Risk Calibration | After R8 | `aggregate_risks` → risk assessment across all puzzles | CRITICAL risks block |
+| 4. Deployment Doc | After risks pass | `generate_deployment_doc` → deployment doc with D-01..D-18 checks | D-errors block R9 |
+| 5. Substep Trace | R9-R10 | `trace_substeps` → validate substep linkage (D-10 check) | Linkage errors block publish |
+
+## R1-R10 Build Order
+
+| Round | Object | MCP Operation | Key Decision |
+|-------|--------|---------------|--------------|
+| R1 | Account | `account_operation.gen` + `faucet` | New or reuse? |
+| R2 | Industry mode | `project_operation.analyze_intent` (pass `industry`) | Which driving mode? |
+| R3 | Service | `onchain_operations.service` CREATE | Name, type_parameter, description |
+| R4 | Permission | `onchain_operations.permission` CREATE/REUSE | Index 1000 = provider/merchant (customer uses `namedOperator:""` = OrderHolder; arbiter is NOT a Permission index — arbiters live in `Arbitration.voting_guard`) |
+| R5 | Machine | `onchain_operations.machine` CREATE | Nodes, forwards (mode defaults from MCP) |
+| R6 | Progress | `onchain_operations.progress` CREATE + bind | Mirror Machine nodes |
+| R7 | Guards | `onchain_operations.guard` CREATE + `gen_passport` test | 5 Guard templates (mode defaults from MCP) |
+| R8 | Allocation | `onchain_operations.allocation` CREATE + `service.order_allocators` | Fund split (mode defaults from MCP) |
+| R9 | Test order | `onchain_operations.order` CREATE + `progress` advance + `allocation.alloc_by_guard` | Full flow dry run |
+| R10 | Publish | `onchain_operations.machine` publish + `service` publish | Pre-publish audit must PASS |