marvisx-cli 0.3.6__tar.gz → 0.3.7__tar.gz

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/LICENSE

@@ -5,19 +5,18 @@ Parameters
 Licensor:             Emilio Martucci
 Licensed Work:        MarvisX
                       The Licensed Work is (c) 2026 Emilio Martucci.
-Additional Use Grant: You may make production use of the Licensed Work only
-                      for personal, non-commercial purposes (for example,
-                      self-hosting it for your own individual use). Any other
-                      production use is not granted here and requires a separate
-                      commercial license from the Licensor. Uses that are NOT
-                      granted include, without limitation: any commercial use;
-                      any use by, within, or for the benefit of a business,
-                      company, or other organization; offering the Licensed
-                      Work (or a modified or adapted version of it) to third
-                      parties as a hosted or managed service; and using a
-                      modified or adapted version of the Licensed Work as, or
-                      as part of, a product or service that competes with the
-                      Licensor.
+Additional Use Grant: You may make production use of the Licensed Work,
+                      including for internal business and commercial
+                      purposes and including self-hosting the Licensed
+                      Work for your own use, provided that you may not
+                      provide the Licensed Work to third parties as a
+                      Hosted or Managed Service. A "Hosted or Managed
+                      Service" is a commercial offering that gives third
+                      parties (other than your employees and contractors)
+                      access to the substantial functionality of the
+                      Licensed Work, or of a modified or derived version
+                      of it, or that otherwise competes with a product or
+                      service the Licensor offers using the Licensed Work.
 Change Date:          2030-01-01
 Change License:       Apache License, Version 2.0
 

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/MANIFEST.in

@@ -10,4 +10,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 core/cli/guides *.md
 recursive-include projects/_template *

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.3.6
+Version: 0.3.7
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/README.md

@@ -1,6 +1,8 @@
 # Marvis
 
