docs: add OSS governance files, versioning policy, refresh roadmap

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug report
+description: Report incorrect behavior, a crash, or a numerical discrepancy
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the report. For **security** issues, do not file here — see
+        [SECURITY.md](https://github.com/CyberdyneCorp/Cyberfluids/blob/main/SECURITY.md).
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What went wrong, and what did you expect instead?
+      placeholder: The 3D wind tunnel diverges after ~N steps at Re=...
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: A minimal case — grid size, parameters, obstacle/mesh, backend, and how you drove it (C++, Python, Swift, or `just`).
+      placeholder: |
+        just bench 64 32 32 100
+        # or a code snippet / Python script
+    validations:
+      required: true
+  - type: input
+    id: backend
+    attributes:
+      label: Backend
+      placeholder: CPU (par_unseq) / CUDA / OpenCL / Metal
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, compiler + version, CMake version, GPU + driver (if relevant), commit/tag.
+      placeholder: |
+        Ubuntu 24.04, GCC 13.3, CMake 3.28, RTX 5060 (driver 580.95), commit abc1234
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: Relevant build or run output (paste as text or attach files).
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/CyberdyneCorp/Cyberfluids/security/advisories/new
+    about: Report security issues privately — please do not open a public issue.
+  - name: Question / discussion
+    url: https://github.com/CyberdyneCorp/Cyberfluids/discussions
+    about: Ask usage questions or discuss ideas before filing a feature request.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+name: Feature request
+description: Propose a new capability (physics model, backend, binding, tooling)
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: The use case or limitation motivating the request.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed capability
+      description: What you'd like Cyberfluids to do. Larger features are developed spec-first with OpenSpec — see CONTRIBUTING.md.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Physics / dynamics
+        - Boundary conditions / geometry
+        - Backend (CPU / CUDA / OpenCL / Metal / SYCL)
+        - Language bindings (Python / Swift)
+        - Build / packaging / tooling
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or existing workarounds, if any.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+<!-- Thanks for contributing! Keep unrelated changes in separate PRs. -->
+
+## Summary
+
+<!-- What does this change and why? -->
+
+## Related
+
+<!-- OpenSpec change / issue, e.g. "Implements openspec/changes/... " or "Fixes #123" -->
+
+## Checklist
+
+- [ ] Tests added/updated; **bug fixes include a regression test** that fails before the fix.
+- [ ] `openspec validate --all --strict` passes (spec-first for medium/large features).
+- [ ] Docs and `openspec/specs/` updated where behavior changed — no claim left contradicting the code.
+- [ ] CI is green (Linux + macOS + OpenSpec).
+- [ ] For physics changes: the Palabos-oracle / GPU-vs-CPU tests still pass.
+
+## Notes for reviewers
+
+<!-- Anything worth calling out: trade-offs, follow-ups, how you verified it. -->

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to Cyberfluids are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0: minor/patch may still
+carry breaking changes while the API stabilizes).
+
+## [Unreleased]
+
+### Added
+- **Installable package** — `install`/`export` rules and a generated `CyberfluidsConfig.cmake`
+  so downstream projects can `find_package(Cyberfluids)` and link `Cyberfluids::core` /
+  `Cyberfluids::c`. The C ABI shared library carries a semver `SOVERSION`.
+- **Zero-setup dependency resolution** — NumPP is fetched at a pinned tag via FetchContent when
+  it is not already installed, so a plain `cmake -B build` works with no manual checkout
+  (`-DCYBERFLUIDS_FETCH_DEPS=OFF` to disable).
+- **Benchmark reference** — `docs/benchmarks.md` records methodology and measured GLUPS across
+  CPU / CUDA / OpenCL; the `bench/wind_tunnel_bench.cpp` harness runs via `just bench`.
+- **Project governance** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, this
+  changelog, and GitHub issue/PR templates.
+
+### Changed
+- Documentation and OpenSpec specs brought back in sync with the shipped code (GPU backends
+  marked validated, dependency mechanism corrected, spec `Purpose` placeholders filled).
+
+## [0.0.1] - 2026-07-05
+
+Initial tagged release — a zero-legacy C++20 Lattice Boltzmann CFD engine on the CyberdyneCorp
+scientific suite (NumPP), single-node, no MPI.
+
+### Added
+- **Physics** — BGK / TRT / MRT / regularized / forced dynamics; D2Q9, D2Q5, D3Q7, D3Q19, D3Q27
+  stencils (2D and 3D); single- and multi-component Shan-Chen multiphase; Boussinesq thermal
+  (Rayleigh-Bénard); porous media (partial bounce-back); per-cell external forcing and
+  advection-diffusion coupling.
+- **Geometry & wind tunnel** — STL/OBJ import + voxelization (CyberMeshGenerator); a 3D D3Q19
+  wind tunnel with off-lattice bounce-back (analytic sphere or imported mesh).
+- **Backends** — CPU (`std::execution::par_unseq` + serial fallback); validated CUDA and OpenCL
+  D3Q19 wind-tunnel device kernels (~30× the parallel CPU on an RTX 5060); Metal D2Q9 cavity.
+- **Validation** — Palabos numerical oracle for the 2D and 3D lid-driven cavity; fp32 GPU
+  agreement with the fp64 CPU oracle to ~1e-5.
+- **Bindings & I/O** — Python (NumPy / DLPack) and Swift bindings over a stable C ABI;
+  legacy-VTK structured-points output; checkpoint/restart.
+- **Tooling** — a `justfile` (build, test, GPU, benchmark, spec), a GitHub Actions CI pipeline
+  (Linux GCC + macOS Metal/Swift + OpenSpec validation), and in-repo OpenSpec specs.
+
+[Unreleased]: https://github.com/CyberdyneCorp/Cyberfluids/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/CyberdyneCorp/Cyberfluids/releases/tag/v0.0.1

CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive,
+and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from
+  the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their
+  explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable
+behavior and will take appropriate and fair corrective action in response to any behavior that
+they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the
+community leaders responsible for enforcement at **leonardoaraujo.santos@gmail.com**. All
+complaints will be reviewed and investigated promptly and fairly. Community leaders are obligated
+to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to Cyberfluids
+
+Thanks for your interest in Cyberfluids — a zero-legacy C++20 Lattice Boltzmann CFD engine.
+This guide covers how to build, the workflow we follow, and what a mergeable change looks like.
+
+## Getting set up
+
+```bash
+git clone https://github.com/CyberdyneCorp/Cyberfluids.git
+cd Cyberfluids
+just bootstrap      # build + install NumPP into .deps/  (or: scripts/bootstrap_deps.sh)
+just test           # configure + build + full CTest suite (CPU backend)
+```
+
+No `just`? The equivalent is `scripts/bootstrap_deps.sh` then `cmake -B build` +
+`cmake --build build` + `ctest --test-dir build`. See
+[docs/getting-started.md](docs/getting-started.md). GPU work: `just gpu-detect`, then
+`just cuda` / `just opencl` / `just metal`.
+
+## Development workflow
+
+We develop spec-first with [OpenSpec](https://github.com/Fission-AI/OpenSpec). Living
+capability specs are in [`openspec/specs/`](openspec/specs); completed changes are archived
+under [`openspec/changes/archive/`](openspec/changes/archive).
+
+- **Medium or large features** (new physics, backends, bindings, build/packaging behavior):
+  start with an OpenSpec change (proposal → specs/tasks) before implementing. Run
+  `openspec validate --all --strict` — CI enforces it.
+- **Small fixes and docs:** a direct PR is fine. Still keep the specs and docs truthful — if
+  your change makes a spec or doc statement false, update it in the same PR.
+
+## What a mergeable PR looks like
+
+- **Tests.** New behavior ships with tests. **Every bug fix includes a regression test** that
+  fails before the fix and passes after.
+- **Green CI.** Linux (GCC, `par_unseq` + oracle suite), macOS (Metal build + Swift binding),
+  and OpenSpec validation must all pass.
+- **Docs/specs in sync.** Update `docs/` and `openspec/specs/` when your change affects
+  documented behavior. Don't leave a claim that the code contradicts.
+- **Readable, low-complexity code.** Match the surrounding style (Concepts, Ranges, smart
+  pointers, contiguous data — no raw owning pointers, no legacy macros). Keep per-function
+  cognitive complexity modest; isolate genuinely irreducible algorithms (kernels, AST-like
+  traversals) and flag them rather than mangling them to hit a number.
+- **A descriptive PR message.** Explain what changed and why. If you found a bug, describe how
+  it reproduced.
+
+## Commit & PR style
+
+- Concise, technical, imperative commit subjects (e.g. "Fix Shan-Chen weight formula in docs").
+- Reference the OpenSpec change or issue when there is one.
+- Keep unrelated changes in separate PRs.
+
+## Numerical correctness
+
+Physics changes are validated against **Palabos** as a numerical oracle (see
+[docs/oracle-validation.md](docs/oracle-validation.md)) and GPU paths against the fp64 CPU
+solver within a documented fp32 tolerance. If you change a collision model, boundary scheme, or
+equilibrium, make sure the relevant oracle/GPU-vs-CPU tests still pass — and add one if a gap
+exists.
+
+## Reporting bugs & requesting features
+
+Open an issue using the templates. For **security** issues, do **not** open a public issue —
+see [SECURITY.md](SECURITY.md).
+
+## License
+
+By contributing, you agree that your contributions are licensed under the project's
+[MIT License](LICENSE).

README.md

@@ -312,11 +312,19 @@ worldwide LBM community through Palabos. In tests, identical setups run in both
 their macroscopic fields are compared within a documented tolerance — see
 [oracle validation](docs/oracle-validation.md).
 
+## 🧭 Versioning & API stability
+
+Cyberfluids is **pre-1.0 (`0.0.x`)**: the API is still settling, and minor/patch releases may
+carry breaking changes until `1.0`. The C ABI shared library carries a semver `SOVERSION`
+(`libcyberfluids_c.so.<major>`) so consumers can pin ABI compatibility. Notable changes are
+tracked in [CHANGELOG.md](CHANGELOG.md).
+
 ## 🤝 Contributing
 
 Work is spec-driven. Before writing code, read the relevant spec in `openspec/specs/`, and
 open changes through the OpenSpec workflow (`/opsx:propose`). Every bug fix ships with a
-regression test.
+regression test. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full workflow, the
+[Code of Conduct](CODE_OF_CONDUCT.md), and [security reporting](SECURITY.md).
 
 ## 📄 License
 

SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+Cyberfluids is a numerical simulation library. The most relevant risks are memory-safety issues
+(out-of-bounds access, use-after-free) reachable through the C ABI or the geometry/STL import
+path, and denial-of-service from untrusted input (e.g. a malformed mesh or an extreme grid size).
+
+## Supported versions
+
+The project is pre-1.0 (`0.0.x`). Security fixes are applied to `main` and released in the next
+tag. There is no long-term-support branch yet.
+
+| Version | Supported |
+|---------|-----------|
+| `main`  | ✅ |
+| latest `0.0.x` tag | ✅ |
+| older tags | ❌ |
+
+## Reporting a vulnerability
+
+**Please do not open a public issue for security vulnerabilities.**
+
+Report privately via GitHub's [**Report a vulnerability**](https://github.com/CyberdyneCorp/Cyberfluids/security/advisories/new)
+(Security → Advisories), or email the maintainer at **leonardoaraujo.santos@gmail.com** with:
+
+- a description of the issue and its impact,
+- steps or a minimal input that reproduces it (a mesh/config file, grid parameters, or a code
+  snippet driving the C ABI),
+- affected version/commit.
+
+We aim to acknowledge a report within a few days and to agree on a disclosure timeline with you.
+Please give us a reasonable window to ship a fix before any public disclosure.
+
+## Scope
+
+In scope: the core library, the C ABI, geometry import, and the language bindings in this repo.
+Out of scope: vulnerabilities in third-party dependencies (report those upstream) and issues that
+require running deliberately hostile build tooling.