🏛️ Archie: Codify Zod Schema Validation & Establish Core Architectural Artifacts

.jules/archie.md

@@ -0,0 +1,3 @@
+2026-08-24 - Establish Core Architectural Governance & Codify Schema Validation ADR
+Learning: Implicit repository conventions for Zod boundary validation and Cloudflare/Render target separation lacked explicit AI Agent Directives and master index documentation, risking agent architectural drift.
+Action: Standardized ADR template formatting, established `docs/adr/README.md` master index and `docs/tech-radar.md` repository tech radar, and codified strict Zod boundary validation into `docs/adr/0002-strict-zod-schema-validation.md`.

docs/adr/0001-cloudflare-production-render-jules.md

@@ -1,18 +1,26 @@
-# ADR 0001: Cloudflare as production, Render as Jules test env
+# 0001. Cloudflare as Production, Render as Jules Test Environment
 
-- Status: Accepted
-- Date: 2026-08-24
+- **Status:** Accepted
+- **Date:** 2026-08-24
+- **Deciders:** Autonomous Architect (Archie) / Repository Analysis
 
 ## Context
 
-The site can build two ways: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node standalone server when `RENDER=true` (`@astrojs/node`). Prod already runs at https://me.alehar.workers.dev/. We need a clear split so Google Jules can debug against a Node environment without treating that path as a second production or failover.
+The site can build two ways: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node standalone server when `RENDER=true` (`@astrojs/node`). Production already runs at https://me.alehar.workers.dev/. We need a clear architectural split so automated AI agents (such as Google Jules) can debug against a Node server environment without treating that path as a second production instance or failover target.
 
 ## Decision
 
-Production is Cloudflare Workers only. Render is a test environment for Google Jules (Node server via `render.yaml`). It is not a second prod and not a failover.
+Production is strictly Cloudflare Workers + Assets. Render is exclusively a isolated test environment for Google Jules debugging (Node server via `render.yaml`). Render is not a second production environment and must never be treated as a failover target.
 
-## Consequences
+## Consequences & Tradeoffs
 
-- Ship and operate prod on the Cloudflare Worker (`wrangler.jsonc`, `src/cloudflare-worker.ts`).
-- Keep the Render Node path for Jules debugging only; expect AI/KV and other Workers bindings to be absent or stubbed there (`src/env/cloudflare-workers.node.ts`).
-- Docs and ops language should call Cloudflare production and Render the Jules test env.
+- **Positive:** Clear separation of deployment targets; production operates entirely on serverless edge infrastructure with ultra-low latency and native Cloudflare Workers assets.
+- **Negative / Risks:** Development and test environments running on Node (such as Render) must mock or stub Cloudflare Workers runtime bindings (`src/env/cloudflare-workers.node.ts`).
+- **Adoption Readiness:** Fully adopted and active in production.
+
+## Directives for AI Agents
+
+- **Do:** Ship and operate production strictly on the Cloudflare Workers target (`wrangler.jsonc`, `src/cloudflare-worker.ts`).
+- **Do:** Refer to Cloudflare as "production" and Render as "Jules test environment" across logs, documentation, and PR descriptions.
+- **Don't:** Treat Render as a production target, secondary region, or failover system.
+- **Don't:** Rely on native Cloudflare Workers bindings (e.g. KV, AI bindings) when running inside the Render Node test environment.

docs/adr/0002-strict-zod-schema-validation.md

