From ae96d5883a5a8e445309234e010f6f0c2d518988 Mon Sep 17 00:00:00 2001 From: wcjord <32568597+wcjord@users.noreply.github.com> Date: Fri, 27 Feb 2026 13:53:41 -0500 Subject: [PATCH] Fix instruction doc issues found in audit (Closes #5842) (#5843) --- .../cross-service-debugging.instructions.md | 14 ++++++ .../instructions/deployment.instructions.md | 14 ++++++ .../language-list.instructions.md | 50 +++++++++++++++++++ .github/instructions/layout.instructions.md | 6 ++- .github/instructions/testing.instructions.md | 2 +- .../token-info-feedback-v2.instructions.md | 2 +- 6 files changed, 84 insertions(+), 4 deletions(-) create mode 100644 .github/instructions/cross-service-debugging.instructions.md create mode 100644 .github/instructions/deployment.instructions.md create mode 100644 .github/instructions/language-list.instructions.md diff --git a/.github/instructions/cross-service-debugging.instructions.md b/.github/instructions/cross-service-debugging.instructions.md new file mode 100644 index 000000000..6014c7ba8 --- /dev/null +++ b/.github/instructions/cross-service-debugging.instructions.md @@ -0,0 +1,14 @@ +--- +applyTo: "**/assets/.env*,**/*repo*.dart,lib/pangea/common/network/**" +--- + +# Cross-Service Debugging (client) + +See the [org-wide cross-service debugging guide](../../../.github/instructions/cross-service-debugging.instructions.md) for staging auth tokens, curl commands, local full-stack setup, and common pitfalls. + +## Client-Specific Notes + +- Staging `.env` config: set choreo and Matrix URLs to staging endpoints +- Local choreo testing: use `.env.local_choreo` to point at `localhost:8000` +- API repo files (e.g., `igc_repo.dart`) pair with request/response models — debug at the repo boundary +- Client calls choreo pre-send (grammar check, tokenization) and post-receive (reading assistance) diff --git a/.github/instructions/deployment.instructions.md b/.github/instructions/deployment.instructions.md new file mode 100644 index 000000000..01540421e --- /dev/null +++ b/.github/instructions/deployment.instructions.md @@ -0,0 +1,14 @@ +--- +applyTo: "**/.github/workflows/**,**/deploy*" +--- + +# Deployment (client) + +Follows the [org-wide deployment conventions](../../../.github/instructions/deployment.instructions.md) — see that doc for pipelines, environment URLs, deploy notes, and coordination. This doc covers client-specific details only. + +## Deploy Mechanism + +- Flutter web build → S3 upload via GitHub Actions +- Mobile builds: manual app store builds and releases +- Staging: app.staging.pangea.chat (S3 + CloudFront) +- Production: app.pangea.chat (S3 + CloudFront) diff --git a/.github/instructions/language-list.instructions.md b/.github/instructions/language-list.instructions.md new file mode 100644 index 000000000..59d454349 --- /dev/null +++ b/.github/instructions/language-list.instructions.md @@ -0,0 +1,50 @@ +--- +applyTo: "lib/pangea/languages/**,lib/pangea/learning_settings/**,lib/pangea/login/pages/language_selection_page.dart" +--- + +# Language List — Client + +For the cross-service language list architecture, L1/L2 definitions, and CMS schema, see [language-list.instructions.md](../../../.github/.github/instructions/language-list.instructions.md). + +## Data Flow + +1. [`LanguageRepo._fetch()`](../../lib/pangea/languages/language_repo.dart) fetches all languages from CMS REST API (`/api/languages?limit=500&sort=language_name`) — public, no auth +2. [`PLanguageStore`](../../lib/pangea/languages/p_language_store.dart) caches the list in `SharedPreferences` and re-fetches roughly daily +3. Hardcoded fallback in [`LanguageConstants.languageList`](../../lib/pangea/languages/language_constants.dart) if CMS is unreachable and cache is empty + +## L1/L2 Filtering + +[`PLanguageStore`](../../lib/pangea/languages/p_language_store.dart) exposes three getters: + +| Getter | Filter | Used for | +|---|---|---| +| `baseOptions` | All languages (no filter) | L1 / source / native language selection | +| `targetOptions` | `element.l2` (i.e., `l2Support != L2SupportEnum.na`) | L2 / target / learning language selection | +| `unlocalizedTargetOptions` | L2 filter + excludes regional variants (e.g., keeps "Portuguese" but not "Portuguese (Brazil)") | Course creation language filter | + +The `l2` getter on [`LanguageModel`](../../lib/pangea/languages/language_model.dart) returns `l2Support != L2SupportEnum.na`. + +## Key Usage Sites + +- **Login language selection**: [`language_selection_page.dart`](../../lib/pangea/login/pages/language_selection_page.dart) — uses `targetOptions` for L2 chips, defaults L1 to system language +- **Learning settings dialog**: [`p_language_dialog.dart`](../../lib/pangea/learning_settings/p_language_dialog.dart) — `baseOptions` for L1, `targetOptions` for L2 +- **Learning settings view**: [`settings_learning_view.dart`](../../lib/pangea/learning_settings/settings_learning_view.dart) — same pattern +- **Bot chat settings**: [`bot_chat_settings_dialog.dart`](../../lib/pangea/bot/widgets/bot_chat_settings_dialog.dart) — `targetOptions` for room target language +- **Course creation**: [`course_language_filter.dart`](../../lib/pangea/course_creation/course_language_filter.dart) — `unlocalizedTargetOptions` + +## Models + +- [`LanguageModel`](../../lib/pangea/languages/language_model.dart) — core model with `langCode`, `displayName`, `l2Support`, `script`, `localeEmoji`, `voices` +- [`L2SupportEnum`](../../lib/pangea/languages/l2_support_enum.dart) — `na`, `alpha`, `beta`, `full` with localized display strings and badge rendering +- [`LanguageArc`](../../lib/pangea/languages/language_arc_model.dart) — L1→L2 pair, constructed from user settings + +## Conventions + +- Display names are localized via `getDisplayName(context)` using l10n keys, with fallback to CMS `language_name` +- Regional variants show `localeEmoji` in place of parenthesized region: "Portuguese 🇧🇷" instead of "Portuguese (Brazil)" +- `langCodeShort` strips the territory: `en-US` → `en` +- RTL detection uses a hardcoded list in `LanguageConstants.rtlLanguageCodes` + +## Future Work + +_(No linked issues yet.)_ diff --git a/.github/instructions/layout.instructions.md b/.github/instructions/layout.instructions.md index d81c98ab9..5420df85c 100644 --- a/.github/instructions/layout.instructions.md +++ b/.github/instructions/layout.instructions.md @@ -1,6 +1,8 @@ -# Client Layout System +--- +applyTo: "lib/config/themes.dart,lib/widgets/layouts/**,lib/pangea/spaces/space_navigation_column.dart,lib/widgets/navigation_rail.dart,lib/config/routes.dart" +--- -Applies to: `lib/config/themes.dart`, `lib/widgets/layouts/**`, `lib/pangea/spaces/space_navigation_column.dart`, `lib/widgets/navigation_rail.dart`, `lib/config/routes.dart` +# Client Layout System ## Overview diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md index 96fb19484..412dc8005 100644 --- a/.github/instructions/testing.instructions.md +++ b/.github/instructions/testing.instructions.md @@ -4,7 +4,7 @@ applyTo: "**/*test*,**/test/**,**/integration_test/**" # Testing Guide (Client) -Follows the [cross-repo testing strategy](../../.github/instructions/testing.instructions.md) — see that doc for tier definitions (unit / integration / e2e), conventions, and rationale. This doc covers client-specific details only. +Follows the [cross-repo testing strategy](../../../.github/instructions/testing.instructions.md) — see that doc for tier definitions (unit / integration / e2e), conventions, and rationale. This doc covers client-specific details only. ## Stack diff --git a/.github/instructions/token-info-feedback-v2.instructions.md b/.github/instructions/token-info-feedback-v2.instructions.md index 06b67f997..bb31a8c36 100644 --- a/.github/instructions/token-info-feedback-v2.instructions.md +++ b/.github/instructions/token-info-feedback-v2.instructions.md @@ -1,5 +1,5 @@ --- -applyTo: "lib/pangea/token_info_feedback/**, lib/**" +applyTo: "lib/pangea/token_info_feedback/**" --- # Token Info Feedback — v2 Migration (Client)