fix(shared): refresh portfolio story and asset delivery

.dev-surfaces/skills/dev-surface/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: portfolio-dev-surface
+description: Use when working in Portfolio and needing the local Next site or Storybook.
+---
+
+# Portfolio Dev Surface
+
+Inside this repo, use the repo-native command:
+
+```sh
+bun install
+bun run dev
+```
+
+`bun run dev` runs `scripts/dev.mjs`, which starts the Next site and Storybook together, streams both logs, and cleans up on Ctrl-C.
+
+Expected ports:
+
+- `3201`: Next site
+- `3202`: Storybook
+
+Useful native commands:
+
+```sh
+bun run dev
+bun run dev:site
+bun run storybook
+```
+
+For cross-repo orchestration from anywhere, use the global workbench:
+
+```sh
+dev launch portfolio
+dev launch portfolio:site
+dev status portfolio
+dev health portfolio
+dev stop portfolio
+```
+
+Do not call `.dev-surfaces/run.mjs`; this repo should not have that wrapper.

.dev-surfaces/surfaces.json

@@ -0,0 +1,48 @@
+{
+  "version": 1,
+  "project": {
+    "id": "portfolio",
+    "name": "Portfolio",
+    "root": "/Users/afo/Code/portfolio"
+  },
+  "surfaces": [
+    {
+      "id": "site",
+      "name": "Next site",
+      "kind": "ui",
+      "ports": [
+        3201
+      ],
+      "command": [
+        "bun",
+        "run",
+        "dev:site"
+      ],
+      "urls": [
+        "http://localhost:3201/"
+      ],
+      "env": {
+        "PATH": "/Users/afo/.local/share/mise/installs/node/22.22.1/bin:${PATH}"
+      }
+    },
+    {
+      "id": "storybook",
+      "name": "Storybook",
+      "kind": "docs-ui",
+      "ports": [
+        3202
+      ],
+      "command": [
+        "bun",
+        "run",
+        "storybook"
+      ],
+      "urls": [
+        "http://localhost:3202/"
+      ],
+      "env": {
+        "PATH": "/Users/afo/.local/share/mise/installs/node/22.22.1/bin:${PATH}"
+      }
+    }
+  ]
+}

.env.example

@@ -1,3 +1,4 @@
 NEXT_PUBLIC_WEBSITE_URL=https://afolabi.info
-AUTH_EMAIL_PASS=
-AUTH_EMAIL_USER=
+RESEND_API_KEY=
+CONTACT_EMAIL_TO=contact@afolabi.info
+CONTACT_EMAIL_FROM=Afolabi Portfolio <notifications@afolabi.info>

.gitignore

@@ -38,6 +38,7 @@ jspm_packages/
 
 # Typescript v1 declaration files
 typings/
+*.tsbuildinfo
 
 # Optional npm cache directory
 .npm
@@ -60,6 +61,7 @@ typings/
 
 build/
 build-storybook/
+output/agentic-browser-proof/
 public/sitemap.xml
 public/draco/
 public/og

.plans/README.md

@@ -0,0 +1,19 @@
+# Portfolio Planning OS
+
+Portfolio uses a lightweight planning surface modeled after TAS Hub. It is meant
+to keep implementation plans reusable without adding lane files, queue scripts,
+or tool-specific handoff choreography.
+
+## Layout
+
+- `features/<feature-slug>/spec.md` - execution-ready plan
+- `features/<feature-slug>/context.md` - current state, constraints, notes
+- `audits/YYYY-MM-DD-<slug>.md` - point-in-time audits and readiness reports
+- `templates/feature/` - starter files for new feature folders
+
+## Operating Rules
+
+- Keep plan artifacts human-readable and reusable by future tools.
+- Do not add `.todo.md` lane files, queue metadata, handoff branches, or package scripts unless the planning system is deliberately expanded later.
+- Keep runtime component, CSS, content, and asset edits out of plan-only passes.
+- When the worktree has active story or UI changes, preserve those files and scope plan updates to `.plans/**`.

.plans/features/modern-css-web-ui-primitives/context.md

