FAQ Docs Audit — 2026-08-18

Scope: docs/faqs/*.md (19 files) rendered at http://localhost:8080/docs/faqs/* Verified against: live platform (firetail-sandbox session → https://localhost:3000, org firetail) and the saas-frontend codebase (src/utils/hooks/usePaths.tsx, routes in src/pages/organisations/orgID/*, billing/alert components). Method: read every FAQ source file, checked every rendered page (HTTP status), validated every internal link and image, and navigated the live platform UI to confirm menu paths, page names, table columns, and download-modal attributes.

Summary

Top problems:

1. Self-service organization creation no longer exists. The Organizations page has no "Create Organization" button (verified live and in code: OrganisationsList.tsx has no create control, its empty state says "To create an organization, reach out to your account manager or FireTail support", and a unit test explicitly asserts the create control is absent). Multiple FAQs — why-create-an-organization.md, how-do-i-set-up-an-account.md, how-do-i-log-in-to-the-platform.md — still tell users to create organizations themselves, and the linked doc docs/organizations/create-a-new-organization.md documents the removed Create Organization button flow.
2. The account sign-up FAQ describes an entry flow that no longer exists. www.firetail.app now shows "Start a Trial" (no "Get Started" button), and it redirects to firetail.ai/book-an-onboarding-call (sales-led onboarding call booking) instead of a sign-up form. The only self-service path is Log In → Auth0 → "Sign up" link. Verified live on 2026-08-18.
3. Billing/Subscription FAQs describe UI that no longer exists in the app. The Settings menu has no Subscription or Billing entries (verified live: Settings = Overview, Members, Quotas, Audit Logs, Projects, Events, Integrations, Reporting, Programmatic Access). Billing is now handled via a Stripe customer portal session (useNavigationBar.tsx → createPortalSession), and the in-app subscription.tsx page is not wired into PlatformRoutes (old /settings/subscription URLs redirect to platform/organization/subscription, which falls through to Overview).
4. A live FAQ links to a draft page — how-do-i-switch-plans.md links to /docs/organizations/manage-subscriptions-and-billing/, which 404s (isDraft: true).
5. Download-attribute lists are stale across findings/events/models/prompts examples.

Per-file findings

✅ Accurate — no action needed

⚠️ Minor issues

1. how-do-i-log-in-to-the-platform.md

   • Login flow itself verified live (2026-08-18): Log In → Auth0 hosted page with Email address/Password + Continue, "Continue with Google", "Forgot password?" — matches the doc ✅.
   • Screenshot outdated: 1748372027511.png shows the old landing page; the live top-right area still has Log In, but the page hero/CTA changed ("Start a Trial" instead of "Get Started"). Retake recommended.
   • Stale claim: closing line says users "can view any existing organizations or create a new organization" — self-service org creation has been removed (see item 7 below); the link to create-a-new-organization should be dropped or the doc reworded to "contact your account manager or FireTail support".
   • Sentence fragment: "After you have created an account or have been invited… . You can log in" — the period splits one sentence into a fragment.
   • "Click Continue." — bold includes the period inconsistently.

2. how-do-i-view-and-analyze-ai-logs.md

   • Navigation verified live: Workload → Cloud Logs ✅.
   • Column claim "displaying columns for ID, generated time, model used, input/output messages, and performance metrics (latency, token usage)" — live table columns are: ID, Generated, Models, Tags, Input Message, Output Message, Latency, Input Tokens, Output Tokens, Total Tokens. The Tags column is missing from the doc (minor omission).
   • Detail drawer verified: Inputs/Outputs sections, Input/Output Metadata, Stop Reason ✅.

3. token-usage-in-ai-services.md

   • Token metric names verified live (Input Tokens, Output Tokens, Total Tokens; usage-over-time charts on dashboards) ✅.
   • "you need to first set up integrations with your cloud environments and code repositories" — token metrics come from logging integrations (cloud logs), not repo scanning; repo scanning discovers inventory, not token usage. Slightly misleading.

4. do-you-have-any-integrations-with-azure.md

   • Understated: platform now offers Azure OpenAI Logging and AZURE Inventory Scanning (both verified live in Integrations catalog), plus Azure DevOps repo scanning docs exist (azure-devops-repo-scanning.md, azure-openai-logging.md). FAQ mentions only "AI discovery integration" and links only to inventory scanning.

5. whats-the-difference-between-a-finding-and-an-alert.md

   • Findings description verified (event/scan-driven; posture management shows Findings + Resource Policies tabs) ✅.
   • Anomaly alerts claim not supported by the app: frontend only implements static alerts — AlertType = 'static' in src/utils/models/Alert.ts, only "AI Static Alerting" visible live, and the Create Alert flow opens a "Static Alert" dialog directly with no type choice. Either anomaly detection is not yet shipped or is backend-only; the FAQ presents it as a current, user-selectable alert type.

6. how-do-i-delete-a-member.md

   • Link resolves ✅. Minor: consider confirming "contact support to remove a member completely" is still the process.

❌ Significant issues

7. how-do-i-set-up-an-account.md

   • The documented sign-up entry flow no longer exists. Verified live (2026-08-18) on www.firetail.app:
     • Step 2 says "Click Get Started" — there is no Get Started button; the landing CTA is now "Start a Trial".
     • "Start a Trial" does not open a sign-up form — it redirects to https://www.firetail.ai/book-an-onboarding-call ("Start Your Trial — Book a setup call…"), i.e. a sales-led onboarding call, not self-service registration.
     • The only remaining self-service path is Log In → Auth0 page → "Sign up" link (/u/signup).
   • Stale closing claim: "When the account is activated you can then create an organization" — self-service org creation has been removed (see item 8); orgs are provisioned by FireTail (account manager/support).
   • Screenshot outdated: 1748372028609.png shows the old "Get Started" landing page.
   • The MFA/QR/recovery-code steps (4–9, images 1748372029218.png, 1748372029832.png) are Auth0-hosted and may still be accurate for the Auth0 sign-up path, but were not verifiable without creating an account — retest once the entry-flow rewrite is decided.
   • Formatting bug (renders live): "Uppercase letters.Numbers (0-9)." — two list items merged into one line. Confirmed in rendered HTML: <li>Uppercase letters.Numbers (0-9).</li>.
   • Minor: special-characters example !&%%^\* shows a doubled % and escaped * (!&%%^* rendered).
   • Decision needed from product: should this FAQ be rewritten around the Auth0 "Sign up" link, or repositioned as "start a trial / book an onboarding call"?

8. why-create-an-organization.md (and the linked docs/organizations/create-a-new-organization.md)

   • Self-service organization creation has been removed from the platform. Verified live (2026-08-18): the Organizations page (org switcher → View All Organizations) shows a heading, search box, and org cards — no "Create Organization" button.
   • Confirmed in code (src/components/Organisations/OrganisationsList.tsx): no create control is rendered; the empty state reads "To create an organization, reach out to your account manager or FireTail support" with a Contact Support (HubSpot chat) button. A unit test (OrganisationsList.test.tsx) explicitly asserts "does not render a create organization control" — this is intentional product behavior, not a bug.
   • The FAQ says "When you set up an account… you first create an organization" and links to create-a-new-organization.md, which documents the removed Create Organization button flow (including "Add additional organizations" via View All Organizations → Create Organization, and screenshot 1748372046645.png).
   • The FAQ's conceptual content (org isolation, members scoped per org) is still accurate; only the creation-flow claims are stale.
   • Also affects: how-do-i-log-in-to-the-platform.md and how-do-i-set-up-an-account.md (both link to the create-org flow), and docs/organizations/create-a-new-organization.md itself (out of FAQ scope but user-facing and now wrong end-to-end).

9. how-do-i-switch-plans.md

   • Step 1 is wrong for the current UI: "In the side menu, go to Settings then select Subscription" — verified live: there is no Subscription menu item under Settings. The Subscription page component exists (src/pages/organisations/orgID/platform/subscription.tsx) but is not registered in PlatformRoutes (platform.tsx) and not in the nav (usePaths.tsx). Legacy /settings/subscription URLs redirect to platform/organization/subscription → falls through to Overview.
   • Plan changes now go through a Stripe checkout session (BillingPlansCards → createCheckoutSession), typically surfaced via upgrade modals, not a Settings page.
   • Screenshots (subscription-menu.png, 1748372027066.png) show the old UI.

10. how-do-i-change-my-payment-details.md

    • Steps describe UI that doesn't exist: "go to Settings and click Billing" — no Billing menu item live. Code path: the nav key settings-organization-billing triggers createPortalSession and redirects the browser to the Stripe customer portal (useNavigationBar.tsx), and even that key is not present in current usePaths.tsx menus. Payment-method editing (pencil icon, "Add payment method") happens inside Stripe's portal, not the FireTail UI.
    • Role claim ("Only Organization Admin or Admin…") aligns with hasPermissionToUpdateBillingDetails (requires billing.updateDetails + Stripe billing platform + showStripeBilling) — roughly right but gated on Stripe availability too.

11. what-are-the-differences-between-plans.md (draft — 404 on site, not user-facing)

    • Kept as draft, so not an immediate issue, but it is the only place plan limits are documented and other live FAQs depend on it conceptually. Frontend renders plans dynamically from the billing API (useListPlansQuery) — the hard-coded table (5/50/100/250 APIs etc.) cannot be verified from the frontend and needs product/billing confirmation before publishing.

12. how-do-i-download-information-from-the-firetail-platform.md

    • Grammar: "in the most areas of the platform" → "in most areas" (renders live).
    • Punctuation: "Click Download," (comma instead of period) — appears in 4 places.
    • Findings attribute list stale. Doc: UUID, code, context, dateAddedInMicroSeconds, events, resources, severity, status, tags. Live modal: ID, Name, Description, Remediation, Code, Context, Date Added in Microseconds, Creation Time, Tags, Events, Severity, Resources, Status (humanized labels; Name/Description/Remediation/Creation Time missing from doc).
    • Events attribute list stale. Doc: UUID, code, context, dateAddedInMicroSeconds, dateOccurredInMicroSeconds, event_orgUUID, g_orgUUID, initialFindingSeverities, resources, source, version. Live: ID, Name, Description, Code, Context, Date Added in Microseconds, Date Ocurred in Microseconds, Creation Time, Organization ID, Resources, Version, Source (no event_orgUUID/g_orgUUID/initialFindingSeverities; note the live label "Date Ocurred" is itself a typo in the app — possible frontend bug worth reporting separately).
    • Models attribute list slightly stale. Live modal also includes Risk Score, which the doc omits; ordering/naming otherwise matches.
    • Prompts list: matches live except copy-paste error in steps 4 ("number of Events" should be "number of Prompts"; same issue in the Models section — "number of Events" should be "number of Models").
    • Dashboard chart section verified live (Download CSV icon per chart on Workforce Usage; Top Employees/Top Devices metric toggles exist in code: ChartMetricToggle, EmployeeMetric, DeviceMetric) ✅.

13. Draft/archived files depended on by live content

    • whats-the-difference-between-a-finding-and-an-incident.md (isDraft: true, isArchived: true, 404) — fine as archived, but its eleventyNavigation still declares parent: FAQs Security Concepts order 2; confirm it doesn't leave a gap in section ordering.
    • manage-subscriptions-and-billing.md (in docs/organizations/, isDraft: true) — linked from the live FAQ how-do-i-switch-plans.md, producing a 404 for users. Either publish it (after correcting it for the Stripe-portal flow) or remove the link.

Link & asset check

• Rendered pages: all 17 non-draft FAQs return 200; the 2 drafts 404 as expected.
• Internal links in FAQ sources: 12/13 resolve; 1 broken: /docs/organizations/manage-subscriptions-and-billing/ (404, draft) referenced from how-do-i-switch-plans.md.
• Images: all 10 images in docs/faqs/images/ load (200).

Screenshot currency review

Screenshots were assessed by comparing the live UI flows against what each doc describes (direct pixel inspection was not possible in this audit environment).

Live-platform verification notes (firetail-sandbox)

• Side nav (top level): Dashboards, Workforce, Workload, Posture Management, Settings — matches usePaths.tsx.
• Settings submenu: Overview, Members, Quotas, Audit Logs, Projects, Events, Integrations, Reporting, Programmatic Access — no Subscription/Billing.
• Organizations page (org switcher → View All Organizations): heading, search, org cards — no Create Organization button; empty state directs users to contact their account manager/FireTail support (confirmed in OrganisationsList.tsx + unit test asserting the control's absence).
• Workload submenu: Services, Models, Agents, Prompts, Model Scanning, Alerting, Cloud Logs.
• Workforce submenu: Platforms, Employees, Groups, Devices, Applications, Policies, Topics, Employee Logs.
• Posture Management: Findings / Resource Policies tabs with Download button.
• Dashboards: Workforce Risk, Workforce Usage, Workload Risk, Workload Usage; per-chart "Download CSV" buttons confirmed.
• Alerting: "Create Alert" opens "Static Alert" dialog; only static alerts exist (AlertType = 'static').
• Integrations catalog includes Azure OpenAI Logging and AZURE Inventory Scanning.

Live public-site verification notes (www.firetail.app, 2026-08-18)

• Landing header: logo, docs link, Log In; hero CTA: Start a Trial (no "Get Started").
• Start a Trial → https://www.firetail.ai/book-an-onboarding-call ("Start Your Trial", 45-minute onboarding call, embedded scheduler) — no self-service sign-up form.
• Log In → auth.firetail.app (Auth0): Email address + Password + Continue, "Continue with Google", "Forgot password?", and a "Sign up" link (/u/signup) — matching the login FAQ, and the only self-service registration entry found.

Recommended actions (not applied)

1. Rewrite how-do-i-set-up-an-account.md: decide with product whether to document the Auth0 "Sign up" path (via Log In) or the new trial/onboarding-call flow; retake 1748372028609.png and re-verify the Auth0 MFA screenshots.
2. Update org-creation docs: rework why-create-an-organization.md (and docs/organizations/create-a-new-organization.md) to reflect that organizations are provisioned by FireTail (account manager/support), remove "Create Organization" button steps and screenshot 1748372046645.png, and fix the create-org links/claims in how-do-i-log-in-to-the-platform.md and how-do-i-set-up-an-account.md.
3. Rewrite how-do-i-switch-plans.md and how-do-i-change-my-payment-details.md around the current Stripe-portal/checkout flow; replace outdated screenshots; remove or fix the draft billing-doc link.
4. Update the four attribute lists (findings, events, models, prompts) in how-do-i-download-information-from-the-firetail-platform.md to the current modal labels; retake the two download-modal screenshots; fix "number of Events" copy-paste errors and grammar.
5. Fix the merged password-requirement bullets in how-do-i-set-up-an-account.md.
6. Add the Tags column to how-do-i-view-and-analyze-ai-logs.md.
7. Either document anomaly alerts as "coming soon"/remove from whats-the-difference-between-a-finding-and-an-alert.md, or confirm with backend that anomaly alerts are user-facing.
8. Broaden do-you-have-any-integrations-with-azure.md to mention Azure OpenAI Logging and Azure DevOps repo scanning.
9. Retake the landing-page screenshot in how-do-i-log-in-to-the-platform.md.
10. Confirm with product: retention tiers (how-long-is-traffic-data-stored.md), on-prem statement, and plan-limit table before publishing the draft.
11. Separately: report the app-side typo "Date Ocurred in Microseconds" in the Events download modal (saas-frontend).