Refocus README on users

[sri-rang]

Summary

• rewrite the README as a concise, privacy-focused product introduction with a four-image screenshot gallery
• move development and automatic-paste details into focused documentation guides
• preserve installed documentation links and add regression checks for links, assets, and uninstall cleanup
• stabilize asynchronous managed-model invalidation coverage

Closes #39

Validation

• make screenshots — passed; four 1140×780 Plasma-themed images visually inspected
• ctest --test-dir build -R '^model-manager$' --repeat until-fail:100 --output-on-failure — passed; 100/100 repetitions
• make lint — passed
• make test — passed; 11/11 tests
• make install-smoke — passed
• make validate — passed; 11/11 tests

[qodo-code-review]

PR Summary by Qodo

Refocus README on users and harden installed documentation checks

📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Rewrite README into a user-focused, privacy-first overview with a 4-image screenshot gallery.
• Move development and automatic-paste setup into dedicated docs and link them from README.
• Install docs/assets and add regression checks for links, assets, and uninstall cleanup.

Diagram

graph TD
  docs["Docs markdown"] --> cmake["CMake install rules"] --> installdocs[("Installed docs")]
  shots["Screenshots PNGs"] --> cmake
  installdocs --> smoke["make install-smoke"] --> linkcheck[["Link checker"]]
  repo["Source tree"] --> ctest["CTest doc test"] --> linkcheck
  subgraph Legend
    direction LR
    _md["Markdown/file"] ~~~ _proc["Build step"] ~~~ _dir[("Install dir")] ~~~ _scr[["Script"]]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use an off-the-shelf link checker (e.g., lychee/markdown-link-check)

• ➕ Less custom parsing logic to maintain
• ➕ Often supports more markdown edge cases and richer reporting
• ➖ Adds a runtime dependency (and potentially network behavior) to tests/CI
• ➖ Harder to guarantee availability across developer distros without bootstrapping

2. Run documentation checks only in CI (not as a CTest target)

• ➕ Keeps local test surface area smaller
• ➕ Avoids surprising failures for contributors running ctest
• ➖ Broken docs/asset links can linger longer before being caught
• ➖ Packagers/integrators lose an easy local validation hook

Recommendation: The PR’s approach (a small, dependency-free shell checker integrated into both CTest and install-smoke) is a good fit for an offline/privacy-focused project and for catching packaging regressions. The main tradeoff is maintaining the awk-based markdown parsing, but it’s scoped to relative links/images and heading anchors, which keeps it manageable.

Files changed (10) +420 / -243 · 4 not counted

Documentation (7) +315 / -240

README.mdRewrite README as user-facing overview with privacy section and gallery +90/-240

Rewrite README as user-facing overview with privacy section and gallery

• Replaces developer/setup-heavy content with a concise product introduction, a four-image screenshot gallery, usage flow, and a detailed privacy/trust section. Moves build/development and automatic paste setup details out to dedicated guides and adds a consolidated help/links section.

README.md

AUTOMATIC_PASTE.mdAdd focused automatic paste setup, troubleshooting, and security notes +82/-0

Add focused automatic paste setup, troubleshooting, and security notes

• Introduces a dedicated guide for installing and enabling paste helpers on Plasma Wayland/X11, including ydotoold troubleshooting steps. Documents security and privacy considerations and links back to the README and development guide.

docs/AUTOMATIC_PASTE.md

DEVELOPMENT.mdAdd development/install/packaging guide and contributor tooling reference +143/-0

Add development/install/packaging guide and contributor tooling reference

• Adds a comprehensive development guide covering dependencies, build/run, install/uninstall behavior, distribution packaging knobs, and a high-level architecture summary. Documents validation targets (tests, coverage, screenshots, lint, install-smoke, validate) and editor/roadmap notes.

docs/DEVELOPMENT.md

01-offline-dictation.pngRefresh offline dictation screenshot asset _{not counted}

Refresh offline dictation screenshot asset

• Updates the PNG screenshot used in the README gallery and installed documentation assets.

screenshots/01-offline-dictation.png

02-speech-models.pngRefresh speech models screenshot asset _{not counted}

Refresh speech models screenshot asset

• Updates the PNG screenshot used in the README gallery and installed documentation assets.

screenshots/02-speech-models.png

03-audio-input.pngRefresh audio input screenshot asset _{not counted}

Refresh audio input screenshot asset

• Updates the PNG screenshot used in the README gallery and installed documentation assets.

screenshots/03-audio-input.png

04-settings.pngRefresh settings screenshot asset _{not counted}

Refresh settings screenshot asset

• Updates the PNG screenshot used in the README gallery and installed documentation assets.

screenshots/04-settings.png

Other (3) +105 / -3

CMakeLists.txtInstall docs/screenshots and add documentation-links CTest +15/-2

Install docs/screenshots and add documentation-links CTest

• Extends installation rules to ship README, new documentation guides, screenshots, and relocates the license into a LICENSES subdirectory. Adds a BUILD_TESTING CTest entry that runs the documentation link checker against the source tree.

CMakeLists.txt

MakefileValidate installed documentation and uninstall cleanup in install-smoke +19/-1

