chore(ai): migrate to dual-agent handoff system
Split the monolithic CLAUDE.md into a durable handoff system:
- .ai/PROJECT_CONTEXT.md — stable architectural truth (stack, structure,
SaaS shape, ConnectWise, coding standards, frontend patterns, critical
lessons). Ported verbatim from the previous CLAUDE.md.
- .ai/CURRENT_TASK.md — single active task with DoD + out-of-scope.
- .ai/HANDOFF.md — resume point, kept under ~2K tokens.
- .ai/TODO.md — backlog, read only when CURRENT_TASK complete.
- .ai/DECISIONS.md — append-only architectural decision log.
- .ai/SESSION_LOG.md — append-only chronological history.
- .ai/README.md — human-facing explanation of the system.
Root agent files share a byte-identical protocol block (verified via diff):
- CLAUDE.md — primary agent, with GitNexus + gstack tooling and the
Claude Opus 4.7 co-author trailer.
- AGENTS.md — OpenAI Codex resume agent, with grep/rg fallbacks and the
Codex co-author trailer. Steps in when Claude hits session/weekly
limits.
Legacy root-level SESSION-HANDOFF.md deleted — superseded by .ai/HANDOFF.md.
It was a self-describing one-off from the Design System v4 migration and
had no external references.
Supersedes previous CLAUDE.md. Old version recoverable via
`git show pre-ai-handoff:CLAUDE.md` (tag points at commit e110fed).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
23
.ai/CURRENT_TASK.md
Normal file
23
.ai/CURRENT_TASK.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# CURRENT_TASK.md
|
||||
|
||||
<!-- EXAMPLE — replace on first real task -->
|
||||
|
||||
**Task:** One-sentence goal describing what this task accomplishes.
|
||||
|
||||
**Status:** not-started
|
||||
|
||||
**Definition of Done:**
|
||||
- [ ] Testable criterion 1 (e.g., "endpoint returns 200 with expected payload shape")
|
||||
- [ ] Testable criterion 2 (e.g., "frontend displays new field without layout regression")
|
||||
- [ ] Tests added or updated
|
||||
- [ ] `npm run build` passes (frontend) / `pytest` passes (backend)
|
||||
|
||||
**Assumptions:**
|
||||
- What we're treating as given (e.g., "existing auth middleware handles this case")
|
||||
- Constraints inherited from surrounding work
|
||||
|
||||
**Out of scope:**
|
||||
- What this task explicitly does NOT cover (prevents scope creep across handoffs)
|
||||
- Adjacent work that belongs in a separate task
|
||||
|
||||
<!-- END EXAMPLE -->
|
||||
31
.ai/DECISIONS.md
Normal file
31
.ai/DECISIONS.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# DECISIONS.md
|
||||
|
||||
> Append-only architectural decision log. Newest entries at the top.
|
||||
> Entry format:
|
||||
>
|
||||
> ```
|
||||
> ## YYYY-MM-DD — <short title>
|
||||
> **Context:** why this came up
|
||||
> **Decision:** what we chose
|
||||
> **Rejected:** what we didn't choose and why
|
||||
> **Consequences:** what this means going forward
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-24 — Adopt dual-agent handoff system (`.ai/` + `CLAUDE.md` + `AGENTS.md`)
|
||||
|
||||
**Context:** Claude Code hits session and weekly usage limits. Work stalls when the primary agent is locked out. Needed a structured way for OpenAI Codex to resume where Claude left off without losing architectural truth or drifting across sessions.
|
||||
|
||||
**Decision:** Split the old CLAUDE.md into `.ai/PROJECT_CONTEXT.md` (stable repo truth), agent-specific root files (`CLAUDE.md`, `AGENTS.md`) with a shared protocol block, and a small handoff toolkit (`CURRENT_TASK.md`, `HANDOFF.md`, `TODO.md`, `DECISIONS.md`, `SESSION_LOG.md`, `README.md`). Previous CLAUDE.md snapshotted in commit `e110fed` before the migration.
|
||||
|
||||
**Rejected:**
|
||||
- Single symlinked CLAUDE.md/AGENTS.md — diverges silently, hides agent-specific tooling differences.
|
||||
- Putting GitNexus/gstack content in AGENTS.md — Codex doesn't have those tools; would mislead the resume agent.
|
||||
- Keeping the old CLAUDE.md as-is and adding AGENTS.md alongside it — duplicated truth, drift guaranteed.
|
||||
|
||||
**Consequences:**
|
||||
- First read for either agent: `.ai/PROJECT_CONTEXT.md` + `.ai/CURRENT_TASK.md` + `.ai/HANDOFF.md`.
|
||||
- Architectural changes in the repo require updating PROJECT_CONTEXT.md, not the root agent files.
|
||||
- Git trailers differ per agent (`Claude Opus 4.7` vs `Codex`) — preserved in each root file.
|
||||
- Legacy `SESSION-HANDOFF.md` deleted in the same commit; superseded by `.ai/HANDOFF.md`.
|
||||
24
.ai/HANDOFF.md
Normal file
24
.ai/HANDOFF.md
Normal file
@@ -0,0 +1,24 @@
|
||||
<!-- Keep under ~2K tokens. Old handoffs live in SESSION_LOG.md. Do not let this file accumulate history. -->
|
||||
|
||||
# HANDOFF.md
|
||||
|
||||
**Last updated:** 2026-04-24 (America/New_York) — initial setup
|
||||
|
||||
**Active task:** See [CURRENT_TASK.md](CURRENT_TASK.md). (No real task yet — handoff system just initialized.)
|
||||
|
||||
**Branch:** `feat/flowpilot-migration`
|
||||
|
||||
**Where I left off:**
|
||||
- File: n/a
|
||||
- Next intended action: first agent to pick up real work should replace `CURRENT_TASK.md` example and start fresh here.
|
||||
|
||||
**Uncommitted state:**
|
||||
- `backend/pytest.ini`, `backend/requirements-dev.txt`, `backend/tests/conftest.py`, `backend/tests/test_rls_isolation.py` modified (pre-existing, unrelated to handoff-system migration).
|
||||
- Safe to WIP-commit? Ask Michael — these are mid-flight test isolation fixes from `dab740d`.
|
||||
|
||||
**Immediate next steps:**
|
||||
1. When picking up real work, replace this file's body with the actual resume point.
|
||||
2. Keep this file under ~2K tokens. If it grows, move older context into `SESSION_LOG.md`.
|
||||
|
||||
**Open questions / blockers:**
|
||||
- None.
|
||||
254
.ai/PROJECT_CONTEXT.md
Normal file
254
.ai/PROJECT_CONTEXT.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# PROJECT_CONTEXT.md — ResolutionFlow
|
||||
|
||||
> SaaS troubleshooting platform for MSPs. Stable architectural truth. Updated only when the repo's shape changes.
|
||||
|
||||
---
|
||||
|
||||
## Product & naming
|
||||
|
||||
Canonical product name is **ResolutionFlow**. `patherly` is the legacy internal name — still present in DB name (`patherly` on Railway, `resolutionflow` locally), some Railway service names, and historical paths. Treat as aliases, not canonical. Docker containers are `resolutionflow_*`.
|
||||
|
||||
**User terminology:** "Flows" (not Trees), "Projects" (not Procedures), "Solutions Library" (not Step Library). Maintenance flows hidden from pilot UI (backend retains them). DB column `tree_type` values unchanged.
|
||||
|
||||
---
|
||||
|
||||
## SaaS shape
|
||||
|
||||
Multi-tenant by account. Roles: `super_admin` > `team_admin` > `engineer` > `viewer`. Team admin = `role='engineer'` + `is_team_admin=True` + valid `team_id`. Never `role=='admin'` — use `is_super_admin`. Backend deps in `app/api/deps.py`: `get_current_active_user`, `require_engineer_or_admin`, `require_admin`. Frontend: `usePermissions()` hook. Central logic in `backend/app/core/permissions.py` + `frontend/src/hooks/usePermissions.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Go-to-Market Validation (pre-PMF). Backend feature-complete (55+ endpoints, 100+ tests). Phase 0.5 FlowPilot telemetry baseline accruing. See [CURRENT-STATE.md](../CURRENT-STATE.md) for live status, [03-DEVELOPMENT-ROADMAP.md](../03-DEVELOPMENT-ROADMAP.md) for phases.
|
||||
|
||||
---
|
||||
|
||||
## Tech stack
|
||||
|
||||
- **Backend:** Python 3.11 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan).
|
||||
- **Frontend:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios (token-refresh interceptor), Lucide.
|
||||
- **DB:** PostgreSQL 16 (RLS enabled Phase 4, pgvector).
|
||||
|
||||
---
|
||||
|
||||
## Project structure
|
||||
|
||||
```
|
||||
resolutionflow/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI entry
|
||||
│ │ ├── api/endpoints/ # auth, trees, sessions, admin, steps, survey, copilot, assistant_chat, integrations, flow_proposals, flowpilot_analytics
|
||||
│ │ ├── api/deps.py # auth deps (incl. require_team_admin)
|
||||
│ │ ├── api/router.py # registration
|
||||
│ │ ├── core/ # config, database, permissions, security, audit, rate_limit
|
||||
│ │ ├── models/ # SQLAlchemy (incl. FlowProposal)
|
||||
│ │ ├── schemas/ # Pydantic
|
||||
│ │ ├── services/psa/ # PSA provider pattern (base, connectwise/, autotask/, halopsa/, cache, encryption, registry, types)
|
||||
│ │ ├── services/knowledge_flywheel.py + _scheduler.py
|
||||
│ │ └── services/knowledge_gap_service.py
|
||||
│ ├── alembic/versions/ # 001-070 sequential, then hex hash
|
||||
│ ├── scripts/ # seed_data, seed_trees, seed_test_users
|
||||
│ └── tests/ # pytest integration
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # Axios client + endpoint modules
|
||||
│ │ ├── components/ # common, layout, dashboard, tree-editor, session, procedural, procedural-editor, library, step-library, ui, flowpilot
|
||||
│ │ ├── hooks/ # usePermissions, useSessionTimer, useKeyboardShortcuts
|
||||
│ │ ├── pages/
|
||||
│ │ ├── store/ # Zustand (auth, treeEditor, proceduralEditor, userPreferences, scriptGeneratorStore)
|
||||
│ │ └── types/
|
||||
│ └── (Tailwind v4 CSS-only config in src/index.css)
|
||||
├── docs/plans/archive/ # pre-March 2026 plans
|
||||
├── docs/connectwise/ # CW API reference + best-practices guides
|
||||
├── docs/LESSONS-ARCHIVE.md # archived lessons (fixes in code)
|
||||
├── .ai/ # dual-agent handoff system (see .ai/README.md)
|
||||
├── CLAUDE.md · AGENTS.md · CURRENT-STATE.md · DESIGN-SYSTEM.md · DEV-ENV.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dev commands
|
||||
|
||||
Full setup in [DEV-ENV.md](../DEV-ENV.md) (host-agnostic, with homelab Proxmox reference topology). Day-to-day:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml up -d # start stack
|
||||
cd backend && source venv/bin/activate && uvicorn app.main:app --reload
|
||||
cd frontend && npm run dev
|
||||
pytest --override-ini="addopts=" # tests (first time: CREATE DATABASE resolutionflow_test)
|
||||
cd backend && alembic upgrade head # migrate
|
||||
cd backend && alembic revision -m "desc" # manual migration (preferred per Lesson 77)
|
||||
cd backend && alembic revision --autogenerate -m "desc" # picks up drift; review carefully
|
||||
cd frontend && npm run build # stricter than tsc --noEmit — final check
|
||||
cd frontend && npx tsc -b # TS-only check when dist/ has EACCES
|
||||
docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
|
||||
python -m scripts.seed_trees # seed (from backend/)
|
||||
```
|
||||
|
||||
**Never pass `--rev-id`** to alembic — let it generate the hex hash.
|
||||
|
||||
---
|
||||
|
||||
## URLs & test users
|
||||
|
||||
**URLs:** Frontend <http://localhost:5173>, backend <http://localhost:8000>, API docs <http://localhost:8000/api/docs>.
|
||||
|
||||
**Test users** (all password `TestPass123!`): `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com`, `engineer@resolutionflow.example.com`, `pro@resolutionflow.example.com`.
|
||||
|
||||
---
|
||||
|
||||
## CI
|
||||
|
||||
Gitea (`gitea.resolutionflow.com/chihlasm/resolutionflow/actions`). `gh` CLI works for issues/PRs on the GitHub mirror, but not CI runs.
|
||||
|
||||
---
|
||||
|
||||
## Deployment (Railway)
|
||||
|
||||
- **Prod:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend).
|
||||
- Auto-deploy: Gitea push → GitHub mirror → Railway follows GitHub `main`.
|
||||
- PR environments auto-created; need manual domain generation + `VITE_API_URL` with `https://` prefix.
|
||||
- `ALLOW_RAILWAY_ORIGINS=true` for `*.up.railway.app` CORS.
|
||||
- Shared Variables (Railway project-level) auto-propagate to PR envs — use for secrets like `ANTHROPIC_API_KEY`.
|
||||
- Super admin utility: `backend/make_superadmin_simple.py list|<email>`.
|
||||
|
||||
---
|
||||
|
||||
## ConnectWise PSA
|
||||
|
||||
Reference: `docs/connectwise/` — start with `CONNECTWISE-API-REFERENCE.md`, then the `best-practices/` guides. Extracted OpenAPI spec in `connectwise-psa-resolutionflow-reference.json` (670 endpoints, v2025.16); full spec in `connectwise-psa-openapi-full.json`.
|
||||
|
||||
- **Auth:** API Key (Base64 `companyId+publicKey:privateKey`) + `clientId` header every request. `clientId` is server-side (`CW_CLIENT_ID` in `config.py`) — identifies ResolutionFlow, not per-tenant. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`.
|
||||
- **Architecture:** `services/psa/` provider pattern — `PSAProvider` base, `ConnectWiseProvider` impl, `PsaProviderRegistry` for multi-PSA dispatch. Credentials encrypted at rest via `services/psa/encryption.py` (Fernet). Per-team credentials, never per-user. Endpoints in `api/endpoints/integrations.py`. In-memory TTL cache in `services/psa/cache.py`.
|
||||
- **Integration flows:** session docs → ticket notes (`POST /service/tickets/{id}/notes`, markdown supported); ticket context → FlowPilot; callbacks via `/system/callbacks` with HMAC verification.
|
||||
- **API rules:** pin version via Accept header `application/vnd.connectwise.com+json; version=2025.16`. Paginate ≤1000/page. Dynamic base URL via `/login/companyinfo/{companyId}`. Request minimal permissions (MY, not ALL).
|
||||
|
||||
---
|
||||
|
||||
## Coding standards
|
||||
|
||||
- **Python:** type hints everywhere, async/await for DB, Pydantic v2, `DateTime(timezone=True)` always.
|
||||
- **TypeScript:** interfaces for all data, `const` over `let`, functional components + hooks, shared logic in custom hooks.
|
||||
- **Git:** feature branch before committing (`git checkout -b feat/feature-name`). Commit format: `type: description` (feat/fix/refactor/docs/test/chore). Large features: commit per phase with `npm run build` validation. Push to Gitea — auto-mirrors to GitHub (`.gitea/workflows/mirror-to-github.yml`); never push GitHub directly. (Agent-specific `Co-Authored-By` trailers live in CLAUDE.md / AGENTS.md.)
|
||||
|
||||
**After shipping:** update [CURRENT-STATE.md](../CURRENT-STATE.md) + [03-DEVELOPMENT-ROADMAP.md](../03-DEVELOPMENT-ROADMAP.md), `gh issue close #N` for resolved issues, add lessons only for non-obvious traps (otherwise let the code speak).
|
||||
|
||||
---
|
||||
|
||||
## Common tasks
|
||||
|
||||
- **New endpoint:** `endpoints/` → `router.py` → `schemas/` → tests → frontend API client.
|
||||
- **New page:** `pages/` → route in `router.tsx` → nav in `AppLayout.tsx`.
|
||||
- **New public route:** top-level in `router.tsx` alongside `/login`, not inside `ProtectedRoute`.
|
||||
- **New frontend API module:** types in `types/` → export from `types/index.ts` → client in `api/` → export from `api/index.ts`.
|
||||
- **Schema change:** update model → `alembic revision -m "desc"` → review → `alembic upgrade head`.
|
||||
- **New `VITE_*` env var:** add as `ARG` + `ENV` in `frontend/Dockerfile` for Railway builds (Lesson 60 — Railway env vars are runtime-only, Vite bakes at build time).
|
||||
- **Account sub-page:** add route in `router.tsx` under `account` children + add link card in `AccountSettingsPage.tsx` — `AccountLayout` has NO sidebar nav.
|
||||
|
||||
---
|
||||
|
||||
## Design system
|
||||
|
||||
**Source of truth: [DESIGN-SYSTEM.md](../DESIGN-SYSTEM.md).** Read before any visual change.
|
||||
|
||||
- Flat high-contrast dark theme, Sentry/PostHog-inspired. **No** glass, backdrop blur, ambient orbs, gradient surfaces.
|
||||
- Accent **electric blue** (#60a5fa dark / #2563eb light) — ≤5% of UI, interactive elements only. Warning amber (#fbbf24), info cyan (#67e8f9), success green (#34d399), danger red (#f87171). Each with `-dim` at 10% opacity.
|
||||
- Backgrounds: `bg-sidebar` (#0e1016) → `bg-page` (#16181f) → `bg-card` (#1e2028) → `bg-elevated` (#2a2d38). Borders `border-default` / `border-hover`.
|
||||
- Text: `text-heading` → `text-primary` → `text-muted-foreground` → `text-muted`.
|
||||
- Fonts: IBM Plex Sans (body), Bricolage Grotesque (heading, 700 weight for logo), JetBrains Mono (code).
|
||||
- Logo: 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque. Assets in `brand-assets/`, `frontend/src/assets/brand/`, `frontend/public/icons/`.
|
||||
- Mockups: `docs/mockups/` (HTML).
|
||||
- **Deprecated — do not use:** glass-card, glass-stat, `bg-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, ember orange as accent, cyan as accent (cyan is info only).
|
||||
|
||||
---
|
||||
|
||||
## Frontend patterns
|
||||
|
||||
- **Component basics:** `cn()` from `@/lib/utils`, Lucide icons, `Modal.tsx` for modals (mobile-responsive `items-end sm:items-center` + `max-w-full sm:max-w-lg`).
|
||||
- **Types:** Create in `types/`, export from `types/index.ts`, `import type { T } from '@/types'`.
|
||||
- **Routing:** `getTreeNavigatePath()` / `getTreeEditorPath()` from `@/lib/routing`. Tree editor is `/trees/new`. All dashboard session clicks → `/pilot/:id` regardless of `session_type`.
|
||||
- **Lazy routes:** `lazyWithRetry` from `@/lib/lazyWithRetry.ts`, not `React.lazy` (auto-reload on stale chunks).
|
||||
- **Public pages:** raw `fetch()` with full URL, NOT `apiClient` (which requires auth tokens).
|
||||
- **Toast:** `toast.warning()` not `toast.warn()`. Import from `@/lib/toast` — methods: `success`, `error`, `warning`, `info`.
|
||||
- **Assistant chat:** uses local React `useState`, not Zustand. All three send paths (`handleSend`, `sendPrefill`, `handleResumeNew`) must call `setShowTaskLane(true)` when response has actions/questions.
|
||||
- **Chat backend wiring:** `aiSessionsApi.sendChatMessage` → `/ai-sessions/{id}/chat` → `unified_chat_service.py`. NOT `assistant_chat_service.py` (removed except retention settings).
|
||||
- **FlowPilot:** Actions live in page header (Resolve/Escalate/Share Update + overflow). `useBlocker` for active-session nav guard. "Pause & Leave" auto-pauses.
|
||||
- **AI markers:** `[QUESTIONS]`, `[ACTIONS]`, `[FORK]`, `[DELTA]...[/DELTA]` (editor), `[TREE_UPDATE]` (troubleshooting builder), `[STEPS_UPDATE]` (procedural builder), `[METADATA]`. Parsed in `unified_chat_service.py`; conversation history stores stripped `display_content`. If markers disappear: check system-prompt final reminder + per-user-message `[SYSTEM: ...]` injection in `_call_anthropic_cached()`.
|
||||
- **Image uploads:** paste/attach → Railway S3 via `uploadsApi.upload()` → resized by `storage_service.resize_image_for_vision()` (Pillow, 1568px max, PNG→JPEG) → base64 → Claude multimodal blocks. Max 3/msg. Images NOT stored in history.
|
||||
- **Async select-load-apply:** guard with a ref (pattern in `AssistantChatPage` `currentChatRef`). Update synchronously on every selection change; after every `await`, bail out if `ref.current !== thisId`.
|
||||
- **Editor-Embedded Flow Assist:** `EditorAIPanel` (320px side panel) + `useEditorAI`. Ghost nodes via `_suggestion: true`. Route actions via `settings.get_model_for_action()`.
|
||||
- **Script Builder:** `/script-builder`, chat-style. Backend `ScriptBuilderSession`, `script_builder_service.py`, endpoints `/scripts/builder/`. FlowPilot handoff via `action_type: "open_script_builder"` + `sessionStorage`.
|
||||
- **Intake form field schema:** `variable_name` + `field_type` (NOT `name` / `type`).
|
||||
- **Node field priority** (copilot, summaries): `title` → `question` → `description` → `content` → `label`.
|
||||
- **Procedural sessions auto-start** on page load (no intake/Start screen). Troubleshooting flows DO have a start screen.
|
||||
|
||||
---
|
||||
|
||||
## Critical lessons
|
||||
|
||||
> Lessons 1-40 archived to [docs/LESSONS-ARCHIVE.md](../docs/LESSONS-ARCHIVE.md) — fixes baked into the codebase. **Grep the archive when an error message or symptom is unfamiliar, or after two failed attempts at resolving an issue.** Don't pre-load for routine work.
|
||||
|
||||
### Backend / data
|
||||
|
||||
- **APScheduler interval jobs always `max_instances=1`** — without it, overlapping runs reprocess records (TOCTOU).
|
||||
- **`get_db` rolls back on exception** — never remove the `await session.rollback()`, or one failed request poisons the connection with `InFailedSQLTransaction` cascading.
|
||||
- **Startup routines on tenant-isolated tables must use `_admin_session_factory()`, not `get_db()`.** Phase 4 RLS has no `app.current_account_id` set at startup. `get_service_account_id` is safe (reads cached `app.state`).
|
||||
- **Backfill migrations adding `account_id`:** grep ALL `ModelClass(` sites in service code to verify `account_id=` is passed. SQLAlchemy accepts `None` silently — Phase 4 RLS WITH CHECK surfaces the problem at runtime as `InsufficientPrivilegeError: new row violates row-level security policy`.
|
||||
- **`tree_shares.account_id = tree.account_id`**, never `current_user.account_id`. A super_admin sharing another tenant's tree must produce the share in the tree owner's tenant, or it becomes invisible post-RLS.
|
||||
- **Global tables (no `account_id`, never in RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts`. Scan at class level — one `.py` file can hold multiple classes with different columns (e.g. `ScriptCategory` vs `ScriptTemplate`).
|
||||
- **`ai_sessions.status` is VARCHAR(30)** — fits `requesting_escalation` (23 chars). Migration `f0aad74ea51b` widened from 20.
|
||||
- **PostgreSQL `func.sum(case(...))` returns `Decimal` via asyncpg** — cast to `int()` before Pydantic `dict[str, Any]`.
|
||||
- **Enhancement / branch_addition proposals need `modified_flow_data` via "Edit & Publish"** — backend 400 on direct approve. Only `new_flow` supports direct approve.
|
||||
- **Adding email types:** static async method on `EmailService` in `core/email.py`. Fire-and-forget from endpoints (log errors, don't fail the request).
|
||||
|
||||
### AI / FlowPilot
|
||||
|
||||
- **Anthropic SDK `max_retries=1`** — default of 2 can take 3× the timeout.
|
||||
- **Model tier routing:** `settings.get_model_for_action(action_type)`. Always alias form (`claude-sonnet-4-6`).
|
||||
- **FlowPilot must ask GUI-vs-script before suggesting either** when both are viable — see `FLOWPILOT_SYSTEM_PROMPT` in `flowpilot_engine.py`.
|
||||
- **Telemetry events to grep:** `anthropic.cache` (prompt-cache hit/create), `mcp.turn` (per-turn MCP availability), `mcp.fallback` (MCP silent-retry fired).
|
||||
- **Don't put literal payloads in system prompts.** Bit us twice in one day: a worked `[QUESTIONS]` example with literal "Outlook + jsmith" content, and a full DNS troubleshooting tree, both caused Claude to recite that content on unrelated tickets — the symptom looked like task-lane state leaking across chats. The fix is structural: every output example in a system prompt uses `<placeholder>` syntax (`{"text": "<one short, specific question>"}`), never literal field values. Real-looking format examples live in few-shot messages (separate file, separate code path), not system prompts. Guardrail: `tests/test_prompt_anti_parrot.py` scans every `*_PROMPT`/`*_SCHEMA`/`*_PROTOCOL`/`*_FORMAT` constant in `app/services/` and `app/core/`; CI fails when a marker block contains a literal JSON value or when a known leaked token (jsmith, DC01, ADSync, Dnscache, etc.) appears anywhere in a prompt.
|
||||
|
||||
### Frontend / UI
|
||||
|
||||
- **Flex height chain:** every ancestor from `app-shell` grid to React Flow canvas needs `flex` + `flex-1` + `min-h-0` or `h-full`. Missing `flex` collapses to 0. Same rule for FlowPilot action bar and any tall scroller.
|
||||
- **React Flow CSS in Tailwind v4:** import in `index.css`, not component JS. Override dark theme via `--xy-*` CSS vars.
|
||||
- **`text-secondary` renders invisible on dark** — Tailwind v4 maps it to `--color-secondary` (a surface color). Use `text-muted-foreground` for readable secondary text. Avoid `text-muted` for body — labels only.
|
||||
- **`bg-accent` is electric blue — never for code/kbd.** Use `bg-white/[0.12] border border-white/[0.06]` for inline code, `bg-white/[0.08]` for kbd. Accent reserved for interactive elements.
|
||||
- **`landing.css` uses self-contained `--lp-*` vars** — never `var(--color-*)` theme tokens (they resolve incorrectly outside the app shell).
|
||||
- **Never `transition: all`** — list properties explicitly, or layout props animate and jank.
|
||||
- **Date range filter end dates:** `setHours(23, 59, 59, 999)` before sending, or the day's items are excluded. For string-based date inputs, append `T23:59:59.999Z`.
|
||||
- **TopBar search:** full bar `hidden sm:block`, icon button `sm:hidden` — both open CommandPalette.
|
||||
- **Hover pop-out cards:** scrim `pointer-events-none`, expanded card has its own click handler at `z-50`, dismiss via `onMouseLeave` on wrapper. Never put handlers on the scrim.
|
||||
- **`tsc -b` in Dockerfile is stricter than `tsc --noEmit`** — enforces `noUnusedLocals` / `noUnusedParameters` as hard errors. Check IDE yellow squiggles before pushing.
|
||||
- **Dashboard prefill auto-submits** via `useEffect` + `prefillHandledRef` guard — no double-enter.
|
||||
- **Global Axios 5xx interceptor fires before component `.catch()`** — fix optional-data endpoints at the source (return `[]` / `{}` on provider failure), not in the component.
|
||||
- **Playwright strict mode:** scope selectors to avoid sidebar/main ambiguity. Use `getByRole('heading', { name })` or `.animate-scale-in` locators, not bare `getByText()`.
|
||||
|
||||
### Env / infra
|
||||
|
||||
- **Node 20.19+ required** (Vite 7). `nvm use 20` or `PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH"`.
|
||||
- **Railway backend service is `patherly`, DB name `railway`.** Public Postgres proxy: `interchange.proxy.rlwy.net:45797`.
|
||||
- **Railway Object Storage bucket `resolutionflow-uploads`.** Env vars `STORAGE_*`. boto3 in `storage_service.py`. Dockerfile needs Pillow + `libjpeg-dev` / `zlib1g-dev`.
|
||||
- **PostHog:** `PostHogProvider` + `posthog.init()` in `main.tsx`. Helpers in `lib/analytics.ts`. Env: `VITE_PUBLIC_POSTHOG_KEY`, `VITE_PUBLIC_POSTHOG_HOST`. `identifyUser()` in `authStore.fetchUser()`, `resetAnalytics()` on logout.
|
||||
- **bun PATH on devserver01:** `BUN_INSTALL="$HOME/.bun"`, `PATH="$BUN_INSTALL/bin:$PATH"`. Playwright Chromium needs `libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2`.
|
||||
- **Full-stack change:** trace schema → endpoint → API client → hook → store → UI. Don't assume one end proves the other.
|
||||
- **Dev env** — see [DEV-ENV.md](../DEV-ENV.md) for current topology, `REPO_ROOT` requirement when compose runs inside a container, Vite `allowedHosts`, linuxserver.io `group_add` + custom-cont-init.d workaround, `docker compose up` no-op-on-unchanged-hash gotcha.
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| Detailed status | [CURRENT-STATE.md](../CURRENT-STATE.md) |
|
||||
| Roadmap | [03-DEVELOPMENT-ROADMAP.md](../03-DEVELOPMENT-ROADMAP.md) |
|
||||
| Design system | [DESIGN-SYSTEM.md](../DESIGN-SYSTEM.md) |
|
||||
| Dev env | [DEV-ENV.md](../DEV-ENV.md) |
|
||||
| Archived lessons | [docs/LESSONS-ARCHIVE.md](../docs/LESSONS-ARCHIVE.md) |
|
||||
| ConnectWise API | `docs/connectwise/` |
|
||||
| GitHub issues | `gh issue list --state open` |
|
||||
| Local API docs | <http://localhost:8000/api/docs> |
|
||||
| Handoff system | [.ai/README.md](README.md) |
|
||||
42
.ai/README.md
Normal file
42
.ai/README.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# .ai/ — dual-agent handoff system
|
||||
|
||||
ResolutionFlow uses two coding agents: **Claude Code** (primary) and **OpenAI Codex** (resume when Claude hits session or weekly limits). This directory holds the shared state that lets either agent start a session with full context.
|
||||
|
||||
## Files
|
||||
|
||||
| File | Holds | Written when | Read when |
|
||||
|---|---|---|---|
|
||||
| [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) | Stable repo truth: stack, structure, SaaS shape, ConnectWise, coding standards, frontend patterns, critical lessons | Only when the repo's shape changes | Every session start |
|
||||
| [CURRENT_TASK.md](CURRENT_TASK.md) | The single active task: goal, DoD, assumptions, out-of-scope | On task start; status updates during work | Every session start |
|
||||
| [HANDOFF.md](HANDOFF.md) | Exact resume point: branch, where you left off, next steps, blockers | On session end / context-window limit | Every session start (most important) |
|
||||
| [TODO.md](TODO.md) | Backlog of work NOT currently active | When deferring or queueing work | Only when `CURRENT_TASK.md` is `complete` |
|
||||
| [DECISIONS.md](DECISIONS.md) | Append-only architectural decision log | When an architectural choice is made | Skim top entries each session |
|
||||
| [SESSION_LOG.md](SESSION_LOG.md) | Append-only chronological history | On session end | Only when broader context is needed |
|
||||
|
||||
Agent-specific tooling lives at the repo root:
|
||||
- [../CLAUDE.md](../CLAUDE.md) — Claude Code's tooling (GitNexus, gstack slash commands, Claude trailer)
|
||||
- [../AGENTS.md](../AGENTS.md) — OpenAI Codex's tooling (grep/rg fallbacks, Codex trailer)
|
||||
|
||||
Both root files contain an **identical shared-protocol block**. If you edit one, edit the other.
|
||||
|
||||
## The handoff ritual
|
||||
|
||||
At session end (limit hit, task complete, or user stop): update `HANDOFF.md` to reflect the new resume point, update `CURRENT_TASK.md` status if it changed, append to `DECISIONS.md` if you made an architectural call, append a session entry to `SESSION_LOG.md`, and WIP-commit any dirty working tree with `wip(handoff): <one-line>` unless told otherwise. Don't push.
|
||||
|
||||
## How to invoke a resume
|
||||
|
||||
Tell the agent:
|
||||
|
||||
> Read CLAUDE.md (or AGENTS.md) and follow its instructions.
|
||||
|
||||
The agent will read its root file, which directs it to `.ai/PROJECT_CONTEXT.md`, `.ai/CURRENT_TASK.md`, and `.ai/HANDOFF.md` before doing anything else.
|
||||
|
||||
## Recovery
|
||||
|
||||
The previous monolithic CLAUDE.md is recoverable via:
|
||||
|
||||
```bash
|
||||
git show pre-ai-handoff:CLAUDE.md
|
||||
```
|
||||
|
||||
(Tag `pre-ai-handoff` on commit `e110fed` — the snapshot taken before this migration.)
|
||||
21
.ai/SESSION_LOG.md
Normal file
21
.ai/SESSION_LOG.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# SESSION_LOG.md
|
||||
|
||||
> Append-only chronological record. Newest entries at the top. Skim when broader context is needed.
|
||||
> Entry format:
|
||||
>
|
||||
> ```
|
||||
> ## YYYY-MM-DD HH:MM <timezone> — <agent> — <one-line summary>
|
||||
> - What was accomplished
|
||||
> - What was left for next session
|
||||
> - Files touched
|
||||
> ```
|
||||
|
||||
---
|
||||
|
||||
## 2026-04-24 — Claude Code — Migrate to dual-agent handoff system
|
||||
|
||||
- Split CLAUDE.md into `.ai/PROJECT_CONTEXT.md` + shared-protocol root files (`CLAUDE.md`, `AGENTS.md`).
|
||||
- Seeded `CURRENT_TASK.md`, `HANDOFF.md`, `TODO.md`, `DECISIONS.md`, `SESSION_LOG.md`, `README.md`.
|
||||
- Deleted legacy `SESSION-HANDOFF.md` (superseded).
|
||||
- Left for next session: first real feature task should replace the seed `CURRENT_TASK.md` and update `HANDOFF.md` with real resume state.
|
||||
- Files touched: `.ai/*.md` (created), `CLAUDE.md` (rewritten), `AGENTS.md` (created), `SESSION-HANDOFF.md` (deleted).
|
||||
12
.ai/TODO.md
Normal file
12
.ai/TODO.md
Normal file
@@ -0,0 +1,12 @@
|
||||
# TODO.md
|
||||
|
||||
> Backlog of work NOT currently active. Read only when `CURRENT_TASK.md` status is `complete`.
|
||||
> Format: `- [ ] short description — optional link to issue/PR`
|
||||
|
||||
## Up next
|
||||
|
||||
- [ ] (seed entry — replace with real next-up items)
|
||||
|
||||
## Backlog
|
||||
|
||||
- [ ] (seed entry — replace with real backlog items)
|
||||
61
AGENTS.md
Normal file
61
AGENTS.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# AGENTS.md — ResolutionFlow
|
||||
|
||||
You are OpenAI Codex, the resume agent for ResolutionFlow. Claude Code is the primary coding agent; you step in when Claude hits session or weekly limits.
|
||||
|
||||
The first thing to do every session: read [`.ai/PROJECT_CONTEXT.md`](.ai/PROJECT_CONTEXT.md), [`.ai/CURRENT_TASK.md`](.ai/CURRENT_TASK.md), and [`.ai/HANDOFF.md`](.ai/HANDOFF.md). The ritual is spelled out below.
|
||||
|
||||
> The protocol section below is byte-identical to the shared block in CLAUDE.md. If you edit one, edit the other.
|
||||
|
||||
## Shared protocol
|
||||
|
||||
### Startup ritual (every session)
|
||||
|
||||
1. Read `.ai/PROJECT_CONTEXT.md` — architectural truth for this repo.
|
||||
2. Read `.ai/CURRENT_TASK.md` — what we're actively working on.
|
||||
3. Read `.ai/HANDOFF.md` — exact resume point.
|
||||
4. Skim `.ai/DECISIONS.md` for recent entries relevant to the current task.
|
||||
5. Run `git log --oneline -15` and `git status`.
|
||||
6. Before taking action, state back in two sentences: the current goal and your proposed next action.
|
||||
|
||||
### Handoff ritual (session end — limit hit, task complete, or user stop)
|
||||
|
||||
1. Update `.ai/HANDOFF.md` to reflect new state. Keep it under ~2K tokens.
|
||||
2. If `CURRENT_TASK.md` status changed, update it.
|
||||
3. If you made an architectural decision, append to `.ai/DECISIONS.md`.
|
||||
4. Append a session entry to `.ai/SESSION_LOG.md`.
|
||||
5. If working tree is dirty, commit WIP with `wip(handoff): <one-line summary>`. Do not push unless explicitly asked.
|
||||
|
||||
### Writing rules for .ai/ files
|
||||
|
||||
- Use model-neutral voice in `HANDOFF.md`, `SESSION_LOG.md`, `DECISIONS.md` ("previous session did X", NOT "Claude did X" or "Codex did X"). Exception: `SESSION_LOG.md` entries include an `<agent>` field in the header.
|
||||
- Do not duplicate content between files. `CURRENT_TASK.md` holds the goal, `HANDOFF.md` holds the resume point, `TODO.md` holds the backlog. If unsure where something goes, check `.ai/README.md`.
|
||||
- Don't invent facts about the repo. If you're uncertain, write `TODO: confirm` and flag it.
|
||||
|
||||
### Project principle
|
||||
|
||||
Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs for review before taking them.
|
||||
|
||||
## Codex-specific notes
|
||||
|
||||
### Tooling you do NOT have
|
||||
|
||||
- **No GitNexus tools.** Use `grep -r`, `rg`, `git grep`, or `find` for code search. For blast-radius reasoning, grep call sites manually and read the files.
|
||||
- **No gstack slash commands** (`/review`, `/ship`, `/qa`, `/browse`, `/investigate`, `/design-review`, `/plan-*`). Run the equivalent work directly: `pytest` for tests, `npm run build` for frontend validation, manual PR description for review flow.
|
||||
- **No `/codex` second-opinion command.** You are Codex.
|
||||
|
||||
### Git trailer
|
||||
|
||||
Every commit: `Co-Authored-By: Codex <noreply@openai.com>`
|
||||
|
||||
### Model selection
|
||||
|
||||
Handled on OpenAI's side. Do not attempt to set Anthropic model aliases for your own runtime. (The repo's application code still uses Anthropic aliases like `claude-sonnet-4-6` via `settings.get_model_for_action()` — that's runtime config for the product, not your agent.)
|
||||
|
||||
### Reviewing Claude's work
|
||||
|
||||
When you resume from a Claude session, assume some decisions may have been informed by GitNexus queries or gstack commands whose output isn't in the handoff. If a decision looks unverified from the `.ai/` files alone, either:
|
||||
|
||||
- re-verify with `grep`/`rg`/file reads, or
|
||||
- flag it in `HANDOFF.md` under "Open questions" so Michael or Claude can confirm on the next handoff.
|
||||
|
||||
Do not assume tooling output that isn't written down.
|
||||
252
CLAUDE.md
252
CLAUDE.md
@@ -1,215 +1,43 @@
|
||||
# CLAUDE.md — ResolutionFlow
|
||||
|
||||
> SaaS troubleshooting platform for MSPs. Last reviewed 2026-04-19.
|
||||
You are Claude Code, the primary coding agent for ResolutionFlow. OpenAI Codex is the resume agent when you hit session or weekly limits.
|
||||
|
||||
**Naming:** Canonical product name is **ResolutionFlow**. `patherly` is the legacy internal name — still present in DB name (`patherly` on Railway, `resolutionflow` locally), some Railway service names, and historical paths. Treat as aliases, not canonical. Docker containers are `resolutionflow_*`.
|
||||
The first thing to do every session: read [`.ai/PROJECT_CONTEXT.md`](.ai/PROJECT_CONTEXT.md), [`.ai/CURRENT_TASK.md`](.ai/CURRENT_TASK.md), and [`.ai/HANDOFF.md`](.ai/HANDOFF.md). The ritual is spelled out below.
|
||||
|
||||
**User terminology:** "Flows" (not Trees), "Projects" (not Procedures), "Solutions Library" (not Step Library). Maintenance flows hidden from pilot UI (backend retains them). DB column `tree_type` values unchanged.
|
||||
> The protocol section below is byte-identical to the shared block in AGENTS.md. If you edit one, edit the other.
|
||||
|
||||
**SaaS shape:** Multi-tenant by account. Roles: `super_admin` > `team_admin` > `engineer` > `viewer`. Team admin = `role='engineer'` + `is_team_admin=True` + valid `team_id`. Never `role=='admin'` — use `is_super_admin`. Backend deps in `app/api/deps.py`: `get_current_active_user`, `require_engineer_or_admin`, `require_admin`. Frontend: `usePermissions()` hook. Central logic in `backend/app/core/permissions.py` + `frontend/src/hooks/usePermissions.ts`.
|
||||
## Shared protocol
|
||||
|
||||
**Status:** Go-to-Market Validation (pre-PMF). Backend feature-complete (55+ endpoints, 100+ tests). Phase 0.5 FlowPilot telemetry baseline accruing. See `CURRENT-STATE.md` for live status, `03-DEVELOPMENT-ROADMAP.md` for phases.
|
||||
### Startup ritual (every session)
|
||||
|
||||
**Principle:** Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs for review before taking them.
|
||||
1. Read `.ai/PROJECT_CONTEXT.md` — architectural truth for this repo.
|
||||
2. Read `.ai/CURRENT_TASK.md` — what we're actively working on.
|
||||
3. Read `.ai/HANDOFF.md` — exact resume point.
|
||||
4. Skim `.ai/DECISIONS.md` for recent entries relevant to the current task.
|
||||
5. Run `git log --oneline -15` and `git status`.
|
||||
6. Before taking action, state back in two sentences: the current goal and your proposed next action.
|
||||
|
||||
---
|
||||
### Handoff ritual (session end — limit hit, task complete, or user stop)
|
||||
|
||||
## Tech stack
|
||||
1. Update `.ai/HANDOFF.md` to reflect new state. Keep it under ~2K tokens.
|
||||
2. If `CURRENT_TASK.md` status changed, update it.
|
||||
3. If you made an architectural decision, append to `.ai/DECISIONS.md`.
|
||||
4. Append a session entry to `.ai/SESSION_LOG.md`.
|
||||
5. If working tree is dirty, commit WIP with `wip(handoff): <one-line summary>`. Do not push unless explicitly asked.
|
||||
|
||||
- **Backend:** Python 3.11 + FastAPI, SQLAlchemy 2.0 async (asyncpg), Alembic, Pydantic v2, JWT (python-jose + bcrypt, JTI refresh rotation), APScheduler (in-process with FastAPI lifespan).
|
||||
- **Frontend:** React 19 + Vite + TypeScript, Tailwind v4 (CSS-only config in `index.css`), Zustand (immer + zundo), React Router v7, Axios (token-refresh interceptor), Lucide.
|
||||
- **DB:** PostgreSQL 16 (RLS enabled Phase 4, pgvector).
|
||||
### Writing rules for .ai/ files
|
||||
|
||||
---
|
||||
- Use model-neutral voice in `HANDOFF.md`, `SESSION_LOG.md`, `DECISIONS.md` ("previous session did X", NOT "Claude did X" or "Codex did X"). Exception: `SESSION_LOG.md` entries include an `<agent>` field in the header.
|
||||
- Do not duplicate content between files. `CURRENT_TASK.md` holds the goal, `HANDOFF.md` holds the resume point, `TODO.md` holds the backlog. If unsure where something goes, check `.ai/README.md`.
|
||||
- Don't invent facts about the repo. If you're uncertain, write `TODO: confirm` and flag it.
|
||||
|
||||
## Project structure
|
||||
### Project principle
|
||||
|
||||
```
|
||||
resolutionflow/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI entry
|
||||
│ │ ├── api/endpoints/ # auth, trees, sessions, admin, steps, survey, copilot, assistant_chat, integrations, flow_proposals, flowpilot_analytics
|
||||
│ │ ├── api/deps.py # auth deps (incl. require_team_admin)
|
||||
│ │ ├── api/router.py # registration
|
||||
│ │ ├── core/ # config, database, permissions, security, audit, rate_limit
|
||||
│ │ ├── models/ # SQLAlchemy (incl. FlowProposal)
|
||||
│ │ ├── schemas/ # Pydantic
|
||||
│ │ ├── services/psa/ # PSA provider pattern (base, connectwise/, autotask/, halopsa/, cache, encryption, registry, types)
|
||||
│ │ ├── services/knowledge_flywheel.py + _scheduler.py
|
||||
│ │ └── services/knowledge_gap_service.py
|
||||
│ ├── alembic/versions/ # 001-070 sequential, then hex hash
|
||||
│ ├── scripts/ # seed_data, seed_trees, seed_test_users
|
||||
│ └── tests/ # pytest integration
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # Axios client + endpoint modules
|
||||
│ │ ├── components/ # common, layout, dashboard, tree-editor, session, procedural, procedural-editor, library, step-library, ui, flowpilot
|
||||
│ │ ├── hooks/ # usePermissions, useSessionTimer, useKeyboardShortcuts
|
||||
│ │ ├── pages/
|
||||
│ │ ├── store/ # Zustand (auth, treeEditor, proceduralEditor, userPreferences, scriptGeneratorStore)
|
||||
│ │ └── types/
|
||||
│ └── (Tailwind v4 CSS-only config in src/index.css)
|
||||
├── docs/plans/archive/ # pre-March 2026 plans
|
||||
├── docs/connectwise/ # CW API reference + best-practices guides
|
||||
├── docs/LESSONS-ARCHIVE.md # archived lessons (fixes in code)
|
||||
├── CLAUDE.md · CURRENT-STATE.md · DESIGN-SYSTEM.md · DEV-ENV.md
|
||||
```
|
||||
Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs for review before taking them.
|
||||
|
||||
---
|
||||
## Claude-specific tooling
|
||||
|
||||
## Design system
|
||||
|
||||
**Source of truth: [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md).** Read before any visual change.
|
||||
|
||||
- Flat high-contrast dark theme, Sentry/PostHog-inspired. **No** glass, backdrop blur, ambient orbs, gradient surfaces.
|
||||
- Accent **electric blue** (#60a5fa dark / #2563eb light) — ≤5% of UI, interactive elements only. Warning amber (#fbbf24), info cyan (#67e8f9), success green (#34d399), danger red (#f87171). Each with `-dim` at 10% opacity.
|
||||
- Backgrounds: `bg-sidebar` (#0e1016) → `bg-page` (#16181f) → `bg-card` (#1e2028) → `bg-elevated` (#2a2d38). Borders `border-default` / `border-hover`.
|
||||
- Text: `text-heading` → `text-primary` → `text-muted-foreground` → `text-muted`.
|
||||
- Fonts: IBM Plex Sans (body), Bricolage Grotesque (heading, 700 weight for logo), JetBrains Mono (code).
|
||||
- Logo: 30px gradient square (ember orange) + "ResolutionFlow" in Bricolage Grotesque. Assets in `brand-assets/`, `frontend/src/assets/brand/`, `frontend/public/icons/`.
|
||||
- Mockups: `docs/mockups/` (HTML).
|
||||
- **Deprecated — do not use:** glass-card, glass-stat, `bg-gradient-brand`, `backdrop-filter: blur()`, ambient orbs, purple gradients, ember orange as accent, cyan as accent (cyan is info only).
|
||||
|
||||
---
|
||||
|
||||
## ConnectWise PSA
|
||||
|
||||
Reference: `docs/connectwise/` — start with `CONNECTWISE-API-REFERENCE.md`, then the `best-practices/` guides. Extracted OpenAPI spec in `connectwise-psa-resolutionflow-reference.json` (670 endpoints, v2025.16); full spec in `connectwise-psa-openapi-full.json`.
|
||||
|
||||
- **Auth:** API Key (Base64 `companyId+publicKey:privateKey`) + `clientId` header every request. `clientId` is server-side (`CW_CLIENT_ID` in `config.py`) — identifies ResolutionFlow, not per-tenant. Per-connection: `company_id`, `public_key`, `private_key`, `server_url`.
|
||||
- **Architecture:** `services/psa/` provider pattern — `PSAProvider` base, `ConnectWiseProvider` impl, `PsaProviderRegistry` for multi-PSA dispatch. Credentials encrypted at rest via `services/psa/encryption.py` (Fernet). Per-team credentials, never per-user. Endpoints in `api/endpoints/integrations.py`. In-memory TTL cache in `services/psa/cache.py`.
|
||||
- **Integration flows:** session docs → ticket notes (`POST /service/tickets/{id}/notes`, markdown supported); ticket context → FlowPilot; callbacks via `/system/callbacks` with HMAC verification.
|
||||
- **API rules:** pin version via Accept header `application/vnd.connectwise.com+json; version=2025.16`. Paginate ≤1000/page. Dynamic base URL via `/login/companyinfo/{companyId}`. Request minimal permissions (MY, not ALL).
|
||||
|
||||
---
|
||||
|
||||
## Dev commands
|
||||
|
||||
Full setup in [DEV-ENV.md](DEV-ENV.md) (host-agnostic, with homelab Proxmox reference topology). Day-to-day:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.dev.yml up -d # start stack
|
||||
cd backend && source venv/bin/activate && uvicorn app.main:app --reload
|
||||
cd frontend && npm run dev
|
||||
pytest --override-ini="addopts=" # tests (first time: CREATE DATABASE resolutionflow_test)
|
||||
cd backend && alembic upgrade head # migrate
|
||||
cd backend && alembic revision -m "desc" # manual migration (preferred per Lesson 77)
|
||||
cd backend && alembic revision --autogenerate -m "desc" # picks up drift; review carefully
|
||||
cd frontend && npm run build # stricter than tsc --noEmit — final check
|
||||
cd frontend && npx tsc -b # TS-only check when dist/ has EACCES
|
||||
docker exec -it resolutionflow_postgres psql -U postgres -d resolutionflow
|
||||
python -m scripts.seed_trees # seed (from backend/)
|
||||
```
|
||||
|
||||
**URLs:** Frontend <http://localhost:5173>, backend <http://localhost:8000>, API docs <http://localhost:8000/api/docs>.
|
||||
|
||||
**Test users** (all password `TestPass123!`): `admin@resolutionflow.example.com` (super_admin), `teamadmin@resolutionflow.example.com`, `engineer@resolutionflow.example.com`, `pro@resolutionflow.example.com`.
|
||||
|
||||
**CI:** Gitea (`gitea.resolutionflow.com/chihlasm/resolutionflow/actions`). `gh` CLI works for issues/PRs on the GitHub mirror, but not CI runs.
|
||||
|
||||
**Never pass `--rev-id`** to alembic — let it generate the hex hash.
|
||||
|
||||
---
|
||||
|
||||
## Common tasks
|
||||
|
||||
- **New endpoint:** `endpoints/` → `router.py` → `schemas/` → tests → frontend API client.
|
||||
- **New page:** `pages/` → route in `router.tsx` → nav in `AppLayout.tsx`.
|
||||
- **New public route:** top-level in `router.tsx` alongside `/login`, not inside `ProtectedRoute`.
|
||||
- **New frontend API module:** types in `types/` → export from `types/index.ts` → client in `api/` → export from `api/index.ts`.
|
||||
- **Schema change:** update model → `alembic revision -m "desc"` → review → `alembic upgrade head`.
|
||||
- **New `VITE_*` env var:** add as `ARG` + `ENV` in `frontend/Dockerfile` for Railway builds (Lesson 60 — Railway env vars are runtime-only, Vite bakes at build time).
|
||||
- **Account sub-page:** add route in `router.tsx` under `account` children + add link card in `AccountSettingsPage.tsx` — `AccountLayout` has NO sidebar nav.
|
||||
|
||||
---
|
||||
|
||||
## Coding standards
|
||||
|
||||
- **Python:** type hints everywhere, async/await for DB, Pydantic v2, `DateTime(timezone=True)` always.
|
||||
- **TypeScript:** interfaces for all data, `const` over `let`, functional components + hooks, shared logic in custom hooks.
|
||||
- **Git:** feature branch before committing (`git checkout -b feat/feature-name`). Format: `type: description` (feat/fix/refactor/docs/test/chore). Always `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`. Large features: commit per phase with `npm run build` validation. Push to Gitea — auto-mirrors to GitHub (`.gitea/workflows/mirror-to-github.yml`); never push GitHub directly.
|
||||
|
||||
**After shipping:** update `CURRENT-STATE.md` + `03-DEVELOPMENT-ROADMAP.md`, `gh issue close #N` for resolved issues, add lessons here only for non-obvious traps (otherwise let the code speak).
|
||||
|
||||
---
|
||||
|
||||
## Frontend patterns
|
||||
|
||||
- **Component basics:** `cn()` from `@/lib/utils`, Lucide icons, `Modal.tsx` for modals (mobile-responsive `items-end sm:items-center` + `max-w-full sm:max-w-lg`).
|
||||
- **Types:** Create in `types/`, export from `types/index.ts`, `import type { T } from '@/types'`.
|
||||
- **Routing:** `getTreeNavigatePath()` / `getTreeEditorPath()` from `@/lib/routing`. Tree editor is `/trees/new`. All dashboard session clicks → `/pilot/:id` regardless of `session_type`.
|
||||
- **Lazy routes:** `lazyWithRetry` from `@/lib/lazyWithRetry.ts`, not `React.lazy` (auto-reload on stale chunks).
|
||||
- **Public pages:** raw `fetch()` with full URL, NOT `apiClient` (which requires auth tokens).
|
||||
- **Toast:** `toast.warning()` not `toast.warn()`. Import from `@/lib/toast` — methods: `success`, `error`, `warning`, `info`.
|
||||
- **Assistant chat:** uses local React `useState`, not Zustand. All three send paths (`handleSend`, `sendPrefill`, `handleResumeNew`) must call `setShowTaskLane(true)` when response has actions/questions.
|
||||
- **Chat backend wiring:** `aiSessionsApi.sendChatMessage` → `/ai-sessions/{id}/chat` → `unified_chat_service.py`. NOT `assistant_chat_service.py` (removed except retention settings).
|
||||
- **FlowPilot:** Actions live in page header (Resolve/Escalate/Share Update + overflow). `useBlocker` for active-session nav guard. "Pause & Leave" auto-pauses.
|
||||
- **AI markers:** `[QUESTIONS]`, `[ACTIONS]`, `[FORK]`, `[DELTA]...[/DELTA]` (editor), `[TREE_UPDATE]` (troubleshooting builder), `[STEPS_UPDATE]` (procedural builder), `[METADATA]`. Parsed in `unified_chat_service.py`; conversation history stores stripped `display_content`. If markers disappear: check system-prompt final reminder + per-user-message `[SYSTEM: ...]` injection in `_call_anthropic_cached()`.
|
||||
- **Image uploads:** paste/attach → Railway S3 via `uploadsApi.upload()` → resized by `storage_service.resize_image_for_vision()` (Pillow, 1568px max, PNG→JPEG) → base64 → Claude multimodal blocks. Max 3/msg. Images NOT stored in history.
|
||||
- **Async select-load-apply:** guard with a ref (pattern in `AssistantChatPage` `currentChatRef`). Update synchronously on every selection change; after every `await`, bail out if `ref.current !== thisId`.
|
||||
- **Editor-Embedded Flow Assist:** `EditorAIPanel` (320px side panel) + `useEditorAI`. Ghost nodes via `_suggestion: true`. Route actions via `settings.get_model_for_action()`.
|
||||
- **Script Builder:** `/script-builder`, chat-style. Backend `ScriptBuilderSession`, `script_builder_service.py`, endpoints `/scripts/builder/`. FlowPilot handoff via `action_type: "open_script_builder"` + `sessionStorage`.
|
||||
- **Intake form field schema:** `variable_name` + `field_type` (NOT `name` / `type`).
|
||||
- **Node field priority** (copilot, summaries): `title` → `question` → `description` → `content` → `label`.
|
||||
- **Procedural sessions auto-start** on page load (no intake/Start screen). Troubleshooting flows DO have a start screen.
|
||||
|
||||
---
|
||||
|
||||
## Critical lessons
|
||||
|
||||
> Lessons 1-40 archived to `docs/LESSONS-ARCHIVE.md` — fixes baked into the codebase. **Grep the archive when an error message or symptom is unfamiliar, or after two failed attempts at resolving an issue.** Don't pre-load for routine work.
|
||||
|
||||
### Backend / data
|
||||
|
||||
- **APScheduler interval jobs always `max_instances=1`** — without it, overlapping runs reprocess records (TOCTOU).
|
||||
- **`get_db` rolls back on exception** — never remove the `await session.rollback()`, or one failed request poisons the connection with `InFailedSQLTransaction` cascading.
|
||||
- **Startup routines on tenant-isolated tables must use `_admin_session_factory()`, not `get_db()`.** Phase 4 RLS has no `app.current_account_id` set at startup. `get_service_account_id` is safe (reads cached `app.state`).
|
||||
- **Backfill migrations adding `account_id`:** grep ALL `ModelClass(` sites in service code to verify `account_id=` is passed. SQLAlchemy accepts `None` silently — Phase 4 RLS WITH CHECK surfaces the problem at runtime as `InsufficientPrivilegeError: new row violates row-level security policy`.
|
||||
- **`tree_shares.account_id = tree.account_id`**, never `current_user.account_id`. A super_admin sharing another tenant's tree must produce the share in the tree owner's tenant, or it becomes invisible post-RLS.
|
||||
- **Global tables (no `account_id`, never in RLS migrations):** `script_categories`, `platform_steps`, `template_trees`, `plan_feature_defaults`, `accounts`. Scan at class level — one `.py` file can hold multiple classes with different columns (e.g. `ScriptCategory` vs `ScriptTemplate`).
|
||||
- **`ai_sessions.status` is VARCHAR(30)** — fits `requesting_escalation` (23 chars). Migration `f0aad74ea51b` widened from 20.
|
||||
- **PostgreSQL `func.sum(case(...))` returns `Decimal` via asyncpg** — cast to `int()` before Pydantic `dict[str, Any]`.
|
||||
- **Enhancement / branch_addition proposals need `modified_flow_data` via "Edit & Publish"** — backend 400 on direct approve. Only `new_flow` supports direct approve.
|
||||
- **Adding email types:** static async method on `EmailService` in `core/email.py`. Fire-and-forget from endpoints (log errors, don't fail the request).
|
||||
|
||||
### AI / FlowPilot
|
||||
|
||||
- **Anthropic SDK `max_retries=1`** — default of 2 can take 3× the timeout.
|
||||
- **Model tier routing:** `settings.get_model_for_action(action_type)`. Always alias form (`claude-sonnet-4-6`).
|
||||
- **FlowPilot must ask GUI-vs-script before suggesting either** when both are viable — see `FLOWPILOT_SYSTEM_PROMPT` in `flowpilot_engine.py`.
|
||||
- **Telemetry events to grep:** `anthropic.cache` (prompt-cache hit/create), `mcp.turn` (per-turn MCP availability), `mcp.fallback` (MCP silent-retry fired).
|
||||
- **Don't put literal payloads in system prompts.** Bit us twice in one day: a worked `[QUESTIONS]` example with literal "Outlook + jsmith" content, and a full DNS troubleshooting tree, both caused Claude to recite that content on unrelated tickets — the symptom looked like task-lane state leaking across chats. The fix is structural: every output example in a system prompt uses `<placeholder>` syntax (`{"text": "<one short, specific question>"}`), never literal field values. Real-looking format examples live in few-shot messages (separate file, separate code path), not system prompts. Guardrail: `tests/test_prompt_anti_parrot.py` scans every `*_PROMPT`/`*_SCHEMA`/`*_PROTOCOL`/`*_FORMAT` constant in `app/services/` and `app/core/`; CI fails when a marker block contains a literal JSON value or when a known leaked token (jsmith, DC01, ADSync, Dnscache, etc.) appears anywhere in a prompt.
|
||||
|
||||
### Frontend / UI
|
||||
|
||||
- **Flex height chain:** every ancestor from `app-shell` grid to React Flow canvas needs `flex` + `flex-1` + `min-h-0` or `h-full`. Missing `flex` collapses to 0. Same rule for FlowPilot action bar and any tall scroller.
|
||||
- **React Flow CSS in Tailwind v4:** import in `index.css`, not component JS. Override dark theme via `--xy-*` CSS vars.
|
||||
- **`text-secondary` renders invisible on dark** — Tailwind v4 maps it to `--color-secondary` (a surface color). Use `text-muted-foreground` for readable secondary text. Avoid `text-muted` for body — labels only.
|
||||
- **`bg-accent` is electric blue — never for code/kbd.** Use `bg-white/[0.12] border border-white/[0.06]` for inline code, `bg-white/[0.08]` for kbd. Accent reserved for interactive elements.
|
||||
- **`landing.css` uses self-contained `--lp-*` vars** — never `var(--color-*)` theme tokens (they resolve incorrectly outside the app shell).
|
||||
- **Never `transition: all`** — list properties explicitly, or layout props animate and jank.
|
||||
- **Date range filter end dates:** `setHours(23, 59, 59, 999)` before sending, or the day's items are excluded. For string-based date inputs, append `T23:59:59.999Z`.
|
||||
- **TopBar search:** full bar `hidden sm:block`, icon button `sm:hidden` — both open CommandPalette.
|
||||
- **Hover pop-out cards:** scrim `pointer-events-none`, expanded card has its own click handler at `z-50`, dismiss via `onMouseLeave` on wrapper. Never put handlers on the scrim.
|
||||
- **`tsc -b` in Dockerfile is stricter than `tsc --noEmit`** — enforces `noUnusedLocals` / `noUnusedParameters` as hard errors. Check IDE yellow squiggles before pushing.
|
||||
- **Dashboard prefill auto-submits** via `useEffect` + `prefillHandledRef` guard — no double-enter.
|
||||
- **Global Axios 5xx interceptor fires before component `.catch()`** — fix optional-data endpoints at the source (return `[]` / `{}` on provider failure), not in the component.
|
||||
- **Playwright strict mode:** scope selectors to avoid sidebar/main ambiguity. Use `getByRole('heading', { name })` or `.animate-scale-in` locators, not bare `getByText()`.
|
||||
|
||||
### Env / infra
|
||||
|
||||
- **Node 20.19+ required** (Vite 7). `nvm use 20` or `PATH="$HOME/.nvm/versions/node/v20.19.0/bin:$PATH"`.
|
||||
- **Railway backend service is `patherly`, DB name `railway`.** Public Postgres proxy: `interchange.proxy.rlwy.net:45797`.
|
||||
- **Railway Object Storage bucket `resolutionflow-uploads`.** Env vars `STORAGE_*`. boto3 in `storage_service.py`. Dockerfile needs Pillow + `libjpeg-dev` / `zlib1g-dev`.
|
||||
- **PostHog:** `PostHogProvider` + `posthog.init()` in `main.tsx`. Helpers in `lib/analytics.ts`. Env: `VITE_PUBLIC_POSTHOG_KEY`, `VITE_PUBLIC_POSTHOG_HOST`. `identifyUser()` in `authStore.fetchUser()`, `resetAnalytics()` on logout.
|
||||
- **bun PATH on devserver01:** `BUN_INSTALL="$HOME/.bun"`, `PATH="$BUN_INSTALL/bin:$PATH"`. Playwright Chromium needs `libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libatspi2.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2`.
|
||||
- **Full-stack change:** trace schema → endpoint → API client → hook → store → UI. Don't assume one end proves the other.
|
||||
- **Dev env** — see DEV-ENV.md for current topology, `REPO_ROOT` requirement when compose runs inside a container, Vite `allowedHosts`, linuxserver.io `group_add` + custom-cont-init.d workaround, `docker compose up` no-op-on-unchanged-hash gotcha.
|
||||
|
||||
---
|
||||
|
||||
## GitNexus code intelligence
|
||||
### GitNexus code intelligence
|
||||
|
||||
Indexed as `resolutionflow`. Earns its cost on cross-cutting work only.
|
||||
|
||||
@@ -224,9 +52,7 @@ Indexed as `resolutionflow`. Earns its cost on cross-cutting work only.
|
||||
|
||||
Re-indexes automatically on commit (PostToolUse hook). Manual refresh if stale: `npx gitnexus analyze`.
|
||||
|
||||
---
|
||||
|
||||
## gstack skills
|
||||
### gstack skills
|
||||
|
||||
Always use `/browse` for web, never `mcp__claude-in-chrome__*`. Most-used:
|
||||
|
||||
@@ -238,28 +64,10 @@ Always use `/browse` for web, never `mcp__claude-in-chrome__*`. Most-used:
|
||||
- `/codex` — OpenAI Codex second opinion
|
||||
- `/plan-eng-review` / `/plan-design-review` / `/plan-ceo-review` — plan critiques
|
||||
|
||||
---
|
||||
### Git trailer
|
||||
|
||||
## Deployment (Railway)
|
||||
Every commit: `Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>`
|
||||
|
||||
- **Prod:** `resolutionflow.com` (frontend), `api.resolutionflow.com` (backend).
|
||||
- Auto-deploy: Gitea push → GitHub mirror → Railway follows GitHub `main`.
|
||||
- PR environments auto-created; need manual domain generation + `VITE_API_URL` with `https://` prefix.
|
||||
- `ALLOW_RAILWAY_ORIGINS=true` for `*.up.railway.app` CORS.
|
||||
- Shared Variables (Railway project-level) auto-propagate to PR envs — use for secrets like `ANTHROPIC_API_KEY`.
|
||||
- Super admin utility: `backend/make_superadmin_simple.py list|<email>`.
|
||||
### Model aliases
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| Detailed status | [CURRENT-STATE.md](CURRENT-STATE.md) |
|
||||
| Roadmap | [03-DEVELOPMENT-ROADMAP.md](03-DEVELOPMENT-ROADMAP.md) |
|
||||
| Design system | [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) |
|
||||
| Dev env | [DEV-ENV.md](DEV-ENV.md) |
|
||||
| Archived lessons | [docs/LESSONS-ARCHIVE.md](docs/LESSONS-ARCHIVE.md) |
|
||||
| ConnectWise API | `docs/connectwise/` |
|
||||
| GitHub issues | `gh issue list --state open` |
|
||||
| Local API docs | <http://localhost:8000/api/docs> |
|
||||
Always use alias form (`claude-sonnet-4-6`, `claude-opus-4-6`, etc.) via `settings.get_model_for_action()`. Never hardcode a dated model ID.
|
||||
|
||||
@@ -1,70 +0,0 @@
|
||||
# Session Handoff — Design System v4 Migration
|
||||
|
||||
> **For the next Claude session:** Read this file completely, internalize the context, then delete it (`rm SESSION-HANDOFF.md`). This is a one-time context transfer.
|
||||
|
||||
---
|
||||
|
||||
## What Was Done This Session
|
||||
|
||||
### 1. FlowPilot Message Bar + AI Script Builder (MERGED to main)
|
||||
- PR #118 merged. Always-visible message bar in FlowPilot sessions, AI Script Builder at `/script-builder`, library reorg (My/Team Scripts tabs), FlowPilot-to-Script-Builder handoff, session abandon/close, unified session history.
|
||||
- Eng review completed: normalized `script_builder_messages` table, typed content helpers, 6 edge case tests.
|
||||
|
||||
### 2. Design System v4 Migration (PR #119, open, branch: `refactor/design-system-v4`)
|
||||
- Complete frontend redesign from glassmorphism to flat dark theme (Sentry/PostHog-inspired)
|
||||
- **CSS Foundation:** New color tokens in `index.css`, all via CSS custom properties. Light mode ready (just needs `.light` class values).
|
||||
- **Icon Rail Sidebar:** 72px rail with 5 grouped icons (Home, Work, Knowledge, Insights, Help). Full-height resizable drawer on hover. Pin-to-expand to 260px. Mobile hamburger overlay.
|
||||
- **Component Sweep:** ~200 files migrated. All hardcoded hex replaced with semantic Tailwind tokens (bg-card, text-foreground, border-border, etc.).
|
||||
- **Landing Page:** Flat surfaces, no glow, solid buttons.
|
||||
- **Interactive Shadows:** Dark-mode-aware — elevated surfaces + faint cyan accent glow (black shadows invisible on dark bg).
|
||||
- **Stat Cards:** 3px colored left borders.
|
||||
- **Tab Toggles:** Active state uses `tab-active-shadow` (elevated bg + faint glow).
|
||||
|
||||
### 3. GTM Strategy (from /office-hours)
|
||||
- Shadow & Ship approach: Michael uses ResolutionFlow on real tickets for 2 weeks, then hands logins to 5 MSP colleagues. Key metric: unprompted return.
|
||||
- Design doc at `~/.gstack/projects/patherly-patherly/`
|
||||
|
||||
---
|
||||
|
||||
## What Needs To Be Done Next
|
||||
|
||||
### Immediate (Design System v4 polish)
|
||||
1. **Home icon color fix:** The Home icon in the sidebar shouldn't have a cyan background when not active. Instead, the Home icon itself should always be cyan (brand accent), and only show the `bg-accent-dim` background when the route is actually `/`. Michael specifically requested this.
|
||||
2. **Visual QA pass:** Michael hasn't done a full page-by-page walkthrough yet. Expect feedback on individual pages once he does.
|
||||
3. **`font-label` cleanup:** ~10 files still reference `font-label` (deprecated alias for `font-mono`). Each needs inspection — some should be `font-mono`, others `font-sans text-xs`.
|
||||
4. **Inline `style` attributes:** ~29 instances still use hardcoded hex in inline styles (sidebar, drawer, badges). Should be converted to CSS variable references or Tailwind classes where possible.
|
||||
|
||||
### Before Merging PR #119
|
||||
- Run migrations: `docker exec resolutionflow_backend alembic upgrade head` (new tables from the Script Builder PR are on main now)
|
||||
- Full visual QA with backend running
|
||||
- Test mobile responsive (hamburger menu)
|
||||
- Test FlowPilot session with new message bar + action bar positioning
|
||||
|
||||
### Future
|
||||
- **Light mode toggle:** CSS variables are ready. Need to add `.light` class values in `index.css` + toggle in user settings/account page.
|
||||
- **Script Builder testing:** The AI Script Builder hasn't been tested end-to-end with the backend running yet.
|
||||
|
||||
---
|
||||
|
||||
## Key Files to Know
|
||||
|
||||
| File | What it does |
|
||||
|------|-------------|
|
||||
| `DESIGN-SYSTEM.md` | Single source of truth for all design decisions |
|
||||
| `frontend/src/index.css` | CSS tokens, component utilities, shadow patterns |
|
||||
| `frontend/src/components/layout/Sidebar.tsx` | Icon rail + drawer + pinned sidebar |
|
||||
| `frontend/src/components/layout/AppLayout.tsx` | CSS Grid shell |
|
||||
| `frontend/src/components/dashboard/StartSessionInput.tsx` | The Guided/Chat toggle |
|
||||
| `frontend/src/components/dashboard/PerformanceCards.tsx` | Stat cards with colored borders |
|
||||
|
||||
## Key Lessons From This Session
|
||||
|
||||
- The component sweep agents missed `editor-ai/`, `guides/`, `maintenance/`, `scripts/`, `settings/` directories and `text-brand-dark` references. Always do a final grep audit after sweeps.
|
||||
- `bg-[#hex]` hardcoding defeats the purpose of CSS variables. We had to do a second pass to replace 3,200+ hardcoded values with semantic tokens.
|
||||
- Black shadows (`rgba(0,0,0,...)`) are invisible on dark backgrounds. Use elevated surfaces + faint accent glow instead.
|
||||
- The sidebar flyout needed `position: fixed` to escape the CSS Grid cell clipping — `absolute` positioning was hidden behind the main content area.
|
||||
- Flyout hover timing: individual item `onMouseLeave` was killing the flyout before the mouse reached the drawer. Only the outer wrapper should handle `onMouseLeave`.
|
||||
|
||||
---
|
||||
|
||||
> **After reading this file:** Save relevant context to your session memory, then run `rm SESSION-HANDOFF.md` and `git add -A && git commit -m "chore: remove session handoff file"`.
|
||||
Reference in New Issue
Block a user