source ⟩ AGENTS.md

# AGENTS.md: Instructions for friendly computers and robots

## About the project

This is the source code for *The Satyrs’ Forest*, a small personal website running on my beat-up old laptop, accessible to all at https://satyrs.eu.

## Codebase structure

- ./analytics stores visitor logs, including timestamps, viewed pages, referrers, and user-agents (though no IP addresses or any of that nonsense).
- ./app contains most of the code, written in Javascript.
	- ./app/locales contains localisation data, stored as JS objects; this is used by…
	- ./app/grimm.js is the mess of a library that handles translation and internationalisation for the site, including English, Dutch, Ancient Greek, Chinese, and more!
- ./db contains the Sqlite database for the site
- ./hypertext contains, well, hypertext for the site. This is written in Pug (https://pugjs.org), a nice syntactic sugar bowl of a language that gets rendered to HTML.
	- ./hypertext/admin/planter is a basic CMS for updates to *The Garden*, the site’s blog.

If you (the agent) would like to leave some notes for your future self on a certain part of the codebase, you can place a file named `EUDA-NOTES.txt` in the relevant folder.

## Code style guide

- Prefer arrow functions, as opposed to traditional function expressions
- Tabs, not spaces
- Use `const` and `let`, not `var`
- Liberal use of `.map()`, `.filter()`, `.reduce()`, `.forEach()`, and friends is welcomed, where it’s more efficient than for loops

CSS properties should go in the following order:
- Custom properties
- `content` (if applicable)
- Positioning-related properties, including:
	- `position`
	- `inset-block`, `inset-inline`, &c.
    - `z-index`
- Display, grid, and flex:
	- `display`
	- `flex` and friends
	- `grid-template-columns` and friends
	- `gap`
    - `align-*`, `justify-*`, and friends
- Box model
    - `float`
    - Size (`inline-size`, `max-block-size`, `aspect-ratio`…)
    - Margin
    - Padding
    - Others (`overflow`, `clip`…)
- Typography (`color`, `font-*`, `text-*`, &c, in alphabetical order)
- Visuals (alphabetical order)
- Transitions and animation (alphabetical order)

## “Best” practices

This is a hobby site, so there’s no test directory or anything. Code outside of ./hypertext doesn’t get reloaded on edits, either; I have to manually go into the tmux pane that’s running the site and reset it myself. C’est la vie.

## Translation

If tasked with translating a page, your translations should be fluent, idiomatic, and dynamic, carrying over the page’s original tone.

If no variant of a language is otherwise specified, assume the language’s “original” version: British English, Metropolitan French, European Spanish, European Portuguese, and so on.

For Dutch specifically, translate the gender-neutral singular “they” as “die”, with the possessive “their” as “z’r”. It’s not perfect, but it’ll do.