From bf42a76cf93f81308381f0adcc3534319c411e13 Mon Sep 17 00:00:00 2001 From: tinqs-limited Date: Wed, 3 Jun 2026 02:47:06 +0100 Subject: [PATCH] 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) --- _index_template.html | 7 + agents.md | 164 +++++++++++++++++++++ index.html | 14 +- pi-flow-native-brain.html | 216 +++++++++------------------- posts/pi-flow-native-brain.md | 259 ---------------------------------- skills/blog.md | 57 -------- 6 files changed, 247 insertions(+), 470 deletions(-) create mode 100644 agents.md delete mode 100644 posts/pi-flow-native-brain.md delete mode 100644 skills/blog.md 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 @@
+ + + 3 June 2026 +

How Pi Agents Build, Test, and Ship Game Code with Oracle-Backed Flows

+

When we ask Pi to build a game feature, it doesn't just write code. It compiles, runs tests, drives the live game, measures feel, fixes CI failures, and ships a green PR — all through composable oracle-backed flows.

+ Read → + {{CARDS}}
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/.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 .html + rebuilds index.html +git add posts/.md .html index.html +git commit -m "post: " +``` + +### 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. diff --git a/index.html b/index.html index 54e4393..9059dc9 100644 --- a/index.html +++ b/index.html @@ -120,6 +120,13 @@ <!-- BLOG LIST --> <div class="blog-list"> + <!-- hand-authored HTML posts (not from build.js) --> + <a href="pi-flow-native-brain" class="blog-card"> + <span class="blog-card__date">3 June 2026</span> + <h2 class="blog-card__title">How Pi Agents Build, Test, and Ship Game Code with Oracle-Backed Flows</h2> + <p class="blog-card__excerpt">When we ask Pi to build a game feature, it doesn't just write code. It compiles, runs tests, drives the live game, measures feel, fixes CI failures, and ships a green PR — all through composable oracle-backed flows.</p> + <span class="blog-card__read">Read →</span> + </a> <a href="blog-visual-upgrade" class="blog-card"> <span class="blog-card__date">3 June 2026</span> @@ -128,13 +135,6 @@ <span class="blog-card__read">Read →</span> </a> - <a href="pi-flow-native-brain" class="blog-card"> - <span class="blog-card__date">3 June 2026</span> - <h2 class="blog-card__title">Pi's Flow-Native Brain: Retiring the Supervisor, Teaching Agents to Fix Their Own Builds</h2> - <p class="blog-card__excerpt">Two changes made Pi genuinely autonomous: we deleted the hardcoded supervisor and replaced it with composable oracle-backed flows, and we taught agents to watch CI, read failure logs, and fix their own broken builds.</p> - <span class="blog-card__read">Read →</span> - </a> - <a href="cloud-harness" class="blog-card"> <span class="blog-card__date">26 May 2026</span> <h2 class="blog-card__title">Building a Cloud Agent Harness with DeepSeek V4 and Pi</h2> diff --git a/pi-flow-native-brain.html b/pi-flow-native-brain.html index a12fb10..7302c82 100644 --- a/pi-flow-native-brain.html +++ b/pi-flow-native-brain.html @@ -4,27 +4,27 @@ <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> - <title>Pi's Flow-Native Brain: Retiring the Supervisor, Teaching Agents to Fix Their Own Builds — Tinqs Blog - + How Pi Agents Build, Test, and Ship Game Code with Oracle-Backed Flows — Tinqs Blog + - - + + - - + + - - - @@ -53,7 +47,6 @@