web3skill 0.1.0

package/dist/skills/web3-native-operator/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: web3-native-operator
+description: Web3 routing layer for safe execution, simulation, trace analysis, and repo-first smart contract work. Use for transfers, approvals, swaps, audits, onchain debugging, or Web3 research. It does not execute venue-specific flows directly; it routes to safety gates and profile adapters.
+always: true
+---
+
+# Web3-Native Operator
+
+Use this skill as the default control plane for Web3 work.
+
+## Routing Rules
+
+- If the user wants a chain write, read `web3-risk-gate` first.
+- If the action may move value or approvals, read `web3-transaction-simulator` before any venue-specific adapter.
+- If the user wants a tx, call, state diff, proxy path, or archive-node analysis, read `web3-trace-and-state-analysis`.
+- If the task is a contract or protocol security review, read `web3-audit-orchestrator`.
+- If the user explicitly wants scanners, read `web3-static-analysis-runner`.
+- If the user wants invariants, fuzzing, or failure interpretation, read `web3-fuzzing-and-invariants`.
+- If the task is token research, protocol diligence, market intel, or pre-trade investigation, read `web3-research-and-market-intel`.
+- If the task is venue-specific trading on Hyperliquid, route to `hyperliquid` after risk and simulation.
+- If the task is repo- or contract-based, read `web3-repo-heuristics` before testing or patching.
+- If the task needs live RPC, storage, bytecode, logs, or call data, read `evm-mcp-playbook`.
+
+## Stable Routing Contract
+
+For execution, audit, and research flows, do not route from free text alone once
+the relevant downstream skills have produced normalized blocks.
+
+Use:
+
+- [references/ROUTING_STATE_MACHINE.md](references/ROUTING_STATE_MACHINE.md)
+- [references/ROUTE_RECIPES.md](references/ROUTE_RECIPES.md)
+- [references/EXECUTION_BUNDLE_TEMPLATE.md](references/EXECUTION_BUNDLE_TEMPLATE.md)
+- [references/OPERATOR_BUNDLE_TEMPLATE.md](references/OPERATOR_BUNDLE_TEMPLATE.md)
+- [references/PRETRADE_PACKET_TEMPLATE.md](references/PRETRADE_PACKET_TEMPLATE.md)
+- [references/POSTTRADE_WATCH_TEMPLATE.md](references/POSTTRADE_WATCH_TEMPLATE.md)
+- [references/POSTTRADE_FOLLOWUP_BUNDLE_TEMPLATE.md](references/POSTTRADE_FOLLOWUP_BUNDLE_TEMPLATE.md)
+- [references/WATCH_FOLLOWUP_BUNDLE_TEMPLATE.md](references/WATCH_FOLLOWUP_BUNDLE_TEMPLATE.md)
+- [references/WATCH_CRON_REQUEST_TEMPLATE.md](references/WATCH_CRON_REQUEST_TEMPLATE.md)
+- [references/WATCH_HEARTBEAT_TEMPLATE.md](references/WATCH_HEARTBEAT_TEMPLATE.md)
+- [scripts/render_execution_bundle.py](scripts/render_execution_bundle.py)
+- [scripts/render_operator_bundle.py](scripts/render_operator_bundle.py)
+- [scripts/render_pretrade_packet.py](scripts/render_pretrade_packet.py)
+- [scripts/render_posttrade_followup_bundle.py](scripts/render_posttrade_followup_bundle.py)
+- [scripts/render_posttrade_watch_status.py](scripts/render_posttrade_watch_status.py)
+- [scripts/apply_followup_bundle_to_heartbeat.py](scripts/apply_followup_bundle_to_heartbeat.py)
+- [scripts/render_watch_followup_bundle.py](scripts/render_watch_followup_bundle.py)
+- [scripts/render_watch_cron_request.py](scripts/render_watch_cron_request.py)
+- [scripts/render_watch_heartbeat.py](scripts/render_watch_heartbeat.py)
+
+The operator should consume:
+
+- execution:
+  - `risk_gate.decision`
+  - `risk_gate.coverage`
+  - `simulation.status`
+  - `simulation.readiness`
+  - `simulation.venue`
+- audit:
+  - `audit_review.review_state`
+  - `static_analysis_summary.status`
+  - `fuzz_summary.campaign_status`
+- research:
+  - `research_brief.conclusion`
+  - `research_brief.freshness`
+- watch:
+  - `watch_status.status`
+  - `watch_status.watch_kind`
+  - `watch_status.subject`
+  - `watch_status.trigger_source`
+  - `watch_status.severity`
+  - `watch_status.next_check_hint`
+  - `watch_status.recommended_adapter`
+- pretrade:
+  - `research_brief.conclusion`
+  - `risk_gate.decision`
+  - `risk_gate.coverage`
+  - `simulation.status`
+  - `simulation.readiness`
+  - `simulation.venue`
+- posttrade:
+  - `execution_receipt.status`
+  - `execution_receipt.venue`
+  - `execution_receipt.settlement`
+  - `execution_receipt.reference_id`
+- portfolio:
+  - `portfolio_status.status`
+  - `portfolio_status.coverage`
+  - `portfolio_status.source_class`
+  - `portfolio_status.provider`
+  - `portfolio_status.venue`
+- trace:
+  - `trace_summary.status`
+  - `trace_summary.backend.readiness`
+  - `trace_summary.follow_up_skills`
+
+Then emit one stable operator bundle before any venue-specific execution step.
+
+## Minimum Inputs
+
+Collect the minimum missing context before acting:
+
+- chain
+- token or contract address
+- amount and units
+- receiver / spender / target address
+- tx hash or block context
+- repo path, if code is involved
+
+## Adapter Preference
+
+Prefer the Web3 profile adapters already bundled in workspace `skills/`:
+
+- Safety: `security-check`, `binance-token-audit`, `query-token-audit`, `query-address-info`, `token-integration-analyzer`, `proxy-upgrade-safety`
+- Planning: `swap-planner`, `liquidity-planner`, `token-swap`, `hyperliquid`, `gas-tracker`
+- Analysis: `behavioral-state-analysis`, `entry-point-analyzer`, `etherscan`
+- Audit: `solidity-auditor`, `audit-context-building`, `secure-workflow-guide`, `security-auditor`
+- Static analysis: `codeql`, `semgrep`, `sarif-parsing`, `scv-scan`
+- Fuzzing: `property-based-testing`, `harness-writing`, `coverage-analysis`, `state-invariant-detection`
+- Research: `defillama`, `coingecko`, `dune`, `whale-watcher`, `trading-signal`, `binance-token-info`, `binance-market-rank`, `binance-meme-rush`, `four-meme`, `debank`
+
+## Execution Contract
+
+1. Classify the task: execution, simulation, trace, repo audit, or research.
+2. Name assumptions explicitly.
+3. Do not jump from user intent straight to a chain write.
+4. Prefer reproducible artifacts: command, quote, trace summary, report, patch, or execution bundle.
+
+## Execution Bundle Rules
+
+- If `risk_gate.decision = BLOCK`, stop immediately.
+- If `simulation.status = NO_SIMULATION`, do not route to a write adapter.
+- If `risk_gate.decision = WARN` or `simulation.status = WARN`, require explicit confirmation.
+- If both risk and simulation are green enough to continue, emit a bundle naming the next adapter:
+  - `hyperliquid` for Hyperliquid perp / spot venue flow
+  - `token-swap` for executable EVM swap flow
+  - `liquidity-planner` for LP planning flow
+  - `web3-trace-and-state-analysis` as follow-up when route safety still depends on trace evidence
+
+## Audit And Research Bundle Rules
+
+- For audit flows:
+  - if `static_analysis_summary.status != complete`, route to `web3-static-analysis-runner`
+  - else if `fuzz_summary.campaign_status != ready`, route to `web3-fuzzing-and-invariants`
+  - else if `audit_review.review_state` is at triage/report/retest stages, route to `web3-audit-reporting`
+- For research flows:
+  - if `research_brief.conclusion = ready-for-risk-gate`, route to `web3-risk-gate`
+  - if `research_brief.conclusion = investigate-more`, keep the flow in research and name the follow-up
+  - if `research_brief.conclusion = watch`, normalize the watch target with `watch_status` before scheduling or monitoring
+  - if `research_brief.conclusion = avoid-for-now`, stop instead of implying trade readiness
+
+## Pretrade Bundle Rules
+
+- For `research -> risk-gate -> simulator -> venue` flows:
+  - if `research_brief.conclusion = avoid-for-now`, stop immediately
+  - if research is not yet `ready-for-risk-gate`, route back to `web3-research-and-market-intel`
+  - if `risk_gate.decision = BLOCK`, stop immediately
+  - if `risk_gate.coverage != complete` or `simulation.status = NO_SIMULATION`, route to `web3-trace-and-state-analysis`
+  - if `risk_gate.decision = WARN` or `simulation.status = WARN`, require explicit confirmation before venue routing
+  - if research is ready, risk is `ALLOW`, and simulation is `PASS/ready`, route directly to the venue adapter
+  - if the runtime needs `research_brief`, `risk_gate`, `simulation`, and
+    `operator_bundle` together, emit `pretrade_packet` with
+    `render_pretrade_packet.py`
+
+## Posttrade Bundle Rules
+
+- If `execution_receipt.status = FAILED` or `REVERTED`, route to:
+  - `web3-trace-and-state-analysis` for EVM settlement
+  - the venue adapter for venue-native failure inspection
+- If `execution_receipt.status = SUBMITTED` or `PENDING`, keep the flow in monitoring:
+  - `web3-trace-and-state-analysis` for EVM confirmation
+  - `hyperliquid` or the same venue adapter for venue-native fill / position checks
+- If `execution_receipt.status = CONFIRMED` or `FILLED`, route to:
+  - `web3-trace-and-state-analysis` for EVM outcome verification
+  - the venue adapter for post-fill status and position checks
+- If the posttrade state must persist across turns, normalize `execution_receipt`
+  into `watch_status` with `render_posttrade_watch_status.py` before writing a
+  heartbeat or cron scaffold.
+- If the consumer needs the immediate posttrade route plus all deferred monitor
+  artifacts together, emit `posttrade_followup_bundle` with
+  `render_posttrade_followup_bundle.py`.
+
+## Portfolio Bundle Rules
+
+- If `portfolio_status.status = UNAVAILABLE` or coverage is missing, route to `web3-research-and-market-intel`.
+- If `source_class = venue` and `venue = hyperliquid`, route to `hyperliquid`.
+- If `source_class = wallet`, prefer `debank`.
+- If `source_class = address`, prefer `query-address-info`.
+
+## Watch Bundle Rules
+
+- If `watch_status.status = UNAVAILABLE`, investigate missing data or backend scope before implying monitoring coverage.
+- If severity is `high` or `critical`, escalate to investigation instead of passive monitoring.
+- If `watch_status.status = CLEARED`, stop the watch unless the user explicitly wants it kept alive.
+- Otherwise keep the workflow in monitor mode and route to the recommended adapter or an explicit follow-up.
+- If the watch should persist across sessions, render a heartbeat task block before writing into `HEARTBEAT.md`.
+- If the watch or posttrade bundle is ready to be persisted, use
+  `apply_followup_bundle_to_heartbeat.py` to append it under `Active Tasks`.
+- If the watch should become a real scheduled task, render a `cron_request`
+  scaffold with `render_watch_cron_request.py` instead of freehand tool args.
+- If the runtime needs all watch follow-up artifacts at once, emit a
+  `watch_followup_bundle` with `render_watch_followup_bundle.py`.
+
+## Trace Bundle Rules
+
+- If `trace_summary.status = UNAVAILABLE` or backend readiness is missing, route to `evm-mcp-playbook`.
+- If trace was gathered for execution safety:
+  - `COMPLETE + ready` -> route back to `web3-transaction-simulator`
+  - `PARTIAL` -> route back to `web3-risk-gate` or another explicit follow-up
+- If trace was gathered for audit evidence, route back to `web3-audit-orchestrator`.
+- If trace was gathered for research diligence, route back to `web3-research-and-market-intel`.
+
+## Guardrails
+
+- Do not treat adapter output as final until chain, contract, and action scope are explicit.
+- If a safety gate says `BLOCK`, stop and explain why.
+- If simulation or tracing is unavailable, say so explicitly instead of implying safety.
+- Keep the operator bundle stable so future execution runtimes can consume it without reparsing prose.

