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

Open Beginner friendly
#655 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
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.