docs-toolbox Architecture

This assembled architecture is a draft adaptation of the repository’s existing artifacts into the architecture-knowledge-toolkit structure. It treats local files as evidence and records uncertain claims as open questions or proposed architecture artifacts.

1. Introduction And Goals

docs-toolbox is a lightweight Docker image for running Docs-as-Code pipelines in a reproducible environment locally and in CI.

Within the Docs-as-Code Toolkit it provides the runtime layer for rendering. It can support direct Asciidoctor/Pandoc/Gradle builds and can also be combined with higher-level publishing workflows such as docToolchain when a consuming project chooses that path.

1.1. Quality Goals

The top-level quality goals are derived from README.md, .github/workflows/create-docs-toolbox-image.yml, and Dockerfile.

Priority	Goal	Evidence
1	Reproducible documentation builds across local and CI environments.	README states the image is for reproducible Docs-as-Code pipelines.
2	Fast contributor onboarding with zero local toolchain setup.	README emphasizes zero-setup onboarding and avoiding random local installs.
3	Consistent CI execution through a published container image.	GitHub Actions example uses the image as a job container.
4	Traceable image publication.	Workflow publishes a Dockerfile-hash tag and tag-based aliases.

Priority

Goal

Evidence

Reproducible documentation builds across local and CI environments.

README states the image is for reproducible Docs-as-Code pipelines.

Fast contributor onboarding with zero local toolchain setup.

README emphasizes zero-setup onboarding and avoiding random local installs.

Consistent CI execution through a published container image.

GitHub Actions example uses the image as a job container.

Traceable image publication.

Workflow publishes a Dockerfile-hash tag and tag-based aliases.

1.2. Requirements Overview

ID Requirement Evidence

ID	Requirement	Evidence
REQ-001	The repository shall build a Docker image named `docs-toolbox`.	Dockerfile and workflow image name step.
REQ-002	The image shall include Asciidoctor, Asciidoctor Diagram, Asciidoctor reveal.js, Pandoc, Graphviz, unzip, curl, and Python 3.	Dockerfile package and gem installation.
REQ-003	The image shall allow callers to run arbitrary commands.	Dockerfile uses an empty `ENTRYPOINT []`.
REQ-004	The release workflow shall publish multi-platform images to GHCR.	Workflow uses Docker Buildx with `linux/amd64,linux/arm64` and `--push`.
REQ-005	The workflow shall publish a Dockerfile-hash tag for every build on `main` or tags.	Workflow computes `df-<hash>`.
REQ-006	The repository shall build architecture documentation HTML without Gradle, including rendered PlantUML diagrams.	`build.sh` validates metadata, generates fragments, and runs Asciidoctor with `asciidoctor-diagram`.
REQ-007	Pull requests shall validate architecture documentation.	`.github/workflows/architecture-docs.yml` runs `./build.sh validate` for pull requests.
REQ-008	Pushes to `main` shall publish generated architecture HTML to GitHub Pages.	`.github/workflows/architecture-docs.yml` builds `build/architecture` and deploys it with GitHub Pages actions.
REQ-009	The image shall expose `asciidoctor-revealjs` so downstream projects can build Reveal.js presentations from `.adoc` files.	Dockerfile gem installation and README usage example.
REQ-010	The repository shall provide a docToolchain showcase that verifies HTML and PDF generation from the toolkit-compatible architecture sources.	`showcase/doctoolchain/build.sh` validates metadata, regenerates fragments, and runs `dtcw` against the assembled architecture source.
REQ-011	The image shall expose `docs-toolbox-serve` so downstream projects can serve generated static files without requiring a host-local web server runtime.	Dockerfile script installation and README usage example.

REQ-001

The repository shall build a Docker image named docs-toolbox.

Dockerfile and workflow image name step.

REQ-002

The image shall include Asciidoctor, Asciidoctor Diagram, Asciidoctor reveal.js, Pandoc, Graphviz, unzip, curl, and Python 3.

Dockerfile package and gem installation.

REQ-003

The image shall allow callers to run arbitrary commands.

Dockerfile uses an empty ENTRYPOINT [].

REQ-004

The release workflow shall publish multi-platform images to GHCR.

Workflow uses Docker Buildx with linux/amd64,linux/arm64 and --push.

REQ-005

The workflow shall publish a Dockerfile-hash tag for every build on main or tags.

Workflow computes df-<hash>.

REQ-006

The repository shall build architecture documentation HTML without Gradle, including rendered PlantUML diagrams.

build.sh validates metadata, generates fragments, and runs Asciidoctor with asciidoctor-diagram.

REQ-007

Pull requests shall validate architecture documentation.

.github/workflows/architecture-docs.yml runs ./build.sh validate for pull requests.

REQ-008

Pushes to main shall publish generated architecture HTML to GitHub Pages.

.github/workflows/architecture-docs.yml builds build/architecture and deploys it with GitHub Pages actions.

REQ-009

The image shall expose asciidoctor-revealjs so downstream projects can build Reveal.js presentations from .adoc files.

Dockerfile gem installation and README usage example.

REQ-010

The repository shall provide a docToolchain showcase that verifies HTML and PDF generation from the toolkit-compatible architecture sources.

showcase/doctoolchain/build.sh validates metadata, regenerates fragments, and runs dtcw against the assembled architecture source.

REQ-011

The image shall expose docs-toolbox-serve so downstream projects can serve generated static files without requiring a host-local web server runtime.

Dockerfile script installation and README usage example.

The list is incomplete until maintainers confirm which README claims are part of the supported contract.

1.3. Stakeholders