package/dist/skills/web3-native-operator/references/EXECUTION_BUNDLE_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Web3 Native Operator Execution Bundle Template
+
+Emit this bundle after consuming normalized `risk_gate` and `simulation` blocks.
+
+```yaml
+operator_bundle:
+  version: 1
+  intent: swap
+  chain: base
+  state: needs-confirmation
+  next_adapter: token-swap
+  execution_mode: confirm_then_route
+  requires_user_confirmation: true
+  inputs:
+    risk_decision: WARN
+    risk_coverage: complete
+    simulation_status: PASS
+    simulation_readiness: needs-confirmation
+    simulation_venue: token-swap
+  follow_up_skills:
+    - web3-trace-and-state-analysis
+  reasons:
+    - token is upgradeable
+    - route exists but approval is still missing
+```
+
+## Required Fields
+
+- `state`: `blocked | needs-confirmation | ready-to-route | investigate-more`
+- `next_adapter`: venue adapter, follow-up skill, or `none`
+- `execution_mode`
+- `requires_user_confirmation`
+- `inputs`
+
+## Execution Mode Values
+
+- `stop`
+- `investigate`
+- `confirm_then_route`
+- `route`
+
+## Notes
+
+- Keep `inputs` flattened so downstream runtimes do not need to re-parse earlier blocks.
+- `follow_up_skills` is optional but should be explicit when trace or research is still needed.
+- For `blocked`, prefer `next_adapter = none`.
+- For `investigate-more`, prefer a follow-up analyzer such as `web3-trace-and-state-analysis`.

