From 78dc5ebc37047a14a0effb1d4de80b80e071e6e6 Mon Sep 17 00:00:00 2001
From: "a.tolmachev" <a.tolmachev@tbank.ru>
Date: Tue, 7 Apr 2026 13:11:22 +0300
Subject: [PATCH] docs: add staging note block helper

---
 README.md                          |  6 +++
 TASKS.md                           |  8 ++--
 docs/authenticated-staging-pass.md | 14 +++++++
 docs/staging-regression-notes.md   |  6 +++
 justfile                           |  3 ++
 scripts/README.md                  | 11 ++++++
 scripts/staging-note-block.sh      | 59 ++++++++++++++++++++++++++++++
 7 files changed, 103 insertions(+), 4 deletions(-)
 create mode 100644 scripts/staging-note-block.sh

diff --git a/README.md b/README.md
index 1fb79a0..90576fb 100644
--- a/README.md
+++ b/README.md
@@ -145,3 +145,9 @@ export CRANK_STAGING_ADMIN_EMAIL=owner@example.com
 export CRANK_STAGING_ADMIN_PASSWORD=secret
 just authenticated-staging-smoke https://<domain>
 ```
+
+Чтобы быстро подготовить запись для `docs/staging-regression-notes.md`:
+
+```bash
+just staging-note-block <domain> <deploy-sha> "codex + operator"
+```
diff --git a/TASKS.md b/TASKS.md
index f1b1ad1..3dd8b5d 100644
--- a/TASKS.md
+++ b/TASKS.md
@@ -2,14 +2,14 @@
 
 ## Current
 
-### `feat/authenticated-staging-smoke-helper`
+### `feat/staging-note-block-helper`
 
 Status: completed
 
 DoD:
-- browser-authenticated staging smoke can be run against a real domain through env vars
-- Playwright skips local webServer for remote runs
-- docs and justfile expose the authenticated smoke helper
+- authenticated staging notes block can be generated through a helper command
+- authenticated pass docs point to the helper
+- README and scripts docs expose the helper
 
 ## Next
 
diff --git a/docs/authenticated-staging-pass.md b/docs/authenticated-staging-pass.md
index 080e960..0a36827 100644
--- a/docs/authenticated-staging-pass.md
+++ b/docs/authenticated-staging-pass.md
@@ -38,6 +38,14 @@ export CRANK_STAGING_ADMIN_PASSWORD=secret
 just authenticated-staging-smoke https://<domain>
 ```
 
+После завершения прохода готовый блок для
+[staging-regression-notes.md](/home/a.tolmachev/code/rust/mcpaas/docs/staging-regression-notes.md)
+можно сгенерировать так:
+
+```bash
+just staging-note-block <domain> <deploy-sha> "codex + operator"
+```
+
 ### 3.1. Login and shell
 
 1. Открыть `/login`
@@ -163,6 +171,12 @@ just authenticated-staging-smoke https://<domain>
 
 ## 5. Готовый блок для вставки
 
+Этот же блок можно получить через:
+
+```bash
+just staging-note-block <domain> <deploy-sha> "codex + operator"
+```
+
 ```md
 ## YYYY-MM-DD HH:MM TZ — rmcp.itexp.me (authenticated pass)
 
diff --git a/docs/staging-regression-notes.md b/docs/staging-regression-notes.md
index c568588..4b2d8e0 100644
--- a/docs/staging-regression-notes.md
+++ b/docs/staging-regression-notes.md
@@ -60,6 +60,12 @@
 - [manual-regression-checklist.md](/home/a.tolmachev/code/rust/mcpaas/docs/manual-regression-checklist.md)
 - [authenticated-staging-pass.md](/home/a.tolmachev/code/rust/mcpaas/docs/authenticated-staging-pass.md)
 
+Шаблон нового блока можно быстро сгенерировать через:
+
+```bash
+just staging-note-block <domain> <deploy-sha> "codex + operator"
+```
+
 ## 2. Как вести записи
 
 Каждый deploy или ручной regression pass должен добавляться новым блоком в начало документа.
diff --git a/justfile b/justfile
index 651d3fe..b69fb3c 100644
--- a/justfile
+++ b/justfile
@@ -32,3 +32,6 @@ staging-smoke base_url:
 
 authenticated-staging-smoke base_url:
     bash scripts/authenticated-staging-smoke.sh {{base_url}}
+
+staging-note-block environment deploy_commit checked_by smoke_status='partial':
+    bash scripts/staging-note-block.sh {{environment}} {{deploy_commit}} {{checked_by}} {{smoke_status}}
diff --git a/scripts/README.md b/scripts/README.md
index 2249ea2..54e596a 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -26,3 +26,14 @@ CRANK_STAGING_ADMIN_EMAIL=owner@example.com \
 CRANK_STAGING_ADMIN_PASSWORD=secret \
 ./scripts/authenticated-staging-smoke.sh https://rmcp.itexp.me
 ```
+
+## staging-note-block.sh
+
+Helper that renders a ready-to-paste markdown block for
+`docs/staging-regression-notes.md` after a real staging pass.
+
+Usage:
+
+```bash
+./scripts/staging-note-block.sh rmcp.itexp.me abc1234 "codex + operator" partial
+```
diff --git a/scripts/staging-note-block.sh b/scripts/staging-note-block.sh
new file mode 100644
index 0000000..cc0332e
--- /dev/null
+++ b/scripts/staging-note-block.sh
@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -lt 3 ]]; then
+  echo "usage: $0 <environment> <deploy-commit> <checked-by> [smoke-status]" >&2
+  echo "example: $0 rmcp.itexp.me abc1234 \"codex + operator\" partial" >&2
+  exit 64
+fi
+
+ENVIRONMENT="$1"
+DEPLOY_COMMIT="$2"
+CHECKED_BY="$3"
+SMOKE_STATUS="${4:-partial}"
+STAMP="$(TZ="${TZ:-Europe/Moscow}" date '+%Y-%m-%d %H:%M %Z')"
+
+cat <<EOF
+## ${STAMP} — ${ENVIRONMENT} (authenticated pass)
+
+- deploy commit: \`${DEPLOY_COMMIT}\`
+- checked by: \`${CHECKED_BY}\`
+- smoke status: \`${SMOKE_STATUS}\`
+- scope:
+  - auth
+  - ui shell
+  - operations
+  - wizard
+  - agents
+  - api keys
+  - secrets
+  - logs
+  - usage
+  - streaming
+  - mcp smoke
+
+### Passed
+
+- login/logout completed
+- shell pages open after auth
+- secrets/auth profile flow status: \`<passed|partial|failed>\`
+- REST smoke: \`<passed|partial|failed>\`
+- GraphQL smoke: \`<passed|partial|failed>\`
+- gRPC smoke: \`<passed|partial|failed>\`
+- streaming pages status: \`<passed|partial|failed>\`
+- WebSocket: \`<not exercised|passed|failed>\`
+- SOAP: \`<not exercised|passed|failed>\`
+
+### Findings
+
+- none
+
+### Infra notes
+
+- ...
+
+### Follow-up
+
+- ...
+EOF