Release v1.2

## Added

- **DocEngine CLI** (`c5dec docengine report|presentation -n <name> [-d <dest>]`): `create_docengine_template()` in the SSDLC module copies and customizes report/presentation templates with variable substitution, overwrite protection, Quarto dependency check, and `REPORT_TEMPLATE_PATH` / `PRESENTATION_TEMPLATE_PATH` constants in `c5settings.py`
- **DocEngine enhancements**: `c5dec_config_v2.yml` and `custom_vars_v2.py` pre-render script with automatic LaTeX conversion, support for string/list/dict changelog entry formats, and LaTeX escaping for special characters; Quarto presentation template (`c5dec/assets/presentation/`) with Reveal.js and PowerPoint output, ALab branding, and modular slide organization
- **`docEngine.Dockerfile`**: dedicated DocEngine dev container (Quarto, TeX Live, Kryptor, Cryptomator CLI); separate `.devcontainer/c5dec-dev/` for the lightweight C5-DEC dev container
- **CRA compliance module** (`c5dec/core/cra.py`, EU Regulation 2024/2847 Tier 1): YAML requirements database (35+ Annex I items), Doorstop-integrated checklist with pass/fail/na verdicts and Excel export, CRA Technical Documentation template (Annex VII, seven chapters), EU Declaration of Conformity generator (Annex V); `cra` CLI command (`create`, `verify`, `export`); feature flags and `c5settings.py` constants; test suite `tests/cra_checklist_test.py` (16 methods); user manual `docs/manual/cra.md`
- **SBOM lifecycle management module** (`c5dec/core/sbom.py`): Syft-based generation (CycloneDX/SPDX), parsing, validation, version diff, Doorstop traceability, and `auto_verify_sbom_requirement()` for CRA `cra_ii_1_1`; `sbom` CLI command (`generate`, `import`, `diff`, `validate`); test suite `tests/sbom_test.py` (25+ methods); user manual `docs/manual/sbom.md`
- **Native Python cryptography module** (`c5dec/core/cryptography.py`): SHA-256 file integrity, GnuPG signing/encryption, Shamir's Secret Sharing over GF(2^127−1), NaCl Ed25519 digital signatures; `c5dec crypto` CLI command with 11 subcommands (`hash`, `verify-hash`, `sign`, `verify-sig`, `encrypt`, `decrypt`, `shamir-split`, `shamir-recover`, `nacl-keygen`, `nacl-sign`, `nacl-verify`)
- **CPSSA as a multi-subsystem package** (`c5dec/core/cpssa/`): `create_threat_model()` generating Threagile-compatible YAML from Doorstop SRS/ARC artefacts with auto-discovery of architecture folders; `generate_cpssa_report()` for STRIDE-based Markdown reports; Threagile field-mapping subsystem (`threagile-mappings.yml`, `threagile-schema.json`); sidecar YAML support (`threat-actors.yml`, `assumptions.yml`); `generate_fair_input_template()` and `run_quantitative_risk_analysis()` with `--fair-params` YAML override and PERT distribution support; water-treatment worked example (`c5dec/core/cpssa/examples/water-treatment/`)
- **SpecEngine tools**: `c5graph.py` — interactive Cytoscape.js traceability graph producing a self-contained `specs-graph.html` (dagre layout, expand/collapse, color-coded coverage, offline asset inlining); `prune_bad_links.py` — removes Doorstop links with mismatched target prefix or links on root documents; `doorstop_yml_to_md.py` — migration script converting Doorstop items from pure YAML to Markdown with YAML frontmatter; `c5mermaid.py` — Mermaid diagram pre-processor that scans Doorstop `.md` item files for fenced ` ```mermaid ``` ` blocks, renders each to SVG (or PNG) via the Mermaid CLI (`mmdc`), stores the result in the item's `assets/` directory, and replaces the fenced block with an HTML comment preserving the original source plus a Markdown image reference; transformation is one-way and idempotent (content-hash-based filenames, `c5-mermaid-source` sentinel); supports `render` (default) and `undo` actions, `--dry-run`, and `--format svg|png`; integrated into `publish.sh` (render before publish, undo after); all support `--dry-run`; "Traceability Graph" entry added to `index.html` via `c5publish.py`; automatic item ID linkification in published HTML (`linkify_html_file()` / `_linkify_item_ids()`); per-column filter inputs in `c5browser.py`; section titles in `c5traceability.py` nav bar; `docs/specs/SpecEngine/README.md` and `c5traceability_config_example.yaml` added
- **Specs**: 19 new SRS items; 5 new TCS test cases; grouping items added to `swd/`, `mrs/`, and `arc/`; headings added to all TRP items; SWD-002 updated with full C5-DEC CAD class diagram in Mermaid; SWD-003 updated with Mermaid architecture overview diagram
- **Documentation**: user manuals `docs/manual/isms.md`, `docs/manual/README.md`; updated `cpssa.md`, `cryptography.md`, `ssdlc.md`
- **Project template** (`c5dec/assets/templates/project/`) synchronized with current toolchain: containers, SpecEngine toolkit, DocEngine assets, refreshed `pyproject.toml` and `poetry.lock`
- `SECURITY.md` detailing supported versions, responsible disclosure process, response timeline, scope definition
- `CONTRIBUTING.md` explaining how to set up the development environment, submit changes, and follow project conventions
- **Mermaid resize support** in `c5mermaid.py`: `--width` and `--height` flags passed to `mmdc` for SVG/PNG output dimensions
- TCS and TRP Doorstop document templates added to the project template (`c5dec/assets/templates/project/docs/specs/`); test case and test report spec documents consolidated
- **Common Criteria knowledge base**: completed CC KB (new CC pages) and revisions covering CC:2022

