AGENTS.md — Codex CLI Blogging Automation Rules

This repository is a Jekyll-based blog hosted on GitHub Pages.

Codex CLI may assist with blog creation, validation, and media generation under the rules below. Automation is meant to reduce friction — not replace editorial judgment.

0. Global safety & scope rules (non-negotiable)

• Operate only inside this repository.
• Never access, print, or modify secrets, tokens, or credentials.
• Never publish (git push) unless explicitly instructed.
• Prefer minimal, explainable diffs over large rewrites.
• Preserve the author’s tone, structure, and intent.
• If required information is missing, stop and ask rather than guessing.
• Always show a clear git diff and list of changed/created files.

MCP Tools

News link builder (Weekly AI Signals)

Purpose: fetch fresh, English, open-access AI news links for weekly posts.

Tool name: build_weekly_ai_links Server: DaehnhardtNews (_scripts/mcp/mcp_news_server.py)

Outputs (relative to repo root):

• _scripts/mcp/drafts/links/core_signals.txt (latest 5 “core signals” links)
• _scripts/mcp/drafts/links/apps_and_tools.txt (latest 5 “apps & tools” links)

Default parameters:

• days=7
• core_count=5
• apps_count=5
• language="eng"

Policy:

• Prefer domains in _scripts/mcp/allowlists/news_domains.txt
• Soft-allow unknown domains if needed, but report them in logs/notes
• Block non-English TLDs (see _scripts/mcp/blocklists/news_domains.txt if present)

1. Post types (always decide first)

Every task must explicitly or implicitly select one post type.

Post Type A — Technical Posts

Examples:

• MCP tutorials
• Python / AI tooling deep dives
• Workflow or infrastructure articles

Characteristics:

• No web search required
• May include Python code blocks
• Uses Flux image generation
• Structure follows a canonical technical layout

Post Type B — Weekly AI Signals

Examples:

• “Signals from the AI Supply Chain”
• Weekly AI news & infrastructure roundups

Characteristics:

• Requires external sources
• Summarisation + interpretation, not speculation
• Cover image: user choice — (1) Flux image generation, or (2) default Weekly Signals image (§6.4)
• Strict citation discipline
• Reusable “Signals” section pattern

Rule: If Post Type B is requested and no sources or web tool are available, Codex must stop and ask for links or propose search queries.

Post Type C — Series

Examples:

• Multi-part Git workflows
• AI image generation in practice
• Neural network architecture foundations

Characteristics:

• Establish a series page under series/<slug>.md with permalink: /series/<slug>/
• Assign series and series_order to each included post
• Order posts from foundational concepts to advanced topics
• Include series navigation via _includes/series.html (already wired in /_layouts/post.html)
• Show unpublished posts as “Coming Soon”

Workflow: 1) Create or update series/<slug>.md using the same structure as series/codex-cli.md 2) Add series: "<Series Name>" and series_order: <n> in each post’s front matter 3) Ensure series_order reflects a learning sequence (beginner → advanced) 4) Do not add ` ` to posts (use _includes/series.html) 5) Confirm the series appears in series/index.md (auto via series metadata)

2. Canonical layout reference (single source of truth)

When creating or editing posts, follow the exact front-matter structure and ordering used in:

_posts/2025-12-27-the-missing-manual-for-flux-1.md

Rules

• Copy the same front-matter keys and ordering
• Adjust values only
• Do not invent new fields unless they already exist in the reference
• Optional fields are allowed only if present in the reference post

3. Creating a new post (shared rules)

File location

_posts/YYYY-MM-DD-<slug>.md

Slug rules

• lowercase
• hyphen-separated
• ASCII only

Example:

"A Gentle Introduction to MCP"
→ 2026-01-15-a-gentle-introduction-to-mcp.md

Default front-matter rules

• published: false unless explicitly requested otherwise
• image, thumb_image, and image_title must be present
• No placeholder text unless explicitly unavoidable (and must be reported)

4. Tags: assignment, validation, and creation

Tag pages live in:

tag/

Rule A — Prefer existing tags

