@wazir-dev/cli 1.0.0

package/expertise/i18n/foundations/text-direction-bidi.md

@@ -0,0 +1,241 @@
+# Text Direction and Bidirectional Text — i18n/RTL Expertise Module
+
+> How text direction works: logical vs visual order, the Unicode BiDi algorithm, and when to use markup vs control characters. Essential for any interface that mixes Arabic, Hebrew, or other RTL scripts with LTR content.
+
+> **Category:** Foundation
+> **Applies to:** All (Mobile, Web, Backend)
+> **Key standards:** Unicode UAX #9 (BiDi Algorithm), W3C HTML BiDi
+> **RTL impact:** Critical — this is the foundation of all RTL support
+
+## 1. Core Concepts
+
+### What This Area Covers
+
+Text direction determines how characters are laid out horizontally: left-to-right (LTR) for English, Latin, Cyrillic, etc., and right-to-left (RTL) for Arabic, Hebrew, Persian, Urdu. Bidirectional (BiDi) text mixes both in a single line—e.g., "Hello العربية world"—and requires the Unicode Bidirectional Algorithm to resolve display order.
+
+### Logical vs Visual Order
+
+| Concept | Definition | Example |
+|---------|------------|---------|
+| **Logical order** | Sequence in which text is typed, pronounced, and stored in memory | "english ARABIC text" |
+| **Visual order** | Sequence in which text appears on screen | "english CIBARA text" (Arabic reversed) |
+
+**Always use logical order in markup and data.** The BiDi algorithm converts logical → visual at display time. Storing visual order breaks copy-paste, search, and maintenance.
+
+### Base Direction
+
+The base direction is the default for a block of text when the BiDi algorithm runs. It affects:
+- Order of neutral characters (spaces, punctuation)
+- Alignment (start vs end)
+- How mixed-direction runs are resolved
+
+Set via `dir="ltr"`, `dir="rtl"`, or `dir="auto"` (first strong character wins).
+
+---
+
+## 2. Unicode Bidirectional Algorithm (UAX #9)
+
+### How It Works
+
+1. **Character classification** — Each character has a directional type: L (strong LTR), R (strong RTL), AL (Arabic letter), EN (European number), AN (Arabic number), NSM (non-spacing mark), etc.
+2. **Resolving levels** — The algorithm assigns embedding levels (0 = LTR, 1 = RTL, etc.) based on base direction and character types.
+3. **Reordering** — Characters are reordered for display according to their levels.
+
+### When the Algorithm Needs Help
+
+- **Neutral characters** — Spaces, punctuation between opposite-direction runs can be misassigned
+- **Numbers** — European (0123) vs Arabic (٠١٢٣) numerals; numbers can "stick" to wrong runs
+- **Spillover** — An RTL phrase followed by a number in LTR context: the number may join the RTL run incorrectly
+
+### Directional Formatting Characters
+
+**Prefer isolate pairs (Unicode 6.3+):** They prevent spillover.
+
+| Character | Name | Code | Use |
+|-----------|------|------|-----|
+| LRI | LEFT-TO-RIGHT ISOLATE | U+2066 | Wrap LTR text in RTL context |
+| RLI | RIGHT-TO-LEFT ISOLATE | U+2067 | Wrap RTL text in LTR context |
+| FSI | FIRST-STRONG ISOLATE | U+2068 | `dir="auto"` equivalent |
+| PDI | POP DIRECTIONAL ISOLATE | U+2069 | Closes LRI, RLI, or FSI |
+
+**Legacy (avoid for new content):** Can cause spillover.
+
+| Character | Name | Code | Use |
+|-----------|------|------|-----|
+| LRE | LEFT-TO-RIGHT EMBEDDING | U+202A | LTR embedding |
+| RLE | RIGHT-TO-LEFT EMBEDDING | U+202B | RTL embedding |
+| PDF | POP DIRECTIONAL FORMATTING | U+202C | Closes LRE/RLE |
+| LRO | LEFT-TO-RIGHT OVERRIDE | U+202D | Force LTR display order |
+| RLO | RIGHT-TO-LEFT OVERRIDE | U+202E | Force RTL display order |
+
+**Single-character marks:**
+
+| Character | Name | Code | Use |
+|-----------|------|------|-----|
+| LRM | LEFT-TO-RIGHT MARK | U+200E | Break link between number and RTL text; extend LTR run |
+| RLM | RIGHT-TO-LEFT MARK | U+200F | Extend RTL run to include punctuation |
+
+### When to Use Control Characters vs Markup
+
+- **HTML/CSS available** — Use `dir` attribute or `<bdi>`. Prefer markup.
+- **Plain text only** — Use Unicode controls (e.g., `title` attribute, WebVTT, CSV, filenames).
+- **User-generated content** — `dir="auto"` or FSI when direction is unknown.
+
+### Example: Fixing Spillover
+
+**Problem:** "We found the phrase 'نشاط التدويل' 5 times" — the "5" incorrectly joins the Arabic.
+
+**Solution with RLI/PDI:**
+```
+We find the phrase '\u2067نشاط التدويل\u2069' 5 times
+```
+
+**Solution with LRM** (if you only need to break the link):
+```
+We find the phrase 'نشاط التدويل'\u200E 5 times
+```
+
+---
+
+## 3. HTML and Markup
+
+### Document-Level Direction
+
+```html
+<html lang="ar" dir="rtl">
+```
+
+### Block-Level Direction
+
+```html
+<div dir="rtl">محتوى عربي</div>
+```
+
+### Inline Mixed Content
+
+Wrap opposite-direction phrases tightly:
+
+```html
+<p>The title is <span dir="rtl">مدخل إلى C++</span> in Arabic.</p>
+```
+
+### `dir="auto"`
+
+Detects direction from first strong directional character. Use for user-supplied or unknown content.
+
+```html
+<span dir="auto">{{userInput}}</span>
+```
+
+### `<bdi>` (Bidirectional Isolate)
+
+Isolates content from surrounding BiDi context. Use when direction is unknown and you want the algorithm to determine it independently.
+
+```html
+<bdi>{{username}}</bdi> commented
+```
+
+---
+
+## 4. Platform Implementation
+
+### Web (HTML/CSS)
+
+- Set `dir` on `<html>` for document; override on specific elements
+- Use `dir="auto"` for dynamic content
+- CSS: `direction`, `unicode-bidi` (rarely needed if markup is correct)
+
+### Flutter
+
+```dart
+Directionality(
+  textDirection: TextDirection.rtl,
+  child: child,
+)
+// Or: Directionality.of(context)
+```
+
+### React
+
+```tsx
+<div dir="rtl" lang="ar">{content}</div>
+```
+
+### iOS
+
+```swift
+// UIView.semanticContentAttribute = .forceRightToLeft
+// Or per view
+```
+
+### Android
+
+```xml
+android:layoutDirection="rtl"
+```
+
+---
+
+## 5. Mixed Content Handling
+
+### LTR in RTL Context
+
+- English brand names, URLs, code snippets, email addresses
+- Wrap in `dir="ltr"` or LRI/PDI when in plain text
+
+### Numbers
+
+- European numerals (0123) are weakly directional; they can "stick" to RTL
+- Insert LRM before a number in LTR context if it incorrectly joins RTL
+- Arabic numerals (٠١٢٣) are RTL; use when displaying in Arabic UI
+
+### URLs and Email
+
+- Always LTR; wrap in `dir="ltr"` if displayed in RTL paragraph
+
+### Punctuation
+
+- Punctuation at the end of an RTL phrase may be assigned to the wrong run
+- Add RLM after the punctuation to extend the RTL run, or wrap in RLI/PDI
+
+---
+
+## 6. Anti-Patterns
+
+1. **Storing visual order** — Store logical order; let the algorithm handle display.
+2. **Using LRE/RLE instead of LRI/RLI** — Causes spillover; prefer isolates.
+3. **Ignoring neutral characters** — Commas, spaces between RTL phrases can misalign.
+4. **No base direction for user content** — Use `dir="auto"` or detect.
+5. **Assuming `dir` is inherited** — Explicitly set on root and overrides.
+6. **Mixing `direction` CSS with `dir`** — Prefer `dir` for semantics.
+7. **Forgetting `lang`** — `dir` and `lang` should be set together.
+8. **Not wrapping opposite-direction phrases** — Loose wrapping causes wrong display.
+9. **Using override (LRO/RLO) for isolation** — Override forces display order; use isolate instead.
+10. **Skipping BiDi for "English-only" apps** — User names, search results, and API data can be any script.
+
+---
+
+## 7. Testing Approach
+
+- Test with real Arabic (العربية) and Hebrew (עברית) — not placeholder text
+- Test mixed content: "Hello العربية 123"
+- Test spillover case: RTL phrase + number
+- Test lists of opposite-direction items (e.g., country names in Arabic in LTR list)
+- Verify copy-paste preserves logical order
+- Check `dir` and `lang` on root and key containers
+
+---
+
+## Quick Reference Checklist
+
+- [ ] Store and transmit text in logical order
+- [ ] Set `dir` and `lang` on document root
+- [ ] Use RLI/LRI/PDI (not RLE/LRE) for plain-text BiDi
+- [ ] Wrap opposite-direction phrases tightly
+- [ ] Use `dir="auto"` for unknown user content
+- [ ] Add LRM/RLM when needed to fix spillover
+- [ ] Test with real Arabic and Hebrew strings
+- [ ] Verify numbers and punctuation display correctly
+
+---
+*Researched: 2026-03-08 | Sources: Unicode UAX #9, W3C BiDi controls, W3C visual vs logical, MDN dir/bdi*

