site/AGENTS.md

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. Pendra is planned but does not yet have a product page.

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.
• Pendra is planned as a simpler path for bringing completed presentation slides into QLearn.

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

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.

/
├── 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 Pendra 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.