Advantages:

Trade-offs:

The Publication Target Generator is a build-time component that reads article sidecar metadata and creates target-specific AsciiDoc inputs for public, preview, and private site builds.

It owns:

It does not own:

The public canonical-URL slice is authorized by accepted ADR-008 and may be implemented independently because it processes only already selected public output. Publication selection, preview/private targets, and promotion automation remain subject to ADR-009 and the still-missing first promotion check.

The Architecture Metamodel Validator checks architecture source artifacts before generated architecture fragments or rendered architecture pages are produced.

It owns:

It does not own:

The Profile Metamodel Validator checks profile content metadata before profile indexes, website artifacts, CV output, README output, or article exports are generated.

It owns:

It does not own:

The Architecture Artifact Generator derives navigation and traceability fragments from validated architecture metadata.

It owns:

It does not own:

The Profile Artifact Generator derives a profile artifact index from validated profile metadata.

It owns:

It does not own:

The Article Summary Generator creates paste-ready publication summary packs from source articles.

It owns:

It does not own:

In progress. The backlog epic is tracked as GitHub issue #26. The lifecycle is accepted in ADR-008. Public canonical metadata can proceed independently; private repository integration and promotion automation remain proposed in ADR-009, and no first promotion check has yet been performed.

The private site is a reading and review surface for the author. It is not a substitute for source privacy; private content remains in the private repository.

After promotion, preview content is public-source content. It is not official publication content, but it must no longer contain information that depends on private repository confidentiality.

Publishing is an explicit metadata transition. The public target must not include preview or private articles.

If an article is not ready to become public-source preview material, it stays private. No generated preview or public artifact is expected.

Proposed (derived).

Use AsciiDoc as the primary source format for profile and architecture content.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed (derived).

Use Gradle tasks as the local and CI build orchestration layer.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed (derived).

Use the docs-toolbox container as the reproducible CI runtime.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed (derived).

Use Pandoc via DocBook for README and article Markdown exports.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed (derived).

Keep the public website static and avoid unnecessary third-party runtime behavior. Optional integrations may use progressive enhancement when the core content and navigation work without them and the reader explicitly triggers any third-party request. The article-comments proof of concept follows this boundary: creating a comment navigates to a structured issue form in the dedicated dieterbaier/profile-artikelkommentare repository, while loading label-matched comment issues requires an explicit button click. This applies ADR-005 to feature #44.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed (derived).

Use a profile-specific metamodel, validator, and generator alongside the architecture metamodel.

This ADR was derived while bootstrapping the existing project to the architecture-knowledge-toolkit structure. The decision reflects existing repository practice and should be reviewed before being marked accepted.

Proposed.

This ADR is AI-assisted and must not be treated as accepted architecture truth until reviewed and accepted by the accountable owner.

We propose to generate file-based article summaries as HTML build artifacts under build/summaries. Each summary filename uses the article filename stem plus summary<target> and the .html extension.

These summaries are generated writing aids. They are excluded from generated site and article-export targets, and generated public content must not link to them.

For example:

The project already treats profile article sources under src-content/profile/site/articles as product source. AI-assisted article summaries are paste-ready publication aids for LinkedIn and Substack.

An earlier proposal placed written summaries next to the article source. The current desired practice is different: summaries are generated whenever they are requested and written to build/summaries.

This keeps authored article sources clean, makes the workflow reproducible through Gradle, and avoids treating publication drafts as primary source.

Confirm that generated summaries should stay build artifacts before changing this ADR to accepted or reviewed.

Accepted.

The Basic Auth requirement this record states for the preview target is replaced by ADR-011. Everything else here stands, including Basic Auth for the private target.

We separate article privacy from article publication quality by combining repository boundaries with metadata-driven build targets.