-**The Company Brain your agents install.** Use Claude Code, or whatever coding agent you run, to manage projects and coordinate your agents, not just write code. Marvis captures what your agents do as they work, structures it into a cross-project Knowledge Graph, and hands it back to them, so your work stays on track and the system learns from it. Self-hosted, EU-resident, governed by an immutable audit chain.
+[![PyPI](https://img.shields.io/pypi/v/marvisx-cli.svg)](https://pypi.org/project/marvisx-cli/) [![License: BSL 1.1](https://img.shields.io/badge/license-BSL%201.1-blue.svg)](LICENSE) [![Change Date: Apache-2.0 2030](https://img.shields.io/badge/change%20date-Apache--2.0%20(2030)-lightgrey.svg)](LICENSE)
+
+**The Company Brain your agents install.** Use Claude Code, or whatever coding agent you run, to manage projects and coordinate your agents, not just write code. Marvis captures what your agents do as they work, structures it into a cross-project Knowledge Graph, and hands it back to them, so your work stays on track and the system learns from it. Self-hosted, EU-resident, with a tamper-evident audit log.
 
 **Open-core and free to run.** Marvis is the free core: you self-host it, read the source, fork it, audit it, at no cost. MarvisX is the commercial tier on top of the same brain: multi-department teams, data sovereignty and managed hosting, and autonomous, hands-off-the-keyboard operation. Marvis is what you install today; MarvisX is what you reach for when a single self-hosted instance is no longer enough.
 
@@ -15,6 +17,8 @@ marvis init
 
 `marvis init` scaffolds the project and installs the governance hooks, then exposes the MCP surface to your agent. Python 3.10–3.13; on 3.14, pin the interpreter: `uv tool install --python 3.13 marvisx-cli`. No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh`.
 
+**Managed Windows (application-control policy)?** If your organization enforces application control — Windows **WDAC** / AppLocker / Managed Installer, common on managed corporate machines — Windows blocks running any binary placed in `%LOCALAPPDATA%`, which is where `uv` installs tools, so `uv tool install` can't execute. Don't bypass it. Install Marvis inside **WSL2** (recommended) or **Docker**, or ask IT to whitelist `uv` (or publish it through your managed channel); the Linux runtime is identical.
+
 To run the full Console + API stack yourself, see [Self-hosting the full stack](#self-hosting-the-full-stack).
 
 ## What it does, in plain terms
@@ -28,7 +32,7 @@ To run the full Console + API stack yourself, see [Self-hosting the full stack](
 ## Under the hood
 
 - **Cross-project Knowledge Graph** with 17 deterministic edge types covering code, work-chain artifacts, knowledge-chain documents, cross-project references, and bridge edges. Canonical IDs follow `{prefix}:{kind}:{slug}`.
-- **Foreign-key-immutable audit log** with provenance pinned at the SQLite level. Designed to satisfy the logging surface required by EU Regulation 2024/1689 (AI Act) Article 12.
+- **Append-only audit log** (foreign-key + trigger enforced) with provenance pinned at the SQLite level. The managed **MarvisX** tier builds on it to cover the logging surface required by EU Regulation 2024/1689 (AI Act) Article 12.
 - **Brain reflection pipeline** in five layers — substrate, digest and journal, drift checker, memory operations, findings — closed by a Direction-Aware loop.
 - **Constitution-enforced safety rules** enforced by deterministic hook gates and an MCP mirror for providers without native hooks.
 - **Agent-native MCP surface** exposing 91 tools, callable identically from Claude Code, Codex, Gemini, OpenCode, and a web console.
@@ -37,14 +41,14 @@ To run the full Console + API stack yourself, see [Self-hosting the full stack](
 
 Marvis defaults to **IBM Granite-Embedding-97m-Multilingual-R2** self-hosted via ONNX, blended with SQLite BM25 keyword search through Reciprocal Rank Fusion. Backend is selectable through `EMBEDDING_MODE`.
 
-This is a deliberate tradeoff: EU compliance, self-hosting, and zero external embedding cost come at the cost of retrieval quality that is below commercial managed embedding providers. See [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) for the benchmark numbers, affected workflows, mitigations available today, and the Phase 2 fine-tune roadmap.
+This is a deliberate tradeoff: EU residency, self-hosting, and zero external embedding cost come at the cost of retrieval quality that is below commercial managed embedding providers. See [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) for the benchmark numbers, affected workflows, mitigations available today, and the Phase 2 fine-tune roadmap.
 
 ## License posture
 
-- **Free to self-host.** Code is **source-available** under the **Business Source License 1.1**, with an automatic change date converting to **Apache License 2.0** four years after release.
+- **Free to self-host and use internally**, including for commercial purposes. Code is **source-available** under the **Business Source License 1.1**; a paid license is required only to offer Marvis to third parties as a hosted or managed service. The change date automatically converts the code to **Apache License 2.0** four years after release.
 - Documentation and architectural patterns: **CC-BY 4.0**.
 
-This is open-core, not OSI open source: the core is free to run and read, and the BSL holds back only competing commercial-as-a-service use until the change date. The combination keeps the architecture freely citable while preserving the ability to ship a self-hosted reference deployment.
+This is open-core, not OSI open source: the core is free to run, read and fork, and the BSL holds back only competing commercial-as-a-service use until the change date. GitHub does not recognize the BSL and labels the repo `NOASSERTION`; the authoritative terms are in [`LICENSE`](LICENSE).
 
 ## Architecture map
 

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/core/api/config.py

@@ -80,6 +80,14 @@ class Settings(BaseSettings):
         default_factory=lambda: str(db_default_path()),
         validation_alias=AliasChoices("MARVIS_DB_PATH", "PIR_DB_PATH", "DB_PATH"),
     )
+    db_backup_dir: str = Field(
+        # Where pre-migration / pre-rebuild console.db snapshots land. Empty (the
+        # OSS default) keeps them next to the DB. In a managed deployment set this
+        # to a roomy data volume: the snapshots are full DB copies (>1GB) and a
+        # couple of them fill a small root disk — the recurring 90%-full cause.
+        default="",
+        validation_alias=AliasChoices("MARVIS_DB_BACKUP_DIR", "PIR_DB_BACKUP_DIR"),
+    )
     cookie_domain: str | None = Field(default=None, alias="COOKIE_DOMAIN")
     cors_origins_prod: list[str] = Field(
         default_factory=list,

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/core/api/db.py

@@ -617,20 +617,24 @@ def run_migrations() -> None:
             and int(f.stem.split("_")[0]) > current_version
         ]
 
-        # Pre-migration backup (enterprise rollback strategy)
-        # Keep only last 2 backups to prevent disk fill (was unbounded)
+        # Pre-migration backup (enterprise rollback strategy).
+        # Snapshots go to settings.db_backup_dir (a roomy data volume in prod)
+        # when set, otherwise next to the DB. Rotation is GLOBAL keep-2 across
+        # ALL tags in that dir (migration `backup-v*`, kg `backup-pre-rebuild-*`,
+        # etc.) — full DB copies are >1GB, so only the two newest are retained.
         if pending:
-            backup_path = f"{settings.db_path}.backup-v{current_version}"
+            db_name = os.path.basename(settings.db_path)
+            backup_dir = settings.db_backup_dir or os.path.dirname(settings.db_path) or "."
+            backup_path = os.path.join(backup_dir, f"{db_name}.backup-v{current_version}")
             try:
+                os.makedirs(backup_dir, exist_ok=True)
                 shutil.copy2(settings.db_path, backup_path)
                 logger.info("Pre-migration backup: %s", backup_path)
-                # Rotate: keep only the 2 most recent backups
+                # Rotate: keep only the 2 most recent backups (global, all tags)
                 import glob
 
-                db_dir = os.path.dirname(settings.db_path) or "."
-                db_name = os.path.basename(settings.db_path)
                 backups = sorted(
-                    glob.glob(os.path.join(db_dir, f"{db_name}.backup-v*")),
+                    glob.glob(os.path.join(backup_dir, f"{db_name}.backup-*")),
                     key=os.path.getmtime,
                 )
                 for old_backup in backups[:-2]:

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/core/api/services/brain/jobs.py

@@ -283,7 +283,20 @@ async def _execute_cycle(
     event_count = 0
     journal_count = 0
 
-    collectors = collectors if collectors is not None else registered_collectors()
+    if collectors is None:
+        collectors = registered_collectors()
+        if not collectors:
+            # Standalone runtime (`marvis brain run` / brain_cycles_recompute via
+            # the CLI + stdio MCP) never runs the API lifespan startup hook that
+            # registers the source collectors, so the registry is empty and the
+            # cycle would silently collect 0 events even with in-window data
+            # (issue #6). Register them lazily here so the standalone path lights
+            # up the same capture→reflect collectors as the API service. Idempotent
+            # and inert when the API already registered them at startup.
+            from core.api.services.brain.sources import register_all_collectors
+
+            register_all_collectors()
+            collectors = registered_collectors()
 
     # Cycle window resolution (bug fix 2026-05-18). When caller did not pass
     # explicit window bounds (legacy periodic path), default to the legacy

marvisx_cli-0.3.7/core/cli/guides/__init__.py

@@ -0,0 +1,6 @@
+"""Packaged Marvis reference guides loaded at runtime by `marvis guide`.
+
+The ``__init__.py`` makes this a regular package so
+``importlib.resources.files("core.cli.guides")`` resolves the bundled markdown
+identically from a source checkout and from an installed wheel.
+"""

marvisx_cli-0.3.7/core/cli/guides/marvis-way.md

@@ -0,0 +1,183 @@
+# The Marvis Way
+
+> **If you are an AI agent, this is your operating manual — read it before you
+> touch the user's repository.** It tells you exactly how to organize their
+> work, where to write what, and how to leave the workspace better than you
+> found it so the next agent (or you, tomorrow) picks up without losing context.
+> Everything here is concrete and you can act on it immediately.
+
+Marvis is a **mold** for how an agent-run workspace keeps its memory. It does
+not replace your agent — Claude Code, Codex, Cursor, whatever you use — it gives
+that agent a place to put what it learns, a shape for your projects, and a way
+to find prior decisions across them.
+
+This guide is the source of truth for how that shape works. Read it, then apply
+it to your own repository: an agent can use these conventions to organize a
+messy folder, write the missing context, and let Marvis index the result. You
+do not have to adopt everything at once — start with one project and a
+`context.md`, and grow into the rest.
+
+**Installing on a locked-down machine.** If `uv tool install` is blocked by an
+organization's application-control policy (Windows WDAC / AppLocker / Managed
+Installer — common on managed corporate machines), do not bypass it. Install
+Marvis inside WSL2 (recommended) or Docker, or ask IT to whitelist `uv`; the
+Linux runtime is identical.
+
+Sections (jump with `marvis guide --section <name>`): concepts, naming,
+directories, dependencies, tags, frontmatter, brain, lifecycle, adopt.
+
+## Concepts
+
+Three nested units organize everything:
+
+- **Program** — a long-running line of work or a team area. Optional grouping
+  over projects (e.g. "platform", "growth"). Programs give cross-project views.
+- **Project** — the main unit. One folder, one `project.yaml`. A project has a
+  `type`: `code` (has a git repo and ships PRs), `work` (docs/research, no git),
+  or `system` (infrastructure). Everything below — context, memory, docs — hangs
+  off a project.
+- **Task** — a single tracked piece of work inside a project. Tasks survive
+  across agent sessions, so an agent that picks up tomorrow sees what was open.
+  Tasks carry an intent score (impact / confidence / ease) and a delegation
+  (agent, hybrid, human).
+
+The rule of thumb: **one thing in progress at a time per worker**, and every
+implementation change starts by creating a task — so the work is tracked before
+the first edit, not reconstructed afterwards.
+
+## Naming
+
+- **Slugs** are kebab-case, lowercase, stable: `growth-site`, `q3-research`.
+  A slug never changes once other things reference it.
+- **Canonical IDs** in the Knowledge Graph follow `{prefix}:{kind}:{slug}`,
+  for example `task:artifact:<uuid>`, `handoff:artifact:2026-06-04-onboarding`,
+  `py:function:core.api.db.get_db`. The prefix says what kind of thing it is;
+  the kind says whether it is a file, function, module, or artifact.
+- **Files** are dated when they are events (`handoff-2026-06-04-<topic>.md`) and
+  named by subject when they are references (`context.md`, `project.yaml`).
+
+## Directories
+
+A project is a folder. The conventional layout:
+
+```
+<project-slug>/
+  project.yaml          # name, slug, type, lifecycle  (the only required file)
+  context.md            # the living state of the project: goal, status, constraints
+  memory/
+    handoff-YYYY-MM-DD-<topic>.md   # what happened in a session, for the next one
+  docs/
+    brainstorms/        # exploring WHAT to build
+    plans/              # deciding HOW to build it
+    solutions/          # what was built and why (post-hoc, durable)
+  input/                # raw material you bring in (transcripts, exports, briefs)
+  output/               # finished artifacts you hand out
+```
+
+`code` projects keep their actual source wherever it already lives (a `repo_path`
+in `project.yaml` points at it); the project folder holds the *memory* around the
+code, not necessarily the code itself.
+
+## Dependencies
+
+Marvis links artifacts in a **Knowledge Graph** so an agent can ask "who calls
+this", "what breaks if I change it", and "why does this exist" instead of
+grepping blind. The edges are deterministic — derived from the code and the
+documents, not guessed by a model. They fall into categories:
+
+- **Code**: `calls`, `imports`, `defines` — extracted from the source tree.
+- **Work chain**: `produces`, `contains` — a task produces a PR; a project
+  contains its docs.
+- **Knowledge chain**: `describes`, `documents`, `cites`, `applies_to` — a
+  handoff describes a task; a learning applies to a module.
+- **Cross-project**: `depends_on`, `mentions`, `refers_to`, `shares_tag`,
+  `similar_to` — how one project's work relates to another's.
+- **Bridge**: `resolves_to` — links a referenced symbol to its canonical file.
+
+You never write edges by hand. They are populated from what you commit and the
+frontmatter you fill in. The authoritative, live set of edge types for an
+install is what the graph reports — treat the list above as the shape, not a
+fixed count.
+
+## Tags
+
+Tags are free-form, lowercase, kebab-case labels on tasks, handoffs, and
+learnings. They power search and the `shares_tag` cross-project edge. Keep them
+few and meaningful: a topic (`auth`, `billing`), a surface (`frontend`, `api`),
+or a workstream (`q3-launch`). Tags are not a taxonomy you design up front; they
+accrete, and search does the rest.
+
+## Frontmatter
+
+Every durable markdown artifact starts with a YAML frontmatter block. It is how
+Marvis indexes the file and how an agent reads its metadata without parsing
+prose. The body below the block is **only content** — no "this document is for
+X" preamble; audience and status live in the frontmatter.
+
+A handoff:
+
+```yaml
+---
+date: 2026-06-04
+project: growth-site
+tags: [onboarding, launch]
+---
+```
+
+A plan or brainstorm adds `title`, `type`, `status`. A solution records what was
+built. The minimum that makes a file first-class is a `date` (for events) or a
+`title` + `project` (for references). Missing frontmatter does not break
+anything — the file is just weaker signal until you add it.
+
+## Brain
+
+The Brain is a reflection layer that runs on a schedule (or on demand with
+`marvis brain run`). It does not write your code; it watches the work and keeps
+the memory honest. It runs in layers:
+
+1. **Substrate** — collects what changed since last time.
+2. **Digest & journal** — a short narrative of what happened, per project.
+3. **Drift** — compares what was produced against the stated intent and flags
+   where they diverge before it compounds.
+4. **Memory operations** — proposes consolidating duplicates, superseding stale
+   notes, hardening provenance. Proposals, not silent edits.
+5. **Findings** — conclusions worth your attention, queued for you to approve.
+
+The free mode never uses an LLM key — it is local upkeep. The full mode adds an
+LLM pass for narrative polish and citations when you have configured a key.
+
+## Lifecycle
+
+Work moves through a fixed set of states so nothing is silently dropped:
+
+```
+pending  →  approved  →  in_progress  →  review  →  completed
+                                                     (or rejected / failed)
+```
+
+- **pending** — created, not yet greenlit. A human approves it.
+- **approved** — greenlit, ready to start.
+- **in_progress** — being worked. Exactly one per worker at a time.
+- **review** — a `code`/`system` task opens a pull request and waits for a human
+  to merge it. `completed` is reached by the merge, not set by hand.
+- **completed** — done and verified.
+
+For `work` projects there is no PR — the task completes when its document
+exists. For quick diagnostics, a task can complete with no artifact at all.
+
+## Adopt
+
+To bring an existing, messy folder into this shape, point your agent at this
+guide and ask it to work **non-destructively** — map first, then propose:
+
+1. **Read** the folder and group files by the project they belong to.
+2. **Propose** a structure (the layout above), one project at a time, and wait
+   for your OK before moving anything. Nothing is deleted or overwritten without
+   confirmation.
+3. **Create** the missing `project.yaml` and a `context.md` from the templates,
+   and add frontmatter to the documents that lack it.
+4. **Index** — let Marvis read the resulting project folders. The Knowledge
+   Graph and search build themselves from there.
+
+Marvis is the mold; your agent does the shaping. You stay in control of every
+move.

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/core/cli/marvis_brain.py

@@ -41,6 +41,106 @@ def register(app: typer.Typer) -> None:
     )
 
 
+# ---------------------------------------------------------------------------
+# brain_enabled setter (issue #7) — a supported toggle instead of a direct
+# console.db UPDATE (which the governance hooks block).
+# ---------------------------------------------------------------------------
+
+
+async def _read_brain_enabled() -> str:
+    """Current brain_enabled mode; defaults to 'shadow' like the runtime loader."""
+    from core.cli._runtime_ctx import with_db
+
+    async with with_db() as db:
+        cur = await db.execute(
+            "SELECT value FROM app_settings WHERE key = 'brain_enabled'"
+        )
+        row = await cur.fetchone()
+    return row[0] if row and row[0] else "shadow"
+
+
+async def _write_brain_enabled(value: str) -> None:
+    """Set brain_enabled through the single writer (the supported path) and close
+    the pool we opened so the one-shot CLI exits immediately (no ~30s teardown)."""
+    from datetime import datetime, timezone
+
+    from core.cli._runtime_ctx import _apply_settings
+
+    _apply_settings()
+    from core.api import db as db_mod
+
+    own_pool = db_mod._writer is None
+    if own_pool:
+        await db_mod.init_pool()
+    try:
+        async with db_mod.acquire_write_db(label="marvis-brain-set") as db:
+            await db.execute(
+                "INSERT INTO app_settings (key, value, updated_at) VALUES (?, ?, ?) "
+                "ON CONFLICT(key) DO UPDATE SET value = excluded.value, "
+                "updated_at = excluded.updated_at",
+                ("brain_enabled", value, datetime.now(timezone.utc).isoformat()),
+            )
+            await db.commit()
+    finally:
+        if own_pool:
+            await db_mod.close_pool()
+
+
+def _print_brain_mode(mode: str) -> None:
+    from core.cli._runtime_ctx import console
+
+    style = {"true": "green", "shadow": "cyan", "false": "yellow"}.get(mode, "white")
+    explain = {
+        "true": "on — reflection runs and writes",
+        "shadow": "shadow — reflection runs, proposals only (default)",
+        "false": "off — reflection disabled",
+    }.get(mode, mode)
+    console.print(f"[{style}]brain_enabled = {mode}[/{style}]  ({explain})")
+
+
+@brain_app.command("enable")
+def enable_cmd(
+    shadow: bool = typer.Option(
+        False, "--shadow", help="Enable in shadow mode (proposals only) instead of full."
+    ),
+    json_out: bool = typer.Option(False, "--json", help="Emit pure JSON to stdout."),
+) -> None:
+    """Turn the Company Brain on — a supported setter, no direct DB write."""
+    mode = "shadow" if shadow else "true"
+    run_async(_write_brain_enabled(mode))
+    emit(
+        {"brain_enabled": mode},
+        json_out=json_out,
+        render=lambda r: _print_brain_mode(r["brain_enabled"]),
+    )
+
+
+@brain_app.command("disable")
+def disable_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Emit pure JSON to stdout."),
+) -> None:
+    """Turn the Company Brain off."""
+    run_async(_write_brain_enabled("false"))
+    emit(
+        {"brain_enabled": "false"},
+        json_out=json_out,
+        render=lambda r: _print_brain_mode(r["brain_enabled"]),
+    )
+
+
+@brain_app.command("status")
+def brain_status_cmd(
+    json_out: bool = typer.Option(False, "--json", help="Emit pure JSON to stdout."),
+) -> None:
+    """Show whether the Company Brain is on, off, or in shadow mode."""
+    mode = run_async(_read_brain_enabled())
+    emit(
+        {"brain_enabled": mode},
+        json_out=json_out,
+        render=lambda r: _print_brain_mode(r["brain_enabled"]),
+    )
+
+
 @brain_app.command("run")
 def run_cmd(
     mode: str = typer.Option(
@@ -72,12 +172,23 @@ def run_cmd(
     async def _run() -> dict[str, Any]:
         from core.api import db as db_mod
 
-        if db_mod._writer is None:  # lazy one-shot writer init for the CLI process
+        # We own the pool only if we open it here. A server-hosted process that
+        # already initialized the pool keeps owning it — we must not tear it down.
+        own_pool = db_mod._writer is None
+        if own_pool:  # lazy one-shot writer init for the CLI process
             await db_mod.init_pool()
 
         from core.api.services.brain.jobs import run_brain_cycle_once
 
-        return await run_brain_cycle_once(reflection_mode=mode)
+        try:
+            return await run_brain_cycle_once(reflection_mode=mode)
+        finally:
+            # Close the connections we opened. Each aiosqlite connection runs on a
+            # NON-daemon thread that the interpreter joins at exit, so leaving the
+            # writer open hangs the one-shot CLI ~30s after run_async returns —
+            # the flagship-command "is it broken?" bug (issue #1).
+            if own_pool:
+                await db_mod.close_pool()
 
     payload = run_async(_run())
     emit(payload, json_out=json_out, render=_render)

{marvisx_cli-0.3.6 → marvisx_cli-0.3.7}/core/cli/marvis_doctor.py

@@ -389,7 +389,16 @@ def _check_resolved_paths() -> CheckResult:
     from core.api.config import settings
 
     db = Path(settings.db_path)
-    projects = projects_root_default()
+    # The configured projects root — apply_marvis_settings() (run at the top of
+    # doctor) set core.api.routers.projects.PROJECT_DIRS from settings.yaml, the
+    # same source `project list` reads. Fall back to the platform default only
+    # when nothing is configured, so doctor reports the real root, not the default.
+    try:
+        from core.api.routers.projects import PROJECT_DIRS
+
+        projects = PROJECT_DIRS[0] if PROJECT_DIRS else projects_root_default()
+    except Exception:  # noqa: BLE001 — never let a resolver hiccup break doctor
+        projects = projects_root_default()
     detail = f"db={db} | projects={projects}"
     if not db.is_absolute():
         return CheckResult(
@@ -846,6 +855,18 @@ def doctor_cmd(
     """
     checks: list[CheckResult] = []
 
+    # Resolve the user's settings.yaml into `settings` BEFORE any check reads a
+    # path, so resolved_paths reports the configured db / projects_root instead
+    # of the module defaults (the ~/Library/Application Support cosmetic bug).
+    # Best-effort: a missing/unreadable settings.yaml leaves the defaults, which
+    # is the correct state for a not-yet-initialized install.
+    try:
+        from core.api.runtime_settings import apply_marvis_settings
+
+        apply_marvis_settings()
+    except Exception:  # noqa: BLE001 — doctor must never crash on settings load
+        pass
+
     checks.append(_check_os())
     checks.append(_check_python())
     checks.append(_check_install_manager())
@@ -923,3 +944,9 @@ def _render_human(checks: list[CheckResult]) -> None:
         console.print("[yellow]! WARNING: install is functional but has issues.[/yellow]")
     else:
         console.print("[green bold]✓ All checks passed.[/green bold]")
+
+    console.print()
+    console.print(
+        "[dim]Tip: `marvis guide` explains how Marvis organizes work — point "
+        "your agent at an existing folder to adopt it.[/dim]"
+    )

marvisx_cli-0.3.7/core/cli/marvis_guide.py

@@ -0,0 +1,112 @@
+# v1.0.0 - 2026-06-04 - C1: `marvis guide` — the single callable "Marvis way" guide.
+"""``marvis guide`` — print the one reference for how Marvis works.
+
+The guide is a packaged markdown data-file (``core/cli/guides/marvis-way.md``)
+loaded at runtime via ``importlib.resources`` so it resolves identically from a
+source checkout and from an installed wheel. It is the SAME content published on
+the web (so an agent can read it before installing anything); this command is
+the offline, already-installed surface.
+
+Registered onto the SAME Typer ``app`` as ``marvis init`` via ``register(app)``,
+exactly like ``marvis_doctor`` / ``marvis_telemetry``.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import typer
+
+_PANEL_GUIDE = "Guide"
+_GUIDE_PACKAGE = "core.cli.guides"
+_GUIDE_FILE = "marvis-way.md"
+
+
+def _load_guide() -> str:
+    """Read the packaged guide markdown (works from checkout and from wheel)."""
+    import importlib.resources as ir
+
+    return ir.files(_GUIDE_PACKAGE).joinpath(_GUIDE_FILE).read_text(encoding="utf-8")
+
+
+def _split_sections(text: str) -> dict[str, str]:
+    """Map each lowercased H2 title → its section markdown (title line included)."""
+    sections: dict[str, str] = {}
+    current_key: str | None = None
+    current: list[str] = []
+    for line in text.splitlines(keepends=True):
+        if line.startswith("## "):
+            if current_key is not None:
+                sections[current_key] = "".join(current)
+            current_key = line[3:].strip().lower()
+            current = [line]
+        elif current_key is not None:
+            current.append(line)
+    if current_key is not None:
+        sections[current_key] = "".join(current)
+    return sections
+
+
+def guide_cmd(
+    section: str | None = typer.Option(
+        None,
+        "--section",
+        "-s",
+        help="Print only one section (e.g. frontmatter, lifecycle, adopt).",
+    ),
+    list_sections: bool = typer.Option(
+        False, "--list", help="List the section names and exit."
+    ),
+    json_out: bool = typer.Option(
+        False, "--json", help="Emit the guide as JSON to stdout."
+    ),
+    no_pager: bool = typer.Option(
+        False, "--no-pager", help="Print straight to stdout, never page."
+    ),
+) -> None:
+    """Print the Marvis way: how projects, tasks, the graph and the brain fit together."""
+    import click
+
+    text = _load_guide()
+    sections = _split_sections(text)
+
+    if list_sections:
+        for name in sections:
+            click.echo(name)
+        return
+
+    if section:
+        key = section.strip().lower()
+        if key not in sections:
+            from core.cli._runtime_ctx import err_console
+
+            err_console.print(
+                f"[red]No section '{section}'. Available: {', '.join(sections)}[/red]"
+            )
+            raise typer.Exit(2)
+        text = sections[key]
+
+    if json_out:
+        import json
+
+        if section:
+            payload: dict[str, Any] = {
+                "section": section.strip().lower(),
+                "markdown": text,
+            }
+        else:
+            payload = {"guide": text, "sections": list(sections)}
+        click.echo(json.dumps(payload))
+        return
+
+    # Page for a human TTY; plain stdout when piped or asked. echo_via_pager
+    # silently skips the pager when stdin isn't a TTY, so gate on stdout instead.
+    if sys.stdout.isatty() and not no_pager:
+        click.echo_via_pager(text)
+    else:
+        click.echo(text)
+
+
+def register(app: typer.Typer) -> None:
+    """Attach ``guide`` onto an existing Typer app."""
+    app.command("guide", rich_help_panel=_PANEL_GUIDE)(guide_cmd)