Skill: alibabaedge/logos-node (version 1.0.0)

--- name: logos-node description: > Install, update, or check the status of a Logos Blockchain testnet validator node on Linux x86_64. Use this skill when the user wants to set up a Logos node, join the testnet, perform a breaking upgrade, or troubleshoot a running node. version: "1.0.0" allowed-tools: - Bash - Read - Write - WebFetch metadata: openclaw: requires: bins: - curl - tar - systemctl category: infrastructure --- # Logos Node Skill You are a Logos Blockchain node operator assistant. When the user invokes this skill, read `$ARGUMENTS` to determine the command: - `install` → fresh install of a Logos validator node - `update` → breaking upgrade (wipe state, re-init, restart) - `status` → check sync mode, peers, block height, wallet balance If `$ARGUMENTS` is empty, ask the user which operation they want: install / update / status. --- ## ALWAYS do this first Before taking any action, fetch the **latest stable** release — filtering out pre-releases and release candidates (RC). `/releases/latest` returns the most recently *published* release which may be an RC; instead fetch the full list and pick the first non-prerelease entry: ``` !`curl -s https://api.github.com/repos/logos-blockchain/logos-blockchain/releases | python3 -c "import sys,json; releases=[r for r in json.load(sys.stdin) if not r['prerelease'] and not r['draft']]; r=releases[0]; print(json.dumps({'tag':r['tag_name'],'assets':[{'name':a['name'],'url':a['browser_download_url']} for a in r['assets']],'body':r['body'][:2000]}))" 2>/dev/null` ``` From the response extract: - `tag` — stable version (e.g. `0.1.2`) — **ignore any tag containing `-rc`, `-dev`, or `-beta`** - `assets[].url` — filter for `linux-x86_64` binary tarball and circuits tarball - `body` — breaking-change notice and bootstrap peers If the API call fails or returns no stable release, fall back to the official quickstart docs: ``` !`curl -s https://raw.githubusercontent.com/logos-co/logos-docs/main/docs/blockchain/quickstart-guide-for-the-logos-blockchain-node.md | head -120` ``` Also check [sharp-edges.md](./sharp-edges.md) before every install or update. --- ## install — Fresh node installation Follow [install-procedure.md](./install-procedure.md) step by step. Key checkpoints: 1. Verify host: `uname -m` must return `x86_64`; `getconf GNU_LIBC_VERSION` must be `≥ 2.39` 2. Create service user `logos`, directories under `/pool0/logos` 3. Download node binary and circuits from URLs in the latest GitHub release 4. Export `LOGOS_BLOCKCHAIN_CIRCUITS` **before** running `init` 5. Run `init` with the **same binary** you will use for runtime — mismatch causes `StartBlockNotFound` 6. Run `init` with the bootstrap peers from the latest release body 7. Create and start the `logos-blockchain-node` systemd service 8. Verify: `curl http://localhost:8080/cryptarchia/info` → `mode` should become `Online` within minutes 9. Open peer port: `ufw allow 3000/udp` --- ## update — Breaking upgrade Follow [update-procedure.md](./update-procedure.md). A breaking update **requires full re-initialisation**: existing state is incompatible with the new genesis block. Skipping any deletion step causes genesis mismatch errors. Key checkpoints: 1. Stop the service: `systemctl stop logos-blockchain-node` 2. Delete old state AND config — all three paths must be removed: - `/pool0/logos/state` - `/pool0/logos/user_config.yaml` - `/pool0/logos/.logos-blockchain-circuits` 3. Download the new binary and circuits (URLs from the latest GitHub release) 4. Export `LOGOS_BLOCKCHAIN_CIRCUITS` before `init` 5. Run `init` with the **new binary** and the new bootstrap peers 6. Restart: `systemctl start logos-blockchain-node` 7. Verify sync and confirm `mode: Online` --- ## status — Node health check Follow [status-checks.md](./status-checks.md). Run these checks: ```bash systemctl status logos-blockchain-node --no-pager curl -w "\n" http://localhost:8080/cryptarchia/info curl -w "\n" http://localhost:8080/network/info ``` Interpret results: - `mode: Online` — node is fully synced and participating - `mode: Bootstrapping` — still in initial block download (IBD); wait and recheck - `n_peers: 0` — no P2P connectivity; check firewall (`ufw status`) and port 3000/udp - `slot` / `height` not increasing — node may be stalled; check logs with `journalctl -u logos-blockchain-node -f` To check wallet balance (replace `<key>` with hex key from `user_config.yaml`): ```bash grep -A3 known_keys /pool0/logos/user_config.yaml curl http://localhost:8080/wallet/<key>/balance ``` --- <!-- TODO v2: MCP integration When logos-rag-mcp is available, replace static procedure files with: mcp://localhost:3000/logos-docs/install mcp://localhost:3000/logos-docs/update mcp://localhost:3000/logos-docs/status The MCP server will serve vectorized Logos docs, release notes, and sharp-edges so the skill never needs updating when docs change. See mcp/README.md. -->