Private drafts, notes, and protocols start in the private repository dieterbaier/profile-private. Reviewable but not official article content is promoted to the public profile repository with status: preview. Public deployment uses only metadata-selected status: published article content and derives canonical links from a deployment-specific base URL plus each generated output path. Preview and private deployments render their own target-specific sites without canonical links, with noindex metadata, and behind Basic Auth.

The profile repository is public. Deployment protection such as .htaccess can protect generated HTML on a webspace, but it cannot protect source files that are already public in Git. Therefore, the privacy boundary must exist at source level before generated deployment targets are considered.

At the same time, not every unfinished article is confidential. After an article is cleaned enough for feedback, public source visibility is acceptable, while public website visibility and search indexing are still not desired.

This decision supports the lifecycle tracked as GitHub issue #26.

The following diagrams document the decision basis for the lifecycle. While this ADR is proposed, they remain close to the options and consequences. Official architecture views include these diagrams by tag so that the accepted decision can be reused without duplicating the model.

Positive:

Negative:

Neutral or follow-up:

Confirmed on 2026-07-18:

Open follow-up:

Accepted by the site owner.

We treat profile-private (dieterbaier/profile-private) as a separate source component of the same profile application, integrated through explicit content and promotion contracts instead of Git submodules or duplicated build logic.

The two repositories are checked out as siblings. The private build reaches the shared tooling through that sibling checkout and owns no copy of it. Private rendering and verification run locally; the private target needs no GitHub Actions deployment.

Promotion moves an article from the private repository to the public one rather than copying it, so that an article has exactly one authoritative source and no second place to edit it.

Move is the outcome, not a property of the operation. Two repositories cannot be written atomically: the promotion is a saga with an ordering, states it can stop in, and a recovery step. The Promotion Saga section below defines them.

The public repository remains the owner of shared build logic, validators, generators, theme assets, profile metadata contracts, and architecture documentation. The private repository owns private article, note, and protocol source content. Private content is rendered by reusing the public repository’s build tooling through a documented checkout or local path contract.

The private repository should not maintain separate architecture documentation unless it introduces architecture decisions that are not part of the overall profile application. It may contain local operational notes, but architecture truth stays in this repository.

The private repository is not just backup storage. It is part of the profile publishing system because it contributes source content to the private site and can promote reviewable articles to the public repository. At the same time, its main architectural reason to exist is privacy: content that must not be public source cannot live in the public repository.

Git submodules could express a repository relationship directly, but they introduce extra workflow complexity, detached version management, and contributor friction. Treating the private repository as a completely independent product would keep boundaries simple, but it would likely duplicate generators, validation rules, theme assets, and deployment behavior.

This decision supports GitHub issue #26 and must be reviewed before implementation slices that create private repository automation.

The component model below documents the preferred repository integration option. The official building block view includes it by tag while the decision is still proposed, so later refinements can happen once at the decision source.

Two Git repositories cannot be written in one transaction. Promotion therefore has a defined order, and every point it can stop at is a state someone has to be able to recognize and finish.

The public repository leads. From the moment the promoted article lands there, it is the authoritative copy. Everything after that point is cleanup of the private side, never a source of truth.

The order follows from which failure is survivable. Removing from private first would put the article nowhere if the public write then fails. Writing to public first can only ever produce a duplicate, and a duplicate is recoverable while a loss is not.

The incomplete state is duplication, and it is detectable. The same artifact id present in both repositories is the signal a resumed promotion looks for, which is why artifact IDs are stable and unique across the contract rather than per repository.

The signal is not conclusive on its own. A shared id can also mean a genuine collision — two different articles that ended up with the same identifier — and a resumption that trusted the id alone would overwrite public content with private content. Recognizing an interrupted promotion therefore means matching the public artifact against the private one being promoted, not matching identifiers. The three states a public id can represent, and their opposite responses, are specified in GitHub issue #85.

A promoted article is never rolled back by moving it home. If the article should not have been promoted, it is removed from the public repository like any other public content, and the public Git history keeps the record. Promotion is not reversible by re-running it backwards, because public history cannot be unpublished.

