# Gmail Inbox Architect — Example Project Roadmap

> **Note:** This is a sanitized example showing the structure and decisions
> produced by a completed Phase 1 + Phase 2 run of the Gmail Inbox Architect plugin.
> Replace bracketed placeholders with your own project values.

**Status:** Phase 1 complete, Phase 2 deployed, Phase 3 planning

---

## What's Done

### Phase 1 — Filter Activation (Complete)
- [N] Gmail filters live across [M] label trees (Support, Finance, Notifications,
  Operations, Vendors, Clients/Resellers, Development, Marketing, Personal, Sales, Travel)
- [N] new Gmail labels created
- Master Tracker tracking all rules: `Tracker.xlsx`

### Phase 2 — Apps Script Attachment Scanner (Complete)
- Deployed: `scanDocumentationAttachments()` — hourly trigger
- Catches `.STP`/`.STEP` files and diagram+PDF combos → applies `Documentation` label
- Guard label `Z-Archive/DocScan` (hidden) prevents re-scanning
- No star/Studio trigger — verification-only in current form

### Cleanup Completed
- ✅ [Example: mark-read enabled for a high-volume noise sender]
- ✅ [Example: legacy label backfilled and deprecated]

---

## Open Backlog

### Immediate / Low Effort

| Item | Notes |
|---|---|
| Delete deprecated legacy label | Label is empty after backfill. Remove when ready. |
| `! Rule Needed` periodic review | Run with architect agent when label accumulates candidates |
| Deferred rule (e.g. seasonal vendor) | Held at `do_not_automate_yet`. Revisit when activity resumes. |

### Apps Script Extensions (Medium Effort)

| Document Type | Detection Pattern | Target Label |
|---|---|---|
| Vendor invoices | `filename: /inv[-_]\d+\.pdf/i` | Finance/Invoices-Vendor-Payable |
| Purchase orders | `filename: /po[-_\s]?\d+\|purchase.order/i` | Finance/Purchase-Orders |
| Signed contracts | `filename: /signed\|executed/i` + PDF | Documentation |
| Shipping manifests | `filename: /manifest\|packing.list/i` | Vendors/Shipping |
| Quotes/proposals | `filename: /quote\|proposal\|rfq/i` + PDF | Sales/Quotes |

### Phase 3 — Real-Time Studio Integration (Future)

| Item | Notes |
|---|---|
| Gmail `watch()` API | Pub/Sub + webhook for near-real-time Apps Script triggering |
| AI processing layer | Route starred/queued messages through Claude for triage |
| Morning brief integration | Pull high-signal classified mail into daily brief |

---

## ! Rule Needed Process

**What it is:** A Gmail label applied manually when an email arrives that should have
an automated rule but doesn't.

**Review cadence:** Ad hoc — run when label accumulates enough candidates.

**Session flow:**
1. Pull all messages in `! Rule Needed`
2. Review senders, subjects, patterns
3. Determine: gmail_filter_safe or apps_script_needed?
4. Draft rules, add to Tracker, deploy
5. Remove `! Rule Needed` label from processed threads

---

## Key Decisions on Record

- **apps_script_needed** = attachment filename inspection only. Multi-domain OR queries
  are gmail_filter_safe — Gmail's query field handles these natively.
- **Studio timing constraint:** Stars applied by Apps Script don't trigger Studio flows.
  Star must come from a Gmail filter at receipt time. Apps Script stars are schedule-driven,
  not receipt-driven.
- **Single-label-per-filter:** Required to avoid Gmail API rate limits on parallel creation.
- **Participant-domain pattern:** `from:(domain.com) OR to:(domain.com) OR cc:(domain.com)`
  — use for business relationships. From-only for inbound-only services (card issuers, SaaS).
- **End-customer domains:** Do not auto-rule domains that appear adjacent to a client without
  confirming the relationship is consistent. Flag with `! Rule Needed` first.