path: skill/update-procedure.md
content: # Logos Node — Update Procedure (Breaking Release)

> This procedure applies to any release marked **breaking** in the release notes.
> Breaking updates require full re-initialisation: old state is incompatible with
> the new genesis block.

Read [sharp-edges.md](./sharp-edges.md) before starting.

---

## When is an update breaking?

The release notes on GitHub will say:
> "This is a breaking update. Existing node operators will need to delete their node data before rejoining."

If the release does NOT say breaking, you may be able to just swap the binary (check the notes).

---

## Step 0 — Fetch the latest stable release

Fetch the full release list and pick the first **non-prerelease** entry.
`/releases/latest` may return an RC — always filter explicitly:

```bash
curl -s https://api.github.com/repos/logos-blockchain/logos-blockchain/releases \
  | python3 -c "
import sys, json
releases = [r for r in json.load(sys.stdin) if not r['prerelease'] and not r['draft']]
r = releases[0]
print('tag:', r['tag_name'])
for a in r['assets']:
    print('asset:', a['name'], '->', a['browser_download_url'])
print()
print(r['body'][:2000])
"
```

Ignore any tag containing `-rc`, `-dev`, or `-beta`.
If the API is unreachable, check the official quickstart:
`https://github.com/logos-co/logos-docs/blob/main/docs/blockchain/quickstart-guide-for-the-logos-blockchain-node.md`

Note from the response:
- Stable version tag
- Asset URLs for the `linux-x86_64` binary tarball and circuits tarball
- New bootstrap peers (may differ from previous release)
- Whether this is a breaking release

---

## Step 1 — Stop the service

```bash
systemctl stop logos-blockchain-node
systemctl status logos-blockchain-node --no-pager
```

Wait until the service shows `inactive (dead)` before continuing.

---

## Step 2 — Delete old state, config, and circuits

All three paths must be removed. Skipping any one causes genesis mismatch errors.

```bash
rm -rf /pool0/logos/state
rm -f  /pool0/logos/user_config.yaml
rm -rf /pool0/logos/.logos-blockchain-circuits
```

Verify all are gone:
```bash
ls /pool0/logos/
```

Expected: only the old binary tarball(s) and binary file remain — no `state/`, no `user_config.yaml`, no `.logos-blockchain-circuits`.

---

## Step 3 — Download new binary and circuits

Replace URLs with values from the latest release JSON fetched in Step 0.

```bash
su - logos -c '
set -e
cd /pool0/logos

# new binary
curl -L -o logos-blockchain-node-new.tar.gz "<NEW_BINARY_URL>"
tar -xf logos-blockchain-node-new.tar.gz
# the binary will overwrite the old one in-place

# new circuits
curl -L -o logos-blockchain-circuits-new.tar.gz "<NEW_CIRCUITS_URL>"
tar -xf logos-blockchain-circuits-new.tar.gz
mv /pool0/logos/logos-blockchain-circuits-* /pool0/logos/.logos-blockchain-circuits
'
```

Verify the version:
```bash
su - logos -c '/pool0/logos/logos-blockchain-node --version'
```

---

## Step 4 — Re-initialise with the new bootstrap peers

`LOGOS_BLOCKCHAIN_CIRCUITS` must be exported **before** `init`.
Use the peer list from the new release body (it may differ from the previous release).

```bash
su - logos -c '
cd /pool0/logos
export LOGOS_BLOCKCHAIN_CIRCUITS=/pool0/logos/.logos-blockchain-circuits
./logos-blockchain-node init \
  -p /ip4/65.109.51.37/udp/3000/quic-v1/p2p/12D3KooWFrouXfmrR4nsLMtE7wu15DoMJ6VtoUtHinREZCvbWHar \
  -p /ip4/65.109.51.37/udp/3001/quic-v1/p2p/12D3KooWJRGau8M1rjT7R5e4YYsgdFhsMX35nRDtMwCDjxQkXAHz \
  -p /ip4/65.109.51.37/udp/3002/quic-v1/p2p/12D3KooWQXJavMDTRscjauFSgVAB1VLB6Rzpy2uY5SU9Tk7927tb \
  -p /ip4/65.109.51.37/udp/3003/quic-v1/p2p/12D3KooWSQc7CcGtvWDPF1yCbBthFnQjprfCVHmfmNDUrSmqQsU1
'
```

