@spectratools/assembly-cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -29,6 +29,19 @@ function relTime(unixSeconds) {
 function asNum(value) {
   return Number(value);
 }
+function jsonSafe(value) {
+  if (typeof value === "bigint") return value.toString();
+  if (Array.isArray(value)) return value.map((item) => jsonSafe(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        jsonSafe(entry)
+      ])
+    );
+  }
+  return value;
+}
 
 // src/commands/council.ts
 import { Cli, z } from "incur";
@@ -4293,12 +4306,35 @@ function createAssemblyPublicClient(rpcUrl) {
 }
 
 // src/commands/council.ts
-var env = z.object({ ABSTRACT_RPC_URL: z.string().optional() });
+var env = z.object({
+  ABSTRACT_RPC_URL: z.string().optional().describe("Abstract RPC URL override")
+});
+function decodeSeat(value) {
+  const [owner, startAt, endAt, forfeited] = value;
+  return { owner, startAt, endAt, forfeited };
+}
+function decodeAuction(value) {
+  const [highestBidder, highestBid, settled] = value;
+  return { highestBidder, highestBid, settled };
+}
 var council = Cli.create("council", {
-  description: "Read council seat and auction state."
+  description: "Inspect council seats, members, auctions, and seat parameters."
 });
 council.command("seats", {
+  description: "List all council seats and their occupancy windows.",
   env,
+  output: z.array(
+    z.object({
+      id: z.number(),
+      owner: z.string(),
+      startAt: z.number(),
+      startAtRelative: z.string(),
+      endAt: z.number(),
+      endAtRelative: z.string(),
+      forfeited: z.boolean()
+    })
+  ),
+  examples: [{ description: "List all council seats" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4307,7 +4343,7 @@ council.command("seats", {
       functionName: "seatCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i));
-    const seats = ids.length ? await client.multicall({
+    const seatTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: councilSeatsAbi,
@@ -4316,13 +4352,14 @@ council.command("seats", {
         args: [id]
       }))
     }) : [];
+    const seats = seatTuples.map(decodeSeat);
     return c.ok(
       seats.map((seat, idx) => ({
         id: idx,
         owner: toChecksum(seat.owner),
-        startAt: Number(seat.startAt),
+        startAt: asNum(seat.startAt),
         startAtRelative: relTime(seat.startAt),
-        endAt: Number(seat.endAt),
+        endAt: asNum(seat.endAt),
         endAtRelative: relTime(seat.endAt),
         forfeited: seat.forfeited
       }))
@@ -4330,26 +4367,49 @@ council.command("seats", {
   }
 });
 council.command("seat", {
-  args: z.object({ id: z.coerce.number().int().nonnegative() }),
+  description: "Get detailed seat information for a specific seat id.",
+  args: z.object({
+    id: z.coerce.number().int().nonnegative().describe("Seat id (0-indexed)")
+  }),
   env,
+  output: z.object({
+    id: z.number(),
+    owner: z.string(),
+    startAt: z.number(),
+    endAt: z.number(),
+    forfeited: z.boolean(),
+    endAtRelative: z.string()
+  }),
+  examples: [{ args: { id: 0 }, description: "Inspect seat #0" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const seat = await client.readContract({
+    const seatTuple = await client.readContract({
       abi: councilSeatsAbi,
       address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
       functionName: "seats",
       args: [BigInt(c.args.id)]
     });
+    const seat = decodeSeat(seatTuple);
     return c.ok({
       id: c.args.id,
-      ...seat,
       owner: toChecksum(seat.owner),
+      startAt: asNum(seat.startAt),
+      endAt: asNum(seat.endAt),
+      forfeited: seat.forfeited,
       endAtRelative: relTime(seat.endAt)
     });
   }
 });
 council.command("members", {
+  description: "List currently active council members and voting power.",
   env,
+  output: z.array(
+    z.object({
+      address: z.string(),
+      votingPower: z.number()
+    })
+  ),
+  examples: [{ description: "List active council members" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4358,7 +4418,7 @@ council.command("members", {
       functionName: "seatCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i));
-    const seats = ids.length ? await client.multicall({
+    const seatTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: councilSeatsAbi,
@@ -4367,9 +4427,10 @@ council.command("members", {
         args: [id]
       }))
     }) : [];
+    const seats = seatTuples.map(decodeSeat);
     const activeOwners = [
       ...new Set(
-        seats.filter((x) => !x.forfeited && Number(x.endAt) > Math.floor(Date.now() / 1e3)).map((x) => x.owner)
+        seats.filter((x) => !x.forfeited && asNum(x.endAt) > Math.floor(Date.now() / 1e3)).map((x) => x.owner)
       )
     ];
     const powers = activeOwners.length ? await client.multicall({
@@ -4390,8 +4451,21 @@ council.command("members", {
   }
 });
 council.command("is-member", {
-  args: z.object({ address: z.string() }),
+  description: "Check whether an address is currently a council member.",
+  args: z.object({
+    address: z.string().describe("Address to check")
+  }),
   env,
+  output: z.object({
+    address: z.string(),
+    isMember: z.boolean()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      description: "Check council status for one address"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const isMember = await client.readContract({
@@ -4404,8 +4478,21 @@ council.command("is-member", {
   }
 });
 council.command("voting-power", {
-  args: z.object({ address: z.string() }),
+  description: "Get the current voting power for an address.",
+  args: z.object({
+    address: z.string().describe("Address to inspect")
+  }),
   env,
+  output: z.object({
+    address: z.string(),
+    votingPower: z.number()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      description: "Get voting power for one address"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const votingPower = await client.readContract({
@@ -4418,7 +4505,22 @@ council.command("voting-power", {
   }
 });
 council.command("auctions", {
+  description: "List recent and current council auction slots and leading bids.",
   env,
+  output: z.object({
+    currentDay: z.number(),
+    currentSlot: z.number(),
+    auctions: z.array(
+      z.object({
+        day: z.number(),
+        slot: z.number(),
+        highestBidder: z.string(),
+        highestBid: z.string(),
+        settled: z.boolean()
+      })
+    )
+  }),
+  examples: [{ description: "Inspect current and recent auction slots" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [day, slot, slotsPerDay] = await Promise.all([
@@ -4443,7 +4545,7 @@ council.command("auctions", {
       if (d < 0) continue;
       for (let s = 0; s < Number(slotsPerDay); s++) recent.push({ day: BigInt(d), slot: s });
     }
-    const auctions = recent.length ? await client.multicall({
+    const auctionTuples = recent.length ? await client.multicall({
       allowFailure: false,
       contracts: recent.map((x) => ({
         abi: councilSeatsAbi,
@@ -4452,12 +4554,14 @@ council.command("auctions", {
         args: [x.day, x.slot]
       }))
     }) : [];
+    const auctions = auctionTuples.map(decodeAuction);
     return c.ok(
       {
         currentDay: asNum(day),
         currentSlot: asNum(slot),
         auctions: recent.map((x, i) => ({
-          ...x,
+          day: Number(x.day),
+          slot: x.slot,
           highestBidder: toChecksum(auctions[i].highestBidder),
           highestBid: eth(auctions[i].highestBid),
           settled: auctions[i].settled
@@ -4476,19 +4580,29 @@ council.command("auctions", {
   }
 });
 council.command("auction", {
+  description: "Get one auction slot by day + slot.",
   args: z.object({
-    day: z.coerce.number().int().nonnegative(),
-    slot: z.coerce.number().int().nonnegative()
+    day: z.coerce.number().int().nonnegative().describe("Auction day index"),
+    slot: z.coerce.number().int().nonnegative().describe("Slot index within day")
   }),
   env,
+  output: z.object({
+    day: z.number(),
+    slot: z.number(),
+    highestBidder: z.string(),
+    highestBid: z.string(),
+    settled: z.boolean()
+  }),
+  examples: [{ args: { day: 0, slot: 0 }, description: "Inspect day 0, slot 0 auction" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const auction = await client.readContract({
+    const auctionTuple = await client.readContract({
       abi: councilSeatsAbi,
       address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
       functionName: "auctions",
       args: [BigInt(c.args.day), c.args.slot]
     });
+    const auction = decodeAuction(auctionTuple);
     return c.ok({
       day: c.args.day,
       slot: c.args.slot,
@@ -4499,8 +4613,22 @@ council.command("auction", {
   }
 });
 council.command("pending-refund", {
-  args: z.object({ address: z.string() }),
+  description: "Get pending refundable bid amount for an address.",
+  args: z.object({
+    address: z.string().describe("Bidder address")
+  }),
   env,
+  output: z.object({
+    address: z.string(),
+    pendingRefund: z.string(),
+    pendingRefundWei: z.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      description: "Check pending refund for an address"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const amount = await client.readContract({
@@ -4517,7 +4645,17 @@ council.command("pending-refund", {
   }
 });
 council.command("params", {
+  description: "Read council seat term and auction scheduling parameters.",
   env,
+  output: z.object({
+    SEAT_TERM: z.number(),
+    AUCTION_SLOT_DURATION: z.number(),
+    AUCTION_SLOTS_PER_DAY: z.number(),
+    auctionEpochStart: z.number(),
+    auctionWindowStart: z.number(),
+    auctionWindowEnd: z.number()
+  }),
+  examples: [{ description: "Inspect council seat + auction timing constants" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [SEAT_TERM, AUCTION_SLOT_DURATION, AUCTION_SLOTS_PER_DAY, auctionEpochStart] = await Promise.all([
@@ -4569,10 +4707,78 @@ council.command("params", {
 
 // src/commands/forum.ts
 import { Cli as Cli2, z as z2 } from "incur";
-var env2 = z2.object({ ABSTRACT_RPC_URL: z2.string().optional() });
-var forum = Cli2.create("forum", { description: "Read forum threads/comments/petitions." });
+var env2 = z2.object({
+  ABSTRACT_RPC_URL: z2.string().optional().describe("Abstract RPC URL override")
+});
+function decodeThread(value) {
+  const [id, kind, author, createdAt, category, title, body, proposalId, petitionId] = value;
+  return {
+    id: asNum(id),
+    kind: asNum(kind),
+    author: toChecksum(author),
+    createdAt: asNum(createdAt),
+    category,
+    title,
+    body,
+    proposalId: asNum(proposalId),
+    petitionId: asNum(petitionId)
+  };
+}
+function decodeComment(value) {
+  const [id, threadId, parentId, author, createdAt, body] = value;
+  return {
+    id: asNum(id),
+    threadId: asNum(threadId),
+    parentId: asNum(parentId),
+    author: toChecksum(author),
+    createdAt: asNum(createdAt),
+    body
+  };
+}
+function decodePetition(value) {
+  const [
+    id,
+    proposer,
+    createdAt,
+    category,
+    title,
+    body,
+    signatures,
+    promoted,
+    threadId,
+    proposalInput
+  ] = value;
+  return {
+    id: asNum(id),
+    proposer: toChecksum(proposer),
+    createdAt: asNum(createdAt),
+    category,
+    title,
+    body,
+    signatures: asNum(signatures),
+    promoted,
+    threadId: asNum(threadId),
+    proposalInput: jsonSafe(proposalInput)
+  };
+}
+var forum = Cli2.create("forum", {
+  description: "Browse Assembly forum threads, comments, and petitions."
+});
 forum.command("threads", {
+  description: "List forum threads with author and creation metadata.",
   env: env2,
+  output: z2.array(
+    z2.object({
+      id: z2.number(),
+      kind: z2.number(),
+      author: z2.string(),
+      createdAt: z2.number(),
+      createdAtRelative: z2.string(),
+      category: z2.string().nullable().optional(),
+      title: z2.string().nullable().optional()
+    })
+  ),
+  examples: [{ description: "List all forum threads" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4581,7 +4787,7 @@ forum.command("threads", {
       functionName: "threadCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i + 1));
-    const items = ids.length ? await client.multicall({
+    const threadTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: forumAbi,
@@ -4590,15 +4796,16 @@ forum.command("threads", {
         args: [id]
       }))
     }) : [];
+    const items = threadTuples.map(decodeThread);
     return c.ok(
       items.map((x) => ({
-        id: asNum(x.id),
-        kind: asNum(x.kind),
-        author: toChecksum(x.author),
-        createdAt: asNum(x.createdAt),
+        id: x.id,
+        kind: x.kind,
+        author: x.author,
+        createdAt: x.createdAt,
         createdAtRelative: relTime(x.createdAt),
-        category: x.category,
-        title: x.title
+        category: x.category ?? null,
+        title: x.title ?? null
       })),
       {
         cta: {
@@ -4613,11 +4820,19 @@ forum.command("threads", {
   }
 });
 forum.command("thread", {
-  args: z2.object({ id: z2.coerce.number().int().positive() }),
+  description: "Get one thread and all comments associated with it.",
+  args: z2.object({
+    id: z2.coerce.number().int().positive().describe("Thread id (1-indexed)")
+  }),
   env: env2,
+  output: z2.object({
+    thread: z2.record(z2.string(), z2.unknown()),
+    comments: z2.array(z2.record(z2.string(), z2.unknown()))
+  }),
+  examples: [{ args: { id: 1 }, description: "Fetch thread #1 and its comments" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const [thread, commentCount] = await Promise.all([
+    const [threadTuple, commentCount] = await Promise.all([
       client.readContract({
         abi: forumAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.forum,
@@ -4630,8 +4845,9 @@ forum.command("thread", {
         functionName: "commentCount"
       })
     ]);
+    const thread = decodeThread(threadTuple);
     const ids = Array.from({ length: Number(commentCount) }, (_, i) => BigInt(i + 1));
-    const comments = ids.length ? await client.multicall({
+    const commentTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: forumAbi,
@@ -4640,15 +4856,21 @@ forum.command("thread", {
         args: [id]
       }))
     }) : [];
+    const comments = commentTuples.map(decodeComment);
     return c.ok({
-      thread,
-      comments: comments.filter((x) => Number(x.threadId) === c.args.id)
+      thread: jsonSafe(thread),
+      comments: comments.filter((x) => x.threadId === c.args.id).map((comment) => jsonSafe(comment))
     });
   }
 });
 forum.command("comments", {
-  args: z2.object({ threadId: z2.coerce.number().int().positive() }),
+  description: "List comments for a thread id.",
+  args: z2.object({
+    threadId: z2.coerce.number().int().positive().describe("Thread id to filter comments by")
+  }),
   env: env2,
+  output: z2.array(z2.record(z2.string(), z2.unknown())),
+  examples: [{ args: { threadId: 1 }, description: "List comments for thread #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4657,7 +4879,7 @@ forum.command("comments", {
       functionName: "commentCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i + 1));
-    const comments = ids.length ? await client.multicall({
+    const commentTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: forumAbi,
@@ -4666,25 +4888,36 @@ forum.command("comments", {
         args: [id]
       }))
     }) : [];
-    return c.ok(comments.filter((x) => Number(x.threadId) === c.args.threadId));
+    const comments = commentTuples.map(decodeComment);
+    return c.ok(
+      comments.filter((x) => x.threadId === c.args.threadId).map((comment) => jsonSafe(comment))
+    );
   }
 });
 forum.command("comment", {
-  args: z2.object({ id: z2.coerce.number().int().positive() }),
+  description: "Get one comment by comment id.",
+  args: z2.object({
+    id: z2.coerce.number().int().positive().describe("Comment id (1-indexed)")
+  }),
   env: env2,
+  output: z2.record(z2.string(), z2.unknown()),
+  examples: [{ args: { id: 1 }, description: "Fetch comment #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const comment = await client.readContract({
+    const commentTuple = await client.readContract({
       abi: forumAbi,
       address: ABSTRACT_MAINNET_ADDRESSES.forum,
       functionName: "comments",
       args: [BigInt(c.args.id)]
     });
-    return c.ok(comment);
+    return c.ok(jsonSafe(decodeComment(commentTuple)));
   }
 });
 forum.command("petitions", {
+  description: "List petitions submitted in the forum contract.",
   env: env2,
+  output: z2.array(z2.record(z2.string(), z2.unknown())),
+  examples: [{ description: "List all petitions" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4693,7 +4926,7 @@ forum.command("petitions", {
       functionName: "petitionCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i + 1));
-    const petitions = ids.length ? await client.multicall({
+    const petitionTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: forumAbi,
@@ -4702,32 +4935,58 @@ forum.command("petitions", {
         args: [id]
       }))
     }) : [];
-    return c.ok(petitions);
+    const petitions = petitionTuples.map(decodePetition);
+    return c.ok(petitions.map((petition) => jsonSafe(petition)));
   }
 });
 forum.command("petition", {
-  args: z2.object({ id: z2.coerce.number().int().positive() }),
+  description: "Get one petition plus whether proposer already signed it.",
+  args: z2.object({
+    id: z2.coerce.number().int().positive().describe("Petition id (1-indexed)")
+  }),
   env: env2,
+  output: z2.object({ proposerSigned: z2.boolean() }).passthrough(),
+  examples: [{ args: { id: 1 }, description: "Fetch petition #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const petition = await client.readContract({
-      abi: forumAbi,
-      address: ABSTRACT_MAINNET_ADDRESSES.forum,
-      functionName: "petitions",
-      args: [BigInt(c.args.id)]
-    });
+    const petition = decodePetition(
+      await client.readContract({
+        abi: forumAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.forum,
+        functionName: "petitions",
+        args: [BigInt(c.args.id)]
+      })
+    );
     const proposerSigned = await client.readContract({
       abi: forumAbi,
       address: ABSTRACT_MAINNET_ADDRESSES.forum,
       functionName: "hasSignedPetition",
       args: [BigInt(c.args.id), petition.proposer]
     });
-    return c.ok({ ...petition, proposerSigned });
+    return c.ok({ ...jsonSafe(petition), proposerSigned });
   }
 });
 forum.command("has-signed", {
-  args: z2.object({ petitionId: z2.coerce.number().int().positive(), address: z2.string() }),
+  description: "Check whether an address signed a petition.",
+  args: z2.object({
+    petitionId: z2.coerce.number().int().positive().describe("Petition id (1-indexed)"),
+    address: z2.string().describe("Signer address to check")
+  }),
   env: env2,
+  output: z2.object({
+    petitionId: z2.number(),
+    address: z2.string(),
+    hasSigned: z2.boolean()
+  }),
+  examples: [
+    {
+      args: {
+        petitionId: 1,
+        address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+      },
+      description: "Check if an address signed petition #1"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const hasSigned = await client.readContract({
@@ -4740,7 +4999,15 @@ forum.command("has-signed", {
   }
 });
 forum.command("stats", {
+  description: "Read top-level forum counters and petition threshold.",
   env: env2,
+  output: z2.object({
+    threadCount: z2.number(),
+    commentCount: z2.number(),
+    petitionCount: z2.number(),
+    petitionThresholdBps: z2.number()
+  }),
+  examples: [{ description: "Get forum counts and petition threshold" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [threadCount, commentCount, petitionCount, petitionThresholdBps] = await Promise.all([
@@ -4776,12 +5043,105 @@ forum.command("stats", {
 
 // src/commands/governance.ts
 import { Cli as Cli3, z as z3 } from "incur";
-var env3 = z3.object({ ABSTRACT_RPC_URL: z3.string().optional() });
+var env3 = z3.object({
+  ABSTRACT_RPC_URL: z3.string().optional().describe("Abstract RPC URL override")
+});
+function decodeProposal(value) {
+  const [
+    kind,
+    configRiskTier,
+    origin,
+    status,
+    proposer,
+    threadId,
+    petitionId,
+    createdAt,
+    deliberationEndsAt,
+    voteStartAt,
+    voteEndAt,
+    timelockEndsAt,
+    activeSeatsSnapshot,
+    forVotes,
+    againstVotes,
+    abstainVotes,
+    amount,
+    snapshotAssetBalance,
+    transferIntent,
+    intentDeadline,
+    intentMaxRiskTier,
+    title,
+    description
+  ] = value;
+  return {
+    kind,
+    configRiskTier,
+    origin,
+    status,
+    proposer: toChecksum(proposer),
+    threadId,
+    petitionId,
+    createdAt,
+    deliberationEndsAt,
+    voteStartAt,
+    voteEndAt,
+    timelockEndsAt,
+    activeSeatsSnapshot,
+    forVotes,
+    againstVotes,
+    abstainVotes,
+    amount,
+    snapshotAssetBalance,
+    transferIntent,
+    intentDeadline,
+    intentMaxRiskTier,
+    title,
+    description
+  };
+}
+function serializeProposal(proposal) {
+  return {
+    kind: asNum(proposal.kind),
+    configRiskTier: asNum(proposal.configRiskTier),
+    origin: asNum(proposal.origin),
+    status: asNum(proposal.status),
+    proposer: proposal.proposer,
+    threadId: asNum(proposal.threadId),
+    petitionId: asNum(proposal.petitionId),
+    createdAt: asNum(proposal.createdAt),
+    deliberationEndsAt: asNum(proposal.deliberationEndsAt),
+    voteStartAt: asNum(proposal.voteStartAt),
+    voteEndAt: asNum(proposal.voteEndAt),
+    timelockEndsAt: asNum(proposal.timelockEndsAt),
+    activeSeatsSnapshot: asNum(proposal.activeSeatsSnapshot),
+    forVotes: proposal.forVotes.toString(),
+    againstVotes: proposal.againstVotes.toString(),
+    abstainVotes: proposal.abstainVotes.toString(),
+    amount: proposal.amount.toString(),
+    snapshotAssetBalance: proposal.snapshotAssetBalance.toString(),
+    transferIntent: proposal.transferIntent,
+    intentDeadline: asNum(proposal.intentDeadline),
+    intentMaxRiskTier: asNum(proposal.intentMaxRiskTier),
+    title: proposal.title,
+    description: proposal.description
+  };
+}
 var governance = Cli3.create("governance", {
-  description: "Read governance proposals and params."
+  description: "Inspect Assembly governance proposals, votes, and parameters."
 });
 governance.command("proposals", {
+  description: "List governance proposals with status and vote end time.",
   env: env3,
+  output: z3.array(
+    z3.object({
+      id: z3.number(),
+      kind: z3.number(),
+      status: z3.number(),
+      title: z3.string().nullable().optional(),
+      voteEndAt: z3.number(),
+      voteEndRelative: z3.string()
+    })
+  ),
+  examples: [{ description: "List all proposals" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const count = await client.readContract({
@@ -4790,7 +5150,7 @@ governance.command("proposals", {
       functionName: "proposalCount"
     });
     const ids = Array.from({ length: Number(count) }, (_, i) => BigInt(i + 1));
-    const proposals = ids.length ? await client.multicall({
+    const proposalTuples = ids.length ? await client.multicall({
       allowFailure: false,
       contracts: ids.map((id) => ({
         abi: governanceAbi,
@@ -4799,12 +5159,13 @@ governance.command("proposals", {
         args: [id]
       }))
     }) : [];
+    const proposals = proposalTuples.map(decodeProposal);
     return c.ok(
       proposals.map((p, i) => ({
         id: i + 1,
         kind: asNum(p.kind),
         status: asNum(p.status),
-        title: p.title,
+        title: p.title ?? null,
         voteEndAt: asNum(p.voteEndAt),
         voteEndRelative: relTime(p.voteEndAt)
       })),
@@ -4821,22 +5182,47 @@ governance.command("proposals", {
   }
 });
 governance.command("proposal", {
-  args: z3.object({ id: z3.coerce.number().int().positive() }),
+  description: "Get full raw proposal details by proposal id.",
+  args: z3.object({
+    id: z3.coerce.number().int().positive().describe("Proposal id (1-indexed)")
+  }),
   env: env3,
+  output: z3.record(z3.string(), z3.unknown()),
+  examples: [{ args: { id: 1 }, description: "Fetch proposal #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const proposal = await client.readContract({
-      abi: governanceAbi,
-      address: ABSTRACT_MAINNET_ADDRESSES.governance,
-      functionName: "proposals",
-      args: [BigInt(c.args.id)]
-    });
-    return c.ok(proposal);
+    const proposal = decodeProposal(
+      await client.readContract({
+        abi: governanceAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.governance,
+        functionName: "proposals",
+        args: [BigInt(c.args.id)]
+      })
+    );
+    return c.ok(serializeProposal(proposal));
   }
 });
 governance.command("has-voted", {
-  args: z3.object({ proposalId: z3.coerce.number().int().positive(), address: z3.string() }),
+  description: "Check if an address has voted on a proposal.",
+  args: z3.object({
+    proposalId: z3.coerce.number().int().positive().describe("Proposal id (1-indexed)"),
+    address: z3.string().describe("Voter address")
+  }),
   env: env3,
+  output: z3.object({
+    proposalId: z3.number(),
+    address: z3.string(),
+    hasVoted: z3.boolean()
+  }),
+  examples: [
+    {
+      args: {
+        proposalId: 1,
+        address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+      },
+      description: "Check whether an address already voted"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const hasVoted = await client.readContract({
@@ -4845,11 +5231,31 @@ governance.command("has-voted", {
       functionName: "hasVoted",
       args: [BigInt(c.args.proposalId), c.args.address]
     });
-    return c.ok({ proposalId: c.args.proposalId, address: c.args.address, hasVoted });
+    return c.ok({
+      proposalId: c.args.proposalId,
+      address: toChecksum(c.args.address),
+      hasVoted
+    });
   }
 });
 governance.command("params", {
+  description: "Read governance threshold and timing parameters.",
   env: env3,
+  output: z3.object({
+    deliberationPeriod: z3.number(),
+    votePeriod: z3.number(),
+    quorumBps: z3.number(),
+    constitutionalDeliberationPeriod: z3.number(),
+    constitutionalVotePeriod: z3.number(),
+    constitutionalPassBps: z3.number(),
+    majorPassBps: z3.number(),
+    parameterPassBps: z3.number(),
+    significantPassBps: z3.number(),
+    significantThresholdBps: z3.number(),
+    routineThresholdBps: z3.number(),
+    timelockPeriod: z3.number()
+  }),
+  examples: [{ description: "Inspect governance timing and pass thresholds" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const getters = [
@@ -4874,33 +5280,171 @@ governance.command("params", {
         functionName: name
       }))
     });
-    return c.ok(Object.fromEntries(getters.map((k, i) => [k, asNum(values[i])])));
+    return c.ok({
+      deliberationPeriod: asNum(values[0]),
+      votePeriod: asNum(values[1]),
+      quorumBps: asNum(values[2]),
+      constitutionalDeliberationPeriod: asNum(values[3]),
+      constitutionalVotePeriod: asNum(values[4]),
+      constitutionalPassBps: asNum(values[5]),
+      majorPassBps: asNum(values[6]),
+      parameterPassBps: asNum(values[7]),
+      significantPassBps: asNum(values[8]),
+      significantThresholdBps: asNum(values[9]),
+      routineThresholdBps: asNum(values[10]),
+      timelockPeriod: asNum(values[11])
+    });
   }
 });
 
 // src/commands/members.ts
 import { Cli as Cli4, z as z4 } from "incur";
+var DEFAULT_MEMBER_SNAPSHOT_URL = "https://www.theaiassembly.org/api/indexer/members";
+var REGISTERED_EVENT_SCAN_STEP = 100000n;
 var env4 = z4.object({
-  ABSTRACT_RPC_URL: z4.string().optional(),
-  ASSEMBLY_INDEXER_URL: z4.string().optional()
+  ABSTRACT_RPC_URL: z4.string().optional().describe("Abstract RPC URL override"),
+  ASSEMBLY_INDEXER_URL: z4.string().optional().describe("Optional members snapshot endpoint (default: theaiassembly.org indexer)")
 });
+var memberSnapshotSchema = z4.array(z4.string());
+var AssemblyApiValidationError = class extends Error {
+  constructor(details) {
+    super("Assembly API response validation failed");
+    this.details = details;
+    this.name = "AssemblyApiValidationError";
+  }
+};
+var AssemblyIndexerUnavailableError = class extends Error {
+  constructor(details) {
+    super("Assembly indexer unavailable");
+    this.details = details;
+    this.name = "AssemblyIndexerUnavailableError";
+  }
+};
 async function memberSnapshot(url) {
-  const res = await fetch(url);
-  if (!res.ok) return [];
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (error) {
+    throw new AssemblyIndexerUnavailableError({
+      code: "ASSEMBLY_INDEXER_UNAVAILABLE",
+      url,
+      reason: error instanceof Error ? error.message : String(error)
+    });
+  }
+  if (!res.ok) {
+    throw new AssemblyIndexerUnavailableError({
+      code: "ASSEMBLY_INDEXER_UNAVAILABLE",
+      url,
+      status: res.status,
+      statusText: res.statusText
+    });
+  }
   const json = await res.json();
-  if (!Array.isArray(json)) return [];
-  return json.filter((x) => typeof x === "string");
+  const parsed = memberSnapshotSchema.safeParse(json);
+  if (parsed.success) {
+    return parsed.data;
+  }
+  throw new AssemblyApiValidationError({
+    code: "INVALID_ASSEMBLY_API_RESPONSE",
+    url,
+    issues: parsed.error.issues,
+    response: json
+  });
+}
+async function membersFromRegisteredEvents(client) {
+  const latestBlock = await client.getBlockNumber();
+  const addresses = /* @__PURE__ */ new Set();
+  for (let fromBlock = 0n; fromBlock <= latestBlock; fromBlock += REGISTERED_EVENT_SCAN_STEP) {
+    const toBlock = fromBlock + REGISTERED_EVENT_SCAN_STEP - 1n > latestBlock ? latestBlock : fromBlock + REGISTERED_EVENT_SCAN_STEP - 1n;
+    const events = await client.getContractEvents({
+      abi: registryAbi,
+      address: ABSTRACT_MAINNET_ADDRESSES.registry,
+      eventName: "Registered",
+      fromBlock,
+      toBlock,
+      strict: true
+    });
+    for (const event of events) {
+      const member = event.args.member;
+      if (typeof member === "string") {
+        addresses.add(member);
+      }
+    }
+  }
+  return [...addresses];
+}
+function indexerIssue(details) {
+  if (typeof details.status === "number") {
+    return `${details.status}${details.statusText ? ` ${details.statusText}` : ""}`;
+  }
+  if (details.reason) return details.reason;
+  return "unknown error";
+}
+function emitIndexerFallbackWarning(details) {
+  process.stderr.write(
+    `${JSON.stringify({
+      level: "warn",
+      code: details.code,
+      message: "Member snapshot indexer is unavailable. Falling back to on-chain Registered events.",
+      url: details.url,
+      issue: indexerIssue(details)
+    })}
+`
+  );
 }
 var members = Cli4.create("members", {
-  description: "Read Assembly membership state from Registry."
+  description: "Inspect Assembly membership and registry fee state."
 });
 members.command("list", {
-  description: "List members from indexer snapshot + onchain status.",
+  description: "List members from an indexer snapshot (or Registered event fallback) plus on-chain active state.",
   env: env4,
+  output: z4.array(
+    z4.object({
+      address: z4.string(),
+      active: z4.boolean(),
+      registered: z4.boolean(),
+      activeUntil: z4.number(),
+      activeUntilRelative: z4.string(),
+      lastHeartbeatAt: z4.number(),
+      lastHeartbeatRelative: z4.string()
+    })
+  ),
+  examples: [
+    { description: "List members using default indexer snapshot" },
+    { description: "Override ASSEMBLY_INDEXER_URL to use a custom snapshot source" }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? "https://www.theaiassembly.org/api/indexer/members";
-    const addresses = await memberSnapshot(snapshotUrl);
+    const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? DEFAULT_MEMBER_SNAPSHOT_URL;
+    let addresses;
+    let fallbackReason;
+    try {
+      addresses = await memberSnapshot(snapshotUrl);
+    } catch (error) {
+      if (error instanceof AssemblyApiValidationError) {
+        return c.error({
+          code: error.details.code,
+          message: `Member snapshot response failed validation. url=${error.details.url}; issues=${JSON.stringify(error.details.issues)}; response=${JSON.stringify(error.details.response)}`,
+          retryable: false
+        });
+      }
+      if (!(error instanceof AssemblyIndexerUnavailableError)) {
+        throw error;
+      }
+      fallbackReason = error.details;
+      try {
+        addresses = await membersFromRegisteredEvents(client);
+      } catch (fallbackError) {
+        return c.error({
+          code: "MEMBER_LIST_SOURCE_UNAVAILABLE",
+          message: `Member indexer unavailable (${indexerIssue(error.details)} at ${error.details.url}) and on-chain Registered event fallback failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`,
+          retryable: true
+        });
+      }
+    }
+    if (fallbackReason) {
+      emitIndexerFallbackWarning(fallbackReason);
+    }
     const calls = addresses.flatMap((address) => [
       {
         abi: registryAbi,
@@ -4931,16 +5475,32 @@ members.command("list", {
     });
     return c.ok(rows, {
       cta: {
-        description: "Inspect one member:",
+        description: fallbackReason ? `Indexer unavailable (${indexerIssue(fallbackReason)}); using on-chain Registered event fallback. Inspect one member:` : "Inspect one member:",
         commands: [{ command: "members info", args: { address: "<addr>" } }]
       }
     });
   }
 });
 members.command("info", {
-  description: "Read member info for an address.",
-  args: z4.object({ address: z4.string() }),
+  description: "Get registry record and active status for a member address.",
+  args: z4.object({
+    address: z4.string().describe("Member wallet address")
+  }),
   env: env4,
+  output: z4.object({
+    address: z4.string(),
+    active: z4.boolean(),
+    activeUntil: z4.number(),
+    lastHeartbeatAt: z4.number(),
+    activeUntilRelative: z4.string(),
+    lastHeartbeatRelative: z4.string()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      description: "Inspect one member address"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [member, active] = await Promise.all([
@@ -4960,15 +5520,21 @@ members.command("info", {
     return c.ok({
       address: toChecksum(c.args.address),
       active,
-      ...member,
+      activeUntil: Number(member.activeUntil),
+      lastHeartbeatAt: Number(member.lastHeartbeatAt),
       activeUntilRelative: relTime(member.activeUntil),
       lastHeartbeatRelative: relTime(member.lastHeartbeatAt)
     });
   }
 });
 members.command("count", {
-  description: "Read active + known member counts.",
+  description: "Get active and total-known member counts from Registry.",
   env: env4,
+  output: z4.object({
+    active: z4.number(),
+    total: z4.number()
+  }),
+  examples: [{ description: "Count active and known members" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [active, total] = await Promise.all([
@@ -4987,8 +5553,16 @@ members.command("count", {
   }
 });
 members.command("fees", {
-  description: "Read registry fee config.",
+  description: "Get registration and heartbeat fee settings.",
   env: env4,
+  output: z4.object({
+    registrationFeeWei: z4.string(),
+    registrationFee: z4.string(),
+    heartbeatFeeWei: z4.string(),
+    heartbeatFee: z4.string(),
+    heartbeatGracePeriodSeconds: z4.number()
+  }),
+  examples: [{ description: "Inspect current registry fee configuration" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [registrationFee, heartbeatFee, heartbeatGracePeriod] = await Promise.all([
@@ -5020,10 +5594,21 @@ members.command("fees", {
 
 // src/commands/treasury.ts
 import { Cli as Cli5, z as z5 } from "incur";
-var env5 = z5.object({ ABSTRACT_RPC_URL: z5.string().optional() });
-var treasury = Cli5.create("treasury", { description: "Read treasury state." });
+var env5 = z5.object({
+  ABSTRACT_RPC_URL: z5.string().optional().describe("Abstract RPC URL override")
+});
+var treasury = Cli5.create("treasury", {
+  description: "Inspect treasury balances, execution status, and spend controls."
+});
 treasury.command("balance", {
+  description: "Get current native token balance for the treasury contract.",
   env: env5,
+  output: z5.object({
+    address: z5.string(),
+    balanceWei: z5.string(),
+    balance: z5.string()
+  }),
+  examples: [{ description: "Check treasury balance" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const balance = await client.getBalance({ address: ABSTRACT_MAINNET_ADDRESSES.treasury });
@@ -5035,8 +5620,21 @@ treasury.command("balance", {
   }
 });
 treasury.command("whitelist", {
-  args: z5.object({ asset: z5.string() }),
+  description: "Check whether an asset address is treasury-whitelisted.",
+  args: z5.object({
+    asset: z5.string().describe("Token/asset contract address")
+  }),
   env: env5,
+  output: z5.object({
+    asset: z5.string(),
+    whitelisted: z5.boolean()
+  }),
+  examples: [
+    {
+      args: { asset: "0x0000000000000000000000000000000000000000" },
+      description: "Check whitelist status for one asset"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const whitelisted = await client.readContract({
@@ -5049,7 +5647,15 @@ treasury.command("whitelist", {
   }
 });
 treasury.command("major-spend-status", {
+  description: "Read major-spend cooldown status for the treasury contract.",
   env: env5,
+  output: z5.object({
+    majorSpendCooldownSeconds: z5.number(),
+    lastMajorSpendAt: z5.number(),
+    lastMajorSpendRelative: z5.string(),
+    isMajorSpendAllowed: z5.boolean()
+  }),
+  examples: [{ description: "Inspect treasury major-spend guardrails" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [cooldown, lastMajorSpendAt, allowed] = await Promise.all([
@@ -5080,8 +5686,16 @@ treasury.command("major-spend-status", {
   }
 });
 treasury.command("executed", {
-  args: z5.object({ proposalId: z5.coerce.number().int().positive() }),
+  description: "Check whether a treasury action for a proposal has executed.",
+  args: z5.object({
+    proposalId: z5.coerce.number().int().positive().describe("Governance proposal id")
+  }),
   env: env5,
+  output: z5.object({
+    proposalId: z5.number(),
+    executed: z5.boolean()
+  }),
+  examples: [{ args: { proposalId: 1 }, description: "Check execution status for proposal #1" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const executed = await client.readContract({
@@ -5103,10 +5717,21 @@ cli.command(council);
 cli.command(forum);
 cli.command(governance);
 cli.command(treasury);
-var rootEnv = z6.object({ ABSTRACT_RPC_URL: z6.string().optional() });
+var rootEnv = z6.object({
+  ABSTRACT_RPC_URL: z6.string().optional().describe("Abstract RPC URL override")
+});
 cli.command("status", {
-  description: "Cross-contract status snapshot.",
+  description: "Get a cross-contract Assembly snapshot (members, council, governance, treasury).",
   env: rootEnv,
+  output: z6.object({
+    activeMemberCount: z6.number(),
+    seatCount: z6.number(),
+    proposalCount: z6.number(),
+    currentAuctionDay: z6.number(),
+    currentAuctionSlot: z6.number(),
+    treasuryBalance: z6.string()
+  }),
+  examples: [{ description: "Fetch the current Assembly system status" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [
@@ -5155,9 +5780,25 @@ cli.command("status", {
   }
 });
 cli.command("health", {
-  description: "Cross-contract health for one address.",
-  args: z6.object({ address: z6.string() }),
+  description: "Check cross-contract health for one address (membership, council, refunds, power).",
+  args: z6.object({
+    address: z6.string().describe("Member or wallet address to inspect")
+  }),
   env: rootEnv,
+  output: z6.object({
+    address: z6.string(),
+    isActive: z6.boolean(),
+    activeUntil: z6.number(),
+    isCouncilMember: z6.boolean(),
+    pendingReturnsWei: z6.string(),
+    votingPower: z6.number()
+  }),
+  examples: [
+    {
+      args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
+      description: "Inspect one address across Assembly contracts"
+    }
+  ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const [isActive, member, isCouncilMember, pendingReturns, votingPower] = await Promise.all([
@@ -5193,7 +5834,7 @@ cli.command("health", {
       })
     ]);
     return c.ok({
-      address: c.args.address,
+      address: toChecksum(c.args.address),
       isActive,
       activeUntil: Number(member.activeUntil),
       isCouncilMember,