footprinter-cli 1.1.0__tar.gz → 1.1.1__tar.gz

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: footprinter-cli
-Version: 1.1.0
+Version: 1.1.1
 Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
 Author: SwellCity Group
 License: MIT

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/bundled/config.example.yaml

@@ -86,8 +86,27 @@ exclusions:
 indexing:
   supported_extensions: []  # Empty = index ALL file types
   max_file_size_mb: 50      # MB; 0 = no size limit. 50 is generous for prose/docs.
+  # Cap on how many bytes the MCP read path (footprinter_read) pulls from a local
+  # file before decode/extraction. MB; 0 = no cap (read the whole file).
+  # Default 10 MB closes the old 500 KB silent-truncation gap so the read tool can
+  # return content the index already holds.
+  # The returned content is ALWAYS bounded to a payload-safe size regardless of
+  # this cap: a single MCP tool result has a ~1 MB protocol payload ceiling, so an
+  # oversized read returns a marked, in-budget slice (output_truncated) plus a
+  # pointer to semantic/keyword search — never a hard failure. That bound is a
+  # UTF-8 BYTE budget (sliced on a code-point boundary) sized under the ~1 MB JSON
+  # wall with headroom for JSON-escape expansion of multibyte content (CJK/emoji)
+  # and the result envelope — not a character count, so non-Latin scripts stay
+  # safe. Raise this cap to read more bytes from large files; for large documents,
+  # prefer search.
+  max_read_size_mb: 10
   lookback_days: 14         # Browser history window (days back to index)
-  content_snippets: false   # Extract file/email content previews for keyword search
+  # Opt-in (default off). When true, ingest reads each file/email and stores a
+  # short preview (~1000 chars/file) so keyword search matches file content, not
+  # just names. Cost: extra read work during ingest + the stored preview in SQLite.
+  # Enabling this after the first ingest backfills already-indexed files only on
+  # the next `fp ingest` run; new ingests populate previews automatically.
+  content_snippets: false
 
 # Semantic search — stores content as embeddings in a local ChromaDB database
 # Enables finding files and chats by meaning, not just keywords
@@ -99,6 +118,17 @@ semantic:
   # Add 'unlisted' to also embed hidden/dot-files.
   # vectorize_statuses:
   #   - listed
+  # Semantic file results — how much matched content to return per result.
+  # A chunk is ~1000 chars ≈ 250 tokens. Payload size ≈ max_chunks_per_file ×
+  # max_chunk_chars, so raise these for more context at higher token cost.
+  # Max characters of each matched chunk to return. Default 1000. 0 = no cap
+  # (return the whole chunk).
+  max_chunk_chars: 1000
+  # How many matched chunks to return per file, best-relevance first. Default 3.
+  # Clamped to [1, 20] — values above the cap are bounded to keep payloads sane.
+  # The per-result `chunks` list is returned only on the vector (semantic) path;
+  # the FTS5 keyword fallback (used when semantic search is unavailable) omits it.
+  max_chunks_per_file: 3
 
 # Vectorization — controls what gets embedded for semantic search
 # Requires semantic.file_vectorization: true to take effect for files

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/cli/mcp_setup.py

@@ -2,11 +2,11 @@
 MCP Configuration Helper for AI clients.
 
 Detects config paths for MCP clients, generates the correct
-MCP server snippet for this Footprinter installation, and optionally writes it.
+MCP server config block for this Footprinter installation, and optionally writes it.
 
 Usage:
