Skip to content

Simplify Enter navigation and add complete MDA documentation - #54

Open
B0LK13 wants to merge 3 commits into
mainfrom
docs/complete-readme
Open

B0LK13 wants to merge 3 commits into
mainfrom
docs/complete-readme

Conversation

@B0LK13

@B0LK13 B0LK13 commented Nov 14, 2026

Copy link
Copy Markdown
Collaborator

Why

The published repository was behind the tested local installation, and the old README did not accurately describe the workflow. This PR publishes the Enter navigation, the existing local in-place protections, and a complete Dutch user guide together so the documented behavior matches the code.

Changes

  • Open one file browser directly. Enter opens a directory or processes only the highlighted file; mouse clicks remain selection/preview actions.
  • Keep the main footer focused on Enter, Backspace, help, and quit. Put advanced shortcuts in the help overlay, prevent overlapping runs, and remember the last browsed folder.
  • Include the previously local in-place workflow: show a diff, request confirmation per changed file, back up the original, detect source changes, and verify written content. TUI in-place processing remains blocked until it supports diff approval.
  • Replace the README with a complete guide covering setup, providers, skills, CLI options, configuration, outputs, JSONL, troubleshooting, and development.
  • Document the current limitations accurately, including the PDF/DOCX provider route, editable installation requirement, explicit OpenRouter model selection in the TUI, and experimental vault helpers.

Validation

Recorded validation for the included implementation:

  • python -m pytest -q -m "not integration": 107 passed, 1 deselected, including 22 TUI tests.
  • Installed Linux/pipx runtime smoke: Enter opens a folder and triggers exactly one processing call for the highlighted synthetic file.
  • Provider boundaries were mocked for the UI checks; no live model request was used.
  • Ruff passed for the changed TUI/CLI/TUI-test files; Python compilation and Git whitespace checks passed.
  • README internal links and all 34 Bash code blocks were checked; five documented read-only/dry-run commands were exercised with temporary files.

Review notes

This PR includes the three local commits f685212, c83f473, and 2e07dba, based on main at b86c7f3. The package version remains 0.2.9 and the changes are recorded under Unreleased.

Existing PRs #16 and #49–#53 also touch stabilization, TUI, providers, or backups. Account for those overlapping changes when choosing the merge order.

The documented pre-existing limitations remain open. This publication is a branch and pull request; it does not create a release.

B0LK13 and others added 3 commits November 14, 2026 16:40
--in-place now shows a diff per file and writes only after a yes
(--yes skips the prompt; required when stdin is not a terminal).
The original is always copied to the backup dir first
(--backup-dir, MDA_BACKUP_DIR, default ~/home/backups-obsidian) as
<YYYYMMDD>/<vault>/<path>.<sha256[:8]>.bak, so no sibling .bak files
are left in the vault. --backup becomes a deprecated no-op.

In-place writes are refused when the source changed since it was
read, and the written bytes are read back and compared. The TUI
blocks in-place mode until it can show the per-file diff.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant