[docs] add initial TODO.md with actionable backlog and prioritization

README.md

@@ -9,19 +9,35 @@ Key features
 - GPU backend selection at runtime; auto-detects available accelerators.
 - Clean outputs (JSON and SRT), speaker naming prompts, and useful logging controls.
 
-Quickstart
-1) Install Rust (rustup) and ffmpeg, then build:
-- rustup install stable
-- rustup default stable
-- cargo build --release
+Prerequisites
+- Rust toolchain (rustup recommended)
+- ffmpeg available on PATH
+- Optional for GPU acceleration at runtime: CUDA, ROCm/HIP, or Vulkan drivers (match your build features)
 
-2) Download a model (first run can prompt you):
+Installation
+- Build from source (CPU-only by default):
+  - rustup install stable
+  - rustup default stable
+  - cargo build --release
+- Binary path: ./target/release/polyscribe
+- GPU builds (optional): build with features
+  - CUDA: cargo build --release --features gpu-cuda
+  - HIP: cargo build --release --features gpu-hip
+  - Vulkan: cargo build --release --features gpu-vulkan
+
+Quickstart
+1) Download a model (first run can prompt you):
 - ./target/release/polyscribe --download-models
 
-3) Transcribe a file:
+2) Transcribe a file:
 - ./target/release/polyscribe -v -o output my_audio.mp3
 This writes JSON and SRT into the output directory with a date prefix.
 
+Shell completions and man page
+- Completions: ./target/release/polyscribe completions <bash|zsh|fish|powershell|elvish> > polyscribe.<ext>
+  - Then install into your shell’s completion directory.
+- Man page: ./target/release/polyscribe man > polyscribe.1 (then copy to your manpath)
+
 Model locations
 - Development (debug builds): ./models next to the project.
 - Packaged/release builds: $XDG_DATA_HOME/polyscribe/models or ~/.local/share/polyscribe/models.
@@ -50,21 +66,12 @@ Minimal usage examples
 - Update local models non-interactively (good for CI):
   - ./target/release/polyscribe --update-models --no-interaction -q
 
-Running tests and tools
-- cargo test
-- cargo clippy --all-targets -- -D warnings
-- cargo build (preferably without warnings)
-
-Model downloader
-- Interactive: ./target/release/polyscribe --download-models
-- Non-interactive: relies on defaults; set WHISPER_MODEL or POLYSCRIBE_MODELS_DIR when needed.
-
-Documentation index
+Troubleshooting & docs
+- docs/faq.md – common issues and solutions (missing ffmpeg, GPU selection, model paths)
 - docs/usage.md – complete CLI reference and workflows
 - docs/development.md – build, run, and contribute locally
 - docs/design.md – architecture overview and decisions
 - docs/release-packaging.md – packaging notes for distributions
-- docs/faq.md – common issues and solutions
 - docs/ci.md – minimal CI checklist and job outline
 - CONTRIBUTING.md – PR checklist and workflow
 
@@ -78,5 +85,4 @@ See the examples/ directory for copy-paste scripts:
 
 License
 -------
-
 This project is licensed under the MIT License — see the LICENSE file for details.

TODO.md

@@ -0,0 +1,158 @@
+This is a prioritized, actionable backlog to guide short-term improvements. Each item includes a short description,
+priority, estimated effort, suggested owner(s), and acceptance criteria. Use this as a living document — update status
+and estimates as you make progress.
+
+## How to use
+
+- Priority: P0 (highest), P1, P2.
+- Effort: S (small, <1 week), M (medium, 1–2 weeks), L (large, 2+ weeks).
+- Owner: team or role that should pick it up.
+- AC: acceptance criteria — what "done" looks like.
+
+---
+
+## 1. Populate this README & quickstart (P0, S)
+
+- Description: Add a short README and a "Getting started" quickstart with environment setup, how to run locally, and how
+  to run tests.
+- Owner: Developer / Docs
+- Effort: S
+- Acceptance criteria:
+    - README contains: purpose, prerequisites, install steps, run steps, test command.
+    - Quickstart reproduces a working dev environment on a fresh machine.
+    - One developer verified it following the instructions.
+
+## 2. First-run onboarding & demo data (P0, M)
+
+- Description: Add an interactive first-run walkthrough and an optional "Try demo" mode that populates safe sample data.
+- Owner: Product / Frontend
+- Effort: M
+- Acceptance criteria:
+    - First-run modal guides through top 3 core actions.
+    - Demo mode populates a non-destructive dataset and can be reset.
+    - Onboarding completion is tracked via an analytics event.
+
+## 3. Instrument basic analytics & events (P0, M)
+
+- Description: Add event instrumentation for key flows to measure adoption and drop-offs (onboarding, critical actions,
+  errors).
+- Owner: Engineering / Product
+- Effort: M
+- Acceptance criteria:
+    - Tracking for: onboarding_start, onboarding_complete, core_action_X, error_high_priority.
+    - Events include a minimal context payload (non-sensitive): user-agnostic session id, event name, timestamp.
+    - Privacy opt-out toggle exists in settings.
+
+## 4. Improve error messages & in-app help (P0, S)
+
+- Description: Replace generic errors with actionable messages and add a Help/FAQ entry and a "Report a bug" flow that
+  optionally attaches logs.
+- Owner: Frontend / QA
+- Effort: S
+- Acceptance criteria:
+    - Top 10 most common errors have specific messages and suggested next steps.
+    - A simple Help view exists with links to docs and a one-click "Report issue" action that collects an anonymized log
+      bundle (with consent).
+
+## 5. Add basic structured logging & correlation IDs (P1, M)
+
+- Description: Implement structured logs and add correlation IDs to sessions/requests to make debugging easier from logs
+  and error reports.
+- Owner: Backend / Infra
+- Effort: M
+- Acceptance criteria:
+    - Logs emitted in JSON or consistent structured format.
+    - Correlation ID generated per session/request and included in error logs and any bug reports.
+    - Document how to search logs by correlation ID.
+
+## 6. CI: run tests, linter, and basic checks on PRs (P1, M)
+
+- Description: Add a CI pipeline that runs unit tests, a formatter/linter, and basic build checks for each PR.
+- Owner: DevOps / Engineering
+- Effort: M
+- Acceptance criteria:
+    - PRs are blocked from merging if tests fail or the linter/format checks fail.
+    - Developers can run the same checks locally via a single script or Makefile.
+
+## 7. Add automated end-to-end tests for critical flow(s) (P1, L)
+
+- Description: Create a small suite of E2E tests that cover onboarding, signing in (if relevant), and the main user
+  flow.
+- Owner: QA / Engineering
+- Effort: L
+- Acceptance criteria:
+    - At least 3 E2E tests added and green in CI.
+    - Tests are stable and do not flake more than a predefined threshold.
+    - Documentation on how to run and update tests exists.
+
+## 8. Performance profiling and one optimization (P2, M)
+
+- Description: Run a lightweight performance profile (CPU/memory) on the key path and implement one low-effort,
+  high-impact optimization (e.g., lazy-load a heavy module or add caching).
+- Owner: Engineering
+- Effort: M
+- Acceptance criteria:
+    - Profile data collected and summarized (top 5 hotspots).
+    - One optimization implemented with measurable improvement (e.g., 20% faster load or 30% memory reduction).
+    - Benchmarks recorded in the repo.
+
+## 9. Output templates: add predefined template flags (P1, M)
+
+- Description: Provide CLI/UI flags to select from a set of predefined output templates (for example: json, csv, pretty,
+  report, compact). Each template controls formatting, default file extension, and optional post-processing steps.
+- Owner: Product / CLI / Frontend
+- Effort: M
+- Acceptance criteria:
+    - Add flag (CLI): `--template <template_name>` and (UI) template selector in export dialog.
+    - Supported predefined templates documented (name, description, default extension).
+    - Template selection influences output format and default file extension automatically.
+    - Invalid template name produces a helpful error with a list of valid templates.
+    - Unit tests cover at least 3 templates and the error path.
+
+## 10. Output templates: add custom template paste & output extension flag (P1, M)
+
+- Description: Allow users to paste/provide a custom template (e.g., Mustache, Go template, or simple placeholder
+  format) and specify output extension via flag or UI input. Support local validation and a preview before writing
+  output.
+- Owner: Product / CLI / Frontend
+- Effort: M
+- Acceptance criteria:
+    - Add flag (CLI): `--custom-template-file <path>` or `--template-paste '<template_string>'`.
+    - Add flag (CLI): `--out-ext <extension>` and (UI) an "Output filename/extension" input.
+    - Validate custom template at input time and show errors if malformed (with line/column hints when possible).
+    - Provide a preview option that renders a sample using demo data before saving.
+    - When `--out-ext` is provided, output file uses that extension; otherwise, use template's default extension or
+      fallback to `.txt`.
+    - Security: sanitize template execution context to avoid code injection; document limitations.
+    - Tests cover custom-template validation, preview rendering, and output extension resolution.
+
+---
+
+## Nice-to-have / Future items (P2)
+
+- Accessibility audit and WCAG fixes (keyboard nav, aria labels).
+- Feature flagging support for experimental rollouts.
+- Localization prep (externalize strings).
+- Observability: dashboards for errors, latency, adoption (define SLOs).
+
+## Developer experience & contributor friendliness
+
+- Improve README and contributing guide
+    - Add quickstart, environment setup, testing and release instructions.
+- Add a clear issue/tracking template
+    - Bug template, feature-request template, and PR template to standardize contributions.
+- Developer tooling
+    - Add static analysis tools, formatters, and pre-commit hooks to keep code consistent.
+
+## Quality of life improvements (UX polish)
+
+- Dark mode and theme support
+- Keyboard-driven shortcuts and quick actions
+- Contextual undo/redo where destructive actions exist
+- Consistent microcopy and confirmation flows for destructive operations
+
+## Low-effort, high-value items to implement now
+
+- Add a single “Contact support / report a bug” action that attaches logs and repro steps (with user consent).
+- Add usage telemetry opt-in/opt-out and a privacy policy summary.
+- Implement a lightweight feature-usage dashboard to see which features customers actually use.