voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-nextjs/skills/void-parallel-routes-slots/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: void-parallel-routes-slots
+description: Use Next.js parallel routes (@slot) and intercepting routes ((.)foo) — when they're the right tool, when they're an anti-pattern. The "modal that's also a deep-linkable page" archetype.
+---
+
+# parallel-routes-slots
+
+Use when you need to render **multiple independent UI pieces in the same layout that can navigate independently**, or to **show a modal that's also a deep-linkable route**. Parallel routes and intercepting routes are powerful but easy to mis-apply.
+
+If you only need a different page at a different URL → use a normal route. No slots needed.
+
+## Parallel routes (`@slot`)
+
+A `@slot` folder is a **named layout slot** that can be filled by any of its child pages.
+
+```
+app/dashboard/
+├── @analytics/
+│   ├── page.tsx                # default content for the slot
+│   └── audience/page.tsx       # different content at the slot
+├── @team/
+│   ├── page.tsx
+│   └── invite/page.tsx
+└── layout.tsx                  # consumes both slots
+```
+
+```tsx
+// app/dashboard/layout.tsx
+export default function Layout({
+  children,
+  analytics,
+  team,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+  team: React.ReactNode;
+}) {
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      <main className="col-span-2">{children}</main>
+      <aside>{analytics}</aside>
+      <aside>{team}</aside>
+    </div>
+  );
+}
+```
+
+Each slot can independently navigate. The URL `/dashboard/audience/invite` could render `@analytics/audience` AND `@team/invite` AND the main `children` page simultaneously.
+
+## When parallel routes WIN
+
+- **Dashboard layouts** with widgets that load independently and can be refreshed/navigated without rerouting the main view
+- **Admin panels** with side panels showing different details based on selection
+- **Layouts where streaming partial content matters**: each slot has its own loading.tsx, so the user sees content as each piece arrives
+
+## When parallel routes LOSE
+
+- A single page with sections → just compose components in the page, no slots needed
+- Conditional rendering based on user role → handle in the page, not via slots
+- Modals (use intercepting routes — different mechanism, below)
+- Mobile-first apps where slot layouts collapse to stack anyway → adds complexity for no gain on mobile
+
+## Default content (`page.tsx`) per slot
+
+Every slot **must** have a `page.tsx` rendering its default empty state. Without it, you get a 404 when the slot is "empty" but the parent route renders. Common forgetting → cryptic Next errors.
+
+## Intercepting routes — the modal pattern
+
+`(.)foo`, `(..)foo`, `(..)(..)foo`, `(...)foo` intercept a URL and render a different component **based on how the user arrived**.
+
+```
+app/
+├── photos/
+│   ├── [id]/
+│   │   └── page.tsx              # full-page photo view
+│   └── page.tsx                  # photo grid
+└── @modal/
+    └── (.)photos/[id]/
+        └── page.tsx              # modal photo view
+```
+
+When the user is on `/photos` and clicks a photo, the URL changes to `/photos/123` but they see a MODAL on top of the grid (the intercepting route fires). If they refresh or share the link, they get the full-page view.
+
+This is the **deep-linkable modal** pattern — modal for in-app navigation, full page for direct link.
+
+## Intercepting route syntax
+
+| Pattern | Means |
+|---|---|
+| `(.)foo` | Intercept `foo` from the same level |
+| `(..)foo` | Intercept `foo` from one level up |
+| `(..)(..)foo` | Intercept from two levels up |
+| `(...)foo` | Intercept from the root |
+
+The dots count is **route-segment** counts, not file-path. Easy to miscount.
+
+## When intercepting routes WIN
+
+- Photo viewer, image gallery (the canonical use case)
+- "Edit" / "Quick view" overlays that should be linkable
+- Onboarding wizards that take over the UI but stay on a route
+
+## When intercepting routes LOSE
+
+- Truly transient modals (delete confirmation, settings) — use state, not routes
+- Mobile drawers / sheets — usually trigger different UX patterns, intercepting is overkill
+- Modals that aren't shareable — adds URL complexity for no benefit
+
+## Anti-patterns
+
+- ✗ **Slots without default `page.tsx`** — runtime errors when slot is "empty"
+- ✗ **Nested intercepting routes** — debugging becomes impossible
+- ✗ **Mixing slots with `useState` modal management** in the same surface — pick one
+- ✗ **Slot for what should be a component** — if the content doesn't navigate independently, it's a component, not a slot
+- ✗ **Intercepting routes that don't have a non-intercepting fallback** — refresh shows 404 instead of the full-page view
+
+## Workflow
+
+1. **Default**: simple route. No slots. No interception.
+2. **Need independent loading + navigation** of UI pieces in same layout? → parallel routes
+3. **Need a modal that's also a deep link** (refresh works, share link works)? → intercepting routes
+4. **Otherwise**: state-managed modal/sheet via `useState` + Radix Dialog.
+
+## Composition
+
+- `void-route-group-decision` — slots and intercepting routes live within route groups.
+- `void-cache-component-pattern` — each slot has its own cache scope.
+- `void-loading-error-boundaries` — slots can have their own `loading.tsx`, `error.tsx`.
+- `void-state-architecture` — transient modals use `useState`, not routes.

