@margay/ccl-core 1.3.5-rc.6

package/INTENT-GATEWAY-GUIDE.md

@@ -0,0 +1,82 @@
+# Legacy Intent Gateway Guide
+
+This page is retained only as a historical migration note. It is **not** the
+current CCL gateway setup guide.
+
+Current setup lives in:
+
+- [README.md](./README.md)
+- [QUICKSTART.md](./QUICKSTART.md)
+- [docs/gateway-quickstart.md](./docs/gateway-quickstart.md)
+
+## Current Status
+
+CCL `1.3.1` uses the Margay gateway connection managed by the `/gateway`
+commands:
+
+```text
+/gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
+/gateway login    <GATEWAY_URL> <GATEWAY_TOKEN>
+/gateway doctor
+/gateway status
+/gateway logout
+```
+
+The current public docs must not publish real gateway IP addresses, production
+tokens, shared test tokens, or administrator credentials. Use placeholders such
+as `<GATEWAY_URL>` and `<GATEWAY_TOKEN>` in all examples.
+
+## What Changed
+
+Older internal guides described a dedicated intent-classification gateway path
+and direct VPS port usage. Those instructions are no longer the official setup
+path for CCL users.
+
+Current user-facing setup should instead rely on:
+
+1. `/gateway register` for first-time invite-based registration.
+2. `/gateway login` for existing gateway credentials or endpoint switching.
+3. `/gateway doctor` for reachability and configuration diagnosis.
+4. `/model`, `/endpoint`, `/priority`, and `/effort` for runtime model control.
+
+## Migration Guidance
+
+If you find an old runbook telling users to:
+
+- export a concrete gateway IP address,
+- paste a shared key into shell rc files,
+- call a legacy intent-classification endpoint directly,
+- use admin credentials in local examples,
+- or set `ANTHROPIC_BASE_URL` as the gateway path for all traffic,
+
+treat that runbook as stale. Replace it with the current `/gateway` command
+flow and safe placeholders.
+
+## Verification Checklist
+
+For a current gateway setup:
+
+```text
+/gateway doctor
+/gateway status
+/model
+```
+
+For source checkout validation:
+
+```bash
+node dist/cli.js --version
+node dist/cli.js --help
+```
+
+Expected version output:
+
+```text
+1.3.1 (CCL)
+```
+
+## Documentation Policy
+
+This file intentionally avoids concrete production addresses, concrete tokens,
+and legacy endpoint strings. It exists to prevent users and guide agents from
+following obsolete setup instructions.

package/QUICKSTART.md

@@ -0,0 +1,188 @@
+# 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
+[docs/index.md](./docs/index.md).
+
+## 1. Install
+
+```bash
+npm install -g @margay/ccl-core
+ccl --version
+# 1.3.1 (CCL)
+```
+
+From a source checkout:
+
+```bash
+npm install
+npm run build
+node dist/cli.js --version
+```
+
+## 2. Choose Authentication
+
+Use one of these paths.
+
+### Margay Gateway
+
+Use this path for gateway-routed models such as DeepSeek, Kimi, GLM, or any
+model exposed by your Margay gateway.
+
+```text
+ccl
+/gateway register <GATEWAY_URL> <INVITE_CODE> [username] [email] [phone]
+```
+
+If you already have a token:
+
+```text
+ccl
+/gateway login <GATEWAY_URL> <GATEWAY_TOKEN>
+/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.
+
+### Claude OAuth
+
+```text
+ccl
+/login
+```
+
+The first interactive launch can also guide you through OAuth login.
+
+### Anthropic API Key
+
+```bash
+export ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
+ccl --model sonnet
+```
+
+Do not paste real keys into docs, shell history examples, bug reports, or shared
+screenshots.
+
+## 3. Run CCL
+
+Interactive:
+
+```bash
+ccl
+ccl --model deepseek-v4-pro
+ccl --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
+```
+
+Streaming automation:
+
+```bash
+ccl -p "run a compact audit" --output-format stream-json
+```
+
+## 4. Useful First Slash Commands
+
+Run slash commands inside the interactive TUI.
+
+| Command | Purpose |
+|---|---|
+| `/help` | Show commands available in this build |
+| `/doctor` | Diagnose local installation and settings |
+| `/gateway doctor` | Diagnose gateway config and reachability |
+| `/model` | View or switch the active model |
+| `/priority quality` | Prefer stronger models where routing supports it |
+| `/priority cost` | Prefer lower-cost models where routing supports it |
+| `/effort high` | Increase reasoning effort for the current session |
+| `/add-dir <path>` | Add another directory to tool scope |
+| `/permissions` | Manage tool permission rules |
+| `/compact` | Compress conversation context |
+| `/resume` | Resume an earlier conversation |
+| `/workflows` | List, create, inspect, or tail workflows |
+| `/mcp` | Manage MCP servers |
+| `/skills` | List available skills |
+| `/status` | Show current session state |
+| `/exit` | Exit the 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
+```
+
+Important safety options:
+
+| Option | Use |
+|---|---|
+| `--allowedTools` | Limit automation to known-safe tools |
+| `--disallowedTools` | Block dangerous tools or patterns |
+| `--permission-mode plan` | Ask the model to plan before edits |
+| `--dangerously-skip-permissions` | Only for isolated sandboxes |
+
+## 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"
+```
+
+Inside CCL:
+
+```text
+/workflows
+/workflows new <goal>
+/workflows --tail [runId]
+/workflows --inspect [runId]
+```
+
+## 7. SDK Quick Start
+
+```ts
+import { query, resumeWithDecision } from '@margay/ccl-core/sdk'
+
+for await (const event of query('audit this workspace', {
+  cwd: '/srv/workspace',
+  model: 'deepseek-v4-pro',
+  maxTurns: 30,
+  canUseTool: async (toolName) =>
+    toolName === 'Bash' ? { behavior: 'pending' } : { behavior: 'allow' },
+})) {
+  if (event.type === 'suspended') {
+    // Persist approval UI state, then later call resumeWithDecision(...)
+  }
+}
+```
+
+Read [sdk/README.md](./sdk/README.md) and [sdk/API.md](./sdk/API.md) before
+embedding CCL in a host process.
+
+## 8. Troubleshooting
+
+| 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` |
+| 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 |
+
+For the full authoritative docs set, start at [docs/index.md](./docs/index.md).

package/README.md

