# Technical Blog Project Standards & Architectural Specification

This document defines the authoritative engineering, design, templating, and security standards for this technical publication codebase. All new implementations, pull requests, refactors, and debugging tasks must conform to these rules.

---

## 1. User Content Sovereignty (Highest Priority)

1. **User Edits Are Absolute Ground Truth:**
   - The user's custom writing, post titles, tags, navigation labels, terminology, and naming choices strictly supersede any boilerplate, skill instructions, or sample mockups (`sample-designs/*`).
2. **No Unsolicited Modifications:**
   - Never overwrite, sanitize away, or rename user-authored text without explicit instruction.
3. **Mandatory Clarification Gate:**
   - Inconsistencies or typos in user writing must be flagged for clarification rather than unilaterally changed.

---

## 2. Strict Test-Driven Development (TDD) & Adversarial Verification

1. **Test-First Invariant (Tests Before Code):**
   - Automated test cases in `test/*.test.js` MUST ALWAYS be written and established *before writing or modifying any functional code* (filters, templates, server routes, ingestion logic, build scripts).
   - Never implement or modify production code prior to establishing tests.
2. **Mandatory Adversarial Testing:**
   - Every functional implementation must include adversarial tests designed to actively falsify assumptions:
     - Missing or malformed configuration (e.g., unset `SITE_DOMAIN` must throw).
     - Corrupt or unexpected inputs (empty strings, `null`, `undefined`, unexpected types, HTML injections, path traversals, giant payloads).
     - Boundary values and edge cases.
     - Design rule violation assertions (0 instances of forbidden CSS patterns).
     - Link and anchor integrity checks.
3. **Pre-Presentation Verification Gate:**
   - Before presenting the final output to the user, run `npm test`.
   - All test cases must pass before presenting the final output. Delivering unverified or failing code is strictly forbidden.

---

## 3. Design System & CSS Specification

Strict adherence to `sample-designs/design-specification.md` is mandatory.

### 3.1 Color Palette & Token Variables
All colors must use standard CSS custom properties defined in `src/assets/css/tokens.css`:
- Canvas: `var(--bg-canvas)` (`#0d0f12`)
- Surface: `var(--bg-surface)` (`#121417`)
- Elevated: `var(--bg-elevated)` (`#1c1f26`)
- Borders: `var(--border-color)` (`#2b303b`)
- Text: `var(--text-primary)` (`#e0e6f0`), `var(--text-muted)` (`#8a95a5`)
- Accents: `var(--accent-cyan)` (`#00f0ff`), `var(--accent-green)` (`#00e676`), `var(--accent-amber)` (`#ffb700`), `var(--accent-red)` (`#ff5252`)

### 3.2 Hard Anti-Patterns (Forbidden)
- **NO Glassmorphism:** Never use `backdrop-filter: blur(...)`.
- **NO Drop Shadows or Glows:** `box-shadow: none;` and `text-shadow: none;` only.
- **NO Gradients:** Never use `linear-gradient`, `radial-gradient`, or `conic-gradient`. Flat solid surfaces only.
- **NO Rounded Bubbles:** `border-radius` is strictly capped between `0px` and `4px` maximum.
- **NO Floaty / Delayed Transitions:** Hover and state transitions must be instant binary snaps (`transition: none;` or `transition: 0s;`).

### 3.3 Typography & Modularity
- UI & Code: `IBM Plex Mono`, `JetBrains Mono`.
- Body Prose: `Inter`.
- CSS Modularity: Zero monolithic inline `<style>` tags in HTML. Decompose styles into `tokens.css`, `reset.css`, `layout.css`, and `components/*.css`.

---

## 4. Templating & Eleventy Architecture

1. **Layout Inheritance (Nunjucks):**
   - Root layout: `src/_includes/layouts/base.njk`.
   - Post layout: `src/_includes/layouts/post.njk`.
   - Page layout: `src/_includes/layouts/page.njk`.
   - Modular reusable partials in `src/_includes/partials/` (`global-bar.njk`, `hero-tile.njk`, `post-card.njk`, `stats-sidebar.njk`, `code-box.njk`, `footer.njk`).
2. **Collection Invariants:**
   - `collections.posts`: Must filter through `isPostPublic(post)` (excluding both `draft: true` and `hidden: true`) and sort using `postComparator` (prioritizing pinned/featured posts, then chronological descending).
   - `collections.tagList`: Must filter through `isPostPublic(post)` so draft or unlisted tags never leak into public category filters.
3. **Hidden / Unlisted Post Contract:**
   - When frontmatter specifies `hidden: true`:
     - Excluded from public lists, indices, and tag aggregates.
     - Static page STILL compiles to `/posts/<slug>/index.html` and is accessible via direct URL.
     - Emits `<meta name="robots" content="noindex, nofollow">` in `<head>` to prevent search indexing.

---

## 5. Obsidian Content & Frontmatter Contract

1. **Frontmatter Schema:**
   ```yaml
   title: "Article Title"          # Required: string (>= 5 chars)
   date: 2026-09-23                 # Required: ISO YYYY-MM-DD (or 'created')
   tags: ["#tag1", "#tag2"]        # Required: non-empty YAML array
   excerpt: "Article summary..."   # Required: string (>= 20 chars)
   readingTime: "5 MIN READ"        # Optional: explicit override
   draft: false                    # Optional: boolean
   hidden: false                   # Optional: boolean (share by link only)
   pinned: false                   # Optional: boolean (prioritized to top)
   featured: false                 # Optional: boolean (featured pillar)
   ```
2. **Obsidian Syntax Normalization:**
   - Wikilinks: `[[target-slug|Custom Label]]` $\rightarrow$ `[Custom Label](/posts/target-slug/)`.
   - Wikilinks simple: `[[target-slug]]` $\rightarrow$ `[target-slug](/posts/target-slug/)`.
   - Attachments: `![[image.png]]` $\rightarrow$ `![image](/assets/images/posts/image.png)`.
   - Terminal alert callouts for `> [!NOTE]`, `> [!WARNING]`, etc.

---

## 6. Server & Security Invariants

1. **Native Runtime:**
   - `server.js` uses native Node standard library (`node:http`, `node:fs`, `node:path`) with zero external runtime dependencies.
2. **Security Headers on All Responses:**
   - `X-Content-Type-Options: nosniff`
   - `X-Frame-Options: DENY`
   - `Referrer-Policy: strict-origin-when-cross-origin`
3. **Path Traversal Defense:**
   - Sanitize all requested file paths using `path.resolve` and verify the resolved path remains rooted inside the target directory. Block `..` and malicious slug sequences.
4. **Healthcheck Telemetry:**
   - `/healthz` and `/health` must respond with HTTP 200 JSON `{ status: "ok", uptime: <seconds> }`.

---

## 7. Defensive Programming & Error Prevention

1. **Input Guarding:**
   - Never assume incoming arguments have expected shape. Always guard against `null`, `undefined`, non-objects, and primitive inputs (e.g., `item.data ?? item`).
2. **Clean Container Contracts:**
   - Container images must use `node:22-alpine`.
   - Dynamic entrypoint (`entrypoint.sh`) must build markdown on boot, handle optional watcher (`WATCH=true`), and execute server as PID 1 (`exec node server.js`).