Refresh droid-wiki: reorganize and add docs

.factory/settings.json

@@ -0,0 +1,3 @@
+{
+  "enabledPlugins": {}
+}

droid-wiki/.wiki-meta.json

@@ -1,27 +1,30 @@
 {
-  "generatedAt": "2026-05-13T17:04:06Z",
-  "commitHash": "5ff33e7314d127268d971500fcf8397f14a976d7",
-  "branch": "codex/wiki-refresh-2026-05-13",
-  "pageCount": 35,
+  "generatedAt": "2026-05-20T00:00:00Z",
+  "commitHash": "de42eb787d6e9cd71f0ca4631ece4157219d9695",
+  "branch": "develop",
+  "pageCount": 47,
   "topLevelSections": [
     "overview",
     "by-the-numbers",
+    "lore",
+    "fun-facts",
     "how-to-contribute",
     "applications",
     "systems",
     "features",
     "deployment",
     "security",
     "background",
-    "reference",
-    "maintainers"
+    "reference"
   ],
   "pageOrder": [
     "overview/index.md",
     "overview/architecture.md",
     "overview/getting-started.md",
     "overview/glossary.md",
     "by-the-numbers.md",
+    "lore.md",
+    "fun-facts.md",
     "how-to-contribute/index.md",
     "how-to-contribute/development-workflow.md",
     "how-to-contribute/testing.md",
@@ -30,27 +33,38 @@
     "how-to-contribute/tooling.md",
     "applications/index.md",
     "applications/cli.md",
+    "applications/install-script.md",
     "systems/index.md",
     "systems/command-registry.md",
-    "systems/output-rendering.md",
-    "systems/configuration-and-storage.md",
-    "systems/signing-and-auth.md",
+    "systems/signing-and-wallets.md",
+    "systems/error-and-output.md",
+    "systems/watch-and-streaming.md",
+    "systems/update-and-release.md",
+    "systems/input-hardening.md",
     "features/index.md",
+    "features/orders.md",
+    "features/transfers.md",
+    "features/subaccounts.md",
+    "features/staking-vaults-borrowlend.md",
+    "features/builder-and-referrals.md",
+    "features/api-wallets.md",
+    "features/account-and-portfolio.md",
     "features/market-data.md",
-    "features/orders-and-trading.md",
-    "features/wallets-and-signing.md",
-    "features/accounts-and-transfers.md",
-    "features/vaults-staking-and-defi.md",
-    "features/watch-and-subscribe.md",
+    "features/agent-output-contract.md",
+    "features/dry-run.md",
+    "features/schema-discovery.md",
+    "features/raw-payload.md",
+    "features/setup-wizard.md",
+    "features/feedback.md",
     "deployment.md",
     "security.md",
     "background/index.md",
-    "background/agent-first-contracts.md",
-    "background/ows-migration.md",
+    "background/design-decisions.md",
+    "background/pitfalls.md",
     "reference/index.md",
     "reference/configuration.md",
     "reference/data-models.md",
     "reference/dependencies.md",
-    "maintainers.md"
+    "reference/exit-codes.md"
   ]
 }

droid-wiki/applications/cli.md

@@ -1,65 +1,87 @@
-# CLI
+# `hyperliquid` CLI
 
-Active contributors: Sayo, wtfsayo
+The binary is defined in `src/main.rs` (1,079 lines) with clap derive macros. It declares a `Cli` struct with global flags, a `Commands` enum with ~25 top-level subcommands, and dispatches to per-command handlers in `src/cli_runtime.rs`.
 
-The `hyperliquid` binary is the main deliverable. It is a single Rust executable that parses CLI arguments via clap derive macros and dispatches to domain-specific command handlers.
+## Dispatch flow
 
