# AGENTS.md

## Project Overview

Static Vue.js web app that generates privacy policies and Terms & Conditions for Android, iOS, and web apps. The build creates one `index.html` file. It uses no bundler or hot reload. The build toolchain is pure Go (`cmd/build/`): it renders Go `text/template` files, converts YAML to JavaScript, compiles Less, minifies JavaScript, and adds cache-busting values. Node is not required for the build.

## Source Layout

- `src/tpl/` — Go `text/template` files used to build the page; `page.html` is the entry point. The directory contains shared blocks (`head`, `footer`, `mixins`, `meta`, `license-header`, and `css`) plus the page content. Templates use `{{ }}` (Go template delimiters); Vue uses `[[ ]]` delimiters. Put all labels and text through `translate('key')`.
- `src/locales/` — locale JSON files (one per language); `en.json` is the source of truth; `de.json` also exists; `_flag` key for each locale
- `src/tpl/mixins.html` — shared template blocks: `modal()`, `outputButtons()`, `attribution()`, `flycricketDeploy()`, `wizardProgress()`, `wizardMobileLogo()`, `wizardSidebar()`; templates are invoked via `{{template "name" .}}` (carry the page-data dot) or `{{template "name" (dict ...)}}` (map args)
- `src/tpl/meta.html` — meta partials (`metaBase`, `metaAppDescription`, `metaAuthor`, `metaWebappSupport`, `metaFavicon`, `metaDataTag`, `metaLinkPreview`)
- `src/tpl/css.html` — CSS includes (inline normalize/bulma, preload sidebar image, stylesheet link)
- `src/tpl/license-header.html` — GPL license comment block
- `src/tpl/content.html` — includes all content (wizard, privacy policies, T&C, disclaimer, FAQ, affiliate)
- `src/tpl/modals.html` — modal wrappers (privacy simple/no-tracking/gdpr, terms, disclaimer, faq)
- `src/tpl/privacy-simple.html`, `privacy-no-tracking.html`, `privacy-gdpr.html` — privacy policy bodies; all text via `translate('key')`
- `src/tpl/tn-simple.html` — T&C template; all text via `translate('key')`
- `src/tpl/wizard-step-1..8.html` — wizard steps; all labels via `translate('key')`
- `src/tpl/info-modals.html` — Disclaimer/FAQ modals with Vue-controlled visibility; text via `translate('key')`
- `src/tpl/affiliate-flycricket.html` — Flycricket affiliate integration
- `src/js/main.js` — Vue app entry point: creates app with 3 composables (`useAppState`, `useWizard`, `useContent`), registers `translate()`, `_updateMeta()`, `switchLocale()` globally
- `src/js/utils.js` — utility helpers (`convertHtmlToMd`, `getRawHTML`, `getContent`, `getTitle`, `loadInTextView`)
- `src/js/flycricket.js` — Flycricket form submission helper `window.fc_deploy(bodyContentId)` (single function reused by all modal deploy buttons)
- `src/includes/yaml/thirdpartyservices.yml` — 3rd-party service definitions (source of truth); supports locale-aware `name_{code}` fields; JS is auto-generated during build
- `src/includes/vendor/` — vendored third-party assets; each subdirectory mirrors to `public/<subdir>/vendor/` (for example `js/` → `public/js/vendor/`)
- `src/less/style.less` — Less entry point (`@import`s 6 partials); compiled to CSS by Go build
- `src/less/_variables.less` — Less variables (`@color-primary`, `@font-sans`, `@border-radius`, etc.)
- `src/less/_base.less` — Base layout, typography, hero, cards, footer
- `src/less/_scrollbar.less` — Custom scrollbar styles
- `src/less/_overrides.less` — Label, button, input, modal, checkbox overrides
- `src/less/_bg-pattern.less` — `.bg-pattern` SVG data URI background
- `src/less/_dark.less` — Dark theme overrides
- `public/site.webmanifest` — PWA manifest (tracked, edit directly)
- `public/sw.js` — service worker with offline caching (tracked, edit directly)
- `public/404.html` — custom 404 page (tracked, edit directly)
- `public/robots.txt` — robots exclusion (tracked, edit directly)
- `public/humans.txt` — author/tech credits (tracked, edit directly)
- `public/logo.svg` — SVG logo (tracked, edit directly)
- `public/images/third_party_logos/` — third-party service logo images (tracked, add via `add-thirdparty-service` skill)
- `public/images/side_image/` — hero and sidebar graphics (side_image.webp, side_image_dark.webp)
- `public/images/app_graphics/` — app graphics (404.svg, etc.)
- `public/images/app_icons/` — UI icons (disclaimer.svg, etc.)
- `public/favicon*`, `public/apple-touch-icon.png`, `public/android-chrome-*` — favicons and PWA icons
- `public/reviews.html` — generated reviews page (committed for convenience)
- `public/reviews-data.json` — generated reviews data (committed for convenience)
- `public/downloaded_images/` — generated reviews images served as WebP (committed for convenience; source PNGs stay in `tools/reviews-page-generator/downloaded_images/`)
- `public/profile_pictures/` — reviewer profile pictures (gitignored, generated by reviews tool)
- `cmd/build/*.go` — Go build toolchain source files (edit to modify build pipeline); includes `serve.go` (HTTP server for local dev)
- `tests/golden-parity.spec.ts` — served HTML parity tests for English and German
- `tests/golden/` — golden HTML fixtures used by the Playwright parity tests
- `tests/` — Playwright E2E tests (Node.js is used only on demand for testing)
- `tools/reviews-page-generator/` — standalone Go tool that generates the reviews page and its cached data
- `Makefile` — project commands for formatting, building, serving, testing, and deployment

