marvisx-cli 0.2.2__tar.gz → 0.3.5__tar.gz

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/MANIFEST.in

@@ -9,4 +9,5 @@
 recursive-include migrations *.sql
 recursive-include core/scripts/install_hooks *.sh *.json *.py
 recursive-include core/api/templates *.md *.j2
+recursive-include core/api/mcp/tools/workflow_playbooks *.md
 recursive-include projects/_template *

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.2.2
+Version: 0.3.5
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1
@@ -36,7 +36,6 @@ Requires-Dist: fastapi>=0.115.0
 Requires-Dist: slowapi>=0.1.9
 Requires-Dist: cachetools>=5.3.0
 Requires-Dist: uvicorn[standard]>=0.34.0
-Requires-Dist: uvloop>=0.21.0
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: PyJWT>=2.10.0
 Requires-Dist: bcrypt>=4.2.0

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/README.md

@@ -58,9 +58,9 @@ docker compose up -d
 
 The Console becomes available on the configured `CONSOLE_PORT` and the API on the configured `API_PORT`. Detailed first-run instructions are inside the deployment template.
 
-## Embedding migration from a managed provider
+## Setting up local embeddings
 
-If you currently run MarvisX with a managed embedding provider such as Voyage AI, [`docs/MIGRATION-FROM-VOYAGE.md`](docs/MIGRATION-FROM-VOYAGE.md) covers the step-by-step path to the self-hosted Granite backend, including the re-index, KG threshold recalibration, and rollback procedure.
+[`docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md`](docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md) covers the step-by-step path to the self-hosted Granite backend, including first-boot setup, re-indexing an existing corpus, and KG threshold recalibration.
 
 ## MCP surface
 
@@ -74,14 +74,14 @@ The MCP server runs in-process: it calls the same use_cases the HTTP API calls,
 
 Audit is still recorded: the extracted use_cases write the audit log themselves (`core/api/use_cases/{tasks,pull_requests,audit}.py`), so a mutation issued through MCP still produces an audit row at the use_case level. What is lost is only the additional HTTP-surface chokepoint.
 
-Setting `MARVIS_OSS_LOCAL=1` (truthy: `1`/`true`/`yes`/`on`) makes the `block-db-direct-write` safety rule **advisory** — direct writes to a PiR SQLite database are allowed with a warning instead of being blocked. When the variable is unset or falsey the rule is unchanged: direct DB writes are blocked fail-closed, exactly as in the managed deployment. This trade-off is intentional for single-user self-hosting and never weakens the default.
+Setting `MARVIS_OSS_LOCAL=1` (truthy: `1`/`true`/`yes`/`on`) makes the `block-db-direct-write` safety rule **advisory** — direct writes to a Marvis SQLite database are allowed with a warning instead of being blocked. When the variable is unset or falsey the rule is unchanged: direct DB writes are blocked fail-closed, exactly as in the managed deployment. This trade-off is intentional for single-user self-hosting and never weakens the default.
 
 **No-fork guarantee.** The HTTP API and the MCP server are not two implementations: both are thin adapters over the same `core/api/use_cases`, differing only in how they fill the per-call `CallerContext`. The proof is the API test suite staying green after the extraction — the same behaviour, exercised through the HTTP surface, over the identical use_cases the MCP server calls.
 
 ## Documentation
 
 - [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) — search quality expectations, affected workflows, and mitigations
-- [`docs/MIGRATION-FROM-VOYAGE.md`](docs/MIGRATION-FROM-VOYAGE.md) — migration from managed embeddings to Granite
+- [`docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md`](docs/MIGRATION-TO-LOCAL-EMBEDDINGS.md) — setting up the self-hosted Granite embedding backend
 - [`docs/solutions/architecture-patterns/`](docs/solutions/architecture-patterns/) — architectural decision records
 
 ## Contributing

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/agents/session_manager.py

@@ -38,7 +38,9 @@ async def list_agent_managed_sessions() -> list[SessionInfo]:
     import urllib.request
     from core.api.config import settings as cfg
     token = cfg.tasks_api_token if hasattr(cfg, "tasks_api_token") else os.environ.get("TASKS_API_TOKEN", "")
-    api_base = os.environ.get("PIR_INTERNAL_BASE", "http://localhost:8100")
+    api_base = os.environ.get("MARVIS_INTERNAL_BASE") or os.environ.get(
+        "PIR_INTERNAL_BASE", "http://localhost:8100"
+    )
     try:
         req = urllib.request.Request(
             f"{api_base}/api/v1/sessions?agent_managed=true",

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/config.py

@@ -40,22 +40,38 @@ class Settings(BaseSettings):
         populate_by_name=True,
     )
 
