@margay/ccl-core 1.5.1-alpha.4 → 1.5.1-alpha.6

package/QUICKSTART.md

@@ -7,13 +7,15 @@ from an npm package or source checkout. For the full feature map, see [README.md
 ## 1. Install
 
 ```bash
-npm install -g @margay/ccl-core
-margay --version
-# Prints the installed version; npm uses the published default tag.
+npm install -g @margay/ccl-core@1.5.1-alpha.6
+ccl --version
+# Expected: 1.5.1-alpha.6 (CCL); the latest tag is unchanged.
 ```
 
-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`.
+Starting with `1.5.1-alpha.6`, this package provides only `ccl`. Upgrade older
+dual-entry CCL packages before installing the independent `@margay/cli`, which
+will provide `margay` on the 1.8 cleanhouse line. Existing CCL scripts should use
+`ccl`; old documentation using the former alias refers to that same CCL command.
 See [CLI installation and upgrades](docs/cli-installation.md) for local
 versus global installation and migration of older launchers.
 
@@ -27,7 +29,7 @@ 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).
+Use `ccl analytics status` to inspect collection and `ccl 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
 
@@ -53,7 +55,7 @@ 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.
+later; Esc cancels an in-progress TUI login. `/login` opens the same Margay website flow.
 
 Website credentials use the system credential store; `gateway.json` contains
 an account reference and metadata. Store access failure stops login without
@@ -66,7 +68,7 @@ saved session. To sign out from a shell, use `node dist/cli.js logout`.
 These existing TUI paths remain available:
 
 ```text
-margay
+ccl
 /gateway login <GATEWAY_URL> <GATEWAY_TOKEN>
 /gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
 /gateway register --invite <INVITE_CODE>
@@ -84,20 +86,22 @@ explicit environment override. See the
 [account and gateway guide](./docs/gateway-quickstart.md) for defaults,
 status meanings, storage prerequisites, and troubleshooting.
 
-### Claude OAuth
+### Interactive account login
 
 ```text
-margay
+ccl
 /login
 ```
 
-The first interactive launch can also guide you through OAuth login.
+This signs in to your Margay website account. First-launch account setup uses
+the same flow. `/login` does not obtain external-service credentials; existing credentials
+may still be used by compatible channels, but are not created by this command.
 
-### Anthropic API Key
+### Messages API Key
 
 ```bash
 export ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
-margay --model sonnet
+ccl --model "<available-model-id>"
 ```
 
 Do not paste real keys into docs, shell history examples, bug reports, or shared
@@ -108,23 +112,23 @@ screenshots.
 Interactive:
 
 ```bash
-margay
-margay --model deepseek-v4-pro
-margay --cwd /path/to/project
+ccl
+ccl --model deepseek-v4-pro
+ccl --cwd /path/to/project
 ```
 
 One-shot:
 
 ```bash
-margay -p "explain this error" < error.log
-margay -p "summarize the current repository" --max-turns 20
-margay -p "return JSON" --output-format json
+ccl -p "explain this error" < error.log
+ccl -p "summarize the current repository" --max-turns 20
+ccl -p "return JSON" --output-format json
 ```
 
 Streaming automation:
 
 ```bash
-margay -p "run a compact audit" --output-format stream-json --verbose
+ccl -p "run a compact audit" --output-format stream-json --verbose
 ```
 
 ## 4. Useful First Slash Commands
@@ -153,13 +157,13 @@ Run slash commands inside the interactive TUI.
 ## 5. Common CLI Options
 
 ```bash
-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
+ccl --help
+ccl -p "task" --model "<available-model-id>" --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
 ```
 
 Important safety options:
@@ -174,10 +178,10 @@ Important safety options:
 ## 6. Workflows
 
 ```bash
-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"
+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"
 ```
 
 Inside CCL:
@@ -221,7 +225,7 @@ 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 and clear or update all four exported Gateway fields |
-| No credentials found | Margay: `/gateway login`; Claude: `/login` or `ANTHROPIC_API_KEY` |
+| No credentials found | Margay: `/login` or `/gateway login`; direct Messages API: `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 |

package/README.md

@@ -2,7 +2,7 @@
 
 CCL is the `@margay/ccl-core` command-line agent runtime. It starts an
 interactive coding assistant by default, supports non-interactive scripting with
-`--print`, and can run either direct Claude channels or Margay gateway routed
+`--print`, and can run either direct API channels or Margay gateway routed
 models from the same CLI surface.
 
 The package version is recorded in `package.json`. Check the installed runtime
@@ -18,23 +18,25 @@ The analytics commands support opt-in event upload, funnel/retention/path/experi
 
 ## Requirements
 
-- Node.js 20 or newer.
+- Node.js 22.19.0 or newer.
 - At least one authentication path:
   - 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.
+  - Existing external-service OAuth credentials for compatible subscription-backed channels; `/login` signs in to Margay.
+  - API key for a compatible Messages API service.
 
 ## Install
 
 ```bash
-npm install -g @margay/ccl-core
-margay --version
-# Prints the installed version; npm uses the published default tag.
+npm install -g @margay/ccl-core@1.5.1-alpha.6
+ccl --version
+# Expected: 1.5.1-alpha.6 (CCL); the latest tag is unchanged.
 ```
 
-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
+Starting with `1.5.1-alpha.6`, this package provides only `ccl`. Upgrade older
+dual-entry CCL packages before installing the independent `@margay/cli`, which
+will provide `margay` on the 1.8 cleanhouse line. Existing CCL scripts should use
+`ccl`; old documentation using the former alias refers to that same CCL command.
+For installation scope, command ownership and old
 launcher migration, see [CLI installation and upgrades](docs/cli-installation.md).
 
 From a source checkout:
@@ -48,18 +50,18 @@ node dist/cli.js --version
 ## Start A Session
 
 ```bash
-margay
-margay "review the current git diff"
-margay --model deepseek-v4-pro
-margay --cwd /path/to/project
+ccl
+ccl "review the current git diff"
+ccl --model deepseek-v4-pro
+ccl --cwd /path/to/project
 ```
 
 Use `--print` for scripts and pipelines:
 
 ```bash
-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
+ccl -p "explain this stack trace" < error.log
+ccl -p "return JSON only" --output-format json
+ccl -p "stream events" --output-format stream-json --verbose
 ```
 
 ## Authentication
@@ -69,10 +71,10 @@ configuration.
 
 | Channel | Use For | Setup |
 |---|---|---|
-| 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 |
+| Margay website account | Shared Margay identity and gateway-routed models | `ccl login`, or `/login` / `/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>` |
+| Existing external-service OAuth credentials | Compatible external-service channels | Legacy credential compatibility; `/login` and first-launch onboarding use Margay website authorization |
+| Messages API key | Direct API use | Set `ANTHROPIC_API_KEY=<key>` or pass `--api-key <key>` |
 
 The website-account implementation is available in this source checkout; real
 website authorization and commercial readiness remain unverified. No published
@@ -108,8 +110,8 @@ Run these inside an interactive CCL session:
 ```
 
 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
+URL/token or URL/invite, they use the existing manual flow. `/login` opens
+the same Margay website authorization flow. 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.
 
@@ -126,7 +128,7 @@ recovery, see [docs/gateway-quickstart.md](./docs/gateway-quickstart.md).
 
 ## CLI Surface
 
-`margay --help` is the exact runtime source for command-line behavior. The current
+`ccl --help` is the exact runtime source for command-line behavior. The current
 top-level commands are:
 
 | Command | Purpose |
@@ -226,9 +228,9 @@ Copies isolate normal test output, not hostile same-user shell commands. See
 
 ## Models And Routing
 
-CCL accepts model aliases such as `sonnet` or `opus` and gateway model names such
-as `deepseek-v4-pro` or `kimi-for-coding`. The actual available gateway models
-are determined by the connected gateway.
+Use `/model` to inspect the models available in your current configuration.
+Choose a model ID from that list for an explicit `--model` invocation. The
+connected gateway determines its available model catalog.
 
 Useful controls:
 
@@ -242,8 +244,8 @@ Useful controls:
 For one-off runs:
 
 ```bash
-margay -p "summarize this diff" --model sonnet
-margay -p "generate a migration plan" --model deepseek-v4-pro --effort high
+ccl -p "summarize this diff" --model "<available-model-id>"
+ccl -p "generate a migration plan" --model "<available-model-id>" --effort high
 ```
 
 Capability pools use explicit `cost-first ranking` and `quality-first ranking`
@@ -253,7 +255,7 @@ Qwen 3.8 Flash → Grok 4.5 → K3 / Moonshot Platform. DeepSeek Vision remains
 experimental. The hidden K3 visual route is reported as canonical model
 `kimi-platform/kimi-k3`.
 
-Anthropic Messages remains the transport for the main Agent, planning, editing,
+The Messages API remains the transport for the main Agent, planning, editing,
 tool calling, Advisor, Critic, and general subagent loops. Native OpenAI Chat
 Completions support is deliberately bounded to zero-tool, one-shot visual
 analysis and context compaction. These consumers select and pin one configured
@@ -266,11 +268,11 @@ The `workflow` command and `/workflows` slash command run multi-step task
 automation.
 
 ```bash
-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"
+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"
 ```
 
 Inside the TUI:
@@ -335,7 +337,7 @@ and the SDK distinction between recovery outcomes and pending tool approvals.
 |---|---|
 | `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 |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | Direct Messages API 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` |
@@ -369,12 +371,12 @@ Config locations:
 
 | Symptom | Check |
 |---|---|
-| `margay` cannot authenticate | Run `/doctor`, `/gateway doctor`, or `/login` |
+| `ccl` 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 `margay doctor` from a trusted directory and inspect `--mcp-config` inputs |
+| MCP servers behave unexpectedly | Run `ccl doctor` from a trusted directory and inspect `--mcp-config` inputs |
 
 ## Source Of Truth
 
@@ -392,6 +394,6 @@ The current authoritative documentation set is:
 
 ### Project instructions
 
-Margay automatically loads `CCL.md`, `.ccl/CCL.md`, `CCL.local.md`, and `.ccl/rules/**/*.md`, respecting the existing scope, exclusions, and conditional rules. Project and local instructions are included by default.
+CCL automatically loads `CCL.md`, `.ccl/CCL.md`, `CCL.local.md`, and `.ccl/rules/**/*.md`, respecting the existing scope, exclusions, and conditional rules. Project and local instructions are included by default.
 
 `CLAUDE.md`, `CLAUDE.local.md`, `.ccl/CLAUDE.md`, and `.claude/rules/` are not discovered automatically, even when no CCL file exists. To share a document deliberately, import it from `CCL.md` with `@CLAUDE.md`; normal import permissions still apply. Explicit file reads and existing conversation history remain available.