docs: add iosm-cli reference, CLI implementation section, update status and roadmap

Author: ecsiar

README.md

@@ -7,6 +7,8 @@
 
 **IOSM (Improve -> Optimize -> Shrink -> Modularize)** is an engineering methodology for continuous system improvement. This repository is the **canonical specification repository** for IOSM v1.0 and contains the normative spec, machine-readable schemas, and example artifacts required to understand, adopt, and validate the methodology.
 
+> **Looking for the runtime?** See [**iosm-cli**](https://github.com/rokoss21/iosm-cli) — a terminal coding agent that implements IOSM as an engineering runtime with orchestration, MCP, checkpoints, and extensions.
+
 ## What This Repository Contains
 
 - The normative IOSM v1.0 specification: [IOSM_SPEC_v1.0.md](IOSM_SPEC_v1.0.md)
@@ -132,31 +134,45 @@ IOSM can be adopted incrementally:
 - Future incompatible spec versions should be introduced as new versioned files, for example `IOSM_SPEC_v1.1.md` or `IOSM_SPEC_v2.0.md`.
 - Repository-level changes are tracked in [CHANGELOG.md](CHANGELOG.md).
 
+## CLI Implementation
+
+[**iosm-cli**](https://github.com/rokoss21/iosm-cli) is the reference runtime that implements this specification as a terminal coding agent.
+
+```bash
+npm install -g iosm-cli
+iosm
+```
+
+| Feature | Description |
+|---------|-------------|
+| IOSM cycles | `/init` + `/iosm` — measurable improve/verify loops with artifact output |
+| Orchestration | `/orchestrate` — parallel/sequential agents with dependencies, locks, worktrees |
+| Operational controls | `/checkpoint`, `/rollback`, `/doctor`, `/memory` |
+| Extensibility | MCP servers, TypeScript extensions, SDK, JSON/RPC modes |
+| 15+ LLM providers | Anthropic, OpenAI, Gemini, Groq, xAI, OpenRouter, Mistral, and more |
+
+[![npm version](https://img.shields.io/npm/v/iosm-cli?style=flat-square&color=cb3837)](https://www.npmjs.com/package/iosm-cli)
+
 ## Current Status
 
-This repository is currently a **specification repository with automated validation**.
+This repository is a **specification repository with automated validation**.
 
 What is already present:
 
 - a full normative specification;
 - canonical examples and templates;
-- machine-readable schemas for the primary artifacts.
+- machine-readable schemas for the primary artifacts;
 - a reference repository validator;
-- CI automation for repository validation.
-
-What is intentionally out of scope for v1.0:
-
-- a reference CLI implementation;
-- published case studies.
+- CI automation for repository validation;
+- a reference CLI implementation: [iosm-cli](https://github.com/rokoss21/iosm-cli).
 
 ## Roadmap
 
-The most logical next steps after this repository baseline are:
-
-1. Publish one or more worked case studies.
+1. Publish worked case studies.
 2. Add visualization guidance for radar charts, index timelines, and drift heatmaps.
-3. Add a broader implementation toolkit on top of the repository validator.
+3. Expand the implementation toolkit on top of the repository validator.
 4. Add additional schemas and conformance fixtures for future spec versions.
+5. Deepen integration with [iosm-cli](https://github.com/rokoss21/iosm-cli) runtime.
 
 ## Contributing
 
@@ -172,7 +188,7 @@ Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
 
 ## Author
 
-**Emil Rokossovsky**
+**Emil Rokossovskiy**
 
 - GitHub: [@rokoss21](https://github.com/rokoss21)
 - Email: [ecsiar@gmail.com](mailto:ecsiar@gmail.com)