-    pir_env: str = "development"
+    pir_env: str = Field(
+        default="development",
+        validation_alias=AliasChoices("MARVIS_ENV", "PIR_ENV"),
+    )
     # Free-form tenant identifier. Default "core" (OSS). Deploy bundles set
     # DEPLOY_MODE to their own tenant slug via .env; no tenant names are
     # hard-coded in core.
     deploy_mode: str = Field(default="core", alias="DEPLOY_MODE")
-    pir_instance: str = Field(default="prod", alias="PIR_INSTANCE")
+    pir_instance: str = Field(
+        default="prod",
+        validation_alias=AliasChoices("MARVIS_INSTANCE", "PIR_INSTANCE"),
+    )
     marvisx_phase: Literal["A", "B", "C", "D"] = Field(
         default="A", alias="MARVISX_PHASE"
     )
-    pir_canary_banner: bool = Field(default=False, alias="PIR_CANARY_BANNER")
-    pir_voyage_disabled: bool = Field(default=False, alias="PIR_VOYAGE_DISABLED")
-    pir_jwt_secret: str = "dev-secret-change-in-production"
-    pir_admin_password_hash: str = ""
+    pir_canary_banner: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("MARVIS_CANARY_BANNER", "PIR_CANARY_BANNER"),
+    )
+    pir_jwt_secret: str = Field(
+        default="dev-secret-change-in-production",
+        validation_alias=AliasChoices("MARVIS_JWT_SECRET", "PIR_JWT_SECRET"),
+    )
+    pir_admin_password_hash: str = Field(
+        default="",
+        validation_alias=AliasChoices(
+            "MARVIS_ADMIN_PASSWORD_HASH", "PIR_ADMIN_PASSWORD_HASH"
+        ),
+    )
     db_path: str = Field(
         default="console.db",
-        validation_alias=AliasChoices("PIR_DB_PATH", "DB_PATH"),
+        validation_alias=AliasChoices("MARVIS_DB_PATH", "PIR_DB_PATH", "DB_PATH"),
     )
     cookie_domain: str | None = Field(default=None, alias="COOKIE_DOMAIN")
     cors_origins_prod: list[str] = Field(
@@ -83,6 +99,16 @@ class Settings(BaseSettings):
     brain_run_off_peak_only: bool = Field(
         default=False, alias="BRAIN_RUN_OFF_PEAK_ONLY"
     )
+    # Warehouse consolidation pass (full-store learning dedup, ships DORMANT).
+    # Unlike memory_ops M2 (same-cycle only), this scans the WHOLE learnings
+    # warehouse and PROPOSES consolidation of cross-cycle duplicates. Default
+    # FALSE — a human enables it after reviewing. Daily cadence guard.
+    brain_warehouse_consolidation_enabled: bool = Field(
+        default=False, alias="BRAIN_WAREHOUSE_CONSOLIDATION_ENABLED"
+    )
+    brain_warehouse_consolidation_interval_seconds: int = Field(
+        default=86400, alias="BRAIN_WAREHOUSE_CONSOLIDATION_INTERVAL_SECONDS"
+    )
 
     # GitHub Webhook
     github_webhook_secret: str = ""
@@ -401,9 +427,6 @@ class Settings(BaseSettings):
     # WIP limit: max tasks in_progress per project (doc/none tasks count as 0.5)
     wip_max_in_progress: int = 3
 
-    # Voyage AI embeddings
-    voyage_api_key: str = ""
-
     # sqlite-vec: env VEC0_PATH → sqlite_vec.loadable_path() → prod fallback.
     vec0_path: str = Field(
         default_factory=_default_vec0_path,

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/db.py

@@ -740,18 +740,26 @@ def _seed_users_and_migrate_owner(conn: sqlite3.Connection) -> None:
     install seeds no hardcoded name. On an existing deployment this seed is
     skipped (users already exist), so the defaults never affect a running install.
     """
-    # Prefer pre-hashed password (production .env has PIR_ADMIN_PASSWORD_HASH)
-    hashed = os.environ.get("PIR_ADMIN_PASSWORD_HASH", "").strip()
+    # Prefer pre-hashed password. Canonical var is MARVIS_ADMIN_PASSWORD_HASH;
+    # PIR_ADMIN_PASSWORD_HASH stays accepted as a deprecated alias.
+    hashed = (
+        os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
+        or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
+    ).strip()
     if not hashed:
         import bcrypt
 
-        pir_password = os.environ.get("PIR_PASSWORD", "").strip()
-        if not pir_password:
+        seed_password = (
+            os.environ.get("MARVIS_PASSWORD")
+            or os.environ.get("PIR_PASSWORD", "")
+        ).strip()
+        if not seed_password:
             raise RuntimeError(
-                "Migration 016 requires PIR_ADMIN_PASSWORD_HASH or PIR_PASSWORD env var "
-                "to seed the admin user. Set at least one in .env."
+                "Migration 016 requires MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD "
+                "env var (PIR_* aliases still accepted) to seed the admin user. "
+                "Set at least one in .env."
             )
-        hashed = bcrypt.hashpw(pir_password.encode("utf-8"), bcrypt.gensalt()).decode()
+        hashed = bcrypt.hashpw(seed_password.encode("utf-8"), bcrypt.gensalt()).decode()
 
     admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
     admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/main.py

@@ -1,7 +1,7 @@
 # v1.18.0 - 2026-05-22 - P1.5.E1: remove PaddleOCR local (broken warm-up since 30-apr); OCR live via Mac Gateway tier-ocr
 # v1.17.0 - 2026-04-30 - P1.5.E0: add PaddleOCR async warm + /health/ocr backend status
 # v1.16.0 - 2026-04-17 - P2: add slowapi rate limiting middleware for /graph endpoints
-# v1.15.0 - 2026-03-15 - Add push delivery + Voyage init in lifespan + orphan proxy cleanup
+# v1.15.0 - 2026-03-15 - Add push delivery + embedding client init in lifespan + orphan proxy cleanup
 from __future__ import annotations
 
 import asyncio
@@ -986,7 +986,7 @@ async def lifespan(app: FastAPI):
         _pr_impact_gc_task
 
     # Startup
-    logger.info("Starting Console PiR API (env=%s)", settings.pir_env)
+    logger.info("Starting Console Marvis API (env=%s)", settings.pir_env)
     run_migrations()
 
     # Phase 1.5 D14: Phoenix client-side OTel SDK (feature flag — default OFF).
@@ -1109,13 +1109,17 @@ async def lifespan(app: FastAPI):
         _push_delivery_task = asyncio.create_task(_periodic_push_delivery())
         logger.info("Push delivery started (interval=5s)")
 
-    # Voyage AI client for embeddings
-    from core.api.services.embedding_service import init_voyage_client
+    # Embedding backend client (remote backend when present + configured,
+    # else the in-process local engine). The operator kill-switch lives inside
+    # the optional remote backend module, so we ask it rather than config.
+    from core.api.services.embedding_service import init_embedding_client
+    from core.api.services.embedding_backends import load_remote_backend
 
-    if settings.pir_voyage_disabled:
-        logger.info("[canary] skipping Voyage client initialization")
+    _remote = load_remote_backend()
+    if _remote is not None and _remote.is_disabled():
+        logger.info("[canary] skipping remote embedding client initialization")
     else:
-        init_voyage_client()
+        init_embedding_client()
 
     # Monitoring collectors
     await metrics_collector.start()
@@ -1266,7 +1270,7 @@ async def lifespan(app: FastAPI):
 from core.api.rate_limit import limiter  # noqa: E402
 
 app = FastAPI(
-    title="Console PiR API",
+    title="Console Marvis API",
     version="1.0.0",
     docs_url="/docs" if settings.expose_openapi else None,
     redoc_url="/redoc" if settings.expose_openapi else None,
@@ -1477,7 +1481,7 @@ async def _resolve_ws_user(ws: WebSocket):
                 )
         return None
 
-    # 2. Cookie (Console PiR web)
+    # 2. Cookie (Console Marvis web)
     cookie_token = ws.cookies.get("pir_session")
     if not cookie_token:
         return None

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/_adapter.py

@@ -70,7 +70,7 @@ LOCAL_CTX: CallerContext = CallerContext.local_single_user()
 #                           on the running tool loop — no Node, no HTTP, no fork. The
 #                           use_case calls this sync seam un-awaited (side effect),
 #                           so it schedules a background task and returns immediately;
-#                           the embed (incl. the slow model/Voyage call) runs OUTSIDE
+#                           the embed (incl. the slow model/remote backend call) runs OUTSIDE
 #                           any write lock, then writes via the single-writer pool.
 #                           No-ops gracefully when the embedder is unavailable.
 #   * mcp_requires_pr_gate -> returns False locally. The completed-PR gate (code/
@@ -136,6 +136,75 @@ def mcp_schedule_embed(
     t.add_done_callback(_bg_embed_tasks.discard)
 
 
+# Background set for the remote-backend fire-and-forget learning embeds (the local
+# backend awaits inline instead — see below). Same GC-prevention pattern as
+# ``_bg_embed_tasks``.
+_bg_embed_learnings: set[asyncio.Task] = set()
+
+
+async def mcp_embed_learning(
+    *,
+    learning_id: str,
+    title: str,
+    description: str,
+    category: str,
+    severity: str,
+    prevention: str | None = None,
+    project: str | None = None,
+    workspace_id: str,
+) -> None:
+    """Backend-aware embed-on-write for learnings on the local MCP surface.
+
+    The learning analogue of ``mcp_schedule_embed``, but ASYNC + backend-aware: the
+    product decision is "embed synchronously on write", and a local Granite embed
+    (sub-second) can honor it — it is awaited inline so the just-created learning is
+    immediately retrievable by meaning, not just by keyword. A rate-limited remote
+    backend (remote, 3 RPM) must not block the create -> fire-and-forget instead.
+    Either way the SHARED fastapi-free body (``embedding_service.embed_learning_document``)
+    runs the embed OUTSIDE the write lock. The caller (the ``create_learning`` tool)
+    invokes this AFTER its ``acquire_write_db`` block has released the writer lock, so
+    the inline await cannot deadlock the non-reentrant single-writer lock (learning
+    f83f5209). No-ops when the embedder is unavailable.
+    """
+    from core.api.services import embedding_service
+
+    if not embedding_service.is_available():
+        return
+
+    async def _embed() -> None:
+        try:
+            await embedding_service.embed_learning_document(
+                learning_id=learning_id,
+                title=title,
+                description=description,
+                category=category,
+                severity=severity,
+                prevention=prevention,
+                project=project,
+                workspace_id=workspace_id,
+            )
+        except Exception:
+            logger.debug(
+                "MCP auto-embed learning %s failed (non-critical)",
+                learning_id,
+                exc_info=True,
+            )
+
+    if embedding_service.embedding_is_synchronous():
+        # Local Granite: await inline -> synchronous, immediately retrievable.
+        await _embed()
+        return
+
+    # Remote / rate-limited backend: fire-and-forget so the create never blocks.
+    try:
+        t = asyncio.create_task(_embed())
+    except RuntimeError:
+        logger.debug("MCP auto-embed learning skipped: no running event loop")
+        return
+    _bg_embed_learnings.add(t)
+    t.add_done_callback(_bg_embed_learnings.discard)
+
+
 def mcp_requires_pr_gate(_project: str | None) -> bool:
     """Local PR-gate seam: governance gate collapses in single-user OSS (S1 §AUTH)."""
     return False

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/server.py

@@ -1,7 +1,7 @@
 # v1.0.0 - 2026-05-27 - S1 F3.0: Python MCP server skeleton (FastMCP, stdio, use_cases-direct)
 """Python MCP server — the payoff of the S1 "collapse runtime" refactor.
 
-A single ``FastMCP("pir")`` instance exposes the PiR tools, each calling the
+A single ``FastMCP("marvis")`` instance exposes the Marvis tools, each calling the
 ``use_cases`` layer DIRECTLY (no Node, no HTTP, no uvicorn). Claude Code launches
 this as a stdio subprocess exactly as it does the Node ``index.mjs`` today:
 
@@ -34,7 +34,7 @@ from core.api.mcp.tools import register_all
 # `app.state` equivalent for a server with no FastAPI `app`). Tools register on
 # this at import time so `from core.api.mcp.server import mcp` already carries the
 # full tool set — the smoke test introspects it without launching stdio.
-mcp = FastMCP("pir")
+mcp = FastMCP("marvis")
 
 register_all(mcp)
 
@@ -47,11 +47,35 @@ def main() -> None:
     ``graph_*`` reach the SAME SQLite file the ``marvis`` CLI uses (instead of the
     bare ``db_path='console.db'`` default). Best-effort: no settings file → the
     API defaults / ``$PIR_DB_PATH`` env stand (parity with the CLI runtime).
+
+    Then open the DB the SAME way the FastAPI lifespan does — ``init_pool()``
+    creates the read-only pool AND the single dedicated writer. This is NOT
+    optional for write tools: ``acquire_db()`` has a no-pool fallback (so reads
+    answer even if the pool is absent), but ``acquire_write_db()`` raises
+    ``"DB not initialized — call init_pool() first"`` when the writer is None.
+    Without this, every mutator (``create_task``, ``update_task``, ...) failed —
+    the agent could read the brain via MCP but never write it back.
+
+    init + serve + close run in ONE event loop: aiosqlite connections are bound
+    to the running loop, so opening the pool in a separate ``asyncio.run()`` pass
+    before ``mcp.run()`` would leave the writer attached to an already-closed loop.
     """
+    import asyncio
+
+    from core.api.config import settings
+    from core.api.db import close_pool, init_pool
     from core.api.runtime_settings import apply_marvis_settings
 
     apply_marvis_settings()
-    mcp.run()
+
+    async def _serve() -> None:
+        await init_pool(size=settings.db_pool_size)
+        try:
+            await mcp.run_stdio_async()
+        finally:
+            await close_pool()
+
+    asyncio.run(_serve())
 
 
 if __name__ == "__main__":

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/__init__.py

@@ -35,6 +35,7 @@ from . import (
     safety,
     search,
     tasks,
+    workflows,
 )
 
 #: Ordered registration callables. ``server.py`` iterates this so adding a new
@@ -50,6 +51,7 @@ REGISTRARS = (
     ingest.register,
     pull_requests.register,
     safety.register,
+    workflows.register,
 )
 
 

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/brain.py

@@ -391,7 +391,7 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Get apply GUIDANCE for an approved memory operation (NO write — sub-03 §11.1).
 
-        QUANDO USARLO: dopo aver `approved` un'operazione (via brain_memory_operations_patch), per ottenere `next_action.tool` (es. mcp__pir__create_task) + args + `must_include_in_tags` (es. `brain_memory_op:abc123`). L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il `next_action.tool` con i tag richiesti per stabilire la chain di audit.
+        QUANDO USARLO: dopo aver `approved` un'operazione (via brain_memory_operations_patch), per ottenere `next_action.tool` (es. mcp__marvis__create_task) + args + `must_include_in_tags` (es. `brain_memory_op:abc123`). L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il `next_action.tool` con i tag richiesti per stabilire la chain di audit.
         QUANDO NON USARLO: per scrivere direttamente l'artifact — questo endpoint ritorna SOLO guidance. Pattern: PATCH → apply (guidance) → call next_action.tool con must_include_in_tags. Non usarlo prima di approval_state='approved' (409 precondition).
         RESTITUISCE: {operation_id, next_action:{tool, args, must_include_in_tags}, operation_summary}."""
         # GUIDANCE-only: the use_case calls get_apply_guidance (READ-only precondition
@@ -535,8 +535,8 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Get apply GUIDANCE for an approved finding (NO write — sub-04 F1).
 
-        QUANDO USARLO: dopo aver `approved` una finding, per ottenere `next_action.tool` (es. mcp__pir__create_task con title/description/tags pre-compilato) + `must_include_in_tags=brain_finding:{id}` per audit chain. L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il next_action.tool con i tag richiesti.
-        QUANDO NON USARLO: per scrivere artifact direttamente — pattern e' GUIDANCE-only. Non usarlo prima di approval_state='approved' (409). Non chiamarlo in loop 'ricomputa finche' la finding X appare': se non emerge, e' un problema del producer rule — file un learning via mcp__pir__create_learning.
+        QUANDO USARLO: dopo aver `approved` una finding, per ottenere `next_action.tool` (es. mcp__marvis__create_task con title/description/tags pre-compilato) + `must_include_in_tags=brain_finding:{id}` per audit chain. L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il next_action.tool con i tag richiesti.
+        QUANDO NON USARLO: per scrivere artifact direttamente — pattern e' GUIDANCE-only. Non usarlo prima di approval_state='approved' (409). Non chiamarlo in loop 'ricomputa finche' la finding X appare': se non emerge, e' un problema del producer rule — file un learning via mcp__marvis__create_learning.
         RESTITUISCE: {operation_id (=finding_id), next_action:{tool, args, must_include_in_tags}, operation_summary}."""
         # GUIDANCE-only: the use_case calls get_apply_guidance (READ-only precondition
         # + next-action envelope). No write transaction, no mutation — preserved.
@@ -588,7 +588,7 @@ def register(mcp) -> None:
     async def brain_capabilities() -> dict[str, Any]:
         """Discover Brain schema metadata (enums + glyphs + node kinds) — sub-05 OD-11.
 
-        QUANDO USARLO: cold-start dell'agente — leggere i Literal enum esposti dal Brain (event_types, signal_types, knowledge_forms, operation_types, finding_types, severities, confidence_tiers, drift_axes, approval_states, signal_states, run_statuses, closure_condition_kinds, knowledge_glyphs). Pattern equivalente di mcp__pir__graph_capabilities. Evita hardcoding constants. Schema_version aumenta quando i Literal cambiano.
+        QUANDO USARLO: cold-start dell'agente — leggere i Literal enum esposti dal Brain (event_types, signal_types, knowledge_forms, operation_types, finding_types, severities, confidence_tiers, drift_axes, approval_states, signal_states, run_statuses, closure_condition_kinds, knowledge_glyphs). Pattern equivalente di mcp__marvis__graph_capabilities. Evita hardcoding constants. Schema_version aumenta quando i Literal cambiano.
         QUANDO NON USARLO: per dati live del ciclo — usa brain_runs/brain_events/etc. Non e' un health check.
         RESTITUISCE: {schema_version, event_types[], source_systems[], signal_types[], knowledge_forms[], operation_types[], finding_types[], severities[], confidence_tiers[], drift_axes[], approval_states[], finding_approval_states[], signal_states[], run_statuses[], run_triggers[], scope_types[], suggested_artifacts[], closure_condition_kinds[], knowledge_glyphs:{form: glyph}}."""
         # Deterministic; no DB. The use_case takes only ctx.

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/learnings.py

@@ -22,7 +22,14 @@ from typing import Annotated, Any, Literal
 
 from pydantic import Field
 
-from core.api.mcp._adapter import LOCAL_CTX, acquire_db, acquire_write_db, dump, raise_mcp_error
+from core.api.mcp._adapter import (
+    LOCAL_CTX,
+    acquire_db,
+    acquire_write_db,
+    dump,
+    mcp_embed_learning,
+    raise_mcp_error,
+)
 from core.api.use_cases import learnings as learnings_uc
 from core.api.use_cases._errors import ServiceError
 
@@ -85,7 +92,20 @@ def register(mcp) -> None:
                     tags=tags,
                     project=project,
                 )
-                return dump(result)
+            # Writer lock released: embed-on-write. On a local Granite backend this
+            # awaits inline (synchronous) so the learning is immediately retrievable by
+            # meaning — not just by keyword until a manual reindex (the bug this fixes).
+            await mcp_embed_learning(
+                learning_id=result.id,
+                title=result.title,
+                description=result.description,
+                category=result.category,
+                severity=result.severity,
+                prevention=result.prevention,
+                project=result.project,
+                workspace_id=LOCAL_CTX.workspace_id,
+            )
+            return dump(result)
         except ServiceError as e:
             raise_mcp_error(e)
 
@@ -142,3 +162,21 @@ def register(mcp) -> None:
                 return dump(result)
         except ServiceError as e:
             raise_mcp_error(e)
+
+    @mcp.tool()
+    async def delete_learning(
+        learning_id: Annotated[str, Field(min_length=1)],
+    ) -> dict[str, Any]:
+        """Permanently remove a learning from the Marvis DB (non-recoverable) + prune the search index.
+
+        QUANDO USARLO: solo per learning duplicati, spam, o entry chiaramente invalide. Hard delete: rimuove anche il mirror nell'indice di ricerca (documents + vec_documents + FTS) cosi' il learning smette di comparire in search/check_learnings.
+        QUANDO NON USARLO: NOT per archiviare un learning ancora valido — la cancellazione e' permanente e perde la history. Aggiornalo con update_learning se il contenuto e' obsoleto.
+        RESTITUISCE: {deleted: true} o 404 se non esiste."""
+        try:
+            async with acquire_write_db(label="mcp.delete_learning") as db:
+                await learnings_uc.delete_learning(
+                    LOCAL_CTX, db, learning_id=learning_id
+                )
+                return {"deleted": True}
+        except ServiceError as e:
+            raise_mcp_error(e)

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/projects.py

@@ -39,7 +39,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def list_projects() -> list[dict[str, Any]]:
-        """List all PiR-tracked projects grouped by program.
+        """List all Marvis-tracked projects grouped by program.
 
         QUANDO USARLO: serve un inventario (quali progetti ci sono, dammi tutti gli slug) o non conosci lo slug target.
         QUANDO NON USARLO: NOT quando hai gia' uno slug specifico e vuoi i dettagli -> usa get_project. NOT per cold-start di un progetto -> usa session_brief.

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/pull_requests.py

@@ -79,7 +79,7 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Atomic create branch + worktree + draft PR (orchestrator-managed).
 
-        QUANDO USARLO: hai un task approved/in_progress e ti serve un worktree isolato per iniziare a lavorare. Un'unica call crea branch `feat/task-{uuid}`, worktree in `~/dev/task-{uuid}`, e draft PR row in PiR. Preferisci su `git worktree add` manuale + register_branch (2-step flow).
+        QUANDO USARLO: hai un task approved/in_progress e ti serve un worktree isolato per iniziare a lavorare. Un'unica call crea branch `feat/task-{uuid}`, worktree in `~/dev/task-{uuid}`, e draft PR row in Marvis. Preferisci su `git worktree add` manuale + register_branch (2-step flow).
         QUANDO NON USARLO: NOT se il worktree esiste gia' (creato manualmente o fuori orchestrator) -> usa register_branch per attaccarlo al task. NOT se il task non e' ancora approved -> il backend risponde 400.
         RESTITUISCE: {task_id, branch_name, worktree_path, status:'draft'} idempotent."""
         try:
@@ -97,8 +97,8 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Attach an existing git branch/worktree to a task as draft PR record (idempotent).
 
-        QUANDO USARLO: il worktree e' stato creato manualmente via `git worktree add` o fuori orchestrator, e serve la PR row PiR per poter chiamare submit_pr dopo. BOUNDARY: register_branch crea draft; submit_pr promuove draft -> open per review.
-        QUANDO NON USARLO: NOT quando vuoi che PiR crei il worktree per te -> usa endpoint HTTP /api/v1/pull_requests/{task_id}/branch. NOT dopo submit -> il record e' gia' open.
+        QUANDO USARLO: il worktree e' stato creato manualmente via `git worktree add` o fuori orchestrator, e serve la PR row Marvis per poter chiamare submit_pr dopo. BOUNDARY: register_branch crea draft; submit_pr promuove draft -> open per review.
+        QUANDO NON USARLO: NOT quando vuoi che Marvis crei il worktree per te -> usa endpoint HTTP /api/v1/pull_requests/{task_id}/branch. NOT dopo submit -> il record e' gia' open.
         RESTITUISCE: {task_id, branch_name, worktree_path, status:'draft'} idempotent."""
         try:
             async with acquire_write_db() as db:

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/safety.py

@@ -5,7 +5,7 @@ The Node ``check_safety`` SHELLS ``python3 scripts/safety_bridge.py check
 --action-type <t> [--file-path ...] [--command ...] [--cwd ...]`` and parses the
 ``{allowed, reason, rule}`` JSON it prints. ``core/scripts/safety_bridge.py`` is
 pure stdlib (``argparse`` / ``json`` / ``re`` / ``shlex`` / ``subprocess`` for the
-git/npm checks) — it has ZERO fastapi and ZERO PiR-app dependency. So the in-process
+git/npm checks) — it has ZERO fastapi and ZERO Marvis-app dependency. So the in-process
 port imports the bridge's ``evaluate_action`` (the exact function ``_run_check``
 calls) DIRECTLY: no subprocess, no ``python3`` re-exec, no HTTP. The returned
 ``Decision`` is mapped to the SAME ``{allowed, reason, rule}`` dict shape the Node

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/search.py

@@ -22,7 +22,7 @@ Name mapping (Node tool name -> use_case function):
 The embedding/hybrid services are pulled FUNCTION-LOCALLY by the use_case itself
 (``hybrid_search`` / ``embedding_service``), so nothing fastapi-bound is imported
 at module load. ``search`` raises ``ServiceUnavailableError`` (-> raise_mcp_error)
-when Voyage is down — the 503 collapses to the MCP error result shape.
+when the embedding backend is down — the 503 collapses to the MCP error result shape.
 
 Return typing: ``search`` returns the ``SearchResponse`` DTO (``.model_dump()`` via
 ``dump()``); ``reindex`` returns a plain status dict.
@@ -49,11 +49,11 @@ def register(mcp) -> None:
     async def search(
         q: Annotated[str, Field(min_length=1, max_length=500)],
     ) -> dict[str, Any]:
-        """Semantic embedding-based search across tasks + projects + files + handoffs + learnings.
+        """Semantic + hybrid search by MEANING across tasks, projects, files, handoffs, learnings, inbox, audits. Fuses the embedding retriever with the Knowledge Graph (RRF).
 
-        QUANDO USARLO: natural-language discovery cross-type quando non conosci keyword esatte o doc_type (es. 'dove abbiamo parlato di caching Redis?'). Score > 0.6 generalmente rilevante.
-        QUANDO NON USARLO: NOT per singolo artifact noto per ID -> usa get_task / list_handoffs con filtri. NOT per keyword exact-match -> usa search_handoffs. NOT per doc_type specifico con filtri -> usa list_tasks.
-        RESTITUISCE: {tasks[], projects[], files[], handoffs[], learnings[], total, query} ranked per (70% Voyage similarity + 30% salience). 503 se Voyage non disponibile."""
+        QUANDO USARLO: PRIMA scelta per domande trasversali o concettuali ('dove abbiamo parlato di caching Redis?', 'decisioni sul rollback', 'cosa dipende da X'): trova per significato anche senza le keyword esatte. Alza il tetto: usala invece di fermarti al primo summary o a una lista filtrata. Score > 0.6 generalmente rilevante.
+        QUANDO NON USARLO: NOT per un artifact noto per ID -> usa get_task / get_handoff. NOT per un filtro esatto su un solo doc_type -> usa list_tasks / list_handoffs. NOT per keyword literal su un handoff -> usa search_handoffs.
+        RESTITUISCE: {tasks[], projects[], files[], handoffs[], learnings[], total, query} ranked per (70% similarita semantica + 30% salience) + semantic_available (bool|None) + semantic_reason (enum|None: model-not-loadable/vec0-not-loadable/runtime-gate). Se semantic_available=false la lane semantica e' giu' e i risultati sono solo keyword. 503 se il motore di embedding non e' disponibile."""
         # The use_case takes only `ctx`: it opens its own connections from
         # settings (db_path / vec0_path) and pulls hybrid_search / embedding_service
         # function-locally — so the MCP path stays fastapi-free at import.
@@ -65,7 +65,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def reindex(type: ReindexType = "all") -> dict[str, Any]:
-        """Rebuild Voyage embeddings index for semantic search backend.
+        """Rebuild the embeddings index for the semantic search backend.
 
         QUANDO USARLO: solo dopo bulk ops che bypassano i normali hook (direct SQL insert, file-sync script, migration) se noti search stale. Operator+.
         QUANDO NON USARLO: NOT routinely — l'index e' auto-sync su create/update normali. NOT su errori transient di search -> aspetta background reconcile.

{marvisx_cli-0.2.2 → marvisx_cli-0.3.5}/core/api/mcp/tools/tasks.py

@@ -137,7 +137,7 @@ def register(mcp) -> None:
         delegation: TaskDelegation | None = None,
         completion_mode: TaskCompletionMode = "pr",
     ) -> dict[str, Any]:
-        """Persist a new cross-session task in PiR DB (survives session end, visible in Console Triage).
+        """Persist a new cross-session task in Marvis DB (survives session end, visible in Console Triage).
 
         QUANDO USARLO: PRIMA AZIONE per ogni lavoro implementativo (feat/fix/refactor/research) — richiesto da Constitution Rule 1 prima di qualunque Edit/Write. SEMPRE con ICE-D (impact/confidence/ease/delegation).
         QUANDO NON USARLO: NOT per modificare un task esistente -> usa update_task. NOT per free chat/brainstorm (session-first).
@@ -189,7 +189,7 @@ def register(mcp) -> None:
         delegation: TaskDelegation | None = None,
         completion_mode: TaskCompletionMode | None = None,
     ) -> dict[str, Any]:
-        """Mutate an existing PiR task (status, priority, description, tags, ICE-D, completion_mode).
+        """Mutate an existing Marvis task (status, priority, description, tags, ICE-D, completion_mode).
 
         QUANDO USARLO: transizioni di stato lungo il lifecycle (pending -> approved -> in_progress -> review -> completed) o rifinitura scoring/description dopo creazione.
         QUANDO NON USARLO: NOT per creare un nuovo task -> usa create_task. NOT per delete permanente -> usa delete_task. Status='approved' e' BLOCCATO per agent (403) — solo umani approvano via Console Triage.
@@ -231,7 +231,7 @@ def register(mcp) -> None:
     async def delete_task(
         task_id: Annotated[str, Field(min_length=1)],
     ) -> dict[str, Any]:
-        """Permanently remove a task from the PiR DB (non-recoverable).
+        """Permanently remove a task from the Marvis DB (non-recoverable).
 
         QUANDO USARLO: solo per spam/duplicate o entry chiaramente invalidi.
         QUANDO NON USARLO: NOT per abbandonare un task valido -> usa update_task con status='rejected' o 'failed' (preserva audit trail). Deletion cancella la history.