@margay/ccl-core 1.4.1-beta-duo.0 → 1.4.5-rc.10

package/QUICKSTART.md

@@ -1,17 +1,22 @@
 # CCL Quick Start
 
 This guide gets a new user from install to first useful session with CCL
-`1.3.1`. For the full feature map, see [README.md](./README.md) and
+from an npm package or source checkout. For the full feature map, see [README.md](./README.md) and
 [docs/index.md](./docs/index.md).
 
 ## 1. Install
 
 ```bash
 npm install -g @margay/ccl-core
-ccl --version
-# 1.3.1 (CCL)
+margay --version
+# Prints the installed version; npm uses the published default tag.
 ```
 
+Starting with `1.4.5-rc.10`, the package registers both `ccl` and `margay` for the
+same CLI. The `1.4.5-rc.9` package registers only `margay`.
+See [CLI installation and upgrades](docs/cli-installation.md) for local
+versus global installation and migration of older launchers.
+
 From a source checkout:
 
 ```bash
@@ -20,39 +25,69 @@ npm run build
 node dist/cli.js --version
 ```
 
+## Local analytics on the upgraded workstation
+
+Use `margay analytics status` to inspect collection and `margay analytics gate status` to inspect the analysis feature. Collection starts disabled and requires an authorized local website account to upload; installing this build does not change your login or connect production events. See [viewing events and controlling switches](docs/local-analytics-quickstart.md).
+
 ## 2. Choose Authentication
 
 Use one of these paths.
 
-### Margay Gateway
+### Margay website account (current source checkout)
 
-Use this path for gateway-routed models such as DeepSeek, Kimi, GLM, or any
-model exposed by your Margay gateway.
+The website-account flow is implemented in this checkout and has passed local
+client tests. Live website authorization and commercial readiness are still
+unverified; installing a published package does not establish that it includes
+these changes. Build the checkout as shown above, then run:
 
-```text
-ccl
-/gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
+```bash
+node dist/cli.js login
+node dist/cli.js account status
 ```
 
-If you already have a token:
+Complete login or registration at `https://margay-ai.com`, approve CLI access,
+and wait for the terminal to confirm sign-in. Existing Margay users should use
+the same website login method. No separate CLI password is created.
+
+Inside the interactive CLI, `/gateway login` or `/gateway register` without
+arguments opens the same website flow. `/gateway status` shows the saved
+account's verified membership and balance. `/gateway logout` signs out locally.
+The first-launch account step supports Enter to sign in and S/Esc to set up
+later; Esc cancels an in-progress TUI login. `/login` remains Claude OAuth.
+
+Website credentials use the system credential store; `gateway.json` contains
+an account reference and metadata. Store access failure stops login without
+falling back to plaintext. To change the website account, use
+`node dist/cli.js login --force`; cancellation or failure preserves the old
+saved session. To sign out from a shell, use `node dist/cli.js logout`.
+
+### Manual gateway credentials / invite codes
+
+These existing TUI paths remain available:
 
 ```text
-ccl
+margay
 /gateway login <GATEWAY_URL> <GATEWAY_TOKEN>
+/gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
+/gateway register --invite <INVITE_CODE>
 /gateway doctor
-/gateway status
 ```
 
-`/gateway login` and `/gateway register` write `~/.ccl/gateway.json`, update the
-current CCL process, and maintain a managed shell rc block. If your current
-terminal already exported old `CCL_GATEWAY_URL` or `CCL_GATEWAY_KEY` values,
-open a new terminal, reload the rc file, or unset those variables before
-starting a new CCL process.
+Manual credentials use the legacy configuration storage and do not acquire the
+website flow's system-store guarantee. If a website account is already saved,
+run `/gateway logout` before replacing it with manual credentials.
+
+Explicit `CCL_GATEWAY_*` environment credentials may override the saved website
+account for model requests. Inspect `/gateway doctor` and clear an obsolete
+complete tuple in the launching shell; website logout does not remove an
+explicit environment override. See the
+[account and gateway guide](./docs/gateway-quickstart.md) for defaults,
+status meanings, storage prerequisites, and troubleshooting.
 
 ### Claude OAuth
 
 ```text
-ccl
+margay
 /login
 ```
 
@@ -62,7 +97,7 @@ The first interactive launch can also guide you through OAuth login.
 
 ```bash
 export ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
-ccl --model sonnet
+margay --model sonnet
 ```
 
 Do not paste real keys into docs, shell history examples, bug reports, or shared
@@ -73,23 +108,23 @@ screenshots.
 Interactive:
 
 ```bash
-ccl
-ccl --model deepseek-v4-pro
-ccl --cwd /path/to/project
+margay
+margay --model deepseek-v4-pro
+margay --cwd /path/to/project
 ```
 
 One-shot:
 
 ```bash
-ccl -p "explain this error" < error.log
-ccl -p "summarize the current repository" --max-turns 20
-ccl -p "return JSON" --output-format json
+margay -p "explain this error" < error.log
+margay -p "summarize the current repository" --max-turns 20
+margay -p "return JSON" --output-format json
 ```
 
 Streaming automation:
 
 ```bash
-ccl -p "run a compact audit" --output-format stream-json
+margay -p "run a compact audit" --output-format stream-json --verbose
 ```
 
 ## 4. Useful First Slash Commands
@@ -118,13 +153,13 @@ Run slash commands inside the interactive TUI.
 ## 5. Common CLI Options
 
 ```bash
-ccl --help
-ccl -p "task" --model sonnet --effort high
-ccl -p "task" --allowedTools "Bash(git:*) Edit"
-ccl -p "task" --disallowedTools "Bash(rm:*)"
-ccl --bare -p "minimal startup task"
-ccl --resume <SESSION_ID>
-ccl --continue
+margay --help
+margay -p "task" --model sonnet --effort high
+margay -p "task" --allowedTools "Bash(git:*) Edit"
+margay -p "task" --disallowedTools "Bash(rm:*)"
+margay --bare -p "minimal startup task"
+margay --resume <SESSION_ID>
+margay --continue
 ```
 
 Important safety options:
@@ -139,10 +174,10 @@ Important safety options:
 ## 6. Workflows
 
 ```bash
-ccl workflow validate <name-or-path>
-ccl workflow run <name-or-path> --json
-ccl workflow run <name-or-path> --dry-run
-ccl workflow generate "produce a release audit workflow"
+margay workflow validate <name-or-path>
+margay workflow run <name-or-path> --json
+margay workflow run <name-or-path> --dry-run
+margay workflow generate "produce a release audit workflow"
 ```
 
 Inside CCL:
@@ -177,10 +212,18 @@ embedding CCL in a host process.
 
 ## 8. Troubleshooting
 
+For recovery prompts and SDK outcomes, see the
+[recovery guide](./docs/error-recovery-usage.md). Short, low-risk repairs can
+proceed within existing permissions. A recovery that needs your consent waits
+for approval; declining or cancelling leaves that action unperformed. In
+headless mode, `needs_user` means user intervention is needed before continuing.
+
 | Symptom | Fix |
 |---|---|
-| Gateway login worked but a new shell uses the old gateway | Check exported `CCL_GATEWAY_URL` and `CCL_GATEWAY_KEY`, then reload shell rc or unset old variables |
-| No credentials found | Use `/login`, `/gateway login`, or set `ANTHROPIC_API_KEY` |
+| Gateway login worked but a new shell uses the old gateway | Check and clear or update all four exported Gateway fields |
+| No credentials found | Margay: `/gateway login`; Claude: `/login` or `ANTHROPIC_API_KEY` |
+| Persistent network, authentication, or account-credit failure | Follow the reported `blocked_external` reason; restore access or credit, then continue after checking prior tool results |
+| Output budget lower than configured | The observed gateway/model ceiling clamps output tokens; this is separate from account credit |
 | Model unavailable | Use `/model` to inspect configured options or check the gateway model list |
 | Automation loops too long | Set `--max-turns`, `--max-budget-usd`, or `CCL_PRINT_MAX_TURNS` |
 | Tool calls need policy control | Use CLI allow/deny options or the SDK `canUseTool` callback |

package/README.md

@@ -5,17 +5,22 @@ interactive coding assistant by default, supports non-interactive scripting with
 `--print`, and can run either direct Claude channels or Margay gateway routed
 models from the same CLI surface.
 
-Current package version: **1.3.1**.
+The package version is recorded in `package.json`. Check the installed runtime
+with `--version`; a source checkout and an installed npm package can differ.
 
 This file is the public package entry point. The full authoritative
 documentation index is [docs/index.md](./docs/index.md), and the fast path for
 new users is [QUICKSTART.md](./QUICKSTART.md).
 
