docs(style-guide): align the guide with the shipped sections and settle its open rules

.github/CONTRIBUTING.md

@@ -36,7 +36,7 @@ pnpm build:local     # build + frontmatter validation (CI runs this too)
 pnpm lint:slugcheck  # permalink rules
 ```
 
-- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it under **URL changes and redirects** in the PR description.
+- Changed a permalink or moved a page? **Add the redirect in this PR**, in the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`, and list it on the redirect row of the PR checklist.
 - Can't update `pt-br` yourself? Create the follow-up `i18n` issue and link it in the PR checklist.
 
 ## The PR

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,15 +1,26 @@
-## Summary
+## What & why
 
-<!-- 1–3 bullets: what changed and why. Don't restate the diff. -->
+**Related issue:** <!-- EDU-1234 / #123 / none — the ticket lives here and in the branch name, never in the title -->
+**Pages affected:** <!-- permalinks or file paths -->
 
-## How to test
+<!-- What changed and why, then how you checked it. Don't restate the diff. -->
 
-<!-- Numbered, concrete steps to verify THIS PR: the command to run (pnpm dev / pnpm build:local), the page or permalink to open, and the expected result. -->
+## Type of change
 
-## URL changes and redirects
+- [ ] 🆕 New content (`feat`)
+- [ ] 🩹 Fix (`fix`) — typo, broken link, wrong information
+- [ ] ♻️ Content update (`docs`) — rewrite, expansion, upkeep
+- [ ] 🌐 Translation sync (`i18n`)
+- [ ] 🏗️ Platform / structure (`refactor` / `chore`) — reviewed by UXE, no content mixed in
 
