@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: Apache-2.0
+name: Bug report
+description: Something does not work as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this. If it is a **security**
+        issue, please do not file it here — see the security policy instead.
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Which part of CuOS?
+      options:
+        - cuos — the operating system, updater, factories
+        - cuos-release — tool.sh, building images and installers
+        - cuos-iac — IaC manager, WebUI, fleet
+        - Not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - x86_64
+        - rpi-arm64 (64-bit Raspberry Pi)
+        - rpi-arm32 (32-bit Raspberry Pi)
+        - orangepi-zero3
+        - LXC container
+        - Other / not applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what did you expect instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How can we reproduce it?
+      description: The commands you ran, and the relevant part of your `system.json` — **with passwords and registry credentials removed**.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Version
+      description: |
+        On a running system: `cuos version`.
+        When building: the tag or commit of the repository, and `./tool.sh name your-system.json`.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: "`cuos log`, or `journalctl -u cuos-*` — again with any secrets removed."
+      render: shell
@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+# Blank issues stay enabled: a report that fits no template is still a report.
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/cuos-dev/.github/security/policy
+    about: Do not open an issue. Report it privately — see the security policy.
+  - name: Building a system — documentation
+    url: https://github.com/cuos-dev/cuos-release#readme
+    about: How to define a system and build an image, installer or container.
+  - name: The operating system — documentation
+    url: https://github.com/cuos-dev/cuos/tree/main/docs
+    about: Architecture, system.json, the update mechanism, platform support.
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+name: Feature request
+description: Suggest something CuOS should be able to do
+labels: ["enhancement"]
+body:
+  - type: dropdown
+    id: component
+    attributes:
+      label: Which part of CuOS?
+      options:
+        - cuos — the operating system, updater, factories
+        - cuos-release — tool.sh, building images and installers
+        - cuos-iac — IaC manager, WebUI, fleet
+        - Not sure
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: The situation you are in, rather than the solution you have in mind — it often turns out there is a shorter way.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like CuOS to do?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What are you doing instead today?
+      description: A workaround, another tool, or nothing at all — all three are useful to know.
@@ -0,0 +1,27 @@
+## What does this change, and why?
+
+<!-- If it fixes an open issue, say "Fixes #123". -->
+
+## How was it verified?
+
+<!--
+Say what you actually ran, and what you did not. "Built an rpi-arm64 image and
+booted it on a Pi 4" and "reviewed only, not built" are both useful answers;
+a checkbox that means neither is not.
+-->
+
+## Checklist
+
+- [ ] Every commit is signed off (`git commit -s`) — see [DCO.txt](../DCO.txt).
+      CI checks this and will fail the pull request otherwise.
+- [ ] New shell scripts carry `# SPDX-License-Identifier: Apache-2.0`.
+- [ ] `shellcheck --severity=warning` is clean, and any `*.test.sh` passes.
+- [ ] The documentation matches the change — including any command in a README
+      that this renames or removes.
+
+<!--
+Branch flow: pull requests go to `development`, not to `main`.
+History is kept as it was made: no squashing, and no rebasing of a branch that
+has already been pushed. Bring a branch up to date by merging `development`
+into it.
+-->
@@ -1,25 +1,64 @@
 # Security Policy
 
-## Supported Versions
+## Reporting a vulnerability
 
-We release security updates for the latest stable version of the software. Older versions may not receive security updates.
+**Please do not open a public issue for a security problem.**
 
-## Reporting a Vulnerability
+Report it through **GitHub's private vulnerability reporting**: go to the
+affected repository, open the *Security* tab, and choose *Report a
+vulnerability*. That keeps the report private to you and the maintainers until
+a fix is available, and gives you a thread to follow it in.
 
-If you discover a security vulnerability, please report it to us privately. Do not create a public issue.
+If you cannot use that — no GitHub account, or the repository does not offer
+it — email **contact@simonwalz.de** with `CuOS security` in the subject.
 
