feat: Own and auto-sync the OpenAPI spec extras (RES-14)

[ArmagedonFlamer]

Gives cognee_openapi_spec.json a single owner, then keeps the parts of it that
FastAPI cannot generate honest automatically.

Closes the RES-14 acceptance criteria on spec ownership; the automation is RES-21.

Why

The published spec had two owners that disagreed. tools/sync_release_docs.py
generated it on release. The docs repo's .github/scripts/generate-api-docs.sh
regenerated it on a Wednesday cron and post-processed in everything FastAPI does not
emit — servers, tag descriptions, request examples, security schemes. Both rewrote
the whole file, so every release stripped what the cron added and every Wednesday
put it back.

The extras were also wrong in a way nobody could see. The docs cron published
CookieAuth with cookie name fastapiusersauth — fastapi-users' default — while
cognee's transport sets auth_token (default_transport.cookie_name). The reference
documented a cookie that has never existed.

What changed

1. enhance_spec() in tools/sync_release_docs.py — the docs cron's
post-processing, ported. This script is now the only generator.

The extras live in tools/spec_extras.json rather than as Python literals, because
two of the three are machine-maintained: the fixer does a JSON load-mutate-dump
instead of splicing source. That also sidesteps what forced router_docstring_sync
to pin ruff@0.15.11 "so the bot never fights the formatter" — there is no Python
for the formatter to reflow.

request_examples is keyed by "METHOD /path", not FastAPI's operationId. The
operationId embeds the handler function name (add_api_v1_add_post), so a rename
silently orphaned an example. Path and method are the API contract.

2. spec_extras_sync.yml + check/fix_spec_extras.py — a detect → fix → PR
automation in the shape of router_docstring_sync.

Drift	Treatment
blurb for a tag no route uses	deleted (mechanical)
tag with no blurb	placeholder inserted (mechanical), then written by Claude from the endpoints carrying that tag
example pinned to a route that no longer exists	reported in the PR body
malformed servers entry	reported in the PR body

The last two are not guessed at: choosing a route for a stale sample would attach a
wrong body to a live endpoint, and a base URL is a deployment fact.

This matters because the drift is already real — 21 of 32 route tags have no
description. The 11 that do cover add/cognify/search/delete, the legacy
surface, while remember/recall/forget/improve render as bare sidebar groups.
The automation's first PR clears that backlog.

Verification

Port fidelity. A faithful Python replica of the bash step 3 run against the same
app.openapi() output. Entire diff, 12k lines in:

12343c12343
<         "name": "fastapiusersauth"
---
>         "name": "auth_token"

Against the live published spec, every extra matches byte-for-byte:

servers identical: True
top-level key order identical: True
tags: published 32, mine 32, descriptions agree on all shared: True
  only in published: []      only in mine: []
securitySchemes keys identical: True
all 4 request examples: match=True

The enhance_spec output stayed byte-identical through both the move to JSON and the
re-key.

Pipeline, real app, Claude stubbed:

Detect drift          11/32 described, 21 issues     exit=1 -> drift=true
Fix --describe        43 changes                     exit=0
Convergence re-check  32/32 described, 0 issues      exit=0

Plus, on a cached schema so each case is hermetic: no-op rerun leaves the file
byte-identical, dead key removed, orphaned example reported (exit 1, not fixed),
--warn-only never fails. The PR-lookup logic was exercised against all five states —
no PR / open / closed / merged-only / closed+merged → CREATE, UPDATE,
REOPEN+UPDATE, CREATE, REOPEN+UPDATE.

🤖 Generated with Claude Code

[Vasilije1990]

@ArmagedonFlamer please keep PRs as draft until they pass base checks and ruff

[ArmagedonFlamer]

@ArmagedonFlamer please keep PRs as draft until they pass base checks and ruff

@Vasilije1990 It seems the ruff issue was from the dev branch. After merging updated dev, the ruff issue is gone.