---
name: ak-dev-sync-docs-from-branch
description: >
  Sync Agent Kernel documentation from branch changes before a feature or bugfix is merged.
  Use this skill when implementation is ready and you need to inspect new commits plus
  uncommitted changes, then update root docs, ak-py docs, deployment READMEs, example
  READMEs, and the docs website so the documentation matches the implemented behavior.
license: Apache-2.0
metadata:
  author: yaalalabs
  category: developer
---

# Sync Documentation From Branch Changes

Use this skill when a feature branch or bugfix branch is functionally ready and you need to align Agent Kernel documentation with what actually changed.

This skill is for **documentation maintenance driven by code diff**, not for implementing the feature itself.

## Goal

Read the branch delta, infer what user-facing and contributor-facing documentation changed, then update the relevant docs across the repository.

Required documentation surfaces covered by this skill:

1. `ak-py/README.md`
2. docs website content under `docs/` — update existing pages, add pages, remove obsolete pages, and adjust intro/getting-started/reference sections as needed, **including the React landing and features pages** (`docs/src/pages/index.tsx`, `docs/src/pages/features.tsx`) whose hard-coded inventories drift silently when only markdown is updated
3. README files under `ak-deployment/`
4. example README files when an example was added or changed, plus docs-site references to those examples
5. root `README.md`
6. root `DEVELOPER_GUIDE.md`

## When to Use This Skill

Use this skill when all of the following are true:

1. The developer is on a feature or bugfix branch.
2. The implementation is already done or nearly done.
3. There are new commits on the branch and/or uncommitted local changes.
4. The branch changes behavior, setup, APIs, integrations, deployment flows, examples, capabilities, or contributor workflows in ways documentation should reflect.

Do **not** use this skill as the first step of a feature. Use it near the end, before merge or PR finalization.

## Step 1: Determine the Comparison Base

Find the correct baseline branch first.

Preferred order:

1. The PR target branch if it is known.
2. The upstream tracking branch for the current branch.
3. `origin/develop`.
4. `develop`.

For this repository, prefer `origin/develop` or `develop` as the default base branch unless the PR target or upstream tracking branch says otherwise.

Use Git to identify the merge base between the current branch and that baseline.

Minimum evidence to gather:

- current branch name
- merge base commit
- commits since merge base
- staged changes
- unstaged changes

If the baseline is ambiguous, state the assumption you are using and continue.

## Step 2: Read the Branch Delta

Inspect both committed and uncommitted work.

Required diff inputs:

1. **Committed changes on the branch**
   - commits since merge base
   - file list and diff summary
2. **Current local changes**
   - staged diff
   - unstaged diff

Pay special attention to changes in:

- `ak-py/src/agentkernel/`
- `ak-py/README.md`
- `ak-deployment/`
- `examples/`
- `docs/`
- root `README.md`
- root `DEVELOPER_GUIDE.md`
- tests, examples, and Terraform modules that imply docs drift

## Step 3: Map Code Changes to Documentation Impact

Classify the branch delta into these buckets:

1. **Root-level product docs drift**
   - project overview, supported features, installation, quick start, contributor guidance
   - update `README.md` and `DEVELOPER_GUIDE.md` as needed

2. **Package-level docs drift**
   - Python package install, CLI, skills, APIs, framework support, configuration
   - update `ak-py/README.md`

3. **Docs website drift**
   - new capabilities, changed setup steps, outdated examples, missing pages, obsolete pages
   - update or add/remove pages under `docs/`

4. **Deployment docs drift**
   - Terraform modules, module inputs, deploy flows, packaging changes, environment setup
   - update relevant `ak-deployment/**/README.md` files

5. **Example docs drift**
   - example added, removed, renamed, or behavior changed
   - update example README files and docs-site references to those examples

## Step 4: Required Documentation Surfaces

You must evaluate all of these surfaces before deciding no documentation work is needed:

### Root Docs

- `README.md`
- `DEVELOPER_GUIDE.md`

### Package Docs

- `ak-py/README.md`

### Docs Website

- pages under `docs/docs/`
- related docs metadata such as sidebars or linked overview pages when needed
- intro/getting-started/reference/example pages that are affected by the branch change
- the What's New tip at the top of `docs/docs/intro.md` when the branch ships a headline capability
- the React landing and features pages (next subsection): these are not generated from markdown, so a new framework, integration, provider, transport, or capability is invisible there until its entry is added by hand

### Docs-Site Landing and Features Pages (React)

The landing page (`docs/src/pages/index.tsx`) and the features page (`docs/src/pages/features.tsx`) enumerate the product surface in hard-coded data, so a new framework, integration, provider, transport, or capability is invisible there until its entry is added by hand. On the landing page the inventories live in three component data files, not in `index.tsx` itself:

