From 0b789b77e9f53d9565680433ea404c11b427b737 Mon Sep 17 00:00:00 2001
From: Saky <sakydogalo@gmail.com>
Date: Sat, 14 Mar 2026 17:55:28 +0100
Subject: [PATCH] docs: add project overview

---
 docs/project_overview.md | 243 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 243 insertions(+)
 create mode 100644 docs/project_overview.md

diff --git a/docs/project_overview.md b/docs/project_overview.md
new file mode 100644
index 0000000..050b7e2
--- /dev/null
+++ b/docs/project_overview.md
@@ -0,0 +1,243 @@
+# Project Overview --- cd-browser
+
+Author: Saky
+
+This document provides a quick introduction to the **cd-browser**
+project and guides readers through the repository structure,
+documentation, and development workflow.
+
+------------------------------------------------------------------------
+
+# What is cd-browser?
+
+`cd-browser` is a **terminal-based directory navigator** that allows
+users to browse directories interactively and then change the working
+directory of their shell.
+
+It solves a common shell limitation:
+
+A program cannot directly change the directory of its parent shell.
+
+The solution is:
+
+1.  The program returns a directory path.
+2.  A shell wrapper function performs the actual `cd`.
+
+------------------------------------------------------------------------
+
+# Example usage
+
+``` bash
+cd_
+```
+
+The command launches an interactive terminal browser.
+
+After navigating and exiting:
+
+-   the selected directory is returned
+-   the shell wrapper changes the working directory.
+
+------------------------------------------------------------------------
+
+# Key Features
+
+-   interactive terminal navigation
+-   tree-style directory browsing
+-   expandable directories
+-   keyboard-driven interface
+-   directory navigation history
+-   clean shell integration
+-   installable as a CLI tool
+-   tested Python codebase
+-   automated formatting and linting
+
+------------------------------------------------------------------------
+
+# Repository Structure
+
+    cd-browser/
+
+    README.md                → main project documentation
+    README_TEMPLATE.md       → original template documentation
+
+    docs/
+        development-journey.md
+        ai-development-playbook.md
+        architecture.md
+
+    specs/
+        cd_browser_spec.md
+
+    src/
+        app/
+            cli.py
+            filesystem.py
+            history.py
+            navigator.py
+            ui.py
+            main.py
+
+    tests/
+
+    scripts/
+
+    pyproject.toml
+    Makefile
+
+------------------------------------------------------------------------
+
+# Documentation Guide
+
+The repository includes several documents explaining the project from
+different perspectives.
+
+## README.md
+
+Quick introduction and installation instructions.
+
+## specs/
+
+Functional specifications of the application.
+
+## docs/development-journey.md
+
+Explains how the project was built step-by-step using AI coding agents.
+
+## docs/ai-development-playbook.md
+
+Reusable methodology for building applications using AI development
+workflows.
+
+## docs/architecture.md
+
+Technical architecture of the application.
+
+------------------------------------------------------------------------
+
+# Installation
+
+Clone the repository:
+
+``` bash
+git clone https://gitea.sakydogalo.es/saky/cd-browser.git
+cd cd-browser
+```
+
+Install the tool:
+
+``` bash
+pip install .
+```
+
+------------------------------------------------------------------------
+
+# Shell Integration
+
+Add this function to your shell configuration (`~/.zshrc`):
+
+``` bash
+cd_() {
+  local target
+  target="$(cd_browser)"
+  if [ -n "$target" ] && [ -d "$target" ]; then
+    cd "$target"
+  fi
+}
+```
+
+Reload the shell:
+
+``` bash
+source ~/.zshrc
+```
+
+Now you can run:
+
+``` bash
+cd_
+```
+
+------------------------------------------------------------------------
+
+# Development Setup
+
+For contributors or developers:
+
+``` bash
+make dev
+source .venv/bin/activate
+```
+
+Run the application:
+
+``` bash
+python -m app.main
+```
+
+------------------------------------------------------------------------
+
+# Quality and Validation
+
+The project uses automated tools to ensure code quality.
+
+Tools:
+
+-   black (formatting)
+-   ruff (linting)
+-   mypy (type checking)
+-   pytest (testing)
+
+Commands:
+
+``` bash
+make fix
+make quality
+make ci
+```
+
+------------------------------------------------------------------------
+
+# AI-Assisted Development
+
+This project was built using a structured **AI-assisted development
+workflow**.
+
+Key ideas:
+
+-   architecture defined by a human
+-   AI agents used for focused implementation tasks
+-   strict validation loops
+-   small scoped prompts
+
+More information:
+
+    docs/ai-development-playbook.md
+
+------------------------------------------------------------------------
+
+# Status
+
+Current version:
+
+    v0.1.0
+
+The project is stable and functional as a minimal terminal directory
+navigator.
+
+Future improvements may include:
+
+-   improved navigation model
+-   fuzzy search
+-   bookmarks
+-   persistent history
+
+------------------------------------------------------------------------
+
+# License
+
+See the LICENSE file.
+
+------------------------------------------------------------------------
+
+End of document.