@@ -0,0 +1,24 @@
+# Modern CSS/Web UI Primitives Context
+
+## Current State
+
+- Source audit: `/Users/afo/Documents/Codex/2026-05-23/i-m-watching-this-great-video/modern-css-web-ui-audit.md`.
+- Portfolio did not have a `.plans` directory before this bootstrap, so this feature uses the same lightweight plan shape as TAS Hub.
+- The app is a Next 15, React 18, Bun 1.3.10 portfolio site using CSS Modules, SCSS, Framer Motion, Three.js, and a JavaScript token/theme provider.
+- `src/components/ThemeProvider/theme.js` defines viewport-specific rem-based typography and light/dark theme tokens.
+- `src/layouts/App/global.scss` sets `body` to `width: 100vw` and `overflow-x: hidden`; several pages and layout modules still use `100vh` or `100vw`.
+- Current interaction code includes manual scroll listeners for hash scrolling, parallax, navbar inversion, and scroll restoration, plus Framer Motion route/page transitions.
+- The app has `color-scheme` in reset CSS and several reduced-motion-aware hooks, but no explicit `prefers-contrast` or `forced-colors` contract for text, focus, canvas/WebGL, image-backed overlays, or project-page surfaces.
+
+## Constraints
+
+- This plan tracks future work only. Do not change runtime CSS, components, scripts, dependencies, metadata, or generated assets in this pass.
+- Preserve the active `portfolio-story-refresh` worktree. Existing dirty story, component, package, docs, public, and asset files are unrelated unless a future task explicitly scopes them in.
+- Bootstrap only the lightweight planning surface: README, templates, and this feature pack. Do not add package scripts, validation helpers, lane files, or queue metadata.
+- Modern CSS/Web UI adoption should be progressive and compatible with Portfolio's current browser target of `>10%, not dead, not ie 11, not op_mini all`.
+
+## Notes
+
+- Priority primitives from the audit: text-scale readiness, dynamic viewport units, OS preference support, token roles, native browser navigation/motion primitives, and reduced scroll-listener complexity.
+- Portfolio-specific candidates: `100vw`/scrollbar policy, `100vh` to dynamic viewport migration, CSS scroll spy for hash navigation, progressive View Transitions as an alternative to some Framer route transitions, and a token contract that bridges JS theme tokens with CSS Modules.
+- Safe adoption path: document first, pilot one low-risk route or component, guard newer features with `@supports` or feature detection, provide static/reduced-motion fallbacks, and verify across breakpoint and preference modes.

.plans/features/modern-css-web-ui-primitives/spec.md

@@ -0,0 +1,36 @@
+# Modern CSS/Web UI Primitives
+
+## Goal
+
+Create an execution-ready backlog for adopting modern CSS and Web UI primitives in Portfolio without starting runtime implementation yet. The work should improve accessibility, scrolling behavior, and design-token consistency while preserving the current portfolio story refresh.
+
+## Key Changes
+
+- Text-scale readiness: audit the JS token system, rem conversion, large display type, project pages, nav, contact page, and mobile layouts before considering `meta name="text-scale" content="scale"`.
+- CSS architecture: document how global SCSS, CSS Modules, JS theme tokens, custom media, and project case-study styles should share ownership before introducing cascade layers, scoped CSS, or new token conventions.
+- Preference and native UI readiness: define `color-scheme`, `prefers-reduced-motion`, `prefers-contrast`, `forced-colors`, visible focus, and touch-target expectations; future overlays, menus, and tooltips should prefer native `<dialog>` or `popover` where component-library behavior is unnecessary.
+- Viewport cleanup: replace future reliance on `width: 100vw`, `height: 100vh`, and `min-height: 100vh` with scrollbar-aware and dynamic viewport patterns such as `overflow-x: clip`, `100dvh`, `100svh`, or `100lvh` where validated.
+- Scroll behavior: inventory `useScrollToHash`, `useParallax`, `ScrollRestore`, navbar scroll listeners, and project-page parallax to identify where CSS scroll spy, scroll-state queries, or awaited programmatic scroll can reduce JavaScript.
+- Motion modernization: compare current Framer Motion route/page transitions with progressive View Transitions, keeping reduced-motion behavior and existing visual continuity as acceptance criteria.
+- Token consistency: document how `ThemeProvider` JS tokens, CSS custom properties, CSS Modules, and hardcoded page styles should relate before adding new project case-study styles.
+- Layered UI readiness: no immediate overlay work is required, but future dialogs, tooltips, and menus should prefer native `<dialog>` or `popover` where component-library behavior is unnecessary.
+- Research only: keep HTML-in-Canvas, overscroll gestures, scoped View Transitions, CSS `@function`, CSS `if()`, `corner-shape`, and `fit-text` out of production scope until a specific Portfolio use case justifies a pilot.
+
+## Validation
+
+- Plan-only pass: confirm `git status --short --branch` before editing and keep the diff scoped to `.plans/**`.
+- Run `git diff --check` after the plan files are added.
+- Each future primitive promotion should capture regression risk, vulnerable surfaces, fallback behavior, proof required, existing abstraction fit, and reversibility before runtime work starts.
+- Do not run `bun run lint`, `bun run build`, or Storybook validation for this pass because no runtime files should change and the checkout has unrelated active UI work.
+
+## Next Proof Task
+
+- Keep this plan-only until a route, case-study, media, or Storybook runtime change is scoped. The next proof task is an isolated Chrome DevTools MCP or `bun run agentic:browser-proof` pass for the changed surface, capturing route/surface URL, viewport, screenshot or DOM/accessibility snapshot, console/page errors, useful network notes, `/llms.txt`, reduced-motion behavior, and `list_webmcp_tools`.
+- For any View Transition prototype, capture LCP, INP, CLS, route label, `navigationType`, reduced-motion state, and media/3D state before and after the transition. Do not add RUM dependencies for this planning pass.
+- Keep runtime WebMCP frozen. Any future page/case-study read-only tool candidate needs an approval spec covering candidate visible tools, forbidden tools, confirmation rules, public/privacy boundary, schema tests, wrong-tool/wrong-argument evals, and proof commands.
+
+## Assumptions
+
+- Portfolio should use the lightweight TAS-style planning model rather than the heavier Green Goods or Coop plan-hub contracts.
+- Backlog-first means this feature pack becomes the tracking surface for future CSS modernization, not an implementation batch.
+- Existing Framer Motion and Three.js surfaces stay in place until a future task proves a modern browser primitive can replace or simplify them safely.

