studio/services/bot/planning.md

Planning

Notes and roadmap for taco-bot.

Product Vision

Taco is an autonomous meeting assistant. It has its own email address, gets invited to meetings like any team member, joins at the scheduled time, listens, takes notes, and answers questions when asked.

Core Requirements

1. Calendar-driven auto-join

• Taco has a Google Workspace email (e.g. taco@tinqs.com)
• Team members invite Taco to a Google Calendar meeting like any other attendee
• Any meeting Taco is invited to, Taco joins. No exceptions, no opt-in toggle. Invite = join.
• Taco reads its calendar, joins the Google Meet at the scheduled time automatically
• No manual intervention — invite it and it shows up

2. Live meeting listening

• Taco joins the meeting and captures live audio/captions throughout
• Builds a running transcript of the entire meeting
• Identifies speakers by name where possible

3. Meeting notes

• Taco takes structured notes as the meeting progresses
• Captures key topics, decisions, action items, and questions raised
• Notes are available after the meeting ends

4. "Hey Taco" wake word

• When someone says "Hey Taco", the bot listens for what follows
• Question → Taco answers in the Google Meet chat
• Task/action item → Taco acknowledges and logs it as a follow-up
• Context-aware: Taco uses the current meeting conversation to understand what's being asked and why

5. Docs repo search

• Taco can read the tinqs-ltd/docs repo on Git Studio (and eventually other repos)
• When answering questions, Taco searches relevant docs for grounded answers
• Combines meeting context + docs knowledge for accurate responses
• Migration note: Docs search currently uses GitHub Code Search API — must be migrated to Gitea API (git.arikigame.com)

6. Chat responses

• All Taco responses go to the Google Meet chat (not audio)
• Prefixed with "🌮 Taco:" for visibility
• Concise, actionable answers

Architecture — AWS

Everything runs on AWS. No Vercel. Dockerfile already exists.

AWS Services

Service	Role
ECS Fargate	Runs the bot container — both the API and the meeting joiner. Long-running tasks for meetings, always-on service for the API.
S3	Already in use. Store meeting transcripts, notes, action items. Cheap, durable, no expiry.
EventBridge	Cron scheduler — polls Google Calendar every 1-2 min, triggers meeting join tasks.
ALB or API Gateway	Routes HTTP traffic to the ECS service (API endpoints).
ECR	Docker image registry. CI pipeline already pushes here.
CloudWatch	Logs, monitoring, alerts.

Two container modes, one image

The same Docker image runs in two modes:

1. API service (always-on ECS service) — handles /api/meeting/* endpoints, Claude Q&A, transcript storage, calendar polling
2. Meeting bot (on-demand ECS task) — launched per meeting, runs headless Chrome, joins Google Meet, captures captions, posts to chat. Task stops when meeting ends.

EventBridge cron triggers the API service to check the calendar. When a meeting is upcoming, the API service launches a Fargate task for that meeting.

Meeting join approach

Option A: Headless browser bot (Puppeteer/Playwright) — start here

• Launches headless Chrome, navigates to the Meet URL, joins as taco@tinqs.com
• Captures captions via DOM observation (similar to current Chrome extension approach)
• Posts to Meet chat via DOM injection
• Pros: Proven pattern (current extension already does this), works with Google Meet as-is
• Cons: Brittle (DOM selectors break), resource-heavy (headless Chrome per meeting), Google may block bot-like joins

Option B: Google Meet REST API + Media API (if available)

• Google has been rolling out Meet REST API for bots/companions
• Would allow joining programmatically without a browser
• Pros: Official, stable, no DOM scraping
• Cons: API access may require Google Workspace Enterprise, limited availability, still maturing

Option C: LiveKit replacement (longer-term)

• Replace Google Meet entirely with self-hosted LiveKit
• Bot joins as a native LiveKit Agents participant
• Pros: Full control, proper bot SDK, no DOM hacks, Tailscale-native
• Cons: Team has to switch away from Google Meet

Recommended: Option A now, Option C later

Flow

Google Calendar (invite taco@tinqs.com)
  → EventBridge cron (every 1-2 min)
    → API service checks calendar
      → Upcoming meeting found
        → Launches Fargate task for that meeting:
            1. Headless Chrome starts
            2. Signs in as taco@tinqs.com
            3. Joins Google Meet
            4. Captures captions → writes to S3 (or posts to API service)
            5. Listens for "Hey Taco" triggers
            6. On trigger → calls Claude with transcript context
            7. Posts answer to Meet chat
            8. Meeting ends → generates notes → writes to S3
            9. Task stops

Integration with Tailscale

• ECS tasks can join the tailnet via Tailscale sidecar container or installed in the Docker image
• API service accessible over tailnet for internal admin/dashboard
• Public API endpoints exposed via ALB or API Gateway (for Google Calendar webhooks if used)
• Meeting bot tasks communicate with API service over tailnet or AWS internal networking

Google Meet Alternatives Research (2026-04-07)

Researched 10 platforms for the longer-term self-hosted path. Full analysis below.

Recommendation: LiveKit

• Self-host on Tailscale: Single Go binary or Docker image. Zero external dependencies.
• Chat: First-class data channels via lk.chat topics.
• Bot API: Agents SDK (Python/TS/Go) — bot joins as a participant, reads/sends chat. Maps 1:1 to taco-bot.
• Transcription: Built-in STT pipeline (Deepgram, Whisper).
• License: Apache 2.0
• Migration benefit: Replaces brittle DOM scraping with proper SDK. No more breaking when Google changes their UI.

Also considered

Platform	Verdict
Matrix/Element Call	Best bot ecosystem for chat, but complex deploy. Uses LiveKit under the hood.
Galene	Ultra-lightweight (15 MB), MIT. DIY bot integration via WebSocket.
Jitsi Meet	Mature but weak bot API.
Nextcloud Talk	Good if running Nextcloud. P2P for small calls.
Whereby / Daily.co	Cloud-only — eliminated
BigBlueButton	Too heavy, education-focused
RustDesk	Remote desktop, not conferencing. Ozan uses for remote access.

GitHub → Git Studio Migration

All repos have moved from GitHub to Git Studio (git.arikigame.com). The codebase still has GitHub references that need updating:

Code changes required

File	What to change
lib/docs-search.ts	Swap GitHub Code Search API → Gitea search API (git.arikigame.com/api/v1/repos/{owner}/{repo}/contents or Gitea's topic/code search endpoints)
.env.example, .env.local.example	GITHUB_TOKEN → GITEA_TOKEN, GITHUB_DOCS_REPO → GITEA_DOCS_REPO, add GITEA_TOKEN_NAME
README.md	Remove GitHub legacy notice, update all references to Git Studio
NEXT-STEPS.md	Update env var docs, deployment instructions
RUNBOOK.md	Update env var table, deployment references
.cursor/SOUL.md	Update "GitHub Code Search" → "Gitea code search"
.cursor/MEMORY.md	Update migration status (it's done now)
package.json	repository.url → https://git.arikigame.com/tinqs-ltd/taco-bot.git
.github/workflows/agentic-pipeline.yml	Either migrate to Gitea Actions or remove if CI moves to Gitea
scripts/security-check.sh	Keep github_pat_ pattern in secret scan (still useful), add Gitea token pattern

Gitea search API

Gitea provides these search endpoints (replacing GitHub Code Search):

• Repo code search: GET /api/v1/repos/{owner}/{repo}/topics and content search via raw file access
• Repo file contents: GET /api/v1/repos/{owner}/{repo}/contents/{filepath} — read files directly
• Repo search: GET /api/v1/repos/search?q={query} — search across repos
• Token auth: Authorization: token {GITEA_TOKEN} header
• Token name tracked in GITEA_TOKEN_NAME (currently Taco-bot) for audit/rotation purposes

Deploy pipeline

CI builds Docker image → pushes to ECR → deploys to ECS. Existing agentic-pipeline.yml already has ECR push steps. Migrate triggers from GitHub Actions to Gitea Actions (or keep as manual/webhook-triggered).

Backlog

Phase 0: Migration cleanup

• Migrate lib/docs-search.ts from GitHub API → Gitea API
• Update env vars across all config files (GITHUB_* → GITEA_*)
• Update README, NEXT-STEPS, RUNBOOK — remove GitHub references
• Update .cursor/ files (SOUL.md, MEMORY.md)
• Migrate CI from GitHub Actions to Gitea Actions (ECR push + ECS deploy)
• Update package.json repo URL

Phase 1: Calendar + auto-join

• Set up taco@tinqs.com Google Workspace account
• Google Calendar API OAuth for reading Taco's calendar
• Calendar polling cron on Vercel (or push notifications via webhook)
• Headless browser meeting joiner (Puppeteer + Google auth)

Phase 2: AWS infrastructure + meeting bot core

• ECS Fargate cluster + task definitions (API service + meeting bot task)
• ALB or API Gateway for API endpoints
• EventBridge cron rule for calendar polling
• ECR repository (may already exist from CI pipeline)
• Caption capture in headless mode (port content.js logic)
• Chat injection in headless mode (port reply logic)
• Meeting notes generation (Claude summary at meeting end)
• Transcript + notes storage in S3

Phase 3: LiveKit (longer-term)

• Evaluate LiveKit self-hosted on Tailscale (Ozan)
• Prototype taco-bot agent using LiveKit Agents SDK

Decisions

• 2026-04-07: All repos moved from GitHub to Git Studio (git.arikigame.com). Codebase migration pending.
• 2026-04-07: LiveKit recommended as long-term Google Meet replacement. Ozan to evaluate.
• 2026-04-07: Product vision defined — calendar-driven auto-join bot. Full AWS deployment (ECS Fargate + S3 + EventBridge). No Vercel.
• 2026-04-07: App Runner deployed. ECR repo created. Service live at ytre5eznhp.eu-west-1.awsapprunner.com.
• 2026-04-07: LLM switched to Mistral Ministral 8B on Bedrock for testing (LLM_PROVIDER=bedrock). ~$0.0005/question vs Claude's ~$0.02/question. Anthropic API key commented out locally as safety measure.
• 2026-04-07: Domain taco.arikigame.com CNAME switched from Vercel to App Runner. ACM cert validation pending (Ozan to add DNS records in Cloudflare).
• 2026-04-07: Chrome extension caption detection fixed — poll-based on .ygicle.VbkSUe. Debounce tuning ongoing.