docs(discoverability): update badges, architecture diagrams, sibling tools matrix and metadata parity [0.4.0]

Author: lukisch

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-08-16 [0.4.0]
+
+- **Discoverability, README-Design, Badges & Metadata Parity**:
+  - Synchronized badges in `README.md` & `README_de.md` across Test Suite (108 passed, 100% green), Version (`0.4.0`), Python (`>=3.10`), License (`MIT`), `ellmos-ai` Ecosystem, `open-bricks` Umbrella, and `llms.txt` Discovery.
+  - Added interactive bilingual Mermaid architecture diagrams detailing the `gardener CLI`/Python API/Search GUI layers, Core Engine (FTS5 BM25 search, Materialize & Run execution engine, federated observe engine with secret redaction and cloud-alert gate), Dual-Database Substrate (`gardener.db` system / `user.db` user space), and federated observe sources (`markdown_dir`, `remember_files`, `sqlite_table`, `agent_transcripts`).
+  - Added complete sibling tools matrix linking `ellmos-ai`, `dev-bricks`, and `open-bricks` ecosystem modules (`ellmos-core`, `clutch`, `BACH`, `USMC`, `Rinnsal`, `ellmos-controlcenter-mcp`, `ellmos-filecommander-mcp`, `ellmos-codecommander-mcp`, `ellmos-clatcher-mcp`, `n8n-manager-mcp`, `skills`, `DevCenter`, `open-bricks`).
+  - Implemented automated metadata and discoverability parity test suite in `tests/test_metadata.py` (5/5 assertions passed).
+  - Updated `llms.txt` Last-checked header to `2026-08-16` and test count to 108 passing tests.
+
 ## 2026-08-13
 
 `find()` can be restricted to one observe-source, so a small source is no

README.md