## Fixed

- TeX rendering issue in DocEngine templates and `cli new` command (malformed `\usepackage` argument in `_quarto.yml`)
- Broken Doorstop link format in 14 SWD items (`ARC003`/`ARC004` → `ARC-003`/`ARC-004`)
- Orphaned TCS-001–TCS-007 with empty `links: []`; all now carry SRS traceability links
- 14 SRS items with placeholder (TBD) text replaced with complete procedural descriptions
- Missing MRS upward traceability links in ARC-003 (MRS-013, MRS-024, MRS-025, MRS-046, MRS-047) and ARC-004 (MRS-040, MRS-041, MRS-044, MRS-060)
- HTML output path in `c5traceability.py` and `c5browser.py` resolved relative to script dir instead of specs dir; corrected to `SCRIPT_DIR.parent / "docs" / "publish"`
- Typos in SRS items

## Modified

- `dev.Dockerfile` and `docEngine.Dockerfile` extended with Node.js 20.x, Chromium, and Mermaid CLI (`mmdc`) for Mermaid diagram rendering in the SpecEngine pipeline
- `dev.Dockerfile` stripped of DocEngine dependencies (Quarto, TeX Live, fonts, cryptographic tools); `.devcontainer/devcontainer.json` updated to use `docEngine.Dockerfile`
- `c5dec crypto` CLI upgraded from stub to full implementation dispatching to the native cryptography module
- `c5dec cpssa` CLI extended with `fair-input` and `risk-analysis` subcommands
- `c5traceability.py`: generalized to YAML-configurable, project-agnostic Doorstop traceability analyser; added `--config`, `--discover`, `--discover-write` flags and auto-discovery of document hierarchy from `.doorstop.yml` files
- `c5browser.py`: extended to support both `.md` (Markdown frontmatter) and `.yml` (pure YAML) Doorstop item formats; document type list auto-discovered at runtime; numeric field detection for proper column sorting
- All 246 Doorstop item files in `arc`, `mrs`, `srs`, `swd`, `tra`, `trb`, `tst` converted from pure YAML to Markdown with YAML frontmatter; `.doorstop.yml` configs updated to `itemformat: markdown`
- ARC item files renamed to hyphenated format (`ARC001.yml` → `ARC-001.yml`); SWD items likewise (`SWD001.yml`–`SWD014.yml` → `SWD-001.yml`–`SWD-014.yml`)
- PlantUML schematics relocated to `docs/specs/swd/assets/PlantUML/`; obsolete `classes.puml` and `subsystems.puml` removed
- SpecEngine folder renamed from `docs/specs/c5dec-SpecEngine/` to `docs/specs/SpecEngine/`; `publish.sh` updated with linkification step, `c5graph.py` generation, and Mermaid render/undo steps
- `c5publish.py` tooling-reports block moved to `<body>` top with "Traceability Graph" link added
- DocEngine pre-render script updated from `custom_vars.py` to `custom_vars_v2.py`; default approval signatures set to placeholder (`"---"`)
- **Docker security hardening**: non-root user, dropped Linux capabilities, `--no-install-recommends`, and package pinning applied to `Dockerfile`, `dev.Dockerfile`, and `docEngine.Dockerfile`; `.dockerignore` added to limit build context
- **Unit test coverage significantly extended**: new test files for CLI (`cli_test.py`, 298 lines), ISMS (`isms_test.py`, 268 lines), SSDLC (`ssdlc_test.py`, 251 lines), Transformer (`transformer_test.py`, 176 lines), CPSSA (`cpssa_test.py`, 1175 lines), and cryptography (`cryptography_test.py`, 380 lines); existing CCT test files improved
- Mermaid SVGs pre-rendered for SWD-002 and SWD-003; stored in `docs/specs/swd/assets/`
- README, `docs/manual/README.md`, `docs/specs/README.md`

