diff --git a/AGENTS.md b/AGENTS.md
index 09584e2a..6671de80 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -88,6 +88,25 @@ mew space down
4. Check TypeScript errors: `npm run lint`
5. Rebuild after changes: `npm run build`
+## Spec-Driven Development (IMPORTANT!)
+
+When making changes, follow the workflow in `CONTRIBUTING.md`:
+
+1. **Start with CHANGELOG** - Add entry to `CHANGELOG.md` "Next" section
+2. **Create proposal** - Document in `spec//proposals/XXX-name/`
+ - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (NOT 001, 002, or "bat", "tok")
+ - Include motivation, research, decisions, spec
+3. **Incorporate into specs** - Update main spec docs, mark CHANGELOG as needing implementation
+4. **Create implementation plan** (if complex) - `spec/integration-plans/XXX-name.md`
+5. **Implement code** - Write code, tests, examples; update CHANGELOG status
+6. **Submit PR** - Include proposals, spec updates, code, tests, CHANGELOG
+
+**Key points:**
+- Proposals stay in `proposals/` permanently (status tracked in CHANGELOG)
+- Specs and code developed together in same PR
+- All changes must update relevant specs
+- See `CONTRIBUTING.md` for full workflow details
+
## Key Files
- Protocol types: `src/types/protocol.ts`
- Gateway: `src/cli/commands/gateway.ts`
@@ -103,9 +122,17 @@ mew space down
- DO update specs if changing protocol
## Making Changes
-1. **Protocol changes**: Update spec/protocol/draft/ → src/types/ → implementations → tests
-2. **New features**: Check spec → implement → test → document
-3. **Bug fixes**: Write failing test → fix → verify all tests pass
+
+**All changes must follow the spec-driven workflow above.** Quick reference:
+
+1. **New features/protocol changes**:
+ - Create proposal in `spec//proposals/XXX-name/`
+ - Update specs, add to CHANGELOG
+ - Implement: types → implementations → tests
+
+2. **Bug fixes**:
+ - If trivial: Write failing test → fix → verify
+ - If significant: Create proposal documenting the issue and fix
## Documentation
- Main docs hub: `docs/README.md`
diff --git a/CLAUDE.md b/CLAUDE.md
index 09584e2a..6671de80 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -88,6 +88,25 @@ mew space down
4. Check TypeScript errors: `npm run lint`
5. Rebuild after changes: `npm run build`
+## Spec-Driven Development (IMPORTANT!)
+
+When making changes, follow the workflow in `CONTRIBUTING.md`:
+
+1. **Start with CHANGELOG** - Add entry to `CHANGELOG.md` "Next" section
+2. **Create proposal** - Document in `spec//proposals/XXX-name/`
+ - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (NOT 001, 002, or "bat", "tok")
+ - Include motivation, research, decisions, spec
+3. **Incorporate into specs** - Update main spec docs, mark CHANGELOG as needing implementation
+4. **Create implementation plan** (if complex) - `spec/integration-plans/XXX-name.md`
+5. **Implement code** - Write code, tests, examples; update CHANGELOG status
+6. **Submit PR** - Include proposals, spec updates, code, tests, CHANGELOG
+
+**Key points:**
+- Proposals stay in `proposals/` permanently (status tracked in CHANGELOG)
+- Specs and code developed together in same PR
+- All changes must update relevant specs
+- See `CONTRIBUTING.md` for full workflow details
+
## Key Files
- Protocol types: `src/types/protocol.ts`
- Gateway: `src/cli/commands/gateway.ts`
@@ -103,9 +122,17 @@ mew space down
- DO update specs if changing protocol
## Making Changes
-1. **Protocol changes**: Update spec/protocol/draft/ → src/types/ → implementations → tests
-2. **New features**: Check spec → implement → test → document
-3. **Bug fixes**: Write failing test → fix → verify all tests pass
+
+**All changes must follow the spec-driven workflow above.** Quick reference:
+
+1. **New features/protocol changes**:
+ - Create proposal in `spec//proposals/XXX-name/`
+ - Update specs, add to CHANGELOG
+ - Implement: types → implementations → tests
+
+2. **Bug fixes**:
+ - If trivial: Write failing test → fix → verify
+ - If significant: Create proposal documenting the issue and fix
## Documentation
- Main docs hub: `docs/README.md`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4ecfa096..44686062 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,18 +1,95 @@
# Contributing to MEW Protocol
+Thank you for contributing to MEW Protocol! This guide covers how to contribute changes, from initial design through implementation to release.
+
+---
+
## Quick Start
+
1. Fork and clone the repository
2. `npm install && npm run build`
3. `npm test` to verify everything works
-4. Make changes, add tests
+4. Make changes following the workflow below
5. `npm run lint && npm test`
6. Submit PR
-## Development Workflow
-See [Development Guide](docs/development.md) for details.
+---
+
+## Spec-Driven Development Workflow
+
+MEW Protocol follows a spec-driven development approach where specifications are designed and documented before code implementation. All changes begin with a CHANGELOG entry that tracks the proposal and implementation status throughout the lifecycle.
+
+### Lifecycle Stages
+
+1. **Draft** - Add CHANGELOG entry, design and write proposals in proposals/ (in Draft PR)
+2. **Incorporate** - Update specs, mark CHANGELOG entry as needing implementation (still Draft PR)
+3. **Implementation Planning** - Create implementation plan in integration-plans/, reference from CHANGELOG (still Draft PR)
+4. **Implementation** - Write code, tests, examples, update CHANGELOG status (still Draft PR)
+5. **Review** - Get feedback, iterate or revert if needed (PR Ready for Review)
+6. **Merge** - Merge approved changes (specs + code together)
+7. **Release** - Tag version with all merged changes (happens later)
+
+### Folder Structure
+
+- **`spec//proposals/XXX-name/`** - All proposals (status tracked in CHANGELOG)
+ - XXX = unique 3-character alphanumeric code (e.g., `a7z`, `k3p`, `m9w`)
+- **`spec//rejected/XXX-name/`** - Rejected proposals (moved out of proposals/)
+- **`spec/integration-plans/XXX-name.md`** - Implementation plans for complex changes
+ - XXX = unique 3-character alphanumeric code (e.g., `b4x`, `r8n`)
+
+### Core Documents
+
+- **Proposals** - Design rationale, research, decisions (stay in `proposals/` permanently)
+- **Main Specs** - Authoritative documentation (updated from proposals)
+- **CHANGELOG.md** - Tracks status of all proposals (Draft → Needs Implementation → In Progress → Done → Released)
+- **Implementation Plans** - Guides code development (optional, for complex changes)
+
+### Naming Convention
+
+- Proposals and implementation plans use unique 3-character alphanumeric codes
+- Format: `XXX-descriptive-name` (e.g., `a7z-message-batching`, `k3p-token-limits`, `m9w-new-feature`)
+- Codes must be unique within their scope (proposals per spec area, implementation plans globally)
+- Use random alphanumeric combinations (mix letters and numbers) to avoid conflicts across concurrent PRs
+- Avoid sequential numbers (001, 002) or word-like abbreviations (bat, tok) that may conflict
+
+---
+
+## Development Setup
+
+See [Development Guide](docs/development.md) for detailed development setup, testing, and practices.
+
+---
## Submitting PRs
-- Keep PRs focused on single feature/fix
+
+### PR Guidelines
+
+- Keep PRs focused on a logical unit of changes (may include multiple proposals)
+- Follow the spec-driven workflow above
- Add tests for new functionality
-- Update specs if changing protocol
-- Run full test suite before submitting
+- Update specs if changing protocol/behavior
+- Run full test suite before submitting: `npm run lint && npm test`
+
+### PR Structure
+
+A typical PR includes:
+1. **Proposals** in `spec//proposals/XXX-name/`
+2. **Spec updates** incorporating the proposals
+3. **CHANGELOG entries** tracking status
+4. **Implementation plan** (if complex changes)
+5. **Code implementation** with tests and examples
+
+### Review Process
+
+- Open as **Draft PR** while working through stages 1-4
+- Mark **Ready for Review** when implementation is complete
+- Address feedback; may need to iterate or revert to draft
+- Once approved, maintainers will merge
+
+---
+
+## Getting Help
+
+- Open an issue for questions or discussions
+- Check [Documentation Hub](docs/README.md) for guides
+- Review existing proposals in `spec//proposals/` for examples
diff --git a/docs/README.md b/docs/README.md
index 3338c186..2c166b8e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,8 +11,7 @@
- [Release Process](releasing.md) - Publishing packages
## Specifications
-- [Protocol Spec](../spec/protocol/v0.4/SPEC.md) - Current stable (v0.4)
-- [Protocol Draft](../spec/protocol/draft/SPEC.md) - Next version
+- [Protocol Spec](../spec/protocol/SPEC.md) - Core MEW Protocol (v0.4)
- [CLI Spec](../spec/cli/SPEC.md) - Command-line interface
- [SDK Spec](../spec/sdk/SPEC.md) - TypeScript SDK
- [Bridge Spec](../spec/bridge/SPEC.md) - MCP-MEW bridge
diff --git a/docs/architecture.md b/docs/architecture.md
index f7b4c764..3ea84cd2 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -753,7 +753,7 @@ if (envelope.kind === "custom/action") {
## Related Documentation
-- **[Protocol Spec](../spec/protocol/v0.4/SPEC.md)** - Complete protocol reference
+- **[Protocol Spec](../spec/protocol/SPEC.md)** - Complete protocol reference
- **[SDK Spec](../spec/sdk/SPEC.md)** - SDK architecture and patterns
- **[Bridge Spec](../spec/bridge/SPEC.md)** - MCP-MEW bridge details
- **[CLI Spec](../spec/cli/SPEC.md)** - Command-line interface
diff --git a/docs/development.md b/docs/development.md
index 69ab5c5d..d1a4dd8c 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -415,7 +415,7 @@ tail -f .mew/logs/envelope-history.jsonl | jq .
## Additional Resources
-- [MEW Protocol Specification](../spec/protocol/v0.4/SPEC.md)
+- [MEW Protocol Specification](../spec/protocol/SPEC.md)
- [Testing Guide](testing.md)
- [Templates Guide](templates.md)
- [End-to-End Test Scenarios](../e2e/README.md)
@@ -425,7 +425,7 @@ tail -f .mew/logs/envelope-history.jsonl | jq .
- Check existing issues: https://github.com/rjcorwin/mew-protocol/issues
- Review test scenarios for examples: `e2e/scenario-*/`
-- Read the protocol specification: `spec/protocol/v0.4/SPEC.md`
+- Read the protocol specification: `spec/protocol/SPEC.md`
## Important Notes
diff --git a/docs/getting-started.md b/docs/getting-started.md
index b2952be2..5ca2d3a8 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -308,7 +308,7 @@ mew
### Understand the Protocol
-- **[Protocol Specification](../spec/protocol/v0.4/SPEC.md)** - Complete protocol reference
+- **[Protocol Specification](../spec/protocol/SPEC.md)** - Complete protocol reference
- **[CLI Spec](../spec/cli/SPEC.md)** - Command-line interface details
- **[SDK Spec](../spec/sdk/SPEC.md)** - Build your own participants
diff --git a/docs/guides/SPEC-GUIDE.md b/docs/guides/SPEC-GUIDE.md
deleted file mode 100644
index b1314b07..00000000
--- a/docs/guides/SPEC-GUIDE.md
+++ /dev/null
@@ -1,467 +0,0 @@
-# Specification Guide
-
-This guide explains how to create and maintain specifications for any component in the repository.
-
-## Universal Specification Structure
-
-Any folder can have a `spec/` directory following this structure:
-
-```
-[any-folder]/
-├── spec/
-│ ├── draft/ # Current work in progress
-│ │ ├── decisions/
-│ │ │ ├── proposed/ # ADRs under consideration
-│ │ │ ├── accepted/ # Approved ADRs
-│ │ │ └── rejected/ # Rejected ADRs
-│ │ ├── SPEC.md # Draft specification
-│ │ └── PATTERNS.md # Draft patterns (optional)
-│ └── [version]/ # Released versions
-│ ├── decisions/ # Frozen ADRs
-│ │ ├── accepted/
-│ │ └── rejected/
-│ ├── SPEC.md
-│ └── PATTERNS.md
-└── ... (other files)
-```
-
-## Version Naming Conventions
-
-Choose the versioning scheme that makes sense for your component:
-
-| Version Format | Examples | Use When |
-|----------------|----------|----------|
-| `v[major]` | `v0`, `v1`, `v2` | Simple major versions only |
-| `v[major].[minor]` | `v1.0`, `v2.1` | Need minor versions |
-| `v[major].[minor].[patch]` | `v1.0.0`, `v2.1.3` | Full semantic versioning |
-| `v[date]` | `v2025.08`, `v2025.09` | Time-based releases |
-| `v[number]` | `v1`, `v2`, `v3` | Simple incrementing |
-
-## Creating a Specification
-
-### Step 1: Initialize Draft
-
-```bash
-# For any component
-mkdir -p [component]/spec/draft/decisions/{proposed,accepted,rejected}
-
-# Create SPEC.md using the template below
-edit [component]/spec/draft/SPEC.md
-```
-
-### Step 2: Work in Draft
-
-- All active development happens in `draft/`
-- ADRs move through proposed → accepted/rejected
-- SPEC.md is continuously updated
-- No version number yet
-
-### Step 3: Release a Version
-
-**Important:** Before releasing, ensure all ADRs are fully incorporated into the spec:
-1. Incorporate each ADR into SPEC.md
-2. Update ADR incorporation field to "Complete"
-3. Move ADR from `proposed/` to `accepted/` or `rejected/`
-4. Update ADR status field accordingly
-
-```bash
-# When ready to release
-VERSION="v1.0.0" # or "v1" or whatever scheme you chose
-
-# Copy draft to version
-cp -r [component]/spec/draft [component]/spec/$VERSION
-
-# Update spec header to remove "Draft" status
-# Update version number throughout
-
-# Clean up - proposed folder should already be empty
-rm -rf [component]/spec/$VERSION/decisions/proposed
-
-# Tag in git (if applicable)
-git tag [component]@$VERSION
-```
-
-### Step 4: Continue Development
-
-After release, either:
-- Clear draft for next major version
-- Continue evolving draft for next release
-- Start parallel draft for breaking changes
-
-## ADR Process
-
-ADRs work the same way everywhere:
-
-1. **Create**: New ADR in `draft/decisions/proposed/`
-2. **Review**: Discuss and refine
-3. **Implement**: Incorporate into SPEC.md (must happen BEFORE accepting)
-4. **Accept/Reject**:
- - If accepting: Update incorporation to "Complete", then move to `accepted/`
- - If rejecting: Add rejection rationale, then move to `rejected/`
-5. **Release**: Included in next version
-
-### ADR Template
-
-```markdown
-# ADR-[ID]: [Title]
-
-**Status:** [Proposed|Accepted|Rejected]
-**Date:** [YYYY-MM-DD]
-**Incorporation:** [Not Incorporated|Partial|Complete]
-
-## Context
-
-[What is the issue we're addressing?]
-[Why does this decision need to be made now?]
-[What constraints exist?]
-
-## Options Considered
-
-### Option 1: [Name]
-[Description]
-
-**Pros:**
-- [Advantage]
-- [Advantage]
-
-**Cons:**
-- [Disadvantage]
-- [Disadvantage]
-
-### Option 2: [Name]
-[Description]
-
-**Pros:**
-- [Advantage]
-- [Advantage]
-
-**Cons:**
-- [Disadvantage]
-- [Disadvantage]
-
-## Decision
-
-[Which option was chosen and why]
-
-### Implementation Details
-[How this will be implemented]
-
-## Consequences
-
-### Positive
-- [Good outcome]
-- [Good outcome]
-
-### Negative
-- [Tradeoff or downside]
-- [Tradeoff or downside]
-```
-
-### ADR Naming
-
-**Filename:** `[number]-[id]-[descriptive-name].md`
-- Number: Sequential (001, 002, etc.)
-- ID: Unique 3-character identifier (e.g., x7k, a3b)
-- Name: Kebab-case description
-
-**Example:** `001-x7k-api-versioning-strategy.md`
-
-## Examples
-
-### Example 1: Simple Version
-```
-[any-folder]/
-└── spec/
- ├── draft/
- └── v1/ # Simple version
-```
-
-### Example 2: Semantic Version
-```
-[any-folder]/
-└── spec/
- ├── draft/
- └── v2.0.0/ # Semver version
-```
-
-### Example 3: Date-Based Version
-```
-[any-folder]/
-└── spec/
- ├── draft/
- └── v2025.08/ # Date-based version
-```
-
-### Example 4: Multiple Versions
-```
-[any-folder]/
-└── spec/
- ├── draft/ # Current work
- ├── v1.0/ # First release
- ├── v1.1/ # Minor update
- └── v2.0/ # Major update
-```
-
-### Example 5: With Decisions
-```
-[any-folder]/
-└── spec/
- ├── draft/
- │ ├── decisions/
- │ │ ├── proposed/
- │ │ ├── accepted/
- │ │ └── rejected/
- │ └── SPEC.md
- └── v1/
- ├── decisions/
- │ ├── accepted/
- │ └── rejected/
- └── SPEC.md
-```
-
-## What Goes in a Spec?
-
-Use the template below as a starting point, but adapt based on what you're specifying:
-
-### Always Include
-- **Purpose**: What this component does
-- **Scope**: What it covers and doesn't cover
-- **API/Interface**: How others interact with it
-- **Dependencies**: What it needs to work
-
-### Include When Relevant
-- **Architecture**: For complex components
-- **Configuration**: For configurable components
-- **Security**: For components with security implications
-- **Performance**: For performance-critical components
-- **Testing**: For components with specific test requirements
-- **Migration**: When changing from previous versions
-
-## Specification Lifecycle
-
-### 1. No Spec → Draft
-When starting to formalize a component
-
-### 2. Draft → v1
-First formal release
-
-### 3. v1 → Draft → v2
-Major changes requiring new version
-
-### 4. Deprecation
-Mark old versions as deprecated but keep for reference
-
-## Release Process
-
-### Releasing a Version from Draft
-
-1. **Verify ADR Incorporation**
- - All accepted ADRs must be fully incorporated into SPEC.md
- - Update ADR "Incorporation" status to "Complete"
- - Proposed folder should be empty (no pending decisions)
-
-2. **Create Version Directory**
- ```bash
- # Copy draft to new version
- cp -r spec/draft spec/v0.2
-
- # Remove proposed folder (should be empty)
- rmdir spec/v0.2/decisions/proposed
- ```
-
-3. **Update Version Headers**
- - Change "Version: draft" to "Version: 0.2" in SPEC.md
- - Update "Status" from "Draft" to appropriate status (Alpha/Beta/Stable)
- - Set "Release Date" in addition to "Last Updated"
-
-4. **Freeze the Release**
- - Released specs are immutable
- - All ADRs in the version are frozen
- - No further edits allowed
-
-### Starting a New Draft After Release
-
-1. **Clean Draft Directory**
- ```bash
- # Remove old draft decisions (now in released version)
- rm -rf spec/draft/decisions/accepted/*
- rm -rf spec/draft/decisions/rejected/*
-
- # Ensure proposed is empty
- ls spec/draft/decisions/proposed/ # Should only have README.md
- ```
-
-2. **Update Draft Spec**
- - Keep SPEC.md as starting point for next version
- - Update version header to indicate next target (e.g., "draft for v0.4")
- - Remove completed work that won't carry forward
-
-3. **Add README Clarifications**
- ```bash
- # Add README to each decision folder explaining state
- echo "# Proposed ADRs for v0.4" > spec/draft/decisions/proposed/README.md
- echo "# No accepted ADRs for v0.4 yet" > spec/draft/decisions/accepted/README.md
- echo "# No rejected ADRs for v0.4 yet" > spec/draft/decisions/rejected/README.md
- ```
-
-### Example Release Flow
-
-```bash
-# 1. Release v0.4 from draft
-cp -r spec/draft spec/v0.4
-rmdir spec/v0.4/decisions/proposed
-# Edit spec/v0.4/SPEC.md to update version
-
-# 2. Prepare draft for v0.5
-rm -rf spec/draft/decisions/accepted/*.md
-rm -rf spec/draft/decisions/rejected/*.md
-# Edit spec/draft/SPEC.md to indicate "draft for v0.5"
-
-# 3. Continue development
-# New ADRs go in spec/draft/decisions/proposed/
-```
-
-## Best Practices
-
-### DO
-- ✅ Keep draft separate from releases
-- ✅ Use consistent versioning within a component
-- ✅ Incorporate ADRs into spec BEFORE moving to accepted
-- ✅ Ensure proposed folder is empty before release
-- ✅ Track decisions with ADRs
-- ✅ Update SPEC.md as ADRs are incorporated
-- ✅ Link to related specifications
-- ✅ Update CHANGELOG.md for each release
-- ✅ Clean draft decisions after releasing a version
-- ✅ Add README files to clarify decision folder status
-
-### DON'T
-- ❌ Edit released specifications
-- ❌ Mix versioning schemes in one component
-- ❌ Skip the draft phase
-- ❌ Have proposed ADRs in released versions
-- ❌ Move ADRs to accepted before incorporating them
-- ❌ Change specs without ADRs
-- ❌ Keep old decisions in draft after release
-- ❌ Mix decisions from different versions
-
-## Quick Reference
-
-### Directory Creation
-```bash
-# Create spec structure anywhere
-mkdir -p $COMPONENT/spec/draft/decisions/{proposed,accepted,rejected}
-```
-
-### Version Release
-```bash
-# Ensure all ADRs are incorporated first!
-# Proposed folder should already be empty
-
-# Release a version
-cp -r $COMPONENT/spec/draft $COMPONENT/spec/$VERSION
-
-# Verify proposed is empty (should be)
-rm -rf $COMPONENT/spec/$VERSION/decisions/proposed
-
-# Update spec header to finalize version
-```
-
-### ADR Creation
-```bash
-# Create new ADR
-echo "# ADR-$ID: Title" > $COMPONENT/spec/draft/decisions/proposed/$NUM-$ID-name.md
-```
-
-## Release Documentation
-
-Each component should maintain:
-
-### CHANGELOG.md
-Track all changes between versions:
-```markdown
-## [v2.0] - 2025-01-03
-### Added
-- New feature X
-### Changed
-- Breaking change Y
-### Fixed
-- Bug Z
-```
-
-### RELEASING.md (Optional)
-Document the release process if it differs from this guide.
-
-## Integration
-
-Specifications can reference each other:
-
-```markdown
-## Dependencies
-This component implements:
-- [Protocol v1](../protocol-spec/spec/v1/SPEC.md)
-- [Client API v2.0.0](../packages/client/spec/v2.0.0/SPEC.md)
-```
-
-## Generic Specification Template
-
-Here's a simple template to start with. Adapt sections based on what you're specifying:
-
-```markdown
-# [Component Name] Specification
-
-**Version:** [draft or version number]
-**Status:** [Draft|Alpha|Beta|Stable]
-**Last Updated:** [YYYY-MM-DD]
-
-## Overview
-
-[What this component does and why it exists]
-
-## Scope
-
-[What this covers and what it doesn't]
-
-## Architecture
-
-[How it's structured - diagrams, components, data flow]
-
-## Interface
-
-[How others interact with this - API, commands, protocols]
-
-## Configuration
-
-[Any configuration options or settings]
-
-## Dependencies
-
-[What this needs to work]
-
-## Security Considerations
-
-[Security implications and mitigations]
-
-## Examples
-
-[Usage examples and patterns]
-
-## References
-
-[Links to related specs, documentation, or standards]
-```
-
-### Customizing the Template
-
-Add sections as needed:
-- **Error Handling** - For components with specific error patterns
-- **Performance** - For performance-critical components
-- **Testing** - For components with specific test requirements
-- **Migration** - When changing from previous versions
-- **Patterns** - Common usage patterns (can be separate PATTERNS.md)
-
-Remove sections that don't apply - keep it focused and relevant.
-
-## Questions?
-
-This guide provides a universal specification structure that can be applied to any component. Adapt the templates and process to fit your specific needs.
\ No newline at end of file
diff --git a/docs/templates.md b/docs/templates.md
index 8669380c..528a88df 100644
--- a/docs/templates.md
+++ b/docs/templates.md
@@ -656,4 +656,4 @@ The note-taker agent is designed for simple, conversational note-taking without
- Explore [Testing Guide](testing.md) for automated test scenarios
- See [Development Guide](development.md) for creating custom templates
-- Read the [Protocol Specification](../spec/protocol/v0.4/SPEC.md) for deeper protocol understanding
+- Read the [Protocol Specification](../spec/protocol/SPEC.md) for deeper protocol understanding
diff --git a/spec/README.md b/spec/README.md
index 347df132..8aacc2ab 100644
--- a/spec/README.md
+++ b/spec/README.md
@@ -1,102 +1,22 @@
# MEW Protocol Specifications
-This directory contains all MEW Protocol specifications organized by component.
+Complete specifications for MEW Protocol and its components.
-## Active Specifications
+## Specifications
-### Protocol (Core)
-- **[v0.4](protocol/v0.4/SPEC.md)** - Current stable release
- - [Accepted Decisions](protocol/v0.4/accepted/)
- - [Rejected Decisions](protocol/v0.4/rejected/)
-- **[Draft](protocol/draft/SPEC.md)** - Next version under development
- - [Accepted Decisions](protocol/draft/accepted/)
- - [Proposed Decisions](protocol/draft/proposed/)
- - [Rejected Decisions](protocol/draft/rejected/)
+- **[Protocol](protocol/SPEC.md)** - Core MEW Protocol (v0.4)
+- **[CLI](cli/SPEC.md)** - Command-line interface
+- **[SDK](sdk/SPEC.md)** - TypeScript SDK
+- **[Bridge](bridge/SPEC.md)** - MCP-MEW bridge
-### CLI (Command-Line Interface)
-- **[SPEC.md](cli/SPEC.md)** - Living specification
- - [Accepted Decisions](cli/accepted/)
- - [Proposed Decisions](cli/proposed/)
- - [Rejected Decisions](cli/rejected/)
+## Proposals
-### SDK (TypeScript)
-- **[SPEC.md](sdk/SPEC.md)** - SDK architecture and patterns
- - [Accepted Decisions](sdk/accepted/)
- - [Proposed Decisions](sdk/proposed/)
- - [Rejected Decisions](sdk/rejected/)
+Each spec area contains a `proposals/` folder with design documents for changes. Proposal status is tracked in `/CHANGELOG.md`.
-### Bridge (MCP Integration)
-- **[SPEC.md](bridge/SPEC.md)** - MCP-MEW bridge specification
- - [Accepted Decisions](bridge/accepted/)
- - [Proposed Decisions](bridge/proposed/)
- - [Rejected Decisions](bridge/rejected/)
-
-## Specification Development
-
-### Making Changes
-
-1. Create a decision document in the appropriate `proposed/` directory
-2. Discuss and refine in PR review
-3. Once accepted, move to `accepted/` directory
-4. Update the SPEC.md to incorporate the change
-
-### Decision Document Format
-
-Decision documents follow the Architecture Decision Record (ADR) format:
-
-```markdown
-# [Number]. [Title]
-
-**Status**: Proposed | Accepted | Rejected
-**Date**: YYYY-MM-DD
-
-## Context
-What is the issue we're facing?
-
-## Decision
-What are we doing about it?
-
-## Consequences
-What becomes easier or more difficult as a result?
-
-## Alternatives Considered
-What other options did we evaluate?
-```
-
-### Versioning Strategy
-
-- **Protocol**: Uses semantic versioning (v0.4, v0.5, etc.)
- - Breaking changes allowed in v0.x minor versions
- - `v0.4/` is current stable
- - `draft/` is next version under development
-
-- **CLI, SDK, Bridge**: Living documents (no versions)
- - Single `SPEC.md` evolves over time
- - Decisions track the evolution
- - Breaking changes documented in decisions
-
-## Archive
-
-Historical protocol specifications preserved in [archive/](archive/) for reference:
-- [v0.0](archive/protocol/v0.0/) - Initial specification
-- [v0.1](archive/protocol/v0.1/) - First iteration
-- [v0.2](archive/protocol/v0.2/) - Second iteration
-- [v0.3](archive/protocol/v0.3/) - Third iteration
-
-Historical CLI versions:
-- [v0.0.0](archive/cli/v0.0.0/) - Initial CLI spec
-- [v0.1.0](archive/cli/v0.1.0/) - First CLI iteration
-
-## Navigation
-
-- **For Users**: Start with [Protocol v0.4](protocol/v0.4/SPEC.md) to understand MEW Protocol
-- **For CLI Users**: See [CLI Spec](cli/SPEC.md) for command-line interface details
-- **For Developers**: Check [SDK Spec](sdk/SPEC.md) for TypeScript SDK patterns
-- **For MCP Integration**: Review [Bridge Spec](bridge/SPEC.md) for MCP-MEW bridge
+See [/CONTRIBUTING.md](/CONTRIBUTING.md) for the spec-driven development workflow.
## Related Documentation
-- [Main Documentation Hub](../docs/README.md)
-- [Development Guide](../docs/development.md)
-- [Testing Guide](../docs/testing.md)
-- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Contributing Guidelines](/CONTRIBUTING.md) - How to propose and implement changes
+- [Development Guide](../docs/development.md) - Development setup and practices
+- [Main Documentation Hub](../docs/README.md) - All documentation
diff --git a/spec/archive/cli/v0.0.0/SPEC.md b/spec/archive/cli/v0.0.0/SPEC.md
deleted file mode 100644
index 31d55a46..00000000
--- a/spec/archive/cli/v0.0.0/SPEC.md
+++ /dev/null
@@ -1,575 +0,0 @@
-# MEUP CLI Specification - Minimal Test Implementation
-
-**Version:** v0.0.0
-**Status:** Alpha
-**Release Date:** 2025-01-05
-**Last Updated:** 2025-01-05
-
-## Overview
-
-The MEUP CLI (`@meup/cli`) provides minimal command-line tools needed to execute the test plan in `/tests/TEST_PLAN.md`. This is a focused implementation that prioritizes getting tests running.
-
-## Scope
-
-This specification covers:
-- Gateway server with space configuration support
-- Client connections with FIFO mode for automation
-- Interactive space connection via terminal UI
-- Capability management through space.yaml
-- Process management for local agents
-
-## Architecture
-
-```
-@meup/cli
-├── Commands
-│ ├── gateway.js # Start gateway server
-│ ├── client.js # Connect as client (interactive or FIFO)
-│ ├── space.js # Space management (up/down)
-│ └── token.js # Generate test tokens
-├── SDK Dependencies
-│ ├── @meup/gateway
-│ ├── @meup/client
-│ ├── @meup/agent
-│ └── @meup/capability-matcher
-└── External Dependencies
- ├── js-yaml # Parse space.yaml config
- ├── commander # CLI argument parsing
- ├── ws # WebSocket client
- └── readline # Terminal UI
-```
-
-## Commands
-
-### `meup gateway start`
-
-Starts a gateway server.
-
-```bash
-meup gateway start [options]
-
-Options:
- --port Port to listen on (default: 8080)
- --space-config Path to space.yaml (default: ./space.yaml)
- --log-level debug|info|warn|error (default: info)
-```
-
-**Example:**
-```bash
-meup gateway start --port 8080 --space-config ./space.yaml --log-level debug
-```
-
-### `meup client connect`
-
-Connects to a gateway as a client. Supports interactive mode (default) or FIFO mode for automation.
-
-```bash
-meup client connect [options]
-
-Options:
- --gateway WebSocket URL (required)
- --space Space to join (required)
- --token Authentication token
- --participant-id Participant ID
- --fifo-in Input FIFO for automation (optional)
- --fifo-out Output FIFO for automation (optional)
- --no-interactive Disable interactive mode when using FIFOs
-```
-
-**Interactive Mode (default):**
-- Uses readline-based terminal interface
-- Plain text automatically becomes chat messages
-- JSON envelopes can be sent for any message type
-- Commands start with `/` (e.g., `/help`, `/exit`)
-- See responses in real-time
-- Press Ctrl+C to exit
-
-**FIFO Mode (for automation):**
-- Specify both --fifo-in and --fifo-out
-- Send JSON messages to fifo-in
-- Receive JSON messages from fifo-out
-- Add --no-interactive to disable terminal input
-
-**Examples:**
-```bash
-# Interactive mode (default)
-meup client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant-id human-user
-
-# FIFO mode for automation
-mkfifo cli-in cli-out
-meup client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant-id test-client \
- --fifo-in cli-in \
- --fifo-out cli-out \
- --no-interactive &
-```
-
-## Running Agents
-
-Agents are standalone executables that connect to the gateway. They are NOT started through the CLI but run directly or via space.yaml configuration.
-
-### Direct Execution
-
-```bash
-# Run example agents directly
-node ./agents/echo.js --gateway ws://localhost:8080 --token echo-token
-node ./agents/calculator.js --gateway ws://localhost:8080 --space test-space
-python ./my-custom-agent.py --gateway ws://localhost:8080
-
-# Each agent handles its own argument parsing
-```
-
-### Via Space Configuration
-
-Agents can be auto-started when the gateway starts:
-
-```yaml
-# space.yaml
-participants:
- echo-agent:
- command: "node"
- args: ["./agents/echo.js", "--gateway", "ws://localhost:8080"]
- auto_start: true
- tokens: ["echo-token"]
-```
-
-### `meup token create`
-
-Creates a simple test token.
-
-```bash
-meup token create [options]
-
-Options:
- --participant-id Participant ID (required)
- --capabilities JSON array of capabilities (required)
-```
-
-**Example:**
-```bash
-meup token create \
- --participant-id echo-agent \
- --capabilities '[{"kind":"chat"}]'
-```
-
-
-## FIFO Message Format
-
-Messages sent to/from FIFOs use MEUP v0.2 protocol format.
-
-**Input (to fifo-in):**
-Simplified format - CLI adds protocol envelope fields:
-```json
-{
- "kind": "chat",
- "payload": {
- "text": "Hello world"
- }
-}
-```
-
-**Output (from fifo-out):**
-Full MEUP v0.2 envelope:
-```json
-{
- "protocol": "meup/v0.2",
- "id": "msg-123",
- "ts": "2025-01-05T12:00:00Z",
- "from": "other-agent",
- "kind": "chat",
- "payload": {
- "text": "Response"
- }
-}
-```
-
-## Test Execution Flow
-
-The test plan uses the CLI as follows:
-
-1. **Start Gateway (with space config):**
- ```bash
- meup gateway start --port 8080 --space-config ./space.yaml > gateway.log 2>&1 &
- ```
-
-2. **Start Agents (if not auto-started):**
- ```bash
- # Agents are separate programs, not part of CLI
- # Example: node ./tests/agents/echo.js --gateway ws://localhost:8080 &
- # Or define in space.yaml with auto_start: true
- ```
-
-3. **Connect Test Clients with FIFOs:**
- ```bash
- mkfifo cli-in cli-out
- meup client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --fifo-in cli-in \
- --fifo-out cli-out &
- ```
-
-4. **Send Test Messages:**
- ```bash
- echo '{"kind":"chat","payload":{"text":"test"}}' > cli-in
- ```
-
-5. **Read Responses:**
- ```bash
- RESPONSE=$(timeout 5 cat cli-out | head -1)
- echo "$RESPONSE" | jq '.kind'
- ```
-
-## Minimal Implementation Requirements
-
-### Gateway
-- Start WebSocket server on specified port
-- Accept client connections
-- Route messages between participants in same space
-- Load space.yaml for capability configuration
-- Provide hooks for capability resolution
-
-### Client
-- Connect to gateway WebSocket
-- Join specified space
-- Support interactive mode (readline) by default
-- Support FIFO mode for automation
-- Read JSON from fifo-in, send to gateway (FIFO mode)
-- Write received messages to fifo-out as JSON (FIFO mode)
-
-
-### Token
-- Generate simple JWT or even just return the participant-id as token
-- Gateway can ignore tokens initially
-
-## Error Handling
-
-Minimal error handling for test scenarios:
-- Malformed JSON: Return system/error
-- Missing fields: Return system/error
-- Capability violations: Return system/error (if implemented)
-
-## Dependencies
-
-Minimal dependencies:
-- `ws` - WebSocket client/server
-- `commander` - Command parsing
-- Core SDK packages (@meup/gateway, @meup/client, @meup/agent)
-
-## Configuration
-
-### Space Configuration (space.yaml)
-
-The CLI manages participant capabilities through a `space.yaml` configuration file. This design separates authorization logic from the gateway implementation, allowing the gateway library to remain a pure protocol handler while the CLI manages the policy layer.
-
-#### Configuration Structure
-
-```yaml
-space:
- id: space-identifier
- name: "Human Readable Space Name"
- description: "Space description"
-
-participants:
- participant-id:
- tokens:
- - token-value-1
- - token-value-2
- capabilities:
- - kind: "mcp/*"
- - kind: "chat"
-
-defaults:
- capabilities:
- - kind: "mcp/proposal"
- - kind: "chat"
-```
-
-#### Capability Patterns
-
-Capabilities use JSON pattern matching as defined in MEUP v0.2:
-
-**Simple patterns:**
-```yaml
-capabilities:
- - kind: "*" # All capabilities
- - kind: "mcp/*" # All MCP messages (request, response, proposal)
- - kind: "chat" # Only chat messages
-```
-
-**Nested patterns for fine-grained control:**
-```yaml
-capabilities:
- - kind: "mcp/request"
- payload:
- method: "tools/call"
- params:
- name: "read_*" # Only read tools
- - kind: "mcp/response"
- - kind: "chat"
-```
-
-#### Gateway Integration Architecture
-
-The gateway library provides bidirectional hooks for capability management and participant lifecycle:
-
-```javascript
-// Gateway requests capability resolution from CLI
-gateway.setCapabilityResolver(async (token, participantId, messageKind) => {
- // CLI loads from space.yaml (may return subset of configured capabilities)
- const config = await loadSpaceConfig();
- const participant = findParticipantByToken(config, token);
-
- // CLI can choose to return only relevant capabilities for this message
- const relevantCaps = filterCapabilitiesForMessage(
- participant?.capabilities || config.defaults.capabilities,
- messageKind
- );
- return relevantCaps;
-});
-
-// Gateway notifies CLI when participants join
-gateway.onParticipantJoined(async (participantId, token, metadata) => {
- // CLI can update space.yaml with new participant
- if (!knownParticipant(participantId)) {
- await addParticipantToConfig(participantId, token, {
- type: 'key',
- capabilities: config.defaults.capabilities,
- first_seen: new Date().toISOString()
- });
- }
- // CLI may also spawn local agents based on space.yaml
- await spawnLocalAgents(config);
-});
-
-// Gateway provides authorization hook
-gateway.setAuthorizationHook(async (participantId, messageKind, capabilities) => {
- const required = getRequiredCapability(messageKind);
- return hasCapability(capabilities, required);
-});
-```
-
-#### Participant Lifecycle Management
-
-The space.yaml can define how local participants should be started:
-
-```yaml
-participants:
- calculator-agent:
- type: local
- command: "node"
- args: ["./agents/calculator.js", "--gateway", "ws://localhost:8080"]
- env:
- LOG_LEVEL: "debug"
- CACHE_DIR: "/tmp/calculator-cache"
- auto_start: true # CLI spawns this when space starts
- restart_policy: "on-failure"
- tokens:
- - calculator-token
- capabilities:
- - kind: "mcp/*"
- - kind: "chat"
-```
-
-The CLI handles:
-- **Process Management**: Starting/stopping local agents based on config
-- **Environment Setup**: Passing environment variables to agents
-- **Restart Policies**: Handling agent failures
-- **Dynamic Registration**: Adding new participants as they join
-
-The gateway only cares about:
-- **Token Validation**: Is this token valid?
-- **Capability Check**: Does this participant have this capability?
-- **Message Routing**: Protocol-level concerns
-
-This architecture enables:
-- **Separation of Concerns**: Gateway handles protocol, CLI handles operations
-- **Dynamic Participants**: New participants can be added at runtime
-- **Flexible Deployment**: Different environments can have different startup configs
-- **Testing**: Mock resolvers for unit tests
-- **Capability Subsetting**: CLI can return only needed capabilities per request
-
-#### Loading Configuration
-
-The CLI loads space configuration in order of precedence:
-1. Command-line flag: `--space-config path/to/space.yaml`
-2. Environment variable: `MEUP_SPACE_CONFIG`
-3. Default location: `./space.yaml`
-
-Example:
-```bash
-meup gateway start --port 8080 --space-config ./configs/production.yaml
-```
-
-## Space Management
-
-### `meup space up`
-
-Brings up all components of a space based on space.yaml configuration, optionally connecting interactively as a participant.
-
-```bash
-meup space up [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --participant Optional: Connect as this participant after bringing up space
- --detach, -d Run in background without connecting
-```
-
-This command:
-1. Starts the gateway based on space.yaml settings
-2. Starts all agents with `auto_start: true`
-3. Optionally connects you as a participant (see Participant Resolution below)
-
-When connecting as a participant, tokens and capabilities come from space.yaml - no need to specify them.
-
-#### Participant Resolution
-
-The CLI automatically determines which participant to connect as using this precedence:
-
-1. **Explicit flag**: `--participant ` always takes priority
-2. **Space default**: `default_participant` field in space.yaml
-3. **Single human**: Auto-selects if only one participant without a `command` field exists
-4. **Interactive prompt**: Shows list of human participants to choose from
-5. **System username**: Used if it matches a human participant (last resort)
-6. **Detached mode**: Runs without connecting if no participant can be determined
-
-Example space.yaml with participant resolution:
-```yaml
-space:
- id: my-space
- default_participant: developer # Optional default
-
-participants:
- developer: # Human participant (no command)
- tokens: ["dev-token"]
- capabilities:
- - kind: "mcp/*"
- - kind: "chat"
- echo-agent: # Agent participant (has command)
- command: "node"
- args: ["./agents/echo.js"]
- auto_start: true
- tokens: ["echo-token"]
- capabilities:
- - kind: "mcp/response"
- - kind: "chat"
- rjcorwin: # Matches system username
- tokens: ["rj-token"]
- capabilities:
- - kind: "mcp/proposal"
- - kind: "chat"
-```
-
-### `meup space down`
-
-Stops all components of a running space.
-
-```bash
-meup space down [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --force Force kill processes if graceful shutdown fails
-```
-
-This command:
-1. Disconnects all clients
-2. Stops all agents started by the space
-3. Shuts down the gateway
-4. Cleans up any temporary files
-
-### Terminal Interface
-
-#### Input Handling
-
-The terminal interface uses smart detection to handle both simple chat and full protocol messages:
-
-1. **Commands** (start with `/`): Execute special actions
-2. **JSON envelopes** (valid MEUP JSON): Send as-is for full protocol access
-3. **Plain text**: Automatically wrapped as chat messages
-
-Supported message kinds (per MEUP v0.2):
-- `chat` - Chat messages
-- `mcp/request` - MCP requests
-- `mcp/response` - MCP responses
-- `mcp/proposal` - MCP proposals
-- Others as defined in MEUP v0.2 specification
-
-Examples:
-```bash
-> Hello everyone # Sends chat message
-> {"kind": "mcp/request", ...} # Sends JSON envelope as-is
-> /help # Executes help command
-> How's it going? # Sends chat message
-> { invalid json # Sends as chat (not valid JSON)
-```
-
-#### Terminal Commands
-
-Special commands available when connected interactively:
-
-```
-/help Show available commands
-/participants List active participants
-/capabilities Show your current capabilities
-/chat Force text to be sent as chat (edge cases)
-/exit Disconnect from space
-```
-
-### Example Sessions
-
-#### Developer Review Session
-```bash
-# Bring up space and connect as developer
-meup space up --space-config ./code-review.yaml --participant developer
-
-# In another terminal, CI system connects with FIFOs for automation
-mkfifo ci-in ci-out
-meup client connect \
- --gateway ws://localhost:8080 \
- --space code-review \
- --participant ci-bot \
- --fifo-in ci-in \
- --fifo-out ci-out &
-```
-
-#### Test Automation Session
-```bash
-# Bring up the space in background
-meup space up --detach
-
-# Connect test clients with FIFOs
-mkfifo client1-in client1-out
-meup client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant test-client-1 \
- --fifo-in client1-in \
- --fifo-out client1-out &
-
-# Send test messages
-echo '{"kind":"chat","payload":{"text":"test"}}' > client1-in
-```
-
-## Next Steps
-
-After tests pass with this minimal implementation:
-1. ~~Add proper authentication~~ ✓ Token-based auth via space.yaml
-2. ~~Implement capability enforcement~~ ✓ Via resolver hooks
-3. ~~Add space configuration support~~ ✓ space.yaml specification
-4. Implement remaining features from `/cli/spec/next/SPEC.md`
-
-## Success Criteria
-
-This CLI successfully implements the test plan when:
-1. All test scenarios in TEST_PLAN.md can be executed
-2. Gateway starts and accepts connections
-3. Agents respond appropriately
-4. FIFO mode enables test automation
-5. Messages flow correctly between participants
\ No newline at end of file
diff --git a/spec/archive/cli/v0.0.0/decisions/accepted/001-a1b-agent-start-command.md b/spec/archive/cli/v0.0.0/decisions/accepted/001-a1b-agent-start-command.md
deleted file mode 100644
index 22e974a2..00000000
--- a/spec/archive/cli/v0.0.0/decisions/accepted/001-a1b-agent-start-command.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# ADR-a1b: Agent Start Command
-
-**Status:** Accepted
-**Date:** 2025-01-05
-**Incorporation:** Complete
-
-## Context
-
-The CLI specification includes a `meup agent start` command for starting agents. The TEST_PLAN.md currently uses this command with a `--type` flag to start built-in agents (echo, calculator, fulfiller).
-
-However, MEUP agents are just programs that connect to a gateway WebSocket. They can be:
-- Started directly as executables with appropriate arguments
-- Started via space.yaml configuration with `command` and `auto_start` fields
-- Started through a CLI wrapper command
-
-We need to decide whether the `meup agent start` command adds value or unnecessary complexity.
-
-## Options Considered
-
-### Option 1: Remove Agent Start Command
-
-No `meup agent start` command. Agents are started either:
-- Directly as executables: `node ./agents/echo.js --gateway ws://localhost:8080`
-- Via space.yaml with auto_start
-
-**Pros:**
-- Simplest approach - no unnecessary abstraction
-- Agents are just programs, no special handling
-- One less command to maintain
-- Clear separation: manual execution vs declarative config
-
-**Cons:**
-- TEST_PLAN.md needs updates
-- Users must know how to run their agents
-- No convenience wrapper for common options
-
-### Option 2: Keep Agent Start with Path
-
-Keep `meup agent start ` as a convenience wrapper.
-
-**Pros:**
-- Provides standard way to start agents
-- Can add common options/defaults
-- Easier for users who don't know agent requirements
-
-**Cons:**
-- Adds a layer of abstraction
-- Premature optimization - may not be needed
-- Another command to maintain and document
-
-### Option 3: Keep Agent Start with Types (Current)
-
-Keep `meup agent start --type echo|calculator|fulfiller`.
-
-**Pros:**
-- Simple for built-in test agents
-- TEST_PLAN.md stays unchanged
-
-**Cons:**
-- Limited to built-in agents only
-- Can't test custom agents
-- Inconsistent with "agents are just programs" principle
-
-## Decision
-
-**Recommended: Option 1 - Remove Agent Start Command**
-
-Remove the `meup agent start` command entirely. Agents are just programs that should be started directly or via space.yaml configuration.
-
-### Implementation Details
-
-1. **Direct execution for manual testing:**
- ```bash
- # Start agent directly (agent handles its own args)
- node ./agents/echo.js --gateway ws://localhost:8080 --token echo-token
-
- # Or with compiled executable
- ./agents/calculator --gateway ws://localhost:8080 --space test-space
-
- # Python agent
- python ./agents/custom.py --gateway ws://localhost:8080
- ```
-
-2. **Space.yaml for declarative configuration:**
- ```yaml
- participants:
- echo-agent:
- command: "node"
- args: ["./agents/echo.js", "--gateway", "ws://localhost:8080"]
- auto_start: true
- tokens: ["echo-token"]
-
- calculator:
- command: "./agents/calculator"
- args: ["--gateway", "ws://localhost:8080"]
- auto_start: true
- tokens: ["calc-token"]
- ```
-
-3. **Provide example agents with standard CLI interface:**
- ```
- agents/
- ├── echo.js # Example echo agent
- ├── calculator.js # Example calculator agent
- ├── fulfiller.js # Example fulfiller agent
- └── README.md # How to write agents
- ```
-
- Each agent is responsible for its own argument parsing:
- ```javascript
- // agents/echo.js
- const args = parseArgs(process.argv);
- const gateway = args.gateway || 'ws://localhost:8080';
- const token = args.token || 'echo-token';
- ```
-
-4. **Update TEST_PLAN.md to use direct execution:**
- ```bash
- # Old way (remove this)
- meup agent start --type echo --gateway ws://localhost:8080
-
- # New way
- node ./agents/echo.js --gateway ws://localhost:8080
- ```
-
-## Consequences
-
-### Positive
-- Simplest possible approach - no premature optimization
-- Agents are just programs, no special treatment needed
-- No abstraction layer to maintain
-- Clear separation: direct execution vs space.yaml config
-- Consistent with Unix philosophy (do one thing well)
-- Agents can be written in any language
-
-### Negative
-- TEST_PLAN.md needs updates to use direct execution
-- Users need to know how to run their agents (node, python, etc.)
-- No convenience wrapper for common options
-- Each agent must handle its own argument parsing
-
-### Mitigation
-- Provide well-documented example agents with standard CLI
-- Update TEST_PLAN.md with new commands
-- Document common patterns for agent argument handling
-- Consider adding `meup agent start` later if proven necessary
\ No newline at end of file
diff --git a/spec/archive/cli/v0.0.0/decisions/accepted/002-p4k-participant-id-resolution.md b/spec/archive/cli/v0.0.0/decisions/accepted/002-p4k-participant-id-resolution.md
deleted file mode 100644
index 30d778d1..00000000
--- a/spec/archive/cli/v0.0.0/decisions/accepted/002-p4k-participant-id-resolution.md
+++ /dev/null
@@ -1,249 +0,0 @@
-# ADR-p4k: Participant ID Resolution for Space Up
-
-**Status:** Accepted
-**Date:** 2025-01-05
-**Incorporation:** Complete
-
-## Context
-
-The `meup space up` command can optionally connect as a participant after starting the space infrastructure. Currently, users must explicitly provide `--participant ` to connect interactively. This creates friction for users who frequently connect to spaces.
-
-We need a low-friction way to determine the participant ID when not explicitly provided, while maintaining clarity about which participant is being used.
-
-## Options Considered
-
-### Option 1: Environment Variable
-
-Use `MEUP_PARTICIPANT_ID` environment variable as default.
-
-**Pros:**
-- Standard pattern in CLI tools
-- Easy to set in shell profile
-- Works across all spaces
-- Clear and explicit
-
-**Cons:**
-- Requires initial setup
-- May not be appropriate for all spaces
-- Could cause confusion if forgotten
-
-### Option 2: System Username with Prompt
-
-Use system username as default, prompt for confirmation.
-
-```bash
-$ meup space up
-> Connecting as participant 'rjcorwin' (your system username). Continue? [Y/n]
-```
-
-**Pros:**
-- Zero configuration to start
-- Natural default for single-user spaces
-- Interactive confirmation prevents mistakes
-
-**Cons:**
-- System username may not match participant ID
-- Extra prompt adds friction
-- May not work in automation
-
-### Option 3: Space Configuration Default
-
-Add `default_participant` field to space.yaml.
-
-```yaml
-space:
- id: my-space
- default_participant: developer
-
-participants:
- developer:
- tokens: [...]
-```
-
-**Pros:**
-- Space-specific defaults
-- No global configuration needed
-- Explicit in space definition
-
-**Cons:**
-- Only works for one user per space
-- Conflicts in shared repositories
-- Not portable across machines
-
-### Option 4: Interactive Selection
-
-If not provided, show list of available participants.
-
-```bash
-$ meup space up
-Select a participant to connect as:
- 1) developer
- 2) reviewer
- 3) observer
- > (none - run detached)
-Choice [none]: 1
-```
-
-**Pros:**
-- No configuration needed
-- Shows all options
-- Prevents wrong participant selection
-
-**Cons:**
-- Adds interactive step every time
-- Doesn't work in automation
-- More friction than other options
-
-### Option 5: Simple Cascading (Space Default + Interactive + System Username)
-
-Combine options 2, 3, and 4 in a simple cascade:
-1. Command line flag (--participant)
-2. Space configuration default_participant
-3. Interactive selection from available participants
-4. System username as last resort (only for human participants)
-
-**Pros:**
-- Simple and predictable
-- No global configuration needed
-- Prioritizes explicit choices over assumptions
-- System username only used when safe
-
-**Cons:**
-- No persistent user preference across spaces
-- May prompt more often than expected
-- System username may not always apply
-
-## Decision
-
-**Selected: Option 5 - Simple Cascading**
-
-We will implement a simple cascading resolution that checks space config, auto-selects single human participants, prompts interactively when multiple options exist, and falls back to system username only for human participants. This approach balances zero-friction defaults with explicit user control.
-
-### Implementation Details
-
-1. **Resolution Order:**
- ```
- 1. --participant flag (explicit)
- 2. space.yaml default_participant field
- 3. Single human participant (auto-select if only one)
- 4. Interactive selection (if multiple human participants)
- 5. System username (only if matches a non-agent participant)
- 6. Detached mode (final fallback)
- ```
-
-2. **Space Configuration:**
- ```yaml
- space:
- id: my-space
- default_participant: developer # Optional field
-
- participants:
- developer:
- tokens: [...]
- echo-agent:
- command: "node" # Has command = agent
- args: ["./agents/echo.js"]
- rjcorwin: # No command = human participant
- tokens: [...]
- ```
-
-3. **Resolution Logic:**
- ```javascript
- function resolveParticipant(args, spaceConfig) {
- // 1. Explicit flag
- if (args.participant) return args.participant;
- if (args.detach) return null;
-
- // 2. Space default
- if (spaceConfig.space?.default_participant) {
- console.log(`Using default participant: ${spaceConfig.space.default_participant}`);
- return spaceConfig.space.default_participant;
- }
-
- // Get human participants (no command field)
- const humanParticipants = Object.entries(spaceConfig.participants)
- .filter(([id, p]) => !p.command)
- .map(([id]) => id);
-
- // 3. Single human participant - auto-select
- if (humanParticipants.length === 1) {
- console.log(`Connecting as '${humanParticipants[0]}' (only human participant)`);
- return humanParticipants[0];
- }
-
- // 4. Interactive selection (if TTY and multiple humans)
- if (process.stdin.isTTY && humanParticipants.length > 1) {
- const choice = promptForParticipant(humanParticipants);
- if (choice !== null) return choice;
- }
-
- // 5. System username (only if matches a human participant)
- const username = os.userInfo().username;
- if (humanParticipants.includes(username)) {
- console.log(`Connecting as '${username}' (your system username)`);
- return username;
- }
-
- // 6. Detached fallback
- console.log('Running detached (no participant selected)');
- return null;
- }
- ```
-
-4. **Interactive Prompt:**
- ```bash
- $ meup space up
- Select participant to connect as:
- 1) developer (human)
- 2) reviewer (human)
- 3) observer (human)
- [echo-agent and other agents not shown]
- 0) none (run detached)
- Choice [0]: 1
- > Connecting as participant: developer
- ```
-
-5. **Examples:**
- ```bash
- # Explicit participant
- meup space up --participant reviewer
-
- # Uses default_participant from space.yaml
- meup space up # → connects as 'developer'
-
- # Single human participant (auto-selected)
- meup space up # → connects as 'developer' (only human)
-
- # Multiple human participants (interactive)
- meup space up # → prompts to choose between humans
-
- # System username fallback (only if no prompt)
- MEUP_NO_PROMPT=1 meup space up # → tries 'rjcorwin' if human
-
- # Detached mode
- meup space up --detach
- ```
-
-## Consequences
-
-### Positive
-- Simple implementation with clear precedence
-- Zero configuration required to get started
-- Auto-selects when there's only one human participant
-- Interactive prompt prevents wrong participant selection
-- System username only used when safe (human participants)
-- Agents automatically excluded from selection
-- No configuration files to manage
-
-### Negative
-- No persistent user preference across spaces
-- May prompt when multiple human participants exist
-- System username rarely used (only as last resort)
-- No environment variable override for automation
-
-### Mitigation
-- Clear messages about which participant is being used
-- Interactive prompt only shows human participants
-- Can always use explicit --participant flag
-- Space default_participant for common cases
-- Detached mode available for automation
\ No newline at end of file
diff --git a/spec/archive/cli/v0.0.0/decisions/accepted/003-t7m-terminal-input-handling.md b/spec/archive/cli/v0.0.0/decisions/accepted/003-t7m-terminal-input-handling.md
deleted file mode 100644
index 785a601e..00000000
--- a/spec/archive/cli/v0.0.0/decisions/accepted/003-t7m-terminal-input-handling.md
+++ /dev/null
@@ -1,252 +0,0 @@
-# ADR-t7m: Terminal Input Handling
-
-**Status:** Accepted
-**Date:** 2025-01-05
-**Incorporation:** Complete
-
-## Context
-
-When a user connects to a space interactively via `meup space up` or `meup client connect`, they can type input in the terminal. We need to decide how to handle non-command input (text that doesn't start with `/`).
-
-The terminal interface needs to balance:
-- Ease of use for humans
-- Ability to send different message types
-- Consistency with the MEUP protocol
-- Testing and debugging needs
-
-## Options Considered
-
-### Option 1: Plain Text as Chat
-
-Any non-command input is automatically wrapped as a chat message.
-
-```bash
-$ meup space up
-> Hello world
-# Sends: {"kind": "chat", "payload": {"text": "Hello world"}}
-```
-
-**Pros:**
-- Most intuitive for users
-- Similar to chat applications
-- Low friction for common case
-- Good for human interaction
-
-**Cons:**
-- Can only send chat messages easily
-- Need special syntax for other message types
-- Might be limiting for testing
-
-### Option 2: JSON Envelopes Required
-
-Users must type valid JSON for all messages.
-
-```bash
-$ meup space up
-> {"kind": "chat", "payload": {"text": "Hello"}}
-# Sends exactly what was typed
-```
-
-**Pros:**
-- Full protocol access
-- Consistent with FIFO mode
-- Good for testing/debugging
-- Can send any message type
-
-**Cons:**
-- Terrible UX for humans
-- Error-prone (JSON syntax)
-- High friction for common use
-- Not suitable for demos
-
-### Option 3: Smart Detection
-
-Detect JSON vs plain text and handle accordingly.
-
-```bash
-$ meup space up
-> Hello world
-# Sends: {"kind": "chat", "payload": {"text": "Hello world"}}
-
-> {"kind": "mcp/request", "payload": {...}}
-# Sends the JSON as-is
-```
-
-**Pros:**
-- Best of both worlds
-- Natural for humans
-- Full access when needed
-- Good for testing and demos
-
-**Cons:**
-- Ambiguity (what if someone wants to chat about JSON?)
-- More complex to implement
-- Might surprise users
-
-### Option 4: Mode Switching
-
-Start in chat mode, use commands to switch modes.
-
-```bash
-$ meup space up
-[chat mode]> Hello world
-# Sends: {"kind": "chat", "payload": {"text": "Hello world"}}
-
-[chat mode]> /mode json
-[json mode]> {"kind": "mcp/request", "payload": {...}}
-# Sends the JSON as-is
-
-[json mode]> /mode chat
-[chat mode]> Back to chatting
-```
-
-**Pros:**
-- Clear user intent
-- No ambiguity
-- Full protocol access
-- Explicit mode indicator
-
-**Cons:**
-- Extra step to switch modes
-- Users must remember current mode
-- More complex than Option 1
-
-### Option 5: Prefix-Based
-
-Use a prefix to indicate raw JSON input.
-
-```bash
-$ meup space up
-> Hello world
-# Sends: {"kind": "chat", "payload": {"text": "Hello world"}}
-
-> @json {"kind": "mcp/request", "payload": {...}}
-# Sends the JSON as-is
-
-> @mcp request tools/list
-# Sends: {"kind": "mcp/request", "payload": {"method": "tools/list"}}
-```
-
-**Pros:**
-- Clear intent per message
-- No mode to track
-- Can add shortcuts for common patterns
-- Extensible
-
-**Cons:**
-- Need to remember prefixes
-- Slightly more typing for non-chat
-
-## Decision
-
-**Recommended: Option 3 - Smart Detection**
-
-We need to support both simple chat for human interaction AND the ability to send any MEUP message type for testing and advanced use. Smart detection provides this flexibility while maintaining good UX.
-
-### Implementation Details
-
-1. **Detection Logic:**
- ```javascript
- function processInput(input) {
- const trimmed = input.trim();
-
- // 1. Check for commands
- if (trimmed.startsWith('/')) {
- return handleCommand(trimmed);
- }
-
- // 2. Try to parse as JSON
- if (trimmed.startsWith('{')) {
- try {
- const parsed = JSON.parse(trimmed);
- // Validate it looks like a MEUP message
- if (parsed.kind && parsed.payload) {
- return sendMessage(parsed);
- }
- } catch (e) {
- // Not valid JSON, treat as chat
- }
- }
-
- // 3. Default to chat
- return sendMessage({
- kind: 'chat',
- payload: {
- text: trimmed
- }
- });
- }
- ```
-
-2. **Usage Examples:**
- ```bash
- $ meup space up --participant developer
- Connected as 'developer' to space 'my-space'
-
- > Hello everyone
- # Sends: {"kind": "chat", "payload": {"text": "Hello everyone"}}
-
- > {"kind": "mcp/request", "payload": {"method": "tools/list"}}
- # Sends the JSON exactly as typed
-
- > How's the code review going?
- # Sends: {"kind": "chat", "payload": {"text": "How's the code review going?"}}
-
- > {"kind": "chat", "payload": {"text": "I can also send chat via JSON"}}
- # Sends the JSON exactly as typed
-
- > { this is not valid JSON }
- # Sends: {"kind": "chat", "payload": {"text": "{ this is not valid JSON }"}}
- ```
-
-3. **Escape Hatch:**
- For the edge case where someone wants to send a chat message that starts with `{`:
- ```bash
- > /chat {"foo": "bar"} is valid JSON
- # Forces chat mode, sends: {"kind": "chat", "payload": {"text": "{\"foo\": \"bar\"} is valid JSON"}}
- ```
-
-4. **Display Format:**
- ```bash
- > Hello
- [developer → all] chat: Hello
-
- > {"kind": "mcp/request", "payload": {"method": "tools/list"}}
- [developer → all] mcp/request: {"method": "tools/list"}
-
- [echo-agent → developer] mcp/response: {"tools": [...]}
-
- > Thanks!
- [developer → all] chat: Thanks!
- ```
-
-5. **Error Handling:**
- ```bash
- > {"kind": "invalid"}
- Error: Message missing required 'payload' field
-
- > {"not valid json
- # Treated as chat since it doesn't parse
- [developer → all] chat: {"not valid json
- ```
-
-## Consequences
-
-### Positive
-- Natural chat interface for humans
-- Full protocol access when needed
-- Good for both demos and testing
-- No mode switching required
-- Handles common cases elegantly
-
-### Negative
-- Slight ambiguity when chatting about JSON
-- More complex than pure chat mode
-- Detection logic could surprise users occasionally
-- Need to validate JSON structure
-
-### Mitigation
-- Provide `/chat` command for edge cases
-- Clear error messages for malformed JSON
-- Document the detection behavior clearly
-- Show message type in output for clarity
\ No newline at end of file
diff --git a/spec/archive/cli/v0.1.0/SPEC.md b/spec/archive/cli/v0.1.0/SPEC.md
deleted file mode 100644
index 2c24f4c9..00000000
--- a/spec/archive/cli/v0.1.0/SPEC.md
+++ /dev/null
@@ -1,833 +0,0 @@
-# MEW CLI Specification - Minimal Test Implementation
-
-**Version:** 0.1.0
-**Status:** Stable
-**Release Date:** 2025-01-10
-**Last Updated:** 2025-01-10
-
-## Overview
-
-The MEW CLI (`@mew/cli`) provides minimal command-line tools needed to execute the test plan in `/tests/TEST_PLAN.md`. This is a focused implementation that prioritizes getting tests running.
-
-## Scope
-
-This specification covers:
-- Gateway server with space configuration support
-- Client connections with FIFO mode for automation
-- Interactive space connection via terminal UI
-- Capability management through space.yaml
-- Process management for local agents
-
-## Architecture
-
-```
-@mew/cli
-├── Commands
-│ ├── gateway.js # Start gateway server
-│ ├── client.js # Connect as client (interactive or FIFO)
-│ ├── space.js # Space management (up/down/status)
-│ └── token.js # Generate test tokens
-├── SDK Dependencies
-│ ├── @mew/gateway
-│ ├── @mew/client
-│ ├── @mew/agent
-│ └── @mew/capability-matcher
-└── External Dependencies
- ├── pm2 # Process manager (embedded library)
- ├── js-yaml # Parse space.yaml config
- ├── commander # CLI argument parsing
- ├── ws # WebSocket client
- └── readline # Terminal UI
-```
-
-## Commands
-
-### `mew gateway start`
-
-Starts a gateway server.
-
-```bash
-mew gateway start [options]
-
-Options:
- --port Port to listen on (default: 8080)
- --space-config Path to space.yaml (default: ./space.yaml)
- --log-level debug|info|warn|error (default: info)
-```
-
-**Example:**
-```bash
-mew gateway start --port 8080 --space-config ./space.yaml --log-level debug
-```
-
-### `mew client connect`
-
-Connects to a gateway as a client. Supports interactive mode (default) or FIFO mode for automation.
-
-```bash
-mew client connect [options]
-
-Options:
- --gateway WebSocket URL (required)
- --space Space to join (required)
- --token Authentication token
- --participant-id Participant ID
- --fifo-in Input FIFO for automation (optional)
- --fifo-out Output FIFO for automation (optional)
- --no-interactive Disable interactive mode when using FIFOs
-```
-
-**Interactive Mode (default):**
-- Uses readline-based terminal interface
-- Plain text automatically becomes chat messages
-- JSON envelopes can be sent for any message type
-- Commands start with `/` (e.g., `/help`, `/exit`)
-- See responses in real-time
-- Press Ctrl+C to exit
-
-**FIFO Mode (for automation):**
-- Specify both --fifo-in and --fifo-out
-- Send JSON messages to fifo-in
-- Receive JSON messages from fifo-out
-- Add --no-interactive to disable terminal input
-
-**Examples:**
-```bash
-# Interactive mode (default)
-mew client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant-id human-user
-
-# FIFO mode for automation
-mkfifo cli-in cli-out
-mew client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant-id test-client \
- --fifo-in cli-in \
- --fifo-out cli-out \
- --no-interactive &
-```
-
-## Running Agents
-
-Agents are standalone executables that connect to the gateway. They are NOT started through the CLI but run directly or via space.yaml configuration.
-
-### Direct Execution
-
-```bash
-# Run example agents directly
-node ./agents/echo.js --gateway ws://localhost:8080 --token echo-token
-node ./agents/calculator.js --gateway ws://localhost:8080 --space test-space
-python ./my-custom-agent.py --gateway ws://localhost:8080
-
-# Each agent handles its own argument parsing
-```
-
-### Via Space Configuration
-
-Agents can be auto-started when the gateway starts:
-
-```yaml
-# space.yaml
-participants:
- echo-agent:
- command: "node"
- args: ["./agents/echo.js", "--gateway", "ws://localhost:8080"]
- auto_start: true
- tokens: ["echo-token"]
-```
-
-### `mew token create`
-
-Creates a simple test token.
-
-```bash
-mew token create [options]
-
-Options:
- --participant-id Participant ID (required)
- --capabilities JSON array of capabilities (required)
-```
-
-**Example:**
-```bash
-mew token create \
- --participant-id echo-agent \
- --capabilities '[{"kind":"chat"}]'
-```
-
-
-## FIFO Message Format
-
-Messages sent to/from FIFOs use MEW v0.4 protocol format.
-
-**Input (to fifo-in):**
-Simplified format - CLI adds protocol envelope fields:
-```json
-{
- "kind": "chat",
- "payload": {
- "text": "Hello world"
- }
-}
-```
-
-**Output (from fifo-out):**
-Full MEW v0.4 envelope:
-```json
-{
- "protocol": "mew/v0.4",
- "id": "msg-123",
- "ts": "2025-01-05T12:00:00Z",
- "from": "other-agent",
- "kind": "chat",
- "payload": {
- "text": "Response"
- }
-}
-```
-
-## Test Execution Flow
-
-The test plan uses the CLI as follows:
-
-1. **Start Gateway (with space config):**
- ```bash
- mew gateway start --port 8080 --space-config ./space.yaml > gateway.log 2>&1 &
- ```
-
-2. **Start Agents (if not auto-started):**
- ```bash
- # Agents are separate programs, not part of CLI
- # Example: node ./tests/agents/echo.js --gateway ws://localhost:8080 &
- # Or define in space.yaml with auto_start: true
- ```
-
-3. **Connect Test Clients with FIFOs:**
- ```bash
- mkfifo cli-in cli-out
- mew client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --fifo-in cli-in \
- --fifo-out cli-out &
- ```
-
-4. **Send Test Messages:**
- ```bash
- echo '{"kind":"chat","payload":{"text":"test"}}' > cli-in
- ```
-
-5. **Read Responses:**
- ```bash
- RESPONSE=$(timeout 5 cat cli-out | head -1)
- echo "$RESPONSE" | jq '.kind'
- ```
-
-## Minimal Implementation Requirements
-
-### Gateway
-- Start WebSocket server on specified port
-- Accept client connections
-- Route messages between participants in same space
-- Load space.yaml for capability configuration
-- Provide hooks for capability resolution
-
-### Client
-- Connect to gateway WebSocket
-- Join specified space
-- Support interactive mode (readline) by default
-- Support FIFO mode for automation
-- Read JSON from fifo-in, send to gateway (FIFO mode)
-- Write received messages to fifo-out as JSON (FIFO mode)
-
-
-### Token
-- Generate simple JWT or even just return the participant-id as token
-- Gateway can ignore tokens initially
-
-## Error Handling
-
-Minimal error handling for test scenarios:
-- Malformed JSON: Return system/error
-- Missing fields: Return system/error
-- Capability violations: Return system/error (if implemented)
-
-## Dependencies
-
-Minimal dependencies:
-- `ws` - WebSocket client/server
-- `commander` - Command parsing
-- Core SDK packages (@mew/gateway, @mew/client, @mew/agent)
-
-## Configuration
-
-### Space Configuration (space.yaml)
-
-The CLI manages participant capabilities through a `space.yaml` configuration file. This design separates authorization logic from the gateway implementation, allowing the gateway library to remain a pure protocol handler while the CLI manages the policy layer.
-
-#### Configuration Structure
-
-```yaml
-space:
- id: space-identifier
- name: "Human Readable Space Name"
- description: "Space description"
-
-participants:
- participant-id:
- tokens:
- - token-value-1
- - token-value-2
- capabilities:
- - kind: "mcp/*"
- - kind: "chat"
-
-defaults:
- capabilities:
- - kind: "mcp/proposal"
- - kind: "chat"
-```
-
-#### Capability Patterns
-
-Capabilities use JSON pattern matching as defined in MEW v0.4:
-
-**Simple patterns:**
-```yaml
-capabilities:
- - kind: "*" # All capabilities
- - kind: "mcp/*" # All MCP messages (request, response, proposal)
- - kind: "chat" # Only chat messages
-```
-
-**Nested patterns for fine-grained control:**
-```yaml
-capabilities:
- - kind: "mcp/request"
- payload:
- method: "tools/call"
- params:
- name: "read_*" # Only read tools
- - kind: "mcp/response"
- - kind: "chat"
-```
-
-#### Gateway Integration Architecture
-
-The gateway library provides bidirectional hooks for capability management and participant lifecycle:
-
-```javascript
-// Gateway requests capability resolution from CLI
-gateway.setCapabilityResolver(async (token, participantId, messageKind) => {
- // CLI loads from space.yaml (may return subset of configured capabilities)
- const config = await loadSpaceConfig();
- const participant = findParticipantByToken(config, token);
-
- // CLI can choose to return only relevant capabilities for this message
- const relevantCaps = filterCapabilitiesForMessage(
- participant?.capabilities || config.defaults.capabilities,
- messageKind
- );
- return relevantCaps;
-});
-
-// Gateway notifies CLI when participants join
-gateway.onParticipantJoined(async (participantId, token, metadata) => {
- // CLI can update space.yaml with new participant
- if (!knownParticipant(participantId)) {
- await addParticipantToConfig(participantId, token, {
- type: 'key',
- capabilities: config.defaults.capabilities,
- first_seen: new Date().toISOString()
- });
- }
- // CLI may also spawn local agents based on space.yaml
- await spawnLocalAgents(config);
-});
-
-// Gateway provides authorization hook
-gateway.setAuthorizationHook(async (participantId, messageKind, capabilities) => {
- const required = getRequiredCapability(messageKind);
- return hasCapability(capabilities, required);
-});
-```
-
-#### Participant Lifecycle Management
-
-The space.yaml can define how local participants should be started:
-
-```yaml
-participants:
- calculator-agent:
- type: local
- command: "node"
- args: ["./agents/calculator.js", "--gateway", "ws://localhost:8080"]
- env:
- LOG_LEVEL: "debug"
- CACHE_DIR: "/tmp/calculator-cache"
- auto_start: true # CLI spawns this when space starts
- restart_policy: "on-failure"
- tokens:
- - calculator-token
- capabilities:
- - kind: "mcp/*"
- - kind: "chat"
-```
-
-#### FIFO and Output Configuration
-
-Participants can be configured with FIFOs for automation and testing:
-
-```yaml
-participants:
- test-client:
- tokens: ["test-token"]
- capabilities:
- - kind: "chat"
- fifo: true # Create input FIFO (and output FIFO unless output_log is set)
- output_log: "./logs/test-client.log" # Redirect output to file (non-blocking)
- auto_connect: true # Auto-connect when space starts
-```
-
-**FIFO Configuration Options:**
-
-- `fifo: true` - Creates FIFOs for the participant:
- - When `output_log` is NOT set: Creates both input and output FIFOs
- - When `output_log` IS set: Creates only input FIFO, output goes to log file
-
-- `output_log: ` - Redirects client output to a file instead of FIFO:
- - Prevents blocking issues in automated tests
- - Allows analysis of output after test completion
- - Appends to file if it exists
-
-- `auto_connect: true` - Automatically connects the client when space starts
-
-**Use Cases:**
-
-```yaml
-# Automated testing (non-blocking)
-test-client:
- fifo: true
- output_log: "./logs/test-output.log" # Output to file
- auto_connect: true
-
-# Interactive debugging (traditional FIFOs)
-debug-client:
- fifo: true
- # No output_log means both FIFOs are created
- auto_connect: false # Connect manually for debugging
-
-# Agent without FIFOs
-echo-agent:
- fifo: false
- auto_start: true
- command: "node"
- args: ["./agents/echo.js"]
-```
-
-The CLI handles:
-- **Process Management**: Starting/stopping local agents based on config
-- **Environment Setup**: Passing environment variables to agents
-- **Restart Policies**: Handling agent failures
-- **Dynamic Registration**: Adding new participants as they join
-
-The gateway only cares about:
-- **Token Validation**: Is this token valid?
-- **Capability Check**: Does this participant have this capability?
-- **Message Routing**: Protocol-level concerns
-
-This architecture enables:
-- **Separation of Concerns**: Gateway handles protocol, CLI handles operations
-- **Dynamic Participants**: New participants can be added at runtime
-- **Flexible Deployment**: Different environments can have different startup configs
-- **Testing**: Mock resolvers for unit tests
-- **Capability Subsetting**: CLI can return only needed capabilities per request
-
-#### Loading Configuration
-
-The CLI loads space configuration in order of precedence:
-1. Command-line flag: `--space-config path/to/space.yaml`
-2. Environment variable: `MEW_SPACE_CONFIG`
-3. Default location: `./space.yaml`
-
-Example:
-```bash
-mew gateway start --port 8080 --space-config ./configs/production.yaml
-```
-
-## Process Management
-
-The CLI uses PM2 as an embedded library for reliable process management. This ensures that gateway and agent processes remain running even after the parent CLI command exits.
-
-### PM2 Integration Architecture
-
-PM2 is used programmatically as a library, not as a global tool:
-
-```javascript
-// Each space gets its own isolated PM2 daemon
-process.env.PM2_HOME = path.join(spaceDir, '.mew/pm2');
-
-// Connect to space-specific PM2 daemon
-const pm2 = require('pm2');
-pm2.connect((err) => {
- // All PM2 operations are space-local
-});
-```
-
-### Space-Local Process Management
-
-Each space maintains complete isolation:
-
-```
-space-directory/
-├── space.yaml # Space configuration
-├── .mew/
-│ ├── pm2/ # PM2 daemon for this space only
-│ │ ├── pm2.log # PM2 daemon logs
-│ │ ├── pm2.pid # Daemon process ID
-│ │ └── pids/ # Managed process PIDs
-│ └── pids.json # Space metadata
-├── logs/ # Process output logs
-│ ├── gateway.log
-│ └── agent-*.log
-└── fifos/ # FIFO pipes if configured
-```
-
-Benefits of this approach:
-- **No global PM2 required**: PM2 is bundled with the CLI
-- **Complete isolation**: Multiple spaces can run simultaneously
-- **Self-contained**: All artifacts stay within the space directory
-- **Transparent**: Users don't need to know PM2 is being used
-- **Reliable**: Processes survive parent CLI exit
-
-## Space Management
-
-### `mew space up`
-
-Brings up all components of a space based on space.yaml configuration, optionally connecting interactively as a participant.
-
-```bash
-mew space up [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --port Gateway port (default: from config or 8080)
- --participant Connect as this participant
- --interactive, -i Connect interactively after starting space
- --detach, -d Run in background (incompatible with -i)
-```
-
-This command:
-1. Creates space-local PM2 daemon in `.mew/pm2/`
-2. Starts the gateway using PM2 for process management
-3. Starts all agents with `auto_start: true` via PM2
-4. If `-i` flag is present: Connects interactively as a participant
-5. If `-d` flag is present: Runs in background without connecting
-6. If neither flag: Starts space and exits (current behavior)
-
-All processes are managed by PM2 and will continue running after the CLI exits. When connecting as a participant, tokens and capabilities come from space.yaml - no need to specify them.
-
-#### Participant Resolution
-
-The CLI automatically determines which participant to connect as using this precedence:
-
-1. **Explicit flag**: `--participant ` always takes priority
-2. **Space default**: `default_participant` field in space.yaml
-3. **Single human**: Auto-selects if only one participant without a `command` field exists
-4. **Interactive prompt**: Shows list of human participants to choose from
-5. **System username**: Used if it matches a human participant (last resort)
-6. **Detached mode**: Runs without connecting if no participant can be determined
-
-Example space.yaml with participant resolution:
-```yaml
-space:
- id: my-space
- default_participant: developer # Optional default
-
-participants:
- developer: # Human participant (no command)
- tokens: [...]
- echo-agent: # Agent participant (has command)
- command: "node"
- args: ["./agents/echo.js"]
- auto_start: true
- rjcorwin: # Matches system username
- tokens: [...]
-```
-
-### `mew space status`
-
-Shows the status of running space processes.
-
-```bash
-mew space status [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --json Output as JSON
-```
-
-This command:
-1. Connects to the space-local PM2 daemon
-2. Lists all managed processes with their status
-3. Shows gateway health check results
-4. Displays connected participants
-
-### `mew space connect`
-
-Connects interactively to a running space.
-
-```bash
-mew space connect [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --participant Connect as this participant
- --space-dir Directory of space to connect to (default: .)
- --gateway Override gateway URL (default: from running space)
-```
-
-This command:
-1. Checks if space is running in current/specified directory
-2. Loads space configuration
-3. Resolves participant (same logic as `space up`)
-4. Connects interactively to the space
-5. Shows interactive terminal UI
-
-Error handling:
-- If space not running: "No running space found. Use 'mew space up' first."
-- If no participant resolved: "No participant found. Specify with --participant"
-- If connection fails: Shows helpful error with gateway URL
-
-### `mew space down`
-
-Stops all components of a running space.
-
-```bash
-mew space down [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --force Force kill processes if graceful shutdown fails
-```
-
-This command:
-1. Disconnects all clients
-2. Stops all PM2-managed processes for this space
-3. Shuts down the space-local PM2 daemon
-4. Cleans up FIFOs and temporary files
-5. Preserves logs for debugging
-
-### `mew space clean`
-
-Cleans up space artifacts such as logs, FIFOs, and temporary files. Provides safety checks to prevent accidental data loss.
-
-```bash
-mew space clean [options]
-
-Options:
- --all Clean everything including .mew directory
- --logs Clean only log files
- --fifos Clean only FIFO pipes
- --force Skip confirmation prompts
- --dry-run Show what would be cleaned without doing it
-```
-
-**Default behavior (no flags):**
-- Cleans `logs/*` (except current session if running)
-- Cleans `fifos/*` (except active pipes)
-- Cleans temporary response files
-- Preserves `.mew/` directory (contains process state)
-
-**With `--all`:**
-- Everything from default cleaning
-- Removes `.mew/` directory entirely
-- Stops PM2 daemon for this space
-
-**Safety features:**
-- Warns if space is currently running
-- Requires confirmation for destructive operations
-- Never cleans active FIFO pipes
-- Preserves space.yaml and agent files
-- Shows summary of what will be cleaned
-
-**Examples:**
-```bash
-# Clean logs after debugging session
-mew space clean --logs
-
-# Start completely fresh for testing
-mew space down
-mew space clean --all
-
-# Check what would be cleaned
-mew space clean --dry-run
-
-# CI/CD cleanup (no prompts)
-mew space down
-mew space clean --all --force
-```
-
-## Interactive Terminal Interface
-
-The interactive connection feature provides a lightweight terminal UI for sending and receiving MEW protocol messages. This is a protocol debugging tool with convenience features, not a polished chat interface.
-
-### Input Processing
-
-The terminal interface uses smart input detection with clear rules and escape hatches:
-
-#### Detection Rules (applied in order):
-1. **Commands** (starts with `/`): Execute command
-2. **Valid JSON** (parseable as JSON): Send as-is if valid envelope, otherwise wrap
-3. **Plain text**: Wrap as chat message
-
-#### Input Examples:
-```bash
-> Hello everyone # Sends chat message
-> {"kind": "chat", "payload": {"text": "hi"}} # Partial envelope - adds protocol fields
-> {"kind": "mcp/request", ...} # Sends JSON envelope
-> /help # Executes help command
-> { invalid json # Sends as chat (not valid JSON)
-> /chat {"actual": "json"} # Forces JSON to be sent as chat text
-> /json {"kind": "custom"} # Forces input as protocol message
-```
-
-### Message Display Format
-
-All messages shown with consistent format:
-```
-[timestamp] direction participant kind
-└─ payload preview
-```
-
-Examples:
-```
-[10:23:45] → you chat
-└─ "Hello everyone"
-
-[10:23:46] ← echo-agent chat
-└─ "Echo: Hello everyone"
-
-[10:23:50] → you mcp/request
-└─ method: "tools/list", to: ["calculator"]
-
-[10:23:51] ← calculator mcp/response
-└─ tools: [3 tools]
-```
-
-Verbose mode (`/verbose`) shows full JSON messages.
-
-### Terminal Commands
-
-#### Essential commands:
-```
-/help Show available commands
-/participants List active participants
-/capabilities Show your current capabilities
-/verbose Toggle verbose output (show full JSON)
-/json Force input as JSON (escape hatch)
-/chat Force input as chat (escape hatch)
-/replay Show last N messages
-/clear Clear screen
-/exit Disconnect and exit
-```
-
-#### Future commands (not in initial implementation):
-```
-/filter Filter messages by kind
-/save Save session to file
-/load Replay messages from file
-/stats Show message statistics
-```
-
-### Output Filtering
-
-Control what's displayed:
-- System messages (welcome, presence) - dimmed by default
-- Heartbeats - hidden by default
-- Chat messages - normal color
-- MCP messages - highlighted
-- Errors - red
-
-Configuration via environment:
-```bash
-MEW_INTERACTIVE_SHOW_HEARTBEAT=true
-MEW_INTERACTIVE_SHOW_SYSTEM=true
-MEW_INTERACTIVE_COLOR=false # Disable colors
-```
-
-### Interactive Mode Overrides
-
-When in interactive mode, certain participant configurations are overridden:
-- `fifo: true` → Ignored (use interactive terminal instead)
-- `output_log` → Ignored (output to terminal)
-- `auto_connect` → Ignored (we're manually connecting)
-
-The interactive connection always uses:
-- Terminal input (stdin)
-- Terminal output (stdout)
-- Readline-based interface
-
-### Example Sessions
-
-#### Interactive Development Session
-```bash
-# Start fresh and connect immediately
-mew space up -i
-
-# In another terminal, connect as different participant
-mew space connect --participant admin
-
-# Connect to space in another directory
-mew space connect --space-dir ../other-project
-
-# In another terminal, CI system connects with FIFOs for automation
-mkfifo ci-in ci-out
-mew client connect \
- --gateway ws://localhost:8080 \
- --space code-review \
- --participant ci-bot \
- --fifo-in ci-in \
- --fifo-out ci-out &
-```
-
-#### Mixed Interactive and Automation Session
-```bash
-# Start space in background
-mew space up -d
-
-# Connect interactively to debug
-mew space connect --participant debugger
-
-# Also connect test clients with FIFOs for automation
-mkfifo client1-in client1-out
-mew client connect \
- --gateway ws://localhost:8080 \
- --space test-space \
- --participant test-client-1 \
- --fifo-in client1-in \
- --fifo-out client1-out &
-
-# Send test messages
-echo '{"kind":"chat","payload":{"text":"test"}}' > client1-in
-```
-
-## Next Steps
-
-After tests pass with this minimal implementation:
-1. ~~Add proper authentication~~ ✓ Token-based auth via space.yaml
-2. ~~Implement capability enforcement~~ ✓ Via resolver hooks
-3. ~~Add space configuration support~~ ✓ space.yaml specification
-4. Implement remaining features from `/cli/spec/next/SPEC.md`
-
-## Success Criteria
-
-This CLI successfully implements the test plan when:
-1. All test scenarios in TEST_PLAN.md can be executed
-2. Gateway starts and accepts connections
-3. Agents respond appropriately
-4. FIFO mode enables test automation
-5. Messages flow correctly between participants
\ No newline at end of file
diff --git a/spec/archive/cli/v0.1.0/decisions/accepted/005-iui-interactive-ui-architecture.md b/spec/archive/cli/v0.1.0/decisions/accepted/005-iui-interactive-ui-architecture.md
deleted file mode 100644
index cbd3aa76..00000000
--- a/spec/archive/cli/v0.1.0/decisions/accepted/005-iui-interactive-ui-architecture.md
+++ /dev/null
@@ -1,395 +0,0 @@
-# ADR-iui: Interactive UI Architecture
-
-**Status:** Accepted
-**Date:** 2025-01-10
-**Incorporation:** Complete
-
-## Context
-
-The interactive connection feature needs a user interface for sending and receiving MEW protocol messages. The goal is to create a dead-simple implementation that:
-- Shows all protocol messages (sent and received)
-- Provides lightweight helpers for common tasks
-- Remains useful for debugging even after better UIs are created
-- Requires minimal dependencies and complexity
-
-This is explicitly NOT trying to be a polished chat interface or sophisticated client. It's a protocol debugging tool with convenience features.
-
-## Options Considered
-
-### Option 1: Raw Protocol Mode Only
-
-Show only JSON messages, require full JSON input:
-```
-< {"protocol":"mew/v0.4","kind":"system/welcome",...}
-> {"protocol":"mew/v0.4","kind":"chat","payload":{"text":"hello"}}
-< {"protocol":"mew/v0.4","kind":"chat","from":"echo",...}
-```
-
-**Pros:**
-- Purest protocol view
-- No ambiguity about what's being sent
-- Easiest to implement
-
-**Cons:**
-- Tedious to type full envelopes
-- Hard to read in terminal
-- Not practical for actual use
-
-### Option 2: Smart Input Detection
-
-Detect input type and handle accordingly:
-- JSON → Send as protocol message
-- `/command` → Execute command
-- Plain text → Auto-wrap as chat message
-
-**Pros:**
-- Natural for both simple and complex usage
-- Progressive disclosure of complexity
-- Convenient for common cases
-
-**Cons:**
-- Edge cases (what if chat text starts with `{`?)
-- "Magic" behavior might confuse users
-- Need escape hatches for edge cases
-
-### Option 3: Modal Interface
-
-Different modes for different message types:
-```
-[chat mode] > Hello
-[mcp mode] > tools/list
-[raw mode] > {"kind":"custom","payload":{}}
-```
-
-**Pros:**
-- Clear what mode you're in
-- Optimized input per mode
-- No ambiguity
-
-**Cons:**
-- Mode switching is cumbersome
-- Another thing to learn
-- State to manage
-
-### Option 4: Prefix-Based Commands
-
-Everything is explicit with prefixes:
-```
-> chat: Hello everyone
-> mcp: tools/list
-> raw: {"kind":"custom","payload":{}}
-> /help
-```
-
-**Pros:**
-- Always explicit
-- No ambiguity
-- Easy to extend
-
-**Cons:**
-- More typing for common cases
-- Less natural than smart detection
-
-## Decision
-
-Implement **Option 2: Smart Input Detection** with clear rules and escape hatches.
-
-This provides the best balance of simplicity and power while maintaining the tool's debugging focus.
-
-### Implementation Details
-
-#### Input Processing Pipeline
-
-```
-User Input → Input Detector → Message Builder → WebSocket Send
- ↓
- Command Handler
-```
-
-#### Input Detection Rules
-
-Applied in order:
-1. **Commands** (starts with `/`): Execute command
-2. **Valid JSON** (parseable as JSON): Send as-is if valid envelope, otherwise wrap
-3. **Plain text**: Wrap as chat message
-
-```javascript
-function processInput(input) {
- // 1. Commands
- if (input.startsWith('/')) {
- return handleCommand(input);
- }
-
- // 2. Try JSON
- try {
- const json = JSON.parse(input);
- if (isValidEnvelope(json)) {
- // Full envelope - send as-is
- return sendMessage(json);
- } else if (json.kind) {
- // Partial envelope - add protocol fields
- return sendMessage(wrapEnvelope(json));
- } else {
- // Not an envelope - treat as chat
- return sendChat(JSON.stringify(json));
- }
- } catch {
- // 3. Plain text - send as chat
- return sendChat(input);
- }
-}
-```
-
-#### Display Format
-
-All messages shown with consistent format:
-```
-[timestamp] direction participant kind
-└─ payload preview
-```
-
-Examples:
-```
-[10:23:45] → you chat
-└─ "Hello everyone"
-
-[10:23:46] ← echo-agent chat
-└─ "Echo: Hello everyone"
-
-[10:23:50] → you mcp/request
-└─ method: "tools/list", to: ["calculator"]
-
-[10:23:51] ← calculator mcp/response
-└─ tools: [3 tools]
-```
-
-Verbose mode (`/verbose` command) shows full JSON:
-```
-[10:23:45] → you chat
-{
- "protocol": "mew/v0.4",
- "id": "msg-123",
- "kind": "chat",
- "payload": {"text": "Hello"}
-}
-```
-
-#### Commands
-
-Essential commands for debugging:
-```
-/help Show available commands
-/participants List active participants
-/capabilities Show your capabilities
-/verbose Toggle verbose output
-/json Force input as JSON (escape hatch)
-/chat Force input as chat (escape hatch)
-/replay Show last N messages
-/clear Clear screen
-/exit Disconnect and exit
-```
-
-Future commands (not in initial implementation):
-```
-/filter Filter messages by kind
-/save Save session to file
-/load Replay messages from file
-/stats Show message statistics
-```
-
-#### Message Building Helpers
-
-Shortcuts for common MEW protocol messages:
-```javascript
-// Partial envelope completion
-{"kind": "chat", "payload": {"text": "hi"}}
-// Becomes full envelope with protocol, id, ts
-
-// MCP shortcuts (future)
-{"kind": "mcp/request", "method": "tools/list"}
-// Adds proper payload structure
-
-// Direct targeting
-{"kind": "chat", "to": ["agent-1"], "text": "hi"}
-// Restructures into proper envelope
-```
-
-#### Output Filtering
-
-Control what's displayed:
-- System messages (welcome, presence) - dimmed by default
-- Heartbeats - hidden by default
-- Chat messages - normal color
-- MCP messages - highlighted
-- Errors - red
-
-Configuration via environment or flags:
-```bash
-MEW_INTERACTIVE_SHOW_HEARTBEAT=true
-MEW_INTERACTIVE_SHOW_SYSTEM=true
-MEW_INTERACTIVE_COLOR=false # Disable colors
-```
-
-#### Terminal UI Components
-
-Minimal UI using just readline and ANSI codes:
-```
-┌─ MEW Interactive (space: dev-space, participant: human) ──────┐
-│ │
-│ [10:23:45] → you chat │
-│ └─ "Hello everyone" │
-│ │
-│ [10:23:46] ← echo-agent chat │
-│ └─ "Echo: Hello everyone" │
-│ │
-└────────────────────────────────────────────────────────────────┘
-> _
-```
-
-Status line shows:
-- Connected/disconnected state
-- Current space
-- Current participant
-- Message count
-- Error state (if any)
-
-## Consequences
-
-### Positive
-- Natural interaction for both simple and complex usage
-- All protocol messages visible for debugging
-- Lightweight implementation (readline + WebSocket)
-- Escape hatches prevent getting stuck
-- Useful even after better UIs exist
-
-### Negative
-- Smart detection might surprise users initially
-- Need clear documentation of detection rules
-- Some edge cases require escape hatches
-- Not suitable for production use (debugging tool)
-
-### Security Considerations
-- All messages shown in terminal (including tokens/secrets)
-- Command history may contain sensitive data
-- No message encryption or privacy
-
-## Migration Path
-
-1. **Phase 1**: Basic implementation with chat and JSON
-2. **Phase 2**: Add command system
-3. **Phase 3**: Add message formatting and colors
-4. **Phase 4**: Add filtering and shortcuts
-5. **Future**: Keep as debug tool, build separate production UI
-
-## Examples
-
-### Simple Chat Session
-```
-> Hello everyone
-[10:23:45] → you chat
-└─ "Hello everyone"
-
-[10:23:46] ← echo-agent chat
-└─ "Echo: Hello everyone"
-
-> How can I help?
-[10:23:50] → you chat
-└─ "How can I help?"
-```
-
-### MCP Interaction
-```
-> {"kind": "mcp/request", "to": ["calculator"], "payload": {"method": "tools/list"}}
-[10:24:00] → you mcp/request
-└─ method: "tools/list", to: ["calculator"]
-
-[10:24:01] ← calculator mcp/response
-└─ tools: ["add", "subtract", "multiply", "divide"]
-
-> {"kind": "mcp/request", "to": ["calculator"], "payload": {"method": "tools/call", "params": {"name": "add", "arguments": {"a": 5, "b": 3}}}}
-[10:24:10] → you mcp/request
-└─ method: "tools/call", name: "add", args: {a: 5, b: 3}
-
-[10:24:11] ← calculator mcp/response
-└─ result: 8
-```
-
-### Debugging Session
-```
-> /verbose
-Verbose mode: ON
-
-> /participants
-Active participants:
-- you (human) [capabilities: chat, mcp/*]
-- echo-agent [capabilities: chat]
-- calculator [capabilities: mcp/response]
-
-> {"kind": "invalid"}
-[10:25:00] → you invalid
-{
- "protocol": "mew/v0.4",
- "id": "msg-456",
- "ts": "2025-01-10T10:25:00Z",
- "from": "human",
- "kind": "invalid"
-}
-
-[10:25:01] ← system system/error
-{
- "protocol": "mew/v0.4",
- "kind": "system/error",
- "payload": {
- "error": "Unknown message kind: invalid",
- "code": "INVALID_KIND"
- }
-}
-```
-
-### Edge Cases
-```
-> { this is not json but starts with brace
-[10:26:00] → you chat
-└─ "{ this is not json but starts with brace"
-
-> /chat {"actual": "json", "as": "text"}
-[10:26:10] → you chat
-└─ "{\"actual\": \"json\", \"as\": \"text\"}"
-
-> /json {"kind": "custom", "payload": {"force": "json"}}
-[10:26:20] → you custom
-└─ {"force": "json"}
-```
-
-## Future Enhancements
-
-1. **Better MCP support**:
- - Auto-complete for tool names
- - Parameter hints
- - Response formatting
-
-2. **Session management**:
- - Save/replay sessions
- - Session statistics
- - Export for analysis
-
-3. **Advanced filtering**:
- - Regex patterns
- - Participant filtering
- - Time-based filtering
-
-4. **Separate production UI**:
- - Full chat interface
- - Rich formatting
- - File uploads
- - Keep this as debug tool
-
-## Testing Requirements
-
-1. Test input detection for edge cases
-2. Test command parsing
-3. Test message formatting
-4. Test color output on different terminals
-5. Test verbose vs normal modes
-6. Test with large message volumes
-7. Test reconnection handling
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/ARCHITECTURE.md b/spec/archive/protocol/v0.0/ARCHITECTURE.md
deleted file mode 100644
index 28dee621..00000000
--- a/spec/archive/protocol/v0.0/ARCHITECTURE.md
+++ /dev/null
@@ -1,510 +0,0 @@
-# MCPx Architecture Guide
-
-## Overview
-
-MCPx creates a collaborative environment where humans, AI agents, and robots interact as peers through a shared messaging fabric. This document describes how the various components connect and interact in an MCPx-based system.
-
-## Core Architecture Principles
-
-1. **Peer Equality**: Every participant (human, agent, robot) is an MCP server capable of exposing and calling tools
-2. **Topic-Based Routing**: All communication happens within named topics (rooms) where messages are visible to all participants
-3. **Protocol Transparency**: MCP messages flow unchanged through the system, wrapped in thin routing metadata
-4. **Decoupled Components**: Each component has a single responsibility and communicates through well-defined interfaces
-
-## System Components
-
-### 1. MCPx Gateway Server
-
-The gateway is the central hub that manages topics and routes messages between participants.
-
-```
-┌────────────────────────────────────────┐
-│ MCPx Gateway Server │
-│ │
-│ ┌──────────────┐ ┌─────────────────┐ │
-│ │ WebSocket │ │ REST API │ │
-│ │ Handler │ │ (Optional) │ │
-│ └──────────────┘ └─────────────────┘ │
-│ │ │ │
-│ ┌──────────────────────────────────┐ │
-│ │ Topic Service │ │
-│ │ - Message routing │ │
-│ │ - Presence tracking │ │
-│ │ - History management │ │
-│ └──────────────────────────────────┘ │
-│ │ │
-│ ┌──────────────┐ ┌─────────────────┐ │
-│ │ Auth Service │ │ Rate Limiter │ │
-│ └──────────────┘ └─────────────────┘ │
-└────────────────────────────────────────┘
-```
-
-**Responsibilities:**
-- Accept WebSocket connections with JWT authentication
-- Validate and route message envelopes between participants
-- Track participant presence (join/leave/heartbeat)
-- Store message history for late-joining participants
-- Enforce rate limits and security policies
-
-**Key Design Decisions:**
-- Stateless where possible (JWT auth, no session state)
-- In-memory storage for v0 (can be replaced with persistent storage)
-- No message transformation—purely routing and broadcasting
-
-### 2. MCPx Bridge
-
-The bridge connects existing MCP servers to MCPx topics, acting as a protocol translator.
-
-```
-┌───────────────────────────────────────┐
-│ MCPx Bridge │
-│ │
-│ ┌──────────────┐ ┌────────────────┐ │
-│ │ MCPx Client │ │ MCP Client │ │
-│ │ (WebSocket) │ │ (stdio/ws/sse)│ │
-│ └──────────────┘ └────────────────┘ │
-│ │ │ │
-│ ┌──────────────────────────────────┐ │
-│ │ Message Translator │ │
-│ │ - Envelope wrapping/unwrapping │ │
-│ │ - ID correlation │ │
-│ │ - Error handling │ │
-│ └──────────────────────────────────┘ │
-│ │
-│ ┌──────────────────────────────────┐ │
-│ │ Configuration Manager │ │
-│ │ - Server connection details │ │
-│ │ - Participant identity │ │
-│ │ - Auth credentials │ │
-│ └──────────────────────────────────┘ │
-└───────────────────────────────────────┘
-```
-
-**Responsibilities:**
-- Maintain connections to both MCPx gateway and MCP server
-- Wrap MCP messages in MCPx envelopes (outgoing)
-- Unwrap MCPx envelopes to extract MCP messages (incoming)
-- Handle the MCP handshake (initialize/initialized) on behalf of the server
-- Broadcast tool capabilities on joining a topic
-- Manage request/response correlation between protocols
-
-**Key Design Decisions:**
-- One bridge instance per MCP server
-- Transparent proxy—no modification of MCP payloads
-- Automatic reconnection on connection loss
-- Configuration-driven deployment
-
-### 3. Human Interface (Frontend)
-
-The web interface allows humans to participate in topics and interact with agents.
-
-```
-┌────────────────────────────────────────┐
-│ Frontend Application │
-│ │
-│ ┌──────────────────────────────────┐ │
-│ │ UI Components │ │
-│ │ - Chat interface │ │
-│ │ - Participant list │ │
-│ │ - MCP Dev Tools │ │
-│ │ - Connection manager │ │
-│ └──────────────────────────────────┘ │
-│ │ │
-│ ┌──────────────────────────────────┐ │
-│ │ MCPx Client Hook │ │
-│ │ - WebSocket management │ │
-│ │ - Message handling │ │
-│ │ - State synchronization │ │
-│ └──────────────────────────────────┘ │
-│ │ │
-│ ┌──────────────────────────────────┐ │
-│ │ Local MCP Server (Optional) │ │
-│ │ - Human-specific tools │ │
-│ │ - UI interaction capabilities │ │
-│ └──────────────────────────────────┘ │
-└────────────────────────────────────────┘
-```
-
-**Responsibilities:**
-- Provide UI for joining topics and sending messages
-- Display real-time messages and participant presence
-- Offer developer tools for direct MCP interactions
-- Optionally expose MCP tools (e.g., "approve_action", "provide_feedback")
-- Handle authentication flow and connection management
-
-**Key Design Decisions:**
-- React-based for broad compatibility
-- Real-time updates via WebSocket subscription
-- Progressive disclosure (basic chat → dev tools → advanced features)
-- Mobile-responsive design
-
-## Data Flow Patterns
-
-### 1. Message Flow: Agent to Agent
-
-```
-Agent A Bridge A Gateway Bridge B Agent B
- │ │ │ │ │
- │ MCP Request │ │ │ │
- ├────────────────────>│ │ │ │
- │ │ │ │ │
- │ │ Wrap in Envelope │ │ │
- │ ├───────────────────> │ │ │
- │ │ │ │ │
- │ │ │ Broadcast │ │
- │ │ ├──────────────────>│ │
- │ │ │ │ │
- │ │ │ │ Unwrap & Forward │
- │ │ │ ├────────────────────>│
- │ │ │ │ │
- │ │ │ │ │
- │ │ │ │ MCP Response │
- │ │ │ │<────────────────────┤
- │ │ │ │ │
- │ │ │ Wrap & Route │ │
- │ │ │<───────────────────┤ │
- │ │ │ │ │
- │ │ Forward │ │ │
- │ │<─────────────────────┤ │ │
- │ │ │ │ │
- │ MCP Response │ │ │ │
- │<────────────────────┤ │ │ │
-```
-
-### 2. Human Interaction Pattern
-
-```
-Human (Frontend) Gateway Bridge MCP Server
- │ │ │ │
- │ Join Topic │ │ │
- ├──────────────────>│ │ │
- │ │ │ │
- │ Welcome + History │ │ │
- │<───────────────────┤ │ │
- │ │ │ │
- │ Send Chat │ │ │
- ├──────────────────>│ │ │
- │ │ │ │
- │ │ Broadcast │ │
- │ ├────────────────>│ │
- │ │ │ │
- │ │ │ Process & Respond │
- │ │ ├───────────────────>│
- │ │ │ │
- │ │ │ Tool Response │
- │ │ │<────────────────────┤
- │ │ │ │
- │ │ Route │ │
- │ │<─────────────────┤ │
- │ │ │ │
- │ Display Response │ │ │
- │<───────────────────┤ │ │
-```
-
-### 3. Multi-Agent Coordination
-
-```
-┌─────────────┐ ┌─────────────┐ ┌─────────────┐
-│ Coordinator │ │ Agent 1 │ │ Agent 2 │
-│ (Human) │ │ (Weather) │ │ (Calendar) │
-└─────┬───────┘ └──────┬──────┘ └──────┬──────┘
- │ │ │
- │ "Schedule meeting │ │
- │ with good weather" │ │
- ├────────────────────>│ │
- │ │ │
- │ │ Check weather │
- │ ├──────────────────>│
- │ │ │
- │ │ Get availability │
- │ ├───────────────────>│
- │ │ │
- │ │<───────────────────┤
- │ │ │
- │ │ Coordinate │
- │ │<──────────────────>│
- │ │ │
- │ "Meeting scheduled │ │
- │ for sunny Tuesday" │ │
- │<────────────────────┤ │
-```
-
-## Deployment Architectures
-
-### 1. Development/Research Setup
-
-Simple single-machine deployment for experimentation:
-
-```
-┌──────────────────────────────────────┐
-│ Local Machine │
-│ │
-│ ┌────────┐ ┌────────┐ ┌────────┐ │
-│ │Gateway │ │Frontend│ │Bridge 1│ │
-│ │ :3000 │ │ :3001 │ │ │ │
-│ └────────┘ └────────┘ └────────┘ │
-│ │ │
-│ ┌────────┐ ┌────────┐ │ │
-│ │Bridge 2│ │Bridge 3│ │ │
-│ │ │ │ │ │ │
-│ └────────┘ └────────┘ │ │
-│ │ │ │ │
-│ ┌────────┐ ┌────────┐ ┌────────┐ │
-│ │MCP Srv1│ │MCP Srv2│ │MCP Srv3│ │
-│ └────────┘ └────────┘ └────────┘ │
-└──────────────────────────────────────┘
-```
-
-### 2. Cloud Deployment
-
-Scalable cloud architecture for production:
-
-```
-┌─────────────────────────────────────────────┐
-│ Load Balancer │
-└─────────────────┬───────────────────────────┘
- │
- ┌────────────┼────────────┐
- │ │ │
-┌────▼────┐ ┌────▼────┐ ┌────▼────┐
-│Gateway 1│ │Gateway 2│ │Gateway 3│
-└─────────┘ └─────────┘ └─────────┘
- │ │ │
- └────────────┼────────────┘
- │
- ┌───────▼────────┐
- │ Redis/Kafka │ (Message Bus)
- │ Pub/Sub │
- └───────┬────────┘
- │
- ┌────────────┼────────────┐
- │ │ │
-┌────▼────┐ ┌────▼────┐ ┌────▼────┐
-│Bridge │ │Bridge │ │Bridge │
-│Pool 1 │ │Pool 2 │ │Pool 3 │
-└─────────┘ └─────────┘ └─────────┘
-```
-
-### 3. Platform Integration
-
-Bridging MCPx into existing chat platforms:
-
-```
-┌──────────────┐ ┌──────────────┐
-│ Slack │ │ Discord │
-│ Workspace │ │ Server │
-└──────┬───────┘ └──────┬───────┘
- │ │
-┌──────▼───────┐ ┌──────▼───────┐
-│ Slack-MCPx │ │Discord-MCPx │
-│ Adapter │ │ Adapter │
-└──────┬───────┘ └──────┬───────┘
- │ │
- └──────────┬─────────┘
- │
- ┌───────▼────────┐
- │ MCPx Gateway │
- └───────┬────────┘
- │
- ┌────────────┼────────────┐
- │ │ │
-┌────▼────┐ ┌────▼────┐ ┌────▼────┐
-│ Agent 1 │ │ Agent 2 │ │ Agent 3 │
-└─────────┘ └─────────┘ └─────────┘
-```
-
-## Security Architecture
-
-### Authentication Flow
-
-```
-Client Gateway Auth Service
- │ │ │
- │ Request Token │ │
- ├───────────────────>│ │
- │ │ Validate │
- │ ├──────────────────> │
- │ │ │
- │ │ Generate JWT │
- │ │<───────────────────┤
- │ JWT Token │ │
- │<───────────────────┤ │
- │ │ │
- │ Connect (Bearer) │ │
- ├───────────────────>│ │
- │ │ Verify JWT │
- │ ├──────────────────> │
- │ │ │
- │ Connected │ Valid │
- │<───────────────────┤<───────────────────┤
-```
-
-### Trust Boundaries
-
-```
-┌─────────────────────────────────────────┐
-│ Trusted Zone (Internal) │
-│ │
-│ ┌─────────────┐ ┌─────────────┐ │
-│ │ Gateway │─── │Auth Service │ │
-│ └─────────────┘ └─────────────┘ │
-│ │ │
-└─────────┼───────────────────────────────┘
- │
- TLS/JWT Boundary
- │
-┌─────────┼───────────────────────────────┐
-│ │ Untrusted Zone │
-│ ┌─────▼─────┐ ┌─────────────┐ │
-│ │ Clients │ │ Bridges │ │
-│ └───────────┘ └─────────────┘ │
-│ │
-└─────────────────────────────────────────┘
-```
-
-## Extension Points
-
-### 1. Custom Message Kinds
-
-While v0 focuses on MCP messages, the envelope supports extension:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "kind": "custom:video-stream",
- "payload": {
- "stream_url": "rtsp://...",
- "codec": "h264"
- }
-}
-```
-
-### 2. Gateway Plugins
-
-Gateways can add functionality without breaking compatibility:
-
-- **Persistence plugins**: Store messages in PostgreSQL/MongoDB
-- **Analytics plugins**: Track usage patterns and metrics
-- **Filter plugins**: Content moderation or PII detection
-- **Transform plugins**: Message enrichment (timestamps, metadata)
-
-### 3. Bridge Extensions
-
-Bridges can enhance MCP servers with additional capabilities:
-
-- **Caching layer**: Cache tool responses for performance
-- **Rate limiting**: Protect MCP servers from overload
-- **Tool augmentation**: Add wrapper tools (logging, permissions)
-- **Protocol adapters**: Support non-MCP protocols
-
-### 4. UI Components
-
-Frontends can create rich interactions beyond chat:
-
-- **Tool-specific widgets**: Custom UI for specific MCP tools
-- **Visualization panels**: Real-time graphs and dashboards
-- **Workflow builders**: Visual programming for agent coordination
-- **AR/VR interfaces**: Spatial computing for multi-agent interaction
-
-## Performance Considerations
-
-### Scalability Patterns
-
-1. **Horizontal Scaling**: Multiple gateway instances behind load balancer
-2. **Topic Sharding**: Distribute topics across gateway instances
-3. **Message Bus**: Use Redis/Kafka for inter-gateway communication
-4. **Connection Pooling**: Reuse WebSocket connections in bridges
-5. **Caching**: Cache MCP tool schemas and frequent responses
-
-### Optimization Points
-
-- **Message Batching**: Group multiple messages in single WebSocket frame
-- **Compression**: Enable WebSocket compression for large payloads
-- **Lazy Loading**: Load message history on demand
-- **Rate Limiting**: Prevent cascade failures from misbehaving participants
-- **Circuit Breakers**: Isolate failing MCP servers
-
-## Monitoring and Observability
-
-### Key Metrics
-
-```
-Gateway Metrics:
-- Active connections
-- Messages per second
-- Topic participant count
-- Message latency (p50, p95, p99)
-- Error rate by type
-
-Bridge Metrics:
-- MCP server health
-- Request/response times
-- Queue depth
-- Reconnection rate
-
-System Metrics:
-- CPU/Memory usage
-- Network I/O
-- WebSocket frame size
-- JWT validation time
-```
-
-### Distributed Tracing
-
-```
-Trace ID: abc123
-├─ Client Send (0ms)
-├─ Gateway Receive (10ms)
-├─ Auth Verify (12ms)
-├─ Topic Broadcast (15ms)
-├─ Bridge A Receive (18ms)
-├─ MCP Server A Process (20ms-150ms)
-├─ Bridge A Response (152ms)
-├─ Gateway Route (155ms)
-└─ Client Receive (160ms)
-```
-
-## Future Architecture Directions
-
-### Federation
-
-Connect multiple MCPx deployments:
-
-```
-┌──────────────┐ ┌──────────────┐
-│ MCPx Cloud │◄───────►│ MCPx Edge │
-│ Region A │ │ Region B │
-└──────────────┘ └──────────────┘
- ▲ ▲
- │ │
- └────────┬───────────────┘
- │
- ┌───────▼────────┐
- │ MCPx Private │
- │ Deployment │
- └────────────────┘
-```
-
-### Semantic Routing
-
-Intelligence layer for message routing:
-
-- Route by capability matching
-- Load balance by server specialization
-- Priority queues for time-sensitive operations
-- Semantic deduplication of similar requests
-
-### Native Platform SDKs
-
-Direct integration without bridges:
-
-- Python/JavaScript/Go client libraries
-- Mobile SDKs (iOS/Android)
-- Game engine plugins (Unity/Unreal)
-- IoT frameworks (ROS, Arduino)
-
-## Conclusion
-
-The MCPx architecture prioritizes simplicity, transparency, and extensibility. By treating all participants as peers and maintaining a thin protocol layer, it enables rich multi-agent interactions while remaining easy to understand, implement, and debug. The modular design allows each component to evolve independently while maintaining compatibility through the stable message envelope format.
-
-This architecture serves as both a practical system for today's needs and a foundation for exploring the future of human-AI-robot collaboration.
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/PATTERNS.md b/spec/archive/protocol/v0.0/PATTERNS.md
deleted file mode 100644
index 03e3768e..00000000
--- a/spec/archive/protocol/v0.0/PATTERNS.md
+++ /dev/null
@@ -1,281 +0,0 @@
-# MCPx v0 Usage Patterns and Workflows (Draft)
-
-Status: Draft
-Date: 2025-08-17
-Editors: MCPx Working Group (RJ Corwin)
-
----
-
-## 1. Purpose
-
-This document provides practical patterns for using the v0 SPEC in real systems. It shows how agents discover peers, establish MCP sessions, invoke tools (directed and broadcast), manage presence/history, and handle errors and reconnection.
-
----
-
-## 2. Peer Discovery and Handshake
-
-- On join, read the gateway welcome (`system` kind) and subsequent `presence` events to build the roster.
-- Choose a handshake strategy:
- - Eager: handshake (`initialize` → `initialized`) with all MCP‑capable peers immediately.
- - Lazy: wait until the first interaction, then handshake with the target.
- - On‑demand: preselect a subset (e.g., by `kind`, name, or capability) and handshake only with them.
-- Avoid handshake storms in large rooms by rate‑limiting and deduping parallel sessions.
-
-Example initialize envelope (addressed):
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-init-1",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "ui",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": 1,
- "method": "initialize",
- "params": {
- "protocolVersion": "2025-06-18",
- "capabilities": {"sampling": {}, "elicitation": {}, "roots": {}},
- "clientInfo": {"name": "UI", "version": "1.0.0"}
- }
- }
-}
-```
-
----
-
-## 3. Directed Tool Call (1:1)
-
-- Set `to` to the target participant. Others observe but ignore.
-- Expect exactly one MCP response with matching `payload.id` and `correlation_id` set to your request envelope `id`.
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-req-1",
- "ts": "2025-08-17T14:01:00Z",
-
- "from": "ui",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "payload": {"jsonrpc": "2.0", "id": 42, "method": "tools/call", "params": {"name": "robot.move", "arguments": {"x":1,"y":2}}}
-}
-```
-
----
-
-## 4. Broadcast Notifications
-
-- Only notifications (no `payload.id`) may be broadcast by omitting `to` or leaving it empty.
-- Requests MUST target exactly one participant to maintain MCP client/server semantics.
-- For multi-participant queries, use a coordinator pattern (see §5) or send individual requests.
-
----
-
-## 5. Coordinator/Mediator Pattern
-
-- Introduce a coordinator agent that:
- - Handshakes with all peers and maintains a capability index (from `tools/list` and list_changed notifications).
- - Routes tool calls to the most appropriate peer(s) and aggregates replies.
- - Applies policies: rate limiting, retries, and backoff.
-
-This reduces coupling between spontaneous participants and provides a single point for policy enforcement.
-
----
-
-## 6. Presence, Roster, and History
-
-- Presence: listen for `presence` join/leave/heartbeat to keep a live roster. Expose it via UI or a local MCP tool (e.g., `presence.get`).
-- History: use `GET /v0/topics/{topic}/history` to fetch recent envelopes for context (size is deployment‑dependent). Merge with live stream by `ts` or `id`.
-
----
-
-## 7. Reconnect and Resume
-
-- On reconnect: fetch a small window of history, reconcile roster, and resubscribe.
-- For outstanding MCP requests:
- - Track by `payload.id` and request envelope `id`.
- - If no responses arrive within timeout, send MCP cancellation and/or retry.
-
----
-
-## 8. Capability Discovery and Caching
-
-- After handshake, call `tools/list` and cache results per peer. Respect `notifications/tools/list_changed` to invalidate caches.
-- Optionally broadcast a discovery notification on join with a summary of offered tool names to help UIs quickly populate menus.
-
----
-
-## 9. Chat Implementation Patterns
-
-### 9.1 Broadcast Chat Notifications (Recommended)
-
-For room-wide chat, use broadcast MCP notifications:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-chat-1",
- "ts": "2025-08-17T14:05:00Z",
- "from": "user-alice",
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/chat/message",
- "params": {
- "text": "Hello everyone!",
- "format": "plain",
- "thread_id": "general"
- }
- }
-}
-```
-
-**Payload schema for `notifications/chat/message`:**
-- `text` (string, required): The chat message content
-- `format` (string, optional): "plain" or "markdown", defaults to "plain"
-- `thread_id` (string, optional): Thread/channel identifier for organizing conversations
-- `mentions` (array[string], optional): Participant IDs mentioned in the message
-- `reply_to` (string, optional): Message ID this is replying to
-
-### 9.2 Chat Tools as Syntactic Sugar
-
-Participants MAY provide `chat.say` tools that emit broadcast notifications:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-tool-1",
- "ts": "2025-08-17T14:05:00Z",
- "from": "ui",
- "to": ["coordinator"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "chat.say",
- "arguments": {"text": "Hello!", "format": "plain"}
- }
- }
-}
-```
-
-The coordinator then emits the corresponding broadcast notification.
-
-### 9.3 Coordinator Chat Example
-
-A coordinator that accepts `chat.say` tool calls and emits broadcast notifications:
-
-**Tool call to coordinator:**
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-req-1",
- "from": "ui",
- "to": ["coordinator"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0", "id": 42,
- "method": "tools/call",
- "params": {"name": "chat.say", "arguments": {"text": "Meeting starts in 5 min"}}
- }
-}
-```
-
-**Coordinator's broadcast response:**
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-broadcast-1",
- "from": "coordinator",
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/chat/message",
- "params": {"text": "Meeting starts in 5 min", "format": "plain"}
- }
-}
-```
-
-**Tool response to caller:**
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-resp-1",
- "from": "coordinator",
- "to": ["ui"],
- "kind": "mcp",
- "correlation_id": "env-req-1",
- "payload": {"jsonrpc": "2.0", "id": 42, "result": {"status": "broadcasted"}}
-}
-```
-
-### 9.4 UI Integration
-
-- Display notifications from `notifications/chat/message` in chat interfaces
-- Agents without chat support simply ignore these notifications
-- Consider visual indicators for mentions and threading
-- UIs MAY provide both notification listening and `chat.say` tool calling for flexibility
-
----
-
-## 10. Error Handling and Retries
-
-- Distinguish between:
- - MCP protocol errors (JSON‑RPC error in `payload`)
- - Gateway/system errors (`system` kind with details)
-- Apply exponential backoff for transient failures; surface actionable errors to users.
-
----
-
-## 11. Topic Planning
-
-- Keep rooms small for bandwidth and clarity; shard by task, team, or capability.
-- For privacy, use separate topics (v0 topics are not private by default). Higher‑layer E2E encryption is out of scope.
-
----
-
-## 12. Versioning and Compatibility
-
-- Prefer MCP `2025-06-18`. If a peer offers an older MCP version, limit features accordingly.
-- Expose your supported envelope `protocol` (`mcp-x/v0`) and MCP version in presence metadata.
-
----
-
-## 13. Coordinator Aggregation Example
-
-The coordinator sends individual requests to multiple participants:
-
-Request 1:
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-req-1",
- "ts": "2025-08-17T14:03:00Z",
- "from": "coordinator",
- "to": ["search-agent-1"],
- "kind": "mcp",
- "payload": {"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "search", "arguments": {"q": "map zone7"}}}
-}
-```
-
-Request 2:
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-req-2",
- "ts": "2025-08-17T14:03:00Z",
- "from": "coordinator",
- "to": ["search-agent-2"],
- "kind": "mcp",
- "payload": {"jsonrpc": "2.0", "id": 8, "method": "tools/call", "params": {"name": "search", "arguments": {"q": "map zone7"}}}
-}
-```
-
-Coordinator policy:
-- Track responses by `correlation_id` matching request envelope ids.
-- Apply aggregation strategy (first-wins, best-of, consensus, etc.).
diff --git a/spec/archive/protocol/v0.0/SPEC.md b/spec/archive/protocol/v0.0/SPEC.md
deleted file mode 100644
index e67b652f..00000000
--- a/spec/archive/protocol/v0.0/SPEC.md
+++ /dev/null
@@ -1,474 +0,0 @@
-# MCPx v0 Protocol Specification (Draft)
-
-Status: Draft v0
-Date: 2025-08-17
-Intended Status: Informational
-Editors: MCPx Working Group (RJ Corwin)
-
----
-
-## Requirements Language
-
-The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
-
----
-
-## 1. Abstract
-
-MCPx v0 defines a minimal, topic‑based meta‑message format and a realtime gateway API that allows multiple MCP servers (agents/humans/robots) to interoperate in shared “rooms.”
-
-- Every participant behaves like an MCP server.
-- Messages are published to a topic and are visible to all participants.
-- A message’s intended recipient(s) is expressed as metadata; delivery is not private at the topic layer.
-- MCP (JSON‑RPC 2.0) requests/responses are encapsulated inside a simple envelope.
-
-This v0 deliberately focuses on MCP tools. Resources/Prompts are out of scope unless they work transparently through the same mechanism.
-
----
-
-## 2. Goals and Non‑Goals
-
-### 2.1 Goals
-- Simplicity: a "USB‑C for multi‑agent collaboration."
-- Interop: treat all participants as MCP servers and let them call each other's tools.
-- Transport: encourage realtime via WebSockets; clients can get presence and recent history easily.
-- Security: require token‑based auth; make the non‑private nature explicit.
-- Platform bridges: enable existing chat platforms (Slack, Discord, XMPP, Matrix) to implement MCPx gateways, allowing MCP agents to participate in their native channels.
-
-### 2.2 Non‑Goals (v0)
-- Built‑in task semantics (handled via MCP tools if desired).
-- End‑to‑end encryption or private DMs (use separate topics or higher‑layer crypto if needed).
-- Schema registries/ACL granularity beyond topic admission.
-- Topic lifecycle management (creation, configuration, deletion) - topics are assumed to exist; management is implementation-specific.
-
----
-
-## 3. Model Overview
-
-- Topic: named room (e.g., `room:alpha`).
-- Participant: any client (human UI, robot, agent) that joins a topic. Each participant SHOULD expose an MCP server interface to others.
-- Visibility: all published messages in a topic are visible to all participants. “To” metadata is advisory routing metadata, not a privacy boundary.
-- Addressing: participants can broadcast, or address one/many participants. Participants ignore messages not addressed to them.
-
----
-
-## 4. Message Envelope
-
-All data flowing over a topic MUST be a single top‑level JSON envelope. This enables multiplexing different kinds of payloads while keeping routing and correlation consistent.
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "2f6b6e70-7b36-4b8b-9ad8-7c4f7d0e2d0b",
- "ts": "2025-08-17T14:00:00Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp",
- "correlation_id": "env-1",
- "payload": { /* kind-specific body (see below) */ }
-}
-```
-
-Field semantics:
-- protocol: MUST be `"mcp-x/v0"` for this version.
-- id: globally unique message id (e.g., UUIDv4).
-- ts: RFC3339 timestamp (producer clock).
-- from: stable participant id within the topic (assigned on join or self‑asserted per deployment).
-- to: array of participant ids indicating intended recipient(s); MAY be empty or omitted to indicate broadcast to all participants.
-- kind: one of `mcp`, `presence`, or `system`.
-- correlation_id: when a message semantically replies to another envelope, this field **MUST** be set to the target envelope `id`. Otherwise it MAY be omitted.
-- payload: object; structure depends on `kind`.
-
-### 4.1 MCP Encapsulation (kind = "mcp")
-
-The payload MUST contain an embedded JSON‑RPC 2.0 message exactly as defined by MCP.
-
-```json
-{
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": { /* MCP params */ }
- }
-}
-```
-
-Rules:
-- Requests (messages with `payload.id`) MUST set `to` to exactly one participant. Broadcasting requests is NOT supported as it breaks the MCP client/server model.
-- Responses MUST carry the same `payload.id` as the request and MUST set `correlation_id` to the request envelope `id`.
-- Notifications (no `payload.id`) MAY be broadcast (empty `to` array) or directed to specific participants.
-- JSON‑RPC `payload.id` SHOULD be a number for consistency; clients MUST NOT coerce types and MUST echo the same type in responses.
-
-Handshake over topics:
-- Before sending MCP requests to a participant, the caller MUST perform the MCP initialization flow with that participant:
- 1) Send `initialize` (JSON‑RPC request) addressed via `to: [""]`.
- 2) Receive `initialize` result from the target.
- 3) Send `notifications/initialized` (JSON‑RPC notification) to the target.
-- Version negotiation and capability exchange MUST follow MCP 2025‑06‑18.
-- Other participants will observe these handshake messages but MUST ignore those not addressed to them.
-- All MCP methods including `resources/*`, `prompts/*`, and `tools/*` are passed through unchanged in the envelope payload.
-
-Example initialize request in an envelope:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-init-1",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "coordinator",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": 1,
- "method": "initialize",
- "params": {
- "protocolVersion": "2025-06-18",
- "capabilities": { "sampling": {}, "elicitation": {}, "roots": {} },
- "clientInfo": { "name": "Coordinator", "version": "1.0.0" }
- }
- }
-}
-```
-
-#### 4.1.1 Reply Semantics
-
-A reply is any envelope that semantically responds to a previous envelope.
-
-- The reply envelope MUST set `correlation_id` to the original envelope `id`.
-- The reply SHOULD set `to` to the original `from` (or a subset thereof).
-- For MCP JSON‑RPC responses:
- - `payload.id` MUST equal the original MCP request `payload.id`.
- - `from` MUST be the participant that received the request.
- - `to` SHOULD be the requestor participant.
-
-MCP response example:
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-2",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp",
- "correlation_id": "env-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": { "status": "ok" }
- }
-}
-```
-
-Non‑request reply example (notification acknowledging a previous message):
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-3",
- "ts": "2025-08-17T14:00:05Z",
- "from": "coordinator",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "correlation_id": "env-chat-1",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/message_acknowledged",
- "params": { "original_id": "env-chat-1" }
- }
-}
-```
-
-### 4.2 Presence (kind = "presence")
-
-Gateway‑emitted join/leave/heartbeat messages.
-
-Payload schema:
-```json
-{
- "event": "join" | "leave" | "heartbeat",
- "participant": {
- "id": "string",
- "name": "string",
- "kind": "human" | "agent" | "robot",
- "mcp": { "version": "2025-06-18" }
- }
-}
-```
-
-Example:
-```json
-{
- "payload": { "event": "join", "participant": {"id": "robot-alpha", "name": "Robot Alpha", "kind": "robot", "mcp": {"version": "2025-06-18"} } }
-}
-```
-
----
-
-## 5. Realtime Gateway API
-
-Deployments SHOULD offer a simple gateway that provides auth, presence, history, and a realtime stream.
-
-### 5.1 Authentication
-- Bearer token via `Authorization: Bearer `.
-- Tokens SHOULD be short‑lived and audience‑scoped to topics.
-
-### 5.2 WebSocket (recommended)
-- Connect: `GET /v0/ws?topic=` with Authorization header.
-- On open: server sends a `system` welcome with assigned `participant.id`, current participants, and optional recent history.
-- Bidirectional: clients send/receive envelope objects as text frames (JSON).
-
-### 5.3 REST (optional helpers)
-- `GET /v0/topics` → list of visible topics.
-- `GET /v0/topics/{topic}/participants` → presence list.
-- `GET /v0/topics/{topic}/history?limit=100&before=` → recent envelopes (most recent first).
-
-Pagination SHOULD be based on the envelope `id` or `ts`. History MAY be capped or disabled.
-
-On open (welcome):
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-welcome-1",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "system:gateway",
- "kind": "system",
- "payload": {
- "event": "welcome",
- "participant": {"id": "coordinator"},
- "participants": [
- {"id": "robot-alpha", "name": "Robot Alpha", "kind": "robot", "mcp": {"version": "2025-06-18"}}
- ],
- "history": { "enabled": true, "limit": 100 },
- "protocol": "mcp-x/v0"
- }
-}
-```
-
----
-
-## 6. Participants and Presence
-
-- Participant Identity: a stable `id` within the topic (e.g., `robot-alpha`). Display metadata MAY include `name`, `kind` (human/agent/robot), and `mcp.version`.
-- Join/Leave: the gateway SHOULD emit `presence` events on joins and leaves. Heartbeats MAY be emitted for liveness.
-- Discovery: participants MAY broadcast `mcp` notifications advertising MCP tool availability on join, or respond to discovery requests.
-
-### 6.1 Peer Discovery and Handshake
-
-See `PATTERNS.md` §2 for recommended discovery and handshake strategies (eager, lazy, on‑demand), concurrency/de‑duplication, and backoff guidance.
-
-Briefly: discover peers from presence, then perform MCP `initialize` → `initialized` with selected peers via addressed `mcp` envelopes (others observe but ignore). Version negotiation MUST follow MCP 2025‑06‑18.
-
----
-
-## 7. MCP Interop Rules
-
-See `PATTERNS.md` §3–§5 for practical guidance on directed vs broadcast calls, aggregation, and coordinator patterns.
-
-- Every participant SHOULD act as an MCP server.
-- Participants MAY also run an MCP client to invoke other participants’ tools.
-- Addressing: when invoking a tool, set `to` to the target participant. Others MUST ignore MCP requests not addressed to them, but may observe them.
-- Error Handling: MCP errors are returned as JSON‑RPC error objects inside `payload`. Gateways MUST NOT rewrite MCP payloads.
-
----
-
-## 8. Chat Communication
-
-See `PATTERNS.md` §9 for detailed chat implementation patterns.
-
-### 8.1 Broadcast Chat Notifications (Recommended)
-
-For room-wide chat messages, participants SHOULD use broadcast MCP notifications:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-chat-1",
- "ts": "2025-08-17T14:05:00Z",
- "from": "user-alice",
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/chat/message",
- "params": {
- "text": "Hello everyone!",
- "format": "plain"
- }
- }
-}
-```
-
-- Notifications with `method: "notifications/chat/message"` MAY be broadcast (empty or omitted `to` array).
-- All participants SHOULD display/log these notifications if they support chat UX.
-- Payload params MUST include `text` (string); `format` ("plain"|"markdown") is OPTIONAL and defaults to "plain".
-
-### 8.2 Optional Chat Tools
-
-Participants MAY provide these MCP tools as syntactic sugar:
-
-- `chat.say` — params: `{ text: string, format?: "plain"|"markdown" }`; emits a `notifications/chat/message` broadcast.
-- `presence.get` — returns the current presence list (equivalent to calling the REST API).
-
----
-
-## 9. Security Considerations
-
-Alignment with MCP security guidance (2025‑06‑18):
-- Tool safety: UIs SHOULD require human confirmation for sensitive tools; treat tool annotations as untrusted unless verified.
-- Data privacy: do not leak user data into public topics; hosts MUST obtain consent before exposing resources.
-- Origin/transport: if using HTTP variants, validate `Origin`, prefer localhost binding for local servers, and authenticate all connections.
-- Participant verification: gateways MUST verify that `from` matches the authenticated participant identity. Consider cryptographic signatures for high-security deployments.
-- Rate limiting: implementations MAY apply per-participant rate limits to prevent abuse and implement backpressure.
-
----
-
-## 10. Versioning and Negotiation
-
-- The envelope `protocol` field MUST be `"mcp-x/v0"` for this version.
-- Gateways SHOULD reject connects from clients that do not advertise support for `mcp-x/v0` (e.g., via a query param or first message).
-
----
-
-## 11. Rationale (Pros/Cons)
-
-- Single public stream per topic keeps implementations simple and auditable; addressing is metadata only.
- - Pro: simple, observable, easy to debug; enables “peanut gallery.”
- - Con: no privacy; bandwidth grows with participants. Use more topics or filtering if needed.
-- MCP encapsulation avoids defining new RPC; client libraries can bridge JSON‑RPC requests/responses to the envelope with minimal glue.
-- WebSockets provide low‑latency bidirectional streaming; SSE/HTTP polling MAY be supported but are discouraged for write paths.
-
----
-
-## 12. Reference Client (Library Guidance)
-
-A standard client library SHOULD:
-- Expose a local MCP client that presents remote participants as selectable MCP servers.
-- Handle envelope creation, addressing, correlation, and response matching.
-- Provide helpers for presence, history, and chat notifications (`notifications/chat/message` listening and broadcast).
-- Offer pluggable auth token providers and reconnection with backoff.
-
----
-
-## 13. Appendix: Minimal Examples
-
-For additional end‑to‑end example flows (broadcast + aggregation, reconnect), see `PATTERNS.md` §13.
-
-### 13.1 MCP tool call request → response
-
-Request (to robot):
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-1",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "coordinator",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "payload": { "jsonrpc": "2.0", "id": "42", "method": "tools/call", "params": { "name": "robot.move", "arguments": {"x":1, "y":2} } }
-}
-```
-
-Response (from robot):
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-2",
- "ts": "2025-08-17T14:00:00Z",
-
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp",
- "correlation_id": "env-1",
- "payload": { "jsonrpc": "2.0", "id": "42", "result": { "status": "ok" } }
-}
-```
-
-### 13.2 Presence join
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-join-1",
- "ts": "2025-08-17T13:59:59Z",
- "from": "system:gateway",
- "kind": "presence",
- "payload": { "event": "join", "participant": {"id": "coordinator", "name": "Coordinator"} }
-}
-```
-
-### 13.3 Progress notification
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-progress-1",
- "ts": "2025-08-17T14:00:10Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp",
- "correlation_id": "env-1",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/progress",
- "params": {
- "progressToken": 42,
- "progress": 0.5,
- "total": 1.0
- }
- }
-}
-```
-
-### 13.4 Cancellation notification
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "env-cancel-1",
- "ts": "2025-08-17T14:00:15Z",
- "from": "coordinator",
- "to": ["robot-alpha"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/cancelled",
- "params": {
- "requestId": 42,
- "reason": "User cancelled operation"
- }
- }
-}
-```
-
----
-
-## 14. Future Directions
-
-The following areas are intentionally not covered in MCPx v0 but represent potential areas for future specification versions:
-
-### 14.1 Topic Management
-- **Topic Creation**: Standardized APIs for creating new topics with configuration
-- **Topic Discovery**: Mechanisms for finding and browsing available topics
-- **Topic Metadata**: Schemas for topic descriptions, permissions, and settings
-- **Topic Lifecycle**: Rules for topic archival, deletion, and migration
-- **Topic Federation**: Cross-gateway topic bridging and routing
-
-### 14.2 Enhanced Security
-- **E2E Encryption**: End-to-end encryption for sensitive communications
-- **Granular Permissions**: Fine-grained ACLs beyond topic-level admission
-- **Identity Verification**: Cryptographic identity and signature verification
-
-### 14.3 Advanced Features
-- **Private Messaging**: Direct messages outside the public topic stream
-- **Message Editing/Deletion**: Protocols for modifying historical messages
-- **Presence Status**: Rich presence states beyond join/leave/heartbeat
-- **File Transfer**: Standardized binary data and large file handling
-
-### 14.4 Platform Integration Specifications
-- **Platform Adapters**: Standardized patterns for bridging MCPx to existing chat platforms
-- **UI Extensions**: Guidelines for native MCP tool rendering in chat UIs
-- **Identity Mapping**: Protocols for mapping platform users to MCPx participants
-- **Rate Limit Coordination**: Harmonizing MCPx and platform rate limits
-
-These features may be addressed in future versions as the protocol matures and implementation experience provides guidance on requirements.
diff --git a/spec/archive/protocol/v0.0/adr/001-tool-authorization-investigation.md b/spec/archive/protocol/v0.0/adr/001-tool-authorization-investigation.md
deleted file mode 100644
index 708e93ad..00000000
--- a/spec/archive/protocol/v0.0/adr/001-tool-authorization-investigation.md
+++ /dev/null
@@ -1,77 +0,0 @@
-# ADR-001: Tool Authorization Investigation
-
-## Investigation: MCP Approach to Tool Authorization
-
-### Current MCP Approach
-
-Based on examination of the MCP specification (draft version), MCP handles tool authorization through the following mechanisms:
-
-#### 1. Trust & Safety Guidelines (Non-Protocol Level)
-
-The MCP specification provides **guidelines** rather than protocol-level enforcement for tool authorization:
-
-From `modelcontextprotocol/docs/specification/draft/server/tools.mdx`:
-
-> For trust & safety and security, there **SHOULD** always be a human in the loop with the ability to deny tool invocations.
->
-> Applications **SHOULD**:
-> - Provide UI that makes clear which tools are being exposed to the AI model
-> - Insert clear visual indicators when tools are invoked
-> - Present confirmation prompts to the user for operations, to ensure a human is in the loop
-
-#### 2. Client-Side Implementation Responsibility
-
-Tool authorization is delegated to the **client implementation** rather than being part of the protocol:
-
-> Clients **SHOULD**:
-> - Prompt for user confirmation on sensitive operations
-> - Show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration
-> - Validate tool results before passing to LLM
-> - Implement timeouts for tool calls
-> - Log tool usage for audit purposes
-
-#### 3. Transport-Level Authorization
-
-MCP includes OAuth 2.1-based authorization at the **transport level** (for HTTP-based transports) in `modelcontextprotocol/docs/specification/draft/basic/authorization.mdx`, but this is for:
-- Authenticating clients to servers
-- Protecting access to MCP server resources
-- NOT for authorizing individual tool calls
-
-#### 4. Elicitation Pattern
-
-MCP introduces an "elicitation" pattern (`modelcontextprotocol/docs/specification/draft/client/elicitation.mdx`) that allows servers to request user input during interactions. While not specifically for tool authorization, it demonstrates a pattern for user interaction:
-- Servers can request structured data from users
-- Clients control the presentation and validation
-- Users can accept, decline, or cancel requests
-
-### Key Findings
-
-1. **No Protocol-Level Tool Authorization**: MCP does not define protocol messages for tool authorization. It's considered an implementation concern.
-
-2. **Client Implementation Freedom**: Clients are free to implement any authorization UI/UX they choose, from automatic approval to detailed confirmation dialogs.
-
-3. **Trust Model**: MCP assumes clients are trusted to make authorization decisions on behalf of users.
-
-4. **Security Through Transparency**: Emphasis is on making tool invocations visible and clear to users rather than enforcing authorization at the protocol level.
-
-### Implications for MCPx
-
-For MCPx, which involves multiple agents potentially calling each other's tools in a distributed environment, we need to consider:
-
-1. **Multi-Party Authorization**: In MCPx, tool calls may cross agent boundaries, requiring authorization from the tool owner rather than just the caller's user.
-
-2. **Delegation Patterns**: Agents may need to delegate authorization decisions to human operators or other agents.
-
-3. **Audit Requirements**: Multi-agent scenarios require clear audit trails of who authorized what.
-
-4. **Protocol-Level Support**: Unlike MCP's client-centric model, MCPx may benefit from protocol-level authorization messages to ensure interoperability.
-
-### Recommendation
-
-MCPx should extend beyond MCP's approach by:
-1. Defining protocol-level authorization request/response messages
-2. Supporting both synchronous (blocking) and asynchronous (non-blocking) authorization flows
-3. Enabling authorization delegation patterns
-4. Maintaining audit trails of authorization decisions
-
-This would ensure consistent authorization behavior across different MCPx implementations while supporting the complex multi-agent scenarios that MCPx enables.
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/adr/001-tool-authorization.md b/spec/archive/protocol/v0.0/adr/001-tool-authorization.md
deleted file mode 100644
index 7acd54e9..00000000
--- a/spec/archive/protocol/v0.0/adr/001-tool-authorization.md
+++ /dev/null
@@ -1,229 +0,0 @@
-# ADR-001: Tool Authorization in MCPx
-
-## Status
-PROPOSED
-
-## Context
-
-MCPx enables multiple agents to interact in shared topics/rooms, where agents can discover and invoke each other's tools. This creates a need for authorization mechanisms that go beyond what standard MCP provides.
-
-In MCP, tool authorization is handled at the client implementation level with guidelines but no protocol-level enforcement. Clients are trusted to prompt users for confirmation on sensitive operations. This approach works well for single-client scenarios but is insufficient for MCPx's multi-agent environment where:
-
-1. Tool calls cross agent boundaries
-2. Authorization may need to come from the tool owner, not the caller
-3. Multiple participants may need visibility into authorization decisions
-4. Audit trails are required for compliance and debugging
-
-## Decision
-
-MCPx will implement protocol-level tool authorization through a new message flow that allows tool owners to approve, deny, or delegate authorization for incoming tool calls.
-
-### Authorization Flow
-
-#### 1. Authorization Request Message
-
-When an agent receives a tool call that requires authorization, it can respond with an authorization request instead of immediately executing the tool:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "auth-req-123",
- "ts": "2024-01-01T12:00:00Z",
- "from": "agent-b",
- "to": ["agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "original-request-id",
- "error": {
- "code": -32001,
- "message": "Authorization required",
- "data": {
- "authorizationRequest": {
- "id": "auth-123",
- "tool": "dangerous_operation",
- "arguments": {"target": "production"},
- "requester": "agent-a",
- "reason": "Tool requires user approval for production operations",
- "expiresAt": "2024-01-01T12:05:00Z"
- }
- }
- }
- }
-}
-```
-
-#### 2. Authorization Decision Notification
-
-The agent can then emit a notification to request authorization (potentially to a human operator or authorization service):
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "auth-notify-123",
- "ts": "2024-01-01T12:00:01Z",
- "from": "agent-b",
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/authorization/request",
- "params": {
- "id": "auth-123",
- "tool": "dangerous_operation",
- "arguments": {"target": "production"},
- "requester": "agent-a",
- "reason": "Tool requires user approval for production operations"
- }
- }
-}
-```
-
-#### 3. Authorization Response
-
-Once authorization is granted or denied, the authorizing party sends an authorization response:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "auth-resp-123",
- "ts": "2024-01-01T12:00:30Z",
- "from": "user-1",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "authorization/respond",
- "params": {
- "authorizationId": "auth-123",
- "decision": "approve", // or "deny"
- "reason": "Approved for maintenance window",
- "validUntil": "2024-01-01T13:00:00Z"
- }
- }
-}
-```
-
-#### 4. Tool Execution or Denial
-
-Based on the authorization response, the agent either executes the tool or returns an error:
-
-**If approved:**
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "tool-resp-123",
- "ts": "2024-01-01T12:00:31Z",
- "from": "agent-b",
- "to": ["agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "original-request-id",
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed successfully"
- }]
- }
- }
-}
-```
-
-**If denied:**
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "tool-resp-123",
- "ts": "2024-01-01T12:00:31Z",
- "from": "agent-b",
- "to": ["agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "original-request-id",
- "error": {
- "code": -32002,
- "message": "Authorization denied",
- "data": {
- "reason": "User denied authorization"
- }
- }
- }
-}
-```
-
-### Authorization Modes
-
-Agents can operate in different authorization modes:
-
-1. **Always Allow**: Execute all tool calls immediately (default for backward compatibility)
-2. **Always Prompt**: Require authorization for all tool calls
-3. **Selective**: Require authorization based on tool configuration or caller identity
-4. **Delegated**: Forward authorization decisions to another participant
-
-### Tool Metadata Extension
-
-Tools can declare their authorization requirements:
-
-```json
-{
- "name": "dangerous_operation",
- "description": "Performs a dangerous operation",
- "inputSchema": {...},
- "authorization": {
- "required": true,
- "mode": "user_approval", // or "automatic", "delegated"
- "timeout": 300, // seconds
- "message": "This operation affects production systems"
- }
-}
-```
-
-## Consequences
-
-### Positive
-- **Enhanced Security**: Protocol-level authorization prevents unauthorized tool execution
-- **Audit Trail**: All authorization decisions are captured in the message flow
-- **Flexibility**: Supports multiple authorization patterns (immediate, async, delegated)
-- **User Control**: Humans can maintain control over sensitive operations
-- **Interoperability**: Standardized authorization ensures consistent behavior across implementations
-
-### Negative
-- **Increased Complexity**: Adds new message types and flows to implement
-- **Latency**: Authorization adds delay to tool execution
-- **State Management**: Agents must track pending authorizations
-- **Backward Compatibility**: Need to maintain compatibility with agents that don't support authorization
-
-### Neutral
-- **Optional Implementation**: Authorization can be optional, with agents defaulting to "always allow"
-- **MCP Alignment**: Diverges from MCP's client-centric approach but maintains compatibility
-- **Gateway Role**: Gateways may need to participate in authorization flows for web-based users
-
-## Implementation Considerations
-
-1. **Timeout Handling**: Authorization requests should timeout to prevent indefinite blocking
-2. **Caching**: Authorization decisions could be cached for repeated operations
-3. **Revocation**: Need mechanism to revoke previously granted authorizations
-4. **Policy Engine**: Agents could integrate with policy engines for automated decisions
-5. **UI/UX**: Human-facing agents need clear UI for authorization prompts
-
-## Alternatives Considered
-
-1. **Client-Side Only** (MCP approach): Leave authorization to client implementation
- - Rejected: Insufficient for multi-agent scenarios
-
-2. **Capability-Based Security**: Use capability tokens for authorization
- - Rejected: Too complex for initial implementation
-
-3. **Role-Based Access Control**: Define roles and permissions
- - Rejected: Requires centralized authority, against MCPx's distributed nature
-
-4. **Smart Contract Style**: Use blockchain or consensus mechanisms
- - Rejected: Over-engineered for the use case
-
-## References
-
-- MCP Tool Specification: `/modelcontextprotocol/docs/specification/draft/server/tools.mdx`
-- MCP Authorization Specification: `/modelcontextprotocol/docs/specification/draft/basic/authorization.mdx`
-- MCP Elicitation Pattern: `/modelcontextprotocol/docs/specification/draft/client/elicitation.mdx`
-- Investigation Notes: `/protocol-spec/v0/adr/001-tool-authorization-investigation.md`
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/adr/002-elicitation-for-tool-approval.md b/spec/archive/protocol/v0.0/adr/002-elicitation-for-tool-approval.md
deleted file mode 100644
index 0bd1ed60..00000000
--- a/spec/archive/protocol/v0.0/adr/002-elicitation-for-tool-approval.md
+++ /dev/null
@@ -1,266 +0,0 @@
-# ADR-002: Using Elicitation for Tool Approval in MCPx
-
-## Status
-PROPOSED
-
-## Context
-
-MCP's elicitation pattern allows servers to request structured information from users through clients during interactions. While designed for gathering user input (like forms), this pattern could potentially be adapted for tool approval workflows.
-
-### Current MCP Elicitation Pattern
-
-In MCP, elicitation works as follows:
-1. Server sends `elicitation/create` request to client
-2. Client presents UI to user
-3. User responds with action: `accept`, `decline`, or `cancel`
-4. Client returns response to server
-
-### The Tool Approval Challenge in MCPx
-
-In MCPx's multi-agent environment:
-- Agent A wants to call Agent B's tool
-- Agent B needs approval (possibly from a human) before executing
-- The approval request needs to flow through the network to the appropriate authorizer
-
-## Decision
-
-MCPx will extend the elicitation pattern to support tool approval workflows, allowing agents to request approval for tool calls through the same mechanism used for gathering user input.
-
-### Approach: Elicitation-Based Tool Approval
-
-#### 1. Tool Call Interception
-
-When Agent B receives a tool call requiring approval, instead of executing it immediately, it initiates an elicitation:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-456",
- "ts": "2024-01-01T12:00:00Z",
- "from": "agent-b",
- "to": ["user-1"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "elicit-123",
- "method": "elicitation/create",
- "params": {
- "message": "Agent A requests permission to execute 'dangerous_operation'",
- "requestedSchema": {
- "type": "object",
- "properties": {
- "approve": {
- "type": "boolean",
- "title": "Approve this tool call?",
- "description": "Tool: dangerous_operation\nCaller: agent-a\nArguments: {target: 'production'}"
- },
- "reason": {
- "type": "string",
- "title": "Reason (optional)",
- "description": "Provide a reason for your decision"
- }
- },
- "required": ["approve"]
- },
- "metadata": {
- "elicitationType": "tool_approval",
- "originalRequest": {
- "from": "agent-a",
- "tool": "dangerous_operation",
- "arguments": {"target": "production"},
- "requestId": "original-req-123"
- }
- }
- }
- }
-}
-```
-
-#### 2. User Response
-
-The user (or authorizing agent) responds through the standard elicitation response:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-457",
- "ts": "2024-01-01T12:00:30Z",
- "from": "user-1",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "elicit-123",
- "result": {
- "action": "accept",
- "content": {
- "approve": true,
- "reason": "Approved for scheduled maintenance"
- }
- }
- }
-}
-```
-
-#### 3. Tool Execution Based on Elicitation
-
-Agent B processes the elicitation response and either executes or rejects the original tool call:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-458",
- "ts": "2024-01-01T12:00:31Z",
- "from": "agent-b",
- "to": ["agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "original-req-123",
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed (approved by user-1)"
- }]
- }
- }
-}
-```
-
-### Enhanced Elicitation Patterns for MCPx
-
-#### Pattern 1: Direct Approval Elicitation
-Simple boolean approval with optional reason (as shown above).
-
-#### Pattern 2: Detailed Parameter Review
-Allow users to review and potentially modify tool parameters:
-
-```json
-{
- "requestedSchema": {
- "type": "object",
- "properties": {
- "approve": {
- "type": "boolean",
- "title": "Approve execution?"
- },
- "modifiedTarget": {
- "type": "string",
- "title": "Target system",
- "default": "production",
- "enum": ["production", "staging", "development"]
- },
- "timeout": {
- "type": "number",
- "title": "Timeout (seconds)",
- "default": 30,
- "minimum": 1,
- "maximum": 300
- }
- }
- }
-}
-```
-
-#### Pattern 3: Delegated Approval Chain
-Support for forwarding approval requests:
-
-```json
-{
- "requestedSchema": {
- "type": "object",
- "properties": {
- "action": {
- "type": "string",
- "enum": ["approve", "deny", "delegate"],
- "enumNames": ["Approve", "Deny", "Delegate to another user"]
- },
- "delegateTo": {
- "type": "string",
- "title": "Delegate to (participant ID)",
- "description": "Only required if action is 'delegate'"
- }
- }
- }
-}
-```
-
-### Protocol Extensions
-
-#### 1. Elicitation Metadata
-Add optional `metadata` field to elicitation requests to indicate type and context:
-
-```json
-{
- "metadata": {
- "elicitationType": "tool_approval",
- "timeout": 300,
- "priority": "high",
- "originalRequest": {...}
- }
-}
-```
-
-#### 2. Async Elicitation Support
-Since tool approvals may take time, support async patterns:
-- Elicitation requests can include correlation IDs
-- Responses can arrive after significant delay
-- Original caller can be notified of pending approval
-
-## Consequences
-
-### Positive
-- **Reuses Existing Pattern**: Leverages MCP's elicitation mechanism rather than creating new protocol messages
-- **Rich UI Support**: Elicitation's schema-based approach enables rich approval UIs
-- **Flexible**: Can handle simple yes/no approvals or complex parameter reviews
-- **User-Friendly**: Familiar form-like interface for approvals
-
-### Negative
-- **Semantic Overload**: Elicitation was designed for gathering information, not authorization
-- **Schema Limitations**: Elicitation schemas are limited to flat objects with primitives
-- **No Native Audit**: Elicitation responses aren't inherently tracked as authorization decisions
-- **Indirect Flow**: Approval happens through side-channel rather than inline with tool call
-
-### Neutral
-- **MCP Compatibility**: Uses standard MCP patterns but extends their semantics
-- **Implementation Complexity**: Similar complexity to dedicated authorization messages
-
-## Implementation Considerations
-
-1. **Timeout Handling**: Tool calls blocked on elicitation need timeout management
-2. **Response Correlation**: Must correctly map elicitation responses to pending tool calls
-3. **Error Handling**: Need clear errors when elicitation is declined/cancelled
-4. **Audit Logging**: Should log tool approval decisions separately from regular elicitations
-5. **Performance**: Elicitation adds latency to tool calls
-
-## Alternatives Considered
-
-1. **Dedicated Authorization Protocol** (See ADR-001)
- - Pros: Cleaner semantics, purpose-built for authorization
- - Cons: New protocol messages to implement
-
-2. **Client-Side Only** (MCP approach)
- - Pros: Simple, no protocol changes needed
- - Cons: Doesn't work for cross-agent tool calls in MCPx
-
-3. **Hybrid Approach**
- - Use elicitation for user approvals
- - Use dedicated protocol for agent-to-agent authorization
- - Pros: Best of both worlds
- - Cons: More complex, two patterns to maintain
-
-## Recommendation
-
-While elicitation CAN be used for tool approval, it may be better to:
-
-1. **Short term**: Use elicitation for tool approval as it requires no new protocol messages
-2. **Long term**: Develop dedicated authorization protocol (ADR-001) for cleaner semantics
-3. **Consider hybrid**: Use elicitation for human approvals, dedicated protocol for automated/policy-based authorization
-
-The elicitation approach is particularly well-suited for scenarios requiring human review and approval, where the form-like interface is beneficial.
-
-## References
-
-- MCP Elicitation Specification: `/modelcontextprotocol/docs/specification/draft/client/elicitation.mdx`
-- MCP Tools Specification: `/modelcontextprotocol/docs/specification/draft/server/tools.mdx`
-- ADR-001 Tool Authorization: `/protocol-spec/v0/adr/001-tool-authorization.md`
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/adr/003-tool-access-control.md b/spec/archive/protocol/v0.0/adr/003-tool-access-control.md
deleted file mode 100644
index 6e10971a..00000000
--- a/spec/archive/protocol/v0.0/adr/003-tool-access-control.md
+++ /dev/null
@@ -1,604 +0,0 @@
-# ADR-003: Tool Access Control in MCPx
-
-## Status
-PROPOSED
-
-## Context
-
-MCPx needs to prevent rogue agents from calling tools they haven't been authorized to use. This is a security requirement that goes beyond user approval - we need to establish and enforce which agents have permission to call which tools BEFORE they attempt to do so.
-
-### The Security Challenge
-
-Current problems:
-1. Any agent in a topic can attempt to call any other agent's tools
-2. Elicitation/approval happens AFTER the attempt, which is too late for security
-3. No mechanism to establish trust relationships between agents
-4. Potential for denial-of-service through unauthorized call attempts
-
-### Requirements
-
-- **Preventive Security**: Block unauthorized calls before they reach the tool owner
-- **Explicit Authorization**: Agents must explicitly grant access to their tools
-- **Revocable Permissions**: Ability to revoke previously granted access
-- **Audit Trail**: Track who has access to what
-- **Minimal Performance Impact**: Security shouldn't significantly slow down legitimate calls
-
-## Decision
-
-Implement a capability-based access control system where agents must possess valid capability tokens to call tools. This will be enforced at multiple levels: by the tool owner, optionally by the gateway, and through cryptographic signatures.
-
-### Access Control Architecture
-
-#### 1. Tool Access Declaration
-
-When an agent joins a topic, it declares its tool access policy:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-100",
- "ts": "2024-01-01T12:00:00Z",
- "from": "agent-b",
- "kind": "system",
- "payload": {
- "type": "tool_access_policy",
- "policy": {
- "mode": "allowlist", // or "denylist" or "open"
- "default": "deny", // default action for unlisted agents
- "rules": [
- {
- "agent": "agent-a",
- "tools": ["read_file", "list_files"],
- "expires": "2024-01-02T00:00:00Z"
- },
- {
- "agent": "user-1",
- "tools": "*", // all tools
- "requires_approval": true // still needs elicitation per call
- }
- ]
- }
- }
-}
-```
-
-#### 2. Capability Token Request
-
-Before calling a tool, an agent must request a capability token:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-101",
- "ts": "2024-01-01T12:00:00Z",
- "from": "agent-a",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "cap-req-1",
- "method": "capabilities/request",
- "params": {
- "tools": ["dangerous_operation"],
- "duration": 3600, // seconds
- "reason": "Need to perform maintenance task"
- }
- }
-}
-```
-
-#### 3. Capability Token Grant
-
-The tool owner can grant (automatically or after user approval) a capability token:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-102",
- "ts": "2024-01-01T12:00:01Z",
- "from": "agent-b",
- "to": ["agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "cap-req-1",
- "result": {
- "token": "cap_2024_abc123def456",
- "tools": ["dangerous_operation"],
- "expires": "2024-01-01T13:00:00Z",
- "signature": "..." // cryptographic signature from agent-b
- }
- }
-}
-```
-
-#### 4. Tool Call with Capability
-
-When calling a tool, the agent includes the capability token:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-103",
- "ts": "2024-01-01T12:05:00Z",
- "from": "agent-a",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "tool-call-1",
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "staging"},
- "capability": "cap_2024_abc123def456"
- }
- }
-}
-```
-
-#### 5. Capability Validation
-
-Agent B validates the capability before executing:
-- Checks signature authenticity
-- Verifies token hasn't expired
-- Confirms tool is included in capability
-- Validates caller matches token holder
-
-If invalid, returns an error immediately:
-
-```json
-{
- "error": {
- "code": -32003,
- "message": "Invalid or missing capability token",
- "data": {
- "reason": "Token expired"
- }
- }
-}
-```
-
-### Gateway Enforcement (Optional)
-
-Gateways can provide an additional security layer by:
-
-1. **Caching Access Policies**: Gateways cache agent access policies
-2. **Pre-filtering**: Block tool calls without valid capabilities before forwarding
-3. **Rate Limiting**: Prevent capability request spam
-4. **Revocation Lists**: Maintain lists of revoked capabilities
-
-```json
-{
- "protocol": "mcp-x/v0",
- "id": "msg-104",
- "ts": "2024-01-01T12:05:00Z",
- "from": "gateway",
- "to": ["agent-a"],
- "kind": "system",
- "payload": {
- "type": "tool_call_blocked",
- "reason": "No valid capability for tool 'dangerous_operation' on agent 'agent-b'",
- "suggestion": "Request capability first using capabilities/request"
- }
-}
-```
-
-### Access Control Modes
-
-Agents can operate in different modes:
-
-1. **Open Mode**: All tools accessible to everyone (backward compatible)
-2. **Allowlist Mode**: Only specified agents can access tools
-3. **Denylist Mode**: Everyone except specified agents can access tools
-4. **Hybrid Mode**: Default policy with exceptions
-
-### Capability Token Structure
-
-```typescript
-interface CapabilityToken {
- id: string; // Unique token ID
- issuer: string; // Agent ID that issued token
- holder: string; // Agent ID that can use token
- tools: string[]; // List of authorized tools or "*"
- constraints?: {
- maxUses?: number; // Maximum number of uses
- validFrom?: string; // ISO timestamp
- validUntil?: string; // ISO timestamp
- arguments?: Record; // Constraints on tool arguments
- };
- signature: string; // Cryptographic signature
-}
-```
-
-## Consequences
-
-### Positive
-- **Strong Security**: Unauthorized agents cannot call tools they lack capabilities for
-- **Explicit Trust**: Clear trust relationships between agents
-- **Revocable**: Can revoke access by invalidating tokens
-- **Audit Trail**: All capability grants and uses are logged
-- **DoS Prevention**: Rogue agents can't spam tool calls
-- **Flexible**: Supports various access control patterns
-
-### Negative
-- **Additional Complexity**: Requires capability management
-- **Performance Overhead**: Extra round-trip for capability requests
-- **State Management**: Agents and gateways must track capabilities
-- **Breaking Change**: Not backward compatible with simple tool calling
-
-### Neutral
-- **Cryptographic Requirements**: Needs signature verification (but libraries exist)
-- **Token Management**: Similar to OAuth/JWT patterns developers know
-- **Gateway Optional**: Can work with or without gateway enforcement
-
-## Security Analysis: Man-in-the-Middle Attacks
-
-### Attack Scenario
-
-In MCPx, all messages in a topic are visible to all participants (broadcast by default). A malicious agent could:
-
-1. **Observe capability token exchange**: See Agent A receive a capability token from Agent B
-2. **Steal and replay the token**: Use the token to impersonate Agent A
-3. **Intercept tool calls**: See the capability tokens being used in tool calls
-
-#### Attack Example
-
-```
-1. Agent B grants capability to Agent A:
- {from: "agent-b", to: ["agent-a"], capability: "cap_xyz"}
-
-2. Malicious Agent M observes this message in the topic
-
-3. Agent M attempts to use the stolen token:
- {from: "agent-m", to: ["agent-b"], method: "tools/call",
- params: {capability: "cap_xyz"}}
-```
-
-### Defense Mechanisms
-
-#### 1. Token Binding to Agent Identity
-
-Capability tokens MUST be cryptographically bound to the holder's identity:
-
-```typescript
-interface SecureCapabilityToken {
- holder: string; // Agent ID that can use token
- holderPublicKey: string; // Public key of the holder
- // ... other fields ...
- issuerSignature: string; // Signed by issuer
-}
-```
-
-When using a capability, the caller must prove ownership:
-
-```json
-{
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "capability": "cap_xyz",
- "proof": {
- "timestamp": "2024-01-01T12:05:00Z",
- "nonce": "unique-random-value",
- "signature": "..." // Signed with holder's private key
- }
- }
-}
-```
-
-#### 2. Validation Process
-
-Agent B validates:
-1. **Token validity**: Signature matches issuer (Agent B's own signature)
-2. **Holder verification**: `from` field matches token's `holder` field
-3. **Proof of possession**: Caller's signature proves they have the private key
-4. **Replay prevention**: Timestamp and nonce prevent replay attacks
-
-#### 3. Direct Message Capability Exchange (Optional)
-
-For sensitive capabilities, use directed messages instead of broadcast:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "to": ["agent-a"], // Directed only to Agent A
- "kind": "mcp",
- "payload": {
- "result": {
- "token": "cap_xyz",
- "encrypted": true // Token encrypted with Agent A's public key
- }
- }
-}
-```
-
-However, this requires:
-- Gateway support for directed messages
-- Public key infrastructure for encryption
-- May not prevent observation if gateway is compromised
-
-#### 4. Channel Binding
-
-Bind capabilities to specific communication channels:
-
-```typescript
-interface ChannelBoundToken {
- holder: string;
- channelId: string; // Specific WebSocket connection ID
- sessionId: string; // Specific session identifier
- // ...
-}
-```
-
-This prevents tokens from being used on different connections, even by the same agent.
-
-### Residual Vulnerabilities
-
-Even with these defenses:
-
-1. **Compromised Agent Keys**: If an agent's private key is stolen, attacker can impersonate
- - Mitigation: Key rotation, hardware security modules
-
-2. **Gateway Compromise**: A compromised gateway could forge messages
- - Mitigation: End-to-end encryption between agents
-
-3. **Capability Leak via Side Channels**: Tokens might leak through logs, errors, etc.
- - Mitigation: Careful handling, token redaction in logs
-
-4. **Social Engineering**: Tricking agents into granting capabilities
- - Mitigation: User confirmation for sensitive capability grants
-
-### Recommended Implementation
-
-1. **Mandatory**: Token binding to holder identity with signature verification
-2. **Mandatory**: Replay prevention with timestamp/nonce
-3. **Recommended**: Direct message exchange for sensitive capabilities
-4. **Optional**: Channel binding for high-security environments
-5. **Optional**: End-to-end encryption for defense-in-depth
-
-## Implementation Considerations
-
-1. **Bootstrap Problem**: How does an agent get initial capabilities?
- - Solution: User-agents (humans) can have implicit capabilities
- - Solution: Topics can have default capability policies
-
-2. **Capability Discovery**: How do agents know what capabilities they need?
- - Solution: Include required capabilities in tool listings
- - Solution: Error messages guide agents to request capabilities
-
-3. **Offline Agents**: What if tool owner is offline when capability is needed?
- - Solution: Pre-issued long-lived capabilities
- - Solution: Capability delegation to online agents
-
-4. **Revocation**: How to revoke compromised capabilities?
- - Solution: Broadcast revocation notices
- - Solution: Short-lived tokens with refresh mechanism
-
-5. **Key Management**: How do agents manage cryptographic keys?
- - Solution: Use existing PKI or derive from agent credentials
- - Solution: Gateway can act as certificate authority
-
-## Migration Path
-
-1. **Phase 1**: Implement capability system in parallel with open access
-2. **Phase 2**: Agents can opt-in to capability requirements
-3. **Phase 3**: Gateways begin enforcing capabilities where configured
-4. **Phase 4**: Make capability-based access the default
-
-## Alternatives Considered
-
-1. **Pure Elicitation-Based**: Use elicitation for all tool calls
- - Rejected: Doesn't prevent unauthorized attempts, enables DoS
-
-2. **Topic-Level Permissions**: Set permissions when joining topic
- - Rejected: Too coarse, doesn't allow dynamic permission changes
-
-3. **Challenge-Response**: Require proof of authorization per call
- - Rejected: Too much latency for every call
-
-4. **Trust Scores**: Reputation-based system
- - Rejected: Complex, doesn't provide hard security guarantees
-
-5. **Gateway-Enforced Privilege Separation** (Alternative Design)
- - See detailed analysis below
-
-### Alternative Design: Gateway-Enforced Privilege Separation
-
-Instead of agent-managed capabilities, the gateway could issue two types of tokens with different privilege levels:
-
-#### Token Types
-
-1. **Full Access Token** (Type: `full`)
- - Can send any message type including direct `tools/call`
- - Typically issued to trusted agents and human users
- - Tool calls go through immediately
-
-2. **Request-Only Token** (Type: `restricted`)
- - Can only send `tools/request` messages, not direct `tools/call`
- - Issued to untrusted or new agents
- - Tool calls require fulfillment by a privileged participant
-
-#### How It Works
-
-##### 1. Gateway Token Assignment
-
-When an agent connects, the gateway assigns a token type:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "from": "gateway",
- "to": ["agent-a"],
- "kind": "system",
- "payload": {
- "type": "welcome",
- "tokenType": "restricted", // or "full"
- "participantId": "agent-a"
- }
-}
-```
-
-##### 2. Restricted Agent Makes Tool Request
-
-A restricted agent cannot call tools directly, but can request them:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "from": "agent-a",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "req-123",
- "method": "tools/request", // Not tools/call
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "staging"},
- "reason": "Need to complete maintenance task"
- }
- }
-}
-```
-
-##### 3. Gateway Transforms and Broadcasts
-
-The gateway intercepts and transforms the request:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "from": "gateway",
- "kind": "system",
- "payload": {
- "type": "tool_request_pending",
- "requester": "agent-a",
- "target": "agent-b",
- "tool": "dangerous_operation",
- "arguments": {"target": "staging"},
- "requestId": "req-123"
- }
-}
-```
-
-##### 4. Privileged Agent Fulfills Request
-
-An agent with full access can choose to fulfill the request:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "from": "user-1",
- "to": ["agent-b"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "call-456",
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "staging"},
- "onBehalfOf": "agent-a",
- "requestId": "req-123"
- }
- }
-}
-```
-
-##### 5. Response Routing
-
-The tool response is sent to both the fulfiller and original requester:
-
-```json
-{
- "protocol": "mcp-x/v0",
- "from": "agent-b",
- "to": ["user-1", "agent-a"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "id": "call-456",
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }],
- "fulfilledBy": "user-1",
- "originalRequester": "agent-a"
- }
- }
-}
-```
-
-#### Advantages of Gateway Privilege Separation
-
-1. **Simpler Implementation**: No cryptographic capabilities needed
-2. **Centralized Control**: Gateway manages all permissions
-3. **Clear Trust Boundaries**: Binary trust model (full vs restricted)
-4. **No Token Theft Risk**: Privileges tied to connection, not transferable tokens
-5. **Human-in-the-Loop**: Natural pattern for human oversight of untrusted agents
-6. **Gradual Trust**: Agents can be promoted from restricted to full over time
-
-#### Disadvantages
-
-1. **Gateway Dependency**: All security depends on gateway implementation
-2. **Less Flexible**: Binary model vs granular per-tool capabilities
-3. **Gateway Becomes Bottleneck**: Must process all permission checks
-4. **No Peer-to-Peer Trust**: Agents can't directly trust each other
-5. **Stateful Gateway**: Gateway must track token types and connections
-
-#### Hybrid Approach
-
-Could combine both approaches:
-- Gateway privilege separation for coarse-grained trust levels
-- Agent capabilities for fine-grained tool access control
-- Restricted agents must get capabilities AND fulfillment
-- Full agents only need capabilities
-
-## Recommendation
-
-Consider a **phased approach**:
-
-### Phase 1: Gateway Privilege Separation (Immediate Security)
-Start with gateway-enforced privilege separation as it:
-- Provides immediate security benefits
-- Requires no cryptographic infrastructure
-- Is simpler to implement and understand
-- Naturally supports human-in-the-loop patterns
-
-### Phase 2: Agent Capabilities (Fine-Grained Control)
-Add agent-managed capabilities for:
-- Granular per-tool access control
-- Peer-to-peer trust relationships
-- Reduced gateway dependency
-- Advanced security scenarios
-
-### Why This Phased Approach Works
-
-1. **Immediate Protection**: Gateway privilege separation can be deployed quickly to prevent rogue agents
-2. **Progressive Enhancement**: Capabilities can be added without breaking existing privilege separation
-3. **Best of Both Worlds**: Coarse-grained gateway control + fine-grained agent control
-4. **Graceful Degradation**: If capability system fails, gateway separation still provides baseline security
-
-### Combined Security Model
-
-In the final state:
-- **Restricted agents**: Must use `tools/request` AND need fulfillment from privileged agents
-- **Full agents**: Can use `tools/call` but still need valid capabilities from target agents
-- **Human users**: Have full access by default but can delegate through tool requests
-- **Gateway enforcement**: Blocks invalid messages at transport layer
-- **Agent enforcement**: Validates capabilities at application layer
-
-This can be combined with elicitation (ADR-002) for human approval workflows:
-1. Gateway tokens control WHO can attempt tool calls
-2. Capability tokens control WHICH tools can be called
-3. Elicitation controls WHETHER specific calls are approved
-
-## References
-
-- ADR-001: Tool Authorization
-- ADR-002: Elicitation for Tool Approval
-- OAuth 2.0 RFC 6749
-- JSON Web Token (JWT) RFC 7519
-- Capability-based Security literature
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.0/decisions/decision-1.md b/spec/archive/protocol/v0.0/decisions/decision-1.md
deleted file mode 100644
index f64e4e42..00000000
--- a/spec/archive/protocol/v0.0/decisions/decision-1.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# Decision 1: How to Send Chat to All Participants without Broadcasting Requests
-
-Status: Proposed
-Date: 2025-08-17
-Owners: MCPx WG
-
-## Context
-
-- MCPx v1 intentionally disallows broadcasting JSON-RPC requests because it breaks MCP’s client/server model and complicates response handling.
-- We still want a simple way to send "chat messages" to everyone in a room.
-- MCP tools remain the focus; the envelope supports notifications (no `payload.id`) that can be broadcast.
-
-## Decision (proposed)
-
-Use broadcast MCP notifications for room-wide chat. Define a canonical notification method (e.g., `notifications/chat/message`) that any participant MAY emit with an empty `to` array, and that all participants SHOULD display/log if they support chat UX.
-
-- This preserves MCP purity (no broadcast requests), keeps the envelope small, and avoids reintroducing a `chat` envelope kind.
-- Tools like `chat.say` MAY exist as syntactic sugar that emit the notification under the hood.
-
-## Options Considered
-
-### Option A — Broadcast MCP Notification (recommended)
-- Description: Send a JSON-RPC notification (`payload.method = "notifications/chat/message"`) with no `payload.id` and no `to` (broadcast). Content carries `{ text, format? }`.
-- Pros:
- - Aligns with v1 rule: only notifications can be broadcast
- - Minimal surface area; no new envelope kinds
- - Easy to implement and interoperable (any client can listen)
-- Cons:
- - Not a tool call; no tool schema validation pathway
- - No per-recipient delivery guarantees (consistent with room visibility)
-
-### Option B — `chat.say` Tool to a Coordinator (fan-out server-side)
-- Description: Caller invokes `chat.say` on a coordinator agent; coordinator emits a broadcast notification to the room.
-- Pros:
- - Retains tool semantics for the caller (familiar MCP flow)
- - Centralizes moderation, formatting, and rate limiting
-- Cons:
- - Requires a coordinator role and extra hop
- - Coordinator becomes a dependency and potential bottleneck
-
-### Option C — Client-Side Fan-out of `chat.say` Tool Calls (unicast many)
-- Description: Caller lists participants and sends a 1:1 `tools/call` to each with `chat.say`.
-- Pros:
- - Pure MCP tool semantics; no broadcast
- - Per-recipient responses/acks possible
-- Cons:
- - N network sends; O(N) overhead and duplication
- - Message ordering inconsistencies across recipients
-
-### Option D — Reintroduce `chat` Envelope Kind (non-MCP)
-- Description: Keep a simple `chat` envelope kind for human-readable messages.
-- Pros:
- - Very simple to consume; no MCP processing
- - Clear separation from tool traffic
-- Cons:
- - Expands envelope surface area again
- - Diverges from “MCP-first” principle; duplicate representation of chat (tool vs kind)
-
-### Option E — Gateway Broadcast API (system-side fan-out)
-- Description: Gateway accepts a single authenticated submit (REST/WS control), then emits a broadcast notification to the room.
-- Pros:
- - Efficient; avoids client-side N-way sends
- - Consistent moderation and rate limiting
-- Cons:
- - Out-of-band relative to MCP traffic (separate API surface)
- - Adds gateway complexity and policy surface
-
-### Option F — Topic-Per-Channel for Chat
-- Description: Use a separate room-level chat topic; participants subscribe; gateway bridges from MCP tool calls.
-- Pros:
- - Isolation of chat traffic; scalable retention policy
- - Can be bridged to existing chat systems
-- Cons:
- - Multiple topics to manage; more moving parts
- - Still requires a bridge layer for MCP-first apps
-
-### Option G — Event-Sourced Chat Stream
-- Description: Treat chat as an immutable event log within the topic. Participants append chat events using a standardized notification method and maintain local chat state by replaying events.
-- Pros:
- - Naturally handles message ordering; provides replay capability
- - Fits well with distributed systems patterns
-- Cons:
- - Requires more complex state management on client side
- - Potentially higher memory usage
-
-### Option H — Chat as MCP Resource
-- Description: Model the chat room as an MCP resource that participants can subscribe to and update. Chat messages become resource update notifications.
-- Pros:
- - Leverages existing MCP resource patterns
- - Provides structured subscription model
-- Cons:
- - Resource model might be overkill for simple chat
- - Adds complexity to resource management
-
-### Option I — Hybrid Notification + Tool Pattern
-- Description: Support both broadcast notifications (Option A) AND `chat.say` tools. Tools validate schema and provide responses, while notifications handle the actual broadcast.
-- Pros:
- - Best of both worlds—tool validation for senders, efficient broadcast for recipients
-- Cons:
- - Dual pathways could cause confusion
- - Slight increase in spec complexity
-
-### Option J — Message Relay Pattern
-- Description: Participants send directed `chat.relay` tool calls to designated relay participants who then emit broadcast notifications.
-- Pros:
- - Maintains tool semantics; allows for distributed relay architecture
-- Cons:
- - Requires relay participant designation
- - Adds network hops
-
-### Option K — Topic Metadata Channel
-- Description: Use a separate metadata/control channel within the same WebSocket connection for chat, parallel to the main MCP envelope stream.
-- Pros:
- - Complete separation of concerns; optimized for each use case
-- Cons:
- - Violates the "single envelope" design principle
- - Increases connection complexity
-
-## Implications
-- Choosing A (recommended) keeps v1 simple: broadcast notifications for chat, no broadcast requests.
-- B can layer moderation and formatting policies without changing the core spec.
-- C is simplest to implement without broadcast but is inefficient and can cause fragmentation.
-- D increases spec surface area; likely not aligned with v1 simplification goals.
-- E/F are operational patterns that can be documented in PATTERNS.md as alternatives.
-- G-K represent more complex architectural patterns that may suit specific use cases but add implementation overhead.
-
-## Follow-ups
-- Specify a minimal payload schema for `notifications/chat/message` in PATTERNS.md (text, format, optional meta like mentions/thread id).
-- Add rate limit guidance for chat notifications in Security.
-- Provide a coordinator example that accepts `chat.say` and emits the corresponding notification.
diff --git a/spec/archive/protocol/v0.1/SPEC.md b/spec/archive/protocol/v0.1/SPEC.md
deleted file mode 100644
index bf26fa6a..00000000
--- a/spec/archive/protocol/v0.1/SPEC.md
+++ /dev/null
@@ -1,676 +0,0 @@
-# MCPx v0.1 Protocol Specification
-
-Status: v0.1
-Date: 2025-08-29
-Intended Status: Experimental
-Editors: RJ Corwin (https://github.com/rjcorwin)
-
----
-
-## Requirements Language
-
-The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
-
----
-
-## 1. Abstract
-
-MCPx enables real-time collaboration between multiple AI agents and humans by extending the Model Context Protocol with broadcast messaging and capability-based security. The protocol wraps MCP messages in envelopes that include routing and permission metadata, allowing gateways to enforce access control without parsing payloads. Untrusted agents use proposals to suggest operations that trusted participants can review and execute, enabling progressive automation as orchestrators learn from human decisions over time.
-
----
-
-## 2. Goals and Non-Goals
-
-### 2.1 Goals
-- **Collaborative Governance**: Enable multiple humans and AI systems to jointly supervise agent operations
-- **Progressive Automation**: Allow orchestrators to learn from collective decisions over time
-- **Security Through Isolation**: Untrusted agents propose rather than execute, maintaining safety
-- **Observable Operations**: All messages broadcast by default, enabling auditing and pattern learning
-- **Stateless Gateway**: Minimal gateway state for scalability, with lazy enforcement
-- **MCP Compatibility**: Every participant implements standard MCP server interfaces
-
-### 2.2 Non-Goals
-- End-to-end encryption or private channels (all messages visible within topic)
-- Payload validation at gateway (only validates `kind` field, not message contents)
-- Message persistence or replay (topics are ephemeral)
-- Cross-topic routing or participant discovery
-- Guaranteed delivery (WebSocket best-effort)
-- Application-layer semantics or business logic
-
----
-
-## 3. Message Envelope
-
-All data flowing over a topic MUST be a single top-level JSON envelope:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "2f6b6e70-7b36-4b8b-9ad8-7c4f7d0e2d0b",
- "ts": "2025-08-26T14:00:00Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp/request:tools/call",
- "correlation_id": "env-1",
- "payload": { /* kind-specific body */ }
-}
-```
-
-Field semantics:
-- `protocol`: MUST be `"mcpx/v0.1"` for this version
-- `id`: globally unique message id (e.g., UUIDv4)
-- `ts`: RFC3339 timestamp
-- `from`: stable participant id within the topic
-- `to`: array of participant ids (empty/omitted = broadcast)
-- `kind`: Message type with format:
- - `mcp/request:METHOD` - MCP request/notification (e.g., `mcp/request:tools/call`)
- - `mcp/response:METHOD` - MCP response (e.g., `mcp/response:tools/call`)
- - `mcp/proposal:METHOD` - MCP proposal (e.g., `mcp/proposal:tools/call`)
- - `chat` - Chat messages
- - `presence` - Join/leave events
- - `system` - Gateway system messages
-- `correlation_id`: links related envelopes in a conversation chain
- - Response → Request: `mcp/response:METHOD` MUST reference the originating `mcp/request:METHOD`
- - Fulfillment → Proposal: `mcp/request:METHOD` MAY reference a `mcp/proposal:METHOD` when fulfilling it
- - Error → Trigger: `system` error messages SHOULD reference the envelope that caused the error
- - Reply → Message: Any envelope MAY reference another for threading/context
-- `payload`: object; structure depends on `kind`
-
-### 3.1 MCP Messages (kind = "mcp/request:METHOD[:CONTEXT]")
-
-MCP requests and notifications use the format `mcp/request:METHOD[:CONTEXT]` where:
-- METHOD is the MCP method name (e.g., `tools/call`, `resources/read`)
-- CONTEXT is the specific operation (e.g., tool name, resource URI)
-
-#### 3.1.1 MCP Requests
-
-Example tool call request:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-call-1",
- "from": "trusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/request:tools/call:dangerous_operation",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-#### 3.1.2 MCP Responses (kind = "mcp/response:METHOD[:CONTEXT]")
-
-Responses MUST include the `correlation_id` field referencing the original request's `id`. This is critical for translating MCP's client-server request/response model to MCPx's multi-participant broadcast paradigm, allowing all participants to match responses to their corresponding requests.
-
-Response to the above tool call. The response SHOULD include the operation context in the kind:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-resp-1",
- "from": "target-agent",
- "to": ["trusted-agent"],
- "kind": "mcp/response:tools/call:dangerous_operation",
- "correlation_id": "env-call-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }]
- }
- }
-}
-```
-
-Note: The extended kind format (`METHOD:CONTEXT`) makes responses self-contained and enables fine-grained capability control. The MCP payload remains unchanged.
-
-### 3.2 MCP Proposals (kind = "mcp/proposal:METHOD[:CONTEXT]")
-
-Participants with restricted capabilities MUST use proposals instead of direct MCP operations:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-req-1",
- "from": "untrusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/proposal:tools/call:dangerous_operation",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-This is an MCPx-specific protocol extension that proposes an MCP operation requiring fulfillment by a participant with appropriate capabilities.
-
-#### 3.2.1 Proposal Fulfillment
-
-A participant with appropriate capabilities fulfills the proposal by making the real MCP call. The `correlation_id` field is critical for matching approvals to their original proposals:
-- Proposals MUST NOT include a `correlation_id` (they originate new workflows)
-- Fulfillment messages MUST include `correlation_id` referencing the proposal's `id`
-- This allows participants to track which fulfillment corresponds to which proposal
-- The correlation chain enables audit trails and multi-step approval workflows
-
-Example fulfillment:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-fulfill-1",
- "from": "human-user",
- "to": ["target-agent"],
- "kind": "mcp/request:tools/call:dangerous_operation",
- "correlation_id": "env-req-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-The response goes to both the fulfiller and the original proposer. Note that the response's `correlation_id` references the fulfillment message (`env-fulfill-1`), NOT the original proposal (`env-req-1`). This maintains the standard request/response pairing while the proposer can still receive the outcome:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-fulfill-resp-1",
- "from": "target-agent",
- "to": ["human-user", "untrusted-agent"],
- "kind": "mcp/response:tools/call:dangerous_operation",
- "correlation_id": "env-fulfill-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed successfully"
- }]
- }
- }
-}
-```
-
-### 3.3 Chat Messages (kind = "chat")
-
-Chat messages are MCPx-specific and do not pollute the MCP namespace:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-chat-1",
- "from": "user-alice",
- "kind": "chat",
- "payload": {
- "text": "Hello everyone!",
- "format": "plain"
- }
-}
-```
-
-- `text` (required): The message content
-- `format` (optional): "plain" or "markdown", defaults to "plain"
-- Chat messages are typically broadcast (empty/omitted `to` array)
-
-### 3.4 Presence Messages (kind = "system/presence")
-
-Presence messages are broadcast to notify all participants about join/leave events:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-presence-1",
- "from": "system:gateway",
- "kind": "system/presence",
- "payload": {
- "event": "join",
- "participant": {
- "id": "new-agent",
- "capabilities": ["mcp/proposal:*", "chat"]
- }
- }
-}
-```
-
-- `event` (required): Either `"join"` or `"leave"`
-- `participant` (required): Information about the participant
- - `id`: The participant's identifier
- - `capabilities`: The participant's capabilities (for `join` events)
-
-Note: Presence messages are broadcast to all participants. The joining participant also receives a welcome message addressed specifically to them (via the `to` field) with their authoritative capabilities and the current participant list.
-
-### 3.5 System Messages (kind = "system/*")
-
-#### 3.5.1 Welcome Message (kind = "system/welcome")
-
-When a participant connects, the gateway MUST send a welcome message addressed specifically to that participant (using the `to` field):
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-welcome-1",
- "from": "system:gateway",
- "to": ["new-participant"],
- "kind": "system/welcome",
- "payload": {
- "you": {
- "id": "new-participant",
- "capabilities": ["mcp/proposal:*", "chat"]
- },
- "participants": [
- {
- "id": "agent-1",
- "capabilities": ["mcp/*", "chat"]
- },
- {
- "id": "agent-2",
- "capabilities": ["mcp/response:*", "chat"]
- }
- ]
- }
-}
-```
-
-- `you`: The joining participant's own information and authoritative capabilities
-- `participants`: Current list of other participants in the topic and their capabilities
-- Other participants can safely ignore this message (it's addressed specifically to the new participant)
-
-#### 3.5.2 Capability Violation (kind = "system/error")
-
-When a participant attempts an operation they lack capability for:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-violation-1",
- "from": "system:gateway",
- "to": ["violator"],
- "kind": "system/error",
- "correlation_id": "env-bad-call",
- "payload": {
- "error": "capability_violation",
- "message": "You lack capability for 'mcp/request:tools/call'",
- "attempted_kind": "mcp/request:tools/call",
- "your_capabilities": ["mcp/proposal:*", "chat"]
- }
-}
-```
-
----
-
-## 4. Security Model
-
-### 4.1 Capability-Based Access Control
-
-The gateway assigns capabilities to each connection, determining which message kinds they can send. Capabilities support wildcards for flexible access control.
-
-**Wildcard Patterns:**
-- `mcp/*` - All MCP-related messages (requests, responses, proposals)
-- `mcp/request:*` - All MCP requests/notifications
-- `mcp/request:tools/*` - All tool operations (call, list)
-- `mcp/request:resources/*` - All resource operations (read, list, subscribe)
-- `mcp/response:*` - Can respond to any MCP request
-- `mcp/proposal:*` - Can propose any MCP operation
-
-**Reserved Namespace:**
-The `system/*` namespace is reserved exclusively for the gateway. Participants MUST NOT send messages with `kind` starting with `system/`. The gateway MUST reject any such attempts. Only the gateway can generate system messages (`system/welcome`, `system/presence`, `system/error`).
-
-**Example Capability Sets:**
-
-Gateways may implement various capability profiles based on their security requirements:
-
-1. **Full Access** example:
- - `["mcp/*", "chat"]`
- - Can initiate any MCP operations, respond, and fulfill proposals
-
-2. **Proposal-Only** example:
- - `["mcp/proposal:*", "mcp/response:*", "chat"]`
- - Cannot send direct MCP requests, must use proposals
- - Can respond when their proposals are fulfilled
-
-3. **Response-Only** example:
- - `["mcp/response:*", "chat"]`
- - Can only respond to MCP requests, cannot initiate
-
-4. **Read-Only** example:
- - `["mcp/request:resources/read", "mcp/request:*/list", "mcp/response:*", "chat"]`
- - Can read resources and list anything, but cannot modify
-
-5. **Tool-Only** example:
- - `["mcp/request:tools/*", "mcp/response:tools/*", "chat"]`
- - Can use tools but not access resources
-
-**Progressive Trust Example:**
-
-One possible pattern is to expand capabilities as trust increases:
-1. Initial: `["mcp/proposal:*", "chat"]` - Proposals only
-2. Basic: Add `["mcp/request:resources/read"]` - Can read resources
-3. Trusted: Add `["mcp/request:tools/*"]` - Can use tools
-4. Full: Replace with `["mcp/*"]` - Unrestricted access
-
-### 4.2 Gateway Enforcement (Lazy)
-
-The gateway uses lazy enforcement for efficiency, only checking capabilities against the `kind` field:
-
-**What the Gateway Does:**
-- Pattern matches `kind` against participant's capabilities
-- Blocks messages if no capability matches
-- Returns error responses for capability violations
-- **Does NOT validate that payload matches the kind**
-
-**What the Gateway Does NOT Do:**
-- Parse or validate JSON-RPC payloads
-- Understand MCP semantics
-- Detect spoofing (where `kind` doesn't match payload content)
-
-**Security Model:** The gateway relies on receiving participants to detect and reject spoofed messages where the envelope `kind` doesn't match the actual payload. This division of responsibility keeps the gateway lightweight while maintaining security.
-
-**Pattern Matching Examples:**
-- Kind `mcp/request:tools/call` matches capabilities: `mcp/*`, `mcp/request:*`, `mcp/request:tools/*`, `mcp/request:tools/call`
-- Kind `mcp/response:tools/call` matches: `mcp/*`, `mcp/response:*`, `mcp/response:tools/*`
-- Kind `chat` only matches exact: `chat`
-
-### 4.3 Participant Validation (Strict)
-
-Receiving participants MUST validate that messages are well-formed:
-- **CRITICAL**: Verify both METHOD and CONTEXT from `kind` match the payload
- - For `kind: "mcp/request:tools/call:read_file"`, validate:
- - `payload.method` is `"tools/call"`
- - `payload.params.name` is `"read_file"`
-- Drop or report malformed messages
-- MAY track misbehaving participants for reputation scoring
-
-**Security Note:** Participants MUST validate that the envelope `kind` (including both METHOD and CONTEXT) matches the payload content before accepting any message. Without this validation, malicious participants could spoof operations by using a `kind` they have capabilities for while sending a payload for operations they don't have permission to perform (e.g., using `kind: "mcp/request:tools/call:safe_tool"` while `payload.params.name` is actually `"dangerous_tool"`).
-
-**Schema Mismatch Warning:** Participants may observe messages with schemas that differ from what was advertised:
-- Other participants might advertise one tool schema in their capabilities but send different parameters
-- Participants joining mid-conversation may see responses to requests they never observed
-- The gateway doesn't validate payload contents, only the `kind` field
-- Always parse messages defensively and validate `kind` matches payload structure before processing
-
-This lazy enforcement model keeps gateways fast while maintaining security through edge validation.
-
----
-
-## 5. Realtime Gateway API
-
-### 5.1 Authentication and Capability Assignment
-
-The gateway determines capabilities during authentication. Implementation-specific policies may include:
-
-1. **Token-based**: Tokens map to specific capability sets
- - Implementations may encode capabilities in tokens or map tokens to capability profiles
-2. **Identity-based**: Map authenticated identities to capability sets
-3. **Topic access control**: Topics may be public, private, or restricted
-4. **Dynamic capabilities**: Capabilities may be modified during a session
-
-### 6.2 WebSocket Connection
-
-Connect: `GET /ws?topic=` with Authorization header
-
-The gateway:
-1. Validates the bearer token (if provided)
-2. Maps the token to a participant ID (implementation-specific)
-3. Determines capabilities based on implementation policy
-4. **MUST** send welcome message with the assigned participant ID and accurate capabilities
-5. **MUST** enforce capability rules on all subsequent messages
-
-**Note:** Participants only provide their bearer token. The gateway is responsible for mapping tokens to participant IDs through its own implementation-specific mechanism.
-
-The capabilities in the welcome message constitute the authoritative list of what operations the participant can perform. Participants SHOULD use this list to understand their allowed operations.
-
-### 6.3 Message Routing
-
-Participants can configure their message routing preference (implementation-specific):
-
-**Routing Modes:**
-- **All**: Receive every message in the topic (default)
-- **Directed**: Only receive messages where:
- - `to` field includes their participant ID, OR
- - `to` field is empty/omitted (broadcast)
-
-This allows participants to reduce noise while still receiving broadcasts and messages directed to them. The gateway MUST respect these preferences when routing messages.
-
-### 6.4 Message Filtering
-
-For each incoming message from a participant:
-
-```python
-if not matches_any_capability(message.kind, participant.capabilities):
- send_error(f"Capability violation: you lack capability for '{message.kind}'")
- broadcast_violation_notice() # optional
- return
-send_to_topic(message)
-```
-
----
-
-## 6. Version Compatibility
-
-### 6.1 Breaking Changes
-
-This is a v0.x release. Breaking changes are expected between minor versions until v1.0:
-- v0.1 is NOT backward compatible with v0.0
-- Clients and gateways MUST use matching protocol versions
-- No compatibility guarantees until v1.0 release
-
-### 6.2 Migration from v0.0
-
-Key breaking changes from v0.0:
-- Protocol identifier changed from `mcp-x/v0` to `mcpx/v0.1`
-- Message kinds now use hierarchical namespacing (e.g., `mcp/request:tools/call`)
-- Capabilities replace privilege levels
-- Chat moved to dedicated `chat` kind
-
-### 6.3 Future Compatibility
-
-- v0.x series is experimental and subject to breaking changes
-- v1.0 will establish stable protocol with compatibility guarantees
-- Production deployments should pin specific v0.x versions
-
----
-
-## 7. Security Considerations
-
-The security model for MCPx is detailed in Section 4. Key considerations include:
-
-- **Capability-based access control** enforced by the gateway (Section 4.1)
-- **Lazy enforcement** at the gateway level for performance (Section 4.2)
-- **Strict validation** requirements for all participants (Section 4.3)
-- **Reserved namespaces** preventing participant spoofing of system messages (Section 4.1)
-
-Implementers MUST pay particular attention to the participant validation requirements to prevent spoofing attacks where the envelope `kind` doesn't match the payload content.
-
-### 7.1 Best Practices
-
-1. **Start restricted**: New agents should begin with minimal capabilities (`mcp/proposal:*`)
-2. **Validate strictly**: All participants MUST validate both METHOD and CONTEXT match payload
-3. **Monitor proposals**: Log and audit proposal/fulfillment patterns
-4. **Progressive trust**: Expand capabilities only after establishing trust through observed behavior
-5. **Report misbehavior**: Track and report participants sending malformed messages
-
----
-
-## 8. Implementation Checklist
-
-### 8.1 Gateway Requirements
-- [ ] **Connection Management**
- - [ ] WebSocket server at `GET /ws?topic=`
- - [ ] Bearer token validation from Authorization header
- - [ ] Token-to-participant-ID mapping (implementation-specific)
- - [ ] Connection state tracking per participant
-
-- [ ] **Capability Enforcement**
- - [ ] Pattern matching engine for wildcard capabilities
- - [ ] Validate message `kind` against sender's capabilities
- - [ ] Block messages that don't match capabilities
- - [ ] Return `system/error` for capability violations
-
-- [ ] **System Messages**
- - [ ] Send `system/welcome` with participant ID and capabilities on connect
- - [ ] Broadcast `system/presence` for join/leave events
- - [ ] Generate `system/error` for protocol violations
- - [ ] Ensure only gateway can send `system/*` messages
-
-- [ ] **Message Routing**
- - [ ] Route messages based on `to` field (broadcast if empty/omitted)
- - [ ] Support participant routing preferences (All vs Directed mode)
- - [ ] Preserve envelope structure without modification
- - [ ] NO payload parsing or validation (lazy enforcement)
-
-### 8.2 Participant Requirements
-- [ ] **Message Validation**
- - [ ] Verify envelope structure before processing
- - [ ] Validate `kind` METHOD matches `payload.method`
- - [ ] Validate `kind` CONTEXT matches payload content (e.g., tool name)
- - [ ] Drop messages that fail validation
- - [ ] Track/report misbehaving participants
-
-- [ ] **MCP Integration**
- - [ ] Implement MCP server capabilities
- - [ ] Handle incoming MCP requests/responses
- - [ ] Generate proper correlation IDs for responses
- - [ ] Include correlation ID in all response messages
-
-- [ ] **Proposal Handling** (if applicable)
- - [ ] Recognize `mcp/proposal:*` messages
- - [ ] Implement fulfillment logic for approved proposals
- - [ ] Include proposal ID as correlation_id when fulfilling
-
-- [ ] **Connection Behavior**
- - [ ] Process `system/welcome` to learn own ID and capabilities
- - [ ] Handle `system/presence` to track other participants
- - [ ] Respect capability restrictions from welcome message
-
----
-
-## 9. Examples
-
-The following examples demonstrate multi-agent orchestration patterns enabled by MCPx's capability-based security model. The core pattern is **delegated fulfillment**, where untrusted agents propose operations that are reviewed and executed by trusted participants.
-
-### 9.1 Proposal-Based Workflow Example
-
-In this example, an agent with limited capabilities uses proposals:
-
-1. Agent connects → receives proposal-only capabilities
-2. Agent attempts MCP request → gateway blocks, returns error
-3. Agent sends `mcp/proposal:METHOD` → visible to all participants
-4. Another participant with appropriate capabilities fulfills it
-5. Fulfiller sends real `mcp/request:METHOD` message to target
-6. Target executes and returns result to fulfiller (and optionally to proposer)
-
-### 9.2 Capability Expansion Example
-
-One possible administrative workflow:
-
-1. Agent operates successfully over time
-2. Administrator observes behavior patterns
-3. Administrator expands agent capabilities
-4. Agent gains access to additional operations
-
-### 9.3 Mixed Environment Example
-
-A gateway might assign different capability profiles:
-
-- Administrative users: `mcp/*` (full access)
-- Service agents: `mcp/response:*` (response-only)
-- New agents: `mcp/proposal:*` (proposal-only)
-- Monitoring tools: `mcp/request:*/list` (read-only)
-
-All participants operate in the same topic with their assigned capabilities.
-
-### 9.4 Delegated Fulfillment Example
-
-A human supervises an untrusted agent through intermediary agents:
-
-1. **Proposer Agent** (`mcp/proposal:*`) proposes writing a file
-2. **Human** reviews the proposal and decides to approve it by directing the **Orchestrator Agent** (`mcp/request:*`) to fulfill the proposal
-4. **Orchestrator Agent** sends the MCP request to **Worker Agent**
-5. **Worker Agent** executes the actual file write operation and responds
-6. Over time, **Human** teaches **Orchestrator Agent** rules about which proposals to auto-approve
-7. **Orchestrator Agent** begins autonomously fulfilling certain proposals without human intervention
-
-This pattern demonstrates **progressive automation** - a key goal of MCPx. As the orchestrator observes human decisions over time, it learns which types of proposals can be safely auto-approved. This transforms human judgment into automated policies, creating a system that becomes more autonomous while maintaining safety through learned boundaries.
-
----
-
-## 10. Appendix: Implementation Notes
-
-### 10.1 Gateway State
-
-Minimal state required per connection:
-```json
-{
- "connectionId": "ws-123",
- "participantId": "agent-a",
- "capabilities": ["mcp/proposal:*", "chat"],
- "connectedAt": "2025-08-26T14:00:00Z"
-}
-```
-
-### 10.2 Proposal Tracking
-
-Optional proposal tracking for fulfillment (maintained by agents, not gateway):
-```json
-{
- "proposalId": "env-proposal-1",
- "proposer": "untrusted-agent",
- "target": "target-agent",
- "method": "tools/call",
- "params": {"name": "dangerous_operation", "arguments": {...}},
- "status": "pending",
- "createdAt": "2025-08-26T14:00:00Z",
- "expiresAt": "2025-08-26T14:05:00Z"
-}
-```
-
-### 11.3 Capability Promotion API
-
-Optional admin endpoint:
-```
-POST /admin/participants/{id}/capabilities
-Authorization: Bearer
-
-Request:
-{
- "add": ["mcp/request:tools/*"],
- "remove": []
-}
-
-Response:
-{
- "participantId": "agent-a",
- "oldCapabilities": ["mcp/proposal:*", "chat"],
- "newCapabilities": ["mcp/proposal:*", "mcp/request:tools/*", "chat"],
- "modifiedBy": "admin-user",
- "modifiedAt": "2025-08-26T14:30:00Z"
-}
-```
-
----
-
-## References
-
-- MCP Specification 2025-06-18
-- MCPx v0.0 Specification
-- ADR-003: Tool Access Control
-- OAuth 2.0 RFC 6749 (for token patterns)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.1/decisions/001-fulfill-message-kind.md b/spec/archive/protocol/v0.1/decisions/001-fulfill-message-kind.md
deleted file mode 100644
index ae5d636a..00000000
--- a/spec/archive/protocol/v0.1/decisions/001-fulfill-message-kind.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Decision: Fulfill Message Kind
-
-**Date**: 2025-08-27
-**Status**: Decided
-**Outcome**: No separate `mcp/fulfill:METHOD` kind needed
-
-## Context
-
-When a participant with appropriate capabilities wants to fulfill a proposal from a restricted participant, they need to execute the actual operation that was proposed. The question arose whether we need a separate message kind `mcp/fulfill:METHOD` to explicitly mark fulfillment actions.
-
-## Options Considered
-
-### Option 1: Add `mcp/fulfill:METHOD` kind
-Create a new message kind specifically for fulfillment:
-```json
-{
- "kind": "mcp/fulfill:tools/call",
- "correlation_id": "proposal-123",
- "payload": { ... }
-}
-```
-
-**Pros:**
-- Explicit semantic marking of fulfillment actions
-- Could enable special gateway handling of fulfillments
-- Clear audit trail of what's a fulfillment vs independent action
-
-**Cons:**
-- Adds complexity to the protocol
-- Requires new capability patterns (`mcp/fulfill:*`)
-- Semantically redundant - fulfillment IS just executing the operation
-- Gateway would need to track proposal state
-
-### Option 2: Use existing `mcp/request:METHOD` with correlation_id (CHOSEN)
-Fulfillment is simply executing the proposed operation with correlation:
-```json
-{
- "kind": "mcp/request:tools/call",
- "correlation_id": "proposal-123",
- "payload": { ... }
-}
-```
-
-**Pros:**
-- No new message kinds needed
-- Simpler capability model
-- Clear semantics: fulfillment = execution
-- Correlation already provides the linkage
-- Gateway remains stateless about proposals
-
-**Cons:**
-- Less explicit about fulfillment intent
-- Requires agents to infer fulfillment from correlation
-
-## Decision
-
-We will **NOT** introduce a separate `mcp/fulfill:METHOD` kind. Fulfillment is accomplished by sending the actual `mcp/request:METHOD` with a `correlation_id` referencing the proposal.
-
-## Rationale
-
-1. **Simplicity**: The protocol remains minimal without additional message types
-2. **Clear semantics**: Fulfilling a proposal means executing it - they're the same action
-3. **Gateway simplicity**: No need for gateways to track proposal state
-4. **Correlation is sufficient**: The `correlation_id` field already provides the linkage needed for audit trails
-5. **Capability model stays clean**: No need for additional `mcp/fulfill:*` capability patterns
-
-## Implementation Notes
-
-When implementing fulfillment:
-1. Copy the proposed operation's method and params
-2. Create a new `mcp/request:METHOD` message
-3. Set `correlation_id` to the proposal's message ID
-4. The response can include both the fulfiller and original proposer in the `to` field
-
-## Example
-
-Proposal:
-```json
-{
- "id": "prop-123",
- "kind": "mcp/proposal:tools/call",
- "from": "untrusted-agent",
- "payload": {
- "method": "tools/call",
- "params": { "name": "write_file", "arguments": {...} }
- }
-}
-```
-
-Fulfillment:
-```json
-{
- "id": "fulfill-456",
- "kind": "mcp/request:tools/call",
- "correlation_id": "prop-123",
- "from": "human",
- "to": ["target-agent"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 789,
- "method": "tools/call",
- "params": { "name": "write_file", "arguments": {...} }
- }
-}
-```
-
-The correlation_id clearly indicates this request fulfills the proposal, without needing a separate message kind.
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.1/decisions/002-orchestrator-standardization.md b/spec/archive/protocol/v0.1/decisions/002-orchestrator-standardization.md
deleted file mode 100644
index c2bf6482..00000000
--- a/spec/archive/protocol/v0.1/decisions/002-orchestrator-standardization.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# Decision: Orchestrator Pattern Standardization
-
-**Date**: 2025-08-27
-**Status**: Open for Discussion
-**Proposed Outcome**: Create guidance document, not protocol requirement
-
-## Context
-
-Orchestrator agents are critical to the MCPx multi-agent collaboration model. They review proposals, make fulfillment decisions, and learn policies over time. The question is whether and how to standardize orchestrator behavior, interfaces, and patterns.
-
-## Options Considered
-
-### Option 1: Protocol-Level Orchestrator Specification
-Define MCPx protocol extensions specifically for orchestrators.
-
-**Pros:**
-- Guaranteed interoperability between orchestrators
-- Standard tool names ensure consistent interfaces
-- Clear compliance requirements
-- Easier tooling and client development
-
-**Cons:**
-- Increases protocol complexity
-- Constrains innovation in orchestrator design
-- May not fit all use cases
-- Premature standardization before patterns emerge
-
-**Example additions:**
-```json
-{
- "method": "orchestrator/teach",
- "params": {
- "rule": "always approve TODO.md updates from agent-x"
- }
-}
-```
-
-### Option 2: MCP Server Capability Declaration
-Orchestrators declare capabilities through standard MCP mechanisms.
-
-**Pros:**
-- Uses existing MCP patterns
-- Discoverable through standard tools/list
-- No protocol changes needed
-- Flexible implementation
-
-**Cons:**
-- No guarantee of interface consistency
-- Each orchestrator may use different tool names
-- Harder for clients to work with multiple orchestrators
-- No standard rule format
-
-**Example:**
-```json
-{
- "tools": [
- {
- "name": "add_policy",
- "description": "Add an automation policy"
- },
- {
- "name": "list_policies",
- "description": "Show current policies"
- }
- ]
-}
-```
-
-### Option 3: Best Practices Guide (RECOMMENDED)
-Create non-normative guidance without protocol requirements.
-
-**Pros:**
-- Maintains protocol simplicity
-- Allows experimentation and innovation
-- Community can evolve best patterns
-- Can become standard later if patterns converge
-- Easy to update as we learn
-
-**Cons:**
-- No guaranteed interoperability
-- May lead to fragmentation
-- Requires more work from implementers
-- Discovery is harder
-
-**Proposed guide contents:**
-- Recommended tool naming conventions
-- Common rule format suggestions
-- Audit logging best practices
-- Learning algorithm considerations
-- Security guidelines
-
-### Option 4: Orchestrator Profile Specification
-Create a separate spec that orchestrators can claim compliance with.
-
-**Pros:**
-- Optional standardization
-- Multiple profiles for different use cases
-- Clear compliance markers
-- Maintains protocol simplicity
-
-**Cons:**
-- Additional specification to maintain
-- May still fragment into multiple profiles
-- Compliance verification complexity
-- May discourage innovation
-
-**Example:**
-```json
-{
- "_meta": {
- "orchestrator_profile": "mcpx-orchestrator/v1"
- }
-}
-```
-
-## Proposed Decision
-
-**Option 3: Best Practices Guide** - Create a non-normative orchestrator implementation guide that provides recommendations without protocol requirements.
-
-## Rationale
-
-1. **Protocol Minimalism**: MCPx should remain a minimal protocol focused on secure multi-agent communication
-2. **Innovation Space**: Orchestrator patterns are still evolving; premature standardization would limit innovation
-3. **Market Discovery**: Let the community discover optimal patterns through implementation
-4. **Progressive Formalization**: Can standardize later once patterns stabilize
-5. **Low Barrier**: Doesn't increase complexity for basic implementations
-
-## Proposed Guide Structure
-
-### `orchestrator-patterns.md` should include:
-
-1. **Core Concepts**
- - Role of orchestrators in MCPx
- - Proposal review patterns
- - Policy learning approaches
-
-2. **Recommended Interfaces**
- ```
- Suggested tool names:
- - orchestrator.add_rule
- - orchestrator.remove_rule
- - orchestrator.list_rules
- - orchestrator.get_statistics
- - orchestrator.review_proposal (for manual review requests)
- ```
-
-3. **Rule Format Suggestions**
- ```json
- {
- "pattern": "mcp/proposal:tools/call",
- "conditions": {
- "from": "agent-x",
- "tool_name": "write_file",
- "path_pattern": "*/TODO.md"
- },
- "action": "auto_approve",
- "expires": "2025-12-31"
- }
- ```
-
-4. **Security Considerations**
- - Preventing rule injection attacks
- - Capability verification
- - Audit trail requirements
-
-5. **Learning Patterns**
- - Human teaching interfaces
- - Statistical learning from decisions
- - Consensus mechanisms for multiple supervisors
-
-## Implementation Path
-
-1. **Phase 1**: Create initial best practices guide
-2. **Phase 2**: Gather feedback from early implementers
-3. **Phase 3**: Refine based on real-world usage
-4. **Phase 4**: Consider standardization if patterns converge
-
-## Open Questions
-
-1. Should we provide a reference orchestrator implementation?
-2. How should orchestrators indicate which patterns they follow?
-3. Should there be a registry of orchestrator implementations?
-4. How do we handle orchestrator composition (orchestrators managing other orchestrators)?
-
-## Related Decisions
-
-- Fulfill Message Kind (Decision 001) - Affects how orchestrators execute proposals
-- Capability Model - Orchestrators need appropriate capabilities to fulfill proposals
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.1/decisions/002-response-context.md b/spec/archive/protocol/v0.1/decisions/002-response-context.md
deleted file mode 100644
index 86fa49ee..00000000
--- a/spec/archive/protocol/v0.1/decisions/002-response-context.md
+++ /dev/null
@@ -1,241 +0,0 @@
-# Decision 002: Including Request Context in Response Envelopes
-
-## Status
-Proposed
-
-## Context
-
-In the current v0.1 spec, response envelopes use `kind: "mcp/response:METHOD"` (e.g., `mcp/response:tools/call`), but this doesn't include enough context to interpret the response payload without the original request (which a client is not guaranteed to have because of history limits).
-
-### Problem
-
-When a response envelope is viewed in isolation (e.g., in logs, history replay, or debugging):
-- We know it's a response to `tools/call`
-- We don't know WHICH tool was called
-- We can't properly parse the `result` structure without knowing the tool
-- Different tools return different result structures (text, base64, structured data, etc.)
-
-This is especially problematic in MCPx because:
-1. **Late-joining participants** receive limited history and may never see the original request
-2. **Broadcast nature** means many observers see responses without making the request
-3. **History limits** mean the correlated request may have been dropped from the buffer
-4. **Multi-agent scenarios** have many concurrent operations making correlation harder
-5. **Audit logs** need to be self-contained for compliance and debugging
-
-Example ambiguous response:
-```json
-{
- "kind": "mcp/response:tools/call",
- "correlation_id": "env-call-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }]
- }
- }
-}
-```
-
-Without the original request, we don't know if this is from `read_file`, `execute_command`, `query_database`, etc.
-
-## Options Considered
-
-### Option 1: Include Full Method Path in Kind
-Extend the kind to include the full method path:
-```json
-{
- "kind": "mcp/response:tools/call:read_file",
- "payload": { ... }
-}
-```
-
-**Pros:**
-- Complete context in the envelope metadata
-- Easy to route and filter by specific tool
-- No payload changes needed
-
-**Cons:**
-- Non-standard extension to MCP method names
-- Breaks the clean METHOD mapping
-- Requires parsing kind string to extract tool name
-
-### Option 2: Add Request Context to Response Payload (RECOMMENDED)
-Include the original method and params in the response payload:
-```json
-{
- "kind": "mcp/response:tools/call",
- "correlation_id": "env-call-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "read_file",
- "arguments": { "path": "/tmp/test.txt" }
- },
- "result": {
- "content": [{
- "type": "text",
- "text": "File contents here"
- }]
- }
- }
-}
-```
-
-**Pros:**
-- Follows JSON-RPC patterns (some implementations include method in responses)
-- Self-contained responses with full context
-- Maintains clean kind format
-- Useful for debugging and audit logs
-- Supports history replay without correlation lookup
-
-**Cons:**
-- Increases message size (duplicates request info)
-- Deviates from standard MCP response format
-- Redundant when correlation_id is available
-
-### Option 3: Status Quo with Documentation
-Keep current format but document the limitation:
-```json
-{
- "kind": "mcp/response:tools/call",
- "correlation_id": "env-call-1", // REQUIRED for context
- "payload": { ... standard MCP response ... }
-}
-```
-
-**Pros:**
-- No protocol changes needed
-- Maintains pure MCP compatibility
-- Smaller message size
-
-**Cons:**
-- Responses not self-contained
-- Requires correlation lookup for context
-- Poor debugging/observability experience
-- History replay requires full message chain
-
-## Recommendation
-
-**Adopt Option 1**: Include full method path in kind.
-
-### Proposed Implementation
-
-1. **Extend the kind format** to include the full operation context:
-
-For tool calls:
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "env-resp-1",
- "from": "target-agent",
- "to": ["requester"],
- "kind": "mcp/response:tools/call:read_file", // Extended with tool name
- "correlation_id": "env-call-1",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": { // Pure MCP response, unchanged
- "content": [{
- "type": "text",
- "text": "File contents here"
- }]
- }
- }
-}
-```
-
-For resource operations:
-```json
-{
- "kind": "mcp/response:resources/read:config.json", // Extended with resource URI
- "payload": { /* standard MCP response */ }
-}
-```
-
-For prompt operations:
-```json
-{
- "kind": "mcp/response:prompts/get:debug_prompt", // Extended with prompt name
- "payload": { /* standard MCP response */ }
-}
-```
-
-2. **Format specification**:
- - Tool operations: `mcp/[request|response|proposal]:tools/[call|list][:tool_name]`
- - Resource operations: `mcp/[request|response|proposal]:resources/[read|list|subscribe][:resource_uri]`
- - Prompt operations: `mcp/[request|response|proposal]:prompts/[get|list][:prompt_name]`
- - Completion operations: `mcp/[request|response|proposal]:completion/complete[:ref]`
-
-3. **Capability implications**:
- Capabilities can now be more granular:
- ```json
- {
- "capabilities": [
- "mcp/request:tools/call:read_file", // Can call read_file tool
- "mcp/request:tools/call:write_*", // Can call any write tool
- "mcp/proposal:tools/call:delete_file", // Can only propose delete_file
- "mcp/response:*" // Can send any response
- ]
- }
- ```
-
-### Backward Compatibility
-
-- Old format (`mcp/response:tools/call`) remains valid
-- Extended format (`mcp/response:tools/call:read_file`) is RECOMMENDED for new implementations
-- Capability matching supports wildcards for compatibility
-- MCP payloads remain completely unchanged
-
-### Implementation Guidelines
-
-1. **When sending requests/responses**:
- - Include the specific tool/resource/prompt name in the kind
- - Use the extended format for better observability
- - Maintain correlation_id for request/response linking
-
-2. **When matching capabilities**:
- - `mcp/request:tools/call:*` matches all tool calls
- - `mcp/request:tools/call:read_*` matches tools starting with "read_"
- - `mcp/request:tools/call` matches any tool call (backward compatible)
-
-3. **Gateway behavior**:
- - Gateway remains simple - just matches kind against capabilities
- - No need to parse MCP payloads
- - No state tracking required
-
-## Consequences
-
-### Positive
-- **Clean separation**: MCPx remains a pure wrapper, MCP payloads untouched
-- **Self-contained messages**: Response kind tells you everything about the operation
-- **Fine-grained capabilities**: Can control access to specific tools/resources
-- **Better observability**: Can filter/route based on specific operations
-- **Simpler clients**: Parse MCPx envelope OR MCP payload, never both for same info
-- **Gateway simplicity**: No payload inspection needed
-
-### Negative
-- Kind strings become longer with full context
-- Requires parsing kind string to extract operation details
-- Need to standardize delimiter (`:`) usage
-
-## Migration Path
-
-1. **Phase 1**: Update spec to support extended kind format
-2. **Phase 2**: Update agents to generate extended kinds
-3. **Phase 3**: Update capability matching to leverage extended format
-4. **Phase 4**: Deprecate short format in v0.2
-
-## Decision Rationale
-
-Option 1 is superior because:
-1. **Maintains MCPx as pure wrapper**: No modifications to MCP payloads
-2. **Enables capability granularity**: Can control access to specific tools
-3. **Simpler mental model**: Kind describes the operation completely
-4. **Better separation of concerns**: MCPx handles routing, MCP handles content
-5. **Cleaner implementation**: Clients parse envelope XOR payload, not both
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.1/orchestrator-patterns.md b/spec/archive/protocol/v0.1/orchestrator-patterns.md
deleted file mode 100644
index 290f7f8c..00000000
--- a/spec/archive/protocol/v0.1/orchestrator-patterns.md
+++ /dev/null
@@ -1,357 +0,0 @@
-# MCPx Orchestrator Patterns Guide
-
-**Version**: 0.1
-**Status**: Draft
-**Date**: 2025-08-27
-
-## Overview
-
-This guide provides recommended patterns for implementing orchestrator agents in MCPx. Orchestrators are trusted agents that review proposals from restricted participants and decide whether to fulfill them, either automatically based on learned policies or with human approval.
-
-This is a **non-normative guide** - orchestrators are free to implement different patterns. However, following these recommendations will improve interoperability and user experience.
-
-## Core Concepts
-
-### Role of Orchestrators
-
-Orchestrators act as intelligent gatekeepers that:
-1. **Review** proposals from restricted agents
-2. **Decide** whether to approve, reject, or escalate
-3. **Execute** approved operations on behalf of proposers
-4. **Learn** from human feedback to improve decisions
-5. **Audit** all decisions for accountability
-
-### Orchestrator Capabilities
-
-Orchestrators typically need:
-- `mcp/request:*` - To execute operations
-- `mcp/response:*` - To respond to requests
-- `chat` - To communicate with humans and agents
-- Additional capabilities based on what they orchestrate
-
-## Recommended Tool Interface
-
-### Core Tools
-
-Orchestrators SHOULD expose these MCP tools for management:
-
-#### `orchestrator.add_rule`
-Add an automation rule or policy.
-
-```json
-{
- "name": "orchestrator.add_rule",
- "description": "Add an automation rule for proposal handling",
- "inputSchema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "description": "Human-readable rule name"
- },
- "pattern": {
- "type": "object",
- "description": "Pattern to match proposals against"
- },
- "action": {
- "type": "string",
- "enum": ["auto_approve", "auto_reject", "require_human"],
- "description": "Action to take when pattern matches"
- },
- "reason": {
- "type": "string",
- "description": "Explanation for this rule"
- },
- "expires": {
- "type": "string",
- "format": "date-time",
- "description": "Optional expiration time"
- }
- },
- "required": ["name", "pattern", "action"]
- }
-}
-```
-
-#### `orchestrator.list_rules`
-List current automation rules.
-
-```json
-{
- "name": "orchestrator.list_rules",
- "description": "List all active automation rules",
- "inputSchema": {
- "type": "object",
- "properties": {
- "filter": {
- "type": "string",
- "description": "Optional filter pattern"
- }
- }
- }
-}
-```
-
-#### `orchestrator.remove_rule`
-Remove an automation rule.
-
-```json
-{
- "name": "orchestrator.remove_rule",
- "description": "Remove an automation rule",
- "inputSchema": {
- "type": "object",
- "properties": {
- "rule_id": {
- "type": "string",
- "description": "ID of rule to remove"
- }
- },
- "required": ["rule_id"]
- }
-}
-```
-
-#### `orchestrator.get_stats`
-Get statistics about proposal handling.
-
-```json
-{
- "name": "orchestrator.get_stats",
- "description": "Get orchestrator statistics",
- "inputSchema": {
- "type": "object",
- "properties": {
- "since": {
- "type": "string",
- "format": "date-time",
- "description": "Start time for statistics"
- }
- }
- }
-}
-```
-
-### Optional Tools
-
-#### `orchestrator.review_proposal`
-Request manual review of a specific proposal.
-
-#### `orchestrator.set_default_action`
-Set default action for unmatched proposals.
-
-#### `orchestrator.export_rules`
-Export rules for backup or sharing.
-
-#### `orchestrator.import_rules`
-Import rules from backup or another orchestrator.
-
-## Rule Format Recommendations
-
-### Basic Rule Structure
-
-```json
-{
- "id": "rule-uuid",
- "name": "Allow TODO updates",
- "pattern": {
- "from": "openai-agent",
- "kind": "mcp/proposal:tools/call",
- "method": "write_file",
- "path_regex": ".*/TODO\\.md$"
- },
- "action": "auto_approve",
- "reason": "TODO updates are low risk",
- "created_by": "human",
- "created_at": "2025-08-27T10:00:00Z",
- "expires_at": "2025-12-31T23:59:59Z",
- "stats": {
- "matched": 42,
- "approved": 42,
- "rejected": 0
- }
-}
-```
-
-### Pattern Matching
-
-Patterns should support:
-- **Exact match**: `"from": "agent-123"`
-- **Wildcard**: `"from": "agent-*"`
-- **Regex**: `"path_regex": ".*/TODO\\.md$"`
-- **Nested paths**: `"params.tool_name": "write_file"`
-- **Arrays**: `"from": ["agent-1", "agent-2"]`
-
-### Action Types
-
-- `auto_approve`: Automatically fulfill the proposal
-- `auto_reject`: Automatically reject with reason
-- `require_human`: Escalate to human for decision
-- `delegate`: Forward to another orchestrator
-- `conditional`: Apply additional checks
-
-## Decision Flow
-
-### Standard Decision Process
-
-```
-Receive Proposal
- ↓
-Match Against Rules (priority order)
- ↓
-Found Match? → Execute Rule Action
- ↓ No
-Apply Default Action
-```
-
-### Implementation Pseudocode
-
-```python
-def handle_proposal(proposal):
- # Check rules in priority order
- for rule in sorted_rules:
- if matches_pattern(proposal, rule.pattern):
- log_match(rule, proposal)
- return execute_action(rule.action, proposal)
-
- # No rule matched - use default
- return execute_action(default_action, proposal)
-
-def execute_action(action, proposal):
- if action == "auto_approve":
- return fulfill_proposal(proposal)
- elif action == "auto_reject":
- return reject_proposal(proposal, "Blocked by policy")
- elif action == "require_human":
- return escalate_to_human(proposal)
-```
-
-## Learning Patterns
-
-### Human Teaching
-
-Orchestrators should learn from human decisions:
-
-1. **Explicit Teaching**: Human adds rule via tool
-2. **Implicit Learning**: Track human decisions on proposals
-3. **Feedback Loop**: Adjust rules based on corrections
-4. **Batch Learning**: Analyze patterns across many decisions
-
-### Example Teaching Interactions
-
-```
-Human: @orchestrator always approve file reads from research-agent
-Orchestrator: Added rule: auto-approve read operations from research-agent
-
-Human: @orchestrator reject write operations to /etc
-Orchestrator: Added rule: auto-reject write operations to /etc
-```
-
-## Security Considerations
-
-### Input Validation
-
-- Validate all proposal patterns to prevent injection
-- Sanitize rule names and descriptions
-- Verify capability requirements before fulfillment
-- Rate limit rule additions to prevent spam
-
-### Audit Requirements
-
-- Log all proposals received
-- Log all decisions made (approve/reject/escalate)
-- Log all rule changes
-- Maintain decision history for analysis
-- Track which rules matched which proposals
-
-### Failure Handling
-
-- Clear error messages for rejected proposals
-- Timeout handling for human escalations
-- Graceful degradation when rules database unavailable
-- Recovery mechanisms for partial fulfillments
-
-## Multi-Orchestrator Patterns
-
-### Hierarchical Orchestration
-
-Orchestrators can delegate to other orchestrators:
-
-```
-General Orchestrator
- ↓
-Domain-Specific Orchestrators
- ↓
-Worker Agents
-```
-
-### Consensus Orchestration
-
-Multiple orchestrators vote on proposals:
-
-```
-Proposal → [O1, O2, O3] → Majority Decision → Execute
-```
-
-### Specialized Orchestration
-
-Different orchestrators for different domains:
-
-- **Security Orchestrator**: Reviews security-sensitive operations
-- **Compliance Orchestrator**: Ensures regulatory compliance
-- **Performance Orchestrator**: Manages resource-intensive operations
-
-## Implementation Checklist
-
-When implementing an orchestrator:
-
-- [ ] Implement core tools (add_rule, list_rules, etc.)
-- [ ] Define rule storage mechanism
-- [ ] Implement pattern matching engine
-- [ ] Add audit logging
-- [ ] Create fulfillment mechanism
-- [ ] Add human escalation interface
-- [ ] Implement timeout handling
-- [ ] Add statistics collection
-- [ ] Create backup/restore functionality
-- [ ] Document rule format
-- [ ] Provide example rules
-- [ ] Test with various proposal patterns
-
-## Example Orchestrator Responses
-
-### Approval
-```json
-{
- "decision": "approved",
- "rule_matched": "rule-123",
- "execution_id": "exec-456",
- "timestamp": "2025-08-27T10:30:00Z"
-}
-```
-
-### Rejection
-```json
-{
- "decision": "rejected",
- "rule_matched": "rule-789",
- "reason": "Operation blocked by security policy",
- "timestamp": "2025-08-27T10:31:00Z"
-}
-```
-
-### Escalation
-```json
-{
- "decision": "escalated",
- "reason": "Requires human approval",
- "escalation_id": "esc-012",
- "timeout": "2025-08-27T10:35:00Z"
-}
-```
-
-## References
-
-- MCPx Protocol Specification v0.1
-- Decision 001: Fulfill Message Kind
-- Decision 002: Orchestrator Standardization
diff --git a/spec/archive/protocol/v0.2/README.md b/spec/archive/protocol/v0.2/README.md
deleted file mode 100644
index 85ad76ff..00000000
--- a/spec/archive/protocol/v0.2/README.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# MEUP Protocol v0.2
-
-**Status:** Experimental
-**Released:** 2025-01-03
-**Protocol Version:** meup/v0.2
-
-## Overview
-
-This is the v0.2 release of the MEUP (Multi-Entity Unified Protocol) specification. This version represents the first complete specification with all foundational ADRs incorporated.
-
-## Key Documents
-
-- **[SPEC.md](./SPEC.md)** - Complete protocol specification
-- **[decisions/](./decisions/)** - Architecture Decision Records
- - **[accepted/](./decisions/accepted/)** - Incorporated design decisions
- - **[rejected/](./decisions/rejected/)** - Decisions not adopted
- - **[proposed/](./decisions/proposed/)** - (Currently empty)
-
-## Major Features
-
-- Broadcast messaging within spaces
-- Capability-based security with JSON pattern matching
-- Proposal/fulfillment pattern for untrusted agents
-- Space management operations (invite, kick, grant, revoke)
-- Reasoning transparency with context support
-- Array-based correlation IDs for workflow support
-- Slash notation for message kinds
-
-## Implementation Checklist
-
-See Section 8 of SPEC.md for detailed implementation requirements:
-- Section 8.1: Gateway requirements
-- Section 8.2: Participant requirements
-
-## Breaking Changes from Previous Versions
-
-This version is NOT backward compatible with v0.0 or v0.1. Key changes:
-- Protocol identifier: `meup/v0.2`
-- Slash notation for kinds (e.g., `mcp/request`)
-- Array correlation IDs
-- JSON pattern capabilities
-
-## Future Compatibility
-
-As a v0.x release, breaking changes may occur in future minor versions. Production systems should pin to specific versions until v1.0 provides stability guarantees.
-
-## Contributing
-
-Please submit feedback and contributions to: https://github.com/rjcorwin/mcpx-protocol
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/SPEC.md b/spec/archive/protocol/v0.2/SPEC.md
deleted file mode 100644
index a91e2ed0..00000000
--- a/spec/archive/protocol/v0.2/SPEC.md
+++ /dev/null
@@ -1,1061 +0,0 @@
-# Multi-Entity Unified-context Protocol (MEUP) Specification v0.2
-
-Status: Experimental
-Date: 2025-09-03
-Version: v0.2
-Editors: RJ Corwin (https://github.com/rjcorwin)
-
----
-
-## Requirements Language
-
-The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
-
----
-
-## 1. Abstract
-
-MEUP (Multi-Entity Unified-context Protocol) provides a unified context where all agent-to-agent and agent-to-tool interactions are visible and controllable at the protocol layer. Unlike traditional systems where AI coordination happens in hidden contexts, MEUP broadcasts all messages within a shared space, enabling participants to observe everything and privileged users to approve or reject actions through a proposal-review pattern. The protocol extends MCP semantics while adding capability-based access control, allowing untrusted agents to propose operations that trusted participants execute. This transparency enables progressive automation, where systems learn from human decisions to safely expand their autonomous capabilities over time.
-
----
-
-## 2. Goals and Non-Goals
-
-### 2.1 Goals
-- **Unified Context**: All participants share the same visible stream of interactions
-- **Protocol-Level Control**: Control actions through capabilities and proposals, not application wrappers
-- **Progressive Automation**: Learn from human decisions to safely expand autonomous operations
-- **Tool Compatibility**: Preserve existing MCP tool and resource interfaces
-
-### 2.2 Non-Goals
-- End-to-end encryption or private channels (all messages visible within space)
-- Message persistence or replay (spaces are ephemeral)
-- Cross-space routing or participant discovery
-- Guaranteed delivery or ordering (WebSocket best-effort)
-- Application-specific semantics beyond MCP operations
-- Configuration management (implementation-specific)
-
----
-
-## 3. Message Envelope
-
-All data flowing over a space MUST be a single top-level JSON envelope:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "2f6b6e70-7b36-4b8b-9ad8-7c4f7d0e2d0b",
- "ts": "2025-08-26T14:00:00Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp/request",
- "correlation_id": ["env-1"],
- "context": "workflow-123/step-1",
- "payload": { /* kind-specific body */ }
-}
-```
-
-Field semantics:
-- `protocol`: MUST be `"meup/v0.2"` for this version
-- `id`: globally unique message id (e.g., UUIDv4)
-- `ts`: RFC3339 timestamp
-- `from`: stable participant id within the space
-- `to`: array of participant ids (empty/omitted = broadcast)
-- `kind`: Message type using minimal kinds:
- - `mcp/request` - MCP request/notification
- - `mcp/response` - MCP response
- - `mcp/proposal` - MCP proposal for operations
- - `mcp/withdraw` - Withdraw a proposal
- - `mcp/reject` - Reject a proposal
- - `reasoning/start` - Begin reasoning sequence
- - `reasoning/thought` - Reasoning monologue (thinking out loud)
- - `reasoning/conclusion` - End reasoning sequence
- - `capability/grant` - Grant capabilities to participant
- - `capability/revoke` - Revoke capabilities from participant
- - `capability/grant-ack` - Acknowledge capability grant
- - `space/invite` - Invite participant to space
- - `space/kick` - Remove participant from space
- - `chat` - Chat messages
- - `system/presence` - Join/leave events
- - `system/welcome` - Welcome message for new participants
- - `system/error` - System error messages
-- `correlation_id`: array of message IDs this message relates to (always an array, even for single values)
- - Response → Request: `mcp/response` MUST reference the originating `mcp/request`
- - Fulfillment → Proposal: `mcp/request` MAY reference a `mcp/proposal` when fulfilling it
- - Withdraw → Proposal: `mcp/withdraw` MUST reference the proposal being withdrawn
- - Reject → Proposal: `mcp/reject` MUST reference the proposal being rejected
- - Error → Trigger: `system/error` messages SHOULD reference the envelope that caused the error
- - Reply → Message: Any envelope MAY reference others to indicate explicit reply intent (use `context` field for threading)
- - Workflow → Multiple: Messages in complex workflows MAY reference multiple related messages (e.g., a summary referencing several analyses, a decision based on multiple proposals, a response addressing multiple questions)
- - Fork/Join → Multiple: A response that combines results from multiple parallel requests
- - The array structure supports complex multi-party coordination and DAG-like message flows
-- `context`: (optional) string representing the context or sub-context for this message
- - Path-based hierarchy using forward slashes: `"parent/child/grandchild"`
- - Messages in sub-contexts (reasoning, workflows) include this field for organization
- - Context groups related messages together (e.g., all thoughts in a reasoning sequence)
- - When prompting LLMs, implementations MAY filter contexts to reduce noise
- - IMPORTANT: Messages addressed to a participant (via `to` field) MUST be handled regardless of context
-- `payload`: object; structure depends on `kind`
-
-### 3.1 MCP Messages
-
-MCP messages use minimal kinds with method information in the payload:
-- `kind: "mcp/request"` for requests/notifications
-- `kind: "mcp/response"` for responses
-- `kind: "mcp/proposal"` for proposals
-- `kind: "mcp/withdraw"` for withdrawing proposals
-- `kind: "mcp/reject"` for rejecting proposals
-- The specific method (e.g., `tools/call`, `resources/read`) is in `payload.method`
-
-#### 3.1.1 MCP Requests
-
-Example tool call request:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-call-1",
- "from": "trusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-#### 3.1.2 MCP Responses
-
-Responses MUST include the `correlation_id` field referencing the original request's `id`. This is critical for translating MCP's client-server request/response model to MEUP's multi-participant broadcast paradigm, allowing all participants to match responses to their corresponding requests.
-
-Response to the above tool call:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-resp-1",
- "from": "target-agent",
- "to": ["trusted-agent"],
- "kind": "mcp/response",
- "correlation_id": ["env-call-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }]
- }
- }
-}
-```
-
-Note: The MCP payload structure remains unchanged from standard MCP.
-
-### 3.2 MCP Proposals
-
-Participants with restricted capabilities MUST use proposals instead of direct MCP operations. Proposals have the same payload structure as requests:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-req-1",
- "from": "untrusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/proposal",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-This is a MEUP-specific protocol extension that proposes an MCP operation requiring fulfillment by a participant with appropriate capabilities.
-
-#### 3.2.1 Proposal Fulfillment
-
-A participant with appropriate capabilities fulfills the proposal by making the real MCP call. The `correlation_id` field is critical for matching approvals to their original proposals:
-- Proposals typically don't include `correlation_id` (they originate new workflows)
-- Fulfillment messages MUST include `correlation_id` referencing the proposal's `id`
-- This allows participants to track which fulfillment corresponds to which proposal
-- The correlation chain enables audit trails and multi-step approval workflows
-
-Example fulfillment:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-fulfill-1",
- "from": "human-user",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "correlation_id": ["env-req-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-The response goes only to the fulfiller who made the request. The response's `correlation_id` references the fulfillment message (`env-fulfill-1`), maintaining the standard request/response pairing. The original proposer can observe the outcome since messages are broadcast by default:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-fulfill-resp-1",
- "from": "target-agent",
- "to": ["human-user"],
- "kind": "mcp/response",
- "correlation_id": ["env-fulfill-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed successfully"
- }]
- }
- }
-}
-```
-
-The proposer can follow the correlation chain to track the outcome:
-1. Proposer sends proposal (`env-req-1`)
-2. Fulfiller sends request with `correlation_id: ["env-req-1"]` (`env-fulfill-1`)
-3. Target sends response with `correlation_id: ["env-fulfill-1"]` (`env-fulfill-resp-1`)
-4. Proposer observes the broadcast response and can trace back through the correlation chain
-
-### 3.3 Proposal Lifecycle Operations
-
-MEUP extends the proposal pattern with lifecycle operations for cancellation and feedback.
-
-#### 3.3.1 Withdraw Proposals (kind = "mcp/withdraw")
-
-Proposers can withdraw their own proposals that are no longer needed:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "withdraw-456",
- "from": "untrusted-agent",
- "correlation_id": ["env-req-1"],
- "kind": "mcp/withdraw",
- "payload": {
- "reason": "no_longer_needed"
- }
-}
-```
-
-- Only the original proposer can withdraw their proposals
-- `correlation_id` MUST reference the proposal being withdrawn
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.2 Reject Proposals (kind = "mcp/reject")
-
-Any participant with the capability can reject proposals. Rejections provide early feedback to avoid unnecessary waiting:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "reject-789",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["env-req-1"],
- "kind": "mcp/reject",
- "payload": {
- "reason": "unsafe"
- }
-}
-```
-
-**Purpose and Behavior:**
-- Prevents proposers from waiting unnecessarily for fulfillment that won't come
-- Particularly important when explicitly targeted in a proposal's `to` field
-- Proposers MAY give up after the first rejection (fail-fast approach)
-- Proposers MAY continue waiting for other participants to fulfill (resilient approach)
-- The choice depends on the proposer's implementation and use case
-- Multiple participants may reject the same proposal for different reasons
-
-**Requirements:**
-- `correlation_id` MUST reference the proposal being rejected
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.3 Standardized Reason Codes
-
-Lifecycle operations use standardized reason codes:
-
-- `"disagree"` - Don't agree with the proposed action
-- `"inappropriate"` - Not suitable for the current context
-- `"unsafe"` - Could cause harm or unintended consequences
-- `"busy"` - Currently handling other work
-- `"incapable"` - Don't have the required tools/access
-- `"policy"` - Violates security or operational policy
-- `"duplicate"` - Already being handled by another participant
-- `"invalid"` - Proposal is malformed or impossible
-- `"timeout"` - Too old or expired
-- `"resource_limit"` - Would exceed resource constraints
-- `"no_longer_needed"` - Proposer no longer needs the operation
-- `"other"` - Reason not covered above
-
-Detailed explanations can be provided via follow-up chat messages using `correlation_id`:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "chat-790",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["reject-789"],
- "kind": "chat",
- "payload": {
- "text": "I'm currently processing a large batch operation that requires exclusive file access. Please retry in about 5 minutes.",
- "format": "plain"
- }
-}
-```
-
-**Important timing consideration:** The reject message with a reason code should be sent immediately for fast feedback. Detailed explanations may arrive later as generating them (especially with LLMs) can take time. Participants implementing proposers should:
-- Process the reject immediately upon receipt
-- Optionally wait for follow-up explanations if they need details
-- Not block on explanations that may never come
-
-### 3.4 Chat Messages (kind = "chat")
-
-Chat messages are MEUP-specific and do not pollute the MCP namespace:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-chat-1",
- "from": "user-alice",
- "kind": "chat",
- "payload": {
- "text": "Hello everyone!",
- "format": "plain"
- }
-}
-```
-
-- `text` (required): The message content
-- `format` (optional): "plain" or "markdown", defaults to "plain"
-- Chat messages are typically broadcast (empty/omitted `to` array)
-
-### 3.5 Reasoning Transparency
-
-MEUP supports transparent reasoning through dedicated message kinds and the context field. This allows agents to share their thinking process while maintaining clear boundaries between reasoning sequences and regular operations.
-
-#### 3.5.1 Reasoning Pattern
-
-Common patterns for transparent reasoning:
-
-**Response Pattern:**
-1. Agent receives a request (e.g., `mcp/request`)
-2. Agent sends `reasoning/start` with `correlation_id` referencing the request
-3. The `reasoning/start` message ID becomes the `context` for subsequent messages
-4. Agent MAY send `reasoning/thought` messages for internal monologue (optional)
-5. Agent MAY use `chat` messages within context for dialogue with other participants
-6. Agent MAY send `reasoning/conclusion` to summarize findings (optional)
-7. Agent sends final response with `correlation_id` to original request
-
-**Autonomous Pattern:**
-- Agent sends `reasoning/start` at any time (e.g., periodic analysis, monitoring)
-- The `reasoning/start` creates a context for transparent thinking
-- Agent shares thoughts as they occur
-- No response required - purely for transparency
-
-Note: `reasoning/start` creates a context for transparency. Whether responding to requests or reasoning autonomously, it lets other participants observe the agent's thinking process.
-
-#### 3.5.2 Reasoning Start (kind = "reasoning/start")
-
-Signals the beginning of a reasoning sequence:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "reason-start-1",
- "from": "agent-1",
- "kind": "reasoning/start",
- "correlation_id": ["req-123"],
- "payload": {
- "message": "Analyzing the request to modify the configuration file..."
- }
-}
-```
-
-#### 3.5.3 Reasoning Thought (kind = "reasoning/thought")
-
-Shares internal reasoning steps (monologue, no reply expected):
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "thought-1",
- "from": "agent-1",
- "kind": "reasoning/thought",
- "context": "reason-start-1",
- "payload": {
- "message": "The configuration file appears to use YAML format. I should validate the syntax before making changes."
- }
-}
-```
-
-#### 3.5.4 Reasoning Conclusion (kind = "reasoning/conclusion")
-
-Concludes the reasoning sequence:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "reason-end-1",
- "from": "agent-1",
- "kind": "reasoning/conclusion",
- "context": "reason-start-1",
- "payload": {
- "message": "Configuration update is safe to proceed. The changes are valid YAML and won't break existing settings."
- }
-}
-```
-
-#### 3.5.5 Context Behavior
-
-- Messages with a `context` field are part of a sub-context
-- Participants MAY filter out contexts when constructing prompts (e.g., excluding other agents' reasoning traces to reduce noise)
-- **Exception**: Participants MUST NOT ignore `mcp/request` or `mcp/proposal` messages, even if they have a context field
-- The context field supports hierarchical paths: `"parent/child/grandchild"`
-- Context enables parallel reasoning by multiple agents without interference
-
-### 3.6 Space Management Operations
-
-A **space** in MEUP is a communication context where participants exchange messages. It's analogous to a channel or room - a bounded environment where a specific set of participants collaborate. Each space has its own:
-- Set of participants (who can send/receive messages)
-- Capability assignments (what each participant can do)
-- Message history (the stream of envelopes exchanged)
-
-A gateway may manage multiple spaces, each isolated from the others. The gateway enforces capabilities and routing rules for all its spaces.
-
-MEUP extends the protocol with operations for managing these spaces dynamically. These operations use the `capability/*` and `space/*` namespaces to clearly indicate their purpose.
-
-#### 3.6.1 Grant Capabilities (kind = "capability/grant")
-
-Allows participants with appropriate capabilities to grant capabilities to other participants:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "grant-789",
- "from": "trusted-orchestrator",
- "to": ["untrusted-agent"],
- "kind": "capability/grant",
- "payload": {
- "recipient": "untrusted-agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_file"
- }
- }
- }
- ],
- "reason": "Demonstrated safe file handling"
- }
-}
-```
-
-- The grant message ID becomes the `grant_id` for future revocation
-- Capabilities use the same JSON pattern matching format from Section 4.1
-- Gateway SHOULD add granted capabilities to recipient's capability set
-- Multiple grants are cumulative
-
-#### 3.6.2 Revoke Capabilities (kind = "capability/revoke")
-
-Revokes previously granted capabilities:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "revoke-123",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "grant_id": "grant-789",
- "reason": "Task completed"
- }
-}
-```
-
-Alternatively, revoke by capability pattern (removes ALL matching capabilities):
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "revoke-456",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/*"
- }
- }
- ],
- "reason": "No longer needed"
- }
-}
-```
-
-#### 3.6.3 Grant Acknowledgment (kind = "capability/grant-ack")
-
-Recipients acknowledge capability grants:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "ack-001",
- "from": "agent",
- "correlation_id": ["grant-789"],
- "kind": "capability/grant-ack",
- "payload": {
- "status": "accepted"
- }
-}
-```
-
-#### 3.6.4 Invite Participant (kind = "space/invite")
-
-Invites new participants to the space:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "invite-123",
- "from": "admin",
- "kind": "space/invite",
- "payload": {
- "participant_id": "new-agent",
- "email": "agent-operator@example.com", // Optional
- "initial_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ],
- "reason": "Adding specialized analysis agent"
- }
-}
-```
-
-**Fields:**
-- `participant_id`: Identifier for the new participant
-- `email`: (optional) Email address to send invitation to
-- `initial_capabilities`: Capabilities the participant will have when they join
-- `reason`: Explanation for the invitation
-
-**Note:** This message is broadcast within the space to inform existing participants. If `email` is provided, the gateway SHOULD send an invitation email with connection details. Additional notification methods (webhook, token generation, etc.) are gateway implementation-specific.
-
-#### 3.6.5 Remove Participant (kind = "space/kick")
-
-Removes participants from the space:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "kick-456",
- "from": "admin",
- "kind": "space/kick",
- "payload": {
- "participant_id": "misbehaving-agent",
- "reason": "Repeated capability violations"
- }
-}
-```
-
-#### 3.6.6 Delegation Security
-
-- Only participants with `capability/grant` capability can grant capabilities
-- Participants cannot grant capabilities they don't possess
-- Gateway SHOULD track grant chains for audit purposes
-- Revocations take effect immediately
-- All space management operations generate audit logs
-
-### 3.7 Presence Messages (kind = "system/presence")
-
-Presence messages are broadcast to notify all participants about join/leave events:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-presence-1",
- "from": "system:gateway",
- "kind": "system/presence",
- "payload": {
- "event": "join",
- "participant": {
- "id": "new-agent",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
- }
-}
-```
-
-- `event` (required): Either `"join"` or `"leave"`
-- `participant` (required): Information about the participant
- - `id`: The participant's identifier
- - `capabilities`: The participant's capabilities (for `join` events)
-
-Note: Presence messages are broadcast to all participants. The joining participant also receives a welcome message addressed specifically to them (via the `to` field) with their authoritative capabilities and the current participant list.
-
-### 3.8 System Messages
-
-#### 3.8.1 Welcome Message (kind = "system/welcome")
-
-When a participant connects, the gateway MUST send a welcome message addressed specifically to that participant (using the `to` field):
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-welcome-1",
- "from": "system:gateway",
- "to": ["new-participant"],
- "kind": "system/welcome",
- "payload": {
- "you": {
- "id": "new-participant",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- },
- "participants": [
- {
- "id": "agent-1",
- "capabilities": [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- },
- {
- "id": "agent-2",
- "capabilities": [
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- }
- ]
- }
-}
-```
-
-- `you`: The joining participant's own information and authoritative capabilities
-- `participants`: Current list of other participants in the space and their capabilities
-
-**Important:** Other participants SHOULD ignore welcome messages not addressed to them when constructing prompts, as these can cause significant bloat. The message is already targeted via the `to` field.
-
-#### 3.8.2 Capability Violation (kind = "system/error")
-
-When a participant attempts an operation they lack capability for:
-
-```json
-{
- "protocol": "meup/v0.2",
- "id": "env-violation-1",
- "from": "system:gateway",
- "to": ["violator"],
- "kind": "system/error",
- "correlation_id": ["env-bad-call"],
- "payload": {
- "error": "capability_violation",
- "attempted_kind": "mcp/request",
- "your_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
-}
-```
-
----
-
-## 4. Security Model
-
-### 4.1 Capability-Based Access Control
-
-The gateway enforces security through two mechanisms:
-
-1. **Identity Validation**: The gateway MUST verify that the `from` field matches the authenticated participant's ID. Participants cannot spoof messages from other participants.
-
-2. **Capability Matching**: The gateway assigns capabilities to each connection using JSON pattern matching. Capabilities are JSON objects that match against the message structure (kind and payload).
-
-**Capability Pattern Structure:**
-```json
-{
- "kind": "pattern",
- "payload": {
- "field": "pattern"
- }
-}
-```
-
-**Pattern Types:**
-- String with wildcards: `"mcp/*"` matches `mcp/request`, `mcp/response`, etc.
-- Exact match: `"chat"` only matches `"chat"`
-- Nested patterns: Match specific payload fields
-
-**Reserved Namespace:**
-The `system/*` namespace is reserved exclusively for the gateway. Participants MUST NOT send messages with `kind` starting with `system/`. The gateway MUST reject any such attempts. Only the gateway can generate system messages (`system/welcome`, `system/presence`, `system/error`).
-
-**Example Capability Sets:**
-
-Gateways may implement various capability profiles using JSON patterns:
-
-1. **Full Access** example:
- ```json
- [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- ```
- Can send any MCP messages (requests, responses, proposals)
-
-2. **Proposal-Only** example:
- ```json
- [
- {"kind": "mcp/proposal"},
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Cannot send direct MCP requests, must use proposals
-
-3. **Tool-Specific** example:
- ```json
- [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_*"
- }
- }
- },
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Can only call tools matching `read_*` pattern
-
-**Progressive Trust Example:**
-
-Capabilities can be expanded as trust increases:
-1. Initial: `[{"kind": "mcp/proposal"}, {"kind": "chat"}]` - Proposals only
-2. Basic: Add read capabilities with payload patterns
-3. Trusted: Add tool usage with specific tool patterns
-4. Full: Replace with `[{"kind": "mcp/*"}]` - Unrestricted MCP access
-
-### 4.2 Gateway Enforcement
-
-The gateway enforces capabilities using JSON pattern matching against the message structure:
-
-**What the Gateway Does:**
-- Matches the message's `kind` and `payload` against participant's capability patterns
-- Uses wildcards, regex patterns, and JSONPath for flexible matching
-- Blocks messages if no capability matches
-- Returns error responses for capability violations
-
-**What the Gateway Does NOT Do:**
-- Parse or validate JSON-RPC payloads
-- Understand MCP semantics
-- Detect spoofing (where `kind` doesn't match payload content)
-
-**Pattern Matching Examples:**
-- Message with `kind: "mcp/request"` and `payload.method: "tools/call"` matches:
- - `{"kind": "mcp/*"}`
- - `{"kind": "mcp/request"}`
- - `{"kind": "mcp/request", "payload": {"method": "tools/*"}}`
-- Message with `kind: "chat"` only matches:
- - `{"kind": "chat"}`
- - `{"kind": "*"}` (wildcard for all kinds)
-
-### 4.3 Participant Validation
-
-Receiving participants SHOULD validate message structure:
-- Verify `kind` is appropriate for the message type
-- Validate payload structure matches expected schema
-- Drop or report malformed messages
-- MAY track misbehaving participants for reputation scoring
-
-**Schema Mismatch Warning:** Participants may observe messages with schemas that differ from what was advertised:
-- Other participants might advertise one tool schema but send different parameters
-- Participants joining mid-conversation may see responses to requests they never observed
-- Always parse messages defensively and validate structure before processing
-
----
-
-## 5. Realtime Gateway API
-
-### 5.1 Authentication and Capability Assignment
-
-The gateway determines capabilities during authentication. Implementation-specific policies may include:
-
-1. **Token-based**: Tokens map to specific capability sets
- - Implementations may encode capabilities in tokens or map tokens to capability profiles
-2. **Identity-based**: Map authenticated identities to capability sets
-3. **Space access control**: Spaces may be public, private, or restricted
-4. **Dynamic capabilities**: Capabilities may be modified during a session
-
-### 5.2 WebSocket Connection
-
-Connect: `GET /ws?space=` with Authorization header
-
-The gateway:
-1. Validates the bearer token (if provided)
-2. Maps the token to a participant ID (implementation-specific)
-3. Determines capabilities based on implementation policy
-4. **MUST** send welcome message with the assigned participant ID and accurate capabilities
-5. **MUST** enforce capability rules on all subsequent messages
-
-**Note:** Participants only provide their bearer token. The gateway is responsible for mapping tokens to participant IDs through its own implementation-specific mechanism.
-
-The capabilities in the welcome message constitute the authoritative list of what operations the participant can perform. Participants SHOULD use this list to understand their allowed operations.
-
-### 5.3 Message Filtering
-
-For each incoming message from a participant:
-
-```python
-if not matches_any_capability(message, participant.capabilities):
- send_error(f"Capability violation: you lack capability for this operation")
- broadcast_violation_notice() # optional
- return
-send_to_space(message)
-```
-
----
-
-## 6. Version Compatibility
-
-### 6.1 Breaking Changes
-
-This is a v0.x release. Breaking changes are expected between minor versions until v1.0:
-- v0.2 is NOT backward compatible with v0.1
-- Clients and gateways MUST use matching protocol versions
-- No compatibility guarantees until v1.0 release
-
-### 6.2 Migration from v0.0
-
-Key breaking changes from v0.0:
-- Protocol identifier changed from `mcp-x/v0` to `meup/v0.2`
-- Message kinds now use slash notation (e.g., `mcp/request` instead of `mcp/request:tools/call`)
-- Method information moved to payload
-- Capabilities use JSON pattern matching instead of string wildcards
-- `correlation_id` is now always an array
-- Chat remains as dedicated `chat` kind
-
-### 6.3 Future Compatibility
-
-- v0.x series is experimental and subject to breaking changes
-- v1.0 will establish stable protocol with compatibility guarantees
-- Production deployments should pin specific v0.x versions
-
----
-
-## 7. Security Considerations
-
-MEUP's security model relies on capability-based access control enforced by the gateway, with additional validation responsibilities distributed among participants.
-
-### 7.1 Core Security Mechanisms
-
-1. **Identity Validation**: Gateway MUST verify the `from` field matches the authenticated participant ID (Section 4.1)
-2. **Capability Enforcement**: Gateway enforces JSON pattern-based capabilities on all messages (Section 4.1, 4.2)
-3. **Reserved Namespaces**: Only the gateway can send `system/*` messages, preventing spoofing (Section 3.8)
-4. **Proposal Isolation**: Untrusted agents use `mcp/proposal` to suggest rather than execute operations (Section 3.3)
-5. **Lazy Gateway Enforcement**: Gateway validates message structure but not payload semantics (Section 4.2)
-
-### 7.2 Security Boundaries
-
-**Gateway Responsibilities:**
-- Authenticate participants and assign stable IDs
-- Enforce capability patterns on message kinds and payloads
-- Prevent identity spoofing via `from` field validation
-- Block `system/*` messages from participants
-
-**Participant Responsibilities:**
-- Validate envelope `kind` matches payload content
-- Detect and report malformed or spoofed messages
-- Parse messages defensively (schemas may differ from advertised)
-- Track misbehaving participants for reputation scoring
-
-### 7.3 Best Practices
-
-1. **Start Restricted**: New agents begin with `mcp/proposal` capability only
-2. **Progressive Trust**: Expand capabilities based on observed behavior over time
-3. **Validate Strictly**: Check that `kind` matches the payload type (e.g., `mcp/request` for MCP requests)
-4. **Monitor Proposals**: Log proposal/fulfillment patterns for audit trails
-5. **Report Violations**: Track and broadcast capability violations for transparency
-
----
-
-## 8. Implementation Checklist
-
-### 8.1 Gateway Requirements
-- [ ] **Connection Management**
- - [ ] WebSocket server at `GET /ws?space=`
- - [ ] Bearer token validation from Authorization header
- - [ ] Token-to-participant-ID mapping (implementation-specific)
- - [ ] Connection state tracking per participant
-
-- [ ] **Capability Enforcement**
- - [ ] Pattern matching engine for wildcard capabilities
- - [ ] Validate message `kind` against sender's capabilities
- - [ ] Block messages that don't match capabilities
- - [ ] Return `system/error` for capability violations
-
-- [ ] **System Messages**
- - [ ] Send `system/welcome` with participant ID and capabilities on connect
- - [ ] Broadcast `system/presence` for join/leave events
- - [ ] Generate `system/error` for protocol violations
- - [ ] Ensure only gateway can send `system/*` messages
-
-- [ ] **Message Routing**
- - [ ] Route messages based on `to` field (broadcast if empty/omitted)
- - [ ] Preserve envelope structure without modification
- - [ ] NO payload parsing or validation (lazy enforcement)
-
-### 8.2 Participant Requirements
-- [ ] **Message Validation**
- - [ ] Verify envelope structure before processing
- - [ ] Validate `kind` matches the payload type (e.g., `mcp/request` for requests with `payload.method`)
- - [ ] Validate payload structure matches expected schema for the `kind`
- - [ ] Drop messages that fail validation
- - [ ] Track/report misbehaving participants
-
-- [ ] **MCP Integration**
- - [ ] Implement MCP server capabilities
- - [ ] Handle incoming MCP requests/responses
- - [ ] Generate proper correlation IDs for responses
- - [ ] Include correlation ID in all response messages
-
-- [ ] **Proposal Handling** (if applicable)
- - [ ] Recognize `mcp.proposal` messages
- - [ ] Implement fulfillment logic for approved proposals
- - [ ] Include proposal ID as correlation_id when fulfilling
-
-- [ ] **Connection Behavior**
- - [ ] Process `system/welcome` to learn own ID and capabilities
- - [ ] Handle `system/presence` to track other participants
- - [ ] Respect capability restrictions from welcome message
-
----
-
-## 9. Examples
-
-The following examples demonstrate multi-agent orchestration patterns enabled by MEUP's capability-based security model. The core pattern is **delegated fulfillment**, where untrusted agents propose operations that are reviewed and executed by trusted participants.
-
-### 9.1 Proposal-Based Workflow Example
-
-In this example, an agent with limited capabilities uses proposals:
-
-1. Agent connects → receives proposal-only capabilities
-2. Agent attempts MCP request → gateway blocks, returns error
-3. Agent sends `mcp/proposal` → visible to all participants
-4. Another participant with appropriate capabilities fulfills it
-5. Fulfiller sends real `mcp/request` message to target
-6. Target executes and returns result to fulfiller (proposer observes via broadcast)
-
-### 9.2 Capability Expansion Example
-
-One possible administrative workflow:
-
-1. Agent operates successfully over time
-2. Administrator observes behavior patterns
-3. Administrator expands agent capabilities
-4. Agent gains access to additional operations
-
-### 9.3 Mixed Environment Example
-
-A gateway might assign different capability profiles:
-
-- Administrative users: `{"kind": "mcp/*"}` (full access)
-- Service agents: `{"kind": "mcp/response"}` (response-only)
-- New agents: `{"kind": "mcp/proposal"}` (proposal-only)
-- Monitoring tools: `{"kind": "mcp/request", "payload": {"method": "*/list"}}` (read-only)
-
-All participants operate in the same space with their assigned capabilities.
-
-### 9.4 Delegated Fulfillment Example
-
-A human supervises an untrusted agent through intermediary agents:
-
-1. **Proposer Agent** (capability: `mcp/proposal`) proposes writing a file
-2. **Human** reviews the proposal and decides to approve it by directing the **Orchestrator Agent** (capability: `mcp/request`) to fulfill the proposal
-3. **Orchestrator Agent** sends the MCP request to **Worker Agent**
-4. **Worker Agent** executes the actual file write operation and responds
-5. Over time, **Human** teaches **Orchestrator Agent** rules about which proposals to auto-approve
-6. **Orchestrator Agent** begins autonomously fulfilling certain proposals without human intervention
-
-This pattern demonstrates **progressive automation** - a key goal of MEUP. As the orchestrator observes human decisions over time, it learns which types of proposals can be safely auto-approved. This transforms human judgment into automated policies, creating a system that becomes more autonomous while maintaining safety through learned boundaries.
-
----
-
-## 10. Appendix: Implementation Notes
-
-### 10.1 Gateway State
-
-Minimal state required per connection:
-```json
-{
- "connection_id": "ws-123",
- "participant_id": "agent-a",
- "capabilities": [{"kind": "mcp/proposal"}, {"kind": "chat"}],
- "connected_at": "2025-08-26T14:00:00Z"
-}
-```
-
-### 10.2 Proposal Tracking
-
-Optional proposal tracking for fulfillment (maintained by agents, not gateway):
-```json
-{
- "proposalId": "env-proposal-1",
- "proposer": "untrusted-agent",
- "target": "target-agent",
- "method": "tools/call",
- "params": {"name": "dangerous_operation", "arguments": {...}},
- "status": "pending",
- "createdAt": "2025-08-26T14:00:00Z",
- "expiresAt": "2025-08-26T14:05:00Z"
-}
-```
-
----
-
-## References
-
-- MCP Specification 2025-06-18
-- MEUP v0.0 Specification
-- ADR-003: Tool Access Control
-- OAuth 2.0 RFC 6749 (for token patterns)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/001-0-x7k-protocol-name.md b/spec/archive/protocol/v0.2/decisions/accepted/001-0-x7k-protocol-name.md
deleted file mode 100644
index affe7776..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/001-0-x7k-protocol-name.md
+++ /dev/null
@@ -1,478 +0,0 @@
-# ADR-x7k: Protocol Name
-
-**Status:** Accepted
-**Date:** 2025-08-30
-**Context:** MCPx Protocol Draft Specification
-**Incorporation:** Complete
-
-## Context
-
-The protocol needs a clear, memorable name that accurately represents its purpose and capabilities. The current name "MCPx" was a placeholder indicating an extension of MCP. A proper name should:
-- Clearly indicate the multi-party nature
-- Show the relationship to MCP
-- Be memorable and pronounceable
-- Accurately represent that humans are first-class participants
-- Avoid conflicts with existing protocols
-
-### Decision Drivers
-- Accuracy in describing protocol purpose
-- Clarity for new users
-- Maintaining connection to MCP heritage
-- Avoiding naming conflicts
-- Marketability and memorability
-
-## Decision
-
-**Adopt MEUP (Multi-Entity Unified-Context Protocol) as the protocol name**
-
-MEUP captures the protocol's core purpose of unifying context for multiple entities (humans, AI agents, robots, services). The name works as both protocol and CLI command ("meup into space"), making it memorable and action-oriented. While we use the full "Multi-Entity Unified-Context Protocol" expansion, the acronym intentionally drops the "C" to create the pronounceable "MEUP" rather than "MEUCP".
-
-## Options Considered
-
-### Option 1: MCPx (Status Quo)
-
-Keep the current MCPx name.
-
-**Pros:**
-- Already in use
-- Shows MCP extension clearly
-- No migration needed
-
-**Cons:**
-- Unclear what "x" means
-- Sounds like a placeholder
-- Doesn't describe functionality
-
-### Option 2: MECP - Multi-Entity Context Protocol
-
-**Pros:**
-- Clearly indicates multiple entities (not just models)
-- Emphasizes shared context (key differentiator)
-- Maintains MCP naming pattern
-- Simple, pronounceable, memorable
-- Accurately includes humans as entities
-
-**Cons:**
-- New acronym to learn
-- Requires documentation updates
-
-### Option 3: MPCP - Multi-Participant Context Protocol
-
-**Pros:**
-- "Participant" is inclusive of all entity types
-- Maintains MCP prefix and pattern
-- Clear functional description
-- Natural language - everyone understands "participant"
-- Avoids technical jargon
-- Accurate terminology for the protocol's purpose
-
-**Cons:**
-- Very similar to MCP (one letter difference)
-- Could be confused in speech/pronunciation
-- "Participant" is less distinctive than "Entity"
-- Longer acronym (4 letters)
-
-### Option 4: MCPP - Model Context Space Protocol
-
-**Pros:**
-- Maintains MCP prefix
-- Includes "space" terminology
-- Clear lineage from MCP
-
-**Cons:**
-- "Model" doesn't accurately include human participants
-- Ties protocol name to container metaphor
-- Less descriptive of actual functionality
-
-### Option 5: MACP - Multi-Agent Context Protocol
-
-**Pros:**
-- Clear multi-party indication
-- Maintains MCP pattern
-- Short and memorable
-
-**Cons:**
-- "Agent" may not clearly include humans
-- Could imply AI-only system
-
-### Option 6: MCSP - Multi-Context Sharing Protocol
-
-**Pros:**
-- Emphasizes context sharing
-- Clear functional description
-
-**Cons:**
-- Loses direct MCP connection in naming
-- Less clear about multi-entity aspect
-
-### Option 7: MXCP - Multi-X Context Protocol
-
-**Pros:**
-- X as variable represents any participant type (human, AI, robot, service)
-- Mathematically elegant - X as universal placeholder
-- Future-proof - doesn't limit participant types
-- Distinctive from MCP in pronunciation
-- Maintains MCP heritage pattern
-- Avoids entity/participant terminology debate
-- Cool technical factor
-
-**Cons:**
-- X might be unclear without explanation
-- Could seem gimmicky or trendy
-- Less descriptive than spelled-out names
-
-### Option 8: MEUP - Multi-Entity Unified Protocol (Recommended)
-
-Simple, clean expansion without "Context" in the name.
-
-**Pros:**
-- Natural command line usage ("meup into space")
-- Playful "beam me up" connotation
-- "Unified Context" precisely describes the shared space
-- Memorable and pronounceable
-- CLI and protocol name unity
-- Action-oriented feeling
-- Flexible acronym expansion
-
-**Cons:**
-- Less formal/professional sounding
-- Could be seen as gimmicky
-- Doesn't maintain MCP pattern as clearly
-- "Me up" phrasing might not translate well internationally
-
-### Option 9: MEUCP - Multi-Entity Unified-Context Protocol
-
-Full acronym with all components represented.
-
-**Pros:**
-- Accurate acronym - every word is represented
-- "Unified-Context" is precisely descriptive
-- Maintains technical credibility
-- No ambiguity about what each letter means
-- Still pronounceable ("mew-cp" or "me-you-cp")
-- Professional and precise
-
-**Cons:**
-- Loses the playful "me up" sound
-- 5 letters is getting long
-- Less memorable than MEUP
-- Harder to type quickly
-- "Mew-cp" pronunciation less intuitive
-- Doesn't work as naturally for CLI naming
-
-### Option 10: MEUP - Multi-Entity Unified-Context Protocol (with selective acronym)
-
-Same full name as Option 9 but using MEUP as the acronym (dropping the C).
-
-**Pros:**
-- Gets the "me up" playful sound
-- Full name is technically accurate
-- Marketing-friendly acronym
-- Natural CLI usage
-- Precedent exists (like SOAP not being SOARP)
-
-**Cons:**
-- Acronym doesn't match the full name exactly
-- Could seem contrived or forced
-- Might confuse technical audiences
-- Appears to prioritize branding over accuracy
-
-### Option 11: UCP - Unified-Context Protocol
-
-Drops "Multi-Entity" for simplicity.
-
-**Pros:**
-- Short and clean (3 letters)
-- Focus on the key innovation (unified context)
-- Easy to pronounce and remember
-- Professional sounding
-- No acronym gymnastics
-
-**Cons:**
-- Loses the multi-entity emphasis
-- Very generic sounding
-- Might conflict with existing protocols
-- Doesn't indicate who/what is being unified
-- Less descriptive than other options
-
-### Option 12: POD Protocol Variants
-
-Various "POD" acronym expansions were considered (Participant Orchestration & Delegation, etc.)
-
-**Pros:**
-- Memorable acronym
-- Could align with space terminology
-
-**Cons:**
-- "POD Protocol" name already exists
-- Focuses on container metaphor rather than functionality
-- Longer full names
-
-### Option 13: MEUC - Multi-Entity Unified-Context Protocol
-
-Same as MEUCP but with a 4-letter acronym dropping the P.
-
-**Pros:**
-- Shorter than MEUCP (4 letters vs 5)
-- Still includes all key concepts
-- Easier to type than MEUCP
-- Pronounceable ("mew-k" or "myook")
-- Maintains technical accuracy
-
-**Cons:**
-- Dropping "Protocol" from acronym is unconventional
-- Pronunciation might vary
-- Less clear that it's a protocol without the P
-- Could be confused with other acronyms
-
-### Option 14: UECP - Unified Entity Context Protocol
-
-Puts "Unified" first, emphasizing the unification aspect.
-
-**Pros:**
-- Emphasizes unification as the primary feature
-- Clear and descriptive
-- Professional sounding
-- All components represented in acronym
-- Good flow: unified -> entities -> context -> protocol
-
-**Cons:**
-- 4 letters might be harder to remember
-- Less distinctive than shorter options
-- "Unified Entity" could be misread as single entity
-- Doesn't maintain MCP pattern
-
-### Option 15: UEP - Unified Entity Protocol
-
-Simplified version focusing on unified entities.
-
-**Pros:**
-- Short and clean (3 letters)
-- Easy to pronounce ("you-ep" or "yoop")
-- Emphasizes the key innovation (unified entities)
-- Simple and memorable
-- Professional sounding
-
-**Cons:**
-- Loses "context" which is central to the protocol
-- Very generic sounding
-- Could conflict with existing protocols
-- Less descriptive than other options
-
-### Option 16: UCEP - Unified Context for Entities Protocol
-
-Emphasizes that the context is what's unified, not the entities.
-
-**Pros:**
-- Grammatically clearer ("unified context" not "unified entities")
-- Accurately describes the architecture
-- Makes it clear entities remain independent
-- Good technical accuracy
-
-**Cons:**
-- Longer name with "for" in the middle
-- 4-letter acronym
-- Less catchy than shorter options
-- More complex to explain
-
-### Option 17: UXP - Unified X Protocol (where X = Entity Context)
-
-Uses X as a variable representing the entity-context combination.
-
-**Pros:**
-- Very short (3 letters)
-- X as variable is elegant and flexible
-- Easy to pronounce ("you-ex-pee" or "yux-p")
-- Memorable and distinctive
-- X can represent the intersection/crossing of entities and context
-- Mathematical/technical appeal
-- Future-proof - X can evolve in meaning
-
-**Cons:**
-- X might be too abstract without explanation
-- Loses explicit mention of entities and context
-- Could seem gimmicky
-- Harder to understand purpose from name alone
-- "Unified X" sounds like placeholder text
-
-### Option 18: CCP - Collaborative Context Protocol
-
-Direct emphasis on collaboration between entities.
-
-**Pros:**
-- Short and memorable (3 letters)
-- "Collaborative" perfectly captures the spirit
-- Clear purpose from the name
-- Easy to pronounce
-- Professional sounding
-
-**Cons:**
-- High likelihood of naming conflicts (CCP is common)
-- Doesn't explicitly mention entities
-- Very generic combination of words
-- SEO challenges due to conflicts
-
-### Option 19: COCP - Collaborative Context Protocol
-
-Adds an O to avoid conflicts while keeping "Collaborative".
-
-**Pros:**
-- Avoids direct CCP conflicts
-- Still emphasizes collaboration
-- Reasonably short (4 letters)
-- Clear descriptive name
-- "Co" prefix reinforces collaboration
-
-**Cons:**
-- Pronunciation unclear ("co-cp"? "cock-p"?)
-- Extra letter makes it less elegant
-- Still might conflict with other protocols
-- The O seems arbitrary
-
-### Option 20: COLP - Collaborative Protocol
-
-Simplified version focusing on collaboration.
-
-**Pros:**
-- Short (4 letters)
-- Unique combination unlikely to conflict
-- "Collaborative" is the key differentiator
-- Clean acronym
-- Could pronounce as "collab-p"
-
-**Cons:**
-- Loses both "context" and "entity" concepts
-- Too generic without those key terms
-- Less descriptive of actual functionality
-- COLP is less intuitive as an acronym
-
-### Option 21: COPE - Commons Protocol for Entities
-
-Uses "Commons" metaphor for shared collaborative space.
-
-**Pros:**
-- "Commons" perfectly captures shared ownership concept
-- COPE is memorable and positive ("cope with complexity")
-- Clear that it's for multiple entities
-- Rich historical/cultural meaning (town commons, creative commons)
-- Implies democratic participation
-- Natural word with good connotations
-
-**Cons:**
-- "Cope" might imply dealing with problems
-- Longer full name with "for" in middle
-- Commons might sound informal to some
-- Could be seen as too metaphorical
-
-### Option 22: COMP - Commons Protocol
-
-Simplified commons-based name.
-
-**Pros:**
-- Very short (4 letters)
-- "Commons" captures the shared space concept
-- COMP is familiar from "computer", "component"
-- Clean and professional
-- Easy to type and remember
-- Could use "comp" as CLI command
-
-**Cons:**
-- Very generic sounding
-- High chance of conflicts (COMP is common abbreviation)
-- Loses explicit mention of entities
-- Might be confused with "comparison" or "computer"
-
-### Option 23: ECP - Entity Commons Protocol
-
-Entities-first naming with commons concept.
-
-**Pros:**
-- Short and clean (3 letters)
-- "Entity Commons" is descriptive
-- Emphasizes that entities share the commons
-- Professional yet approachable
-- Good flow: entities -> commons -> protocol
-- Natural abbreviation
-
-**Cons:**
-- ECP might already be taken
-- Could be confused with other protocols
-- "Entity Commons" is a new phrase to explain
-- Less distinctive than longer options
-
-### Option 24: MECP - Multi-Entity Commons Protocol
-
-Reinterprets MECP with "Commons" instead of "Context".
-
-**Pros:**
-- Keeps the MECP acronym already in use
-- "Commons" is more evocative than "Context"
-- Emphasizes shared ownership and democratic participation
-- Rich metaphor (digital commons, creative commons heritage)
-- Multiple entities sharing a commons is intuitive
-- Maintains MCP naming pattern
-- No migration needed from current MECP usage
-
-**Cons:**
-- Changes meaning of C from Context to Commons
-- Commons might sound less technical
-- Requires explaining the commons concept
-- Some might prefer the precision of "Context"
-
-## Implementation Details
-
-### Protocol Identifier
-```json
-{
- "protocol": "meup/v0.1"
-}
-```
-
-### Package Naming
-- NPM organization: `@meup`
-- Repository: `meup-protocol` or similar
-- Package structure:
- - `@meup/sdk` - Core SDK
- - `@meup/gateway` - Gateway server
- - `@meup/bridge` - MCP-to-MEUP bridge
- - `meup` - CLI tool (note: no @meup prefix for easier typing)
-
-### CLI Usage
-```bash
-# Install globally
-npm install -g meup
-
-# Natural command flow
-meup ./space.yaml # Start and join a space
-meup into workspace # Join existing space
-meup status # Check status
-meup down # Leave space
-```
-
-### Documentation Updates
-- Replace all instances of "MCPx" and "MECP" with "MEUP"
-- Update protocol description to emphasize unified context
-- Embrace the playful nature in examples and tutorials
-
-## Consequences
-
-### Positive
-- **Clear Purpose**: Name describes what the protocol does
-- **Inclusive**: "Entity" covers humans, AI, robots, services
-- **MCP Heritage**: Maintains naming pattern and connection
-- **Professional**: Sounds like a real protocol, not a placeholder
-- **No Conflicts**: No known conflicts with existing protocols
-
-### Negative
-- **Breaking Change**: Requires updating all references
-- **New Learning**: Users must learn new acronym
-- **SEO Impact**: Lose any existing "MCPx" search presence
-
-## Migration Path
-
-Since this is v0.x (experimental):
-1. Direct cutover to MEUP naming
-2. Update all documentation and folder structures
-3. Create new packages under @meup organization
-4. Emphasize the "meup into context" concept in messaging
-5. No backward compatibility needed in v0.x
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/001-1-y3m-communication-space-terminology.md b/spec/archive/protocol/v0.2/decisions/accepted/001-1-y3m-communication-space-terminology.md
deleted file mode 100644
index 86adf93b..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/001-1-y3m-communication-space-terminology.md
+++ /dev/null
@@ -1,330 +0,0 @@
-# ADR-y3m: Terminology for Communication Spaces
-
-**Status:** Accepted
-**Date:** 2025-08-30
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-**Parent ADR:** 001-0-x7k (Protocol Name)
-
-## Context
-
-The protocol needs clear terminology for the isolated communication spaces where participants collaborate. The current specification uses "topic" but this may not best convey the bounded, container-like nature of these spaces. The terminology affects:
-- How users understand the protocol
-- API endpoint naming
-- Documentation clarity
-- Conceptual alignment with the protocol's purpose
-
-### Decision Drivers
-- Clarity of concept for new users
-- Distinctiveness from generic messaging terms
-- Alignment with container/isolation concepts
-- Consistency with modern cloud/orchestration patterns
-
-## Decision
-
-**Adopt "space" as the terminology for communication spaces**
-
-The term "space" provides the optimal balance of simplicity and flexibility. It avoids conflicts with Kubernetes `pod.yaml` files while being generic enough to represent a unified context. The phrase "meup into space" creates a memorable command pattern with natural Star Trek connotations.
-
-Configuration files can use flexible naming conventions:
-- Default: `space.yaml` or `[name]-space.yaml`
-- But any `.yaml` file works: `meup production.yaml`, `meup code-review.yaml`, etc.
-
-This approach provides clear terminology for documentation while allowing users complete freedom in naming their configuration files.
-
-## Options Considered
-
-### Option 1: Topic (Status Quo)
-
-Keep the current "topic" terminology.
-
-**Pros:**
-- Already in documentation
-- Familiar from pub/sub systems
-- Clear conversation metaphor
-- No migration needed
-
-**Cons:**
-- Generic term used everywhere
-- Doesn't convey isolation/boundaries
-- Less distinctive
-- Doesn't emphasize the container aspect
-
-### Option 2: Pod
-
-Use "pod" as the primary term.
-
-**Pros:**
-- Conveys isolation and containment
-- Aligns with Kubernetes/container concepts
-- Distinctive and memorable
-- Natural fit: "join a pod"
-- Emphasizes bounded context
-
-**Cons:**
-- **Critical**: `pod.yaml` conflicts with Kubernetes pod definitions
-- May confuse with Kubernetes pods
-- Requires documentation updates
-- Less familiar for messaging contexts
-
-### Option 3: Room
-
-Use "room" as the primary term.
-
-**Pros:**
-- Natural collaboration metaphor
-- Used by Matrix protocol successfully
-- Intuitive for chat-like interactions
-- Clear spatial boundaries
-
-**Cons:**
-- Too chat-focused
-- Less technical/professional
-- Common term, not distinctive
-
-### Option 4: Channel
-
-Use "channel" as the primary term.
-
-**Pros:**
-- Familiar from Slack, Discord, IRC
-- Clear communication metaphor
-- Well understood concept
-
-**Cons:**
-- Very common terminology
-- Doesn't emphasize isolation
-- Implies persistent/named channels
-
-### Option 5: Space
-
-Use "space" as the primary term.
-
-**Pros:**
-- Neutral term
-- Conveys area for collaboration
-- Modern (used by various platforms)
-
-**Cons:**
-- Too generic
-- Doesn't convey boundaries strongly
-- Overused in tech
-
-### Option 6: Context
-
-Use "context" as the primary term.
-
-**Pros:**
-- Directly describes purpose
-- Technically accurate
-- Aligns with protocol goals
-- `context.yaml` is clear filename
-
-**Cons:**
-- Abstract concept
-- Could confuse with sub-contexts
-- Less intuitive for users
-- Might clash with other "context" configs
-
-### Option 7: Nexus
-
-Use "nexus" as the primary term.
-
-**Pros:**
-- Perfect "connection point" metaphor
-- Distinctive and memorable
-- Professional sounding
-- `nexus.yaml` is unique filename
-- Suggests convergence of entities
-
-**Cons:**
-- Less familiar term
-- Might sound too sci-fi
-- Could be taken by other tools
-
-### Option 8: Space (RECOMMENDED)
-
-Use "space" as the primary term.
-
-**Pros:**
-- Simple and universal
-- Works perfectly with MEUP: "meup into space"
-- `space.yaml` is intuitive
-- Natural phrasing: "join a space"
-- Familiar from Slack/Teams "spaces"
-
-**Cons:**
-- Very generic term
-- Doesn't convey boundaries strongly
-- Overused in tech
-
-### Option 9: Session
-
-Use "session" as the primary term.
-
-**Pros:**
-- Familiar from web/gaming
-- Clear temporal boundaries
-- `session.yaml` is descriptive
-- Implies active participation
-
-**Cons:**
-- Might imply non-persistent
-- Could suggest single-user
-- Less distinctive
-
-### Option 10: Mesh
-
-Use "mesh" as the primary term.
-
-**Pros:**
-- Implies interconnection
-- Modern service mesh association
-- `mesh.yaml` sounds technical
-- Captures multi-entity nature
-
-**Cons:**
-- Might imply peer-to-peer only
-- Could confuse with service mesh
-- Less intuitive for new users
-
-### Option 11: Sphere
-
-Use "sphere" as the primary term.
-
-**Pros:**
-- Bounded 3D space metaphor
-- Unique and distinctive
-- `sphere.yaml` is memorable
-- Suggests completeness
-
-**Cons:**
-- More abstract
-- Harder to visualize
-- Less common in tech
-
-### Option 12: Realm
-
-Use "realm" as the primary term.
-
-**Pros:**
-- Clear boundary/kingdom metaphor
-- Distinctive terminology
-- `realm.yaml` sounds authoritative
-- Implies governance
-
-**Cons:**
-- Gaming/fantasy connotations
-- Might sound unprofessional
-- Could imply hierarchy
-
-### Option 13: Unified-Context
-
-Use "unified-context" or shortened variants as the primary term.
-
-**Pros:**
-- Directly references MEUP's full name (Multi-Entity Unified-Context Protocol)
-- Most technically accurate description
-- Multiple filename options: `uc.yaml`, `unified.yaml`, `ucontext.yaml`
-- Reinforces the protocol's core purpose
-- No ambiguity about what it represents
-
-**Cons:**
-- Longer/hyphenated term less convenient
-- More technical sounding
-- `uc.yaml` might be too cryptic
-- "Join a unified-context" is awkward phrasing
-- Could be verbose in documentation
-
-## Implementation Details
-
-### Terminology Mapping
-- "topic" → "space"
-- "topic ID" → "space ID"
-- "join topic" → "join space"
-- "topic isolation" → "space isolation"
-- "per-topic" → "per-space"
-- "topic members" → "space participants"
-
-### API Endpoints
-```
-# Old
-GET /ws?topic=
-GET /topics
-GET /topics/{id}/participants
-
-# New
-GET /ws?space=
-GET /spaces
-GET /spaces/{id}/participants
-```
-
-### Environment Variables
-```bash
-# Old
-MEUP_TOPIC_NAME=my-topic
-MEUP_TOPIC_ID=abc123
-
-# New
-MEUP_SPACE_NAME=my-space
-MEUP_SPACE_ID=abc123
-```
-
-### Configuration Files
-```bash
-# Default conventions
-meup space.yaml # Simple default
-meup production-space.yaml # Named space
-meup ./configs/review.yaml # Any path/name works
-
-# The actual filename is flexible
-meup my-awesome-setup.yaml # User's choice
-```
-
-### Documentation Examples
-```
-# Old
-"Participants join a topic to collaborate..."
-"Each topic provides isolation..."
-"Messages are broadcast within the topic..."
-
-# New
-"Participants join a space to collaborate..."
-"Each space provides isolation..."
-"Messages are broadcast within the space..."
-"Use 'meup into space' to enter the unified context..."
-```
-
-## Consequences
-
-### Positive
-- **No Conflicts**: Avoids Kubernetes `pod.yaml` collision
-- **Memorable Command**: "meup into space" is iconic and fun
-- **Flexible Naming**: Users can name config files anything
-- **Familiar**: "Space" used by Slack, Teams, etc.
-- **Simple**: Easy to understand and explain
-
-### Negative
-- **Generic**: "Space" is a common term
-- **Less Distinctive**: Not as unique as "pod" or "nexus"
-- **Migration Work**: Requires updating all documentation from "topic"
-
-## Security Considerations
-
-None - this is purely a terminology change.
-
-## Migration Path
-
-Since this is v0.x (experimental):
-1. Update all documentation to use "space"
-2. Change API endpoints
-3. Update environment variable names
-4. Update SDK method names
-5. No backward compatibility needed in v0.x
-
-## Future Considerations
-
-- Space discovery mechanisms
-- Space lifecycle management
-- Space templates for common scenarios
-- Space federation (connecting spaces)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/002-0-m3p-namespace-pattern.md b/spec/archive/protocol/v0.2/decisions/accepted/002-0-m3p-namespace-pattern.md
deleted file mode 100644
index ed752095..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/002-0-m3p-namespace-pattern.md
+++ /dev/null
@@ -1,622 +0,0 @@
-# ADR-m3p: Message Kind Namespace Pattern
-
-**Status:** Accepted
-**Date:** 2025-08-30
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-
-## Context
-
-The current spec uses various patterns for the `kind` field, leading to confusion about the namespace structure. We need a consistent, elegant pattern that clearly indicates:
-1. What protocol/format is in the payload
-2. What MEUP operation is being performed
-3. Any additional context needed for routing/capabilities
-
-### Current Issues
-- Inconsistent patterns: `mcp/request:tools/call` vs `system/welcome` vs `chat`
-- Unclear when to use `/` vs `:` separators
-- Confusion about whether `mcp/proposal:withdraw` means MCP method "withdraw"
-- No clear mental model for developers
-- **Mixed abstraction levels**: The `kind` field tries to serve both as an envelope-level message type and a payload-level operation descriptor, violating separation of concerns
-
-## Decision
-
-**Accepted: Option 7 (Minimal Kind with Payload Inspection)**
-
-**Pattern:** `TYPE[.SUBTYPE]` with gateway payload inspection for capabilities
-
-### Design Rationale:
-
-The `kind` field is kept minimal, containing only the high-level message type. The actual operation details live in the payload where they naturally belong. This approach:
-
-- **Simplifies the envelope**: Kind only indicates message type
-- **Embraces payload inspection**: Gateway examines payload for fine-grained permissions
-- **Enables complex rules**: Capabilities can express sophisticated patterns
-- **Maintains MCP alignment**: MCP messages already have all details in payload
-
-### Kind Values:
-
-- `mcp.request` - Any MCP request
-- `mcp.response` - Any MCP response
-- `mcp.proposal` - Any MCP proposal
-- `meup.lifecycle` - MEUP lifecycle operations
-- `system` - System messages
-- `chat` - Chat messages
-
-### Why Option 7 Wins:
-- **Simplicity**: Minimal `kind` field is easier to understand
-- **Flexibility**: Rich capability expressions in gateway configuration
-- **Truth in payload**: Payload is authoritative source
-- **Natural for MCP**: MCP already has all details in payload
-- **Future-proof**: Can add complex permission rules without protocol changes
-- **Clean separation of concerns**: The envelope (`kind`) handles routing/type, while the payload handles operation details - no mixing of abstraction levels
-
-### Implementation Requirements:
-
-**Gateway MUST:**
-1. Parse the minimal `kind` field (simple string match)
-2. Inspect payload content based on capability definitions
-3. Match payload patterns against participant capabilities
-4. Cache capability decisions when possible
-
-**Capability definitions will include payload patterns** (see child ADR 002-1):
-```javascript
-{
- kind: "mcp.request",
- payload: {
- method: "tools/*",
- params: {
- name: "read_*"
- }
- }
-}
-```
-
-**Examples with Minimal Kind:**
-```
-kind: mcp.request
-payload: {
- method: "tools/call",
- params: { name: "read_file" }
-}
-// Gateway checks if participant has capability for this payload pattern
-
-kind: meup.lifecycle
-payload: {
- action: "withdraw",
- proposalId: "prop-123"
-}
-// Gateway validates lifecycle action permissions
-
-kind: system
-payload: {
- type: "welcome",
- participant: {...}
-}
-// Only gateway can send system messages
-```
-
-### Migration from Current Spec:
-- `mcp/request:tools/call` → `mcp.request` + payload inspection
-- `mcp/proposal:tools/call` → `mcp.proposal` + payload inspection
-- `system/welcome` → `system` + payload.type check
-- `system/presence` → `system` + payload.type check
-- `chat` → `chat` (no change needed)
-- `proposal/withdraw` → `meup.lifecycle` + payload.action check
-- `proposal/reject` → `meup.lifecycle` + payload.action check
-
-## Options Considered
-
-### Option 1: Payload-First Pattern (Current-ish)
-
-**Pattern:** `PAYLOAD_TYPE/OPERATION[:METHOD[:CONTEXT]]`
-
-Examples:
-- `mcp/request:tools/call` - MCP payload, request operation, tools/call method
-- `mcp/proposal:tools/call` - MCP payload, proposal operation, tools/call method
-- `mcp/response:tools/call` - MCP payload, response operation, tools/call method
-- `proposal/withdraw` - Proposal payload, withdraw operation
-- `proposal/reject` - Proposal payload, reject operation
-- `system/welcome` - System payload, welcome operation
-- `system/presence` - System payload, presence operation
-- `system/error` - System payload, error operation
-- `chat` - Chat payload (simple case)
-
-**Capability Examples:**
-- `mcp/*` - All MCP operations
-- `mcp/request:*` - All MCP requests
-- `mcp/request:tools/*` - All tool requests
-- `proposal/*` - All proposal lifecycle operations
-- `system/*` - Reserved for gateway only
-
-**Pros:**
-- First segment tells you payload structure
-- Works for simple cases
-- Decent capability pattern matching
-
-**Cons:**
-- Confusion when operation seems like a method (proposal:withdraw)
-- Inconsistent depth (chat vs mcp/request:tools/call)
-- Mixed separators confuse pattern matching
-
----
-
-### Option 2: Strict Three-Level Hierarchy
-
-**Pattern:** `PAYLOAD_PROTOCOL.MCPX_OPERATION[.PAYLOAD_METHOD[:PAYLOAD_CONTEXT]]`
-
-Examples:
-- `mcp.request.tools/call` - MCP protocol, request op, tools/call method
-- `mcp.proposal.tools/call` - MCP protocol, proposal op, tools/call method
-- `mcp.response.tools/call` - MCP protocol, response op, tools/call method
-- `meup.withdraw.proposal` - MEUP protocol, withdraw op, proposal target
-- `meup.reject.proposal` - MEUP protocol, reject op, proposal target
-- `system.welcome.participant` - System protocol, welcome op, participant target
-- `system.presence.join` - System protocol, presence op, join event
-- `system.presence.leave` - System protocol, presence op, leave event
-- `system.error.capability` - System protocol, error op, capability violation
-- `chat.message.text` - Chat protocol, message op, text format
-
-**Capability Examples:**
-- `mcp.*` - All MCP operations
-- `mcp.request.*` - All MCP requests
-- `mcp.request.tools/*` - All tool requests
-- `meup.withdraw.*` - Can withdraw proposals
-- `system.*` - Reserved for gateway only
-- `chat.*` - All chat operations
-
-**Pros:**
-- Completely consistent structure
-- Clear hierarchy
-- No ambiguity about separators
-- Very clean capability patterns
-
-**Cons:**
-- Verbose for simple messages
-- Dots might be confused with object notation
-- Breaking change from current spec
-
----
-
-### Option 3: Operation-First Pattern
-
-**Pattern:** `OPERATION/TARGET[:DETAILS]`
-
-Examples:
-- `request/mcp:tools/call` - Request operation on MCP, tools/call method
-- `proposal/mcp:tools/call` - Proposal operation on MCP, tools/call method
-- `response/mcp:tools/call` - Response operation on MCP, tools/call method
-- `withdraw/proposal` - Withdraw operation on proposal
-- `reject/proposal` - Reject operation on proposal
-- `welcome/participant` - Welcome operation for participant
-- `presence/join` - Presence operation, join event
-- `presence/leave` - Presence operation, leave event
-- `error/capability` - Error operation, capability type
-- `message/chat` - Message operation for chat
-
-**Capability Examples:**
-- `request/*` - All request operations
-- `request/mcp:*` - All MCP requests
-- `request/mcp:tools/*` - All tool requests
-- `withdraw/*` - Can withdraw anything
-- `welcome/*` - Reserved for gateway
-
-**Pros:**
-- Operation is always first (what are we doing?)
-- Target is clear (what are we doing it to?)
-- Flexible detail section
-
-**Cons:**
-- Breaks from current spec significantly
-- Less clear what's in the payload
-- Capability patterns less intuitive
-
----
-
-### Option 4: Hybrid with Clear Rules
-
-**Pattern:** `NAMESPACE/[SUBNAMESPACE/]OPERATION[:METHOD[:CONTEXT]]`
-
-Rules:
-- `/` separates protocol namespaces
-- `:` separates operation details
-- Never use `:` for MEUP-specific operations
-
-Examples:
-- `mcp/request:tools/call` - MCP namespace, request:tools/call
-- `mcp/proposal:tools/call` - MCP namespace, proposal:tools/call
-- `mcp/response:tools/call` - MCP namespace, response:tools/call
-- `meup/proposal/withdraw` - MEUP namespace, proposal namespace, withdraw
-- `meup/proposal/reject` - MEUP namespace, proposal namespace, reject
-- `system/welcome` - System namespace, welcome
-- `system/presence` - System namespace, presence
-- `system/error` - System namespace, error
-- `chat` - Chat (top-level for simplicity)
-
-**Capability Examples:**
-- `mcp/*` - All MCP operations
-- `mcp/request:*` - All MCP requests
-- `mcp/request:tools/*` - All tool requests
-- `meup/proposal/*` - All MEUP proposal lifecycle
-- `system/*` - Reserved for gateway only
-- `chat` - Chat capability
-
-**Pros:**
-- Clear rules
-- Explicit about MEUP extensions
-- Maintains most of current spec
-- Good capability patterns
-
-**Cons:**
-- Still some inconsistency (chat vs others)
-- Longer kinds for MEUP operations
-- Two different separator meanings
-
----
-
-### Option 5: Semantic Prefixing
-
-**Pattern:** `[PREFIX]PROTOCOL:OPERATION[:DETAILS]`
-
-Prefixes:
-- `>` for requests/proposals (outgoing)
-- `<` for responses (incoming)
-- `!` for lifecycle/control
-- `@` for system
-- No prefix for simple messages
-
-Examples:
-- `>mcp:tools/call` - Request MCP tools/call
-- `>proposal:tools/call` - Propose MCP tools/call
-- `mcp:*` - All MCP requests
-- `>mcp:tools/*` - All tool requests
-- `>proposal:*` - All proposals
-- `!*` - All lifecycle operations
-- `@*` - Reserved for gateway only
-- `chat` - Chat capability
-
-**Pros:**
-- Visual distinction of operation types
-- Compact
-- Clear at a glance
-- Unique capability patterns
-
-**Cons:**
-- Non-standard use of symbols
-- Might complicate parsing/routing
-- Too creative?
-- Hard to type/remember symbols
-
----
-
-### Option 6: Unified Verb-Based
-
-**Pattern:** `VERB:TARGET[/DETAILS]`
-
-Examples:
-- `request:mcp/tools/call` - Request MCP tools/call
-- `propose:mcp/tools/call` - Propose MCP tools/call
-- `respond:mcp/tools/call` - Respond to MCP tools/call
-- `withdraw:proposal` - Withdraw proposal
-- `reject:proposal` - Reject proposal
-- `welcome:participant` - Welcome participant
-- `notify:presence/join` - Notify presence join
-- `notify:presence/leave` - Notify presence leave
-- `error:capability` - Error about capability
-- `send:chat` - Send chat message
-
-**Capability Examples:**
-- `request:*` - Can make any request
-- `request:mcp/*` - Can make MCP requests
-- `request:mcp/tools/*` - Can make tool requests
-- `withdraw:*` - Can withdraw anything
-- `welcome:*` - Reserved for gateway
-- `send:*` - Can send messages
-
-**Pros:**
-- Extremely consistent
-- Verb always first (action-oriented)
-- Self-documenting
-- Clear capability semantics
-
-**Cons:**
-- Major breaking change
-- Verbose for responses
-- Doesn't indicate payload type clearly
-- Capability overlap concerns
-
----
-
-### Option 7: Minimal Kind with Payload Inspection
-
-**Pattern:** `TYPE[.SUBTYPE]` (minimal kind) + gateway inspects payload
-
-The `kind` field only indicates the message type at a high level. The gateway inspects the actual payload content to determine capabilities.
-
-Examples:
-- `mcp.request` - Any MCP request (gateway checks payload.method)
-- `mcp.response` - Any MCP response
-- `mcp.proposal` - Any MCP proposal
-- `meup.lifecycle` - MEUP lifecycle operations (withdraw, reject, etc.)
-- `system` - System messages (gateway checks payload.type)
-- `chat` - Chat messages
-
-**Capability Examples:**
-- `mcp.request` + payload inspection for `method: "tools/call"`
-- `mcp.request` + payload inspection for `params.name: "read_file"`
-- `meup.lifecycle` + payload inspection for `action: "withdraw"`
-
-**Gateway Capability Matching:**
-```javascript
-// Capability definition includes payload patterns
-capability: {
- kind: "mcp.request",
- payload: {
- method: "tools/*",
- params: {
- name: "read_*"
- }
- }
-}
-```
-
-**Pros:**
-- Minimal `kind` field complexity
-- Flexible capability definitions
-- Payload is source of truth
-- Can express complex permissions
-- Natural for MCP compatibility
-
-**Cons:**
-- **Performance hit**: Must parse payload for every message
-- **Complexity**: Gateway needs payload schema knowledge
-- **Security risk**: Deep inspection increases attack surface
-- **Debugging**: Harder to see permissions from `kind` alone
-- **Caching**: Can't cache capability checks based on `kind` alone
-
-**Performance Impact:**
-- Additional ~50-100μs per message for payload parsing
-- Memory overhead for payload schemas
-- Can't use simple string matching for capabilities
-
----
-
-## Security & Parsing Analysis
-
-### Spoofing Risks
-
-**Key Risk**: Participant claims a `kind` they have capability for, but payload contains different operation.
-
-| Option | Spoofing Risk | Example Attack | Mitigation |
-|--------|---------------|----------------|------------|
-| 1. Payload-First | **High** | Use `mcp/request:tools/read` kind with `tools/write` in payload | Must validate METHOD and CONTEXT match payload |
-| 2. Three-Level | **Low** | Harder - dots create clear boundaries | Simple validation: split on dots, verify each part |
-| 3. Operation-First | **Medium** | Use `request/mcp:tools/read` with different tool | Must parse after `:` carefully |
-| 4. Hybrid Rules | **High** | Mixed separators confuse validation | Complex rules for different namespaces |
-| 5. Semantic Prefix | **Low** | Prefix makes operation explicit | Prefix must match payload operation type |
-| 6. Verb-Based | **Low** | Verb explicitly states operation | Verb must match payload action |
-| 7. Minimal Kind | **Medium** | Generic `mcp.request` could hide actual operation | Gateway must deeply inspect payload |
-
-### Parsing Complexity
-
-| Option | Parse Complexity | Regex Example | Edge Cases |
-|--------|-----------------|---------------|------------|
-| 1. Payload-First | **Complex** | `/^([^\/]+)\/([^:]+)(:(.+))?$/` | Mixed separators, variable depth |
-| 2. Three-Level | **Simple** | `/^([^.]+)\.([^.]+)\.([^:]+)(:(.+))?$/` | Fixed structure, clear boundaries |
-| 3. Operation-First | **Medium** | `/^([^\/]+)\/([^:]+)(:(.+))?$/` | Must handle optional details |
-| 4. Hybrid Rules | **Complex** | Multiple patterns needed | Different rules per namespace |
-| 5. Semantic Prefix | **Simple** | `/^([>; // Additional context metadata
- };
- payload: any;
-}
-```
-
-### Context Lifecycle
-
-1. **Context Creation**: Any message with a new context.id implicitly creates that context
-2. **Context Membership**: Messages with same context.id belong to that context
-3. **Context Conclusion**: Context ends when no more messages reference it (timeout-based)
-4. **No Explicit Start/End**: Contexts are implicit through usage
-
-### Example: Reasoning Context
-
-```json
-// First message creates the context
-{
- "id": "msg-1",
- "kind": "reflection",
- "context": {
- "id": "reason-789",
- "type": "reasoning",
- "metadata": {
- "trigger": "security-analysis",
- "started_at": "2025-08-31T12:00:00Z"
- }
- },
- "payload": {
- "thought": "Starting security analysis"
- }
-}
-
-// Subsequent messages in same context
-{
- "id": "msg-2",
- "kind": "mcp/proposal:tools/call",
- "context": {
- "id": "reason-789",
- "type": "reasoning"
- },
- "payload": {...}
-}
-
-// Final message still in context
-{
- "id": "msg-3",
- "kind": "conclusion",
- "context": {
- "id": "reason-789",
- "type": "reasoning",
- "metadata": {
- "confidence": 0.95,
- "ended_at": "2025-08-31T12:00:30Z"
- }
- },
- "payload": {
- "decision": "Deny the operation"
- }
-}
-
-// Action based on reasoning (references context via correlation)
-{
- "id": "msg-4",
- "kind": "mcp/response:tools/call",
- "correlation_id": "reason-789", // Links to context
- "payload": {
- "error": "Operation denied after security analysis"
- }
-}
-```
-
-### Nested Contexts Example
-
-```json
-{
- "id": "msg-10",
- "kind": "reflection",
- "context": {
- "id": "sub-reason-abc",
- "type": "reasoning",
- "parent": "reason-789" // Nested within parent context
- },
- "payload": {
- "thought": "Deeper analysis needed"
- }
-}
-```
-
-### Gateway Behavior
-
-The gateway:
-- MUST preserve the context field in envelopes
-- MAY offer filtering based on context.type or context.id
-- SHOULD NOT validate context structure beyond basic syntax
-- MUST broadcast context messages normally (unless filtered)
-
-### Participant Behavior
-
-Participants:
-- MAY ignore the context field entirely
-- MAY filter messages based on context
-- MAY use context for message grouping in UI
-- SHOULD generate unique context IDs (UUIDs recommended)
-- MAY include or exclude context messages when building prompts
-
-### Filtering Strategies
-
-Participants can implement various filtering strategies:
-
-```typescript
-// Include everything (default)
-const allMessages = messages;
-
-// Exclude all sub-contexts
-const mainOnly = messages.filter(m => !m.context);
-
-// Include only specific context types
-const withReasoning = messages.filter(m =>
- !m.context || m.context.type === 'reasoning'
-);
-
-// Include only conclusion messages from contexts
-const conclusions = messages.filter(m =>
- m.context && m.kind === 'conclusion'
-);
-
-// Get all messages from a specific context
-const contextMessages = messages.filter(m =>
- m.context?.id === 'reason-789'
-);
-```
-
-## Consequences
-
-### Positive
-- **Simple Implementation**: Single optional field in envelope
-- **Flexible Filtering**: Participants choose what to include
-- **Nested Support**: Natural parent/child relationship
-- **Backward Compatible**: Optional field doesn't break existing implementations
-- **Gateway Agnostic**: Gateway doesn't need to understand contexts
-- **Type Agnostic**: Any message kind can be in a context
-
-### Negative
-- **Envelope Change**: Requires protocol version update
-- **ID Management**: Participants must generate and track context IDs
-- **No Enforcement**: Gateway can't enforce context structure
-- **Implicit Lifecycle**: No explicit start/end may cause confusion
-- **Memory Growth**: Long-running contexts could accumulate many messages
-
-## Security Considerations
-
-- Context IDs should be unguessable (use UUIDs)
-- Malicious actors could create excessive contexts to consume memory
-- Context metadata could leak sensitive information
-- Rate limiting may need to consider contexts as units
-- Nested contexts could be used for DoS attacks (depth limits needed)
-
-## Migration Path
-
-1. Add context field to envelope specification
-2. Update SDKs to support context field (backward compatible)
-3. Agents can start using contexts immediately
-4. Observing participants can add context filtering gradually
-5. UIs can add context visualization features
-
-## Future Enhancements
-
-- Context templates for common patterns
-- Context compression for transmission
-- Context search and replay capabilities
-- Cross-space context correlation
-- Automatic context summarization
-- Context-based capability rules
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/004-2-p4m-context-field-structure.md b/spec/archive/protocol/v0.2/decisions/accepted/004-2-p4m-context-field-structure.md
deleted file mode 100644
index 1abdb4d9..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/004-2-p4m-context-field-structure.md
+++ /dev/null
@@ -1,514 +0,0 @@
-# ADR-p4m: Context Field Structure and Patterns
-
-**Status:** Accepted
-**Date:** 2025-08-31
-**Context:** MEUP/MEUP Protocol Draft Specification
-**Incorporation:** Complete
-**Parent ADR:** 005-1-k9j (Sub-Context Protocol Mechanics)
-
-## Context
-
-ADR-k9j established that we should use an optional `context` field in the envelope structure to support sub-contexts. This ADR focuses on defining the exact structure and contents of that context field, establishing patterns for its use, and ensuring it meets all requirements while remaining simple and extensible.
-
-Key requirements for the context field:
-- Support various context types (reasoning, workflow, delegation, etc.)
-- Enable nesting and parent-child relationships
-- Allow filtering and selective processing
-- Maintain simplicity and avoid over-engineering
-- Support both ephemeral and persistent contexts
-- Enable correlation without confusion with correlation_id
-
-### Decision Drivers
-- Minimize field complexity while maintaining flexibility
-- Clear semantics that don't overlap with existing fields
-- Support common use cases without prescribing implementation
-- Enable efficient filtering and processing
-- Avoid ambiguity in field meanings
-- Consider future extensibility
-
-## Decision
-
-**Use a simple string context field with path-based hierarchy**
-
-The context field should be just a string that can optionally use path notation (e.g., `parent/child/grandchild`) to represent hierarchy.
-
-## Options Considered
-
-### Option 1: Simple String (Flat)
-
-Context field is just a string identifier with no hierarchy.
-
-```typescript
-context?: string; // Just an ID like "ctx-789" or "reasoning-abc"
-```
-
-**Pros:**
-- Maximum simplicity
-- No parsing required
-- Smallest message size
-- No schema validation needed
-
-**Cons:**
-- No built-in hierarchy (need separate parent tracking)
-- No type information
-- Relationships must use correlation_id
-
-**Example:**
-```json
-{
- "context": "ctx-789",
- "kind": "reflection",
- "payload": {...}
-}
-```
-
-### Option 2: Path-Based Hierarchy (Recommended)
-
-Context ID uses forward-slash notation for natural hierarchy.
-
-```typescript
-context?: string; // Path like "ctx-789" or "ctx-789/sub-abc" or "ctx-789/sub-abc/detail-xyz"
-```
-
-**Pros:**
-- Still just a simple string field
-- Natural hierarchy representation
-- Easy to parse parent from path
-- Familiar pattern (URLs, file paths)
-- Self-documenting structure
-- Can extract depth, parent, root easily
-
-**Cons:**
-- Need to parse for parent extraction
-- Could get long with deep nesting
-- Path separator choice matters
-
-**Examples:**
-```json
-// Root context
-{
- "context": "reason-789",
- "kind": "reflection",
- "payload": {"thought": "Starting analysis"}
-}
-
-// Nested context
-{
- "context": "reason-789/security-check",
- "kind": "mcp/request:tools/call",
- "payload": {...}
-}
-
-// Deeply nested
-{
- "context": "reason-789/security-check/permission-scan",
- "kind": "reflection",
- "payload": {"thought": "Checking file permissions"}
-}
-```
-
-### Option 3: Object with ID and Type
-
-Context object with id and type fields.
-
-```typescript
-context?: {
- id: string;
- type?: string;
-}
-```
-
-**Pros:**
-- Simple but useful
-- Enables type-based filtering
-- Clear semantics
-- Small message size
-
-**Cons:**
-- No nesting support
-- No additional metadata
-- May need extension later
-
-**Example:**
-```json
-{
- "context": {
- "id": "ctx-789",
- "type": "reasoning"
- },
- "kind": "reflection",
- "payload": {...}
-}
-```
-
-### Option 4: Object Structure with Parent
-
-Simple object with id, optional type, and optional parent for nesting.
-
-```typescript
-context?: {
- id: string;
- type?: string;
- parent?: string; // Parent context ID
-}
-```
-
-**Pros:**
-- Supports all core use cases
-- Simple and predictable
-- Enables nesting without complexity
-- Easy to filter and process
-- No nested objects
-
-**Cons:**
-- No arbitrary metadata
-- Parent is just an ID (no type info)
-
-**Example:**
-```json
-{
- "context": {
- "id": "sub-ctx-abc",
- "type": "analysis",
- "parent": "ctx-789"
- },
- "kind": "reflection",
- "payload": {...}
-}
-```
-
-### Option 4: Nested Parent Structure
-
-Parent as an object with its own type.
-
-```typescript
-context?: {
- id: string;
- type?: string;
- parent?: {
- id: string;
- type?: string;
- }
-}
-```
-
-**Pros:**
-- Parent type information available
-- More structured relationships
-
-**Cons:**
-- More complex
-- Recursive structure implications
-- Larger message size
-- Over-engineered for most uses
-
-**Example:**
-```json
-{
- "context": {
- "id": "sub-ctx-abc",
- "type": "analysis",
- "parent": {
- "id": "ctx-789",
- "type": "reasoning"
- }
- }
-}
-```
-
-### Option 5: Full Metadata Support
-
-Include arbitrary metadata field.
-
-```typescript
-context?: {
- id: string;
- type?: string;
- parent?: string;
- metadata?: Record;
-}
-```
-
-**Pros:**
-- Maximum flexibility
-- Extensible without schema changes
-- Supports any future needs
-
-**Cons:**
-- Encourages inconsistency
-- No schema validation
-- Potential for abuse
-- Larger messages
-- Complexity creep
-
-**Example:**
-```json
-{
- "context": {
- "id": "ctx-789",
- "type": "reasoning",
- "metadata": {
- "confidence": 0.95,
- "trigger": "security-check",
- "custom_field": "anything"
- }
- }
-}
-```
-
-### Option 6: Labels/Tags Approach
-
-Use labels array instead of type.
-
-```typescript
-context?: {
- id: string;
- labels?: string[];
- parent?: string;
-}
-```
-
-**Pros:**
-- Multiple categorizations possible
-- Flexible tagging system
-- Familiar from k8s/cloud systems
-
-**Cons:**
-- Array processing overhead
-- Ambiguous semantics
-- Harder to standardize
-
-**Example:**
-```json
-{
- "context": {
- "id": "ctx-789",
- "labels": ["reasoning", "security", "critical"],
- "parent": "ctx-456"
- }
-}
-```
-
-## Implementation Details
-
-### Recommended Context Field Structure
-
-```typescript
-interface Envelope {
- // ... other fields ...
- context?: string; // Path-based hierarchy like "parent/child/grandchild"
- // ... other fields ...
-}
-```
-
-### Path-Based Hierarchy Format
-
-Use forward slashes for hierarchy, similar to URL paths:
-
-```
-[/[/...]]
-```
-
-Rules:
-- Forward slash (`/`) as separator
-- No leading or trailing slashes
-- Each segment should be a valid identifier (alphanumeric + dash/underscore)
-- Maximum depth is implementation-specific (suggest 5 levels)
-- IDs should be short but meaningful
-
-### Context Operations
-
-```typescript
-// Get root context from path
-function getRootContext(context: string): string {
- return context.split('/')[0];
-}
-
-// Get parent context (if any)
-function getParentContext(context: string): string | null {
- const parts = context.split('/');
- return parts.length > 1
- ? parts.slice(0, -1).join('/')
- : null;
-}
-
-// Check if context is nested
-function isNestedContext(context: string): boolean {
- return context.includes('/');
-}
-
-// Get context depth
-function getContextDepth(context: string): number {
- return context.split('/').length;
-}
-
-// Check if one context is ancestor of another
-function isAncestor(ancestor: string, descendant: string): boolean {
- return descendant.startsWith(ancestor + '/');
-}
-```
-
-### Context Examples
-
-#### Simple Reasoning Context
-
-```json
-// Start reasoning
-{
- "id": "msg-1",
- "context": "reason-789",
- "kind": "reflection",
- "payload": {"thought": "Analyzing request"}
-}
-
-// Nested analysis
-{
- "id": "msg-2",
- "context": "reason-789/security",
- "kind": "mcp/request:tools/call",
- "payload": {...}
-}
-
-// Even deeper
-{
- "id": "msg-3",
- "context": "reason-789/security/permissions",
- "kind": "reflection",
- "payload": {"thought": "Insufficient permissions"}
-}
-
-// Back to main reasoning
-{
- "id": "msg-4",
- "context": "reason-789",
- "kind": "conclusion",
- "payload": {"decision": "Deny due to permissions"}
-}
-```
-
-#### Workflow with Subtasks
-
-```json
-// Main workflow
-{
- "context": "deploy-abc",
- "kind": "workflow/start",
- "payload": {...}
-}
-
-// Subtask 1
-{
- "context": "deploy-abc/build",
- "kind": "mcp/request:tools/call",
- "payload": {...}
-}
-
-// Subtask 2 (parallel with 1)
-{
- "context": "deploy-abc/test",
- "kind": "mcp/request:tools/call",
- "payload": {...}
-}
-
-// Nested in subtask 2
-{
- "context": "deploy-abc/test/unit-tests",
- "kind": "reflection",
- "payload": {...}
-}
-```
-
-### Filtering Strategies
-
-```typescript
-// All messages in a context tree
-function getContextTree(messages: Message[], rootContext: string) {
- return messages.filter(m =>
- m.context === rootContext ||
- m.context?.startsWith(rootContext + '/')
- );
-}
-
-// Direct children only
-function getDirectChildren(messages: Message[], parentContext: string) {
- const parentDepth = parentContext.split('/').length;
- return messages.filter(m => {
- if (!m.context?.startsWith(parentContext + '/')) return false;
- const childDepth = m.context.split('/').length;
- return childDepth === parentDepth + 1;
- });
-}
-
-// Exclude all sub-contexts
-function mainContextOnly(messages: Message[]) {
- return messages.filter(m => !m.context);
-}
-
-// Get root contexts only (no parent)
-function getRootContexts(messages: Message[]) {
- return messages.filter(m =>
- m.context && !m.context.includes('/')
- );
-}
-```
-
-### Relationship to correlation_id
-
-The `context` and `correlation_id` fields serve different purposes:
-
-- **context**: Groups related messages into logical units (hierarchical)
-- **correlation_id**: Links responses to requests or actions to triggers (point-to-point)
-
-A message can have both:
-
-```json
-{
- "id": "msg-123",
- "context": "reason-789/security", // Part of reasoning hierarchy
- "correlation_id": "proposal-456", // Fulfills this proposal
- "kind": "mcp/request:tools/call",
- "payload": {...}
-}
-```
-
-## Consequences
-
-### Positive
-- **Maximum Simplicity**: Just a string field, no objects or arrays
-- **Natural Hierarchy**: Path notation is familiar and intuitive
-- **Self-Contained**: Hierarchy encoded in the ID itself
-- **Efficient**: Fast string operations, minimal parsing
-- **Human-Readable**: Paths are self-documenting
-- **Flexible**: Can embed type info in segment names if needed
-
-### Negative
-- **No Explicit Type**: Must infer from ID or use conventions
-- **String Parsing**: Need to split strings for hierarchy operations
-- **Length Concerns**: Deep nesting creates longer strings
-- **No Validation**: Any string is valid (could be garbage)
-- **Convention-Based**: Relies on consistent path formatting
-
-## Security Considerations
-
-- Path traversal attacks not applicable (these aren't file paths)
-- Maximum depth should be enforced to prevent DoS (suggest 5 levels)
-- IDs should be sanitized if displayed in UIs
-- Avoid sensitive information in context IDs
-- Consider length limits for context strings (suggest 255 chars)
-
-## Migration Path
-
-1. Update envelope schema to simple string context field
-2. Document path-based hierarchy convention
-3. Provide helper functions in SDKs
-4. Existing messages work unchanged (field is optional)
-5. Establish conventions for common context patterns
-
-## Future Enhancements
-
-- Context templates for common patterns
-- Context-aware capabilities (e.g., can filter by context prefix)
-- Context summarization for long chains
-- Cross-space context correlation
-- Context visualization standards
-- Optional type prefixes in path segments
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/005-g7r-capability-delegation.md b/spec/archive/protocol/v0.2/decisions/accepted/005-g7r-capability-delegation.md
deleted file mode 100644
index 99cf66cd..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/005-g7r-capability-delegation.md
+++ /dev/null
@@ -1,534 +0,0 @@
-# ADR-g7r: Capability Delegation
-
-**Status:** Accepted
-**Date:** 2025-08-31
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-
-## Context
-
-Currently, capabilities in MEUP are statically assigned when participants join a space. However, during collaboration, situations arise where a participant fulfilling proposals wants to grant capabilities to the proposing participant. This enables progressive trust without requiring administrative intervention.
-
-### Current Limitations
-- Capabilities are fixed at join time
-- No way to grant capabilities dynamically
-- Proposals must continue indefinitely even for trusted operations
-- No mechanism for temporary elevation of privileges
-- Administrative burden for capability changes
-
-### Use Cases
-1. **Progressive Trust**: After successfully fulfilling many proposals, grant direct execution rights
-2. **Temporary Elevation**: Grant capabilities until explicitly revoked
-3. **Delegated Trust**: Allow trusted participants to grant capabilities
-4. **Delegation Chain**: Allow trusted participants to sub-delegate capabilities
-
-### Requirements
-- Must maintain security boundaries
-- Should support revocation
-- Must be auditable
-- Should integrate with existing capability system
-- Must prevent privilege escalation attacks
-
-## Decision
-
-**Implement Hybrid: Capability and Space Namespaces**
-
-We will use:
-- `capability/grant` - Grant capabilities to participants
-- `capability/revoke` - Revoke previously granted capabilities
-- `capability/grant-ack` - Acknowledge capability grants
-- `space/invite` - Invite new participants to the space
-- `space/kick` - Remove participants from the space
-
-This decision provides:
-- **Clear semantics**: Each namespace clearly indicates what's being operated on
-- **Logical grouping**: Capability operations together, space membership operations together
-- **No ambiguity**: `capability/` for permissions, `space/` for membership
-- **Future-proof**: Each namespace can grow independently
-
-The split recognizes two distinct concerns:
-- **Capability management**: What participants can do (`capability/*`)
-- **Space membership**: Who can participate (`space/*`)
-
-## Options Considered
-
-### Option 1: No Delegation (Status Quo)
-
-Capabilities remain static, set only at join time.
-
-**Pros:**
-- Simple security model
-- No privilege escalation risks
-- Easy to audit
-
-**Cons:**
-- No progressive trust
-- Administrative overhead
-- Inefficient proposal patterns continue
-
-### Option 2: Automatic Promotion
-
-System automatically grants capabilities based on behavior patterns.
-
-**Pros:**
-- No manual intervention
-- Progressive trust emerges naturally
-- Reduces proposal overhead over time
-
-**Cons:**
-- Complex to implement
-- Security risks from automated elevation
-- Hard to predict or control
-- Difficult to audit
-
-### Option 3: Administrative API
-
-External admin API for capability changes.
-
-**Pros:**
-- Clear separation of concerns
-- Centralized control
-- Full audit trail
-
-**Cons:**
-- Requires external intervention
-- Breaks space autonomy
-- Slower response times
-- Additional infrastructure
-
-### Option 4: Delegation Messages with Generic Lifecycle Kind
-
-Use a generic `meup.lifecycle` kind with operation field in payload.
-
-```json
-{
- "kind": "meup.lifecycle",
- "payload": {
- "operation": "grant",
- "recipient": "agent",
- "capabilities": [...]
- }
-}
-```
-
-**Pros:**
-- In-band capability management
-- Immediate effect
-- Full audit trail in space
-- Supports automation
-- Enables delegation chains
-
-**Cons:**
-- More complex security model
-- Risk of privilege escalation
-- Need careful permission design
-
-### Option 5: Delegation with MCP Namespace
-
-Use dedicated kinds in the MCP namespace for delegation.
-
-```json
-{
- "kind": "mcp.grant",
- "payload": {
- "recipient": "agent",
- "capabilities": [...]
- }
-}
-```
-
-**Pros:**
-- Consistent with ADR-v2c pattern (mcp.withdraw, mcp.reject)
-- Suggests delegation is core to MCP protocol
-- Simple routing without payload inspection
-
-**Cons:**
-- Mixes MCP operations with MEUP extensions
-- MCP namespace getting crowded
-- Delegation might not be MCP-specific
-
-### Option 6: Delegation with MEUP Namespace
-
-Use dedicated kinds in the MEUP namespace for delegation.
-
-```json
-{
- "kind": "meup.grant",
- "payload": {
- "recipient": "agent",
- "capabilities": [...]
- }
-}
-```
-
-**Pros:**
-- Clear separation: MCP for core protocol, MEUP for space management
-- Delegation is MEUP-specific feature
-- Leaves MCP namespace clean
-- Clear intent from kind alone
-
-**Cons:**
-- **Inconsistent with `chat` having no prefix**
-- Inconsistent with mcp.withdraw/reject pattern
-- Two namespaces to consider
-- More kinds to track
-
-### Option 7: No Namespace (Like Chat)
-
-Use simple kinds without namespace: `grant`, `revoke`, `invite`, `kick`
-
-**Pros:**
-- **Consistent with `chat` pattern**
-- Simplest approach
-- These are MEUP-specific anyway (not MCP)
-- Clean and minimal
-
-**Cons:**
-- Could collide with future additions
-- Less clear these are space management operations
-- No grouping indication
-
-### Option 8: Space Namespace
-
-Use `space/grant`, `space/revoke`, `space/invite`, `space/kick`
-
-**Pros:**
-- Clear these are space management operations
-- Logical grouping
-- Doesn't conflate with protocol name (MEUP)
-- Future-proof for other space operations
-
-**Cons:**
-- Introduces yet another namespace
-- Still inconsistent with `chat`
-- More to remember
-
-### Option 9: Capability Namespace
-
-Use `capability/grant`, `capability/revoke`, and plain `invite`, `kick`
-
-**Pros:**
-- Clear what grant/revoke operate on
-- Invite/kick are different (participant management)
-- Semantic clarity
-
-**Cons:**
-- Splits space management across namespaces
-- Verbose
-- Inconsistent treatment
-
-### Option 10: Admin Namespace
-
-Use `admin/grant`, `admin/revoke`, `admin/invite`, `admin/kick`
-
-**Pros:**
-- Clear these are administrative operations
-- Groups privileged operations together
-- Signals elevated permissions needed
-
-**Cons:**
-- "Admin" might not fit all use cases
-- Still introduces a namespace
-- Not all grants are "admin" level
-
-### Option 11: Smart Contracts
-
-Capability changes through programmable rules.
-
-**Pros:**
-- Flexible logic
-- Automated enforcement
-- Transparent rules
-
-**Cons:**
-- Very complex
-- Requires contract runtime
-- Hard to debug
-- Over-engineered for most uses
-
-### Option 12: Proposal-Based Delegation
-
-Instead of direct grants, use proposals for capability requests.
-
-```json
-// Agent proposes to get capability
-{
- "kind": "mcp.proposal",
- "payload": {
- "method": "capability/request",
- "params": {
- "capabilities": [...],
- "justification": "..."
- }
- }
-}
-
-// Admin fulfills by granting
-{
- "kind": "mcp.request",
- "correlationId": "proposal-123",
- "payload": {
- "method": "capability/grant",
- "params": {...}
- }
-}
-```
-
-**Pros:**
-- Uses existing proposal pattern
-- No new top-level mechanisms
-- Natural audit trail
-
-**Cons:**
-- Indirect and slower
-- Requires proposal capability
-- Less intuitive
-
-### Option 13: Hybrid Approach
-
-Combine static base capabilities with dynamic adjustments.
-
-**Pros:**
-- Best of both worlds
-- Gradual migration path
-- Fallback to static model
-
-**Cons:**
-- Two systems to manage
-- Potential confusion
-- Complex capability resolution
-
-## Comparison Matrix
-
-| Option | Complexity | Security | Flexibility | Audit | Performance | Namespace |
-|--------|------------|----------|-------------|-------|-------------|----------|
-| 1. No Delegation | Very Low | High | None | Simple | Fast | N/A |
-| 2. Automatic | High | Low | High | Hard | Medium | N/A |
-| 3. Admin API | Medium | High | Medium | Good | Slow | External |
-| 4. Generic Lifecycle | Medium | Medium | High | Good | Fast | meup |
-| 5. MCP Namespace | Low | Medium | Medium | Good | Fast | mcp |
-| 6. MEUP Namespace | Low | Medium | Medium | Good | Fast | meup |
-| 7. No Namespace | Low | Medium | Medium | Good | Fast | none |
-| 8. Space Namespace | Low | Medium | Medium | Good | Fast | space |
-| 9. Capability NS | Medium | Medium | Medium | Good | Fast | capability |
-| 10. Admin Namespace | Low | Medium | Medium | Good | Fast | admin |
-| 11. Smart Contracts | Very High | High | Very High | Excellent | Slow | Various |
-| 12. Proposal-Based | Low | High | Medium | Excellent | Medium | mcp |
-| 13. Hybrid | High | Medium | High | Good | Medium | Mixed |
-
-## Consequences
-
-### Positive
-- **Progressive Trust**: Capabilities can grow based on behavior
-- **Reduced Proposals**: Trusted operations become direct
-- **Flexible Security**: Fine-grained permission control
-- **Autonomy**: Spaces self-manage without external admin
-- **Audit Trail**: All changes tracked in space messages
-- **Automation**: Orchestrators can implement trust policies
-
-### Negative
-- **Complexity**: More complex security model
-- **Attack Surface**: Potential for privilege escalation
-- **State Management**: Gateway must track grants
-- **Revocation Challenges**: Ensuring revocation is honored
-- **Audit Overhead**: More messages to track and analyze
-
-## Security Considerations
-
-- **Privilege Escalation**: Carefully limit delegation capabilities
-- **Grant Flooding**: Rate limit grant messages
-- **Grant Abuse**: Monitor for excessive capability grants
-- **Delegation Chains**: Limit depth to prevent abuse
-- **Revocation Timing**: Ensure immediate revocation
-- **Audit Requirements**: All grants must be logged
-- **Token Leakage**: Granted capabilities shouldn't be transferable
-
-## Migration Path
-
-1. Initial implementation without delegation (current state)
-2. Add grant/revoke messages as experimental
-3. Implement grant/revoke tracking
-4. Add audit logging
-5. Enable sub-delegation with controls
-6. Deprecate unlimited static capabilities
-
-## Future Enhancements
-
-- Delegation templates for common patterns
-- Machine learning for trust scoring
-- Automatic revocation on anomaly detection
-- Capability marketplace for space templates
-- Federation of trust across spaces
-- Zero-trust progressive capability systems
-
-## Implementation Details
-
-### Message Kinds for Space Management
-
-#### Capability Delegation
-
-**Grant Message:**
-```json
-{
- "id": "grant-789", // This message ID becomes the grant_id
- "kind": "meup.grant",
- "from": "trusted-orchestrator",
- "to": ["untrusted-agent"],
- "payload": {
- "recipient": "untrusted-agent",
- "capabilities": [
- {
- "kind": "mcp.request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_file"
- }
- }
- }
- ],
- "reason": "Demonstrated safe file handling"
- }
-}
-```
-
-**Revoke Message:**
-```json
-// Option A: Revoke entire grant by ID
-{
- "kind": "meup.revoke",
- "from": "orchestrator",
- "payload": {
- "recipient": "agent",
- "grant_id": "grant-789", // Revokes all capabilities from this grant
- "reason": "Task completed"
- }
-}
-
-// Option B: Revoke by capability descriptor (pattern matching)
-{
- "kind": "meup.revoke",
- "from": "orchestrator",
- "payload": {
- "recipient": "agent",
- "capabilities": [
- {
- "kind": "mcp.request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_*" // Removes ALL matching capabilities
- }
- }
- }
- ],
- "reason": "No longer needed"
- }
-}
-```
-
-Note: When revoking by capability descriptor, the system removes ALL matching capabilities regardless of which grant(s) provided them. Uses pattern matching from ADR-q8f.
-
-**Grant Acknowledgment:**
-```json
-{
- "kind": "meup.grant-ack",
- "from": "agent",
- "correlationId": "grant-789", // References the grant message ID
- "payload": {
- "status": "accepted",
- "effective_capabilities": [ // Optional: confirms what was granted
- {
- "kind": "mcp.request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_file"
- }
- }
- }
- ]
- }
-}
-```
-
-#### Space Membership Management
-
-**Invite Message:**
-```json
-{
- "kind": "meup.invite",
- "from": "space-admin",
- "payload": {
- "participant_id": "new-agent",
- "capabilities": [
- {
- "kind": "mcp.proposal"
- },
- {
- "kind": "chat"
- }
- ],
- "role": "contributor",
- "reason": "Joining development team"
- }
-}
-```
-
-**Kick Message:**
-```json
-{
- "kind": "meup.kick",
- "from": "space-admin",
- "payload": {
- "participant_id": "misbehaving-agent",
- "reason": "Violating space policies",
- "ban_duration": "24h" // Optional: temporary ban
- }
-}
-```
-
-### Capability Requirements
-
-Using JSON pattern matching from ADR-q8f:
-
-```json
-// Can grant any capability
-{"kind": "meup.grant"}
-
-// Can revoke capabilities
-{"kind": "meup.revoke"}
-
-// Can invite participants
-{"kind": "meup.invite"}
-
-// Can remove participants
-{"kind": "meup.kick"}
-
-// Can acknowledge grants (implicit for all participants)
-{"kind": "meup.grant-ack"}
-```
-
-### Gateway Behavior
-
-1. **For capability operations (grant/revoke):**
- - Track active grants per participant with their IDs
- - Validate capability checks include granted capabilities
- - Support revocation by grant ID or specific capabilities
- - Maintain grant-to-capability mappings
- - Audit all changes with grant IDs
-
-2. **For membership operations (invite/kick):**
- - Update participant roster
- - Assign initial capabilities from invite
- - Disconnect kicked participants
- - Enforce ban durations
- - Notify other participants of membership changes
-
-### Security Rules
-
-1. **No Self-Operations**: Can't grant to yourself, can't kick yourself
-2. **Delegation Limits**: Can only grant capabilities you possess
-3. **Hierarchy Respect**: Can't kick participants with higher privileges
-4. **Audit Trail**: All operations must be logged
-5. **Revocation Rights**: Grantor can always revoke their grants
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/006-h2n-correlation-id-structure.md b/spec/archive/protocol/v0.2/decisions/accepted/006-h2n-correlation-id-structure.md
deleted file mode 100644
index 5cd2a86e..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/006-h2n-correlation-id-structure.md
+++ /dev/null
@@ -1,411 +0,0 @@
-# ADR-h2n: Correlation ID Structure
-
-**Status:** Accepted
-**Date:** 2025-09-01
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-
-## Context
-
-Currently, the MEUP specification uses a single string `correlationId` field to link related messages (responses to requests, rejections to proposals, etc.). However, there are scenarios where a message might need to correlate with multiple other messages, such as:
-
-- A response that fulfills multiple proposals
-- A reasoning conclusion that references multiple inputs
-- A grant acknowledgment that responds to multiple grant attempts
-- An aggregated result from multiple tool calls
-- A message that's part of multiple conversation threads
-
-### Current Limitations
-- Can only reference one message at a time
-- Forces artificial message chaining for multi-correlation
-- No way to express "this responds to all of these"
-- Makes it hard to track complex interaction patterns
-
-### Requirements
-- Maintain backward compatibility where possible
-- Support both single and multiple correlations
-- Keep the common case (single correlation) simple
-- Clear semantics for multiple correlations
-
-## Decision
-
-**Implement Option 2: Always Array**
-
-The `correlationId` field will always be an array of strings, even for single correlations.
-
-```json
-// Single correlation (common case)
-{
- "correlationId": ["msg-123"],
- "kind": "mcp.response"
-}
-
-// Multiple correlations
-{
- "correlationId": ["msg-123", "msg-456", "msg-789"],
- "kind": "mcp.response"
-}
-```
-
-### Rationale
-
-1. **Consistency**: One structure for all cases eliminates special-case handling
-2. **Go Compatibility**: Critical for infrastructure likely to be written in Go, which handles arrays well but struggles with union types
-3. **Signals Possibility**: Arrays immediately communicate that multiple correlations are possible
-4. **Workflow-Ready**: Natural expression of fan-in patterns and dependency sets
-5. **Minimal Overhead**: Just two extra characters (`[` and `]`) for tremendous simplification
-
-## Options Considered
-
-### Option 1: Single String (Status Quo)
-
-Keep `correlationId` as a single string field.
-
-```json
-{
- "correlationId": "msg-123",
- "kind": "mcp.request",
- "payload": {...}
-}
-```
-
-**Pros:**
-- Simple and clear
-- Already implemented
-- Covers most use cases
-- Minimal message size
-
-**Cons:**
-- Cannot express multi-correlation
-- Forces workarounds for complex patterns
-- Limited expressiveness
-
-### Option 2: Always Array
-
-Change `correlationId` to always be an array of strings.
-
-```json
-{
- "correlationId": ["msg-123"], // Single correlation
- "kind": "mcp.request",
- "payload": {...}
-}
-
-{
- "correlationId": ["msg-123", "msg-456", "msg-789"], // Multiple
- "kind": "chat",
- "payload": {"message": "Responding to all three requests"}
-}
-```
-
-**Pros:**
-- Consistent structure
-- Supports multiple correlations
-- No ambiguity about type
-
-**Cons:**
-- Breaking change
-- More verbose for common case
-- Arrays for single items feel awkward
-
-### Option 3: String or Array (Union Type)
-
-Allow `correlationId` to be either a string or an array of strings.
-
-```json
-// Single correlation (common case)
-{
- "correlationId": "msg-123",
- "kind": "mcp.request",
- "payload": {...}
-}
-
-// Multiple correlations
-{
- "correlationId": ["msg-123", "msg-456"],
- "kind": "chat",
- "payload": {"message": "Responding to both"}
-}
-```
-
-**Pros:**
-- Backward compatible
-- Simple for common case
-- Flexible for complex cases
-- Natural syntax
-
-**Cons:**
-- Type checking more complex
-- Two different structures to handle
-- Potential confusion
-
-### Option 4: Separate Fields
-
-Keep `correlationId` for single, add `correlationIds` for multiple.
-
-```json
-// Single correlation
-{
- "correlationId": "msg-123",
- "kind": "mcp.request",
- "payload": {...}
-}
-
-// Multiple correlations
-{
- "correlationIds": ["msg-123", "msg-456"],
- "kind": "chat",
- "payload": {"message": "Responding to both"}
-}
-```
-
-**Pros:**
-- Backward compatible
-- Clear intent from field name
-- Type-safe
-
-**Cons:**
-- Two fields for same concept
-- Confusion about which to use
-- What if both are present?
-
-### Option 5: Correlation Object
-
-Use an object structure for more complex correlations.
-
-```json
-// Simple correlation
-{
- "correlation": {"id": "msg-123"},
- "kind": "mcp.request",
- "payload": {...}
-}
-
-// Multiple correlations with types
-{
- "correlation": {
- "ids": ["msg-123", "msg-456"],
- "type": "fulfills" // or "responds_to", "aggregates", etc.
- },
- "kind": "mcp.request",
- "payload": {...}
-}
-```
-
-**Pros:**
-- Extensible for future needs
-- Can express correlation type
-- Rich semantics
-
-**Cons:**
-- More complex
-- Breaking change
-- Over-engineered for most uses
-
-### Option 6: Primary and Additional
-
-Keep single `correlationId` as primary, add optional `additionalCorrelations`.
-
-```json
-{
- "correlationId": "msg-123", // Primary correlation
- "additionalCorrelations": ["msg-456", "msg-789"], // Secondary
- "kind": "chat",
- "payload": {"message": "Mainly responding to first, but also others"}
-}
-```
-
-**Pros:**
-- Backward compatible
-- Preserves primary relationship
-- Clear hierarchy
-
-**Cons:**
-- Artificial distinction
-- More complex than array
-- Two fields to check
-
-### Option 7: No Correlation IDs
-
-Remove correlation IDs entirely and use context field for all relationships.
-
-```json
-{
- "context": "msg-123", // Use context for correlation
- "kind": "mcp.request",
- "payload": {...}
-}
-```
-
-**Pros:**
-- Single mechanism for relationships
-- Simpler protocol
-- Already have context field
-
-**Cons:**
-- Loses semantic distinction
-- Context has different meaning
-- Breaking change
-
-### Option 8: Keep Single, Use Message Aggregation
-
-Keep single correlation but introduce aggregation messages for multi-correlation.
-
-```json
-// Aggregation message
-{
- "id": "aggregate-1",
- "kind": "meup.aggregate",
- "payload": {
- "message_ids": ["msg-123", "msg-456", "msg-789"],
- "reason": "Batch processing"
- }
-}
-
-// Response correlates to the aggregation
-{
- "correlationId": "aggregate-1",
- "kind": "mcp.response",
- "payload": {...}
-}
-```
-
-**Pros:**
-- Backward compatible
-- Explicit aggregation semantics
-- Single correlation maintained
-
-**Cons:**
-- Extra message overhead
-- More complex pattern
-- Indirect correlation
-
-## Comparison Matrix
-
-| Option | Backward Compatible | Complexity | Flexibility | Type Safety | Common Case |
-|--------|-------------------|------------|-------------|-------------|-------------|
-| 1. Single String | Yes | Very Low | Low | High | Perfect |
-| 2. Always Array | No | Low | High | High | Verbose |
-| 3. String or Array | Yes | Medium | High | Low | Perfect |
-| 4. Separate Fields | Yes | Medium | High | Medium | Good |
-| 5. Correlation Object | No | High | Very High | High | Complex |
-| 6. Primary + Additional | Yes | Medium | High | High | Good |
-| 7. No Correlation | No | Low | Low | High | N/A |
-| 8. Aggregation | Yes | High | Medium | High | Perfect |
-
-## Consequences
-
-### Positive
-- **Type Safety**: Single type to handle in all languages
-- **Go-Friendly**: Clean implementation without type assertions
-- **Workflow Support**: Natural fan-in and aggregation patterns
-- **Clear Mental Model**: Arrays signal multi-correlation capability
-- **No Surprises**: Developers always see arrays, never encounter unexpected type changes
-- **Simple Validation**: One schema rule for all messages
-
-### Negative
-- **Breaking Change**: Existing implementations must update
-- **Slight Verbosity**: Single correlations need array syntax
-- **Migration Required**: All existing messages need updating
-
-## Security Considerations
-
-- Correlation IDs should not leak sensitive information
-- Multiple correlations could enable correlation attacks
-- Implementations must handle missing correlations gracefully
-
-## Migration Path
-
-1. **Transition Period**: Gateways temporarily accept both formats
- - If string received, convert to single-element array
- - Log deprecation warnings for string format
-
-2. **Update Generators**: Modify all message producers to emit arrays
-
-3. **Update Consumers**: Ensure all consumers handle arrays
-
-4. **Cut-over**: After transition period, reject string format
-
-5. **Helper Functions**: Provide utilities in SDKs:
- ```typescript
- // For convenience when you know it's single
- function getSingleCorrelation(msg: Message): string | undefined {
- return msg.correlationId?.[0];
- }
- ```
-
-## Future Enhancements
-
-- Correlation types (fulfills, responds_to, aggregates, etc.)
-- Correlation weights or priorities
-- Correlation metadata
-- Correlation patterns for common scenarios
-
-## Implementation Details
-
-### Type Definitions
-
-**TypeScript:**
-```typescript
-interface Message {
- correlationId?: string[];
- // ... other fields
-}
-```
-
-**Go:**
-```go
-type Message struct {
- CorrelationID []string `json:"correlationId,omitempty"`
- // ... other fields
-}
-```
-
-**Python:**
-```python
-class Message:
- correlation_id: Optional[List[str]]
-```
-
-### Validation Rules
-
-1. **Optional Field**: `correlationId` may be omitted
-2. **Empty Array**: `[]` is valid (no correlations)
-3. **Single Element**: `["msg-123"]` for single correlation
-4. **Multiple Elements**: `["msg-1", "msg-2", ...]` for multiple
-5. **Unique Elements**: Implementations SHOULD deduplicate
-6. **Order**: Arrays are unordered sets - order has no semantic meaning
-
-### Workflow Patterns
-
-**Fan-in Aggregation:**
-```json
-{
- "id": "aggregate-1",
- "correlationId": ["parallel-1", "parallel-2", "parallel-3"],
- "kind": "workflow.complete",
- "payload": {"merged_results": {...}}
-}
-```
-
-**Dependency Satisfaction:**
-```json
-{
- "id": "step-5",
- "correlationId": ["prerequisite-1", "prerequisite-2"],
- "kind": "workflow.proceed",
- "payload": {"all_dependencies_met": true}
-}
-```
-
-### Semantic Interpretation
-
-The meaning of multiple correlations depends on the message kind:
-
-- **`mcp.response`**: Fulfills all correlated requests
-- **`mcp.reject`**: Rejects all correlated proposals
-- **`meup.grant-ack`**: Acknowledges all correlated grants
-- **`workflow.*`**: Depends on workflow semantics (wait-all, wait-any, etc.)
-- **`chat`**: Responding to multiple messages in thread
-
-The correlation array provides the structure; the kind and payload provide the semantics.
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/007-j3k-property-naming-convention.md b/spec/archive/protocol/v0.2/decisions/accepted/007-j3k-property-naming-convention.md
deleted file mode 100644
index e47f310d..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/007-j3k-property-naming-convention.md
+++ /dev/null
@@ -1,268 +0,0 @@
-# ADR-j3k: Property Naming Convention
-
-**Status:** Accepted
-**Date:** 2025-09-01
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-
-## Context
-
-The current MEUP specification has inconsistent property naming conventions:
-- Some use camelCase: `correlationId`
-- Some use snake_case: `attempted_kind`, `your_capabilities`
-- The MCP protocol itself uses snake_case for JSON-RPC
-
-This inconsistency creates confusion and makes the protocol feel unpolished. We need a consistent naming convention for all JSON properties in MEUP messages.
-
-### Current State
-- Envelope fields are mixed (mostly snake_case)
-- System message payloads use snake_case
-- Capability definitions are unclear
-- No documented convention
-
-### Requirements
-- Consistency across all message types
-- Clear guidance for extensions
-- Compatibility consideration with MCP
-- Easy to implement and validate
-
-## Decision
-
-**Implement Option 4: Follow MCP exactly**
-
-MEUP will use snake_case for all JSON properties, following MCP's convention. Since MEUP extends MCP, maintaining consistency with the underlying protocol is paramount.
-
-This means:
-- All envelope fields use snake_case: `correlation_id`, `from`, `to`, `kind`
-- All system message fields use snake_case: `attempted_kind`, `your_capabilities`
-- All capability fields use snake_case: `grant_id`, `participant_id`
-- MCP payloads naturally remain snake_case
-
-Rationale:
-- MEUP extends MCP, so following MCP conventions reduces cognitive load
-- Single consistent rule throughout the entire protocol
-- No conversion needed when bridging to/from MCP
-- Eliminates any confusion about which convention to use where
-
-## Options Considered
-
-### Option 1: All snake_case
-
-Use snake_case for all properties throughout MEUP.
-
-```json
-{
- "protocol": "meup/v0.1",
- "correlation_id": ["msg-123"],
- "from_participant": "agent",
- "attempted_kind": "mcp.request",
- "your_capabilities": [...]
-}
-```
-
-**Pros:**
-- Consistent with MCP's JSON-RPC which uses snake_case
-- Python-friendly
-- Common in REST APIs
-- No conversion needed for MCP payloads
-
-**Cons:**
-- Less common in JavaScript/TypeScript ecosystems
-- Differs from many web standards
-
-### Option 2: All camelCase
-
-Use camelCase for all properties throughout MEUP.
-
-```json
-{
- "protocol": "meup/v0.1",
- "correlationId": ["msg-123"],
- "fromParticipant": "agent",
- "attemptedKind": "mcp.request",
- "yourCapabilities": [...]
-}
-```
-
-**Pros:**
-- JavaScript/TypeScript native convention
-- Common in modern web APIs
-- Familiar to web developers
-- Clean appearance
-
-**Cons:**
-- Inconsistent with MCP's snake_case
-- Would need conversion for MCP payloads
-- Less Python-friendly
-
-### Option 3: Mixed - Envelope camelCase, Payloads preserve format
-
-Use camelCase for MEUP envelope fields, preserve original format in payloads.
-
-```json
-{
- "protocol": "meup/v0.1",
- "correlationId": ["msg-123"],
- "kind": "mcp.request",
- "payload": {
- // MCP payload keeps snake_case
- "json_rpc": "2.0",
- "method": "tools/call",
- "params": {
- "tool_name": "read_file"
- }
- }
-}
-```
-
-**Pros:**
-- MEUP fields use modern convention
-- MCP compatibility preserved
-- Clear boundary between protocols
-- No payload transformation needed
-
-**Cons:**
-- Two conventions in one message
-- Potential confusion at boundaries
-- Need clear documentation
-
-### Option 4: Follow MCP exactly
-
-Since MEUP extends MCP, follow MCP's snake_case convention everywhere.
-
-**Pros:**
-- Maximum consistency with MCP
-- Single convention throughout
-- No confusion about which to use
-
-**Cons:**
-- MCP isn't fully consistent itself
-- Less appealing to JavaScript developers
-- Perpetuates any MCP inconsistencies
-
-### Option 5: Context-based
-
-- MEUP-specific fields: camelCase
-- MCP-related fields: snake_case
-- System messages: snake_case
-
-**Pros:**
-- Semantic grouping
-- Preserves compatibility
-- Indicates field origin
-
-**Cons:**
-- Most complex rule
-- Hard to remember
-- Requires constant context awareness
-
-## Comparison Matrix
-
-| Option | Consistency | MCP Compatibility | Developer Experience | Implementation |
-|--------|------------|-------------------|---------------------|----------------|
-| 1. All snake_case | High | Perfect | Good (Python), OK (JS) | Simple |
-| 2. All camelCase | High | Poor | Good (JS), OK (Python) | Simple |
-| 3. Mixed by layer | Medium | Good | OK | Medium |
-| 4. Follow MCP | High | Perfect | Same as MCP | Simple |
-| 5. Context-based | Low | Good | Confusing | Complex |
-
-## Examples
-
-### Critical Fields to Standardize
-
-Regardless of choice, these fields need consistent naming:
-
-**Envelope fields:**
-- correlation_id / correlationId
-- from / fromParticipant
-- to / toParticipants
-
-**System message fields:**
-- attempted_kind / attemptedKind
-- your_capabilities / yourCapabilities
-- grant_id / grantId
-- participant_id / participantId
-- ban_duration / banDuration
-
-**Capability fields:**
-- allow_sub_delegation / allowSubDelegation
-- usage_count / usageCount
-- expires_at / expiresAt
-
-## Consequences
-
-### Positive
-- **Maximum consistency** with MCP protocol
-- **Single rule** - always use snake_case
-- **No conversion** needed for MCP payloads
-- **Clear convention** - no ambiguity
-- **Python-friendly** - natural for Python implementations
-- **REST API standard** - familiar to many developers
-
-### Negative
-- **Less JavaScript-idiomatic** - JS/TS developers prefer camelCase
-- **Perpetuates MCP choices** - even if suboptimal
-- **Framework friction** - some JS frameworks expect camelCase
-
-## Security Considerations
-
-- Property names shouldn't leak implementation details
-- Consistent naming reduces parsing errors
-- Clear conventions prevent injection attacks via property names
-
-## Migration Path
-
-1. Update all MEUP specification examples to use snake_case
-2. Fix any camelCase properties currently in the spec:
- - Change `correlationId` to `correlation_id`
- - Already correct: `attempted_kind`, `your_capabilities`
-3. Update all implementation code
-4. Provide migration guide for early adopters
-5. Add linting rules to enforce snake_case
-
-## Future Enhancements
-
-- Linting rules for property names
-- Automatic conversion utilities
-- Schema validation for naming conventions
-
-## Implementation Details
-
-### Standard Field Names
-
-**Envelope fields:**
-```json
-{
- "protocol": "meup/v0.1",
- "id": "msg-123",
- "ts": "2025-09-01T12:00:00Z",
- "from": "participant-1",
- "to": ["participant-2"],
- "kind": "mcp.request",
- "correlation_id": ["msg-456"],
- "context": "ctx-789",
- "payload": {}
-}
-```
-
-**System message fields:**
-```json
-{
- "attempted_kind": "mcp.request",
- "your_capabilities": [...],
- "grant_id": "grant-123",
- "participant_id": "agent-1",
- "ban_duration": "24h",
- "allow_sub_delegation": true,
- "usage_count": 10,
- "expires_at": "2025-12-31T23:59:59Z"
-}
-```
-
-### Validation
-
-Implementations SHOULD validate that all property names:
-- Use lowercase letters, numbers, and underscores only
-- Start with a letter
-- Use underscores to separate words
-- Match pattern: `^[a-z][a-z0-9_]*$`
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/008-n5r-protocol-kind-separator.md b/spec/archive/protocol/v0.2/decisions/accepted/008-n5r-protocol-kind-separator.md
deleted file mode 100644
index 70caa466..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/008-n5r-protocol-kind-separator.md
+++ /dev/null
@@ -1,208 +0,0 @@
-# ADR-n5r: Protocol-Kind Separator Convention
-
-**Status:** Accepted
-**Date:** 2025-09-03
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Complete
-**Related ADRs:** 002-0-m3p (Namespace Pattern)
-
-## Context
-
-In ADR-m3p, we established minimal kinds for message types (e.g., `mcp.request` instead of `mcp/request:tools/call`). However, we inconsistently used dot notation for the separator between protocol namespace and kind (e.g., `mcp.request`, `meup.grant`).
-
-MCP itself uses slash notation in its JSON-RPC methods (e.g., `tools/call`, `resources/read`). We should align with this established convention for consistency.
-
-### Current State
-- Using dot notation: `mcp.request`, `meup.grant`, `system.error`
-- MCP uses slash: `tools/call`, `resources/read`, `prompts/list`
-
-### Requirements
-- Consistency with MCP conventions
-- Clear visual separation between namespace and operation
-- Easy to parse and understand
-- Maintain minimal kind philosophy from ADR-m3p
-
-## Decision
-
-**Adopt slash notation between protocol namespace and kind**
-
-All message kinds will use slash notation to separate the protocol namespace from the operation:
-- `mcp/request` instead of `mcp.request`
-- `meup/grant` instead of `meup.grant`
-- `system/error` instead of `system.error`
-
-This aligns with MCP's existing convention and provides clear visual separation between namespace and operation.
-
-## Options Considered
-
-### Option 1: Keep Dot Notation (Status Quo)
-
-Continue using dots: `mcp.request`, `meup.grant`, `system.error`
-
-**Pros:**
-- Already implemented in current spec
-- Common in many programming languages
-- Single separator throughout
-
-**Cons:**
-- Inconsistent with MCP's slash convention
-- Less visual distinction between namespace and operation
-- Dots often imply property access rather than categorization
-
-### Option 2: Slash Notation (Recommended)
-
-Use slashes: `mcp/request`, `meup/grant`, `system/error`
-
-**Pros:**
-- **Consistent with MCP's existing convention** (`tools/call`, `resources/read`)
-- Clear visual separation between namespace and operation
-- Slashes commonly indicate categorization/hierarchy
-- Aligns with URI/URL path conventions
-
-**Cons:**
-- Requires updating current spec
-- Different from some programming language conventions
-
-### Option 3: Colon Notation
-
-Use colons: `mcp:request`, `meup:grant`, `system:error`
-
-**Pros:**
-- Clear namespace separation
-- Used in XML namespaces
-- Distinct from other separators
-
-**Cons:**
-- Not used by MCP
-- Less common in modern APIs
-- Could be confused with port notation
-
-### Option 4: Double Colon
-
-Use double colons: `mcp::request`, `meup::grant`, `system::error`
-
-**Pros:**
-- Very clear separation
-- Used in some programming languages (C++, Rust)
-- Unlikely to conflict
-
-**Cons:**
-- Verbose
-- Not used by MCP
-- Uncommon in protocols
-
-## Comparison Matrix
-
-| Option | MCP Consistency | Visual Clarity | Familiarity | Parse Simplicity |
-|--------|----------------|----------------|-------------|------------------|
-| 1. Dot | Poor | Medium | High | High |
-| 2. Slash | **Excellent** | **High** | **High** | **High** |
-| 3. Colon | Poor | High | Medium | High |
-| 4. Double Colon | Poor | Very High | Low | Medium |
-
-## Implementation Examples
-
-### Before (Dot Notation)
-```json
-{
- "kind": "mcp.request",
- "payload": { "method": "tools/call" }
-}
-
-{
- "kind": "meup.grant",
- "payload": { "capabilities": [...] }
-}
-
-{
- "kind": "system.error",
- "payload": { "error": "capability_violation" }
-}
-```
-
-### After (Slash Notation)
-```json
-{
- "kind": "mcp/request",
- "payload": { "method": "tools/call" }
-}
-
-{
- "kind": "meup/grant",
- "payload": { "capabilities": [...] }
-}
-
-{
- "kind": "system/error",
- "payload": { "error": "capability_violation" }
-}
-```
-
-## Complete Kind List with Slash Notation
-
-**MCP namespace:**
-- `mcp/request` - MCP request/notification
-- `mcp/response` - MCP response
-- `mcp/proposal` - MCP proposal for operations
-- `mcp/withdraw` - Withdraw a proposal
-- `mcp/reject` - Reject a proposal
-
-**MEUP namespace:**
-- `meup/grant` - Grant capabilities
-- `meup/revoke` - Revoke capabilities
-- `meup/grant-ack` - Acknowledge grant
-- `meup/invite` - Invite participant
-- `meup/kick` - Remove participant
-
-**Reasoning namespace:**
-- `reasoning/start` - Begin reasoning
-- `reasoning/thought` - Reasoning step
-- `reasoning/conclusion` - End reasoning
-
-**System namespace:**
-- `system/welcome` - Welcome message
-- `system/presence` - Join/leave events
-- `system/error` - Error messages
-
-**No namespace:**
-- `chat` - Chat messages (no namespace needed)
-
-## Consequences
-
-### Positive
-- **Consistency** with MCP's established conventions
-- **Clear separation** between namespace and operation
-- **Familiar pattern** from URLs and file paths
-- **Visual hierarchy** is immediately apparent
-- **Future proof** for sub-namespacing if needed (e.g., `mcp/tools/call`)
-
-### Negative
-- **Breaking change** from current spec
-- **Migration required** for any implementations
-- **Documentation updates** needed throughout
-
-## Security Considerations
-
-- No security impact from separator choice
-- Pattern matching for capabilities remains unchanged
-- Reserved namespace enforcement unchanged
-
-## Migration Path
-
-1. Update all ADRs to use slash notation
-2. Update SPEC.md with slash notation throughout
-3. Update capability matching examples
-4. Update any implementation code
-5. Document as breaking change in v0.2
-
-## Future Considerations
-
-- Slash notation naturally extends to sub-namespaces if needed
-- Could support hierarchical kinds like `mcp/tools/call` if we ever need more specificity
-- Aligns with potential REST API mappings
-
-## References
-
-- MCP Specification (uses `tools/call`, `resources/read`, etc.)
-- ADR-m3p (Minimal Kind pattern)
-- URI/URL specifications (use slash for hierarchy)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/accepted/README.md b/spec/archive/protocol/v0.2/decisions/accepted/README.md
deleted file mode 100644
index 7764433f..00000000
--- a/spec/archive/protocol/v0.2/decisions/accepted/README.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# Accepted ADRs
-
-This folder contains ADRs that have been reviewed and accepted for implementation.
-
-## Format
-
-**Filename:** `[proposal-number]-[adr-id]-[descriptive-name].md`
-
-- **Proposal number:** Maintains the original number from when it was proposed
-- **ADR ID:** The same unique identifier from the proposal stage
-- **Descriptive name:** Same descriptive name from proposal
-
-## Status Tracking
-
-Each accepted ADR should have:
-- **Status:** "Accepted"
-- **Incorporation:** Track implementation progress
- - "Not Incorporated" - Accepted but not yet in spec
- - "Partial" - Some aspects implemented
- - "Complete" - Fully incorporated into specification
-
-## Currently Accepted
-
-All ADRs have been accepted and fully incorporated into the MEUP specification:
-
-- `001-0-x7k-protocol-name.md` - Protocol naming (chose MEUP)
-- `001-1-y3m-communication-space-terminology.md` - Terminology for communication spaces (chose "space")
-- `002-0-m3p-namespace-pattern.md` - Message kind namespace patterns (chose Option 7: Minimal Kind)
-- `002-1-q8f-capability-definitions.md` - Capability definition conventions (chose Option 1: JSON Pattern Matching)
-- `003-v2c-proposal-lifecycle-management.md` - Proposal lifecycle extensions (withdraw/reject)
-- `004-0-t8k-agent-reasoning-transparency.md` - Agent reasoning transparency through sub-contexts
-- `004-1-k9j-sub-context-protocol-mechanics.md` - Protocol mechanics for implementing sub-contexts
-- `004-2-p4m-context-field-structure.md` - Context field structure and patterns
-- `005-g7r-capability-delegation.md` - Dynamic capability delegation and grants (chose capability/* and space/* namespaces)
-- `006-h2n-correlation-id-structure.md` - Correlation ID as array of strings (chose Option 2: Always Array)
-- `007-j3k-property-naming-convention.md` - Property naming convention (chose Option 4: Follow MCP with snake_case)
-- `008-n5r-protocol-kind-separator.md` - Protocol-kind separator convention (chose slash notation)
-
-## Moving from Proposed
-
-When an ADR is accepted:
-1. Move file from `proposed/` to `accepted/`
-2. Keep the same filename (preserves proposal order)
-3. Update Status to "Accepted"
-4. Track Incorporation status as implementation progresses
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/proposed/README.md b/spec/archive/protocol/v0.2/decisions/proposed/README.md
deleted file mode 100644
index 48fe65a8..00000000
--- a/spec/archive/protocol/v0.2/decisions/proposed/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Proposed ADRs
-
-This folder contains ADRs (Architecture Decision Records) that are currently under consideration.
-
-## Format
-
-**Filename:** `[proposal-number]-[adr-id]-[descriptive-name].md`
-
-- **Proposal number:** Sequential number based on order of proposal (001, 002, etc.)
-- **ADR ID:** Unique 3-character alphanumeric identifier (e.g., x7k, m3p)
-- **Descriptive name:** Kebab-case description of the decision
-
-## Current Proposals
-
-(Currently empty - all ADRs have been accepted and incorporated into the specification)
-
-## Process
-
-1. Create new ADR with next sequential number and unique ID
-2. Status should be "Proposed"
-3. Incorporation should be "Not Incorporated"
-4. Follow the ADR template in `/protocol-spec/CLAUDE.md`
-5. After review, ADR moves to either `accepted/` or `rejected/`
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/001-d4n-space-configuration.md b/spec/archive/protocol/v0.2/decisions/rejected/001-d4n-space-configuration.md
deleted file mode 100644
index bc94b818..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/001-d4n-space-configuration.md
+++ /dev/null
@@ -1,449 +0,0 @@
-# ADR-d4n: Space Configuration Specification
-
-**Status:** Rejected
-**Date:** 2025-08-31
-**Context:** MEUP Protocol Draft Specification
-**Incorporation:** Not Incorporated
-**Rejection Rationale:** Configuration format is implementation-specific, not part of the wire protocol. This ADR will be applied to future CLI implementation rather than the protocol specification itself.
-**Parent ADR:** 001-1-y3m (Communication Space Terminology)
-**Related ADRs:** 002-1-q8f (Capability Definition Conventions)
-
-## Context
-
-Currently, the protocol assumes loose authorization where tokens work across any space. This lacks explicit configuration for space participants, their capabilities, and connection methods. We need a declarative way to configure spaces that:
-- Defines who can participate
-- Specifies participant capabilities
-- Supports different connection types (local processes, remote endpoints, access keys)
-- Handles protocol bridging for non-MEUP participants
-- Provides reproducible space environments
-
-Similar to how Docker Compose defines multi-container applications, or how MCP servers are configured in coding agents, spaces need explicit configuration files.
-
-### Decision Drivers
-- Need for explicit, reproducible space configurations
-- Support for heterogeneous participant types
-- Security through explicit capability assignment
-- Ease of space deployment and management
-- Support for protocol bridging (MCP, A2A, MEUP)
-
-## Decision
-
-**Adopt YAML-based space configuration files**
-
-Spaces are configured through a `space.yaml` file (or similar) that declaratively specifies participants, their capabilities, connection methods, and protocols. This provides explicit, version-controlled space definitions.
-
-**Note:** The exact configuration structure and field names shown in this ADR are illustrative examples. This ADR should be incorporated last, after other foundational ADRs have stabilized. The final design will be refined during incorporation into the specification, with particular attention to:
-- Consistency with the capability format from ADR-q8f
-- Clear distinction between native and bridged participants
-- Proper separation of protocol-specific details
-- Validation and error handling requirements
-- Integration with decisions from other ADRs (namespace patterns, lifecycle management, etc.)
-
-## Options Considered
-
-### Option 1: No Configuration (Status Quo)
-
-Continue with dynamic, token-based authorization without explicit configuration.
-
-**Pros:**
-- Maximum flexibility
-- No configuration overhead
-- Dynamic participant joining
-
-**Cons:**
-- No reproducibility
-- Unclear space boundaries
-- Hard to audit/review
-- No explicit capability management
-
-### Option 2: YAML Configuration Files (Recommended)
-
-Use YAML files similar to docker-compose.yml for space configuration.
-
-**Pros:**
-- Declarative and version-controllable
-- Familiar pattern from Docker/Kubernetes
-- Human-readable and editable
-- Supports comments and documentation
-- Explicit capability management
-
-**Cons:**
-- YAML parsing complexity
-- Potential for configuration errors
-- Less dynamic than pure token-based
-
-### Option 3: JSON Configuration
-
-Use JSON for space configuration.
-
-**Pros:**
-- Native to JavaScript/TypeScript
-- No parsing ambiguity
-- Direct object mapping
-
-**Cons:**
-- Less human-friendly
-- No comments support
-- More verbose than YAML
-
-### Option 4: Code-Based Configuration
-
-Use programming language (TypeScript/Python) for configuration.
-
-**Pros:**
-- Full programming power
-- Type safety possible
-- Dynamic configuration
-
-**Cons:**
-- Not declarative
-- Requires code execution
-- Harder to validate/audit
-
-## Implementation Details
-
-**Important:** The configuration examples below are illustrative and will be refined during specification incorporation. The goal is to establish the pattern of declarative YAML configuration; exact field names, structure, and semantics will be finalized based on implementation experience and community feedback.
-
-### Capability Format
-
-Capabilities use the JSON pattern matching format defined in ADR-q8f. They can be:
-- Simple strings for basic message types: `kind: "chat"`
-- Complex patterns with payload inspection:
- ```yaml
- kind: "mcp.request"
- payload:
- method: "tools/*"
- params:
- name: "read_*"
- ```
-
-### Space Configuration Structure (Illustrative Example)
-
-```yaml
-# space.yaml
-version: "1.0"
-name: "code-review-space"
-description: "Space for collaborative code review with security scanning"
-
-# Space-level settings
-settings:
- max_participants: 10
- message_retention: "24h"
- context_depth_limit: 5
-
-# Participant definitions
-# Note: Participants that provide tools/resources typically have response capabilities,
-# while those that use tools have request capabilities
-participants:
- # Human user with access key
- human-reviewer:
- type: key
- description: "Human code reviewer"
- capabilities:
- - kind: "*" # Full access to all message types (can request and respond)
-
- # Local process (MEUP native)
- security-scanner:
- type: local
- command: "./security-scanner"
- args: ["--mode", "aggressive"]
- env:
- SCAN_LEVEL: "high"
- protocol: meup # Native MEUP participant
- capabilities:
- - kind: "meup.proposal"
- - kind: "meup.response"
- - kind: "chat"
-
- # Remote MCP server (needs bridge)
- mcp-file-editor:
- type: remote
- url: "https://mcp-server.example.com/file-editor"
- protocol: mcp
- bridge:
- enabled: true
- image: "@meup/mcp-bridge:latest"
- # These are the MEUP capabilities this MCP server provides via bridge
- capabilities:
- - kind: "mcp.response" # Can respond to requests
- # MCP tools this server exposes (bridge handles translation)
- mcp_tools:
- - "read_file"
- - "write_file"
-
- # Remote A2A agent (needs bridge)
- a2a-analyzer:
- type: remote
- url: "wss://a2a-agent.example.com/analyzer"
- protocol: a2a
- bridge:
- enabled: true
- image: "@meup/a2a-bridge:latest"
- capabilities:
- - kind: "meup.proposal"
- - kind: "chat"
-
- # GitHub integration (native MEUP bridge)
- github-integration:
- type: local
- command: "@meup/github-bridge"
- args: ["--repo", "${GITHUB_REPO}"]
- protocol: meup # Bridge speaks native MEUP
- capabilities:
- - kind: "meup.response" # Can respond to requests
- # This bridge provides these tools to the space
- provides_tools:
- - "create_pr"
- - "comment"
- - "get_pr_status"
-
- # Workflow engine with arbitrary configuration
- workflow-orchestrator:
- type: local
- command: "@meup/workflow-engine"
- protocol: meup
- capabilities:
- - kind: "*" # Full capabilities to orchestrate
- # Arbitrary configuration passed to the participant
- config:
- engine: "dagster"
- workflow:
- name: "code-review-pipeline"
- steps:
- - id: "security-scan"
- type: "parallel"
- agents: ["security-scanner"]
- timeout: 300
- - id: "style-check"
- type: "sequential"
- agents: ["linter", "formatter"]
- - id: "approval"
- type: "human-in-loop"
- require_all: false
- triggers:
- - type: "on_message"
- pattern: "pr:opened"
- error_handling:
- retry_count: 3
- fallback: "manual-review"
- runtime:
- max_parallel_tasks: 5
- checkpoint_interval: "10m"
- state_backend: "redis://localhost:6379"
-
-# Access keys for external participants
-access_keys:
- - id: "reviewer-key-1"
- participant: "human-reviewer"
- expires: "2025-12-31T23:59:59Z"
- - id: "ci-system-key"
- participant: "ci-agent"
- capabilities:
- - kind: "mcp.request"
- payload:
- method: "tools/call"
- params:
- name: "run_tests"
- - kind: "meup.response" # Can respond in MEUP protocol
- - kind: "chat"
-
-# Bridge configurations
-bridges:
- mcp:
- default_image: "@meup/mcp-bridge:latest"
- config:
- timeout: 30000
- retry_attempts: 3
- a2a:
- default_image: "@meup/a2a-bridge:latest"
- config:
- task_timeout: 60000
-```
-
-### Participant Types
-
-#### 1. Local Process (`type: local`)
-- Spawned as subprocess
-- Can be MEUP native or use bridge
-- Supports command, args, environment variables
-- Accepts arbitrary `config` object passed to participant
-
-#### 2. Remote Endpoint (`type: remote`)
-- Connects to external service
-- Requires protocol specification
-- Bridge automatically configured if non-MEUP
-- Accepts arbitrary `config` object for service configuration
-
-#### 3. Access Key (`type: key`)
-- Generates joinable access tokens
-- Can be distributed to users/systems
-- Supports expiration and capability limits
-
-### Arbitrary Participant Configuration
-
-Any participant can include a `config` field containing arbitrary YAML/JSON that is passed directly to the participant at startup. This enables:
-
-1. **Workflow Engines**: Complete workflow DAG definitions
-2. **AI Agents**: Model parameters, prompts, temperature settings
-3. **Tool Servers**: Database connections, API keys, feature flags
-4. **Custom Services**: Any domain-specific configuration
-
-Example configurations:
-
-```yaml
-# AI Agent with model configuration
-ai-assistant:
- type: local
- command: "ai-agent"
- config:
- model: "gpt-4"
- temperature: 0.7
- system_prompt: "You are a helpful code reviewer"
- tools_enabled: ["search", "explain", "suggest"]
- max_tokens: 4000
-
-# Database bridge with connection config
-database-bridge:
- type: local
- command: "@meup/sql-bridge"
- config:
- connection:
- host: "${DB_HOST}"
- port: 5432
- database: "code_review"
- credentials_secret: "db-creds"
- query_timeout: 30000
- allowed_operations: ["SELECT", "INSERT"]
-
-# Custom analytics engine
-analytics-engine:
- type: remote
- url: "https://analytics.internal"
- config:
- metrics:
- - type: "code_complexity"
- threshold: 10
- - type: "test_coverage"
- minimum: 80
- reporting:
- format: "json"
- destination: "s3://reports/bucket"
-```
-
-The `config` field is:
-- Passed as-is to the participant on startup
-- Can be any valid YAML structure
-- Supports environment variable substitution
-- Participant-specific (gateway doesn't interpret it)
-- Enables "participant as a service" pattern
-
-### Protocol Bridging
-
-When `protocol` is not `meup`, a bridge agent is automatically provisioned:
-
-```yaml
-participant:
- type: remote
- protocol: mcp # or 'a2a'
- bridge:
- enabled: true
- image: "@meup/mcp-bridge:latest" # Bridge container/process
- config:
- # Bridge-specific configuration
-```
-
-The bridge agent:
-- Translates between MEUP and target protocol
-- Maintains protocol-specific connections
-- Maps capabilities to protocol-specific operations
-- Handles message transformation
-
-### Capability Mapping for Bridges
-
-Bridge agents translate MEUP JSON pattern capabilities to protocol-specific operations. The bridge inspects the capability patterns and maps them accordingly.
-
-MCP Bridge Example:
-```yaml
-# Bridge automatically translates JSON patterns to MCP operations
-# For example, this MEUP capability:
-meup_capability:
- kind: "mcp.request"
- payload:
- method: "tools/call"
- params:
- name: "read_*"
-
-# Maps to MCP tools matching the pattern
-mcp_operations: ["read_file", "read_config", "read_logs"]
-```
-
-### Space Lifecycle
-
-```bash
-# Start space from configuration
-meup space start ./space.yaml
-
-# List running spaces
-meup space list
-
-# Show space participants and status
-meup space status code-review-space
-
-# Stop space
-meup space stop code-review-space
-
-# Validate configuration
-meup space validate ./space.yaml
-```
-
-### Environment Variable Substitution
-
-Support environment variables in configuration:
-
-```yaml
-participant:
- type: remote
- url: "${API_ENDPOINT}"
- auth:
- token: "${API_TOKEN}"
-```
-
-## Consequences
-
-### Positive
-- **Explicit Configuration**: Clear, auditable space definitions
-- **Reproducibility**: Spaces can be recreated exactly
-- **Protocol Agnostic**: Supports MCP, A2A, MEUP participants
-- **Version Control**: Configuration files can be tracked
-- **Security**: Explicit capability assignment
-- **Automation**: Spaces can be programmatically deployed
-
-### Negative
-- **Less Dynamic**: Requires configuration before use
-- **Complexity**: More complex than simple token auth
-- **Bridge Overhead**: Non-MEUP participants need bridges
-- **Configuration Management**: Another file to maintain
-
-## Security Considerations
-
-- Access keys must be securely generated and stored
-- Configuration files may contain sensitive data (use env vars)
-- Bridge agents have elevated privileges (protocol translation)
-- Capability validation must be enforced
-- Remote endpoints need authentication
-
-## Migration Path
-
-1. Start with optional configuration (fallback to current behavior)
-2. Provide configuration generators from existing setups
-3. Gradually require configuration for new spaces
-4. Deprecate unconfigured spaces in future version
-
-## Future Enhancements
-
-- Space templates for common scenarios
-- Configuration inheritance/composition
-- Dynamic participant addition with approval
-- Hot-reload of configuration changes
-- Integration with orchestration platforms (K8s, Docker Compose)
-- GUI configuration builders
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/001-h9j-pod-discovery-and-hub-architecture.md b/spec/archive/protocol/v0.2/decisions/rejected/001-h9j-pod-discovery-and-hub-architecture.md
deleted file mode 100644
index 3896b2b6..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/001-h9j-pod-discovery-and-hub-architecture.md
+++ /dev/null
@@ -1,240 +0,0 @@
-# ADR-h9j: Pod Discovery and Hub Architecture
-
-**Status:** Rejected
-**Date:** 2025-08-30
-**Context:** MECP Protocol Draft Specification
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-08-31
-**Rejection Reason:** Out of scope for initial version. Pod configuration (ADR-d4n) provides a different approach that needs to mature first. Some aspects may be addressed by reasoning transparency (ADR-t8k).
-
-## Context
-
-A hub hosts multiple pods where participants collaborate. When a participant connects to a hub, they need a way to:
-- Discover what pods exist on the hub
-- Understand what each pod is for
-- Request access to pods they're interested in
-- Create new pods if authorized
-
-This creates a fundamental discoverability problem: how do participants learn about and access pods on a hub?
-
-The solution must:
-- Work within the existing MCPx protocol design
-- Maintain stateless gateway architecture
-- Avoid special protocol extensions
-- Support varying levels of access control
-- Enable different hub implementations
-
-## Options Considered
-
-### Option 1: Special Discovery Protocol
-
-Add dedicated protocol messages for pod discovery (pod/list, pod/join, pod/create).
-
-**Pros:**
-- Purpose-built for discovery
-- Clear protocol semantics
-- Standardized across all hubs
-
-**Cons:**
-- Adds complexity to core protocol
-- Special cases in message handling
-- Not using MCP's existing capabilities
-- More protocol surface area to maintain
-
-### Option 2: Direct Pod Connection
-
-Participants connect directly to known pod URLs without discovery.
-
-**Pros:**
-- Simple - no discovery needed
-- No special infrastructure
-- Direct access path
-
-**Cons:**
-- No way to discover available pods
-- Requires out-of-band pod URL sharing
-- No central access control point
-- Poor user experience
-
-### Option 3: Lobby Pod with Hub Agent
-
-Create a special "lobby" pod that all participants join first, containing a hub agent that exposes MCP tools for discovery and management.
-
-**Pros:**
-- Uses standard MCP tools - no protocol extensions
-- Dogfooding - hub uses its own protocol
-- Flexible - different hubs can offer different tools
-- Natural entry point metaphor
-- Discoverable via standard MCP tool introspection
-
-**Cons:**
-- Requires hub agent implementation
-- Adds a layer of indirection
-- Lobby pod becomes special case
-
-### Option 4: System Messages Only
-
-Use system messages in each pod to announce other pods.
-
-**Pros:**
-- No special components needed
-- Works with existing protocol
-
-**Cons:**
-- No interactive discovery
-- Can't query for specific pods
-- No way to request access
-- Limited to broadcast information
-
-## Decision
-
-**Adopt Option 3: Lobby Pod with Hub Agent**
-
-The lobby pod pattern with a hub agent exposing MCP tools provides the best balance of simplicity, flexibility, and functionality.
-
-### Hub Architecture
-
-```
-Hub (ws://hub.example.com)
-├── /lobby # Entry pod with hub agent
-├── /podA # Application pod
-├── /podA/subpod1 # Nested pod
-└── /podB # Another application pod
-```
-
-### Terminology
-
-- **Hub**: Server infrastructure hosting multiple pods
-- **Pod**: Isolated collaboration space within a hub
-- **Lobby**: Special pod serving as hub entry point
-- **Hub Agent**: MCP server in lobby pod exposing discovery and management tools
-
-### Hub Agent MCP Tools
-
-The hub agent SHOULD expose tools like:
-
-```typescript
-{
- "list_pods": {
- "description": "List available pods on this hub",
- "parameters": {
- "filter": "string" // Optional filter pattern
- }
- },
- "get_pod_info": {
- "description": "Get metadata about a specific pod",
- "parameters": {
- "pod_id": "string"
- }
- },
- "request_access": {
- "description": "Request access to a pod",
- "parameters": {
- "pod_id": "string",
- "token": "string" // Optional auth token
- }
- },
- "create_pod": {
- "description": "Create a new pod on this hub",
- "parameters": {
- "name": "string",
- "config": "object" // Optional configuration
- }
- }
-}
-```
-
-### Discovery Flow
-
-1. **Connect**: Participant connects to hub WebSocket
-2. **Join Lobby**: Automatically placed in `/lobby` pod
-3. **Discover Tools**: Standard MCP tool discovery from hub agent
-4. **List Pods**: Call `list_pods` tool to see available pods
-5. **Request Access**: Call `request_access` for desired pod
-6. **Join Pod**: Connect to pod-specific WebSocket if granted
-
-### Example: Discovering Pods
-
-```json
-// Request
-{
- "jsonrpc": "2.0",
- "method": "tools/call",
- "params": {
- "name": "list_pods",
- "arguments": {}
- },
- "id": "disc-1"
-}
-
-// Response
-{
- "jsonrpc": "2.0",
- "result": {
- "pods": [
- {
- "id": "/podA",
- "name": "Development Team",
- "description": "Main development coordination",
- "members": 5,
- "public": true
- },
- {
- "id": "/podB",
- "name": "Testing",
- "description": "QA and testing discussions",
- "members": 3,
- "public": false
- }
- ]
- },
- "id": "disc-1"
-}
-```
-
-### Implementation Flexibility
-
-- Hubs MAY provide a lobby pod (recommended but not required)
-- Lobby pods CAN contain hub agents with varying tool sets
-- Hub agents SHOULD expose standard discovery tools
-- Different hubs MAY offer different capabilities
-- Hubs without lobby pods must provide alternative discovery mechanisms
-
-### Benefits
-
-1. **Protocol Simplicity**: No special discovery protocol needed
-2. **Dogfooding**: Hub operations use MCP itself
-3. **Flexibility**: Each hub can customize its tools
-4. **Discoverability**: Standard MCP tool introspection
-5. **Extensibility**: Add new hub features by adding tools
-6. **Compatibility**: Works with existing MCP clients
-
-## Consequences
-
-### Positive
-- Clean separation between protocol and hub operations
-- Hub features can evolve independently of protocol
-- Natural entry point for new participants
-- Supports both public and private pod models
-
-### Negative
-- Requires hub agent implementation
-- Lobby pod is a special case
-- Additional hop for pod access
-- Dependency on MCP tool discovery working properly
-
-## Security Considerations
-
-- Hub agent validates all access requests
-- Token-based authentication for pod access
-- Rate limiting on tool calls
-- Audit logging of access decisions
-- Gateway remains stateless - auth handled by agents
-
-## Migration Path
-
-For existing implementations:
-1. Add lobby pod to hub configuration
-2. Implement hub agent with basic tools
-3. Update client connection flow
-4. Maintain backward compatibility during transition
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/002-a3j-request-cancellation-mechanism.md b/spec/archive/protocol/v0.2/decisions/rejected/002-a3j-request-cancellation-mechanism.md
deleted file mode 100644
index 47b2e446..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/002-a3j-request-cancellation-mechanism.md
+++ /dev/null
@@ -1,151 +0,0 @@
-# ADR-001: Request Cancellation Mechanism
-
-**Status:** Resolved
-**Date:** 2025-08-30
-**Context:** MCPx Protocol Draft Specification
-
-## Context
-
-MCP specification 2025-06-18 already defines cancellation through `notifications/cancelled` messages. MCPx needs to determine how to handle these MCP cancellation messages within its envelope-based routing system.
-
-The MCP cancellation mechanism:
-- Uses `notifications/cancelled` with a `requestId` parameter
-- Is a fire-and-forget notification (no response expected)
-- Can include an optional reason string
-- Handles race conditions gracefully
-
-## Decision Drivers
-
-- Alignment with existing MCP specification
-- Maintaining protocol compatibility
-- Proper routing of cancellation notifications in multi-participant environments
-- Correlation ID tracking across the MCPx envelope system
-
-## Considered Options
-
-### Option 1: Direct Pass-Through of MCP Cancellation
-
-Route MCP `notifications/cancelled` messages as-is within MCPx envelopes.
-
-```json
-{
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/cancelled",
- "params": {
- "requestId": "123",
- "reason": "User requested cancellation"
- }
- }
-}
-```
-
-**Pros:**
-- Full MCP compatibility maintained
-- No translation needed
-- Follows MCP specification exactly
-- Simple implementation
-
-**Cons:**
-- Requires tracking MCP request IDs at MCPx layer
-- May need correlation between MCPx envelope IDs and MCP request IDs
-
-### Option 2: MCPx-Level Cancellation Wrapper
-
-Create an MCPx-specific cancellation kind that wraps the envelope ID.
-
-```json
-{
- "kind": "mcpx/cancel",
- "payload": {
- "envelopeId": "original-envelope-id",
- "reason": "User requested cancellation"
- }
-}
-```
-
-**Pros:**
-- Clear separation between MCPx and MCP layers
-- Can cancel non-MCP messages
-- Simpler correlation tracking
-
-**Cons:**
-- Duplicates MCP functionality
-- Requires translation between layers
-- Not MCP-compliant
-
-### Option 3: Dual-Layer Approach
-
-Support both MCP cancellation for MCP messages and MCPx cancellation for other message types.
-
-**Pros:**
-- Maximum flexibility
-- MCP compliance for MCP messages
-- Can handle all message types
-
-**Cons:**
-- Complex implementation
-- Two cancellation mechanisms to maintain
-- Potential confusion
-
-## Recommendation
-
-**Option 1: Direct Pass-Through of MCP Cancellation**
-
-Since MCPx is designed to extend MCP, we should use MCP's existing cancellation mechanism directly. This maintains full compatibility and avoids reinventing established patterns.
-
-## Implementation Notes
-
-### Cancellation Message Format
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "cancel-123",
- "from": "participant-1",
- "to": ["participant-2"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/cancelled",
- "params": {
- "requestId": "original-mcp-request-id",
- "reason": "User cancelled operation"
- }
- }
-}
-```
-
-### Progress Support
-MCP also defines `notifications/progress` for tracking long-running operations. MCPx should pass these through as well:
-
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "progress-456",
- "from": "participant-2",
- "to": ["participant-1"],
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/progress",
- "params": {
- "progressToken": "abc123",
- "progress": 50,
- "total": 100,
- "message": "Processing..."
- }
- }
-}
-```
-
-### Key Requirements
-- MCPx envelopes must preserve MCP request IDs for correlation
-- Gateways route cancellation notifications without interpretation
-- Participants handle race conditions per MCP specification
-- Progress tokens are included in request metadata when progress tracking is desired
-- **No cancellation confirmation**: Following MCP specification, cancellations are fire-and-forget notifications with no acknowledgment or confirmation response
-
-## References
-- MCP Specification 2025-06-18: Cancellation utility
-- MCP Specification 2025-06-18: Progress utility
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/004-j99-targeted-proposals-and-rejection.md b/spec/archive/protocol/v0.2/decisions/rejected/004-j99-targeted-proposals-and-rejection.md
deleted file mode 100644
index 263b88e2..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/004-j99-targeted-proposals-and-rejection.md
+++ /dev/null
@@ -1,273 +0,0 @@
-# ADR-004: Targeted Proposals and Rejection Mechanisms
-
-**Status:** Superseded by ADR-006
-**Date:** 2025-08-30
-**Context:** MCPx Protocol Draft Specification
-
-> **Note**: This ADR has been superseded by ADR-006: Proposal Lifecycle Management, which combines targeting and cancellation into a simpler, more cohesive design.
-
-## Context
-
-In the current MCPx protocol, proposals are broadcast to all participants. This creates inefficiencies when:
-- A proposer knows which participant should handle a request
-- Participants must wait for timeouts when no one will fulfill a proposal
-- Load balancing or specific routing is desired
-- Sensitive operations should be limited to trusted participants
-
-There's a need to consider:
-1. Allowing proposers to specify intended fulfiller(s)
-2. Enabling timely rejection responses to avoid waiting for timeout
-3. Maintaining the observable, learning-friendly nature of the protocol
-
-## Decision Drivers
-
-- Need for efficient proposal routing
-- Reduction of unnecessary timeout waiting
-- Support for both broadcast and targeted patterns
-- Backward compatibility with existing implementations
-- Maintaining system observability for learning
-
-## Considered Options
-
-### Option 1: Add Optional `fulfiller` Field to Proposals
-
-Simple extension with an optional field specifying intended participants.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "fulfiller": ["agent-1", "agent-2"],
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Simple extension to existing protocol
-- Maintains backward compatibility
-- Clear intent signaling
-- Multiple participants can be requested
-
-**Cons:**
-- No guarantee specified fulfillers will respond
-- Other capable participants might be excluded unnecessarily
-- No formal rejection mechanism
-- Still requires timeout waiting
-
-### Option 2: Request/Response Pattern with Accept/Reject
-
-Formal request/response mechanism with explicit accept/reject messages.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "request_response": true,
- "response_timeout": 5000,
- "preferred_fulfillers": ["agent-1"],
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Explicit accept/reject mechanism
-- Faster failure detection
-- Enables negotiation patterns
-- Can track who's considering the proposal
-
-**Cons:**
-- Adds significant protocol complexity
-- Requires new message types
-- Need to handle multiple responses
-- Coordination overhead
-
-### Option 3: Capability-Based Routing
-
-Route based on required capabilities rather than specific participants.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "required_capabilities": ["filesystem", "git"],
- "preferred_participant": "agent-1",
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Semantic targeting based on capabilities
-- Fallback to any capable participant
-- Self-organizing system
-- Maintains simplicity
-
-**Cons:**
-- Requires capability discovery mechanism
-- Preferred participant is just a hint
-- No rejection mechanism
-- May not match proposer's intent
-
-### Option 4: Bidding/Auction System
-
-Market-like system where participants bid on proposals.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "request_bids": true,
- "bid_timeout": 3000,
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Market-like efficiency
-- Best participant self-selects
-- Provides metadata for decision making
-- Enables load balancing
-
-**Cons:**
-- Most complex option
-- Overhead for simple operations
-- Requires bid evaluation logic
-- May create competitive dynamics
-
-### Option 5: Hybrid - Optional Targeting with Timeout Override
-
-Flexible system supporting both broadcast and targeted patterns with optional quick rejection.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "targeting": {
- "preferred": ["agent-1", "agent-2"],
- "exclusive": false,
- "quick_reject": true,
- "fallback_timeout": 5000
- },
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Flexible targeting options
-- Maintains broadcast nature
-- Optional rejection for efficiency
-- Graceful fallback behavior
-- Progressive enhancement
-
-**Cons:**
-- More complex targeting configuration
-- Needs careful timeout coordination
-- Mixed paradigms (broadcast + targeting)
-
-## Recommendation
-
-**Option 5: Hybrid - Optional Targeting with Timeout Override**
-
-This provides the best balance of flexibility, efficiency, and compatibility. It allows progressive enhancement from simple broadcast to sophisticated targeting while maintaining backward compatibility.
-
-## Implementation Notes
-
-### Phase 1: Simple Preference Field
-Add optional `preferred` field to proposals:
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "preferred": "filesystem-agent",
- "params": { ... }
- }
-}
-```
-
-### Phase 2: Quick Rejection Capability
-Add optional rejection message:
-```json
-{
- "kind": "proposal-reject",
- "payload": {
- "proposal_id": "abc123",
- "reason": "busy" | "incapable" | "error"
- }
-}
-```
-
-### Phase 3: Full Targeting Configuration
-Complete targeting system with exclusive mode and fallback:
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "targeting": {
- "preferred": ["trusted-agent"],
- "exclusive": true,
- "exclusive_timeout": 3000,
- "fallback_to_broadcast": true
- },
- "params": { ... }
- }
-}
-```
-
-## Example Flows
-
-### Simple Preference
-```
-1. Proposer broadcasts proposal with preferred: "agent-1"
-2. Agent-1 sees preference and prioritizes response
-3. Other agents may still respond if agent-1 doesn't
-```
-
-### Quick Rejection
-```
-1. Proposer sends proposal with quick_reject: true
-2. Agent-1 immediately rejects (busy)
-3. Agent-2 accepts and fulfills
-Total time: ~100ms vs 5000ms timeout
-```
-
-### Exclusive with Fallback
-```
-1. Proposer sends exclusive proposal to trusted-agent
-2. Wait 3 seconds for response
-3. If no response, fallback to broadcast
-4. Any agent can now fulfill
-```
-
-## Design Principles
-
-1. **Default to Broadcast**: Maintains current behavior without configuration
-2. **Progressive Enhancement**: All features are optional
-3. **Fail Open**: If targeting fails, fall back to broadcast
-4. **Semantic Intent**: Express why, not just who
-5. **Observability**: All decisions remain visible for learning
-
-## Security Considerations
-
-- Exclusive mode should not bypass permission checks
-- Rejection messages should not leak sensitive information
-- Targeting preferences are hints, not access control
-- Gateway still enforces capability-based permissions
-
-## Open Questions
-
-1. Should rejection messages be required when quick_reject is enabled?
-2. How to handle multiple simultaneous acceptances?
-3. Should proposal state be tracked (pending/accepted/fulfilled)?
-4. Is capability advertisement needed as part of peer-joined?
-5. How does targeting interact with untrusted proposal routing?
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/005-38e-proposal-cancellation-mechanism.md b/spec/archive/protocol/v0.2/decisions/rejected/005-38e-proposal-cancellation-mechanism.md
deleted file mode 100644
index 674ed4f0..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/005-38e-proposal-cancellation-mechanism.md
+++ /dev/null
@@ -1,238 +0,0 @@
-# ADR-005: Proposal Cancellation Mechanism
-
-**Status:** Superseded by ADR-006
-**Date:** 2025-08-30
-**Context:** MCPx Protocol Draft Specification
-
-> **Note**: This ADR has been superseded by ADR-006: Proposal Lifecycle Management, which combines targeting and cancellation into a simpler, more cohesive design.
-
-## Decision
-
-We will implement **Option 1: Proposal Withdrawal Message** as the primary cancellation mechanism. This provides a simple, explicit way to withdraw proposals that follows the fire-and-forget pattern established by MCP's cancellation mechanism. No confirmation is sent for withdrawals, maintaining consistency with MCP patterns.
-
-## Context
-
-Proposals in MCPx are suggestions from untrusted participants for operations that trusted participants can review and execute. Unlike MCP requests which have defined cancellation via `notifications/cancelled`, proposals are MCPx-specific constructs that need their own cancellation mechanism.
-
-Current challenges:
-- Proposers may want to withdraw proposals before they're fulfilled
-- Proposals may become irrelevant due to changing context
-- No way to indicate a proposal is no longer needed
-- Fulfillment attempts on cancelled proposals waste resources
-
-## Decision Drivers
-
-- Need to withdraw proposals that are no longer relevant
-- Prevent unnecessary fulfillment attempts
-- Maintain audit trail of proposal lifecycle
-- Keep consistency with MCP cancellation patterns where applicable
-- Support both manual and automatic cancellation scenarios
-
-## Considered Options
-
-### Option 1: Proposal Withdrawal Message
-
-Introduce a dedicated message kind for withdrawing proposals.
-
-```json
-{
- "kind": "proposal/withdraw",
- "payload": {
- "proposalId": "original-proposal-id",
- "reason": "No longer needed"
- }
-}
-```
-
-**Pros:**
-- Clear and explicit intent
-- Simple to implement
-- Maintains proposal audit trail
-- Can include reason for documentation
-
-**Cons:**
-- Adds new message kind to protocol
-- Requires proposal ID tracking
-- May arrive after fulfillment starts
-
-### Option 2: Proposal with TTL (Time-To-Live)
-
-Add optional TTL field to proposals that auto-expires them.
-
-```json
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "ttl": 30000, // Expires after 30 seconds
- "params": { ... }
- }
-}
-```
-
-**Pros:**
-- Automatic cleanup
-- No additional messages needed
-- Predictable behavior
-- Useful for time-sensitive operations
-
-**Cons:**
-- Not true cancellation (can't withdraw early)
-- Requires time synchronization
-- Fixed duration may not fit all scenarios
-- No explicit withdrawal record
-
-### Option 3: Proposal Status Updates
-
-Implement a status system where proposers can update proposal state.
-
-```json
-{
- "kind": "proposal/status",
- "payload": {
- "proposalId": "original-proposal-id",
- "status": "withdrawn" | "expired" | "pending",
- "reason": "Context changed"
- }
-}
-```
-
-**Pros:**
-- Flexible status management
-- Can handle multiple states
-- Extensible for future needs
-- Clear lifecycle tracking
-
-**Cons:**
-- More complex state machine
-- Requires status synchronization
-- May conflict with fulfillment status
-
-### Option 4: Reuse MCP Cancellation Pattern
-
-Treat proposals like requests and use MCP's cancellation pattern.
-
-```json
-{
- "kind": "mcp",
- "payload": {
- "jsonrpc": "2.0",
- "method": "notifications/cancelled",
- "params": {
- "requestId": "proposal-id",
- "reason": "Proposal withdrawn"
- }
- }
-}
-```
-
-**Pros:**
-- Consistent with MCP patterns
-- No new message types
-- Familiar to MCP implementers
-- Reuses existing infrastructure
-
-**Cons:**
-- Proposals aren't MCP requests
-- Semantic mismatch
-- May confuse MCP and MCPx layers
-- Could break MCP compliance
-
-### Option 5: Hybrid Approach with TTL and Withdrawal
-
-Combine TTL for automatic expiry with explicit withdrawal capability.
-
-```json
-// Proposal with optional TTL
-{
- "kind": "proposal",
- "payload": {
- "method": "tools/call",
- "ttl": 60000, // Optional auto-expiry
- "params": { ... }
- }
-}
-
-// Explicit withdrawal (before TTL)
-{
- "kind": "proposal/withdraw",
- "payload": {
- "proposalId": "proposal-123",
- "reason": "User cancelled"
- }
-}
-```
-
-**Pros:**
-- Maximum flexibility
-- Handles both automatic and manual cases
-- Clear semantics
-- Progressive enhancement
-
-**Cons:**
-- Two mechanisms to implement
-- Slightly more complex
-- Need to handle interaction between TTL and withdrawal
-
-## Recommendation
-
-**Option 1: Proposal Withdrawal Message**
-
-This approach is chosen for its simplicity and consistency with MCP's cancellation patterns. It provides clear, explicit withdrawal semantics without adding unnecessary complexity. TTL functionality can be added in a future iteration if needed, but starting simple allows us to validate the core pattern first.
-
-## Implementation Notes
-
-### Withdrawal Message Format
-```json
-{
- "protocol": "mcpx/v0.1",
- "id": "withdraw-456",
- "from": "untrusted-agent",
- "kind": "proposal/withdraw",
- "payload": {
- "proposalId": "prop-123",
- "reason": "Operation no longer needed"
- }
-}
-```
-
-## Behavior Requirements
-
-1. **Withdrawal Handling**:
- - Only the original proposer can withdraw their proposal
- - Withdrawal is immediate and irreversible
- - No confirmation is sent (fire-and-forget, like MCP cancellation)
- - Gateway may emit system notification for observability
-
-2. **Race Conditions**:
- - Fulfillment may start before withdrawal arrives
- - Withdrawals after fulfillment are ignored
- - Participants should handle gracefully
- - No error is sent for late withdrawals
-
-3. **State Tracking**:
- - Proposals can be: pending, withdrawn, or fulfilled
- - State transitions are one-way
- - History is maintained for audit
- - Withdrawn proposals remain visible (marked as withdrawn)
-
-## Security Considerations
-
-- Only proposal originator can withdraw their own proposals
-- Withdrawal reasons should not leak sensitive information
-- Gateway validates withdrawal authorization
-- No denial-of-service via withdrawal spam (fire-and-forget pattern)
-
-## Future Extensions
-
-- TTL support for automatic expiry (if needed)
-- Batch withdrawal for multiple proposals
-- Proposal dependencies and cascading cancellation
-- Proposal renewal mechanism
-
-## Open Questions
-
-1. Should we add TTL support in a future version?
-2. How should proposal withdrawal interact with the targeted proposals feature (ADR-004)?
-3. Should system emit notifications when proposals are withdrawn?
-4. Should there be rate limiting on withdrawal messages?
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.2/decisions/rejected/README.md b/spec/archive/protocol/v0.2/decisions/rejected/README.md
deleted file mode 100644
index 92751b46..00000000
--- a/spec/archive/protocol/v0.2/decisions/rejected/README.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Rejected ADRs
-
-This folder contains ADRs (Architecture Decision Records) that have been reviewed and rejected.
-
-## Format
-
-**Filename:** `[rejection-number]-[adr-id]-[descriptive-name].md`
-
-- **Rejection number:** Sequential number based on order of rejection (may have gaps)
-- **ADR ID:** Original unique 3-character alphanumeric identifier (preserved from proposal)
-- **Descriptive name:** Original kebab-case description
-
-Note: Numbering may have gaps if ADRs were moved or reorganized.
-
-## Rejected ADRs
-
-- `001-d4n-space-configuration.md` - Space configuration specification
- - **Rejection Date:** 2025-09-03
- - **Reason:** Configuration format is implementation-specific, not part of the wire protocol. Will be applied to future CLI implementation.
-
-- `001-h9j-pod-discovery-and-hub-architecture.md` - Hub discovery architecture
- - **Rejection Date:** 2025-08-31
- - **Reason:** Out of scope for initial version. Pod configuration (ADR-d4n) provides a different approach that needs to mature first.
-
-- `002-a3j-request-cancellation-mechanism.md` - Request cancellation mechanism
- - **Reason:** Conflicts with fire-and-forget philosophy of MCP/MECP
-
-- `004-j99-targeted-proposals-and-rejection.md` - Targeted proposals and rejection
- - **Reason:** Adds complexity without clear benefit over existing patterns
-
-- `005-38e-proposal-cancellation-mechanism.md` - Proposal cancellation mechanism
- - **Reason:** Overlaps with request cancellation, adds unnecessary state management
-
-## Rejection Reasons
-
-ADRs may be rejected for various reasons:
-- Out of scope for current version
-- Superseded by alternative approach
-- Technical infeasibility
-- Complexity outweighs benefits
-- Conflicts with core design principles
-- Implementation-specific (not protocol-level)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.3/SPEC.md b/spec/archive/protocol/v0.3/SPEC.md
deleted file mode 100644
index 97969da0..00000000
--- a/spec/archive/protocol/v0.3/SPEC.md
+++ /dev/null
@@ -1,1069 +0,0 @@
-# MEW Protocol v0.3 Specification
-
-Version: v0.3
-Status: Released
-Release Date: 2025-09-10
-Intended Status: Experimental
-Editors: RJ Corwin (https://github.com/rjcorwin)
-
----
-
-## Requirements Language
-
-The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
-
----
-
-## 1. Abstract
-
-MEW Protocol (Multi-Entity Workspace Protocol) provides a unified context where all agent-to-agent and agent-to-tool interactions are visible and controllable at the protocol layer. The name playfully evokes "herding cats" - the quintessential challenge of coordinating multiple independent, autonomous agents who each have their own goals and behaviors. Unlike traditional systems where AI coordination happens in hidden contexts, MEW Protocol broadcasts all messages within a shared workspace, enabling participants to observe everything and privileged users to approve or reject actions through a proposal-review pattern. The protocol extends MCP semantics while adding capability-based access control, allowing untrusted agents to propose operations that trusted participants execute. This transparency enables progressive automation, where systems learn from human decisions to safely expand their autonomous capabilities over time - essentially teaching the "cats" to work together effectively.
-
----
-
-## 2. Goals and Non-Goals
-
-### 2.1 Goals
-- **Unified Context**: All participants share the same visible stream of interactions
-- **Protocol-Level Control**: Control actions through capabilities and proposals, not application wrappers
-- **Progressive Automation**: Learn from human decisions to safely expand autonomous operations
-- **Tool Compatibility**: Preserve existing MCP tool and resource interfaces
-
-### 2.2 Non-Goals
-- End-to-end encryption or private channels (all messages visible within space)
-- Message persistence or replay (spaces are ephemeral)
-- Cross-space routing or participant discovery
-- Guaranteed delivery or ordering (WebSocket best-effort)
-- Application-specific semantics beyond MCP operations
-- Configuration management (implementation-specific)
-
----
-
-## 3. Message Envelope
-
-All data flowing over a space MUST be a single top-level JSON envelope:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "2f6b6e70-7b36-4b8b-9ad8-7c4f7d0e2d0b",
- "ts": "2025-08-26T14:00:00Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp/request",
- "correlation_id": ["env-1"],
- "context": "workflow-123/step-1",
- "payload": { /* kind-specific body */ }
-}
-```
-
-Field semantics:
-- `protocol`: MUST be `"mew/v0.3"` for this version
-- `id`: globally unique message id (e.g., UUIDv4)
-- `ts`: RFC3339 timestamp
-- `from`: stable participant id within the space
-- `to`: array of participant ids (empty/omitted = broadcast)
-- `kind`: Message type using minimal kinds:
- - `mcp/request` - MCP request/notification
- - `mcp/response` - MCP response
- - `mcp/proposal` - MCP proposal for operations
- - `mcp/withdraw` - Withdraw a proposal
- - `mcp/reject` - Reject a proposal
- - `reasoning/start` - Begin reasoning sequence
- - `reasoning/thought` - Reasoning monologue (thinking out loud)
- - `reasoning/conclusion` - End reasoning sequence
- - `capability/grant` - Grant capabilities to participant
- - `capability/revoke` - Revoke capabilities from participant
- - `capability/grant-ack` - Acknowledge capability grant
- - `space/invite` - Invite participant to space
- - `space/kick` - Remove participant from space
- - `chat` - Chat messages
- - `system/presence` - Join/leave events
- - `system/welcome` - Welcome message for new participants
- - `system/error` - System error messages
-- `correlation_id`: array of message IDs this message relates to (always an array, even for single values)
- - Response → Request: `mcp/response` MUST reference the originating `mcp/request`
- - Fulfillment → Proposal: `mcp/request` MAY reference a `mcp/proposal` when fulfilling it
- - Withdraw → Proposal: `mcp/withdraw` MUST reference the proposal being withdrawn
- - Reject → Proposal: `mcp/reject` MUST reference the proposal being rejected
- - Error → Trigger: `system/error` messages SHOULD reference the envelope that caused the error
- - Reply → Message: Any envelope MAY reference others to indicate explicit reply intent (use `context` field for threading)
- - Workflow → Multiple: Messages in complex workflows MAY reference multiple related messages (e.g., a summary referencing several analyses, a decision based on multiple proposals, a response addressing multiple questions)
- - Fork/Join → Multiple: A response that combines results from multiple parallel requests
- - The array structure supports complex multi-party coordination and DAG-like message flows
-- `context`: (optional) string representing the context or sub-context for this message
- - Path-based hierarchy using forward slashes: `"parent/child/grandchild"`
- - Messages in sub-contexts (reasoning, workflows) include this field for organization
- - Context groups related messages together (e.g., all thoughts in a reasoning sequence)
- - When prompting LLMs, implementations MAY filter contexts to reduce noise
- - IMPORTANT: Messages addressed to a participant (via `to` field) MUST be handled regardless of context
-- `payload`: object; structure depends on `kind`
-
-### 3.1 MCP Messages
-
-MCP messages use minimal kinds with method information in the payload:
-- `kind: "mcp/request"` for requests/notifications
-- `kind: "mcp/response"` for responses
-- `kind: "mcp/proposal"` for proposals
-- `kind: "mcp/withdraw"` for withdrawing proposals
-- `kind: "mcp/reject"` for rejecting proposals
-- The specific method (e.g., `tools/call`, `resources/read`) is in `payload.method`
-
-#### 3.1.1 MCP Requests
-
-Example tool call request:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-call-1",
- "from": "trusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-#### 3.1.2 MCP Responses
-
-Responses MUST include the `correlation_id` field referencing the original request's `id`. This is critical for translating MCP's client-server request/response model to MEW Protocol's multi-participant broadcast paradigm, allowing all participants to match responses to their corresponding requests.
-
-Response to the above tool call:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-resp-1",
- "from": "target-agent",
- "to": ["trusted-agent"],
- "kind": "mcp/response",
- "correlation_id": ["env-call-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }]
- }
- }
-}
-```
-
-Note: The MCP payload structure remains unchanged from standard MCP.
-
-### 3.2 MCP Proposals
-
-Participants with restricted capabilities MUST use proposals instead of direct MCP operations. Proposals have the same payload structure as requests:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-req-1",
- "from": "untrusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/proposal",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-This is a MEW Protocol-specific extension that proposes an MCP operation requiring fulfillment by a participant with appropriate capabilities.
-
-#### 3.2.1 Proposal Fulfillment
-
-A participant with appropriate capabilities fulfills the proposal by making the real MCP call. The `correlation_id` field is critical for matching approvals to their original proposals:
-- Proposals typically don't include `correlation_id` (they originate new workflows)
-- Fulfillment messages MUST include `correlation_id` referencing the proposal's `id`
-- This allows participants to track which fulfillment corresponds to which proposal
-- The correlation chain enables audit trails and multi-step approval workflows
-
-Example fulfillment:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-fulfill-1",
- "from": "human-user",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "correlation_id": ["env-req-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-The response goes only to the fulfiller who made the request. The response's `correlation_id` references the fulfillment message (`env-fulfill-1`), maintaining the standard request/response pairing. The original proposer can observe the outcome since messages are broadcast by default:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-fulfill-resp-1",
- "from": "target-agent",
- "to": ["human-user"],
- "kind": "mcp/response",
- "correlation_id": ["env-fulfill-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed successfully"
- }]
- }
- }
-}
-```
-
-The proposer can follow the correlation chain to track the outcome:
-1. Proposer sends proposal (`env-req-1`)
-2. Fulfiller sends request with `correlation_id: ["env-req-1"]` (`env-fulfill-1`)
-3. Target sends response with `correlation_id: ["env-fulfill-1"]` (`env-fulfill-resp-1`)
-4. Proposer observes the broadcast response and can trace back through the correlation chain
-
-### 3.3 Proposal Lifecycle Operations
-
-MEW Protocol extends the proposal pattern with lifecycle operations for cancellation and feedback.
-
-#### 3.3.1 Withdraw Proposals (kind = "mcp/withdraw")
-
-Proposers can withdraw their own proposals that are no longer needed:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "withdraw-456",
- "from": "untrusted-agent",
- "correlation_id": ["env-req-1"],
- "kind": "mcp/withdraw",
- "payload": {
- "reason": "no_longer_needed"
- }
-}
-```
-
-- Only the original proposer can withdraw their proposals
-- `correlation_id` MUST reference the proposal being withdrawn
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.2 Reject Proposals (kind = "mcp/reject")
-
-Any participant with the capability can reject proposals. Rejections provide early feedback to avoid unnecessary waiting:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "reject-789",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["env-req-1"],
- "kind": "mcp/reject",
- "payload": {
- "reason": "unsafe"
- }
-}
-```
-
-**Purpose and Behavior:**
-- Prevents proposers from waiting unnecessarily for fulfillment that won't come
-- Particularly important when explicitly targeted in a proposal's `to` field
-- Proposers MAY give up after the first rejection (fail-fast approach)
-- Proposers MAY continue waiting for other participants to fulfill (resilient approach)
-- The choice depends on the proposer's implementation and use case
-- Multiple participants may reject the same proposal for different reasons
-
-**Requirements:**
-- `correlation_id` MUST reference the proposal being rejected
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.3 Standardized Reason Codes
-
-Lifecycle operations use standardized reason codes:
-
-- `"disagree"` - Don't agree with the proposed action
-- `"inappropriate"` - Not suitable for the current context
-- `"unsafe"` - Could cause harm or unintended consequences
-- `"busy"` - Currently handling other work
-- `"incapable"` - Don't have the required tools/access
-- `"policy"` - Violates security or operational policy
-- `"duplicate"` - Already being handled by another participant
-- `"invalid"` - Proposal is malformed or impossible
-- `"timeout"` - Too old or expired
-- `"resource_limit"` - Would exceed resource constraints
-- `"no_longer_needed"` - Proposer no longer needs the operation
-- `"other"` - Reason not covered above
-
-Detailed explanations can be provided via follow-up chat messages using `correlation_id`:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "chat-790",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["reject-789"],
- "kind": "chat",
- "payload": {
- "text": "I'm currently processing a large batch operation that requires exclusive file access. Please retry in about 5 minutes.",
- "format": "plain"
- }
-}
-```
-
-**Important timing consideration:** The reject message with a reason code should be sent immediately for fast feedback. Detailed explanations may arrive later as generating them (especially with LLMs) can take time. Participants implementing proposers should:
-- Process the reject immediately upon receipt
-- Optionally wait for follow-up explanations if they need details
-- Not block on explanations that may never come
-
-### 3.4 Chat Messages (kind = "chat")
-
-Chat messages are MEW Protocol-specific and do not pollute the MCP namespace:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-chat-1",
- "from": "user-alice",
- "kind": "chat",
- "payload": {
- "text": "Hello everyone!",
- "format": "plain"
- }
-}
-```
-
-- `text` (required): The message content
-- `format` (optional): "plain" or "markdown", defaults to "plain"
-- Chat messages are typically broadcast (empty/omitted `to` array)
-
-### 3.5 Reasoning Transparency
-
-MEW Protocol supports transparent reasoning through dedicated message kinds and the context field. This allows agents to share their thinking process while maintaining clear boundaries between reasoning sequences and regular operations.
-
-#### 3.5.1 Reasoning Pattern
-
-Common patterns for transparent reasoning:
-
-**Response Pattern:**
-1. Agent receives a request (e.g., `mcp/request`)
-2. Agent sends `reasoning/start` with `correlation_id` referencing the request
-3. The `reasoning/start` message ID becomes the `context` for subsequent messages
-4. Agent MAY send `reasoning/thought` messages for internal monologue (optional)
-5. Agent MAY use `chat` messages within context for dialogue with other participants
-6. Agent MAY send `reasoning/conclusion` to summarize findings (optional)
-7. Agent sends final response with `correlation_id` to original request
-
-**Autonomous Pattern:**
-- Agent sends `reasoning/start` at any time (e.g., periodic analysis, monitoring)
-- The `reasoning/start` creates a context for transparent thinking
-- Agent shares thoughts as they occur
-- No response required - purely for transparency
-
-Note: `reasoning/start` creates a context for transparency. Whether responding to requests or reasoning autonomously, it lets other participants observe the agent's thinking process.
-
-#### 3.5.2 Reasoning Start (kind = "reasoning/start")
-
-Signals the beginning of a reasoning sequence:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "reason-start-1",
- "from": "agent-1",
- "kind": "reasoning/start",
- "correlation_id": ["req-123"],
- "payload": {
- "message": "Analyzing the request to modify the configuration file..."
- }
-}
-```
-
-#### 3.5.3 Reasoning Thought (kind = "reasoning/thought")
-
-Shares internal reasoning steps (monologue, no reply expected):
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "thought-1",
- "from": "agent-1",
- "kind": "reasoning/thought",
- "context": "reason-start-1",
- "payload": {
- "message": "The configuration file appears to use YAML format. I should validate the syntax before making changes."
- }
-}
-```
-
-#### 3.5.4 Reasoning Conclusion (kind = "reasoning/conclusion")
-
-Concludes the reasoning sequence:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "reason-end-1",
- "from": "agent-1",
- "kind": "reasoning/conclusion",
- "context": "reason-start-1",
- "payload": {
- "message": "Configuration update is safe to proceed. The changes are valid YAML and won't break existing settings."
- }
-}
-```
-
-#### 3.5.5 Context Behavior
-
-- Messages with a `context` field are part of a sub-context
-- Participants MAY filter out contexts when constructing prompts (e.g., excluding other agents' reasoning traces to reduce noise)
-- **Exception**: Participants MUST NOT ignore `mcp/request` or `mcp/proposal` messages, even if they have a context field
-- The context field supports hierarchical paths: `"parent/child/grandchild"`
-- Context enables parallel reasoning by multiple agents without interference
-
-### 3.6 Space Management Operations
-
-A **space** in MEW Protocol is a communication context where participants exchange messages. It's analogous to a channel or room - a bounded environment where a specific set of participants collaborate. Each space has its own:
-- Set of participants (who can send/receive messages)
-- Capability assignments (what each participant can do)
-- Message history (the stream of envelopes exchanged)
-
-A gateway may manage multiple spaces, each isolated from the others. The gateway enforces capabilities and routing rules for all its spaces.
-
-MEW Protocol extends with operations for managing these spaces dynamically. These operations use the `capability/*` and `space/*` namespaces to clearly indicate their purpose.
-
-#### 3.6.1 Grant Capabilities (kind = "capability/grant")
-
-Allows participants with appropriate capabilities to grant capabilities to other participants:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "grant-789",
- "from": "trusted-orchestrator",
- "to": ["untrusted-agent"],
- "kind": "capability/grant",
- "payload": {
- "recipient": "untrusted-agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_file"
- }
- }
- }
- ],
- "reason": "Demonstrated safe file handling"
- }
-}
-```
-
-- The grant message ID becomes the `grant_id` for future revocation
-- Capabilities use the same JSON pattern matching format from Section 4.1
-- Gateway SHOULD add granted capabilities to recipient's capability set
-- Multiple grants are cumulative
-
-#### 3.6.2 Revoke Capabilities (kind = "capability/revoke")
-
-Revokes previously granted capabilities:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "revoke-123",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "grant_id": "grant-789",
- "reason": "Task completed"
- }
-}
-```
-
-Alternatively, revoke by capability pattern (removes ALL matching capabilities):
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "revoke-456",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/*"
- }
- }
- ],
- "reason": "No longer needed"
- }
-}
-```
-
-#### 3.6.3 Grant Acknowledgment (kind = "capability/grant-ack")
-
-Recipients acknowledge capability grants:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "ack-001",
- "from": "agent",
- "correlation_id": ["grant-789"],
- "kind": "capability/grant-ack",
- "payload": {
- "status": "accepted"
- }
-}
-```
-
-#### 3.6.4 Invite Participant (kind = "space/invite")
-
-Invites new participants to the space:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "invite-123",
- "from": "admin",
- "kind": "space/invite",
- "payload": {
- "participant_id": "new-agent",
- "email": "agent-operator@example.com", // Optional
- "initial_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ],
- "reason": "Adding specialized analysis agent"
- }
-}
-```
-
-**Fields:**
-- `participant_id`: Identifier for the new participant
-- `email`: (optional) Email address to send invitation to
-- `initial_capabilities`: Capabilities the participant will have when they join
-- `reason`: Explanation for the invitation
-
-**Note:** This message is broadcast within the space to inform existing participants. If `email` is provided, the gateway SHOULD send an invitation email with connection details. Additional notification methods (webhook, token generation, etc.) are gateway implementation-specific.
-
-#### 3.6.5 Remove Participant (kind = "space/kick")
-
-Removes participants from the space:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "kick-456",
- "from": "admin",
- "kind": "space/kick",
- "payload": {
- "participant_id": "misbehaving-agent",
- "reason": "Repeated capability violations"
- }
-}
-```
-
-#### 3.6.6 Delegation Security
-
-- Only participants with `capability/grant` capability can grant capabilities
-- Participants cannot grant capabilities they don't possess
-- Gateway SHOULD track grant chains for audit purposes
-- Revocations take effect immediately
-- All space management operations generate audit logs
-
-### 3.7 Presence Messages (kind = "system/presence")
-
-Presence messages are broadcast to notify all participants about join/leave events:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-presence-1",
- "from": "system:gateway",
- "kind": "system/presence",
- "payload": {
- "event": "join",
- "participant": {
- "id": "new-agent",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
- }
-}
-```
-
-- `event` (required): Either `"join"` or `"leave"`
-- `participant` (required): Information about the participant
- - `id`: The participant's identifier
- - `capabilities`: The participant's capabilities (for `join` events)
-
-Note: Presence messages are broadcast to all participants. The joining participant also receives a welcome message addressed specifically to them (via the `to` field) with their authoritative capabilities and the current participant list.
-
-### 3.8 System Messages
-
-#### 3.8.1 Welcome Message (kind = "system/welcome")
-
-When a participant connects, the gateway MUST send a welcome message addressed specifically to that participant (using the `to` field):
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-welcome-1",
- "from": "system:gateway",
- "to": ["new-participant"],
- "kind": "system/welcome",
- "payload": {
- "you": {
- "id": "new-participant",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- },
- "participants": [
- {
- "id": "agent-1",
- "capabilities": [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- },
- {
- "id": "agent-2",
- "capabilities": [
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- }
- ]
- }
-}
-```
-
-- `you`: The joining participant's own information and authoritative capabilities
-- `participants`: Current list of other participants in the space and their capabilities
-
-**Important:** Other participants SHOULD ignore welcome messages not addressed to them when constructing prompts, as these can cause significant bloat. The message is already targeted via the `to` field.
-
-#### 3.8.2 Capability Violation (kind = "system/error")
-
-When a participant attempts an operation they lack capability for:
-
-```json
-{
- "protocol": "mew/v0.3",
- "id": "env-violation-1",
- "from": "system:gateway",
- "to": ["violator"],
- "kind": "system/error",
- "correlation_id": ["env-bad-call"],
- "payload": {
- "error": "capability_violation",
- "attempted_kind": "mcp/request",
- "your_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
-}
-```
-
----
-
-## 4. Security Model
-
-### 4.1 Capability-Based Access Control
-
-The gateway enforces security through two mechanisms:
-
-1. **Identity Validation**: The gateway MUST verify that the `from` field matches the authenticated participant's ID. Participants cannot spoof messages from other participants.
-
-2. **Capability Matching**: The gateway assigns capabilities to each connection using JSON pattern matching. Capabilities are JSON objects that match against the message structure (kind and payload).
-
-**Capability Pattern Structure:**
-```json
-{
- "kind": "pattern",
- "payload": {
- "field": "pattern"
- }
-}
-```
-
-**Pattern Types:**
-- String with wildcards: `"mcp/*"` matches `mcp/request`, `mcp/response`, etc.
-- Exact match: `"chat"` only matches `"chat"`
-- Nested patterns: Match specific payload fields
-
-**Reserved Namespace:**
-The `system/*` namespace is reserved exclusively for the gateway. Participants MUST NOT send messages with `kind` starting with `system/`. The gateway MUST reject any such attempts. Only the gateway can generate system messages (`system/welcome`, `system/presence`, `system/error`).
-
-**Example Capability Sets:**
-
-Gateways may implement various capability profiles using JSON patterns:
-
-1. **Full Access** example:
- ```json
- [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- ```
- Can send any MCP messages (requests, responses, proposals)
-
-2. **Proposal-Only** example:
- ```json
- [
- {"kind": "mcp/proposal"},
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Cannot send direct MCP requests, must use proposals
-
-3. **Tool-Specific** example:
- ```json
- [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_*"
- }
- }
- },
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Can only call tools matching `read_*` pattern
-
-**Progressive Trust Example:**
-
-Capabilities can be expanded as trust increases:
-1. Initial: `[{"kind": "mcp/proposal"}, {"kind": "chat"}]` - Proposals only
-2. Basic: Add read capabilities with payload patterns
-3. Trusted: Add tool usage with specific tool patterns
-4. Full: Replace with `[{"kind": "mcp/*"}]` - Unrestricted MCP access
-
-### 4.2 Gateway Enforcement
-
-The gateway enforces capabilities using JSON pattern matching against the message structure:
-
-**What the Gateway Does:**
-- Matches the message's `kind` and `payload` against participant's capability patterns
-- Uses wildcards, regex patterns, and JSONPath for flexible matching
-- Blocks messages if no capability matches
-- Returns error responses for capability violations
-
-**What the Gateway Does NOT Do:**
-- Parse or validate JSON-RPC payloads
-- Understand MCP semantics
-- Detect spoofing (where `kind` doesn't match payload content)
-
-**Pattern Matching Examples:**
-- Message with `kind: "mcp/request"` and `payload.method: "tools/call"` matches:
- - `{"kind": "mcp/*"}`
- - `{"kind": "mcp/request"}`
- - `{"kind": "mcp/request", "payload": {"method": "tools/*"}}`
-- Message with `kind: "chat"` only matches:
- - `{"kind": "chat"}`
- - `{"kind": "*"}` (wildcard for all kinds)
-
-### 4.3 Participant Validation
-
-Receiving participants SHOULD validate message structure:
-- Verify `kind` is appropriate for the message type
-- Validate payload structure matches expected schema
-- Drop or report malformed messages
-- MAY track misbehaving participants for reputation scoring
-
-**Schema Mismatch Warning:** Participants may observe messages with schemas that differ from what was advertised:
-- Other participants might advertise one tool schema but send different parameters
-- Participants joining mid-conversation may see responses to requests they never observed
-- Always parse messages defensively and validate structure before processing
-
----
-
-## 5. Realtime Gateway API
-
-### 5.1 Authentication and Capability Assignment
-
-The gateway determines capabilities during authentication. Implementation-specific policies may include:
-
-1. **Token-based**: Tokens map to specific capability sets
- - Implementations may encode capabilities in tokens or map tokens to capability profiles
-2. **Identity-based**: Map authenticated identities to capability sets
-3. **Space access control**: Spaces may be public, private, or restricted
-4. **Dynamic capabilities**: Capabilities may be modified during a session
-
-### 5.2 WebSocket Connection
-
-Connect: `GET /ws?space=` with Authorization header
-
-The gateway:
-1. Validates the bearer token (if provided)
-2. Maps the token to a participant ID (implementation-specific)
-3. Determines capabilities based on implementation policy
-4. **MUST** send welcome message with the assigned participant ID and accurate capabilities
-5. **MUST** enforce capability rules on all subsequent messages
-
-**Note:** Participants only provide their bearer token. The gateway is responsible for mapping tokens to participant IDs through its own implementation-specific mechanism.
-
-The capabilities in the welcome message constitute the authoritative list of what operations the participant can perform. Participants SHOULD use this list to understand their allowed operations.
-
-### 5.3 Message Filtering
-
-For each incoming message from a participant:
-
-```python
-if not matches_any_capability(message, participant.capabilities):
- send_error(f"Capability violation: you lack capability for this operation")
- broadcast_violation_notice() # optional
- return
-send_to_space(message)
-```
-
----
-
-## 6. Version Compatibility
-
-### 6.1 Breaking Changes
-
-This is a v0.x release. Breaking changes are expected between minor versions until v1.0:
-- v0.3 is NOT backward compatible with v0.2
-- Clients and gateways MUST use matching protocol versions
-- No compatibility guarantees until v1.0 release
-
-### 6.2 Migration from v0.2
-
-Key breaking changes from v0.2:
-- Protocol name changed from MEUP to MEW Protocol
-- Protocol identifier changed from `meup/v0.2` to `mew/v0.3`
-- Full name is now "Multi-Entity Workspace Protocol"
-
-### 6.3 Migration from v0.0
-
-Key breaking changes from v0.0:
-- Protocol identifier changed from `mcp-x/v0` to `mew/v0.3`
-- Message kinds now use slash notation (e.g., `mcp/request` instead of `mcp/request:tools/call`)
-- Method information moved to payload
-- Capabilities use JSON pattern matching instead of string wildcards
-- `correlation_id` is now always an array
-- Chat remains as dedicated `chat` kind
-
-### 6.4 Future Compatibility
-
-- v0.x series is experimental and subject to breaking changes
-- v1.0 will establish stable protocol with compatibility guarantees
-- Production deployments should pin specific v0.x versions
-
----
-
-## 7. Security Considerations
-
-MEW Protocol's security model relies on capability-based access control enforced by the gateway, with additional validation responsibilities distributed among participants.
-
-### 7.1 Core Security Mechanisms
-
-1. **Identity Validation**: Gateway MUST verify the `from` field matches the authenticated participant ID (Section 4.1)
-2. **Capability Enforcement**: Gateway enforces JSON pattern-based capabilities on all messages (Section 4.1, 4.2)
-3. **Reserved Namespaces**: Only the gateway can send `system/*` messages, preventing spoofing (Section 3.8)
-4. **Proposal Isolation**: Untrusted agents use `mcp/proposal` to suggest rather than execute operations (Section 3.3)
-5. **Lazy Gateway Enforcement**: Gateway validates message structure but not payload semantics (Section 4.2)
-
-### 7.2 Security Boundaries
-
-**Gateway Responsibilities:**
-- Authenticate participants and assign stable IDs
-- Enforce capability patterns on message kinds and payloads
-- Prevent identity spoofing via `from` field validation
-- Block `system/*` messages from participants
-
-**Participant Responsibilities:**
-- Validate envelope `kind` matches payload content
-- Detect and report malformed or spoofed messages
-- Parse messages defensively (schemas may differ from advertised)
-- Track misbehaving participants for reputation scoring
-
-### 7.3 Best Practices
-
-1. **Start Restricted**: New agents begin with `mcp/proposal` capability only
-2. **Progressive Trust**: Expand capabilities based on observed behavior over time
-3. **Validate Strictly**: Check that `kind` matches the payload type (e.g., `mcp/request` for MCP requests)
-4. **Monitor Proposals**: Log proposal/fulfillment patterns for audit trails
-5. **Report Violations**: Track and broadcast capability violations for transparency
-
----
-
-## 8. Implementation Checklist
-
-### 8.1 Gateway Requirements
-- [ ] **Connection Management**
- - [ ] WebSocket server at `GET /ws?space=`
- - [ ] Bearer token validation from Authorization header
- - [ ] Token-to-participant-ID mapping (implementation-specific)
- - [ ] Connection state tracking per participant
-
-- [ ] **Capability Enforcement**
- - [ ] Pattern matching engine for wildcard capabilities
- - [ ] Validate message `kind` against sender's capabilities
- - [ ] Block messages that don't match capabilities
- - [ ] Return `system/error` for capability violations
-
-- [ ] **System Messages**
- - [ ] Send `system/welcome` with participant ID and capabilities on connect
- - [ ] Broadcast `system/presence` for join/leave events
- - [ ] Generate `system/error` for protocol violations
- - [ ] Ensure only gateway can send `system/*` messages
-
-- [ ] **Message Routing**
- - [ ] Route messages based on `to` field (broadcast if empty/omitted)
- - [ ] Preserve envelope structure without modification
- - [ ] NO payload parsing or validation (lazy enforcement)
-
-### 8.2 Participant Requirements
-- [ ] **Message Validation**
- - [ ] Verify envelope structure before processing
- - [ ] Validate `kind` matches the payload type (e.g., `mcp/request` for requests with `payload.method`)
- - [ ] Validate payload structure matches expected schema for the `kind`
- - [ ] Drop messages that fail validation
- - [ ] Track/report misbehaving participants
-
-- [ ] **MCP Integration**
- - [ ] Implement MCP server capabilities
- - [ ] Handle incoming MCP requests/responses
- - [ ] Generate proper correlation IDs for responses
- - [ ] Include correlation ID in all response messages
-
-- [ ] **Proposal Handling** (if applicable)
- - [ ] Recognize `mcp.proposal` messages
- - [ ] Implement fulfillment logic for approved proposals
- - [ ] Include proposal ID as correlation_id when fulfilling
-
-- [ ] **Connection Behavior**
- - [ ] Process `system/welcome` to learn own ID and capabilities
- - [ ] Handle `system/presence` to track other participants
- - [ ] Respect capability restrictions from welcome message
-
----
-
-## 9. Examples
-
-The following examples demonstrate multi-agent orchestration patterns enabled by MEW Protocol's capability-based security model. The core pattern is **delegated fulfillment**, where untrusted agents propose operations that are reviewed and executed by trusted participants.
-
-### 9.1 Proposal-Based Workflow Example
-
-In this example, an agent with limited capabilities uses proposals:
-
-1. Agent connects → receives proposal-only capabilities
-2. Agent attempts MCP request → gateway blocks, returns error
-3. Agent sends `mcp/proposal` → visible to all participants
-4. Another participant with appropriate capabilities fulfills it
-5. Fulfiller sends real `mcp/request` message to target
-6. Target executes and returns result to fulfiller (proposer observes via broadcast)
-
-### 9.2 Capability Expansion Example
-
-One possible administrative workflow:
-
-1. Agent operates successfully over time
-2. Administrator observes behavior patterns
-3. Administrator expands agent capabilities
-4. Agent gains access to additional operations
-
-### 9.3 Mixed Environment Example
-
-A gateway might assign different capability profiles:
-
-- Administrative users: `{"kind": "mcp/*"}` (full access)
-- Service agents: `{"kind": "mcp/response"}` (response-only)
-- New agents: `{"kind": "mcp/proposal"}` (proposal-only)
-- Monitoring tools: `{"kind": "mcp/request", "payload": {"method": "*/list"}}` (read-only)
-
-All participants operate in the same space with their assigned capabilities.
-
-### 9.4 Delegated Fulfillment Example
-
-A human supervises an untrusted agent through intermediary agents:
-
-1. **Proposer Agent** (capability: `mcp/proposal`) proposes writing a file
-2. **Human** reviews the proposal and decides to approve it by directing the **Orchestrator Agent** (capability: `mcp/request`) to fulfill the proposal
-3. **Orchestrator Agent** sends the MCP request to **Worker Agent**
-4. **Worker Agent** executes the actual file write operation and responds
-5. Over time, **Human** teaches **Orchestrator Agent** rules about which proposals to auto-approve
-6. **Orchestrator Agent** begins autonomously fulfilling certain proposals without human intervention
-
-This pattern demonstrates **progressive automation** - a key goal of MEW Protocol. As the orchestrator observes human decisions over time, it learns which types of proposals can be safely auto-approved. This transforms human judgment into automated policies, creating a system that becomes more autonomous while maintaining safety through learned boundaries.
-
----
-
-## 10. Appendix: Implementation Notes
-
-### 10.1 Gateway State
-
-Minimal state required per connection:
-```json
-{
- "connection_id": "ws-123",
- "participant_id": "agent-a",
- "capabilities": [{"kind": "mcp/proposal"}, {"kind": "chat"}],
- "connected_at": "2025-08-26T14:00:00Z"
-}
-```
-
-### 10.2 Proposal Tracking
-
-Optional proposal tracking for fulfillment (maintained by agents, not gateway):
-```json
-{
- "proposalId": "env-proposal-1",
- "proposer": "untrusted-agent",
- "target": "target-agent",
- "method": "tools/call",
- "params": {"name": "dangerous_operation", "arguments": {...}},
- "status": "pending",
- "createdAt": "2025-08-26T14:00:00Z",
- "expiresAt": "2025-08-26T14:05:00Z"
-}
-```
-
----
-
-## References
-
-- MCP Specification 2025-06-18
-- MEW v0.0 Specification (formerly MEUP)
-- ADR-003: Tool Access Control
-- OAuth 2.0 RFC 6749 (for token patterns)
diff --git a/spec/archive/protocol/v0.3/decisions/README.md b/spec/archive/protocol/v0.3/decisions/README.md
deleted file mode 100644
index bc0b27bc..00000000
--- a/spec/archive/protocol/v0.3/decisions/README.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Draft Protocol Decisions
-
-This directory will contain Architecture Decision Records (ADRs) for the next version of the MEUP protocol.
-
-## Current Status
-
-No active decisions for the draft version. All v0.2 decisions have been incorporated and are available in `/spec/v0.2/decisions/`.
-
-## Directory Structure
-
-- `proposed/` - ADRs under consideration for the next version
-- `accepted/` - Approved ADRs for the next version
-- `rejected/` - Rejected ADRs kept for historical context
-
-## Creating New ADRs
-
-When proposing changes for the next protocol version:
-
-1. Create ADR in `proposed/` with format: `[number]-[id]-[name].md`
-2. Use unique 3-character ID (e.g., `a1b`)
-3. Follow ADR template from `/spec/CLAUDE.md`
-4. Reference this as "MEUP Protocol Next" or specific version when known
-
-## Previous Versions
-
-- **v0.2 decisions**: `/spec/v0.2/decisions/` - Current released protocol
-- **v0.1 decisions**: Historical (if any)
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.3/decisions/accepted/001-mew-protocol-name-change.md b/spec/archive/protocol/v0.3/decisions/accepted/001-mew-protocol-name-change.md
deleted file mode 100644
index 257ed4e7..00000000
--- a/spec/archive/protocol/v0.3/decisions/accepted/001-mew-protocol-name-change.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# ADR-001: MEW Protocol Name Change
-
-**Status:** Accepted
-**Date:** 2025-01-09
-**Incorporation:** Complete
-
-## Context
-
-The protocol is currently named MEUP (Multi-Entity Unified-context Protocol). A proposal has been made to rename it to MEW Protocol, which is shorter and potentially more memorable. The acronym MEW needs to be defined to maintain the semantic meaning and purpose of the protocol.
-
-## Options Considered
-
-### Option 1: Multi-Entity Workspace
-**MEW** = Multi-Entity Workspace
-
-**Pros:**
-- Emphasizes the "space" concept that's central to the protocol
-- "Workspace" clearly conveys a collaborative environment
-- Maintains the multi-entity aspect from the original name
-- Simple and intuitive
-
-**Cons:**
-- Loses the "unified context" concept
-- Less emphasis on the protocol aspect
-
-### Option 2: Message Exchange Web
-**MEW** = Message Exchange Web
-
-**Pros:**
-- Emphasizes the message-passing nature of the protocol
-- "Web" suggests interconnected participants
-- Clear focus on communication
-
-**Cons:**
-- Too generic, could apply to many messaging protocols
-- Loses the multi-entity and context aspects
-
-### Option 3: Multi-Entity Wire
-**MEW** = Multi-Entity Wire
-
-**Pros:**
-- "Wire" is a common protocol/transport metaphor
-- Very concise
-- Maintains multi-entity focus
-
-**Cons:**
-- Loses context and workspace concepts
-- "Wire" might be too low-level
-
-### Option 4: Mediated Entity Workflow
-**MEW** = Mediated Entity Workflow
-
-**Pros:**
-- "Mediated" captures the gateway's role
-- "Workflow" implies coordination and proposals
-- Emphasizes the orchestration aspect
-
-**Cons:**
-- "Workflow" might be too restrictive
-- Less emphasis on the unified context
-
-### Option 5: Multiparty Exchange Wire
-**MEW** = Multiparty Exchange Wire
-
-**Pros:**
-- "Multiparty" emphasizes multiple participants
-- "Exchange" captures bidirectional communication
-- "Wire" suggests protocol-level operation
-
-**Cons:**
-- Doesn't capture the unified context aspect
-- Similar to generic messaging protocols
-
-### Option 6: Multi-Entity Unified
-**MEU** = Multi-Entity Unified
-
-**Pros:**
-- Preserves the exact core concepts from MEUP
-- Drops only "Protocol" which is implied by context
-- Maintains the unified context concept explicitly
-- Minimal semantic change from original
-
-**Cons:**
-- "MEU" pronunciation less memorable than "MEW"
-- Feels incomplete without "Protocol"
-- Less intuitive what "Unified" means without more context
-
-### Option 7: Multi-Entity Protocol
-**MEP** = Multi-Entity Protocol
-
-**Pros:**
-- Simple and clear
-- Explicitly identifies as a protocol
-- Maintains multi-entity focus
-- Generic enough to be flexible
-
-**Cons:**
-- Loses the unified context concept entirely
-- Very generic, could describe many protocols
-- No differentiation from other multi-party protocols
-- "MEP" less memorable as a sound
-
-## Decision
-
-**Recommended: Option 1 - Multi-Entity Workspace (MEW)**
-
-**MEW** should stand for **Multi-Entity Workspace**. This option provides the best balance of semantic meaning and memorability:
-
-1. **Multi-Entity**: Preserves the core concept of multiple participants (agents, tools, humans) operating together
-2. **Workspace**: Effectively captures the "unified-context" concept - a workspace IS a unified context where all participants share visibility
-3. **Memorable**: The "mew" pronunciation is playful and memorable, making the protocol more approachable
-
-The term "workspace" naturally conveys:
-- A unified context where all work happens
-- Shared visibility and transparency
-- Collaboration between multiple entities
-- A bounded environment (matching the "space" concept in the protocol)
-
-This interpretation maintains the essential semantics of MEUP while providing a more intuitive and memorable name.
-
-### Implementation Details
-
-1. Update all references from "MEUP" to "MEW" throughout the specification
-2. Update the protocol identifier from `"meup/v0.2"` to `"mew/v0.2"`
-3. Update the abstract to define MEW as "Multi-Entity Workspace"
-4. Maintain backward compatibility notes for migration from MEUP
-
-## Consequences
-
-### Positive
-- Shorter, more memorable name (3 letters vs 4)
-- "MEW" is easier to pronounce and remember
-- Playful connection to cat sound ("mew") makes it memorable and approachable
-- Perfect metaphor: "herding cats" captures the challenge of coordinating multiple autonomous agents
- - Independent agents (cats) need coordination in a shared workspace
- - Capability-based control manages what each "cat" can do
- - Proposal pattern prevents chaos from agents doing whatever they want
-- "Workspace" is more intuitive than "Unified-context Protocol"
-- Maintains semantic continuity with the original goals
-
-### Negative
-- Breaking change for existing implementations
-- Need to update all documentation and references
-- Potential confusion during transition period
-- Loss of explicit "protocol" in the acronym (though context makes it clear)
-
diff --git a/spec/archive/protocol/v0.3/decisions/accepted/README.md b/spec/archive/protocol/v0.3/decisions/accepted/README.md
deleted file mode 100644
index 6636e72c..00000000
--- a/spec/archive/protocol/v0.3/decisions/accepted/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Accepted ADRs
-
-This folder contains accepted Architecture Decision Records for the next version of the MEUP protocol.
-
-## Current Status
-
-No accepted ADRs for the next version yet. All v0.2 ADRs are in `/spec/v0.2/decisions/accepted/`.
-
-## Format
-
-When ADRs are accepted from `proposed/`:
-- Maintain the same filename (including proposal number)
-- Update Status to "Accepted"
-- Track Incorporation status as implementation progresses
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.3/decisions/proposed/001-r5x-reasoning-interruption.md b/spec/archive/protocol/v0.3/decisions/proposed/001-r5x-reasoning-interruption.md
deleted file mode 100644
index a033ab8d..00000000
--- a/spec/archive/protocol/v0.3/decisions/proposed/001-r5x-reasoning-interruption.md
+++ /dev/null
@@ -1,235 +0,0 @@
-# ADR-r5x: Reasoning Interruption Mechanism
-
-**Status:** Proposed
-**Date:** 2025-09-13
-**Context:** MEW Protocol v0.3
-**Incorporation:** Not Incorporated
-
-## Context
-
-MEW Protocol supports transparent reasoning through `reasoning/start`, `reasoning/thought`, and `reasoning/conclusion` message kinds. Agents can enter potentially long reasoning sequences, especially when using ReAct (Reason + Act) loops with LLMs that may require multiple iterations to complete complex tasks.
-
-Currently, there is no standardized mechanism to interrupt an agent's reasoning process. This creates several problems:
-
-1. **Runaway reasoning**: Agents may get stuck in reasoning loops or pursue unproductive lines of thought
-2. **Resource management**: Long reasoning sequences consume computational resources and API calls
-3. **User experience**: Humans cannot easily redirect or stop agents that are reasoning in the wrong direction
-4. **Multi-agent coordination**: Other agents cannot signal that the reasoning agent should stop and reconsider
-
-The protocol needs a mechanism to gracefully interrupt reasoning sequences while maintaining transparency and allowing for proper cleanup.
-
-## Options Considered
-
-### Option 1: Direct Stop Command
-Add a new `reasoning/stop` message kind that any participant can send to interrupt another's reasoning.
-
-**Pros:**
-- Simple and direct approach
-- Clear semantic meaning
-- Works with existing message routing
-- Can be capability-controlled
-
-**Cons:**
-- Abrupt interruption may not allow cleanup
-- No mechanism for the reasoning agent to acknowledge the stop
-- Could be disruptive if misused
-
-### Option 2: Reasoning Interrupt with Acknowledgment
-Add `reasoning/interrupt` and `reasoning/interrupt-ack` message kinds to create a two-phase interruption.
-
-**Pros:**
-- Allows reasoning agent to acknowledge and clean up gracefully
-- Two-phase pattern is already used in capability management
-- Provides audit trail of interruptions
-- Reasoning agent can choose to complete current thought before stopping
-
-**Cons:**
-- More complex than direct stop
-- Requires additional message exchange
-- Reasoning agent could ignore interrupt requests
-
-### Option 3: Context-Based Interruption
-Use chat messages within the reasoning context to signal interruption requests.
-
-**Pros:**
-- Leverages existing message types
-- Natural for human participants to send chat messages
-- Context field ensures messages are associated with the reasoning sequence
-- No new message kinds needed
-
-**Cons:**
-- Less semantically clear than dedicated message types
-- Agents need to parse chat content to detect interruption intent
-- Inconsistent with protocol's explicit message typing
-- Harder to implement capability controls
-
-### Option 4: Reasoning Redirect
-Add `reasoning/redirect` message kind that provides new direction rather than just stopping.
-
-**Pros:**
-- More constructive than just stopping
-- Allows steering reasoning toward better approaches
-- Maintains reasoning context while changing direction
-- Can include new goals or constraints
-
-**Cons:**
-- More complex to implement
-- Reasoning agent may not be able to handle arbitrary redirections
-- Unclear how to merge new direction with existing reasoning state
-
-## Decision
-
-**Option 2: Reasoning Interrupt with Acknowledgment** is selected.
-
-This approach provides the right balance of control and grace, allowing for clean interruption while maintaining the protocol's explicit message semantics and audit trail philosophy.
-
-### Implementation Details
-
-#### New Message Kinds
-
-**`reasoning/interrupt`** - Request interruption of a reasoning sequence
-```json
-{
- "protocol": "mew/v0.3",
- "id": "interrupt-123",
- "from": "human-supervisor",
- "to": ["reasoning-agent"],
- "kind": "reasoning/interrupt",
- "correlation_id": ["reason-start-1"],
- "payload": {
- "reason": "timeout|redirect|error|user_request|resource_limit",
- "message": "Optional human-readable explanation"
- }
-}
-```
-
-**`reasoning/interrupt-ack`** - Acknowledge interruption and indicate response
-```json
-{
- "protocol": "mew/v0.3",
- "id": "interrupt-ack-456",
- "from": "reasoning-agent",
- "correlation_id": ["interrupt-123"],
- "kind": "reasoning/interrupt-ack",
- "payload": {
- "status": "stopping|completing_thought|continuing|ignored",
- "message": "Optional explanation of chosen response"
- }
-}
-```
-
-#### Interrupt Reason Codes
-
-- `"timeout"`: Reasoning has exceeded time limits
-- `"redirect"`: Need to change reasoning direction
-- `"error"`: Error condition requires stopping reasoning
-- `"user_request"`: Human participant wants to interrupt
-- `"resource_limit"`: Computational resources are being exhausted
-- `"other"`: Other reason (must include message explanation)
-
-#### Acknowledgment Status Codes
-
-- `"stopping"`: Will stop reasoning immediately after current thought
-- `"completing_thought"`: Will complete current reasoning step then stop
-- `"continuing"`: Choosing to continue despite interrupt request
-- `"ignored"`: Interrupt not applicable or not authorized
-
-#### Behavioral Requirements
-
-1. **Interrupt Messages**:
- - MUST target specific reasoning agent via `to` field
- - MUST reference the reasoning sequence via `correlation_id`
- - SHOULD include human-readable explanation in message field
-
-2. **Reasoning Agents**:
- - SHOULD check for interrupt messages between reasoning iterations
- - MUST send acknowledgment within 30 seconds of receiving interrupt
- - MAY continue reasoning if interrupt is not from authorized participant
- - SHOULD emit `reasoning/conclusion` with interruption context when stopping
-
-3. **Capability Control**:
- - Sending `reasoning/interrupt` SHOULD be capability-controlled
- - Agents SHOULD respect interrupts from participants with appropriate capabilities
- - Self-interruption (agent interrupting its own reasoning) is always allowed
-
-#### Example Flow
-
-1. Agent begins reasoning sequence with `reasoning/start` (id: `reason-start-1`)
-2. Agent sends several `reasoning/thought` messages
-3. Human sends `reasoning/interrupt` with `correlation_id: ["reason-start-1"]`
-4. Agent receives interrupt and sends `reasoning/interrupt-ack` with `status: "completing_thought"`
-5. Agent completes current thought, sends `reasoning/thought` message
-6. Agent sends `reasoning/conclusion` indicating it was interrupted
-7. Agent stops reasoning sequence
-
-## Consequences
-
-### Positive
-- Provides mechanism to stop runaway or unproductive reasoning
-- Maintains protocol transparency with explicit message types
-- Allows graceful cleanup and acknowledgment
-- Enables capability-based control over who can interrupt
-- Creates audit trail of interruptions for debugging and analysis
-- Supports both automated (timeout/resource) and human interruptions
-
-### Negative
-- Adds complexity with two new message kinds
-- Reasoning agents must implement interruption checking logic
-- Requires additional network round-trips for acknowledgment
-- Agents can choose to ignore interrupts, making it not guaranteed
-- May need additional capability configuration for interruption permissions
-
-### Security Considerations
-- Interruption capability should be granted carefully to prevent DoS attacks
-- Agents should validate interrupt requests are from authorized participants
-- Frequent interruptions could be used to disrupt agent reasoning maliciously
-- Interrupt acknowledgments reveal reasoning agent state to other participants
-
-### Migration Path
-- Existing reasoning sequences continue to work without changes
-- Agents can gradually implement interrupt handling capabilities
-- Participants can start sending interrupts once agents support acknowledgment
-- No breaking changes to existing `reasoning/*` message types
-
-## Examples
-
-### Timeout-Based Interruption
-```json
-{
- "kind": "reasoning/interrupt",
- "from": "resource-monitor",
- "to": ["slow-reasoner"],
- "correlation_id": ["long-reasoning-seq"],
- "payload": {
- "reason": "timeout",
- "message": "Reasoning exceeded 5 minute limit"
- }
-}
-```
-
-### Human Redirection
-```json
-{
- "kind": "reasoning/interrupt",
- "from": "human-operator",
- "to": ["assistant-agent"],
- "correlation_id": ["task-reasoning"],
- "payload": {
- "reason": "redirect",
- "message": "Please focus on the security implications instead"
- }
-}
-```
-
-### Graceful Acknowledgment
-```json
-{
- "kind": "reasoning/interrupt-ack",
- "from": "assistant-agent",
- "correlation_id": ["interrupt-request"],
- "payload": {
- "status": "completing_thought",
- "message": "Will finish current security analysis then address new direction"
- }
-}
-```
\ No newline at end of file
diff --git a/spec/archive/protocol/v0.3/decisions/rejected/README.md b/spec/archive/protocol/v0.3/decisions/rejected/README.md
deleted file mode 100644
index 82d42ba1..00000000
--- a/spec/archive/protocol/v0.3/decisions/rejected/README.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# Rejected ADRs
-
-This folder contains rejected Architecture Decision Records kept for historical context.
-
-## Current Status
-
-No rejected ADRs for the next version yet. All v0.2 rejected ADRs are in `/spec/v0.2/decisions/rejected/`.
-
-## Format
-
-When ADRs are rejected from `proposed/`:
-- Renumber based on rejection order
-- Maintain the ADR ID for reference
-- Update Status to "Rejected"
-- Add rejection rationale to the document
\ No newline at end of file
diff --git a/spec/bridge/proposed/001-mbr-bridge-architecture.md b/spec/bridge/proposals/mbr-bridge-architecture.md
similarity index 100%
rename from spec/bridge/proposed/001-mbr-bridge-architecture.md
rename to spec/bridge/proposals/mbr-bridge-architecture.md
diff --git a/spec/cli/SPEC.md b/spec/cli/SPEC.md
index 9b1b7677..c627c2d3 100644
--- a/spec/cli/SPEC.md
+++ b/spec/cli/SPEC.md
@@ -1474,7 +1474,7 @@ A lightweight terminal interface for protocol debugging and automated testing. T
### MCP Operation Confirmation Workflow
-The advanced interactive mode includes built-in confirmation dialogs for MCP (Model Context Protocol) operations that require human approval. The implementation follows a phased approach from [ADR-009: Approval Dialog UX](./decisions/accepted/009-aud-approval-dialog-ux.md).
+The advanced interactive mode includes built-in confirmation dialogs for MCP (Model Context Protocol) operations that require human approval. The implementation follows a phased approach from [ADR-009: Approval Dialog UX](./proposals/aud-approval-dialog-ux.md).
#### Phase 1: Generic Template (✅ IMPLEMENTED)
diff --git a/spec/cli/accepted/001-pmg-process-manager.md b/spec/cli/accepted/001-pmg-process-manager.md
deleted file mode 100644
index c3fb5cc3..00000000
--- a/spec/cli/accepted/001-pmg-process-manager.md
+++ /dev/null
@@ -1,226 +0,0 @@
-# ADR-pmg: Process Manager for MEW CLI
-
-**Status:** Accepted
-**Date:** 2025-01-07
-**Incorporation:** Complete
-
-## Context
-
-The MEW CLI needs to manage long-running processes (gateway, agents, clients) as part of the `mew space up/down` commands. Currently, when spawning the gateway process using Node.js `child_process.spawn()` with `detached: true` and `unref()`, the gateway process dies immediately, even though it stays alive when run directly.
-
-Investigation has revealed:
-- The gateway works perfectly when run directly via command line
-- The gateway dies when spawned by `mew space up`, regardless of stdio configuration
-- Various attempts to keep the process alive (setInterval, never-resolving promises) have failed
-- The issue appears to be related to process group management and signal handling when the parent process exits
-
-This is blocking automated testing and making the space management commands unreliable.
-
-## Options Considered
-
-### Option 1: Continue with child_process.spawn() Workarounds
-
-Continue trying to fix the current approach with various spawn configurations and keep-alive mechanisms.
-
-**Pros:**
-- No new dependencies
-- Direct control over process spawning
-- Simpler conceptual model
-
-**Cons:**
-- Current approach has proven unreliable despite multiple attempts
-- Platform-specific behaviors are difficult to handle
-- Process lifecycle management is complex and error-prone
-- No built-in process monitoring or restart capabilities
-
-### Option 2: Implement a Lightweight Process Manager
-
-Create an internal process manager service that runs as a daemon and manages all MEW processes.
-
-**Pros:**
-- Full control over process lifecycle
-- Can implement monitoring, restart, and health checks
-- Consistent behavior across platforms
-- Enables advanced features (auto-restart, resource limits)
-- Provides a clean separation between CLI commands and process management
-
-**Cons:**
-- **Would face the same core spawning issues as Option 1**
-- If we can't reliably spawn a gateway, we likely can't reliably spawn a daemon
-- Requires implementing a daemon service
-- More complex architecture
-- Need to handle daemon lifecycle (start/stop/status)
-- Additional code to maintain
-- Significantly more complex than fixing the root cause
-
-### Option 3: Use PM2 as External Dependency
-
-Integrate with PM2, a production-ready process manager for Node.js applications.
-
-**Pros:**
-- Battle-tested process management
-- Built-in monitoring and logging
-- Automatic restart capabilities
-- Ecosystem support and documentation
-- Handles all edge cases
-
-**Cons:**
-- External dependency
-- Might be overkill for simple use cases
-- Users need to understand PM2 concepts
-- Potential version conflicts with user's PM2 installation
-
-### Option 4: Hybrid Approach - Optional Process Manager
-
-Support both direct spawning and process manager, with the manager being optional but recommended.
-
-**Pros:**
-- Flexibility for different use cases
-- Simple mode for development/testing
-- Production mode with full process management
-- Gradual migration path
-
-**Cons:**
-- Two code paths to maintain
-- Potential for inconsistent behavior
-- More complex documentation
-
-### Option 5: Alternative Process Managers
-
-Other Node.js process managers were considered:
-
-**forever/forever-monitor** (~5MB):
-- Pro: Much lighter weight, simple programmatic API
-- Con: Less active maintenance, fewer features
-
-**execa** (1MB):
-- Pro: Minimal, excellent API, well-maintained
-- Con: Just a spawner, would need custom process management
-
-**node-pty**:
-- Pro: Proper PTY handling might solve spawning issues
-- Con: Native dependencies, compilation required
-
-**Evaluation**: PM2 remains the best choice despite its size (30MB) due to:
-- Battle-tested reliability with millions of downloads
-- Programmatic API with PM2_HOME for complete isolation
-- Active maintenance and extensive documentation
-- Handles edge cases we haven't discovered yet
-
-## Decision
-
-Implement **Option 3: Use PM2 as External Dependency** as the sole solution.
-
-Rationale: PM2 is a battle-tested solution that already solves all the process management challenges we're facing. Rather than reinventing the wheel with Option 2 (which would likely hit the same issues), or maintaining parallel implementations, we should fully commit to leveraging existing, proven technology.
-
-### Implementation Details
-
-1. **PM2 as Embedded Library**
- ```javascript
- // PM2 installed as dependency, used programmatically
- const pm2 = require('pm2');
-
- // Each space gets its own PM2 daemon instance
- // PM2_HOME set to space directory to keep everything local
- process.env.PM2_HOME = path.join(spaceDir, '.mew/pm2');
-
- // Connect to space-specific PM2 daemon
- pm2.connect((err) => {
- // Start processes for this space only
- });
- ```
-
-2. **Space-Contained Process Management**
- - Each space has its own `.mew/pm2/` directory
- - PM2 daemon, logs, and PIDs all contained within space folder
- - No global PM2 installation or configuration required
- - Users don't need to know PM2 is being used
- - Complete isolation between spaces
-
-3. **Architecture**
- ```
- CLI Command → PM2 Library → Space-local PM2 Daemon → Spawned Process
- ↓
- .mew/pm2/ (local to space directory)
- ├── pm2.log
- ├── pm2.pid
- └── pids/
- ```
-
-4. **Process Configuration**
- ```javascript
- // Programmatic PM2 configuration (no ecosystem file needed)
- pm2.start({
- name: `${spaceId}-gateway`,
- script: path.resolve(__dirname, '../bin/mew.js'),
- args: ['gateway', 'start', '--port', port],
- cwd: spaceDir,
- autorestart: false, // We handle restart logic
- max_memory_restart: '500M',
- error_file: path.join(spaceDir, 'logs/gateway-error.log'),
- out_file: path.join(spaceDir, 'logs/gateway-out.log'),
- pid_file: path.join(spaceDir, '.mew/pm2/pids/gateway.pid')
- }, callback);
- ```
-
-5. **No Fallback Mode**
-
- **Decision: PM2 will be a required dependency**
-
- Rationale for not having a `--no-pm2` option:
- - Would create a parallel implementation that defeats the purpose
- - We'd still have to solve the same spawning problems for the fallback
- - Maintaining two implementations doubles testing and support burden
- - Users would inevitably use the fallback and hit the same issues we're trying to avoid
- - PM2 is a reasonable dependency (like how many CLIs depend on git, docker, etc.)
-
- Benefits of PM2-only approach:
- - Single, reliable implementation
- - Consistent behavior for all users
- - PM2's maturity solves current and future process management needs
- - Clear documentation and support path
- - Can leverage PM2's full feature set without worrying about fallback compatibility
-
-## Consequences
-
-### Positive
-- Immediately solves the process lifecycle issue
-- Battle-tested solution used in production environments
-- Rich feature set (monitoring, logging, auto-restart, clustering)
-- Complete isolation - each space is self-contained
-- No global state or configuration
-- Users don't need to know PM2 exists
-- Can run multiple spaces simultaneously without conflicts
-- All artifacts stay within space directory (logs, PIDs, etc.)
-- Handles all edge cases we haven't even discovered yet
-
-### Negative
-- External dependency (but a mature, stable one)
-- Adds ~30MB to installation size
-- PM2 daemon overhead per space (minimal, but exists)
-- Need to ensure PM2 daemon cleanup on space down
-- Slightly more complex than direct spawning (but more reliable)
-
-### Migration Path
-
-1. **Phase 1**: Add PM2 as npm dependency, implement space-local daemon
-2. **Phase 2**: Update `mew space up` to use PM2 API with PM2_HOME isolation
-3. **Phase 3**: Update `mew space down` to cleanly shutdown PM2 daemon
-4. **Phase 4**: Add `mew space logs` and `mew space restart` commands leveraging PM2
-
-### Testing Strategy
-
-- Integration tests with PM2 API
-- Test ecosystem file generation from various space.yaml configurations
-- Verify process lifecycle (start, stop, restart)
-- Test fallback mode without PM2
-- Platform-specific tests (macOS, Linux, Windows)
-- Test PM2 namespace isolation to avoid conflicts
-
-### Security Considerations
-
-- PM2 runs with user privileges only
-- No elevation of privileges
-- Process isolation through PM2 namespaces
-- Each space gets unique PM2 app names to prevent conflicts
-- Token validation remains at gateway level
\ No newline at end of file
diff --git a/spec/cli/accepted/002-cln-space-cleanup-command.md b/spec/cli/accepted/002-cln-space-cleanup-command.md
deleted file mode 100644
index bdc85c8a..00000000
--- a/spec/cli/accepted/002-cln-space-cleanup-command.md
+++ /dev/null
@@ -1,255 +0,0 @@
-# ADR-cln: Space Cleanup Command
-
-**Status:** Accepted
-**Date:** 2025-01-07
-**Incorporation:** Complete
-
-## Context
-
-During development and testing, spaces accumulate various artifacts:
-- Process information in `.mew/` directory
-- Log files in `logs/` directory
-- FIFO pipes in `fifos/` directory
-- PM2 daemon state (currently in default PM2_HOME)
-- Potentially orphaned processes
-
-Currently, cleanup is handled by:
-- Manual `rm -rf` commands
-- Test teardown scripts
-- `mew space down` (only stops processes)
-
-We need a formalized cleanup command that provides consistent, reliable cleanup of space artifacts while giving users control over what to preserve.
-
-## Options Considered
-
-### Option 1: Extend `mew space down` with cleanup flags
-
-Add flags to the existing `down` command:
-```bash
-mew space down --clean # Stop and clean everything
-mew space down --clean-logs # Stop and clean logs
-mew space down --clean-all # Stop and clean everything including PM2
-```
-
-**Pros:**
-- Fewer commands to remember
-- Natural extension of stopping a space
-- One-step stop and clean
-
-**Cons:**
-- Conflates two different operations (stop vs clean)
-- Can't clean without stopping
-- Unclear what happens if space is already stopped
-
-### Option 2: New `mew space clean` command
-
-Create a dedicated cleanup command:
-```bash
-mew space clean # Clean default artifacts (logs, fifos)
-mew space clean --all # Clean everything including .mew
-mew space clean --logs-only # Clean only logs
-```
-
-**Pros:**
-- Clear separation of concerns
-- Can clean without affecting running processes
-- More flexible cleanup options
-- Can be run independently
-
-**Cons:**
-- Additional command to learn
-- Might clean while space is running (dangerous)
-
-### Option 3: New `mew space reset` command
-
-Reset implies both stopping and cleaning:
-```bash
-mew space reset # Stop everything and clean
-mew space reset --preserve-logs # Stop and clean but keep logs
-```
-
-**Pros:**
-- Clear intent: "start fresh"
-- Single command for common use case
-- Implies both stop and clean
-
-**Cons:**
-- Less flexible than separate commands
-- Name might be confused with config reset
-
-### Option 4: Multiple specific commands
-
-```bash
-mew space stop # Just stop processes
-mew space clean # Just clean artifacts
-mew space purge # Nuclear option - clean everything
-```
-
-**Pros:**
-- Maximum clarity and control
-- Unix philosophy: do one thing well
-- Composable commands
-
-**Cons:**
-- More commands to remember
-- Requires multiple commands for common tasks
-
-## Decision
-
-Implement **Option 2: `mew space clean` command** with safety checks.
-
-This provides the best balance of flexibility and safety while maintaining clear separation of concerns.
-
-### Implementation Details
-
-#### Command Structure
-```bash
-mew space clean [options]
-
-Options:
- --all Clean everything including .mew directory
- --logs Clean only log files
- --fifos Clean only FIFO pipes
- --force Skip confirmation prompts
- --dry-run Show what would be cleaned without doing it
-```
-
-#### Default Behavior (no flags)
-- Clean logs/* (except current session if running)
-- Clean fifos/*
-- Clean temporary files
-- Preserve .mew/ directory (contains state)
-
-#### Safety Checks
-1. **Running Space Detection**
- - Warn if space is currently running
- - Require `--force` to clean running space artifacts
- - Never clean active FIFO pipes
-
-2. **Confirmation Prompts**
- ```
- Warning: Space is currently running!
- This will clean: logs (42 files), fifos (2 pipes)
- Continue? (y/N)
- ```
-
-3. **Preserve Important Files**
- - Keep .mew/pids.json if space is running
- - Option to preserve recent logs (--keep-recent)
- - Never delete space.yaml or agent files
-
-#### What Gets Cleaned
-
-**Default (`mew space clean`):**
-- `logs/*.log` - All log files
-- `fifos/*` - All FIFO pipes (if not in use)
-- Temporary response files
-- Old PM2 logs in .mew/pm2/logs/
-
-**With `--all`:**
-- Everything from default
-- `.mew/` directory entirely
-- PM2 daemon for this space (if using space-local PM2)
-
-**With `--logs`:**
-- Only files in `logs/` directory
-
-**With `--fifos`:**
-- Only pipes in `fifos/` directory
-
-#### Integration with Other Commands
-
-```bash
-# Common workflow
-mew space down # Stop the space
-mew space clean # Clean artifacts
-mew space up # Start fresh
-
-# Or more aggressive
-mew space down
-mew space clean --all # Complete cleanup
-
-# During development
-mew space clean --logs # Just clear logs while running
-```
-
-## Consequences
-
-### Positive
-- Consistent cleanup across all environments
-- Safety checks prevent accidental data loss
-- Flexible options for different needs
-- Clear separation from stop/down operations
-- Useful for CI/CD pipelines
-- Reduces disk usage from accumulated logs
-
-### Negative
-- Additional command to document and maintain
-- Risk of cleaning active artifacts if used incorrectly
-- Need to educate users on when to use clean vs down
-
-### Future Enhancements
-
-1. **Auto-cleanup policies**
- ```yaml
- # In space.yaml
- cleanup:
- auto_clean_logs: true
- max_log_age: 7d
- max_log_size: 100M
- ```
-
-2. **Scheduled cleanup**
- - Clean old logs automatically
- - Rotate logs based on size/age
-
-3. **Selective preservation**
- ```bash
- mew space clean --keep-errors # Keep error logs
- mew space clean --keep-recent # Keep last hour of logs
- ```
-
-## Examples
-
-### Development Workflow
-```bash
-# After debugging session
-mew space clean --logs # Clear cluttered logs
-
-# Before running tests
-mew space clean --all # Start completely fresh
-
-# CI/CD cleanup
-mew space down
-mew space clean --all --force # No prompts
-```
-
-### Safety Examples
-```bash
-$ mew space clean
-Space "my-space" is currently running.
-Warning: This will clean logs and fifos while space is active.
-Use 'mew space down' first, or use --force to proceed anyway.
-
-$ mew space clean --dry-run
-Would clean:
- - 47 log files (230 MB)
- - 2 FIFO pipes (inactive)
- - 3 temporary files
-Total: 230 MB would be freed
-
-$ mew space clean --all
-This will remove ALL space artifacts including configuration.
-Are you sure? (y/N): n
-Aborted.
-```
-
-## Testing Requirements
-
-1. Test cleaning with running space (should warn)
-2. Test cleaning with stopped space (should succeed)
-3. Test --dry-run shows correct files
-4. Test --force skips confirmations
-5. Test partial cleaning (--logs, --fifos)
-6. Test preservation of important files
-7. Test with space-local PM2 cleanup
\ No newline at end of file
diff --git a/spec/cli/accepted/003-fio-flexible-fifo-handling.md b/spec/cli/accepted/003-fio-flexible-fifo-handling.md
deleted file mode 100644
index 446c4187..00000000
--- a/spec/cli/accepted/003-fio-flexible-fifo-handling.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# ADR-003: Simple FIFO Input with Log Output
-
-**Status:** Accepted
-**Date:** 2025-01-07
-**Incorporation:** Complete
-
-## Context
-
-The current FIFO implementation in `mew space` has revealed a critical blocking issue that prevents test automation:
-
-1. **Blocking Problem**: When `auto_connect: true` is set with `fifo: true`, the client connects and writes to the output FIFO. If nothing is reading from it, the process blocks indefinitely, hanging the entire test.
-
-2. **Immediate Need**: Our test automation needs:
- - FIFO input to send test messages to the client
- - Non-blocking file output to analyze responses later
- - No complex background processes or workarounds
-
-3. **Current Limitations**:
- - Single `fifo: true/false` flag creates both input and output FIFOs
- - Output FIFO blocks if not actively read
- - Tests hang waiting for FIFO readers
-
-## Options Considered
-
-### Option 1: Keep Current Design
-
-Keep the single `fifo: true/false` flag that creates both input and output FIFOs.
-
-**Pros:**
-- No changes needed
-- Simple configuration
-
-**Cons:**
-- Tests will continue to hang
-- Requires complex workarounds
-- Not viable for automation
-
-### Option 2: Complex I/O Configuration
-
-Add a comprehensive I/O configuration system with multiple input/output types, rotation, etc.
-
-**Pros:**
-- Very flexible
-- Handles all future use cases
-
-**Cons:**
-- Over-engineered for current needs
-- Complex to implement
-- Delays fixing the immediate problem
-
-### Option 3: Simple FIFO + Log (Recommended)
-
-Add a simple `output_log` option that redirects output to a file instead of a FIFO:
-
-```yaml
-test-client:
- fifo: true # Creates input FIFO only when output_log is set
- output_log: "./logs/test-client.log" # Output goes to file
- auto_connect: true
-```
-
-**Pros:**
-- Minimal change to existing configuration
-- Solves the blocking problem immediately
-- Easy to understand and implement
-- Backward compatible (when output_log not set, behaves as before)
-
-**Cons:**
-- Less flexible than full I/O configuration
-- May need to revisit for future use cases
-
-## Decision
-
-**Option 3: Simple FIFO + Log** is recommended because it:
-
-1. Solves the immediate blocking problem with minimal changes
-2. Is simple to understand and implement
-3. Maintains backward compatibility
-4. Can be implemented quickly to unblock testing
-5. Leaves room for future enhancements if needed
-
-### Implementation Details
-
-1. **Configuration Behavior**:
- ```javascript
- // When output_log is specified, change behavior:
- if (participant.output_log) {
- // Create only input FIFO
- createFifo(`${participantId}-in`);
-
- // Redirect client output to log file
- clientArgs.push('--output-file', participant.output_log);
- } else {
- // Current behavior: create both FIFOs
- createFifo(`${participantId}-in`);
- createFifo(`${participantId}-out`);
- }
- ```
-
-2. **Client Connection Updates**:
- ```javascript
- // In client.js connect command
- if (options.outputFile) {
- // Write to file instead of FIFO
- const logStream = fs.createWriteStream(options.outputFile, { flags: 'a' });
- // Direct all output to log file
- } else if (options.fifoOut) {
- // Current FIFO behavior
- }
- ```
-
-3. **Space.yaml Examples**:
- ```yaml
- # For automated testing (non-blocking)
- test-client:
- fifo: true
- output_log: "./logs/test-client.log"
- auto_connect: true
-
- # For interactive debugging (current behavior)
- debug-client:
- fifo: true
- # No output_log means both FIFOs created
- ```
-
-## Consequences
-
-### Positive
-- Immediately unblocks test automation
-- Simple to implement and understand
-- Minimal changes to existing code
-- Backward compatible
-- Tests can easily analyze output from log files
-- Can tail log files for real-time debugging
-
-### Negative
-- Less flexible than a full I/O configuration system
-- May need enhancement for future use cases
-- Two different output modes might be confusing initially
-
-## Examples
-
-### Test Automation (Non-blocking)
-```yaml
-# scenario-1-basic/space.yaml
-participants:
- test-client:
- tokens: ["test-token"]
- capabilities:
- - kind: chat
- fifo: true
- output_log: "./logs/test-client.log"
- auto_connect: true
-
-# Test script can then:
-# 1. Send messages via: echo '{"kind":"chat",...}' > fifos/test-client-in
-# 2. Analyze responses: grep "pattern" logs/test-client.log
-```
-
-### Interactive Debugging (Current Behavior)
-```yaml
-# manual-testing/space.yaml
-participants:
- debug-client:
- tokens: ["debug-token"]
- capabilities:
- - kind: "*"
- fifo: true
- # No output_log = both FIFOs created
- auto_connect: false # Connect manually
-
-# Can interact via:
-# Terminal 1: cat < fifos/debug-client-out
-# Terminal 2: echo '{"kind":"chat",...}' > fifos/debug-client-in
-```
-
-### Mixed Mode Space
-```yaml
-participants:
- # Automated test client
- test-client:
- fifo: true
- output_log: "./logs/test-client.log"
- auto_connect: true
-
- # Interactive debug client
- debug-client:
- fifo: true
- # No output_log - use FIFOs for both
- auto_connect: false
-
- # Agent without FIFOs
- echo-agent:
- fifo: false
- auto_start: true
- command: "node"
- args: ["./agents/echo.js"]
-```
-
-## Migration Path
-
-1. **Phase 1** (Immediate): Implement `output_log` option
-2. **Phase 2**: Update test scenarios to use `output_log`
-3. **Phase 3**: Document the pattern in test README
-4. **Future**: If more flexibility needed, consider fuller I/O configuration
\ No newline at end of file
diff --git a/spec/cli/accepted/004-int-interactive-connection.md b/spec/cli/accepted/004-int-interactive-connection.md
deleted file mode 100644
index 6b6842ec..00000000
--- a/spec/cli/accepted/004-int-interactive-connection.md
+++ /dev/null
@@ -1,267 +0,0 @@
-# ADR-int: Interactive Connection Command
-
-**Status:** Accepted
-**Date:** 2025-01-10
-**Incorporation:** Complete
-
-## Context
-
-Currently, connecting to a MEW space requires either:
-1. Using FIFOs for automation (complex setup, blocking issues)
-2. Writing a custom client application
-3. Using the test-interactive.js script (not part of CLI)
-
-Developers need a simple, built-in way to connect to a space interactively for:
-- Debugging protocol interactions
-- Testing agent responses
-- Exploring space capabilities
-- Quick manual testing during development
-
-The current `mew space up` command starts the space but doesn't provide an interactive connection. Users must use separate commands or tools to actually interact with the space.
-
-## Options Considered
-
-### Option 1: Add `--interactive` flag to `mew space up`
-
-Modify the existing command to optionally connect interactively:
-```bash
-mew space up --interactive
-mew space up -i # shorthand
-```
-
-**Pros:**
-- Natural workflow: start space and immediately connect
-- Single command for common use case
-- Reuses existing participant resolution logic
-- Minimal new API surface
-
-**Cons:**
-- Mixes two concerns (starting space vs connecting)
-- What happens if space is already running?
-- Unclear how to connect to existing space
-
-### Option 2: New `mew space connect` command
-
-Create a dedicated command for interactive connection:
-```bash
-mew space connect # Connect to current space
-mew space connect --participant alice
-mew space connect --space-dir ../other-space
-```
-
-**Pros:**
-- Clear separation of concerns
-- Can connect to any running space
-- More flexible connection options
-- Follows pattern of other tools (docker exec, kubectl exec)
-
-**Cons:**
-- Additional command to learn
-- Requires space to be already running
-
-### Option 3: Extend `mew client connect` with interactive mode
-
-Make the existing client command interactive by default:
-```bash
-mew client connect --gateway ws://localhost:8080 --space test
-# If no --fifo flags, runs interactively
-```
-
-**Pros:**
-- Builds on existing command
-- Already has connection logic
-- Natural extension of current functionality
-
-**Cons:**
-- Requires manual specification of gateway/space/token
-- Doesn't leverage space.yaml configuration
-- More complex for simple "just connect me" use case
-
-### Option 4: Both `--interactive` flag and `connect` command
-
-Implement both approaches for maximum flexibility:
-```bash
-mew space up -i # Start and connect
-mew space connect # Connect to running space
-```
-
-**Pros:**
-- Covers all use cases optimally
-- Natural workflow for both scenarios
-- Progressive disclosure of complexity
-
-**Cons:**
-- More implementation work
-- Potential confusion about which to use
-
-## Decision
-
-Implement **Option 4: Both `--interactive` flag and `connect` command**.
-
-This provides the best user experience for both common workflows:
-1. Starting fresh: `mew space up -i`
-2. Connecting to existing: `mew space connect`
-
-### Implementation Details
-
-#### `mew space up --interactive`
-
-Extends the existing command:
-```bash
-mew space up [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --port Gateway port (default: from config or 8080)
- --participant Connect as this participant
- --interactive, -i Connect interactively after starting space
- --detach, -d Run in background (incompatible with -i)
-```
-
-Behavior:
-1. Start the space normally (gateway, agents)
-2. If `-i` flag is present:
- - Resolve participant (same logic as current)
- - Connect interactively to the space
- - Show interactive prompt
-3. If `-d` flag is present:
- - Start space in background
- - Exit immediately (current behavior)
-4. If neither flag:
- - Current behavior (start and exit)
-
-#### `mew space connect`
-
-New command for connecting to running spaces:
-```bash
-mew space connect [options]
-
-Options:
- --space-config Path to space.yaml (default: ./space.yaml)
- --participant Connect as this participant
- --space-dir Directory of space to connect to (default: .)
- --gateway Override gateway URL (default: from running space)
-```
-
-Behavior:
-1. Check if space is running in current/specified directory
-2. Load space configuration
-3. Resolve participant (same logic as `space up`)
-4. Connect interactively
-5. Show interactive prompt
-
-Error handling:
-- If space not running: "No running space found. Use 'mew space up' first."
-- If no participant resolved: "No participant found. Specify with --participant"
-- If connection fails: Show helpful error with gateway URL
-
-#### Participant Resolution (shared logic)
-
-Both commands use the same participant resolution:
-1. Explicit `--participant ` flag
-2. Space config `default_participant` field
-3. Single human participant (no `command` field)
-4. Interactive selection from human participants
-5. System username match
-6. Error if none found
-
-#### Interactive Mode Override
-
-When in interactive mode, certain participant configurations are overridden:
-- `fifo: true` → Ignored (use interactive terminal instead)
-- `output_log` → Ignored (output to terminal)
-- `auto_connect` → Ignored (we're manually connecting)
-
-The interactive connection always uses:
-- Terminal input (stdin)
-- Terminal output (stdout)
-- Readline-based interface
-
-## Consequences
-
-### Positive
-- Natural workflow for development and debugging
-- No need for FIFOs or external tools
-- Leverages existing space configuration
-- Simple commands for common tasks
-- Can connect/reconnect without restarting space
-
-### Negative
-- Two ways to achieve similar outcome (potential confusion)
-- Additional command increases API surface
-- Need to maintain interactive terminal code
-
-### Security Considerations
-- Interactive mode uses participant tokens from space.yaml
-- No additional authentication beyond token
-- Terminal history may contain sensitive commands
-
-## Migration Path
-
-1. **Phase 1**: Implement shared participant resolution logic
-2. **Phase 2**: Add `--interactive` flag to `space up`
-3. **Phase 3**: Implement `space connect` command
-4. **Phase 4**: Deprecate test-interactive.js script
-
-## Examples
-
-### Development Workflow
-```bash
-# Start fresh and connect immediately
-mew space up -i
-
-# In another terminal, connect as different participant
-mew space connect --participant admin
-
-# Connect to space in another directory
-mew space connect --space-dir ../other-project
-```
-
-### Testing Workflow
-```bash
-# Start space in background
-mew space up -d
-
-# Run automated tests...
-
-# Connect to debug issue
-mew space connect --participant debugger
-
-# Clean up
-mew space down
-```
-
-### Configuration Example
-```yaml
-# space.yaml
-space:
- id: dev-space
- default_participant: developer # Used by interactive connection
-
-participants:
- developer:
- tokens: ["dev-token"]
- capabilities:
- - kind: "*" # Full access for debugging
- # No fifo or output_log - these are for automation
-
- test-client:
- tokens: ["test-token"]
- fifo: true # Only used in non-interactive mode
- output_log: "./logs/test.log"
-```
-
-## Future Enhancements
-
-1. **Connection management**:
- - `mew space connect --list` - Show available participants
- - `mew space connect --reconnect` - Reconnect after disconnect
-
-2. **Multiple interactive sessions**:
- - Allow multiple terminals to connect as different participants
- - Show participant ID in prompt
-
-3. **Output modes**:
- - `--json` - Output raw protocol messages
- - `--pretty` - Enhanced formatting
- - `--quiet` - Suppress system messages
\ No newline at end of file
diff --git a/spec/cli/proposals/README.md b/spec/cli/proposals/README.md
new file mode 100644
index 00000000..48cbe6a1
--- /dev/null
+++ b/spec/cli/proposals/README.md
@@ -0,0 +1,5 @@
+# CLI Proposals
+
+Proposals for changes to the MEW CLI. Status tracked in `/CHANGELOG.md`.
+
+See `/CONTRIBUTING.md` for the proposal workflow.
diff --git a/spec/cli/accepted/011-agi-adapt-gemini-input-implementation.md b/spec/cli/proposals/agi-adapt-gemini-input-implementation.md
similarity index 100%
rename from spec/cli/accepted/011-agi-adapt-gemini-input-implementation.md
rename to spec/cli/proposals/agi-adapt-gemini-input-implementation.md
diff --git a/spec/cli/accepted/007-aim-advanced-interactive-mode.md b/spec/cli/proposals/aim-advanced-interactive-mode.md
similarity index 100%
rename from spec/cli/accepted/007-aim-advanced-interactive-mode.md
rename to spec/cli/proposals/aim-advanced-interactive-mode.md
diff --git a/spec/cli/accepted/009-aud-approval-dialog-ux.md b/spec/cli/proposals/aud-approval-dialog-ux.md
similarity index 100%
rename from spec/cli/accepted/009-aud-approval-dialog-ux.md
rename to spec/cli/proposals/aud-approval-dialog-ux.md
diff --git a/spec/archive/cli/v0.1.0/decisions/accepted/002-cln-space-cleanup-command.md b/spec/cli/proposals/cln-space-cleanup-command.md
similarity index 100%
rename from spec/archive/cli/v0.1.0/decisions/accepted/002-cln-space-cleanup-command.md
rename to spec/cli/proposals/cln-space-cleanup-command.md
diff --git a/spec/cli/accepted/001-evd-environment-variable-defaults.md b/spec/cli/proposals/evd-environment-variable-defaults.md
similarity index 100%
rename from spec/cli/accepted/001-evd-environment-variable-defaults.md
rename to spec/cli/proposals/evd-environment-variable-defaults.md
diff --git a/spec/cli/accepted/008-f4x-safe-fifo-input-mechanism.md b/spec/cli/proposals/f4x-safe-fifo-input-mechanism.md
similarity index 100%
rename from spec/cli/accepted/008-f4x-safe-fifo-input-mechanism.md
rename to spec/cli/proposals/f4x-safe-fifo-input-mechanism.md
diff --git a/spec/archive/cli/v0.1.0/decisions/accepted/003-fio-flexible-fifo-handling.md b/spec/cli/proposals/fio-flexible-fifo-handling.md
similarity index 100%
rename from spec/archive/cli/v0.1.0/decisions/accepted/003-fio-flexible-fifo-handling.md
rename to spec/cli/proposals/fio-flexible-fifo-handling.md
diff --git a/spec/cli/accepted/014-get-gateway-envelope-tracing.md b/spec/cli/proposals/get-gateway-envelope-tracing.md
similarity index 100%
rename from spec/cli/accepted/014-get-gateway-envelope-tracing.md
rename to spec/cli/proposals/get-gateway-envelope-tracing.md
diff --git a/spec/archive/cli/v0.1.0/decisions/accepted/004-int-interactive-connection.md b/spec/cli/proposals/int-interactive-connection.md
similarity index 100%
rename from spec/archive/cli/v0.1.0/decisions/accepted/004-int-interactive-connection.md
rename to spec/cli/proposals/int-interactive-connection.md
diff --git a/spec/cli/accepted/005-iui-interactive-ui-architecture.md b/spec/cli/proposals/iui-interactive-ui-architecture.md
similarity index 100%
rename from spec/cli/accepted/005-iui-interactive-ui-architecture.md
rename to spec/cli/proposals/iui-interactive-ui-architecture.md
diff --git a/spec/cli/accepted/001-msd-mcp-server-dependencies.md b/spec/cli/proposals/msd-mcp-server-dependencies.md
similarity index 100%
rename from spec/cli/accepted/001-msd-mcp-server-dependencies.md
rename to spec/cli/proposals/msd-mcp-server-dependencies.md
diff --git a/spec/archive/cli/v0.1.0/decisions/accepted/001-pmg-process-manager.md b/spec/cli/proposals/pmg-process-manager.md
similarity index 100%
rename from spec/archive/cli/v0.1.0/decisions/accepted/001-pmg-process-manager.md
rename to spec/cli/proposals/pmg-process-manager.md
diff --git a/spec/cli/proposed/013-sac-slash-command-parameter-architecture.md b/spec/cli/proposals/sac-slash-command-parameter-architecture.md
similarity index 100%
rename from spec/cli/proposed/013-sac-slash-command-parameter-architecture.md
rename to spec/cli/proposals/sac-slash-command-parameter-architecture.md
diff --git a/spec/cli/accepted/012-stg-secure-token-generation.md b/spec/cli/proposals/stg-secure-token-generation.md
similarity index 100%
rename from spec/cli/accepted/012-stg-secure-token-generation.md
rename to spec/cli/proposals/stg-secure-token-generation.md
diff --git a/spec/cli/accepted/010-tie-terminal-input-enhancements.md b/spec/cli/proposals/tie-terminal-input-enhancements.md
similarity index 100%
rename from spec/cli/accepted/010-tie-terminal-input-enhancements.md
rename to spec/cli/proposals/tie-terminal-input-enhancements.md
diff --git a/spec/cli/accepted/006-tui-terminal-ui-library-selection.md b/spec/cli/proposals/tui-terminal-ui-library-selection.md
similarity index 100%
rename from spec/cli/accepted/006-tui-terminal-ui-library-selection.md
rename to spec/cli/proposals/tui-terminal-ui-library-selection.md
diff --git a/spec/cli/proposed/README.md b/spec/cli/proposed/README.md
deleted file mode 100644
index d2dfe175..00000000
--- a/spec/cli/proposed/README.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Proposed ADRs for CLI
-
-This directory contains Architecture Decision Records (ADRs) that are under consideration for the MEW CLI.
-
-## Current Proposals
-
-*No pending proposals - all ADRs have been accepted and incorporated*
-
-## Recently Accepted (moved to accepted/)
-
-- **006-tui**: Terminal UI Library Selection - Incorporated v0.2.0
-- **007-aim**: Advanced Interactive Mode - Incorporated v0.2.0
-- **008-f4x**: Safe FIFO Input Mechanism - Incorporated v0.2.0
-- **010-tie**: Terminal Input Enhancements - Incorporated v0.4.2
-- **011-agi**: Adapt Gemini CLI Input Implementation - Incorporated v0.4.2
-- **012-stg**: Secure Token Generation - Incorporated v0.3.3
-
-## Process
-
-1. Create ADR in this directory with status "Proposed"
-2. Discuss and refine
-3. Incorporate into SPEC.md
-4. Update incorporation status to "Complete"
-5. Move to accepted/ or rejected/ directory
-
-See [SPEC-GUIDE.md](/SPEC-GUIDE.md) for the full ADR process.
\ No newline at end of file
diff --git a/spec/protocol/README.md b/spec/protocol/README.md
index ba48bbe8..d0291489 100644
--- a/spec/protocol/README.md
+++ b/spec/protocol/README.md
@@ -1,59 +1,7 @@
-# MCPx Protocol Specifications
+# MEW Protocol Specification
-This directory contains the protocol specifications for MCPx (MCP Extension Protocol), which extends the Model Context Protocol for multi-agent coordination.
+The MEW Protocol enables multi-participant coordination through topic-based messaging with MCP tool integration.
-## Structure
+**Current Version**: v0.4
-```
-protocol-spec/
-├── README.md # This file
-└── v0/ # Version 0 of the protocol
- ├── SPEC.md # Main protocol specification
- ├── PATTERNS.md # Common implementation patterns
- ├── ARCHITECTURE.md # System architecture
- └── decisions/ # Protocol design decisions
- └── decision-1.md
-```
-
-## Contents
-
-### v0/
-The initial version of the MCPx protocol specification:
-
-- **[SPEC.md](v0/SPEC.md)** - The complete MCPx v0 protocol specification defining envelope format, messaging patterns, and gateway API
-- **[PATTERNS.md](v0/PATTERNS.md)** - Common implementation patterns and best practices for MCPx
-- **[ARCHITECTURE.md](v0/ARCHITECTURE.md)** - System architecture and implementation details
-- **[decisions/](v0/decisions/)** - Architecture decision records documenting protocol design choices
-
-## Overview
-
-MCPx extends the Model Context Protocol (MCP) to enable multiple participants (humans, agents, robots) to coordinate in shared topics. It provides:
-
-- **Topic-based rooms**: Named spaces where participants interact
-- **Envelope protocol**: Message wrapping for routing and correlation
-- **Peer-to-peer MCP**: All participants act as MCP servers
-- **Real-time gateway**: WebSocket-based messaging with presence
-- **Unified participation**: Humans, agents, and robots as equal peers
-
-## Key Concepts
-
-- **Topics**: Named rooms (e.g., `room:alpha`) where participants collaborate
-- **Participants**: Any client that joins a topic and exposes MCP tools
-- **Envelopes**: JSON wrappers containing MCP messages with routing metadata
-- **Visibility**: All messages in a topic are visible to all participants (no privacy at protocol layer)
-
-## Version History
-
-- **v0** (Current) - Initial specification focusing on MCP tools, WebSocket transport, and core envelope format
-
-## Related Specifications
-
-- **SDK Specification**: See [`../sdk-spec/`](../sdk-spec/) for MCPx SDK architecture and client libraries
-- **MCP Specification**: See [`../../modelcontextprotocol/`](../../modelcontextprotocol/) for the base Model Context Protocol
-
-## Quick Links
-
-- [Protocol Specification](v0/SPEC.md) - Main MCPx v0 specification
-- [Implementation Patterns](v0/PATTERNS.md) - Common patterns and examples
-- [System Architecture](v0/ARCHITECTURE.md) - Architecture overview
-- [SDK Architecture](../sdk-spec/mcpx-sdk-architecture.md) - Client and agent libraries
\ No newline at end of file
+See [SPEC.md](SPEC.md) for the complete specification.
diff --git a/spec/protocol/draft/SPEC.md b/spec/protocol/SPEC.md
similarity index 100%
rename from spec/protocol/draft/SPEC.md
rename to spec/protocol/SPEC.md
diff --git a/spec/protocol/draft/accepted/README.md b/spec/protocol/draft/accepted/README.md
deleted file mode 100644
index 6636e72c..00000000
--- a/spec/protocol/draft/accepted/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Accepted ADRs
-
-This folder contains accepted Architecture Decision Records for the next version of the MEUP protocol.
-
-## Current Status
-
-No accepted ADRs for the next version yet. All v0.2 ADRs are in `/spec/v0.2/decisions/accepted/`.
-
-## Format
-
-When ADRs are accepted from `proposed/`:
-- Maintain the same filename (including proposal number)
-- Update Status to "Accepted"
-- Track Incorporation status as implementation progresses
\ No newline at end of file
diff --git a/spec/protocol/draft/decisions-README.md b/spec/protocol/draft/decisions-README.md
deleted file mode 100644
index bc0b27bc..00000000
--- a/spec/protocol/draft/decisions-README.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Draft Protocol Decisions
-
-This directory will contain Architecture Decision Records (ADRs) for the next version of the MEUP protocol.
-
-## Current Status
-
-No active decisions for the draft version. All v0.2 decisions have been incorporated and are available in `/spec/v0.2/decisions/`.
-
-## Directory Structure
-
-- `proposed/` - ADRs under consideration for the next version
-- `accepted/` - Approved ADRs for the next version
-- `rejected/` - Rejected ADRs kept for historical context
-
-## Creating New ADRs
-
-When proposing changes for the next protocol version:
-
-1. Create ADR in `proposed/` with format: `[number]-[id]-[name].md`
-2. Use unique 3-character ID (e.g., `a1b`)
-3. Follow ADR template from `/spec/CLAUDE.md`
-4. Reference this as "MEUP Protocol Next" or specific version when known
-
-## Previous Versions
-
-- **v0.2 decisions**: `/spec/v0.2/decisions/` - Current released protocol
-- **v0.1 decisions**: Historical (if any)
\ No newline at end of file
diff --git a/spec/protocol/draft/proposed/README.md b/spec/protocol/draft/proposed/README.md
deleted file mode 100644
index 6730060f..00000000
--- a/spec/protocol/draft/proposed/README.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Proposed ADRs
-
-This folder contains ADRs (Architecture Decision Records) that are currently under consideration for the next version of the MEUP protocol.
-
-## Format
-
-**Filename:** `[proposal-number]-[adr-id]-[descriptive-name].md`
-
-- **Proposal number:** Sequential number based on order of proposal (001, 002, etc.)
-- **ADR ID:** Unique 3-character alphanumeric identifier (e.g., x7k, m3p)
-- **Descriptive name:** Kebab-case description of the decision
-
-## Current Proposals
-
-(Currently empty - no active proposals for the next version)
-
-## Process
-
-1. Create new ADR with next sequential number and unique ID
-2. Status should be "Proposed"
-3. Incorporation should be "Not Incorporated"
-4. Follow the ADR template in `/spec/CLAUDE.md`
-5. After review, ADR moves to either `accepted/` or `rejected/`
\ No newline at end of file
diff --git a/spec/protocol/draft/rejected/README.md b/spec/protocol/draft/rejected/README.md
deleted file mode 100644
index a34f546e..00000000
--- a/spec/protocol/draft/rejected/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Rejected ADRs
-
-This folder contains rejected Architecture Decision Records kept for historical context.
-
-## Current Status
-
-The following draft ADRs were rejected while preparing MEW Protocol v0.4:
-- ADR-REN — Rename Participant to Entity
-- ADR-WCM — Where to Put MCP Request/Proposal Auto-Conversion Logic
-- ADR-DSA — Data Stream Announcements (superseded by incorporated stream guidance)
-- ADR-002 — Join Protocol Extension for Space Participation
-- ADR-CTX — Simplify Context Terminology
-- ADR-009 — Gateway I/O Options for Participant Communication (scope-limited to WebSocket for v0.4)
-
-## Format
-
-When ADRs are rejected from `proposed/`:
-- Renumber based on rejection order
-- Maintain the ADR ID for reference
-- Update Status to "Rejected"
-- Add rejection rationale to the document
diff --git a/spec/protocol/proposals/README.md b/spec/protocol/proposals/README.md
new file mode 100644
index 00000000..048ea606
--- /dev/null
+++ b/spec/protocol/proposals/README.md
@@ -0,0 +1,5 @@
+# Protocol Proposals
+
+Proposals for changes to the MEW Protocol. Status tracked in `/CHANGELOG.md`.
+
+See `/CONTRIBUTING.md` for the proposal workflow.
diff --git a/spec/protocol/draft/rejected/001-ren-participant-to-entity.md b/spec/protocol/rejected/001-ren-participant-to-entity.md
similarity index 100%
rename from spec/protocol/draft/rejected/001-ren-participant-to-entity.md
rename to spec/protocol/rejected/001-ren-participant-to-entity.md
diff --git a/spec/protocol/draft/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md b/spec/protocol/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md
similarity index 100%
rename from spec/protocol/draft/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md
rename to spec/protocol/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md
diff --git a/spec/protocol/draft/rejected/002-dsa-data-stream-announcements.md b/spec/protocol/rejected/002-dsa-data-stream-announcements.md
similarity index 100%
rename from spec/protocol/draft/rejected/002-dsa-data-stream-announcements.md
rename to spec/protocol/rejected/002-dsa-data-stream-announcements.md
diff --git a/spec/protocol/draft/rejected/002-join-protocol-extension.md b/spec/protocol/rejected/002-join-protocol-extension.md
similarity index 100%
rename from spec/protocol/draft/rejected/002-join-protocol-extension.md
rename to spec/protocol/rejected/002-join-protocol-extension.md
diff --git a/spec/protocol/draft/rejected/003-ctx-simplify-context-terminology.md b/spec/protocol/rejected/003-ctx-simplify-context-terminology.md
similarity index 100%
rename from spec/protocol/draft/rejected/003-ctx-simplify-context-terminology.md
rename to spec/protocol/rejected/003-ctx-simplify-context-terminology.md
diff --git a/spec/protocol/draft/rejected/009-gateway-io-options.md b/spec/protocol/rejected/009-gateway-io-options.md
similarity index 100%
rename from spec/protocol/draft/rejected/009-gateway-io-options.md
rename to spec/protocol/rejected/009-gateway-io-options.md
diff --git a/spec/protocol/rejected/README.md b/spec/protocol/rejected/README.md
new file mode 100644
index 00000000..44c5801a
--- /dev/null
+++ b/spec/protocol/rejected/README.md
@@ -0,0 +1,3 @@
+# Rejected Proposals
+
+Proposals that were considered but not accepted, preserved for historical context and learning.
diff --git a/spec/protocol/v0.4/SPEC.md b/spec/protocol/v0.4/SPEC.md
deleted file mode 100644
index f330d518..00000000
--- a/spec/protocol/v0.4/SPEC.md
+++ /dev/null
@@ -1,1572 +0,0 @@
-# MEW Protocol v0.4 Specification
-
-Version: v0.4
-Status: Released
-Release Date: 2025-09-26
-Intended Status: Experimental
-Editors: RJ Corwin (https://github.com/rjcorwin)
-
----
-
-## Requirements Language
-
-The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119 and RFC 8174.
-
----
-
-## 1. Abstract
-
-MEW Protocol (Multi-Entity Workspace Protocol) provides a unified context where all agent-to-agent and agent-to-tool interactions are visible and controllable at the protocol layer. The name playfully evokes "herding cats" - the quintessential challenge of coordinating multiple independent, autonomous agents who each have their own goals and behaviors. Unlike traditional systems where AI coordination happens in hidden contexts, MEW Protocol broadcasts all messages within a shared workspace, enabling participants to observe everything and privileged users to approve or reject actions through a proposal-review pattern. The protocol extends MCP semantics while adding capability-based access control, allowing untrusted agents to propose operations that trusted participants execute. This transparency enables progressive automation, where systems learn from human decisions to safely expand their autonomous capabilities over time - essentially teaching the "cats" to work together effectively.
-
----
-
-## 2. Goals and Non-Goals
-
-### 2.1 Goals
-- **Unified Context**: All participants share the same visible stream of interactions
-- **Protocol-Level Control**: Control actions through capabilities and proposals, not application wrappers
-- **Progressive Automation**: Learn from human decisions to safely expand autonomous operations
-- **Tool Compatibility**: Preserve existing MCP tool and resource interfaces
-
-### 2.2 Non-Goals
-- End-to-end encryption or private channels (all messages visible within space)
-- Message persistence or replay (spaces are ephemeral)
-- Cross-space routing or participant discovery
-- Guaranteed delivery or ordering (WebSocket best-effort)
-- Application-specific semantics beyond MCP operations
-- Configuration management (implementation-specific)
-
----
-
-## 3. Message Envelope
-
-All data flowing over a space MUST be a single top-level JSON envelope:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "2f6b6e70-7b36-4b8b-9ad8-7c4f7d0e2d0b",
- "ts": "2025-08-26T14:00:00Z",
- "from": "robot-alpha",
- "to": ["coordinator"],
- "kind": "mcp/request",
- "correlation_id": ["env-1"],
- "context": "workflow-123/step-1",
- "payload": { /* kind-specific body */ }
-}
-```
-
-Field semantics:
-- `protocol`: MUST be `"mew/v0.4"` for this version
-- `id`: globally unique message id (e.g., UUIDv4)
-- `ts`: RFC3339 timestamp
-- `from`: stable participant id within the space
-- `to`: array of participant ids (empty/omitted = broadcast)
-- `kind`: Message type using minimal kinds:
- - `mcp/request` - MCP request/notification
- - `mcp/response` - MCP response
- - `mcp/proposal` - MCP proposal for operations
- - `mcp/withdraw` - Withdraw a proposal
- - `mcp/reject` - Reject a proposal
- - `reasoning/start` - Begin reasoning sequence
- - `reasoning/thought` - Reasoning monologue (thinking out loud)
- - `reasoning/conclusion` - End reasoning sequence
- - `reasoning/cancel` - Abort an in-progress reasoning sequence
- - `capability/grant` - Grant capabilities to participant
- - `capability/revoke` - Revoke capabilities from participant
- - `capability/grant-ack` - Acknowledge capability grant
- - `space/invite` - Invite participant to space
- - `space/kick` - Remove participant from space
- - `participant/pause` - Pause outbound activity from a participant
- - `participant/resume` - Resume a participant after a pause
- - `participant/status` - Report usage status (e.g., tokens consumed vs. maximum) including current message counts per context
- - `participant/request-status` - Ask a participant to emit its current status
- - `participant/forget` - Instruct a participant to drop cached context (oldest or newest data)
- - `participant/compact` - Request that a participant compact its working memory to free headroom
- - `participant/compact-done` - Participant acknowledgement that compaction is complete
- - `participant/clear` - Wipe the participant's entire conversational context or scratchpad
- - `participant/restart` - Restart a participant back to a known baseline state
- - `participant/shutdown` - Request an orderly shutdown that ends activity without restarting
- - `stream/request` - Ask the gateway to establish a new data stream
- - `stream/open` - Gateway confirms stream creation with assigned identifier
- - `stream/close` - Close a previously opened stream
- - `chat` - Chat messages
- - `chat/acknowledge` - Confirm receipt of a chat message
- - `chat/cancel` - Withdraw attention from a chat message that no longer needs action
- - `system/presence` - Join/leave events
- - `system/welcome` - Welcome message for new participants
- - `system/error` - System error messages
-- `correlation_id`: array of message IDs this message relates to (always an array, even for single values)
- - Response → Request: `mcp/response` MUST reference the originating `mcp/request`
- - Fulfillment → Proposal: `mcp/request` MAY reference a `mcp/proposal` when fulfilling it
- - Withdraw → Proposal: `mcp/withdraw` MUST reference the proposal being withdrawn
- - Reject → Proposal: `mcp/reject` MUST reference the proposal being rejected
- - Error → Trigger: `system/error` messages SHOULD reference the envelope that caused the error
- - Reply → Message: Any envelope MAY reference others to indicate explicit reply intent (use `context` field for threading)
- - Workflow → Multiple: Messages in complex workflows MAY reference multiple related messages (e.g., a summary referencing several analyses, a decision based on multiple proposals, a response addressing multiple questions)
- - Fork/Join → Multiple: A response that combines results from multiple parallel requests
- - The array structure supports complex multi-party coordination and DAG-like message flows
-- `context`: (optional) string representing the context or sub-context for this message
- - Path-based hierarchy using forward slashes: `"parent/child/grandchild"`
- - Messages in sub-contexts (reasoning, workflows) include this field for organization
- - Context groups related messages together (e.g., all thoughts in a reasoning sequence)
- - When prompting LLMs, implementations MAY filter contexts to reduce noise
- - IMPORTANT: Messages addressed to a participant (via `to` field) MUST be handled regardless of context
-- `payload`: object; structure depends on `kind`
-
-### 3.1 MCP Messages
-
-MCP messages use minimal kinds with method information in the payload:
-- `kind: "mcp/request"` for requests/notifications
-- `kind: "mcp/response"` for responses
-- `kind: "mcp/proposal"` for proposals
-- `kind: "mcp/withdraw"` for withdrawing proposals
-- `kind: "mcp/reject"` for rejecting proposals
-- The specific method (e.g., `tools/call`, `resources/read`) is in `payload.method`
-
-#### 3.1.1 MCP Requests
-
-Example tool call request:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-call-1",
- "from": "trusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-#### 3.1.2 MCP Responses
-
-Responses MUST include the `correlation_id` field referencing the original request's `id`. This is critical for translating MCP's client-server request/response model to MEW Protocol's multi-participant broadcast paradigm, allowing all participants to match responses to their corresponding requests.
-
-Response to the above tool call:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-resp-1",
- "from": "target-agent",
- "to": ["trusted-agent"],
- "kind": "mcp/response",
- "correlation_id": ["env-call-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 42,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed"
- }]
- }
- }
-}
-```
-
-Note: The MCP payload structure remains unchanged from standard MCP.
-
-### 3.2 MCP Proposals
-
-Participants with restricted capabilities MUST use proposals instead of direct MCP operations. Proposals have the same payload structure as requests:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-req-1",
- "from": "untrusted-agent",
- "to": ["target-agent"],
- "kind": "mcp/proposal",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-This is a MEW Protocol-specific extension that proposes an MCP operation requiring fulfillment by a participant with appropriate capabilities.
-
-#### 3.2.1 Proposal Fulfillment
-
-A participant with appropriate capabilities fulfills the proposal by making the real MCP call. The `correlation_id` field is critical for matching approvals to their original proposals:
-- Proposals typically don't include `correlation_id` (they originate new workflows)
-- Fulfillment messages MUST include `correlation_id` referencing the proposal's `id`
-- This allows participants to track which fulfillment corresponds to which proposal
-- The correlation chain enables audit trails and multi-step approval workflows
-
-Example fulfillment:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-fulfill-1",
- "from": "human-user",
- "to": ["target-agent"],
- "kind": "mcp/request",
- "correlation_id": ["env-req-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "method": "tools/call",
- "params": {
- "name": "dangerous_operation",
- "arguments": {"target": "production"}
- }
- }
-}
-```
-
-The response goes only to the fulfiller who made the request. The response's `correlation_id` references the fulfillment message (`env-fulfill-1`), maintaining the standard request/response pairing. The original proposer can observe the outcome since messages are broadcast by default:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-fulfill-resp-1",
- "from": "target-agent",
- "to": ["human-user"],
- "kind": "mcp/response",
- "correlation_id": ["env-fulfill-1"],
- "payload": {
- "jsonrpc": "2.0",
- "id": 44,
- "result": {
- "content": [{
- "type": "text",
- "text": "Operation completed successfully"
- }]
- }
- }
-}
-```
-
-The proposer can follow the correlation chain to track the outcome:
-1. Proposer sends proposal (`env-req-1`)
-2. Fulfiller sends request with `correlation_id: ["env-req-1"]` (`env-fulfill-1`)
-3. Target sends response with `correlation_id: ["env-fulfill-1"]` (`env-fulfill-resp-1`)
-4. Proposer observes the broadcast response and can trace back through the correlation chain
-
-### 3.3 Proposal Lifecycle Operations
-
-MEW Protocol extends the proposal pattern with lifecycle operations for cancellation and feedback.
-
-#### 3.3.1 Withdraw Proposals (kind = "mcp/withdraw")
-
-Proposers can withdraw their own proposals that are no longer needed:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "withdraw-456",
- "from": "untrusted-agent",
- "correlation_id": ["env-req-1"],
- "kind": "mcp/withdraw",
- "payload": {
- "reason": "no_longer_needed"
- }
-}
-```
-
-- Only the original proposer can withdraw their proposals
-- `correlation_id` MUST reference the proposal being withdrawn
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.2 Reject Proposals (kind = "mcp/reject")
-
-Any participant with the capability can reject proposals. Rejections provide early feedback to avoid unnecessary waiting:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "reject-789",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["env-req-1"],
- "kind": "mcp/reject",
- "payload": {
- "reason": "unsafe"
- }
-}
-```
-
-**Purpose and Behavior:**
-- Prevents proposers from waiting unnecessarily for fulfillment that won't come
-- Particularly important when explicitly targeted in a proposal's `to` field
-- Proposers MAY give up after the first rejection (fail-fast approach)
-- Proposers MAY continue waiting for other participants to fulfill (resilient approach)
-- The choice depends on the proposer's implementation and use case
-- Multiple participants may reject the same proposal for different reasons
-
-**Requirements:**
-- `correlation_id` MUST reference the proposal being rejected
-- `reason` field uses standardized codes (see below)
-
-#### 3.3.3 Standardized Reason Codes
-
-Lifecycle operations may use the following suggested reason codes (optional and non-normative):
-
-- `"disagree"` - Don't agree with the proposed action
-- `"inappropriate"` - Not suitable for the current context
-- `"unsafe"` - Could cause harm or unintended consequences
-- `"busy"` - Currently handling other work
-- `"incapable"` - Don't have the required tools/access
-- `"policy"` - Violates security or operational policy
-- `"duplicate"` - Already being handled by another participant
-- `"invalid"` - Proposal is malformed or impossible
-- `"timeout"` - Too old or expired
-- `"resource_limit"` - Would exceed resource constraints
-- `"no_longer_needed"` - Proposer no longer needs the operation
-- `"other"` - Reason not covered above
-
-These reason codes are suggestions only; participants MAY use other reason strings and MUST handle unknown codes gracefully.
-
-Detailed explanations can be provided via follow-up chat messages using `correlation_id`:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "chat-790",
- "from": "filesystem-agent",
- "to": ["untrusted-agent"],
- "correlation_id": ["reject-789"],
- "kind": "chat",
- "payload": {
- "text": "I'm currently processing a large batch operation that requires exclusive file access. Please retry in about 5 minutes.",
- "format": "plain"
- }
-}
-```
-
-**Important timing consideration:** The reject message with a reason code should be sent immediately for fast feedback. Detailed explanations may arrive later as generating them (especially with LLMs) can take time. Participants implementing proposers should:
-- Process the reject immediately upon receipt
-- Optionally wait for follow-up explanations if they need details
-- Not block on explanations that may never come
-
-### 3.4 Chat Messages (kind = "chat")
-
-Chat messages are MEW Protocol-specific and do not pollute the MCP namespace:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-chat-1",
- "from": "user-alice",
- "kind": "chat",
- "payload": {
- "text": "Hello everyone!",
- "format": "plain"
- }
-}
-```
-
-- `text` (required): The message content
-- `format` (optional): "plain" or "markdown", defaults to "plain"
-- Chat messages are typically broadcast (empty/omitted `to` array)
-
-#### 3.4.1 Chat Acknowledge (kind = "chat/acknowledge")
-
-Acknowledges receipt of a chat message without generating additional conversation content. Useful when participants need to
-signal that they observed a chat entry but have no substantive reply:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "chat-ack-1",
- "from": "agent-1",
- "kind": "chat/acknowledge",
- "correlation_id": ["env-chat-1"],
- "payload": {
- "status": "received"
- }
-}
-```
-
-- `correlation_id` MUST reference the chat envelope being acknowledged
-- `payload.status` conveys acknowledgement semantics (implementations MAY standardize values like `"received"` or
- `"read"`)
-- Gateways MAY suppress broadcasting acknowledgements to reduce noise, but if delivered they provide an auditable confirmation
- that the message was seen
-- User interfaces often surface a **queue of chat messages awaiting acknowledgement** so that humans and agents can close the
- loop explicitly. Clearing that queue SHOULD emit acknowledgements for each entry to provide an auditable trail.
-
-#### 3.4.2 Chat Cancel (kind = "chat/cancel")
-
-Signals that an earlier chat message no longer requires attention. This helps UIs and agents clear acknowledgement queues and
-avoid stale follow-ups:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "chat-cancel-1",
- "from": "user-alice",
- "kind": "chat/cancel",
- "to": ["agent-1"],
- "correlation_id": ["env-chat-1"],
- "payload": {
- "reason": "handled elsewhere"
- }
-}
-```
-
-- `correlation_id` MUST reference the chat message that is being cancelled
-- `payload.reason` SHOULD communicate why the message no longer needs attention (e.g., `"handled_elsewhere"`,
- `"duplicate"`, `"timeout"`)
-- UIs MAY provide a shortcut to cancel **all** unacknowledged chat messages, emitting one cancellation per message to keep
- participants in sync
-
-### 3.5 Reasoning Transparency
-
-MEW Protocol supports transparent reasoning through dedicated message kinds and the context field. This allows agents to share their thinking process while maintaining clear boundaries between reasoning sequences and regular operations.
-
-#### 3.5.1 Reasoning Pattern
-
-Common patterns for transparent reasoning:
-
-**Response Pattern:**
-1. Agent receives a request (e.g., `mcp/request`)
-2. Agent sends `reasoning/start` with `correlation_id` referencing the request
-3. The `reasoning/start` message ID becomes the `context` for subsequent messages
-4. Agent MAY send `reasoning/thought` messages for internal monologue (optional)
-5. Agent MAY use `chat` messages within context for dialogue with other participants
-6. Agent MAY send `reasoning/conclusion` to summarize findings (optional)
-7. Agent sends final response with `correlation_id` to original request
-
-**Autonomous Pattern:**
-- Agent sends `reasoning/start` at any time (e.g., periodic analysis, monitoring)
-- The `reasoning/start` creates a context for transparent thinking
-- Agent shares thoughts as they occur
-- No response required - purely for transparency
-
-Note: `reasoning/start` creates a context for transparency. Whether responding to requests or reasoning autonomously, it lets other participants observe the agent's thinking process.
-
-#### 3.5.2 Reasoning Start (kind = "reasoning/start")
-
-Signals the beginning of a reasoning sequence:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "reason-start-1",
- "from": "agent-1",
- "kind": "reasoning/start",
- "correlation_id": ["req-123"],
- "payload": {
- "message": "Analyzing the request to modify the configuration file..."
- }
-}
-```
-
-#### 3.5.3 Reasoning Thought (kind = "reasoning/thought")
-
-Shares internal reasoning steps (monologue, no reply expected):
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "thought-1",
- "from": "agent-1",
- "kind": "reasoning/thought",
- "context": "reason-start-1",
- "payload": {
- "message": "The configuration file appears to use YAML format. I should validate the syntax before making changes."
- }
-}
-```
-
-#### 3.5.4 Reasoning Conclusion (kind = "reasoning/conclusion")
-
-Concludes the reasoning sequence:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "reason-end-1",
- "from": "agent-1",
- "kind": "reasoning/conclusion",
- "context": "reason-start-1",
- "payload": {
- "message": "Configuration update is safe to proceed. The changes are valid YAML and won't break existing settings."
- }
-}
-```
-
-#### 3.5.5 Reasoning Cancel (kind = "reasoning/cancel")
-
-Terminates an active reasoning sequence without providing a conclusion. Useful when the initiating trigger is withdrawn or the
-participant needs to abort due to higher-priority work:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "reason-cancel-1",
- "from": "agent-1",
- "kind": "reasoning/cancel",
- "context": "reason-start-1",
- "payload": {
- "reason": "superseded"
- }
-}
-```
-
-- `context` MUST reference the `reasoning/start` envelope establishing the sequence
-- `correlation_id` MAY reference the triggering request/proposal if the reasoning was in response to another message
-- `payload.reason` SHOULD use deployment-defined codes (e.g., `"timeout"`, `"superseded"`, `"error"`) to simplify monitoring
-- Upon cancellation, participants SHOULD stop sending additional `reasoning/thought` messages for that context
-- User-facing surfaces (CLIs, dashboards) SHOULD provide an explicit affordance to issue `reasoning/cancel` for any active
- reasoning sequence so humans can interrupt long-running work without crafting raw envelopes
-
-#### 3.5.6 Context Behavior
-
-- Messages with a `context` field are part of a sub-context
-- Participants MAY filter out contexts when constructing prompts (e.g., excluding other agents' reasoning traces to reduce noise)
-- **Exception**: Participants MUST NOT ignore `mcp/request` or `mcp/proposal` messages, even if they have a context field
-- The context field supports hierarchical paths: `"parent/child/grandchild"`
-- Context enables parallel reasoning by multiple agents without interference
-
-### 3.6 Space Management Operations
-
-A **space** in MEW Protocol is a communication context where participants exchange messages. It's analogous to a channel or room - a bounded environment where a specific set of participants collaborate. Each space has its own:
-- Set of participants (who can send/receive messages)
-- Capability assignments (what each participant can do)
-- Message history (the stream of envelopes exchanged)
-
-A gateway may manage multiple spaces, each isolated from the others. The gateway enforces capabilities and routing rules for all its spaces.
-
-MEW Protocol extends with operations for managing these spaces dynamically. These operations use the `capability/*` and `space/*` namespaces to clearly indicate their purpose.
-
-#### 3.6.1 Grant Capabilities (kind = "capability/grant")
-
-Allows participants with appropriate capabilities to grant capabilities to other participants:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "grant-789",
- "from": "trusted-orchestrator",
- "to": ["untrusted-agent"],
- "kind": "capability/grant",
- "payload": {
- "recipient": "untrusted-agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_file"
- }
- }
- }
- ],
- "reason": "Demonstrated safe file handling"
- }
-}
-```
-
-- The grant message ID becomes the `grant_id` for future revocation
-- Capabilities use the same JSON pattern matching format from Section 4.1
-- Gateway SHOULD add granted capabilities to recipient's capability set
-- Multiple grants are cumulative
-
-**Capability Update Flow:**
-
-When the gateway processes a `capability/grant`:
-
-1. **Validate**: Check sender has `capability/grant` permission
-2. **Store**: Add granted capabilities to recipient's runtime capability set
-3. **Notify**: Send updated `system/welcome` to recipient with combined static + runtime capabilities
-4. **Acknowledge**: Recipient sends `capability/grant-ack` after updating capabilities
-
-**Important**: The gateway MUST resolve logical participant names to actual participant IDs when sending the updated welcome. If the recipient's participant ID differs from their logical name (e.g., "mew" vs "client-123"), the gateway must maintain a mapping (see Section 3.6.4).
-
-**Example Flow**:
-
-```
-1. Human → Gateway: capability/grant (to: ["mew"])
-2. Gateway: Validates, stores capabilities for "mew"
-3. Gateway → Agent: system/welcome (to: ["client-123"], with new capabilities)
-4. Agent: Updates participantInfo.capabilities
-5. Agent → Gateway: capability/grant-ack (correlation_id: ["grant-789"])
-```
-
-#### 3.6.2 Revoke Capabilities (kind = "capability/revoke")
-
-Revokes previously granted capabilities:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "revoke-123",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "grant_id": "grant-789",
- "reason": "Task completed"
- }
-}
-```
-
-Alternatively, revoke by capability pattern (removes ALL matching capabilities):
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "revoke-456",
- "from": "orchestrator",
- "kind": "capability/revoke",
- "payload": {
- "recipient": "agent",
- "capabilities": [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/*"
- }
- }
- ],
- "reason": "No longer needed"
- }
-}
-```
-
-#### 3.6.3 Grant Acknowledgment (kind = "capability/grant-ack")
-
-Recipients acknowledge capability grants:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "ack-001",
- "from": "agent",
- "correlation_id": ["grant-789"],
- "kind": "capability/grant-ack",
- "payload": {
- "status": "accepted"
- }
-}
-```
-
-#### 3.6.4 Participant ID Resolution
-
-Gateways MUST maintain a mapping between logical participant names (from configuration) and runtime participant IDs (from WebSocket connections):
-
-- **Logical names** are defined in space configuration (e.g., "mew", "orchestrator")
-- **Runtime IDs** are assigned during connection (e.g., "client-1234567-abc")
-- Messages addressed to logical names must be resolved to runtime IDs for delivery
-
-When processing `capability/grant`, `capability/revoke`, or other messages that reference participants by name, the gateway MUST:
-
-1. Resolve the logical name to the actual runtime participant ID
-2. Use the runtime ID to locate the participant's WebSocket connection
-3. Deliver messages using the runtime ID
-
-**Implementation Strategy:**
-
-Gateways can maintain this mapping by:
-- Creating a map of `logicalName → runtimeClientID` when participants join
-- Looking up tokens: `logicalName → token` (from config) and `runtimeClientID → token` (from connection)
-- Matching tokens to resolve logical names to runtime IDs
-
-**Example:**
-
-```
-Space config defines: "mew" with token "abc123"
-Agent connects with: participant_id = "client-1759310701273-q9i1e5jkg", token = "abc123"
-Gateway stores: "mew" → "client-1759310701273-q9i1e5jkg"
-
-When processing capability/grant with recipient="mew":
-1. Look up logical name "mew" → token "abc123"
-2. Find runtime participant with token "abc123" → "client-1759310701273-q9i1e5jkg"
-3. Send system/welcome to "client-1759310701273-q9i1e5jkg"
-```
-
-#### 3.6.5 Invite Participant (kind = "space/invite")
-
-Invites new participants to the space:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "invite-123",
- "from": "admin",
- "kind": "space/invite",
- "payload": {
- "participant_id": "new-agent",
- "email": "agent-operator@example.com", // Optional
- "initial_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ],
- "reason": "Adding specialized analysis agent"
- }
-}
-```
-
-**Fields:**
-- `participant_id`: Identifier for the new participant
-- `email`: (optional) Email address to send invitation to
-- `initial_capabilities`: Capabilities the participant will have when they join
-- `reason`: Explanation for the invitation
-
-**Note:** This message is broadcast within the space to inform existing participants. If `email` is provided, the gateway SHOULD send an invitation email with connection details. Additional notification methods (webhook, token generation, etc.) are gateway implementation-specific.
-
-#### 3.6.6 Remove Participant (kind = "space/kick")
-
-Removes participants from the space:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "kick-456",
- "from": "admin",
- "kind": "space/kick",
- "payload": {
- "participant_id": "misbehaving-agent",
- "reason": "Repeated capability violations"
- }
-}
-```
-
-#### 3.6.7 Delegation Security
-
-- Only participants with `capability/grant` capability can grant capabilities
-- Participants cannot grant capabilities they don't possess
-- Gateway SHOULD track grant chains for audit purposes
-- Revocations take effect immediately
-- All space management operations generate audit logs
-
-### 3.7 Presence Messages (kind = "system/presence")
-
-Presence messages are broadcast to notify all participants about join/leave events:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-presence-1",
- "from": "system:gateway",
- "kind": "system/presence",
- "payload": {
- "event": "join",
- "participant": {
- "id": "new-agent",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
- }
-}
-```
-
-- `event` (required): Either `"join"` or `"leave"`
-- `participant` (required): Information about the participant
- - `id`: The participant's identifier
- - `capabilities`: The participant's capabilities (for `join` events)
-
-Note: Presence messages are broadcast to all participants. The joining participant also receives a welcome message addressed specifically to them (via the `to` field) with their authoritative capabilities and the current participant list.
-
-### 3.8 System Messages
-
-#### 3.8.1 Welcome Message (kind = "system/welcome")
-
-When a participant connects, the gateway MUST send a welcome message addressed specifically to that participant (using the `to` field):
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-welcome-1",
- "from": "system:gateway",
- "to": ["new-participant"],
- "kind": "system/welcome",
- "payload": {
- "you": {
- "id": "new-participant",
- "capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- },
- "participants": [
- {
- "id": "agent-1",
- "capabilities": [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- },
- {
- "id": "agent-2",
- "capabilities": [
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- }
- ]
- }
-}
-```
-
-- `you`: The joining participant's own information and authoritative capabilities
-- `participants`: Current list of other participants in the space and their capabilities
-
-**Important:** Other participants SHOULD ignore welcome messages not addressed to them when constructing prompts, as these can cause significant bloat. The message is already targeted via the `to` field.
-
-#### 3.8.2 Capability Violation (kind = "system/error")
-
-When a participant attempts an operation they lack capability for:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "env-violation-1",
- "from": "system:gateway",
- "to": ["violator"],
- "kind": "system/error",
- "correlation_id": ["env-bad-call"],
- "payload": {
- "error": "capability_violation",
- "attempted_kind": "mcp/request",
- "your_capabilities": [
- {"kind": "mcp/proposal"},
- {"kind": "chat"}
- ]
- }
-}
-```
-
----
-
-### 3.9 Participant Control Messages
-
-Participant control envelopes allow coordinators and the gateway to modulate how agents operate in a space. They provide a
-uniform mechanism for pausing work, requesting telemetry, and resetting state without overloading the MCP namespace.
-
-#### 3.9.1 Pause Participant (kind = "participant/pause")
-
-Requests that a participant temporarily stop emitting new work:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "pause-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/pause",
- "payload": {
- "reason": "rate_limit",
- "timeout_seconds": 60
- }
-}
-```
-
-- Target participant SHOULD stop sending envelopes other than acknowledgements or cancellations until resumed
-- `payload.timeout_seconds` MAY be provided so the participant can automatically resume if no explicit resume arrives
-- Gateways MAY enforce pauses by rejecting other outbound traffic while in effect
-
-#### 3.9.2 Resume Participant (kind = "participant/resume")
-
-Lifts a previously applied pause:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "resume-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/resume",
- "correlation_id": ["pause-1"],
- "payload": {}
-}
-```
-
-- `correlation_id` SHOULD reference the pause being cleared when known
-- Participants MAY resume autonomously when a pause timeout expires, but SHOULD still emit a `participant/resume` to document
- the change in state
-
-#### 3.9.3 Request Status (kind = "participant/request-status")
-
-Asks a participant to emit its current utilization telemetry. Earlier drafts referenced this as `participant/requestStatus`; the
-hyphenated name is normative:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "status-request-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/request-status",
- "payload": {
- "fields": ["tokens", "latency"]
- }
-}
-```
-
-- `payload.fields` MAY limit which metrics are requested
-- Participants SHOULD answer with `participant/status` promptly
-
-#### 3.9.4 Participant Status (kind = "participant/status")
-
-Reports runtime telemetry such as token consumption and context occupancy. This message is typically emitted in response to
-`participant/request-status` but MAY be sent proactively:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "status-1",
- "from": "agent-1",
- "kind": "participant/status",
- "correlation_id": ["status-request-1"],
- "payload": {
- "tokens": 12345,
- "max_tokens": 20000,
- "messages_in_context": 128,
- "latency_ms": 350
- }
-}
-```
-
-- `tokens` and `max_tokens` provide the usage context introduced in this release
-- `messages_in_context` MUST be included and counts envelopes currently retained for the active conversational context
-- Additional metrics are allowed and should use descriptive snake_case keys
-- Participants MAY broadcast status to improve observability, but gateways MAY limit dissemination to reduce noise
-- Participants MAY also emit `participant/status` proactively when approaching a resource limit (for example, when only 10%
- of the context window remains) so orchestrators can intervene before prompts truncate unexpectedly
-
-#### 3.9.5 Participant Forget (kind = "participant/forget")
-
-Instructs a participant to drop cached context. The `payload.direction` field indicates whether to trim from the oldest or
-newest data, corresponding to the `(Oldest|Newest)` notation in the request:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "forget-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/forget",
- "payload": {
- "direction": "oldest",
- "entries": 10
- }
-}
-```
-
-- `direction` MUST be either `"oldest"` or `"newest"`
-- `entries` (optional) specifies how many records or messages to discard; implementations MAY interpret as tokens
-- Participants SHOULD emit a follow-up `participant/status` or `chat/acknowledge` once the context is dropped
-- Agents SHOULD monitor their context usage and automatically trigger a forget/compaction cycle before hitting hard limits.
- When compacting autonomously, they MUST send a `participant/status` update indicating the compaction status and resulting
- resource headroom so observers understand why history changed.
-
-#### 3.9.6 Participant Compact (kind = "participant/compact")
-
-Requests that a participant run its compaction routine to free headroom in its working memory or conversational history:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "compact-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/compact",
- "payload": {
- "reason": "token_pressure",
- "target_tokens": 16000
- }
-}
-```
-
-- `payload.reason` (optional) provides operator context the participant MAY log or surface in status updates
-- `payload.target_tokens` (optional) indicates a desired ceiling after compaction; participants MAY ignore if unsupported
-- Participants that maintain working memory SHOULD attempt compaction promptly and emit interim `participant/status` updates
- such as `compacting` / `compacted`
-- Participants with no compactable state MAY ignore the request entirely or MAY reply with `participant/compact-done` including
- `"skipped": true` to document that nothing changed
-
-#### 3.9.7 Participant Compaction Complete (kind = "participant/compact-done")
-
-Acknowledges the completion (or intentional skip) of a requested compaction:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "compact-done-1",
- "from": "agent-1",
- "to": ["orchestrator"],
- "kind": "participant/compact-done",
- "correlation_id": ["compact-1"],
- "payload": {
- "freed_tokens": 2048,
- "freed_messages": 12,
- "status": "compacted"
- }
-}
-```
-
-- `correlation_id` MUST reference the originating `participant/compact` request when one exists
-- `freed_tokens` / `freed_messages` (optional) report how much context was reclaimed
-- When compaction is skipped, participants SHOULD include `"skipped": true` and MAY add a human-readable `"reason"`
-- Participants MUST send `participant/compact-done` after completing work triggered by `participant/compact`, even if no context
- was removed, so orchestrators can clear pending actions
-
-#### 3.9.8 Participant Clear (kind = "participant/clear")
-
-Instructs a participant to wipe its entire retained conversational or working memory:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "clear-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/clear"
-}
-```
-
-- `participant/clear` SHOULD be treated as stronger than `participant/forget` and MUST erase all cached context, scratchpads, and working memories
-- No additional payload fields are required; implementations MAY omit the `payload` property or include an empty object if their transport requires it
-- Participants SHOULD emit a follow-up `participant/status` confirming an empty context (e.g., `messages_in_context = 0`)
-
-#### 3.9.9 Participant Restart (kind = "participant/restart")
-
-Returns a participant to a known baseline configuration:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "restart-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/restart"
-}
-```
-
-- No standard payload fields are required; implementations MAY include vendor-specific restart hints if all participants support them
-- Participants SHOULD terminate outstanding workflows and streams when restarting
-- Gateways MAY treat a restart as implicit acknowledgement that previous capability grants remain in effect unless explicitly
- revoked
-
-#### 3.9.10 Participant Shutdown (kind = "participant/shutdown")
-
-Requests that a participant cease all activity without restarting, allowing the orchestrator to keep the slot idle or replace it later:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "shutdown-1",
- "from": "orchestrator",
- "to": ["agent-1"],
- "kind": "participant/shutdown"
-}
-```
-
-- No standard payload fields are required; orchestrators MAY include optional context if their counterpart supports it
-- Participants SHOULD acknowledge shutdown via `chat/acknowledge` or by emitting a terminal `system/presence` leave event
-- After shutdown, gateways SHOULD reject further outbound envelopes from the participant until it rejoins the space
-
----
-
-### 3.10 Stream Lifecycle Messages
-
-Streaming envelopes coordinate high-volume or binary data transfer while keeping the core message bus lightweight.
-
-#### 3.10.1 Stream Request (kind = "stream/request")
-
-Sent by whichever entity initiates stream negotiation (typically a participant asking the gateway for bulk-transfer resources):
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "stream-req-1",
- "from": "agent-1",
- "to": ["gateway"],
- "kind": "stream/request",
- "payload": {
- "direction": "upload",
- "expected_size_bytes": 10485760,
- "description": "Large dataset export"
- }
-}
-```
-
-- `direction` clarifies whether the sender will upload or download data
-- `expected_size_bytes` is advisory and MAY be omitted
-- `correlation_id` (not shown) MAY reference the message that motivated the stream (e.g., a proposal or request)
-- The gateway MUST intercept all `stream/request` messages and reply with `stream/open` containing a unique `stream_id`
-- The gateway is responsible for stream ID allocation and management, regardless of the request's `to` field
-- Agents that expose long-form reasoning SHOULD consider issuing a `stream/request` alongside `reasoning/start` so subscribers
- can follow high-volume traces without bloating the shared envelope log.
-
-#### 3.10.2 Stream Open (kind = "stream/open")
-
-Confirms that a stream has been established and assigns the identifier used for raw frames:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "stream-open-1",
- "from": "gateway",
- "to": ["agent-1"],
- "kind": "stream/open",
- "correlation_id": ["stream-req-1"],
- "payload": {
- "stream_id": "stream-42",
- "encoding": "binary"
- }
-}
-```
-
-- `payload.stream_id` MUST be unique per active stream on the connection
-- Additional metadata such as `encoding` or `compression` MAY be provided for the receiver
-
-#### 3.10.3 Stream Data Frames (no envelope)
-
-Once a stream is open, binary or chunked data travels on the same WebSocket without the JSON envelope wrapper. Frames are prefixed using the pattern `#streamID#data`, matching the `#streamID#data` example provided with this update. Implementations MUST ensure framing preserves boundaries so receivers can demultiplex concurrent streams.
-
-#### 3.10.4 Stream Close (kind = "stream/close")
-
-Terminates a stream and releases associated resources:
-
-```json
-{
- "protocol": "mew/v0.4",
- "id": "stream-close-1",
- "from": "gateway",
- "to": ["agent-1"],
- "kind": "stream/close",
- "correlation_id": ["stream-open-1"],
- "payload": {
- "reason": "complete"
- }
-}
-```
-
-- Either side MAY send `stream/close`
-- `payload.reason` SHOULD distinguish between normal completion and errors (e.g., `"complete"`, `"cancelled"`, `"timeout"`)
-- After closing, no additional `#streamID#...` frames MUST be sent
-
----
-
-## 4. Security Model
-
-### 4.1 Capability-Based Access Control
-
-The gateway enforces security through two mechanisms:
-
-1. **Identity Validation**: The gateway MUST verify that the `from` field matches the authenticated participant's ID. Participants cannot spoof messages from other participants.
-
-2. **Capability Matching**: The gateway assigns capabilities to each connection using JSON pattern matching. Capabilities are JSON objects that match against the message structure (kind and payload).
-
-**Capability Pattern Structure:**
-```json
-{
- "kind": "pattern",
- "payload": {
- "field": "pattern"
- }
-}
-```
-
-**Pattern Types:**
-- String with wildcards: `"mcp/*"` matches `mcp/request`, `mcp/response`, etc.
-- Exact match: `"chat"` only matches `"chat"`
-- Nested patterns: Match specific payload fields
-
-**Reserved Namespace:**
-The `system/*` namespace is reserved exclusively for the gateway. Participants MUST NOT send messages with `kind` starting with `system/`. The gateway MUST reject any such attempts. Only the gateway can generate system messages (`system/welcome`, `system/presence`, `system/error`).
-
-**Example Capability Sets:**
-
-Gateways may implement various capability profiles using JSON patterns:
-
-1. **Full Access** example:
- ```json
- [
- {"kind": "mcp/*"},
- {"kind": "chat"}
- ]
- ```
- Can send any MCP messages (requests, responses, proposals)
-
-2. **Proposal-Only** example:
- ```json
- [
- {"kind": "mcp/proposal"},
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Cannot send direct MCP requests, must use proposals
-
-3. **Tool-Specific** example:
- ```json
- [
- {
- "kind": "mcp/request",
- "payload": {
- "method": "tools/call",
- "params": {
- "name": "read_*"
- }
- }
- },
- {"kind": "mcp/response"},
- {"kind": "chat"}
- ]
- ```
- Can only call tools matching `read_*` pattern
-
-**Progressive Trust Example:**
-
-Capabilities can be expanded as trust increases:
-1. Initial: `[{"kind": "mcp/proposal"}, {"kind": "chat"}]` - Proposals only
-2. Basic: Add read capabilities with payload patterns
-3. Trusted: Add tool usage with specific tool patterns
-4. Full: Replace with `[{"kind": "mcp/*"}]` - Unrestricted MCP access
-
-### 4.2 Gateway Enforcement
-
-The gateway enforces capabilities using JSON pattern matching against the message structure:
-
-**What the Gateway Does:**
-- Matches the message's `kind` and `payload` against participant's capability patterns
-- Uses wildcards, regex patterns, and JSONPath for flexible matching
-- Blocks messages if no capability matches
-- Returns error responses for capability violations
-
-**What the Gateway Does NOT Do:**
-- Parse or validate JSON-RPC payloads
-- Understand MCP semantics
-- Detect spoofing (where `kind` doesn't match payload content)
-
-**Pattern Matching Examples:**
-- Message with `kind: "mcp/request"` and `payload.method: "tools/call"` matches:
- - `{"kind": "mcp/*"}`
- - `{"kind": "mcp/request"}`
- - `{"kind": "mcp/request", "payload": {"method": "tools/*"}}`
-- Message with `kind: "chat"` only matches:
- - `{"kind": "chat"}`
- - `{"kind": "*"}` (wildcard for all kinds)
-
-### 4.3 Participant Validation
-
-Receiving participants SHOULD validate message structure:
-- Verify `kind` is appropriate for the message type
-- Validate payload structure matches expected schema
-- Drop or report malformed messages
-- MAY track misbehaving participants for reputation scoring
-
-**Schema Mismatch Warning:** Participants may observe messages with schemas that differ from what was advertised:
-- Other participants might advertise one tool schema but send different parameters
-- Participants joining mid-conversation may see responses to requests they never observed
-- Always parse messages defensively and validate structure before processing
-
----
-
-## 5. Realtime Gateway API
-
-### 5.1 Authentication and Capability Assignment
-
-The gateway determines capabilities during authentication. Implementation-specific policies may include:
-
-1. **Token-based**: Tokens map to specific capability sets
- - Implementations may encode capabilities in tokens or map tokens to capability profiles
-2. **Identity-based**: Map authenticated identities to capability sets
-3. **Space access control**: Spaces may be public, private, or restricted
-4. **Dynamic capabilities**: Capabilities may be modified during a session
-
-### 5.2 WebSocket Connection
-
-Connect: `GET /ws?space=` with Authorization header
-
-The gateway:
-1. Validates the bearer token (if provided)
-2. Maps the token to a participant ID (implementation-specific)
-3. Determines capabilities based on implementation policy
-4. **MUST** send welcome message with the assigned participant ID and accurate capabilities
-5. **MUST** enforce capability rules on all subsequent messages
-
-**Note:** Participants only provide their bearer token. The gateway is responsible for mapping tokens to participant IDs through its own implementation-specific mechanism.
-
-The capabilities in the welcome message constitute the authoritative list of what operations the participant can perform. Participants SHOULD use this list to understand their allowed operations.
-
-### 5.3 HTTP Message Injection (Optional)
-
-Gateways MAY expose HTTP endpoints that let trusted callers inject MEW envelopes without maintaining a WebSocket connection. These endpoints mirror the WebSocket semantics and MUST enforce the same capability rules as live connections.
-
-```
-POST /participants/{participant_id}/messages
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
- "kind": "chat",
- "payload": {
- "text": "Hello world"
- }
-}
-```
-
-**Typical response**
-```json
-{
- "id": "msg-123",
- "status": "accepted",
- "timestamp": "2025-01-09T10:00:00Z"
-}
-```
-
-Gateways MAY also expose a retrieval endpoint for polling scenarios:
-
-```
-GET /participants/{participant_id}/messages?since={timestamp}
-Authorization: Bearer {token}
-```
-
-Responses MUST contain complete envelopes and respect the caller's capabilities; messages the caller lacks permission to view MUST be omitted.
-
-### 5.4 Message Filtering
-
-For each incoming message from a participant:
-
-```python
-if not matches_any_capability(message, participant.capabilities):
- send_error(f"Capability violation: you lack capability for this operation")
- broadcast_violation_notice() # optional
- return
-send_to_space(message)
-```
-
----
-
-## 6. Version Compatibility
-
-### 6.1 Breaking Changes
-
-This is a v0.x release. Breaking changes are expected between minor versions until v1.0:
-- v0.4 is NOT backward compatible with v0.3
-- Clients and gateways MUST use matching protocol versions
-- No compatibility guarantees until v1.0 release
-
-### 6.2 Migration from v0.3
-
-Key updates in v0.4:
-- Protocol identifier changed from `mew/v0.3` to `mew/v0.4`
-- Added participant control messages for runtime management: `participant/request-status`, `participant/status`, `participant/forget`, `participant/clear`, `participant/restart`, and `participant/shutdown`
-- Introduced stream lifecycle support (`stream/request`, `stream/open`, `stream/close`) plus binary frame guidance for high-volume data
-- Documented optional HTTP message injection endpoints alongside the WebSocket channel
-
-### 6.3 Migration from v0.2
-
-Key breaking changes from v0.2 (cumulative):
-- Protocol name changed from MEUP to MEW Protocol
-- Protocol identifier changed from `meup/v0.2` to `mew/v0.4`
-- Full name is now "Multi-Entity Workspace Protocol"
-
-### 6.4 Migration from v0.0
-
-Key breaking changes from v0.0 (cumulative):
-- Protocol identifier changed from `mcp-x/v0` to `mew/v0.4`
-- Message kinds now use slash notation (e.g., `mcp/request` instead of `mcp/request:tools/call`)
-- Method information moved to payload
-- Capabilities use JSON pattern matching instead of string wildcards
-- `correlation_id` is now always an array
-- Chat remains as dedicated `chat` kind
-
-### 6.5 Future Compatibility
-
-- v0.x series is experimental and subject to breaking changes
-- v1.0 will establish stable protocol with compatibility guarantees
-- Production deployments should pin specific v0.x versions
-
----
-
-## 7. Security Considerations
-
-MEW Protocol's security model relies on capability-based access control enforced by the gateway, with additional validation responsibilities distributed among participants.
-
-### 7.1 Core Security Mechanisms
-
-1. **Identity Validation**: Gateway MUST verify the `from` field matches the authenticated participant ID (Section 4.1)
-2. **Capability Enforcement**: Gateway enforces JSON pattern-based capabilities on all messages (Section 4.1, 4.2)
-3. **Reserved Namespaces**: Only the gateway can send `system/*` messages, preventing spoofing (Section 3.8)
-4. **Proposal Isolation**: Untrusted agents use `mcp/proposal` to suggest rather than execute operations (Section 3.3)
-5. **Lazy Gateway Enforcement**: Gateway validates message structure but not payload semantics (Section 4.2)
-
-### 7.2 Security Boundaries
-
-**Gateway Responsibilities:**
-- Authenticate participants and assign stable IDs
-- Enforce capability patterns on message kinds and payloads
-- Prevent identity spoofing via `from` field validation
-- Block `system/*` messages from participants
-
-**Participant Responsibilities:**
-- Validate envelope `kind` matches payload content
-- Detect and report malformed or spoofed messages
-- Parse messages defensively (schemas may differ from advertised)
-- Track misbehaving participants for reputation scoring
-
-### 7.3 Best Practices
-
-1. **Start Restricted**: New agents begin with `mcp/proposal` capability only
-2. **Progressive Trust**: Expand capabilities based on observed behavior over time
-3. **Validate Strictly**: Check that `kind` matches the payload type (e.g., `mcp/request` for MCP requests)
-4. **Monitor Proposals**: Log proposal/fulfillment patterns for audit trails
-5. **Report Violations**: Track and broadcast capability violations for transparency
-
----
-
-## 8. Implementation Checklist
-
-### 8.1 Gateway Requirements
-- [ ] **Connection Management**
- - [ ] WebSocket server at `GET /ws?space=`
- - [ ] Bearer token validation from Authorization header
- - [ ] Token-to-participant-ID mapping (implementation-specific)
- - [ ] Connection state tracking per participant
-
-- [ ] **Capability Enforcement**
- - [ ] Pattern matching engine for wildcard capabilities
- - [ ] Validate message `kind` against sender's capabilities
- - [ ] Block messages that don't match capabilities
- - [ ] Return `system/error` for capability violations
-
-- [ ] **System Messages**
- - [ ] Send `system/welcome` with participant ID and capabilities on connect
- - [ ] Broadcast `system/presence` for join/leave events
- - [ ] Generate `system/error` for protocol violations
- - [ ] Ensure only gateway can send `system/*` messages
-
-- [ ] **Message Routing**
- - [ ] Route messages based on `to` field (broadcast if empty/omitted)
- - [ ] Preserve envelope structure without modification
- - [ ] NO payload parsing or validation (lazy enforcement)
-
-### 8.2 Participant Requirements
-- [ ] **Message Validation**
- - [ ] Verify envelope structure before processing
- - [ ] Validate `kind` matches the payload type (e.g., `mcp/request` for requests with `payload.method`)
- - [ ] Validate payload structure matches expected schema for the `kind`
- - [ ] Drop messages that fail validation
- - [ ] Track/report misbehaving participants
-
-- [ ] **MCP Integration**
- - [ ] Implement MCP server capabilities
- - [ ] Handle incoming MCP requests/responses
- - [ ] Generate proper correlation IDs for responses
- - [ ] Include correlation ID in all response messages
-
-- [ ] **Proposal Handling** (if applicable)
- - [ ] Recognize `mcp.proposal` messages
- - [ ] Implement fulfillment logic for approved proposals
- - [ ] Include proposal ID as correlation_id when fulfilling
-
-- [ ] **Connection Behavior**
- - [ ] Process `system/welcome` to learn own ID and capabilities
- - [ ] Handle `system/presence` to track other participants
- - [ ] Respect capability restrictions from welcome message
-
----
-
-## 9. Examples
-
-The following examples demonstrate multi-agent orchestration patterns enabled by MEW Protocol's capability-based security model. The core pattern is **delegated fulfillment**, where untrusted agents propose operations that are reviewed and executed by trusted participants.
-
-### 9.1 Proposal-Based Workflow Example
-
-In this example, an agent with limited capabilities uses proposals:
-
-1. Agent connects → receives proposal-only capabilities
-2. Agent attempts MCP request → gateway blocks, returns error
-3. Agent sends `mcp/proposal` → visible to all participants
-4. Another participant with appropriate capabilities fulfills it
-5. Fulfiller sends real `mcp/request` message to target
-6. Target executes and returns result to fulfiller (proposer observes via broadcast)
-
-### 9.2 Capability Expansion Example
-
-One possible administrative workflow:
-
-1. Agent operates successfully over time
-2. Administrator observes behavior patterns
-3. Administrator expands agent capabilities
-4. Agent gains access to additional operations
-
-### 9.3 Mixed Environment Example
-
-A gateway might assign different capability profiles:
-
-- Administrative users: `{"kind": "mcp/*"}` (full access)
-- Service agents: `{"kind": "mcp/response"}` (response-only)
-- New agents: `{"kind": "mcp/proposal"}` (proposal-only)
-- Monitoring tools: `{"kind": "mcp/request", "payload": {"method": "*/list"}}` (read-only)
-
-All participants operate in the same space with their assigned capabilities.
-
-### 9.4 Delegated Fulfillment Example
-
-A human supervises an untrusted agent through intermediary agents:
-
-1. **Proposer Agent** (capability: `mcp/proposal`) proposes writing a file
-2. **Human** reviews the proposal and decides to approve it by directing the **Orchestrator Agent** (capability: `mcp/request`) to fulfill the proposal
-3. **Orchestrator Agent** sends the MCP request to **Worker Agent**
-4. **Worker Agent** executes the actual file write operation and responds
-5. Over time, **Human** teaches **Orchestrator Agent** rules about which proposals to auto-approve
-6. **Orchestrator Agent** begins autonomously fulfilling certain proposals without human intervention
-
-This pattern demonstrates **progressive automation** - a key goal of MEW Protocol. As the orchestrator observes human decisions over time, it learns which types of proposals can be safely auto-approved. This transforms human judgment into automated policies, creating a system that becomes more autonomous while maintaining safety through learned boundaries.
-
----
-
-## 10. Appendix: Implementation Notes
-
-### 10.1 Gateway State
-
-Minimal state required per connection:
-```json
-{
- "connection_id": "ws-123",
- "participant_id": "agent-a",
- "capabilities": [{"kind": "mcp/proposal"}, {"kind": "chat"}],
- "connected_at": "2025-08-26T14:00:00Z"
-}
-```
-
-### 10.2 Proposal Tracking
-
-Optional proposal tracking for fulfillment (maintained by agents, not gateway):
-```json
-{
- "proposalId": "env-proposal-1",
- "proposer": "untrusted-agent",
- "target": "target-agent",
- "method": "tools/call",
- "params": {"name": "dangerous_operation", "arguments": {...}},
- "status": "pending",
- "createdAt": "2025-08-26T14:00:00Z",
- "expiresAt": "2025-08-26T14:05:00Z"
-}
-```
-
----
-
-## References
-
-- MCP Specification 2025-06-18
-- MEW v0.0 Specification (formerly MEUP)
-- ADR-003: Tool Access Control
-- OAuth 2.0 RFC 6749 (for token patterns)
diff --git a/spec/protocol/v0.4/accepted/README.md b/spec/protocol/v0.4/accepted/README.md
deleted file mode 100644
index 6636e72c..00000000
--- a/spec/protocol/v0.4/accepted/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Accepted ADRs
-
-This folder contains accepted Architecture Decision Records for the next version of the MEUP protocol.
-
-## Current Status
-
-No accepted ADRs for the next version yet. All v0.2 ADRs are in `/spec/v0.2/decisions/accepted/`.
-
-## Format
-
-When ADRs are accepted from `proposed/`:
-- Maintain the same filename (including proposal number)
-- Update Status to "Accepted"
-- Track Incorporation status as implementation progresses
\ No newline at end of file
diff --git a/spec/protocol/v0.4/decisions-README.md b/spec/protocol/v0.4/decisions-README.md
deleted file mode 100644
index bc0b27bc..00000000
--- a/spec/protocol/v0.4/decisions-README.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# Draft Protocol Decisions
-
-This directory will contain Architecture Decision Records (ADRs) for the next version of the MEUP protocol.
-
-## Current Status
-
-No active decisions for the draft version. All v0.2 decisions have been incorporated and are available in `/spec/v0.2/decisions/`.
-
-## Directory Structure
-
-- `proposed/` - ADRs under consideration for the next version
-- `accepted/` - Approved ADRs for the next version
-- `rejected/` - Rejected ADRs kept for historical context
-
-## Creating New ADRs
-
-When proposing changes for the next protocol version:
-
-1. Create ADR in `proposed/` with format: `[number]-[id]-[name].md`
-2. Use unique 3-character ID (e.g., `a1b`)
-3. Follow ADR template from `/spec/CLAUDE.md`
-4. Reference this as "MEUP Protocol Next" or specific version when known
-
-## Previous Versions
-
-- **v0.2 decisions**: `/spec/v0.2/decisions/` - Current released protocol
-- **v0.1 decisions**: Historical (if any)
\ No newline at end of file
diff --git a/spec/protocol/v0.4/rejected/001-ren-participant-to-entity.md b/spec/protocol/v0.4/rejected/001-ren-participant-to-entity.md
deleted file mode 100644
index 7785ec13..00000000
--- a/spec/protocol/v0.4/rejected/001-ren-participant-to-entity.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# ADR-REN: Rename Participant to Entity
-
-**Status:** Rejected
-**Date:** 2025-01-10
-**Context:** MEW Protocol v0.3
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** Retaining "participant" terminology for v0.4 maintains compatibility with existing implementations; the rename needs additional planning beyond this release.
-
-## Context
-
-The term "Participant" is currently used throughout the MEW Protocol specification to refer to connected actors in a workspace. However, this terminology has become problematic for several reasons:
-
-1. **Legacy Confusion**: "Participant" is a legacy term from earlier iterations of the protocol that no longer accurately reflects the current architecture
-2. **Naming Conflicts**: The term conflicts with domain-specific uses, particularly in game development where "participant" might refer to game items or players with different semantics
-3. **Specification Clarity**: The protocol name itself (Multi-Entity Workspace Protocol) already uses "Entity" in its expansion, creating inconsistency when the spec refers to "Participants"
-4. **Conceptual Alignment**: "Entity" better captures the abstract nature of actors in the system - they can be humans, AI agents, tools, or services
-
-## Options Considered
-
-### Option 1: Keep "Participant"
-Continue using the current terminology.
-
-**Pros:**
-- No changes required to existing documentation
-- No risk of breaking existing implementations
-
-**Cons:**
-- Continues the confusion and naming conflicts
-- Inconsistent with protocol name
-- Makes game development and other domain-specific implementations harder
-
-### Option 2: Rename to "Entity"
-Replace all instances of "Participant" with "Entity" throughout the specification.
-
-**Pros:**
-- Aligns with protocol name (Multi-Entity Workspace Protocol)
-- More abstract and flexible term
-- Avoids domain-specific conflicts
-- Cleaner conceptual model
-
-**Cons:**
-- Requires updating all documentation
-- May temporarily confuse readers familiar with old terminology
-
-### Option 3: Use "Actor"
-Replace with the term "Actor" instead.
-
-**Pros:**
-- Common term in distributed systems
-- Clear implication of active participation
-
-**Cons:**
-- Still has potential conflicts (e.g., in theater/drama applications)
-- Less alignment with protocol name
-- "Actor" implies agency that might not apply to all entities
-
-## Decision
-
-Adopt Option 2: Rename "Participant" to "Entity" throughout the specification.
-
-### Implementation Details
-
-1. **Specification Updates**: Replace all instances of "participant" with "entity" in SPEC.md
-2. **Field Renaming**: Update protocol fields:
- - `participant_id` → `entity_id`
- - `participant_name` → `entity_name`
- - `participants` → `entities`
-3. **Message Updates**: Update related message types and fields
-4. **Documentation**: Add a migration note for implementers
-
-## Consequences
-
-### Positive
-- Creates consistency between protocol name and specification terminology
-- Eliminates confusion in domain-specific implementations
-- Provides a more abstract and flexible conceptual model
-- Aligns with the protocol's goal of supporting diverse types of actors
-
-### Negative
-- Requires a one-time update to all documentation
-- May require a brief transition period where both terms are recognized
-- Existing implementations will need to update their terminology (though protocol compatibility can be maintained)
diff --git a/spec/protocol/v0.4/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md b/spec/protocol/v0.4/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md
deleted file mode 100644
index 4e8a8fe2..00000000
--- a/spec/protocol/v0.4/rejected/001-wcm-where-to-put-mcp-request-proposal-logic.md
+++ /dev/null
@@ -1,243 +0,0 @@
-# ADR-WCM: Where to Put MCP Request/Proposal Auto-Conversion Logic
-
-**Status:** Rejected
-**Date:** 2025-01-10
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** v0.4 scope keeps current MEWParticipant auto-conversion behavior; larger refactor will be reconsidered alongside future SDK updates.
-
-## Context
-
-The MEW Protocol supports two ways for participants to execute MCP operations:
-1. **Direct MCP requests** (`mcp/request`) - For trusted participants with appropriate capabilities
-2. **MCP proposals** (`mcp/proposal`) - For untrusted participants requiring approval
-
-Agents and other participants need a seamless way to make MCP requests that automatically fall back to proposals when they lack direct request capabilities. This automatic conversion is crucial for:
-- **Agent development**: Agents should work regardless of trust level
-- **Progressive trust**: Participants can gain capabilities over time
-- **Security**: Untrusted participants can still function with approval workflows
-
-Currently, the `MEWParticipant.request()` method in the SDK already implements this logic, but we need to determine:
-1. Is this the right architectural location?
-2. Should we enhance it with the advanced capability-matcher?
-3. How should this integrate with the new TypeScript mew-agent?
-
-## Options Considered
-
-### Option 1: Keep Enhanced Logic in MEWParticipant (Current Location)
-
-Keep and enhance the existing implementation in `sdk/typescript-sdk/participant/src/MEWParticipant.ts`.
-
-**Current Implementation:**
-- Already has basic auto-conversion logic
-- Uses simple capability checking
-- Returns promises that resolve with responses
-
-**Proposed Enhancements:**
-- Integrate advanced capability-matcher for sophisticated pattern matching
-- Add better error messages explaining why proposals were used
-- Add optional logging/monitoring of capability decisions
-
-**Pros:**
-- ✅ Logic already exists and works
-- ✅ Right architectural layer (participant abstraction)
-- ✅ All participants automatically benefit
-- ✅ Minimal breaking changes
-- ✅ Single source of truth for request routing
-
-**Cons:**
-- ❌ Couples participant package to capability-matcher package
-- ❌ May add complexity to a currently simple implementation
-- ❌ Could increase bundle size for all participants
-
-### Option 2: Create New Request Manager in Client Package
-
-Move the logic down to the MEWClient level and create a dedicated RequestManager class.
-
-**Structure:**
-```typescript
-// sdk/typescript-sdk/client/src/RequestManager.ts
-class RequestManager {
- constructor(client: MEWClient, capabilities: Capability[])
- async smartRequest(target, method, params): Promise
-}
-```
-
-**Pros:**
-- ✅ Separation of concerns
-- ✅ Could be reused by non-participant clients
-- ✅ More testable as isolated component
-
-**Cons:**
-- ❌ Breaking change - MEWClient doesn't currently know about capabilities
-- ❌ Wrong architectural layer - client should be protocol-agnostic
-- ❌ Would require significant refactoring
-- ❌ Duplicates existing working logic
-
-### Option 3: Create Separate Utility Package
-
-Create a new package `@mew-protocol/smart-request` that provides the enhanced logic.
-
-**Structure:**
-```typescript
-// sdk/typescript-sdk/smart-request/
-import { SmartRequestManager } from '@mew-protocol/smart-request';
-
-class MEWParticipant {
- private requestManager: SmartRequestManager;
-
- async request(...) {
- return this.requestManager.execute(...);
- }
-}
-```
-
-**Pros:**
-- ✅ Clean separation of concerns
-- ✅ Optional dependency (can use basic or smart)
-- ✅ Highly testable
-- ✅ Could support different strategies
-
-**Cons:**
-- ❌ Over-engineering for current needs
-- ❌ Another package to maintain
-- ❌ Adds complexity to SDK
-- ❌ Splits logic that naturally belongs together
-
-### Option 4: Enhanced Capability Checking Only
-
-Keep request logic in MEWParticipant but enhance only the capability checking to use the advanced matcher.
-
-**Implementation:**
-```typescript
-// In MEWParticipant
-import { hasCapability } from '@mew-protocol/capability-matcher';
-
-canSend(kind: string, payload?: any): boolean {
- // Use advanced matcher if available, fall back to simple
- if (hasCapability) {
- return hasCapability(this.participantInfo, { kind, payload });
- }
- return simpleCanSend(this.participantInfo.capabilities, kind, payload);
-}
-```
-
-**Pros:**
-- ✅ Minimal changes to existing code
-- ✅ Optional enhancement (graceful degradation)
-- ✅ Leverages existing advanced matcher
-- ✅ No breaking changes
-
-**Cons:**
-- ❌ Doesn't address other enhancement needs (logging, monitoring)
-- ❌ Still couples packages together
-- ❌ May confuse with two capability checking systems
-
-## Decision
-
-**Selected Option: Option 1 - Keep Enhanced Logic in MEWParticipant**
-
-We will keep the MCP request/proposal auto-conversion logic in its current location (`MEWParticipant.request()`) and enhance it with:
-
-1. **Optional advanced capability matching** - Use the capability-matcher package when sophisticated patterns are needed
-2. **Better debugging** - Add optional debug logging for capability decisions
-3. **Improved error messages** - Explain why proposals were used instead of direct requests
-4. **Configuration options** - Allow participants to configure fallback behavior
-
-### Implementation Details
-
-The enhanced `MEWParticipant.request()` method will:
-
-```typescript
-interface RequestOptions {
- timeout?: number;
- preferProposal?: boolean; // Force proposal even if direct is available
- debug?: boolean; // Log capability decisions
-}
-
-async request(
- target: string | string[],
- method: string,
- params?: any,
- options?: RequestOptions
-): Promise {
- const debug = options?.debug || this.options.debug;
-
- // Enhanced capability checking
- const canDirectRequest = this.canSendEnhanced('mcp/request', { method, params });
- const canPropose = this.canSendEnhanced('mcp/proposal', { proposal: { method, params } });
-
- if (debug) {
- this.logger.debug('MCP request capability decision:', {
- method,
- canDirectRequest,
- canPropose,
- preferProposal: options?.preferProposal
- });
- }
-
- // Use proposal if forced or no direct capability
- if (options?.preferProposal || !canDirectRequest) {
- if (!canPropose) {
- throw new Error(
- `Cannot execute ${method}: No capability for mcp/request or mcp/proposal. ` +
- `Available capabilities: ${this.describeCapabilities()}`
- );
- }
- return this.sendProposal(target, method, params, options);
- }
-
- return this.sendRequest(target, method, params, options);
-}
-
-private canSendEnhanced(kind: string, payload?: any): boolean {
- // Try advanced matcher first if available
- if (this.options.useAdvancedMatcher && hasCapability) {
- return hasCapability(
- { capabilities: this.participantInfo.capabilities },
- { kind, payload },
- { cache: true }
- );
- }
-
- // Fall back to simple matcher
- return canSend(this.participantInfo.capabilities, kind, payload);
-}
-```
-
-## Consequences
-
-### Positive
-- ✅ **Minimal disruption** - Enhances existing working code
-- ✅ **Backward compatible** - No breaking changes
-- ✅ **Progressive enhancement** - Advanced features are optional
-- ✅ **Better debugging** - Developers can understand capability decisions
-- ✅ **Flexibility** - Supports different use cases (force proposal, debug mode)
-- ✅ **Right location** - Logic stays in the appropriate architectural layer
-
-### Negative
-- ❌ **Package coupling** - Participant package may depend on capability-matcher
-- ❌ **Increased complexity** - More options and code paths
-- ❌ **Bundle size** - May increase size if advanced matcher is included
-
-### Mitigation Strategies
-
-1. **Make capability-matcher optional** - Use dynamic imports or peer dependencies
-2. **Provide build variants** - Offer basic and enhanced builds
-3. **Clear documentation** - Explain when to use which options
-4. **Performance monitoring** - Ensure enhanced checking doesn't slow down requests
-
-## Future Considerations
-
-1. **Caching Strategy** - Could cache capability decisions for performance
-2. **Proposal Tracking** - Could add proposal status tracking
-3. **Batch Requests** - Could support batching multiple requests
-4. **Request Middleware** - Could add plugin system for request processing
-5. **Metrics Collection** - Could add capability usage metrics
-
-## References
-
-- [MEW Protocol v0.3 Specification](../../spec/v0.3/SPEC.md)
-- [Current MEWParticipant Implementation](../../sdk/typescript-sdk/participant/src/MEWParticipant.ts)
-- [Capability Matcher Package](../../sdk/typescript-sdk/capability-matcher/)
-- [MEW Agent Specification](../../mew-agent/spec/draft/SPEC.md)
diff --git a/spec/protocol/v0.4/rejected/002-dsa-data-stream-announcements.md b/spec/protocol/v0.4/rejected/002-dsa-data-stream-announcements.md
deleted file mode 100644
index a53cbeb4..00000000
--- a/spec/protocol/v0.4/rejected/002-dsa-data-stream-announcements.md
+++ /dev/null
@@ -1,188 +0,0 @@
-# ADR-DSA: Data Stream Announcements
-
-**Status:** Rejected
-**Date:** 2025-01-10
-**Context:** MEW Protocol v0.3
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** Streaming primitives remain out of scope for the v0.4 protocol release; the team will revisit once core request/proposal flows stabilize.
-
-## Context
-
-MEW Protocol currently handles request-response patterns and proposals well, but lacks a mechanism for entities to announce and manage continuous data streams. Many real-world applications require streaming capabilities:
-
-1. **Live Data Feeds**: Entities may need to broadcast sensor data, market prices, or other real-time information
-2. **Progress Updates**: Long-running operations need to stream progress without blocking the protocol
-3. **Event Streams**: Applications need to publish event streams that other entities can observe
-4. **Media Streams**: Audio, video, or other continuous media data needs protocol-level coordination
-
-Without a formal announcement mechanism, entities cannot:
-- Declare their intent to broadcast a stream
-- Allow other entities to discover available streams
-- Coordinate stream lifecycle (start, pause, stop)
-- Prevent stream ID conflicts
-- Enable capability-based access control for streams
-
-## Options Considered
-
-### Option 1: Ad-hoc Streaming
-Allow entities to stream data without formal announcements.
-
-**Pros:**
-- Simple to implement
-- No additional protocol complexity
-
-**Cons:**
-- No discovery mechanism
-- ID conflicts likely
-- No lifecycle management
-- Cannot apply capabilities to streams
-- Other entities can't prepare for incoming data
-
-### Option 2: Stream Announcement Messages
-Add dedicated message types for announcing and managing streams.
-
-**Pros:**
-- Clear protocol-level support
-- Enables discovery and coordination
-- Allows capability-based access control
-- Prevents ID conflicts through announcement
-- Clear lifecycle management
-
-**Cons:**
-- Adds protocol complexity
-- Requires new message types
-
-### Option 3: Overload Existing Messages
-Use existing proposal/notification messages for streams.
-
-**Pros:**
-- No new message types needed
-- Reuses existing patterns
-
-**Cons:**
-- Semantically incorrect (streams aren't proposals)
-- Lacks stream-specific fields
-- Confuses protocol semantics
-
-## Decision
-
-Adopt Option 2: Add dedicated stream announcement messages to the protocol.
-
-### Implementation Details
-
-#### New Message Types
-
-1. **stream.announce**: Entity declares intention to create a stream
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.announce",
- "params": {
- "stream_id": "ctx123:entity456",
- "name": "Market Data Feed",
- "description": "Real-time market prices",
- "content_type": "application/json",
- "metadata": {
- "update_frequency": "100ms",
- "format": "ticker"
- }
- }
-}
-```
-
-2. **stream.start**: Begin streaming data
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.start",
- "params": {
- "stream_id": "ctx123:entity456"
- }
-}
-```
-
-3. **stream.data**: Stream data packet
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.data",
- "params": {
- "stream_id": "ctx123:entity456",
- "sequence": 1,
- "data": {...},
- "timestamp": "2025-01-10T10:00:00Z"
- }
-}
-```
-
-4. **stream.pause**: Temporarily pause streaming
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.pause",
- "params": {
- "stream_id": "ctx123:entity456"
- }
-}
-```
-
-5. **stream.stop**: Terminate stream
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.stop",
- "params": {
- "stream_id": "ctx123:entity456"
- }
-}
-```
-
-6. **stream.list**: Request available streams
-```json
-{
- "jsonrpc": "2.0",
- "method": "stream.list",
- "id": "1"
-}
-```
-
-#### Stream ID Convention
-
-Recommend the convention: `[context_id]:[entity_id]`
-- Ensures uniqueness within a workspace
-- Makes ownership clear
-- Allows filtering by context or entity
-- Example: `game_state:npc_controller`, `sensors:temperature_monitor`
-
-#### Capability Integration
-
-Streams respect capability-based access control:
-- `stream:announce` - Permission to announce new streams
-- `stream:write:[stream_id]` - Permission to write to specific stream
-- `stream:read:[stream_id]` - Permission to read from specific stream
-- `stream:*` - Full stream permissions
-
-#### Stream Lifecycle
-
-1. **Announcement Phase**: Entity announces intent with metadata
-2. **Approval Phase** (optional): If capabilities require, await approval
-3. **Active Phase**: Stream is active, data flows
-4. **Pause Phase** (optional): Temporarily suspended
-5. **Termination Phase**: Clean shutdown with stop message
-
-## Consequences
-
-### Positive
-- **Discovery**: Entities can discover available streams before subscribing
-- **Coordination**: Clear lifecycle management prevents resource leaks
-- **Access Control**: Capability system extends naturally to streams
-- **Conflict Prevention**: Announcement pattern prevents ID collisions
-- **Metadata**: Rich metadata enables informed subscription decisions
-- **Progressive Enhancement**: Systems can ignore stream messages if not needed
-
-### Negative
-- **Protocol Complexity**: Adds 6 new message types to the protocol
-- **Implementation Burden**: All implementations need stream support
-- **State Management**: Entities must track stream state
-- **Backward Compatibility**: Older implementations won't understand stream messages
diff --git a/spec/protocol/v0.4/rejected/002-join-protocol-extension.md b/spec/protocol/v0.4/rejected/002-join-protocol-extension.md
deleted file mode 100644
index 614f6e8b..00000000
--- a/spec/protocol/v0.4/rejected/002-join-protocol-extension.md
+++ /dev/null
@@ -1,109 +0,0 @@
-# ADR-002: Join Protocol Extension for Space Participation
-
-**Status:** Rejected
-**Date:** 2025-01-15
-**Context:** MEW Protocol Draft (post v0.3)
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** Connection and join flows stay implementation-defined for v0.4; standardization needs deeper security review before inclusion.
-
-## Context
-
-MEW Protocol v0.3 defines message exchange semantics but does not specify how participants initially join spaces. The protocol assumes participants are already connected and authenticated, leaving the join mechanism as an implementation gap.
-
-Current implementations have created inconsistent join patterns:
-- Legacy format: `{"type": "join", "participantId": "...", "space": "...", "token": "..."}`
-- MEW-style format: `{"kind": "system/join", "payload": {...}}`
-
-This inconsistency creates protocol compliance issues and interoperability problems between implementations.
-
-## Decision
-
-Extend MEW Protocol with a standardized `system/join` message kind for space participation.
-
-### Join Message Format:
-```json
-{
- "protocol": "mew/v0.3",
- "id": "join-{uuid}",
- "ts": "{iso8601-timestamp}",
- "from": "{participant-id}",
- "kind": "system/join",
- "payload": {
- "space": "{space-identifier}",
- "participant": "{participant-id}",
- "token": "{authentication-token}",
- "capabilities": ["{requested-capabilities}"]
- }
-}
-```
-
-### Gateway Response:
-Success: `system/welcome` with assigned capabilities
-Failure: `system/error` with rejection reason
-
-## Rationale
-
-1. **Protocol Consistency**: All messages follow MEW envelope format
-2. **Authentication Integration**: Token-based auth fits MEW security model
-3. **Capability Negotiation**: Supports MEW's capability-based access control
-4. **Audit Trail**: Standard envelope provides message tracking
-5. **Implementation Guidance**: Removes ambiguity for new implementations
-
-## Impact
-
-### Protocol Changes:
-- **New Message Kind**: `system/join` joins the `system/*` namespace
-- **Authentication Semantics**: Defines token-based participant authentication
-- **Response Pattern**: Standardizes `system/welcome` response with capabilities
-
-### Implementation Requirements:
-- Gateways MUST handle `system/join` messages
-- Gateways MUST respond with `system/welcome` or `system/error`
-- Clients MUST use proper MEW envelope format for join requests
-
-### Backward Compatibility:
-- Existing v0.3 implementations may continue using implementation-specific join
-- New implementations SHOULD adopt standardized format
-- Transition period allows dual format support
-
-## Alternatives Considered
-
-### Option 1: Keep Implementation-Specific
-**Rejected**: Creates interoperability issues and protocol fragmentation
-
-### Option 2: MCP-Style Handshake
-**Rejected**: MEW uses broadcast model, not client-server handshake
-
-### Option 3: HTTP-Only Authentication
-**Rejected**: Doesn't align with WebSocket-primary MEW transport model
-
-## Consequences
-
-### Positive:
-- **Interoperability**: Standard join mechanism across implementations
-- **Protocol Completeness**: Addresses missing authentication semantics
-- **Tooling Support**: Protocol analyzers can parse join sequences
-- **Security Clarity**: Well-defined authentication flow
-
-### Negative:
-- **Breaking Change**: Existing implementations need updates
-- **Complexity**: Requires capability negotiation logic
-- **Specification Growth**: Adds protocol surface area
-
-### Migration Path:
-1. **Phase 1**: Add to draft specification
-2. **Phase 2**: Update reference implementations
-3. **Phase 3**: Deprecate non-standard formats
-4. **Phase 4**: Include in next major protocol version
-
-## Related Decisions
-
-- Links to capability assignment mechanisms
-- Relates to authentication and authorization patterns
-- Connects to space management semantics
-
-## References
-
-- MEW Protocol v0.3 Specification: Message envelope format
-- Implementation analysis: CLI gateway join handling inconsistencies
diff --git a/spec/protocol/v0.4/rejected/003-ctx-simplify-context-terminology.md b/spec/protocol/v0.4/rejected/003-ctx-simplify-context-terminology.md
deleted file mode 100644
index 8e9a36b0..00000000
--- a/spec/protocol/v0.4/rejected/003-ctx-simplify-context-terminology.md
+++ /dev/null
@@ -1,96 +0,0 @@
-# ADR-CTX: Simplify Context Terminology
-
-**Status:** Rejected
-**Date:** 2025-01-10
-**Context:** MEW Protocol v0.3
-**Incorporation:** Not Incorporated
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** Terminology cleanup will ride a future comprehensive documentation pass; v0.4 keeps existing wording to avoid churn during release prep.
-
-## Context
-
-The current specification uses the term "sub context" or "sub-context" to refer to logical groupings within a workspace. This terminology is unnecessarily complex and hierarchical when the actual relationship is more about partitioning or namespacing rather than true hierarchy.
-
-The term "sub context" implies:
-1. A parent-child relationship that doesn't truly exist in the protocol
-2. Nested contexts, which the protocol doesn't support
-3. Dependency relationships that aren't enforced
-
-In practice, these are simply separate contexts within a shared workspace, each with their own ID and scope. The "sub" prefix adds confusion without adding meaning.
-
-## Options Considered
-
-### Option 1: Keep "Sub Context"
-Maintain the current terminology with "sub context" or "sub-context".
-
-**Pros:**
-- No documentation changes needed
-- May imply the scoping relationship to some readers
-
-**Cons:**
-- Implies hierarchy that doesn't exist
-- Unnecessarily verbose
-- Confusing for new implementers
-- Inconsistent with the flat nature of the protocol
-
-### Option 2: Use "Context"
-Simplify to just "context" throughout the specification.
-
-**Pros:**
-- Simpler and clearer
-- Accurately represents the flat namespace
-- Reduces cognitive load
-- More consistent with actual protocol behavior
-
-**Cons:**
-- Requires updating documentation
-- Might initially confuse readers expecting hierarchy
-
-### Option 3: Use "Channel" or "Room"
-Replace with alternative terms like "channel" or "room".
-
-**Pros:**
-- Familiar from chat applications
-- Clearly indicates separate spaces
-
-**Cons:**
-- Conflicts with existing "workspace" terminology
-- "Channel" implies communication path rather than logical grouping
-- "Room" has physical connotations that don't apply
-
-## Decision
-
-Adopt Option 2: Use "context" throughout the specification, removing the "sub" prefix.
-
-### Implementation Details
-
-1. **Terminology Updates**:
- - Replace all instances of "sub context" with "context"
- - Replace all instances of "sub-context" with "context"
- - Update any references to "subcontext" to "context"
-
-2. **Field Updates**:
- - Fields remain unchanged (already use `context_id` not `sub_context_id`)
- - No protocol changes required
-
-3. **Clarification**:
- - Add a note that contexts are independent namespaces within a workspace
- - Clarify that contexts don't have hierarchical relationships
- - Explain that context IDs are flat identifiers
-
-4. **Examples**:
- - Update all examples to use simplified terminology
- - Show how contexts partition the workspace without hierarchy
-
-## Consequences
-
-### Positive
-- **Clarity**: Removes confusion about hierarchical relationships
-- **Simplicity**: Easier to understand and explain
-- **Accuracy**: Better represents the actual protocol structure
-- **Consistency**: Aligns terminology with implementation
-
-### Negative
-- **Documentation Update**: One-time effort to update all references
-- **Mental Model Shift**: Readers familiar with "sub context" need to adjust
-- **Potential Ambiguity**: Without "sub", might need additional clarification that contexts exist within workspaces
diff --git a/spec/protocol/v0.4/rejected/009-gateway-io-options.md b/spec/protocol/v0.4/rejected/009-gateway-io-options.md
deleted file mode 100644
index 8ccb9816..00000000
--- a/spec/protocol/v0.4/rejected/009-gateway-io-options.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# ADR-009: Gateway I/O Options for Participant Communication
-
-## Status
-Rejected
-
-**Rejection Date:** 2025-09-26
-**Rejection Rationale:** Gateway I/O expansion is deferred; v0.4 only documents existing WebSocket interface while we validate desired operational requirements.
-
-## Context
-Currently, the MEW Protocol gateway only accepts WebSocket connections for participants. This creates limitations:
-1. Testing is complex - requires WebSocket clients or FIFO workarounds
-2. CLI tools need WebSocket support to interact with spaces
-3. Simple scripts can't easily send messages without WebSocket libraries
-4. No way to inject messages for testing or debugging
-
-## Decision
-Add two additional I/O mechanisms to the gateway alongside WebSocket:
-
-### 1. HTTP REST API for Message Injection
-The gateway will expose HTTP endpoints for sending messages on behalf of participants:
-
-```
-POST /participants/{participant_id}/messages
-Authorization: Bearer {token}
-Content-Type: application/json
-
-{
- "kind": "chat",
- "payload": {
- "text": "Hello world"
- }
-}
-```
-
-### 2. Stdio Support for Direct Process Communication
-The gateway can spawn participant processes with stdio communication:
-
-```yaml
-participants:
- my-agent:
- command: "./my-agent"
- args: ["--mode", "stdio"]
- io: stdio # Uses stdin/stdout instead of WebSocket
-```
-
-## Implementation Details
-
-### HTTP API Endpoints
-```
-POST /participants/{participant_id}/messages # Send a message
-GET /participants/{participant_id}/messages # Poll for messages (long-polling)
-GET /participants # List active participants
-```
-
-### Message Flow
-1. **HTTP Input**: Messages posted to HTTP endpoint are validated and injected as if from that participant
-2. **Stdio Input**: Messages from process stdout are parsed as JSON envelopes
-3. **WebSocket**: Existing bidirectional communication continues unchanged
-
-### Authentication
-- HTTP: Bearer token in Authorization header
-- Stdio: Implicit trust (process spawned by gateway)
-- WebSocket: Existing token-based auth
-
-### Configuration
-```yaml
-# space.yaml
-gateway:
- http:
- enabled: true
- port: 8080
- bind: "127.0.0.1"
-
-participants:
- websocket-agent:
- tokens: ["token-1"]
- # Default: connects via WebSocket
-
- stdio-agent:
- command: "./agent"
- io: stdio
- # Spawned process, communicates via stdin/stdout
-
- http-client:
- tokens: ["token-2"]
- io: http
- # Expects HTTP API calls
-```
-
-## Consequences
-
-### Positive
-- **Simpler Testing**: Tests can use curl/HTTP instead of WebSocket clients
-- **Better CLI Integration**: Command-line tools can POST messages easily
-- **Debugging**: Can inject test messages via HTTP during development
-- **Process Management**: Gateway can spawn and manage participant processes
-- **Flexibility**: Participants can choose the most appropriate I/O mechanism
-
-### Negative
-- **Complexity**: Gateway must handle three different I/O mechanisms
-- **Security**: HTTP endpoint needs careful authentication/authorization
-- **Message Ordering**: HTTP polling may miss messages or receive out-of-order
-- **Resource Usage**: Long-polling connections consume server resources
-
-### Neutral
-- HTTP is request-response, not bidirectional like WebSocket
-- Stdio requires gateway to manage process lifecycle
-- Different I/O mechanisms have different performance characteristics
-
-## Alternatives Considered
-
-1. **FIFO Pipes Only**: Too platform-specific, blocking issues
-2. **Message Queue (RabbitMQ/Redis)**: Additional infrastructure dependency
-3. **gRPC**: More complex than needed for simple message passing
-4. **Socket Files**: Platform-specific, similar issues to FIFOs
-
-## Migration Path
-
-1. Phase 1: Add HTTP API to gateway (backward compatible)
-2. Phase 2: Add stdio support for spawned processes
-3. Phase 3: Update tests to use HTTP instead of FIFOs
-4. Phase 4: Document patterns for each I/O mechanism
-
-## Decision Outcome
-Implement HTTP REST API first for testing simplification, then add stdio support for process management. This provides maximum flexibility while maintaining backward compatibility with existing WebSocket participants.
diff --git a/spec/protocol/v0.4/rejected/README.md b/spec/protocol/v0.4/rejected/README.md
deleted file mode 100644
index f564b122..00000000
--- a/spec/protocol/v0.4/rejected/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Rejected ADRs
-
-This folder contains rejected Architecture Decision Records kept for historical context.
-
-## Current Status
-
-The following ADRs were rejected prior to the v0.4 release:
-- ADR-REN — Rename Participant to Entity
-- ADR-WCM — Where to Put MCP Request/Proposal Auto-Conversion Logic
-- ADR-DSA — Data Stream Announcements (streams documented directly in the spec)
-- ADR-002 — Join Protocol Extension for Space Participation
-- ADR-CTX — Simplify Context Terminology
-- ADR-009 — Gateway I/O Options for Participant Communication (non-WebSocket I/O remains optional guidance)
-
-## Format
-
-When ADRs are rejected from `proposed/`:
-- Renumber based on rejection order
-- Maintain the ADR ID for reference
-- Update Status to "Rejected"
-- Add rejection rationale to the document
diff --git a/spec/repo/REPO-SPEC.md b/spec/repo/REPO-SPEC.md
deleted file mode 100644
index 12bfafe2..00000000
--- a/spec/repo/REPO-SPEC.md
+++ /dev/null
@@ -1,488 +0,0 @@
-# REPO SPEC
-
-## Summary
-
-Publish one npm package, `@mew-protocol/mew`, that contains:
-- Library subpaths: `@mew-protocol/mew/{types,client,participant,agent,gateway,capability-matcher,bridge}`
-- Executables (bins):
- - `mew` (primary CLI)
- - Subcommands: `mew agent …`, `mew bridge …`
- - Additional binaries: `mew-agent`, `mew-bridge` → thin shims that forward to `mew agent` / `mew bridge`
-
-Outcome:
-- One install, one version, one publish.
-- Templates depend only on `@mew-protocol/mew`.
-- Keeps modular imports via subpath exports.
-- No workspace configuration needed (single package).
-
-## Goals / Non-goals
-
-Goals
-- Simplify release to a single publish target.
-- Preserve modular code organization and import ergonomics.
-- Offer a clean CLI UX with subcommands while maintaining compatibility with existing bin names.
-
-Non-goals
-- Changing protocol specs or scenario harnesses.
-- Deep refactors of SDK internals beyond packaging and exports.
-
-## Package Structure
-
-```
-packages/mew/ # Single published package
- package.json # name: @mew-protocol/mew
- tsconfig.json # unified build config (no per-module configs)
- src/
- bin/
- mew.js # main CLI with subcommands (JS first)
- mew-agent.js # shim → invokes `mew agent …` (optional)
- mew-bridge.js # shim → invokes `mew bridge …` (optional)
- cli/ # CLI implementation (JS, no package.json)
- commands/
- ui/
- utils/
- types/ # Library source (TS, no package.json)
- index.ts
- protocol.ts
- mcp.ts
- client/ # Library source (TS, no package.json)
- index.ts
- MEWClient.ts
- types.ts
- participant/ # Library source (TS, no package.json)
- index.ts
- MEWParticipant.ts
- capabilities.ts
- agent/ # Library source (TS, no package.json)
- index.ts
- MEWAgent.ts
- capability-matcher/ # Library source (TS, no package.json)
- index.ts
- matcher.ts
- bridge/ # Library source (TS, no package.json)
- index.ts
- mcp-bridge.ts
- templates/ # CLI templates
- dist/ # Build output (gitignored)
-```
-
-## Repository Structure (Target)
-
-Top-level layout after consolidation to a single published package:
-
-```
-.
-├─ packages/
-│ └─ mew/ # Single published package (@mew-protocol/mew)
-│ ├─ package.json # name, bins, exports
-│ ├─ src/
-│ │ ├─ bin/ # Executables and shims
-│ │ │ ├─ mew.js # primary CLI with subcommands (JS first)
-│ │ │ ├─ mew-agent.js # shim → runs `mew agent …`
-│ │ │ └─ mew-bridge.js # shim → runs `mew bridge …`
-│ │ ├─ cli/ # CLI implementation (commands, UI) — JS first
-│ │ │ ├─ commands/
-│ │ │ ├─ ui/
-│ │ │ │ ├─ components/
-│ │ │ │ ├─ hooks/
-│ │ │ │ └─ utils/
-│ │ │ └─ utils/
-│ │ ├─ types/ # Library subpaths (sources or re-exports)
-│ │ ├─ client/
-│ │ ├─ participant/
-│ │ ├─ agent/
-│ │ ├─ gateway/
-│ │ ├─ capability-matcher/
-│ │ └─ bridge/
-│ ├─ templates/ # CLI templates bundled with the package
-│ │ ├─ cat-maze/
-│ │ ├─ coder-agent/
-│ │ └─ note-taker/
-│ ├─ dist/ # Build output (ESM + .d.ts, bin JS)
-│ ├─ tsconfig.json # unified build config
-│ ├─ CHANGELOG.md
-│ ├─ README.md
-│ └─ spec/ # CLI specs
-├─ spaces/ # Manual dev spaces (uses local CLI + link:)
-├─ tests/ # Integration scenarios (scenario-*)
-├─ mew-protocol-spec/ # MEW Protocol specification (separate from implementation)
-│ ├─ draft/ # Draft protocol spec
-│ ├─ v0.4/ # Current stable protocol version
-│ └─ README.md # Protocol overview
-├─ repo-spec/ # Repository structure specification
-│ ├─ REPO-SPEC.md # This file - describes repo organization
-│ └─ decisions/ # Architecture Decision Records for implementation
-│ └─ 015-cli-typescript-conversion.md
-├─ docs/ # Architecture, guides, progress
-├─ .github/ # CI workflows
-├─ package.json # private root with repo-level scripts
-├─ tsconfig.base.json # shared TS settings
-├─ RELEASE.md # release guide (updated for single package)
-└─ README.md
-```
-
-Notes:
-- Only `packages/mew` is published to npm. The root remains `private: true` with repo-level scripts.
-- No workspace configuration needed (single package eliminates hoisting complexity).
-- CLI code lives under `packages/mew/src/cli/` and `packages/mew/src/bin/`.
-- Library modules live under `packages/mew/src/{types,client,participant,agent,gateway,capability-matcher,bridge}` and are exposed via subpath exports.
-- Templates ship from `packages/mew/templates/`.
-- **Spec organization**:
- - `mew-protocol-spec/`: MEW Protocol specification (versioned, independent of implementation)
- - `repo-spec/`: Repository structure and implementation ADRs
- - `packages/mew/spec/`: CLI package versioned specifications
-
-## Package.json (sketch)
-
-```
-{
- "name": "@mew-protocol/mew",
- "type": "module",
- "bin": {
- "mew": "dist/bin/mew.js",
- "mew-agent": "dist/bin/mew-agent.js",
- "mew-bridge": "dist/bin/mew-bridge.js"
- },
- "exports": {
- ".": "./dist/index.js",
- "./types": "./dist/types/index.js",
- "./client": "./dist/client/index.js",
- "./participant": "./dist/participant/index.js",
- "./agent": "./dist/agent/index.js",
- "./gateway": "./dist/gateway/index.js",
- "./capability-matcher": "./dist/capability-matcher/index.js",
- "./bridge": "./dist/bridge/index.js"
- }
-}
-```
-
-## Build Strategy
-
-### TypeScript Configuration
-
-The package uses **`"moduleResolution": "bundler"`** with ESM output:
-
-- **Module settings**: `"module": "ESNext"`, `"moduleResolution": "bundler"`, `"type": "module"`
-- **Rationale**: Pragmatic approach used by real-world ESM libraries (e.g., @langchain/core)
-- **Benefits**:
- - No `.js` extension required in relative imports (developer-friendly)
- - Still produces valid ESM output
- - Compatible with modern bundlers and Node.js ESM
-- **Alternative considered**: `"moduleResolution": "NodeNext"` requires explicit `.js` extensions in all imports, adding friction without clear benefit for this use case
-
-See `tsconfig.base.json` for the canonical settings.
-
-### Build Patterns
-
-Two viable patterns; choose one to keep things simple:
-
-1) Multi-entry bundle for bins, plain ESM for libraries (recommended MVP)
-- Use `tsc` to emit ESM and `.d.ts` for the library subpaths.
-- Use `tsup` (or `rollup`) to bundle `src/bin/mew.js` into `dist/bin/mew.js` with a shebang (source can be JS initially).
-- Provide shims `mew-agent.js` and `mew-bridge.js` that invoke the `mew` entry with `agent` or `bridge` subcommands.
-
-2) Single tool for all entries
-- Use a single `tsup` config with multiple entries (library + bins), emitting ESM for libraries and preserving tree-shaking. Slightly more config, still one command.
-
-## CLI UX
-
-- Primary: `mew …` with subcommands
- - `mew agent …`
- - `mew bridge …`
-- Compatibility (optional):
- - `mew-agent …` ≡ `mew agent …`
- - `mew-bridge …` ≡ `mew bridge …`
-
-## Templates
-
-- Update all templates to depend on a single package:
- ```json
- {
- "dependencies": {
- "@mew-protocol/mew": "^X.Y.Z"
- }
- }
- ```
-- CLI continues to rewrite dependencies during local dev/tests.
-
-### Entry Points
-
-- Binaries (package.json):
- ```json
- {
- "bin": {
- "mew": "dist/bin/mew.js",
- "mew-agent": "dist/bin/mew-agent.js",
- "mew-bridge": "dist/bin/mew-bridge.js"
- }
- }
- ```
-- Subpath exports (as specified above) for all libraries.
-
-### Transitional Compatibility (Optional)
-
-- During migration, you may keep thin wrapper bin files to preserve old entry points (`mew-agent`, `mew-bridge`). These can be removed after downstreams update to `mew agent` / `mew bridge`.
-
-## Spaces and Tests: Local Dependency Strategy
-
-### Phase 4 Update: Global Install Required for PM2
-
-**Templates no longer have `package.json` or `node_modules`**. All dependencies (including MCP
-servers and agents) are now bundled in the CLI package itself and accessed via `mew` subcommands.
-
-Templates use PM2 to start participants with commands like:
-- `mew agent run --gateway ws://localhost:${PORT} ...`
-- `mew bridge start --mcp-command mew --mcp-args mcp,filesystem,...`
-
-**This requires the `mew` command to be available globally** when PM2 starts processes.
-
-### Inside the Repo (Dev Mode)
-
-**Required setup before testing**:
-```bash
-# Build and install globally from local source
-npm run build
-npm install -g .
-
-# Now use global mew command for everything
-cd tests/test-feature
-mew space init .
-mew space up
-mew space connect
-```
-
-**After code changes**:
-```bash
-npm run build
-npm install -g . # Reinstall to pick up changes
-```
-
-**Alternative - npm link** (faster iteration):
-```bash
-npm link # One-time setup
-# After code changes:
-npm run build # Just rebuild, link is persistent
-```
-
-Environment overrides (optional):
-- `MEW_FORCE_PUBLISHED`: if set, uses published `@mew-protocol/mew` from registry instead of local.
-
-### Outside the Repo (Published Mode)
-
-- CLI behaves as a normal consumer; templates use globally installed `mew` command.
-- Install: `npm install -g @mew-protocol/mew`
-
-### spaces/README.md Integration
-
-- Spaces created under `spaces/` are for interactive local dev. The README should document:
- - Building and installing globally: `npm run build && npm install -g .`
- - Creating a new space: `cd spaces && mkdir test && cd test`
- - Using global mew command: `mew space init .`, `mew space up`, `mew space connect`
-
-### tests/README.md Integration
-
-- Scenario harnesses create disposable workspaces under `tests/scenario-*/.workspace`.
-- Test runner (`tests/run-all-tests.sh`) installs globally once at the start.
-- All scenarios use global `mew` command (not local wrapper paths).
-- Example in setup.sh:
- ```bash
- # Use global mew for all commands
- mew init "${TEMPLATE_NAME}" --force --name "${SPACE_NAME}"
- mew space up --space-dir . --port "${TEST_PORT}" --detach
- ```
-
-### Rationale
-
-- **Why global install?** PM2 spawns processes independently and needs `mew` in PATH.
-- **Why not local paths in templates?** Templates are shipped to users and can't have repo-relative paths.
-- **Why not bundle everything?** Phase 4 accomplished this - templates have no dependencies, everything is in the CLI package.
-
-### Fallback Behavior and Robustness
-
-- If global `mew` is not found, `space up` will fail with clear error from PM2.
-- The CLI can detect if running from repo and warn if global install is outdated.
-
-## Operating Modes & Release Process
-
-This section consolidates four concerns: developer workflow, manual space testing, E2E testing, and
-the single‑package release process.
-
-### 1) Developer Workflow (Dev)
-
-- Edit code in `packages/mew/src/**`.
-- Build locally:
- - From root: `npm run build` (uses TypeScript project references)
- - From package: `cd packages/mew && npm run build:all`
-- Optional watch task for fast iteration: `cd packages/mew && npm run dev`.
-- Run CLI from source (dev):
- - With compat wrapper: `./cli/bin/mew.js …` (for existing scripts) → forwards to `packages/mew/dist/bin/mew.js`.
- - Or direct: `node packages/mew/dist/bin/mew.js …`.
-- Lint/format: `npm run lint`, `npm run format` (delegates to packages/mew).
-
-### 2) Spaces Testing (Manual Integration)
-
-Manual "spaces" exist under `spaces/` for developer exploration:
-
-```bash
-# First time: build and install globally
-npm run build
-npm install -g .
-
-cd spaces && mkdir test-demo && cd test-demo
-# Use global mew for all commands
-mew space init .
-mew space up
-mew space connect
-```
-
-Key points:
-- Templates no longer have `package.json` - all dependencies bundled in CLI.
-- All commands use global `mew` (required for PM2 to find it in PATH).
-- After code changes: `npm run build && npm install -g .` to reinstall.
-- Alternative for faster iteration: `npm link` once, then just `npm run build` after changes.
-
-### 3) Tests Testing (E2E Scenarios)
-
-E2E tests live under `tests/scenario-*` and create disposable workspaces under `.workspace/`:
-
-```bash
-# First time: build and install globally
-npm run build
-npm install -g .
-
-# Run all non‑LLM scenarios (test runner installs globally automatically)
-npm run test
-
-# Or invoke a single scenario's shell orchestrator
-tests/scenario-14-cat-maze/test.sh
-```
-
-Behavior:
-- Test runner (`tests/run-all-tests.sh`) builds and installs globally before running scenarios.
-- All scenarios use global `mew` command consistently.
-- Logs and envelope history validate protocol flows; failures surface in scenario logs.
-
-### 4) Release Process (Single Package)
-
-Pre‑release checks:
-- Build & pack from a clean tree:
- ```bash
- npm ci
- npm --workspace packages/mew run build:all
- (cd packages/mew && npm pack --dry-run)
- ```
-- E2E: `npm run test` (expect green on core scenarios).
-- Manual smoke: create a temp dir and test `mew` from the packed tarball.
-
-Versioning & changelog:
-- Bump version in `packages/mew/package.json` (semver) and update `packages/mew/CHANGELOG.md`.
-
-Publish:
-```bash
-cd packages/mew
-npm publish --access public --otp=XXXXXX
-```
-
-Tag & push:
-```bash
-git tag mew-vX.Y.Z
-git push origin main --tags
-```
-
-Post‑publish verification:
-```bash
-TMP=$(mktemp -d)
-cd "$TMP" && npm init -y >/dev/null 2>&1
-npm install @mew-protocol/mew@latest
-./node_modules/.bin/mew --version
-./node_modules/.bin/mew space init --template coder-agent demo
-```
-
-Notes:
-- Templates ship with the package; no separate publish for CLI/templates.
-- Compat bins (`mew-agent`, `mew-bridge`) are optional; keep them during the migration window.
-
-## Migration
-
-Phase 1 — Package consolidation ✅ COMPLETED
-- Create `packages/mew` directory structure
-- Move SDK library modules, bridge, and CLI to packages/mew/src/
-- Move templates to packages/mew/templates/
-- Update root package.json workspaces
-- Create packages/mew/package.json
-
-Phase 2 — Flatten and integrate ✅ COMPLETED
-- Flatten src/ structure (remove nested src/ in each module)
-- Remove per-module metadata files (package.json, tsconfig.json, etc.)
-- Create unified packages/mew/tsconfig.json
-- Move CLI metadata (CHANGELOG, README, spec) to packages/mew/
-- Create stable CLI wrapper at cli/bin/mew.js
-- Update templates to depend on `@mew-protocol/mew`
-- Clean up old directories
-
-Phase 3 — Import paths and build system ✅ COMPLETED
-- ✅ Update all import paths in source code (relative imports within package)
-- ✅ Switch to `moduleResolution: "bundler"` for pragmatic ESM support
-- ✅ Set up TypeScript build (tsc for libraries)
-- ✅ Convert CLI from CommonJS to ESM (all 20 files converted)
-- ✅ Add bridge command to CLI (mew bridge start)
-- ✅ Set up bin bundling (tsup for CLI binaries)
-- ✅ Update test harnesses to use new paths (CLI wrapper forwards to dist/bin/mew.js)
-- ✅ Wire bin shims (mew-agent, mew-bridge)
-
-Phase 4 — Publish & verify
-- Test `npm pack` from packages/mew
-- Smoke tests on bins from tarball: `mew --version`, `mew space init`
-- Update all documentation
-- First publish of @mew-protocol/mew
-
-Phase 5 — (Optional) retire individual SDK packages
-- Publish deprecation notes or compatibility stubs for a short window.
-
-## Execution Plan & Order of Operations
-
-To minimize risk and maximize speed, defer the CLI TypeScript refactor until after
-the single‑package consolidation is shipped:
-
-1) Deliver Option 4 MVP first (Phases 1–3 above):
- - One npm package `@mew-protocol/mew`
- - `mew` with `agent`/`bridge` subcommands (+ optional shims)
- - Library subpath exports
- - Templates updated to a single dependency
-
-2) After consolidation is stable, perform the CLI TypeScript refactor as a
- follow‑up (tracked separately from this spec):
- - Convert CLI JS → TS with minimal behavior change
- - Keep subcommand UX intact
- - Add tarball smoke tests and types emission
-
-Rationale for sequencing: isolates packaging changes from language refactors,
-delivers the biggest release simplification first, and keeps debugging scopes
-small if issues arise.
-
-## Testing
-
-- Keep existing scenario tests; they run via the `mew` binary.
-- Add a minimal bin smoke suite in CI:
- - `npm pack` → install in temp dir → run `mew --version`, `mew agent --help`, `mew bridge --help`.
-
-## Risks & Mitigations
-
-- Larger install size → mitigate by externalizing heavyweight peer deps where safe and relying on ESM tree-shaking for libs.
-- Bin dispatch regressions → maintain optional bin shims for compatibility; add smoke tests.
-
-## Acceptance Criteria
-
-- One npm package publishes successfully with working `mew` subcommands.
-- Templates install and run using only `@mew-protocol/mew`.
-- Integration scenarios pass without changes beyond dependency names.
-
-## Protocol Spec Placement
-
-- Canonical sources remain under `spec/` with versioned folders (`spec/v0.x/`) and draft (`spec/draft/`).
-- Add a root `SPEC.md` that links to:
- - Latest stable: `spec/v0.4/SPEC.md` (update as versions change)
- - Draft (next): `spec/draft/SPEC.md`
- - ADR index: `spec/draft/decisions/`
-- Root `README.md` gets a short “Protocol Spec” section linking to `SPEC.md`.
-- The published npm package excludes `spec/` (docs live in GitHub, not the tarball).
diff --git a/spec/repo/decisions/015-clt-cli-typescript-conversion.md b/spec/repo/decisions/015-clt-cli-typescript-conversion.md
deleted file mode 100644
index b0a9354c..00000000
--- a/spec/repo/decisions/015-clt-cli-typescript-conversion.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# ADR 015: Convert CLI from JavaScript to TypeScript
-
-**Status**: Proposed
-**Date**: 2025-09-30
-**Deciders**: Core Team
-**Tags**: cli, typescript, build-system, module-resolution
-
-## Context
-
-During Phase 4 of the repository restructure, we consolidated all packages into a single `@mew-protocol/mew` package. The library code (types, client, participant, agent, gateway, bridge) is written in TypeScript, while the CLI (commands, UI, utilities) was converted from CommonJS to ESM JavaScript.
-
-This mixed JavaScript/TypeScript setup has created a critical module resolution issue:
-
-### The Problem
-
-1. **TypeScript with `moduleResolution: "bundler"`** emits imports without `.js` extensions:
- ```typescript
- // src/agent/index.ts compiles to:
- import { MEWAgent } from './MEWAgent'; // No .js extension
- ```
-
-2. **Node.js ESM requires `.js` extensions** for relative imports:
- ```typescript
- // Node.js needs:
- import { MEWAgent } from './MEWAgent.js';
- ```
-
-3. **Bundled CLI tries to dynamically import library code**:
- ```javascript
- // src/cli/commands/agent.js attempts:
- const { MEWAgent } = await import('@mew-protocol/mew/agent');
- // This fails because the built agent/index.js has broken imports
- ```
-
-### Impact
-
-- `mew agent run` command is completely broken
-- Templates that use `mew agent run` (coder-agent, cat-maze) cannot start agents
-- Dynamic imports from CLI → library are unreliable
-- Build system fragmentation (tsup for CLI, tsc for library)
-
-### Current Workarounds Attempted
-
-1. **Dynamic import with relative paths**: Bundler still tries to resolve and breaks
-2. **Dynamic import with package subpath**: Library code has broken imports
-3. **External dependencies in bundler**: Doesn't solve the core TypeScript → Node.js ESM mismatch
-
-## Decision
-
-**Convert the entire CLI codebase from JavaScript to TypeScript** and adopt consistent ESM module resolution across the entire package.
-
-### Migration Strategy
-
-#### Phase 5.2: CLI Conversion (~20 files)
-- Convert `src/cli/utils/*.js` → `*.ts`
-- Convert `src/cli/commands/*.js` → `*.ts` (12 command files)
-- Convert `src/cli/ui/*.js` → `*.ts`
-- Convert `src/cli/index.js` → `index.ts`
-- Update `tsup.config.js` entry points to `.ts`
-
-#### Phase 5.3: Module Resolution Fix
-- Change `moduleResolution: "bundler"` → `"NodeNext"` in `tsconfig.json`
-- Add `.js` extensions to **all** relative imports across the codebase (~50 files total)
-- Use TypeScript's new `rewriteRelativeImportExtensions` option if needed
-- Ensure `tsc` and `tsup` both produce correct output
-
-#### Phase 5.4: Testing
-- Test `mew agent run` command works
-- Test all three templates end-to-end
-- Run full integration test suite
-- Verify no regressions in existing commands
-
-## Consequences
-
-### Positive
-
-- **Unified codebase**: One language, one set of module resolution rules
-- **Type safety in CLI**: Catch errors at compile time instead of runtime
-- **Fixes dynamic imports**: Library code will have correct `.js` extensions
-- **Better IDE support**: Full TypeScript IntelliSense throughout
-- **Consistent build**: Same TypeScript compiler for everything
-- **Future-proof**: Proper ESM that works with Node.js and bundlers
-
-### Negative
-
-- **Migration effort**: ~20 files to convert, ~50 files to add `.js` extensions
-- **Breaking change risk**: Must test thoroughly to avoid regressions
-- **Slight complexity**: TypeScript requires explicit `.js` in imports (but this is correct ESM)
-
-### Neutral
-
-- **Build time**: May increase slightly, but likely negligible
-- **Bundle size**: Should remain approximately the same
-- **Learning curve**: Team already knows TypeScript
-
-## Alternatives Considered
-
-### Alternative 1: Keep CLI as JavaScript, fix library imports manually
-- Add a post-processing step to add `.js` extensions to built library files
-- **Rejected**: Hacky, error-prone, doesn't solve root cause
-
-### Alternative 2: Use CommonJS for everything
-- Convert back to CommonJS to avoid ESM import issues
-- **Rejected**: ESM is the future, we've already committed to it
-
-### Alternative 3: Don't use dynamic imports
-- Bundle MEWAgent directly into CLI
-- **Rejected**: Creates bundling issues with micromatch, increases bundle size significantly
-
-### Alternative 4: Remove `mew agent run`, use template scripts only
-- Templates provide their own agent scripts (like note-taker)
-- **Rejected**: Less convenient UX, doesn't solve underlying issue
-
-## Implementation Plan
-
-### Phase 5.1: Documentation ✓
-- [x] Create this ADR
-- [x] Update TODO.md with Phase 5 plan
-
-### Phase 5.2: CLI Conversion (Est. 2-3 hours)
-- [ ] Update `packages/mew/tsconfig.json` to include `src/cli/**/*.ts`
-- [ ] Convert utility files first (smallest, fewest dependencies)
-- [ ] Convert command files one by one, testing incrementally
-- [ ] Convert UI components
-- [ ] Convert main CLI entry point
-- [ ] Update `tsup.config.js` entry points
-
-### Phase 5.3: Module Resolution (Est. 1-2 hours)
-- [ ] Change `moduleResolution` to `"NodeNext"`
-- [ ] Add `.js` extensions to all relative imports (use find/replace + manual review)
-- [ ] Fix any build errors
-- [ ] Verify `tsc` output is correct
-- [ ] Verify `tsup` bundles work
-
-### Phase 5.4: Testing (Est. 1 hour)
-- [ ] Build and install globally
-- [ ] Test `mew agent run`
-- [ ] Test all three templates
-- [ ] Run integration tests
-- [ ] Fix any issues found
-
-**Total estimated time**: 4-6 hours
-
-## References
-
-- [Node.js ESM documentation](https://nodejs.org/api/esm.html)
-- [TypeScript Module Resolution](https://www.typescriptlang.org/docs/handbook/modules/theory.html#module-resolution)
-- [TypeScript 5.0 - moduleResolution: "bundler"](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-0.html#moduleresolution-bundler)
-- Phase 4 work: Template dependency refactor (REFACTOR-TEMPLATE-DEPS.md)
-- Related: ADR 012 (secure token generation), ADR 014 (gateway envelope tracing)
\ No newline at end of file
diff --git a/spec/scratch/MESSAGE-FORMATTERS.md b/spec/scratch/MESSAGE-FORMATTERS.md
deleted file mode 100644
index 7c7861d8..00000000
--- a/spec/scratch/MESSAGE-FORMATTERS.md
+++ /dev/null
@@ -1,189 +0,0 @@
-# Message Formatters Inventory
-
-## Overview
-
-This document inventories which MEW protocol messages have dedicated formatters in the CLI and which don't. Formatters provide enhanced display formatting for specific message types in the interactive terminal UI.
-
-## Message Kinds with Formatters
-
-### ✅ Implemented Formatters
-
-#### `chat`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1900)
-- **Formatting**:
- - Shows text content directly
- - Full-width separators (top/bottom borders) for visual distinction
- - Filled diamond (◆) prefix
- - Theme-aware colors
-
-#### `chat/acknowledge`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2544)
-- **Formatting**:
- - Checkmark (✓) prefix
- - Shows status field from payload (e.g., "processing", "received", "seen")
- - Example: `✓ processing` or `✓ received`
- - Note: Per spec, payload only contains `status` field; correlation_id (in envelope) references acknowledged message
-
-#### `mcp/request` and `mcp/proposal`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1920)
-- **Formatting**:
- - Shows method and tool name
- - Arguments preview
- - Special handling for `tools/call` with tool-specific formatters
-
-#### `mcp/response`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1940)
-- **Formatting**:
- - Handles result content arrays (shows first text item)
- - Object results with key summary
- - String results with path tail-end display
- - Error messages
-
-#### `reasoning/thought`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1900)
-- **Formatting**:
- - Special cyan color for reasoning text
- - Magenta color for action field
- - Indented display with wrap
-
-#### `reasoning/start` & `reasoning/conclusion`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1960)
-- **Formatting**:
- - Prefixes: ◇ for start, ◆ for conclusion
- - Message preview (truncated to 120 chars)
-
-#### `stream/request`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2642)
-- **Formatting**:
- - Shows direction (upload/download)
- - Shows description if present
- - Shows expected size in MB if present
- - Example: `upload stream "reasoning:reason-123"` or `download stream (5.2MB)`
-
-#### `stream/open`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2649)
-- **Formatting**:
- - Shows stream ID and encoding
- - Example: `opened stream-4 [text]` or `opened stream-42 [binary]`
-
-#### `stream/close`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2655)
-- **Formatting**:
- - Shows stream ID (if present) and reason
- - Example: `stream-4 complete` or `cancelled`
-
-#### `system/help`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1970)
-- **Formatting**:
- - Multi-line display with proper indentation
- - Section titles highlighted
- - Line-by-line rendering
-
-#### `system/info`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2565)
-- **Formatting**:
- - Shows text content directly
- - Example: `Stream closed (complete)`
-
-#### `system/welcome`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~2569)
-- **Formatting**:
- - Shows your participant ID, capability count, and other participants
- - Example: `connected as participant-123 (2 capabilities) • 2 other participants: mew, mcp-fs-bridge`
- - Concise format to avoid bloat (per spec recommendation)
-
-### 🛠️ Tool-Specific Formatters
-
-The advanced UI includes a pluggable tool formatter system for `mcp/proposal` messages:
-
-#### `write_file`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1300)
-- **Formatting**:
- - Shows file path
- - Line count
- - Content preview with first/last 5 lines
- - Diff-style display with + prefix
-
-#### `edit_file`
-- **Location**: `src/cli/utils/advanced-interactive-ui.ts` (line ~1350)
-- **Formatting**:
- - Shows file path
- - Side-by-side diff with old/new lines
- - Red for removed lines, green for added lines
- - Handles multiple edits
-
-## Message Kinds Without Formatters
-
-### ❌ Basic JSON Display
-
-These message types fall back to generic JSON preview in `getPayloadPreview()`:
-
-#### `system/*` (except `help`, `info`, `welcome`)
-- `system/heartbeat`
-- `system/error`
-- `system/presence`
-- **Current behavior**: Generic object preview showing first 2-3 keys
-
-#### `participant/*`
-- `participant/status`
-- `participant/pause`
-- `participant/resume`
-- `participant/forget`
-- `participant/clear`
-- `participant/restart`
-- `participant/shutdown`
-- `participant/request-status`
-- `participant/compact`
-- `participant/compact-done`
-- **Current behavior**: Generic object preview
-
-#### `stream/data`
-- **Current behavior**: Filtered from display (binary/chunked data, not shown in envelope view)
-
-#### `capability/*`
-- `capability/grant`
-- `capability/grant-ack`
-- **Current behavior**: Generic object preview
-
-#### `chat/cancel`
-- **Current behavior**: Generic object preview
-
-#### Other Protocol Messages
-- Any custom or future message kinds
-- **Current behavior**: Generic object preview
-
-## Formatter Architecture
-
-### Advanced UI (Only)
-- **File**: `src/cli/utils/advanced-interactive-ui.ts`
-- **Function**: `getPayloadPreview()` (line ~2540)
-- **Component**: `ReasoningDisplay` (line ~1880)
-- **Approach**: React component with pluggable tool formatters
-- **Tool Formatters**: Object registry at line ~1300
-- **Note**: The simple readline UI has been removed as of v0.5
-
-## Recommendations
-
-### High Priority Formatters
-1. **`system/error`** - Errors should have distinct formatting (red, prominent)
-2. **`participant/status`** - Status telemetry could be tabular
-3. **`capability/grant`** - Security-critical, needs clear display
-
-### Medium Priority Formatters
-1. **`participant/pause`** - Show timeout and reason clearly
-2. **`chat/cancel`** - Show cancellation status visually
-3. **`system/presence`** - Show join/leave events clearly
-
-### Tool Formatters to Add
-1. **`read_file`** - Show file path and size
-2. **`create_directory`** - Show directory path
-3. **`list_directory`** - Show directory contents preview
-4. **`search_files`** - Show search pattern and results count
-
-## Implementation Notes
-
-- Tool formatters receive `(args, { headerLabel, proposalColor, detailColor, theme })`
-- Formatters should return React elements for advanced UI
-- Consider both verbose and non-verbose modes
-- Maintain consistency with existing color schemes
-- Handle edge cases (missing data, large payloads)
\ No newline at end of file
diff --git a/spec/scratch/SPEC-default-chat-targeting.md b/spec/scratch/SPEC-default-chat-targeting.md
deleted file mode 100644
index 85a9b51a..00000000
--- a/spec/scratch/SPEC-default-chat-targeting.md
+++ /dev/null
@@ -1,158 +0,0 @@
-# Spec: Default Chat Targeting in MEW CLI
-
-Status: Draft
-Last Updated: 2025-01-17
-Authors: MEW Protocol Team
-Related Docs:
-- MEW Protocol v0.4 (spec/protocol/v0.4/SPEC.md)
-- MEW CLI Specification (spec/cli/SPEC.md)
-
-## 1. Summary
-
-Provide a configurable way to automatically set the `to` field for chat envelopes originating from the CLI participant (typically the human) so plain-text input is addressed to a specific participant (e.g., `mew`) without requiring an explicit classifier or manual targeting each time. The feature is opt-in via space.yaml and can be toggled at runtime.
-
-## 2. Motivation
-
-- Reduce latency and cognitive load in the common case where the human primarily collaborates with a single agent (e.g., coder template: human → mew).
-- Avoid unnecessary broadcast chatter and downstream filtering when a single recipient is intended.
-- Preserve protocol correctness: MEW v0.4 allows broadcast by omitting `to`; this feature simply pre-fills `to` where appropriate.
-
-## 3. Non-Goals
-
-- Not a routing policy inside the gateway; this is a CLI-side convenience for composing envelopes.
-- Not a hard authorization or delivery guarantee; standard capability enforcement and routing still apply.
-- Not a replacement for multi-target addressing; users can still explicitly set `to` when needed.
-
-## 4. Configuration Schema (space.yaml)
-
-Introduce an optional per-participant configuration to specify default targets by message kind:
-
-```
-participants:
- :
- # ...existing fields...
- default_to:
- chat: ["mew"]
-```
-
-Notes:
-- Keys under `default_to` are MEW kinds. This spec only defines behavior for `chat` initially; future kinds MAY be added.
-- Values are arrays of logical participant names as declared in space configuration (e.g., `mew`, `mcp-fs-bridge`). Gateway performs logical→runtime ID resolution per Protocol §3.6.4.
-- Omission means "no default" (maintain broadcast unless the user explicitly targets).
-
-Optional global defaults (lowest precedence) may be provided under `defaults`:
-
-```
-defaults:
- routing:
- default_to:
- chat: ["mew"]
-```
-
-Precedence is described in §7.
-
-## 5. CLI Behavior Changes
-
-### 5.1 Input Wrapping
-
-Per CLI spec, the interactive client wraps plain text as a `chat` envelope. With this feature enabled:
-- When the local participant sends plain text (no explicit JSON), the CLI sets `to` to the configured `default_to.chat` list if present.
-- When sending valid JSON that is a `chat` envelope and omits `to`, the CLI MAY apply the same default. If the JSON already contains a `to`, it is respected.
-
-### 5.2 FIFO Mode
-
-In FIFO mode, the same rules apply when the CLI composes envelopes from simplified inputs. For fully formed envelopes arriving on FIFO, the CLI does not mutate `to` unless it is missing and the envelope `kind` is `chat` and the sender is the CLI participant; then the default MAY be applied.
-
-### 5.3 Advanced UI and Debug UI
-
-Both interactive modes follow identical targeting rules. The UI should surface the active target (see §6) so operators understand where messages go.
-
-## 6. Runtime Controls (Slash Commands)
-
-Add session-scoped controls:
-
-- `/target `: Set an in-session override of default chat targets (one or more). Example: `/target mew`.
-- `/target none`: Clear override and revert to config-based behavior.
-- `/target show`: Display current effective target and source (override vs config vs none).
-
-Behavior:
-- Overrides apply only to the current CLI session and only for `chat` envelopes.
-- Overrides take precedence over space.yaml defaults (see §7).
-- Overrides do not modify space.yaml.
-
-## 7. Precedence Rules
-
-When composing a `chat` envelope from the CLI participant, the CLI determines `to` using the following order:
-
-1. Explicit `to` present in user-provided JSON envelope → use as-is.
-2. Session override set via `/target` → use override.
-3. Participant-level default in `participants..default_to.chat` → use list.
-4. Global default in `defaults.routing.default_to.chat` → use list.
-5. Otherwise → omit `to` (broadcast).
-
-If the resolved list is empty, the CLI omits `to`.
-
-## 8. Failure Modes and Fallbacks
-
-- Target name not present in current participant list: send anyway; gateway performs name→runtime resolution when possible. If no runtime participant matches, delivery will naturally produce no recipients. UI SHOULD warn once per target per session.
-- Multiple targets: the CLI sets `to` to all listed targets; normal fan-out applies.
-- Capability violations: unchanged; gateway will enforce as usual.
-
-## 9. Backward Compatibility
-
-- Default behavior is unchanged when no config or override is present.
-- Existing spaces function without modification.
-- The new keys are ignored by prior CLI versions.
-
-## 10. Template Updates (Recommended)
-
-For the coder-agent template, set a sensible default so plain text routes to `mew`:
-
-```
-participants:
- human:
- default_to:
- chat: ["mew"]
-```
-
-This mirrors the common workflow in that template while remaining opt-in for other spaces.
-
-## 11. Minimal Implementation Plan
-
-- Schema:
- - Extend space.yaml loader to read `participants.*.default_to.chat` and `defaults.routing.default_to.chat`.
-- CLI Input Pipeline:
- - After building the base envelope for plain text or simplified JSON, apply precedence rules (§7) to set `to`.
- - Respect explicit `to` in user-provided JSON.
-- Slash Commands:
- - Implement `/target` with subcommands: value list, `none`, `show`.
- - Persist only in memory for the session.
- - Reflect current effective target in the status/board area of the advanced UI.
-- Telemetry/Logs:
- - Optionally annotate local logs with the decision path (override vs config vs none) to aid debugging.
-
-## 12. Test Plan
-
-- Unit tests for precedence resolution (explicit > override > participant default > global default > none).
-- Interactive mode:
- - With coder template defaults, sending plain text creates `chat` with `to: ["mew"]`.
- - `/target none` clears override and reverts to config-based behavior.
- - `/target mew mcp-fs-bridge` targets both.
- - JSON envelope with explicit `to` is not mutated.
-- FIFO mode:
- - Simplified input acquires default `to`.
- - Fully formed envelope with missing `to` remains broadcast unless local composition path applies and policy allows applying default.
-- Negative:
- - Unknown target names warn once; messages still sent (no crash).
-
-## 13. Security Considerations
-
-- This is a client-side composition aid; capability enforcement remains server-side (Protocol §4).
-- Explicit `to` in user-provided JSON is always respected to avoid unexpected redirection.
-- UI makes the effective target visible to reduce operator error.
-
-## 14. Future Extensions
-
-- Kind patterning (e.g., defaults for `mcp/request` by `payload.method`).
-- Context-aware targeting (e.g., stickiness per conversation thread).
-- Per-space operator commands to update defaults at runtime and persist changes to space.yaml (with confirmation flow).
diff --git a/spec/sdk/SPEC.md b/spec/sdk/SPEC.md
index 9deb5414..09506fd7 100644
--- a/spec/sdk/SPEC.md
+++ b/spec/sdk/SPEC.md
@@ -1298,9 +1298,6 @@ await agent.start();
## Future Considerations
-### Composition vs Inheritance
-The current implementation uses inheritance, but will be refactored to use composition per ADR-cmp (see `decisions/accepted/001-cmp-composition-over-inheritance.md`). This refactoring is planned for the next major version (2.0) to provide better separation of concerns, testability, and flexibility.
-
### Plugin System
Allow extending agents with plugins:
- Custom thinking strategies
diff --git a/spec/sdk/accepted/001-cmp-composition-over-inheritance.md b/spec/sdk/accepted/001-cmp-composition-over-inheritance.md
deleted file mode 100644
index f65ee224..00000000
--- a/spec/sdk/accepted/001-cmp-composition-over-inheritance.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# ADR-cmp: Composition Over Inheritance
-
-**Status:** Accepted
-**Date:** 2025-09-12
-**Incorporation:** Complete
-
-## Context
-
-The current SDK implementation uses inheritance for the three-layer architecture:
-- `MEWParticipant extends MEWClient`
-- `MEWAgent extends MEWParticipant`
-
-This creates tight coupling between layers and violates the principle of composition over inheritance. It also makes it difficult to:
-- Test layers independently
-- Swap implementations
-- Extend functionality without modifying base classes
-- Maintain clear separation of concerns
-
-The inheritance chain also leads to confusion about which layer is responsible for what functionality, as child classes have direct access to parent implementation details.
-
-## Options Considered
-
-### Option 1: Keep Inheritance (Current)
-Continue with the current inheritance model.
-
-**Pros:**
-- No breaking changes needed
-- Simple to understand inheritance chain
-- Direct access to parent methods
-- Less code to write initially
-
-**Cons:**
-- Tight coupling between layers
-- Difficult to test in isolation
-- Violates SOLID principles
-- Hard to extend without modification
-- Unclear separation of concerns
-
-### Option 2: Use Composition
-Refactor to use composition, where each layer contains an instance of the lower layer.
-
-**Pros:**
-- Clear separation of concerns
-- Easy to test with mocks
-- Follows SOLID principles
-- Flexible and extensible
-- Can swap implementations
-- Better encapsulation
-
-**Cons:**
-- Breaking change for existing code
-- Need to expose necessary methods
-- Slightly more verbose
-- Requires delegation methods
-
-### Option 3: Hybrid Approach
-Use composition internally but maintain inheritance for backwards compatibility.
-
-**Pros:**
-- Backwards compatible
-- Gradual migration path
-- Benefits of composition internally
-
-**Cons:**
-- More complex implementation
-- Maintains confusing public API
-- Technical debt
-
-## Decision
-
-**Option 2: Use Composition** should be adopted for the next major version.
-
-The architecture should be refactored to:
-
-```typescript
-class MEWParticipant {
- private client: MEWClient;
-
- constructor(options: ParticipantOptions) {
- this.client = new MEWClient(options);
- this.setupEventHandlers();
- }
-
- // Delegate connection methods
- async connect(): Promise {
- return this.client.connect();
- }
-
- // Use client for sending
- protected send(envelope: Envelope): void {
- this.client.send(envelope);
- }
-}
-
-class MEWAgent {
- private participant: MEWParticipant;
-
- constructor(config: AgentConfig) {
- this.participant = new MEWParticipant(config);
- this.setupAutonomousBehavior();
- }
-
- // Delegate to participant
- async start(): Promise {
- await this.participant.connect();
- // Start agent-specific behavior
- }
-}
-```
-
-### Implementation Details
-
-1. **MEWClient** remains standalone
- - Pure transport layer
- - No knowledge of higher layers
- - Event-based communication
-
-2. **MEWParticipant** contains MEWClient
- - Creates and manages client instance
- - Subscribes to client events
- - Exposes protocol-level API
- - Hides transport details
-
-3. **MEWAgent** contains MEWParticipant
- - Creates and manages participant instance
- - Subscribes to participant events
- - Adds autonomous behavior
- - Hides protocol details
-
-4. **Migration Strategy**
- - Create new major version (2.0)
- - Provide migration guide
- - Maintain 1.x branch for fixes
- - Deprecation warnings in 1.x
-
-## Consequences
-
-### Positive
-- **Better Testing**: Each layer can be tested with mocked dependencies
-- **Clear Contracts**: Explicit interfaces between layers
-- **Flexibility**: Can swap implementations (e.g., different transports)
-- **Maintainability**: Changes isolated to specific layers
-- **Extensibility**: Easy to add new functionality without modifying core
-- **Better Documentation**: Clear separation makes documentation clearer
-
-### Negative
-- **Breaking Change**: Existing code will need updates
-- **More Code**: Need delegation methods and interfaces
-- **Learning Curve**: Developers need to understand new structure
-- **Migration Effort**: Existing applications need refactoring
\ No newline at end of file
diff --git a/spec/sdk/proposals/README.md b/spec/sdk/proposals/README.md
new file mode 100644
index 00000000..1c30a947
--- /dev/null
+++ b/spec/sdk/proposals/README.md
@@ -0,0 +1,3 @@
+# SDK Proposals
+
+This directory contains all proposals for changes to the MEW SDK. Proposal status is tracked in the root `CHANGELOG.md`.
diff --git a/spec/sdk/accepted/002-mpt-multi-participant-tool-selection.md b/spec/sdk/proposals/mpt-multi-participant-tool-selection.md
similarity index 100%
rename from spec/sdk/accepted/002-mpt-multi-participant-tool-selection.md
rename to spec/sdk/proposals/mpt-multi-participant-tool-selection.md
diff --git a/spec/sdk/proposed/004-mqr-message-queueing-during-reasoning.md b/spec/sdk/proposals/mqr-message-queueing-during-reasoning.md
similarity index 100%
rename from spec/sdk/proposed/004-mqr-message-queueing-during-reasoning.md
rename to spec/sdk/proposals/mqr-message-queueing-during-reasoning.md
diff --git a/spec/sdk/accepted/001-tdc-tool-discovery-in-participant.md b/spec/sdk/proposals/tdc-tool-discovery-in-participant.md
similarity index 100%
rename from spec/sdk/accepted/001-tdc-tool-discovery-in-participant.md
rename to spec/sdk/proposals/tdc-tool-discovery-in-participant.md
diff --git a/spec/sdk/accepted/003-tns-tool-namespace-management.md b/spec/sdk/proposals/tns-tool-namespace-management.md
similarity index 100%
rename from spec/sdk/accepted/003-tns-tool-namespace-management.md
rename to spec/sdk/proposals/tns-tool-namespace-management.md