aweshare 0.5.9 → 0.6.1

package/apps/hub/dist/cli.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { fmtDate, fmtTime } from '../../../packages/protocol/dist/index.js';
 import { ensureDataDir, HUB_CONFIG_TEMPLATE, initHubProduceFiles, loadHubConfig, readAdminToken, resolvePaths, } from './config.js';
 import { createHubServer, installConfigReloader } from './server.js';
-import { refreshTargets, renderHubStatus, renderInvites, renderUsage, renderUsageSummary, } from './table.js';
+import { refreshTargets, renderConsumers, renderHubStatus, renderInvites, renderOfferings, renderProducers, renderUsage, renderUsageSummary, } from './table.js';
 import { loadOrCreateAdminToken, loadOrCreatePepper } from './tokens.js';
 const VERSION = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8')).version;
 // One-liners only; flags per command live in their own -h, everything else in README.
@@ -17,14 +17,12 @@ Options:
 
 Commands:
   init     Create the data dir, pepper, and admin token.
-  serve    Run the hub server.
-  produce  Run the hub serving its own models too (hub/...); 'refresh'
-           re-anchors or raises one hub model's daily token budget.
-  invite   Mint invite codes (default); revoke or restore one by id.
-  list     Read hub state: invites (the ledger) or usage (consumption).
-  limits   Show, set or clear one consumer's limit overrides.
-  status   Live state: capacity, offering health; rosters print with --all.
-  offering Block or restore one offering alias (the per-alias scalpel).`;
+  serve    Run the hub server (the only runner; config.produce.toml mounts itself).
+  produce  Hub-local models: init scaffolds, refresh re-anchors today's budgets.
+  admin    Govern: invite mint|revoke|restore, offering revoke|restore.
+  list     Read hub state: invites (default), producers, consumers, offerings, usage.
+  status   Live dashboard: capacity, 5m health, admission pressure, defaults.
+  limits   Show, set or clear one consumer's limit overrides.`;
 const COMMAND_HELP = {
     init: `Usage: aweshare hub init
 
@@ -34,7 +32,9 @@ Options:
   -h, --help  Show this message and exit.`,
     serve: `Usage: aweshare hub serve [OPTIONS]
 
-  Run the hub server.
+  Run the hub server — the only runner. A config.produce.toml in the
+  data dir mounts automatically: its [[backends]]/[[offerings]] are
+  served in-process as hub/... (scaffold one with: aweshare hub produce init).
 
   Tunables in config.toml (rate limits, timeouts, maxProducers) hot-reload:
   edits are picked up within a couple of seconds (or send SIGHUP at once);
@@ -44,14 +44,15 @@ Options:
   --host ADDR  Address to listen on (default from AWESHARE_HUB_HOST, else 0.0.0.0).
   --port N     Port to listen on, 1..65535 (default from AWESHARE_HUB_PORT, else 8787).
   -h, --help   Show this message and exit.`,
-    produce: `Usage: aweshare hub produce [init|refresh] [OPTIONS]
+    produce: `Usage: aweshare hub produce init|refresh [OPTIONS]
 
-  Run the hub with its own models attached. Identical to 'serve'; the
-  difference is intent: define [[backends]] and [[offerings]] in the data
-  dir's config.produce.toml (namespace hub/...), put upstream keys in secrets.json
-  next to it, and consumers reach those models as hub/<name> — served by
-  this process directly, no producer tunnel. Same flags as serve; catalog
-  edits hot-reload like every other config key.
+  Hub-local models — the hub serving its own catalog, no producer agent.
+  Define [[backends]] and [[offerings]] in the data dir's
+  config.produce.toml (namespace hub/...), put upstream keys in
+  secrets.json next to it, and consumers reach those models as
+  hub/<name>. Running the server is 'aweshare hub serve' — the same
+  runner mounts the catalog automatically; this group only scaffolds
+  and re-anchors budgets.
 
   ` +
         '`init`' +
@@ -78,14 +79,34 @@ Options:
     aweshare hub produce refresh glm-5.3 --clear        # drop both markers
 
 Options:
-  --host ADDR  Address to listen on (default from AWESHARE_HUB_HOST, else 0.0.0.0).
-  --port N     Port to listen on, 1..65535 (default from AWESHARE_HUB_PORT, else 8787).
   --add N      refresh only: raise today's cap by N tokens until Beijing midnight.
   --clear      refresh only: drop the refresh marker and any bonus.
   --all        refresh only: bare-refresh every hub/... model (no ALIAS, --add or --clear).
   --json       refresh only: print the raw API response(s).
   -h, --help   Show this message and exit.`,
-    invite: `Usage: aweshare hub invite [mint|revoke|restore] [ARGS] [OPTIONS]
+    admin: `Usage: aweshare hub admin [invite|offering] ACTION [ARGS] [OPTIONS]
+
+  The operator's write operations, one gate. Reads are 'list', the live
+  dashboard is 'status', tuning is 'limits' — everything that changes
+  hub state lives here (thin wrappers over the admin REST API).
+
+  Commands:
+    invite mint [...]         Mint one-time invite codes.
+    invite revoke N           Kill invite N — the sledgehammer: a pending
+                              code stops pairing, a redeemed one suspends
+                              the whole producer or consumer it minted.
+    invite restore N          Undo an invite revoke.
+    offering revoke ALIAS     The scalpel: 503 OFFERING_BLOCKED for new
+                              requests to one alias while the producer's
+                              other offerings keep serving.
+    offering restore ALIAS    Undo an offering revoke.
+
+  Run 'aweshare hub admin invite -h' or 'aweshare hub admin offering -h'
+  for the full semantics of each group.
+
+Options:
+  -h, --help  Show this message and exit.`,
+    'admin invite': `Usage: aweshare hub admin invite [mint|revoke|restore] [ARGS] [OPTIONS]
 
   The invite lifecycle. One code, one identity — and the invite is the
   operator's handle from mint to suspension: revoking a redeemed code
@@ -93,7 +114,7 @@ Options:
   a consumer's key stops working); restoring brings both back.
 
   Commands:
-    mint      Mint one-time invite codes (default). Printed once; recover
+    mint      Mint one-time invite codes. Printed once; recover
               with: aweshare hub list invites --reveal. Listing lives under
               'list invites' on purpose — minting sends real codes, reading
               the ledger never should.
@@ -114,19 +135,38 @@ Options:
                     token's lifetime; 'none' mints a code (and identity) that
                     never expires.
     -h, --help      Show this message and exit.`,
-    list: `Usage: aweshare hub list [invites|usage] [OPTIONS]
+    'admin offering': `Usage: aweshare hub admin offering revoke|restore ALIAS
+
+  Revoke one offering alias (every protocol row of it) or bring it back —
+  the scalpel between doing nothing and revoking the whole producer
+  ('admin invite revoke'). A revoke 503s new requests with
+  OFFERING_BLOCKED while the producer's other offerings keep serving;
+  'list offerings' shows 'blocked'. Manual revokes survive producer
+  re-registers; auto revokes (repeated model mismatch, only when
+  autoBlockModelMismatch is enabled) clear once the producer re-declares
+  a different upstreamModel.
+
+Options:
+  -h, --help  Show this message and exit.`,
+    list: `Usage: aweshare hub list [invites|producers|consumers|offerings|usage] [OPTIONS]
 
-  Read hub state (default: invites). The rosters and offering health live in
-  'aweshare hub status'; this is the ledger and the meter.
+  Read hub state, one table per noun (default: invites). The live
+  dashboard is 'aweshare hub status'.
 
   Commands:
-    invites  The invite ledger: every code, the identity it minted and its
-             lifecycle (pending/used/suspended/revoked/expired).
-    usage    Who used how much: aggregated on the hub's SQLite, one row per
-             consumer × model (default) — a person's rows stay together,
-             busiest person and busiest model first. --details switches to the
-             request log instead: newest first, one row per request, zero
-             content stored, each row naming the consumer that made it.
+    invites    The invite ledger: every code, the identity it minted and its
+               lifecycle (pending/used/suspended/revoked/expired).
+    producers  The producer roster: name, status, online state, last seen.
+    consumers  The consumer roster: name, status, last seen.
+    offerings  The catalog: one row per alias, worst status first — the same
+               columns as 'consumer list' ('aweshare consumer list' from the
+               other side), with observed model, caps, live occupancy and
+               today's remaining tokens.
+    usage      Who used how much: aggregated on the hub's SQLite, one row per
+               consumer × model (default), most recently used first. --details
+               switches to the request log instead: newest first, one row per
+               request, zero content stored, each row naming the consumer
+               that made it.
 
   Options:
     --reveal          Invites only: show the full invite codes (asi_...).
@@ -138,8 +178,12 @@ Options:
     --alias ALIAS     Usage only: only rows for this alias (ns/model).
     --group-by KEY    Usage only: consumer × model (default), consumer or alias.
     --since DUR       Usage only: window: 30m, 12h, 7d (default), 30d… or all.
+    --sort KEY        Usage summary only: time (default, newest first), consumer,
+                      producer or model (alphabetical, newest first within), or
+                      tokens / requests (busiest first; tokens keeps a person's
+                      rows together).
     --limit N         Usage --details only: rows to show, 1..1000 (default 100).
-    --json            Print the raw API response instead of a table.
+    --json            Print the raw API rows instead of a table.
     -h, --help        Show this message and exit.`,
     limits: `Usage: aweshare hub limits NAME [OPTIONS]
 
@@ -156,31 +200,16 @@ Options:
     --clear               Drop every override (back to hub-wide defaults).
     --json                Print the raw API response instead of text.
     -h, --help            Show this message and exit.`,
-    status: `Usage: aweshare hub status [OPTIONS]
+    status: `Usage: aweshare hub status
 
-  The hub's live state: capacity, offering health and the effective hub-wide
-  consumer defaults. No tokens or request contents appear. Offerings are
-  counted per deduplicated alias (one alias, several protocols, one verdict —
-  the worst); the alias table uses the same columns as 'consumer list' and
-  'producer list', sorted worst status first, with live occupancy (IN USE
-  n/max) and today's remaining daily tokens. The last-5m health line comes
-  from the usage summary — admission 429s are never metered, so it reflects
-  relayed outcomes only. The producer/consumer rosters are counts here; pass
-  --all to print them in full.
-
-Options:
-  --all       Also print the producer and consumer rosters (name, status,
-              online state, last seen).
-  -h, --help  Show this message and exit.`,
-    offering: `Usage: aweshare hub offering block|restore ALIAS
-
-  Block one offering alias (every protocol row of it) or bring it back — the
-  scalpel between doing nothing and revoking the whole producer. A block 503s
-  new requests with OFFERING_BLOCKED while the producer's other offerings
-  keep serving; status shows 'blocked'. Manual blocks survive producer
-  re-registers; auto blocks (repeated model mismatch, only when
-  autoBlockModelMismatch is enabled) clear once the producer re-declares a
-  different upstreamModel.
+  The hub's live dashboard: capacity, the last-5m health, admission
+  (rate-limit) pressure and the effective hub-wide consumer defaults.
+  No tokens or request contents appear, and no tables — every table
+  this summarizes lives under 'aweshare hub list' (producers, consumers,
+  offerings, usage). The last-5m health line comes from the usage
+  summary — admission 429s are never metered, so it reflects relayed
+  outcomes only; the rejection lines are the throttling that summary
+  cannot see, the tuning evidence for 'limits' and per-offering caps.
 
 Options:
   -h, --help  Show this message and exit.`,
@@ -212,6 +241,26 @@ function fail(message) {
     console.error(`error: ${message}`);
     process.exit(1);
 }
+/** Flags each command accepts (beyond -h/--help); anything else is a typo
+ * and must fail loudly. Commands whose subcommands take different flags
+ * (produce, admin, list) resolve the allowed list first, then call this. */
+function checkFlags(cmd, flags, allowed) {
+    for (const name of flags.keys()) {
+        if (name !== 'help' && !allowed.includes(name))
+            fail(`unknown option '--${name}' (see: aweshare hub ${cmd} -h)`);
+    }
+}
+/** Deepest matching help entry: 'admin invite mint -h' shows the invite
+ * help, 'hub produce refresh -h' the produce help. */
+function helpFor(cmd, positional) {
+    const words = [cmd, ...positional.filter((a) => !a.startsWith('-'))];
+    for (let n = words.length; n >= 1; n--) {
+        const help = COMMAND_HELP[words.slice(0, n).join(' ')];
+        if (help)
+            return help;
+    }
+    return undefined;
+}
 /** Listen, turning bind errors (EADDRINUSE, unbindable host) into the CLI's
  * one-line error shape instead of an uncaught 'error' event stack trace. */
 function listenOrFail(hub, host, port) {
@@ -339,6 +388,28 @@ function fmtLimits(name, overrides) {
         ? `${name}: ${set.join(', ')}`
         : `${name}: no overrides — hub-wide defaults apply (AWESHARE_CONSUMER_* env vars)`;
 }
+/** The five readable tables; bare `list` defaults to the ledger (a read,
+ * and the one operators reach for first). */
+const LIST_TARGETS = ['invites', 'producers', 'consumers', 'offerings', 'usage'];
+/** Flags each list target accepts — a flag from another target is a typo. */
+const LIST_FLAGS = {
+    invites: ['reveal', 'token', 'json'],
+    producers: ['json'],
+    consumers: ['json'],
+    offerings: ['json'],
+    usage: ['details', 'consumer', 'producer', 'alias', 'group-by', 'since', 'sort', 'limit', 'json'],
+};
+/** Sort keys `hub list usage --sort` accepts, mirroring the API's sort param. */
+const USAGE_SORTS = ['time', 'consumer', 'producer', 'model', 'tokens', 'requests'];
+/** What the summary header says for each sort key. */
+const SORT_LABELS = {
+    time: 'recent first',
+    consumer: 'consumer',
+    producer: 'producer',
+    model: 'model',
+    tokens: 'tokens, busiest first',
+    requests: 'requests, busiest first',
+};
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const { positional, flags } = parseArgs(rest);
@@ -350,7 +421,7 @@ async function main() {
         console.log(USAGE);
         return;
     }
-    const help = COMMAND_HELP[cmd];
+    const help = helpFor(cmd, positional);
     if (help && (positional.includes('-h') || flags.get('help') === 'true')) {
         console.log(help);
         return;
@@ -358,6 +429,8 @@ async function main() {
     const paths = resolvePaths();
     switch (cmd) {
         case 'init': {
+            checkFlags('init', flags, []);
+            noPositionals('init', positional);
             ensureDataDir(paths);
             loadOrCreatePepper(paths);
             const tokenExisted = existsSync(paths.adminTokenFile);
@@ -376,8 +449,7 @@ async function main() {
             return;
         }
         case 'serve': {
-            // same runner — 'produce' just names the intent; the local catalog is
-            // config-driven and loads either way
+            checkFlags('serve', flags, ['host', 'port']);
             noPositionals('serve', positional);
             const hub = createHubServer({ paths });
             installConfigReloader(hub);
@@ -390,11 +462,20 @@ async function main() {
             return;
         }
         case 'produce': {
-            if (positional[0] === 'init') {
+            const sub = positional[0];
+            if (!sub) {
+                // serve absorbed the runner: the local catalog is config-driven and
+                // mounts either way, so a second runner only invited drift
+                fail("'hub produce' no longer runs the server — 'aweshare hub serve' is the only runner and mounts config.produce.toml by itself;\n" +
+                    "this group is produce init (scaffold) and produce refresh (re-anchor today's budgets)");
+            }
+            if (sub !== 'init' && sub !== 'refresh') {
+                fail(`unknown produce action '${sub}' — expected init or refresh (the runner is: aweshare hub serve)`);
+            }
+            if (sub === 'init') {
+                checkFlags('produce', flags, []);
                 if (positional[1])
                     fail(`unexpected argument '${positional[1]}' (see: aweshare hub produce -h)`);
-                if (flags.size > 0)
-                    fail(`'aweshare hub produce init' takes no options`);
                 const files = initHubProduceFiles(paths);
                 loadOrCreatePepper(paths);
                 const adminToken = loadOrCreateAdminToken(paths);
@@ -404,80 +485,127 @@ async function main() {
                 console.log(`secrets file: ${paths.secretsFile} (${files.secretsCreated ? 'created' : 'already exists; kept'})`);
                 console.log(`data dir:    ${paths.dataDir}`);
                 console.log(`admin token: ${adminToken}`);
-                console.log('next: add [[backends]] / [[offerings]] to config.produce.toml, fill secrets.json, then run: aweshare hub produce');
+                console.log('next: add [[backends]] / [[offerings]] to config.produce.toml, fill secrets.json, then run: aweshare hub serve');
                 return;
             }
-            if (positional[0] === 'refresh') {
-                const raw = positional[1];
-                const all = flags.get('all') === 'true';
-                if (positional[2])
-                    fail(`unexpected argument '${positional[2]}' (see: aweshare hub produce -h)`);
-                if (all) {
-                    if (raw)
-                        fail(`--all refreshes every hub/ model — drop the alias '${raw}'`);
-                    if (flags.get('add') !== undefined || flags.get('clear') === 'true')
-                        fail('--all is a bare refresh of every hub/ model — --add/--clear stay single-alias');
-                    const api = adminApi();
-                    await runProduceRefreshAll(api, flags.get('json') === 'true');
-                    return;
-                }
-                if (!raw)
-                    fail('produce refresh: alias is required (hub/model — the hub/ prefix is optional), or --all for every hub/ model');
-                // hub-hosted offerings live in the reserved hub/ namespace — accept
-                // the bare name too; anything else the hub rejects as not its own
-                const alias = raw.includes('/') ? raw : `hub/${raw}`;
-                const params = new URLSearchParams({ alias });
-                const add = flags.get('add');
-                if (add !== undefined) {
-                    const n = Number(add);
-                    if (!Number.isSafeInteger(n) || n <= 0)
-                        fail(`--add must be a positive integer, got '${add}'`);
-                    params.set('add', String(n));
-                }
-                if (flags.get('clear') === 'true') {
-                    if (add !== undefined)
-                        fail('--clear drops both markers — drop --add too');
-                    params.set('clear', 'true');
-                }
+            checkFlags('produce', flags, ['add', 'clear', 'all', 'json']);
+            const raw = positional[1];
+            const all = flags.get('all') === 'true';
+            if (positional[2])
+                fail(`unexpected argument '${positional[2]}' (see: aweshare hub produce -h)`);
+            if (all) {
+                if (raw)
+                    fail(`--all refreshes every hub/ model — drop the alias '${raw}'`);
+                if (flags.get('add') !== undefined || flags.get('clear') === 'true')
+                    fail('--all is a bare refresh of every hub/ model — --add/--clear stay single-alias');
                 const api = adminApi();
-                const out = (await api('POST', `/admin/v1/offerings/refresh?${params}`));
-                if (flags.get('json') === 'true') {
-                    console.log(JSON.stringify(out, null, 2));
-                    return;
-                }
-                printRefreshResult(out);
-                if (out.reset)
-                    console.log(`  undo: aweshare hub produce refresh ${out.alias} --clear`);
+                await runProduceRefreshAll(api, flags.get('json') === 'true');
                 return;
             }
-            // same runner as serve — 'produce' names the intent; the local catalog
-            // is config-driven and loads either way.
-            noPositionals('produce', positional);
-            const hub = createHubServer({ paths });
-            installConfigReloader(hub);
-            const host = flags.get('host') ?? hub.config.host;
-            const port = Number(flags.get('port') ?? hub.config.port);
-            if (!Number.isInteger(port) || port < 1 || port > 65535) {
-                fail(`--port must be an integer between 1 and 65535, got '${flags.get('port')}'`);
+            if (!raw)
+                fail('produce refresh: alias is required (hub/model — the hub/ prefix is optional), or --all for every hub/ model');
+            // hub-hosted offerings live in the reserved hub/ namespace — accept
+            // the bare name too; anything else the hub rejects as not its own
+            const alias = raw.includes('/') ? raw : `hub/${raw}`;
+            const params = new URLSearchParams({ alias });
+            const add = flags.get('add');
+            if (add !== undefined) {
+                const n = Number(add);
+                if (!Number.isSafeInteger(n) || n <= 0)
+                    fail(`--add must be a positive integer, got '${add}'`);
+                params.set('add', String(n));
             }
-            listenOrFail(hub, host, port);
+            if (flags.get('clear') === 'true') {
+                if (add !== undefined)
+                    fail('--clear drops both markers — drop --add too');
+                params.set('clear', 'true');
+            }
+            const api = adminApi();
+            const out = (await api('POST', `/admin/v1/offerings/refresh?${params}`));
+            if (flags.get('json') === 'true') {
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            printRefreshResult(out);
+            if (out.reset)
+                console.log(`  undo: aweshare hub produce refresh ${out.alias} --clear`);
             return;
         }
-        case 'invite': {
-            // the invite lifecycle: mint (default), revoke, restore — one code, one
-            // identity, and every suspension travels through the invite that minted it
-            const sub = positional[0] ?? 'mint';
-            if (sub !== 'mint' && sub !== 'revoke' && sub !== 'restore') {
-                fail(`unknown invite action '${sub}' — expected mint, revoke or restore`);
+        case 'admin': {
+            // the write gate: every state-changing verb lives here — bare calls
+            // print help (the safest action), nothing mutates by accident
+            const group = positional[0];
+            if (!group) {
+                console.log(COMMAND_HELP.admin);
+                return;
+            }
+            if (group !== 'invite' && group !== 'offering') {
+                fail(`unknown admin target '${group}' — expected invite or offering (see: aweshare hub admin -h)`);
+            }
+            const action = positional[1];
+            if (!action) {
+                console.log(COMMAND_HELP[`admin ${group}`]);
+                return;
             }
             const api = adminApi();
-            if (sub === 'revoke' || sub === 'restore') {
-                const id = positional[1];
+            if (group === 'invite') {
+                if (action !== 'mint' && action !== 'revoke' && action !== 'restore') {
+                    fail(`unknown invite action '${action}' — expected mint, revoke or restore`);
+                }
+                if (action === 'mint') {
+                    checkFlags('admin invite', flags, ['role', 'name', 'count', 'expires-in']);
+                    if (positional[2])
+                        fail(`unexpected argument '${positional[2]}' (see: aweshare hub admin invite -h)`);
+                    const body = {};
+                    const role = flags.get('role') ?? 'producer';
+                    if (role !== 'producer' && role !== 'consumer')
+                        fail("--role must be 'producer' or 'consumer'");
+                    body.role = role;
+                    const name = flags.get('name');
+                    if (name)
+                        body.name = name;
+                    if (role === 'consumer' && !name)
+                        fail('consumer invites need --name (limits, usage and suspension reference consumers by name)');
+                    const count = flags.get('count');
+                    if (role === 'consumer' && count && count !== '1')
+                        fail('consumer invites are one per name — drop --count and mint one per consumer');
+                    // absent flag still mints a 7d code — an unexpiring secret should be a
+                    // deliberate choice (`none` here; API callers may omit expiresAt). Since
+                    // v12 the expiry also bounds the minted identity's lifetime.
+                    const expiresIn = flags.get('expires-in') ?? '7d';
+                    if (expiresIn !== 'none') {
+                        body.expiresAt = new Date(Date.now() + parseDuration(expiresIn)).toISOString();
+                    }
+                    if (count) {
+                        const n = Number(count);
+                        if (!Number.isInteger(n) || n < 1 || n > 100) {
+                            fail(`--count must be an integer between 1 and 100, got '${count}'`);
+                        }
+                        body.count = n;
+                    }
+                    const out = (await api('POST', '/admin/v1/invites', body));
+                    for (const invite of out.invites)
+                        console.log(invite.code);
+                    if (role === 'consumer') {
+                        console.error('(save this now; codes print only here — re-view later with: aweshare hub list invites --reveal.\n' +
+                            `hand it to '${name}' — they redeem it and keep the returned asc_ token:\n` +
+                            '  aweshare consumer join --hub https://YOUR-HUB --code CODE\n' +
+                            'no aweshare installed? curl -s -X POST https://YOUR-HUB/invites/v1/redeem -H \'content-type: application/json\' -d \'{"code":"asi_..."}\')');
+                    }
+                    else {
+                        console.error(name
+                            ? '(save these now; codes print only here — re-view later with: aweshare hub list invites --reveal. redeem: aweshare producer join --hub URL --code CODE)'
+                            : '(save these now; codes print only here — re-view later with: aweshare hub list invites --reveal. redeem: aweshare producer join --hub URL --code CODE --name NAME --email YOU@EXAMPLE.COM)');
+                    }
+                    return;
+                }
+                checkFlags('admin invite', flags, []);
+                const id = positional[2];
                 if (!id)
-                    fail(`invite ${sub}: id is required (find ids with: aweshare hub list invites)`);
-                if (positional[2])
-                    fail(`unexpected argument '${positional[2]}' (see: aweshare hub invite -h)`);
-                if (sub === 'revoke') {
+                    fail(`invite ${action}: id is required (find ids with: aweshare hub list invites)`);
+                if (positional[3])
+                    fail(`unexpected argument '${positional[3]}' (see: aweshare hub admin invite -h)`);
+                if (action === 'revoke') {
                     const out = (await api('DELETE', `/admin/v1/invites/${id}`));
                     if (!out.revoked && !out.suspended) {
                         console.log(`invite ${id} was already revoked — nothing to do`);
@@ -489,7 +617,7 @@ async function main() {
                     else {
                         console.log(`✓ invite ${id} revoked — the code no longer pairs`);
                     }
-                    console.log(`  undo: aweshare hub invite restore ${id}`);
+                    console.log(`  undo: aweshare hub admin invite restore ${id}`);
                     return;
                 }
                 const out = (await api('POST', `/admin/v1/invites/${id}/restore`));
@@ -508,65 +636,39 @@ async function main() {
                 }
                 return;
             }
-            if (positional[1])
-                fail(`unexpected argument '${positional[1]}' (see: aweshare hub invite -h)`);
-            // minting is the one state-changing read-adjacent verb — refuse the old
-            // ledger flag loudly instead of silently minting a code
-            if (flags.has('list')) {
-                fail("'hub invite --list' became its own command — the ledger is: aweshare hub list invites");
-            }
-            const body = {};
-            const role = flags.get('role') ?? 'producer';
-            if (role !== 'producer' && role !== 'consumer')
-                fail("--role must be 'producer' or 'consumer'");
-            body.role = role;
-            const name = flags.get('name');
-            if (name)
-                body.name = name;
-            if (role === 'consumer' && !name)
-                fail('consumer invites need --name (limits, usage and suspension reference consumers by name)');
-            const count = flags.get('count');
-            if (role === 'consumer' && count && count !== '1')
-                fail('consumer invites are one per name — drop --count and mint one per consumer');
-            // absent flag still mints a 7d code — an unexpiring secret should be a
-            // deliberate choice (`none` here; API callers may omit expiresAt). Since
-            // v12 the expiry also bounds the minted identity's lifetime.
-            const expiresIn = flags.get('expires-in') ?? '7d';
-            if (expiresIn !== 'none') {
-                body.expiresAt = new Date(Date.now() + parseDuration(expiresIn)).toISOString();
-            }
-            if (count) {
-                const n = Number(count);
-                if (!Number.isInteger(n) || n < 1 || n > 100) {
-                    fail(`--count must be an integer between 1 and 100, got '${count}'`);
-                }
-                body.count = n;
+            // offering: the per-alias scalpel ('block' renamed to 'revoke' — the
+            // hub error code stays OFFERING_BLOCKED, the API path stays /block)
+            if (action === 'block') {
+                fail("'block' became 'revoke' — it is 'aweshare hub admin offering revoke ALIAS' now");
             }
-            const out = (await api('POST', '/admin/v1/invites', body));
-            for (const invite of out.invites)
-                console.log(invite.code);
-            if (role === 'consumer') {
-                console.error('(save this now; codes print only here — re-view later with: aweshare hub list invites --reveal.\n' +
-                    `hand it to '${name}' — they redeem it and keep the returned asc_ token:\n` +
-                    '  aweshare consumer join --hub https://YOUR-HUB --code CODE\n' +
-                    'no aweshare installed? curl -s -X POST https://YOUR-HUB/invites/v1/redeem -H \'content-type: application/json\' -d \'{"code":"asi_..."}\')');
+            if (action !== 'revoke' && action !== 'restore') {
+                fail(`unknown offering action '${action}' — expected revoke or restore`);
             }
-            else {
-                console.error(name
-                    ? '(save these now; codes print only here — re-view later with: aweshare hub list invites --reveal. redeem: aweshare producer join --hub URL --code CODE)'
-                    : '(save these now; codes print only here — re-view later with: aweshare hub list invites --reveal. redeem: aweshare producer join --hub URL --code CODE --name NAME --email YOU@EXAMPLE.COM)');
+            checkFlags('admin offering', flags, []);
+            const alias = positional[2];
+            if (!alias)
+                fail(`offering ${action}: alias is required (ns/model)`);
+            if (positional[3])
+                fail(`unexpected argument '${positional[3]}' (see: aweshare hub admin offering -h)`);
+            if (action === 'revoke') {
+                const out = (await api('POST', `/admin/v1/offerings/block?alias=${encodeURIComponent(alias)}`));
+                console.log(`✓ ${alias} revoked (${out.offerings} protocol row(s)) — new requests get 503 OFFERING_BLOCKED`);
+                console.log(`  undo: aweshare hub admin offering restore ${alias}`);
+                return;
             }
+            const out = (await api('POST', `/admin/v1/offerings/restore?alias=${encodeURIComponent(alias)}`));
+            console.log(`✓ ${alias} restored (${out.offerings} protocol row(s)) — requests flow again`);
             return;
         }
         case 'list': {
-            // the read verbs: the invite ledger and the meter (rosters and offering
-            // health are `status`); bare `list` defaults to the ledger
-            const sub = positional[0] ?? 'invites';
+            // the read verbs, one table per noun; bare `list` defaults to the ledger
+            const sub = (positional[0] ?? 'invites');
             if (positional[1])
                 fail(`unexpected argument '${positional[1]}' (see: aweshare hub list -h)`);
-            if (sub !== 'invites' && sub !== 'usage') {
-                fail(`unknown list target '${sub}' — expected invites or usage`);
+            if (!LIST_TARGETS.includes(sub)) {
+                fail(`unknown list target '${sub}' — expected ${new Intl.ListFormat('en', { type: 'disjunction' }).format(LIST_TARGETS)}`);
             }
+            checkFlags('list', flags, LIST_FLAGS[sub]);
             const api = adminApi();
             if (sub === 'invites') {
                 const reveal = flags.get('reveal') === 'true';
@@ -588,6 +690,26 @@ async function main() {
                 }
                 return;
             }
+            if (sub === 'producers' || sub === 'consumers') {
+                const roster = (await api('GET', '/admin/v1/tokens'));
+                if (flags.get('json') === 'true') {
+                    console.log(JSON.stringify(sub === 'producers' ? roster.producers : roster.consumers));
+                    return;
+                }
+                console.log(sub === 'producers'
+                    ? renderProducers(roster.producers)
+                    : renderConsumers(roster.consumers));
+                return;
+            }
+            if (sub === 'offerings') {
+                const data = (await api('GET', '/admin/v1/offerings'));
+                if (flags.get('json') === 'true') {
+                    console.log(JSON.stringify(data.offerings, null, 2));
+                    return;
+                }
+                console.log(renderOfferings(data.offerings));
+                return;
+            }
             const params = new URLSearchParams();
             const consumer = flags.get('consumer');
             if (consumer)
@@ -607,8 +729,19 @@ async function main() {
                 const since = flags.get('since') ?? '7d';
                 if (since !== 'all')
                     parseDuration(since); // validate early with a local error
+                const sort = flags.get('sort') ?? 'time';
+                if (!USAGE_SORTS.includes(sort))
+                    fail(`--sort must be time (default), consumer, producer, model, tokens or requests, got '${sort}'`);
+                const sortKey = sort;
+                // a sort key needs its column: the alias view has no consumer, the
+                // consumer view no model — reject instead of silently not sorting
+                if (group === 'alias' && sort === 'consumer')
+                    fail('--sort consumer has no consumer column in the alias view — use --group-by consumer-alias (default) or consumer');
+                if (group === 'consumer' && sort === 'model')
+                    fail('--sort model has no model column in the consumer view — use --group-by consumer-alias (default) or alias');
                 params.set('group', group);
                 params.set('since', since);
+                params.set('sort', sortKey);
                 const qs = params.toString();
                 const rows = (await api('GET', `/admin/v1/usage/summary?${qs}`));
                 if (flags.get('json') === 'true') {
@@ -619,7 +752,7 @@ async function main() {
                     ? 'all time'
                     : `since ${fmtDate(new Date(Date.now() - parseDuration(since)))} (${since})`;
                 const grouping = group === 'alias' ? 'alias' : group === 'consumer' ? 'consumer' : 'consumer × model';
-                console.log(`usage ${window} — group: ${grouping}`);
+                console.log(`usage ${window} — group: ${grouping}, sort: ${SORT_LABELS[sortKey]}`);
                 console.log(renderUsageSummary(rows, group));
                 return;
             }
@@ -636,6 +769,8 @@ async function main() {
                 fail('--since applies to the summary, not --details');
             if (flags.get('group-by') !== undefined)
                 fail('--group-by applies to the summary, not --details');
+            if (flags.get('sort') !== undefined)
+                fail('--sort applies to the summary, not --details (the log is newest first)');
             const qs = params.toString();
             const rows = (await api('GET', `/admin/v1/usage${qs ? `?${qs}` : ''}`));
             if (flags.get('json') === 'true') {
@@ -658,10 +793,8 @@ async function main() {
             console.log(renderUsage(rows, (id) => names.get(id) ?? `#${id}`));
             return;
         }
