[oto-macenauer-absa]

Turns this repository into the Knowledge Base user guide while keeping it the docs template other teams copy. The guide itself is the working example of the template. A GitHub Agentic Workflow (gh-aw, Copilot engine) maps the features of a knowledge-base release and opens one draft PR that brings the guide up to date.

Docs structure

• docs/index.md is now the Knowledge Base overview.
• The template pages (template.md, previously index.md; customising.md, adding-pages.md, publishing.md) move into a Docs Template section (order 100+).
• Product pages will live in docs/kb/ under the sections Knowledge Base, Publish Your Docs, Run a Knowledge Base, Embed in a Host App and Reference. The first full run creates them.
• mkdocs.yml site_name is now "Knowledge Base User Guide".

Feature map: .kb-sync/features.yml

• Maps about 30 knowledge-base features (v1.3.1) to their upstream source files (most authoritative first) and the guide page that documents each one.
• Has an ignore list for upstream paths that are not user-facing.
• Records synced.tag / synced.sha. It is empty now, so the first run is a full one.

Workflow: .github/workflows/sync-kb-docs.md

Triggers

• workflow_dispatch with an optional tag (empty means the latest release) and a mode.
• repository_dispatch kb-release, which knowledge-base can send after a release.

Modes

• incremental diffs synced.sha..target, maps the changed paths to features and documents any unmapped user-facing path as a new feature.
• full re-maps everything.
• audit changes no files and opens one issue listing the drift.

What the agent does

• Documents only released vX.Y.Z tags. It ignores floating v1 and unreleased commits.
• Resolves conflicts between sources in this order: contract, then action.yml / workflow inputs, then code, then prose. Every key, input, env var, route and rule ID it writes has to exist at the target tag.
• Lists any upstream prose-vs-code disagreements in the PR.
• Rewrites data/showcase.yml so the Knowledge Base is the product and the Docs Template is one of its features. This happens in full mode, or in incremental mode when a headline feature changes.
• Keeps docs/kb/changelog.md and the feature map up to date.

Safeguards

• The agent treats the upstream checkout as read-only and never executes code from it.
• It never edits .github/, theme/ or scripts/.
• Output is a single draft PR ([kb-docs] prefix), or one issue in audit mode.
• It verifies with python scripts/pack.py --headless.

sync-kb-docs.lock.yml is generated by gh aw compile; edit the .md and recompile. The compiler still shows one warning, privileged-checkout, which is accepted: only users with write access can trigger the workflow, and upstream code is never executed.

Setup required

• Repository secret COPILOT_GITHUB_TOKEN: a fine-grained PAT with Copilot Requests: Read. Inference is billed to the PAT owner's Copilot plan.
• After merging, run Actions → sync-kb-docs → mode: full to generate the guide for v1.3.1.
• Optional follow-up in knowledge-base: dispatch kb-release with client_payload.tag after each release.
• Draft PRs opened by the workflow do not trigger check-docs.yml; close and reopen them to run the check.

Release Notes

• The site is now the Knowledge Base user guide; the template documentation moved to a "Docs Template" section.
• Added the sync-kb-docs agentic workflow, which documents each knowledge-base release (incremental, full or audit mode) through a draft PR.
• Added .kb-sync/features.yml, which maps knowledge-base features to guide pages and records the last documented release.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The workflow instructions leave generated PRs without an explicit contract-check gate and block builder compatibility updates needed for contract-major version bumps.

2 open issues

• Allow contract-major version bumps in both builders · New
• Require checker validation before merging generated PRs · New

What changed in this PR

Adds a Copilot-powered workflow to keep this MkDocs documentation template aligned with knowledge-base releases by proposing updates in a draft PR.

Changes:

• Supports release notifications and manual runs against a supplied upstream tag.
• Defines upstream comparison, scoped updates, headless build verification, and draft PR creation.
• Adds the compiled workflow and action pin metadata, while ignoring the upstream checkout and marking generated workflow files.

File	Description
.gitignore	Ignores the workflow’s .kb-upstream/ checkout.
.github/​workflows/​sync-kb-docs.md	Defines triggers, agent permissions, synchronization instructions, and PR output.
.github/​workflows/​sync-kb-docs.lock.yml	Provides the compiled workflow for execution in GitHub Actions.
.github/​aw/​actions-lock.json	Records the pinned agentic-workflow setup action.
.gitattributes	Marks compiled workflow files as generated.

_{Review effort: Balanced}