@wowok/skills 1.1.5 → 1.1.7

package/README.md

@@ -170,6 +170,7 @@ const providerSkill = getSkillByName('wowok-provider');
 | `wowok-messenger` | Encrypted messaging (E2E communication, WTS evidence, conversation management) | All Roles | On-demand |
 | `wowok-guard` | Guard design mastery (programmable trust rules) | All Roles | On-demand |
 | `wowok-machine` | Machine workflow design (state machines, progress tracking) | Service Provider | On-demand |
+| `wowok-output` | Output processing (address resolution, name mapping, amount formatting) | All Roles | Always |
 | `wowok-tools` | MCP tool usage mastery (13 tools, schema references) | All Roles | Always |
 | `wowok-safety` | Safety protocol (dry-run → confirm → execute) | All Roles | Always |
 

package/dist/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,WAAW,EAAE,WA0EzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAEnC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,EAAE,CAExE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CA4B5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,CAyBvD"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,eAAO,MAAM,WAAW,EAAE,WAkFzB,CAAC;AAEF;;GAEG;AACH,wBAAgB,SAAS,IAAI,KAAK,EAAE,CAEnC;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAE9D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,EAAE,CAExE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,EAAE,CA4B5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,CAyBvD"}

package/dist/skills.js

@@ -77,7 +77,7 @@ exports.wowokSkills = {
         },
         {
             name: 'wowok-tools',
-            description: 'MCP tool usage mastery — query_toolkit, onchain_operations, messenger_operation, schema_query, and all 13+ tools with correct parameter formats. ALWAYS loaded for all roles.',
+            description: 'MCP tool usage mastery — query_toolkit, onchain_operations, messenger_operation, schema_query, and all 13 tools with correct parameter formats. ALWAYS loaded for all roles.',
             version: '1.0.0',
             role: 'shared',
             loading: 'always',
@@ -91,6 +91,14 @@ exports.wowokSkills = {
             loading: 'always',
             related: ['wowok-tools']
         },
+        {
+            name: 'wowok-output',
+            description: 'Output processing — post-processes all WoWok tool responses for human-readable presentation. Handles address resolution, name mapping, amount formatting, and data visualization. ALWAYS loaded for all roles.',
+            version: '1.0.0',
+            role: 'shared',
+            loading: 'always',
+            related: ['wowok-tools']
+        },
         {
             name: 'wowok-guard',
             description: 'Guard design mastery — programmable trust rules, multi-signature authorization, guard2file export/import. Used by providers and arbitrators for complex validation logic.',

package/dist/skills.js.map

@@ -1 +1 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/wowok-arbitrator/SKILL.md

@@ -4,7 +4,7 @@ description: |
   WoWok Arbitrator — build and operate on-chain arbitration services.
   Create Arbitration objects, configure voting rules (open or guard-based weighted),
   manage dispute cases through their full lifecycle, and earn fees from resolution.
-  
+
   Core value: achieve trust consensus between merchants and users through
   transparent, fair, and efficient dispute resolution.
 when_to_use:
@@ -18,7 +18,55 @@ when_to_use:
 
 Build trust through fair dispute resolution. Arbitration services enable neutral third parties to resolve conflicts between customers and merchants, earning fees while establishing on-chain reputation.
 
-> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer disputes), [wowok-provider](../wowok-provider/SKILL.md) (service arbitration config), [wowok-guard](../wowok-guard/SKILL.md) (voting_guard design), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange)
+> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer disputes), [wowok-provider](../wowok-provider/SKILL.md) (service arbitration config), [wowok-guard](../wowok-guard/SKILL.md) (voting_guard design), [wowok-machine](../wowok-machine/SKILL.md) (workflow analysis), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange), [wowok-safety](../wowok-safety/SKILL.md) (safety)
+
+---
+
+## ⚠️ PRE-FLIGHT: Required Items Checklist
+
+**THIS SECTION IS MANDATORY.** Before ANY arbitration service creation, the AI MUST collect explicit user confirmation for EVERY required item. **Do NOT skip, do NOT fabricate, do NOT proceed with missing items.**
+
+### The Golden Rule
+
+```
+NEVER guess the user's fee model, voting structure, or Guard design.
+These are BUSINESS and GOVERNANCE decisions that ONLY the user can make.
+
+User hasn't provided it → ASK.
+User provides incomplete info → ASK for clarification.
+User says "just make something up" → REFUSE and explain why each item matters.
+```
+
+### Required Items
+
+| # | Item | User Must Provide | Why Not Fabricate |
+|---|------|-------------------|--------------------|
+| **R1** | **Account** | Which account to operate from. Default `""` is fine. | Safe default exists |
+| **R2** | **Arbitration Name** | Service name. What kind of arbitration? | Your brand and reputation on-chain |
+| **R3** | **Fee** | How much per case? (e.g. "10 WOW per dispute") | IS your revenue model — you cannot guess pricing |
+| **R4** | **Voting Guard(s)** | Who votes and with what weight? Open voting (centralized) or Guard-based (decentralized)? | ⛔ Guards are **immutable after creation** — wrong design = create replacement Guard |
+| **R5** | **Usage Guard** | Who can file disputes? Public or restricted? | Controls your case volume and quality |
+| **R6** | **Contact (um)** | Messenger Contact name/ID for evidence exchange | Without this, customers cannot submit evidence — service is broken |
+
+### Information Collection Protocol
+
+```
+STEP 0: Present checklist R1-R6 to user
+├── Each item: "Reuse or create new? Provide details."
+├── Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]
+└── ⛔ GATE: ALL R1-R6 must be [confirmed] before any on-chain action
+    └── NOT confirmed → STOP. Ask. Do NOT suggest creating arbitration.
+```
+
+All subsequent on-chain operations use R1 (Account) as `env.account`.
+
+### Anti-Fabrication Rules (HARD Constraints)
+
+| Never... | Because... |
+|----------|------------|
+| Invent a fee amount | You don't know their pricing strategy |
+| Assume usage_guard logic | You don't know their target audience |
+| Skip the checklist | Arbitration design decisions are on-chain and visible |
 
 ---
 
@@ -39,9 +87,11 @@ Neither party can force outcome unilaterally — the design forces collaboration
 
 ### Arb State Machine
 
+Customer dispute creates Arb directly at (1). State (0) entered only via `reset`.
+
 | State | Available Operations | Next State |
 |-------|---------------------|------------|
-| **(0) Principal_confirming** | Customer (via Order): `arb_confirm` | → (1) |
+| **(0) Revision Pending** | Customer (via Order): `arb_confirm` | → (1) |
 | **(1) Arbitrator_confirming** | Arbitrator: `confirm` → (2), `reset` → (0), feedback | → (2) or (0) |
 | **(2) Voting** | Arbitrator: vote, set deadline, `arbitration` → (3), feedback | → (3) |
 | **(3) Arbitrated** | Customer (via Order): `arb_objection` → (4), `arb_claim_compensation` → (5) | → (4) or (5) |
@@ -67,7 +117,9 @@ Neither party can force outcome unilaterally — the design forces collaboration
 | `usage_guard` | Who can file disputes | Public vs invitation-only |
 | `um` | Contact for evidence exchange | Messenger addresses for WTS verification |
 
-**Start paused** (`pause: true`). Configure everything before accepting disputes.
+**⚠️ Start paused** (`pause: true`). **Forgetting to unpause = all disputes silently rejected with no error.** Complete all configuration — fee, guards, um — before unpausing.
+
+**⚠️ Guard Immutability**: Once a Guard is created, its rules **cannot be modified**. If your `voting_guard` design is wrong, you must create a replacement Guard and reconfigure the Arbitration — wasteful but not fatal. Test with `gen_passport` before finalizing.
 
 ### Voting Modes
 
@@ -81,54 +133,34 @@ Neither party can force outcome unilaterally — the design forces collaboration
   - `FixedValue(u32)`: Equal weight for all qualified voters
   - `GuardIdentifier(u8)`: Dynamic weight from credential (e.g., reputation score, token balance)
 - Max 50 guards — enables tiered voting (experts + community, token-holders + NFT-holders)
+- **Guard table design**: When using `GuardIdentifier`, the referenced index must be a `b_submission: true` entry of **numeric type** (U8–U256). Its value is cast to u32 as the voter's weight. The `name` field of that entry should explain its purpose to Passport applicants.
 
 **Voting Flow**: Voter selects a voting guard → System verifies voter's Passport against that guard → Calculates weight based on guard's rule → Applies weight to selected propositions. One vote per voter per case.
 
+> **Guard Design Reference**: Voting guards follow the same construction as all Guards. See [wowok-guard](../wowok-guard/SKILL.md) for table design, computation trees, and the full type requirements by object.
+
 ---
 
 ## Phase 2: Handle Cases
 
 ### Case Lifecycle
 
-**1. Arrival** (`dispute` by customer)
-- Arb created in state (1)
-- Fee locked in `arb.fee`
-- Customer's propositions recorded
-
-**2. Review** — Two paths:
-
-| Path | Condition | Action | Result |
-|------|-----------|--------|--------|
-| **Proceed** | Propositions clear, evidence sufficient | `confirm` + `voting_deadline` | → Voting (2) |
-| **Revise** | Ambiguous claims, insufficient evidence | `reset` + feedback | → Principal_confirming (0) |
+| # | Step | State | Action |
+|---|------|-------|--------|
+| 1 | **Arrival** | (1) | Arb created via customer `dispute`. Fee locked, propositions recorded. |
+| 2 | **Review** ⚠️ | (1) | `confirm` (proceed) or `reset` (send back). **Insufficient → MUST reset.** |
+| 3 | **Voting** | (2) | Vote, set `voting_deadline` (≤ 3 days). Max 520 voters. |
+| 4 | **Finalize** ⛔ | (2)→(3) | `arbitration`: sets `feedback` + `indemnity`. **Irreversible** by arbitrator. |
+| 5 | **Resolution** | (3) | Customer: `arb_claim_compensation` → (5), or `arb_objection` → (4). |
+| 6 | **Objection** | (4) | Only `reset` → (0) for revision. |
+| 7 | **Withdraw** | (5)/(3)/(4) | Finished: **immediate**. Others: ⛔ **30-day mandatory wait**. |
 
