memctl 0.2.0__tar.gz → 0.3.0__tar.gz

{memctl-0.2.0 → memctl-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memctl
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Unix-native memory control plane for LLM orchestration
 Author-email: Olivier Vitrac <olivier.vitrac@adservio.fr>
 License: MIT
@@ -150,7 +150,22 @@ memctl search "authentication"
 memctl search "database" --json -k 5
 ```
 
-### 5. Inspect and manage
+### 5. Inspect a folder (one-liner)
+
+```bash
+# Auto-mounts, auto-syncs, and inspects — all in one command
+memctl inspect docs/
+
+# Same in JSON (for scripts)
+memctl inspect docs/ --json
+
+# Skip sync (use cached state)
+memctl inspect docs/ --no-sync
+```
+
+`inspect` auto-mounts the folder if needed, checks staleness, syncs only if stale, and produces a structural summary. All implicit actions are announced on stderr.
+
+### 6. Manage
 
 ```bash
 memctl show MEM-abc123def456     # Show item details
@@ -180,6 +195,9 @@ memctl <command> [options]
 | `stats` | Store statistics |
 | `consolidate [--dry-run]` | Deterministic merge of similar STM items |
 | `loop QUERY --llm CMD` | Bounded recall-answer loop with LLM |
+| `mount PATH` | Register a folder as a structured source |
+| `sync [PATH]` | Delta-sync mounted folders into the store |
+| `inspect [PATH]` | Structural inspection with auto-mount and auto-sync |
 | `serve` | Start MCP server (requires `memctl[mcp]`) |
 
 ### Global Flags
@@ -291,6 +309,52 @@ memctl push "database schema" --source src/ \
 memctl loop --replay trace.jsonl "original question"
 ```
 
+#### `memctl mount`
+
+```bash
+memctl mount PATH [--name NAME] [--ignore PATTERN ...] [--lang HINT]
+memctl mount --list
+memctl mount --remove ID_OR_NAME
+```
+
+Registers a folder as a structured source. Stores metadata only — no scanning, no ingestion. The folder contents are synced separately via `sync` or automatically via `inspect`.
+
+#### `memctl sync`
+
+```bash
+memctl sync [PATH] [--full] [--json] [--quiet]
+```
+
+Delta-syncs mounted folders into the memory store. Uses a 3-tier delta rule:
+1. **New file** (not in DB) → ingest
+2. **Size + mtime match** → fast skip (no hashing)
+3. **Hash compare** → ingest only if content changed
+
+If `PATH` is given but not yet mounted, it is auto-registered first. `--full` forces re-processing of all files.
+
+#### `memctl inspect`
+
+```bash
+# Orchestration mode — auto-mounts, auto-syncs, and inspects
+memctl inspect PATH [--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
+                    [--budget N] [--ignore PATTERN ...] [--json] [--quiet]
+
+# Classic mode — inspect an existing mount by ID/name
+memctl inspect --mount ID_OR_NAME [--budget N] [--json] [--quiet]
+```
+
+When given a positional `PATH`, inspect operates in **orchestration mode**:
+1. **Auto-mount** — registers the folder if not already mounted
+2. **Staleness check** — compares disk inventory (path/size/mtime triples) against the store
+3. **Auto-sync** — runs delta sync only if stale (or always/never per `--sync`)
+4. **Inspect** — generates a deterministic structural summary
+
+Output includes file/chunk/size totals, per-folder breakdown, per-extension distribution, top-5 largest files, and rule-based observations. All paths in output are mount-relative (never absolute).
+
+`--mount-mode ephemeral` removes the mount record after inspection (corpus data is preserved). `--no-sync` is shorthand for `--sync never`.
+
+All implicit actions (mount, sync) are announced on stderr. `--quiet` suppresses them.
+
 ---
 
 ## Environment Variables
@@ -348,6 +412,15 @@ memctl search "" --json | jq -c '.[]'
 
 # Iterative recall-answer loop with trace
 memctl push "auth flow" --source docs/ | memctl loop "auth flow" --llm "claude -p" --trace
+
+# One-liner: inspect a folder (auto-mount + auto-sync)
+memctl inspect docs/
+
+# Inspect in JSON, pipe to jq for extension breakdown
+memctl inspect src/ --json | jq '.extensions'
+
+# Inspect without syncing (use cached state)
+memctl inspect docs/ --no-sync --json
 ```
 
 ---
@@ -402,14 +475,17 @@ Tool names use the `memory_*` prefix for drop-in compatibility with RAGIX.
 ```
 memctl/
 ├── types.py           Data model (MemoryItem, MemoryProposal, MemoryEvent, MemoryLink)
-├── store.py           SQLite + FTS5 + WAL backend (9 tables + schema_meta)
+├── store.py           SQLite + FTS5 + WAL backend (10 tables + schema_meta)
 ├── extract.py         Text extraction (text files + binary format dispatch)
 ├── ingest.py          Paragraph chunking, SHA-256 dedup, source resolution
 ├── policy.py          Write governance (30 patterns: secrets, injection, instructional)
 ├── config.py          Dataclass configuration
 ├── similarity.py      Stdlib text similarity (Jaccard + SequenceMatcher)
 ├── loop.py            Bounded recall-answer loop controller
-├── cli.py             9 CLI commands
+├── mount.py           Folder mount registration and management
+├── sync.py            Delta sync with 3-tier change detection
+├── inspect.py         Structural inspection and orchestration
+├── cli.py             12 CLI commands
 ├── consolidate.py     Deterministic merge (Jaccard clustering, no LLM)
 ├── proposer.py        LLM output parsing (delimiter + regex)
 └── mcp/
@@ -418,7 +494,7 @@ memctl/
     └── server.py      FastMCP server entry point
 ```
 
-16 source files. ~5,300 lines. Zero compiled dependencies for core.
+19 source files. ~7,300 lines. Zero compiled dependencies for core.
 
 ### Memory Tiers
 
@@ -485,7 +561,7 @@ Deterministic, no-LLM merge pipeline:
 
 ## Database Schema
 
-Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
+Single SQLite file with WAL mode. 10 tables + 1 FTS5 virtual table:
 
 | Table | Purpose |
 |-------|---------|
@@ -494,13 +570,14 @@ Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
 | `memory_events` | Audit log (every read/write/consolidate) |
 | `memory_links` | Directional relationships (supersedes, supports, etc.) |
 | `memory_embeddings` | Reserved for RAGIX (empty in memctl) |
-| `corpus_hashes` | SHA-256 file dedup registry |
+| `corpus_hashes` | SHA-256 file dedup + mount metadata (mount_id, rel_path, ext, size_bytes, mtime_epoch, lang_hint) |
 | `corpus_metadata` | Corpus-level metadata |
 | `schema_meta` | Schema version, creation info |
 | `memory_palace_locations` | Reserved for RAGIX |
+| `memory_mounts` | Registered folder mounts (path, name, ignore patterns, lang hint) |
 | `memory_items_fts` | FTS5 virtual table for full-text search |
 
-Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
+Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=2`. Migration from v1 is additive (ALTER TABLE ADD COLUMN) and idempotent.
 
 ---
 
@@ -509,17 +586,20 @@ Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
 memctl is extracted from [RAGIX](https://github.com/ovitrac/RAGIX) and maintains schema-identical databases. To upgrade:
 
 ```bash
-pip install ragix[all]
+git clone git@github.com:ovitrac/RAGIX.git
+cd RAGIX
+pip install -e .[all]
 # Point at the same database — all items carry over
-ragix memory stats --db .memory/memory.db
+ragix memory stats --db /path/to/your/.memory/memory.db
 ```
 
 | Feature | memctl | RAGIX |
 |---------|--------|-------|
-| SQLite schema | Identical | Identical |
+| SQLite schema | Forward-compatible (RAGIX can open memctl DBs) | Superset |
 | Injection format | `format_version=1` | `format_version=1` |
 | MCP tool names | `memory_*` | `memory_*` |
 | FTS5 recall | Yes | Yes (+ hybrid embeddings) |
+| Folder mount + sync | Yes (v0.3+) | No |
 | Embeddings | No | Yes (FAISS + Ollama) |
 | LLM-assisted merge | No | Yes |
 | Graph-RAG | No | Yes |
@@ -573,7 +653,7 @@ pip install memctl[dev]
 pytest tests/ -v
 ```
 
-332 tests covering types, store, policy, ingest, text extraction, similarity, loop controller, forward compatibility, contracts, CLI (subprocess), and pipe composition.
+479 tests across 14 test files covering types, store, policy, ingest, text extraction, similarity, loop controller, mount, sync, inspect, forward compatibility, contracts, CLI (subprocess), and pipe composition.
 
 ---
 

{memctl-0.2.0 → memctl-0.3.0}/README.md

@@ -107,7 +107,22 @@ memctl search "authentication"
 memctl search "database" --json -k 5
 ```
 
-### 5. Inspect and manage
+### 5. Inspect a folder (one-liner)
+
+```bash
+# Auto-mounts, auto-syncs, and inspects — all in one command
+memctl inspect docs/
+
+# Same in JSON (for scripts)
+memctl inspect docs/ --json
+
+# Skip sync (use cached state)
+memctl inspect docs/ --no-sync
+```
+
+`inspect` auto-mounts the folder if needed, checks staleness, syncs only if stale, and produces a structural summary. All implicit actions are announced on stderr.
+
+### 6. Manage
 
 ```bash
 memctl show MEM-abc123def456     # Show item details
@@ -137,6 +152,9 @@ memctl <command> [options]
 | `stats` | Store statistics |
 | `consolidate [--dry-run]` | Deterministic merge of similar STM items |
 | `loop QUERY --llm CMD` | Bounded recall-answer loop with LLM |
+| `mount PATH` | Register a folder as a structured source |
+| `sync [PATH]` | Delta-sync mounted folders into the store |
+| `inspect [PATH]` | Structural inspection with auto-mount and auto-sync |
 | `serve` | Start MCP server (requires `memctl[mcp]`) |
 
 ### Global Flags
@@ -248,6 +266,52 @@ memctl push "database schema" --source src/ \
 memctl loop --replay trace.jsonl "original question"
 ```
 
+#### `memctl mount`
+
+```bash
+memctl mount PATH [--name NAME] [--ignore PATTERN ...] [--lang HINT]
+memctl mount --list
+memctl mount --remove ID_OR_NAME
+```
+
+Registers a folder as a structured source. Stores metadata only — no scanning, no ingestion. The folder contents are synced separately via `sync` or automatically via `inspect`.
+
+#### `memctl sync`
+
+```bash
+memctl sync [PATH] [--full] [--json] [--quiet]
+```
+
+Delta-syncs mounted folders into the memory store. Uses a 3-tier delta rule:
+1. **New file** (not in DB) → ingest
+2. **Size + mtime match** → fast skip (no hashing)
+3. **Hash compare** → ingest only if content changed
+
+If `PATH` is given but not yet mounted, it is auto-registered first. `--full` forces re-processing of all files.
+
+#### `memctl inspect`
+
+```bash
+# Orchestration mode — auto-mounts, auto-syncs, and inspects
+memctl inspect PATH [--sync auto|always|never] [--no-sync] [--mount-mode persist|ephemeral]
+                    [--budget N] [--ignore PATTERN ...] [--json] [--quiet]
+
+# Classic mode — inspect an existing mount by ID/name
+memctl inspect --mount ID_OR_NAME [--budget N] [--json] [--quiet]
+```
+
+When given a positional `PATH`, inspect operates in **orchestration mode**:
+1. **Auto-mount** — registers the folder if not already mounted
+2. **Staleness check** — compares disk inventory (path/size/mtime triples) against the store
+3. **Auto-sync** — runs delta sync only if stale (or always/never per `--sync`)
+4. **Inspect** — generates a deterministic structural summary
+
+Output includes file/chunk/size totals, per-folder breakdown, per-extension distribution, top-5 largest files, and rule-based observations. All paths in output are mount-relative (never absolute).
+
+`--mount-mode ephemeral` removes the mount record after inspection (corpus data is preserved). `--no-sync` is shorthand for `--sync never`.
+
+All implicit actions (mount, sync) are announced on stderr. `--quiet` suppresses them.
+
 ---
 
 ## Environment Variables
@@ -305,6 +369,15 @@ memctl search "" --json | jq -c '.[]'
 
 # Iterative recall-answer loop with trace
 memctl push "auth flow" --source docs/ | memctl loop "auth flow" --llm "claude -p" --trace
+
+# One-liner: inspect a folder (auto-mount + auto-sync)
+memctl inspect docs/
+
+# Inspect in JSON, pipe to jq for extension breakdown
+memctl inspect src/ --json | jq '.extensions'
+
+# Inspect without syncing (use cached state)
+memctl inspect docs/ --no-sync --json
 ```
 
 ---
@@ -359,14 +432,17 @@ Tool names use the `memory_*` prefix for drop-in compatibility with RAGIX.
 ```
 memctl/
 ├── types.py           Data model (MemoryItem, MemoryProposal, MemoryEvent, MemoryLink)
-├── store.py           SQLite + FTS5 + WAL backend (9 tables + schema_meta)
+├── store.py           SQLite + FTS5 + WAL backend (10 tables + schema_meta)
 ├── extract.py         Text extraction (text files + binary format dispatch)
 ├── ingest.py          Paragraph chunking, SHA-256 dedup, source resolution
 ├── policy.py          Write governance (30 patterns: secrets, injection, instructional)
 ├── config.py          Dataclass configuration
 ├── similarity.py      Stdlib text similarity (Jaccard + SequenceMatcher)
 ├── loop.py            Bounded recall-answer loop controller
-├── cli.py             9 CLI commands
+├── mount.py           Folder mount registration and management
+├── sync.py            Delta sync with 3-tier change detection
+├── inspect.py         Structural inspection and orchestration
+├── cli.py             12 CLI commands
 ├── consolidate.py     Deterministic merge (Jaccard clustering, no LLM)
 ├── proposer.py        LLM output parsing (delimiter + regex)
 └── mcp/
@@ -375,7 +451,7 @@ memctl/
     └── server.py      FastMCP server entry point
 ```
 
-16 source files. ~5,300 lines. Zero compiled dependencies for core.
+19 source files. ~7,300 lines. Zero compiled dependencies for core.
 
 ### Memory Tiers
 
@@ -442,7 +518,7 @@ Deterministic, no-LLM merge pipeline:
 
 ## Database Schema
 
-Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
+Single SQLite file with WAL mode. 10 tables + 1 FTS5 virtual table:
 
 | Table | Purpose |
 |-------|---------|
@@ -451,13 +527,14 @@ Single SQLite file with WAL mode. 9 tables + 1 FTS5 virtual table:
 | `memory_events` | Audit log (every read/write/consolidate) |
 | `memory_links` | Directional relationships (supersedes, supports, etc.) |
 | `memory_embeddings` | Reserved for RAGIX (empty in memctl) |
-| `corpus_hashes` | SHA-256 file dedup registry |
+| `corpus_hashes` | SHA-256 file dedup + mount metadata (mount_id, rel_path, ext, size_bytes, mtime_epoch, lang_hint) |
 | `corpus_metadata` | Corpus-level metadata |
 | `schema_meta` | Schema version, creation info |
 | `memory_palace_locations` | Reserved for RAGIX |
+| `memory_mounts` | Registered folder mounts (path, name, ignore patterns, lang hint) |
 | `memory_items_fts` | FTS5 virtual table for full-text search |
 
-Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
+Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=2`. Migration from v1 is additive (ALTER TABLE ADD COLUMN) and idempotent.
 
 ---
 
@@ -466,17 +543,20 @@ Schema version is tracked in `schema_meta`. Current: `SCHEMA_VERSION=1`.
 memctl is extracted from [RAGIX](https://github.com/ovitrac/RAGIX) and maintains schema-identical databases. To upgrade:
 
 ```bash
-pip install ragix[all]
+git clone git@github.com:ovitrac/RAGIX.git
+cd RAGIX
+pip install -e .[all]
 # Point at the same database — all items carry over
-ragix memory stats --db .memory/memory.db
+ragix memory stats --db /path/to/your/.memory/memory.db
 ```
 
 | Feature | memctl | RAGIX |
 |---------|--------|-------|
-| SQLite schema | Identical | Identical |
+| SQLite schema | Forward-compatible (RAGIX can open memctl DBs) | Superset |
 | Injection format | `format_version=1` | `format_version=1` |
 | MCP tool names | `memory_*` | `memory_*` |
 | FTS5 recall | Yes | Yes (+ hybrid embeddings) |
+| Folder mount + sync | Yes (v0.3+) | No |
 | Embeddings | No | Yes (FAISS + Ollama) |
 | LLM-assisted merge | No | Yes |
 | Graph-RAG | No | Yes |
@@ -530,7 +610,7 @@ pip install memctl[dev]
 pytest tests/ -v
 ```
 
-332 tests covering types, store, policy, ingest, text extraction, similarity, loop controller, forward compatibility, contracts, CLI (subprocess), and pipe composition.
+479 tests across 14 test files covering types, store, policy, ingest, text extraction, similarity, loop controller, mount, sync, inspect, forward compatibility, contracts, CLI (subprocess), and pipe composition.
 
 ---
 

{memctl-0.2.0 → memctl-0.3.0}/memctl/__init__.py

@@ -7,7 +7,7 @@ Policy-governed, content-addressed, and forward-compatible with RAGIX.
 Author: Olivier Vitrac, PhD, HDR | olivier.vitrac@adservio.fr | Adservio
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from memctl.types import (
     MemoryItem,

{memctl-0.2.0 → memctl-0.3.0}/memctl/cli.py

@@ -10,6 +10,9 @@ Commands:
     memctl stats                             — store metrics
     memctl consolidate [--dry-run]           — merge + promote STM items
     memctl loop   "query" --llm CMD          — bounded recall-answer loop
+    memctl mount  <path> [--name N]          — register folder for sync
+    memctl sync   [<path>] [--full]          — scan + ingest mounted folders
+    memctl inspect [--mount M] [--budget N]  — structural injection block → stdout
     memctl serve  [--fts-tokenizer FR]       — start MCP server (foreground)
 
 Environment variables:
@@ -670,6 +673,205 @@ def cmd_loop(args: argparse.Namespace) -> None:
         sys.exit(1)
 
 
+# ===========================================================================
+# Command: mount  (register folder for sync)
+# ===========================================================================
+
+
+def cmd_mount(args: argparse.Namespace) -> None:
+    """Register, list, or remove folder mounts."""
+    from memctl.mount import register_mount, list_mounts, remove_mount
+
+    db_path = _resolve_db(args)
+
+    if getattr(args, "list", False):
+        mounts = list_mounts(db_path)
+        if getattr(args, "json", False):
+            print(json.dumps(mounts, indent=2, ensure_ascii=False))
+            return
+        if not mounts:
+            _info("No mounts registered.")
+            return
+        else:
+            for m in mounts:
+                synced = m["last_sync_at"] or "never"
+                label = f" ({m['name']})" if m["name"] else ""
+                print(f"  {m['mount_id']}{label}  {m['path']}  synced={synced}")
+        return
+
+    if getattr(args, "remove", None):
+        ok = remove_mount(db_path, args.remove)
+        if ok:
+            _info(f"Removed mount: {args.remove}")
+        else:
+            _warn(f"Mount not found: {args.remove}")
+            sys.exit(1)
+        return
+
+    # Register mode (default)
+    if not args.path:
+        _warn("Usage: memctl mount <path> [--name NAME] [--ignore PATTERN...]")
+        sys.exit(1)
+
+    ignore = getattr(args, "ignore", None) or []
+    lang = getattr(args, "lang", None)
+    name = getattr(args, "name", None)
+
+    try:
+        mount_id = register_mount(
+            db_path, args.path,
+            name=name,
+            ignore_patterns=ignore,
+            lang_hint=lang,
+        )
+    except (FileNotFoundError, NotADirectoryError) as e:
+        _warn(f"Error: {e}")
+        sys.exit(1)
+
+    _info(f"Mounted: {mount_id} → {os.path.realpath(args.path)}")
+
+
+# ===========================================================================
+# Command: sync  (scan + ingest mounted folders)
+# ===========================================================================
+
+
+def cmd_sync(args: argparse.Namespace) -> None:
+    """Sync mounted folders into the memory store."""
+    from memctl.sync import sync_mount, sync_all
+
+    db_path = _resolve_db(args)
+    full = getattr(args, "full", False)
+    quiet = getattr(args, "quiet", False)
+
+    if getattr(args, "path", None):
+        # Sync specific path
+        try:
+            result = sync_mount(
+                db_path, args.path,
+                delta=not full,
+                quiet=quiet,
+            )
+        except (FileNotFoundError, NotADirectoryError) as e:
+            _warn(f"Error: {e}")
+            sys.exit(1)
+
+        if getattr(args, "json", False):
+            print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))
+        else:
+            _info(
+                f"[sync] {result.files_new} new, {result.files_changed} changed, "
+                f"{result.files_unchanged} unchanged, {result.chunks_created} chunks"
+            )
+    else:
+        # Sync all mounts
+        results = sync_all(db_path, delta=not full, quiet=quiet)
+        if not results:
+            _info("[sync] No mounts registered. Use 'memctl mount <path>' or 'memctl sync <path>'.")
+            return
+        if getattr(args, "json", False):
+            print(json.dumps(
+                {k: v.to_dict() for k, v in results.items()},
+                indent=2, ensure_ascii=False,
+            ))
+        else:
+            for path, r in results.items():
+                _info(
+                    f"[sync] {path}: {r.files_new} new, {r.files_changed} changed, "
+                    f"{r.files_unchanged} unchanged, {r.chunks_created} chunks"
+                )
+
+
+# ===========================================================================
+# Command: inspect  (structural injection block → stdout)
+# ===========================================================================
+
+
+def cmd_inspect(args: argparse.Namespace) -> None:
+    """Generate a structural injection block from corpus metadata.
+
+    With positional path: auto-mount + auto-sync + inspect (orchestration mode).
+    Without positional path: inspect existing store (classic mode).
+    """
+    from memctl.inspect import inspect_mount, inspect_stats
+
+    db_path = _resolve_db(args)
+    budget = _resolve_budget(args)
+
+    # --- Orchestration mode: positional path provided ---
+    path = getattr(args, "path", None)
+    if path is not None:
+        from memctl.inspect import inspect_path
+
+        # Warn if --mount filter is also given (path takes precedence)
+        if getattr(args, "mount", None):
+            _warn("--mount filter ignored when positional path is provided")
+
+        sync_mode = (
+            "never" if getattr(args, "no_sync", False)
+            else getattr(args, "sync", "auto")
+        )
+        mount_mode = getattr(args, "mount_mode", "persist")
+        ignore = getattr(args, "ignore", None) or None
+
+        try:
+            result = inspect_path(
+                db_path, path,
+                sync_mode=sync_mode,
+                mount_mode=mount_mode,
+                budget=budget,
+                ignore_patterns=ignore,
+                log=_info,
+            )
+        except (FileNotFoundError, NotADirectoryError) as e:
+            _warn(str(e))
+            sys.exit(1)
+        except ValueError as e:
+            _warn(str(e))
+            sys.exit(1)
+
+        if getattr(args, "json", False):
+            print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))
+        else:
+            text = inspect_mount(
+                db_path,
+                mount_id=result.mount_id,
+                mount_label=result.mount_label,
+                budget=budget,
+            )
+            print(text)
+        return
+
+    # --- Classic mode: no positional path ---
+    mount_filter = getattr(args, "mount", None)
+    mount_id = None
+    mount_label = None
+    if mount_filter:
+        from memctl.store import MemoryStore
+        store = MemoryStore(db_path=db_path)
+        try:
+            m = store.read_mount(mount_filter)
+        finally:
+            store.close()
+        if m is None:
+            _warn(f"Mount not found: {mount_filter}")
+            sys.exit(1)
+        mount_id = m["mount_id"]
+        mount_label = m.get("name") or m["path"]
+
+    if getattr(args, "json", False):
+        stats = inspect_stats(db_path, mount_id=mount_id)
+        print(json.dumps(stats, indent=2, ensure_ascii=False))
+    else:
+        text = inspect_mount(
+            db_path,
+            mount_id=mount_id,
+            mount_label=mount_label,
+            budget=budget,
+        )
+        print(text)
+
+
 # ===========================================================================
 # Command: serve  (start MCP server)
 # ===========================================================================
