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
• Perform a web search to find out about other AI news published in the last seven days that have to be included, such as major AI model releases, new AI apps, and technological novelties pertaining to AI. Update the links collection with the web search results. Aim to include no more than 5 new news items.

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

Ask me if I want to work on a post for the newsletter. If I confirm “yes”, proceed with the following:

In folder _posts, find posts with published: false. Select 2 posts that are most related to the generated AI Signals post you have just created. Estimate these posts’ completion status, the required improvements, and provide me with the most important details on these two posts and the required changes in a concise bullet point list.

Allow me to select the post we will work on next to further improve and publish. When I choose a post, please rename its filename to reflect today’s publication, commit the post if it is not committed yet to the Git with a commit message “post slug draft” with the slug string substituted by the post title, enhance the post readability, and add important technical details and code, if required for topic understanding. Create a new Flux cover (Option 1) and thumbnail for the chosen post. When finished, report on the post changes and describe the generated image.

Fact-check the improved post, fix the mistakes and further enhance it if needed. Check that the included URLs are not pay-walled (if they are, find the open, published URLs from the last week). Remove the news that did not happen this week, and further rewrite the post without these outdated signals. Confirm if the post is publishable.

Finally, create a short, two-paragraph newsletter e-mail message, starting with the first paragraph introducing the AI signals post and the second paragraph describing the improved post, in a style that incites readers to open it. Make sure the second paragraph flows seamlessly from the first. Print the generated two-paragraph newsletter and save it to the file with the current date and a mobile-friendly e-mail subject line that relates to both topics at once and also has the estimated highest opening rate.

Make sure to:

1. Consider only the unpublished posts that do not have the Weekly tag.
2. Fix the tags section in the frontmatter of the edited posts. You can find the available tags in the tag folder.

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.

Wrapping up

When finished, make sure that all included sources are published in the last seven days; otherwise, remove them and rewrite the post to exclude any reference to the related claims. All stated claims must be fact-checked, and if needed, the post must be corrected to have accurate details.

Attempt to structure the AI signals post into sections, as in the previous post in the file _posts/2026-03-20-agentic-everything.md

Make sure that the keywords, excerpt, TLDs, and the introduction and conclusion sections reflect the main AI signals in the post. Make these sections sharp and avoid general fluff. Add details instead, but keep it brief.