uttrflow / uttrflow/uttrflow-swift
Docs/README.md does not list soak.md or ui-tests.md, and no document links to either
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
`Docs/README.md` indexes 88 of the 90 files in `Docs/`. The two it leaves out, `Docs/soak.md` (how to run `make soak`) and `Docs/ui-tests.md` (how to run `make uitest`), are not linked from any other Markdown file in the repository (`git grep -l 'soak.md\|ui-tests.md' -- '*.md'` finds nothing), so the only way to find them is to list the directory.
`Scripts/docs_audit.sh` checks that links resolve, but not that every document is reachable from the index.
## Why it matters
`make soak` and `make uitest` are in `make help`, and these are the pages that explain what they need (hours of running, a windowing session) before somebody starts one.
## Acceptance criteria
- Both documents are listed in `Docs/README.md` under a fitting heading.
- `Scripts/docs_audit.sh` gains a check that every `Docs/*.md` other than `Docs/README.md` is linked from `Docs/README.md`, and fails naming the file when one is not.
- `make docs-audit` passes; say in the pull request that removing one of the new index lines makes it fail.
## Where to start
- `Docs/README.md`, `Scripts/docs_audit.sh` section 3 (relative links), which already parses links.
- 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
Research direction
Read CONTRIBUTING.md first, then inspect Docs/README.md and section 3 of Scripts/docs_audit.sh, which already parses relative links. Add the two document links and the missing index-coverage check, then run make docs-audit and make verify; done means both files are indexed and removing an index line makes the audit fail naming that file.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, shell
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100