Bump cypress-io/github-action from 6 to 7

.agent/AGENTS.md

@@ -0,0 +1,67 @@
+# 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.
+
+## 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/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/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.
+---

.agent/gemini/claude_subagent_delegation.md

@@ -0,0 +1,29 @@
+---
+### SUBAGENT DELEGATION PROTOCOL: CLAUDE
+
+**Identity & Capability:**
+You are equipped with a CLI tool to orchestrate a Claude AI subagent via the `claude` command. Claude executes statelessly and has no awareness of this current chat session or your previous outputs.
+
+**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 visually complex layouts (e.g., a new content-listing or data-visualization component).
+*   **Code Review:** Performing rigorous, independent audits of a notebook's analysis logic before it's cited in a report.
+
+**Execution Syntax:**
+Execute the command in your terminal environment. Always enclose the prompt in single quotes to protect shell formatting.
+`claude 'YOUR_COMPREHENSIVE_PROMPT_HERE'`
+
+**Subagent Prompting Rules (How to talk to Claude):**
+1.  **Context Injection:** You MUST paste all relevant snippets, constraints, and current state into the prompt. 
+2.  **Strict Boundaries:** Clearly define what Claude should NOT do to save processing time (e.g., "Do not write explanations, output only the refactored component file").
+3.  **Step-by-Step Prompting:** For complex tasks, instruct Claude to use a `<thinking>` XML block before providing the final answer.
+
+**Example Usage:**
+`claude 'You are an expert TypeScript/React developer. Below is the shape of the front-matter for a report under app/content/reports/. Write a well-typed TS interface for it, and generate a generic React component to render its metadata card. Wrap your reasoning in <thought> tags and output the code in a single markdown block. Context: [INSERT_FRONTMATTER_SHAPE_HERE]'`
+
+**Failure Modes to Avoid:**
+*   **Do not** nest quotes improperly (e.g., `claude 'He said 'hello''`). 
+*   **Do not** ask Claude to perform actions it cannot do (like interacting with your local file system directly). You must parse its text output and perform the file operations yourself.
+*   **Do not** use ambiguous instructions; quantify your requests (e.g., "Provide exactly 2 solutions").
+---

.agent/prompts/architecture_analysis.md

@@ -0,0 +1,8 @@
+# Prompt: Architecture Analysis
+
+Given a request to analyze or propose architecture changes:
+
+1. Read [`.agent/AGENTS.md`](../AGENTS.md) §3 for current module boundaries (`app/`, `src/components/`, `lib/`, `notebooks/`).
+2. Identify which of those boundaries the change affects, and whether it's compatible with a static export (`output: 'export'`) — no server runtime.
+3. Present trade-offs (at least two options) rather than a single prescriptive answer, unless the choice is clear-cut.
+4. Note the migration cost for existing content/pages if the proposal changes how content is loaded or routed.

.agent/prompts/debug.md

@@ -0,0 +1,9 @@
+# Prompt: Debug an Issue
+
+Given a bug report:
+
+1. Reproduce it first — do not attempt a fix from the description alone.
+2. Follow `.agent/workflows/error_debug.md`.
+3. Identify the minimal root cause; explain why the current code produces the wrong result.
+4. Fix and add a regression test.
+5. Report back with: root cause, fix, and what the regression test now guards against.

.agent/prompts/documentation_update.md

@@ -0,0 +1,8 @@
+# Prompt: Documentation Update
+
+Given a request to update documentation:
+
+1. Identify every doc surface affected: `README.md`, `docs/research/*.md`, `.agent/AGENTS.md`, inline comments.
+2. Match the existing tone and structure of the surrounding document — don't introduce a new format for one section.
+3. Verify any commands/code examples actually run against the current codebase before including them.
+4. Check for now-stale links elsewhere in the repo that reference the changed section.

.agent/prompts/feature_implementation.md

@@ -0,0 +1,9 @@
+# Prompt: Feature Implementation
+
+Given a feature request:
+
+1. Restate the feature as concrete acceptance criteria.
+2. Identify which layer(s) it touches (`app/` routing/content, `src/components/`, `lib/`) and read [`.agent/rules/typescript_react.md`](../rules/typescript_react.md).
+3. Propose the smallest design that satisfies the criteria; flag any ambiguity as a question rather than assuming.
+4. Implement with tests written alongside the code, not after (Vitest for components/logic in `test/unit/`, an MSW-backed integration test in `test/integration/` for multi-component flows, Cypress for a new user-facing flow).
+5. Confirm the change still builds as a static export (`npm run build`).

.agent/prompts/master_context.md

@@ -0,0 +1,9 @@
+# Master Context Prompt
+
+You are working in ACFHarbinger's personal website: a statically-exported Next.js/React/TypeScript blog. Before making changes:
+
+1. Read [`.agent/AGENTS.md`](../AGENTS.md) for the project's stack, module boundaries, and coding standards.
+2. Follow the per-topic rules in [`.agent/rules/`](../rules/) and the workflow in [`.agent/workflows/`](../workflows/) matching the task type.
+3. Remember the site is a fully static export deployed to GitHub Pages — no server runtime, no API routes.
+
+If a requested change implies something the site can't do statically (a server-side secret, a database, a live API route), say so rather than inventing a workaround.

.agent/prompts/refactory_safety.md

@@ -0,0 +1,9 @@
+# Prompt: Safe Refactor
+
+Given a refactor request:
+
+1. Confirm test coverage exists for the code being touched; add characterization tests first if not.
+2. Follow `.agent/workflows/code_refactor.md` — mechanical changes only, no behavior changes in the same commit.
+3. Run the full test suite for the affected module(s) before and after.
+4. List every call site updated, so the diff is auditable against the stated scope.
+5. Flag anything that looked risky enough to warrant a human second look.