From 61025ea0d553ca89803062d764e3bc41cb2cc130 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Thu, 26 Feb 2026 13:48:01 -0500 Subject: [PATCH] Docs: Add CLAUDE.md project context file for AI agent coordination Project-specific context file for Claude Code containing: - Critical privacy/business rules (IDAA, Journals) - Mandatory workflows and tech stack - API patterns and key documentation references - Active issues tracking Complements global ~/.claude/CLAUDE.md with SvelteKit-specific guidance. --- CLAUDE.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..eda91257 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,120 @@ +# Claude Code — Project: Aether App SvelteKit + +**Part of:** One Sky IT / Aether Platform +**Backend:** `~/OSIT_dev/aether_api_fastapi/` via Docker + +--- + +## CRITICAL: Privacy & Business Rules + +### IDAA — International Doctors in Alcoholics Anonymous +- **ALL IDAA content is PRIVATE. Authentication required. Never public.** +- BB (Bulletin Board / Posts) — always private +- Archives — always private +- Recovery Meetings — always private +- A previous AI agent accidentally exposed IDAA BB publicly. This is a severe security failure. +- IDAA users authenticate via Novi API (Novi UUID per member) at `Authenticated` permission level. +- Default permission required: `trusted_access` or higher for IDAA module. + +### Journals +- Private personal data. Always authenticated. Passcode/encryption features exist. + +### General +- **Never expose private content publicly.** When in doubt — it's private. +- Code comments must explain the WHY for any non-obvious business logic. + Key features have been silently broken by AI agents that didn't understand intent. + +--- + +## Mandatory Workflow + +1. **Before starting:** Read `documentation/TODO__Agents.md` for active tasks +2. **Before committing:** Run `npx svelte-check` — no exceptions +3. **Commits:** Atomic — one component or fix per commit +4. **Never delete files with `rm`** — move to `~/tmp/gemini_trash` +5. **Backend coordination:** Use `ae_send_message` or flag changes clearly + +--- + +## Tech Stack + +- **Framework:** Svelte 5 (runes mode) + SvelteKit v2 +- **Styling:** Tailwind CSS v4, Flowbite; Skeleton UI being phased out +- **State:** `$state`, `$derived` runes + Dexie.js IndexedDB (`liveQuery`) +- **Icons:** Lucide +- **Editors:** CodeMirror 6 (primary), Edra/TipTap (secondary) +- **Markdown:** `marked` library +- **UI primitives:** ShadCN (`src/lib/components/ui/`) +- **Native/Electron bridge:** `src/lib/electron/electron_relay.ts` via `window.aetherNative` + +--- + +## API (V3) + +- Base: `/v3/crud/{obj_type}/` for all CRUD +- Lookups: `/v3/lookup/` +- Search: `POST /v3/crud/{obj_type}/search` +- Auth headers: `x-aether-api-key` + `x-account-id` (NOT Bearer tokens) +- Permissive PATCH: add `x-ae-ignore-extra-fields: true` +- Guide: `documentation/GUIDE__AE_API_V3_for_Frontend.md` + +--- + +## Key Patterns + +- **Canonical reference:** Journals module (`src/lib/ae_journals/`) — use as the pattern template +- **Object files:** `ae___.ts` + `.editable_fields.ts` +- **DB:** `db_.ts` per module (Dexie instance) +- **LiveQuery:** `lq__xyz` (read-only), `lqw__xyz` (writable form snapshot) +- **Load pattern:** SWR — return Dexie cache immediately, refresh from API in background +- **Component naming:** `ae_comp__*` (route-level), `ae__comp__*` (module), `element_*` (reusable) +- **Standard fields:** `id`, `id_random`, `code`, `name`, `enable`, `hide`, `priority`, `sort`, `group`, `notes`, `created_on`, `updated_on`, `cfg_json`, `data_json` + +--- + +## Source Layout + +``` +src/lib/ + ae_api/ — API helpers (prefer V3) + ae_core/ — Account, User, Person, Site, Address, Contact + ae_events/ — Events, sessions, presenters, badges, locations, devices + ae_journals/ — Journals (canonical/frontier model) + ae_archives/ — Archives + ae_posts/ — Posts + Post Comments (IDAA BB) + ae_idaa/ — IDAA custom module + ae_reports/ — Reporting + elements/ — Reusable UI: V3 editor, CRUD, data store, CodeMirror + electron/ — Native app bridge + +src/routes/ + /core/ — Admin (accounts, people, sites, users, contacts) + /events/[id]/ — Events: pres_mgmt, launcher, badges, leads, settings + /journals/ — Journals + /idaa/ — IDAA: archives, bb, recovery_meetings, video_conferences + /hosted_files/ — File management + /testing/ — Dev testing +``` + +--- + +## Active Issues (check TODO__Agents.md for current state) + +- Session/Presentation page cold-start bug (Events Pres Mgmt) — unresolved +- Sev-1: `PUBLIC_AE_API_SECRET_KEY` audit +- CRUD v2 retirement → V3 editor +- 403/401 error boundaries ("Session Expired" UI) + +--- + +## Key Docs + +| File | Purpose | +|---|---| +| `documentation/TODO__Agents.md` | Active task list — read first | +| `documentation/GUIDE__Development.md` | Dev SOP | +| `documentation/GUIDE__AE_API_V3_for_Frontend.md` | V3 API reference (authoritative) | +| `documentation/GUIDE__SvelteKit2_Svelte5_DexieJS.md` | Dexie + liveQuery patterns | +| `documentation/GEMINI__Svelte_and_Me.md` | Svelte 5 runes patterns | +| `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | Electron/Launcher | +| `documentation/PROJECT__AE_Pres_Mgmt_Session_view_refactor_2026-02.md` | Session bug plan |