[bakirgdev]

An audit of docs/: every claim checked against the code, croc v11.5.4's source, the CI config and GitHub, then rewritten so it stays true and reads plainly. Docs now hold current facts only: no dates, no planning IDs, no history.

Docs

• Facts fixed across every file (about 140 wrong, stale or dangling claims). Examples: views import CrocKit value types, and only CrocEngine is off limits; TransferEvent has .stored; the Advanced options are wired end to end; .xcode-version is 27.1; the nullability warning is fixed, not "expected"; store function signatures; UI labels spelled as the app spells them.
• App Store state made true everywhere: 1.0.0 is a notarized DMG with Sparkle, the App Store builds are in TestFlight, and the first App Store release is 1.1.0. CHANGELOG.md [1.0.0], the landing page, llms.txt and the docs site said otherwise.
• Structure:
  • New docs/README.md indexes every doc, replacing docs/knowledge/README.md.
  • New docs/RELEASING.md takes signing, notarization, Sparkle, App Store uploads and a repeatable release checklist out of BUILDING.md. The one-off setup log is now a "One-time setup" how-to.
  • New docs/knowledge/landing-page.md, plus a test-suite map in BUILDING.md.
• IDs and dates removed: the old requirement, feature, plan and session IDs, in docs and in code comments, scripts and CI. The threat model now names its requirements and weaknesses in words. design/ names the version a fact was checked against instead of a date.
• known-issues.md:
  • Deleted items that were already fixed or are fixed here.
  • The rest are corrected and grouped.
  • "Release" now lists what gates the first App Store submission.
• Duplication cut: each fact has one home, and the other files link to it. Long bullets and table cells are split up.
• CONTRIBUTING.md regains its "Verification" and "Docs" sections, which its contents table linked to. The README's dead #build-from-source anchor is fixed.

Keeping docs true

• docs/AGENTS.md: where each kind of fact goes and how to write it.
• Root AGENTS.md: a "Verification" rule, and a "Docs" map from each area of code to the docs it must keep in step.
• scripts/verify-docs.sh (bash and POSIX awk) checks every tracked markdown file outside the docs site:
  • relative links and their anchors
  • repo paths in inline code (gitignored build outputs count as present, so a fresh clone passes)
  • in docs/ and the AGENTS.md files only: dates, planning IDs and section-number citations
• CI gets a docs checks job that runs on every push and PR: renaming any file can break a path a doc names. It is part of ci pass.

Code

• crocmobile/session.go: a delegate panic in OnCodeReady during a text send no longer leaves the text temp file behind. TestNetworkGlobalsRestoredAfterPanic now asserts it, and it fails without the fix.
• CodeField: the paste button's 38 pt figure was a claim nothing set. SwiftUI lets an app set only a PasteButton's border shape, label style and tint, so its size is the system's. The docs now say that, and measuring it is listed in the open accessibility audit.
• AutoVerify.swift's header lists --transport. crocmobile/osv-scanner.toml names the x/crypto packages croc really imports.

Verification

• scripts/verify-docs.sh: PASS, 48 markdown files, locally and in CI. Its first CI run caught a wrong path in a doc that was still untracked locally, so the script now scans uncommitted docs too. Also passes with CrocKit/Croc.xcframework and .tools/ removed (fresh-clone case).
• scripts/verify-design.sh: OK. shellcheck -x scripts/*.sh: clean. scripts/format-swift.sh --lint: PASS.
• crocmobile/: go build, go vet, go test -race ./... ok, golangci-lint run 0 issues.
• Builds and tests: xcodebuild iOS Simulator build and macOS test, both with warnings as errors (TEST SUCCEEDED); CrocApp Direct build; swift test --package-path CrocKit (35 tests passed).
• scripts/assemble-site.sh: builds, and the docs site fails on any broken link.
• Not run: the transfer harnesses. The only engine change is the cleanup path, which the Go test covers.

AI assistance: substantial