# Agent Repo Map

This file is an agent-facing operational map of the Flynn repo: entrypoints, key modules, conventions, config schema anchors, and debug workflows.

## Entry Points

- Daemon start: `src/cli/index.ts` -> `src/daemon/index.ts#startDaemon`
- One-shot send: `src/cli/send.ts`
- TUI:
  - Minimal: `src/frontends/tui/minimal.ts`
  - Fullscreen Ink app: `src/frontends/tui/components/App.tsx`
- Gateway server: `src/gateway/server.ts`

## Core Message Flow

1. Channel ingress/gateway request -> `src/daemon/routing.ts`
2. Session/orchestration -> `src/backends/native/orchestrator.ts`
3. Agent loop/tool execution -> `src/backends/native/agent.ts`
4. Model dispatch -> `src/models/router.ts` + provider clients in `src/models/*`

## High-Value Modules

- Config schema + defaults:
  - `src/config/schema.ts`
  - `config/default.yaml`
  - `config/profiles/*.overlay.yaml` (profile overlays)
- Model wiring:
  - `src/daemon/models.ts`
  - `src/models/router.ts`
  - `src/models/openai.ts`, `src/models/anthropic.ts`, `src/models/gemini.ts`, `src/models/bedrock.ts`, `src/models/github.ts`, `src/models/local/*`
- Tool registration chain:
  - Tool impl: `src/tools/builtin/*`
  - Export: `src/tools/builtin/index.ts`
  - Registry/bootstrap: `src/daemon/index.ts`, `src/daemon/tools.ts`
- Channel adapters:
  - `src/channels/*/adapter.ts`
  - Registration: `src/daemon/channels.ts`
- Auth stores:
  - OpenAI/Anthropic/etc: `src/auth/*`
  - Google services: `src/auth/google.ts` + `src/google/oauth.ts`
- Observability:
  - Audit logger: `src/audit/*`
  - Doctor checks: `src/cli/doctor.ts`

## Conventions

- TypeScript strict mode, NodeNext modules.
- Local imports use `.js` extension.
- Keep provider-specific branches localized in provider clients; prefer shared helpers for cross-service auth logic.
- Tests use Vitest (`*.test.ts`).

## Config Schema Anchors

- Model tiers and fallback chain: `models.*` in `src/config/schema.ts`
- Tool policy and profiles: `tools.*`
- Automation integrations:
  - Gmail watcher: `automation.gmail`
  - Google tools: `automation.gcal`, `automation.gdocs`, `automation.gdrive`, `automation.gtasks`
- Server/gateway behavior: `server.*`

## Run and Debug

```bash
pnpm dev                 # daemon watch mode
pnpm tui                 # minimal terminal UI
pnpm tui:fs              # fullscreen UI
pnpm test:run            # full test run once
pnpm lint
pnpm typecheck
```

Focused debug commands:

```bash
pnpm test:run src/models/router.test.ts src/models/openai.oauth.test.ts
pnpm test:run src/tools/builtin/gmail.test.ts src/automation/gmail.test.ts
pnpm test:run src/cli/doctor.test.ts
```

Config profile sync:

```bash
pnpm config:profiles:generate
pnpm config:profiles:check
```