@oiioii/cli 0.1.0

package/README.md

@@ -0,0 +1,840 @@
+# oiioii-cli
+
+Agent-native CLI for Oiioii / Hogi GenAI capabilities.
+
+`oiioii-cli` exposes Hogi workspace creation/selection, image/video/audio generation,
+resource upload/download, and generation records through a scriptable
+command-line interface. Authentication is persisted with `oiioii auth login`
+or temporarily overridden through `OIIOII_API_KEY`. It supports both
+human-readable output and a stable JSON envelope for AI agents and automation.
+
+## Current Status
+
+| Command | Capability | Status |
+|---|---|---|
+| `auth login` | Persist API Key and backend configuration | Implemented |
+| `workspace create/set/current` | Create, configure, and inspect workspaces | Implemented |
+| `image text` | Text-to-image generation | Implemented |
+| `image edit` | Image-to-image editing | Implemented |
+| `video text` | Text-to-video generation | Implemented |
+| `video image` | Image-to-video generation | Implemented |
+| `video generate` | Model-validated mixed image/video/audio reference generation | Implemented |
+| `audio generate` | Seed Audio and Suno audio/music generation | Implemented |
+| `upload file` | Upload local image/video/audio resources | Implemented |
+| `record get/open` | Query generation metadata and download resources | Implemented |
+| `inspect capabilities/models` | Inspect declared capabilities and live backend models | Implemented |
+| `preview latest/bundle` | Read local preview bundles created by generation commands | Implemented |
+| `task list/status/wait` | Inspect and wait for local generation tasks | Implemented |
+| `logs list/export/path` | Inspect and export structured local logs | Implemented |
+| `points balance/quote/cost` | Inspect balance, estimate a request, and query actual charges | Implemented |
+
+Important current limitations:
+
+- API keys are stored in `~/.oiioii/config.json` after `oiioii auth login`; the file is owner-readable only (`0600`).
+- Generation submits `submit_async_media_generation` and returns immediately with the authoritative backend `task_id` plus a `local_task_id`.
+- The backend task ID, workspace, media type, asset ID, progress, and terminal outputs are cached in the owner-only local task store.
+- `task status/wait` query `query_async_media_generation` for non-terminal cached tasks and accept either the backend or local task ID.
+- Image, video, and audio generation create local preview bundles after a queried task reaches a terminal state.
+- `inspect capabilities` is local metadata; `inspect models` requires authentication and queries the active backend.
+- Asset-library browsing/search/update/delete and style-library commands are not available.
+
+## Requirements
+
+- Node.js 18 or newer when running from source or the npm package.
+- An existing Hogi MCP API Key.
+- A workspace ID for image/video/audio generation and resource upload. It can be
+  created with `oiioii workspace create` or supplied from an existing project.
+- `npm` is the repository package manager.
+
+The hosted installer uses Node.js 18 or newer when available. If no compatible
+Node.js/npm installation exists, it downloads an official Node.js runtime,
+verifies its SHA256, and keeps it under the oiioii installation directory.
+
+## Quick Start
+
+```bash
+npm install
+npm run build
+
+node dist/cli.js --help
+node dist/cli.js --version
+```
+
+Development mode does not require a build:
+
+```bash
+npm run dev -- --help
+```
+
+Install from the checkout:
+
+```bash
+npm install -g .
+oiioii --help
+oiioii-cli --version
+```
+
+Both `oiioii` and `oiioii-cli` point to the same CLI entry point.
+
+### Install from npm or the hosted bootstrap
+
+The bootstrap scripts install the npm package into an application-owned prefix,
+write `install.json`, and create stable `oiioii` / `oiioii-cli` wrappers. CLI
+updates reuse the exact Node.js, npm, registry, package, and prefix recorded by
+the installer.
+
+macOS (Apple Silicon and Intel are detected automatically):
+
+```bash
+curl -fsSL https://<public-host>/install.sh | bash
+```
+
+Windows x64, from PowerShell:
+
+```powershell
+$script = Join-Path $env:TEMP "install.ps1"; curl.exe -fsSL https://<public-host>/install.ps1 -o $script; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script; Remove-Item $script
+```
+
+Production is the default and follows npm's `latest` dist-tag. For the HOE test
+build, set `OIIOII_ENV=test`; it follows the `test` dist-tag and accepts only
+prerelease versions. Set `OIIOII_CLI_VERSION` to install one exact version.
+
+After bootstrap installation:
+
+```bash
+oiioii update --check
+oiioii update
+oiioii install 0.2.0
+oiioii versions
+```
+
+Local builds are intentionally excluded from npm self-update and should be
+rebuilt from the checkout.
+
+## Build Environments
+
+The default backend URL is embedded into the generated bundle at build time.
+
+| Build command | Environment | Embedded default backend |
+|---|---|---|
+| `npm run build:production` | production | `https://api.oiioii.ai` |
+| `npm run build:test` | test (HOE) | `https://api-hoe.oiioii.tv` |
+| `npm run build:local` | local | `http://localhost:4000` |
+
+`npm run build` builds the test environment to preserve the existing default.
+
+For a custom deployment, override the embedded URL during the build:
+
+```bash
+OIIOII_BUILD_BASE_URL=https://custom.example.com npm run build:production
+```
+
+Supported build environment names are exactly `production`, `test`, and
+`local`. Unknown values fail the build instead of silently selecting a domain.
+
+The embedded URL is a fallback. Existing runtime overrides remain available:
+
+- Root option: `--base-url <url>` for commands that consume the root override.
+- Environment variable: `OIIOII_BASE_URL`.
+- Persisted `baseUrl` in `~/.oiioii/config.json`.
+
+## Authentication and Workspace
+
+Persist an existing MCP API Key and the backend URL:
+
+```bash
+oiioii auth login \
+  --api-key "oii_sk_..." \
+  --base-url "https://api-hoe.oiioii.tv"
+```
+
+The CLI writes the API Key and Base URL to `~/.oiioii/config.json` with file
+permissions `0600`. `OIIOII_API_KEY` remains available as a temporary process
+override. A legacy `~/.oiioii/credentials.json` file, if present, is ignored.
+
+Create a workspace using the injected API Key:
+
+```bash
+oiioii workspace create \
+  --name "My video project" \
+  --language zh \
+  --set-current \
+  --json
+```
+
+`--language` accepts `en`, `zh`, `zh-Hant`, or `ja`. `--set-current` is
+explicit: without it, creating a workspace does not overwrite the current
+workspace in local configuration.
+
+Set and inspect the active workspace:
+
+```bash
+oiioii workspace set <workspace_id> --json
+oiioii workspace current --json
+```
+
+Workspace resolution order is:
+
+1. Root `--workspace <id>` option.
+2. `OIIOII_WORKSPACE_ID` environment variable.
+3. `defaultWorkspaceId` in `~/.oiioii/config.json`.
+
+## Image Generation
+
+Text-to-image:
+
+```bash
+oiioii image text \
+  --prompt "a cinematic city in the rain" \
+  --model seedream45 \
+  --resolution 2K \
+  --json
+```
+
+Image editing:
+
+```bash
+oiioii image edit \
+  --image hogi://image/<id> \
+  --prompt "change the scene to watercolor" \
+  --model seedream45 \
+  --resolution 2K \
+  --json
+```
+
+Current behavior:
+
+- Accepts `--model-id <id>` from `inspect models` for exact backend model
+  selection, or `--model <key> --variant <variant>` as an alternative.
+- Calls `POST /mcp/genai/sse` with JSON-RPC `tools/call` and `submit_async_media_generation`.
+- Authenticates with `x-hogi-api-key`.
+- Requires an active workspace.
+- Returns after submission; use `task status` or `task wait` to query progress and terminal `hogi://image/...` output.
+- Image editing adapts the source URI to the async service's `referenceImages` contract.
+- When image shape options are omitted, the CLI uses the exact selected model
+  catalog row's first aspect ratio and resolution (falling back only when the
+  catalog leaves those fields empty).
+- Prefer `--aspect-ratio` for image shape. Deprecated `--size WxH` remains
+  accepted for script compatibility but is hidden from help; GPT-4o receives
+  its nearest supported pixel-size enum.
+
+## Video Generation
+
+Text-to-video:
+
+```bash
+oiioii video text \
+  --prompt "slow camera push through neon rain" \
+  --model seedance20 \
+  --duration 5 \
+  --aspect-ratio 16:9 \
+  --resolution 720p \
+  --json
+```
+
+Image-to-video:
+
+```bash
+oiioii video image \
+  --image hogi://image/<id> \
+  --prompt "animate the clouds and move the camera forward" \
+  --model seedance20 \
+  --duration 5 \
+  --aspect-ratio 16:9 \
+  --resolution 720p \
+  --json
+```
+
+Mixed model-supported references:
+
+```bash
+oiioii video generate \
+  --prompt "combine the visual rhythm, motion, and soundtrack references" \
+  --image hogi://image/<id-1> hogi://image/<id-2> \
+  --video hogi://video/<id> \
+  --audio hogi://audio/<id> \
+  --model seedance25 \
+  --duration 8 \
+  --resolution 720p \
+  --json
+```
+
+When video duration, aspect ratio, or resolution is omitted, the CLI resolves
+the first supported value from the exact selected model/variant before dry-run
+validation or submission. This avoids applying Seedance defaults to models
+such as MiniMax, Veo, Sora, Kling, or Grok.
+
+Current behavior:
+
+- Accepts `--model-id <id>` from `inspect models` for exact backend model
+  selection, or `--model <key> --variant <variant>` as an alternative.
+- Calls `submit_async_media_generation` through `/mcp/genai/sse` with `x-hogi-api-key` authentication.
+- Returns after submission; terminal video URI validation happens during `task status/wait`.
+- Text-to-video sends `prompt`, `duration`, `aspectRatio`, `resolution`, and
+  `workspace_id`.
+- Model-specific `imageUrl`/`images` fields are validated locally, then adapted
+  to the async service's `referenceImages` field with `generateMode` preserved.
+- `video generate` accepts zero or more `--image`, `--video`, and `--audio`
+  references in the same request. `--mode auto` derives `text2Video` or
+  `omni2Video`; frame semantics can be selected explicitly with `--mode`.
+- Reference fields, combinations, and limits are validated against an exact
+  backend-tool contract before MCP submission. The current mixed-input matrix is:
+  Seedance 2.0/2.5 (image + video + audio), MiniMax H3
+  (image + video + optional audio), Wan 3.0 (image + video + audio), Wan 2.7
+  (image + video), Gemini Omni and Kling V3 Omni (image + video). Other verified
+  models accept image references only. Seedance 2.0 video references use the
+  same frontend asset-generation boundary as Hogi rather than the narrower
+  Agent-facing MCP schema.
+
+## Audio Generation
+
+Seed Audio text generation:
+
+```bash
+oiioii audio generate \
+  --prompt "温柔女声朗读一段雨夜旁白" \
+  --model seed-audio \
+  --format mp3 \
+  --subtitle \
+  --json
+```
+
+Seed Audio reference generation accepts either up to three audio references or
+one image reference; the two reference kinds cannot be mixed:
+
+```bash
+oiioii audio generate --prompt "保持参考音色" --audio hogi://audio/<id> --json
+oiioii audio generate --prompt "为画面生成氛围音" --image hogi://image/<id> --json
+```
+
+Suno supports description mode, custom lyrics/style mode, and instrumental
+music. The supported variants are `chirp-v4-5` and `chirp-v5`:
+
+```bash
+oiioii audio generate --prompt "cinematic orchestral background music" --model suno --instrumental --json
+oiioii audio generate --prompt "custom lyrics" --model suno --custom --tags "dream pop, female vocal" --json
+```
+
+Current behavior:
+
+- Accepts `--model-id <id>` from `inspect models`, or an exact
+  `--model <key> --variant <variant>` selection.
+- Seed Audio supports `mp3`, `wav`, `pcm`, and `ogg_opus`, plus subtitle,
+  loudness, pitch, sample-rate, and speech-rate controls.
+- Terminal queries accept only `hogi://audio/...` output for audio tasks.
+- The backend async generation service owns the loading asset and final workspace update.
+- Structured logs and telemetry record model/mode/reference counts/output
+  format/result metadata, but never prompts, request bodies, or API keys.
+
+Generation consumes real credits. Do not run image/video/audio generation in
+unbounded automated loops, and do not retry failures blindly.
+
+## Async Generation and Workspace Assets
+
+Image, video, and audio commands submit through:
+
+```text
+POST /mcp/genai/sse
+method: tools/call
+name: submit_async_media_generation
+```
+
+The backend creates the loading workspace asset and returns its `assetId` and
+authoritative `taskId`. The CLI caches both IDs. `task status/wait` calls
+`query_async_media_generation`, reconciles progress/error/output into the local
+record, and creates the terminal preview bundle. The CLI does not issue a second
+`create_asset` call, which avoids duplicate workspace assets.
+
+## Local Resource Upload
+
+Upload image, video, or audio bytes:
+
+```bash
+oiioii upload file ./image.png --json
+oiioii upload file ./clip.mp4 --json
+oiioii upload file ./voice.mp3 --json
+
+# Force VOD direct upload for any supported video
+oiioii upload file ./clip.mp4 --vod --json
+```
+
+Override the inferred extension or display name:
+
+```bash
+oiioii upload file ./raw-file --type mp3 --name voice.mp3 --json
+```
+
+Insert the new asset after an existing workspace asset when ordering matters:
+
+```bash
+oiioii upload file ./voice.mp3 --after-asset-id <asset_id> --json
+```
+
+Upload behavior:
+
+- Images, audio, and videos smaller than 10 MB use raw `application/octet-stream` bytes at
+  `POST /v1/workspace/uploadAsset` with `workspace_id`, `file_type`, and optional
+  `file_name` / `after_asset_id` query parameters.
+- MOV files and videos of 10 MB or larger automatically use the VOD flow:
+  `GET /media/vod/upload_token` -> direct upload to Volc VOD (multipart for large files) ->
+  `POST /media/vod/commit_upload` -> `GET /media/vod/transcode_status`.
+  `--vod` forces this flow for a smaller video.
+- VOD uploads support videos up to 500 MB. File bytes bypass the Hogi backend;
+  only the short-lived token, Vid commit, and transcode polling use Hogi APIs.
+- The command waits for VOD transcoding and returns the final `hogi://video/...`
+  URI together with `task_id` and `upload_mode: "vod"`.
+- `--after-asset-id` applies only to the small-file endpoint and is rejected for VOD uploads.
+- Requires an active workspace. The small-file request creates the asset directly;
+  VOD creates it during `commit_upload`.
+- Returns `asset_id`, `asset_uri`, `file_uri`, `domain`, `workspace_id`, and
+  `upload_mode`; VOD also returns `task_id`. `uri`
+  remains an alias of `file_uri` for compatibility.
+- `--attach` is retained as a no-op compatibility flag because uploads are now
+  always attached.
+- A storage or workspace-write failure fails the upload command.
+- Arbitrary documents and URL uploads are outside the current scope.
+
+Supported extensions:
+
+- Images: `jpg`, `jpeg`, `png`, `gif`, `svg`, `webp`, `heic`, `heif`, `bmp`, `ico`, `tiff`, `jfif`.
+- Video: `mp4`, `webm`, `avi`, `mov`, `flv`, `mkv`.
+- Audio: `mp3`, `wav`, `ogg`, `m4a`, `aac`, `flac`, `wma`, `ape`.
+
+## Records and Resource Download
+
+Query generation metadata:
+
+```bash
+oiioii record get hogi://image/<id> --json
+oiioii record get hogi://video/<id> --json
+```
+
+Download and open a resource:
+
+```bash
+oiioii record open hogi://image/<id> --json
+```
+
+Download without opening it:
+
+```bash
+oiioii record open hogi://video/<id> \
+  --output ./downloads \
+  --no-open \
+  --json
+```
+
+`record open` also supports `--filename <name>` and `--wm` for a watermarked
+resource when supported by the backend.
+
+Uploaded files are resources but not GenAI generation records. Use `record open`
+for an uploaded URI; `record get` may not find it.
+
+## Capability and Model Inspection
+
+```bash
+oiioii inspect capabilities --json
+oiioii inspect models --json
+oiioii inspect models --domain image --json
+oiioii inspect models --domain video --json
+oiioii inspect models --domain audio --json
+```
+
+`inspect models` authenticates with `OIIOII_API_KEY` and calls the active
+backend model catalog at `POST /points/mcp_model_pricings`. It returns actual
+displayable image/video/audio model records, including the model name and key,
+text-LLM input capabilities, reference-image bounds, points cost, supported
+sizes/aspect ratios/durations, descriptions, tags, and membership restrictions.
+MCP tool definitions are not returned.
+
+Each model includes a unique, directly executable selector:
+
+```json
+{
+  "id": 50,
+  "name": "Seedance2.0 fast",
+  "key": "seedance20",
+  "variant": "fast",
+  "selector": {
+    "model_id": 50,
+    "cli_args": ["--model-id", "50"]
+  }
+}
+```
+
+The top-level `selection` object is the machine-readable interpretation contract:
+
+- `preferred: "model_id"` tells an Agent to copy `selector.cli_args` into a
+  generation command.
+- `variant_mcp_argument: "version"` states that the selected catalog variant is
+  forwarded as the GenAI MCP `version` argument.
+- `empty_input_capabilities: "unknown"` means an empty list must not be treated
+  as text-only or unsupported.
+- `input_capabilities` describes text-LLM input modalities; it does not determine
+  whether an image/video/audio generation model belongs to that output domain.
+- `reference_image_count_max` controls reference-image support for image models.
+  An explicit `0` disables image editing; a missing/null value follows the Hogi
+  frontend fallback and does not reject image references.
+- `generation_input_contract` is the CLI's resolved per-model contract after
+  combining model-specific image/video/audio rules with catalog reference-image
+  bounds. Its `media` field lists accepted inputs, while
+  `prompt_only_supported` separately states whether references may be omitted.
+- `points_cost_semantics: "base_cost"` means `points_cost` is not a final quote.
+- Duration entries are either exact seconds (`"10"`) or inclusive ranges
+  (`"4-15"`).
+
+Agents should prefer `--model-id` because a single key can have multiple
+variants. Human callers can alternatively use `--model <key> --variant <value>`.
+When `--variant` is omitted, the active catalog row with the lowest
+`sort_order` is the deterministic default:
+
+```bash
+oiioii video text --prompt "cinematic rain" --model-id 50 --duration 5 --resolution 720p --aspect-ratio 16:9 --json
+oiioii video text --prompt "cinematic rain" --model seedance20 --variant fast --duration 5 --resolution 720p --aspect-ratio 16:9 --json
+```
+
+When an exact catalog selection is used, generation validates its output domain,
+reference-image bounds, aspect ratio, resolution, duration, and command-specific
+reference contract before consuming credits. `input_capabilities` is not used as
+a universal deny-list for image/video/audio generation models. The catalog
+variant is sent to GenAI MCP as `version`. `--model <key>` resolves through the
+same catalog selection and constraint validation path as `--model-id`.
+
+## Points and Generation Cost
+
+```bash
+oiioii points balance --json
+oiioii points quote --model-id 60 --duration 4 --resolution 480p --json
+oiioii points quote --model seedance20 --variant mini --duration 4 --resolution 480p --json
+oiioii points cost hogi://video/example.mp4 --json
+```
+
+`points balance` calls MCP resource tool `get_user_info`. `points cost` calls
+`query_generation_cost`; `chargedAmount` is authoritative when status is
+`charged`. Because decrement ledgers commonly return a negative
+`chargedAmount`, CLI also returns positive `consumed_points`. A successful generation can temporarily report `no_charge` while
+the asynchronous backend settlement is still completing.
+
+`points quote` combines the authenticated user's tier with the current backend
+model catalog, including resolution prices, requested/reference duration and an
+active promotional discount. Its result always contains `estimate: true` and a
+`caveat`: backend feature flags, resolved media duration, promotion changes and
+fallback pricing can make the final charge differ. Use `points cost` for the
+settled amount.
+
+Structured MCP errors `GENAI_POINTS_INSUFFICIENT` and
+`GENAI_SUB_ACCOUNT_MONTHLY_POINTS_LIMIT_EXCEEDED` map to the stable CLI code
+`QUOTA_EXCEEDED` instead of a generic generation failure.
+
+## Local Tasks and Preview Bundles
+
+Generation commands create local task entries in:
+
+```text
+~/.oiioii/tasks.jsonl
+```
+
+The current lifecycle is:
+
+```text
+created -> submitting -> queued -> running -> succeeded | failed | cancelled
+```
+
+The public commands accept the cached backend ID or local ID:
+
+```bash
+oiioii task list
+oiioii task status <task_id>
+oiioii task wait <task_id> --timeout 300
+```
+
+For non-terminal tasks, `status` makes one authenticated backend query and
+`wait` polls the backend until a terminal state or `TASK_TIMEOUT`. Every query
+uses the workspace cached with the original submission.
+
+Existing preview bundles can be read with:
+
+```bash
+oiioii preview latest --json
+oiioii preview bundle <task_id> --json
+```
+
+Bundle format:
+
+```text
+~/.oiioii/previews/<bundle_id>/
+  manifest.json
+  summary.json
+  artifacts/
+```
+
+Image, video, and audio generation invoke `PreviewStore.createBundle` after the local
+task reaches a terminal state. Preview persistence is best-effort: a local
+preview write failure is reported as a warning and does not turn a successful
+generation into a failure. When an older terminal task predates automatic
+preview creation, `preview latest` and `preview bundle <task_id>` lazily create
+the missing bundle from local task history.
+
+## JSON Output Protocol
+
+Implemented commands support the global `--json` option.
+
+Success envelope:
+
+```json
+{
+  "ok": true,
+  "type": "generation_submitted",
+  "data": {
+    "task_id": "async_image_...",
+    "local_task_id": "task_...",
+    "status": "queued",
+    "artifacts": []
+  },
+  "next": [
+    { "command": "oiioii task status async_image_... --json" }
+  ]
+}
+```
+
+Error envelope:
+
+```json
+{
+  "ok": false,
+  "type": "generation_failed",
+  "error": {
+    "code": "WORKSPACE_REQUIRED",
+    "message": "No workspace set."
+  }
+}
+```
+
+Stable error codes include:
+
+| Code | Meaning |
+|---|---|
+| `AUTH_REQUIRED` | `OIIOII_API_KEY` is missing or empty |
+| `AUTH_INVALID` | Credential rejected |
+| `API_KEY_INVALID` | Invalid API Key |
+| `WORKSPACE_REQUIRED` | No active workspace |
+| `INVALID_ARGUMENT` | Unsupported or malformed input |
+| `GENERATION_FAILED` | MCP/model generation failure |
+| `GENERATION_TIMEOUT` | Long-running request timed out |
+| `RECORD_NOT_FOUND` | Record/resource/bundle not found |
+| `TASK_NOT_FOUND` | Local task ID not found |
+| `TASK_TIMEOUT` | Local task did not become terminal before the wait deadline |
+| `QUOTA_EXCEEDED` | Insufficient points, subgroup quota, or backend rate limit exceeded |
+| `PAYLOAD_TOO_LARGE` | Upload exceeds the backend limit |
+| `CONTENT_SAFETY_BLOCKED` | Prompt or reference rejected by the general content safety policy |
+| `IP_CHARACTER_RESTRICTED` | Prompt or reference may contain a restricted IP or character |
+| `SERVER_ERROR` | Invalid response or backend error |
+| `NETWORK_ERROR` | Network request failed |
+| `NOT_IMPLEMENTED` | Registered capability is not implemented |
+| `CONFIG_ERROR` | Local configuration error category |
+
+## Structured Logs
+
+Every CLI feature creates a client-side trace through the shared logging API.
+The logging module owns the schema, redaction, local storage, filtering,
+rotation, and export behavior; business modules never write log files directly.
+
+A feature trace uses one `trace_id` from command entry to command completion:
+
+```text
+feature.started
+  -> feature.step (configuration, task, validation, local storage)
+  -> api.request -> api.response | api.error
+  -> feature.completed | feature.failed
+```
+
+This is CLI-side observability only. It does not collect or depend on logs from
+inside the Hogi backend.
+
+Recorded API events use the same `request_id` for correlation:
+
+```text
+api.request -> api.response | api.error
+```
+
+Feature traces cover workspace, image/video/audio generation, upload, records,
+inspection, preview, task commands, and their local storage steps. API boundary
+events cover:
+
+- GenAI and Asset MCP calls.
+- Resource upload and download.
+- Generation-record lookup.
+
+Logs contain safe operational fields such as source, operation, HTTP method,
+path, status, duration, and selected non-sensitive metadata. They do not record
+request headers, API Keys, bearer tokens, prompts, request bodies, or response
+bodies. Sensitive key names and recognizable secret values are redacted again
+inside the central logger before persistence.
+
+Default storage:
+
+```text
+~/.oiioii/logs/events.jsonl
+```
+
+The active file is limited to 5 MiB and rotated across at most five files. Log
+directories use owner-only permissions and log/export files are written with
+mode `0600`. Logging is best-effort: a storage failure does not change the
+result of the API operation being logged.
+
+List logs:
+
+```bash
+oiioii logs list --json
+oiioii logs list --category api --level error --limit 20 --json
+oiioii logs list --source hogi_mcp_client --since 2026-08-14T00:00:00Z --json
+oiioii logs list --feature image.text --json
+oiioii logs list --trace trace_<id> --json
+```
+
+Export logs as JSONL or JSON:
+
+```bash
+oiioii logs export --output ./oiioii-logs.jsonl --json
+oiioii logs export --output ./oiioii-logs.json --format json --json
+```
+
+Exports do not overwrite an existing file unless `--force` is supplied.
+
+Show the active log path:
+
+```bash
+oiioii logs path --json
+```
+
+`logs list`, `logs export`, and `logs path` do not create feature-trace entries
+themselves, so inspecting or exporting logs does not change the result set.
+
+## DataFinder Telemetry
+
+Remote product telemetry is centralized under `src/telemetry/`. Business code
+only calls `recordTelemetryBusinessInfo`, `markTelemetryPartialSuccess`, or
+`setTelemetryWorkspaceId` to provide safe business information. It does not
+import the DataRangers SDK, define event names, construct common parameters, or
+manage delivery.
+
+Each executable command is mapped centrally to one business domain and emits at
+most two events: `cli_biz_<domain>_called` and `cli_biz_<domain>_result`. The
+result event records the command's total `duration_ms`, `result`
+(`success`, `partial_success`, `failure`, or `timeout`), and a normalized
+`error_code` on failure. There are no separate staged or technical events;
+latency and outcome are measured on the business result event.
+
+The telemetry manager adds `schema_version`, `app_env`, `app_name`,
+`cli_version`, `command`, `trace_id`, `workspace_id`, `os`, `arch`, and
+`node_major`. `workspace_id` is omitted for commands without an active
+workspace. API Keys, tokens, prompts, file paths, and request/response bodies
+are dropped centrally.
+
+Telemetry requires an explicitly identified real Hogi user ID. There is no
+installation-ID or anonymous fallback: until the authenticated backend UID is
+provided through `identifyTelemetryUser`, events are not sent. SDK delivery is
+best-effort, writes only delivery status to the local debug log, and waits for
+the SDK queue for a bounded period at process exit.
+
+## Global Options
+
+```text
+--json
+--base-url <url>
+--workspace <id>
+--verbose
+--no-color
+```
+
+`--verbose` and `--no-color` are reserved global options; current
+output does not yet vary based on them.
+
+## Local Files and Environment Variables
+
+Default local directory: `~/.oiioii/`.
+
+| Path | Purpose |
+|---|---|
+| `config.json` | API Key, backend URL, and default workspace |
+| `tasks.jsonl` | Local generation task records |
+| `previews/` | Preview bundles created by image, video, and audio generation |
+| `logs/events.jsonl` | Active structured log file; older files use numeric suffixes |
+
+Environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `OIIOII_CONFIG_DIR` | Override the local configuration directory |
+| `OIIOII_BASE_URL` | Override the backend URL at runtime |
+| `OIIOII_WORKSPACE_ID` | Override the active workspace |
+| `OIIOII_BUILD_ENV` | Select `production`, `test`, or `local` while building |
+| `OIIOII_BUILD_BASE_URL` | Override the URL embedded in a build |
+| `OIIOII_API_KEY` | Temporarily override the persisted API Key for the current process |
+| `OIIOII_E2E` | Explicit opt-in marker for credit-consuming E2E workflows |
+| `OIIOII_LOG_DISABLED` | Set to `1` to disable local logging, primarily for isolated tests |
+| `OIIOII_TELEMETRY_DISABLED` | Set to `1` to disable DataFinder telemetry |
+
+Never commit or print real API Keys, tokens, or passwords.
+
+## Development and Verification
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run lint
+npm run build
+```
+
+The current local suite contains unit tests and CLI subprocess integration
+tests with mocked HTTP servers. There are no checked-in real-backend E2E test
+files at present; running the normal test command does not consume GenAI credits.
+
+Most recent local verification for this README update:
+
+- 45 test files passed.
+- 333 tests passed.
+- `npm run typecheck` passed.
+- `npm run lint` passed.
+- Production, HOE test, and local builds passed; their embedded backend
+  URLs were verified as `api.oiioii.ai`, `api-hoe.oiioii.tv`, and
+  `localhost:4000` respectively.
+
+## Project Structure
+
+```text
+oiioii-cli/
+  src/
+    cli.ts                         Commander entry point
+    app/context.ts                 AppContext definition
+    commands/                      CLI command wiring and workflows
+    clients/                       Hogi HTTP/MCP adapters
+    config/
+      build_environment.ts         Build environment/domain mapping
+      config_store.ts              Local configuration storage
+    core/
+      model_map.ts                 Model-to-MCP-tool mapping
+      task_store.ts                Local task persistence
+      preview_store.ts             Preview bundle persistence
+      upload_file_types.ts         Upload type/domain validation
+    output/                        JSON envelopes, errors, human output
+    logging/                       Log schema, redaction, storage, API spans
+    telemetry/                     Event registry, common context, lifecycle, Volc transport
+    skills/SKILL.md                Agent usage reference
+  tests/
+    unit/                          Unit tests
+    cli/                           CLI subprocess integration tests
+  .plan/release/                   Standalone installer workflow/assets
+  tsup.config.ts                   Environment-aware ESM bundling
+  package.json
+```
+
+## Security Notes
+
+- API keys are persisted by `oiioii auth login` in `~/.oiioii/config.json`.
+- Config files containing credentials are written with owner-only permissions (`0600`).
+- Generation and resource APIs use `x-hogi-api-key`.
+- Generated artifacts must use the expected `hogi://image/...`,
+  `hogi://video/...`, or `hogi://audio/...` URI domain; public URLs and mismatched resource domains are
+  rejected by the generation workflow.