deckhouse · dacetascien · Jun 4, 2026
diff --git a/.cursor/prompts/documentation-review.md b/.cursor/prompts/documentation-review.md
@@ -0,0 +1,80 @@
+Review documentation changes for compliance with this repository's rules.
+
+Context:
+- This repository contains Hugo-based product documentation.
+- Review the changed documentation files, and inspect nearby related files when needed.
+- If the reviewed page describes product or module behavior, verify the statements against the relevant source code, configuration, schemas, examples, or adjacent documentation. Do not guess functionality.
+- If a rule is not applicable to the changed files, explicitly skip it instead of forcing a finding.
+
+Primary rule sources:
+- `.cursor/rules/docs/global-style.mdc`
+- `.cursor/rules/docs/terminology.mdc`
+- `.cursor/rules/docs/refs-editorial-policy-full.mdc`
+- `.cursor/rules/docs/refs-glossary-full.mdc`
+- `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`
+
+Apply additional rules when relevant:
+- `.cursor/rules/docs/ru-en-parity.mdc` for EN/RU pairs, `.ru.md` naming, and localized media.
+- `.cursor/rules/docs/hugo-shortcodes.mdc` for `alert`, `tabs`, `details`, and shortcode usage.
+- `.cursor/rules/docs/frontmatter-links-media.mdc` for front matter, related links, and media placement.
+- `.cursor/rules/docs/crd-translation-files.mdc` for `crds/doc-ru-*.yaml` translation files.
+- `.cursor/rules/docs/openapi-x-doc.mdc` for `openapi/**/*.yaml` and `x-doc-*` fields.
+
+Review checklist:
+
+1. Accuracy and consistency
+- Check that the documentation matches the actual behavior described by the code, configuration, schema, or examples.
+- Flag claims that are unsupported, outdated, misleading, or contradicted by the implementation.
+- Flag missing prerequisites, caveats, limits, or version-sensitive behavior when they are necessary for safe use.
+
+2. Editorial and style compliance
+- Check compliance with `.cursor/rules/docs/refs-editorial-policy-full.mdc` and `.cursor/rules/docs/global-style.mdc`.
+- Check for concise technical wording, meaningful link anchors, correct emphasis, and actionable instructions.
+- For Russian instructional text, require imperative "вы"-form.
+- For docs pages, do not allow first-level headings (`#`). Minimum heading level is `##`.
+
+3. Terminology compliance
+- Check compliance with `.cursor/rules/docs/terminology.mdc` and `.cursor/rules/docs/refs-glossary-full.mdc`.
+- Flag forbidden or inconsistent terms.
+- Require exact approved product naming.
+- Require `d8 k` instead of `kubectl` in command examples unless the repository rule clearly does not apply to that case.
+
+4. Markdown, Hugo, and code examples
+- Every fenced code block must have an explicit language tag.
+- The language tag must be present in `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`.
+- Markdown ordered lists must use `1.` for every item, not `1.`, `2.`, `3.`.
+- Check Hugo shortcode usage when present.
+- Check that YAML, JSON, shell, and other examples are syntactically plausible and internally consistent.
+- Check that commands, flags, paths, field names, and HTTP codes are formatted as inline code where appropriate.
+
+5. Localization and parity
+- RU files must use the `.ru.md` suffix only.
+- If a change is relevant to both EN and RU pages, check whether both sides were updated consistently.
+- Flag semantic divergence between paired EN/RU pages when it appears unintentional.
+- Check localized media naming when media is language-specific.
+
+6. Front matter, links, and structure
+- Check required front matter fields when present and applicable.
+- Check that links are concise, meaningful, and not broken by obvious path mistakes.
+- Flag manual "related links" sections when front matter rules require structured related links instead.
+
+7. Schema-specific rules
+- For CRD translation files, check path naming, translation scope, and YAML structure.
+- For OpenAPI docs, check `x-doc-*` usage, example structure, and description conventions.
+
+Severity model:
+- `critical`: incorrect or dangerous guidance, a behavioral contradiction, or a change that can cause user harm or a broken workflow.
+- `major`: a strong rules violation, missing important context, broken parity, or a likely user-facing documentation defect.
+- `minor`: wording, formatting, consistency, or low-risk style issues.
+
+Output requirements:
+- Report findings first, ordered by severity: `critical`, `major`, `minor`.
+- Only report real issues. Do not pad the review.
+- For each finding, provide:
+  - severity;
+  - file path;
+  - exact issue;
+  - why it matters;
+  - specific proposed fix.
+- If there are no findings, say: `No issues found.`
+- After findings, add a short section named `Residual risk` with any unverified assumptions or areas you could not validate from the available sources.
diff --git a/.cursor/rules/docs/frontmatter-links-media.mdc b/.cursor/rules/docs/frontmatter-links-media.mdc
@@ -0,0 +1,45 @@
+---
+description: Front matter, links, and media rules
+globs: content/**/*.md
+alwaysApply: false
+---
+
+# Front Matter
+
+- Use YAML front matter in page header.
+- `title`: required.
+- If `title` is missing, generate it from page purpose and module context.
+- For `README` title use template:
+  - RU file (`README.ru.md`): `Модуль <MODULENAME>`
+  - EN file (`README.md`): `Module <MODULENAME>`
+- `<MODULENAME>` must be the exact value from `module.yaml.name` (lowercase Kebab Case), without case/style changes.
+- `linkTitle`: optional, and applicable only to Hugo pages.
+- Do not use `linkTitle` in Jekyll page metadata.
+- `description`: required, concise, unique, and not a copy of `title`.
+- If `description` is missing, generate it automatically from page purpose and key context.
+- Do not set top-level front matter `url`; it is generated automatically.
+- `moduleStatus` in README front matter is deprecated and must not be used.
+- If `moduleStatus` is present:
+  - remove it from README front matter;
+  - validate that lifecycle status is set in `module.yaml` via `stage`;
+  - if README `moduleStatus` conflicts with `module.yaml.stage`, ask user before changing lifecycle value.
+
+# Related Links
+
+- For Hugo pages, use related links as `params.relatedLinks` in front matter.
+- For Jekyll pages, use related links as top-level `relatedLinks` in front matter (without `params`).
+- Do not add manual "Related links" or "Related pages" sections in Markdown body.
+- The related links block is rendered automatically from front matter.
+- If a `relatedLinks` item has no `url`, the link must not be rendered.
+- If `title` is missing, render only module links like `/modules/<module-name>/`.
+
+# Link Rules
+
+- Same module docs links must be relative (`cr.html`, `usage.html`).
+- Other module links must be absolute without domain (`/modules/<module-name>/...`).
+- Deckhouse Kubernetes Platform docs links must be absolute without domain (`/products/kubernetes-platform/documentation/v1/...`).
+
+# Media Rules
+
+- Store images, PDFs, and media only in `docs/` or its subdirectories.
+- Use relative links for files within the same module repository.
diff --git a/.cursor/rules/docs/global-style.mdc b/.cursor/rules/docs/global-style.mdc
@@ -0,0 +1,53 @@
+---
+description: Global style rules for module docs
+alwaysApply: true
+---
+
+# Documentation Style
+
+- Write concise technical text with clear user value.
+- The full editorial policy and glossary are published at https://pp.flant.ru/llms.txt and are normative.
+  Fetch and apply them before writing or reviewing documentation text.
+- Apply editorial policy directly in text:
+  - use inline code for parameters, module names, commands, file paths, and HTTP codes;
+  - do not overuse inline code for resource type names in narrative text;
+  - use meaningful link anchors (avoid generic "here" or "тут");
+  - keep links concise and readable;
+  - prefer bold for emphasis; use italics rarely.
+- Use inline code for parameters, commands, file paths, and HTTP codes.
+- Use fenced code blocks with a mandatory language tag.
+- The language tag must be from `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`.
+- If a needed language is absent in that list, use `text` or `plain`.
+- Prefer short paragraphs and structured lists.
+- For emphasis, prefer bold text; avoid unnecessary italic text.
+- Use Hugo alert shortcode levels: `info`, `warning`, `danger`.
+- For lists, keep punctuation and casing consistent within one list.
+- In Markdown ordered lists, use `1.` for every item instead of `1.`, `2.`, `3.`.
+- Keep instructions actionable and testable.
+- In command examples use `d8 k` instead of `kubectl` (syntax is the same).
+- YAML snippets and YAML files must be syntactically valid.
+
+# Russian Text Style
+
+- In Russian instructional text, always use the imperative (вы-форма), not the first-person plural (мы-форма).
+  - Use «создайте», not «создаем»;
+  - Use «нажмите», not «нажимаем»;
+  - Use «перейдите», not «переходим»;
+  - Use «подключитесь», not «подключаемся»;
+  - Use «введите», not «вводим».
+- This applies to all step-by-step instructions, quickstart guides, and procedural text.
+
+# Markdown And Hugo
+
+- Documentation is rendered by Hugo.
+- Keep Markdown valid and deterministic for static rendering.
+- Use only supported shortcodes and avoid custom undocumented markup.
+- Do not use first-level heading (`# ...`) in documentation files.
+- Minimum allowed heading level is second-level (`## ...`).
+- If a local checklist conflicts with full policy text, follow https://pp.flant.ru/llms.txt.
+
+# Release notes (`content/documentation/release-notes/`)
+
+- Under a heading (`##`, `###`, or `####`), if the only body content is a single top-level bullet (`-` or `*`), do not use a list: write one or more plain paragraphs instead (merge the bullet text with any lead-in sentence on the same topic).
+- If there is a lead-in paragraph and exactly one bullet, merge them into continuous prose and drop the list marker.
+- When there are two or more top-level bullets under the same heading, keep a Markdown list.
diff --git a/.cursor/rules/docs/hugo-shortcodes.mdc b/.cursor/rules/docs/hugo-shortcodes.mdc
@@ -0,0 +1,44 @@
+---
+description: Allowed Hugo shortcodes and partials
+globs: content/**/*.md
+alwaysApply: false
+---
+
+# Hugo Shortcodes
+
+- Use `alert` shortcode with levels `info`, `warning`, `danger`.
+- Use `tabs` for multi-option instructions.
+- Use `details` for collapsible sections with long examples.
+- In fenced code blocks, language identifier is mandatory and must be listed in `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`.
+
+Example `alert`:
+
+```go-html-template
+{{< alert level="warning" >}}
+The warning message...
+{{< /alert >}}
+```
+
+Example `tabs`:
+
+```go-html-template
+{{< tabs name="tabs_uniq_name" >}}
+{{% tab name="Tab caption 1" %}}Tab 1 Content {{% /tab %}}
+{{% tab name="Tab caption 2" %}}Tab 2 Content {{% /tab %}}
+{{< /tabs >}}
+```
+
+Example `details`:
+
+```go-html-template
+{{% details "Summary..."%}}
+## Markdown content
+
+Markdown content...
+{{% /details %}}
+```
+
+# Templates And Partials
+
+- In templates, `alert` and `details` partials are allowed.
+- Keep shortcode syntax exact to avoid broken page rendering.