Validate installed documentation and uninstall cleanup in install-smoke

• Enhances install-smoke to assert installed doc files (README, guides, screenshots, license) and to run the link checker against the installed doc root. Updates uninstall to remove the newly installed docs/assets and also cleans up a legacy top-level license path for regression coverage.

Makefile

check-documentation-links.shAdd script to verify relative doc links, images, and heading anchors +71/-0

Add script to verify relative doc links, images, and heading anchors

• Adds a portable shell script that scans README/docs markdown links and HTML img src attributes, verifies referenced relative files exist, and optionally checks that fragment links resolve to generated heading slugs. Intended for both CTest (source tree) and install-smoke (installed docs) regression coverage.

tools/check-documentation-links.sh

[qodo-code-review]

Code Review by Qodo

Great, no actions required

You can view lower severity findings below.

View more (2)

1. DEVELOPMENT.md uses non-ASCII × 📘 Rule violation ✧ Quality

Description

docs/DEVELOPMENT.md and README.md introduce non-ASCII characters (e.g., × and —), violating
the English-only ASCII literal requirement. This can lead to inconsistent rendering or failures in
tooling/pipelines that assume ASCII-only content.

Code

docs/DEVELOPMENT.md[114]

+`make screenshots` renders all four top-level views in a 760×520 logical window with deterministic

Evidence

PR Compliance ID 576985 requires all newly added or modified string content to contain only ASCII
characters. The cited documentation line includes 760×520, where the multiplication sign × is a
non-ASCII character, and the cited README line contains an em dash —, which is also a non-ASCII
code point (>127); these citations directly demonstrate the rule violation in the updated text.

Rule 576985: Enforce English-only string literals in code
docs/DEVELOPMENT.md[114-114]
README.md[17-17]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/DEVELOPMENT.md` and `README.md` contain non-ASCII characters (e.g., `×` in a resolution and an em dash `—`), which violates the policy requiring English-only ASCII string content.
## Issue Context
PR Compliance ID 576985 requires all newly added/modified string content to use ASCII-only characters; both `×` and `—` are outside the ASCII range and may break or behave inconsistently in ASCII-only tooling (linters, parsers, or downstream packaging/processing pipelines).
## Fix Focus Areas
- docs/DEVELOPMENT.md[114-114]
- README.md[17-17]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Pipeline masks find failures ✓ Resolved 🐞 Bug ☼ Reliability

Description

tools/check-documentation-links.sh builds the markdown file list with a find | while pipeline, so
a failing find can be ignored and the script may still exit 0 under set -e. This can make the
new documentation-links CTest and install-smoke checks pass even when the docs tree was only
partially scanned.

Code

tools/check-documentation-links.sh[R16-19]

+{
+    test -f "$documentation_root/README.md" && printf '%s\n' "$documentation_root/README.md"
+    if [ -d "$documentation_root/docs" ]; then
+        find "$documentation_root/docs" -type f -name '*.md' -print

Evidence

The file enumeration uses find upstream of a pipeline into a while loop, and the script only
sets -eu (no pipefail in POSIX sh), so find errors may not affect the script exit code. The
script is then directly wired into both CTest and install-smoke, so a false pass reduces regression
coverage.

tools/check-documentation-links.sh[16-22]
CMakeLists.txt[260-263]
Makefile[84-93]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`tools/check-documentation-links.sh` uses a `find | while ...` pipeline to enumerate markdown files. In POSIX `sh`, the pipeline exit status is that of the `while` loop, so `find` failures (permissions/IO errors) may not fail the script even with `set -e`, reducing the reliability of the new doc-link regression test.
## Issue Context
This script is executed in both CI contexts:
- As a CTest (`documentation-links`) from CMake.
- From `make install-smoke` against the installed doc tree.
## Fix Focus Areas
- tools/check-documentation-links.sh[16-37]
## Suggested fix approach
- Avoid piping `find` into `while`. Instead, write the document list to a temp file, check `find`’s exit code explicitly, then read that list in a separate loop.
- Example pattern:
  - `docs_list=$(mktemp)`
  - `find ... -print >"$docs_list"` and `test $? -eq 0` (or `if ! find ...; then ...; fi`)
  - `while IFS= read -r document; do ...; done <"$docs_list"`
- Alternatively (if you are willing to require `bash`), switch shebang to `#!/usr/bin/env bash` and add `set -euo pipefail`, but the temp-file approach keeps `/bin/sh` compatibility.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context used

✅ Compliance rules (platform): 20 rules

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[qodo-code-review]

PR approved by Qodo

All merge criteria satisfied — approved by default policy

[qodo-code-review]

Qodo Fixer

No findings are available for this PR yet. Findings appear here once Qodo has reviewed the PR.

[qodo-code-review]

Code review by qodo was updated up to the latest commit fb3525c

[sri-rang]

Review decision: ignoring finding 1 about non-ASCII typography. The cited ASCII-only rule concerns source-code string literals; the reported characters are intentional prose typography in Markdown documentation and do not affect localization, packaging, or runtime behavior.

[qodo-code-review]

Code review by qodo was updated up to the latest commit 346e11a