docs: add gravity cli skill

[Lchangliang]

Summary

• add a Codex skill for gravity_cli command usage
• document command tree, config/profile defaults, signer behavior, and safety notes
• clarify source-vs-binary command availability for doctor and qs-db

Scope

Only adds .agents/skills/gravity-cli/SKILL.md.

[Richard1048576]

Review: don't split, plus 5 polish suggestions

Thanks for shipping this @Lchangliang — putting the full gravity_cli command surface into one skill is the right call. Some thoughts on whether to split it (TL;DR: no), plus a few things worth tightening before merge.

Should this be split? — No

I went through four candidate splits and none of them pay for themselves:

Candidate split	Why it doesn't pay for itself
Validator vs Non-Validator	Almost no one runs gravity_cli as a non-validator — RPC users / indexers / exchanges go through web3 libraries. The non-validator slice would be ~80 lines (read-only commands) and not worth a separate skill.
Read-only vs Write-chain	Profile config / signer / output / RPC are shared infra both groups need; splitting forces duplication or cross-skill references.
Setup (genesis + join) vs Ongoing ops	stake get and validator list straddle both phases; unwind is emergency ops that doesn't sit naturally in either bucket.
CLI infra (init/profile/signer) vs Domain commands	AI assistants need both to do anything useful; doesn't match the one-binary-one-skill convention used elsewhere.

gravity_cli is one binary → one skill. 500 lines covering 13 subcommands is on the comfortable side — comparable to single-tool skills shipped elsewhere.

5 polish suggestions

1. Add a "Quick Decision" table near the top (highest value)

A 500-line skill won't get read linearly. A short "I want to → use this" triage table near the top maps intent to a command flow:

Intent	Commands
Onboard a new validator	genesis generate-key → stake create → validator join
Daily node health	doctor → status → tail logs
Validator exit	validator leave → wait one epoch → validator list to confirm
Emergency DB rollback	⚠️ unwind (destructive)
Just observing the chain	status / epoch status / validator list (read-only)

Both human operators and AI assistants benefit from this triage.

2. Tag commands by risk tier in the command tree

Today the command tree is flat — you can't tell from looking at stake create vs validator list which one signs a tx. Suggested restructure:

Read-only:
  status, epoch status, validator list, dkg status, dkg randomness,
  stake get, doctor

Write-chain (signs a tx):
  stake create, validator join, validator leave

Local destructive:
  node start, node stop, unwind

Setup / utility:
  init, genesis generate-key, genesis generate-waypoint,
  genesis generate-account, completions

This lets AI assistants see risk at a glance instead of inferring from the Safety section.

3. Move (or remove) the qs-db "not wired" note

The current paragraph about bin/gravity_cli/src/qs_db.rs find-batches being an unwired draft is repo-internal state — for consumers of the binary it's noise (calling it just returns "unrecognized subcommand"). Either delete it, or move it to a bottom-of-doc "Known not-yet-wired" section. The doctor source-vs-binary note is worth keeping because operators do hit that case.

4. Move "Common Pitfalls" up, or inline each pitfall into its section

Currently at the very bottom. AI assistants reading top-down may miss them. Either move the section up right after ## Safety, or inline each pitfall into the relevant command section:

• "Do not pass --private-key" → Signing section
• "stake get --from-block auto only scans 90,000 blocks" → Stake section
• "validator join requires governance whitelist" → Validator Commands

Inline placement is harder to miss when an AI assistant is reading just one section to generate a command.

5. Add a "Known Endpoints" section

All examples use <RPC_URL> / <SERVER_URL> placeholders. First-time operators have to hunt elsewhere for real values. Suggested addition:

## Known Endpoints

| Env                | RPC                              | DKG server       |
| ------------------ | -------------------------------- | ---------------- |
| Longevity Testnet  | https://rpc-testnet.gravity.xyz  | (internal)       |
| Mainnet            | https://mainnet-rpc.gravity.xyz  | (internal)       |
| Local devnet       | http://127.0.0.1:8545            | 127.0.0.1:1024   |

Or just link to the docsite network/ pages.

Smaller nits

• The private-mainnet term appears in the Safety section ("querying private-mainnet RPC..."). Suggest rewording to "internal/restricted network" or just dropping the qualifier — it reads like an internal codename in an otherwise public-facing doc.
• init interactive prompt order (Profile name / RPC URL / DKG server URL / Deploy path) doesn't match the column order in the Resolution priority table — align for readability.
• Some examples use <RPC_URL>, others <RPC>. Pick one placeholder style and apply throughout.
• RUSTFLAGS="--cfg tokio_unstable" for the source build is buried inside the Binary section but is required — worth a callout or bold marker.

---

Happy to land a follow-up commit with #1, #2, #3 if you'd like — those three are the biggest quality wins and shouldn't be controversial. #4 and #5 are stylistic and best left to you.

[Richard1048576]

LGTM