ai-skills: Back up AI agent skills in jiyuu/ai-skills

README.md

@@ -7,7 +7,7 @@
 | Path | Description |
 | ---- | ----------- |
 | <span style="white-space: nowrap;">📂 [algos](./algos/algos-notes.md)</span> | Algorithm practice problems with Go implementations and Anki-formatted notes for deliberate practice |
-| <span style="white-space: nowrap;">📂 [aictx](./aictx/README.md)</span> | File to context convertor for pasing files to feed LLMs. Similar to `cat` and `bat`. |
+| <span style="white-space: nowrap;">📂 [ctxcat](./ctxcat/README.md)</span> | File to context convertor for pasing files to feed LLMs. Similar to `cat` and `bat`. |
 | <span style="white-space: nowrap;">📂 [gocovmerge](./gocovmerge/README.md)</span> | Go coverage profile merger with modern CLI features |
 | <span style="white-space: nowrap;">📂 [mdtoc](./mdtoc/README.md)</span> | Markdown table of contents (TOC) generator |
 | <span style="white-space: nowrap;">📂 [winfixtext](./winfixtext/README.md)</span> | Fixes Windows encoding issues and corrupted LLM text outputs |

ai-skills/commit-diff/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: commit-diff
+description: >-
+  Generate a clear, cogent, concise, and conventional-like commit message from
+  the relevant git diff. Default is staged changes (what will be committed). Use
+  when the user asks for a commit message, says "save/commit", or asks to
+  summarize staged, working tree, or last commit changes.
+---
+
+# Commit Diff
+
+## When to Apply
+
+Use this skill when the user wants a commit message written from their `git diff`, or when they ask for a commit message for their changes without specifying
+one.
+
+## Instructions
+
+### 0) Confirm what the user wants to summarize
+
+Default to **what will be committed** (staged changes). If the user's phrasing is ambiguous, pick the most likely intent from the table below.
+
+| User intent (trigger phrases) | Use this command | Notes |
+|---|---|---|
+| "commit message", "save", "ready to commit", "staged", "what I'm about to commit" (default) | `git diff --staged` | Exactly what `git commit` would include right now. |
+| "latest changes", "since last commit", "working tree", "everything I changed" | `git diff HEAD` | Includes staged + unstaged changes vs last commit. |
+| "what's in my last commit", "latest commit", "changes in commit" | `git show HEAD` | Shows the patch for the last commit (includes new files). |
+| "compare to main", "PR diff", "branch delta", "since branching" | `git diff <base>...HEAD` | Merge-base diff (commits on this branch). If `<base>` not given, assume `main` but ask once to confirm. |
+
+If `git diff --staged` is empty, check `git status`. If there are only unstaged changes, either ask the user to stage what they want committed or switch to `git diff HEAD` to summarize the whole working tree.
+
+### 1) Untracked files gotcha (new files)
+
+Diffs only include **tracked** content.
+
+- If `git status` shows `?? some-file`, that file will not appear in `git diff --staged` or `git diff HEAD` until you stage it.
+- If you want a diff that includes new files without fully staging them, use `git add -N <file>` (intent-to-add), then rerun the chosen diff.
+
+### 2) Write the commit message (Conventional Commits)
+
+Output **one subject line**, plus an optional body when it helps explain "why".
+
+Subject format:
+
+`type(scope): imperative summary`
+
+- **type**: prefer one of `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `build`, `ci`
+- **scope**: optional, short (e.g. `sai`, `indexer`, `scripts`, `docs`)
+- **imperative**: "add", "fix", "remove", "refactor" (not past tense)
+- **length**: keep subject <= 72 chars; no trailing period
+- **breaking changes**: add `!` after type/scope when clearly breaking (`feat!: …`, `feat(api)!: …`)
+
+Body (optional):
+
+- Blank line after subject
+- 1–3 bullets focusing on **why** and any non-obvious behavior changes
+
+### Examples
+
+```
+feat(sai): add vault OI query helpers
+```
+
+```
+fix(indexer): query staking data via staking container
+
+- Avoid deprecated root-level fields
+- Clarify amount units (unibi) in output
+```
+
+```
+chore(scripts): align tx query output formatting
+```

ai-skills/epics-plus/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: epics-plus
+description: Discover, read, and manage Epics+ markdown documents in the boku repository. Use when asked about active tasks, priorities, epics for specific repos or tags, or when needing to regenerate the epic index (INDEX.md) using the epics-plus CLI.
+---
+
+# Epics+ Management
+
+Navigate, interpret, and manage Epics+ docs in the boku repository. Use this skill to understand the status and priority of work, and to use the `epics-plus` tooling.
+
+## Quick Start
+
+1. **Check active work**: Read [epics/INDEX.md](/home/realu/ki/boku/epics/INDEX.md) for the current dashboard of active epics grouped by priority.
+2. **Regenerate index**: If you've modified frontmatter or added an epic, update the dashboard:
+   ```bash
+   cd /home/realu/ki/boku/epics && just epics-plus index
+   ```
+3. **Verify/Scan**: To see all epics with frontmatter or validate them:
+   ```bash
+   cd /home/realu/ki/boku/epics && just epics-plus scan --only-with-frontmatter --strict
+   ```
+
+## Interpreting Epics+ Frontmatter (Reader View)
+
+When reading an epic doc, look at the YAML frontmatter at line 1 for context:
+
+- **status**: `active` | `inactive` | `done` | `archived`.
+- **priority**: `p0` (urgent) to `p3` (someday). `p2` is default.
+- **epic_kind**: `spec` | `journal` | `reference`.
+- **tags**: Broad themes (e.g., `sai`, `evm`, `slashing`). Use for "related work" queries.
+- **repos**: Which codebase this epic targets (e.g., `nibi-chain`, `sai-keeper`).
+- **related_context**: Links to other epics (`/epics/...`). Follow these to understand dependencies.
+- **agent_skills**: Cursor skill IDs relevant to this epic. Suggest using them when working on the task.
+
+## Recommended Workflow
+
+### 1. Triage / "What's Active?"
+Read [epics/INDEX.md](/home/realu/ki/boku/epics/INDEX.md). If you think it might be stale, run `just epics-plus index --dry-run` to see the current state without writing.
+
+### 2. Deep Dive / Context Gathering
+When assigned to an epic, open the file and:
+- Check `related_context` and `tags` to find relevant background docs.
+- Use `repos` to identify the target codebase and cross-reference with the `repo-map` skill.
+- Check `agent_skills` to see if specific domain expertise is required.
+
+### 3. Maintenance
+Regenerate the index after any frontmatter changes so the dashboard stays accurate.
+
+## Commands Reference
+
+Run from `/home/realu/ki/boku/epics`:
+
+- `just epics-plus index`: Writes `INDEX.md`.
+  - `--dry-run`: Print to stdout instead.
+  - `--all-statuses`: Include inactive/done/archived epics.
+- `just epics-plus scan`: List epics.
+  - `--only-with-frontmatter`: Skip files without Epics+ YAML.
+  - `--strict`: Exit non-zero if validation fails.
+  - `--format ndjson`: Useful for batch processing.
+
+## Additional Resources
+- Full schema and semantics: [epics/26-02-24-epics-plus.md](/home/realu/ki/boku/epics/26-02-24-epics-plus.md)
+- Index generation dashboard: [epics/INDEX.md](/home/realu/ki/boku/epics/INDEX.md)

ai-skills/epics-plus/reference.md

@@ -0,0 +1,31 @@
+# Epics+ Reference
+
+Detailed reference for the Epics+ system in boku.
+
+## Schema & Semantics
+The canonical source for the Epics+ v1 schema is:
+[epics/26-02-24-epics-plus.md](/home/realu/ki/boku/epics/26-02-24-epics-plus.md)
+
+### Key Field Meanings (Reader View)
+- **status**:
+  - `active`: In motion; expect to touch this again.
+  - `inactive`: Paused, but still relevant.
+  - `done`: Complete; useful as reference.
+  - `archived`: Intentionally out of circulation.
+- **priority**:
+  - `p0`: Urgent / drop-everything.
+  - `p1`: Important, should move soon.
+  - `p2`: Normal / default.
+  - `p3`: Nice-to-have / someday.
+
+## Index Generation (INDEX.md)
+The file [epics/INDEX.md](/home/realu/ki/boku/epics/INDEX.md) is a generated dashboard.
+
+- **Grouping**: Active epics are grouped by `priority` (p0 → p3).
+- **Links**: Links in the index use the `/epics/` prefix as per the project's standard.
+- **Regeneration**: If the file feels stale, run `cd /home/realu/ki/boku/epics && just epics-plus index`.
+
+## Relationship to Other Agents/Skills
+- **epics-frontmatter agent**: Used for *writing* frontmatter (adding/updating YAML).
+- **repo-map skill**: Use the `repos` field in an epic's frontmatter to find the target repository in the `repo-map` skill.
+- **agent_skills**: These fields in the frontmatter should be treated as suggestions for which skills to apply when working on the epic's tasks.

ai-skills/evm-rpc/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: evm-rpc
+description: Query EVM JSON-RPC methods for transaction debugging and endpoint
+  triage, including eth_getTransactionReceipt and debug_traceTransaction. Use
+  when the user asks to inspect tx status, retrieve receipts, run tracers,
+  compare EVM vs Cosmos outcomes, or choose between EVM RPC and Comet RPC
+  endpoints.
+---
+
+# EVM RPC: Receipt and Trace Playbook
+
+Use this skill for EVM transaction debugging with JSON-RPC.
+
+## Quick Start
+
+Set a hash and endpoint, then run receipt first and trace second.
+
+```bash
+evm_tx="0xYOUR_evm_tx"
+EVM_RPC="https://evm-rpc.archive.testnet-2.nibiru.fi"
+
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$evm_tx\"],\"id\":1}" \
+  "$EVM_RPC" | jq
+
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"debug_traceTransaction\",\"params\":[\"$evm_tx\",{\"tracer\":\"callTracer\"}],\"id\":1}" \
+  "$EVM_RPC" | jq
+```
+
+## Endpoint Map - Nibiru Examples
+
+Chain-agnostic rule: methods determine endpoint family.
+
+| Purpose | Example endpoint | Methods |
+|---|---|---|
+| EVM JSON-RPC (mainnet) | `https://evm-rpc.nibiru.fi` | `eth_*`, `debug_*`, `net_*`, `web3_*` |
+| EVM JSON-RPC archive (mainnet) | `https://evm-rpc.archive.nibiru.fi` | historical reads, tracing |
+| EVM JSON-RPC archive (testnet) | `https://evm-rpc.archive.testnet-2.nibiru.fi` | testnet tracing and historical reads |
+| Comet RPC archive (mainnet) | `https://rpc.archive.nibiru.fi` | `/block_results`, `/consensus_params` |
+| Comet RPC archive (testnet) | `https://rpc.archive.testnet-2.nibiru.fi` | `/block_results`, `/consensus_params` |
+
+Rules:
+- Run `eth_*` and `debug_*` only on EVM RPC endpoints.
+- Run `/block_results` and `/consensus_params` only on Comet RPC endpoints.
+- Prefer archive endpoints for old heights/hashes and tracing workflows.
+
+## Basic Queries (Health / Identity)
+
+### web3_clientVersion
+
+Queries the traceability info like the client name, version, Git commit, Go version,
+runtime architecture, and build tags.
+
+```bash
+curl -X POST https://evm-rpc.nibiru.fi \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "web3_clientVersion",
+    "params": [],
+    "id": 1
+  }'
+```
+
+The response looks like this: "Nibiru 2.6.0: Compiled at Git commit 3cf97e3468f8ce922c8760f839f8f336ca0c37f4 using Go go1.24.5, arch amd64, and build tags (netgo osusergo ledger static rocksdb pebbledb muslc)"
+
+### eth_chainId
+
+Queries the EIP-155 replay-protection chain id for the current ethereum blockchain (Nibiru).
+
+```bash
+curl -X POST https://evm-rpc.nibiru.fi \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "eth_chainId",
+    "params": [],
+    "id": 1
+  }'
+```
+
+## Transaction Triage Workflow
+
+Use this sequence to avoid false conclusions:
+
+1. `eth_getTransactionByHash`
+   - Confirms the tx exists and gives gas fields, type, input, and block refs.
+2. `eth_getTransactionReceipt`
+   - Authoritative EVM execution result.
+3. `debug_traceTransaction` (usually `callTracer`)
+   - Explains internal call path and where execution diverged.
+4. Optional cross-layer checks on Comet RPC
+   - `block_results?height=...`, `consensus_params?height=...`.
+
+## Concrete Command Cookbook
+
+### 1 - Get Transaction by Hash
+
+```bash
+evm_tx="0xYOUR_evm_tx"
+EVM_RPC="https://evm-rpc.archive.testnet-2.nibiru.fi"
+
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionByHash\",\"params\":[\"$evm_tx\"],\"id\":1}" \
+  "$EVM_RPC" | jq
+```
+
+### 2 - Get Transaction Receipt - Authoritative Status
+
+```bash
+evm_tx="0xYOUR_evm_tx"
+EVM_RPC="https://evm-rpc.archive.testnet-2.nibiru.fi"
+
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$evm_tx\"],\"id\":1}" \
+  "$EVM_RPC" | jq
+```
+
+Interpretation:
+- `result == null`: **Not mined** or rejected. Either the tx is still in the mempool, it was dropped, or it failed consensus/validation (e.g., bad nonce, invalid signature, insufficient funds for gas). It is not in any block.
+- `status == "0x1"`: **Full Success**. The transaction was executed successfully, and all state changes were applied.
+- `status == "0x0"`: **Execution Failure (Revert)**. The transaction was successfully mined and included in a block (consuming gas), but the EVM execution was reverted. No state changes occurred except for the gas fee deduction from the sender.
+- `blockNumber` present: Mined/included in a block.
+- `logs` present: Events emitted (decode by `address`, `topics`, `data`). Note that a reverted tx (`0x0`) will generally have an empty `logs` array, even if it attempted to emit them before reverting.
+
+### 3 - Run Debug Tracer - Call Tree View
+
+```bash
+evm_tx="0xYOUR_evm_tx"
+EVM_RPC="https://evm-rpc.archive.testnet-2.nibiru.fi"
+
+curl -s -X POST \
+  -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"debug_traceTransaction\",\"params\":[\"$evm_tx\",{\"tracer\":\"callTracer\"}],\"id\":1}" \
+  "$EVM_RPC" | jq
+```
+
+Interpretation:
+- Inspect top-level `from`, `to`, `gas`, `gasUsed`.
+- Walk `calls[]` for internal call chain and outputs.
+- Use trace to explain behavior; use receipt status to decide success/failure.
+
+### 4 - Cross-Layer Checks with Comet RPC
+
+```bash
+HEIGHT="5959008"
+TM_RPC="https://rpc.archive.testnet-2.nibiru.fi"
+
+curl -s "$TM_RPC/block_results?height=$HEIGHT" | jq
+curl -s "$TM_RPC/consensus_params?height=$HEIGHT" | jq
+```
+
+Use when EVM and Cosmos observations appear inconsistent.
+
+## Receipt and Trace Rules of Thumb
+
+- **Receipt status is the authoritative EVM truth** for success vs. failure.
+- **Mined does not mean successful**: A transaction can be in a block and consume gas (`0x0`), but have zero effect on state. Always check the `status` field.
+- **Null receipt implies non-existence**: If `eth_getTransactionReceipt` returns `null`, the transaction was never mined. This is usually due to a consensus/mempool error (invalid signature, wrong chain ID, bad nonce, or insufficient funds to cover the max gas cost).
+- **Consensus failures don't have receipts**: Errors like "insufficient funds" or "bad nonce" prevent a transaction from even entering a block, so no EVM status is ever generated.
+- **A non-empty `logs` array** (at the receipt level) generally only exists for successful transactions (`0x1`).
+- **Gas consumption**: Even in failure (`0x0`), the `gasUsed` is still charged to the sender up to the point of reversion.
+- **Gas Comparison**: Compare receipt `gasUsed` with the `gas` (limit) from `eth_getTransactionByHash` to see if the transaction ran out of gas.
+- **Tracing Failures**: If tracing fails, verify the provider supports the `debug` namespace and retry on an archive endpoint.
+
+## Endpoint Selection Guide
+
+Choose endpoint by method and historical depth:
+
+- Latest, simple reads (`eth_blockNumber`, recent receipt):
+  - Standard EVM RPC is usually enough.
+- Historical receipts, old block state, trace/debug:
+  - Prefer archive EVM RPC.
+- Tendermint/Comet block metadata and app-level event correlation:
+  - Use Comet RPC endpoints.
+
+## Common Pitfalls
+
+- Calling Comet paths on EVM RPC host (or the reverse).
+- Using the wrong network endpoint for a valid tx hash.
+- Assuming `result == null` always means pending; it may be wrong chain/provider.
+- Treating trace output alone as final status without reading receipt.
+- Ignoring timeout/retry behavior for freshly broadcast transactions.
+
+## Reusable Triage Template
+
+```bash
+evm_tx="0xYOUR_evm_tx"
+EVM_RPC="https://evm-rpc.archive.testnet-2.nibiru.fi"
+TM_RPC="https://rpc.archive.testnet-2.nibiru.fi"
+
+# 1) tx details
+curl -s -X POST -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionByHash\",\"params\":[\"$evm_tx\"],\"id\":1}" \
+  "$EVM_RPC" | jq
+
+# 2) receipt status
+curl -s -X POST -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"eth_getTransactionReceipt\",\"params\":[\"$evm_tx\"],\"id\":1}" \
+  "$EVM_RPC" | jq
+
+# 3) call trace
+curl -s -X POST -H "Content-Type: application/json" \
+  --data "{\"jsonrpc\":\"2.0\",\"method\":\"debug_traceTransaction\",\"params\":[\"$evm_tx\",{\"tracer\":\"callTracer\"}],\"id\":1}" \
+  "$EVM_RPC" | jq
+```
+
+## Additional Resources
+
+- Zero-gas debug walkthrough:
+  `/home/realu/ki/boku/epics/epic-evm/26-02-zero-gas/26-02-10-zero-gas-debug.md`
+- Existing endpoint conventions:
+  `/home/realu/ki/boku/nibi/cook/index.ts`