# Project: Custom Font Homebrew Tap

This document describes the repository for Cursor, other LLMs, and automation agents. Read this first to understand structure, conventions, and workflows.

## LLM / agent context files (conventions)

This repo follows common conventions so multiple tools can discover project context:

| File | Used by |
|------|--------|
| **PROJECT.md** (this file) | Canonical project description; any LLM or agent. |
| **.cursorrules** | [Cursor](https://cursor.com): root-level rules; points to PROJECT.md. |
| **.github/copilot-instructions.md** | [GitHub Copilot](https://docs.github.com/en/copilot) (VS Code, Visual Studio, GitHub.com): workspace instructions; references PROJECT.md. |
| **.claude/skills/project-context/SKILL.md** | [Claude Code](https://code.claude.com) / [Claude Agent SDK](https://docs.anthropic.com/en/docs/agent-sdk/overview): project skill; references PROJECT.md. |

When adding or changing project rules, update **PROJECT.md** first, then sync the tool-specific files above if needed.

## What This Repo Is

A **Homebrew tap** that serves a personal collection of fonts. Users add the tap once, then install fonts with `brew install font-<name>`. The repo is the tap source: it contains font assets and Homebrew Formula (Ruby) files that install them.

- **Tap name (from README):** `genet-godzilla/fonts`
- **Install flow:** `brew tap ...` → `brew install font-<name>`

## Repository Layout

```
custom_font_tap/
├── PROJECT.md              # This file — canonical project overview for LLMs/agents
├── .cursorrules            # Cursor: root rules (points here)
├── .github/
│   └── copilot-instructions.md   # GitHub Copilot / VS Code
├── .claude/skills/project-context/
│   └── SKILL.md            # Claude Code / Agent SDK
├── README.md               # User-facing install instructions
├── .gitignore
├── font_files/             # Canonical font data (one folder per font)
│   └── font-<name>/        # Each font: ttf/, otf/, web/, other_files/
├── Formula/                # Homebrew formulae (*.rb), one per font
├── To Sort/                # Staging: new downloads not yet in font_files
├── .fontfoldercleanup/     # Scripts to organize folders and generate formulae
└── .cursor/rules/          # Cursor rule(s) for font folder structure
```

## Font Folder Structure (Required)

Every font lives in `font_files/` in a folder named **`font-<name>`**. Inside that folder only these four subdirectories are allowed:

| Directory     | Purpose |
|---------------|--------|
| `ttf/`        | `.ttf` files |
| `otf/`        | `.otf` files |
| `web/`        | `.woff`, `.woff2`, `.eot`, `.svg` |
| `other_files/`| Everything else (licenses, PDFs, docs, etc.) |

- All font folders **must** use the `font-` prefix.
- No other top-level files or dirs; anything else goes under `other_files/`.
- The rule and cleanup script are documented in `.cursor/rules/font-folder-structure.mdc`.

## Key Files and Scripts

| Path | Purpose |
|------|--------|
| `.fontfoldercleanup/cleanup_font_folders.py` | Organizes a font tree into `ttf/`, `otf/`, `web/`, `other_files/`. Run with `--path` (default `../font_files` relative to script). |
| `.fontfoldercleanup/create_homebrew_formula.py` | Scans `font_files/` for `font-*` dirs and writes/updates one `.rb` per font in `Formula/`. |
| `.fontfoldercleanup/tap_config.rb` | Reference tap config (meta-formula); not the main installer. |
| `Formula/font-<name>.rb` | Generated; do not edit by hand. Class name is `Font<Name>` with formula name normalized (e.g. `font-graham_hand` → `FontGraham_hand`). |

## Workflows

### Adding a new font

1. Get the font (e.g. extract a zip) into **`To Sort/`** or a temp folder.
2. Rename the folder to **`font-<name>`** (lowercase, hyphens for spaces).
3. Move the folder into **`font_files/`**.
4. Run the cleanup script so files go into `ttf/`, `otf/`, `web/`, `other_files/`:
   - From repo root:  
     `python3 .fontfoldercleanup/cleanup_font_folders.py --path font_files`  
   - Or from `.fontfoldercleanup/`:  
     `python3 cleanup_font_folders.py --path ../font_files`
5. Generate/update the formula:  
   `python3 .fontfoldercleanup/create_homebrew_formula.py`
6. Commit `font_files/font-<name>/` and `Formula/font-<name>.rb`.

### Regenerating all formulae

From repo root:

```bash
python3 .fontfoldercleanup/create_homebrew_formula.py
```

This overwrites Formula files for every `font-*` directory in `font_files/`.

### Only reorganizing folders (no formula changes)

Point the cleanup script at the directory that contains font folders (e.g. `font_files` or a folder under `To Sort/`):

```bash
python3 .fontfoldercleanup/cleanup_font_folders.py --path font_files
```

## Formula Conventions

- **File:** `Formula/font-<name>.rb` (e.g. `font-pixelon.rb`, `font-graham_hand.rb`).
- **Class:** `Font<Name>` where `<Name>` is the part after `font-`, with hyphens/underscores kept as in the folder name (e.g. `FontGraham_hand`, `FontMba-slice-mono`).
- **Source:** Formulae assume the archive unpacks as `homebrew-fonts-main/` and fonts live under `homebrew-fonts-main/font_files/font-<name>/`.
- **Comment in formulae:** "This file was generated by the font folder cleanup script — Do not edit this file directly." Edits should go in the generator (`.fontfoldercleanup/create_homebrew_formula.py`) or in font folder structure/scripts.

## Technical Notes

- **Python:** Scripts are Python 3, standard library only (pathlib, shutil, argparse).
- **Ruby:** Formulae are standard Homebrew Formula; they use `share/"fonts/truetype"`, etc., and optional `share/"<formula_name>"` for `other_files` content.
- **Homebrew URL in formulae:** `http://clancy.genet-godzilla.ts.net:3002/Fonts/homebrew-fonts/archive/main.tar.gz` (may need updating if the server or repo path changes).
- **Ignored (`.gitignore`):** `*.ofm`, `*.cfg`, `*.g2n`, `.DS_Store`, `.setup_complete`, `.env/`, `.idea/`.

## Quick Reference for Agents

- To **add a font:** ensure a `font-<name>` folder exists in `font_files/` with the required four subdirs and files in the right places; run `cleanup_font_folders.py` then `create_homebrew_formula.py`.
- To **fix folder structure:** run `cleanup_font_folders.py` on the directory containing the `font-*` folders.
- To **sync Formula with font_files:** run `create_homebrew_formula.py`; do not edit Formula `*.rb` files by hand.
- **To Sort/** is for unsorted downloads; fonts are only “in the tap” when they are under `font_files/` and have a matching file in `Formula/`.