| Data file | What it drives | Entry shape |
|---|---|---|
| `docs/src/components/IntegrationsMarquee/data.tsx` (`INTEGRATION_ROWS`) | "Popular integrations": five scrolling rows, one tile per third-party integration | `{ name, role, href, logo or icon, mono?, wide?, soon?, title? }` placed in the matching row |
| `docs/src/components/ArchitectureOverview/data.tsx` (`SOURCES`, `DESTINATIONS`, `CORE_PILLS`, `FLOW_WORDS`) | the architecture diagram: summary cards of icon chips, four runtime pills, the flow line | a chip is `pick("<marquee tile name>")`; the name must match the marquee tile exactly or the static build fails |
| `docs/src/components/FeatureExplorer/data.tsx` (`FEATURE_TABS`) | the tabbed feature catalogue (Build, Connect, Remember, Guard, Scale, Observe) | a card has `title`, `description`, `tags`, `docs`, and an optional `example` folder under `examples/` |

`index.tsx` itself still holds the `WhatsNewBanner` text, the hero's Agent Skills block (the two install commands only; there is no per-skill list on the landing page any more), and the `clouds` list in `Deployment`. Read the current data before editing and confirm identifiers with `grep -n "const " docs/src/pages/index.tsx docs/src/components/*/data.tsx`.

| Branch changes ... | Marquee row and role | Architecture card | Feature card (tab) | `features.tsx` |
|---|---|---|---|---|
| A headline capability worth announcing | (none) | (none) | a card on the fitting tab | `FEATURE_PAGE_MAP` hint; a card in the `features` list under Core Capabilities when it is durable; plus `WhatsNewBanner` in `index.tsx` |
| A framework adapter | Agent frameworks & dev tools, `Framework` | Agent frameworks | Framework Adapters (Build): `tags` and `description` | `integrations`; the "Framework adapters for N SDKs" highlight on the Six Core Abstractions card |
| A messaging integration | Channels & protocols, `Channel` | Messaging channels | Messaging Channels (Connect): `tags` and `description` | `MESSAGING_PLATFORMS` |
| A protocol surface (MCP, A2A, AG-UI) | Channels & protocols, `Protocol` | Protocols & APIs | its own card under Connect | `protocols` |
| A session, thread, response, schedule, or attachment store backend | Memory, knowledge & data, `Memory` (list every store it backs in `title`) | Memory & knowledge | Pluggable Session Stores or Attachment Storage (Remember): `tags` | the "Backends: ..." highlight on the Smart Memory Management card |
| A knowledge base backend | Memory, knowledge & data, `Vector knowledge` / `Graph knowledge` / `SQL knowledge` | Memory & knowledge | Knowledge Bases (Remember): `tags` and `description` | the Knowledge Bases card description and highlights |
| A queue transport | Cloud & infrastructure, `Queue` | (none) | Queue Pipeline (Scale): `tags` and `description` | the "Queue broker over ..." highlight on the Sandboxed Code Execution card, the "Queue-backed scaling" highlight on the Multi-Cloud Deployment card |
| A sandbox provider or broker flavor | Cloud & infrastructure, `Sandbox` | (none) | Sandboxed Execution (Scale): `tags` and `description` | the sandbox entry hint in `FEATURE_PAGE_MAP` (provider count), the provider and broker highlights on the Sandboxed Code Execution card, `docs/src/components/SandboxFlowDiagram` |
| A deployment target or topology | Cloud & infrastructure, `Serverless` / `Containers` / `Gateway` | Clouds & observability | Multi-Cloud Deployment or Kubernetes Helm Chart (Scale) | the Multi-Cloud Deployment card highlights; plus `clouds` in `Deployment` in `index.tsx` |
| A schedule provider | Cloud & infrastructure, `Scheduler` | (none) | Scheduled Tasks (Scale): `tags` | (none) |
| A secret provider | Cloud & infrastructure, `Secrets` | (none) | Secret Resolution (Guard): `tags` and `description` | (none) |
| A guardrail provider | Observability, safety & testing, `Guardrail` | (none) | Content Guardrails (Guard): `tags` and `description` | the `with:` cells in the Problem section's `rows` that name the built-in guardrail providers |
| A tracing provider | Observability, safety & testing, `Tracing` | Clouds & observability (optional) | Tracing (Observe): `tags` and `description` | the Observability card highlights; the `with:` cells in the Problem section's `rows` |
| A test evaluator | Observability, safety & testing, `Evaluator` | (none) | Pluggable Evaluators (Observe): `tags` and `description` | `approaches` / `modes` under Testing & Evaluation |
| A bundled user skill (`ak-py/src/agentkernel/skills/`) | (none) | (none) | (none) | (none); only `docs/docs/agent-skills.md` lists individual skills |

Rules for these pages:

