gmeow 1.0.0__tar.gz

gmeow-1.0.0/.gitignore

@@ -0,0 +1,39 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+data/
+*.egg-info/
+.env
+.env.*
+config.toml
+config/*.local.*
+config/gmeow.yaml
+config/*.secret.*
+**/service-account*.json
+**/*service_account*.json
+**/imap-password
+exports/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# coding-ethos generated runtime output
+.code-ethos/cache/
+.coding-ethos/cache/
+.coding-ethos/code-intel.db
+.coding-ethos/hook-runs/
+.coding-ethos/lint-runs/
+.coding-ethos/prune-runs/
+.coding-ethos/state/
+.coding-ethos/code-intel.*
+
+.coding-ethos/code-intel.db-shm
+.coding-ethos/code-intel.db-wal
+
+.coding-ethos/code-intel.duckdb
+.coding-ethos/code-intel.duckdb.wal
+.coding-ethos/events/

gmeow-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,61 @@
+<!-- SPDX-FileCopyrightText: 2026 Blackcat Informatics Inc. -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Gmeow Contributor Code of Conduct
+
+## Purpose
+
+Gmeow is a professional open source project stewarded by Blackcat Informatics
+Inc. We want collaboration here to stay technical, respectful, privacy-aware,
+and productive.
+
+## Expectations
+
+We ask contributors to:
+
+- stay technical and focus discussions on code, docs, testing, security,
+  privacy, and design
+- be respectful and critique ideas rather than people
+- assume good intent and ask clarifying questions before escalating
+- keep feedback specific, actionable, and professional
+- avoid posting private mailbox data, credentials, personal information, or
+  attachment contents in project spaces
+- help maintain a working environment where contributors can do high-quality
+  engineering work
+
+## Unacceptable Behavior
+
+The following is not acceptable in project spaces such as issues, pull requests,
+discussions, chats, or events:
+
+- harassment, discrimination, or threats
+- personal attacks, intimidation, or bullying
+- sustained disruption that derails collaboration
+- publishing private information without consent
+- posting mailbox data, secrets, access tokens, or private attachment content
+- coordinated bad-faith participation, trolling, or sealioning
+
+## Enforcement
+
+Project maintainers may take any action they deem appropriate, including
+warnings, requests to disengage, comment moderation, removal of sensitive
+content, or bans from project spaces. Decisions are final.
+
+## Reporting
+
+If you experience or witness behavior that violates this Code of Conduct:
+
+- email <conduct@blackcat.ca>
+- include links, context, and any relevant screenshots or logs
+- avoid public escalation while a report is being reviewed
+
+Reports are handled confidentially and will be acknowledged within two business
+days.
+
+Security vulnerabilities should be reported through [SECURITY.md](SECURITY.md)
+rather than the conduct process.
+
+## Attribution
+
+This policy is adapted from common open source codes of conduct and tailored for
+the Gmeow project.

