@jstn-sdk/rcs 0.1.6 → 0.1.8

package/docs/readme/README.uk.md

@@ -1,41 +1,68 @@
 # Roblox Creator Skills (RCS)
 
-This localized README is intentionally condensed for the strict v0.1.0 ship pass.
-Use the canonical checked-in docs below for the current product surface.
+Цей локалізований README навмисно зроблено стислим.
+Для актуальної поверхні продукту використовуйте канонічні документи за посиланнями нижче.
 
-- Package: `@jstn-sdk/rcs`
-- Repository: `https://github.com/JustineDevs/roblox-ai-os`
-- Getting started: [../getting-started.html](../getting-started.html)
-- Skills reference: [../skills.html](../skills.html)
-- Integrations: [../integrations.html](../integrations.html)
-- Canonical README: [../../README.md](../../README.md)
+- Пакет: `@jstn-sdk/rcs`
+- Репозиторій: `https://github.com/JustineDevs/roblox-ai-os`
+- Початок роботи: [../getting-started.html](../getting-started.html)
+- Довідник skills: [../skills.html](../skills.html)
+- Вікі для контриб'юторів: [../wiki/Home.md](../wiki/Home.md)
+- Дорожня карта: [../wiki/Roadmap.md](../wiki/Roadmap.md)
+- Архітектура: [../reference/multi-agent-compatibility-architecture.md](../reference/multi-agent-compatibility-architecture.md)
+- Посібник з внеску: [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
+- Інтеграції: [../integrations.html](../integrations.html)
+- Канонічний README: [../../README.md](../../README.md)
 
-## Canonical Creator Workflow
+## Канонічний workflow для creator
 
 `$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
 
-For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
-- gather references
-- build understanding
-- standardize terms
-- design modular file tree architecture
-- only then implement
+Для роботи з реалізацією в Roblox обов’язковий pre-action gate застосовується до будь-якої генерації коду:
+- зібрати референси
+- побудувати розуміння
+- стандартизувати терміни
+- спроєктувати модульну архітектуру дерева файлів
+- і лише потім реалізовувати
 
-See:
+Див.:
 - [../../README.md](../../README.md)
 - [../skills.html](../skills.html)
 - [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)
 
-## Ownership
+## Активація MCP
 
-RCS is owned and maintained by [JustineDevs](https://github.com/JustineDevs) and [@JustineDevs](https://github.com/JustineDevs) for Roblox creator workflows.
+Після `rcs setup` типова сумісна з Codex конфігурація має містити два шари MCP:
 
-## Acknowledgements
+1. **First-party MCP сервери RCS** через `rcs mcp-serve`
+2. **MCP сервери довідкових Roblox-джерел** через віддалений transport GitMCP
+
+Рекомендована модель:
+- залишайте **`rcs mcp-serve`** активним для локальної runtime/state/control-plane роботи
+- залишайте **довідкові Roblox сервери через GitMCP** увімкненими за замовчуванням, щоб зменшувати галюцинації й покращувати прив’язку до платформи
+- вмикайте **`robloxstudio-mcp`** вручну лише тоді, коли потрібне живе з’єднання між Codex CLI та Roblox Studio
+
+Важливе уточнення:
+- `rcs mcp-serve` обслуговує лише **локальні MCP сервери, що належать RCS**
+- він **не** обслуговує `robloxstudio-mcp`
+
+## Внесок
+
+- Шукайте issues з мітками `good first issue` або `help wanted`.
+- Внески в документацію, локалізацію, QA та чистоту релізів вітаються.
+- Використовуйте вікі для контриб'юторів і дорожню карту, щоб тримати scope малим і зрозумілим.
+- Вікі для контриб'юторів **не** є тим самим, що локальна runtime-вікі в `.rcs/wiki/`.
+
+## Власність
+
+RCS належить [JustineDevs](https://github.com/JustineDevs) та [@JustineDevs](https://github.com/JustineDevs) і підтримується ними для creator-workflow у Roblox.
+
+## Подяки
 
 - [OpenAI Codex CLI](https://github.com/openai/codex)
 - [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
 - [robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp)
 
-## License
+## Ліцензія
 
 [MIT](https://opensource.org/licenses/MIT)

package/docs/readme/README.vi.md

@@ -1,41 +1,68 @@
 # Roblox Creator Skills (RCS)
 
-This localized README is intentionally condensed for the strict v0.1.0 ship pass.
-Use the canonical checked-in docs below for the current product surface.
+README bản địa hóa này được giữ ngắn gọn có chủ đích.
+Hãy dùng các tài liệu chuẩn liên kết bên dưới cho bề mặt sản phẩm hiện tại.
 
-- Package: `@jstn-sdk/rcs`
-- Repository: `https://github.com/JustineDevs/roblox-ai-os`
-- Getting started: [../getting-started.html](../getting-started.html)
-- Skills reference: [../skills.html](../skills.html)
-- Integrations: [../integrations.html](../integrations.html)
-- Canonical README: [../../README.md](../../README.md)
+- Gói: `@jstn-sdk/rcs`
+- Kho mã: `https://github.com/JustineDevs/roblox-ai-os`
+- Bắt đầu: [../getting-started.html](../getting-started.html)
+- Tham chiếu skills: [../skills.html](../skills.html)
+- Wiki cho người đóng góp: [../wiki/Home.md](../wiki/Home.md)
+- Lộ trình: [../wiki/Roadmap.md](../wiki/Roadmap.md)
+- Kiến trúc: [../reference/multi-agent-compatibility-architecture.md](../reference/multi-agent-compatibility-architecture.md)
+- Hướng dẫn đóng góp: [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
+- Tích hợp: [../integrations.html](../integrations.html)
+- README chuẩn: [../../README.md](../../README.md)
 
-## Canonical Creator Workflow
+## Quy trình creator chuẩn
 
 `$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
 
-For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
-- gather references
-- build understanding
-- standardize terms
-- design modular file tree architecture
-- only then implement
+Đối với công việc triển khai Roblox, pre-action gate bắt buộc được áp dụng trước mọi bước sinh mã:
+- thu thập tài liệu tham chiếu
+- xây dựng hiểu biết
+- chuẩn hóa thuật ngữ
+- thiết kế kiến trúc cây tệp dạng mô-đun
+- chỉ sau đó mới triển khai
 
-See:
+Xem:
 - [../../README.md](../../README.md)
 - [../skills.html](../skills.html)
 - [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)
 
-## Ownership
+## Kích hoạt MCP
 
-RCS is owned and maintained by [JustineDevs](https://github.com/JustineDevs) and [@JustineDevs](https://github.com/JustineDevs) for Roblox creator workflows.
+Sau `rcs setup`, cấu hình mặc định tương thích với Codex nên bao gồm hai lớp MCP:
 
-## Acknowledgements
+1. **Máy chủ MCP first-party của RCS** qua `rcs mcp-serve`
+2. **Máy chủ MCP tham chiếu Roblox mặc định** qua cơ chế vận chuyển từ xa GitMCP
+
+Mô hình khuyến nghị:
+- giữ **`rcs mcp-serve`** hoạt động cho công việc runtime/state/control-plane cục bộ
+- giữ **các máy chủ tham chiếu Roblox qua GitMCP** bật theo mặc định để giảm hallucination và tăng độ bám sát nền tảng
+- chỉ bật **`robloxstudio-mcp`** thủ công khi bạn muốn có kết nối thời gian thực giữa Codex CLI và Roblox Studio
+
+Làm rõ quan trọng:
+- `rcs mcp-serve` chỉ phục vụ **các máy chủ MCP cục bộ thuộc sở hữu của RCS**
+- nó **không** phục vụ `robloxstudio-mcp`
+
+## Đóng góp
+
+- Hãy tìm các issue có nhãn `good first issue` hoặc `help wanted`.
+- Các đóng góp về tài liệu, bản địa hóa, QA và vệ sinh release đều được chào đón.
+- Hãy dùng wiki dành cho người đóng góp và lộ trình để giữ phạm vi nhỏ và rõ ràng.
+- Wiki dành cho người đóng góp **không** giống với wiki runtime cục bộ trong `.rcs/wiki/`.
+
+## Quyền sở hữu
+
+RCS thuộc sở hữu và được duy trì bởi [JustineDevs](https://github.com/JustineDevs) và [@JustineDevs](https://github.com/JustineDevs) cho các workflow creator của Roblox.
+
+## Lời cảm ơn
 
 - [OpenAI Codex CLI](https://github.com/openai/codex)
 - [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
 - [robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp)
 
-## License
+## Giấy phép
 
 [MIT](https://opensource.org/licenses/MIT)

package/docs/readme/README.zh-TW.md

@@ -1,41 +1,68 @@
 # Roblox Creator Skills (RCS)
 
-This localized README is intentionally condensed for the strict v0.1.0 ship pass.
-Use the canonical checked-in docs below for the current product surface.
+這份在地化 README 刻意保持精簡。
+目前產品表面請以下方連結的正規文件為準。
 
-- Package: `@jstn-sdk/rcs`
-- Repository: `https://github.com/JustineDevs/roblox-ai-os`
-- Getting started: [../getting-started.html](../getting-started.html)
-- Skills reference: [../skills.html](../skills.html)
-- Integrations: [../integrations.html](../integrations.html)
-- Canonical README: [../../README.md](../../README.md)
+- 套件：`@jstn-sdk/rcs`
+- 儲存庫：`https://github.com/JustineDevs/roblox-ai-os`
+- 快速開始： [../getting-started.html](../getting-started.html)
+- Skills 參考： [../skills.html](../skills.html)
+- 貢獻者 Wiki： [../wiki/Home.md](../wiki/Home.md)
+- 路線圖： [../wiki/Roadmap.md](../wiki/Roadmap.md)
+- 架構： [../reference/multi-agent-compatibility-architecture.md](../reference/multi-agent-compatibility-architecture.md)
+- 貢獻指南： [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
+- 整合： [../integrations.html](../integrations.html)
+- 正規 README： [../../README.md](../../README.md)
 
-## Canonical Creator Workflow
+## 正規創作者工作流程
 
 `$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
 
-For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
-- gather references
-- build understanding
-- standardize terms
-- design modular file tree architecture
-- only then implement
+對於 Roblox 實作工作，在任何程式碼產生之前都必須先通過 pre-action gate：
+- 蒐集參考資料
+- 建立理解
+- 統一術語
+- 設計模組化檔案樹架構
+- 然後才開始實作
 
-See:
+請參考：
 - [../../README.md](../../README.md)
 - [../skills.html](../skills.html)
 - [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)
 
-## Ownership
+## MCP 啟用
 
-RCS is owned and maintained by [JustineDevs](https://github.com/JustineDevs) and [@JustineDevs](https://github.com/JustineDevs) for Roblox creator workflows.
+執行 `rcs setup` 之後，預設的 Codex 相容設定應包含兩層 MCP：
 
-## Acknowledgements
+1. 透過 `rcs mcp-serve` 提供的 **RCS 第一方 MCP 伺服器**
+2. 透過 GitMCP 遠端傳輸提供的 **預設 Roblox 參考 MCP 伺服器**
+
+建議模式：
+- 保持 **`rcs mcp-serve`** 啟用，用於本機 runtime / state / control-plane 工作
+- 預設保持 **GitMCP Roblox 參考伺服器** 啟用，以減少幻覺並提升平台脈絡準確度
+- 只有在需要 Codex CLI 與 Roblox Studio 之間的即時連線時，才手動啟用 **`robloxstudio-mcp`**
+
+重要說明：
+- `rcs mcp-serve` 只服務 **RCS 自有的本機 MCP 伺服器**
+- 它 **不會** 服務 `robloxstudio-mcp`
+
+## 貢獻
+
+- 優先尋找帶有 `good first issue` 或 `help wanted` 標籤的 issue。
+- 文件、本地化、QA 與發佈整理類貢獻同樣歡迎。
+- 使用貢獻者 Wiki 與路線圖來保持範圍小且清楚。
+- 貢獻者 Wiki **不是** `.rcs/wiki/` 下的本地執行階段 Wiki。
+
+## 擁有權
+
+RCS 由 [JustineDevs](https://github.com/JustineDevs) 與 [@JustineDevs](https://github.com/JustineDevs) 擁有並維護，用於 Roblox 創作者工作流程。
+
+## 致謝
 
 - [OpenAI Codex CLI](https://github.com/openai/codex)
 - [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
 - [robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp)
 
-## License
+## 授權
 
 [MIT](https://opensource.org/licenses/MIT)

package/docs/readme/README.zh.md

@@ -1,41 +1,68 @@
 # Roblox Creator Skills (RCS)
 
-This localized README is intentionally condensed for the strict v0.1.0 ship pass.
-Use the canonical checked-in docs below for the current product surface.
+这份本地化 README 有意保持简洁。
+当前产品表面请以下方链接的规范文档为准。
 
-- Package: `@jstn-sdk/rcs`
-- Repository: `https://github.com/JustineDevs/roblox-ai-os`
-- Getting started: [../getting-started.html](../getting-started.html)
-- Skills reference: [../skills.html](../skills.html)
-- Integrations: [../integrations.html](../integrations.html)
-- Canonical README: [../../README.md](../../README.md)
+- 包名：`@jstn-sdk/rcs`
+- 仓库：`https://github.com/JustineDevs/roblox-ai-os`
+- 入门： [../getting-started.html](../getting-started.html)
+- Skills 参考： [../skills.html](../skills.html)
+- 贡献者 Wiki： [../wiki/Home.md](../wiki/Home.md)
+- 路线图： [../wiki/Roadmap.md](../wiki/Roadmap.md)
+- 架构： [../reference/multi-agent-compatibility-architecture.md](../reference/multi-agent-compatibility-architecture.md)
+- 贡献指南： [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
+- 集成： [../integrations.html](../integrations.html)
+- 规范 README： [../../README.md](../../README.md)
 
-## Canonical Creator Workflow
+## 规范的创作者工作流
 
 `$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
 
-For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
-- gather references
-- build understanding
-- standardize terms
-- design modular file tree architecture
-- only then implement
+对于 Roblox 实现工作，任何代码生成之前都必须先通过 pre-action gate：
+- 收集参考资料
+- 建立理解
+- 统一术语
+- 设计模块化文件树架构
+- 然后才开始实现
 
-See:
+参见：
 - [../../README.md](../../README.md)
 - [../skills.html](../skills.html)
 - [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)
 
-## Ownership
+## MCP 激活
 
-RCS is owned and maintained by [JustineDevs](https://github.com/JustineDevs) and [@JustineDevs](https://github.com/JustineDevs) for Roblox creator workflows.
+执行 `rcs setup` 之后，默认的 Codex 兼容配置应包含两层 MCP：
 
-## Acknowledgements
+1. 通过 `rcs mcp-serve` 提供的 **RCS 第一方 MCP 服务器**
+2. 通过 GitMCP 远程传输提供的 **默认 Roblox 参考 MCP 服务器**
+
+推荐模型：
+- 保持 **`rcs mcp-serve`** 处于启用状态，用于本地 runtime / state / control-plane 工作
+- 默认启用 **GitMCP Roblox 参考服务器**，以减少幻觉并提高平台语境准确度
+- 只有在你需要 Codex CLI 与 Roblox Studio 的实时连接时，才手动启用 **`robloxstudio-mcp`**
+
+重要说明：
+- `rcs mcp-serve` 只服务于 **RCS 自有的本地 MCP 服务器**
+- 它 **不会** 服务 `robloxstudio-mcp`
+
+## 贡献
+
+- 优先查找带有 `good first issue` 或 `help wanted` 标签的 issue。
+- 文档、本地化、QA 和发布整理类贡献同样受欢迎。
+- 使用贡献者 Wiki 和路线图来保持范围小且清晰。
+- 贡献者 Wiki **不是** `.rcs/wiki/` 下的本地运行时 Wiki。
+
+## 所有权
+
+RCS 由 [JustineDevs](https://github.com/JustineDevs) 和 [@JustineDevs](https://github.com/JustineDevs) 拥有并维护，用于 Roblox 创作者工作流。
+
+## 致谢
 
 - [OpenAI Codex CLI](https://github.com/openai/codex)
 - [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
 - [robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp)
 
-## License
+## 许可证
 
 [MIT](https://opensource.org/licenses/MIT)

package/docs/reference/agentic-platform-compatibility.md

@@ -0,0 +1,147 @@
+# Agentic Platform Compatibility
+
+RCS should be portable across agentic AI platforms, but **portability does not mean pretending every platform has the same runtime model as Codex**.
+
+The correct goal is:
+
+- one canonical authoring surface
+- one compatibility contract
+- multiple platform-specific delivery lanes
+
+That contract is now materialized in:
+
+- [`src/platform-targets/manifest.json`](../../src/platform-targets/manifest.json)
+- [`src/platform-targets/schema.ts`](../../src/platform-targets/schema.ts)
+- [`src/platform-targets/reader.ts`](../../src/platform-targets/reader.ts)
+
+## What stays canonical
+
+These are the source-of-truth surfaces inside this repo:
+
+- `skills/` — canonical workflow skills
+- `prompts/` — canonical prompt guidance for setup-owned native-agent generation
+- `src/agents/definitions.ts` — canonical native-agent role registry
+- `src/catalog/manifest.json` — canonical installability and alias/merged policy
+- `templates/AGENTS.md` — canonical orchestration brain template
+- `src/config/rcs-first-party-mcp.ts` and related config generators — canonical first-party MCP metadata
+
+Everything else should be an **emitted delivery surface** or an **adapter surface**.
+
+## Delivery lanes
+
+### 1. Codex native setup lane
+
+This is the deepest-supported lane today.
+
+It includes:
+
+- generated native agents under `.codex/agents/`
+- installed prompts under `.codex/prompts/`
+- installed skills under the selected setup scope
+- setup-owned runtime hooks
+- `.rcs/` runtime state
+
+This lane is driven by `rcs setup`.
+
+### 2. Codex plugin + marketplace lane
+
+This is the installable bundle lane today.
+
+It includes:
+
+- plugin bundle under `plugins/roblox-ai-os-creator-skills/`
+- marketplace metadata in `.agents/plugins/marketplace.json`
+- plugin-scoped skill discovery
+- plugin-scoped MCP/app companion metadata
+
+Important boundary:
+
+- the plugin bundle is **not** the full runtime setup
+- setup-owned prompts, native-agent TOMLs, and runtime hooks remain outside the plugin manifest
+
+### 3. Adapter lane for external platforms
+
+This is how non-Codex platforms should be integrated.
+
+Examples:
+
+- OpenClaw
+- Hermes
+- future Claude-oriented or marketplace-oriented bridges
+
+The rule is:
+
+- do not fork canonical skill/prompt/runtime truth into platform-specific ad hoc copies
+- add a platform adapter or delivery contract that maps canonical RCS surfaces into the target platform’s format
+
+## What “compatible with any agentic AI platform” should mean
+
+It should mean:
+
+- RCS authors once from canonical source surfaces
+- RCS can emit or adapt those surfaces for a target platform
+- each target gets the format it actually supports
+
+It should **not** mean:
+
+- every platform receives the exact same file layout
+- every platform gets Codex-only runtime semantics
+- plugin, marketplace, hooks, prompts, and native agents all collapse into one fake universal package
+
+## Platform model
+
+Use this mental model:
+
+- **Canonical source layer**: skills, prompts, registry, catalog, templates
+- **Delivery layer**: Codex native setup, Codex plugin bundle, marketplace package
+- **Adapter layer**: target-specific bridge for platforms with different runtime rules
+
+## Claude-style example
+
+For a Claude-like platform, the right question is not:
+
+- “Can we copy the Codex plugin/runtime shape into `.claude/`?”
+
+The right question is:
+
+- “Which canonical RCS surfaces should be delivered natively, and which must stay adapter-owned because the target platform does not share Codex runtime semantics?”
+
+That usually means:
+
+- skills may be portable
+- selected guidance may be portable
+- marketplace/package metadata may be portable
+- setup-owned native agents and runtime hooks are **not** automatically portable one-to-one
+
+## Marketplace example
+
+For a marketplace-oriented platform, the package should be treated as a delivery artifact:
+
+- emitted from canonical repo sources
+- versioned from canonical package/release metadata
+- validated against a platform-specific boundary contract
+
+Not as a second source of truth.
+
+## Current repo posture
+
+Today RCS is strongest in:
+
+- Codex native setup
+- Codex plugin/marketplace packaging
+- adapter-style compatibility lanes such as OpenClaw/Hermes
+
+It is **not yet** a finished universal emitter for every external agent platform.
+
+That is intentional. The repo should grow by adding **clean adapters/delivery contracts**, not by duplicating the product into platform-specific silos.
+
+## Concrete target lanes
+
+The current platform target manifest defines these concrete lanes:
+
+- `codex-native`
+- `codex-plugin`
+- `claude-like`
+- `marketplace-bundle`
+- `adapter-openclaw`
+- `adapter-hermes`

package/docs/reference/canonical-vocabulary.md

@@ -102,5 +102,4 @@ Use these classifications consistently:
 - Active prompts/skills/missions should prefer this vocabulary.
 - Active prompts/skills/missions should expose taxonomy frontmatter so generated surface maps and validators can classify them consistently.
 - Generated surface-map output should stay synced with the active taxonomy layer.
-- Historical docs may mention removed or generic terms only as archive/reference context.
 - Tests may mention removed terms in negative assertions, migration guards, or compatibility fixtures, but not as active surface recommendations.

package/docs/reference/llm-provider-abstraction.md

@@ -0,0 +1,88 @@
+# LLM Provider Abstraction
+
+Status: canonical model- and API-agnostic provider layer for RCS runtime configuration.
+
+## Purpose
+
+RCS should treat LLM providers as interchangeable components, not permanent dependencies.
+
+That means:
+- model routing is separate from provider routing
+- provider configuration is explicit
+- fallback providers can be declared without rewriting core logic
+- OpenAI-compatible gateways, Anthropic-style gateways, or other future providers can be swapped in without redesigning the product surface
+
+## Core Principle
+
+RCS routes work by:
+1. workflow or role intent
+2. model lane
+3. provider selection
+
+The application should not have to change its core logic just because the backing provider changes.
+
+## Config Shape
+
+`.rcs-config.json` may now include:
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "base_url": "https://openrouter.ai/api/v1",
+      "api_format": "openai-compatible",
+      "env_key": "OPENROUTER_API_KEY",
+      "capabilities": ["chat", "reasoning"],
+      "label": "OpenRouter"
+    }
+  },
+  "routing": {
+    "default_provider": "openrouter",
+    "mode_providers": {
+      "forge": "openrouter"
+    },
+    "fallback_providers": ["openrouter"],
+    "mode_fallback_providers": {
+      "forge": ["openrouter"]
+    },
+    "hot_swap": true,
+    "failover": true
+  }
+}
+```
+
+## What This Enables
+
+- **Provider-agnostic routing** — use one model/provider abstraction without hard-wiring a single vendor into every workflow
+- **OpenAI-compatible gateways** — route through unified proxy formats where useful
+- **Mode-specific provider policies** — for example one provider for `forge`, another for `team`
+- **Fallback chains** — define ordered failover providers for runtime resilience
+- **Hot-swap intent** — document whether provider hot-swapping is considered part of the runtime policy
+
+## Important Clarification
+
+This layer is about **LLM/model provider routing**.
+
+It is **not** the same as:
+- `robloxstudio-mcp` live Studio transport
+- OpenClaw notifications/gateway delivery
+
+### OpenClaw
+
+OpenClaw is adjacent infrastructure:
+- useful for notifications/gateway automation
+- not the canonical LLM provider abstraction
+- should not be treated as the model-provider routing layer
+
+## Current Runtime Hooks
+
+Implemented runtime helpers live in:
+- `src/config/models.ts`
+
+They now support:
+- provider profile reads
+- default provider resolution
+- mode-specific provider resolution
+- fallback provider lists
+- hot-swap/failover flags
+- normalized active provider connection summaries