@wowok/skills 1.2.3 → 1.2.5

package/wowok-safety/APPENDIX.md

@@ -1,561 +0,0 @@
-# Appendix — wowok-safety
-
-> This file is loaded on-demand (Progressive Disclosure).
-> Main skill: [SKILL.md](./SKILL.md)
-
----
-
-## Dialogue Scripts (R1-R10)
-
-A guided 10-round dialogue for the safety verification journey — runs before ANY on-chain write operation. Each round has a specific AI Goal, Key Questions, Tool Calls, Success Criteria, Fallback, and Checkpoint. Checkpoints persist via `local_info_operation` so the verification can resume after interruption.
-
-> **Trigger**: This dialogue is automatically invoked when the user requests an on-chain write operation (transfer, publish, create, modify, etc.). It is the safety gate that all writes must pass through.
-
-### R1 — Operation Intent Capture
-
-**AI Goal**: Understand exactly what operation the user wants to perform, which objects are involved, and on which network. Classify the operation as LOCAL, ON-CHAIN, or QUERY to determine the required safety checks.
-
-**Key Questions**:
-- What operation do you want to perform? (transfer, publish, create, modify, etc.)
-- Which objects are involved? (names, IDs, or types)
-- Which network? (testnet default, or mainnet)
-- Which account? (default `""` or a specific account)
-
-**Tool Calls**:
-1. Classify the operation: LOCAL (`account_operation`, `local_mark_operation`, `local_info_operation`) / ON-CHAIN (`onchain_operations`, `messenger_operation` some ops, `wip_file` sign) / QUERY (read-only).
-2. If QUERY → no safety gate needed, proceed directly.
-3. If LOCAL → minimal safety checks (no gas, no confirmation).
-4. If ON-CHAIN → full safety gate (R2-R10).
-5. `local_info_operation` → create a session checkpoint `{ round: R1, operation_type, objects, network, account, classification }`.
-
-**Success Criteria**: Operation classified correctly. All involved objects identified. Network and account confirmed.
-
-**Fallback**: User provides vague intent ("transfer some funds") → ask for specific amount, token, and recipient. User doesn't know the network → default to testnet, inform user. User doesn't specify an account → use default `""`.
-
-**Checkpoint**: Persist `{ round: R1, operation_type, objects: [...], network, account, classification: LOCAL|ONCHAIN|QUERY }`. Mark R1 COMPLETE.
-
-### R2 — Account & Network Verification
-
-**AI Goal**: Verify the account exists and has sufficient balance for the operation. Confirm the network matches the objects' chain.
-
-**Key Questions**:
-- Confirm: account `<address>` on `<network>`. Correct?
-- Does the account have sufficient balance for gas and the operation amount?
-
-**Tool Calls**:
-1. `account_operation` → `get` to confirm the account exists.
-2. `query_toolkit` → `onchain_objects` for the account object. Check balance.
-3. If balance insufficient → inform user, suggest faucet (`account_operation` → `faucet` on testnet).
-4. `local_info_operation` → persist account verification.
-
-**Success Criteria**: Account exists. Balance sufficient for gas + operation amount. Network confirmed.
-
-**Fallback**: Account not found → guide through `account_operation` → `gen`. Balance insufficient → suggest faucet (testnet) or fund the account (mainnet). Wrong network → warn user, switch via `env.network`.
-
-**Checkpoint**: Persist `{ round: R2, account_verified: true, balance_sufficient: true, network_confirmed: true }`. Mark R2 COMPLETE.
-
-### R3 — Object Reuse vs Create Decision
-
-**AI Goal**: For each object involved in the operation, determine whether to reuse an existing object (string reference) or create a new one (object shape). Apply the Object Reuse Principle.
-
-**Key Questions**:
-- For each object: do you have an existing one to reuse, or do you need to create new?
-- If reusing: provide the name or ID.
-- If creating: confirm the need for a new object.
-
-**Tool Calls**:
-1. For each object the user wants to reuse: `query_toolkit` → `onchain_objects` to verify it exists and is owned by the account.
-2. Confirm the CREATE vs MODIFY pattern:
-   - String `"<name>"` or `"<0x...>"` → REUSE existing.
-   - Object `{ name?, ... }` → CREATE new.
-3. For Permission objects: strongly recommend reuse (centralized control).
-4. For Arbitration objects: always reuse (customers choose established arbiters).
-5. `local_info_operation` → persist the reuse/create decision per object.
-
-**Success Criteria**: Each object has a clear reuse/create decision. Reused objects verified to exist. Created objects confirmed as necessary.
-
-**Fallback**: User wants to reuse but object doesn't exist → SDK will throw `GetObjectExisted()` error. Either create new or correct the name/ID. User wants to create but an equivalent object exists → recommend reuse to reduce management overhead.
-
-**Checkpoint**: Persist `{ round: R3, objects: [{name, decision: reuse|create, verified: bool}] }`. Mark R3 COMPLETE.
-
-### R4 — Permission & Guard Pre-Check
-
-**AI Goal**: Verify the account has the required Permission indices for the operation. If Guards are involved, verify the user can satisfy them (or has a valid passport).
-
-**Key Questions**:
-- Does the operation require specific Permission indices?
-- If Guards are involved: can you satisfy the conditions? Do you have a valid passport?
-
-**Tool Calls**:
-1. `query_toolkit` → `onchain_objects` for the Permission object. Check the account's role/indices.
-2. For Machine forwards: verify the `namedOperator` and Guard requirements per [wowok-machine](../wowok-machine/SKILL.md).
-3. If a Guard is required and user needs a passport: `onchain_operations` → `gen_passport`.
-4. `guard2file` to export and review the Guard logic if unclear.
-5. `local_info_operation` → persist permission and guard verification.
-
-**Success Criteria**: Account has required Permission indices. Guards are satisfiable (or passport obtained). No permission denied errors expected.
-
-**Fallback**: Permission denied → check the object's Permission configuration. User lacks the required index → request the permission holder to grant access. Guard cannot be satisfied → flag the blocker, consider alternative path or hand off to [wowok-guard](../wowok-guard/SKILL.md) for redesign.
-
-**Checkpoint**: Persist `{ round: R4, permission_verified: true, guard_requirements: [...], passport_obtained: bool }`. Mark R4 COMPLETE.
-
-### R5 — Amount & Token Verification
-
-**AI Goal**: Verify all amounts in the operation are correct. Query token decimals — never assume. Confirm amounts are submitted as U64 integers.
-
-**Key Questions**:
-- What is the amount and token for this operation?
-- Do you know the token's decimals? (I will query to verify.)
-- Confirm: `<human_readable_amount>` = `<u64_integer>`?
-
-**Tool Calls**:
-1. `query_toolkit` → `token_list` to get the token's `decimals` and `symbol`.
-2. Calculate: `u64_amount = human_amount × (10 ^ decimals)`.
-3. Present both: "2 WOW = 2000000000 (U64, 9 decimals)".
-4. Verify the operation submits the U64 integer, not the human-readable string.
-5. For multi-token operations: verify each token's decimals independently.
-6. `local_info_operation` → persist amount verification.
-
-**Success Criteria**: Token decimals queried (not assumed). Amount converted to U64 integer. User confirmed both human-readable and U64 amounts.
-
-**Fallback**: Token decimals cannot be queried → HALT the amount submission. Alert the user. Do not proceed with hardcoded or guessed precision. User specifies "2 WOW" → submit `2000000000`, not the string "2 WOW".
-
-**Checkpoint**: Persist `{ round: R5, token: {symbol, decimals}, human_amount, u64_amount, verified: true }`. Mark R5 COMPLETE.
-
-### R6 — Export & Review (Publish Operations Only)
-
-**AI Goal**: For publish operations (Service, Machine), export and review the definitions before publishing. Warn about immutability — many fields become locked after publish.
-
-**Key Questions**:
-- Ready to review the Guard and Machine definitions before publishing?
-- Are you aware that after publish, many fields become immutable?
-- Have you tested all Guard conditions and Machine transitions?
-
-**Tool Calls**:
-1. `guard2file` to export all Guard definitions.
-2. `machineNode2file` to export all Machine node definitions.
-3. Review the exported files with the user. Confirm logic matches intent.
-4. Warn about immutability: list which fields become locked after publish.
-5. `local_info_operation` → persist the export review.
-
-**Success Criteria**: All Guards and Machine nodes exported and reviewed. User confirms logic matches intent. User acknowledges immutability constraints.
-
-**Fallback**: Export fails → check file format and schema compliance. User finds a logic error → fix before publishing (after publish, must create replacement objects). User is unsure about logic → hand off to [wowok-guard](../wowok-guard/SKILL.md) or [wowok-machine](../wowok-machine/SKILL.md) for detailed review.
-
-**Checkpoint**: Persist `{ round: R6, guards_exported: [...], machine_exported: bool, reviewed: true, immutability_acknowledged: true }`. Mark R6 COMPLETE. (Skip if not a publish operation.)
-
-### R7 — Immutability Warning & User Confirmation
-
-**AI Goal**: Present the final operation preview. For irreversible operations (publish, arbitration verdict, transfer), obtain explicit user confirmation. Use the confirmation template.
-
-**Key Questions**:
-- Here is the operation preview. Proceed?
-- Are you aware this operation is irreversible? (if applicable)
-- For amount-sensitive operations: confirm the amount and recipient.
-
-**Tool Calls**:
-1. Render the confirmation template:
-   ```
-   📋 Operation Preview
-   | Field | Value |
-   |-------|-------|
-   | Operation | {operation_type} — {op} |
-   | Object | {object_name} |
-   | Network | {network} |
-   | Account | {account} |
-   ⚠️ This will {describe_what_will_happen}
-   Proceed with execution?
-   ```
-2. For publish: add the publish confirmation warning.
-3. For transfers: display amount with token symbol (from R5).
-4. Wait for explicit user confirmation ("yes", "proceed", "confirm").
-5. `local_info_operation` → persist the confirmation.
-
-**Success Criteria**: Operation preview rendered. User explicitly confirmed. For irreversible operations, user acknowledged irreversibility.
-
-**Fallback**: User says "no" or hesitates → abort, ask for clarification. User says "maybe" → explain the operation in more detail, re-confirm. User asks to modify → return to the relevant R round for the change.
-
-**Checkpoint**: Persist `{ round: R7, confirmation_template_rendered: true, user_confirmed: true, irreversible_acknowledged: bool }`. Mark R7 COMPLETE.
-
-### R8 — Two-Phase Submission (Call Without Submission)
-
-**AI Goal**: Execute the first phase of the two-phase submission loop. Call the operation WITHOUT `submission` — the SDK returns a prompt confirming the operation details.
-
-**Key Questions**:
-- Ready to submit the operation? I will first call without submission to verify.
-- Does the SDK prompt match our expectations?
-
-**Tool Calls**:
-1. `onchain_operations` (or relevant tool) with the assembled operation, WITHOUT `submission`.
-2. SDK returns a prompt confirming the operation details.
-3. Verify the prompt matches R1-R7 expectations.
-4. If prompt is unexpected → diagnose (wrong object, wrong amount, wrong account).
-5. `local_info_operation` → persist the SDK prompt.
-
-**Success Criteria**: SDK prompt received and matches expectations. Operation is ready for the second phase (with submission).
-
-**Fallback**: SDK returns an error → diagnose: wrong object name, insufficient gas, permission denied, Guard validation failure. SDK prompt doesn't match → re-verify R1-R7, correct the issue. `GetObjectExisted()` error → the string reference couldn't be resolved; either create new or correct the name.
-
-**Checkpoint**: Persist `{ round: R8, sdk_prompt_received: true, prompt_matches: true }`. Mark R8 COMPLETE.
-
-### R9 — Execute with Submission
-
-**AI Goal**: Execute the second phase of the two-phase submission loop. Call the operation WITH `submission` to execute it on-chain.
-
-**Key Questions**:
-- Confirm: execute the operation on-chain? This is the final step.
-- (For publish) Reminder: after this, the object is publicly accessible and many fields are immutable.
-
-**Tool Calls**:
-1. `onchain_operations` (or relevant tool) with the same operation AND `submission`.
-2. SDK executes the transaction on-chain.
-3. Capture the transaction digest and result.
-4. `query_toolkit` → `onchain_objects` to verify the result (new object created, balance updated, state changed).
-5. `local_info_operation` → persist the transaction digest and result.
-
-**Success Criteria**: Transaction executed on-chain. Digest captured. Result verified via query.
-
-**Fallback**: Transaction fails → check the error: Guard validation failure (review Guard logic and submitted data), insufficient gas (add more), permission denied (check Permission indices), object not found (verify name/ID with `no_cache: true`). Transaction succeeds but result is unexpected → query with `no_cache: true` to bypass cache lag.
-
-**Checkpoint**: Persist `{ round: R9, tx_digest, result: success|failure, verified: true }`. Mark R9 COMPLETE.
-
-### R10 — Post-Operation Verification & Handoff
-
-**AI Goal**: Verify the operation's outcome. Confirm the on-chain state matches expectations. Hand off to the next workflow with a clean state.
-
-**Key Questions**:
-- The operation is complete. Would you like to verify the result?
-- What's your next operation? (hand off to the appropriate Skill)
-
-**Tool Calls**:
-1. `query_toolkit` → `onchain_objects` with `no_cache: true` for the affected objects.
-2. `onchain_events` → check for relevant events (NewOrderEvent, ProgressEvent, ArbEvent, etc.).
-3. Confirm the state change matches expectations.
-4. `local_info_operation` → write the final verification and handoff packet.
-5. Recommend next Skills based on the operation type:
-   - After `service.buy` → [wowok-order](../wowok-order/SKILL.md) for order operations.
-   - After `service.publish` → [wowok-provider](../wowok-provider/SKILL.md) for merchant operations.
-   - After `arbitration.create` → [wowok-arbitrator](../wowok-arbitrator/SKILL.md) for case management.
-   - After `guard.create` → [wowok-guard](../wowok-guard/SKILL.md) for binding.
-   - After `machine.create` → [wowok-machine](../wowok-machine/SKILL.md) for publish.
-
-**Success Criteria**: On-chain state verified. Events checked. Handoff packet written. Next Skill recommended.
-
-**Fallback**: State doesn't match expectations → check with `no_cache: true` (cache lag). If still wrong → diagnose: transaction may have partially failed, or a Guard blocked a sub-operation. User wants to undo → for most operations, impossible (immutable); for some, a reverse operation exists (e.g., `transfer_to` for ownership).
-
-**Checkpoint**: Persist `{ round: R10, state_verified: true, events_checked: true, handoff_emitted: true, next_skill: <recommended> }`. Mark safety verification COMPLETE.
-
----
-
-## Decision Trees
-
-### D1: Object Reuse vs Create
-
-```
-For each object involved in the operation:
-├── Does an equivalent object already exist?
-│   ├── YES (user provides name/ID)
-│   │   ├── Verify via query_toolkit → onchain_objects
-│   │   │   ├── Exists and owned by account → REUSE (string reference)
-│   │   │   ├── Exists but owned by another → Cannot reuse. CREATE new.
-│   │   │   └── Does not exist → Name typo or never created. CREATE new.
-│   │   └── Object type matters:
-│   │       ├── Permission → STRONGLY recommend reuse (centralized control)
-│   │       ├── Arbitration → ALWAYS reuse (established arbiters)
-│   │       ├── Machine → Reuse if workflow fits
-│   │       ├── Guard → Reuse if logic matches
-│   │       └── Contact → Reuse if same customer service point
-│   └── NO (no equivalent exists)
-│       └── CREATE new (object shape { name?, ... })
-├── SDK enforcement:
-│   ├── String "<name>" or "<0x...>" → GetObjectExisted() resolves
-│   │   ├── Resolution succeeds → REUSE
-│   │   └── Resolution fails → Hard error. Fix name or switch to CREATE.
-│   └── Object { name?, ... } → Always creates new
-└── replaceExistName flag (for name collisions):
-    ├── false (default) → Throws error if name in use (safe)
-    └── true → Steals name from existing object (development only)
-```
-
-### D2: Confirmation Level Required
-
-```
-What level of confirmation does this operation need?
-├── Operation type:
-│   ├── QUERY (read-only) → No confirmation needed
-│   ├── LOCAL (account_operation, local_mark, local_info) → No confirmation needed
-│   ├── ON-CHAIN write (modify, create) → Standard confirmation (R7 template)
-│   ├── Amount-sensitive (transfer, payment, reward) → AMOUNT VERIFICATION required
-│   │   ├── Query token decimals (never assume)
-│   │   ├── Convert to U64 integer
-│   │   ├── Display both human-readable and U64
-│   │   └── Explicit user confirmation
-│   ├── Publish (Service, Machine) → PUBLISH CONFIRMATION required
-│   │   ├── Export and review (guard2file, machineNode2file)
-│   │   ├── Warn about immutability
-│   │   └── Explicit user confirmation
-│   └── Irreversible (arbitration verdict, transfer) → DOUBLE CONFIRMATION
-│       ├── First: standard R7 template
-│       └── Second: "Are you absolutely sure? This cannot be undone."
-├── Amount threshold (user-configurable):
-│   ├── Small (< 1 WOW) → Standard confirmation
-│   ├── Medium (1-100 WOW) → Standard + amount display
-│   └── Large (> 100 WOW) → Explicit verbal confirmation + amount display
-└── Network:
-    ├── testnet → Standard confirmation (low risk)
-    └── mainnet → Heightened confirmation (real funds)
-```
-
-### D3: LOCAL vs ON-CHAIN vs QUERY
-
-```
-Classifying the operation:
-├── LOCAL ONLY (no gas, no confirmation)
-│   ├── account_operation (gen, get, faucet, messenger, etc.)
-│   ├── local_mark_operation
-│   └── local_info_operation
-├── ON-CHAIN (gas required, confirmation required)
-│   ├── onchain_operations (all 16 operation_types)
-│   ├── messenger_operation (some ops — sign, proof_message)
-│   └── wip_file (sign)
-├── QUERY (read-only, no gas, no confirmation)
-│   ├── query_toolkit
-│   ├── onchain_table_data
-│   ├── onchain_events
-│   ├── guard2file
-│   ├── machineNode2file
-│   └── wowok_buildin_info
-└── ENCRYPTED (local encryption, no gas)
-    └── messenger_operation (watch/send messages — local ops)
-```
-
-### D4: Publish Readiness Check
-
-```
-Before publishing a Service or Machine:
-├── Have all Guards been created and tested?
-│   ├── YES → continue
-│   └── NO → STOP. Create and test Guards first (gen_passport).
-├── Has the Machine been created and nodes exported?
-│   ├── YES → machineNode2file export reviewed
-│   └── NO → STOP. Create Machine first.
-├── Has the Permission object been configured with required indices?
-│   ├── YES → continue
-│   └── NO → STOP. Machine forwards reference Permission indices.
-├── Have all mutable fields been finalized?
-│   ├── YES → continue
-│   └── NO → STOP. After publish, many fields are immutable.
-├── Has the Contact (um) been configured?
-│   ├── YES → continue
-│   └── NO → STOP. Customers need a contact channel.
-├── Has the compensation_fund been funded (for Services)?
-│   ├── YES → continue
-│   └── NO → Warn. Fund may be insufficient for arbitration awards.
-├── Are you on the correct network?
-│   ├── testnet → OK for testing
-│   └── mainnet → DOUBLE CHECK. Real users, real funds.
-└── All checks pass → Proceed with publish confirmation (R7).
-```
-
-### D5: Error Recovery Path
-
-```
-An operation failed. What's the error?
-├── Guard validation failure
-│   ├── Review Guard's rule tree via guard2file
-│   ├── Check submitted data values
-│   ├── Re-submit with corrected data
-│   └── If Guard logic is wrong → create replacement Guard (immutable)
-├── Cache stale reads
-│   ├── Retry with env.no_cache: true
-│   ├── If still fails → wait, then retry
-│   └── For sequential operations → always set no_cache: true
-├── Permission denied
-│   ├── Check the object's Permission configuration
-│   ├── Verify account has required indices
-│   └── Request permission holder to grant access
-├── Object not found
-│   ├── Verify name/ID spelling
-│   ├── Check env.network matches
-│   ├── Retry with no_cache: true
-│   └── If truly doesn't exist → create new or correct reference
-├── Insufficient gas
-│   ├── Add more gas to the account
-│   ├── Faucet on testnet (account_operation → faucet)
-│   └── Retry the operation
-├── File parsing failure
-│   ├── Check machineNode2file / guard2file output format
-│   ├── Verify schema compliance
-│   └── Regenerate the export
-└── GetObjectExisted() error
-    ├── String reference couldn't be resolved
-    ├── Check name spelling
-    ├── Check if object exists via query_toolkit
-    └── Switch to CREATE (object shape) if object doesn't exist
-```
-
----
-
-## Failure Playbooks
-
-### F1: Cache Stale Reads
-
-**Trigger**: Sequential operations fail unexpectedly. For example, "object not found" when the object was just created in the previous step.
-
-**Diagnosis**:
-- WoWok's caching layer hasn't propagated the latest state.
-- The previous operation succeeded, but the cache still returns the old state.
-- Common in rapid sequential operations (create object → reference object in next call).
-
-**Recovery**:
-1. Retry the failing operation with `env.no_cache: true`.
-2. If the retry succeeds → cache lag confirmed. Always use `no_cache: true` for sequential operations.
-3. If the retry still fails → the object truly doesn't exist or the operation has a different error.
-4. For ongoing sequential operations: set `no_cache: true` on ALL operations in the chain.
-
-**Prevention**: When building multiple interdependent objects, set `env.no_cache: true` on all operations. This is listed in §Common Mistakes as "Forgetting no_cache."
-
-### F2: Missing Permission Indices
-
-**Trigger**: A Machine forward references a Permission index that doesn't exist. The operation fails with "permission denied" or "index out of bounds."
-
-**Diagnosis**:
-- The Machine's forward specifies a `namedOperator` index that the Permission object doesn't have.
-- The Permission object was created with fewer indices than the Machine requires.
-- The Machine was designed before the Permission object was fully configured.
-
-**Recovery**:
-1. `machineNode2file` to export the Machine and identify all `namedOperator` indices.
-2. `query_toolkit` → `onchain_objects` for the Permission object. Check available indices.
-3. If the Permission object is mutable → add the missing indices.
-4. If the Permission object is immutable → create a new Permission with the required indices, then update the Machine (if mutable) or create a new Machine.
-5. If the Machine is already published → cannot modify. Must create a new Machine with correct references.
-
-**Prevention**: Before creating a Machine, verify the Permission object has all required indices. This is listed in §Common Mistakes as "Missing permission indices." Design the Permission object first, then the Machine.
-
-### F3: Token Decimals Assumption
-
-**Trigger**: An amount-sensitive operation fails or produces unexpected results because the token's decimals were assumed rather than queried.
-
-**Diagnosis**:
-- The AI assumed WOW has 9 decimals (correct, but should still query).
-- The AI assumed a custom token has the same decimals as WOW (wrong).
-- The amount was submitted as a human-readable string ("2 WOW") instead of a U64 integer (`2000000000`).
-- The token's decimals couldn't be queried, and the AI guessed (wrong).
-
-**Recovery**:
-1. `query_toolkit` → `token_list` to get the correct `decimals` and `symbol`.
-2. Recalculate: `u64_amount = human_amount × (10 ^ decimals)`.
-3. Re-submit the operation with the correct U64 integer.
-4. If the token's decimals cannot be queried → HALT. Alert the user. Do not proceed with guessed precision.
-
-**Prevention**: NEVER assume token decimals. ALWAYS query via `query_toolkit` with `query_type: "token_list"` before any amount-sensitive operation. This is documented in §2.2 Amount Verification and §5.1 Multi-Token Support.
-
-### F4: Name Collision (replaceExistName)
-
-**Trigger**: An operation fails because an object with the same name already exists. Or, `replaceExistName: true` was used accidentally, stealing the name from an existing object.
-
-**Diagnosis**:
-- `replaceExistName: false` (default) → throws error if name is in use.
-- `replaceExistName: true` → steals the name; the old object becomes unnamed (potentially orphaned).
-- The user didn't realize the name was already in use.
-- The user used `replaceExistName: true` in production (should be development only).
-
-**Recovery**:
-1. If `replaceExistName: false` and name collision → either:
-   - Choose a different name (e.g., append `_v2`).
-   - Use `replaceExistName: true` intentionally if the old object is obsolete.
-2. If `replaceExistName: true` was used accidentally → the old object is now unnamed. Query by ID to find it. Re-name it or accept the orphaned state.
-3. For production systems → use versioned names (`_v1`, `_v2`) instead of `replaceExistName`.
-
-**Prevention**: Default to `replaceExistName: false` in production. Use versioned names for iterations. Only use `replaceExistName: true` during development with fixed test names. This is documented in §4.1 replaceExistName Flag.
-
-### F5: Guard Validation Failure
-
-**Trigger**: An operation with `submission` fails because the Guard logic evaluated to false. The Guard rejected the submitted data.
-
-**Diagnosis**:
-- The Guard's rule tree was satisfied by the conditions, but the submitted data didn't meet the requirements.
-- The Guard logic itself may be correct, but the data values are wrong.
-- The Guard logic may be wrong (designed incorrectly), but since Guards are immutable, it cannot be patched.
-
-**Recovery**:
-1. `guard2file` to export and review the Guard's rule tree.
-2. Compare the submitted data values against the Guard's requirements.
-3. If the data is wrong → correct the data and re-submit.
-4. If the Guard logic is wrong → create a replacement Guard with corrected logic. Update the host object (if mutable) to reference the new Guard.
-5. If the host object is immutable → cannot update the Guard reference. Must create a new host object.
-
-**Prevention**: Test Guards with `gen_passport` before binding them to objects. Review the Guard's rule tree via `guard2file` before finalizing. This is documented in §7 Error Patterns.
-
-### F6: Immutable Field Modification Attempt
-
-**Trigger**: The user tries to modify a field that became immutable after publish (e.g., Service machine, Service order_allocators, Guard rules, Machine node topology).
-
-**Diagnosis**:
-- After a Service is published, `machine` and `order_allocators` are locked.
-- After a Guard is created, all rules are locked.
-- After a Machine is published, node topology and forwards are locked.
-- The operation fails with an error indicating the field cannot be modified.
-
-**Recovery**:
-1. Identify which field is immutable.
-2. If the field is on a Service:
-   - `machine` and `order_allocators` → immutable after publish. Must create a new Service.
-   - `description`, `location`, `sales`, `customer_required`, `um` → mutable. Can modify.
-3. If the field is on a Guard → all rules immutable. Must create a replacement Guard.
-4. If the field is on a Machine → node topology and forwards immutable after publish. Must create a new Machine.
-5. Communicate to the user: the only path is creating a new object (Service, Guard, or Machine) with the desired configuration.
-
-**Prevention**: Before publishing, thoroughly test and review all configurations. Use the Export & Review step (R6) to verify. Warn about immutability in the confirmation template (R7). This is documented in §2.3 Publish Confirmation.
-
----
-
-## Tier Layering
-
-### Novice — Always Confirm, Always Query First
-
-**Profile**: First-time user. Unfamiliar with WoWok safety rules. Needs explicit confirmation for every operation.
-
-**AI Behavior**:
-- Always run the full R1-R10 safety dialogue for ON-CHAIN operations.
-- Always query token decimals before amount-sensitive operations (never assume).
-- Always use the confirmation template (R7) with full operation preview.
-- Always set `env.no_cache: true` for sequential operations.
-- Always verify object existence before referencing (R3).
-- For publish operations: always export and review (R6) before confirming.
-- Default to conservative: if any check is uncertain, STOP and ask the user.
-
-**Typical Journey**: R1 (intent) → R2 (account) → R3 (reuse/create) → R4 (permission) → R5 (amount) → R6 (export if publish) → R7 (confirmation) → R8 (call without submission) → R9 (execute) → R10 (verify).
-
-### Advanced — Batch Operations, Incremental Building
-
-**Profile**: Experienced user. Understands WoWok safety rules. Wants efficient operations without redundant checks.
-
-**AI Behavior**:
-- Batch related operations: verify all objects in R3 before proceeding.
-- For incremental object building: allow step-by-step creation with verification at each step, but don't re-run the full R1-R10 for each step.
-- For amount-sensitive operations: query token decimals once, cache for the session.
-- For sequential operations: set `no_cache: true` globally for the session.
-- For publish operations: export and review, but allow the user to skip detailed review if they've tested independently.
-- Use `replaceExistName` strategically during development (with user awareness).
-- Support multi-account operations: verify permissions for each account independently.
-
-**Typical Journey**: R1 (intent, batch) → R2 (account, batch) → R3 (reuse/create, batch) → R4 (permission, batch) → R5 (amount, cached) → R6 (export if publish) → R7 (confirmation, batch) → R8-R9 (execute, batch) → R10 (verify, batch).
-
-### Expert — Complex Multi-Object Systems, Circular References
-
-**Profile**: Power user. Builds complex systems with circular references (CREATE object → CREATE Guard → MODIFY object). Needs advanced safety patterns.
-
-**AI Behavior**:
-- Support circular reference patterns: CREATE object (without Guard binding) → CREATE Guard (references object by name) → MODIFY object (binds Guard).
-- Manage dependency chains: track which objects depend on which, execute in the correct order.
-- For multi-object systems: create a dependency graph, execute in topological order.
-- Support `replaceExistName` for iterative development with fixed names.
-- Support multi-network operations: testnet for development, mainnet for production, with explicit network switching.
-- For publish operations: comprehensive readiness check (D4) before proceeding.
-- Support custom confirmation thresholds: user-configurable amount thresholds for heightened confirmation.
-- Track immutability constraints across the system: warn when a modification would require creating replacement objects.
-- Support rollback planning: before irreversible operations, document the recovery path (e.g., "if this publish fails, create a new Service with corrected config").
-
-**Typical Journey**: R1 (intent, system-level) → R2 (account, multi-account) → R3 (reuse/create, dependency graph) → R4 (permission, multi-account) → R5 (amount, multi-token) → R6 (export, full system review) → R7 (confirmation, system-level) → R8-R9 (execute, dependency-ordered) → R10 (verify, system-level handoff).

package/wowok-scenario/APPENDIX.md

@@ -1,97 +0,0 @@
-# Appendix — wowok-scenario
-
-> This file is loaded on-demand (Progressive Disclosure).
-> Main skill: [SKILL.md](./SKILL.md)
-
----
-
-## Tier Layering
-
-### Novice Tier — Full Driving Mode
-
-- User selects an industry; mode defaults fill R3-R8 with no manual configuration
-- 10-round build completes with user only confirming mode defaults
-- Audit checklist enforces all blocker items
-- Failure playbook provides step-by-step recovery
-
-### Advanced Tier — Customize Defaults
-
-- User selects a mode but overrides specific fields (e.g., freelance Allocator changed from 100% provider to 80% provider + 20% platform)
-- Mode template is the starting point, not the contract
-- Audit checklist still runs; user can dismiss warnings with explicit confirmation
-- Trigger: user says "I want to customize" or has done this before
-
-### Expert Tier — Free Mode
-
-- User invokes `general` mode (escape hatch)
-- No defaults applied; raw MCP operations exposed
-- wowok-machine, wowok-guard, wowok-provider become the primary references
-- Audit checklist is optional but recommended
-- Trigger: user explicitly asks for "expert mode" or invokes MCP operations by name
-
----
-
-## IndustryModeSchema (Reference)
-
-```typescript
-type IndustryModeSchema = {
-  name: "freelance" | "rental" | "education" | "travel" | "subscription" | "general";
-  display_name: string;
-  traits: IndustryTraits;
-  defaults: {
-    permission_indexes: { role: string; index: number | null; scope: string }[]; // null = uses namedOperator: ""
-    machine_template: {
-      nodes: { name: string; prev_node: string; threshold: number }[];
-      forwards: {
-        name: string;
-        weight: number;
-        permissionIndex?: number;   // user-defined ≥1000; absent if using namedOperator
-        namedOperator?: string;     // "" = order owner/agents (customer/renter)
-        guard?: string;             // Forward guard name (binds via Machine MODIFY)
-      }[];
-    };
-    guard_templates: {
-      name: string;
-      host: string;              // Service.buy_guard | Machine Forward <name> | Allocator trigger
-      validation_logic: string;
-      table_entries: { identifier: number; b_submission: boolean; value_type: string; value?: string; name: string }[];
-    }[];
-    // Mirrors AllocatorSchema: each allocator has guard + sharing[] (each item has who + sharing + mode)
-    allocator_strategy: {
-      guard: string;             // Allocator trigger guard name (NOT trigger_guard — matches AllocatorSchema)
-      sharing: { who: RecipientType; sharing: number; mode: "Amount" | "Rate" | "Surplus" }[];
-      fix?: number;              // optional fixed amount
-      max?: number | null;       // optional cap
-    }[];
-    arbitration_enabled: boolean;
-  };
-  dialogue_script: { round: string; goal: string; mcp_calls: string[] }[];
-  audit_checklist: { id: number; check: string; blocker: boolean }[];
-  failure_playbook: { scenario: string; mitigation: string; recovery: string }[];
-  escape_hatch: {
-    available: true;
-    warning: string;
-  };
-};
-
-type RecipientType =
-  | { Entity: { name_or_address: string } }
-  | { GuardIdentifier: number }
-  | { Signer: "signer" };
-```
-
-Every mode definition in this Skill follows this schema. Phase 2/3 modes (education, travel, subscription) will fill in the same schema when promoted to Phase 1 detail level.
-
----
-
-## Quick Reference
-
-| Want to... | Use this |
-|------------|----------|
-| Pick a mode for a new user | §Mode Selection Logic |
-| Get freelance defaults | §Freelance Mode |
-| Get rental defaults | §Rental Mode |
-| Combine two modes | §Mode Composition |
-| Switch to manual config | §Escape Hatch |
-| Validate before publish | Mode-specific §Audit Checklist |
-| Recover from a stuck flow | Mode-specific §Failure Playbooks |