Imported from K41R0N/k41r0n.github.io (AGENTS.md). Install upstream with npx skills add K41R0N/k41r0n.github.io. Copyright stays with the author.

Agent Instructions — Kairon Portfolio

Instructions for AI agents working on this project. Read before making any changes.

New here? Start with agent/README.md — a dedicated contributor brain (orientation, skills, guidelines, write-guard protocol, and live-component automation foundations) built so an agent can edit this repo without breaking the CMS. This file remains the quick reference; agent/ is the deeper, task-oriented guide.

⚠️ If you are the G14 Research Agent: You operate under strict read-only constraints for this repo. Read agent/README.md to understand your specific boundaries.

Project Overview

Personal portfolio for Alejandro (Kairon) Arango Giraldo — Creative Technologist and Martech Daylighter.

Key Architecture Principle

Content is the source of truth. Edit content/ files — run npm run build — done.

content/settings/site.json    ──▶ scripts/build.js ──▶ dist/index.html
content/theses/*.md           ──▶ scripts/build.js ──▶ dist/ (SEO + LLM endpoints)

Content Structure

Thesis Frontmatter Schema

---
title: "Thesis Title"
slug: "thesis-slug"           # kebab-case, used as HTML anchor ID
order: 1                       # display order
description: "One sentence."  # used in SEO, llms.txt, card subtitle
links:                        # optional list of supporting links
  - label: "Article"
    title: "Display Title"
    url: "https://..."
---

Optional body text in markdown.

Critical Files

Files You Should NOT Modify

Build Pipeline

npm run build
  ├─ prebuild: generate-cms-config.js  # admin/config.yml from template
  └─ build.js                           # main build
      ├─ Load content/settings/site.json
      ├─ Load content/theses/*.md
      ├─ Render index.html
      ├─ Generate llms.txt + llms-full.txt
      ├─ Generate api/content.json
      ├─ Generate sitemap.xml + feed.xml + robots.txt
      └─ Copy css/ + assets/ + admin/

Build Output

dist/
├── index.html          # Portfolio page
├── llms.txt            # AI agent guidance
├── llms-full.txt       # Full content dump
├── api/content.json    # Structured JSON API (CORS-enabled)
├── sitemap.xml         # Search engine sitemap
├── feed.xml            # RSS feed
├── robots.txt          # AI crawler allowances
├── css/                # Stylesheets
├── assets/fonts/       # Self-hosted fonts
└── admin/              # CMS entry point

Design System

Design tokens in src/css/tokens.css. Only change variable values, never names.

• Background: #F5F5F5 (warm off-white)
• Text: #000 (black)
• Accent: #bf150f (crimson)
• Font display: Kyrios (variable sans — self-hosted)
• Font body: Merriweather (serif — Google Fonts)
• Font mono: Departure Mono / system monospace (technical label voice)
• Font kairon: Kairon (custom display glyph — self-hosted)

Design Patterns

CMS Configuration (Sveltia CMS)

• Backend: GitHub (K41R0N/k41r0n.github.io)
• Auth: https://sveltia-cms-auth.alejandro-057.workers.dev/ (hardcoded in template)
• Admin URL: /admin
• Schema source: admin/config.template.yml → generates admin/config.yml at build time

Collections and What They Control

What Each Thesis Field Controls

Environment Variables (Vercel dashboard)

CMS_REPO and CMS_AUTH_URL are hardcoded in admin/config.template.yml — no extra Vercel env vars needed.

about.md Format

No frontmatter. Plain markdown body only. Do not add frontmatter — the CMS only maps to the body and will strip any frontmatter on the next save.

Adding a New Configurable Field

1. Add to content/settings/site.json with a default value
2. Add to admin/config.template.yml Settings collection with a hint:
3. Update scripts/build.js to read the field (always include a fallback)
4. Document in CONTENT_ARCHITECTURE.md

LLM-Friendly Endpoints

Documented Solutions

docs/solutions/ — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type). Relevant when implementing or debugging in documented areas.

Key Commands

npm install          # Install dependencies (gray-matter, marked)
npm run build        # Production build → dist/
npm run validate     # Validate content only (placeholder)

Handover Checklist

Before shipping changes, verify:

• npm run build completes without errors
• dist/index.html renders correctly in browser
• All 3 theses appear with correct links
• dist/llms.txt contains correct metadata
• dist/robots.txt has AI crawler allowances
• dist/api/content.json is valid JSON
• Fonts load correctly (no FOUT / invisible text)

Built with clarity, not breadth.