alehar9320 · Sep 17, 2026
diff --git a/.Jules/archie.md b/.Jules/archie.md
@@ -0,0 +1,3 @@
+2026-03-30 - Cloudflare Workers + Assets Architecture Codification
+Learning: Transitioning from legacy Cloudflare Pages to the unified Workers + Assets model (`wrangler.jsonc`) requires explicit agent directives to prevent AI agents from generating outdated `_routes.json` or `_headers` files or attempting manual deployment pushes in CI.
+Action: Document Workers + Assets in ADR 0002 and enforce via Tech Radar `Hold` status on legacy Pages patterns.
diff --git a/docs/adr/0002-cloudflare-workers-assets-unified-architecture.md b/docs/adr/0002-cloudflare-workers-assets-unified-architecture.md
@@ -0,0 +1,24 @@
+# 0002. Cloudflare Workers + Assets Unified Architecture
+
+- **Status:** Accepted
+- **Date:** 2026-03-30
+- **Deciders:** Autonomous Architect (Archie) / Repository Analysis
+
+## Context
+
+Cloudflare transitioned static asset hosting and edge functions under a unified Workers + Assets model configured via `wrangler.jsonc`. Previous deployment patterns relied on Cloudflare Pages or multi-step manual deployment tasks in CI pipelines. The repository migrated to Astro with `@astrojs/cloudflare` and `wrangler.jsonc` to align with the Workers-first architecture.
+
+## Decision
+
+Adopt the unified Cloudflare Workers + Assets architecture (`wrangler.jsonc` and `src/cloudflare-worker.ts`) as the single canonical production deployment target. Production auto-deploys are handled exclusively via Cloudflare Git integration on pushes to `main`. CI GitHub Actions workflows validate quality checks and create GitHub releases without modifying `main` or running redundant manual wrangler deployment steps.
+
+## Consequences & Tradeoffs
+
+- **Positive:** Eliminates dual-deploy race conditions, reduces CI runtime by delegating build/deploy to Cloudflare Workers infrastructure, and unifies static assets with edge Worker bindings (KV, AI, env vars).
+- **Negative / Risks:** Local development requires `wrangler` CLI or `astro dev` with worker bindings stubbing. Non-Cloudflare test environments (such as Render Node adapter) require adapter switching (`RENDER=true`).
+- **Adoption Readiness:** High confidence; live production (`https://me.alehar.workers.dev`) is operating successfully on this model.
+
+## Directives for AI Agents
+
+- **Do:** Use `wrangler.jsonc` for Worker bindings and environment configuration. Maintain static output (`output: "static"`) with Cloudflare adapter in `astro.config.mjs`.
+- **Don't:** Do not introduce legacy Cloudflare Pages configuration files (`_routes.json`, `_headers` in static roots) or add manual `wrangler deploy` steps in GitHub Actions CI workflows. Do not modify `wrangler.jsonc` without verifying Workers-first impact.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,18 @@
+# Architecture Decision Records (ADR)
+
+This directory contains Architecture Decision Records (ADRs) for the personal portfolio repository of Alexander Härenstam.
+
+## ADR Index
+
+| Number                                                           | Title                                              | Status   | Date       |
+| :--------------------------------------------------------------- | :------------------------------------------------- | :------- | :--------- |
+| [0001](./0001-cloudflare-production-render-jules.md)             | Cloudflare as production, Render as Jules test env | Accepted | 2026-08-24 |
+| [0002](./0002-cloudflare-workers-assets-unified-architecture.md) | Cloudflare Workers + Assets Unified Architecture   | Accepted | 2026-03-30 |
+
+## Governance & Rules for AI Agents
+
+When introducing new architectural changes:
+
+1. Always create sequential ADRs (`NNNN-title.md`).
+2. Include explicit "Directives for AI Agents" with clear `Do` and `Don't` boundaries.
+3. Update this index table whenever an ADR is added, updated, or superseded.
diff --git a/docs/tech-radar.md b/docs/tech-radar.md
@@ -0,0 +1,56 @@
+# Repository Tech Radar
+
+## Quadrants
+
+### 1. Frameworks & Runtimes
+
+- **Adopt:**
+  - Astro (v7+) - Core SSG framework for performance, SEO, and content collections.
+  - TypeScript (Strict) - Mandatory type checking and schema validation across the codebase.
+  - Node.js (v22.12.0+) - Standard runtime engine for local development and Render test environment.
+- **Trial:**
+  - `@astrojs/node` - Standalone Node adapter reserved for Render Jules test environment when `RENDER=true`.
+- **Assess:**
+  - Server-Sent Events (SSE) / Edge Stream Handlers - Potential future pattern for dynamic edge responses.
+- **Hold:**
+  - React / Vue / Svelte UI Framework Islands - Avoid heavy JS frameworks; preserve vanilla HTML/CSS/JS model.
+
+### 2. Infrastructure & Cloud
+
+- **Adopt:**
+  - Cloudflare Workers + Assets (`wrangler.jsonc`) - Primary edge host for static assets and edge logic.
+  - GitHub Actions CI - Automated PR quality checks, linting, tests, and GitHub Release generation.
+- **Trial:**
+  - Render Web Services - Secondary test environment for Google Jules debugging (`RENDER=true`).
+- **Assess:**
+  - Cloudflare KV / D1 - Edge storage bindings for future dynamic features.
+- **Hold:**
+  - Legacy Cloudflare Pages - Phased out in favor of Workers + Assets unified model.
+  - Direct Writes to Protected `main` in CI - CI must not push generated release artifacts back to `main`.
+
+### 3. Tooling & AI Workflows
+
+- **Adopt:**
+  - Vitest - Fast unit test runner for utilities and content validations.
+  - Prettier & ESLint - Code style and linting enforcement across repository files.
+  - Zod - Core runtime and compile-time schema validation library.
+  - MCP Servers (`mcp_config.json`) - Model Context Protocol servers for AI tool integration.
+- **Trial:**
+  - Codecov Vite Plugin - Test coverage and bundle analysis integration.
+- **Assess:**
+  - Playwright / Automated E2E Visual Testing - Under evaluation for visual regression automation.
+- **Hold:**
+  - `pnpm` / `yarn` - Stick strictly to `npm` for package operations and lockfile maintenance.
+
+### 4. Patterns & Architecture
+
+- **Adopt:**
+  - Static Pre-rendering (`output: "static"`) - Default build target for high performance and low latency.
+  - Vanilla CSS & Northern Lights Theme - Custom CSS variables with glassmorphism aesthetics.
+  - Feature Flags (`src/content/flags/config.json`) - Zod-validated JSON feature toggle configuration.
+- **Trial:**
+  - Experimental Subroutes (`src/pages/experimental/`) - Isolated routes for testing MVP enhancements.
+- **Assess:**
+  - View Transitions API - Native browser transition enhancements across static route navigation.
+- **Hold:**
+  - Tailwind CSS / External Utility CSS Frameworks - Prohibited to prevent bundle bloat and maintain custom styling control.