@@ -0,0 +1,286 @@
+# CCL
+
+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
+models from the same CLI surface.
+
+Current package version: **1.3.1**.
+
+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).
+
+## Requirements
+
+- Node.js 20 or newer.
+- At least one authentication path:
+  - Margay gateway token for gateway-routed models.
+  - Claude OAuth for subscription-backed Claude use.
+  - Anthropic API key for direct API-key Claude use.
+
+## Install
+
+```bash
+npm install -g @margay/ccl-core
+ccl --version
+# 1.3.1 (CCL)
+```
+
+From a source checkout:
+
+```bash
+npm install
+npm run build
+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
+```
+
+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
+```
+
+## Authentication
+
+CCL can use multiple channels. Environment variables override saved gateway
+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` |
+| 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` and synchronized into a
+managed shell rc block by `/gateway login` and `/gateway register`. If a parent
+terminal already exported `CCL_GATEWAY_URL` or `CCL_GATEWAY_KEY`, that terminal's
+environment still wins for newly launched child processes. Use `/gateway doctor`
+to detect mismatches, then open a new terminal, reload the shell rc file, or
+unset the old variables.
+
+## Gateway Commands
+
+Run these inside an interactive CCL session:
+
+```text
+/gateway register <url> <invite_code> [username] [email] [phone]
+/gateway login    <url> <token>
+/gateway status
+/gateway doctor
+/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.
+
+More detail: [docs/gateway-quickstart.md](./docs/gateway-quickstart.md).
+
+## CLI Surface
+
+`ccl --help` is the exact runtime source for command-line behavior. The current
+top-level commands are:
+
+| Command | Purpose |
+|---|---|
+| `agents` | List configured agents |
+| `auth` | Manage authentication |
+| `doctor` | Check installation and updater health |
+| `install` | Install a CCL native build |
+| `mcp` | Configure and manage MCP servers |
+| `plugin`, `plugins` | Manage CCL plugins |
+| `setup-token` | Set up a long-lived authentication token |
+| `update`, `upgrade` | Check for updates and install if available |
+| `workflow` | Run and manage workflows |
+
+Common global options:
+
+| Option | Purpose |
+|---|---|
+| `-p`, `--print` | Non-interactive mode for scripts and pipes |
+| `--output-format text|json|stream-json` | Select non-interactive output format |
+| `--input-format text|stream-json` | Select non-interactive input format |
+| `--model <model>` | Pick a model alias or full model name |
+| `--effort low|medium|high|max` | Set reasoning effort |
+| `--fallback-model <model>` | Fallback model for `--print` overload handling |
+| `--max-turns <n>` | Limit agentic turns in `--print`; `0` means unlimited |
+| `--max-budget-usd <amount>` | Stop before a non-interactive run exceeds a budget |
+| `--cwd <path>` | Change working directory and add it to tool scope |
+| `--add-dir <path...>` | Add extra directories to tool scope |
+| `--allowedTools <tools...>` | Allow specific tools or tool patterns |
+| `--disallowedTools <tools...>` | Deny specific tools or tool patterns |
+| `--permission-mode <mode>` | Use `default`, `acceptEdits`, `dontAsk`, `plan`, or `bypassPermissions` |
+| `--dangerously-skip-permissions` | Bypass permission checks; only use in isolated sandboxes |
+| `--bare` | Minimal startup without hooks, LSP, plugin sync, keychain reads, or auto memory |
+| `--mcp-config <file-or-json...>` | Load MCP servers from JSON files or JSON strings |
+| `--plugin-dir <path>` | Load plugins from explicit directories |
+| `-c`, `--continue` | Continue the latest conversation for the current directory |
+| `-r`, `--resume [id]` | Resume a conversation by session id or picker |
+| `--fork-session` | Resume into a new session id |
+| `--session-id <uuid>` | Force a specific session id |
+| `--worktree [name]` | Create a git worktree for the session |
+| `--tmux` | Create a tmux session for a worktree |
+| `--debug [filter]`, `--debug-file <path>` | Enable debug logging |
+
+## Interactive Slash Commands
+
+Slash commands are available inside the interactive TUI. Some commands may be
+hidden by feature gates or environment constraints, but the current source tree
+defines these public command families:
+
+| Area | Commands |
+|---|---|
+| Help and session state | `/help`, `/status`, `/version`, `/doctor`, `/context`, `/cost`, `/usage`, `/stats`, `/extra-usage`, `/rate-limit-options` |
+| Authentication and gateway | `/login`, `/logout`, `/gateway`, `/endpoint`, `/priority`, `/model`, `/effort`, `/advisor` |
+| Conversation control | `/resume`, `/continue`, `/sessions`, `/compact`, `/rewind`, `/checkpoint`, `/clear`, `/reset`, `/new`, `/rename`, `/tag`, `/exit`, `/quit` |
+| Workspaces and files | `/add-dir`, `/files`, `/diff`, `/copy`, `/export`, `/branch`, `/fork`, `/tasks`, `/bashes` |
+| Planning and goals | `/plan`, `/goal`, `/loop`, `/brief` |
+| Automation and workflows | `/workflows`, `/mcp`, `/skills`, `/plugin`, `/plugins`, `/reload-plugins`, `/hooks` |
+| Agents and collaboration | `/agents`, `/buddy`, `/peers`, `/remote-control`, `/rc`, `/session`, `/remote`, `/remote-env` |
+| Review and GitHub | `/review`, `/ultrareview`, `/security-review`, `/pr-comments`, `/commit`, `/commit-push-pr` |
+| UI and integrations | `/theme`, `/color`, `/vim`, `/keybindings`, `/ide`, `/chrome`, `/desktop`, `/app`, `/mobile`, `/ios`, `/android`, `/terminal-setup`, `/web-setup` |
+| Settings and privacy | `/config`, `/settings`, `/permissions`, `/allowed-tools`, `/privacy-settings`, `/memory`, `/sandbox` |
+| Diagnostics and optional utilities | `/heapdump`, `/voice`, `/feedback`, `/bug`, `/release-notes`, `/install-slack-app`, `/install-github-app`, `/stickers`, `/insights`, `/think-back`, `/thinkback-play`, `/btw`, `/fast`, `/passes`, `/init`, `/init-verifiers` |
+
+Use `/help` in the TUI for command availability in the current build.
+
+## 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.
+
+Useful controls:
+
+```text
+/model [model]
+/endpoint
+/priority [quality|cost]
+/effort [low|medium|high|max]
+```
+
+For one-off runs:
+
+```bash
+ccl -p "summarize this diff" --model sonnet
+ccl -p "generate a migration plan" --model deepseek-v4-pro --effort high
+```
+
+## Workflows
+
+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"
+```
+
+Inside the TUI:
+
+```text
+/workflows
+/workflows new <goal>
+/workflows --tail [runId]
+/workflows --inspect [runId]
+/workflows --json [runId]
+```
+
+## SDK
+
+The package exports an embeddable SDK at `@margay/ccl-core/sdk`. It runs the CLI
+as a managed subprocess and exposes stream events, permission interception,
+session resume, pending approval, and usage accumulation.
+
+```ts
+import { query, resumeWithDecision } from '@margay/ccl-core/sdk'
+
+for await (const event of query('inspect the workspace', {
+  cwd: '/srv/workspace',
+  model: 'deepseek-v4-pro',
+  maxTurns: 30,
+  canUseTool: async (toolName) =>
+    toolName === 'Bash' ? { behavior: 'pending' } : { behavior: 'allow' },
+})) {
+  if (event.type === 'suspended') {
+    // render approval UI, then later call resumeWithDecision(...)
+  }
+}
+```
+
+SDK references:
+
+- [sdk/README.md](./sdk/README.md)
+- [sdk/API.md](./sdk/API.md)
+
+## Configuration And Environment
+
+| Variable | Purpose |
+|---|---|
+| `CCL_GATEWAY_URL`, `CCL_GATEWAY_KEY` | Margay gateway URL and token |
+| `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | Direct Anthropic API-key channel |
+| `CCL_MODEL` | Default model |
+| `CCL_ROUTING_PRIORITY` | Default routing preference, usually `cost` or `quality` |
+| `CCL_PRINT_MAX_TURNS` | Default `--max-turns` for `--print` |
+| `CCL_LOG` | SDK or provider logging level |
+| `CCL_SDK_CLI_PATH` | CLI path used by the SDK |
+| `CCL_SDK_STORE_DIR` | SDK file store directory |
+
+Config locations:
+
+| Path | Purpose |
+|---|---|
+| `~/.ccl/gateway.json` | Saved gateway connection |
+| `~/.ccl/endpoints.json` | Optional endpoint definitions |
+| `~/.ccl/workflows/` | User workflow specs |
+| `~/.ccl/debug/` | Debug log files |
+| `~/.ccl/sdk-store/` | Default SDK store |
+
+## Safety Notes
+
+- Do not publish real gateway URLs, personal tokens, API keys, or shared team
+  keys in documentation.
+- Use placeholders such as `<GATEWAY_URL>`, `<GATEWAY_TOKEN>`, and
+  `<ANTHROPIC_API_KEY>`.
+- Only use `--dangerously-skip-permissions` or `--permission-mode
+  bypassPermissions` inside isolated sandboxes.
+- Treat old files under `docs/` that are not linked from [docs/index.md](./docs/index.md)
+  as historical reports, not current setup instructions.
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| `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 `ccl doctor` from a trusted directory and inspect `--mcp-config` inputs |
+
+## Source Of Truth
+
+The current authoritative documentation set is:
+
+- [README.md](./README.md): package entry point and feature map.
+- [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.
+- [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.