chore: sync develop to main — PostHog migration verification

.env.example

@@ -7,5 +7,10 @@ VITE_SUPABASE_ANON_KEY=your-anon-key
 # Google Identity Services — Web OAuth client ID (public)
 VITE_GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
 
+# PostHog analytics (optional — skip in local dev)
+VITE_POSTHOG_API_HOST=https://us.i.posthog.com
+VITE_POSTHOG_API_KEY=phc_your_project_token
+# For production with reverse proxy: VITE_POSTHOG_API_HOST=https://e.bayanflow.com
+
 # Optional: Pyodide CDN override (see src/constants/pyodideCdn.js)
 # VITE_PYODIDE_CDN_BASE=

.github/workflows/ci.yml

@@ -127,6 +127,8 @@ jobs:
         env:
           VITE_GIT_BRANCH: ${{ github.ref_name }}
           VITE_DEV_SITE_URL: 'https://dev.bayanflow.com'
+          VITE_POSTHOG_API_KEY: ${{ secrets.VITE_POSTHOG_API_KEY }}
+          VITE_POSTHOG_API_HOST: 'https://us.i.posthog.com'
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v5

.github/workflows/deploy-cloudflare.yml

@@ -51,6 +51,8 @@ jobs:
           VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
           VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
           VITE_GOOGLE_WEB_CLIENT_ID: ${{ secrets.VITE_GOOGLE_WEB_CLIENT_ID }}
+          VITE_POSTHOG_API_KEY: ${{ secrets.VITE_POSTHOG_API_KEY }}
+          VITE_POSTHOG_API_HOST: ${{ github.event.workflow_run.head_branch == 'main' && 'https://e.bayanflow.com' || 'https://e.dev.bayanflow.com' }}
 
       - name: Deploy to Cloudflare Workers
         uses: cloudflare/wrangler-action@9acf94ace14e7dc412b076f2c5c20b8ce93c79cd # v3

.github/workflows/preview-cloudflare.yml

@@ -58,6 +58,8 @@ jobs:
           VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
           VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
           VITE_GOOGLE_WEB_CLIENT_ID: ${{ secrets.VITE_GOOGLE_WEB_CLIENT_ID }}
+          VITE_POSTHOG_API_KEY: ${{ secrets.VITE_POSTHOG_API_KEY }}
+          VITE_POSTHOG_API_HOST: https://e.dev.bayanflow.com
 
       - name: Upload preview version
         id: deploy

SECURITY.md

@@ -69,7 +69,7 @@ Bayan Flow implements several security measures:
 
 - **Client-side only**: No server-side data processing or storage for algorithm execution
 - **Local algorithm execution**: Sorting, searching, pathfinding, and graph visualizations run entirely in the browser
-- **Limited third-party calls**: Umami analytics (privacy-oriented), GitHub public API (release/repo metadata), and jsDelivr (Pyodide, only when the user opens the Python panel)
+- **Limited third-party calls**: PostHog analytics (privacy-oriented, via first-party proxy), GitHub public API (release/repo metadata), and jsDelivr (Pyodide, only when the user opens the Python panel)
 - **HTTP security headers** (via Cloudflare Workers static assets `public/_headers`): Strict-Transport-Security, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy
 - **Content Security Policy**: Restricts script, connect, frame, and worker sources to approved origins
 - **Automated scanning**:

docs/AGENTS_REFERENCE.md

@@ -615,3 +615,31 @@ Use focused tests first for registry/category changes, then broaden to the full
 - If a shared helper is required, add it in the earliest commit that needs it.
 - Prefer existing hooks, registries, helpers, and component patterns over one-off branches.
 - Keep deterministic generators deterministic in tests by accepting/passing an `rng` where existing utilities do.
+
+## Agent-Readiness Endpoints
+
+### Static files (served from `public/`)
+
+| File | Content-Type | Purpose |
+|------|-------------|---------|
+| `/.well-known/api-catalog` | `application/linkset+json` | RFC 9727 API catalog with `linkset` array |
+| `/.well-known/mcp/server-card.json` | `application/json` | MCP Server Card (SEP-1649) with `serverInfo`, endpoint, capabilities |
+| `/.well-known/oauth-authorization-server` | `application/json` | OAuth discovery (Supabase issuer) with `agent_auth` block |
+| `/.well-known/oauth-protected-resource` | `application/json` | RFC 9728 Protected Resource Metadata |
+| `/.well-known/agent-card.json` | `application/json` | Agent card with capabilities and features |
+| `/.well-known/agent-skills/index.json` | `application/json` | Agent skills catalog |
+| `/auth.md` | `text/markdown` | Agent registration / authentication guide |
+| `/llms.txt` | `text/plain` | Machine-readable site description for AI agents |
+
+### Link headers (in `public/_headers`)
+
+The `/*` section includes `Link` headers pointing to:
+- `</.well-known/api-catalog>; rel="api-catalog"`
+- `</.well-known/oauth-protected-resource>; rel="oauth-protected-resource"`
+- `</.well-known/mcp/server-card.json>; rel="mcp-server-card"`
+- `</auth.md>; rel="auth-md"`
+- `</llms.txt>; rel="llms-txt"`
+
+### CORS
+
+All `/.well-known/*` paths include `Access-Control-Allow-Origin: *` for cross-origin agent discovery.