-## Directory layout
-
-```
-src/
-├── main.rs               # clap CLI definition, arg parsing, format resolution, main()
-├── cli_runtime.rs         # Command routing, context resolution, API client setup
-├── lib.rs                 # Public module exports for integration testing
-├── command_registry.rs    # Typed command contracts from command_catalog.json
-├── command_handlers.rs    # Handler binding metadata for command contracts
-├── command_context.rs     # Per-call execution context (clients, output options)
-├── command_metadata.rs    # Metadata normalization from catalog entries
-├── update_check.rs        # Release update checks and self-update command
-└── commands/              # 23 domain command modules
+```mermaid
+graph TD
+    Argv[argv] --> Clap[clap parse<br/>src/main.rs::Cli]
+    Clap --> Format[Resolve --format<br/>HYPERLIQUID_FORMAT / TTY check]
+    Format --> Network[Resolve --testnet<br/>HYPERLIQUID_NETWORK / config]
+    Network --> Signer{Need signer?}
+    Signer -->|read-only| Skip[Skip signer resolution]
+    Signer -->|signed action| Resolve[resolvers::resolve_selected_signer]
+    Skip --> Dispatch
+    Resolve --> Dispatch[src/cli_runtime.rs<br/>match Commands]
+    Dispatch --> Handler[commands/*.rs handler]
+    Handler --> Output[src/output/mod.rs<br/>pretty / table / json]
+    Output --> Stdout[stdout]
+    Handler -->|error| ErrPath[src/errors.rs<br/>CliError + exit code]
 ```
 
-## Key abstractions
+## Global flags
 
-| Type | File | Description |
-|------|------|-------------|
-| `Cli` | `src/main.rs` | Top-level clap struct with global flags (format, signer, network, dry-run) |
-| `Commands` | `src/main.rs` | clap subcommand enum dispatching to domain groups |
-| `CommandRegistry` | `src/command_registry.rs` | In-memory typed registry loaded from `src/command_catalog.json` |
-| `CommandContract` | `src/command_registry.rs` | Typed contract per command (lifecycle, risk, dry-run policy, auth, inputs) |
-| `AppContext` | `src/cli_runtime.rs` | Resolved runtime context: network, signer, API URLs, HTTP clients |
-| `CommandContext` | `src/command_context.rs` | Per-command execution context with output projection and transport policy |
-| `UpdateResult` | `src/update_check.rs` | JSON/pretty result for `hyperliquid update` and dry-run update previews |
+| Flag | Purpose |
+|------|---------|
+| `--format pretty\|table\|json` | Output format. Default: pretty on TTY; JSON for non-TTY or `HYPERLIQUID_AGENT=1` |
+| `--private-key <HEX>` | Signer private key (overrides env/config) |
+| `--keystore <PATH>` | Foundry-compatible keystore file |
+| `--keystore-password <PASSWORD>` | Password for `--keystore` (prefer an interactive source in production) |
+| `--account <SELECTOR>` | Wallet name/id/address from the stored account DB |
+| `--ows-signer <SELECTOR>` | OWS signer selector (`0x` address, wallet name, or id) |
+| `--testnet` | Use testnet instead of mainnet |
+| `--select <FIELDS>` | JSON field projection |
+| `--results-only` | Strip envelope from JSON output |
+| `--max-results <N>` | Cap top-level array length |
+| `--dry-run` | Preview supported mutations |
+| `--no-update-check` | Skip the passive update notice |
+| `--payload-json <JSON>` | Raw JSON action payload (mutually exclusive with `--payload-file`) |
+| `--payload-file <PATH>` | Raw JSON action payload file (`-` for stdin) |
 
-## How it works
+`--private-key`, `--keystore`/`--keystore-password`, `--account`, and `--ows-signer` are mutually exclusive at parse time.
 
-```mermaid
-graph TD
-    Args[CLI args] --> Clap[clap parse]
-    Clap --> Format[resolve output format<br/>flag > env > agent/TTY default]
-    Clap --> Registry[CommandRegistry::load<br/>from command_catalog.json]
-    Clap --> Route[run_command dispatch]
+## Top-level command groups
 
-    Route --> Validate[validate_cli_inputs<br/>validate_stream_bounds]
-    Validate --> DryRun{--dry-run or --payload?}
-    DryRun -->|yes| CheckPolicy{dry_run supported?}
-    CheckPolicy -->|no| Err[Exit 13: unsupported]
-    CheckPolicy -->|yes| Resolve[AppContext::resolve]
+| Group | Subcommands | Page |
+|-------|-------------|------|
+| Market data | `mids`, `book`, `candles`, `spread`, `funding`, `status`, `meta` | [features/market-data](../features/market-data.md) |
+| Perps / Spot | `perps list/get`, `spot list/get` | [features/market-data](../features/market-data.md) |
+| Outcome markets | `outcomes list/get` | [features/market-data](../features/market-data.md) |
+| Asset utilities | `asset decode/search` | [features/market-data](../features/market-data.md) |
+| Account | `account fills/fees/rate-limit/orders/portfolio/subaccounts/portfolio-history/ledger/funding/twap-history/twap-fills/abstraction`, `account add/ls/set-default/remove` | [features/account-and-portfolio](../features/account-and-portfolio.md) |
+| API wallets | `api-wallet create/approve/list/revoke` | [features/api-wallets](../features/api-wallets.md) |
+| Subaccounts | `subaccount list/create/transfer/spot-transfer` | [features/subaccounts](../features/subaccounts.md) |
+| Orders | `orders create/scale/batch-create/tpsl/cancel/cancel-all/modify/twap-create/twap-cancel/schedule-cancel/open/status/history` | [features/orders](../features/orders.md) |
+| Positions | `positions list/leverage/isolated-margin` | (under [features/orders](../features/orders.md)) |
+| Transfers | `transfer *` | [features/transfers](../features/transfers.md) |
+| Wallets | `wallet create/import/import-mnemonic/list/show/address/rename/export/delete` | [systems/signing-and-wallets](../systems/signing-and-wallets.md) |
+| Staking | `staking *` | [features/staking-vaults-borrowlend](../features/staking-vaults-borrowlend.md) |
+| Vaults | `vault list/get/deposit/withdraw` | [features/staking-vaults-borrowlend](../features/staking-vaults-borrowlend.md) |
+| Borrow / lend | `borrowlend list/supply/withdraw` | [features/staking-vaults-borrowlend](../features/staking-vaults-borrowlend.md) |
+| Builder fees | `builder max-fee/approved/approve` | [features/builder-and-referrals](../features/builder-and-referrals.md) |
+| Referrals | `referral state/set/register` | [features/builder-and-referrals](../features/builder-and-referrals.md) |
+| Prio | `prio *` (gossip priority auction) | (under-the-hood) |
+| Schema | `schema [PATH...]` | [features/schema-discovery](../features/schema-discovery.md) |
+| Setup | `setup [-y]` | [features/setup-wizard](../features/setup-wizard.md) |
+| Subscribe | `subscribe trades/orderbook/candles/all-mids/orders/fills` | [systems/watch-and-streaming](../systems/watch-and-streaming.md) |
+| Feedback | `feedback` | [features/feedback](../features/feedback.md) |
+| Update | `update` | [systems/update-and-release](../systems/update-and-release.md) |
 
-    DryRun -->|no| Resolve
-    Resolve --> Signer[resolve signer<br/>private-key > keystore > account > OWS > stored default]
-    Signer --> Http[create HTTP client]
-    Http --> Dispatch[match on command variant]
-    Dispatch --> Handler[domain command handler]
-    Handler --> Output[render output<br/>pretty / table / json]
-```
+## Format resolution
 
-## Command dispatch
+The runtime resolves `--format` per command using these rules (in `src/main.rs` and `src/output/mod.rs`):
 
-The `run_command` function in `src/cli_runtime.rs` matches on each `Commands` variant and calls the corresponding handler in `src/commands/`. A few commands (wallet, local-only operations) skip API client creation. Read-only commands use `/info`; signed actions use `/exchange`.
+1. Explicit `--format` flag wins.
+2. Else `HYPERLIQUID_FORMAT` env var.
+3. Else pretty on a TTY; JSON if stdout is not a TTY or `HYPERLIQUID_AGENT=1`.
+
+Format is also threaded into watch and subscribe paths so JSON streams become NDJSON.
 
 ## Entry points for modification
 
-- **Add a new command**: define the clap variant in `src/main.rs`, add the dispatch arm in `src/cli_runtime.rs`, implement the handler in `src/commands/`, and add the contract to `src/command_catalog.json`
-- **Change output behavior**: modify `src/output/mod.rs` or the `TableData` impl on the command's output struct
-- **Change signer resolution**: modify `src/auth.rs`, `src/signing.rs`, or the `SignerResolverInput` flow in `src/resolvers.rs`
+- To add a new top-level command, add a `Commands` variant in `src/main.rs`, an enum for its subcommands if any, a runtime arm in `src/cli_runtime.rs`, and a handler module under `src/commands/`. Register metadata in `src/command_catalog.json`.
+- To change a global flag, edit `Cli` in `src/main.rs` and the propagation through `src/cli_runtime.rs`.
+- The legacy clap dispatch remains the execution authority during the registry rollout; do not delete it without following `docs/registry-rollout-policy.md`.
+
+See also: [systems/command-registry](../systems/command-registry.md), [overview/architecture](../overview/architecture.md).

droid-wiki/applications/index.md

@@ -1,9 +1,8 @@
 # Applications
 
-This repository ships a single binary:
+`hyperliquid-cli` ships as one Rust binary plus an installer script.
 
-| Binary | Crate | Entry point | Description |
-|--------|-------|-------------|-------------|
-| `hyperliquid` | `hyperliquid-cli` | `src/main.rs` | The main CLI for Hyperliquid DEX operations |
-
-The `hyperliquid` binary is the product surface.
+| Page | Description |
+|------|-------------|
+| [cli](cli.md) | The `hyperliquid` binary — global flags, command groups, dispatch |
+| [install-script](install-script.md) | `install.sh` — release lookup, SHA-256 verification, install location |

droid-wiki/applications/install-script.md

@@ -0,0 +1,53 @@
+# `install.sh`
+
+The installer is a POSIX shell script that downloads a release artifact, verifies its SHA-256 checksum, and places the binary in `~/.local/bin/hyperliquid` (or `$BIN_DIR`).
+
+## Usage
+
+```bash
+curl -fsSLO https://raw.githubusercontent.com/hypurrclaw/hyperliquid-cli/main/install.sh
+sh install.sh
+hyperliquid --version
+```
+
+For unattended environments:
+
+```bash
+sh install.sh --json --quiet
+```
+
+## What it does
+
+1. Detect platform via `uname -ms` and map to a release asset name.
+2. Resolve the latest release tag from `https://api.github.com/repos/hypurrclaw/hyperliquid-cli/releases/latest` (or `HYPERLIQUID_CLI_VERSION` if pinned).
+3. Download the asset tarball and its `.sha256` companion.
+4. Verify the checksum.
+5. Extract the binary and copy it to `BIN_DIR/hyperliquid` (default `~/.local/bin`).
+6. Make the binary executable.
+
+## Environment overrides
+
+| Variable | Purpose |
+|----------|---------|
+| `HYPERLIQUID_CLI_REPO=OWNER/REPO` | Alternate source repo |
+| `HYPERLIQUID_CLI_VERSION=v0.11.0` | Pinned version |
+| `BIN_DIR=/path/to/bin` | Alternate install location |
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--json` | Emit progress as JSON lines for programmatic consumption |
+| `--quiet` | Suppress non-error output |
+
+## Failure modes
+
+- Mismatched checksum aborts the install before touching `BIN_DIR`.
+- Missing asset for the platform exits non-zero with a clear message.
+- A pre-existing `BIN_DIR/hyperliquid` is overwritten; back up first if you need to roll back without redownloading.
+
+## See also
+
+- [systems/update-and-release](../systems/update-and-release.md) — the in-binary `hyperliquid update` path mirrors this logic.
+- [security](../security.md) — checksum verification and supply-chain notes.
+- The release artifacts are produced by `.github/workflows/release.yml`.