@spectratools/assembly-cli 0.1.1 → 0.3.0

package/README.md

@@ -1,231 +1,81 @@
-# @spectra-the-bot/assembly-cli
+# @spectratools/assembly-cli
 
-Assembly governance CLI for the Abstract ecosystem. Built on [incur](https://github.com/wevm/incur).
+Assembly is the governance layer for protocols on the Abstract chain: it manages membership, council seats, proposals, forum participation, and treasury controls through onchain contracts. Abstract is an Ethereum L2 focused on consumer-facing apps and agent-friendly infrastructure. This CLI gives operators and agents one interface to query Assembly state, run checks, and power automation.
 
-The CLI is organized into 5 command groups:
+Learn more:
 
-- `proposals` — list/get/vote on governance proposals
-- `council` — inspect council members and seats
-- `forum` — browse governance forum posts
-- `members` — inspect member registry and membership status
-- `votes` — view vote history and proposal tallies
+- Abstract site: https://abs.xyz
+- Abstract docs: https://docs.abs.xyz
 
-## Installation
+## Install
 
 ```bash
-pnpm add -g @spectra-the-bot/assembly-cli
+pnpm add -g @spectratools/assembly-cli
 ```
 
-## Configuration
-
-Set environment variables before running commands:
-
-| Variable | Required | Description |
-|---|---|---|
-| `ASSEMBLY_API_URL` | No | Base URL for the Assembly API (defaults to `https://api.assembly.abs.xyz`) |
-| `ASSEMBLY_API_KEY` | No* | API key sent as `X-Api-Key` header |
-| `ABSTRACT_WALLET_ADDRESS` | No | Default wallet address used by `members status` when `--address` is omitted |
-
-\* Some deployments/endpoints may require an API key.
-
-Example setup:
-
-```bash
-export ASSEMBLY_API_URL="https://api.assembly.abs.xyz"
-export ASSEMBLY_API_KEY="your_api_key"
-export ABSTRACT_WALLET_ADDRESS="0x1234...abcd"
-```
-
-## Usage
-
-```bash
-assembly-cli <group> <command> [args] [options]
-```
-
----
-
-## Commands
-
-### Proposals
-
-```bash
-# List proposals
-assembly-cli proposals list [--status active|passed|rejected|all]
-
-# Get one proposal
-assembly-cli proposals get <id>
-
-# Vote on a proposal
-assembly-cli proposals vote <id> <for|against|abstain> [--reason "optional reason"]
-```
-
-Examples:
-
-```bash
-assembly-cli proposals list
-assembly-cli proposals list --status active
-assembly-cli proposals get 42
-assembly-cli proposals vote 42 for --reason "Supports treasury transparency improvements"
-```
-
-### Council
+## LLM / Agent Discovery
 
 ```bash
-# List council members
-assembly-cli council members [--status active|inactive|all]
-
-# Get member details by address
-assembly-cli council info <address>
-
-# List council seats
-assembly-cli council seats [--status open|filled|all]
-```
+# Emit machine-readable command metadata
+assembly-cli --llms
 
-Examples:
+# Register as a reusable local skill for agent runtimes
+assembly-cli skills add
 
-```bash
-assembly-cli council members
-assembly-cli council members --status all
-assembly-cli council info 0xabc123...
-assembly-cli council seats --status open
+# Register as an MCP server entry
+assembly-cli mcp add
 ```
 
-### Forum
-
-```bash
-# List forum posts
-assembly-cli forum posts [--category governance|general|all]
-
-# Get a forum post by id
-assembly-cli forum post <id>
+## Configuration
 
-# Search forum posts
-assembly-cli forum search <query>
-```
+| Variable | Required | Description |
+|---|---|---|
+| `ABSTRACT_RPC_URL` | No | Abstract RPC URL override (default from package client) |
+| `ASSEMBLY_INDEXER_URL` | No | Optional member snapshot endpoint for `members list` (falls back to on-chain `Registered` events with a warning if unavailable) |
 
-Examples:
+## Command Group Intent Summary
 
-```bash
-assembly-cli forum posts
-assembly-cli forum posts --category governance
-assembly-cli forum post post-123
-assembly-cli forum search "delegate incentives"
-```
+- `members` — Membership state, counts, and registry fee settings
+- `council` — Seat occupancy, active council members, auction slots, and council params
+- `forum` — Threads, comments, petitions, and petition participation checks
+- `governance` — Proposal index/details, vote participation checks, governance params
+- `treasury` — Treasury balance, whitelist checks, major-spend status, execution checks
+- root commands (`status`, `health`) — Cross-contract snapshots for bots/monitors
 
-### Members
+## Usage
 
 ```bash
-# List members
-assembly-cli members list [--role council|voter|all]
-
-# Get member details
-assembly-cli members info <address>
-
-# Check membership status
-assembly-cli members status [--address <address>]
+assembly-cli <group> <command> [args] [options]
 ```
 
-Examples:
+## Agent-Oriented Examples
 
 ```bash
-assembly-cli members list
-assembly-cli members list --role voter
-assembly-cli members info 0xabc123...
-assembly-cli members status --address 0xabc123...
-# or uses ABSTRACT_WALLET_ADDRESS if set:
-assembly-cli members status
-```
-
-### Votes
+# 1) Agent startup snapshot: report system health in one call
+assembly-cli status --json
 
-```bash
-# Vote history
-assembly-cli votes history [--voter <address>] [--proposal <id>]
+# 2) Verify whether an address can currently participate as council
+assembly-cli council is-member 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --format json
 
-# Proposal tally
-assembly-cli votes tally <proposalId>
-```
+# 3) Pull active member roster with relative activity timings
+# Note: best results require ASSEMBLY_INDEXER_URL; if the indexer returns 404/unavailable,
+# the CLI falls back to onchain Registered events and output may be slower or partial.
+assembly-cli members list --json
 
-Examples:
+# 4) Pre-vote automation: list proposals and fetch one in detail
+assembly-cli governance proposals --format json
+assembly-cli governance proposal 1 --json
 
-```bash
-assembly-cli votes history
-assembly-cli votes history --voter 0xabc123...
-assembly-cli votes history --proposal 42
-assembly-cli votes tally 42
+# 5) Treasury monitoring loop: balance + spend lock status
+assembly-cli treasury balance --format json
+assembly-cli treasury major-spend-status --json
 ```
 
----
-
-## Output formats
-
-### Human-readable (default)
-
-```bash
-assembly-cli proposals list
-```
+## Output Mode
 
-### JSON (agent/script-friendly)
+All commands support structured JSON output for agents with either `--json` or `--format json`:
 
 ```bash
-assembly-cli proposals list --format json
-assembly-cli votes tally 42 --format json
-```
-
-Example JSON envelope:
-
-```json
-{
-  "ok": true,
-  "data": [
-    {
-      "id": "42",
-      "title": "Treasury Reallocation",
-      "status": "active",
-      "proposer": "0xabc123...",
-      "votes": {
-        "for": 120,
-        "against": 35,
-        "abstain": 4
-      },
-      "startTime": "2026-03-01T12:00:00.000Z",
-      "endTime": "2026-03-03T12:00:00.000Z"
-    }
-  ]
-}
-```
-
-Example tally output (`votes tally`):
-
-```json
-{
-  "ok": true,
-  "data": {
-    "proposalId": "42",
-    "votesFor": 120,
-    "votesAgainst": 35,
-    "votesAbstain": 4,
-    "totalVotes": 159,
-    "breakdown": {
-      "for": "75.5%",
-      "against": "22.0%",
-      "abstain": "2.5%"
-    }
-  }
-}
-```
-
-## Error handling
-
-On request failures, commands return structured errors. Example:
-
-```json
-{
-  "ok": false,
-  "error": {
-    "code": "FETCH_ERROR",
-    "message": "Failed to fetch proposals: ...",
-    "retryable": true
-  }
-}
+assembly-cli forum threads --json
+assembly-cli forum threads --format json
 ```