-        case 'usage':
-            // usage became a `list` subcommand — the read surface is list + status
-            return fail("'hub usage' moved — it is 'aweshare hub list usage' now");
         case 'limits': {
+            checkFlags('limits', flags, [...LIMIT_FLAGS.map(([flag]) => flag), 'clear', 'json']);
             const name = positional[0];
             if (!name)
                 fail('consumer name is required (see: aweshare hub limits -h)');
@@ -700,7 +833,8 @@ async function main() {
             return;
         }
         case 'status': {
-            noPositionals(cmd, positional);
+            checkFlags('status', flags, []);
+            noPositionals('status', positional);
             const api = adminApi();
             const [roster, offeringsRes, usageRes, rejectionsRes] = await Promise.all([
                 api('GET', '/admin/v1/tokens'),
@@ -736,37 +870,23 @@ async function main() {
                 offerings: offeringsRes.offerings,
                 recent,
                 rejections,
-                all: flags.get('all') === 'true',
             }));
             return;
         }
-        case 'offering': {
-            const action = positional[0];
-            if (action !== 'block' && action !== 'restore') {
-                fail(`expected 'block' or 'restore' (see: aweshare hub offering -h), got '${action ?? ''}'`);
-            }
-            const alias = positional[1];
-            if (!alias)
-                fail(`offering ${action}: alias is required (ns/model)`);
-            if (positional[2])
-                fail(`unexpected argument '${positional[2]}' (see: aweshare hub offering -h)`);
-            const api = adminApi();
-            if (action === 'block') {
-                const out = (await api('POST', `/admin/v1/offerings/block?alias=${encodeURIComponent(alias)}`));
-                console.log(`✓ ${alias} blocked (${out.offerings} protocol row(s)) — new requests get 503 OFFERING_BLOCKED`);
-                console.log(`  undo: aweshare hub offering restore ${alias}`);
-                return;
-            }
-            const out = (await api('POST', `/admin/v1/offerings/restore?alias=${encodeURIComponent(alias)}`));
-            console.log(`✓ ${alias} restored (${out.offerings} protocol row(s)) — requests flow again`);
-            return;
-        }
+        case 'invite':
+            // invite mint/revoke/restore moved under the admin gate
+            return fail("'hub invite' moved — it is 'aweshare hub admin invite mint|revoke|restore' now");
+        case 'offering':
+            return fail("'hub offering' moved — block/restore live under 'aweshare hub admin offering revoke|restore' now");
+        case 'usage':
+            // usage became a `list` subcommand — the read surface is list + status
+            return fail("'hub usage' moved — it is 'aweshare hub list usage' now");
         case 'revoke':
-            // revoke/restore became `invite` subcommands — the invite is the
-            // lifecycle handle, same shape as `offering block|restore`
-            return fail("'hub revoke --id N' moved — it is 'aweshare hub invite revoke N' now");
+            // revoke/restore became `admin invite` subcommands — the invite is the
+            // lifecycle handle, same shape as `admin offering revoke|restore`
+            return fail("'hub revoke --id N' moved — it is 'aweshare hub admin invite revoke N' now");
         case 'restore':
-            return fail("'hub restore --id N' moved — it is 'aweshare hub invite restore N' now");
+            return fail("'hub restore --id N' moved — it is 'aweshare hub admin invite restore N' now");
         default:
             fail(`unknown command: ${cmd}\n\n${USAGE}`);
     }