nexo-brain 7.30.18 → 7.30.20

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.30.18",
+  "version": "7.30.20",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,9 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `7.30.18` is the current packaged-runtime line. Patch release over v7.30.17 - managed email replies now resolve the active assistant identity per account, replacing stale generated signatures without touching custom signatures.
+Version `7.30.20` is the current packaged-runtime line. Patch release over v7.30.19 - packaged installs now copy the `product_knowledge` package into the installed runtime so `nexo update` can import the new product knowledge tools.
 
-Previously in `7.30.17`: patch release over v7.30.16 - F0.6 repairs promoted helper imports for personal scripts by adding a core-backed compatibility shim without duplicating the script catalog.
+Previously in `7.30.19`: patch release over v7.30.18 - product capabilities now live in a structured, validated catalog with read-only discovery tools and preserved legacy system-catalog names.
 
 Previously in `7.30.16`: patch release over v7.30.14 - Desktop diagnostics can read embedding migration status without warming models, and the coordinated Desktop update path is covered for bundled model verification and obsolete managed model cleanup.
 

package/bin/nexo-brain.js

@@ -1346,7 +1346,7 @@ function getCoreRuntimeFlatFiles(srcDir = path.join(__dirname, "..", "src")) {
 }
 
 function getCoreRuntimePackages() {
-  return ["db", "cognitive", "doctor", "local_context"];
+  return ["db", "cognitive", "doctor", "local_context", "product_knowledge"];
 }
 
 // Brain contracts — files the NEXO Brain publishes to consumers like

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "7.30.18",
+  "version": "7.30.20",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",

package/src/auto_update.py

@@ -2753,6 +2753,7 @@ def _f06_legacy_shim_map() -> list[tuple[str, Path]]:
         ("hooks", core_root / "hooks"),
         ("rules", core_root / "rules"),
         ("local_context", core_root / "local_context"),
+        ("product_knowledge", core_root / "product_knowledge"),
         ("data", NEXO_HOME / "runtime" / "data"),
         ("logs", NEXO_HOME / "runtime" / "logs"),
         ("operations", NEXO_HOME / "runtime" / "operations"),
@@ -2822,6 +2823,7 @@ def _f06_live_legacy_paths() -> list[Path]:
             "hooks",
             "rules",
             "local_context",
+            "product_knowledge",
             "db",
             "dashboard",
             "skills-core",
@@ -2907,6 +2909,7 @@ def _promote_packaged_runtime_code_to_core() -> None:
         ("doctor", core_root / "doctor"),
         ("dashboard", core_root / "dashboard"),
         ("local_context", core_root / "local_context"),
+        ("product_knowledge", core_root / "product_knowledge"),
         ("skills-core", core_root / "skills"),
     ]
 
@@ -4740,6 +4743,7 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
         "cognitive",
         "dashboard",
         "local_context",
+        "product_knowledge",
         "rules",
         "crons",
         "scripts",
@@ -4819,7 +4823,18 @@ def _restore_runtime_tree(backup_dir: str, dest: Path = NEXO_HOME) -> None:
 def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_HOME, progress_fn=None) -> dict:
     import shutil
 
-    packages = ["db", "cognitive", "doctor", "local_context", "dashboard", "rules", "crons", "hooks", "presets"]
+    packages = [
+        "db",
+        "cognitive",
+        "doctor",
+        "local_context",
+        "product_knowledge",
+        "dashboard",
+        "rules",
+        "crons",
+        "hooks",
+        "presets",
+    ]
     flat_files = _runtime_flat_files(src_dir)
     copied_packages = 0
     copied_files = 0

package/src/plugins/update.py

@@ -1104,6 +1104,7 @@ def _backup_code_tree() -> tuple[str | None, str | None]:
         "cognitive",
         "dashboard",
         "local_context",
+        "product_knowledge",
         "rules",
         "crons",
         "scripts",

package/src/product_knowledge/__init__.py

@@ -0,0 +1,28 @@
+"""Structured NEXO product knowledge.
+
+The catalog in this package is intentionally small, schema-checked and
+source-linked. It complements the live system catalog; it is not a replacement
+for live backend state.
+"""
+
+from .catalog import (
+    answer_product_question,
+    catalog_entries_for_system_catalog,
+    explain_capability,
+    find_capabilities,
+    list_capabilities,
+    load_product_catalog,
+    surface_status,
+    validate_catalog,
+)
+
+__all__ = [
+    "answer_product_question",
+    "catalog_entries_for_system_catalog",
+    "explain_capability",
+    "find_capabilities",
+    "list_capabilities",
+    "load_product_catalog",
+    "surface_status",
+    "validate_catalog",
+]

package/src/product_knowledge/catalog.json

