footprinter-cli 1.0.0rc4__tar.gz → 1.0.2__tar.gz

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.2
 Name: footprinter-cli
-Version: 1.0.0rc4
+Version: 1.0.2
 Summary: A local context layer for your files, browser history, chats, and email — searchable, user-owned, MCP-served.
 Author: SwellCity Group
 License: MIT
-Project-URL: Homepage, https://github.com/swellcitygroup/footprinter
-Project-URL: Repository, https://github.com/swellcitygroup/footprinter
-Project-URL: Issues, https://github.com/swellcitygroup/footprinter/issues
-Project-URL: Documentation, https://github.com/swellcitygroup/footprinter/blob/main/README.md
-Project-URL: Changelog, https://github.com/swellcitygroup/footprinter/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/harringjohn/footprinter-cli
+Project-URL: Repository, https://github.com/harringjohn/footprinter-cli
+Project-URL: Issues, https://github.com/harringjohn/footprinter-cli/issues
+Project-URL: Documentation, https://github.com/harringjohn/footprinter-cli/blob/main/README.md
+Project-URL: Changelog, https://github.com/harringjohn/footprinter-cli/blob/main/CHANGELOG.md
 Keywords: indexer,mcp,metadata,model-context-protocol,file-indexing,sqlite,context-engineering,personal-information-management
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: End Users/Desktop
@@ -53,23 +53,73 @@ Requires-Dist: httpx<1.0,>=0.27.0; extra == "dev"
 # Footprinter
 
 [![Tests](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml/badge.svg)](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/footprinter-cli)](https://pypi.org/project/footprinter-cli/)
 
 **A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
 
 Your work lives across a filesystem, a browser, an inbox, a chat history, and whatever other tools you reach for. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings *you* define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
 
+## Prerequisites
+
+- **Python 3.11 or newer.** Stock macOS ships with Python 3.9, which won't work — install a newer Python from [python.org](https://www.python.org/downloads/) (recommended) or via `brew install python@3.11`.
+- **macOS 13+** or **Linux**.
+- **Full Disk Access on macOS** for browser history indexing. Grant it to your terminal app under *System Settings → Privacy & Security → Full Disk Access*. `fp setup` will guide you through this when needed.
+
 ## Install
 
+The fastest path on a clean machine is the install script — it ensures Python 3.11+ is present and installs `footprinter-cli`:
+
 ```bash
-pip install footprinter-cli
+# Base install (CLI + MCP + HTTP API)
+curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install.sh | bash
+
+# Full install (adds semantic search + document parsing)
+curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install-full.sh | bash
 ```
 
-The base install includes the indexing pipeline, CLI, MCP server, HTTP API, and token encryption. Optional extras add more capabilities:
+If you prefer to manage the install yourself, use **pipx** (recommended) — it isolates Footprinter and sidesteps the macOS install caveats noted below:
+
+```bash
+brew install pipx
+pipx ensurepath           # then restart your terminal
+pipx install footprinter-cli
+pipx install 'footprinter-cli[full]'   # with semantic + parse
+```
+
+> **macOS caveats for manual installs:**
+> - **zsh** treats `[...]` as a glob, so keep the single quotes around any bracketed extras specifier (e.g. `'footprinter-cli[full]'`). Without quotes you'll see `zsh: no matches found`.
+> - **System and Homebrew Python** ship with PEP 668 enabled, which blocks bare `pip install` outside a venv. Use pipx (above) instead.
+> - **python.org-distributed Python** doesn't enforce PEP 668, so a bare `pip install footprinter-cli` outside pipx or a venv may succeed but place `fp` in `/Library/Frameworks/Python.framework/Versions/<x.y>/bin`, which isn't on `PATH` by default. Use pipx (above) or the install script.
+
+Inside an existing venv, `pip` works as expected:
 
 ```bash
-pip install footprinter-cli[full]       # All optional extras (semantic + parse)
-pip install footprinter-cli[semantic]   # Semantic search (ChromaDB + ONNX embeddings)
-pip install footprinter-cli[parse]      # PDF, Word, Excel, PowerPoint content extraction
+./venv/bin/pip install footprinter-cli
+./venv/bin/pip install 'footprinter-cli[full]'
+```
+
+The base install includes the indexing pipeline, CLI, MCP server, HTTP API, and token encryption. Optional extras add more:
+
+| Extra | What it adds |
+|-------|-------------|
+| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
+| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
+| `[full]` | All optional extras (semantic + parse) |
+
+> **Privacy note:** The `[semantic]` extra installs ChromaDB. Footprinter initializes
+> the ChromaDB client with `anonymized_telemetry=False`, so no telemetry is sent
+> regardless of which version pip resolves. ChromaDB also removed product telemetry
+> entirely in version 1.5.4. See
+> [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss) for details.
+
+### Uninstall
+
+`fp uninstall` cleans up the MCP entry and user data first, then run the appropriate package uninstall:
+
+```bash
+fp uninstall                                    # remove MCP entry + user data
+pipx uninstall footprinter-cli                  # if you installed via pipx
+./venv/bin/pip uninstall footprinter-cli        # if you installed inside a venv
 ```
 
 ## Quick Start
@@ -81,16 +131,22 @@ fp status    # See what's indexed
 fp search "meeting notes"   # Find things
 ```
 
-**macOS note:** Browser history indexing requires Full Disk Access for your terminal app (System Settings > Privacy & Security > Full Disk Access).
+A few first-run notes:
+
+- The first ingest is implicitly full; subsequent runs are incremental. If you change exclusions or add directories after the first run, re-run with `fp ingest --full` so previously skipped files get picked up.
+- With `[semantic]` or `[full]`, the **first ingest downloads ~80MB** of ONNX embedding model weights. It's a one-time cost — subsequent ingests are fast.
+- Keep the directories you want indexed **outside `~/Downloads`** — the default exclusion list skips it.
 
 ## Connect to Claude Desktop
 
 Footprinter includes an MCP server that gives Claude Desktop (or any MCP client) structured access to your indexed data:
 
 ```bash
-fp setup mcp    # Configure MCP for Claude Desktop
+fp setup mcp --claude    # Configure MCP for Claude Desktop
 ```
 
+After running this, **fully quit Claude Desktop (Cmd+Q) and relaunch** before the Footprinter tools appear in the conversation tools list. A simple window close isn't enough — the app keeps running in the menu bar.
+
 Once configured, Claude can search your files, browse projects, and find related conversations — through natural language.
 
 ## What It Indexes
@@ -104,6 +160,8 @@ Once configured, Claude can search your files, browse projects, and find related
 | **Documents** | PDF, Word, Excel, PowerPoint content (with `[parse]` extra) |
 | **Semantic embeddings** | Conceptual similarity across all sources (with `[semantic]` extra) |
 
+What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, Footprinter only indexes metadata; it does not read your file content until you explicitly enable it. See [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) for the full breakdown.
+
 Additional sources are available through [connector plugins](#connectors).
 
 ## CLI Commands
@@ -120,10 +178,12 @@ All commands use the `fp` entry point.
 | `fp mcp` | MCP server and access policies |
 | `fp api` | Start the HTTP API server |
 | `fp view` | Browse indexed data (files, folders, projects, clients, chats, emails, visits) |
-| `fp upsert` | Create or update records and assign relationships |
+| `fp upsert` | Create/update records, assign relationships, or soft-delete via `--status removed` |
 | `fp data` | Export data, generate templates, or import metadata corrections |
-| `fp delete` | Soft-delete a record |
+| `fp delete` | Hard-delete a super entity (irreversible) |
 | `fp vectorize` | Manage per-record vectorization control |
+| `fp doctor` | Post-install health check (Python version, install location, FDA, MCP wiring) |
+| `fp uninstall` | Remove Footprinter — MCP entry, user data, package |
 
 Run `fp <command> --help` for full usage.
 
@@ -145,23 +205,10 @@ Single-process CLI with optional MCP server. SQLite database. No containers, no
 
 Sources are scanned into SQLite with bidirectional links connecting local files to remote backups via content hash matching. Embeddings are generated at ingest time for semantic search. The MCP server exposes indexed data with two-layer access control (visibility + permissions) — you decide what agents can see.
 
-## Optional Extras
-
-| Extra | What it adds |
-|-------|-------------|
-| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
-| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
-| `[full]` | All optional extras (semantic + parse) |
-
-> **Privacy note:** The `[semantic]` extra installs ChromaDB, which bundles PostHog analytics.
-> ChromaDB collects anonymous usage telemetry by default. Set `ANONYMIZED_TELEMETRY=False`
-> in your environment to disable it. See
-> [ChromaDB telemetry docs](https://docs.trychroma.com/docs/overview/telemetry) for details.
-
 ## Requirements
 
 - Python 3.11+
-- macOS or Linux
+- macOS 13+ or Linux
 - Full Disk Access on macOS (for browser history)
 
 ## Documentation
@@ -169,6 +216,7 @@ Sources are scanned into SQLite with bidirectional links connecting local files
 - [Interfaces](https://github.com/swellcitygroup/footprinter/blob/main/reference/interfaces.md) — CLI commands, MCP tools, Python API
 - [Data Model](https://github.com/swellcitygroup/footprinter/blob/main/reference/data-model.md) — database schema
 - [Pipeline](https://github.com/swellcitygroup/footprinter/blob/main/reference/pipeline.md) — indexing stages and configuration
+- [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
 - [Access Control](https://github.com/swellcitygroup/footprinter/blob/main/reference/mcp-access-control.md) — MCP security model
 
 ## Contributing
@@ -189,7 +237,7 @@ python3 -m venv venv
 ### Running tests
 
 ```bash
-pytest tests/ -v --tb=short
+./venv/bin/pytest tests/ -v --tb=short
 ```
 
 ### Code style

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/README.md

@@ -1,23 +1,73 @@
 # Footprinter
 
 [![Tests](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml/badge.svg)](https://github.com/swellcitygroup/footprinter/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/footprinter-cli)](https://pypi.org/project/footprinter-cli/)
 
 **A local context layer for your files, browser history, chats, and email — searchable, user-owned, and served to AI agents through [MCP](https://modelcontextprotocol.io/).**
 
 Your work lives across a filesystem, a browser, an inbox, a chat history, and whatever other tools you reach for. Footprinter indexes those sources into a single local store, organizes them into the projects and groupings *you* define, and serves the result to AI agents through a governed access layer. You control what the agent can see. Everything stays on your machine.
 
+## Prerequisites
+
+- **Python 3.11 or newer.** Stock macOS ships with Python 3.9, which won't work — install a newer Python from [python.org](https://www.python.org/downloads/) (recommended) or via `brew install python@3.11`.
+- **macOS 13+** or **Linux**.
+- **Full Disk Access on macOS** for browser history indexing. Grant it to your terminal app under *System Settings → Privacy & Security → Full Disk Access*. `fp setup` will guide you through this when needed.
+
 ## Install
 
+The fastest path on a clean machine is the install script — it ensures Python 3.11+ is present and installs `footprinter-cli`:
+
 ```bash
-pip install footprinter-cli
+# Base install (CLI + MCP + HTTP API)
+curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install.sh | bash
+
+# Full install (adds semantic search + document parsing)
+curl -fsSL https://raw.githubusercontent.com/swellcitygroup/footprinter/main/scripts/release/install-full.sh | bash
 ```
 
-The base install includes the indexing pipeline, CLI, MCP server, HTTP API, and token encryption. Optional extras add more capabilities:
+If you prefer to manage the install yourself, use **pipx** (recommended) — it isolates Footprinter and sidesteps the macOS install caveats noted below:
+
+```bash
+brew install pipx
+pipx ensurepath           # then restart your terminal
+pipx install footprinter-cli
+pipx install 'footprinter-cli[full]'   # with semantic + parse
+```
+
+> **macOS caveats for manual installs:**
+> - **zsh** treats `[...]` as a glob, so keep the single quotes around any bracketed extras specifier (e.g. `'footprinter-cli[full]'`). Without quotes you'll see `zsh: no matches found`.
+> - **System and Homebrew Python** ship with PEP 668 enabled, which blocks bare `pip install` outside a venv. Use pipx (above) instead.
+> - **python.org-distributed Python** doesn't enforce PEP 668, so a bare `pip install footprinter-cli` outside pipx or a venv may succeed but place `fp` in `/Library/Frameworks/Python.framework/Versions/<x.y>/bin`, which isn't on `PATH` by default. Use pipx (above) or the install script.
+
+Inside an existing venv, `pip` works as expected:
 
 ```bash
-pip install footprinter-cli[full]       # All optional extras (semantic + parse)
-pip install footprinter-cli[semantic]   # Semantic search (ChromaDB + ONNX embeddings)
-pip install footprinter-cli[parse]      # PDF, Word, Excel, PowerPoint content extraction
+./venv/bin/pip install footprinter-cli
+./venv/bin/pip install 'footprinter-cli[full]'
+```
+
+The base install includes the indexing pipeline, CLI, MCP server, HTTP API, and token encryption. Optional extras add more:
+
+| Extra | What it adds |
+|-------|-------------|
+| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
+| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
+| `[full]` | All optional extras (semantic + parse) |
+
+> **Privacy note:** The `[semantic]` extra installs ChromaDB. Footprinter initializes
+> the ChromaDB client with `anonymized_telemetry=False`, so no telemetry is sent
+> regardless of which version pip resolves. ChromaDB also removed product telemetry
+> entirely in version 1.5.4. See
+> [Chroma OSS overview](https://docs.trychroma.com/docs/overview/oss) for details.
+
+### Uninstall
+
+`fp uninstall` cleans up the MCP entry and user data first, then run the appropriate package uninstall:
+
+```bash
+fp uninstall                                    # remove MCP entry + user data
+pipx uninstall footprinter-cli                  # if you installed via pipx
+./venv/bin/pip uninstall footprinter-cli        # if you installed inside a venv
 ```
 
 ## Quick Start
@@ -29,16 +79,22 @@ fp status    # See what's indexed
 fp search "meeting notes"   # Find things
 ```
 
-**macOS note:** Browser history indexing requires Full Disk Access for your terminal app (System Settings > Privacy & Security > Full Disk Access).
+A few first-run notes:
+
+- The first ingest is implicitly full; subsequent runs are incremental. If you change exclusions or add directories after the first run, re-run with `fp ingest --full` so previously skipped files get picked up.
+- With `[semantic]` or `[full]`, the **first ingest downloads ~80MB** of ONNX embedding model weights. It's a one-time cost — subsequent ingests are fast.
+- Keep the directories you want indexed **outside `~/Downloads`** — the default exclusion list skips it.
 
 ## Connect to Claude Desktop
 
 Footprinter includes an MCP server that gives Claude Desktop (or any MCP client) structured access to your indexed data:
 
 ```bash
-fp setup mcp    # Configure MCP for Claude Desktop
+fp setup mcp --claude    # Configure MCP for Claude Desktop
 ```
 
+After running this, **fully quit Claude Desktop (Cmd+Q) and relaunch** before the Footprinter tools appear in the conversation tools list. A simple window close isn't enough — the app keeps running in the menu bar.
+
 Once configured, Claude can search your files, browse projects, and find related conversations — through natural language.
 
 ## What It Indexes
@@ -52,6 +108,8 @@ Once configured, Claude can search your files, browse projects, and find related
 | **Documents** | PDF, Word, Excel, PowerPoint content (with `[parse]` extra) |
 | **Semantic embeddings** | Conceptual similarity across all sources (with `[semantic]` extra) |
 
+What lands in the database — and when — is controlled by the **content storage tier** you opt into. By default, Footprinter only indexes metadata; it does not read your file content until you explicitly enable it. See [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) for the full breakdown.
+
 Additional sources are available through [connector plugins](#connectors).
 
 ## CLI Commands
@@ -68,10 +126,12 @@ All commands use the `fp` entry point.
 | `fp mcp` | MCP server and access policies |
 | `fp api` | Start the HTTP API server |
 | `fp view` | Browse indexed data (files, folders, projects, clients, chats, emails, visits) |
-| `fp upsert` | Create or update records and assign relationships |
+| `fp upsert` | Create/update records, assign relationships, or soft-delete via `--status removed` |
 | `fp data` | Export data, generate templates, or import metadata corrections |
-| `fp delete` | Soft-delete a record |
+| `fp delete` | Hard-delete a super entity (irreversible) |
 | `fp vectorize` | Manage per-record vectorization control |
+| `fp doctor` | Post-install health check (Python version, install location, FDA, MCP wiring) |
+| `fp uninstall` | Remove Footprinter — MCP entry, user data, package |
 
 Run `fp <command> --help` for full usage.
 
@@ -93,23 +153,10 @@ Single-process CLI with optional MCP server. SQLite database. No containers, no
 
 Sources are scanned into SQLite with bidirectional links connecting local files to remote backups via content hash matching. Embeddings are generated at ingest time for semantic search. The MCP server exposes indexed data with two-layer access control (visibility + permissions) — you decide what agents can see.
 
-## Optional Extras
-
-| Extra | What it adds |
-|-------|-------------|
-| `[semantic]` | Semantic search via ChromaDB + ONNX embeddings |
-| `[parse]` | PDF, Word, Excel, PowerPoint content extraction |
-| `[full]` | All optional extras (semantic + parse) |
-
-> **Privacy note:** The `[semantic]` extra installs ChromaDB, which bundles PostHog analytics.
-> ChromaDB collects anonymous usage telemetry by default. Set `ANONYMIZED_TELEMETRY=False`
-> in your environment to disable it. See
-> [ChromaDB telemetry docs](https://docs.trychroma.com/docs/overview/telemetry) for details.
-
 ## Requirements
 
 - Python 3.11+
-- macOS or Linux
+- macOS 13+ or Linux
 - Full Disk Access on macOS (for browser history)
 
 ## Documentation
@@ -117,6 +164,7 @@ Sources are scanned into SQLite with bidirectional links connecting local files
 - [Interfaces](https://github.com/swellcitygroup/footprinter/blob/main/reference/interfaces.md) — CLI commands, MCP tools, Python API
 - [Data Model](https://github.com/swellcitygroup/footprinter/blob/main/reference/data-model.md) — database schema
 - [Pipeline](https://github.com/swellcitygroup/footprinter/blob/main/reference/pipeline.md) — indexing stages and configuration
+- [Content Storage](https://github.com/swellcitygroup/footprinter/blob/main/reference/content-storage.md) — metadata vs. snippet vs. full-content tiers
 - [Access Control](https://github.com/swellcitygroup/footprinter/blob/main/reference/mcp-access-control.md) — MCP security model
 
 ## Contributing
@@ -137,7 +185,7 @@ python3 -m venv venv
 ### Running tests
 
 ```bash
-pytest tests/ -v --tb=short
+./venv/bin/pytest tests/ -v --tb=short
 ```
 
 ### Code style

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/access.py

@@ -46,7 +46,7 @@ def _is_inherit_source(source: str) -> bool:
 #   table:          SQL table name
 #   has_visibility: has mcp_view column
 #   has_permissions: has mcp_read column
-#   has_status:     has status column (filter WHERE status != 'removed')
+#   has_status:     has status column (filter WHERE status = 'listed')
 #   has_project_id: has project_id FK
 #   has_client_id:  has client_id FK
 #   has_account:    has account column
@@ -129,7 +129,7 @@ def _get_all_ids(conn: sqlite3.Connection, entity_type: str) -> list[int]:
     meta = ENTITY_META[entity_type]
     table = meta["table"]
     if meta["has_status"]:
-        rows = conn.execute(f"SELECT id FROM {table} WHERE status != 'removed'").fetchall()
+        rows = conn.execute(f"SELECT id FROM {table} WHERE status = 'listed'").fetchall()
     else:
         rows = conn.execute(f"SELECT id FROM {table}").fetchall()
     return [r["id"] for r in rows]
@@ -162,7 +162,7 @@ def _get_ids_for_scope(conn: sqlite3.Connection, scope: str) -> dict[str, list[i
             table = meta["table"]
             where = "account = ?"
             if meta["has_status"]:
-                where += " AND status != 'removed'"
+                where += " AND status = 'listed'"
             rows = conn.execute(f"SELECT id FROM {table} WHERE {where}", (value,)).fetchall()
             ids = [r["id"] for r in rows]
             if ids:
@@ -183,7 +183,7 @@ def _get_ids_for_scope(conn: sqlite3.Connection, scope: str) -> dict[str, list[i
             table = meta["table"]
             where = f"{path_col} LIKE ? ESCAPE '\\'"
             if meta["has_status"]:
-                where += " AND status != 'removed'"
+                where += " AND status = 'listed'"
             rows = conn.execute(
                 f"SELECT id FROM {table} WHERE {where}",
                 (escaped + "%",),
@@ -210,7 +210,7 @@ def _get_ids_for_scope(conn: sqlite3.Connection, scope: str) -> dict[str, list[i
             table = meta["table"]
             where = "project_id = ?"
             if meta["has_status"]:
-                where += " AND status != 'removed'"
+                where += " AND status = 'listed'"
             rows = conn.execute(f"SELECT id FROM {table} WHERE {where}", (project_id,)).fetchall()
             ids = [r["id"] for r in rows]
             if ids:
@@ -248,7 +248,7 @@ def _get_ids_for_scope(conn: sqlite3.Connection, scope: str) -> dict[str, list[i
             table = meta["table"]
             where = "client_id = ?"
             if meta["has_status"]:
-                where += " AND status != 'removed'"
+                where += " AND status = 'listed'"
             rows = conn.execute(f"SELECT id FROM {table} WHERE {where}", (client_id,)).fetchall()
             if rows:
                 id_sets.setdefault(etype, {}).update({r["id"]: None for r in rows})

footprinter_cli-1.0.2/footprinter/api/__init__.py

@@ -0,0 +1,4 @@
+"""Footprinter HTTP API — FastAPI routers calling the service layer."""
+
+MAX_LIMIT = 200
+"""Upper bound for `limit` query params on HTTP list/search endpoints."""

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/api/entities.py

@@ -4,6 +4,7 @@ from typing import Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
+from footprinter.api import MAX_LIMIT
 from footprinter.api.db import get_conn
 from footprinter.services import (
     chat_service,
@@ -36,7 +37,7 @@ def list_files(
     source: Optional[str] = Query(None, description="Comma-separated source filter"),
     status: Optional[str] = Query(None, description="Comma-separated status filter"),
     content_type: Optional[str] = None,
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
     source_list = [s.strip() for s in source.split(",")] if source else None
@@ -71,7 +72,7 @@ def list_emails(
     has_attachments: Optional[bool] = None,
     sort_by: str = "received_at",
     order: str = "desc",
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
     return email_service.list_(
@@ -105,7 +106,7 @@ def list_chats(
     sort_by: str = "modified_at",
     order: str = "desc",
     status: Optional[str] = Query(None, description="Comma-separated status filter"),
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
     status_list = [s.strip() for s in status.split(",")] if status else None
@@ -137,7 +138,7 @@ def list_projects(
     status: Optional[str] = Query(None, description="Comma-separated status filter"),
     client: Optional[str] = None,
     project_type: Optional[str] = None,
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
     include_list = [s.strip() for s in include.split(",")] if include else None
@@ -172,7 +173,7 @@ def list_clients(
     conn=Depends(get_conn),
     include: Optional[str] = Query(None, description="Comma-separated includes"),
     status: Optional[str] = Query(None, description="Comma-separated status filter"),
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
     include_list = [s.strip() for s in include.split(",")] if include else None
@@ -216,16 +217,19 @@ def list_folders(
     project_id: Optional[int] = None,
     depth: Optional[int] = 1,
     include_hidden: bool = False,
+    status: Optional[str] = Query(None, description="Comma-separated status filter"),
     sort_by: str = "size",
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     page: int = 1,
 ):
+    status_list = [s.strip() for s in status.split(",")] if status else None
     return folder_service.list_(
         conn,
         role=Role.ADMIN,
         project_id=project_id,
         depth=depth,
         include_hidden=include_hidden,
+        status=status_list,
         sort_by=sort_by,
         limit=limit,
         page=page,
@@ -241,7 +245,11 @@ def get_folder(folder_id: int, conn=Depends(get_conn)):
 
 
 @router.get("/visits")
-def list_visits(conn=Depends(get_conn), limit: int = 50, page: int = 1):
+def list_visits(
+    conn=Depends(get_conn),
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
+    page: int = 1,
+):
     return visit_service.list_(conn, role=Role.ADMIN, limit=limit, page=page)
 
 

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/api/search.py

@@ -4,6 +4,7 @@ from typing import Optional
 
 from fastapi import APIRouter, Depends, Query
 
+from footprinter.api import MAX_LIMIT
 from footprinter.api.db import get_conn
 from footprinter.services import search_service
 from footprinter.services.roles import Role
@@ -20,7 +21,7 @@ def search(
     client: Optional[str] = None,
     date_from: Optional[str] = None,
     date_to: Optional[str] = None,
-    limit: int = 50,
+    limit: int = Query(50, ge=1, le=MAX_LIMIT),
     account: Optional[str] = None,
     sender: Optional[str] = None,
     days_back: Optional[int] = None,

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/api/semantic.py

@@ -2,6 +2,7 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 
+from footprinter.api import MAX_LIMIT
 from footprinter.api.db import get_conn
 from footprinter.services import semantic_service
 from footprinter.services.roles import Role
@@ -16,7 +17,7 @@ def semantic_search(
     conn=Depends(get_conn),
     query: str = Query(..., min_length=3, description="Search query (minimum 3 characters)"),
     source: str = Query("all", description="Source to search: chats, files, or all"),
-    limit: int = 10,
+    limit: int = Query(10, ge=1, le=MAX_LIMIT),
 ):
     """Semantic (vector) search across indexed content."""
     if source not in _VALID_SOURCES:

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/bundled/config.example.yaml

@@ -17,7 +17,7 @@ browsers:
 #
 # Files matching these patterns are NEVER scanned — they don't appear in the
 # database at all. This is different from hidden files (dot-files/dot-directories),
-# which ARE scanned and indexed with status='hidden' so they appear in the catalog
+# which ARE scanned and indexed with status='unlisted' so they appear in the catalog
 # but are excluded from Drive sync.
 #
 # Two tiers: always (all folders), sensitive (all folders)
@@ -41,8 +41,11 @@ exclusions:
     - ".*/\\.sfdx/.*"            # Salesforce DX CLI
     - ".*/\\.docker/.*"          # Docker config
     - ".*/\\.cumulusci/.*"       # CumulusCI cache
+    - ".*/\\.browser_state/.*"   # Playwright/Puppeteer browser state
+    - ".*/\\.context/.*"         # IDE/agent context directories
+    - ".*/\\.ai-dev/.*"          # AI dev tool scratch dirs
     # Home-level Claude dirs only (keep .claude within Work/Personal)
-    - "^~/\\.claude/.*"           # Home-level .claude
+    - "^~/\\.claude/.*"           # Home-level .claude (includes session-env snapshots)
     - "^~/\\.claude-worktrees/.*" # Home-level .claude-worktrees
     # Git internals (but NOT .gitignore, .gitattributes - those are kept)
     - ".*/\\.git/.*"             # Git internal directory contents
@@ -115,17 +118,19 @@ vectorization:
   # but not embedded in the vector store.
   #
   # Common exclusions — system caches, IDE output, and tool output that
-  # match text file extensions but contain no meaningful prose content:
-  #   - "**/Photos Library.photoslibrary/**"  # macOS Spotlight index cache (.txt)
-  #   - "**/.claude/debug/**"                 # Claude Code debug logs
-  #   - "**/.claude/paste-cache/**"           # Claude Code paste cache
-  #   - "**/.claude/cache/**"                 # Claude Code cache
-  #   - "**/.claude/projects/**"              # Claude Code session data
-  #   - "**/.claude/plans/**"                 # Claude Code auto-generated plans
-  #   - "**/.claude/plugins/**"              # Claude Code plugin cache
-  #   - "**/.cci/**"                          # CumulusCI cache
-  #   - "**/.context/**"                      # IDE context directories
-  exclude_patterns: []
+  # match text file extensions but contain no meaningful prose content.
+  exclude_patterns:
+    - "**/Photos Library.photoslibrary/**"  # macOS Spotlight index cache (.txt)
+    - "**/.claude/debug/**"                 # Claude Code debug logs
+    - "**/.claude/paste-cache/**"           # Claude Code paste cache
+    - "**/.claude/cache/**"                 # Claude Code cache
+    - "**/.claude/projects/**"              # Claude Code session data
+    - "**/.claude/plans/**"                 # Claude Code auto-generated plans
+    - "**/.claude/plugins/**"               # Claude Code plugin cache
+    - "**/.cci/**"                          # CumulusCI cache
+    - "**/.context/**"                      # IDE context directories
+    - "**/.github/**"                       # GitHub workflow files (FTS-only)
+    - "**/.ai-dev/**"                       # AI dev tool scratch dirs
 
 # Source registry seeds — loaded into the sources table on init
 # Connector sources added by: fp connect install <name>

{footprinter_cli-1.0.0rc4 → footprinter_cli-1.0.2}/footprinter/cli/__init__.py

@@ -63,6 +63,12 @@ def main(argv=None) -> None:
             "  fp api                     Start the HTTP API server\n"
             "  fp mcp check ~/Work/file   Check access resolution for a path\n"
             "\n"
+            "diagnostics:\n"
+            "  fp doctor                  Check installation health\n"
+            "\n"
+            "cleanup:\n"
+            "  fp uninstall               Remove Footprinter (MCP entry, data, package)\n"
+            "\n"
             "tip: use 'fp <command> --help' for details on any command."
         ),
         formatter_class=FORMATTER,
@@ -80,11 +86,13 @@ def main(argv=None) -> None:
         connect,
         data,
         delete,
+        doctor,
         ingest,
         mcp_cmd,
         search_cmd,
         setup,
         status_cmd,
+        uninstall,
         upsert,
         vectorize_cmd,
         view,
@@ -103,6 +111,8 @@ def main(argv=None) -> None:
         data,
         delete,
         vectorize_cmd,
+        uninstall,
+        doctor,
     ]:
         mod.register(subparsers)