docs: add documentation index linking all project docs

README.md

@@ -4,6 +4,13 @@
 
 It provides an interactive interface for exploring directories with the keyboard and returns the selected path at the end of the session so shell wrappers can change the current shell directory.
 
+
+## Documentation
+
+See the documentation index:
+
+docs/index.md
+
 ## Features
 
 - Interactive terminal directory browser

docs/index.md

@@ -0,0 +1,174 @@
+# Documentation Index --- cd-browser
+
+Welcome to the documentation hub for **cd-browser**.
+
+This index helps navigate all technical and project documents included
+in the repository.
+
+------------------------------------------------------------------------
+
+# Project Documentation
+
+## Project Overview
+
+High‑level explanation of the project.
+
+**File**
+
+    docs/project_overview.md
+
+Describes:
+
+-   what the project is
+-   how it works
+-   how to install and use it
+-   repository structure
+
+------------------------------------------------------------------------
+
+# Architecture
+
+Technical explanation of the internal design of the application.
+
+**File**
+
+    docs/architecture.md
+
+Includes:
+
+-   module responsibilities
+-   system architecture
+-   shell integration model
+-   terminal handling
+-   validation pipeline
+
+------------------------------------------------------------------------
+
+# Development Journey
+
+Chronological reconstruction of how the project was built.
+
+**File**
+
+    docs/development-journey.md
+
+Contains:
+
+-   development phases
+-   prompts used with AI agents
+-   problems encountered
+-   solutions applied
+-   decisions taken during development
+
+------------------------------------------------------------------------
+
+# AI Development Playbook
+
+Reusable methodology for building software using AI coding agents.
+
+**File**
+
+    docs/ai-development-playbook.md
+
+Explains:
+
+-   prompt design patterns
+-   agent workflow
+-   validation loops
+-   best practices for AI-assisted programming
+
+------------------------------------------------------------------------
+
+# Functional Specifications
+
+Defines the functional behavior of the application.
+
+**File**
+
+    specs/cd_browser_spec.md
+
+Describes:
+
+-   navigation model
+-   terminal behaviour
+-   keyboard controls
+-   application requirements
+
+------------------------------------------------------------------------
+
+# Template Documentation
+
+Original documentation from the development template used to start the
+project.
+
+**File**
+
+    README_TEMPLATE.md
+
+Preserved for reference.
+
+------------------------------------------------------------------------
+
+# Main Entry Points
+
+The most important project entry points are:
+
+## Project README
+
+    README.md
+
+Provides:
+
+-   project description
+-   installation instructions
+-   shell integration
+
+------------------------------------------------------------------------
+
+# Repository Structure
+
+    cd-browser
+    │
+    ├─ README.md
+    ├─ README_TEMPLATE.md
+    │
+    ├─ docs
+    │   ├─ index.md
+    │   ├─ project_overview.md
+    │   ├─ architecture.md
+    │   ├─ development-journey.md
+    │   └─ ai-development-playbook.md
+    │
+    ├─ specs
+    │   └─ cd_browser_spec.md
+    │
+    ├─ src
+    ├─ tests
+    ├─ scripts
+    │
+    ├─ pyproject.toml
+    └─ Makefile
+
+------------------------------------------------------------------------
+
+# Reading Order Recommendation
+
+For someone new to the project, the recommended reading order is:
+
+1.  `README.md`
+2.  `docs/project_overview.md`
+3.  `docs/architecture.md`
+4.  `specs/cd_browser_spec.md`
+5.  `docs/development-journey.md`
+6.  `docs/ai-development-playbook.md`
+
+------------------------------------------------------------------------
+
+# Purpose of This Document
+
+This index exists to make the repository easier to understand and to
+provide a clear entry point to all documentation.
+
+------------------------------------------------------------------------
+
+End of document.