blog/agents.md

# 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.

> **Repo agent context + Knowledge map:** [`.agents/AGENTS.md`](.agents/AGENTS.md) (skills, plans, handoffs, wiki). Human content (posts/HTML/templates) stays at the repo root.

## Shared context

Shared agent identity, team roster, skills, and cross-project rules live in `../docs/.agents/`. Read at session start:
- `../docs/.agents/SOUL.md` — shared identity
- `../docs/ai/company.md` — team roster
- `../docs/ai/siblings.md` — repo locations
- `../docs/.agents/rules/shared-context.md` — cross-repo conventions

## 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)
- `<!--raw-->` / `<!--/raw-->` 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`:

```yaml
---
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:
```bash
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}}`:

```html
    <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)

1. `../style.css` — external, served by Git Studio. Nav, footer, base typography, `--c-accent: #c9935a`. Never edit.
2. `<style>` in `_template.html` — post-page overrides (inline, at end of `<head>`)
3. `<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

1. Open `_template.html` (or `_index_template.html` for listing-only styles)
2. Find the `<style>` block at end of `<head>` (marked with `/* ── Team guide aesthetic ── */`)
3. 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`
4. `node build.js` to regenerate
5. 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:

1. **Lead paragraph** — what this is about, one punchy sentence
2. **The hook** — why it matters, what problem it solves
3. **How it works** — concrete examples, code, metrics
4. **What we learned** — insights, surprises, trade-offs
5. **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 `&mdash;`, `--` as `&ndash;`

## Deploy

```bash
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

Skills live in the hub: `../docs/.agents/skills/` (image-generation, concept-art-pipeline, sora2-video, tripo-browser-workflow, and more). Read skill SKILL.md files from there when needed.