docs: update GUIDE__Development.md — add URL params, refresh stale content

- 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 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-03-17 20:09:05 -04:00
parent 931df5581f
commit c1f96ba94e

View File

@@ -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
## 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 |