voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-mobile/skills/void-expo-config-plugins/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: void-expo-config-plugins
+description: Add native functionality to an Expo app via config plugins, never by ejecting. Pick existing Expo modules first, write a custom plugin only when none fits. Document everything in app.config.ts.
+---
+
+# expo-config-plugins
+
+Use when an Expo app needs functionality not available in JS — push notifications, camera, haptics, secure storage, or any native iOS/Android API. The Expo way: config plugins + Expo Modules. Ejecting to bare React Native is a one-way door — almost never the right answer.
+
+## The decision tree
+
+```
+1. Is there an `expo-X` package on npm?         → use it (e.g., expo-camera, expo-haptics)
+2. Is there a community config plugin?           → use it (search "expo-plugin" + your need)
+3. Does it just need a Podfile / Manifest tweak? → write a custom config plugin (~30 lines)
+4. Does it need new Swift/Kotlin code?           → write an Expo Module
+5. Truly nothing fits?                           → reconsider the requirement; ejecting last resort
+```
+
+Most teams hit (1) for 80% of needs and never go past (3).
+
+## What a config plugin is
+
+A function that mutates the native iOS/Android project files at build time. It does not run in the app — it runs in EAS Build / `expo prebuild`.
+
+```ts
+// app.config.ts
+import { ConfigContext, ExpoConfig } from 'expo/config';
+
+export default ({ config }: ConfigContext): ExpoConfig => ({
+  ...config,
+  name: 'Solaar',
+  slug: 'solaar',
+  plugins: [
+    'expo-router',
+    'expo-secure-store',
+    [
+      'expo-build-properties',
+      {
+        ios: { deploymentTarget: '15.1', useFrameworks: 'static' },
+        android: { compileSdkVersion: 34, targetSdkVersion: 34 },
+      },
+    ],
+    './plugins/my-custom-plugin',     // local plugin
+  ],
+});
+```
+
+Each entry is either:
+
+- A string: package name; uses the package's default plugin
+- A tuple `[name, props]`: passes config to the plugin
+
+## Common Expo modules
+
+Pin the ones below mentally — they handle 80% of native needs:
+
+| Need | Package |
+|---|---|
+| Camera | `expo-camera` |
+| Push notifications | `expo-notifications` |
+| Haptics (vibrate, tap feedback) | `expo-haptics` |
+| Secure storage (keychain / keystore) | `expo-secure-store` |
+| File system | `expo-file-system` |
+| Local notifications | `expo-notifications` |
+| Authentication (OAuth, biometrics) | `expo-auth-session`, `expo-local-authentication` |
+| Location | `expo-location` |
+| Linking (deep links) | `expo-linking` |
+| Updates | `expo-updates` |
+| Sharing | `expo-sharing` |
+| WebView | `expo-webview` (or `react-native-webview`) |
+| Storage (key-value) | `expo-sqlite` or `react-native-mmkv` |
+
+For each: install, add to `plugins` array if it needs prebuild config, use the JS API in your code.
+
+## When to write a custom plugin
+
+Two cases:
+
+### A. Config-only (Info.plist, AndroidManifest tweaks)
+
+```ts
+// plugins/with-app-tracking.ts
+import { ConfigPlugin, withInfoPlist } from 'expo/config-plugins';
+
+const withAppTracking: ConfigPlugin<{ reason: string }> = (config, { reason }) => {
+  return withInfoPlist(config, (cfg) => {
+    cfg.modResults.NSUserTrackingUsageDescription = reason;
+    return cfg;
+  });
+};
+
+export default withAppTracking;
+```
+
+Usage:
+
+```ts
+// app.config.ts
+plugins: [
+  ['./plugins/with-app-tracking', { reason: 'Personalize your experience' }],
+];
+```
+
+This pattern handles: permission strings, URL schemes, custom Info.plist keys, AndroidManifest entries, build settings.
+
+### B. Native code (Swift / Kotlin)
+
+If you need actual native code, write an **Expo Module**, not a config plugin. Expo Modules are first-class native modules with auto-linking + TS bindings.
+
+```bash
+npx create-expo-module@latest --local my-native-module
+```
+
+The generated package has `ios/`, `android/`, and `src/` (TS bindings). Build runs `expo prebuild` automatically.
+
+## When NOT to do native
+
+Most "I need a native feature" turns out to be solvable in JS:
+
+- **"I need to read the file system"** → `expo-file-system`, no native code
+- **"I need biometric auth"** → `expo-local-authentication`
+- **"I need to detect device type"** → `expo-device` provides everything
+
+Try the JS path first. Native is overhead: build complexity, EAS Build minutes, debugging hardness.
+
+## `app.config.ts` vs `app.json`
+
+Use `app.config.ts`. Reasons:
+
+- TypeScript = typo-safe
+- Dynamic values (env vars, computed flags) supported
+- One source of truth for dev/staging/prod variants
+
+Example:
+
+```ts
+// app.config.ts
+import { ConfigContext, ExpoConfig } from 'expo/config';
+
+const variant = process.env.APP_VARIANT ?? 'dev';
+
+export default ({ config }: ConfigContext): ExpoConfig => ({
+  ...config,
+  name: variant === 'prod' ? 'Solaar' : `Solaar (${variant})`,
+  slug: 'solaar',
+  ios: {
+    bundleIdentifier: `io.voidcorp.solaar.${variant}`,
+  },
+  android: {
+    package: `io.voidcorp.solaar.${variant}`,
+  },
+  extra: {
+    apiUrl: process.env.EXPO_PUBLIC_API_URL,
+  },
+});
+```
+
+Dev + staging + prod variants installed side-by-side on a single device thanks to bundle ID variation.
+
+## Anti-patterns
+
+- ✗ **Ejecting on first sign of native need** — almost always reversible to "use an Expo module"
+- ✗ **Hand-editing `ios/` or `android/`** after prebuild — gets nuked on next `expo prebuild`; bad merges between repo and prebuild
+- ✗ **Mixing `app.json` and `app.config.ts`** — pick one, delete the other; precedence is unclear
+- ✗ **`extra` field used for secrets** — `extra` ships in the JS bundle, visible to anyone
+- ✗ **Plugin order matters and you ignored it** — some plugins must come before others (e.g., expo-router before any router consumer); follow plugin docs
+
+## Verification
+
+`npx expo prebuild --no-install --clean` — runs the plugin pipeline locally, generates `ios/` and `android/` you can inspect. If something's broken at native level, you'll see it before EAS.
+
+## Composition
+
+- `void-eas-build-profile` — config plugins + build profiles together define what binary ships
+- `void-ota-update-strategy` — JS-only changes don't need a rebuild; native config changes do
+- `void-state-architecture` — share state architecture with web siblings; only native deps differ
+- `void-env-validation` — env reaches the app via `extra` or EAS Build env; validate with same schema discipline