gmeow-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,189 @@
+<!-- SPDX-FileCopyrightText: 2026 Blackcat Informatics Inc. -->
+<!-- SPDX-License-Identifier: MIT -->
+
+# Contributing to Gmeow
+
+Gmeow is an open source local Gmail intelligence, archive, REST, MCP, and
+read-only IMAP service maintained by Blackcat Informatics Inc. Contributions to
+code, tests, documentation, migrations, and release tooling are welcome.
+
+## Code of Conduct
+
+Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating. We
+expect respectful, professional collaboration. To report unacceptable behavior,
+email <conduct@blackcat.ca>.
+
+## Security and Privacy First
+
+Gmeow works with private mailbox data. Treat privacy as part of the engineering
+contract.
+
+- Do not commit `config.toml`, credentials, mailbox exports, object-store data,
+  database dumps, SOPS files, or runtime data.
+- Use synthetic fixtures in tests and examples.
+- Do not paste real Gmail messages, access tokens, service-account keys,
+  database passwords, or private attachment content into issues or pull
+  requests.
+- Report vulnerabilities through [SECURITY.md](SECURITY.md), not public issues.
+
+## Ways to Contribute
+
+### Report Bugs
+
+Before opening an issue:
+
+- search existing issues first
+- verify the problem on the latest code in `main` when possible
+- reproduce against synthetic data or a disposable local database
+
+Include:
+
+- a clear title
+- exact reproduction steps
+- expected behavior
+- actual behavior
+- relevant command output or stack traces
+- OS, Python version, PostgreSQL version, and `uv` version
+
+### Suggest Enhancements
+
+Good enhancement requests usually include:
+
+- the workflow or mailbox-management problem you are solving
+- the current limitation
+- the proposed behavior
+- concrete examples of expected REST, MCP, CLI, or database behavior
+
+### Submit Pull Requests
+
+1. Fork the repository and create a branch from `main`.
+2. Install dependencies.
+3. Make the smallest coherent change that solves the problem.
+4. Add or update tests when behavior changes.
+5. Update README or docs when public behavior, commands, endpoints, schemas, or
+   outputs change.
+6. Run the verification steps below before requesting review.
+
+## Contributor License Agreement
+
+External contributions may require the project Contributor License Agreement,
+enforced by CLA Assistant:
+
+The CLA link is provided by CLA Assistant on pull requests when it is required.
+
+When CLA Assistant comments on your pull request, follow the signing link and
+sign in with GitHub to accept the agreement. The CLA confirms that you have the
+right to submit the contribution and grants the project the rights needed to use
+and redistribute it.
+
+Developer Certificate of Origin style sign-off trailers are welcome as
+additional contribution evidence, but DCO sign-off does not replace a required
+CLA Assistant check:
+
+```text
+Signed-off-by: Your Name <you@example.com>
+```
+
+## Governance and Continuity
+
+Gmeow is maintained by Blackcat Informatics Inc. Project decisions are made
+through GitHub issues, pull requests, discussions, security reports, and release
+reviews, using the repository quality bar, security policy, and release process
+as the decision framework.
+
+Repository owners and code owners are listed in `.github/CODEOWNERS` when that
+file exists.
+
+## Development Setup
+
+### Prerequisites
+
+- Git
+- Python 3.13+
+- PostgreSQL suitable for integration testing
+- `uv`
+
+### Local Setup
+
+```bash
+uv sync --extra test
+cp config.toml-example config.toml
+```
+
+Use a disposable database for integration testing. Do not point tests or local
+development at a production mailbox database.
+
+Example local test DSN:
+
+```text
+postgresql://gmeow-test:gmeow-test@127.0.0.1:5432/gmeow-test
+```
+
+## Project-Specific Guidance
+
+- If REST endpoint behavior changes, update API examples and tests.
+- If MCP tools change, update help text and any client-facing examples.
+- If CLI behavior changes, update README usage and command verification.
+- If database schema changes, add or update Alembic migrations and migration
+  comments.
+- If attachment analysis behavior changes, cover privacy and hostile-file
+  handling risks in tests or docs.
+- If archive, retention, or object-store behavior changes, verify data-loss and
+  restore paths explicitly.
+
+## Coding Style
+
+Contributions must pass the project lint, formatting, and test gates.
+
+- Python follows PEP 8 plus the stricter Ruff configuration in this repository.
+- Type hints are expected for public functions and non-trivial helpers.
+- Prefer structural fixes over lint suppressions.
+- Keep changes focused; avoid unrelated refactors.
+- Use standard library or existing project helpers before adding dependencies.
+
+## Verification
+
+Before requesting review, run the checks relevant to your change:
+
+```bash
+uvx ruff format --config ruff.toml main.py migrations scripts src
+uvx ruff check --config ruff.toml main.py migrations scripts src
+uv run python -m compileall main.py src migrations tests
+uv run pytest
+uv build
+uv run python scripts/public_release_check.py
+```
+
+For database-backed changes, also run against a disposable local PostgreSQL
+database and document the DSN shape used, without committing private
+credentials.
+
+## Commit Messages
+
+We prefer Conventional Commits:
+
+- `feat:` new functionality
+- `fix:` bug fixes
+- `docs:` documentation-only changes
+- `refactor:` internal restructuring without behavior change
+- `test:` test additions or updates
+- `chore:` maintenance work
+
+Examples:
+
+```text
+feat: add archive verification endpoint
+fix: preserve raw RFC822 during retention preview
+docs: clarify local database setup
+test: cover category exclusion in text search
+```
+
+## Questions
+
+For public questions, open an issue or discussion in the repository. For private
+matters, email <oss@blackcat.ca>.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+project license defined in [LICENSE](LICENSE).

gmeow-1.0.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Blackcat Informatics® Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gmeow-1.0.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: gmeow
+Version: 1.0.0
+Summary: Local Gmail intelligence server for agents, MCP, and REST automation
+Project-URL: Homepage, https://github.com/blackcat-informatics/gmeow
+Project-URL: Repository, https://github.com/blackcat-informatics/gmeow
+Project-URL: Issues, https://github.com/blackcat-informatics/gmeow/issues
+Project-URL: PyPI, https://pypi.org/project/gmeow/
+Author: Blackcat Informatics Inc.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,archive,email,gmail,knowledge-graph,mcp,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.13
+Requires-Dist: alembic>=1.18.4
+Requires-Dist: blake3>=1.0
+Requires-Dist: en-core-web-sm
+Requires-Dist: fastapi>=0.115
+Requires-Dist: google-api-python-client>=2.150
+Requires-Dist: google-auth-httplib2>=0.2
+Requires-Dist: google-auth>=2.36
+Requires-Dist: mcp>=1.8
+Requires-Dist: pgvector>=0.3
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: pydantic>=2.10
+Requires-Dist: rustworkx>=0.15
+Requires-Dist: scikit-learn>=1.8.0
+Requires-Dist: semchunk>=4.0.0
+Requires-Dist: spacy>=3.8.14
+Requires-Dist: tantivy>=0.22
+Requires-Dist: uvicorn[standard]>=0.32
+Requires-Dist: zstandard>=0.23
+Provides-Extra: test
+Requires-Dist: httpx>=0.27; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackcat-informatics/gmeow/main/docs/gmeow-logo.svg" alt="Gmeow logo" width="280">
+</p>
+
+# Gmeow
+
+Local Gmail intelligence for agents.
+
+Gmeow turns a Gmail mailbox into a local intelligence layer for agents and automation. It exposes a loopback REST API and an MCP Streamable HTTP endpoint over an authenticated Gmail mailbox, while maintaining a local PostgreSQL-backed cache, semantic index, attachment object store, and knowledge graph.
+
+Gmeow is designed for trusted single-user local systems. By default it binds to `127.0.0.1` and does not add application-level authentication. Do not expose it directly to an untrusted network.
+
+## What Gmeow Does
+
+- Gives agents a local MCP and REST interface to search, read, and act on Gmail without scraping a browser.
+- Builds a durable local archive with raw RFC822 messages, attachment payloads, labels, threads, sync state, and search indexes.
+- Adds semantic search, category discovery, and knowledge-graph views over mailbox content.
+- Extracts attachment metadata and text so documents, images, archives, PDFs, and calendar files become searchable context.
+- Serves the cached archive through read-only IMAP for tools that already speak mail protocols.
+
+## Features
+
+- Gmail mailbox access through Google Workspace service-account delegation or local user OAuth.
+- REST and MCP tools for search, reads, labels, archive/read/star state, contacts, categories, graph exploration, and archive operations.
+- PostgreSQL catalog for labels, threads, headers, MIME structure, categories, graph triples, jobs, sync state, and pgvector embedding chunks.
+- Live Gmail search hydration: unbounded searches can query Gmail, cache returned messages, and enqueue analysis work.
+- Full local object storage for payload bytes using a BLAKE3 content-addressed store with zstd compression for compressible content.
+- Attachment sidecars with Gmail source metadata, `exiftool` metadata, extracted text, OCR, archive listings, document conversion, and optional vision captions.
+- Semantic search using `semchunk` chunking and an OpenAI-compatible embedding endpoint.
+- Knowledge graph extraction with RDF/RDFS, FOAF, SIOC, schema.org, SKOS, PROV-O, and DOAP alignment.
+- Rustworkx graph projection, paths, ranking, centrality, components, project views, and related-node discovery.
+- Category rules plus learned category suggestions from TF-IDF clustering.
+- Timed maintenance jobs for history sync, priority sync, intelligence workers, derived views, PostgreSQL analyze, and optional sidecar refresh.
+- Token-Oriented Object Notation by default for MCP responses, with JSON available on request.
+- Read-only IMAP service backed by cached RFC822 archive objects.
+
+## Install
+
+```bash
+uv sync --extra test
+cp config.toml-example config.toml
+```
+
+Edit `config.toml`. All Gmeow settings live under `[gmeow]` so this file can be shared with other Google proxy/archive applications.
+
+```toml
+[gmeow]
+subject = "user@example.com"
+service_account_file = "data/secrets/service-account.json"
+postgres_dsn = "postgresql://gmeow:change-me@127.0.0.1:5432/gmeow"
+embedding_endpoint = "http://127.0.0.1:8090/v1/embeddings"
+
+[gmeow.secrets]
+file = "~/.config/gmeow/secrets.sops.yaml"
+unlock_key = "replace-with-local-unlock-key"
+age_key = "AGE-SECRET-KEY-REPLACE-WITH-LOCAL-SOPS-AGE-IDENTITY"
+```
+
+When `[gmeow.secrets]` is configured, Gmeow decrypts the SOPS YAML file at startup and uses `postgres_dsn`, `service_account_json`, `user_credentials_json`, and `imap_password` from that single encrypted file. Configured credential file paths remain explicit fallback paths for local deployments that do not use SOPS.
+
+Generate Google Cloud service-account provisioning commands:
+
+```bash
+uv run gmeow provision-plan YOUR_PROJECT_ID
+```
+
+Authorize the generated service-account OAuth client ID in Google Admin Console for:
+
+```text
+https://www.googleapis.com/auth/gmail.modify
+```
+
+As a local fallback, set `auth_mode = "user_oauth"` under `[gmeow]` and create Gmail-scoped ADC credentials:
+
+```bash
+gcloud auth application-default login --scopes=https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/cloud-platform
+```
+
+## Run
+
+```bash
+uv run gmeow serve --host 127.0.0.1 --port 8765
+```
+
+REST is available under `/api/v1`. MCP is mounted at `/mcp` when the installed MCP SDK provides an ASGI app.
+
+For persistent local operation under your user account, see [docs/systemd.md](docs/systemd.md).
+
+Useful commands:
+
+```bash
+uv run gmeow status
+uv run gmeow doctor
+uv run gmeow sync
+uv run gmeow sync-history
+uv run gmeow refresh-attachment-sidecars
+uv run gmeow enqueue-intelligence
+uv run gmeow run-intelligence-worker
+uv run gmeow rebuild-intelligence
+uv run gmeow discover-categories --since-hours 48
+uv run gmeow seed-categories
+uv run gmeow recategorize
+uv run gmeow category-stats
+```
+
+`gmeow serve` starts timed maintenance tasks from `[gmeow.maintenance]`. Use `GET /api/v1/maintenance/timed` for scheduler state and `POST /api/v1/maintenance/timed/{task_name}/run` to run one task immediately.
+
+## MCP
+
+Most MCP read/search tools return compact TOON by default. Pass `format: "json"` when an agent needs JSON-shaped results.
+
+Example local agent configuration:
+
+```json
+{
+  "mcpServers": {
+    "gmeow": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/mcp"
+    }
+  }
+}
+```
+
+Useful MCP tools include text/semantic/hybrid search, attachment text search, message/thread reads, attachment metadata, contacts/people, category tools, graph search/path/rank/project tools, status/help, history sync, priority sync, and limited mailbox actions.
+
+## Local Data
+
+By default, local data is ignored by git and stored under `data/`:
+
+- PostgreSQL stores labels, threads, message headers/metadata, MIME structure, sync state, categories, graph triples, async jobs, and pgvector embedding chunks. Schema changes are versioned through Alembic migrations under `migrations/`.
+- `data/objects/blake3/aa/bb/<digest>[.zst]` stores canonical payload bytes in the BLAKE3 content-addressed store.
+- `data/objects/sidecars/aa/bb/<digest>.json` stores attachment sidecar metadata, source metadata, extracted text, and external enrichment.
+- `data/tantivy/` stores the local lexical search index.
+- `data/secrets/` stores local credential files only when you choose file-based credentials instead of SOPS.
+
+## Archive and IMAP
+
+Archive-complete messages require both Gmail full JSON and canonical raw RFC822 bytes. New Gmail hydrations fetch RFC822 automatically. Existing cached messages can be completed in bounded batches:
+
+```bash
+uv run gmeow complete-archive --limit 25
+uv run gmeow archive-status
+uv run gmeow verify-objects
+```
+
+Read-only IMAP is available as a loopback service. It exposes Gmail labels as folders, assigns stable per-folder UIDs, serves RFC822 from CAS, and rejects mutating IMAP commands.
+
+```bash
+printf 'choose-a-local-password\n' > data/secrets/imap-password
+uv run gmeow serve-imap --host 127.0.0.1 --port 1143
+```
+
+## Development
+
+```bash
+uv sync --extra test
+uv run python -m compileall main.py src migrations tests
+uv run pytest
+uv build
+uv run python scripts/public_release_check.py
+```
+
+PostgreSQL-backed integration tests are skipped unless `GMEOW_TEST_POSTGRES_DSN` points at a disposable test database. Tests must not use a production database.
+
+Before publishing, run the checklist in `docs/PUBLIC_RELEASE_CHECKLIST.md`.
+
+## License
+
+Gmeow is licensed under the MIT License. See `LICENSE`.

