uttrflow / uttrflow/uttrflow-swift
README's module map and AGENTS.md describe UttrflowCore, UttrflowClipboard and the app's network access as they no longer are
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 4h 27m
- Merged PRs (30d)
- 286
Description
## What happens
- `README.md:256`: "UttrflowCore — Protocols, models, errors, metrics. Pure stdlib — no platform imports." `Sources/UttrflowCore/Support/StoredList.swift` imports `os`, `Sources/UttrflowCore/Support/SingleInstanceLock.swift` imports `Darwin`, and several files in the module import Foundation.
- `README.md:267`: "UttrflowClipboard — Clipboard history and the panel that shows it." The panel is not in this module: its presentation and keyboard logic are `Sources/UttrflowUX/Panel*.swift` and its views `Sources/Uttrflow/Panel/`.
- `AGENTS.md:239-241`: "This app talks to the backend's API and to nothing else on the network — see `UttrflowAccount`, which is deliberately the only module that can reach a server." `Sources/UttrflowSpeech/TokenizerDownload.swift` opens a connection at model install time (its header calls it "the one file in UttrflowSpeech allowed to open a connection"), and the app links Sparkle for updates (`Package.swift:73`). `Docs/offline.md` covers the tokenizer fetch.
## Why it matters
The module map at `README.md:253-285` is the only module overview a newcomer gets, and a wrong line there sends them to the wrong module. The network sentence is the kind a reviewer quotes when judging whether a change may open a socket.
## Acceptance criteria
- The two README lines describe the modules as they are (for `UttrflowCore`, say what it deliberately does not import instead, e.g. no AppKit or SwiftUI, if that holds; check with `git grep -h '^import\|^public import\|^internal import' Sources/UttrflowCore | sort | uniq -c`).
- The AGENTS.md sentence names every place the app opens a connection (sign-in and the backend in `UttrflowAccount`, the tokenizer fetch at model install, the update check), or points to one document that lists them.
- `make docs-audit` passes.
## Where to start
- `README.md` lines 253-285, `AGENTS.md` lines 237-241, `Docs/offline.md`.
- 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:** XS to S, about 1 hour.
Contributor guide
Research direction
Read CONTRIBUTING.md first, then inspect README.md:253-285, AGENTS.md:237-241, Docs/offline.md, the UttrflowCore imports, TokenizerDownload.swift, and Package.swift:73. Use the specified git grep to verify the module description, update the network-access documentation, and run make docs-audit followed by make verify with the required Xcode version; done means both checks pass and the acceptance criteria are accurate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100