docs: add ecosystem role and contract clarity to bundle README

Author: sven1103

README.md

@@ -6,6 +6,77 @@ A collection of OpenCode AI agent configuration presets with planning-first mult
 
 This bundle provides drop-in OpenCode agent configurations that route work through schema-validated JSON handoff artifacts before planning, execution, and review. The goal is fewer ambiguous changes, less rework, and tighter safety boundaries with a small, explicit contract between agents.
 
+## Versioning & Stability
+
+This bundle follows its own versioning scheme (`bundle_version` in the manifest), independent of the opencode-helper CLI version. This is intentional:
+
+- **Ecosystem Stability**: Configuration bundles are foundational contracts that other tools and workflows depend on. Changes to the bundle should be rare and deliberate.
+- **Semantic Versioning**: Follows semver (e.g., `v1.0.0`, `v1.1.0`, `v2.0.0`) to communicate change impact.
+- **Backward Compatibility**: Minor and patch updates within a major version must not break existing configurations.
+- **Schema Stability**: The bundle manifest schema (see below) is contractually stable. Once published, a manifest version `1` will never change breakingly.
+
+## Bundle Contract (V2)
+
+The V2 bundle manifest is the contract between the bundle and the opencode-helper CLI. This contract is:
+
+- **Published**: Included in the CLI's schema validation
+- **Versioned**: The `manifest_version` field ensures forward compatibility
+- **Minimal**: Only contains what's needed for the CLI to discover and apply presets
+
+### Manifest Schema
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["manifest_version", "bundle_name", "bundle_version", "presets"],
+  "properties": {
+    "manifest_version": { "type": "integer", "const": 1 },
+    "bundle_name": { "type": "string" },
+    "bundle_version": { "type": "string" },
+    "source_repo": { "type": "string" },
+    "source_commit": { "type": "string" },
+    "release_tag": { "type": "string" },
+    "presets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "description", "entrypoint"],
+        "properties": {
+          "name": { "type": "string" },
+          "description": { "type": "string" },
+          "entrypoint": { "type": "string" },
+          "prompt_files": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}
+```
+
+### Required Files
+
+A valid V2 bundle must include:
+
+```
+<bundle-root>/
+  opencode-bundle.manifest.json  <- required for V2
+  <preset-entrypoint>.json       <- each preset file
+  .opencode/schemas/
+    handoff.schema.json          <- canonical handoff contract
+    result.schema.json           <- canonical result contract
+```
+
+## Ecosystem Role
+
+This bundle serves as a foundational component of the OpenCode ecosystem:
+
+1. **Contract Provider**: Exports the canonical V2 bundle manifest schema used by the CLI
+2. **Schema Publisher**: Includes `handoff.schema.json` and `result.schema.json` that define inter-agent contracts
+3. **Preset Repository**: Maintains multiple model-specific configurations in a single, versioned bundle
+
+> **Important**: Because other tools depend on this bundle's contracts, changes should follow semver strictly. The manifest schema (`manifest_version: 1`) is locked and will never break backward compatibility.
+
 ## Bundle Contents
 
 | Preset | Description |
@@ -16,19 +87,6 @@ This bundle provides drop-in OpenCode agent configurations that route work throu
 | `big-pickle` | Big Pickle model-based configuration |
 | `minimax` | MiniMax-based configuration |
 
-## Bundle Manifest
-
-This bundle follows the V2 config bundle manifest specification:
-
-```json
-{
-  "manifest_version": 1,
-  "bundle_name": "qbic-opencode-config-bundle",
-  "bundle_version": "v1.0.0",
-  "presets": [...]
-}
-```
-
 ## Schema Files
 
 The bundle includes the canonical artifact schemas used by all configurations: