@debian777/kairos-mcp 3.2.0-pre.1 → 3.2.0

package/README.md

@@ -27,54 +27,66 @@ KAIROS runs as a Docker stack. Docker and Docker Compose are required.
 
 **Minimal (default):** Qdrant + app only. No Redis or auth.
 
-1. Download the Compose file and minimal env example:
+1. Download the Compose file and minimal env example (or from a clone: `cp docs/install/env.example.minimal.txt .env` from repo root):
   ```bash
    curl -LO https://raw.githubusercontent.com/debian777/kairos-mcp/main/compose.yaml
    curl -LO https://raw.githubusercontent.com/debian777/kairos-mcp/main/docs/install/env.example.minimal.txt
    cp env.example.minimal.txt .env
   ```
-2. Set your embedding provider in `.env` (e.g. `OPENAI_API_KEY=sk-proj-...`).
-3. Start the stack:
+2. Set your embedding provider in `.env`: `OPENAI_API_KEY=sk-proj-...` (OpenAI), or [Ollama](docs/install/README.md#optional--ollama-local-embeddings) (local), or TEI — see [docs/install/README.md](docs/install/README.md).
+3. Start the stack (from the directory that has `compose.yaml` and `.env`):
   ```bash
    docker compose -p kairos-mcp up -d
   ```
+   For a separate minimal deployment (e.g. your own mini directory with its own compose and `.env`): `docker compose -p kairos-mini up -d` from that directory.
 4. Confirm the server is healthy:
   ```bash
    curl http://localhost:3000/health
   ```
 
-**Full stack (Redis, Postgres, Keycloak):** Use [docs/install/env.example.fullstack.txt](docs/install/env.example.fullstack.txt) as `.env`, set `REDIS_URL=redis://redis:6379` and your secrets, then:
-
-See [docs/install/README.md](docs/install/README.md) for env variants. Full developer workflow is in [CONTRIBUTING.md](CONTRIBUTING.md).
+**Full stack (Redis, Postgres, Keycloak):** Use [docs/install/env.example.fullstack.txt](docs/install/env.example.fullstack.txt) as `.env`, set `REDIS_URL=redis://redis:6379` and your secrets. See [docs/install/README.md](docs/install/README.md) for env variants and full stack setup. Full developer workflow is in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Installation
 
 - **Docker Compose (recommended)** — minimal (Qdrant + app) by default, or
 full stack with Redis and Keycloak; see the quick start above.
-- **npm (CLI only)** — install the `kairos` command-line tool globally.
+- **npm (CLI only)** — run the `kairos` CLI without installing, or install globally.
 Node.js 25 or later is required.
   ```bash
-  npm install -g @debian777/kairos-mcp
+  npx @debian777/kairos-mcp
   ```
+  Or install globally: `npm install -g @debian777/kairos-mcp` then run `kairos`.
+  Pre-release: `npm install -g @debian777/kairos-mcp@3.2.0-pre.2` (or latest `*-pre.*` on [npm](https://www.npmjs.com/package/@debian777/kairos-mcp?activeTab=versions)). Use `--install-links` to install link dependencies as real packages.
   See [KAIROS CLI](docs/CLI.md) for usage.
+- **Update your agent instructions (recommended):** Add the KAIROS intro to your project’s **AGENTS.md** (or your IDE’s rules) so agents follow the protocol. Example to copy or adapt:
+
+  > KAIROS MCP is a Model Context Protocol server for persistent memory and
+  > deterministic protocol-chain execution. It stores workflows as linked
+  > memory chains where each step carries a proof-of-work challenge. You
+  > execute a protocol by searching for a match, beginning the run, solving
+  > each challenge via `kairos_next`, and attesting completion. Every hash,
+  > nonce, and identifier is server-generated; echo them verbatim — never
+  > compute them.
+
+
 
 For development setup, all `npm run` commands, and **how we do releases**, see
 [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ### Agent skills
 
-This repo ships **multiple skills**. Adding the repo typically installs **all** of them; use `--skill` to install only the ones you want.
+This repo ships the **kairos** skill (run protocols: /k, /apply, /search). Use `--list` to see what the skills registry reports for this repo.
 
-**Install all skills from this repo:**
+**Install from this repo:**
 
 ```bash
 npx skills add debian777/kairos-mcp
 ```
 
-**Install only specific skills** (e.g. just protocol execution, or just the coding-standard skill):
+**Install only the kairos skill:**
 
 ```bash
-npx skills add debian777/kairos-mcp --skill kairos --skill kairos-code
+npx skills add debian777/kairos-mcp --skill kairos
 ```
 
 List what’s available: `npx skills add debian777/kairos-mcp --list`
@@ -82,14 +94,6 @@ List what’s available: `npx skills add debian777/kairos-mcp --list`
 | Skill | Purpose |
 |-------|---------|
 | `kairos` | Run protocols (/k, /apply, /search). |
-| `kairos-code` | ELITE AI CODING STANDARDS — /code, full protocol (branch, tests, deploy, promote). |
-| `kairos-ai-docs` | Zero-drift AI instructions template — /ai-docs, write/update AI instructions. |
-| `kairos-create-protocol` | Create and mint new KAIROS protocol chains. |
-| `kairos-create-skill` | Create Cursor/agent skills that ship protocols. |
-| `kairos-refine-search` | Refine a weak or empty search (step-by-step better query). |
-| `kairos-development` | Agent instructions for kairos-dev (workflow-test, ai-mcp-integration). |
-
-The **kairos** skill is the one that enables running protocols (/k, /apply, /search). The table above lists all skills in this repo.
 
 **Popular agents (global install, non-interactive):**
 
@@ -100,9 +104,9 @@ The **kairos** skill is the one that enables running protocols (/k, /apply, /sea
 | Cursor + Claude Code | `npx skills add debian777/kairos-mcp -y -g -a cursor -a claude-code` |
 | All detected agents | `npx skills add debian777/kairos-mcp -y -g` (omit `-a` to install to all) |
 
-Optionally add `--skill kairos --skill kairos-code` (etc.) to any command to install only selected skills instead of all.
+Optionally add `--skill kairos` to install only that skill.
 
-**Remove a skill** (use the skill name, e.g. `kairos`, `kairos-code`):
+**Remove a skill** (use the skill name, e.g. `kairos`):
 
 ```bash
 npx skills remove kairos -g
@@ -114,7 +118,7 @@ Run without `-y` to choose agents interactively. Full list and install details:
 
 - [Install KAIROS MCP in Cursor](docs/INSTALL-MCP.md)
 - [KAIROS CLI reference](docs/CLI.md)
-- [Architecture and protocol workflows](docs/architecture/README.md)
+- [Architecture and protocol workflows](docs/architecture/README.md) — tool workflows, infrastructure, [auth overview](docs/architecture/auth-overview.md), [logging](docs/architecture/logging.md)
 - [Protocol examples and challenge types](docs/examples/README.md)
 - [All documentation](docs/README.md)
 
@@ -122,9 +126,7 @@ Run without `-y` to choose agents interactively. Full list and install details:
 
 **The server does not start.** Check that ports 3000 and 6333 (Qdrant) are free (6379 only if using fullstack). Run `docker compose -p kairos-mcp logs` to inspect errors.
 
-**Embeddings fail on startup.** Confirm `OPENAI_API_KEY` is set in
-`.env`, or configure a TEI (Text Embeddings Inference) endpoint with
-`TEI_BASE_URL`.
+**Embeddings fail on startup.** Set an embedding provider in `.env`: `OPENAI_API_KEY` (OpenAI), or [Ollama](docs/install/README.md#optional--ollama-local-embeddings) (`OPENAI_API_URL` base URL + `OPENAI_EMBEDDING_MODEL` + `OPENAI_API_KEY=ollama`; use `http://host.docker.internal:11434` if the app runs in Docker), or TEI (`TEI_BASE_URL` + `TEI_MODEL`). See [docs/install/README.md](docs/install/README.md).
 
 **Health check returns 503.** Qdrant (and Redis if fullstack) may still be initializing. Wait 10–15 seconds, then retry.