Initial release: cd-browser v0.1.0

README.md

@@ -0,0 +1,111 @@
+# cd-browser
+
+`cd-browser` is a terminal-native directory navigator for fast filesystem browsing from the command line.
+
+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.
+
+## Features
+
+- Interactive terminal directory browser
+- Keyboard-driven navigation
+- Parent directory entry via `..`
+- Expand and collapse directory trees
+- Session navigation history support in the application state
+- Installable CLI command: `cd_browser`
+
+## Installation
+
+Install the project in user mode:
+
+```bash
+pip install .
+```
+
+For editable local development:
+
+```bash
+pip install -e '.[dev]'
+```
+
+After installation, the application command is:
+
+```bash
+cd_browser
+```
+
+When the interactive session exits, the program prints the final selected directory path.
+
+## Shell Integration For `cd_`
+
+Because a Python subprocess cannot directly change the parent shell directory, use a shell wrapper that captures the final path printed by `cd_browser`.
+
+Bash or Zsh example:
+
+```bash
+cd_() {
+  local target
+  target="$(cd_browser)" || return
+
+  if [ -n "$target" ] && [ -d "$target" ]; then
+    cd "$target"
+  fi
+}
+```
+
+After adding the function to your shell profile, reload it:
+
+```bash
+source ~/.bashrc
+```
+
+Or:
+
+```bash
+source ~/.zshrc
+```
+
+Then use:
+
+```bash
+cd_
+```
+
+## Uninstall
+
+If the project was installed with `pip`, remove it with:
+
+```bash
+pip uninstall cd-browser
+```
+
+If you also added the `cd_` shell wrapper, remove that function from your shell profile and reload the shell configuration.
+
+## Developer Setup
+
+Recommended setup:
+
+```bash
+make dev
+```
+
+Run the application in development mode:
+
+```bash
+python -m app.main
+```
+
+Useful development commands:
+
+```bash
+make fix
+make quality
+make run
+```
+
+## Template Origin
+
+This project was created from the Python AI Dev Template.
+
+The original template documentation has been preserved in `README_TEMPLATE.md` so the project-specific README can focus on `cd-browser` usage and development.
+
+For the original template setup, conventions, and generic workflow notes, see `README_TEMPLATE.md`.