.plans/templates/feature/context.md

@@ -0,0 +1,13 @@
+# Feature Context
+
+## Current State
+
+Summarize the relevant repo surface as it exists today.
+
+## Constraints
+
+- Runtime, package manager, validation, or content constraints
+
+## Notes
+
+- Links to related audits, docs, or prior decisions

.plans/templates/feature/spec.md

@@ -0,0 +1,17 @@
+# Feature Spec
+
+## Goal
+
+Describe the user outcome and success condition.
+
+## Key Changes
+
+- List the behavior or implementation changes required.
+
+## Validation
+
+- List the exact commands and QA checks required before completion.
+
+## Assumptions
+
+- Record defaults chosen to keep implementation decision-complete.

.storybook/manager-head.html

@@ -38,7 +38,6 @@
   content="My custom design component system created from the ground up used in building my portfolio"
 />
 <meta name="twitter:title" content="Afolabi Aiyeloja | Storybook" />
-<meta name="twitter:site" content="@Afolabi_A_A_A" />
 <meta name="twitter:image" content="https://afolabi.info/social-image.png" />
 
 <script src="https://magi.afolabi.info/script.js" data-site="CJZKJKLA" defer></script>

AGENTS.md

@@ -7,10 +7,23 @@ Working agreements for AI coding agents in `portfolio`.
 - Use Bun (`bun@1.3.10`), the checked-in `bun.lock`, and the project scripts already present in this repository. Do not reintroduce npm, yarn, or pnpm lockfiles unless the user explicitly asks for that package-manager change.
 - Keep changes scoped to the user request and avoid broad dependency, workflow, or agent-config churn.
 
-## Agentic Browser QA
+## Agentic Modern Web Standard
 
+- Baseline target: Baseline Widely Available. Before frontend, UI, CSS, accessibility, browser proof, or web-design changes, run repo-installed Modern Web Guidance with `bun run agentic:guidance`, then apply the existing Next.js, Storybook, and portfolio presentation constraints.
+- Prefer semantic HTML, native controls, platform CSS, and browser primitives before custom JavaScript. Keep landmarks, headings, links, buttons, forms, accessible names, focus states, touch targets, loading/error/empty states, and reduced-motion behavior clear in the rendered DOM and accessibility tree.
+- Run `bun run agentic:check` for hard guidance-readiness plus the design-token guard and lint lane. For local layout, interaction, motion, 3D, or route QA, use the authenticated Brave QA profile through the live authenticated-browser path below. Treat `bun run agentic:browser-proof` as a CI/clean-room browser proof lane only; it builds Next, captures route screenshots and accessibility summaries, checks console/page errors, `/llms.txt`, reduced-motion behavior, WebMCP discovery, and then builds Storybook, but it must not be reported as local authenticated verification. `dev-surfaces` remains the cross-repo/global doctor for shared Modern Web Guidance cache refresh, Brave, and MCP readiness.
 - Local agentic browser QA must use the authenticated Brave QA profile. Codex: use the Codex browser-extension path and claim the already-open Brave tab/window. Claude Code: use the Claude Code Chrome/Chromium extension path (`claude --chrome` or `/chrome`) and select the authenticated Brave profile/tab when it is installed, connected, and able to control the already-open Brave window. Do not fall back merely because the extension is branded Chrome. If the Brave extension path is unavailable or not connected, use Claude computer-use/visible desktop control of the already-open Brave window; if neither can reach authenticated Brave, report QA as blocked. Use this for admin, PWA, extension, wallet/passkey, staging-session, installed-app, and profile-dependent verification.
 - Do not use isolated Browser, Playwright, or DevTools MCP profiles for local QA. Existing isolated browser-proof commands are CI/clean-room checks only and must not be reported as authenticated verification. If authenticated Brave access is blocked, stop and report QA as blocked.