package/core-assets/packs/pack-mobile/skills/void-expo-config-plugins/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-mobile/skills/void-expo-router-pattern/.source

@@ -0,0 +1,8 @@
+Sources for `void-expo-router-pattern` skill (see `docs/plans/skill-audits/void-expo-router-pattern.md` for the full audit):
+
+- expo-router official documentation — no URL recorded in the audit — distilled the file-based routing conventions (`(tabs)/`, `(modal)/`, `(auth)/`, per-group `_layout.tsx`, typed routes via `experiments.typedRoutes`, deep-link auto-config).
+- Next.js App Router conventions — no URL recorded in the audit — used as the shared mental model expo-router mirrors by design, so a monorepo keeps one routing model across web and mobile.
+
+No external skill ships this verbatim; authored by distilling the expo-router docs and aligning them to the Next.js App Router convention.
+
+Strategy: distill. Lean on the deliberate Next.js parity so devs do not reinvent React Navigation patterns.

package/core-assets/packs/pack-mobile/skills/void-expo-router-pattern/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: void-expo-router-pattern
+description: File-based routing in Expo via expo-router — layouts, tabs, modals, deep links. Mirrors Next.js App Router so monorepos can share mental model. Stack-aware navigation patterns.
+---
+
+# expo-router-pattern
+
+Use when adding screens / navigation to an Expo app using `expo-router`. The convention mirrors Next.js App Router by design — same `(group)/`, `_layout.tsx`, `[param]`, dynamic segments — so a monorepo sharing web + mobile keeps one routing mental model.
+
+If your app uses React Navigation directly (not expo-router), this skill does not apply (different API entirely).
+
+## File layout (Solaar archetype)
+
+```
+apps/mobile/app/
+├── _layout.tsx                # root layout: providers, Stack navigator
+├── (tabs)/                    # tab navigation root
+│   ├── _layout.tsx            # tab bar config
+│   ├── index.tsx              # / → Home tab
+│   ├── contacts/
+│   │   ├── index.tsx          # /contacts
+│   │   └── [id].tsx           # /contacts/123
+│   ├── notes.tsx
+│   └── settings.tsx
+├── (modal)/                   # modal-presented screens
+│   ├── _layout.tsx            # presentation: 'modal'
+│   ├── new-contact.tsx        # /new-contact (slides up)
+│   └── share.tsx
+├── (auth)/                    # auth flow (no tabs)
+│   ├── _layout.tsx            # presentation: stack, no tab bar
+│   ├── sign-in.tsx
+│   └── sign-up.tsx
+└── +not-found.tsx             # 404
+```
+
+## Layouts: what each `_layout.tsx` does
+
+### Root `app/_layout.tsx`
+
+- Wraps `<Stack />` (or `<Slot />` for layoutless)
+- Provides global Providers (Auth, Query Client, Theme, i18n)
+- Initializes Sentry, fonts, splash hide
+- Owns navigation theme (`DarkTheme` / `DefaultTheme`)
+
+```tsx
+// app/_layout.tsx
+import { Stack } from 'expo-router';
+import { Providers } from '@/providers';
+import { useFonts } from 'expo-font';
+import * as SplashScreen from 'expo-splash-screen';
+
+SplashScreen.preventAutoHideAsync();
+
+export default function RootLayout() {
+  const [loaded] = useFonts({ /* ... */ });
+  if (!loaded) return null;
+
+  return (
+    <Providers>
+      <Stack screenOptions={{ headerShown: false }}>
+        <Stack.Screen name="(tabs)" />
+        <Stack.Screen name="(modal)" options={{ presentation: 'modal' }} />
+        <Stack.Screen name="(auth)" />
+      </Stack>
+    </Providers>
+  );
+}
+```
+
+### `(tabs)/_layout.tsx`
+
+```tsx
+import { Tabs } from 'expo-router';
+
+export default function TabsLayout() {
+  return (
+    <Tabs screenOptions={{ tabBarActiveTintColor: 'gold' }}>
+      <Tabs.Screen name="index" options={{ title: 'Accueil' }} />
+      <Tabs.Screen name="contacts" options={{ title: 'Contacts' }} />
+      <Tabs.Screen name="notes" options={{ title: 'Notes' }} />
+      <Tabs.Screen name="settings" options={{ title: 'Réglages' }} />
+    </Tabs>
+  );
+}
+```
+
+### `(modal)/_layout.tsx`
+
+```tsx
+import { Stack } from 'expo-router';
+
+export default function ModalLayout() {
+  return <Stack screenOptions={{ presentation: 'modal' }} />;
+}
+```
+
+## Navigation primitives
+
+```tsx
+import { useRouter, Link } from 'expo-router';
+
+function ContactCard({ id }: { id: string }) {
+  const router = useRouter();
+  return (
+    <>
+      {/* Imperative */}
+      <Pressable onPress={() => router.push(`/contacts/${id}`)} />
+
+      {/* Declarative — composes with Tappable from @repo/ui */}
+      <Link href={{ pathname: '/contacts/[id]', params: { id } }} asChild>
+        <Tappable>{children}</Tappable>
+      </Link>
+    </>
+  );
+}
+```
+
+Prefer `<Link>` over `router.push` — typed params, better a11y (renders an actual touchable surface), works with deep links.
+
+## Dynamic segments + typed routes
+
+```
+app/(tabs)/contacts/[id].tsx     →  /contacts/:id
+app/(tabs)/contacts/[...rest].tsx →  /contacts/* (catch-all)
+```
+
+Access params:
+
+```tsx
+import { useLocalSearchParams } from 'expo-router';
+
+export default function Contact() {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  return <ContactView id={id} />;
+}
+```
+
+Enable **typed routes** in `app.config.ts`:
+
+```ts
+experiments: { typedRoutes: true }
+```
+
+Then `<Link href="/contacts/xyz" />` is type-checked at build time.
+
+## Deep links
+
+`expo-router` automatically configures deep links from the file structure. To open the app at `/contacts/123` from outside:
+
+```
+iOS: yourscheme://contacts/123
+Android: same
+Universal Link / App Link: https://app.solaar.com/contacts/123
+```
+
+`scheme` in `app.config.ts`:
+
+```ts
+scheme: 'solaar',
+```
+
+Universal Links need additional setup (`apple-app-site-association`, `assetlinks.json` on the web).
+
+## Modals
+
+Two patterns:
+
+### A. Modal as a route (`(modal)/` group)
+
+Stack-based modal presentation, full route URL, supports deep linking. Use for screens that ARE work — new-contact form, share sheet, settings detail.
+
+### B. Modal as local state
+
+`useState` + a `<Modal>` component from React Native or Radix-ish mobile library. Use for transient UI — confirmation dialog, toast.
+
+Same rule as web: if the modal should be shareable / deep-linkable / browser-backable, it's a route. Otherwise local state.
+
+## Auth flow
+
+`(auth)/` group with its own layout, no tab bar. Root layout redirects unauthenticated users:
+
+```tsx
+// app/_layout.tsx
+import { Redirect } from 'expo-router';
+import { useAuth } from '@/auth';
+
+export default function RootLayout() {
+  const { user, loading } = useAuth();
+  if (loading) return null;
+  if (!user) return <Redirect href="/sign-in" />;
+  return <Stack>...</Stack>;
+}
+```
+
+## Anti-patterns
+
+- ✗ **Mixing `react-navigation` directly with `expo-router`** — they conflict; pick one
+- ✗ **One mega `_layout.tsx` at root with all logic** — push down to per-group layouts
+- ✗ **Dynamic `useEffect` to redirect** — use `<Redirect>` or middleware-like guards in `_layout.tsx`
+- ✗ **`router.replace` in render** — only call navigation actions in effects/handlers
+- ✗ **Hardcoded path strings everywhere** — enable typedRoutes; centralize destinations in a constants file otherwise
+
+## Composition
+
+- `void-expo-config-plugins` — `expo-router` is itself a config plugin (`plugins: ['expo-router']`)
+- `void-eas-build-profile` — dev profile must have `developmentClient: true` for expo-router to work in dev
+- `void-route-group-decision` — same `(group)/` convention; same WHY (group by trust posture)
+- `void-state-architecture` — modal-as-route vs modal-as-state decision
+- `void-accessibility-check` — touch targets, focus management apply identically

