@schandlergarcia/sf-web-components 1.0.0

package/.a4drules/skills/building-react-components/implementation/page.md

@@ -0,0 +1,93 @@
+# Implementation — Page
+
+### Rules
+
+1. **Edit the component that owns the UI, never output raw HTML** — When editing the home page or any page content, modify the actual `.tsx` file that renders the target. If the target is inside a child component (e.g. `<GlobalSearchInput />` in `Home.tsx`), edit the child's file (e.g. `GlobalSearchInput.tsx`), not the parent. Do not wrap the component with extra elements in the parent; go into the component and change its JSX. Do not paste or generate raw HTML.
+2. **`routes.tsx` is the only route registry** — never add routes in `app.tsx` or inside page files.
+3. **All pages are children of the AppLayout route** — do not create top-level routes that bypass the layout shell.
+4. **Default export per page** — each page file has exactly one default-export component.
+5. **Path aliases in all imports** — use `@/pages/...`, `@/components/...`; no deep relative paths.
+6. **No inline styles** — Tailwind utility classes and design tokens only.
+7. **Catch-all last** — `path: '*'` (NotFound) must always remain the last child in the layout route.
+8. **Never modify `appLayout.tsx`** when adding a page — layout changes are a separate concern.
+
+### Step 1 — Create the page file
+
+Create `src/pages/MyPage.tsx` with a **default export** and the standard page container:
+
+```tsx
+export default function MyPage() {
+  return (
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+      <h1 className="text-3xl font-bold text-foreground">My Page</h1>
+      <p className="mt-4 text-muted-foreground">Page content goes here.</p>
+    </div>
+  );
+}
+```
+
+Use shadcn components from `@/components/ui` for UI elements. All styling via Tailwind — no inline `style={{}}`.
+
+### Step 2 — Register the route in `routes.tsx`
+
+Open `src/routes.tsx`. Import the page and add it inside the layout route's `children` array:
+
+```tsx
+import MyPage from "@/pages/MyPage";
+
+// Inside the layout route's children array (before the catch-all):
+{
+  path: "my-page",
+  element: <MyPage />,
+  handle: { showInNavigation: true, label: "My Page" },
+},
+```
+
+- `path` is a **relative segment** (e.g., `"contacts"`), not an absolute path.
+- Include `handle: { showInNavigation: true, label: "Label" }` only if the page should appear in the navigation menu.
+- The catch-all `path: '*'` must stay **last**.
+
+### Step 3 — Apply an auth guard (if needed)
+
+| Access type                        | Guard                   | Behavior                                |
+| ---------------------------------- | ----------------------- | --------------------------------------- |
+| Public                             | None                    | Direct child of layout                  |
+| Authenticated only                 | `<PrivateRoute>`        | Redirects to login if not authenticated |
+| Unauthenticated only (e.g., login) | `<AuthenticationRoute>` | Redirects away if already authenticated |
+
+Example — private page:
+
+```tsx
+import { PrivateRoute } from "@/components/auth/private-route";
+
+{
+  path: "settings",
+  element: <PrivateRoute><SettingsPage /></PrivateRoute>,
+  handle: { showInNavigation: true, label: "Settings" },
+},
+```
+
+Use `ROUTES.*` constants from `@/utils/authenticationConfig` for auth-related paths — do not hardcode `/login`, `/profile`, etc.
+
+### File Conventions — Page
+
+| Concern           | Location                                               |
+| ----------------- | ------------------------------------------------------ |
+| Page component    | `src/pages/<PageName>.tsx` (default export)            |
+| Route definition  | `src/routes.tsx` only                                  |
+| Layout shell      | `src/appLayout.tsx` — do not modify for page additions |
+| Auth config paths | `ROUTES.*` from `@/utils/authenticationConfig`         |
+
+### State and Data
+
+- **Local state:** `useState`, `useReducer`, `useRef` inside the page component
+- **Shared or complex state:** extract to `src/hooks/` with a `use` prefix (e.g., `useContacts`)
+- **Data fetching:** prefer GraphQL (`executeGraphQL`) or REST utilities in `src/api/`; place shared data logic in `src/hooks/`
+- **Auth context:** `useAuth()` from `@/context/AuthContext` when current user is needed — only valid under `AuthProvider`
+
+### Confirm — Page
+
+- The page renders inside the app shell (header/nav visible)
+- If `showInNavigation: true`, the link appears in the navigation menu
+- No TypeScript errors; no broken imports; no missing exports
+- Imports use path aliases (`@/`, not deep relative paths)

