blog/.agents/rules/blog-system.md

Technical Blog System Rules & Architecture Directives

1. Core Invariant: User Content Sovereignty (Highest Priority)

1. User Edits Are Absolute Ground Truth:
   • The user's edits, custom writing, post titles, navigation labels, terminology, and naming choices are the absolute highest level of truth in this codebase.
   • They strictly take precedence over any background content description, sample design mockup (sample-designs/*), skill instructions, or default boilerplate.
2. Strict Prohibition on Unsolicited Rewriting or Renaming:
   • You must NEVER revert, alter, overwrite, or substitute user-authored text, titles, navigation labels, tags, or naming conventions unless the user directly and explicitly requests that specific modification.
   • Do not reintroduce removed text or names from prior mockups or commits.
3. Mandatory Clarification Gate:
   • If you notice a potential inconsistency, typo, or naming ambiguity in user-authored content, you must NOT unilaterally modify it.
   • You must ask the user for specific clarification before altering any user-authored writing or naming.
4. Sample Designs Are Layout References Only:
   • Files in sample-designs/ serve solely as visual, CSS, and structural layout references.
   • Never extract or re-inject titles, domain names, service labels, or technical copy from sample-designs/ into active templates or site data without explicit instruction.

---

2. Pedagogical Explanations (Interactive Learning)

1. Explain the Code: Whenever creating or refactoring code (Eleventy configuration, Nunjucks templates, CSS modules, build scripts), provide a clear, educational breakdown.
2. Break Down Key Concepts: Explain why a particular Eleventy filter, Nunjucks tag, or CSS variable structure was used so the user learns the foundational concepts.
3. No Magic: Avoid opaque or overly clever abstractions; prioritize readable, idiomatic code with commentary explaining tricky points.

---

3. CSS Architecture & Isolation

1. Zero Monolithic Inlines: Do not inject raw <style> blocks into HTML templates.
2. Modular File Structure:
   • Put global tokens in src/assets/css/tokens.css.
   • Put reset and base typography in src/assets/css/reset.css.
   • Put layout structures (tiling layout, split grids) in src/assets/css/layout.css.
   • Put scoped component styles in src/assets/css/components/<component-name>.css.
3. Design System Token Integrity: Always use CSS custom properties defined in 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)
4. Hard Aesthetic Constraints:
   • No glassmorphism (backdrop-filter).
   • No box-shadows or glows.
   • No linear/radial gradients.
   • Border radius strictly bounded between 0px and 4px.
   • Transition durations set to none or 0s for instant snap responses on hover.

---

4. Templating Guidelines (Eleventy + Nunjucks)

1. Layout Hierarchy:
   • Root template: src/_includes/layouts/base.njk (contains HTML structure, <head>, metadata, scripts, stylesheets).
   • Content layouts: src/_includes/layouts/post.njk (for articles), src/_includes/layouts/page.njk (for landing/catalog).
2. Component Partials:
   • Isolated partials in src/_includes/partials/ (global-bar.njk, hero-tile.njk, post-card.njk, stats-sidebar.njk, code-box.njk, footer.njk).
   • Pass dynamic data via Nunjucks macros or contextual variables.

---

5. Obsidian Content Pipeline

1. Frontmatter Specification: Every post ingested from Obsidian must adhere to:

   title: "Article Title"
   date: YYYY-MM-DD
   tags: ["#tag1", "#tag2"]
   excerpt: "Single paragraph summary"
   readingTime: "X MIN READ"
   draft: false
   

2. Obsidian Normalization:
   • Wikilinks [[slug]] or [[slug|Label]] must be transformed into standard web URLs (/posts/slug/).
   • Callout blocks (> [!NOTE], > [!WARNING], etc.) must render as terminal-style alert callouts.
   • Images must be processed into src/assets/images/posts/ and linked via standard <img> or Markdown image syntax.

---

6. Test-Driven Development (TDD) & Adversarial Verification

1. Strict Pre-Implementation Testing (Tests Before Functional Code):
   • Test cases MUST ALWAYS be written in test/*.test.js before writing or modifying any functional code (filters, templates, server routes, ingestion pipeline, data loaders, scripts).
   • Never implement or modify functional or production code prior to writing and establishing corresponding automated tests.
2. Mandatory Adversarial Test Coverage:
   • Standard behavior for any functional change MUST ALWAYS include adversarial testing specifically designed to stress assumptions and break the system:
     • Data & Configuration: Test that missing required environment variables (e.g. SITE_DOMAIN) throw fatal errors.
     • Filters & Logic: Test edge cases: empty strings, undefined/null values, unexpected types, single-word inputs, massive word counts, non-date objects.
     • Security & Integrity: Test path traversals, malformed JSON, unauthorized tokens, malicious payloads.
     • Content Schemas: Validate all Markdown files in src/posts/ against frontmatter schemas.
     • Design Spec Compliance: Automate regex/AST assertions on src/assets/css/ ensuring zero violations of the "Do Not Use" list (backdrop-filter, box-shadow, text-shadow, gradients, floaty transitions).
     • Link & Anchor Integrity: Verify that every compiled page has zero broken internal links and that all Table of Contents anchor links resolve to valid heading IDs.
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. Presenting unverified output or code with failing tests is strictly prohibited.