tinqs/blog

Files

T

ozan 56795b680f chore(.agents): adopt the .agents/ agent-context convention (matches studio)

Add .agents/ (AGENTS.md Knowledge-map + skills/plans/handoffs/wiki) so blog matches the
cross-repo structure; human content (posts/HTML/templates) stays at repo root. Root agents.md
points to .agents/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-08 00:23:33 +01:00

6.4 KiB

Raw Permalink 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.

Repo agent context + Knowledge map: .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

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

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.

6.4 KiB Raw Permalink Blame History