add: documentation

docs/60_strategy/docs_generation_clickhouse_template.md

@@ -0,0 +1,67 @@
+# Docs Generation Strategy: ClickHouse Template
+
+## Purpose
+This document captures the current documentation generation logic based on the ClickHouse template. It is a living reference and should be updated when the generator logic changes or issues are found.
+
+## Scope
+- Applies to all resources generated from API-derived YAML specs in:
+  - `universal_rebuild/resources_yaml/*.yaml`
+- Output target:
+  - `docs/30_registry/resources/`
+- ClickHouse is the reference template and is excluded from automatic generation by default.
+
+## Current Generator
+- Go generator:
+  - `universal_rebuild/tools/docs_template_gen/main.go`
+- Runner script:
+  - `devops/02_generate_resources_and_docs_template.sh`
+
+## Input Sources
+- Primary source of truth: API YAML specs
+  - `universal_rebuild/resources_yaml/*.yaml`
+- Service ordering:
+  - `devops/services_list.txt`
+
+## Output Structure (per resource)
+For each resource `name`, the generator writes:
+- `name.md` (Manual)
+- `name_params_create.md`
+- `name_params_modify.md`
+- `name_outputs.md`
+- `name_ops.md`
+- `name_example.md`
+- `name_params.md` (landing)
+
+Each page uses a fixed nav row:
+`Manual | Create params | Modify params | Output params | Operations | Example`
+
+## Template Notes
+- Manual page uses `service_man` content from YAML.
+- Example page builds a copy-ready manifest with required params first, then default params.
+- Create params are split into:
+  - Required params (no Default column)
+  - Params with defaults (Default column kept)
+- Modify params table has no Required or Default columns.
+- Output params list is derived from `outputs.params`.
+- Operations page lists actions with links to Create/Modify pages and subresources where present.
+- Lifecycle defaults are rendered as a small note at the end of Create params if present in YAML.
+
+## Snapshot + Validation Process
+Before running the generator, take a snapshot of the current ClickHouse docs:
+- Location: `docs/30_registry/resources/_snapshot_clickhouse_YYYYMMDD/`
+- Content: copy all `clickhouse*.md`
+
+After generation, compare the new outputs to the snapshot to validate:
+- Nav row consistency
+- Table structure and column rules
+- Lifecycle note format and line breaks
+- Example formatting and default params separation
+
+## Known Exclusions
+- ClickHouse is excluded by default to preserve manual refinements.
+- To include ClickHouse for testing, remove it from the generator exclude list.
+
+## Update Policy
+- When generator logic changes, update this document.
+- Record any issues found during comparison and how they were resolved.
+