## Removed

- DocEngine-specific dependencies from `dev.Dockerfile` (moved to `docEngine.Dockerfile`)
- `c5traceability_v2.py`; merged into `c5traceability.py`
- Stale Doorstop Bootstrap CSS/JS assets from `docs/assets/doorstop/`; replaced by CDN references
- `docs/manual/overview.md`; content merged into `docs/manual/start.md`

Author: CryptographySandbox

.devcontainer/c5dec-dev/devcontainer.json

@@ -0,0 +1,51 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
+{
+	"name": "C5-DEC CAD development",
+	// Use 'dockerFile' if you want to build an image from a Dockerfile.
+	// Use 'image' if you want to use an existing image from Docker Hub or a local image, e.g., the commented line for OpenSSL with oqs provider for PQC.
+	// Use 'dockerComposeFile' and 'service' if you want to use a service from a docker-compose.yml file.
+	"build": {
+		// Sets the run context to one level up instead of the .devcontainer folder.
+		"context": "../..",
+		// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
+		"dockerfile": "../../dev.Dockerfile"
+	},
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Uncomment the next line to run commands after the container is created.
+	// "postCreateCommand": "cat /etc/os-release",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		"vscode": {
+            "extensions": [
+				"ms-python.python",
+				"streetsidesoftware.code-spell-checker",
+				"quarto.quarto",
+				"ms-toolsai.jupyter",
+				"ms-toolsai.datawrangler",
+				"ms-azuretools.vscode-docker"
+			],
+            "settings": {
+                "python.testing.pytestArgs": [
+                    "."
+                ],
+                "python.testing.unittestEnabled": false,
+                "python.testing.pytestEnabled": true,
+                "python.formatting.provider": "black"
+            }
+        }
+	},
+
+	"workspaceMount": "source=${localWorkspaceFolder},target=/home/alab/c5dec,type=bind",
+	"workspaceFolder": "/home/alab/c5dec"
+
+	// Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "devcontainer"
+}

.devcontainer/devcontainer.json