gmeow-1.0.0/README.md

@@ -0,0 +1,170 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/blackcat-informatics/gmeow/main/docs/gmeow-logo.svg" alt="Gmeow logo" width="280">
+</p>
+
+# Gmeow
+
+Local Gmail intelligence for agents.
+
+Gmeow turns a Gmail mailbox into a local intelligence layer for agents and automation. It exposes a loopback REST API and an MCP Streamable HTTP endpoint over an authenticated Gmail mailbox, while maintaining a local PostgreSQL-backed cache, semantic index, attachment object store, and knowledge graph.
+
+Gmeow is designed for trusted single-user local systems. By default it binds to `127.0.0.1` and does not add application-level authentication. Do not expose it directly to an untrusted network.
+
+## What Gmeow Does
+
+- Gives agents a local MCP and REST interface to search, read, and act on Gmail without scraping a browser.
+- Builds a durable local archive with raw RFC822 messages, attachment payloads, labels, threads, sync state, and search indexes.
+- Adds semantic search, category discovery, and knowledge-graph views over mailbox content.
+- Extracts attachment metadata and text so documents, images, archives, PDFs, and calendar files become searchable context.
+- Serves the cached archive through read-only IMAP for tools that already speak mail protocols.
+
+## Features
+
+- Gmail mailbox access through Google Workspace service-account delegation or local user OAuth.
+- REST and MCP tools for search, reads, labels, archive/read/star state, contacts, categories, graph exploration, and archive operations.
+- PostgreSQL catalog for labels, threads, headers, MIME structure, categories, graph triples, jobs, sync state, and pgvector embedding chunks.
+- Live Gmail search hydration: unbounded searches can query Gmail, cache returned messages, and enqueue analysis work.
+- Full local object storage for payload bytes using a BLAKE3 content-addressed store with zstd compression for compressible content.
+- Attachment sidecars with Gmail source metadata, `exiftool` metadata, extracted text, OCR, archive listings, document conversion, and optional vision captions.
+- Semantic search using `semchunk` chunking and an OpenAI-compatible embedding endpoint.
+- Knowledge graph extraction with RDF/RDFS, FOAF, SIOC, schema.org, SKOS, PROV-O, and DOAP alignment.
+- Rustworkx graph projection, paths, ranking, centrality, components, project views, and related-node discovery.
+- Category rules plus learned category suggestions from TF-IDF clustering.
+- Timed maintenance jobs for history sync, priority sync, intelligence workers, derived views, PostgreSQL analyze, and optional sidecar refresh.
+- Token-Oriented Object Notation by default for MCP responses, with JSON available on request.
+- Read-only IMAP service backed by cached RFC822 archive objects.
+
+## Install
+
+```bash
+uv sync --extra test
+cp config.toml-example config.toml
+```
+
+Edit `config.toml`. All Gmeow settings live under `[gmeow]` so this file can be shared with other Google proxy/archive applications.
+
+```toml
+[gmeow]
+subject = "user@example.com"
+service_account_file = "data/secrets/service-account.json"
+postgres_dsn = "postgresql://gmeow:change-me@127.0.0.1:5432/gmeow"
+embedding_endpoint = "http://127.0.0.1:8090/v1/embeddings"
+
+[gmeow.secrets]
+file = "~/.config/gmeow/secrets.sops.yaml"
+unlock_key = "replace-with-local-unlock-key"
+age_key = "AGE-SECRET-KEY-REPLACE-WITH-LOCAL-SOPS-AGE-IDENTITY"
+```
+
+When `[gmeow.secrets]` is configured, Gmeow decrypts the SOPS YAML file at startup and uses `postgres_dsn`, `service_account_json`, `user_credentials_json`, and `imap_password` from that single encrypted file. Configured credential file paths remain explicit fallback paths for local deployments that do not use SOPS.
+
+Generate Google Cloud service-account provisioning commands:
+
+```bash
+uv run gmeow provision-plan YOUR_PROJECT_ID
+```
+
+Authorize the generated service-account OAuth client ID in Google Admin Console for:
+
+```text
+https://www.googleapis.com/auth/gmail.modify
+```
+
+As a local fallback, set `auth_mode = "user_oauth"` under `[gmeow]` and create Gmail-scoped ADC credentials:
+
+```bash
+gcloud auth application-default login --scopes=https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/cloud-platform
+```
+
+## Run
+
+```bash
+uv run gmeow serve --host 127.0.0.1 --port 8765
+```
+
+REST is available under `/api/v1`. MCP is mounted at `/mcp` when the installed MCP SDK provides an ASGI app.
+
+For persistent local operation under your user account, see [docs/systemd.md](docs/systemd.md).
+
+Useful commands:
+
+```bash
+uv run gmeow status
+uv run gmeow doctor
+uv run gmeow sync
+uv run gmeow sync-history
+uv run gmeow refresh-attachment-sidecars
+uv run gmeow enqueue-intelligence
+uv run gmeow run-intelligence-worker
+uv run gmeow rebuild-intelligence
+uv run gmeow discover-categories --since-hours 48
+uv run gmeow seed-categories
+uv run gmeow recategorize
+uv run gmeow category-stats
+```
+
+`gmeow serve` starts timed maintenance tasks from `[gmeow.maintenance]`. Use `GET /api/v1/maintenance/timed` for scheduler state and `POST /api/v1/maintenance/timed/{task_name}/run` to run one task immediately.
+
+## MCP
+
+Most MCP read/search tools return compact TOON by default. Pass `format: "json"` when an agent needs JSON-shaped results.
+
+Example local agent configuration:
+
+```json
+{
+  "mcpServers": {
+    "gmeow": {
+      "type": "http",
+      "url": "http://127.0.0.1:8765/mcp"
+    }
+  }
+}
+```
+
+Useful MCP tools include text/semantic/hybrid search, attachment text search, message/thread reads, attachment metadata, contacts/people, category tools, graph search/path/rank/project tools, status/help, history sync, priority sync, and limited mailbox actions.
+
+## Local Data
+
+By default, local data is ignored by git and stored under `data/`:
+
+- PostgreSQL stores labels, threads, message headers/metadata, MIME structure, sync state, categories, graph triples, async jobs, and pgvector embedding chunks. Schema changes are versioned through Alembic migrations under `migrations/`.
+- `data/objects/blake3/aa/bb/<digest>[.zst]` stores canonical payload bytes in the BLAKE3 content-addressed store.
+- `data/objects/sidecars/aa/bb/<digest>.json` stores attachment sidecar metadata, source metadata, extracted text, and external enrichment.
+- `data/tantivy/` stores the local lexical search index.
+- `data/secrets/` stores local credential files only when you choose file-based credentials instead of SOPS.
+
+## Archive and IMAP
+
+Archive-complete messages require both Gmail full JSON and canonical raw RFC822 bytes. New Gmail hydrations fetch RFC822 automatically. Existing cached messages can be completed in bounded batches:
+
+```bash
+uv run gmeow complete-archive --limit 25
+uv run gmeow archive-status
+uv run gmeow verify-objects
+```
+
+Read-only IMAP is available as a loopback service. It exposes Gmail labels as folders, assigns stable per-folder UIDs, serves RFC822 from CAS, and rejects mutating IMAP commands.
+
+```bash
+printf 'choose-a-local-password\n' > data/secrets/imap-password
+uv run gmeow serve-imap --host 127.0.0.1 --port 1143
+```
+
+## Development
+
+```bash
+uv sync --extra test
+uv run python -m compileall main.py src migrations tests
+uv run pytest
+uv build
+uv run python scripts/public_release_check.py
+```
+
+PostgreSQL-backed integration tests are skipped unless `GMEOW_TEST_POSTGRES_DSN` points at a disposable test database. Tests must not use a production database.
+
+Before publishing, run the checklist in `docs/PUBLIC_RELEASE_CHECKLIST.md`.
+
+## License
+
+Gmeow is licensed under the MIT License. See `LICENSE`.