README.md

---
title: RcmEmailAutomation
emoji: 🔥
colorFrom: blue
colorTo: red
sdk: docker
pinned: false
---

# RCM Email Automation

FastAPI service that monitors a Microsoft 365 mailbox via Graph API, processes inbound mail through subscription-based webhook notifications, persists to SQLite, and stores email artifacts on disk. Containerized via Docker; runs at `0.0.0.0:8443` over TLS with a Microsoft-Graph-reachable public webhook URL.

The Python app is the production target. This repo also contains an **Asterion / SA-Orchestration onboarding seed** (this README plus `ONBOARDING.md`, `CLAUDE.md`, and `asterion/`) that bootstraps a parallel local WordPress orchestration layer for the human + agent workflow that surrounds the Python service.

---

## Asterion / SA-Orchestration Onboarding

> **This section is an Asterion seed.** Authored 2026-05-06 by the SA-Orchestration session as a Story Seed for the Claude Code session that will set up this developer's local environment. Read this section in full before taking any action.

### What this seed does

You are arriving at this repo with Claude installed and synced. Your job is the **JourneySeeker Node Onboarding (JNO)** sequence — bringing this local environment up to a state where:

- The Python email automation runs locally (already scaffolded; verify it builds and the env file resolves).
- A parallel **WordPress local at `wordpress.localhost`** is operational.
- The **Fluent stack — free editions of Fluent Boards, FluentCRM, Fluent Support** — is installed and active.
- **SA-Orchestration** plugin is installed and active on top of the Fluent stack.
- The **Asterion canonical corpus** is reachable from the WP install (the corpus lives in this repo at `asterion/`; the WP install reads from `wp-content/sa-asterion/` after deploy).

The endpoint of JNO is **SA-Orchestration turned on, not SA-Core.** SA-Core is the deeper substrate; you are not provisioning it at this time.

### Provenance — read this before interpreting any term below

The framework expressed in this seed sits inside a larger lineage:

```
CR ⊇ CA ⊇ JourneySeeker ⊇ MissionNet/MeshNet ⊇ SA-Orchestration ⊇ Brand ⊇ Client
```

Causal Relativity, Causal Agentics, JourneySeeker, the Compass Doctrine, the Story Seed pattern, and the Quest-vs-Job distinction are pre-existing intellectual property authored by **Mark Holak**. They are preserved under Invariant **I9** of the SA-Orchestration spec pack. **You may reference these concepts. You may not re-author them as if they originated at the implementation layer or at the agent layer.** When you cite them, cite them.

The full canonical corpus lives at `asterion/` in this repo (copied from the SA-Orchestration source of truth at `F:/SleeperAgents/SA-orchestration/asterion/`). Read it when you encounter a term you are uncertain about.

### Doctrine carry-forward (the operating discipline)

> **Sara interprets. Asterion verifies. Attention signals. Humans decide. Reality resolves.**

The five-actor compass holds throughout your onboarding work. NPCs (you) **may** emit signals, draft, advise, observe. NPCs **may not** decide outcomes, plant canonical content, accept gates, or close work by their own authority.