- Keep counts and names in sync with the code and with `docs/docs/` (a "six providers" hint or "4 SDKs" highlight goes stale the moment a backend is added).
- Every third-party integration (a vendor, a protocol, a managed service) gets a marquee tile; built-ins such as `in_memory`, `local_subprocess`, or `env` do not. `href` points at the docs page; a page that exists only in the unreleased docs takes the `/docs/next/...` path with a comment to drop `next` after the release.
- Logo, in this order: an existing asset under `docs/static/img/integrations/`; a Simple Icons glyph from `react-icons/si` (confirm the export exists, since Simple Icons has dropped the AWS, Microsoft, Slack, and OpenAI marks); otherwise the vendor's own SVG or PNG saved under `docs/static/img/integrations/`. Set `mono: true` for a black-on-transparent mark and `wide: true` for a wordmark.
- A marquee tile `name` is an identifier: `ArchitectureOverview` picks chips by it, so a rename there without the matching `pick()` change fails the static build.
- `FLOW_WORDS` in the architecture data and the `label`s in `FEATURE_TABS` are the same six words; change both or neither.
- Follow the existing entry shape exactly; do not restyle or restructure a section to add one entry.
- The other persona pages (`docs/src/pages/developer.tsx`, `ai-engineer.tsx`, `business-leader.tsx`, `use-cases.tsx`) carry their own feature groups; grep them for the old name or count whenever an inventory changes.
- Verify with the docs build, which also fails on broken internal links: `cd docs && npm ci && NODE_OPTIONS=--max-old-space-size=8192 npm run build`.

### Deployment Docs

- README files under `ak-deployment/`

### Example Docs

- `examples/**/README.md`
- docs-site pages that list, categorize, or link to examples

Do not update only one documentation surface if the same capability is described elsewhere in the repository.

## Step 5: Add, Update, or Remove Documentation

Apply these rules.

### Update Existing Docs When

- the capability already has a documented home
- the branch changes behavior, supported options, configuration, module inputs, examples, or terminology

### Add New Docs or Pages When

- the branch introduces a new reusable workflow, feature area, or example that does not fit cleanly into an existing page
- a new docs page is clearer than overloading an unrelated page

### Remove Docs or Pages When

- the capability or example is no longer supported
- the page is now misleading or fully replaced
- a replacement page or section exists in the same edit

Do not leave stale pages in place once the code path or example has been removed.

## Step 6: Documentation Authoring Rules

When writing or updating docs:

- ground every change in the branch diff and the current implementation
- prefer updating existing pages before creating parallel pages with overlapping scope
- keep terminology consistent with code, config keys, module inputs, and example names
- use current version numbers and current framework/integration names
- align docs examples with live code in `examples/` and `ak-deployment/`
- if an example changed, update both the example README and any docs-site references to it
- if setup steps changed, update both quick-start/getting-started material and deeper reference pages where relevant

## Step 7: Required Files to Consider

Depending on branch impact, review and update files from this list:

- `README.md`
- `DEVELOPER_GUIDE.md`
- `ak-py/README.md`
- `docs/docs/**`
- `docs/sidebars.js`
- `docs/src/pages/index.tsx`
- `docs/src/components/IntegrationsMarquee/data.tsx`, `docs/src/components/ArchitectureOverview/data.tsx`, `docs/src/components/FeatureExplorer/data.tsx` (the landing page inventories)
- `docs/src/pages/features.tsx`
- `docs/src/pages/developer.tsx`, `ai-engineer.tsx`, `business-leader.tsx`, `use-cases.tsx` (when an inventory or count they display changes)
- `ak-deployment/**/README.md`
- `examples/**/README.md`

Also update docs-site example index pages or overview pages when example inventory changes.

## Step 8: Validation Checklist

Before finishing, validate the documentation sync work.

Minimum validation:

1. Confirm the diff-backed rationale for each documentation update.
2. Verify changed docs still reflect the live code, examples, and module inputs.
3. Check edited markdown/JSON/JS files for diagnostics.
4. Search for stale names, old counts, removed examples, or outdated setup/version references introduced by the branch delta, including inside `docs/src/pages/*.tsx`.
5. Confirm example references in the docs site still point to examples that exist.
6. If a `.tsx` page was edited, confirm the docs site still builds (`cd docs && NODE_ENV=production NODE_OPTIONS=--max-old-space-size=6144 npm run build`; TypeScript is not installed in `docs/`, so the production build is the compile check, and `NODE_ENV=production` keeps the debug plugin out of the client bundle) and that every new `link` resolves to an existing `docs/docs/` page.

## Output Expectations

When using this skill, the coding agent should produce:

1. A short branch-impact summary based on commits plus uncommitted changes.
2. A documentation-impact summary by surface:
   - root docs
   - package docs
   - docs website
   - deployment READMEs
   - example READMEs
3. The actual file edits.
4. A validation summary.

## Common Pitfalls

- Updating code or examples without updating the matching README.
- Updating example READMEs but forgetting docs-site references to those examples.
- Updating docs website pages but leaving root or package README content stale.
- Describing behavior from memory instead of checking live code or Terraform inputs.
- Leaving outdated pages in place after capabilities or examples were removed.
- Changing example inventory without updating overview/index pages.
- Updating `docs/docs/` markdown for a new framework, integration, provider, transport, or capability but leaving the hard-coded lists in `docs/src/pages/index.tsx` and `docs/src/pages/features.tsx` (and the `intro.md` What's New tip) untouched, so the landing and features pages advertise a stale inventory.

## Quick Heuristic

Use this documentation-sync heuristic:

- **Behavior changed** → patch the docs where that behavior is already explained.
- **New workflow or example appeared** → add or expand docs in every location that should expose it.
- **Workflow or example disappeared** → remove or replace stale docs.
- **Only internal refactoring changed** → no docs change unless contributor guidance is affected.