+## Local analytics preview
+
+The analytics commands support opt-in event upload, funnel/retention/path/experiment queries and local/remote control of `analytics.query`. See the [analytics user guide](docs/local-analytics-quickstart.md) for viewing events, switches, account prerequisites and troubleshooting, and the [event/query contract](docs/self-hosted-product-events.md) for supported data and limits.
+
 ## Requirements
 
 - Node.js 20 or newer.
 - At least one authentication path:
-  - Margay gateway token for gateway-routed models.
+  - Margay website account or gateway token for gateway-routed models.
   - Claude OAuth for subscription-backed Claude use.
   - Anthropic API key for direct API-key Claude use.
 
@@ -23,10 +28,15 @@ new users is [QUICKSTART.md](./QUICKSTART.md).
 
 ```bash
 npm install -g @margay/ccl-core
-ccl --version
-# 1.3.1 (CCL)
+margay --version
+# Prints the installed version; npm uses the published default tag.
 ```
 
+Starting with `1.4.5-rc.10`, the package registers both `ccl` and `margay` for the
+same CLI. The `1.4.5-rc.9` package registers only `margay`.
+For installation scope, dual-entry verification and old
+launcher migration, see [CLI installation and upgrades](docs/cli-installation.md).
+
 From a source checkout:
 
 ```bash
@@ -38,18 +48,18 @@ node dist/cli.js --version
 ## Start A Session
 
 ```bash
-ccl
-ccl "review the current git diff"
-ccl --model deepseek-v4-pro
-ccl --cwd /path/to/project
+margay
+margay "review the current git diff"
+margay --model deepseek-v4-pro
+margay --cwd /path/to/project
 ```
 
 Use `--print` for scripts and pipelines:
 
 ```bash
-ccl -p "explain this stack trace" < error.log
-ccl -p "return JSON only" --output-format json
-ccl -p "stream events" --output-format stream-json
+margay -p "explain this stack trace" < error.log
+margay -p "return JSON only" --output-format json
+margay -p "stream events" --output-format stream-json --verbose
 ```
 
 ## Authentication
@@ -59,16 +69,23 @@ configuration.
 
 | Channel | Use For | Setup |
 |---|---|---|
-| Margay gateway | DeepSeek, Kimi, GLM, gateway-managed Claude or OpenAI-compatible models | In CCL, run `/gateway register <url> <invite>` or `/gateway login <url> <token>` |
-| Claude OAuth | Claude subscription sessions | Run `ccl` and follow the login prompt, or use `/login` |
+| Margay website account (current checkout) | Shared Margay identity and gateway-routed models | Build this checkout, then `node dist/cli.js login`, or use `/gateway login` in the TUI |
+| Manual Margay gateway | Existing gateway tokens or invite codes | `/gateway login <url> <token>` or `/gateway register <url> <invite>` |
+| Claude OAuth | Claude subscription sessions | Run `margay` and follow the login prompt, or use `/login` |
 | Anthropic API key | Direct Anthropic API use | Set `ANTHROPIC_API_KEY=<key>` or pass `--api-key <key>` |
 
-Gateway configuration is saved to `~/.ccl/gateway.json`. CCL records the
-credential type and binds it to the normalized Gateway URL. `/gateway register`
-accepts only the returned Gateway JWT and verifies it with the same Gateway's
-`/auth/me`; `/gateway login` verifies a Gateway-owned credential before saving
-it. Do not paste an upstream model-provider API key into either command or into
-`CCL_GATEWAY_KEY`.
+The website-account implementation is available in this source checkout; real
+website authorization and commercial readiness remain unverified. No published
+release is claimed here. It opens `https://margay-ai.com` for login/registration,
+verifies the returned identity with the selected gateway, and stores credentials
+in the system credential store. `~/.ccl/gateway.json` holds the website account's
+reference and metadata, without its token. A locked/unavailable store fails
+closed. An explicit config directory changes this file location.
+
+The manual token/invite paths retain their existing configuration storage.
+They verify a Gateway credential using `/auth/me` before saving it; do not
+supply an upstream model-provider API key. A saved website account must be
+logged out before replacement with a manual credential.
 
 If a parent terminal explicitly exports a Gateway configuration, use all four
 variables as one atomic set: `CCL_GATEWAY_URL`, `CCL_GATEWAY_KEY`,