package/dist/skills/web3-native-operator/references/OPERATOR_BUNDLE_TEMPLATE.md

@@ -0,0 +1,39 @@
+# Web3 Native Operator Bundle Template
+
+Use this template when routing normalized blocks from execution, audit, research, watch, pretrade, posttrade, portfolio, or trace flows.
+
+```yaml
+operator_bundle:
+  version: 1
+  workflow_kind: portfolio
+  state: monitor-portfolio
+  next_adapter: debank
+  execution_mode: route
+  requires_user_confirmation: false
+  inputs:
+    portfolio_status: COMPLETE
+    coverage: complete
+    source_class: wallet
+    provider: debank
+    venue: none
+  follow_up_skills:
+    - web3-research-and-market-intel
+  reasons:
+    - wallet portfolio state is ready for monitoring
+```
+
+## Required Fields
+
+- `workflow_kind`: `execution | audit | research | watch | pretrade | posttrade | portfolio | trace`
+- `state`
+- `next_adapter`: venue adapter, builtin skill, follow-up skill, or `none`
+- `execution_mode`: `stop | investigate | confirm_then_route | route | monitor`
+- `requires_user_confirmation`
+- `inputs`
+
+## Notes
+
+- Execution flows can still use [EXECUTION_BUNDLE_TEMPLATE.md](EXECUTION_BUNDLE_TEMPLATE.md)
+  for the execution-specific shape.
+- Audit, research, watch, pretrade, posttrade, portfolio, and trace flows should keep `inputs` flattened so the operator runtime
+  does not need to re-parse upstream blocks.

