feat: OACP v0.1.1

README.md

@@ -6,6 +6,8 @@
 [![Codex](https://img.shields.io/badge/Runtime-Codex-74AA9C.svg)](https://openai.com/index/codex/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/kiloloop/oacp/pulls)
 
+> **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.
+
 **Empowering solo founders to coordinate AI agents, with human-in-the-loop for control.**
 
 A file-based coordination protocol for multi-agent engineering workflows. OACP defines the message formats, state machines, review processes, and safety rules that enable AI agents on different runtimes to collaborate asynchronously through a shared filesystem.
@@ -32,6 +34,43 @@ When multiple AI agents work on the same codebase, they need a way to:
 
 OACP solves this with a filesystem-based protocol that requires no server, no database, and no vendor lock-in. Agents read and write YAML files in a shared directory — that's it.
 
+## Where OACP Fits
+
+Three protocols are shaping multi-agent development. They solve different problems at different layers:
+
+```
+┌─────────────────────────────────────────────┐
+│  A2A — Agent discovery & remote messaging   │  internet-scale
+├─────────────────────────────────────────────┤
+│  OACP — Agent coordination & workflows      │  local filesystem
+├─────────────────────────────────────────────┤
+│  MCP — Agent-to-tool integration            │  tool access
+└─────────────────────────────────────────────┘
+```
+
+**[MCP](https://modelcontextprotocol.io/)** gives agents access to tools and data sources — databases, APIs, file systems. It defines how an agent *calls a tool*.
+
+**[A2A](https://github.com/a2aproject/A2A)** lets agents discover and communicate with each other across the internet. HTTP-based, enterprise-grade, backed by 150+ organizations under the Linux Foundation.
+
+**OACP** coordinates agents working together on the same machine. File-based, zero-infra, designed for dev teams and CI pipelines.
+
+### OACP vs A2A
+
+Both coordinate agents — but for different topologies:
+
+| | A2A | OACP |
+|---|---|---|
+| **Transport** | HTTP/HTTPS — always-on servers | Filesystem — read/write files |
+| **Best for** | Cross-org, internet-routable agents | Local teams, dev machines, CI |
+| **Infrastructure** | TLS, auth, HTTP endpoints | A shared directory |
+| **Offline support** | Agent must be reachable | Native — messages wait in inbox |
+| **Audit trail** | Requires log infrastructure | The inbox directory *is* the log |
+| **Setup** | Deploy servers + configure networking | `oacp init my-project` |
+
+They complement each other. A2A connects agents across the internet. OACP coordinates agents on your machine. A gateway between OACP inboxes and A2A endpoints is a natural bridge — and A2A's own community is [exploring inbox patterns](https://github.com/a2aproject/A2A/discussions/792) that validate this design.
+
+**OACP + MCP work together.** An agent can use MCP to access tools (databases, APIs) while using OACP to coordinate with other agents (review loops, task dispatch, shared memory). Different layers, no conflict.
+
 ## Install
 
 ```bash
@@ -179,7 +218,8 @@ make preflight
 ## Documentation
 
 - [SPEC.md](SPEC.md) — Full protocol specification
-- [QUICKSTART.md](QUICKSTART.md) — 5-minute getting started guide
+- [examples/quickstart/](examples/quickstart/) — Hands-on tutorial: send a message to an AI agent
+- [QUICKSTART.md](QUICKSTART.md) — CLI reference walkthrough
 - [docs/guides/setup.md](docs/guides/setup.md) — Detailed setup guide
 - [docs/guides/adoption.md](docs/guides/adoption.md) — Adoption guide (minimum → full)
 - [docs/protocol/](docs/protocol/) — Individual protocol specs

examples/quickstart/README.md

@@ -0,0 +1,98 @@
+# Quickstart: Your First Agent Message
+
+Send a message to an AI agent and get a reply — coordinated through files in a directory.
+
+```
+you (alice)                    AI agent (bob)
+  │                                 │
+  │──── task_request ──────────────▶│
+  │                                 │
+  │◀─── notification ───────────────│  "Done!"
+  │                                 │
+```
+
+## Prerequisites
+
+- Python 3.9+
+- `pip install oacp-cli`
+- An AI agent runtime — [Claude Code](https://claude.ai/code), [Codex](https://openai.com/index/codex/), or any agent that can read/write files
+
+## Setup
+
+```bash
+git clone https://github.com/kiloloop/oacp.git && cd oacp
+
+export OACP_HOME="$HOME/oacp-quickstart"
+oacp init demo
+
+# Create inboxes for alice (you) and bob (your AI agent)
+mkdir -p $OACP_HOME/projects/demo/agents/alice/{inbox,outbox}
+mkdir -p $OACP_HOME/projects/demo/agents/bob/{inbox,outbox}
+```
+
+## Step 1: Send a message
+
+```bash
+oacp send demo \
+  --from alice --to bob \
+  --type task_request \
+  --subject "Hello from alice" \
+  --body "Introduce yourself and tell me what you can do."
+```
+
+Check bob's inbox:
+
+```bash
+cat $OACP_HOME/projects/demo/agents/bob/inbox/*.yaml
+```
+
+```yaml
+id: msg-20260315-alice-a1b2
+from: alice
+to: bob
+type: task_request
+created_at_utc: "2026-03-15T20:00:00Z"
+subject: "Hello from alice"
+body: |
+  Introduce yourself and tell me what you can do.
+```
+
+Every OACP message is a human-readable YAML file. No binary formats, no databases.
+
+## Step 2: Your agent replies
+
+Open your AI agent in this repo and give it this prompt:
+
+> Read `SPEC.md` to learn the OACP protocol. Then check your inbox at `$OACP_HOME/projects/demo/agents/bob/inbox/` and reply to any messages. You are bob.
+
+The agent reads the spec, finds the message in its inbox, and uses `oacp send` to reply to alice.
+
+## Step 3: Check your inbox
+
+```bash
+cat $OACP_HOME/projects/demo/agents/alice/inbox/*.yaml
+```
+
+You should see a reply from bob. That's it — two agents communicating through files.
+
+## What just happened?
+
+- You sent a message by writing a YAML file to an agent's inbox
+- Your agent read the protocol spec, checked its inbox, and replied the same way
+- Every message is threaded, human-readable, and stored as a file
+- The inbox directory is the audit trail — no log infrastructure needed
+
+**No servers. No databases. No API keys.** Just files in a directory.
+
+## Next steps
+
+- **Add skills** — install [OACP Skills](https://github.com/kiloloop/oacp-skills) so agents check inboxes automatically
+- **Read the spec** — [SPEC.md](https://github.com/kiloloop/oacp/blob/main/SPEC.md) covers the full protocol including the review loop
+- **See it in production** — [Cortex](https://github.com/kiloloop/cortex) is an example app built on OACP
+
+## Cleanup
+
+```bash
+rm -rf "$OACP_HOME"
+unset OACP_HOME
+```

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oacp-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Open Agent Coordination Protocol CLI for file-based multi-agent workflows"
 readme = "README.md"
 license = "Apache-2.0"

scripts/init_project_workspace.py

@@ -110,7 +110,7 @@ def _standards_version() -> str:
             return path.read_text(encoding="utf-8").splitlines()[0].strip()
         except (FileNotFoundError, IndexError):
             continue
-    return "0.5.0"
+    return "0.1.0"
 
 
 def _project_facts_template() -> str: