Merge branch 'main' into dependabot/github_actions/peter-evans/create-pull-request-7

Author: yaniv-golan

AGENTS.md

@@ -6,6 +6,7 @@ This repository hosts the automatically generated **Affinity API v1** and **API
 
 - **Primary doc (v1):** `docs/v1/affinity_api_docs.md` (auto-generated)
 - **Primary doc (v2):** `docs/v2/affinity_api_docs.md` (auto-generated)
+- **OpenAPI spec (v2):** `docs/v2/openapi.json` (auto-generated)
 - **Automation:** `tools/v1_sync_pipeline/` and `tools/v2_sync_pipeline/` (sync + QA tooling)
 
 ## Current Status
@@ -25,7 +26,7 @@ This repository hosts the automatically generated **Affinity API v1** and **API
 - **v1:** `python tools/v1_sync_pipeline/sync_v1_docs.py [--fail-on-diff]`
   - Reads https://api-docs.affinity.co/, writes `docs/v1/affinity_api_docs.md`, snapshot artifacts under `tmp/`
 - **v2:** `python tools/v2_sync_pipeline/sync_v2_docs.py [--fail-on-diff]`
-  - Reads https://developer.affinity.co/, writes `docs/v2/affinity_api_docs.md`, HTML/state JSON/manifest saved under `tmp/v2/`
+  - Reads https://developer.affinity.co/, writes `docs/v2/affinity_api_docs.md` and `docs/v2/openapi.json`, HTML/state JSON/manifest saved under `tmp/v2/`
   - Automatically extracts the embedded Redoc OpenAPI JSON, dereferences `$ref`s, flattens schemas, and injects schema + error appendices
   - `--fail-on-diff` mirrors the v1 behavior (exit 1 when the output differs from what is committed)
 
@@ -41,7 +42,7 @@ This repository hosts the automatically generated **Affinity API v1** and **API
 
 ## Maintenance & Ownership
 
-1. **Never edit** `docs/v1/affinity_api_docs.md` or `docs/v2/affinity_api_docs.md` manually. Regenerate via the sync scripts whenever updates are needed.
+1. **Never edit** `docs/v1/affinity_api_docs.md`, `docs/v2/affinity_api_docs.md`, or `docs/v2/openapi.json` manually. Regenerate via the sync scripts whenever updates are needed.
 2. **Quarterly BROKEN_ANCHOR_MAP review:** revisit `BROKEN_ANCHOR_MAP` inside `sync_v1_docs.py`, confirm the live site still requires the overrides, and track the reminder in the quarterly review issue (label `quarterly-review`).
 3. **Manual validation checklist (when investigating diffs):**
    - Run `python tools/v1_sync_pipeline/sync_v1_docs.py` and `python tools/v2_sync_pipeline/sync_v2_docs.py`
@@ -63,6 +64,7 @@ affinity-api-docs/
 │   │   └── affinity_api_docs.md          # auto-generated canonical doc
 │   ├── v2/
 │   │   └── affinity_api_docs.md          # auto-generated canonical doc
+│   │   └── openapi.json                  # auto-generated OpenAPI spec
 │   └── development/
 ├── tools/
 │   └── v1_sync_pipeline/
@@ -91,6 +93,7 @@ affinity-api-docs/
 ## Important Notes
 
 - `docs/v1/affinity_api_docs.md` and `docs/v2/affinity_api_docs.md` are generated—**editing them manually will be reverted** the next time the pipelines run.
+- `docs/v2/openapi.json` is generated—**editing it manually will be reverted** the next time the v2 pipeline runs.
 - `docs/internal/` is gitignored on purpose—keep planning/rollout notes there locally without committing them.
 - The sync header clearly states the unofficial nature of this copy; always cross-check with https://api-docs.affinity.co/.
 - `llms.txt` spells out the guardrails for AI assistants—review it before delegating tasks to LLMs.

CHANGELOG.md

@@ -9,7 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 _No changes yet._
 
-## [2.0.0] - 2025-11-10
+## [2.1.0] - 2025-12-14
+
+### Added
+
+- Stable Affinity API v2 OpenAPI spec artifact at `docs/v2/openapi.json` (auto-generated by `tools/v2_sync_pipeline/sync_v2_docs.py`).
+
+### Fixed
+
+- v2 markdown internal links now point to GitHub-compatible anchors (rewrites Redoc-style fragments during generation).
+- Updated broken API key help-center URL in the v2 markdown output.
+
+## [2.0.0] - 2025-12-02
 
 ### Added
 
@@ -25,6 +36,10 @@ _No changes yet._
 - v2 descriptions preserve embedded markdown tables, convert single-cell callout tables into blockquote warnings, and keep filter matrices/notes in sync with the live Redoc formatting.
 - Response schemas now include explicit model names, constraint-aware type strings, cleaner property tables, nested detail links, and a note explaining why live-site request/response samples are not mirrored in the markdown export.
 
+### Removed
+
+- Legacy `.github/scripts/check_and_update_docs.py` workflow helper in favor of the dedicated v1 and v2 sync pipeline scripts.
+
 ## [1.1.0] - 2025-11-10
 
 ### Added

README.md

@@ -46,6 +46,7 @@ The original Affinity API documentation is hosted on dynamic, interactive websit
 
 - 📄 [View on GitHub](https://github.com/yaniv-golan/affinity-api-docs/blob/main/docs/v2/affinity_api_docs.md)
 - 🔗 [Raw Markdown](https://raw.githubusercontent.com/yaniv-golan/affinity-api-docs/main/docs/v2/affinity_api_docs.md)
+- 🔗 [OpenAPI JSON](https://raw.githubusercontent.com/yaniv-golan/affinity-api-docs/main/docs/v2/openapi.json)
 
 ### Accessing Raw Markdown
 
@@ -92,20 +93,20 @@ cd affinity-api-docs/docs/v1
 - ✅ Tag-based chapters, request/response tables, schema appendix, and error reference
 - ✅ Example `curl` requests synthesized for every endpoint
 - 📂 Location: `docs/v2/affinity_api_docs.md` (do **not** edit manually)
+- 📂 OpenAPI spec: `docs/v2/openapi.json` (do **not** edit manually)
 
 ## Automated Updates & Manual Workflow
 
 ### GitHub Actions
 
-- **Sync Affinity v1 Docs** (`.github/workflows/check-docs-updates.yml`)
+- **Sync Affinity Docs** (`.github/workflows/check-docs-updates.yml`)
   - Runs daily at 00:00 UTC (plus manual `workflow_dispatch`)
-  - Executes `python tools/v1_sync_pipeline/sync_v1_docs.py --fail-on-diff`
-  - Runs `python tools/v1_sync_pipeline/qa/check_links.py docs/v1/affinity_api_docs.md`
-  - Uses `peter-evans/create-pull-request` to open a PR whenever the canonical markdown changes
+  - Executes both sync pipelines and link-checks the generated markdown
+  - Uses `peter-evans/create-pull-request` to open a PR whenever the generated outputs change
 - **Tests** (`.github/workflows/tests.yml`)
   - Runs on push/PR
   - Re-runs the sync script with `--fail-on-diff` to ensure the repo already contains the generated output
-  - Executes the pytest suite (coverage over `tools/v1_sync_pipeline`)
+  - Executes the pytest suite (coverage over `tools/v1_sync_pipeline` and `tools/v2_sync_pipeline`)
 
 ### Manual Sync Steps
 
@@ -161,7 +162,9 @@ affinity-api-docs/
 ├── docs/
 │   ├── v1/               # API v1 documentation
 │   │   └── affinity_api_docs.md        # Auto-generated canonical doc
-│   ├── v2/               # API v2 documentation (planned)
+│   ├── v2/               # API v2 documentation
+│   │   ├── affinity_api_docs.md        # Auto-generated canonical doc
+│   │   └── openapi.json                # Auto-generated OpenAPI spec
 │   └── development/      # Development documentation
 │       ├── TESTING.md    # Testing guide
 │       └── TEST_RESULTS.md  # Test results

REPOSITORY_STRUCTURE.md

@@ -33,6 +33,16 @@ This document explains the repository structure and why files are organized this
 
 **Why here?**: Development documentation belongs in `docs/`, separate from user-facing documentation.
 
+### `docs/v1/` and `docs/v2/` - Generated Documentation Outputs
+
+- **Purpose**: Houses generated artifacts that mirror the official Affinity API documentation.
+- **Key files**:
+  - `docs/v1/affinity_api_docs.md` – generated by `tools/v1_sync_pipeline/sync_v1_docs.py`
+  - `docs/v2/affinity_api_docs.md` – generated by `tools/v2_sync_pipeline/sync_v2_docs.py`
+  - `docs/v2/openapi.json` – generated by `tools/v2_sync_pipeline/sync_v2_docs.py` (stable OpenAPI download)
+
+**Why here?**: These are the canonical, committed outputs of the sync pipelines. They should never be edited manually.
+
 ### `tools/v1_sync_pipeline/` - Production Sync + QA Tooling
 
 - **Purpose**: Houses the production-ready sync pipeline and QA scripts
@@ -43,6 +53,16 @@ This document explains the repository structure and why files are organized this
 
 **Why here?**: Separates long-lived automation from discarded extraction experiments (`scripts/` directory has been removed).
 
+### `tools/v2_sync_pipeline/` - Production v2 Sync Pipeline
+
+- **Purpose**: Fetches the Redocly state payload from https://developer.affinity.co/ and generates the v2 markdown mirror + a stable OpenAPI JSON artifact.
+- **Contents**:
+  - `sync_v2_docs.py` – Fetches Redoc shell HTML + state JS, extracts OpenAPI JSON, renders markdown, writes outputs under `docs/v2/`
+  - `openapi_loader.py` – Discovers the `redocly-state-*.js` asset and extracts the embedded OpenAPI document
+  - `markdown_renderer.py` – Converts the OpenAPI spec into readable markdown sections + appendices
+
+**Why here?**: Keeps v2 automation co-located with v1, using the same “generated outputs, never hand-edit” approach.
+
 ### `requirements-ci.txt` - CI Dependencies
 
 - **Purpose**: Python dependencies needed for CI/CD workflows
@@ -73,6 +93,7 @@ This document explains the repository structure and why files are organized this
 | Test docs | `docs/development/` | Development docs |
 | CI scripts | `.github/scripts/` | GitHub-specific (only `validate_docs_structure.py` remains) |
 | Sync pipeline | `tools/v1_sync_pipeline/` | Production automation + QA helpers |
+| Sync pipeline (v2) | `tools/v2_sync_pipeline/` | Production automation for v2 docs |
 | Workflows | `.github/workflows/` | GitHub Actions |
 | Requirements | `requirements-ci.txt` | Root level, CI-specific |
 | Metadata | `.github/docs-version-*.json` | Workflow state |