aweshare 0.4.7 → 0.4.9

package/README.ai.md

@@ -0,0 +1,346 @@
+# aweshare Bootstrap Protocol
+
+This document is for AI coding agents. Help the user install and configure `aweshare`, a local-first AI capability relay: producers share local Ollama/vLLM or authorized OpenAI/Anthropic backends through a self-hosted hub; consumers point standard OpenAI/Anthropic SDKs at the hub and call models by `namespace/alias`.
+
+## Long-Running Services and Secrets
+
+Unlike ordinary CLIs, aweshare's two core processes are **long-running services**:
+
+- Never launch them from this agent — not `aweshare hub serve`, not `aweshare producer start` (foreground blocks the session; even `--background` starts a shared service, which is the user's call). The same applies to deploying the hub as a container (`docker run` / `docker compose up` of `ghcr.io/wehuman01/aweshare`). Give the user the commands and let them run them in their own terminal.
+- Upstream API keys live only in `~/.aweshare/secrets.json` (0600) on the producer's machine. Never print them, never echo them into logs or chat. `aweshare producer config show` redacts them.
+- Some tokens are printed exactly once (the hub admin token from `hub init`, an `asc_` consumer token from `consumer join`, invite codes from `hub invite`). Prefer having the user run those commands so the secret lands in their terminal; if you must run one, tell the user to save the value immediately.
+- Before helping share an OpenAI/Anthropic backend, state the compliance boundary: relaying a personal-subscription key (coding plans included) to third parties likely violates the upstream's terms; self-hosted open models have no such issue. When in doubt, don't share.
+
+## Language Behavior
+
+- Reply in the user's language when possible.
+- If the user asks in Chinese, continue in Chinese.
+- If the user asks in English, continue in English.
+
+## Step 0: Identify the user's role
+
+aweshare has three roles with different setups. Ask which one applies (more than one is possible):
+
+- **Hub operator** — runs the public hub on an always-on server; mints invite codes.
+- **Producer** — shares models from their own machine through a hub.
+- **Consumer** — calls shared models with a standard SDK from any machine.
+
+Then follow Steps 1–2 (identical for everyone) and the matching path in Step 4.
+
+## Step 1: Install aweshare CLI
+
+### Prerequisites
+
+- Node >= 22 (`node --version`)
+
+If Node.js is missing, tell the user to install it from https://nodejs.org/.
+
+### Steps
+
+```bash
+npm install -g aweshare
+aweshare -v
+```
+
+Expected output: a version number (e.g. `0.4.8`).
+
+---
+
+## Step 2: Install the aweshare skill
+
+Install the skill so the agent can operate aweshare in this and future sessions. Choose one of the following options.
+
+### Option A: Via aweskill (recommended if aweskill is available)
+
+Use this option if the user already has aweskill installed, or is willing to install it. This gives full skill management — install, update, projection, backup.
+
+#### Prerequisites
+
+- Node.js >= 20 (`node --version`) — required by aweskill
+- npm available (`npm --version`)
+
+#### Steps
+
+##### A1. Install aweskill (if not already installed)
+
+```bash
+npm install -g aweskill
+```
+
+##### A2. Initialize the aweskill central store (if not already done)
+
+```bash
+aweskill store init
+```
+
+##### A3. Install the aweshare skill from GitHub
+
+```bash
+aweskill install wehuman01/aweshare
+```
+
+##### A4. Identify the current agent
+
+```bash
+aweskill agent supported
+```
+
+Look for lines marked with `✓`. Common agent ids: `claude-code`, `cursor`, `codex`, `gemini-cli`, `windsurf`, `opencode`, `qwen-code`.
+
+If you cannot determine the agent id, ask the user.
+
+##### A5. Project the aweshare skill to this agent
+
+```bash
+aweskill agent add skill aweshare --global --agent <agent-id>
+```
+
+##### A6. Verify
+
+```bash
+aweskill agent list --global --agent <agent-id>
+```
+
+Expected: `aweshare` shows as `linked`.
+
+---
+
+### Option B: Direct copy (no aweskill needed)
+
+Use this option if the user does not have aweskill. This copies the SKILL.md file directly into the agent's skill directory.
+
+#### Prerequisites
+
+- `curl` or `wget` available
+
+#### Steps
+
+##### B1. Identify the current agent's skill directory
+
+Determine which agent is running and its global skill directory:
+
+| Agent | Skill directory |
+|---|---|
+| Claude Code | `~/.claude/skills/aweshare/` |
+| Codex | `~/.codex/skills/aweshare/` |
+| Cursor | `.cursor/skills/aweshare/` (project-level) |
+| Gemini CLI | `~/.gemini/skills/aweshare/` |
+| Windsurf | `~/.windsurf/skills/aweshare/` |
+| OpenCode | `~/.opencode/skills/aweshare/` |
+| Qwen Code | `~/.qwen/skills/aweshare/` |
+
+If the agent is not in this list, ask the user where to place the skill file.
+
+##### B2. Download and place SKILL.md
+
+```bash
+mkdir -p <skill-directory>
+curl -fsSL https://raw.githubusercontent.com/wehuman01/aweshare/main/resources/skills/aweshare/SKILL.md -o <skill-directory>/SKILL.md
+```
+
+Replace `<skill-directory>` with the path from step B1.
+
+---
+
+## Step 3: Detect the current setup (read-only, safe to run)
+
+```bash
+aweshare producer config path       # where config.toml / secrets.json live
+aweshare producer config show       # config with token + secrets redacted
+aweshare producer doctor --status   # background producer state + recent log, instant, no network
+```
+
+Report the findings to the user:
+
+- No config at `~/.aweshare/config.toml` — fresh machine, continue with Step 4.
+- Config present — a producer is (or was) set up here; `doctor --status` tells whether a background instance is running.
+- Full `aweshare producer doctor` (without `--status`) adds network probes of the configured backends and the hub plus the recent log. Diagnostic traffic only — run it freely after setup, fix the first FAIL, re-run until green.
+
+---
+
+## Step 4: Role-specific setup
+
+Interactive or service-starting commands stay in the user's terminal. Everything else you can do.
+
+### Producer — shares models from this machine
+
+1. Join the hub (either works):
+   - The user redeems their invite code — you may run it, it is non-interactive and writes `~/.aweshare/config.toml` + empty `secrets.json`:
+     ```bash
+     aweshare producer join --hub https://hub.example.com --code asi_...
+     ```
+   - Or the operator handed over a token directly:
+     ```bash
+     aweshare producer init --hub https://hub.example.com --token asp_...
+     ```
+2. Edit `config.toml` yourself: set `hubUrl`/`token`, define `[[backends]]` (protocol + baseUrl convention: `openai` baseUrl includes `/v1`; `anthropic` excludes `/v1`; `responses` includes the version path) and `[[offerings]]` (alias namespace = producer name, one upstream model each).
+3. Upstream keys go into `secrets.json` under the backend's `keyRef` name. **Do not ask the user to paste keys into chat** — ask them to edit `secrets.json` themselves, then continue.
+4. Verify:
+   ```bash
+   aweshare producer doctor      # instance, config, backend probes, hub — fix the first FAIL
+   ```
+5. Tell the user (do not run):
+   > Run `aweshare producer start` in your terminal — or `aweshare producer start --background` to detach it (logs to `~/.aweshare/producer.log`). Stopping later: `aweshare producer stop`.
+
+After config edits on a running producer, `aweshare producer reload` applies the new catalog without a restart (both processes also stat-poll their config every 2s and hot-apply valid edits; `hubUrl`/`token` still need a restart).
+
+### Consumer — calls shared models
+
+1. Have the user redeem their invite in their own terminal — it prints the `asc_` token exactly once:
+   ```bash
+   aweshare consumer join --hub https://hub.example.com --code asi_...
+   ```
+   (No aweshare installed? One curl works: `POST https://hub.example.com/invites/v1/redeem` with `{"code":"asi_..."}`.)
+2. Configure the tool with the printed env vars:
+   ```bash
+   # Claude Code / Anthropic SDK — the key is the asc_ consumer key, NOT any upstream x-api-key
+   export ANTHROPIC_BASE_URL=https://hub.example.com
+   export ANTHROPIC_AUTH_TOKEN=asc_...
+   claude --model peng/sonnet
+
+   # OpenAI SDK / Codex
+   export OPENAI_BASE_URL=https://hub.example.com/v1
+   export OPENAI_API_KEY=asc_...
+   ```
+3. Discovery (read-only, safe to run once you have the token):
+   ```bash
+   aweshare consumer list --hub https://hub.example.com --token asc_...
+   ```
+   Every producer, alias, protocol, status, caps, live occupancy and remaining daily tokens.
+4. A first smoke-test request (`curl ... /v1/chat/completions` with `"ping"`) is a real model call — only run it when the user asks.
+
+Remind the consumer: prompts and responses transit the hub in plaintext — only use a hub they trust. If Claude Code ignores env config, a stale OAuth login is overriding it — switch with `/login`.
+
+### Hub operator — runs the hub on a server
+
+1. Choose npm or Docker (Docker is the better default on a VPS). Both `hub serve` and container deployment run in the **user's** terminal:
+   ```bash
+   # npm
+   npm install -g aweshare
+   aweshare hub init        # data in ~/.aweshare-hub; prints the admin token ONCE — save it
+   aweshare hub serve       # listens on :8787; put Caddy/nginx TLS in front
+
+   # docker
+   docker run -d --name aweshare-hub --restart unless-stopped \
+     -p 127.0.0.1:8787:8787 -v "$PWD/data:/data" ghcr.io/wehuman01/aweshare:latest
+   docker exec aweshare-hub aweshare hub init
+   ```
+2. After `hub init` (wherever it ran), mint invites — you may run these:
+   ```bash
+   aweshare hub invite --name peng                       # bound producer code → asi_...
+   aweshare hub invite --count 10                        # unbound batch, name+email at redeem
+   aweshare hub invite --role consumer --name alice      # bound consumer code → asi_...
+   ```
+   Consumers redeem codes themselves (`aweshare consumer join`); producers via `aweshare producer join`.
+3. Administering a remote hub: run admin commands on the server (`ssh` + CLI, or `docker exec aweshare-hub aweshare hub ...`), or locally with `AWESHARE_HUB_URL=https://<hub-host>` plus the admin-token file in a local data dir — otherwise they fail with "no admin token" / connection refused.
+4. Guardrails you can tune on request: per-consumer `aweshare hub limits NAME [--rps N] [--tpm N] [--max-total-tokens N] ...`, suspension `aweshare hub revoke --id N` / `restore --id N` (reversible, invite-keyed).
+5. Security notes for the operator: keep :8787 off the public internet behind TLS; a redeemed consumer key can call **every** offering on the hub; tokens/codes stored plaintext-recoverable (`hub list --reveal` / `--token`) means a data-dir leak exposes identities — guard it.
+
+---
+
+## Step 5: Verify and tune (safe to run)
+
+After setup:
+
+```bash
+aweshare producer doctor            # full diagnosis, ordered to find the first failing link
+aweshare producer list              # registered offerings, live status, caps, occupancy, config drift
+aweshare hub list producers         # roster + last seen (admin context only)
+aweshare hub usage                  # who used how much, aggregated per consumer × model
+aweshare self-update --check        # installed vs npm latest
+```
+
+On the user's request you may also:
+
+```bash
+aweshare hub limits alice --tpm 60000 --max-total-tokens 5000000   # cap a consumer
+aweshare hub usage --details --since 24h                           # per-request log
+aweshare producer reload                                           # apply config edits without restart
+```
+
+## Useful commands
+
+Read-only commands (safe to run in agent):
+
+```bash
+aweshare -v                          # installed version
+aweshare producer config path        # config/secrets locations
+aweshare producer config show        # config, secrets redacted
+aweshare producer doctor [--status]  # diagnosis (with --status: instant, no network)
+aweshare producer list [--json]      # this producer's offerings + drift
+aweshare producer usage [...]        # who used this producer's models
+aweshare consumer list --hub URL --token asc_...   # hub catalog view
+aweshare hub list [invites|producers|consumers] [--json]   # rosters / invite lifecycle
+aweshare hub limits NAME             # bare call views current overrides
+aweshare hub usage [--details] [--group-by consumer|alias] [--since 7d]
+aweshare self-update --check         # versions only
+```
+
+Local changes (run on user request):
+
+```bash
+aweshare producer init [--hub URL] [--token asp_...]   # write templates; no-op if they exist
+aweshare producer join --hub URL --code asi_...        # redeem a producer invite into the config
+aweshare producer config edit                          # open config.toml in $EDITOR
+aweshare producer reload                               # re-read config + re-register offerings
+aweshare hub init                                      # create data dir + admin token (printed once!)
+aweshare hub invite [--role producer|consumer] ...     # mint one-time codes (printed once)
+aweshare hub limits NAME [--rps N] [--burst N] [--max-concurrent N] [--tpm N] [--max-total-tokens N] [--clear]
+aweshare hub revoke --id N / restore --id N            # reversible suspension, by invite handle
+```
+
+User-only commands (long-running, TTY-confirming, or one-time-secret-printing):
+
+```bash
+aweshare producer start [--background] / stop          # the relay service
+aweshare hub serve                                     # the hub
+aweshare consumer join --hub URL --code asi_...        # prints the asc_ token once
+aweshare self-update                                   # y/n confirm; non-interactive: npm install -g aweshare
+docker run / docker compose up                         # hub deployment
+```
+
+## Safety Rules
+
+- Never start or stop the long-running services (`hub serve`, `producer start`/`stop`, hub containers) inside the agent — deployment is the user's call. Inspect a detached producer with `producer doctor --status`.
+- Never read or print `secrets.json` values; use `producer config show` (redacted) when showing config. Never ask the user to paste an upstream API key into chat — point them at the file instead.
+- Commands that print a secret exactly once (`hub init`, `consumer join`, `hub invite`) are best run by the user; if you run one, flag the value as save-now.
+- State the trust boundary before anyone joins a hub: consumer traffic transits the hub in plaintext; a redeemed consumer key can call every offering. State the compliance boundary before anyone shares a key: personal-subscription keys forwarded to third parties likely violate upstream terms — the producer bears the consequences.
+- Read state through the CLI (`config show`, `list`, `doctor`); do not hand-edit SQLite or pidfiles. Config TOML edits are fine — they hot-reload.
+- Offering aliases must be `namespace/name`, lowercase, namespace matching the producer token's name. One offering = one upstream model; the old `maxConcurrency` key fails validation with a rename hint (use `maxConcurrencyPerUser`).
+- If any command fails, report the exact command and error message (codes like `403 HUB_FULL`, `409 INVITE_ROLE_MISMATCH`, `401 TOKEN_REVOKED` carry meaning — pass them through). Do not silently retry.
+
+## Final Step
+
+After setup, tell the user to invoke skills (`/` in Claude Code, `$` in Codex, or the equivalent in other agents) and check if `aweshare` appears in the list. If it does, the skill is ready to use immediately. If not, the user should restart the agent.
+
+> aweshare is installed and configured. Invoke skills (type `/` or `$` depending on your agent) and look for `aweshare` — if it appears, you're good to go. If not, restart the agent. Then you can ask me things like:
+>
+> - "Share my local Ollama qwen2.5:7b as peng/qwen2.5.7b."
+> - "Why is my producer offline?" (I'll run `producer doctor` and fix the first FAIL.)
+> - "Cap alice at 60k tokens per minute."
+> - "Who used my models this week?"
+
+If the user is speaking Chinese, use this version instead:
+
+> aweshare 已安装并配置完成。请调用 skills（输入 `/` 或 `$`，取决于你的 agent），看看列表中是否出现了 `aweshare`。如果出现了，说明已就绪可以直接使用。如果没有，请重启 agent 后再试。然后你可以继续问我，例如：
+>
+> - “把我本地的 Ollama qwen2.5:7b 以 peng/qwen2.5.7b 共享出去。”
+> - “我的 producer 为什么掉线了？”（我会跑 `producer doctor` 并修复第一个 FAIL。）
+> - “给 alice 限流到每分钟 6 万 token。”
+> - “这周谁用了我的模型？”
+
+---
+
+## Next Steps
+
+### Community hub — no server of your own
+
+The project's developer runs an invite-based community hub at https://aweshare.wehuman.top. If the user wants to share or consume without operating a hub, guide them through the tutorial: https://github.com/wehuman01/aweshare/blob/main/docs/community-hub/README.md — requesting an invite at peng@wehuman.top, joining as producer or consumer, and the first connection. State the trust rule before they join: their traffic transits that hub in plaintext.
+
+### awewarm — keep shared subscription windows warm
+
+If the user shares a coding-plan-backed endpoint through aweshare, pair it with [awewarm](https://github.com/wehuman01/awewarm): it schedules one minimal request per window so the underlying subscription quota never cools down mid-day. Its agent doc lives at https://github.com/wehuman01/awewarm/blob/main/README.ai.md.
+
+### aweswitch — agent profile switching
+
+Consumers who juggle several providers can use [aweswitch](https://github.com/Webioinfo01/aweswitch) to switch Claude Code / Codex / OpenCode profiles; pointing one of those profiles at an aweshare hub is just another provider entry.

package/README.md

@@ -14,7 +14,7 @@
     <a href="https://ko-fi.com/mugpeng"><img src="https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-FF5E5B?style=flat-square&logo=ko-fi&logoColor=white" alt="Ko-fi"></a>
   </p>
   <p>
-     <a href="https://github.com/wehuman01/aweshare-source/releases"><img src="https://img.shields.io/badge/version-0.4.7-7C3AED?style=flat-square" alt="Version"></a>
+     <a href="https://github.com/wehuman01/aweshare-source/releases"><img src="https://img.shields.io/badge/version-0.4.9-7C3AED?style=flat-square" alt="Version"></a>
     <a href="https://github.com/wehuman01/aweshare"><img src="https://img.shields.io/badge/node-%E2%89%A522-0EA5E9?style=flat-square" alt="Node"></a>
     <a href="https://github.com/wehuman01/aweshare/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-proprietary-E34F26?style=flat-square" alt="License"></a>
     <a href="https://www.npmjs.com/package/aweshare"><img src="https://img.shields.io/badge/npm-aweshare-7C3AED?style=flat-square" alt="npm package"></a>
@@ -69,7 +69,19 @@ Consumer (standard SDK, zero changes)         Producer side
 
 Published as [`aweshare`](https://www.npmjs.com/package/aweshare) on npm (requires Node ≥ 22) and as a Docker image (`ghcr.io/wehuman01/aweshare`). No clone needed.
 
-### 1. Start the hub (operator, one VPS)
+### Let an AI agent set it up
+
+Working in Claude Code, Codex, or another coding agent? Tell it:
+
+```text
+Read https://github.com/wehuman01/aweshare/blob/main/README.ai.md and follow it to install and configure aweshare.
+```
+
+The agent installs the CLI and the skill, asks whether you are a hub operator, producer, or consumer, and does everything that is safe to automate — editing configs, minting invites, running `producer doctor`. Steps that print one-time tokens (`hub init`, `consumer join`) or start long-running services (`hub serve`, `producer start`) stay in your terminal. After setup you can ask things like "share my local Ollama model as peng/qwen2.5.7b", "why is my producer offline?", or "who used my models this week?".
+
+### Manual setup
+
+#### 1. Start the hub (operator, one VPS)
 
 **npm** (simplest):
 
@@ -79,7 +91,7 @@ aweshare hub init        # data in ~/.aweshare-hub; prints the admin token — s
 aweshare hub serve       # listens on :8787 (put Caddy/nginx TLS in front)
 ```
 
-The hub can also host models itself — no producer machine needed. Add `[[backends]]`/`[[offerings]]` sections to `~/.aweshare-hub/config.toml` (same format as a producer's config, alias namespace `hub/…`), put the upstream keys in `~/.aweshare-hub/secrets.json`, and run:
+The hub can also host models itself — no producer machine needed. Add `[[backends]]`/`[[offerings]]` sections to `~/.aweshare-hub/config.produce.toml` (same format as a producer's config, alias namespace `hub/…`), put the upstream keys in `~/.aweshare-hub/secrets.json`, and run:
 
 ```bash
 aweshare hub produce    # serve + the hub's own models; consumers dial hub/<name> like any offering
@@ -132,7 +144,7 @@ The producer's `name` becomes their alias namespace (the `peng/` in `peng/gpt-4o
 
 The operator owns admission: one-time invite codes for both roles, the only admission path (every identity carries its invite handle for its whole lifecycle). A redeemed consumer key may call **every** offering on the hub — if you let someone in, they can use what is shared. Guardrails: per-consumer `hub limits` (rate, concurrency, token budgets), per-offering caps (`maxConcurrentUsers`, `dailyTokens`) and `hub revoke` suspension, all enforced by the hub.
 
-### 2. Producer first run (in this order)
+#### 2. Producer first run (in this order)
 
 ```bash
 npm install -g aweshare   # ⓪ once, on the producer machine (Node ≥ 22)
@@ -153,7 +165,7 @@ aweshare producer start            # foreground; add --background to detach it
 #    and stopped with 'aweshare producer stop'
 ```
 
-### 3. Consumer first run (in this order)
+#### 3. Consumer first run (in this order)
 
 ```bash
 # ⓪ redeem your invite code (skip if the operator handed you an asc_ key directly)
@@ -278,11 +290,11 @@ Honest limits: token-based caps count what upstreams report — Ollama streams r
 | `GET /v1/catalog` | every offering on the hub — producer, alias, protocol, status, the per-offering caps, live in-flight occupancy (`activeUsers`/`activeRequests`) and today's used/remaining tokens (discovery view for `aweshare consumer list`) |
 | `GET /healthz` | liveness |
 | `GET /admin/v1/offerings` | registered offerings with live status, caps, in-flight occupancy and today's used tokens — admin sees everything, a producer token only its own slice (`aweshare producer list`) |
-| `/admin/v1/*` | token/limit/usage management (admin or producer token) · usage: `GET /admin/v1/usage` (newest-first log) and `GET /admin/v1/usage/summary` (`group=consumer\|alias`, `since=30m\|12h\|7d`, `consumer`/`producer`/`alias` filters; every role sees its own slice) · consumer limit overrides: `GET`/`PUT`/`DELETE /admin/v1/consumers/{name}/limits` (admin only) |
+| `/admin/v1/*` | token/limit/usage management (admin or producer token) · usage: `GET /admin/v1/usage` (newest-first log) and `GET /admin/v1/usage/summary` (`group=consumer-alias\|consumer\|alias`, `since=30m\|12h\|7d\|all`, default 7d, `consumer`/`producer`/`alias` filters; every role sees its own slice) · consumer limit overrides: `GET`/`PUT`/`DELETE /admin/v1/consumers/{name}/limits` (admin only) |
 
 Error semantics: `401` invalid key · `401 TOKEN_REVOKED` suspended token (ask the operator to restore it) · `403 HUB_FULL` producer capacity reached · `404` unknown alias · `400 PROTOCOL_MISMATCH` protocol/alias mismatch · `429` rate limit, TPM or producer concurrency cap (`PRODUCER_MAX_USERS` = distinct-consumer cap; `QUOTA_EXCEEDED` = lifetime or daily token budget hit) · `502` upstream/tunnel failure (upstream 4xx/5xx passes through verbatim) · `503` producer offline / backend degraded · `504` timeout. Errors carry `{error:{code,message,requestId}}`; the requestId spans both sides' logs.
 
-Usage metering: one row per request (alias, real model, status, duration, byte counts, best-effort token counts), **zero content stored**. The log is queried with `aweshare hub usage` or `GET /admin/v1/usage` (admin sees everything, producers and consumers their own slice; rows carry the consumer/producer names). For "who used how much", `aweshare hub usage summary --since 7d` (or `GET /admin/v1/usage/summary`) aggregates server-side on the hub's SQLite: one row per producer × consumer (`--group-by consumer`, the default) or per alias (`--group-by alias`) with request/error counts, best-effort token totals, an explicit unknown-token count (streaming backends that report no counts) and mean duration — busiest first. A producer sees its own slice the same way with `aweshare producer usage [summary]` on its own machine.
+Usage metering: one row per request (alias, real model, status, duration, byte counts, best-effort token counts), **zero content stored**. `aweshare hub usage` (and `aweshare producer usage` on a producer's machine, scoped to its own models) answers "who used how much" by default: server-side aggregation on the hub's SQLite, one row per consumer × model — a person's rows stay together, busiest person and busiest model first — with request/error counts, best-effort token totals, an explicit unknown-token count (streaming backends that report no counts) and mean duration. The window defaults to 7 days and is printed with the table (`--since 30m\|12h\|7d\|…\|all`); `--group-by consumer` rolls up to per-person totals, `--group-by alias` to per-model totals. `--details` switches to the per-request log (`GET /admin/v1/usage`; admin sees everything, producers and consumers their own slice, rows carry the consumer/producer names).
 
 ## Command reference
 
@@ -294,11 +306,11 @@ Both sides at a glance — details in the sections above.
 |---|---|
 | `aweshare hub init` | create data dir + admin token (printed once) |
 | `aweshare hub serve [--host H] [--port N]` | run the hub |
-| `aweshare hub produce [--host H] [--port N]` | run the hub with its own models attached — same as `serve`; the `[[backends]]`/`[[offerings]]` sections of the hub's config.toml become `hub/…` offerings served in-process (keys in the data dir's secrets.json; edits hot-reload) |
+| `aweshare hub produce [--host H] [--port N]` | run the hub with its own models attached — same as `serve`; the `[[backends]]`/`[[offerings]]` sections of `config.produce.toml` become `hub/…` offerings served in-process (keys in the data dir's secrets.json; edits hot-reload) |
 | `aweshare hub invite [--role producer\|consumer] [--name NAME] [--count N] [--expires-in D]` | mint one-time invite codes (`asi_…`, printed once, expire after 7 d by default; re-view with `list --reveal`); producer codes: bound (`--name`) or unbound (name + email at redeem, `--count` batches); consumer codes: always bound to one name |
 | `aweshare hub list [invites\|producers\|consumers] [--reveal] [--token] [--json]` | read hub state: invite lifecycle (ROLE + who redeemed, `--reveal` codes, `--token` the minted tokens), or the producer/consumer rosters with status and last seen |
 | `aweshare hub limits NAME [--rps N] [--burst N] [--max-concurrent N] [--tpm N] [--max-total-tokens N] [--clear] [--json]` | show, merge or clear one consumer's limit overrides (unset keys keep the hub-wide defaults) |
-| `aweshare hub usage [summary] [--consumer NAME] [--producer NAME] [--alias ns/model] [--limit N] [--group-by consumer\|alias] [--since 7d] [--json]` | request log (default): newest first, one row per request, zero content stored, says which consumer made each call · `summary`: server-side aggregate per producer × consumer (default) or per alias — requests, errors, rate, best-effort token totals, unknown-token count, mean duration; `--since` (30m, 12h, 7d, …) required |
+| `aweshare hub usage [--details] [--consumer NAME] [--producer NAME] [--alias ns/model] [--group-by consumer-alias\|consumer\|alias] [--since 7d\|all] [--limit N] [--json]` | who used how much (default): aggregate per consumer × model, a person's rows together, busiest first — requests, errors, rate, best-effort token totals, unknown-token count, mean duration; window defaults to 7d and is printed with the table · `--details`: per-request log, newest first, zero content stored, each row naming its consumer |
 | `aweshare hub revoke --id N` · `aweshare hub restore --id N` | kill an invite / undo — a redeemed code suspends the producer it minted, restore revives both |
 
 Token issuance runs through invites (both roles). `limits` and `usage` are thin wrappers over the admin REST API (`/admin/v1/*`, see Endpoints and errors) — curl works too.
@@ -314,7 +326,7 @@ Token issuance runs through invites (both roles). `limits` and `usage` are thin
 | `aweshare producer config path` · `config show` · `config edit` | locate / inspect (secrets redacted) / edit the config |
 | `aweshare producer doctor [--status]` | diagnose end to end: background instance, config, backend probes, hub (including how many of your offerings are registered), recent log (`--status` skips the network probes for an instant answer) |
 | `aweshare producer list [--json]` | what this producer has registered on the hub — alias, protocol, live status, caps, live occupancy (`IN USE`, distinct consumers in flight right now), today's token use — plus the local background instance state and drift against config.toml (hubUrl/token come from config.toml) |
-| `aweshare producer usage [summary] [--consumer NAME] [--alias ns/model] [--limit N] [--group-by consumer\|alias] [--since 7d] [--json]` | who used this producer's models (the producer token scopes the hub's metering to its own slice): request log (default), newest first with the consumer named per call, or `summary` aggregated per consumer (default) or per alias — requests, errors, rate, best-effort token totals, unknown-token count, mean duration; `--since` required |
+| `aweshare producer usage [--details] [--consumer NAME] [--alias ns/model] [--group-by consumer-alias\|consumer\|alias] [--since 7d\|all] [--limit N] [--json]` | who used this producer's models (the producer token scopes the hub's metering to its own slice): aggregate per consumer × model by default — a person's rows together, busiest first, window defaults to 7d · `--details`: per-request log, newest first, each row naming its consumer |
 | `aweshare producer start [--background]` | connect and relay (long-running; `--background` detaches it — logs to `~/.aweshare/producer.log`, pid to `producer.pid`) |
 | `aweshare producer reload` | signal the background producer (SIGHUP) to re-read `config.toml` + `secrets.json` and re-register its offerings on the open tunnel — no disconnect; a broken config keeps the previous values |
 | `aweshare producer stop` | stop the background producer (SIGTERM, SIGKILL after 10s) and clean up its pidfile |
@@ -336,7 +348,7 @@ The hub reads `config.toml` from its data dir (`~/.aweshare-hub/config.toml`; Do
 
 **Hot reload:** every tunable in the table except host/port applies live on `SIGHUP` (`kill -HUP <pid>`; Docker: `docker kill -s HUP aweshare-hub`) — the new file is validated first, and a broken edit is logged while the previous values keep serving. Env vars are fixed at process start, so keys pinned by `AWESHARE_*` ignore the reloaded file (same precedence as startup); host/port need a restart. Producer-side offerings and caps reload via `aweshare producer reload`.
 
-**Hub-hosted models (`hub produce`):** the same config.toml may carry `[[backends]]` and `[[offerings]]` sections (producer format; alias namespace `hub/…` — bare names are auto-prefixed) with upstream keys in `secrets.json` next to it (chmod 600). Those offerings appear in the catalog under producer `hub` and are served by the hub process directly — no tunnel, and they never count against `AWESHARE_MAX_PRODUCERS`. Caps (`maxConcurrencyPerUser`, `maxConcurrentUsers`, `dailyTokens`), usage metering and consumer limits apply exactly as for remote producers. The built-in `hub` producer is not an identity (no token, no invite, cannot be revoked); it appears in `hub list producers` — status `built-in` — only while it carries offerings. Catalog and key edits hot-reload like the tunables; a broken catalog keeps the previous one and is logged.
+**Hub-hosted models (`hub produce`):** `config.produce.toml` carries `[[backends]]` and `[[offerings]]` sections (producer format; alias namespace `hub/…` — bare names are auto-prefixed) with upstream keys in `secrets.json` next to it (chmod 600). `config.toml` remains exclusively for Hub runtime settings. Those offerings appear in the catalog under producer `hub` and are served by the hub process directly — no tunnel, and they never count against `AWESHARE_MAX_PRODUCERS`. Caps (`maxConcurrencyPerUser`, `maxConcurrentUsers`, `dailyTokens`), usage metering and consumer limits apply exactly as for remote producers. The built-in `hub` producer is not an identity (no token, no invite, cannot be revoked); it appears in `hub list producers` — status `built-in` — only while it carries offerings. Catalog and key edits hot-reload like the tunables; a broken catalog keeps the previous one and is logged.
 
 | Env var | Default | Purpose |
 |---|---|---|

package/apps/agent/dist/cli.js

@@ -31,7 +31,7 @@ Commands:
   doctor  Diagnose: instance, config, backends, hub (--status for the quick view).
   list    Show what this producer has registered on the hub.
   status  Summarize this producer's config, process and registered models.
-  usage   Who used this producer's models: request log or aggregated summary.
+  usage   Who used this producer's models: summary (default) or --details.
   start   Connect, register offerings, relay (--background to daemonize).
   reload  Force the background producer to re-read its config now.
   stop    Stop the background producer and clean up its pidfile.`;
@@ -94,25 +94,25 @@ Options:
 
 Options:
   -h, --help  Show this message and exit.`,
-    usage: `Usage: aweshare producer usage [summary] [OPTIONS]
+    usage: `Usage: aweshare producer usage [OPTIONS]
 
-  Detail (default): recent requests against this producer's models, newest
-  first — one row per request, zero content stored. The producer token scopes
-  everything to this producer's slice; rows say which consumer made each call.
+  Who used this producer's models: aggregated on the hub, one row per
+  consumer × model (default) — a person's rows stay together, busiest person
+  and busiest model first. The producer token scopes everything to this
+  producer's slice; narrow further with --consumer/--alias.
 
-  Summary: consumption aggregated on the hub — one row per consumer (default)
-  or per alias, busiest first, with request/error counts, best-effort token
-  totals and mean duration. --since is required there: aggregates answer
-  "how much", not "when".
+  --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:
-  --consumer NAME  Only rows for this consumer.
-  --alias ALIAS    Only rows for this alias (one of your offerings).
-  --limit N        Detail only: rows to show, 1..1000 (default 100).
-  --group-by KEY   Summary only: consumer (default) or alias.
-  --since DUR      Summary only: window, like 30m, 12h or 7d (required).
-  --json           Print the raw API response instead of a table.
-  -h, --help       Show this message and exit.`,
+  --details         Show the per-request log instead of the summary.
+  --consumer NAME   Only rows for this consumer.
+  --alias ALIAS     Only rows for this alias (one of your offerings).
+  --group-by KEY    consumer × model (default), consumer or alias.
+  --since DUR       Window: 30m, 12h, 7d (default), 30d… or all.
+  --limit N         --details only: rows to show, 1..1000 (default 100).
+  --json            Print the raw API response instead of a table.
+  -h, --help        Show this message and exit.`,
     start: `Usage: aweshare producer start [OPTIONS]
 
   Connect to the hub, register offerings, relay requests.
@@ -153,7 +153,7 @@ const COMMAND_FLAGS = {
     doctor: ['status'],
     list: ['json'],
     status: [],
-    usage: ['consumer', 'alias', 'limit', 'group-by', 'since', 'json'],
+    usage: ['consumer', 'alias', 'limit', 'group-by', 'since', 'details', 'json'],
     start: ['background'],
     reload: [],
 };
@@ -374,30 +374,37 @@ async function runStatus(dir) {
 /** Usage views: detail log (default) or `summary` aggregate. The producer
  * token scopes both to this producer's models on the hub side. */
 async function runUsage(dir, flags, positional) {
-    const sub = positional[0];
-    if (positional[1])
-        fail(`unexpected argument '${positional[1]}' (see: aweshare producer usage -h)`);
-    if (sub !== undefined && sub !== 'summary')
-        fail(`unknown usage view '${sub}' — expected 'summary' or nothing (see: aweshare producer usage -h)`);
+    if (positional[0])
+        fail(`unexpected argument '${positional[0]}' — summaries are the default view now; the request log is --details (see: aweshare producer usage -h)`);
     const { config } = loadAgentConfig(dir);
     const consumer = flags.get('consumer');
     const alias = flags.get('alias');
-    if (sub === 'summary') {
-        const since = flags.get('since');
-        if (!since)
-            fail('--since is required for summaries (e.g. --since 7d) — aggregates need an explicit window');
+    if (flags.get('details') !== 'true') {
         if (flags.get('limit') !== undefined)
-            fail('--limit applies to the detail view, not summaries');
-        const group = flags.get('group-by') ?? 'consumer';
+            fail('--limit applies to --details, not the summary');
+        const group = flags.get('group-by') ?? 'consumer-alias';
+        if (group !== 'consumer-alias' && group !== 'consumer' && group !== 'alias')
+            fail(`--group-by must be 'consumer', 'alias' or 'consumer-alias' (default), got '${group}'`);
+        const since = flags.get('since') ?? '7d';
+        if (since !== 'all' && !/^\d+[smhd]$/.test(since))
+            fail(`--since must look like 30m, 12h, 7d or all, got '${since}'`);
+        const usageGroup = group;
         const rows = await fetchUsageSummary(config.hubUrl, config.token, {
-            group: group === 'alias' ? 'alias' : 'consumer',
+            group: usageGroup,
             since,
             consumer,
             alias,
         });
-        console.log(flags.get('json') === 'true'
-            ? JSON.stringify(rows, null, 2)
-            : renderUsageSummary(rows, group === 'alias' ? 'alias' : 'consumer'));
+        if (flags.get('json') === 'true') {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        const window = since === 'all'
+            ? 'all time'
+            : `since ${new Date(Date.now() - sinceMs(since)).toISOString().slice(0, 10)} (${since})`;
+        const grouping = group === 'alias' ? 'alias' : group === 'consumer' ? 'consumer' : 'consumer × model';
+        console.log(`usage ${window} — group: ${grouping}`);
+        console.log(renderUsageSummary(rows, usageGroup));
         return;
     }
     let limit;
@@ -419,6 +426,12 @@ async function runUsage(dir, flags, positional) {
         names.set(r.consumer_id, r.consumer_name ?? `#${r.consumer_id}`);
     console.log(renderUsage(rows, (id) => names.get(id) ?? `#${id}`));
 }
+/** '30m' / '12h' / '7d' → milliseconds (the window header's date math). */
+function sinceMs(raw) {
+    const m = /^(\d+)([smhd])$/.exec(raw);
+    const unit = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m?.[2]];
+    return Number(m?.[1]) * unit;
+}
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function runStart(dir, flags) {
     // Validate before daemonizing so config errors hit the terminal, not the log file.