@@ -81,6 +98,8 @@ quarantines untyped opaque or issuer-mismatched credentials before any request.
 Run these inside an interactive CCL session:
 
 ```text
+/gateway login
+/gateway register
 /gateway register <url> <invite_code> [username] [email] [phone]
 /gateway login    <url> <token>
 /gateway status
@@ -88,15 +107,26 @@ Run these inside an interactive CCL session:
 /gateway logout
 ```
 
-`/gateway login` validates the gateway before writing local state. The current
-health check uses the gateway auth/status endpoints implemented by the active
-gateway; do not use legacy intent-classifier guides as setup instructions.
+With no arguments, `login` and `register` open website authorization. With a
+URL/token or URL/invite, they use the existing manual flow. `/login` remains
+Claude OAuth. Website sign-out removes the local account; it does not revoke
+the website session or cancel a subscription. Explicit environment overrides
+remain effective until removed from the launching shell.
+
+Shell account commands in the current source build:
+
+```bash
+node dist/cli.js login
+node dist/cli.js account status
+node dist/cli.js logout
+```
 
-More detail: [docs/gateway-quickstart.md](./docs/gateway-quickstart.md).
+For account switching, test endpoints, membership/credit status, and error
+recovery, see [docs/gateway-quickstart.md](./docs/gateway-quickstart.md).
 
 ## CLI Surface
 
-`ccl --help` is the exact runtime source for command-line behavior. The current
+`margay --help` is the exact runtime source for command-line behavior. The current
 top-level commands are:
 
 | Command | Purpose |
@@ -162,13 +192,16 @@ defines these public command families:
 
 Use `/help` in the TUI for command availability in the current build.
 
-### Duo collaboration (development branch)
+### Duo collaboration (reviewed local candidate)
 
-Use `/duo-agent` (alias `/duo`) to enter standby, then configure
-`/duo --reviewer-model <fixed-model-id>` and provide a task. Duo supports code,
-plans and documents, with independent review, executor counter-review and user
-pause/resume controls. See the [Duo guide](docs/ccl-duo-agent.md) for examples.
-Runtime acceptance is in progress; the installed CLI has not been updated.
+Use `/duo-agent` (alias `/duo`) to enter standby, then provide a task. The
+reviewed candidate resolves Auto execution and critic roles to two distinct
+concrete models. `/model` and `/duo --reviewer-model <fixed-model-id>` can
+override a role. Completion requires actual requests from both models, a
+current review and executor acceptance; accepted tasks return to standby for
+the next task, and `/duo exit` releases input even if cleanup fails. See the
+[Duo guide](docs/ccl-duo-agent.md). This candidate is not yet on npm `next`;
+RC8/RC10/C790 release acceptance remains on HOLD.
 
 ### Lightweight peer development and review
 
@@ -183,7 +216,9 @@ messages. The reviewer tests an independent copy of each submission; only its
 approval of the current content completes the protected task. Disagreements,
 cancellation and exhausted limits remain unfinished. Both models are fixed for
 the pair; automatic routing aliases are rejected. Ordinary `/buddy` and Team
-usage remain available.
+usage remain available. Ordinary `/buddy` first creates or reuses a Team, then
+starts Agent with the team name actually returned by TeamCreate. Its prompt
+alone does not prove the teammate started.
 
 The current mode requires a Git working directory and runs in one CCL interface.
 Copies isolate normal test output, not hostile same-user shell commands. See
@@ -207,8 +242,8 @@ Useful controls:
 For one-off runs:
 
 ```bash
-ccl -p "summarize this diff" --model sonnet
-ccl -p "generate a migration plan" --model deepseek-v4-pro --effort high
+margay -p "summarize this diff" --model sonnet
+margay -p "generate a migration plan" --model deepseek-v4-pro --effort high
 ```
 
 Capability pools use explicit `cost-first ranking` and `quality-first ranking`
@@ -231,11 +266,11 @@ The `workflow` command and `/workflows` slash command run multi-step task
 automation.
 
 ```bash
-ccl workflow run <name-or-path>
-ccl workflow run <name-or-path> --params '{"out":"report.md"}' --json
-ccl workflow run <name-or-path> --dry-run
-ccl workflow validate <name-or-path>
-ccl workflow generate "create a regression audit workflow"
+margay workflow run <name-or-path>
+margay workflow run <name-or-path> --params '{"out":"report.md"}' --json
+margay workflow run <name-or-path> --dry-run
+margay workflow validate <name-or-path>
+margay workflow generate "create a regression audit workflow"
 ```
 
 Inside the TUI:
@@ -275,6 +310,25 @@ SDK references:
 - [sdk/README.md](./sdk/README.md)
 - [sdk/API.md](./sdk/API.md)
 
+## Recovery And User Intervention
+
+The agent is instructed to investigate and verify short, low-risk repairs within
+its existing authority, then report the outcome. Long, uncertain, sensitive, or
+experience-changing repairs require consent. Runtime recovery prompts offer
+**Keep current settings** or **Approve this recovery**; cancellation does not
+approve the action. Existing tool permissions still apply.
+
+Persistent network, authentication, or account-credit failures stop with an
+actionable request for help. Output-token limits are handled separately from
+account credit: known gateway limits clamp requests, while recovery that raises
+an output budget or disables reasoning requires consent.
+
+In `--print` and SDK mode, runtime recovery proposals that require interaction
+end with `recovery.status = needs_user`. External blockers use `blocked_external`.
+A terminal result does not imply the task succeeded. See the
+[recovery guide](./docs/error-recovery-usage.md) for user actions, fallback rules,
+and the SDK distinction between recovery outcomes and pending tool approvals.
+
 ## Configuration And Environment
 
 | Variable | Purpose |
@@ -282,6 +336,7 @@ SDK references:
 | `CCL_GATEWAY_URL`, `CCL_GATEWAY_KEY` | Margay gateway URL and credential; prefer `/gateway login` over manual export |
 | `CCL_GATEWAY_CREDENTIAL_TYPE`, `CCL_GATEWAY_ISSUER` | Credential admission metadata; required as an atomic pair for opaque environment credentials |
 | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | Direct Anthropic API-key channel |
+| `CCL_MAX_OUTPUT_TOKENS` | Output budget; takes precedence over `CLAUDE_CODE_MAX_OUTPUT_TOKENS` and remains subject to model/gateway limits |
 | `CCL_MODEL` | Default model |
 | `CCL_ROUTING_PRIORITY` | Default routing preference, usually `cost` or `quality` |
 | `CCL_PRINT_MAX_TURNS` | Default `--max-turns` for `--print` |
@@ -314,12 +369,12 @@ Config locations:
 
 | Symptom | Check |
 |---|---|
-| `ccl` cannot authenticate | Run `/doctor`, `/gateway doctor`, or `/login` |
+| `margay` cannot authenticate | Run `/doctor`, `/gateway doctor`, or `/login` |
 | Gateway status differs between shells | Check exported `CCL_GATEWAY_URL` and `CCL_GATEWAY_KEY` versus `~/.ccl/gateway.json` |
 | A model name fails | Run `/model` or query the gateway's model list |
 | `--print` runs too long | Set `--max-turns`, `--max-budget-usd`, or `CCL_PRINT_MAX_TURNS` |
 | Tool permission prompts block automation | Use `--allowedTools`, `--disallowedTools`, `--permission-mode`, or the SDK `canUseTool` callback |
-| MCP servers behave unexpectedly | Run `ccl doctor` from a trusted directory and inspect `--mcp-config` inputs |
+| MCP servers behave unexpectedly | Run `margay doctor` from a trusted directory and inspect `--mcp-config` inputs |
 
 ## Source Of Truth
 
@@ -329,9 +384,11 @@ The current authoritative documentation set is:
 - [QUICKSTART.md](./QUICKSTART.md): shortest working setup.
 - [docs/index.md](./docs/index.md): official documentation information architecture.
 - [docs/gateway-quickstart.md](./docs/gateway-quickstart.md): current gateway setup.
+- [docs/error-recovery-usage.md](./docs/error-recovery-usage.md): recovery and user intervention.
+- [docs/releases/1.4.5-rc.4.md](./docs/releases/1.4.5-rc.4.md): candidate delivery and validation boundaries.
 - [sdk/README.md](./sdk/README.md) and [sdk/API.md](./sdk/API.md): SDK contract.
-- [docs/official-docs-coverage-matrix.json](./docs/official-docs-coverage-matrix.json):
-  inventory and classification matrix for current and historical docs.
+- `docs/official-docs-coverage-matrix.json` (source checkout only): historical
+  inventory snapshot; not certification of this candidate.
 
 ### Project instructions