package/dist/skills/web3-native-operator/references/POSTTRADE_FOLLOWUP_BUNDLE_TEMPLATE.md

@@ -0,0 +1,35 @@
+# Posttrade Follow-Up Bundle Template
+
+Use this template when a normalized `execution_receipt` should immediately
+produce both the posttrade route and deferred monitoring artifacts.
+
+```yaml
+posttrade_followup_bundle:
+  version: 1
+  execution_receipt:
+    receipt_status: SUBMITTED
+    venue: token-swap
+    settlement: evm
+    reference_id: "0xabc"
+  operator_bundle:
+    workflow_kind: posttrade
+    state: monitor-settlement
+    next_adapter: web3-trace-and-state-analysis
+    execution_mode: monitor
+  watch_status:
+    status: ACTIVE
+    watch_kind: posttrade
+    subject: tx:0xabc
+    recommended_adapter: web3-trace-and-state-analysis
+  heartbeat_task: |
+    - [ ] Watch tx:0xabc
+      Task: Re-run web3-trace-and-state-analysis for tx:0xabc on heartbeat and summarize any new evidence.
+  cron_request:
+    action: add
+    cron_expr: "*/5 * * * *"
+```
+
+## Notes
+
+- `operator_bundle` here is the immediate posttrade route from `execution_receipt`.
+- `watch_status`, `heartbeat_task`, and `cron_request` are the deferred monitor artifacts.

package/dist/skills/web3-native-operator/references/POSTTRADE_WATCH_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Posttrade Watch Template
+
+Use this template when a normalized `execution_receipt` must be converted into a
+stable `watch_status` block for monitoring or alerting.
+
+```yaml
+watch_status:
+  version: 1
+  status: ACTIVE
+  watch_kind: posttrade
+  subject: tx:0xabc
+  trigger_source: token-swap
+  severity: medium
+  next_check_hint: check receipt confirmations and final token balances after 5 minutes
+  schedule_hint: "*/5 * * * *"
+  recommended_adapter: web3-trace-and-state-analysis
+  evidence:
+    - adapter: token-swap
+      detail: transaction submitted and awaiting settlement
+```
+
+## Mapping Rules
+
+- `SUBMITTED | PENDING` -> `status = ACTIVE`
+- `CONFIRMED | FILLED` -> `status = TRIGGERED`
+- `FAILED | REVERTED` -> `status = TRIGGERED`
+- EVM settlement prefers `recommended_adapter = web3-trace-and-state-analysis`
+- Venue settlement prefers `recommended_adapter = venue`
+
+## Notes
+
+- Use `TRIGGERED` for confirmed or failed receipts because both still require a
+  verification or failure-inspection step.
+- `schedule_hint` should stay advisory if no scheduler is being installed.

package/dist/skills/web3-native-operator/references/PRETRADE_PACKET_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Pretrade Packet Template
+
+Use this template when normalized `research_brief`, `risk_gate`, and
+`simulation` should be packaged together with the operator decision before any
+venue-specific route.
+
+```yaml
+pretrade_packet:
+  version: 1
+  intent: swap
+  chain: base
+  research_brief:
+    conclusion: ready-for-risk-gate
+    freshness: fresh
+  risk_gate:
+    decision: ALLOW
+    coverage: complete
+  simulation:
+    status: PASS
+    readiness: ready
+    venue: token-swap
+  operator_bundle:
+    workflow_kind: pretrade
+    state: ready-to-route
+    next_adapter: token-swap
+    execution_mode: route
+```
+
+## Notes
+
+- Use `render_pretrade_packet.py` when the runtime should consume pretrade
+  research, safety, simulation, and routing state as one stable artifact.
+- `risk_gate` and `simulation` may be omitted only when research is still
+  incomplete or blocks the flow before pretrade checks should run.

package/dist/skills/web3-native-operator/references/ROUTE_RECIPES.md

@@ -0,0 +1,140 @@
+# Web3 Native Operator Route Recipes
+
+Use these recipes after both `web3-risk-gate` and `web3-transaction-simulator`
+have emitted normalized blocks.
+
+## Swap Or Token Buy
+
+1. Run `web3-risk-gate` on token, router, spender, and receiver.
+   - If multiple adapters emitted separate `risk_gate` blocks, merge them first with `web3-risk-gate/scripts/merge_risk_gate_blocks.py`
+     or pass them directly to the operator scripts with repeated `--risk-input-file`.
+2. Run `web3-transaction-simulator` for quote, allowance, output, and revert risk.
+   - If multiple planners or live-read adapters emitted separate `simulation` blocks, merge them first with
+     `web3-transaction-simulator/scripts/merge_simulation_blocks.py`
+     or pass them directly to the operator scripts with repeated `--simulation-input-file`.
+3. Emit `operator_bundle`.
+4. Route:
+   - `state = blocked` -> stop
+   - `state = investigate-more` -> `web3-trace-and-state-analysis`
+   - `next_adapter = hyperliquid` -> venue-specific Hyperliquid flow
+   - `next_adapter = token-swap` -> EVM swap execution flow
+
+## Liquidity Add Or Remove
+
+1. Risk-gate LP tokens, router, pool, and approval targets.
+2. Simulate token ratios, slippage, approvals, and gas assumptions.
+3. Emit `operator_bundle`.
+4. Route:
+   - `ready-to-route` or `needs-confirmation` -> `liquidity-planner`
+   - incomplete pool evidence -> `web3-trace-and-state-analysis`
+
+## Transfer Or Approve
+
+1. Risk-gate receiver or spender first.
+2. If value-moving or approval-changing, still use `web3-transaction-simulator`
+   for balance, allowance delta, and target code checks.
+3. Emit `operator_bundle`.
+4. Route:
+   - direct execution adapter only if gate/simulation allow it
+   - suspicious receiver or opaque contract -> trace / live-read follow-up
+
+## Trace-Escalated Execution
+
+Escalate to `web3-trace-and-state-analysis` when:
+
+- `risk_gate.coverage != complete`
+- `simulation.status = NO_SIMULATION`
+- route safety depends on proxy path, delegatecall, storage slot, or internal call attribution
+- the write target is upgradeable or implementation provenance is unclear
+
+The trace skill should then emit a stable `trace_summary` block before the operator
+re-enters venue routing.
+
+## Trace Re-Entry
+
+1. Consume `trace_summary`.
+2. If `trace_summary.status = UNAVAILABLE` or backend readiness is `missing`, route to `evm-mcp-playbook`.
+3. If the trace goal was execution safety:
+   - `COMPLETE + ready` -> re-enter through `web3-transaction-simulator`
+   - `PARTIAL` -> re-enter through `web3-risk-gate`
+4. If the trace goal was audit evidence, re-enter through `web3-audit-orchestrator`.
+5. If the trace goal was research diligence, re-enter through `web3-research-and-market-intel`.
+
+## Audit Or Review
+
+1. Consume `audit_review`.
+2. If scanner evidence is incomplete, route to `web3-static-analysis-runner`.
+3. If invariant or fuzz coverage is incomplete after static triage, route to `web3-fuzzing-and-invariants`.
+4. Once review state reaches triage, confirmed findings, or retest, emit `operator_bundle`.
+5. Route:
+   - `collect-evidence` -> `web3-static-analysis-runner` or `web3-fuzzing-and-invariants`
+   - `triage-findings` -> `web3-audit-orchestrator`
+   - `report-and-retest` -> `web3-audit-reporting`
+
+## Research To Execution
+
+1. Consume `research_brief`.
+2. Emit `operator_bundle`.
+3. Route:
+   - `conclusion = ready-for-risk-gate` -> `web3-risk-gate`
+   - `conclusion = investigate-more` -> follow-up research skill or `web3-research-and-market-intel`
+   - `conclusion = watch` -> emit `watch_status` before handing the task to monitoring
+   - `conclusion = avoid-for-now` -> stop
+
+## Pretrade Closure
+
+1. Consume `research_brief`, `risk_gate`, and `simulation`.
+   - If the risk view comes from multiple adapters, merge those `risk_gate` blocks before this step.
+   - If the simulation view comes from multiple adapters, merge those `simulation` blocks before this step.
+2. Emit `operator_bundle`.
+3. Route:
+   - research not ready -> `web3-research-and-market-intel`
+   - risk blocked -> stop
+   - risk coverage partial or no simulation -> `web3-trace-and-state-analysis`
+   - warnings present -> venue adapter with explicit confirmation
+   - green path -> venue adapter directly
+4. If the runtime wants the full pretrade context in one stable payload, emit
+   `pretrade_packet` with `render_pretrade_packet.py`.
+
+## Posttrade Verification
+
+1. Consume `execution_receipt`.
+2. Emit `operator_bundle`.
+3. Route:
+   - EVM `SUBMITTED/PENDING` -> `web3-trace-and-state-analysis`
+   - EVM `CONFIRMED/FILLED` -> `web3-trace-and-state-analysis`
+   - EVM `FAILED/REVERTED` -> `web3-trace-and-state-analysis`
+   - Hyperliquid `SUBMITTED/PENDING/CONFIRMED/FILLED` -> `hyperliquid`
+   - venue-native failure -> same venue adapter or explicit follow-up skill
+4. If the monitoring target must persist beyond the current turn, normalize the
+   receipt with `render_posttrade_watch_status.py` before writing heartbeat or
+   cron scaffolding.
+5. If the consumer needs receipt routing and deferred monitoring artifacts in one
+   shot, emit `posttrade_followup_bundle` with `render_posttrade_followup_bundle.py`.
+
+## Portfolio Status Routing
+
+1. Consume `portfolio_status`.
+2. Emit `operator_bundle`.
+3. Route:
+   - wallet portfolio -> `debank`
+   - chain-scoped address holdings -> `query-address-info`
+   - venue position status -> `hyperliquid`
+   - incomplete or unavailable status -> `web3-research-and-market-intel`
+
+## Watch Or Alert Routing
+
+1. Consume `watch_status`.
+2. Emit `operator_bundle`.
+3. Route:
+   - `status = UNAVAILABLE` -> investigate missing backend or scope via recommended adapter or `web3-research-and-market-intel`
+   - `severity = high | critical` -> escalate to investigation using the recommended adapter
+   - `status = ACTIVE | TRIGGERED` with low/medium severity -> keep monitor mode and route to the recommended adapter
+   - `status = CLEARED` -> stop with `next_adapter = none`
+4. If the watch must survive beyond the current turn, render a task snippet with
+   `render_watch_heartbeat.py` and append it under `HEARTBEAT.md -> Active Tasks`.
+   - or apply the full bundle directly with `apply_followup_bundle_to_heartbeat.py`
+5. If the watch should be scheduled through the `cron` tool, render a
+   `cron_request` block with `render_watch_cron_request.py`.
+6. If the consumer needs the operator route plus heartbeat and cron scaffolding
+   together, emit `watch_followup_bundle` with `render_watch_followup_bundle.py`.

package/dist/skills/web3-native-operator/references/ROUTING_STATE_MACHINE.md

@@ -0,0 +1,73 @@
+# Web3 Native Operator Routing State Machine
+
+Use this state machine once `web3-risk-gate` and `web3-transaction-simulator` have both produced
+normalized output.
+
+## Inputs
+
+- `intent`
+- `risk_gate.decision`
+- `risk_gate.coverage`
+- `simulation.status`
+- `simulation.readiness`
+- `simulation.venue`
+
+## States
+
+### `blocked`
+
+Enter when:
+
+- `risk_gate.decision = BLOCK`
+- or `simulation.status = FAIL`
+
+Result:
+
+- do not route to a write adapter
+- set `next_adapter = none` unless an explicit investigation follow-up is required
+- explain the blocker and preserve evidence
+
+### `needs-confirmation`
+
+Enter when:
+
+- `risk_gate.decision = WARN`
+- or `simulation.status = WARN`
+- or `simulation.readiness = needs-confirmation`
+
+Result:
+
+- prepare the venue route
+- require explicit confirmation before any write path
+
+### `ready-to-route`
+
+Enter when:
+
+- `risk_gate.decision = ALLOW`
+- and `simulation.status = PASS`
+- and `simulation.readiness = ready`
+
+Result:
+
+- emit the next adapter and execution mode
+
+### `investigate-more`
+
+Enter when:
+
+- `simulation.status = NO_SIMULATION`
+- or `risk_gate.coverage != complete` and the action is value-moving
+
+Result:
+
+- stop before execution
+- name the missing backend or evidence
+- route to `web3-trace-and-state-analysis` or another explicit follow-up skill instead of a write adapter
+
+## Venue Mapping
+
+- `simulation.venue = hyperliquid` -> next adapter `hyperliquid`
+- `simulation.venue = token-swap` or `simulation.action = swap` -> next adapter `token-swap`
+- `simulation.action = liquidity` -> next adapter `liquidity-planner`
+- if route safety still depends on call-path or state evidence -> add follow-up `web3-trace-and-state-analysis`