## Build

```sh
make format     # format Go source files
make check      # run Go tests, vet, and build checks
make build      # equivalent: go run ./cmd/build/
```

Compiles `src/` → `public/index.html`, `public/css/style.min.css`, `public/js/*.min.js`. Build outputs are tracked. The build is pure Go — no Node/npm dependency.

Build pipeline:
1. Go compiles `src/less/style.less` → `public/css/style.min.css` via `toakleaf/less.go`
2. Go parses `src/includes/yaml/thirdpartyservices.yml` → `public/tmp/thirdpartyservices.js`
3. Go builds locales registry from `src/locales/` → `public/js/locales.min.js`
4. Go renders `src/tpl/` (`text/template`, entry `page.html`) → `public/index.html`
5. Go minifies every `src/js/*.js` and `public/tmp/*.js` to `public/js/<name>.min.js`
6. Go mirrors each `src/includes/vendor/<type>/` directory to `public/<type>/vendor/`
7. Per-locale: Go renders HTML with `lang` override; Go generates `locale.min.js`
8. Cache-busting: `?v=<md5>` appended to all CSS/JS references in HTML files

Dev: `make serve` (builds then serves `public/` on port 8000 via Go HTTP server). `public/css/vendor/bulma.min.css` is purged out-of-band: run `make purge-css` after template or Bulma class changes, then `make build`. Node.js is required for `purge-css` only.

## Code Conventions

- **No comments** in source code unless documenting a complex legal rationale
- **Commit style**: `type(scope): Description`
- **Vue.js 3** is self-hosted (served from `public/js/vendor/vue.global.prod.js`); uses `[[ ]]` delimiters (configured in `createApp`)
- **Go `text/template`** files use default `{{ }}` delimiters; Vue `[[ variable ]]` mustache interpolation passes through untouched (Vue.js syntax, not Go template syntax)
- **Translation**: use `translate('key')` in templates (global method set in `main.js`), not `$t('key')`
- **Computed properties** in Vue composable `computed()` calls — prefer over inline string matching
- **Derived text** (e.g. `deviceType`, `platformDesc`) computed inside `generate()` following existing pattern, not watchers
- **Compile-time flags** are passed as context fields on `pageData` in `cmd/build/render.go`: `Lang`, `Flycricket`, `NoTracking`, `Gdpr`, `ThemeToggle` (always `true` in the current site)
- **`data-theme`** attribute on `<html>` element; dark mode support via `_dark.less` and `toggleTheme()` in `main.js`
- **Go 1.25** — toolchain uses `github.com/tdewolff/minify/v2` for JS and `gopkg.in/yaml.v3` for YAML parsing

## Testing

Run these checks:

- Run `make format` after Go source changes.
- Run `make check` for Go vet and build checks.
- The Playwright parity test compares served `en`/`de` HTML against `tests/golden/`.
- Run `make check` for all Go, golden, and Playwright checks.
- Node.js is only required for `make check`, `make test-ui`, and `make test-debug`.
- `make check` runs tests, vet, build, and Playwright checks.

## Deployment

```sh
make deploy VERSION="<version>"
```

CI via GitHub Actions (`.github/workflows/`): production deploy on push to `master`, preview deploy on PRs from same repo. Only maintainers can deploy.

## Skills

- `.agents/skills/add-thirdparty-service/` — Load this skill when adding a new 3rd-party service entry.
- `.agents/skills/add-localization/` — Load this skill when adding a new language translation.

## Quick Workflow for Edits

1. Edit templates under `src/tpl/`
2. Run `make format` after Go source changes
3. Run `make build` to produce `public/`
4. Verify `public/` renders correctly (open `public/index.html`)
5. Commit source and build output changes

## Contribution Rules

- Bug fixes only for PRs (features discussed via issue first)
- New 3rd-party service: load the `add-thirdparty-service` skill or manually add entry to `src/includes/yaml/thirdpartyservices.yml` + logo (160×160) to `public/images/third_party_logos/`
- `cmd/build/` is pure Go; the build has no Node dependency (templates live in `src/tpl/`, rendering via `text/template`)
- Build outputs expected (do not remove unless intentional): `public/index.html`, `public/css/style.min.css`, `public/js/*.min.js`, `public/js/vendor/`
- `public/css/vendor/bulma.min.css` is a tracked source file. Re-run `make purge-css` when a change adds Bulma classes the build does not already use.
- `public/sw.js`, `public/site.webmanifest`, `public/404.html`, `public/robots.txt`, `public/humans.txt`, `public/logo.svg` are tracked source files (not generated)
- `public/reviews.html` and `public/reviews-data.json` are generated by `tools/reviews-page-generator/` but tracked for convenience