release: 0.2.6 add advanced navigation and contextual open actions

release: 0.2.5 add repository link for PyPI users
release: 0.2.4 fix PyPI README gif rendering
2026-04-04 01:53:00 +02:00 · 2026-04-03 22:51:08 +02:00 · 2026-04-03 21:30:40 +02:00 · 2026-04-03 21:14:23 +02:00 · 2026-04-02 22:38:42 +02:00 · 2026-04-02 21:35:45 +02:00
21 changed files with 2320 additions and 402 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,16 +4,68 @@ All notable changes to this project will be documented in this file.

 The format is based on Keep a Changelog, and this project follows Semantic Versioning.

-## [1.0.0] - 2026-03-14
+## [0.2.6] - 2026-04-04

 ### Added
- Initial release of the Python AI Dev Template
- Universal Python project structure using `src/`
- `pyproject.toml`-based project configuration
- Development tooling with `black`, `ruff`, `mypy`, and `pytest`
- `pre-commit` integration
- `Makefile` with development, quality, and diagnostic commands
- `instructions-agent.md` for AI coding agent guidance
- `.env.example` for environment-based configuration
- README with setup, workflow, and template reuse instructions
- MIT license
+- Incremental filter workflow (`/`) with contextual Enter behavior:
+  - Directories navigate in-place
+  - Files open the app menu
+- File visibility toggle (`a`) to switch between directories-only and mixed view
+- Open-with app menu (`o`) with arrow-key selection (`↑`/`↓`, `Enter`, `Esc`)
+- New opener support for `nano`, `less`, and `bat` for file actions
+- Blocking terminal app execution with UI state restore after exit
+
+### Improved
+- Open-with options are now context-aware (GUI/headless, file/directory) and only shown when executables are available
+- Better handling of paths containing spaces when launching openers
+- Extended README with full controls reference and platform compatibility guidance
+
+## [0.2.5] - 2026-04-03
+
+### Improved
+- Add explicit repository link in README for PyPI users to access the full demo and documentation
+
+## [0.2.4] - 2026-04-03
+
+### Fixed
+- Use absolute demo GIF URL in README so image renders correctly on PyPI
+
+## [0.2.3] - 2026-04-02
+
+### Added
+- Add project demo GIF at `docs/demo.gif`
+- Show GIF demo in README
+
+## [0.2.2] - 2026-04-02
+
+### Fixed
+- Include `cd_browser_post_install.py` in wheel/sdist so `cd_browser_post_install` works after `pip install`
+
+## [0.2.1] - 2026-04-02
+
+### Fixed
+- Prevent crashes when scanning directories with restricted permissions
+- Handle non-interactive post-install runs without failing on EOF
+- Fix shell reload message interpolation in post-install output
+
+### Improved
+- Make post-install shell integration idempotent (avoid duplicate `cd_()` entries)
+- Add test coverage for permission errors and post-install flows
+- Update default application name to `cd-browser`
+
+## [0.2.0] - 2026-04-02
+
+### Added
+- Interactive post-install script (`cd_browser_post_install`) for automatic shell integration
+- Option to automatically add `cd_()` function to ~/.bashrc or ~/.zshrc during installation
+- Improved uninstall instructions in README
+
+### Improved
+- Installation UX: clearer setup process with user prompts
+- Shell integration: better guidance for enabling `cd_` command
+
+### Added
+- Initial release of **cd-browser**
+- Terminal-based directory navigation
+- Interactive directory tree navigation
+- History navigation mode
--- a/README.md
+++ b/README.md
@@ -1,46 +1,119 @@
 # cd-browser

-`cd-browser` is a terminal-native directory navigator for fast filesystem browsing from the command line.
+**Stop typing paths. Browse them.**

-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.
+`cd-browser` is a fast keyboard-driven directory navigator for the terminal.
+It lets you explore directory trees visually and jump to any folder instantly.

