[docs] Update AI assistant rules (#230)

Author: z9r5

.cursor/prompts/documentation-review.md

@@ -8,17 +8,16 @@ Context:
 
 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`
+- Full policy compliance using the normative style guide and glossary at https://pp.flant.ru/llms.txt.
+  Fetch it before starting the review.
+- Terminology and wording compliance using https://pp.flant.ru/llms.txt (see "Glossary" section, fetch before starting the review)
+  and `.cursor/rules/docs/terminology.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:
 
@@ -28,13 +27,14 @@ Review checklist:
 - 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 compliance with policy compliance using the normative style guide and glossary.
+- Check terminology and wording compliance.
 - 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`.
+- Check compliance using https://pp.flant.ru/llms.txt and `.cursor/rules/docs/terminology.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.

.cursor/rules/docs/frontmatter-links-media.mdc

@@ -8,38 +8,17 @@ alwaysApply: false
 
 - 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.
+- If `title` is missing, generate it from page purpose and context.
 - `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`).
+- Use related links as `params.relatedLinks` in front matter.
 - 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.
+- Links to the project pages must be relative. Other links must be absolute.
+- Links to Deckhouse Kubernetes Platform documentation must be absolute without domain (`/products/kubernetes-platform/documentation/v1/...`).

.cursor/rules/docs/global-style.mdc

@@ -1,5 +1,5 @@
 ---
-description: Global style rules for module docs
+description: Global style rules for docs
 alwaysApply: true
 ---
 

.cursor/rules/docs/hugo-supported-codeblock-languages.mdc

@@ -3,8 +3,6 @@ description: Hugo supported code block language identifiers
 alwaysApply: true
 ---
 
-# Hugo and Jekyll Supported Code Block Languages
-
 The full language identifier list below is part of Cursor rules.
 
 # Supported code block languages

.cursor/rules/docs/openapi-x-doc.mdc

@@ -24,7 +24,7 @@ alwaysApply: true
   - `HTTP-протокол` or `протокол HTTP` (not `HTTP протокол`).
 - Do not replace approved terms with synonyms if glossary defines exact form.
 - Keep product naming consistent with glossary and product wording rules.
-- Module name must be used exactly as defined in `module.yaml.name` (canonical lowercase Kebab Case).
+- Deckhouse Module name must be canonical lowercase Kebab Case.
 - Do not humanize or reformat module name in prose:
   - use `stronghold`, not `Stronghold`;
   - use `volume-data-manager`, not `Volume Data Manager`.
@@ -34,7 +34,6 @@ alwaysApply: true
 # Inline Code Scope
 
 - Do not wrap values inside YAML files in backticks — YAML values are already code context.
-  For example, the `name` field in `module.yaml` must contain the plain module name, not `` `module-name` ``.
 - The same applies to other YAML fields: `enum` values, `default` values, etc.
 
 # Language Consistency

.cursor/rules/docs/terminology.mdc

@@ -1,6 +1,6 @@
 ---
 name: run-website
-description: Runs the documentation website locally via `Makefile` and werf. Use when the user wants to run the docs, preview the documentation site, start the docs server, or open the documentation website locally.
+description: Runs the documentation website locally via `Makefile`. Use when the user wants to run the docs, preview the documentation site, start the docs server, or open the documentation website locally.
 ---
 
 # Run Documentation Website