+- WebMCP has an explicitly approved public read-only runtime pilot. Keep tools in `src/utils/webmcp.ts` visible, page-scoped, and public-safe; do not add contact submission, analytics, private context, hidden admin actions, destructive operations, or background-only actions.
+- For MCP/tool selection and WebMCP expansion, use `docs/agentic-mcp-tooling-runbook.md` as the operating map before adding tools or changing proof lanes.
+
+## Design System Guardrails
+
+- Load `DESIGN.md`, `src/components/ThemeProvider/theme.ts`, the nearest CSS Module or SCSS file, and Storybook context before UI/CSS work.
+- Run `bun run check:design-tokens` for UI/CSS changes; it blocks new raw colors, gradients, viewport units, raw radii, and raw motion values unless they are intentionally recorded in `scripts/data/design-token-baseline.tsv`.
+- Keep existing Portfolio identity intact: editorial case studies, restrained motion, and 3D as supporting atmosphere rather than a new product UI system.
+- For new case studies or route changes, update project data in `src/constants.ts`, route data in `src/utils/siteRoutes.json`, and keep public/browser-proof routes aligned with `bun run check:site-routes`. Reuse `layouts/Project` and `src/pages/projects/CaseStudy.module.scss` before adding a new visual grammar.
+- For contact or form changes, keep validation shared through `src/utils/contact.ts` so client constraints and API parsing do not drift.
 
 ## Supply-chain and agent safety
 

DESIGN.md

@@ -0,0 +1,38 @@
+---
+name: Portfolio Design System
+description: Lightweight design contract for the Afolabi portfolio site, grounded in the current Next.js, Storybook, SCSS, CSS Modules, Framer Motion, and Three.js implementation.
+---
+
+# Portfolio Design System
+
+This site is a personal portfolio and case-study surface. It should feel precise, editorial, technical, and calm: the work is the signal, with motion and 3D used to deepen the story rather than decorate every section.
+
+## Source Of Truth
+
+- Runtime theme tokens live in `src/components/ThemeProvider/theme.ts`.
+- Global CSS ownership lives in `src/layouts/App/global.scss` and `src/layouts/App/reset.css`.
+- Component and route styling lives in CSS Modules next to the component or page.
+- Project content contracts live in `src/constants.ts`; public route, nav, and browser-proof route ownership lives in `src/utils/siteRoutes.json`.
+- Storybook is the visual review surface; use `bun run agentic:browser-proof` when UI, layout, motion, or public routes change.
+
+## Token Rules
+
+- Use `ThemeProvider` tokens for color, spacing, typography, motion duration, easing, and z-index before adding raw values.
+- New project pages should add a typed project record first, add the route manifest entry, reuse `src/pages/projects/CaseStudy.module.scss` and existing `layouts/Project` patterns, then run `bun run check:site-routes` before adding a new visual grammar.
+- Raw hex, `rgba()`, `linear-gradient()`, `100vw`, `100vh`, raw radius, raw duration, and raw easing values are design-system risks. They are allowed only when captured in `scripts/data/design-token-baseline.tsv` with a reason.
+- Metadata colors in `_document.page.tsx` are allowed because browser chrome cannot consume CSS variables reliably.
+
+## Layout And Responsiveness
+
+- Prefer scrollbar-safe sizing over `width: 100vw`.
+- Prefer dynamic viewport units or content-driven sizing over `height: 100vh` and `min-height: 100vh` on mobile-sensitive sections.
+- Keep focus states visible, touch targets large enough for coarse pointers, and text readable when browser text scaling increases.
+
+## Motion And 3D
+
+- Framer Motion and Three.js are part of the current identity, but new motion must honor reduced-motion behavior and should not be required to understand content.
+- Prefer CSS/browser primitives when they replace custom scroll listeners or route animation code without losing accessibility.
+
+## Validation
+
+Run `bun run check:design-tokens` for UI/CSS changes. Run `bun run agentic:check` before handoff. Use `bun run agentic:browser-proof` for layout, route, Storybook, motion, 3D, or public-page changes.

README.md

@@ -12,15 +12,19 @@ Make sure you have Node.js `22.22.1` and Bun `1.3.10` installed. This repo uses
 bun install --frozen-lockfile
 ```
 
-Once it's done start up a local server with:
+Once it's done, start the full local environment with:
 
 ```bash
 bun run dev
 ```
 
-To view the components storybook:
+That launches the Next site on `3201` and Storybook on `3202` through the
+repo-native coordinator in `scripts/dev.mjs`. Press Ctrl-C to stop both.
+
+To run only the Next site or only Storybook:
 
 ```bash
+bun run dev:site
 bun run storybook
 ```