docs(audit): add report, google auth runbook, and agent repo map

2026-02-23 17:12:41 -08:00
parent 092a9baeae
commit d8188b5425
7 changed files with 344 additions and 1 deletions
@@ -0,0 +1,85 @@
+# 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
+```