chore: add agents instructions

Signed-off-by: Emilien Escalle <emilien.escalle@escemi.com>

Author: neilime

AGENTS.md

@@ -0,0 +1,48 @@
+# AGENTS.md — agent instructions and operational contract
+
+This file is written for automated coding agents (for example: Copilot coding agents). It exists to provide a concise operational contract and guardrails for agents working in this repository. It is not the canonical source for design or style rules. Those live in the developer documentation linked below.
+
+## Organization-wide guidelines
+
+(required)
+
+- Follow the prioritized shared instructions in [hoverkraft-tech/.github/AGENTS.md](https://github.com/hoverkraft-tech/.github/blob/main/AGENTS.md) before making any change.
+- Apply the global engineering guidelines from `ACCESSIBILITY.md`, `CONTRIBUTING.md`, and other root-level guides when modifying UI, documentation, or build tooling.
+
+## Quick Start
+
+This repository contains the Hoverkraft-branded Docusaurus theme and its documentation site. Review these entry points before coding:
+
+- **[Overview](README.md#overview)** — Theme purpose, supported use cases, and positioning within the Hoverkraft design system.
+- **[Feature Highlights](README.md#feature-highlights)** — Canonical list of enforced branding capabilities.
+- **[Documentation](README.md#documentation)** — Location of end user docs and how they are published.
+- **[Development](README.md#development)** — Required toolchain, workspace workflow, lint/test commands, and release expectations.
+- **[Contributing](CONTRIBUTING.md)** — Accessibility-first contribution guidelines and review expectations.
+
+## Agent-Specific Development Patterns
+
+### Critical Workflow Knowledge
+
+```bash
+npm install                         # Install workspace dependencies
+npm run build --workspaces          # Build the theme and docs packages
+npm run lint --workspaces           # Run linting across all workspaces
+npm run test --workspaces           # Execute unit tests (ts-jest)
+npm run start --workspace=@hoverkraft/hoverkraft-theme-docs  # Launch docs for local QA
+```
+
+- Prefer `npm` for workspace orchestration. Only switch toolchains when the user explicitly requests it.
+- Run `npm run build --workspaces` before submitting changes that impact published assets.
+
+### Code Quality Expectations
+
+- Maintain strict TypeScript types by updating `packages/theme/src` and generated declarations together.
+- Keep UI/UX changes accessible: audit color contrast, focus management, and screen reader semantics in tandem (see `ACCESSIBILITY.md`).
+- Validate configuration updates with existing tests in `packages/theme/src/__tests__`. Add new Arrange-Act-Assert unit tests for public APIs.
+- Do not bypass linting or formatting rules; they are enforced via `eslint.config.mjs`, Prettier, and `ts-dev-tools` presets.
+
+### Documentation Updates
+
+- Mirror any theme changes in `packages/docs/content` and `packages/docs/src` when user-facing behavior changes.
+- Update `README.md` and relevant guide pages if interfaces, commands, or outputs change.
+- Keep version bumps and changelog notes aligned with the release process defined in `README.md#releasing` once present.

CONTRIBUTING.md

@@ -5,6 +5,11 @@ email, or any other method with the owners of this repository before making a ch
 
 Please note we have a code of conduct, please follow it in all your interactions with the project.
 
+## Development Guidelines
+
+- Make accessibility a first-class concern for every change to the theme. Audit color contrast, focus management, ARIA semantics, keyboard navigation, and screen reader behavior for new or updated components.
+- Validate each contribution in both light and dark modes. Ensure accessible color palettes, imagery, and interactive states meet WCAG AA standards regardless of the active color scheme.
+
 ## Pull Request Process
 
 1. Ensure any install or build dependencies are removed before the end of the layer when doing a

README.md

@@ -1,74 +1,96 @@
-# @hoverkraft/docusaurus-theme
+<div align="center">
+  <h1>@hoverkraft/docusaurus-theme</h1>
+  <p>Strictly opinionated Docusaurus theme that enforces Hoverkraft branding and accessibility standards.</p>
+</div>
 
-A strictly opinionated Docusaurus theme that enforces Hoverkraft branding guidelines for all Hoverkraft documentation projects.
+---
+
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+## Overview
+
+`@hoverkraft/docusaurus-theme` delivers a production-ready Hoverkraft-branded experience for every Docusaurus documentation project. The theme removes customization levers so that every property stays synchronized with the official Hoverkraft design system, accessibility bar, and editorial tone.
+
+## Feature Highlights
+
+- **Enforced branding**: Colors, typography, spacing, and component styling sourced from the [Hoverkraft Branding Guidelines](https://github.com/hoverkraft-tech/branding).
+- **Accessibility-first**: Built to meet WCAG 2.1 Level AA, with detailed practices captured in `ACCESSIBILITY.md`.
+- **Responsive layout**: Mobile-first breakpoints and fluid components covering desktop, tablet, and handset experiences.
+- **Shared components**: Header, footer, hero, feature grid, buttons, and layout primitives with consistent semantics.
+- **Print-friendly defaults**: Print styles remove noise while preserving content hierarchy.
+
+## Documentation
+
+- Public docs site content lives in `packages/docs` and is sourced from `packages/docs/content`.
+- Generated static output is emitted to `packages/docs/build` during CI and local testing.
+- Component usage and configuration examples are organized under `packages/docs/content/components` and `packages/docs/content/configuration`.
+
+## Packages
+
+| Package          | Description                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------- |
+| `packages/theme` | Source for the published `@hoverkraft/docusaurus-theme` package (TypeScript, compiled to `lib/`). |
+| `packages/docs`  | Docusaurus site showcasing the theme, used for QA and documentation.                              |
 
 ## Installation
 
 ```bash
 npm install @hoverkraft/docusaurus-theme
-# or
-yarn add @hoverkraft/docusaurus-theme
 ```
 
-## Usage
-
-Add the theme to your Docusaurus configuration file (`docusaurus.config.js`):
+Add the theme to your Docusaurus configuration:
 
 ```javascript
+// docusaurus.config.js
 module.exports = {
-  // ... other config
+  // ...other config
   themes: ["@hoverkraft/docusaurus-theme"],
-  // No additional configuration required - theme enforces Hoverkraft branding
 };
 ```
 
-## Strict Branding Enforcement
+The theme is opinionated by design and intentionally exposes no customization knobs.
 
-This theme is **opinionated by design** and enforces the official Hoverkraft branding guidelines:
-
-- **Official Hoverkraft Branding**: Colors, typography, and design elements from the [Hoverkraft Branding Guidelines](https://github.com/hoverkraft-tech/branding)
-- **Fixed Implementation**: No customization options to ensure brand consistency
-- **Consistent Layout**: Standardized header, footer, and content structure
+## Development
 
-**No customization options are provided.** This ensures brand consistency across all Hoverkraft documentation projects.
+Use npm workspaces to manage both packages in the monorepo:
 
-For detailed branding specifications, color palettes, typography guidelines, and design principles, see the official [Hoverkraft Branding Repository](https://github.com/hoverkraft-tech/branding).
+```bash
+npm install                              # Install workspace dependencies
+npm run lint --workspaces                # Run ESLint across packages
+npm run build --workspaces               # Build theme and docs outputs
+npm run start --workspace=@hoverkraft/hoverkraft-theme-docs  # Launch the docs site
+```
 
-## Features
+- Run builds before publishing or submitting pull requests to ensure `packages/theme/lib` is up to date.
+- Accessibility changes must be mirrored in documentation updates; see `ACCESSIBILITY.md` for the audit checklist.
 
-This theme provides:
+## Testing
 
-- **Enforced Hoverkraft Branding**: Official color palette, typography, and layout
-- **Responsive Design**: Mobile-first responsive layout
-- **Professional Components**: Standardized header, footer, and page structure
-- **Accessibility**: Built with accessibility best practices
-- **Print-friendly**: Optimized print styles
+```bash
+npm run test --workspaces                # Execute ts-jest suites
+npm run test:ci --workspaces             # Serial test run for CI environments
+npm run lint --workspaces                # Linting serves as static analysis guardrail
+```
 
-## Development
+- Theme unit tests are located in `packages/theme/src/__tests__`.
+- The docs site can be smoke-tested locally with `npm run start --workspace=@hoverkraft/hoverkraft-theme-docs`.
 
-To contribute to this theme:
+## Releasing
 
-1. Clone the repository
-2. Install dependencies: `pnpm install`
-3. Build the theme: `pnpm --filter @hoverkraft/docusaurus-theme run build`
-4. Test your changes locally (optional): `pnpm --filter hoverkraft-theme-docs run start`
+1. Update semantic versioning in `packages/theme/package.json`.
+2. Regenerate `packages/theme/lib` via `npm run build --workspaces`.
+3. Validate docs output with `npm run build --workspace=@hoverkraft/hoverkraft-theme-docs` when content changes.
+4. Publish the theme package via your chosen registry workflow (GitHub Actions or manual `npm publish`).
 
-### Building
+## Contributing
 
-```bash
-pnpm run build
-```
+Please review [`CONTRIBUTING.md`](CONTRIBUTING.md) for accessibility requirements, review expectations, and code of conduct.
 
-### Watch mode for development
+## Support
 
-```bash
-pnpm --filter @hoverkraft/docusaurus-theme run build:watch
-```
+Questions or issues? Open an issue in the [GitHub repository](https://github.com/hoverkraft-tech/docusaurus-theme) or start a discussion.
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
-
-## Support
-
-For issues and questions, please open an issue in the [GitHub repository](https://github.com/hoverkraft-tech/docusaurus-theme).
+MIT License — see [LICENSE](LICENSE) for details.