From f68aa305fa9b3d3ac3907e5c54894c932f720222 Mon Sep 17 00:00:00 2001
From: Adrian Bonpin <adrianbonpin@gmail.com>
Date: Wed, 19 Aug 2026 02:48:31 +0800
Subject: [PATCH] docs: add AGENTS.md agent guide

---
 AGENTS.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7d9522b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,86 @@
+# ISMIS Helper — Agent Guide
+
+Guidance for AI coding agents and contributors working in this repository.
+
+## What this is
+
+A Firefox/Chrome **MV3** extension that automates the USC ISMIS student portal
+(`ismis.usc.edu.ph`): auto-login, privacy-policy auto-accept, and a **Study Load
+PDF** export that visually matches the official document (bundled **Segoe UI**
+fonts, USC logo, course table, units total).
+
+No build step is required for the source itself; `scripts/build.js` only packages
+the two browser variants into `dist/`.
+
+## Commands
+
+```bash
+npm install                       # dev deps (only needed for tests)
+npm test                          # run the test suite (node --test)
+node scripts/build.js all         # build both browser zips -> dist/
+node scripts/build.js firefox     # build just firefox
+node scripts/build.js chrome      # build just chrome
+node scripts/build.js all --version 1.3.0   # versioned zips
+npm run build                     # shorthand for `node scripts/build.js all`
+```
+
+Never edit anything under `dist/` — it is generated and gitignored.
+
+## Repo layout
+
+- `manifest.json` — **Firefox** manifest (the single source of truth). The Chrome
+  manifest is derived at build time.
+- `background.js` — message handler; builds the PDF via `pdf.js` and downloads it.
+  Also has the cross-browser `browser.*`/`chrome.*` alias shim at the top.
+- `content.js` — runs on ismis.usc.edu.ph: auto-login, privacy modal auto-accept,
+  scrapes the study load, injects the on-page **Download PDF** button.
+- `parsers.js` — pure HTML-scraping helpers (study load table, profile page,
+  offered courses, filtering/summing).
+- `pdf.js` — builds the PDF; exports `buildStudyLoadPdf` plus formatting helpers
+  (`compactProgram`, `formatSchedule`, `formatFullName`, `formatTeacher`,
+  `deriveDateRange`, `truncateToWidth`).
+- `popup.html` / `popup.js` / `popup.css` — settings UI (profiles, master toggle,
+  PDF settings like truncation and Year Level).
+- `libs/` — vendored `pdf-lib.min.js` and `fontkit.min.js` (needed to embed the
+  custom Segoe UI fonts).
+- `assets/` — the transparent PNG logo and `fonts/Segoe-UI*.ttf`.
+- `icons/` — 16/32/48/128 extension icons.
+- `scripts/build.js` — zero-dependency packaging script for both browsers.
+- `.gitea/workflows/build.yml` — Gitea Actions: builds + tests on push, creates a
+  Gitea Release with both zips when a `v*` tag is pushed.
+- `test/` — `node --test` suite (`pdf.test.js`, `parsers.test.js`).
+
+## Build model (Firefox vs Chrome)
+
+- The **root is the Firefox source**: `manifest.json` uses `background.scripts`
+  (multiple files) and `browser.*` APIs.
+- The **Chrome build** derives a manifest with
+  `"background": { "service_worker": "background.chrome.js" }` and assembles that
+  single worker by concatenating, in order:
+  `libs/fontkit.min.js` → `libs/pdf-lib.min.js` → `pdf.js` → `background.js`.
+- The cross-browser shim (top of `background.js`, `content.js`, `popup.js`) aliases
+  `browser` to `chrome` when the former is absent. It is a no-op in Firefox.
+- `scripts/build.js` **excludes** `test/`, `docs/`, `scripts/`, `dist/`, and
+  `.git` from the packaged output.
+
+## Conventions & constraints
+
+- Plain ES5+ JavaScript. No framework, no bundler, no build step for the source.
+- Use Promise-based `browser.*` APIs (Chrome MV3 supports `browser.*`; the shim
+  covers builds that only expose `chrome.*`).
+- Login profiles are stored **plaintext** in `browser.storage.local`. At most one
+  profile is enabled at a time; a master `enabled` toggle disables all behavior.
+- The on-page **Download PDF** button must never touch another window's DOM; it
+  sends a message to the background which downloads via
+  `browser.downloads.download({ saveAs: true })` (blob → object URL).
+- If you change `pdf.js` layout constants, verify against the reference PDF
+  (`/Users/adrianbonpin/Downloads/BSIT - Y3S1 - Study Load.pdf`) and re-check the
+  position measurements, since offsets can be font-metric dependent.
+- Keep `docs/` and `dist/` out of git (they are ignored).
+
+## Workflow
+
+1. Run `npm test` before and after changes.
+2. Build (`npm run build`) to make sure both variants assemble.
+3. Manually load `dist/firefox` in Firefox (`about:debugging`) and `dist/chrome`
+   in Chrome (`chrome://extensions`) to verify PDF generation.