-<!-- Every permalink this PR changes or removes, one per line: old URL -> new URL. Then the redirect entries you added, with the file each one is in (apps/docs/redirects/en/*.json or apps/docs/redirects/pt-br/*.json). Write "None" when no URL changes. -->
+## Author checklist
 
-## Notes
-
-<!-- Breaking change (what + migration), i18n follow-up, new dependency, related issue. Write "None" when there is nothing. -->
+- [ ] PR title follows `type(scope): summary` (see [GOVERNANCE.md §4](GOVERNANCE.md))
+- [ ] Frontmatter complete: `title`, `description`, `meta_tags`, `namespace`, `permalink`, `last_reviewed`
+- [ ] No legacy "edge-" product names in the copy
+- [ ] How-to/tutorial content includes at least one runnable, copy-paste-tested code block
+- [ ] Screenshots (if any) have alt text and follow image standards
+- [ ] Internal links are relative and resolve locally
+- [ ] **If any permalink changed or page moved: redirect added in this PR** <!-- every permalink changed or removed, old URL -> new URL, one per line, and the file each redirect entry is in (apps/docs/redirects/en/*.json or apps/docs/redirects/pt-br/*.json) -->
+- [ ] **i18n:** `pt-br` updated in this PR **or** follow-up `i18n` issue created: <!-- link -->
+- [ ] I ran `pnpm build:local` (build + frontmatter check) without errors

.gitignore

@@ -62,4 +62,7 @@ reports/
 
 .working-files/*
 
+# A pull request description an agent drafts for the person who opens the PR (see AGENTS.md).
+/pr.md
+
 apps/docs/src/consts.ts

AGENTS.md

@@ -25,7 +25,7 @@ preferences.
 | `apps/docs/src/content/docs/en` · `.../pt-br` | every published page, as `.mdx` |
 | `apps/docs/src/nav` | the navigation trees that build the sidebars |
 | `apps/docs/src/pages` | routes, including the `.md` twins, `llms.txt`, and the sitemaps |
-| `apps/redirects-massive/src/redirects/{en,pt-br}/doc.json` | the redirect map |
+| `apps/docs/redirects/{en,pt-br}/*.json` | the redirect map, in numbered files |
 | `.claude/rules/webkit-*.md` · `CLAUDE.md` | the design system rules, for UI work only |
 
 ## Writing or changing a page
@@ -36,8 +36,8 @@ preferences.
   requires `description`, `meta_tags`, `namespace`, and `permalink`, and reviewers hold you to
   it. `namespace` pairs a page with its translation, so the two language versions share one.
 - **Changing a `permalink` or moving a page requires a redirect in the same pull request**, in
-  `apps/redirects-massive/src/redirects/{en,pt-br}/doc.json`. A permalink change without one is
-  a broken build.
+  the highest-numbered file of `apps/docs/redirects/{en,pt-br}/`. A permalink change without one
+  is a broken build.
 - **Register a new page in a navigation tree** under `apps/docs/src/nav`, or nothing links to it
   and it reaches no index.
 - **Internal links are root-relative** (`/en/documentation/...`) and must resolve.
@@ -71,10 +71,30 @@ Run a script of another app with `pnpm -F <app> <script>`, for example
   corrections, `docs` upkeep, `i18n` translation, `refactor`/`chore` structure and tooling.
 - One concern per pull request. Content changes and platform or code changes never travel
   together.
-- Fill the pull request template; its checklists are the review contract.
 - Two people sign off: a subject matter expert for accuracy, a DevRel maintainer for writing
   and placement.
 
+### The description
+
+Write the description in the format of
+[`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md), the same body GitHub
+prefills for people. Its checklists are the review contract.
+
+- **Three sections, in order:** What & why, Type of change, Author checklist. Add no other
+  top-level section.
+- **What & why** opens with the **Related issue** and **Pages affected** lines. Then say what
+  changed and why, grouped by topic rather than by file, and how you checked it: which commands
+  ran, which pages you opened, and what you could not verify.
+- **Keep every checklist row verbatim.** Never drop, reword, shorten, or reorder a row. Tick a
+  row only when it is true. When a row is not true, leave it unticked and say why after a dash
+  on the same line. When it does not apply, tick it and say so the same way:
+  `— no screenshot is added or changed`.
+- **Leave the `pnpm build:local` row unticked unless you ran it** and it passed.
+- **When you do not open the pull request yourself, write it to `pr.md`** at the repository
+  root, which git ignores. The file starts with the title line,
+  ``**Title:** `type(scope): summary` ``, followed by the template's three sections, so the
+  person opening the pull request pastes it as it is.
+
 ## Building UI
 
 Components come from the `@aziontech/webkit` design system, and that work has its own

CLAUDE.md

@@ -1,3 +1,9 @@
+## Repository rules
+
+The rules for every agent in this repository, including the pull request description format,
+are in AGENTS.md:
+
+@AGENTS.md
 
 <!-- @aziontech/webkit -->
 ## @aziontech/webkit design system

apps/docs/src/content/docs/en/pages/style-guide/components.mdx

@@ -257,7 +257,7 @@ One dated entry: label and version on the left, the notes on the right, with an
 ```mdx
 import DocUpdate from '@aziontech/webkit/doc-update'
 
-<DocUpdate label="July 10, 2026" description="Bot Manager 1.3.0" tags={['Marketplace']}>
+<DocUpdate label="July 10, 2026" description="Version 1.3.0" tags={['Marketplace']}>
 
 **Bot Manager** now ships nine new static rules and two new arguments.
 
@@ -344,7 +344,7 @@ import ProductGuidesSection from '~/components/ProductGuidesSection.astro'
 - `product` — the section's id, such as `applications`. The table lists every guide the guides catalog tags with the section or with a Product nested in it.
 - The date is the page's last change, filled in for you. Never write it by hand.
 - The type column shows each page's content type, in the reader's language.
-- Rows sort by title.
+- Rows sort alphabetically by each page's navigation label, in the reader's language, never by date. The name column shows that label, not the page title.
 
 ---
 

apps/docs/src/content/docs/en/pages/style-guide/content/changelog.mdx

@@ -37,7 +37,7 @@ Each entry is one `DocUpdate`: the date, the version, and the Platform Resource
 **Required components**
 
 - **A `DocUpdate` entry**, newest first. `label` is the date, `<Month> <day>, <year>`: dates are allowed in changelogs and only in changelogs. `anchor` is the date as a slug, `july-10-2026`.
-- **The opening sentence**: `**<Platform Resource>** now <verb>s <what it now does>.`, plus the concrete detail: the flag, the field, or the default.
+- **The opening sentence**: `**<Platform Resource>** now <verb>s <what it now does>.`, plus the concrete detail: the flag, the field, or the default. When the change belongs to a Product nested in the Platform Resource, the Product is the subject.
 - **What it means concretely**: what works without configuration now, or what behaves differently.
 - **Who is not affected**: existing configurations, earlier versions, accounts that did not opt in.
 - **The closing link**: `For more information, refer to [<the documenting page>](/en/documentation/.../).`
@@ -70,7 +70,7 @@ For more information, refer to [<the documenting page>](/en/documentation/.../).
 
 ## Rules
 
-- **Open with the Platform Resource as the subject.** `**<Platform Resource>** now <verb>s <what it now does>.` Present tense, never `we`, never `Azion is excited to`.
+- **Open with the element that changed as the subject.** `**<Platform Resource>** now <verb>s <what it now does>.` A change to a Product nested in the Platform Resource opens with the Product: `**Bot Manager** now…`. Present tense, never `we`, never `Azion is excited to`.
 - **State who is not affected.** A reader's first question about any change is whether it breaks them; answer it before they ask.
 - **Show migration or opt-in steps when the surface changed.** An API, CLI, or configuration change gets a code sample; two lines is enough.
 - **Close every entry with the documentation link.** An entry that documents the feature in full is a page filed in the wrong place.

apps/docs/src/content/docs/en/pages/style-guide/content/choose-a-content-type.mdx

@@ -41,7 +41,7 @@ A page kind is a base form plus a place in the [information architecture](/en/do
 | [Glossary](/en/documentation/style-guide/content/glossary/) | Reference | Yes | Define the terms the section's documentation uses, in a filterable table |
 | [Navigation hub](/en/documentation/style-guide/content/navigation-hubs/) | None | No | Direct readers deeper. Links plus one sentence of orientation |
 
-Required per section means required in every Platform Resource section. A Product nested as a dropdown in a Platform Resource needs only its reference pages, plus a Quickstart when it has a setup of its own; every other page it would have is a section of the resource's pages. The nesting rule is in [Information architecture](/en/documentation/style-guide/content/information-architecture/#nested-products).
+Required per section means required in every Platform Resource section. A Product nested as a dropdown in a Platform Resource needs only its reference pages, plus a mechanism page when it has a mechanism to explain and a Quickstart when it has a setup of its own; every other page it would have is a section of the resource's pages. The nesting rule is in [Information architecture](/en/documentation/style-guide/content/information-architecture/#nested-products).
 
 ## Slots are not kinds
 

apps/docs/src/content/docs/en/pages/style-guide/content/concept.mdx

@@ -41,6 +41,8 @@ Descriptive: 25 words per sentence, active voice, passive only where the actor i
 
 The title is `How <X> works`, `About <X>`, or a short noun phrase: `How Tiered Cache works`.
 
+A mechanism page is the concept page of one Product nested in a Platform Resource. It opens the Product's Reference group in the sidebar, and its title names the mechanism, such as `Scoring and modes` for WAF. It is never titled `How <Product> works`, because the resource's How it works page already introduces the Product in a `## <Product>` section that links here.
+
 **Required components**
 
 - **Opening move**: a declarative statement of how the system behaves, in the reader's terms before any Azion object is named. Never `This page explains`.
@@ -106,7 +108,7 @@ behaves, and what it costs.>
 This excerpt of a concept page for Tiered Cache shows the opening move, the roadmap sentence, and the first mechanism section:
 
 ```mdx
-**Tiered Cache** is a Cache feature that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team.
+**Tiered Cache** is a Feature of Cache that adds a cache layer between Azion's distributed infrastructure and the origin servers. With Tiered Cache enabled for the application, content stays cached for longer periods and the origin receives fewer requests. Tiered Cache is designed for objects that can remain in cache for a long period of time. Tiered Cache is available on request: activation goes through the Sales team.
 
 Its behavior depends on five mechanisms: the cache layers, the second-layer region, the TTL requirements, the Bypass Cache limitation, and the purge order.
 

apps/docs/src/content/docs/en/pages/style-guide/content/information-architecture.mdx

@@ -36,24 +36,23 @@ A Platform Resource type with a section of its own (Workloads, Edge DNS, Applica
 
 Two slots have a fixed sidebar shape.
 
-**Guides and tutorials is one row that opens a page.** The row points at a hub whose body is a single table: name, last updated, and difficulty, one row per guide and per tutorial. The sidebar never expands it, and the reader opens a guide from the table. A section with forty guides stays one sidebar row, so the sidebar keeps showing the whole section.
+**Guides and tutorials is one row that opens a page.** The row points at a hub whose body is a single table: name, type, and last updated, one row per guide and per tutorial. The sidebar never expands it, and the reader opens a guide from the table. A section with forty guides stays one sidebar row, so the sidebar keeps showing the whole section.
 
-The table is generated, not written. The date is the page's last change and the difficulty comes from the page's `difficulty` frontmatter field, so the hub cannot drift from the pages it lists.
+The table is generated, not written. The date is the page's last change and the type is the content type the guides catalog records for the page, so the hub cannot drift from the pages it lists.
 
 **Reference is a fixed group.** The sidebar shows a **Reference** parent holding one row per reference page. The group name is the same in every Platform Resource section, so the reader finds the fields in the same place everywhere.
 
-Other rows may group the same way. A group is a menu parent, not a page, and it stays one level deep. Two modes exist:
+Other rows may group the same way. A group is a menu parent, not a page, and it stays one level deep. It holds one slot's pages under the slot's standard name. Reference is the canonical case. Quickstart groups the same way in the one case it still splits: a first run an interface cannot share.
 
-- **Fixed groups** hold one slot's pages under the slot's standard name. Reference is the canonical case. Quickstart groups the same way in the one case it still splits: a first run an interface cannot share.
-- **Same-type groups** hold related closing pages under one thematic parent. **Management** holds Limits, Pricing, and Changelog: the pages the reader consults about running the Platform Resource.
+Limits, Pricing, and Changelog are rows of the section, at the same level as every other row, in slot order. They never share a parent such as **Management**.
 
 Do not group rows that read fine flat. A parent costs the reader one click on every visit, so a group must pay for itself.
 
 A feature with its own surface repeats the pattern one level down: Tiered Cache under Cache, with the same skeleton reduced to the parts it needs.
 
 ## Nested Products
 
-A Product enabled on a Platform Resource is a dropdown row inside the resource section, in the slot-4 position, with no group label: WAF, Network Shield, and Bot Manager inside Firewall; Cache, Application Accelerator, and Image Processor inside Applications; Load Balancer and Origin Shield inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. The Product keeps only the pages that are its own: its reference pages, a Quickstart when it has a setup of its own, and, optionally, an Overview that the resource's Overview links. Everything else the reader needs about it is written once, in the resource's pages: what the Product does and when to turn it on in the resource's Overview, how it works in the resource's How it works, its limits, practices, and symptoms in the resource's Limits, Best practices, and Troubleshooting, its terms in the resource's Glossary, and its guides in the resource's hub.
+A Product enabled on a Platform Resource is a dropdown row inside the resource section, in the slot-4 position, with no group label: WAF, Network Shield, and Bot Manager inside Firewall; Cache, Application Accelerator, and Image Processor inside Applications; Load Balancer, Origin Shield, and Live Ingest inside Connectors; Certificate Manager, Custom Pages, and DDoS Protection inside Workloads. The Product keeps only the pages that are its own: its reference pages, a Quickstart when it has a setup of its own, and, optionally, an Overview that the resource's Overview links. When the Product has a mechanism to explain, its Reference group opens with a mechanism page: a [concept page](/en/documentation/style-guide/content/concept/) titled for the mechanism, such as Scoring and modes for WAF. Everything else the reader needs about it is written once, in the resource's pages: what the Product does and when to turn it on in the resource's Overview, a `## <Product>` section in the resource's How it works that introduces the Product and links its mechanism page, its limits, practices, and symptoms in the resource's Limits, Best practices, and Troubleshooting, its terms in the resource's Glossary, and its guides in the resource's hub.
 
 A Product nests when its configuration lives in the resource's own settings or rules: a flag in `modules`, a Rules Engine behavior, or a field of the resource. A Product or resource the reader consumes from code (Functions, Object Storage, SQL Database, KV Store, AI Inference) and a standalone service (Edge DNS, Data Stream, Orchestrator) stay at the root of Platform Resources. A feature is a page inside its Product, never a dropdown. A Platform Resource type nested in another, such as Certificate Manager and Custom Pages in Workloads, follows the same rule.
 
@@ -65,7 +64,7 @@ Platform onboarding, such as [Creating an account](/en/documentation/fundamental
 
 - **The order mirrors adoption.** A slot never moves ahead of its stage.
 - **Pricing and Changelog close the section.** The reader consults them rather than passing through them.
-- **The Required column decides what ships.** Every other slot exists only when real content fills it. The column applies to a section; a nested Product needs only its reference pages, plus a Quickstart when it has a setup of its own.
+- **The Required column decides what ships.** Every other slot exists only when real content fills it. The column applies to a section; a nested Product needs only its reference pages, plus a mechanism page when it has a mechanism to explain and a Quickstart when it has a setup of its own.
 - **Never add a slot to complete the pattern**, and never keep an empty one as a placeholder.
 - **The slot list is closed. Grow by splitting a slot the section already has:** Guides and tutorials into named task groups on the hub page, Features by surface. Quickstart grows inside its page, by interface tabs, and splits only when the stages cannot be shared. A fixed list is what lets the reader find the same slot in the same place in every section.