VetCan Studio Handoff Guide

VetCan is an AI operations layer and premium control surface for voice, chat, booking, reminders, payment-safe next steps, workflow orchestration, approvals, exports, demos, operator visibility, and launch readiness.

Current product truth:

• Internal-preview and operator-safe by default.
• Studio is not a live-production switch.
• Approval, publish package, and demo flows must stay clearly separated from live routing.
• No medical advice.
• Avoid PHI.
• Do not store transcripts.

This README is the handoff entrypoint for:

• Local docker bring-up.
• Remote smoke checks.
• n8n + Google Sheets verification.
• Studio preview and founder-demo execution.

1) Prerequisites

• Node.js 20.x
• npm
• Docker + Docker Compose
• bash (WSL-compatible)
• curl

2) Repo Layout

• api/ Express + Prisma API
• web/ React + Vite web app
• web/src/pages/VetCanStudio.tsx Studio control surface
• web/src/pages/VetCanStudioPreview.tsx Studio preview center
• web/src/components/studio/ Studio UI modules
• n8n/workflows/ current importable workflow JSON exports
• n8n/archived/ archive-only workflow history; do not import into the active workspace
• scripts/ validated smoke/ops scripts
• docs/ runbooks, A-series truth, and delivery evidence

3) Environment Files (Current)

• .env.example
  • Template for local non-compose usage.
• .env.docker
  • Compose env file (KEY=VALUE only).
  • Used by docker scripts and compose commands.

Current compose command pattern:

docker compose --env-file .env.docker ...

4) Local Docker Quick Start (Recommended)

Cold start (rebuild + migrations + prisma generate):

bash scripts/cold-start.sh

Warm start (existing stack):

bash scripts/warm-start.sh docker

Warm stop:

bash scripts/warm-stop.sh docker

Manual compose equivalents:

docker compose --env-file .env.docker up -d

docker compose --env-file .env.docker up -d --build

Local URLs:

• Web app: http://localhost:5173
• Studio: http://localhost:5173/studio
• Studio preview: http://localhost:5173/studio/preview
• API: http://localhost:4000
• n8n: http://localhost:5678

Health checks:

curl -sS http://localhost:4000/api/health
curl -sS http://localhost:4000/api/clinic-profile

5) Required Validation Order (Release + Handoff)

Run in this exact order:

node scripts/validate-n8n-workflows.mjs
npm --prefix api test && npm --prefix api run build
npm --prefix web test && npm --prefix web run build

6) Remote Smoke Path (No Local Stack Required)

Set remote base once:

export API_BASE="https://api.vetcan.astormscoming.com"

Storyline smoke (API + optional n8n checks):

bash scripts/smoke-demo-storyline.sh

Friday smoke bundle (tests/build + optional voice/scheduling + optional remote curls):

export VETCAN_API_BASE_PROD="https://api.vetcan.astormscoming.com"
bash scripts/smoke-friday-demo.sh

Scheduling ops smoke (requires token):

export INTERNAL_ADMIN_TOKEN="<token>"
export API_BASE="https://api.vetcan.astormscoming.com"
bash scripts/smoke-prod-scheduling.sh

Outbound voice sweep smoke (requires token):

export INTERNAL_ADMIN_TOKEN="<token>"
export API_BASE="https://api.vetcan.astormscoming.com"
bash scripts/smoke-prod-outbound-voice.sh

Live vs staged posture:

• npm --prefix web run build produces staged web assets only until they are uploaded to Hostinger.
• npm --prefix api run build produces a staged API artifact only until Render deploys the selected commit.
• /studio and /studio/preview remain staged/internal proof surfaces even after web upload.
• /metrics plus remote API, n8n, Twilio, and Sheets checks provide the live operator proof path.
• Supabase, if used, is an optional existing-auth seam and not a universal install-week gate.

7) Trigger n8n + Verify Google Sheets

Set webhook env vars for your n8n workspace:

export N8N_ALERT_WEBHOOK_URL="https://<n8n-domain>/webhook/<alerts-id>"
export N8N_BOOKING_WEBHOOK_URL="https://<n8n-domain>/webhook/<booking-id>"
export N8N_METRICS_WEBHOOK_URL="https://<n8n-domain>/webhook/<metrics-id>"

Trigger all three directly:

bash scripts/curl-trigger-n8n-plenty.sh

Alternative end-to-end chat + webhook demo script:

export API_BASE="https://api.vetcan.astormscoming.com"
export BOOKING_NOTIFY_N8N_WEBHOOK_URL="https://<n8n-domain>/webhook/<booking-id>"
bash scripts/curl-demo-pipeline-plenty.sh

Then verify:

• n8n Executions show recent successful runs.
• Google Sheets tabs append rows:
  • Alerts
  • Bookings
  • Metrics

n8n archive guardrail:

• Treat n8n/workflows/ as the current importable set.
• Treat n8n/archived/ as archive-only history. Do not import archived workflow JSON into the active workspace unless a deliberate rollback or forensic comparison is underway.

8) Studio + Ops Runbooks

Core Studio truth:

• A21_1_VETCAN_STUDIO_SHELL.md
• A21_2_NL_BUILDER.md
• A21_3_PREVIEW_TEST_CENTER.md
• A21_4_MONITOR_IMPROVE_LOOP.md
• A22_0_VETCAN_STUDIO_PREMIUM_DEMO.md
• A22_1_STUDIO_PERSISTENCE.md
• A22_2_DEPLOYMENT_CHOREOGRAPHY.md
• A22_3_SCENARIO_RUNNER.md
• A22_4_MONITOR_IMPROVE_LOOP.md
• A22_5_EXPORT_HANDOFF.md
• A22_6_STUDIO_CONTROL_BINDINGS.md
• A22_7_PREVIEW_EVIDENCE_LEDGER.md
• A22_8_APPROVAL_PUBLISH_PACKAGE.md
• A22_9_DEMO_LAUNCHER.md

Ops and delivery references:

• DEMO_RUNBOOK.md
• OPS_RUNBOOK.md
• N8N_RUNBOOK.md
• TWILIO_RUNBOOK.md
• ARCHITECT_NOTES.md
• ARCHITECT_HANDOFF_CARD.md
• A13_CLOSEOUT.md
• A18_0_CUTOVER_REHEARSAL_EVIDENCE.md
• client/CLIENT_PROFILE.md
• client/CLIENT_ONBOARDING_CHECKLIST.md
• client/STAFF_TONE_GUIDE.md
• client/CLIENT_ENV_FILL_SHEET.md
• client/OWNER_ACCESS_MATRIX.md
• client/ACCEPTANCE_SIGNOFF.md
• DELIVERY_TALK_TRACK.md
• DELIVERY_EVIDENCE_PACK.md
• delivery/ZOOM_DELIVERY_SCRIPT.md
• delivery/ZOOM_NOTECARDS.md
• delivery/DELIVERY_CHECKLIST.md
• delivery/DELIVERY_FAQ_OBJECTIONS.md
• OPS_GOVERNANCE.md
• POST_DELIVERY_PLAYBOOK.md
• WEEK1_STABILIZATION_PLAN.md
• render-postgres-basic-plan-note.md
• CHANGE_REQUEST_TEMPLATE.md
• BACKLOG_NEXT.md
• EXPANSION_BRAINSTORM.md
• PLUG_AND_PLAY_MODULES.md
• INTEGRATIONS_CATALOG.md
• PRICING_PACKAGING_NOTES.md
• templates/OWNER_WEEKLY_UPDATE_TEMPLATE.md
• templates/INCIDENT_UPDATE_TEMPLATE.md
• templates/WEEKLY_ROI_SNAPSHOT.md
• addons/ELEVENLABS_VOICE_UPGRADE.md
• addons/CLINIC_SOP_MAPPING_WORKSHEET.md
• addons/WEEK1_STABILIZATION_PLAN.md
• addons/EMBED_AND_PORTING_OPTIONS.md
• CUTOVER_CHECKLIST.md
• ROLLBACK_PLAN.md
• Scripts Catalog

9) Current Canonical Workflow/Setup References

• n8n/workflows/*.json (runtime workflow exports)
• docs/architecture/ARCHITECT_NOTES.md (canonical endpoint/contract/gotcha freeze)
• docs/workflows/*.md (workflow contracts + required keys)
• docs/ops/outbound-voice-production.md (production voice/sweep rollout details)
• docs/ops/n8n-render-base-url.md (Render URL/proxy settings for n8n)
• docs/a17/*.md and docs/a17/*.json (offer, service-map, live-config, webhook-prep truth)
• docs/a20/*.md (voice preview lane, humanization, and rollout controls)
• docs/a21/*.md and docs/a22/*.md (Studio product truth, persistence, evidence, approval, launcher)

10) Safety Notes

• Keep operations launch-safe and clearly separated by preview, approval, and live path.
• Do not include medical advice in scripts, payloads, or runbooks.
• Do not store PHI or transcript content in sheets, logs, exports, or evidence packs.
• Keep payload keys and env var names unchanged unless explicitly requested.
• Do not imply Studio preview equals live deployment.

11) Release Checklist

1. Run required validation order:

   node scripts/validate-n8n-workflows.mjs
   npm --prefix api test && npm --prefix api run build
   npm --prefix web test && npm --prefix web run build

2. Complete CUTOVER_CHECKLIST.md.
3. Keep ROLLBACK_PLAN.md open during release.
4. Run remote demo driver once webhooks are set:

   export API_BASE="https://api.vetcan.astormscoming.com"
   export N8N_ALERT_WEBHOOK_URL="https://<n8n-domain>/webhook/<alerts-id>"
   export BOOKING_NOTIFY_N8N_WEBHOOK_URL="https://<n8n-domain>/webhook/<booking-id>"
   export N8N_METRICS_WEBHOOK_URL="https://<n8n-domain>/webhook/<metrics-id>"
   bash scripts/demo-driver.sh

5. Capture release evidence:
   • API health + clinic-profile response.
   • n8n execution timestamps for alert, booking, and metrics.
   • Google Sheets rows in Alerts, Bookings, and Metrics.
6. For Studio-facing demos, verify /studio and /studio/preview behavior before presenting.