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. Red-Green-Refactor Lifecycle:
   • Write tests in test/*.test.js using Node's native test runner (node:test, node:assert/strict).
   • Test inputs before implementing filters, data loaders, or template macros.
2. Adversarial Test Coverage Required:
   • Data & Configuration: Test that missing required environment variables (e.g. SITE_DOMAIN) throw fatal errors.
   • Filters: Test edge cases: empty strings, undefined values, single-word inputs, massive word counts, non-date objects.
   • 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. Execution Invariant:
   • Always run npm test before committing. All tests must pass cleanly with 0 failures.