• Read all existing tags from tag/*.md
• Tags in posts must correspond to existing tag files whenever possible

Rule B — Content-driven tagging

• Validate user-provided tags against post content
• Remove irrelevant tags
• Add missing but clearly relevant tags

Rule C — Creating a new tag (only if necessary)

If no suitable tag exists:

Create tag/<slug>.md (lowercase filename) with:

---
layout: tag
title: "Tag: <Tag>"
keywords: "<comma-separated keywords>"
tag: <Tag>
search: true
definition: "<1–3 sentence, friendly dictionary-style definition>"
---

Do not create speculative, overlapping, or redundant tags.

5. Python code blocks (Technical posts only)

What to check

• All fenced blocks marked:

Validation method

• Extract each block into a temporary .py file

• Run:

  python -m py_compile <file>
  

Behaviour

• If code fails:

  • Report snippet index and error
  • Do not silently fix code

• If code passes:

  • Report success

6. Image generation workflow (shared)

6.1 Main image — Flux

Use:

_scripts/image_generation/flux_pipe_args.py

Required arguments:

• --prompt
• --out

Standard output path:

images/ai_art/flux/<slug>.jpg

Recommended defaults:

• size: 1024 × 1024
• steps: 4
• guidance: 0.0

Example:

python _scripts/image_generation/flux_pipe_args.py \
  --prompt "<post-specific image prompt>" \
  --out "images/ai_art/flux/<slug>.jpg"

### 6.4 Flux prompt templates (Weekly signals covers)

Use one of these prompt structures and swap the subject for the post theme. Keep prompts short and structural. Preferred choice is #1 unless specified.

1) Editorial Default (preferred)
`[Subject], clean editorial illustration, modern technology theme, calm and human-centred, soft blue and green colour palette with warm accents, balanced composition, subtle depth, professional magazine style, non-dystopian, no text, no logos, square`

2) Conceptual Systems View
`[Subject], conceptual editorial illustration, abstract but readable tech systems, restrained colour palette, soft contrast, clean geometry, professional magazine style, calm tone, no text, no logos, square`

3) Friendly Technical
`[Subject], friendly technical illustration, clear structure and visual logic, soft lighting, calm colours, approachable design, editorial style, non-dystopian, no text, square`

4) Human-in-the-Loop Emphasis
`[Subject], editorial illustration showing human control alongside technology, calm atmosphere, soft blue and neutral tones, thoughtful composition, professional tech magazine style, no logos, no text, square`

5) Gentle Motion / Progress
`[Subject], modern editorial tech illustration, subtle sense of progress and motion, clean shapes, vivid but controlled colours, optimistic and grounded, professional magazine style, no text, square`

6.2 Thumbnail generation

Use:

_scripts/image_generation/make_thumbnail.py

Standard output path:

images/thumbnails/<slug>.jpg

Example:

python _scripts/image_generation/make_thumbnail.py \
  --in images/ai_art/flux/<slug>.jpg \
  --out images/thumbnails/<slug>.jpg \
  --size 300

6.3 Front-matter update

After generation, update:

image: "https://daehnhardt.com/images/ai_art/flux/<slug>.jpg"
thumb_image: "https://daehnhardt.com/images/thumbnails/<slug>.jpg"
image_title: "Flux: <shortened image prompt>"

6.4 Weekly Signals cover image (user choice)

For Post Type B — Weekly AI Signals, the user may choose:

Option 1 — Flux image generation

• Generate a square image with Flux (§6.1), then thumbnail (§6.2), then set front matter per §6.3.

Option 2 — Default Weekly Signals image

• Use the following in front matter (no Flux or thumbnail run):

image: "https://daehnhardt.com/images/ai_art/gemini/nano_banana/ai_signals_mail_dog.jpg"
image_title: "Nano Banana via Gemini. Prompt: A robotic but friendly dog brings a huge white envelope with a written 'AI Signals' on it. clean editorial illustration, modern technology theme, calm and human-centred, soft blue and green colour palette with warm accents, balanced composition, subtle depth, professional magazine style, square."
thumb_image: "https://daehnhardt.com/images/thumbnails/ai_signals_mail_dog.jpg"

If the user does not specify a choice, ask which option to use before creating the post.

7. Workflow A — Technical posts

Steps Codex must follow

1. Read canonical layout reference (§2)
2. Create or update post in _posts/
3. Validate and adjust tags (§4)
4. Generate Flux image + thumbnail (§6)
5. Update front-matter image fields
6. Check Python code blocks (§5)

7. Report:

   • files changed/created
   • Python check results
   • git diff

8. Workflow B — Weekly AI Signals (requires web links)

When the user requests a Weekly AI Signals post:

1) Run the MCP tool first

• Call: build_weekly_ai_links(days=7, core_count=5, apps_count=5, language="eng")
• Confirm both files exist:
  • _scripts/mcp/drafts/links/core_signals.txt
  • _scripts/mcp/drafts/links/apps_and_tools.txt

2) Read and validate the links

• Each file must contain 1 URL per line
• Remove duplicates across both files
• If fewer than 4 total links are generated, stop and report the issue

3) Produce the Weekly post draft in _posts/

• Use the Weekly template post layout (example: “Signals from the AI Supply Chain”)
• Generate 5 title variations, rank by estimated open rate, and use the top-ranked title
• Include:
  • warm reflective intro
  • 4–6 numbered signals (core_signals first)
  • optional “Apps & Tool Updates” section (from apps_and_tools)
  • closing reflection + a question
• Include a favicon+link block for each URL
• Do NOT invent facts: only summarise what is supported by the linked sources

4) Tags and metadata

• Must include Weekly
• Add/adjust tags using /tag/*.md definitions
• Add keywords/excerpt/tldr consistent with the content

5) Images (§6.4)

• User choice: (1) Flux image generation + 300×300 thumbnail, then set front matter per §6.3; or (2) use the default Weekly Signals image and set image, image_title, and thumb_image per §6.4 Option 2.
• If the user has not specified which option, ask before generating the post.

6) Output

• Show a file list of all created/modified files
• Provide a short checklist of what was done and any warnings (unknown domains, etc.)

Source rules (critical)

• No claims without sources
• Do not invent facts, numbers, or quotes
• Prefer open-access sources
• If a source is paywalled, clearly label it or pair with an open alternative

Structure requirements

• Intro reflection (Elena tone)
• 4–6 numbered core signals
• Optional “Apps & Tool Updates”

• Each signal includes:

  • favicon + link block
  • concise summary
  • Why This Matters
• Closing reflection

Source tracking

Save a machine-readable list:

drafts/sources/<slug>.yml

Each entry should include:

• title
• url
• publisher
• date (if known)
• short note

9. Allowed commands

Codex may run:

• ls, find, cat, grep, sed
• python -m py_compile
• python _scripts/image_generation/flux_pipe_args.py
• python _scripts/image_generation/make_thumbnail.py

Codex may not:

• push commits
• delete historical posts
• mass-edit unrelated files
• fabricate sources or citations

10. Definition of “done”

A task is complete when:

• Post exists with correct layout and tone
• Tags are valid and tag files exist
• Image and thumbnail are generated and linked
• Python snippets compile (if present)
• Sources are cited correctly (Weekly posts)
• Changes are visible via git diff

Guiding principle

Automation should make the work lighter — never louder, faster, or less thoughtful.

When in doubt: pause, explain, and ask.