From d21f8e6080531c426bb8f51a4198740301b915e7 Mon Sep 17 00:00:00 2001
From: Margaret <margaret@hobbs.farm>
Date: Tue, 3 Feb 2026 15:15:16 +0000
Subject: [PATCH] docs: Add CHANGELOG.md and CONTRIBUTING.md

---
 CHANGELOG.md    |  52 +++++++++++++++++++
 CONTRIBUTING.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 181 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..4bf4577
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to the Android Kiosk Browser project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0-MVP] - 2026-02-03
+
+### Added
+- **Fullscreen WebView browser** with immersive mode (hides status & navigation bars)
+- **URL whitelist system** with proper domain boundary matching
+- **Configurable homepage** URL via admin settings
+- **Lock Task Mode** support for full kiosk lockdown
+- **Admin PIN protection** (default: 1234) with 3-tap corner unlock
+- **Auto-launch on boot** via RECEIVE_BOOT_COMPLETED receiver
+- **Idle timeout** with automatic return to homepage and session clearing
+- **Admin settings panel** for runtime configuration
+- **29 unit tests** covering whitelist, idle timer, and config validation
+
+### Security
+- Fixed whitelist bypass vulnerability (`hobbs.farm.evil.com` attack vector)
+- Proper domain boundary checking: `host == domain || host.endsWith(".$domain")`
+
+### Documentation
+- README.md with setup instructions
+- TESTING.md with comprehensive QA checklist
+- IMPROVEMENTS.md with code review findings
+
+### Technical Details
+- **Language:** Kotlin
+- **Min SDK:** 21 (Android 5.0+)
+- **Target SDK:** 34
+- **Dependencies:** AndroidX Core, AppCompat, WebKit, Preference
+
+---
+
+## Future Releases (Planned)
+
+### [1.1.0] - Remote Management
+- Remote configuration updates
+- Usage analytics
+- Centralized device management
+
+### [1.2.0] - Multi-Profile
+- Multiple whitelist profiles
+- Scheduled profile switching
+- Digital signage mode
+
+---
+
+*Maintained by the hobbs.farm team: Pluto 🪐, Spirit 👻, Margaret 🌸*
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..7cb9807
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,129 @@
+# Contributing to Android Kiosk Browser
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+### Prerequisites
+- Android Studio (latest stable)
+- JDK 17+
+- Android SDK (API 21+)
+- Git
+
+### Setup
+```bash
+# Clone the repository
+git clone https://git.hobbs.farm/pluto/android-kiosk-browser.git
+cd android-kiosk-browser
+
+# Open in Android Studio
+# File → Open → select project directory
+
+# Build
+./gradlew build
+
+# Run tests
+./gradlew test
+```
+
+## Development Workflow
+
+### Branching Strategy
+- `main` — Stable release branch
+- `feature/*` — New features
+- `fix/*` — Bug fixes
+- `docs/*` — Documentation updates
+
+### Making Changes
+
+1. **Create a branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes**
+   - Follow existing code style (Kotlin conventions)
+   - Add tests for new functionality
+   - Update documentation as needed
+
+3. **Test your changes**
+   ```bash
+   ./gradlew test
+   ./gradlew lint
+   ```
+
+4. **Commit with clear messages**
+   ```bash
+   git commit -m "feat: Add new whitelist import feature"
+   ```
+
+5. **Push and create a PR**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+### Commit Message Format
+Use conventional commits:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation only
+- `test:` Adding/updating tests
+- `refactor:` Code refactoring
+- `chore:` Maintenance tasks
+
+## Code Guidelines
+
+### Kotlin Style
+- Use Kotlin idioms (let, apply, etc.)
+- Prefer immutability (`val` over `var`)
+- Use meaningful variable names
+- Keep functions small and focused
+
+### Testing
+- All new features need unit tests
+- Security-related code needs extra test coverage
+- Run the full test suite before submitting
+
+### Security
+- Never store sensitive data in plain text
+- Validate all user inputs
+- Test for bypass vulnerabilities (see `WhitelistTest.kt`)
+
+## Project Structure
+
+```
+app/src/main/
+├── java/farm/hobbs/kioskbrowser/
+│   ├── KioskActivity.kt      # Main WebView activity
+│   ├── AdminActivity.kt      # Settings panel
+│   ├── BootReceiver.kt       # Auto-start on boot
+│   └── KioskDeviceAdminReceiver.kt
+└── res/
+    ├── layout/               # UI layouts
+    ├── values/               # Strings, themes
+    └── xml/                  # Device admin config
+
+app/src/test/
+└── kotlin/farm/hobbs/kioskbrowser/
+    ├── WhitelistTest.kt
+    ├── IdleTimerTest.kt
+    └── ConfigValidationTest.kt
+```
+
+## Reporting Issues
+
+Use Vikunja (vikunja.hobbs.farm) for issue tracking:
+- **P0** — Critical/security issues
+- **P1** — Important features/bugs
+- **P2** — Nice-to-have improvements
+
+## Questions?
+
+Reach out to the team:
+- **Pluto** 🪐 — Project coordination, infrastructure
+- **Spirit** 👻 — Testing, code review
+- **Margaret** 🌸 — Documentation, requirements
+
+---
+
+*Happy contributing! 🚀*