docs(cli): add db + measurement sections (arcctl PR3 surface)

docs/cli/db.md

@@ -0,0 +1,136 @@
+---
+sidebar_position: 5
+---
+
+# Database Administration
+
+`arcctl db` manages databases on an Arc cluster. The subcommands map directly onto Arc's `/api/v1/databases` endpoints.
+
+## Quick reference
+
+```bash
+# List every database the active token can see
+arcctl db list
+
+# Inspect one database (info + its measurements)
+arcctl db show production
+
+# Create an empty database
+arcctl db create metrics
+
+# Drop a database and ALL its files (prompts y/N; use --yes to skip)
+arcctl db drop old_metrics
+```
+
+## `db list`
+
+```bash
+arcctl db list
+arcctl db list -o json | jq '.databases[] | select(.measurement_count > 0)'
+arcctl db list -o csv > inventory.csv
+```
+
+Output formats: `table` (default), `json`, `csv`. Rows are sorted by name across every format so JSON / CSV / table agree on row order.
+
+Empty server (no databases) renders `(no databases)` so you know the call ran.
+
+## `db show <name>`
+
+```bash
+$ arcctl db show production
+Database: production
+Measurements: 4
+
+┌─────────────┬───────┐
+│ MEASUREMENT │ FILES │
+├─────────────┼───────┤
+│ cpu         │       │
+│ disk        │       │
+│ mem         │       │
+│ net         │       │
+└─────────────┴───────┘
+```
+
+Combines `GET /api/v1/databases/:name` with `GET /api/v1/databases/:name/measurements`. JSON output (`-o json`) composes them into one object:
+
+```json
+{
+  "database":     { "name": "production", "measurement_count": 4 },
+  "measurements": [{ "name": "cpu" }, { "name": "disk" }, ...],
+  "count":        4
+}
+```
+
+`-o csv` emits only the measurements list — the database header isn't tabular-shaped.
+
+If either API call fails, `arcctl` exits with that error and prints nothing — better to fail loud than render half a view.
+
+## `db create <name>`
+
+```bash
+$ arcctl db create metrics
+Created database "metrics" (created_at: 2026-05-31T23:39:58Z)
+```
+
+Server-side validation:
+
+- Name must start with a letter and contain only alphanumeric, underscore (`_`), or hyphen (`-`) characters, max 64.
+- Names `system`, `internal`, `_internal` are reserved.
+- Creating a database that already exists returns HTTP 409.
+
+The server's error messages surface verbatim, so a rejected create gives an actionable hint:
+
+```bash
+$ arcctl db create 1bad
+Error: arc: Invalid database name: must start with a letter and contain only alphanumeric characters, underscores, or hyphens (max 64 characters) (HTTP 400)
+```
+
+## `db drop <name>`
+
+**Destructive.** Drops a database and **all** of its files.
+
+```bash
+# Interactive: prompts y/N
+$ arcctl db drop old_metrics
+Delete database "old_metrics" and ALL its files? [y/N] y
+Deleted database "old_metrics"
+
+# Scripted: --yes skips the prompt
+$ arcctl db drop --yes ci_scratch
+Deleted database "ci_scratch"
+```
+
+Layered safety. arcctl gates the call client-side; Arc gates it server-side:
+
+1. **Client-side prompt** — default is N. Pass `--yes` (or `-y`) to skip; anything other than `y` / `yes` (case-insensitive) aborts.
+2. **Server requires `delete.enabled=true`** in `arc.toml`. If not set, the server returns HTTP 403 with the verbatim message `"Delete operations are disabled. Set delete.enabled=true in arc.toml to enable."` — arcctl surfaces it as-is.
+3. **Server requires admin token.** A read- or write-only token gets HTTP 403 from the server, surfaced verbatim.
+4. **Server blocks reserved names** (`system`, `internal`, `_internal`). HTTP 403, surfaced verbatim.
+5. **Server requires `?confirm=true`** on the request URL. arcctl always sends it; no operator-visible knob.
+
+`arcctl` never bypasses any of these. If a drop fails, the message will tell you why.
+
+## Connection overrides
+
+All `db` subcommands accept the same connection flags as `query` and `write`:
+
+```bash
+# Named profile
+arcctl db list --connection prod
+
+# Ad-hoc (no profile)
+arcctl db list --endpoint https://arc.x.example.com --token YOUR-TOKEN
+
+# CI-friendly env vars
+ARC_CONNECTION=prod arcctl db list
+ARC_ENDPOINT=https://... ARC_TOKEN=... arcctl db list
+```
+
+See [Connection management](/arc/cli/connections#precedence) for the full precedence rules.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (including `Aborted.` on a declined `db drop` prompt) |
+| 1 | Any failure: bad flags, network error, server error, missing connection |

docs/cli/index.md

@@ -34,7 +34,8 @@ Operating Arc without arcctl means:
 |---|---|
 | v0.1.0 (PR1) | `config` subcommand tree, multi-connection store at `~/.arcctl/config.toml` |
 | v0.2.0 (PR2) | `query`, `write` — table / JSON / CSV / Arrow IPC output, stdin / file input |
-| v0.3.0+ | `db`, `import`, `auth`, `cluster` subcommands (in development) |
+| v0.3.0 (PR3) | `db {list,show,create,drop}`, `measurement list` |
+| v0.4.0+ | `import`, `auth`, `cluster` subcommands (in development) |
 | v1.0.0 | release workflow + Homebrew tap + multi-arch Docker |
 
 ## Compatibility
@@ -59,3 +60,5 @@ Requires Go 1.25+.
 - [Connection management](/arc/cli/connections) — adding, switching, and overriding connection profiles
 - [Querying](/arc/cli/query) — running SQL with table / JSON / CSV / Arrow output
 - [Writing line protocol](/arc/cli/write) — stdin and file ingestion with precision control
+- [Database administration](/arc/cli/db) — list / show / create / drop databases
+- [Measurement listing](/arc/cli/measurement) — list measurements within a database

docs/cli/measurement.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 6
+---
+
+# Measurement Listing
+
+`arcctl measurement list` shows the measurements inside one database. It's a thin wrapper over `GET /api/v1/databases/:name/measurements` — the same data as `arcctl db show <name>`, but presented measurement-first.
+
+Use `arcctl db show` when you want database metadata plus its measurements. Use `arcctl measurement list` when measurements are the primary thing you care about (scripts, CI, alerts).
+
+## Quick reference
+
+```bash
+# Use the active connection's default_database
+arcctl measurement list
+
+# Explicit database
+arcctl measurement list --database metrics
+
+# Pipe to jq
+arcctl measurement list --database logs -o json | jq '.measurements[].name'
+
+# Save to CSV (includes the database column for downstream joins)
+arcctl measurement list --database production -o csv > production-measurements.csv
+```
+
+## Database selection
+
+The database name comes from one of three places, in this precedence:
+
+1. `--database NAME` flag
+2. Active connection's `default_database` (set via `arcctl config create --default-database NAME`)
+3. *(nothing else)*
+
+If neither is set, the command exits with a clear error before any network call:
+
+```bash
+$ arcctl measurement list
+Error: no database specified (pass --database or set default_database on the active connection)
+```
+
+## Output formats
+
+### Table (default)
+
+```bash
+$ arcctl measurement list --database production
+┌─────────────┬───────┐
+│ MEASUREMENT │ FILES │
+├─────────────┼───────┤
+│ cpu         │       │
+│ disk        │       │
+│ mem         │       │
+│ net         │       │
+└─────────────┴───────┘
+```
+
+Rows sorted alphabetically. `FILES` is empty when the server omits the field (older Arc versions or when file counts haven't been computed).
+
+Empty database: `(no measurements in database "X")` so you know the call ran.
+
+### JSON
+
+```bash
+$ arcctl measurement list --database production -o json
+{
+  "database": "production",
+  "measurements": [
+    { "name": "cpu" },
+    { "name": "disk" },
+    { "name": "mem" },
+    { "name": "net" }
+  ],
+  "count": 4
+}
+```
+
+Server-reported `count` is passed through verbatim — not re-derived from `len(measurements)` — so a future Arc server that paginates results will not silently disagree with itself.
+
+### CSV
+
+```bash
+$ arcctl measurement list --database production -o csv
+database,measurement,file_count
+production,cpu,
+production,disk,
+production,mem,
+production,net,
+```
+
+The CSV includes a leading `database` column so you can concatenate output across multiple `arcctl measurement list` calls without losing context:
+
+```bash
+for db in production staging logs; do
+  arcctl measurement list --database "$db" -o csv --no-header
+done > all-measurements.csv
+```
+
+## Connection overrides
+
+Same flags as every other arcctl command:
+
+```bash
+arcctl measurement list -c prod --database metrics
+arcctl measurement list --endpoint https://arc.x.example.com --token YOUR-TOKEN --database logs
+ARC_CONNECTION=prod arcctl measurement list --database metrics
+```
+
+See [Connection management](/arc/cli/connections#precedence).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success (including 0 measurements) |
+| 1 | Any failure: missing database, network error, server error, missing connection |