-**Best Practice**: Use `reset` proactively. A revision cycle is faster than a flawed arbitration followed by objection.
+**Reset feedback channels**:
 
-**3. Voting** (state 2)
-- Votes accumulate on propositions
-- Voters can change votes (old votes replaced)
-- Max 520 voters per case
-
-**4. Finalization** (`arbitration` operation)
-- Sets `feedback` (reasoned decision)
-- Sets `indemnity` (compensation amount, 0 = provider wins)
-- Requires deadline passed (if set)
-- → Arbitrated (3)
-
-**5. Resolution** — Customer chooses (via Order operations):
-
-| Choice | Action | Result |
-|--------|--------|--------|
-| **Accept** | `arb_claim_compensation` | → Finished (5), fee withdrawable |
-| **Object** | `arb_objection` | → Objectionable (4) |
-
-**6. Objection Handling**
-- Only action: `reset` → back to (0) for revision
-- Forces collaborative resolution — no override mechanism
-
-**7. Fee Withdrawal**
-- From Finished: Immediate
-- From Arbitrated/Objectionable: 30-day wait (protects customer rights)
+| Channel | Use | Visibility |
+|---------|-----|------------|
+| **Messenger** (preferred) | Specific evidence, privacy-sensitive | Encrypted, off-chain |
+| **on-chain feedback** | General clarification, procedural | Public, permanent |
 
 ---
 
@@ -154,63 +186,32 @@ Customer pays fee
 
 Arbitrator sets `indemnity` → Customer claims via `order.arb_claim_compensation` → Funds transfer from `service.compensation_fund` to Order.
 
-**Key Principle**: Arbitrator decides amount, provider's fund pays it. This aligns incentives — providers have reason to avoid disputes, arbitrators have reason to be fair.
-
-> See [wowok-order](../wowok-order/SKILL.md) for customer-side arbitration operations.
+> **Note**: The compensation payout comes from the **provider's** compensation_fund, not the arbitrator's funds. Customers should assess the provider's fund balance before purchase — this is covered in [wowok-order](../wowok-order/SKILL.md) Phase 1.1.
 
 ---
 
-## Integration Patterns
+## Integration
 
-### Evidence Workflow (Messenger)
+### Evidence (Messenger)
 
 1. Customer queries Arbitration's `um` → gets Messenger addresses
 2. Customer sends WTS evidence files (encrypted, off-chain)
-3. Arbitrator verifies WTS authenticity (`messenger_operation` with `verify_wts`)
+3. Arbitrator verifies WTS authenticity (`verify_wts`)
 4. Only verified evidence considered valid
 
-**Why WTS**: Cryptographically proves communication history without on-chain exposure.
-
-### Guard Relationships
-
-| Guard | Purpose | Effect |
-|-------|---------|--------|
-| `usage_guard` | Access control | Must satisfy to file dispute |
-| `voting_guard` | Authentication + weight | Must satisfy to vote; weight from rule |
+**⚠️ `um` must be configured before unpausing** — without it customers cannot submit evidence.
 
-**Design Principle**: `usage_guard` = yes/no gate; `voting_guard` = credential-verified weighted participation.
-
-### Service Provider Integration
+### Service Provider
 
 Providers list approved Arbitrations in their Service. Customers choose from this list when disputes arise.
 
-**Trust Flywheel**: Fair arbitrators get listed by more providers → more cases → more revenue → stronger reputation → more provider listings.
-
 ---
 
 ## Design Principles
 
-### Fairness Mechanisms
-
-1. **Separated Powers**: Arbitrator cannot force acceptance; customer cannot force ruling
-2. **Revision Cycles**: `reset` enables correction without penalty
-3. **Objection Rights**: Customer always retains right to contest
-4. **Transparent Rules**: All voting logic on-chain, verifiable
-5. **Timed Withdrawal**: 30-day wait protects customer claim rights
-
-### Efficiency Mechanisms
-
-1. **State Machine**: Clear progression, no ambiguity about next steps
-2. **Weighted Voting**: Credential-based influence reduces voter spam
-3. **Deadline Enforcement**: Optional time-boxing prevents indefinite delays
-4. **Fee Incentive**: Arbitrator earns per case, motivated to resolve
-
-### Trust Building
-
-1. **On-Chain Reputation**: Past rulings (`feedback`) are public and permanent
-2. **Consistent Standards**: Apply uniform criteria across similar cases
-3. **Reasoned Decisions**: Detailed `arbitration.feedback` explains logic
-4. **Professional Response**: Monitor Messenger, verify WTS promptly
+- **Fairness**: Separated powers (neither side can force outcome), revision cycles (`reset`), customer objection rights, transparent on-chain rules, 30-day withdrawal protection.
+- **Efficiency**: Clear state machine, weighted voting to reduce spam, deadline enforcement, fee incentive for timely resolution.
+- **Trust**: ⚠️ Feedback is permanently public — be reasoned and professional. Apply consistent standards. Monitor Messenger, verify WTS promptly.
 
 ---
 
