# Client St0r — Roadmap

> Living plan. Phases 1–7 + 9 + 10 + 11 + 31 (Vault Access Rules) complete. Update as phases complete.

## Phasing principle

Foundations first — engines that *enable* downstream features. Then revenue-relevant features. Then ITIL + ecosystem + polish. Each phase is self-contained, ships incrementally via the Apply flow, and unblocks the next.

---

## Phase 1 — Contract / agreement engine deepening **(M · foundation)** [complete]

Mature contract engine — beyond the basics. Required for accurate profitability reporting (Phase 3).

- Per-contract **overage rules** — different rate for billable hours past allowance *(1.1 — shipped v3.17.126)*
- **Role-based inclusion/exclusion** — e.g. "T1 work included, T3 work billable at $X" *(1.1 — shipped v3.17.126)*
- **Prepaid block hours with rollover** — % rollover, expiry dates *(1.1 — shipped v3.17.126)*
- **Auto-renewal** — N days before end_date, auto-create next period via `psa_auto_renew_contracts` cron *(1.2 — shipped v3.17.130)*
- **Proration** — mid-month start/cancel *(1.1 — shipped v3.17.126)*
- **Bundled services** — line items per agreement via `ContractBundleItem` model with dynamic editor *(1.2 — shipped v3.17.130)*
- Agreement **profitability snapshot** — revenue vs. cost-of-delivery this period, surfaced on contract detail page *(1.2 — shipped v3.17.130)*

## Phase 2 — Resource management foundation **(M · foundation)** [complete]

Required by capacity planning, profitability-by-tech, and scheduling improvements.

- `UserSkill`, `UserCertification` models
- `WorkingHours` (per user, per weekday + per-org override)
- `Holiday` / `LeaveRequest` (PTO booking with approval)
- `BillableTarget` (hours/week per tech, used for utilization KPI)
- **Capacity report** — forecast vs. scheduled vs. actual hours per week per tech
- **Skill matching** on the dispatch board — when assigning, surface techs ranked by skill+availability

## Phase 3 — Financial reporting + BI **(L · keystone)** [complete]

Most-requested feature class. Big surface, but builds entirely on Phase 1+2 foundations.

- Canonical reporting query layer (`reports/queries.py`) — single source of truth for revenue, hours, costs *(3.1 — shipped v3.17.139)*
- **Profitability by**: client *(3.1 — shipped v3.17.139)* / contract / project / tech *(3.2 — shipped v3.17.140)* / agreement / ticket-type / closure-category
- **Effective hourly rate** report (revenue ÷ billable hours) *(3.3 — shipped v3.17.141)*
- **Revenue-leakage report** (unbilled time ≥ N days old + expired blocks + un-pushed invoices) *(3.3 — shipped v3.17.141)*
- **SLA trend report** — breach rate per client, per priority, over time *(3.4 — shipped v3.17.143)*
- **Margin analytics** by service line *(3.4 — shipped v3.17.143)*
- **Custom dashboards** — drag-and-drop widgets sourced from the canonical query layer *(3.5 — shipped v3.17.142)*
- **Scheduled reports** — cron-style, email PDF/CSV *(3.6 wave B — shipped v3.17.147)*
- **Wallboard view** — TV-ready big-number display (active tickets, breaches, MTTR, queue depth) *(3.6 wave A — shipped v3.17.146; basic 6-tile fixed layout)*
- **Configurable wallboards with widgets** *(shipped v3.17.211)* — multiple named `Wallboard` rows per org via `reports.Wallboard` + `reports.WallboardWidget`, widgets sourced from the v3.17.142 `widget_sources.REGISTRY`, per-wallboard `refresh_seconds`, per-widget refresh override, "rotate through wallboards" mode at `/reports/wallboards/<pk>/rotate/` using meta-refresh redirects (no JS required — works on any TV browser). Drag-to-reorder UI deferred — admins set the `order` field via the admin interface for now
- **Executive scorecard** — single page rolling 30-day MSP KPIs *(3.6 wave A — shipped v3.17.146)*
- **Client-health score** — composite of SLA hits, ticket velocity, NPS proxy, billing aging *(3.6 wave B — shipped v3.17.147)*

## Phase 4 — Procurement workflow **(L)** **— shipped**

Builds on existing distributor integrations (Ingram/Pax8/Synnex). Adds the workflow above the catalog.

- `PurchaseRequisition` → approval → `PurchaseOrder` *(4.1 — shipped v3.17.148)*
- POs auto-numbered + branded PDF + email-to-vendor (mirror Quote/Invoice pattern) *(4.1 — shipped v3.17.148)*
- **Receiving** — partial receive, back-orders, serial-number capture into Asset records *(4.2 — shipped v3.17.149)*
- **Vendor relationship** model — lead times, payment terms, contact preferences *(4.3 — shipped v3.17.150)*
- **Stock minimums + auto-replenish** suggestion *(4.3 — shipped v3.17.150)*
- **Drop-ship handling** — direct-to-customer flag with shipping address override *(4.1 — shipped v3.17.148)*
- **Fulfillment tracking** — link POs to tickets/projects, status pipeline *(4.1 — shipped v3.17.148)*
- **One-click PO from accepted quote** — converts quote line items to a draft PO *(4.4 — shipped v3.17.151)*

## Phase 5 — CRM / sales pipeline **(L)** **— complete**

A mature PSA covers sales-pipeline-to-invoice. Currently we have quotes; we need everything *before* the quote.

- `Lead`, `Opportunity`, `Campaign`, `Commission` models *(5.1 — shipped v3.17.152; 5.2 — shipped v3.17.153)*
- Lead scoring + conversion funnel report *(5.2 — shipped v3.17.153)*
- Pipeline Kanban view (Discovery → Qualified → Proposal → Closed Won/Lost) *(5.1 — shipped v3.17.152)*
- **Quote-to-project automation** — one click on accepted quote spins a Project with tasks pre-populated from quote line items *(5.1 — opportunity → quote shipped v3.17.152; quote → project shipped v3.17.213)*
- **Configurable wallboards.** Multi-named per-org boards, widget grid sourced from the v3.17.142 widget registry, per-wallboard refresh + per-widget override, NOC-TV rotation mode *(shipped v3.17.211; Chart.js + nav + screenshots v3.17.212; drag-to-reorder widgets v3.17.215; global / cross-tenant overview boards v3.17.216; selectable category dropdown on widgets v3.17.217; categories on tickets/revenue/at-risk sources v3.17.218; in-form widget add/delete + starter templates v3.17.220; 9 new operations / monitoring widget sources + Monitoring template v3.17.224)*
- Sales-activity timeline per org/lead (calls, emails, meetings logged) *(5.3 — shipped v3.17.155)*
- Commission rules engine + per-tech commission report *(5.2 — shipped v3.17.153)*
- Lead capture from web form / IMAP / API *(5.3 — web + API shipped v3.17.155; IMAP poller stubbed, full implementation deferred to 5.4 follow-up)*

## Phase 6 — ITIL maturity **— complete**

Extends existing tickets + approvals; doesn't fork into a separate model layer.

- **Change requests** as a `Ticket.ticket_type='change'` extension with required CAB approval before status moves to "Implementing" *(6.1 — shipped v3.17.158)*
- **CAB workflow** — multi-approver gate (extends existing single-approval) *(6.1 — shipped v3.17.158)*
- **Problem records** — link N related tickets, root-cause analysis field, status pipeline *(6.2 — shipped v3.17.160)*
- **Release management** — group changes into release windows, freeze flags, rollback documentation *(6.3 — shipped v3.17.165)*
- **Service-catalog governance** — approval gate on catalog item changes *(6.3 — shipped v3.17.165)*
- MSP-named sample role templates seeded by `RoleTemplate.get_or_create_system_templates()`: Client, Client Admin, Technician, Tech Manager, Office Manager, Full Admin (in addition to the existing Owner/Administrator/Editor/Help Desk/IT Manager/Documentation Writer/Read-Only) *(shipped v3.17.164)*

## Phase 7 — Outsourcing, integrations, polish **(continuous track)** [complete]

Not a single phase — runs alongside 1-6.

- **Outsourcing**: subcontractor org type, share-ticket-to-partner endpoint with HMAC, two-way sync of comments + status, optional billing markup *(shipped v3.17.166)*
- **Integration SDK**: clean provider plugin interface *(skeleton shipped v3.17.166)*; then steady drops — Datto Backup, ITGlue v2 import, Hudu sync, BackupRadar, ScreenConnect, Acronis, Liongard. Target: 5-10 new providers per quarter.
- **Polish backlog** — test coverage gaps, permission edge cases, audit improvements, mobile UI fixes, onboarding docs, import-tool maturity, API stability, third-party trust signals *(continuous track)*
  - Tenant-isolation security-test suite restored from rotted state; latent `/api/passwords/<id>/` audit-log crash fixed *(shipped v3.17.171)*
  - Removed deprecated `datetime.utcnow()` / `datetime.now()` from core views; bug-report timestamp no longer mislabels server-local time as UTC *(shipped v3.17.173)*
  - Codebase-wide sweep of deprecated datetime calls; fixes tz-naive query bug in audit-log cleanup + expired-session cleanup on non-UTC servers *(shipped v3.17.174)*
  - Auto-apply-gunicorn-fix migration silenced on test runners + fresh dev installs (no longer spams "Fix script exited with code 1" banners) *(shipped v3.17.175)*
  - Defender adapter flagged as a reference stub in label + test-connection message + module docstring so operators don't pick it expecting live alert flow *(shipped v3.17.179)*
  - Silent `except Exception: pass` swallowers in `core/views.py` audit-log fallback + `core/security_views.py` scan handler tightened to log real exceptions; package-scanner JSON endpoints use a `_staff_or_superuser_api` decorator instead of inline checks *(shipped v3.17.180)*
  - Vault password mutation audit logging — `password_edit` + `password_delete` now write per-action AuditLog rows on success and on every failure mode (form validation, EncryptionError); 2 new tests in `vault.tests.PasswordMutationAuditTests` *(shipped v3.17.181)*
  - Phase 9 forms (Auto-Ticket Rule + Vendor Connection) rewritten with proper card-section layout, Bootstrap widget classes, copy-to-clipboard webhook helpers, "ALL must match" semantic hint on rule clauses *(shipped v3.17.182)*
  - UniFi + M365 connection forms rewritten with the same card-section layout (the only other forms using the sloppy generic field-loop pattern; audit confirmed the rest of the integration forms were already clean) *(shipped v3.17.183)*
  - Bare `except:` clauses replaced with `except Exception:` across 24 sites in 12 modules — no more accidental `SystemExit`/`KeyboardInterrupt` swallowing *(shipped v3.17.184)*
  - `core/security_views.py` inline staff-check sweep finished — all 9 endpoints now use `@_staff_or_superuser_view` (HTML) or `@_staff_or_superuser_api` (JSON) decorators; latent silent `except Exception` in `run_python_scan` also logged *(shipped v3.17.185)*
  - Documentation refresh: 8 new screenshots for Phase 9 + integration forms + the roadmap page; README updated with annotated captions; screenshot script extended with the new pages *(shipped v3.17.186)*
  - Baseline test coverage for `imports/` app — 34 tests across org-matcher fuzzy logic, ImportJob lifecycle, rollback flow (matched orgs preserved, created orgs deleted), unique-together constraints on mapping models, CSV preview helper *(shipped v3.17.187)*

  ➡ **Wave 1 closed (v3.17.171 → v3.17.187)** — every item from the original Phase 7 polish survey has been delivered or explicitly deferred (reCAPTCHA needs Google credentials; scheduler email-send is a feature gap not polish; welcome-email on member-add *was* a feature gap, **shipped v3.17.214**). Phase 7 stays `[in progress]` by design (continuous track) — the next wave will be triggered by user-reported issues + the next bug-bash audit.

  ### Wave 2 — going-from-zero baselines (v3.17.192 → ongoing)

  The audit punch-list flagged 16 apps with no test coverage. Wave 2 is a sustained pass through them. Each app gets baseline tests (model behavior, view tenant-isolation, key happy-path flows) — not feature-complete, but enough to surface latent crashes and lock down the contract going forward.

  **The pattern is paying off.** Three of the first six baselines surfaced real production bugs that had been latent for months — usually a wrong kwarg name, a stale field reference, or a `hasattr` check that doesn't catch `None`. Bugs caught:

  - `psa/tests.py` (5,465 lines / 220+ cases) split into 5 topical shards under `psa/tests/` so CI can run them under the 540s timeout. 271 tests across 5 shards, max shard 147s *(shipped v3.17.192)*
  - **`api/` baseline (11 tests across 6 classes)** — caught two real bugs: `AssetViewSet.filterset_fields` and `AssetSerializer.Meta.fields` both referenced `is_active` and `location` columns that don't exist on the Asset model. Every `/api/assets/` list and detail request 500'd. Fixed in same release *(shipped v3.17.193)*
  - **`audit/` baseline (30 tests across 7 classes)** — caught `AuditLoggingMiddleware._is_update()` crashing on POST to unresolved URLs (`hasattr(req, 'resolver_match')` returns True for None values; `None.kwargs` then raised `AttributeError`). Fixed in same release *(shipped v3.17.195)*
  - `assets/` baseline (16 tests across 6 classes) — model behavior, OrganizationManager filtering, view tenant-isolation, EquipmentModel back-reference. No production bugs surfaced *(shipped v3.17.196)*
  - `monitoring/` baseline (22 tests across 5 classes) — WebsiteMonitor + Expiration property logic, IPAM `(subnet, ip_address)` unique-together dedupe contract, `for_organization()` filtering. No production bugs surfaced *(shipped v3.17.197)*
  - `processes/` baseline (19 tests across 4 classes) — workflow engine slug auto-gen, ProcessExecution lifecycle, completion-percentage math (incl. zero-stages safety), `(execution, stage)` unique-together. No production bugs surfaced *(shipped v3.17.199)*
  - `files/` baseline (9 tests across 2 classes) — `attachment_upload_path()` enforces per-org / per-entity directory structure with UUID filenames (filesystem tenant-isolation contract). No production bugs surfaced *(shipped v3.17.200)*
  - `scheduling/` baseline (20 tests across 5 classes) — recurrence math for every cadence, `check_completion` any-of vs all-of sign-off, `spawn_next_occurrence` clones assignments + tags. No production bugs surfaced *(shipped v3.17.201)*
  - `locations/` baseline (20 tests across 3 classes) — HQ-uniqueness invariant, shared-location ACL, `full_address` formatting, WAN bandwidth display. No production bugs surfaced *(shipped v3.17.202)*
  - `docs/` baseline (13 tests across 5 classes) — Document slug auto-gen, version-snapshot lifecycle (no row on first save, increments on edit), Diagram slug, `is_global` cross-tenant KB. No production bugs surfaced *(shipped v3.17.203)*
  - `inventory/` baseline (15 tests across 5 classes) — InventoryItem QR-code auto-gen, low-stock boundary, total_value math, transaction signed-quantity formatting. No production bugs surfaced *(shipped v3.17.204)*
  - `vehicles/` baseline (18 tests across 3 classes) — ServiceVehicle expiry warnings, `has_location` flag, `update_location()` setter, fleet inventory low-stock + needs-restock + total-value. No production bugs surfaced *(shipped v3.17.205)*

  ➡ **Wave 2 closed (v3.17.192 → v3.17.205)** — every one of the 16 originally-untested apps now has baseline coverage. **Final ratio: 3 of 11 baseline efforts surfaced real production bugs that had been latent for months** (api/, audit/, the v3.17.171 tenant-isolation rebuild before the wave formally started). All bugs caught were stale-attribute / wrong-kwarg / hasattr-vs-None patterns — the same family the next wave should look for first.

  Wave 2 totals: ~280 new tests across 11 modules in 14 commits. Combined with the v3.17.192 psa-tests shard split, the project's test runtime now fits comfortably under any reasonable CI ceiling: each shard ≤ 147s, smaller apps ≤ 7s.

  - Installer never installed the background timers — a fresh install had no scheduler, no monitoring and no breach scan, while looking perfectly healthy; `install.sh` now installs all seven with user/path rewriting, enables the operational ones, and leaves `auto-update` and `accounting-sync` off as operator decisions *(shipped v3.17.534)*

  ✅ **Phase 7 marked complete at v3.17.207.** All three pillars have shipped: outsourcing (v3.17.166), Integration SDK skeleton (v3.17.166) + first reference adapter (v3.17.168), and the polish-backlog test-coverage push (Waves 1 + 2). Ongoing polish continues as routine maintenance — bug fixes, deprecation sweeps, new vendor adapters in the SDK — but it's no longer tracked as an active phase. Future polish lands as standalone releases under whatever phase the change applies to (e.g. a vault-side improvement = Phase 31 polish).

## Phase 9 — Security alert ingestion: EDR / AV / Firewall on the dashboard **(M)** [shipped — v3.17.168]

MSPs run a stack of security tools that all alert independently — SentinelOne, CrowdStrike, Defender, Sophos, Bitdefender, Webroot, Fortinet, Palo Alto, Sonicwall, etc. The PSA dashboard should aggregate alerts from all of them, surface critical issues per client, and let techs triage from one screen.

### Sub-phase 9.1 — Connection framework *(shipped v3.17.168)*

- Generic `SecurityVendorConnection` model: provider type (edr/av/firewall), org-scoped credentials (encrypted), poll interval, last_sync_at, last_error
- Provider type enums covering EDR (CrowdStrike Falcon, SentinelOne Singularity, Microsoft Defender for Endpoint, Sophos Central, Huntress, ThreatLocker), AV (Bitdefender GravityZone, Webroot, Malwarebytes, ESET), Firewall (Fortinet FortiGate, Palo Alto, Sonicwall, Cisco Meraki MX, Sophos XG, pfSense)
- Two-way mapping: each connection optionally pinned to a client `Organization` (multi-tenant alert routing)
- Reuses existing integration patterns (status pill from v3.17.135)

### Sub-phase 9.2 — Alert model + poller *(shipped v3.17.168)*

- `SecurityAlert` model: connection FK, external_id (dedupe key), severity (info/low/medium/high/critical), title, description, asset hint, raw_payload (JSON), seen_at, acknowledged_by, acknowledged_at, status (new/acknowledged/dismissed/resolved), auto_ticket FK (optional)
- Per-vendor poller adapters returning normalized alert dicts; one mgmt cmd `poll_security_alerts` runs every 5 min via cron
- Idempotent dedupe by (connection_id, external_id)
- Alert webhook receiver endpoint `/security/webhook/<token>/` for vendors that push (HMAC-verified)

### Sub-phase 9.3 — Dashboard + auto-ticketing *(shipped v3.17.168)*

- New "Security alerts" card on the global dashboard + per-org dashboard: count by severity in the last 24h, drill-down to filtered list, color-coded
- New page `/security/alerts/` — full triage UI; filter by severity / vendor / client / status
- Per-vendor or per-severity rule: auto-create a PSA ticket from an alert (priority mapped from severity, queue configurable, assignee from a default rule). Mirrors workflow rules engine (v3.17.111).
- Bulk "ack / dismiss / convert to ticket" actions

### Sub-phase 9.4 — Reporting *(shipped v3.17.168)*

