From 94a82eac076bf0c557151935ed106887c67f2ec9 Mon Sep 17 00:00:00 2001 From: Kaden Napper Date: Sun, 26 Jul 2026 14:32:55 +1000 Subject: [PATCH] docs: add AGENTS instructions --- AGENTS.md | 242 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..72f3961 --- /dev/null +++ b/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. \ No newline at end of file