From 449f133a1ffcce607dd22099e58b433e1d95c67f Mon Sep 17 00:00:00 2001
From: vikingowl <christian@nachtigall.dev>
Date: Fri, 17 Oct 2025 00:41:47 +0200
Subject: [PATCH] docs: add repo map (tree) and generating script

---
 CONTRIBUTING.md         |  4 +++
 README.md               |  1 +
 docs/repo-map.md        | 70 +++++++++++++++++++++++++++++++++++++++++
 scripts/gen-repo-map.sh | 31 ++++++++++++++++++
 4 files changed, 106 insertions(+)
 create mode 100644 docs/repo-map.md
 create mode 100755 scripts/gen-repo-map.sh

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9aa91ca..fe4884d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,6 +10,10 @@ This project and everyone participating in it is governed by the [Owlen Code of
 
 ## How Can I Contribute?
 
+### Repository map
+
+Need a quick orientation before diving in? Start with the curated [repo map](docs/repo-map.md) for a two-level directory overview. If you move folders around, regenerate it with `scripts/gen-repo-map.sh`.
+
 ### Reporting Bugs
 
 This is one of the most helpful ways you can contribute. Before creating a bug report, please check a few things:
diff --git a/README.md b/README.md
index 441adee..325eba0 100644
--- a/README.md
+++ b/README.md
@@ -112,6 +112,7 @@ For more detailed information, please refer to the following documents:
 - **[CHANGELOG.md](CHANGELOG.md)**: A log of changes for each version.
 - **[docs/architecture.md](docs/architecture.md)**: An overview of the project's architecture.
 - **[docs/troubleshooting.md](docs/troubleshooting.md)**: Help with common issues.
+- **[docs/repo-map.md](docs/repo-map.md)**: Snapshot of the workspace layout and key crates.
 - **[docs/provider-implementation.md](docs/provider-implementation.md)**: Trait-level details for implementing providers.
 - **[docs/adding-providers.md](docs/adding-providers.md)**: Step-by-step checklist for wiring a provider into the multi-provider architecture and test suite.
 - **Experimental providers staging area**: [crates/providers/experimental/README.md](crates/providers/experimental/README.md) records the placeholder crates (OpenAI, Anthropic, Gemini) and their current status.
diff --git a/docs/repo-map.md b/docs/repo-map.md
new file mode 100644
index 0000000..aa45653
--- /dev/null
+++ b/docs/repo-map.md
@@ -0,0 +1,70 @@
+# Repo Map
+
+> Generated by `scripts/gen-repo-map.sh`. Regenerate whenever the workspace layout changes.
+
+```text
+.
+├── crates
+│   ├── mcp
+│   │   ├── client
+│   │   ├── code-server
+│   │   ├── llm-server
+│   │   ├── prompt-server
+│   │   └── server
+│   ├── owlen-cli
+│   │   ├── src
+│   │   ├── tests
+│   │   ├── Cargo.toml
+│   │   └── README.md
+│   ├── owlen-core
+│   │   ├── examples
+│   │   ├── migrations
+│   │   ├── src
+│   │   ├── tests
+│   │   ├── Cargo.toml
+│   │   └── README.md
+│   ├── owlen-markdown
+│   │   ├── src
+│   │   └── Cargo.toml
+│   ├── owlen-providers
+│   │   ├── src
+│   │   ├── tests
+│   │   └── Cargo.toml
+│   ├── owlen-tui
+│   │   ├── src
+│   │   ├── tests
+│   │   ├── Cargo.toml
+│   │   └── README.md
+│   └── providers
+│       └── experimental
+├── docs
+│   ├── migrations
+│   ├── CHANGELOG_v1.0.md
+│   ├── adding-providers.md
+│   ├── architecture.md
+│   ├── configuration.md
+│   ├── faq.md
+│   ├── migration-guide.md
+│   ├── phase5-mode-system.md
+│   ├── platform-support.md
+│   ├── provider-implementation.md
+│   ├── testing.md
+│   └── troubleshooting.md
+├── examples
+├── scripts
+│   ├── check-windows.sh
+│   └── gen-repo-map.sh
+├── AGENTS.md
+├── CHANGELOG.md
+├── CODE_OF_CONDUCT.md
+├── CONTRIBUTING.md
+├── Cargo.lock
+├── Cargo.toml
+├── LICENSE
+├── PKGBUILD
+├── README.md
+├── SECURITY.md
+└── config.toml
+
+29 directories, 32 files
+```
diff --git a/scripts/gen-repo-map.sh b/scripts/gen-repo-map.sh
new file mode 100755
index 0000000..a54ff54
--- /dev/null
+++ b/scripts/gen-repo-map.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+OUTPUT_PATH="${1:-${REPO_ROOT}/docs/repo-map.md}"
+
+if ! command -v tree >/dev/null 2>&1; then
+  echo "error: the 'tree' command is required to regenerate the repo map. Install it (e.g., 'sudo pacman -S tree') and re-run this script." >&2
+  exit 1
+fi
+
+EXCLUDES='target|\\.git|\\.github|node_modules|dist|images|themes|dev|\\.venv'
+
+TMP_FILE="$(mktemp)"
+trap 'rm -f "${TMP_FILE}"' EXIT
+
+pushd "${REPO_ROOT}" >/dev/null
+tree -a -L 2 --dirsfirst --prune -I "${EXCLUDES}" > "${TMP_FILE}"
+popd >/dev/null
+
+{
+  printf '# Repo Map\n\n'
+  printf '> Generated by `scripts/gen-repo-map.sh`. Regenerate when the layout changes.\n\n'
+  printf '```text\n'
+  cat "${TMP_FILE}"
+  printf '```\n'
+} > "${OUTPUT_PATH}"
+
+echo "Repo map written to ${OUTPUT_PATH}"