# Repository Contents

Updated: 2026-03-01
Purpose: single-file map of repository structure for quick onboarding and orientation.

## How to use this file
- Read this file at the start of a new chat/session to understand repo structure quickly.
- Re-read this file when context is unclear, requirements conflict, or there are navigation uncertainties.
- For active build/deploy work, treat `devops/` as the primary operational source of truth.

## Mandatory policy for new chats
- Для `instance`-ресурсов с операциями `suspend/resume` обязательный источник правил: `docs/60_strategy/provider_philosophy.md` (разделы 7-9).
- Применять только каноничные флаги: `adopt_existing_on_create` (default `false`) и `suspend_on_destroy` (default `true`).
- Логика apply/destroy/modify должна следовать status-matrix из стратегии (`deleted`, `suspend`, `running`, `not created`, `creating`).
- Упоминания `resume_if_exists` и `delete_mode` считать legacy и не использовать как норматив для новой реализации.

## Build/Deploy priority
- Основной источник инструкций для сборки и деплоя: `devops/`.
- При любых задачах публикации, генерации, сборки и релизов сначала проверять:
  - `devops/README.md`
  - `devops/ARCHITECTURE.md`
  - `devops/01_generate_yamls.sh`
  - `devops/02_generate_resources_and_docs_template_v2.sh`
  - `devops/03_build_and_upload_provider.sh`

---

## Top-level summary
- `docs/` — **Единый корень документации** (overview, discovery, registry, analysis, history, strategy, API).
- `tools/har/` — Scripts used to analyze HAR files and extract parameters/stages.
- `har/` — Collected HAR files captured from browser/API traffic (raw evidence files).
- `artifacts/` — JSON artifacts produced by live API queries and intermediate outputs.
- `internal/provider/` — Terraform provider implementation (resources and data-sources).
- `operator/`, `k8s/` — Operator manifests and Kubernetes overlays.
- `examples/` & `tests/` — Usage examples and test scenarios for the provider.
---

## Docs publication (CI) & Cloud S3 Storage
- **Cloud Storage:** The project uses Nubes Cloud S3 (`s3.msk-1.ngcloud.ru`) with `S3_*` variables.
- **Infrastructure:** Storage is external S3; Kubernetes resources are S3-only.
- **Docs Location:** Published static HTML is stored in the `terraform-registry` bucket.
- **Path Pattern:** `/docs/nubes/nubes/<version>/` (Proxy logic handles mapping to S3 keys).
- **Branding:** Documentation uses MkDocs Material with Nubes "Strict" style (Logo-only header, Blue/Indigo palette).
- **CI Secrets:** `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_BUCKET`, `REGISTRY_HOSTNAME`.
- **History & Discovery:** See `docs/history/09_s3_migration_and_branded_docs.md`, `docs/discovery/s3-storage-and-docs-architecture.md` and `docs/discovery/documentation_build_and_deploy.md` for full context on this transition and build processes.
---

## docs/
- `docs/README.md` — Главный индекс документации (быстрые ссылки на критические темы).
- `docs/00_overview/` — Обзор, архитектура, чеклисты.
- `docs/20_discovery/` — Discovery-материалы по сервисам.
- `docs/30_registry/` — Реестр и ресурсы.
- `docs/40_analysis/` — Анализ, форензика, инциденты.
- `docs/50_history/` — История изменений.
- `docs/60_strategy/` — Стратегия и принципы.
- `docs/70_api/` — API-материалы и дампы.
  - `docs/70_api/api_analysis/` — API reverse-engineering outputs and machine-generated API documentation.


## tools/har/
- `analyze_f12_har.py` — Script to parse `f12vmbad.har` and extract operation timelines.
- `analyze_faststart.py` — Analysis helper for `faststart.har`.
- `extract_params.py` — Extracts `instanceOperationCfsParams` bodies and maps them to svc IDs.
- `compare_har.py` — Diffing tool for HAR files (stages/headers summary).
- `check_op.py` / `check_status.py` — Helpers to re-query API operation status.

## har/
- `f12vmbad.har`, `f12vmbad1.har`, `faststart.har`, `edge.har`, `vm.har`, etc. — Raw HAR files. **Large and sensitive**; don't commit new raw HARs to repo without consent. Use `tools/har/*` scripts to parse.

## artifacts/
- `edge_instance.json`, `service_22_detail.json`, `instances_list.json` — Live API JSON dumps captured during investigation. Use them to craft provider schemas.

## internal/provider/
- `*resource.go`, `*_data_source.go` — Provider implementations for resources (VM, VDC, Edge, VApp, Postgres, S3bucket, etc.). Important files:
  - `vm_resource.go` — VM lifecycle logic & polling
  - `edge_resource.go` — Edge discovery/resolution
  - `provider.go` — Provider schema and configuration

## examples/ & tests/
- `examples/*` — Terraform example configs for different deployment patterns (full-stack, infra-only, quick-start).
- `tests/*` — Automated test scenarios (lifecycle, postgres modify tests, s3 tests). Use to validate changes.

## operator/ & k8s/
- Operator code and Kubernetes manifests to run the Registry/Operator. Contains build artifacts in `operator/bin/`.

## scripts/
- `scripts/deploy-dev.sh` — Dev deployment helpers.

---

## Recommended reading order for agents
1. Read `REPO_CONTENTS.md` at chat start (and re-read when unclear context appears).
2. For build/deploy/generation tasks: read `devops/README.md` and relevant scripts in `devops/` first.
3. Read `docs/60_strategy/provider_philosophy.md` (обязательные правила поведения провайдера и агентов; сначала разделы 7-9).
4. Read `docs/README.md` (главный индекс).
5. Read `docs/70_api/api_analysis/API_DOCUMENTATION_SUMMARY.md` to understand API endpoints.
6. Read `docs/20_discovery/*` relevant to the target service (e.g., `edge-service.md`).
7. Inspect `artifacts/*` JSON examples and `har/*` only via `tools/har/*` scripts.

---

If you want, I can add more granular mapping (function names, exported symbols) per source file, or generate a Markdown tree with intra-file links. Tell me the level of detail you want: "brief", "detailed", or "code-level".