@@ -0,0 +1,27 @@
+# 0002. Strict Zod Schema Validation for Content Collections and API Boundaries
+
+- **Status:** Accepted
+- **Date:** 2026-08-24
+- **Deciders:** Autonomous Architect (Archie) / Repository Analysis
+
+## Context
+
+The repository handles unstructured or dynamic inputs across several key system boundaries: Astro Markdown/MDX content collections, environment variable configurations, and edge API request payloads. Without explicit schema validation at runtime and build time, unvalidated input can lead to runtime exceptions (`undefined` field access), type safety erosion, and agent drift when generating content or handling API payloads.
+
+## Decision
+
+All external data, content collections, environment variables, and dynamic API request payloads must be strictly validated using Zod schemas at runtime and compile-time boundaries. TypeScript interfaces for data collections must be derived directly from Zod schemas using `z.infer<typeof schema>`.
+
+## Consequences & Tradeoffs
+
+- **Positive:** Eliminates runtime `undefined` property access errors; provides a single source of truth for application data types; prevents untyped agent drift during content generation and API refactoring.
+- **Negative / Risks:** Minor build-time overhead for schema parsing; requires keeping Zod schemas synchronized when adding new content fields.
+- **Adoption Readiness:** Fully adopted across Astro content collections (`src/content.config.ts`), environment handling (`src/env/`), and edge endpoints (`src/pages/api/`).
+
+## Directives for AI Agents
+
+- **Do:** Declare and export explicit Zod schemas in `src/content.config.ts` or endpoint modules before consuming external data or content collections.
+- **Do:** Derive TypeScript types via `z.infer<typeof schema>` rather than declaring redundant manual interface declarations.
+- **Do:** Use `z.ZodError['issues']` or safe guards when referencing Zod error types in tests to avoid Zod 4 deprecation warnings.
+- **Don't:** Bypass schema validation using type assertions (`as MyType`), explicit `any`, or `@ts-ignore`.
+- **Don't:** Parse API request bodies without using `.safeParse()` or `.parse()` at the boundary handler.

docs/adr/README.md

@@ -0,0 +1,17 @@
+# Architecture Decision Records (ADRs)
+
+This directory contains Architecture Decision Records (ADRs) for the repository. ADRs document significant architectural decisions, context, trade-offs, and explicit directives for human developers and autonomous AI agents.
+
+## ADR Master Index
+
+| ID                                                 | Title                                                                   | Status   | Date       | Summary                                                                                                                            |
+| -------------------------------------------------- | ----------------------------------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| [0001](0001-cloudflare-production-render-jules.md) | Cloudflare as Production, Render as Jules Test Environment              | Accepted | 2026-08-24 | Production is Cloudflare Workers + Assets; Render is strictly a test environment for Google Jules debugging.                       |
+| [0002](0002-strict-zod-schema-validation.md)       | Strict Zod Schema Validation for Content Collections and API Boundaries | Accepted | 2026-08-24 | All boundary inputs (content, env vars, edge APIs) must be validated with Zod schemas and TypeScript types inferred via `z.infer`. |
+
+## ADR Lifecycle & Rules
+
+1. **Sequential Numbering:** ADR files must strictly follow `NNNN-[title].md` format (e.g. `0001-...md`, `0002-...md`).
+2. **Master Index Sync:** Every new, updated, or status-changed ADR must be reflected in the index table above.
+3. **AI Agent Directives:** Every ADR must contain a `## Directives for AI Agents` section establishing explicit `Do` and `Don't` boundaries to prevent AI agent architectural drift.
+4. **Non-Destructive Modifications:** ADRs must not be deleted or superseded without creating or linking the replacement ADR in the same change.

docs/tech-radar.md

