clavue 8.8.72 → 8.8.73

package/README.md

@@ -1,21 +1,41 @@
-# Clavue v8.8.72
+# Clavue v8.8.73
 
 ![Clavue cover](https://unpkg.com/clavue/image.png)
 
-`clavue` is an AI coding CLI. It starts fast, stays execution-first on real software tasks, and keeps product behavior anchored to `clavue` even when the runtime is routed through compatible providers or gateways.
+`clavue` is an AI coding CLI. It is built for execution-first engineering: the terminal remains the control surface, API providers stay configurable routes, permissions are explicit, and setup should move quickly from install to real coding work.
 
-## Study Guide
+## Product Philosophy
 
-For full user-facing usage and learning documentation, start in [study/README.md](./study/README.md).
+Clavue is built around a simple operating model: the user owns the workflow, the CLI owns the execution loop, and providers are replaceable routes.
+
+- Execution first: every feature should help inspect, edit, run, verify, or recover real software work.
+- Terminal-owned workflow: Clavue stays close to files, commands, diffs, permissions, and project state instead of becoming a detached chat surface.
+- Provider control, not provider identity: official login, custom API profiles, and compatible gateways are routing choices. The product identity remains Clavue.
+- Fast first run: install, choose an API configuration mode, paste URL/key or token, set model slots if needed, then start coding.
+- Visible configuration: `/provider` and `clavue provider` expose the active route, saved profiles, credential mode, model slots, validation, repair, and current environment state.
+- Practical autonomy: permission setup should make development smoother while still being explicit about trust boundaries.
+- Continuity over spectacle: long-context recovery, compaction, `/mao`, `/team`, and `/retro` exist to keep work moving, not to add noise.
+
+## What Clavue Is
 
-## Current Highlights
+- An AI coding CLI for execution-first engineering work.
+- A provider control center for custom API URLs, API keys, auth tokens, model slots, route validation, and repair.
+- A fast onboarding path for users who want official login, custom API configuration, CCR-compatible proxy routing, or manual setup later.
+- A runtime that can use compatible providers and gateways without pretending those providers are the product.
+- A set of native workflows for coding, review, recovery, team inspection, and retrospective improvement.
+
+## Core Surfaces
+
+- `/provider`: configure, switch, validate, repair, copy, edit, delete, or save provider profiles.
+- `/approvals`: set the default permission mode so trusted development environments can run with less friction.
+- `/mao`: run bundled Codex-style review and rescue flows through the active Clavue provider profile.
+- `/team`: inspect local team readiness, active team config, and capability state.
+- `/retro`: run a multi-round repo retrospective and upgrade loop.
+- Long-context recovery: proactive compaction plus reactive overflow recovery for long-running work.
+
+## Study Guide
 
-- AI coding CLI identity with provider routing as explicit operator control, not the product definition
-- Provider control center for saved profiles, current API environment, credentials, model slots, validation, and repair
-- `/mao` bundled Codex execution through the active clavue provider profile without a separate Codex login flow
-- `/team` local team inspection with concrete provider-readiness and capability reporting
-- Remote session surfaces that show the remote cwd, clear backend context correctly, and mark idle task boards as not currently running
-- Proactive compaction plus reactive overflow recovery to keep long-context sessions usable
+For full user-facing usage and learning documentation, start in [study/README.md](./study/README.md).
 
 ## Install
 
@@ -63,10 +83,10 @@ curl -fsSL https://unpkg.com/clavue/install.sh | bash
 Install a specific version:
 
 ```bash
-curl -fsSL https://unpkg.com/clavue@8.8.72/install.sh | bash -s -- 8.8.72
+curl -fsSL https://unpkg.com/clavue@8.8.73/install.sh | bash -s -- 8.8.73
 ```
 
-## Quick Start
+## Quick Start: Custom API
 
 Fastest path for custom API users:
 
@@ -97,6 +117,25 @@ clavue provider validate
 
 Use `clavue auth login` only if you want the official Anthropic login path. Custom API users do not need official login.
 
+## First-Run Setup Modes
+
+On first launch, Clavue should make the setup choice obvious:
+
+```text
+请选择 API 配置模式:
+  使用官方登录
+  自定义 API 配置
+  使用 CCR 代理
+  跳过（稍后手动配置）
+```
+
+- Use official login when you want the official Anthropic account flow.
+- Use custom API configuration when you have an API base URL plus API key or auth token.
+- Use CCR proxy when your environment already standardizes on a compatible proxy route.
+- Skip only when you want to configure later with `clavue provider` or `/provider`.
+
+After API setup, Clavue can also ask for a default permission mode. The recommended path for a trusted local development machine is the efficient development mode; the maximum-permission mode is intentionally reserved for environments you fully trust.
+
 This package is intended for users who want an execution-first coding CLI with explicit routing control when compatible providers or gateways are part of the setup.
 
 On macOS, `clavue` avoids Keychain by default and stores local credentials in `~/.clavue/.credentials.json` so startup does not trigger system Keychain prompts. If you explicitly want the old Keychain behavior back, launch with `CLAVUE_USE_KEYCHAIN=1 clavue`.