AkurAI-Framework / AGENTS_DOCS.md

Latest change 4ed55d17e0979479dc70291811217113b6062fa0 - docs: split AGENTS.md into domain-indexed subfiles + add breaking-changes guide by Ólafur Búi Ólafsson

# AGENTS_DOCS.md — documentation conventions

> Docs are first-class (constitutional principle #10) and breaking changes are
> never silent (#12). This file is the contract for the docs site, the
> dual-changelog policy, and the breaking-changes policy.

## Docs ship with the feature (principle #10)

The framework maintains a `/docs` site in a Next.js/Vue-style layout (sidebar
nav, sectioned guides + API reference), served by the framework itself from
`site/`. **Every new crate or feature ships its docs in the same change:**

1. A Markdown page at `site/content/docs/<feature>.md` (rendered by
   `crates/markdown`, including the live `preview` fence —
   [`AGENTS_FRONTEND.md`](./AGENTS_FRONTEND.md)).
2. A `docs_nav` entry in `site/backend/page.json` linking to it, in the right
   section (`Guide` / `Building` / `Design system` / `Reference`).

Both land together — a feature without its doc page + nav entry is incomplete.
House voice: lead with what matters, be honest about status (✅ shipped · 🟡
partial · ⬜ planned), no fluff.

> **Integration boundary:** worktree agents **write the doc page**
> (`site/content/docs/<feature>.md`) but do **not** edit `site/backend/page.json`
> — the orchestrator wires `docs_nav` (and `routes.json`) at integration time so
> parallel agents don't collide on shared nav files. See the forbidden list
> below.

## Changelog policy — two files, always together

**Every feature ships its changelog entry in the same commit**, in **both**
changelogs, kept under their "Unreleased" heading:

- `CHANGELOG.md` — developer-facing, detailed; under `## [Unreleased]`
  (Keep-a-Changelog dialect).
- `site/content/changelog.md` — visitor-facing, curated; under `## Unreleased`.

`deploy.sh` cuts both `Unreleased` sections into a dated, versioned release in
**lockstep** at release time (see [`AGENTS_DEPLOY.md`](./AGENTS_DEPLOY.md)), so the
live `/changelog` always reflects the version just shipped. An optional,
**non-blocking** `pre-commit` hook nudges you when a commit touches `crates/**`
or `site/frontend/**` without staging `CHANGELOG.md` — it only warns (always
exits 0), so docs-only / refactor / WIP commits are never blocked. Enable it once
per clone:

```
git config core.hooksPath scripts/hooks
```

## Breaking-changes policy (principle #12)

The project is **pre-1.0**, so a minor version may include breaking changes. None
is allowed to be silent. **Every breaking change gets, in the same change:**

1. A `### Breaking` entry in **both** changelogs (`CHANGELOG.md` and
   `site/content/changelog.md`) for that version, alongside the normal
   Added/Changed/Fixed entries.
2. A migration note appended to `site/content/docs/breaking-changes.md` — the
   user-facing breaking-changes & migration guide, reverse-chronological by
   version, each entry stating **what changed, why, and the before→after
   migration steps**.

Post-1.0 the project switches to strict semver (breaking changes only in major
versions). Until then, `breaking-changes.md` is the single place a user checks
before upgrading.

## Forbidden for worktree agents (orchestrator owns these)

To keep parallel agents from colliding on shared integration files, **do not
edit** the following — the orchestrator wires them post-merge:

- `site/backend/page.json` (docs nav, site config) and `backend/routes.json`.
- `CHANGELOG.md` and `site/content/changelog.md` — you only **document** the
  policy here; the orchestrator stages the actual entries at integration.
- `site/content/docs/roadmap.md` — the orchestrator's mirror of
  [`BATCHES.md`](./BATCHES.md).

Agents **do** write their own feature doc pages under `site/content/docs/` and,
when a change is breaking, the migration note in
`site/content/docs/breaking-changes.md`.