[marcus-souza-azion]

What & why

Related issue: none. The source is a comparison of the style guide, as published after #2561, with the shipped repository and with the rulings of the Applications and Workloads reviews.
Pages affected: 34 files in the style guide. 13 pages change in both languages, and 8 Portuguese pages change only in their examples. The en permalinks, under /en/documentation/style-guide/:

• Content structure: content/information-architecture/, content/navigation-hubs/, content/choose-a-content-type/, content/concept/, content/overview/, content/troubleshooting/, content/reference/, content/changelog/
• Writing, formatting, and conventions: writing/terminology/, writing/sentence-structure/, formatting/headings/, conventions/bilingual/, components/
• Portuguese examples only, under /pt-br/documentacao/guia-de-estilo/: como-documentamos/docs-as-code/, conteudo/arquitetura/, conteudo/casos-de-uso/, conteudo/guias-multirrecurso/, conteudo/quickstart/, escrita/procedimentos/, formatacao/pontuacao/, formatacao/texto/
• Repository files (Part 5): .github/PULL_REQUEST_TEMPLATE.md, .github/CONTRIBUTING.md, AGENTS.md, CLAUDE.md, .gitignore

In some places the style guide described one structure while the shipped sections use another. It was also silent on rules that recent reviews settled. In every case, this PR moves the guide to the rule. Pages that do not follow a new rule yet are left for later PRs: the guide describes the target, and this PR changes no page outside it.

The PR has 5 commits, grouped by topic. Each commit that changes a page carries both languages. The fifth gives agents the pull request description format, so a contributor who drafts a PR with an agent gets the review checklist without asking for it.

Part 1: section structure (48b789891)

• No Management group. Limits, Pricing, and Changelog are rows of a Platform Resource section, at the same level as the others. The root sidebar keeps its own Management group.
• Guides and tutorials hub. The table lists name, type, and last updated, and it sorts alphabetically by navigation label. The guide had said "newest first" in one place, "by title" in another, and a difficulty column in a third. No page sets difficulty.
• Mechanism page. When a nested Product has a mechanism to explain, its Reference group opens with a concept page titled for that mechanism, such as Scoring and modes for WAF. The resource's How it works keeps a ## <Product> section that introduces the Product and links the mechanism page. Concept pages gains a paragraph on this page.
• Troubleshooting. On a resource with nested Products, the resource's symptoms come first, then one ## <Product> section per Product, with its symptoms as ###.
• Live Ingest joins the list of Products nested in Connectors.

Part 2: classes and terminology (922dfb3b6)

• State the class. The sentence that defines an Azion element states its class, as in **Functions** is a Platform Resource that…. A new Documentation terminology section classifies each element: a section root is a Platform Resource, a nested Product is a Product, and a Feature carries its scope. The Overview template, its Functions example, its resources entries, and the Tiered Cache example in Concept pages carry the class.
• The Overview mechanism opens with what the reader would assume wrong and says what happens instead, in the same sentence.
• Name the data center. A sentence about where the platform answers names "the data center nearest to your user", never "close to your users", and never "geographically closest".
• Tie the instance to its Platform Resource where the instance first appears: "An application is the object you create in Applications."
• Instance names in Brazilian Portuguese. The instance keeps its US English name, in lowercase: a application, a function, o workload, o connector, o firewall, o deployment, o bucket. Generic nouns stay translated: regra, instância, certificado, zona. The Bilingual pages substitution and every Portuguese example in the guide follow the rule, except one link text that quotes the title of a published page.

Part 3: cohesion (d6de1d6de)

• Sentence structure gains three rules: connect each sentence to the one before; let the first sentences of paragraphs and bullet lead-ins carry the section; introduce one new term per sentence.
• "Use the same word for the same action" now covers a restated list. Its paragraph on interface strings also asks for the fact before the quoted string.
• The draft checklist gains one line for each rule.

Part 4: four rules the guide stated two ways (2ceb1ce77)

• Version notices. Reference pages no longer allows a hand-written caution for a version. Every version notice comes from the snippets in Components.
• Changelog description. The Components example now uses description="Version 1.3.0", as Changelog pages requires.
• Changelog subject. A change to a nested Product opens with the Product, as in **Bot Manager** now…. That matches the guide's own example.
• Acronyms in headings. An acronym is spelled out once per page, at its first mention, so a ## WAF section on a page that already expanded WAF is valid.

Part 5: the pull request description format