-Please email [Simon Walz](https://simonwalz.de/?id=impressum) with the details of the vulnerability. Include:
+Please include:
 
-- A description of the vulnerability
-- Steps to reproduce
-- Any relevant logs or screenshots
+- which component and version (`cuos version` on a running system, or the tag
+  or commit you built from)
+- what an attacker can do, and what access they need to start
+- steps to reproduce, and any logs — **with credentials removed**
 
-We will respond as quickly as possible and coordinate a fix and disclosure timeline.
+### What happens next
 
-## Security Best Practices
+| | |
+|---|---|
+| We acknowledge the report | within **5 working days** |
+| We tell you whether we can reproduce it, and our assessment | within **10 working days** |
+| We agree a disclosure date with you | once a fix or a mitigation exists |
 
-- Keep your dependencies up to date.
-- Avoid exposing sensitive data in logs or error messages.
-- Use secure coding practices and input validation.
+If you do not hear from us in that time, please chase us — a missed
+notification is more likely than silence on purpose.
 
-Thank you for helping us keep our project secure!
+We will credit you in the release notes unless you would rather stay anonymous.
+We have no bug bounty.
+
+## Which versions get fixes
+
+CuOS is **pre-1.0 and has no long-term support branches**. Security fixes go
+into the current release; there are no backports to older tags. If you run a
+pinned version, expect to move forward to take a fix.
+
+Every CuOS image reference is pinned by digest and a mismatch is fatal, so
+updating means changing the pin deliberately rather than drifting onto a new
+image by accident.
+
+## What is in scope
+
+The four repositories of this organisation: the operating system and its update
+mechanism (`cuos`), the build tooling (`cuos-release`), the IaC manager, WebUI
+and fleet components (`cuos-iac`), and these org-wide files.
+
+Out of scope: vulnerabilities in application containers you run **on** CuOS,
+which belong to their own projects; and the consequences of a configuration that
+deliberately weakens the system — an unprivileged report that CuOS is insecure
+when run with `os_root_password` set to a known value tells us nothing.
+
+## Hardening your own deployment
+
+- Pin images by digest and update deliberately.
+- Keep registry credentials out of images and out of `system.json` files you
+  share; use the config encryption in `cuos-release`.
+- Sign your IaC repository's commits and set `iac_repo_signing_keys`, so a
+  device only applies configuration it can verify.
+- Give the application container only the privileges it needs.
@@ -4,6 +4,10 @@
 
 The CuOS operating system is also a solid base for IoT, edge, and VM-based products.
 
+## Start here
+
+**To build a bootable system**, start at [cuos-release](https://github.com/cuos-dev/cuos-release#readme): describe the system you want in a `system.json` and run `./tool.sh image`. It produces a disk image, an ISO installer or an LXC container.
+
 ## Framework overview
 
 Components are organized in layers from device to service:
@@ -12,7 +16,8 @@ Components are organized in layers from device to service:
 | --- | --- | --- |
 | Device management | CuOS Fleet Management — agent + server for device enrollment, health telemetry, remote commands, and rollout orchestration. | [cuos-iac](https://github.com/cuos-dev/cuos-iac#readme) |
 | Service management | CuOS IaC — Infrastructure-as-Code manager and Web UI for defining services, builds, deployments, and release channels. | [cuos-iac](https://github.com/cuos-dev/cuos-iac#readme) |
-| Operating system | CuOS (OS) — minimal OS image with updater, image and installer factories, OTA tooling and reproducible builds. | [cuos](https://github.com/cuos-dev/cuos#readme) |
+| Operating system | CuOS (OS) — minimal OS image with updater, OTA tooling and reproducible builds. | [cuos](https://github.com/cuos-dev/cuos#readme) |
+| Build & release | CuOS Release Tooling — `tool.sh`, the image and installer factories, pinned image versions, configuration merging, signing and encryption. | [cuos-release](https://github.com/cuos-dev/cuos-release#readme) |
 
 All components can be used independently — each CuOS component works standalone (you don’t need to run the others to use a single component).