index.html

@@ -38,34 +38,6 @@
       })();
     </script>
 
-    <!-- Umami Analytics - Dynamically loaded based on environment -->
-    <script>
-      (function () {
-        const hostname = window.location.hostname;
-        let websiteId;
-        if (
-          hostname === 'dev.bayanflow.com' ||
-          hostname.slice(-12) === '.workers.dev'
-        ) {
-          // Develop
-          websiteId = 'b21ffc5d-66c1-4bfc-9e54-e05dbbe26852';
-        } else if (
-          hostname === 'bayanflow.com' ||
-          hostname === 'www.bayanflow.com'
-        ) {
-          // main
-          websiteId = 'c096589e-f026-47e9-b458-aeb6850d5d5c';
-        }
-        if (websiteId) {
-          const script = document.createElement('script');
-          script.defer = true;
-          script.src = 'https://cloud.umami.is/script.js';
-          script.setAttribute('data-website-id', websiteId);
-          document.head.appendChild(script);
-        }
-      })();
-    </script>
-
     <!-- Open Graph / Facebook -->
     <meta property="og:type" content="website" />
     <meta property="og:url" content="https://bayanflow.com/" />

package.json

@@ -59,6 +59,7 @@
     "@monaco-editor/react": "^4.7.0",
     "@octokit/rest": "^22.0.1",
     "@phosphor-icons/react": "^2.1.10",
+    "@posthog/react": "^1.10.3",
     "@remotion/media": "4.0.436",
     "@remotion/web-renderer": "^4.0.436",
     "@supabase/supabase-js": "^2.108.2",
@@ -69,6 +70,7 @@
     "i18next": "^25.7.1",
     "i18next-browser-languagedetector": "^8.2.0",
     "isomorphic-dompurify": "^3.18.0",
+    "posthog-js": "^1.404.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-i18next": "^15.7.4",

public/.well-known/agent-card.json

@@ -3,8 +3,22 @@
   "name": "Bayan Flow",
   "description": "Interactive educational tool for learning algorithms through step-by-step visual animations with clarity (بيان). Features sorting, pathfinding, searching, tree traversal, and graph algorithms with Python code examples and real-time complexity analysis.",
   "url": "https://bayanflow.com",
+  "version": "0.5.0",
   "capabilities": ["visualization", "education", "code-execution", "video-export"],
   "category": "education",
+  "skills": [
+    {
+      "name": "algorithm-visualization",
+      "description": "Browse and explore interactive algorithm visualizations across sorting, pathfinding, searching, tree traversal, and graph categories.",
+      "url": "https://bayanflow.com/app"
+    },
+    {
+      "name": "complexity-analysis",
+      "description": "View time and space complexity information for any algorithm.",
+      "url": "https://bayanflow.com/app"
+    }
+  ],
+  "supportedInterfaces": ["web", "mcp"],
   "features": [
     "45 interactive algorithm visualizations",
     "Real-time complexity analysis",

public/.well-known/api-catalog

@@ -1,5 +1,45 @@
 {
-  "schemaVersion": 1,
-  "description": "Bayan Flow is a fully client-side single-page application. No public REST APIs are available. All algorithm execution, visualization rendering, and code interpretation happens in the user's browser via React and Pyodide (WebAssembly Python runtime).",
-  "endpoints": []
+  "linkset": [
+    {
+      "anchor": "https://bayanflow.com",
+      "service-desc": [
+        {
+          "href": "https://bayanflow.com/.well-known/agent-card.json",
+          "title": "Bayan Flow Agent Card",
+          "type": "application/json"
+        }
+      ],
+      "service-doc": [
+        {
+          "href": "https://bayanflow.com/auth.md",
+          "title": "Bayan Flow Agent Authentication Guide",
+          "type": "text/markdown"
+        }
+      ],
+      "describedby": [
+        {
+          "href": "https://bayanflow.com/llms.txt",
+          "title": "Bayan Flow — Machine-Readable Description",
+          "type": "text/plain"
+        }
+      ]
+    },
+    {
+      "anchor": "https://bayanflow.com/app",
+      "service-desc": [
+        {
+          "href": "https://bayanflow.com/.well-known/mcp/server-card.json",
+          "title": "Bayan Flow MCP Server Card",
+          "type": "application/json"
+        }
+      ],
+      "service-doc": [
+        {
+          "href": "https://bayanflow.com/.well-known/agent-skills/index.json",
+          "title": "Bayan Flow Agent Skills",
+          "type": "application/json"
+        }
+      ]
+    }
+  ]
 }