@xmarts/genius-setup 1.10.0 → 1.11.0

package/bin/genius-setup.js

@@ -225,6 +225,32 @@ function runSetup(token) {
     log('WARN: could not write CLAUDE.md protocol (' + e.message + ')');
   }
 
+  // 4b) ~/.claude/skills — install the bundled Genius skills so `token+npm` REALLY
+  //     delivers skills too (previously only hooks+MCP shipped, though the footer
+  //     already claimed skills arrived — this closes that gap). plugin/skills is the
+  //     git source-of-truth mirror; copy each skill dir into ~/.claude/skills/<name>/,
+  //     refreshing ours without clobbering the consultant's own skills. Fails open.
+  let skillsInstalled = [];
+  try {
+    const SKILLS_SRC = path.join(__dirname, '..', 'plugin', 'skills');
+    const SKILLS_DST = path.join(CLAUDE_DIR, 'skills');
+    if (fs.existsSync(SKILLS_SRC)) {
+      ensureDir(SKILLS_DST);
+      for (const name of fs.readdirSync(SKILLS_SRC)) {
+        const src = path.join(SKILLS_SRC, name);
+        try {
+          if (!fs.statSync(src).isDirectory()) continue;
+          fs.cpSync(src, path.join(SKILLS_DST, name), { recursive: true, force: true });
+          skillsInstalled.push(name);
+        } catch (e) {
+          log('WARN: could not install skill ' + name + ' (' + e.message + ')');
+        }
+      }
+    }
+  } catch (e) {
+    log('WARN: could not install skills (' + e.message + ')');
+  }
+
   // 5) Fan out the consultant's OTHER MCP servers (asana, clickup, google, ...).
   //    Their non-secret shape (manifest) + per-device secret VALUES come from the
   //    Bearer-authed /xma/genius/v1/mcp/secrets endpoint. We write Claude Code
