ozan
bf42a76cf9
- 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)
165 lines
6.4 KiB
Markdown
165 lines
6.4 KiB
Markdown
# 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)
|
|
- `<!--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 →</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 `—`, `--` as `–`
|
|
|
|
## 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 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.
|