package/core-assets/packs/pack-nextjs/skills/void-parallel-routes-slots/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-nextjs/skills/void-route-group-decision/.source

@@ -0,0 +1,5 @@
+Sources for `void-route-group-decision` skill (see `docs/plans/skill-audits/void-route-group-decision.md` for the full audit):
+
+- No external source listed in the audit. Original void-machine convention: group route groups (name) by trust boundary, not visual section, behind a 3-condition gate.
+
+Strategy: native. Authored from scratch as a void-machine convention; no external source.

package/core-assets/packs/pack-nextjs/skills/void-route-group-decision/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: void-route-group-decision
+description: Decide when to use a (route-group), what to name it, and how to share layouts. The void-machine convention groups by trust boundary, not by visual section.
+---
+
+# route-group-decision
+
+Use when adding any new route in `app/`, or when refactor an existing flat `app/` into groups. Route groups (folders named `(name)`) don't affect URL but DO affect layout and convention scope.
+
+## The void-machine convention
+
+```
+app/
+├── (api|actions)/        # trust boundaries (Server Actions, route handlers)
+│   ├── (actions)/<feature>/
+│   └── (api)/<resource>/route.ts
+├── (marketing)/          # public, statically rendered, no auth
+│   ├── layout.tsx        # marketing nav + footer
+│   ├── page.tsx          # /
+│   ├── pricing/page.tsx  # /pricing
+│   └── blog/[slug]/page.tsx
+├── (app)/                # authenticated app
+│   ├── layout.tsx        # auth gate + app shell
+│   ├── dashboard/page.tsx
+│   └── settings/page.tsx
+└── api/webhooks/<source>/route.ts   # webhooks NOT in (api|actions) — different lifecycle
+```
+
+The principle: **group by trust boundary and rendering model, not by visual section**.
+
+## Why these specific groups
+
+- `(api|actions)` — every file inside is a trust boundary. The skill `void-server-action` applies. The "no fetch in components" rule applies in reverse: these files MUST fetch / mutate.
+- `(marketing)` — statically renderable (Cache Components opted in by default), no auth, indexable by search engines. Different layout (marketing nav vs app shell).
+- `(app)` — authenticated. Layout checks session, redirects to login if absent. All routes inside trust the layout's auth gate.
+- `api/webhooks/<source>/` — NOT in a route group because the convention is path-stable for external systems. Stripe sends to `/api/webhooks/stripe`, period.
+
+## When to add a new group
+
+You need ALL three:
+
+1. **A distinct layout** the new routes share (not just a different page)
+2. **A distinct trust posture** OR rendering model (cached vs dynamic, auth vs public)
+3. **≥ 2 routes** that fit the group
+
+If you'd only put one route inside, don't add the group. Put the route in the closest existing group or at top level.
+
+## Naming the group
+
+- Use parentheses: `(name)` — they're invisible in URL
+- Lowercase, single word, plural if it represents a category
+- Conventional names: `(api|actions)`, `(marketing)`, `(app)`, `(admin)`, `(public)`, `(authed)`
+- Avoid: `(misc)`, `(stuff)`, `(my-new-feature)` — groups are coarse, not feature-scoped
+
+## Sharing layouts across groups
+
+You can't directly — groups are siblings, each owns its layout. To share a header across `(marketing)` and `(app)`:
+
+- Option A: put the shared header in `app/layout.tsx` (the root)
+- Option B: extract the header as a component, import in each group's layout
+
+A is cleaner if the header is truly shared by every group. B is right if only some groups share it.
+
+## The `app/layout.tsx` (root)
+
+ONE root layout, contains:
+
+- `<html>` and `<body>` tags (mandatory — only the root layout has these)
+- Providers needed everywhere (Theme, i18n, Sentry, query client if RQ used)
+- Global stylesheets
+
+Should NOT contain:
+
+- Navigation (lives in group layouts)
+- Auth check (lives in `(app)/layout.tsx`)
+- Marketing-specific markup
+
+If root layout grows past 40 lines, you have layout-creep — push down.
+
+## Parallel routes and intercepting routes — separate concept
+
+`@modal`, `(.)`, `(..)`, `(..)(..)`, `(...)` are **NOT** route groups. They're parallel/intercepting routes. See `void-parallel-routes-slots` for that pattern.
+
+A route group is `(name)` (parentheses around a folder). Don't confuse them.
+
+## Anti-patterns
+
+- ✗ **`(feature-name)` group for one route** — premature. Put the route at top level until you have a second.
+- ✗ **Auth check in every page** instead of the `(app)/layout.tsx` — repetition + miss risk
+- ✗ **Mixing public + authed routes in the same group** — the layout can't enforce a uniform auth posture
+- ✗ **Group nesting**: `(app)/(admin)/...` — usually a smell. Flatten to `(admin)/` and put the auth check in its layout
+- ✗ **Renaming a group after launch** — the convention is propagated through skill references and CLAUDE.md modules; rename is cheap technically but expensive culturally
+
+## Workflow
+
+1. **List the routes you're adding.** 3 routes? They probably go in one group.
+2. **Identify the trust posture.** Public? Authed? Trust boundary? That picks the group.
+3. **Check existing groups.** Does one fit? If yes, use it. Don't create new groups for routes that fit.
+4. **Layout content:** what's truly shared between these routes? That's the layout. Everything else is page-specific.
+5. **If creating a new group**, write an ADR (`void-decide`). Group convention drift is annoying to undo.
+
+## Composition
+
+- `void-cache-component-pattern` — `(marketing)` is cache-by-default; `(app)` mostly `'use no cache'`.
+- `void-server-action` — `(actions)/` is where Server Actions live.
+- `void-decide` — adding/renaming groups is ADR-worthy.
+- `void-security-guidance` — `(app)/layout.tsx` is the auth boundary; redirects centralized here.

