Development

.agent/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md - Instructions for Coding Assistant LLMs
+
+[![Next.js](https://img.shields.io/badge/Next.js-14-000000?logo=nextdotjs&logoColor=white)](https://nextjs.org/)
+[![React](https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=white)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
+[![Python](https://img.shields.io/badge/Python-3.11+-3776ab?logo=python&logoColor=white)](https://www.python.org/)
+
+> **Purpose**: Authoritative reference for AI assistants (Claude, GPT, Gemini, Copilot, etc.) working in this repository.
+
+## Table of Contents
+
+1. [Project Overview](#1-project-overview)
+2. [Technical Stack](#2-technical-stack)
+3. [Module Boundaries](#3-module-boundaries)
+4. [Key Commands](#4-key-commands)
+5. [Coding Standards](#5-coding-standards)
+6. [Known Constraints](#6-known-constraints)
+
+## 1. Project Overview
+
+This is ACFHarbinger's personal website: a statically-exported Next.js blog/knowledge base covering posts, longer-form reports, project write-ups, tool notes, and media, deployed to GitHub Pages at
+[acfharbinger.github.io/github-pages](https://acfharbinger.github.io/github-pages/). Content lives as Markdown under `app/content/<section>/` and is rendered through the App Router; `notebooks/` is a small, separate Python/uv workspace used to run the analysis behind some reports (e.g. audio signal processing, PCVRP) before writing them up.
+
+## 2. Technical Stack
+
+| Component | Specification | Notes |
+| --- | --- | --- |
+| Next.js | 14 (App Router, `output: 'export'`) | Static export deployed to GitHub Pages, `basePath: /github-pages` |
+| React / TypeScript | 18 / 5 | `strict: true` in `tsconfig.json` |
+| Styling | Tailwind CSS 3 | Config in `tailwind.config.js` |
+| Content | Markdown + `gray-matter` / `remark` | Parsed at build time from `app/content/<section>/` |
+| Unit tests | Vitest + Testing Library | `test/unit/`, mirroring `src/components/` |
+| Integration tests | Vitest + Testing Library + MSW | `test/integration/` |
+| E2E / smoke tests | Cypress | `test/cypress/e2e/`, `test/cypress/smoke/` |
+| Notebooks | Python 3.11+, managed via `uv` | `notebooks/`, workspace member of the root `pyproject.toml` |
+
+## 3. Module Boundaries
+
+- `app/` — Next.js App Router: routes, layouts, and Markdown content under `app/content/<section>/` (`posts`, `reports`, `projects`, `tools`, `media`, `about`, `other`).
+- `src/components/` — presentational and layout React components consumed by `app/`. Business logic (content loading/parsing) belongs in `lib/`, not inline in components.
+- `lib/` — server-side helpers (Markdown loading/parsing, front-matter handling) used by `app/` at build time.
+- `notebooks/` — independent Python/uv workspace for exploratory analysis backing written reports. Not part of the Next.js build; never imported from `src/`/`app/`.
+- `public/` — static assets served as-is.
+- `infra/global/` — optional external/public-facing deploy and host tooling (docker, k8s, helm, terraform, ansible). Not used by the default GitHub Pages workflow.
+- `infra/cloud/` — managed cloud static-host configs (AWS, Azure Pipelines, Firebase, Serverless).
+- `infra/server/` — standalone nginx and Envoy reverse-proxy configs.
+- `infra/private/` — internal developer-only infra experiments (e.g. webpack, wordpress).
+
+## 4. Key Commands
+
+| Command | Purpose |
+| --- | --- |
+| `npm run dev` | Local dev server |
+| `npm run build` | Static export to `out/` |
+| `npm run lint` | ESLint (Next.js config) |
+| `npm test` / `npm run test:watch` | Vitest: unit (`test/unit/`) + integration (`test/integration/`) |
+| `npm run cypress:run` / `npm run cypress:smoke` | Cypress e2e/smoke (against a running build/dev server) |
+| `cd notebooks && uv sync --extra dev` | Set up the notebooks Python environment |
+
+## 5. Coding Standards
+
+- Follow the per-topic rules in [`.agent/rules/`](rules/) (`typescript_react.md`, `python.md`, plus the language-agnostic ones).
+- Prefer small, reviewable diffs. Do not reformat files unrelated to the change.
+- New components get a Vitest unit test in `test/unit/`; multi-component interactions get an integration test in `test/integration/` (mock any network calls with MSW); new user-facing flows get a Cypress spec in `test/cypress/e2e/`.
+- Never commit secrets. This site has no runtime secrets today — flag it clearly if a change would introduce one.
+
+## 6. Known Constraints
+
+- The site is a fully static export (`output: 'export'`) — no server-side code, API routes, or runtime environment variables beyond the build-time `NEXT_PUBLIC_BASE_PATH`.
+- `notebooks/` is exploratory/research tooling, not covered by the main CI build; it has its own lint/test story via `uv`.

.agent/chat/claude_subagent_delegation.md

@@ -0,0 +1,28 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: CLAUDE
+
+**Identity & Capability:**
+You can deploy a Claude AI subagent via the local terminal using the `claude` CLI command. Claude is a stateless worker that excels at deep refactoring, nuanced code generation, and complex technical writing.
+
+**When to Delegate:**
+Invoke the Claude subagent for:
+*   **Deep Refactoring:** Restructuring a React/TypeScript component tree in `src/components/` without changing rendered output.
+*   **UI/Frontend Generation:** Generating structured code for complex layouts (e.g., a new content-listing or data-visualization component).
+*   **Granular Code Review:** Performing rigorous audits of a notebook's analysis logic before it's cited in a report.
+
+**Execution Syntax:**
+Run the command in your shell, wrapping the prompt in strong quotes.
+`claude 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Claude):**
+1.  **Complete Independence:** Claude cannot read your memory. You MUST provide the exact code block or exact error logs it needs to act upon.
+2.  **ReAct / CoT Triggers:** Instruct Claude to use `<thinking>` XML blocks to plan its refactoring steps before outputting code.
+3.  **Strict Boundaries:** Specify exact input and output formats (e.g., "Output ONLY valid TypeScript code inside a single markdown block").
+
+**Example Usage:**
+`claude 'Act as an expert React/TypeScript developer. Refactor the following PostWrapper component so it shares its Markdown-rendering logic with ReportWrapper via a common hook, without changing rendered output. Wrap your reasoning in <thinking> tags, then provide the refactored code. Code to refactor: [INSERT_CODE_HERE]'`
+
+**Failure Modes to Avoid:**
+*   **Do not** include single quotes inside the prompt string without escaping them.
+*   **Do not** delegate tasks that require multi-turn conversational context.
+---

.agent/chat/gemini_subagent_delegation.md

@@ -0,0 +1,28 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: GEMINI
+
+**Identity & Capability:**
+You have the authority to spawn a Gemini AI subagent via the terminal using the `agy` CLI command. Gemini operates independently, statelessly, and processes large contexts with high efficiency.
+
+**When to Delegate:**
+Invoke the Gemini subagent for:
+*   **Data Wrangling:** Standardizing a notebook's data transformations or parsing large JSON/log/CSV inputs for a report.
+*   **Front-Matter/Content Boilerplate:** Generating consistent Markdown front-matter and stub pages when adding a new `app/content/<section>/` entry.
+*   **Long-Context Extraction:** Pulling structured summaries or key figures out of a long research write-up under `docs/research/`.
+
+**Execution Syntax:**
+Execute the command in your terminal. Ensure the prompt is enclosed in single quotes.
+`agy 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Gemini):**
+1.  **Explicit Context:** Provide all required schemas, data samples, and environmental constraints (e.g., Linux, KDE, specific GPU hardware).
+2.  **Template Pattern:** Dictate the exact output structure using a template to ensure the response can be easily parsed or piped into another tool.
+3.  **Action-Oriented Verbs:** Start instructions with clear directives like "Analyze," "Generate," or "Extract."
+
+**Example Usage:**
+`agy 'Act as an expert technical writer. Given the following notebook analysis output (summary stats + a chart description), draft the "Results" section of a Markdown report for app/content/reports/. Constraints: 1. Match the tone of the site's existing reports. 2. Output only the Markdown section. Context: [INSERT_ANALYSIS_OUTPUT]'`
+
+**Failure Modes to Avoid:**
+*   **Do not** use unescaped single quotes in the `agy` execution string.
+*   **Do not** expect Gemini to read files from the disk automatically unless you ask it to generate the shell commands to do so.
+---

.agent/chat/grok_subagent_delegation.md

@@ -0,0 +1,33 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: GROK
+
+**Identity & Capability:**
+You can deploy a Grok AI subagent via the local terminal using the `grok` CLI command (Grok Build by xAI). Grok is a tool-using coding agent that can explore codebases, edit files, run shell commands, and implement multi-step software engineering tasks. It does not share your context window; treat it as an independent worker.
+
+**When to Delegate:**
+Invoke the Grok subagent for:
+*   **End-to-End Implementation:** Building features, fixing bugs, or applying multi-file refactors with tests and commits.
+*   **Codebase Exploration:** Navigating large repositories, tracing call graphs, and summarizing architecture before you act.
+*   **Agentic Tool Work:** Tasks that benefit from iterative shell/build/test loops rather than pure text generation.
+*   **Real-Time / Web-Aware Reasoning:** Problems that need up-to-date context, search, or alternative high-level approaches when you are stuck.
+
+**Execution Syntax:**
+Run the command in your shell, wrapping the prompt in strong quotes to prevent shell evaluation errors. Prefer single-turn / headless mode so the subagent prints a result and exits:
+`grok -p 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+For longer agentic work that may need tools and multiple turns:
+`grok --always-approve -p 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Grok):**
+1.  **Complete Independence:** Grok does not see your conversation. Include paths, constraints, acceptance criteria, and any required snippets or error logs in the prompt.
+2.  **Actionable Scope:** State the working directory, which files may change, and what "done" looks like (e.g., "tests pass", "output only the diff summary").
+3.  **Strict Boundaries:** Specify format and limits (e.g., "Do not open a PR", "Output ONLY a bullet list of findings", "Modify only files under src/").
+
+**Example Usage:**
+`grok -p 'Act as an expert systems engineer. In the current repository, locate the authentication middleware, identify why refresh tokens are rejected after 24h, and propose a minimal fix. Constraints: 1. Do not modify files. 2. Return a short root-cause analysis and a concrete patch suggestion in a single markdown code block.'`
+
+**Failure Modes to Avoid:**
+*   **Do not** use unescaped single quotes inside the `grok` command string.
+*   **Do not** assume Grok knows your prior conversation or unstated project goals.
+*   **Do not** nest quotes improperly (e.g., `grok -p 'He said 'hello''`).
+---

.agent/claude/chatgpt_subagent_delegation.md

@@ -0,0 +1,29 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: CHATGPT
+
+**Identity & Capability:**
+You can orchestrate a ChatGPT AI subagent via your local terminal using the `chatgpt` CLI command. ChatGPT acts as a stateless, highly capable reasoning engine. It does not share your context window.
+
+**When to Delegate:**
+Invoke the ChatGPT subagent for:
+*   **Mathematical Formulations:** Drafting formal definitions or notation for a report's math section (e.g. the PCVRP report under `app/content/reports/`).
+*   **Literature & Concept Mapping:** Summarizing background material or related work to cite in a report.
+*   **Creative Brainstorming:** Generating varied framings for a post/report before committing to a structure.
+
+**Execution Syntax:**
+Run the command in your shell, wrapping the prompt in strong quotes to prevent shell evaluation errors.
+`chatgpt 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to ChatGPT):**
+1.  **Zero-Shot Context:** You MUST include all necessary definitions, constraints, and current state.
+2.  **Constraint Pattern:** Explicitly list what ChatGPT must *not* do to keep the response focused and token-efficient.
+3.  **Role Definition:** Always assign ChatGPT a clear persona (e.g., "Act as a PhD-level Operations Research scientist").
+
+**Example Usage:**
+`chatgpt 'Act as an Operations Research expert. I am writing a report on the Periodic Capacitated Vehicle Routing Problem (PCVRP). Provide the formal mathematical formulation for the objective function minimizing total travel cost over a multi-day horizon. Rules: 1. Use standard OR notation. 2. Define all variables clearly. 3. Output ONLY the formulation and variable definitions in plain text.'`
+
+**Failure Modes to Avoid:**
+*   **Do not** use unescaped single quotes inside the `chatgpt` command string.
+*   **Do not** assume ChatGPT knows our current project state.
+*   **Do not** delegate tasks requiring direct file manipulation.
+---

.agent/claude/gemini_subagent_delegation.md

@@ -0,0 +1,29 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: GEMINI
+
+**Identity & Capability:**
+You have the ability to spawn an independent Gemini AI subagent via your local terminal using the `agy` CLI command. Gemini does not share your context window; it acts as a stateless, highly capable assistant. 
+
+**When to Delegate:**
+Invoke the Gemini subagent for:
+*   **Alternative Reasoning:** Generating a second opinion on a notebook's analysis approach before it's written up as a report.
+*   **Parallel Processing:** Delegating isolated sub-tasks (e.g., drafting a regex, summarizing a log file) while you focus on the main change.
+*   **Long-Context Summarization:** Leveraging Gemini's large context window to distill a long research doc under `docs/research/` into a post-sized outline.
+
+**Execution Syntax:**
+Run the command in your shell, wrapping the prompt in strong quotes to prevent shell evaluation errors.
+`agy 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Gemini):**
+1.  **Zero-Shot Context:** You MUST include all necessary code, logs, or context in your string. Gemini cannot see your current workspace unless explicitly provided in the prompt.
+2.  **Explicit Formatting:** Tell Gemini exactly how to output the response (e.g., "Return ONLY raw JSON," or "Provide a Markdown table").
+3.  **Role Definition:** Assign Gemini a role if helpful (e.g., "Act as an expert technical editor...").
+
+**Example Usage:**
+`agy 'Act as an expert in signal processing. Review the following Python analysis code from notebooks/ and identify potential correctness issues in the filtering step. Return only a bulleted list of 3 specific issues: [INSERT_LOGIC_HERE]'`
+
+**Failure Modes to Avoid:**
+*   **Do not** use unescaped single quotes inside the `agy` command string.
+*   **Do not** assume Gemini knows the history of our conversation.
+*   **Do not** delegate tasks that require writing files directly, unless you instruct Gemini to output the exact terminal commands for you to run.
+---

.agent/claude/grok_subagent_delegation.md

@@ -0,0 +1,33 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: GROK
+
+**Identity & Capability:**
+You can deploy a Grok AI subagent via the local terminal using the `grok` CLI command (Grok Build by xAI). Grok is a tool-using coding agent that can explore codebases, edit files, run shell commands, and implement multi-step software engineering tasks. It does not share your context window; treat it as an independent worker.
+
+**When to Delegate:**
+Invoke the Grok subagent for:
+*   **End-to-End Implementation:** Building features, fixing bugs, or applying multi-file refactors with tests and commits.
+*   **Codebase Exploration:** Navigating large repositories, tracing call graphs, and summarizing architecture before you act.
+*   **Agentic Tool Work:** Tasks that benefit from iterative shell/build/test loops rather than pure text generation.
+*   **Real-Time / Web-Aware Reasoning:** Problems that need up-to-date context, search, or alternative high-level approaches when you are stuck.
+
+**Execution Syntax:**
+Run the command in your shell, wrapping the prompt in strong quotes to prevent shell evaluation errors. Prefer single-turn / headless mode so the subagent prints a result and exits:
+`grok -p 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+For longer agentic work that may need tools and multiple turns:
+`grok --always-approve -p 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Grok):**
+1.  **Complete Independence:** Grok does not see your conversation. Include paths, constraints, acceptance criteria, and any required snippets or error logs in the prompt.
+2.  **Actionable Scope:** State the working directory, which files may change, and what "done" looks like (e.g., "tests pass", "output only the diff summary").
+3.  **Strict Boundaries:** Specify format and limits (e.g., "Do not open a PR", "Output ONLY a bullet list of findings", "Modify only files under src/").
+
+**Example Usage:**
+`grok -p 'Act as an expert systems engineer. In the current repository, locate the authentication middleware, identify why refresh tokens are rejected after 24h, and propose a minimal fix. Constraints: 1. Do not modify files. 2. Return a short root-cause analysis and a concrete patch suggestion in a single markdown code block.'`
+
+**Failure Modes to Avoid:**
+*   **Do not** use unescaped single quotes inside the `grok` command string.
+*   **Do not** assume Grok knows your prior conversation or unstated project goals.
+*   **Do not** nest quotes improperly (e.g., `grok -p 'He said 'hello''`).
+---

.agent/gemini/chatgpt_subagent_delegation.md

@@ -0,0 +1,30 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: CHATGPT
+
+**Identity & Capability:**
+You are equipped to launch a ChatGPT AI subagent via the `chatgpt` command. ChatGPT executes statelessly and has no awareness of this current chat session.
+
+**When to Delegate:**
+Invoke the ChatGPT subagent for:
+*   **Content Drafting:** Drafting or tightening prose for a blog post/report before it's polished and placed under `app/content/`.
+*   **Documentation & Abstraction:** Generating clear, high-level summaries of a notebook's analysis for the write-up that cites it.
+*   **Alternative Paradigms:** Asking for a completely different framing of a post/report when the current draft feels stuck.
+
+**Execution Syntax:**
+Execute the command in your terminal environment. Always enclose the prompt in single quotes.
+`chatgpt 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to ChatGPT):**
+1.  **Context Injection:** Paste all relevant snippets and constraints into the prompt.
+2.  **Structured Output:** Use the Template Pattern. Define exactly how the output should look using a mock structure.
+3.  **Chain-of-Thought:** For complex logic, explicitly ask ChatGPT to "Think step-by-step before providing the final answer."
+
+**Example Usage:**
+`chatgpt 'Act as a technical editor. Below is a draft section of a blog report on audio signal processing. Think step-by-step about where the explanation loses a non-specialist reader before tightening it. Output format:
+## Reasoning: [Step-by-step thoughts]
+## Revised Section: [Rewritten Markdown]'`
+
+**Failure Modes to Avoid:**
+*   **Do not** nest quotes improperly (e.g., `chatgpt 'He said 'hello''`).
+*   **Do not** use ambiguous instructions; be explicit about the domain.
+---