Two rules carry the drift concern, and they divide the failure between them.

The no second implementation rule removes drift in the tooling rather than detecting it. A vendored copy keeps looking like the original after it has stopped being one, which is the property that made the divergence in metamodel/artifact.schema.yaml invisible; a repository that holds no copy cannot diverge in one.

The contract version rule covers what remains: a sibling checkout that is simply older than the content beside it. Enforcing metadata_version makes a stale contract fail with a name attached, and makes raising the version the deliberate act it should be when the contract changes.

The rule needs one place where the accepted versions are declared, and it is the metadata_version enum in metamodel/profile-artifact.schema.yaml. The validator reads it from there rather than carrying a second list, and reads it from its own checkout rather than from the tree it was pointed at, so a run against private content answers with the contract of the tooling doing the validating. A build that borrows this repository as its metamodel can read the same file to report what its checkout accepts.

Absence is not read as the initial version. An artifact that declares no metadata_version fails as a missing field, because a default would let content say nothing about its contract and still pass — and a checkout older than that content would then accept it silently, which is the mismatch this rule exists to catch.

Neither rule catches a contract change nobody versioned. That is a discipline gap rather than a mechanism gap, and no inexpensive check closes it.

The decision holds; the rules it accepts are at different stages, and this section says which is which so the documentation does not claim protection that does not exist yet.

metadata_version is required on every artifact, and the validator rejects a version outside the accepted set by name. Both drift rules are in force, and the private build applies them: buildSitePrivate validates the private content root with this repository’s validator before rendering it, and reads the accepted versions from this checkout rather than from the tree beside the content.

What the private build does not yet do is run the generators against the private tree, so a private page carries no tags, no article navigation, and no series links. The generators write link registries into the includes tree, which for the private target is this repository’s — a generator run would write into the public checkout while rendering private content. That is a real coupling and not a detail of wiring, so it is left to a slice of its own rather than solved in passing.

This was the gate on private-source work. No slice that reads private source or promotes an article was to run before the accepted-version check existed, because a promotion validated against an unenforced contract is the exact failure this decision claims to prevent. #83 closed that gate; the remaining private slices are ordered by their own dependencies.

Positive:

Negative:

Neutral or follow-up:

The site owner confirmed the four open points at acceptance:

The same review corrected promotion from a copy to a move.

A second review round sharpened two claims this record had overstated. A cross-repository move is not atomic, so the promotion is described as a saga with a leading repository, an order, its stop states, and their recovery. The metadata_version protection is decided but not yet built, so the Implementation Status section separates what holds from what runs.

Accepted.

The decision was drafted AI-assisted, then reviewed and accepted by the accountable owner with all open questions decided and all traceability relations confirmed.

The site becomes multilingual with de as the default language, and every language-dependent reference is resolved at build time in the profile artifact generator rather than in AsciiDoc markup or at page runtime.

Four resolution classes are distinguished, because they need different fallback semantics:

Fallback and hard failure are therefore deliberately split along the line of what a reader can make sense of. A link that leads to a German page is usable, so it falls back and says so. A German paragraph inside an English article is not, so it fails the build instead of producing a page in mixed languages.

Every language variant of an artifact is a profile artifact in its own right, with its own stable ID, its own sidecar metadata, and its own comment thread.

Default language and original language are deliberately separate concepts. de is the default language, which means it is the fallback target when a translation is missing. The original is the variant an artifact was authored in first, which may be any language. An article written in English and translated into German afterwards is therefore an English original with a German translation, while German remains the site’s fallback language.

The site currently exists in German only. src-content/profile/includes/docheader.adoc already defaults :lang: to de, and article sources already use en for external links, so the language attribute exists but carries no structural meaning. All chrome is hard-coded German: menue.adoc contains German labels and hard-coded relative page paths, docheader.adoc sets :toc-title: Inhalt, includes/docinfo/docinfo-footer.html links to {basedir}/legal.html, and src-content/theme/article-comments.js carries German status strings.

