From c1f96ba94efd789344df834965d6a55d36d5e530 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 17 Mar 2026 20:09:05 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20update=20GUIDE=5F=5FDevelopment.md=20?= =?UTF-8?q?=E2=80=94=20add=20URL=20params,=20refresh=20stale=20content?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Section 6: full URL parameters reference (global + per-module) - Update coordination section: message tool → ae_send_message MCP - Expand Section 5 into a proper key documentation table - Fix section numbering (Continuity was unnumbered) - Bump version to 1.2 (2026-03-17) Co-Authored-By: Claude Sonnet 4.6 --- documentation/GUIDE__Development.md | 115 +++++++++++++++++++++++----- 1 file changed, 94 insertions(+), 21 deletions(-) diff --git a/documentation/GUIDE__Development.md b/documentation/GUIDE__Development.md index 12889b9b..fe13af78 100644 --- a/documentation/GUIDE__Development.md +++ b/documentation/GUIDE__Development.md @@ -1,39 +1,112 @@ # Aether Development SOP (Frontend) -> **Version:** 1.1 (2026-02-16) +> **Version:** 1.2 (2026-03-17) > **Location:** documentation/GUIDE__Development.md -## 1. 🛡️ Verification (The "Test-First" Mandate) -**Rule:** No code is to be committed unless it has passed local verification. Skipping this is a violation of the Aether Dev Protocol. +## 1. Verification (The "Test-First" Mandate) +**Rule:** No code is to be committed unless it has passed local verification. ### Required Checks 1. **Svelte Integrity:** `npx svelte-check` - - **Zero Tolerance Policy:** If a task introduces even a single svelte-check warning or error, it must not be merged. All warnings must be resolved before code review or merge. This prevents the "circle-running" and technical debt that results from ignoring warnings. + - **Zero Tolerance:** If a task introduces even a single svelte-check warning or error, it must not be merged. Resolve all warnings before committing. 2. **Type Safety:** Ensure interfaces in `src/lib/types/ae_types.ts` match backend schemas. 3. **Reactivity Check:** Verify Svelte 5 runes (`$state`, `$derived`) are not creating race conditions with Dexie `liveQuery`. 4. **Build Check:** For major changes, run `npm run build:staging` to ensure no SSR or build-time failures. -## 2. 📝 Commit & Sync Policy +## 2. Commit Policy - **Atomic Commits:** One component or one logic fix per commit. Do not batch unrelated changes. -- **Verification Log:** Mention the verification steps taken in your work log (`ae_log_work`). -- **Safety:** Use `~/tmp/gemini_trash` for removals; never use `rm` directly on source files. +- **Safety:** Use `~/tmp/gemini_trash` for file removal; never use `rm` directly on source files. +- **Secrets:** Never commit `.env`, API keys, or passwords. -## 3. 🤝 The Handshake (Coordination) -You are not working in a vacuum. You MUST coordinate with the Backend Agent. +## 3. Coordination (The Handshake) +You are not working in a vacuum. Coordinate with the Backend Agent via MCP tools. ### Mandatory Messaging Triggers - **Data Requirements:** When a UI feature requires a new field or endpoint. -- **API Failures:** When a V3 endpoint returns unexpected data or 500s. -- **Status:** IGNORE THIS FOR NOW: ~~Update your shared Journal in `~/agents_sync/aether/journals/` after significant milestones.~~ -- **Stuck in Loop or Insufficient Information: ** If you find yourself in a loop or lacking information, ask Scott and or use the `message` tool to ask for clarification or assistance from the Backend Agent. +- **API Failures:** When a V3 endpoint returns unexpected data or errors. +- **Blocked:** If stuck in a loop or lacking information, use `ae_send_message` to ask the Backend Agent, or flag for Scott. -**Tool:** Use the `message` tool to communicate with the Backend Agent or Scott's other agents. +### Tools +- `ae_send_message` / `ae_inbox` — agent-to-agent messaging +- `ae_task_list` / `ae_task_add` / `ae_task_complete` — shared Kanban board +- `ae_log_work` — log activity to daily journal -## 🧠 Continuity -Before starting work: -1. Read `~/agents_sync/README.md` to understand the fleet status and cross-agent tasks. -2. Check `README.md` in the project root for technical specs. -3. Review your local `documentation/TODO__Agents.md` for active tasks. -4. Be sure to describe the plan before you start making code changes to one or more files. +## 4. Continuity (Before Starting Work) +1. Review `documentation/TODO__Agents.md` for active tasks. +2. Check `~/agents_sync/README.md` for fleet status and cross-agent tasks. +3. Describe your plan before making code changes across multiple files. -## 4. Aether UI/UX and API V3 Documentation -* documentation/GUIDE__AE_API_V3_for_Frontend.md \ No newline at end of file +## 5. Key Documentation + +| File | Purpose | +| --- | --- | +| `documentation/TODO__Agents.md` | Active task list — read first | +| `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/AE__Architecture.md` | System architecture overview | +| `documentation/AE__Naming_Conventions.md` | Naming rules | +| `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` | Electron/Launcher reference | + +## 6. URL Parameters + +URL params consumed by the app. Params are read by layouts and applied on mount. + +### Global (active on all routes — read by `src/routes/+layout.svelte`) + +| Param | Values | Effect | +| --- | --- | --- | +| `iframe` | `true` / `false` | Enables iframe mode — hides sys bar for non-trusted users, suppresses sign-in/passcode UI | +| `hide_menu` | `true` | Hides the AE system bar entirely, even for trusted_access users. Use when embedding in Novi or pages with their own navigation. | +| `theme` | theme name | Applies a theme on load, then removes param from URL (no history entry) | +| `theme_mode` | `light` / `dark` | Applies theme mode on load, then removes param from URL | + +### IDAA Module (`/idaa/` routes) + +| Param | Values | Consumed by | Effect | +| --- | --- | --- | --- | +| `iframe` | `true` | `idaa/+layout.svelte` | Hides IDAA nav chrome | +| `uuid` | Novi UUID | `idaa/(idaa)/+layout.svelte` | Sets Novi UUID → triggers member auth lookup | + +### IDAA Video Conferences (`/idaa/video_conferences`) + +| Param | Values | Effect | +| --- | --- | --- | +| `uuid` | Novi UUID | Member identity for Jitsi JWT | +| `key` | site key string | Site auth key | +| `room` | room name | Jitsi room name | +| `moderator` | `true` | Grants moderator role + JWT, enables lobby and activity logging | +| `domain` | hostname | Jitsi server (default: `jitsi.dgrzone.com`) | +| `start_muted` | `true` | Start audio muted | +| `start_hidden` | `true` | Start video off | +| `incoming_msg_sound` | `true` | Disable incoming message sound | +| `participant_joined_sound` | `true` | Disable participant joined sound | +| `participant_left_sound` | `true` | Disable participant left sound | +| `reaction_sound` | `true` | Disable reaction sound | +| `raise_hand_sound` | `true` | Disable raise hand sound | + +### Events Launcher (`/events/[id]/launcher`) + +| Param | Values | Effect | +| --- | --- | --- | +| `session_id` | session ID | Pre-selects a session on load | +| `iframe` | `true` | Iframe mode flag | +| `launcher_menu` | show/hide | Show/hide launcher menu chrome | +| `launcher_header` | show/hide | Show/hide launcher header | +| `launcher_footer` | show/hide | Show/hide launcher footer | + +### Events Sign-In (`/events/[id]/sign_in_out`) + +| Param | Values | Effect | +| --- | --- | --- | +| `person_id` | person ID | Pre-fill attendee | +| `person_pass` | passphrase | Auto-authenticate attendee | +| `presentation_id` | ID | Pre-select presentation | +| `presenter_id` | ID | Pre-select presenter | +| `session_id` | ID | Pre-select session | + +### Badges (`/events/[id]/badges/print_list`) + +| Param | Values | Effect | +| --- | --- | --- | +| `printed_status` | filter value | Filter badge list by print status | +| `badge_type_code` | code string | Filter badge list by type |