@@ -1,15 +1,15 @@
 // For format details, see https://aka.ms/devcontainer.json. For config options, see the
 // README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
 {
-	"name": "C5-DEC CAD dev container",
+	"name": "C5-DEC CAD DocEngine",
 	// Use 'dockerFile' if you want to build an image from a Dockerfile.
 	// Use 'image' if you want to use an existing image from Docker Hub or a local image, e.g., the commented line for OpenSSL with oqs provider for PQC.
 	// Use 'dockerComposeFile' and 'service' if you want to use a service from a docker-compose.yml file.
 	"build": {
 		// Sets the run context to one level up instead of the .devcontainer folder.
 		"context": "..",
 		// Update the 'dockerFile' property if you aren't using the standard 'Dockerfile' filename.
-		"dockerfile": "../dev.Dockerfile"
+		"dockerfile": "../docEngine.Dockerfile"
 	},
 
 	// Features to add to the dev container. More info: https://containers.dev/features.

.devcontainer/pqc-openssl/devcontainer.json

@@ -1,7 +1,7 @@
 // For format details, see https://aka.ms/devcontainer.json. For config options, see the
 // README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-dockerfile
 {
-	"name": "C5-DEC cryptography dev container",
+	"name": "C5-DEC Cryptography",
 	"image": "openquantumsafe/oqs-ossl3:latest",
 	// Use 'dockerFile' if you want to build an image from a Dockerfile.
 	// Use 'image' if you want to use an existing image from Docker Hub or a local image, e.g., the commented line for OpenSSL with oqs provider for PQC.

.dockerignore

@@ -0,0 +1,38 @@
+# Version control
+.git/
+.gitignore
+
+# Python cache and build artefacts
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Environment / secrets
+.env
+.env.*
+
+# Test artefacts
+.pytest_cache/
+tests/content/
+
+# Input data (not needed in the image)
+input/
+
+# Node
+node_modules/
+
+# IDE / editor
+.vscode/
+.idea/
+
+# Dev-container metadata (not needed inside the image)
+.devcontainer/

.gitignore

@@ -171,5 +171,11 @@ cython_debug/
 # WSL stuff
 *:Zone.Identifier
 
+# Quarto/DocEngine output folders
+c5dec/assets/report/_output/
+c5dec/assets/etr/etr_template/_output/
+
 /.quarto/
-.Rhistory
+.Rhistory
+
+.cpssa_cache/docs/specs/docs/

AUTHORS

@@ -0,0 +1,9 @@
+Developers
+----------
+
+* Arash Atashpendar
+* Heinrich Fries
+* Itzel Vazquez Sandoval
+* Sven Angel
+
+C5-DEC is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE version 3.

CHANGELOG.md

@@ -1,3 +1,61 @@
+# 1.2 (2026-03-10)
+
+## Added
+
+- **DocEngine CLI** (`c5dec docengine report|presentation -n <name> [-d <dest>]`): `create_docengine_template()` in the SSDLC module copies and customizes report/presentation templates with variable substitution, overwrite protection, Quarto dependency check, and `REPORT_TEMPLATE_PATH` / `PRESENTATION_TEMPLATE_PATH` constants in `c5settings.py`
+- **DocEngine enhancements**: `c5dec_config_v2.yml` and `custom_vars_v2.py` pre-render script with automatic LaTeX conversion, support for string/list/dict changelog entry formats, and LaTeX escaping for special characters; Quarto presentation template (`c5dec/assets/presentation/`) with Reveal.js and PowerPoint output, ALab branding, and modular slide organization
+- **`docEngine.Dockerfile`**: dedicated DocEngine dev container (Quarto, TeX Live, Kryptor, Cryptomator CLI); separate `.devcontainer/c5dec-dev/` for the lightweight C5-DEC dev container
+- **CRA compliance module** (`c5dec/core/cra.py`, EU Regulation 2024/2847 Tier 1): YAML requirements database (35+ Annex I items), Doorstop-integrated checklist with pass/fail/na verdicts and Excel export, CRA Technical Documentation template (Annex VII, seven chapters), EU Declaration of Conformity generator (Annex V); `cra` CLI command (`create`, `verify`, `export`); feature flags and `c5settings.py` constants; test suite `tests/cra_checklist_test.py` (16 methods); user manual `docs/manual/cra.md`
+- **SBOM lifecycle management module** (`c5dec/core/sbom.py`): Syft-based generation (CycloneDX/SPDX), parsing, validation, version diff, Doorstop traceability, and `auto_verify_sbom_requirement()` for CRA `cra_ii_1_1`; `sbom` CLI command (`generate`, `import`, `diff`, `validate`); test suite `tests/sbom_test.py` (25+ methods); user manual `docs/manual/sbom.md`
+- **Native Python cryptography module** (`c5dec/core/cryptography.py`): SHA-256 file integrity, GnuPG signing/encryption, Shamir's Secret Sharing over GF(2^127−1), NaCl Ed25519 digital signatures; `c5dec crypto` CLI command with 11 subcommands (`hash`, `verify-hash`, `sign`, `verify-sig`, `encrypt`, `decrypt`, `shamir-split`, `shamir-recover`, `nacl-keygen`, `nacl-sign`, `nacl-verify`)
+- **CPSSA as a multi-subsystem package** (`c5dec/core/cpssa/`): `create_threat_model()` generating Threagile-compatible YAML from Doorstop SRS/ARC artefacts with auto-discovery of architecture folders; `generate_cpssa_report()` for STRIDE-based Markdown reports; Threagile field-mapping subsystem (`threagile-mappings.yml`, `threagile-schema.json`); sidecar YAML support (`threat-actors.yml`, `assumptions.yml`); `generate_fair_input_template()` and `run_quantitative_risk_analysis()` with `--fair-params` YAML override and PERT distribution support; water-treatment worked example (`c5dec/core/cpssa/examples/water-treatment/`)
+- **SpecEngine tools**: `c5graph.py` — interactive Cytoscape.js traceability graph producing a self-contained `specs-graph.html` (dagre layout, expand/collapse, color-coded coverage, offline asset inlining); `prune_bad_links.py` — removes Doorstop links with mismatched target prefix or links on root documents; `doorstop_yml_to_md.py` — migration script converting Doorstop items from pure YAML to Markdown with YAML frontmatter; `c5mermaid.py` — Mermaid diagram pre-processor that scans Doorstop `.md` item files for fenced ` ```mermaid ``` ` blocks, renders each to SVG (or PNG) via the Mermaid CLI (`mmdc`), stores the result in the item's `assets/` directory, and replaces the fenced block with an HTML comment preserving the original source plus a Markdown image reference; transformation is one-way and idempotent (content-hash-based filenames, `c5-mermaid-source` sentinel); supports `render` (default) and `undo` actions, `--dry-run`, and `--format svg|png`; integrated into `publish.sh` (render before publish, undo after); all support `--dry-run`; "Traceability Graph" entry added to `index.html` via `c5publish.py`; automatic item ID linkification in published HTML (`linkify_html_file()` / `_linkify_item_ids()`); per-column filter inputs in `c5browser.py`; section titles in `c5traceability.py` nav bar; `docs/specs/SpecEngine/README.md` and `c5traceability_config_example.yaml` added
+- **Specs**: 19 new SRS items; 5 new TCS test cases; grouping items added to `swd/`, `mrs/`, and `arc/`; headings added to all TRP items; SWD-002 updated with full C5-DEC CAD class diagram in Mermaid; SWD-003 updated with Mermaid architecture overview diagram
+- **Documentation**: user manuals `docs/manual/isms.md`, `docs/manual/README.md`; updated `cpssa.md`, `cryptography.md`, `ssdlc.md`
+- **Project template** (`c5dec/assets/templates/project/`) synchronized with current toolchain: containers, SpecEngine toolkit, DocEngine assets, refreshed `pyproject.toml` and `poetry.lock`
+- `SECURITY.md` detailing supported versions, responsible disclosure process, response timeline, scope definition
+- `CONTRIBUTING.md` explaining how to set up the development environment, submit changes, and follow project conventions
+- **Mermaid resize support** in `c5mermaid.py`: `--width` and `--height` flags passed to `mmdc` for SVG/PNG output dimensions
+- TCS and TRP Doorstop document templates added to the project template (`c5dec/assets/templates/project/docs/specs/`); test case and test report spec documents consolidated
+- **Common Criteria knowledge base**: completed CC KB (new CC pages) and revisions covering CC:2022
+
+## Fixed
+
+- TeX rendering issue in DocEngine templates and `cli new` command (malformed `\usepackage` argument in `_quarto.yml`)
+- Broken Doorstop link format in 14 SWD items (`ARC003`/`ARC004` → `ARC-003`/`ARC-004`)
+- Orphaned TCS-001–TCS-007 with empty `links: []`; all now carry SRS traceability links
+- 14 SRS items with placeholder (TBD) text replaced with complete procedural descriptions
+- Missing MRS upward traceability links in ARC-003 (MRS-013, MRS-024, MRS-025, MRS-046, MRS-047) and ARC-004 (MRS-040, MRS-041, MRS-044, MRS-060)
+- HTML output path in `c5traceability.py` and `c5browser.py` resolved relative to script dir instead of specs dir; corrected to `SCRIPT_DIR.parent / "docs" / "publish"`
+- Typos in SRS items
+
+## Modified
+
+- `dev.Dockerfile` and `docEngine.Dockerfile` extended with Node.js 20.x, Chromium, and Mermaid CLI (`mmdc`) for Mermaid diagram rendering in the SpecEngine pipeline
+- `dev.Dockerfile` stripped of DocEngine dependencies (Quarto, TeX Live, fonts, cryptographic tools); `.devcontainer/devcontainer.json` updated to use `docEngine.Dockerfile`
+- `c5dec crypto` CLI upgraded from stub to full implementation dispatching to the native cryptography module
+- `c5dec cpssa` CLI extended with `fair-input` and `risk-analysis` subcommands
+- `c5traceability.py`: generalized to YAML-configurable, project-agnostic Doorstop traceability analyser; added `--config`, `--discover`, `--discover-write` flags and auto-discovery of document hierarchy from `.doorstop.yml` files
+- `c5browser.py`: extended to support both `.md` (Markdown frontmatter) and `.yml` (pure YAML) Doorstop item formats; document type list auto-discovered at runtime; numeric field detection for proper column sorting
+- All 246 Doorstop item files in `arc`, `mrs`, `srs`, `swd`, `tra`, `trb`, `tst` converted from pure YAML to Markdown with YAML frontmatter; `.doorstop.yml` configs updated to `itemformat: markdown`
+- ARC item files renamed to hyphenated format (`ARC001.yml` → `ARC-001.yml`); SWD items likewise (`SWD001.yml`–`SWD014.yml` → `SWD-001.yml`–`SWD-014.yml`)
+- PlantUML schematics relocated to `docs/specs/swd/assets/PlantUML/`; obsolete `classes.puml` and `subsystems.puml` removed
+- SpecEngine folder renamed from `docs/specs/c5dec-SpecEngine/` to `docs/specs/SpecEngine/`; `publish.sh` updated with linkification step, `c5graph.py` generation, and Mermaid render/undo steps
+- `c5publish.py` tooling-reports block moved to `<body>` top with "Traceability Graph" link added
+- DocEngine pre-render script updated from `custom_vars.py` to `custom_vars_v2.py`; default approval signatures set to placeholder (`"---"`)
+- **Docker security hardening**: non-root user, dropped Linux capabilities, `--no-install-recommends`, and package pinning applied to `Dockerfile`, `dev.Dockerfile`, and `docEngine.Dockerfile`; `.dockerignore` added to limit build context
+- **Unit test coverage significantly extended**: new test files for CLI (`cli_test.py`, 298 lines), ISMS (`isms_test.py`, 268 lines), SSDLC (`ssdlc_test.py`, 251 lines), Transformer (`transformer_test.py`, 176 lines), CPSSA (`cpssa_test.py`, 1175 lines), and cryptography (`cryptography_test.py`, 380 lines); existing CCT test files improved
+- Mermaid SVGs pre-rendered for SWD-002 and SWD-003; stored in `docs/specs/swd/assets/`
+- README, `docs/manual/README.md`, `docs/specs/README.md` 
+
+## Removed
+
+- DocEngine-specific dependencies from `dev.Dockerfile` (moved to `docEngine.Dockerfile`)
+- `c5traceability_v2.py`; merged into `c5traceability.py`
+- Stale Doorstop Bootstrap CSS/JS assets from `docs/assets/doorstop/`; replaced by CDN references
+- `docs/manual/overview.md`; content merged into `docs/manual/start.md`
+
+
 # 1.1 (2025-05-12)
 
 ## Added

CONTRIBUTING.md

@@ -0,0 +1,160 @@
+# Contributing to C5-DEC CAD
+
+Thank you for your interest in contributing to C5-DEC CAD. This document explains how to set up the development environment, submit changes, and follow project conventions.
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [Getting the code](#getting-the-code)
+- [Development environment](#development-environment)
+- [Branching and workflow](#branching-and-workflow)
+- [Commit message convention](#commit-message-convention)
+- [Running the test suite](#running-the-test-suite)
+- [Code conventions](#code-conventions)
+- [Documentation conventions](#documentation-conventions)
+- [Opening issues and pull requests](#opening-issues-and-pull-requests)
+
+---
+
+## Prerequisites
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [Docker Engine](https://docs.docker.com/engine/install/)
+- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
+- [Git](https://git-scm.com/)
+- [Poetry](https://python-poetry.org/) ≥ 1.1 (inside the dev container, Poetry is pre-installed)
+
+---
+
+## Getting the code
+
+```sh
+git clone https://github.com/AbstractionsLab/c5dec.git
+cd c5dec
+```
+
+Open the folder in VS Code and select **Reopen in Container** to start the `C5-DEC CAD dev container`. All Python dependencies are installed automatically via Poetry.
+
+---
+
+## Development environment
+
+Inside the dev container, activate the Poetry virtual environment:
+
+```sh
+poetry shell
+```
+
+You can then run any `c5dec` command directly:
+
+```sh
+c5dec -h
+```
+
+If you modify `pyproject.toml`, always validate it before committing:
+
+```sh
+poetry check
+```
+
+---
+
+## Branching and workflow
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Stable release branch; only merged from `develop` via pull request |
+| `develop` | Integration branch for ongoing work |
+| `feature/<short-description>` | New features or enhancements |
+| `fix/<short-description>` | Bug fixes |
+| `docs/<short-description>` | Documentation-only changes |
+
+1. Branch off from `develop` (not `main`):
+   ```sh
+   git checkout develop
+   git pull
+   git checkout -b feature/my-feature
+   ```
+2. Make changes in small, focused commits (see below).
+3. Push your branch and open a pull request targeting `develop`.
+
+---
+
+## Commit message convention
+
+Use the imperative mood and keep the subject line under 72 characters:
+
+```
+<type>: <short summary>
+
+[optional body — wrap at 72 chars]
+```
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `docs` | Documentation changes only |
+| `refactor` | Code restructuring with no functional change |
+| `test` | Adding or updating tests |
+| `chore` | Tooling, dependencies, CI changes |
+
+Example:
+
+```
+feat: add CRA Annex I checklist Excel export
+
+Adds per-category compliance percentage columns to the
+exported spreadsheet. Closes #42.
+```
+
+---
+
+## Running the test suite
+
+Run all tests from the repository root:
+
+```sh
+./run-test-suite.sh
+```
+
+Or with pytest directly (inside the Poetry environment):
+
+```sh
+pytest
+```
+
+Test fixtures live in `tests/content/`. Mock all external services (OpenProject, Doorstop remote) in new tests. 
+
+---
+
+## Code conventions
+
+- Target Python 3.8–3.11; avoid syntax or library features not available in 3.8.
+- Use `common.logger(__name__)` for logging; never `print()` for operational output.
+- Raise `common.C5decError` for expected error conditions.
+- Reference paths via `c5settings` constants — never hard-code file paths.
+- Follow NumPy/Google docstring style for all public functions and classes.
+- Run `poetry check` after any `pyproject.toml` modification.
+
+See `.github/instructions/python.instructions.md` for the full style guide.
+
+---
+
+## Documentation conventions
+
+- All documentation lives under `docs/` (`docs/manual/`, `docs/specs/`). Never place docs alongside source code.
+- File names: lowercase with hyphens (`debug-mode.md`). Exception: `README.md`.
+- Section headings: sentence case only (`## Getting started`, not `## Getting Started`).
+- Formats: Markdown, YAML, JSON, CSV, or LaTeX only.
+
+See `.github/instructions/docs.instructions.md` for the full guide.
+
+---
+
+## Opening issues and pull requests
+
+- Search existing issues before opening a new one.
+- For bug reports, include: C5-DEC version, deployment model (Docker scripts or dev container), steps to reproduce, expected vs actual behaviour.
+- For feature requests, describe the use case and how it fits the C5-DEC methodology.
+- Pull requests must include a description of the change and reference any related issue numbers.
+- To report a security vulnerability, follow the process in [SECURITY.md](SECURITY.md) instead of opening a public issue.