The authoring concept relies on reusable includes. Writing an article in another language therefore does not only mean translating the article body; the surrounding generated chrome must switch language as well, and the references inside it must point at same-language pages where those exist.

The core constraint is that AsciiDoc has no file-existence conditional. ifdef and ifeval evaluate attributes only, and opts=optional expresses "include or skip", not "include A, otherwise B". A language-aware include or xref cannot be expressed in portable AsciiDoc markup. Only the build knows which language variants exist, and the profile artifact generator (scripts/validate-profile-metamodel.rb) already owns exactly that knowledge: it reads every .profile.yaml, and it already writes per-article navigation, tag, and comment includes plus the article listings.

The comment integration adds a second constraint. Comment threads are keyed by article ID, and generateProfileArtifacts synchronizes an allowlist of published article IDs to the comments repository. Any language model that does not produce a stable ID per language variant would break that contract.

Option 2 loses mainly on tooling: a custom include processor is invisible to the IntelliJ AsciiDoc preview, which breaks the authoring loop for the person who writes the content. Option 3 contradicts ADR-005: Minimal Static Site. Option 4 pushes drift detection to the reader.

None. The questions raised while drafting this ADR were decided by the accountable owner and folded into the language contract above: outdated translations stay publishable with a visible note, the digest covers the full article source, freshness and divergence notes may appear together, the author can override the derived freshness state, and the language switcher appears whenever an artifact exists in more than one language.

Reviewed and accepted by the accountable owner. The following were confirmed during review:

Implementation is tracked in GitHub issue #47 and its slices.

Accepted by the site owner.

The site owner decides that preview.dieterbaier.eu serves the preview target without authentication. Preview pages carry noindex metadata and no canonical link, and every article whose status is not published carries a visible notice saying that it is not finished.

The public site never links to the preview target. No page, listing, navigation entry, related-article suggestion, or link registry entry generated into dieterbaier.eu points at preview.dieterbaier.eu. A preview URL is something a reviewer is handed, not something a reader can arrive at.

Basic Auth stays on the private target, where it protects content whose source is not public.

ADR-008 remains accepted. Three statements in it are replaced by this record:

ADR-008’s own publication target deployment diagram already shows the preview target as noindex, no canonical with no Basic Auth, and names Basic Auth on the private target only. The diagram agrees with this record; the prose did not.

Everything else in ADR-008 stands, including the repository boundary, the metadata-driven targets, and Basic Auth for the private target.

The preview target is built from the public repository. An article reaches it by being promoted into public source, which means its text is already readable in Git by anyone before any page is deployed. Authentication in front of the rendered pages therefore guards a copy of something already published in another form.

What the preview target does need is that its pages are not mistaken for finished work: not indexed, not canonical, and not read as a statement the author stands behind. The first two are technical and invisible to a reader. The third is what a password was standing in for, badly — a credential prompt says "you may not read this", which is not the message, and once a reviewer has the credential the prompt says nothing at all.

Reachability is a separate question from indexing. noindex keeps a preview page out of search results; a link from the public site would put it in front of readers who never searched for it, and would make an unfinished article part of the site’s navigable surface. The two rules cover the two ways a reader arrives.

The private target is a different case and keeps its access boundary. Its source is not public, so the deployment is the only place its content could leak.

Basic Auth ties the chosen option on exactly one criterion — keeping the page out of search results — and noindex achieves that without it. On the other five it loses. It costs credential handling, rotation, and a handshake with every reviewer, and it buys protection for content that is public in source. It also misleads: a reader who gets past it reasonably concludes the page was worth protecting.

Unguessable URLs lose for the same reason without the operational cost. Obscurity that is described as protection is the more dangerous of the two, because nothing about it fails visibly.

Positive:

Negative:

Neutral or follow-up:

The site owner raised the contradiction, confirmed that the deployment diagram and not the prose states the intent, and answered both open points at acceptance:

The decision holds; the mechanisms that carry it are at different stages.

Until the notice exists, a preview page carries no reader-facing signal at all. The preview deployment therefore waits for #88: the decision removes an access boundary and puts the notice in its place, so deploying the one without the other would leave an unfinished article publicly readable with nothing saying so. This is a blocking dependency of #79, recorded there and in the epic rather than only here.

Accepted by the site owner on 2026-08-04, after the first private render in GitHub issue #86 raised the question.

The private target is rendered from the private content root alone, with this repository’s theme, includes, and page chrome. A draft is read as a styled page, and links that leave it — start page, CV, legal notice, article listings — do not resolve, because their targets are not in this repository.

That is accepted rather than worked around. If it turns out to obstruct reading, this record is superseded rather than amended.

Two rules come with it:

ADR-009 gives the private repository content and nothing else. The first private render therefore produced what the private repository contains: three article pages and the theme, with no site around them. Every link in the page chrome points at a file that is not in the target.

The target exists so a draft can be read as a finished page before anything is decided about it. The open question was whether "as a finished page" requires the finished site around it.

The preview target does not have this problem, and stating that here keeps it from being solved twice. Promotion moves an article into the public repository and sets status: preview there. build/site-preview is built from public source only, as #78 specifies, so it already contains the whole public site plus the preview articles. Only the private target reads from a tree that holds articles alone.

Private content only is what #86 built and what this record accepts. It is the cheapest and the most predictable, and its output is plainly not a site.

Compose public site and private content renders both trees into one target. It scores one point higher, and the point it wins is the reading context.

Generated minimal shell would produce just enough index and menu targets for the links to resolve. It invents a structure that matches no real site, so a draft would be read inside a fourth thing that exists only in this target.

Read only after promotion to preview removes the private reading target entirely. It scores well until the criterion that matters: the article would be publicly reachable — ADR-011 removed the access boundary in front of preview — before its author had read it as a page once.

The chosen option is not the highest-scoring one, and the difference is a single point on seven criteria. The owner weighed the two criteria that separate them — reading context against cost and predictability — and judged the broken chrome tolerable for a target read by the person who wrote its content and knows why the links fail.

The matrix is kept as it was scored rather than re-weighted to agree with the outcome. A matrix adjusted until it produces the decision already made records nothing.

The site owner accepted the decision and answered all three open questions:

Positive:

Negative:

The decision holds; the rules it accepts are at different stages.

Until #94 closes, a private draft can carry an artifact id or an output path that a public artifact already uses, and nothing says so until the article is promoted. Until #95 closes, no check stops a workflow edit from pointing the public deployment at a non-public target.

Because content and metadata evolve separately, generated indexes may become incomplete, leading to misleading public artifacts.

Because local and CI tool versions may diverge, builds may become non-reproducible, leading to deployment failures.

Because CV builds can inject private contact data, secrets may be exposed if environment handling is wrong.

Because private drafts and public preview content are promoted across repository boundaries, private-only source material may be copied into the public repository, leading to irreversible disclosure through public Git history.

Because public, preview, and private builds share article sources and build tooling, preview articles may be included in the public website or indexed by search engines, leading to premature or misleading publication.

Status: open.

The bootstrap derives a profile metamodel from the existing content and the architecture-knowledge-toolkit pattern. A human review should confirm artifact types, required fields, and whether further profile fragments need first-class metadata.

Status: open.

AI-generated article publication packs must not invent URLs. Missing canonical URLs remain placeholders until supplied.

Status: open.

Current assumption: The profile project should remain a concrete running example, not a second copy of the organization positioning. It should show that profile content and architecture metadata are authoritative source knowledge, while generated website, README, CV, article, and architecture outputs are derived publication artifacts. docs-toolbox is the reproducible rendering runtime; docToolchain or similar tools could be combined with the same source model in other projects.