Voice-to-Ops

Field reports that write themselves. A field-service technician dictates a site note instead of filling in a form; Speechmatics transcribes it, an open model on Featherless AI turns it into a validated structured report (findings by severity with verbatim evidence, action items, materials, an explicit "couldn't determine" list), and one click drafts a follow-up email.

What this repo is. This is the pre-hackathon preparation repo for the AI Factory — Native.builder Hackathon (lablab.ai × NativelyAI, Aug 3–10 2026) — not the competition entry. Eligibility requires the real submission to be built from scratch inside native.builder, during the Aug 3–10 window; nothing built earlier can count. So this repo spends the time before the window de-risking the parts that are expensive to get wrong on the clock: the report schema, the prompt, the anti-hallucination guardrails (proven against deliberately mutated payloads, not just "it passed once"), the screens, and the secrets topology. prototype/ is a throwaway Next.js app that rehearses that architecture for real, mock-first, fully tested. hackathon/ is the resulting build-week playbook. See hackathon/BRIEF.md §3 for the full eligibility framing.

Try it now

Live rehearsal deploy: https://voice-to-ops-prototype.vercel.app — a mock-mode deployment of prototype/ (Vercel, zero provider keys, zero network calls). This is a rehearsal of the demo path, not the hackathon entry.

1. Load demo jobs on the empty dashboard — seeds 4 fixture jobs.
2. Open #0417 ("Building B rooftop unit 3") — a critical-severity report with verbatim evidence quotes, action items, and materials.
3. Click Draft Follow-up Email — a deterministic template render, no LLM call, no network.

Run it locally instead — one command, zero config, zero network calls:

git clone https://github.com/SebAustin/voice-to-ops.git
cd voice-to-ops/prototype
npm install
npm run demo

Open http://localhost:3000. See prototype/README.md for the full script inventory and RUNBOOK.md for day-to-day operation.

Screenshots

Dashboard (demo jobs loaded)	Job report (severity + evidence)	Capture pipeline (mid-run)

Captured live from the Vercel deployment above; regenerate with docs/images/capture-screenshots.js (node "docs/images/capture-screenshots.js" from the repo root — reuses the Playwright install already in prototype/node_modules, same pattern as launch/assets/render-cover.js).

Architecture

One job = one voice note in, one structured report + email draft out. Two sequential route-handler calls drive a four-step pipeline; the browser never sees a provider key. Full reasoning in ARCHITECTURE.md.

flowchart LR
  subgraph BROWSER["Browser — untrusted, no secrets ever"]
    CAP["Capture screen"]
    DASH["Dashboard"]
    DET["Job Detail + Email draft"]
  end

  subgraph SERVER["Next.js Route Handlers — trusted, holds keys"]
    RT["POST /api/transcribe"]
    RS["POST /api/structure"]
    G["Input/output guardrails +\nZod schema validation"]
  end

  subgraph EXT["External APIs — untrusted responses"]
    SPX["Speechmatics"]
    FTH["Featherless AI\n(open model)"]
  end

  CAP -->|"audio or fixture"| RT --> G --> SPX
  RT -->|transcript| CAP -->|transcript| RS --> G --> FTH
  G -->|"validated report, warnings, or typed error"| CAP
  CAP -->|Save| DASH --> DET
  DET -->|"pure fn, no network"| EMAIL["renderEmail(report)"]

Loading

The two route handlers are written to map 1:1 onto two Supabase Edge Functions — the build-week secrets/CORS design (ARCHITECTURE.md §9) — so this is an honest rehearsal of the real topology, not a toy.

Directory map

Path	What it is
prototype/	The throwaway Next.js blueprint — mock-first, fully tested. See its own README.md.
hackathon/	The 6-file build-week prep package: BRIEF.md, NATIVE-BUILDER-PLAYBOOK.md, INTEGRATIONS.md, TIMELINE.md, DEMO-SCRIPT.md, SUBMISSION-CHECKLIST.md. Planning docs only, no code.
launch/	Draft, human-gated launch copy (SOCIAL.md, SUBMISSION-COPY.md) and submission assets (cover image, deck, rehearsal video) for after the real entry is submitted — not posted or submitted by anything in this pipeline.
design/	UX-SPEC.md (screens, states, tokens) and AI-QUALITY.md (the schema/prompt/guardrail contract — the single authoritative source for the report schema).
reviews/	Independent review passes, e.g. 2026-07-26-full-review.md (23 findings, all fixed, with pinning tests).
docs/images/	README screenshots and the script that regenerates them.

Docs index

Planning & contract: PLAN.md (architecture, milestones, ADR-0, revision log) · REQUIREMENTS.md · ASSUMPTIONS.md · DEPLOYMENT-CONTEXT.md · SECURITY.md

System & operations: ARCHITECTURE.md · RUNBOOK.md · prototype/README.md

Outcomes: ACCEPTANCE.md (success-criteria pass/fail, quality evidence) · POSTMORTEM.md (blameless retrospective) · SKILL-UPDATES.md (gated process-improvement proposals — none applied) · reviews/2026-07-26-full-review.md

Build week: hackathon/BRIEF.md (start here) · hackathon/TIMELINE.md · hackathon/NATIVE-BUILDER-PLAYBOOK.md · hackathon/INTEGRATIONS.md · hackathon/DEMO-SCRIPT.md · hackathon/SUBMISSION-CHECKLIST.md

Launch (draft, human-gated): launch/SUBMISSION-COPY.md · launch/SOCIAL.md

Quality evidence

As of 2026-08-03: 307 unit/component tests (Vitest, 31 files) and 12 Playwright E2E specs — verified passing both locally and, independently, against the live Vercel deployment via prototype/playwright.prod.config.ts. Coverage over the NFR-5-named globs (src/lib/**, src/features/jobs/**, src/features/report/**): 93% statements / 84% branches / 90% functions / 95% lines, above the enforced 80% threshold. npm run eval — all Gate A (blocking) and Gate B (target) checks pass in mock mode, with the grader itself validated against 8 deliberately mutated payloads. An independent solution-verifier's final acceptance verdict: SOLID (98/100) — see ACCEPTANCE.md. A full-app review round found 23 issues (6 HIGH, 14 MEDIUM, 3 LOW); all fixed with pinning tests — see reviews/2026-07-26-full-review.md. Security: 0 Critical / 0 open High findings — see SECURITY.md. Counts drift as the repo grows (see POSTMORTEM.md §5.1 on doc-drift) — the CI badge above reflects the live, current state rather than a number frozen in this file.

Build-week entry point

Day 1 of the actual build starts at hackathon/TIMELINE.md → Day 1 — Aug 3, which opens with the 90-minute Day-1 verification pass (PLAN.md §5.3, V1–V6) before any native.builder prompting begins.

Prerequisites

• Node.js ≥ 20.9 (tested on Node 26.5.0)
• npm (this repo uses npm, not pnpm/yarn) — package-lock.json is committed
• The repo path may contain a space (AI Factory) — quote it in any shell command run outside npm scripts

---

Licensed under the MIT License © 2026 Sebastien Henry.