docs(meta): document issue types, area labels, and release milestones

AGENTS.md

@@ -68,3 +68,11 @@ Prefer plain ASCII characters in Markdown unless a typographic character is genu
 
 - CI runs `npm run build` and `npm run format:check` on pull requests.
 - If CI fails on formatting, run `npm run format:write` locally and commit the result.
+
+## Issues & Project Management
+
+- Issues are filed via the issue forms (blank issues are disabled). Each form sets an issue **type**: **Bug** (documented content is wrong/broken, or a site defect), **Feature** (new or expanded docs/site capability), or **Task** (smaller edits/cleanup, usually applied during triage).
+- **Area labels:** `content` (documentation text/examples) vs `platform` (the docs site itself — build, search, navigation, styling). These are the only area labels; there are no per-subsystem labels.
+- Kind is captured by the issue **type**, not labels — do not reintroduce `bug`/`enhancement` labels.
+- **Milestones:** `v5.x` release milestones, named to match the `harper`/`harper-pro` repos. Tag an issue with the milestone of the release whose docs it must ship with, so docs work is tracked per release. Do not delete the empty release milestones — they are the canonical per-release buckets.
+- See `CONTRIBUTING.md` (Reporting Issues) for the contributor-facing version.

CONTRIBUTING.md

@@ -1,5 +1,22 @@
 # Contributing
 
+Thanks for helping improve the Harper documentation. You can contribute by [reporting an issue](#reporting-issues) or opening a pull request.
+
+## Reporting Issues
+
+Issues are filed through the issue forms (the blank issue box is disabled, so choose the form that fits):
+
+- **📝 Content Issue** / **📚 Content Request** — for the documentation itself (errors, gaps, new or expanded pages).
+- **🐛 Platform Bug** / **⚡️ Platform Feature Request** — for the docs _site_ (search, navigation, build, styling).
+
+Issues are organized along three axes:
+
+- **Type** (set automatically by the form): **Bug** — something documented is wrong or broken, or a site defect; **Feature** — new or substantially expanded documentation or site capability; **Task** — smaller content edits and cleanup (usually applied by maintainers during triage). Kind is tracked by issue type, not by labels.
+- **Area label**: **`content`** (documentation text and examples) or **`platform`** (the docs site — Docusaurus, build, search, navigation, styling). These are the only area labels — there are intentionally no per-subsystem labels. A few flags also appear: `from-jira` (provenance), `good first issue`, `help wanted`.
+- **Milestone**: the **`v5.x` release** the work should ship with. Milestone names mirror the `harper` / `harper-pro` repos, so documentation work is tracked per release alongside the product. Maintainers set a milestone on issues that must land in a given release; issues that aren't tied to a release are left without one.
+
+You don't need to get type, area, or milestone exactly right when filing — maintainers confirm them during triage.
+
 ## Prerequisites
 
 Before contributing, please ensure you have the following installed:

README.md

@@ -8,6 +8,6 @@ Hosted at [docs.harper.fast](https://docs.harper.fast). Powered by [Docusaurus](
 
 This documentation site is open source!
 
-If you notice something out-of-place or have suggestions for improvement, please feel free to submit an issue and/or a pull request. Make sure to follow the relevant bug report and content/feature request templates.
+If you notice something out-of-place or have suggestions for improvement, please feel free to submit an issue and/or a pull request. Issues are filed through templates and organized by **type** (Bug / Feature / Task), **area** (`content` / `platform`), and **release milestone** (`v5.x`).
 
-For more information on contributing, follow the [contribution guide](CONTRIBUTING.md).
+For more information on contributing — including issue conventions — follow the [contribution guide](CONTRIBUTING.md#reporting-issues).