Instructions for AI agents working on this repository.
Personal website and blog at imiles.me. Built with Astro, React islands, Tailwind CSS v4, and Three.js. Content is authored in MDX (blog) and Markdown (stories).
content/ blog/ # MDX blog posts (schema: title, description, pubDate, tags, heroImage) stories/ # Markdown stories (schema: title, description, pubDate, tags) experience/ # Bilingual MDX experience timeline entries src/ pages/ # Astro routes (index, blog, stories, projects, notes, about, rss, og) components/ # React (.tsx) and Astro (.astro) components layouts/ # BaseLayout.astro — single layout wrapping all pages data/ # Static data: projects.ts, socialLinks.ts, imageCredits.ts, research.ts, welcomeTimeline.tsx, scriptMappings.ts hooks/ # React hooks (useScrollDirection, useReducedMotion, useSimulatedPulse, useTextScramble) lib/ # Utilities (i18n, readTime, search, utils, mdxToMarkdown, enhanceCodeBlocks) styles/ # global.css (Tailwind v4) content.config.ts # Astro content collection schemas for blog, stories, and experience public/ images/ # Static images (welcome timeline, logos) projects/ # Project demo assets organized by slug fonts/ # Inter fonts for OG image generation icons/ # PWA icons
- Styling: Tailwind CSS v4 with dark mode default. Use
cn()fromsrc/lib/utils.tsfor class merging. - Components: React components use
.tsx. Astro components use.astro. React islands are hydrated viaclient:loadorclient:visible. - Content: Blog posts go in
content/blog/as.mdx. Stories go incontent/stories/as.md. Experiences go incontent/experience/as.mdx. All must include valid frontmatter matching their schema incontent.config.ts. - Images: Place in
public/under the appropriate subdirectory. Third-party photos require a credit entry insrc/data/imageCredits.ts. - Linting: Biome handles lint and format. Run
pnpm lintandpnpm format:checkbefore committing. - Pre-commit: Husky + lint-staged runs Biome on staged files.
Use pnpm scripts directly. This repository does not use an extra command runner.
| Task | Command |
|---|---|
| Install dependencies | pnpm install |
| Start dev server | pnpm dev |
| Build production output | pnpm build |
| Preview production build | pnpm preview |
| Run lint/checks | pnpm lint |
| Format files | pnpm format |
Additional scripts:
pnpm format:checkchecks formatting without writing changes.pnpm lint:fixruns Biome with autofix.pnpm checkruns Astro's type/content check, but it requires@astrojs/checkto be installed.pnpm generate-iconsregenerates PWA icons.pnpm generate:llmsregenerates LLM-facing text output.pnpm perf:budgetruns the homepage performance budget script.pnpm run deploybuilds and deploys to Cloudflare Workers.
When changing code, prefer targeted checks first, such as pnpm exec biome check <file>, then run broader checks or pnpm build when the change affects routing, content collections, Astro pages, or build-time behavior.
Import individually or via barrel export from ../components:
| Component | Purpose | Hydration |
|---|---|---|
PreviewLink |
External link with hover preview card | client:load |
ExploreCard |
Collapsible card for supplementary content (Snippet of the Week) | client:load |
Aside |
Side-note or callout box | client:load |
BlockQuote |
Styled quotation with author/source attribution | client:load |
PullQuote |
Large emphasized inline quote | client:load |
Collapsible |
Generic collapsible section | client:load |
YouTubeEmbed |
YouTube video embed (takes id and title props) |
client:load |
ChatDemo |
Interactive AI chat demonstration | client:visible |
Phonetic |
IPA pronunciation display (takes ipa prop) |
client:load |
ScriptInline |
Script/alphabet transliteration | client:load |
GPEvolutionVisualizer |
Animated genetic programming visualization | client:visible |
CriticalThinkingLoop |
Animated critical thinking loop diagram | client:visible |
FirstPrinciplesVisual |
First principles breakdown | client:visible |
ConfirmationBiasVisual |
Confirmation bias illustration | client:visible |
ExtrapolationVisual |
Extrapolation concept visual | client:visible |
ConsilienceVisual |
Consilience concept visual | client:visible |
SearchLandscapeVisual |
Search/optimization landscape visual | client:visible |
Cite |
Inline superscript citation linking to reference list | none |
References |
Rendered reference list with back-links to inline citations | none |
PDFCard |
Document download and standalone reader card | none |
PDFLink |
Inline PDF badge link opening reader in new tab | none |
| Component | Purpose |
|---|---|
Hero |
Landing page hero section |
LandingExperience |
Three.js plexus background + landing |
WelcomeTimeline |
About page timeline |
TimelineImage |
Image with credit overlay (used in timeline) |
AutoHideHeader |
Scroll-responsive header |
NavbarMenuEnhanced |
Main navigation |
MobileMenu |
Mobile navigation drawer |
MobileTOC |
Mobile table of contents |
TableOfContents |
Desktop table of contents |
CodeBlockEnhancer |
Adds copy buttons to code blocks |
HeadingLinkEnhancer |
Adds anchor links to headings |
ProjectCard / ProjectHero |
Project listing and detail pages |
FeatureGrid / TechStackGrid |
Project detail page grids |
TerminalDemo / ImageShowcase |
Project demo renderers |
ResearchCard / ResearchHero |
Research page components |
BlogSearch |
Blog search with fuzzy matching |
SocialDock / SocialLinksGrid |
Social links display |
ShareButton / CopyMarkdownButton |
Post sharing utilities |
ModeToggle |
Dark/light theme toggle |
StatusBadge |
Project status indicator |
NewsletterSignup |
Newsletter subscription form |
ArchitectureFlow |
Architecture diagram component |
NavigationMenuDemo |
Navigation menu showcase |
StandalonePDFReader |
Full-screen desktop PDF reader (/pdf route) |
| Component | Source |
|---|---|
button |
shadcn/ui |
dropdown-menu |
shadcn/ui + Radix |
navigation-menu |
Radix |
navbar-menu |
Custom animated nav |
timeline |
Custom timeline renderer |
floating-dock |
Animated floating dock |
link-preview |
Hover link preview card |
placeholders-and-vanish-input |
Animated search input |
aurora-background |
Aurora gradient background |
background-lines |
Animated background lines |
plexus-background |
Three.js plexus network (+ plexus-webgl/ subdir) |
- Frontmatter requires:
title,description,pubDate,tags. Optional:heroImage,updatedDate,shareText. - In the CMS, save an unpublished working copy with Save draft and make it public with Publish.
- Tags are arrays of lowercase strings.
- Can import and use React components with
client:loadorclient:visiblehydration. - Support KaTeX math via
remark-math+rehype-katex($$for display,$for inline).
Stories are text-only Markdown (.md) in content/stories/. They use no React components, no images, and no MDX.
Frontmatter requires: title, description, pubDate, tags. Optional: updatedDate.
Writing style:
- First-person, present-tense narration — immediate, visceral, stream-of-consciousness.
- Short paragraphs — often a single sentence or word. White space controls pacing.
- Dialogue is inline, separated by blank lines. Uses
"..."quotes with speaker attribution after. _italics_for internal thought and emphasis.*italics*for meta-text (e.g.,*To be continued...*).--for em-dashes (double hyphen, not—) — used for interruption, hesitation, and mid-thought breaks.<br/>for forced line breaks within a paragraph — keeps lines visually together while breaking mid-thought (e.g., multi-line dialogue from one speaker, fragmented thoughts).---for scene breaks — rendered as decorative— ✧ —ornaments by the story CSS.- No headings within content — narrative is continuous, divided only by
---scene breaks. - No code blocks, no math, no embeds, no images — pure prose only.
- Continuation marker: Multi-part stories end with
*To be continued...*.
Rendering:
- Stories render in
story-proseclass:1.2remfont,line-height: 2,letter-spacing: 0.01em. <hr>renders as centered— ✧ —ornaments with3remmargin.- A decorative "End" footer (diamond ornament + uppercase label) is auto-appended by the
[slug].astrotemplate. - Max width:
max-w-2xl(narrower than blog for readability). - OG metadata:
ogType="article"withpublishedTimeandtags.
Tone:
- Emotionally raw, fragmented, urgent.
- Pacing via paragraph length — shorter = faster.
- Abrupt cuts, incomplete thoughts, and repeated
---blackouts convey disorientation. - Dialogue is sparse and loaded — characters say little, imply much.
Every blog post should close with a "Snippet of the Week" — a cross-domain educational tangent inside an ExploreCard. This is a core content convention established in the first post.
Pattern:
## Snippet of the Week
<ExploreCard client:load title="Topic — Subtitle">
Explanatory prose connecting the snippet to the post.
#### The Math (optional)
$$
LaTeX formula
$$
#### The Code
```language
code sampleTies the snippet back to the post's theme.
```Rules:
- Must be from a different domain than the post's primary subject.
- Should include code and/or math when applicable.
ExploreCardis collapsed by default.- Posts with formal references use a
## Referencessection with numbered citations instead of or in addition to the snippet.
Blog posts with references use Cite and References components for dynamic two-way linking.
Usage:
import Cite from '../components/Cite';
import References from '../components/References';
...training datasets<Cite id={1} />.
---
<References items={[
{ id: 1, text: 'Author. "Title." Source, Year.', url: "https://..." },
]} /><Cite id={N} />renders as superscript[N]linking down to#ref-N.- Each reference entry's
[N]links back up to#cite-N. - No
client:loadneeded — both are static markup. idvalues must match betweenCiteandReferencesitems.- Place
<References>at the end of the post after---. textcontains the citation (author, title, source, year) — URL renders separately.
- Image format: WebP for photos, SVG for charts/icons, PNG for screenshots with text.
- Image credits: Any third-party image must have a corresponding entry in
src/data/imageCredits.tswith photographer name and URL. - YouTube embeds: Use the
YouTubeEmbedcomponent with a valid video ID. - Project demos: Referenced in
src/data/projects.ts— images go inpublic/projects/<slug>/. - OG images: Auto-generated via Satori at
src/pages/og/[...slug].png.ts. Uses Inter fonts frompublic/fonts/. - Stories have no visual support — do not add images, embeds, or components to story files.
- Code (source, config, tooling): Apache License 2.0
- Content (blog posts, images, branding): CC BY-NC-ND 4.0
Any contributed images must be compatible with CC BY-NC-ND 4.0 or be original work.
Skills live in .agents/skills/<name>/SKILL.md:
- use-iconify (
.agents/skills/use-iconify/SKILL.md): Complete workflow for adding Iconify (iconify.design) icons anywhere in the project — including the tech-stack icon cloud insrc/components/article/TechSkillsCloud.tsx(data files, STACK entries, thessrgotcha, brand colors, and verification). Use when the user asks to add/use icons. - svg-to-threejs-signature (
.agents/skills/svg-to-threejs-signature/SKILL.md): End-to-end workflow for transforming raw hand-drawn SVG signatures/paths into 3D Three.js particle constellation patterns (stroke extraction, RDP curve simplification, 3D depth camber, spatial hash connection tuning, and Plexus/Hero integration). Use when converting SVG signatures or vector drawings into 3D particle animations.
- Remove or rename
public/fonts/Inter-*.ttf— OG image generation depends on them. - Add images without credit entries for third-party work.
- Modify
content.config.tsschemas without updating all existing content to match. - Use
git add -A— stage specific files to avoid committing.envor build artifacts. - Skip the Snippet of the Week in new blog posts without explicit instruction.
- Use
client:loadfor heavy visualization components — preferclient:visiblefor anything with animations or WebGL. - Add React components, images, or embeds to stories — stories are pure Markdown prose.
- Use
—(em-dash character) in stories — use--(double hyphen) instead. - Add headings (
##,###, etc.) inside story content — use---scene breaks only.