> **Critical**: the peers above are the v0.1.2 bootstrap peers. Always use the peers from the
> **current release body**, not hardcoded values from this file. See SKILL.md Step 0.

After `init` completes, a new wallet key is printed and saved to `user_config.yaml`.
The old wallet key is gone — faucet again if needed.

---

## Step 5 — Restart the service

The systemd unit does not need to be recreated (it uses the same binary path).

```bash
systemctl daemon-reload
systemctl start logos-blockchain-node
systemctl status logos-blockchain-node --no-pager
```

---

## Step 6 — Verify sync

```bash
curl -w "\n" http://localhost:8080/cryptarchia/info
curl -w "\n" http://localhost:8080/network/info
```

Wait until `mode` changes from `Bootstrapping` to `Online`.
If `n_peers` stays at 0 for more than 2 minutes, check:
```bash
ufw status
journalctl -u logos-blockchain-node --no-pager -n 50
```

---

## Checklist

- [ ] Service stopped
- [ ] `/pool0/logos/state` deleted
- [ ] `/pool0/logos/user_config.yaml` deleted
- [ ] `/pool0/logos/.logos-blockchain-circuits` deleted
- [ ] New binary downloaded and verified
- [ ] New circuits downloaded and moved into place
- [ ] `LOGOS_BLOCKCHAIN_CIRCUITS` exported before `init`
- [ ] `init` run with new binary and new peers
- [ ] Service restarted
- [ ] `mode: Online` confirmed


path: skill/sharp-edges.md
content: # Logos Node — Sharp Edges

Operational gotchas observed during actual node deployments. Read before every install or update.

---

## 1. `init` binary must match runtime binary

**Problem**: Running `init` with one binary version and then starting the node with a different
version generates an incompatible genesis block. Every subsequent node start fails with:
```
StartBlockNotFound
```

**Rule**: The binary you pass to `./logos-blockchain-node init` and the binary in the systemd
`ExecStart` line must be the **exact same file**.

If you downloaded a new binary, re-run `init` before starting the service.

---

## 2. `LOGOS_BLOCKCHAIN_CIRCUITS` must be exported before `init`

**Problem**: If the env var is not set when `init` runs, the circuits path is not written into
`user_config.yaml`. The node starts but immediately crashes looking for ZK circuits.

**Rule**: Always run:
```bash
export LOGOS_BLOCKCHAIN_CIRCUITS=/pool0/logos/.logos-blockchain-circuits
./logos-blockchain-node init ...
```

The systemd unit sets this var via `Environment=`, but `init` is run manually — you must export it yourself.

---

## 3. Breaking update = delete ALL three paths

A breaking update is not a binary swap. Three separate artifacts must be removed:

| Path | Why |
|---|---|
| `/pool0/logos/state` | Old chain state — incompatible with new genesis |
| `/pool0/logos/user_config.yaml` | Old config — references old genesis hash and old peers |
| `/pool0/logos/.logos-blockchain-circuits` | Old ZK circuits — may not match new proof format |

Missing any one path causes either a genesis mismatch on start or a silent ZK failure.

---

## 4. Ubuntu 22.04 is NOT supported

**Problem**: Ubuntu 22.04 ships `glibc 2.35`. The Logos binary requires `glibc ≥ 2.39`.
The binary will fail to run with:
```
/lib/x86_64-linux-gnu/libc.so.6: version GLIBC_2.38 not found
```

**Rule**: Use Ubuntu 24.04 or Debian 12+. Always check before downloading:
```bash
getconf GNU_LIBC_VERSION
```

---

## 5. ARM is not supported

The official release only ships `linux-x86_64`. There is no `aarch64` / ARM binary.
Do not attempt to run under QEMU emulation — it is too slow for block production timing.

---

## 6. Bootstrap peers change between breaking releases

The bootstrap peer addresses (IP + peer ID) are embedded in `user_config.yaml` during `init`.
They may change with each breaking release. Always use the peer list from the **current release
body** on GitHub, not from this file or any old runbook.