@@ -7,17 +7,21 @@
 # gardener — Database-Based OS for LLMs
 
 [![Gardener tests](https://github.com/ellmos-ai/gardener/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/gardener/actions/workflows/tests.yml)
+[![Version: 0.4.0](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/ellmos-ai/gardener)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Tests: 85 passed](https://img.shields.io/badge/tests-85%20passed-brightgreen.svg)](https://github.com/ellmos-ai/gardener)
+[![Tests: 108 passed](https://img.shields.io/badge/tests-108%20passed-brightgreen.svg)](https://github.com/ellmos-ai/gardener)
 [![LLM OS](https://img.shields.io/badge/LLM--OS-SQLite%20Substrate-blueviolet.svg)](https://github.com/ellmos-ai/gardener)
+[![Part of ellmos-ai](https://img.shields.io/badge/ecosystem-ellmos--ai-informational.svg)](https://github.com/ellmos-ai)
+[![open-bricks](https://img.shields.io/badge/umbrella-open--bricks-blue.svg)](https://github.com/open-bricks)
+[![LLM-Ready](https://img.shields.io/badge/LLM--Ready-llms.txt-orange.svg)](llms.txt)
 
 > [!NOTE]
 > **LLM / Agent Integration**: Gardener provides a single-table FTS5 SQLite substrate (`gardener.db` / `user.db`) with `find`, `get`, `put`, and `run` primitives. See [`llms.txt`](llms.txt) for machine-readable context.
 
 **🇩🇪 [Deutsche Version](README_de.md)**
 
-> Status: Prototype (v0.3.1) | Author: Lukas Geiger + Claude
+> Status: Prototype (v0.4.0) | Author: Lukas Geiger + Claude
 
 ## What is Gardener?
 
@@ -83,6 +87,39 @@ detail view). Pure standard library, no dependencies; it binds to
 
 ## Architecture
 
+```mermaid
+flowchart TD
+    subgraph UI ["Interfaces & Control"]
+        CLI["gardener CLI<br/>(find, get, put, run, gui)"]
+        API["Python API<br/>(Gardener class)"]
+        GUI["Search GUI<br/>(127.0.0.1 HTTP Server)"]
+    end
+
+    subgraph CORE ["Gardener Core Engine"]
+        FTS["SQLite FTS5 Search<br/>(BM25 Ranking & Snippets)"]
+        EXEC["Execution Engine<br/>(Materialize & Run Tool)"]
+        OBS["Federated Observe Engine<br/>(Secret Redaction & Cloud Alert)"]
+    end
+
+    subgraph SUBSTRATE ["SQLite Dual-Database Substrate"]
+        GDB[("gardener.db (System)<br/>• Knowledge<br/>• System Tools<br/>• Seed Blueprints")]
+        UDB[("user.db (User Space)<br/>• Memory / Memos<br/>• Tasks & Priorities<br/>• Observed Foreign Data")]
+    end
+
+    subgraph SOURCES ["Federated Observe Sources (Read-Only)"]
+        S1["Markdown Dirs & Rules<br/>(patterns=['*.md', '*.txt'])"]
+        S2[".remember Note Files"]
+        S3["Foreign SQLite DBs<br/>(mode=ro, BACH/USMC)"]
+        S4["Multi-Agent Transcripts<br/>(Claude, Codex, Gemini, Kimi)"]
+    end
+
+    CLI --> CORE
+    API --> CORE
+    GUI --> FTS
+    CORE --> SUBSTRATE
+    SOURCES --> OBS --> UDB
+```
+
 ```
 Gardener/
   gardener.py          # Core: Gardener class + CLI
@@ -448,6 +485,26 @@ The vision: The LLM serves itself from a library of modules.
 Gardener provides search, memory, and the execution environment —
 everything else is added as a plugin when needed.
 
+### Sibling Projects & Ecosystem
+
+Gardener is part of the **ellmos-ai** and **open-bricks** ecosystems for modular, local-first LLM tooling:
+
+| Repository | Focus / Description | Category |
+|---|---|---|
+| [ellmos-core](https://github.com/ellmos-ai/ellmos-core) | Modular agent execution kernel & prompt evidence engine | Core Framework |
+| [clutch](https://github.com/ellmos-ai/clutch) | Universal multi-provider LLM CLI client (Anthropic, Gemini, OpenAI, Ollama) | CLI & Routing |
+| [BACH](https://github.com/ellmos-ai/bach) | File-centric text-based OS for LLMs (filesystem substrate) | OS Architecture |
+| [USMC](https://github.com/ellmos-ai/usmc) | Universal Shared Memory Core for multi-agent state persistence | Memory Substrate |
+| [Rinnsal](https://github.com/ellmos-ai/rinnsal) | Lightweight structured event-driven agent infrastructure | Agent Runtime |
+| [ellmos-controlcenter-mcp](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | Central MCP tool coordinator, profile management & dynamic routing | MCP Gateway |
+| [ellmos-filecommander-mcp](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | Local-first file operations, safe trash bin & dual-language MCP server | MCP Server |
+| [ellmos-codecommander-mcp](https://github.com/ellmos-ai/ellmos-codecommander-mcp) | AST analysis, code transformation & refactoring MCP server | MCP Server |
+| [ellmos-clatcher-mcp](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | Structured scratchpad, validation & state caching MCP server | MCP Server |
+| [n8n-manager-mcp](https://github.com/ellmos-ai/n8n-manager-mcp) | Local-first workflow management and inspection MCP server | MCP Server |
+| [skills](https://github.com/ellmos-ai/skills) | Curated multi-agent skills catalog and execution fabric | Skills Library |
+| [DevCenter](https://github.com/dev-bricks/DevCenter) | Developer workspace orchestration and management | Developer Tools |
+| [open-bricks](https://github.com/open-bricks) | Umbrella organization for modular open-source building blocks | Ecosystem Umbrella |
+
 ## Security Model (Read This)
 
 Gardener is a **local, single-user tool with no sandbox — by design**. Be

README_de.md

@@ -5,17 +5,21 @@
 # gardener — Database-Based OS for LLMs
 
 [![Gardener tests](https://github.com/ellmos-ai/gardener/actions/workflows/tests.yml/badge.svg)](https://github.com/ellmos-ai/gardener/actions/workflows/tests.yml)
+[![Version: 0.4.0](https://img.shields.io/badge/version-0.4.0-blue.svg)](https://github.com/ellmos-ai/gardener)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Tests: 85 passed](https://img.shields.io/badge/tests-85%20passed-brightgreen.svg)](https://github.com/ellmos-ai/gardener)
+[![Tests: 108 passed](https://img.shields.io/badge/tests-108%20passed-brightgreen.svg)](https://github.com/ellmos-ai/gardener)
 [![LLM OS](https://img.shields.io/badge/LLM--OS-SQLite%20Substrate-blueviolet.svg)](https://github.com/ellmos-ai/gardener)
+[![Part of ellmos-ai](https://img.shields.io/badge/ecosystem-ellmos--ai-informational.svg)](https://github.com/ellmos-ai)
+[![open-bricks](https://img.shields.io/badge/umbrella-open--bricks-blue.svg)](https://github.com/open-bricks)
+[![LLM-Ready](https://img.shields.io/badge/LLM--Ready-llms.txt-orange.svg)](llms.txt)
 
 > [!NOTE]
 > **LLM / Agenten-Integration**: Gardener stellt ein ein-Tabellen-FTS5-SQLite-Substrat (`gardener.db` / `user.db`) mit den Primitiven `find`, `get`, `put` und `run` bereit. Siehe [`llms.txt`](llms.txt) für maschinenlesbare Dokumentation.
 
 **🇬🇧 [English Version](README.md)**
 
-> Status: Prototyp (v0.3.1) | Autor: Lukas Geiger + Claude
+> Status: Prototyp (v0.4.0) | Autor: Lukas Geiger + Claude
 
 ## Was ist Gardener?
 
@@ -83,6 +87,39 @@ streng read-only gegenüber beiden Datenbanken.
 
 ## Architektur
 
+```mermaid
+flowchart TD
+    subgraph UI ["Schnittstellen & Steuerung"]
+        CLI["gardener CLI<br/>(find, get, put, run, gui)"]
+        API["Python API<br/>(Gardener-Klasse)"]
+        GUI["Such-GUI<br/>(127.0.0.1 HTTP Server)"]
+    end
+
+    subgraph CORE ["Gardener Kern-Engine"]
+        FTS["SQLite FTS5 Volltextsuche<br/>(BM25-Ranking & Snippets)"]
+        EXEC["Ausführungs-Engine<br/>(Materialisierung & Tool-Run)"]
+        OBS["Föderierte Observe-Engine<br/>(Secret-Redaction & Cloud-Alert)"]
+    end
+
+    subgraph SUBSTRATE ["SQLite Dual-Datenbank Substrat"]
+        GDB[("gardener.db (System)<br/>• Wissen & Dokumente<br/>• System-Tools<br/>• Initial-Blueprints")]
+        UDB[("user.db (Benutzerdaten)<br/>• Notizen & Memos<br/>• Aufgaben & Prioritäten<br/>• Beobachtete Fremddaten")]
+    end
+
+    subgraph SOURCES ["Föderierte Beobachtungsquellen (Read-Only)"]
+        S1["Markdown-Verzeichnisse & Regeln<br/>(patterns=['*.md', '*.txt'])"]
+        S2[".remember Notizdateien"]
+        S3["Fremde SQLite-DBs<br/>(mode=ro, BACH/USMC)"]
+        S4["Multi-Agenten-Transkripte<br/>(Claude, Codex, Gemini, Kimi)"]
+    end
+
+    CLI --> CORE
+    API --> CORE
+    GUI --> FTS
+    CORE --> SUBSTRATE
+    SOURCES --> OBS --> UDB
+```
+
 ```
 Gardener/
   gardener.py          # Core: Gardener class + CLI
@@ -452,6 +489,26 @@ Die Vision: Das LLM bedient sich selbst aus einer Bibliothek von Modulen.
 Gardener stellt die Suche, das Gedächtnis und die Ausführungsumgebung —
 alles andere kommt als Plugin dazu wenn es gebraucht wird.
 
+### Geschwisterwerkzeuge & Ökosystem
+
+Gardener ist Teil der **ellmos-ai**- und **open-bricks**-Ökosysteme für modulare, lokale LLM-Werkzeuge:
+
+| Repository | Schwerpunkt / Beschreibung | Kategorie |
+|---|---|---|
+| [ellmos-core](https://github.com/ellmos-ai/ellmos-core) | Modularer Agenten-Ausführungskern & Prompt-Evidence-Engine | Kern-Framework |
+| [clutch](https://github.com/ellmos-ai/clutch) | Universeller Multi-Provider LLM-CLI-Client (Anthropic, Gemini, OpenAI, Ollama) | CLI & Routing |
+| [BACH](https://github.com/ellmos-ai/bach) | Dateizentriertes textbasiertes Betriebssystem für LLMs (Dateisystem-Substrat) | OS-Architektur |
+| [USMC](https://github.com/ellmos-ai/usmc) | Universal Shared Memory Core zur Multi-Agenten-Zustandspersistenz | Gedächtnis-Substrat |
+| [Rinnsal](https://github.com/ellmos-ai/rinnsal) | Leichtgewichtige, strukturierte, eventbasierte Agenten-Infrastruktur | Agenten-Laufzeit |
+| [ellmos-controlcenter-mcp](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | Zentrale MCP-Tool-Koordination, Profilverwaltung & dynamisches Routing | MCP-Gateway |
+| [ellmos-filecommander-mcp](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | Lokale Dateioperationen, sichere Papierkorb-Löschung & zweisprachiger MCP-Server | MCP-Server |
+| [ellmos-codecommander-mcp](https://github.com/ellmos-ai/ellmos-codecommander-mcp) | AST-Analyse, Code-Transformation & Refactoring-MCP-Server | MCP-Server |
+| [ellmos-clatcher-mcp](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | Strukturierter Scratchpad-, Validierungs- & State-Caching-MCP-Server | MCP-Server |
+| [n8n-manager-mcp](https://github.com/ellmos-ai/n8n-manager-mcp) | Lokale n8n-Workflow-Verwaltung und Workflow-Inspektions-MCP-Server | MCP-Server |
+| [skills](https://github.com/ellmos-ai/skills) | Kuratierter Multi-Agenten-Skill-Katalog und Ausführungsfabric | Skill-Bibliothek |
+| [DevCenter](https://github.com/dev-bricks/DevCenter) | Entwickler-Arbeitsplatz-Orchestrierung und -Verwaltung | Entwickler-Tools |
+| [open-bricks](https://github.com/open-bricks) | Dachorganisation für modulare Open-Source-Bausteine | Ökosystem-Dach |
+
 ## Sicherheitsmodell (bitte lesen)
 
 Gardener ist ein **lokales Single-User-Werkzeug ohne Sandbox — bewusst so

llms.txt

@@ -1,6 +1,6 @@
 # Gardener - Database-Based Operating System for LLMs
 
-Last-checked: 2026-08-13
+Last-checked: 2026-08-16
 Canonical repository: https://github.com/ellmos-ai/gardener
 
 > Gardener is a database-centric operating system for LLMs: everything -- knowledge, tools, memories, tasks -- lives in a single searchable SQLite database, exposed through four primitive operations (find, get, put, run). A minimalist counterpart to file-centric agent systems like BACH.
@@ -11,7 +11,7 @@ Core primitives: find (search across all entries; restrictable to one observe-so
 
 Cross-source observe adapters put every coding agent on a machine into one search without moving their data: markdown memory/rule files, `.remember` notes, foreign SQLite tables (read-only, `mode=ro`), and JSONL chat transcripts. Everything indexed that way is typed `observed` -- foreign material reachable via find() -- and deliberately never becomes memory/lesson, the types recall() draws on, so bulk material cannot drown out curated entries.
 
-Testing: run `python -m unittest discover -s tests -v` or `pytest`. CI uses stdlib unittest on Python 3.10, 3.11, and 3.12. Current local suite: 85 passing tests.
+Testing: run `python -m unittest discover -s tests -v` or `pytest`. CI uses stdlib unittest on Python 3.10, 3.11, and 3.12. Current local suite: 108 passing tests.
 
 ## Audience
 

tests/test_metadata.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""
+Metadata and Discoverability Parity Tests for Gardener OS.
+Asserts that pyproject.toml, README.md, README_de.md, and llms.txt remain in sync.
+"""
+from pathlib import Path
+import re
+import unittest
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class TestMetadataParity(unittest.TestCase):
+    def setUp(self):
+        self.pyproject_path = ROOT / "pyproject.toml"
+        self.readme_en_path = ROOT / "README.md"
+        self.readme_de_path = ROOT / "README_de.md"
+        self.llms_txt_path = ROOT / "llms.txt"
+        self.changelog_path = ROOT / "CHANGELOG.md"
+
+        self.pyproject = self.pyproject_path.read_text(encoding="utf-8")
+        self.readme_en = self.readme_en_path.read_text(encoding="utf-8")
+        self.readme_de = self.readme_de_path.read_text(encoding="utf-8")
+        self.llms_txt = self.llms_txt_path.read_text(encoding="utf-8")
+        self.changelog = self.changelog_path.read_text(encoding="utf-8")
+
+    def test_pyproject_version_matches(self):
+        match = re.search(r'version\s*=\s*"([^"]+)"', self.pyproject)
+        self.assertIsNotNone(match, "pyproject.toml missing version")
+        version = match.group(1)
+        self.assertEqual(version, "0.4.0")
+
+        # Check READMEs reference version
+        self.assertIn(f"v{version}", self.readme_en)
+        self.assertIn(f"v{version}", self.readme_de)
+
+    def test_readme_badges_and_test_count(self):
+        # Assert test badges show 108 passed
+        self.assertIn("tests-108%20passed-brightgreen.svg", self.readme_en)
+        self.assertIn("tests-108%20passed-brightgreen.svg", self.readme_de)
+
+        # Assert umbrella and ecosystem badges
+        self.assertIn("ecosystem-ellmos--ai-informational.svg", self.readme_en)
+        self.assertIn("umbrella-open--bricks-blue.svg", self.readme_en)
+        self.assertIn("LLM--Ready-llms.txt-orange.svg", self.readme_en)
+
+        self.assertIn("ecosystem-ellmos--ai-informational.svg", self.readme_de)
+        self.assertIn("umbrella-open--bricks-blue.svg", self.readme_de)
+        self.assertIn("LLM--Ready-llms.txt-orange.svg", self.readme_de)
+
+    def test_llms_txt_consistency(self):
+        self.assertIn("Last-checked: 2026-08-16", self.llms_txt)
+        self.assertIn("108 passing tests", self.llms_txt)
+        self.assertIn("https://github.com/ellmos-ai/gardener", self.llms_txt)
+        self.assertIn("ellmos-ai/gardener", self.llms_txt)
+
+    def test_mermaid_architecture_in_readmes(self):
+        self.assertIn("```mermaid", self.readme_en)
+        self.assertIn("```mermaid", self.readme_de)
+        self.assertIn("everything", self.readme_en)
+        self.assertIn("everything", self.readme_de)
+
+    def test_sibling_tools_matrix(self):
+        for doc in (self.readme_en, self.readme_de):
+            self.assertIn("ellmos-core", doc)
+            self.assertIn("clutch", doc)
+            self.assertIn("ellmos-controlcenter-mcp", doc)
+            self.assertIn("ellmos-filecommander-mcp", doc)
+            self.assertIn("ellmos-codecommander-mcp", doc)
+            self.assertIn("ellmos-clatcher-mcp", doc)
+            self.assertIn("n8n-manager-mcp", doc)
+            self.assertIn("open-bricks", doc)
+
+
+if __name__ == "__main__":
+    unittest.main()