kino-cli 0.1.4 → 0.1.5

package/README.md

@@ -1,15 +1,447 @@
 # kino-cli
 
-kino learns a codebase and its tools, then works as one of the team's developers by running processes
-(ticket to PR, review loops, and more). It includes **kino-code**, a coding agent that runs on any model.
+kino works in your team's repository as one of its developers. It learns the codebase and the tools around it,
+answers questions about it, writes and fixes code, and runs the team's documented processes, such as ticket to
+pull request or working through review comments. It runs on the model you choose, and it asks before anything
+leaves your machine.
+
+This guide covers everything, start to finish:
+
+1. [Install](#1-install)
+2. [First start: choosing a model](#2-first-start-choosing-a-model)
+3. [The console](#3-the-console)
+4. [Approvals and modes](#4-approvals-and-modes)
+5. [Console commands and keys](#5-console-commands-and-keys)
+6. [kino-code without the console](#6-kino-code-without-the-console)
+7. [Setting kino up for a team repo](#7-setting-kino-up-for-a-team-repo)
+8. [Processes](#8-processes)
+9. [Connecting your tools](#9-connecting-your-tools)
+10. [Knowledge](#10-knowledge)
+11. [Who writes the code](#11-who-writes-the-code)
+12. [Safety](#12-safety)
+13. [Configuration reference](#13-configuration-reference)
+14. [Updating, uninstalling, troubleshooting](#14-updating-uninstalling-troubleshooting)
+
+---
+
+## 1. Install
+
+```bash
+npm i -g kino-cli                       # Node 18 or newer
+brew install dogukangun/tap/kino-cli    # or Homebrew (macOS, Linux)
+npx kino-cli                            # or try it without installing
+```
+
+Check it with `kino --version`.
+
+kino ships compiled for macOS (Apple silicon and Intel), Linux (x64 and arm64) and Windows (x64). It runs through
+[uv](https://docs.astral.sh/uv), which fetches Python 3.12 and kino's libraries on the first run and caches them,
+so the first start takes a little longer. If uv is missing, the npm package installs it. Set
+`KINO_NO_UV_INSTALL=1` to stop that, or `KINO_UV=/path/to/uv` to use a specific uv.
+
+## 2. First start: choosing a model
+
+kino needs a language model. Open it in any folder:
+
+```bash
+cd ~/code/my-project
+kino
+```
+
+The first time, kino looks at what this machine can already use and offers it:
+
+```
+╭─ Choose a model ─────────────────────────────────────────╮
+│ kino needs a model to work. Found on this machine:       │
+│ Saved for every folder; /model changes it.               │
+│                                                          │
+│   1. Claude Sonnet 5.5, with your Claude Code login      │
+│   2. Claude Opus 5.5, with your Claude Code login        │
+│   3. Another model: type provider:model                  │
+╰──────────────────────────────────────────────────────────╯
+choose 1-3 or type an option:
+```
+
+What it looks for:
+
+| Found | Offered as |
+|---|---|
+| Claude Code installed and logged in | Claude models on your Claude Code login: `claude-code:<model>` (no API key needed) |
+| Claude Code installed, logged out | "Log in to Claude Code now", which opens Claude Code's own sign-in |
+| `ANTHROPIC_API_KEY` | Claude models on that key: `anthropic:<model>` |
+| `OPENAI_API_KEY`, `GEMINI_API_KEY` or `GOOGLE_API_KEY` | that provider; you type the model id |
+| Ollama running locally | its installed models |
+
+The choice is saved for every folder, in `~/.config/kino/settings.json` (`%APPDATA%\kino\settings.json` on
+Windows). Change it any time:
+
+```bash
+kino model                                  # what kino uses now, and what this machine can run
+kino model claude-code:claude-opus-5-5      # save another one
+```
+
+In the console, `/model` opens the same picker.
+
+**Model names** are `provider:model`:
+- `claude-code:<id>`: your Claude Code login;
+- `anthropic:<id>`, `openai:<id>`, `google-gla:<id>`: an API key in the environment;
+- `ollama:<id>`: a local model;
+- any OpenAI-compatible endpoint, configured in the workspace (see [13](#13-configuration-reference)).
+
+**Which model is used**, first match wins:
+1. `--model` on the command line, or `/model` in the console;
+2. `models.default` in the repository's `.kino/config.yaml`;
+3. the `KINO_MODEL` environment variable;
+4. the saved choice;
+5. the first model found on this machine. kino prints which one it took.
+
+## 3. The console
+
+`kino` with no command opens the console in the current folder. Type what you want in plain words and press
+Enter.
+
+**Ask about the code:**
+
+```
+› Where is the cart total computed, and what does it do with discounts?
+```
+
+**Give it a task:**
+
+```
+› Cart totals ignore item quantity. Fix total() and run the tests.
+```
+
+While it works you see each step as it happens:
+
+```
+● do_task · worker
+  ⎿ search(pattern="def total", glob="*.py")
+    ✓ 84 chars
+  ⎿ read_file(path="src/shop/cart.py")
+    ✓ 14 lines
+  ⎿ edit_file(path="src/shop/cart.py", old="sum(item.price for item in items)", new="sum(item.price * i…
+```
+
+Before a file changes you see the change and decide:
+
+```
+╭─ edit src/shop/cart.py? ─────────────────────────────────╮
+│ -    subtotal = sum(item.price for item in items)        │
+│ +    subtotal = sum(item.price * item.qty for item in items)
+╰──────────────────────────────────────────────────────────╯
+a = apply every edit for the rest of this session
+Apply this edit? [y/N/a]
+```
+
+It then runs the tests and reports what it changed and how it checked, ending with `✓ done`.
+
+**It remembers the conversation.** Each new message knows the earlier ones, how they ended and which files they
+changed, so "now add a test for it" works. `/clear` starts over. `kino -c` reopens the last conversation, and
+continues a run that was waiting or had failed.
+
+**Attach files** with `@`: `explain @src/api/routes.py` (Tab completes paths). **Several lines:** Alt-Enter,
+Ctrl-J, or a `\` at the end of a line; pasting several lines also works.
+
+**The bar at the bottom** shows the model, the approval mode, and the tokens and requests used so far.
+
+**Stop and leave:**
+- Esc or Ctrl-C while kino works stops it. The run is kept, and `/resume` continues it.
+- Ctrl-C on a line you are typing clears the line.
+- To leave: type `exit` or `quit`, press Ctrl-D, or press Ctrl-C twice on an empty line.
+
+## 4. Approvals and modes
+
+- **Reading** files and searching runs without asking.
+- **Changing a file** shows the change first and asks `Apply this edit? [y/N/a]`. If you refuse, the file stays
+  as it was and kino is told.
+- **Anything that leaves your machine** is asked one call at a time: `git push`, opening or commenting on a pull
+  request, writing to a ticket or an API. It asks `Allow this one call? [y/N/a]`.
+- **`a`** allows that one kind of call for the rest of this console session only: one command (such as
+  `git push`), one API operation, or, for edits, every edit. `/permissions` shows what you allowed, and
+  `/permissions revoke <n|all>` takes it back. Nothing is remembered after you leave.
+
+Modes, changed with `/mode`:
+
+| Mode | File changes | Outward actions |
+|---|---|---|
+| `ask` (default) | shown and asked | asked |
+| `auto-edit` | shown and applied | asked |
+| `read-only` | refused | refused |
+
+Some things are never done, whatever you answer: see [Safety](#12-safety).
+
+## 5. Console commands and keys
+
+| Command | Does |
+|---|---|
+| `/help` | list the commands |
+| `/model [provider:model]` | open the model picker, or switch to that model |
+| `/mode [ask\|auto-edit\|read-only]` | show or set how changes are approved |
+| `/permissions [revoke <n\|all>]` | what you allowed this session; take it back |
+| `/diff` | `git diff` of what changed |
+| `/cost` | requests, tool calls and tokens used this session |
+| `/clear` | start a new conversation and clear the screen |
+| `/process <name> [key=value…]` | run one of the documented processes |
+| `/processes` | list the processes |
+| `/runs` | list runs and their status |
+| `/resume [id] [node=value…]` | continue a waiting or stopped run, answering its question |
+| `/ask <query>` | search what kino knows about this repo and team |
+| `/exit`, `/quit` | leave |
+
+| Key | Does |
+|---|---|
+| Enter | send |
+| Alt-Enter, Ctrl-J, `\` at line end | new line |
+| Tab | complete a command, a process name, or a path after `@` |
+| ↑ / ↓ | earlier messages |
+| Esc | stop the current run |
+| Ctrl-C | stop the run; clear the line; twice on an empty line to leave |
+| Ctrl-D | leave |
+
+The console needs a terminal. In a pipe, a script or CI, use the commands in the next sections.
+
+## 6. kino-code without the console
+
+kino-code is kino's coding agent. `kino code` gives it one task, lets it work, and exits:
+
+```bash
+kino code -p "fix the off-by-one in pagination and add a test"
+kino code -p "…" --cwd ~/code/api --model anthropic:<id> --verbose
+echo "add a --dry-run flag" | kino code
+```
+
+Nobody is there to ask, so edits are made directly (review them with `git diff`), and anything outward, such as
+push, pull requests or API writes, is refused.
+
+| Option | Meaning |
+|---|---|
+| `-p, --print <task>` | the task (read from stdin when left out) |
+| `--cwd <path>` | the repository to work in (default: here) |
+| `--model <provider:model>` | the model (default as in [2](#2-first-start-choosing-a-model)) |
+| `--verbose` | show the steps and tool calls as they happen (on stderr) |
+| `--output-format text\|json` | JSON: `result`, `is_error`, `num_turns`, `duration_ms`, `model`, `usage`, `todos` |
+| `--add-dir <path>` | another folder it may read but not change (repeatable) |
+| `--max-turns <n>` | most model requests before it gives up (default 200) |
+| `--memory-floor <pct>` | tests and builds wait while free memory is below this (default 35; `0` turns it off) |
+| `--allow-outward` | let it commit, push its branch and open a PR when the task asks; for sandboxes and CI only |
+
+What kino-code does on its own: it reads before it edits, searches with glob and grep (ripgrep when installed),
+runs the repository's own test and lint commands, keeps a to-do list for longer work, and can hand a wide
+investigation to a read-only helper. It follows `AGENTS.md`, `KINO.md` or `CLAUDE.md` when the repository has one.
+
+## 7. Setting kino up for a team repo
+
+The console works in any folder straight away. To let kino work like a team member, set it up once in the
+repository:
+
+```bash
+cd ~/code/team-repo
+kino init
+```
+
+The setup asks:
+- **the model** kino's agents use;
+- **who writes code**: kino-code, or the Claude Code CLI (see [11](#11-who-writes-the-code));
+- **which repositories to learn**: this one, plus GitHub or GitLab URLs or local paths (remote ones are cloned);
+- **who kino works as**: the commit name and email;
+- **your tools**: GitHub (`gh`), Jira, Linear, ClickUp or GitHub Issues, and the review bot;
+- **your working style**, and which processes it may run.
+
+Then it **learns each repository**. It scans the stack, the build, test and run commands for each part, the CI,
+the conventions in the git history, the docs and the tools in use. Then it reads the code and writes a profile:
+architecture, commands, conventions, gotchas.
+
+Unattended, for scripts:
+
+```bash
+kino init --yes --llm claude-code --model claude-sonnet-5-5 --coding-agent kino-code \
+          --repo https://github.com/acme/web --repo ~/code/api
+```
+
+Later:
+
+```bash
+kino learn https://gitlab.com/acme/infra    # add a repository
+kino relearn                                # learn them all again (values you set by hand are kept)
+```
+
+What it writes:
+- `.kino/config.yaml`, `.kino/knowledge/` and `.kino/processes/`: **commit these**, so the team shares one setup;
+- `.kino/runs/` and connection state: local to your machine, already in `.kino/.gitignore`.
+
+## 8. Processes
+
+A process is a documented way of working, drawn as a BPMN diagram, that kino carries out step by step. The
+diagram decides the path: branches, loops, parallel work, waiting for a person. A step agent does each activity.
+Each run is saved after every step, so it can wait for an answer, stop, and continue later.
+
+Included:
+
+| Process | Does |
+|---|---|
+| `ticket-to-pr` | a ticket to a pull request: worktree and branch, the change in the repo's style, local checks, the PR description |
+| `review-bot-loop` | asks the review bot, then fixes or replies to its comments, round after round, with CI checked |
+| `human-review-response` | finds people's review feedback, fixes it and replies, branch by branch |
+| `review-others-prs` | reviews teammates' pull requests line by line, with real QA |
+| `qa-evidence` | real QA of a feature (UI, API), with its own test data, and the QA comment |
+| `sprint-ticket-sweep` | goes through your sprint's tickets one at a time, skipping the exceptions you name |
+| `stacked-epic-delivery` | an epic as a stack of branches, one per ticket, then merged in order |
+| `ticket-status-and-links` | links and closing comments on tickets; moves status only once the work is reviewed |
+| `data-migration-runbook` | a one-off data migration: check, throttled and resumable migrate, verify |
+| `customer-announcement` | a feature announcement email, per language |
+| `client-demo-video` | records a product demo video |
+
+```bash
+kino processes                                          # list them
+kino show-process ticket-to-pr                          # what it does, step by step
+kino start ticket-to-pr --input ticket=ABC-123          # run one
+kino runs                                               # runs and their status
+kino resume <run-id> --answer approve=yes               # answer a waiting step
+kino run "Sweep my sprint tickets except anything about billing"   # a free-form task
+```
+
+In the console: `/process ticket-to-pr ticket=ABC-123`, `/runs`, `/resume`.
+
+**Your own processes:**
+- `kino draft-process "Expenses over 500 need a manager's OK before payment"`: an agent drafts the diagram. It is
+  checked until it runs, then shown to you before it is saved;
+- `kino import-bpmn ./expense.bpmn`: use a diagram drawn in bpmn.io or Camunda Modeler, with its own conditions.
+
+## 9. Connecting your tools
+
+kino reaches your tools through the connections you already have.
+
+**From Claude Code.** If you connected MCP servers in Claude Code (`claude mcp add …`), `kino connect` lists them
+and lets you pick which ones kino uses and for what: tickets, code hosting, docs. Servers from Claude Code
+plugins are included.
+
+```bash
+kino connect
+```
+
+**GitHub** through the `gh` CLI you are logged into (the token stays with gh):
+
+```bash
+kino connect --gh-cli --setting org=YourOrg
+```
+
+**Any tool with an API**, from its OpenAPI or GraphQL description, or a built-in profile:
+
+```bash
+kino connect billing --spec https://billing.example.com/openapi.json --auth env:BILLING_TOKEN
+kino connect jira --profile jira --base-url https://your-site.atlassian.net \
+    --auth env:JIRA_API_TOKEN --username env:JIRA_EMAIL
+kino connect billing --find-spec billing-vendor.com     # look up a vendor's published API
+```
+
+Each connection gets its own agent. Reads run; **every write is confirmed, call by call**. Secrets are given as
+references (`env:VAR`, `keychain:item`). They are read when a call is made and never stored in config, prompts or
+logs.
+
+Tools that only authorize through OAuth inside Claude Code, such as claude.ai connectors or ClickUp's official
+server, cannot be reached from outside Claude Code. Connect those through their API instead.
+
+## 10. Knowledge
+
+kino searches what it knows before it works: the repository profiles, the process documents, and anything you
+add.
+
+```bash
+kino add-docs ./handbook                  # a file, a folder or a URL
+kino ask "how do we run the api tests"    # search it yourself (in the console: /ask)
+```
+
+Notes that belong to you rather than the team can stay outside the repository, in your own config:
+
+```yaml
+knowledge:
+  - {kind: memory, path: ~/notes/agent-memory}      # one fact per file
+  - {kind: markdown, path: ~/notes/handoff.md, stale: true}
+```
+
+Optionally, kino can also keep a **domain specialist**: it studies your product's rules from the code and docs,
+checks what it learned, and answers the other agents with sources. It is off by default; see `kino domain --help`.
+
+## 11. Who writes the code
+
+In processes, the coding steps are done by the agent set in `coding_agent.kind`:
+
+| | kino-code (default) | claude-code |
+|---|---|---|
+| What | kino's own coding agent | the Claude Code CLI, `claude -p` |
+| Models | any model kino supports, including your Claude Code login | Claude |
+| Needs | a model | `claude`, installed and logged in |
+
+```yaml
+coding_agent:
+  kind: kino-code
+  model: anthropic:<id>       # optional; default: the workspace model
+```
+
+Either way, the coder only edits files and runs the repository's commands. Pushing, pull requests, tickets and
+API calls stay with kino's own steps, behind its confirmations.
+
+## 12. Safety
+
+- **Outward actions are confirmed one call at a time**: push, pull requests, comments, ticket and API writes. With
+  nobody at the terminal they are refused, or the run waits until someone answers.
+- **Never done, whatever you answer**: force-push, `git reset --hard`, `git stash`, merging pull requests,
+  admin overrides, co-author trailers.
+- **Files** can only change inside the folder kino works in.
+- **Heavy commands** (tests, builds, containers, browsers) wait while free memory is below the floor (35% by
+  default; `policy.min_free_memory_pct`).
+- **Secrets** are references, resolved per request and kept out of config, prompts and logs. Auth headers are
+  removed from request logs.
+- **Allow and deny lists** in the config narrow what may be asked at all. A denied call never reaches the tool.
+- kino reports honestly: what it changed, how it checked, and what it did not do.
+
+## 13. Configuration reference
+
+The workspace config is `.kino/config.yaml` in the repository; `kino init` writes it.
+
+```yaml
+models:
+  default: claude-code:claude-sonnet-5-5
+  per_agent:                       # optional: another model for one kind of agent
+    reviewer: anthropic:<id>
+  # an OpenAI-compatible endpoint (vLLM, LM Studio, a gateway):
+  # default: {provider: openai-compatible, model: <id>, base_url: http://localhost:8000/v1, api_key_env: MY_KEY}
+
+coding_agent:
+  kind: kino-code                  # or claude-code
+  model: anthropic:<id>            # optional
+
+policy:
+  min_free_memory_pct: 35
+
+knowledge:
+  - {kind: markdown, path: docs/handbook.md}
+```
+
+| Environment variable | Meaning |
+|---|---|
+| `KINO_MODEL` | the model, when the config sets none |
+| `KINO_SETTINGS` | another settings file than `~/.config/kino/settings.json` |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | provider keys |
+| `OLLAMA_HOST` | where Ollama runs (default `http://localhost:11434`) |
+| `KINO_UV`, `KINO_NO_UV_INSTALL` | which uv the npm package uses; don't install uv |
+
+All commands: `kino --help`, and `kino <command> --help` for each one.
+
+## 14. Updating, uninstalling, troubleshooting
 
 ```bash
-npx kino-cli            # open the kino shell in this folder
-npx kino-cli init       # set kino up for this repository
-npx kino-cli code -p "fix the off-by-one in pagination and add a test"
-npm i -g kino-cli       # then just: kino
+npm i -g kino-cli@latest     # or: brew upgrade kino-cli
+kino --version
+npm rm -g kino-cli           # or: brew uninstall kino-cli
 ```
 
-This package carries kino compiled for macOS, Linux and Windows and runs it with [uv](https://docs.astral.sh/uv),
-which fetches Python 3.12 and kino's dependencies on the first run and caches them. If uv is missing it is installed
-for you (set `KINO_NO_UV_INSTALL=1` to refuse, or `KINO_UV=/path/to/uv` to pick one). Node 18+.
+| Problem | Fix |
+|---|---|
+| "kino needs a model" | Log in to Claude Code (`claude auth login`), set an API key, or start Ollama, then run `kino` or `kino model`. |
+| The model picker doesn't list Claude Code | Check that `claude` is on your PATH and that `claude auth status` says you are logged in. |
+| The first start is slow | uv is fetching Python and kino's libraries, once. Later starts are fast. |
+| Tests "wait for memory" | Free some memory, or lower `policy.min_free_memory_pct` (`--memory-floor` for `kino code`). |
+| A run stopped or failed | `kino runs`, then `kino resume <id>` (in the console: `/resume`). |
+| The console prints help and exits | It needs a terminal. In scripts use `kino code -p`, `kino run` or `kino start`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kino-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "kino: an agent that learns your codebase and tools, then works as one of the team's developers. Includes kino-code, a coding agent on any model.",
   "bin": {
     "kino": "bin/kino.js"