clavue-v1 1.0.2 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Clavue v1 (clavue-v1)
 
-![Clavue cover](https://unpkg.com/clavue/image.png)
+![Clavue cover](https://unpkg.com/clavue-v1/image.png)
 
 `clavue-v1` is an execution-first AI coding CLI built on the stable v8.9.1 engine with a lightweight four-slot multi-model combo layer (`main` / `light` / `plan` / `review`). It keeps the terminal as the control surface, uses direct repo tools for inspection/editing/verification, treats API providers as configurable routes, and passes slot models through verbatim — no allowlist, no family filter. Combo is opt-in via `CLAVUE_COMBO_*` env vars; with combo off, behavior is byte-identical to v8.9.1.
 
@@ -13,7 +13,7 @@ Clavue is built around a simple operating model: the user owns the workflow, the
 - Provider control, not provider identity: official login, custom API profiles, and compatible gateways are routing choices. The product identity remains Clavue.
 - Native coding workflows: direct file tools, shell execution, task tracking, worktrees, skills, and MCP resources are part of the runtime loop.
 - 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.
+- Visible configuration: `/provider` and `clavue-v1 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, `/team`, and `/retro` exist to keep work moving, not to add noise.
 
@@ -52,7 +52,7 @@ For provider and model routing setup, see [Clavue Provider And Model Best Practi
 
 Requirements:
 
-- Node.js 18 or newer
+- Node.js 22.18 or newer (tests and source-direct runs rely on native TypeScript type stripping)
 - macOS or Linux shell environment
 
 Run once with `npx` when you do not want a global install:
@@ -64,11 +64,11 @@ npx -y clavue-v1
 Run a specific version with `npx`:
 
 ```bash
-npx -y clavue-v1@1.0.0 --version
-npx -y clavue-v1@1.0.0
+npx -y clavue-v1@1.2.0 --version
+npx -y clavue-v1@1.2.0
 ```
 
-Install globally from npm when you want the `clavue` command to stay available:
+Install globally from npm when you want the `clavue-v1` command to stay available:
 
 ```bash
 npm install -g clavue-v1
@@ -76,7 +76,7 @@ clavue-v1 --version
 clavue-v1
 ```
 
-The package also exposes a `clavue` bin alias for drop-in migration.
+The package exposes a single `clavue-v1` bin. It deliberately does not claim the `clavue` name, so a global install never clashes with an existing `clavue` (v8.9.1) installation.
 
 One-line global install:
 
@@ -87,15 +87,40 @@ curl -fsSL https://unpkg.com/clavue-v1/install.sh | bash
 Install a specific version globally:
 
 ```bash
-curl -fsSL https://unpkg.com/clavue-v1@1.0.0/install.sh | bash -s -- 1.0.0
+curl -fsSL https://unpkg.com/clavue-v1@1.2.0/install.sh | bash -s -- 1.2.0
 ```
 
+## Quick Start: Official Clavue Cloud
+
+Official mode is a provider profile, not a second runtime: the same tools,
+compaction, permissions, and route inspection as every custom-API profile —
+only the credential source and the model catalog differ.
+
+1. Create a member API key at `https://www.clavue.com/account` (`cv_live_…`).
+2. Start `clavue-v1`, choose `自定义 API 配置` → `1. 添加配置`, pick the
+   `Clavue 官方` preset (API URL `https://api.clavue.com`), paste the key as
+   the auth token, and set model slots from the official family:
+
+```text
+主模型:   clavue-2.1        (official 27B coding model, 128K, premium pool)
+Haiku:    clavue-2.1-fast   (same model, fast pool — higher daily quota)
+Sonnet:   clavue-2.1-pro    (premium ceiling for planning and long-horizon work)
+Opus:     clavue-2.1-rev    (review-oriented; a different family from clavue-2.1, so it
+                             also works as CLAVUE_COMBO_REVIEW for cross-family review)
+```
+
+`auto` is also accepted. The CLI talks to `api.clavue.com/v1/messages`
+(Anthropic Messages API) and `/provider current` shows your plan and remaining
+points from the `x-clavue-points-*` response headers. Official identity is
+decided by exact host match only — a third-party gateway can never be
+mistaken for the official cloud.
+
 ## Quick Start: Custom API
 
 Fastest path for custom API users:
 
-1. Install with `curl -fsSL https://unpkg.com/clavue/install.sh | bash`
-2. Start with `clavue`
+1. Install with `curl -fsSL https://unpkg.com/clavue-v1/install.sh | bash`
+2. Start with `clavue-v1`
 3. At `请选择 API 配置模式`, choose `自定义 API 配置`
 4. Choose `1. 添加配置`
 5. Enter a profile name, API base URL, API key or auth token, and optional model slots
@@ -113,14 +138,14 @@ Opus 模型: planning/high-capability model, or leave empty to inherit safely
 Useful recovery commands:
 
 ```bash
-clavue provider        # reopen the same API setup manager
-clavue provider list   # list saved profiles without opening the UI
-clavue provider current
-clavue provider doctor # diagnose source-of-truth, drift, validation, and next repair action
-clavue provider validate
+clavue-v1 provider        # reopen the same API setup manager
+clavue-v1 provider list   # list saved profiles without opening the UI
+clavue-v1 provider current
+clavue-v1 provider doctor # diagnose source-of-truth, drift, validation, and next repair action
+clavue-v1 provider validate
 ```
 
-Use `clavue auth login` only if you want the official Anthropic login path. Custom API users do not need official login.
+Use `clavue-v1 auth login` only if you want the official Anthropic login path. Custom API users do not need official login.
 
 ## First Useful Session
 
@@ -147,14 +172,14 @@ On first launch, Clavue should make the setup choice obvious:
 - 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`.
+- Skip only when you want to configure later with `clavue-v1 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.
 
 For deployments, releases, builds, packaging, and operational maintenance where file edits should proceed but shell commands must still be confirmed, use trusted ops mode:
 
 ```bash
-clavue --permission-mode trustedOps
+clavue-v1 --permission-mode trustedOps
 ```
 
 You can also set it in settings with `"permissions": { "defaultMode": "trustedOps" }`. `trustedOps` behaves like `acceptEdits` for file edit tools in the current workspace, but Bash/PowerShell commands still ask before execution. The legacy `dontAsk` permission mode is deprecated and will not activate from CLI or settings; migrate `dontAsk` defaults to `trustedOps` for release/build/deploy workflows.
@@ -169,7 +194,35 @@ You can also run `/permissions` and choose `Autonomous development` from the mod
 
 This package is intended for users who want an execution-first coding CLI with direct repository tools, native workflow orchestration, explicit permission control, and configurable provider routing 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`.
+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-v1`.
+
+## Cross-Family Combo Review
+
+The review slot puts an independent model family between "the code changed"
+and "the work is done". Since 1.2.0 review is scheduled so it does not tax
+every edit:
+
+```bash
+CLAVUE_COMBO_MAIN=glm-5.3-flash          # developer model (any slot model is passed through verbatim)
+CLAVUE_COMBO_REVIEW=deepseek-v4-flash    # reviewer — pick a different family than main
+CLAVUE_COMBO_REVIEW_MODE=overlap         # overlap (default) | serial
+CLAVUE_COMBO_REVIEW_MIN_CHANGED_CHARS=80 # small edits accumulate; one review covers them
+CLAVUE_COMBO_REVIEW_MAX_PER_CHAIN=3      # review budget per query chain
+CLAVUE_COMBO_REVIEW_GRACE_MS=5000        # bounded wait for the final verdict at chain end
+CLAVUE_COMBO_REVIEW_FIX_LOOP=1           # opt-in: a chain-end "P0:" verdict grants one bounded fix turn
+```
+
+- `overlap` fires the review hop without blocking; the verdict is injected
+  at the next loop boundary so the developer model actually acts on it.
+  In the shipped A/B it roughly halves the review tax versus `serial`
+  (+38% vs +94% wall-clock on the hard task).
+- The reviewer is told which family wrote the code and which failure modes
+  that family is prone to. Same-family pairs still work; `/provider current`
+  flags them so you can choose an independent second opinion.
+- Review-on and the fix loop stay opt-in: on oracle-complete tasks a
+  competent developer model saturates on its own (see
+  `docs/evals/combo-review/`), so the defaults do not spend your time until
+  the discriminating experiment justifies it.
 
 ## Long-Running Session Memory
 
@@ -178,39 +231,38 @@ Clavue automatically restarts normal long-running sessions with `--max-old-space
 Useful controls:
 
 ```bash
-CLAVUE_MAX_OLD_SPACE_SIZE_MB=12288 clavue
-CLAVUE_DISABLE_HEAP_REEXEC=1 clavue
-NODE_OPTIONS="--max-old-space-size=12288" clavue
+CLAVUE_MAX_OLD_SPACE_SIZE_MB=12288 clavue-v1
+CLAVUE_DISABLE_HEAP_REEXEC=1 clavue-v1
+NODE_OPTIONS="--max-old-space-size=12288" clavue-v1
 ```
 
-`clavue --version` stays on the zero-load fast path and does not restart.
+`clavue-v1 --version` stays on the zero-load fast path and does not restart.
 
 ## CLI Entry Points
 
 Version check:
 
 ```bash
-clavue --version
 npx -y clavue-v1 --version
-npx -y clavue-v1@1.0.0 --version
-# available after a global install and launcher setup
-clavue --version
+npx -y clavue-v1@1.2.0 --version
+# available after a global install
+clavue-v1 --version
 ```
 
 Provider/config entry point:
 
 ```bash
-clavue provider
+clavue-v1 provider
 ```
 
 Anthropic account login/token commands:
 
 ```bash
-clavue auth login
-clavue setup-token
+clavue-v1 auth login
+clavue-v1 setup-token
 ```
 
-`clavue auth login` and `clavue setup-token` are only for Anthropic account auth flows. They are not the provider-profile entrypoint.
+`clavue-v1 auth login` and `clavue-v1 setup-token` are only for Anthropic account auth flows. They are not the provider-profile entrypoint.
 
 ## In-Session Workflows
 
@@ -232,7 +284,7 @@ clavue setup-token
 
 The Mao supervisor ledger is still used internally by delivery gates; user-facing `/mao` and `/codex` command surfaces are hidden while native Team/Agent workflows remain the public agent system.
 
-`/team` inspects real local team state from the active config root instead of giving a generic explanation. By default that is `~/.clavue/teams`, but it follows `CLAVUE_CONFIG_DIR` if you launch clavue against a different config root.
+`/team` inspects real local team state from the active config root instead of giving a generic explanation. By default that is `~/.clavue/teams`, but it follows `CLAVUE_CONFIG_DIR` if you launch clavue-v1 against a different config root.
 
 ```text
 /team
@@ -283,9 +335,9 @@ Companion commands are still available and can either follow the current app pro
 
 ## Package And Release Model
 
-- Source repo: `https://github.com/mycode699/clavue`
-- Public package: `https://www.npmjs.com/package/clavue`
-- Public install entrypoint: `npx -y clavue`
+- Source repo: `https://github.com/mycode699/clavue-v1`
+- Public package: `https://www.npmjs.com/package/clavue-v1`
+- Public install entrypoint: `npx -y clavue-v1`
 - `src/` is the development surface for new changes, while the checked-in `dist/` bundle is the current shipped runtime artifact
 - `types/generated/` holds generated contract types that stay outside authored runtime source
 - GitHub Releases publish installable archives plus `install.sh`
@@ -298,6 +350,9 @@ Companion commands are still available and can either follow the current app pro
 
 ```bash
 npm run validate:repo
+npm run typecheck
+npm run lint
+npm run test:fast
 npm run verify:dist
 node scripts/verify-provider-command-sidecar.mjs
 npm run verify:source-build
@@ -309,6 +364,9 @@ npm run package:release
 ```
 
 - `npm run validate:repo`: checks package metadata, required tracked files, workflow presence, and tag/version consistency
+- `npm run typecheck`: TypeScript 7 native full check (~2s) gated by a decrease-only error baseline in `scripts/typecheck-baseline.json`
+- `npm run lint`: Biome correctness rules scoped to changed files (`npm run lint:all` for the full tree)
+- `npm run test:fast`: curated 14-file high-signal suite under a 20s wall-clock budget
 - `npm run verify:dist`: smoke-tests `dist/cli.js`, provider setup, provider command, and release-critical sidecars
 - `node scripts/verify-provider-command-sidecar.mjs`: focused guard that fails if `dist/provider-command.js` drifts from the authored provider command source
 - `npm run verify:source-build`: rebuilds from `src/` into `experimental-dist/` and requires `--version` plus `--help` to boot under Node