package/core-assets/packs/pack-mobile/skills/void-expo-router-pattern/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-mobile/skills/void-ota-update-strategy/.source

@@ -0,0 +1,7 @@
+Sources for `void-ota-update-strategy` skill (see `docs/plans/skill-audits/void-ota-update-strategy.md` for the full audit):
+
+- EAS Update official documentation — no URL recorded in the audit — distilled the runtime-version model (fingerprint vs appVersion policy), the JS-only-vs-rebuild boundary, channels, and rollback into a change-type table plus an explicit "what CAN'T go in OTA" list, with a strong recommendation toward the fingerprint policy.
+
+No external skill ships this verbatim; authored by distilling the official EAS Update docs into the void-machine "when can I OTA vs when do I rebuild" decision.
+
+Strategy: distill. Surface the quiet runtime-version footgun explicitly rather than leave it scattered across the docs.

package/core-assets/packs/pack-mobile/skills/void-ota-update-strategy/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: void-ota-update-strategy
+description: Ship JS-only fixes via EAS Update; full rebuild via EAS Build. Runtime versions, channels, rollback. The "when can I OTA vs when do I rebuild" decision.
+---
+
+# ota-update-strategy
+
+Use when planning to ship a change to an Expo app already in users' hands. The fundamental choice: **JS-only change** → EAS Update (minutes); **native change** → EAS Build + store submit (hours/days). Getting this wrong means either users running broken apps or unnecessary store rejections.
+
+## The fundamental rule
+
+| Change type | Path | Speed |
+|---|---|---|
+| JS bug fix (logic, UI text, layout) | EAS Update | Minutes |
+| Adding a new screen (no new native dep) | EAS Update | Minutes |
+| Changing a string in `app.config.ts` env | EAS Update if same plugins | Minutes |
+| New `expo-X` package added to plugins | EAS Build + submit | Hours + store review days |
+| Native config changes (Info.plist, permissions) | EAS Build + submit | Hours + store review |
+| New native module | EAS Build + submit | Hours + store review |
+| Bump SDK version | EAS Build + submit | Hours + store review |
+
+When in doubt: if the change touches `plugins:` or `ios:`/`android:` config in `app.config.ts`, it needs a rebuild.
+
+## Branches and channels (mental model)
+
+EAS Update splits the publishing target in two layers:
+
+- **Branch** — where you PUBLISH an update (`eas update --branch production`)
+- **Channel** — what the BUILD reads from (declared in `eas.json` per profile)
+
+Builds read from a channel; channels point at branches; you publish to branches.
+
+```jsonc
+// eas.json
+"production": {
+  "channel": "production",
+  // ...
+}
+```
+
+This build is on channel `production`. By default, channel `production` points at branch `production`. To re-point: `eas channel:edit production --branch <other>`.
+
+Publish to the production branch (so the production channel picks it up):
+
+```bash
+eas update --branch production --message "Fix avatar crash on iOS"
+```
+
+A user with a production-channel build pulls this update on next app launch.
+
+Pre-launch / staging:
+
+```bash
+eas update --branch preview --message "..."
+```
+
+Users with a preview-channel build get this update; production users don't see it (different channel → different branch).
+
+## Runtime versions — the critical detail
+
+`expo-updates` checks **runtime version** before applying an update. If the update's runtime version doesn't match the build's, the update is silently skipped.
+
+```ts
+// app.config.ts
+runtimeVersion: { policy: 'fingerprint' },
+```
+
+`'fingerprint'` is the modern policy: SDK + every native plugin + every native dep contribute to a hash. Add a native plugin → fingerprint changes → new builds have new runtime version → old builds won't accept new updates (which is correct: old build can't run the new code anyway).
+
+Other policies:
+
+- `'appVersion'` — uses `version` field (manual; you remember to bump it when adding native)
+- `'sdkVersion'` — every SDK bump = new runtime (coarse; native changes within an SDK rev don't trigger)
+
+`fingerprint` is the right default; the others are legacy. Don't use them on new apps.
+
+## Update strategy: when does the user actually see the update
+
+`expo-updates` config:
+
+```ts
+// app.config.ts (extra section or via expo-updates config block)
+updates: {
+  enabled: true,
+  checkAutomatically: 'ON_LOAD',     // check on every cold start
+  fallbackToCacheTimeout: 0,         // 0 = use cache instantly, check in background
+}
+```
+
+| `checkAutomatically` | When checks happen |
+|---|---|
+| `ON_LOAD` | Every cold start |
+| `ON_ERROR_RECOVERY` | Only after a crash |
+| `NEVER` | Manual only (call `Updates.checkForUpdateAsync()` yourself) |
+
+For most apps, `ON_LOAD` + `fallbackToCacheTimeout: 0` is right: instant launch with cached code, update applied silently on next launch.
+
+If you need immediate apply (critical security fix), code-call:
+
+```ts
+import * as Updates from 'expo-updates';
+
+async function applyUpdateIfAvailable() {
+  const update = await Updates.checkForUpdateAsync();
+  if (update.isAvailable) {
+    await Updates.fetchUpdateAsync();
+    await Updates.reloadAsync();         // forces immediate reload
+  }
+}
+```
+
+Show a confirmation UI before forced reload — don't yank the user out of their current task.
+
+## Rollback
+
+If an update is broken, deploy a fixed one — there's no "delete" for OTA updates, but newer wins.
+
+```bash
+eas update --branch production --message "Revert: avatar crash fix had its own bug"
+```
+
+The new update reverts the change in code. Users get it on next check.
+
+For a hard halt of bad updates, republish a known-good update at the head of the branch:
+
+```bash
+eas update:republish --branch production --group <previous-good-update-id>
+```
+
+Or re-point the production channel at a known-good branch:
+
+```bash
+eas channel:edit production --branch production-stable
+```
+
+This shifts every production-channel build to read the alternate branch.
+
+## Testing updates before production
+
+`eas channel:edit` lets you point a channel at any branch:
+
+```bash
+# Build was on production, but you want to test an update from "experimental" branch
+eas channel:edit production --branch experimental
+```
+
+Test on real production-channel builds → switch back to production branch when validated:
+
+```bash
+eas channel:edit production --branch production
+```
+
+## What CAN'T go in an OTA update
+
+- Anything touching native code (SDK bump, new module, config plugin change)
+- Adding new permissions
+- Changing the bundle ID, name, icon
+- Splash screen image change (it's pre-bundled in the native shell)
+
+These all require EAS Build + store submission. Plan ahead.
+
+## Anti-patterns
+
+- ✗ **`'appVersion'` runtime policy** — silently skips updates when devs forget to bump version. `fingerprint` removes this trap.
+- ✗ **OTA-ing a native dep change** — update silently doesn't apply (different runtime version). Confusing for hours of debugging.
+- ✗ **`Updates.reloadAsync()` without warning** — yanks user mid-task; bad UX
+- ✗ **Same channel for staging + prod** — staging users get prod updates; prod users get unfinished work
+- ✗ **No `extra` field for update metadata** — can't tell "which build is this user on" in Sentry / analytics
+
+## Verification
+
+After deploying an update:
+
+```bash
+eas update:list --branch production --limit 5
+```
+
+Shows recent updates with IDs, messages, runtime versions, dates. Spot the new one.
+
+In the app, check:
+
+```ts
+import * as Updates from 'expo-updates';
+console.log(Updates.updateId, Updates.createdAt);
+```
+
+This logs which update the user is currently on. Useful in a debug screen for QA.
+
+## Composition
+
+- `void-eas-build-profile` — channel names map to build profile names
+- `void-expo-config-plugins` — plugin changes invalidate runtime versions
+- `void-observability` — log `Updates.updateId` in every Sentry event so you can correlate "which JS is running"
+- `void-async-safety` — `Updates.checkForUpdateAsync()` failures should not block app launch; timeout + fallback to cached

package/core-assets/packs/pack-mobile/skills/void-ota-update-strategy/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-monorepo/skills/void-dependency-direction/.source

@@ -0,0 +1,5 @@
+Sources for `void-dependency-direction` skill (see `docs/plans/skill-audits/void-dependency-direction.md` for the full audit):
+
+- No external source. Native concretization of the `01-monorepo-layout.md` module's abstract `@repo/*` import rules into worked examples.
+
+Strategy: native. Distills the module topology into concrete violation-plus-fix examples; core `void-hexagonal-architecture` is the generic doctrine, this is the monorepo-specific operational guide.