hudra/AGENTS.md

Hudra
Purpose

Hudra is a browser extension that turns structured QLearn lesson pages into a clean, classroom-friendly presentation.

Hudra presents existing QLearn content in a slide-oriented or presentation-oriented format.

It is not a QLearn page editor.

Core product promise

Hudra should allow a teacher to open an existing QLearn lesson and present it clearly without rebuilding the content in separate presentation software.

The original QLearn page remains the source of truth.

Responsibilities

Hudra may:

detect supported QLearn lesson pages;
identify presentation sections from page structure;
interpret supported headings as presentation boundaries;
present page content in a slide-like view;
provide previous and next navigation;
support keyboard navigation;
provide fullscreen or classroom presentation modes;
display progress through the presentation;
preserve embedded content where practical;
provide graceful fallback behaviour for unsupported elements;
restore the normal QLearn page when presentation mode closes;
remember appropriate user preferences.
Product boundaries

Hudra must not:

edit or permanently rewrite QLearn page content;
save changes into the QLearn editor;
become a general page-formatting tool;
add teacher notes to the source page;
become a general distraction-removal extension;
duplicate Pendra’s editing features;
duplicate Lildra’s general focus-mode features;
require users to rebuild lessons specifically for Hudra unless a documented structure is necessary.
Relationship to other Napper applications
Lildra

Lildra reduces surrounding QLearn clutter while leaving the content in its original continuous-page form.

Hudra provides a presentation experience.

A feature belongs in Hudra when it is specifically useful while presenting lesson content.

Pendra

Pendra helps teachers edit, structure and enhance QLearn pages.

Hudra may interpret structure created by Pendra, but it must not perform Pendra’s editing work.

Content interpretation

Hudra should rely on semantic page structure wherever possible.

Preferred signals include:

valid heading hierarchy;
clearly defined content sections;
predictable QLearn content containers;
explicit Hudra-compatible markers only where normal semantic structure is insufficient.

Do not rely unnecessarily on fragile visual selectors or exact class names.

QLearn may change its DOM structure. Detection should therefore be defensive and easy to update.

Behaviour principles
Never permanently alter lesson content.
Presentation mode must be reversible.
Closing Hudra should restore the original page state.
Missing elements must not cause the entire extension to fail.
Unsupported content should remain visible where possible.
Avoid hiding important content silently.
Provide clear feedback when a page cannot be presented reliably.
Do not activate on unrelated pages.
Avoid interfering with normal QLearn controls when Hudra is inactive.
User experience

Hudra should feel calm, predictable and suitable for classroom use.

Prioritise:

large readable content;
clear navigation;
minimal controls;
obvious presentation state;
reliable keyboard interaction;
smooth restoration of the normal page;
minimal setup.

Avoid:

crowded toolbars;
unnecessary configuration;
distracting animation;
ambiguous icons;
features unrelated to presenting content.
Accessibility
Preserve meaningful heading and document structure where practical.
Maintain keyboard navigation.
Ensure controls have accessible names.
Use sufficient colour contrast.
Avoid relying on colour alone to convey state.
Preserve alternative text for images.
Do not remove captions or transcripts from embedded content.
Avoid trapping keyboard focus.
Technical principles
Prefer plain JavaScript, HTML and CSS.
Avoid unnecessary frameworks and dependencies.
Keep the extension independently installable.
Request only the permissions Hudra genuinely needs.
Do not include remote executable code.
Do not include API keys, passwords or private credentials.
Validate DOM elements before accessing them.
Isolate QLearn selectors and detection logic where practical.
Avoid duplicated selectors across multiple files.
Use clear, descriptive names.
Keep functions focused.
Add comments only when behaviour is not obvious.
Remove temporary debugging output before release.
QLearn safety

Hudra operates inside an external platform that may change without notice.

Code must:

check that expected elements exist;
handle missing or changed selectors;
avoid assumptions about a single page layout;
fail without breaking the underlying QLearn page;
avoid deleting source elements;
avoid destructive DOM operations;
retain enough state to restore the original page;
document selectors that are especially fragile.
Permissions and privacy

Hudra should request the smallest possible set of browser permissions.

Any stored data should normally be limited to local preferences, such as:

display options;
presentation preferences;
last-used settings.

Do not collect or transmit:

student information;
lesson content;
QLearn credentials;
browsing history;
analytics;
personal data;

unless the repository documentation and privacy policy are deliberately updated to reflect verified behaviour.

Repository expectations

The repository should contain:

README.md
AGENTS.md
CHANGELOG.md
manifest.json
source files
icons
release tooling
relevant documentation
tests where practical

Generated release packages should not be committed unless there is a deliberate reason.

Release output should remain ignored through .gitignore.

Versioning

Hudra uses its own version number.

Use semantic versioning where practical:

patch: fixes without new user-facing capability;
minor: backwards-compatible features;
major: substantial or potentially disruptive changes.

The version in manifest.json must match the intended release.

Use release tags such as:

v0.9.3
v1.0.0
v1.1.0

Release packages should use names such as:

Hudra-v1.0.0.zip
Release requirements

Before preparing a release:

Confirm the manifest version.
Review requested permissions.
Run available checks and tests.
Test Hudra manually on representative QLearn pages.
Test activation and deactivation.
Test keyboard navigation.
Test fullscreen behaviour if supported.
Confirm the normal QLearn page is restored correctly.
Check the extension package contains only required runtime files.
Exclude development files, previous releases and generated folders.
Update CHANGELOG.md.
Update documentation when behaviour changes.
Identify remaining manual testing requirements.
Codex working rules

When asked to implement a feature:

Inspect the relevant implementation before editing.
Confirm that the feature belongs within Hudra’s scope.
Prefer the smallest reliable change.
Do not broaden permissions without explaining why.
Do not silently change public behaviour.
Preserve compatibility with existing structured pages where possible.
Update documentation and changelog entries when appropriate.
Run available validation.
Summarise changes clearly.
State what still requires testing inside QLearn.

When asked to review the repository:

distinguish confirmed defects from possible risks;
do not rewrite functioning code solely for stylistic preference;
identify fragile QLearn selectors;
identify destructive or irreversible DOM changes;
identify unnecessary permissions;
identify files accidentally included in release packages;
identify differences between documented and actual behaviour.