package/core-assets/packs/pack-nextjs/skills/void-route-group-decision/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-pwa/skills/void-install-prompt-ux/.source

@@ -0,0 +1,5 @@
+Sources for `void-install-prompt-ux` skill (see `docs/plans/skill-audits/void-install-prompt-ux.md` for the full audit):
+
+- No external source audited — native VoidCorp skill (beforeinstallprompt capture, engagement-signal threshold, dismiss cooldown, iOS fallback).
+
+Strategy: native. Original VoidCorp authoring, not derived from an external source.

package/core-assets/packs/pack-pwa/skills/void-install-prompt-ux/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: void-install-prompt-ux
+description: Surface the PWA install prompt at the right moment (engagement signal) with the right UI (custom button, not auto-prompt). Capture beforeinstallprompt, defer, recover declined.
+---
+
+# install-prompt-ux
+
+Use when adding "Install app" UX to a PWA, or when figuring out why the default browser prompt doesn't appear / appears at the wrong time. Default browser behavior is broken for most apps — too early, too generic, no recovery.
+
+This skill is the void-machine pattern: capture the event, defer it, surface a custom button at a meaningful moment.
+
+## The browser default is bad
+
+Without custom code, Chrome (etc.) decides when to show a small browser-styled "Add to Home Screen" toast. The decision is opaque (engagement heuristic), the UI is generic, and once dismissed it doesn't reappear soon. Users either miss it or click "Cancel" reflexively.
+
+Solution: hijack the prompt, defer it, show your own button.
+
+## The `beforeinstallprompt` flow
+
+```tsx
+// apps/web/src/components/InstallPrompt.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+
+interface BIPEvent extends Event {
+  prompt: () => Promise<void>;
+  userChoice: Promise<{ outcome: 'accepted' | 'dismissed' }>;
+}
+
+export function InstallPrompt() {
+  const [deferred, setDeferred] = useState<BIPEvent | null>(null);
+  const [isInstalled, setIsInstalled] = useState(false);
+
+  useEffect(() => {
+    // 1. Capture the event when the browser fires it
+    const onBIP = (e: Event) => {
+      e.preventDefault();                         // don't show browser default
+      setDeferred(e as BIPEvent);
+    };
+    window.addEventListener('beforeinstallprompt', onBIP);
+
+    // 2. Detect already-installed (PWA opened from home screen)
+    const onInstalled = () => {
+      setIsInstalled(true);
+      setDeferred(null);
+    };
+    window.addEventListener('appinstalled', onInstalled);
+
+    // 3. Sanity check: are we already in standalone mode?
+    if (window.matchMedia('(display-mode: standalone)').matches) {
+      setIsInstalled(true);
+    }
+
+    return () => {
+      window.removeEventListener('beforeinstallprompt', onBIP);
+      window.removeEventListener('appinstalled', onInstalled);
+    };
+  }, []);
+
+  if (isInstalled || !deferred) return null;
+
+  async function handleInstall() {
+    if (!deferred) return;
+    await deferred.prompt();                      // shows the browser native prompt NOW
+    const { outcome } = await deferred.userChoice;
+    setDeferred(null);                            // one shot per page load; can't re-prompt
+    if (outcome === 'accepted') {
+      // Tracked, navigated to standalone — onInstalled fires shortly
+    } else {
+      // User dismissed — store decision, don't pester
+      localStorage.setItem('install-dismissed-at', String(Date.now()));
+    }
+  }
+
+  return (
+    <button onClick={handleInstall}>Installer l'app</button>
+  );
+}
+```
+
+## When to show your custom button
+
+NOT immediately. Show only after an engagement signal — proof the user finds the app useful:
+
+| Signal | Threshold (default) |
+|---|---|
+| Sessions completed | ≥ 2 |
+| Time in-app this session | ≥ 30 seconds |
+| Key action completed | 1 (e.g., created their first contact in Solaar) |
+| Days since first visit | ≥ 1 |
+
+Combine: "shown after 2 sessions AND ≥ 30s AND not dismissed in the last 7 days". The combination kills the "saw an empty app, prompted to install, declined forever" failure.
+
+```tsx
+const ENGAGEMENT_THRESHOLD = { sessions: 2, secondsThisSession: 30 };
+
+function shouldShow(state) {
+  const dismissedAt = Number(localStorage.getItem('install-dismissed-at') ?? 0);
+  const daysSinceDismiss = (Date.now() - dismissedAt) / (24 * 60 * 60 * 1000);
+  if (dismissedAt && daysSinceDismiss < 7) return false;
+  return state.sessions >= ENGAGEMENT_THRESHOLD.sessions &&
+         state.secondsThisSession >= ENGAGEMENT_THRESHOLD.secondsThisSession;
+}
+```
+
+## Recovery: dismissed → can we re-prompt?
+
+Once `beforeinstallprompt` is dismissed, Chrome won't refire for at least 90 days (per their heuristic, not contractual). Strategies:
+
+- **Cooldown**: store `install-dismissed-at`, don't show button for 7-14 days. After cooldown, if `deferred` is again non-null (Chrome decided to re-fire), show.
+- **Fallback for unsupported browsers** (Safari iOS): provide instructions in a help page ("Tap Share → Add to Home Screen").
+
+iOS Safari doesn't fire `beforeinstallprompt` at all. The button can still be useful as a "How to install on iPhone" link.
+
+## Placement of the install button
+
+Three patterns; pick one based on app type:
+
+- **A. In the settings/profile menu**: discoverable for power users, low-friction. Default.
+- **B. As a dismissible banner**: more aggressive; for content-heavy apps where install is the conversion goal
+- **C. After a key action**: e.g., "Just created your first contact! Install the app to access it offline." Highest conversion when timed right.
+
+Avoid: modal pop-ups on first visit (worst conversion + user trust).
+
+## Anti-patterns
+
+- ✗ **Calling `deferred.prompt()` without user gesture** — browsers reject; the prompt won't fire
+- ✗ **Showing the install button before SW registers** — install prompt requires manifest + SW; show only after `serviceWorker.ready`
+- ✗ **No recovery for dismissed users** — silent forever
+- ✗ **Pestering on every page** — kills trust; one button in the settings menu is enough for most apps
+- ✗ **No handling for iOS** — Safari doesn't fire BIP; without a fallback "how to install" page, iOS users have no path
+
+## Anatomy of a great PWA install flow (Solaar archetype)
+
+1. New visitor → no install UX
+2. Visit 2, 30s in → small "Installer" button appears in settings menu (subtle)
+3. After creating first contact → contextual prompt: "Vos contacts dans la poche. Installer ?"
+4. User dismisses → 7-day cooldown
+5. After 7 days, if still using the app → re-prompt in the contextual spot, not in face
+
+## Verification
+
+DevTools → Application → Manifest → "Add to home screen" button (forces install in dev).
+Lighthouse → PWA category → "Installable" should be green; otherwise read the failure reasons (usually missing icon, missing start_url, etc.).
+
+## Composition
+
+- `void-manifest-checklist` — installability requires a valid manifest first
+- `void-service-worker-strategy` — installability requires SW registered
+- `void-accessibility-check` — install button is interactive; needs label, focus ring
+- `void-observability` — track install events (`window.addEventListener('appinstalled', ...)`) for conversion measurement
+- `void-frontend-design` — when to show, where to place — UX trade-offs covered here

