feat(ui-website): env-driven sibling URLs with localhost dev fallbacks (#42)

The UI website hardcoded `https://webjs.dev` and `https://docs.webjs.dev`
as the defaults for its header + footer links. Local dev navigated off
the localhost dev cluster as soon as you clicked the Webjs / Docs links,
which broke the flow when working across all three apps simultaneously.

Mirror the pattern the root website (`website/app/layout.ts`) already
uses:

- Flip the WEBSITE_URL / DOCS_URL defaults to the canonical localhost
  ports (`http://localhost:5000`, `http://localhost:4000`), matching
  each sibling app's `webjs:dev --port` flag.
- Replace the one hardcoded `https://webjs.dev` link in the footer with
  the WEBSITE_URL constant (was a missed substitution).
- Add `.env.example` documenting the same defaults so deployment env
  overrides have something to point at.
- AGENTS.md table covering env var name, local fallback, production
  value, plus a note that copying .env.example is only needed when
  overriding (the fallbacks already match local).

Deploys (ui.webjs.dev on Railway) MUST set WEBSITE_URL=https://webjs.dev
and DOCS_URL=https://docs.webjs.dev in service env vars; otherwise the
header + footer will link to the localhost ports in production. Adding
that step to the deployment runbook is part of this commit's intent
(see the AGENTS.md table).

Author: vivek7405

packages/ui/packages/website/.env.example

@@ -0,0 +1,7 @@
+# Sibling-app URLs surfaced in the UI website's header + footer.
+# Copy this file to `.env` (`cp .env.example .env`) for local dev.
+# Canonical localhost dev ports (one source of truth alongside the
+# matching fallbacks in app/layout.ts). Deployments override these
+# with real public URLs (e.g. via Railway's service env vars).
+WEBSITE_URL=http://localhost:5000
+DOCS_URL=http://localhost:4000

packages/ui/packages/website/AGENTS.md

@@ -103,6 +103,21 @@ The `predev` hook runs `scripts/copy-registry.js` to populate
 something to import. Re-running `npm run dev` re-populates from the
 current registry state.
 
+### Sibling-app URLs (header, footer)
+
+Sibling-app links in the header + footer (Webjs site, Docs) read from
+`WEBSITE_URL` / `DOCS_URL` env vars. Fallbacks are the canonical
+localhost dev ports so local `npm run dev` works with zero setup. Deploy
+by overriding via the service env (e.g. Railway's variables):
+
+| Env var | Local fallback | Production value |
+|---|---|---|
+| `WEBSITE_URL` | `http://localhost:5000` | `https://webjs.dev` |
+| `DOCS_URL` | `http://localhost:4000` | `https://docs.webjs.dev` |
+
+`.env.example` in this directory documents the same defaults. Copy it to
+`.env` only if you need to override locally; the fallbacks already match.
+
 ---
 
 Framework-wide rules and the framework API reference:

packages/ui/packages/website/app/layout.ts

@@ -1,9 +1,20 @@
 import { html } from '@webjskit/core';
 import './_components/theme-toggle.ts';
 
+/**
+ * Sibling-app URLs are read from env so the same code works in
+ * `webjs dev` (localhost) and in deployment (real hosts). Fallbacks
+ * are the canonical localhost dev ports (matching the matching apps'
+ * `webjs:dev --port` flags). Deploy by overriding WEBSITE_URL /
+ * DOCS_URL in the service env (Railway, etc.); `.env.example` in
+ * this directory documents the same defaults for visibility.
+ *
+ * Guarded against `process` being undefined: this file also loads
+ * on the client during hydration.
+ */
 const env = (globalThis as any).process?.env ?? {};
-const WEBSITE_URL = env.WEBSITE_URL || 'https://webjs.dev';
-const DOCS_URL = env.DOCS_URL || 'https://docs.webjs.dev';
+const WEBSITE_URL = env.WEBSITE_URL || 'http://localhost:5000';
+const DOCS_URL = env.DOCS_URL || 'http://localhost:4000';
 
 const TITLE = 'Webjs UI: AI-first component library';
 const DESCRIPTION =
@@ -310,7 +321,7 @@ export default function Layout({ children }: { children: any }) {
 
     <footer class="border-t mt-20 py-8 text-center" style="color: var(--fg-subtle); font-size: 13px">
       <div class="max-w-5xl mx-auto px-6">
-        <a class="text-brand no-underline hover:underline" href="https://webjs.dev" target="_blank">Webjs</a> ·
+        <a class="text-brand no-underline hover:underline" href=${WEBSITE_URL} target="_blank">Webjs</a> ·
         <a class="text-brand no-underline hover:underline" href=${DOCS_URL} target="_blank">Docs</a> ·
         <a class="text-brand no-underline hover:underline" href="https://github.com/vivek7405/webjs" target="_blank">GitHub</a>
       </div>