Replace Lua integration contracts and docs with mruby Code Mode

.github/workflows/mruby.yml

@@ -0,0 +1,76 @@
+name: mruby contracts
+
+on:
+  pull_request:
+    paths:
+      - '.github/workflows/mruby.yml'
+      - 'core/src/Script/**'
+      - 'packages/*/src/**'
+      - 'packages/*/script-docs/**'
+      - 'scripts/check-mruby-contracts.php'
+      - 'scripts/export-script-catalog.php'
+      - 'scripts/validate-ruby-docs.php'
+      - 'scripts/ci/composer.json'
+      - 'scripts/ci/composer.lock'
+      - 'tests/Core/MrubyCatalogConformanceTest.php'
+  push:
+    branches: [main]
+    paths:
+      - '.github/workflows/mruby.yml'
+      - 'core/src/Script/**'
+      - 'packages/*/src/**'
+      - 'packages/*/script-docs/**'
+      - 'scripts/check-mruby-contracts.php'
+      - 'scripts/export-script-catalog.php'
+      - 'scripts/validate-ruby-docs.php'
+      - 'scripts/ci/composer.json'
+      - 'scripts/ci/composer.lock'
+      - 'tests/Core/MrubyCatalogConformanceTest.php'
+
+permissions:
+  contents: read
+
+jobs:
+  contracts-and-ruby-docs:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      # The integration source is tested against a deliberately tiny public
+      # host dependency set. The adapter and guest both come from the immutable
+      # release candidate rather than a sibling engine checkout.
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          tools: composer:v2
+
+      - name: Install minimal host dependencies
+        run: composer install --no-interaction --no-progress --prefer-dist --working-dir=scripts/ci
+
+      - name: Install checksum-pinned mruby release candidate
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p .ci/ruby-engine
+          curl --fail --location --retry 3 \
+            https://github.com/OpenCompanyApp/bowerbird-ruby-engine/releases/download/v0.1.0-rc.1/bowerbird-ruby-engine-v0.1.0-rc.1-linux-amd64.tar.gz \
+            --output .ci/ruby-engine.tar.gz
+          echo '3c4b1d629d4813b5ffa977fc1559844c58ea94ffd391a6ffce9e7ac0b016605c  .ci/ruby-engine.tar.gz' | sha256sum --check
+          tar -xzf .ci/ruby-engine.tar.gz --strip-components=1 -C .ci/ruby-engine
+          test -x .ci/ruby-engine/bin/ruby-engine
+
+      - name: Check source catalog contracts
+        env:
+          OPENCOMPANY_HOST_AUTOLOAD: ${{ github.workspace }}/scripts/ci/vendor/autoload.php
+        run: php scripts/check-mruby-contracts.php "$OPENCOMPANY_HOST_AUTOLOAD"
+
+      - name: Run focused source-first conformance test
+        env:
+          OPENCOMPANY_HOST_AUTOLOAD: ${{ github.workspace }}/scripts/ci/vendor/autoload.php
+        run: php -d auto_prepend_file="$OPENCOMPANY_HOST_AUTOLOAD" scripts/ci/vendor/bin/phpunit tests/Core/MrubyCatalogConformanceTest.php
+
+      - name: Compile Ruby documentation examples
+        env:
+          OPENCOMPANY_HOST_AUTOLOAD: ${{ github.workspace }}/scripts/ci/vendor/autoload.php
+        run: php scripts/validate-ruby-docs.php "$OPENCOMPANY_HOST_AUTOLOAD" "$GITHUB_WORKSPACE/.ci/ruby-engine/bin/ruby-engine"

.gitignore

@@ -1,4 +1,7 @@
 /vendor/
+/scripts/node_modules/
+/scripts/ci/vendor/
+/.ci/
 .phpunit.cache/
 .DS_Store
 *.log

AGENTS.md

@@ -9,7 +9,7 @@ When adding or modifying an integration in this repo, optimize for:
 - package quality over package count
 - stable host behavior across OpenCompany and KosmoKrator
 - clean metadata and naming in discovery UIs
-- Lua docs that help agents use tools correctly on the first try
+- Ruby script docs that help agents use tools correctly on the first try
 - deterministic tests with fake data only
 
 This repo is a package monorepo, not a dumping ground for thin wrappers. If an integration is redundant, inconsistent, undocumented, or untested, it is not ready.
@@ -31,7 +31,7 @@ For the full architecture, see `README.md`. For a step-by-step walkthrough, see
 - Add new integrations under `packages/{name}` as Composer packages. Do not create separate repos for new integrations unless explicitly required.
 - Prefer one canonical package per service family. Do not add duplicate legacy wrappers when an existing package already owns that namespace.
 - If a legacy package must remain for compatibility, make it defer to the canonical package and declare the replacement clearly in Composer metadata.
-- Keep package ids, namespaces, app names, and Lua namespaces aligned. Avoid `google-docs` vs `google_docs` style drift.
+- Keep package ids, namespaces, app names, and script namespaces aligned. Avoid `google-docs` vs `google_docs` style drift.
 - Public-facing names must be human-readable. Do not use keyword blobs or SEO labels as the visible integration name.
 
 ## File Structure
@@ -47,8 +47,8 @@ packages/{name}/
       {Name}{Action}.php          # One class per tool
     Triggers/                     # Only if the service supports webhooks
       {Name}WebhookTrigger.php
