First Release

doc/README.md

@@ -0,0 +1,13 @@
+# Documentation Index
+
+This directory contains project documentation for `git-tui`.
+
+## Modules
+
+- [`doc/architecture.md`](architecture.md) - architecture and module responsibilities.
+- [`doc/usage.md`](usage.md) - installation, runtime requirements, and user workflow.
+
+## Conventions
+
+- Keep public behavior changes documented in both module docs and `CHANGELOG.md`.
+- Keep this index updated when adding documentation modules.

doc/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+## Overview
+
+`git-tui` is a single executable Python script that provides a terminal UI for common Git commands.
+
+## Module Responsibilities
+
+- `git-tui`:
+  - Initializes and runs the curses application loop.
+  - Renders a menu-driven UI with keyboard navigation.
+  - Executes Git subprocess commands and displays command output.
+  - Implements file selection for staged and unstaged operations.
+
+## Public API and Contracts
+
+- Command entry point: `git-tui` executable script.
+- Runtime contract:
+  - Must be executed in a terminal that supports curses.
+  - Must be run from a directory inside a Git working tree.
+  - Requires `git` to be installed and available in `PATH`.
+
+## Data Model
+
+- `ChangedFile`:
+  - `index_status`: index status marker from `git status --short`.
+  - `worktree_status`: worktree status marker from `git status --short`.
+  - `path`: repository-relative file path.
+
+## Build and Deployment Rules
+
+- No build step is required.
+- Deployment is a direct executable file install (copy or symlink).
+
+## Cross References
+
+- Usage and install details: [`doc/usage.md`](usage.md)
+- Change tracking: [`CHANGELOG.md`](../CHANGELOG.md)

doc/usage.md

@@ -0,0 +1,53 @@
+# Usage
+
+## Environment Requirements
+
+- Linux or Unix-like terminal environment with curses support.
+- Python 3 interpreter available as `python3`.
+- Git installed and available in `PATH`.
+
+## Installation
+
+1. Make the script executable:
+   ```bash
+   chmod +x git-tui
+   ```
+2. Install as a memorable command name (example: `gtui`):
+   ```bash
+   sudo install -m 755 git-tui /usr/local/bin/gtui
+   ```
+
+## Running
+
+- Enter any Git repository and run:
+  ```bash
+  gtui
+  ```
+
+## Key Commands in UI
+
+- Main menu:
+  - `Up/Down` or `j/k` to move.
+  - `Enter` to execute selected action.
+  - `q` or `Esc` to quit.
+- File selector:
+  - `Space` to toggle file selection.
+  - `a` to toggle all files.
+  - `Enter` to confirm.
+  - `q` or `Esc` to cancel.
+
+## Git Operations Covered
+
+- Stage all changes (`git add -A`).
+- Stage selected files (`git add -- <paths...>`).
+- Unstage selected files (`git restore --staged -- <paths...>`).
+- Commit staged changes (`git commit -m "<message>"`).
+- Push current branch (`git push`).
+- Pull with rebase (`git pull --rebase`).
+- Fetch all remotes (`git fetch --all --prune`).
+- Show full status (`git status`).
+
+## Cross References
+
+- Architecture and contracts: [`doc/architecture.md`](architecture.md)
+- Change history: [`CHANGELOG.md`](../CHANGELOG.md)