fathom-server 0.1.0__tar.gz

fathom_server-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include fathom_server/static *
+recursive-exclude * *.sync-conflict*

fathom_server-0.1.0/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: fathom-server
+Version: 0.1.0
+Summary: Dashboard + REST API + background services for the Fathom vault layer
+Author-email: Myra Krusemark <myra@myrakrusemark.com>
+License-Expression: MIT
+Project-URL: Homepage, https://hifathom.com
+Project-URL: Repository, https://github.com/myrakrusemark/fathom-vault
+Project-URL: Issues, https://github.com/myrakrusemark/fathom-vault/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=3.1.0
+Requires-Dist: flask-sock>=0.7.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: telethon>=1.36.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.9.0; extra == "dev"
+
+# Fathom Server
+
+Dashboard, API, and background services for [Fathom](https://hifathom.com) — a multi-workspace vault system with search, activity tracking, rooms, and agent coordination.
+
+Runs once, serves all workspaces. Per-workspace MCP tools are provided by [`fathom-mcp`](./fathom-mcp/).
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  fathom-server (Python)                      │
+│                                              │
+│  React Dashboard ─── REST API ─── Services   │
+│  (vault browser,    (Flask,      (indexer,   │
+│   terminal,          :4243)       pings,     │
+│   activation,                     crystal,   │
+│   rooms,                          telegram,  │
+│   telegram)                       access)    │
+│                                              │
+│  Workspace Registry + API Key Auth           │
+└──────────────────┬───────────────────────────┘
+                   │ HTTP localhost:4243
+      ┌────────────┼──────────────┐
+      ▼            ▼              ▼
+┌──────────┐ ┌──────────┐  ┌──────────┐
+│ ws: main │ │ ws: ns   │  │ ws: apps │
+│ npx      │ │ npx      │  │ npx      │
+│ fathom-  │ │ fathom-  │  │ fathom-  │
+│ mcp      │ │ mcp      │  │ mcp      │
+└──────────┘ └──────────┘  └──────────┘
+ Claude inst. Claude inst.  Claude inst.
+```
+
+## Requirements
+
+- Python 3.11+
+- Node.js 18+ (for frontend build and [qmd](https://github.com/nicoblu/qmd))
+- [qmd](https://github.com/nicoblu/qmd) — `npm install -g @tobilu/qmd` (powers search)
+- tmux (for agent sessions and inter-workspace messaging)
+
+## Install
+
+```bash
+git clone https://github.com/myrakrusemark/fathom-vault.git
+cd fathom-vault
+
+# Install Python package + dependencies
+pip install -e .              # editable install — includes CLI entry point
+pip install -e '.[dev]'       # optional: adds pytest + ruff
+
+# Build the frontend
+cd frontend && npm install && npm run build && cd ..
+cp -r frontend/dist/* fathom_server/static/
+```
+
+## Setup
+
+Run the setup command to create the data directory and generate an API key:
+
+```bash
+fathom-server setup           # interactive — prompts for confirmation
+fathom-server setup -y        # non-interactive — just do it
+```
+
+This creates the data directory (see [Data directory](#data-directory) below) and generates an API key. The key is printed once — copy it, you'll need it when running `npx fathom-mcp init` in your project directories.
+
+## Run
+
+```bash
+fathom-server                  # start the server (default: 0.0.0.0:4243)
+fathom-server --port 8080      # custom port
+fathom-server --host 127.0.0.1 # bind to localhost only
+```
+
+Opens at `http://localhost:4243`. On startup the server:
+
+1. Loads all registered workspaces
+2. Starts persistent Claude sessions for each workspace (if configured)
+3. Configures ping schedulers, background indexer, and crystal regeneration
+4. Starts the Telegram bridge (if enabled)
+
+## Install as a system service
+
+Register fathom-server as a systemd user service that starts on boot:
+
+```bash
+fathom-server install                          # install, enable, and start
+fathom-server install --port 8080              # custom port
+fathom-server install --data-dir /opt/fathom   # custom data directory
+fathom-server install --no-start               # install and enable without starting
+```
+
+This writes a unit file to `~/.config/systemd/user/fathom-server.service`, enables linger (so the service survives logout), and starts it.
+
+Manage the service with standard systemd commands:
+
+```bash
+systemctl --user status fathom-server.service
+systemctl --user restart fathom-server.service
+journalctl --user -u fathom-server.service -f
+```
+
+To remove the service:
+
+```bash
+fathom-server uninstall
+```
+
+## CLI reference
+
+```
+fathom-server                    Run the server (default)
+fathom-server serve              Run the server (explicit)
+  --host HOST                    Bind address (default: 0.0.0.0)
+  --port PORT                    Port (default: 4243)
+
+fathom-server setup              First-time setup (data dirs + API key)
+  -y, --yes                      Skip confirmation prompt
+
+fathom-server install            Install as a systemd user service
+  --host HOST                    Bind address (default: 0.0.0.0)
+  --port PORT                    Port (default: 4243)
+  --data-dir DIR                 FATHOM_DATA_DIR override
+  --working-dir DIR              WorkingDirectory for the service
+  --no-start                     Install and enable without starting
+
+fathom-server uninstall          Remove the systemd user service
+```
+
+## Quick start — new workspace
+
+```bash
+# In your project directory:
+npx fathom-mcp init
+```
+
+The init wizard prompts for server URL and API key, creates `.fathom.json`, registers the workspace with the server, and sets up Claude Code hooks. See [`fathom-mcp` README](./fathom-mcp/README.md) for details.
+
+You can also add workspaces via the dashboard at Settings > Workspaces.
+
+## Data directory
+
+Runtime data (SQLite database, API key, vaults, Telegram assets) is stored outside the install directory:
+
+| Priority | Location |
+|----------|----------|
+| 1. `FATHOM_DATA_DIR` env var | Wherever you point it |
+| 2. `XDG_DATA_HOME`/fathom-server | Follows XDG spec |
+| 3. `~/.local/share/fathom-server` | Default fallback |
+
+For development, set `FATHOM_DATA_DIR=./data` in your `.env` file to keep data in the project directory.
+
+### Configuration
+
+**Environment variables** (override defaults):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FATHOM_DATA_DIR` | `~/.local/share/fathom-server` | Runtime data directory |
+| `FATHOM_PORT` | `4243` | Server port |
+| `FATHOM_VAULT_DIR` | (none) | Default vault directory |
+
+**Server config** — `<data-dir>/server.json` (auto-generated):
+
+```json
+{
+  "api_key": "fv_...",
+  "auth_enabled": true
+}
+```
+
+**Per-workspace config** — `<project>/.fathom/settings.json` (auto-created with defaults):
+
+```json
+{
+  "background_index": {
+    "enabled": true,
+    "interval_minutes": 15
+  },
+  "mcp": {
+    "query_timeout_seconds": 120,
+    "search_results": 10,
+    "search_mode": "hybrid"
+  },
+  "activity": {
+    "decay_halflife_days": 7,
+    "recency_window_hours": 48,
+    "show_heat_indicator": true
+  },
+  "crystal_regen": {
+    "enabled": false,
+    "interval_days": 7
+  },
+  "ping": {
+    "routines": []
+  }
+}
+```
+
+## API Authentication
+
+All `/api/*` routes require a Bearer token when auth is enabled:
+
+```bash
+curl -H "Authorization: Bearer fv_abc123..." http://localhost:4243/api/workspaces
+```
+
+The dashboard is exempt (served from the same origin). Manage the API key from the dashboard at Settings > API Key & Auth.
+
+## HTTP API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/workspaces` | GET | List all workspaces with status |
+| `/api/workspaces` | POST | Register a workspace (name, path) |
+| `/api/workspaces/<name>` | DELETE | Unregister a workspace |
+| `/api/vault` | GET | Folder tree |
+| `/api/vault/folder/<path>` | GET | List files with metadata and previews |
+| `/api/vault/file/<path>` | GET/POST | Read/write files |
+| `/api/vault/append/<path>` | POST | Append to files |
+| `/api/search` | GET | Unified search (`?q=...&mode=bm25\|vector\|hybrid`) |
+| `/api/vault/links/<path>` | GET | Forward/backlinks |
+| `/api/vault/activity` | GET | Activity-scored file list |
+| `/api/room` | GET | List all rooms |
+| `/api/room/<name>` | GET/POST | Read/post room messages |
+| `/api/room/<name>/describe` | POST | Set room description |
+| `/api/telegram/contacts` | GET | List Telegram contacts |
+| `/api/telegram/messages/<id>` | GET | Read messages (windowed) |
+| `/api/telegram/send/<id>` | POST | Send a message |
+| `/api/telegram/send-image/<id>` | POST | Send an image |
+| `/api/telegram/image/<id>` | GET | Get message image (base64) |
+| `/api/telegram/status` | GET | Bridge connection status |
+| `/api/settings` | GET/POST | Settings management |
+| `/api/auth/status` | GET | Auth status (masked key) |
+| `/api/auth/key` | GET | Full API key |
+| `/api/auth/key/regenerate` | POST | Generate new API key |
+| `/api/auth/toggle` | POST | Enable/disable auth |
+
+All endpoints accept `?workspace=` parameter. When omitted, they use the default workspace.
+
+## Search
+
+Requires qmd with a collection matching the workspace name:
+
+```bash
+qmd collection add /path/to/project/vault --name my-project
+qmd index my-project
+```
+
+The background indexer keeps it updated automatically.
+
+Three search modes:
+- **bm25** — keyword search, fast, exact-match oriented
+- **vector** — semantic/vector search, finds conceptually similar content
+- **hybrid** — BM25 + vector + reranking, most thorough (default)
+
+## Dashboard
+
+The React SPA at `localhost:4243` provides:
+
+- **Vault browser** — file tree with previews, heat indicators, frontmatter display
+- **Editor** — markdown editing with frontmatter validation
+- **Terminal** — WebSocket-connected tmux terminal for workspace sessions (Inbox mode for human workspaces)
+- **Activation** — identity crystal viewer, ping scheduler controls
+- **Rooms** — shared chatrooms for cross-workspace communication
+- **Telegram** — contact list, message history, send/receive
+- **Settings** — workspace management, API key management, per-workspace config
+
+## Project structure
+
+```
+fathom-vault/
+├── fathom_server/               # Python package
+│   ├── __init__.py              # Version from importlib.metadata
+│   ├── app.py                   # Flask entry — routes, startup, CLI
+│   ├── auth.py                  # API key generation + Bearer token middleware
+│   ├── config.py                # Port, paths — configurable via env vars
+│   ├── paths.py                 # XDG-compliant data directory resolution
+│   ├── service.py               # systemd user service management
+│   ├── static/                  # Built frontend (copied from frontend/dist/)
+│   ├── routes/
+│   │   ├── vault.py             # Vault CRUD, search, links, activity
+│   │   ├── room.py              # Room chat endpoints
+│   │   ├── settings.py          # Settings, workspace CRUD, auth management
+│   │   ├── activation.py        # Identity crystal + activation
+│   │   ├── telegram.py          # Telegram contacts, messages, images
+│   │   └── terminal.py          # WebSocket terminal (tmux)
+│   └── services/
+│       ├── access.py            # SQLite activity tracking + scoring
+│       ├── settings.py          # Settings persistence
+│       ├── indexer.py           # Background vault indexing (qmd)
+│       ├── links.py             # Wikilink parsing + backlinks
+│       ├── crystallization.py   # Identity crystal synthesis
+│       ├── crystal_scheduler.py # Scheduled crystal regen
+│       ├── persistent_session.py# Workspace session management
+│       ├── ping_scheduler.py    # Scheduled ping routines
+│       ├── telegram_bridge.py   # Telegram bridge (Telethon)
+│       ├── memento.py           # Memento SaaS API integration
+│       └── vault.py             # Core vault file operations
+├── frontend/                    # React SPA (Vite, Tailwind, DaisyUI, xterm.js)
+├── fathom-mcp/                  # MCP tools npm package (see fathom-mcp/README.md)
+├── tests/                       # pytest suite
+├── pyproject.toml               # pip packaging + ruff/pytest config
+└── .env                         # FATHOM_DATA_DIR for development
+```
+
+## Test
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+Pre-commit hooks run ruff (lint + format) and pytest:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## License
+
+MIT

fathom_server-0.1.0/README.md

@@ -0,0 +1,323 @@
+# Fathom Server
+
+Dashboard, API, and background services for [Fathom](https://hifathom.com) — a multi-workspace vault system with search, activity tracking, rooms, and agent coordination.
+
+Runs once, serves all workspaces. Per-workspace MCP tools are provided by [`fathom-mcp`](./fathom-mcp/).
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────┐
+│  fathom-server (Python)                      │
+│                                              │
+│  React Dashboard ─── REST API ─── Services   │
+│  (vault browser,    (Flask,      (indexer,   │
+│   terminal,          :4243)       pings,     │
+│   activation,                     crystal,   │
+│   rooms,                          telegram,  │
+│   telegram)                       access)    │
+│                                              │
+│  Workspace Registry + API Key Auth           │
+└──────────────────┬───────────────────────────┘
+                   │ HTTP localhost:4243
+      ┌────────────┼──────────────┐
+      ▼            ▼              ▼
+┌──────────┐ ┌──────────┐  ┌──────────┐
+│ ws: main │ │ ws: ns   │  │ ws: apps │
+│ npx      │ │ npx      │  │ npx      │
+│ fathom-  │ │ fathom-  │  │ fathom-  │
+│ mcp      │ │ mcp      │  │ mcp      │
+└──────────┘ └──────────┘  └──────────┘
+ Claude inst. Claude inst.  Claude inst.
+```
+
+## Requirements
+
+- Python 3.11+
+- Node.js 18+ (for frontend build and [qmd](https://github.com/nicoblu/qmd))
+- [qmd](https://github.com/nicoblu/qmd) — `npm install -g @tobilu/qmd` (powers search)
+- tmux (for agent sessions and inter-workspace messaging)
+
+## Install
+
+```bash
+git clone https://github.com/myrakrusemark/fathom-vault.git
+cd fathom-vault
+
+# Install Python package + dependencies
+pip install -e .              # editable install — includes CLI entry point
+pip install -e '.[dev]'       # optional: adds pytest + ruff
+
+# Build the frontend
+cd frontend && npm install && npm run build && cd ..
+cp -r frontend/dist/* fathom_server/static/
+```
+
+## Setup
+
+Run the setup command to create the data directory and generate an API key:
+
+```bash
+fathom-server setup           # interactive — prompts for confirmation
+fathom-server setup -y        # non-interactive — just do it
+```
+
+This creates the data directory (see [Data directory](#data-directory) below) and generates an API key. The key is printed once — copy it, you'll need it when running `npx fathom-mcp init` in your project directories.
+
+## Run
+
+```bash
+fathom-server                  # start the server (default: 0.0.0.0:4243)
+fathom-server --port 8080      # custom port
+fathom-server --host 127.0.0.1 # bind to localhost only
+```
+
+Opens at `http://localhost:4243`. On startup the server:
+
+1. Loads all registered workspaces
+2. Starts persistent Claude sessions for each workspace (if configured)
+3. Configures ping schedulers, background indexer, and crystal regeneration
+4. Starts the Telegram bridge (if enabled)
+
+## Install as a system service
+
+Register fathom-server as a systemd user service that starts on boot:
+
+```bash
+fathom-server install                          # install, enable, and start
+fathom-server install --port 8080              # custom port
+fathom-server install --data-dir /opt/fathom   # custom data directory
+fathom-server install --no-start               # install and enable without starting
+```
+
+This writes a unit file to `~/.config/systemd/user/fathom-server.service`, enables linger (so the service survives logout), and starts it.
+
+Manage the service with standard systemd commands:
+
+```bash
+systemctl --user status fathom-server.service
+systemctl --user restart fathom-server.service
+journalctl --user -u fathom-server.service -f
+```
+
+To remove the service:
+
+```bash
+fathom-server uninstall
+```
+
+## CLI reference
+
+```
+fathom-server                    Run the server (default)
+fathom-server serve              Run the server (explicit)
+  --host HOST                    Bind address (default: 0.0.0.0)
+  --port PORT                    Port (default: 4243)
+
+fathom-server setup              First-time setup (data dirs + API key)
+  -y, --yes                      Skip confirmation prompt
+
+fathom-server install            Install as a systemd user service
+  --host HOST                    Bind address (default: 0.0.0.0)
+  --port PORT                    Port (default: 4243)
+  --data-dir DIR                 FATHOM_DATA_DIR override
+  --working-dir DIR              WorkingDirectory for the service
+  --no-start                     Install and enable without starting
+
+fathom-server uninstall          Remove the systemd user service
+```
+
+## Quick start — new workspace
+
+```bash
+# In your project directory:
+npx fathom-mcp init
+```
+
+The init wizard prompts for server URL and API key, creates `.fathom.json`, registers the workspace with the server, and sets up Claude Code hooks. See [`fathom-mcp` README](./fathom-mcp/README.md) for details.
+
+You can also add workspaces via the dashboard at Settings > Workspaces.
+
+## Data directory
+
+Runtime data (SQLite database, API key, vaults, Telegram assets) is stored outside the install directory:
+
+| Priority | Location |
+|----------|----------|
+| 1. `FATHOM_DATA_DIR` env var | Wherever you point it |
+| 2. `XDG_DATA_HOME`/fathom-server | Follows XDG spec |
+| 3. `~/.local/share/fathom-server` | Default fallback |
+
+For development, set `FATHOM_DATA_DIR=./data` in your `.env` file to keep data in the project directory.
+
+### Configuration
+
+**Environment variables** (override defaults):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FATHOM_DATA_DIR` | `~/.local/share/fathom-server` | Runtime data directory |
+| `FATHOM_PORT` | `4243` | Server port |
+| `FATHOM_VAULT_DIR` | (none) | Default vault directory |
+
+**Server config** — `<data-dir>/server.json` (auto-generated):
+
+```json
+{
+  "api_key": "fv_...",
+  "auth_enabled": true
+}
+```
+
+**Per-workspace config** — `<project>/.fathom/settings.json` (auto-created with defaults):
+
+```json
+{
+  "background_index": {
+    "enabled": true,
+    "interval_minutes": 15
+  },
+  "mcp": {
+    "query_timeout_seconds": 120,
+    "search_results": 10,
+    "search_mode": "hybrid"
+  },
+  "activity": {
+    "decay_halflife_days": 7,
+    "recency_window_hours": 48,
+    "show_heat_indicator": true
+  },
+  "crystal_regen": {
+    "enabled": false,
+    "interval_days": 7
+  },
+  "ping": {
+    "routines": []
+  }
+}
+```
+
+## API Authentication
+
+All `/api/*` routes require a Bearer token when auth is enabled:
+
+```bash
+curl -H "Authorization: Bearer fv_abc123..." http://localhost:4243/api/workspaces
+```
+
+The dashboard is exempt (served from the same origin). Manage the API key from the dashboard at Settings > API Key & Auth.
+
+## HTTP API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/workspaces` | GET | List all workspaces with status |
+| `/api/workspaces` | POST | Register a workspace (name, path) |
+| `/api/workspaces/<name>` | DELETE | Unregister a workspace |
+| `/api/vault` | GET | Folder tree |
+| `/api/vault/folder/<path>` | GET | List files with metadata and previews |
+| `/api/vault/file/<path>` | GET/POST | Read/write files |
+| `/api/vault/append/<path>` | POST | Append to files |
+| `/api/search` | GET | Unified search (`?q=...&mode=bm25\|vector\|hybrid`) |
+| `/api/vault/links/<path>` | GET | Forward/backlinks |
+| `/api/vault/activity` | GET | Activity-scored file list |
+| `/api/room` | GET | List all rooms |
+| `/api/room/<name>` | GET/POST | Read/post room messages |
+| `/api/room/<name>/describe` | POST | Set room description |
+| `/api/telegram/contacts` | GET | List Telegram contacts |
+| `/api/telegram/messages/<id>` | GET | Read messages (windowed) |
+| `/api/telegram/send/<id>` | POST | Send a message |
+| `/api/telegram/send-image/<id>` | POST | Send an image |
+| `/api/telegram/image/<id>` | GET | Get message image (base64) |
+| `/api/telegram/status` | GET | Bridge connection status |
+| `/api/settings` | GET/POST | Settings management |
+| `/api/auth/status` | GET | Auth status (masked key) |
+| `/api/auth/key` | GET | Full API key |
+| `/api/auth/key/regenerate` | POST | Generate new API key |
+| `/api/auth/toggle` | POST | Enable/disable auth |
+
+All endpoints accept `?workspace=` parameter. When omitted, they use the default workspace.
+
+## Search
+
+Requires qmd with a collection matching the workspace name:
+
+```bash
+qmd collection add /path/to/project/vault --name my-project
+qmd index my-project
+```
+
+The background indexer keeps it updated automatically.
+
+Three search modes:
+- **bm25** — keyword search, fast, exact-match oriented
+- **vector** — semantic/vector search, finds conceptually similar content
+- **hybrid** — BM25 + vector + reranking, most thorough (default)
+
+## Dashboard
+
+The React SPA at `localhost:4243` provides:
+
+- **Vault browser** — file tree with previews, heat indicators, frontmatter display
+- **Editor** — markdown editing with frontmatter validation
+- **Terminal** — WebSocket-connected tmux terminal for workspace sessions (Inbox mode for human workspaces)
+- **Activation** — identity crystal viewer, ping scheduler controls
+- **Rooms** — shared chatrooms for cross-workspace communication
+- **Telegram** — contact list, message history, send/receive
+- **Settings** — workspace management, API key management, per-workspace config
+
+## Project structure
+
+```
+fathom-vault/
+├── fathom_server/               # Python package
+│   ├── __init__.py              # Version from importlib.metadata
+│   ├── app.py                   # Flask entry — routes, startup, CLI
+│   ├── auth.py                  # API key generation + Bearer token middleware
+│   ├── config.py                # Port, paths — configurable via env vars
+│   ├── paths.py                 # XDG-compliant data directory resolution
+│   ├── service.py               # systemd user service management
+│   ├── static/                  # Built frontend (copied from frontend/dist/)
+│   ├── routes/
+│   │   ├── vault.py             # Vault CRUD, search, links, activity
+│   │   ├── room.py              # Room chat endpoints
+│   │   ├── settings.py          # Settings, workspace CRUD, auth management
+│   │   ├── activation.py        # Identity crystal + activation
+│   │   ├── telegram.py          # Telegram contacts, messages, images
+│   │   └── terminal.py          # WebSocket terminal (tmux)
+│   └── services/
+│       ├── access.py            # SQLite activity tracking + scoring
+│       ├── settings.py          # Settings persistence
+│       ├── indexer.py           # Background vault indexing (qmd)
+│       ├── links.py             # Wikilink parsing + backlinks
+│       ├── crystallization.py   # Identity crystal synthesis
+│       ├── crystal_scheduler.py # Scheduled crystal regen
+│       ├── persistent_session.py# Workspace session management
+│       ├── ping_scheduler.py    # Scheduled ping routines
+│       ├── telegram_bridge.py   # Telegram bridge (Telethon)
+│       ├── memento.py           # Memento SaaS API integration
+│       └── vault.py             # Core vault file operations
+├── frontend/                    # React SPA (Vite, Tailwind, DaisyUI, xterm.js)
+├── fathom-mcp/                  # MCP tools npm package (see fathom-mcp/README.md)
+├── tests/                       # pytest suite
+├── pyproject.toml               # pip packaging + ruff/pytest config
+└── .env                         # FATHOM_DATA_DIR for development
+```
+
+## Test
+
+```bash
+pip install -e '.[dev]'
+pytest
+```
+
+Pre-commit hooks run ruff (lint + format) and pytest:
+
+```bash
+pre-commit install
+pre-commit run --all-files
+```
+
+## License
+
+MIT

fathom_server-0.1.0/fathom_server/__init__.py

@@ -0,0 +1,8 @@
+"""Fathom Server — dashboard + REST API + background services for the vault layer."""
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("fathom-server")
+except Exception:
+    __version__ = "0.0.0-dev"