alehar9320 · Sep 1, 2026 · coderabbitai · Sep 1, 2026
diff --git a/.Jules/archie.md b/.Jules/archie.md
@@ -0,0 +1,3 @@
+2026-09-01 - Codify Feature Flags & Establish Tech Radar
+Learning: Lack of explicit ADR master index and centralized Tech Radar allowed implicit patterns (like feature flag synchronization and prohibited CSS frameworks) to drift across multi-agent contributions.
+Action: Enforce ADR 0002 for all feature flag modifications and maintain `docs/tech-radar.md` rings to guide autonomous agent decisions.
diff --git a/docs/adr/0002-feature-flags-schema-validation.md b/docs/adr/0002-feature-flags-schema-validation.md
@@ -0,0 +1,33 @@
+# 0002. Feature Flags Schema Validation & Decoupled Configuration
+
+- **Status:** Accepted
+- **Date:** 2026-09-01
+- **Deciders:** Autonomous Architect (Archie) / Repository Analysis
+
+## Context
+
+The repository contains multiple autonomous AI agents (such as Apex, Kinetic, Aurora, and Jules) shipping isolated micro-features and UI experiments. To isolate experimental features without modifying global routing, runtime layout logic, or incurring runtime build breaks, feature toggles are stored in `src/content/flags/config.json`.
+
+However, modifying or adding feature toggles in `config.json` without updating Content Collections validation schemas breaks content schema unit tests and type inference.
+
+## Decision
+
+All runtime feature flags must be declared centrally in `src/content/flags/config.json` and synchronized with the Zod schema in `src/content.config.ts`.
+
+Feature flags must follow standard boolean property defaults (e.g., `z.boolean().default(false)`).
+
+## Consequences & Tradeoffs
+
+- **Positive:** Ensures strict type safety, prevents runtime undefined flag access, and enables safe experimental isolation for all autonomous agents.
+- **Negative / Risks:** Developers and AI agents must update two files (`config.json` and `src/content.config.ts`) when adding new flags.
+- **Adoption Readiness:** Pattern is already fully operational in `src/content/flags/` and `src/content.config.ts`.
+
+## Directives for AI Agents
+
+- **Do:**
+  - Define new feature flags in `src/content/flags/config.json`.
+  - Synchronize any new feature flag with `src/content.config.ts` under the `flags` collection schema using `z.boolean().default(false)`.
+  - Use feature flags to isolate experimental routes, micro-interactions, or visual enhancements.
+- **Don't:**
+  - Never add a flag to `config.json` without adding its Zod schema definition to `src/content.config.ts`.
+  - Never remove existing feature flags without checking component references across `src/`.
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -0,0 +1,10 @@
+# Architecture Decision Records (ADRs)
+
+Architecture Decision Records (ADRs) document key strategic and architectural decisions made for this repository. They describe the context, rationale, trade-offs, and enforceable Directives for AI Agents to prevent technical drift.
+
+## Index
+
+| ADR                                                  | Title                                                     | Status   | Date       |
+| :--------------------------------------------------- | :-------------------------------------------------------- | :------- | :--------- |
+| [0001](./0001-cloudflare-production-render-jules.md) | Cloudflare as production, Render as Jules test env        | Accepted | 2026-08-24 |
+| [0002](./0002-feature-flags-schema-validation.md)    | Feature Flags Schema Validation & Decoupled Configuration | Accepted | 2026-09-01 |
diff --git a/docs/tech-radar.md b/docs/tech-radar.md
@@ -0,0 +1,61 @@
+# Repository Tech Radar
+
+## Quadrants
+
+### 1. Frameworks & Runtimes
+
+- **Adopt:**
+  - **Astro (v7.x):** Primary static site generator and SSG framework for all core pages.
+  - **TypeScript:** Strict type system for all application logic and utilities.
+  - **Cloudflare Workers (`@astrojs/cloudflare`):** Production rendering and edge serverless target.
+- **Trial:**
+  - **Node Standalone Adapter (`@astrojs/node`):** Used exclusively for Jules test debugging environment on Render.
+- **Assess:**
+  - **Wasm / Edge Module Extensions:** Evaluating potential client/edge compute extensions.
+- **Hold:**
+  - **React / Vue / Svelte Component Frameworks:** Keep site lightweight using zero-framework Vanilla JS/CSS islands.
+
+### 2. Infrastructure & Cloud
+
+- **Adopt:**
+  - **Cloudflare Pages / Workers:** Production hosting environment (`wrangler.jsonc`).
+  - **Sentry (`@sentry/astro`, `@sentry/cloudflare`):** Error logging and application performance monitoring.
+- **Trial:**
+  - **PostHog (`posthog-js`):** Web analytics and feature engagement tracking.
+- **Assess:**
+  - **Cloudflare KV / Vectorize:** Autonomous AI assistant memory context storage.
+- **Hold:**
+  - **Heavy Node Origin Hosting:** Production Node dynamic servers (migrated to Cloudflare edge).
+
+### 3. Tooling & AI Workflows
+
+- **Adopt:**
+  - **Vitest:** Unit testing framework for utility functions and content validation.
+  - **Prettier & ESLint:** Code formatting and static linting guardrails.
+  - **Jules & Autonomous Agent Fleet:** Multi-agent autonomous workflow operating under agent-specific directives.
+- **Trial:**
+  - **Playwright:** End-to-end frontend visual verification.
+- **Assess:**
+  - **MCP (Model Context Protocol):** Standardized tools and prompts interface for AI context extensions.
+- **Hold:**
+  - **Manual Deployment Scripts:** Replaced by automated GitHub Actions CI/CD workflows.
+
+### 4. Patterns & Architecture
+
+- **Adopt:**
+  - **Feature Flags via Content Collections:** Decoupled JSON toggles validated via Zod schemas (`src/content.config.ts`).
+  - **Vanilla CSS Glassmorphic Styling:** Scoped CSS variables using 'Northern Lights' design language without external CSS frameworks.
+  - **Explicit Image Dimensions:** `width` and `height` declared on visual assets for zero Cumulative Layout Shift (CLS=0).
-  - **Explicit Image Dimensions:** `width` and `height` declared on visual assets for zero Cumulative Layout Shift (CLS=0).
+  - **Explicit Image Dimensions:** `width` and `height` declared on visual assets to reduce image-induced Cumulative Layout Shift (CLS).
-  - **Explicit Image Dimensions:** `width` and `height` declared on visual assets for zero Cumulative Layout Shift (CLS=0).
+  - **Explicit Image Dimensions:** `width` and `height` declared on visual assets to reduce image-induced Cumulative Layout Shift (CLS).
+- **Trial:**
+  - **Pointer-Based Edge Stream Parsing:** High-performance buffer scanning in Cloudflare Worker SSE endpoints.
+- **Assess:**
+  - **Canvas Lab Isolation (`src/pages/lab/`):** Dedicated route sandbox for interactive 3D/canvas visual features.
+- **Hold:**
+  - **Tailwind CSS / CSS Utility Frameworks:** Prohibited to maintain pure CSS standard performance.
+
+## Rings
+
+- **Adopt:** High confidence, production-proven in this repo. Default choice for new work.
+- **Trial:** High potential with low risk. Ready for isolated usage in minor features or scripts.
+- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production code.
+- **Hold:** Phasing out or proven problematic in our setup. Do not use for new work.