tinqs/blog

Files

T

ozan bf42a76cf9 refactor: hand-authored pi-flow post + consolidated agents.md

- pi-flow-native-brain is now hand-authored HTML (direct SVGs + styled
  tables; no build.js passthrough needed)
- Card hardcoded in _index_template.html above {{CARDS}}
- Removed posts/pi-flow-native-brain.md (build.js no longer touches it)
- New agents.md: consolidated agent guide for the blog repo
  (blog architecture, build pipeline, adding posts, styling rules,
  writing guide, deploy instructions, skills reference)
- Removed old skills/blog.md (content migrated to agents.md)

2026-06-03 02:47:06 +01:00

6.4 KiB

Raw Blame History

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

Regular posts — Markdown in posts/*.md, built via node build.js into *.html. Always edit the .md, never the .html.
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

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/<slug>.md:

---
title: "Post Title — with optional subtitle"
slug: url-friendly-slug
date: "2026-06-03"
description: "Full meta description for SEO (150-160 chars ideal)."
og_description: "Shorter OG/Twitter description (optional)."
og_image: "https://www.tinqs.com/img/og-cover.jpg"
excerpt: "Card text shown on the blog index page."
author: "Ozan Bozkurt"
author_initials: "OB"
author_role: "CTO & Developer, Tinqs"
---
First paragraph becomes the lead. Keep it punchy — two sentences max.

Everything after the first blank line is the post body. Use standard markdown.

Then:

node build.js    # generates <slug>.html + rebuilds index.html
git add posts/<slug>.md <slug>.html index.html
git commit -m "post: <title>"

Hand-authored HTML post

Copy pi-flow-native-brain.html as a template. Keep the <style> block and nav/footer wrapper. Key rules:

Always add a card to _index_template.html so it appears on the listing page
Never create a corresponding .md in posts/ — build.js will overwrite it
Use the same class structure: .post, .post__title, .post__body, etc.

Adding a card for a hand-authored HTML post

In _index_template.html, add before {{CARDS}}:

    <a href="your-slug" class="blog-card">
      <span class="blog-card__date">3 June 2026</span>
      <h2 class="blog-card__title">Your Title</h2>
      <p class="blog-card__excerpt">Card excerpt text.</p>
      <span class="blog-card__read">Read &rarr;</span>
    </a>

Styling

Three layers (cascade order)

../style.css — external, served by Git Studio. Nav, footer, base typography, --c-accent: #c9935a. Never edit.
<style> in _template.html — post-page overrides (inline, at end of <head>)
<style> in _index_template.html — index-page overrides

The inline <style> blocks come AFTER the ../style.css link, so same-specificity rules win by cascade order. No !important needed.

Adding a style rule

Open _template.html (or _index_template.html for listing-only styles)
Find the <style> block at end of <head> (marked with /* ── Team guide aesthetic ── */)
Add your rule using the existing palette:
- Amber #c9935a (brand anchor), gold #f59e0b (emphasis)
- Blue #38bdf8 (links, pills), purple #a855f7 (h3, hover)
- Dark #0a0e14 (code bg), border #2a3340
node build.js to regenerate
Verify: grep "your-selector" *.html

Never

Edit ../style.css (outside this repo)
Hand-edit generated *.html (build.js clobbers them)
Restyle .nav, .footer, or mobile menu (belongs to parent site)
Introduce new colours without a strong reason
Add external font loads, CDN deps, or @import

Post structure (writing guide)

Good technical posts follow this pattern:

Lead paragraph — what this is about, one punchy sentence
The hook — why it matters, what problem it solves
How it works — concrete examples, code, metrics
What we learned — insights, surprises, trade-offs
Closing — what's next, internal links to related posts

Voice: direct, concrete, no marketing fluff. Show numbers. Show code. Tell stories.

SEO checklist

Title under 60 characters
Description 150-160 characters
og_image set (falls back to /img/og-cover.jpg)
Meaningful excerpt for index card
Internal links where relevant ([other post](other-slug))

Conventions

Slugs: kebab-case matching filename: my-post.md → slug my-post
Dates: ISO format 2026-06-03
Canonical URLs: https://www.tinqs.com/blog/<slug>
Em dashes: --- in markdown renders as —, -- as –

Deploy

git add -A
git commit -m "post: <description>"
git push origin main

Git Studio serves this repo directly. A push to main is a deploy. No build step on the server — static HTML files.

Skills reference

The skills/ directory contains reusable agent playbooks for game dev workflows. These are NOT blog-specific — they're for game development agents using Tinqs Studio.

Image Generation (skills/image-generation.md) — fal.ai Flux API, 4-layer prompt pattern, model comparison
Concept Art Pipeline (skills/concept-art-pipeline.md) — Full 2D concept art → 3D model workflow
Sora 2 Video (skills/sora2-video.md) — Trailer clips with OpenAI Sora 2
Tripo 3D (skills/tripo-browser-workflow.md) — Text-to-3D and image-to-3D via Tripo Studio

Skills are markdown playbooks — drop them into any agent's skills directory to teach it a workflow.

6.4 KiB Raw Blame History