-  lua-docs/
-    {name}.md                     # MANDATORY — supplementary docs for the AI agent
+  script-docs/
+    {name}.md                     # MANDATORY — supplementary Ruby docs for the AI agent
 ```
 
 If you add tests, they belong in this repository under `tests/`, not in a host app such as KosmoKrator or OpenCompany.
@@ -251,7 +251,7 @@ For package folder names, prefer the established package id over inventing a sec
 
 ## Checklist
 
-Every integration MUST have ALL applicable items checked. An integration is NOT complete without lua-docs, PHPDoc, and all 4 core files.
+Every integration MUST have ALL applicable items checked. An integration is NOT complete without script-docs, PHPDoc, and all 4 core files.
 
 ### Mandatory (every integration)
 
@@ -260,15 +260,15 @@ Every integration MUST have ALL applicable items checked. An integration is NOT
 - [ ] `src/{Name}ServiceProvider.php` with singleton + registry registration
 - [ ] `src/{Name}ToolProvider.php` with `ConfigurableIntegration` + multi-account `resolveService()`
 - [ ] `src/Tools/{Name}{Action}.php` — one file per tool, each with `name()`, `description()`, `parameters()`, `execute()` with try-catch
-- [ ] `lua-docs/{name}.md` — **MANDATORY for every integration, not optional**
+- [ ] `script-docs/{name}.md` — **MANDATORY for every integration, not optional**
 - [ ] PHPDoc on every class (class docblock), constructor (`@param`), `execute()` (`@param array<string, mixed> $args`), and service methods (`@param` + `@return`)
 - [ ] `credentialFields()` for credential-based integrations
 - [ ] `testConnection()` for credential-based integrations
 - [ ] All PHP files pass `php -l` syntax checks
 - [ ] Tests added in this repo for non-trivial behavior, fallback logic, filters, or endpoint mapping
 - [ ] No confidential domains, real tokens, real emails, or private project names in tests or docs
-- [ ] Lua docs match the actual normalized tool output, not just the upstream API marketing docs
-- [ ] Host behavior checked in both OpenCompany and KosmoKrator when the change affects discovery, credentials, Lua docs, or namespaces
+- [ ] Ruby script docs match the actual normalized tool output, not just the upstream API marketing docs
+- [ ] Host behavior checked in both OpenCompany and KosmoKrator when the change affects discovery, credentials, script docs, or namespaces
 
 ### Strongly Recommended
 
@@ -291,10 +291,10 @@ Every integration MUST have ALL applicable items checked. An integration is NOT
   - unsupported-host behavior
   - metadata and naming regressions
 
-## Lua Docs Rules
+## Ruby Script Docs Rules
 
-- `lua-docs/{name}.md` is required.
-- Document the namespace and the intended usage pattern.
+- `script-docs/{name}.md` is required.
+- Document the `app.call("integrations.{name}.{tool_slug}", ...)` usage pattern.
 - Document return shapes or normalized response notes when the output is not obvious.
 - If the integration flattens or renames upstream fields, say so explicitly.
 - Keep examples minimal, fake, and safe to publish.
@@ -306,12 +306,12 @@ Every integration MUST have ALL applicable items checked. An integration is NOT
 - Do not rely on fragile discovery side effects or duplicate package registration.
 - Keep metadata compatible with both:
   - settings UIs
-  - Lua namespace builders
+  - script catalog builders
 - If a change affects discovery, visible naming, or namespace shape, verify both catalog output and UI-facing metadata.
 
 ### Common Mistakes to Avoid
 
-1. **Forgetting lua-docs** — Every integration needs `lua-docs/{name}.md`. This is not optional.
+1. **Forgetting script-docs** — Every integration needs `script-docs/{name}.md`. This is not optional.
 2. **Forgetting PHPDoc** — Every class needs a docblock. Every constructor needs `@param`. Every `execute()` needs `@param array<string, mixed> $args`.
 3. **Partial completions** — Do not submit with only Service + ServiceProvider but no ToolProvider or Tools.
 4. **Missing ToolProvider** — Without it the integration won't appear in the registry.

CLAUDE.md

@@ -17,7 +17,7 @@ This repo contains Composer packages under `packages/` plus shared code under `c
 - Prefer one canonical package per service family
 - Do not add duplicate wrappers or alternate namespace spellings unless explicitly needed for compatibility
 - Keep visible names clean and human-readable
-- Keep Lua namespaces, package ids, metadata, and docs aligned
+- Keep Ruby script namespaces, package ids, metadata, and docs aligned
 - Do not commit real domains, real emails, real project names, or real API tokens in tests or docs
 
 ## Before You Add An Integration
@@ -40,14 +40,14 @@ This repo contains Composer packages under `packages/` plus shared code under `c
 - `src/{Name}ServiceProvider.php`
 - `src/{Name}ToolProvider.php`
 - `src/Tools/...`
-- `lua-docs/{name}.md`
+- `script-docs/{name}.md`
 
 ## Quality Bar
 
 - Tools should return shaped agent-friendly output, not raw API dumps
 - Services should own normalization, endpoint quirks, and safe fallbacks
 - Unsupported capabilities should fail clearly
-- Lua docs should reflect actual tool behavior, including normalized output and self-hosted caveats
+- Ruby script docs should reflect actual tool behavior, including normalized output and self-hosted caveats
 - Non-trivial behavior needs tests in this repo
 
 ## Test Rules
@@ -62,5 +62,5 @@ This repo contains Composer packages under `packages/` plus shared code under `c
 - Run syntax checks
 - Run the relevant PHPUnit coverage in this repo
 - Check metadata and naming
-- Check Lua docs
+- Check Ruby script docs
 - Make sure the worktree is clean before you stop