package/dist/skills/web3-native-operator/references/WATCH_CRON_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Watch Cron Request Template
+
+Use this template when a `watch_status` should be turned into a structured
+payload for the `cron` tool.
+
+```yaml
+cron_request:
+  action: add
+  message: Re-run whale-watcher for token:PEPE and summarize any new evidence. Escalate immediately if severity becomes high or critical.
+  cron_expr: "*/15 * * * *"
+  tz: Asia/Shanghai
+```
+
+## Required Fields
+
+- `action`: always `add`
+- `message`
+- one of:
+  - `every_seconds`
+  - `cron_expr`
+  - `at`
+
+## Notes
+
+- Keep the `message` executable by the agent, not just descriptive.
+- `tz` is only valid with `cron_expr`.

package/dist/skills/web3-native-operator/references/WATCH_FOLLOWUP_BUNDLE_TEMPLATE.md

@@ -0,0 +1,35 @@
+# Watch Follow-Up Bundle Template
+
+Use this template when a normalized `watch_status` should be turned into all
+downstream runtime artifacts in one shot.
+
+```yaml
+watch_followup_bundle:
+  version: 1
+  watch_status:
+    status: ACTIVE
+    watch_kind: research
+    subject: token:PEPE
+    trigger_source: whale-watcher
+    severity: medium
+    next_check_hint: refresh whale flow after 15 minutes
+    schedule_hint: "*/15 * * * *"
+    recommended_adapter: whale-watcher
+  operator_bundle:
+    workflow_kind: watch
+    state: monitor-watch
+    next_adapter: whale-watcher
+    execution_mode: monitor
+  heartbeat_task: |
+    - [ ] Watch token:PEPE
+      Task: Re-run whale-watcher for token:PEPE on heartbeat and summarize any new evidence. Escalate immediately if severity becomes high or critical.
+  cron_request:
+    action: add
+    cron_expr: "*/15 * * * *"
+    tz: Asia/Shanghai
+```
+
+## Notes
+
+- `cron_request` may be `null` when the watch is not being promoted to a real scheduled job.
+- `heartbeat_task` remains useful even when `cron_request` is absent.