First Login & Smoke Test

Your stack is deployed (production-deployment.md)
or running locally (quickstart.md). This page onboards
your first engineer and then proves the whole pipeline with a five-point
end-to-end smoke test — client chat in, AutoTask ticket out.

---

1. Engineer onboarding

There is no admin console for creating engineer accounts and no invitation
flow — Entra group membership is the entire access model:

Entra security group member  ──sign in──>  AVA engineer record (auto-created)
                                              │
                                              └─ AutoTask Resource (auto-mapped by email)

Per engineer

1. Add them to the Entra security group whose object ID you set in
   ENGINEERING_GROUP_ID. That's the only provisioning step.
2. They browse to https://<your-host>/dashboard (or
   http://localhost:3000/dashboard locally) and are redirected to Microsoft
   sign-in.
3. On successful sign-in, AVA checks the ID token's groups claim for your
   group's object ID. The check is fail-closed: a non-member — or a token
   without the claim — is denied. (If every sign-in is denied with
   access_denied, the app registration is missing Token configuration →
   Add groups claim (Security groups) for the ID token; see
   requirements.md §2.2.)
4. On the first successful sign-in AVA auto-creates the engineer record
   and looks up an AutoTask Resource whose email matches the engineer's
   O365 sign-in email, storing the mapping. From then on, that engineer's
   wrap-up time entries attribute to their AutoTask resource.

If the resource lookup finds no match

The engineer still signs in and can work chats normally — the mapping is
logged as unmapped, and their time entries fall back to the default role
without per-person attribution. To fix it, align the emails (the AutoTask
resource's email must equal the O365 sign-in email) — the mapping is attempted
at first login, so correct it before the engineer's first sign-in, or expect
to reconcile that engineer's early time entries by hand.

Removing an engineer

Remove them from the Entra security group — the fail-closed group check denies
their next sign-in. (Repo operators can also mark the engineer record disabled
with npx tsx scripts/disable-engineer.ts <email> — a disabled engineer is
rejected on their very next request, even with a still-valid session token.)

After signing in

Each engineer manages their own state from the profile menu at the bottom of
the icon rail: availability (online/away — signals to the team whether
they're taking chats), light/dark theme, and feedback. Pressing ? shows the
keyboard shortcuts; ⌘K / Ctrl-K opens the command palette.

---

2. The five-point smoke test

This walks one chat through the entire pipeline and verifies every AutoTask
write. Have one browser signed in to the dashboard as an engineer (set
yourself online), and a second browser (or an incognito window) for the
client side.

Outside business hours? The client page will show the after-hours state.
Either wait for your configured window or temporarily set
BUSINESS_HOURS_BYPASS=true and restart — and remove it afterwards.

Point 1 — Client starts a chat

In the client browser, open https://<your-host>/ and fill in the contact
form. Choose the email deliberately:

• an address at a domain that matches an AutoTask company (e.g.
  [email protected]) exercises domain → company matching;
• a personal address (e.g. [email protected]) exercises the catchall
  company path.

Submit. The client should land in the queue view with a position indicator.

Verify in AutoTask now: a new ticket exists under the matched company (or
the catchall), created with your configured default status / priority / queue
/ source / type. If no ticket appeared for a personal-email test, check
AUTOTASK_CATCHALL_COMPANY_ID (quickstart.md Step 5) —
the client UI will also show a "No AT ticket" badge on such sessions.

Point 2 — Triage classifies it

Within a few seconds the dashboard queue shows the new session carrying an
AI-assigned priority pill (P1–P4), an AutoTask issue category, and a
one-line topic summary, plus a live wait timer. (If the AI call fails or times
out, the chat still queues — it just files at normal priority with the raw
description. Triage failure never blocks a client.)

Point 3 — Engineer accepts

Accept the chat from the queue. The client's view flips from "waiting" to the
live conversation; the engineer gets the transcript pane with the triage
context and (if configured) the NinjaOne device card in the rail.

Point 4 — Exchange messages

Send a message in each direction and confirm both sides render it live, with
typing indicators. Optionally attach a small image from the client side to
exercise the upload path (5 MB cap, type-allowlisted).

Point 5 — Close with details

In the engineer rail, open the wrap-up panel:

1. Pick the resolution outcome — resolved vs. needs follow-up (this
   drives the final AutoTask ticket status).
2. Review the billed time — auto-computed from the chat duration and
   quarter-hour rounded; adjust if needed.
3. Enter the client-facing summary (and any internal note), then Submit &
   Close.

The client side receives the closure and a satisfaction survey.

Verify in AutoTask — the full round-trip. The ticket should now have:

• a client-facing note with your summary,
• an internal note (if you entered one),
• a distinctly titled Chat Transcript note with the full conversation,
• any attachments uploaded during the chat,
• a time entry for the billed duration, attributed to the engineer's
  mapped resource,
• the final status/resolution matching your wrap-up choice.

If all five points pass, your instance is wired correctly end-to-end.

---

3. If a point fails

---

Next: put your own identity on it — white-label.md — and
keep configuration.md at hand for everything tunable.