Перейти к основному содержимому

Refresh documentation for mp.hyp.ru

Use this skill to bring the maintained GWPTD documentation in line with the current source and, when explicitly requested, with read-only runtime evidence from production s2. s3 may execute the isolated refresh, but it is not a live documentation source. The generated catalogs remain under docs/, not in this directory. Continuous collection has two independent lanes: code-only GitHub automation and a read-only s2 live snapshot executed from s3; their health and boundaries are defined in docs/DOCUMENTATION-AUTOMATION.md.

The separate docs-next/ lane reconciles declared Next contracts with the observed s3 runtime. It does not replace s2 evidence and must remain independent from the maintained documentation refresh described here.

When to use it​

  • The user asks to refresh, update, or verify the documentation of mp.hyp.ru, GWPTD, the backend catalog, the /new UI catalog, or the documentation registry.
  • A code or navigation change needs its documentation evidence refreshed.
  • A documentation CI run reports stale generated output.

This skill documents and verifies the fixed business formulas and rules; it does not authorize changing their meaning, deploying code, editing secrets, or closing owner-gated decisions. A formula or status change needs an owner decision and matching code, machine-rule, BR and golden-case evidence.

Required context​

Before modifying files:

  1. Work only in the real gwptd-analytics Git repository.
  2. Read AGENTS.md, CLAUDE.md, this file, and relevant Vestige/code-index context.
  3. Record git status --short and HEAD; preserve unrelated changes.
  4. Classify the requested evidence mode:
    • code-only is the default;
    • live is allowed only when the user asks for current/server evidence or explicitly mentions s2, s3, runtime, or a live refresh.

Never print or copy .env contents, credentials, API tokens, raw payloads, database passwords, or raw runtime logs into documentation or the skill.

Procedure​

1. Diagnose without writing​

Run the repository check first:

scripts/docs/check-documentation.sh

It regenerates comparison output in temporary directories and fails if the tracked backend/UI catalogs or documentation registry are stale, or if the fixed business-canon integrity check fails. It must not be treated as a successful refresh merely because an individual generator printed output.

2. Refresh code-derived catalogs​

For the default code-only mode, this refreshes the schema catalog, ETL and formula catalog, PageSpec-aware UI catalog, UI-to-Data-API matrix and the main documentation registry:

scripts/docs/refresh-catalogs.sh
scripts/docs/check-documentation.sh

For live mode, s2 is the only canonical evidence source. Run it from the trusted s3 executor, which publishes a documentation-only branch; do not try to run --live from a Mac that lacks the V3 database client:

ssh s3 'cd /opt/gwptd-analytics/repo && scripts/docs/publish-live-catalog.sh'

The s3 executor reads data-free DDL and redacted runtime state from s2, creates an isolated worktree, and pushes only documentation to automation/next-s2-live-catalog. It is evidence gathering, not permission to write or deploy on s2. To install the daily executor after the code is deployed to s3, run scripts/docs/install-live-catalog-timer.sh as root on s3.

S3 deliberately has no host PHP. The installed live unit therefore sets GWPTD_DOCS_PHP to scripts/docs/run-container-php.sh: it runs only the UI generator in the exact running gwptd-app-new:next image, with network disabled and only the isolated worktree plus reviewed Composer dependencies mounted. The launcher refuses a mismatched worktree SHA or image ID before generating output.

3. Reconcile editorial registers​

Inspect the generated diff and update these only where current code, a committed decision, or live evidence supports the claim:

  • docs/architecture/GAPS-AND-REMEDIATION.md
  • docs/domain/DEFECT-LEDGER.md
  • docs/domain/OPEN-GATES.md
  • docs/ui/KNOWN-GAPS.md
  • docs/ui/NAVIGATION-MAP.md

Keep implementation evidence separate from decisions. A missing owner decision is an open gate, not a defect that an agent may close. For navigation, describe the actual /new group order and distinguish marketplace, cross-marketplace, and service/administration layers.

For the fixed business canon, inspect rather than rewrite meaning:

  • docs/domain/machine-rules/formulas.yaml
  • docs/domain/machine-rules/shipment.yaml
  • docs/domain/metric-status-map.yaml
  • docs/domain/DO-NOT-REGRESS.md

A disagreement between those sources and implemented kernel/Data API behavior is a hard failure, not an editorial cleanup.

4. Validate and hand off​

  1. Run scripts/docs/check-documentation.sh after every intended change.
  2. When a script, workflow, unit or this skill changes, run scripts/docs/check-documentation-automation.sh; after deployment, also use --github --live-host s3.
  3. Review git diff --check and the documentation diff. Do not stage or alter unrelated user changes.
  4. Publish only with explicit user authorization. The scheduled GitHub workflow may propose a draft PR; it does not authorize a merge or a live refresh.
  5. Report evidence mode, validation results, files changed, and gaps grouped as active, owner-gated, frozen, or stale-registry.

Failure handling​

  • If the refresh produced files but returned a non-zero status, do not claim a completed refresh. Run the check, inspect whether docs/DOCUMENTATION-CATALOG.md was updated, and report the failed generator.
  • If a live host is unavailable, retain existing evidence and mark it stale; do not fabricate a runtime conclusion.
  • If a generated diff reflects unrelated uncommitted code, stop before editing editorial registers and ask whether that code belongs in this refresh.

Procedural memory maintenance​

The manifest records the stable inputs, outputs, and lifecycle triggers. The repository is canonical; distribute this skill with scripts/docs/sync-documentation-skill.sh --install rather than editing local Codex or Claude copies. Update this skill and skill.yaml whenever scripts, evidence boundaries, or the documentation contract change. Record the result of a material refresh in Git and Vestige; do not add raw logs or secret-bearing runtime output to this tree.