harborclerk: Instructions file for Codex

AGENTS.md

Operating rules for any agent or human working in this repository. Rules here are binding. Reference material — architecture, API surface, schema — lives elsewhere; see Map. On matters of fact, the code is authoritative and this file may be stale: trust the source and fix this file. On matters of rule, this file is authoritative.

What this is

Harbor Clerk is a single-tenant, local-first document intelligence system: local extraction, OCR (eng/fra), hybrid retrieval with reranking, cited local-AI answers, and Research. It runs as a Mac-native app or via Docker Compose, and exposes the corpus to external agents through an MCP server and a mirrored CLI.

Non-negotiables

• Single-tenant. No tenant_id in schema, API, or code. Ever.
• Read-only external access. API keys are read-only and stored hashed.
• Snippets, not corpus. MCP/CLI callers receive retrieved passages and citations — never a bulk corpus export.
• Never modify a source. Watched-folder files are never altered, copied, or moved. Mailboxes are read-only (IMAP EXAMINE; read-only OAuth scopes when OAuth lands) — never marked read, never deleted.
• Copy only where the source requires it. Watched-folder documents are read in place from source_path. IMAP is the deliberate exception: messages and attachments must be fetched and stored, because there is no file to reference.
• All results carry citations. Every retrieval surface returns sources.
• Tika is required for PDF/Office/eBook/HTML/email extraction.
• Never commit credentials. Passwords, API keys, JWTs, or tokens supplied in conversation never enter a file, regardless of stated intent.
• Strategy stays private. Positioning, competitive analysis, claim posture, and candid assessment live in docs/strategy/ (a separate private repo), never here.

Working agreement

• Branch first. Create a feature branch before any change, including docs. Never commit to main. Do this from the start, not retroactively.
• PR always. Every change lands via PR, even docs-only. Branch protection is enforced.
• Never bypass the gate. No gh pr merge --admin, no direct push to main, without explicit human permission in the current conversation.
• Verify before claiming done. Run the checks and read the output before saying anything passes. Evidence, then assertion.
• Don't stack PRs. Land the base on main and branch again. A stacked branch once lost ~3,000 lines to a squash-merge of its base.
• Regenerate docs after changing tools, routes, models, stages, or compose services: uv run python -m scripts.gen_docs. CI fails otherwise.
• dependency-audit can fail on an unrelated PR. It audits the whole environment against live advisory databases, so a newly-published CVE turns it red on a change that touched nothing relevant.