Add contribution guidelines and GitHub templates

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,59 @@
+name: Spec bug report
+description: Report a problem in the OpenAPI specification, generated output, or repository docs.
+title: "[Bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before opening an issue, check for existing issues or pull requests covering the same problem.
+
+        Use this template for incorrect behavior, invalid schema definitions, broken examples, or documentation problems.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: Describe the problem clearly and concisely.
+      placeholder: The schema for ... does not match the documented example.
+    validations:
+      required: true
+  - type: input
+    id: affected-area
+    attributes:
+      label: Affected area
+      description: Reference the relevant path, schema, component, or documentation section if known.
+      placeholder: paths/chat.yml or components/schemas/FeedbackResponse
+    validations:
+      required: true
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current behavior
+      description: Explain what is wrong in the current spec or docs.
+      placeholder: The request body marks field `x` as required, but the example omits it.
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: Explain what the correct behavior or definition should be.
+      placeholder: Field `x` should be optional, or the example should include it.
+    validations:
+      required: true
+  - type: textarea
+    id: supporting-context
+    attributes:
+      label: Supporting context
+      description: Add example payloads, validation output, screenshots, or links that help reproduce or understand the issue.
+      render: markdown
+    validations:
+      required: false
+  - type: textarea
+    id: additional-notes
+    attributes:
+      label: Additional notes
+      description: Include constraints, related discussions, or follow-up considerations.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/spec-change.yml

@@ -0,0 +1,67 @@
+name: Spec change proposal
+description: Propose a new endpoint, schema change, clarification, or other API specification update.
+title: "[Proposal] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template for non-trivial API or documentation changes.
+
+        A focused proposal makes review faster and reduces ambiguity during implementation.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or goal
+      description: Describe the problem to solve or the improvement you want to make.
+      placeholder: Consumers need a way to ...
+    validations:
+      required: true
+  - type: input
+    id: affected-area
+    attributes:
+      label: Affected area
+      description: List the relevant endpoints, schemas, or documentation sections if known.
+      placeholder: /feedback, components/schemas/Submission, README
+    validations:
+      required: true
+  - type: textarea
+    id: proposed-change
+    attributes:
+      label: Proposed change
+      description: Describe the concrete change you want in the spec.
+      placeholder: Add a new optional field ... or clarify the response contract for ...
+      render: markdown
+    validations:
+      required: true
+  - type: textarea
+    id: examples
+    attributes:
+      label: Example payloads or schema snippets
+      description: Provide sample requests, responses, or schema fragments where useful.
+      render: yaml
+    validations:
+      required: false
+  - type: textarea
+    id: impact
+    attributes:
+      label: Compatibility and impact
+      description: Note whether this is breaking, additive, or documentation-only, and mention downstream impact if known.
+      placeholder: Additive change; existing consumers should continue to work unchanged.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Describe other options you evaluated or reasons for rejecting them.
+    validations:
+      required: false
+  - type: textarea
+    id: additional-notes
+    attributes:
+      label: Additional notes
+      description: Include related issues, constraints, or open questions.
+    validations:
+      required: false

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+Describe the change and why it is needed.
+
+## Related issue
+
+Link the related issue if one exists.
+
+## Scope
+
+- [ ] This pull request is focused on a single concern.
+- [ ] The change was started from the latest `main` branch, or from a fork if direct branch creation is not available.
+
+## Validation
+
+- [ ] `npm run lint`
+- [ ] `npm run bundle`
+
+## Notes for reviewers
+
+Call out anything that needs extra attention during review, including compatibility concerns, open questions, or follow-up work.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+This repository contains the OpenAPI specification for the µEd API. Contributions should keep the source files consistent and go through GitHub pull requests.
+
+## Creating issues
+
+Before opening a new issue, check whether the topic is already covered by an existing issue or pull request.
+
+When creating an issue, include:
+
+- a clear, specific title
+- the problem you observed or the change you want to propose
+- the relevant part of the specification, if known
+- example requests, responses, or schema snippets when they help clarify the change
+- expected behavior and any constraints or open questions
+
+Use issues to capture bugs, unclear parts of the specification, and proposed API changes before implementation when the scope is non-trivial.
+
+## Contributing
+
+1. Start from the latest `main` branch.
+2. Create a topic branch for your work.
+3. If you do not have permission to create branches in this repository, fork the repository and open the pull request from your fork.
+4. Make your changes in the source spec files.
+5. Run the local checks before opening or updating a pull request:
+
+```bash
+npm install
+npm run lint
+npm run bundle
+```
+
+When you open the pull request:
+
+- describe the change and why it is needed
+- link the related issue when one exists
+- keep the pull request focused on a single concern
+
+## Reviewing
+
+Reviewers should check that:
+
+- the proposed change is clear and scoped appropriately
+- the OpenAPI source remains consistent and readable
+- `npm run lint` passes
+- `npm run bundle` succeeds when applicable
+
+Pull request authors should respond to review comments by updating the branch or clarifying intent in the discussion.
+
+## Merging
+
+Pull requests should be merged with **Squash and merge**.
+
+Before merging:
+
+- the pull request has been reviewed
+- the GitHub CI checks for linting and bundling are passing
+- open review comments have been resolved
+
+Merged branches are deleted automatically.

README.md

@@ -8,7 +8,6 @@ This repository is intentionally **spec-only**. It defines an **OpenAPI 3.1** co
 
 - `openapi.yml` — the main entry point (OpenAPI 3.1)
 - `paths/` — endpoint definitions (multi-file structure)
-- `dist/openapi.yml` — bundled single-file spec (generated)
 
 ## What the spec covers
 
@@ -45,4 +44,10 @@ npm run bundle
 
 ## Viewing the spec
 
-Open `openapi.yml` (or `dist/openapi.yml` for the bundled version) in any OpenAPI-capable tool (e.g., Swagger Editor, Swagger UI, Stoplight, Redocly) to render and explore the docs.
+The published spec is also available in an online viewer at [mued.org/spec](https://mued.org/spec/).
+
+For local viewing, open `openapi.yml` in any OpenAPI-capable tool (e.g., Swagger Editor, Swagger UI, Stoplight, Redocly). If you want a single-file version, run `npm run bundle` first and then open `dist/openapi.yml`.
+
+## Contributing
+
+Contributor workflow guidance for issues, branching, reviews, and merging lives in [CONTRIBUTING.md](CONTRIBUTING.md).