webmaven · webmaven · Jan 14, 2026 · Jan 14, 2026 · Jan 14, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -21,6 +21,20 @@ The project's roadmap is outlined in the `README.md` file. However, for day-to-d
 
 -   **Issue tracker > Roadmap**: The issue tracker is more tactical and pragmatic and takes precedence over the roadmap, which is more strategic and aspirational.
 
+## Documentation
+
+### CONTRIBUTING.md
+
+The [`CONTRIBUTING.md`](./CONTRIBUTING.md) file contains instructions for setting up the development environment, running tests, and submitting pull requests. If you make changes to the development process, build steps, or quality checks, you must update this file accordingly.
+
+### CHANGELOG.md
+
+The [`CHANGELOG.md`](./CHANGELOG.md) file tracks the project's version history. For any user-visible changes, such as new features, bug fixes, or performance improvements, you must add an entry to the "Unreleased" section of this file.
+
 ## Programmatic checks
 
-Currently, there are no programmatic checks. This section can be updated in the future to include any checks that can be run to verify the quality of the code.
+To ensure code quality, the following checks are in place. These should be run before submitting any changes.
+
+-   **Tests**: Run the test suite with `hatch run pytest`.
+-   **Linting**: Check the code for style issues with `hatch run ruff check .`.
+-   **Type Checking**: Verify the type hints with `hatch run mypy .`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this 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).
+
+## [Unreleased]
+
+### Added
+- Table of contents display.
+- Project documentation (`CONTRIBUTING.md`, `CHANGELOG.md`, `AGENTS.md`).
+- Custom exception hierarchy for error handling.
+- `LICENSE` file (Apache 2.0).
+
+### Changed
+- Updated documentation for accuracy and completeness.
+
+## [0.1.0] - 2025-12-21
+
+### Added
+
+- Initial release of the Imposition library.
+- Core functionality for parsing EPUB files.
+- Basic rendering of EPUB content in a web page.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing to Imposition
+
+First off, thank you for considering contributing to Imposition! It's people like you that make open source such a great community.
+
+We welcome contributions of all kinds, from bug reports and feature requests to code and documentation.
+
+## How to Contribute
+
+### Reporting Bugs
+
+If you find a bug, please [open an issue](https://github.com/webmaven/imposition/issues) on our GitHub issue tracker. Please provide a clear and descriptive title, a detailed description of the problem, and steps to reproduce the bug.
+
+### Suggesting Enhancements
+
+If you have an idea for an enhancement, please [open an issue](https://github.com/webmaven/imposition/issues) to discuss it. We're always open to new ideas!
+
+### Pull Requests
+
+If you'd like to contribute code, please follow these steps:
+
+1.  Fork the repository and create a new branch for your feature or bug fix.
+2.  Set up your development environment (see below).
+3.  Make your changes, and be sure to add or update tests as appropriate.
+4.  Ensure that all tests, linting, and type checks pass.
+5.  Open a pull request with a clear description of your changes.
+
+## Development Setup
+
+This project uses [Hatch](https://hatch.pypa.io/latest/) to manage dependencies and virtual environments.
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/webmaven/imposition.git
+    cd imposition
+    ```
+
+2.  **Create the development environment:**
+    ```bash
+    hatch env create
+    ```
+
+3.  **Activate the virtual environment:**
+    ```bash
+    hatch shell
+    ```
+
+## Building the Package
+
+To build the wheel for use with Pyodide:
+
+```bash
+hatch build
+```
+
+This will create a `dist` directory containing the wheel file.
+
+## Quality Checks
+
+Before submitting a pull request, please ensure that your changes pass all of our quality checks. The package must be built before running the tests, as the end-to-end tests require the built wheel.
+
+### Running Tests
+
+This project uses [pytest](https://pytest.org/) for testing. To run the test suite:
+
+```bash
+hatch run pytest
+```
+
+To run the tests with coverage reporting:
+
+```bash
+hatch run pytest --cov=src/imposition
+```
+
+### Linting
+
+This project uses [Ruff](https://beta.ruff.rs/docs/) for code linting. To run the linter:
+
+```bash
+hatch run ruff check .
+```
+
+### Type Checking
+
+This project uses [mypy](http://mypy-lang.org/) for static type checking. To run the type checker:
+
+```bash
+hatch run mypy .
+```
diff --git a/README.md b/README.md
@@ -38,112 +38,17 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## Development Setup
+## Contributing
 
-To set up a development environment, clone the repository and use [Hatch](https://hatch.pypa.io/latest/) to manage dependencies.
+Contributions are welcome! Please see the [Contributing Guidelines](CONTRIBUTING.md) for more information on how to get started.
 
-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/webmaven/imposition.git
-   cd imposition
-   ```
+## Changelog
 
-2. **Create the development environment:**
-   ```bash
-   hatch env create
-   ```
+For a detailed list of changes, please see the [Changelog](CHANGELOG.md).
 
-3. **Activate the environment:**
-   ```bash
-   hatch shell
-   ```
+## License
 
-4. **Run tests:**
-   ```bash
-   pytest
-   ```
-
-## Building
-
-To build the wheel for use with Pyodide, use the following command:
-
-```bash
-hatch build
-```
-
-This will create a `dist` directory with the wheel file (`imposition-0.1.0-py3-none-any.whl`).
-
-## Testing
-
-### Prerequisites
-
-Before running tests, ensure you have the following installed:
-
-1. **Python 3.13+** (or compatible version)
-2. **pytest** and **pytest-playwright**:
-
-   ```bash
-   pip install pytest pytest-playwright
-   ```
-
-3. **Playwright browsers** (Chromium is required for E2E tests):
-
-   ```bash
-   python -m playwright install chromium
-   ```
-
-### Building the Package
-
-The E2E tests require a built wheel package. Build it using:
-
-```bash
-pip install build
-python -m build --wheel
-```
-
-This creates `dist/imposition-0.1.0-py3-none-any.whl`, which is loaded by the demo page during testing.
-
-### Running Tests
-
-Run all tests with:
-
-```bash
-python -m pytest -v
-```
-
-For more detailed output:
-
-```bash
-python -m pytest -vv
-```
-
-### Test Coverage
-
-The current test suite includes:
-
-- **E2E Test** (`tests/test_e2e.py`): Tests the complete workflow of loading an EPUB file in a browser using Pyodide, rendering it in an iframe, and verifying the content is visible.
-
-### Test Artifacts
-
-Tests generate the following artifacts:
-
-- **Screenshots**: `tests/screenshots/` - Contains screenshots of test runs (both passed and failed)
-- **Wheel Package**: `dist/imposition-0.1.0-py3-none-any.whl` - Built package for Pyodide
-
-### Troubleshooting
-
-**Test fails with "404 - File not found" for the wheel:**
-
-- Make sure you've built the package first with `python -m build --wheel`
-
-**Test fails with "playwright: command not found":**
-
-- Install Playwright browsers: `python -m playwright install chromium`
-
-**Test times out waiting for iframe:**
-
-- Check that the HTTP server is running properly
-- Verify that Pyodide can load from the CDN (requires internet connection)
+This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
 
 ## Error Handling
 
@@ -168,7 +73,7 @@ except ImpositionError as e:
 
 For a detailed competitive analysis and the strategic reasoning behind this roadmap, please see [`COMPETITIVE_ANALYSIS.md`](./COMPETITIVE_ANALYSIS.md).
 
-The following is a prioritized roadmap for the `Imposition` library, based on a competitive analysis of existing EPUB libraries.
+**Note:** The following roadmap is a strategic overview. For the most up-to-date list of priorities, please see the [GitHub issue tracker](https://github.com/webmaven/imposition/issues).
 
 ### Phase 1: Minimum Viable Product (MVP)