• Template. .github/PULL_REQUEST_TEMPLATE.md returns to What & why, Type of change, and Author checklist, the format of docs(governance): add governance model, PR checks, and contribution templates #2307 that CONTRIBUTING, GOVERNANCE, and AGENTS.md still described as "the review contract". The checklist rows are the docs(governance): add governance model, PR checks, and contribution templates #2307 rows, word for word. The URL guidance that docs(style-guide): review the EN style guide against the naming catalog (MM-16284) #2561 added becomes a comment on the redirect row.
• AGENTS.md. A new "The description" section tells an agent to write the description in the template's format and to keep every checklist row verbatim. A row that is not true stays unticked, with the reason after a dash. When the agent does not open the PR, it writes the description to pr.md at the repository root, title line first.
• Claude Code. When a repository has both files, Claude Code reads CLAUDE.md and not AGENTS.md. CLAUDE.md now imports AGENTS.md above the webkit block, which webkit init leaves alone.
• Redirect path. AGENTS.md pointed redirects to apps/redirects-massive/src/redirects/, which no longer exists. It now names apps/docs/redirects/{en,pt-br}/, as CONTRIBUTING does. CONTRIBUTING's pointer to the removed "URL changes and redirects" section now points to the redirect row.
• .gitignore ignores /pr.md, so a drafted description is never committed.

Where the facts come from

• Navigation trees (src/nav/trees/): Live Ingest is nested in Connectors. In 16 Platform Resource trees, the Management parent holds only Pricing and Changelog.
• Hub code: buildGuidesHome in src/nav/resolve.ts sorts by label with localeCompare, and ProductGuidesTable.vue renders name, type, and updated.
• Shipped pages: Firewall > WAF > Reference > Scoring and modes (secure/waf/how-it-works.mdx) and the ## WAF section of Firewall troubleshooting.
• The naming catalog sets the class of each nested element. Certificate Manager, Custom Pages, and DDoS Protection are platform resources. WAF, Network Shield, Cache, Application Accelerator, Image Processor, and Live Ingest are products.
• Azion Platform overview: the nearest data center is chosen by latency, network conditions, and load.
• Applications overview: "a workload whose deployment names it", the fact behind the cohesion examples.
• Template history: docs(governance): add governance model, PR checks, and contribution templates #2307 added the checklist template, refactor(docs): rebuild the docs on Astro 7, Tailwind 4 and @aziontech/webkit 4 #2328 replaced it with Summary, How to test, and Notes, and docs(style-guide): review the EN style guide against the naming catalog (MM-16284) #2561 added URL changes and redirects.
• Claude Code documentation (How Claude remembers your project, AGENTS.md): with both files present, Claude reads only CLAUDE.md, and an @AGENTS.md import brings AGENTS.md in.

For review

• Instance names diverge from the naming catalog. The catalog's translation rule says the entities a customer creates are translated, with the example "funções do cliente". This PR keeps them in English in the documentation, by decision, so the catalog owner needs to know about the divergence.
• instância de function is the default for a function instance in Portuguese, in Docs as code and in the Overview mechanism example. Please confirm it.
• Pages follow later. The 16 trees still carry Management. Portuguese pages still write aplicação and função. Most Overviews do not state the class yet.
• Content and repository files travel together. Part 5 changes the PR template and agent instructions in a content PR. AGENTS.md asks for one concern per PR, and this is a decision to ship them together. Part 5 also reverts the template change of refactor(docs): rebuild the docs on Astro 7, Tailwind 4 and @aziontech/webkit 4 #2328 and docs(style-guide): review the EN style guide against the naming catalog (MM-16284) #2561, so their authors should see it.
• GlossaryFilter is out of this PR, because docs/mm-16227-glossary-filter-removal removes it.
• Overlap with docs/mm-16248-console-paths. Both branches touch componentes.mdx, the Portuguese troubleshooting.mdx, and guias-multirrecurso.mdx, on different lines. The branch that merges second rebases.

How it was checked

• Write-time gate: no new finding on the 34 files. The three findings left are the description lengths above.
• Build-free link check: no broken rendered link, no cross-language link, and every namespace paired, across the 34 files.
• Dev server: every changed page returns 200 in both languages and shows the new text. The new headings render the anchors the links use: state-the-class-of-an-azion-element, declare-a-classe-de-um-elemento-da-azion, connect-each-sentence-to-the-one-before, and ligue-cada-frase-a-anterior. The existing avisos-de-versao anchor also renders, and a new link now targets it.
• Inbound anchors: the guide headings that other pages link keep their text: #nested-products, #produtos-aninhados, #mermaid-diagrams, #diagramas-mermaid, and #version-notices.
• EN and PT parity: every pair has the same ## and ### counts, except Punctuation, as noted above.
• Regression search: none of the replaced wordings remains in the guide: Management as a group, "newest first" for the hub, difficulty, "by title", "effort and freshness", "Two modes exist", the version caution, and the Bot Manager description. The only matches left are Changelog pages' own "newest first" order for entries and the rule that bans "close to your users".

Type of change

• 🆕 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 — Part 5 changes repository files, but it travels with content, so this row is not true

Author checklist

• PR title follows type(scope): summary (see GOVERNANCE.md §4)
• 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 — no screenshot is added or changed
• Internal links are relative and resolve locally
• If any permalink changed or page moved: redirect added in this PR
• i18n: pt-br updated in this PR or follow-up i18n issue created: — every en change has its pt-br twin in the same commit
• I ran pnpm build:local (build + frontmatter check) without errors