@@ -0,0 +1,76 @@
+# Repository Tech Radar
+
+This document tracks technologies, frameworks, infrastructure patterns, and workflows used across the repository. It provides ground-truth context for human engineers and autonomous AI agents.
+
+## Quadrants & Technology Status
+
+### 1. Frameworks & Runtimes
+
+- **Adopt:**
+  - **Astro (v7+):** Primary static site generator and dynamic server-rendering framework.
+  - **TypeScript (Strict Mode):** Mandatory language choice for type-safe application logic and data schemas.
+  - **Node.js (>=22.12):** Standard runtime engine for local development, CI pipelines, and Jules test runner.
+- **Trial:**
+  - **Cloudflare Workers `@astrojs/cloudflare` adapter:** Edge adapter for serverless asset routing and pre-rendering.
+- **Assess:**
+  - **WebGPU / Native Canvas Shaders:** Evaluation for potential interactive background visuals in lab components.
+- **Hold:**
+  - **React / Vue / Svelte Component Frameworks:** Avoid client UI runtime frameworks; leverage static HTML + Vanilla Web Components to keep client JS minimal.
+
+---
+
+### 2. Infrastructure & Cloud
+
+- **Adopt:**
+  - **Cloudflare Workers + Assets:** Unified serverless deployment target for production site hosting (`wrangler.jsonc`).
+  - **Sentry (`@sentry/astro`):** Client and edge runtime monitoring and error performance tracking.
+- **Trial:**
+  - **Render Node Standalone Server (`render.yaml`):** Isolated testing environment for Google Jules debugging (see [ADR 0001](adr/0001-cloudflare-production-render-jules.md)).
+- **Assess:**
+  - **Cloudflare Vectorize / AI Workers:** Potential future integration for local semantic RAG queries.
+- **Hold:**
+  - **Deprecated Cloudflare Pages Direct Uploads:** Replaced by unified Workers-First model (`wrangler.jsonc`).
+  - **Parallel Manual Production CI Deploys:** Cloudflare Git integration owns production deployments on `main`.
+
+---
+
+### 3. Tooling & AI Workflows
+
+- **Adopt:**
+  - **Vitest:** Primary Unit & Integration testing suite.
+  - **ESLint & Prettier:** Mandatory code formatting and static analysis rules.
+  - **Husky & lint-staged:** Pre-commit hooks for automated formatting and linting verification.
+  - **Jules & Autonomous Agent Suite (Archie, Kinetic, Stratus, Palette, Sentinel, Engine, etc.):** Autonomous agent ecosystem.
+  - **MCP Servers (`mcp_config.json`):** Model Context Protocol integrations for local documentation and tooling.
+- **Trial:**
+  - **Playwright (Python/Node):** Visual verification screenshotting and E2E smoke tests.
+- **Assess:**
+  - **Codecov Bundle Analysis:** Tracking bundle sizes and coverage metrics in PR workflows.
+- **Hold:**
+  - **Commit-time Writes to Protected Main Branch:** Release scripts must create GitHub releases rather than committing version tags directly back to `main`.
+
+---
+
+### 4. Patterns & Architecture
+
+- **Adopt:**
+  - **Static-First Pre-rendering:** Pre-render pages to static HTML by default (`output: "static"`).
+  - **Zod Boundary Validation:** Validate all external content collections, environment variables, and API payloads via Zod schemas (see [ADR 0002](adr/0002-strict-zod-schema-validation.md)).
+  - **Vanilla CSS Glassmorphism:** Scoped CSS with custom properties ('Northern Lights' aesthetic); no CSS utility frameworks.
+  - **Workers-First Binding Pattern:** Uniform environment variable binding and asset routing via `wrangler.jsonc`.
+- **Trial:**
+  - **Astro View Transitions (`astro:page-load`):** Smooth client navigation with strict initialization event handler listener patterns.
+- **Assess:**
+  - **Edge Caching Header Customization:** Micro-optimizations for static asset edge cache TTL.
+- **Hold:**
+  - **Tailwind CSS / CSS Frameworks:** Banned. Use Vanilla scoped CSS only.
+  - **Any / `@ts-ignore` Type Bypasses:** Banned. All code must pass strict TypeScript checks.
+
+---
+
+## Ring Definitions
+
+- **Adopt:** High confidence, production-proven in this repository. Default choice for new work.
+- **Trial:** High potential with low risk. Ready for isolated usage in minor features or experimental routes.
+- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production code.
+- **Hold:** Phasing out or proven problematic in our setup. Banned for new work.