@@ -0,0 +1,358 @@
+{
+  "schema_version": 1,
+  "updated_at": "2026-06-06",
+  "source_policy": "Brain owns stable product semantics. Desktop manifests describe installed UI surfaces. Backend endpoints own live state, prices, balances, tickets and provisioning.",
+  "capabilities": [
+    {
+      "id": "nexo_product_self_knowledge",
+      "title": "Product Self-Knowledge",
+      "category": "product",
+      "layer": "brain",
+      "status": "live",
+      "summary": "NEXO can answer what its own runtime, tools, scripts, projects and supported workflows are by using structured local catalog sources.",
+      "aliases": ["system catalog", "tool explain", "self knowledge", "product map", "capabilities"],
+      "source_refs": [
+        "nexo/src/system_catalog.py",
+        "nexo/src/tools_system_catalog.py",
+        "nexo/src/server.py:nexo_system_catalog",
+        "nexo/src/server.py:nexo_tool_explain"
+      ],
+      "surfaces": ["Brain MCP tools", "Desktop conversation bootstrap"],
+      "live_state": {
+        "source": "local generated system catalog",
+        "max_age": "per tool call",
+        "fallback": "Answer only from this catalog and source_refs; do not guess unsupported capabilities."
+      },
+      "actions": {
+        "read": ["Search catalog sections", "Explain a tool or product capability"],
+        "write": []
+      },
+      "safety": {
+        "data_touched": ["tool descriptors", "local project atlas metadata", "script registry metadata"],
+        "data_origin": "local runtime metadata",
+        "consent_required": "no for read-only lookup",
+        "confirmation_required": "never for read-only lookup",
+        "credential_policy": "Do not expose credentials or secret values.",
+        "retention": "No new user data is stored by read-only lookup.",
+        "audit": "Tool calls are covered by the standard NEXO session/tool logs.",
+        "forbidden_actions": ["Invent unsupported product features", "Treat static docs as live backend state"]
+      },
+      "answer_guidance": {
+        "must_say": ["Use the live catalog first when available.", "Mark uncertain or missing capabilities as unknown."],
+        "must_not_say": ["Do not claim runtime parity that is not in the catalog."]
+      }
+    },
+    {
+      "id": "nexo_desktop_settings",
+      "title": "Desktop Preferences And Managed Settings",
+      "category": "desktop",
+      "layer": "desktop",
+      "status": "live",
+      "summary": "NEXO Desktop exposes non-technical settings through the Settings UI and a structured preference catalog.",
+      "aliases": ["preferences", "settings", "configuracion", "configuración", "settings catalog"],
+      "source_refs": [
+        "nexo-desktop/lib/settings-schema.js",
+        "nexo-desktop/lib/settings-preference-catalog.js",
+        "nexo-desktop/lib/app-settings-ipc.js",
+        "nexo-desktop/renderer/react/panels/Settings/SettingsShell.jsx"
+      ],
+      "surfaces": ["Desktop Settings", "settings-catalog IPC", "settings-preference-get IPC", "settings-preference-set IPC"],
+      "live_state": {
+        "source": "Desktop app settings + Brain calibration/profile files",
+        "max_age": "per IPC read",
+        "fallback": "Tell the user the setting exists only if present in the generated Desktop manifest."
+      },
+      "actions": {
+        "read": ["List preferences", "Read one preference"],
+        "write": ["Set one supported preference through settings-preference-set"]
+      },
+      "safety": {
+        "data_touched": ["Desktop settings", "Brain calibration", "Brain profile"],
+        "data_origin": "local user profile and Desktop app state",
+        "consent_required": "yes before changing preferences that affect behavior",
+        "confirmation_required": "yes for destructive, account, billing, permission or automation changes",
+        "credential_policy": "Never ask for passwords in chat; use Desktop connection flows or credential tools.",
+        "retention": "Settings persist in local app settings and Brain profile/calibration files.",
+        "audit": "Preference changes must pass through settings-save/settings-preference-set and standard logs.",
+        "forbidden_actions": ["Apply side effects from raw UI onChange", "Bypass Desktop Settings for normal users"]
+      },
+      "answer_guidance": {
+        "must_say": ["Guide non-technical users through Desktop Settings first."],
+        "must_not_say": ["Do not tell users to edit JSON files for normal preference changes."]
+      }
+    },
+    {
+      "id": "nexo_local_memory",
+      "title": "Local Memory And Local File Index",
+      "category": "memory",
+      "layer": "brain+desktop",
+      "status": "live",
+      "summary": "NEXO can index approved local folders for local retrieval while preserving exclusions, retention limits and diagnostics.",
+      "aliases": ["local memory", "index", "local index", "memoria local", "files"],
+      "source_refs": [
+        "nexo/src/server.py:nexo_local_index_status",
+        "nexo/src/server.py:nexo_local_index_roots",
+        "nexo/src/server.py:nexo_local_index_exclusions",
+        "nexo-desktop/renderer/react/panels/Settings/tabs/LocalMemoryTab.jsx"
+      ],
+      "surfaces": ["Desktop Local Memory settings", "Brain local index MCP tools"],
+      "live_state": {
+        "source": "local index service status and indexed roots",
+        "max_age": "per tool call",
+        "fallback": "If status is unavailable, describe only the configured design and ask to inspect diagnostics."
+      },
+      "actions": {
+        "read": ["Read index status", "List roots", "List exclusions"],
+        "write": ["Add/remove roots", "Add/remove exclusions", "Clear local index after confirmation"]
+      },
+      "safety": {
+        "data_touched": ["local file metadata", "text snippets from approved roots", "index diagnostics"],
+        "data_origin": "operator-approved local folders",
+        "consent_required": "yes before adding roots or clearing indexed data",
+        "confirmation_required": "yes for clear-index, purge, broad roots and sensitive folders",
+        "credential_policy": "Do not index credential files; keep secret patterns excluded.",
+        "retention": "Must follow local retention and disk growth limits.",
+        "audit": "Root/exclusion changes and purge operations must be logged.",
+        "forbidden_actions": ["Index home directory broadly without review", "Ignore exclusion rules", "Claim cloud upload for local-only index"]
+      },
+      "answer_guidance": {
+        "must_say": ["Local memory is local-first and controlled from Desktop settings."],
+        "must_not_say": ["Do not imply all user files are indexed by default."]
+      }
+    },
+    {
+      "id": "nexo_agent_email",
+      "title": "Managed Agent Email",
+      "category": "email",
+      "layer": "desktop+backend",
+      "status": "live",
+      "summary": "NEXO can use a managed IMAP/SMTP agent mailbox when the account exists, is configured and the user has enabled email automation.",
+      "aliases": ["email", "mailbox", "imap", "smtp", "agent mailbox", "managed mailbox"],
+      "source_refs": [
+        "nexo/src/system_catalog.py:nexo_email_managed_agent_mailbox",
+        "nexo-desktop/lib/email-automation-runtime.js",
+        "nexo-desktop/renderer/react/panels/Settings/tabs/EmailTab.jsx",
+        "nexo-desktop-web NexoEmailController"
+      ],
+      "surfaces": ["Desktop Email settings", "Backend NEXO Email API", "email-monitor automation"],
+      "live_state": {
+        "source": "Desktop settings + backend NEXO Email API + local automation supervisor",
+        "max_age": "per lookup",
+        "fallback": "If not configured, explain the setup route without inventing credentials."
+      },
+      "actions": {
+        "read": ["Check mailbox configuration", "Check automation readiness"],
+        "write": ["Configure managed mailbox", "Send email only with explicit authorization and account readiness"]
+      },
+      "safety": {
+        "data_touched": ["email addresses", "message metadata", "message bodies when processing email"],
+        "data_origin": "managed mailbox and local email monitor",
+        "consent_required": "yes before enabling monitoring or sending email",
+        "confirmation_required": "yes before sending external email or changing account settings",
+        "credential_policy": "Never request or reveal mailbox passwords in chat; use managed account connection flows.",
+        "retention": "Email processing follows local logs and mailbox retention; avoid storing full message bodies unnecessarily.",
+        "audit": "Sent email and monitor actions require verifiable logs.",
+        "forbidden_actions": ["Send email without current user authorization", "Use private followups as support tickets", "Expose SMTP/IMAP secrets"]
+      },
+      "answer_guidance": {
+        "must_say": ["Email works only when the mailbox is configured and enabled."],
+        "must_not_say": ["Do not promise sending if readiness was not checked."]
+      }
+    },
+    {
+      "id": "nexo_product_automations",
+      "title": "Product Automations",
+      "category": "automation",
+      "layer": "brain+desktop",
+      "status": "live",
+      "summary": "NEXO ships managed automations for email monitoring, followups and morning briefings; Desktop exposes safe controls for product automations.",
+      "aliases": ["automations", "email-monitor", "followup-runner", "morning-agent", "morning-digest"],
+      "source_refs": [
+        "nexo-desktop/renderer/react/panels/Settings/tabs/automationTabHelpers.js",
+        "nexo/src/server.py:nexo_automation_supervisor",
+        "nexo/src/server.py:nexo_automation_reconcile"
+      ],
+      "surfaces": ["Desktop Automations settings", "Brain automation supervisor"],
+      "live_state": {
+        "source": "automation supervisor + Desktop automation catalog",
+        "max_age": "per supervisor read",
+        "fallback": "Describe packaged automation categories, not individual running status."
+      },
+      "actions": {
+        "read": ["List automations", "Read schedule and health"],
+        "write": ["Enable/disable supported automations", "Change supported cadence or extra instructions"]
+      },
+      "safety": {
+        "data_touched": ["automation schedule", "automation logs", "email and followup metadata"],
+        "data_origin": "local automation runtime",
+        "consent_required": "yes before enabling/disabling or changing cadence",
+        "confirmation_required": "yes for changes that send email, notify users or alter recurring work",
+        "credential_policy": "Automations must use configured managed credentials; no secrets in chat.",
+        "retention": "Automation logs follow runtime log retention.",
+        "audit": "Automation changes and runs must be traceable.",
+        "forbidden_actions": ["Expose technical RSS/feed setup to normal users for Morning Digest", "Claim an automation is running without checking health"]
+      },
+      "answer_guidance": {
+        "must_say": ["Morning Digest is a managed briefing automation, not a raw feed configuration surface."],
+        "must_not_say": ["Do not say there are only three automations if the Desktop manifest reports four product automation identifiers."]
+      }
+    },
+    {
+      "id": "nexo_support_tickets_api",
+      "title": "Support Tickets",
+      "category": "support",
+      "layer": "desktop+backend",
+      "status": "live",
+      "summary": "Product bugs, setup failures and customer support reports belong in the backend support ticket system.",
+      "aliases": ["support", "tickets", "bug report", "soporte"],
+      "source_refs": [
+        "nexo/src/system_catalog.py:nexo_support_tickets_api",
+        "nexo/src/server.py:nexo_support_ticket_list",
+        "nexo/src/server.py:nexo_support_ticket_create",
+        "nexo-desktop/renderer/react/panels/Settings/tabs/SupportTab.jsx",
+        "nexo-desktop-web routes/web.php"
+      ],
+      "surfaces": ["Desktop Support settings", "Brain support-ticket tools", "Backend support API"],
+      "live_state": {
+        "source": "backend support API",
+        "max_age": "per API call",
+        "fallback": "Create a local draft only if backend is unavailable; do not treat reminders as real tickets."
+      },
+      "actions": {
+        "read": ["List/read tickets"],
+        "write": ["Create ticket", "Reply to ticket", "Close/reopen ticket"]
+      },
+      "safety": {
+        "data_touched": ["support subject", "support messages", "diagnostic attachments when user approves"],
+        "data_origin": "user report and Desktop diagnostics",
+        "consent_required": "yes before sending diagnostics or personal data to support",
+        "confirmation_required": "yes before creating external support tickets with attachments",
+        "credential_policy": "Use authenticated Desktop/backend session; do not ask for backend tokens in chat.",
+        "retention": "Backend support retention applies; diagnostic bundles must be minimized and redacted.",
+        "audit": "Ticket IDs and API results are the evidence of support actions.",
+        "forbidden_actions": ["Use private reminders/followups instead of support tickets", "Attach logs without permission"]
+      },
+      "answer_guidance": {
+        "must_say": ["Real product reports should be filed as support tickets."],
+        "must_not_say": ["Do not say a ticket was created without ticket ID evidence."]
+      }
+    },
+    {
+      "id": "nexo_credits_provider_proxy",
+      "title": "NEXO Credits Provider Proxy",
+      "category": "credits",
+      "layer": "backend+desktop",
+      "status": "live",
+      "summary": "NEXO Credits routes billable provider calls through backend policy, estimation, reservation and reconciliation.",
+      "aliases": ["credits", "provider proxy", "models", "openrouter", "heygen", "billing"],
+      "source_refs": [
+        "nexo/src/system_catalog.py:nexo_provider_proxy",
+        "nexo/src/system_catalog.py:nexo_provider_models",
+        "nexo-desktop/renderer/react/panels/Settings/tabs/SubscriptionsTab.jsx",
+        "nexo-desktop-web ProviderProxyController",
+        "nexo-desktop-web ProviderCatalogService"
+      ],
+      "surfaces": ["Desktop Subscriptions/Credits", "Backend provider-proxy API"],
+      "live_state": {
+        "source": "backend provider-proxy platforms/models/estimate endpoints",
+        "max_age": "per backend call",
+        "fallback": "Mark provider/model support as unknown or planned if not returned by backend."
+      },
+      "actions": {
+        "read": ["List platforms", "List models", "Estimate cost", "Read request status"],
+        "write": ["Reserve credits", "Execute provider call after explicit user intent"]
+      },
+      "safety": {
+        "data_touched": ["billing account", "credits balance", "provider request payload", "provider request result"],
+        "data_origin": "backend account and provider APIs",
+        "consent_required": "yes before spending credits or sending payloads to providers",
+        "confirmation_required": "yes before billable provider calls or top-ups",
+        "credential_policy": "Provider credentials live in backend credential storage; never reveal them.",
+        "retention": "Provider request records and ledger retention follow backend policy.",
+        "audit": "Credit reservation, ledger and provider request IDs are required evidence.",
+        "forbidden_actions": ["Hardcode prices or balances", "Promise video/model invocation unless backend marks it invokable", "Spend credits silently"]
+      },
+      "answer_guidance": {
+        "must_say": ["Balances, prices and invokable models are live backend facts."],
+        "must_not_say": ["Do not infer provider availability from marketing copy."]
+      }
+    },
+    {
+      "id": "nexo_managed_cloud_edge",
+      "title": "Managed Cloud And Edge",
+      "category": "cloud",
+      "layer": "backend+desktop",
+      "status": "planned_live",
+      "summary": "NEXO can list and provision managed cloud/edge resources through NEXO Credits when backend routes and spend controls are available.",
+      "aliases": ["nexo cloud", "nexo edge", "cloudflare", "gcloud", "managed infrastructure", "domains"],
+      "source_refs": [
+        "nexo/src/system_catalog.py:nexo_credits_cloud",
+        "nexo/src/system_catalog.py:nexo_edge_cloudflare",
+        "nexo-desktop-web NexoCloudController",
+        "nexo-desktop-web NexoEdgeController"
+      ],
+      "surfaces": ["Backend NEXO Cloud API", "Backend NEXO Edge API", "future Desktop managed infrastructure UI"],
+      "live_state": {
+        "source": "backend cloud/edge APIs",
+        "max_age": "per backend call",
+        "fallback": "Listing can be described as safe discovery; provisioning remains billable and must not be promised without route confirmation."
+      },
+      "actions": {
+        "read": ["List projects", "List sites", "List deployments", "List edge assets"],
+        "write": ["Provision project/site", "Register/check domain", "Create DNS/redirect/job after approval"]
+      },
+      "safety": {
+        "data_touched": ["cloud project metadata", "domain names", "DNS records", "deployment metadata", "billing/credits"],
+        "data_origin": "backend managed infrastructure and third-party cloud APIs",
+        "consent_required": "yes before provisioning or changing infrastructure",
+        "confirmation_required": "yes before billable, public or DNS-changing operations",
+        "credential_policy": "Cloud provider credentials are backend-managed; do not expose tokens.",
+        "retention": "Backend resource and job retention applies.",
+        "audit": "Provisioning/job IDs and credit ledger entries are required evidence.",
+        "forbidden_actions": ["Register domains without explicit approval", "Change DNS silently", "State a server/route/IP without verification"]
+      },
+      "answer_guidance": {
+        "must_say": ["Listing existing managed infrastructure is safe; creation is billable and approval-gated."],
+        "must_not_say": ["Do not claim a domain/server exists without live verification."]
+      }
+    },
+    {
+      "id": "nexo_protocol_cards",
+      "title": "Protocol Cards",
+      "category": "workflow",
+      "layer": "backend+brain+desktop",
+      "status": "live",
+      "summary": "Official workflow cards are served by backend and matched by Brain when available, so product procedures can evolve without hardcoded prompts.",
+      "aliases": ["cards", "protocol cards", "workflow cards", "procedures"],
+      "source_refs": [
+        "nexo/src/server.py:nexo_card_match",
+        "nexo-desktop-web CardCatalogService",
+        "nexo-desktop/prompts/system/conversation-bootstrap.md"
+      ],
+      "surfaces": ["Brain nexo_card_match", "Backend cards catalog", "Desktop bootstrap"],
+      "live_state": {
+        "source": "backend cards API",
+        "max_age": "per match request",
+        "fallback": "If unauthenticated/unavailable, continue with local product docs and say nothing about internal failure unless operationally relevant."
+      },
+      "actions": {
+        "read": ["Match cards", "Fetch catalog", "Fetch card"],
+        "write": ["Activate card when backend supports it and user context requires it"]
+      },
+      "safety": {
+        "data_touched": ["workflow metadata", "business type/category", "authenticated backend session"],
+        "data_origin": "backend card catalog",
+        "consent_required": "no for read-only matching",
+        "confirmation_required": "depends on actions inside the matched card",
+        "credential_policy": "Use existing authenticated Desktop/backend session; do not expose tokens.",
+        "retention": "Backend/API logging policy applies.",
+        "audit": "Card match/use is captured by runtime task evidence when relevant.",
+        "forbidden_actions": ["Invent official protocols", "Expose internal card fetch failures as user-facing noise"]
+      },
+      "answer_guidance": {
+        "must_say": ["Follow official cards silently when available."],
+        "must_not_say": ["Do not present backend-auth failures as product limitations."]
+      }
+    }
+  ]
+}