Current v0.1.2 peers:
```
/ip4/65.109.51.37/udp/3000/quic-v1/p2p/12D3KooWFrouXfmrR4nsLMtE7wu15DoMJ6VtoUtHinREZCvbWHar
/ip4/65.109.51.37/udp/3001/quic-v1/p2p/12D3KooWJRGau8M1rjT7R5e4YYsgdFhsMX35nRDtMwCDjxQkXAHz
/ip4/65.109.51.37/udp/3002/quic-v1/p2p/12D3KooWQXJavMDTRscjauFSgVAB1VLB6Rzpy2uY5SU9Tk7927tb
/ip4/65.109.51.37/udp/3003/quic-v1/p2p/12D3KooWSQc7CcGtvWDPF1yCbBthFnQjprfCVHmfmNDUrSmqQsU1
```

---

## 7. Wallet balance returns HTTP 400 during IBD

`GET /wallet/<key>/balance` returns:
```
Requested wallet state for unknown block: ...
```
while the node is still in `Bootstrapping` mode. This is expected — wait for `mode: Online`.

---

## 8. Peer port must be open on the host firewall

The default peer port is `3000/udp`. If `ufw` is active, you must allow it:
```bash
ufw allow 3000/udp
```

If the host is behind NAT, upstream port forwarding for `3000/udp` is also required.

---

## 9. Slot ≠ Block height (many empty slots)

Not every slot produces a block. The `slot` counter increments every 20 seconds regardless.
`height` only increments when a block is produced. During Bootstrapping, `height` may lag far
behind `slot`. This is normal behaviour — not a sign of a stuck node.

---

## 10. RC and devnet binaries cause testnet genesis mismatch

Logos occasionally publishes release candidates (e.g. `0.1.2-rc1`) and devnet binaries. These are
**not compatible** with the public testnet genesis. Only use binaries tagged without `-rc` or `-devnet`
from the releases page for testnet operation.


path: skill/status-checks.md
content: # Logos Node — Status Checks

Quick reference for verifying node health at any time.

---

## Service status

```bash
systemctl status logos-blockchain-node --no-pager
```

Expected: `active (running)`.

If `failed` or `inactive`, check logs:
```bash
journalctl -u logos-blockchain-node --no-pager -n 100
```

Common log errors and causes:

| Log line | Cause |
|---|---|
| `StartBlockNotFound` | Binary mismatch — `init` and runtime used different versions |
| `GLIBC_2.38 not found` | OS too old (need glibc ≥ 2.39) |
| `No such file or directory: circuits` | `LOGOS_BLOCKCHAIN_CIRCUITS` not set before `init` |
| `address already in use` | Another process using port 8080 or 3000 |

---

## Consensus info

```bash
curl -s http://localhost:8080/cryptarchia/info | python3 -m json.tool
```

Fields to check:

| Field | Good value | Problem if... |
|---|---|---|
| `mode` | `"Online"` | Still `"Bootstrapping"` after 30+ min → check peers |
| `slot` | Increasing | Not moving → node stalled; restart service |
| `height` | Increasing (slower than slot — normal) | Zero for a long time → sync not starting |
| `lib_slot` | Close to `slot` | Very far behind → still in IBD |

---

## Peer connectivity

```bash
curl -s http://localhost:8080/network/info | python3 -m json.tool
```

Fields to check:

| Field | Good value | Problem if... |
|---|---|---|
| `n_peers` | `> 0` (ideally 5–30) | 0 → firewall or NAT issue |
| `n_connections` | Same as `n_peers` | Mismatched → connection instability |
| `n_pending_connections` | Low or 0 | Very high → P2P storm (usually self-resolves) |

If `n_peers` is 0:
```bash
ufw status                     # is port 3000/udp open?
journalctl -u logos-blockchain-node -f   # look for connection errors
```

---

## Wallet balance

Find your key:
```bash
grep -A3 known_keys /pool0/logos/user_config.yaml
```

Check balance (replace `<key>` with the hex string from config):
```bash
curl -s http://localhost:8080/wallet/<key>/balance | python3 -m json.tool
```

Expected response:
```json
{
  "tip": "8f7523a0...",
  "balance": 1000,
  "notes": { "c73f3f3a...": 1000 },
  "address": "20385ef6..."
}
```

- `balance: 0` after faucet → wait 1–2 minutes and retry
- HTTP 400 `Requested wallet state for unknown block` → node still in IBD; wait for `mode: Online`

---

## Live block stream (optional)

To watch new blocks arrive in real time:
```bash
curl -N http://localhost:8080/cryptarchia/events/blocks/stream
```

Each block event confirms the node is actively participating in the network.

---

## Compare against official dashboard

The Logos team runs a public testnet dashboard (requires auth for full view):
```
https://testnet.blockchain.logos.co/web/
```

You can compare your node's `height` against the dashboard to confirm you are on the same chain.

---

## Day-2 operations

