Add project documentation and repository structure

docs/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# Hudra Architecture
+
+## Overview
+
+Hudra is a Manifest V3 browser extension that presents the existing DOM of an
+HTML lesson.
+
+It does not convert the lesson into a proprietary format.
+
+## Slide detection
+
+The current presentation model uses HTML headings:
+
+- H1 identifies the lesson title
+- H2 identifies the beginning of a new slide
+- content following an H2 belongs to that slide until the next H2
+
+## Main components
+
+### background.js
+
+Handles extension-level behaviour and presentation launch logic.
+
+### controls.html
+
+Provides the presenter dashboard interface.
+
+### controls.css
+
+Styles the presenter controls.
+
+### controls.js
+
+Manages presenter navigation, controls and audience communication.
+
+### presenter.js
+
+Creates and manages the audience presentation experience.
+
+### manifest.json
+
+Defines the extension metadata, permissions and version.
+
+## Design constraints
+
+Hudra should avoid:
+
+- cloning complex media unnecessarily
+- fragile LMS-specific DOM assumptions
+- large content-detection systems
+- destructive modification of the original lesson
+
+New media features should be implemented and tested independently.

docs/DECISIONS.md

@@ -0,0 +1,31 @@
+# Hudra Development Decisions
+
+## Decision 001 — HTML is the source of truth
+
+Hudra presents the existing lesson rather than requiring teachers to maintain
+a separate presentation.
+
+## Decision 002 — No proprietary lesson format
+
+Teachers should continue authoring normal HTML in QLearn, Canvas or another
+web-based platform.
+
+## Decision 003 — Simplicity over automation
+
+Hudra should avoid complicated content heuristics unless they are reliable and
+provide a clear classroom benefit.
+
+## Decision 004 — Stable features are added incrementally
+
+Media-specific improvements should be developed and tested one at a time.
+
+## Decision 005 — Hudra 0.9.1 is the stable baseline
+
+Hudra 0.9.1 is the known-good version and is tagged in Git as v0.9.1.
+
+## Decision 006 — Public and internal versions may differ
+
+The visible product branding may show a major/minor version such as Hudra 0.9.
+
+The browser extension manifest may use a patch version such as 0.9.1 for
+maintenance and debugging.

docs/VISION.md

@@ -0,0 +1,48 @@
+# Hudra Vision
+
+## Purpose
+
+Hudra turns an existing HTML lesson into a classroom presentation.
+
+It is designed primarily for QLearn and Canvas, while remaining compatible
+with ordinary HTML pages.
+
+## The problem
+
+Teachers transitioning from OneNote and PowerPoint to QLearn often maintain
+two versions of the same lesson:
+
+- the QLearn page used by students
+- the PowerPoint used for classroom presentation
+
+This creates duplicated work and version-control problems.
+
+## The idea
+
+The HTML lesson should be the single source of truth.
+
+Teachers should build the lesson once and use that same lesson:
+
+- in the classroom
+- online
+- for students learning from home
+- as a presentation
+
+## Core message
+
+> Build once. Present everywhere.
+
+## Design principles
+
+Hudra should be:
+
+- simple
+- fast
+- reliable
+- lightweight
+- predictable
+- easy for teachers to understand
+
+Hudra should not introduce a proprietary lesson format.
+
+It should enhance existing lesson content rather than rebuild or convert it.