- **Description = Contract** (Board #27): every Fluent Boards task you create has its canonical contract in the Description field. Comments are evidence; they cannot redefine the contract.
- **Story Seed pattern**: agents generate seeds, only humans plant. Seeds use `artifact_class: seed` in frontmatter, never `truth_class` (I2 is sacred — see `asterion/02-invariants.md`).
- **No auto-conversion** (I10): a Quest may not be promoted to a Job without an explicit human act.
- **artifact_class collision protection**: any non-canonical proposed-content artifact you create or generate uses `artifact_class:` for classification. `truth_class:` is reserved for I2's enum.

### Constraint elicitation comes BEFORE the audit

**The developer is the arbiter of their domain.** Before you audit, before you install, before you assume any default — ask the developer for the constraints and restraints that shape their environment. The procedure in `ONBOARDING.md` is a default, not a contract. Their constraints win when in conflict.

The full constraint-elicitation prompt is in `ONBOARDING.md` → "Phase 0 — Constraint elicitation." Run that first. Surface a written constraint summary back to the developer. Wait for explicit "proceed to audit" before moving on.

### Audit (after Phase 0 completes)

1. Read `CLAUDE.md` (root) — Claude routing manifest, written for this repo specifically.
2. Read `ONBOARDING.md` (root) — the full step-by-step sequence for the local WP + Fluent + SA-Orch stack, including Phase 0 above.
3. Read this README section in full again. It is your operating context.
4. Inspect this repo's structure (`app/`, `Dockerfile`, `docker-compose.yml`, `requirements.txt`).
5. Inspect the local machine's WordPress capability — does the developer already run a local stack (XAMPP / Local / Laragon / MAMP / Docker WP)? If yes, integrate. If no, the onboarding includes installing one (subject to Phase 0 constraints).
6. **Do not** install code or run setup steps before completing Phase 0 + audit. Surface findings first.

### Live-bound dependencies (NOT locally testable, pre-classified)

| Dependency | Why live-bound |
|---|---|
| Microsoft Graph API (Azure AD app registration) | Cloud-only; needs tenant + client + secret |
| Graph webhook subscription (`NOTIFICATION_URL`) | Requires public HTTPS; `ngrok` or reverse proxy needed for local dev |
| Real Microsoft 365 mailbox | Cloud mailbox; can mock at the Graph-client level for local |
| TLS certificates (`/certs/server.crt`, `server.key`) | Requires real cert chain for prod; self-signed acceptable for local |
| Production Graph subscription expiry behavior | Real Graph behavior; renewal scheduler exercises real quotas |

Test the **logic** of integrations locally with mocks where possible; accept that the **wire** is not testable here.

### Local stack required for SA-Orchestration alignment

| Component | Purpose | Source |
|---|---|---|
| Local WordPress at `wordpress.localhost` | Host the orchestration layer | Choice of XAMPP / Local / Laragon / MAMP / Docker |
| MySQL or MariaDB | WordPress DB | Bundled with the chosen stack |
| PHP 7.4+ (8.1+ preferred) | WordPress runtime | Bundled |
| Fluent Boards (free) | Project tasks; the operational contract surface | WP plugin directory |
| FluentCRM (free) | Contact + audience layer | WP plugin directory |
| Fluent Support (free) | Support tickets; the public-facing curated surface | WP plugin directory |
| SA-Orchestration plugin | Agent layer (Sara, Asterion, Seed Generator, Attention) | Clone from `github.com/SleeperAgents/SA-Orchestration` (verify URL with the human) |
| Asterion canonical corpus | Read-only doctrine source the Asterion Explorer renders | This repo's `asterion/` directory |
| LLM provider credentials | OpenAI / Anthropic / etc. for Sara + Asterion Projection | Human enters via WP admin after activation; **never** transit the LLM with secret values |

### The end state of JNO (acceptance)

You complete JNO when **all of the following are true** and verified in chat to the human:

1. Local WordPress responds at `http://wordpress.localhost`.
2. Fluent Boards admin page renders. At least one test board is reachable.
3. FluentCRM admin page renders.
4. Fluent Support admin page renders. The `wp_fs_*` tables exist at the standard WP prefix (no orphan-prefix issue).
5. SA-Orchestration plugin is installed and active. The `wp_sa_*` tables exist (6 of them: arbitration, arbitration_plan_link, acceptance_event, attention_log, token_log, actor_handoff).
6. Asterion Explorer admin page (`?page=sa-orchestration-asterion`) renders the spec corpus tree from this repo's `asterion/`. The spec_root filter is registered (mu-plugin or wp-config.php constant).
7. Sara identity test passes: a meta-question ("what is your role?") returns the compass, named surfaces, doctrine line.
8. Asterion canonical query passes: "what is Truth Class?" cites `01-ontology.md` and gives the canonical definition.
9. Asterion off-topic test: an off-corpus question returns "no canonical reference found in the spec corpus."
10. Seed Generator produces a seed file with frontmatter `artifact_class: seed` and `accepted_into_asterion: false`.
11. No SA-Core wiring beyond what SA-Orchestration provides. SA-Core remains untouched.

### Constraints (locked)

- Do not deploy to any production host.
- Do not invent credentials.
- Do not copy secrets between environments.
- Do not perform destructive database changes.
- Do not modify the Python app code as part of onboarding (Python work is separate).
- Do not enable SA-Core; SA-Orchestration is the JNO endpoint.
- Do not push to `github.com/SleeperAgents/RcmEmailAutomation` from the local environment without explicit human direction; the seed and onboarding artifacts may be committed when the human approves.
- Do not create canonical Asterion content (writes to `asterion/`); the corpus is read-only from this repo's perspective. If a doctrine question arises, surface it; do not author.

### When in doubt — references

| Need | Read |
|---|---|
| Claude routing for this repo | `CLAUDE.md` (root) |
| Step-by-step JNO setup | `ONBOARDING.md` (root) |
| SA-Orchestration canonical corpus | `asterion/` |
| Doctrine (Story Seed, Compass, Concept-vs-Label, Attention, Lineage) | `asterion/concepts/` |
| Invariants I1–I10 | `asterion/02-invariants.md` |
| Vocabulary | `asterion/01-ontology.md` |
| The truth contract | `asterion/README.md` |

---

*This Asterion seed is non-canonical until accepted. The seed remains an artifact, not a truth. The Description = Contract discipline applies. The compass holds.*