# AGENTS.md

## Project purpose

This repository contains the public website for the Napper application ecosystem. It includes the main `napper.au` landing site, the Hudra and Lildra product sites, and shared legal, privacy, support and ecosystem content.

## Source of truth

The repository is the source of truth, not individual conversations or AI sessions.

When an important architectural, deployment, naming or development decision is made:

1. update the appropriate repository documentation;
2. update this file when the guidance affects AI contributors;
3. avoid relying on undocumented conversational context.

## Product distinction

- Hudra is primarily a presentation and slide-viewing system that turns complete QLearn lesson pages into a classroom presentation experience. Do not describe Hudra as a general-purpose editor.
- Lildra is a distraction-free reading extension that hides the surrounding Canvas/QLearn interface while preserving the lesson DOM, content and styling. It is not a presentation system.

Keep product wording within these boundaries and do not reuse Lildra's clutter-removal positioning as Hudra's primary message.

## Future-product publication

- Do not mention future products on the public website unless their inclusion is part of an explicit teaser or launch decision.
- An approved teaser must define its wording, destination, campaign purpose and publication period.
- Preserve unapproved concepts under `docs/future-products.md`, not in public HTML, CSS or browser JavaScript.

## Current architecture

The site is a dependency-free static site using HTML, CSS and small browser JavaScript files. Do not introduce a framework, package manager, build system or templating engine without an explicit architectural decision.

```text
/
├── index.html
├── css/
│   ├── napper.css
│   ├── hudra.css
│   └── hudra-legal.css
├── js/
│   ├── napper.js
│   └── hudra.js
├── img/
└── hudra/
    ├── index.html
    ├── support/index.html
    ├── privacy/index.html
    └── terms/index.html
```

Hudra provides the established foundational product-page and legal-page styling. Lildra reuses that stable foundation through its own theme stylesheets and keeps Lildra-specific colours and visuals isolated there. Reassess this CSS layering before adding another product rather than creating another product-to-product dependency.

## Deployment assumptions

- The repository is `napper/site` and is deployed to `napper.au`.
- A push to `main` triggers automatic deployment.
- Gitea sends a signed webhook to the CloudPanel server.
- `dploy` creates a release and switches the site's `current` symlink.
- CloudPanel serves `/home/napper/htdocs/napper.au/current`.
- The production server supports directory URLs such as `/hudra/privacy`, resolving them to the relevant `index.html`.
- Pages and assets use root-relative paths and assume deployment at the domain root.

Do not expose webhook secrets, credentials or other server-specific private data.

## Canonical external locations

- QLearn: `https://qlearn.eq.edu.au`
- Gitea organisation: `https://git.napper.au/napper`
- Hudra Chrome Web Store: `https://chromewebstore.google.com/detail/hudra/bjggdeecklhnpebgmjiaedaadmpdoddm`
- Hudra Microsoft Edge Add-ons: `https://microsoftedge.microsoft.com/addons/detail/hudra/aogdgaofdldbpmkjknklojbhcbcfandb`
- Lildra Chrome Web Store: `https://chromewebstore.google.com/detail/lildra/plgcccpjkfeimphghbpojjmibmajgocp`
- Lildra Microsoft Edge Add-ons: `https://microsoftedge.microsoft.com/addons/detail/lildra/lecbknefoekmfockhhkjopjgkoepdbnh`
- Hudra releases: `https://git.napper.au/napper/hudra/releases`
- Lildra releases: `https://git.napper.au/napper/lildra/releases`

## Working principles

- Keep the site simple and maintainable.
- Prefer conventional web technologies over unnecessary frameworks.
- Avoid dependencies unless they provide a clear benefit.
- Preserve accessibility, responsive design and fast page loads.
- Reuse shared styles and components where practical.
- Keep each application page focused on what the application does.
- Do not expose secrets, credentials or server-specific private data.
- Keep deployment configuration documented and reproducible.

## Expected workflow

1. Review existing documentation before changing architecture.
2. Make focused changes.
3. Test locally where possible.
4. Update documentation when behaviour or structure changes.
5. Commit using a clear, descriptive message when a commit is requested.