@@ -221,34 +222,24 @@ Providers list approved Arbitrations in their Service. Customers choose from thi
 | Operation | State | Purpose |
 |-----------|-------|---------|
 | `confirm` | (1)→(2) | Start voting, set deadline |
-| `reset` | (1)→(0), (4)→(0) | Request revision |
+| `reset` | (1)→(0), (4)→(0) | Request revision (requires feedback) |
 | `vote` | (2) | Cast weighted votes |
-| `arbitration` | (2)→(3) | Finalize with indemnity |
-| `arb_withdraw` | (5), (3), (4) | Extract fee to balance |
+| `arbitration` | (2)→(3) | Finalize verdict (**irreversible**) |
+| `arb_withdraw` | (5), (3), (4) | Extract fee (30-day wait if not finished) |
 
 ### Common Workflows
 
-**Standard Resolution**:
-```
-Dispute → Review → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
-```
-
-**With Revision**:
-```
-Dispute → Reset → arb_confirm → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
-```
-
-**With Objection**:
-```
-Dispute → Confirm → Vote → Finalize → arb_objection → Reset → arb_confirm → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
-```
+See [Core Architecture > Key Flows](#arb-state-machine) above.
 
 ### Critical Constraints
 
 - Max 20 propositions per case
 - Max 520 voters per case
 - Max 50 voting guards per Arbitration
-- 30-day withdrawal wait for non-finished cases
+- ⛔ 30-day withdrawal wait for non-finished cases (mandatory, cannot bypass)
+- ⛔ Guard is **immutable after creation** — test before finalizing
+- ⛔ `arbitration` verdict is **irreversible** by arbitrator — only customer can object
+- ⛔ `feedback` is **permanently public on-chain** — use Messenger for privacy-sensitive communication
 
 ### Schema Access
 
@@ -262,18 +253,21 @@ schema_query({ action: "get", name: "messenger_operation" })
 
 ## Best Practices
 
-1. **Configure before unpause**: Fee, contact, voting rules ready first
-2. **Reset proactively**: Unclear case? Send back immediately
-3. **Verify all evidence**: Use `verify_wts` before evaluating
-4. **Write detailed feedback**: Your on-chain reputation
-5. **Set fair indemnity**: Proportional to order value and dispute nature
-6. **Test guards first**: Use `gen_passport` to verify voting_guard logic
-7. **Monitor compensation funds**: Warn if provider fund insufficient for indemnity
+1. **Configure before unpause**: Fee, contact, voting rules ready first. ⚠️ Unpause is the last step.
+2. **Reset proactively**: Unclear case? Send back immediately with clear feedback (Messenger preferred for privacy).
+3. **Verify all evidence**: Use `verify_wts` before evaluating — unverified evidence is not evidence.
+4. **Write detailed feedback**: Your on-chain reputation is permanent. Be professional, reasoned, and fair.
+5. **Set fair indemnity**: Proportional to order value and dispute nature.
+6. **Test guards first**: Use `gen_passport` to verify voting_guard logic before deployment.
+7. **Set reasonable deadlines**: Suggest ≤ 3 days for voting — balances efficiency with thoroughness.
 
 ### Common Pitfalls
 
-- **Paused Arbitration**: Silently rejects disputes — remember to unpause
-- **Past deadline**: Set future timestamps only
-- **Empty reset feedback**: Explain why revision needed
-- **Early withdrawal**: Wait for Finished state or 30-day timer
-- **Unverified evidence**: Always verify WTS before using
+| Pitfall | Consequence | Prevention |
+|---------|------------|------------|
+| **Paused Arbitration** | All disputes silently rejected | Verify `pause: false` after configuration |
+| **Wrong Guard design** | Must create replacement Guard | Test with `gen_passport` before creating |
+| **Past deadline** | Vote cannot be finalized | Set future timestamps only |
+| **Empty reset feedback** | Customer doesn't know what to fix | Always provide feedback on reset |
+| **Early withdrawal** | Funds locked for 30 days if not finished | Wait for Finished state |
+| **Unverified evidence** | Ruling based on invalid claims | Always verify WTS first |

package/wowok-guard/SKILL.md

@@ -6,7 +6,7 @@ description: |
   the trust layer for Services (buy_guard), Arbitration (voting_guard weight,
   usage_guard), Machines (forward validation), Demands (recommendation filtering),
   Rewards (claim eligibility), and Repositories (write validation with data extraction).
-  Guards also enable off-chain use cases: generate a Passport via `gen_passport` to
+  Guards also enable off-chain use cases: generate a Passport via `onchain_operations` (`operation_type: "gen_passport"`) to
   obtain a signed, time-bound credential for off-chain permission verification.
 when_to_use:
   - User wants to create or modify a Guard
@@ -22,13 +22,8 @@ when_to_use:
 # WoWok Guard Design Reference
 
 > **Role**: Service Provider, Arbitrator, or any builder needing programmable on-chain validation
-> **Prerequisites**: Understand CREATE vs MODIFY pattern — Guards are CREATE-only; once deployed on-chain their logic is frozen forever
-> **Machine Integration**: See [wowok-machine](../wowok-machine/SKILL.md) for how Guards attach to workflow node forwards
-> **Service Provider**: See [wowok-provider](../wowok-provider/SKILL.md) for buy_guard, allocator guards, and reward guard configuration
-> **Customer Order Operations**: See [wowok-order](../wowok-order/SKILL.md) for Guard submissions during Progress advancement and the arbitration dispute process from the customer's perspective
-> **Arbitrator Operations**: See [wowok-arbitrator](../wowok-arbitrator/SKILL.md) for voting_guard and usage_guard configuration, vote organization, and the full Arb case lifecycle from the arbitrator's perspective
-> **Messenger**: See [wowok-messenger](../wowok-messenger/SKILL.md) for encrypted evidence exchange
-> **Tools**: See [wowok-tools](../wowok-tools/SKILL.md)
+> **Prerequisites**: Guards are CREATE-only; frozen on-chain once deployed  
+> **Related Skills**: [wowok-machine](../wowok-machine/SKILL.md) (forward guards), [wowok-provider](../wowok-provider/SKILL.md) (buy_guard, allocator guards), [wowok-order](../wowok-order/SKILL.md) (guard submissions), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (voting_guard, usage_guard), [wowok-messenger](../wowok-messenger/SKILL.md) (encrypted evidence), [wowok-safety](../wowok-safety/SKILL.md) (naming, confirmation), [wowok-tools](../wowok-tools/SKILL.md) (tool reference)
 
 ---
 
@@ -58,9 +53,9 @@ Every Guard is built from three layers, each with a distinct role:
 
 **The root is the question**: It must return Bool. Intermediate nodes return numbers, strings, addresses, or vectors. Guard is **strongly typed** — the type system is strictly enforced at creation time. Type mismatches (e.g., passing a string to a numeric comparison node) will cause validation errors and prevent Guard creation.
 
-**The rely is composition**: Up to 4 dependent Guards. When `rely.logic_or` is false (default), all dependencies must pass. When true, any dependency passing is sufficient. This lets you build complex validation from simple, tested components. A Guard can only depend on Guards that are themselves standalone (`immutable: true` and `rep: true`) — no circular or transitive dependency chains.
+**The rely is composition**: Up to 4 dependent Guards. When `rely.logic_or` is false (default), all dependencies must pass (AND). When true, any passing is sufficient (OR). A Guard can only depend on Guards with `rep: true` — `rep` is the Guard's internal flag indicating it has no external Repository dependency and can serve as a dependency. Guards with `rep: false` cannot appear in `rely` lists. Violations are caught by the contract layer at creation time.
 
-### 4. Where Guards Attach in the Ecosystem
+### Where Guards Attach in the Ecosystem
 
 Guards are not standalone — they plug into other WoWok objects as validation rules. Understanding these integration points is essential because the **context** of the Guard determines what data is available to it and what happens when it fails.
 
@@ -108,11 +103,24 @@ Every Guard answers these questions:
 | "Vote weight equals reputation score" | Dynamic weight | GuardIdentifier extracts numeric value from Passport | Table needs numeric submission entry at referenced index. Guard validates eligibility AND weight range |
 | "Only premium members can file disputes" | Membership verification | Entity registration or tier check | `query` on ENTITY_REGISTRAR_ADDRESS or Repository. Combine entity existence check with tier comparison via `logic_and` |
 
+### Quick Decision: What Guard Pattern Fits?
+
+```
+Identity check?      → context(Signer) + logic_equal (single address) / vec_contains_address (allowlist)
+Time constraint?     → context(Clock) + calc_number_* comparisons
+External data?       → query + table entry declaring target object address
+Progress state?      → query_progress_history_find + convert_witness
+One-time claim?      → query_reward_record_count + logic_equal(0)
+Dynamic weight?      → GuardIdentifier + numeric table entry (b_submission: true)
+External Repository? → query + table entry declaring Repository address
+Entity reputation?   → query + table entry declaring ENTITY_REGISTRAR_ADDRESS(0xaab) / ENTITY_LINKER_ADDRESS(0xaaa)
+```
+
 ### Design Before Building
 
-The Guard design process is entirely upfront. There is no "draft" or "edit" phase after creation. Design thoroughly before calling the create operation:
+**Design thoroughly before calling the create operation** — there is no edit phase after creation (see The Immutability Contract above).
 
-1. **Query available query instructions first**: Before designing any Guard that queries on-chain data, use `wowok_buildin_info` with query `"guard queries"` to retrieve the complete list of available query instructions. Each query has a specific ID, name, parameters, and return type — you MUST verify these details before constructing your Guard. Never guess query instruction names or parameter types.
+1. **Query available query instructions first**: Before designing any Guard that queries on-chain data, use `wowok_buildin_info` with info `"guard instructions"` to retrieve the complete list of available query instructions. Each query has a specific ID, name, parameters, and return type — you MUST verify these details before constructing your Guard. Never guess query instruction names or parameter types.
 2. List every data dependency — what must the caller provide? What constants are baked in?
 3. Sketch the logic tree — what comparisons, arithmetic, and logical combinations produce the final boolean?
 4. Verify types — does every comparison receive compatible operands? Are all conversions explicit?
@@ -130,7 +138,7 @@ The Guard table is the **complete declaration of information** the Guard consume
 |-------|---------|---------------|
 | `identifier` | Unique index (0–255). The computation tree uses this number to reference the entry. | Always |
 | `b_submission` | Whether the **caller** must provide this value at runtime. `true` = runtime submission; `false` = pre-set constant. | Always |
-| `value_type` | The type of the value: Bool, Address, String, U8–U256, or vector types. Uses numeric type codes (use `wowok_buildin_info` with query `"value types"` for the complete mapping). | Always |
+| `value_type` | The type of the value: Bool, Address, String, U8–U256, or vector types. Uses numeric type codes (use `wowok_buildin_info` with info `"value types"` for the complete mapping). | Always |
 | `value` | The constant value when `b_submission` is false; a placeholder when `b_submission` is true. | When `b_submission` is false |
 | `name` | Human-readable label describing what this entry represents. | Always |
 
@@ -141,7 +149,9 @@ The Guard table is the **complete declaration of information** the Guard consume
 - **Non-submission entries must have a value.** These are baked into the Guard immutably.
 - **Submission entries use placeholder values.** The actual value is provided by the caller at runtime.
 - **Query target objects must be of type Address in the table.** Their `object_type` field should match the expected query target type (Progress, Order, Machine, Reward, etc.).
+- **Querying EntityRegistrar or EntityLinker requires system address table entries.** Add entries for `ENTITY_REGISTRAR_ADDRESS` (`0xaab`) or `ENTITY_LINKER_ADDRESS` (`0xaaa`) to the table as Address-type constants when your query instruction targets these global registries. Without them, creation fails.
 - **Maximum 256 table entries** (identifiers 0–255). The total serialized table size must not exceed 40000 bytes.
+- **Submission entries must have descriptive `name` values.** For `b_submission: true` entries, `name` is the contract between Guard and caller — it tells callers what data they must provide. Use natural language that explains the purpose and necessity: "The order ID that identifies the target Order for verification" not `"order_id"`, "The signer's account address that will be compared against the authorized list" not `"addr"`. This is critical because callers see only this name when submitting data.
 
 ### The convert_witness Mechanism
 
@@ -150,26 +160,14 @@ The Guard table is the **complete declaration of information** the Guard consume
 **Core principle**: Caller submits what they have (e.g., Order ID); Guard queries what it needs (e.g., Progress state) via witness conversion.
 
 **Rules**:
-- Witness type encodes source→target transformation (e.g., `100` = Order→Progress)
+- Witness type encodes source→target transformation
 - Table entry's `object_type` must match witness source type
 - Query instruction's object type must match witness target type
 - Type mismatches cause Guard creation to fail
 
-**Available Witness Types**:
+**Available witness types** are defined in the schema — query `wowok_buildin_info` with info `"guard instructions"` for the complete list with use cases.
 
-| Witness Type | Value | Source → Target | Use Case |
-|--------------|-------|-----------------|----------|
-| TypeOrderProgress | 100 | Order → Progress | Check if order has reached a specific workflow node (e.g., 'complete') before allowing reward claims |
-| TypeOrderMachine | 101 | Order → Machine | Verify the workflow structure or check node configurations |
-| TypeOrderService | 102 | Order → Service | Validate the service offering details or check service-level configurations |
-| TypeProgressMachine | 103 | Progress → Machine | Access workflow definition from a Progress context |
-| TypeArbOrder | 104 | Arb → Order | In arbitration voting guards, verify order details like payment amount or service ID |
-| TypeArbArbitration | 105 | Arb → Arbitration | Access arbitration configuration or fee settings from within an Arb case |
-| TypeArbProgress | 106 | Arb → Progress | Check order workflow state during arbitration validation |
-| TypeArbMachine | 107 | Arb → Machine | Access workflow definition for dispute context analysis |
-| TypeArbService | 108 | Arb → Service | Verify service terms or compensation fund status during arbitration |
-
-**Example**: To validate that an order has reached the 'complete' node, query the Order with `convert_witness=100` (TypeOrderProgress) and check the Progress's `current_node` field.
+**Notable**: `TypeArbArbitration (105)`: Arb and Arbitration are **different on-chain objects**. The witness queries the Arbitration (parent service) from an Arb (case) address — the binding is set when Arbitration creates the Arb. Schema describes this as "access arbitration configuration or fee settings."
 
 ---
 
@@ -181,7 +179,6 @@ The root tree is a computational expression whose terminal nodes read data and w
 
 - **Type safety is enforced at creation time.** Every node validates that its children return types compatible with its operation. A `logic_equal` node that receives a String child and a U64 child will fail validation.
 - **Evaluation order is stack-based.** Children are evaluated in reverse, so the first child in the array appears at the top of the evaluation stack.
-- **The root must return Bool.** Logic and comparison nodes produce Bool. Arithmetic nodes produce numbers. Conversion nodes produce the target type. Ensure your outermost node is a logic or comparison type.
 - **Every `identifier` node's index must exist in the table.** This is validated at creation time.
 
 ### Discovering Available Node Types
@@ -199,7 +196,7 @@ This returns the complete `GuardNodeSchema` definition — every node type, its
 
 **Key principle**: Every node declares its return type and the types it expects from children. The schema enforces these constraints at Guard creation time — type mismatches cause creation to fail. All numeric comparisons normalize to U256, enabling cross-type comparisons without explicit conversion.
 
-**Query instructions**: For the `query` node, discover available instructions via `wowok_buildin_info` with query `"guard instructions"`. Use the `filter` parameter to narrow results by name, return type, parameter count, or object type — more effective than browsing raw ID ranges.
+**Query instructions**: For the `query` node, discover available instructions via `wowok_buildin_info` with info `"guard instructions"`. Use the `filter` parameter to narrow results by name, return type, parameter count, or object type — more effective than browsing raw ID ranges.
 
 ---
 
@@ -211,6 +208,10 @@ Guard creation is a **single atomic operation** — it either succeeds (the Guar
 
 Use `onchain_operations` with `operation_type: "guard"`.
 
+**Two creation modes**:
+- `root.type: "node"` — build the computation tree directly in the operation payload.
+- `root.type: "file"` — load the tree from a `guard2file`-exported JSON/Markdown file. Use this to iterate on existing Guards: export → edit file → create new Guard from file.
+
 **Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_guard" })`
 
 ---
@@ -221,9 +222,9 @@ Use `onchain_operations` with `operation_type: "guard"`.
 
 Before embedding a Guard into a live Machine, Service, or Arbitration, test it in isolation.
 
-**Tool**: `gen_passport`
+**Tool**: `onchain_operations` with `operation_type: "gen_passport"`
 
-**Schema Reference**: `schema_query({ action: "get", name: "gen_passport" })`
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_gen_passport" })`
 
 This tool verifies one or more Guards and, on success, generates an immutable Passport — a verified credential stored on-chain. Use it to:
 
@@ -232,12 +233,32 @@ This tool verifies one or more Guards and, on success, generates an immutable Pa
 
 The Passport itself is useful beyond testing — it serves as a reusable on-chain credential for offline verification, transaction condition checking, and multi-guard validation. A single Passport can satisfy multiple Guards in a single transaction.
 
+**Multi-Guard behavior**: When verifying multiple Guards, they are AND-ed — all must pass for the Passport to be generated. Each Guard's submission is passed independently.
+
+**Optional `info` field**: If you omit `info` (submission data), the system attempts to auto-fetch existing submissions from the Guard. Provide `info` explicitly when testing with custom inputs.
+
+**Passport query**: Once generated, query the Passport object via `query_toolkit` → `onchain_objects` to inspect its data, validated Guards, and timestamp.
+
 ### Query On-Chain Guards
 
 **Tool**: `query_toolkit` with `query_type: "onchain_objects"`
 
 Guards are **public consensus**. Once bound to objects (Service, Machine, Arbitration), they become the trusted executor of rights and obligations. All parties can inspect the exact validation rules — this transparency is the foundation of trustless interaction. Query Guards before engaging with any protected operation.
 
+Query results include `_guard_node_comments` — human-readable annotations for each computation node automatically injected by the system. Use these to quickly verify that the Guard's logic matches the intended design without manually decoding the node tree.
+
+### Guard Iteration Workflow
+
+Guards are immutable but iterable. The full cycle:
+
+```
+1. guard2file <existing_guard> → JSON/Markdown file
+2. Edit file (table, root tree, rely)
+3. Review edited JSON with user → confirm
+4. onchain_operations(guard) with root.type="file" → new Guard created
+5. Update all references (Machine forwards, Service buy_guard, Arbitration voting_guard, etc.)
+```
+
 ---
 
 ## Guard Data Flow: How Objects Read Guard Data
@@ -258,12 +279,24 @@ Machine's forward `guard` validates state transitions. If `retained_submission`
 
 ### Repository: Policy Write Guard with Data Extraction
 
-Repository's `write_guard` validates writes. If `id_from_submission` is set, reads entity ID from that submission index; if `data_from_submission` is set, reads data value from that index. Guard table must include entries for the data being extracted.
+Repository's `write_guard` validates writes. If `id_from_submission` is set, reads entity ID from that submission index — **the index must be Address type**. If `data_from_submission` is set, reads data value from that index — **the value type must match the Repository's declared value_type**. Guard table must include entries for the data being extracted.
 
 ---
 
 **Key Principle**: Design your Guard table based on what data the target object needs to read. Objects don't just validate — they consume Guard submissions as structured data inputs.
 
+### Type Requirements by Object
+
+Each object extracts Guard data with precise type expectations. Mismatches cause creation or runtime failure:
+
+| Object | Extraction Field | Table Index Requirement | Type Constraint |
+|--------|-----------------|------------------------|-----------------|
+| **Arbitration** `voting_guard` | Vote weight via `GuardIdentifier(u8)` | Index must be `b_submission: true` | **Numeric** (U8–U256, cast to u32) |
+| **Demand** `ServiceGuard` | `service_identifier` mapping | Index must be `b_submission: true` | Depends on Service validation |
+| **Machine** Forward | `retained_submission` | Index must be `b_submission: true`; uniquely located by `node→next_node→forward` triple | As declared in table |
+| **Repository** | `id_from_submission` | Index must be `b_submission: true` | **Must be Address** |
+| **Repository** | `data_from_submission` | Index must be `b_submission: true` | **Must match Repository's value_type** |
+
 ---
 
 ## Best Practices
@@ -274,7 +307,7 @@ Repository's `write_guard` validates writes. If `id_from_submission` is set, rea
 
 2. **Type mismatches in comparison nodes**: A `logic_equal` comparing a String to a U64 fails validation. Use explicit conversion nodes (`convert_string_number`, `convert_number_string`) when types differ. Numeric comparisons use `logic_as_u256_*` variants which auto-widen to U256.
 
-3. **Wrong query instruction IDs or parameter counts**: Query instructions are system-defined. Always discover them through `wowok_buildin_info` with `"guard instructions"`. The parameter count and types in your query node must match the instruction exactly — off-by-one parameter counts are a common failure.
+3. **Wrong query instruction IDs or parameter counts**: Query instructions are system-defined. Always discover them through `wowok_buildin_info` with info `"guard instructions"`. The parameter count and types in your query node must match the instruction exactly — off-by-one parameter counts are a common failure.
 
 4. **Missing convert_witness**: When accessing Progress data from an Order ID in the table, the query node needs `convert_witness` with the appropriate witness type. Without it, the runtime looks for a Progress at the Order's address — which does not exist as a Progress object. The creation-time validation catches this mismatch.
 
@@ -284,7 +317,7 @@ Repository's `write_guard` validates writes. If `id_from_submission` is set, rea
 
 7. **Root not returning Bool**: The outermost node of the tree must produce Bool. Logic and comparison nodes return Bool; arithmetic, conversion, and string operation nodes do not. Ensure your tree terminates at a logic or comparison node — the creation validation will reject non-Bool roots.
 
-8. **Dependency on non-standalone Guards**: A Guard's `rely` entries must reference Guards that are themselves standalone (`immutable: true` and `rep: true`). Guards with their own dependencies cannot be used as dependencies for others — this is a strict no-transitive-dependency rule.
+8. **Dependency on non-standalone Guards**: A Guard's `rely` entries must reference Guards with `rep: true` — meaning they have no external Repository dependency. Guards that depend on a Repository (`rep: false`) cannot serve as dependencies. The contract layer catches violations at creation time.
 
 9. **Forgetting voting_guard weight type validation**: When using `GuardIdentifier`, the referenced identifier must exist in the guard's table and its value type must be numeric. The system checks this when the VotingGuard is added to the Arbitration — if the identifier does not exist or is non-numeric, the operation reverts with `E_GUARD_IDENTIFIER_NOT_NUMBER`.
 
@@ -296,10 +329,10 @@ Repository's `write_guard` validates writes. If `id_from_submission` is set, rea
 
 | Tool | Purpose |
 |------|---------|
-| `wowok_buildin_info` (`query: "guard instructions"`) | Discover all available query instructions — their IDs, parameter types, return types, and target object types |
-| `wowok_buildin_info` (`query: "value types"`) | Discover the numeric codes for all supported value types used in table entries |
-| `wowok_buildin_info` (`query: "built-in permissions"`) | Discover all built-in permission index codes for use with `permission.entity.perm has` queries |
-| `gen_passport` | Test Guard validation with runtime submissions and generate a verified on-chain credential on success |
+| `wowok_buildin_info` (`info: "guard instructions"`) | Discover all available query instructions — their IDs, parameter types, return types, and target object types |
+| `wowok_buildin_info` (`info: "value types"`) | Discover the numeric codes for all supported value types used in table entries |
+| `wowok_buildin_info` (`info: "built-in permissions"`) | Discover all built-in permission index codes for use with `permission.entity.perm has` queries |
+| `onchain_operations` (`operation_type: "gen_passport"`) | Test Guard validation with runtime submissions and generate a verified on-chain credential on success |
 | `guard2file` | Export an existing Guard's complete definition (description, table, root tree, dependencies) to a local JSON or Markdown file |
 | `query_toolkit` (`query_type: "onchain_objects"`) | Query any Guard object on-chain by name or address to inspect its full definition |
 | `schema_query` (`name: "onchain_operations_guard"`) | Retrieve the complete Guard operation schema with all parameter definitions |