```bash
systemctl restart logos-blockchain-node    # restart
systemctl stop logos-blockchain-node       # stop
journalctl -u logos-blockchain-node -f     # follow live logs
journalctl -u logos-blockchain-node --since "1 hour ago"  # last hour
```


path: skill/install-procedure.md
content: # Logos Node — Install Procedure

> Generated from the official [v0.1.2 release notes](https://github.com/logos-blockchain/logos-blockchain/releases/tag/0.1.2)
> and the citizenweb3 runbook (`logos/docs/logos-testnet-v01-amd64-systemd.md`).
> 
> **Always fetch the latest release first** (SKILL.md Step 0) to get the current
> binary URLs and bootstrap peers before running these commands.

---

## Prerequisites

- Linux `x86_64` (no ARM binary provided)
- `glibc ≥ 2.39` — Ubuntu 22.04 ships 2.35 and is **not supported**
- `≥ 64 GB` free storage
- `curl`, `tar`, `systemctl` available
- Root (or sudo) access for systemd setup

## Step 0 — Verify host compatibility

```bash
uname -m            # must be x86_64
getconf GNU_LIBC_VERSION   # must be >= 2.39
df -h /pool0        # check free space
```

If glibc is too old, upgrade the OS before continuing.

## Step 1 — Create the service user and directories

```bash
apt update
apt install -y curl tar ca-certificates
id -u logos >/dev/null 2>&1 || useradd -m -s /bin/bash logos
install -d -o logos -g logos /pool0/logos /pool0/logos/.logos-blockchain-circuits
```

## Step 2 — Download binary and circuits

Replace `<VERSION>` and `<CIRCUITS_VERSION>` with values from the latest GitHub release response.

```bash
su - logos -c '
set -e
cd /pool0/logos

# node binary
curl -L -o logos-blockchain-node.tar.gz "<BINARY_URL_FROM_RELEASE>"
tar -xf logos-blockchain-node.tar.gz

# ZK circuits
curl -L -o logos-blockchain-circuits.tar.gz "<CIRCUITS_URL_FROM_RELEASE>"
tar -xf logos-blockchain-circuits.tar.gz
rm -rf /pool0/logos/.logos-blockchain-circuits
mv /pool0/logos/logos-blockchain-circuits-* /pool0/logos/.logos-blockchain-circuits
'
```

Verify binary is executable:
```bash
su - logos -c '/pool0/logos/logos-blockchain-node --version'
```

## Step 3 — Initialise node config

`LOGOS_BLOCKCHAIN_CIRCUITS` **must be exported** before running `init`.
The `-p` peers come from the `body` field of the latest GitHub release JSON.

```bash
su - logos -c '
cd /pool0/logos
export LOGOS_BLOCKCHAIN_CIRCUITS=/pool0/logos/.logos-blockchain-circuits
./logos-blockchain-node init \
  -p /ip4/65.109.51.37/udp/3000/quic-v1/p2p/12D3KooWFrouXfmrR4nsLMtE7wu15DoMJ6VtoUtHinREZCvbWHar \
  -p /ip4/65.109.51.37/udp/3001/quic-v1/p2p/12D3KooWJRGau8M1rjT7R5e4YYsgdFhsMX35nRDtMwCDjxQkXAHz \
  -p /ip4/65.109.51.37/udp/3002/quic-v1/p2p/12D3KooWQXJavMDTRscjauFSgVAB1VLB6Rzpy2uY5SU9Tk7927tb \
  -p /ip4/65.109.51.37/udp/3003/quic-v1/p2p/12D3KooWSQc7CcGtvWDPF1yCbBthFnQjprfCVHmfmNDUrSmqQsU1
'
```

> **Critical:** Use the **same binary** for `init` and for runtime. If you run `init` with an RC
> or devnet binary while connecting to testnet peers, the node generates an incompatible genesis
> and every subsequent start fails with `StartBlockNotFound`. See [sharp-edges.md](./sharp-edges.md).

After `init`, a wallet key is printed to stdout and saved to `user_config.yaml`. Save it.

## Step 4 — Create the systemd service

```bash
cat >/etc/systemd/system/logos-blockchain-node.service <<'EOF'
[Unit]
Description=Logos Blockchain Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=logos
Group=logos
WorkingDirectory=/pool0/logos
Environment=LOGOS_BLOCKCHAIN_CIRCUITS=/pool0/logos/.logos-blockchain-circuits
ExecStart=/pool0/logos/logos-blockchain-node /pool0/logos/user_config.yaml
Restart=on-failure
RestartSec=10
KillSignal=SIGINT
TimeoutStopSec=30
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF
```

## Step 5 — Start the node

```bash
systemctl daemon-reload
systemctl enable logos-blockchain-node
systemctl start logos-blockchain-node
systemctl status logos-blockchain-node --no-pager
```

## Step 6 — Open the peer port

```bash
ufw allow 3000/udp
ufw status
```

## Step 7 — Verify sync

```bash
curl -w "\n" http://localhost:8080/cryptarchia/info
curl -w "\n" http://localhost:8080/network/info
```

Expected progression:
- `mode: Bootstrapping` immediately after start (IBD in progress)
- `mode: Online` after sync completes (minutes to hours depending on chain length)
- `n_peers > 0` means P2P is working

Check slot/height again after 60 seconds — both should be increasing.

## Step 8 — Request faucet tokens

```bash
grep -A3 known_keys /pool0/logos/user_config.yaml
```

Take the hex key and visit the official faucet:
```
https://testnet.blockchain.logos.co/web/faucet/
```

After 1–2 minutes, verify the balance landed:
```bash
curl http://localhost:8080/wallet/<your_key>/balance
```

> Note: balance queries return HTTP 400 while the node is still in `Bootstrapping` mode.

## Step 9 — Wait for stake aging

The node begins participating in block production automatically after roughly 2 epochs
(≈ 3.5 hours) from when the funded wallet key was staked.


path: install.sh
content: #!/usr/bin/env bash
# install.sh — Logos Node skill installer (no npm required)
# Usage: curl -fsSL https://raw.githubusercontent.com/citizenweb3/ai-integrations/logos-node/install.sh | bash
set -euo pipefail

REPO="citizenweb3/ai-integrations"
BRANCH="logos-node"
SKILL_NAME="logos-node"
TARBALL="https://github.com/${REPO}/archive/refs/heads/${BRANCH}.tar.gz"
TMP_DIR="$(mktemp -d)"

GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

info()  { echo -e "${GREEN}[logos-node]${NC} $*"; }
warn()  { echo -e "${YELLOW}[logos-node]${NC} $*"; }

# Parse --global flag
GLOBAL=false
for arg in "$@"; do
  [[ "$arg" == "--global" || "$arg" == "-g" ]] && GLOBAL=true
done

info "Downloading skill from ${REPO}@${BRANCH}..."
curl -fsSL "$TARBALL" | tar -xz -C "$TMP_DIR" --strip-components=1
SKILL_SRC="${TMP_DIR}/skill"

# Agent detection
declare -A AGENTS
declare -A INSTALL_PATHS

detect_agents() {
  # Claude Code
  if [[ -d "${HOME}/.claude" || -d ".claude" ]]; then
    if $GLOBAL; then
      AGENTS[claude]="Claude Code"
      INSTALL_PATHS[claude]="${HOME}/.claude/skills/${SKILL_NAME}"
    else
      AGENTS[claude]="Claude Code"
      INSTALL_PATHS[claude]="${PWD}/.claude/skills/${SKILL_NAME}"
    fi
  fi

  # GitHub Copilot
  if [[ -d ".github/copilot" ]] || git remote -v 2>/dev/null | grep -q "github.com"; then
    if $GLOBAL; then
      AGENTS[copilot]="GitHub Copilot"
      INSTALL_PATHS[copilot]="${HOME}/.agents/skills/${SKILL_NAME}"
    else
      AGENTS[copilot]="GitHub Copilot"
      INSTALL_PATHS[copilot]="${PWD}/.agents/skills/${SKILL_NAME}"
    fi
  fi

  # Gemini CLI
  if [[ -d ".gemini" || -d "${HOME}/.gemini" || -n "${GEMINI_API_KEY:-}" ]]; then
    if $GLOBAL; then
      AGENTS[gemini]="Gemini CLI"
      INSTALL_PATHS[gemini]="${HOME}/.gemini/skills/${SKILL_NAME}"
    else
      AGENTS[gemini]="Gemini CLI"
      INSTALL_PATHS[gemini]="${PWD}/.gemini/skills/${SKILL_NAME}"
    fi
  fi

  # OpenAI Codex CLI
  if [[ -n "${OPENAI_API_KEY:-}" || -d ".codex" ]]; then
    if $GLOBAL; then
      AGENTS[codex]="OpenAI Codex CLI"
      INSTALL_PATHS[codex]="${HOME}/.agents/skills/${SKILL_NAME}"
    else
      AGENTS[codex]="OpenAI Codex CLI"
      INSTALL_PATHS[codex]="${PWD}/.agents/skills/${SKILL_NAME}"
    fi
  fi

  # opencode
  if [[ -d ".opencode" || -f "opencode.json" ]] || command -v opencode &>/dev/null; then
    if $GLOBAL; then
      AGENTS[opencode]="opencode"
      INSTALL_PATHS[opencode]="${HOME}/.config/opencode/skills/${SKILL_NAME}"
    else
      AGENTS[opencode]="opencode"
      INSTALL_PATHS[opencode]="${PWD}/.opencode/skills/${SKILL_NAME}"
    fi
  fi

  # OpenClaw (always global — personal assistant)
  if [[ -d "${HOME}/.openclaw" || -f "openclaw.json" ]] || command -v openclaw &>/dev/null; then
    AGENTS[openclaw]="OpenClaw"
    INSTALL_PATHS[openclaw]="${HOME}/.openclaw/skills/${SKILL_NAME}"
  fi
}

install_skill() {
  local agent="$1"
  local path="${INSTALL_PATHS[$agent]}"
  info "Installing for ${AGENTS[$agent]} → ${path}"
  mkdir -p "$path"
  cp -r "${SKILL_SRC}/." "$path/"
  info "✅ Done: ${path}"
}

detect_agents

if [[ ${#AGENTS[@]} -eq 0 ]]; then
  warn "No supported AI agents detected. Installing to ~/.agents/skills/${SKILL_NAME}"
  DEFAULT_PATH="${HOME}/.agents/skills/${SKILL_NAME}"
  mkdir -p "$DEFAULT_PATH"
  cp -r "${SKILL_SRC}/." "$DEFAULT_PATH/"
  info "✅ Installed to ${DEFAULT_PATH}"
else
  echo ""
  info "Detected agents:"
  for agent in "${!AGENTS[@]}"; do
    echo "  • ${AGENTS[$agent]} → ${INSTALL_PATHS[$agent]}"
  done
  echo ""

  for agent in "${!AGENTS[@]}"; do
    read -r -p "Install for ${AGENTS[$agent]}? [Y/n] " answer </dev/tty
    case "${answer,,}" in
      n|no) warn "Skipping ${AGENTS[$agent]}" ;;
      *)    install_skill "$agent" ;;
    esac
  done
fi

rm -rf "$TMP_DIR"

echo ""
info "Installation complete. To verify in your agent, run:"
echo "  /logos-node status"
echo ""
info "Available commands:"
echo "  /logos-node install   — fresh node setup"
echo "  /logos-node update    — breaking upgrade (wipe + re-init)"
echo "  /logos-node status    — check sync, peers, wallet balance"


path: mcp/README.md
content: # MCP Integration — v0.2 Placeholder

This directory is reserved for the future **logos-rag-mcp** server that will power
a smarter version of the Logos Node skill.

---

## Planned architecture

```
SKILL.md
  └─ MCP call: mcp://localhost:3000/logos-docs
       └─ logos-rag-mcp (citizenweb3/logos-rag-mcp — not yet published)
            ├─ Vectorized Logos documentation
            ├─ Release notes + breaking-change history
            ├─ Node API reference (logos-node-api.md)
            └─ Sharp-edges knowledge base
```

When the MCP server is available, the skill will replace static procedure file references
with live tool calls to retrieve up-to-date, context-aware instructions.

## Why MCP?

Static markdown files in `skill/` are good but have one limitation: if Logos releases a new
version with changed steps (new flags, new paths, new peer format), someone must manually
update the files in this repo.

With a RAG-backed MCP server:
- The server indexes the Logos docs repo automatically
- The skill always retrieves the most current instructions
- No PR to this repo needed for routine Logos version changes

## Activating in SKILL.md (when ready)

Uncomment the `# TODO v2` section in `skill/SKILL.md` and add:

```yaml
allowed-tools:
  - Bash
  - Read
  - Write
  - WebFetch
  - mcp__logos_docs__install
  - mcp__logos_docs__update
  - mcp__logos_docs__status
```

## Contributing

If you want to build logos-rag-mcp, open an issue in citizenweb3/ai-integrations
or start a PR in a new repo `citizenweb3/logos-rag-mcp`.


path: README.md
content: # logos-node — AI agent skill for Logos Blockchain

[![AgentSkills](https://img.shields.io/badge/AgentSkills-compatible-blue)](https://agentskills.io)
[![Works with Claude Code](https://img.shields.io/badge/Claude_Code-supported-orange)](https://claude.ai/code)
[![Works with Copilot](https://img.shields.io/badge/GitHub_Copilot-supported-blue)](https://github.com/features/copilot)

An AI agent skill that helps you **install, update, and operate a Logos Blockchain testnet validator node** on Linux x86_64.

The skill always fetches the latest release information from GitHub at runtime — no manual updates needed when a new Logos version ships.

---

## What this skill does

| Command | Action |
|---|---|
| `/logos-node install` | Fresh node installation: binary, circuits, systemd service, faucet |
| `/logos-node update` | Breaking upgrade: wipe state, re-init, restart with new binary |
| `/logos-node status` | Check sync mode, peers, block height, wallet balance |

---

## Requirements

- Linux `x86_64` server (no ARM support in current Logos releases)
- `glibc ≥ 2.39` (Ubuntu 24.04+, Debian 12+)
- `≥ 64 GB` free storage
- `curl`, `tar`, `systemctl` on the server
- Root or sudo access for systemd setup

---

## Installation

### Option 1 — npx (no install required)

```bash
# Install for current project
npx @citizenweb3/ai-integrations logos-node

# Install globally (available in all projects)
npx @citizenweb3/ai-integrations logos-node --global
```

### Option 2 — npm global install

```bash
npm install -g @citizenweb3/ai-integrations
ai-integrations logos-node
```

### Option 3 — Claude Code plugin marketplace

```
/plugin marketplace add citizenweb3/ai-integrations
/plugin install logos-node@citizenweb3
```

### Option 4 — OpenClaw / ClawHub

```bash
npx clawhub@latest install citizenweb3/logos-node
```

### Option 5 — Bash (no npm)

```bash
curl -fsSL https://raw.githubusercontent.com/citizenweb3/ai-integrations/logos-node/install.sh | bash
```

---

## Supported agents

| Agent | Skill path |
|---|---|
| Claude Code | `~/.claude/skills/logos-node/` |
| GitHub Copilot | `.agents/skills/logos-node/` |
| Gemini CLI | `.gemini/skills/logos-node/` |
| OpenAI Codex CLI | `.agents/skills/logos-node/` |
| opencode | `.opencode/skills/logos-node/` |
| OpenClaw | `~/.openclaw/skills/logos-node/` |

---

## Usage

After installing, activate the skill in your agent:

```
/logos-node install
/logos-node update
/logos-node status
```

The skill will:
1. Fetch the current Logos release from GitHub API (live — no hardcoded version)
2. Check prerequisites for your server
3. Walk you through each step with exact commands
4. Verify success before declaring done

---

## About

Part of [citizenweb3/ai-integrations](https://github.com/citizenweb3/ai-integrations) — AI agent skills for blockchain node operators.

Built by [CitizenWeb3](https://github.com/citizenweb3) as a public contribution to the Logos ecosystem.

- [Logos Blockchain](https://github.com/logos-blockchain/logos-blockchain)
- [Logos Testnet Dashboard](https://testnet.blockchain.logos.co/web/)
- [AgentSkills Standard](https://agentskills.io)


path: AGENTS.md
content: # ai-integrations — logos-node branch

This branch contains the Logos Blockchain node operator skill for AI agents.

## What's in this branch

```
skill/
├── SKILL.md               # Main wizard (AgentSkills standard)
├── install-procedure.md   # Fresh node installation steps
├── update-procedure.md    # Breaking upgrade steps
├── sharp-edges.md         # Known operational gotchas
└── status-checks.md       # Health-check commands and interpretation

mcp/
└── README.md              # Future RAG/MCP integration notes

.claude-plugin/
└── plugin.json            # Claude Code plugin metadata

install.sh                 # Bash installer (no npm required)
```

## Agent roles

When working with this skill as a subagent, follow this workflow order:

1. **research** — Before modifying any procedure file, verify the current
   [Logos release notes](https://github.com/logos-blockchain/logos-blockchain/releases/latest).
   Do not invent endpoints, peer IDs, or version numbers.

2. **executor** — Perform node operations conservatively. Log exact commands,
   paths, and outcomes. Never skip a checklist step.

3. **review** — After changes, verify: path correctness, no hardcoded versions
   that should be dynamic, no secrets committed, rollback steps present.

## Updating this skill

When Logos releases a new version:

1. Check if it is a breaking release
2. If breaking: update `update-procedure.md` checklist and `sharp-edges.md`
3. Do NOT hardcode bootstrap peers in procedure files — they come from GitHub API at runtime
4. The `SKILL.md` dynamic fetch already handles new binary/circuits URLs automatically

## Other networks (other branches)

- `main` — npm installer `@citizenweb3/ai-integrations`
- `darkfi-node` — DarkFi node skill (planned)
- `genlayer-node` — GenLayer node skill (planned)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)