package/.a4drules/skills/configuring-csp-trusted-sites/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: configuring-csp-trusted-sites
+description: Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error.
+---
+
+# CSP Trusted Sites
+
+## When to Use
+
+Use this skill whenever the application references a new external domain that is not already registered as a CSP Trusted Site. This includes:
+
+- Adding images from a new CDN (Unsplash, Pexels, Cloudinary, etc.)
+- Loading fonts from an external provider (Google Fonts, Adobe Fonts)
+- Calling a third-party API (Open-Meteo, Nominatim, Mapbox, etc.)
+- Loading map tiles from a tile server (OpenStreetMap, Mapbox)
+- Embedding iframes from external services (YouTube, Vimeo)
+- Loading external stylesheets or scripts
+
+Salesforce enforces Content Security Policy (CSP) headers on all web applications. Any external domain not registered as a CSP Trusted Site will be blocked by the browser, causing images to not load, API calls to fail, or fonts to be missing.
+
+**Reference:** [Salesforce CspTrustedSite Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
+
+---
+
+## Step 1 — Identify external domains
+
+Scan the code for any URLs pointing to external domains. Common patterns:
+
+- `fetch("https://api.example.com/...")` — API calls
+- `<img src="https://images.example.com/..." />` — images
+- `<link href="https://fonts.example.com/..." />` — stylesheets
+- `url="https://tiles.example.com/{z}/{x}/{y}.png"` — map tiles
+- `@import url("https://cdn.example.com/...")` — CSS imports
+
+Extract the **origin** (scheme + host) from each URL. For example:
+- `https://api.open-meteo.com/v1/forecast?lat=...` → `https://api.open-meteo.com`
+- `https://images.unsplash.com/photo-123?w=800` → `https://images.unsplash.com`
+
+---
+
+## Step 2 — Check existing CSP Trusted Sites
+
+Before creating a new file, check if the domain already has a CSP Trusted Site:
+
+```bash
+ls force-app/main/default/cspTrustedSites/
+```
+
+If the domain is already registered, no action is needed.
+
+---
+
+## Step 3 — Determine the CSP directive(s)
+
+Map the resource type to the correct CSP `isApplicableTo*Src` fields. Read `implementation/metadata-format.md` for the full reference.
+
+Quick reference:
+
+| Resource type | CSP directive field(s) to set `true` |
+|--------------|--------------------------------------|
+| Images (img, background-image) | `isApplicableToImgSrc` |
+| API calls (fetch, XMLHttpRequest) | `isApplicableToConnectSrc` |
+| Fonts (.woff, .woff2, .ttf) | `isApplicableToFontSrc` |
+| Stylesheets (CSS) | `isApplicableToStyleSrc` |
+| Video / audio | `isApplicableToMediaSrc` |
+| Iframes | `isApplicableToFrameSrc` |
+
+**Always also set `isApplicableToConnectSrc` to `true`** — most resources also require connect-src for preflight/redirect handling.
+
+---
+
+## Step 4 — Create the metadata file
+
+Read `implementation/metadata-format.md` and follow the instructions to create the `.cspTrustedSite-meta.xml` file.
+
+---
+
+## Step 5 — Verify
+
+1. Confirm the file is valid XML and matches the expected schema.
+2. Confirm the file is placed in `force-app/main/default/cspTrustedSites/`.
+3. Confirm only the necessary `isApplicableTo*Src` fields are set to `true`.
+4. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

package/.a4drules/skills/configuring-csp-trusted-sites/implementation/metadata-format.md

@@ -0,0 +1,281 @@
+# CSP Trusted Site Metadata — Implementation Guide
+
+## File location
+
+```
+force-app/main/default/cspTrustedSites/{Name}.cspTrustedSite-meta.xml
+```
+
+The `cspTrustedSites/` directory must be a direct child of `force-app/main/default/`. Create it if it does not exist.
+
+---
+
+## File naming convention
+
+The file name must match the `<fullName>` value inside the XML, with `.cspTrustedSite-meta.xml` appended.
+
+| Domain | fullName | File name |
+|--------|----------|-----------|
+| `https://images.unsplash.com` | `Unsplash_Images` | `Unsplash_Images.cspTrustedSite-meta.xml` |
+| `https://api.open-meteo.com` | `Open_Meteo_API` | `Open_Meteo_API.cspTrustedSite-meta.xml` |
+| `https://tile.openstreetmap.org` | `OpenStreetMap_Tiles` | `OpenStreetMap_Tiles.cspTrustedSite-meta.xml` |
+
+**Naming rules:**
+- Use PascalCase with underscores separating words (e.g. `Google_Fonts_Static`)
+- Name should describe the provider and resource type (e.g. `Pexels_Videos`, not just `Pexels`)
+- Must be unique across the org
+- Maximum 80 characters
+
+---
+
+## XML template
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>{UNIQUE_NAME}</fullName>
+    <description>{DESCRIPTION}</description>
+    <endpointUrl>{HTTPS_ORIGIN}</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>{true|false}</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>{true|false}</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>{true|false}</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>{true|false}</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>{true|false}</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>{true|false}</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+---
+
+## Field reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `fullName` | Yes | Unique API name. Must match the file name (before `.cspTrustedSite-meta.xml`). |
+| `description` | Yes | Human-readable purpose. Start with "Allow access to..." |
+| `endpointUrl` | Yes | The external origin (scheme + host). Must start with `https://`. No trailing slash. No path. |
+| `isActive` | Yes | Always `true` for new entries. Set `false` to disable without deleting. |
+| `context` | Yes | `All` (applies to all contexts). Other values: `LEX` (Lightning Experience only), `Communities` (Experience Cloud only), `VisualForce`. Use `All` unless there is a specific reason to restrict. |
+| `isApplicableToConnectSrc` | Yes | `true` if the domain is called via `fetch()`, `XMLHttpRequest`, or WebSocket. |
+| `isApplicableToFontSrc` | Yes | `true` if the domain serves font files (`.woff`, `.woff2`, `.ttf`, `.otf`). |
+| `isApplicableToFrameSrc` | Yes | `true` if the domain is loaded in an `<iframe>` or `<object>`. |
+| `isApplicableToImgSrc` | Yes | `true` if the domain serves images (`<img>`, CSS `background-image`, `<svg>`). |
+| `isApplicableToMediaSrc` | Yes | `true` if the domain serves audio or video (`<audio>`, `<video>`). |
+| `isApplicableToStyleSrc` | Yes | `true` if the domain serves CSS stylesheets (`<link rel="stylesheet">`). |
+
+**Reference:** [CspTrustedSite — Salesforce Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
+
+---
+
+## CSP directive mapping
+
+| CSP header directive | Metadata field | What it allows |
+|---------------------|----------------|----------------|
+| `connect-src` | `isApplicableToConnectSrc` | `fetch()`, `XMLHttpRequest`, WebSocket, `EventSource` |
+| `font-src` | `isApplicableToFontSrc` | `@font-face` sources |
+| `frame-src` | `isApplicableToFrameSrc` | `<iframe>`, `<frame>`, `<object>`, `<embed>` |
+| `img-src` | `isApplicableToImgSrc` | `<img>`, `background-image`, `favicon`, `<picture>` |
+| `media-src` | `isApplicableToMediaSrc` | `<audio>`, `<video>`, `<source>`, `<track>` |
+| `style-src` | `isApplicableToStyleSrc` | `<link rel="stylesheet">`, `@import` in CSS |
+
+---
+
+## Common external domains and their directives
+
+Use this table as a quick reference when adding new domains:
+
+| Domain | connect-src | font-src | frame-src | img-src | media-src | style-src |
+|--------|:-----------:|:--------:|:---------:|:-------:|:---------:|:---------:|
+| `https://images.unsplash.com` | true | false | false | true | false | false |
+| `https://images.pexels.com` | true | false | false | true | false | false |
+| `https://videos.pexels.com` | true | false | false | false | true | false |
+| `https://fonts.googleapis.com` | true | false | false | false | false | true |
+| `https://fonts.gstatic.com` | true | true | false | false | false | false |
+| `https://avatars.githubusercontent.com` | true | false | false | true | false | false |
+| `https://api.open-meteo.com` | true | false | false | false | false | false |
+| `https://nominatim.openstreetmap.org` | true | false | false | false | false | false |
+| `https://tile.openstreetmap.org` | true | false | false | true | false | false |
+| `https://api.mapbox.com` | true | false | false | true | false | false |
+| `https://cdn.jsdelivr.net` | true | false | false | false | false | true |
+| `https://www.youtube.com` | false | false | true | true | false | false |
+| `https://player.vimeo.com` | false | false | true | false | false | false |
+| `https://res.cloudinary.com` | true | false | false | true | false | false |
+
+---
+
+## Complete examples
+
+### Image CDN (Unsplash)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Unsplash_Images</fullName>
+    <description>Allow access to Unsplash image content for static app media</description>
+    <endpointUrl>https://images.unsplash.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>true</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### REST API (Open-Meteo weather)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Open_Meteo_API</fullName>
+    <description>Allow access to Open-Meteo weather forecast API</description>
+    <endpointUrl>https://api.open-meteo.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Font provider (Google Fonts — requires two entries)
+
+Google Fonts needs two CSP entries because CSS is served from `fonts.googleapis.com` and font files from `fonts.gstatic.com`:
+
+**Entry 1: Stylesheets**
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Google_Fonts</fullName>
+    <description>Allow access to Google Fonts stylesheets for custom typography</description>
+    <endpointUrl>https://fonts.googleapis.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>true</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+**Entry 2: Font files**
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Google_Fonts_Static</fullName>
+    <description>Allow access to Google Fonts static files for font loading</description>
+    <endpointUrl>https://fonts.gstatic.com</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>true</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Map tiles (OpenStreetMap)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>OpenStreetMap_Tiles</fullName>
+    <description>Allow access to OpenStreetMap tile images for map rendering</description>
+    <endpointUrl>https://tile.openstreetmap.org</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>true</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+### Geocoding API (Nominatim)
+
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<CspTrustedSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>OpenStreetMap_Nominatim</fullName>
+    <description>Allow access to OpenStreetMap Nominatim geocoding API</description>
+    <endpointUrl>https://nominatim.openstreetmap.org</endpointUrl>
+    <isActive>true</isActive>
+    <context>All</context>
+    <isApplicableToConnectSrc>true</isApplicableToConnectSrc>
+    <isApplicableToFontSrc>false</isApplicableToFontSrc>
+    <isApplicableToFrameSrc>false</isApplicableToFrameSrc>
+    <isApplicableToImgSrc>false</isApplicableToImgSrc>
+    <isApplicableToMediaSrc>false</isApplicableToMediaSrc>
+    <isApplicableToStyleSrc>false</isApplicableToStyleSrc>
+</CspTrustedSite>
+```
+
+---
+
+## Endpoint URL rules
+
+| Rule | Correct | Incorrect |
+|------|---------|-----------|
+| Must be HTTPS | `https://api.example.com` | `http://api.example.com` |
+| No trailing slash | `https://api.example.com` | `https://api.example.com/` |
+| No path | `https://api.example.com` | `https://api.example.com/v1/forecast` |
+| No port (unless non-standard) | `https://api.example.com` | `https://api.example.com:443` |
+| No wildcards | `https://api.example.com` | `https://*.example.com` |
+
+Each subdomain needs its own entry. For example, `fonts.googleapis.com` and `fonts.gstatic.com` are separate entries.
+
+---
+
+## When a service requires multiple domains
+
+Some services split resources across multiple subdomains. Create one CSP Trusted Site per domain:
+
+| Service | Domains needed |
+|---------|---------------|
+| Google Fonts | `fonts.googleapis.com` (CSS) + `fonts.gstatic.com` (font files) |
+| Mapbox | `api.mapbox.com` (tiles/API) + `events.mapbox.com` (telemetry) |
+| YouTube embed | `www.youtube.com` (iframe) + `i.ytimg.com` (thumbnails) |
+| Cloudflare CDN | `cdnjs.cloudflare.com` (scripts/CSS) |
+
+---
+
+## Troubleshooting CSP violations
+
+If the browser console shows a CSP error like:
+
+```
+Refused to load the image 'https://example.com/image.png' because it violates
+the following Content Security Policy directive: "img-src 'self' ..."
+```
+
+1. Extract the **blocked origin** from the URL (e.g. `https://example.com`).
+2. Identify the **directive** from the error message (e.g. `img-src` → `isApplicableToImgSrc`).
+3. Check if a CSP Trusted Site already exists for that origin.
+4. If not, create one using this skill.
+5. Deploy the metadata and refresh the page.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Including a path in `endpointUrl` | Use only the origin: `https://api.example.com` |
+| Adding trailing slash | Remove it: `https://api.example.com` not `https://api.example.com/` |
+| Using HTTP instead of HTTPS | Salesforce requires HTTPS. If the service only supports HTTP, it cannot be added. |
+| Forgetting `isApplicableToConnectSrc` | Most resources also need connect-src for redirects/preflight. Set to `true` by default. |
+| One entry for multiple subdomains | Each subdomain needs its own file (e.g. `api.example.com` and `cdn.example.com` are separate) |
+| File name doesn't match `fullName` | They must be identical (excluding the `.cspTrustedSite-meta.xml` extension) |

package/.a4drules/skills/configuring-webapp-metadata/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: configuring-webapp-metadata
+description: Use this skill when configuring web application metadata structure, webapplication.json, or bundle organization. Covers WebApplication bundle layout, meta XML, build output directory, and webapplication.json settings.
+---
+
+# WebApplication Requirements
+
+## Bundle Rules
+- A WebApplication bundle must live under `webapplications/<AppName>/`
+- The bundle must contain `<AppName>.webapplication-meta.xml`
+- The metadata filename must exactly match the folder name
+- A build output directory must exist and contain at least one file
+- Default build output directory: `dist/`
+- If `webapplication.json.outputDir` is set, it overrides `dist/`
+
+Valid example:
+```text
+webapplications/
+  MyApp/
+    MyApp.webapplication-meta.xml
+    webapplication.json
+    dist/
+      index.html
+```
+
+## Metadata XML
+Required fields:
+- `masterLabel`
+- `version` (max 20 chars)
+- `isActive` (boolean)
+
+Optional fields:
+- `description` (max 255 chars)
+
+## webapplication.json
+`webapplication.json` is optional.
+
+Allowed top-level keys only:
+- `outputDir`
+- `routing`
+- `headers`
+
+### File Constraints
+- Must be valid UTF-8 JSON
+- Max size: 100 KB
+- Root must be a non-empty object
+- Never allow `{}`, arrays, or primitives as the root
+
+### Path Safety
+Applies to:
+- `outputDir`
+- `routing.fallback`
+
+Reject:
+- backslashes
+- leading `/` or `\`
+- `..` segments
+- null or control characters
+- globs: `*`, `?`, `**`
+- `%`
+
+All resolved paths must stay within the application bundle.
+
+### outputDir
+- Must be a non-empty string
+- Must reference a subdirectory only
+- Reject `.` and `./`
+- The directory must exist in the bundle
+- The directory must contain at least one file
+
+### routing
+- If present, must be a non-empty object
+- Allowed keys only:
+  - `rewrites`
+  - `redirects`
+  - `fallback`
+  - `trailingSlash`
+  - `fileBasedRouting`
+
+#### routing.trailingSlash
+- Must be one of: `"always"`, `"never"`, `"auto"`
+
+#### routing.fileBasedRouting
+- Must be a boolean
+
+#### routing.fallback
+- Must be a non-empty string
+- Must satisfy Path Safety rules
+- Target file must exist
+
+#### routing.rewrites
+- Must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `route`, `rewrite`
+- `rewrite` must be a non-empty string
+- `route`, if present, must be a non-empty string
+
+Example:
+```json
+{
+  "routing": {
+    "rewrites": [
+      { "route": "/app/:path*", "rewrite": "/index.html" }
+    ]
+  }
+}
+```
+
+#### routing.redirects
+- Must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `route`, `redirect`, `statusCode`
+- `redirect` must be a non-empty string
+- `route`, if present, must be a non-empty string
+- `statusCode`, if present, must be one of: `301`, `302`, `307`, `308`
+
+Example:
+```json
+{
+  "routing": {
+    "redirects": [
+      { "route": "/old-page", "redirect": "/new-page", "statusCode": 301 }
+    ]
+  }
+}
+```
+
+### headers
+- If present, must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `source`, `headers`
+- `headers` must be a non-empty array
+
+Each header entry must contain:
+- `key`: non-empty string
+- `value`: non-empty string
+
+Example:
+```json
+{
+  "headers": [
+    {
+      "source": "/assets/**",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
+      ]
+    }
+  ]
+}
+```
+
+## Never Suggest
+- `{}` as the JSON root
+- `"routing": {}`
+- empty arrays
+- empty array items such as `[{}]`
+- `"outputDir": "."`
+- `"outputDir": "./"`