From 32dbd1fc5d3db1aaa36e0602733d260e16d5cac3 Mon Sep 17 00:00:00 2001
From: dimgigov <gigov@gigov.org>
Date: Mon, 11 May 2026 14:45:50 +0300
Subject: [PATCH] docs: fix AI-First heading visibility and index navigation

- Remove leading blank line and --- separator before H1 in
  03-ai-integration.md (EN + BG) to prevent markdown rendering issues
- Fix broken language switcher links in en/index.md and bg/index.md
- Add documentation TOC tables to both index files for proper navigation
---
 docs/bg/03-ai-integration.md |  3 ---
 docs/bg/index.md             | 14 +++++++++++++-
 docs/en/03-ai-integration.md |  3 ---
 docs/en/index.md             | 14 +++++++++++++-
 4 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/docs/bg/03-ai-integration.md b/docs/bg/03-ai-integration.md
index a5666e3..bec8f3d 100644
--- a/docs/bg/03-ai-integration.md
+++ b/docs/bg/03-ai-integration.md
@@ -1,8 +1,5 @@
-
 [← Към индекса](index.md)
 
----
-
 # AI-First Философия на Дизайна
 
 ## Защо AI-First?
diff --git a/docs/bg/index.md b/docs/bg/index.md
index 88553e7..aa6c39c 100644
--- a/docs/bg/index.md
+++ b/docs/bg/index.md
@@ -7,7 +7,7 @@
 
 | 🇧🇬 Български | 🇬🇧 English |
 |-------------|------------|
-| [Българска Документация](bg/index.md) | [English Documentation](en/index.md) |
+| [Българска Документация](index.md) | [English Documentation](../en/index.md) |
 
 ## Бързи връзки
 
@@ -17,6 +17,18 @@
 - **AI Интеграция:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
 - **Test Suite:** [Съвместимост с Clojure Test Suite](07-clojure-test-suite.md) — между-диалектно тестване за съответствие
 
+## Документация
+
+| # | Тема | Файл |
+|---|------|------|
+| 1 | Първи стъпки | [01-getting-started.md](01-getting-started.md) |
+| 2 | Архитектура | [02-architecture.md](02-architecture.md) |
+| 3 | AI Интеграция | [03-ai-integration.md](03-ai-integration.md) |
+| 4 | API Справочник | [04-api-reference.md](04-api-reference.md) |
+| 5 | Ръководство за потребителя | [05-user-guide.md](05-user-guide.md) |
+| 6 | Пътна карта | [06-roadmap.md](06-roadmap.md) |
+| 7 | Clojure Test Suite | [07-clojure-test-suite.md](07-clojure-test-suite.md) |
+
 ## Защо Bara Lang?
 
 За разлика от всеки друг Clojure диалект, Bara Lang има **нула зависимост от Java екосистемата** — нито JVM, нито GraalVM, нито Google Closure Compiler, нито Java стандартна библиотека.
diff --git a/docs/en/03-ai-integration.md b/docs/en/03-ai-integration.md
index c451b33..4faf331 100644
--- a/docs/en/03-ai-integration.md
+++ b/docs/en/03-ai-integration.md
@@ -1,8 +1,5 @@
-
 [← Back to Index](index.md)
 
----
-
 # AI-First Design Philosophy
 
 ## Why AI-First?
diff --git a/docs/en/index.md b/docs/en/index.md
index 145f9ec..98a300b 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -7,7 +7,7 @@
 
 | 🇬🇧 English | 🇧🇬 Български |
 |------------|-------------|
-| [English Documentation](en/index.md) | [Българска Документация](bg/index.md) |
+| [English Documentation](index.md) | [Българска Документация](../bg/index.md) |
 
 ## Quick Links
 
@@ -17,6 +17,18 @@
 - **AI Integration:** DeepSeek API, OpenAI-compatible, Xiaomi MiMo
 - **Test Suite:** [Clojure Test Suite Compatibility](07-clojure-test-suite.md) — cross-dialect compliance testing
 
+## Documentation
+
+| # | Topic | File |
+|---|-------|------|
+| 1 | Getting Started | [01-getting-started.md](01-getting-started.md) |
+| 2 | Architecture | [02-architecture.md](02-architecture.md) |
+| 3 | AI Integration | [03-ai-integration.md](03-ai-integration.md) |
+| 4 | API Reference | [04-api-reference.md](04-api-reference.md) |
+| 5 | User Guide | [05-user-guide.md](05-user-guide.md) |
+| 6 | Roadmap | [06-roadmap.md](06-roadmap.md) |
+| 7 | Clojure Test Suite | [07-clojure-test-suite.md](07-clojure-test-suite.md) |
+
 ## Why Bara Lang?
 
 Unlike every other Clojure dialect, Bara Lang has **zero dependency on the Java ecosystem** — no JVM, no GraalVM, no Google Closure Compiler, no Java standard library.