+![cd-browser demo](https://gitea.sakydogalo.es/saky/cd-browser/raw/branch/main/docs/demo.gif)
+
+Repository (full demo + docs): https://gitea.sakydogalo.es/saky/cd-browser
+
+## Why cd-browser?
+
+Working in the terminal often means:
+
+- typing long directory paths
+- navigating deep folder trees
+- repeating `cd ..` multiple times
+
+`cd-browser` provides an **interactive terminal UI** that allows you to browse directories with the keyboard and return the selected path directly to your shell.
+
+## Features
+
+- ⌨️ Fully keyboard-driven workflow (`↑` / `↓` / `←` / `→`)
+- 🌲 Expand and collapse directories (`→` to expand/enter, `←` to collapse/back)
+- 📜 Navigation history inside the session (`h` history mode, `b` back, `f` forward)
+- 🔎 Incremental filter mode (`/`, type to filter, `Backspace`, `Esc`)
+- 📄 Toggle file visibility (`a`) to switch between directories-only and mixed view
+- ⚡ Fast jumps in large lists (`PgUp`/`PgDn`, `Home`/`End`, `g`/`G` in normal mode)
+- 🚀 Contextual `open with` menu (`o`) with app detection based on your environment
+- 🔁 Blocking terminal editors restore the UI state when they exit (`nvim`, `nano`, `less`, `bat`)
+- 👀 Toggle hidden entries with `.`
+- 🖥 Native terminal interface
+- 🔁 Works with Bash, Zsh and other shells
+- ⚡ Returns the selected path to the shell (`Enter` to confirm, `Esc` to cancel)
+
+## Controls
+
+Normal mode:
+
+- `↑` / `↓`: Move selection
+- `→`: Expand directory, or enter when already expanded
+- `←`: Collapse directory, or go to parent
+- `Enter`: Confirm selected path and exit
+- `Esc`: Cancel and return the original path
+- `h`: Toggle history mode
+- `b` / `f`: Back / forward in navigation history
+- `.`: Toggle hidden entries
+- `a`: Toggle file visibility
+- `/`: Enter filter mode
+- `o`: Open selected entry with an app
+- `PgUp` / `PgDn`: Page jump
+- `Home` / `End`: Jump to first/last entry
+- `g` / `G`: Jump to first/last entry
+
+Filter mode:
+
+- Type text: Filter visible entries in real time (case-insensitive)
+- `↑` / `↓`: Move inside filtered results
+- `Enter`: Apply filter and perform contextual action:
+  - Directory: navigate into it without exiting `cd_`
+  - File: open app selection menu
+- `Esc`: Exit filter mode and clear query
+- `Backspace`: Remove last filter character
+
+History mode:
+
+- `↑` / `↓`: Move through history entries
+- `Enter`: Jump to selected history path
+- `Esc` or `h`: Exit history mode
+- `PgUp` / `PgDn`, `Home` / `End`: Fast history navigation
+
+Open with menu (`o`):
+
+- `↑` / `↓`: Move between app options
+- `Enter`: Launch selected app
+- `Esc`: Cancel
+
+The menu only shows apps available in your system (`PATH`) and context:
+
+- GUI options (when GUI is available): `code`, system `open`/`xdg-open`
+- Terminal options: `antigravity`, `nvim`, `nano`, `less`, `bat` (as applicable)
+
+## Quick Demo
+
+Run:
+
+```bash
+cd_
+```
+
+Browse directories using the arrow keys and press **Enter** to jump directly to the selected folder.

 ## Documentation

 See the documentation index:

+```
 docs/index.md
-
-## 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 .
+pip install cd-browser
 ```

-For editable local development:
+**Important**: After installation, run this to set up the `cd_` command:

 ```bash
-pip install -e '.[dev]'
+cd_browser_post_install
 ```

-After installation, the application command is:
-
-```bash
-cd_browser
-```
-
-When the interactive session exits, the program prints the final selected directory path.
+This interactive script will guide you through enabling `cd_` in your shell.

 ## Shell Integration For `cd_`

@@ -77,6 +150,15 @@ Then use:
 cd_
 ```

+- Inside `cd_browser`, press `.` to toggle hidden entries.
+
+## Platform Compatibility
+
+Practical conclusion:
+
+- Best current support: **macOS and Linux**
+- **Windows is partially supported**, but still needs real-world validation in Windows terminal environments before being considered fully supported
+
 ## Uninstall

 If the project was installed with `pip`, remove it with:
@@ -85,7 +167,7 @@ If the project was installed with `pip`, remove it with:
 pip uninstall cd-browser
 ```

-If you also added the `cd_` shell wrapper, remove that function from your shell profile and reload the shell configuration.
+**Important**: After uninstalling, remove the `cd_()` function from your shell profile (~/.bashrc or ~/.zshrc) to clean up completely.

 ## Developer Setup

--- a/docs/ai-execution-log.md
+++ b/docs/ai-execution-log.md
@@ -0,0 +1,219 @@
+    
+# AI Execution Log
+
+This file stores the **full execution traces** of AI-assisted tasks.
+
+Unlike:
+- `docs/ai-worklog.md` → concise technical task summaries
+- `docs/ai-prompts.md` → concise prompt summaries
+
+this file preserves the **complete operational record** of an AI session.
+
+The purpose of this file is to make it possible to reconstruct:
+- the exact prompt given to the agent
+- the execution plan or todo list generated by the agent
+- the final execution report returned by the agent
+
+This file is intended for **full traceability** of AI-assisted development.
+
+Entries must be appended in chronological order.
+
+---
+
+## Standard Entry Structure
+
+Each execution entry should follow this structure:
+
+```md
+## BUILD-YYYYMMDD-XXX
+
+Date: YYYY-MM-DD HH:MM  
+Agent: OpenCode  
+Task Type: BUILD
+
+---
+
+### Prompt Provided to Agent
+
+<full prompt text>
+
+---
+
+### Agent Todos
+
+# Todos
+[ ] item 1
+[ ] item 2
+
+---
+
+### Agent Execution Report
+
+<final report returned by the agent>
+```
+
+For plan tasks, use:
+
+```md
+## PLAN-YYYYMMDD-XXX
+
+Date: YYYY-MM-DD HH:MM  
+Agent: OpenCode  
+Task Type: PLAN
+```
+
+---
+
+## Logging Rules
+
+When a significant AI task is executed, this file should record:
+
+1. The prompt that was actually given to the agent.
+2. The todo or execution plan shown by the agent.
+3. The final summary or execution report returned by the agent.
+
+Do not store private chain-of-thought.
+Only store user-visible execution artifacts.
+
+---
+
+## Relationship With Other Logs
+
+- `docs/ai-prompts.md` stores a concise summary of the prompt.
+- `docs/ai-worklog.md` stores a concise technical summary of what was done.
+- `docs/ai-execution-log.md` stores the complete visible execution trace.
+
+Together, the three files provide:
+
+1. Prompt intent
+2. Technical result
+3. Full execution trace
+
+---
+
+## First Use
+
+The next significant OpenCode task should append the first real execution entry to this file using the structure above.
+
+---
+
+## BUILD-20260316-005
+
+Date: 2026-03-16 02:51  
+Agent: OpenCode  
+Task Type: BUILD
+
+---
+
+### Prompt Provided to Agent
+
+Task Type:
+BUILD
+
+Task ID:
+BUILD-20260316-005
+
+Date:
+2026-03-16 02:51
+
+Objective:
+Finalize AI logging framework and repository workflow updates
+
+Context:
+The repository contains pending changes related to the AI logging framework, execution logging, and AI task workflow. These changes introduce a three-level logging system (`ai-worklog.md`, `ai-prompts.md`, and `ai-execution-log.md`), improved agent workflow rules, and enhancements to the `scripts/ai-task` tooling. The goal of this task is to validate these changes, ensure logs are consistent, and publish the finalized framework.
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Requirements:
+1. Inspect the current working tree and confirm the changes in scope.
+2. Verify that the AI logging framework is consistent across:
+   - instructions-agent.md
+   - AGENT_WORKFLOW.md
+   - AI_TASK_TEMPLATE.md
+   - scripts/ai-task
+3. Ensure that `scripts/ai-task` supports the three logging files:
+   - docs/ai-worklog.md
+   - docs/ai-prompts.md
+   - docs/ai-execution-log.md
+4. Append a new AI BUILD ENTRY to `docs/ai-worklog.md`.
+5. Append a new BUILD PROMPT ENTRY to `docs/ai-prompts.md`.
+6. Append a new execution entry to `docs/ai-execution-log.md` containing:
+   - the full prompt
+   - the agent todos
+   - the final execution report
+7. Ensure all three logs remain in chronological order.
+8. Stage all modified files within the defined scope.
+9. Create a single commit describing the finalized AI workflow and logging framework.
+10. Push the commit to the current branch.
+
+Constraints:
+- follow AGENT_WORKFLOW.md
+- keep scope limited to the files listed above
+- preserve existing project behavior unless explicitly changed
+- logs must be written before creating the commit
+- logs must be included in the same commit
+
+Testing:
+- run `make fix`
+- run `make quality`
+- verify that `scripts/ai-task` still generates a valid BUILD task prompt
+- verify that log files remain chronologically ordered
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- append entry to docs/ai-worklog.md
+- append entry to docs/ai-prompts.md
+- include Date, Task ID, Agent, Scope
+- use Task ID: BUILD-20260316-005
+- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md
+- append entry to docs/ai-execution-log.md
+
+Execution Logging requirements:
+- append entry to docs/ai-execution-log.md
+- include:
+  - full prompt
+  - agent todos
+  - final execution report
+- use the standard execution log format defined in docs/ai-execution-log.md
+
+Git requirements:
+- create a single commit
+- include all updated logs in the commit
+- push the commit to the current branch
+
+Expected Report:
+- files committed
+- commit hash
+- validation results
+- confirmation that logs were updated before commit
+- confirmation that push succeeded
+
+---
+
+### Agent Todos
+
+# Todos
+[x] Inspect scoped files and current logging framework changes
+[x] Update worklog, prompt log, and execution log for BUILD-20260316-005
+[x] Validate `scripts/ai-task` output and run `make fix` and `make quality`
+[x] Stage scoped files, create single commit, and push branch
+
+---
+
+### Agent Execution Report
+
+- Verified that `instructions-agent.md`, `AGENT_WORKFLOW.md`, `AI_TASK_TEMPLATE.md`, and `scripts/ai-task` describe the same three-level logging workflow.
+- Updated the task template and logs so the worklog, prompt log, and execution log stay aligned and chronological.
+- Confirmed `scripts/ai-task build "test task" src/app/ui.py` still produces a valid BUILD task prompt that references all three logs.
+- Ran `make fix` and `make quality` successfully before commit creation.
+- Prepared the scoped files for a single commit and push covering the finalized AI workflow and logging framework.
--- a/docs/ai-prompts.md
+++ b/docs/ai-prompts.md
@@ -1,43 +1,221 @@
 # AI Prompts Log

-This file stores relevant prompts used during AI-assisted development.
+This file stores the prompts that triggered significant AI-driven development tasks.

-Only store prompts that:
+The goal is to preserve traceability between:
+- the prompt given to the AI
+- the scope of the change
+- the resulting work recorded in `ai-worklog.md`
+
+Each entry must include:
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task type (plan/build)
+- Scope
+- Prompt summary
+- Result summary
+
+Only record prompts that:
 - change architecture
 - introduce new behavior
 - modify important logic
 - affect project structure
 - debug complex issues

-Do not store internal chain-of-thought reasoning.
-Store only the user prompt and a short result summary.
+Do not store chain-of-thought reasoning. Only store the prompt intent and a concise result summary.

-## 2026-03-15
+---

- prompt summary: Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view.
- result summary: Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests.
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 18:05
+Task ID: BUILD-20260315-001
+Agent: OpenCode
+Task: build

-## 2026-03-15
+Scope:
+- src/app/ui.py
+- tests/test_ui.py

- prompt summary: Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries.
- result summary: Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks.
+Prompt Summary:
+Implement a dedicated history mode in `src/app/ui.py` so pressing `h` hides the tree, shows only history entries, supports Up/Down navigation, and uses Enter to select a history entry and return to the normal tree view.

-## 2026-03-15
+Result Summary:
+Added a dedicated history mode with its own selection state, removed the temporary overlay behavior, preserved existing `b`/`f` and normal tree navigation behavior, and added focused UI tests.

- prompt summary: Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
- result summary: Added a standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` format, improved consistency expectations for AI logs, and updated the log files to reflect the new format.
+---

-## 2026-03-15
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 19:25
+Task ID: BUILD-20260315-002
+Agent: OpenCode
+Task: build

- prompt summary: Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
- result summary: Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md

-## 2026-03-15
+Prompt Summary:
+Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries.

- prompt summary: Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
- result summary: Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+Result Summary:
+Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks.

-## 2026-03-16 00:27
+---

- prompt summary: Improve terminal UI navigation by refining tree and history keyboard behavior, adding scrolling continuity so selection stays visible, and preserving confirmation, cancellation, and history mode behavior.
- result summary: Updated `src/app/ui.py` and `tests/test_ui.py` to support dedicated history selection, improved Right/Left/Enter/ESC behavior, and vertical scrolling for both tree and history views while keeping the AI logs current.
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 20:00
+Task ID: BUILD-20260315-003
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs.
+
+Result Summary:
+Added standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` formats, improving consistency and long-term traceability of AI-assisted development.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 21:35
+Task ID: BUILD-20260315-004
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Improve keyboard navigation in `src/app/ui.py` so Right expands or enters, Left collapses or goes to the parent, Enter confirms the selected destination, and ESC cancels back to the starting directory.
+
+Result Summary:
+Updated the tree-mode key handling in the terminal UI, preserved history mode behavior, and added focused UI tests for the new navigation rules.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-15 22:20
+Task ID: BUILD-20260315-005
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Improve vertical scrolling in `src/app/ui.py` so the selected entry always remains visible in tree mode and history mode when the list is taller than the screen.
+
+Result Summary:
+Added UI scroll offset handling for tree and history views, kept existing navigation behavior unchanged, and added focused tests for the scroll helper logic.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 00:27
+Task ID: BUILD-20260316-001
+Agent: OpenCode
+Task: build
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Prompt Summary:
+Refine terminal UI navigation, maintain dedicated history mode, and ensure scrolling continuity so selections remain visible.
+
+Result Summary:
+Updated terminal UI behavior, consolidated navigation improvements, and ensured consistent scrolling and selection visibility across tree and history modes.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:26
+Task ID: BUILD-20260316-002
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Finalize the AI logging format system by requiring timestamped structured log entries and aligning the repository worklog and prompt log with the current logging framework.
+
+Result Summary:
+Updated the logging instructions, normalized the prompt log to the structured entry format, and added matching repository log entries for the finalized AI logging system.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:34
+Task ID: BUILD-20260316-003
+Agent: OpenCode
+Task: build
+
+Scope:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+
+Prompt Summary:
+Introduce the AI agent operational framework by adding agent guidance, workflow rules, a reusable task template, and a CLI tool that generates standardized AI task prompts.
+
+Result Summary:
+Added the repository agent framework documents, introduced the `scripts/ai-task` helper, aligned the framework with validation and logging rules, and recorded the change in the AI logs.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 01:45
+Task ID: BUILD-20260316-004
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Prompt Summary:
+Finalize and publish the repository AI agent workflow and instruction framework by strengthening workflow and logging rules, documenting the agent framework files, and shipping the task generation tooling.
+
+Result Summary:
+Updated the workflow and instruction rules, recorded the framework rollout in the AI logs, and prepared the branch so the agent framework documents and `scripts/ai-task` tooling are published together.
+
+---
+
+### BUILD PROMPT ENTRY
+Date: 2026-03-16 02:51
+Task ID: BUILD-20260316-005
+Agent: OpenCode
+Task: build
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Prompt Summary:
+Finalize the AI logging framework by aligning instructions, workflow rules, task templates, generator tooling, and all three repository logs, then validate and publish the changes.
+
+Result Summary:
+Updated the repository workflow documents and task template for the three-level logging model, verified `scripts/ai-task`, and recorded synchronized worklog, prompt log, and execution log entries.
--- a/docs/ai-worklog.md
+++ b/docs/ai-worklog.md
@@ -1,27 +1,40 @@
 # AI Worklog

-This file records important AI-assisted development actions.
+This file records important AI‑assisted development actions.

-Each entry should include:
- date
- task type (plan/build)
- objective
- files inspected or modified
- key decisions
- validation commands executed
- result
- open issues (if any)
+The log is designed for long‑term traceability of AI‑driven development.

-Entries must be concise and chronological.
+Each entry must include:
+- Date (YYYY-MM-DD HH:MM)
+- Task ID
+- Agent
+- Task type (plan/build)
+- Objective
+- Scope
+- Files Modified / Files Inspected
+- Key Decisions or Proposed Changes
+- Validation
+- Result
+- Open Issues
+
+Entries must remain chronological.
+
+---

 ### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 18:10
+Task ID: BUILD-20260315-001
+Agent: OpenCode
 Task: build
 Objective: Replace the temporary history debug overlay with a dedicated history mode in the terminal UI.

+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
 Files Modified:
- `src/app/ui.py`
- `tests/test_ui.py`
+- src/app/ui.py
+- tests/test_ui.py

 Key Decisions:
 - Keep `b` and `f` unchanged.
@@ -34,131 +47,331 @@ Validation:
 - make quality

 Result:
- History mode now shows only the history list, supports Up/Down selection, allows Enter to jump to a prior directory, and exits cleanly back to normal navigation.
+- History mode now shows only the history list and allows navigation and selection of past directories.

 Open Issues:
- None.
+- None
+
+---

 ### AI BUILD ENTRY
-Date: 2026-03-16 00:27  
+Date: 2026-03-15 19:30
+Task ID: BUILD-20260315-002
+Agent: OpenCode
 Task: build
-Objective: Consolidate recent terminal UI navigation improvements and document the updated interaction behavior.
+Objective: Introduce mandatory AI logging rules and repository logging workflow.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md

 Files Modified:
- `src/app/ui.py`
- `tests/test_ui.py`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md

 Key Decisions:
- Keep dedicated history mode while refining tree-mode keyboard behavior for Right, Left, Enter, and ESC.
- Add scroll continuity for both tree and history views so the selected row remains visible on long lists.
- Cover the UI-focused behavior with helper-level tests instead of changing navigator or filesystem logic.
-
-Validation:
- make fix (passed)
- make quality (passed)
-
-Result:
- The terminal UI now combines dedicated history mode, clearer confirmation and cancellation behavior, improved tree navigation semantics, and vertical scrolling that keeps the current selection visible in both tree and history views.
-
-Open Issues:
- None.
-
-### AI BUILD ENTRY
-Date: 2026-03-15  
-Task: build  
-Objective: Introduce mandatory AI logging rules and document the repository logging workflow.
-
-Files Modified:
- `instructions-agent.md`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
-
-Key Decisions:
- Require AI agents to log significant plan and build tasks.
- Preserve separate logs for work performed and prompts received.
- Keep entries concise and user-facing.
+- Require AI agents to log plan and build tasks.
+- Separate logs for work results and prompts.
+- Keep entries concise and user‑focused.

 Validation:
 - not run

 Result:
- The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries.
+- Repository now enforces AI logging via instructions-agent.md.

 Open Issues:
- None.
+- None
+
+---

 ### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 20:05
+Task ID: BUILD-20260315-003
+Agent: OpenCode
 Task: build
-Objective: Record the introduction of the standard AI log entry format and improve AI logging consistency.
+Objective: Introduce the standard AI log entry format and improve logging consistency.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md

 Files Modified:
- `instructions-agent.md`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md

 Key Decisions:
- Add a dedicated "Standard AI Log Entry Format" section to define `AI BUILD ENTRY` and `AI PLAN ENTRY` blocks.
- Use the new standardized format for this worklog update to establish the pattern in the repository logs.
+- Define AI BUILD ENTRY and AI PLAN ENTRY blocks.
+- Standardize structure for long‑term repository traceability.

 Validation:
 - make fix (passed)
 - make quality (passed)

 Result:
- The repository now documents a standard AI log entry format and uses it to improve consistency of AI-assisted development logs.
+- Repository now uses a standardized AI logging format.

 Open Issues:
- None.
+- None
+
+---

 ### AI BUILD ENTRY
-Date: 2026-03-15  
-Task: build  
-Objective: Improve vertical scrolling in the terminal UI so the selected row remains visible in tree mode and history mode.
-
-Files Modified:
- `src/app/ui.py`
- `tests/test_ui.py`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
-
-Key Decisions:
- Add separate scroll offsets for tree mode and history mode inside the UI state.
- Introduce a small helper to clamp scroll offsets so the selected row always stays within the visible window.
- Keep all existing navigation semantics unchanged while limiting the change to UI rendering behavior.
-
-Validation:
- make fix (passed)
- make quality (passed)
-
-Result:
- The terminal UI now scrolls vertically in both tree mode and history mode to keep the current selection visible when the list is taller than the screen.
-
-Open Issues:
- None.
-
-### AI BUILD ENTRY
-Date: 2026-03-15  
+Date: 2026-03-15 21:40
+Task ID: BUILD-20260315-004
+Agent: OpenCode
 Task: build
 Objective: Improve keyboard navigation behavior in the terminal UI for tree mode.

+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
 Files Modified:
- `src/app/ui.py`
- `tests/test_ui.py`
+- src/app/ui.py
+- tests/test_ui.py

 Key Decisions:
- Make Right expand collapsed directories and enter already expanded directories.
- Make Left collapse expanded directories and otherwise navigate to the parent directory.
- Make Enter confirm the selected path as the final destination and make ESC return the original starting directory.
+- Right expands collapsed directories and enters expanded directories.
+- Left collapses expanded directories or navigates to the parent directory.
+- Enter confirms the selected path.
+- ESC cancels and returns to the original directory.

 Validation:
 - make fix (passed)
 - make quality (passed)

 Result:
- Tree-mode keyboard navigation now supports expand-or-enter on Right, collapse-or-parent on Left, explicit selection confirmation on Enter, and cancel-to-start behavior on ESC.
+- Tree navigation semantics improved with clearer expand, enter, and cancel behavior.

 Open Issues:
- None.
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-15 22:25
+Task ID: BUILD-20260315-005
+Agent: OpenCode
+Task: build
+Objective: Implement vertical scrolling so the selected entry always remains visible.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Files Modified:
+- src/app/ui.py
+- tests/test_ui.py
+
+Key Decisions:
+- Introduce scroll offsets in the UI state.
+- Clamp offsets to keep the selected row visible.
+- Apply the same mechanism to history mode.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- Tree and history views now scroll when navigating beyond the visible screen area.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 00:27
+Task ID: BUILD-20260316-001
+Agent: OpenCode
+Task: build
+Objective: Consolidate terminal UI navigation improvements and document updated behavior.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- src/app/ui.py
+- tests/test_ui.py
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Maintain dedicated history mode.
+- Refine tree-mode keyboard behavior.
+- Keep UI logic isolated from navigator logic.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- Terminal UI now includes history mode, improved navigation semantics, and reliable vertical scrolling.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:26
+Task ID: BUILD-20260316-002
+Agent: OpenCode
+Task: build
+Objective: Finalize the AI logging format system and align repository log files with the structured logging framework.
+
+Scope:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- instructions-agent.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Require timestamped log entries with date and time, Task ID, Agent, and Scope fields.
+- Keep the worklog and prompt log aligned with the current structured logging framework.
+- Normalize prompt logging into a single consistent `BUILD PROMPT ENTRY` format.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The AI logging system now uses consistent structured entries across repository instructions, worklog history, and prompt history.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:34
+Task ID: BUILD-20260316-003
+Agent: OpenCode
+Task: build
+Objective: Introduce the AI agent operational framework and task generation tooling for standardized AI-assisted repository work.
+
+Scope:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+
+Files Modified:
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Define separate documents for agent behavior, operational workflow, and reusable task structure.
+- Keep the task generator focused on producing standardized PLAN and BUILD prompts with task IDs and validation requirements.
+- Align the new framework with the repository logging rules and validation workflow.
+
+Validation:
+- scripts/ai-task build "test task" src/app/ui.py (passed)
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now includes a documented AI agent framework and an executable helper tool for generating standardized AI task prompts.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 01:45
+Task ID: BUILD-20260316-004
+Agent: OpenCode
+Task: build
+Objective: Finalize and publish the AI agent workflow, instruction framework, and task tooling updates.
+
+Scope:
+- instructions-agent.md
+- AGENT.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Files Modified:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+
+Key Decisions:
+- Strengthen commit and logging order rules so AI logs must be written before creating commits.
+- Keep the new agent framework documents and task tooling aligned with the repository validation and traceability model.
+- Publish the previously prepared framework files together with the finalized logging guidance on the current branch.
+
+Validation:
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now has a finalized AI instruction and workflow framework, standardized task tooling, and matching logs documenting the framework rollout.
+
+Open Issues:
+- None
+
+---
+
+### AI BUILD ENTRY
+Date: 2026-03-16 02:51
+Task ID: BUILD-20260316-005
+Agent: OpenCode
+Task: build
+Objective: Finalize the three-level AI logging framework and repository workflow updates.
+
+Scope:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Files Modified:
+- instructions-agent.md
+- AGENT_WORKFLOW.md
+- AI_TASK_TEMPLATE.md
+- scripts/ai-task
+- docs/ai-worklog.md
+- docs/ai-prompts.md
+- docs/ai-execution-log.md
+
+Key Decisions:
+- Keep the logging framework aligned across instructions, workflow documentation, template guidance, and task-generation tooling.
+- Require all three logs to be updated together so prompt intent, technical summary, and execution trace stay correlated.
+- Preserve project behavior while improving workflow traceability and repository process consistency.
+
+Validation:
+- scripts/ai-task build "test task" src/app/ui.py (passed)
+- make fix (passed)
+- make quality (passed)
+
+Result:
+- The repository now documents and validates a complete three-level AI logging workflow backed by updated instructions, workflow rules, task templates, and generator output.
+
+Open Issues:
+- None
+
+---
--- a/docs/demo.gif
+++ b/docs/demo.gif
--- a/instructions-agent.md
+++ b/instructions-agent.md
@@ -1,190 +0,0 @@
-# Agent Instructions: Universal Python Project Template
-
-## Project Overview
-This repository is a universal and adaptable Python template intended to serve as a professional starting point for new projects.
-
-## Core Directives
-1. All code, comments, variables, string literals, commit messages, and documentation must be written in English.
-2. Use Python 3.11+ with type hints whenever possible.
-3. Follow clean code principles and PEP 8.
-4. Keep modules small, cohesive, and maintainable.
-5. Use consistent docstrings for public classes and functions.
-6. Prefer explicit error handling over silent failures.
-
-## Architecture Guidelines
-1. Keep business logic separate from infrastructure concerns.
-2. Avoid mixing configuration, I/O, and domain logic in the same module.
-3. Prefer reusable services over duplicated logic.
-4. Do not introduce unnecessary complexity or premature abstractions.
-
-## Quality Standards
-1. Every meaningful feature should include tests.
-2. Run formatting, linting, and type checks before considering a task complete.
-3. Keep the README updated whenever setup, commands, or structure changes.
-4. Do not leave placeholder code unless clearly marked.
-
-## Tooling
- Testing: pytest
- Formatting: black
- Linting: ruff
- Static typing: mypy
-
-## Expected Project Structure
-src/app/
-tests/
-scripts/
-README.md
-instructions-agent.md
-pyproject.toml
-
-## Agent Workflow
-1. First understand the repository structure.
-2. Propose a short implementation plan before major changes.
-3. Reuse existing modules whenever possible.
-4. Keep changes minimal, coherent, and production-oriented.
-5. Validate changes with tests and quality tools when possible.
-
-## Application Specification
-
-This repository includes an application specification that defines the expected behavior of the project.
-
-Primary specification file:
-
- `specs/cd_browser_spec.md`
-
-Agent rules:
-
-1. Before implementing any feature, read the application specification.
-2. If implementation details are unclear, follow the specification first.
-3. If the specification conflicts with a previous assumption, the specification takes precedence.
-4. Keep implementation aligned with the MVP scope unless explicitly asked to extend it.
-5. After code changes, run the appropriate validation workflow defined by this repository.
-
-## AI Worklog Policy
-
-This repository maintains an AI-assisted development log.
-
-Files:
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
-
-Rules:
-1. After every significant `plan` or `build` task, append a concise worklog entry to `docs/ai-worklog.md`.
-2. Each worklog entry must include:
-   - date
-   - task type (`plan` or `build`)
-   - short objective
-   - files inspected or modified
-   - key decisions
-   - validation commands run
-   - result
-   - unresolved issues if any
-3. When a prompt meaningfully changes architecture, behavior, workflow, debugging direction, or project structure, append the prompt (or a concise cleaned version of it) to `docs/ai-prompts.md`.
-4. Do not store private chain-of-thought or internal reasoning.
-5. Store only concise, user-facing summaries of what was done.
-6. Keep entries chronological and easy to scan.
-
-## Mandatory AI Logging
-
-Every significant AI interaction in this repository must be logged.
-
-This applies to:
- `plan` tasks
- `build` tasks
- debugging tasks
- documentation tasks
- architectural discussions that affect the project
-
-Required files:
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
-
-Mandatory rules:
-1. After every significant `plan` task, append a concise entry to `docs/ai-worklog.md`.
-2. After every significant `build` task, append a concise entry to `docs/ai-worklog.md`.
-3. If the task was driven by a meaningful prompt, also append an entry to `docs/ai-prompts.md`.
-4. Logging is part of the task itself and must not be skipped.
-5. The task is not complete until the logs are updated.
-
-Each worklog entry must include:
- date
- task type (`plan` or `build`)
- short objective
- files inspected or modified
- key decisions
- validation commands run, if any
- result
- unresolved issues, if any
-
-Validation logging rule:
- If validation commands such as `make fix`, `make quality`, `pytest`, or other checks are executed during the task, the worklog entry must record them explicitly.
- The value `validation: not run` may only be used if no validation commands were executed.
- The worklog entry must reflect the actual commands run during the task.
-
-Each prompt log entry must include:
- date
- task type (`plan` or `build`)
- short prompt summary
- scope
- result summary
-
-Rules:
- Do not store chain-of-thought or private reasoning.
- Store only concise user-facing summaries.
- Keep entries chronological.
- Even small but meaningful tasks must be logged.
-
-## Standard AI Log Entry Format
-
-To ensure consistency and readability of long AI-assisted development histories, all log entries must follow a standardized block format.
-
-Agents must write log entries using the following structure.
-
-Example for build tasks:
-
-### AI BUILD ENTRY
-Date: YYYY-MM-DD HH:MM  
-Task: build  
-Objective: short description of the task
-
-Files Modified:
- file/path/example.py
- another/file.md
-
-Key Decisions:
- short bullet explaining important choices
-
-Validation:
- make fix (passed)
- make quality (passed)
-
-Result:
- short description of what changed or was achieved
-
-Open Issues:
- optional list of unresolved problems
-
-Example for plan tasks:
-
-### AI PLAN ENTRY
-Date: YYYY-MM-DD HH:MM  
-Task: plan  
-Objective: short description of planning objective
-
-Files Inspected:
- src/app/example.py
- specs/example_spec.md
-
-Proposed Changes:
- summary of planned changes
-
-Notes:
- optional relevant observations
-
-Rules:
- Always use these headers exactly (`AI BUILD ENTRY` or `AI PLAN ENTRY`).
- Keep entries concise and structured.
- Do not include chain-of-thought reasoning.
- Use bullet points when possible.
- This format must be used when updating `docs/ai-worklog.md`.
- The Date field must include both date and time using the format YYYY-MM-DD HH:MM.
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,17 +4,31 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "cd-browser"
-version = "0.1.0"
-description = "A universal and adaptable Python project template for AI-assisted development."
+version = "0.2.6"
+description = "A fast keyboard-driven directory navigator for the terminal."
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.8"
 authors = [
  { name = "Saky" }
 ]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Utilities",
+]
 dependencies = []

 [project.scripts]
 cd_browser = "app.main:main"