@@ -325,6 +351,7 @@ function runSetup(token) {
   log('  - Presence       : ' + presenceDst + '  (SessionStart, detached — honest time-tracking amarre)');
   log('  - Config         : ' + path.join(GENIUS_DIR, 'config.json'));
   log('  - Protocol       : ' + path.join(CLAUDE_DIR, 'CLAUDE.md') + '  (auto-managed)');
+  if (skillsInstalled.length) log('  - Skills         : ' + path.join(CLAUDE_DIR, 'skills') + '  (' + skillsInstalled.join(', ') + ')');
   if (CLIENT) log('  - Default client : ' + CLIENT);
   log('');
   log('  Restart Claude Code. Per-turn Brain injection + automatic capture + the Genius');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmarts/genius-setup",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "One-command, self-updating onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session/time capture + presence heartbeat for honest time-tracking 'amarre' + plan/committee→Brain enforcement + CLAUDE.md protocol + MCP fan-out: provisions the consultant's granted MCP servers into Claude Code & Claude Desktop). Secret-free onboarding via single-use setup-token exchange. Installs once; self-updates daily so new tools/skills/features arrive with zero action.",
   "bin": {
     "genius-setup": "bin/genius-setup.js"
@@ -12,7 +12,8 @@
     "hooks/plan_committee_guard.py",
     "hooks/genius_presence.py",
     "CLAUDE_PROTOCOL.md",
-    "README.md"
+    "README.md",
+    "plugin/skills"
   ],
   "engines": {
     "node": ">=16"

package/plugin/skills/genius-operator/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: genius-operator
+description: >
+  Operate the Xmarts Genius platform from any session: read, write, deploy webapps,
+  deploy/manage modules, snapshot, restore and restart Odoo — on the BeeSmart central
+  OR on ANY registered client Odoo (GEA, Elevatrix, Deploy-O, etc.) through the
+  `beesmart_genius` MCP. The key unlock most sessions miss: every Genius tool accepts a
+  `target_client` parameter that routes the SAME call to a client's Odoo over the secure
+  HMAC gateway. Use this skill whenever a session says it "can't" reach a client, can't
+  deploy a webapp to a client, can't see/manage a client's modules, or whenever the work
+  touches xma_genius, xma_connect, beesmart_genius, the Genius Brain, GEA Ecuador, or
+  deploying/controlling anything on a client instance from the central — even if the user
+  doesn't name the tool. If you ever think "I don't have access to that client", read this
+  skill first: you almost certainly do.
+---
+
+# Genius Operator
+
+You are operating the **Xmarts Genius** platform. Genius is a central command server
+(module `xma_genius`, living on `beesmart.digital`) that controls a fleet of client Odoo
+instances. Each client runs a thin agent (`xma_connect`) that exposes a signed HMAC gateway.
+You reach all of it through one MCP server: **`beesmart_genius`**.
+
+This skill exists to kill one specific failure: sessions saying *"no puedo hacer eso / I
+don't have access to that client"* when they actually can. They can. They just didn't set
+one parameter.
+
+## The one thing to internalize: `target_client`
+
+Almost every `mcp__beesmart_genius__*` tool takes an optional **`target_client`** argument.
+
+- **Omit it** → the call runs on the BeeSmart central (`odoo_clean` DB).
+- **Set it** to a client's name or UUID → the EXACT same call is signed (HMAC-SHA256) and
+  routed through that client's `xma_connect` gateway, executing on *their* Odoo and returning
+  the result to you.
+
+```
+# Reads the central Brain on beesmart:
+execute_orm(code="result = env['xma.learning'].search_count([])")
+
+# Reads GEA Ecuador's live Odoo — same tool, one extra arg:
+execute_orm(code="result = env['sale.order'].search_count([])", target_client="GEA Ecuador")
+```
+
+That is the whole trick. A session is **not** sandboxed to beesmart. With `target_client`
+it can read data, write records, deploy webapps, install/upgrade modules, snapshot, restore,
+and restart Odoo on any *registered, connected* client. When you catch yourself about to say
+"I can't do that on the client," stop and set `target_client` instead.
+
+`target_client` accepts either the human name (`"GEA Ecuador"`) or the UUID
+(`"74292458-44e8-406c-a476-4e89f86920c8"`). The name is matched on the central's `xma.client`
+registry, so it must match an existing record.
+
+## "Can I actually do X?" — yes, here's the map
+
+When in doubt, this table answers it. The full per-tool reference with quirks is in
+[references/tool-catalog.md](references/tool-catalog.md) — read it when you need the exact
+argument shape or hit an edge case.
+
+| You want to… | Tool | Routable to a client? |
+|---|---|---|
+| Run arbitrary ORM/Python (read or write) | `execute_orm` | ✅ `target_client` |
+| Search / read records | `search_read`, `read_record`, `read_group` | ✅ |
+| Create / update / delete a record | `create_record`, `update_record`, `delete_record` | ✅ |
+| Call a model method | `execute_method` | ✅ |
+| Deploy / edit a **webapp** | `manage_webapp` | ✅ **only if the client has the webapp infra installed — probe first** (see below + [deploy-webapp-to-client.md](references/deploy-webapp-to-client.md)) |
+| Deploy / install / upgrade a **module** | `manage_module`, `deploy_module` | ✅ — see [manage-client-modules.md](references/manage-client-modules.md) |
+| Inspect a model's schema | `get_model_schema`, `list_models` | ✅ |
+| Read / search a client's source code | `code_read`, `code_search`, `search_webapp_code` | ✅ |
+| Snapshot / restore / export the DB | `create_snapshot`, `restore_snapshot`, `export_database` | ✅ |
+| Restart Odoo | `trigger_restart` | ✅ |
+| Build a chart/dashboard | `create_echart` | ✅ *(same infra caveat as webapps)* |
+| Query the Genius **Brain** | `query_knowledge` | ❌ central only (the Brain lives on beesmart) |
+| Capture a learning to the Brain | `capture_learning` | ❌ central only |
+| Read your own consultant profile | `get_my_profile` | ❌ central only |
+
+33 tools are routable to clients in total. If a tool you need isn't listed, check
+[references/tool-catalog.md](references/tool-catalog.md) before concluding it's impossible.
+
+## Always orient before you act
+
+The Brain (`query_knowledge`) is the server-side source of truth and it remembers things this
+session doesn't. It has saved you from real footguns (downgrade bricking, version desync,
+auth gotchas). So:
+
+1. **`query_knowledge(<your task topic>)` before building or debugging.** Two minutes here
+   beats an hour of rediscovering a known trap.
+2. Check the client is actually reachable before routing to it. A quick
+   `execute_orm(code="result = True", target_client="<name>")` round-trips the gateway. If it
+   errors with `auth_invalid` / `Not configured`, the client has a master↔client api_key
+   desync — that's a known issue, query the Brain for "Not configured gateway api_key desync"
+   rather than guessing.
+3. After a notable build or fix, **`capture_learning(...)`** so the next session inherits it.
+   Required shape: `name` + `category` (one of `breaking_change | pattern | antipattern |
+   workaround | best_practice`) + `resolution`; `tags` is a comma-separated **string**.
+
+## Hard rules (these are non-negotiable and protect production)
+
+These come straight from the Xmarts operating doctrine — follow them even when not asked:
+
+- **Snapshot before any write to a client's production data.** Use `create_snapshot`
+  (`target_client=...`) first. The orchestrated `deploy_module` auto-snapshots; manual
+  `update_record`/`execute_orm` writes do not — you take the snapshot. No snapshot → don't run
+  the change.
+- **Never destroy productive data.** Archive with `active=False`, never `unlink()`/delete.
+  It's reversible and keeps the audit trail.
+- **Everything is Odoo 19.** Generate only v19-compatible code (e.g. `<list>` not `<tree>`,
+  `models.Constraint` not `_sql_constraints`, `group_ids` not `groups_id`). When unsure,
+  `code_search` the client's own source to confirm the API before you write it.
+- **Webapps are mobile-first and theme-driven.** No hardcoded hex colors — colors flow from
+  the theme. Don't hand-roll a webapp from scratch here; use the dedicated skills (below) to
+  build it well, then this skill to *deploy* it to the right place.
+- **Credentials never inline.** No api_keys/passwords in tool arguments or committed code.
+
+## Webapps: build with the specialists, deploy with this skill
+
+This skill's job for webapps is the **routing and deployment** layer — getting the right app
+onto the right Odoo (central vs a specific client) and verifying it serves. For the actual
+*construction* quality (design, theming, mobile-first, audit), hand off to the specialists:
+
+- `webapp-forge` — prompt → mockup → theme → React → deploy pipeline
+- `webapp-theming-system` — OKLCH themes, dark mode, WCAG contrast
+- `webapp-refine` — iterate on an existing webapp
+- `webapp-audit` — 6-point quality gate before you call it done
+- `xmarts-kanban-standard` — the mandatory kanban card look
+
+**Prerequisite — probe the client's capability first, do NOT trust the version number.**
+Webapp deploy to a client only works if that client's `xma_connect` actually ships *and loads*
+the webapp infra (the `mcp.webapp*` models + the `/mcp/webapp` controller + the `manage_webapp`
+gateway handler). The reported `xma_connect_version` is **not** a reliable gate — a stale-
+constant bug and divergent deployed bundles mean a client labelled "5.0.0" may lack the infra
+even though git added it at 4.0.0. So before deploying, route this probe:
+
+```
+execute_orm(code="result = bool(env['ir.model'].search([('model','=','mcp.webapp')], limit=1))",
+            target_client="<client>")
+```
+
+`false` → the client can't host a webapp yet; it needs an `xma_connect` upgrade that ships and
+loads the webapp infra first (and on some clients that upgrade is itself gated). Probe every
+time, because **state changes**: GEA Ecuador returned `false` at `xma_connect` 5.0.0, then was
+upgraded to 8.0.0 (Deploy-O parity) and now returns `true`. Never hard-code "client X can/can't"
+from memory — the version field lies and clients get upgraded; the live probe is the truth.
+
+The deploy mechanics, the data-flow gotcha that bites everyone (page `data_code` vs webapp
+`data_code`), the slug/URL model, and the client-vs-central decision are all in
+[references/deploy-webapp-to-client.md](references/deploy-webapp-to-client.md). Read it before
+your first deploy to a client.
+
+## Modules: controlling what Xmarts builds for a client (the GEA case)
+
+When a client like GEA accumulates many Xmarts-built modules, this is how you keep control of
+them from the central — list installed modules, read their source, deploy new ones, upgrade,
+snapshot before each change, and roll back if needed. The full workflow, including the
+orchestrated `deploy_module` (pre-checks + auto-snapshot + post-checks) and when a
+Python-bearing module needs the SSH path instead of `manage_module`, is in
+[references/manage-client-modules.md](references/manage-client-modules.md).
+
+The short version: `module_list_installed` / `manage_module` (info) to see what's there,
+`code_read` + `code_search` to inspect it, `deploy_module` to ship changes safely. Always
+validate a non-trivial module on a clean Odoo 19 env first — green install ≠ correct.
+
+## When a session is stuck saying "I can't"
+
+Diagnose in this order — it's almost always #1 or #2:
+
+1. **Did it set `target_client`?** Most "I can't reach the client" cases are just a missing
+   parameter. Add it.
+2. **Is the MCP authenticated?** The `beesmart_genius` tools must be loaded. If they aren't
+   visible, the session needs the MCP connected (and OAuth doesn't always persist between
+   sessions). Reconnect, don't give up.
+3. **Is the client connected?** Round-trip a trivial `execute_orm` to it. If `Not configured`,
+   it's the known api_key desync — query the Brain, don't reinvent.
+4. **Is the tool genuinely central-only?** Only Brain tools (`query_knowledge`,
+   `capture_learning`, `get_my_profile`) are. Everything operational is routable.
+
+Only after all four genuinely fail is "I can't" the honest answer — and then say *why*,
+specifically, not just "no puedo".

package/plugin/skills/genius-operator/references/deploy-webapp-to-client.md

@@ -0,0 +1,183 @@
+# Deploying a webapp to a client (or central) via Genius
+
+This is the routing/deployment layer. Build the webapp's quality (design, theme, mobile-first,
+audit) with the specialist skills — `webapp-forge`, `webapp-theming-system`, `webapp-refine`,
+`webapp-audit`, `xmarts-kanban-standard`. This file is about getting the right app onto the
+right Odoo and confirming it serves.
+
+## Table of contents
+- [Prerequisite: the client must HAVE the webapp infra (probe it)](#prerequisite-probe-the-client)
+- [Central vs client: decide first](#central-vs-client-decide-first)
+- [The data model](#the-data-model)
+- [The gotcha that bites everyone: data_code lives on the PAGE](#the-gotcha-data_code-lives-on-the-page)
+- [Deploy recipe](#deploy-recipe)
+- [Verify it serves](#verify-it-serves)
+- [Editing an existing webapp](#editing-an-existing-webapp)
+- [Quality gates before you call it done](#quality-gates)
+
+## Prerequisite: probe the client
+
+A client can only host a webapp if its `xma_connect` actually ships **and loads** the webapp
+infra: the models `mcp.webapp` / `mcp.webapp.page` / `mcp.webapp.page.file` /
+`mcp.webapp.endpoint` / `mcp.webapp.theme`, the `/mcp/webapp/...` controller, and the
+`manage_webapp` gateway handler. The webapp infra was added to `xma_connect` at v19.0.4.0.0,
+but **do not gate on the version number** — it lies. A stale-constant version bug plus divergent
+deployed bundles (an older "5.0.0" served as newest) mean a client can report a version that
+*should* have the infra and still not have it. Probe the ground truth instead:
+
+```
+execute_orm(code="result = bool(env['ir.model'].search([('model','=','mcp.webapp')], limit=1))",
+            target_client="<client>")
+```
+
+- `true`  → infra present, proceed.
+- `false` → the client cannot host a webapp yet. It needs an `xma_connect` upgrade that ships
+  and loads the webapp models first. Don't attempt `manage_webapp` against it — it will fail
+  on a missing model. Say so explicitly and, if asked, scope the upgrade (which on some clients
+  is itself a gated rollout).
+
+**Why this is probe-not-version:** GEA Ecuador once returned `false` at `xma_connect` 5.0.0
+(webapp models absent), and was later upgraded to 8.0.0 — it now returns `true` (full infra,
+Deploy-O parity). The version field is unreliable AND clients get upgraded out from under you,
+so the only safe gate is the live probe. If a client's probe is `false`, it needs an
+`xma_connect` upgrade that ships + loads the webapp infra (on big/gated clients that upgrade
+has its own rollout window); until then a "client webapp" can only live on the central reading
+the client's data over the gateway (slower, fragile).
+
+## Central vs client: decide first
+
+`manage_webapp` writes `mcp.webapp` records wherever the call lands:
+
+- **No `target_client`** → webapp lives on BeeSmart central, served at
+  `https://beesmart.digital/mcp/webapp/<slug>`. Use for Genius's own admin/consultant tools.
+- **`target_client="<client>"`** (one whose probe returned `true`) → webapp lives on that
+  client's Odoo, served at `https://<client-domain>/mcp/webapp/<slug>`. Use for anything the
+  client's own users see, or any app that needs the client's live data.
+
+Rule of thumb: if the app reads/writes the client's business data (their sales, their
+inventory), deploy it ON the client with `target_client`. Routing a central webapp to read
+client data over the gateway per request is slower and fragile — put the app where the data is.
+
+The client must have `xma_connect` installed and connected **with the webapp infra present**
+for client deploys (see the prerequisite probe above). Don't assume a given client's state from
+memory — it changes (GEA went from no-infra to full infra after an upgrade). Probe, then decide.
+
+## Visibility & RBAC (xma_connect ≥ 19.0.9.0.0) — PROBE → CHOOSE → DEPLOY → VERIFY
+
+Newer `xma_connect` gates every webapp natively by a `visibility` field
+(`public` / `internal` / `groups` / `users`, default **internal**), enforced by `ir.rule` +
+route auth — no self-gating inside `data_code`. The contract for every deploy:
+
+1. **PROBE** the client supports it: `search_read(model="ir.model", domain=[["model","=","mcp.webapp"]], ...)` exists, and check `mcp.webapp._fields` has `visibility` (xma_connect ≥ 9.0.0). Older clients have no visibility model → upgrade first.
+2. **CHOOSE** visibility explicitly on EVERY `manage_webapp` create — never omit (omitting defaults to `internal`, which is safe but be deliberate):
+   - `internal` (default): any logged-in internal user.
+   - `groups`: pass `shared_group_ids` (native `res.groups`); add `base.group_portal` for portal users.
+   - `users`: pass `shared_user_ids`.
+   - `public`: anyone, no login — requires BOTH `visibility:"public"` **and** `public_confirm:true` in the SAME call, plus `public_model_allowlist` for any model the data reads. The tool rejects public without confirm.
+   - **Do NOT** write `env.user.has_group(...)`/`res.users` self-gates in `data_code` — the native rule gates; a self-gate just double-gates and 403s anonymous.
+3. **DEPLOY** with the explicit visibility; the tool result echoes `visibility` + `access_summary` ("who can see this") — read it back.
+4. **VERIFY** by fetching `/mcp/webapp/<slug>/page/<id>/data` (or the app URL) **as anonymous AND as an internal user**: an `internal` app must 401/redirect anonymous (no traceback); a `public` app must render for anonymous with its blast radius == the allowlist.
+
+**Public forms / notice boards:** public `data_code` runs in a locked sandbox (no `.sudo()`, only allowlisted models). To accept submissions, set the endpoint `allow_public:true` + `submit_fields` and call `submit({...})` in `handler_code` — it writes one `mcp.webapp.submission` (staff-only) and returns an opaque ref. Anonymous calls are rate-limited per IP/min.
+
+## The data model
+
+```
+mcp.webapp                 # the app: name, slug, router_mode, theme, PWA, shared styles/components
+└── mcp.webapp.page        # a route: route_path, component_code (React), data_code (Python)
+    └── mcp.webapp.page.file   # extra JS/JSX files injected before the page component
+mcp.webapp.endpoint        # api.get/post/... handlers (handler_code, safe_eval Python)
+mcp.webapp.theme           # theme tokens (OKLCH); colors flow from here — never hardcode hex
+```
+
+`component_code` is React (props: `{data, routeParams, globalState, setGlobalState,
+initialData, api, storage}`). `data_code` / `handler_code` are safe_eval Python with the SAME
+rules and pre-imports as `execute_orm` — assign to `result`, no `import`, use
+`env['mcp.webapp'].browse(mcp_webapp_id)`, never hardcode IDs or slugs.
+
+## The gotcha: `data_code` lives on the PAGE
+
+The single most common reason a deployed page shows no data: the component reads its data from
+the **page's** `data_code`, not the webapp's. The webapp-level `data_code` only feeds
+`initialData` on app load. If your page needs records, put the query in that **page's**
+`data_code` and read it from the `data` prop.
+
+When you edit data logic, update the PAGE's `data_code` (and if you also keep a copy at webapp
+level, update both — they drift otherwise). This has burned multiple sessions.
+
+## Deploy recipe
+
+1. **Pick the target.** Central or `target_client`? (see above)
+2. **If targeting a client, run the capability probe** (`mcp.webapp` exists?). `false` → stop,
+   the client needs an agent upgrade first.
+4. **`query_knowledge("webapp deploy <client> <topic>")`** — pick up known gotchas first.
+5. **Snapshot if it's a client with anything to lose.** `create_snapshot(target_client=...)`.
+   Creating a brand-new webapp is additive and low-risk; still cheap insurance on production.
+6. **Create the webapp shell**, then pages/endpoints. You can do it in one `manage_webapp`
+   call combining `create_webapp` + `create_pages` + `create_endpoints`:
+
+```
+manage_webapp(
+  target_client="<client-with-webapp-infra>",
+  create_webapp={
+    "name": "GEA Ops Dashboard",
+    "slug": "gea-ops",
+    "router_mode": "hash",          # hash works everywhere; "browser" needs a slug + clean URLs
+    "pwa_enabled": True,            # mobile-first PWA is the Xmarts standard
+    "tailwind_enabled": True
+  },
+  create_pages=[{
+    "name": "Home",
+    "route_path": "/",
+    "component_code": "function Home({data}){ return <div className='p-4'>...</div> }",
+    "data_code": "result = {'orders': env['sale.order'].search_count([])}"   # PAGE data_code!
+  }]
+)
+```
+
+7. **Theme it** — don't hardcode colors. Hand off to `webapp-theming-system` or set the
+   `mcp.webapp.theme`. Colors must flow from theme tokens so dark/light both work.
+8. **Verify** (next section).
+9. **`capture_learning(...)`** if you hit and solved anything non-obvious.
+
+For multi-step builds, create the shell first, then add pages/files in follow-up
+`manage_webapp` calls (each can derive the webapp from a page/file id, so you don't have to
+repeat `update_webapp`).
+
+## Verify it serves
+
+Don't declare done from the tool's success message alone — confirm the route actually renders:
+
+```
+# Confirm the record exists on the right instance:
+search_read(model="mcp.webapp", domain=[["slug","=","my-app"]],
+            fields=["id","name","slug"], target_client="<client>", limit=5)
+```
+Then load `https://<client-domain>/mcp/webapp/my-app` (or have the user open it). A 200
+with the rendered page = deployed. If the page is blank, re-check the **page** `data_code` and
+the browser console for a component error.
+
+## Editing an existing webapp
+
+Read before you write — use `search_read`/`read_record` (with `target_client`) to get current
+code, then patch surgically:
+
+```
+# Discover pages:
+search_read(model="mcp.webapp.page", domain=[["webapp_id","=",ID]],
+            fields=["id","name","route_path"], target_client="<client>", limit=50)
+# Read full code:
+read_record(model="mcp.webapp.page", id=PAGE_ID,
+            fields=["component_code","data_code"], target_client="<client>")
+# Surgical edit (preferred over full rewrite):
+manage_webapp(target_client="<client>",
+  update_pages=[{"page_id": PAGE_ID,
+                 "component_code_patches": [{"find": "old snippet", "replace": "new snippet"}]}])
+```
+Use `search_webapp_code` to locate exact strings before patching.
+
+## Quality gates
+
+Before calling a webapp done, run the `webapp-audit` skill (PWA, WCAG contrast, no hardcoded
+hex, CSS/JS budget, accessibility, dark mode). The Xmarts non-negotiables: mobile-first PWA,
+44px touch targets, theme-driven colors, dark mode that actually flips, skeleton loading.

package/plugin/skills/genius-operator/references/manage-client-modules.md

@@ -0,0 +1,106 @@
+# Controlling a client's Xmarts-built modules (the GEA case)
+
+GEA Ecuador will accumulate many modules built by Xmarts. This is how you keep central control
+of them: see what's installed, read the source, ship changes safely, upgrade, and roll back —
+all from the `beesmart_genius` MCP with `target_client="GEA Ecuador"`.
+
+GEA facts to keep in mind: Odoo 19 Enterprise, ~474 modules installed, DB ≈ 14.8 GB (large —
+exports/restores need a dedicated window), hosted on `geaecuador.xmarts.net`. Its `xma_connect`
+was upgraded to 8.0.0 (Deploy-O parity) and now has the full webapp/dashboard infra — but
+always probe `mcp.webapp` rather than trusting that statement, since state changes.
+Files in `xma_connect`/custom addons on `xmarts.net` infra are often owned by root, so Odoo's
+uid can't write — a true filesystem deploy may need an SSH `chown`. The gateway path below
+avoids that for ZIP-importable modules.
+
+## Table of contents
+- [See what Xmarts has shipped](#1-see-whats-installed)
+- [Inspect a module's source](#2-inspect-the-source)
+- [Ship or upgrade a module](#3-ship-or-upgrade-a-module-safely)
+- [manage_module vs deploy_module vs SSH](#which-path-data-vs-python)
+- [Snapshot & rollback](#4-snapshot--rollback)
+- [Restart when needed](#5-restart-when-the-registry-is-stale)
+
+## 1. See what's installed
+
+```
+module_list_installed(target_client="GEA Ecuador")
+```
+Or filter to the Xmarts-built ones:
+```
+search_read(model="ir.module.module",
+            domain=[["state","=","installed"],["name","=like","xma%"]],
+            fields=["name","installed_version","summary","state"],
+            target_client="GEA Ecuador", order="name", limit=200)
+```
+This is your inventory of "what Xmarts built and shipped to GEA" and the live version of each.
+(Remember the central's `xma.client.xma_connect_version` field is unreliable — read the real
+versions from GEA like this instead.)
+
+## 2. Inspect the source
+
+```
+# Find where something is defined across GEA's addons:
+code_search(pattern="class .*Model|def action_", file_pattern="**/*.py",
+            output_mode="files_with_matches", limit=50, target_client="GEA Ecuador",
+            module="xma_<module>")
+# Read a specific file (path from the addon root):
+code_read(path="xma_<module>/models/<file>.py", target_client="GEA Ecuador")
+```
+For webapp/echart code shipped to GEA, use `search_webapp_code`.
+
+## 3. Ship or upgrade a module safely
+
+Prefer the orchestrated path — it snapshots automatically and runs pre/post checks:
+
+```
+deploy_module(target_client="GEA Ecuador", arguments={...module + options...})
+```
+
+`deploy_module` = pre-checks → auto-snapshot → install/upgrade → post-checks. This is the
+right default for production because the snapshot and verification are built in.
+
+For authoring/iterating a data/XML/CSV/webapp module, `manage_module` gives finer control:
+- `create_module` + `create_files` (include `__manifest__.py` as a normal file).
+- `skip_install=true` while adding files across several calls; `false` on the last call to
+  install.
+- If an install fails, **files are saved but the install rolls back** — fix the broken file
+  with `update_files` and call again; you don't resubmit everything.
+- `force=true` re-inits `noupdate=1` records. `uninstall_first=true` **drops all module data**
+  — destructive, ask the user before using it.
+- Manifest is validated pre-install: every file in `data` must exist.
+
+### Which path: data vs Python
+
+| Module contents | Path | Why |
+|---|---|---|
+| XML / CSV / views / webapp / data only | `manage_module` or `deploy_module` (ZIP via `base_import_module`) | Installs cleanly over the gateway, no SSH. |
+| Python that must execute at load (models, compute, controllers) | Validate on a **clean Odoo 19 EE env first**, then deploy. `base_import_module` does not reliably run arbitrary Python — a real filesystem deploy may be needed (SSH `chown` on `xmarts.net`). | Historically `manage_module` is data-only for code execution (Brain: "manage_module data-only confirmed"). Don't assume a Python module "installed" just because the call returned success — verify the model/fields actually exist. |
+
+Always: a green install ≠ a correct module. After install, verify behavior — e.g.
+`list_models` / `get_model_schema` for new models, or `execute_orm` exercising the new logic,
+routed to GEA. For anything non-trivial, validate on the disposable clean env before GEA.
+
+When generating module code, it's **Odoo 19** — `<list>` not `<tree>`, `models.Constraint` not
+`_sql_constraints`, `group_ids` not `groups_id`, `hr.version` not `hr.contract`, fiscal tax
+mappings on taxes not fiscal positions. `code_search` GEA's own source to confirm an API before
+relying on it.
+
+## 4. Snapshot & rollback
+
+```
+create_snapshot(target_client="GEA Ecuador")        # before any change deploy_module didn't auto-snapshot
+list_snapshots(target_client="GEA Ecuador")          # confirm it exists
+restore_snapshot(target_client="GEA Ecuador", ...)   # the rollback — confirm with the user first
+```
+Register every snapshot per the snapshot protocol (name, UUID, type, size, trigger, storage).
+On a 14.8 GB DB, snapshot/restore is heavy — plan the window, don't fire it mid-business-hours
+without telling the user.
+
+## 5. Restart when the registry is stale
+
+Some upgrades change the in-memory registry; the running server keeps the old one until
+restarted:
+```
+trigger_restart(target_client="GEA Ecuador")
+```
+Always restart after a `--stop-after-init` style upgrade so the new code is actually live.

package/plugin/skills/genius-operator/references/tool-catalog.md

@@ -0,0 +1,129 @@
+# Genius Tool Catalog (`beesmart_genius` MCP)
+
+The authoritative list of what you can do through Genius, what routes to a client, and the
+quirks that trip people up. All tools are namespaced `mcp__beesmart_genius__<tool>`.
+
+## Table of contents
+- [Routing model](#routing-model)
+- [Routable operational tools (run on central OR a client)](#routable-operational-tools)
+- [Central-only tools (Brain & self)](#central-only-tools)
+- [Cross-cutting quirks](#cross-cutting-quirks)
+
+## Routing model
+
+Every routable tool takes `target_client` (string: client name or UUID).
+- Omitted → executes on BeeSmart central (`odoo_clean`).
+- Set → signed HMAC-SHA256 request through the client's `xma_connect` gateway
+  (`/xma/gateway/v1`), executed under the client's non-admin **service user** (not superuser),
+  inside a savepoint that rolls back on error.
+
+The client side dispatches through `ToolDispatcher` (33 registered handlers). If a tool isn't
+in that set, it can't be routed — but every operational tool you'd want is.
+
+Reachability self-test (cheap, safe, read-only):
+```
+execute_orm(code="result = {'ok': True, 'db': env.cr.dbname}", target_client="GEA Ecuador")
+```
+A clean `{success: true, ...}` means the gateway, HMAC auth and service user are all healthy.
+`auth_invalid` / `Not configured` = master↔client api_key desync (known issue — query the
+Brain: "Deploy-O gateway Not configured api_key desync", learning #1065).
+
+## Routable operational tools
+
+### Data read
+| Tool | Use | Quirks |
+|---|---|---|
+| `search_read` | Search + read fields | Paginated — compare `count` vs `total`, use `offset`. Binary/image fields auto-base64'd as separate content. |
+| `read_record` | One record by ID | Cheaper than `search_read` if you have the ID. |
+| `read_group` | GROUP BY aggregation | v19: this is the supported aggregator (raw `read_group` ORM method is deprecated in favor of `_read_group`/`formatted_read_group`, but the MCP tool wraps it correctly). |
+| `validate_domain` | Sanity-check a domain before a big query | Use on untrusted/long domains. |
+
+### Data write
+| Tool | Use | Quirks |
+|---|---|---|
+| `create_record` | Create one record | Simple creates only. |
+| `update_record` | Write fields | **Snapshot first if production.** Archive via `active=False`, never delete. |
+| `delete_record` | Delete | Avoid on productive data — prefer `active=False`. Ask the user before destructive deletes. |
+| `execute_method` | Call any model method | For `action_confirm`, recompute, custom methods. Powerful — same write-safety rules apply. |
+| `execute_orm` | Arbitrary safe_eval Python | The workhorse. NO `import`/`from` — utilities are pre-imported (`env`, `Command`, `datetime`, `requests`, `re`, `json`, `defaultdict`, `Counter`, etc.). Assign to `result`. Output cap ~100KB → paginate. `hasattr`/`getattr`/`__class__`/`dir` are blocked by safe_eval. |
+| `bulk_execute` | Batch several operations | For multi-op efficiency. |
+
+### Schema & code introspection
+| Tool | Use |
+|---|---|
+| `get_model_schema` / `get_model_schema_progressive` | Field definitions. Filter by type / required to shrink output. |
+| `list_models` | Enumerate models on the instance. |
+| `code_read` | Read a source file by path (from addon root). |
+| `code_search` | Regex search across addon source. `files_with_matches` to discover, then `code_read`. Paginate via `offset` (compare `returned` vs `total_*`). |
+| `search_webapp_code` | Search inside `mcp.webapp` component/data code. |
+| `get_system_info` | Odoo version, db, module counts, etc. |
+
+### Webapps  → see [deploy-webapp-to-client.md](deploy-webapp-to-client.md)
+**Client-routed webapp/echart/design tools require the client's `xma_connect` to actually have
+the `mcp.webapp*` / `mcp.echart` / `mcp.design.asset` infra installed.** This is NOT guaranteed
+by the version number (see the version-truth quirk below) — probe first:
+`execute_orm(code="result = bool(env['ir.model'].search([('model','=','mcp.webapp')], limit=1))", target_client="<client>")`.
+A `false` means these three tools fail there until the agent is upgraded. State changes — GEA
+returned `false` at 5.0.0 and `true` after its 8.0.0 upgrade — so probe each time, don't recall.
+
+| Tool | Use |
+|---|---|
+| `manage_webapp` | Create/update webapps, pages, endpoints, page-files, assets. Surgical `*_patches` edits. Needs `mcp.webapp` infra on the client. |
+| `create_echart` | Persistent ECharts 6.x dashboards. Needs `mcp.echart` on the client. |
+| `manage_design_asset` | Manage `mcp.design.asset` (icons/SVGs). Needs `mcp.design.asset` on the client. |
+
+### Modules  → see [manage-client-modules.md](manage-client-modules.md)
+| Tool | Use | Quirks |
+|---|---|---|
+| `module_list_installed` | List installed modules on the instance | Start here to see what Xmarts has shipped to a client. |
+| `manage_module` | Create/install/upgrade/uninstall an importable module (ZIP via `base_import_module`) | Best for data/XML/CSV/webapp modules. `skip_install=true` for multi-step builds. `uninstall_first=true` is **destructive** — ask the user first. |
+| `deploy_module` | Orchestrated deploy: pre-checks → **auto-snapshot** → install → post-checks | Preferred path for shipping a module to a client safely. |
+| `module_manage_safe` | Guarded module ops | Safety wrapper. |
+| `module_job_status` | Poll an async module job | For long installs. |
+
+### DB lifecycle & ops
+| Tool | Use | Quirks |
+|---|---|---|
+| `create_snapshot` | Snapshot the DB (and register it) | **Do this before any production write.** Register per the snapshot protocol (name, UUID, type, size, trigger). |
+| `list_snapshots` | List snapshots | Verify a snapshot exists before a risky change. |
+| `restore_snapshot` | Restore from a snapshot | The rollback. Confirm with the user. |
+| `export_database` / `export_data` | Pull a full DB dump / dataset out | GEA is ~14.8GB — large-dump exports need a dedicated window. |
+| `upload_attachment` | Push a binary into the instance | Base64 or URL. |
+| `trigger_restart` / `trigger_restart` | Restart Odoo on the client | Needed after some module upgrades (registry lives in memory until restart). |
+| `analyze_data` | Server-side analysis helper | — |
+
+## Central-only tools
+
+These have **no** `target_client` because they operate on Genius's own brain/registry:
+
+| Tool | Use |
+|---|---|
+| `query_knowledge` | Vector search the Genius Brain (Gemini embeddings). Run BEFORE debugging/building. Filters: `category`, `odoo_version`. |
+| `capture_learning` | Write a learning to the Brain. Required: `name` + `category` (`breaking_change\|pattern\|antipattern\|workaround\|best_practice`) + `resolution`. `tags` = comma-separated string. |
+| `bulk_manage_learnings` / `update_learning` | Maintain learnings. |
+| `get_my_profile` | Your consultant profile (specialty, leverage stats). Self-orient at session start. |
+| `upload_code_graph` | Push a code-graph for a repo. |
+
+Note: the central `xma.client` registry itself is just data on beesmart — read/manage it with a
+plain (no-`target_client`) `execute_orm` / `search_read` on model `xma.client`.
+
+## Cross-cutting quirks
+
+- **Service user, not admin.** Client-routed calls run as the client's `service_user_id`
+  (a non-admin). Record rules apply. If a write is silently empty, it may be an ACL issue, not
+  a tool failure.
+- **`SUPERUSER_ID` is rejected** for routed tool execution (security). Don't pass `user_id=1`.
+- **Savepoint semantics.** A routed call that raises rolls back its savepoint — partial writes
+  won't persist, which is good, but means you must fix and re-run cleanly.
+- **safe_eval limits** (in `execute_orm`, page `data_code`, endpoint `handler_code`): no
+  `import`, no `hasattr`/`getattr`/`__class__`/`dir`/`del`. Use the pre-imported names. Use
+  `datetime.datetime.now()` (datetime is the module). Test field presence with
+  `'field' in record._fields`, not `hasattr`.
+- **Output ~100KB cap** on `execute_orm` — page large reads.
+- **Version truth is unreliable on the central** for `xma_connect_version` (a known stale-
+  constant bug, plus divergent deployed bundles). To learn a client's REAL `xma_connect`
+  version, route an `execute_orm` reading
+  `env['ir.module.module'].search([('name','=','xma_connect')]).installed_version` to the
+  client — don't trust the central `xma.client.xma_connect_version` field. And because even the
+  real version can mislead (a "5.0.0" without the webapp infra that landed at 4.0.0), gate
+  feature availability on **probing the actual model/capability**, not on the version string.