package/src/product_knowledge/catalog.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+CATALOG_PATH = Path(__file__).with_name("catalog.json")
+LEGACY_SYSTEM_CATALOG_NAMES = {
+    "nexo_agent_email": [
+        ("nexo_email_managed_agent_mailbox", "Email NEXO Managed Agent Mailbox"),
+    ],
+    "nexo_credits_provider_proxy": [
+        ("nexo_provider_proxy", "NEXO Credits Provider Proxy"),
+        ("nexo_provider_models", "Provider Model Discovery"),
+    ],
+    "nexo_managed_cloud_edge": [
+        ("nexo_credits_cloud", "NEXO Credits Managed Cloud"),
+        ("nexo_edge_cloudflare", "NEXO Edge Cloudflare"),
+    ],
+}
+
+REQUIRED_CAPABILITY_FIELDS = {
+    "id",
+    "title",
+    "category",
+    "layer",
+    "status",
+    "summary",
+    "aliases",
+    "source_refs",
+    "surfaces",
+    "live_state",
+    "actions",
+    "safety",
+    "answer_guidance",
+}
+REQUIRED_LIVE_STATE_FIELDS = {"source", "max_age", "fallback"}
+REQUIRED_ACTION_FIELDS = {"read", "write"}
+REQUIRED_SAFETY_FIELDS = {
+    "data_touched",
+    "data_origin",
+    "consent_required",
+    "confirmation_required",
+    "credential_policy",
+    "retention",
+    "audit",
+    "forbidden_actions",
+}
+REQUIRED_GUIDANCE_FIELDS = {"must_say", "must_not_say"}
+
+
+def _normalize(text: Any) -> str:
+    return str(text or "").strip().lower()
+
+
+def _tokens(text: Any) -> set[str]:
+    return {
+        token
+        for token in re.findall(r"[a-z0-9][a-z0-9._:-]{1,}", _normalize(text))
+        if len(token) >= 2
+    }
+
+
+def _haystack(capability: dict[str, Any]) -> str:
+    return " ".join(
+        [
+            str(capability.get("id", "")),
+            str(capability.get("title", "")),
+            str(capability.get("category", "")),
+            str(capability.get("layer", "")),
+            str(capability.get("status", "")),
+            str(capability.get("summary", "")),
+            " ".join(str(item) for item in capability.get("aliases") or []),
+            " ".join(str(item) for item in capability.get("source_refs") or []),
+            " ".join(str(item) for item in capability.get("surfaces") or []),
+        ]
+    )
+
+
+def _score(query: str, capability: dict[str, Any]) -> float:
+    query_tokens = _tokens(query)
+    if not query_tokens:
+        return 1.0
+    haystack_tokens = _tokens(_haystack(capability))
+    overlap = query_tokens & haystack_tokens
+    if not overlap:
+        return 0.0
+    exact_bonus = 0.25 if _normalize(query) in _normalize(_haystack(capability)) else 0.0
+    return len(overlap) / max(1, len(query_tokens)) + exact_bonus
+
+
+@lru_cache(maxsize=1)
+def load_product_catalog() -> dict[str, Any]:
+    payload = json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+    errors = validate_catalog(payload)
+    if errors:
+        raise ValueError("Invalid product knowledge catalog:\n- " + "\n- ".join(errors))
+    return payload
+
+
+def validate_catalog(catalog: dict[str, Any] | None = None) -> list[str]:
+    payload = catalog if catalog is not None else json.loads(CATALOG_PATH.read_text(encoding="utf-8"))
+    errors: list[str] = []
+    if not isinstance(payload, dict):
+        return ["catalog must be a JSON object"]
+    if payload.get("schema_version") != 1:
+        errors.append("schema_version must be 1")
+    capabilities = payload.get("capabilities")
+    if not isinstance(capabilities, list) or not capabilities:
+        errors.append("capabilities must be a non-empty list")
+        return errors
+    seen: set[str] = set()
+    for index, capability in enumerate(capabilities):
+        prefix = f"capabilities[{index}]"
+        if not isinstance(capability, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        missing = sorted(REQUIRED_CAPABILITY_FIELDS - capability.keys())
+        if missing:
+            errors.append(f"{prefix} missing fields: {', '.join(missing)}")
+        cap_id = str(capability.get("id", "")).strip()
+        if not re.match(r"^[a-z0-9][a-z0-9_:-]{2,}$", cap_id):
+            errors.append(f"{prefix}.id is invalid")
+        if cap_id in seen:
+            errors.append(f"{prefix}.id duplicates {cap_id}")
+        seen.add(cap_id)
+        for field in ("aliases", "source_refs", "surfaces"):
+            if not isinstance(capability.get(field), list) or not capability.get(field):
+                errors.append(f"{prefix}.{field} must be a non-empty list")
+        live_state = capability.get("live_state") or {}
+        if not isinstance(live_state, dict):
+            errors.append(f"{prefix}.live_state must be an object")
+        else:
+            missing_live = sorted(REQUIRED_LIVE_STATE_FIELDS - live_state.keys())
+            if missing_live:
+                errors.append(f"{prefix}.live_state missing fields: {', '.join(missing_live)}")
+        actions = capability.get("actions") or {}
+        if not isinstance(actions, dict):
+            errors.append(f"{prefix}.actions must be an object")
+        else:
+            missing_actions = sorted(REQUIRED_ACTION_FIELDS - actions.keys())
+            if missing_actions:
+                errors.append(f"{prefix}.actions missing fields: {', '.join(missing_actions)}")
+            for action_field in REQUIRED_ACTION_FIELDS:
+                if not isinstance(actions.get(action_field), list):
+                    errors.append(f"{prefix}.actions.{action_field} must be a list")
+        safety = capability.get("safety") or {}
+        if not isinstance(safety, dict):
+            errors.append(f"{prefix}.safety must be an object")
+        else:
+            missing_safety = sorted(REQUIRED_SAFETY_FIELDS - safety.keys())
+            if missing_safety:
+                errors.append(f"{prefix}.safety missing fields: {', '.join(missing_safety)}")
+            for list_field in ("data_touched", "forbidden_actions"):
+                if not isinstance(safety.get(list_field), list) or not safety.get(list_field):
+                    errors.append(f"{prefix}.safety.{list_field} must be a non-empty list")
+        guidance = capability.get("answer_guidance") or {}
+        if not isinstance(guidance, dict):
+            errors.append(f"{prefix}.answer_guidance must be an object")
+        else:
+            missing_guidance = sorted(REQUIRED_GUIDANCE_FIELDS - guidance.keys())
+            if missing_guidance:
+                errors.append(f"{prefix}.answer_guidance missing fields: {', '.join(missing_guidance)}")
+            for list_field in REQUIRED_GUIDANCE_FIELDS:
+                if not isinstance(guidance.get(list_field), list):
+                    errors.append(f"{prefix}.answer_guidance.{list_field} must be a list")
+    return errors
+
+
+def list_capabilities() -> list[dict[str, Any]]:
+    return list(load_product_catalog().get("capabilities") or [])
+
+
+def find_capabilities(
+    query: str = "",
+    *,
+    category: str = "",
+    status: str = "",
+    limit: int = 20,
+) -> list[dict[str, Any]]:
+    category_clean = _normalize(category)
+    status_clean = _normalize(status)
+    rows: list[tuple[float, dict[str, Any]]] = []
+    for capability in list_capabilities():
+        if category_clean and _normalize(capability.get("category")) != category_clean:
+            continue
+        if status_clean and _normalize(capability.get("status")) != status_clean:
+            continue
+        score = _score(query, capability)
+        if query and score <= 0:
+            continue
+        rows.append((score, capability))
+    rows.sort(key=lambda item: (item[0], item[1].get("id", "")), reverse=True)
+    return [dict(row) for _, row in rows[: max(1, int(limit or 20))]]
+
+
+def explain_capability(capability_id: str = "", *, query: str = "") -> dict[str, Any] | None:
+    target = _normalize(capability_id)
+    if target:
+        for capability in list_capabilities():
+            keys = [
+                capability.get("id"),
+                capability.get("title"),
+                *(capability.get("aliases") or []),
+            ]
+            if target in {_normalize(key) for key in keys}:
+                return dict(capability)
+    matches = find_capabilities(query or capability_id, limit=1)
+    return matches[0] if matches else None
+
+
+def catalog_entries_for_system_catalog() -> list[dict[str, Any]]:
+    entries = []
+    for capability in list_capabilities():
+        base_entry = {
+            "kind": "product_capability",
+            "name": capability["id"],
+            "display_name": capability["title"],
+            "category": capability["category"],
+            "layer": capability["layer"],
+            "status": capability["status"],
+            "description": capability["summary"],
+            "source": ", ".join(capability.get("source_refs") or []),
+            "surfaces": capability.get("surfaces") or [],
+            "aliases": capability.get("aliases") or [],
+            "live_state": capability.get("live_state") or {},
+            "safety": capability.get("safety") or {},
+            "answer_guidance": capability.get("answer_guidance") or {},
+        }
+        entries.append(base_entry)
+        for legacy_name, legacy_display in LEGACY_SYSTEM_CATALOG_NAMES.get(capability["id"], []):
+            legacy_entry = dict(base_entry)
+            legacy_entry["name"] = legacy_name
+            legacy_entry["display_name"] = legacy_display
+            legacy_entry["canonical_capability_id"] = capability["id"]
+            entries.append(legacy_entry)
+    return entries
+
+
+def answer_product_question(question: str, *, locale: str = "es", limit: int = 5) -> str:
+    matches = find_capabilities(question, limit=limit)
+    if not matches:
+        return "No encuentro esa capacidad en el catálogo de producto. La respuesta segura es marcarla como no verificada hasta consultar la fuente viva."
+    lines = ["Respuesta basada en el catálogo de producto NEXO:"]
+    for capability in matches:
+        lines.append(f"- {capability['title']}: {capability['summary']}")
+        live_state = capability.get("live_state") or {}
+        if live_state.get("source"):
+            lines.append(f"  Fuente viva: {live_state['source']}.")
+        safety = capability.get("safety") or {}
+        if safety.get("confirmation_required"):
+            lines.append(f"  Confirmación: {safety['confirmation_required']}.")
+    lines.append("Regla: precios, saldos, proveedores invocables, tickets e infraestructura se verifican en backend o runtime vivo antes de prometerlos.")
+    return "\n".join(lines)
+
+
+def surface_status(surface: str = "", *, limit: int = 50) -> dict[str, Any]:
+    needle = _normalize(surface)
+    capabilities = []
+    for capability in list_capabilities():
+        surfaces = capability.get("surfaces") or []
+        if needle and not any(needle in _normalize(item) for item in surfaces):
+            continue
+        capabilities.append(
+            {
+                "id": capability["id"],
+                "title": capability["title"],
+                "category": capability["category"],
+                "status": capability["status"],
+                "surfaces": surfaces,
+                "live_state_source": (capability.get("live_state") or {}).get("source", ""),
+            }
+        )
+    return {
+        "ok": True,
+        "schema_version": load_product_catalog().get("schema_version"),
+        "count": len(capabilities[: max(1, int(limit or 50))]),
+        "capabilities": capabilities[: max(1, int(limit or 50))],
+    }

package/src/server.py

@@ -57,6 +57,13 @@ from tools_system_catalog import (
     handle_system_catalog,
     handle_tool_explain,
 )
+from tools_product_knowledge import (
+    handle_capability_explain,
+    handle_product_answer,
+    handle_product_capabilities,
+    handle_product_knowledge_validate,
+    handle_product_surface_status,
+)
 from tools_drive import (
     handle_drive_signals,
     handle_drive_reinforce,
@@ -1692,6 +1699,36 @@ def nexo_tool_explain(name: str) -> str:
     return handle_tool_explain(name)
 
 
+@mcp.tool
+def nexo_product_capabilities(query: str = "", category: str = "", status: str = "", limit: int = 20) -> str:
+    """Search the structured NEXO product capability catalog."""
+    return handle_product_capabilities(query, category, status, limit)
+
+
+@mcp.tool
+def nexo_capability_explain(capability_id: str = "", query: str = "", locale: str = "es") -> str:
+    """Explain one NEXO product capability with source and safety context."""
+    return handle_capability_explain(capability_id, query, locale)
+
+
+@mcp.tool
+def nexo_product_answer(question: str, locale: str = "es", limit: int = 5) -> str:
+    """Answer a NEXO product question using the structured product catalog."""
+    return handle_product_answer(question, locale, limit)
+
+
+@mcp.tool
+def nexo_product_surface_status(surface: str = "", limit: int = 50) -> str:
+    """Show which NEXO product capabilities are exposed by a product surface."""
+    return handle_product_surface_status(surface, limit)
+
+
+@mcp.tool
+def nexo_product_knowledge_validate() -> str:
+    """Validate the structured NEXO product knowledge catalog."""
+    return handle_product_knowledge_validate()
+
+
 @mcp.tool
 def nexo_guardian_rule_override(rule_id: str, mode: str = "", ttl: str = "24h") -> str:
     """Temporarily override a Guardian rule's mode (Plan Consolidado 0.17).

package/src/system_catalog.py

@@ -614,13 +614,20 @@ def _artifact_entries() -> list[dict]:
 
 
 def _product_capability_entries() -> list[dict]:
-    """Static product contract map for agent self-discovery.
+    """Product contract map for agent self-discovery.
 
-    These entries are intentionally endpoint-level rather than marketing
-    copy. They let a fresh agent find the real backend surfaces before
-    guessing unsupported workflows.
+    The structured catalog is the primary source. The fallback below keeps
+    ``nexo_system_catalog`` alive if the product-knowledge package has a
+    syntax error during development.
     """
 
+    try:
+        from product_knowledge import catalog_entries_for_system_catalog
+
+        return catalog_entries_for_system_catalog()
+    except Exception:
+        pass
+
     return [
         {
             "kind": "product_capability",

package/src/tools_product_knowledge.py

@@ -0,0 +1,59 @@
+"""MCP handlers for structured NEXO product knowledge."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from product_knowledge import (
+    answer_product_question,
+    explain_capability,
+    find_capabilities,
+    list_capabilities,
+    surface_status,
+    validate_catalog,
+)
+
+
+def _json(payload: Any) -> str:
+    return json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True)
+
+
+def handle_product_capabilities(
+    query: str = "",
+    category: str = "",
+    status: str = "",
+    limit: int = 20,
+) -> str:
+    """Return structured product capabilities from the NEXO catalog."""
+    capabilities = find_capabilities(query, category=category, status=status, limit=limit)
+    return _json({"ok": True, "count": len(capabilities), "capabilities": capabilities})
+
+
+def handle_capability_explain(capability_id: str = "", query: str = "", locale: str = "es") -> str:
+    """Explain one product capability with safety and source context."""
+    capability = explain_capability(capability_id, query=query)
+    if not capability:
+        return _json({"ok": False, "error": "capability-not-found"})
+    return _json({"ok": True, "capability": capability})
+
+
+def handle_product_answer(question: str, locale: str = "es", limit: int = 5) -> str:
+    """Answer a NEXO product question using only the structured product catalog."""
+    return answer_product_question(question, locale=locale, limit=limit)
+
+
+def handle_product_surface_status(surface: str = "", limit: int = 50) -> str:
+    """Return which product capabilities are exposed by a surface."""
+    return _json(surface_status(surface, limit=limit))
+
+
+def handle_product_knowledge_validate() -> str:
+    """Validate the product knowledge catalog."""
+    try:
+        errors = validate_catalog()
+        capability_count = 0 if errors else len(list_capabilities())
+    except Exception as exc:
+        errors = [str(exc)]
+        capability_count = 0
+    return _json({"ok": not errors, "errors": errors, "capability_count": capability_count})

package/tool-enforcement-map.json

@@ -693,6 +693,21 @@
       },
       "triggers_after": []
     },
+    "nexo_capability_explain": {
+      "description": "Explain one NEXO product capability with source and safety context",
+      "category": "product_knowledge",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "product_capability_explanation"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_change_commit": {
       "description": "Link change log entry to git commit",
       "category": "change_log",
@@ -3496,6 +3511,66 @@
       },
       "triggers_after": []
     },
+    "nexo_product_answer": {
+      "description": "Answer a NEXO product question from the structured product catalog",
+      "category": "product_knowledge",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "product_answer"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_product_capabilities": {
+      "description": "Search the structured NEXO product capability catalog",
+      "category": "product_knowledge",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "product_capability_catalog"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_product_knowledge_validate": {
+      "description": "Validate the structured NEXO product knowledge catalog",
+      "category": "product_knowledge",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "product_knowledge_validation"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
+    "nexo_product_surface_status": {
+      "description": "Show which NEXO product capabilities are exposed by a product surface",
+      "category": "product_knowledge",
+      "source": "server",
+      "requires": [],
+      "provides": [
+        "product_surface_status"
+      ],
+      "internal_calls": [],
+      "enforcement": {
+        "level": "none",
+        "rules": []
+      },
+      "triggers_after": []
+    },
     "nexo_recall": {
       "description": "Search across ALL NEXO memory",
       "category": "memory",