- "Mean time to acknowledge" metric per client / per vendor
- Suppression rules (don't auto-ticket from this vendor between 22:00–06:00 etc.)
- Weekly digest email to client of unresolved alerts (opt-in) *(deferred — pending email subscription mgmt; framework + MTTA shipped)*

**Sizing:** **M** — 9.1+9.2 = 2 weeks (one reference adapter + the framework), 9.3 = 2 weeks, 9.4 = 1 week. Each new vendor adapter beyond the first is ~2-4 days. Ship the framework + 1-2 reference adapters first, then add vendors as customer demand arrives.

**Dependencies:** none. Can run alongside Phase 2 / 3 / 8.

---

# Long-term roadmap — Phases 10-23

The following are **planned / in-progress** items focused on MSP workflow consolidation and operational visibility. None are positioned as fully implemented. Items overlapping with already-shipped phases are noted as "Extends X" so the deltas are explicit. AI-assisted features are clearly marked **OPTIONAL AI**.

## Phase 10 — Advanced Email-to-Ticket Engine **(M)** [complete]

**Roadmap item:** Advanced Email Processing & Ticket Intelligence. Extends the basic IMAP poller already shipped (v3.17.83+).

Planned capabilities:
- Advanced inbound email parsing (HTML + plain-text fallback) *(10.2 — shipped v3.17.177)*
- Thread reconstruction across replies + forwards *(10.1 — shipped v3.17.176)*
- Reply correlation by Message-ID + In-Reply-To headers (more reliable than current subject-regex match) *(10.1 — shipped v3.17.176)*
- Signature stripping *(10.2 — shipped v3.17.177)*
- Loop detection (ignore auto-responders) *(10.3 — shipped v3.17.188)*
- Spam scoring before ticket creation *(10.3 — shipped v3.17.188)*
- Attachment extraction with MIME-type allowlist *(10.2 — shipped v3.17.177)*
- Automatic contact association (match sender email → existing contact / membership) *(planned — Phase 10.3.1)*
- Per-client parsing rules *(10.3 — shipped v3.17.188 via EmailRoutingRule)*
- Ticket categorization (rule-based) *(10.3 — shipped v3.17.188 via routing rule queue/priority overrides)*
- Ticket tagging
- Email security validation (SPF / DKIM / DMARC inspection) *(10.3 — shipped v3.17.188; opt-in via enforce_dmarc)*
- Outbound threading + per-ticket conversation panel *(10.4 — shipped v3.17.189)*
- Microsoft 365 mailbox source via Graph API (alternative to IMAP for tenants that can't enable IMAP) *(10.5 — shipped v3.17.506 — `EmailIngestionConfig.source='graph'` reuses an existing M365 connection's app registration (needs `Mail.Read`); the poller fetches each unread message's MIME via Graph and runs the identical threading/quarantine/attachment pipeline, then marks it read — issue #142)*
- Microsoft 365 **outbound** via Graph (optional transport; SMTP remains default) *(10.6 — shipped v3.17.507 — `EmailIngestionConfig.outbound_method='graph'` sends staff replies via Graph `sendMail`/`reply`/`replyAll` on the same mailbox (needs `Mail.Send`, scoped via Exchange Online RBAC for Applications). Durable `EmailOutboundJob` with idempotent claim-lock, 202-accepted tracking, Retry-After-aware retries for 429/5xx, fail-fast on auth/validation, and an 'uncertain' state for post-submit timeouts (never auto-resent). Immutable Graph message ids stored on inbound so replies preserve the M365 conversation. Readiness check + labeled test-send in the mailbox form — issue #142)*
- Reply-to-requester from the ticket form *(10.7 — shipped v3.17.508 — an opt-in "Email this reply to …" checkbox on the ticket reply box sends the comment to the requester through whichever transport the originating mailbox is configured for (SMTP or Graph), closing the round trip so outbound replies are captured in the conversation panel and, on Graph, in the mailbox's Sent Items. Off by default; internal notes are never emailed; a send failure reports but never discards the saved comment — issue #142)*
- Ticket summarization (**OPTIONAL AI**)
- Intent detection (**OPTIONAL AI**)

### Sub-phase 10.1 — Threading + Message-ID correlation *(shipped v3.17.176)*

- New `EmailMessage` model captures every inbound (and later, outbound) email's Message-ID, In-Reply-To, References, headers, and bodies. Unique per `(organization, message_id)` so cross-tenant Message-ID collisions never thread incorrectly.
- New `Ticket.last_inbound_message_id` cache feeds outbound threading in 10.4.
- Poller correlation order is now: (a) In-Reply-To against `EmailMessage.message_id` in the same org, (b) walk the References chain right-to-left, (c) subject-regex fallback (legacy tickets keep working), (d) create new ticket. Whichever path matches, the inbound message is persisted as an `EmailMessage` row so the next reply has something to chain against.
- Tests cover header-threading, References-chain walking, subject-regex fallback for legacy replies, cross-org isolation, and new-ticket creation.

### Sub-phase 10.2 — Body cleanup + attachment ingestion *(shipped v3.17.177)*

- New `psa/email_parsing.py` helper module: `sanitize_html` (bleach with tight allowlist; strips scripts, styles, iframes, inline event handlers, remote images / tracking pixels; rewrites links with `rel="noopener noreferrer" target="_blank"`), `strip_signature` (RFC 3676 `\n-- \n` sentinel + mobile/marketing prefaces), `strip_quoted_reply` (Apple/Gmail "On … wrote:", Outlook `-----Original Message-----` / From-Sent-To-Subject block, trailing `>`-prefix block).
- Reply comments to existing tickets get sig + quoted history stripped so only the new content shows. Full original body still preserved on `EmailMessage.body_text` for the Phase 10.4 conversation panel. New tickets keep the full body so context isn't lost.
- Attachment ingestion via `_ingest_attachments`: walks parts for `Content-Disposition: attachment`, validates against `PSA_EMAIL_ATTACHMENT_MIME_ALLOWLIST` (default: images, PDF, text, Office, ZIP) + `PSA_EMAIL_ATTACHMENT_MAX_BYTES` (default 25 MB), writes accepted files as `TicketAttachment` rows linked to the new comment. Rejected files logged at WARNING level. Filenames sanitized.
- Inbound HTML bodies are sanitized at write time before landing on `EmailMessage.body_html`.

### Sub-phase 10.3 — Routing rules + auto-responder & spam gating *(shipped v3.17.188)*

- New `EmailRoutingRule` model with sender-domain glob matching (exact `acme.com`, subdomain `*.acme.com`, full-email `noreply@acme.com`); MSP's generic `help@msp.com` mailbox now fans inbound mail to the right client tenant + queue + priority. First match wins, ordered by `order` (lower fires first).
- Auto-responder detection via `detect_auto_responder()` — `Auto-Submitted`, `X-Autoreply`, `Precedence: bulk/list/junk`, NDR `multipart/report`, plus subject heuristics for "Out of Office" / "Vacation Auto-Reply" / "Undeliverable".
- DMARC verdict gate — opt-in per-config (`enforce_dmarc`); reads upstream MTA's `Authentication-Results` header; no inline crypto / DNS.
- Spam-keyword scorer — opt-in per-config (`spam_keyword_threshold > 0`); conservative pattern list (claim-your-prize, congratulations-winner, nigerian-prince, etc.).
- Quarantined inbound persists with `was_quarantined=True` + reason but NEVER creates a ticket; admins triage via Django admin.
- 16 new tests across 6 classes covering all four gates plus routing rule end-to-end.

### Sub-phase 10.4 — Outbound threading + conversation panel *(shipped v3.17.189)*

- New `psa/email_outbound.py::send_threaded_reply()` helper — generates Message-ID, sets `In-Reply-To` + `References` from `Ticket.last_inbound_message_id`, sends via Django email backend with optional HTML alternative, persists `EmailMessage(direction='out')` row so future replies thread back via 10.1's `_thread_target` (closing the round-trip).
- New per-ticket conversation view at `/psa/t/<ticket_number>/conversation/` — chronological inbound + outbound rows, HTML bodies rendered in `<iframe sandbox="">` (most-restrictive sandbox), quarantined-inbound shown with reason banner, raw headers/body collapse into `<details>`.
- 9 new tests covering threading headers, round-trip closure, HTML alternative, missing recipients, conversation view ACL.

**Goal:** Reduce dispatcher and technician overhead while improving ticket workflow accuracy.

## Phase 11 — Advanced Dispatch & Technician Scheduling **(M)** [complete]

**Roadmap item:** Dispatch Optimization & Technician Coordination. Extends Phase 2 (resourcing) + the dispatch board (v3.17.112) + skill ranking (v3.17.138).

Planned capabilities:
- Drag/drop dispatch board *(shipped — v3.17.112)*
- Technician scheduling *(partial — Phase 2 WorkingHours shipped)*
- Shift management
- PTO conflict awareness *(11.2 — shipped v3.17.208; extends Phase 2.2 LeaveRequest)*
- Calendar conflict detection *(11.2 — shipped v3.17.208)*
- Recurring onsite scheduling *(deferred — handled by `scheduling.ScheduledTask` recurrence; not a separate dispatch surface)*
- Dispatch prioritization (auto-rank queue by SLA + priority) *(11.1 — shipped v3.17.194)*
- SLA-aware dispatching — SLA-burn panel for tickets due ≤ 4h *(11.1 — shipped v3.17.194)*
- Technician utilization metrics *(shipped — Phase 2.3 capacity report)*
- Geo-aware technician routing *(deferred — needs GPS data on User + Ticket which Phase 8 mobile timeclock will provide; revisit then)*
- Travel time estimation *(deferred — pending Phase 8 GPS data)*
- Dispatch heatmaps *(11.3 — shipped v3.17.209)*
- **Home-dashboard Schedule + Tasks panels** — the main dashboard now leads with a 7-day agenda (scheduled tasks + ticket resolution deadlines, grouped by day, empty days omitted) and an open-work Tasks list ordered most-urgent-first with undated items last. Expiring passwords, tracked expirations and SSL certificates are folded into Tasks rather than sitting in their own panel — an expiry is something somebody has to act on. Replaces the "My Recent", "Recent Activity" and "Expiring Soon" panels, which showed what had already happened. Same shapes as the mobile agenda (v3.17.478), so both surfaces agree on what "upcoming" means *(shipped v3.17.524)*

### Sub-phase 11.1 — Dispatch prioritization + SLA-burn panel *(shipped v3.17.194)*

- New `_dispatch_priority_key(ticket)` returns `(priority.sort_order, no_due_flag, due)` — every lane on the dispatch board (overdue, SLA-burn, unassigned-by-day, assigned-tech cells) now sorts most-urgent first.
- New "SLA at risk" panel above the grid: open tickets due in the next 4 hours but not yet overdue, surfaced with a yellow fire icon. Already-overdue stays in the existing red panel — no duplication. Closed tickets excluded.
- 9 new tests across 3 classes covering sort-key contract, panel filtering, and end-to-end lane ordering.

### Sub-phase 11.2 — PTO + calendar conflict awareness *(shipped v3.17.208)*

- New `_dispatch_conflicts(tech, ticket)` helper returns advisory warnings: **PTO conflict** (approved `resourcing.LeaveRequest` covering the ticket's due date) + **calendar overlap** (another open ticket assigned to the same tech with a due date inside a ±2-hour window).
- `/psa/dispatch/assign/` JSON response now carries a `conflict_warnings` array. Advisory, not blocking — dispatchers made an explicit decision; the warning surfaces as a chip for review. AuditLog includes the conflict list so post-hoc trails capture "they assigned despite the warning".
- 9 new tests across 2 classes covering pure-function conflict detection + end-to-end JSON response shape.

### Sub-phase 11.3 — Dispatch heatmap *(shipped v3.17.209)*

- New `/psa/dispatch/heatmap/` — per-tech, per-day open-ticket load over a ±7-day window (15 columns), rendered as a color-intensity grid so dispatchers see lopsided assignments at a glance.
- 5-step intensity scale (0..4) bucketized against the busiest cell in the visible window; today's column has a blue inset border.
- Counts open assigned tickets with due dates in window; tenant-isolated.
- Geo-aware routing + travel-time estimation **deferred** — they need GPS data the Phase 8 mobile timeclock will collect; revisit then.
- 8 new tests in `DispatchHeatmapTests` covering the view, window calculation, what's counted vs filtered, max-count math, and tenant isolation.

✅ **Phase 11 marked complete at v3.17.210.** All three planned sub-phases shipped (11.1 dispatch prioritization + SLA-burn, 11.2 PTO + calendar conflict awareness, 11.3 heatmap). 27 dispatch tests across the three sub-phases. Two listed capabilities — geo-aware technician routing and travel time estimation — were deferred to Phase 8 because they depend on GPS data the mobile timeclock will collect; revisit them in that phase rather than blocking Phase 11 closure on infrastructure that doesn't exist yet.

**Goal:** Improve technician coordination and service workflow efficiency.

## Phase 12 — Customer Communication Workflows **(M)** [complete]

**Roadmap item:** Enhanced Client Communication & Portal Workflows. Extends the existing customer portal.

Planned capabilities:
- Customer satisfaction (CSAT) surveys post-ticket-close *(shipped v3.17.231 — token-based 1-5 star rating + optional comment, gated by `psa_csat_enabled` SystemSetting flag)*
- Branded client portals *(extends Phase v3.17.112 per-org branding)* *(shipped v3.17.233 — `Organization.portal_primary_color` consumed by portal `base.html` overriding `--bs-primary` + button/link CSS)*
- Portal announcements *(shipped v3.17.232 — per-org banners on the portal home with severity, expiry, dismissable flag + per-session dismissal endpoint; managed via Django admin in v1)*
- Customer approval workflows *(shipped v3.17.239 — `PSAApproval.is_client_approval` flag + `/portal/approvals/` list + decide endpoint; staff route an approval to the client side and the portal user can Approve / Deny with an optional comment)*
- Threaded customer communication *(shipped v3.17.237 — `TicketComment.parent_comment` self-FK + portal "Reply to this comment" button + indented thread render)*
- SMS ticket communication (using existing SMS provider plumbing) *(shipped v3.17.238 — opt-in `portal_notify_sms_status_change` flag + `notify_portal_status_change` helper hooked into the status-change signal; phone field on portal preferences page)*
- Customer escalation workflows *(shipped v3.17.236 — `Ticket.escalated_at/by/reason` fields + portal endpoint that stamps fields and creates a `[Escalated by client]` public comment)*
- Customer-facing knowledge base *(`Document.is_client_visible` shipped earlier; portal KB search shipped; featured + view counts shipped v3.17.234)*
- Customer ticket voting / prioritization *(shipped v3.17.235 — `psa.TicketVote` model + portal toggle endpoint + thumbs-up button on ticket detail)*
- Secure customer messaging *(deferred — would need an encrypted message-thread model + key management distinct from the existing AES-GCM vault; substantial scope and lower priority than other planned phases. Re-evaluated when there's customer demand)*
- Customer notification preferences *(shipped v3.17.233 — three opt-in/out switches at `/portal/preferences/` for ticket replies, status changes, CSAT survey invitations; CSAT helper now honors the flag)*

**Goal:** Improve client interaction visibility and communication consistency.

## Phase 13 — Procurement & Lifecycle Management **(M)** [shipped — v3.17.272]

**Roadmap item:** Advanced Procurement & Asset Lifecycle Management. Extends Phase 4 (Procurement) + the asset lifespan tracking already shipped.

Planned capabilities:
- Serial lifecycle tracking *(partial — serial capture shipped v3.17.149)*
- Warranty expiration tracking *(shipped v3.17.254 — `assets_warranty_alerts` management command emails per-org digests with 7-day per-asset cooldown; configurable warning window via `--days N`)*
- Vendor inventory checks (live stock from distributor APIs) *(shipped v3.17.272 — `/integrations/distributors/stock-check/` fans out `?sku=` to every active DistributorConnection's `check_stock()` + `get_pricing()` so a buyer can compare live qty + unit price across Ingram / Pax8 / SYNNEX in one shot)*
- Procurement approval workflows *(shipped — Phase 4.1 PR/PO)*
- Purchase receiving workflows *(shipped — Phase 4.2)*
- Margin analytics on resold hardware *(shipped v3.17.271 — `/reports/hardware-margin/` joins POs and Invoices by `source_quote_id` to compute resale margin = revenue − cost; per-quote rows + blended summary; CSV export; staff-only)*
- RMA tracking (return / replace lifecycle) *(shipped v3.17.261 — `RMAReturn` model with explicit state machine: open → sent → received_by_vendor → replaced/refunded/closed; views at `/assets/rma/`; tenant-scoped)*
- Asset lifecycle scoring (composite age × usage × warranty) *(shipped v3.17.263 — `Asset.lifecycle_score()` returns 0-100 breakdown {age, warranty, firmware}; report at `/reports/asset-lifecycle/` with `?threshold=` filter and CSV export)*
- Procurement forecasting from historical PR/PO data *(shipped v3.17.268 — `/reports/procurement-forecasting/` projects per-vendor spend over the next 3 months using a 3-month moving average over the last 12 months of committed POs; CSV export; staff-only)*
- Recurring purchasing templates *(shipped v3.17.266 — `RecurringPurchaseTemplate` with JSON line snapshot + recurrence (weekly/biweekly/monthly/quarterly/yearly); `spawn_pr()` creates a draft PR; daily `psa_run_recurring_purchases` cron with catch-up cap)*
- Vendor cost history (price-at-time-of-PO trend) *(shipped v3.17.262 — `/reports/vendor-cost-history/` aggregates POLine items over last 730 days per `(vendor, sku, description)` with min/avg/max/last unit price; CSV export; staff-only)*
- Procurement reporting *(shipped v3.17.258 — `/reports/procurement-summary/` per-vendor + per-month spend over last 365 days; CSV export; staff-only)*

**Goal:** Improve operational procurement visibility and hardware lifecycle management.
- Spreadsheet import for Shop + VAN inventory *(shipped v3.17.523 — the CSV import pipeline now reads .xlsx as well as .csv, and gains `shop_inventory` / `vehicle_inventory` targets so stock levels can be loaded from a spreadsheet with the existing column-mapping, preview and rollback machinery. Vehicles match on name, licence plate or VIN; an unmatched van skips the row with a log line naming the value, rather than failing the batch. Legacy .xls is refused with a re-save instruction instead of a silent half-parse)*

## Phase 14 — Visual Workflow Automation Engine **(L)** [shipped — v3.17.290]

**Roadmap item:** Visual Workflow & Operational Automation Engine. Extends the workflow rules engine (v3.17.111) + visual rule builder (v3.17.112).

Planned capabilities:
- Visual workflow builder *(partial — visual rule builder shipped v3.17.112)*
- Conditional workflow routing (branching based on ticket fields) *(shipped v3.17.285 — `WorkflowRule.else_actions` JSONField runs when `conditions` evaluate false; engine picks branch and counts both as fires)*
- SLA-driven automation *(shipped v3.17.286 — `sla_threshold_crossed` trigger + `sla_pct_at_least` condition + `WorkflowRule.fire_once_per_ticket` guard via `WorkflowRuleFiring` join table; `psa_sla_workflow_tick` cron evaluates open tickets every 5 min)*
- Ticket orchestration (multi-step automated sequences) *(shipped v3.17.285 — new `fire_rule` action type chains by name within the same org / MSP-wide scope; sub-rule's else_actions also honored)*
- Approval chains (extends Phase 6.1 CAB pattern)
- Trigger / action workflows
- Escalation logic (auto-escalate after N hours unanswered)
- Scheduled automations
- State-based workflows *(shipped — already covered by `status_changed` trigger + `status` condition; v3.17.289 confirmation)*
- Dynamic technician assignment (round-robin, skill-match, load-balanced) *(shipped v3.17.287 — 3 new action types: `assign_round_robin` (oldest-assigned wins), `assign_skill_match` (Django Group lookup, load-tiebreak), `assign_load_balanced` (lowest open-ticket count); all skip inactive users)*
- Workflow templates *(shipped v3.17.288 — `WorkflowRuleTemplate` model + `instantiate(organization, name_override)` clone method; UI at `/psa/rules/templates/` with per-template "Use Template" button)*
- Cross-module workflow integration (PSA ↔ procurement ↔ CRM) *(shipped v3.17.289 — `create_charge` action type lets workflow rules add billing rows; future actions for procurement/CRM cross-module land as the need arises)*
- AI-assisted workflow suggestions (**OPTIONAL AI**) *(shipped v3.17.290 — `WorkflowSuggestion` model + `psa_generate_workflow_suggestions` heuristic command (LLM-swap-in later) gated by `psa_ai_enabled`; review/accept/dismiss UI at `/psa/rules/suggestions/`)*

**Goal:** Reduce repetitive operational tasks while improving workflow consistency.

## Phase 15 — Recurring Billing & Contract Management **(M)** [shipped — v3.17.299]

**Roadmap item:** Recurring Billing & Financial Workflow Automation. Extends Phase 1 (contract engine) + invoicing.

Planned capabilities:
- Recurring invoices (auto-generated from contract bundles) *(shipped v3.17.291 — `Contract.billing_frequency` (monthly/quarterly/yearly) + `next_billing_date` + `recurring_amount`; `Contract.generate_invoice()` method; daily `psa_generate_recurring_invoices` cron with catch-up cap + dry-run)*
- Usage-based billing (per-seat / per-device / per-GB metered) *(shipped v3.17.292 — `ContractMeter` model with unit/unit_price/current_quantity + atomic `increment()` helper; `Contract.generate_invoice()` adds one line item per active meter alongside the base recurring amount; meter resets to 0 after billing)*
- Contract renewals *(shipped v3.17.299 — Phase 1.2 auto-renewal cron + Phase 15 v13 pause/resume/cancel-at-period-end complete the lifecycle picture)*
- Proration handling *(shipped v3.17.293 — `Contract._proration_factor()` method computes days-active fraction; `generate_invoice()` applies it to the base amount only (usage line items not prorated); description suffix shows the proration % to the customer)*
- Service bundles *(shipped — Phase 1.2 ContractBundleItem)*
- Billing reconciliation *(shipped v3.17.295 — `/reports/billing-reconciliation/` per-client invoiced-vs-paid over `?days=N` window with collection % coloring; CSV export; tenant-scoped)*
- Late fee automation *(shipped v3.17.294 — `SystemSetting.late_fee_pct` + `late_fee_min_days_overdue`; daily `psa_apply_late_fees` cron creates a `Charge` row for each overdue invoice; idempotent)*
- ACH / payment integrations (Stripe ACH, GoCardless, etc.) *(shipped v3.17.296 — `PaymentConnection` model + `BasePaymentProvider` interface + Stripe & GoCardless adapter stubs; live `charge()` implementation lands when an MSP connects a real account)*
- MRR forecasting *(shipped v3.17.295 — `/reports/mrr-forecast/` reads active recurring contracts; normalizes monthly/quarterly/yearly to monthly equivalents; per-contract table + 12-month projection; staff-only)*
- Contract profitability tracking *(shipped v3.17.299 — Phase 3 profitability-by-contract analytics + Phase 15 v9 MRR forecasting cover both revenue and cost sides)*
- Invoice automation *(shipped v3.17.299 — `SystemSetting.psa_auto_push_recurring_invoices` toggles auto-push of recurring-cron-generated invoices to the configured `AccountingConnection`; failures captured for review on the existing accounting reconciliation report)*
- Tax handling support (Avalara / TaxJar integrations) *(shipped v3.17.297 — `TaxConnection` model + `BaseTaxProvider` interface + Avalara & TaxJar adapter stubs; live `compute_tax()` lands when an MSP connects a real account)*
- Subscription lifecycle management *(shipped v3.17.298 — `Contract.paused_at` / `paused_until` / `cancel_at_period_end` fields + `pause()` / `resume()` / `cancel_at_end_of_period()` methods; daily `psa_advance_subscription_lifecycle` cron auto-resumes + cancels)*

**Goal:** Improve recurring service management and operational billing visibility.

## Phase 16 — Documentation Relationship Mapping **(M)** [shipped — v3.17.303]

**Roadmap item:** Infrastructure Relationship Mapping & Dependency Visualization.

Planned capabilities:
- Asset relationship mapping (parent / child / depends-on) *(shipped — `assets.Relationship` model with parent/child/depends/related/documents choices; v3.17.300 confirmation)*
- Visual dependency graphs (DAG renders) *(shipped — `relationship_map` view emits nodes + edges; v3.17.300 confirmation)*
- Topology visualization *(shipped v3.17.303 — `/assets/relationships/topology.json` returns full org graph as nodes + edges; consumable by Cytoscape / vis-network / D3)*
- Nested organization mapping (extends Phase 17 multi-location) *(shipped — Phase 18 v1, v3.17.240)*
- Shared infrastructure relationships *(shipped — Phase 18 v3, v3.17.252 — `Asset.is_shared_with_descendants` + `visible_to_org()`)*
- Automatic asset linking (heuristic — same subnet, same rack, etc.) *(shipped v3.17.301 — `assets_auto_link` management command buckets by /24 subnet; creates pairwise `related` among peers + `depends` toward a single gateway when one is detected; idempotent; `--dry-run` + `--organization=<slug>` flags)*
- Infrastructure dependency chains *(shipped v3.17.300 — `Asset.dependency_chain(direction='downstream'|'upstream', max_depth=10)` BFS walker; cycle-safe)*
- Rack relationship visualization *(shipped v3.17.303 — racks already shipped; topology JSON includes rack-type assets and their relationships)*
- Service relationship tracking ("Email service depends on Exchange Online + DNS X + Connector Y") *(shipped v3.17.302 — `assets.Service` model with status (operational/degraded/down/maintenance) + criticality + owner; `set_status()` stamps last_status_change; `asset_dependencies()` walks `Relationship(source_type='service')` rows)*
- Documentation inheritance (child sites inherit parent SOPs) *(shipped — `OrganizationManager.for_organization()` walks the parent chain so child orgs see parent KB articles / docs / contacts; v3.17.303 confirmation)*

**Goal:** Improve infrastructure visibility and operational context awareness.

## Phase 17 — Advanced Asset Intelligence **(L)** [shipped — v3.17.310]

**Roadmap item:** Asset Intelligence & Infrastructure Visibility.

Planned capabilities:
- Asset drift detection (compare current state vs. last-known baseline) *(shipped v3.17.304 — `Asset.detect_drift()` field-by-field comparison vs. latest `AssetBaseline`; returns list of `{field, baseline, current}` dicts)*
- Baseline comparison *(shipped v3.17.304 — `AssetBaseline` model with JSONField snapshot + `Asset.capture_baseline()` method; `is_current` flag tracks the active baseline; old ones kept for history)*
- Software compliance auditing *(shipped v3.17.305 — `SoftwarePolicy` model with deny/require actions + severity; `/reports/software-compliance/` joins policies against `RMMSoftware` inventory and surfaces deny violations + require gaps)*
- Hardware lifecycle scoring (composite — see Phase 13) *(shipped — Phase 13 v6, v3.17.263 — `Asset.lifecycle_score()` 0-100 composite)*
- Warranty lookups (vendor API integrations) *(shipped v3.17.309 — `WarrantyConnection` model + `BaseWarrantyProvider` interface + Dell / HPE / Lenovo adapter stubs; live `lookup_warranty()` lands when an MSP connects a real account)*
- Patch correlation (this CVE matches these N assets) *(shipped v3.17.306 — `Vulnerability` model with cve_id + cvss_score + affected_pattern; `affected_assets()` walks `RMMSoftware → RMMDevice → Asset` (by name) to surface affected endpoints)*
- Smart asset grouping (auto-cohort by role/version/location) *(shipped v3.17.307 — `AssetGroup` model with JSON criteria + computed `members()`; supports `asset_type` / `manufacturer__icontains` / `model__icontains` / `os_version__icontains` / `tags__contains`)*
- Vulnerability-to-ticket linking *(shipped v3.17.307 — `Vulnerability.create_remediation_ticket()` spawns a PSA Ticket with severity-mapped priority (critical→P1) and an affected-asset list)*
- Configuration monitoring *(shipped v3.17.308 — `Asset.config_monitored` flag drives the daily `assets_capture_baselines` cron that snapshots into `AssetBaseline`; old baselines retained for history)*
- Operational health scoring per asset *(shipped v3.17.308 — `Asset.health_score()` composite 0-100; deductions for drift (-25), vulnerabilities (-10/-5/-2 by severity, cap -40), lifecycle (cap -50), firmware update (-10); returns factor breakdown for UI)*
- Automated remediation suggestions (**OPTIONAL AI**) *(shipped v3.17.310 — `RemediationSuggestion` model + `assets_generate_remediation_suggestions` heuristic command (LLM-swap-in later) gated by `psa_ai_enabled`; 4 heuristics: firmware update / drift / health regression / CVE match; review/accept/dismiss flow)*

**Goal:** Improve infrastructure awareness and proactive operational management.

## Phase 18 — Multi-Location Client Hierarchy **(M)** [shipped — v3.17.283]

**Roadmap item:** Advanced Multi-Location Organization Management.

Planned capabilities:
- Parent / child organizations (`Organization.parent` self-FK) *(shipped v3.17.240)*
- Multi-site hierarchy *(shipped v3.17.240 — `Organization.ancestors` property + breadcrumb labels)*
- Shared infrastructure inheritance *(shipped v3.17.252 — `Asset.is_shared_with_descendants` flag + `Asset.visible_to_org()` classmethod that unions own/descendants/shared-from-ancestors; `core.utils.ancestor_org_ids` helper added)*
- Location-specific documentation *(shipped — KnowledgeBase articles already scope per organization via Phase 18 v1 parent/child support; v3.17.282 confirmation)*
- Location-level contacts *(shipped — `assets.Contact` rows already scope per organization via Phase 18 v1 parent/child support; v3.17.282 confirmation)*
- Site-level SLA assignment (override parent SLA) *(shipped v3.17.282 — `Organization.sla_overrides` JSONField + `sla_override_for(priority_code)` method that walks up the parent chain)*
- Site filtering on every list page *(shipped v3.17.240 — `OrganizationManager.for_organization` walks parent chain via `core.utils.descendant_org_ids` helper, parent queries see all descendants automatically)*
- Shared services mapping *(shipped v3.17.283 — `/reports/multi-location/` "Shared services" section lists every `Asset.is_shared_with_descendants=True` row + the descendant orgs that see it)*
- Regional operational views (group sites by region) *(shipped v3.17.283 — `/reports/multi-location/` "By region" section groups orgs by `normalized_region`)*
- Multi-location reporting *(shipped v3.17.283 — `/reports/multi-location/` per-parent rollup: tree size, open ticket count, AR balance, asset count across the full descendant tree)*

**Goal:** Improve management of larger MSP client environments.

## Phase 19 — Advanced Reporting & Analytics **(continuous)** [shipped — v3.17.326]

**Roadmap item:** Operational Analytics & Business Intelligence. Extends Phase 3 (Financial Reporting + BI) — these are the next-tier analytics on top of the canonical query layer.

Planned capabilities:
- Technician utilization reporting *(shipped — Phase 2.3 + 3.2)*
- SLA forecasting (predict breach risk before it happens) *(shipped v3.17.320 — `/reports/sla-forecast/` ranks open tickets by % SLA window elapsed; ok/at_risk/critical/breached bands; CSV export)*
- Ticket aging analytics *(shipped v3.17.257 — `/reports/ticket-aging/` 5-bucket breakdown + per-priority matrix + 7+ day aged-table + CSV export)*
- Contract profitability *(shipped — Phase 3.2)*
- Quote conversion tracking *(shipped v3.17.321 — `/reports/quote-conversion/` per-creator quote → accepted → invoiced funnel; configurable rolling window via `?days=`; CSV export)*
- Customer health scoring *(shipped — Phase 3.6B)*
- Executive dashboards *(shipped — Phase 3.6A scorecard)*
- KPI dashboards *(shipped v3.17.322 — `/reports/kpi/` live widget grid: open tickets, mean age, weekly closed, 30d SLA breaches, MRR/ARR; tenant-scoped; CSV export)*
- Operational metrics *(shipped v3.17.323 — `/reports/operational-metrics/` mean time to first response + mean time to resolution + first-touch resolution % + queue depth + age distribution; tenant-scoped; CSV export)*
- Workflow performance analytics *(shipped v3.17.324 — `/reports/workflow-performance/` per-rule fire-count + last-error roll-up; by-trigger distribution; errored rules floated; staff-only; CSV export)*
- Trend analysis *(shipped v3.17.325 — `/reports/trends/` 12-month time series of tickets opened/resolved + MRR added; staff-only; CSV export)*
- Capacity forecasting *(shipped v3.17.325 — same `/reports/trends/` page surfaces per-tech open-tickets vs `BillableTarget` target_hours_per_week; over-target rows highlighted)*
- Reporting exports (already CSV; add PDF + scheduled email) *(shipped v3.17.326 — `?format=pdf` on procurement_summary, ar_aging, mrr_forecast, kpi dashboard via `reports.pdf_export.render_pdf` ReportLab helper; `ScheduledReport` model + `psa_send_scheduled_reports` cron already shipped earlier — confirmed end-to-end)*

**Goal:** Provide MSP operational visibility and business insight.

## Phase 20 — Approval & Change Management Workflows **(M)** [shipped — v3.17.277]

**Roadmap item:** Approval Routing & Change Management. Extends Phase 6.1 (CAB) + the existing approvals queue.

Planned capabilities:
- Multi-stage approvals (sequential gates: tech lead → manager → CAB) *(shipped v3.17.265 — `PSAApproval.parent_approval` self-FK + `stage_index` + `blocked` status; `PSAApproval.create_chain()` factory; approve cascades to next blocked stage; deny cancels downstream)*
- Change advisory workflows *(shipped — Phase 6.1 CAB)*
- Quote approval routing (gate quotes above threshold) *(shipped v3.17.270 — `Quote.send_for_approval()` wraps `PSAApproval.create_chain`; default routing creates a 2-stage chain when total ≥ threshold else single-stage; idempotent against open chains; POST view at `/psa/quotes/<pk>/send-for-approval/` with modal UI on quote detail)*
- Financial approval chains (POs / invoices over $X) *(shipped v3.17.259 — `SystemSetting.invoice_approval_threshold_total` + `invoice_approval_overage_pct` auto-flag invoices via post_save signal; uses existing `Invoice.flag_for_approval` machinery)*
- Escalation approvals (auto-escalate idle approvals) *(shipped v3.17.256 — `psa_escalate_idle_approvals` management command + per-row `escalation_threshold_hours` + `escalated_at` dedupe; emails superusers a single digest)*
- Conditional approvals (rules: "if value > $5k, route to owner") *(shipped v3.17.273 — `SystemSetting.quote_approval_threshold_total` drives a post_save signal that auto-creates a 2-stage approval chain when total ≥ threshold; only fires on draft/sent statuses; idempotent against open chains)*
- Approval audit trails *(shipped v3.17.274 — `PSAApproval.decide()` and `create_chain()` now write to `audit.AuditLog` automatically; cascade transitions (auto-unblock, auto-cancel-on-deny) are logged too; per-approval history viewer at `/psa/approvals/<pk>/history/`)*
- Workflow enforcement *(shipped v3.17.275 — `Quote.has_open_approvals` property + `Quote.mark_accepted()` raises ValueError when any chain stage is pending/blocked; matches the existing Invoice push gate)*
- Change tracking *(shipped v3.17.276 — `ChangeRequestTransition` table records every implementation_status transition; `ChangeRequest.transition_status()` method auto-stamps timestamps + writes attribution; pre/post_save signals capture direct edits too)*
- Operational sign-off workflows *(shipped v3.17.277 — `Ticket.sign_off()` method + `signed_off_at`/`signed_off_by`/`signoff_note` fields; `TicketStatus.requires_signoff` flag drives a pre_save guard that raises ValidationError on attempted transition without sign-off)*

**Goal:** Improve workflow accountability and operational governance.

## Phase 21 — Advanced Mobile Technician Workflows **(L)** [shipped — v3.17.318]

**Roadmap item:** Mobile Technician Workflow Expansion. Extends Phase 8 (mobile apps + GPS auto-time + Timeclock).

Planned capabilities:
- Offline workflow support (work without connectivity, sync on reconnect) *(shipped — `static/service-worker.js` pre-caches static assets, network-first on navigation with cached fallback when offline; v3.17.318 confirmation)*
- Camera uploads (photo upload from the phone, attached to the ticket) *(shipped — `psa.TicketAttachment` model + existing upload endpoint accept image MIMEs; PWA uses HTML5 `<input capture="environment">`; v3.17.317 confirmation)*
- Barcode scanning *(shipped v3.17.318 — extends Phase 8 vehicle inventory QR; PWA `BarcodeDetector` API → `/api/assets/?search=...` which now matches `mac_address` / `ip_address` too)*
- QR scanning *(shipped v3.17.318 — same scan-and-search path as barcode)*
- NFC scanning *(shipped — Web NFC API client-side reads NDEF record, calls `/api/assets/?search=...`; v3.17.318 confirmation)*
- GPS time tracking *(shipped v3.17.315 — `TicketTimeEntry.start_lat/lng` + `end_lat/lng` Decimal fields captured by the PWA at timer start/stop)*
- Technician signatures (canvas signature pad on completion) *(shipped v3.17.312 — `TicketSignature` model one-to-one with Ticket; base64 PNG data-URI storage + geo capture)*
- Onsite checklist enforcement (must complete X before close) *(shipped v3.17.312 — `TicketChecklistItem` model + `Ticket.has_outstanding_checklist` property + sign-off-required transitions blocked while required items are incomplete)*
- Push notifications *(shipped v3.17.313 — `WebPushSubscription` model with per-user/endpoint uniqueness + `send()` helper; live VAPID-signed delivery via pywebpush when `WEBPUSH_VAPID_PUBLIC_KEY` / `WEBPUSH_VAPID_PRIVATE_KEY` are configured)*
- Voice-to-ticket workflows *(shipped v3.17.315 — `TicketComment.source='voice'` + `voice_meta` JSONField for confidence/language/duration; PWA Web Speech API → existing comment-create endpoint, no new server endpoint needed)*
- Mobile dispatch routing (turn-by-turn from current GPS to next ticket) *(shipped v3.17.317 — `/psa/t/<ticket_number>/route-urls/` returns Google / Apple / Waze deep-link URLs as JSON; PWA picks the right one based on platform)*
- Mobile asset lookup *(shipped — existing `/api/assets/` REST endpoint; v3.17.317 confirmation)*
- **Site check-in / check-out (Field Mode)** — explicit "I have arrived" / "I have left" buttons against the active ticket, separate from the generic Timeclock — gives per-ticket onsite-duration evidence for billing *(shipped v3.17.311 — `SiteVisit` model with arrival/departure lat+lng; `check_out()` stamps closeout + computes `duration_minutes`)*
- **Mileage and trip logging** — auto-distance from previous geofence to current geofence, plus manual override; rolls up into per-tech / per-org mileage reports *(shipped v3.17.311 — `MileageLog` model with `is_auto` flag + start/end coords + `MileageLog.haversine_miles()` static helper for great-circle distance)*
- **Quick asset edit from phone** — beyond lookup, lets a tech update serial / location / notes inline without leaving the ticket *(shipped — existing PATCH on `/api/assets/<pk>/`; PWA calls the same REST endpoint as desktop; v3.17.317 confirmation)*

**Goal:** Improve field technician workflow efficiency and mobility.

## Phase 22 — Knowledge Base & SOP Management **(M)** [complete]

**Roadmap item:** Knowledge Base & Operational Documentation Expansion. Extends Phase v3.17.128 (KB tree) + v3.17.134 (KB perms).

Planned capabilities:
- Knowledge base versioning (history of edits, rollback) *(shipped earlier — `DocumentVersion`)*
- Article approvals (review-before-publish gate) *(shipped v3.17.250 — `/docs/approval-queue/` + approve / reject / submit-for-review endpoints; rejection notes appended to article body for inline feedback)*
- Article ownership *(shipped v3.17.245 — `Document.owner` FK defaults to `created_by`)*
- SOP workflows (links the KB to step-by-step Process executions)
- Review reminders (article hasn't been reviewed in 90 days → email owner) *(shipped v3.17.245 — `kb_review_reminders` management command + `Document.review_interval_days` / `last_reviewed_at` / `is_review_overdue` + `/docs/review-queue/` view + `mark-reviewed` endpoint)*
- Internal / external KB separation *(partial — `is_client_visible` shipped)*
- KB analytics (most-viewed, least-viewed, dead links) *(partial — `Document.portal_view_count` shipped v3.17.234)*
- Public knowledge publishing (selected articles → public URL)
- Documentation lifecycle management (draft → published → archived) *(model fields shipped v3.17.245 — `is_draft`, `published_at`; full pipeline is v2)*
- Linked SOP automation (KB article triggers a workflow run)
- Import DOCX/PDF as editable documents + AI review (**OPTIONAL AI**) *(shipped v3.17.503 — `/docs/import/` bulk-extracts Word/PDF/TXT/Markdown text into editable KB documents; optional per-document AI reformat-to-standard + gap analysis via `review_imported_document`, gated by `psa_ai_enabled`. DOCX parsed dependency-free; PDF via PyMuPDF — issue #140)*
- Document export — Markdown / print-ready HTML / DOCX / PDF, single article or bulk ZIP *(shipped v3.17.510 — `Export` menu on every KB article and Global KB article writes Markdown, a standalone print-optimised HTML page, a real Word .docx (built dependency-free straight into the OOXML package, with Word styles, bullet/number lists, tables and live hyperlinks) or a letter-size PDF; `Export All` on the document list bundles everything the current category / tag / search filters select into one ZIP with an `index.md` table of contents, for handing a departing client their whole documentation set. Exported HTML and the article page itself carry an `@media print` block that strips background images, shadows and app chrome so a printed copy is legible. v3.17.511 drops decorative chrome — floating code-block language badges, print-hidden and screen-reader-only elements — that would otherwise flatten into stray one-word paragraphs in a linear export — issue #144)*

**Goal:** Improve operational knowledge management and documentation governance.

## Phase 23 — Security Event & Incident Workflows **(L)** [shipped — v3.17.363]

**Roadmap item:** Security Event Correlation & Incident Operations. Extends Phase 9 (security alert ingestion) — these are the next-tier incident workflows on top of the basic alert dashboard.

Planned capabilities:
- Security event ingestion *(shipped v3.17.168 via Phase 9.1+9.2 — SecurityVendorConnection + SecurityAlert + pollers + webhook)*
- SIEM integrations *(shipped v3.17.337 — generic CEF/JSON/Syslog inbound endpoint with HMAC auth at /security/siem/webhook/)*
- Vulnerability correlation (CVE → affected assets → exposure) *(shipped v3.17.306–307 via Phase 17 v6+v8 — Vulnerability + affected_assets + ticket linking)*
- CVE-to-ticket workflows *(shipped v3.17.307 via Phase 17 v8 — vuln-to-ticket linking)*
- Security incident timelines *(shipped v3.17.338 — SecurityIncident + SecurityIncidentEvent + auto-correlation by asset+severity window + `/security/incidents/`)*
- Exposure scoring *(shipped v3.17.339 — Organization.exposure_score cached + `recompute_exposure_scores` mgmt cmd + org-detail badge)*
- Incident SLA tracking *(shipped v3.17.355 — SecurityIncidentSLAPolicy + `check_incident_sla_breaches` mgmt cmd + idempotent timeline events)*
- Automated remediation workflows *(shipped v3.17.358 — RemediationPlaybook + RemediationPlaybookStep engine; auto-fires on incident open; step types create_ticket / send_email / quarantine_asset_flag / run_workflow_rule)*
- Security dashboarding *(shipped v3.17.168 via Phase 9.3 — `/security/alerts/`)*
- Threat visibility *(shipped v3.17.361 — `/security/threat-overview/` single-pane dashboard with severity rollups, top-exposed orgs, playbook activity, week-over-week trend)*
- Security event reporting *(shipped v3.17.168 via Phase 9.4 — MTTA + suppression + digest framework)*
- AI-assisted incident summarization (**OPTIONAL AI**) *(shipped v3.17.362 — gated by `psa_ai_enabled`; pluggable provider; POST `/security/incidents/<id>/ai-summarize/` writes summary as timeline note)*

Potential integrations:
- Huntress
- SentinelOne
- CrowdStrike
- Microsoft security ecosystem (Defender, Sentinel)
- Sophos
- Other security platforms

**Goal:** Improve operational security visibility and incident response workflows.

## Phase 25 — Mature Timesheet Approval Workflows **(M)** [complete]

**Roadmap item:** Formal time-entry approval pipeline. Today `psa.TicketTimeEntry` is logged ad-hoc by techs; there's no formal weekly approval before billing.

Planned capabilities:
- Weekly timesheet model — groups a tech's TicketTimeEntry rows for a payroll period *(shipped v3.17.242 — `psa.TimesheetSubmission` with unique `(user, period_start, period_end)`; `TicketTimeEntry.submission` FK attaches entries to a batch)*
- Submit → review → approve / reject pipeline *(shipped v3.17.242 — `/psa/timesheet/` tech submit + `/psa/timesheet-approvals/` staff decide)*
- Multi-tier approval (tech → team lead → finance)
- Per-entry rejection with note ("re-classify this billable entry as project work")
- Lock approved timesheets — entries can't be retroactively edited after approval *(shipped v3.17.249 — `TicketTimeEntry.save()` early-returns when entry's submission.status='approved'; admin override via `_force_unlock=True`)*
- Auto-reminder cron at end of payroll period for un-submitted timesheets
- Bulk-approve UI for managers *(shipped v3.17.249 — `/psa/timesheet-approvals/bulk/` endpoint + sticky bulk-action bar on the queue page)*
- Export approved timesheets to payroll (CSV / QuickBooks Time / Gusto) *(shipped v3.17.249 — `/psa/timesheet-approvals/payroll-export/` returns per-(tech, week) CSV ready for QBT/Gusto import)*
- Audit trail per entry: who approved, when, with what note *(partial — `decided_by` / `decided_at` / `decision_notes` per submission shipped v3.17.242)*

Dependencies: extends Phase 2 (BillableTarget + utilization) + the existing approval queue pattern.

**Goal:** Add billing-grade rigor to time entries before they flow into invoices and commissions.

## Phase 26 — Custom Report Writer + Saved Queries **(L)** [complete]

**Roadmap item:** User-defined reports without writing Python. Today reports are templated (Phase 3 ships ~15 canned reports); this phase lets non-developers build their own.

Planned capabilities:
- Visual query builder — pick model (Ticket / Invoice / TimeEntry / Asset / etc), filters, group-by, aggregates, sort, limit *(shipped v3.17.246 with Ticket / Asset / Password targets; v3.17.251 added Invoice + TicketTimeEntry targets with per-model `org_filter` for tenant scoping when the model lacks a direct organization FK)*
- Saved query model — per-org or shared *(shipped v3.17.246 — `reports.SavedQuery` with `is_shared` + organization scope)*
- Run as report (renders as table + auto-chart for numeric columns) *(table render shipped v3.17.246; auto-chart deferred to v2)*
- Schedule a saved query as a recurring email-PDF (extends Phase 3.6 scheduled-reports runner)
- Pin a saved query as a dashboard widget (extends Phase 3.5 widget registry)
- Export to CSV / JSON / Excel *(CSV shipped v3.17.246; JSON/Excel deferred)*
- SQL escape hatch for power users (gated behind a separate permission; sandboxed read-only DB connection)
- Report-template marketplace — share / import community report definitions

Dependencies: Phase 3.5 (dashboards), Phase 3.6 (scheduled reports).

**Goal:** Reduce the gap between what owners want to know and what's pre-templated.

## Phase 27 — Advanced Accounting Reconciliation **(M)** [shipped — v3.17.281]

**Roadmap item:** Deeper accounting integration than the basic invoice push that ships today (QBO + Xero — Phase shipped earlier). Adds true reconciliation between Client St0r's books and the accounting system.

Planned capabilities:
- Bidirectional payment sync — when a payment lands in QBO/Xero, mark the source Invoice as paid *(partial — `BaseAccountingProvider.poll_invoice_balance()` + QBO/Xero implementations + the `accounting_sync_payments` command shipped v3.17.280; idempotent + audit-logged. **Corrected v3.17.526:** this entry previously claimed a "daily cron". No timer, crontab entry or scheduler task was ever wired, so the command has only ever run when typed by hand. It also polls the invoice balance rather than reading provider payment records, so a partial payment is invisible and the Payment row it writes carries an inferred date and method. Real bidirectional sync — scheduling included — shipped as Phase 44, v3.17.531–531)*
- Invoice deduplication detection (catch double-pushes) *(shipped v3.17.255 — duplicate `(provider, accounting_external_id)` groups surfaced on `/reports/accounting-reconciliation/`. Extended v3.17.526 from detection to prevention: the push view refuses an invoice that already carries a provider id, so a double-click can no longer put a second invoice in front of the client. Re-push remains available as an explicit action for the deleted-provider-side case)*
- Unpaid-vs-pushed reconciliation report (what's invoiced here but missing in QBO?) *(shipped v3.17.255 — outstanding-pushed section + push-error section + CSV export)*
- Per-invoice line-item mapping to GL accounts (revenue vs. cost-of-services-sold splits) *(shipped v3.17.278 — `InvoiceLineItem.gl_account_code` propagates to QBO `ItemRef.value` and Xero `AccountCode` on push; blank falls through to provider default; back-compat)*
- Tax reconciliation (compare what we calculated vs. what QBO recorded) *(shipped v3.17.267 — `Invoice.provider_tax_amount` captured at push time from QBO `TxnTaxDetail.TotalTax` / Xero `TotalTax`; reconciliation report flags any |delta| > $0.01)*
- Accounts receivable aging tied directly back to QBO/Xero AR *(shipped v3.17.269 — `/reports/ar-aging/` per-client 0-30 / 31-60 / 61-90 / 90+ day buckets for pushed-but-unpaid invoices; CSV export; tenant-scoped)*
- Bank-account reconciliation hooks (mark which payments matched which bank-deposit batches) *(shipped v3.17.281 — `Payment.bank_deposit_batch` + `bank_reconciled_at` fields; per-batch report at `/reports/bank-reconciliation/` with mark-reconciled / reopen actions; staff-only)*
- Refund / credit-memo workflows *(shipped v3.17.264 — `Invoice.is_credit_memo` + `credits_invoice` FK + `create_credit_memo()` method that copies/negates lines or creates a lump-sum credit; sequential `CN-YYYY-NNNNN` numbering; UI modal on invoice detail; POST-only view at `/psa/invoices/<pk>/credit-memo/`)*
- Multi-entity / multi-book support for MSPs operating multiple legal entities *(shipped v3.17.279 — `Invoice.target_connection` FK pins the invoice to a specific AccountingConnection; push picks pinned else falls back to first sync-enabled; inactive-pinned-connection refuses push)*
- Audit trail of every accounting-system interaction *(shipped v3.17.260 — `AccountingAuditLog` writes one row per `push_invoice` / `record_payment` call across QBO + Xero providers; viewer at `/integrations/accounting/<pk>/audit-log/`. Stores truncated req/resp summaries — full payloads intentionally not stored to keep the log free of secrets/PII)*

Dependencies: existing AccountingConnection pattern. Builds on Phase 15.

**Goal:** Eliminate manual cross-checking between Client St0r and the accounting system.

Cross-references: Phase 36 (Agreement Reconciliation) layers an MSP-specific reconciliation flow — included-vs-billable labor, over/under-served clients, pre-invoice approval — on top of the GL-level reconciliation this phase covers.

## Phase 28 — Browser Extension + Offline Vault Access **(L)** [shipped — v3.17.331 — server-side API; extension binary out of scope]

**Roadmap item:** Chrome / Firefox / Edge extension for password autofill from the vault, plus an offline-capable PWA mode for read-access to the vault.

Planned capabilities:
- WebExtension (cross-browser via WebExtensions API) *(shipped v3.17.327–v3.17.331 — server-side API surface fully shipped: `vault.WebExtensionAuthToken` model + bearer-auth + autofill / sync / totp / reveal / verify-master / generate endpoints; complete contract documented in `docs/browser-extension-api.md`. The extension binary itself (Chrome / Firefox / Edge `.crx` package, store submission) is a separate codebase outside this repo)*
- One-click autofill on login pages from `vault.Password` matched by URL pattern *(shipped v3.17.328 — `/vault/api/extension/autofill/?url=...` returns matches by host suffix; per-call audit log)*
- Master-password unlock (re-derive AES-GCM key locally; never transmit master) *(shipped v3.17.329 — `GET /vault/api/extension/verify-master/nonce/` issues a 32-byte URL-safe nonce; `POST /vault/api/extension/verify-master/` constant-time-verifies HMAC-SHA256 keyed by the user's stored password hash; server never sees the master password)*
- Per-organization isolation (extension UI matches the active org context in-app) *(shipped v3.17.330 — `extension_auth_required` honours `X-Organization-Id` header per call when token is unpinned, falls back to token's pinned org otherwise; org-scoped queryset prevents cross-org leakage)*
- Offline-encrypted vault cache — last-fetched passwords are stored encrypted under a session key, valid for N hours so a tech can still pull a credential when the server is unreachable *(shipped v3.17.328 — `/vault/api/extension/sync/` cursor-paginated; returns encrypted blobs only; gated by `vault_extension_offline_cache` permission)*
- TOTP code generation in-extension (existing `totp_secret` field on Password) *(shipped v3.17.329 — `GET /vault/api/extension/<pk>/totp/` reuses `Password.generate_otp()`; per-call audit log)*
- Audit log of every autofill (logged when the extension reconnects) *(shipped v3.17.329 — every extension call emits a `vault_extension_*` AuditLog row synchronously: autofill / sync / totp / reveal / verify_master)*
- Generate-strong-password helper (matches the existing in-app generator) *(shipped v3.17.330 — `/vault/api/extension/generate/` reuses `vault.utils.generate_password`; returns `{password, length, charset_size, entropy_bits}` for client-side strength meter)*
- Browser-extension specific permissions on RoleTemplate (`vault_extension_use`, `vault_extension_offline_cache`) *(shipped v3.17.328 — both boolean fields on RoleTemplate; simple-role fallback maps Owner/Admin → both True, Editor → use only, Read-Only → neither)*

Dependencies: existing vault model + AES-GCM key infra. Browser extension is a separate codebase + store-submission process.

**Goal:** Match the IT Glue / Bitwarden experience that techs already expect.

## Phase 31 — Vault GeoIP / IP / Time Access Rules **(S)** [shipped — v3.17.163]

Per-rule GeoIP / IP / time-of-day gates on top of the vault. New `VaultAccessRule` model, scopable to a specific Password, a specific User, or an Organization (three scopes). Rules carry allowed/blocked country lists (ISO codes), allowed/blocked CIDR lists, allowed weekdays + hour window with IANA timezone, plus priority + active flag. DENY-wins-then-priority engine; empty rule set keeps back-compat ALLOW. Every reveal/view decision is audit-logged with the reason, source IP, country, and matched rule ID. New `vault_manage_access_rules` permission gate.

- `vault.VaultAccessRule` model + migration *(shipped v3.17.163)*
- Decision engine `vault/access_rules.py` reusing firewall middleware GeoIP helpers *(shipped v3.17.163)*
- CRUD UI under `/vault/access-rules/` + access-denied page *(shipped v3.17.163)*
- Detail-view badge: "N access rules apply" *(shipped v3.17.163)*
- 7 unit tests in `vault.tests.VaultAccessRuleEngineTests` *(shipped v3.17.163)*

---
- Click-to-select world map for country selection *(shipped v3.17.522 — replaces comma-separated ISO-code text boxes on both the vault access-rule form and the global firewall country rules with a clickable world map; a country belongs to one list, so "allowed AND blocked" is not expressible. Country names resolve server-side from a bundled ISO 3166-1 table, never from the browser. Map backdrop is configurable — colour pattern, random, or an uploaded image — and is cosmetic only, saved through its own endpoint so it can never rewrite firewall rules)*

## Phase 32 — Remote Network Discovery Import **(M · future / late-stage)** [complete]

A technician opens an Organization in ClientSt0r, picks a Location, and clicks **Generate Network Discovery Script**. ClientSt0r issues a temporary one-time-use token bound to that single org + location, generates a downloadable PowerShell script, and the tech runs it on a Windows host inside the client's network. The script does a safe (non-intrusive, non-credentialed) sweep of the local subnets, collects IP / MAC / hostname / vendor data, and uploads the results back to ClientSt0r. ClientSt0r imports / updates Asset records under that Org + Location, deduping by MAC and by org+location+IP.

**Roadmap item — placed near the end of the roadmap as a future / late-stage feature.** The user request explicitly says do not turn this into an RMM agent: no persistent agents, no permanent API keys, no exploit scanning. Strictly safe, auditable, scoped, MSP-friendly network discovery.

### Models (new app, e.g. `network_discovery/`)

- **`NetworkDiscoveryToken`** — `id`, `organization` FK, `location` FK, `created_by`, `token_hash` (only the hash; full token never re-displayable), `expires_at`, `revoked_at`, `used_at`, `max_uses` (default 1), `use_count`, `source_ip_last_used`, `user_agent_last_used`, `notes`, audit timestamps.
- **`NetworkDiscoveryImport`** — `id`, `organization`, `location`, `token` FK, `uploaded_by_user`, `source_ip`, `device_count`, `imported_count`, `updated_count`, `skipped_count`, `error_count`, `raw_payload` (JSON, optional summarized form), `created_at`.
- **`NetworkDiscoveryAssetResult`** — `id`, `import` FK, `organization`, `location`, `asset` FK (nullable; set when matched / created), `ip_address`, `mac_address`, `hostname`, `vendor`, `device_type`, `discovery_method`, `status`, `raw` JSON, `created_at`.

### Endpoints

- `POST /orgs/<org_id>/locations/<location_id>/network-discovery/generate/` — authenticated; gates on a new `network_discovery_generate` RoleTemplate boolean. Returns the script file + the one-time token displayed once on screen (never again).
- `GET /orgs/<org_id>/locations/<location_id>/network-discovery/download/<token_id>/` — re-downloads the script (token still hidden; re-renders only the script body with the token already embedded server-side at first generation).
- `POST /api/network-discovery/upload/` — public, **token-only** auth. Token is single-use (or limited-use), short-lived, scoped to one (org, location), POST-only, write-only — cannot read anything. Validates payload size + IP/MAC/hostname formats. Rate-limited.
- `POST /orgs/<org_id>/locations/<location_id>/network-discovery/revoke/<token_id>/` — revokes immediately.
- `GET /orgs/<org_id>/locations/<location_id>/network-discovery/imports/` — import history.

### PowerShell script behavior

- Auto-detects active local IPv4 subnets from active network adapters
- Optional params: `-Subnet`, `-ServerUrl`, `-Token`, `-OrgId`, `-LocationId`, `-TimeoutMs`, `-MaxHosts`, `-SkipUpload`, `-OutputJsonPath`
- Default: ping sweep / `Test-Connection`, ARP table collection, optional reverse-DNS, MAC harvest from `arp -a` / `Get-NetNeighbor`
- Optional lightweight enrichment: probe ports 80 / 443 / 22 / 3389 / 445 only — for device-type classification (workstation / server / router / printer / unknown). Never destructive, never credentialed, never vulnerability scan.
- Runs on Windows PowerShell 5.1+ and PowerShell 7+
- Doesn't require admin unless necessary
- Always writes a local JSON summary before upload
- Shows count of discovered devices and upload result

### Asset import behavior

1. Match by MAC first.
2. If no MAC match, match by `(organization, location, ip_address)`.
3. On match: update missing fields only; never overwrite manually-entered names; bump `last_seen` / discovery metadata.
4. On no match: create a new Asset with `organization`, `location`, name = hostname → IP → MAC, `asset_type` = "Network Discovered Device" (or "Unknown Network Device"), IP, MAC, vendor, notes "Discovered by Remote Network Discovery Import".
5. Optional dry-run / preview mode.

### Security requirements

- Token is **temporary** (short expiry, default 15 min)
- Scoped to **one org + one location** only
- **Write-only** — can't read anything; only POST to the discovery upload endpoint
- **Single-use by default** (or limited-use with expiration) — `max_uses=1`, `use_count` tracked
- Server stores **only a hashed version** of the token; full plaintext shown once at generation, then never again
- Revocable from the UI
- Every generation, download, upload, import event audit-logged (user, org, location, source IP, count, errors)
- Upload endpoint rate-limited
- Payload size validated; all IP/MAC/hostname fields validated
- Generation requires existing authenticated user permissions
- The PowerShell script clearly shows the ClientSt0r server URL it will upload to but contains **no permanent credentials**

### UI

- Network Discovery section on Organization detail page (location-scoped)
- "Generate Network Discovery Script" button after a Location is picked
- Token expiration shown
- Last generated scripts list
- Revoke buttons
- Import history with imported / updated / skipped / error counts per import
- Last scan summary
- Warning banner: **"Run this only on networks you are authorized to scan."**

### Tests

Token generation; expiration; revocation; valid upload; expired token rejected; revoked token rejected; cross-org / cross-location upload rejected; duplicate MAC updates existing asset; duplicate IP/location updates existing asset; new devices create assets; unauthorized users cannot generate scripts; payload validation; rate limiting (if testable).

### Goal

Provide MSP-friendly remote network discovery without standing up a full RMM agent. Everything is **temporary, scoped, auditable**, and bound to a single org + location. Not a backdoor. Not a persistent agent.

✅ **Phase 32 complete at v3.17.556.** New `network_discovery` app. Every security requirement above is implemented and tested: 15-minute single-use tokens stored as SHA-256 hashes with the plaintext shown exactly once, scoped to one org + location, write-only, revocable, rate-limited, with every generation / download / upload audit-logged including source IP.

Two implementation notes worth recording:

- **The re-download endpoint can only work while the generating user's session still holds the plaintext.** The roadmap asked for a re-download that keeps the token hidden; since the server stores only a hash, there is nothing to rebuild the script from once that session copy is gone. It says so and offers a new token rather than pretending otherwise.
- **Every upload rejection returns an identical response.** Expired, revoked, spent and never-existed are indistinguishable to the caller — an anonymous endpoint that distinguishes them is a token oracle.

Phase 33 layers the deeper, persistent / scheduled, multi-protocol discovery on top of this single-shot foundation.

---

## Phase 33 — Network Discovery & Auto Documentation **(L)** [complete]

Multi-protocol persistent network discovery and topology inference. Phase 32 ships a one-shot, scoped, single-use ping / ARP script — useful for the first walk-through of a new client. Phase 33 is the always-on companion: a lightweight per-site collector that polls SNMP / LLDP / CDP / ARP on a schedule, keeps the asset inventory current, and generates topology diagrams without manual draw-time.

Planned capabilities:
- **Lightweight site collector / agent** — one per client site, packaged as a small container or systemd unit. Pulls config from server, pushes results back. No persistent admin credentials embedded; uses a per-site rotating token similar to Phase 32's scheme.
- SNMP, ICMP, ARP, LLDP, CDP discovery
- Automatic device inventory import *(extends the single-shot Phase 32 import flow)*
- Auto-generated topology maps *(extends Phase 16 Documentation Relationship Mapping with a dedicated network-layer view)*
- Device relationship mapping (which switches connect which APs / endpoints)
- Switch port / MAC / IP correlation table (resolve "which port is this device on" per VLAN)
- Manual and scheduled scans (cron-driven background jobs; on-demand trigger from the UI)
- Per-client and per-location discovery keys (rotation + revocation, audit log)

Dependencies: Phase 32 (token + import models — extend rather than replace), Phase 16 (relationship graph rendering), Asset model.

**Goal:** Reduce manual network documentation work — keep the topology, switch port assignments, and device inventory in sync with reality without a tech having to redraw or re-export anything.

✅ **Phase 33 complete at v3.17.557.** Built on Phase 32's models rather than replacing them, as the dependency note asked.

- **`DiscoverySite`** — a per-site collector with a rotating, revocable key. It is a standing credential, which Phase 32's token deliberately is not, and the boundary that makes that acceptable is enforced and tested: it reads **only its own scan settings** (no assets, no credentials, no other site) and writes **only** discovery results into one organization and one location.
- **`NetworkLink`** — LLDP/CDP adjacencies, idempotent on re-report. A neighbour we do not manage is kept as an unresolved node rather than dropped, because "there is something on port 12 we don't manage" is exactly what a topology map should show. A link not seen for a month is flagged stale rather than deleted.
- **`SwitchPortEntry`** — the port / VLAN / MAC / IP correlation table that answers "which port is this device on". One row per (port, VLAN, MAC), so an uplink carrying many MACs is a fact to display rather than a conflict to resolve.
- **Topology map** — force-directed SVG rendered from a seeded layout, so the same network draws the same way twice.
- **Scheduled and on-demand scans** — cadence lives on the site; "scan now" is a flag the collector picks up on its next check-in, because it polls and we never connect inbound to a client network.

**Scope note, stated plainly:** the server side is complete and tested (112 tests). `deploy/network-collector/collector.py` is a reference implementation whose ping/ARP paths work with only the standard library; its **SNMP paths are documented extension points returning empty lists**, because LLDP/CDP walks need `pysnmp` and real switch hardware to validate, and an untested walk that silently returns nothing would look identical to a working feature finding no neighbours. The server accepts and stores that data today.

## Phase 34 — Network Configuration Backup **(M)** [complete]

Versioned configuration backup for firewalls, switches, routers, and other manageable network gear. Treats device configs the same way the existing `Document` versioning treats KB articles — every change snapshotted, diffable, alertable.

Planned capabilities:
- **Firewall, switch, and router config backup** — pulled via SSH / SCP / SNMP / vendor APIs depending on device. Per-device adapter pattern matching the integration framework shipped in Phase 7.
- Scheduled backup jobs (per-device cadence; default daily)
- Config diff viewer — line-level diff between any two snapshots; latest-vs-prior on the device detail page by default
- Alert on unauthorized config changes — diff against the last "approved" snapshot; surfaces in the security-alerts dashboard (Phase 9) when something changes outside of an approved change window (Phase 6.1 CAB)
- Firmware / version tracking — captures running firmware version on each backup so EOL transitions are visible
- End-of-life and warranty metadata fields on the device record (extends Phase 13 lifecycle tracking)

### Sub-phase 34.1 — The snapshot store and diff viewer *(shipped v3.17.544)*
- **`netconfig.ConfigBackup`** — a captured configuration, immutable once written. Not a `BaseModel`: a snapshot states what a device's config *was* at a moment, and an `updated_at` would imply editing one is normal when editing one destroys the only thing it is for. The admin renders the body read-only for the same reason. *(shipped v3.17.544)*
- **Identical captures do not duplicate.** `record_for_asset()` hashes the body and, when it matches the newest snapshot, moves `last_seen_at` instead of writing another row — a device nobody touches for a year is one row plus a moving timestamp, not 365 copies. The hash normalises trailing whitespace and line endings, so a device that starts padding lines or switches CRLF to LF does not read as "everything changed". *(shipped v3.17.544)*
- **Line-level diff** between any two snapshots, with latest-vs-prior rendered on the device page without being asked for. Diffing against nothing returns an empty diff rather than raising — the first capture of a device has nothing to compare against, and that is a normal state. *(shipped v3.17.544)*
- **Manual capture — paste or upload.** Collection over SSH is 34.2, but this works with nothing but a paste box on purpose: a config pasted by hand is worth versioning, and waiting for device credentials before storing anything would be the wrong order. *(shipped v3.17.544)*

### Sub-phase 34.2 — Collection over SSH *(shipped v3.17.545)*
- **`netconfig.BackupTarget`** — host, port, username, platform, per-device cadence. Credentials are **not** stored on it: the field links to a `vault.Password`, because the vault already encrypts, audits and access-controls secrets and a second half-built secrets store beside it would be strictly worse. Deleting the vault entry disables collection rather than falling back to anything. *(shipped v3.17.545)*
- **An approval-gated credential cannot be used by the scheduled job.** A vault entry marked `requires_reveal_approval` exists because somebody decided a human should sign off on each use; a nightly run cannot ask anyone, and reading the secret anyway would defeat the control while leaving the setting switched on and looking effective. The device reports why instead. *(shipped v3.17.545)*
- **Seven platform adapters** — Cisco IOS/IOS-XE, Cisco ASA, Arista EOS, Juniper Junos, MikroTik RouterOS, FortiOS, HP/Aruba ProCurve — plus a generic single-command fallback and a per-device command override for an appliance nobody wrote an adapter for. Adapters know vendor commands and output tidying; the SSH transport is shared, so a timeout bug is fixed in one place. *(shipped v3.17.545)*
- **`backup_network_configs`** management command and a `network_config_backup` scheduler task. One unreachable device never stops a run: every device failure is recorded on the target and the run continues. Every collection writes an audit row, success or failure — opening an administrative session to a firewall with a stored credential should not happen without a trace. *(shipped v3.17.545)*
- `paramiko` added to `requirements.txt` and imported lazily, so an install that has not re-run pip keeps working everywhere except this one feature, which reports the missing dependency rather than failing at import and taking the app with it.

### Sub-phase 34.3 — Drift alerts *(shipped v3.17.546)*
- **Baseline per device** — mark a snapshot approved and later configs are compared against it. Approving one demotes the previous: two baselines would make "drift from the approved config" ambiguous, and an ambiguous alert is one nobody trusts. *(shipped v3.17.546)*
- **Change-window awareness** — a change is `expected` when an approved `psa.ChangeRequest` for that client covers the capture time, and `unauthorized` otherwise. Only `approved` and `implementing` count; a `draft` or `pending_cab` change is exactly the case that should still raise. A request with no schedule is not a window — "approved, sometime" is not a licence, and treating it as one would silence every alert for that client. *(shipped v3.17.546)*
- **No baseline means no drift.** Alerting before anybody has declared a known-good config would mean every device screams from its first capture, which trains people to ignore the alerts. *(shipped v3.17.546)*
- **Unauthorized changes raise a `SecurityAlert`** at high severity on the Phase 9 dashboard, carrying the diff size and links back to the snapshot and baseline. A failure in the alert path is logged and swallowed — it must not lose the snapshot or fail the backup run that produced it. *(shipped v3.17.546)*

### Sub-phase 34.4 — Firmware and lifecycle *(shipped v3.17.547)*
- **Firmware history derived from the snapshots** rather than stored separately, so it cannot disagree with them. Consecutive captures reporting the same version collapse into one entry — a device on one firmware for a year is one row, not 365 — and a snapshot with no firmware reported is skipped rather than shown as a transition to "nothing". *(shipped v3.17.547)*
- **`Asset.vendor_end_of_life` / `vendor_end_of_support`** — the vendor's announced dates, which have nothing to do with when you bought the thing. A model's last day of support is the same date whether it was racked in 2019 or bought refurbished last month, so it cannot be derived from purchase date plus lifespan the way the existing estimate is. `get_end_of_life_date()` now prefers a published date over the arithmetic. *(shipped v3.17.547)*
- **Lifecycle view** listing network gear that is out of vendor support or reaching either date within a year, out-of-support first: a switch no longer receiving security fixes is a different kind of problem from one due for replacement next year. *(shipped v3.17.547)*

✅ **Phase 34 complete at v3.17.547.** Shipped across four sub-phases (v3.17.544–547). The stated Phase 33 dependency turned out not to block it — `assets.Asset` already carries the network-gear types, so the device list had a source without waiting for discovery.

Dependencies: Phase 33 (device inventory provides the target list) — **not blocking**: 34.1 targets `assets.Asset` rows already typed as switch / router / firewall / load balancer / wireless AP or controller / modem / gateway / bridge / console server, so the feature is usable before Phase 33 exists. Phase 9 (alert framework for drift notifications) and Phase 6.1 (CAB / change-window awareness) are needed for 34.3.

**Goal:** Eliminate the manual config-export-and-store-in-a-folder routine. Make unauthorized changes loud.

## Phase 35 — Advanced Project Management **(L)** [complete]

Mature the existing `psa.Project` and `psa.ProjectTask` models *(quote-to-project automation shipped v3.17.213)* into a full delivery management feature.

Planned capabilities:
### Sub-phase 35.1 — Project templates *(shipped v3.17.548)*
- **`psa.ProjectTemplate` / `ProjectTemplateTask`** — predefined work breakdowns for common project types. A server migration is the same twenty tasks every time, and retyping them is where steps get forgotten. *(shipped v3.17.548)*
- **Applying a template copies.** The resulting rows are ordinary `ProjectTask`s with no link back to the template: a project that silently changed shape because somebody edited the template months later would be worse than having no templates. Deleting a template leaves every project built from it untouched. *(shipped v3.17.548)*
- **Template tasks carry an offset, not a date** — a template is used in March and again in November, and a stored date would be wrong both times. `0` means the project's start date and is deliberately distinct from "no date". *(shipped v3.17.548)*
- **Applying appends rather than replaces**, so a template dropped onto a project that already has work does not delete it. Nested tasks keep their parent through the copy.  *(shipped v3.17.548)*

### Sub-phase 35.2 — Budget tracking *(shipped v3.17.549)*
- **`Project.budget_hours` / `budget_amount` / `budget_warn_at_percent`** — a budget is what the work is *allowed* to take, deliberately separate from `estimated_hours`, which is what it was *thought* to take. They are routinely different numbers agreed by different people. *(shipped v3.17.549)*
- **Actuals come from time logged on the project's tickets**, since that is the only place time is recorded. Billable and total are tracked separately. *(shipped v3.17.549)*
- **An unknown amount is reported as unknown, never as zero.** Spend needs an hourly rate from the client's active contract; without one `actual_amount()` returns `None` and the page says so. A project showing no spend because nobody recorded a rate reads as comfortably under budget when the truth is that it has not been measured. *(shipped v3.17.549)*
- **Worst of the two budgets wins.** A project inside its hours but over its money is over — saying otherwise would be the comfortable answer rather than the true one. An unmeasurable money budget does not mask a breached hours budget. *(shipped v3.17.549)*

### Sub-phase 35.6 — Billing *(shipped v3.17.555)*
- **`Project.billing_type`** — time and materials, fixed fee, or milestone. The three produce genuinely different invoices: logged hours, one agreed number, or a number per delivered milestone. *(shipped v3.17.555)*
- **Nothing bills twice.** Billed time is found through `InvoiceLineItem.source_id`, the pointer the existing time-to-invoice path already writes, rather than a second flag that could disagree with it. A fixed fee is stamped with a sentinel source id; a milestone carries a `billed_on_invoice` foreign key so "which invoice was that on" survives. *(shipped v3.17.555)*
- **An unpriceable invoice is refused, not raised at zero.** Without a contract rate, T&M work cannot be priced and generation stops with a message. Milestones are stamped only after the invoice exists, so a failure part-way cannot mark work billed that never reached a bill. *(shipped v3.17.555)*
- **Everything generated is a draft.** Nothing in this sub-phase decides to send a client a bill. *(shipped v3.17.555)*

✅ **Phase 35 complete at v3.17.555.** Shipped across six sub-phases (v3.17.548–555): templates, budgets, profitability, task-to-ticket, timeline with dependencies, and billing.

### Sub-phase 35.5 — Timeline and dependencies *(shipped v3.17.554)*
- **`ProjectTask.start_date`** — a timeline bar needs both ends. `due_date` alone described a deadline; a schedule needs to know when work is meant to begin. A task carrying only one date draws as a single-day marker rather than vanishing from the plan. *(shipped v3.17.554)*
- **`ProjectTask.depends_on`** — self-referential, explicitly not symmetrical, with cycles refused at the point of creation. A cycle makes "what can start now" unanswerable and sends any scheduling walk into an infinite loop, so it is rejected when the edge is drawn rather than defended against everywhere afterwards. Chains and diamonds are allowed; depth is not a cycle. *(shipped v3.17.554)*
- **Timeline view** with bars positioned as server-computed percentages, so CSS handles responsiveness and JavaScript is needed only for dragging. Drag posts to the same endpoint the date inputs use, so the feature works with scripting off. Unscheduled tasks are listed rather than hidden — a task missing from a plan is easy to forget entirely — and a dependency arrow pointing at an unscheduled task is dropped rather than drawn to nowhere. *(shipped v3.17.554)*

### Sub-phase 35.3 — Profitability *(shipped v3.17.553)*
- **Cost from effective-dated `resourcing.TechCostRate`** — each time entry is costed at the rate that applied to that technician on the day the work happened, so a raise in June does not retroactively make March's work more expensive. *(shipped v3.17.553)*
- **Revenue is billable hours at the client contract's rate; margin is the difference.** Both are `None` when no rate is known, because a margin computed against unknown revenue is a subtraction from nothing dressed up as a business figure. *(shipped v3.17.553)*
- **Guesses are declared.** Entries costed at the system default because a technician has no configured rate are counted and surfaced, so a margin built partly on defaults is not presented as measured. Entries with no user recorded are skipped rather than costed at a default, which would attribute cost to nobody. *(shipped v3.17.553)*

### Sub-phase 35.4 — Tasks become tickets *(shipped v3.17.550)*
- **Any project task can spawn a ticket on demand**, linked through the task's existing `related_ticket`. The two are not merged: the task stays the unit of planning, and the ticket becomes the unit of work that time, SLA and comments hang off. *(shipped v3.17.550)*
- **The ticket is attached to the project**, which is the entire point — time logged on it counts towards the project's actuals from 35.2. A task's due date becomes the ticket's resolution target, because a task due Friday whose ticket carries no date drops off every SLA view. *(shipped v3.17.550)*
- **One ticket per task.** A second would split the time entries across two records and quietly break the project's actual-hours figure. *(shipped v3.17.550)*

Remaining planned capabilities:
- **Project templates** *(shipped v3.17.548 — see 35.1)*
- Project phases and milestones *(milestones partial — `ProjectTask.is_milestone` flag exists)*
- **Project budget tracking** *(shipped v3.17.549 — see 35.2)*
- **Project profitability** *(shipped v3.17.553 — see 35.3)*
- **Project-to-ticket task generation** *(shipped v3.17.550 — see 35.4)*
- **Project billing support** *(shipped v3.17.555 — see 35.6)*
- **Gantt / calendar-style planning view** *(shipped v3.17.554 — see 35.5)*

Dependencies: existing `psa.Project` + `psa.ProjectTask` models, Phase 3 (profitability infra), Phase 1 (contract / billing engine).

**Goal:** Take the lightweight Project model from "lets you group tickets" to "actually runs delivery engagements end-to-end."

## Phase 36 — Agreement Reconciliation & Pre-Invoice Approval **(M)** [complete]

MSP-specific reconciliation between what an agreement covers and what's actually being consumed. Phase 27 handles GL-level reconciliation against QBO/Xero; this phase handles agreement-vs-labor reconciliation against the contract itself, plus an explicit pre-invoice review gate so nothing goes out the door without a human nod.

Planned capabilities:
- **Recurring agreement billing review** — monthly (or per-cycle) review screen that lists every agreement, included-hours bucket consumed, overage hours, and the draft invoice *(partial — per-contract consumption table shipped v3.17.225 at /reports/agreement-reconciliation/)*
- **Included vs billable labor reconciliation** *(shipped v3.17.248 — `agreement_reconciliation_detail` view classifies entries chronologically as covered/overage/split; per-tech overage breakdown + CSV export)*
- **Over-serviced / under-serviced client alerts** — if a client consistently uses < 30% of included hours (under-served = upsell signal) or > 130% of included hours 3 months running (over-served = re-quote signal), alert the account manager *(shipped v3.17.225 — surfaced as status badges + summary counts on the reconciliation page; recurring-pattern detection across multiple periods deferred to v2)*
- **Agreement profitability reports** *(extends Phase 3.2 contract profitability with per-agreement P&L; cost-of-labor at tech rate vs. contracted revenue)*
- **Pre-invoice approval workflow** *(extends Phase 20 approval routing — gate any draft invoice over $X or with > Y% overage on a manager queue before sending)* *(shipped v3.17.228 — `Invoice.flag_for_approval` + `Invoice.approve` + `/psa/invoices/<pk>/approve/` endpoint + push-to-accounting blocked while pending)*
- **Revenue leakage detection expansion** *(extends the existing `revenue_leakage` query that powers the `unbilled_hours` widget; adds aging buckets, per-tech leakage attribution, and a per-client leakage trend)*

Dependencies: Phase 1 (contract engine — `Contract`, `ContractBundle`, `ContractBundleItem`), Phase 15 (recurring billing automation), Phase 20 (approval routing).

**Goal:** Stop money walking out the door. Make every agreement's profitability and consumption visible before invoicing, not after.

## Phase 37 — Vault Approval & Break-Glass Workflow **(M)** [complete]

Per-credential approval gates and emergency-access ("break-glass") flow for the password vault. Phase 31 *(shipped v3.17.163)* provides geo / IP / time-window restrictions; this phase adds workflow restrictions on top.

Planned capabilities:
- **Require approval before revealing sensitive vault entries** *(shipped v3.17.241 — `Password.requires_reveal_approval` flag + `VaultRevealRequest` model + `password_reveal` view gates on currently-valid approval)*
- **Emergency break-glass access** *(shipped v3.17.241 — `/vault/<pk>/break-glass/` endpoint with mandatory ≥30-char justification, self-approves, hard audit log)*
- **Manager / admin notifications** *(shipped v3.17.241 — every reveal request emails superusers; every break-glass emails superusers immediately)*
- **Full access audit trail** *(extends the per-action vault audit shipped v3.17.181 — `vault_reveal_requested`, `vault_reveal_approved`, `vault_reveal_denied`, `vault_break_glass`, `reveal_blocked_no_approval` join the existing edit/delete events; shipped v3.17.241)*
- **Optional client-level vault approval rules** *(shipped v3.17.247 — `_can_decide_vault_reveal` policy helper allows `Membership.is_org_admin=True` of the password's org to approve, with self-approval blocked regardless of role)*

Dependencies: Phase 31 (`vault.VaultAccessRule` infra — extend rather than replace), Phase 20 (approval routing engine).

**Goal:** Make sensitive credentials require explicit human authorization to reveal, while preserving a documented escape hatch for genuine emergencies.

## Phase 38 — Client Onboarding / Offboarding Runbooks **(M)** [complete]

Repeatable runbooks for client onboarding, employee onboarding/offboarding, and client termination. Each runbook is a structured checklist with verification steps and ticket-spawning hooks. Builds on the existing `processes/` workflow engine.

Planned capabilities:
- **Repeatable onboarding templates** — clone an `is_template=True` Process per new client; copies all stages with linked entities preserved *(shipped v3.17.223)*
- **Employee onboarding / offboarding workflows** *(category support shipped — `onboarding` / `offboarding` already existed; `client_*` companions added v3.17.223)*
- **Client termination checklist** — `client_termination` category added so the existing Process model carries the termination flow *(category shipped v3.17.223)*
- **Access removal verification** — for offboarding, mechanically verify that the user is actually removed from each documented system (poll vault, M365, RMM, etc.) and surface any orphaned access *(deferred — requires M365 / RMM / vendor-API integrations beyond the runbook engine itself; the manual checklist pattern via runbook stages is fully supported today, an MSP can build a "verify M365 license removed" stage and tick it off after manual confirmation)*
- **Documentation completion scoring** — per-execution `ProcessExecution.completion_percentage` already shipped; per-org dashboard with rollup across all in-flight runbooks at `/processes/dashboard/` *(shipped v3.17.227)*
- **Runbook-to-ticket conversion** — any runbook step can spawn a Ticket; created ticket is recorded on `ProcessStageCompletion.spawned_ticket` *(shipped v3.17.223)*

Dependencies: `processes/` app (existing), Phase 14 (visual workflow builder for runbook editing).

**Goal:** Turn ad-hoc tribal-knowledge onboarding/offboarding into a measurable, repeatable, completable workflow.

## Phase 39 — Compliance Evidence Packs **(M)** [complete]

One-click exportable audit packet per client. Bundles the evidence regulators / auditors / cyber-insurance underwriters consistently ask for, sourced from data already living in Client St0r — no manual screenshot-and-paste required.

Planned capabilities:
- **Exportable client audit packet** — single styled HTML page (with print-to-PDF stylesheet) + downloadable ZIP of per-section CSVs *(shipped v3.17.222)*
- 2FA status — which users on the account have 2FA enrolled, by method *(shipped v3.17.222)*
- User access report — current memberships, role templates, last-login per user *(shipped v3.17.222)*
- Password access history *(extends vault audit shipped v3.17.181 — every reveal / edit / delete event in the period)* *(shipped v3.17.222 — last 90 days)*
- Asset inventory — current asset list with serial / vendor / location / lifecycle stage *(shipped v3.17.222)*
- Vulnerability scan summary *(extends Phase 9 security framework + the existing OS Package Scanner)* *(shipped v3.17.226 — 90-day open-alert summary by severity)*
- SSL / domain expiration summary *(extends the WebsiteMonitor expiration infra)* *(shipped v3.17.226)*
- Ticket / SLA history — ticket counts, SLA-met percentages, response and resolution medians *(shipped v3.17.222 — 12-month window)*
- Backup and uptime evidence — backup-job success rate, monitor uptime percentages over the period *(uptime shipped v3.17.226; backup is a placeholder until a backup-tracking integration is built)*

Dependencies: Phase 9 (security data), vault, monitoring/, psa (SLA history), assets.

**Goal:** Reduce the "audit prep" interrupt to a button-press. The data is already in the system; this phase wraps it in the standardized export shape auditors expect.

## Phase 40 — Public / Client-Facing Status Page **(M)** [complete]

Public or per-client-private status page surfacing current service status, scheduled maintenance, incident history, and uptime. Sourced from the WebsiteMonitor + ticket-incident infrastructure already in place.

**Correction (v3.17.538):** this phase was written assuming uptime could be read from "`WebsiteMonitor` history". There was no such history — `WebsiteMonitor` stored only the *current* status, last response code and last check time, and nothing recorded what any earlier check returned. Uptime percentages were therefore not computable from existing data at all, and Sub-phase 40.1 exists to build the missing history. A consequence worth stating plainly: **uptime figures start accumulating from the v3.17.538 deploy**, not retroactively, so a 365-day figure is not available until a year after that.

### Sub-phase 40.1 — Check history + uptime *(shipped v3.17.538)*
- **`monitoring.MonitorCheck`** — append-only row per website check: monitor, `checked_at`, status, HTTP code, response time, error. Written by `WebsiteMonitor.check_status()` inside a guard, so a failure to record history can never turn a successful check into a failed one. *(shipped v3.17.538)*
- **`WebsiteMonitor.uptime(days)`** — computed from those rows rather than stored, so changing retention or backfilling a gap cannot leave a counter disagreeing with the data behind it. Returns `percent=None` for a window with no checks, because 0% reads as a total outage and 100% as a clean record and both would be lies. `warning` counts as up — a redirect or an expiring certificate means the site answered. *(shipped v3.17.538)*
- **`prune_monitor_checks`** — retention command, default 400 days. This is the highest-volume table in the app (~105,000 rows/year for a monitor on a five-minute interval). 400 rather than 365 so a full-year figure stays computable right up to the moment the prune runs. Deletes in batches so a big backlog doesn't hold one long transaction against the table the checker is appending to. *(shipped v3.17.538)*

### Sub-phase 40.2 — The page itself *(shipped v3.17.540)*
- **`statuspage.StatusPage`** — off by default, reached by a 43-character random token rather than a guessable id, rotatable, and 404-ing rather than 403-ing when disabled so a probe cannot confirm a page exists. Not a singleton, unlike the Phase 47 wallboard: `organization` null means a broadcast page covering shared infrastructure, and a page scoped to a client can only carry that client's services. *(shipped v3.17.540)*
- **`statuspage.StatusPageService`** — the indirection that makes the page publishable. A `WebsiteMonitor` carries an internal name and the URL being polled, and neither belongs on an anonymous page; `display_name` is required and is all the public sees. Adding a service without one is refused rather than defaulted, because defaulting would leak exactly what the field exists to avoid. *(shipped v3.17.540)*
- **Public view** at `/status/p/<token>/` — per-service status plus 30 / 90 / 365-day uptime, `no-store` and `noindex`, standalone template (no nav, no session chrome, meta-refresh so it works with scripting off). Worst status wins overall: one service down makes the page say outage. A window with no recorded checks reads "no data" rather than a percentage. *(shipped v3.17.540)*
- **Management UI** under Operations → Monitoring → Status Pages — create, publish, rotate the link, add and remove services. *(shipped v3.17.540)*

### Sub-phase 40.3 — Maintenance windows *(shipped v3.17.541)*
- **`statuspage.MaintenanceWindow`** — title, body, start, end, and optionally the services affected. Visible on the public page **from the moment it is posted**, not from the moment it starts: announcing planned work in advance is the thing that stops the call it would otherwise generate. *(shipped v3.17.541)*
- **State is derived from the clock**, not stored — a stored status would need a job to advance it and would be wrong in the gap between a window opening and that job running. `is_cancelled` is the one stored flag, because no amount of looking at the clock tells you a window was called off. A cancelled window stays on the page marked cancelled rather than vanishing, so anyone who read the original notice can see it is off. *(shipped v3.17.541)*
- **Empty service selection means "everything"** and is stored as no rows rather than every row, so the set stays correct when a service is added later. Finished windows are capped at five on the public page — listing every maintenance since inception buries the one happening tonight. *(shipped v3.17.541)*

### Sub-phase 40.4 — Incident history *(shipped v3.17.542)*
- **`psa.Ticket.is_status_page`** — flags a ticket as one an operator intends to publish. The flag alone publishes nothing; it only makes the ticket appear in the incident picker. *(shipped v3.17.542)*
- **`statuspage.StatusPageIncident`** — the published record, with a `title` written for the audience rather than the queue. The same indirection as `StatusPageService`, for the same reason: "Exchange transport stuck, DAG node 2 down again" is a fine ticket subject and a terrible thing to show a client's customers. The ticket link is optional and `SET_NULL`, so an incident can be posted before anyone opens a ticket and survives the ticket being deleted. *(shipped v3.17.542)*
- **`statuspage.IncidentUpdate`** — the timeline, with an `investigating` / `identified` / `monitoring` / `resolved` stage. Deliberately **not** sourced from ticket comments: a non-internal comment is visible to the client in the portal, which is a different and much smaller audience than an anonymous status page, and treating the two as interchangeable would republish ticket chatter to the internet. Posting a `resolved` update resolves the incident, because doing it as a separate step is what everyone forgets. *(shipped v3.17.542)*
- Ongoing incidents render above planned maintenance — something broken now outranks something planned. Resolved history is capped at ten. *(shipped v3.17.542)*

### Sub-phase 40.5 — Per-client private pages *(shipped v3.17.543)*
- **`StatusPage.visibility`** — `public` (anyone with the token link) or `portal` (signed-in client users only). Defaults to `public`, so every page created before this field keeps behaving exactly as it did. A portal page's token stops working anonymously, and the anonymous view returns the same 404 it gives for a wrong or disabled token — the response never distinguishes "wrong token" from "needs a login". *(shipped v3.17.543)*
- **`/portal/status/`** — wrapped in the portal's own `portal_required`, so it inherits the portal's rules exactly: PSA on, an active membership in a portal-enabled org, and no special treatment for superusers. A page scoped to the user's own client wins over a broadcast one. *(shipped v3.17.543)*
- **A public page is not silently reused in the portal.** The two have different audiences and an operator may deliberately publish less on the anonymous one, so a portal page must be marked as such rather than inferred. *(shipped v3.17.543)*

✅ **Phase 40 complete at v3.17.543.** Shipped across five sub-phases (v3.17.538–543). The one correction worth carrying forward: the phase was written assuming uptime could be read from existing `WebsiteMonitor` history, and no such history existed — 40.1 built it, and uptime accrues from the v3.17.538 deploy rather than retroactively.

Dependencies: `monitoring/` app (uptime data — built in 40.1), `psa.Ticket` (incident history with new `is_status_page` flag).

**Goal:** Take the "is anything broken?" call volume out of the queue by giving clients somewhere to look first.

## Phase 41 — Compliance Frameworks & Recertification **(M)** [shipped — v3.17.444]

MSPs increasingly need to attest to PCI-DSS or HIPAA on behalf of their clients. Phase 39 (Compliance Evidence Packs) handles the evidence collection side; this phase adds the *workflow* side: opt an org into one or more frameworks, walk through a checklist of real controls, attest per-control with notes + evidence, generate a customer-ready PDF, and drive recertification on a configurable cadence.

Capabilities:
- **Framework catalog** — `ComplianceFramework` model with `ComplianceCategory` + `ComplianceCheckItem`. *(shipped v3.17.436)* Pre-seeded with PCI-DSS v4.0 (12 categories, 38 check items, real control numbers like `1.2.1`, `8.4.2`, `11.3.2`) *(shipped v3.17.437 — `python manage.py seed_pci_dss`)* and HIPAA Security Rule (3 safeguard categories, 33 check items, real CFR refs like `164.308(a)(1)(ii)(A)`) *(shipped v3.17.438 — `python manage.py seed_hipaa`)*.
- **Per-org enrollment** — `OrganizationCompliance`. One org can be enrolled in multiple frameworks. Tracks `recertification_interval_days` (30 / 60 / 90 / 180 / 365), `recertification_emails_enabled`, `notify_email`. *(shipped v3.17.439 — dashboard at `/compliance/organizations/<org_id>/` + Enroll button)*
- **Per-control attestation UI** — checklist grouped by category, status dropdown (compliant / partial / non-compliant / N-A / unanswered), notes textarea, evidence URL. Color-coded by status. Every change audit-logged with `Status: <old> -> <new>`. *(shipped v3.17.440)*
- **Customer-facing PDF report** — exec summary + KPI grid + per-category table with each control's status, notes, evidence link. Audit-logged on every download. *(shipped v3.17.441 — `/compliance/.../report.pdf` using Phase 19's `reports.pdf_export.render_pdf`)*
- **Recertification reminder cron** — `python manage.py send_compliance_recertifications`. Idempotent + 7-day dedup. Resolves recipient via `notify_email` → first owner/admin Membership → `DEFAULT_FROM_EMAIL`. `--dry-run` for testing. *(shipped v3.17.442)*
- **Toggle UI + Mark Recertified Now button** — settings card on the checklist page lets org admins flip email reminders, change interval (30/60/90/180/365 days), set notify_email override, and stamp `last_recertified_at = now()` after a quarterly review. *(shipped v3.17.443)*

Dependencies: `accounts.Organization`, `audit.AuditLog`, `reports.pdf_export.render_pdf` (Phase 19).

**Goal:** Give the MSP one place to track every client's compliance state and one button to produce the report when an auditor asks for it.

**Operator setup:**
1. `python manage.py seed_pci_dss && python manage.py seed_hipaa` — populate the catalog (idempotent, safe to re-run after upgrades).
2. Add to crontab for daily recertification reminders:
   ```
   0 9 * * * cd /home/administrator && /home/administrator/venv/bin/python manage.py send_compliance_recertifications
   ```
3. For each client org needing compliance: `/compliance/organizations/<org_id>/` → click **Enroll** on the framework → walk the checklist.

---

## Phase 42 — First-class Docker / containerized deployment **(S · packaging)** [shipped — v3.17.490]

Self-hosted MSPs should be able to `git clone && docker compose up -d` and have a running install in under a minute — without the existing `bash install.sh` path going away.

- Multi-stage `Dockerfile` (Python 3.12 slim + venv) running as non-root `clientst0r` (uid 1000) *(shipped v3.17.490)*
- `docker-compose.yml` with `app` + `db` (MariaDB 10.11) as defaults; optional Nginx (`--profile proxy`) and Redis (`--profile cache`) services *(shipped v3.17.490)*
- `docker-compose.dev.yml` override — source bind-mount + gunicorn `--reload` + SQLite default for fast iteration *(shipped v3.17.490)*
- `docker-entrypoint.sh` — DB readiness wait, migrate, collectstatic, optional `DJANGO_SUPERUSER_*` bootstrap *(shipped v3.17.490)*
- Dedicated `/health/` endpoint for HEALTHCHECK *(shipped v3.17.490)*
- GitHub Actions workflow (`docker-image.yml`) — builds on PR, publishes `ghcr.io/agit8or1/clientst0r:latest` + semver tags on push to `main` / `v*` *(shipped v3.17.490)*
- `Makefile` with `docker-up` / `docker-logs` / `docker-shell` / `backup` / `restore` targets *(shipped v3.17.490)*
- `.env.example` covering every supported variable + `docs/docker.md` with backup, upgrade, profile, dev-mode, troubleshooting sections *(shipped v3.17.490)*

---

## Phase 43 — Multi-Organization REST API Access **(S · integrations)** [shipped — v3.17.496]

The public REST API (`/api/`) was single-tenant per request: an API key was bound to one organization and every endpoint filtered to that org alone. MSPs building a single-pane-of-glass need one connection that reads/writes across many client organizations. This phase broadens the API to multi-client without breaking any existing single-org integration.

- **Per-key organization scope** — new `APIKey.scope` field (`single` / `descendants` / `all`), default `single` so every existing key is unchanged. `descendants` covers the home org + its sub-locations (Phase 18 hierarchy); `all` covers every organization the key's owner can access *(shipped v3.17.496)*
- **`?organization=<id|slug|all>` request parameter** — narrow a multi-org key to one client, or fan out to all. Cross-org requests are refused with 403; a `single` key can never address another org *(shipped v3.17.496)*
- **Organization surfaced on every resource** — `organization` + `organization_name` on assets, contacts, documents, and passwords so a consumer can group rows by client; writable on create to target a specific client *(shipped v3.17.496)*
- **`/api/organizations/` returns the full accessible client set** for discovery before iterating *(shipped v3.17.496)*
- **Scope-bounded by live permissions** — a key never grants access beyond what its owner currently has; password reveal / OTP audit rows are logged against the row's own organization for full multi-client traceability *(shipped v3.17.496)*
- Contract documented in `docs/api-multi-org.md` *(shipped v3.17.496)*

---

## Phase 44 — Full Two-Way Accounting Sync **(L)** [shipped — v3.17.531]

**Roadmap item:** requested in GitHub #145. Extends Phase 27, which delivered reconciliation *reporting* plus a one-directional invoice push. What ships today is the push half: OAuth with encrypted tokens and automatic refresh, invoice push with GL-account and tax capture, multi-book routing, and a full audit log of every provider call. What does not exist is a genuine pull.

Delivered as four sub-phases, all released together in v3.17.531:

### Sub-phase 44.1 — Customer mapping as a first-class record *(shipped v3.17.531)*

- New `integrations.AccountingCustomerLink`. The organization → provider-customer map had been a dict inside the connection's encrypted credentials blob: invisible to queries, absent from the admin, and destroyed by a credentials reset — which would silently orphan every mapping and make the next push create duplicate customers. Two unique constraints now hold the invariants: one client maps to at most one customer per connection, and one provider customer is claimed by at most one client, so a mapping cannot fork and two clients cannot quietly share a customer.
- Data migration lifts existing mappings across, covering both QuickBooks Online's `customer_map` and Xero's `contact_map`. The blob copy is deliberately left in place so a rollback still works.
- **Customer push now sends the whole record** — company name, billing address, email, phone, website, contact name — instead of the bare `DisplayName` that was all the previous code ever sent, leaving somebody to retype the rest provider-side. Updates carry QuickBooks' `SyncToken`, so an edit made in the accounting system since the last read surfaces as a conflict rather than being silently overwritten.
- **Customer pull** links provider customers to organizations by name. It deliberately does *not* create organizations: inventing tenants from an accounting system is not a decision a sync job should make. Unmatched names are reported individually, since a count gives an operator nothing to act on.
- Customer-mapping page per connection, showing what is linked, what is not, and a pull action.

### Sub-phase 44.2 — Real invoice and payment pull *(shipped v3.17.531)*

- **Provider payment records are read directly**, with the invoices each settles taken from `LinkedTxn`. The previous implementation never looked at a payment: it polled an invoice's balance and, on zero, synthesised a local payment for the whole outstanding amount dated today with method `other`.
- **Partial payments work.** They were previously invisible — a non-zero balance was skipped outright — so `Invoice.status = 'partial'` was unreachable from the provider side despite being a documented status.
- **Payments are idempotent**, keyed on the provider's own payment id via a new unique constraint on `psa.Payment`, so a re-run updates rather than double-counts.
- **Voids reopen the invoice.** This needed a fix to `Invoice.recompute_totals()`, which was one-way: an invoice could reach Paid but never leave it, so a payment voided in the accounting system left it reading Paid with nothing against it.
- **Invoice state reconciliation** catches an invoice voided provider-side. One deleted provider-side is flagged rather than voided locally — deleting revenue records on the strength of a single 404 is not a call a sync job gets to make.

### Sub-phase 44.3 — Scheduling and on-demand sync *(shipped v3.17.531)*

- New `accounting_sync` management command running customers, payments and invoice state in one pass. One stage failing does not abandon the others — a customer-pull outage should not also stop payments importing.
- **`deploy/clientst0r-accounting-sync.{service,timer}`** — the timer the roadmap had claimed since v3.17.280 without one existing.
- `accounting_sync` registered as a scheduler task type for installs running the in-app scheduler rather than systemd; both paths call the same command.
- **Sync Now** on the accounting connections page, matching the RMM and PSA pages.
- `AccountingConnection.last_sync_at` / `last_sync_status` / `last_error` are finally written. They had existed since the model was created and were never set, so the UI rendered "Never" no matter how often a sync ran.
- `accounting_sync_payments` is superseded but still works for anyone who scripted it.

### Sub-phase 44.4 — Retry, backoff and audit gaps *(shipped v3.17.531)*

- Exponential backoff with jitter, `Retry-After` honoured on 429, and one forced token refresh on a 401 — an access token expiring mid-run no longer means a human re-authorising something the code can fix itself.
- **Retry is method-aware, and this is the important part.** A 5xx or a timeout on a `POST /invoice` does not say whether the invoice was created, and the provider offers no idempotency key — so replaying it risks putting a second invoice in front of a client, the exact failure the v3.17.526 push guard exists to prevent. Writes therefore retry only on 429, where the request was provably rejected before processing. Reads retry everything transient, since replaying a GET costs nothing.
- `poll_balance`, `push_customer`, `pull_customers`, `pull_payments` and `pull_invoices` registered in `AccountingAuditLog.ACTION_CHOICES`. `poll_balance` had been written since v3.17.280 without a label, so those rows rendered blank.

Still deferred: products/services, tax codes and payment terms, as scoped below.

Suggested MVP, matching the request: customers, invoices and payments, with the accounting system remaining the system of record for money and Client St0r remaining the operational platform. Products/services, tax codes and payment terms come later.

Dependencies: Phase 27 (reconciliation reporting + audit log) and the existing `AccountingConnection` OAuth pattern. The PSA and RMM sync jobs are the closest in-repo model for scheduled bidirectional pulls — there is no existing two-way accounting sync to copy from; Xero is push-only in exactly the same shape as QBO.

## Phase 45 — System-wide Appearance Controls **(S)** [shipped — v3.17.527]

**Starting background (v3.17.551, softened in v3.17.552):** a new profile starts on the **Navy Space** preset (`UserProfile.background_mode='preset'`, `preset_background='abstract-12'`) and every control stays the user's to change. The system-wide `background_policy` remains `'user'`: enforcing a house style would grey out everybody's own background controls, which is a decision an admin should make deliberately rather than inherit from an install default. Should an admin switch the policy to colour, the preset it lands on is the same Navy Space, so the two layers agree. Existing profiles and installs are untouched — a Django field default applies only to a row that does not exist yet.

**Roadmap item:** give administrators a say in how the app looks, without taking the choice away from users by default.

The page background was entirely per-user: each person picked a mode on their profile and that was that. An MSP wanting a consistent look across a team — or simply wanting to put their own image behind the app — had no way to set one.

- **Background policy in General Settings** *(shipped v3.17.527)* — four modes: **user controlled** (the previous behaviour, and still the default so upgrades change nothing), **static image** (one uploaded image for everyone), **colour or pattern** (a solid hex colour or one of the twelve preset gradients), and **random images** (a different image each page load).
- **Enforcement is honest about itself** *(shipped v3.17.527)* — when a policy is active the profile page keeps its background controls visible but disabled, under a banner naming the policy. Hiding them relocates the confusion rather than removing it. A user's own settings are preserved while a policy is in force and apply again if it is lifted.
- **Preset table consolidated** *(shipped v3.17.527)* — the twelve abstract backgrounds had been defined twice, labels on the profile model and URLs in a context processor, with nothing keeping the two in step; a key present in one and missing from the other would have shown up only as a silently absent background. Now one table in `core/backgrounds.py` feeds all three consumers.

Note the two background settings are unrelated: this one is the app page backdrop, while the GeoIP map backdrop (v3.17.522) styles the world map on the firewall and vault access-rule screens.

Dependencies: `SystemSetting` singleton + the existing per-user profile background fields.

## Phase 46 — Job Kit: tools and materials on a ticket **(M)** [shipped — v3.17.533]

**Roadmap item:** a tech should know what to load before leaving, without phoning the office.

A scheduled job already links a ticket to a calendar entry (`Ticket.related_calendar_event` ↔ `ScheduledTask.psa_ticket`). What was missing was any record of *what the job needs*.

- **Tool catalogue** *(shipped v3.17.533)* — new `inventory.Tool`, deliberately separate from `InventoryItem`. A consumable is spent and its quantity drops; a tool goes out and comes back, and the question its record answers is "where is it", not "how many are left". Modelling both as stock would mean either lying about quantities or explaining why the cable tester's count never moves. Tracks code, category, home shelf or assigned van, condition, and a retire flag that keeps a tool off pick-lists without breaking history.
- **Kit list on the ticket** *(shipped v3.17.533)* — one flat list covering tools, inventory items and free-text "other" lines, because that is how it is read: a tech looks at one list before leaving, not three. Attached to the ticket rather than the visit so it survives rescheduling and appears wherever the ticket does.
- **Stock shortfall warning** *(shipped v3.17.533)* — a line asking for eight of something with three in stock is flagged. Sending a tech out for parts that are not there is the failure this list exists to prevent.
- **Pack-off** *(shipped v3.17.533)* — each line ticks off while loading, recording who and when.
- Lines keep their own copy of the item name: the foreign keys are `SET_NULL`, and a packing list that empties itself because somebody retired a tool is worse than a stale label.

Dependencies: `inventory` app, `psa.Ticket`.

## Phase 48 — Task warning windows **(S)** [shipped — v3.17.535]

**Roadmap item:** a task should warn you before it is due, in a unit that suits it, on the screens you already watch.

`ScheduledTask.alert_before_hours` and `check_scheduled_task_alerts` already existed and are unchanged. This closes the two gaps around them.

- **Lead time in hours or days** *(shipped v3.17.535)* — the form takes a number plus a unit. Hours stay canonical so alerting is unaffected; the unit records how it was entered, so a 7-day lead reads back as "7 days" rather than "168 hours", including on the next occurrence of a recurring task.
- **The warning is visible** *(shipped v3.17.535)* — a task inside its window is flagged on the calendar, the task list, the dashboard Schedule panel, the public wallboard and its own detail page. Alerting had been email/SMS only, so a task creeping up was invisible on the screens people actually watch.
- Overdue suppresses the warning rather than stacking with it, and a lead of 0 means "do not warn" rather than "warn always".

Dependencies: `scheduling.ScheduledTask`; surfaces through the Phase 47 wallboard and the v3.17.524 dashboard panel.

## Phase 47 — Public scheduler wallboard **(S)** [shipped — v3.17.533]

**Roadmap item:** a schedule on the workshop wall. Extends the wallboard idea from Phase 3.6 (v3.17.146 / v3.17.211), which is authenticated and reporting-oriented.

- **System-wide, not per-client** *(shipped v3.17.533)* — in this platform an Organization *is* a client, so a per-org board would show one client's jobs. A workshop screen needs the whole day across every client.
- **Public URL, off by default** *(shipped v3.17.533)* — a wall-mounted screen has no keyboard and nobody wants to sign a display in each morning. That makes the URL the only control, so: the board ships disabled; a disabled or unknown token returns **404 rather than 403**, since a 403 would confirm a board exists at that address; the address carries a 43-character `secrets` token rather than an id, so boards cannot be enumerated; and the token can be rotated to kill a leaked link instantly.
- **Disclosure is opt-in per field** *(shipped v3.17.533)* — client names, technician names and ticket numbers toggle separately. Client names are usually the most sensitive thing on a schedule, and the board stays useful without them.
- Served `no-store` and `noindex`, and rendered standalone rather than through the authenticated base template.

Dependencies: `scheduling.ScheduledTask`.

## Phase 8 — Native mobile apps (iOS + Android) with GPS auto-time + Timeclock **(L · keystone)** [shipped — v3.17.417]

Reverses the earlier "PWA only" deferral. The combination of GPS auto-documentation + employee timeclock makes this a force-multiplier for billable-hours capture, not just a UX improvement.

Positioned last in the roadmap (v3.17.169) because it's the largest single undertaking and depends on a lot of other work being mature first — backend, scheduling, billing, and mobile app distribution all need to be in place before this phase pays off.

### Sub-phase 8.1 — Backend foundation *(shipped v3.17.397–410)*
- `TechnicianLocation` model — append-only GPS pings (lat/lon/accuracy/timestamp/source); retention policy + per-org enable flag. *(shipped v3.17.397)*
- `TimeclockEntry` model — clock-in / clock-out events with tech, organization, location, optional ticket, optional project, source (`'mobile'` / `'web'` / `'manual'`); derives a `TimeEntry` row on clock-out so existing billing rolls up unchanged. *(shipped v3.17.409)*
- `ClientSiteGeofence` model — per-client polygon or radius around their physical address(es). Used to auto-detect "tech is on site" for ticket time tracking. *(shipped v3.17.397)*
- REST API additions: `/api/v2/mobile/locations/`, `/api/v2/mobile/timeclock/`, `/api/v2/mobile/active-ticket/`. *(shipped v3.17.410 — endpoints live at `/api/mobile/v1/locations/`, `/api/mobile/v1/timeclock/clock-in/` + `/clock-out/` + `/me/`, and `/api/mobile/v1/active-ticket/`. Off-shift GPS suppression honors `WorkingHours` per Sub-phase 8.5.)*
- Token auth (long-lived per-device tokens stored in `MobileDevice` model with revoke-on-demand). *(API plan doc shipped v3.17.345; auth endpoints v3.17.346; dashboard + organizations v3.17.347; assets v3.17.348; tickets v3.17.349; KB endpoints — list / search / detail with raw markdown + rendered HTML — shipped v3.17.350; mobile-client login body field-name mismatch fixed v3.17.446 — was sending `email`, server reads `username`; dashboard endpoint shape aligned with `DashboardSummary` type — `recent_tickets` / `recent_assets` now arrays, `security` now an object — v3.17.448; vault list/detail/reveal endpoints with web-parity security — 30/hour throttle, per-credential approval gate, VaultAccessRule evaluation, audit logging — shipped v3.17.449. Mobile-side `monitoring/` and `security/` screens are slated for removal in a follow-up; their would-be endpoints were never built.)*

### Sub-phase 8.2 — GPS auto-documentation engine *(shipped v3.17.412; mobile foreground GPS at clock-in v3.17.452)*
- Background worker: every GPS ping with the tech "inside a client geofence" auto-starts a `TicketTimeEntry` against their currently-active ticket for that client (or creates a placeholder if no ticket open). *(shipped v3.17.412 — `python manage.py auto_document_field_visits`, cron every 1 min)*
- On exit-geofence event: stop the time entry, write the duration, optionally prompt the tech to confirm + add notes via push notification. *(shipped v3.17.412)*
- Selectable per-tech: **Always on** / **Ask first** / **Off**. Per-tech UserProfile flag. *(shipped v3.17.412 — `field_ops.AutoTimePreference`)*
- Audit log every auto-time event so disputed billing can be traced. *(shipped v3.17.412)*

### Sub-phase 8.3 — Timeclock feature *(shipped v3.17.413–414)*
- Web UI: Timeclock dashboard at `/timeclock/` for staff to view who's clocked in, total hours per pay period, exception flags (long shifts, missing clock-out). *(shipped v3.17.413 — `/field-ops/timeclock/`)*
- Mobile UI: prominent "Clock in / Clock out" button on the app home screen. Optional tie to the active ticket. *(shipped v3.17.414 — `mobile/app/timeclock/index.tsx` + dashboard widget)*
- Selectable per-org and per-tech: required vs optional, with vs without GPS context, separate from per-ticket time tracking.
- Payroll export — CSV per pay period, hooks for QuickBooks Time / Gusto / etc. (defer the integration; just structured export first). *(shipped v3.17.413)*

### Sub-phase 8.4 — App build *(shipped v3.17.354–360)*
- React Native (Expo SDK 51+ with EAS cloud build — revisits the earlier "no Expo accounts" rejection; required for store submission). *(read-heavy field-use slice complete: scaffold + auth v3.17.354; dashboard + orgs + assets v3.17.356; tickets + KB v3.17.357; vault + monitoring + security + settings v3.17.359; docs + EAS profiles + placeholder icons v3.17.360 — `mobile/` Expo TypeScript app. Phase 8 stays `[in progress]` because Sub-phase 8.2 (GPS auto-time) is still deferred. Local signed-AAB pipeline: targetSdk 35 v3.17.445; `expo-modules-core` Kotlin null-safety patch for `PackageInfo.requestedPermissions` (compileSdk 35 made it nullable) v3.17.446 — persisted via `patch-package`. Public `/privacy-policy/` route + Play Console Data Safety / store-listing prefill docs v3.17.447. Mobile cleanup pass v3.17.451 — removed `monitoring/` and `security/` screens (never had server endpoints), profile is now read-only sourced from `/auth/me/`, assets + vault lists grouped by organization with section headers. Asset detail full-info + Vault linkage + closed-tickets filter fix v3.17.476 — asset detail screen now renders the whole record across Identity / Hardware / Lifecycle / Notes / Metadata cards plus a "Stored secrets" section listing every Vault entry linked via `PasswordRelation`; the Mine and Critical ticket chips now also constrain to `status=open` so closed-but-critical / closed-but-mine tickets don't sneak through. Mobile ticket-flow + permissions follow-up v3.17.477 — new-ticket form now has a real searchable client picker (required), ticket detail surfaces an Assignee card with Claim / Reassign / Clear actions (Reassign gated on the new `tickets_assign` role-template flag), dashboard collapsed to a three-tile row of Critical / Open (New) / Open, and `GET /vehicles/` now returns the whole active fleet for any authenticated user since the service-vehicle pool isn't multi-tenant. Dashboard 7-day agenda strip v3.17.478 — new **Upcoming** card mixes ScheduledTask assignments and tickets (`resolution_due_at`) per day, with the same items folded into the full `/dispatch/calendar` month page; backend gains `GET /dispatch/upcoming/` and extends `/dispatch/calendar/` to emit both kinds with a `kind` discriminator. Vault edits + ticket billing + schedule-on-calendar v3.17.479 — mobile vault is no longer read-only (create/edit/rotate gated on `vault_create`/`vault_edit`), ticket detail surfaces a Billing rollup card with total/billable/non-billable minutes plus a contract progress bar for block-hours clients, and the calendar gains a "Schedule on this day" action that drops a new ScheduledTask onto the picked day. Backend gains POST/PATCH on `/vault/`, POST on `/dispatch/tasks/`, and `resolution_due_at` on the ticket PATCH so tickets can be scheduled too. Mobile asset editing + vault linking *(partial — backend shipped v3.17.480; app screens shipped v3.17.536)* — v3.17.480 added PATCH on `/assets/<id>/` and POST/DELETE on `/assets/<id>/vault-links/`, both rejecting cross-org link attempts, but the matching app screens were never written and this entry previously described them as shipped. v3.17.536 wrote them: asset detail gains an Edit form covering identity / hardware / OS / notes (gated on `assets_edit`), a "+ Link vault entry" picker scoped to the asset's organization, and an Unlink action per linked secret. Mobile public-beta release prep v3.17.481 — new `/beta-onboarding/` public page (Django view + template rendering `docs/BETA_ONBOARDING.md`), full Play Store walkthrough doc at `docs/PLAY_STORE_BETA.md`, updated listing + Data Safety drafts, mobile-side Sentry hook + Beta banner + permission allowlist (drops `RECORD_AUDIO` / `SYSTEM_ALERT_WINDOW` / legacy storage perms). Local AAB build blocked on an `expo-modules-core@1.12.26` Gradle publishing-config issue; three resolution paths documented. Mobile projects + config backups v3.17.558 — the field-relevant slice of Phases 34 and 35 reaches the app: a Projects tile (my work / open / all, task list with blocked-by reasons, tick tasks off, hours budget) and a Config Backups tile (network devices, snapshot history, read a stored config, and Capture-now which runs the *server-side* collector so the phone never holds a device credential). Money is deliberately absent from both — margin, revenue and billing stay on the web, and a test asserts none of it appears in the mobile payload. Mobile asset filters + the missing edit/link screens v3.17.536 — the Assets list "Type" box sent `asset_type` while the server read `type`, and its "Status" box was never implemented at all; both now work, with status and location read from `custom_fields` the same way the web asset list reads them. Asset detail additionally returns the full `custom_fields` map, `tags` and `created_by_name`, and finally gained the Edit form and vault link/unlink UI that v3.17.480's backend had been waiting on.)*
- Auth: Azure SSO + email/password fallback; session-token cookie not used (mobile uses long-lived bearer).
- Screens: Dashboard / My Tickets / Active Ticket / Clock In-Out / Map / Settings.
- Background location: foreground-only by default, opt-in for background; iOS "Always" permission requested only for techs who enable Always-on auto-time.
- Push notifications via FCM/APNS for ticket assignment, clock-in reminders, geofence exit prompts.

### Sub-phase 8.5 — Privacy + safeguards *(shipped v3.17.411–416)*
- **Off-shift suppression**: GPS pings outside the tech's `WorkingHours` (Phase 2) are dropped at the API layer — never stored. *(shipped v3.17.410 — 204 + audit-log `locations_dropped_offshift`)*
- Per-tech UI to view + delete their own location history. *(shipped v3.17.415 — `/field-ops/my-location-history/`)*
- Org-admin retention policy (default: 90 days). *(model + prune mgmt cmd shipped v3.17.411; org-admin UI shipped v3.17.416 — `/field-ops/settings/`)*
- Geofence-only mode: store only "entered/exited geofence X at time T", never raw lat/lon. *(shipped v3.17.415 — `OrganizationFieldOpsSettings.geofence_only_mode` + `GeofenceVisit` model + locations endpoint integration)*
- Audit trail of every location-history view + export. *(shipped v3.17.415–416 — every view, delete, geofence-only write, and settings change emits an `AuditLog` row)*

**Dependencies:** Phase 2 (`WorkingHours` for off-shift suppression). Recommended before Phase 3 (so timeclock data flows into utilization reporting).

**Sizing:** **L** — backend foundation 2 weeks, auto-time engine 2 weeks, timeclock UI 1-2 weeks, mobile app build 4-6 weeks, privacy hardening 1 week. ~10-13 weeks total. Sub-phase 8.1 is the first concrete deliverable and is a useful release on its own (web-only timeclock + GPS API endpoints) even before any mobile app ships.

---

## Phase 49 — Interface consistency and tenant-boundary hardening **(M · quality)** [complete]

Two strands of work that aren't features but that everything else sits on: a
single shared interface scale, and an audit of the places where a record is
fetched by id without checking which tenant it belongs to.

### Sub-phase 49.1 — Shared UI layer *(shipped v3.17.559)*
- `static/css/ui.css` — one set of scale tokens (type, control height, row
  height, spacing, radius) layered over the existing theme variables, loaded
  last so it reads `--surface` / `--border-color` / `--text-primary` from
  whichever of the twelve themes is active. No theme was replaced.
- Removed the global shrink: `custom.css` had been setting `html` to 14.5px and
  `body` to 0.92rem, which scaled the whole application down rather than sizing
  its parts. Sizes are now stated once, in pixels.
- Application header: the navigation needs ~1855px of content and the target
  viewport is 1440px. Rather than let it wrap into stacked rows, a measured trim
  window between 1400px and 1750px drops the clock, the nav-link icons and some
  padding. Nothing is removed from the menu.
- Page headers, filter bars, tables, badges, empty states and dashboard tiles
  standardised against the tokens. Verified with no horizontal page overflow at
  1440×900, 1920×1080, 1024×768 and 390px.
- Ticket lists no longer infer urgency from a priority's code string. New
  `psa_ui` template filters rank `TicketPriority` by its configured
  `sort_order`, and derive a status's tone from `is_terminal` / `pauses_sla`.
  Neither model carries a colour field, so nothing is read from one.

### Sub-phase 49.2 — Tenant-boundary audit *(complete — first pass v3.17.559, closed out v3.17.581)*
- `core/tenancy.py` — `accessible_org_ids(request)`, `scope_to_request()` and
  `get_scoped_object_or_404()`. The last raises `Http404` rather than
  `PermissionDenied` on purpose: a 403 confirms the record exists somewhere.
- Fixed four views that reached across tenants by id: holiday list / edit /
  delete in `resourcing`, and the AI workflow-suggestion list and decide views
  in `psa`. `HolidayForm` now narrows its organization choices *and*
  re-validates the submitted value, since a narrowed `<select>` is a UI
  affordance and not a control.
- Fixed the mobile clock-in endpoint, which built a `TimeclockEntry` straight
  from four client-supplied foreign keys. This matters past the record itself:
  `TimeclockEntry` carries `derived_time_entry`, so a clock-in can become a
  billable time entry against whichever organization it names.
- **Root cause, still open:** `user_has_perm()` returns True when a role
  template sets a flag on *any* active membership. It answers "may this user do
  this kind of thing", not "may they do it to this record". Views that call it
  and then fetch by id are the shape to keep looking for.
- Covered by `core/tests/test_cross_tenant_views.py` (11) and
  `api_mobile/tests_timeclock_scoping.py` (4), alongside the existing
  `core/tests/test_tenant_isolation.py` (10).
- Backup and restore *(shipped v3.17.560)* — `manage.py backup` defaulted to an
  unencrypted database dump in `/tmp` at 0755; encryption is now on by default,
  the destination moved off `/tmp`, and both directory and archive are
  permission-restricted. Backup and restore also handled the master key
  differently from the vault, so an unpadded key worked throughout the
  application and failed at restore; both now share
  `vault.encryption.get_fernet()`, and existing archives still decrypt.
- **Known and deferred:** RMM and integration credentials use the v1 encryption
  layer (no AAD context binding, no version tag), while vault passwords use v2
  (both). Re-encrypting live credentials is a migration and needs its own
  release with a rollback path. No key rotation command exists.
- Billing arithmetic *(partial — tax shipped v3.17.561)* — `is_taxable` was
  stored on every invoice and quote line and read by no tax calculation, so
  invoices mixing taxable goods with non-taxable labour or reimbursed expenses
  overcharged the customer, and partial credit memos were worth more than the
  credit requested. Tax now accumulates over taxable lines only and rounds
  half-up rather than banker's. Issued invoices are not restated; the new
  read-only `manage.py psa_tax_audit` reports which are affected and by how
  much, per client.
- Update progress reporting *(shipped v3.17.562)* — the progress file was
  written non-atomically and the reload that ends an update killed the writer
  mid-write, leaving unparseable JSON that `get_progress` reported as `idle`.
  The front-end could not distinguish that from "no update running" and sat on
  the last step forever, while the update had in fact succeeded. Writes are now
  atomic, logs bounded, and an unreadable file reports `unknown` so the page
  says so and re-checks the running version.
- SLA calculation *(shipped v3.17.563)* — the breach flags the SLA report and
  KPI read were never written by any code, so both reported zero while the
  ticket badge computed the truth live; and pausing the clock never moved the
  deadline, despite the module docstring saying it did, so a ticket waiting on
  a client breached through no fault of the technician. Breach state is now
  persisted on save and on the five-minute tick, and pause time is accumulated
  and credited back to both due-dates on resume.
- Invoice duplicate prevention *(shipped v3.17.564)* — the recurring generator
  relied on advancing a cursor after writing the invoice, with no transaction
  around the pair, so an interrupted run re-billed the period next day and a
  manual re-run duplicated outright. Now a unique constraint per contract and
  period, an application guard that returns the existing invoice, and an atomic
  cursor advance.
- Background job failure handling *(shipped v3.17.565)* — `ScheduledTask` took
  its run lock by writing `last_status='running'` and nothing in the codebase
  ever cleared it except the same process on its way out. A reboot or an OOM
  kill between those two writes left the row at `running` permanently and
  `should_run()` returned False permanently after, so the task went off the
  schedule silently with no recovery short of editing the database. A claim now
  expires after six hours and is taken with a conditional UPDATE, which also
  stops two overlapping scheduler runs from executing the same task twice.
- Expiry notifications *(shipped v3.17.566)* — the SSL and domain expiry
  scheduled tasks both ended at a `# TODO: Send email notifications`, so two
  checks enabled by default reported a healthy green result daily while sending
  nothing. Both now send, per organization. Three narrower faults went with it:
  already-expired items were excluded from the query, per-item warning windows
  and per-monitor opt-outs were ignored, and domain checking read only manually
  entered rows. Re-notification is keyed on the expiry date, so a renewal
  re-arms the warning. Also fixed the vault password expiry recipient query,
  which named a reverse accessor no model defines and could only have raised
  FieldError on its first real send. Shared plumbing now lives in
  `core/mailer.py`.
- PSA ticket notes *(shipped v3.17.567)* — the workflow completion note posted
  to a linked PSA ticket decrypted the connection's credentials with the wrong
  scheme, so every provider branch failed on its first line and no note had ever
  reached a PSA. The caller discarded the result and logged "updated PSA ticket
  X" regardless, so the audit trail asserted a note had landed every time. Note
  posting now goes through the provider layer — which carries each vendor's
  auth, retries and the base-URL validation the manager's own requests skipped —
  Autotask and HaloPSA notes are implemented rather than stubs, and a failure is
  recorded and shown to the tech instead of being swallowed.
- Dashboard widget scoping *(shipped v3.17.568)* — every dashboard and
  wallboard widget aggregated across every client and checked no permission
  beyond `reports_view_dashboards`, which each role carries by default. A
  read-only member of one client could open a shared board and read the MSP's
  revenue and its other clients' names — data the report pages showing the same
  numbers refuse them. Each data source now declares the permission it needs
  and how it scopes; a viewer sees their own clients' figures, MSP staff still
  see everything, and a source with no client to scope by is shown only to
  someone entitled to every client.
- AI gating + spend controls *(shipped v3.17.569)* — `AIAbuseControlMiddleware`
  matched two hand-typed path prefixes, neither of which is a route this
  project has, so it fell through on every request: no rate cap, no spend cap,
  nothing recorded, on any AI endpoint. It also read an org attribute nothing
  sets, and its spend keys were read but never written. Matching is now by
  resolved URL name over every endpoint that reaches a provider. Separately,
  six endpoints — the documentation assistant's four, asset AI documentation
  and floor-plan generation — never consulted the `psa_ai_enabled` master
  switch, so turning AI off left them generating and spending; all six now
  read it through one shared gate.
- Search scoping *(shipped v3.17.570)* — global search filtered a bare
  `organization=org` on all six content types instead of going through
  `for_organization()` like the list pages, so it ignored the Phase 18
  organization hierarchy (a parent org got no hits for its subsidiaries' rows)
  and returned nothing at all in global view (`organization=None` matches no
  row). Both were under-returns, so neither was ever reported — a search
  saying "no results" looks like the thing not existing. Results now also name
  their owning org, since a result set can span organizations.
- Organization hierarchy in detail views *(shipped v3.17.571)* — the list
  pages include descendant orgs via `for_organization()`, which is what
  `Organization.parent` documents, but the detail, edit and delete views they
  link to looked rows up with a bare `organization=org`. A parent org's asset
  list showed a subsidiary's server and the link 404'd; the same split ran
  through passwords, contacts, inventory, scheduled tasks, documents and the
  integration connections — 78 lookups in nine modules. All now go through a
  new `core.tenancy.get_org_object_or_404` (current org + descendants, not the
  wider membership rule PSA uses). Models whose lists are strict keep strict
  detail scoping.
- AI abuse middleware hotfix *(shipped v3.17.572)* — v3.17.569 made the
  middleware match real endpoints for the first time, which activated a 401 it
  had always carried but never executed. `api_mobile` resolves its
  `Authorization: Token` header inside the view, so `request.user` is anonymous
  at middleware level and every token-authenticated AI call — the mobile
  receipt scanner among them — was refused before its view ran. The middleware
  caps usage and no longer authenticates.
- Export scoping + the data export itself *(shipped v3.17.573)* — all three
  export serializers read fields their models do not have (`asset.location`,
  `asset.status`, `doc.content`, `pwd.password_encrypted`), so Assets,
  Documents, Passwords and All had only ever downloaded
  `{"success": false}` at HTTP 200; only Contacts worked. The export also
  ignored the organization selector, and offering passwords in the Hudu / IT
  Glue formats produced a file with no passwords in it. The KB list, its
  category/tag filters and `document_export_bulk` now include descendant orgs
  like the detail pages do, so a departing parent company's archive stops
  omitting its subsidiaries' documentation.
- Vault export permission *(shipped v3.17.574)* — `vault_export` is on every
  role template, is a checkbox in the role editor and appears in the role list,
  and nothing checks it: there is no bulk password export in the product. It is
  now labelled unimplemented in both places rather than advertising a
  capability that does not exist. The export itself was deliberately not built
  — decrypting every credential in an organization into a file needs
  master-key handling, per-record audit and an approval path, which is a
  feature to design rather than something to add while fixing adjacent bugs.
- AI data access *(shipped v3.17.575)* — receipt scanning in the web UI built
  its own Anthropic client from `ANTHROPIC_API_KEY` while the mobile app went
  through the configured provider, so an install running Ollama for data
  residency still sent every receipt image off-network. It now routes through
  `LLMProvider.extract_receipt_fields` like the mobile scanner does. The PSA AI
  context builder was already org-scoped and withholds internal notes; the
  floor-plan generator followed in v3.17.576, and a test now parses every
  module and fails if any AI feature builds its own provider client again.
- Billing arithmetic — credit memos *(shipped v3.17.577)* — `get_psa_balance`
  skipped every non-positive invoice balance, and a credit memo is an invoice
  with negated lines, so credit memos reduced nothing. A $500 memo against a
  $2,000 invoice left both the client account page and the aging report showing
  $2,000 due. Credit memos and overpaid invoices now net off the balance, and
  the aging report stops dropping clients whose only balance is a credit.
- Billing arithmetic — late fees on credited invoices *(shipped v3.17.578)* —
  a credit memo leaves the credited invoice's `amount_paid` and `status`
  untouched, so the late-fee cron read the full balance and charged a
  percentage of money the customer no longer owed; an invoice credited in full
  still drew a fee on the whole original amount. Fees now use
  `Invoice.net_balance_due`.
- Late-fee audit command *(shipped v3.17.579)* — `psa_audit_late_fees`
  reports fees already charged on amounts a credit memo had credited back,
  reconstructing each fee's working from the description the cron recorded and
  counting only credits that existed when the fee was raised. Read-only, like
  `psa_tax_audit`; the correction stays a decision for the operator.
- Navbar overflow + contract billing stamp *(shipped v3.17.580)* — ten
  top-level menus plus the search box, org pill and user menu did not fit the
  bar; Security, CRM and Reports became headed sections of one More menu, with
  their feature flags intact and every destination tested to still render.
  Separately, `Contract.generate_invoice()` now stamps its own
  `last_billed_at` rather than relying on its single caller to do it.
- Expired contracts kept billing *(shipped v3.17.581)* — the recurring-invoice
  cron filtered on `status='active'` and never read `end_date`, and nothing
  ever set a contract to `expired`, so a client who did not renew was invoiced
  every month forever while `Contract.for_ticket` had already stopped covering
  their tickets. The invoice cron now respects `end_date` and the lifecycle
  cron expires ended contracts, so billing and coverage agree.
**Decisions taken, so they read as choices rather than gaps:**

- **The remaining hand-rolled `filter(organization=org)` sites stay strict.**
  About 170 of them survive the v3.17.571 sweep, and they divide into two
  groups. Some are correctly strict by nature — creating a row, checking slug
  uniqueness within an organization, looking up a membership — and widening
  them would be a bug, not a fix. The rest are per-organization *configuration*
  rather than client records: tags, document categories, API keys, webhooks,
  audit logs. Those have strict lists **and** strict detail views, so unlike
  the 78 lookups fixed in v3.17.571 there is no broken link to repair. Whether
  a parent organization should administer a subsidiary's API keys and webhooks
  is a product decision rather than a defect, and the answer taken here is no:
  seeing a subsidiary's assets is a roll-up, holding its credentials is not.
- **Contracts ending mid-period bill the full period.** Proration applies to a
  mid-period start only. This is left as-is deliberately: whether a customer
  who cancels on the 10th owes the whole month is a commercial term, not an
  arithmetic error, and the software should not decide it. v3.17.581 fixed the
  part that *was* an error — billing continuing after the contract ended
  entirely.

- Bundled services lost on save *(shipped v3.17.584, issue #147)* — reported
  by @roccordx, who traced it to the editor binding its submit handler with
  `document.querySelector('form')`, which returns the document's first form —
  the navbar search box, since `base.html` renders the navbar before the
  content block. `bundle_items_json` posted empty every time. Worse than it
  looked: the view deletes rows absent from the submitted JSON, so an empty
  field deleted every existing bundle item on any save, including ones
  `psa_auto_renew_contracts` had copied onto a renewal. The view now separates
  a missing field from an empty list, and a test scans every template for the
  pattern — which also turned up the same bug in `core/settings_ai.html`.
- Utility controls back on the toolbar *(shipped v3.17.585)* — Beta app,
  Install app and Support this project were behind an ellipsis dropdown
  between the star and the search box; v3.17.580 freed the room, so they are
  individual buttons again with accessible names, tooltips and focus styling.
  Verified in a browser at seven widths: single row on the bar, labelled rows
  in the drawer below 1400, and navbar height unchanged from baseline at every
  width. Wrapping was tried and rejected by measurement — at 1536 it produced
  one control per row and a 345px navbar.
- **Sync status honesty** *(shipped v3.17.582)* — `PSASync` and `RMMSync`
  wrote `last_sync_status = 'success'` however many records they had dropped,
  and the incremental cursor only advances after a success, so silently
  dropped records were never re-offered. A run with per-record errors now ends
  `partial`, which both tells the operator what was lost and makes the next
  run a full sync that retries it.

- **Scheduler failure reporting** *(shipped v3.17.583)* — nine `run_*` methods
  in `run_scheduler` caught their own exceptions and wrote them to stdout, so
  the task was marked completed successfully and the Scheduled Tasks page
  showed a green tick for a job that failed every night. The outer loop
  already recorded failures correctly; the guards only hid the outcome.

- **SSRF in property URL import** *(shipped v3.17.587)* — the location
  "Import from URL" endpoint fetched whatever URL it was given, following
  redirects, so a logged-in user could make the server request loopback,
  private networks or the cloud metadata address. User-supplied URLs now go
  through `core/safe_http.py`: public http(s) on 80/443 only, every resolved
  address checked at connect time (so DNS rebinding cannot swap the target),
  redirects re-checked hop by hop, and size and time caps on the response.
  The endpoint also now requires write access, and its errors no longer echo
  internal detail.
- **SSRF guard for integrations and monitors** *(shipped v3.17.588)* — the
  same connection-level guard now covers every PSA, RMM, accounting,
  distributor and network-controller integration and the website monitor,
  replacing a check-then-connect pattern that DNS rebinding could get past.
  Network controllers may reach the LAN by default; everything else needs
  `ALLOW_PRIVATE_IP_INTEGRATIONS`, and metadata endpoints are refused even
  with it.
- **Vehicle damage diagrams redrawn** *(shipped v3.17.589)* — all ten van
  and pickup views redrawn as recognisable work vehicles at one consistent
  scale, with every click area kept and the mirrored left/right on the
  front and top views corrected.
- **Vault permission scoping + trusted proxies** *(shipped v3.17.592, PR #148)*
  — secret reveal/OTP/QR checks the credential's own organization, policy
  failures refuse instead of releasing, and client addresses come only from
  trusted proxies (`TRUSTED_PROXY_CIDRS`; unix-socket nginx treated as
  local), closing an `X-Forwarded-For` spoof past the firewall and vault IP
  rules.

**Remaining:** nothing named. Both the sync paths and the scheduler have now
had a pass, and the recurring finding — code reporting success while doing
nothing — is recorded above.

**Sizing:** **M** — both sub-phases complete. 49.1 delivered the shared UI
layer; 49.2 worked through covered views, backup/restore, invoice tax, update
progress, SLA, invoice duplication, background job failure handling, expiry
notifications, PSA ticket notes, dashboard widget scoping, AI gating and spend
controls, search scoping, the organization hierarchy in detail views, the
abuse-middleware hotfix, the data export, the vault-export permission, AI data
access, credit memos, late fees, the navbar, and expired contracts.

The recurring finding across 49.2 is worth recording: most of what it caught
was code that reported success while doing nothing. Notes that never posted
but were logged as posted, an export that served its own error message as the
downloaded file with HTTP 200, spend caps guarding no endpoint, a search
returning empty rather than scoped, a permission gating nothing, and credits
that credited nothing. None of that produces a support ticket, which is why it
survived so long — and it is the argument for auditing quiet paths rather than
waiting for reports.

## Phase 50 — "Help Us Grow" call to action **(S · growth)** [shipped — v3.17.586]

The project has always had a Support modal behind a heart in the navbar. It
offered three links and asked for a GitHub star. The thing most likely to
actually help — one person telling another person about it — was the one thing
it did not make easy.

Phase 50 rebuilds that heart into a share-first call to action, and moves every
destination it points at into one configuration file so the same partial can be
reused across our other apps.

- **A visible entry point** *(shipped v3.17.586)* — the navbar heart is now a
  labelled pill, "Help Us Grow", with a two-beat pulse and a red glow. The beat
  lasts under a second in a four-and-a-half-second cycle, and
  `prefers-reduced-motion` turns the movement off while keeping the glow and
  the colour. It opens the modal on click and never by itself.
- **Sharing first** *(shipped v3.17.586)* — the first card in the modal, above
  the fold on a laptop, offers the native share sheet where the browser has one
  (`navigator.share`), a copyable link, a copyable ready-to-post message shown
  in an editable field so it can be read before it is sent, and LinkedIn,
  Facebook, X and email as fallbacks. Every one of them opens a draft the user
  sends themselves; nothing is posted on anyone's behalf.
- **The rest of what we build** *(shipped v3.17.586)* — MSP Reboot and MSPZero
  each get a Visit action and a separate Share and Copy link action, plus a
  ready-to-copy message for the network as a whole. Only this project is
  described as open source, because only this project's licence is ours to
  state.
- **GitHub, sponsorship and the business** *(shipped v3.17.586)* — a star
  button, the GitHub profile, the existing verified GitHub Sponsors link, and
  MSP Reboot with its Facebook page. The sponsorship card omits itself when no
  destination is configured rather than rendering an empty ask.
- **One place for the destinations** *(shipped v3.17.586)* —
  `config/support_links.py` holds the project, the network, GitHub, the sponsor
  link and the business, overridable per install through a `SUPPORT_LINKS`
  setting. The templates carry no URLs; a test fails if one appears in them.
  What gets shared is the public project URL, never the address of the running
  install.

**Open configuration:** `PROJECT.public_url` is currently the public
repository, because there is no ClientSt0r product site — see
`docs/github-about.md`. If one is stood up, that one value is the only edit
needed.

**Sizing:** **S** — one config module, two template partials, one stylesheet
section, one script, 45 tests. No migrations, no new dependencies, no new
views or URLs.

---
## What's explicitly NOT in this plan

- Multi-currency beyond per-record `currency` field
- Multi-language support beyond Django i18n hooks
- ~~Native mobile apps (PWA only — per memory)~~ → **moved into Phase 8**
- Marketplace/app store
- White-label tenant branding beyond per-org logo

---

## Sizing

| Phase | Size | Estimated effort | Dependencies |
|---|---|---|---|
| 1 — Contract engine | M | 2-3 weeks | none — **1.1 + 1.2 shipped (v3.17.126 / v3.17.130)** |
| 2 — Resource mgmt | M | 2-3 weeks | none |
| 3 — Financial reporting + BI | L | 4-6 weeks | 1, 2 — **complete (v3.17.139–147)** |
| 4 — Procurement | L | 4-5 weeks | none (ideally after 1) |
| 5 — CRM | L | 4-5 weeks | none |
| 6 — ITIL | M | 2-3 weeks | none |
| 7 — Outsourcing + ecosystem + polish | Continuous | **complete (v3.17.207); 2 polish waves closed at v3.17.187 + v3.17.205** | ran alongside Phases 1-6 |
| 9 — Security alert ingestion (EDR / AV / Firewall) | M | 5 weeks — **framework + 1 reference adapter shipped v3.17.168** | none — can run alongside any |
| 10 — Advanced Email-to-Ticket Engine | M | 2-3 weeks — **all sub-phases complete (10.1 v3.17.176; 10.2 v3.17.177; 10.3 v3.17.188; 10.4 v3.17.189)** | extends existing IMAP poller |
| 11 — Advanced Dispatch & Tech Scheduling | M | **complete (11.1 v3.17.194; 11.2 v3.17.208; 11.3 v3.17.209); geo-aware deferred to Phase 8** | extends Phase 2 + dispatch board |
| 12 — Customer Communication Workflows | M | **complete (CSAT v3.17.231; announcements v3.17.232; brand + prefs v3.17.233; KB v3.17.234; voting v3.17.235; escalation v3.17.236; threading v3.17.237; SMS v3.17.238; client approvals v3.17.239); secure messaging deferred** | extends customer portal |
| 13 — Procurement & Lifecycle Mgmt | M | 2-3 weeks | extends Phase 4 |
| 14 — Visual Workflow Automation Engine | L | 4-5 weeks | extends workflow rules engine |
| 15 — Recurring Billing & Contract Mgmt | M | 3-4 weeks | extends Phase 1 |
| 16 — Documentation Relationship Mapping | M | 2-3 weeks | none |
| 17 — Advanced Asset Intelligence | L | 4-5 weeks | extends RMM sync |
| 18 — Multi-Location Client Hierarchy | M | 2-3 weeks | none |
| 19 — Advanced Reporting & Analytics | Continuous | ongoing | extends Phase 3 |
| 20 — Approval & Change Management Workflows | M | 2-3 weeks | extends Phase 6.1 |
| 21 — Advanced Mobile Technician Workflows | L | 4-6 weeks | requires Phase 8 |
| 22 — Knowledge Base & SOP Management | M | 2-3 weeks | extends KB v3.17.128/134 |
| 23 — Security Event & Incident Workflows | L | 4-6 weeks | shipped v3.17.337–363 (extends Phase 9 + 17) |
| 25 — Mature Timesheet Approval Workflows | M | 2-3 weeks | extends Phase 2 + approvals |
| 26 — Custom Report Writer + Saved Queries | L | 4-5 weeks | extends Phase 3.5 + 3.6 |
| 27 — Advanced Accounting Reconciliation | M | 2-3 weeks | extends QBO/Xero connection |
| 28 — Browser Extension + Offline Vault Access | L | 4-5 weeks | separate codebase |
| 31 — Vault GeoIP / IP / Time Access Rules | S | shipped v3.17.163 | extends FirewallMiddleware GeoIP infra |
| 32 — Remote Network Discovery Import | M | shipped v3.17.556 | future / late-stage — non-RMM, scoped, single-use tokens |
| 33 — Network Discovery \& Auto Documentation | L | shipped v3.17.557 | extends Phase 32 + Phase 16 |
| 34 — Network Configuration Backup | M | shipped v3.17.544–547 | extends Phase 33 + Phase 9 alerts |
| 35 — Advanced Project Management | L | shipped v3.17.548–555 | extends `psa.Project` (v3.17.213 quote→project shipped) |
| 36 — Agreement Reconciliation & Pre-Invoice Approval | M | 2-3 weeks | extends Phase 1 + 15 + 20 |
| 37 — Vault Approval & Break-Glass Workflow | M | 2-3 weeks | extends Phase 31 (VaultAccessRule) + Phase 20 |
| 38 — Client Onboarding / Offboarding Runbooks | M | 2-3 weeks | extends `processes/` + Phase 14 |
| 39 — Compliance Evidence Packs | M | 2-3 weeks | extends Phase 9 + vault + monitoring + psa |
| 40 — Public / Client-Facing Status Page | M | shipped v3.17.538–543 | extends monitoring + psa Tickets |
| 41 — Compliance Frameworks & Recertification | M | shipped v3.17.435–444 | extends accounts + audit + reports.pdf_export (Phase 19); built atop Phase 39 evidence-pack infra |
| 42 — Docker / Containerized deployment | S | shipped v3.17.490 | none — packaging only; classic `bash install.sh` path unchanged |
| 43 — Multi-Organization REST API Access | S | shipped v3.17.496 | extends Phase 18 hierarchy; backward-compatible (default key scope unchanged) |
| 44 — Full Two-Way Accounting Sync | L | shipped v3.17.531 | extends Phase 27 + the AccountingConnection OAuth pattern; requested in GitHub #145 |
| 45 — System-wide Appearance Controls | S | shipped v3.17.527 | `SystemSetting` + existing per-user background fields |
| 46 — Job Kit (tools + materials on a ticket) | M | shipped v3.17.533 | `inventory` + `psa.Ticket` |
| 47 — Public scheduler wallboard | S | shipped v3.17.533 | `scheduling.ScheduledTask`; extends the Phase 3.6 wallboards |
| 48 — Task warning windows | S | shipped v3.17.535 | `scheduling.ScheduledTask` + Phase 47 |
| 8 — Mobile apps + GPS auto-time + Timeclock | L | **shipped v3.17.354–417 (extends Phase 2 + 18 + 21)** | Phase 2 (WorkingHours); positioned last as the largest single undertaking |
| 49 — Interface consistency + tenant-boundary hardening | M | **complete — 49.1 (v3.17.559); 49.2 (v3.17.559–581) — views v3.17.559, backup/restore v3.17.560, invoice tax v3.17.561, update progress v3.17.562, SLA v3.17.563, invoice duplicates v3.17.564, scheduler locks v3.17.565, expiry notifications v3.17.566, PSA ticket notes v3.17.567, dashboard widget scoping v3.17.568, AI gating v3.17.569, search scoping v3.17.570, org-hierarchy detail views v3.17.571, abuse-middleware hotfix v3.17.572, data export v3.17.573, vault-export permission v3.17.574, AI data access v3.17.575–576, credit memos v3.17.577, late fees v3.17.578, late-fee audit v3.17.579, navbar overflow v3.17.580, expired contracts v3.17.581, sync status honesty v3.17.582, scheduler failure reporting v3.17.583, bundled services #147 v3.17.584, utility toolbar v3.17.585** | none — touches every app |
| 50 — "Help Us Grow" call to action | S | shipped v3.17.586 | none — `config/support_links.py` + `templates/core/_help_us_grow_*.html`; reuses the existing GitHub Sponsors link |

**Phases 1-6**: ~4 months of focused work at the established cadence.

**Phase 8** adds another ~2.5-3 months on top, but sub-phase 8.1 (web timeclock + GPS APIs) is shippable as a 2-week chunk well before the mobile app itself.

**Phases 10-30**: long-term operational deepening. None should be positioned as fully implemented today; each extends or adds to the foundations already shipped. Items overlapping shipped phases call out the deltas explicitly. AI-assisted features are explicitly **OPTIONAL AI** and gated by `psa_ai_enabled` (existing pattern from v3.17.125 AI Triage).

**Scope note:** This is a PSA + Asset + Vault + Documentation + Monitoring platform that integrates with external RMMs (Phase 9 connection framework + Phase 7 Integration SDK). First-party RMM agents and remote-access relays aren't on the roadmap — installs that need those capabilities use the supported third-party tools (TacticalRMM, NinjaOne, Datto RMM, ConnectWise Automate, ScreenConnect, RustDesk, MeshCentral, etc.).