Stakeholder	Interest	Evidence
Documentation contributors	Run documentation builds without local setup.	README local Docker usage.
CI maintainers	Use one consistent toolchain image in workflows.	README GitHub Actions example.
Project maintainers	Publish traceable and reusable image versions.	GHCR workflow with hash and Git tags.
Downstream Docs-as-Code projects	Build AsciiDoc, Markdown, diagram, and document outputs.	README typical use cases.

Stakeholder

Interest

Evidence

Documentation contributors

Run documentation builds without local setup.

README local Docker usage.

CI maintainers

Use one consistent toolchain image in workflows.

README GitHub Actions example.

Project maintainers

Publish traceable and reusable image versions.

GHCR workflow with hash and Git tags.

Downstream Docs-as-Code projects

Build AsciiDoc, Markdown, diagram, and document outputs.

README typical use cases.

2. Architecture Constraints

The current constraints are derived from the existing Dockerfile, workflow, and license files.

2.1. Toolbox Constraints

Constraint Description Evidence

Constraint	Description	Evidence
Container delivery	The supported toolchain is packaged as an OCI/Docker image.	README and Dockerfile.
Base image	The current base is `openjdk:22-jdk-slim`.	Dockerfile `FROM` line.
Installed packages	Tools are installed with `apt-get install`.	Dockerfile package installation.
GHCR publication	Images are published to `ghcr.io/${GITHUB_REPOSITORY_OWNER}/docs-toolbox`.	Workflow `Set image name` step.
Multi-platform build	Workflow builds `linux/amd64` and `linux/arm64`.	Workflow `docker buildx build` command.
MIT license	Use and distribution follow MIT license terms.	`LICENSE.md`.

Container delivery

The supported toolchain is packaged as an OCI/Docker image.

README and Dockerfile.

Base image

The current base is openjdk:22-jdk-slim.

Dockerfile FROM line.

Installed packages

Tools are installed with apt-get install.

Dockerfile package installation.

GHCR publication

Images are published to ghcr.io/${GITHUB_REPOSITORY_OWNER}/docs-toolbox.

Workflow Set image name step.

Multi-platform build

Workflow builds linux/amd64 and linux/arm64.

Workflow docker buildx build command.

MIT license

Use and distribution follow MIT license terms.

LICENSE.md.

Open constraints are recorded in Questions And Answers.

3. System Scope And Context

3.1. Business Context

The system boundary is the docs-toolbox container image and its publication workflow. It contains the installed documentation toolchain and OCI metadata. Projects using the image, GitHub Actions runners, GHCR, and contributor workstations are external actors or systems.

3.2. Technical Context

Interface Partner Description

Interface	Partner	Description
Docker build context	Docker Buildx	The workflow builds the repository root using `Dockerfile`.
GHCR registry API	GHCR	The workflow authenticates and pushes built images.
Container command execution	Docker or CI runtime	Callers mount a workspace and run documentation commands inside the image.
README marker block	GitHub Actions shell step	The workflow extracts package description metadata from README markers.
Publishing workflow	Downstream project, docToolchain, or similar tools	The image provides a reproducible runtime layer; consuming projects own the publishing workflow choice.

Docker build context

Docker Buildx

The workflow builds the repository root using Dockerfile.

GHCR registry API

GHCR

The workflow authenticates and pushes built images.

Container command execution

Docker or CI runtime

Callers mount a workspace and run documentation commands inside the image.

README marker block

GitHub Actions shell step

The workflow extracts package description metadata from README markers.

Publishing workflow

Downstream project, docToolchain, or similar tools

The image provides a reproducible runtime layer; consuming projects own the publishing workflow choice.

4. Solution Strategy

The solution strategy is to publish one versioned OCI image that contains the documentation toolchain needed by downstream Docs-as-Code projects.

4.1. Strategy Overview

The current architecture uses a container image as the distribution unit for the Docs-as-Code toolchain. Build and publication are automated with GitHub Actions.

Strategy Rationale Evidence

Strategy	Rationale	Evidence
Containerize the toolchain	Avoid host setup and CI drift.	README philosophy and Dockerfile.
Keep entrypoint empty	Let consumers run arbitrary documentation commands.	Dockerfile `ENTRYPOINT []`.
Publish traceable tags	Help users choose deterministic image references.	Workflow `df-<hash>` tag.
Reuse README marker text	Keep package description close to product documentation.	Workflow README extraction step.
Verify publisher compatibility with a showcase	Prove that toolkit-compatible architecture sources can still be published by docToolchain.	`showcase/doctoolchain` renders the repository architecture to HTML and PDF with `dtcw`.

Containerize the toolchain

Avoid host setup and CI drift.

README philosophy and Dockerfile.

Keep entrypoint empty

Let consumers run arbitrary documentation commands.

Dockerfile ENTRYPOINT [].

Publish traceable tags

Help users choose deterministic image references.

Workflow df-<hash> tag.

Reuse README marker text

Keep package description close to product documentation.

Workflow README extraction step.

Verify publisher compatibility with a showcase

Prove that toolkit-compatible architecture sources can still be published by docToolchain.

showcase/doctoolchain renders the repository architecture to HTML and PDF with dtcw.

5. Building Block View

5.1. Level 1 Building Blocks

Building Block Responsibility Interface Storage Location

Building Block	Responsibility	Interface	Storage Location
OCI image	Provide a runnable documentation toolbox environment.	Docker image command execution.	Built from `Dockerfile`, published to GHCR.
Documentation toolchain	Provide Asciidoctor, Asciidoctor Diagram, Asciidoctor reveal.js, Pandoc, Graphviz, unzip, curl, Python 3, and `docs-toolbox-serve`.	CLI commands, Asciidoctor Ruby extensions, and helper scripts inside the image.	Installed by `apt-get`, `gem install`, and `COPY` in `Dockerfile`.
Build workflow	Build, tag, and push the image.	GitHub Actions workflow dispatch, push, and tag events.	`.github/workflows/create-docs-toolbox-image.yml`.
README description marker	Provide package description metadata.	Marker block parsed by workflow shell step.	`README.md`.