+cd_browser_post_install = "cd_browser_post_install:main"

 [project.optional-dependencies]
 dev = [
@@ -27,6 +41,7 @@ dev = [

 [tool.setuptools]
 package-dir = {"" = "src"}
+py-modules = ["cd_browser_post_install"]

 [tool.setuptools.packages.find]
 where = ["src"]
--- a/scripts/ai-task
+++ b/scripts/ai-task
@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+
+# ai-task
+# Helper CLI to generate AI task prompts based on AI_TASK_TEMPLATE.md
+# Usage:
+#   scripts/ai-task build "Objective text" [scope...]
+#   scripts/ai-task plan "Objective text" [scope...]
+
+set -e
+
+TYPE="$1"
+OBJECTIVE="$2"
+shift 2 || true
+SCOPE=("$@")
+
+if [[ -z "$TYPE" || -z "$OBJECTIVE" ]]; then
+  echo "Usage: ai-task <plan|build> \"Objective\" [scope files...]"
+  exit 1
+fi
+
+TYPE_LOWER=$(echo "$TYPE" | tr '[:upper:]' '[:lower:]')
+TYPE_UPPER=$(echo "$TYPE_LOWER" | tr '[:lower:]' '[:upper:]')
+
+DATE=$(date "+%Y-%m-%d %H:%M")
+DAY=$(date "+%Y%m%d")
+
+case "$TYPE_LOWER" in
+  build)
+    PREFIX="BUILD"
+    ;;
+  plan)
+    PREFIX="PLAN"
+    ;;
+  *)
+    echo "Error: task type must be 'plan' or 'build'"
+    exit 1
+    ;;
+esac
+
+WORKLOG_FILE="docs/ai-worklog.md"
+PROMPTS_FILE="docs/ai-prompts.md"
+EXECUTION_LOG_FILE="docs/ai-execution-log.md"
+
+check_task_id_order() {
+  local file="$1"
+  local prefix="$2"
+  local previous=""
+  local current=""
+
+  [[ -f "$file" ]] || return 0
+
+  while IFS= read -r current; do
+    if [[ -n "$previous" && "$current" < "$previous" ]]; then
+      echo "Error: task IDs in $file are out of chronological order for prefix $prefix" >&2
+      echo "Previous: $previous" >&2
+      echo "Current:  $current" >&2
+      echo "Please fix the log order before generating a new task." >&2
+      exit 1
+    fi
+    previous="$current"
+  done < <(grep -Eo "${prefix}-[0-9]{8}-[0-9]{3}" "$file" || true)
+}
+
+check_task_id_order "$WORKLOG_FILE" "$PREFIX"
+check_task_id_order "$PROMPTS_FILE" "$PREFIX"
+check_task_id_order "$EXECUTION_LOG_FILE" "$PREFIX"
+
+LAST_SEQ=0
+
+if [[ -f "$WORKLOG_FILE" ]]; then
+  LAST_MATCH=$(grep -Eo "${PREFIX}-${DAY}-[0-9]{3}" "$WORKLOG_FILE" | tail -n 1 || true)
+  if [[ -n "$LAST_MATCH" ]]; then
+    LAST_SEQ=${LAST_MATCH##*-}
+    LAST_SEQ=$((10#$LAST_SEQ))
+  fi
+fi
+
+NEXT_SEQ=$(printf "%03d" $((LAST_SEQ + 1)))
+TASK_ID="${PREFIX}-${DAY}-${NEXT_SEQ}"
+
+# Build scope block
+cat <<EOF
+Task Type:
+${TYPE_UPPER}
+
+Task ID:
+${TASK_ID}
+
+Date:
+${DATE}
+
+Objective:
+${OBJECTIVE}
+
+Context:
+<describe repository state if needed>
+
+Scope:
+EOF
+
+if [ ${#SCOPE[@]} -gt 0 ]; then
+  for item in "${SCOPE[@]}"; do
+    printf '%s\n' "- ${item}"
+  done
+else
+  printf '%s\n' "- <fill scope>"
+fi
+
+cat <<EOF
+
+Requirements:
+<describe expected behavior>
+
+Constraints:
+- follow AGENT_WORKFLOW.md
+- keep scope minimal
+- preserve existing behavior unless explicitly changed
+
+Testing:
+<describe expected tests>
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- append entry to docs/ai-worklog.md
+- append entry to docs/ai-prompts.md
+- include Date, Task ID, Agent, Scope
+- use Task ID: ${TASK_ID}
+- maintain chronological Task ID order in ai-worklog.md, ai-prompts.md and ai-execution-log.md
+- append entry to docs/ai-execution-log.md
+
+Execution Logging requirements:
+- append entry to docs/ai-execution-log.md
+- include:
+  - full prompt
+  - agent todos
+  - final execution report
+- use the standard execution log format defined in docs/ai-execution-log.md
+
+Git requirements:
+- do NOT commit or push unless explicitly requested
+
+Expected Report:
+- files changed
+- behavior changes
+- validation results
+EOF
--- a/src/app/config.py
+++ b/src/app/config.py
@@ -5,5 +5,5 @@ from dataclasses import dataclass
 class AppConfig:
    """Application configuration."""

-    app_name: str = "Python AI Dev Template"
+    app_name: str = "cd-browser"
    debug: bool = False
--- a/src/app/filesystem.py
+++ b/src/app/filesystem.py
@@ -13,28 +13,95 @@ class DirectoryEntry:
    has_children: bool


-def list_directories(path: Path) -> list[DirectoryEntry]:
+@dataclass(frozen=True, slots=True)
+class FileSystemEntry:
+    """Filesystem entry metadata for tree rendering."""
+
+    name: str
+    path: Path
+    is_directory: bool
+    has_children: bool
+
+
+def list_directories(path: Path, show_hidden: bool = False) -> list[DirectoryEntry]:
    """Return direct child directories sorted by name."""

-    directory_path = path.expanduser().resolve()
-    entries: list[DirectoryEntry] = []
-
-    for child in directory_path.iterdir():
-        if child.is_dir():
-            entries.append(
+    entries = list_entries(path, show_hidden=show_hidden, include_files=False)
+    return [
        DirectoryEntry(
+            name=entry.name,
+            path=entry.path,
+            has_children=entry.has_children,
+        )
+        for entry in entries
+    ]
+
+
+def list_entries(
+    path: Path, show_hidden: bool = False, include_files: bool = False
+) -> list[FileSystemEntry]:
+    """Return direct child entries sorted by type and name."""
+
+    directory_path = path.expanduser().resolve()
+    entries: list[FileSystemEntry] = []
+
+    try:
+        children = list(directory_path.iterdir())
+    except PermissionError:
+        return []
+
+    for child in children:
+        try:
+            is_directory = child.is_dir()
+        except OSError:
+            continue
+
+        if not is_directory and not include_files:
+            continue
+        if not show_hidden and child.name.startswith("."):
+            continue
+
+        entries.append(
+            FileSystemEntry(
                name=child.name,
                path=child,
-                    has_children=has_subdirectories(child),
+                is_directory=is_directory,
+                has_children=(
+                    has_subdirectories(child, show_hidden=show_hidden)
+                    if is_directory
+                    else False
+                ),
            )
        )

-    return sorted(entries, key=lambda entry: entry.name.casefold())
+    return sorted(
+        entries,
+        key=lambda entry: (not entry.is_directory, entry.name.casefold()),
+    )


-def has_subdirectories(path: Path) -> bool:
+def has_subdirectories(path: Path, show_hidden: bool = False) -> bool:
    """Return whether the directory contains at least one subdirectory."""

    directory_path = path.expanduser().resolve()

-    return any(child.is_dir() for child in directory_path.iterdir())
+    try:
+        children = list(directory_path.iterdir())
+    except PermissionError:
+        return False
+
+    for child in children:
+        try:
+            is_directory = child.is_dir()
+        except OSError:
+            continue
+
+        if not is_directory:
+            continue
+
+        if not show_hidden and child.name.startswith("."):
+            continue
+
+        return True
+
+    return False
--- a/src/app/navigator.py
+++ b/src/app/navigator.py
@@ -3,13 +3,13 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from pathlib import Path

-from app.filesystem import list_directories
+from app.filesystem import list_entries
 from app.history import SessionHistory


@dataclass(frozen=True, slots=True)
 class VisibleEntry:
-    """A directory row visible in the navigator."""
+    """A row visible in the navigator tree."""

    name: str
    path: Path
@@ -17,6 +17,7 @@ class VisibleEntry:
    has_children: bool
    is_expanded: bool
    is_parent: bool = False
+    is_file: bool = False


@dataclass(slots=True)
@@ -28,6 +29,8 @@ class Navigator:
    current_path: Path = field(init=False)
    selected_index: int = field(init=False, default=0)
    _expanded_paths: set[Path] = field(init=False, default_factory=set)
+    show_hidden: bool = False
+    show_files: bool = False

    def __post_init__(self) -> None:
        self.current_path = self.start_path.expanduser().resolve()
@@ -68,6 +71,9 @@ class Navigator:
    def enter_selected_directory(self) -> Path:
        """Enter the currently selected directory and record it in history."""

+        if self.selected_entry.is_file:
+            return self.current_path
+
        return self._change_directory(self.selected_entry.path)

    def go_to_parent_directory(self) -> Path:
@@ -144,6 +150,22 @@ class Navigator:
        self._set_current_path(path)
        return path

+    def toggle_hidden(self) -> None:
+        """Toggle showing/hiding hidden directory entries."""
+
+        self.show_hidden = not self.show_hidden
+        self._reset_view_state()
+
+    def toggle_files(self) -> None:
+        """Toggle showing/hiding file entries."""
+
+        self.show_files = not self.show_files
+        self._reset_view_state()
+
+    def _reset_view_state(self) -> None:
+        self.selected_index = 0
+        self._expanded_paths.clear()
+
    def select_history_entry(self, index: int) -> Path:
        """Jump to a directory stored in session history."""

@@ -154,20 +176,25 @@ class Navigator:
    def _build_entries(self, path: Path, depth: int) -> list[VisibleEntry]:
        entries: list[VisibleEntry] = []

-        for directory in list_directories(path):
-            is_expanded = directory.path in self._expanded_paths
+        for item in list_entries(
+            path, show_hidden=self.show_hidden, include_files=self.show_files
+        ):
+            is_expanded = (
+                item.path in self._expanded_paths if item.is_directory else False
+            )
            entries.append(
                VisibleEntry(
-                    name=directory.name,
-                    path=directory.path,
+                    name=item.name,
+                    path=item.path,
                    depth=depth,
-                    has_children=directory.has_children,
+                    has_children=item.has_children,
                    is_expanded=is_expanded,
+                    is_file=not item.is_directory,
                )
            )

            if is_expanded:
-                entries.extend(self._build_entries(directory.path, depth=depth + 1))
+                entries.extend(self._build_entries(item.path, depth=depth + 1))

        return entries

--- a/src/app/opener.py
+++ b/src/app/opener.py
@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+LaunchMode = Literal["background", "blocking"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenWithOption:
+    """Candidate application command for opening a path."""
+
+    label: str
+    command_template: str
+    executable: str
+    launch_mode: LaunchMode
+    requires_gui: bool = False
+    supports_files: bool = True
+    supports_directories: bool = True
+
+
+def available_openers(path: Path) -> list[OpenWithOption]:
+    """Return available open-with options for a file or directory path."""
+
+    is_directory = path.is_dir()
+    has_gui = _has_gui_session()
+    options: list[OpenWithOption] = []
+
+    for option in _default_options():
+        if is_directory and not option.supports_directories:
+            continue
+        if not is_directory and not option.supports_files:
+            continue
+        if option.requires_gui and not has_gui:
+            continue
+        if not shutil.which(option.executable):
+            continue
+
+        options.append(option)
+
+    return options
+
+
+def launch_background_option(path: Path, option: OpenWithOption) -> tuple[bool, str]:
+    """Launch a non-blocking option and return status/message."""
+
+    command = _command_parts(option.command_template, path)
+    if not command:
+        return False, "Invalid open command"
+
+    try:
+        subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    except OSError as error:
+        return False, f"Open failed: {error}"
+
+    return True, f"Opened with {option.label}"
+
+
+def launch_blocking_option(path: Path, option: OpenWithOption) -> tuple[bool, str]:
+    """Launch a blocking terminal option and return status/message."""
+
+    command = _command_parts(option.command_template, path)
+    if not command:
+        return False, "Invalid open command"
+
+    try:
+        result = subprocess.run(command, check=False)
+    except OSError as error:
+        return False, f"Open failed: {error}"
+
+    if result.returncode != 0:
+        return (
+            False,
+            f"Open failed: {option.label} exited with code {result.returncode}",
+        )
+
+    return True, f"Opened with {option.label}"
+
+
+def is_blocking_option(option: OpenWithOption) -> bool:
+    """Return whether the option should block the current terminal session."""
+
+    return option.launch_mode == "blocking"
+
+
+def _default_options() -> tuple[OpenWithOption, ...]:
+    return (
+        OpenWithOption(
+            label="VS Code",
+            command_template="code {path}",
+            executable="code",
+            launch_mode="background",
+            requires_gui=True,
+        ),
+        OpenWithOption(
+            label="Open (system)",
+            command_template=_system_open_template(),
+            executable=_system_open_executable(),
+            launch_mode="background",
+            requires_gui=True,
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Antigravity",
+            command_template="antigravity {path}",
+            executable="antigravity",
+            launch_mode="background",
+        ),
+        OpenWithOption(
+            label="Neovim",
+            command_template="nvim {path}",
+            executable="nvim",
+            launch_mode="blocking",
+        ),
+        OpenWithOption(
+            label="Nano",
+            command_template="nano {path}",
+            executable="nano",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Less",
+            command_template="less {path}",
+            executable="less",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+        OpenWithOption(
+            label="Bat",
+            command_template="bat {path}",
+            executable="bat",
+            launch_mode="blocking",
+            supports_directories=False,
+        ),
+    )
+
+
+def _has_gui_session() -> bool:
+    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY"):
+        return False
+
+    if sys.platform == "darwin":
+        return True
+
+    if sys.platform.startswith("linux"):
+        return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+    if sys.platform.startswith("win"):
+        return True
+
+    return False
+
+
+def _system_open_template() -> str:
+    if sys.platform == "darwin":
+        return "open {path}"
+
+    if sys.platform.startswith("linux"):
+        return "xdg-open {path}"
+
+    if sys.platform.startswith("win"):
+        return 'cmd /c start "" {path}'
+
+    return "open {path}"
+
+
+def _system_open_executable() -> str:
+    if sys.platform == "darwin":
+        return "open"
+
+    if sys.platform.startswith("linux"):
+        return "xdg-open"
+
+    if sys.platform.startswith("win"):
+        return "cmd"
+
+    return "open"
+
+
+def _command_parts(command_template: str, path: Path) -> list[str]:
+    rendered = command_template.format(path=shlex.quote(str(path)))
+    return shlex.split(rendered)
--- a/src/app/ui.py
+++ b/src/app/ui.py
@@ -10,8 +10,16 @@ from pathlib import Path
 from typing import TextIO

 from app.navigator import Navigator, VisibleEntry
+from app.opener import (
+    OpenWithOption,
+    available_openers,
+    is_blocking_option,
+    launch_background_option,
+    launch_blocking_option,
+)

 ESCAPE_KEY = 27
+BACKSPACE_KEYS = (curses.KEY_BACKSPACE, 127, 8)


@dataclass(frozen=True, slots=True)
@@ -46,9 +54,13 @@ def format_entry(entry: VisibleEntry) -> str:
        return entry.name

    indent = "    " * entry.depth
-    indicator = " "
-    if entry.has_children:
+
+    if entry.is_file:
+        indicator = "•"
+    elif entry.has_children:
        indicator = "▼" if entry.is_expanded else "▶"
+    else:
+        indicator = " "

    return f"{indent}{indicator} {entry.name}"

@@ -104,6 +116,11 @@ class TerminalUI:
        self._history_selected_index = 0
        self._tree_scroll_offset = 0
        self._history_scroll_offset = 0
+        self._filter_mode = False
+        self._filter_query = ""
+        self._filter_selected_index = 0
+        self._filter_scroll_offset = 0
+        self._status_message: str | None = None

    def run(self, navigator: Navigator) -> Path:
        """Start the interactive session and return the final directory path."""
@@ -121,6 +138,16 @@ class TerminalUI:
            self._render(stdscr, navigator)
            key = stdscr.getch()

+            if self._history_mode:
+                self._handle_history_key(key, navigator, stdscr=stdscr)
+                continue
+
+            if self._filter_mode:
+                filter_result = self._handle_filter_key(key, navigator, stdscr)
+                if filter_result is not None:
+                    return filter_result
+                continue
+
            if key == ESCAPE_KEY:
                return original_path

@@ -128,11 +155,7 @@ class TerminalUI:
                self._toggle_history_mode(navigator)
                continue

-            if self._history_mode:
-                self._handle_history_key(key, navigator)
-                continue
-
-            tree_result = self._handle_tree_key(key, navigator)
+            tree_result = self._handle_tree_key(key, navigator, stdscr=stdscr)
            if tree_result is not None:
                return tree_result

@@ -145,30 +168,93 @@ class TerminalUI:
            stdscr.refresh()
            return

-        path_text = str(navigator.current_path)
-        stdscr.addnstr(0, 0, path_text, width - 1)
+        hidden_status = "on" if navigator.show_hidden else "off"
+        file_status = "on" if navigator.show_files else "off"
+        path_text = (
+            f"{navigator.current_path} [hidden: {hidden_status}] [files: {file_status}]"
+        )
+        stdscr.addnstr(0, 0, path_text, max(0, width - 1))

-        lines = build_render_lines(navigator)
-        visible_count = max(0, height - 2)
+        start_row = 2
+        if self._filter_mode:
+            stdscr.addnstr(
+                1,
+                0,
+                f"Filter: {self._filter_query}",
+                max(0, width - 1),
+                curses.A_BOLD,
+            )
+            start_row = 3
+
+        lines, selected_index = self._build_tree_lines_for_render(navigator)
+        footer_rows = 1 if self._status_message else 0
+        visible_count = max(0, height - start_row - footer_rows)
+
+        if self._filter_mode:
+            self._filter_scroll_offset = clamp_scroll_offset(
+                selected_index,
+                self._filter_scroll_offset,
+                visible_count,
+                len(lines),
+            )
+            scroll_offset = self._filter_scroll_offset
+        else:
            self._tree_scroll_offset = clamp_scroll_offset(
-            navigator.selected_index,
+                selected_index,
                self._tree_scroll_offset,
                visible_count,
                len(lines),
            )
+            scroll_offset = self._tree_scroll_offset

+        if self._filter_mode and self._filter_query and not lines:
+            stdscr.addnstr(start_row, 0, "No matches", max(0, width - 1), curses.A_DIM)
+        else:
            for row, line in enumerate(
-            lines[self._tree_scroll_offset : self._tree_scroll_offset + visible_count],
-            start=2,
+                lines[scroll_offset : scroll_offset + visible_count],
+                start=start_row,
            ):
                if row >= height:
                    break

                attributes = curses.A_REVERSE if line.is_selected else curses.A_NORMAL
-            stdscr.addnstr(row, 0, line.text, width - 1, attributes)
+                stdscr.addnstr(row, 0, line.text, max(0, width - 1), attributes)
+
+        if self._status_message and height > 0:
+            stdscr.addnstr(
+                height - 1,
+                0,
+                self._status_message,
+                max(0, width - 1),
+                curses.A_DIM,
+            )

        stdscr.refresh()

+    def _build_tree_lines_for_render(
+        self, navigator: Navigator
+    ) -> tuple[list[RenderLine], int]:
+        if not self._filter_mode:
+            return build_render_lines(navigator), navigator.selected_index
+
+        entries = navigator.visible_entries
+        matches = self._matching_indices(entries)
+        if not matches:
+            self._filter_selected_index = 0
+            return [], 0
+
+        self._filter_selected_index = max(
+            0, min(self._filter_selected_index, len(matches) - 1)
+        )
+
+        return [
+            RenderLine(
+                text=format_entry(entries[entry_index]),
+                is_selected=match_index == self._filter_selected_index,
+            )
+            for match_index, entry_index in enumerate(matches)
+        ], self._filter_selected_index
+
    def _render_history_mode(
        self, stdscr: curses.window, navigator: Navigator, width: int, height: int
    ) -> None:
@@ -176,7 +262,8 @@ class TerminalUI:
            navigator.history.entries(), self._history_selected_index
        )
        start_row = 1
-        visible_count = max(0, height - start_row - 1)
+        footer_rows = 1 if self._status_message else 0
+        visible_count = max(0, height - start_row - 1 - footer_rows)
        self._history_scroll_offset = clamp_scroll_offset(
            self._history_selected_index,
            self._history_scroll_offset,
@@ -184,7 +271,7 @@ class TerminalUI:
            len(history_lines),
        )

-        stdscr.addnstr(start_row, 0, "History:", width - 1, curses.A_BOLD)
+        stdscr.addnstr(start_row, 0, "History:", max(0, width - 1), curses.A_BOLD)

        for index, line in enumerate(
            history_lines[
@@ -198,17 +285,33 @@ class TerminalUI:
                break

            attributes = curses.A_REVERSE if line.is_selected else curses.A_NORMAL
-            stdscr.addnstr(row, 0, line.text, width - 1, attributes)
+            stdscr.addnstr(row, 0, line.text, max(0, width - 1), attributes)
+
+        if self._status_message and height > 0:
+            stdscr.addnstr(
+                height - 1,
+                0,
+                self._status_message,
+                max(0, width - 1),
+                curses.A_DIM,
+            )

    def _toggle_history_mode(self, navigator: Navigator) -> None:
        self._history_mode = not self._history_mode
+        self._status_message = None
        if self._history_mode:
            self._history_selected_index = self._get_current_history_index(navigator)
            self._history_scroll_offset = 0

-    def _handle_history_key(self, key: int, navigator: Navigator) -> None:
+    def _handle_history_key(
+        self, key: int, navigator: Navigator, stdscr: curses.window | None = None
+    ) -> None:
        history_entries = navigator.history.entries()

+        if key in (ESCAPE_KEY, ord("h")):
+            self._history_mode = False
+            return
+
        if key == curses.KEY_UP:
            self._history_selected_index = move_selection(
                self._history_selected_index,
@@ -225,12 +328,134 @@ class TerminalUI:
            )
            return

+        if key == curses.KEY_PPAGE:
+            step = -self._page_step(stdscr, start_row=1)
+            self._history_selected_index = move_selection(
+                self._history_selected_index,
+                step=step,
+                entry_count=len(history_entries),
+            )
+            return
+
+        if key == curses.KEY_NPAGE:
+            step = self._page_step(stdscr, start_row=1)
+            self._history_selected_index = move_selection(
+                self._history_selected_index,
+                step=step,
+                entry_count=len(history_entries),
+            )
+            return
+
+        if key in (curses.KEY_HOME, ord("g")):
+            self._history_selected_index = 0
+            return
+
+        if key in (curses.KEY_END, ord("G")) and history_entries:
+            self._history_selected_index = len(history_entries) - 1
+            return
+
        if key in (curses.KEY_ENTER, 10, 13) and history_entries:
            navigator.select_history_entry(self._history_selected_index)
            self._history_mode = False
            self._tree_scroll_offset = 0

-    def _handle_tree_key(self, key: int, navigator: Navigator) -> Path | None:
+    def _handle_filter_key(
+        self, key: int, navigator: Navigator, stdscr: curses.window | None = None
+    ) -> Path | None:
+        entries = navigator.visible_entries
+        matches = self._matching_indices(entries)
+
+        if key == ESCAPE_KEY:
+            self._filter_mode = False
+            self._filter_query = ""
+            self._filter_selected_index = 0
+            self._filter_scroll_offset = 0
+            return None
+
+        if key in (curses.KEY_ENTER, 10, 13):
+            if not matches:
+                return None
+
+            selected_entry_index = matches[self._filter_selected_index]
+            navigator.set_selected_index(selected_entry_index)
+            selected = entries[selected_entry_index]
+
+            self._filter_mode = False
+            self._filter_query = ""
+            self._filter_selected_index = 0
+            self._filter_scroll_offset = 0
+
+            if selected.is_file:
+                self._open_with_selected(navigator, stdscr)
+                return None
+
+            navigator.enter_selected_directory()
+            self._tree_scroll_offset = 0
+            return None
+
+        if key == curses.KEY_UP:
+            self._filter_selected_index = move_selection(
+                self._filter_selected_index,
+                step=-1,
+                entry_count=len(matches),
+            )
+            return None
+
+        if key == curses.KEY_DOWN:
+            self._filter_selected_index = move_selection(
+                self._filter_selected_index,
+                step=1,
+                entry_count=len(matches),
+            )
+            return None
+
+        if key == curses.KEY_PPAGE:
+            step = -self._page_step(stdscr, start_row=3)
+            self._filter_selected_index = move_selection(
+                self._filter_selected_index,
+                step=step,
+                entry_count=len(matches),
+            )
+            return None
+
+        if key == curses.KEY_NPAGE:
+            step = self._page_step(stdscr, start_row=3)
+            self._filter_selected_index = move_selection(
+                self._filter_selected_index,
+                step=step,
+                entry_count=len(matches),
+            )
+            return None
+
+        if key == curses.KEY_HOME:
+            self._filter_selected_index = 0
+            return None
+
+        if key == curses.KEY_END and matches:
+            self._filter_selected_index = len(matches) - 1
+            return None
+
+        if key in BACKSPACE_KEYS:
+            self._filter_query = self._filter_query[:-1]
+            self._filter_selected_index = 0
+            self._filter_scroll_offset = 0
+            return None
+
+        if 32 <= key <= 126:
+            self._filter_query += chr(key)
+            self._filter_selected_index = 0
+            self._filter_scroll_offset = 0
+
+        return None
+
+    def _handle_tree_key(
+        self,
+        key: int,
+        navigator: Navigator,
+        stdscr: curses.window | None = None,
+    ) -> Path | None:
+        self._status_message = None
+
        if key == curses.KEY_UP:
            navigator.set_selected_index(
                move_selection(
@@ -251,8 +476,40 @@ class TerminalUI:
            )
            return None

+        if key == curses.KEY_PPAGE:
+            navigator.set_selected_index(
+                move_selection(
+                    navigator.selected_index,
+                    step=-self._page_step(stdscr, start_row=2),
+                    entry_count=len(navigator.visible_entries),
+                )
+            )
+            return None
+
+        if key == curses.KEY_NPAGE:
+            navigator.set_selected_index(
+                move_selection(
+                    navigator.selected_index,
+                    step=self._page_step(stdscr, start_row=2),
+                    entry_count=len(navigator.visible_entries),
+                )
+            )
+            return None
+
+        if key in (curses.KEY_HOME, ord("g")):
+            navigator.set_selected_index(0)
+            return None
+
+        if key in (curses.KEY_END, ord("G")):
+            navigator.set_selected_index(len(navigator.visible_entries) - 1)
+            return None
+
        if key == curses.KEY_RIGHT:
-            was_expanded = navigator.selected_entry.is_expanded
+            selected = navigator.selected_entry
+            if selected.is_file:
+                return None
+
+            was_expanded = selected.is_expanded

            if not navigator.expand_selected_directory():
                navigator.enter_selected_directory()
@@ -282,11 +539,172 @@ class TerminalUI:
            self._tree_scroll_offset = 0
            return None

+        if key == ord("."):
+            navigator.toggle_hidden()
+            self._tree_scroll_offset = 0
+            return None
+
+        if key == ord("a"):
+            navigator.toggle_files()
+            self._tree_scroll_offset = 0
+            return None
+
+        if key == ord("/"):
+            self._filter_mode = True
+            self._filter_query = ""
+            self._filter_selected_index = 0
+            self._filter_scroll_offset = 0
+            return None
+
+        if key == ord("o"):
+            self._open_with_selected(navigator, stdscr)
+            return None
+
        if key in (curses.KEY_ENTER, 10, 13):
            return navigator.selected_entry.path

        return None

+    def _matching_indices(self, entries: tuple[VisibleEntry, ...]) -> list[int]:
+        if not self._filter_query:
+            return list(range(len(entries)))
+
+        query = self._filter_query.casefold()
+        return [
+            index
+            for index, entry in enumerate(entries)
+            if query in entry.name.casefold()
+        ]
+
+    def _page_step(self, stdscr: curses.window | None, start_row: int) -> int:
+        if stdscr is None:
+            return 10
+
+        height, _width = stdscr.getmaxyx()
+        footer_rows = 1 if self._status_message else 0
+        return max(1, height - start_row - footer_rows)
+
+    def _open_with_selected(
+        self, navigator: Navigator, stdscr: curses.window | None
+    ) -> None:
+        selected = navigator.selected_entry
+        options = available_openers(selected.path)
+        if not options:
+            self._status_message = "No applications available for this entry"
+            return
+
+        option_index = 0
+        if stdscr is not None:
+            choice = self._prompt_open_with_choice(stdscr, options, selected.name)
+            if choice is None:
+                self._status_message = "Open cancelled"
+                return
+
+            option_index = choice
+
+        option = options[option_index]
+        if is_blocking_option(option):
+            success, message = self._launch_blocking_with_terminal_restore(
+                stdscr, selected.path, option
+            )
+        else:
+            success, message = launch_background_option(selected.path, option)
+
+        self._status_message = message
+        if not success:
+            self._status_message = message
+
+    def _prompt_open_with_choice(
+        self,
+        stdscr: curses.window,
+        options: list[OpenWithOption],
+        entry_name: str,
+    ) -> int | None:
+        selected_index = 0
+
+        while True:
+            height, width = stdscr.getmaxyx()
+            title_row = max(0, height - len(options) - 2)
+            title = f"Open '{entry_name}' with (↑/↓, Enter, Esc):"
+
+            stdscr.addnstr(
+                title_row,
+                0,
+                " " * max(0, width - 1),
+                max(0, width - 1),
+            )
+            stdscr.addnstr(
+                title_row,
+                0,
+                title,
+                max(0, width - 1),
+                curses.A_BOLD,
+            )
+
+            for index, option in enumerate(options):
+                row = title_row + index + 1
+                if row >= height:
+                    break
+
+                attributes = (
+                    curses.A_REVERSE if index == selected_index else curses.A_NORMAL
+                )
+                label = f"  {option.label}"
+                stdscr.addnstr(
+                    row,
+                    0,
+                    " " * max(0, width - 1),
+                    max(0, width - 1),
+                )
+                stdscr.addnstr(row, 0, label, max(0, width - 1), attributes)
+
+            stdscr.refresh()
+            key = stdscr.getch()
+
+            if key == ESCAPE_KEY:
+                return None
+
+            if key == curses.KEY_UP:
+                selected_index = move_selection(
+                    selected_index,
+                    step=-1,
+                    entry_count=len(options),
+                )
+                continue
+
+            if key == curses.KEY_DOWN:
+                selected_index = move_selection(
+                    selected_index,
+                    step=1,
+                    entry_count=len(options),
+                )
+                continue
+
+            if key in (curses.KEY_ENTER, 10, 13):
+                return selected_index
+
+    def _launch_blocking_with_terminal_restore(
+        self,
+        stdscr: curses.window | None,
+        path: Path,
+        option: OpenWithOption,
+    ) -> tuple[bool, str]:
+        if stdscr is None:
+            return launch_blocking_option(path, option)
+
+        curses.def_prog_mode()
+        curses.endwin()
+
+        try:
+            success, message = launch_blocking_option(path, option)
+        finally:
+            curses.reset_prog_mode()
+            stdscr.keypad(True)
+            stdscr.clear()
+            stdscr.refresh()
+
+        return success, message
+
    def _get_current_history_index(self, navigator: Navigator) -> int:
        history_entries = navigator.history.entries()

--- a/src/cd_browser_post_install.py
+++ b/src/cd_browser_post_install.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Post-install script for cd-browser to guide users on shell integration."""
+
+import os
+import sys
+
+
+def _profile_for_shell(shell: str) -> str:
+    if shell == "zsh":
+        return "~/.zshrc"
+
+    return "~/.bashrc"
+
+
+def _is_cd_function_present(profile_path: str) -> bool:
+    if not os.path.exists(profile_path):
+        return False
+
+    with open(profile_path, encoding="utf-8") as profile_file:
+        return "cd_() {" in profile_file.read()
+
+
+def main() -> None:
+    """Print shell integration instructions after installation."""
+    print("\n" + "=" * 60)
+    print("🎉 cd-browser installed successfully!")
+    print("=" * 60)
+    print()
+    print(
+        "To enable the 'cd_' command, you need to add a function to your shell profile."
+    )
+    print()
+
+    shell = os.environ.get("SHELL", "").split("/")[-1]
+    profile = _profile_for_shell(shell)
+
+    cd_function = """cd_() {
+  local target
+  target="$(cd_browser)" || return
+  if [ -n "$target" ] && [ -d "$target" ]; then
+    cd "$target"
+  fi
+}"""
+
+    print(f"Copy this to the end of {profile}:")
+    print()
+    print(cd_function)
+    print()
+
+    profile_path = os.path.expanduser(profile)
+
+    try:
+        response = (
+            input("Do you want me to add it automatically? (y/n): ").strip().lower()
+        )
+        if response == "y":
+            if _is_cd_function_present(profile_path):
+                print(f"\nℹ️ cd_() already exists in {profile}, no changes made.")
+            else:
+                with open(profile_path, "a", encoding="utf-8") as f:
+                    f.write("\n" + cd_function + "\n")
+                print(f"\n✅ Added to {profile}")
+            print(f"Run 'source {profile}' or restart your terminal to activate cd_.")
+        else:
+            print(f"\nAdd the function to {profile} manually.")
+            print(f"Then run 'source {profile}' or restart terminal.")
+    except EOFError:
+        print(
+            f"\nNo interactive input detected. Add the function to {profile} manually."
+        )
+        print(f"Then run 'source {profile}' or restart terminal.")
+    except KeyboardInterrupt:
+        print("\n\nSetup cancelled. You can add the function manually later.")
+        sys.exit(0)
+
+    print("\n" + "=" * 60)
+    print(
+        f"For uninstall: after 'pip uninstall cd-browser', remove cd_() from {profile}."
+    )
+    print("=" * 60 + "\n")
+
+
+if __name__ == "__main__":
+    main()
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -4,9 +4,10 @@ import pytest

 from app.cli import run_cli
 from app.navigator import Navigator
+from app.ui import TerminalUI


-class StubUI:
+class StubUI(TerminalUI):
    def __init__(self, result: Path) -> None:
        self.result = result
        self.navigator: Navigator | None = None
--- a/tests/test_filesystem.py
+++ b/tests/test_filesystem.py
@@ -2,7 +2,13 @@ from pathlib import Path

 import pytest

-from app.filesystem import DirectoryEntry, has_subdirectories, list_directories
+from app.filesystem import (
+    DirectoryEntry,
+    FileSystemEntry,
+    has_subdirectories,
+    list_directories,
+    list_entries,
+)


 def test_has_subdirectories_detects_nested_directory(tmp_path: Path) -> None:
@@ -44,3 +50,55 @@ def test_list_directories_raises_for_missing_directory(tmp_path: Path) -> None:

    with pytest.raises(FileNotFoundError):
        list_directories(missing_path)
+
+
+def test_list_entries_returns_files_when_include_files_enabled(tmp_path: Path) -> None:
+    folder = tmp_path / "folder"
+    file_path = tmp_path / "notes.txt"
+    folder.mkdir()
+    file_path.write_text("content", encoding="utf-8")
+
+    assert list_entries(tmp_path, include_files=True) == [
+        FileSystemEntry(
+            name="folder",
+            path=folder,
+            is_directory=True,
+            has_children=False,
+        ),
+        FileSystemEntry(
+            name="notes.txt",
+            path=file_path,
+            is_directory=False,
+            has_children=False,
+        ),
+    ]
+
+
+def test_list_directories_skips_permission_errors_for_children(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    allowed = root / "allowed"
+    blocked = root / "blocked"
+    allowed.mkdir()
+    blocked.mkdir()
+
+    blocked.chmod(0)
+    try:
+        entries = list_directories(root)
+    finally:
+        blocked.chmod(0o700)
+
+    assert any(entry.name == "allowed" for entry in entries)
+
+
+def test_has_subdirectories_returns_false_on_permission_error(tmp_path: Path) -> None:
+    blocked = tmp_path / "blocked"
+    blocked.mkdir()
+
+    blocked.chmod(0)
+    try:
+        result = has_subdirectories(blocked)
+    finally:
+        blocked.chmod(0o700)
+
+    assert result is False
--- a/tests/test_navigator.py
+++ b/tests/test_navigator.py
@@ -25,6 +25,49 @@ def test_navigator_initial_state_includes_parent_entry(tmp_path: Path) -> None:
    ]


+def test_toggle_hidden_directories(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    visible = root / "visible"
+    visible.mkdir()
+    hidden = root / ".hidden"
+    hidden.mkdir()
+
+    navigator = Navigator(root)
+
+    assert [entry.name for entry in navigator.visible_entries] == ["..", "visible"]
+
+    navigator.toggle_hidden()
+    assert navigator.show_hidden is True
+    assert [entry.name for entry in navigator.visible_entries] == [
+        "..",
+        ".hidden",
+        "visible",
+    ]
+
+    navigator.toggle_hidden()
+    assert navigator.show_hidden is False
+    assert [entry.name for entry in navigator.visible_entries] == ["..", "visible"]
+
+
+def test_toggle_files_includes_files_in_visible_entries(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    (root / "folder").mkdir()
+    (root / "notes.txt").write_text("hello", encoding="utf-8")
+
+    navigator = Navigator(root)
+    assert [entry.name for entry in navigator.visible_entries] == ["..", "folder"]
+
+    navigator.toggle_files()
+    assert navigator.show_files is True
+    assert [entry.name for entry in navigator.visible_entries] == [
+        "..",
+        "folder",
+        "notes.txt",
+    ]
+
+
 def test_expand_selected_directory_reveals_nested_entries(tmp_path: Path) -> None:
    current = tmp_path / "workspace"
    current.mkdir()
--- a/tests/test_opener.py
+++ b/tests/test_opener.py
@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from pathlib import Path
+from subprocess import CompletedProcess
+
+import pytest
+
+from app.opener import (
+    OpenWithOption,
+    available_openers,
+    is_blocking_option,
+    launch_background_option,
+    launch_blocking_option,
+)
+
+
+def test_available_openers_headless_file_excludes_gui(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    file_path = tmp_path / "notes.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    monkeypatch.setenv("SSH_CONNECTION", "1")
+
+    available = {
+        "antigravity": "/usr/local/bin/antigravity",
+        "nvim": "/usr/local/bin/nvim",
+        "nano": "/usr/bin/nano",
+        "less": "/usr/bin/less",
+        "bat": "/usr/local/bin/bat",
+        "code": "/usr/local/bin/code",
+        "open": "/usr/bin/open",
+    }
+    monkeypatch.setattr("app.opener.shutil.which", lambda name: available.get(name))
+
+    labels = [option.label for option in available_openers(file_path)]
+
+    assert "VS Code" not in labels
+    assert "Open (system)" not in labels
+    assert labels == ["Antigravity", "Neovim", "Nano", "Less", "Bat"]
+
+
+def test_available_openers_gui_directory_filters_file_only_tools(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    folder = tmp_path / "project"
+    folder.mkdir()
+
+    monkeypatch.delenv("SSH_CONNECTION", raising=False)
+    monkeypatch.setattr("app.opener.sys.platform", "darwin")
+
+    available = {
+        "antigravity": "/usr/local/bin/antigravity",
+        "nvim": "/usr/local/bin/nvim",
+        "nano": "/usr/bin/nano",
+        "less": "/usr/bin/less",
+        "bat": "/usr/local/bin/bat",
+        "code": "/usr/local/bin/code",
+        "open": "/usr/bin/open",
+    }
+    monkeypatch.setattr("app.opener.shutil.which", lambda name: available.get(name))
+
+    labels = [option.label for option in available_openers(folder)]
+
+    assert labels == ["VS Code", "Antigravity", "Neovim"]
+
+
+def test_launch_background_option_returns_success(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    option = OpenWithOption(
+        label="VS Code",
+        command_template="code {path}",
+        executable="code",
+        launch_mode="background",
+        requires_gui=True,
+    )
+
+    monkeypatch.setattr("app.opener.subprocess.Popen", lambda *args, **kwargs: None)
+
+    success, message = launch_background_option(tmp_path, option)
+
+    assert success is True
+    assert "VS Code" in message
+
+
+def test_launch_blocking_option_reports_non_zero_exit(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    option = OpenWithOption(
+        label="Neovim",
+        command_template="nvim {path}",
+        executable="nvim",
+        launch_mode="blocking",
+    )
+
+    monkeypatch.setattr(
+        "app.opener.subprocess.run",
+        lambda *args, **kwargs: CompletedProcess(args=[], returncode=2),
+    )
+
+    success, message = launch_blocking_option(tmp_path, option)
+
+    assert success is False
+    assert "code 2" in message
+
+
+def test_is_blocking_option_uses_launch_mode() -> None:
+    blocking = OpenWithOption(
+        label="Neovim",
+        command_template="nvim {path}",
+        executable="nvim",
+        launch_mode="blocking",
+    )
+    background = OpenWithOption(
+        label="VS Code",
+        command_template="code {path}",
+        executable="code",
+        launch_mode="background",
+    )
+
+    assert is_blocking_option(blocking) is True
+    assert is_blocking_option(background) is False
+
+
+def test_launch_blocking_option_handles_paths_with_spaces(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    target_path = tmp_path / "COMPETENCIAS A.LEDO"
+    option = OpenWithOption(
+        label="Neovim",
+        command_template="nvim {path}",
+        executable="nvim",
+        launch_mode="blocking",
+    )
+    captured: dict[str, list[str]] = {}
+
+    def fake_run(command: list[str], check: bool) -> CompletedProcess[object]:
+        captured["command"] = command
+        return CompletedProcess(args=[], returncode=0)
+
+    monkeypatch.setattr("app.opener.subprocess.run", fake_run)
+
+    success, _message = launch_blocking_option(target_path, option)
+
+    assert success is True
+    assert captured["command"] == ["nvim", str(target_path)]
--- a/tests/test_post_install.py
+++ b/tests/test_post_install.py
@@ -0,0 +1,47 @@
+from pathlib import Path
+
+import pytest
+
+from cd_browser_post_install import main
+
+CD_FUNCTION_SNIPPET = "cd_() {"
+
+
+def test_post_install_handles_eof_without_crashing(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv("SHELL", "/bin/zsh")
+    monkeypatch.setattr(
+        "builtins.input", lambda _prompt: (_ for _ in ()).throw(EOFError)
+    )
+
+    main()
+
+    output = capsys.readouterr().out
+    assert "No interactive input detected" in output
+    assert "source ~/.zshrc" in output
+
+
+def test_post_install_adds_cd_function_once(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv("SHELL", "/bin/zsh")
+    monkeypatch.setenv("HOME", str(tmp_path))
+
+    responses = iter(["y", "y"])
+    monkeypatch.setattr("builtins.input", lambda _prompt: next(responses))
+
+    main()
+    main()
+
+    profile_path = tmp_path / ".zshrc"
+    content = profile_path.read_text(encoding="utf-8")
+
+    assert content.count(CD_FUNCTION_SNIPPET) == 1
+
+    output = capsys.readouterr().out
+    assert "already exists" in output
+    assert "source ~/.zshrc" in output
--- a/tests/test_ui.py
+++ b/tests/test_ui.py
@@ -52,6 +52,19 @@ def test_format_entry_supports_parent_and_tree_indicators(tmp_path: Path) -> Non
    assert format_entry(expanded_child) == "      build"


+def test_format_entry_marks_files_with_file_indicator(tmp_path: Path) -> None:
+    file_entry = VisibleEntry(
+        name="notes.txt",
+        path=tmp_path / "notes.txt",
+        depth=0,
+        has_children=False,
+        is_expanded=False,
+        is_file=True,
+    )
+
+    assert format_entry(file_entry) == "• notes.txt"
+
+
 def test_build_render_lines_marks_selected_entry(tmp_path: Path) -> None:
    workspace = tmp_path / "workspace"
    workspace.mkdir()
@@ -221,6 +234,112 @@ def test_enter_returns_selected_path_without_navigating(tmp_path: Path) -> None:
    assert navigator.current_path == workspace.resolve()


+def test_toggle_files_key_updates_navigator_state(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    (root / "folder").mkdir()
+    (root / "notes.txt").write_text("content", encoding="utf-8")
+
+    navigator = Navigator(root)
+    ui = TerminalUI()
+
+    assert navigator.show_files is False
+    assert ui._handle_tree_key(ord("a"), navigator) is None
+    assert navigator.show_files is True
+
+
+def test_filter_matching_is_case_insensitive(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    (root / "Alpha").mkdir()
+    (root / "beta").mkdir()
+
+    navigator = Navigator(root)
+    ui = TerminalUI()
+    ui._filter_mode = True
+    ui._filter_query = "alp"
+
+    matches = ui._matching_indices(navigator.visible_entries)
+
+    assert matches == [1]
+
+
+def test_filter_mode_uses_g_and_g_upper_as_query_characters(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    (root / "alpha").mkdir()
+    (root / "gamma").mkdir()
+
+    navigator = Navigator(root)
+    ui = TerminalUI()
+    ui._filter_mode = True
+
+    assert ui._handle_filter_key(ord("g"), navigator) is None
+    assert ui._handle_filter_key(ord("G"), navigator) is None
+    assert ui._filter_query == "gG"
+
+
+def test_filter_enter_on_directory_navigates_and_exits_filter(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    child = root / "child"
+    root.mkdir()
+    child.mkdir()
+
+    navigator = Navigator(root)
+    ui = TerminalUI()
+    ui._filter_mode = True
+    ui._filter_query = "child"
+
+    result = ui._handle_filter_key(10, navigator)
+
+    assert result is None
+    assert ui._filter_mode is False
+    assert navigator.current_path == child.resolve()
+
+
+def test_filter_enter_on_file_opens_menu_and_exits_filter(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    file_path = root / "notes.txt"
+    file_path.write_text("hello", encoding="utf-8")
+
+    navigator = Navigator(root)
+    navigator.toggle_files()
+    ui = TerminalUI()
+    ui._filter_mode = True
+    ui._filter_query = "notes"
+    opened: dict[str, bool] = {"called": False}
+
+    def fake_open_with_selected(
+        _navigator: Navigator, _stdscr: curses.window | None
+    ) -> None:
+        opened["called"] = True
+
+    monkeypatch.setattr(ui, "_open_with_selected", fake_open_with_selected)
+
+    result = ui._handle_filter_key(10, navigator)
+
+    assert result is None
+    assert ui._filter_mode is False
+    assert opened["called"] is True
+    assert navigator.selected_entry.path == file_path.resolve()
+
+
+def test_end_key_jumps_to_last_entry(tmp_path: Path) -> None:
+    root = tmp_path / "root"
+    root.mkdir()
+    for name in ("alpha", "beta", "gamma"):
+        (root / name).mkdir()
+
+    navigator = Navigator(root)
+    ui = TerminalUI()
+
+    assert ui._handle_tree_key(curses.KEY_END, navigator) is None
+    assert navigator.selected_index == len(navigator.visible_entries) - 1
+
+
 def test_open_terminal_streams_raises_without_terminal(
    monkeypatch: pytest.MonkeyPatch,
 ) -> None:
Author	SHA1	Message	Date
Saky	6f78f6d9ca	release: 0.2.6 add advanced navigation and contextual open actions	2026-04-04 01:53:00 +02:00
Saky	8259b2e132	release: 0.2.5 add repository link for PyPI users	2026-04-03 22:51:08 +02:00
Saky	4052c6f71f	release: 0.2.4 fix PyPI README gif rendering	2026-04-03 21:30:40 +02:00
Saky	0e94895349	merge: bring 0.2.x releases into main	2026-04-03 21:14:23 +02:00
Saky	d9cf164b2c	release: 0.2.3 add demo gif	2026-04-02 22:38:42 +02:00
Saky	a64bc768b5	release: 0.2.2 fix post-install packaging and robustness	2026-04-02 21:35:45 +02:00
Saky	f7f09b895d	feat: update pyproject.toml for PyPI release - Lower Python requirement to >=3.8 for broader compatibility - Update version to 0.1.1 - Add classifiers for better PyPI discoverability - Fix description to match cd-browser functionality	2026-04-02 17:06:16 +02:00
Saky	10c3849fb3	cleanup: remove AI internal files for public repo focus - Removed AGENT.md, AGENT_WORKFLOW.md, AI_TASK_TEMPLATE.md, instructions-agent.md - These were internal AI development tools, not needed for end-users - Repository now cleaner and more product-focused - Files can be recovered from git history if needed for future development	2026-04-02 16:48:58 +02:00
Saky	f28fef7758	docs: update changelog with hidden toggle feature	2026-04-02 16:45:15 +02:00
Saky	ab689cfbb4	feat: toggle hidden directories in cd-browser with . key	2026-04-02 16:28:21 +02:00
Saky	9688ed0974	docs: update changelog and readme for cd-browser v0.1.1	2026-04-02 16:00:06 +02:00
Saky	d9d412973b	feat: finalize AI logging framework and workflow - align instructions, workflow rules, and task template with three-level logging - extend ai-task generation to support execution-log requirements - update worklog, prompt log, and execution log for the finalized framework - validate the framework with generator and project quality checks	2026-03-16 03:00:39 +01:00
Saky	9704d3ef5b	docs: improve AI agent workflow and instruction framework - strengthen agent workflow rules and commit/log ordering - improve AI logging instructions and traceability - add agent framework documents and task generation tooling - keep repository workflow consistent for future AI-assisted tasks	2026-03-16 02:00:18 +01:00
Saky	0118ad9314	docs: record AI agent framework task logs	2026-03-16 01:47:57 +01:00
Saky	e766210920	feat: introduce AI agent framework and task tooling - add AGENT.md describing the agent system - add AGENT_WORKFLOW.md defining the execution workflow - add AI_TASK_TEMPLATE.md for structured task prompts - add scripts/ai-task CLI tool for generating standardized agent tasks	2026-03-16 01:38:36 +01:00
Saky	6849631cc1	docs: finalize AI logging format system - align ai-worklog and ai-prompts with the current logging framework - require timestamped structured log entries - finalize logging rules in instructions-agent.md	2026-03-16 01:33:02 +01:00