Analyze the repository, README, codebase, AND Backstage `catalog-info.yaml` to generate complete, context-aware documentation using `.github/mkdocs.yml` as a template.

---

## Steps to perform

### 1. Determine Repository Metadata
- Detect the repository name using `git config --get remote.origin.url` (or fallback to folder name).
- Read the `README.md` file to extract any useful descriptive or architectural information:
  - Project summary
  - Features
  - Usage instructions
  - Diagrams or architecture hints
- Analyze the source code (entire repo) to identify:
  - Key components (frontend, backend, API, database, workers, pipelines, etc.)
  - Technologies, frameworks, and libraries
  - Integrations, dependencies, or message flows
  - Authentication, CI/CD, or deployment logic

### 2. Read and Analyze `catalog-info.yaml` (if present)
- Parse `catalog-info.yaml` for additional metadata:
  - From `metadata.annotations`:
    - `github.com/project-slug` → GitHub repo URL
    - `jenkins.io/job-full-name` (+ optional `jenkins.io/instance`) → Jenkins job URL
    - `backstage.io/techdocs-ref` → docs directory (assume `dir:.`)
    - `backstage.io/source-location` → source code location
    - Any other service links (e.g., Datadog, Grafana, Confluence)
  - From `metadata.links[]`:
    - Collect Repo, CI/CD, KB, Monitoring, Runbook, Architecture, or Documentation links
  - From `spec`:
    - `system`, `domain`, and `owner` (Tribe/Team)
    - `dependsOn`, `providesApis`, `consumesApis`
- Merge this metadata with information from the README and codebase.

---

### 3. Generate Contextual Project Description
- Compose a short, meaningful description using combined signals from:
  - README overview
  - Key technologies
  - `catalog-info.yaml` metadata
  - Code structure
- Example:
  > “A scalable cross-device tracking and matching system for event correlation and identity resolution, integrated with Jenkins CI/CD and Datadog monitoring.”

---

### 4. Generate or Update Root `mkdocs.yml`
- Use `.github/mkdocs.yml` as a reference.
- Create a **new `mkdocs.yml`** in the repo root with the following updates:
  - **`site_name`**:
    ```
    Documentation for <AUTO_GENERATED_DESCRIPTION> — <REPO_NAME>
    ```
  - **Navigation (`nav`)**
    - Replace `Developer-Portal` with `<REPO_NAME>`
    - Include only pages that actually exist or were generated (`index.md`, `architecture.md`, etc.)
    - Skip irrelevant sections (e.g., “Authentication” if not detected)
  - **`extra:` section**
    - Add quick-access links extracted from `catalog-info.yaml`, such as:
      ```yaml
      extra:
        links:
          - title: GitHub Repository
            url: https://github.com/awin/tracking-crossdevice-matcher
          - title: Jenkins Pipeline
            url: https://jenkins.awin.com/job/AWS-crossdevice-matcher/
          - title: Knowledge Base
            url: https://awin.atlassian.net/wiki/x/3A0QDw
          - title: Monitoring Dashboard
            url: https://app.datadoghq.eu/dashboard/abc123
      ```
- Validate the YAML structure and formatting before saving.

---

### 5. Generate Markdown Documentation (`/docs`)
For each section in the navigation, create or update `.md` files with:

- Title: `# <Page Title>`
- AI disclaimer:
  > **Note:** This documentation is AI-generated and may contain inaccuracies. Please verify technical details before use.
- `_Last updated: <today’s date>_`

Include relevant sections dynamically:
- **Overview** — short project summary (from README + catalog-info.yaml)
- **Details** — technical explanation based on code analysis
- **Implementation** — setup, build, or environment details
- **Dependencies** — from `spec.dependsOn` or inferred from imports
- **Diagrams (Mermaid)** — automatically generated as needed:
  ```mermaid
  graph LR
    A[Frontend] --> B[Backend API]
    B --> C[(Database)]
    B --> D[External Integrations]
  ```
- **Quick Links** — generated from `catalog-info.yaml` (Repo, Jenkins, KB, Monitoring, Runbook)
- **Next Steps** — references to other docs or related services

---

### 6. Optional: Update or Enrich `catalog-info.yaml`
If missing, automatically add or fix fields:
```yaml
annotations:
  backstage.io/techdocs-ref: dir:.
  backstage.io/source-location: url:<repo-url>
  jenkins.io/job-full-name: <jenkins-job>
  github.com/project-slug: <org>/<repo>
links:
  - url: <generated-docs-link>
    title: Documentation (TechDocs)
    icon: docs
  - url: <monitoring-url>
    title: Monitoring (Datadog)
    icon: dashboard
  - url: <kb-url>
    title: Knowledge Base
    icon: help
```

---

### 7. Validate and Summarize
At the end of the run:
- Print a summary of all generated files under `/docs`
- Show a **diff between `.github/mkdocs.yml` and the new `mkdocs.yml`**
- Output detected metadata:
  - Repository name
  - System, domain, owner
  - Tech stack (inferred from code)
  - Extracted URLs (GitHub, Jenkins, Datadog, Confluence)
- Display generated site name and AI-generated description

---

### Expected Output Structure
```
mkdocs.yml                # New, repo-aware TechDocs config
.github/mkdocs.yml        # Reference template (unchanged)
docs/
  index.md
  architecture.md
  architecture-overview.md
  architecture-frontend.md
  architecture-backend.md
  architecture-dataflow.md
  architecture-integrations.md
  architecture-deployment.md
  deploy.md
  cross-functional-teams.md
  dependencies.md
  api.md
```

---

### Goal
Produce a **complete, self-contained TechDocs suite** that:
- Uses repo, code, and Backstage metadata to auto-populate content
- Links directly to Jenkins, dashboards, and KBs
- Generates visual diagrams for architecture and data flow
- Creates an accurate, AI-generated but verifiable documentation baseline
