Skip to content

Docs overhaul: restructure, QA fixes, data processing labels, vulnerability reduction#63

Open
andrej-schreiner wants to merge 1 commit intomainfrom
claude/objective-edison
Open

Docs overhaul: restructure, QA fixes, data processing labels, vulnerability reduction#63
andrej-schreiner wants to merge 1 commit intomainfrom
claude/objective-edison

Conversation

@andrej-schreiner
Copy link
Copy Markdown
Collaborator

@andrej-schreiner andrej-schreiner commented Mar 20, 2026

Summary

Complete documentation overhaul — restructured site architecture, QA-tested every API example against the live AIFS API, fixed UI issues, added data processing location info, and reduced npm vulnerabilities by 84%.

95 files changed | +9,426 | -14,392

📁 Documentation Restructure

Before: Flat numbered files (01_Overview.md, 04_Model Serving/API Usage Guide.md, etc.)
After: Topic-based hierarchy matching industry-standard API docs:

docs/
├── overview.mdx
├── getting-started/    (authentication, quickstart, models)
├── guides/             (chat, streaming, embeddings, multimodal, audio, reasoning, function-calling, image-gen, fine-tuning, async, visual-rag)
├── integrations/       (langchain, llama-index)
├── smartchat/          (overview, api-reference, global-chat, local-chat)
├── reference/          (api-endpoints, error-codes, rate-limits)
└── faq.mdx
  • Added Docusaurus versioning (versions.json, versioned_docs/version-1.0.0/, versioned_sidebars/)
  • Sidebar reorganized with collapsible sections

🔧 UI / Design Fixes

Issue Fix
Dark mode toggle broken switchMode.js: replaced DOMContentLoaded (fires before React) with MutationObserver; also sets data-theme on <html> for Infima CSS vars
Version dropdown malformed Replaced <scale-dropdown-select> with native <select> + Telekom Scale-styled CSS
"Why AI Foundation Services?" section Removed (not useful)
Half-black page in dark mode Fixed CSS color inheritance

📝 API Documentation Fixes (QA-tested against live API)

Every code example was tested with a real API key. Issues found and fixed:

Broken Model Names

Location Old (broken) New (verified)
quickstart, multimodal Qwen2.5-VL-72B-Instruct (410 Gone) Qwen3-VL-30B-A3B-Instruct-FP8
fine-tuning Meta-Llama-3.1-8B-Instruct (not found) Llama-3.3-70B-Instruct
async-requests text-embedding-3-small (not found) text-embedding-bge-m3

Runtime Crashes

  • Streaming examples — AIFS sends chunks with empty choices array → IndexError. Added if not chunk.choices: continue guard to all 3 examples.

Incorrect Documentation

Issue Fix
Error format {"error":{"message":"..."}} Corrected to {"detail":"..."} (AIFS actual format)
Rate limit headers on all models Only on Azure models (GPT, o-series). Changed example to gpt-4.1, added note
Embedding dims jina-embeddings-v2-base-de: 1024 Actually 768. Fixed
Audio filter model_type="NLP" returns 0 Changed to "STT" (3 occurrences)
Models JSON example with zero values Replaced with real Llama-3.3-70B-Instruct API response
"Hello from AIFS!" in curl Removed ! — CloudWAF blocks exclamation marks in JSON body
Wikipedia image URL → 403 Replaced with Unsplash URL (4 occurrences)
Bare OPENAI_API_KEY in code Fixed to os.getenv('OPENAI_API_KEY')

🏷️ Available Models Overhaul

  • Removed 8 offline models: gpt-4.1-nano, gpt-4o-mini, GPT-5-Codex, gpt-5-nano, Mistral-Large-2411, Mistral-Medium-3, o1, text-embedding-ada-002
  • Added 2 missing models: gpt-5.2, Qwen3-Coder-30B-A3B-Instruct-FP8
  • 32 models total, all verified live against the API
  • Sort order: GPT OSS 120B (T-Cloud flagship) → T-Cloud open-source → newest hyperscaler → embeddings/audio
  • OTC → T-Cloud rebrand in provider display
  • Data Processing location added to every card:
    • T-Cloud models: Germany 🇩🇪
    • Hyperscaler models: EU 🇪🇺

🔒 Vulnerability Reduction (113 → 18)

Change Vulns
Before 113 (7 critical, 56 high, 47 moderate)
Remove unused docusaurus v1 package → 31
Remove duplicate docusaurus-plugin-search-local → 30
npm audit fix → 18
After 18 (18 high — all serialize-javascript via Docusaurus internals)

All critical and moderate vulnerabilities eliminated. Remaining 18 require upstream Docusaurus fix.

🧪 Test Plan

  • Visit every docs page — verify code examples render correctly
  • Test dark mode toggle — should switch theme on Scale + Docusaurus content
  • Test version dropdown — should show versions and navigate
  • Check /#available-models — GPT OSS 120B first, 32 models, "Data Processing: Germany/EU" labels
  • Run quickstart curl example with API key
  • Run streaming Python example — should not crash
  • Verify gpt-5.2 in model cards
  • Check SmartChat pages — contact email should be ai@t-systems.com

👥 Reviewers

🤖 Generated with Claude Code

@claude
fix: add data processing location to model cards, reduce npm vulnerab…
18721f0 
…ilities

- Model cards now show both Server Location and Data Processing
  - T-Cloud models: Data Processing in Germany
  - Hyperscaler models: Data Processing in EU
- Overview text updated to clarify Germany vs EU distinction
- Removed unused docusaurus v1 and duplicate search plugin (113→18 vulns)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@niderhoff
Copy link
Copy Markdown
Collaborator

niderhoff commented Mar 23, 2026 •
edited
Loading

Can you please ask claude to fix bun.lock as well, not only package.json since this project uses bun as primary package manager.

@niderhoff niderhoff mentioned this pull request Apr 5, 2026
Draft
@niderhoff
Copy link
Copy Markdown
Collaborator

niderhoff commented Apr 5, 2026

included in #65

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@tattrongvu tattrongvu Awaiting requested review from tattrongvu

@niderhoff niderhoff Awaiting requested review from niderhoff

@ManvendraSinghJii ManvendraSinghJii Awaiting requested review from ManvendraSinghJii

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@andrej-schreiner @niderhoff
⚡