uttrflow / uttrflow/uttrflow-swift

No glossary: AI suggestions is also tab-to-complete, predict, completion and suggestion, and tidying is also clean-up, cleaning and transformer

Open Beginner friendly
#657 0 comments 0 reactions 0 assignees View on GitHub
area:general documentation good first issue P2
Dominant language
Swift
Stars
4
Forks
17
Avg merge
3h 32m
Merged PRs (30d)
277

Description

## What happens

The same two features go by several names depending on where you look, and nothing says they are the same thing.

**AI suggestions:** the Settings tab is "AI suggestions" (`Sources/UttrflowUX/SettingsPresenter.swift:26`); its switch is "Finish what I am typing" (`:363`); modules are `UttrflowPredict`, `UttrflowPredictStore`, `UttrflowPredictCapture`; app code is `Sources/Uttrflow/Suggestion/Suggestion*`; the store protocol is `PredictionStore` and its implementation `PredictStore`; the log category is `predict`; `Docs/README.md:53` heads the section "Tab-to-complete" and the files are `Docs/predict-*.md`; `uttrflow-dev probe` is described as "Measure what tab-to-complete can rely on, before any of it is built" (`Sources/uttrflow-dev/Probe.swift:11`), although it is built. `Docs/README.md` never uses the words "AI suggestions".

**Dictation clean-up:** Settings says "Tidying up" (`SettingsPresenter.swift:265-271`, `SettingsTidyingLevel`) stored as `transformerPreference`; the pipeline state is `tidying`; Diagnostics says "Clean-up steps"; engines are `TextTransformers`, `TransformerRouter` beside `CleanupModel`; the core folder is `UttrflowCore/Cleaning/`; the documents are `Docs/cleanup.md` and `Docs/cleanup-design.md`, and `Docs/core-engine-kinds.md` says "transformer kinds".

## Why it matters

A newcomer who reads an issue about "AI suggestions" cannot find it in `Docs/README.md`, and one who reads "Tidying up" in Settings has to guess that `TransformerRouter` is where to look. Renaming modules is out of proportion; a short map is not.

## Acceptance criteria

- `Docs/README.md` gains a short "Names" section: for each of the two features, the name people read in the app, and the module, folder, type prefix, document prefix and log category that mean the same thing.
- The "Tab-to-complete" heading in `Docs/README.md` also says "AI suggestions".
- The `probe` abstract in `Sources/uttrflow-dev/Probe.swift:11` no longer says "before any of it is built".
- `make docs-audit` passes.

## Where to start

- `Docs/README.md`; `README.md:80` and `:117` already link the feature to its modules and can be copied.
- Read [CONTRIBUTING.md](https://github.com/uttrflow/uttrflow-swift/blob/main/CONTRIBUTING.md) first, and say on this issue that you are taking it.
- Before pushing, run `make verify` (with `DEVELOPER_DIR` pointing at Xcode 26.6 or later). It is the same command CI runs.

**Size:** S, about 1 hour.

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md first, then use Docs/README.md, including its existing links at README.md:80 and :117, as the starting point. Update the documented names and the abstract in Sources/uttrflow-dev/Probe.swift:11, then run make docs-audit and make verify with the required DEVELOPER_DIR; done means all acceptance criteria pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.