@@ -13,18 +13,22 @@ description: Runs the documentation website locally via `Makefile` and werf. Use
    ```
 
 3. **Open** in a browser:
-   - for the English version — http://localhost/products/kubernetes-platform/documentation/v1/
-   - for the Russian version — http://ru.localhost/products/kubernetes-platform/documentation/v1/
+   - EN: http://localhost/products/development-platform/documentation/
+   - RU: http://ru.localhost/products/development-platform/documentation/
 
-4. **Stop** when done:
+1. **Stop** when done:
    ```bash
    make down
    ```
 
-## Other targets (from docs/site/)
+## All targets
 
-| Target | Use case                                                                    |
-|--------|-----------------------------------------------------------------------------|
-| `make up` | Start docs in watch mode that rebuilds on commit                            |
-| `make lint-markdown-fix` | Run markdown linter and fix some problems automatically                    |
-| `make down` | Stop containers, remove networks, and stop the local registry               |
+| Target | Use case |
+|--------|---------|
+| `make up` | Start docs via Docker Compose |
+| `make down` | Stop and remove containers (`docker compose down --remove-orphans`) |
+| `make serve` | Start Hugo dev server locally without Docker (`hugo serve`) |
+| `make build` | Build the site to `./public` |
+| `make lint-markdown` | Lint Markdown files |
+| `make lint-markdown-fix` | Lint and auto-fix Markdown files |
+| `make mod` | Clean up Hugo modules (`hugo mod tidy`) |

.cursor/skills/run-docs-website/SKILL.md

@@ -0,0 +1,127 @@
+# CLAUDE.md for Deckhouse Development Platform
+
+This repository contains Hugo-based documentation for the Deckhouse Development Platform.
+
+## Run the docs site locally
+
+```bash
+make up      # start via Docker Compose
+make down    # stop and remove containers
+```
+
+- EN: <http://localhost/products/development-platform/documentation/>
+- RU: <http://ru.localhost/products/development-platform/documentation/>
+
+All targets:
+
+| Target | Purpose |
+|--------|---------|
+| `make up` | Start docs via Docker Compose |
+| `make down` | Stop and remove containers |
+| `make serve` | Start Hugo dev server locally without Docker |
+| `make build` | Build the site to `./public` |
+| `make lint-markdown` | Lint Markdown files |
+| `make lint-markdown-fix` | Lint and auto-fix Markdown files |
+| `make mod` | Clean up Hugo modules (`hugo mod tidy`) |
+
+## Editorial policy
+
+The normative style guide and glossary are at **<https://pp.flant.ru/llms.txt>**.  
+Fetch it before writing or reviewing documentation.
+
+## Documentation style
+
+- Write concise technical text with clear user value.
+- No first-level headings (`#`) in documentation files. Minimum level is `##`.
+- Prefer short paragraphs and structured lists.
+- For emphasis, use **bold**; avoid unnecessary italic.
+- Keep instructions actionable and testable.
+- In command examples use `d8 k` instead of `kubectl`.
+- YAML snippets must be syntactically valid.
+- Markdown ordered lists: use `1.` for every item (not `1.`, `2.`, `3.`).
+
+### Inline code
+
+Use inline code for: parameters, module names, commands, file paths, HTTP codes.  
+Do not overuse it for resource type names in narrative text.  
+Do not wrap values inside YAML files in backticks — YAML values are already code context.
+
+### Links
+
+- Use meaningful link anchors (avoid "here" or "тут").
+- Links to project pages must be relative.
+- Links to Deckhouse Kubernetes Platform docs must be absolute without domain (`/products/kubernetes-platform/documentation/v1/...`).
+
+### Code blocks
+
+Every fenced code block must have an explicit language tag from the Hugo/Chroma list.  
+If the needed language is absent, use `text` or `plain`.
+
+Common tags: `bash`, `yaml`, `json`, `go`, `go-html-template`, `text`, `plain`.  
+Full list: see `.cursor/rules/docs/hugo-supported-codeblock-languages.mdc`.
+
+### Hugo shortcodes
+
+```go-html-template
+{{< alert level="warning" >}}
+Message text.
+{{< /alert >}}
+```
+
+Alert levels: `info`, `warning`, `danger`.
+
+```go-html-template
+{{< tabs name="uniq_name" >}}
+{{% tab name="Tab 1" %}}Content{{% /tab %}}
+{{% tab name="Tab 2" %}}Content{{% /tab %}}
+{{< /tabs >}}
+```
+
+```go-html-template
+{{% details "Summary..." %}}
+Markdown content.
+{{% /details %}}
+```
+
+### Release notes (`content/documentation/release-notes/`)
+
+- Under a heading, if the only body content is a single bullet — write plain prose, not a list.
+- Keep lists only when there are two or more top-level bullets under the same heading.
+
+## Terminology
+
+Full glossary: <https://pp.flant.ru/llms.txt> (see "Glossary" section).
+
+Key rules:
+- `K8s` (uppercase K)
+- Use "узел", not "нода"
+- Use "веб-интерфейс"
+- Use `IP-адрес`
+- Use "файлы cookie"
+- Avoid "платформа Deckhouse"; use explicit product names (e.g. Deckhouse Kubernetes Platform)
+- Deckhouse module names must be in lowercase kebab-case.
+- Do not translate product names and abbreviations that the glossary keeps in EN (e.g. `RBAC`)
+
+Mixed EN/RU compound terms use a hyphen: `S3-бакет`, `managed-сервис`, `master-узел`, `HTTP-протокол`.
+
+## Russian text style
+
+In Russian instructional text, always use the imperative вы-form:
+- «создайте», not «создаем»
+- «нажмите», not «нажимаем»
+- «перейдите», not «переходим»
+
+This applies to all step-by-step instructions, quickstart guides, and procedural text.
+
+## Front matter
+
+Required fields: `title`, `description` (concise, unique, not a copy of title).
+
+- Related links: use `params.relatedLinks` in front matter; do not add manual "Related links" sections in the Markdown body.
+
+## EN/RU parity
+
+- Russian files use the `.ru.md` suffix only (not `.RU.md`, `_RU.md`).
+- For each change relevant to both languages, update both files.
+- Do not leave EN/RU pairs semantically diverged unless the change is intentionally language-specific.
+- Localized media: `image1.jpg` (EN) / `image1.ru.jpg` (RU).