-    fp setup mcp             # Print MCP snippet to paste
-    fp setup mcp --claude    # Write/merge snippet into Claude Desktop config (with backup)
+    fp setup mcp             # Print MCP config block to paste
+    fp setup mcp --claude    # Write/merge config block into Claude Desktop config (with backup)
 """
 
 import json
@@ -125,8 +125,8 @@ def get_mcp_command(project_root: Path = None) -> tuple[str, list[str]]:
     return sys.executable, ["-m", "footprinter.mcp"]
 
 
-def generate_snippet(project_root: Path = None) -> dict:
-    """Generate the MCP server config snippet as a dict.
+def generate_config_block(project_root: Path = None) -> dict:
+    """Generate the MCP server config block as a dict.
 
     Args:
         project_root: Override project root (default: auto-detected).
@@ -151,13 +151,13 @@ def generate_snippet(project_root: Path = None) -> dict:
     return {"mcpServers": {"footprinter": server_config}}
 
 
-def write_config(snippet: dict, config_path: Path = None) -> bool:
-    """Write or merge the MCP snippet into Claude Desktop config.
+def write_config(config_block: dict, config_path: Path = None) -> bool:
+    """Write or merge the MCP config block into Claude Desktop config.
 
     Creates a backup before modifying an existing file.
 
     Args:
-        snippet: The snippet dict from generate_snippet().
+        config_block: The config block dict from generate_config_block().
         config_path: Override config path (default: auto-detected).
 
     Returns:
@@ -182,7 +182,7 @@ def write_config(snippet: dict, config_path: Path = None) -> bool:
     # Merge: add/update mcpServers.footprinter
     if "mcpServers" not in existing:
         existing["mcpServers"] = {}
-    existing["mcpServers"]["footprinter"] = snippet["mcpServers"]["footprinter"]
+    existing["mcpServers"]["footprinter"] = config_block["mcpServers"]["footprinter"]
 
     # Backup existing file
     if path.exists():
@@ -298,13 +298,13 @@ def print_client_paths():
     console.print(table)
 
 
-def print_snippet(snippet: dict):
-    """Display the MCP snippet for manual pasting.
+def print_config_block(config_block: dict):
+    """Display the MCP config block for manual pasting.
 
     Args:
-        snippet: The snippet dict from generate_snippet().
+        config_block: The config block dict from generate_config_block().
     """
-    json_str = json.dumps(snippet, indent=2)
+    json_str = json.dumps(config_block, indent=2)
     console.print()
     console.print("Add this to your MCP client config:")
     console.print(Panel(json_str, title="MCP Config"))

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/cli/setup.py

@@ -233,17 +233,17 @@ def _handle_setup(args) -> None:
 
 def _add_mcp_parser(subparsers, *, formatter_class=None):
     """Add the MCP subparser with --claude flag."""
