docs: add AGENTS instructions

AGENTS.md

@@ -0,0 +1,242 @@
+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.