Skip to main content

Core concepts & glossary

In one line: the vocabulary you need to follow any conversation about HIGHFIELD — skim it once and the rest of the docs read easily.

What it is​

HIGHFIELD has its own domain language: tickets, gates, slots, lock-in, escalations, briefs. This page defines each term in plain language. The deeper mechanics live on the linked pages; this is the dictionary.

Glossary​

(Alphabetical.)

  • Admin / Approver — A property manager or finance signer. The agent treats a sender as admin only when their email matches a configured approver address (env APPROVER_EMAIL or BC approvalEmail1/2/3), flagged by the admin-mode preprocessor (src/skills/admin.skill.ts:18-20). Admins get terse, factual, data-rich answers and can record approvals, query tickets, and relay instructions — but cannot directly reassign or close a ticket (src/skills/admin.skill.ts:44-47).

  • Alex Carter — The agent's persona: a warm, professional "Property Maintenance Coordinator" personality that all three audiences talk to. One identity with rules that shift by audience. Defined in src/index.ts:71-546.

  • AgentMail — A third-party email API (api.agentmail.to) powering a dedicated mailbox. Distinct from the production Lua send-message lane. Every AgentMail outbound is force-overridden to a test address (AGENTMAIL_OVERRIDE_TO) as a safety measure. See Communication & email.

  • Business Central (BC) — Microsoft Dynamics 365 Business Central, the property company's ERP/accounting system. HIGHFIELD's system of record: every ticket, vendor, quote, and audit entry lives here (README.md:1-4).

  • Brief (daily / weekly) — Automated summary emails to managers. The daily brief runs at 09:00 Europe/London (daily-report.job.ts:32) covering open tickets by status, last-24h activity, pending approvals, escalations, and vendor performance. The weekly brief runs Friday 17:00 wrapping up Mon–Fri (weekly-report.job.ts:21-26). Both have once-per-period guards to avoid duplicate sends. See Scheduled jobs.

  • Dual-write — The pattern of writing ticket data both as JSON attachments via the standard BC API (the source of truth) and mirroring it into custom BC extension tables (for native BC pages/reporting). The mirror is fire-and-forget; failures are logged, not propagated. See Data model.

  • Escalation — A flag raised when the agent can't resolve something itself (a non-responsive vendor, a dispute, an unhandled scenario, an SLA breach). Created via escalate_ticket, it emails the admin team so a human can step in (src/skills/maintenance.skill.ts:75). The escalation-check job also raises escalations automatically for stuck tickets every 4 hours.

  • Lock-in — The moment a visit is finally settled and the contractor is cleared to proceed. It happens when both gates clear: cost approved AND the tenant confirms the time. Once locked in, the time is settled and the agent never re-asks (src/index.ts:185; logic in src/services/lock-in.ts).

  • Money-blindness — The rule that tenants never see or hear about cost, price, "approval", or "management sign-off" — the finance gate is invisible to them (src/index.ts:184,524). Vendors may see cost.

  • PO (Purchase Order) — The BC document authorising payment to a vendor for a job. Created/managed as the quote is approved and the job completes. Auto-posting the invoice is behind a kill-switch (BC_AUTO_POST_INVOICE, default off). See Configuration.

  • Quote — A vendor's cost estimate plus scope for a claimed job, recorded via submit_quote (cost only); visit options come separately via offer_visit_slots (src/skills/vendor.skill.ts:66,77). A revised quote (submit_revised_quote) auto-approves if it's at or below the already-approved amount.

  • Slot scheduling — The visit-time mechanism. A contractor must offer at least two distinct options; the tenant picks from a numbered menu. A single fixed time is intentionally not allowed to reach the tenant (src/skills/vendor.skill.ts:77, src/index.ts:308-313). Controlled by SLOT_SCHEDULING_ENABLED (on unless set to false).

  • Tenant — A resident of a managed property. Reports issues, sends photos, confirms times, gives feedback. Every tenant report becomes a ticket — there is no deflection path (src/index.ts:144-148).

  • Ticket — The unit of work: one maintenance request, identified by an MT-YYYY-NNN ID. Created by create_maintenance_ticket; one email = at most one ticket (src/index.ts:246). Stored in BC as a JSON attachment + a custom-extension row. See Data model.

  • Ticket lifecycle / status — The states a ticket moves through (src/skills/maintenance.skill.ts:80): reported → vendor_contacted → quoted → [pending_approval] → pending_tenant_confirmation → approved → in_progress → completed → closed. Plus on_hold (work paused), disputed, rejected, and cancelled. Full state machine in Data model.

  • Two-gate (cost + time) flow — After a quote, two independent gates must clear before a contractor proceeds: the cost gate (finance approval if over threshold — internal, the tenant never sees it) and the time gate (the tenant confirms a visit time). The tenant only ever confirms the time, never the cost (src/index.ts:177-184).

  • Urgency anti-liability rule — Urgency is an INTERNAL routing field only. The agent never surfaces urgency labels, severity verdicts, timing synonyms ("ASAP", "right away"), or severity adjectives ("spreading", "serious") in tenant/vendor copy — even echoing the tenant's own words (src/index.ts:389-432).

  • Vendor / Contractor — An approved trade who does repairs. Browses, claims, quotes, schedules, starts, and completes jobs (src/skills/vendor.skill.ts:37-49).