npm package: @lmtlssss/caduceusmail
Description: Portable Microsoft 365 plus Cloudflare mail orchestration framework with skill bundle packaging for agent harnesses like Codex.
Latest version: 3.7.0

# ☤CaduceusMail 3.7.0

CaduceusMail is a portable Microsoft 365 plus Cloudflare mail operations framework built for agent harnesses. It packages the skill bundle, bootstrap tooling, DNS and transport automation, sender identity controls, and verification flows needed to make one mailbox behave like a full control plane.

Version `3.7.0` separates publishable framework code from machine-local identity state. The repo now ships safe generic defaults, while live mailbox branding, personal names, footer data, and domain maps live in a local override file outside git.

## What ships

The repo now includes:

* a root `SKILL.md` bundle that can be installed into agent harnesses
* a generic sender identity rules template
* Microsoft 365 and Cloudflare bootstrap + doctor tooling
* Exchange, Graph, DNS, and DKIM orchestration scripts
* a small npm package wrapper for skill installation and profile scaffolding
* credential templates, examples, docs, and regression tests

## Two surfaces

Use the project in two clean layers:

1. Publishable framework
   The tracked repo, npm package, docs, templates, and skill bundle stay generic and safe to ship publicly.
2. Machine-local operations profile
   Names, domains, footer details, and live mailbox inventory belong in `~/.caduceusmail/sender_identity_rules.local.json` or another file pointed to by `CADUCEUSMAIL_SENDER_IDENTITY_RULES_PATH`.

That split keeps public releases reusable while preserving a tuned live operator profile on a specific machine.

## npm and skill install

Global install:

```bash
npm install -g @lmtlssss/caduceusmail
```

Initialize a local sender identity profile:

```bash
caduceusmail init-profile
```

Install the packaged skill into Codex:

```bash
caduceusmail install-skill --harness codex --force
```

You can also print the installed package root for custom harness wiring:

```bash
caduceusmail skill-path
```

## Local identity customization

The tracked rules file at `scripts/sender_identity_rules.json` is a generic template.

Customize your live sender behavior in:

```text
~/.caduceusmail/sender_identity_rules.local.json
```

The runtime resolves sender identity rules in this order:

1. `CADUCEUSMAIL_SENDER_IDENTITY_RULES_PATH`
2. `~/.caduceusmail/sender_identity_rules.local.json`
3. `~/.config/caduceusmail/sender_identity_rules.local.json`
4. bundled `scripts/sender_identity_rules.json`

That means the public package stays generic while your live machine can keep exact brand maps, reply names, footer blocks, and mailbox inventory.

## Credentials and bootstrap

Copy the credential templates, fill them in locally, then run the wrapper:

```bash
cp credentials/entra.txt.template credentials/entra.txt
cp credentials/cloudflare.txt.template credentials/cloudflare.txt

bash ./scripts/caduceusmail.sh \
  --organization-domain "example.com" \
  --mailbox "ops@example.com" \
  --bootstrap-auth-mode device
```

For headless daily operations after the trust ceremony:

```bash
bash ./scripts/caduceusmail.sh \
  --organization-domain "example.com" \
  --mailbox "ops@example.com" \
  --skip-m365-bootstrap
```

Persistence is opt-in. The wrapper does not write secrets to disk unless you explicitly ask it to.

## Doctor

Use the doctor to check runtime readiness:

```bash
python3 ./scripts/caduceusmail-doctor.py --json
```

Or through the npm bin:

```bash
caduceusmail doctor --json
```

It reports:

* required binaries
* credentials file presence and key coverage
* headless readiness
* skill frontmatter safety
* recommended bootstrap mode for the current host

## Deliverability model

CaduceusMail coordinates four planes together:

1. Entra and Graph identity
2. Exchange transport and accepted domains
3. Cloudflare DNS for MX, SPF, DMARC, and DKIM selectors
4. sender identity + footer rendering through the local profile

New lane verification and send preflight now include DKIM, so subdomains are not treated as ready on MX/SPF/DMARC alone.

## Agent harness notes

The bundle is shaped for skill-based agent runtimes:

* Codex can load the copied skill folder under `~/.codex/skills/caduceusmail`
* OpenClaw can load the root `SKILL.md` directly and inject env through `skills.entries.<skill>.env`
* other harnesses can copy the same packaged bundle to any custom skill path

See:

* `docs/openclaw.md`
* `docs/codex.md`
* `examples/openclaw.config.json5`

## Security

Do not track:

* live credentials
* local sender identity override files
* mailbox inventory snapshots
* generated intel artifacts

The repo intentionally keeps credential templates in git and real secrets out of git.

## Testing

Smoke test:

```bash
bash ./scripts/caduceusmail-sandbox-smoke.sh
```

Full test suite:

```bash
PYTHONPATH=src python3 -m pytest -q
```

npm payload dry run:

```bash
npm pack --dry-run
```

## Publishing

The repo now includes `.github/workflows/npm-publish.yml` for push-driven GitHub-to-npm publishing from `main`. It expects an `NPM_TOKEN` repository secret, runs the test/package checks on each push, and only publishes when the `package.json` version is not already present on npm.

## License

MIT.