@xmachines/docs 1.0.0-beta.9 → 1.1.0

package/rfc/cli.md

@@ -0,0 +1,118 @@
+# RFC: CLI
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Command-line interface architecture, configuration, and implementation resolution  
+**Non-goals:** Execution semantics, protocol definitions, stream behavior
+
+---
+
+## 1. Purpose
+
+This RFC defines the XMachines CLI architecture.
+
+The CLI provides:
+
+- a human-facing interface to XMachines capabilities
+- configuration and defaults for implementation selection
+- an orchestration layer over RFC-defined capabilities
+
+The CLI does not define behavior. It selects and wires implementations.
+
+---
+
+## 2. Design Principles
+
+1. CLI is optional
+2. CLI never defines semantics
+3. CLI resolves implementations explicitly
+4. Configuration is explicit and persistent
+5. Alias packages expose commands, implementation packages implement behavior
+
+---
+
+## 3. Package Structure
+
+- `@xmachines/cli`
+- built using oclif
+- contains command definitions and shared helpers only
+
+---
+
+## 4. Implementation Resolution
+
+Resolution order:
+
+1. explicit CLI flags
+2. persisted configuration
+3. alias-level defaults (if any)
+4. error
+
+Implementation identifiers are stored as fully qualified package names.
+If no scope is provided, default scope is `@xmachines/`.
+
+---
+
+## 5. Configuration Model
+
+- stored via oclif config
+- user-scoped
+- persistent across upgrades
+
+Defaults follow a first-writer-wins strategy.
+
+---
+
+## 6. Install & Uninstall Hooks
+
+Implementation packages MAY:
+
+- suggest themselves as defaults on install
+- respect `if-not-set` or `quiet` strategies
+- avoid auto-reassignment on uninstall
+
+Uninstall MAY support an explicit purge option to remove config entries.
+
+---
+
+## 7. Feature Enablement
+
+Some capabilities expose features (e.g. REST, Git, MCP).
+
+Rules:
+
+- features map to installed packages
+- enablement is explicit
+- disablement requires explicit flags
+
+---
+
+## 8. Scope Boundaries
+
+The CLI:
+
+- wires components
+- launches servers
+- manages configuration
+
+The CLI does NOT:
+
+- define protocol semantics
+- parse stream payloads
+- implement execution logic
+
+---
+
+## 9. Invariants
+
+1. No implicit defaults
+2. Explicit implementation selection
+3. CLI never defines semantics
+
+---
+
+## 10. Lock statement
+
+> The CLI is an orchestration and configuration layer only.  
+> All semantics live in other RFCs.  
+> This is CLI.

package/rfc/git.md

@@ -0,0 +1,61 @@
+# RFC: Git
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Durable streams and distribution  
+**Non-goals:** Runtime execution
+
+---
+
+## 1. Purpose
+
+Git is used as:
+
+- durable stream
+- replication mechanism
+- backup format
+
+Git is optional.
+
+---
+
+## 2. Model
+
+- machines = orphan branches
+- runs = forks
+- events = commits
+- snapshots = commits
+
+History is append-only.
+
+---
+
+## 3. Identity
+
+- commit hashes are canonical IDs
+- same algorithm used with or without Git
+
+---
+
+## 4. SmartHTTP
+
+```
+/<repo>.git/**
+```
+
+Standard Git semantics apply.
+
+---
+
+## 5. Invariants
+
+1. No history rewriting
+2. Git is optional
+3. Append-only semantics
+
+---
+
+## 6. Lock statement
+
+> Git is a durable, append-only stream for XMachines.  
+> This is Git.

package/rfc/mcp.md

@@ -0,0 +1,43 @@
+# RFC: MCP
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Model Context Protocol integration  
+**Non-goals:** Transport inference, execution semantics
+
+---
+
+## 1. Purpose
+
+MCP exposes machines as **tools** to external agents.
+
+---
+
+## 2. Implementations
+
+Examples:
+
+- `@xmachines/mcp-http`
+- `@xmachines/mcp-tty`
+
+---
+
+## 3. Server Semantics
+
+- MCP server runs machines
+- transport is irrelevant server-side
+- tools map to machine events
+
+---
+
+## 4. Invariants
+
+1. MCP implementation selection is explicit
+2. MCP is bidirectional
+
+---
+
+## 5. Lock statement
+
+> MCP integrates XMachines with external agents using explicit transports.  
+> This is MCP.

package/rfc/node.md

@@ -0,0 +1,36 @@
+# RFC: Node
+
+**Status:** Draft  
+**Version:** 1  
+**Scope:** Node.js-specific interoperability  
+**Non-goals:** Browser APIs, execution semantics
+
+---
+
+## 1. Purpose
+
+Defines Node-only adapters for non-isomorphic APIs.
+
+---
+
+## 2. Packages
+
+- `node-stream`
+- `node-process`
+
+There is no generic `@xmachines/node`.
+
+---
+
+## 3. Invariants
+
+1. Web Streams are canonical
+2. Node adapters are optional
+3. No protocol semantics
+
+---
+
+## 4. Lock statement
+
+> Node interop is provided by focused adapters only.  
+> This is Node.