OCI image

Provide a runnable documentation toolbox environment.

Docker image command execution.

Built from Dockerfile, published to GHCR.

Documentation toolchain

Provide Asciidoctor, Asciidoctor Diagram, Asciidoctor reveal.js, Pandoc, Graphviz, unzip, curl, Python 3, and docs-toolbox-serve.

CLI commands, Asciidoctor Ruby extensions, and helper scripts inside the image.

Installed by apt-get, gem install, and COPY in Dockerfile.

Build workflow

Build, tag, and push the image.

GitHub Actions workflow dispatch, push, and tag events.

.github/workflows/create-docs-toolbox-image.yml.

README description marker

Provide package description metadata.

Marker block parsed by workflow shell step.

README.md.

6. Runtime View

6.1. Local Usage Runtime Scenario

The README example runs asciidoctor -v in the toolbox container.

6.1.1. Architecture Documentation Build

For this repository itself, ./build.sh build validates architecture metadata, generates derived fragments, and renders src/docs/doc-001-arc42.adoc to build/architecture/index.html with Asciidoctor and asciidoctor-diagram. Generated diagram assets are written beside the HTML output.

This is intentional dogfooding: the architecture documentation for the toolbox is generated with the toolbox image itself whenever a container engine is available.

The script first computes the local Dockerfile hash and tries to pull ghcr.io/docs-as-code-toolkit/docs-toolbox:df-<hash>. If that image is not available, the script builds a local image from the current Dockerfile before running the documentation build. This keeps local Dockerfile changes visible to the build without requiring Gradle.

Gradle projects can still use AsciidoctorJ inside the same toolbox image. This repository’s direct CLI build uses the Ruby Asciidoctor path.

6.1.2. docToolchain Showcase

The showcase/doctoolchain workflow validates that the same architecture sources can also be consumed by docToolchain. It runs the toolkit metamodel validator and generators first, then renders the assembled architecture document with dtcw generateHTML and dtcw generatePDF.

The default showcase path uses dtcw local and installs the configured docToolchain version under $HOME/.doctoolchain when necessary. The same script also supports dtcw docker for environments where the docToolchain container is available.

6.2. Image Publication Runtime Scenario

6.3. Failure And Recovery Runtime Scenario

Failure Observed Effect Recovery Candidate

Failure	Observed Effect	Recovery Candidate
GHCR authentication fails	Workflow cannot push images.	Verify `GHCR_PAT`, package permissions, and GitHub actor access.
Package installation fails	Docker build fails during `apt-get install`.	Re-run after upstream recovery or pin/update affected package source.
Tool command missing in image	Downstream documentation command fails.	Add a smoke test and update Dockerfile if the tool is supported.
README marker missing	Workflow uses fallback description.	Restore marker block or accept fallback behavior.

GHCR authentication fails

Workflow cannot push images.

Verify GHCR_PAT, package permissions, and GitHub actor access.

Package installation fails

Docker build fails during apt-get install.

Re-run after upstream recovery or pin/update affected package source.

Tool command missing in image

Downstream documentation command fails.

Add a smoke test and update Dockerfile if the tool is supported.

README marker missing

Workflow uses fallback description.

Restore marker block or accept fallback behavior.

7. Deployment View

7.1. Local And CI Deployment

Environment Deployment Form Notes

Environment	Deployment Form	Notes
Contributor workstation	Docker container run with mounted workspace.	README uses `docker run --rm -v $(pwd):/workspace -w /workspace`.
GitHub Actions runner	Job container or image build environment.	README shows the image as a job container; workflow builds with Buildx.
GHCR	Published multi-platform image.	Workflow pushes `linux/amd64` and `linux/arm64` images.
Downstream CI	Pinned image reference.	README recommends pinning versions for determinism.
GitHub Pages	Static architecture HTML generated from `src/docs/doc-001-arc42.adoc`.	`.github/workflows/architecture-docs.yml` uploads `build/architecture` to the expected URL `https://docs-as-code-toolkit.github.io/docs-toolbox/` after the first successful deployment.
docToolchain showcase	Local or containerized `dtcw` execution against the repository architecture sources.	`showcase/doctoolchain/build.sh` can render HTML and PDF using `local` or `docker` mode.

Contributor workstation

Docker container run with mounted workspace.

README uses docker run --rm -v $(pwd):/workspace -w /workspace.

GitHub Actions runner

Job container or image build environment.

README shows the image as a job container; workflow builds with Buildx.

GHCR

Published multi-platform image.

Workflow pushes linux/amd64 and linux/arm64 images.

Downstream CI

Pinned image reference.

README recommends pinning versions for determinism.

GitHub Pages

Static architecture HTML generated from src/docs/doc-001-arc42.adoc.

.github/workflows/architecture-docs.yml uploads build/architecture to the expected URL https://docs-as-code-toolkit.github.io/docs-toolbox/ after the first successful deployment.

docToolchain showcase

Local or containerized dtcw execution against the repository architecture sources.

showcase/doctoolchain/build.sh can render HTML and PDF using local or docker mode.

8. Crosscutting Concepts

8.1. Threat Model

ID STRIDE Threat Mitigation Candidate

ID	STRIDE	Threat	Mitigation Candidate
T-001	Tampering	Published image contents may not match maintainer intent.	Build from repository source in GitHub Actions and publish traceable tags.
T-002	Spoofing	Unauthorized actor may push to GHCR if credentials are misused.	Limit `GHCR_PAT` scope and review package permissions.
T-003	Information disclosure	Workflow logs may expose sensitive token handling if commands change.	Keep token use through `docker login --password-stdin`.
T-004	Denial of service	Upstream package or registry outage may block image publication.	Retry after outage and consider package pinning/mirroring policy.