package/expertise/i18n/foundations/unicode-and-encoding.md

@@ -0,0 +1,86 @@
+# Unicode and Encoding — i18n/RTL Expertise Module
+
+> Character encoding is the foundation: UTF-8 everywhere, normalization for comparison, and understanding code points vs grapheme clusters. Wrong encoding causes mojibake, broken emoji, and lost characters.
+
+> **Category:** Foundation
+> **Applies to:** All
+> **Key standards:** Unicode, UTF-8 (RFC 3629)
+> **RTL impact:** Low — encoding enables all scripts; RTL is layout
+
+## 1. Core Concepts
+
+### UTF-8 as Standard
+
+- **99% of web** uses UTF-8
+- Variable-width: 1–4 bytes per character
+- ASCII-compatible (bytes 0–127 identical)
+- Supports all 1.1M+ Unicode code points
+
+### Code Points vs Characters
+
+- **Code point:** U+0000 to U+10FFFF (e.g., U+0041 = 'A')
+- **Grapheme cluster:** What users perceive as one character (e.g., "é" = e + combining acute, or precomposed U+00E9)
+- **Surrogate pairs:** UTF-16 uses two 16-bit units for code points > U+FFFF; common bug source in JS (string length, indexing)
+
+### Unicode Normalization
+
+- **NFC** (Canonical Composition): Preferred for web; precomposed where possible
+- **NFD** (Canonical Decomposition): Decomposed; used in some systems
+- **NFKC/NFKD:** Compatibility forms; use for search/collation, not display
+- Use NFC for storage and comparison to avoid duplicate representations
+
+---
+
+## 2. Declaration and Configuration
+
+| Layer | How to Set UTF-8 |
+|-------|------------------|
+| HTML5 | `<meta charset="UTF-8">` |
+| HTTP | `Content-Type: text/html; charset=UTF-8` |
+| JSON API | `Content-Type: application/json; charset=UTF-8` |
+| MySQL | `utf8mb4` (not `utf8` — that's 3-byte only; emoji need 4) |
+| PostgreSQL | `UTF8` encoding |
+| Node/JS | Default UTF-8 in modern runtimes |
+| Python | `# -*- coding: utf-8 -*-` or default in Python 3 |
+
+---
+
+## 3. Locale Variations
+
+- **Arabic:** Requires UTF-8; no special encoding
+- **Hebrew:** Same
+- **CJK:** Multi-byte sequences; ensure no truncation at byte boundaries
+- **Emoji:** 4-byte sequences in UTF-8; `utf8mb4` in MySQL
+
+---
+
+## 4. Anti-Patterns
+
+1. **Assuming 1 byte = 1 character** — UTF-8 is variable-width
+2. **Truncating by byte count** — Can split multi-byte sequences; truncate by grapheme or code point
+3. **Using `utf8` in MySQL** — Use `utf8mb4` for full Unicode
+4. **No charset in HTTP/HTML** — Browsers guess; can cause mojibake
+5. **Double-encoding** — Encoding already-UTF-8 bytes again
+6. **String length for limits** — `"é".length` is 2 in JS (UTF-16); use grapheme segmentation for display limits
+7. **Case conversion without locale** — Turkish dotted i; use `toLocaleLowerCase('tr-TR')`
+
+---
+
+## 5. Testing
+
+- Test with: العربية, 日本語, emoji (👋), combining characters (é)
+- Verify no mojibake when submitting forms
+- Check DB storage and retrieval
+
+---
+
+## Quick Reference Checklist
+
+- [ ] UTF-8 declared in HTML, HTTP, DB
+- [ ] MySQL: `utf8mb4`
+- [ ] NFC normalization for comparison
+- [ ] No byte-based truncation of strings
+- [ ] Test with Arabic, CJK, emoji
+
+---
+*Researched: 2026-03-08 | Sources: Unicode FAQ, W3C forms UTF-8, Better i18n encoding*

package/expertise/i18n/index.md

@@ -0,0 +1,38 @@
+# i18n/RTL Expertise — Knowledge Base
+
+Comprehensive internationalization, localization, and RTL expertise for AI agents. Used during **Clarifier** (architecture) and **Dev** (implementation) to bake i18n in from day one.
+
+## Directory Structure
+
+```
+expertise/i18n/
+  foundations/     — Core concepts, standards, patterns
+  rtl/             — RTL-specific rules, Arabic, Hebrew
+  platform/        — Flutter, React, iOS, Android, Web, Backend
+  content/         — Translation, MT, adaptation
+  advanced/        — BiDi algorithm, complex scripts, a11y, performance
+  PROGRESS.md      — Research status
+```
+
+## Quick Navigation
+
+| Need | Read |
+|------|------|
+| Architecture decisions | foundations/i18n-architecture.md |
+| String extraction | foundations/string-externalization.md |
+| RTL layout rules | rtl/rtl-fundamentals.md, rtl/rtl-layout-mirroring.md |
+| Arabic specifics | rtl/arabic-specific.md |
+| Hebrew specifics | rtl/hebrew-specific.md |
+| Flutter i18n | platform/flutter-i18n.md |
+| React i18n | platform/react-i18n.md |
+| Web CSS RTL | platform/web-css-i18n.md |
+| BiDi text | foundations/text-direction-bidi.md |
+| Testing RTL | rtl/rtl-testing-and-qa.md |
+
+## Key Principles
+
+1. **Physical vs logical** — Use start/end, inline-start/end; never left/right for layout
+2. **Arabic ≠ Hebrew** — Different script, numerals, calendar, plurals
+3. **ICU for plurals** — Never `count === 1 ? 'item' : 'items'`
+4. **Intl for formats** — Never hardcode date/number formats
+5. **Real text for testing** — العربية، עברית — not placeholder

package/expertise/i18n/platform/backend-i18n.md

@@ -0,0 +1,31 @@
+# Backend i18n — i18n/RTL Expertise Module
+
+> Backend i18n: Accept-Language, locale parameter, message catalogs, and formatting. APIs return locale-aware content; never assume server locale.
+
+> **Category:** Platform
+> **Applies to:** Backend
+> **Key standards:** HTTP Accept-Language, BCP 47
+> **RTL impact:** Low — backend returns data; client handles layout
+
+## 1. Core Concepts
+
+- **Locale resolution:** Accept-Language header or ?locale= query param
+- **Message catalogs:** gettext, ICU, or JSON per locale
+- **Formatting:** Use ICU/Intl for dates, numbers, currency server-side
+- **Storage:** Store user locale preference; pass to formatting
+
+## 2. Implementation
+
+- Parse Accept-Language; resolve to supported locale
+- Load message catalog for locale
+- Format dates/numbers with locale
+- Return Content-Language in response
+
+## 3. Anti-Patterns
+
+- Assuming server locale
+- Hardcoded formats
+- No locale in API
+
+---
+*Researched: 2026-03-08 | Sources: HTTP i18n*

package/expertise/i18n/platform/flutter-i18n.md

@@ -0,0 +1,148 @@
+# Flutter i18n — i18n/RTL Expertise Module
+
+> Flutter's built-in i18n: ARB files, `flutter gen-l10n`, `AppLocalizations`, and RTL via `Directionality`. The `intl` package and `flutter_localizations` provide the foundation.
+
+> **Category:** Platform
+> **Applies to:** Mobile (Flutter)
+> **Key standards:** ARB, ICU MessageFormat
+> **RTL impact:** High — Directionality, EdgeInsetsDirectional, AlignmentDirectional
+
+## 1. Platform i18n System
+
+### Built-in Framework
+
+- **ARB** (Application Resource Bundle): JSON-based locale files
+- **Code generation:** `flutter gen-l10n` produces `AppLocalizations`
+- **Delegates:** `AppLocalizations.localizationsDelegates`
+- **Supported locales:** `AppLocalizations.supportedLocales`
+
+### RTL at System Level
+
+- `Directionality` widget; `TextDirection.rtl` for RTL
+- `MaterialApp` uses `locale` to set `Directionality` when supported locale is RTL (ar, he, etc.)
+- `EdgeInsetsDirectional`, `AlignmentDirectional`, `AlignmentDirectional` for layout
+
+### Locale Resolution
+
+- `MaterialApp.locale` or `supportedLocales` with `localeResolutionCallback`
+- Fallback: first `supportedLocales` when no match
+
+---
+
+## 2. Setup Guide
+
+### pubspec.yaml
+
+```yaml
+dependencies:
+  flutter_localizations:
+    sdk: flutter
+  intl: ^0.19.0
+
+flutter:
+  generate: true
+```
+
+### l10n.yaml
+
+```yaml
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+```
+
+### Folder Structure
+
+```
+lib/
+  l10n/
+    app_en.arb
+    app_ar.arb
+    app_he.arb
+```
+
+### MaterialApp
+
+```dart
+MaterialApp(
+  localizationsDelegates: AppLocalizations.localizationsDelegates,
+  supportedLocales: AppLocalizations.supportedLocales,
+  home: Home(),
+)
+```
+
+---
+
+## 3. Key APIs and Patterns
+
+### String Localization
+
+```dart
+AppLocalizations.of(context)!.greeting('أحمد')
+```
+
+### ARB with Placeholders
+
+```json
+{
+  "greeting": "Hello, {name}!",
+  "@greeting": {
+    "placeholders": { "name": { "type": "String" } }
+  }
+}
+```
+
+### Plural (ICU)
+
+```json
+{
+  "itemCount": "{count, plural, =0{No items} one{1 item} other{# items}}",
+  "@itemCount": { "placeholders": { "count": { "type": "int" } } }
+}
+```
+
+### Date/Number Formatting
+
+```dart
+DateFormat.yMd(locale).format(date)
+intl.NumberFormat.decimalPattern(locale).format(number)
+```
+
+### RTL
+
+```dart
+Directionality.of(context) == TextDirection.rtl
+EdgeInsetsDirectional.only(start: 16, end: 8)
+AlignmentDirectional.centerStart
+```
+
+---
+
+## 4. RTL Support
+
+- Add `ar`, `he`, `fa`, `ur` to `supportedLocales`
+- Use `EdgeInsetsDirectional`, `AlignmentDirectional`, `Positioned.directional`
+- Icons: many auto-mirror; use `Transform` for custom
+- `TextDirection.rtl` for RTL text
+
+---
+
+## 5. Anti-Patterns
+
+1. **EdgeInsets.only(left: 16)** — Use `EdgeInsetsDirectional.only(start: 16)`
+2. **Alignment.centerLeft** — Use `AlignmentDirectional.centerStart`
+3. **Missing RTL locales** — Add ar, he to supportedLocales
+4. **Hardcoded strings** — Always use AppLocalizations
+
+---
+
+## Quick Reference Checklist
+
+- [ ] flutter_localizations + intl
+- [ ] l10n.yaml + ARB files
+- [ ] supportedLocales includes ar, he
+- [ ] EdgeInsetsDirectional, AlignmentDirectional
+- [ ] Run flutter gen-l10n
+
+---
+*Researched: 2026-03-08 | Sources: Flutter docs, IntlPull Flutter guide*

package/expertise/i18n/platform/native-android-i18n.md

@@ -0,0 +1,36 @@
+# Native Android i18n — i18n/RTL Expertise Module
+
+> Android i18n: strings.xml, plurals, getString(), and RTL via layoutDirection, start/end attributes, and AutoMirrored drawables.
+
+> **Category:** Platform
+> **Applies to:** Mobile (Android)
+> **Key standards:** Android Resources
+> **RTL impact:** High — layoutDirection, start/end
+
+## 1. Platform i18n System
+
+- **Strings:** res/values/strings.xml, res/values-ar/strings.xml
+- **Plurals:** plurals resource with quantity
+- **API:** getString(R.string.key), getQuantityString()
+- **RTL:** android:layoutDirection="locale", layout_marginStart/End
+
+## 2. Setup
+
+- Create values-ar, values-he for RTL
+- Use start/end in XML (not left/right)
+- Icons.AutoMirrored for directional icons
+
+## 3. RTL
+
+- layoutDirection="rtl" or "locale"
+- layout_marginStart, paddingStart
+- getLayoutDirectionFromLocale()
+
+## 4. Anti-Patterns
+
+- layout_marginLeft/Right
+- Hardcoded strings
+- No RTL resource directories
+
+---
+*Researched: 2026-03-08 | Sources: Android docs*

package/expertise/i18n/platform/native-ios-i18n.md

@@ -0,0 +1,36 @@
+# Native iOS i18n — i18n/RTL Expertise Module
+
+> iOS i18n: Localizable.strings, .stringsdict for plurals, NSLocalizedString, and RTL via leading/trailing constraints and semanticContentAttribute.
+
+> **Category:** Platform
+> **Applies to:** Mobile (iOS)
+> **Key standards:** Apple Localization
+> **RTL impact:** High — leading/trailing, semanticContentAttribute
+
+## 1. Platform i18n System
+
+- **Strings:** Localizable.strings (`"key" = "value";`)
+- **Plurals:** .stringsdict
+- **API:** NSLocalizedString, String(localized:)
+- **RTL:** leading/trailing in Auto Layout; UIView.semanticContentAttribute
+
+## 2. Setup
+
+- Add languages in Project → Info → Localizations
+- Create Localizable.strings per locale
+- Use NSLocalizedString("key", comment: "")
+
+## 3. RTL
+
+- Use leadingAnchor, trailingAnchor (not left/right)
+- semanticContentAttribute = .forceRightToLeft for RTL
+- SF Symbols auto-mirror many directional icons
+
+## 4. Anti-Patterns
+
+- left/right constraints
+- Hardcoded strings
+- No RTL testing
+
+---
+*Researched: 2026-03-08 | Sources: Apple HIG, Developer docs*