package/core-assets/packs/pack-pwa/skills/void-install-prompt-ux/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-pwa/skills/void-manifest-checklist/.source

@@ -0,0 +1,5 @@
+Sources for `void-manifest-checklist` skill (see `docs/plans/skill-audits/void-manifest-checklist.md` for the full audit):
+
+- No external source audited — native VoidCorp skill (field-by-field manifest checklist with the WHY for each, anti-pattern list, optional-fields-worth-adding section).
+
+Strategy: native. Original VoidCorp authoring, not derived from an external source.

package/core-assets/packs/pack-pwa/skills/void-manifest-checklist/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: void-manifest-checklist
+description: "Get manifest.webmanifest right the first time — required fields, icon sizes (192, 512, maskable), display modes, scope, start_url. Single artifact: every field motivated, no dead options."
+---
+
+# manifest-checklist
+
+Use when creating or updating the web app manifest. The manifest is the document that tells browsers "this is a PWA, install it like an app". A wrong manifest is the difference between "no install prompt ever" and "installable on all platforms".
+
+If you have no manifest yet, this skill is the green-field checklist. If you have one and "install" doesn't work somewhere, this skill is the debug.
+
+## File location and reference
+
+```
+apps/<app>/public/manifest.webmanifest     # the file
+apps/<app>/app/layout.tsx                  # references via <link>
+```
+
+Reference in `<head>`:
+
+```tsx
+// app/layout.tsx
+export const metadata = {
+  manifest: '/manifest.webmanifest',
+};
+```
+
+Or for Next 16's typed metadata.ts:
+
+```ts
+// app/manifest.ts
+import type { MetadataRoute } from 'next';
+
+export default function manifest(): MetadataRoute.Manifest {
+  return { /* ... */ };
+}
+```
+
+Use the TS file if your stack supports it — typo-safe.
+
+## Required fields
+
+```json
+{
+  "name": "Solaar",
+  "short_name": "Solaar",
+  "description": "Relationship intelligence companion.",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "background_color": "#0a0a0a",
+  "theme_color": "#0a0a0a",
+  "lang": "fr",
+  "dir": "ltr",
+  "icons": [
+    {
+      "src": "/icons/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icons/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/icons/icon-maskable-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/icons/icon-maskable-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ]
+}
+```
+
+Every field above has a reason. Skipping ANY breaks installability on some platform.
+
+## Field-by-field
+
+### `name` and `short_name`
+
+- `name`: full name shown in the install prompt and OS app list
+- `short_name`: home screen label (truncated platforms). ≤ 12 chars ideal
+
+Distinct values when the full name is long: `name: "Solaar by VoidCorp"`, `short_name: "Solaar"`.
+
+### `start_url` and `scope`
+
+- `start_url`: where the app opens on launch from home screen. Almost always `/`.
+- `scope`: paths that "belong to" the app. Outside scope, the OS opens browser instead of in-app. Almost always `/`.
+
+If you scope to `/app/` and the user visits `/marketing/`, they'll bounce out to browser. Usually undesired.
+
+### `display`
+
+| Value | Effect |
+|---|---|
+| `standalone` | Full-screen app, no browser UI. **Default for PWAs.** |
+| `fullscreen` | Even hides the status bar (for games) |
+| `minimal-ui` | Some browser controls visible |
+| `browser` | Normal browser tab (no PWA-ness) |
+
+Use `standalone`. The others are niche.
+
+### `theme_color` and `background_color`
+
+- `theme_color`: status bar / title bar color in standalone mode
+- `background_color`: splash screen color before the app's CSS loads
+
+Set both to your app's primary background. Mismatch causes a flash on launch.
+
+### `lang` and `dir`
+
+- `lang`: primary language ISO code (`fr`, `en`, `pt-BR`)
+- `dir`: `ltr` or `rtl`
+
+Don't omit. AT and OS use them for accessibility hints.
+
+### `icons`
+
+The minimum: **4 icons** — 192 and 512 in both `any` and `maskable` purposes.
+
+- `any` purpose: standard square icons (used on browsers, older Android)
+- `maskable`: safe-zone respected (used by Android adaptive icons, where the OS clips to circle/squircle/etc.). MUST have 20% padding around the actual logo
+
+Larger sizes (1024) are nice but not required. iOS uses its own `apple-touch-icon.png` (set separately in `<head>`).
+
+Generate from one SVG via:
+
+```bash
+npx pwa-asset-generator logo.svg public/icons/ --maskable-only false --padding "20%"
+```
+
+## Optional fields worth adding
+
+```json
+{
+  "categories": ["productivity", "business"],
+  "screenshots": [
+    {
+      "src": "/screenshots/home-narrow.png",
+      "sizes": "390x844",
+      "form_factor": "narrow",
+      "label": "Accueil sur mobile"
+    },
+    {
+      "src": "/screenshots/home-wide.png",
+      "sizes": "1280x720",
+      "form_factor": "wide",
+      "label": "Accueil sur desktop"
+    }
+  ],
+  "shortcuts": [
+    {
+      "name": "Nouveau contact",
+      "url": "/contacts/new",
+      "icons": [{ "src": "/icons/new-contact.png", "sizes": "96x96" }]
+    }
+  ],
+  "share_target": {
+    "action": "/share",
+    "method": "POST",
+    "enctype": "multipart/form-data",
+    "params": { "title": "title", "text": "text", "url": "url" }
+  }
+}
+```
+
+- `categories`: helps Play Store / OS app categorization
+- `screenshots`: shown in install prompt on Android (Chrome). **Set form_factor** so each is shown on the right platform
+- `shortcuts`: appear on long-press of the app icon (Android)
+- `share_target`: receive shared content from other apps
+
+## Anti-patterns
+
+- ✗ **Same icon for `any` and `maskable`** — maskable needs 20% padding; non-padded icon gets clipped on Android
+- ✗ **Both `manifest.webmanifest` and `manifest.json`** — confuse browsers; pick `.webmanifest` (correct mime type)
+- ✗ **`start_url: "/?source=pwa"`** with tracking query — breaks back-navigation, surprises the user
+- ✗ **`scope: "."`** — relative scope is fragile; use `/`
+- ✗ **Missing maskable icon** — Android adaptive icons render with broken padding
+- ✗ **Theme color set on `<meta>` but missing in manifest** — inconsistent splash screen
+
+## Verification
+
+Browser DevTools → Application → Manifest:
+
+- Shows parsed manifest with warnings
+- "Installability" badge red? Read the reasons listed
+- Use Chrome DevTools Lighthouse → PWA category for a comprehensive audit (target 100)
+
+## Composition
+
+- `void-install-prompt-ux` — installability depends on manifest being valid
+- `void-service-worker-strategy` — SW + manifest are the two PWA artifacts; both required for install prompt
+- `void-accessibility-check` — `lang` + `dir` are a11y signals
+- `void-frontend-design` — theme_color and icon design should match the brand

package/core-assets/packs/pack-pwa/skills/void-manifest-checklist/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]