T-001

Tampering

Published image contents may not match maintainer intent.

Build from repository source in GitHub Actions and publish traceable tags.

T-002

Spoofing

Unauthorized actor may push to GHCR if credentials are misused.

Limit GHCR_PAT scope and review package permissions.

T-003

Information disclosure

Workflow logs may expose sensitive token handling if commands change.

Keep token use through docker login --password-stdin.

T-004

Denial of service

Upstream package or registry outage may block image publication.

Retry after outage and consider package pinning/mirroring policy.

8.2. Security

Current evidence:

Workflow requests contents: read and packages: write.
GHCR login uses ${{ secrets.GHCR_PAT }} via standard input.
The Dockerfile removes /var/lib/apt/lists/* after package installation.

Open security decisions:

Whether image signing is required.
Whether vulnerability scanning is required before publishing.
Whether the GHCR token can be replaced with GITHUB_TOKEN permissions.

8.3. Testing

No automated tests were found in the repository during this migration.

Proposed smoke tests:

Build the Docker image.
Run asciidoctor --version.
Run asciidoctor-revealjs --version.
Run ruby -e 'require "asciidoctor-diagram"'.
Run ruby -e 'require "asciidoctor-diagram/plantuml"'.
Run pandoc --version.
Run dot -V.
Run curl --version.
Run unzip -v.
Render a minimal PlantUML block through asciidoctor -r asciidoctor-diagram.
Render a minimal slide deck through asciidoctor-revealjs with an explicit revealjsdir value.

These tests would turn README claims about available tools into executable evidence.

Current documentation checks:

Pull requests run ./build.sh validate.
The main branch Pages workflow runs ./build.sh build.
build.sh validate runs ruby scripts/validate-metamodel.rb --generate.
showcase/doctoolchain/build.sh html local and showcase/doctoolchain/build.sh pdf local verify that docToolchain can render the toolkit-compatible architecture sources to HTML and PDF.

8.4. Observability

Observable signals currently visible from repository evidence:

Docker command exit codes and standard output for local usage.
GitHub Actions logs for image name, tags, README description, and summary.
GHCR package tags and annotations after a successful build.

No runtime application logs, metrics, traces, or audit trails exist inside the image because the image is a toolbox environment, not a long-running service.

8.5. Error Handling

The workflow shell steps use set -euo pipefail in the tag computation, description extraction, and build/push steps. This means most command failures fail the workflow instead of being silently ignored.

The README description extraction step has a fallback description if the marker block is absent or empty. Docker command failures are surfaced through the container process exit code.

9. Architecture Decisions

9.1. ADR Index

ADR	Title	Status	Notes
ADR-001	Containerized Docs Toolchain	proposed	Proposes treating the Docker image as the supported distribution unit for the Docs-as-Code toolchain.
ADR-002	GHCR Publication Tags	proposed	Proposes documenting Dockerfile-hash, Git tag, and latest tag semantics.

ADR

Title

Status

Notes

ADR-001

Containerized Docs Toolchain

proposed

Proposes treating the Docker image as the supported distribution unit for the Docs-as-Code toolchain.

ADR-002

GHCR Publication Tags

proposed

Proposes documenting Dockerfile-hash, Git tag, and latest tag semantics.

9.2. Open Questions

Question Role Topic

Question	Role	Topic
Q-ARCH-001	Architecture	Is `openjdk:22-jdk-slim` the intentional long-term base?
Q-ARCH-002	Architecture	What smoke tests should verify image readiness?
Q-ARCH-003	Architecture	Should Reveal.js assets be bundled in the toolbox image?
Q-ARCH-004	Architecture	Should docToolchain be installed in the toolbox image?
Q-PO-001	Product Owner	Which installed tools are part of the supported contract?
Q-PO-002	Product Owner	What tag should users pin for reproducible CI builds?
Q-PO-003	Product Owner	Should package versions be pinned inside the Dockerfile?

Q-ARCH-001

Architecture

Is openjdk:22-jdk-slim the intentional long-term base?

Q-ARCH-002

Architecture

What smoke tests should verify image readiness?

Q-ARCH-003

Architecture

Should Reveal.js assets be bundled in the toolbox image?

Q-ARCH-004

Architecture

Should docToolchain be installed in the toolbox image?

Q-PO-001

Product Owner

Which installed tools are part of the supported contract?

Q-PO-002

Product Owner

What tag should users pin for reproducible CI builds?

Q-PO-003

Product Owner

Should package versions be pinned inside the Dockerfile?

9.3. ADR-001: Containerized Docs Toolchain

9.3.1. Status

Proposed.

This ADR is derived from existing repository evidence and requires maintainer review before it becomes accepted architecture truth.

9.3.2. Decision

We propose to treat the docs-toolbox Docker image as the supported distribution unit for the documentation toolchain.

9.3.3. Context

The README describes the image as the single source of truth for the documentation toolchain. The Dockerfile packages OpenJDK plus documentation tools. The workflow publishes the image to GHCR.

9.3.4. Decision Drivers

Reproducible local and CI builds.
Low contributor setup effort.
Traceable image publication.

9.3.5. Considered Options

Option 1: Containerized Toolbox Image

Package the toolchain as a Docker image.

Option 2: Host Installation Documentation

Document installation commands for each supported host environment.

Option 3: Project-Specific CI Setup

Let every downstream project install tools in its own pipeline.

9.3.6. Pugh Matrix

Criterion	Container image	Host installation	Project-specific CI
Reproducibility	+1	-1	-1
Contributor onboarding	+1	-1	0
CI consistency	+1	-1	-1
Maintenance simplicity	0	-1	-1
Sum	3	-4	-3

9.3.7. Consequences

Positive

Downstream users can run the same image locally and in CI.
Maintainers can publish traceable image tags.

Negative

Image rebuilds may drift if upstream package versions change.
Users need Docker or a compatible container runtime.

Neutral or Follow-Up

Maintainers should decide whether package versions need explicit pinning.

9.4. ADR-002: GHCR Publication Tags

9.4.1. Status

Proposed.

9.4.2. Decision

We propose to document the current publication tag behavior as an explicit architecture and user contract after maintainer review.

9.4.3. Context

The workflow always computes a Dockerfile hash tag df-<hash>. If the commit has a Git tag, it also publishes the Git tag and latest.

9.4.4. Decision Drivers

Deterministic downstream CI configuration.
Clear release communication.
Compatibility with the existing workflow.

9.4.5. Considered Options

Option 1: Current Tag Set

Use Dockerfile hash tags for all builds and Git tag plus latest for tagged commits.

Option 2: Git Tags Only

Publish only human release tags.

Option 3: Latest Only

Publish only latest.

9.4.6. Pugh Matrix

Criterion	Current tag set	Git tags only	Latest only
Traceability	+1	0	-1
User simplicity	0	+1	+1
Reproducibility	+1	+1	-1
Workflow fit	+1	0	-1
Sum	3	2	-2

9.4.7. Consequences

Positive

Users can choose between hash-based traceability and release tags.

Negative

README guidance must explain when latest is published and why pinning is preferred.

9.5. ADR Candidates

The migration found the following decision candidates:

Whether openjdk:22-jdk-slim is the long-term base image.
Whether Debian package versions should be pinned.
Whether GHCR_PAT should remain the registry authentication mechanism.
Whether image signing or vulnerability scanning is required before publishing.
Whether GitHub Pages is the long-term publication channel for architecture documentation.
Whether Reveal.js frontend assets should be bundled in the toolbox image or supplied by downstream projects through revealjsdir.
Whether docToolchain support should remain a repository-local showcase, move into a dedicated showcase repository, or become a preinstalled variant of the docs-toolbox image.

10. Quality Requirements

10.1. Quality Scenarios

ID Objective Source Stimulus Artifact Environment Response Response measure

ID	Objective	Source	Stimulus	Artifact	Environment	Response	Response measure
QS-001	DOC-01001-quality-goals	Documentation contributor or CI pipeline	Runs a documentation build using the same pinned `docs-toolbox` image reference	Containerized documentation toolchain	Local workstation and GitHub Actions runner	The same documented tools are available in both environments	All supported tool smoke-test commands pass in both environments for the same image reference
QS-002	DOC-01001-quality-goals	Downstream project pipeline	Starts the image and calls a documented CLI tool	Installed packages inside `docs-toolbox`	Normal CI execution	The command exists and returns version or help output	`asciidoctor`, `asciidoctor-revealjs`, `pandoc`, `dot`, `curl`, `unzip`, `python3`, and `docs-toolbox-serve` version/help checks all exit successfully, and Ruby can require `asciidoctor-diagram` and `asciidoctor-diagram/plantuml`
QS-003	DOC-01001-quality-goals	Maintainer	Inspects a published image tag after workflow completion	GHCR image tags and annotations	Successful GitHub Actions build on `main` or a Git tag	The image has a Dockerfile-hash tag and source annotation; tagged commits also publish Git tag and `latest`	Workflow summary prints the Dockerfile hash tag on every successful run and prints the Git tag when present

QS-001

DOC-01001-quality-goals

Documentation contributor or CI pipeline

Runs a documentation build using the same pinned docs-toolbox image reference

Containerized documentation toolchain

Local workstation and GitHub Actions runner

The same documented tools are available in both environments

All supported tool smoke-test commands pass in both environments for the same image reference

QS-002

DOC-01001-quality-goals

Downstream project pipeline

Starts the image and calls a documented CLI tool

Installed packages inside docs-toolbox

Normal CI execution

The command exists and returns version or help output

asciidoctor, asciidoctor-revealjs, pandoc, dot, curl, unzip, python3, and docs-toolbox-serve version/help checks all exit successfully, and Ruby can require asciidoctor-diagram and asciidoctor-diagram/plantuml

QS-003

DOC-01001-quality-goals

Maintainer

Inspects a published image tag after workflow completion

GHCR image tags and annotations

Successful GitHub Actions build on main or a Git tag

The image has a Dockerfile-hash tag and source annotation; tagged commits also publish Git tag and latest

Workflow summary prints the Dockerfile hash tag on every successful run and prints the Git tag when present

10.2. Quality Tree

Reproducibility
- QS-001: Reproducible Toolchain
- QS-003: Publication Traceability
Usability
- QS-002: Toolchain Availability
Maintainability
- Candidate: automated smoke tests for all supported tools.

10.3. QS-001: Reproducible Toolchain

10.3.1. Status

Proposed.

10.3.2. Scenario

Element Description

Element	Description
Source	Documentation contributor or CI pipeline.
Stimulus	Runs a documentation build using the same pinned `docs-toolbox` image reference.
Environment	Local workstation and GitHub Actions runner.
Artifact	Containerized documentation toolchain.
Response	The same documented tools are available in both environments.
Response Measure	All supported tool smoke-test commands pass in both environments for the same image reference.

Source

Documentation contributor or CI pipeline.

Stimulus

Runs a documentation build using the same pinned docs-toolbox image reference.

Environment

Local workstation and GitHub Actions runner.

Artifact

Containerized documentation toolchain.

Response

The same documented tools are available in both environments.

Response Measure

All supported tool smoke-test commands pass in both environments for the same image reference.

10.3.3. Assumptions

The exact supported smoke-test command list requires maintainer confirmation.

10.4. QS-002: Toolchain Availability

10.4.1. Status

Proposed.

10.4.2. Scenario

Element Description

Element	Description
Source	Downstream project pipeline.
Stimulus	Starts the image and calls a documented CLI tool.
Environment	Normal CI execution.
Artifact	Installed packages inside `docs-toolbox`.
Response	The command exists and returns version or help output.
Response Measure	`asciidoctor`, `asciidoctor-revealjs`, `pandoc`, `dot`, `curl`, `unzip`, `python3`, and `docs-toolbox-serve` version/help checks all exit successfully, and Ruby can require `asciidoctor-diagram` and `asciidoctor-diagram/plantuml`.

Source

Downstream project pipeline.

Stimulus

Starts the image and calls a documented CLI tool.

Environment

Normal CI execution.

Artifact

Installed packages inside docs-toolbox.

Response

The command exists and returns version or help output.

Response Measure

10.4.3. Assumptions

The command names should be confirmed against the actual image entrypoint and package paths.
A minimal diagram rendering smoke test should confirm the Asciidoctor CLI path.
A minimal slide rendering smoke test should confirm the Asciidoctor reveal.js CLI path and explicit revealjsdir handling.
A static web server smoke test should confirm that docs-toolbox-serve --help works and that the command serves a generated presentation directory.

10.5. QS-003: Publication Traceability

10.5.1. Status

Proposed.

10.5.2. Scenario

Element Description

Element	Description
Source	Maintainer.
Stimulus	Inspects a published image tag after workflow completion.
Environment	Successful GitHub Actions build on `main` or a Git tag.
Artifact	GHCR image tags and annotations.
Response	The image has a Dockerfile-hash tag and source annotation; tagged commits also publish Git tag and `latest`.
Response Measure	Workflow summary prints the Dockerfile hash tag on every successful run and prints the Git tag when present.

Source

Maintainer.

Stimulus

Inspects a published image tag after workflow completion.

Environment

Successful GitHub Actions build on main or a Git tag.

Artifact

GHCR image tags and annotations.

Response

The image has a Dockerfile-hash tag and source annotation; tagged commits also publish Git tag and latest.

Response Measure

Workflow summary prints the Dockerfile hash tag on every successful run and prints the Git tag when present.

10.5.3. Assumptions

Maintainers should confirm whether source annotations are sufficient traceability or whether commit SHA labels are required.

11. Risks And Technical Debt

11.1. Risks

ID	Risk	Probability	Impact	Priority	Mitigation/action
RISK-001	Unpinned Package Versions	Medium	Medium	Medium	QS-001-reproducible-toolchain
RISK-002	Registry Publication Credentials	Low	High	Medium	QS-003-publication-traceability
RISK-003	Ambiguous Latest Tag	Medium	Medium	Medium	QS-003-publication-traceability

Risk

Probability

Impact

Priority

Mitigation/action

RISK-001

Unpinned Package Versions

Medium

QS-001-reproducible-toolchain

RISK-002

Registry Publication Credentials

Low

High

Medium

QS-003-publication-traceability

RISK-003

Ambiguous Latest Tag

Medium

QS-003-publication-traceability

11.2. Technical Debt

ID	Debt Candidate	Affected Building Block
TD-001	No automated smoke tests currently prove that the image contains every documented tool.	Documentation toolchain.
TD-003	Package version support policy is not recorded.	Dockerfile and publication workflow.

Debt Candidate

Affected Building Block

TD-001

No automated smoke tests currently prove that the image contains every documented tool.

Documentation toolchain.

TD-003

Package version support policy is not recorded.

Dockerfile and publication workflow.

11.3. RISK-001: Unpinned Package Versions

11.3.1. Status

Proposed.

11.3.2. Risk Statement

Because the Dockerfile installs packages from distribution repositories without explicit package version pins, future image rebuilds may contain different tool versions, leading to unexpected documentation build differences.

11.3.3. Assessment

Field	Value
Likelihood	Medium.
Impact	Medium.
Priority	Medium.
Timeframe	Medium-term.
Confidence	Medium.

Field

Value

Likelihood

Medium.

Impact

Medium.

Priority

Medium.

Timeframe

Medium-term.

Confidence

Medium.

11.3.4. Mitigation Options

Decide whether package pinning is required.
Add smoke tests and publish tested image references.
Document recommended tag pinning for downstream CI.

11.4. RISK-002: Registry Publication Credentials

11.4.1. Status

Proposed.

11.4.2. Risk Statement

Because the workflow authenticates to GHCR using GHCR_PAT, token misconfiguration or exposure may prevent image publication or allow unintended package writes.

11.4.3. Assessment

Field	Value
Likelihood	Low.
Impact	High.
Priority	Medium.
Timeframe	Near-term.
Confidence	Medium.

Field

Value

Likelihood

Low.

Impact

High.

Priority

Medium.

Timeframe

Near-term.

Confidence

Medium.

11.4.4. Mitigation Options

Keep workflow permissions minimal.
Review whether GITHUB_TOKEN can replace the PAT.
Rotate the token if exposure is suspected.

11.5. RISK-003: Ambiguous Latest Tag

11.5.1. Status

Proposed.

11.5.2. Risk Statement

Because latest is a moving tag and is published for tagged commits, downstream users may pin latest in CI and lose reproducibility across time.

11.5.3. Assessment

Field	Value
Likelihood	Medium.
Impact	Medium.
Priority	Medium.
Timeframe	Near-term.
Confidence	Medium.

Field

Value

Likelihood

Medium.

Impact

Medium.

Priority

Medium.

Timeframe

Near-term.

Confidence

Medium.

11.5.4. Mitigation Options

Document recommended pinning behavior.
Prefer Git tag or Dockerfile hash references in CI examples.
Clarify when latest is published.

12. Glossary

12.1. Terms

Term Meaning

Term	Meaning
Docs-as-Code	Treating documentation sources, reviews, builds, and publishing as code-like versioned workflows.
docs-toolbox	The container image built by this repository for documentation pipelines.
GHCR	GitHub Container Registry, the publication target used by the workflow.
Dockerfile hash tag	Image tag of the form `df-<hash>` derived from the Dockerfile SHA-256 hash prefix.
Asciidoctor reveal.js	Converter that turns AsciiDoc slide sources into Reveal.js HTML presentations.
Supported tool	A CLI tool that maintainers confirm as part of the image contract.

Docs-as-Code

Treating documentation sources, reviews, builds, and publishing as code-like versioned workflows.

docs-toolbox

The container image built by this repository for documentation pipelines.

GHCR

GitHub Container Registry, the publication target used by the workflow.

Dockerfile hash tag

Image tag of the form df-<hash> derived from the Dockerfile SHA-256 hash prefix.

Asciidoctor reveal.js

Converter that turns AsciiDoc slide sources into Reveal.js HTML presentations.

Supported tool

A CLI tool that maintainers confirm as part of the image contract.

13. Appendix

13.1. Questions And Answers

This document records open questions and assumptions discovered while adapting existing repository artifacts into the toolkit documentation structure.

13.1.1. Open Questions For Product Owner

Q-PO-001: Which installed tools are part of the supported contract?

Answer: Open.

Evidence currently shows Asciidoctor, Asciidoctor Diagram, Asciidoctor reveal.js, Pandoc, Graphviz, unzip, curl, Python 3, OpenJDK, and the docs-toolbox-serve helper in the Dockerfile. It is not yet reviewed whether all of them are long-term supported features or implementation conveniences.

Q-PO-002: What tag should users pin for reproducible CI builds?

Answer: Open.

The workflow publishes df-<hash> tags and, on Git-tagged commits, the Git tag and latest. Maintainers should confirm recommended user guidance.

Q-PO-003: Should package versions be pinned inside the Dockerfile?

Answer: Open.

The current Dockerfile installs packages from the base distribution repositories without explicit package version pins.

13.1.2. Open Questions For Architecture

Q-ARCH-001: Is `openjdk:22-jdk-slim` the intentional long-term base?

Answer: Open.

The Dockerfile uses this base image. The architectural rationale and update policy are not recorded yet.

Q-ARCH-002: What smoke tests should verify image readiness?

Answer: Open.

No automated tests were found in this repository. A candidate is verifying the version command for each supported CLI tool.

Q-ARCH-003: Should Reveal.js assets be bundled in the toolbox image?

Answer: Open.

The image now provides the asciidoctor-revealjs converter. Slide rendering still needs a revealjsdir value that points to CDN-hosted, vendored, or local Reveal.js frontend assets.

Q-ARCH-004: Should docToolchain be installed in the toolbox image?

Answer: Open.

Current assumption: docs-toolbox should first stay a lightweight, reproducible runtime for the tools already used by the project: Asciidoctor, Asciidoctor Diagram, Pandoc, Graphviz, and Java/Gradle-based builds. This does not compete with docToolchain. docToolchain can remain a higher-level publishing workflow that consumes structured AsciiDoc sources, while docs-toolbox provides local and CI rendering support. Installing docToolchain in the image should be a deliberate product decision, not an implicit dependency.

13.2. Traceability Matrix

Artifact ID	Type	Title	Status	Outgoing relations	Incoming relations
ADR-001-containerized-docs-toolchain	ADR	Containerized Docs Toolchain	proposed	addresses → QS-001-reproducible-toolchain introduces_risk → RISK-001-unpinned-package-versions	DOC-02001-toolbox-constraints → constrains
ADR-002-ghcr-publication-tags	ADR	GHCR Publication Tags	proposed	addresses → QS-003-publication-traceability introduces_risk → RISK-003-ambiguous-latest-tag	-
DOC-001-arc42	Document	docs-toolbox Architecture	draft	documents → DOC-01000-introduction-and-goals documents → DOC-02000-architecture-constraints documents → DOC-03000-system-scope-and-context documents → DOC-04000-solution-strategy documents → DOC-05000-building-block-view documents → DOC-06000-runtime-view documents → DOC-07000-deployment-view documents → DOC-08000-crosscutting-concepts documents → DOC-09000-architecture-decisions documents → DOC-10000-quality-requirements documents → DOC-11000-risks-and-technical-debt documents → DOC-12000-glossary documents → DOC-13000-appendix	-
DOC-01000-introduction-and-goals	Document	Introduction And Goals	draft	-	DOC-001-arc42 → documents DOC-01001-quality-goals → refines DOC-01002-requirements-overview → refines DOC-01003-stakeholders → refines
DOC-01001-quality-goals	Document	Quality Goals	draft	refines → DOC-01000-introduction-and-goals	QS-001-reproducible-toolchain → refines QS-002-toolchain-availability → refines QS-003-publication-traceability → refines
DOC-01002-requirements-overview	Document	Requirements Overview	draft	refines → DOC-01000-introduction-and-goals	-
DOC-01003-stakeholders	Document	Stakeholders	draft	refines → DOC-01000-introduction-and-goals	-
DOC-02000-architecture-constraints	Document	Architecture Constraints	draft	-	DOC-001-arc42 → documents DOC-02001-toolbox-constraints → refines
DOC-02001-toolbox-constraints	Document	Toolbox Constraints	draft	constrains → ADR-001-containerized-docs-toolchain refines → DOC-02000-architecture-constraints	-
DOC-03000-system-scope-and-context	Document	System Scope And Context	draft	-	DOC-001-arc42 → documents DOC-03001-business-context → refines DOC-03002-technical-context → refines
DOC-03001-business-context	Document	Business Context	draft	refines → DOC-03000-system-scope-and-context	-
DOC-03002-technical-context	Document	Technical Context	draft	refines → DOC-03000-system-scope-and-context	-
DOC-04000-solution-strategy	Document	Solution Strategy	draft	-	DOC-001-arc42 → documents DOC-04001-strategy-overview → refines
DOC-04001-strategy-overview	Document	Strategy Overview	draft	addresses → QS-001-reproducible-toolchain refines → DOC-04000-solution-strategy	-
DOC-05000-building-block-view	Document	Building Block View	draft	-	DOC-001-arc42 → documents DOC-05001-level-1 → refines
DOC-05001-level-1	Document	Level 1 Building Blocks	draft	affects → QS-002-toolchain-availability refines → DOC-05000-building-block-view	-
DOC-06000-runtime-view	Document	Runtime View	draft	-	DOC-001-arc42 → documents DOC-06001-local-usage → refines DOC-06002-image-publication → refines DOC-06003-failure-recovery → refines
DOC-06001-local-usage	Document	Local Usage Runtime Scenario	draft	addresses → QS-001-reproducible-toolchain refines → DOC-06000-runtime-view	-
DOC-06002-image-publication	Document	Image Publication Runtime Scenario	draft	addresses → QS-003-publication-traceability refines → DOC-06000-runtime-view	-
DOC-06003-failure-recovery	Document	Failure And Recovery Runtime Scenario	draft	affects → RISK-001-unpinned-package-versions refines → DOC-06000-runtime-view	-
DOC-07000-deployment-view	Document	Deployment View	draft	-	DOC-001-arc42 → documents DOC-07001-local-and-ci → refines
DOC-07001-local-and-ci	Document	Local And CI Deployment	draft	refines → DOC-07000-deployment-view	-
DOC-08000-crosscutting-concepts	Document	Crosscutting Concepts	draft	-	DOC-001-arc42 → documents DOC-08001-threat-model → refines DOC-08002-security → refines DOC-08003-testing → refines DOC-08004-observability → refines DOC-08005-error-handling → refines
DOC-08001-threat-model	Document	Threat Model	draft	refines → DOC-08000-crosscutting-concepts	-
DOC-08002-security	Document	Security	draft	mitigates → RISK-002-registry-publication-credentials refines → DOC-08000-crosscutting-concepts	-
DOC-08003-testing	Document	Testing	draft	refines → DOC-08000-crosscutting-concepts verifies → QS-002-toolchain-availability	-
DOC-08004-observability	Document	Observability	draft	refines → DOC-08000-crosscutting-concepts	-
DOC-08005-error-handling	Document	Error Handling	draft	refines → DOC-08000-crosscutting-concepts	-
DOC-09000-architecture-decisions	Document	Architecture Decisions	draft	-	DOC-001-arc42 → documents DOC-09001-adr-candidates → refines
DOC-09001-adr-candidates	Document	ADR Candidates	draft	refines → DOC-09000-architecture-decisions	-
DOC-10000-quality-requirements	Document	Quality Requirements	draft	-	DOC-001-arc42 → documents DOC-10002-quality-tree → refines
DOC-10002-quality-tree	Document	Quality Tree	draft	refines → DOC-10000-quality-requirements	-
DOC-11000-risks-and-technical-debt	Document	Risks And Technical Debt	draft	-	DOC-001-arc42 → documents DOC-11002-technical-debt → refines
DOC-11002-technical-debt	Document	Technical Debt	draft	refines → DOC-11000-risks-and-technical-debt	-
DOC-12000-glossary	Document	Glossary	draft	-	DOC-001-arc42 → documents DOC-12001-terms → refines
DOC-12001-terms	Document	Terms	draft	refines → DOC-12000-glossary	-
DOC-13000-appendix	Document	Appendix	draft	-	DOC-001-arc42 → documents
QS-001-reproducible-toolchain	QualityScenario	Reproducible Toolchain	proposed	refines → DOC-01001-quality-goals	ADR-001-containerized-docs-toolchain → addresses DOC-04001-strategy-overview → addresses DOC-06001-local-usage → addresses RISK-001-unpinned-package-versions → affects
QS-002-toolchain-availability	QualityScenario	Toolchain Availability	proposed	refines → DOC-01001-quality-goals	DOC-05001-level-1 → affects DOC-08003-testing → verifies
QS-003-publication-traceability	QualityScenario	Publication Traceability	proposed	refines → DOC-01001-quality-goals	ADR-002-ghcr-publication-tags → addresses DOC-06002-image-publication → addresses RISK-002-registry-publication-credentials → affects RISK-003-ambiguous-latest-tag → affects
RISK-001-unpinned-package-versions	Risk	Unpinned Package Versions	proposed	affects → QS-001-reproducible-toolchain	DOC-06003-failure-recovery → affects ADR-001-containerized-docs-toolchain → introduces_risk
RISK-002-registry-publication-credentials	Risk	Registry Publication Credentials	proposed	affects → QS-003-publication-traceability	DOC-08002-security → mitigates
RISK-003-ambiguous-latest-tag	Risk	Ambiguous Latest Tag	proposed	affects → QS-003-publication-traceability	ADR-002-ghcr-publication-tags → introduces_risk

Artifact ID

Type

Title

Status

Outgoing relations

Incoming relations

ADR-001-containerized-docs-toolchain

ADR

Containerized Docs Toolchain

proposed

addresses → QS-001-reproducible-toolchain
introduces_risk → RISK-001-unpinned-package-versions

DOC-02001-toolbox-constraints → constrains