@@ -890,6 +1092,73 @@ def main() -> None:
     )
     p_loop.set_defaults(func=cmd_loop)
 
+    # -- mount -------------------------------------------------------------
+    p_mount = sub.add_parser(
+        "mount", parents=[_common],
+        help="Register folder for sync",
+    )
+    p_mount.add_argument("path", nargs="?", default=None, help="Folder path to mount")
+    p_mount.add_argument("--name", default=None, help="Human-readable label")
+    p_mount.add_argument(
+        "--ignore", nargs="+", default=None,
+        help="Glob patterns to exclude during sync",
+    )
+    p_mount.add_argument(
+        "--lang", default=None, choices=["fr", "en", "mix"],
+        help="Language hint for FTS tokenizer selection",
+    )
+    p_mount.add_argument("--list", action="store_true", default=argparse.SUPPRESS, help="List mounts")
+    p_mount.add_argument("--remove", default=None, metavar="ID", help="Remove mount by ID or name")
+    p_mount.set_defaults(func=cmd_mount)
+
+    # -- sync --------------------------------------------------------------
+    p_sync = sub.add_parser(
+        "sync", parents=[_common],
+        help="Scan + ingest mounted folders",
+    )
+    p_sync.add_argument("path", nargs="?", default=None, help="Folder path (auto-registers)")
+    p_sync.add_argument(
+        "--full", action="store_true",
+        help="Re-process all files (ignore delta cache)",
+    )
+    p_sync.set_defaults(func=cmd_sync)
+
+    # -- inspect -----------------------------------------------------------
+    p_inspect = sub.add_parser(
+        "inspect", parents=[_common],
+        help="Structural injection block → stdout (auto-mounts/syncs if path given)",
+    )
+    p_inspect.add_argument(
+        "path", nargs="?", default=None,
+        help="Folder to inspect (auto-mounts and auto-syncs as needed)",
+    )
+    p_inspect.add_argument(
+        "--mount", default=None, metavar="ID_OR_NAME",
+        help="Filter by registered mount (classic mode, no positional path)",
+    )
+    p_inspect.add_argument(
+        "--budget", type=int, default=None,
+        help="Token budget (default: MEMCTL_BUDGET or 2200)",
+    )
+    p_inspect.add_argument(
+        "--sync", default="auto", choices=["auto", "always", "never"],
+        help="Sync mode: auto (default), always, or never",
+    )
+    p_inspect.add_argument(
+        "--no-sync", action="store_true", default=False,
+        help="Skip sync (equivalent to --sync=never)",
+    )
+    p_inspect.add_argument(
+        "--mount-mode", dest="mount_mode", default="persist",
+        choices=["persist", "ephemeral"],
+        help="Keep mount (persist, default) or remove after inspect (ephemeral)",
+    )
+    p_inspect.add_argument(
+        "--ignore", nargs="+", default=None,
+        help="Glob patterns to exclude when auto-mounting",
+    )
+    p_inspect.set_defaults(func=cmd_inspect)
+
     # -- serve -------------------------------------------------------------
     p_serve = sub.add_parser("serve", parents=[_common], help="Start MCP server")
     p_serve.add_argument(