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)
This commit is contained in:
@@ -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)
|
||||
- `<!--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.
|
||||
Reference in New Issue
Block a user