-    kwargs = {"help": "Show or install the MCP server snippet"}
+    kwargs = {"help": "Show or install the MCP server config block"}
     if formatter_class:
         kwargs.update(
             description=(
-                "Show the MCP server snippet for AI clients, or write it automatically.\n\n"
-                "Bare command prints the JSON snippet for manual copy/paste into any MCP client.\n"
+                "Show the MCP server config block for AI clients, or write it automatically.\n\n"
+                "Bare command prints the JSON config block for manual copy/paste into any MCP client.\n"
                 "Use --claude to write it directly to Claude Desktop config (creates a backup)."
             ),
             epilog=(
                 "examples:\n"
-                "  fp setup mcp               Print MCP snippet for manual config\n"
+                "  fp setup mcp               Print MCP config block for manual config\n"
                 "  fp setup mcp --claude      Write to Claude Desktop config (creates backup)"
             ),
             formatter_class=formatter_class,
@@ -252,7 +252,7 @@ def _add_mcp_parser(subparsers, *, formatter_class=None):
     parser.add_argument(
         "--claude",
         action="store_true",
-        help="Write/merge snippet into Claude Desktop config (creates backup)",
+        help="Write/merge config block into Claude Desktop config (creates backup)",
     )
     return parser
 
@@ -263,14 +263,14 @@ def _dispatch_mcp(args) -> None:
         console.print("[red]MCP protocol library not installed.[/red] Run: pip install mcp")
         sys.exit(1)
 
-    snippet = mcp_setup.generate_snippet()
+    config_block = mcp_setup.generate_config_block()
 
     if getattr(args, "claude", False):
-        ok = mcp_setup.write_config(snippet)
+        ok = mcp_setup.write_config(config_block)
         sys.exit(0 if ok else 1)
 
-    # Default: print snippet
-    mcp_setup.print_snippet(snippet)
+    # Default: print config block
+    mcp_setup.print_config_block(config_block)
 
 
 def _handle_setup_inner(args) -> None:
@@ -842,12 +842,13 @@ def collect_vectorization_answers(
     """
     existing_vec = (existing or {}).get("vectorization", {})
     existing_semantic = (existing or {}).get("semantic", {})
-    # Fresh installs default to ON so `fp search` returns content matches, not
-    # just filenames; reconfigure runs preserve the user's prior choice.
+    # Fresh installs default to OFF: content snippets are an informed opt-in
+    # (they read and store file content), so the wizard presents the choice
+    # without pre-selecting it. Reconfigure runs preserve the user's prior choice.
     if existing is not None and "indexing" in existing and "content_snippets" in existing["indexing"]:
         snippets_default = existing["indexing"]["content_snippets"]
     else:
-        snippets_default = True
+        snippets_default = False
     file_types = existing_vec.get("file_types", list(DEFAULT_FILE_TYPES))
     existing_excludes = existing_vec.get("exclude_patterns", [])
 
@@ -868,7 +869,9 @@ def collect_vectorization_answers(
         "  [bold]Local only[/bold]: previews are written to a local SQLite database\n"
         "  on your machine. Nothing is uploaded or shared, and the MCP client only sees\n"
         "  content when you grant explicit permission via fp permission.\n"
-        "  [dim]Trade-off: Footprinter keeps a stored copy of file (and connector) previews on disk.[/dim]"
+        "  [dim]Trade-off: Footprinter keeps a stored copy of file (and connector) previews on disk.[/dim]\n"
+        "  [dim]Enabling this later only backfills already-indexed files when you\n"
+        "  re-run `fp ingest`; new ingests populate previews automatically.[/dim]"
     )
     content_snippets = Confirm.ask("  Enable file content snippets?", default=snippets_default)
 
@@ -1333,25 +1336,25 @@ def offer_setup_claude() -> bool:
         return False
 
     try:
-        snippet = mcp_setup.generate_snippet()
+        config_block = mcp_setup.generate_config_block()
     except Exception as e:  # Intentional broad catch: user-facing CLI; errors shown to console, not re-raised
         console.print(f"  [yellow]MCP setup failed: {e}[/yellow]")
         console.print("  [dim]Run manually: fp setup mcp --claude[/dim]")
         return False
 
-    # Offer snippet for manual copy/paste (Cursor, Windsurf, etc.)
+    # Offer config block for manual copy/paste (Cursor, Windsurf, etc.)
     if Confirm.ask(
-        "\nView MCP config snippet (for Claude Code, Cursor, VS Code, and other clients)?",
+        "\nView MCP config block (for Claude Code, Cursor, VS Code, and other clients)?",
         default=True,
     ):
-        mcp_setup.print_snippet(snippet)
+        mcp_setup.print_config_block(config_block)
 
     # Offer Claude Desktop auto-config
     if not Confirm.ask("\nConfigure Claude Desktop automatically?", default=False):
         return False
 
     try:
-        mcp_setup.write_config(snippet)
+        mcp_setup.write_config(config_block)
         console.print("  [green]Claude Desktop MCP configured.[/green]")
         return True
     except Exception as e:  # Intentional broad catch: user-facing CLI; errors shown to console, not re-raised

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/db/clients.py

@@ -227,7 +227,7 @@ def get_client(conn: sqlite3.Connection, client_id: int) -> Optional[dict]:
     cursor.execute(
         """SELECT id, name, slug, client_type, status,
                   visibility, access,
-                  visibility_source, access_source
+                  visibility_source, access_source, context_path
            FROM clients WHERE id = ?""",
         (client_id,),
     )
@@ -245,6 +245,7 @@ def get_client(conn: sqlite3.Connection, client_id: int) -> Optional[dict]:
         "access": row["access"] or "inherit",
         "visibility_source": row["visibility_source"],
         "access_source": row["access_source"],
+        "context_path": row["context_path"],
     }
 
     # Attached projects
@@ -282,7 +283,7 @@ def find_by_name_fuzzy(conn: sqlite3.Connection, name: str) -> list[dict]:
     rows = conn.execute(
         """SELECT id, name, slug, client_type, status,
                   created_at, visibility, access,
-                  visibility_source, access_source
+                  visibility_source, access_source, context_path
            FROM clients WHERE name LIKE ?""",
         (f"%{name}%",),
     ).fetchall()

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/db/folders.py

@@ -171,7 +171,7 @@ def get_folder_by_path(conn: sqlite3.Connection, path: str) -> dict | None:
         """SELECT id, path, relative_path, name, source, status,
                   direct_file_count, total_size_bytes, scanned_at,
                   project_id, external_id, account, visibility, access,
-                  visibility_source, access_source
+                  visibility_source, access_source, context_path
            FROM folders WHERE path = ?""",
         (path,),
     ).fetchone()
@@ -184,7 +184,7 @@ def get_folder_by_relative_path(conn: sqlite3.Connection, relative_path: str) ->
         """SELECT id, path, relative_path, name, source, status,
                   direct_file_count, total_size_bytes, scanned_at,
                   project_id, external_id, account, visibility, access,
-                  visibility_source, access_source
+                  visibility_source, access_source, context_path
            FROM folders WHERE relative_path = ?""",
         (relative_path,),
     ).fetchone()

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/db/projects.py

@@ -65,7 +65,7 @@ def find_by_name_fuzzy(conn: sqlite3.Connection, name: str) -> list[dict]:
     rows = conn.execute(
         """SELECT id, name, status, client,
                   description, visibility, access,
-                  visibility_source, access_source
+                  visibility_source, access_source, context_path
            FROM projects
            WHERE name LIKE ?""",
         (f"%{name}%",),

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/db/search.py

@@ -18,6 +18,7 @@ from footprinter.db.sql_utils import (
     paginated_response,
     split_query_terms,
 )
+from footprinter.utils.text import EXCERPT_BUDGET, build_excerpt
 
 
 def _status_clause(
@@ -196,7 +197,8 @@ def search_files_keyword(
         f"""
         SELECT file.id, file.source, file.name, file.path, file.content_type,
                file.size_bytes, file.modified_at, file.account, file.mime_type,
-               file.visibility, file.status, file.status_reason,
+               file.visibility, file.access, file.status, file.status_reason,
+               file.content_preview,
                project.name AS project_name, client.name AS client
         FROM files file
         {fts_join}
@@ -209,25 +211,44 @@ def search_files_keyword(
         params,
     ).fetchall()
 
-    return [
-        {
-            "id": r["id"],
-            "source": r["source"],
-            "name": r["name"],
-            "path": r["path"],
-            "content_type": r["content_type"],
-            "size_bytes": r["size_bytes"],
-            "modified_at": r["modified_at"],
-            "account": r["account"],
-            "mime_type": r["mime_type"],
-            "project": r["project_name"],
-            "client": r["client"],
-            "visibility": r["visibility"],
-            "status": r["status"],
-            "status_reason": r["status_reason"],
-        }
-        for r in rows
-    ]
+    # Function-local import: services.access_service pulls in db.chats/files,
+    # which load this module via db/__init__, so a module-level import here
+    # would close an import cycle. Deferring to call time breaks the loop while
+    # still using the one canonical permission resolver.
+    from footprinter.services.access_service import resolve_inherit_permission
+
+    results = []
+    for r in rows:
+        # File-excerpt precedence: content_preview when present and the
+        # canonical resolver puts access at 'allow', else name/path. Using
+        # resolve_inherit_permission honors a global-deny policy for 'inherit'
+        # files and fails closed on NULL/unexpected values, so the in-DB
+        # excerpt decision agrees with the service-layer content-gating net.
+        if r["content_preview"] and resolve_inherit_permission(r["access"]) == "allow":
+            excerpt_fields = build_excerpt(r["content_preview"], source="content_preview")
+        else:
+            excerpt_fields = build_excerpt(f"{r['name']} — {r['path'] or ''}", source="title")
+        results.append(
+            {
+                "id": r["id"],
+                "source": r["source"],
+                "name": r["name"],
+                "path": r["path"],
+                "content_type": r["content_type"],
+                "size_bytes": r["size_bytes"],
+                "modified_at": r["modified_at"],
+                "account": r["account"],
+                "mime_type": r["mime_type"],
+                "project": r["project_name"],
+                "client": r["client"],
+                "visibility": r["visibility"],
+                "access": r["access"],
+                "status": r["status"],
+                "status_reason": r["status_reason"],
+                **excerpt_fields,
+            }
+        )
+    return results
 
 
 def search_emails_keyword(
@@ -322,7 +343,7 @@ def search_emails_keyword(
             "received_at": r["received_at"],
             "account": r["account"],
             "labels": r["labels"],
-            "snippet": r["body_preview"],
+            **build_excerpt(r["body_preview"] or "", source="body_preview"),
             "project_name": r["project_name"],
             "client_name": r["client_name"],
             "visibility": r["visibility"],
@@ -335,6 +356,122 @@ def search_emails_keyword(
     ]
 
 
+# Bounds on the per-hit message fetch in ``chat_message_excerpt``. The excerpt
+# only ever surfaces a ~``EXCERPT_BUDGET``-char window (centered on the first
+# query-term match, or position 0 for title-only hits), so loading the whole
+# conversation is wasted CPU/memory. Two guards cap the fetch:
+# ``_CHAT_EXCERPT_MSG_LIMIT`` caps row transfer for chats with many short
+# messages, and ``_CHAT_EXCERPT_FETCH_BUDGET`` caps total characters for chats
+# with a few enormous messages. The char budget
+# is a comfortable multiple of ``EXCERPT_BUDGET`` so a normal chat's window is
+# byte-for-byte unchanged; the row cap is large enough that no normal chat's
+# leading content is truncated before the char budget is hit.
+_CHAT_EXCERPT_MSG_LIMIT = 64
+_CHAT_EXCERPT_FETCH_BUDGET = EXCERPT_BUDGET * 4
+
+
+def chat_message_excerpt(
+    conn: sqlite3.Connection,
+    chat_id: int,
+    query: str,
+    title: str,
+    *,
+    status: "str | list[str] | None" = None,
+) -> dict:
+    """Re-derive a chat's excerpt from its message content at query time.
+
+    Keyword chat search matches the title only, so the re-derived excerpt is a
+    query-centered window over the conversation's message content (the opening
+    of the conversation when the hit was on the title). Falls back to the chat
+    ``title`` only when the chat has no listed message content. The excerpt
+    fields are built via the shared :func:`build_excerpt` so the size budget and
+    provenance match every other content-bearing source.
+
+    The message fetch is **bounded** to ``_CHAT_EXCERPT_MSG_LIMIT`` leading rows
+    (SQL ``LIMIT``, kept in ``ORDER BY id`` so the *opening* of the conversation
+    is what's loaded) and to ``_CHAT_EXCERPT_FETCH_BUDGET`` characters of
+    accumulated content. The excerpt only ever surfaces a ~``EXCERPT_BUDGET``
+    window, so a bound several times that budget reproduces the identical window
+    for any normal-sized chat while stopping a single huge conversation from
+    ballooning memory. Because only the bounded slice is loaded,
+    ``chars_available`` / ``has_more`` describe that bounded window, not the
+    entire conversation: for a chat longer than the fetch budget ``has_more``
+    can under-report. This is the documented trade of bounding the fetch; a
+    separate ``COUNT``/``SUM(length)`` query to recover the true total is
+    deliberately avoided because it reintroduces the per-hit DB work this bound
+    removes.
+
+    The lookup stays a single bounded query **per chat hit**
+    (``search_chats_keyword`` calls this once per result row). Batching across
+    hits into one ``WHERE chat_id IN (...)`` query is deferred: it would
+    complicate the per-message visibility/access gating applied here, and
+    bounding each query already addresses the memory/CPU concern. The
+    ``messages.list_messages`` accessor is not reused — it orders newest-first
+    (``ORDER BY message.id DESC``), the wrong order for leading-content
+    windowing, and returns extra columns the excerpt does not need.
+    """
+    # Imported here to avoid a module-level dependency on the optional
+    # semantic package (chromadb/onnx) from the always-loaded db layer.
+    from footprinter.semantic.hybrid_search import extract_snippet
+
+    # Function-local import: services.access_service pulls in db.chats/files,
+    # which load this module via db/__init__, so a module-level import here
+    # would close an import cycle. Deferring to call time breaks the loop while
+    # still using the one canonical resolver. (Same pattern as the file paths.)
+    from footprinter.services.access_service import (
+        resolve_inherit_permission,
+        resolve_inherit_visibility,
+    )
+
+    status_conds, status_params = _status_clause(status, column="status")
+    # Per-row content gating now defers to the canonical resolvers rather than an
+    # inline ``access IN (...)`` / ``visibility IN (...)`` SQL predicate. The old
+    # predicate admitted ``inherit`` unconditionally; the resolvers map
+    # ``inherit`` to the cached global policy, so an ``inherit`` row resolves to
+    # deny/hidden under a global-deny/hidden policy and is dropped here — the SQL
+    # only bounds and orders the candidate rows, the visibility/access decision
+    # runs in Python below. Status filtering stays in SQL (global policy does not
+    # affect it). The resolvers carry the fail-closed posture: NULL access →
+    # deny, NULL visibility → opaque, and explicit hidden/opaque/deny still drop.
+    where = " AND ".join(["chat_id = ?", *status_conds])
+    rows = conn.execute(
+        f"""
+        SELECT content, access, visibility
+        FROM messages
+        WHERE {where}
+        ORDER BY id
+        LIMIT ?
+        """,
+        [chat_id, *status_params, _CHAT_EXCERPT_MSG_LIMIT],
+    ).fetchall()
+
+    # Accumulate leading message content only until the char budget is reached,
+    # then stop — so even a single enormous message is sliced to the budget. The
+    # per-row visibility/access gate runs before accumulation, so the budget
+    # bounds only admitted content.
+    pieces: list[str] = []
+    accumulated = 0
+    for r in rows:
+        content = r["content"]
+        if not content:
+            continue
+        if (
+            resolve_inherit_permission(r["access"]) != "allow"
+            or resolve_inherit_visibility(r["visibility"]) != "full"
+        ):
+            continue
+        pieces.append(content)
+        accumulated += len(content) + 1  # +1 for the "\n" join separator
+        if accumulated >= _CHAT_EXCERPT_FETCH_BUDGET:
+            break
+    full_content = "\n".join(pieces).strip()[:_CHAT_EXCERPT_FETCH_BUDGET]
+    if not full_content:
+        return build_excerpt(title or "", source="title")
+
+    window = extract_snippet(full_content, query)
+    return build_excerpt(window, source="message", chars_available=len(full_content))
+
+
 def search_chats_keyword(
     conn: sqlite3.Connection,
     *,
@@ -383,6 +520,8 @@ def search_chats_keyword(
 
     where_sql = (" AND ".join(where)) if where else "1=1"
 
+    query_text = " ".join(terms)
+
     rows = conn.execute(
         f"""
         SELECT chat.id, chat.external_id, chat.account, chat.title,
@@ -415,6 +554,9 @@ def search_chats_keyword(
             "visibility_source": r["visibility_source"],
             "access_source": r["access_source"],
             "status": r["status"],
+            # Re-derive the excerpt from message content; fall back to the
+            # title only when the chat has no listed message content.
+            **chat_message_excerpt(conn, r["id"], query_text, r["title"] or ""),
         }
         for r in rows
     ]
@@ -506,7 +648,9 @@ def chat_fts5_fallback(
     """FTS5 keyword fallback for chat search.
 
     Returns dicts shaped for semantic_service consumption: chat_id, chat_title,
-    snippet, relevance_score, source, created_at, message_id.
+    relevance_score, source, created_at, message_id, plus a ``snippet`` staging
+    field (the chat title) that ``semantic_service`` converts into the excerpt
+    contract (``excerpt_source="title"``) and removes before returning results.
     The ``status`` kwarg defaults to listed-only; pass ``"all"`` or a list to widen.
     """
     safe_query = query.replace('"', '""')
@@ -554,8 +698,14 @@ def file_fts5_fallback(
     """FTS5 keyword fallback for file search.
 
     Returns dicts shaped for semantic_service consumption: id, source, name,
-    path, content_type, size_bytes, modified_at, relevance_score, snippet,
-    visibility, access.
+    path, content_type, size_bytes, modified_at, relevance_score, the excerpt
+    contract (excerpt, excerpt_source, chars_returned, chars_available,
+    has_more), visibility, access.
+
+    Shape divergence: this degraded path carries **no** ``chunks`` key. The
+    per-file ``chunks`` list (top-N matched chunks) is a vector-path-only
+    enrichment attached by ``semantic_service._top_chunks_by_file``; the keyword
+    fallback has no chunk-level matches to surface.
     The ``status`` kwarg defaults to listed-only; pass ``"all"`` or a list to widen.
     """
     terms = split_query_terms(query)
@@ -579,12 +729,20 @@ def file_fts5_fallback(
         [match_str, *status_params, limit],
     ).fetchall()
 
+    # Function-local import — see search_files_keyword for the cycle rationale.
+    from footprinter.services.access_service import resolve_inherit_permission
+
     results = []
     for row in rows:
-        if row["content_preview"] and row["access"] != "deny":
-            snippet = row["content_preview"][:200]
+        # File-excerpt precedence on the keyword fallback path: content_preview
+        # when present and the canonical resolver puts access at 'allow', else
+        # name/path. resolve_inherit_permission honors a global-deny policy for
+        # 'inherit' files and fails closed on NULL — the weaker `!= "deny"`
+        # gate leaked content for NULL/inherit-under-global-deny rows.
+        if row["content_preview"] and resolve_inherit_permission(row["access"]) == "allow":
+            excerpt_fields = build_excerpt(row["content_preview"], source="content_preview")
         else:
-            snippet = f"{row['name']} — {row['path']}"
+            excerpt_fields = build_excerpt(f"{row['name']} — {row['path'] or ''}", source="title")
         results.append(
             {
                 "id": row["id"],
@@ -595,7 +753,7 @@ def file_fts5_fallback(
                 "size_bytes": row["size_bytes"],
                 "modified_at": row["modified_at"],
                 "relevance_score": 0.5,
-                "snippet": snippet,
+                **excerpt_fields,
                 "visibility": row["visibility"],
                 "access": row["access"],
                 "visibility_source": row["visibility_source"],

{footprinter_cli-1.1.0 → footprinter_cli-1.1.1}/footprinter/ingest/db/ddl.py

@@ -241,7 +241,10 @@ def init_schema(conn):
             access_source TEXT,
 
             -- Display
-            display_name TEXT
+            display_name TEXT,
+
+            -- Curated context (pointer to a Markdown file; nullable override)
+            context_path TEXT
         )
     """
     )
@@ -336,7 +339,10 @@ def init_schema(conn):
             visibility_source TEXT,
 
             -- Display
-            display_name TEXT
+            display_name TEXT,
+
+            -- Curated context (pointer to a Markdown file; nullable override)
+            context_path TEXT
         )
     """
     )
@@ -542,7 +548,10 @@ def init_schema(conn):
             visibility_source TEXT,
 
             -- Display
-            display_name TEXT
+            display_name TEXT,
+
+            -- Curated context (pointer to a Markdown file; nullable override)
+            context_path TEXT
         )
     """
     )
@@ -794,14 +803,25 @@ def _ensure_source_columns(conn):
 
 
 _SUPER_ENTITY_COLUMNS: dict[str, list[tuple[str, str]]] = {
-    "projects": [("slug", "TEXT"), ("status_changed_at", "DATETIME")],
-    "clients": [("slug", "TEXT"), ("status_changed_at", "DATETIME")],
-    "folders": [("status_changed_at", "DATETIME")],
+    "projects": [
+        ("slug", "TEXT"),
+        ("status_changed_at", "DATETIME"),
+        ("context_path", "TEXT"),
+    ],
+    "clients": [
+        ("slug", "TEXT"),
+        ("status_changed_at", "DATETIME"),
+        ("context_path", "TEXT"),
+    ],
+    "folders": [
+        ("status_changed_at", "DATETIME"),
+        ("context_path", "TEXT"),
+    ],
 }
 
 
 def _ensure_super_entity_columns(conn):
-    """Add slug/status_changed_at to super-entity tables (idempotent upgrade)."""
+    """Add slug/status_changed_at/context_path to super-entity tables (idempotent)."""
     for table, columns in _SUPER_ENTITY_COLUMNS.items():
         for col_name, col_type in columns:
             try: