#5: Docs consistency pass

CONTRIBUTING.md

@@ -12,18 +12,18 @@
 
 ## Branch Naming
 
-Branches have to start with one of the allowed prefixes: `feature/`, `fix/`, `docs/`, `chore/`
+Branches have to start with one of the allowed prefixes — `feature/`, `fix/`, `docs/`, `chore/` — followed immediately by the related issue number, then a short kebab-case scope: `<prefix>/<issue>-<scope>`.
 Examples:
-- `feature/add-hierarchy-support`
+- `feature/128-add-hierarchy-support`
 - `fix/567-handle-empty-chapter`
-- `docs/improve-contribution-guide`
-- `chore/update-ci-python-version`
-  
+- `docs/203-improve-contribution-guide`
+- `chore/91-update-ci-python-version`
+
 Rename if needed before pushing:
 ```shell
-git branch -m fix/<new-name>
+git branch -m fix/<issue>-<new-name>
 ```
-Use lowercase **kebab-case** and reflect actual scope.
+Use lowercase **kebab-case** and reflect actual scope. The issue number is required — CI (`check-pr-requirements`) rejects a branch without one.
 
 ## PR Naming
 

docs/guides/getting-started.md

@@ -52,17 +52,17 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
 
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-issues.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-issues.json --output generator-ready.json
 
       - name: Generate Markdown
         uses: AbsaOSS/living-doc-generator-markdown@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           output-path: docs/generated
 
       - name: Publish
@@ -76,7 +76,7 @@ jobs:
 
 A few things to note about these inputs:
 
-- `doc-issues.json` / `pdf_ready.json` are `collector-gh`'s and `toolkit`'s current documented file names (`pdf_ready.json` is slated to be renamed `generator-ready.json` — see [Data Flows & Schemas](../specs/data-flows.md) §5 — but that migration hasn't shipped yet, so use `pdf_ready.json` today).
+- `doc-issues.json` and `generator-ready.json` are `collector-gh`'s and `toolkit`'s documented file names — `generator-ready.json` is the canonical dataset `toolkit`'s `normalize-issues` step emits (see [Data Flows & Schemas](../specs/data-flows.md) §5 for the naming rationale).
 - `living-doc normalize-issues` is `toolkit`'s actual CLI command, taking `--input`/`--output` file paths — this is a workflow step like any other, not a local-only affordance.
 - Swap the collector/generator `uses:` steps for the ones you picked in steps 1–2 above; each project's own README documents its exact action inputs and outputs, which evolve faster than this guide.
 

docs/introduction/quickstart.md

@@ -80,17 +80,17 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-issues.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-issues.json --output generator-ready.json
 
       # 3. GENERATE — canonical dataset -> Markdown files
       - name: Generate Markdown
         uses: AbsaOSS/living-doc-generator-markdown@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           output-path: docs/generated
 
       # 4. COMMIT the refreshed docs

docs/tutorials/ado-workitems-to-markdown.md

@@ -38,16 +38,16 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input work-items.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input work-items.json --output generator-ready.json
 
       - name: Generate Markdown
         uses: AbsaOSS/living-doc-generator-markdown@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           output-path: docs/generated
 
       - name: Commit output

docs/tutorials/gh-issues-to-markdown.md

@@ -34,16 +34,16 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-issues.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-issues.json --output generator-ready.json
 
       - name: Generate Markdown
         uses: AbsaOSS/living-doc-generator-markdown@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           output-path: docs/generated
 
       - name: Commit output

docs/tutorials/gh-source-to-markdown.md

@@ -51,17 +51,17 @@ jobs:
       # 2. NORMALIZE
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-source.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-source.json --output generator-ready.json
 
       # 3. GENERATE Markdown
       - name: Generate Markdown
         uses: AbsaOSS/living-doc-generator-markdown@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           output-path: docs/generated
 
       # 4. COMMIT

docs/tutorials/gh-source-to-pdf.md

@@ -46,17 +46,17 @@ jobs:
       # 2. NORMALIZE
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-source.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-source.json --output generator-ready.json
 
       # 3. GENERATE PDF — pick the document-type for the document you want
       - name: Generate PDF
         uses: AbsaOSS/living-doc-generator-pdf@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           document-type: user-stories        # or: ui-test-catalog | coverage-matrix
           output-path: reports/living-doc.pdf
 

docs/tutorials/user-stories-to-pdf.md

@@ -28,16 +28,16 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.10'
       - name: Normalize (toolkit)
         run: |
           pip install living-doc-toolkit
-          living-doc normalize-issues --input doc-issues.json --output pdf_ready.json   # renamed to generator-ready.json in a coming release
+          living-doc normalize-issues --input doc-issues.json --output generator-ready.json
 
       - name: Generate PDF
         uses: AbsaOSS/living-doc-generator-pdf@v1
         with:
-          source-path: pdf_ready.json
+          source-path: generator-ready.json
           document-type: user-stories
           output-path: reports/user-stories.pdf