diff --git a/README.md b/README.md
index cfc17140..5c9d27c4 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,10 @@
 # Open Elements Website
 
-This repository contains the Open Elements website.
+This repository contains the Open Elements website built with Next.js and Tailwind CSS, with legacy Hugo content kept for migration and historical content.
 
 ## Architecture (2026)
 
-The project is now a Next.js application with App Router, Tailwind CSS, and `next-intl` for i18n. Legacy Hugo content and templates are still kept in the repo for migration and historical content.
+The project is a Next.js application using App Router, Tailwind CSS, and `next-intl` for i18n. Legacy Hugo content and templates are kept in the repo for migration and historical content.
 
 ### Runtime layers
 
@@ -58,8 +58,36 @@ pnpm run build
 pnpm run start
 ```
 
+### Lint
+
+```
+pnpm run lint
+```
+
 ### E2E tests
 
 ```
 pnpm run test:e2e
 ```
+
+## Repo structure
+
+```
+src/app            Next.js App Router pages & layouts
+src/components     UI components
+src/i18n           next-intl routing/messages helpers
+locales            Translation JSON files
+content            Legacy Hugo Markdown content
+src/layouts        Legacy Hugo templates
+public             Static assets and generated artifacts
+react-src          Web components source (bundled to public/js)
+tests/e2e          Playwright specs
+```
+
+## Web components build
+
+Custom elements in `react-src` are bundled with esbuild via `react-src/build.mjs` into `public/js`. This output is treated as generated code.
+
+## Deployment
+
+Netlify builds run `pnpm install` and `pnpm run build` (see `netlify.toml`).
diff --git a/src/app/[locale]/about/page.tsx b/src/app/[locale]/about/page.tsx
index e288ae13..a3b0486f 100644
--- a/src/app/[locale]/about/page.tsx
+++ b/src/app/[locale]/about/page.tsx
@@ -35,7 +35,6 @@ export default function AboutPage() {
 
   return (
     <div className="">
-      {/* Hero Background */}
       <div className="absolute  left-0 w-full top-0 h-34 -z-10 overflow-hidden">
         <Image
           src="/illustrations/hero-bg-2.svg"
@@ -47,7 +46,6 @@ export default function AboutPage() {
       </div>
 
       <div className="flow-root relative pb-20 sm:pb-36 container">
-        {/* Decorative images */}
         <Image
           className="top-20 right-0 absolute size-40 shrink-0"
           src="/illustrations/circles-2.svg"
diff --git a/src/app/[locale]/contact/page.tsx b/src/app/[locale]/contact/page.tsx
index e5cde012..8550f7ea 100644
--- a/src/app/[locale]/contact/page.tsx
+++ b/src/app/[locale]/contact/page.tsx
@@ -11,7 +11,6 @@ export default function ContactPage() {
   return (
     <div className="relative">
       <div className="container relative max-w-sm lg:max-w-7xl md:max-w-2xl sm:max-w-xl sm:w-full xl:pb-36 pb-28">
-        {/* Decorative lines */}
         <Image
           className="absolute hidden w-full -ml-20 top-52 2xl:-ml-32 lg:block"
           src="/illustrations/lines-5.svg"
@@ -26,8 +25,7 @@ export default function ContactPage() {
           width={800}
           height={100}
         />
-        
-        {/* Header */}
+
         <div className="flex items-center justify-center pt-16 pb-4 lg:pt-36 md:pt-28 sm:pt-24 sm:pb-12">
           <h1 className="flex items-center justify-center w-full text-center h1">
             <div className="relative z-0 flex items-center justify-center w-full">
@@ -42,13 +40,11 @@ export default function ContactPage() {
             </div>
           </h1>
         </div>
-        
-        {/* Content */}
+
         <div className="relative flex flex-col gap-24 2xl:gap-40 lg:gap-32">
           <CalendlyButton />
           
           <div className="relative flex flex-col-reverse items-center justify-center w-full gap-16 lg:flex-row xl:gap-12 lg:gap-6">
-            {/* Decorative rounds */}
             <Image
               className="absolute lg:w-[450px] w-80 lg:-left-44 -left-24 lg:top-12 top-[500px] sm:block hidden"
               src="/illustrations/round-1.svg"
diff --git a/src/app/[locale]/layout.tsx b/src/app/[locale]/layout.tsx
index fe289d4e..f97faca3 100644
--- a/src/app/[locale]/layout.tsx
+++ b/src/app/[locale]/layout.tsx
@@ -65,13 +65,10 @@ export default async function LocaleLayout({
 }) {
   const { locale } = await params;
 
-  // Ensure that the incoming `locale` is valid
   if (!routing.locales.includes(locale as any)) {
     notFound();
   }
 
-  // Providing all messages to the client
-  // side is the easiest way to get started
   const messages = await getMessages();
 
   return (
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index da969b84..78a498ad 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -23,8 +23,6 @@ export const metadata: Metadata = {
   },
 }
 
-// Root layout delegates to [locale]/layout.tsx for i18n support
-// The locale layout provides html/body with proper lang attributes
 export default function RootLayout({
   children,
 }: {