📚 Add guides for project licensing commands

guides/checking-licence-compliance.md

@@ -6,6 +6,11 @@ Use `cd-check-licence-compliance` as a CI gate or local check when you need to
 assess the project and its dependencies against the configured licence policy
 without generating SPDX documents. The command writes no files by default.
 
+When `FILE_LICENCE_IDENTIFIER` is one exact SPDX identifier, CDS also checks
+that the configured project licence file exists and matches that identifier
+before dependency compliance runs. Compound licence expressions skip this
+project-file check.
+
 ## Inputs and example
 
 Select a language plugin that provides project metadata. Configure
@@ -54,5 +59,7 @@ for the limits and report provenance.
 To generate SPDX tag-value documents as well as reports, use
 [`cd-generate-spdx`](generating-an-spdx-sbom.md). See
 [third-party IP reporting](third-party-ip-reporting.md) for more on reviewing
-the summaries and [project configuration](reading-project-configuration.md)
-for the shared settings.
+the summaries, [project configuration](reading-project-configuration.md)
+for the shared settings, and
+[syncing the project licence file](syncing-project-licence.md) for the
+top-level project licence workflow.

guides/checking-project-configuration.md

@@ -0,0 +1,37 @@
+# Check CDS project configuration
+
+## Problem and when to use it
+
+Use `cd-check-project-config` when you want to validate the CDS-specific
+`[ProjectConfig]` section in `pyproject.toml` before running other delivery
+commands. It is useful when setting up a project, reviewing configuration
+changes, or debugging why another CDS command fails early.
+
+The command checks the configuration keys CDS understands, validates expected
+types, verifies some formats such as regexes, URLs and UUIDs, and reuses the
+existing validation for licence-assessment policy overrides.
+
+## Inputs and example
+
+Run the command in a repository with `pyproject.toml`:
+
+```bash
+cd-check-project-config
+```
+
+To validate a specific file path instead of the nearest project config:
+
+```bash
+cd-check-project-config --config-file path/to/pyproject.toml
+```
+
+## Output
+
+The command prints `Project configuration is valid.` when the configuration
+passes validation. It fails if CDS finds unknown `ProjectConfig` keys, invalid
+types, malformed values, or invalid licence-assessment policy settings.
+
+Use it before [`cd-check-licence-compliance`](checking-licence-compliance.md),
+[`cd-generate-spdx`](generating-an-spdx-sbom.md) or
+[`cd-tag-and-release`](automating-releases.md) when configuration changes are
+part of the work.

guides/describing-project-licence-obligations.md

@@ -0,0 +1,39 @@
+# Describe project licence obligations
+
+## Problem and when to use it
+
+Use `cd-describe-licence-obligations` when you want a quick human-readable
+summary of the obligations attached to the project's configured licence.
+
+The command resolves the project licence from `FILE_LICENCE_IDENTIFIER` and
+combines data from SPDX.org, choosealicense.com and OSADL to explain the
+licence in practical terms.
+
+This command only covers projects configured with one exact SPDX identifier. It
+does not cover compound expressions such as `Apache-2.0 OR MIT`.
+
+## Inputs and example
+
+Configure `FILE_LICENCE_IDENTIFIER` in `[ProjectConfig]` and run:
+
+```bash
+cd-describe-licence-obligations
+```
+
+## Output
+
+The command prints a text report including:
+
+- the SPDX identifier and licence name
+- OSI approval when available
+- choosealicense.com summary information
+- permissions, conditions and limitations when available
+- OSADL checklist obligations when available
+
+For proprietary projects, CDS reports that the author must provide the full
+licence text and that obligations need manual review against the custom terms.
+
+Related commands:
+
+- [`cd-sync-project-licence`](syncing-project-licence.md)
+- [`cd-check-licence-compliance`](checking-licence-compliance.md)

guides/index.md

@@ -14,6 +14,8 @@ the [plugin guides](https://github.com/ARMmbed/continuous-delivery-scripts/tree/
 
 - [Assess dependency licence risks](assessing-dependency-licences.md): Review directional, explainable licence screening and optional project policy overrides.
 - [Check licence compliance](checking-licence-compliance.md): Gate a project without generating SPDX files; optionally write reports.
+- [Sync the project licence file](syncing-project-licence.md): Create or refresh the top-level project licence file from the configured SPDX identifier.
+- [Describe project licence obligations](describing-project-licence-obligations.md): Summarise obligations for the configured project licence.
 - [Generate an SPDX SBOM](generating-an-spdx-sbom.md): Produce project and dependency SPDX tag-value documents.
 - [Generate a third-party IP / TPIP report](third-party-ip-reporting.md): Review dependency licences and compliance summaries.
 - [Manage licence headers](licence-header-management.md): Apply copyright and SPDX headers to source files.
@@ -29,6 +31,7 @@ the [plugin guides](https://github.com/ARMmbed/continuous-delivery-scripts/tree/
 ## Other project checks
 
 - [Generate code documentation](generating-code-documentation.md): Build the API reference.
+- [Check project configuration](checking-project-configuration.md): Validate CDS `ProjectConfig` values before running other commands.
 - [Read project configuration](reading-project-configuration.md): Reuse values in scripts and CI.
 - [Record accepted secret findings](recording-secrets.md): Maintain the detect-secrets baseline.
 - [Check for new secrets](checking-for-secrets.md): Scan Git-tracked files in CI.

guides/syncing-project-licence.md

@@ -0,0 +1,49 @@
+# Sync the top-level project licence file
+
+## Problem and when to use it
+
+Use `cd-sync-project-licence` when a project has one exact SPDX licence
+identifier in `FILE_LICENCE_IDENTIFIER` and you want CDS to create or refresh
+the repository's top-level licence file from canonical public licence text.
+
+This is useful when bootstrapping a project, standardising an existing
+`LICENSE` file, or correcting drift before a release or compliance check.
+
+The command only covers projects configured with one exact SPDX identifier. It
+does not cover compound expressions such as `MIT OR Apache-2.0`.
+
+## Inputs and example
+
+Configure:
+
+- `FILE_LICENCE_IDENTIFIER`
+- `LICENCE_FILE_PATH` (defaults to `LICENSE`)
+
+Then run:
+
+```bash
+cd-sync-project-licence
+```
+
+CDS fetches canonical text in this order when needed:
+
+1. [ScanCode LicenseDB](https://scancode-licensedb.aboutcode.org/)
+2. [SPDX.org](https://spdx.org/licenses/)
+3. GitHub licences API
+4. [choosealicense.com](https://choosealicense.com/)
+
+## Output
+
+If the file is missing, CDS creates it. If the file exists but differs from the
+canonical text, CDS shows a diff in verbose mode and rewrites it. If the file
+already matches, the command reports success without changing it.
+
+For a proprietary project, CDS cannot fetch canonical text and instead requires
+the author to provide the licence file manually.
+
+Related commands:
+
+- [`cd-check-licence-compliance`](checking-licence-compliance.md) for strict
+  project and dependency licence checks
+- [`cd-describe-licence-obligations`](describing-project-licence-obligations.md)
+  for a summary of obligations

news/202610142140000000001.doc

@@ -0,0 +1 @@
+:books: Add guides for checking project configuration and for the project licence sync and obligations commands.