docs: add AGENTS instructions
This commit is contained in:
@@ -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.
|
||||||
Reference in New Issue
Block a user