Hermecious is a self-hosted, agent-assisted sales operations product. It discovers legitimate local businesses, researches their observable needs from permitted sources, matches them to verified offers, and runs consented, policy-gated WhatsApp outreach through to a human handoff. The first market is Lahore, Pakistan, and the first vertical is independent schools.
It is not a bulk-message bot, a scraper of prohibited sources, or a generic CRM.
Foundation work is in progress; EXECUTION_LEDGER.md tracks each subphase. P0.1 provided the documents, ADR-001 and the secrets rules. P0.2 added a local Docker Compose stack: a FastAPI API, an RQ worker, a Next.js web app, Postgres and Redis, each with health probes. P0.3 added CI, the Alembic migration harness and deterministic tests (bash scripts/check.sh). P0.4 added structured logs and the error envelope; P1.1 added operator authentication (create the first owner with docs/runbooks/auth.md). P1.2 added the rights-aware account, source and fact data model (no UI yet). P1.3 added the versioned offer catalog (/offers). P1.4 added account management with evidence entry and corrections (/accounts). P1.5 added durable Postgres jobs and a transactional outbox (ADR-011). P2.1 added the rights-aware discovery adapter framework, exercised only with an offline synthetic fixture. P2.2 added an owner-activated OpenStreetMap (Overpass) source behind a pinned egress client, an operator CSV seed import, and unreviewed candidate staging (docs/runbooks/discovery-sources.md); the live source is off by default and has not yet been run against the real endpoint. P2.3 added conservative campus identity resolution: a deterministic matcher that only suggests, human review decisions with undo, and no automatic merges (docs/contracts/identity-resolution.md). P2.4 added operator discovery runs as durable jobs with a review UI (/discovery), where a reviewer explicitly admits listings as research-pending accounts (ADR-015). P3.1 added source-backed research on accounts: rights-checked sources read by key, deterministic English/Urdu claim extraction with exact locators, and reviewer acceptance into facts (docs/contracts/research.md); live website research is not yet authorized. P3.2 added a six-part school operations brief (observed / hypothesis / conflicting / unknown, with citations and discovery questions; never a ranking). P3.3 added explainable four-axis qualification (ordinal dimensions, fixed-precedence recommendation, audited overrides); contact_now is a research priority with channel eligibility not checked. P3.4 added evidence quality evaluation (/quality): frozen 30-account samples, human verdicts, an honest supported/all metric, linked corrections and a fail-closed enrollment gate. The real 30-account audit has not been run. P4.1 added campaign planning (/campaigns): published-offer-bound campaigns, typed target rules, previews with reasons, approve-for-drafting (gated by evidence quality) and exclusion; it authorizes no contact. P4.2 added the Draft Studio: deterministic, source-grounded, immutable first-contact drafts that are never sendable. P4.3 added a simulation-only channel eligibility engine (/accounts/{id}/contacts): masked contacts, pending-then-owner-verified opt-in evidence, org-wide suppressions and a deterministic eligibility-policy-1.0 reading that never authorizes a send (docs/contracts/channel-eligibility.md). P4.4 added the Approval Studio in the Draft Studio: grounded edits as new immutable revisions and simulation-only "Approve content only" receipts bound to the exact revision, contact and eligibility, re-validated on every read (docs/contracts/approvals.md). P4.5 added a zero-egress Dry Run on campaigns: bounded, fresh-checked simulations with a fake transport and a reconciled, redacted report labelled "SIMULATION ONLY — 0 real messages sent" (docs/contracts/simulations.md). There is no messaging.
| Path | Purpose |
|---|---|
docs/HERMECIOUS_EXECUTION_BLUEPRINT_v1.md |
Master technical specification (source of truth) |
docs/phases/ |
Phase implementation packages and per-subphase prompts |
AGENTS.md |
Operating contract for coding agents and contributors |
EXECUTION_LEDGER.md |
Subphase status, evidence, blockers and rollback notes |
docs/adr/ |
Architecture decision records |
docs/runbooks/secrets.md |
Secrets rules and leak response |
.env.example |
Environment variable template (names only for secrets) |
scripts/verify-setup.sh |
Baseline check: required documents and secrets rules |
compose.yaml |
The local development stack |
apps/api/ |
FastAPI app and RQ worker (Python 3.13, uv) |
apps/web/ |
Next.js operator UI (Node 22, npm) |
docs/runbooks/local-development.md |
Stack commands, health contracts, recovery and troubleshooting |
docs/runbooks/testing.md |
scripts/check.sh, test layout, integration stack, migrations, time control |
docs/runbooks/observability.md |
JSON logs, redaction, request IDs, error envelope |
docs/runbooks/auth.md |
Owner bootstrap, sessions, CSRF, roles, login limits |
docs/contracts/core-domain.md |
Accounts, sources, facts: schema, rights policy, fact rules |
docs/contracts/offer-catalog.md |
Offers: revisions, publication rules, sales-ready projection |
docs/contracts/account-management.md |
Accounts API/UI, evidence entry, corrections, audit trail |
docs/contracts/job-outbox.md, docs/runbooks/jobs.md |
Durable jobs, transactional outbox, worker operations |
docs/contracts/source-adapters.md |
Discovery source adapters, rights policy, budgets (offline fixture) |
.github/workflows/ci.yml |
CI: runs scripts/check.sh |
Prerequisites: git, bash, curl, openssl and Docker with the Compose v2 plugin. Python and Node are only needed to work on the code outside containers.
# Private repository: needs a GitHub account with access (SSH shown).
git clone git@github.com:cognetheus/hermecious.git
cd hermecious
cp .env.example .env
chmod 600 .env
sed -i.bak "s/^POSTGRES_PASSWORD=$/POSTGRES_PASSWORD=$(openssl rand -hex 32)/" .env && rm .env.bak
bash scripts/verify-setup.sh
docker compose up --build -d
docker compose run --rm --no-deps api python -m alembic upgrade head # the worker is unhealthy until this runs
bash scripts/smoke-local.shverify-setup.sh must end with All checks passed and smoke-local.sh with All smoke checks passed. A FAIL line names what was broken. The secrets rules are explained in docs/runbooks/secrets.md. The stack commands (logs, restart, stop, recovery checks) are in docs/runbooks/local-development.md.
To run the check's own tests:
bash scripts/verify-setup.test.shSee ADR-001. Hermecious is a modular monolith (FastAPI with a separate worker, PostgreSQL as the system of record, Redis as the queue and a Next.js operator UI) deployed with Docker Compose on one VPS. The worker runs a Postgres-authoritative job runner with Redis as an optional wake-up channel (ADR-011, superseding the runtime role of ADR-009).
Read AGENTS.md first. Work proceeds one blueprint subphase at a time, and each subphase records its evidence in the ledger.