docs: add AI development playbook and architecture documentation

docs/architecture.md

@@ -0,0 +1,191 @@
+# cd-browser Architecture
+
+Author: Saky
+
+This document describes the architecture of the `cd-browser` terminal
+navigation tool.
+
+------------------------------------------------------------------------
+
+# 1. Purpose
+
+`cd-browser` provides a keyboard‑driven terminal interface to explore
+directories and return a selected path to the shell.
+
+It solves a limitation of shells:
+
+A program cannot directly change the parent shell directory.
+
+Instead:
+
+1.  The application returns a path
+2.  A shell wrapper performs `cd`
+
+------------------------------------------------------------------------
+
+# 2. High Level Architecture
+
+The project follows a layered architecture:
+
+CLI Layer ↓ UI Layer ↓ Navigator Layer ↓ Filesystem Layer
+
+History is used by the navigator.
+
+------------------------------------------------------------------------
+
+# 3. Modules
+
+## filesystem.py
+
+Responsibilities:
+
+-   inspect filesystem
+-   list directories
+-   detect children directories
+
+Core structures:
+
+DirectoryEntry
+
+Functions:
+
+list_directories() has_subdirectories()
+
+------------------------------------------------------------------------
+
+## history.py
+
+Handles navigation history.
+
+Features:
+
+-   visit(path)
+-   back()
+-   forward()
+-   select()
+
+Used by navigator.
+
+------------------------------------------------------------------------
+
+## navigator.py
+
+Core state machine of the application.
+
+Tracks:
+
+-   current_path
+-   visible directory entries
+-   selected index
+-   expanded nodes
+
+Handles:
+
+-   entering directories
+-   parent navigation
+-   tree expansion
+-   history integration
+
+------------------------------------------------------------------------
+
+## ui.py
+
+Terminal interface using curses.
+
+Responsibilities:
+
+-   render directory list
+-   highlight selection
+-   process keyboard input
+
+Keys used:
+
+↑ ↓ navigation → expand ← collapse ESC exit
+
+------------------------------------------------------------------------
+
+## cli.py
+
+Application orchestrator.
+
+Responsibilities:
+
+-   create navigator
+-   start terminal UI
+-   capture resulting path
+
+------------------------------------------------------------------------
+
+## main.py
+
+Entrypoint.
+
+Responsibilities:
+
+-   initialize logging
+-   start CLI flow
+-   print final path
+
+------------------------------------------------------------------------
+
+# 4. Shell Integration
+
+Shell wrapper function:
+
+cd\_() { local target target="$(cd_browser)"
+  if [ -n "$target" \] && \[ -d "$target" ]; then
+    cd "$target" fi }
+
+This enables:
+
+cd\_
+
+to change the working directory.
+
+------------------------------------------------------------------------
+
+# 5. Terminal Handling
+
+The application attaches its UI to:
+
+/dev/tty
+
+This allows the UI to function even when stdout is captured by shell
+substitution.
+
+stdout is reserved for:
+
+final directory path
+
+stderr is used for logging.
+
+------------------------------------------------------------------------
+
+# 6. Validation
+
+Quality tools ensure correctness:
+
+black -- formatting\
+ruff -- linting\
+mypy -- type checking\
+pytest -- testing
+
+Commands:
+
+make fix make quality make ci
+
+------------------------------------------------------------------------
+
+# 7. Extensibility
+
+Future improvements:
+
+-   enhanced navigation model
+-   fuzzy search
+-   bookmark directories
+-   persistent history
+-   configuration file
+
+------------------------------------------------------------------------
+
+# End