diff --git a/_index_template.html b/_index_template.html index 20836ee..91e1ff7 100644 --- a/_index_template.html +++ b/_index_template.html @@ -120,6 +120,13 @@
diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..c99b49e --- /dev/null +++ b/agents.md @@ -0,0 +1,164 @@ +# agents.md — Tinqs Blog Agent Guide + +This file teaches AI agents (Pi, Cursor, Claude Code) how to work with the Tinqs blog repo. Read it before making any changes. + +## Blog architecture + +``` +tinqs-ltd/blog/ +├── _template.html # Post shell — wraps a single blog post +├── _index_template.html # Listing shell — blog index page +├── build.js # Zero-dep Node script: posts/*.md + templates → *.html +├── posts/ # Markdown posts with YAML frontmatter +│ ├── agent-harness.md +│ ├── agentic-workflow.md +│ └── ... +├── *.html # Generated output (never hand-edit regular posts) +├── pi-flow-native-brain.html # Hand-authored HTML post (SVGs + tables) +├── agents.md # This file +└── skills/ # Reusable skill playbooks +``` + +### Two kinds of posts + +1. **Regular posts** — Markdown in `posts/*.md`, built via `node build.js` into `*.html`. Always edit the `.md`, never the `.html`. +2. **Hand-authored HTML posts** — `pi-flow-native-brain.html` is the only one. It contains inline SVGs and styled tables that build.js can't emit. Edit the HTML directly, never create a `.md` for it. Cards for hand-authored posts are hardcoded in `_index_template.html`. + +### Build pipeline + +```bash +node build.js # reads posts/*.md → generates *.html + index.html +``` + +`build.js` has zero npm dependencies — pure Node.js built-ins. It handles: +- YAML frontmatter parsing +- Minimal markdown → HTML conversion (headings, bold/italic, inline code, fenced code blocks, lists, figures, links, hr) +- `` / `` blocks for raw HTML passthrough +- Lead paragraph separation (first paragraph after frontmatter → `.post__lead`) +- Date formatting +- Index page generation (newest-first sorted cards) + +## How to add a post + +### Regular markdown post + +Create `posts/